# dsh-plugin-tts 使用手册（执行手册）

> 这本手册写给"不想看技术文档"的人。每一步都写明：**做什么 → 为什么 → 怎么做 → 怎么知道成功了**。
> 你可以只读自己需要的部分：
> - **只想让 AI 回复能朗读** → 看第 3 节（约 5 分钟）
> - **想用自己训练的音色朗读** → 看第 4 节（约 30 分钟，含 4.2 的服务启动）
> - **想下载别人分享的音色** → 看第 5 节（约 10 分钟）
> - 出问题 → 看第 7 节（按症状查）和第 8 节（术语字典）

---

## 0. 这个插件到底做什么？

一句话：**让你的 AI 回复能被读出来，而且能把朗读的声音换成你喜欢的音色。**

- 每条 AI 回复下面多一个 🔈 喇叭按钮：点一下朗读，再点一下停止；
- 输入框左边有一个喇叭开关：打开后，每条新回复**自动朗读**；
- 朗读的声音可以是微软的免费音色（Edge TTS），也可以是**你自己训练的 RVC 音色**，
  或**从网上下载的音色包**。

全程在你自己的电脑上运行（除了微软在线朗读本身），你的声音模型不会上传到任何地方。

---

## 1. 安装（只有第一次需要）

**前提**：你已经在用 DeepSeek Harness 的网页版（`dsh web`）。

1. 打开一个终端（PowerShell 或命令提示符），执行：

   ```sh
   dsh plugin --profile web add "github:1624318455/dsh-plugin-tts#main"
   ```

2. **完全关闭再重新启动 `dsh web`**（不是刷新页面）。
3. 验证成功：打开网页 → 侧边栏 **设置 → 插件**，出现「**语音**」标签页。

> 想开发/本地安装：`dsh plugin --profile web add "file:D:/Work/ForAI/dsh-plugin-TTS/plugin"`
> （Windows 下是复制安装，改代码后要把 `lib/` 再复制进 profile 副本并重启，详见 README「开发」）。

---

## 2. 先认识界面上的三个地方

| 位置 | 长什么样 | 干什么 |
|---|---|---|
| 每条 AI 回复左下角 | 🔈 喇叭按钮 | 朗读这一条 / 再点停止 |
| 输入框左下角（命令按钮旁边） | 🔈 喇叭开关 | 开启后新回复自动朗读（有圆环高亮 = 已开） |
| 侧边栏 设置 → 插件 → 语音 | 设置面板 | 换声音、调语速、试听、配 RVC、下载音色包 |

---

## 3. 第一步：让回复能朗读（Edge TTS，开箱即用）

1. 打开任意对话，问一句话，等 AI 回复完成。
2. 在回复的左下角找到 🔈 按钮，**点一下**。
   - 成功：开始朗读，按钮变成跳动的音柱；再点一下停止。
3. 试试自动朗读：输入框左边点 🔈 开关（出现高亮 = 已开启）。
   之后每条新回复完成时会自动朗读。
4. 想换声音 / 调快慢：**设置 → 插件 → 语音** →
   - 「朗读音色」：下拉选一个喜欢的声音（中文/英文/日文…都有）；
   - 「声音调节」：语速 / 音调 / 音量，0 表示默认；
   - 最下面「试听测试」：输入一句话点 ▶，马上听效果。

> 到这里，基本功能已经会用了。如果只想朗读，可以不用看后面。

---

## 4. 第二步：用你自己的音色（RVC）

> RVC 是什么：一个"声音转换"工具。你的 AI 先让 Edge TTS 朗读（这是"原声"），
> 然后 RVC 把这段朗读**换声**成你训练的模型音色。全程在你自己的电脑上完成。

### 4.1 你需要先有的东西

| 需要 | 是什么 | 必须吗 |
|---|---|---|
| RVC 模型文件（`.pth`） | 你的音色本体（通常几 MB~几十 MB） | ✅ 必须 |
| 索引文件（`.index`） | 让音色更像原声的辅助文件（几百 MB，可压缩） | ❌ 可选 |
| RVC WebUI 安装 **或便携运行时** | 转换服务要跑在它里面；没有 RVC WebUI 也能用便携运行时 | ✅ 二选一 |

### 4.2 启动"转换服务"（一次性；每次想用时都要先启动）

**没有装 RVC WebUI？** 可以下载别人做好的**便携运行时**（一个免安装的文件夹，
含转换所需的一切，Windows 双击 `启动服务.bat`，macOS/Linux 运行 `start-rvc-server.sh`；
详见手册末尾「便携运行时」）。

