前言¶
在 DeepSeek Harness 里做助手，文字会话往往已经跑通，但「按住说话」和「朗读回复」仍要单独接 ASR、TTS，还要和 DSH Web 的认证、会话界面对齐。若同时用 OneBot / QQ，还要考虑语音消息的转写、合成和现有 QQ 插件的 record 发送，不能把权限网关绕开。
dsh-voice-conversation-qq-web 由维护者 6789-6 发布，归类为模型推理相关能力：为 DSH Web 提供麦克风转写与朗读入口，并为 Agent 注册可选的 voice_tts 工具；推荐合成侧走 Fish Audio，识别侧接独立 ASR，可选 QQ 桥接在 ASR 失败时尝试 OneBot 原生转写。公开包不含 Key、音色 ID 或个人配置，双语说明见仓库 README。
这是什么¶
插件 npm 包名为 dsh-voice-conversation-qq-web，当前版本 0.1.4，采用 MIT 许可证。要求 Node.js 24+，DSH 0.2.1-rc.2 或兼容 0.2.x。它不捆绑 ASR 推理模型，只定义 HTTP 接口；Fish Audio 原生 TTS API 与插件期望的 POST /v1/audio/speech 不一致，需用仓库内适配器或自研等价服务。
核心功能¶
四条数据路径¶
| 场景 | 数据路径 |
|---|---|
| 网页说话 | 按住麦克风 → DSH 已认证连接 → ASR → 输入草稿 → 用户确认发送 |
| 网页朗读 | 点击朗读 → DSH 已认证连接 → TTS → 浏览器播放 |
| QQ 收语音 | OneBot → 可选桥接 → ASR；失败时尝试 OneBot 原生转写 → 现有 QQ 插件 |
| QQ 发语音 | Agent 调用 voice_tts → TTS 生成 WAV → 现有 QQ 插件发送 record → OneBot 回执 |
网页侧 /api/dsh-voice/asr、/api/dsh-voice/tts 走 DSH 已认证连接，插件不单独开放匿名 HTTP 路由。未配置 TTS 时不注册 voice_tts。
对外服务约定¶
ASR 须接受 POST、Content-Type: audio/wav 和 WAV 体；成功响应为非空 JSON，例如 {"text":"请告诉我今天星期几"}。输入 WAV 上限 2 MiB，转写上限 1000 字。
TTS 须接受 POST /v1/audio/speech、JSON {"input":"你好","response_format":"wav"}，返回 WAV。每次合成正文最多 180 字，WAV 响应最多 5 MiB；请求默认超时 30 秒，timeoutMs 可设 1000–150000 毫秒。
QQ 能力依赖现有 dsh-onebot-hub、OneBot 及原有权限与会话隔离；可选桥接不能替代权限网关。
安装与启用¶
环境与秘密管理¶
先在独立 profile 验证，现网接入前备份 profile。Fish Key、音色 reference_id、适配器令牌、ASR 令牌、OneBot 令牌等放在仓库外私有文件，每文件一行，Linux 上建议权限 0600，不要写入 Git 或截图。
从 Release 安装¶
当前公开安装方式为 GitHub Release 的 dsh-voice-conversation.tgz，尚未发布到 npm。Linux 示例：
curl -fL -o dsh-voice-conversation.tgz https://github.com/6789-6/dsh-voice-conversation-qq-web/releases/latest/download/dsh-voice-conversation.tgz
dsh plugin --profile <profile> add ./dsh-voice-conversation.tgz
dsh --profile <profile> --dump-config
在输出中确认只有一条 dsh-voice-conversation-qq-web 记录。安装包内 cordis.patch.yml 已插入插件，不要再应用 examples/cordis.patch.yml 的手动 insert。
Profile 配置示例¶
按 examples/profile-override.patch.yml，用插件 id 覆盖已安装条目，地址与路径须 DSH 进程可读、可达：
- id: dsh-voice-conversation-qq-web
config:
enabled: true
asrUrl: http://127.0.0.1:9002/v1/asr
asrTokenFile: /run/secrets/asr-token
ttsUrl: http://127.0.0.1:9003/v1/audio/speech
ttsTokenFile: /run/secrets/tts-token
voice: ''
model: ''
timeoutMs: 30000
只用网页朗读或只用网页转写时，另一项 URL 可留空。ttsTokenFile 指向适配器令牌，而非 Fish Key。保存后重启 DSH，再用 --dump-config 核对。
典型用法¶
Fish Audio 与本地适配器¶
Fish 原生 POST https://api.fish.audio/v1/tts 不能直接填入 ttsUrl。推荐复制 examples/fish-tts.env.example 到仓库外环境文件，填秘密文件路径后启动适配器：
node --env-file=/private/fish-tts.env /path/to/repository/examples/fish-tts-adapter.mjs
默认监听 127.0.0.1:9003。私有网络内用 Authorization: Bearer <适配器令牌> 和 JSON 正文测试，预期 200、audio/wav。插件里 ttsUrl 指向该地址。
网页验收¶
- 在已认证的 DSH Web 工作区允许麦克风（HTTPS 或 localhost）。
- 按住麦克风说话，松开后 ASR 结果进入草稿，需手动发送。
- 对助手回复点「朗读」，浏览器播放 TTS，不发送 QQ 消息。
可选 QQ 桥接¶
拓扑推荐：DSH QQ hub → 原有权限网关 → 本语音桥接 → OneBot。参考 examples/bridge.env.example 建私有环境，在仓库副本执行：
npm ci --ignore-scripts
node --env-file=/private/voice-bridge.env /path/to/repository/bin/voice-bridge.js
在 QQ hub 设置 tts.provider=plugin、tts.plugin.tool=voice_tts。白名单文件每行一个 QQ 账号 ID，不得进 Git。status=synthesized 仅表示 WAV 已生成，还须 onebot_reply 发送 record 并得到成功回执。
适用场景与注意¶
适合谁： 已在 DSH 0.2.x 上跑 Web 或 OneBot QQ，愿意自建 ASR、TTS（或 Fish 适配器），并保留现有权限网关与白名单策略的团队。
运行权限： 插件以当前 DSH 进程权限运行；ASR/TTS 地址须从该进程可达，令牌文件须可读。安装前请阅读 仓库源码 与 MIT 许可证，在独立环境验收后再接现网。
排错要点： 安装后无配置项时查 DSH 版本与是否重复手动 insert；Fish 适配器 401 查适配器令牌，502 查 Fish Key 与额度；QQ 合成了但没送达时分别看 voice_tts 与 onebot_reply 回执。回退时停止桥接、恢复网关目标、移除 profile 覆盖并用插件管理器卸载。进一步步骤见仓库 docs/LIVE-INTEGRATION.md。
结尾¶
dsh-voice-conversation-qq-web 把 DSH Web 语音输入输出和 QQ 侧 voice_tts 合成接到统一配置里，ASR/TTS 保持可替换，QQ 桥接可选且服从原有网关。目录页：SkillHub 插件页；源码与 Release：GitHub。
