下面给出对“dictionary.js”整份脚本的系统化、细粒度讲解。由于代码体量极大（上万行级别），真正逐行到每一处分号都会超过消息限制与阅读阈值。为兼顾“逐行/逐段详解”的深度与可读性，我采用“模块→函数→关键行”的方式，从上到下覆盖所有功能面与技术细节，并在关键片段提供贴近逐行的解释与注释。你可以在任何小节后对我说“继续展开 XX 函数/模块”，我会补发更细粒度的逐行注释。

— 说明：本文默认运行环境为 JSBox（iOS），涉及 Objective‑C 桥接（$objc）、系统 UI（$ui）、缓存（$cache）、音频（$audio / AVSpeechSynthesizer）、网络（$http）与小组件（$widget）等 JSBox 专用 API；并使用私有框架 DictionaryUI，这属于 iOS 私有 API，非 App Store 上架场景请谨慎。

目录（快速导航）

• 一、总体概览与运行环境
• 二、启动与基础配置
• 三、常量、全局与工具集
• 四、收藏夹/历史/标签/熟悉度数据层
• 五、AI 历史/导入导出/合并去重
• 六、词典查询与模糊匹配（系统词典 + UITextChecker）
• 七、结果展示页与“更多”菜单（收藏/标签/复制/网页/AI）
• 八、AI 模块（解释/故事/每日一句/文章学习/生成词表）
• 九、Markdown 渲染到 HTML（自实现转换器）
• 十、TTS 与有道发音回退策略
• 十一、练习与学习（拼写→选择、闪卡、自动学习、随机练习）
• 十二、收藏夹视图/筛选/排序/卡片模式
• 十三、历史记录整合页（含 AI 与文章学习）
• 十四、每日一词与小组件缓存策略
• 十五、每日一句（远端 JSON 缓存）与 AI 解读
• 十六、设置页（完整状态持久化）与主题切换
• 十七、文章学习模式（翻译/分析/词汇 三页签）与 iCloud 导入
• 十八、唐诗功能（XML 解析+缓存）与首页展示
• 十九、关键技术亮点汇总
• 二十、潜在风险与改进建议

一、总体概览与运行环境

• 核心定位：这是一个“系统词典增强器 + 学习工具箱”，整合系统内置词典查询、收藏/分组/标签、AI 解释与故事、自动/随机学习、每日一词/每日一句、文章学习模式、TTS 发音和小组件展示等功能。
• 运行环境：JSBox（iOS），大量使用 $ui（界面）、$objc（桥接）、$http（网络）、$cache/$clipboard/$audio 等 API。
• 私有框架：通过 $objc 加载 DictionaryUI.framework，并使用 DUDictionaryManager 私有类直接调用系统词典底层能力（definitionValuesForTerm 等）。
• UI 体系：完全用 $ui 描述式布局、list/matrix/web 组合，统一考虑深浅色主题。

二、启动与基础配置（文件开头）

1. 框架加载

• $objc("NSBundle").$bundleWithPath("/System/Library/PrivateFrameworks/DictionaryUI.framework").$load();
  • 加载 iOS 私有框架 DictionaryUI，后续可使用 DUDictionaryManager 访问词典内容。
• $objc("NSBundle").$bundleWithPath("/System/Library/Frameworks/AVFoundation.framework").$load();
  • 加载 AVFoundation，用于系统 TTS（AVSpeechSynthesizer）发音。

2. 多语言配置（$app.strings）

• 内置 en / zh-Hans 字符串键值，如 MAIN_TITLE、SEARCH、NO_RESULTS、MANAGEMENT 等。
• $l10n 调用时按系统语言自动映射。

3. 常量与全局（SCHEMA_VERSION、缓存键、历史上限）

• SCHEMA_VERSION：数据结构版本（迁移时参考）。
• FAVORITE_LISTS_KEY、HISTORY_WORDS_KEY、SETTINGS_KEY 等：所有本地缓存键统一管理，易维护。
• COMMON_WORDS_EXCLUDE：常见功能词/停用词集合，用于“从句子里抽词”“剪贴板导入过滤”等，避免选中 a、the、is… 之类无学习意义的词。

4. 关键 ObjC 与系统对象

