dsh-gsv-tts

August 31, 2026 · View on GitHub

为 DSH（DeepSeek Harness）接入语音朗读能力 —— 双模式可选：云端快速体验（Edge，免安装、装上即听）+ 本地专业（GSV-TTS-Lite，音色克隆、完全离线）。

npm Downloads License

English README: README_EN.md · 变更记录: CHANGELOG.md

✨ 功能亮点

🌐 云端快速体验（Edge）：零配置、装上即用，无需 Python / 模型 / 引擎；20+ 种免费自然语言音色（晓晓、云希、Aria 等），联网即用，< 1 秒出声
🖥️ 本地专业（GSV）：按参考音频克隆目标音色、完全离线；由云端简单模式一键升级引导而来
🔊 一键朗读：每条助手消息旁的 🔊 按钮直接朗读（自动排除思考内容）；长回复按句分段渐进播放，带暂停/继续/停止与进度显示，正在朗读的消息会高亮
🔁 自动朗读：开启后自动朗读助手回复；新回复默认打断当前朗读（barge-in），可在设置中关闭
🔄 模式切换：设置面板一键在"快速体验 / 本地专业"间切换，音色与状态实时跟随
🎛️ 声音设置面板：可视化配置，保存即热生效（无需重启）；每条音色可"试听"，或"全部试听"循环对比
🎪 音色市场：从内置/自定义远端清单一键下载并注入音色，试听后安装、只读托管；内置可信源免确认，远端源二次确认
🚀 引擎一键启停 / 一键安装：本地 GSV 引擎启停（模型加载约 15~90 秒）与自动安装，均由设置面板/工具完成
🔗 同源音频短链接：合成音频落盘并同源提供，不再撑爆模型上下文

🎯 快速上手（两种模式，任选其一）

你的诉求	用哪种	怎么开始
"我就想装上就能听"	🌐 快速体验（Edge）	见下方「一、快速体验模式」——无需任何安装
"我要克隆自己的声音 / 完全离线"	🖥️ 本地专业（GSV）	见下方「二、本地专业模式」

默认模式：全新安装默认为 Edge 快速体验（联网即用）；从旧版本升级的老用户仍保持 GSV 本地模式、声音不变，可随时在设置面板切换。

一、快速体验模式（Edge，新装默认）

安装插件并重启 DSH（见「📦 安装」）
打开设置 → 声音设置 → TTS 模式选 快速体验（Edge）
"音色"下拉选一个云端音色（晓晓 / 云希 / Aria…）
点任意助手消息旁的 🔊 —— 立即出声，< 1 秒

无需安装 Python、无需模型、无需启动引擎。仅需联网。云端音色标注 🌐，为您提供免配置即听的入口。

二、本地专业模式（GSV）

安装插件并重启 DSH（见「📦 安装」）
打开设置 → 声音设置 → TTS 模式选 本地专业（GSV）
安装引擎：让 agent 调用 tts_setup_engine，或见「🔧 安装 GSV-TTS-Lite 引擎」
启动引擎：打开"启动引擎"开关，等待状态变为"运行中"
添加音色：在"音色预设"添加，或从「🎪 音色市场」一键下载，或克隆
点任意助手消息旁的 🔊，或让 agent 调用 tts_speak

本地模式全程离线运行，支持音色克隆，不依赖网络与云端配额。

📦 安装

两种方式任选其一，然后在设置中启用：

# 方式一：从 npm 安装
dsh plugin --profile web add dsh-gsv-tts

# 方式二：从 GitHub 安装
dsh plugin --profile web add "github:TaoruiLiu19/dsh-gsv"

关于 profile：以上以 web profile 为例；当前桌面应用常用 desktop profile，把命令里的 web 换成 desktop 即可。

安装后重启 DSH，工具自动注册到 agent，设置中出现"声音设置"项。

依赖 DSH 的 webServer 服务（Web / Desktop profile 自带）提供音频下载；settings 服务提供设置面板。无这些服务的环境仅保留工具能力。

🔄 模式切换与迁移

项	说明
如何切换	设置 → 声音设置 → TTS 模式（快速体验 / 本地专业），切换即时生效
配置项	`provider: 'edge' \| 'gsv'`（初始化分派，建议经设置面板切换，勿手动改）
老用户升级	无 `provider` 字段的旧配置 → 保持 `gsv` 本地模式，声音不变
全新安装	默认 `edge` 云端简单模式，联网即用
`schemaVersion`	配置结构版本，迁移守卫的落点

Edge 模式需联网；若云端不可用，面板会提示"云端通道拥挤 / 暂不可用"，本地 GSV 模式始终可用作降级。

🏗️ 系统架构

dsh-gsv-tts 系统构成与数据流

📖 交互式架构图：打开 dsh-gsv-tts.architecture.html（支持缩放、聚焦、主题切换）

