@rookiestar/eng-lang-tutor 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -2,57 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.2.4] - 2026-02-27
-
-### Fixed
-- **TTS voice selection**: Audio composer now automatically selects appropriate voices based on TTS provider
-  - Edge-TTS: `en-US-JennyNeural`, `en-US-EricNeural`
-  - XunFei: `catherine`, `henry`
-- **CLI import paths**: Fixed broken imports in `state_manager.py` CLI module
-
-### Changed
-- **npm package**: Removed automatic `pip install` from postinstall script
-  - Added `eng-lang-tutor-setup` CLI tool for manual dependency installation
-  - Supports `--venv`, `--user`, and `--check` options
-- **Test coverage**: Added 38 new tests covering:
-  - `scripts/audio/utils.py` (6 tests)
-  - `scripts/audio/converter.py` (16 tests)
-  - `scripts/utils/helpers.py` (16 tests)
-- **Test fixes**: Fixed pre-existing test failures in CLI and TTS modules
-
-## [1.2.3] - 2026-02-27
-
-### Changed
-- Version bump for npm publishing
-
-## [1.2.0] - 2026-02-27
-
-### Changed
-- Initial npm package setup
-
-## [1.0.1] - 2025-02-27
-
-### Fixed
-- **TTS voice selection**: Audio composer now automatically selects appropriate voices based on TTS provider
-  - Edge-TTS: `en-US-JennyNeural`, `en-US-EricNeural`
-  - XunFei: `catherine`, `henry`
-- **CLI import paths**: Fixed broken imports in `state_manager.py` CLI module
-
-### Changed
-- **npm package**: Removed automatic `pip install` from postinstall script
-  - Added `eng-lang-tutor-setup` CLI tool for manual dependency installation
-  - Supports `--venv`, `--user`, and `--check` options
-- **Test coverage**: Added 38 new tests covering:
-  - `scripts/audio/utils.py` (6 tests)
-  - `scripts/audio/converter.py` (16 tests)
-  - `scripts/utils/helpers.py` (16 tests)
-- **Test fixes**: Fixed pre-existing test failures in CLI and TTS modules
-
-## [1.0.1] - 2025-02-27
-
-### Changed
-- Version bump for npm publishing (1.0.0 was previously unpublished)
-
 ## [1.0.0] - 2025-02-26
 
 Initial release.

package/README.md

@@ -84,6 +84,21 @@ openclaw skills list
 openclaw skills info eng-lang-tutor
 ```
 
+### 卸载
+
+```bash
+# 卸载 npm 包并清除所有数据（包括状态和媒体文件）
+npm uninstall -g @rookiestar/eng-lang-tutor && rm -rf ~/.openclaw/state/eng-lang-tutor ~/.openclaw/media/eng-lang-tutor
+```
+
+**如需保留学习数据，仅卸载软件：**
+
+```bash
+npm uninstall -g @rookiestar/eng-lang-tutor
+```
+
+> 注意：`~/.openclaw/state/eng-lang-tutor/` 存储学习进度、XP、连胜等数据；`~/.openclaw/media/eng-lang-tutor/` 存储生成的音频文件。
+
 **重启 Gateway：**
 
 ```bash
@@ -180,6 +195,59 @@ export XUNFEI_API_SECRET=xxx
 | 快速 | 1.3 | 听力挑战 |
 | 非常快 | 1.7 | 进阶训练 |
 
+## 🛠️ 飞书语音气泡魔改指南
+
+> 通过修改 OpenClaw 飞书插件，可使 `.opus` 音频文件以语音气泡形式展示，提升用户体验。
+
+**文件位置：** `/home/linuxbrew/.linuxbrew/lib/node_modules/openclaw/extensions/feishu/src/media.ts`
+
+### 📍 第一处修改：扩充类型定义 (约第 276 行)
+
+```typescript
+// 【修改前】
+msgType?: "file" | "media";
+
+// 【修改后】
+msgType?: "file" | "media" | "audio";
+```
+
+### 📍 第二处修改：重构路由逻辑 (约第 375 行)
+
+```typescript
+// 【修改前】
+// Feishu requires msg_type "media" for audio/video, "file" for documents
+const isMedia = fileType === "mp4" || fileType === "opus";
+return sendFileFeishu({
+  cfg,
+  to,
+  fileKey,
+  msgType: isMedia ? "media" : "file",
+  replyToMessageId,
+  accountId,
+});
+
+// 【修改后】
+// 精细化路由：mp4 走 media (视频), opus 走 audio (语音气泡), 其余走 file
+let msgType: "file" | "media" | "audio" = "file";
+if (fileType === "mp4") {
+  msgType = "media";
+} else if (fileType === "opus") {
+  msgType = "audio";
+}
+return sendFileFeishu({
+  cfg,
+  to,
+  fileKey,
+  msgType,
+  replyToMessageId,
+  accountId,
+});
+```
+
+**效果：**
+- `.opus` 文件 → 语音气泡形式播放
+- 其他文件 → 普通文件附件形式
+
 ## 命令列表
 
 | 命令 | 别名 | 描述 |

