词汇构建器（Vocabulary Builder）

该技能读取和写入以下文件（路径相对于 workspace）：

• 词汇追踪器（Vocabulary tracker）：memory/vocabulary.md — 所有单词数据均存放于此
• 音频片段目录（Audio clips directory）：docs/tts-fr/ — 仅读取；用户将发音音频文件放置在此目录中

请确保这些路径存在，或在首次使用前手动创建。

阅读工作流（Reading Workflow）

当用户希望阅读/练习阅读某本书时：

1. 询问用户正在阅读哪本书
2. 检查词汇追踪器中是否已记录该书的单词 —— 读取 ## Active Words 小节末尾部分（可使用 tail 命令，或直接读取最后几条记录），以确定实际最新添加的单词。注意：memory_search 可能返回不完整或排序后的结果，因此在核查最新条目时，也应直接读取文件内容进行验证。
3. 告知用户最后添加的单词及其所在页码，以便其知道从何处继续阅读
4. 询问用户是否希望：① 练习待复习单词，或 ② 继续阅读并添加新单词

添加新单词（Adding New Words）

当用户提供一个新单词时：

1. 首先提供该词的美式英语国际音标（American English IPA）发音（例如：/ˈtrɑːli/）
2. 提供清晰、简洁的释义（Meaning）
3. 提供同义词（Synonyms） —— 用户可能已知的近义表达
4. 除非用户明确表示“不添加”，否则立即写入词汇追踪器
5. 添加完成后，立即展示该单词卡片（word card）

在解释与单词卡片中，始终优先使用IPA，而非临时拼读法（ad-hoc respelling）。若需辅以通俗英文发音提示（plain-English pronunciation hint），仅可在 IPA 之后补充，不可替代 IPA。

若用户表示当前聚焦于发音（pronunciation）训练，请进一步询问其易混淆的具体单词（例如：seem / same / sim）。在发音专注模式下：

• 若用户目标为辨音对比，而非学习三个独立词汇项，则将该组词视为一个单一辨音条目（single comparison entry）
• 在回复及单词卡片中，分别列出每个单词的发音
• 以组合标题形式记录该条目，例如：### seem / same / sim
• 在Meaning 字段中，说明各词发音要点及需注意的音素差异，而非常规词汇释义
• 发音说明应简短、实用、聚焦对比
• 若用户未提供例句，则为每个单词生成极简语境句（very very simple context lines）
• 复用用户提供的共用书籍/页码/上下文信息

所有新增条目均添加至 ## Active Words 小节末尾（位于 --- 分隔符之前，该分隔符用于标记“长期复习”部分）。

单词条目格式（Word Entry Format）

### [word]
- **Type:** noun/verb/adj/adv
- **Learned:** YYYY-MM-DD HH:MM TZ
- **Book:** [source name]
- **Page:** [number]
- **Pronunciation:** /IPA/
- **Meaning:** [explanation]
- **Synonyms:** [similar words]
- **Context:** "[sentence from source]"
- **Practice History:**
  - YYYY-MM-DD HH:MM TZ: Step N ✓/✗ (notes)

发音对比条目格式（Pronunciation Comparison Entry Format）

### [word 1] / [word 2] / [word 3]
- **Type:** pronunciation comparison set
- **Learned:** YYYY-MM-DD HH:MM TZ
- **Book:** [source name]
- **Page:** [number]
- **Pronunciation:**
  - **[word 1]** — /IPA/
  - **[word 2]** — /IPA/
  - **[word 3]** — /IPA/
- **Meaning:** 简明发音指导，说明关键音素差异（例如：`[word 1]` 含 /iː/，`[word 2]` 含 /eɪ/，`[word 3]` 含 /ɪ/）
- **Synonyms:** pronunciation set, minimal comparison set
- **Context:**
  - **[word 1]:** "[very simple sentence]"
  - **[word 2]:** "[very simple sentence]"
  - **[word 3]:** "[very simple sentence]"
- **Practice History:**

法语单词（French Words）

• Context（语境）：仅填写法语句子
• English Translation（英文翻译）：单独字段，填写对应英文译文
• 切勿在同一字段中混合法语与英语
• 用户将音频文件存放在 docs/tts-fr/ 目录下 → 在条目中添加 Audio 字段，并填入对应文件路径

三步学习流程（3-Step Learning Process）

全部三个步骤须在单次对话流中完成（不可跨数小时分散执行）：

