@rookiestar/eng-lang-tutor 1.0.2 → 1.0.3

package/CLAUDE.md

@@ -70,7 +70,6 @@ Agent结合难度与偏好的设置，以及用户的历史学习进度动态生
 |-----|------|
 | **XP & 等级** | 1-20级，XP累积升级（启程者 → 行路人 → 探索者 → 开拓者） |
 | **连胜系统** | 连续学习天数，支持连胜冻结（50宝石） |
-| **联赛系统** | Bronze → Silver → Gold → Platinum → Diamond（周结算） |
 | **徽章系统** | First Steps、Week Warrior、Month Master、Perfect 10、Vocab Hunter、Error Slayer |
 | **宝石系统** | 用于购买连胜冻结、提示等 |
 
@@ -148,7 +147,7 @@ eng-lang-tutor/
 ├── scripts/
 │   ├── state_manager.py        # 状态持久化与事件日志
 │   ├── scorer.py               # 答案评估与XP计算
-│   ├── gamification.py         # 连胜/等级/徽章/联赛
+│   ├── gamification.py         # 连胜/等级/徽章
 │   └── dedup.py                # 14天去重逻辑
 ├── templates/
 │   ├── state_schema.json       # 状态 JSON Schema
@@ -160,7 +159,8 @@ eng-lang-tutor/
 ├── examples/
 │   ├── sample_keypoint.json    # 示例知识点
 │   └── sample_quiz.json        # 示例Quiz
-└── data/
+└── (数据存储在外部目录)
+    ~/.openclaw/state/eng-lang-tutor/   # 实际数据存储位置
     ├── state.json              # 运行时状态
     ├── logs/
     │   └── events_YYYY-MM.jsonl
@@ -169,6 +169,8 @@ eng-lang-tutor/
             ├── keypoint.json
             ├── quiz.json
             └── user_answers.json
+
+    注: 可通过 OPENCLAW_STATE_DIR 环境变量自定义存储位置
 ```
 
 ## 4. 功能切片实现
@@ -185,7 +187,6 @@ eng-lang-tutor/
 | 连胜更新 | gamification.py | study_date | new_streak |
 | 等级更新 | gamification.py | XP | level |
 | 徽章检查 | gamification.py | progress | new_badges |
-| 联赛更新 | gamification.py | weekly_xp | league |
 | 去重检查 | dedup.py | new_content, recent_content | is_duplicate |
 
 ### 4.2 核心工作流

package/README.md

@@ -45,6 +45,12 @@ openclaw skills list
 openclaw skills info eng-lang-tutor
 ```
 
+**重启 Gateway：**
+
+```bash
+openclaw gateway restart
+```
+
 **配置渠道：**
 
 **Discord 配置：**
@@ -165,12 +171,21 @@ eng-lang-tutor/
 │   ├── dedup.py                # 14天去重逻辑
 │   ├── command_parser.py       # 用户命令解析
 │   ├── cron_push.py            # 定时内容推送
+│   ├── constants.py            # 共享常量（等级阈值）
+│   ├── utils.py                # 工具函数（安全除法、深度合并）
+│   ├── cli.py                  # CLI 入口点
 │   └── tts/                    # TTS 语音合成模块
 ├── templates/
 │   ├── state_schema.json       # 状态 JSON Schema
 │   ├── keypoint_schema.json    # 知识点 JSON Schema
 │   ├── quiz_schema.json        # 测验 JSON Schema
-│   └── prompt_templates.md     # LLM Prompt 模板
+│   ├── prompt_templates.md     # LLM Prompt 模板索引
+│   └── prompts/                # 拆分的 Prompt 模板
+│       ├── keypoint_generation.md
+│       ├── quiz_generation.md
+│       ├── display_guide.md
+│       ├── initialization.md
+│       └── responses.md
 ├── references/
 │   └── resources.md            # 主题化学习资源
 ├── examples/

package/README_EN.md