• manager = $objc("DUDictionaryManager").$assetManager()
  • 词典查询入口。后续 getWordDefinition 中用 manager.$__definitionValuesForTerm(term)。
• textChecker = $objc("UITextChecker").$new()
  • iOS 拼写检查/联想，用于模糊匹配 buildFuzzyTerms。
• synthesizer = $objc("AVSpeechSynthesizer").$new()
  • 系统 TTS 朗读，用于 createAndSpeakUtterance/speak。

5. 全局控制变量

• definitions[]：当前搜索结果对应的原生 definition 对象数组（或特殊标记 "GOOGLE_TRANSLATE"）。
• timer：输入框 debounce。
• currentSearchText：当前搜索关键字，用于 google 翻译分支。
• currentFavoriteFilter：收藏夹筛选/排序状态持久化（settings.favoriteFilter）。
• ROLEPROMPT：AI 解释角色提示，供 getWordExplanationAI 复用。

6. 默认设置与持久化（defaultSettings / getSettings / saveSettings）

• 统一收口设置项：语速/音量/音调、pronunciationType（英/美式）、自动学习参数、AI 历史数量、每日单词刷新间隔等。
• getSettings 会“补齐缺省字段”，保证向后兼容（重要的“无痛升级”写法）。

三、工具集与通用函数（摘选关键）

• detectDefaultVoice：按地区（GB/UK/IE 使用 en‑GB 否则 en‑US）。
• trimOneLine：归一空白到单空格后再 trim，适配摘要显示。
• formatTimestampToMinute：统一时间显示。
• isDarkMode：代理 $device.isDarkMode。
• toggleTheme/updateUIColors：主题轮换与控件重绘。
• isSingleWord：严格正则 + 排除停用词，区分“文章”与“单词”入口。
• isArticleContent：基于长度/句数/段落/URL/代码特征计分判断“像不像文章”。

四、收藏夹 / 历史 / 标签 / 熟悉度（数据层）

1. 结构迁移与容错

• migrateItemDefaults(item)
  • 统一清洗对象字段：word/definition/source/timestamp/mastered/tags/schemaVersion。
  • 防御“definition 变成 [object Object]”的历史错误，回退“暂无释义”。

2. 收藏夹多列表（默认收藏夹 + 自定义）

• getFavoriteLists / set / active_list / lists：支持多收藏夹、重命名、移动、导入/导出，兼容老版本 favorite_words_v2。
• setActiveListName：切换当前活跃收藏夹，UI 顶部标题也联动。

3. 字词项操作

• isWordFavorited、saveFavoriteWord、removeFavoriteWord、updateWordMasteryStatus。
• 标签：addTagToWord(word, tag) 用 Set 去重后回写。
• 熟悉度：updateWordFamiliarity / getWordFamiliarity
  • 用标签实现 5 级熟悉度（不认识/认识/一般/熟悉/非常熟悉），方便与其他标签共存。

4. 历史记录

• addToHistory：当前词典详情页打开即记历史；限制最大长度（500）。

五、AI 历史 / 导入导出 / 合并去重

1. 三类 AI 历史

• AI_EXPLANATION_HISTORY_KEY、AI_STORY_HISTORY_KEY、AI_DAILY_SENTENCE_HISTORY_KEY。
• getXXXHistory / saveXXXHistory / addXXXToHistory：统一“去重 + 头部插入 + 截断上限”。

2. 清空/导入/导出

• clearAIHistory(type)：按类型或全部清除。
• 三种导入 _importAIExplanationHistory/_importAIStoryHistory/_importAIDailySentenceHistory：
  • 支持两种文件结构：直接数组或 { data: [...] }；验证必需字段，Map 去重合并。
• 综合导入 _importComprehensiveHistory：
  • 处理 data.aiExplanation / aiStory / aiDailySentence / articleLearning。
• 学习历史 _importLearningHistory：按 content+date 键去重。

技术要点

• 去重键的设计（word+explanation 等）可有效避免重复导入。
• 所有导入均容错提示，失败亦不破坏现有数据。

六、词典查询与模糊匹配

1. getWordDefinition(word)

• 通过 manager.$__definitionValuesForTerm(term) 获取 definition 值对象数组。
• 取第 1 条，读出 elements = def.$definitionElements().rawValue()
  • DCSTextElementKeySenses（数组）→ 拼接前三义项（短释）
  • DCSTextElementKeyPartOfSpeech（词性）
