dsh-notify-say 0.4.56 → 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
 ```
 
-**418 条测试通过。** 绝大多数是纯逻辑测试，克隆仓库后 `npm test` 即可跑。
+**426 条测试通过。** 绝大多数是纯逻辑测试，克隆仓库后 `npm test` 即可跑。
 
 少数用例需要真实的 DSH 宿主（用于验证 Cordis 上下文行为）。
 找不到宿主时它们会**自动 skip** —— 注意 skip 不等于通过。

package/lib/client.js

@@ -610,6 +610,12 @@ window.__ModuleLoader__.load({
       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: {
@@ -965,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 }
@@ -2276,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.56",
+    "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 我们看不到');
+});