前言¶
在 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。
