@rookiestar/eng-lang-tutor 1.0.3 → 1.0.4

package/package.json

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

package/requirements.txt

@@ -1,5 +1,7 @@
 # Core dependencies
 websocket-client>=1.6.0  # For XunFei TTS WebSocket API
+certifi>=2024.0.0        # SSL certificate bundle for HTTPS/WebSocket connections
+aiohttp>=3.8.0           # Async HTTP client for Feishu API
 
 # Optional: Edge-TTS support (uncomment if needed)
 # edge-tts>=6.1.0

package/scripts/audio_composer.py

@@ -0,0 +1,389 @@
+#!/usr/bin/env python3
+"""
+知识点音频合成器 - 将多个音频片段合并为单个文件
+
+音频结构：
+- expressions: 引导语 [1s] 内容 [2s]
+- alternatives: 引导语 [1s] 内容 [2s]
+- dialogues: 引导语 [1s] 对话行1 [0.5s] 对话行2 ...
+
+使用示例：
+    from scripts.audio_composer import AudioComposer
+    from scripts.tts import TTSManager
+
+    tts = TTSManager.from_env()
+    composer = AudioComposer(tts)
+
+    result = composer.compose_keypoint_audio(keypoint, Path("output.mp3"))
+"""
+
+import subprocess
+import tempfile
+import shutil
+from pathlib import Path
+from typing import Optional, List
+from dataclasses import dataclass
+
+try:
+    from .tts import TTSManager
+except ImportError:
+    from tts import TTSManager
+
+
+@dataclass
+class CompositionResult:
+    """音频合成结果"""
+    success: bool
+    audio_path: Optional[Path] = None
+    duration_seconds: Optional[float] = None
+    error_message: Optional[str] = None
+
+
+class AudioComposer:
+    """
+    知识点音频合成器
+
+    将 expressions + alternatives + dialogues 合并为单个音频文件
+    """
+
+    def __init__(
+        self,
+        tts_manager: TTSManager,
+        ffmpeg_path: Optional[str] = None
+    ):
+        """
+        初始化音频合成器
+
+        Args:
+            tts_manager: TTS 管理器实例
+            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.temp_dir = Path(tempfile.mkdtemp(prefix="audio_composer_"))
+
+    def __del__(self):
+        """清理临时目录"""
+        if self.temp_dir.exists():
+            shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def compose_keypoint_audio(
+        self,
+        keypoint: dict,
+        output_path: Path,
+        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 音色（男声，沉稳）
+        speed: float = 0.9              # 语速
+    ) -> CompositionResult:
+        """
+        合成知识点音频
+
+        Args:
+            keypoint: 知识点数据
+            output_path: 输出文件路径
+            lead_in_silence: 引导语后留白时长（秒）
+            section_silence: 内容后留白时长（秒）
+            dialogue_silence: 对话行之间留白时长（秒）
+            narrator_voice: 旁白音色
+            voice_a: 对话 A 角色音色
+            voice_b: 对话 B 角色音色
+            speed: 语速
+
+        Returns:
+            CompositionResult: 合成结果
+        """
+        try:
+            output_path = Path(output_path)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+
+            segments: List[Path] = []
+            segment_index = 0
+
+            # 1. Expressions 部分
+            expressions = keypoint.get("expressions", [])
+            if expressions:
+                # 引导语
+                lead_in = self._synthesize_segment(
+                    text="Key expressions",
+                    voice=narrator_voice,
+                    speed=speed,
+                    index=segment_index
+                )
+                segments.append(lead_in)
+                segment_index += 1
+
+                # 引导语后留白
+                silence_1s = self._generate_silence(lead_in_silence)
+                segments.append(silence_1s)
+
+                # 内容
+                phrases = [expr.get("phrase", "") for expr in expressions]
+                content_text = ". ".join(p for p in phrases if p)
+                if content_text:
+                    content = self._synthesize_segment(
+                        text=content_text,
+                        voice=narrator_voice,
+                        speed=speed,
+                        index=segment_index
+                    )
+                    segments.append(content)
+                    segment_index += 1
+
+                # 内容后留白
+                silence_2s = self._generate_silence(section_silence)
+                segments.append(silence_2s)
+
+            # 2. Alternatives 部分
+            alternatives = keypoint.get("alternatives", [])
+            if alternatives:
+                # 引导语
+                lead_in = self._synthesize_segment(
+                    text="You can also say",
+                    voice=narrator_voice,
+                    speed=speed,
+                    index=segment_index
+                )
+                segments.append(lead_in)
+                segment_index += 1
+
+                # 引导语后留白
+                silence_1s = self._generate_silence(lead_in_silence)
+                segments.append(silence_1s)
+
+                # 内容
+                content_text = ". ".join(alt for alt in alternatives if alt)
+                if content_text:
+                    content = self._synthesize_segment(
+                        text=content_text,
+                        voice=narrator_voice,
+                        speed=speed,
+                        index=segment_index
+                    )
+                    segments.append(content)
+                    segment_index += 1
+
+                # 内容后留白
+                silence_2s = self._generate_silence(section_silence)
+                segments.append(silence_2s)
+
+            # 3. Dialogues 部分
+            examples = keypoint.get("examples", [])
+            if examples:
+                # 引导语
+                lead_in = self._synthesize_segment(
+                    text="Dialogue",
+                    voice=narrator_voice,
+                    speed=speed,
+                    index=segment_index
+                )
+                segments.append(lead_in)
+                segment_index += 1
+
+                # 引导语后留白
+                silence_1s = self._generate_silence(lead_in_silence)
+                segments.append(silence_1s)
+
+                # 对话内容
+                silence_05s = self._generate_silence(dialogue_silence)
+                for example in examples:
+                    dialogue = example.get("dialogue", [])
+                    for line in dialogue:
+                        if ":" in line:
+                            speaker, text = line.split(":", 1)
+                            speaker = speaker.strip()
+                            text = text.strip()
+
+                            if not text:
+                                continue
+
+                            # A = henry (男声), B = catherine (女声)
+                            voice = voice_a if speaker.upper() == "A" else voice_b
+
+                            segment = self._synthesize_segment(
+                                text=text,
+                                voice=voice,
+                                speed=speed,
+                                index=segment_index
+                            )
+                            segments.append(segment)
+                            segment_index += 1
+
+                            # 对话行之间留白
+                            segments.append(silence_05s)
+
+            if not segments:
+                return CompositionResult(
+                    success=False,
+                    error_message="No audio content to compose"
+                )
+
+            # 4. 拼接所有片段
+            final_audio = self._concatenate_segments(segments, output_path)
+
+            # 5. 获取时长
+            duration = self._get_duration(final_audio)
+
+            return CompositionResult(
+                success=True,
+                audio_path=final_audio,
+                duration_seconds=duration
+            )
+
+        except Exception as e:
+            return CompositionResult(
+                success=False,
+                error_message=str(e)
+            )
+
+    def _synthesize_segment(
+        self,
+        text: str,
+        voice: str,
+        speed: float,
+        index: int
+    ) -> Path:
+        """
+        合成单个音频片段
+
+        Args:
+            text: 文本
+            voice: 音色
+            speed: 语速
+            index: 片段索引
+
+        Returns:
+            音频文件路径
+        """
+        output_path = self.temp_dir / f"segment_{index}.mp3"
+
+        result = self.tts.synthesize(
+            text=text,
+            output_path=output_path,
+            voice=voice,
+            speed=speed
+        )
+
+        if not result.success:
+            raise RuntimeError(f"TTS synthesis failed: {result.error_message}")
+
+        return output_path
+
+    def _generate_silence(self, duration: float) -> Path:
+        """
+        生成空白音频
+
+        Args:
+            duration: 时长（秒）
+
+        Returns:
+            空白音频文件路径
+        """
+        output_path = self.temp_dir / f"silence_{duration}.mp3"
+
+        if output_path.exists():
+            return output_path
+
+        cmd = [
+            self.ffmpeg_path,
+            "-f", "lavfi",
+            "-i", f"anullsrc=r=16000:cl=mono",
+            "-t", str(duration),
+            "-y",
+            str(output_path)
+        ]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to generate silence: {result.stderr}")
+
+        return output_path
+
+    def _concatenate_segments(
+        self,
+        segments: List[Path],
+        output_path: Path
+    ) -> Path:
+        """
+        拼接多个音频片段
+
+        Args:
+            segments: 音频片段路径列表
+            output_path: 输出文件路径
+
+        Returns:
+            拼接后的音频文件路径
+        """
+        # 创建文件列表
+        list_file = self.temp_dir / "concat_list.txt"
+        with open(list_file, "w") as f:
+            for seg in segments:
+                # 需要转义路径中的特殊字符
+                escaped_path = str(seg).replace("'", "'\\''")
+                f.write(f"file '{escaped_path}'\n")
+
+        cmd = [
+            self.ffmpeg_path,
+            "-f", "concat",
+            "-safe", "0",
+            "-i", str(list_file),
+            "-c", "copy",
+            "-y",
+            str(output_path)
+        ]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=120
+        )
+
+        if result.returncode != 0:
+            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

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""
+音频格式转换器 - 将 MP3 转换为飞书语音格式
+
+飞书语音消息要求：
+- 格式: Opus / Speex / AAC / AMR
+- 采样率: 8000Hz / 16000Hz
+- 声道: 单声道
+"""
+
+import subprocess
+import shutil
+from pathlib import Path
+from typing import Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class ConversionResult:
+    """转换结果"""
+    success: bool
+    output_path: Optional[Path] = None
+    error_message: Optional[str] = None
+    duration_seconds: Optional[float] = None
+
+
+class AudioConverter:
+    """音频格式转换器"""
+
+    # 飞书支持的语音格式
+    SUPPORTED_FORMATS = ["opus", "speex", "aac", "amr"]
+    SUPPORTED_SAMPLE_RATES = [8000, 16000]
+
+    def __init__(self, ffmpeg_path: Optional[str] = None):
+        """
+        初始化转换器
+
+        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)"
+            )
+
+    def convert_to_voice(
+        self,
+        input_path: Path,
+        output_path: Optional[Path] = None,
+        format: str = "opus",
+        sample_rate: int = 16000,
+        bitrate: str = "24k"
+    ) -> ConversionResult:
+        """
+        将音频文件转换为飞书语音格式
+
+        Args:
+            input_path: 输入文件路径（支持 MP3, WAV, M4A 等）
+            output_path: 输出文件路径（可选，默认同目录更换扩展名）
+            format: 输出格式（opus, speex, aac, amr）
+            sample_rate: 采样率（8000 或 16000）
+            bitrate: 比特率（默认 24k，适合语音）
+
+        Returns:
+            ConversionResult: 转换结果
+        """
+        # 参数验证
+        if format not in self.SUPPORTED_FORMATS:
+            return ConversionResult(
+                success=False,
+                error_message=f"Unsupported format: {format}. Supported: {self.SUPPORTED_FORMATS}"
+            )
+
+        if sample_rate not in self.SUPPORTED_SAMPLE_RATES:
+            return ConversionResult(
+                success=False,
+                error_message=f"Unsupported sample rate: {sample_rate}. Supported: {self.SUPPORTED_SAMPLE_RATES}"
+            )
+
+        input_path = Path(input_path)
+        if not input_path.exists():
+            return ConversionResult(
+                success=False,
+                error_message=f"Input file not found: {input_path}"
+            )
+
+        # 确定输出路径
+        if output_path is None:
+            output_path = input_path.with_suffix(f".{format}")
+        else:
+            output_path = Path(output_path)
+
+        # 确保输出目录存在
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # 构建 ffmpeg 命令
+        codec_map = {
+            "opus": "libopus",
+            "speex": "libspeex",
+            "aac": "aac",
+            "amr": "libvo_amrwbenc"
+        }
+
+        cmd = [
+            self.ffmpeg_path,
+            "-i", str(input_path),      # 输入文件
+            "-acodec", codec_map[format],  # 编码器
+            "-ar", str(sample_rate),    # 采样率
+            "-ac", "1",                 # 单声道
+            "-ab", bitrate,             # 比特率
+            "-y",                       # 覆盖输出文件
+            str(output_path)
+        ]
+
+        # 特定格式优化
+        if format == "opus":
+            # Opus 针对语音优化
+            cmd.extend(["-application", "audio"])
+        elif format == "speex":
+            # Speex 针对语音优化
+            cmd.extend(["-compression_level", "10"])
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=60  # 60秒超时
+            )
+
+            if result.returncode != 0:
+                return ConversionResult(
+                    success=False,
+                    error_message=f"ffmpeg error: {result.stderr}"
+                )
+
+            # 获取音频时长
+            duration = self._get_duration(output_path)
+
+            return ConversionResult(
+                success=True,
+                output_path=output_path,
+                duration_seconds=duration
+            )
+
+        except subprocess.TimeoutExpired:
+            return ConversionResult(
+                success=False,
+                error_message="Conversion timeout (>60s)"
+            )
+        except Exception as e:
+            return ConversionResult(
+                success=False,
+                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,
+        output_dir: Optional[Path] = None,
+        format: str = "opus",
+        sample_rate: int = 16000
+    ) -> dict:
+        """
+        批量转换目录中的音频文件
+
+        Args:
+            input_dir: 输入目录
+            output_dir: 输出目录（可选，默认在输入目录下创建 voice/ 子目录）
+            format: 输出格式
+            sample_rate: 采样率
+
+        Returns:
+            转换结果字典 {原文件名: ConversionResult}
+        """
+        input_dir = Path(input_dir)
+        if output_dir is None:
+            output_dir = input_dir / "voice"
+        else:
+            output_dir = Path(output_dir)
+
+        results = {}
+
+        # 支持的输入格式
+        input_extensions = [".mp3", ".wav", ".m4a", ".flac", ".ogg"]
+
+        for input_file in input_dir.glob("*"):
+            if input_file.suffix.lower() not in input_extensions:
+                continue
+
+            output_file = output_dir / input_file.with_suffix(f".{format}").name
+            results[input_file.name] = self.convert_to_voice(
+                input_path=input_file,
+                output_path=output_file,
+                format=format,
+                sample_rate=sample_rate
+            )
+
+        return results
+
+
+# 便捷函数
+def convert_mp3_to_opus(
+    input_path: Path,
+    output_path: Optional[Path] = None
+) -> ConversionResult:
+    """
+    将 MP3 转换为 Opus 格式（飞书推荐）
+
+    Args:
+        input_path: MP3 文件路径
+        output_path: 输出路径（可选）
+
+    Returns:
+        ConversionResult
+    """
+    converter = AudioConverter()
+    return converter.convert_to_voice(
+        input_path=input_path,
+        output_path=output_path,
+        format="opus",
+        sample_rate=16000
+    )

package/scripts/cli.py

@@ -20,7 +20,8 @@ def main():
                         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'],
+                                 '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')
@@ -198,6 +199,25 @@ def main():
             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/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))

package/scripts/state_manager.py

@@ -287,7 +287,8 @@ class StateManager:
         return daily_path
 
     def save_daily_content(self, content_type: str, content: Dict[str, Any],
-                           target_date: Optional[date] = None) -> Path:
+                           target_date: Optional[date] = None,
+                           generate_audio: bool = True) -> Path:
         """
         Save content to the daily directory.
 
