前言¶

在 DSH 里让智能体「出声」，常见做法是为每个 TTS 服务单独写调用逻辑、查 voice 列表、处理返回格式。后端一旦换成自建或第三方 OpenAI 兼容接口，又要改一遍 glue 代码。dsh-tts 是维护者 xuan25 发布的 out-of-tree 插件（社区目录分类：模型推理），提供一个统一的 tts 工具，通过任意 OpenAI 兼容 TTS 后端把文本写成音频文件，并附带列举音色、探测路由、调用开发用 phonemize 等能力，减少按后端拆工具的成本。

这是什么¶

dsh-tts（npm 包名 dsh-tts，当前资料中版本 0.1.0，MIT 许可证）面向 DeepSeek Harness 的 profile：安装后注册一个 tts 工具，支持 wav、mp3、flac、aac、opus、pcm 等输出格式。插件不创建配置文件或状态文件；配置分层合并，且 providers 动词会标明每个字段来自哪一层，避免静默覆盖。

核心功能¶

tts 工具按 verb 区分行为，下表摘自官方 README。

synth 要点（与文档一致）：

1. voice 必填，无默认值；可用 id 通过 voices 查询。
2. 未传 model 时：路由只声明一个模型则用该模型；未声明则 live 探测 /models；若候选多于一个则失败并列出候选项。
3. response_format 默认 wav，原样传给后端。
4. 工具会校验返回容器（如 wav 的 RIFF walk、其它格式的 magic）；与声明格式不符则失败但保留文件；已知缺陷（如占位 RIFF 尺寸）可在成功结果里以 warnings 报告。
5. 输出路径：设 out 则为文件或目录；省略时写入 <process.cwd()>/tts/<unixts>_<voice>.<ext>。
6. speed、language 仅在调用方传入时下发。
7. 超时：synth 180 s；探测 15 s；phonemize 30 s。

插件附带 dsh-tts skill，供智能体上下文查阅参数表、环境变量约定与错误形态。

安装与启用¶

在指定 dsh profile 下执行官方安装命令：

dsh plugin --profile <name> add dsh-tts

安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证；插件以当前 dsh 进程权限运行，并会按配置访问网络与读写输出路径。

配置¶

优先级从低到高：内置默认（api: openai-compatible）→ TTS_* 环境变量（进程启动时静态）→ cordis patch（id dsh-tts 的 config 或 profile 级 patch）→ $DSH_HOME/settings.yaml 中的 dsh-tts: 段（每次调用重读，改 settings 无需重启）。

settings 示例：

dsh-tts:
  defaultProvider: local
  providers:
    local:
      baseURL: http://<host>:<port>/v1
    hosted:
      baseURL: https://api.example.com/v1
      apiKeyEnv: TTS_HOSTED_KEY
      models: [kokoro-v2]
      displayName: Hosted Speech

环境变量与配置字段一一对应：TTS_DEFAULT_PROVIDER；每个路由 <NAME> 对应 TTS_PROVIDER_<NAME>_BASEURL、TTS_PROVIDER_<NAME>_API、TTS_PROVIDER_<NAME>_APIKEYENV、TTS_PROVIDER_<NAME>_HEADERS（JSON 字符串）、TTS_PROVIDER_<NAME>_MODELS（逗号分隔）、TTS_PROVIDER_<NAME>_DISPLAYNAME。<NAME> 为大写且 - 转为 _。baseURL 需含 /v1 前缀；插件在其后拼接 /audio/speech、/audio/voices、/models，并从 base 去掉尾部 /v1 后访问服务根的 /health 与 /dev/phonemize。apiKeyEnv 只写环境变量名；请求时从进程环境或 $DSH_HOME/.credentials.yaml 解析。

典型用法¶

下列 JSON 调用示例来自 README，可直接对照 verb 理解参数。

// 默认路由及其唯一声明模型
{ "verb": "synth", "input": "hello world", "voice": "zf_xiaoxiao" }
// 指定路由、格式、语速与输出
{ "verb": "synth", "provider": "hosted", "input": "the quick brown fox",
  "voice": "zf_xiaoxiao", "response_format": "mp3", "speed": 1.1, "out": "/tmp/hi.mp3" }
// 按 id 前缀筛音色
{ "verb": "voices", "filter": "zf_" }
// 按 id/name 子串（不区分大小写）
{ "verb": "voices", "query": "zf" }
{ "verb": "providers" }
{ "verb": "status" }
{ "verb": "phonemize", "text": "hello world", "language": "zh" }

建议流程：先用 providers 确认路由与凭证 → status / voices 确认后端可达与音色 → 再 synth。多路由且未设默认时，须在调用中传 provider，或设置 TTS_DEFAULT_PROVIDER / defaultProvider。

适用场景与注意¶

适合：已在 DSH 中跑智能体、希望用同一套工具对接本地或托管的 OpenAI 兼容 TTS（含列举模型/音色、健康检查、可选 phonemize）的开发者。

注意：

1. 插件能力边界以 README 与 skill 为准；未在文档出现的后端行为不要假设。
2. voices 为 source: static 时，列表可能与本后端实际音色不一致。
3. 失败时返回带 error 字段的 JSON；常见如 TTS_NOT_CONFIGURED、凭证未设置、unknown provider、多路由无默认、容器校验失败等，README Troubleshooting 节有对应说明。
4. DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-tts 把合成、音色、路由状态与 phonemize 收进一个 tts 工具，配置可分层、可观测，便于智能体在 OpenAI 兼容 TTS 上落地语音输出而不必为每个后端单独写胶水。

• 目录页：https://www.skillhub.cn/plugins/xuan25/dsh-tts
• 源码与文档：https://github.com/xuan25/dsh-tts