Back to Details

english-learner

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

English Learner

英语学习助手

Personal vocabulary learning assistant with persistent storage and mastery tracking.
具备持久化存储和掌握程度追踪功能的个人词汇学习助手。

Keywords (Special Commands)

关键词（特殊命令）

KeywordAction
学习
/ 
review
/ 
quiz
Start interactive learning session
stats
/ 
统计
Show learning statistics
All other input is treated as content to translate/learn (English, Chinese, or mixed).
关键词操作
学习
/ 
review
/ 
quiz
启动交互式学习会话
stats
/ 
统计
查看学习统计数据
所有其他输入均被视为待翻译/学习的内容（英文、中文或混合语言）。

Workflow

工作流程

1. CHECK KEYWORD    → If "学习"/"review"/"quiz" → Learning Mode
2. PARSE INPUT      → Understand user intent (clarify if ambiguous)
3. IDENTIFY CONTENT → Extract word(s)/phrase(s)/sentence(s) into a list
4. IF AMBIGUOUS     → AskUserQuestion to confirm before processing
5. BATCH LOOKUP     → python vocab_manager.py batch_get '["word1", "word2", ...]'
6. AI GENERATES     → For each "not_found" word, AI provides definition/phonetic/examples
7. BATCH SAVE       → python vocab_manager.py batch_save '[{...}, {...}]'
8. LOG QUERY        → python vocab_manager.py log_query <query> <type>
9. RESPOND          → Unified format output
CRITICAL: Step 7 is MANDATORY. Every word/phrase MUST be saved before responding.
1. 检查关键词    → 如果是“学习”/“review”/“quiz” → 进入学习模式
2. 解析输入      → 理解用户意图（若有歧义则澄清）
3. 识别内容      → 将单词/短语/句子提取为列表
4. 若存在歧义     → 向用户发起确认请求后再处理
5. 批量查询     → python vocab_manager.py batch_get '["word1", "word2", ...]'
6. AI生成内容     → 对每个“未找到”的单词，AI提供释义/音标/例句
7. 批量保存       → python vocab_manager.py batch_save '[{...}, {...}]'
8. 记录查询        → python vocab_manager.py log_query <query> <type>
9. 回复用户          → 采用统一格式输出
重要提示： 步骤7为必填项。在回复用户前，必须保存每个单词/短语。

Input Clarification

输入澄清

If input is unclear or contains multiple items:
AskUserQuestion:
- question: "我理解你想查询以下内容，请确认："
- header: "确认"
- options:
  - label: "单词: apple, banana", description: "分别查询这两个单词"
  - label: "短语: break the ice", description: "查询这个短语"
  - label: "全部", description: "查询所有内容"
若输入内容不清晰或包含多个条目：
向用户发起确认请求：
- 问题: "我理解你想查询以下内容，请确认："
- 标题: "确认"
- 选项:
  - 标签: "单词: apple, banana", 描述: "分别查询这两个单词"
  - 标签: "短语: break the ice", 描述: "查询这个短语"
  - 标签: "全部", 描述: "查询所有内容"

Scripts

脚本

All scripts in 
{skill_root}/scripts/
. Data in 
~/.english-learner/
.
bash
undefined
所有脚本位于
{skill_root}/scripts/
目录下。数据存储在
~/.english-learner/
目录下。
bash
undefined

vocab_manager.py - Single operations

vocab_manager.py - 单个操作

python vocab_manager.py get_word <word> python vocab_manager.py save_word <word> <definition> [phonetic] [examples_json] python vocab_manager.py get_phrase "<phrase>" python vocab_manager.py save_phrase "<phrase>" <definition> [phonetic] [examples_json] python vocab_manager.py log_query <query> <type> python vocab_manager.py stats python vocab_manager.py update_mastery <item> <is_word:true/false> correct:true/false
python vocab_manager.py get_word <word> python vocab_manager.py save_word <word> <definition> [phonetic] [examples_json] python vocab_manager.py get_phrase "<phrase>" python vocab_manager.py save_phrase "<phrase>" <definition> [phonetic] [examples_json] python vocab_manager.py log_query <query> <type> python vocab_manager.py stats python vocab_manager.py update_mastery <item> <is_word:true/false> correct:true/false

vocab_manager.py - Batch operations (PREFERRED for multiple words)

vocab_manager.py - 批量操作（多单词时优先使用）