按你的系统操作：

#### Windows（已装 RVC WebUI）

1. 找到你的 RVC WebUI 安装目录（里面能看到 `runtime` 文件夹和 `assets` 文件夹）。
2. 打开 **PowerShell 或命令提示符**，启动服务（**不需要指定模型/索引**——模型在设置面板里点「浏览」选择，
   首次朗读自动加载；`--model/--index` 只是可选的预载参数）：

   - **推荐**：把 `rvc-server.py` 复制到 RVC 根目录（与 `runtime/` 同级），然后：

     ```powershell
     <你的RVC目录>\runtime\python.exe <你的RVC目录>\rvc-server.py --port 4892
     ```

   - 或者 rvc-server.py 放在别处时，用 `--rvc-dir` 指定 RVC 根目录：

     ```powershell
     <你的RVC目录>\runtime\python.exe <rvc-server.py的路径> --rvc-dir "<你的RVC目录>" --port 4892
     ```

#### macOS / Linux

- **最省事：便携运行时**。解压后运行：

  ```bash
  <你的便携包目录>/start-rvc-server.sh
  ```

- **已有自己搭好的 RVC 环境**：

  ```bash
  <你的工作目录>/venv/bin/python <你的工作目录>/rvc-server.py --port 4892
  ```

- **已有 RVC WebUI 目录**（含 `runtime/` 和 `infer/`）：

  ```bash
  <你的RVC目录>/runtime/bin/python <你的RVC目录>/rvc-server.py --port 4892
  ```

#### 通用

- `<你的RVC目录>` = RVC WebUI 根目录（含 `runtime`/`assets`/`logs`）；`<rvc-server.py的路径>` = rvc-server.py
  文件所在位置（插件源码目录，或从 GitHub 仓库 `1624318455/dsh-plugin-tts` 下载，**不在** node_modules 里）。
- 想要"启动即预载某个音色"再额外加：
  `--model "<RVC目录>/assets/weights/xxx.pth" --index "<RVC目录>/logs/xxx.index"`。

3. **成功的样子**：终端/命令行窗口里出现一行
   `dsh-plugin-tts RVC server: http://127.0.0.1:4892 ...`，
   然后**这个窗口别关**（关了服务就停了）。
4. 想换模型时：关掉窗口，换 `--model` 再启动一次。

### 4.3 在插件里填配置

打开 **设置 → 插件 → 语音**：

1. 「TTS提供者」选 **自定义音色（RVC）**；
2. 「服务地址」：**保持默认** `http://127.0.0.1:4892`（就是刚才那个服务的地址）；
3. 「模型路径 (.pth)」：填模型文件的**完整路径**，或点「浏览」从电脑上选；
4. 「索引路径 (.index)」：**可留空**（免索引，效果略降但能用）；有就填上；
5. 「原声来源」：保持「让 Edge TTS 先读一遍」即可（想用自己录音就选上传）。

### 4.4 测试

1. 回到最下面「试听测试」，输入一句话，点 ▶。
2. **成功**：几秒后（首次可能十几秒，是在加载模型+自动测速）听到**你的音色**在朗读。
3. **失败**：出现红字提示 → 对照第 7 节的排查表。

### 4.5 长文本自动分段

选 RVC 后读很长的回复，插件会自动**分段边合成边播放**：先转换前几段立刻开播，
其余段在播放的同时后台转换，段与段之间**没有停顿**（右上角按钮会显示「第 x/y 段」）。
首次长文本会做一次约 5~7 秒的自动测速（决定分段大小），之后 7 天内不再重复。

---

## 5. 第三步：下载别人分享的音色（音色包）

> 音色包 = 模型 + 可选的紧凑索引 + 说明，打成一个"仓库"，一个网址就能分享。

1. 从音色作者那里拿到一个**仓库地址**（形如 `https://example.com/tts-packs` 的网址）。
2. 打开 **设置 → 插件 → 语音 → 音色包**：
   - 「仓库地址」粘贴网址 → 点「**获取列表**」；
   - 出现一张张音色卡片（名称 / 描述 / 大小 / 许可 / 作者）。
3. 点「**下载并启用**」：插件自动下载（并自动核对文件是否完整、有没有被改坏），
   完成后**自动填好模型和索引路径**，直接去试听即可。
4. 已安装的包会显示版本号；重复下载会自动跳过。
5. ⚠️ 注意：只看「许可」允许分发的音色。演示音色 azusa-test 受版权限制，
   不会出现在公开仓库里；你自己训练的模型也可以做成音色包分享。

