@rookiestar/eng-lang-tutor 1.0.1

package/templates/prompts/output_rules.md

@@ -0,0 +1,106 @@
+# 输出规则
+
+> 本文件定义所有 LLM 输出的通用规则。生成内容时必须遵守这些规则。
+
+---
+
+## JSON 输出要求
+
+### 基本规则
+- ⛔ **只输出合法 JSON** - 无 markdown 代码块，无 ```json 标记
+- ⛔ **无多余文本** - 不要在 JSON 前后添加说明文字
+- ⛔ **无注释** - JSON 中不允许 `//` 或 `/* */` 注释
+- ✅ **必须通过 Schema 验证** - 符合 `templates/` 目录下的 JSON Schema
+
+### JSON 转义规则 (用于 bash 命令)
+```bash
+# 单引号包裹
+python3 -m scripts.cli.cli save_daily --content-type keypoint --content '{"key": "value"}'
+
+# 转义内部单引号: ' → '\''
+python3 -m scripts.cli.cli save_daily --content-type keypoint --content '{"title": "It'\''s a test"}'
+```
+
+---
+
+## Markdown 格式规则
+
+### 平台兼容性
+
+| 格式 | 语法 | 飞书 | Discord | Telegram | Slack |
+|------|------|------|---------|----------|-------|
+| 粗体 | `**text**` | ✅ | ✅ | ✅ | ✅ |
+| 斜体 | `*text*` | ✅ | ✅ | ✅ | ✅ |
+| 链接 | `[text](url)` | ✅ | ✅ | ✅ | ✅ |
+| 代码 | `` `code` `` | ✅ | ✅ | ✅ | ✅ |
+| 删除线 | `~~text~~` | ❌ | ✅ | ✅ | ✅ |
+
+### 飞书兼容性特别说明
+- **删除线**: 飞书不支持 `~~text~~` 语法
+- **替代方案**: 直接使用「错误：xxx」而非删除线
+
+---
+
+## 标点符号规则
+
+| 规则 | 正确示例 | 错误示例 |
+|------|----------|----------|
+| 陈述句以句号结尾 | `This is correct.` | `This is correct` |
+| 问句以问号结尾 | `How are you?` | `How are you` |
+| 避免连续标点 | `Great!` | `Great!!!` |
+| 中英文标点不混用 | `Hello, 你好。` | `Hello，你好.` |
+
+---
+
+## 双语标签格式
+
+### 标准格式
+```
+中文 | English
+```
+
+### 示例
+```
+选择题 | Multiple Choice
+填空题 | Fill in the Blank
+Chinglish 修正 | Fix the Chinglish
+```
+
+---
+
+## Display 对象通用字段
+
+所有 `display` 对象应包含以下通用格式字段：
+
+| 字段 | 描述 | 示例 |
+|------|------|------|
+| `type_emoji` | 类型图标 | `🔤` |
+| `type_name` | 类型名称（双语） | `选择题 \| Multiple Choice` |
+| `hint` | 提示（不泄露答案） | `💡 考虑上下文...` |
+| `correct_feedback` | 正确反馈 | `✅ 正确！` |
+| `wrong_feedback` | 错误反馈 | `❌ 再想想...` |
+| `xp_display` | XP 显示 | `💎 +10 XP` |
+
+---
+
+## Emoji 使用规则
+
+### 通用原则
+- ✅ 使用表情符号增加视觉效果
+- ✅ 每个主要部分使用 emoji 作为视觉分隔
+- ⛔ 不要过度使用，保持简洁
+- ⛔ 不要在 JSON 字段名中使用 emoji
+
+### 常用 Emoji 参考
+- 📝 文档/测验
+- 💬 对话/聊天
+- 💎 XP/奖励
+- ✅ 正确/完成
+- ❌ 错误
+- 💡 提示
+- 🎯 目标/要点
+- 📅 日期
+- 🏆 成就/徽章
+- ⛔ 禁止/警告
+
+详细 Emoji 映射请参考 [display_guide.md](display_guide.md)。

package/templates/prompts/quiz_generation.md

@@ -0,0 +1,190 @@
+# 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
+> **See [output_rules.md](output_rules.md) for complete JSON/Markdown formatting rules.**
+
+1. All questions must relate to today's knowledge point
+2. **Difficulty MUST match CEFR level** - harder for B2+ users
+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
+```
+
+---
+
+## Output Schema
+
+> **CRITICAL:** Display fields must NOT reveal answers before user responds.
+
+```json
+{
+  "_meta": {
+    "prompt_version": "quiz_gen_v1.2"
+  },
+  "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,339 @@
+# 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
+
+### Error Review Session Flow
+
+When user starts `errors review`:
+
+**1. Load Errors**
+- Fetch unreviewed errors from `error_notebook` (max 5 at a time)
+- Skip already reviewed errors (`reviewed: true`)
+
+**2. Present Question**
+```markdown
+🔄 **Error Review** ({current}/{total})
+
+❌ 原题: {question}
+📝 你的答案: {user_answer}
+✅ 正确答案: **{correct_answer}**
+
+💡 {explanation}
+
+───────────────────
+回答回忆: 你选择了 **{user_answer}**
+现在你还记得为什么吗？输入 **记得** 或 **忘了**
+```
+
+**3. User Response**
+- If "记得" / "remember": Mark as reviewed, +5 XP
+- If "忘了" / "forgot": Keep in notebook, show explanation again
+
+**4. State Update**
+- Update `error_notebook[].reviewed` to `true` for remembered items
+- Increment `reviewed_count` for badge tracking
+- Log event: `error_reviewed`
+
+**5. Completion**
+```markdown
+🎉 **Review Complete!**
+
+📊 本次复习: **{reviewed}** 题
+💎 获得: **+{xp} XP**
+
+{if all reviewed:}
+✨ 恭喜！错题本已清空！获得徽章: **Error Slayer** (清除30个错题)
+{else:}
+📓 还剩 **{remaining}** 条错题待复习
+
+───────────────────
+💪 继续加油！输入 **errors 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 `!`)