@rookiestar/eng-lang-tutor 1.0.1

package/templates/prompts/initialization.md

@@ -0,0 +1,350 @@
+# Initialization Flow Templates
+
+> Templates for the 7-step onboarding process when a new user starts.
+
+**Related Files:**
+- [shared_enums.md](shared_enums.md) - CEFR levels, topics, tutor styles
+
+**IMPORTANT Display Rules:**
+- Every step MUST display ALL options with numbers (1, 2, 3...)
+- Every step MUST show the recommended/default option clearly
+- Model MUST NOT skip any options or abbreviate the list
+- User can reply with number or text (both should work)
+
+---
+
+## Step 0: Welcome Message
+
+```json
+{
+  "type": "init_welcome",
+  "step": 0,
+  "display": {
+    "title": "👋 Welcome to American English Tutor!",
+    "message": "Hi! I'm your personal English tutor. I'll help you learn authentic American expressions that native speakers actually use.\n\nLet me ask you a few questions to personalize your learning experience.",
+    "prompt": "Ready to get started? Reply with **start** or **开始** to begin.",
+    "footer": "───────────────────\n🎯 This takes about 2 minutes"
+  }
+}
+```
+
+---
+
+## Step 1: CEFR Level Selection
+
+```json
+{
+  "type": "init_cefr",
+  "step": 1,
+  "display": {
+    "title": "📊 Step 1/7: Your English Level",
+    "message": "What's your current English level?",
+    "options": [
+      "**1.** A1-A2 - Beginner: Basic conversations, everyday words",
+      "**2.** B1-B2 - Intermediate: Work conversations, some idioms ⭐ Recommended",
+      "**3.** C1-C2 - Advanced: Complex topics, nuanced expressions"
+    ],
+    "default": "B1",
+    "prompt": "Reply with a number (1-3) or level (e.g., **2** or **B1**)",
+    "hint": "💡 Not sure? Most working professionals are B1-B2. You can change this later."
+  }
+}
+```
+
+**Input Mapping:**
+| User Input | Value |
+|------------|-------|
+| 1, A1, A2, beginner | A2 |
+| 2, B1, B2, intermediate | B1 |
+| 3, C1, C2, advanced | C1 |
+
+---
+
+## Step 2: Topic Preferences
+
+```json
+{
+  "type": "init_topics",
+  "step": 2,
+  "display": {
+    "title": "🎯 Step 2/7: Your Interests",
+    "message": "Which topics interest you most? (Select multiple)",
+    "options": [
+      "**1.** 🎬 movies - TV shows, films",
+      "**2.** 📰 news - Current events",
+      "**3.** 🎮 gaming - Video games",
+      "**4.** ⚽ sports - Sports & fitness",
+      "**5.** 🏢 workplace - Office & business ⭐ Popular",
+      "**6.** 💬 social - Friends & parties",
+      "**7.** 🏠 daily_life - Shopping, restaurants"
+    ],
+    "default": "workplace, social, daily_life",
+    "prompt": "Reply with numbers (e.g., **1 5 6** or **movies workplace social**)",
+    "hint": "💡 Select 2-4 topics. Popular combo: 5 6 7 (workplace + social + daily_life)"
+  }
+}
+```
+
+**Input Mapping:**
+| User Input | Value |
+|------------|-------|
+| 1, movies | movies |
+| 2, news | news |
+| 3, gaming | gaming |
+| 4, sports | sports |
+| 5, workplace | workplace |
+| 6, social | social |
+| 7, daily, daily_life | daily_life |
+
+---
+
+## Step 3: Tutor Style
+
+```json
+{
+  "type": "init_style",
+  "step": 3,
+  "display": {
+    "title": "🎭 Step 3/7: Tutor Style",
+    "message": "How should I teach you?",
+    "options": [
+      "**1.** 😄 humorous - Fun examples, jokes, pop culture ⭐ Recommended",
+      "**2.** 📚 rigorous - Detailed explanations, grammar focus",
+      "**3.** 😎 casual - Short & sweet, everyday language",
+      "**4.** 👔 professional - Business-focused, formal contexts"
+    ],
+    "default": "humorous",
+    "prompt": "Reply with a number (1-4) or style name (e.g., **1** or **humorous**)"
+  }
+}
+```
+
+**Input Mapping:**
+| User Input | Value |
+|------------|-------|
+| 1, humorous, funny | humorous |
+| 2, rigorous, serious | rigorous |
+| 3, casual, relaxed | casual |
+| 4, professional, formal | professional |
+
+---
+
+## Step 4: Oral/Written Ratio
+
+```json
+{
+  "type": "init_ratio",
+  "step": 4,
+  "display": {
+    "title": "💬 Step 4/7: Speaking vs Writing",
+    "message": "What do you want to focus on?",
+    "options": [
+      "**1.** 🗣️ Mostly speaking (80%) - Daily conversations, casual chat",
+      "**2.** ⚖️ Balanced (50%) - Mix of speaking and writing",
+      "**3.** ✍️ Mostly writing (20%) - Emails, formal documents"
+    ],
+    "default": "70",
+    "prompt": "Reply with a number (1-3) or percentage 0-100 (e.g., **1** or **70**)",
+    "hint": "💡 Recommended: 70% speaking (most learners want to speak better)"
+  }
+}
+```
+
+**Input Mapping:**
+| User Input | Value |
+|------------|-------|
+| 1, mostly speaking | 80 |
+| 2, balanced | 50 |
+| 3, mostly writing | 20 |
+| 0-100 (number) | that number |
+
+---
+
+## Step 5: Schedule Configuration
+
+```json
+{
+  "type": "init_schedule",
+  "step": 5,
+  "display": {
+    "title": "⏰ Step 5/7: Schedule Your Learning",
+    "message": "When should I send you daily content?",
+    "options": [
+      "**1.** Morning person: Keypoint 06:45, Quiz 22:45 ⭐ Recommended",
+      "**2.** Late riser: Keypoint 08:00, Quiz 23:00",
+      "**3.** Custom times (you specify)"
+    ],
+    "defaults": {
+      "keypoint": "06:45",
+      "quiz": "22:45"
+    },
+    "prompt": "Reply with a number (1-3) or custom times (e.g., **1** or **07:00 21:30**)",
+    "hint": "💡 Quiz time must be later than keypoint time. Press Enter for defaults."
+  }
+}
+```
+
+**Input Mapping:**
+| User Input | Keypoint | Quiz |
+|------------|----------|------|
+| 1, default, enter | 06:45 | 22:45 |
+| 2, late | 08:00 | 23:00 |
+| 3, HH:MM HH:MM | first time | second time |
+
+**Validation Rules:**
+- Both times must be in HH:MM format (24-hour)
+- Quiz time must be later than keypoint time
+- If user only provides one time, ask for the second
+- If invalid format, show error and re-prompt
+
+---
+
+## Step 6: Voice Teaching Configuration
+
+```json
+{
+  "type": "init_voice",
+  "step": 6,
+  "display": {
+    "title": "🔊 Step 6/7: Voice Teaching",
+    "message": "Would you like audio versions of knowledge points for listening practice?",
+    "options": [
+      "**1.** 🔊 Yes - Enable voice teaching ⭐ Recommended",
+      "**2.** 🔇 No - Text only, no audio"
+    ],
+    "speed_options": {
+      "description": "If yes, choose your preferred speech speed:",
+      "options": [
+        "**1.** Very slow (0.5x) - Beginner shadowing",
+        "**2.** Slow (0.7x) - Learning pronunciation",
+        "**3.** Normal (0.9x) - Daily learning ⭐ Recommended",
+        "**4.** Fast (1.3x) - Listening challenge",
+        "**5.** Very fast (1.7x) - Advanced training"
+      ]
+    },
+    "default": "yes 3",
+    "prompt": "Reply with **1** or **2**. If yes, also pick speed (e.g., **1** or **1 3** or **yes 3**)",
+    "hint": "💡 Recommended: Yes with normal speed (option 3). Great for commute listening!"
+  }
+}
+```
+
+**Input Mapping:**
+| User Input | Enabled | Speed |
+|------------|---------|-------|
+| 1, yes, y | true | 0.9 (default) |
+| 2, no, n | false | - |
+| 1 3, yes 3 | true | 0.9 |
+| 1 1, yes 1 | true | 0.5 |
+| 1 2, yes 2 | true | 0.7 |
+| 1 4, yes 4 | true | 1.3 |
+| 1 5, yes 5 | true | 1.7 |
+
+**State Update:**
+```json
+{
+  "tts_settings": {
+    "enabled": true,
+    "provider": "edge-tts",
+    "speed": 0.9,
+    "voices": {
+      "narrator": null,
+      "dialogue_a": null,
+      "dialogue_b": null
+    }
+  }
+}
+```
+- If `voices` values are null, use provider defaults
+
+---
+
+## Step 7: Confirmation
+
+```json
+{
+  "type": "init_confirm",
+  "step": 7,
+  "display": {
+    "title": "✅ All Set! Here's Your Profile:",
+    "summary": {
+      "level": "📊 Level: {cefr_level}",
+      "topics": "🎯 Topics: {top_topics}",
+      "style": "🎭 Style: {tutor_style}",
+      "focus": "💬 Focus: {oral_ratio}% speaking",
+      "schedule": "⏰ Schedule: Keypoint at {keypoint_time}, Quiz at {quiz_time}",
+      "voice": "🔊 Voice: {voice_status}"
+    },
+    "options": [
+      "**1.** ✅ Yes, confirm and start learning",
+      "**2.** ✏️ Change something"
+    ],
+    "prompt": "Reply with **1** or **yes** to confirm, or **2** to adjust.",
+    "footer": "───────────────────\n🚀 Your first lesson starts tomorrow!"
+  }
+}
+```
+
+**Voice Status Display:**
+- If enabled: "Enabled, {speed_desc} speed"
+- If disabled: "Disabled (text only)"
+
+---
+
+## Completion
+
+```json
+{
+  "type": "init_complete",
+  "display": {
+    "title": "🎉 Welcome Aboard!",
+    "message": "You're all set! Here's what happens next:\n\n"
+      "☀️ **{keypoint_time}** - Daily knowledge point\n"
+      "🌙 **{quiz_time}** - Daily quiz",
+    "cron_setup": "I'll create cron jobs for your schedule now. You can change this anytime with the **schedule** command.",
+    "first_lesson": "Want your first lesson now? Reply **keypoint** or **知识点**",
+    "footer": "───────────────────\n💡 Say **help** anytime to see all commands"
+  }
+}
+```
+
+---
+
+## Cron Job Creation (after Step 7 confirmation)
+
+After user confirms with "yes" or "1", MUST execute the following bash commands to create cron jobs:
+
+```bash
+# Parse times from schedule
+KEYPOINT_TIME="06:45"  # Default, replace with user's keypoint_time
+QUIZ_TIME="22:45"      # Default, replace with user's quiz_time
+
+# Extract hour and minute
+KEYPOINT_HOUR=$(echo $KEYPOINT_TIME | cut -d: -f1)
+KEYPOINT_MIN=$(echo $KEYPOINT_TIME | cut -d: -f2)
+QUIZ_HOUR=$(echo $QUIZ_TIME | cut -d: -f1)
+QUIZ_MIN=$(echo $QUIZ_TIME | cut -d: -f2)
+
+# Create cron jobs using openclaw
+# Keypoint job
+${KEYPOINT_MIN} ${KEYPOINT_HOUR} * * * openclaw system event --text "Use eng-lang-tutor skill. Push today's keypoint." --mode now
+
+# Quiz job
+${QUIZ_MIN} ${QUIZ_HOUR} * * * openclaw system event --text "Use eng-lang-tutor skill. Push today's quiz invitation." --mode now
+```
+
+**IMPORTANT:** The cron job creation requires:
+1. Parse user's `keypoint_time` and `quiz_time` from state.json schedule
+2. Execute the bash command to register each cron job
+3. Log the event using `state_manager.py append_event`
+
+**State Update:**
+```json
+{
+  "schedule": {
+    "keypoint_time": "06:45",
+    "quiz_time": "22:45",
+    "timezone": "Asia/Shanghai"
+  }
+}
+```

