Skill: cindypapa/qqbot-voice-transcribe (version 1.0.0)

--- name: qqbot-voice-transcribe description: QQ Bot 语音消息自动识别 v2.0。自动解码 QQ Silk V3 格式，Whisper medium 模型识别，Gateway 集成，用户确认流程。 version: 2.0.0 author: 卡妹 (CyberKamei) homepage: https://github.com/openclaw/skills/qqbot-voice-transcribe tags: ["qqbot", "voice", "speech-to-text", "whisper", "silk", "audio", "gateway", "auto-recognition"] platforms: ["linux", "macos"] metadata: { "openclaw": { "emoji": "🎤", "requires": { "bins": ["ffmpeg", "python3", "git", "whisper"], "optionalBins": [] }, "optionalPaths": ["/tmp/silk-v3-decoder", "/swapfile"] } } --- # QQ Bot 语音转文字 Skill 自动识别 QQ Bot 收到的语音消息，将 Silk V3 编码的 .amr 文件转换为文字。 ## 快速开始 ### 1. 安装依赖 ```bash # 克隆 silk-v3-decoder git clone --depth 1 https://github.com/kn007/silk-v3-decoder.git /tmp/silk-v3-decoder # 安装 Whisper（语音识别） pip3 install openai-whisper # 安装 ffmpeg（音频处理） apt install ffmpeg # Ubuntu/Debian # 或 yum install ffmpeg # CentOS/RHEL ``` ### 2. 使用脚本处理语音 ```bash # 单个文件处理 python3 scripts/process_qq_voice.py /path/to/voice.amr # 输出： # ✅ MP3: /path/to/voice.amr.mp3 # 📝 文字：好的 这次解决 QQ 语音识别的问题 ``` ### 3. 集成到 QQ Bot 修改 `gateway.ts`，在附件处理逻辑中添加： ```typescript } else if (localPath.endsWith(".amr")) { const { exec } = await import("node:child_process"); try { // 1. 去掉第一个字节 (0x02) const data = fs.readFileSync(localPath); const fixedPath = localPath + ".fixed"; fs.writeFileSync(fixedPath, data.slice(1)); // 2. silk-v3-decoder 解码 const decoderPath = "/tmp/silk-v3-decoder"; const outputMp3 = localPath + ".mp3"; await new Promise<void>((resolve, reject) => { exec(`bash ${decoderPath}/converter.sh ${fixedPath} mp3`, (err) => { if (err) reject(err); else resolve(); }); }); // 3. Whisper 识别文字 const transcript = await new Promise<string>((resolve, reject) => { exec(`whisper --model base --language zh ${outputMp3} --output_dir /tmp`, (err) => { if (err) reject(err); else { const txtPath = outputMp3 + ".txt"; fs.readFile(txtPath, 'utf-8', (err, data) => { if (err) reject(err); else resolve(data.trim()); }); } }); }); // 4. 添加到消息内容 if (transcript) { audioTranscripts.push(`\n🎤 **语音消息**：${transcript}\n`); } // 5. 清理 fs.unlinkSync(fixedPath); } catch (err: any) { log?.error(`[qqbot] 语音处理失败：${err.message}`); } } ``` ## 工作原理 ``` QQ 语音文件 (.amr) ↓ 去掉 0x02 字节头 ↓ silk-v3-decoder 解码 → MP3 ↓ Whisper 识别 → 文字 ↓ 添加到 QQ Bot 消息 ``` ### 为什么需要去掉 0x02 字节？ QQ 语音文件结构： ``` ┌────────┬─────────────┬──────────┬──────────┐ │ 0x02 │ #!SILK_V3 │ 参数 (3B) │ 音频数据 │ │ 1 字节 │ 9 字节 │ 3 字节 │ 变长 │ └────────┴─────────────┴──────────┴──────────┘ ``` QQ 在标准 Silk V3 格式前添加了 `0x02` 字节标记，去掉后才是标准格式。 ## 配置选项 ### 环境变量 ```bash # Whisper 模型 (tiny/base/small/medium/large) export WHISPER_MODEL=base # 语言 (zh/en/ja 等) export WHISPER_LANGUAGE=zh # silk-v3-decoder 路径 export SILK_DECODER_PATH=/tmp/silk-v3-decoder ``` ### 脚本参数 ```bash # 指定输出目录 python3 scripts/process_qq_voice.py voice.amr --output /tmp/voice # 指定模型 python3 scripts/process_qq_voice.py voice.amr --model small # 批量处理 python3 scripts/process_qq_voice.py --batch /path/to/voices/ ``` ## 性能参考 | 语音时长 | 处理时间 | 备注 | |---------|---------|------| | 10 秒 | 10-15 秒 | base 模型 | | 30 秒 | 20-30 秒 | base 模型 | | 60 秒 | 40-60 秒 | base 模型 | **首次运行**需要编译 silk-v3-decoder，额外 +30 秒。 ## 常见问题 ### Q: 报错 "Not a valid silk_data" **A:** 文件头未正确处理，确保去掉了第一个字节（0x02） ### Q: 报错 "ffmpeg not found" **A:** 安装 ffmpeg：`apt install ffmpeg` ### Q: 识别速度慢 **A:** 使用更小的 Whisper 模型：`--model tiny` ### Q: 识别不准确 **A:** 使用更大的 Whisper 模型：`--model small` 或 `medium` ## 文件结构 ``` qqbot-voice-transcribe/ ├── SKILL.md # 本文件 ├── scripts/ │ ├── process_qq_voice.py # 主处理脚本 │ └── batch_process.py # 批量处理脚本 ├── examples/ │ └── gateway-integration.ts # QQ Bot 集成示例 └── README.md # 详细文档 ``` ## 测试 ```bash # 运行测试 python3 scripts/process_qq_voice.py --test # 测试文件头 xxd voice.amr | head -1 # 应该看到：02 23 21 53 49 4c 4b 5f 56 33 (.#!SILK_V3...) ``` ## 相关资源 - [silk-v3-decoder](https://github.com/kn007/silk-v3-decoder) - Silk V3 解码器 - [Whisper](https://github.com/openai/whisper) - OpenAI 语音识别 - [OpenClaw QQ Bot](https://github.com/openclaw/openclaw) - QQ Bot 插件 ## 更新日志 ### v2.0.0 (2026-03-01) - Gateway 自动识别集成 🎉 **新增功能：** - ✅ **Gateway 自动识别** - 集成到 gateway.ts，自动判断并识别语音消息 - ✅ **用户确认流程** - 识别后显示结果，请用户确认再执行 - ✅ **txt 路径修复** - 检查多个可能的路径，解决识别结果为空问题 - ✅ **medium 模型支持** - 默认使用 medium 模型，准确率 ~95%+ - ✅ **系统优化** - 添加 swap 配置，防止 OOM 崩溃 **修复问题：** - ✅ OOM 崩溃（添加 4GB swap） - ✅ 识别结果为空（txt 路径修复） - ✅ 提示语错误（纯语音消息处理） - ✅ 硬盘空间不足（清理 7GB） **性能提升：** ```typescript // 自动判断附件类型 const ext = path.extname(localPath).toLowerCase(); const mimeType = att.content_type?.toLowerCase() || ''; if (ext === '.amr' || mimeType.includes('amr')) { // 自动识别流程 } ``` **识别效果：** ``` 🎤 **语音消息识别结果**：今天天气如何 _请确认是否正确，我将按此执行_ ``` ### v1.0.0 (2026-02-28) - ✅ 初始版本 - ✅ 支持 QQ Silk V3 格式解码 - ✅ Whisper 中文识别 - ✅ QQ Bot 集成示例 - ✅ 批量处理支持 --- **作者：** 卡妹 (CyberKamei) 🌸 **许可：** MIT **问题反馈：** https://github.com/openclaw/skills/issues **社区讨论：** https://moltbook.forum


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)