前言¶
在 DeepSeek Harness（DSH）里接 @tencent-connect/dsh-qqbot 时，常见做法是只处理文字：用户发语音，agent 往往只能看到附件链接或平台侧零散字段，模型难以像读普通消息一样理解内容；回复也默认是文本，在群聊或移动场景里不够直观。社区维护者 ChencLi819 的 dsh-qqbot-voice 是 DSH 插件，专门给已有 QQ 机器人链路补上「听」和「说」：入站语音转写后注入上下文，出站可合成 QQ 语音消息，并支持基于语音消息往返的对讲模式。下文按安装、配置与用法说明如何在本地启用。
这是什么¶
dsh-qqbot-voice 是 DeepSeek Harness 插件，peer 依赖 @tencent-connect/dsh-qqbot（>= 0.5.0）。它通过补丁向 Cordis 注册 qqbot-bots 服务，在不改动 dsh-qqbot 原有业务逻辑的前提下挂载入站中间件，并完成语音发送能力对接。插件在 SkillHub 目录中归类为「模型推理」；仓库采用 MIT 许可证，当前 npm 包版本为 0.1.0，要求 Node.js >= 20.3.0。
需要事先明确：QQ 官方机器人 API 不提供实时 RTC 语音通话（无拨号、SDP 或音频流接口）。本插件所称「通话」是对讲模式——双方仍通过一条条语音消息交互，静默超时自动结束，并非电话式流媒体。
核心功能¶
资料中列出的能力如下。
| 能力 | 说明 |
|---|---|
| 语音转写（ASR） | 入站语音转写为文本并注入 agent 上下文，格式为 [Voice message] <文本> |
| 语音合成（TTS） | 将回复合成为 QQ 语音消息；支持指令或模式自动触发 |
| 语音通话（对讲） | 通话期间以语音消息往返；静默超时挂断；文本回复仍保留 |
| 引擎可替换 | ASR、TTS 均为可配置引擎链，支持云端接口与本地命令 |
| 运行时可观测 | 落盘诊断文件，记录引擎链、机器人实例与最近入站事件 |
ASR 默认可走阿里云百炼（qwen3-asr-flash），也可切换 OpenAI 兼容 HTTP、command 本地命令，或平台自带转写（qq）。TTS 默认同理（qwen3-tts-flash 等音色）。可选依赖 silk-wasm 用于解码仅有 SILK、无 WAV 的附件。
插件还向模型注册两个工具：qqbot_say（合成并发送语音）与 qqbot_voice_call（控制通话与语音回复模式）。
兼容性与依赖¶
| 项目 | 要求 |
|---|---|
| DSH | 与 dsh-qqbot 声明范围一致：CLI 0.1.0-rc.8、Desktop 0.2.0-rc.2 |
| Node.js | >= 20.3.0 |
@tencent-connect/dsh-qqbot |
>= 0.5.0（必需） |
| 默认云端 ASR/TTS | 需配置 DASHSCOPE_API_KEY（或通过配置项 / ~/.dsh/.credentials.yaml 解析） |
安装与启用¶
通过 DSH CLI 安装¶
Web 与 Desktop profile 的安装命令以 README 为准：
# 从 npm 安装
dsh plugin --profile web add dsh-qqbot-voice
# 或从源码安装
dsh plugin --profile web add github:ChencLi819/dsh-qqbot-voice
# Desktop 版
dsh plugin --profile desktop add dsh-qqbot-voice
本插件需通过补丁获取 dsh-qqbot 的机器人实例。安装后执行（README 示例为 PowerShell，在 Linux 上同样可用 node 调用）：
node tools/install.mjs # 幂等：补全依赖、bundle 与补丁
node tools/patch-dsh-qqbot-voice-hook.mjs # 或仅执行补丁
完成后重启 DSH。dsh-qqbot 升级后补丁可能被覆盖，需重新执行补丁步骤。
检查安装状态时：
node tools/install.mjs --check
配置凭据与插件项¶
默认 ASR/TTS 使用百炼时，需设置环境变量 DASHSCOPE_API_KEY，或在 profile 的 cordis.patch.yml 中深合并覆盖。示例片段：
- id: qqbot-voice
config:
stt:
preferQq: true
tts:
voice: Serena
call:
maxIdleMinutes: 5
greetText: 在的，请讲
完整字段默认值见仓库 lib/config.js 的 DEFAULTS；常见项包括 stt.engine、tts.engine（均可为 auto）、call.maxIdleMinutes（默认 8 分钟静默挂断）、voiceReply.sanitize（合成前清理 Markdown 等）。
典型用法¶
用户指令¶
指令以 / 或 ／ 开头；群聊需 @ 机器人后发送。
| 指令 | 说明 |
|---|---|
/语音 |
查询当前状态（模式、ASR/TTS 引擎链） |
/语音 开 / /语音 关 |
开启或关闭「文本 + 额外语音」回复 |
/通话 或 /打电话 |
开始对讲模式 |
/挂断 |
结束对讲 |
也支持自然语言变体，例如 /语音 打开、/通话 结束。
日常交互流程¶
- 用户发送 QQ 语音消息 → 插件在中间件中转写，写入
ctx.state.processedAttachments，agent 收到带[Voice message]前缀的文本。 - 开启
/语音 开或处于对讲模式时 → 助手回复除文本外，可按规则合成并发送语音消息。 /通话后连续发语音 → 按对讲逻辑处理；长时间无语音则按call.maxIdleMinutes自动结束。
排查时可查看 ~/.dsh/qqbot-voice/diagnostic.json（引擎链、qqbotBotsService、已挂载 bot、lastInbound 等）与 state.json（各会话 call / voice / off 模式）。
仓库提供本地自检脚本，例如：
node tools/fake-host.mjs # 端到端自检（听、说、通话）
node tools/probe-roundtrip.mjs # 合成 → 识别闭环
node tools/check-live.mjs # 只读输出现场信息
适用场景与注意¶
适合谁：已在 DSH 中运行 dsh-qqbot、希望私聊或群聊支持语音输入输出、且能接受「对讲式」而非 RTC 通话的团队或个人开发者。
运行与安全：插件与 DSH 进程同权限运行；语音会经你所配置的 ASR/TTS 引擎（默认可能上传至阿里云百炼）。安装前请阅读仓库源码与 MIT 许可证，自行评估凭据存放方式（环境变量、~/.dsh/.credentials.yaml）。社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。
常见故障：若完全无语音行为，优先确认补丁已执行且已重启，并检查 diagnostic.json 中 qqbotBotsService 与 bots 是否正常。
结尾¶
dsh-qqbot-voice 把 QQ 机器人的语音消息纳入 agent 上下文，并在出站侧补上 TTS 与对讲模式，引擎链可替换，便于在纯文本 bot 之上扩展语音交互。详情与更新以仓库 README 为准。
- 目录页：https://www.skillhub.cn/plugins/ChencLi819/dsh-qqbot-voice
- GitHub：https://github.com/ChencLi819/dsh-qqbot-voice
