@rookiestar/eng-lang-tutor 1.0.1 → 1.2.4

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.4] - 2026-02-27
+
+### Fixed
+- **TTS voice selection**: Audio composer now automatically selects appropriate voices based on TTS provider
+  - Edge-TTS: `en-US-JennyNeural`, `en-US-EricNeural`
+  - XunFei: `catherine`, `henry`
+- **CLI import paths**: Fixed broken imports in `state_manager.py` CLI module
+
+### Changed
+- **npm package**: Removed automatic `pip install` from postinstall script
+  - Added `eng-lang-tutor-setup` CLI tool for manual dependency installation
+  - Supports `--venv`, `--user`, and `--check` options
+- **Test coverage**: Added 38 new tests covering:
+  - `scripts/audio/utils.py` (6 tests)
+  - `scripts/audio/converter.py` (16 tests)
+  - `scripts/utils/helpers.py` (16 tests)
+- **Test fixes**: Fixed pre-existing test failures in CLI and TTS modules
+
+## [1.2.3] - 2026-02-27
+
+### Changed
+- Version bump for npm publishing
+
+## [1.2.0] - 2026-02-27
+
+### Changed
+- Initial npm package setup
+
+## [1.0.1] - 2025-02-27
+
+### Fixed
+- **TTS voice selection**: Audio composer now automatically selects appropriate voices based on TTS provider
+  - Edge-TTS: `en-US-JennyNeural`, `en-US-EricNeural`
+  - XunFei: `catherine`, `henry`
+- **CLI import paths**: Fixed broken imports in `state_manager.py` CLI module
+
+### Changed
+- **npm package**: Removed automatic `pip install` from postinstall script
+  - Added `eng-lang-tutor-setup` CLI tool for manual dependency installation
+  - Supports `--venv`, `--user`, and `--check` options
+- **Test coverage**: Added 38 new tests covering:
+  - `scripts/audio/utils.py` (6 tests)
+  - `scripts/audio/converter.py` (16 tests)
+  - `scripts/utils/helpers.py` (16 tests)
+- **Test fixes**: Fixed pre-existing test failures in CLI and TTS modules
+
+## [1.0.1] - 2025-02-27
+
+### Changed
+- Version bump for npm publishing (1.0.0 was previously unpublished)
+
 ## [1.0.0] - 2025-02-26
 
 Initial release.

package/README.md

@@ -37,10 +37,21 @@ sudo apt-get install ffmpeg python3 python3-venv
 **方式一：npm 安装（推荐）**
 
 ```bash
+# 1. Install the npm package
 npm install -g @rookiestar/eng-lang-tutor
-```
 
-安装会自动执行，skill 将被安装到 `~/.openclaw/skills/eng-lang-tutor/`。
+# 2. Install Python dependencies (choose one method)
+
+# Option A: Using virtual environment (recommended)
+eng-lang-tutor-setup --venv
+# Then activate before using: source ~/.venvs/eng-lang-tutor/bin/activate
+
+# Option B: Install to user directory
+eng-lang-tutor-setup --user
+
+# Option C: Check if dependencies are already installed
+eng-lang-tutor-setup --check
+```
 
 **方式二：从源码安装**
 
@@ -57,12 +68,13 @@ pip install -r eng-lang-tutor/requirements.txt
 **手动安装依赖（如需要）：**
 
 ```bash
-# 创建 Python 虚拟环境
+# 使用 setup 脚本（推荐）
+eng-lang-tutor-setup --venv ~/.venvs/eng-lang-tutor
+
+# 或手动创建虚拟环境
 python3 -m venv ~/.venvs/eng-lang-tutor
 source ~/.venvs/eng-lang-tutor/bin/activate  # Linux/macOS
