@rookiestar/eng-lang-tutor 1.0.2 → 1.0.4

package/scripts/cli.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+CLI interface for eng-lang-tutor state management.
+
+This module provides command-line access to state management operations.
+"""
+
+import argparse
+import json
+from datetime import datetime
+from typing import Optional
+
+from state_manager import StateManager
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(description="State Manager for eng-lang-tutor")
+    parser.add_argument('--data-dir', default=None,
+                        help='Data directory path (default: ~/.openclaw/state/eng-lang-tutor or OPENCLAW_STATE_DIR env)')
+    parser.add_argument('command', nargs='?',
+                        choices=['show', 'backup', 'save_daily', 'record_view',
+                                 'stats', 'config', 'errors', 'schedule',
+                                 'generate_audio'],
+                        help='Command to execute')
+    parser.add_argument('--content-type', help='Content type for save_daily (keypoint, quiz)')
+    parser.add_argument('--content', help='JSON content for save_daily')
+    parser.add_argument('--date', help='Date for content (YYYY-MM-DD format)')
+    # Errors command options
+    parser.add_argument('--page', type=int, default=1, help='Page number for errors list')
+    parser.add_argument('--per-page', type=int, default=5, help='Items per page for errors')
+    parser.add_argument('--month', help='Filter errors by month (YYYY-MM)')
+    parser.add_argument('--random', type=int, help='Get N random errors')
+    parser.add_argument('--stats', action='store_true', help='Get error statistics')
+    parser.add_argument('--review', type=int, help='Get N errors for review session')
+    # Config command options
+    parser.add_argument('--cefr', help='Set CEFR level (A1-C2)')
+    parser.add_argument('--style', help='Set tutor style')
+    parser.add_argument('--oral-ratio', type=int, help='Set oral/written ratio (0-100)')
+    # Schedule command options
+    parser.add_argument('--keypoint-time', help='Set keypoint push time (HH:MM)')
+    parser.add_argument('--quiz-time', help='Set quiz push time (HH:MM)')
+
+    args = parser.parse_args()
+
+    sm = StateManager(args.data_dir)
+
+    if args.command == 'show' or not args.command:
+        state = sm.load_state()
+        print(json.dumps(state, indent=2, ensure_ascii=False))
+
+    elif args.command == 'backup':
+        backup_path = sm.backup_state()
+        print(f"Backup created: {backup_path}")
+
+    elif args.command == 'save_daily':
+        if not args.content_type or not args.content:
+            print("Error: --content-type and --content are required for save_daily")
+            exit(1)
+
+        try:
+            content = json.loads(args.content)
+        except json.JSONDecodeError as e:
+            print(f"Error: Invalid JSON content: {e}")
+            exit(1)
+
+        target_date = None
+        if args.date:
+            try:
+                target_date = datetime.strptime(args.date, '%Y-%m-%d').date()
+            except ValueError:
+                print("Error: Invalid date format. Use YYYY-MM-DD")
+                exit(1)
+
+        path = sm.save_daily_content(args.content_type, content, target_date)
+        print(f"Saved to: {path}")
+
+    elif args.command == 'record_view':
+        target_date = None
+        if args.date:
+            try:
+                target_date = datetime.strptime(args.date, '%Y-%m-%d').date()
+            except ValueError:
+                print("Error: Invalid date format. Use YYYY-MM-DD")
+                exit(1)
+
+        state = sm.load_state()
+        sm.record_keypoint_view(state, target_date)
+        sm.save_state(state)
+        print("View recorded successfully")
+
+    elif args.command == 'stats':
+        """Display learning progress summary."""
+        from gamification import GamificationManager
+        state = sm.load_state()
+        gm = GamificationManager()
+        summary = gm.get_progress_summary(state)
+        print(json.dumps(summary, indent=2, ensure_ascii=False))
+
+    elif args.command == 'config':
+        """Display or update user configuration."""
+        state = sm.load_state()
+
+        # If no update options, just show current config
+        if not any([args.cefr, args.style, args.oral_ratio is not None]):
+            config = {
+                "cefr_level": state.get("preferences", {}).get("cefr_level", "B1"),
+                "tutor_style": state.get("preferences", {}).get("tutor_style", "humorous"),
+                "oral_ratio": state.get("preferences", {}).get("oral_ratio", 70),
+                "topic_weights": state.get("preferences", {}).get("topic_weights", {}),
+                "schedule": state.get("schedule", {})
+            }
+            print(json.dumps(config, indent=2, ensure_ascii=False))
+        else:
+            # Update configuration
+            if args.cefr:
+                if args.cefr not in ['A1', 'A2', 'B1', 'B2', 'C1', 'C2']:
+                    print("Error: Invalid CEFR level. Must be A1, A2, B1, B2, C1, or C2")
+                    exit(1)
+                state = sm.update_preferences(state, cefr_level=args.cefr)
+                print(f"Updated CEFR level to: {args.cefr}")
+
+            if args.style:
+                if args.style not in ['humorous', 'rigorous', 'casual', 'professional']:
+                    print("Error: Invalid style. Must be humorous, rigorous, casual, or professional")
+                    exit(1)
+                state = sm.update_preferences(state, tutor_style=args.style)
+                print(f"Updated tutor style to: {args.style}")
+
+            if args.oral_ratio is not None:
+                if not 0 <= args.oral_ratio <= 100:
+                    print("Error: Oral ratio must be between 0 and 100")
+                    exit(1)
+                state = sm.update_preferences(state, oral_ratio=args.oral_ratio)
+                print(f"Updated oral ratio to: {args.oral_ratio}%")
+
+            sm.save_state(state)
+            print("Configuration updated successfully")
+
+    elif args.command == 'errors':
+        """Error notebook operations."""
+        state = sm.load_state()
+
+        if args.stats:
+            # Get error statistics
+            stats = sm.get_error_stats(state)
+            print(json.dumps(stats, indent=2, ensure_ascii=False))
+
+        elif args.review is not None:
+            # Get errors for review session
+            errors = sm.get_review_errors(state, count=args.review)
+            result = {
+                "count": len(errors),
+                "errors": errors
+            }
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+
+        else:
+            # Get paginated errors list
+            result = sm.get_errors_page(
+                state,
+                page=args.page,
+                per_page=args.per_page,
+                month=args.month,
+                random=args.random
+            )
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    elif args.command == 'schedule':
+        """Display or update schedule configuration."""
+        state = sm.load_state()
+
+        # If no update options, just show current schedule
+        if not any([args.keypoint_time, args.quiz_time]):
+            schedule = state.get("schedule", {})
+            print(json.dumps(schedule, indent=2, ensure_ascii=False))
+        else:
+            # Validate quiz_time must be later than keypoint_time
+            current_keypoint = state.get("schedule", {}).get("keypoint_time", "06:45")
+            current_quiz = state.get("schedule", {}).get("quiz_time", "22:45")
+
+            new_keypoint = args.keypoint_time or current_keypoint
+            new_quiz = args.quiz_time or current_quiz
+
+            # Time validation
+            def parse_time(t):
+                h, m = map(int, t.split(':'))
+                return h * 60 + m
+
+            if parse_time(new_quiz) <= parse_time(new_keypoint):
+                print("Error: Quiz time must be later than keypoint time")
+                exit(1)
+
+            state = sm.update_schedule(
+                state,
+                keypoint_time=new_keypoint,
+                quiz_time=new_quiz
+            )
+            sm.save_state(state)
+            print(f"Schedule updated: keypoint at {new_keypoint}, quiz at {new_quiz}")
+
+    elif args.command == 'generate_audio':
+        """Generate audio for a keypoint."""
+        target_date = None
+        if args.date:
+            try:
+                target_date = datetime.strptime(args.date, '%Y-%m-%d').date()
+            except ValueError:
+                print("Error: Invalid date format. Use YYYY-MM-DD")
+                exit(1)
+
+        result = sm.generate_keypoint_audio(target_date)
+
+        if result.get('success'):
+            print(f"Audio generated: {result.get('audio_path')}")
+            print(f"Duration: {result.get('duration_seconds', 0):.1f} seconds")
+        else:
+            print(f"Failed to generate audio: {result.get('error_message')}")
+            exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/constants.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""
+Shared constants for eng-lang-tutor.
+
+This module contains constants used across multiple scripts to avoid duplication.
+"""
+
+# Level thresholds (XP needed for each level)
+# Note: Level is Activity Level (活跃等级), measuring engagement depth,
+# NOT language ability (which is CEFR level A1-C2)
+LEVEL_THRESHOLDS = [
+    0, 50, 100, 200, 350,       # 1-5 Starter (启程者)
+    550, 800, 1100, 1500, 2000,  # 6-10 Traveler (行路人)
+    2600, 3300, 4100, 5000, 6000,  # 11-15 Explorer (探索者)
+    7200, 8500, 10000, 12000, 15000  # 16-20 Pioneer (开拓者)
+]
+
+# Level range to name mapping
+LEVEL_NAMES = {
+    (1, 5): "Starter",      # 启程者
+    (6, 10): "Traveler",    # 行路人
+    (11, 15): "Explorer",   # 探索者
+    (16, 20): "Pioneer"     # 开拓者
+}
+
+
+def get_level_name(level: int) -> str:
+    """
+    Get the journey stage name for a level.
+
+    Args:
+        level: Activity level (1-20)
+
+    Returns:
+        Stage name (Starter/Traveler/Explorer/Pioneer)
+    """
+    for (min_level, max_level), name in LEVEL_NAMES.items():
+        if min_level <= level <= max_level:
+            return name
+    return "Unknown"
+
+
+def calculate_level(xp: int) -> int:
+    """
+    Calculate level from total XP.
+
+    Args:
+        xp: Total experience points
+
+    Returns:
+        Level (1-20)
+    """
+    for i in range(len(LEVEL_THRESHOLDS) - 1, -1, -1):
+        if xp >= LEVEL_THRESHOLDS[i]:
+            return i + 1
+    return 1