package/examples/sample_quiz_a1.json

@@ -1,6 +1,6 @@
 {
   "_meta": {
-    "prompt_version": "quiz_gen_v1.2"
+    "prompt_version": "quiz_gen_v1.3"
   },
   "quiz_date": "2026-02-25",
   "cefr_level": "A1",
@@ -31,7 +31,7 @@
           "⬜ C. Goodbye",
           "⬜ D. Sorry"
         ],
-        "hint": "💡 Think: what do you say when you get something?",
+        "hint": "💡 What's the polite thing to say?",
         "correct_feedback": "✅ Correct! **'Thank you'** = 谢谢!",
         "wrong_feedback": "❌ Not quite. When someone helps you, say **'Thank you'**!",
         "xp_display": "💎 +10 XP"
@@ -50,7 +50,7 @@
         "type_name": "Chinglish 修正 | Fix the Chinglish",
         "question_formatted": "🔧 What's wrong with this sentence?",
         "sentence_formatted": "📝 \"Thank you very **many** for your help!\"",
-        "hint": "💡 'Many' or 'Much' - which one for degree?",
+        "hint": "💡 Think about which word describes amount or degree",
         "correct_feedback": "✅ Fixed! **'Thank you very much!'** sounds natural! 🎉",
         "wrong_feedback": "❌ Use **'much'** not 'many' here. **'Thank you very much!'**",
         "xp_display": "💎 +15 XP"
@@ -71,7 +71,7 @@
         "question_formatted": "✏️ What do you say?",
         "context_formatted": "🚪 Your friend opens the door for you. You say: '**___**!'",
         "word_bank_formatted": "📦 Options: [ **Thanks** | Hello | Goodbye ]",
-        "hint": "💡 Which one means '谢谢'?",
+        "hint": "💡 Which one is for showing appreciation?",
         "correct_feedback": "✅ Perfect! **'Thanks!'** is casual and friendly! 🎯",
         "wrong_feedback": "❌ The answer was **'Thanks!'** - it means 谢谢!",
         "xp_display": "💎 +12 XP"

package/examples/sample_quiz_a2.json

@@ -1,6 +1,6 @@
 {
   "_meta": {
-    "prompt_version": "quiz_gen_v1.2"
+    "prompt_version": "quiz_gen_v1.3"
   },
   "quiz_date": "2026-02-25",
   "cefr_level": "A2",
@@ -31,7 +31,7 @@
           "⬜ C. When you say goodbye",
           "⬜ D. When you ask for help"
         ],
-        "hint": "💡 'Meet' = first time introduction",
+        "hint": "💡 Think about when you use this phrase in introductions",
         "correct_feedback": "✅ Correct! **'Nice to meet you'** = first time only!",
         "wrong_feedback": "❌ **'Nice to meet you'** is for first-time introductions only!",
         "xp_display": "💎 +10 XP"
@@ -50,7 +50,7 @@
         "type_name": "Chinglish 修正 | Fix the Chinglish",
         "question_formatted": "🔧 Find and fix the error:",
         "sentence_formatted": "📝 \"Hi John! **Nice to see you.** This is our first meeting.\"",
-        "hint": "💡 If it's the FIRST meeting, 'see' or 'meet'?",
+        "hint": "💡 Think about the difference between first-time and repeat meetings",
         "correct_feedback": "✅ Fixed! **'Nice to meet you!'** for first introductions! 🎉",
         "wrong_feedback": "❌ First time = **'Nice to meet you'**, not 'see you'!",
         "xp_display": "💎 +15 XP"
@@ -71,7 +71,7 @@
         "question_formatted": "✏️ Complete the response:",
         "context_formatted": "🎉 Friend: \"This is Sarah.\" You: \"**___!**\"",
         "word_bank_formatted": "📦 Options: [ **Nice to meet you** | Nice to see you | Good to know you ]",
-        "hint": "💡 First introduction = 'meet' or 'see'?",
+        "hint": "💡 Consider the context - is this person new to you?",
         "correct_feedback": "✅ Perfect! **'Nice to meet you!'** is the standard introduction! 🎯",
         "wrong_feedback": "❌ For first introductions, say **'Nice to meet you!'**",
         "xp_display": "💎 +12 XP"

