@rookiestar/eng-lang-tutor 1.0.16 → 1.0.18

package/CLAUDE.md

@@ -117,7 +117,7 @@ Agent结合难度与偏好的设置，以及用户的历史学习进度动态生
 
 #### 2.3.3 去重策略（14天窗口）
 
-使用 `scripts/dedup.py` 实现三层去重：
+使用 `scripts/utils/dedup.py` 实现三层去重：
 
 | 层级 | 方法 | 描述 |
 |-----|------|-----|
@@ -145,10 +145,27 @@ eng-lang-tutor/
 ├── SKILL.md                    # 核心技能文档
 ├── CLAUDE.md                   # 项目说明（本文件）
 ├── scripts/
-│   ├── state_manager.py        # 状态持久化与事件日志
-│   ├── scorer.py               # 答案评估与XP计算
-│   ├── gamification.py         # 连胜/等级/徽章
-│   └── dedup.py                # 14天去重逻辑
+│   ├── __init__.py             # 包入口，重导出核心类
+│   ├── core/
+│   │   ├── state_manager.py    # 状态持久化与事件日志
+│   │   ├── error_notebook.py   # 错题本管理
+│   │   ├── scorer.py           # 答案评估与XP计算
+│   │   ├── gamification.py     # 连胜/等级/徽章
+│   │   └── constants.py        # 共享常量和工具函数
+│   ├── cli/
+│   │   ├── cli.py              # CLI入口点
+│   │   └── command_parser.py   # 命令解析
+│   ├── audio/
+│   │   ├── tts/                # TTS引擎（Coqui/Azure/Edge）
+│   │   ├── composer.py         # 音频合成
+│   │   ├── converter.py        # 格式转换
+│   │   ├── feishu_voice.py     # 飞书语音发送
+│   │   └── utils.py            # 音频工具函数
+│   ├── scheduling/
+│   │   └── cron_push.py        # 定时推送
+│   └── utils/
+│       ├── dedup.py            # 14天去重逻辑
+│       └── helpers.py          # 通用工具函数
 ├── templates/
 │   ├── state_schema.json       # 状态 JSON Schema
 │   ├── keypoint_schema.json    # 知识点 JSON Schema
@@ -179,15 +196,15 @@ eng-lang-tutor/
 
 | 切片 | 对应脚本 | 输入 | 输出 |
 |-----|---------|------|-----|
