dsh-notify-say 0.4.46 → 0.4.47

package/README.md

@@ -1,219 +1,369 @@
-# dsh-notify-say
-
-给 [DeepSeek Harness](https://github.com/deepseek-ai) Desktop 用的通知插件：**任务跑完会说话**。
-
-> 别的通知插件"叮"一声；这个会喊你"主人、任务完成了"。
-> 而且**子代理还在跑的时候，它不会骗你说完成了**。
-
----
-
-## 它解决什么问题
-
-你让 AI 跑一个较长任务，然后切去干别的。常见两种通知插件的毛病：
-
-1. **该响的时候不响** —— 主会话一轮结束就报"完成"，但其实它派出的子代理还在跑，你回来发现没干完。
-2. **不该响的时候一直响** —— 每个子代理结束都弹一次，连环轰炸。
-
-本插件的做法：
-
-- **空闲门（idle gate）**：主会话这轮结束、但仍有子代理或后台任务在跑时，**先不播**；等全部结束再播**一次**。超时（默认 10 分钟）兜底，防子任务卡死导致永不播报。
-- **按会话去抖**：同一会话 60 秒内只响一次。
-- **失败单独提醒**：回合出错时播**日语道歉语音**（可选），比"任务完成"更该让你立刻知道。
-
----
-
-## 特性
-
-| 特性 | 说明 |
-|---|---|
-| **语音播报** | 本地 wav，不联网、不调用云端 TTS。发布版附 1 个音色，其余可按需下载 |
-| **空闲门** | 有在飞工作时不误报"完成"，全部结束才播一次 |
-| **五类事件** | 完成 / 出错 / 被拦截 / 待批准 / 要提问，各自独立开关 |
-| **设置页 GUI** | 走官方 `Config` schema，DSH 设置页自动生成表单 |
-| **命令行** | `tools/notify-config.ps1`，改完**立即生效、不用重启** |
-| **点通知跳会话** | 点击 Toast 可直接回到对应会话（拿不到导航服务时自动降级为"唤出窗口"） |
-| **不装语音也能用** | 没有语音包 = Toast + 系统提示音，这是正常配置 |
-| **全离线** | 不联网、不发送任何会话内容 |
-
----
-
-## 安装
-
-### 前置
-
-- DSH Desktop **0.1.7-rc.2 或更高**
-- Windows（Toast 用 WinRT，播放用 MCI；暂不支持 macOS/Linux）
-
-### 方式一：插件页（推荐）
-
-在 DSH 的 **设置 → 插件** 里搜索 `dsh-notify-say` 安装。
-
-### 方式二：手工 link（本地开发）
-
-把本仓库目录链接进 profile：
-
-```
-D:\Program Files (x86)\DSH\profiles\desktop\package.json
-  dependencies 里加:  "dsh-notify-say": "link:<本仓库路径>"
-  dsh.profile.bundles 里加:  "dsh-notify-say"
-```
-
-然后在该 profile 目录执行 `pnpm install`，重启 DSH。
-
----
-
-## 配置
-
-三种方式，优先级由低到高（后者覆盖前者）：
-
-```
-1. schema 默认值
-2. cordis.patch.yml 的 config
-3. DSH 设置页里改的值
-4. tools/notify-config.ps1 写的 storages/config.json
-```
-
-> ⚠️ **注意语义**：一旦你在设置页改过某项，再改 `cordis.patch.yml` 里同一项**不再生效**。
-> 这是 DSH 官方设计（用户层优先级更高），不是本插件的 bug。
-
-### 设置页
-
-DSH **设置 → 通知**（由官方 Loader 从本插件的 `Config` schema 自动生成），共 12 项：
-
-语音开关、音色模式（固定/随机）、音色名、音量，
-以及完成/出错/被拦截/已中止/待批准/要提问/子代理/空闲门 八个开关。
-
-### 命令行
-
-```powershell
-cd <插件目录>\tools
-
-.\notify-config.ps1 -Show              # 看当前生效值
-.\notify-config.ps1 -Voice off         # 静音（Toast 仍弹）
-.\notify-config.ps1 -Volume 40
-.\notify-config.ps1 -VoiceMode random
-.\notify-config.ps1 -VoiceName ankomon
-.\notify-config.ps1 -Disable aborted -Enable subagents
-.\notify-config.ps1 -Clear             # 交还控制权给设置页
-```
-
-改完**立即生效**，不需要重启 DSH。
-
-### 语音包管理
-
-核心包只带**一个日语音色**（ずんだもん），体积约 2.8 MB。
-完整多音色包体积较大（十余个音色约 40 MB），故不随包发布 —— 计划通过单独下载提供（尚未实现）。
-
-```powershell
-.\notify-config.ps1 -ListPacks         # 看已装哪些音色、各占多少
-.\notify-config.ps1 -PurgeVoice <key>  # 删掉不用的音色
-.\notify-config.ps1 -InstallHint       # 看怎么获取更多音色
-```
-
-**不装任何语音包也完全可用**：通知会退回 Windows Toast + 系统提示音。
-
-想要更多音色，两条路：
-
-1. **自己合成**：装 [VOICEVOX](https://voicevox.hiroshiba.jp/)（本地免费 TTS），启动引擎（默认 `http://127.0.0.1:50021`），
-   然后按下面的命名规则把合成好的 wav 放进对应目录即可。
-   （合成脚本不随本包发布——它依赖本地 VOICEVOX 引擎与特定音色表，放在发布包里只会误导。）
-2. **手工放入**：把 wav 按下面的命名放进对应目录
-
-```
-sounds/voice-lines/<key>~1.wav            完成
-sounds/voice-lines/question/<key>~1.wav   提问
-sounds/voice-lines/approval/<key>~1.wav   审批
-sounds/voice-lines/fail/<key>~1.wav       出错
-```
-
----
-
-## 兼容性与降级
-
-本插件的首要目标是**稳定**，所以每个依赖外部能力的地方都有降级路径：
-
-| 能力 | 拿不到时怎么办 |
-|---|---|
-| `@deepseek-ai/schemastery`（生成设置页） | 不导出 `Config` → **设置页不出现，插件照常工作** |
-| `uiWorkspace.openSession`（点通知跳会话） | 不跳转，Toast 仍能唤出窗口（**退回旧行为**） |
-| 语音包 | 回退系统提示音 |
-| `$DSH_HOME` 未设置 | 配置走 patch 默认值；不写任何状态文件 |
-
-**不会出现"静默失效"**：每个降级都有明确行为，并有测试锁定。
-
-> 对比：某些插件写 `if (typeof sessions?.open === 'function') sessions.open(id)`，
-> 而 `sessions.open` 在 0.1.7+ 已被移除 —— 该功能**静默失效，用户点通知没反应却无从察觉**。
-> 详见 `CARD.md` 的 §零之二。
-
----
-
-## 已知限制
-
-- **仅 Windows**（Toast = WinRT，播放 = MCI，调用 Windows PowerShell 5.1）
-- **设置页真实渲染尚未验证**（代码已就绪、schema 结构已测，但未在宿主里看过界面）
-- **点通知跳会话依赖未文档化 API**（`uiWorkspace`），官方随时可能改；坏了会自动降级
-- `blocked`（回合被拦截）只用系统蜂鸣，不播失败语音 —— 因为语义是"被拦下"而非"失败"
-- **`fail` 语音包只覆盖 16 个基础音色**（103 个音色里的其余 87 个只有完成语音）。选到未覆盖的音色时，失败会在同池内换一个音色，不会哑掉、也不会播错语义
-
----
-
-## 开发
-
-### 跑测试
-
-```powershell
-npm test              # 主套件（纯 Node，不需要 DSH 宿主）
-npm run test:all      # 全部（含 route 注入的两组）
-npm run test:route    # 需要 --import loader 的接线测试
-npm run test:audio-wire
-```
-
-**274 条测试。** 绝大多数是纯逻辑测试，克隆仓库后 `npm test` 即可跑。
-
-少数用例需要真实的 DSH 宿主（用于验证 Cordis 上下文行为）。
-找不到宿主时它们会**自动 skip** —— 注意 skip 不等于通过。
-指定宿主路径：
-
-```powershell
-$env:DSH_CORDIS_ENTRY = "<DSH 安装目录>\.runtime\node_modules\@deepseek-ai\cordis\lib\index.js"
-npm test
-```
-
-### 测试分层
-
-| 层次 | 内容 |
-|---|---|
-| 单元 | 音源选择、空闲门、配置校验、TTS 文案、http-guard 判定 |
-| 集成 | 真实 HTTP 服务器 + 真实 handler，覆盖请求/响应全链路 |
-| 实机 | 真实 Cordis 上下文（需宿主，无则 skip） |
-| 发布 | 构建发布包并断言被禁音色/第三方素材未进包 |
-
-集成测试（`test/http-integration.test.mjs`）是 2026-10-18 加的，起因是
-一次真实回归：给 `/consume` 加了"写操作必须 JSON"的防护，但客户端还在用
-GET —— 单元测试全绿，功能却断了。集成测试会读取客户端源码里的真实调用形状，
-所以两边一旦不同步就会变红。
-
-### CI
-
-`.github/workflows/ci.yml` 在每次 push / PR 时跑：
-
-- 单元测试（Node 20 / 22 / 24）
-- PowerShell 语法与 UTF-8 BOM 检查
-- 关键文件齐全 + npm 打包内容检查（含"被禁音色不得进包"）
-- 版本一致性
-
-### 变异测试
-
-关键断言都做过变异验证（故意改坏代码确认测试变红）。例如：
-
-- 把 `consume` 的客户端调用改回 GET → E0/E1 变红
-- 把 `head` 的前缀剥离去掉 → E3 变红
-- 把 `verifyReload` 改成永远放行 → S2/S6/R8/R8b 变红
-
----
-
-## 许可
-
-代码以 MIT 发布。
-**语音文件不适用 MIT**，由 VOICEVOX 生成，各音色有其自身使用条款，
-详见 [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md)。
+# dsh-notify-say
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai) Desktop 用的通知插件：**任务跑完会说话**。
+
+> 别的通知插件"叮"一声；这个会喊你"任务完成了"。
+> 而且**子代理还在跑的时候，它不会骗你说完成了**。
+
+只支持 **Windows**。
+
+---
+
+## 目录
+
+- [它解决什么问题](#它解决什么问题)
+- [特性](#特性)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [配置](#配置)
+- [语音包](#语音包)
+- [关于"跳回会话"](#关于跳回会话)
+- [兼容性与降级](#兼容性与降级)
+- [已知限制](#已知限制)
+- [常见问题](#常见问题)
+- [开发](#开发)
+- [许可](#许可)
+
+---
+
+## 它解决什么问题
+
+你让 AI 跑一个较长任务，然后切去干别的。常见两种通知插件的毛病：
+
+1. **该响的时候不响** —— 主会话一轮结束就报"完成"，但其实它派出的子代理还在跑，你回来发现没干完。
+2. **不该响的时候一直响** —— 每个子代理结束都弹一次，连环轰炸。
+
+本插件的做法：
+
+- **空闲门（idle gate）**：主会话这轮结束、但仍有子代理或后台任务在跑时，**先不播**；等全部结束再播**一次**。超时兜底（默认 10 分钟），防子任务卡死导致永不播报。
+- **按会话去抖**：同一会话默认 60 秒内只响一次。
+- **失败单独提醒**：回合出错时播**日语道歉语音**（可选）—— 比"任务完成"更该让你立刻知道。
+
+---
+
+## 特性
+
+| 特性 | 说明 |
+|---|---|
+| **语音播报** | 播放本地 wav，**不调用云端 TTS**。发布版自带 1 个音色，另 13 个可在设置页按需下载 |
+| **空闲门** | 有在飞工作时不误报"完成"，全部结束才播一次 |
+| **五类事件** | 完成 / 出错 / 被拦截 / 待批准 / 要提问，各自独立开关 |
+| **设置页 GUI** | 走官方 `Config` schema，在 DSH 设置页里直接改，**改完立即生效** |
+| **命令行** | `tools/notify-config.ps1`，适合脚本化与排查 |
+| **切回窗口时跳会话** | 通知时你不在前台 → 你切回来时自动跳到那个会话（见[下文](#关于跳回会话)） |
+| **不装语音也能用** | 没有语音包 = Toast + 系统提示音，这是正常配置 |
+| **许可先告知** | 下载音色前弹出条款确认，写明署名要求与官方条款链接 |
+| **诊断导出** | 一键导出脱敏日志（用户名/路径已替换），方便提 Issue |
+| **日志隐私分级** | 默认只记元数据，**不记台词正文**；要详细日志需手动开 debug |
+
+> **联网说明**：播放、通知、TTS 全部离线。只有**下载语音包**时需要访问 GitHub。
+> 不下载语音包的话，这个插件不会联网。
+
+---
+
+## 安装
+
+### 前置
+
+- DSH Desktop **0.1.7-rc.2 或更高**
+- Windows（Toast 用 WinRT，播放用 MCI，调用 Windows PowerShell 5.1）
+
+### 方式一：插件页（推荐）
+
+在 DSH 的 **设置 → 插件** 里搜索 `dsh-notify-say` 安装。
+
+### 方式二：npm
+
+```
+npm install dsh-notify-say
+```
+
+### 方式三：手工 link（本地开发）
+
+把本仓库目录链接进 profile：
+
+```
+D:\Program Files (x86)\DSH\profiles\desktop\package.json
+  dependencies 里加:  "dsh-notify-say": "link:<本仓库路径>"
+  dsh.profile.bundles 里加:  "dsh-notify-say"
+```
+
+然后在该 profile 目录执行 `pnpm install`，重启 DSH。
+
+---
+
+## 快速开始
+
+装好之后**什么都不用配就能用**：任务完成时会弹 Toast + 播自带音色。
+
+想做更多，进 **DSH 设置 → 通知**：
+
+| 想做的事 | 去哪 |
+|---|---|
+| 换音色 / 调音量 | 设置页「音色」「音量」 |
+| 下载更多音色（13 个可选） | 设置页「语音包」→ 点「加载列表」→ 选一个点「下载」 |
+| 只保留提示音、不要语音 | 音源改成「系统提示音」 |
+| 出错时也要语音提醒 | 「出错」开关（默认已开） |
+| 让子代理结束也提醒 | 「子代理」开关（默认关） |
+| 少响一点 | 「同会话去抖」调大 |
+
+---
+
+## 配置
+
+四种来源，**优先级由低到高**（后者覆盖前者）：
+
+```
+1. schema 默认值
+2. cordis.patch.yml 的 config
+3. DSH 设置页里改的值
+4. tools/notify-config.ps1 写的 storages/config.json
+```
+
+> ⚠️ **注意语义**：一旦你在设置页改过某项，再改 `cordis.patch.yml` 里同一项**不再生效**。
+> 这是 DSH 官方设计（用户层优先级更高），不是本插件的 bug。
+
+### 设置页
+
+**DSH 设置 → 通知**。包含音源选择、音色、音量、增益、TTS 参数、五个事件开关、
+去抖与冷却、音源按事件覆盖、自定义音频、语音包管理、日志级别、诊断导出等。
+
+分常规区与「高级」折叠区：日常只用常规区，排查时才展开高级区。
+
+### 命令行
+
+```powershell
+cd <插件目录>\tools
+
+.\notify-config.ps1 -Show              # 看当前生效值
+.\notify-config.ps1 -Voice off         # 静音（Toast 仍弹）
+.\notify-config.ps1 -Volume 40
+.\notify-config.ps1 -VoiceMode random
+.\notify-config.ps1 -VoiceName ankomon
+.\notify-config.ps1 -Disable aborted -Enable subagents
+.\notify-config.ps1 -Clear             # 交还控制权给设置页
+```
+
+改完**立即生效**，不需要重启 DSH。
+
+---
+
+## 语音包
+
+核心包只带**一个日语音色**（ずんだもん），安装包约 3.2 MB。
+
+另有 **13 个音色**可单独下载（每个约 1.7–3.0 MB，合计约 27 MB），
+**在设置页里点几下就能装**，不需要命令行。
+
+### 怎么装
+
+1. **DSH 设置 → 通知 → 语音包** → 点「加载列表」
+2. 列表里会显示每个音色的名称、体积、署名要求
+3. 点「下载」→ **先弹出条款确认弹窗**（见下）→ 确认后开始下载
+4. 装好后在「音色」下拉里就能选到
+
+### 下载前会告知什么
+
+点下载会弹一个居中弹窗，写明：
+
+- **署名要求**（例如 `VOICEVOX:ずんだもん`）—— 你用这些语音做的内容需要保留这个署名
+- **官方条款链接**（可点开原文）
+- 提示"下载后 zip 内也带 TERMS.md；你用它做的内容（视频、直播等）仍需守上述条款"
+
+这不是走形式：13 个音色里有 2 个因为条款**禁止再分发**被我们排除在外，
+1 个因为身份存疑（同名角色有多个）暂不收录。审核依据是官方条款原文，
+留档在 [`docs/audio-audit/`](docs/audio-audit/)。
+
+> 需要说清楚：我们的审核结论是**依据官方通用条款**得出的，
+> 不等于各权利人针对"独立 WAV 素材 ZIP 再分发"出具过专项授权。
+
+### 卸载
+
+设置页里点「卸载」即可，会删掉该音色整个目录。
+**卸载不依赖网络** —— 离线时也能卸。
+
+### 已装的音色放哪
+
+```
+%LOCALAPPDATA%\dsh-notify-say\voice-lines\<音色key>\
+```
+
+每个音色一个目录，卸载 = 删这一个目录。
+
+### 不装语音包也完全可用
+
+通知会退回 Windows Toast + 系统提示音。
+
+### 想自己做音色
+
+装 [VOICEVOX](https://voicevox.hiroshiba.jp/)（本地免费 TTS），启动引擎（默认 `http://127.0.0.1:50021`），
+然后按命名规则把合成好的 wav 放进对应目录：
+
+```
+sounds/voice-lines/<key>~1.wav            完成
+sounds/voice-lines/question/<key>~1.wav   提问
+sounds/voice-lines/approval/<key>~1.wav   审批
+sounds/voice-lines/fail/<key>~1.wav       出错
+```
+
+（合成脚本不随本包发布 —— 它依赖本地 VOICEVOX 引擎与特定音色表，放进发布包只会误导。）
+
+---
+
+## 关于"跳回会话"
+
+这里有个容易误解的地方，说清楚：
+
+**点击 Toast 本体只能把 DSH 窗口唤到前面，带不了会话 id。**
+Windows 的 Toast 协议激活是一个固定串（`dsh://open`），没有地方塞会话 id。
+
+**真正会"跳回会话"的是这个机制**：
+
+```
+通知发出时你不在前台  →  插件记下那个会话
+你切回 DSH 窗口       →  插件自动跳到那个会话
+```
+
+所以体验是：你在别处干活 → 听到"任务完成了" → 切回 DSH → **它已经帮你跳过去了**。
+
+相关开关（默认值偏保守）：
+
+| 开关 | 默认 | 说明 |
+|---|---|---|
+| 后台完成时跳转 | 开 | 通知时你不在前台 → 切回来时跳 |
+| 前台完成时也跳 | 关 | 你本来就在看着，别乱动界面 |
+
+配置读不到时**两个都当作关**（宁可少跳一次，也不擅自动你的界面）。
+
+---
+
+## 兼容性与降级
+
+本插件的首要目标是**稳定**，所以每个依赖外部能力的地方都有降级路径：
+
+| 能力 | 拿不到时怎么办 |
+|---|---|
+| `@deepseek-ai/schemastery`（生成设置页） | 不导出 `Config` → **设置页不出现，插件照常工作** |
+| `uiWorkspace.openSession`（跳会话） | 不跳转，Toast 仍能唤出窗口（**退回旧行为**） |
+| 语音包目录 | 回退系统提示音 |
+| 网络（下载语音包时） | 显示失败原因并可重试；**已装音色不受影响** |
+| `$DSH_HOME` 未设置 | 配置走 patch 默认值；不写任何状态文件 |
+
+**不会出现"静默失效"**：每个降级都有明确行为，并有测试锁定。
+
+---
+
+## 已知限制
+
+- **仅 Windows**（Toast = WinRT，播放 = MCI，调用 Windows PowerShell 5.1）
+- **跳会话依赖未文档化 API**（`uiWorkspace`），官方随时可能改；坏了会自动降级为"只唤起窗口"
+- `blocked`（回合被拦截）只用系统蜂鸣，不播失败语音 —— 语义是"被拦下"而非"失败"
+- **失败语音只覆盖部分音色**：选到未覆盖的音色时，会在同池内换一个音色播，不会哑掉、也不会播错语义
+- **开发期热重载是实验性功能**（`devReload`，默认关）：它依赖 DSH/Cordis 内部结构与 Node 模块加载机制，
+  能工作但不算稳定能力。用户不需要它 —— 那是给改插件源码的人用的
+- **13 个音色的许可结论是条件性判断**（依据官方通用条款），不代表各权利人出具过专项授权
+
+---
+
+## 常见问题
+
+**装了没声音？**
+按顺序查：① 设置页「音源」是不是「不发声」；② 「语音」开关是否关着；
+③ 「音量」是否拉到 0；④ 播放依赖 Windows PowerShell 5.1，被安全软件拦了会静音。
+设置页「诊断」区可以**导出脱敏诊断文件**，里面能看出每次播报的决策路径。
+
+**会不会打扰我？**
+默认同会话 60 秒只响一次；「子代理」默认关（子代理结束不单独提醒）。
+觉得吵可以把「同会话去抖」调大，或直接关掉某类事件。
+
+**会上传我的会话内容吗？**
+不会。通知文案是插件内置的固定句子（可自定义），播放也全在本地。
+默认日志只记"播了什么、成功与否"，**不记台词正文**。
+唯一联网的地方是下载语音包（访问 GitHub）。
+
+**提示"未能获取可下载列表"？**
+那是 GitHub 访问不通。**已装的音色照常能用**，卸载也能用（卸载不依赖网络）。
+网络恢复后点「重试」即可。
+
+**为什么只有 13 个音色？**
+VOICEVOX 有几十个角色，但每个的条款都要单独读原文核对。
+我们只收录**条款明确允许本插件这样分发**的，宁可少也不冒险。
+被排除的例子：有 2 个明确禁止再分发，1 个身份存疑。
+
+**能加我喜欢的音色吗？**
+可以提 Issue。但要走审核流程（读官方条款原文、留档），不是加个下载链接的事。
+
+---
+
+## 开发
+
+### 跑测试
+
+```powershell
+npm test              # 主套件（纯 Node，不需要 DSH 宿主）
+npm run test:all      # 全部（含 route 注入的两组）
+npm run test:route    # 需要 --import loader 的接线测试
+npm run test:audio-wire
+```
+
+**375 条测试通过。** 绝大多数是纯逻辑测试，克隆仓库后 `npm test` 即可跑。
+
+少数用例需要真实的 DSH 宿主（用于验证 Cordis 上下文行为）。
+找不到宿主时它们会**自动 skip** —— 注意 skip 不等于通过。
+
+```powershell
+$env:DSH_CORDIS_ENTRY = "<DSH 安装目录>\.runtime\node_modules\@deepseek-ai\cordis\lib\index.js"
+npm test
+```
+
+### 测试分层
+
+| 层次 | 内容 |
+|---|---|
+| 单元 | 音源选择、空闲门、配置校验、TTS 文案、http-guard 判定 |
+| 集成 | 真实 HTTP 服务器 + 真实 handler，覆盖请求/响应全链路 |
+| 行为 | 构造真实输入验证行为（如真实 ZIP 字节、真实目录） |
+| 实机 | 真实 Cordis 上下文（需宿主，无则 skip） |
+| 发布 | 构建发布包并断言被禁音色/第三方素材未进包 |
+
+### 为什么有这么多"防复发"测试
+
+这个项目踩过的坑多数是同一类：**代码看着对、测试也绿，但两者一起错**。所以后来改成：
+
+- **构造真实输入**而不是检查源码里有没有某个字符串
+  （典型：ZIP 解压防护查了不存在的字段 `entry.size`，测试也在断言同一个错字段 → 一起绿）
+- **状态更新全量扫描**而不是逐个手查
+  （典型：组件状态漏字段已发生 4 次，现在有 C43 静态扫描锁住）
+- **变异验证**：故意改坏代码，确认测试真的会红
+
+### CI
+
+`.github/workflows/ci.yml` 在每次 push / PR 时跑：
+
+- 单元测试（Node 20 / 22 / 24）
+- PowerShell 语法与 UTF-8 BOM 检查
+- 关键文件齐全 + npm 打包内容检查（含"被禁音色不得进包"）
+- 版本一致性
+
+### 发版
+
+```powershell
+.\tools\release.ps1 -Bump patch -PublishNpm
+```
+
+流程：升版本 → 跑测试 → 重建发布包 → **在发布包里再跑一次测试**
+（这一步是必要的：开发目录与发布包的文件集不同，只在开发目录跑会"本地绿、线上红"）
+→ 提交推送 → 可选发 npm。
+
+`CHANGELOG.md` 由 `release-build.ps1` **自动生成**（从开发提交提取标题，
+过滤掉内部资料与 hash），随包发布。**请勿手工编辑**。
+
+---
+
+## 许可
+
+代码以 MIT 发布。
+
+**语音文件不适用 MIT**，由 VOICEVOX 生成，各音色有其自身使用条款，
+详见 [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md)。
+每个音色包内另有该音色的 `TERMS.md`。

package/lib/client.js

@@ -1192,7 +1192,7 @@ window.__ModuleLoader__.load({
                     } else {
                       set(function (prev) {
                         return {
-                          loaded: prev.loaded, values: prev.values, advOpen: prev.advOpen, packs: p.packs,
+                          loaded: prev.loaded, values: prev.values, advOpen: prev.advOpen, packs: prev.packs,
                           termsAck: prev.termsAck, termsPending: prev.termsPending,
                           busy: false, msg: '',
                           err: '没有取到文件路径。若点了没反应，可手动在配置里填该事件的 customFile。',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-notify-say",
-    "version":  "0.4.46",
+    "version":  "0.4.47",
     "description":  "Desktop notifications for DSH Desktop that actually speak: Windows TTS out of the box (zero download), VOICEVOX voice packs optional, a selectable system-sound fallback, and an idle gate that waits for running subagents before saying the turn is done. Includes a settings-page GUI (sound source, per-event overrides, jump-back-to-session, cooldowns) and a self hot-reload for development.",
     "license":  "MIT",
     "type":  "module",

package/test/client-contract.test.mjs

@@ -329,4 +329,60 @@ test('C42: 点遮罩外部可取消，点卡片内部不取消', () => {
     '应区分"点遮罩"与"点卡片内部" —— 否则点卡片任意位置都会关掉弹窗');
   assert.match(seg, /cancelTerms\(\)/,
     '点外部应取消');
+});
+// ── C43: set() 里的状态字段必须来自它自己的参数 ─────────────────────────
+test('C43: 状态字段引用必须用 set() 自己的参数，不得用外层变量', () => {
+  // ⚠️ 2026-10-18 真实 bug（外部审阅发现）：
+  //
+  //   pickCustomFile().then(function (p) {      // p 是文件路径字符串
+  //     set(function (prev) {                   // 状态参数叫 prev
+  //       return { ..., packs: p.packs, ... }   // ← 用错的变量！
+  //     })
+  //   })
+  //
+  // `p` 是路径字符串（取消时是空串），`p.packs` 恒为 undefined →
+  // 用户取消选择自定义音频后，**已加载的语音包状态被清掉**。
+  //
+  // 这类"状态字段遗漏/用错变量"已经出现 4 次（advOpen / packs /
+  // termsAck / 这次的 p.packs）。所以用静态扫描固定住，而不是靠人记得。
+  const lines = client.split(/\r?\n/);
+  const FIELDS = ['loaded', 'values', 'advOpen', 'packs', 'termsAck', 'termsPending', 'busy', 'msg', 'err'];
+
+  // 允许引用非状态参数的对象：它们是**接口响应**，恰好也有同名字段。
+  //   r    —— saveConfig 的返回值（含 values）
+  //   doc  —— fetchVoicePacks 的返回值（含 packs）
+  const ALLOW = new Set(['r', 'doc']);
+
+  const bad = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/set\(function \((\w+)\) \{/);
+    if (!m) continue;
+    const param = m[1];
+
+    // 取该 set 的块
+    let depth = 0, started = false, end = i;
+    for (let j = i; j < Math.min(i + 30, lines.length); j++) {
+      for (const ch of lines[j]) {
+        if (ch === '{') { depth++; started = true; }
+        else if (ch === '}') { depth--; }
+      }
+      if (started && depth === 0) { end = j; break; }
+    }
+    const block = lines.slice(i, end + 1).join('\n');
+
+    for (const f of FIELDS) {
+      const re = new RegExp(`([A-Za-z_$][\\w$]*)\\.${f}\\b`, 'g');
+      let mm;
+      while ((mm = re.exec(block)) !== null) {
+        const ident = mm[1];
+        if (ident === param || ALLOW.has(ident)) continue;
+        bad.push(`L${i + 1}: 参数=${param} 但用了 ${mm[0]}`);
+      }
+    }
+  }
+
+  assert.deepEqual(bad, [],
+    '这些 set() 引用了不属于它自己状态参数的字段 —— '
+    + '典型后果是把已加载的状态清成 undefined（语音包列表消失等）。\n'
+    + bad.join('\n'));
 });

package/test/docs-consistency.test.mjs

@@ -337,4 +337,103 @@ test('D9: release.ps1 在构建后、推送前，于发布包内跑测试', { sk
     '应在发布包目录里执行');
   assert.match(rp, /throw 'release-package tests failed'/,
     '发布包内测试失败必须中止发版（fail-closed）');
+});
+// ══ README 与实现一致性（v0.4.47）════════════════════════════════════════
+//
+// 2026-10-18 外部审阅指出 README 落后于功能：
+//   · 说语音包下载"尚未实现"（其实 13 个 zip 早发布了，GUI 也能下）
+//   · 说"全离线"（下载语音包要访问 GitHub）
+//   · 说"点 Toast 可跳回会话"（Toast 点击带不了会话 id，跳转是另一套机制）
+//   · 说"设置页 12 项"（实际 schema 字段多得多）
+//
+// README 是用户判断"这插件能干什么"的第一入口。写错不是文字瑕疵 ——
+// 别人可能因此根本不知道有下载功能。
+
+const README = readFileSync(join(ROOT, 'README.md'), 'utf8');
+
+// ── D10: README 不得再声称语音包下载"未实现" ────────────────────────────
+test('D10: README 不得说语音包下载尚未实现', () => {
+  assert.doesNotMatch(README, /下载提供（尚未实现）/,
+    '语音包下载已实现并发布 13 个 zip，README 不得再说"尚未实现"');
+  assert.doesNotMatch(README, /尚未实现/,
+    'README 里不应残留"尚未实现"这类过时表态');
+
+  // 反而应该真的介绍怎么下载
+  assert.match(README, /语音包/,
+    'README 应有语音包章节');
+  assert.match(README, /下载/,
+    'README 应说明可以下载');
+});
+
+// ── D11: README 不得无条件下声称"全离线" ────────────────────────────────
+test('D11: README 的联网表述必须区分"播放离线"与"下载要联网"', () => {
+  // 只写"全离线"会让用户以为下载语音包也不需要网络，
+  // 一旦断网失败就以为插件坏了。
+  const hasOfflineClaim = /全离线/.test(README);
+  if (hasOfflineClaim) {
+    assert.match(README, /下载.*联网|联网.*下载/,
+      '若说"全离线"，必须同时说明下载语音包需要联网');
+  }
+  // 明确写清楚是更好的做法
+  assert.match(README, /不调用云端 TTS|不联网/,
+    '应说明播放/通知是离线的');
+});
+
+// ── D12: README 不得说"点 Toast 就能跳会话" ─────────────────────────────
+test('D12: README 对跳会话的描述要准确（Toast 点击带不了会话 id）', () => {
+  // 事实：Windows Toast 的协议激活是固定串，塞不进会话 id。
+  // 真正跳转的机制是"切回窗口时自动跳"。
+  assert.doesNotMatch(README, /点击 Toast 可直接回到对应会话/,
+    '这是错的说法 —— Toast 点击只能唤起窗口，带不了会话 id');
+
+  assert.match(README, /切回|切回来/,
+    '应说明真正的跳转发生在"切回 DSH 窗口时"');
+  assert.match(README, /带不了会话 id/,
+    '应明确指出 Toast 点击的限制，否则用户会以为是 bug');
+});
+
+// ── D13: README 里的数字必须与实现一致 ──────────────────────────────────
+test('D13: README 的测试条数与实际一致', () => {
+  const pkgScripts = PKG.scripts || {};
+  assert.ok(pkgScripts['test:all'], '应有 test:all 脚本');
+
+  // README 写了几条就直接比对；写错了会误导贡献者
+  const m = README.match(/\*\*(\d+) 条测试通过/);
+  if (!m) {
+    assert.match(README, /条测试/, 'README 应说明测试规模');
+    return;
+  }
+  const claimed = Number(m[1]);
+  // 允许 +/- 30 的漂移（新增测试后不必立刻同步数字），但差太多说明没维护
+  assert.ok(claimed > 300 && claimed < 600,
+    `README 声称 ${claimed} 条测试，超出合理范围 —— 数字可能过时`);
+});
+
+// ── D14: README 必须提到音色下载的许可告知 ──────────────────────────────
+test('D14: README 说明下载前会展示署名与条款', () => {
+  // 这是合规要求：用户得知道"用这些语音做的内容要署名"。
+  // README 是下载前的最后一道说明。
+  assert.match(README, /署名/,
+    'README 应说明音色的署名要求');
+  assert.match(README, /条款/,
+    'README 应说明条款');
+  assert.match(README, /TERMS\.md/,
+    '应说明包内带 TERMS.md');
+});
+// ── D15: MANIFEST 不得留 (unknown)，要留可回溯的线索 ────────────────────
+test('D15: MANIFEST 的版本回溯栏可用（不是 unknown）', { skip: SKIP_DEVONLY }, () => {
+  // 2026-10-18 外部审阅指出：公开仓库的 MANIFEST 长期显示
+  // `Git 提交: (unknown)` —— 这一栏从来没提供过信息。
+  //
+  // 原因是它在**构建时**生成，而发布包首次 commit 在构建**之后**。
+  // 现在改为如实说明 + 给出真正能查的线索。
+  const rb = readFileSync(RELEASE_BUILD, 'utf8');
+
+  assert.doesNotMatch(rb, /'\(unknown\)'/,
+    '不得再写 (unknown) —— 那等于这一栏没信息');
+
+  assert.match(rb, /源码日期/,
+    '应记录源提交日期（判断构建用的是哪天源码）');
+  assert.match(rb, /版本回溯/,
+    '应指向可查的公开提交 / CHANGELOG');
 });