语音合成客户端 jwilson411/dsh-kokoro

dsh-kokoro

一个小型 DeepSeek Harness 函数插件，可以将文本朗读出来。它只注册一个面向模型的工具——kokoro_tts——该工具将文本 POST 到本地的 Kokoro TTS 服务器，写入返回的 wav 文件，并报告路径。

此处不附带任何权重。 没有 ONNX，没有 .pt，没有语音 bin，没有嵌入——本仓库中没有任何模型数据，安装时也不会下载任何内容。模型位于服务器之后；本包只是通往它的连接线。它确实包含的是十九个语音名称的列表和两个数值边界，这些是从该服务器镜像过来的，这样错误的参数会在这里失败，而不是浪费一次往返。

它也不是一个音频工具包。没有播放、没有格式转换、没有混音、没有流式传输、没有缓存、没有转录。它只回答一个问题——这段文本听起来会是什么样？——然后返回一个文件路径。

没有 API 密钥，没有凭据，没有状态。

安装

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

dsh plugin 会转发到 $DSH_HOME/profiles/web 内的 pnpm，然后根据已安装状态协调 profile：由于本包的清单声明了 dsh.bundle.patch，它会被追加到 profile 清单有序的 dsh.profile.bundles 列表中，其补丁成为一个层。

移除方式相同，只需将 add 换成 remove。

将其指向服务器

插件的内置默认基础 URL 是 http://127.0.0.1:8000。

配套服务器 [jwilson411/kokoro-tts-api][api] 默认监听 8765 端口（KOKORO_PORT）。所以如果你运行的正是该服务器——很可能就是——请将基础 URL 设置为 http://127.0.0.1:8765。可以通过补丁行：

- id: kokoro
config:
baseURL: http://127.0.0.1:8765

或通过环境变量：

export DSH_KOKORO_BASE_URL=http://127.0.0.1:8765

顺序为最具体者优先：插件的补丁行，然后是 DSH_KOKORO_BASE_URL，最后是默认值。指定了 baseURL 的行会按其字面值采用，即使为空——写入该键却留空是一种错误配置，它会在加载时失败，而不是悄悄地去连接一个你并未指定的服务器。无论最终采用哪个值，都会立即进行规范化（去除末尾斜杠）并检查协议：任何不是 http: 或 https: 的都会被拒绝，因此 file: 基础地址无法将这一次出站请求变成一次本地读取。

请先启动服务器——权重步骤请参阅其 README，那是在那边进行的，不是在这里：

KOKORO_PORT=8765 make run # 在 jwilson411/kokoro-tts-api 的检出目录中
curl -s http://127.0.0.1:8765/health

固定版本的 DSH 候选发布版

本包是针对固定版本的候选发布版 0.1.1-rc.2 编写和测试的——即当前的 @deepseek-ai/dsh 发布版以及匹配的 @deepseek-ai/dsh-tools@0.1.1-rc.2，后者被精确固定在 devDependencies 中，以便测试针对一个已知的 API 运行。peer 范围是 ^0.1.1-rc.2，与 harness 自身工具包的声明方式一致。

请注意，@deepseek-ai/dsh-tools 的 npm latest 标签仍指向较旧的 0.0.1-rc.1；0.1.1-rc.2 系列发布在 next 下。请显式固定版本，而不要依赖标签。

没有运行时依赖。

它注册了什么

| Cordis 插件 id | kokoro（cordis.patch.yml 中的行 id） |
| 注入 | tools —— 一项硬依赖；插件会等待，而不是降级 |

| 工具 | 参数 | 返回 |
| kokoro_tts | text（字符串，必填，1–8000 个字符）、voice（字符串，可选，在白名单内，默认 am_michael）、speed（数字，可选，0.5–2.0，默认 1.0） | { path, voice, speed, bytes, text_chars, plugin } |

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

不会自动播放任何内容。路径会被报告出来，以便调用方可以打开它。

语音

共十九种，在白名单内。am_/af_ 是美式男声和女声，bm_/bf_ 是英式男声和女声：

am_michael（默认）、am_adam、am_liam、am_eric、am_james、 am_william、am_caleb、am_david、am_ethan、bm_daniel、bm_george、 bm_lewis、bm_oliver、af_heart、af_nova、af_sarah、af_bella、 bf_emma、bf_isabella。

任何其他名称都会在套接字打开之前以 KOKORO_BAD_VOICE 被拒绝。

wav 文件去向何处——以及为什么你无法选择