> 本地测试仓库：`node tests/mock-registry.mjs <目录> [端口]` 可以把一个文件夹当成仓库起起来。

---

## 6. 日常使用小知识

- **停止朗读**：再点一次喇叭按钮；关闭自动朗读开关会停止自动朗读（不影响手动）。
- **长回复**：自动分段、边读边合成，进度显示「第 x/y 段 · 边播边合成」。
- **换会话 / 关页面**：自动朗读会停止。
- **设置不保存**：声音/开关等设置存在内存里，刷新页面会恢复默认（音色包安装的文件会保留）。

---

## 7. 出问题了？按症状查

| 症状 | 最常见原因 | 怎么办 |
|---|---|---|
| 点朗读没声音 | 浏览器自动播放限制 | 先在页面任意处点一下再试；检查系统音量 |
| 点「浏览」提示"浏览文件需要先启动本地 RVC 服务" | 4.2 那个服务没启动 / 服务地址不对 | 按 4.2 启动并保留窗口；确认「服务地址」是 `http://127.0.0.1:4892` |
| 提示"无法连接本地 RVC 推理服务" | 4.2 那个服务窗口没开 / 被关了 | 重新启动服务窗口（4.2），别关它 |
| 提示"未配置 RVC 模型路径" | 4.3 没填模型 | 填 .pth 路径（或点浏览） |
| 首次朗读等十几秒 | 正常：加载模型 + 自动测速 | 等它；之后会快 |
| 音色不够像 | 没填索引，或索引权重太低 | 填 .index；「索引权重」调向 100% |
| 报 403 / 合成失败（Edge 模式） | 微软端点临时限制 | 过一会儿重试；看 README 疑难排查 |
| 试听按钮一直转 | 网络或服务没起来 | 看红字提示；确认 4.2 窗口在运行 |

---

## 8. 术语小字典（看见不懂的词查这里）

| 词 | 是什么意思 |
|---|---|
| Edge TTS | 微软的免费在线朗读服务（本插件默认的声音来源） |
| RVC | 一个"声音转换"工具：把朗读声换成目标音色 |
| 模型（.pth） | 你的音色本体文件 |
| 索引（.index） | 让音色更像原声的可选文件；很大，但可以压缩 |
| 紧凑索引 | 把几百 MB 的索引缩到几 MB（设置里「压缩索引」按钮） |
| 免索引 | 不填索引直接用（效果略降，但省事） |
| 音色包 | 模型+索引+说明打包，一个网址即可分享（见第 5 节） |
| 仓库地址 | 音色包清单（manifest.json）所在的网址 |
| sha256 | 文件的"指纹"；下载后自动核对，防止文件损坏或被改 |
| 原声 / 原声来源 | 转换前的朗读（Edge TTS 读的，或你上传的音频） |
| 底噪 | 上面"原声"的技术叫法；界面里已改成"原声" |

---

## 9. 进阶：给音色作者 —— 怎么做一个音色包

1. **准备文件**：模型 `model.pth`；可选一个紧凑索引（用设置里「压缩索引」生成，
   10k ≈ 31MB）。
2. **建一个目录**（例如 `my-voice/`），放入 `model.pth`、索引文件，
   再建一个 `manifest.json`（清单/菜单），内容如下（把尖括号替换成你自己的值）：

   ```json
   {
     "schema": 2,
     "packs": [ {
       "id": "my-voice",
       "name": "我的音色",
       "description": "一句话介绍这个音色",
       "version": "1.0.0",
       "author": "你的名字",
       "license": "MIT",
       "baseVoice": "zh-CN-YunyangNeural",
       "f0Method": "rmvpe",
       "indexRate": 0.75,
       "model": { "url": "my-voice/model.pth", "size": 55270272, "sha256": "..." },
       "indexes": [ { "id": "c10k", "name": "紧凑 10k（推荐）",
                      "url": "my-voice/index.index", "size": 6144045, "sha256": "..." } ]
     } ]
   }
   ```

   - `url` 用**相对路径**（相对 manifest.json 所在目录）即可，放哪都通用；
   - `indexes` 是索引变体数组（可以放多个，用户在界面里选）；只想要一个也可以；
   - `size`：文件字节数（右键文件属性可见）；
   - `sha256`：在 PowerShell 里执行 `Get-FileHash 文件路径 -Algorithm SHA256` 得到；
   - 免索引的音色包：不写 `indexes` 即可。
