语音播报 fangqian616/dsh-say

dsh-say

让你的 DSH 用你喜欢的声音开口说话、汇报内容！

三分钟上手 ·工具 ·配置 ·排错 ·

⚡ 三分钟上手

不需要下载任何东西。 默认走你操作系统自带的语音 —— 不用 Python、不用显卡、不用账号。

1 · 装插件

npx dsh-say

就这一条，不用参数。 它默认装进 web profile；用别的 profile 加 --profile <名字>，想看它要执行什么加 --print。

等价的手写命令（npx 那条就是替你跑这个）：

dsh plugin --profile web add dsh-say

然后重启 profile —— 这一步必须由你做，命令行没法替你重启你正开着的会话。npx 跑完会把这句再说一遍，因为它只负责装，重启不了你的会话。

装完就结束。这条命令会把包装好、登记进 profile、并自动应用本包自带的组合层，tts_* 工具在重启后出现。

从源码装 / 用 git 地址（git 来源首次需要放行构建）

git clone https://github.com/fangqian616/dsh-say
dsh plugin --profile web add "file:E:/path/to/dsh-say" # 或用 git 地址：
dsh plugin --profile web add github:fangqian616/dsh-say

git 来源的插件靠 prepare 脚本构建，pnpm 默认拦着。dsh plugin 会直接打印出要放行的那个键 —— 把它加到 profile 目录的 pnpm-workspace.yaml 的 allowBuilds 下，再重跑一次即可。

本地 file: 路径要用绝对路径：pnpm 的工作目录是 profile 目录，相对路径 . 会指到 profile 自己。

它在 profile 里动什么

profile 根目录的 cordis.yml 是空的，它自己写着不要改它。真正的用户层是 cordis.patch.yml，但这里也不用你手写 —— 本包声明了：

"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }

dsh plugin add 识别到这个声明后，会把它列进 profile 的 dsh.profile.bundles 层栈，并在启动时套用包内那一行：

- insert:
- id: say
name: dsh-say

这是 dsh 插件的标准打包方式，所以升级、卸载、dsh plugin list 都能正常跟踪。

如果智能体已经能读到仓库，直接说一句 "装上这个语音插件" 就行。它会用 voice-setup skill 走完这一步，并且在没重启之前不会谎称装好了。

2 · 让它说话

对智能体说：

把"你好，我现在会说话了"念出来

它会调用 tts_speak，声音从音响里出来。安装到此结束。

3 · 确认后端状态

跑一下 tts_engines

selected: builtin (configured: auto)
built-in: available, 3 voice(s)
gpt-sovits: unavailable — no GPT-SoVITS checkout found voice packs: 0 in ~/.dsh/voice-packs

没声音时先跑这个 —— 它会指出确切原因。

4 · 想要角色声线（可选）

main 是插件本体，releases 是声线素材。

| | main（本仓库） | Releases |
| 是什么 | 插件本体 | 推理素材：模型 + 声线 + 参考音 |
| 下载量 | 0（用你系统自带的语音） | 见下面 |

两条路，先选一条

想要角色声线，不需要先有 GPT-SoVITS。

| | ONNX 那条 | GPT-SoVITS 那条 |
| 你要先准备什么 | 什么都不用（本机连 Python 都不用有） | 本机得有一个能跑的 GPT-SoVITS |
| 下载量 | 约 697 MB | 约 7.7 GB（1.34 GB 声线包 + 6.4 GB 官方整合包） |
| 什么时候选它 | 本机没有 GPT-SoVITS | 已经有了：零下载，而且更快 |

两条路跑的是同一套声线模型，只是运行时不同（onnxruntime / PyTorch）。

sample-full-v2ProPlus.zip 里有什么

| | 在包里吗 | 内容 |
| 4 个 base 模型（推理必需） | ✅ 在 | chinese-roberta、chinese-hubert、s1v3、s2Gv2ProPlus，约 1.14 GB |
| 声线权重 + 参考音 | ✅ 在 | 约 316 MB |
| GPT-SoVITS 程序本身 | ❌ 不在 | 需要本机已有一个能跑的检出 |
| Python + torch 运行时 | ❌ 不在 | 约 6 GB，分 Windows/Linux、分 CUDA 版本 |

sample-onnx-v2ProPlus.zip 里有什么

| | 在包里吗 | 内容 |
| ONNX 模型（推理必需） | ✅ 在 | 9 个文件，320.4 MB |
| 参考音 + 逐字文本 | ✅ 在 | ref.wav + ref.txt |
| base 模型 | ➖ 不需要 | Genie-TTS 自带 hubert 和 BERT |
| GPT-SoVITS / PyTorch | ➖ 不需要 | 用 onnxruntime 跑 |

dsh-say-onnx-runtime-win-x64.zip 里有什么（便携运行时，406.7 MB）