package/examples/sample_quiz_b1.json

@@ -28,6 +28,7 @@
           "⬜ C. They want to cancel the project",
           "⬜ D. They want you to write the report"
         ],
+        "hint": "💡 Think about what kind of conversation this implies",
         "correct_feedback": "✅ Correct! **'Touch base'** = quick check-in ⚡",
         "wrong_feedback": "❌ Not quite. **'Touch base'** means a brief, informal chat!",
         "key_phrase": "**touch base**",
@@ -70,6 +71,7 @@
         "question_formatted": "✏️ Complete the sentence:",
         "context_formatted": "💼 To your manager: \"I wanted to **___** on the project timeline.\"",
         "word_bank_formatted": "📦 Word Bank: [ **touch base** | 'discuss together' ❌ | 'communicate' ❌ ]",
+        "hint": "💡 Which sounds natural for a quick check-in with your manager?",
         "correct_feedback": "✅ Perfect! **'Touch base'** is the way to go! 🎯",
         "wrong_feedback": "❌ 'Discuss together' sounds awkward. Try **'touch base'**!",
         "key_phrase": "**touch base**",

package/examples/sample_quiz_b2.json

@@ -1,6 +1,6 @@
 {
   "_meta": {
-    "prompt_version": "quiz_gen_v1.2"
+    "prompt_version": "quiz_gen_v1.3"
   },
   "quiz_date": "2026-02-25",
   "cefr_level": "B2",
@@ -50,7 +50,7 @@
         "type_name": "Chinglish 修正 | Fix the Chinglish",
         "question_formatted": "🔧 Make this sound more corporate:",
         "sentence_formatted": "📝 \"We need to **discuss this topic again** after the meeting.\"",
-        "hint": "💡 Use a spatial metaphor that implies returning",
+        "hint": "💡 Which sounds most natural in American corporate culture?",
         "correct_feedback": "✅ Much better! **'Let's circle back on this'** sounds professional! 🎉",
         "wrong_feedback": "❌ Try **'Let's circle back on this'** instead of 'discuss again'",
         "xp_display": "💎 +15 XP"
@@ -71,7 +71,7 @@
         "question_formatted": "✏️ Complete the sentence:",
         "context_formatted": "📧 \"I'll **___** on the project updates.\"",
         "word_bank_formatted": "📦 Options: [ **loop you in** | circle back | touch base | reach out ]",
-        "hint": "💡 Include someone = ?",
+        "hint": "💡 Think about the relationship - you're keeping them informed",
         "correct_feedback": "✅ Perfect! **'Loop you in'** means include in communication! 🎯",
         "wrong_feedback": "❌ **'Loop you in'** is for including someone in future communication!",
         "xp_display": "💎 +12 XP"

package/examples/sample_quiz_c1.json

@@ -1,6 +1,6 @@
 {
   "_meta": {
-    "prompt_version": "quiz_gen_v1.2"
+    "prompt_version": "quiz_gen_v1.3"
   },
   "quiz_date": "2026-02-25",
   "cefr_level": "C1",
@@ -71,7 +71,7 @@
         "question_formatted": "✏️ Complete with the right idiom:",
         "context_formatted": "🔄 30 minutes, no progress. \"We're **___** here.\"",
         "word_bank_formatted": "📦 Options: [ **spinning our wheels** | boiling the ocean | touching base | circling back ]",
-        "hint": "💡 Car metaphor = going nowhere",
+        "hint": "💡 Think about which idiom describes lack of progress",
         "correct_feedback": "✅ Perfect! **'Spinning our wheels'** = unproductive! 🎯",
         "wrong_feedback": "❌ **'Spinning our wheels'** describes unproductive discussion!",
         "xp_display": "💎 +12 XP"

package/examples/sample_quiz_c2.json

@@ -1,6 +1,6 @@
 {
   "_meta": {
-    "prompt_version": "quiz_gen_v1.2"
+    "prompt_version": "quiz_gen_v1.3"
   },
   "quiz_date": "2026-02-25",
   "cefr_level": "C2",
@@ -50,7 +50,7 @@
         "type_name": "Chinglish 修正 | Fix the Chinglish",
         "question_formatted": "🔧 Make this sound more C-suite:",
         "sentence_formatted": "📝 \"That's **too ambitious**. We need to **reduce the scope**.\"",
-        "hint": "💡 Use the ocean metaphor and 'phased'",
+        "hint": "💡 What's the C-suite way to say 'too ambitious'?",
         "correct_feedback": "✅ Perfect! **'Boiling the ocean' + 'phased approach'** = executive language! 🎉",
         "wrong_feedback": "❌ Try **'That's boiling the ocean. We need a phased approach.'**",
         "xp_display": "💎 +15 XP"
@@ -81,7 +81,7 @@
           "⬜ C. Let's keep it confidential",
           "⬜ D. We should decide now"
         ],
-        "hint": "💡 Get stakeholder buy-in before deciding = ?",
+        "hint": "💡 What's the corporate process for building consensus?",
         "correct_feedback": "✅ Perfect! **'Socialize this'** = systematic stakeholder buy-in! 🎯",
         "wrong_feedback": "❌ **'Socialize this with stakeholders'** is the C-suite process!",
         "xp_display": "💎 +15 XP"

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@rookiestar/eng-lang-tutor",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "地道美式英语导师 - OpenClaw Skill for learning authentic American English",
   "main": "scripts/cli/cli.py",
-  "bin": {
-    "eng-lang-tutor-setup": "scripts/setup.py"
+  "scripts": {
+    "postinstall": "python3 -m pip install -r requirements.txt --quiet"
   },
   "keywords": [
     "english",

package/scripts/release.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+Release Script - Manages file visibility across local repo, remote repo, and npm package.
+
+This script handles three layers:
+1. Local repo - All tracked files (managed by .gitignore)
+2. Remote repo - Public files only
+3. npm package - Minimal user-facing files
+
+Usage:
+    python3 scripts/release.py --check        # Show file distribution
+    python3 scripts/release.py --sync-remote  # Sync to remote (dry-run)
+    python3 scripts/release.py --npm-pack     # Create npm tarball
+"""
+
+import argparse
+import subprocess
+import json
+from pathlib import Path
+from typing import Set
+
+# Files/directories to EXCLUDE from remote repo (not publicly visible)
+REMOTE_EXCLUDE = {
+    "tests/",
+    "package.json",
+    "package-lock.json",
+    "bin/",
+    "scripts/setup.py",
+    ".gitignore",
+    ".gitattributes",
+    ".npmignore",
+    "*.egg-info/",
+    ".pytest_cache/",
+    "__pycache__/",
+    ".coverage",
+    "htmlcov/",
+    ".tox/",
+    ".nox/",
+    ".claude/",
+    "*.pyc",
+    "*.pyo",
+    "*.tgz",
+}
+
+# Files/directories to EXCLUDE from npm package (in addition to REMOTE_EXCLUDE)
+# npm package should be minimal - only what users need to run
+NPM_EXCLUDE = REMOTE_EXCLUDE | {
+    "CLAUDE.md",           # Development guide for Claude AI
+    "docs/",               # Internal documentation
+    "examples/",           # Sample files (not needed for runtime)
+    "references/",         # Reference materials
+    "*.md",                # All markdown except README.md
+}
+
+# Files that MUST be included in npm package
+NPM_INCLUDE = {
+    "README.md",           # Keep README for npm display
+    "package.json",        # Required for npm
+    "requirements.txt",    # Python dependencies
+    "scripts/",            # All scripts (excluding setup.py)
+    "templates/",          # Prompt templates
+    "SKILL.md",           # Skill documentation
+}
+
+
+def get_tracked_files() -> Set[str]:
+    """Get all files tracked by git."""
+    result = subprocess.run(
+        ["git", "ls-files"],
+        capture_output=True,
+        text=True,
+        cwd=Path(__file__).parent.parent
+    )
+    return set(result.stdout.strip().split("\n"))
+
+
+def should_exclude(path: str, exclude_patterns: Set[str]) -> bool:
+    """Check if a path should be excluded based on patterns."""
+    for pattern in exclude_patterns:
+        if pattern.endswith("/"):
+            if path.startswith(pattern) or "/" + pattern in path:
+                return True
+        elif pattern.startswith("*."):
+            if path.endswith(pattern[1:]):
+                return True
+        else:
+            if path == pattern or path.startswith(pattern + "/"):
+                return True
+    return False
+
+
+def categorize_files():
+    """Categorize files into local, remote, and npm groups."""
+    tracked = get_tracked_files()
+
+    local_only = set()
+    remote_files = set()
+    npm_files = set()
+
+    for file in tracked:
+        # Skip empty strings
+        if not file:
+            continue
+
+        # Check if in remote exclude list
+        if should_exclude(file, REMOTE_EXCLUDE):
+            local_only.add(file)
+        else:
+            remote_files.add(file)
+
+        # Check if should be in npm package
+        if should_exclude(file, NPM_EXCLUDE):
+            # Check if explicitly included
+            included = False
+            for inc_pattern in NPM_INCLUDE:
+                if inc_pattern.endswith("/"):
+                    if file.startswith(inc_pattern):
+                        included = True
+                        break
+                elif file == inc_pattern:
+                    included = True
+                    break
+
+            if included:
+                npm_files.add(file)
+        else:
+            npm_files.add(file)
+
+    return local_only, remote_files, npm_files
+
+
+def show_distribution():
+    """Show file distribution across three layers."""
+    local_only, remote_files, npm_files = categorize_files()
+
+    print("=" * 60)
+    print("FILE DISTRIBUTION ACROSS THREE LAYERS")
+    print("=" * 60)
+
+    print(f"\n📦 LOCAL REPO ONLY ({len(local_only)} files)")
+    print("-" * 40)
+    for f in sorted(local_only):
+        print(f"  {f}")
+
+    print(f"\n🌐 REMOTE REPO (public, {len(remote_files)} files)")
+    print("-" * 40)
+    for f in sorted(remote_files):
+        print(f"  {f}")
+
+    print(f"\n📦 NPM PACKAGE ({len(npm_files)} files)")
+    print("-" * 40)
+    for f in sorted(npm_files):
+        print(f"  {f}")
+
+    print("\n" + "=" * 60)
+    print(f"SUMMARY: Local={len(local_only) + len(remote_files)} | Remote={len(remote_files)} | npm={len(npm_files)}")
+    print("=" * 60)
+
+
+def create_gitattributes():
+    """Create .gitattributes with export-ignore for local-only files."""
+    eng_lang_tutor_dir = Path(__file__).parent.parent
+    gitattributes_path = eng_lang_tutor_dir / ".gitattributes"
+
+    # Patterns to exclude from git archive (remote export)
+    export_ignore_patterns = [
+        "tests/",
+        ".pytest_cache/",
+        "*.pyc",
+        "*.pyo",
+        ".coverage",
+        "htmlcov/",
+        ".tox/",
+        ".nox/",
+        ".claude/",
+        "*.egg-info/",
+        "*.tgz",
+    ]
+
+    content = "# Files to exclude from git archive export\n"
+    content += "# These files are tracked locally but not exported to remote archives\n\n"
+
+    for pattern in export_ignore_patterns:
+        content += f"{pattern} export-ignore\n"
+
+    gitattributes_path.write_text(content)
+    print(f"✓ Created {gitattributes_path}")
+    print("\nNote: This affects 'git archive' only.")
+    print("For selective push to remote, consider using a separate public branch.")
+
+
+def npm_pack():
+    """Create npm tarball with proper file filtering."""
+    eng_lang_tutor_dir = Path(__file__).parent.parent
+
+    # Update package.json files field for npm
+    package_json_path = eng_lang_tutor_dir / "package.json"
+
+    with open(package_json_path) as f:
+        package = json.load(f)
+
+    # Set files field to include only what we want
+    package["files"] = [
+        "scripts/",
+        "templates/",
+        "SKILL.md",
+        "README.md",
+        "requirements.txt",
+    ]
+
+    # Remove tests from npm package
+    if "!tests/**" in package.get("files", []):
+        pass  # Already excluded
+
+    print("npm pack would include:")
+    print(json.dumps(package.get("files", []), indent=2))
+
+    print("\nRun the following to create npm package:")
+    print(f"  cd {eng_lang_tutor_dir} && npm pack")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Manage file visibility across local repo, remote repo, and npm package"
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Show file distribution across three layers"
+    )
+    parser.add_argument(
+        "--create-gitattributes",
+        action="store_true",
+        help="Create .gitattributes with export-ignore rules"
+    )
+    parser.add_argument(
+        "--npm-pack",
+        action="store_true",
+        help="Show npm pack configuration"
+    )
+
+    args = parser.parse_args()
+
+    if args.check:
+        show_distribution()
+    elif args.create_gitattributes:
+        create_gitattributes()
+    elif args.npm_pack:
+        npm_pack()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

package/templates/prompts/quiz_generation.md

@@ -19,18 +19,147 @@ Based on today's knowledge point, generate a 3-question quiz calibrated to user'
 ## KNOWLEDGE POINT
 {keypoint_json}
 
-## CEFR DIFFICULTY CALIBRATION
+## CEFR DIFFICULTY CALIBRATION - 6 LEVELS
 
-| Level | Question Characteristics |
-|-------|-------------------------|
-| A1-A2 | Simple recognition, obvious distractors, direct context matching |
-| B1-B2 | Nuanced usage, subtle distractors, requires understanding context |
-| C1-C2 | Complex scenarios, idiomatic variations, cultural nuance testing |
+### A1 - Beginner 入门级
 
-**For B1-B2 (most users):**
-- Multiple choice: Distractors should be grammatically correct but contextually wrong
-- Chinglish fix: Use subtle errors (preposition, article, word choice) not obvious mistakes
-- Create NEW scenarios that differ from the keypoint examples
+**Multiple Choice:**
+- 4 选项，1 个明显错误（语法/拼写）
+- 其他 3 个语法正确但语义不符
+- 场景简单日常：购物、问路、问候
+
+**Chinglish Fix:**
+- 错误类型：基本语法、词序、明显直译
+- 示例错误："I very like it" → "I really like it"
+- 示例错误："She go to school yesterday" → "She went"
+
+**Fill Blank:**
+- 3 选 1 词库
+- 直接匹配，无需理解语境
+
+---
+
+### A2 - Elementary 初级
+
+**Multiple Choice:**
+- 4 选项全部语法正确
+- 干扰项语义差异明显
+- 场景：日常生活、简单工作
+
+**Chinglish Fix:**
+- 错误类型：常见直译、介词错误
+- 示例错误："I agree your opinion" → "I agree with your opinion"
+- 示例错误："Discuss about this" → "Discuss this"
+
+**Fill Blank:**
+- 3 选 1 词库
+- 需要简单语境理解
+
+---
+
+### B1 - Intermediate 中级
+
+**Multiple Choice:**
+- 4 选项全部语法正确
+- 干扰项在**其他语境**下可用
+- 包含 1 个常见学习者错误作为陷阱
+- 场景：工作沟通、旅行、社交
+
+**Example - B1 MC:**
+Context: "You want to end a phone call politely."
+Options:
+A. "I'll let you go now" ← Correct
+B. "I'll hang up now" ← 太直接
+C. "Let's stop talking" ← 不礼貌
+D. "I'm going now" ← 语境不符
+
+**Chinglish Fix:**
+- 错误类型：介词搭配、冠词、固定搭配
+- 示例错误："Make a decision for" → "Make a decision about"
+
+**Fill Blank:**
+- 3-4 选 1 词库
+- 需要理解表达用法
+
+---
+
+### B2 - Upper-Intermediate 中高级 ⚠️ 常见级别
+
+**Multiple Choice:**
+- 4 选项全部语法正确且听起来自然
+- 干扰项必须是 **plausible in OTHER contexts**
+- 至少 1 个"高级陷阱"：常见学习者错误
+- 场景：商务会议、专业沟通
+
+**Example - B2 MC:**
+Context: "In a team meeting, you want to return to a topic later."
+Options:
+A. "Let's circle back on this" ← Correct
+B. "Let's follow up on this" ← Plausible (different meaning - action vs discussion)
+C. "We should revisit this later" ← Plausible (more formal, less idiomatic)
+D. "Let's discuss this again" ← Trap (grammatically correct but not idiomatic)
+
+**Chinglish Fix:**
+- 错误类型：细微介词错误、语体不当、搭配错误
+- 示例错误："We need to discuss about the project"
+- 示例错误："I am interesting in this topic" (interested)
+
+**Fill Blank:**
+- 4 选 1 词库
+- 需要理解细微语义差别
+
+---
+
+### C1 - Advanced 高级
+
+**Multiple Choice:**
+- 所有选项对非母语者都听起来自然
+- 需要文化知识或习语理解
+- 可包含 1-2 个英式/美式差异陷阱
+- 场景：复杂商务、学术讨论
+
+**Example - C1 MC:**
+Context: "You want to politely decline a request without saying no directly."
+Options:
+A. "That might be challenging to fit in" ← Correct (indirect)
+B. "I'm afraid I can't" ← Too direct
+C. "Let me think about it" ← Implies maybe, not decline
+D. "I'll have to pass on this" ← Correct but more casual
+
+**Chinglish Fix:**
+- 错误类型：文化得体性、语域错误、隐含意义
+- 示例错误："Please kindly check" (过度礼貌)
+- 示例错误：在非正式场合使用过于正式的表达
+
+**Fill Blank / Dialogue Completion:**
+- 4 选 1，需要文化理解
+- 多个答案可能都"可以"，但只有一个"最地道"
+
+---
+
+### C2 - Proficiency 精通级
+
+**Multiple Choice:**
+- 所有选项都符合语法且自然
+- 区别在于**细微语气差异**或**文化隐含意义**
+- 场景：专业演讲、文化敏感话题
+
+**Example - C2 MC:**
+Context: "Giving feedback to a senior colleague on their presentation."
+Options:
+A. "I had a thought on slide 3" ← Correct (hedges, collaborative)
+B. "You should change slide 3" ← Too direct
+C. "Slide 3 could be better" ← Vague
+D. "I think slide 3 is wrong" ← Too confrontational
+
+**Chinglish Fix:**
+- 错误类型：深层文化差异、语用失误
+- 示例错误：不理解美式间接沟通文化
+- 示例错误：在需要 hedge 的情况下过于直接
+
+**Dialogue Completion:**
+- 开放式，需要综合理解
+- 可能没有"唯一正确答案"，而是"最符合语境"
 
 ## QUESTION TYPE REQUIREMENTS (3 questions total)
 1. **multiple_choice** (required): Test expression recognition - 10 XP
@@ -73,6 +202,36 @@ Based on today's knowledge point, generate a 3-question quiz calibrated to user'
    - Hint format: "💡 Think about what Americans say in this situation"
    - FORBIDDEN: "💡 The answer is 'touch base'" or showing the phrase directly
 
+## 💡 HINT DESIGN PRINCIPLES
+
+### Core Rule: Hints guide thinking direction, NEVER reveal answers
+
+**SAFE Hint Patterns** (通用模板，可复用):
+- "💡 Think about the formality level of this situation"
+- "💡 Consider who you're talking to - friend or boss?"
+- "💡 What would sound natural in American English?"
+- "💡 Is this formal or casual context?"
+- "💡 Think about the relationship between the speakers"
+- "💡 Consider the tone - professional or friendly?"
+- "💡 What's appropriate for a workplace setting?"
+
+**FORBIDDEN Hint Patterns**:
+- ❌ "💡 Use a spatial metaphor" (太具体，直接指向特定答案)
+- ❌ "💡 The phrase starts with 't'" (字母提示)
+- ❌ "💡 Include someone = ?" (等同告诉答案)
+- ❌ "💡 'A' or 'B' - which one?" (二选一)
+- ❌ "💡 Think about [specific word/concept from answer]" (指向答案)
+- ❌ 直接用中文翻译作为提示
+
+**Validation Test**:
+如果 hint 只适用于 ONE possible answer，则太具体。
+Good hint 应该对 2-3 个选项都"听起来合理"。
+
+**Bad Hint Example:**
+- Question: "Let's ___ on this later." (Answer: circle back)
+- Bad hint: "💡 Think about a shape" ← 太具体，直接指向 circle
+- Good hint: "💡 What's the idiomatic way to say 'return to a topic'?"
+
 3. **NEVER make distractors obviously wrong**
    - All 4 options should sound plausible
    - For B2+: At least one distractor should be a common learner error
@@ -85,6 +244,28 @@ Based on today's knowledge point, generate a 3-question quiz calibrated to user'
 3. Include encouraging feedback in display fields
 4. Total XP should be around 35-40
 5. **Use NEW contexts** - never copy-paste from keypoint examples
+
+## CONTEXT VARIATION RULES
+
+### Multiple Choice - 场景类型（轮换使用）
+1. **Email**: "You're writing to a client..."
+2. **Meeting**: "In a team meeting..."
+3. **Casual chat**: "Talking to a coworker at lunch..."
+4. **Phone/Video call**: "On a call with your manager..."
+5. **Presentation**: "During your presentation..."
+6. **Networking**: "At a professional event..."
+
+### Chinglish Fix - 错误类型分布（按级别）
+| Level | 主导错误类型 | 占比 |
+|-------|-------------|------|
+| A1-A2 | 基本语法、词序、直译 | 80% |
+| B1-B2 | 介词、冠词、搭配 | 60% |
+| C1-C2 | 语域、文化、语用 | 50% |
+
+### Fill Blank - 语境深度
+- A1-A2: 单句，明确场景
+- B1-B2: 对话语境，需理解关系
+- C1-C2: 复杂语境，可能有多重解读
 ```
 
 ---
@@ -96,7 +277,7 @@ Based on today's knowledge point, generate a 3-question quiz calibrated to user'
 ```json
 {
   "_meta": {
-    "prompt_version": "quiz_gen_v1.2"
+    "prompt_version": "quiz_gen_v1.3"
   },
   "quiz_date": "{today_date}",
   "keypoint_fingerprint": "{fingerprint}",

package/.claude/settings.local.json

@@ -1,22 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(python3 -m pytest:*)",
-      "Bash(pytest:*)",
-      "Bash(find:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git push)",
-      "mcp__brave-search__brave_web_search",
-      "mcp__web-search-prime__webSearchPrime",
-      "mcp__zread__get_repo_structure",
-      "mcp__zread__read_file",
-      "mcp__zread__search_doc",
-      "mcp__web-reader__webReader",
-      "WebSearch",
-      "mcp__fetch__fetch",
-      "Bash(wc:*)",
-      "Bash(python3 -m py_compile:*)"
-    ]
-  }
-}

package/backups/state_backup_20260227_063358.json

@@ -1,47 +0,0 @@
-{
-  "version": 2,
-  "initialized": false,
-  "onboarding_step": 0,
-  "completion_status": {
-    "quiz_completed_date": null,
-    "keypoint_view_history": []
-  },
-  "schedule": {
-    "keypoint_time": "06:45",
-    "quiz_time": "22:45",
-    "timezone": "Asia/Shanghai"
-  },
-  "user": {
-    "xp": 0,
-    "level": 1,
-    "streak": 0,
-    "streak_freeze": 0,
-    "gems": 0,
-    "badges": []
-  },
-  "preferences": {
-    "cefr_level": "B1",
-    "oral_written_ratio": 0.7,
-    "topics": {
-      "movies": 0.2,
-      "news": 0.15,
-      "gaming": 0.15,
-      "sports": 0.1,
-      "workplace": 0.2,
-      "social": 0.1,
-      "daily_life": 0.1
-    },
-    "tutor_style": "humorous",
-    "dedup_days": 14
-  },
-  "progress": {
-    "total_quizzes": 0,
-    "correct_rate": 0.0,
-    "last_study_date": null,
-    "perfect_quizzes": 0,
-    "expressions_learned": 0
-  },
-  "recent_topics": [],
-  "error_notebook": [],
-  "error_archive": []
-}

package/backups/state_backup_20260227_063405.json

@@ -1,47 +0,0 @@
-{
-  "version": 2,
-  "initialized": false,
-  "onboarding_step": 0,
-  "completion_status": {
-    "quiz_completed_date": null,
-    "keypoint_view_history": []
-  },
-  "schedule": {
-    "keypoint_time": "06:45",
-    "quiz_time": "22:45",
-    "timezone": "Asia/Shanghai"
-  },
-  "user": {
-    "xp": 0,
-    "level": 1,
-    "streak": 0,
-    "streak_freeze": 0,
-    "gems": 0,
-    "badges": []
-  },
-  "preferences": {
-    "cefr_level": "B1",
-    "oral_written_ratio": 0.7,
-    "topics": {
-      "movies": 0.2,
-      "news": 0.15,
-      "gaming": 0.15,
-      "sports": 0.1,
-      "workplace": 0.2,
-      "social": 0.1,
-      "daily_life": 0.1
-    },
-    "tutor_style": "humorous",
-    "dedup_days": 14
-  },
-  "progress": {
-    "total_quizzes": 0,
-    "correct_rate": 0.0,
-    "last_study_date": null,
-    "perfect_quizzes": 0,
-    "expressions_learned": 0
-  },
-  "recent_topics": [],
-  "error_notebook": [],
-  "error_archive": []
-}

package/backups/state_backup_20260227_064016.json

@@ -1,47 +0,0 @@
-{
-  "version": 2,
-  "initialized": false,
-  "onboarding_step": 0,
-  "completion_status": {
-    "quiz_completed_date": null,
-    "keypoint_view_history": []
-  },
-  "schedule": {
-    "keypoint_time": "06:45",
-    "quiz_time": "22:45",
-    "timezone": "Asia/Shanghai"
-  },
-  "user": {
-    "xp": 0,
-    "level": 1,
-    "streak": 0,
-    "streak_freeze": 0,
-    "gems": 0,
-    "badges": []
-  },
-  "preferences": {
-    "cefr_level": "B1",
-    "oral_written_ratio": 0.7,
-    "topics": {
-      "movies": 0.2,
-      "news": 0.15,
-      "gaming": 0.15,
-      "sports": 0.1,
-      "workplace": 0.2,
-      "social": 0.1,
-      "daily_life": 0.1
-    },
-    "tutor_style": "humorous",
-    "dedup_days": 14
-  },
-  "progress": {
-    "total_quizzes": 0,
-    "correct_rate": 0.0,
-    "last_study_date": null,
-    "perfect_quizzes": 0,
-    "expressions_learned": 0
-  },
-  "recent_topics": [],
-  "error_notebook": [],
-  "error_archive": []
-}