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 仓库中维护庞大的模型文件。