| | 在包里吗 | 内容 |
| Python 运行时 | ✅ 在 | 便携版 CPython 3.10 + 标准库，27 MB |
| 引擎依赖 | ✅ 在 | genie-tts、onnxruntime 等，已装好 |
| Genie 运行时数据 | ✅ 在 | hubert 和 BERT，392 MB，所有人一样 |

安装 GPT-SoVITS

前置条件：本机需要 GPT-SoVITS 检出加 Python 环境。 如果没有，官方 Windows 整合包解压双击即可（下载，6.4 GB）

把 sample-full-v2ProPlus.zip 下载好，对你的 AI 说一句：

安装试听音频

它会在 Downloads 找到那个包、解压、铺好 base 模型和声线权重、登记声线包。已经存在的文件会跳过。

想自己动手 / AI 没有自动做

一条命令，不用传路径 —— 它会去 Downloads、当前目录找这个包：

node scripts/install-voice.mjs

要指定别的包或别的 GPT-SoVITS：

node scripts/install-voice.mjs --from "D:/downloads/某个.zip" --engine "D:/GPT-SoVITS"

安装 ONNX

node scripts/install-onnx.mjs --voice

一条命令，本机不需要有 Python、不需要 PyTorch、不需要 GPT-SoVITS。脚本会下载一个预构建的便携运行时（406.7 MB，里面是便携版 Python + 装好的依赖 + Genie 运行时数据），再铺好声线（290.8 MB）。对 AI 说「安装试听音频」也行。

合计约 697 MB。要日文再加 --with-japanese（约 317 MB，默认不装）。--check 随时复查状态。

本试用声音资源仅供学习交流，严禁用于商业用途，如有侵权，请联系作者，作者得知后会于24小时内删除。

🛠 工具

| 工具 | 作用 |
| tts_speak | 短句直接念 |
| tts_report | 长汇报：先压缩再念，避免把整篇念完 |
| tts_engines | 诊断后端 + 返回当前人设 |
| tts_voices | 列出或登记声线包 |
| tts_config | 读改设置，不用碰配置文件 |

为什么汇报要先压缩

中文语音实测约 5 字/秒 —— 一份 500 字的汇报整篇念完要 100 秒，比读它还慢，用户会直接关掉声音。

tts_report 会先把长报告压成短稿再朗读，并返回它实际念出来的文本，方便确认没漏关键信息：

| | 字数 | 约合时长 |
| 原文 | 500 | 100 秒 |
| 朗读 | 120 | 24 秒 |

压缩是本地句序排序，零额外模型调用。要更多细节就调大 budget。

⚙️ 配置

需要你配什么（大多数情况下是「什么都不用」）

| 项 | 默认 | 什么时候要动 |
| GPT-SoVITS 目录 | 自动找 | 找不到时（见下） |
| 声线包目录 | ~/.dsh/voice-packs | 一般不动 |
| 系统语音（默认引擎） | 用系统自带的 | 不用配 |
| Python 环境 | 引擎目录里的 / conda / PATH 上的 | 引擎能用就不用管 |
| profile | 你装插件时指定的那个（web 等） | 用别的 profile 时 |
| 环境变量 | 一个都不需要 | — |

环境变量全都不必需。 DSH_VOICE_ENGINE_ROOT、DSH_VOICE_VOICES_DIR、DSH_VOICE_CONFIG 都只是覆盖项，设了会优先于配置文件。下面这些走配置文件就够。

GPT-SoVITS 目录是怎么找到的

自动搜索，不需要你填。 顺序是：

1. 配置里的 engines.gptSovits.engineRoot（你手动指定时）
2. 环境变量 DSH_VOICE_ENGINE_ROOT（一般不用）
3. ~/GPT-SoVITS、~/GPT-SoVITS-main、~/gpt-sovits
4. 每个盘符根目录下名字像 GPT-SoVITS… 的文件夹（所以解压到 E:\ 或 F:\ 也能找到）
5. 已经跑起来的 API（配了 serverUrl 时）

第 4 条是关键：官方整合包是个 7z，大家通常解压到空间大的盘根目录，不是 C:\。以前写死 C:\/D:\，引擎明明在那儿却报"找不到"。

真的找不到时（引擎在很深的子目录里之类），跟智能体说一句就行：

GPT-SoVITS 在 E:\tools\GPT-SoVITS-main，帮我配上它会用 tts_config 写进 engines.gptSovits.engineRoot。不用你手改文件。

设置文件

你不用手改配置文件。 插件自己维护一份设置，存在你家目录：

~/.dsh/voice/config.json

首次加载时它会问你三个问题（声线、人设、要不要自动播报），答案直接写进去。之后想改，跟智能体说就行：