@@ -45,6 +45,12 @@ openclaw skills list
 openclaw skills info eng-lang-tutor
 ```
 
+**Restart Gateway:**
+
+```bash
+openclaw gateway restart
+```
+
 ### Configure Channel
 
 **Discord Configuration:**
@@ -165,12 +171,21 @@ eng-lang-tutor/
 │   ├── dedup.py                # 14-day deduplication
 │   ├── command_parser.py       # User command parsing
 │   ├── cron_push.py            # Scheduled content push
+│   ├── constants.py            # Shared constants (level thresholds)
+│   ├── utils.py                # Utility functions (safe divide, deep merge)
+│   ├── cli.py                  # CLI entry point
 │   └── tts/                    # TTS module
 ├── templates/
 │   ├── state_schema.json       # State JSON Schema
 │   ├── keypoint_schema.json    # Keypoint JSON Schema
 │   ├── quiz_schema.json        # Quiz JSON Schema
-│   └── prompt_templates.md     # LLM prompt templates
+│   ├── prompt_templates.md     # LLM prompt templates index
+│   └── prompts/                # Split prompt templates
+│       ├── keypoint_generation.md
+│       ├── quiz_generation.md
+│       ├── display_guide.md
+│       ├── initialization.md
+│       └── responses.md
 ├── references/
 │   └── resources.md            # Themed learning resources
 ├── examples/

package/SKILL.md

@@ -61,57 +61,48 @@ Output: results.json, updated state.json
 
 ## Quiz Types
 
-| Type | Description | XP Value | Daily Quiz |
-|------|-------------|----------|------------|
-| multiple_choice | Select correct expression from 4 options | 10 | 1 (required) |
-| chinglish_fix | Identify and correct Chinglish expression | 15 | 1 (required) |
-| fill_blank | Complete dialogue with missing expression | 12 | 0-1 (random) |
-| dialogue_completion | Choose appropriate response in context | 15 | 0-1 (random) |
+> See [templates/prompts/shared_enums.md](templates/prompts/shared_enums.md#quiz-question-types-题型) for full definitions.
 
-**Daily Quiz Pattern**: 3 questions, ~37 XP, pass with 2/3 correct
+| Type | XP | Daily |
+|------|-----|-------|
+| multiple_choice | 10 | 1 (required) |
+| chinglish_fix | 15 | 1 (required) |
+| fill_blank / dialogue_completion | 12 | 0-1 (random) |
+
+**Daily Quiz:** 3 questions, ~37 XP, pass with 2/3 correct
 
 ## Gamification System
 
 ### XP & Levels
 
 This system has two independent level systems:
-- **Ability Level (CEFR)**: A1-C2, determines content difficulty (language proficiency)
-- **Activity Level (Level)**: 1-20, measures engagement depth (usage progression)
+- **Ability Level (CEFR)**: A1-C2, determines content difficulty
+- **Activity Level (Level)**: 1-20, measures engagement depth
 
-**Activity Level Stages (Journey):**
-- Level 1-5 (Starter/启程者): 0-350 XP
-- Level 6-10 (Traveler/行路人): 550-2000 XP
-- Level 11-15 (Explorer/探索者): 2600-6000 XP
-- Level 16-20 (Pioneer/开拓者): 7200-15000 XP
+> See [templates/prompts/shared_enums.md](templates/prompts/shared_enums.md) for level stages and badge definitions.
 
 ### Streak System
 - Consecutive days of study builds streak
-- Streak broken if miss a day (unless using streak freeze)
-- Streak multiplier: 1.0 + (streak * 0.05), max 2.0x
+- Streak multiplier: `1.0 + (streak * 0.05)`, max 2.0x
 - Streak freeze costs 50 gems
 
-### Badges
-- First Steps: Complete first quiz (+10 gems)
-- Week Warrior: 7-day streak (+25 gems)
-- Month Master: 30-day streak (+100 gems)
-- Perfect 10: 10 perfect quizzes (+50 gems)
-- Vocab Hunter: Learn 100 expressions (+75 gems)
-- Error Slayer: Clear 30 errors (+30 gems)
-
 ## Key Scripts
 
 | Script | Purpose |
 |--------|---------|
-| state_manager.py | State persistence, event logging, CLI for content saving |
+| state_manager.py | State persistence, event logging, error notebook |
 | cron_push.py | Scheduled content push (keypoint/quiz placeholders) |
 | scorer.py | Answer evaluation, XP calculation |
 | gamification.py | Streak/level/badge logic |
 | dedup.py | 14-day content deduplication |
 | command_parser.py | Natural language command parsing |
+| constants.py | Shared constants (level thresholds, level names) |
+| utils.py | Utility functions (safe divide, deep merge) |
+| cli.py | CLI entry point for state management |
 
 ## CLI Commands
 
-> These bash commands are used by the Agent to execute operations. All commands use `--data-dir data` by default.
+> These bash commands are used by the Agent to execute operations. Data is stored in `~/.openclaw/state/eng-lang-tutor/` by default. Do NOT specify `--data-dir` unless using a custom location.
 
 ### Content Management
 ```bash
