飞书极简语音助手

Whisper.cpp + Edge-TTS 双核心脚本，无Hook，Agent内直接调用

为 OpenClaw 提供完整的飞书语音交互能力：接收语音 → 识别文本 → 生成回复 → 合成语音 → 发送回复。

📦 实际文件清单

voice-assistant/
├── asr.py           # 语音识别（OGG/WAV → 文本）
├── tts.py           # 语音合成（文本 → OGG）
├── converter.py     # 音频格式转换（ffmpeg 封装）
├── install.sh       # 依赖检查脚本
├── requirements.txt # Python 依赖列表
└── SKILL.md         # 本文档

注意：

• ❌ 本包 不包含 whisper.cpp 二进制文件
• ❌ 本包 不包含 Whisper 模型文件
• ❌ 本包 不包含 预安装的 edge-tts（需用户安装）
• ✅ 所有核心脚本已就绪，可直接使用

🔧 依赖要求（必须手动准备）

🚀 完整配置流程

步骤 1: 安装 edge-tts

cd ~/.openclaw/workspace/skills/voice-assistant

# 方案 A: 全局安装（推荐）
pip install -r requirements.txt

# 方案 B: 安装到 skill 的 lib 目录（自包含）
pip install --target=lib -r requirements.txt

验证：python3 -c "import edge_tts; print('edge-tts OK')"

步骤 2: 编译 whisper.cpp

cd ~/.openclaw/workspace

# 如果还没有 whisper.cpp 仓库
git clone https://github.com/ggerganov/whisper.cpp

cd whisper.cpp
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

验证二进制：

~/.openclaw/workspace/whisper.cpp/build/bin/whisper-cli --help | head -3
# 应显示帮助信息

步骤 3: 下载 Whisper 模型

# 创建模型目录
mkdir -p ~/.openclaw/workspace/skills/voice-assistant/models/whisper

# 下载中等模型（推荐，1.5GB）
cd ~/.openclaw/workspace/skills/voice-assistant/models/whisper
curl -L -o ggml-medium.bin \
  "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin?download=true"

# 或下载小模型（快速测试，150MB）
# curl -L -o ggml-base.bin \
#   "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin?download=true"

验证：ls -lh models/whisper/*.bin

步骤 4: 运行依赖检查

cd ~/.openclaw/workspace/skills/voice-assistant
chmod +x install.sh
./install.sh

脚本会检查：

1. ✅ ffmpeg 是否安装
2. ✅ edge-tts 是否可用
3. ✅ whisper-cli 二进制是否存在
4. ✅ 模型文件是否已下载

🎯 快速测试

测试 ASR

python3 asr.py /path/to/voice.ogg

输出：识别的文本字符串

测试 TTS

python3 tts.py --text "你好，世界" --output /tmp/test.ogg --voice xiaoxiao

输出：/tmp/test.ogg

🔌 Agent 集成

在 Agent 会话中直接调用脚本，使用 message.send(filePath=...) 发送回复。

完整示例（Python）

import subprocess
import os

async def handle_voice_message(ogg_path, chat_id):
    """处理飞书语音消息的完整流程"""

    # 路径配置（根据你的实际路径调整）
    SKILL_DIR = "~/.openclaw/workspace/skills/voice-assistant"
    WHISPER_BIN = "~/.openclaw/workspace/whisper.cpp/build/bin/whisper-cli"
    MODEL_PATH = f"{SKILL_DIR}/models/whisper/ggml-medium.bin"
    OUTPUT_OGG = "/home/itian/.openclaw/workspace/tmp/reply.ogg"

    # 1. ASR 识别
    result = subprocess.run([
        "python3", f"{SKILL_DIR}/asr.py", ogg_path,
        "--model", MODEL_PATH,
        "--bin", WHISPER_BIN
    ], capture_output=True, text=True)

    if result.returncode != 0:
        print(f"ASR 失败: {result.stderr}")
        return
    user_text = result.stdout.strip()

    # 2. 生成回复（你的业务逻辑）
    reply_text = generate_reply(user_text)

    # 3. TTS 合成
    subprocess.run([
        "python3", f"{SKILL_DIR}/tts.py",
        "--text", reply_text,
        "--output", OUTPUT_OGG,
        "--voice", "xiaoxiao"
    ], capture_output=True, text=True)

    # 4. 发送语音回复
    await message.send(
        target=f"user:{chat_id}",
        filePath=OUTPUT_OGG,
        message=reply_text
    )

📝 脚本参数

asr.py

位置参数:
  audio_file            输入音频文件（OGG 或 WAV）

可选参数:
  --model MODEL         Whisper 模型路径（默认: models/whisper/ggml-large-v3-turbo.bin）
  --bin WHISPER_BIN     whisper-cli 可执行文件路径（默认: /usr/local/bin/whisper-cli）
  --lang LANG           语言代码（默认: zh）
  --threads N           CPU 推理线程数（默认: 8）

tts.py

必需参数:
  --text TEXT           要合成的文本
  --output OUTPUT       输出 OGG 文件路径

可选参数:
  --voice VOICE        Edge-TTS 音色 ID（默认: xiaoxiao）

🎨 Edge-TTS 音色

xiaoxiao  # 默认，普通话温暖女声
xiaoxuan  # 普通话温暖
xiaoyi    # 普通话可爱
liaoning  # 辽宁话幽默
shaanxi   # 陕西方言明亮
hiugaai   # 粤语友好
hiumaan   # 粤语
hsiaochen # 台湾中文友好

⚙️ 环境变量

脚本支持以下环境变量（可选）：

✅ 验证清单

安装完成后，确认以下检查点全部通过：

• ffmpeg 可执行：ffmpeg -version
• Python 3.8+：python3 --version
• edge-tts 可用：python3 -c "import edge_tts"
• whisper-cli 存在：ls ~/.openclaw/workspace/whisper.cpp/build/bin/whisper-cli
• 模型文件存在：ls models/whisper/*.bin
• ASR 测试通过：python3 asr.py test.ogg
• TTS 测试通过：python3 tts.py --text "测试" --output /tmp/test.ogg
• 输出文件可发送：ls /home/itian/.openclaw/workspace/tmp/reply.ogg

📊 性能参考（基于 ggml-medium.bin）

• ASR 识别（3秒语音）：~5-8 秒
• TTS 合成（20字文本）：~3-5 秒
• 完整流程：~10-15 秒

🚨 常见问题

Q: 找不到模型？ A: 下载模型到 skills/voice-assistant/models/whisper/，或使用 --model 参数指定完整路径。

Q: edge-tts 导入失败？ A: 运行 pip install -r requirements.txt 或 pip install edge-tts。

Q: 识别速度慢？ A: 使用较小模型（如 ggml-base.bin），或增加 --threads 参数。

Q: TTS 报错？ A: 检查网络连接（Edge-TTS 需要访问微软服务），确认音色 ID 正确。

📌 重要说明

• 无 Hook：不自动处理任何语音消息，需在 Agent 中显式调用
• 无轮询：不依赖任何定时任务
• 输出路径：建议保存到 workspace/tmp/ 目录
• 模型选择：首次推荐 ggml-medium.bin（1.5GB，平衡）

版本: 0.1.1
最后更新: 2026-03-29
维护: 添哥工作室 EOF echo "✅ SKILL.md 已重写（基于实际文件）"