把语速调到 1.2 默认声线换成 XX 看看现在的配置

可用的键

| 键 | 作用 |
| engine | auto \| builtin \| gpt-sovits |
| defaultVoice / defaultVoiceBuiltin | 默认声线包 / 默认系统语音 |
| speed | 语速 0.5–2.0 |
| textLang | 朗读文本的语言 |
| reportBudget | 汇报保留字数 |
| keepAudio | 是否保留 wav |
| engines.gptSovits.engineRoot | GPT-SoVITS 目录 |
| engines.gptSovits.serverUrl | 或指向已运行的 API |
| engines.gptSovits.python | 指定用哪个 python |
| engines.gptSovits.version | 模型版本（v2ProPlus 等） |

优先级：用户文件 > 组合里的 config > 内置默认。部署方仍可在组合里固定值，但用户自己设的赢。

🎚 三种后端

| | 系统语音（默认） | ONNX | GPT-SoVITS |
| 安装成本 | 零 | 约 1 GB | 约 6.4 GB |
| 音质 | 清晰但机械 | 角色声线 | 角色声线、零样本克隆 |
| 报告长度一句话（生成 12 秒音频） | 瞬时 | 8.9s | 4.7s |
| 语速调节 | 支持 | 不支持 | 支持 |
| 依赖 | Windows SAPI | Python | 本地检出或远端 API |

engine: auto（默认）：有 GPT-SoVITS 就用它，没有就用 ONNX，都没有就用系统语音。登记声线包之后它会自己切，不用改配置。

想强制某一条：

tts_config set engine=onnx # 或 gpt-sovits / builtin / auto

两个后端可以共存。tts_engines 会把两边各自的可用性、缺什么、以及 ONNX 实际在跑哪个 provider 都报出来。

[!NOTE]
ONNX 的 GPU 是碰运气的。 onnxruntime 找不到 CUDA 运行库时会静默回退到 CPU，连最高 verbose 级别都不打一条日志。插件会遍历已建好的会话，把实际在用的 provider 报给你。

🔧 排错

常见问题

| 现象 | 原因 |
| 没声音但 played: true | 输出设备选错或静音 |
| System.Speech is unavailable | 系统没装 SAPI 语音，或 PowerShell 被策略拦截 |
| no GPT-SoVITS checkout found | 设 engines.gptSovits.engineRoot |
| the ONNX engine is not installed | 跑 node scripts/install-onnx.mjs |
| ONNX 报 "running on the CPU" | 正常，见下 |
| ONNX 下 speed 没反应 | ONNX 引擎没有语速控制，不是 bug |
| voice pack ... is incomplete | 声线包缺 ref.wav、ref.txt 或权重 |
| GPT-SoVITS 太慢 | 把 sampleSteps 从 32 降到 16 |

关于 ONNX 在用 CPU：如果你的 onnxruntime 是 GPU 版但会话拿到了 CPU，插件会明说。
onnxruntime 找不到 CUDA 12 / cuDNN 9 运行库时不报错、只回退，所以插件不信它报的 "可用 provider"，而是遍历已建会话问实际拿到了什么。想试 GPU：

node scripts/install-onnx.mjs --gpu
node scripts/install-onnx.mjs --check # 装完实测到底有没有生效

注意：本机实测即使把 CUDA 库加进搜索路径仍然回退到 CPU，原因未查明。 所以 --gpu 是"可以试"，不是"这样就修好了"。

先跑 tts_engines —— 它会给出后端不可用的确切原因，以及 ONNX 实际在跑哪个 provider。

环境要求

- 内置引擎：Windows（SAPI）。目前仅此平台；macOS / Linux 后端欢迎 PR
- GPT-SoVITS 引擎：Windows 或 Linux，需一个带 Python 环境的检出。显卡可选
- Node 20+

📦 开发

git clone https://github.com/fangqian616/dsh-say && cd dsh-say
npm test # 13 个测试，不出声
npm run test:audible # 真实播放检查

无构建步骤，纯 ESM JavaScript。改代码必须让 npm test 通过 —— 详见 CONTRIBUTING.md。

仓库不含任何模型权重、声音数据或音频。 参考音和声线定义在仓库里，权重单独取（单个文件 148 MB，超过 GitHub 的 100 MB 上限）。

Give your DSH agent a voice — speak and report in one you like. 默认后端就是你操作系统里已有的语音，所以第 1 步和第 2 步不用下载任何东西：不用 Python，不用 GPU，不用账号。

dsh plugin --profile web add dsh-say

重启配置档，然后让智能体「say hello out loud」。npx dsh-say 不带参数时做的是同一件事，之后会重复重启这一步，因为安装是它唯一能做的事——它没法重启你的会话。