双 provider 架构：TTSService 按 config.provider 分发到云端（Edge）或本地（GSV），朗读主链路与工具调用两条路径对两种 provider 一致。

🔊 朗读主链路（经 webServer）：用户点击 🔊 → DSH Web 客户端 → webServer 的 /speak 路由 → TTSService 按 provider 请求 → 云端/本地引擎返回音频块 → AudioStore 落盘 → 同源短链接回传浏览器播放。
🤖 Agent 工具调用（宿主内直连）：Agent 调用 tts_speak 等工具时，由宿主进程内 tools 服务直接执行，不经 webServer HTTP 网关。

构成	说明
DSH 应用（DeepSeek Harness）	插件宿主：Web 客户端、webServer、settings 服务
dsh-gsv-tts 插件	`TTSService`（按 provider 分发）/ `AudioStore`（落盘）/ 引擎管理（启停·安装·健康检查）
Edge provider	`edge-tts-universal`，微软精选网络音色，返回 MP3 流（浏览器解码）
GSV-TTS-Lite 本地引擎	本机 Python 进程，FastAPI :9880，真流式 `/tts/stream`，返回 WAV

📸 截图

声音设置面板

设置 → 声音设置：TTS 模式、引擎开关、音色配置、健康状态

消息操作区的 🔊 朗读按钮（悬停显示"朗读结果"）

引擎运行中

本地引擎启动后的"运行中"状态

🌐 快速体验模式（Edge）详解

音色：20+ 种微软精选自然音色（中文晓晓 / 云希 / 云野等，英文 Aria 等），面板下拉即选，无需配置。
输出：MP3 音频流，由 edge-tts-universal 生成，经 AudioStore 落盘为 .mp3 并同源提供，浏览器直接解码（无转码开销）。
健康检测：内置连接超时、令牌自动刷新与错误恢复；面板显示云端可用状态。
限流与降级：微软可能对过量使用限流。若检测到云端不可用，面板会引导切到本地 GSV（无限量 + 可克隆）。
配额字段：quotaDaily（默认 null = 不限量）为预留引导字段，硬配额待后续版本。

🖥️ 本地专业模式（GSV）详解

能力：按参考音频克隆目标音色；完全离线运行，数据不出本机。
成本：需安装 Python 环境 + 下载模型；首次模型加载约 15~90 秒。
入口：见「🔧 安装 GSV-TTS-Lite 引擎」与「🎙️ 添加音色 / 音色市场」。

🔧 安装 GSV-TTS-Lite 引擎

方式一：自动安装（推荐）

让 agent 调用 tts_setup_engine，自动完成：检测 Python → 安装 gsv-tts-lite==0.4.7 → 克隆仓库 → 安装依赖 → 部署流式 API → 启动服务。

方式二：手动安装

安装 Python 3.10+（推荐 3.12），确保 pip 可用
安装核心包：pip install gsv-tts-lite==0.4.7
克隆仓库：git clone https://github.com/chinokikiss/GSV-TTS-Lite.git
安装 API 依赖：pip install -r <仓库>/API/requirements.txt
把本插件 scripts/ 下的 dsh_stream_api.py 复制到 <仓库>/API/ 目录（真流式 API）
下载模型（s1v3.ckpt、s2Gv2ProPlus.pth 等）放入 <仓库>/models/
启动：python <仓库>/API/dsh_stream_api.py -p 9880 --models_dir <仓库>/models
在设置 → 声音设置打开引擎开关验证

引擎示例音频位于 <仓库>/examples/（laffey.mp3、AnAn.ogg），可直接用作测试音色。

🎪 音色市场

从音色市场一键下载并注入音色，无需手动填写参考音频路径。

🌐 在线试听网站：https://taoruiliu19.github.io/gsv-market/ —— 浏览、试听、下载市场中的全部音色，无需安装插件。

打开设置 → 声音设置 → 音色市场
浏览音色卡片（来源、作者、许可），点试听预听
点安装：
- 内置可信清单（trusted）→ 直接安装
- 自定义远端清单（voiceRegistryUrl）→ 二次确认来源与许可后安装
安装后音色自动加入"音色预设"，即可在 🔊 / tts_speak 中选用
市场安装的音色在面板中只读（仅可卸载），防止误改破坏账本；点卸载可（提示）同时删除本地音频

信任规则（A+ 混合模式）：包内 docs/voices.json 收录的音色始终视为 trusted（随包发布已审计），即便经远端清单展示也免确认；远端清单中新增的音色（包内未收录）一律二次确认。合并时以 id 为键，包内优先，远端只补充新 id。自定义音色请在"音色预设"手工添加。

🎙️ 添加音色（本地 GSV）

