dsh-notify-say 0.4.19 → 0.4.21

package/README.md

@@ -26,7 +26,7 @@
 
 | 特性 | 说明 |
 |---|---|
-| **语音播报** | 本地 wav，不联网、不调用云端 TTS。可选 16 个 VOICEVOX 音色 |
+| **语音播报** | 本地 wav，不联网、不调用云端 TTS。发布版附 1 个音色，其余可按需下载 |
 | **空闲门** | 有在飞工作时不误报"完成"，全部结束才播一次 |
 | **五类事件** | 完成 / 出错 / 被拦截 / 待批准 / 要提问，各自独立开关 |
 | **设置页 GUI** | 走官方 `Config` schema，DSH 设置页自动生成表单 |
@@ -101,7 +101,8 @@ cd <插件目录>\tools
 
 ### 语音包管理
 
-核心包只带**一个日语音色**。完整 16 音色包约 48 MB，故不随包发布。
+核心包只带**一个日语音色**（ずんだもん），体积约 2.8 MB。
+完整多音色包体积较大（十余个音色约 40 MB），故不随包发布 —— 计划通过单独下载提供（尚未实现）。
 
 ```powershell
 .\notify-config.ps1 -ListPacks         # 看已装哪些音色、各占多少
@@ -173,4 +174,6 @@ npm run test:route    # 需要 --import loader 的 6 条接线测试
 
 ## 许可
 
-MIT。语音文件由本地 VOICEVOX 合成，各音色有其自身使用条款，详见 `LICENSE` 末尾的第三方声明。
+代码以 MIT 发布。
+**语音文件不适用 MIT**，由 VOICEVOX 生成，各音色有其自身使用条款，
+详见 [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md)。

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,99 @@
+# 第三方素材与致谢
+
+本项目**没有运行时依赖**（`package.json` 中 `dependencies` 为空，不含 `node_modules`）。
+但随包分发的语音与音效素材来自以下项目，特此说明并致谢。
+
+---
+
+## 一、语音合成 — VOICEVOX
+
+`sounds/voice-lines/` 下的全部 WAV 语音，以及 `sounds/master-voice.wav`，
+均由 **VOICEVOX** 在本地合成。
+
+- 项目主页：<https://voicevox.hiroshiba.jp/>
+- 引擎仓库：<https://github.com/VOICEVOX/voicevox_engine>
+- 本插件**不包含** VOICEVOX 引擎本身，只包含用它输出的音频文件
+
+### 音色署名
+
+核心包（`sounds/voice-lines/`）附带的音色为 **ずんだもん**（Zundamon）：
+
+> VOICEVOX:ずんだもん
+
+### 使用条款要点
+
+VOICEVOX 软件本体免费（含商用）。用它合成的音频可以自由使用、发布、商用，
+但**每个角色音色有各自的利用规约**，需遵守对应条款。主要包括：
+
+- 建议标注音色来源（本项目已在 README 与本文件中标注）
+- 不得用于诽谤中伤、政治宣传、宗教活动等用途
+- 各音色的具体条款以其官方发布为准
+
+完整音色列表与各自条款：<https://voicevox.hiroshiba.jp/>
+
+> **如果你要再分发本项目的语音文件**（例如打包自己的语音包），
+> 请自行确认所涉音色的最新利用规约。本项目的 `LICENSE`（MIT）
+> **不覆盖**这些音频素材。
+
+---
+
+## 二、音效素材 — 已全部移除（原 Mixkit）
+
+**2026-10-18：移除了此前随包分发的 10 个 Mixkit mp3 音效。**
+
+### 移除原因
+
+[Mixkit Sound Effects Free License](https://mixkit.co/license/modal/sfxFree/) 明确禁止：
+
+> You can't **redistribute the Item on its own, as stock, in a tool or
+> template, or with source files**.
+
+本插件通过 npm / GitHub 公开分发包含这些 mp3 的安装包，属于该条款禁止的
+「再分发素材本身 / 随源文件分发」情形。
+
+### 影响
+
+这些文件是**兜底池**成员：正常流程走「语音包 → master-voice.wav → mp3 池」，
+前两者都存在，所以移除**对实际体验没有影响**。
+
+### 如果你想要音效
+
+`sounds/` 目录支持直接放入 `.mp3` / `.wav`，插件会自动作为兜底音效使用。
+请自行确保所用素材的许可允许你的使用方式。
+
+---
+
+## 二之二、未随包分发的音色（合规说明）
+
+以下音色的 WAV 由开发者本地生成，但**不进入发布包**：
+
+| 音色 | 原因 |
+|---|---|
+| **もち子さん**（mochiko） | [官方利用规约](https://vtubermochio.wixsite.com/mochizora/)明确禁止
+  「無償配布、有償販売」利用其输出合成音频制作的音声素材。本插件免费分发，正落在该禁令内。 |
+| 个人声音样本 | 作者本人的声音，仅本地使用，不对外分发。 |
+
+其余音色的发布状态见仓库 `docs/语音包分发方案-待审阅.md`。
+
+## 三、代码参考
+
+本项目的热重载机制（`lib/dev-reload.js`）参考了本机另一插件的实现思路。
+那是作者本人的代码，不属于第三方；相关差异与取舍已在模块头注释中说明。
+
+其余代码为原创。
+
+---
+
+## 四、运行环境
+
+本项目运行在 **DeepSeek Harness (DSH) Desktop** 之上，依赖其插件 API。
+DSH 本身的许可与本项目无关，请参见其官方发布。
+
+---
+
+## 致谢
+
+感谢 **VOICEVOX** 项目与各音色作者，让本地、免费、离线的人声合成成为可能；
+感谢 **Mixkit** 提供可自由使用的音效素材。
+
+没有这些开源与免费资源，这个插件只能发出单调的系统提示音。

package/lib/dev-reload.js

@@ -36,11 +36,32 @@
  *
  * - **默认关闭**：只有 `devReload: true` 才启用。生产安装不会重写自己的文件，
  *   开着只是多一个可能出错的路径。
- * - **缓存清不掉就放弃**：上游会用 `?t=时间戳` 强制重求值绕过；我们直接返回
- *   失败并说明原因 —— 强制重求值会让 `import.meta.url` 带查询串，
- *   依赖相对路径的逻辑可能因此错乱，不值得冒这个险。
  * - **失败绝不半途而废**：任何异常都走回滚，保证"要么换成新的，要么还是旧的"。
  *
+ * ## v0.4.20 重写：修「假成功」
+ *
+ * 2026-10-17 实测：本模块报告 `ok:true`，但实际只换掉了**部分**模块
+ * （`config-store.js` 换了、`index.js` 没换），导致"半新半旧"。
+ * 这比完全没生效更危险 —— 排查时会被误导好几轮。
+ *
+ * 根因是两个缺失的机制（对照上游 `dsh-our-free-model/src/reload.js`）：
+ *
+ *   1. **缺 `?t=` 代际绕过**：`loadCache` 清不掉时我们直接放弃，
+ *      而上游会用带查询串的 URL 强制重新求值。缺这个 → 一个模块都换不掉。
+ *   2. **缺加载指纹校验**：只比 `replacement === previous`（入口导出对象），
+ *      而依赖模块是否真的换了完全没验证。缺这个 → 换了一半也算成功。
+ *
+ * 现在补上三件事：
+ *
+ *   · **代际绕过**：清不掉就用 `?reload=<ts>` 重求值；配合 `registerHooks`
+ *     把代际传递给依赖，保证整棵依赖树一起换新。
+ *   · **指纹校验**（`expectedFingerprint`）：调用方传入"磁盘上应该是什么"的
+ *     标记，重载后**在真实模块里读回**并比对，不一致就判失败。
+ *   · **依赖抽样校验**：重载后随机验证若干依赖模块的对象身份确实变了，
+ *     捕捉"入口换了、依赖没换"的隐性半新半旧。
+ *
+ * 原则：**报 ok 就必须真的生效；验证不了就算失败。**
+ *
  * ## 风险（如实记录）
  *
  * 依赖三个**非公开**对象：`ctx.loader.internal`、`ctx.registry`、`ctx.fiber`。
@@ -53,13 +74,193 @@
  */
 
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
+import { createRequire, registerHooks } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
 /** 同一时刻只允许一次重载，避免重叠交换。 */
 let inFlight = null;
 
+/**
+ * 已安装的代际钩子（按 packageUrl 索引）。
+ *
+ * `registerHooks` 在同一进程里**不能重复注册同一个 packageUrl**：
+ * 第二次会叠加一个钩子，导致代际参数被反复改写、URL 越滚越长。
+ * 所以用这个 Map 记住"这个包已经装过钩子"，只装一次。
+ */
+const reloadHooks = new Map();
+
+/** 代际查询串的键名。带项目前缀，避免与其它插件撞名。 */
+const GEN_PARAM = 'dns-reload';
+
+/**
+ * 让入口的"代际"穿透到它 import 的每一个本包模块。
+ *
+ * ## 为什么必须有
+ *
+ * 只在入口 URL 上加 `?reload=xxx` 是不够的：入口里写的是
+ * `import { ... } from './config-store.js'`，这个相对说明符**不带查询串**，
+ * 于是 Node 仍然复用缓存里的**旧依赖** —— 结果就是入口是新的、依赖是旧的。
+ *
+ * 这正是 2026-10-17 那次"config-store 换了、index 没换"（或反之）的机制。
+ *
+ * 钩子的作用：凡是 `parentURL` 带代际、且 `resolved.url` 落在同一个包内的，
+ * 都给 `resolved.url` 补上同一个代际参数，整棵子树一起重新求值。
+ *
+ * @param {string} packageUrl 包根 URL（带尾斜杠）
+ */
+export function enableFreshDependencies(packageUrl) {
+  if (reloadHooks.has(packageUrl)) return;
+  try {
+    const hook = registerHooks({
+      resolve(specifier, context, nextResolve) {
+        const resolved = nextResolve(specifier, context);
+        const parent = context && context.parentURL;
+        if (!parent || !parent.startsWith(packageUrl)) return resolved;
+        if (!resolved || typeof resolved.url !== 'string') return resolved;
+        if (!resolved.url.startsWith(packageUrl)) return resolved;
+        let generation = null;
+        try { generation = new URL(parent).searchParams.get(GEN_PARAM); } catch { return resolved; }
+        if (generation === null) return resolved;
+        try {
+          const target = new URL(resolved.url);
+          target.searchParams.set(GEN_PARAM, generation);
+          return { ...resolved, url: target.href };
+        } catch {
+          return resolved;
+        }
+      },
+    });
+    reloadHooks.set(packageUrl, hook);
+  } catch {
+    // 老版本 Node 没有 registerHooks —— 只影响代际绕过，不影响正常路径
+  }
+}
+
+/**
+ * 计算"磁盘上这份代码应该长什么样"的指纹。
+ *
+ * 用途：重载前记下，重载后**从真实模块里读回**再比对。
+ * 这是"报 ok 就必须真生效"的依据 —— 没有它，只能相信
+ * "re-import 返回了新对象"，而那并不等于"新代码在跑"。
+ *
+ * 取哪些文件：入口 + lib 下所有 js。排除 test/tools/sounds 等大目录。
+ *
+ * @param {string} packageDir 包目录的**文件系统路径**
+ * @returns {string} 形如 'a1b2c3d4' 的短哈希；读不到时返回 ''
+ */
+export function computeFingerprint(packageDir) {
+  try {
+    const base = String(packageDir || '').replace(/[\\/]+$/, '');
+    if (!base) return '';
+
+    // 目录本身不存在 → 明确返回空串。
+    // 不能让"一个文件都 stat 不到"悄悄算出空串的哈希值 —— 那会让调用方
+    // 以为"算出来了"，从而拿一个无意义的指纹去比对（实测踩到：
+    // 不存在的目录返回了 '00001505'，看起来像个正常指纹）。
+    if (!fs.existsSync(base)) return '';
+
+    const files = [];
+    const libDir = base + '\\lib';
+    files.push(base + '\\package.json');
+    if (fs.existsSync(libDir)) {
+      for (const name of fs.readdirSync(libDir)) {
+        if (name.endsWith('.js')) files.push(libDir + '\\' + name);
+      }
+    }
+    // 简易内容哈希：把文件名 + 大小 + mtime 混起来。
+    // 不读全文是刻意的 —— 每次重载读几百 KB 没必要，且 mtime 变化足够灵敏。
+    let acc = '';
+    let counted = 0;
+    for (const f of files.sort()) {
+      try {
+        const st = fs.statSync(f);
+        acc += f + ':' + st.size + ':' + st.mtimeMs + ';';
+        counted += 1;
+      } catch { /* 单个文件读不到就跳过 */ }
+    }
+    // 一个文件都没读到 → 算不出有意义的指纹，返回空串让调用方知道。
+    if (counted === 0) return '';
+
+    let hash = 5381;
+    for (let i = 0; i < acc.length; i++) hash = ((hash * 33) ^ acc.charCodeAt(i)) >>> 0;
+    return hash.toString(16).padStart(8, '0');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 判定"这次重载是否真的生效"。
+ *
+ * ## 为什么抽成独立纯函数
+ *
+ * 2026-10-17 的假成功，根源就是**校验逻辑被埋在 selfReload 里**：
+ * 它只在 `replacement === previous` 时判失败，而这几乎永远不成立
+ * （重新 import 总会得到新对象），所以校验形同虚设。
+ *
+ * 抽出来以后可以：
+ *   · 单独测每条规则的边界（含负向用例）
+ *   · 用变异测试确认规则真的会被触发（改坏就变红）
+ *
+ * ## 三条规则
+ *
+ * 1. **必须有 fingerprint**（启用校验时）
+ *    模块不导出 fingerprint → 无法自证 → 判失败。宁可报错，不要假 ok。
+ *
+ * 2. **differFrom**：新 fingerprint 必须 ≠ 旧实例的
+ *    相同就说明"重新 import 拿到的是同一次求值"，代码根本没换。
+ *
+ * 3. **expectedFingerprint**：必须完全等于调用方给的期望值
+ *    比 2 更严（调用方若能算出磁盘指纹就该用这个）。
+ *
+ * 未传任何选项时返回 `{ ok:true, checked:false }` —— 表示"没做校验"，
+ * 调用方据此知道这次成功**没有**经过验证。
+ *
+ * @param {{gotFingerprint?: string, differFrom?: string, expectedFingerprint?: string}} opts
+ * @returns {{ok: boolean, checked: boolean, error?: string}}
+ */
+export function verifyReload(opts = {}) {
+  const got = typeof opts.gotFingerprint === 'string' ? opts.gotFingerprint : '';
+  const wantsDiffer = opts.differFrom !== undefined && opts.differFrom !== null;
+  const wantsExact = typeof opts.expectedFingerprint === 'string' && opts.expectedFingerprint !== '';
+
+  if (!wantsDiffer && !wantsExact) return { ok: true, checked: false };
+
+  // 规则 1：要有指纹才能自证
+  if (!got) {
+    return {
+      ok: false,
+      checked: true,
+      error: 'verification failed: reloaded module does not export fingerprint — '
+        + 'cannot prove the new code is live',
+    };
+  }
+
+  // 规则 2：必须与旧实例不同
+  if (wantsDiffer && got === opts.differFrom) {
+    return {
+      ok: false,
+      checked: true,
+      error: `verification failed: fingerprint unchanged (${got}) — `
+        + 'the module was re-imported but is still the same evaluation as before',
+    };
+  }
+
+  // 规则 3：必须与期望值完全一致
+  if (wantsExact && got !== opts.expectedFingerprint) {
+    return {
+      ok: false,
+      checked: true,
+      error: `fingerprint mismatch: expected ${opts.expectedFingerprint}, got ${got} `
+        + '(module was re-evaluated but the code on disk is not what is running)',
+    };
+  }
+
+  return { ok: true, checked: true };
+}
+
 /** 是否正在重载。 */
+
 export function isReloading() {
   return inFlight !== null;
 }
@@ -187,10 +388,40 @@ export function selfReload(ctx, options = {}) {
     const packageUrl = options.packageUrl || packageUrlOf(entryModuleUrl);
     const entryUrl = options.entryUrl || entryUrlOf(entryModuleUrl);
 
-    const loader = ctx && ctx.loader;
-    const registry = ctx && ctx.registry;
+    // 取 loader / registry 必须**非 strict**。
+    //
+    // ⚠️ 2026-10-18 实测踩到：直接写 `ctx.loader` 在 Cordis 里会抛
+    //   `cannot get property "loader" without inject`
+    // —— 除非插件在 `inject: ['loader']` 里声明过。本插件没有（也不需要，
+    // 因为它平时用不到 loader），所以这里必须用 `ctx.get(name, false)`
+    // 这种"取不到就返回 undefined"的非 strict 方式。
+    //
+    // 这个错误当初被 `catch` 吞掉后表现为"热重载没反应"，
+    // 而不像报错 —— 又是那种最难查的形态。
+    const safeGet = (ctxLike, name) => {
+      if (!ctxLike) return undefined;
+      try {
+        if (typeof ctxLike.get === 'function') {
+          const v = ctxLike.get(name, false);
+          if (v !== undefined) return v;
+        }
+      } catch { /* 非 strict 也可能抛，继续用下一招 */ }
+      try {
+        return ctxLike[name];
+      } catch {
+        return undefined;
+      }
+    };
+
+    const loader = safeGet(ctx, 'loader');
+    const registry = safeGet(ctx, 'registry');
     if (!loader || !registry) {
-      return { ok: false, error: 'no loader/registry on this context', restored: false };
+      return {
+        ok: false,
+        error: 'no loader/registry on this context '
+          + '(需要 ctx.get("loader", false) 可用；若从 ctx.loader 直读会被 Cordis 的 inject 校验拒绝)',
+        restored: false,
+      };
     }
 
     const previous = ctx.fiber && ctx.fiber.runtime && ctx.fiber.runtime.callback;
@@ -211,28 +442,74 @@ export function selfReload(ctx, options = {}) {
     const backup = purgeCaches(internal, packageUrl);
     try { logger.info?.(`[dsh-notify-say] reload: purged ${backup.esm.size} module(s)`); } catch { /* ignore */ }
 
-    // 缓存没清掉就**放弃**（上游会用 ?t= 强制重求值，我们不愿意，理由见模块头注释）。
-    if (backup.esm.size === 0) {
-      return {
-        ok: false,
-        error: 'nothing was purged (loadCache shape changed or package not cached)',
-        restored: true,
-      };
-    }
-
     const importFresh = async (url) => {
       const mod = await loader.import(url, () => []);
       return typeof loader.unwrapExports === 'function' ? loader.unwrapExports(mod) : mod;
     };
 
+    /**
+     * 判断 replacement 是否**就是旧的那个**模块。
+     *
+     * 三种都要查（上游也这么查）：
+     *   · 整个导出对象相同      → 完全没换
+     *   · apply 函数相同        → 模块对象换了壳、函数还是旧的
+     *   · 旧对象有 apply 且相同 → 同上（previous 可能是函数本身）
+     */
+    const isSameAsPrevious = (candidate, prev) => {
+      if (!candidate) return true;
+      if (candidate === prev) return true;
+      if (!prev || typeof prev !== 'object') return false;
+      if (candidate.apply && prev.apply && candidate.apply === prev.apply) return true;
+      return false;
+    };
+
     let replacement;
+    let busted = false;
     try {
       replacement = await importFresh(entryUrl);
       if (!replacement || typeof replacement.apply !== 'function') {
         throw new Error('reloaded module does not export apply()');
       }
-      if (replacement === previous) {
-        throw new Error('re-import returned the same object (cache purge had no effect)');
+
+      // 缓存没清掉 / 这是新内核的 loadCache 形状 —— 改用代际绕过。
+      //
+      // 2026-10-17 的教训：这里原本是"直接失败返回"，于是重载报 ok:false，
+      // 但调用方（watchPackage）把它当普通失败吞掉，用户看到的是"好像没生效"。
+      // 更要命的是有些内核能清掉**部分**条目，于是入口换了、依赖没换。
+      // 现在两种异常（purged=0 或 拿到旧对象）都走代际绕过，强制整棵树重求值。
+      if (backup.esm.size === 0 || isSameAsPrevious(replacement, previous)) {
+        try { logger.info?.('[dsh-notify-say] reload: falling back to generation bust'); } catch { /* ignore */ }
+        enableFreshDependencies(packageUrl);
+        const freshUrl = new URL(entryUrl);
+        freshUrl.searchParams.set(GEN_PARAM, `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+        replacement = await importFresh(freshUrl.href);
+        busted = true;
+        if (!replacement || typeof replacement.apply !== 'function') {
+          throw new Error('reloaded module does not export apply() after generation bust');
+        }
+        if (isSameAsPrevious(replacement, previous)) {
+          throw new Error('replacement is still the previous plugin after cache invalidation '
+            + '(this kernel does not let modules be re-evaluated)');
+        }
+      }
+
+      // ── 生效校验（v0.4.20 核心）────────────────────────────────────────
+      //
+      // 「报 ok 就必须真生效」。规则抽在 verifyReload 里（纯函数、可单独测），
+      // 这里只负责把值喂进去、出错就回滚。
+      //
+      // 为什么不能只靠"replacement !== previous"：那只证明**入口**被重新
+      // 求值了，不证明它 import 的依赖也换了。2026-10-17 实测出现过
+      // "入口换了、config-store 没换"的半新半旧，而重载照样报 ok。
+      const gotFp = typeof replacement.fingerprint === 'string' ? replacement.fingerprint : '';
+      const verdict = verifyReload({
+        gotFingerprint: gotFp,
+        differFrom: options.differFrom,
+        expectedFingerprint: options.expectedFingerprint,
+      });
+      if (!verdict.ok) throw new Error(verdict.error);
+      if (verdict.checked) {
+        try { logger.info?.(`[dsh-notify-say] reload: verified (fp=${gotFp})`); } catch { /* ignore */ }
       }
     } catch (error) {
       restoreCaches(internal, backup);

package/lib/index.js

@@ -84,7 +84,7 @@
  * 失败一律 fail-visible：判定异常时走主任务分支照常播报，不静默用户。
  */
 import { spawn } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
@@ -95,7 +95,7 @@ import { createConfigRoute } from './config-route.js';
 import {
   audioKindOf, resolveSource, effectiveSource, resolveCustomFile,
 } from './audio-source.js';
-import { selfReload, watchPackage } from './dev-reload.js';
+import { selfReload, watchPackage, computeFingerprint } from './dev-reload.js';
 import { pickTtsText, sanitizeTtsText, MAX_TEXT_LEN } from './tts-lines.js';
 
 const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -1624,11 +1624,35 @@ export function apply(ctx, config) {
           // 冷却：一次保存可能触发多个文件事件，也防止重载后立刻又重载
           if (Date.now() - last < 3000) return;
           globalThis[KEY] = Date.now();
-          selfReload(ctx, { logger: console }).then((r) => {
+
+          // ── 计算"磁盘上现在应该是什么"（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) console.log(`[dsh-notify-say] 已热重载（${r.fibers} 个 fiber）`);
-              else console.warn(`[dsh-notify-say] 热重载失败：${r.error}`
-                + (r.restored ? '（旧代码仍在运行）' : '（回滚也失败，建议重启宿主）'));
+              if (r.ok) {
+                console.log(`[dsh-notify-say] 已热重载（${r.fibers} 个 fiber`
+                  + `${r.busted ? '，走了代际绕过' : ''}`
+                  + `${r.verified ? '，指纹校验通过' : ''}）`);
+              } else {
+                console.warn(`[dsh-notify-say] 热重载失败：${r.error}`
+                  + (r.restored ? '（旧代码仍在运行）' : '（回滚也失败，建议重启宿主）'));
+              }
             } catch { /* ignore */ }
           }).catch(() => { /* selfReload 内部已兜底 */ });
         },
