前言¶
DSH 的理念是「一切皆插件」，消息、工具、輸出都可以由插件接管。但想讓智能體直接開口說話，仍然有不少工程問題要處理：不同廠商的 TTS 接口不統一，密鑰放哪、音色怎麼選、每個片段用什麼語氣、其他插件要複用同一套語音服務，都要自己拼。dsh-tts-service 就是來解決這些問題的插件，由 loveandbeepbrother 維護，用一個包提供多家 TTS 供應商和一個統一的語音服務。下面介紹它的結構、安裝方式和典型用法。
定位¶
dsh-tts-service 是一個面向 DeepSeek Harness（DSH）的多供應商文本轉語音服務。它註冊 Doubao TTS 2.0、阿里雲百鍊（Model Studio，含 CosyVoice、Qwen-Audio-TTS、Qwen3-TTS）以及任何兼容 POST /audio/speech 的 OpenAI 兼容端點，讓用戶自己選音色，並讓智能體可以按片段（per-segment）指定語氣。
它同時是一個可被其他插件複用的服務：其他插件可以調用同一個 ctx.ttsService，不用各自再接一遍 TTS。
一個包分成多個插件入口，在 DSH 插件頁面分別開關：
| 入口 id | 作用 | 默認開啓 |
|---|---|---|
tts-service |
提供服務 ctx.ttsService：供應商註冊、選擇（供應商、音色、語言）、合成、音色列表。 |
是 |
tts-doubao |
供應商：Doubao（火山引擎）TTS 2.0。 | 否 |
tts-bailian |
供應商：阿里雲百鍊 / Model Studio。 | 否 |
tts-openai-compatible |
供應商：任意兼容 POST /audio/speech 的端點。 |
否 |
tts-say |
智能體工具 tts_service_say、tts_service_voices、tts_service_select，以及輸出註冊表 ctx.ttsSay。 |
是 |
tts-speaker-windows |
輸出方式：在電腦前時通過 PC 揚聲器播放（僅 Windows）。 | 是 |
需要先說明一點：插件沒有默認供應商，也沒有默認音色。在你選定之前，tts_service_say 會以 VOICE_NOT_SELECTED 失敗，並告訴智能體應該去哪選。另外，當前版本合成的是完整片段，不做流式輸出。
安裝與啓用¶
安裝命令來自項目 README：
dsh plugin add @loveandbeepbrother/dsh-tts-service
也可以從 GitHub 安裝：
dsh plugin add github:loveandbeepbrother/dsh-tts-service
運行環境要求：
- DSH
>=0.2.1-rc.3 <0.3.0-0（含預發佈版本；項目測試針對 0.2.1-rc.5）。 - Node.js 22 及以上，DSH 自帶的版本即可。
- 至少一家供應商的賬號和 API Key，合成費用由供應商計費。
- 使用揚聲器輸出時，需要 Windows 和 Windows PowerShell（
powershell.exe，系統默認自帶）。
啓用步驟：
- 在插件頁面打開一個供應商入口（
tts-doubao、tts-bailian或tts-openai-compatible），填寫其表單。 - 把 API Key 存進 DSH 的憑據存儲。
- 選定音色：讓智能體「列出可用音色」再「使用某個音色」，或直接在 Text-to-Speech Service（
tts-service）的設置裏填寫provider和voices。 - 讓智能體說一段話。
密鑰管理¶
配置文件裏不存放密鑰值，只存放密鑰名。密鑰值來自 DSH 的憑據服務（ctx.credentials，即設置頁的 key store）；沒有加載憑據服務時，則來自啓動 DSH 時的進程環境變量。密鑰在每次請求時讀取，因此輪換後立即生效。設置頁只顯示該密鑰是否已經配置。
| 入口 | 配置字段 | 默認密鑰名 | 用途 |
|---|---|---|---|
tts-doubao |
apiKeyEnv |
VOLCENGINE_TTS_API_KEY |
合成（火山引擎控制台「API Key 管理」中的 API Key）。 |
tts-doubao |
accessKeyEnv、secretKeyEnv |
VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY |
可選：火山引擎賬號 AK/SK，僅用於列出完整音色目錄。 |
tts-bailian |
apiKeyEnv |
DASHSCOPE_API_KEY |
合成和列出克隆音色（與官方 DashScope SDK 同名）。 |
tts-openai-compatible |
apiKeyEnv |
OPENAI_COMPATIBLE_TTS_API_KEY |
以 Authorization: Bearer 發送。本地無需密鑰的端點可留空。 |
這些字段名都可以重命名，例如需要同時接入兩個同類型端點時，用不同的密鑰名區分。
選擇音色¶
音色選擇保存在 tts-service 的設置裏，寫入用戶 profile，不需要重啓。設置項有：
| 字段 | 含義 |
|---|---|
provider |
默認供應商 id，留空表示無。 |
voices |
每個供應商的默認音色：供應商 id → 音色 id。音色 id 只在所屬供應商內有意義，因此從 Doubao 換到 Bailian 再換回來，兩邊的選擇都會保留。 |
language |
默認語言代碼，默認 auto，必須是供應商聲明支持的值。 |
有三種設置方式，都寫入同一份設置且立即生效：
- 設置頁：在 Text-to-Speech Service 設置裏修改
provider和voices。 - 讓智能體操作：先問「有哪些音色」（
tts_service_voices），再「切換到……」（tts_service_select）。智能體回覆會說明舊音色、新音色以及如何改回去。 - 從插件代碼調用：
await ctx.ttsService.configure({ provider: 'doubao', voices: { doubao: 'voice-id' } })
tts_service_voices（插件中對應 ctx.ttsService.voices(id)）會列出音色及其支持的語言、是否跟隨語氣描述。無法完整的列表會明確標註不完整，也可以手動輸入音色 id。
錯誤處理是明確的：供應商未註冊、語言不被支持、文本超過 maxChars、無法生成該格式，都會直接失敗。服務不會靜默切換到另一個供應商。
供應商細節¶
Doubao TTS 2.0（tts-doubao，供應商 id doubao）¶
| 字段 | 默認值 | 說明 |
|---|---|---|
providerId |
doubao |
需要跑兩份時可改。 |
resourceId |
seed-tts-2.0 |
作爲 X-Api-Resource-Id 發送。 |
apiKeyEnv、accessKeyEnv、secretKeyEnv |
見上文 | |
sampleRate |
24000 |
16-bit 單聲道 PCM。 |
maxChars |
300 |
每次請求的字符上限。 |
timeoutMs |
60000 |
有幾個細節需要注意。語氣描述和「上下文」（用戶上一句話）會合併成一條音色指令，通過 additions.context_texts 發送。只有 Doubao 2.0 系統音色（id 含 uranus）會跟隨這條指令，克隆音色不跟隨。音色列表方面，沒有 AK/SK 時返回從官方音色錶轉錄的 2.0 系統音色靜態表，且標註爲不完整；有 AK/SK 時插件調用官方 ListSpeakers API（HMAC-SHA256 簽名，service 爲 speech_saas_prod，region 爲 cn-beijing）。語言支持 auto、zh、en、ja，以 explicit_language 發送。
Alibaba Bailian（tts-bailian，供應商 id bailian）¶
| 字段 | 默認值 | 說明 |
|---|---|---|
model |
cosyvoice-v3-flash |
也可填 cosyvoice-v3-plus、cosyvoice-v2、cosyvoice-v3.5-flash、qwen-audio-3.1-tts-flash、qwen3-tts-flash 等。音色只與同模型搭配。 |
region |
cn-beijing |
可選 ap-southeast-1、cn-hongkong、us-east-1、eu-central-1、ap-northeast-1。密鑰、workspace 和模型按 region 隔離。 |
workspaceId |
— | API 主機的第一段標籤（如 llm-xxx）。設置後使用 workspace 域名 {workspaceId}.{region}.maas.aliyuncs.com，否則使用舊的 DashScope 域名。eu-central-1 和 ap-northeast-1 必須設置。阿里雲表示 DashScope 域名自 2026-09-30 起不再新增功能，因此建議設置。 |
apiKeyEnv |
DASHSCOPE_API_KEY |
|
sampleRate |
24000 |
CosyVoice / Qwen-Audio-TTS；Qwen3-TTS 固定 24000。 |
maxChars |
Qwen3-TTS 爲 600，其他爲 2000 | |
timeoutMs |
60000 |
覆蓋合成調用和音頻下載。 |
接口層面，CosyVoice 和 Qwen-Audio-TTS 走 /api/v1/services/audio/tts/SpeechSynthesizer，Qwen3-TTS 走 /api/v1/services/aigc/multimodal-generation/generation；兩者都返回有效期 24 小時的音頻 URL，插件負責下載。是否跟隨自由形式的語氣描述（instruction）要看模型：
| 模型 | 是否跟隨自由語氣描述 |
|---|---|
qwen-audio-* |
是，系統音色、克隆音色和設計音色均可（少數英語音色除外）。 |
cosyvoice-v3.5-* |
是（該模型只有克隆和設計音色）。 |
cosyvoice-v3-flash |
僅克隆和設計音色可以；系統音色只接受固定的指令模板。 |
OpenAI 兼容端點（tts-openai-compatible）¶
任何兼容 POST /audio/speech 的端點都可以直接接入，密鑰以 Authorization: Bearer 發送，本地無需密鑰的端點可將密鑰字段留空。
從插件複用服務¶
這個包是一個 ES Module，package.json 中 main 指向 ./src/service.js，types 指向 ./index.d.ts。除了默認導出，exports 字段還按子路徑導出了各個入口：./doubao、./bailian、./openai-compatible、./say、./speaker-windows，配套的 locale 文件也有對應子路徑。想在自己的插件裏直接調用語音服務，可以通過 ctx.ttsService.configure(...)（見上文）或 ctx.ttsService.voices(id) 完成。
其他插件即使不啓用 tts-say，也能複用同一個 ctx.ttsService。這降低了多個插件各自接 TTS、音色和密鑰策略不一致的風險。
適用場景與注意¶
適合以下幾類人：
- 想在 DSH 裏讓智能體直接說話、並按片段控制語氣的組合開發者。
- 已經在用多家 TTS 供應商、希望統一音色選擇與密鑰管理的人。
- 想做一個需要播報或語音提醒的插件、並複用同一套語音服務的人。
使用時需要注意：
- 先在插件頁面打開供應商入口並配置密鑰，再選音色；否則合成會失敗。
- 合成按供應商計費，密鑰在每次請求時讀取，輪換後立即生效。
- 只使用需要一個完整片段、不要求流式播放的場景；當前版本不支持流式合成。
- 語氣描述能否生效取決於供應商和音色型號，列音色時要看是否標註「跟隨語氣描述」。
- 插件以當前 DSH 進程的權限運行，安裝前應自行檢查源碼與許可證（
package.json聲明爲 MIT License）。當前版本號爲0.1.0。 - 社區目錄站是獨立站點，與 DeepSeek / 幻方無官方從屬關係。
小結¶
dsh-tts-service 的價值在於，把「接哪家 TTS、選哪個音色、按片段給語氣、其他插件複用」這幾件事收斂到一個插件裏：一個包、多個入口，供應商按需開關，音色保存在 profile 裏，密鑰只存名字。對需要讓 DSH 智能體開口說話的人來說，這是目前比較省事的路徑。
- 目錄頁：https://www.skillhub.cn/plugins/loveandbeepbrother/dsh-tts-service
- GitHub：https://github.com/loveandbeepbrother/dsh-tts-service