package/templates/prompts/keypoint_generation.md

@@ -0,0 +1,272 @@
+# Knowledge Point Generation Template
+
+> Main template for generating daily English learning content.
+
+**Related Files:**
+- [shared_enums.md](shared_enums.md) - Topics, CEFR levels, tutor styles, quiz types
+- [output_rules.md](output_rules.md) - JSON output rules, markdown formatting
+
+---
+
+## 1. Generation Prompt
+
+```markdown
+You are an authentic American English tutor. Generate a daily knowledge point.
+
+## USER CONTEXT
+- CEFR Level: {cefr_level} (A1=Beginner to C2=Proficient)
+- Topic Focus: {topic} (movies/news/gaming/sports/workplace/social/daily_life)
+- Tutor Style: {tutor_style} (humorous/rigorous/casual/professional)
+- Expression Type: {oral_written_ratio}% oral expressions, {written_ratio}% written
+
+## RESOURCE REFERENCES
+{topic_resources}
+
+## STRICT RULES
+> **See [output_rules.md](output_rules.md) for complete JSON/Markdown formatting rules.**
+
+1. Focus on "How Americans say it" - NOT Chinese translations
+2. Must include: scene context, alternatives, Chinglish trap + correction
+3. Use authentic expressions from the resource references above
+4. Include pronunciation tips for casual speech (gonna, gotta, wanna, etc.)
+5. AVOID these recent topics (14-day dedup): {excluded_topics}
+6. **Include reference links** - provide authoritative sources for verification
+7. **Include formatted display object** - MUST include `display` object with all formatted fields using `**text**` for bold
+8. **Never use strikethrough** - Use ❌ emoji for wrong answers instead of `~~text~~`
+9. **NEVER add [AUDIO:...] tags** - Audio is handled separately by the system
+```
+
+---
+
+## 2. Reference Sources
+
+When generating knowledge points, include links to these authoritative sources:
+
+| Type | Source | URL Pattern | Description |
+|------|--------|-------------|-------------|
+| **Dictionary** | Merriam-Webster | `https://www.merriam-webster.com/dictionary/{phrase}` | Most authoritative American English dictionary |
+| **Usage** | YouGlish | `https://youglish.com/pronounce/{phrase}/english/us` | Real YouTube videos with the phrase |
+| **Etymology** | Etymonline | `https://www.etymonline.com/word/{word}` | Word origin and history |
+| **Frequency** | Google Ngram | `https://books.google.com/ngrams/graph?content={phrase}` | Usage frequency over time |
+
+**URL Encoding:** Replace spaces with `%20` in URLs.
+
+**Reference Requirements:**
+- `dictionary` is REQUIRED - always include Merriam-Webster link
+- `usage_context` is REQUIRED - YouGlish helps users hear real usage
+- `etymology` is OPTIONAL - include for interesting origin stories
+- `frequency` is OPTIONAL - include for frequency comparison
+
+**Example:**
+```json
+{
+  "references": {
+    "dictionary": {
+      "source": "merriam-webster",
+      "url": "https://www.merriam-webster.com/dictionary/touch%20base",
+      "note": "Official definition and usage examples"
+    },
+    "usage_context": {
+      "source": "youglish",
+      "url": "https://youglish.com/pronounce/touch%20base/english/us",
+      "note": "Hear it in 1000+ real YouTube videos"
+    }
+  }
+}
+```
+
+---
+
+## 3. Content Guidelines
+
+### Scene
+- Describe a realistic situation where this expression is used
+- Include formality level (casual/neutral/formal)
+- Make it relatable to the CEFR level
+
+### Expressions
+- Primary expression + 1-2 alternatives
+- Include pronunciation tips for natural speech
+- Usage notes explaining when to use
+
+### Chinglish Trap
+- Show what Chinese speakers TYPICALLY say (the wrong version)
+- Provide the correct American expression
+- Explain WHY the wrong version sounds unnatural
+
+### Examples
+- Use dialogue format with 2-3 exchanges
+- Make conversations feel natural and authentic
+- Include context for each dialogue
+
+---
+
+## 4. Output Schema
+
+```json
+{
+  "_meta": {
+    "prompt_version": "keypoint_gen_v2.1"
+  },
+  "date": "{today_date}",
+  "topic_fingerprint": "unique_lowercase_with_underscores",
+  "category": "oral|written",
+  "topic": "{topic}",
+  "scene": {
+    "context": "Brief description of the situation",
+    "formality": "casual|neutral|formal"
+  },
+  "expressions": [
+    {
+      "phrase": "The American expression",
+      "pronunciation_tip": "How to say it naturally",
+      "usage_note": "When and how to use this"
+    }
+  ],
+  "alternatives": [
+    "Another way to say it 1",
+    "Another way to say it 2"
+  ],
+  "chinglish_trap": {
+    "wrong": "What Chinese speakers typically say",
+    "correct": "The natural American way",
+    "explanation": "Why the wrong version sounds off"
+  },
+  "examples": [
+    {
+      "situation": "Context for example",
+      "dialogue": ["Speaker A: ...", "Speaker B: ..."]
+    }
+  ],
+  "extended_learning": {
+    "related_phrases": ["phrase1", "phrase2"],
+    "cultural_note": "Brief cultural context",
+    "common_mistakes": ["mistake1"]
+  },
+  "references": {
+    "dictionary": {
+      "source": "merriam-webster",
+      "url": "https://www.merriam-webster.com/dictionary/{phrase}",
+      "note": "Definition and usage examples"
+    },
+    "usage_context": {
+      "source": "youglish",
+      "url": "https://youglish.com/pronounce/{phrase}/english/us",
+      "note": "Hear it in real YouTube videos"
+    }
+  },
+  "display": {
+    "title": "🏢 今日知识点 | Today's Knowledge Point",
+    "topic_tag": "🏷️ 主题: **{topic_name}** | {topic_name_en}",
+    "formality_tag": "📊 正式度: **{formality}**",
+    "scene_intro": "🎬 场景 | Scene",
+    "scene_text": "{scene_context}",
+    "expressions_title": "💬 核心表达 | Key Expressions",
+    "expressions_formatted": [
+      {
+        "emoji": "✨",
+        "phrase": "**{phrase}**",
+        "phrase_plain": "{phrase}",
+        "pronunciation": "🔊 {pronunciation_tip}",
+        "usage": "💡 {usage_note}"
+      }
+    ],
+    "alternatives_title": "🔄 其他说法 | Alternatives",
+    "alternatives_formatted": "• **{alt_1}**\n• **{alt_2}**",
+    "chinglish_title": "⚠️ Chinglish 陷阱 | Chinglish Trap",
+    "chinglish_formatted": "❌ Wrong: \"{wrong}\"\n✅ Correct: **{correct}**\n\n📝 {explanation}",
+    "examples_title": "🗣️ 对话示例 | Example Dialogues",
+    "examples_formatted": [
+      {
+        "situation_emoji": "☕",
+        "situation": "{situation_name}",
+        "dialogue": "💬 A: {line_1}\n💬 B: {line_2}",
+        "key_phrase_highlight": "**{key_phrase}**"
+      }
+    ],
+    "extended_title": "📚 延伸学习 | Extended Learning",
+    "extended_formatted": "🔗 Related: **{related_1}** | **{related_2}**\n\n🌎 {cultural_note}",
+    "references_title": "📖 权威参考 | References",
+    "references_formatted": "📚 [Merriam-Webster]({dict_url}) - {dict_note}\n🎬 [YouGlish]({usage_url}) - {usage_note}",
+    "footer": "───────────────────\n📅 {date} | 📝 Take the quiz to earn XP!"
+  }
+}
+```
+
+---
+
+## 5. Topic Resource Injection
+
+When generating content, inject topic-specific resources:
+
+```python
+TOPIC_RESOURCES = {
+    "movies": """
+    Reference expressions from TV shows:
+    - Friends: "How you doin'?", "Could I BE any more...?"
+    - The Office: "That's what she said", "Touch base"
+    - Gossip Girl: "No offense", "None taken", "Done and done"
+    Focus on: dialogue patterns, humor, sarcasm, casual speech
+    """,
+
+    "news": """
+    Reference vocabulary from:
+    - CNN 10: Current events, clear explanations
+    - VOA: Simplified news vocabulary
+    Focus on: formal register, topic-specific vocabulary, clear structure
+    """,
+
+    "gaming": """
+    Reference gaming terminology:
+    - Core: NPC, spawn, loot, grind, level up, buff, nerf
+    - Multiplayer: party, squad, GG, clutch, carry
+    - Slang in daily use: "That was clutch", "GG"
+    Focus on: casual speech, slang, gaming-specific vocabulary
+    """,
+
+    "sports": """
+    Reference sports vocabulary:
+    - Basketball: dunk, buzzer beater, pick and roll
+    - Sports idioms: "step up to the plate", "ballpark figure"
+    Focus on: energetic expressions, idioms used in business
+    """,
+
+    "workplace": """
+    Reference workplace expressions:
+    - Office idioms: touch base, circle back, bandwidth
+    - Meeting phrases: "Let's get the ball rolling", "wrap up"
+    - Email language: formal yet natural
+    Focus on: professional communication, formal/informal switching
+    """,
+
+    "social": """
+    Reference social expressions:
+    - Greetings: "What's up?", "How's it going?"
+    - Making plans: "Let's hang out", "grab coffee"
+    - Casual responses: "Not much, you?", "Can't complain"
+    Focus on: casual speech, fillers, natural conversation flow
+    """,
+
+    "daily_life": """
+    Reference daily life expressions:
+    - Shopping: "Just looking", "Can I get a discount?"
+    - Restaurant: "I'd like the...", "Check, please"
+    - Services: Asking for help, making requests
+    Focus on: practical communication, politeness strategies
+    """
+}
+```
+
+---
+
+## 6. CEFR Level Guidelines
+
+> See [shared_enums.md](shared_enums.md#cefr-levels-能力等级) for level definitions.
+
+Adjust content complexity based on CEFR level.
+
+---
+
+## 7. Tutor Style Variations
+
+> See [shared_enums.md](shared_enums.md#tutor-styles-导师风格) for style definitions.