| 工具 | 用途 |
| tts_speak | 朗读一小段话 |
| tts_report | 压缩长报告，然后朗读 |
| tts_engines | 诊断后端，返回当前生效的人设 |
| tts_voices | 列出或注册语音包 |
| tts_config | 读取和修改设置，不用编辑文件 |

报告为什么要压缩： 中文语音大约每秒 5 个字，所以 500 字的报告全文读下来要 100 秒——比直接看还慢。

配置放在 ~/.dsh/voice/config.json，由首次运行的引导流程写入，可以通过 tts_config 修改。优先级是用户文件 > 组合 > 默认值。

引擎： 内置引擎在 Windows 上驱动 SAPI，不需要外部媒体程序。
两个可选引擎能加上角色语音，auto 会优先用你已有的 GPT-SoVITS （不用下载，也是两者中更快的），然后是 ONNX 引擎，最后是系统语音。
tts_engines 会报告每个引擎在这台机器上能做什么、为什么不能，包括 ONNX 会话实际拿到的执行服务商。

角色语音（可选）

上面这些用你系统已有的语音就能跑，零下载。角色语音需要 Releases 里两个包中的一个——而且你不需要 GPT-SoVITS 也能拿到。

| | ONNX 路线 | GPT-SoVITS 路线 |
| 先要准备什么 | 什么都不用 | 一份能用的 GPT-SoVITS 检出 |
| 语音包 | sample-onnx-v2ProPlus.zip 290.8 MB | sample-full-v2ProPlus.zip 1,343.8 MB |
| 什么时候选它 | 机器上没有 GPT-SoVITS | 你已经有：不用下载，而且更快 |

两条路线跑的是同一个语音模型，只是运行时不同（onnxruntime 对 PyTorch）。

sample-full-v2ProPlus.zip 里有什么：

| | 在包里 | 内容 |
| 推理需要的四个基础模型 | 有 | chinese-roberta、chinese-hubert、s1v3、s2Gv2ProPlus，约 1.14 GB |
| 语音权重 + 参考音频 | 有 | 约 316 MB |
| GPT-SoVITS 本身 | 没有 | 需要机器上有一份能用的检出 |
| Python + torch | 没有 | 约 6 GB，按平台和 CUDA 版本区分 |

dsh-say-onnx-runtime-win-x64.zip 里有什么（便携运行时，406.7 MB）：

| | 在包里 | 内容 |
| Python 运行时 | 有 | 可重定位的 CPython 3.10 加标准库，27 MB |
| 引擎的依赖 | 有 | genie-tts、onnxruntime 等，已经装好 |
| Genie 运行时数据 | 有 | hubert 和 BERT，392 MB——所有人都一样 |
sample-onnx-v2ProPlus.zip 里有什么：

| | 是否在包里 | 内容 |
| ONNX 模型 | 是 | 9 个文件，320.4 MB |
| 参考音频 + 对应文本 | 是 | |
| 基础模型 | 不适用 | Genie-TTS 自带 hubert 和 BERT |
| GPT-SoVITS / PyTorch | 不适用 | 跑在 onnxruntime 上 |

安装

ONNX 路线 —— 机器不需要 Python，不需要 PyTorch，也不需要 GPT-SoVITS：

node scripts/install-onnx.mjs --voice

一条命令搞定。它会下载预构建的便携运行时（406.7 MB：可重定位的 Python、已装好引擎依赖、以及 Genie 的运行时数据）和声音包（290.8 MB）。总共约 697 MB。加 --with-japanese 可装日语（约 317 MB，默认关闭）。node scripts/install-onnx.mjs --check 可随时重新查看状态。

GPT-SoVITS 路线。 前提：有一份能跑的 GPT-SoVITS 代码，并装好 Python。没有的话，官方 Windows 包解压即可运行（下载，6.4 GB）。下载 sample-full-v2ProPlus.zip，然后告诉你的智能体：

install the sample audio

它会在 Downloads 里找到压缩包，解压，放好基础模型和声音权重，并注册这个包。已存在的文件会跳过，所以你调好的引擎不会被覆盖。

六段参考音频 是给你挑音色用的样本，其中一段还能拿来训练：

| reference/中立.wav + reference/中立.txt | 音频带对应文本 | 试听，并把这一对导入做微调 |
| 另外五段（开心/吃惊/生气/难过/恐惧） | 只有音频，没有文本 | 试听，挑音色 |

错误的文本比没有文本更糟，所以这五段都没有编造文本：文件名里的情绪是给听的人看的标签，不是台词本身。

安装前先读 voice/NOTICE.txt：本声音资源仅供学习交流，严禁商用；如有侵权请联系作者，24 小时内删除。

MIT · 不附带任何模型权重、声音数据或音频

代码 MIT · 角色、声音与参考音的权利归其所有者 · Code is MIT; character, voice, and reference-audio rights belong to their owners