python vocab_manager.py batch_get '["word1", "word2", ...]' python vocab_manager.py batch_save '[{"word": "...", "definition": "...", "phonetic": "...", "examples": [...]}]'
python vocab_manager.py batch_get '["word1", "word2", ...]' python vocab_manager.py batch_save '[{"word": "...", "definition": "...", "phonetic": "...", "examples": [...]}]'

sentence_parser.py

sentence_parser.py

python sentence_parser.py classify <text> python sentence_parser.py parse <sentence> python sentence_parser.py batch_check <words>
python sentence_parser.py classify <text> python sentence_parser.py parse <sentence> python sentence_parser.py batch_check <words>

quiz_manager.py

quiz_manager.py

python quiz_manager.py generate [count] [type] [focus] python quiz_manager.py review [limit] python quiz_manager.py summary
undefined
python quiz_manager.py generate [count] [type] [focus] python quiz_manager.py review [limit] python quiz_manager.py summary
undefined

Unified Response Format

统一回复格式

Word (单词)

单词

Required fields: English, phonetic, definitions (all meanings), examples
📖 **{english}** {phonetic}

**词义 Definitions:**

1. **{pos1}** {chinese1}
   - {example1_en}
   - {example1_cn}

2. **{pos2}** {chinese2}
   - {example2_en}
   - {example2_cn}

**同义词:** {synonyms}
**反义词:** {antonyms}

---
📊 查询次数: {lookup_count} | 掌握度: {mastery}%
Example:
📖 **run** /rʌn/

**词义 Definitions:**

1. **v.** 跑，奔跑
   - I run every morning.
   - 我每天早上跑步。

2. **v.** 运行，运转
   - The program runs smoothly.
   - 程序运行顺畅。

3. **v.** 经营，管理
   - She runs a small business.
   - 她经营一家小公司。

4. **n.** 跑步；一段路程
   - I went for a run.
   - 我去跑了一圈。

**同义词:** sprint, jog, operate
**反义词:** walk, stop

---
📊 查询次数: 5 | 掌握度: 40%
必填字段： 英文、音标、释义（所有含义）、例句
📖 **{english}** {phonetic}

**词义：**

1. **{pos1}** {chinese1}
   - {example1_en}
   - {example1_cn}

2. **{pos2}** {chinese2}
   - {example2_en}
   - {example2_cn}

**同义词：** {synonyms}
**反义词：** {antonyms}

---
📊 查询次数: {lookup_count} | 掌握度: {mastery}%
示例：
📖 **run** /rʌn/

**词义：**

1. **v.** 跑，奔跑
   - I run every morning.
   - 我每天早上跑步。

2. **v.** 运行，运转
   - The program runs smoothly.
   - 程序运行顺畅。

3. **v.** 经营，管理
   - She runs a small business.
   - 她经营一家小公司。

4. **n.** 跑步；一段路程
   - I went for a run.
   - 我去跑了一圈。

**同义词：** sprint, jog, operate
**反义词：** walk, stop

---
📊 查询次数: 5 | 掌握度: 40%

Phrase (短语)

短语

Required fields: English, phonetic, meaning, literal meaning, examples
📖 **{english_phrase}** {phonetic}

**释义:** {chinese_meaning}
**字面意思:** {literal_meaning}

**例句:**
- {example1_en}
  {example1_cn}
- {example2_en}
  {example2_cn}

---
📊 查询次数: {lookup_count} | 掌握度: {mastery}%
Example:
📖 **break the ice** /breɪk ðə aɪs/

**释义:** 打破僵局；打破沉默
**字面意思:** 打破冰块

**例句:**
- He told a joke to break the ice at the meeting.
  他在会上讲了个笑话来打破僵局。
- A good question can help break the ice.
  一个好问题可以帮助打破沉默。

---
📊 查询次数: 2 | 掌握度: 60%
必填字段： 英文、音标、含义、字面意思、例句
📖 **{english_phrase}** {phonetic}

**释义：** {chinese_meaning}
**字面意思：** {literal_meaning}

**例句：**
- {example1_en}
  {example1_cn}
- {example2_en}
  {example2_cn}

---
📊 查询次数: {lookup_count} | 掌握度: {mastery}%
示例：
📖 **break the ice** /breɪk ðə aɪs/

**释义：** 打破僵局；打破沉默
**字面意思：** 打破冰块