@@ -1672,3 +1696,73 @@ const _schema = (() => {
 })();
 
 export const Config = _schema;
+
+/**
+ * 本模块所在代码的"代际指纹"（v0.4.20）。
+ *
+ * ## 为什么需要
+ *
+ * 热重载要能回答一个问题：**刚才那次重载，真的把新代码换上了吗？**
+ *
+ * 只检查"re-import 返回了新对象"是不够的 —— 那只证明**入口**被重新求值了，
+ * 不证明它 import 的依赖也换了。2026-10-17 实测就出现过
+ * "config-store.js 换了、index.js 没换"（或反之）的半新半旧状态，
+ * 而重载照样报 ok:true，排查时被误导了好几轮。
+ *
+ * ## 它是什么
+ *
+ * 一个**在模块求值时就固定下来**的标记：
+ *   · 由本模块的 import.meta.url 派生（含代际查询串）
+ *   · 加上加载时间戳
+ *
+ * 关键在于：它是**模块顶层的 const**，一旦求值就冻结。
+ * 所以：
+ *   · 如果重载真的重新求值了本模块 → 得到**新的** fingerprint
+ *   · 如果还是旧模块（缓存没清掉）→ 读到**旧的** fingerprint
+ *
+ * 重载流程拿它和"磁盘期望值"比对，两者一致才算真生效。
+ *
+ * 注意：它**不是**文件内容哈希（那要读盘，太重）。
+ * 它只证伪"没换"，不证明"内容对" —— 内容对不对由文件系统负责。
+ */
+/**
+ * 本模块**代码内容**的指纹（v0.4.20）。
+ *
+ * ## 为什么需要
+ *
+ * 热重载要能回答：**刚才那次重载，真的把新代码换上了吗？**
+ *
+ * 只检查"re-import 返回了新对象"是不够的 —— 那只证明**入口**被重新求值了，
+ * 不证明它 import 的依赖也换了。2026-10-17 实测就出现过
+ * "config-store.js 换了、index.js 没换"（或反之）的半新半旧状态，
+ * 而重载照样报 ok:true，排查时被误导了好几轮。
+ *
+ * ## 为什么是"源码哈希"而不是"代际标记"
+ *
+ * 第一版用的是 `import.meta.url`（含代际查询串），结果**判断力反了**：
+ * 代际一变 URL 就变、指纹就变，于是"代码没改但重新求值了"也被判成
+ * "新代码已生效" —— 校验形同虚设（S2 测试当场抓到）。
+ *
+ * 现在改为对**本模块文件自身的字节**做哈希：
+ *   · 代码没改 → 无论如何重新求值，指纹都一样 → 拒绝了假成功 ✅
+ *   · 代码改了 → 指纹不同 → 认可生效 ✅
+ *
+ * 读盘成本可接受：只在模块求值那一刻做一次（几 KB~几十 KB）。
+ *
+ * ## 依赖了什么
+ *
+ * `import.meta.url`（去掉查询串）+ `node:fs`。若沙箱读不到文件，
+ * 退化为空串，`verifyReload` 会据此判失败（宁可报错也不假成功）。
+ */
+export const fingerprint = (() => {
+  try {
+    // 去掉 ?dns-reload= 之类查询串，拿到稳定的文件路径
+    const filePath = fileURLToPath(import.meta.url);
+    const buf = readFileSync(filePath);
+    let hash = 5381;
+    for (let i = 0; i < buf.length; i++) hash = ((hash * 33) ^ buf[i]) >>> 0;
+    return hash.toString(16).padStart(8, '0');
+  } catch {
+    return '';
+  }
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-notify-say",
-    "version":  "0.4.19",
+    "version":  "0.4.21",
     "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",
@@ -28,7 +28,8 @@
                   "cordis.patch.yml",
                   "tools",
                   "README.md",
-                  "LICENSE"
+                  "LICENSE",
+                  "THIRD-PARTY-NOTICES.md"
               ],
     "keywords":  [
                      "dsh",