打开设置 → 声音设置
"音色预设"下点击"添加音色"
填写四个字段：

字段	说明	示例
`音色名称`	音色名，`tts_speak` 与 🔊 按钮按它选择	`拉菲`
`参考音频路径`	目标音色参考音频（决定声音像谁）	`D:\GSV\GSV-TTS-Lite\examples\laffey.mp3`
`提示音频路径`	语调/情感参考音频	`D:\GSV\GSV-TTS-Lite\examples\AnAn.ogg`
`提示文本`	提示音频对应的文字（引擎不支持留空自动转写，务必填写）	`ちが……ちがう。レイア、貴様は間違っている。`

点击"保存"，立即生效，无需重启
默认音色留空则使用列表第一个音色

参考音频路径必须是引擎服务端能访问的本地路径或可访问 URL。

⚙️ 声音设置说明

字段	说明	默认值
TTS 模式	快速体验（Edge 云端，免安装）/ 本地专业（GSV，离线/克隆）	老用户 `gsv` / 新装 `edge`
引擎开关	启动/停止 GSV-TTS-Lite 引擎进程	关
`apiUrl`	引擎 API 地址	`http://localhost:9880`
`defaultVoice`	默认音色（gsv=预设名 / edge=云端音色 id，留空用第一个）	空
`timeout`	请求超时（毫秒）	`30000`
`installDir`	引擎安装目录	`./GSV-TTS-Lite`
`autoPlay`	自动朗读助手回复	`false`
`interruptOnNew`	自动朗读时新回复是否打断当前朗读（关闭则朗读中跳过，避免叠音）	`true`
`voiceRegistryUrl`	音色市场远端清单地址（默认指向在线试听站点；留空仅用包内离线清单）	站点 URL
`provider`	`gsv` \| `edge`（初始化分派，勿手动改；设置面板切换）	见"TTS 模式"
`schemaVersion`	配置结构版本（迁移守卫落点）	`1`
`quotaDaily`	云端简单模式每日配额（`null`=不限量，仅引导用）	`null`
`voices`	音色预设列表	空

配置保存在 DSH 的 settings（~/.dsh/settings.yaml 的 dsh-gsv-tts: 段），修改后插件热生效。

🧰 工具列表

工具	功能
`tts_speak`	文本转语音；按当前 provider 与音色选择，流式合成返回同源短链接
`tts_list_voices`	列出当前 provider 可用音色
`tts_health_check`	检查当前 provider（引擎/云端）状态
`tts_setup_engine`	一键安装本地 GSV-TTS-Lite 引擎

❓ 常见问题

装上怎么直接出声？：默认 Edge 模式，无需任何安装，设置面板选音色即可；本地模式才需要装引擎。
引擎未启动（本地模式）：设置 → 声音设置 → 打开引擎开关（模型加载约 15~90 秒）。
模型缺失：首次启动会提示，把模型放入 models 目录。
朗读按钮报"语音引擎未启动"：如果你用的是本地 GSV 模式，先到声音设置启动引擎；不想装引擎就切回 Edge 云端模式。
云端音色有的读不了？：确认网络畅通；云端通道受限时可切本地 GSV。
参考音频不可用：必须是引擎服务端可访问的本地路径或 URL。

🛠️ 技术栈

DSH 插件框架：Cordis + @deepseek-ai/dsh-tools
配置 Schema：@deepseek-ai/schemastery
设置面板：@deepseek-ai/dsh-settings + 客户端 settings.section 插槽
云端 Provider：edge-tts-universal（微软网络音色，MP3 流）
本地引擎：GSV-TTS-Lite 0.4.7
语言：TypeScript（宿主）/ 手写客户端 bundle（浏览器）/ Python（本地流式 API）

📦 构建与发布

pnpm install
pnpm build        # 编译宿主代码（lib/）
pnpm publish      # 发布到 npm（files: lib, scripts, cordis.patch.yml）

从 GitHub 安装会自动执行 prepare 脚本编译；lib/client.js 为手写客户端 bundle，随仓库发布。

更多发布细节见 docs/PUBLISHING.md。

📜 变更记录

完整更新历史见 CHANGELOG.md。

⚠️ 已知限制

播放为 markdown 链接点击播放；内嵌 <audio> 需客户端扩展（规划中）
合成音频存于系统临时目录（%TEMP%/dsh-gsv-tts），启动清空、会话内最多 200 个
Edge 云端模式依赖网络；微软限量限流时可能不可用（已有降级引导）
tts_setup_engine 通过 child_process 执行 pip/git，需环境有对应工具
promptText 留空依赖引擎 ASR 能力（能力探测），不支持时合成报错

📄 License

本项目以 MIT 许可证 开源发布。

本项目按"原样"提供,不附带任何明示或默示保证。完整许可条款见 LICENSE 文件。