• 失败时回退 “暂无释义”，捕获异常保证稳定。

2. buildFuzzyTerms(text)

• 用 UITextChecker 的 completionsForPartialWordRange / guessesForWordRange 组合“联想 + 猜测”，每种语言尝试，合并去重，限制数目（maxFuzzyTotal）。
• searchText 会把 baseResults + fuzzyTerms 的结果扩并，最多 200 项。

3. buildListCellFromDefinition(defObj)

• 从 elements 提取 senses（逗号拼接），和 pos、term 与“词典名”（getDictionaryName + formatDictionaryName），构造列表显示单元。

技术亮点

• 私有框架 + UITextChecker 双通道：既能给定词查义，也能从“输入片段”做补全/纠错，用户体验接近系统查词框。

七、结果详情页与“更多”菜单

1. showDefinition(definition)

• 特殊分支：definition === "GOOGLE_TRANSLATE" → showGoogleTranslation(currentSearchText)。

• 常规分支：

  • title = definition.$term().rawValue()
  • body = definition.$longDefinition().rawValue()（原生 HTML）
  • elements = definition.$definitionElements().rawValue()，senses 用于 history 与收藏默认释义。
  • 调用 addToHistory(title, senses, dictionaryName)。

• 顶部按钮（navButtons）

  • 星标：跨收藏夹添加/移除（如已在任何列表会提示从所在列表移除；如不在任何列表，列出所有列表供选择）。
  • 扬声器：speak(title)（优先有道音频，回退系统 TTS）。
  • 省略号：菜单（添加到其他列表 / 添加标签 / 复制释义为纯文本 / 网页搜索 / AI 用法详解 / AI 故事会（难度可选 simple/intermediate/advanced））。

• 网页区域（web.html）

  • 内嵌原生词典 HTML（body）前置“在线翻译/词典链接”导航区，叠加 CSS 重着色（兼容深色），并刻意高亮 Headword/Pronunciation/POS/Senses。
  • 这段 CSS 非常长，核心在于“尽量覆盖原生词典 HTML 风格”，使文本在深浅色中依旧可读。

2. 复制释义“纯文本化”

• 将长 HTML：去掉 <style>、br→\n、</p>→\n\n、去标签、特定符号格式化（▸、编号、标题），最后 trim；复制 title + 纯文本释义到剪贴板。

3. showGoogleTranslation(text)

• 如果 text 含中文：调用 callAI 返回 AI 解读，并通过 markdownToHtml 渲染；否则访问 google 翻译 API（translate.googleapis.com）直出译文，附在线链接（Google/DeepL/百度）备用。
• 容错：超时/错误时给出打开网页版按钮。

八、AI 模块（解释/故事/每日一句/文章学习/生成词表）
A. callAI(text, prompt, model, endpoint, timeout)

• 所有 AI 接口的底座：POST JSON 到 apiEndpoint（默认 https://chats.want.biz/ai/explain）。
• 两种请求体：如果传 prompt 则 { text: prompt, model }；否则 { text, model }。
• 统一检查 HTTP 状态/错误/返回的 explanation 字段；空则抛错。

B. 单词解释 getWordExplanationAI(word)

• 高质量系统提示：要求用中文 + Markdown，结构化“基础信息/详细用法/例句/辨析/易错点/词形变化”。
• showAIExplanation(word, explanation)
  • 保存历史、渲染 HTML、顶部按钮：复制、TTS 朗读整段（playYoudaoTTS），查看历史。
  • markdownToHtml 自渲染，附常用在线词典链接（剑桥/韦氏/牛津/柯林斯/朗文等）。

C. 单词故事 getWordStoryAI(word, { level })

• 根据 simple/intermediate/advanced 生成不同长度/词汇/难度的英文故事，并在故事后要求“中文摘要 + 重点单词详解”段落。
• showAIStory：不仅显示，还抽取“故事部分纯英文”（优先 split 到“故事大意”之前），仅朗读正文（speakWithTTSOnly），避免朗读中文/标题。

D. 生成词表 generateWordListAI(theme, { count, difficulty })