该工具没有 path、output 或 filename 参数，并且将来也不会增加。
让模型选择字节落地的位置，是一种披着文本转语音外衣的文件写入原语；如果这个工具上有 path 参数，那么任何能触达它的提示词都可以将攻击者构造的字节写入攻击者选定的位置。因此由插件来选择：一个名为 kokoro--.wav 的文件，位于它拥有的目录内——默认是
os.tmpdir()/dsh-kokoro，以 0700 模式创建，文件以 0600 模式写入——然后
在事后告诉你路径。运维人员可以通过补丁行中的 config.outputDir 移动该目录。调用方则不能。

不会替你清理任何内容；这些文件位于你的临时目录下，它们的生命周期是你的系统的事。

与 Kokoro 通信

只会发出恰好一个请求，发往恰好一个 URL：POST {baseURL}/tts，以 JSON
形式携带 {text, voice, speed}，并期望返回 audio/wav。不会跟随
重定向——3xx 会被报告为 KOKORO_HTTP_ERROR，而不是把正在朗读的文本带到 Location 头所指定的任何主机。

每个请求都受到双重限制，并且任一限制触发时都会失败关闭：一个 AbortSignal 截止时间（30 秒——合成并非瞬时完成）和一个响应字节上限（10 MiB），后者在响应体流式传输时强制执行，因此超大响应会被放弃，而不是被缓冲。两者都可以从补丁行配置：

- insert:
- id: kokoro
name: dsh-kokoro
config:
baseURL: http://127.0.0.1:8765
timeoutMs: 30000yaml
maxBytes: 10485760
outputDir: /var/tmp/dsh-kokoro

针对 id 的补丁会替换该行的整个 config，而不是合并到其中，因此覆盖必须重新声明其保留的字段。

在任何内容写入磁盘之前都会对其进行检查：内容类型必须是 audio/*，并且前十二个字节必须是声明 WAVE 的 RIFF 容器。以 200 状态返回的代理登录页面或 JSON 错误正文会以 KOKORO_BAD_AUDIO 失败，而不会以 .wav 名称落到磁盘上。

失败会携带稳定的 code —— KOKORO_BAD_TEXT、KOKORO_BAD_VOICE、KOKORO_BAD_SPEED、KOKORO_BAD_BASE_URL、KOKORO_HTTP_ERROR、KOKORO_BAD_AUDIO、KOKORO_RESPONSE_TOO_LARGE、KOKORO_TIMEOUT、KOKORO_UNREACHABLE、KOKORO_WRITE_FAILED —— 因此调用方无需匹配文字描述就能区分端口失效和被拒绝的语音。请求通过一个标明插件和此仓库的 User-Agent 来标识自身。

无头使用

工具工厂同时接受两个接缝——要使用的 fetch 和要写入的目录——因此你可以在不启动配置文件的情况下从普通 Node 脚本驱动它： js // say.mjs — node say.mjs
import { createKokoroTtsTool } from 'dsh-kokoro'

// 省略 fetch 以使用全局的，并与真实服务器通信。
const tts = createKokoroTtsTool({ baseURL: 'http://127.0.0.1:8765' })

const { path, bytes } = await tts.execute(
{ text: 'The kettle is on.', voice: 'bm_george' },
{ signal: AbortSignal.timeout(60_000) },
)
console.log(${bytes} bytes at ${path})

KOKORO_STUB=1

当环境中存在 KOKORO_STUB=1 且没有注入 fetch 时，完全不会发出请求：会在本地生成一个短的静音 wav，以便在没有服务器运行的情况下走完管道的其余部分——验证、写入、报告路径。它是静音，不是语音；这里没有任何内容合成音频，也不涉及任何模型。把它当作演示和冒烟测试的入口，而不是回退方案：当提供了 fetch 时它永远不会触发，也永远不会掩盖真实故障。

测试 sh
npm install
npm test

该测试套件离线运行，不需要 Kokoro 服务器。每个请求都由注入的 fetch 替身应答，并且每个测试文件都会用一个会抛错的守卫替换 globalThis.fetch，因此任何触及真实网络的代码路径都会作为测试失败而不是真实请求而失败。文件会写入 os.tmpdir() 下的一个临时目录，每个测试一个，测试结束时删除。CI 在 Node 22.x 和 24.x 上运行它，使用 contents: read 且没有机密。

许可证

MIT —— 见 LICENSE。版权所有 (c) 2026 Justin Wilson。

Kokoro-82M 模型及其权重不属于此包，也不受此许可证覆盖；请参阅 [jwilson411/kokoro-tts-api][api] 了解这些内容。

[api]: https://github.com/jwilson411/kokoro-tts-api