**例句：**
- He told a joke to break the ice at the meeting.
  他在会上讲了个笑话来打破僵局。
- A good question can help break the ice.
  一个好问题可以帮助打破沉默。

---
📊 查询次数: 2 | 掌握度: 60%

Sentence (句子)

句子

Required fields: Original, translation, phonetic guide, word/phrase breakdown
📝 **句子分析**

**原文:** {original}
**译文:** {translation}
**朗读:** {phonetic_guide}

---

**词汇拆解:**

{For each key word/phrase, use Word/Phrase format above}
Example:
📝 **句子分析**

**原文:** The early bird catches the worm.
**译文:** 早起的鸟儿有虫吃。（比喻：勤奋的人有收获）
**朗读:** /ðə ˈɜːli bɜːd ˈkætʃɪz ðə wɜːm/

---

**词汇拆解:**

📖 **early** /ˈɜːli/

**词义 Definitions:**
1. **adj.** 早的，提前的
   - I'm an early riser.
   - 我是个早起的人。

---

📖 **catch** /kætʃ/

**词义 Definitions:**
1. **v.** 抓住，捕获
   - The cat caught a mouse.
   - 猫抓住了一只老鼠。
2. **v.** 赶上（车、飞机等）
   - I need to catch the 8am train.
   - 我需要赶上早上8点的火车。

---

📖 **worm** /wɜːm/

**词义 Definitions:**
1. **n.** 虫，蠕虫
   - Birds eat worms.
   - 鸟吃虫子。

---
📊 新增词汇: early, catch, worm
必填字段： 原文、译文、音标指南、单词/短语拆解
📝 **句子分析**

**原文：** {original}
**译文：** {translation}
**朗读：** {phonetic_guide}

---

**词汇拆解：**

{对每个关键词/短语，采用上述单词/短语格式展示}
示例：
📝 **句子分析**

**原文：** The early bird catches the worm.
**译文：** 早起的鸟儿有虫吃。（比喻：勤奋的人有收获）
**朗读：** /ðə ˈɜːli bɜːd ˈkætʃɪz ðə wɜːm/

---

**词汇拆解：**

📖 **early** /ˈɜːli/

**词义：**
1. **adj.** 早的，提前的
   - I'm an early riser.
   - 我是个早起的人。

---

📖 **catch** /kætʃ/

**词义：**
1. **v.** 抓住，捕获
   - The cat caught a mouse.
   - 猫抓住了一只老鼠。
2. **v.** 赶上（车、飞机等）
   - I need to catch the 8am train.
   - 我需要赶上早上8点的火车。

---

📖 **worm** /wɜːm/

**词义：**
1. **n.** 虫，蠕虫
   - Birds eat worms.
   - 鸟吃虫子。

---
📊 新增词汇: early, catch, worm

Learning Mode (学习)

学习模式

When user says 
学习
/ 
review
/ 
quiz
:
1. python quiz_manager.py generate 5 all low_mastery

2. For EACH item:
   
   AskUserQuestion #1:
   - question: "📖 **{word}** 的意思是什么？"
   - header: "Quiz"
   - options:
     - label: "认识", description: "我知道这个词的意思"
     - label: "模糊", description: "有点印象但不确定"
     - label: "不认识", description: "完全不知道"
   
3. Show answer (unified Word/Phrase format)

4. AskUserQuestion #2:
   - question: "掌握程度如何？"
   - header: "Mastery"
   - options:
     - label: "完全掌握", description: "+10 mastery"
     - label: "基本掌握", description: "+5 mastery"
     - label: "需要加强", description: "-5 mastery"

5. python vocab_manager.py update_mastery <item> true <result>

6. Continue or show summary
当用户输入
学习
/ 
review
/ 
quiz
时：
1. python quiz_manager.py generate 5 all low_mastery

2. 对每个条目：
   
   发起确认请求 #1:
   - 问题: "📖 **{word}** 的意思是什么？"
   - 标题: "测验"
   - 选项:
     - 标签: "认识", 描述: "我知道这个词的意思"
     - 标签: "模糊", 描述: "有点印象但不确定"
     - 标签: "不认识", 描述: "完全不知道"
   
3. 展示答案（采用统一的单词/短语格式）

