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