DeepSeek Harness 插件介紹：dsh-kokoro

前言¶

DeepSeek Harness (DSH) 的插件生態旨在通過模塊化擴展能力。dsh-kokoro 是一個針對本地 Kokoro TTS 服務的 HTTP 客戶端插件。它不包含任何模型權重（ONNX、.pt 或 voice bins），僅作爲連接器和參數驗證層存在。開發者通過它將文本發送至本地服務器，獲取生成的 WAV 文件路徑，從而在 DSH 環境中實現文本轉語音功能。

核心定位¶

• 插件名稱：jwilson411/dsh-kokoro
• 維護者：jwilson411
• 功能定位：HTTP TTS 客戶端插件，註冊 kokoro_tts 工具。
• 核心邏輯：向本地 Kokoro 服務器 POST 文本，返回 WAV 文件路徑。
• 特性：無權重數據、無播放/混音/緩存、無 API 密鑰認證。

安裝與啓用¶

安裝該插件需要 DeepSeek Harness 環境已配置好 web profile。

dsh plugin --profile web add github:jwilson411/dsh-kokoro

安裝後，插件會依賴 @deepseek-ai/dsh-tools（建議版本 ^0.1.1-rc.2）和 @deepseek-ai/cordis。系統要求 Node.js 版本不低於 22.14.0。

配置與使用¶

插件本身不包含模型數據，必須連接到一個運行中的 kokoro-tts-api 服務器。

連接本地服務器¶

插件的默認 base URL 爲 http://127.0.0.1:8000，但該服務器默認監聽端口爲 8765。因此，你需要顯式配置連接地址。

配置方式有兩種，優先級從高到低：
1. Profile 配置：在 cordis.patch.yml 的配置行中設置 baseURL。
2. 環境變量：設置 DSH_KOKORO_BASE_URL。

示例：

# dsh.profile.bundles 配置示例
- id: kokoro
  config:
    baseURL: http://127.0.0.1:8765

啓動服務器：
在使用插件前，需先啓動對應的 Kokoro TTS API 服務器。

KOKORO_PORT=8765 make run

啓動後可進行健康檢查：

curl -s http://127.0.0.1:8765/health

Stub 模式（無服務器測試）¶

在未運行服務器或進行調試時，可開啓 Stub 模式。此時不會發起網絡請求，而是生成一個靜默的 WAV 文件，用於驗證調用流程。

KOKORO_STUB=1

工具註冊與參數¶

插件註冊的 Cordis 工具 ID 爲 kokoro。它注入了 tools 依賴。

工具：kokoro_tts¶

該工具接受以下參數：

支持的語音列表（共 19 個）：
- am_ 系列（美式男聲）：michael, adam, liam, eric, james, william, caleb, david, ethan
- bm_ 系列（英式男聲）：daniel, george, lewis, oliver
- af_ 系列（美式女聲）：heart, nova, sarah, bella
- bf_ 系列（英式女聲）：emma, isabella

返回值¶

調用成功返回 JSON 對象，包含文件路徑及相關元數據：

{
  "path": "/tmp/dsh-kokoro/kokoro-am_michael-uuid.wav",
  "voice": "am_michael",
  "speed": 1.0,
  "bytes": 122444,
  "text_chars": 41,
  "plugin": "dsh-kokoro"
}

注意事項¶

1. 文件路徑與權限：

   • 輸出目錄默認爲 os.tmpdir()/dsh-kokoro。
   • 目錄權限爲 0700，文件寫入權限爲 0600。
   • 插件不會自動清理生成的臨時文件，由操作系統或用戶管理。
   • 插件不支持自定義輸出路徑或文件名，以防止文件寫入權限被濫用。

2. 請求限制：

   • 請求不跟隨重定向（Redirects not followed）。
   • 響應內容類型必須是 audio/*，且前 12 字節必須是 RIFF/WAVE 頭，否則報錯 KOKORO_BAD_AUDIO。

3. 超時與大小：

   • 默認超時時間爲 30 秒（可配置）。
   • 默認響應最大字節爲 10 MiB（可配置）。

4. 無頭模式：

   • 也可以直接在 Node.js 腳本中導入 createKokoroTtsTool 進行無頭調用。

該插件適合需要在 DeepSeek Harness 環境中快速接入本地輕量級 TTS 能力的場景，無需在 DSH 倉庫中維護龐大的模型文件。