package/scripts/feishu_voice.py

@@ -0,0 +1,421 @@
+#!/usr/bin/env python3
+"""
+飞书语音消息发送模块
+
+将 TTS 生成的音频转换为飞书语音格式并发送。
+
+使用示例：
+    from scripts.feishu_voice import FeishuVoiceSender
+
+    sender = FeishuVoiceSender(app_id="xxx", app_secret="xxx")
+
+    # 发送单条语音
+    await sender.send_voice(
+        receive_id="ou_xxx",
+        text="Hello, nice to meet you!"
+    )
+
+    # 发送知识点音频
+    await sender.send_keypoint_voices(
+        receive_id="ou_xxx",
+        keypoint=keypoint,
+        audio_info=audio_info
+    )
+"""
+
+import os
+import asyncio
+import aiohttp
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass
+
+from .audio_converter import AudioConverter, ConversionResult
+
+
+@dataclass
+class VoiceSendResult:
+    """语音发送结果"""
+    success: bool
+    message_id: Optional[str] = None
+    error_message: Optional[str] = None
+
+
+class FeishuVoiceSender:
+    """
+    飞书语音消息发送器
+
+    工作流程：
+    1. TTS 生成 MP3 音频
+    2. 转换为 Opus 格式（飞书推荐）
+    3. 上传到飞书素材库
+    4. 发送语音消息
+    """
+
+    FEISHU_API_BASE = "https://open.feishu.cn/open-apis"
+
+    def __init__(
+        self,
+        app_id: Optional[str] = None,
+        app_secret: Optional[str] = None,
+        tenant_key: Optional[str] = None,
+        audio_dir: Optional[Path] = None
+    ):
+        """
+        初始化飞书语音发送器
+
+        Args:
+            app_id: 飞书应用 ID（可从环境变量 FEISHU_APP_ID 读取）
+            app_secret: 飞书应用密钥（可从环境变量 FEISHU_APP_SECRET 读取）
+            tenant_key: 租户密钥（自建应用无需）
+            audio_dir: 音频缓存目录
+        """
+        self.app_id = app_id or os.getenv("FEISHU_APP_ID")
+        self.app_secret = app_secret or os.getenv("FEISHU_APP_SECRET")
+        self.tenant_key = tenant_key
+
+        if not self.app_id or not self.app_secret:
+            raise ValueError(
+                "Missing Feishu credentials. Set FEISHU_APP_ID and FEISHU_APP_SECRET "
+                "environment variables or pass them to constructor."
+            )
+
+        self.audio_dir = audio_dir or Path(
+            os.getenv("OPENCLAW_STATE_DIR", "~/.openclaw/state/eng-lang-tutor")
+        ).expanduser() / "audio"
+        self.audio_dir.mkdir(parents=True, exist_ok=True)
+
+        self.converter = AudioConverter()
+        self._access_token: Optional[str] = None
+        self._token_expires: float = 0
+
+    async def _get_access_token(self) -> str:
+        """获取飞书访问令牌"""
+        import time
+
+        # 检查缓存
+        if self._access_token and time.time() < self._token_expires:
+            return self._access_token
+
+        url = f"{self.FEISHU_API_BASE}/auth/v3/tenant_access_token/internal"
+        headers = {"Content-Type": "application/json"}
+        data = {
+            "app_id": self.app_id,
+            "app_secret": self.app_secret
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, headers=headers, json=data) as resp:
+                result = await resp.json()
+
+                if result.get("code") != 0:
+                    raise RuntimeError(f"Failed to get access token: {result}")
+
+                self._access_token = result["tenant_access_token"]
+                self._token_expires = time.time() + result.get("expire", 7200) - 300
+
+                return self._access_token
+
+    async def _upload_file(self, file_path: Path, file_type: str = "opus") -> str:
+        """
+        上传文件到飞书素材库
+
+        Args:
+            file_path: 文件路径
+            file_type: 文件类型
+
+        Returns:
+            file_key
+        """
+        token = await self._get_access_token()
+
+        url = f"{self.FEISHU_API_BASE}/im/v1/files"
+        headers = {"Authorization": f"Bearer {token}"}
+
+        async with aiohttp.ClientSession() as session:
+            with open(file_path, "rb") as f:
+                form = aiohttp.FormData()
+                form.add_field("file_type", file_type)
+                form.add_field("file_name", file_path.name)
+                form.add_field("file", f, filename=file_path.name)
+
+                async with session.post(url, headers=headers, data=form) as resp:
+                    result = await resp.json()
+
+                    if result.get("code") != 0:
+                        raise RuntimeError(f"Failed to upload file: {result}")
+
+                    return result["data"]["file_key"]
+
+    async def _send_file_message(
+        self,
+        receive_id: str,
+        file_key: str,
+        receive_id_type: str = "open_id"
+    ) -> str:
+        """
+        发送文件消息
+
+        Args:
+            receive_id: 接收者 ID
+            file_key: 文件 key
+            receive_id_type: 接收者 ID 类型
+
+        Returns:
+            message_id
+        """
+        token = await self._get_access_token()
+
+        url = f"{self.FEISHU_API_BASE}/im/v1/messages"
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json"
+        }
+        params = {
+            "receive_id_type": receive_id_type
+        }
+        data = {
+            "receive_id": receive_id,
+            "msg_type": "file",
+            "content": f'{{"file_key": "{file_key}"}}'
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, headers=headers, params=params, json=data) as resp:
+                result = await resp.json()
+
+                if result.get("code") != 0:
+                    raise RuntimeError(f"Failed to send message: {result}")
+
+                return result["data"]["message_id"]
+
+    async def send_voice(
+        self,
+        receive_id: str,
+        audio_path: Path,
+        receive_id_type: str = "open_id",
+        auto_convert: bool = True,
+        delete_after_send: bool = False
+    ) -> VoiceSendResult:
+        """
+        发送语音消息
+
+        Args:
+            receive_id: 接收者 ID（open_id / user_id / union_id）
+            audio_path: 音频文件路径（MP3 或 Opus）
+            receive_id_type: 接收者 ID 类型
+            auto_convert: 是否自动转换为 Opus 格式
+            delete_after_send: 发送后是否删除临时文件
+
+        Returns:
+            VoiceSendResult
+        """
+        audio_path = Path(audio_path)
+        temp_file = None
+
+        try:
+            # 如果是 MP3，转换为 Opus
+            if auto_convert and audio_path.suffix.lower() == ".mp3":
+                opus_path = audio_path.with_suffix(".opus")
+                result = self.converter.convert_to_voice(
+                    input_path=audio_path,
+                    output_path=opus_path,
+                    format="opus",
+                    sample_rate=16000
+                )
+                if not result.success:
+                    return VoiceSendResult(
+                        success=False,
+                        error_message=f"Audio conversion failed: {result.error_message}"
+                    )
+                audio_path = opus_path
+                temp_file = opus_path if delete_after_send else None
+
+            # 上传文件
+            file_key = await self._upload_file(audio_path)
+
+            # 发送消息
+            message_id = await self._send_file_message(
+                receive_id=receive_id,
+                file_key=file_key,
+                receive_id_type=receive_id_type
+            )
+
+            return VoiceSendResult(
+                success=True,
+                message_id=message_id
+            )
+
+        except Exception as e:
+            return VoiceSendResult(
+                success=False,
+                error_message=str(e)
+            )
+        finally:
+            # 清理临时文件
+            if temp_file and temp_file.exists():
+                temp_file.unlink()
+
+    async def send_voice_from_text(
+        self,
+        receive_id: str,
+        text: str,
+        voice: str = "catherine",
+        speed: float = 0.9,
+        receive_id_type: str = "open_id"
+    ) -> VoiceSendResult:
+        """
+        从文本直接生成并发送语音
+
+        Args:
+            receive_id: 接收者 ID
+            text: 要转换的文本
+            voice: 音色
+            speed: 语速
+            receive_id_type: 接收者 ID 类型
+
+        Returns:
+            VoiceSendResult
+        """
+        from .tts import TTSManager
+
+        try:
+            # 生成 TTS 音频
+            manager = TTSManager.from_env()
+            output_path = self.audio_dir / f"temp_{hash(text)}.mp3"
+
+            result = manager.synthesize(
+                text=text,
+                output_path=output_path,
+                voice=voice,
+                speed=speed
+            )
+
+            if not result.success:
+                return VoiceSendResult(
+                    success=False,
+                    error_message=f"TTS failed: {result.error_message}"
+                )
+
+            # 发送语音
+            return await self.send_voice(
+                receive_id=receive_id,
+                audio_path=output_path,
+                receive_id_type=receive_id_type,
+                auto_convert=True,
+                delete_after_send=True
+            )
+
+        except Exception as e:
+            return VoiceSendResult(
+                success=False,
+                error_message=str(e)
+            )
+
+    async def send_keypoint_voices(
+        self,
+        receive_id: str,
+        keypoint: Dict[str, Any],
+        audio_info: Dict[str, Any],
+        receive_id_type: str = "open_id",
+        include_dialogue: bool = True,
+        include_expressions: bool = True
+    ) -> List[VoiceSendResult]:
+        """
+        发送知识点的所有语音
+
+        Args:
+            receive_id: 接收者 ID
+            keypoint: 知识点数据
+            audio_info: TTS 生成的音频信息
+            receive_id_type: 接收者 ID 类型
+            include_dialogue: 是否发送对话音频
+            include_expressions: 是否发送表达音频
+
+        Returns:
+            发送结果列表
+        """
+        results = []
+        date_str = audio_info.get("generated_at", "")[:10]  # YYYY-MM-DD
+
+        # 发送对话音频
+        if include_dialogue:
+            for item in audio_info.get("dialogue", []):
+                if "error" in item:
+                    results.append(VoiceSendResult(
+                        success=False,
+                        error_message=f"Dialogue generation failed: {item['error']}"
+                    ))
+                    continue
+
+                audio_url = item.get("audio_url", "")
+                if not audio_url:
+                    continue
+
+                # 解析路径：audio/YYYY-MM-DD/filename.opus
+                parts = audio_url.split("/")
+                audio_path = self.audio_dir / parts[1] / parts[2]
+
+                if not audio_path.exists():
+                    # 尝试 MP3 扩展名
+                    audio_path = audio_path.with_suffix(".mp3")
+
+                if audio_path.exists():
+                    speaker = item.get("speaker", "")
+                    text = item.get("text", "")
+
+                    result = await self.send_voice(
+                        receive_id=receive_id,
+                        audio_path=audio_path,
+                        receive_id_type=receive_id_type,
+                        auto_convert=True
+                    )
+                    results.append(result)
+
+        # 发送表达音频
+        if include_expressions:
+            for item in audio_info.get("expressions", []):
+                if "error" in item:
+                    results.append(VoiceSendResult(
+                        success=False,
+                        error_message=f"Expression generation failed: {item['error']}"
+                    ))
+                    continue
+
+                audio_url = item.get("audio_url", "")
+                if not audio_url:
+                    continue
+
+                parts = audio_url.split("/")
+                audio_path = self.audio_dir / parts[1] / parts[2]
+
+                if not audio_path.exists():
+                    audio_path = audio_path.with_suffix(".mp3")
+
+                if audio_path.exists():
+                    result = await self.send_voice(
+                        receive_id=receive_id,
+                        audio_path=audio_path,
+                        receive_id_type=receive_id_type,
+                        auto_convert=True
+                    )
+                    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))