-
-# 安装依赖
-pip install -r ~/.openclaw/skills/eng-lang-tutor/requirements.txt
+pip install -r $(npm root -g)/@rookiestar/eng-lang-tutor/requirements.txt
 ```
 
 **验证安装：**
@@ -265,6 +277,7 @@ eng-lang-tutor/
 │   ├── cli/                    # 命令行模块
 │   │   ├── cli.py              # CLI 入口点
 │   │   └── command_parser.py   # 用户命令解析
+│   ├── setup.py                # 依赖安装脚本 (npm bin)
 │   ├── scheduling/             # 调度模块
 │   │   └── cron_push.py        # 定时内容推送
 │   ├── utils/                  # 工具模块

package/backups/state_backup_20260227_063358.json

@@ -0,0 +1,47 @@
+{
+  "version": 2,
+  "initialized": false,
+  "onboarding_step": 0,
+  "completion_status": {
+    "quiz_completed_date": null,
+    "keypoint_view_history": []
+  },
+  "schedule": {
+    "keypoint_time": "06:45",
+    "quiz_time": "22:45",
+    "timezone": "Asia/Shanghai"
+  },
+  "user": {
+    "xp": 0,
+    "level": 1,
+    "streak": 0,
+    "streak_freeze": 0,
+    "gems": 0,
+    "badges": []
+  },
+  "preferences": {
+    "cefr_level": "B1",
+    "oral_written_ratio": 0.7,
+    "topics": {
+      "movies": 0.2,
+      "news": 0.15,
+      "gaming": 0.15,
+      "sports": 0.1,
+      "workplace": 0.2,
+      "social": 0.1,
+      "daily_life": 0.1
+    },
+    "tutor_style": "humorous",
+    "dedup_days": 14
+  },
+  "progress": {
+    "total_quizzes": 0,
+    "correct_rate": 0.0,
+    "last_study_date": null,
+    "perfect_quizzes": 0,
+    "expressions_learned": 0
+  },
+  "recent_topics": [],
+  "error_notebook": [],
+  "error_archive": []
+}

package/backups/state_backup_20260227_063405.json

@@ -0,0 +1,47 @@
+{
+  "version": 2,
+  "initialized": false,
+  "onboarding_step": 0,
+  "completion_status": {
+    "quiz_completed_date": null,
+    "keypoint_view_history": []
+  },
+  "schedule": {
+    "keypoint_time": "06:45",
+    "quiz_time": "22:45",
+    "timezone": "Asia/Shanghai"
+  },
+  "user": {
+    "xp": 0,
+    "level": 1,
+    "streak": 0,
+    "streak_freeze": 0,
+    "gems": 0,
+    "badges": []
+  },
+  "preferences": {
+    "cefr_level": "B1",
+    "oral_written_ratio": 0.7,
+    "topics": {
+      "movies": 0.2,
+      "news": 0.15,
+      "gaming": 0.15,
+      "sports": 0.1,
+      "workplace": 0.2,
+      "social": 0.1,
+      "daily_life": 0.1
+    },
+    "tutor_style": "humorous",
+    "dedup_days": 14
+  },
+  "progress": {
+    "total_quizzes": 0,
+    "correct_rate": 0.0,
+    "last_study_date": null,
+    "perfect_quizzes": 0,
+    "expressions_learned": 0
+  },
+  "recent_topics": [],
+  "error_notebook": [],
+  "error_archive": []
+}

package/backups/state_backup_20260227_064016.json

@@ -0,0 +1,47 @@
+{
+  "version": 2,
+  "initialized": false,
+  "onboarding_step": 0,
+  "completion_status": {
+    "quiz_completed_date": null,
+    "keypoint_view_history": []
+  },
+  "schedule": {
+    "keypoint_time": "06:45",
+    "quiz_time": "22:45",
+    "timezone": "Asia/Shanghai"
+  },
+  "user": {
+    "xp": 0,
+    "level": 1,
+    "streak": 0,
+    "streak_freeze": 0,
+    "gems": 0,
+    "badges": []
+  },
+  "preferences": {
+    "cefr_level": "B1",
+    "oral_written_ratio": 0.7,
+    "topics": {
+      "movies": 0.2,
+      "news": 0.15,
+      "gaming": 0.15,
+      "sports": 0.1,
+      "workplace": 0.2,
+      "social": 0.1,
+      "daily_life": 0.1
+    },
+    "tutor_style": "humorous",
+    "dedup_days": 14
+  },
+  "progress": {
+    "total_quizzes": 0,
+    "correct_rate": 0.0,
+    "last_study_date": null,
+    "perfect_quizzes": 0,
+    "expressions_learned": 0
+  },
+  "recent_topics": [],
+  "error_notebook": [],
+  "error_archive": []
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@rookiestar/eng-lang-tutor",
-  "version": "1.0.1",
+  "version": "1.2.4",
   "description": "地道美式英语导师 - OpenClaw Skill for learning authentic American English",
   "main": "scripts/cli/cli.py",
-  "scripts": {
-    "postinstall": "python3 -m pip install -r requirements.txt --quiet"
+  "bin": {
+    "eng-lang-tutor-setup": "scripts/setup.py"
   },
   "keywords": [
     "english",

package/scripts/audio/composer.py

@@ -87,9 +87,9 @@ class AudioComposer:
         lead_in_silence: float = 1.0,   # 引导语后留白
         section_silence: float = 2.0,   # 内容后留白（段落间隔）
         dialogue_silence: float = 0.5,  # 对话行之间留白
-        narrator_voice: str = "henry",  # 旁白音色（男声）
-        voice_a: str = "mary",          # 对话 A 音色（女声）
-        voice_b: str = "henry",         # 对话 B 音色（男声，沉稳）
+        narrator_voice: str = None,     # 旁白音色（None 时使用 TTS provider 默认值）
+        voice_a: str = None,            # 对话 A 音色（None 时使用 TTS provider 默认值）
+        voice_b: str = None,            # 对话 B 音色（None 时使用 TTS provider 默认值）
         speed: float = 0.9              # 语速
     ) -> CompositionResult:
         """
@@ -110,6 +110,11 @@ class AudioComposer:
             CompositionResult: 合成结果
         """
         try:
+            # 使用 TTS provider 的默认音色（自动适配 Edge-TTS 或讯飞）
+            narrator_voice = narrator_voice or self.tts.get_voice_by_role("narrator")
+            voice_a = voice_a or self.tts.get_voice_by_role("dialogue_a")
+            voice_b = voice_b or self.tts.get_voice_by_role("dialogue_b")
+
             output_path = Path(output_path)
             output_path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -213,7 +218,7 @@ class AudioComposer:
                             if not text:
                                 continue
 
-                            # A = henry (男声), B = catherine (女声)
+                            # A = EricNeural (男声), B = JennyNeural (女声)
                             voice = voice_a if speaker.upper() == "A" else voice_b
 
                             segment = self._synthesize_segment(

package/scripts/core/state_manager.py

@@ -810,5 +810,8 @@ class StateManager:
 
 # CLI interface - delegated to cli.py for better code organization
 if __name__ == "__main__":
-    from cli import main
+    try:
+        from ..cli.cli import main
+    except ImportError:
+        from scripts.cli.cli import main
     main()

package/scripts/setup.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""
+Setup script for eng-lang-tutor skill.
+Installs Python dependencies with support for virtual environments.
+
+Usage:
+    eng-lang-tutor-setup              # Install dependencies
+    eng-lang-tutor-setup --venv       # Create venv and install
+    eng-lang-tutor-setup --check      # Check dependencies only
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def get_package_dir() -> Path:
+    """Get the package directory containing requirements.txt."""
+    # When installed via npm, the script is symlinked in node_modules/.bin/
+    # We need to find the actual package directory
+    script_path = Path(__file__).resolve()
+
+    # Check if we're in a typical npm global install location
+    if "node_modules" in str(script_path):
+        # Navigate to the package root
+        parts = script_path.parts
+        for i, part in enumerate(parts):
+            if part == "node_modules":
+                # Find the package directory (usually @scope/package or just package)
+                remaining = parts[i + 1 :]
+                if remaining and remaining[0].startswith("@"):
+                    # Scoped package: @rookiestar/eng-lang-tutor
+                    pkg_dir = Path(*parts[: i + 3])
+                else:
+                    # Unscoped package
+                    pkg_dir = Path(*parts[: i + 2])
+                return pkg_dir
+
+    # Fallback: assume script is in scripts/ directory
+    return script_path.parent.parent
+
+
+def check_dependencies() -> tuple[bool, list[str]]:
+    """Check if all required dependencies are installed."""
+    missing = []
+    required = ["websocket", "certifi", "aiohttp", "edge_tts"]
+
+    for module in required:
+        try:
+            __import__(module)
+        except ImportError:
+            missing.append(module)
+
+    return len(missing) == 0, missing
+
+
+def install_dependencies(
+    requirements_path: Path, venv_path: Path | None = None, user: bool = False
+) -> bool:
+    """Install dependencies from requirements.txt."""
+    if not requirements_path.exists():
+        print(f"Error: requirements.txt not found at {requirements_path}")
+        return False
+
+    pip_cmd = [sys.executable, "-m", "pip", "install", "-r", str(requirements_path)]
+
+    if venv_path:
+        pip_cmd = [str(venv_path / "bin" / "pip"), "install", "-r", str(requirements_path)]
+    elif user:
+        pip_cmd.append("--user")
+
+    try:
+        print(f"Installing dependencies from {requirements_path}...")
+        subprocess.run(pip_cmd, check=True)
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"Error installing dependencies: {e}")
+        return False
+
+
+def create_venv(venv_path: Path) -> bool:
+    """Create a virtual environment."""
+    try:
+        print(f"Creating virtual environment at {venv_path}...")
+        subprocess.run([sys.executable, "-m", "venv", str(venv_path)], check=True)
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"Error creating virtual environment: {e}")
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Setup script for eng-lang-tutor skill"
+    )
+    parser.add_argument(
+        "--venv",
+        metavar="PATH",
+        nargs="?",
+        const="~/.venvs/eng-lang-tutor",
+        help="Create a virtual environment and install dependencies (default: ~/.venvs/eng-lang-tutor)",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Check if dependencies are installed without installing",
+    )
+    parser.add_argument(
+        "--user",
+        action="store_true",
+        help="Install dependencies to user directory (use with --break-system-packages if needed)",
+    )
+
+    args = parser.parse_args()
+
+    pkg_dir = get_package_dir()
+    requirements_path = pkg_dir / "requirements.txt"
+
+    # Check mode
+    if args.check:
+        ok, missing = check_dependencies()
+        if ok:
+            print("All dependencies are installed.")
+            sys.exit(0)
+        else:
+            print(f"Missing dependencies: {', '.join(missing)}")
+            print("Run this script without --check to install them.")
+            sys.exit(1)
+
+    # Venv mode
+    if args.venv:
+        venv_path = Path(args.venv).expanduser().resolve()
+
+        if not (venv_path / "bin" / "python").exists():
+            if not create_venv(venv_path):
+                sys.exit(1)
+
+        if install_dependencies(requirements_path, venv_path=venv_path):
+            print(f"\nSuccess! Virtual environment created at {venv_path}")
+            print(f"To activate it, run: source {venv_path}/bin/activate")
+            sys.exit(0)
+        else:
+            sys.exit(1)
+
+    # Direct install mode
+    if install_dependencies(requirements_path, user=args.user):
+        print("\nDependencies installed successfully!")
+        sys.exit(0)
+    else:
+        print("\nInstallation failed. Try one of these alternatives:")
+        print("  1. Create a virtual environment: eng-lang-tutor-setup --venv")
+        print("  2. Install to user directory: eng-lang-tutor-setup --user")
+        print("  3. If you understand the risks: pip install -r requirements.txt --break-system-packages")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()