@rookiestar/eng-lang-tutor 1.0.2 → 1.0.4

package/templates/prompts/quiz_generation.md

@@ -0,0 +1,187 @@
+# Quiz Generation Template
+
+> Template for generating daily quizzes based on knowledge points.
+
+**Related Files:**
+- [shared_enums.md](shared_enums.md) - Quiz types, XP values, CEFR levels
+- [output_rules.md](output_rules.md) - JSON output rules, markdown formatting
+
+---
+
+## Quiz Generation Prompt
+
+```markdown
+Based on today's knowledge point, generate a 3-question quiz calibrated to user's CEFR level.
+
+## USER CONTEXT
+- CEFR Level: {cefr_level} (A1=Beginner to C2=Proficient)
+
+## KNOWLEDGE POINT
+{keypoint_json}
+
+## CEFR DIFFICULTY CALIBRATION
+
+| 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 |
+
+**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
+
+## QUESTION TYPE REQUIREMENTS (3 questions total)
+1. **multiple_choice** (required): Test expression recognition - 10 XP
+2. **chinglish_fix** (required): Identify and correct Chinglish - 15 XP
+3. **fill_blank OR dialogue_completion** (random): Pick one randomly - 12 XP
+
+## QUESTION GUIDELINES
+
+### Multiple Choice (10 XP)
+- 4 options (A, B, C, D)
+- Only 1 correct answer
+- **Distractors MUST be plausible** - grammatically correct but semantically wrong
+- Test understanding of meaning or usage in a NEW context (not copied from keypoint)
+- For B2+: Include one distractor that's "almost correct" to test nuance
+
+### Chinglish Fix (15 XP)
+- Show a sentence with Chinglish expressions
+- **Create a NEW sentence** - NOT the example from the keypoint
+- For B2+: Use subtle errors (wrong preposition, article misuse, slight word order)
+- Include explanation in the answer
+
+### Fill in the Blank (12 XP)
+- Use "___" for the blank
+- Provide word bank with 3 options
+- **Create a NEW context/sentence** - NOT copied from keypoint
+- Test the expression in a different situation
+
+### Dialogue Completion (12 XP)
+- Show partial dialogue with NEW context
+- Ask what should come next
+- Test natural conversation flow
+
+## ⛔ CRITICAL PROHIBITIONS ⛔
+
+1. **NEVER copy questions directly from keypoint content**
+   - Create NEW scenarios and contexts
+   - Change the situation while testing the same expression
+
+2. **NEVER reveal the answer in hints or question text**
+   - Hint format: "💡 Think about what Americans say in this situation"
+   - FORBIDDEN: "💡 The answer is 'touch base'" or showing the phrase directly
+
+3. **NEVER make distractors obviously wrong**
+   - All 4 options should sound plausible
+   - For B2+: At least one distractor should be a common learner error
+
+## STRICT RULES
+1. Output ONLY valid JSON - no markdown, no extra text
+2. All questions must relate to today's knowledge point
+3. **Difficulty MUST match CEFR level** - harder for B2+ users
+4. Include encouraging feedback in display fields
+5. Total XP should be around 35-40
+6. **End sentences with proper punctuation** - periods for statements, question marks for questions
+7. **Use NEW contexts** - never copy-paste from keypoint examples
+```
+
+---
+
+## Output Schema
+
+> **CRITICAL:** Display fields must NOT reveal answers before user responds.
+
+```json
+{
+  "quiz_date": "{today_date}",
+  "keypoint_fingerprint": "{fingerprint}",
+  "cefr_level": "{cefr_level}",
+  "questions": [
+    {
+      "id": 1,
+      "type": "multiple_choice",
+      "question": "The question text - MUST be a NEW context, not copied from keypoint",
+      "context": "NEW scenario description",
+      "options": ["A. ...", "B. ...", "C. ...", "D. ..."],
+      "correct_answer": "B",
+      "explanation": "Why this is correct...",
+      "xp_value": 10,
+      "display": {
+        "type_emoji": "🔤",
+        "type_name": "选择题 | Multiple Choice",
+        "question_formatted": "💬 {question}",
+        "context_formatted": "📱 {context}",
+        "options_formatted": ["⬜ A. ...", "⬜ B. ...", "⬜ C. ...", "⬜ D. ..."],
+        "hint": "💡 Think about the context - which fits naturally?",
+        "correct_feedback": "✅ Correct! **{key_phrase}** = {meaning}",
+        "wrong_feedback": "❌ Not quite. The answer was **{correct_answer}**. {explanation}",
+        "xp_display": "💎 +10 XP"
+      }
+    },
+    {
+      "id": 2,
+      "type": "chinglish_fix",
+      "question": "Fix this sentence - MUST be NEW sentence, not from keypoint",
+      "chinglish_sentence": "A NEW sentence with Chinglish error...",
+      "correct_answer": "The corrected version...",
+      "explanation": "Why the original was wrong...",
+      "xp_value": 15,
+      "display": {
+        "type_emoji": "🔧",
+        "type_name": "Chinglish 修正 | Fix the Chinglish",
+        "question_formatted": "🔧 What's wrong with this sentence?",
+        "sentence_formatted": "📝 \"{chinglish_sentence}\"",
+        "hint": "💡 How would an American say this naturally?",
+        "correct_feedback": "✅ Fixed! **{correct_phrase}** sounds much more natural!",
+        "wrong_feedback": "❌ Better: **{correct_sentence}**\n💡 {explanation}",
+        "xp_display": "💎 +15 XP"
+      }
+    },
+    {
+      "id": 3,
+      "type": "fill_blank",
+      "question": "Complete the sentence - MUST be NEW context",
+      "context": "NEW dialogue or situation with ___ blank",
+      "word_bank": ["phrase1", "phrase2", "phrase3"],
+      "correct_answer": "phrase1",
+      "explanation": "...",
+      "xp_value": 12,
+      "display": {
+        "type_emoji": "✏️",
+        "type_name": "填空题 | Fill in the Blank",
+        "question_formatted": "✏️ Fill in the blank:",
+        "context_formatted": "💬 {context_with_blank}",
+        "word_bank_formatted": "📦 Options: [ {opt1} | {opt2} | {opt3} ]",
+        "hint": "💡 Consider the formality and context.",
+        "correct_feedback": "✅ Perfect! **{answer}** fits perfectly here!",
+        "wrong_feedback": "❌ The answer was **{correct_answer}**. {explanation}",
+        "xp_display": "💎 +12 XP"
+      }
+    }
+  ],
+  "total_xp": 37,
+  "passing_score": 70,
+  "display": {
+    "header": "📝 今日测验 | Daily Quiz",
+    "date": "📅 {quiz_date}",
+    "difficulty": "📊 Level: **{cefr_level}**",
+    "topic": "🏷️ Topic: **{topic_name}**",
+    "instructions": "🎯 3道小题，答对2道就过关！3 questions, get 2 right to pass!",
+    "progress_bar": "⬜⬜⬜ 0/3 questions",
+    "xp_summary": "💎 Total XP: {total_xp} | 🏆 Pass: 2/3 correct",
+    "footer": "───────────────────\n💪 Good luck! 加油! 🚀"
+  }
+}
+```
+
+**Note:** Removed `key_phrase_summary` from display - it reveals the answer before quiz starts!
+
+---
+
+## XP Values Summary
+
+> See [shared_enums.md](shared_enums.md#quiz-question-types-题型) for full quiz type definitions.
+
+**Daily Quiz:** 3 questions, ~37 XP, pass with 2/3 correct

package/templates/prompts/responses.md

@@ -0,0 +1,291 @@
+# Response Templates
+
+> Templates for various response scenarios in the eng-lang-tutor skill.
+
+**Related Files:**
+- [shared_enums.md](shared_enums.md) - Level names, badges, quiz types
+- [output_rules.md](output_rules.md) - JSON output rules, markdown formatting
+- [display_guide.md](display_guide.md) - Emoji and formatting guidelines
+
+---
+
+## 1. Already Completed Responses
+
+```json
+{
+  "quiz_already_done": {
+    "display": {
+      "title": "✅ Already Completed!",
+      "message": "You've already finished today's quiz. Great job! 🎉",
+      "stats": "Your score: {score}/{total} | XP earned: {xp}",
+      "next_quiz": "Come back tomorrow at 10:45 PM for a new quiz!",
+      "alternative": "💡 Want to review? Say **errors** to see your wrong answers."
+    }
+  }
+}
+```
+
+---
+
+## 2. Not Available Responses
+
+```json
+{
+  "keypoint_not_found": {
+    "display": {
+      "title": "📅 No Keypoint Found",
+      "message": "No knowledge point exists for {date}.",
+      "hint": "Try **keypoint today** for today's content.",
+      "history": "Or say **keypoint history** to see recent keypoints."
+    }
+  }
+}
+```
+
+---
+
+## 2.5. Quiz Request Flow (CRITICAL)
+
+> **NEVER tell user "will generate later" - ALWAYS generate immediately when user requests quiz.**
+
+```
+When user requests quiz:
+1. Check if quiz already completed today (completion_status.quiz_completed_date == today)
+   → YES: Show "Already completed" message
+   → NO: Continue to step 2
+
+2. Check if keypoint.json exists for today
+   → NO: IMMEDIATELY generate keypoint via LLM (do NOT say "will notify later")
+          Save keypoint with generated=true
+   → YES: Continue to step 3
+
+3. Check if quiz.json exists and quiz.generated == true
+   → NO: IMMEDIATELY generate quiz via LLM based on keypoint
+          Save quiz with generated=true
+   → YES: Load existing quiz
+
+4. Present quiz questions to user in ONE response
+```
+
+**FORBIDDEN responses:**
+- ❌ "今天还没有生成知识点，稍后会为您生成并通知您"
+- ❌ "Quiz will be available later"
+- ❌ "Please wait for the scheduled push"
+
+**REQUIRED behavior:**
+- ✅ Generate keypoint immediately via LLM if missing
+- ✅ Generate quiz immediately via LLM
+- ✅ Present quiz in the same response
+
+---
+
+## 3. Keypoint History Response
+
+**When user says:** `keypoint history`, `知识点 历史`, `昨天`, `yesterday`
+
+**Logic:**
+1. Scan `~/.openclaw/state/eng-lang-tutor/daily/` directory for all `YYYY-MM-DD/keypoint.json` files
+2. Sort by date descending (most recent first)
+3. Extract `display.title` or `topic` from each keypoint
+
+**Empty History Response:**
+```markdown
+📚 **知识点历史记录**
+
+暂无历史记录。从今天开始学习吧！
+
+💡 输入 **keypoint** 或 **知识点** 获取今日内容
+```
+
+**With History Response:**
+```markdown
+📚 **知识点历史记录**
+
+| 日期 | 主题 |
+|------|------|
+| 2026-02-21 | 🏢 Touch Base - 工作沟通 |
+| 2026-02-20 | 🎮 GG - 游戏用语 |
+| 2026-02-19 | 🗣️ Gonna/Wanna - 口语缩写 |
+
+💡 输入 **keypoint 日期** 查看详情，如 `keypoint 2026-02-20`
+```
+
+---
+
+## 4. Keypoint Display Template
+
+> IMPORTANT: Use `**text**` for bold. Never use `~~strikethrough~~`. Output Markdown text directly, NOT JSON.
+
+**Assembly Flow:**
+
+```markdown
+{title}
+
+| 主题 | **{topic_name}** |
+|------|------------------|
+| 正式度 | **{formality}** |
+
+───────────────────
+{scene_intro}
+
+{scene_text}
+
+───────────────────
+{expressions_title}
+
+{for each item in expressions_formatted:
+  {emoji} {phrase}
+  {pronunciation}
+  {usage}
+}
+
+───────────────────
+{alternatives_title}
+
+{alternatives_formatted}
+
+───────────────────
+{chinglish_title}
+
+{chinglish_formatted}
+
+───────────────────
+{examples_title}
+
+{for each item in examples_formatted:
+  {situation_emoji} {situation}
+  {dialogue}
+}
+
+───────────────────
+{extended_title}
+
+{extended_formatted}
+
+───────────────────
+{references_title}
+
+{references_formatted}
+
+───────────────────
+{footer}
+```
+
+---
+
+## 5. Stats Display Template
+
+```markdown
+📊 **Your Learning Progress**
+
+• 等级: **{level}** ({level_name})
+• XP: **{current_xp}** / {next_level_xp} (**{progress}%**)
+• 连胜: **{streak}** 天 (倍数: **{multiplier}x**)
+• 正确率: **{correct_rate}%**
+• 徽章: **{badges_count}**/6
+• 宝石: **{gems}**
+
+───────────────────
+Keep it up! 💪
+```
+
+> See [shared_enums.md](shared_enums.md#activity-levels-活跃等级) for level names.
+
+**Multiplier Calculation:** `1.0 + (streak * 0.05)`, max 2.0x
+
+---
+
+## 6. Config Display Template
+
+```markdown
+⚙️ **Your Settings**
+
+• CEFR 等级: **{cefr_level}**
+• 主题偏好: **{topics_list}**
+• 导师风格: **{tutor_style}**
+• 口语占比: **{oral_ratio}%**
+• 知识点推送: **{keypoint_time}**
+• Quiz 推送: **{quiz_time}**
+
+───────────────────
+💡 Say **set level B2** to change your level
+```
+
+---
+
+## 7. Errors Display Template (Paginated)
+
+```markdown
+📓 **Error Notebook**
+
+📊 统计: **{total}** 条错题 (未复习: **{unreviewed}**)
+
+❌ 最近 **5** 条:
+
+**{date_1}**
+Q: {question_1}
+Your answer: {user_answer_1}
+✅ Correct: **{correct_answer_1}**
+
+**{date_2}**
+Q: {question_2}
+Your answer: {user_answer_2}
+✅ Correct: **{correct_answer_2}**
+
+[显示 5 条，第 1/{total_pages} 页]
+
+───────────────────
+📄 输入 **"错题本 更多"** 查看下5条
+📄 输入 **"错题本 2026-02"** 查看特定月份
+📄 输入 **"错题本 随机5"** 随机复习5条
+📄 输入 **"错题本 统计"** 查看完整统计
+📄 输入 **"错题本 复习"** 开始错题复习
+```
+
+**Pagination Commands:**
+- `errors` / `错题本` → Show recent 5 errors
+- `errors more` / `错题本 更多` → Next 5 errors
+- `errors page N` → Go to page N
+- `errors 2026-02` → Filter by month
+- `errors random 5` → Random 5 for review
+- `errors stats` → Show statistics only
+- `errors review` → Start interactive review
+
+---
+
+## 8. Quiz Result Display Template
+
+```markdown
+📊 **Quiz Results**
+
+• 分数: **{correct}/{total}** (**{accuracy}%**)
+• 状态: {status_emoji} {status_text}
+• XP 获得: **+{total_xp} XP**
+• 连胜: **{old_streak}** → **{new_streak}** 天
+• 总 XP: **{total_xp_earned}**
+
+💎 XP 明细:
+  • Base: **{base_xp} XP**
+  • Streak Bonus: **{multiplier}x** ({streak} day streak)
+  {perfect_bonus}
+
+───────────────────
+📝 Come back tomorrow for a new quiz!
+```
+
+**Variables:**
+- `{status_emoji}`: ✅ for passed, ❌ for failed
+- `{status_text}`: "Passed! Great job! 🎉" or "Keep trying! 💪"
+- `{perfect_bonus}`: "• Perfect Bonus: **+20 XP**" (only if 100% correct)
+
+---
+
+## 9. Output Format Rules
+
+> See [output_rules.md](output_rules.md) for complete formatting rules.
+
+**Quick Reference:**
+- **Bold syntax**: Use `**text**` for bold
+- **Never use** `~~strikethrough~~` - use ❌ emoji instead
+- **Emojis**: Include at the start of each section
+- **Punctuation**: End sentences properly (`.` or `?` or `!`)

package/templates/prompts/shared_enums.md

@@ -0,0 +1,97 @@
+# 共享枚举定义
+
+> 本文件定义所有 prompt 模板共用的枚举值。其他模板应引用此文件而非重复定义。
+
+---
+
+## Topics 主题
+
+| ID | 中文名 | Emoji | 描述 |
+|----|--------|-------|------|
+| movies | 电影 | 🎬 | 电影、美剧相关表达 |
+| news | 新闻 | 📰 | 新闻报道、时事评论 |
+| gaming | 游戏 | 🎮 | 电子游戏、在线游戏 |
+| sports | 体育 | ⚽ | 体育运动、比赛 |
+| workplace | 职场 | 💼 | 工作、商务、职业 |
+| social | 社交 | 🍻 | 朋友聚会、社交活动 |
+| daily_life | 生活 | 🏠 | 日常生活、购物、出行 |
+
+---
+
+## CEFR Levels 能力等级
+
+| Level | 中文名 | 描述 | Quiz 特点 |
+|-------|--------|------|-----------|
+| A1 | 入门 | 基础词汇和简单句 | 简单识别，明显干扰项 |
+| A2 | 初级 | 日常表达和基础对话 | 直接上下文匹配 |
+| B1 | 中级 | 熟悉话题的连贯表达 | 细微用法区别 |
+| B2 | 中高级 | 复杂话题的深入讨论 | 隐含干扰项，需理解上下文 |
+| C1 | 高级 | 流利自然的表达 | 复杂场景，习语变体 |
+| C2 | 精通 | 接近母语水平 | 文化细微差别测试 |
+
+---
+
+## Tutor Styles 导师风格
+
+| Style | 中文名 | 语气特点 | 示例 |
+|-------|--------|----------|------|
+| humorous | 幽默 | 轻松愉快，带梗和调侃 | "这个表达老外听了会笑死" |
+| rigorous | 严谨 | 专业分析，深入讲解 | "从语法角度分析..." |
+| casual | 随意 | 自然口语，朋友间聊天 | "平时老美就这么说" |
+| professional | 专业 | 正式商务，职场场景 | "在商务邮件中建议使用..." |
+
+---
+
+## Quiz Question Types 题型
+
+| Type | 中文名 | XP | 描述 | 每日数量 |
+|------|--------|-----|------|----------|
+| multiple_choice | 选择题 | 10 | 四选一，测试表达识别 | 1 (必选) |
+| chinglish_fix | Chinglish修正 | 15 | 识别并修正中式英语 | 1 (必选) |
+| fill_blank | 填空题 | 12 | 完成对话中的空白 | 0-1 (随机) |
+| dialogue_completion | 对话补全 | 15 | 选择合适的对话回应 | 0-1 (随机) |
+
+**每日 Quiz 结构:** 3 题，约 37 XP，答对 2 题即过关
+
+---
+
+## Category Types 类别
+
+| Category | 中文名 | 描述 |
+|----------|--------|------|
+| oral | 口语 | 日常口语表达，非正式场合 |
+| written | 书面 | 正式书面表达，商务邮件、报告 |
+
+---
+
+## Formality Levels 正式程度
+
+| Level | 中文名 | Emoji | 场景示例 |
+|-------|--------|-------|----------|
+| casual | 随意 | 👕 | 朋友聊天、社交媒体 |
+| neutral | 中性 | 👔 | 同事交流、日常沟通 |
+| formal | 正式 | 🤵 | 商务会议、正式邮件 |
+
+---
+
+## Badge Types 徽章
+
+| Badge ID | 中文名 | 触发条件 | 宝石奖励 |
+|----------|--------|----------|----------|
+| first_steps | 初次尝试 | 完成首次 Quiz | 10 |
+| week_warrior | 周末战士 | 7天连胜 | 25 |
+| month_master | 月度大师 | 30天连胜 | 100 |
+| perfect_10 | 完美十连 | 10次满分 Quiz | 50 |
+| vocab_hunter | 词汇猎人 | 学习100个表达 | 75 |
+| error_slayer | 错题克星 | 清除30个错题 | 30 |
+
+---
+
+## Activity Levels 活跃等级
+
+| Stage | 中文名 | Level | XP 范围 |
+|-------|--------|-------|---------|
+| Starter | 启程者 | 1-5 | 0-350 |
+| Traveler | 行路人 | 6-10 | 550-2000 |
+| Explorer | 探索者 | 11-15 | 2600-6000 |
+| Pioneer | 开拓者 | 16-20 | 7200-15000 |

package/templates/state_schema.json

@@ -155,13 +155,8 @@
     },
     "progress": {
       "type": "object",
-      "required": ["total_points", "total_quizzes", "correct_rate", "last_study_date"],
+      "required": ["total_quizzes", "correct_rate", "last_study_date"],
       "properties": {
-        "total_points": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Total points earned"
-        },
         "total_quizzes": {
           "type": "integer",
           "minimum": 0,