fangqian616/dsh-say

dsh-say

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

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

---

⚡ 三分钟上手

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

1 · 装插件

npx dsh-say

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

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

dsh plugin --profile web add dsh-say

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

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

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 根目录的 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 模型和声线权重、登记声线包。已经存在的文件会跳过。

一条命令，不用传路径 —— 它会去 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 上限）。

---

English

Give your DSH agent a voice — speak and report in one you like.

The default backend is whatever speech voices your operating system already has, so step 1 and 2 need no download: no Python, no GPU, no account.

dsh plugin --profile web add dsh-say

Restart the profile, then ask the agent to "say hello out loud". npx dsh-say does the same thing with no arguments and then repeats the restart step, because installing is all it can do — it cannot restart your session.

Tool	Purpose
tts_speak	Speak a short line
tts_report	Compress a long report, then speak it
tts_engines	Diagnose backends, return the active persona
tts_voices	List or register voice packs
tts_config	Read and change settings without editing files

Why reports are compressed: Chinese speech measures about 5 characters per second, so a 500-character report read in full takes 100 seconds — slower than reading it.

Configuration lives in ~/.dsh/voice/config.json, written by first-run onboarding and editable through tts_config. Precedence is user file > composition > default.

Engines: the built-in one drives SAPI on Windows and needs no external media program. Two optional engines add character voices, and auto prefers a GPT-SoVITS you already have (no download, and the faster of the two), then the ONNX engine, then the system voices. tts_engines reports what each one can do here and why not, including the execution provider the ONNX sessions actually got.

The character voice (optional)

Everything above works with the voices your system already has, at zero download. A character voice needs one of the two bundles from Releases — and you do not need GPT-SoVITS to get one.

	The ONNX route	The GPT-SoVITS route
What you need first	nothing	a working GPT-SoVITS checkout
Voice bundle	sample-onnx-v2ProPlus.zip 290.8 MB	sample-full-v2ProPlus.zip 1,343.8 MB
When to pick it	no GPT-SoVITS on the machine	you already have one: no download, and faster

Both routes run the same voice model; only the runtime differs (onnxruntime against PyTorch).

What is in sample-full-v2ProPlus.zip:

	In the bundle	Contents
the four base models inference needs	yes	chinese-roberta, chinese-hubert, s1v3, s2Gv2ProPlus, about 1.14 GB
voice weights + reference clip	yes	about 316 MB
GPT-SoVITS itself	no	needs a working checkout on the machine
Python + torch	no	about 6 GB, per-platform and per-CUDA

What is in dsh-say-onnx-runtime-win-x64.zip (the portable runtime, 406.7 MB):

	In the bundle	Contents
a Python runtime	yes	relocatable CPython 3.10 plus its stdlib, 27 MB
the engine's dependencies	yes	genie-tts, onnxruntime and the rest, already installed
Genie runtime data	yes	hubert and BERT, 392 MB - the same for everyone

What is in sample-onnx-v2ProPlus.zip:

	In the bundle	Contents
the ONNX model	yes	9 files, 320.4 MB
reference clip + its transcript	yes
base models	n/a	Genie-TTS ships its own hubert and BERT
GPT-SoVITS / PyTorch	n/a	runs on onnxruntime

Installing it

ONNX route — the machine needs no Python, no PyTorch and no GPT-SoVITS:

node scripts/install-onnx.mjs --voice

One command. It downloads a prebuilt portable runtime (406.7 MB: a relocatable Python, the engine's dependencies already installed, and Genie's runtime data) and the voice bundle (290.8 MB). About 697 MB in total. Add --with-japanese for Japanese (about 317 MB, off by default). node scripts/install-onnx.mjs --check re-reports the status at any time.

GPT-SoVITS route. Prerequisite: a working GPT-SoVITS checkout with Python. Without one, the official Windows package unzips and runs as-is (download, 6.4 GB). Download sample-full-v2ProPlus.zip, then tell your agent:

install the sample audio

It finds the archive in Downloads, unpacks it, places the base models and the voice weights, and registers the pack. Files that already exist are skipped, so your tuned engine is never overwritten.

The six reference clips are samples for picking a tone, and one of them is also trainable material:

reference/中立.wav + reference/中立.txt	audio with its transcript	audition it, and import the pair to fine-tune
the other five (开心/吃惊/生气/难过/恐惧)	audio only, no transcript	audition them to pick a tone

A wrong transcript is worse than a missing one, so none is invented for the five: the emotion in the filename is a label for the listener, not the line being spoken.

Read voice/NOTICE.txt before installing: this voice resource is for learning and exchange only; commercial use is strictly prohibited; if it infringes any right, contact the author and it will be removed within 24 hours.

---

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

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