dsh-plugin-tts
## 跳转
- **[English README](README.md)**（English，与本页逐节对应）
- **[使用手册（执行手册）](docs/USER-GUIDE.md)**（第一次用，逐步骤上手）
- **[RVC 自定义音色指南](docs/RVC-GUIDE.md)**（自定义音色 · 分块渐进播放 · 紧凑索引 · 音色包 · 便携运行时）
- **[Index-TTS2 指南](docs/INDEX-TTS2-GUIDE.md)**（本机参考音频音色）
- **[CosyVoice 指南](docs/COSYVOICE-GUIDE.md)**（本机提示音频零样本克隆，CosyVoice-2.0-0.5B）
- **[Cloud TTS 指南](docs/CLOUD-GUIDE.md)**（谷歌付费音色 · API Key · 用量与计费口径）
- **[Edge TTS 指南](docs/EDGE-GUIDE.md)**（默认在线朗读）
- **[自适应分块设计文档](docs/adaptive-chunked-playback.md)**（长文无缝朗读的设计与实测）
---
# dsh-plugin-tts — Edge TTS + RVC / Index-TTS2 / CosyVoice / Cloud 语音大集成
DeepSeek Harness 语音插件：给 AI 回复加朗读——开箱即用微软免费在线音色（Edge TTS），
也能用**你自己训练的 RVC 音色**、**本机 Index-TTS2 参考音频音色**、**本机 CosyVoice
提示音频零样本克隆**或**谷歌 Cloud TTS 付费音色**朗读；长回复**自适应分块渐进播放、
段间无缝**；音色可**从音色包仓库一键安装**；还提供**免装 RVC WebUI 的便携运行时**。
> 📖 **第一次用？看[《使用手册（执行手册）》](docs/USER-GUIDE.md)**——每一步都有
> "做什么 / 怎么做 / 怎么算成功"，从朗读、RVC 音色到音色包下载全覆盖。
## 功能
1. **消息朗读按钮**：每条 AI 回复左下角操作行新增「朗读」按钮，点击朗读该条消息
（按钮显示音柱跳动动画），再次点击停止。
2. **自动朗读开关**：输入框左下角的喇叭按钮；开启后每条新完成的 AI 回复自动朗读
（按钮带圆形高亮），关闭则不自动朗读。
3. **语音设置面板**：侧边栏「设置 → 插件」新增「语音」标签页：
- **TTS提供者**：Edge TTS（免费在线）/ 自定义音色（RVC）/ 本地音色（Index-TTS2）/ 本地克隆（CosyVoice）/ Cloud TTS（谷歌付费）
- **朗读音色**：22 个经实测可用的 Edge TTS 音色（默认 晓萱 zh-CN-XiaoxuanNeural）；
Cloud 组 8 个 cmn-CN 音色（默认 cmn-CN-Wavenet-A，也可手输 voice id）
- **声音调节**：语速 / 音调 / 音量（0 = 默认，Edge 与 Cloud 共用）
- **RVC 配置**：服务地址 + 模型（.pth）/ 索引（.index）选择、原声音色、声音调节与高级参数——详见[《RVC 指南》](docs/RVC-GUIDE.md)
- **Index-TTS2 配置**：服务地址（默认 7880）+ 参考音色选择/刷新/上传 + 朗读前清洗开关 + 情感控制 + 采样参数——详见[《Index-TTS2 指南》](docs/INDEX-TTS2-GUIDE.md)
- **CosyVoice 配置**：服务地址（默认 7890）+ 提示音频选择/刷新/上传 +
提示文字稿（必填，按顺序全文填写）+ 语速（0.5–2.0）+ 随机种子（0 = 随机）——详见[《CosyVoice 指南》](docs/COSYVOICE-GUIDE.md)
- **Cloud 配置**：API Key（只存本机 Host 文件，输入框写后即清）+ Project ID（可选）+
测试连接 + 本月分档用量（Standard 400 万 / Wavenet·Neural2·Chirp3 各 100 万）——详见[《Cloud 指南》](docs/CLOUD-GUIDE.md)
- **音色包**：从音色包仓库一键下载安装音色
- **试听测试**：输入文本 + 播放按钮（播放中显示旋转 loading，可点击停止；失败时红字提示）
4. **RVC 自定义音色**：用你自己训练的 RVC 模型朗读，全程本机计算，支持
免索引模式、高级参数（详见[《RVC 指南》](docs/RVC-GUIDE.md)）。
5. **长文本无缝朗读**：自适应分块渐进播放——探测校准块大小、边播边合成、Web Audio
采样级拼接、段间无停顿（详见[设计文档](docs/adaptive-chunked-playback.md)）。
6. **朗读时 mini 播放器**：暂停/继续 + 倍速（1x / 1.25x / 1.5x），分块长读显示可见的
「第 x/y 段」计数。
7. **主题化 tooltip + RVC 首次引导**：悬浮提示用主题 token（`--dsw-*`）渲染；RVC 面板顶部
内嵌首次使用三步引导（分 OS 启动命令 + 一键诊断）。
8. **音频下载**：每条消息操作行新增下载按钮保存合成音频——Edge/Cloud 读出 MP3，
本地链路（RVC/Index-TTS2/CosyVoice）读出 WAV；复用进程内缓存，刚读过的消息一点即下。
分段长文目前没有单个输出文件，会提示"暂不支持导出"而非做无用功的重合成。
9. **朗读选中文本**：在消息里选中文本会在选区上方出现「朗读选中」悬浮按钮，点按只朗读该选中片段。
10. **长读流式（Edge 同样支持）**：纯 Edge 长文本也走自适应分块渐进播放——第一块先响、其余边播边合成，
不再干等整段合成完成。
11. **审批语音提醒**：可选地把 Agent 审批事件用语音播报。开启后：审批请求（`approval/asked`）会
**打断当前朗读**（Agent 正在等这个决定），审批结果（`approval/decided`）仅在空闲时播报。
播报固定走 Edge TTS（不依赖 RVC 服务）、用自己的提醒音色、按审批 id 去重、默认关闭。
（范围说明：任务完成播报留待后续阶段——jobs 子系统目前没有本插件可观察的会话事件通道。）
12. **干净朗读、RVC 静默**：朗读前清洗消息 Markdown（代码块、表格、链接、引用、任务列表），
不再读出一堆符号；可选「朗读原始 Markdown 符号」开关保留逐字朗读（适合读源码）。
Edge 模式下 RVC 面板完全隐藏，只留一行「需要克隆音色？」入口，普通朗读零配置零感知。
## 要求
- DeepSeek Harness `web` profile（`dsh web`）
- Node.js ≥ 22（worker 使用原生 `WebSocket`）
- 仅**本地音色链路**需要额外准备（Edge/Cloud 开箱即用）：
- **RVC 自定义音色**：本机 RVC 推理环境（RVC WebUI 或便携运行时，
并在使用前启动 `rvc-server.py`）——见[《RVC 指南》](docs/RVC-GUIDE.md)
「启动本地 RVC 服务」和[《使用手册》](docs/USER-GUIDE.md) §4.2，macOS 用户同样先看这里。
- **Index-TTS2 音色**：本机 `index-tts2-nvidia` 包的 API 服务
（`启动api服务.bat`，默认端口 7880）——见[《Index-TTS2 指南》](docs/INDEX-TTS2-GUIDE.md)。
- **CosyVoice 克隆**：本机 CosyVoice-2.0-0.5B 包的 `cosy-server.py`
（`启动cosy服务.bat`，默认端口 7890）——见[《CosyVoice 指南》](docs/COSYVOICE-GUIDE.md)。
## 安装
四种等价方式（任选其一）：
```sh
# dsh-market 界面：在 market 里搜索插件名安装
# npm 包：
dsh plugin --profile web add "@memef1f1y/dsh-plugin-tts"
# GitHub 源码：
dsh plugin --profile web add "github:1624318455/dsh-plugin-tts#main"
# 或本地开发：
dsh plugin --profile web add "file:/path/to/dsh-plugin-tts/plugin"
```
重启 `dsh web` 后作为 profile bundle 自动加载，无需手动启用。
注意先卸载已有的再装另一种来源：它们注册的是同一个 loader 条目 id（`tts`），
安装器遇到重复 id 会直接回滚而不是覆盖。
## 可用音色（经实测，Edge TTS）
| 区域 | 音色 |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 简体中文 | 晓萱 Xiaoxuan · 晓伊 Xiaoyi · 云希 Yunxi · 云扬 Yunyang · 晓晓 Xiaoxiao · 云健 Yunjian · 云夏 Yunxia · 晓北(辽宁) liaoning-Xiaobei · 晓妮(陕西) shaanxi-Xiaoni |
| 台湾 | 曉臻 HsiaoChen · 曉雨 HsiaoYu · 雲哲 YunJhe |
| 香港 | 曉佳 HiuGaai · 曉曼 HiuMaan · 雲龍 WanLung |
| 英文 | Aria · Jenny · Guy · Sonia(英) |
| 日/韩/法 | 七海 Nanami · SunHi · Denise |
> 注：Xiaohan / Xiaomeng / Xiaorui / Xiaoshuang 等旧音色已被 Edge 端点移除（返回
> `1007 Unsupported voice`），未列入。
## 架构
| 层 | 位置 | 职责 |
| ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Host | `lib/index.mjs` | 注册 webServer 路由：`/dsh-tts-api/speak`（全链路合成/分块队列）、`/dsh-tts-audio/`（音频字节）、`/dsh-tts-api/rvc-next`（取下一段/取消任务）、`/dsh-tts-api/rvc-files` + `/rvc-compact-index` + `/rvc-packs*`（RVC 服务代理/音色包）、`/dsh-tts-api/index-*` 与 `/dsh-tts-api/cosy-*`（本地服务代理+配置）、`/dsh-tts-api/cloud-*`（Cloud Key/用量/连通测试）、`/dsh-tts-api/notify`（审批提醒队列）、`/dsh-tts-api/diagnose`（一键诊断）；用 `node -e` 运行零依赖 Edge worker |
| Client | `lib/client.js` | `shell.overlay` 里的 Web Audio 分块播放器（采样级拼接，`