3. 把整个目录放到**任意静态托管**（GitHub Pages / 对象存储 / 网盘直链等），
   保证上面 url 能直接下载。
4. 把仓库地址（manifest.json 所在目录的网址）发给用户，他们按第 5 节操作。
5. ⚠️ 版权：只发布你有权分发的音色（自己训练的、或已获授权的）。

---

## 10. 便携运行时（免装 RVC WebUI 也能用）

**给谁用**：只有音色模型、但不想装整套 RVC WebUI 的人（比如收到别人分享的音色包）。

**是什么**：一个免安装的文件夹，里面装好了转换服务需要的一切
（Python + torch + 推理核心 + hubert/rmvpe 模型 + ffmpeg + `rvc-server.py`）。

**下载**：点作者 B站介绍视频，**简介里含便携运行时网盘链接**：

- **B站视频**：https://www.bilibili.com/video/BV1ukbQ6qECo/

便携运行时约 **4.35GB**（torch 2.7.0+cu128，支持 RTX 50 系）；网盘链接如果失效，
可在视频评论区/私信联系作者，或按下方「怎么制作」用自己机器现打一个。

**怎么用**：
1. 解压到任意位置（Windows 例如 `D:\rvc-portable`；macOS/Linux 例如 `~/rvc-portable`）；
2. 启动服务：
   - Windows：双击里面的 **`启动服务.bat`**（会弹出一个小窗口）；
   - macOS/Linux：在终端运行 **`<你的便携包目录>/start-rvc-server.sh`**；
   - 都会显示 `dsh-plugin-tts RVC server: http://127.0.0.1:4892`；
3. 这个窗口/终端**别关**，回到插件设置按第 4.3 节填模型/索引即可。
4. 想停止：关掉那个窗口/按 `Ctrl+C`。

**怎么制作（给打包者）**：在已装 RVC WebUI 的机器上执行：

```powershell
E:\...\RVC20240604Nvidia\runtime\python.exe `
  tools\package-runtime.py `
  --rvc-dir "E:\...\RVC20240604Nvidia" `
  --out "D:\rvc-portable" --skip-torch
```

- 脚本复制已验证的 Python 环境 + 推理核心 + hubert/rmvpe + ffmpeg + rvc-server.py，
  **不下载任何东西**，成品立即可用（已在本机实测：RTX 5070 上模型加载与转换正常）；
- **RTX 50 系列（Blackwell）可选的提速升级**：官方 pytorch CDN 对部分网络很慢
  （实测 31KB/s，3.3GB 要 29 小时），用国内镜像在**可见的终端窗口**里跑（能看到进度条）：

  ```powershell
  D:\rvc-portable\runtime\python.exe -m pip install --upgrade `
    --extra-index-url https://mirrors.aliyun.com/pytorch-wheels/cu128 `
    torch==2.7.0+cu128 torchaudio==2.7.0+cu128
  ```

  （或给打包脚本加 `--index-url https://mirrors.aliyun.com/pytorch-wheels`；
  不升级也能用，只是老 torch 在 50 系显卡上有 sm_120 兼容警告、性能略降）
- 成品文件夹约 7-9GB，压缩后 3-4GB（超出 GitHub 附件 2GB 上限，
  用网盘/对象存储分发，或只把脚本分享出去让各自本机生成）；
- 便携目录内用 `runtime\python.exe rvc-server.py --port 4892` 启动同样可行；
- **跨平台**：脚本支持 `--platform auto|windows|linux|darwin`——Windows 生成
  `启动服务.bat`，Linux/macOS 生成 `start-rvc-server.sh`（macOS 无 CUDA，自动跳过
  torch 升级）。**macOS（Apple Silicon）已实测通过**，详见《RVC 指南》的 macOS 注意事项；
  Linux 仍建议先在目标平台验证。

---

## 附：开发/测试命令

```sh
node tests/smoke.mjs              # 冒烟测试（27 项）
node tests/mock-registry.mjs <目录> [端口]   # 本地音色包仓库
node tests/e2e-real-rvc.mjs       # 真实 RVC 端到端（需 4892 服务）
node tests/e2e-compact-index.mjs  # 紧凑索引端到端（需 4892 服务）
```

详细架构与设计见 [`README.md`](../README.md)（或[中文版](../README.zh.md)）、
[`RVC 指南`](RVC-GUIDE.md) 与 [`adaptive-chunked-playback.md`](adaptive-chunked-playback.md)。