• 第一步：显示纯单词 + 复习次数（例如：“已复习 0 次” 或 “已复习 3 次”）→ 提问：“你会读这个单词吗？” → 用户键入该词以确认
• 第二步：提问：“它的意思是什么？” → 判断回答是否正确或足够接近
• 第三步：请用户用该词造一个句子

发音确认采用“信任制”——不依赖语音输入或 ASR 检测，仅通过用户键入单词完成确认。

发音专注型练习（Pronunciation-Focused Practice）

若用户希望开展发音专项训练，而非按常规“释义优先”的词汇学习：

• 先询问其易混淆的单词组合
• 清晰展示每个单词的发音，且始终将 IPA 置于首位
• 简要突出关键音素对比点
• 重点讲解如何发出这些音（如口型、长/短元音、必要时说明舌位或唇形），而非聚焦词典释义
• 若整体辨音训练比单个单词学习更有效，则将该组词统一记录为一个发音对比条目
• 在 Context 字段中使用极简例句，尽可能为每个单词配一行简短句子
• 对于纯粹的发音对比请求，无需强制执行常规“释义优先”的三步流程

间隔重复计划（Spaced Repetition Schedule）

完成全部三个步骤后，按如下时间点安排复习：

• 次日 → 3 天后 → 1 周后 → 2 周后 → 1 个月后 → 3 个月后
• 完成 3 个月后的复习即视为该词已掌握（mastered）

单词进阶路径（Word Progression）

单词在追踪器中依次经历三个阶段：

1. Active Words（活跃学习中） — 当前正在学习的单词
2. Long-Term Review Words（长期复习中） — 已完成全部三步，进入间隔重复流程
3. Mastered Words（已掌握） — 已通过全部复习节点（含 3 个月节点）

测验规则（Quiz Rules）

• 每次测验仅限一个单词 — 不支持快速连测（rapid-fire）
• 禁止刷屏（No spam）：若当日尚未收到上一轮测验的回复，则不得发送新测验
• 每日重置（Reset next day）：新一天开始即可发送测验，即使昨日测验仍未回复
• 夜间静默（Sleep hours）：用户本地时区的 23:00 – 07:00 不发送任何消息
• 优先级顺序（Priority）：待复习单词 > 新增但未完成步骤的单词 > 复习回顾（refresher）

随机单词选取逻辑（Random Word Selection）

1. 统计每个单词的总练习历史条目数（含全部步骤与复习记录）
2. 按复习次数升序排列所有单词（最少复习者优先）
3. 选取复习次数最少的一组单词
4. 在该组内随机选取：统计单词总数（N），使用公式 (current_timestamp_ms % N) + 1 计算选中位置
5. 绝不连续两次选取同一单词。需查阅 Quiz State 中最近一次测验的单词并跳过。

每次测验时必须显示复习次数，例如：“（已复习 0 次）” 或 “（已复习 3 次）”。

按需测验（On-Demand Quizzes）

用户可随时主动发起特定测验，此类请求将覆盖常规优先级与防刷屏规则：

• “Quiz me” → 随机选词
• “Quiz me on [word]” → 指定单词
• “Quiz me on words from [book]” → 从指定书中随机选词
• “Quiz me on words from this week” → 近 7 天内添加的单词中随机选取
• “Quiz me on [book] page [N] to [M]” → 指定页码区间内的单词
• “Give me 3 quizzes” → 连续执行 3 个单词测验

按需复习（On-demand refresher）：若当前无待复习或待处理单词，则从所有已学单词中随机选取一个。仍需记录本次测验日期。

测验状态追踪（Quiz State Tracking）

在追踪器文件顶部维护一个 ## Quiz State 小节：

## Quiz State
- **Pending quiz:** [word] ([review type], [step] sent)
- **Last quiz sent:** YYYY-MM-DD HH:MM TZ

每次测验交互后均需更新该小节内容。

Cron 设置（Cron Setup）

当用户请求配置定时词汇测验时：

1. 需向用户确认：频率（默认每 1 小时一次）、投递渠道 + 目标地址
2. 任务名称（Job name）：vocabulary-quiz-{agentName}（例如：vocabulary-quiz-english）
3. 创建 cron 任务，配置如下：
   • Session：isolated
   • Timeout：120 秒
   • Message：指示 agent 调用 vocabulary-builder 技能执行一次测验
4. 测验约束条件（需包含在 cron message 中）：
   • 检查 Quiz State — 若当日仍有待回复的测验，则跳过本次执行
   • 遵守夜间静默时段：用户本地时区 23:00–07:00 不发送消息

参考资源（References）

• 视频：Why I Stopped Using Flashcards and Started Using AI