@@ -162,19 +153,17 @@ python3 scripts/state_manager.py schedule --keypoint-time 07:00 --quiz-time 21:0
 
 ## Core Principles
 
+> See [templates/prompts/keypoint_generation.md](templates/prompts/keypoint_generation.md) for detailed generation rules.
+
 1. **Always output valid JSON** - No markdown, no extra text
 2. **Focus on "How Americans say it"** - NOT translation
-3. **Every knowledge point must include**:
-   - Scene context
-   - Alternative expressions
-   - Chinglish trap + correction
+3. **Every knowledge point must include**: Scene context, alternatives, Chinglish trap
 4. **14-day deduplication** - No repeated topics or expressions
-5. **Topic fingerprints** - Use unique identifiers for deduplication
 
 ## File Structure
 
 ```
-data/
+~/.openclaw/state/eng-lang-tutor/  # Default data location
   state.json              # Core state (streak/xp/preferences)
   logs/
     events_2026-02.jsonl  # Monthly event log
@@ -185,6 +174,8 @@ data/
       user_answers.json   # User's answers
 ```
 
+**Note:** Data location can be customized via `OPENCLAW_STATE_DIR` environment variable.
+
 ## JSON Schemas
 
 See templates/ directory:
@@ -194,11 +185,18 @@ See templates/ directory:
 
 ## Resource References
 
-See references/ directory:
-- resources.md - Themed English learning resources (TV shows, news, gaming, sports, workplace, daily life)
+**Prompt Templates** (templates/prompts/):
+- [shared_enums.md](templates/prompts/shared_enums.md) - Topics, CEFR levels, styles, badges
+- [output_rules.md](templates/prompts/output_rules.md) - JSON/markdown formatting rules
+- [keypoint_generation.md](templates/prompts/keypoint_generation.md) - Knowledge point generation
+- [quiz_generation.md](templates/prompts/quiz_generation.md) - Quiz generation
+- [display_guide.md](templates/prompts/display_guide.md) - Emoji and formatting guide
+- [initialization.md](templates/prompts/initialization.md) - Onboarding flow
+- [responses.md](templates/prompts/responses.md) - Response templates
 
-See templates/ directory:
-- prompt_templates.md - LLM prompt templates for content generation
+**Other Resources:**
+- [references/resources.md](references/resources.md) - Themed English learning resources
+- [templates/prompt_templates.md](templates/prompt_templates.md) - Prompt template index
 
 ## Examples
 
@@ -250,32 +248,15 @@ The bot recognizes these natural language commands:
 
 ## Initialization Flow
 
-New users go through a 6-step onboarding process:
+> See [templates/prompts/initialization.md](templates/prompts/initialization.md) for detailed onboarding templates.
 
-```
-Step 0: Welcome → User replies "start"
-Step 1: Select CEFR Level (A1-C2)
-Step 2: Select Topic Interests (movies/news/gaming/sports/workplace/social/daily_life)
-Step 3: Select Tutor Style (humorous/rigorous/casual/professional)
-Step 4: Select Oral/Written Ratio (0-100% oral)
-Step 5: Configure Schedule (keypoint time, quiz time) - Quiz must be later than keypoint
-Step 6: Confirm Configuration → Set initialized=true + Create cron jobs
-```
+6-step onboarding: Welcome → CEFR Level → Topic Interests → Tutor Style → Oral/Written Ratio → Schedule → Confirm
 
-**Step 6 Completion Actions:**
-When user confirms with "yes":
-1. Set `initialized=true` via `state_manager.py`
-2. Create cron jobs for keypoint and quiz push times:
-   ```bash
-   # Parse schedule from state.json
-   # Keypoint job: {minute} {hour} * * * openclaw system event --text "Use eng-lang-tutor skill. Push today's keypoint." --mode now
-   # Quiz job: {minute} {hour} * * * openclaw system event --text "Use eng-lang-tutor skill. Push today's quiz invitation." --mode now
-   ```
-3. Log the completion event
+**Step 6 Completion:** Set `initialized=true` + Create cron jobs for keypoint/quiz push times.
 
 **State Fields:**
 - `initialized`: Boolean - Whether user completed onboarding
-- `onboarding_step`: Integer (0-6) - Current step in onboarding
+- `onboarding_step`: Integer (0-6) - Current step
 
 ---
 
@@ -283,53 +264,93 @@ When user confirms with "yes":
 
 > **TIMEZONE AWARENESS:** All "today" date checks should use `state.json schedule.timezone` (default: Asia/Shanghai) to ensure consistent behavior across server locations. File paths like `daily/2026-02-21/` are timezone-specific.
 