• 让 AI 返回“严格单行逗号分隔”的词表；解析为数组；在“AI 主题选择 + 缓存”中被 generateWordListAIWithCache 调用。
• generateWordListAIWithCache
  • 基于 rich themes 集与 lastUsedMap + recentQueue 做“时间衰减 + 近用惩罚”的加权随机 pickThemeWithDecayWeight。
  • AI/网络失败时：落回缓存；若缓存也无则打标“近期失败”，30 分钟内重试前偏向使用旧缓存。
  • 成功产生 100 词，持久化 DAILY_WORD_LIST_CACHE_KEY，同时更新“主题最近使用记录”。

E. 每日一句 AI 解读

• updateDailySentenceView 里“脑图按钮（brain）”→ callAI 解释中英句子含义、词汇点，保存到 AI_DAILY_SENTENCE_HISTORY。

F. 文章学习模式（startLearningMode）

• 并发 Promise.all 调三项：
  • getTranslation：逐句中英对照；
  • getArticleAnalysis：大意/写作手法/结构；
  • getVocabularyAnalysis：5–10 重点词汇详解。
• showLearningAnalysis：三页签（翻译/分析/词汇），可“中文-only/双语”切换；顶部“历史/复制”；翻译区对原文分段美化；分析/词汇用 markdownToHtml 渲染。

技术亮点

• 统一 AI 底座 + 多业务拼装，所有错误/超时/空返回路径明确。
• 主题选择采用“半衰期 + 近用惩罚”的概率模型，避免主题单一。

九、Markdown 渲染（markdownToHtml）

• 自写轻量解析器，支持：
  • 代码块/行内代码（先占位，后还原，避免后续正则污染）
  • 表格（thead/tbody 结构 + 主题色）
  • 标题/粗体/斜体、链接、图片
  • 有序/无序列表、引用块、分隔线
  • 段落拆分 + <br> 处理
• 结合 isDarkMode 动态配色。
• 能够很好渲染 AI 返回的 Markdown 内容。

十、TTS 与发音策略

• speak(text)
  • 先停止当前朗读（synthesizer.$stopSpeakingAtBoundary(0)），稍延迟后首选“有道发音”（playYoudaoPronunciation）；若失败 2 秒回退系统 TTS（createAndSpeakUtterance）。
• createAndSpeakUtterance
  • 按文本语言选择 zh‑CN 或 en‑US / en‑GB；中文语速略降；读 rate/volume/pitch 设置项。
• playYoudaoPronunciation / playYoudaoTTS
  • 调用有道 dictvoice 接口（type=1/2），使用 $audio.play；设置 2 秒超时 fallback。
• speakWithTTSOnly：纯系统 TTS 朗读（用于故事只读正文）。

技术亮点

• 双通道发音：在线（有道）优先 + 本地 TTS 回退，保证“有声必达”。

十一、练习与学习

1. 题型切换（showPracticeView）

• 先出“拼写题”（输入框），正确后自动跳“选择题”（四选一）。
• generateMaskedChallenge：保留前缀/后缀（un-/‑ing 等），隐藏 30% 位置，提升记忆强度。
• generateChoices：相似度打分（首字母/长度差/字符交集）选干扰项。
• 动效：shakeView 错误抖动，正误 toast + taptic。

2. 闪卡学习（startFlashcardStudy）

• 单词卡片可点击翻转（正面显示词 + 词性，背面显示释义）。
• 熟悉度五档按钮（颜色标示），“已掌握/未掌握/跳过”操作。

3. 自动学习（startAutoStudy / startAutoFlashcardStudy）

• 定时切换（autoStudyInterval），可暂停/继续；到达末尾弹窗 + 语音播报完成信息。
• 自动模式支持“朗读释义”选项，先读单词，再延迟读释义。

4. 表扬语（globalPraise）

• 随机十句鼓励，小朋友友好；createAndSpeakUtterance 播放。

十二、收藏夹视图 / 筛选 / 排序 / 卡片模式

• showFavoriteWords

  • 顶部工具：显示释义开关、卡片模式、筛选器、更多菜单（剪贴板导入/搜索/排序/导入/AI 智能导入/导出/清空）、学习入口（自动/手动/随机/自动随机练习）、列表切换（多收藏夹管理）。
  • 列表项：word（已掌握 ✓ 上色）、时间、#标签（最多 3 个）、释义（可按设置显示/隐藏）。
  • 列表 actions：掌握/未掌握切换、标签（勾选/新增）、删除。
  • refreshFavoriteList：按 mastered/tag/q 过滤，sortWordsByCriteria 排序（新→旧/旧→新/字母 A→Z/Z→A）。

