dsh-notify-say 0.4.55 → 0.4.57

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 > 本文件由 `tools/release-build.ps1` 从开发提交自动生成，**请勿手工编辑**。
 > 只列面向使用者的变更（新增功能与修复），不含内部维护提交。
 
+## v0.4.57 — 2026-10-18
+
+- fix(reload): v0.4.57 —— 自重载改为「点一次重载一次」（修宿主崩溃根因）
+
 ## v0.4.54 — 2026-10-18
 
 - feat(ui): v0.4.54 —— 第二阶段 UI：可读性、动态显示、二级分组

package/README.md

@@ -266,8 +266,14 @@ Windows 的 Toast 协议激活是一个固定串（`dsh://open`），没有地
 - **跳会话依赖未文档化 API**（`uiWorkspace`），官方随时可能改；坏了会自动降级为"只唤起窗口"
 - `blocked`（回合被拦截）只用系统蜂鸣，不播失败语音 —— 语义是"被拦下"而非"失败"
 - **失败语音只覆盖部分音色**：选到未覆盖的音色时，会在同池内换一个音色播，不会哑掉、也不会播错语义
-- **开发期热重载是实验性功能**（`devReload`，默认关）：它依赖 DSH/Cordis 内部结构与 Node 模块加载机制，
-  能工作但不算稳定能力。用户不需要它 —— 那是给改插件源码的人用的
+- **自重载是实验性功能，而且只有"点一次"**：设置页「高级设置 → 开发者选项」里有个
+  「重载现在生效」按钮，点一下尝试一次；**没有开关、不会自动监听文件**。
+  
+  为什么改成这样：2026-10-18 实测「监听文件自动重载」会把宿主拖崩 —— 一次改 UI 期间
+  触发了 40 多次失败重载，每次销毁实例都会释放宿主仍在用的会话引用，最后渲染进程崩溃。
+  危险的不是"重载失败"，是"**反复**重载"
+- **自重载不能替代重启**：它只能重新导入「同一路径上的」代码。用 `dsh plugin update`
+  升级后，新版本装在 `.pnpm/<name>@<ver>/` 另一个路径，自重载做不到 —— 必须重启 DSH
 - **13 个音色的许可结论是条件性判断**（依据官方通用条款），不代表各权利人出具过专项授权
 
 ---