4. 发起确认请求 #2:
   - 问题: "掌握程度如何？"
   - 标题: "掌握度"
   - 选项:
     - 标签: "完全掌握", 描述: "+10 掌握度"
     - 标签: "基本掌握", 描述: "+5 掌握度"
     - 标签: "需要加强", 描述: "-5 掌握度"

5. python vocab_manager.py update_mastery <item> true <result>

6. 继续学习或展示总结

Data Structure

数据结构

~/.english-learner/
├── words/{prefix}.json     # Words grouped by first 2 letters
├── phrases/{first_word}.json
├── history/{date}.json     # Daily query logs
└── memory/
    ├── SOUL.md
    └── USER.md
~/.english-learner/
├── words/{prefix}.json     # 按前两个字母分组的单词
├── phrases/{first_word}.json
├── history/{date}.json     # 每日查询日志
└── memory/
    ├── SOUL.md
    └── USER.md

Word Data Schema

单词数据结构

json
{
  "word": "run",
  "definitions": [
    {"pos": "v.", "meaning": "跑，奔跑", "examples": ["I run every morning."]},
    {"pos": "v.", "meaning": "运行，运转", "examples": ["The program runs."]},
    {"pos": "n.", "meaning": "跑步", "examples": ["I went for a run."]}
  ],
  "phonetic": "/rʌn/",
  "synonyms": ["sprint", "jog"],
  "antonyms": ["walk", "stop"],
  "created_at": "2024-01-15T10:00:00",
  "lookup_count": 5,
  "mastery": 40
}
json
{
  "word": "run",
  "definitions": [
    {"pos": "v.", "meaning": "跑，奔跑", "examples": ["I run every morning."]},
    {"pos": "v.", "meaning": "运行，运转", "examples": ["The program runs."]},
    {"pos": "n.", "meaning": "跑步", "examples": ["I went for a run."]}
  ],
  "phonetic": "/rʌn/",
  "synonyms": ["sprint", "jog"],
  "antonyms": ["walk", "stop"],
  "created_at": "2024-01-15T10:00:00",
  "lookup_count": 5,
  "mastery": 40
}

Stats Response Format

统计数据回复格式

When user says 
stats
/ 
统计
:
📊 **学习统计**

| 类别 | 数量 |
|------|------|
| 总词汇 | {total_words} |
| 总短语 | {total_phrases} |
| 已掌握 (≥80%) | {mastered_words} |
| 学习中 (30-79%) | {learning_words} |
| 新词汇 (<30%) | {new_words} |
| 总查询次数 | {total_lookups} |
当用户输入
stats
/ 
统计
时：
📊 **学习统计**

| 类别 | 数量 |
|------|------|
| 总词汇 | {total_words} |
| 总短语 | {total_phrases} |
| 已掌握 (≥80%) | {mastered_words} |
| 学习中 (30-79%) | {learning_words} |
| 新词汇 (<30%) | {new_words} |
| 总查询次数 | {total_lookups} |

Learning Mode - Empty Vocabulary

学习模式 - 词库为空

If quiz_manager.py returns empty list (no words to review):
📚 **词库为空**

还没有添加任何词汇。试试查询一些单词或句子吧！

**示例:**
- 输入 `apple` 查询单词
- 输入 `break the ice` 查询短语
- 输入一句英文或中文来翻译和学习
如果quiz_manager.py返回空列表（无单词可复习）：
📚 **词库为空**

还没有添加任何词汇。试试查询一些单词或句子吧！

**示例:**
- 输入 `apple` 查询单词
- 输入 `break the ice` 查询短语
- 输入一句英文或中文来翻译和学习

Execution Checklist (AI MUST Follow)

执行检查清单（AI必须遵守）

Before responding to user, verify:
  • All words extracted from input (EN or CN)
  • Batch lookup executed via 
    batch_get
  • New words SAVED via 
    batch_save
    (NOT optional!)
  • Query logged via 
    log_query
  • Response uses unified format
Common Mistake: Only logging query without saving words. FIX: Always run batch_save for new words.
回复用户前，请验证：
  • 已提取输入中的所有单词（英文或中文）
  • 已通过
    batch_get
    执行批量查询
  • 已通过
    batch_save
    保存新单词    （此项为必填！）
  • 已通过
    log_query
    记录查询
  • 回复采用统一格式
常见错误： 仅记录查询但未保存单词。修正方法：对新单词始终执行batch_save操作。