+---
+
+## ⛔ MANDATORY BASH COMMANDS - READ THIS FIRST ⛔
+
+**When generating content via LLM, you MUST execute bash commands to persist data to disk.**
+
+### After Keypoint Generation (MANDATORY)
+```
+Step 1: LLM generates keypoint JSON
+Step 2: ⛔ EXECUTE THIS BASH COMMAND (do NOT skip):
+        python3 scripts/state_manager.py save_daily --content-type keypoint --content '<ESCAPED_JSON>'
+Step 3: ⛔ EXECUTE THIS BASH COMMAND (do NOT skip):
+        python3 scripts/state_manager.py record_view
+Step 4: Display formatted content to user
+```
+
+### After Quiz Generation (MANDATORY)
+```
+Step 1: LLM generates quiz JSON
+Step 2: ⛔ EXECUTE THIS BASH COMMAND (do NOT skip):
+        python3 scripts/state_manager.py save_daily --content-type quiz --content '<ESCAPED_JSON>'
+Step 3: Present quiz questions to user
+```
+
+**JSON Escaping Rules:**
+- Wrap content in single quotes: `'{"key": "value"}'`
+- Escape internal single quotes: `'` → `'\''`
+- Example: `'{"title": "It'\''s a test"}'`
+
+**⛔ FAILURE TO EXECUTE BASH COMMANDS = DATA LOSS ⛔**
+
+---
+
 ### Quiz Already Completed
 ```
 User: "quiz"
 Bot checks: completion_status.quiz_completed_date == today?
   → YES: "You've already completed today's quiz! 🎉 Score: X/Y"
-  → NO: Check quiz.json exists (data/daily/YYYY-MM-DD/quiz.json) and quiz.generated == true?
+  → NO: Check quiz.json exists (~/.openclaw/state/eng-lang-tutor/daily/YYYY-MM-DD/quiz.json) and quiz.generated == true?
       → YES: Load quiz and present questions
-      → NO: Generate quiz via LLM, then:
-          1. Set generated=true in the JSON content
-          2. Save via bash: python3 scripts/state_manager.py save_daily --content-type quiz --content '<ESCAPED_JSON>'
-          3. Present questions
+      → NO:
+         1. Check if keypoint.json exists for today
+            → If NO: Generate keypoint via LLM first
+            → ⛔ EXECUTE: python3 scripts/state_manager.py save_daily --content-type keypoint --content '<ESCAPED_JSON>'
+         2. Generate quiz via LLM
+         3. Set generated=true in the JSON content
+         4. ⛔ EXECUTE: python3 scripts/state_manager.py save_daily --content-type quiz --content '<ESCAPED_JSON>'
+         5. Present questions to user
 ```
 