@@ -330,7 +336,7 @@ npm run test:route    # 需要 --import loader 的接线测试
 npm run test:audio-wire
 ```
 
-**414 条测试通过。** 绝大多数是纯逻辑测试，克隆仓库后 `npm test` 即可跑。
+**426 条测试通过。** 绝大多数是纯逻辑测试，克隆仓库后 `npm test` 即可跑。
 
 少数用例需要真实的 DSH 宿主（用于验证 Cordis 上下文行为）。
 找不到宿主时它们会**自动 skip** —— 注意 skip 不等于通过。

package/lib/client.js

@@ -194,7 +194,8 @@ window.__ModuleLoader__.load({
       ok: { color: '#1e8449', fontSize: '12px', marginTop: '6px' },
       foot: { opacity: 0.65, marginTop: '12px', fontSize: '12.5px', lineHeight: '1.6' },
       // 事件开关：勾选框 + 可换行的说明文字
-      toggleRow: { display: 'flex', alignItems: 'flex-start', gap: '8px', margin: '8px 0' },
+      // 行间距略放大（v0.4.56）：420px 下说明文字密集，靠间距而不是缩字号。
+      toggleRow: { display: 'flex', alignItems: 'flex-start', gap: '8px', margin: '10px 0' },
       toggleBox: { marginTop: '3px', flex: '0 0 auto' },
       toggleText: { flex: '1', lineHeight: '1.5' },
       toggleLabel: { fontWeight: 500 },
@@ -598,6 +599,23 @@ window.__ModuleLoader__.load({
       var hvset = hvst[1]
       var advHover = hvst[0].id || ""
 
+      // 声音设置区的展开状态（v0.4.56）。
+      //
+      // `null` = 跟随默认：声音提醒开着就展开、关了就收起。
+      // 用户手动点过之后才固定成 true/false（不覆盖用户的显式选择）。
+      //
+      // ⚠️ 收起**只是隐藏**，配置一律保留；试听也在里面，
+      // 用户想看随时能展开 —— 不禁用任何操作。
+      var sndst = React.useState({ open: null })
+      var sndset = sndst[1]
+      var sndPref = sndst[0].open
+
+      // 一次性重载的界面状态（v0.4.57）。独立 state：与配置无关，
+      // 也不该因为保存配置（主 state 25 处 set 重建）被清掉。
+      var rlst = React.useState({ busy: false, msg: "", err: "" })
+      var rlset = rlst[1]
+      var rlState = rlst[0]
+
       var st = React.useState({
         loaded: false,
         values: {
@@ -953,6 +971,46 @@ window.__ModuleLoader__.load({
       //
       // 只检查、不安装。升级由用户自己执行 DSH 命令。
       // 详见 lib/update-check.js 头注释（为什么不自动更新）。
+      /**
+       * 一次性自重载（v0.4.57）。
+       *
+       * 用户要求：「点一下重载一下」，不要"开了就一直重载"。
+       * 所以这是一次显式请求，服务端也只尝试一次、失败不重试。
+       *
+       * ⚠️ 成功后当前实例已被 dispose、新实例接管，**这个响应可能发不回来**。
+       * 所以 .catch 与 !r 都按"可能已经重载"提示用户刷新页面，
+       * 而不是报"失败" —— 否则用户会以为没生效，反复点。
+       */
+      function doReload() {
+        rlset({ busy: true, msg: "", err: "" })
+        fetch(cfgUrl('reload'), {
+          method: 'POST',
+          cache: 'no-store',
+          credentials: 'same-origin',
+          headers: { 'content-type': 'application/json' },
+          body: '{}',
+        })
+          .then(function (r) { return r ? r.json().catch(function () { return null }) : null })
+          .then(function (r) {
+            if (!r) {
+              rlset({ busy: false, msg: '', err: '没有收到回应 —— 可能已经重载，请刷新页面确认；若未生效请重启 DSH。' })
+              return
+            }
+            if (r.ok && r.noop) {
+              rlset({ busy: false, msg: '磁盘上的代码与正在运行的一致，无需重载。', err: '' })
+              return
+            }
+            if (r.ok) {
+              rlset({ busy: false, msg: '已重载。请刷新页面，让设置界面也用新代码。', err: '' })
+              return
+            }
+            rlset({ busy: false, msg: '', err: r.hint || '重载没有成功 —— 请重启 DSH。' })
+          })
+          .catch(function () {
+            rlset({ busy: false, msg: '', err: '请求失败 —— 可能已经重载，请刷新页面确认；若未生效请重启 DSH。' })
+          })
+      }
+
       function checkVersion(force) {
         vset(function (p) {
           return { info: p.info, loading: true, copied: false }
@@ -1087,6 +1145,31 @@ window.__ModuleLoader__.load({
       // ── 二、声音设置 ────────────────────────────────────────────────
       rows.push(section('sound', '声音设置', '音量、音色与试听；语音包可按需下载。'))
 
+      // 声音提醒关掉时，把音频控件收起来（v0.4.56）。
+      //
+      // 用户指出：两个提醒都关了，下面还铺着整套 TTS 设置，视觉噪音大。
+      // 但**不能删**配置 —— 用户可能只是暂时静音，回头还要用。
+      var voiceOff = v.voice === false
+      var sndOpen = sndPref === null ? !voiceOff : sndPref === true
+      if (voiceOff) {
+        rows.push(h('div', { key: 'snd-off-head', style: S.foldHead,
+          onClick: function () { sndset({ open: !sndOpen }) },
+          role: 'button', tabIndex: 0,
+          'aria-expanded': sndOpen ? 'true' : 'false',
+          onKeyDown: function (e) {
+            if (e.key === 'Enter' || e.key === ' ') {
+              e.preventDefault()
+              sndset({ open: !sndOpen })
+            }
+          },
+        },
+          h('span', { style: { fontSize: '13px', opacity: 0.9 } },
+            '声音提醒已关闭，原有配置已保留'),
+          h('span', { style: S.foldArrow }, sndOpen ? '▾' : '▸'),
+        ))
+      }
+
+      if (sndOpen) {
       pushIf(curSource !== 'none', h('div', { key: 'vol', style: S.row },
         h('span', { style: S.label }, '音量'),
         h('input', {
@@ -1312,10 +1395,21 @@ window.__ModuleLoader__.load({
                     },
                   }, p.installed ? '卸载' : (p.downloadable ? '下载' : '不可用')),
                 ),
-                // 署名与条款：小字，不抢视觉但随时可查
+                // 署名与条款：小字，不抢视觉但随时可查。
+                //
+                // ⚠️ 占位提示的判据是「**能下载却没有条款**」（v0.4.56）：
+                // 那才是真的数据问题，值得提示。
+                //
+                // 原来判据是「没有 termsUrl 就提示」，于是**离线**时
+                // （索引取不到 → 已安装的包也没有 termsUrl）界面会显示
+                // 「条款链接待补」，看起来像插件发布缺字段 —— 虚报。
+                //
+                // 许可安全本身不受影响：下载按钮要求 p.downloadable，
+                // 而 downloadable 只可能来自带 terms 的远程索引。
                 h('div', { style: S.subHint },
                   (p.credit ? '署名：' + p.credit : '')
-                  + (p.termsUrl ? '' : '　（条款链接待补）'),
+                  // 内联判断（这里是表达式上下文，不能写 var）
+                  + ((p.downloadable && !p.termsUrl) ? '　（条款链接待补）' : ''),
                   p.termsUrl
                     ? h('a', {
                       href: p.termsUrl,
@@ -1541,6 +1635,8 @@ window.__ModuleLoader__.load({
         notifyOnAborted: false, notifyOnApproval: true, notifyOnQuestion: true,
         subagents: false, idleGate: true,
       }
+      }   // ← 声音设置区展开/收起（v0.4.56）
+
       // ── 三、提醒规则 ────────────────────────────────────────────────
       rows.push(section('rules', '提醒规则', '哪些事件要提醒你。默认只提醒需要你关注的那些。'))
       // 按「什么时候会用到」分三组渲染（v0.4.54）。
@@ -1803,7 +1899,8 @@ window.__ModuleLoader__.load({
               var KIND_ROWS = [['Done', '任务完成'], ['Fail', '任务失败'],
                 ['Question', '向你提问'], ['Approval', '待你批准'], ['Blocked', '被拦截']]
               var FOLLOW = '__follow__'
-          rows.push(h('div', { key: 'adv-group', style: S.groupLabel }, '按事件覆盖声音来源'))
+          // 内层不再重复标题 —— 二级分组已经叫「按事件定制声音」（v0.4.56）。
+        // 只保留说明，直接接五个事件选择器。
           rows.push(h('div', { key: 'advhint', style: S.subHint },
             '默认跟随上面的「声音来源」。只有你改过的那几行才会单独生效。'))
           KIND_ROWS.forEach(function (pair) {
@@ -2225,25 +2322,38 @@ window.__ModuleLoader__.load({
               rows.push(h('div', { key: 'dev-warn', style: S.subHint },
                 '⚠️ 实验性：依赖宿主内部结构与 Node 模块加载机制，'
                   + 'DSH 升级后可能失效。失效时只报错，不影响播报。'))
-          // ── 开发选项：热重载 ────────────────────────────────────────────────
-          //
-          // 让用户自己选，而不是我替他决定。默认关（生产安装不需要）。
-          // 开启后：改插件源码保存 → 自动换成新代码，不用重启 DSH。
-          rows.push(h('div', { key: 'sepHr', style: { margin: '10px 0 4px', borderTop: '1px solid rgba(128,128,128,.25)' } }))
-          rows.push(h('div', { key: 'dr', style: S.toggleRow },
-            h('input', {
-              type: 'checkbox',
-              checked: v.devReload === true,
-              disabled: s.busy,
-              style: S.toggleBox,
-              onChange: function (e) { apply({ devReload: !!e.target.checked }, '热重载设置已更新') },
-            }),
-            h('div', { style: S.toggleText },
-              h('span', { style: S.toggleLabel }, '改代码后自动热重载（实验性）'),
-              h('span', { style: S.toggleDesc },
-                '保存插件源码后自动生效，不必重启 DSH。'),
-            ),
-          ))
+              // ── 一次性自重载（v0.4.57）────────────────────────────────
+              //
+              // 用户 2026-10-18 明确要求：「点一下重载一下」，
+              // 不要"开了就一直重载"。所以这里**没有开关**，只有一个按钮。
+              //
+              // 为什么把自动监听删了：2026-10-18 实测它把宿主拖崩 ——
+              // watcher 在我改 UI 期间触发了 40 多次失败重载，每次 dispose
+              // 都释放宿主仍在用的会话引用，最后渲染进程崩在损坏的 client 包上。
+              rows.push(h('div', { key: 'dr-row', style: S.row },
+                h('button', {
+                  type: 'button',
+                  disabled: rlState.busy,
+                  style: S.btn,
+                  onClick: function () { doReload() },
+                }, rlState.busy ? '重载中…' : '重载现在生效'),
+                h('span', { style: S.hint }, '点一次试一次，不会自动重复'),
+              ))
+              rows.push(h('div', { key: 'dr-hint', style: S.subHint },
+                '用途：改完 lib/ 下的代码后，不想重启 DSH 就点一下。'
+                  + '**只对同一路径上的代码有效**；如果刚用 dsh plugin update '
+                  + '升级了版本，新版本装在另一个路径，自重载做不到，必须重启。'))
+              if (rlState.msg) {
+                rows.push(h('div', { key: 'dr-msg', style: S.ok }, rlState.msg))
+              }
+              if (rlState.err) {
+                rows.push(h('div', { key: 'dr-err', style: S.err }, rlState.err))
+              }
+              // 重载后宿主里的会话引用会被释放 —— 用户必须知道要刷新页面，
+              // 否则会遇到"侧边栏点不开"却不知道为什么。
+              rows.push(h('div', { key: 'dr-warn', style: S.subHint },
+                '重载会重建插件实例，宿主里已打开的会话引用会失效。'
+                  + '重载成功后请**刷新页面**；不行就重启 DSH。'))
             }
           }
         })

package/lib/dev-reload.js

@@ -682,65 +682,71 @@ export function selfReload(ctx, options = {}) {
   return inFlight.finally(() => { inFlight = null; });
 }
 
-/**
- * 监听包目录，变更时触发回调（防抖）。
- *
- * 刻意**不自动重载**：由调用方决定怎么用（例如只在 devReload 开启时调 selfReload）。
- * 自动重载会在你保存到一半的文件上触发，拿到语法错误的半成品。
- *
- * @param {string} packageDir
- * @param {{ onChange?: Function, logger?: object, debounceMs?: number }} [opts]
- * @returns {() => void} 停止函数
- */
-export function watchPackage(packageDir, opts = {}) {
-  const logger = opts.logger || console;
-  const debounceMs = Number.isFinite(opts.debounceMs) ? opts.debounceMs : 800;
-  let timer;
-  let paused = false;
-  let watcher;
-  try {
-    // ⚠️ 2026-10-18 外部审阅指出：监听整个目录，但指纹只覆盖
-    // package.json + lib/*.js。改文档或测试也会触发一次注定失败的重载。
-    // 过滤在 schedule(filename) 里做（见 isSourceFile）。
-    watcher = fs.watch(packageDir, { recursive: true });
-    try { opts.diag?.('watching ', packageDir); } catch {}
-  } catch (error) {
-    try { logger.warn?.(`[dsh-notify-say] cannot watch ${packageDir}: ${(error && error.message) || error}`); } catch { /* ignore */ }
-    return () => {};
+// ── 重载决策（v0.4.57）──────────────────────────────────────────────────
+//
+// 把「这次点击该不该真的重载」抽成纯函数 —— 因为它正是上次崩溃的关键：
+// 在自动监听时代，**每一次文件保存都直接进入重载流程**，没有做任何
+// "现在真的需要重载吗"的判断，于是 40 多次保存换来 40 多次 dispose。
+//
+// 抽成纯函数的好处是它能被完整测试（不需要活宿主）：
+//   · 代码没变 → noop（一次 dispose 都不做）
+//   · 插件根真实路径变了（pnpm 升级到新版本）→ 拒绝，并告知必须重启
+//   · 确实变了 → reload（一次）
+//
+// @param {{ diskFingerprint?: string, runningFingerprint?: string,
+//           resolvedRootAtLoad?: string, resolvedRootNow?: string }} input
+// @returns {{ action: 'noop'|'refuse-path-changed'|'reload',
+//             reason: string, hint?: string }}
+export function planReload(input = {}) {
+  const disk = String(input.diskFingerprint || '');
+  const running = String(input.runningFingerprint || '');
+
+  // ① 读不到磁盘指纹：无法证明"变了"，但也不能断言"没变"。
+  //    按 reload 处理会让用户在只读沙箱里反复触发失败 ——
+  //    按 noop 处理则可能让用户以为已生效。
+  //    这里选 reload（唯一有机会真正生效的选择），失败会如实报错。
+  if (!disk) {
+    return { action: 'reload', reason: 'fingerprint-unreadable' };
   }
-  // 只有这些文件变了才值得重载（与指纹覆盖范围保持一致）。
-  const isSourceFile = (filename) => {
-    if (!filename) return true;   // 拿不到文件名时保守处理：当真
-    const f = String(filename).replace(/\\/g, '/');
-    if (f === 'package.json') return true;
-    if (f.startsWith('lib/') && f.endsWith('.js')) return true;
-    return false;
-  };
-
-  const schedule = (filename) => {
-    if (paused) return;
-    if (!isSourceFile(filename)) return;   // 文档/测试变更不触发重载
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      timer = undefined;
-      if (paused) return;
-      try { opts.onChange?.(); } catch (error) {
-        try { logger.warn?.(`[dsh-notify-say] watch onChange threw: ${(error && error.message) || error}`); } catch { /* ignore */ }
-      }
-    }, debounceMs);
-    if (timer && typeof timer.unref === 'function') timer.unref();
-  };
-  // fs.watch 的监听器签名是 (eventType, filename)
-  watcher.on('change', (eventType, filename) => {
-    try { opts.diag?.('event ', String(filename), ' accepted=', String(isSourceFile(filename))); } catch {}
-    schedule(filename);
-  });
-  watcher.on('error', (error) => {
-    try { logger.warn?.(`[dsh-notify-say] watcher error: ${(error && error.message) || error}`); } catch { /* ignore */ }
-  });
-  return () => {
-    paused = true;
-    clearTimeout(timer);
-    try { watcher.close(); } catch { /* 已关闭 */ }
-  };
+
+  // ② 磁盘内容 == 当前实例内容 → 毫无必要重载。
+  //    **这一条就是上次 40 多次无效 dispose 的止血点。**
+  if (running && disk === running) {
+    return { action: 'noop', reason: 'already-current' };
+  }
+
+  // ③ 插件根的真实路径变了 → 自重载救不了。
+  //
+  // `dsh plugin update` 升级后 pnpm 会把包装到新的 .pnpm/<name>@<ver>/，
+  // 而我们手上只有加载时那个路径；从旧路径重新导入拿到的是旧代码。
+  // 与其让用户点完一个"看起来成功其实没换"的按钮，不如直接说清楚。
+  const atLoad = String(input.resolvedRootAtLoad || '');
+  const now = String(input.resolvedRootNow || '');
+  if (atLoad && now && atLoad !== now) {
+    return {
+      action: 'refuse-path-changed',
+      reason: 'path-changed',
+      hint: '新版本装在另一个路径，自重载无法生效 —— 请重启 DSH。',
+    };
+  }
+
+  return { action: 'reload', reason: 'changed' };
 }
+// ── 自动监听已移除（v0.4.57）─────────────────────────────────────────────
+//
+// 这里原来导出 `watchPackage()`：监视包目录，文件一变就触发一次自重载。
+//
+// **2026-10-18 实测它把宿主拖崩了**，崩溃日志给的两条硬证据：
+//
+//   ① 45 条「热重载失败：fingerprint unchanged（旧代码仍在运行）」
+//      —— 那天为调 UI 改了 40 多次文件，每次保存都触发一次注定失败的尝试；
+//   ② 同一时刻反复出现「Session reference "..." is released」
+//      —— 每次重载都 dispose 旧实例，而 dispose 会释放渲染进程仍在用的
+//         会话引用。反复 45 次之后渲染进程拿到损坏的 client 包，
+//         抛 SyntaxError，宿主退出。
+//
+// 结论：危险的不是「重载失败」，而是「**反复**重载」。
+// 现在改由用户在设置页点一次按钮、调一次 `selfReload()`——
+// 一次点击 = 一次尝试，最坏结果是「这次没成功」，不再累积。
+//
+// 相关：lib/index.js 的 `reloadOnce()` 与 `POST /reload` 路由。

package/lib/index.js

@@ -84,7 +84,7 @@
  * 失败一律 fail-visible：判定异常时走主任务分支照常播报，不静默用户。
  */
 import { spawn } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
@@ -102,11 +102,26 @@ import { checkForUpdate } from './update-check.js';
 import { createVoicePackRoute } from './voice-pack-route.js';
 import { isDebug, redactText } from './log-privacy.js';
 import { exportDiagnostics } from './diagnostics.js';
-import { selfReload, watchPackage, computeFingerprint } from './dev-reload.js';
+// ⚠️ 不再导入 watchPackage（v0.4.57）：自动监听重载已移除，见 dev-reload.js 末尾注释。
+import { selfReload, computeFingerprint, planReload } from './dev-reload.js';
 import { pickTtsText, sanitizeTtsText, MAX_TEXT_LEN } from './tts-lines.js';
 
 const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
+/**
+ * 加载那一刻插件根的**真实路径**（解开 Junction / 符号链接）。
+ *
+ * 用途：判断"自重载还能不能救"。
+ *
+ * 自重载只能重新导入「**同一路径上的**」代码。`dsh plugin update` 升级后，
+ * pnpm 会把包装到新的 `.pnpm/<name>@<ver>/` 下，而这里的 PLUGIN_ROOT
+ * 在加载时就已解析成旧路径 —— 那时从旧路径重新导入，拿到的仍是旧代码。
+ * 所以点按钮时比一次，路径变了就**如实说"必须重启"**，不给假希望。
+ */
+const RESOLVED_PLUGIN_ROOT = (() => {
+  try { return realpathSync(PLUGIN_ROOT); } catch { return PLUGIN_ROOT; }
+})();
+
 
 // 检查更新的宿主侧缓存（v0.4.48）。
 //
@@ -749,6 +764,11 @@ export function effectiveForClient(c) {
 }
 
 export function apply(ctx, config) {
+  // 一次性自重载的实现槽（v0.4.57）。
+  //
+  // 路由在 apply 中段注册、实现挂在 apply 末尾 —— 用 let 槽连接两者。
+  // （不写成函数声明：它包在 try 块里，严格模式下块级作用域不会提升出去。）
+  let reloadOnce = null;
   // ── 配置来源（v0.4.0 起三源合并）──────────────────────────────────────────
   //
   // 优先级（后覆盖前）：
@@ -1610,7 +1630,10 @@ function hasVoiceLine(psKind) {
                 (head === 'config' && /\/set\b/.test(pathname))
                 || head === 'consume'
                 || head === 'diagnostics'
-                || (head === 'voicepacks' && (/\/install\b/.test(pathname) || /\/uninstall\b/.test(pathname)));
+                || (head === 'voicepacks' && (/\/install\b/.test(pathname) || /\/uninstall\b/.test(pathname)))
+                // v0.4.57：一次性自重载会 dispose 当前实例并重新求值模块，
+                // 是不可逆副作用，按写操作处理。
+                || head === 'reload';
                 const guard = checkLocalOrigin(req, { write: isWriteRoute });
                 if (!guard.ok) {
                 try {
@@ -1627,6 +1650,56 @@ function hasVoiceLine(psKind) {
         //
         // 为什么不接受客户端传 URL：那等于让本机访问任意地址（SSRF）。
         // 查询地址固定在 update-check.js 里。
+        // ── 一次性自重载（v0.4.57）──────────────────────────────────
+        //
+        // 用户 2026-10-18 明确要求：「点一下重载一下」，不要"开了就一直重载"。
+        // 所以这里是**纯显式动作**：没有任何自动触发（watcher 已删除）。
+        //
+        // 只接受 POST —— 它不可逆。
+        if (head === 'reload') {
+          if (String((req && req.method) || 'GET').toUpperCase() !== 'POST') {
+            try {
+              res.writeHead(405, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', allow: 'POST' });
+              res.end(JSON.stringify({ ok: false, reason: 'method-not-allowed' }));
+            } catch { /* 响应已发出 */ }
+            return;
+          }
+          if (!reloadOnce) {
+            try {
+              res.writeHead(503, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+              res.end(JSON.stringify({ ok: false, reason: 'reload-unavailable' }));
+            } catch { /* 响应已发出 */ }
+            return;
+          }
+          // 限流：5 秒内只允许一次（防连点、也防脚本反复触发 dispose）
+          const rlGate = throttle('reload', 5000);
+          if (!rlGate.ok) {
+            try {
+              res.writeHead(429, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'retry-after': String(Math.ceil((rlGate.retryAfterMs || 1000) / 1000)) });
+              res.end(JSON.stringify({ ok: false, reason: 'throttled', retryAfterMs: rlGate.retryAfterMs }));
+            } catch { /* 响应已发出 */ }
+            return;
+          }
+          // ⚠️ 成功后当前实例已被 dispose、新实例接管 ——
+          // 这个响应**可能发不出去**。客户端必须把"请求失败"也当作
+          // "可能已重载"，提示用户刷新页面。
+          Promise.resolve()
+            .then(() => reloadOnce())
+            .then((r) => {
+              try {
+                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                res.end(JSON.stringify(r));
+              } catch { /* 响应已发出 */ }
+            })
+            .catch((e) => {
+              try {
+                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                res.end(JSON.stringify({ ok: false, reason: 'exception', error: String((e && e.message) || e) }));
+              } catch { /* 响应已发出 */ }
+            });
+          return;
+        }
+
         if (head === 'version') {
           // ?force=1 表示用户手动点了「检查更新」，绕过 24 小时缓存
           const force = /[?&]force=1\b/.test(String((req && req.url) || ''));
@@ -1878,92 +1951,90 @@ function hasVoiceLine(psKind) {
   // ⚠️ 防无限循环：重载后新实例的 apply 会**再次**读到 devReload=true，
   // 若不做标记就会重载→重载→…。故用 globalThis 上的时间戳做冷却：
   // 30 秒内已重载过就跳过。key 带插件名，避免与其它插件冲突。
-  try {
-    if (cfg.devReload) {
-      // ⚠️ 语义必须是「**改文件时**重载」，不是「启动后重载一次」。
-      //
-      // 第一版写成启动后 1.5 秒触发一次 —— 那是错的：没人改文件时重载毫无意义，
-      // 而且每次启动都白跑一次高风险操作。真正的需求是监听源码变更。
-      //
-      // 用 watchPackage（lib/dev-reload.js）监听包目录，变更 → 防抖 → 重载。
-      // 防抖 800ms：编辑器保存常触发多次事件，太灵敏会在写到一半时重载，
-      // 拿到语法不完整的文件。
-      const stop = watchPackage(PLUGIN_ROOT, {
-        // v0.4.44 诊断：把 watcher 的注册与事件写进 notify.log，
-        // 否则"重载没触发"和"重载触发了但失败"无法区分（我为此误判过一次）。
-        diag: (tag, a, b, c) => appendNotifyLog('[watch] ' + tag + (a || '') + (b || '') + (c || '')),
+  // ── 一次性自重载的实现（v0.4.57）──────────────────────────────────────
+  //
+  // 用户要求：点一下重载一次；不点就不动。这里只是**把能力准备好**，
+  // 不做任何自动触发 —— 触发点只有 `POST /reload`（设置页的按钮）。
+  //
+  // ## 为什么删掉 watcher
+  //
+  // 2026-10-18 实测它把宿主拖崩，崩溃日志两条硬证据：
+  //   ① 45 条「fingerprint unchanged（旧代码仍在运行）」
+  //      —— 那天为调 UI 改了 40 多次文件，每次保存触发一次注定失败的尝试；
+  //   ② 同一时刻反复「Session reference "..." is released」
+  //      —— 每次重载都 dispose 旧实例，而 dispose 会释放渲染进程仍在用的
+  //         会话引用；反复几十次后渲染进程拿到损坏的 client 包，
+  //         抛 SyntaxError，宿主退出。
+  //
+  // 结论：危险的不是"失败"，是"**反复**"。一次点击一次尝试，不再累积。
+  reloadOnce = async function () {
+    // ① 前置：磁盘内容与当前实例相同 → 什么都不做
+    //
+    // 同一件事的"没变"判断放在最前面，因为它最省钱也最安全：
+    // 代码没变就不该 dispose 任何东西。
+    let diskFingerprint = '';
+    try { diskFingerprint = computeFingerprint(PLUGIN_ROOT); } catch { /* 读不到就继续 */ }
+    // ② 决策抽在 dev-reload.js 的 planReload() —— 纯函数，可完整测试。
+    //
+    //    代码没变            → noop（一次 dispose 都不做）
+    //    插件根真实路径变了  → 拒绝，告知必须重启
+    //    确实变了            → reload（一次）
+    let nowReal = '';
+    try { nowReal = realpathSync(PLUGIN_ROOT); } catch { /* 解不开就不比 */ }
+    const plan = planReload({
+      diskFingerprint,
+      runningFingerprint: fingerprint,
+      resolvedRootAtLoad: RESOLVED_PLUGIN_ROOT,
+      resolvedRootNow: nowReal,
+    });
+    if (plan.action === 'noop') {
+      return { ok: true, noop: true, reason: plan.reason, fingerprint };
+    }
+    if (plan.action === 'refuse-path-changed') {
+      return { ok: false, reason: plan.reason, hint: plan.hint };
+    }
+
+    // ③ 一次尝试。失败**不重试**，直接如实返回让用户去重启。
+    const eventsBefore = readEventCount();
+    let r;
+    try {
+      r = await selfReload(ctx, {
         logger: console,
-        debounceMs: 800,
-        onChange: () => {
-          const KEY = Symbol.for('dsh-notify-say.devReloadAt');
-          const last = Number(globalThis[KEY]) || 0;
-          // 冷却：一次保存可能触发多个文件事件，也防止重载后立刻又重载
-          if (Date.now() - last < 3000) return;
-          globalThis[KEY] = Date.now();
-
-          // v0.4.36：记下重载前的事件计数，成功后算差值。
-          // 差值 > 0 说明重载窗口内有事件到达，那些播报可能丢了。
-          const eventsBeforeReload = readEventCount();
-
-          // ── 计算"磁盘上现在应该是什么"（v0.4.20）──────────────────────
-          //
-          // 重载必须能自证：换上来的代码 == 磁盘上的代码。
-          // 只靠"拿到新模块对象"不够 —— 那可能只是入口换了、依赖还是旧的。
-          //
-          // 这里算出磁盘内容的指纹，连同代际标记一起交给 selfReload；
-          // 它会在**刚加载的模块里**比对这个值，不一致就判失败并回滚。
-          //
-          // 注意：这个指纹是"内容哈希"，而 index.js 导出的 fingerprint 是
-          // "代际标记"，两者用途不同，不能混。
-          const diskFingerprint = computeFingerprint(PLUGIN_ROOT);
-          selfReload(ctx, {
-            logger: console,
-            // 期望新模块导出一个非空 fingerprint（证明它被重新求值过）
-            expectedFingerprint: undefined,
-            // 但必须要求：新模块的 fingerprint 与**当前这个实例**不同
-            differFrom: fingerprint,
-            diskFingerprint,
-          }).then((r) => {
-            try {
-              if (r.ok) {
-              // 重载窗口内是否有事件被吞掉（见 EVENT_COUNTER_KEY 的注释）
-              try {
-                const missed = readEventCount() - eventsBeforeReload;
-                if (missed > 0) {
-                  // ⚠️ 文案必须准确（外部审阅 2026-10-18 指出）：
-                  // 这个计数器只在 session/event 回调里 +1 ——
-                  // 若重载期间**根本没有监听器**，事件被宿主发出但插件没收到，
-                  // 计数不会增加，missed 却是 0（漏检）。
-                  // 反过来旧/新实例正常处理了事件，计数增加但通知已发出（误报）。
-                  //
-                  // 所以它只能说明"重载窗口内插件观察到过事件"，
-                  // 不能当漏报数量。文案按这个口径写。
-                  appendNotifyLog(`[reload] 重载窗口内观察到 ${missed} 个事件（非漏报数，仅供排查参考）`);
-                  console.warn(`[dsh-notify-say] 重载窗口内观察到 ${missed} 个事件（非漏报数）`);
-                }
-              } catch { /* ignore */ }
-                console.log(`[dsh-notify-say] 已热重载（${r.fibers} 个 fiber`
-                  + `${r.busted ? '，走了代际绕过' : ''}`
-                  + `${r.verified ? '，指纹校验通过' : ''}）`);
-              } else {
-                appendNotifyLog(`[reload] FAILED ${r.error}`);
-                appendNotifyLog(`[reload] FAILED ${r.error}${r.restored ? ' (旧代码仍在跑)' : ' (回滚也失败)'}`);
-                console.warn(`[dsh-notify-say] 热重载失败：${r.error}`
-                  + (r.restored ? '（旧代码仍在运行）' : '（回滚也失败，建议重启宿主）'));
-              }
-            } catch { /* ignore */ }
-          }).catch(() => { /* selfReload 内部已兜底 */ });
-        },
+        expectedFingerprint: undefined,
+        differFrom: fingerprint,
+        diskFingerprint,
       });
-      // 停掉监听挂到 effect 上：插件被卸载/重载时自动清理，否则旧实例的 watcher 会残留
-      try {
-        if (typeof ctx.effect === 'function') ctx.effect(() => stop, 'dsh-notify-say: dev-reload watcher');
-        else process.once('exit', () => { try { stop() } catch { /* ignore */ } });
-      } catch {
-        try { stop(); } catch { /* ignore */ }
-      }
+    } catch (e) {
+      return { ok: false, reason: 'exception', error: String((e && e.message) || e) };
+    }
+
+    if (r && r.ok) {
+      // 重载窗口内是否观察过事件（只作排查参考，不是漏报数 ——
+      // 口径见 EVENT_COUNTER_KEY 的注释）。
+      let observed = 0;
+      try { observed = readEventCount() - eventsBefore; } catch { /* ignore */ }
+      appendNotifyLog('[reload] OK by-user' + (observed > 0 ? ' observed=' + observed : ''));
+      return {
+        ok: true,
+        reason: 'reloaded',
+        fibers: r.fibers,
+        busted: !!r.busted,
+        verified: !!r.verified,
+        observed,
+      };
     }
-  } catch { /* 热重载不可用不影响主功能 */ }
+
+    const err = String((r && r.error) || 'unknown');
+    appendNotifyLog('[reload] FAILED ' + err);
+    return {
+      ok: false,
+      reason: 'reload-failed',
+      error: err,
+      restored: !!(r && r.restored),
+      hint: '自重载没有成功，旧代码仍在运行 —— 请重启 DSH。',
+    };
+  };
+
 }
 
 // ── 官方 Config schema 导出（v0.4.0）─────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-notify-say",
-    "version":  "0.4.55",
+    "version":  "0.4.57",
     "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-bundle.test.mjs

@@ -555,12 +555,16 @@ test('C19: 高级折叠区含五种事件的音源覆盖', () => {
 // 用户 2026-10-17 要求："UI 里面没有放上热重载吗？让他选支不支持"
 test('C20: GUI 有热重载开关，且说明其风险', () => {
   const src = readClient();
-  assert.match(src, /apply\(\{ devReload: !!e\.target\.checked \}/, '应有 devReload 保存逻辑');
-  // 文案在 v0.4.54 第二阶段 UI 里从「开发：改代码后自动热重载」改成
-  // 「改代码后自动热重载（实验性）」—— 因为现在它在「开发者选项」子组里，
-  // 「开发：」前缀冗余；「实验性」比「开发」更准确地表达了风险等级。
-  // ⚠️ 改的只是措辞，下面「依赖内部结构 / 失效时只报错」的风险断言一字未动。
-  assert.match(src, /改代码后自动热重载（实验性）/, '应有开关文案');
+  // ⚠️ v0.4.57：从「自动热重载开关」改成「点一次重载一次」的按钮。
+  //
+  // 原因（2026-10-18 实测宿主崩溃）：watcher 在我改 UI 期间触发了 40 多次
+  // 失败重载，每次 dispose 都释放宿主仍在用的会话引用，最后渲染进程崩溃。
+  // 现在没有开关、没有自动触发，只有显式按钮。
+  assert.doesNotMatch(src, /apply\(\{ devReload: !!e\.target\.checked \}/,
+    '不应再有 devReload 的自动重载开关 —— 自动触发已被移除');
+  assert.match(src, /重载现在生效/, '应有一键重载按钮');
+  assert.match(src, /function doReload\(\)/, '按钮应触发一次显式重载请求');
+  assert.match(src, /cfgUrl\('reload'\)/, '重载应走 POST /reload');
   // 必须说明风险：依赖宿主内部结构、失效不影响播报
   assert.match(src, /依赖宿主内部结构/, '应说明它依赖内部结构');
   assert.match(src, /失效时只报错/, '应说明失效时的行为');

package/test/reload-once.test.mjs

@@ -0,0 +1,145 @@
+/**
+ * 一次性自重载的行为测试（v0.4.57）。
+ *
+ * ## 为什么这个文件存在
+ *
+ * 2026-10-18 宿主崩了。崩溃日志给了两条硬证据：
+ *
+ *   ① 45 条「热重载失败：fingerprint unchanged（旧代码仍在运行）」
+ *      —— 那天为调 UI 改了 40 多次文件，每次保存都触发一次注定失败的尝试；
+ *   ② 同一时刻反复「Session reference "..." is released」
+ *      —— 每次重载都 dispose 旧实例，而 dispose 会释放渲染进程仍在用的
+ *         会话引用；反复几十次后渲染进程拿到损坏的 client 包，抛
+ *         SyntaxError，宿主退出。
+ *
+ * **危险的不是"重载失败"，是"反复重载"。**
+ *
+ * 所以设计改成：删掉 watcher，只在用户点按钮时尝试一次。
+ * 而"该不该真的试"的判断抽成 `planReload()` 纯函数 —— 它就是这个文件的主角：
+ *
+ *   · 代码没变 → noop（**一次 dispose 都不做**，这是止血点）
+ *   · 插件根路径变了（pnpm 升级）→ 拒绝，并如实说必须重启
+ *   · 确实变了 → reload（一次，失败不重试）
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { planReload } from '../lib/dev-reload.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const IDX = readFileSync(join(ROOT, 'lib', 'index.js'), 'utf8');
+const DR = readFileSync(join(ROOT, 'lib', 'dev-reload.js'), 'utf8');
+const CLIENT = readFileSync(join(ROOT, 'lib', 'client.js'), 'utf8');
+
+/** 去掉注释，只看真正会执行的代码。 */
+function code(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .split(/\r?\n/)
+    .filter((l) => !/^\s*\/\//.test(l))
+    .join('\n');
+}
+
+// ── P1: 代码没变 → 一次 dispose 都不做 ──────────────────────────────────
+test('P1: 磁盘指纹与运行中一致时 → noop（不重载）', () => {
+  // 这是整个修复的止血点：上次那 45 次失败尝试，全部属于"点了但没必要"或
+  // "自动触发但没必要"的情形。noop 让它们连 dispose 都不会发生。
+  const r = planReload({
+    diskFingerprint: 'abc123',
+    runningFingerprint: 'abc123',
+    resolvedRootAtLoad: 'E:/p',
+    resolvedRootNow: 'E:/p',
+  });
+  assert.equal(r.action, 'noop');
+  assert.equal(r.reason, 'already-current');
+});
+
+// ── P2: 插件根路径变了 → 拒绝并说清原因 ─────────────────────────────────
+test('P2: 插件根真实路径变了 → 拒绝重载，提示重启', () => {
+  // pnpm 升级会把包装到新的 .pnpm/<name>@<ver>/ 下。
+  // 我们从加载时的旧路径重新导入，拿到的仍是旧代码 —— 与其给一个
+  // "看起来成功其实没换"的按钮，不如直接说清楚。
+  const r = planReload({
+    diskFingerprint: 'NEW',
+    runningFingerprint: 'OLD',
+    resolvedRootAtLoad: 'C:/d/.pnpm/pkg@0.4.56/node_modules/pkg',
+    resolvedRootNow: 'C:/d/.pnpm/pkg@0.5.0/node_modules/pkg',
+  });
+  assert.equal(r.action, 'refuse-path-changed');
+  assert.equal(r.reason, 'path-changed');
+  assert.match(r.hint, /重启/, '必须明确告知只能重启');
+});
+
+// ── P3: 确实变了 → 重载一次 ─────────────────────────────────────────────
+test('P3: 代码确实变了且路径未变 → reload', () => {
+  const r = planReload({
+    diskFingerprint: 'NEW',
+    runningFingerprint: 'OLD',
+    resolvedRootAtLoad: 'E:/p',
+    resolvedRootNow: 'E:/p',
+  });
+  assert.equal(r.action, 'reload');
+});
+
+// ── P4: 读不到指纹 → 不能假装"已是最新" ─────────────────────────────────
+test('P4: 读不到磁盘指纹时不清空判断（按 reload 处理）', () => {
+  // 只读沙箱里 computeFingerprint 会返回 ''。
+  // 这时若判 noop，用户会以为已生效；判 reload 至少有机会真的生效，
+  // 失败也会如实报错。
+  const r = planReload({
+    diskFingerprint: '',
+    runningFingerprint: 'abc',
+    resolvedRootAtLoad: 'E:/p',
+    resolvedRootNow: 'E:/p',
+  });
+  assert.equal(r.action, 'reload', '不能因为读不到指纹就静默 noop');
+  assert.equal(r.reason, 'fingerprint-unreadable');
+});
+
+// ── P5: 唯一入口是 POST /reload，且算写操作 ─────────────────────────────
+test('P5: 重载只经 POST /reload，且被当作写操作保护', () => {
+  assert.match(IDX, /head === 'reload'/, '应有 /reload 路由');
+  assert.match(IDX, /toUpperCase\(\) !== 'POST'/, '必须只接受 POST（不可逆操作）');
+  // 写操作 → 走本地来源防护（Origin/跨站检查）
+  const writeAt = IDX.indexOf('const isWriteRoute =');
+  assert.ok(writeAt > 0, '应能定位 isWriteRoute');
+  const seg = IDX.slice(writeAt, writeAt + 900);
+  assert.match(seg, /head === 'reload'/, '/reload 必须列进 isWriteRoute');
+});
+
+// ── P6: 没有任何自动触发路径 ────────────────────────────────────────────
+test('P6: 没有任何自动触发（无 watcher、无定时器驱动重载）', () => {
+  // 这一条锁住"用户要求：点一下重载一下，不要一直在重载"。
+  const dr = code(DR);
+  assert.doesNotMatch(dr, /fs\.watch/, 'dev-reload.js 不应再监听文件系统');
+  assert.doesNotMatch(dr, /watchPackage/, 'watchPackage 应已彻底移除');
+
+  const idx = code(IDX);
+  assert.doesNotMatch(idx, /watchPackage/, 'index.js 不应再调用 watchPackage');
+  assert.doesNotMatch(idx, /devReload\)\s*\{\s*[\s\S]{0,200}selfReload/,
+    '不应再有「配置开着就自动重载」的路径');
+});
+
+// ── P7: GUI 只有一个按钮，没有开关 ──────────────────────────────────────
+test('P7: GUI 是按钮而不是开关', () => {
+  assert.match(CLIENT, /重载现在生效/, '应有一次性重载按钮');
+  assert.doesNotMatch(CLIENT, /apply\(\{ devReload: !!e\.target\.checked \}/,
+    '不应再有自动热重载开关');
+  // 按钮必须说明它不会自动重复，以及"升级后必须重启"
+  assert.match(CLIENT, /不会自动重复/, '应说明不会自动重复');
+  assert.match(CLIENT, /新版本装在另一个路径/, '应说明升级场景自重载做不到');
+});
+
+// ── P8: 每次尝试都留可观测痕迹 ──────────────────────────────────────────
+test('P8: 成功与失败都写进 notify.log', () => {
+  // watcher 时代的 `[watch]` 信号没了，可观测性要补在重载结果上，
+  // 否则"点了没反应"无法排查。
+  assert.match(IDX, /\[reload\] OK by-user/);
+  assert.match(IDX, /\[reload\] FAILED/);
+  const okAt = IDX.indexOf('[reload] OK by-user');
+  const seg = IDX.slice(Math.max(0, okAt - 400), okAt + 80);
+  assert.match(seg, /appendNotifyLog/, '必须写文件，不能只进 console');
+});

package/test/reload-review.test.mjs

@@ -97,26 +97,40 @@ test('X4: 事件计数日志如实说明「非漏报数」', () => {
   //   · 重载期间没有监听器 → 事件没被观察到，missed=0（漏检）
   //   · 旧/新实例正常处理了 → 计数增加但通知已发出（误报）
   // 所以它只能叫"观察到的事件数"，不能说"漏报数"。
-  assert.match(IDX, /非漏报数/,
+  assert.match(IDX, /非漏报数|不是漏报数/,
     '日志文案必须说明这个数字不是漏报数量 —— 否则排查时会被误导');
 
   assert.doesNotMatch(IDX, /对应播报可能已丢失/,
     '不能声称"播报已丢失"—— 计数器证明不了这件事');
 });
 
-// ── X5: 监听要有源码过滤 ────────────────────────────────────────────────
-test('X5: 只有源码变更才触发重载', () => {
-  const c = code(DR);
-
-  assert.match(c, /isSourceFile/,
-    '应有源码文件过滤 —— 否则改文档/测试也会触发一次注定失败的重载');
+// ── X5: 没有任何自动触发（只能用户点击）────────────────────────────────
 
-  // 过滤要覆盖指纹的同样范围：package.json + lib/*.js
-  const at = c.indexOf('isSourceFile');
-  const seg = c.slice(at, at + 600);
-  assert.match(seg, /package\.json/, '应包含 package.json');
-  assert.match(seg, /lib\//, '应包含 lib/ 目录');
-  assert.match(seg, /\.js/, '应限定 .js');
+test('X5: 重载只能由用户点击触发，没有 watcher', () => {
+  // v0.4.57 之前这里是「监听要有源码过滤」。
+  // 那个保障针对的是"改了文档也会触发一次注定失败的重载"。
+  //
+  // 现在设计变了：**根本没有 watcher**，所以那类问题从根上消失。
+  // 保障升级为更强的一条：不许出现任何自动触发路径。
+  //
+  // 背景（2026-10-18 宿主崩溃）：watcher 在我改 UI 期间触发了 40 多次
+  // 失败重载 —— 每次 dispose 都释放宿主仍在用的会话引用。
+  // 去掉自动触发不是"少了个功能"，而是这个崩溃的根因修复。
+  const dr = code(DR);
+  assert.doesNotMatch(dr, /fs\.watch/,
+    'dev-reload.js 不应再监听文件系统 —— 自动重载是崩溃根因');
+  assert.doesNotMatch(dr, /setInterval|setTimeout\([^)]*reload/i,
+    '不应有任何定时器驱动的重载');
+
+  // index.js 里也不能再启动 watcher
+  assert.doesNotMatch(code(IDX), /watchPackage\(/,
+    'index.js 不应再调用 watchPackage');
+
+  // 唯一入口必须是显式路由
+  assert.match(IDX, /head === 'reload'/,
+    '重载只能经 POST /reload 触发');
+  assert.match(IDX, /toUpperCase\(\) !== 'POST'/,
+    '该路由必须只接受 POST（不可逆操作）');
 });
 
 // ── X6: 成功返回值要带 busted / verified ────────────────────────────────
@@ -137,22 +151,19 @@ test('X6: selfReload 成功时返回 busted 与 verified', () => {
 });
 
 // ── X7: watcher 必须可观测（区分"没触发"与"触发了但失败"）──────────────
-test('X7: watcher 的注册与事件都写进 notify.log', () => {
-  // 2026-10-18 我因为看错时间基准（把重启前的日志当成重启后），
-  // 误判热重载"还是坏的"。真正的教训是：
-  // **没有可观测信号时，只能靠猜。**
-  //
-  // 现在 watcher 起来会写 `[watch] watching <目录>`，
-  // 收到事件会写 `[watch] event <文件> accepted=<bool>`。
-  // 这样"没触发"和"触发了但失败"一眼可分。
-  assert.match(DR, /opts\.diag\?\.\('watching '/,
-    '应能观测到 watcher 注册成功');
-  assert.match(DR, /opts\.diag\?\.\('event '/,
-    '应能观测到收到文件事件（含是否被源码过滤接受）');
-
-  // diag 必须接到真正的日志文件，而不是只进 console
-  assert.match(IDX, /diag:\s*\([^)]*\)\s*=>\s*appendNotifyLog/,
-    'diag 必须写进 notify.log —— 只进 console 的话我们看不到');
-  assert.match(IDX, /\[watch\]/,
-    '日志前缀应是 [watch]');
-});
+test('X7: 每次重载尝试的结果都写进 notify.log', () => {
+  // 原本这里断言 watcher 的 `[watch] watching/event` 可观测信号。
+  // watcher 删除后，需要同样的可观测性 —— 改到**重载结果**上：
+  // 成功与失败都必须落进日志文件，否则"点了没反应"无法排查。
+  assert.match(IDX, /\[reload\] OK by-user/,
+    '成功要写日志（带 by-user 标记，与旧的自动重载区分）');
+  assert.match(IDX, /\[reload\] FAILED/,
+    '失败也要写日志，并留下原因');
+
+  // 必须落文件，不能只进 console
+  const okAt = IDX.indexOf('[reload] OK by-user');
+  assert.ok(okAt > 0, '应能定位成功日志');
+  const seg = IDX.slice(Math.max(0, okAt - 400), okAt + 80);
+  assert.match(seg, /appendNotifyLog/,
+    '日志必须走 appendNotifyLog（写文件），只进 console 我们看不到');
+});

package/test/ui-final.test.mjs

@@ -0,0 +1,220 @@
+/**
+ * 定稿前的收尾行为测试（v0.4.56）。
+ *
+ * 这两条来自用户评审：
+ *   ① 静音时音频设置应收起，但**不能禁用试听**
+ *   ② 「条款链接待补」不能虚报
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CLIENT = readFileSync(join(ROOT, 'lib', 'client.js'), 'utf8');
+
+function fakeReact() {
+  const createElement = (type, props, ...children) => ({
+    $$typeof: Symbol.for('react.element'),
+    type,
+    props: { ...(props || {}), children },
+  });
+  const hooks = { slots: [], index: 0, eff: 0, ranEff: new Set(), rerender: null };
+  const useState = (init) => {
+    const i = hooks.index++;
+    if (hooks.slots[i] === undefined) {
+      hooks.slots[i] = { value: typeof init === 'function' ? init() : init };
+    }
+    const slot = hooks.slots[i];
+    const set = (updater) => {
+      slot.value = typeof updater === 'function' ? updater(slot.value) : updater;
+      if (typeof hooks.rerender === 'function') hooks.rerender();
+    };
+    return [slot.value, set];
+  };
+  // 只跑一次（模拟 [] 依赖）；不调 cleanup（否则 alive=false，配置永远不合并）
+  const useEffect = (fn) => {
+    const i = hooks.eff++;
+    if (hooks.ranEff.has(i)) return;
+    hooks.ranEff.add(i);
+    try { fn(); } catch { /* ignore */ }
+  };
+  const resetIndex = () => { hooks.index = 0; hooks.eff = 0; };
+  return { createElement, useState, useEffect, __hooks: hooks, __resetIndex: resetIndex };
+}
+
+const FULL = {
+  voice: true, voiceMode: 'fixed', voiceName: 'zundamon-normal', volume: 80,
+  notifyOnComplete: true, notifyOnError: true, notifyOnBlocked: true,
+  notifyOnAborted: false, notifyOnApproval: true, notifyOnQuestion: true,
+  subagents: false, idleGate: true,
+  audioSource: 'tts', showToast: true, ttsVoice: '', ttsRate: 0, devReload: false,
+  logLevel: 'info', voiceGain: 2.0, normalizeCustomAudio: false,
+  jumpWhenBackground: true, jumpWhenForeground: false,
+  debounceSeconds: 60, globalCooldownSeconds: 0,
+  audioSourceByKind: {}, ttsTexts: {}, kindSystemSound: {}, kindVoiceName: {},
+  customFiles: {},
+};
+
+function texts(node, out) {
+  const acc = out || [];
+  if (node === null || node === undefined || node === false) return acc;
+  if (typeof node === 'string' || typeof node === 'number') { acc.push(String(node)); return acc; }
+  if (Array.isArray(node)) { node.forEach((n) => texts(n, acc)); return acc; }
+  texts(node.props && node.props.children, acc);
+  return acc;
+}
+
+function elements(node, out) {
+  const acc = out || [];
+  if (!node || typeof node !== 'object') return acc;
+  if (Array.isArray(node)) { node.forEach((n) => elements(n, acc)); return acc; }
+  if (node.type) acc.push(node);
+  elements(node.props && node.props.children, acc);
+  return acc;
+}
+
+/** 按形状找主 state 槽（组件有多个 useState，不能写死索引）。 */
+function findMainSlot(card) {
+  const s = card.r.__hooks.slots.find(
+    (x) => x && x.value && typeof x.value === 'object'
+      && 'values' in x.value && 'loaded' in x.value,
+  );
+  if (!s) throw new Error('找不到主 state 槽');
+  return s;
+}
+
+/** 按形状找「声音设置展开状态」槽（{ open: ... }）。 */
+function findSoundSlot(card) {
+  const s = card.r.__hooks.slots.find(
+    (x) => x && x.value && typeof x.value === 'object'
+      && 'open' in x.value && Object.keys(x.value).length === 1,
+  );
+  if (!s) throw new Error('找不到声音区 state 槽');
+  return s;
+}
+
+async function loadCard() {
+  let captured = null;
+  new Function('window', 'document', CLIENT)(
+    { __ModuleLoader__: { load(def) { captured = def; } }, addEventListener() {}, removeEventListener() {} },
+    undefined,
+  );
+  if (!captured) throw new Error('client.js 没有注册');
+
+  const r = fakeReact();
+  const mod = captured.factory((id) => {
+    if (id === 'react') return r;
+    throw new Error('client 不应 require: ' + id);
+  });
+
+  let component = null;
+  mod.apply({
+    get(id) {
+      if (id === 'slots') return { inject(_n, fn) { fn(); }, register(_m, c) { component = c; } };
+      return undefined;
+    },
+  });
+  if (!component) throw new Error('没有注册设置卡');
+
+  globalThis.fetch = (url) => Promise.resolve({
+    ok: true, status: 200,
+    json: () => Promise.resolve(
+      String(url).includes('version')
+        ? {
+          ok: true, running: '0.4.56', installed: '0.4.56', latest: '0.4.56',
+          hasUpdate: false, needsRestart: false, npmLatest: '0.4.56',
+          githubLatest: '0.4.56', installMode: 'managed', changelogUrl: 'x',
+        }
+        : { ok: true, values: FULL, packs: [] },
+    ),
+  });
+
+  const render = () => { r.__resetIndex(); return component({}); };
+  render();
+  r.__hooks.rerender = render;
+  for (let i = 0; i < 8; i++) await Promise.resolve();
+  return { r, render };
+}
+
+const has = (text, s) => text.includes(s);
+
+/** 设 state 后渲染。 */
+function renderWith(card, main, sound) {
+  findMainSlot(card).value = { ...findMainSlot(card).value, ...main };
+  if (sound !== undefined) findSoundSlot(card).value = { open: sound };
+  const tree = card.render();
+  return { text: texts(tree).join(' '), els: elements(tree) };
+}
+
+// ── N6: 静音时收起声音设置，但不禁用试听 ────────────────────────────────
+test('N6: 声音提醒关闭时收起音频设置，试听仍可用', async () => {
+  const card = await loadCard();
+
+  // 声音开着 → 正常展开；手动把 open 置 null（跟随默认）
+  {
+    const { text } = renderWith(card,
+      { values: { ...FULL, audioSource: 'tts', voice: true } }, null);
+    assert.ok(has(text, '朗读声音'), '声音开着时应正常显示音频控件');
+    assert.ok(!has(text, '声音提醒已关闭'), '声音开着时不该出现收起提示');
+  }
+
+  // 声音关掉 → 收起，但说明"配置还在"
+  {
+    const { text } = renderWith(card,
+      { values: { ...FULL, audioSource: 'tts', voice: false } }, null);
+    assert.ok(has(text, '声音提醒已关闭，原有配置已保留'),
+      '静音时应说明「配置还在」，否则用户以为被清掉了');
+    assert.ok(!has(text, '朗读声音'), '静音时应收起音频控件');
+  }
+
+  // 用户手动展开 → 控件回来，且试听**没有**被禁用
+  {
+    const { text, els } = renderWith(card,
+      { values: { ...FULL, audioSource: 'tts', voice: false } }, true);
+    assert.ok(has(text, '朗读声音'), '手动展开后应能看到音频控件');
+
+    const pvButtons = els.filter((e) => {
+      if (e.type !== 'button') return false;
+      const kids = e.props.children || [];
+      return ['完成', '失败', '提问', '批准', '拦截'].includes(kids[0]);
+    });
+    assert.ok(pvButtons.length >= 5, `五个试听按钮都应存在（实际 ${pvButtons.length}）`);
+    assert.ok(pvButtons.every((b) => !b.props.disabled),
+      '静音**不得禁用试听** —— 试听是测试配置的行为，与通知开关无关');
+  }
+});
+
+// ── N7: 条款占位不虚报 ──────────────────────────────────────────────────
+test('N7: 条款占位只在「能下载却没条款」时出现', () => {
+  // 用户评审时看到「条款链接待补」，要求核实是不是发布缺字段。
+  //
+  // 核实结论：真实 packs.json 的 13 个音色都有 terms，服务端也转成 termsUrl
+  // （R7 用真实请求钉住）。但**离线**时索引取不到，已安装的包没有 termsUrl ——
+  // 原来会显示占位，看起来像发布缺字段。
+  //
+  // 现在判据收窄为「能下载 && 没条款」。
+  assert.match(
+    CLIENT,
+    /\(p\.downloadable && !p\.termsUrl\)/,
+    '占位提示必须同时要求 downloadable —— 否则离线时会虚报',
+  );
+  // 反面断言：不能退回「没有 termsUrl 就报」
+  assert.doesNotMatch(
+    CLIENT,
+    /\+ \(p\.termsUrl \? '' : '　（条款链接待补）'\)/,
+    '不应退回旧的「没 termsUrl 就提示」判据',
+  );
+});
+
+// ── N8: 高级区不再有重复标题 ────────────────────────────────────────────
+test('N8: 高级区四个子组没有重复的内部标题', async () => {
+  const card = await loadCard();
+  const { text } = renderWith(card, { advOpen: true }, undefined);
+  // 子组标题「按事件定制声音」只应出现一次（内部不再重复「按事件覆盖声音来源」）
+  const occurrences = text.split('按事件定制声音').length - 1;
+  assert.equal(occurrences, 1, `「按事件定制声音」应只出现一次（实际 ${occurrences}）`);
+  assert.doesNotMatch(CLIENT, /'按事件覆盖声音来源'/,
+    '内部标题应已删除 —— 与二级分组标题重复');
+});

package/test/voice-pack-route.test.mjs

@@ -182,3 +182,49 @@ test('R7: 安装索引里没有的音色返回 404', async () => {
       `应是 404 或 502，实际 ${res.statusCode}`);
   });
 });
+
+// ── R8: 索引里的 terms → termsUrl（前端读的是这个字段名）─────────────────
+test('R8: 路由把 packs.json 的 terms 映射成前端要的 termsUrl', async () => {
+  // ⚠️ 用户评审时看到界面显示「条款链接待补」，要求核实是不是发布缺字段。
+  //
+  // 核实结论：真实 packs.json 的 13 个音色**都有** terms，
+  // 但字段名是 `terms`，而前端读的是 `termsUrl` ——
+  // 转名这一步在 voice-pack-route.js 里（`termsUrl: p.terms`）。
+  //
+  // 这步一旦被删，界面会对**所有**音色显示「条款链接待补」。
+  // 用真实请求 + 打桩 fetch 把这条跨文件契约钉住。
+  await withDataDir(async () => {
+    const realFetch = globalThis.fetch;
+    const FAKE_TERMS = 'https://example.invalid/voice-terms';
+    globalThis.fetch = async () => ({
+      ok: true,
+      status: 200,
+      headers: { get: () => null },
+      json: async () => ({
+        packs: [{
+          key: 'zundamon-normal',
+          name: 'ずんだもん（ノーマル）',
+          file: 'zundamon-normal.zip',
+          bytes: 100,
+          sha256: 'a'.repeat(64),
+          wavs: 1,
+          credit: 'VOICEVOX:ずんだもん',
+          terms: FAKE_TERMS,
+        }],
+      }),
+    });
+    try {
+      const route = createVoicePackRoute({ pluginRoot: '.', logger: { info() {}, warn() {} } });
+      const res = await call(route, 'GET', 'index');
+      assert.equal(res.statusCode, 200);
+      const doc = res.json();
+      assert.equal(doc.indexOk, true, '索引应可用（fetch 已打桩）');
+      const p = (doc.packs || []).find((x) => x.key === 'zundamon-normal');
+      assert.ok(p, '应返回该音色');
+      assert.equal(p.termsUrl, FAKE_TERMS,
+        'packs.json 里叫 terms，前端读的是 termsUrl —— 名字不对会让界面显示「条款链接待补」');
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+});