-| 状态加载/保存 | state_manager.py | - | state.json |
-| 事件日志 | state_manager.py | event_type, data | events_YYYY-MM.jsonl |
-| 每日内容保存 | state_manager.py | content_type, content | daily/YYYY-MM-DD/*.json |
-| 答案评估 | scorer.py | quiz.json + user_answers | results + updated state |
-| XP计算 | scorer.py | correct_count, streak | XP with multiplier |
-| 连胜更新 | gamification.py | study_date | new_streak |
-| 等级更新 | gamification.py | XP | level |
-| 徽章检查 | gamification.py | progress | new_badges |
-| 去重检查 | dedup.py | new_content, recent_content | is_duplicate |
+| 状态加载/保存 | core/state_manager.py | - | state.json |
+| 事件日志 | core/state_manager.py | event_type, data | events_YYYY-MM.jsonl |
+| 每日内容保存 | core/state_manager.py | content_type, content | daily/YYYY-MM-DD/*.json |
+| 答案评估 | core/scorer.py | quiz.json + user_answers | results + updated state |
+| XP计算 | core/scorer.py | correct_count, streak | XP with multiplier |
+| 连胜更新 | core/gamification.py | study_date | new_streak |
+| 等级更新 | core/gamification.py | XP | level |
+| 徽章检查 | core/gamification.py | progress | new_badges |
+| 去重检查 | utils/dedup.py | new_content, recent_content | is_duplicate |
 
 ### 4.2 核心工作流
 

package/SKILL.md

@@ -90,15 +90,17 @@ This system has two independent level systems:
 
 | Script | Purpose |
 |--------|---------|
-| 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 |
+| core/state_manager.py | State persistence, event logging, error notebook |
+| core/error_notebook.py | Error notebook management |
+| core/scorer.py | Answer evaluation, XP calculation |
+| core/gamification.py | Streak/level/badge logic |
+| core/constants.py | Shared constants (level thresholds, level names) |
+| cli/cli.py | CLI entry point for state management |
+| cli/command_parser.py | Natural language command parsing |
+| scheduling/cron_push.py | Scheduled content push (keypoint/quiz placeholders) |
+| utils/dedup.py | 14-day content deduplication |
+| utils/helpers.py | Utility functions (safe divide, deep merge) |
+| audio/ | Audio generation (TTS, composition, conversion, Feishu) |
 
 ## CLI Commands
 
@@ -107,48 +109,48 @@ This system has two independent level systems:
 ### Content Management
 ```bash
 # Save daily content (keypoint/quiz)
-python3 scripts/state_manager.py save_daily --content-type keypoint --content '<JSON>'
+python3 -m scripts.cli.cli save_daily --content-type keypoint --content '<JSON>'
 
 # Record keypoint view
-python3 scripts/state_manager.py record_view [--date YYYY-MM-DD]
+python3 -m scripts.cli.cli record_view [--date YYYY-MM-DD]
 ```
 
 ### Stats & Config
 ```bash
 # Display learning progress
-python3 scripts/state_manager.py stats
+python3 -m scripts.cli.cli stats
 
 # Display current configuration
-python3 scripts/state_manager.py config
+python3 -m scripts.cli.cli config
 
 # Update configuration
-python3 scripts/state_manager.py config --cefr B2
-python3 scripts/state_manager.py config --style professional
-python3 scripts/state_manager.py config --oral-ratio 80
+python3 -m scripts.cli.cli config --cefr B2
+python3 -m scripts.cli.cli config --style professional
+python3 -m scripts.cli.cli config --oral-ratio 80
 ```
 
 ### Error Notebook
 ```bash
 # List errors (paginated)
-python3 scripts/state_manager.py errors [--page 1] [--per-page 5] [--month YYYY-MM]
+python3 -m scripts.cli.cli errors [--page 1] [--per-page 5] [--month YYYY-MM]
 
 # Get random errors for review
-python3 scripts/state_manager.py errors --random 5
+python3 -m scripts.cli.cli errors --random 5
 
 # Get error statistics
-python3 scripts/state_manager.py errors --stats
+python3 -m scripts.cli.cli errors --stats
 
 # Get errors for review session
-python3 scripts/state_manager.py errors --review 5
+python3 -m scripts.cli.cli errors --review 5
 ```
 
 ### Schedule
 ```bash
 # Display current schedule
-python3 scripts/state_manager.py schedule
+python3 -m scripts.cli.cli schedule
 
 # Update schedule (quiz_time must be later than keypoint_time)
-python3 scripts/state_manager.py schedule --keypoint-time 07:00 --quiz-time 21:00
+python3 -m scripts.cli.cli schedule --keypoint-time 07:00 --quiz-time 21:00
 ```
 
 ## Core Principles
@@ -274,10 +276,10 @@ The bot recognizes these natural language commands:
 ```
 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>'
+        python3 -m scripts.cli.cli save_daily --content-type keypoint --content '<ESCAPED_JSON>'
         (This auto-generates audio and saves to audio/YYYY-MM-DD/keypoint_full.mp3)
 Step 3: ⛔ EXECUTE THIS BASH COMMAND (do NOT skip):
-        python3 scripts/state_manager.py record_view
+        python3 -m scripts.cli.cli record_view
 Step 4: Send audio file via message tool (if audio exists):
         - Read keypoint.json and check if audio.composed field exists
         - If exists, send audio file using message tool with media parameter
@@ -287,46 +289,66 @@ Step 5: Display formatted content to user
 
 ### Audio File Sending (After Keypoint Save)
 
-When keypoint is saved, audio is auto-generated and copied to OpenClaw's allowed media directory. Send it to user:
+When keypoint is saved, audio is auto-generated. Send it to user with backward compatibility:
 
+**Step 1: Check voice bubble capability**
+```bash
+echo $FEISHU_VOICE_BUBBLE_ENABLED
 ```
-1. Check keypoint.json for audio field:
-   cat ~/.openclaw/state/eng-lang-tutor/daily/YYYY-MM-DD/keypoint.json | grep -o '"audio":{[^}]*}'
 
-2. If audio.composed exists, send via message tool:
-   {
-     "action": "send",
-     "media": "~/.openclaw/media/{audio.composed}",
-     "caption": "🔊 今日知识点语音版"
-   }
+**Step 2a: If FEISHU_VOICE_BUBBLE_ENABLED=true (enhanced mode)**
+
+Send BOTH voice bubble AND file attachment for best compatibility:
+
+```json
+// Voice bubble (handled by enhanced OpenClaw gateway)
+{
+  "action": "send",
+  "media": "~/.openclaw/media/{audio.composed}",
+  "asVoice": true
+}
+
+// File attachment (fallback for progress bar control)
+{
+  "action": "send",
+  "media": "~/.openclaw/media/{audio.composed}",
+  "caption": "🔊 今日知识点语音版"
+}
+```
 
-   Example:
-   {
-     "action": "send",
-     "media": "~/.openclaw/media/eng-lang-tutor/2026-02-23/keypoint_full.mp3",
-     "caption": "🔊 今日知识点语音版"
-   }
+**Step 2b: If FEISHU_VOICE_BUBBLE_ENABLED not set or false (standard mode)**
 
-3. Audio file info is stored in keypoint.json:
-   {
-     "audio": {
-       "composed": "eng-lang-tutor/2026-02-23/keypoint_full.mp3",
-       "duration_seconds": 37.7,
-       "generated_at": "2026-02-23T02:20:14"
-     }
-   }
+Only send file attachment:
+```json
+{
+  "action": "send",
+  "media": "~/.openclaw/media/{audio.composed}",
+  "caption": "🔊 今日知识点语音版"
+}
+```
+
+**Audio file info is stored in keypoint.json:**
+```json
+{
+  "audio": {
+    "composed": "eng-lang-tutor/2026-02-23/keypoint_full.mp3",
+    "duration_seconds": 37.7,
+    "generated_at": "2026-02-23T02:20:14"
+  }
+}
 ```
 
 **IMPORTANT:**
 - Audio is saved to `~/.openclaw/media/` (OpenClaw's allowed media directory)
 - Always send audio file BEFORE displaying text content
 - The `audio.composed` field contains the path relative to `~/.openclaw/media/`
+- Enhanced mode (voice bubble) requires OpenClaw gateway patch for Feishu
 
 ### 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>'
+        python3 -m scripts.cli.cli save_daily --content-type quiz --content '<ESCAPED_JSON>'
 Step 3: Present quiz questions to user
 ```
 
@@ -349,10 +371,10 @@ Bot checks: completion_status.quiz_completed_date == today?
       → 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>'
+            → ⛔ EXECUTE: python3 -m scripts.cli.cli 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>'
+         4. ⛔ EXECUTE: python3 -m scripts.cli.cli save_daily --content-type quiz --content '<ESCAPED_JSON>'
          5. Present questions to user
 ```
 
@@ -364,9 +386,9 @@ 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>'
+     2. ⛔ EXECUTE: python3 -m scripts.cli.cli 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>'
+     4. ⛔ EXECUTE: python3 -m scripts.cli.cli 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)
@@ -384,12 +406,12 @@ Bot checks: Does keypoint.json exist for today (~/.openclaw/state/eng-lang-tutor
   → 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
+     3. ⛔ EXECUTE: python3 -m scripts.cli.cli save_daily --content-type keypoint --content '<ESCAPED_JSON>'
+     4. ⛔ EXECUTE: python3 -m scripts.cli.cli record_view
      5. Send audio file via message tool (if audio.composed exists)
      6. Display formatted content to user (REMOVE any [AUDIO:...] tags from text)
   → YES: Check keypoint.generated
-      → TRUE: ⛔ EXECUTE: python3 scripts/state_manager.py record_view, then send audio and display
+      → TRUE: ⛔ EXECUTE: python3 -m scripts.cli.cli record_view, then send audio and display
       → FALSE: Follow steps 1-6 above
 ```
 
@@ -560,6 +582,6 @@ Stored in `state.json`:
 
 | Script | Purpose |
 |--------|---------|
-| command_parser.py | Parse user messages to determine intent |
-| cron_push.py | Handle scheduled content generation |
+| cli/command_parser.py | Parse user messages to determine intent |
+| scheduling/cron_push.py | Handle scheduled content generation |
 

package/package.json

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

package/scripts/__init__.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""
+eng-lang-tutor scripts package
+
+Main entry points:
+- StateManager: Core state persistence
+- Scorer: Quiz evaluation
+- GamificationManager: XP/levels/streaks/badges
+- CommandParser: User command parsing
+- AudioComposer: Audio generation
+"""
+
+from .core.state_manager import StateManager
+from .core.scorer import Scorer
+from .core.gamification import GamificationManager
+from .core.constants import LEVEL_THRESHOLDS, calculate_level, get_level_name, get_streak_multiplier
+from .core.error_notebook import ErrorNotebookManager
+
+__all__ = [
+    'StateManager',
+    'Scorer',
+    'GamificationManager',
+    'ErrorNotebookManager',
+    'LEVEL_THRESHOLDS',
+    'calculate_level',
+    'get_level_name',
+    'get_streak_multiplier',
+]

package/scripts/audio/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""Audio functionality: TTS, composition, conversion, Feishu integration."""
+
+from .composer import AudioComposer, CompositionResult
+from .converter import AudioConverter, ConversionResult, convert_mp3_to_opus
+from .utils import get_ffmpeg_path, get_audio_duration
+from .feishu_voice import FeishuVoiceSender, VoiceSendResult
+from .tts import TTSManager, TTSProvider, TTSResult
+
+__all__ = [
+    'AudioComposer',
+    'CompositionResult',
+    'AudioConverter',
+    'ConversionResult',
+    'convert_mp3_to_opus',
+    'get_ffmpeg_path',
+    'get_audio_duration',
+    'FeishuVoiceSender',
+    'VoiceSendResult',
+    'TTSManager',
+    'TTSProvider',
+    'TTSResult',
+]

package/scripts/{audio_composer.py → audio/composer.py}

@@ -24,10 +24,8 @@ from pathlib import Path
 from typing import Optional, List
 from dataclasses import dataclass
 
-try:
-    from .tts import TTSManager
-except ImportError:
-    from tts import TTSManager
+from .tts import TTSManager
+from .utils import get_ffmpeg_path, get_audio_duration
 
 
 @dataclass
@@ -59,12 +57,7 @@ class AudioComposer:
             ffmpeg_path: ffmpeg 可执行文件路径（默认自动检测）
         """
         self.tts = tts_manager
-        self.ffmpeg_path = ffmpeg_path or shutil.which("ffmpeg")
-        if not self.ffmpeg_path:
-            raise RuntimeError(
-                "ffmpeg not found. Install it with: brew install ffmpeg (macOS) "
-                "or apt-get install ffmpeg (Ubuntu)"
-            )
+        self.ffmpeg_path = ffmpeg_path or get_ffmpeg_path()
 
         # 创建临时目录用于存放中间文件
         self.temp_dir = Path(tempfile.mkdtemp(prefix="audio_composer_"))
@@ -232,7 +225,7 @@ class AudioComposer:
             final_audio = self._concatenate_segments(segments, output_path)
 
             # 5. 获取时长
-            duration = self._get_duration(final_audio)
+            duration = get_audio_duration(final_audio, self.ffmpeg_path)
 
             return CompositionResult(
                 success=True,
@@ -359,31 +352,3 @@ class AudioComposer:
             raise RuntimeError(f"Failed to concatenate audio: {result.stderr}")
 
         return output_path
-
-    def _get_duration(self, audio_path: Path) -> float:
-        """
-        获取音频时长
-
-        Args:
-            audio_path: 音频文件路径
-
-        Returns:
-            时长（秒）
-        """
-        cmd = [
-            self.ffmpeg_path,
-            "-i", str(audio_path),
-            "-hide_banner",
-            "-f", "null",
-            "-"
-        ]
-
-        result = subprocess.run(cmd, capture_output=True, text=True)
-
-        # 从 stderr 中解析时长，格式: "  Duration: 00:00:03.45, ..."
-        import re
-        match = re.search(r"Duration: (\d+):(\d+):(\d+\.?\d*)", result.stderr)
-        if match:
-            hours, minutes, seconds = match.groups()
-            return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
-        return 0.0

package/scripts/{audio_converter.py → audio/converter.py}

@@ -9,11 +9,12 @@
 """
 
 import subprocess
-import shutil
 from pathlib import Path
 from typing import Optional
 from dataclasses import dataclass
 
+from .utils import get_ffmpeg_path, get_audio_duration
+
 
 @dataclass
 class ConversionResult:
@@ -38,12 +39,7 @@ class AudioConverter:
         Args:
             ffmpeg_path: ffmpeg 可执行文件路径（默认自动检测）
         """
-        self.ffmpeg_path = ffmpeg_path or shutil.which("ffmpeg")
-        if not self.ffmpeg_path:
-            raise RuntimeError(
-                "ffmpeg not found. Install it with: brew install ffmpeg (macOS) "
-                "or apt-get install ffmpeg (Ubuntu)"
-            )
+        self.ffmpeg_path = ffmpeg_path or get_ffmpeg_path()
 
     def convert_to_voice(
         self,
@@ -137,7 +133,7 @@ class AudioConverter:
                 )
 
             # 获取音频时长
-            duration = self._get_duration(output_path)
+            duration = get_audio_duration(output_path, self.ffmpeg_path)
 
             return ConversionResult(
                 success=True,
@@ -156,26 +152,6 @@ class AudioConverter:
                 error_message=str(e)
             )
 
-    def _get_duration(self, audio_path: Path) -> float:
-        """获取音频时长（秒）"""
-        cmd = [
-            self.ffmpeg_path,
-            "-i", str(audio_path),
-            "-hide_banner",
-            "-f", "null",
-            "-"
-        ]
-
-        result = subprocess.run(cmd, capture_output=True, text=True)
-
-        # 从 stderr 中解析时长，格式: "  Duration: 00:00:03.45, ..."
-        import re
-        match = re.search(r"Duration: (\d+):(\d+):(\d+\.?\d*)", result.stderr)
-        if match:
-            hours, minutes, seconds = match.groups()
-            return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
-        return 0.0
-
     def batch_convert(
         self,
         input_dir: Path,

package/scripts/{feishu_voice.py → audio/feishu_voice.py}

@@ -30,7 +30,7 @@ from pathlib import Path
 from typing import Optional, Dict, Any, List
 from dataclasses import dataclass
 
-from .audio_converter import AudioConverter, ConversionResult
+from .converter import AudioConverter, ConversionResult
 
 
 @dataclass
@@ -402,20 +402,3 @@ class FeishuVoiceSender:
                     results.append(result)
 
         return results
-
-
-# 同步包装器（用于非异步环境）
-class FeishuVoiceSenderSync:
-    """飞书语音发送器的同步包装"""
-
-    def __init__(self, *args, **kwargs):
-        self._async_sender = FeishuVoiceSender(*args, **kwargs)
-
-    def send_voice(self, *args, **kwargs) -> VoiceSendResult:
-        return asyncio.run(self._async_sender.send_voice(*args, **kwargs))
-
-    def send_voice_from_text(self, *args, **kwargs) -> VoiceSendResult:
-        return asyncio.run(self._async_sender.send_voice_from_text(*args, **kwargs))
-
-    def send_keypoint_voices(self, *args, **kwargs) -> List[VoiceSendResult]:
-        return asyncio.run(self._async_sender.send_keypoint_voices(*args, **kwargs))

package/scripts/{tts → audio/tts}/manager.py

@@ -30,11 +30,15 @@ import os
 import sys
 
 # 添加 scripts 目录到路径以导入 state_manager
-sys.path.insert(0, str(Path(__file__).parent.parent))
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
 
 from .base import TTSProvider, TTSConfig, TTSResult
 from .providers.xunfei import XunFeiProvider
-from state_manager import get_default_state_dir
+
+try:
+    from ...core.state_manager import get_default_state_dir
+except ImportError:
+    from scripts.core.state_manager import get_default_state_dir
 
 
 # Provider 注册表