-**CRITICAL:**
-1. After LLM generation, MUST update quiz JSON with `"generated": true` to prevent re-generation
-2. MUST save via bash command:
-   ```bash
-   python3 scripts/state_manager.py save_daily --content-type quiz --content '<ESCAPED_JSON>'
-   ```
+**⛔ CRITICAL: You MUST execute bash commands to save BEFORE presenting to user.**
+
+### Manual Quiz Before Keypoint Push
+```
+User manually requests quiz before scheduled keypoint push time
+Bot checks: Does keypoint.json exist for today?
+  → NO:
+     1. IMMEDIATELY generate keypoint via LLM (do NOT say "will notify later")
+     2. ⛔ EXECUTE: python3 scripts/state_manager.py save_daily --content-type keypoint --content '<ESCAPED_JSON>'
+     3. Generate quiz via LLM
+     4. ⛔ EXECUTE: python3 scripts/state_manager.py save_daily --content-type quiz --content '<ESCAPED_JSON>'
+     5. Present quiz questions to user
+     → All in ONE response - user should receive quiz immediately
+  → YES: Proceed with quiz generation normally (see Quiz Already Completed section)
+
+This ensures learning sequence is preserved even for early learners.
+```
+
+**⛔ CRITICAL: NEVER tell user "will generate later and notify" - always generate immediately.**
+**⛔ CRITICAL: You MUST execute the bash save commands BEFORE presenting content to user.**
 
 ### Keypoint Query
 ```
 User: "keypoint" or "知识点" or Cron Push
-Bot checks: Does keypoint.json exist for today (data/daily/YYYY-MM-DD/keypoint.json)?
-  → NO: Generate new keypoint via LLM, then:
-      1. Set generated=true in the JSON content
-      2. Save via bash: python3 scripts/state_manager.py save_daily --content-type keypoint --content '<ESCAPED_JSON>'
-      3. Record view via bash: python3 scripts/state_manager.py record_view
-      4. Display formatted content
+Bot checks: Does keypoint.json exist for today (~/.openclaw/state/eng-lang-tutor/daily/YYYY-MM-DD/keypoint.json)?
+  → NO:
+     1. Generate new keypoint via LLM
+     2. Set generated=true in the JSON content
+     3. ⛔ EXECUTE: python3 scripts/state_manager.py save_daily --content-type keypoint --content '<ESCAPED_JSON>'
+     4. ⛔ EXECUTE: python3 scripts/state_manager.py record_view
+     5. Display formatted content to user
   → YES: Check keypoint.generated
-      → TRUE: Record view via bash, then read display object and output as Markdown
-      → FALSE: Generate content via LLM, then follow steps 1-4 above
-```
-
-**CRITICAL:**
-1. After LLM generation, MUST update keypoint JSON with `"generated": true` to prevent re-generation
-2. MUST save via bash command:
-   ```bash
-   python3 scripts/state_manager.py save_daily --content-type keypoint --content '<ESCAPED_JSON>'
-   ```
-3. MUST record view after displaying:
-   ```bash
-   python3 scripts/state_manager.py record_view
-   ```
-4. JSON content must be properly escaped:
-   - Wrap in single quotes
-   - Escape internal single quotes: `'` → `'\''`
+      → TRUE: ⛔ EXECUTE: python3 scripts/state_manager.py record_view, then display to user
+      → FALSE: Follow steps 1-5 above
+```
+
+**⛔ CRITICAL: You MUST execute bash commands to save BEFORE displaying to user.**
 
 **Display Fields (from keypoint.json `display` object):**
 
@@ -352,7 +373,7 @@ Bot checks: Does keypoint.json exist for today (data/daily/YYYY-MM-DD/keypoint.j
 ### Keypoint History
 ```
 User: "keypoint history" or "知识点 历史"
-Bot scans: data/daily/ directory for YYYY-MM-DD/keypoint.json files
+Bot scans: ~/.openclaw/state/eng-lang-tutor/daily/ directory for YYYY-MM-DD/keypoint.json files
   → NO files found: "📚 No history yet. Start learning with 'keypoint' today!"
   → YES: List keypoints (most recent first), max 10 entries:
       - {date}: {title/topic} (e.g., "2026-02-20: Touch Base - 工作沟通")

package/docs/OPENCLAW_DEPLOYMENT.md

@@ -42,7 +42,8 @@ git clone https://github.com/rookiestar/eng-lang-tutor.git
 ├── templates/            # JSON Schema
 ├── references/           # 参考资源
 ├── examples/             # 示例文件
-└── data/                 # 运行时数据
+└── (数据存储在外部目录)
+    ~/.openclaw/state/eng-lang-tutor/  # 运行时数据（自动创建）
 ```
 
 ### 2.3 验证 Skill 加载
@@ -142,12 +143,14 @@ openclaw config set model.api_key YOUR_API_KEY
 
 ### 5.3 数据持久化
 
-确保 `data/` 目录有正确的写入权限：
+数据存储在 `~/.openclaw/state/eng-lang-tutor/` 目录，确保有正确的写入权限：
 
 ```bash
-chmod -R 755 ~/.openclaw/skills/eng-lang-tutor/data/
+chmod -R 755 ~/.openclaw/state/eng-lang-tutor/
 ```
 
+可通过环境变量 `OPENCLAW_STATE_DIR` 自定义数据目录。
+
 ## 6. 故障排查
 
 ### 6.1 Skill 未加载
@@ -208,7 +211,7 @@ python3 state_manager.py --show
 ┌─────────────────────────────────────────────────────────┐
 │               eng-lang-tutor Skill                      │
 │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
-│  │ SKILL.md    │  │ scripts/    │  │ data/       │    │
+│  │ SKILL.md    │  │ scripts/    │  │ ~/.openclaw │    │
 │  │ (技能描述)   │  │ (Python代码) │  │ (状态存储)   │    │
 │  └─────────────┘  └─────────────┘  └─────────────┘    │
 └─────────────────────────────────────────────────────────┘

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rookiestar/eng-lang-tutor",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "English language tutor skill for OpenClaw - Learn authentic American English expressions with gamification",
   "keywords": [
     "english",