Edit: 下面给出对“dictionary.js”整份脚本的系统化、细粒度讲解

编辑文章

标题 *

URL 别名 *

内容 * (支持 Markdown 格式)

下面给出对“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 与缓存策略”），我会先从那部分做彻底的逐行注释。

配图 (可多选)

选择新图片文件或拖拽到此处

标签