• showCardModeView

  • matrix 两列卡片，点击“翻转”切正反面，临时变色再回归。
  • 数据来源完全遵循当前筛选/排序状态，和列表保持一致。

技术亮点

• 所有筛选/排序状态持久化（settings.favoriteFilter），跨会话记忆用户习惯。
• “AI 智能导入”：主题+难度 → 生成词表 → 自动查本地释义 → 一键合并入收藏夹。

十三、历史记录整合页

• showHistoryWords
  • 顶部导入/导出/清空（一次性清空：词典历史 + 三类 AI + 文章学习）。
  • 主列表：最近查词历史（word/时间/source/短释）。
  • 底部“AI 功能”四按钮：AI 解释历史 / AI 故事历史 / 每日一句历史 / 文章学习历史（均可单独导入/导出/清空）。

十四、每日一词与小组件（Widget）

• fetchDailyWordWithCache

  • Widget 环境优先“网络获取”→失败用缓存→再失败返回“网络错误”占位。
  • 主 App 环境：按用户设置的刷新间隔（小时）做缓存失效；若无数据回退本地词库循环词。
  • getRandomWordApiList → generateWordListAIWithCache（AI 生成）→ 不足再用本地词库补全 → 额外保底词列表。
  • getWordDefinitionWithSource：从系统词典取第一义；失败显示“无法获取定义，点此进入词典”。

• 小组件 UI

  • 蓝色单词、绿色词性、黄色释义，来源（AI Generated / Cache / Offline 等）+ 日期，点击可 deeplink 回 JSBox 打开该词。

技术亮点

• Widget 特殊分支，显式网络优先 + 强健的多级回退，避免小组件“空白/崩溃”。

十五、每日一句（远端 JSON 缓存）与 AI 解读

• fetchDailySentence(true/false)

  • 远端 https://wealth.want.biz/pages/dailywords.json，取精简字段（en/cn/source/bg/audio）缓存到 DAILY_SENTENCE_DATA_KEY。
  • DAILY_SENTENCE_KEY 存当前选择句子；LAST_FETCH_TIME_KEY 控制日级刷新。

• updateDailySentenceView

  • 背景图铺底 + 半透明遮罩 → 英文/中文/出处 → 英文音频按钮（$audio）+ 中文朗读按钮（系统 TTS）+ AI 解读按钮（callAI）+ 刷新按钮（随机换句或强更远端）。
  • 刷新成功后，会自动从句子中抽一个“合适的英文词”填入输入框并触发查询（getRandomWordFromSentence + 排除停用词/长度阈值），引导学习。

十六、设置页与主题切换

• showSettings

  • 开关：自动学习、显示熟悉度、自动学习时朗读释义、列表显示释义。
  • 数值：自动学习间隔（秒）、发音类型英/美、rate/volume/pitch、debounceMs、AI 历史最大条数、每日单词刷新间隔。
  • 工具：每日一词缓存查看（含批量“查释义预览”）、清除 AI 生成缓存与故障标记。
  • 每项变更立即 saveSettings 并 refresh list 展示 detail。

• toggleTheme

  • 循环“auto→light→dark”，提示当前模式并 updateUIColors（如魔法棒图标色）。

十七、文章学习模式与 iCloud 导入

• showArticleInput

  • 大输入框 + “开始分析”按钮 + 四个示例（新闻/文学/AI 生成/从 iCloud 导入 txt/html）。
  • importArticleFromiCloud 支持读文本/HTML（stripHtmlTags 清洗标签），兼容常见网页拷贝。

• showLearningAnalysis

  • Tab 三页：翻译（原文+译文）、分析、词汇。
  • “中文-only / 双语”一键切换（仅处理译文显示形式），并不重复存历史（isFromModeSwitch 避免重复存）。

十八、唐诗功能（首页顶部诗词）