@@ -295,6 +296,7 @@ class StateManager:
             content_type: Type of content ('keypoint', 'quiz', 'user_answers')
             content: Content dictionary to save
             target_date: Date for the content (defaults to today)
+            generate_audio: Whether to auto-generate audio for keypoints (default True)
 
         Returns:
             Path to the saved file
@@ -310,8 +312,95 @@ class StateManager:
         with open(file_path, 'w', encoding='utf-8') as f:
             json.dump(content, f, ensure_ascii=False, indent=2)
 
+        # Auto-generate audio for keypoints
+        if content_type == 'keypoint' and generate_audio:
+            try:
+                audio_result = self.generate_keypoint_audio(target_date)
+                if audio_result.get('success'):
+                    # Update keypoint with audio metadata
+                    content['audio'] = {
+                        'composed': audio_result.get('audio_path'),
+                        'duration_seconds': audio_result.get('duration_seconds'),
+                        'generated_at': datetime.now().isoformat()
+                    }
+                    # Re-save with audio info
+                    with open(file_path, 'w', encoding='utf-8') as f:
+                        json.dump(content, f, ensure_ascii=False, indent=2)
+            except Exception as e:
+                print(f"Warning: Audio generation failed: {e}")
+
         return file_path
 
+    def generate_keypoint_audio(self, target_date: Optional[date] = None) -> Dict[str, Any]:
+        """
+        Generate composed audio for a keypoint.
+
+        Args:
+            target_date: Date for the keypoint (defaults to today)
+
+        Returns:
+            Dictionary with:
+                - success: bool
+                - audio_path: str (relative path from data_dir)
+                - duration_seconds: float
+                - error_message: str (if failed)
+        """
+        try:
+            from .audio_composer import AudioComposer
+            from .tts import TTSManager
+        except ImportError:
+            from audio_composer import AudioComposer
+            from tts import TTSManager
+
+        if target_date is None:
+            target_date = date.today()
+
+        # Load the keypoint
+        keypoint = self.load_daily_content('keypoint', target_date)
+        if not keypoint:
+            return {
+                'success': False,
+                'error_message': f'No keypoint found for {target_date}'
+            }
+
+        # Prepare output path
+        date_str = target_date.strftime('%Y-%m-%d')
+        self.audio_dir.mkdir(parents=True, exist_ok=True)
+        output_path = self.audio_dir / date_str / "keypoint_full.mp3"
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            # Initialize TTS and composer (handle both package and direct imports)
+            try:
+                from .audio_composer import AudioComposer
+                from .tts import TTSManager
+            except ImportError:
+                from audio_composer import AudioComposer
+                from tts import TTSManager
+
+            tts = TTSManager.from_env()
+            composer = AudioComposer(tts)
+
+            # Compose audio
+            result = composer.compose_keypoint_audio(keypoint, output_path)
+
+            if result.success:
+                return {
+                    'success': True,
+                    'audio_path': f"audio/{date_str}/keypoint_full.mp3",
+                    'duration_seconds': result.duration_seconds
+                }
+            else:
+                return {
+                    'success': False,
+                    'error_message': result.error_message
+                }
+        except Exception as e:
+            return {
+                'success': False,
+                'error_message': str(e)
+            }
+
     def load_daily_content(self, content_type: str,
                            target_date: Optional[date] = None) -> Optional[Dict[str, Any]]:
         """

package/scripts/tts/manager.py

@@ -27,9 +27,14 @@ from pathlib import Path
 from typing import Dict, Any, Optional, Type, ClassVar
 from datetime import date, datetime
 import os
+import sys
+
+# 添加 scripts 目录到路径以导入 state_manager
+sys.path.insert(0, str(Path(__file__).parent.parent))
 
 from .base import TTSProvider, TTSConfig, TTSResult
 from .providers.xunfei import XunFeiProvider
+from state_manager import get_default_state_dir
 
 
 # Provider 注册表
@@ -57,7 +62,7 @@ class TTSManager:
     def __init__(
         self,
         provider: str = "xunfei",
-        data_dir: str = "data",
+        data_dir: str = None,
         config: Optional[TTSConfig] = None,
         **credentials
     ):
@@ -66,12 +71,12 @@ class TTSManager:
 
         Args:
             provider: Provider 名称（目前仅支持 "xunfei"）
-            data_dir: 数据目录
+            data_dir: 数据目录（默认使用 OPENCLAW_STATE_DIR 或 ~/.openclaw/state/eng-lang-tutor/）
             config: TTS 配置
             **credentials: Provider 认证信息
 
         示例:
-            # 讯飞（从环境变量读取）
+            # 讯飞（使用默认数据目录）
             manager = TTSManager(provider="xunfei")
 
             # 讯飞（直接传入密钥）
@@ -88,7 +93,12 @@ class TTSManager:
                 f"Available: {list(PROVIDERS.keys())}"
             )
 
-        self.data_dir = Path(data_dir)
+        # 使用与 StateManager 相同的默认目录逻辑
+        if data_dir is None:
+            self.data_dir = get_default_state_dir()
+        else:
+            self.data_dir = Path(data_dir)
+
         self.audio_dir = self.data_dir / "audio"
         self.audio_dir.mkdir(parents=True, exist_ok=True)
 

package/scripts/tts/providers/xunfei.py

@@ -16,6 +16,8 @@ import base64
 import hmac
 import json
 import os
+import ssl
+import certifi
 from pathlib import Path
 from typing import Optional, ClassVar, Dict
 from urllib.parse import urlencode
@@ -132,8 +134,12 @@ class XunFeiProvider(TTSProvider):
                 data = json.loads(message)
                 if data.get("code") == 0:
                     audio = data.get("data", {}).get("audio", "")
+                    status = data.get("data", {}).get("status", 0)
                     if audio:
                         audio_data.extend(base64.b64decode(audio))
+                    # status=2 表示合成完成，关闭连接
+                    if status == 2:
+                        ws.close()
                 else:
                     error_msg = f"XunFei API error: code={data.get('code')}, message={data.get('message')}"
             except json.JSONDecodeError as e:
@@ -170,7 +176,10 @@ class XunFeiProvider(TTSProvider):
                 on_error=on_error,
             )
             ws.on_open = on_open
-            ws.run_forever()
+            # 使用 certifi 提供的 SSL 证书
+            ws.run_forever(
+                sslopt={"cert_reqs": ssl.CERT_REQUIRED, "ca_certs": certifi.where()}
+            )
 
             if error_msg:
                 return TTSResult(success=False, error_message=error_msg)