@memef1f1y/dsh-plugin-tts 0.6.5 → 0.6.7

package/docs/USER-GUIDE.md

@@ -1,389 +1,389 @@
-# dsh-plugin-tts 使用手册（执行手册）
-
-> 这本手册写给"不想看技术文档"的人。每一步都写明：**做什么 → 为什么 → 怎么做 → 怎么知道成功了**。
-> 你可以只读自己需要的部分：
-> - **只想让 AI 回复能朗读** → 看第 3 节（约 5 分钟）
-> - **想用自己训练的音色朗读** → 看第 4 节（约 30 分钟，含 4.2 的服务启动）
-> - **想用一段录音克隆声音**（本机参考音频 / 提示音频）→ 看第 5 节（Index-TTS2）或第 6 节（CosyVoice）（约 15 分钟）
-> - **想用谷歌付费音色** → 看第 7 节（约 10 分钟，需自备 API Key）
-> - **想下载别人分享的音色** → 看第 8 节（约 10 分钟）
-> - 出问题 → 看第 10 节（按症状查）和第 11 节（术语字典）
-
----
-
-## 0. 这个插件到底做什么？
-
-一句话：**让你的 AI 回复能被读出来，而且能把朗读的声音换成你喜欢的音色。**
-
-- 每条 AI 回复下面多一个 🔈 喇叭按钮：点一下朗读，再点一下停止；
-- 输入框左边有一个喇叭开关：打开后，每条新回复**自动朗读**；
-- 朗读的声音可以是微软的免费音色（Edge TTS），也可以是**你自己训练的 RVC 音色**、
-  **一段录音还原的本地音色**（Index-TTS2 参考音频 / CosyVoice 提示音频零样本克隆），
-  **谷歌付费音色**，或**从网上下载的音色包**。
-
-全程在你自己的电脑上运行（除了微软 / 谷歌在线朗读本身），你的声音模型与参考音频不会上传到任何地方。
-
----
-
-## 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)」：**可留空**（免索引，效果略降但能用）；有就填上。
-
-### 4.4 测试
-
-1. 回到最下面「试听测试」，输入一句话，点 ▶。
-2. **成功**：几秒后（首次可能十几秒，是在加载模型+自动测速）听到**你的音色**在朗读。
-3. **失败**：出现红字提示 → 对照第 10 节的排查表。
-
-### 4.5 长文本自动分段
-
-选 RVC 后读很长的回复，插件会自动**分段边合成边播放**：先转换前几段立刻开播，
-其余段在播放的同时后台转换，段与段之间**没有停顿**（右上角按钮会显示「第 x/y 段」）。
-首次长文本会做一次约 5~7 秒的自动测速（决定分段大小），之后 7 天内不再重复。
-
----
-
-## 5. 用一段录音还原声音（Index-TTS2，本机）
-
-**给谁用**：有一段几秒~几十秒的清晰人声（wav/mp3），想让朗读直接用这个声音，
-不想训练模型的人。
-
-1. 双击本地包里的「**启动api服务.bat**」，黑窗口**别关**（默认端口 `7880`）。
-2. 设置 → 插件 → 语音 → TTS提供者切到「**本地音色（Index-TTS2）**」→
-   点「**刷新音色**」，下拉里选你的参考音频（没有就用「上传参考音频」传一段）。
-3. 回到底部「试听测试」输一句话点 ▶，听到参考音频的音色即成功。
-4. 长文本同样自动分段（一格约 15 秒音频的块），其余与 RVC 一致。
-
-> 情感、清洗文本等细项见 [《Index-TTS2 指南》](INDEX-TTS2-GUIDE.md)；连不上服务
-> 先看那份指南的疑难排查。
-
----
-
-## 6. 用提示音频零样本克隆（CosyVoice，本机）
-
-**给谁用**：有一段 5~20 秒的人声，想零样本克隆（连参考音频都不用"注册"，即选即用）的人。
-
-1. 双击本地包里的「**启动cosy服务.bat**」，黑窗口**别关**（默认端口 `7890`）。
-2. 设置 → 插件 → 语音 → TTS提供者切到「**本地克隆（CosyVoice）**」→
-   点「**刷新音色**」选提示音频（没有就上传一段）。
-3. **最关键一步**：「提示音频文字稿」必须把提示音频里说的内容**按顺序全文填写**
-   （中英日混的提示音三段都要写；缺一段，模型会把缺的那段复读一遍再读新文字）。
-4. 回到底部试听，听到克隆音色即成功；语速 0.5~2.0，种子填 0 为每次随机。
-
-> 细节见 [《CosyVoice 指南》](COSYVOICE-GUIDE.md)，尤其是「提示音频与文字稿」一节。
-
----
-
-## 7. 用谷歌付费音色（Cloud TTS）
-
-**给谁用**：想要中文标准/波形音色、愿意自备 API Key 并按量付费的人
-（中文标准音色每月前 400 万字符免费，Wavenet/Neural2 每月前 100 万字符免费）。
-
-1. 在 Google Cloud Console 建项目 → 启用 Text-to-Speech API → 创建 API Key。
-2. 设置 → 插件 → 语音 → TTS提供者切到「**Cloud TTS**」→ 粘贴 Key 点「**保存配置**」
-   （输入框会清空；Key 只存本机 Host 文件，可点「测试连接」验证）。
-3. 选音色试听即成功；用量在「本月用量（本地计数）」里按档查看，
-   每月 1 号清零（官方账单以 Google Cloud Billing 为准）。
-
-> Key 与计费细节见 [《Cloud 指南》](CLOUD-GUIDE.md)。
-
----
-
-## 8. 第三步：下载别人分享的音色（音色包）
-
-> 音色包 = 模型 + 可选的紧凑索引 + 说明，打成一个"仓库"，一个网址就能分享。
-
-1. 从音色作者那里拿到一个**仓库地址**（形如 `https://example.com/tts-packs` 的网址）。
-2. 打开 **设置 → 插件 → 语音 → 音色包**：
-   - 「仓库地址」粘贴网址 → 点「**获取列表**」；
-   - 出现一张张音色卡片（名称 / 描述 / 大小 / 许可 / 作者）。
-3. 点「**下载并启用**」：插件自动下载（并自动核对文件是否完整、有没有被改坏），
-   完成后**自动填好模型和索引路径**，直接去试听即可。
-4. 已安装的包会显示版本号；重复下载会自动跳过。
-5. ⚠️ 注意：只看「许可」允许分发的音色。演示音色 azusa-test 受版权限制，
-   不会出现在公开仓库里；你自己训练的模型也可以做成音色包分享。
-
-> 本地测试仓库：`node tests/mock-registry.mjs <目录> [端口]` 可以把一个文件夹当成仓库起起来。
-
----
-
-## 9. 日常使用小知识
-
-- **停止朗读**：再点一次喇叭按钮；关闭自动朗读开关会停止自动朗读（不影响手动）。
-- **长回复**：自动分段、边读边合成，进度显示「第 x/y 段 · 边播边合成」。
-- **换会话 / 关页面**：自动朗读会停止。
-- **设置不保存**：声音/开关等设置存在内存里，刷新页面会恢复默认（音色包安装的文件会保留）。
-
----
-
-## 10. 出问题了？按症状查
-
-| 症状 | 最常见原因 | 怎么办 |
-|---|---|---|
-| 点朗读没声音 | 浏览器自动播放限制 | 先在页面任意处点一下再试；检查系统音量 |
-| 点「浏览」提示"浏览文件需要先启动本地 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 疑难排查 |
-| 试听按钮一直转 | 网络或服务没起来 | 看红字提示；RVC 确认 4.2 窗口在运行，Index/Cosy 确认各自的启动窗口在运行 |
-| 提示"无法连接本地 Index-TTS2 / CosyVoice 服务" | 对应的 `.bat` 窗口没开 / 被关了 | 按第 5 节（Index）/ 第 6 节（Cosy）启动并保留窗口；确认「服务地址」端口（7880/7890） |
-| Cloud 提示 Key 无效 / 未启用接口 | Key 贴错，或 Text-to-Speech API 没启用 | 重贴完整 Key；去 Cloud Console 启用接口；见第 7 节 |
-
-### 10.1 反馈朗读问题时请附带这两样
-
-1. 在出问题的页面按 F12 打开控制台，把 `[tts]` 开头的行复制发过来；
-2. 在控制台运行 `copy(JSON.stringify(__dshTtsDebug.dump()))`，把剪贴板内容一并发过来。
-
-这两样只含键名和数量、不含消息正文，但能直接看出插件读到的数据形状，是定位最快的方式。顺手确认第一行是 `[tts] client build … loaded`（没有它说明页面跑的还是旧包，先硬刷新或重启 `dsh web`）。
-
----
-
-## 11. 术语小字典（看见不懂的词查这里）
-
-| 词 | 是什么意思 |
-|---|---|
-| Edge TTS | 微软的免费在线朗读服务（本插件默认的声音来源） |
-| RVC | 一个"声音转换"工具：把朗读声换成目标音色 |
-| 模型（.pth） | 你的音色本体文件 |
-| 索引（.index） | 让音色更像原声的可选文件；很大，但可以压缩 |
-| 紧凑索引 | 把几百 MB 的索引缩到几 MB（设置里「压缩索引」按钮） |
-| 免索引 | 不填索引直接用（效果略降，但省事） |
-| 音色包 | 模型+索引+说明打包，一个网址即可分享（见第 8 节） |
-| 仓库地址 | 音色包清单（manifest.json）所在的网址 |
-| sha256 | 文件的"指纹"；下载后自动核对，防止文件损坏或被改 |
-| 原声 | 转换前的朗读（Edge TTS 按消息文本自动合成） |
-| 底噪 | 上面"原声"的技术叫法；界面里已改成"原声" |
-| 参考音频（Index-TTS2） | 决定朗读是谁的声音的那段音频，存在本机包的 api/ckyp 目录，可上传新增（见第 5 节） |
-| 提示音频（CosyVoice） | 同上，但存在 prompts 目录；必须配"提示音频文字稿"且按顺序全文填写（见第 6 节） |
-| SSML 计费口径 | Cloud 按实际发送的 SSML 字符数（含标签）计费，本地按此计数（见第 7 节） |
-| 预热（prewarm） | 长文本开播前先合成好的前几段；Edge/Cloud 只等第 1 段就开播，本地链路等 2 段防卡顿 |
-
----
-
-## 12. 进阶：给音色作者 —— 怎么做一个音色包
-
-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 所在目录的网址）发给用户，他们按第 8 节操作。
-5. ⚠️ 版权：只发布你有权分发的音色（自己训练的、或已获授权的）。
-
----
-
-## 13. 便携运行时（免装 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              # 冒烟测试（126 项）
-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)。
+# dsh-plugin-tts 使用手册（执行手册）
+
+> 这本手册写给"不想看技术文档"的人。每一步都写明：**做什么 → 为什么 → 怎么做 → 怎么知道成功了**。
+> 你可以只读自己需要的部分：
+> - **只想让 AI 回复能朗读** → 看第 3 节（约 5 分钟）
+> - **想用自己训练的音色朗读** → 看第 4 节（约 30 分钟，含 4.2 的服务启动）
+> - **想用一段录音克隆声音**（本机参考音频 / 提示音频）→ 看第 5 节（Index-TTS2）或第 6 节（CosyVoice）（约 15 分钟）
+> - **想用谷歌付费音色** → 看第 7 节（约 10 分钟，需自备 API Key）
+> - **想下载别人分享的音色** → 看第 8 节（约 10 分钟）
+> - 出问题 → 看第 10 节（按症状查）和第 11 节（术语字典）
+
+---
+
+## 0. 这个插件到底做什么？
+
+一句话：**让你的 AI 回复能被读出来，而且能把朗读的声音换成你喜欢的音色。**
+
+- 每条 AI 回复下面多一个 🔈 喇叭按钮：点一下朗读，再点一下停止；
+- 输入框左边有一个喇叭开关：打开后，每条新回复**自动朗读**；
+- 朗读的声音可以是微软的免费音色（Edge TTS），也可以是**你自己训练的 RVC 音色**、
+  **一段录音还原的本地音色**（Index-TTS2 参考音频 / CosyVoice 提示音频零样本克隆），
+  **谷歌付费音色**，或**从网上下载的音色包**。
+
+全程在你自己的电脑上运行（除了微软 / 谷歌在线朗读本身），你的声音模型与参考音频不会上传到任何地方。
+
+---
+
+## 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)」：**可留空**（免索引，效果略降但能用）；有就填上。
+
+### 4.4 测试
+
+1. 回到最下面「试听测试」，输入一句话，点 ▶。
+2. **成功**：几秒后（首次可能十几秒，是在加载模型+自动测速）听到**你的音色**在朗读。
+3. **失败**：出现红字提示 → 对照第 10 节的排查表。
+
+### 4.5 长文本自动分段
+
+选 RVC 后读很长的回复，插件会自动**分段边合成边播放**：先转换前几段立刻开播，
+其余段在播放的同时后台转换，段与段之间**没有停顿**（右上角按钮会显示「第 x/y 段」）。
+首次长文本会做一次约 5~7 秒的自动测速（决定分段大小），之后 7 天内不再重复。
+
+---
+
+## 5. 用一段录音还原声音（Index-TTS2，本机）
+
+**给谁用**：有一段几秒~几十秒的清晰人声（wav/mp3），想让朗读直接用这个声音，
+不想训练模型的人。
+
+1. 双击本地包里的「**启动api服务.bat**」，黑窗口**别关**（默认端口 `7880`）。
+2. 设置 → 插件 → 语音 → TTS提供者切到「**本地音色（Index-TTS2）**」→
+   点「**刷新音色**」，下拉里选你的参考音频（没有就用「上传参考音频」传一段）。
+3. 回到底部「试听测试」输一句话点 ▶，听到参考音频的音色即成功。
+4. 长文本同样自动分段（一格约 15 秒音频的块），其余与 RVC 一致。
+
+> 情感、清洗文本等细项见 [《Index-TTS2 指南》](INDEX-TTS2-GUIDE.md)；连不上服务
+> 先看那份指南的疑难排查。
+
+---
+
+## 6. 用提示音频零样本克隆（CosyVoice，本机）
+
+**给谁用**：有一段 5~20 秒的人声，想零样本克隆（连参考音频都不用"注册"，即选即用）的人。
+
+1. 双击本地包里的「**启动cosy服务.bat**」，黑窗口**别关**（默认端口 `7890`）。
+2. 设置 → 插件 → 语音 → TTS提供者切到「**本地克隆（CosyVoice）**」→
+   点「**刷新音色**」选提示音频（没有就上传一段）。
+3. **最关键一步**：「提示音频文字稿」必须把提示音频里说的内容**按顺序全文填写**
+   （中英日混的提示音三段都要写；缺一段，模型会把缺的那段复读一遍再读新文字）。
+4. 回到底部试听，听到克隆音色即成功；语速 0.5~2.0，种子填 0 为每次随机。
+
+> 细节见 [《CosyVoice 指南》](COSYVOICE-GUIDE.md)，尤其是「提示音频与文字稿」一节。
+
+---
+
+## 7. 用谷歌付费音色（Cloud TTS）
+
+**给谁用**：想要中文标准/波形音色、愿意自备 API Key 并按量付费的人
+（中文标准音色每月前 400 万字符免费，Wavenet/Neural2 每月前 100 万字符免费）。
+
+1. 在 Google Cloud Console 建项目 → 启用 Text-to-Speech API → 创建 API Key。
+2. 设置 → 插件 → 语音 → TTS提供者切到「**Cloud TTS**」→ 粘贴 Key 点「**保存配置**」
+   （输入框会清空；Key 只存本机 Host 文件，可点「测试连接」验证）。
+3. 选音色试听即成功；用量在「本月用量（本地计数）」里按档查看，
+   每月 1 号清零（官方账单以 Google Cloud Billing 为准）。
+
+> Key 与计费细节见 [《Cloud 指南》](CLOUD-GUIDE.md)。
+
+---
+
+## 8. 第三步：下载别人分享的音色（音色包）
+
+> 音色包 = 模型 + 可选的紧凑索引 + 说明，打成一个"仓库"，一个网址就能分享。
+
+1. 从音色作者那里拿到一个**仓库地址**（形如 `https://example.com/tts-packs` 的网址）。
+2. 打开 **设置 → 插件 → 语音 → 音色包**：
+   - 「仓库地址」粘贴网址 → 点「**获取列表**」；
+   - 出现一张张音色卡片（名称 / 描述 / 大小 / 许可 / 作者）。
+3. 点「**下载并启用**」：插件自动下载（并自动核对文件是否完整、有没有被改坏），
+   完成后**自动填好模型和索引路径**，直接去试听即可。
+4. 已安装的包会显示版本号；重复下载会自动跳过。
+5. ⚠️ 注意：只看「许可」允许分发的音色。演示音色 azusa-test 受版权限制，
+   不会出现在公开仓库里；你自己训练的模型也可以做成音色包分享。
+
+> 本地测试仓库：`node tests/mock-registry.mjs <目录> [端口]` 可以把一个文件夹当成仓库起起来。
+
+---
+
+## 9. 日常使用小知识
+
+- **停止朗读**：再点一次喇叭按钮；关闭自动朗读开关会停止自动朗读（不影响手动）。
+- **长回复**：自动分段、边读边合成，进度显示「第 x/y 段 · 边播边合成」。
+- **换会话 / 关页面**：自动朗读会停止。
+- **设置不保存**：声音/开关等设置存在内存里，刷新页面会恢复默认（音色包安装的文件会保留）。
+
+---
+
+## 10. 出问题了？按症状查
+
+| 症状 | 最常见原因 | 怎么办 |
+|---|---|---|
+| 点朗读没声音 | 浏览器自动播放限制 | 先在页面任意处点一下再试；检查系统音量 |
+| 点「浏览」提示"浏览文件需要先启动本地 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 疑难排查 |
+| 试听按钮一直转 | 网络或服务没起来 | 看红字提示；RVC 确认 4.2 窗口在运行，Index/Cosy 确认各自的启动窗口在运行 |
+| 提示"无法连接本地 Index-TTS2 / CosyVoice 服务" | 对应的 `.bat` 窗口没开 / 被关了 | 按第 5 节（Index）/ 第 6 节（Cosy）启动并保留窗口；确认「服务地址」端口（7880/7890） |
+| Cloud 提示 Key 无效 / 未启用接口 | Key 贴错，或 Text-to-Speech API 没启用 | 重贴完整 Key；去 Cloud Console 启用接口；见第 7 节 |
+
+### 10.1 反馈朗读问题时请附带这两样
+
+1. 在出问题的页面按 F12 打开控制台，把 `[tts]` 开头的行复制发过来；
+2. 在控制台运行 `copy(JSON.stringify(__dshTtsDebug.dump()))`，把剪贴板内容一并发过来。
+
+这两样只含键名和数量、不含消息正文，但能直接看出插件读到的数据形状，是定位最快的方式。顺手确认第一行是 `[tts] client build … loaded`（没有它说明页面跑的还是旧包，先硬刷新或重启 `dsh web`）。
+
+---
+
+## 11. 术语小字典（看见不懂的词查这里）
+
+| 词 | 是什么意思 |
+|---|---|
+| Edge TTS | 微软的免费在线朗读服务（本插件默认的声音来源） |
+| RVC | 一个"声音转换"工具：把朗读声换成目标音色 |
+| 模型（.pth） | 你的音色本体文件 |
+| 索引（.index） | 让音色更像原声的可选文件；很大，但可以压缩 |
+| 紧凑索引 | 把几百 MB 的索引缩到几 MB（设置里「压缩索引」按钮） |
+| 免索引 | 不填索引直接用（效果略降，但省事） |
+| 音色包 | 模型+索引+说明打包，一个网址即可分享（见第 8 节） |
+| 仓库地址 | 音色包清单（manifest.json）所在的网址 |
+| sha256 | 文件的"指纹"；下载后自动核对，防止文件损坏或被改 |
+| 原声 | 转换前的朗读（Edge TTS 按消息文本自动合成） |
+| 底噪 | 上面"原声"的技术叫法；界面里已改成"原声" |
+| 参考音频（Index-TTS2） | 决定朗读是谁的声音的那段音频，存在本机包的 api/ckyp 目录，可上传新增（见第 5 节） |
+| 提示音频（CosyVoice） | 同上，但存在 prompts 目录；必须配"提示音频文字稿"且按顺序全文填写（见第 6 节） |
+| SSML 计费口径 | Cloud 按实际发送的 SSML 字符数（含标签）计费，本地按此计数（见第 7 节） |
+| 预热（prewarm） | 长文本开播前先合成好的前几段；Edge/Cloud 只等第 1 段就开播，本地链路等 2 段防卡顿 |
+
+---
+
+## 12. 进阶：给音色作者 —— 怎么做一个音色包
+
+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 所在目录的网址）发给用户，他们按第 8 节操作。
+5. ⚠️ 版权：只发布你有权分发的音色（自己训练的、或已获授权的）。
+
+---
+
+## 13. 便携运行时（免装 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              # 冒烟测试（126 项）
+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)。