• fetchAndCachePoemData
  • 远端 https://wealth.want.biz/pages/poem.xml，解析 <node>…</node>（简单正则分割）抽取 title/auth/type/content/desc。
  • 24 小时缓存 POEM_CACHE_KEY；失败时回退旧缓存。
• updatePoemDisplay
  • 随机一首（getRandomPoem），显示“【标题】作者·体裁\n\n正文（<br />→换行）”。

十九、关键技术亮点汇总

• 私有框架直连系统词典：DUDictionaryManager + definitionElements，呈现级别接近 Apple 自带词典体验。
• UITextChecker 模糊补全：带语言偏好（preferredLanguages），实现“动态联想+纠错”。
• 强健的多级回退与容错：
  • 发音：有道 → 系统 TTS；
  • AI：网络 → 缓存 → 标记失败，30 分钟内偏缓存；
  • 每日数据：网络 → 缓存 → 本地词库保底；
  • 翻译：Google API → 打开网页版。
• Markdown 渲染器：自实现解析，适配深浅色，支持表格/代码块/列表等，服务于 AI 内容的可读性。
• 复杂状态持久化：设置项/收藏夹过滤排序/多历史类型/主题权重记录，跨会话记忆。
• 学习体验设计：
  • 从“拼写”过渡到“选择”，强化回忆；
  • 翻卡学习 + 熟悉度可视化；
  • 自动学习/自动随机练习；
  • 从每日一句“一键抽词”引导学习。
• 大量 UI/交互细节：
  • 复制纯释义文本的清洗流程；
  • 详情页 CSS 强制覆盖原生字典 HTML；
  • 收藏夹管理（新建/重命名/移动/导出导入/多列表合并去重）；
  • 文章学习“中文 only/双语”随时切换且不重复入历史。

二十、潜在风险与改进建议

• 风险
  • 私有框架 DictionaryUI：仅限个人/企业内测与 JSBox 环境使用，系统升级可能变更内部结构键名（如 DCSTextElementKeySenses）。
  • 第三方 API 可用性：有道 dictvoice、Google 翻译、AI 后端（chats.want.biz），需关注超时与限流。
  • 大量内嵌 HTML/CSS：iOS 版本差异可能导致部分样式不生效，需要兼容性测试。
• 性能
  • 长列表查义时可考虑缓存 term→shortDef 映射，减少重复 manager 调用。
  • markdownToHtml 的正则链较长，超大文本时可分段处理或采用更高效解析器。
  • 图片/音频等远端资源可加短期缓存（$cache）与失败回退。
• 安全/隐私
  • 剪贴板自动读取：已适时清空 clipboard，仍建议给显式权限提示。
  • 导入/导出：建议校验 JSON 结构并提示敏感信息。
• 代码结构
  • 当前为“大单文件”，可拆分模块：dataStore（收藏/历史），aiService，ttsService，dictionaryService，views（definition/favorites/settings/history/learning），utils 等。
  • 用 TypeScript/注释 JSDoc 补全类型，减少“definition 变对象”的历史问题复发。
• 新功能建议
  • 收藏词“发音缓存”（本地化），离线也能播音；
  • 统计学习曲线（完成数/掌握数/复习间隔）+ 间隔重复（SM‑2 简化版）；
  • 词根词缀/同义网络联动；
  • iCloud Drive 自动备份与恢复（收藏夹 + 历史）。

关键片段“准逐行”示例（再展开）
你可以告诉我“继续逐行展开某段”，我会针对那一段细化到每条语句：

• 例 1：getWordDefinition、buildFuzzyTerms 的 objc 调用栈与 elements 结构键含义。
• 例 2：showDefinition 内 CSS 规则逐条解释（深色适配、Headword/POS/Sense 着色方案）。
• 例 3：generateWordListAIWithCache 的加权选择算法（半衰期公式与近用惩罚）。
• 例 4：markdownToHtml 每个正则的匹配对象、顺序为何重要、如何避免交叉污染。
• 例 5：startAutoStudy 与 startAutoFlashcardStudy 的计时/暂停/按钮状态切换时序。

如果你希望，我可以按你的偏好“逐行从文件第一行往后解释”，将内容分多次消息发完（预计 10,000 字以上）。请告诉我你更关注的部分（如“词典查询链路”或“AI 与缓存策略”），我会先从那部分做彻底的逐行注释。