@memef1f1y/dsh-plugin-tts 0.6.0

package/README.zh.md

@@ -0,0 +1,263 @@
+<p align="center">
+  <img src="logo.png" alt="dsh-plugin-tts" width="140" />
+</p>
+
+<h1 align="center">dsh-plugin-tts</h1>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
+  <a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-22%2B-blue" alt="node"></a>
+  <a href="tests/smoke.mjs"><img src="https://img.shields.io/badge/tests-68%20passed-success" alt="tests"></a>
+  <a href="https://github.com/1624318455/dsh-plugin-tts"><img src="https://img.shields.io/github/stars/1624318455/dsh-plugin-tts" alt="stars"></a>
+  <a href="https://github.com/1624318455/dsh-plugin-tts/commits/main"><img src="https://img.shields.io/github/last-commit/1624318455/dsh-plugin-tts" alt="last commit"></a>
+</p>
+
+## 跳转
+
+- **[English README](README.md)**（English）
+- **[RVC 自定义音色指南](docs/RVC-GUIDE.md)**（自定义音色 · 分块渐进播放 · 紧凑索引 · 音色包 · 便携运行时）
+- **[使用手册（执行手册）](docs/USER-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 音色到音色包下载全覆盖。
+
+
+## 单条朗读和自动朗读
+![alt text](Snipaste_2026-08-16_13-29-01.png)
+![alt text](Snipaste_2026-08-16_13-29-11.png)
+
+## RVC配置
+![alt text](Snipaste_2026-08-16_13-28-10.png)
+
+## RVC高级参数
+![alt text](Snipaste_2026-08-16_13-28-23.png)
+
+## RVC音色包
+![alt text](Snipaste_2026-08-16_13-28-37.png)
+
+## 功能
+
+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 共用）
+   - **CosyVoice 配置**：服务地址（默认 7890）+ 提示音频选择/刷新/上传 + 语速（0.5–2.0）+ 随机种子（0 = 随机）
+   - **Cloud 配置**：API Key（只存本机 Host 文件，输入框写后即清）+ Project ID（可选）+
+     测试连接 + 本月分档用量（Standard 400 万 / Wavenet·Neural2·Chirp3 各 100 万）
+   - **音色包**：从音色包仓库一键下载安装音色
+   - **试听测试**：输入文本 + 播放按钮（播放中显示旋转 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 原声或 RVC 变声）保存为 MP3——
+   复用进程内缓存，刚读过的消息一点即下。
+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`）
+- 仅使用 **RVC 自定义音色** 时：还需要本机 RVC 推理环境（RVC WebUI 或便携运行时，
+  并在使用前启动 `rvc-server.py`）。macOS 用户请看 [《RVC 指南》](docs/RVC-GUIDE.md)
+  的「启动本地 RVC 服务」和 [《使用手册》](docs/USER-GUIDE.md) §4.2。
+
+## 安装
+
+```sh
+# 已发布到 GitHub 后：
+dsh plugin --profile web add "github:1624318455/dsh-plugin-tts#main"
+# 或本地开发：
+dsh plugin --profile web add "file:/path/to/dsh-plugin-tts"
+```
+
+重启 `dsh web` 后作为 profile bundle 自动加载，无需手动启用。
+
+## 可用音色（经实测，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` | 注册 `/dsh-tts-api/speak`（合成/分块队列）、`/dsh-tts-audio/<id>`（音频）、`/dsh-tts-api/rvc-*`（RVC 推理/文件/紧凑索引/音色包）等 webServer 路由；用 `node -e` 运行零依赖 worker |
+| Client | `lib/client.js` | `shell.overlay` 隐藏 `<audio>` 宿主 + UI（朗读按钮 / 自动朗读开关 / 语音设置面板），通过 `fetch` 调 Host 路由                                                                     |
+
+TTS 引擎：worker 协议镜像 [node-edge-tts@1.2.10](https://github.com/SchneeHertz/node-edge-tts)：
+`Sec-MS-GEC` 查询参数（ticks 向下取整到 5 分钟边界）、
+`Sec-MS-GEC-Version=1-143.0.3650.75`、二进制帧 `Path:audio` 前缀、
+`xml:lang` 由音色 locale 推导、1006 异常关闭自动重试一次。音频输出
+`audio-24khz-48kbitrate-mono-mp3`。
+
+## 边界行为
+
+- 自动朗读中点击同一消息朗读按钮 → 停止；点击另一消息 → 打断自动、改手动朗读。
+- 手动朗读中关闭自动开关 → **不打断**手动；自动朗读中关闭 → 停止自动朗读。
+- 新消息完成（自动开启）→ 打断当前、朗读最新；无文本消息跳过；切换会话只停自动来源。
+- 停止 / 换消息时**立即取消**当前 RVC 分块 job，本地转换服务停止调度后续块、及时释放 GPU/内存
+  （不必等惰性回收）。
+- 同一段文本+音色重复朗读 → **复用进程内音频缓存**（不重复合成）；若缓存底层文件已被系统清理，
+  会自动重新合成而非返回失效的 404 URL。
+- Edge 音色被端点移除（`1007 Unsupported voice`）→ 从选择列表剔除并**自动回退默认音色**。
+- **首次用户手势即解锁自动播放**（resume Web Audio 上下文 + 播放静音片段），朗读不会因浏览器自动
+  播放策略被静默拦截。
+- `Esc` / `S`（非输入框内）停止当前朗读。
+- 合成/播放失败（消息朗读与自动朗读路径）→ **弹出主题化 toast 提示**（不再静默失败；
+  试听面板仍保留内联红字）。RVC 模式下错误 toast 带**一键「改用 Edge TTS 朗读」**动作；
+  若在 RVC 设置里开启**「RVC 失败时自动改用 Edge TTS」**（默认关闭——RVC 为纯本地处理，
+  自动降级会把文本发送给微软在线端点），RVC 朗读失败会自动改用 RVC 底噪音色经 Edge 重读，
+  并弹 warn toast 提示。
+- **智能分句**：分块切分绝不切断 URL / 邮箱 / 小数 / 版本号（如"3.14"）；硬切会滑到
+  词/标点边界；末尾的极短句会并入前一块，避免听感像结巴。
+- **审批语音提醒（opt-in）**：Host 订阅 `session/event` 火线（`approval/asked` /
+  `approval/decided`）并按审批 id 去重；客户端轮询 `/dsh-tts-api/notify?s=N`——
+  首次轮询只做基线同步（刷新不重播旧提醒）；播报失败静默（不弹错误 toast，避免 Agent
+  循环期间刷屏）。
+
+## 设置持久化
+
+分层存储：
+
+- **Host 文件**（`~/.dsh/tts-rvc/settings.json`，`{ version: 1, rvc: … }`）：
+  服务类 RVC 配置——服务地址、模型与索引路径。多浏览器共享，清浏览器数据、
+  无痕模式、换浏览器都不丢；经 `GET /dsh-tts-api/rvc-config` +
+  `POST /dsh-tts-api/rvc-config-save` 读写（老 `localStorage` 值一次性上迁，
+  之后以文件为准）。
+- **localStorage**（`dsh-tts-settings`）：只存 UI 偏好——音色、自动朗读开关、
+  提供者、声音调节、原始 Markdown 开关、审批提醒与其余 RVC 偏好。不再存
+  服务地址 / 模型 / 索引。
+
+设置面板「恢复默认设置」一键复位并清除两层（Host 文件为 best-effort）。
+
+## RVC 自定义音色
+
+用你本地训练的 **RVC 模型**做音色转换：设置面板把 TTS提供者切到「自定义音色（RVC）」
+即可。**第一次用 RVC 先做两件事**：①准备模型文件（.pth）；②启动本地 RVC 服务——
+macOS/Windows/Linux 的启动命令见 [《RVC 指南》](docs/RVC-GUIDE.md) 或
+[《使用手册》](docs/USER-GUIDE.md) §4.2。涵盖**服务启动、面板配置、长文无缝播放、紧凑索引、
+音色包一键安装、便携运行时、设置项详解与排查**——完整内容见 **[《RVC 自定义音色指南》](docs/RVC-GUIDE.md)**。
+
+> 公开音色仓库示例：[rvc-for-tts](https://github.com/1624318455/rvc-for-tts)
+> （设置 → 语音 → 音色包 → 仓库地址填 `https://raw.githubusercontent.com/1624318455/rvc-for-tts/main`）。
+
+## 疑难排查（Edge TTS）
+
+- **403 / `Sec-MS-GEC` 被拒**：Edge 端点协议或版本校验变更，更新
+  `lib/index.mjs` 内 worker 的 `CHROMIUM_FULL_VERSION` / `TRUSTED_CLIENT_TOKEN`。
+- **`1007 Unsupported voice`**：所选音色已被端点移除，换用上表列出的音色。
+- **无声音**：确认系统音量、浏览器自动播放策略（先与页面交互一次）或合成日志
+  （`dsh web` 控制台 `[tts]` 前缀错误）。
+
+> RVC 相关排查见 [《RVC 指南》疑难排查](docs/RVC-GUIDE.md#rvc-疑难排查)。
+
+## 常见问题（FAQ）
+
+**Q：体积大吗？**
+- 默认体验（Edge TTS）：插件本体很小（MB 级），**不需要下载任何服务或模型**。
+- 想用自定义音色（RVC）才需要本地 RVC 便携包，体积主要来自**自带的离线 Python 运行时 + 推理依赖 + 预训练模型**：
+  | 平台 | 压缩包 | 解压后 |
+  |---|---:|---:|
+  | macOS（Apple Silicon） | ~660 MB | ~1.3 GB |
+  | Windows（纯 CPU 精简版） | ~1–2 GB | ~2–3 GB |
+  | Windows（保留 NVIDIA GPU 加速） | ~6 GB | ~7 GB |
+- 上面这些是自包含运行包的体积；**完整版 RVC WebUI 有 7.8GB**，本插件用不到的 WebUI/训练/实时变声都不会带。
+
+**Q：依赖大吗？**
+- 不小，但**完全不需要你安装**：RVC 便携包自包含 Python、ffmpeg（Windows）/PyAV（macOS）以及全部推理依赖，解压即用，无编译、无环境配置。
+- 插件本体依赖极简，只在确实用到时才加载。
+
+**Q：需要本地 TTS 模型吗？**
+- 用默认 Edge TTS：**不需要本地模型**（在线合成，免费）。
+- 用自定义音色（RVC）：需要**你自己的** RVC 音色模型（`.pth`），可选加一个 `.index` 索引；预训练的 hubert / rmvpe 已随便携包带好，你只需提供自己训练的模型。
+
+**Q：好装吗？**
+- 插件按常规方式安装即可。
+- 用 RVC 时：下载对应平台的便携包 → 解压 → 运行启动脚本（mac 双击 `.command`，Windows 双击 `.bat`）→ 把 `.pth` 放进 `assets/weights` → 在插件面板里点「浏览」选模型即可。
+- 无需编译、无需手动装 Python/ffmpeg。注意 **mac 首次启动会慢几十秒**（macOS 首次扫描解压出的运行库，一次性行为），之后启动只要几秒。
+
+**Q：需要付费 API 吗？**
+- 不需要。默认 Edge TTS 免费（无 API key）；RVC 完全本地推理，免费。
+- 提示：Edge TTS 是微软公开的端侧免费能力，个人使用没问题；商用 / 高并发请留意微软服务条款。
+
+**Q：改动 DSH 本体了吗？**
+- 没改。这是一个**独立插件**，通过 dsh 的插件机制加载，不修改 DSH 主程序本体，可随时安装 / 停用 / 卸载，不影响 DSH 与其它插件。
+
+**其他常见疑问**
+- **需要显卡吗？** 不需要，CPU 就能跑。要更快可用 Apple Silicon 的 MPS（macOS）或 NVIDIA GPU（Windows，需用 CUDA 版 torch，体积随之增大）。
+- **隐私如何？** RVC 转换完全在本地进行，音频不上传；Edge TTS 会把要朗读的文本发送到微软端点作在线合成（选择合适的音色前请注意）。
+- **只支持 Apple Silicon 吗？** macOS 版目前是 arm64，支持 M1–M5；Intel Mac 需另行提供 x86_64 版。
+
+## 界面语言（i18n）
+
+插件设置面板顶部有「界面语言」选择：**自动（跟随浏览器）/ 中文 / English**。
+- 默认「自动」：按浏览器/系统语言显示（简体中文及其他 → 中文，其余 → English）。
+- 切换后**立即生效**，并持久化到 localStorage（`dsh-tts-lang`），刷新/重开面板不丢。
+- 覆盖范围：整个设置面板 + 气泡/朗读按钮 + 诊断 + 音色包面板，以及 RVC 服务的报错/进度提示。
+
+## 开发
+
+```sh
+node tests/smoke.mjs   # 冒烟测试：fake ctx 注册路由 + 真实 Edge TTS 合成 + 音频回放断言
+npm run test:all       # 全量：smoke + live + patch + i18n + client-load
+```
+
+改 `lib/` 后的热更新（Windows 下 `file:` 安装是**复制**而非符号链接，
+运行中的 dsh 读的是 profile 副本）：
+
+```powershell
+Copy-Item lib/* $env:USERPROFILE\.dsh\profiles\web\node_modules\@dsh-external\dsh-plugin-tts\lib\ -Recurse -Force
+# 然后刷新浏览器即可（bundle 每次请求重新读盘；勿用 pnpm install --force 覆盖）
+```
+
+## 已知限制
+
+- 音色 / 自动朗读开关 / TTS 提供者 / RVC 配置已分层持久化（服务类走 Host 文件，
+  UI 偏好走 localStorage，见上文「设置持久化」）并跨刷新保留
+  （见上文「设置持久化」）；但**音频缓存本身仅进程内**（音频写在 OS 临时目录，由系统清理），
+  完全重启后每段文本第一次朗读会重新合成。
+- 合成音频写入 OS 临时目录，由系统清理。
+- 中英文**布局/视觉**（英文文本较长可能换行/溢出，主题变量 `--dsw-*` 适配）需在**装有所插件的真实 dsh 界面**里人工确认——
+  本插件无独立 HTML，UI 由 dsh web 宿主注入 slots 渲染，无法脱离宿主做 headless 截图对比（`tests/client-load.mjs` 只做内存渲染断言，不生成真实 DOM/CSS）。
+
+## License
+
+MIT

package/TODO.md

@@ -0,0 +1,23 @@
+# TODO（待办）
+
+## 发布与引流
+
+- [x] **B站介绍视频已发布**，简介已放便携运行时网盘链接（`E:\rvc-portable-torch2.7-cu128.zip`，4.35GB）。
+- [x] 便携运行时 zip 已上传个人网盘。
+- [x] B站视频链接已填入 `docs/USER-GUIDE.md` §10（https://www.bilibili.com/video/BV1ukbQ6qECo/）。
+- [x] macOS 实测：已在 Apple Silicon macOS 26 上完整跑通（`npm run test:all` 全绿），
+      修复了 mac-verify.sh 的 od 空格 bug、darwin PyAV 补丁、rvc-server 边界 500→400，
+      并新增 live/边界 标准测试（见 `tests/` 与 `tests/README.md`）。
+- [x] 中英文国际化：设置面板/气泡/诊断/音色包/RVC 报错全部 zh/en，含语言切换与持久化
+      （见 `lib/client.js` 的 i18n 层 + `tests/i18n-keys.mjs`、`tests/client-load.mjs`）。
+- [x] CI：`.github/workflows/test.yml` 已加（Node 22/24，跑 smoke/i18n/client-load/patch；
+      注：Edge TTS worker 依赖原生 `WebSocket`，需 Node ≥ 22，故矩阵不含 20）。
+
+## 后续功能（按需启动）
+
+- [ ] 校准文件（calibration.json）多机同步/备份。
+- [ ] 多个音色包仓库并存（设置里保存多个仓库地址）。
+- [ ] 试听 A/B（UI 内对比两个音色包输出）。
+- [ ] 便携运行时 Linux 实测（macOS 用 `docs/macos-test-prompt.md` 同款流程）。
+- [x] ~~Edge TTS 一键诊断~~（设置面板「诊断」，已上线）。
+- [x] ~~便携运行时跨平台脚本泛化~~（`tools/package-runtime.py --platform`，代码已交付，待实测）。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-plugin-tts bundle: register the Edge TTS voice plugin (host routes + client UI).
+- insert:
+    - id: tts
+      name: '@dsh-external/dsh-plugin-tts'

package/docs/CLOUD-GUIDE.md

@@ -0,0 +1,216 @@
+# Cloud TTS 指南（谷歌付费在线音色 / Cloud TTS Guide）
+
+> dsh-plugin-tts 的 Cloud TTS 能力专册。Cloud TTS 是谷歌付费在线合成：音质与语种覆盖最好，但需要自备 API Key 并按量计费。
+> 主 README：[中文](../README.zh.md) / [English](../README.md) · 使用手册：[《执行手册》](USER-GUIDE.md)
+>
+> 🤖 **给 AI Agent 的说明**：本文档可直接喂给 AI Agent 照着落地。如果觉得晦涩难懂，或想直接脱手实现，
+> 把本文档全文粘贴给你的 AI Agent，让它按文末「给 AI Agent 的落地附录」一步步执行验证即可。
+
+**目录**
+- [Cloud TTS 是什么](#cloud-tts-是什么)
+- [开始前准备](#开始前准备)
+- [获取 API Key 并启用接口](#获取-api-key-并启用接口)
+- [设置面板配置](#设置面板配置)
+- [用量与计费口径](#用量与计费口径)
+- [长文本分块播放](#长文本分块播放)
+- [设置项详解](#设置项详解)
+- [Cloud TTS 疑难排查](#cloud-tts-疑难排查)
+- [安全与隐私提示](#安全与隐私提示)
+- [给 AI Agent 的落地附录](#给-ai-agent-的落地附录)
+- [English](#english)
+
+---
+
+<a name="cloud-tts-是什么"></a>
+## Cloud TTS 是什么
+
+Cloud TTS（Google Cloud Text-to-Speech）是谷歌的在线合成服务：把文本发送到谷歌端点，
+按所选 voice 合成后返回音频播放。
+
+```
+消息文本 → Google Cloud TTS 端点 → mp3 → 播放
+```
+
+与 Edge TTS 的区别：Edge 免费、无 Key；Cloud 需要自备 API Key，且超出免费额度后按量计费，
+但中文标准 / 波形 / 神经网络等档位的音质与稳定性通常更好。
+不需要本地服务与模型，只要本机能访问谷歌端点即可用。
+
+---
+
+<a name="开始前准备"></a>
+## 开始前准备
+
+| 需要 | 是什么 | 必须吗 |
+|---|---|---|
+| 可访问谷歌端点的网络 | 合成请求需要到达 Cloud TTS 端点 | ✅ 必须 |
+| Google Cloud 项目 | 用于启用 Text-to-Speech API 并创建凭据的容器 | ✅ 必须 |
+| API Key | 插件调用端点时的身份凭据 | ✅ 必须 |
+| 本地服务 / 模型文件 | 不需要 | ❌ 不需要 |
+
+> 免费额度按自然月重置（见下文）；超出后按谷歌账单计费，用量以谷歌控制台为准。
+
+---
+
+<a name="获取-api-key-并启用接口"></a>
+## 获取 API Key 并启用接口
+
+通行步骤（界面文案可能随控制台改版变化，认准同名入口即可）：
+
+1. 登录 Google Cloud Console，创建或选择一个项目；
+2. 在「API 和服务」中找到 Text-to-Speech API 并**启用**它（未启用会报无权限）；
+3. 在「API 和服务 → 凭据」中**创建 API Key**（类型选 API Key 即可）；
+4. （可选）给 Key 设置应用限制 / API 限制，并记下项目 ID 备用；
+5. 回到插件面板粘贴保存（见下一节），然后用「测试连接」验证。
+
+通用说明：
+
+- Key 与具体机器、目录、环境变量无关，任何一台能联网的机器粘贴同一个 Key 都能用；
+- 如长期在服务端 / 共享机器使用，建议给 Key 加上调用方限制并定期轮换；
+- 当前版本只用 API Key 调用，不需要服务账号 JSON。
+
+---
+
+<a name="设置面板配置"></a>
+## 设置面板配置
+
+打开 **设置 → 插件 → 语音**：
+
+- **TTS提供者** 选「**Cloud TTS（谷歌付费）**」；
+- **Cloud 音色**：从中文组下拉选择（默认推荐波形档），或直接输入完整的 voice id
+  （如其他语种 / Neural2 / Chirp 系）；
+- **API Key**：粘贴后点「**保存配置**」；输入框会清空，这是正常的——Key 只存本机 Host 文件，
+  不回显、不进浏览器存储；
+- **Project ID（可选）**：当前版本仅做记录，不填也能用；
+- 点「**测试连接**」：成功会合成一句测试语音（其字符会计入本月用量）；
+- 点面板底部「试听测试」输入一句话试听，确认音色与语速。
+
+---
+
+<a name="用量与计费口径"></a>
+## 用量与计费口径
+
+插件面板自带「本月用量（本地计数）」，按档位分别统计：
+
+| 档位 | 本地计数口径 | 免费额度（每月） |
+|---|---|---|
+| Standard | 发送字符数（含 SSML 标签） | 前 400 万字符 |
+| Wavenet / Neural2 / Chirp 3 | 发送字符数（含 SSML 标签） | 各前 100 万字符 |
+
+通用说明：
+
+- 档位按 voice 名称自动归档（名称含 `wavenet` / `neural2` / `chirp` 即归入对应档，否则按 Standard 计）；
+- 本地计数每月 1 号自动清零，仅供参考；**实际账单以谷歌控制台为准**；
+- 测试连接与试听同样会消耗字符，频繁试听大段文本会显著增加用量；
+- 长文本会被切成多个小包逐包合成，每包独立计费，总和即本次朗读的消耗。
+
+---
+
+<a name="长文本分块播放"></a>
+## 长文本分块播放
+
+Cloud TTS 的同步接口对单包大小有硬上限，长回复会被自动切包：
+
+1. 文本先按句切分并避开 URL / 邮箱 / 小数 / 版本号等原子 token，再按字节与字符双上限
+   打包，保证每包都不超限；
+2. 第一包合成完成后立即开播，其余包在播放的同时后台合成——**边播边合成**；
+3. 单包失败只重试该包，不会整段重来；极少数坏包会被跳过并提示，不中断整段播放；
+4. 短文本只发一包，走单文件链路，零额外开销。
+
+---
+
+<a name="设置项详解"></a>
+## 设置项详解
+
+| 设置项 | 作用 | 建议 |
+|---|---|---|
+| Cloud 音色 | 决定朗读是谁的声音 | 中文优先用中文组波形档；跨语种直接输入完整 voice id |
+| 语速 / 音调 / 音量 | 与 Edge 共用的声音调节，映射为 Cloud 音频参数 | `0` = 默认；小幅调整即可 |
+| API Key | 调用谷歌端点的凭据 | 粘贴后保存；输入框清空 = 已存入本机文件 |
+| Project ID | 项目标识，仅记录 | 可留空；不影响合成 |
+| 测试连接 | 用最小成本验证 Key 与网络 | 换 Key / 换网络后必点一次 |
+| 本月用量 | 本地按档位计数的字符消耗 | 每月 1 号清零；对账以谷歌控制台为准 |
+| 清除 Key | 删除本机保存的 Key | 换 Key / 停用 Cloud 前使用；清除后 Cloud 不可用 |
+
+---
+
+<a name="cloud-tts-疑难排查"></a>
+## Cloud TTS 疑难排查
+
+> 💡 设置面板有「**诊断**」按钮与「**测试连接**」按钮：先点测试连接，再看红字分类提示。
+
+| 症状 | 最常见原因 | 怎么办 |
+|---|---|---|
+| 提示未配置 API Key | 还没保存 Key，或 Key 被清除 | 粘贴 Key 后点「保存配置」，再点「测试连接」 |
+| 提示 Key 无效 / 未启用 API（401 / 403） | Key 粘贴不完整 / Text-to-Speech API 未启用 / Key 有调用限制 | 检查粘贴是否完整；去控制台确认 API 已启用；确认 Key 的限制允许该 API |
+| 提示请求被拒绝（400） | voice id 无效或单包超限 | 换用列表内音色或检查手输的 voice id；长文本由插件自动切包，一般无需处理 |
+| 合成失败 / 网络错误 | 到谷歌端点的网络不通、代理拦截 | 检查网络 / 代理后重试；瞬时抖动会自动重试 |
+| 返回音频异常 / 过小 | 服务端异常或文本为空 | 换短文本重试；仍失败看红字详情并反馈 |
+| 用量涨得比预期快 | 本地口径含 SSML 标签；试听与测试连接同样计费 | 减少大段试听；以谷歌控制台账单为准对账 |
+| 反馈问题时请附带 | 定位需要的信息 | F12 控制台 `[tts]` 开头的行；`copy(JSON.stringify(__dshTtsDebug.dump()))` 的输出；**不要**粘贴你的 API Key |
+
+---
+
+<a name="安全与隐私提示"></a>
+## 安全与隐私提示
+
+- API Key 只保存在本机 Host 文件，不进浏览器存储、不回显；任何「导出诊断日志」都不会包含 Key，
+  反馈问题时也**不要**把 Key 发给任何人；
+- Cloud TTS 会把要朗读的文本发送到谷歌端点合成，涉密文本请评估后再用；
+- 合成音频写入系统临时目录，由系统自动清理；同文本 + 同音色在同一会话内会复用缓存。
+
+---
+
+<a name="给-ai-agent-的落地附录"></a>
+## 给 AI Agent 的落地附录
+
+> 以下契约对所有机器通用，不含任何个人路径与 Key 明文。按顺序执行即可打通。
+
+- **provider id**：`google-cloud-tts`（`/speak` 的 `provider` 字段就填这个）。
+- **无需本地服务**：没有 `baseUrl`， disparity 只在云端；网络需能到达谷歌端点。
+- **Key 存放**：当前用户主目录下的 Host 配置文件（`tts-rvc` 目录下的 `settings.json`，`cloud.apiKey` 字段），
+  只写不回显；面板经 `GET /dsh-tts-api/cloud-config` 只返回“是否已存 + 尾部提示”，
+  经 `POST /dsh-tts-api/cloud-config-save` 写入，`POST /dsh-tts-api/cloud-test` 实测合成一句。
+- **合成调用**（经插件 Host 中转，前端不直连谷歌端点）：
+  `POST /dsh-tts-api/speak` body `{ text, provider: "google-cloud-tts", custom: { voice }, prosody }`
+  → 短文本 `{ url }`，长文本 `{ jobId, chunks, total }`（后续包 `GET /dsh-tts-api/rvc-next?job=<jobId>`）。
+- **档位归档**（与用量口径一致）：voice 名含 `chirp` → chirp3，`neural2` → neural2，
+  `wavenet` → wavenet，其余 → standard；用量经 `GET /dsh-tts-api/cloud-usage` 查询（本地计数，每月 1 号清零）。
+- **诊断验证**：`POST /dsh-tts-api/diagnose` body `{ cloudProbe: "1", cloudVoice }` → 看 `checks` 里
+  `id === "cloud"` 一项；`skip = 未配 Key`，`ok = 联通`，`401/403 = Key 或 API 未启用`。
+- **验收标准**：保存 Key → 测试连接通过 → 任选云音色合成一句短文本能播 → 用量接口对应档位 +1。
+- **红线**：任何日志、截图、粘贴都要脱敏 Key；不要把 Key 写进文档、环境变量示例或聊天记录。
+
+---
+
+<a name="english"></a>
+## English
+
+Cloud TTS (Google Cloud Text-to-Speech) is the paid online provider: best coverage and quality,
+but it needs your own API key and bills past the free tier. No local service or model needed —
+just network access to Google's endpoint.
+
+### Quick start
+1. **Prepare**: a Google Cloud project with the Text-to-Speech API enabled, plus an API key.
+   (Console → APIs & Services → enable the API → Credentials → Create API key.)
+2. **Configure**: 设置 → 插件 → 语音 → provider = Cloud TTS; pick a voice (or type a full voice id);
+   paste the key → Save (the input clears — the key lives in the local Host file only);
+   click Test connection, then preview one sentence.
+3. **Read**: same entries as every provider (message button / auto-read toggle / selection chip).
+
+### Usage & billing caliber
+- Local monthly counters per tier (SSML-inclusive chars): Standard free 4M/month;
+  Wavenet / Neural2 / Chirp 3 free 1M/month each; resets on the 1st.
+- Tier is auto-detected from the voice name; the local count is indicative only —
+  **Google Cloud Billing is authoritative**.
+- Test clips and previews also consume characters.
+
+### Key capabilities
+- **Packetized long reads**: long replies are sentence-split and packed under the sync byte limit;
+  the first packet plays while the rest synthesize; per-packet retry only.
+- **Key hygiene**: write-only input, Host-file-only storage, never echoed, never exported in logs.
+
+### Troubleshooting
+- No key configured → paste and save the key, then test the connection.
+- 401/403 → key truncated, API not enabled, or key restrictions block the API.
+- 400 → invalid voice id or over-limit packet; use a listed voice.
+- Never paste your API key when reporting issues.