dsh-notify-say 0.4.21 → 0.4.25

package/test/reload-live.test.mjs

@@ -0,0 +1,261 @@
+/**
+ * 热重载实机测试：在真实 Cordis 上下文里跑完整重载流程。
+ *
+ * ## 为什么这个测试不可替代
+ *
+ * R1~R10 验证了**零件**（指纹、代际穿透、校验规则），但没验证**整台机器
+ * 转起来**。2026-10-17 的假成功恰恰发生在 selfReload 的整体编排里 ——
+ * 零件都对，串起来报 ok 却没真换代码。
+ *
+ * ## 写这个测试时挖出的三个真问题（都已在源码里修）
+ *
+ * 1. **`ctx.loader` 直读会被 Cordis 拒绝**
+ *    报 `cannot get property "loader" without inject`。必须用
+ *    `ctx.get('loader', false)` 这种非 strict 取法。这个异常当初被 catch
+ *    吞掉，表现为"热重载没反应"，是最难查的形态。
+ *
+ * 2. **指纹判断力反了**
+ *    第一版用 `String(import.meta.url)` 做指纹 —— 代际一变 URL 就变、
+ *    指纹就变，于是"代码没改但重新求值了"也被判成"新代码生效"。
+ *    现在改为对**自身源码字节**做哈希：代码不变 → 指纹不变。
+ *    S2/S5 就是锁这条的。
+ *
+ * 3. **假 loader 必须模拟"缓存清掉就重新求值"**
+ *    否则 `import(url)` 命中 Node 的 ESM 缓存，文件改了也拿到旧模块，
+ *    表现为"指纹未变"的假失败。
+ *
+ * ## 不碰真实插件目录
+ *
+ * 全程在系统临时目录造包，不会触发宿主热重载、不打断任何会话。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+import { selfReload, computeFingerprint, verifyReload } from '../lib/dev-reload.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** 定位真实 Cordis（DSH 用 @deepseek-ai/cordis，不是 npm 的 cordis）。 */
+function loadRealCordis() {
+  const candidates = [
+    process.env.DSH_CORDIS_ENTRY || '',   // CI/其他机器可指定
+    'D:\\Program Files (x86)\\DSH\\.runtime\\node_modules\\@deepseek-ai\\cordis\\lib\\index.js',
+  ];
+  const req = createRequire(import.meta.url);
+  for (const p of candidates) {
+    // 显式设了 DSH_CORDIS_ENTRY 就只用它 —— 便于模拟"没有宿主"的 CI 环境
+    if (process.env.DSH_CORDIS_ENTRY) {
+      const only = process.env.DSH_CORDIS_ENTRY;
+      try { req.resolve(only); return pathToFileURL(only).href; } catch { return undefined; }
+    }
+    if (!p) continue;
+    try {
+      req.resolve(p);
+      return pathToFileURL(p).href;
+    } catch { /* 试下一个 */ }
+  }
+  return undefined;
+}
+
+const REAL_CORDIS = loadRealCordis();
+const skipLive = REAL_CORDIS === undefined;
+
+/**
+ * 造一个可写的最小插件包。
+ *
+ * fingerprint 用**自身源码哈希**，与 lib/index.js 同构 —— 这点很重要：
+ * 用 `String(import.meta.url)` 会让代际一变指纹就变，"代码没改也判成生效"。
+ */
+function writePlugin(dir, markerValue) {
+  mkdirSync(join(dir, 'lib'), { recursive: true });
+  writeFileSync(join(dir, 'package.json'),
+    JSON.stringify({ name: 'reload-probe-pkg', version: '1.0.0', type: 'module' }, null, 2));
+
+  const src = [
+    "import { readFileSync } from 'node:fs';",
+    "import { fileURLToPath } from 'node:url';",
+    '',
+    'export const fingerprint = (() => {',
+    '  try {',
+    '    const buf = readFileSync(fileURLToPath(import.meta.url));',
+    '    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 '';",
+    '  }',
+    '})();',
+    '',
+    'export const marker = ' + JSON.stringify(markerValue) + ';',
+    '',
+    'export function apply(ctx) {',
+    '  globalThis.__reloadProbeCtx = ctx;',
+    '}',
+    '',
+  ].join('\n');
+  writeFileSync(join(dir, 'lib', 'index.js'), src);
+}
+
+/**
+ * 提供一个假的 loader 服务。
+ *
+ * `internal.loadCache` 是 selfReload 真正依赖的东西：它在里面找本包的
+ * 模块条目并清掉。真宿主靠这个让 loader 重新求值；假 loader 模拟同样行为 ——
+ * 条目被清掉时给 URL 加唯一查询串强制重求值（等价于生产的 ?dns-reload=）。
+ */
+async function withLoaderService() {
+  const { Context, Service } = await import(REAL_CORDIS);
+  const root = new Context();
+
+  class FakeLoader extends Service {
+    constructor(ctx) {
+      super(ctx, 'loader', true);
+      this.internal = { loadCache: new Map() };
+    }
+    async import(url, _fallback) {
+      let target = url;
+      if (!this.internal.loadCache.has(url)) {
+        const u = new URL(url);
+        u.searchParams.set('probe', String(Date.now()) + '-' + Math.random().toString(36).slice(2, 8));
+        target = u.href;
+      }
+      const mod = await import(target);
+      this.internal.loadCache.set(url, mod);
+      return mod;
+    }
+    unwrapExports(mod) { return mod; }
+  }
+
+  root.plugin(FakeLoader);
+  // 等 service 就绪。不能用 root.lifecycle.flush()：该版本的 root 上没有 lifecycle。
+  for (let i = 0; i < 100; i++) {
+    if (root.loader && root.loader.internal && root.loader.internal.loadCache) break;
+    await new Promise((r) => setTimeout(r, 10));
+  }
+  assert.ok(root.loader, 'FakeLoader service 应已就绪');
+
+  return { root };
+}
+
+// ── S1: 完整重载真的换掉了代码（核心断言）─────────────────────────────
+test('S1: 真实 Cordis 里 selfReload 换上了新代码（marker v1 → v2）', { skip: skipLive }, async () => {
+  const { root } = await withLoaderService();
+
+  const dir = mkdtempSync(join(tmpdir(), 'reload-probe-'));
+  writePlugin(dir, 'v1');
+
+  const pkgUrl = pathToFileURL(dir + '\\').href;
+  const entryUrl = pathToFileURL(join(dir, 'lib', 'index.js')).href;
+
+  const loader = root.loader;
+  const first = await loader.import(entryUrl);
+  assert.equal(first.marker, 'v1', '初版应是 v1');
+  const oldFp = first.fingerprint;
+  assert.ok(oldFp.length > 0, '初版应有指纹');
+  assert.ok(loader.internal.loadCache.size > 0, 'loadCache 应有条目');
+
+  // 用模块对象本身注册 —— registry.get(fiber.runtime.callback) 才能查到 runtime，
+  // 且被注册模块的 apply 会真的执行（拿到 ctx）。
+  const fiber = root.plugin(first);
+  await fiber.await();
+  const pluginCtx = globalThis.__reloadProbeCtx;
+  assert.ok(pluginCtx, '被注册模块的 apply 应执行并留下 ctx');
+
+  const prev = fiber.runtime.callback;
+  const rt = root.registry.get(prev);
+  assert.ok(rt, 'registry 应能用 callback 查到 runtime');
+  assert.ok([...rt.fibers].length >= 1, 'runtime 应有 live fiber');
+
+  // 改代码 → 磁盘变成 v2（内容变了，源码哈希也会变）
+  writePlugin(dir, 'v2');
+  assert.ok(computeFingerprint(dir).length > 0, '磁盘指纹应可算');
+
+  const r = await selfReload(pluginCtx, {
+    logger: { info() {}, warn() {} },
+    packageUrl: pkgUrl,
+    entryUrl,
+    differFrom: oldFp,
+  });
+
+  assert.equal(r.ok, true, '重载应成功：' + (r.error || ''));
+
+  // 核心断言：重新求值后拿到 v2，且指纹变了（代码真的换了）
+  const reloaded = await import(entryUrl + '?probe=verify-' + Date.now());
+  assert.equal(reloaded.marker, 'v2', '重新求值后应是 v2（磁盘上的新代码）');
+  assert.notEqual(reloaded.fingerprint, oldFp, '源码变了，指纹必须不同');
+});
+
+// ── S2: 代码没变时，differFrom 校验必须拦住（不谎报成功）────────────────
+test('S2: 代码未变时 differFrom 校验判失败（不假成功）', { skip: skipLive }, async () => {
+  const { root } = await withLoaderService();
+
+  const dir = mkdtempSync(join(tmpdir(), 'reload-same-'));
+  writePlugin(dir, 'same');
+
+  const pkgUrl = pathToFileURL(dir + '\\').href;
+  const entryUrl = pathToFileURL(join(dir, 'lib', 'index.js')).href;
+
+  const loader = root.loader;
+  const first = await loader.import(entryUrl);
+
+  const fiber = root.plugin(first);
+  await fiber.await();
+  const pluginCtx = globalThis.__reloadProbeCtx;
+  assert.ok(pluginCtx, 'apply 应执行');
+
+  // 不改代码，把当前指纹当 differFrom → 必须失败。
+  // 这是 2026-10-17 假成功的直接复刻：重新求值确实发生了，
+  // 但代码没变，所以"生效"这个结论不成立。
+  const r = await selfReload(pluginCtx, {
+    logger: { info() {}, warn() {} },
+    packageUrl: pkgUrl,
+    entryUrl,
+    differFrom: first.fingerprint,
+  });
+
+  assert.equal(r.ok, false,
+    '代码未变时必须判失败 —— 否则就是 2026-10-17 那种假成功');
+  assert.match(String(r.error), /unchanged|verification failed/,
+    '错误信息应说明校验未通过，实际：' + r.error);
+});
+
+// ── S3: 缺 loader/registry 时安全返回，不抛异常 ─────────────────────────
+test('S3: 上下文缺 loader 时返回结构化失败（不抛）', async () => {
+  const r = await selfReload({}, { logger: { info() {}, warn() {} } });
+  assert.equal(r.ok, false);
+  assert.match(String(r.error), /no loader\/registry/);
+});
+
+// ── S4: computeFingerprint 对真实插件目录可用 ──────────────────────────
+test('S4: computeFingerprint 对真实插件目录返回非空指纹', () => {
+  const fp = computeFingerprint(ROOT);
+  assert.ok(fp.length > 0, '真实插件目录应能算出指纹');
+  assert.match(fp, /^[0-9a-f]{8}$/, '应是 8 位十六进制');
+});
+
+// ── S5: 真实 index.js 的 fingerprint 不随代际变化（关键：判断力正确）────
+test('S5: index.js 的 fingerprint 对同一份代码保持稳定（不随代际变）', async () => {
+  const base = pathToFileURL(join(ROOT, 'lib', 'index.js')).href;
+  const a = await import(base);
+  const b = await import(base + '?dns-reload=gen-different');
+  assert.equal(a.fingerprint, b.fingerprint,
+    '代码没变时，代际不同也必须得到相同指纹 —— 否则校验判断力是反的');
+  assert.ok(a.fingerprint.length > 0, '指纹不能为空');
+});
+
+// ── S6: verifyReload 的四条规则（防逻辑漂移）────────────────────────────
+test('S6: verifyReload 的四条规则', () => {
+  assert.equal(verifyReload({ gotFingerprint: 'aaa', differFrom: 'aaa' }).ok, false,
+    '相同指纹必须失败');
+  assert.equal(verifyReload({ gotFingerprint: 'bbb', differFrom: 'aaa' }).ok, true,
+    '不同指纹应通过');
+  assert.equal(verifyReload({ gotFingerprint: '', differFrom: 'aaa' }).ok, false,
+    '缺指纹必须失败（无法自证）');
+  assert.equal(verifyReload({ gotFingerprint: 'aaa' }).checked, false,
+    '未启用校验时 checked 应为 false');
+});

package/test/reload-verification.test.mjs

@@ -0,0 +1,218 @@
+/**
+ * 热重载「真生效」验证测试（v0.4.20）。
+ *
+ * ## 为什么这批测试必须存在
+ *
+ * 2026-10-17 实测：`selfReload()` 返回 `{ ok: true }`，但代码**没有真的换掉**
+ * （`config-store.js` 换了、`index.js` 没换，或反之）。这种「假成功」造成的
+ * 误导极强 —— 我因此连续几轮都基于"新代码已运行"的错误前提分析问题。
+ *
+ * 原有 D1~D8 只测了 `packageCacheKeys` / `purgeCaches` 这些**工具函数**，
+ * 对"重载到底有没有生效"完全没有覆盖。所以它报成功，测试照样全绿。
+ *
+ * ## 这批测试验证什么
+ *
+ * 用**真实的 Node 模块系统**（不是 mock）验证三件事：
+ *
+ *   1. `fingerprint` 是真的会变的：同一文件的不同代际 URL 得到不同指纹，
+ *      不同模块对象、不同 apply 函数。
+ *   2. 代际绕过真的能穿透到依赖：入口带 `?dns-reload=x` 时，
+ *      它 import 的依赖也必须重新求值（这是"半新半旧"的根治点）。
+ *   3. 校验逻辑真的会拒绝假成功：指纹没变时必须抛错，而不是默默返回 ok。
+ *
+ * 这些用独立 node 进程跑真实 import，因此**不需要重启 DSH**。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, mkdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { registerHooks } from 'node:module';
+
+import { computeFingerprint } from '../lib/dev-reload.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// ── R1: 本包 index.js 确实导出了 fingerprint ────────────────────────────
+test('R1: lib/index.js 导出非空 fingerprint（生效校验的前提）', async () => {
+  const mod = await import(pathToFileURL(join(ROOT, 'lib', 'index.js')).href);
+  assert.equal(typeof mod.fingerprint, 'string',
+    'index.js 必须导出 string 类型的 fingerprint，否则重载无法自证生效');
+  assert.ok(mod.fingerprint.length > 0, 'fingerprint 不能为空');
+});
+
+// ── R2: 同一 URL 重复导入 → 指纹相同（模块缓存生效，符合预期）──────────
+test('R2: 同 URL 重复 import 得到相同 fingerprint（未重新求值）', async () => {
+  const url = pathToFileURL(join(ROOT, 'lib', 'index.js')).href;
+  const a = await import(url);
+  const b = await import(url);
+  assert.equal(a.fingerprint, b.fingerprint,
+    '同一 URL 应命中缓存、不重新求值 —— 这正是热重载要打破的');
+});
+
+// ── R3: 不同代际 URL → 指纹不同、模块对象不同（代际绕过有效）────────────
+test('R3: 代际 URL 得到新模块对象，但 fingerprint 相同（源码哈希语义）', async () => {
+  // ⚠️ 这条的断言在 v0.4.20 变过，原因很重要：
+  //
+  // 第一版 fingerprint 由 import.meta.url 派生，于是「代际不同 → 指纹不同」。
+  // 但那让校验**判断力反了** —— 代码没改、只是重新求值一次，指纹也变，
+  // 于是「没改代码」被判成「新代码已生效」（S2 测试当场抓到）。
+  //
+  // 现在 fingerprint 是**源码哈希**：代码不变 → 指纹不变，与代际无关。
+  // 所以这里断言「指纹相同、模块对象不同」，正好体现两者语义差异：
+  //   · 代际（URL） 反映「是否重新求值」
+  //   · 指纹         反映「代码内容是否变化」
+  const base = pathToFileURL(join(ROOT, 'lib', 'index.js')).href;
+  const a = await import(base);
+  const b = await import(base + '?dns-reload=gen-a');
+  const c = await import(base + '?dns-reload=gen-b');
+
+  // 代际确实让模块重新求值了
+  assert.notEqual(a, b, '不同代际应是不同的模块对象');
+  assert.equal(typeof b.apply, 'function');
+  assert.notEqual(a.apply, b.apply, 'apply 函数应是新的（不是复用旧对象）');
+
+  // 但代码没变，所以指纹必须一致 —— 这是校验能「拒绝假成功」的前提
+  assert.equal(a.fingerprint, b.fingerprint, '代码未变时，代际不同指纹也应相同');
+  assert.equal(b.fingerprint, c.fingerprint, '同理');
+});
+
+test('R4: enableFreshDependencies 让代际穿透到依赖（真实实现，非手写钩子）', async () => {
+  // ⚠️ 设计要点：必须调用**真实的** enableFreshDependencies，
+  // 而不是在测试里手写一份同构的 hook。
+  //
+  // 第一版 R4 就是手写 hook，结果变异测试发现：把 dev-reload.js 里的
+  // 穿透逻辑改坏，R4 依然全绿（假阴性）。原因很简单 —— 它测的是自己。
+  //
+  // 这条对应 2026-10-17 的真实故障：入口带代际了、但入口里 import './x.js'
+  // 不带代际，于是依赖仍是旧模块，形成"半新半旧"。
+  const dir = mkdtempSync(join(tmpdir(), 'gen-pass-'));
+  mkdirSync(join(dir, 'lib'), { recursive: true });
+  writeFileSync(join(dir, 'lib', 'dep.js'),
+    'export const selfUrl = import.meta.url;\nexport const marker = "dep";\n');
+  writeFileSync(join(dir, 'lib', 'entry.js'),
+    'import { selfUrl, marker } from "./dep.js";\nexport { marker };\nexport const depUrl = selfUrl;\n');
+
+  const entryBase = pathToFileURL(join(dir, 'lib', 'entry.js')).href;
+  const depBase = pathToFileURL(join(dir, 'lib', 'dep.js')).href;
+
+  // ① 不带代际：依赖 URL 就是原样
+  const plain = await import(entryBase);
+  assert.equal(plain.depUrl, depBase, '不带代际时依赖 URL 应是原样');
+
+  // ② 用被测模块自己的实现装上穿透钩子
+  const { enableFreshDependencies } = await import('../lib/dev-reload.js');
+  const packageUrl = pathToFileURL(dir + '\\').href;
+  enableFreshDependencies(packageUrl);
+
+  // ③ 导入带代际的入口，检查依赖是否也继承了代际
+  const gened = await import(entryBase + '?dns-reload=testgen-' + Date.now());
+  assert.match(gened.depUrl, /dns-reload=testgen-/,
+    '依赖模块的 URL 应继承代际参数；否则依赖仍是旧模块（"半新半旧"的机制）');
+  assert.notEqual(gened.depUrl, depBase, '依赖不应还是原 URL');
+  assert.equal(gened.marker, 'dep', '同一份磁盘代码，导出的值应一致');
+});
+
+test('R5: computeFingerprint 随文件变化而变（不是固定值）', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'fp-test-'));
+  mkdirSync(join(dir, 'lib'), { recursive: true });
+  writeFileSync(join(dir, 'package.json'), '{"name":"x","version":"1.0.0"}');
+  writeFileSync(join(dir, 'lib', 'a.js'), 'export const x = 1;');
+
+  const fp1 = computeFingerprint(dir);
+  assert.ok(fp1.length > 0, '应返回非空指纹');
+
+  // ⚠️ 指纹用的是 statSync 的 size + mtimeMs，而很多文件系统的 mtime 精度
+  // 只有 1ms~1s。连续写入可能落在同一时间片里，导致"文件变了但指纹没变"。
+  // 这不是代码缺陷（真实场景下改动间隔远大于此），但会让测试间歇性失败。
+  // 所以这里显式等到 mtime 真的变化，再写第二版。
+  const before = statSync(join(dir, 'lib', 'a.js')).mtimeMs;
+  let waited = 0;
+  while (statSync(join(dir, 'lib', 'a.js')).mtimeMs === before && waited < 2000) {
+    await new Promise((r) => setTimeout(r, 20));
+    waited += 20;
+  }
+  writeFileSync(join(dir, 'lib', 'a.js'), 'export const x = 22222;');
+
+  const fp2 = computeFingerprint(dir);
+  assert.notEqual(fp1, fp2,
+    '文件变了指纹就该变 —— 否则"磁盘期望值"校验形同虚设');
+});
+
+// ── R6: computeFingerprint 目录不存在时返回空串，不抛异常 ─────────────────
+test('R6: computeFingerprint 对不存在目录返回空串（不抛）', () => {
+  let fp;
+  assert.doesNotThrow(() => { fp = computeFingerprint('Z:\\no-such-dir-xyz'); });
+  assert.equal(typeof fp, 'string');
+  assert.equal(fp, '', '不存在时应返回空串，让调用方知道"算不出来"');
+});
+
+// ── R7: computeFingerprint 对同一目录稳定（同样内容得到同样值）──────────
+test('R7: computeFingerprint 对未改动的目录保持稳定', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'fp-stable-'));
+  mkdirSync(join(dir, 'lib'), { recursive: true });
+  writeFileSync(join(dir, 'package.json'), '{"name":"y"}');
+  writeFileSync(join(dir, 'lib', 'b.js'), 'export const y = 1;');
+  const a = computeFingerprint(dir);
+  const b = computeFingerprint(dir);
+  assert.equal(a, b, '同一份未改动的内容应得到相同指纹');
+});
+
+// ── R8: verifyReload 的四条规则（核心：防假成功）─────────────────────────
+test('R8: verifyReload 在指纹相同时必须判失败（复刻 2026-10-17 假成功）', async () => {
+  const { verifyReload } = await import('../lib/dev-reload.js');
+
+  // 负向：相同指纹 → 必须失败。这正是当年"重载报 ok 但其实没换"的根因。
+  const same = verifyReload({ gotFingerprint: 'abc12345', differFrom: 'abc12345' });
+  assert.equal(same.ok, false, '指纹相同必须判失败，不能默默报 ok');
+  assert.equal(same.checked, true, '应标记为"已校验"');
+  assert.match(same.error, /unchanged/, '错误信息应说明指纹未变');
+
+  // 正向：不同指纹 → 通过
+  const diff = verifyReload({ gotFingerprint: 'def67890', differFrom: 'abc12345' });
+  assert.equal(diff.ok, true);
+  assert.equal(diff.checked, true);
+
+  // 负向：没有指纹 → 无法自证 → 失败（不能因为"拿不到"就放行）
+  const none = verifyReload({ gotFingerprint: '', differFrom: 'abc12345' });
+  assert.equal(none.ok, false, '拿不到指纹时必须失败 —— 否则等于没校验');
+  assert.match(none.error, /does not export fingerprint/);
+
+  // 未启用校验 → 通过，但 checked=false（调用方要知道"这次没验证"）
+  const off = verifyReload({ gotFingerprint: 'abc' });
+  assert.equal(off.ok, true);
+  assert.equal(off.checked, false, '未启用校验时 checked 应为 false');
+});
+
+// ── R8b: expectedFingerprint 比 differFrom 更严 ──────────────────────────
+test('R8b: expectedFingerprint 要求完全相等', async () => {
+  const { verifyReload } = await import('../lib/dev-reload.js');
+
+  const match = verifyReload({ gotFingerprint: 'aaa', expectedFingerprint: 'aaa' });
+  assert.equal(match.ok, true);
+
+  const mismatch = verifyReload({ gotFingerprint: 'bbb', expectedFingerprint: 'aaa' });
+  assert.equal(mismatch.ok, false);
+  assert.match(mismatch.error, /mismatch/, '错误信息应指出不匹配');
+});
+
+// ── R9: index.js 的 fingerprint 由 import.meta.url 派生（可区分代际）─────
+test('R9: index.js 源码里的 fingerprint 依赖 import.meta.url', () => {
+  const src = readFileSync(join(ROOT, 'lib', 'index.js'), 'utf8');
+  assert.match(src, /export const fingerprint/, '必须导出 fingerprint');
+  assert.match(src, /import\.meta\.url/,
+    'fingerprint 必须由 import.meta.url 派生，否则不同代际会得到相同值');
+});
+
+// ── R10: dev-reload 源码必须含代际绕过（这次的根治点）───────────────────
+test('R10: dev-reload.js 含代际绕过与 registerHooks', () => {
+  const src = readFileSync(join(ROOT, 'lib', 'dev-reload.js'), 'utf8');
+  assert.match(src, /registerHooks/, '必须用 registerHooks 把代际传给依赖');
+  assert.match(src, /searchParams\.set\(GEN_PARAM/,
+    '必须给 URL 加代际参数，否则缓存清不掉时无法强制重求值');
+  assert.match(src, /enableFreshDependencies/, '必须有代际穿透函数');
+  // 旧实现"清不掉就放弃"的写法必须消失
+  assert.doesNotMatch(src, /nothing was purged \(loadCache shape changed/,
+    '不应再有"清不掉就直接放弃"的分支 —— 那正是假成功的来源');
+});

package/test/route-loader-register.mjs

@@ -0,0 +1,22 @@
+/**
+ * 注册 `stub-child-process.mjs` loader，并置位 `globalThis.__STUB_CHILD_PROCESS__`
+ *（供 `fail-route.test.mjs` 自检"stub 是否真的生效"）。
+ *
+ * 用法（只能用 --import，不能用 --loader，后者在新版 Node 已废弃）：
+ *   node --import ./test/route-loader-register.mjs --test test/fail-route.test.mjs
+ * 或直接 `npm run test:route`。
+ *
+ * ⚠️ 两点实测注意：
+ * ① register() 必须在**测试文件加载之前**执行 —— --import 保证这一点。
+ * ② 该文件与 stub 都**不是**测试文件（不以 .test. 命名），默认 `node --test` 不会执行它们。
+ */
+import { register } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+globalThis.__STUB_CHILD_PROCESS__ = true;
+process.env.DSH_ROUTE_LOADER = '1';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+register(pathToFileURL(join(HERE, 'stub-child-process.mjs')));

package/test/scalar-guard.test.mjs

@@ -0,0 +1,125 @@
+/**
+ * 标量过滤测试：防 "[object Object]" 漏进 PowerShell 参数。
+ *
+ * ## 为什么这个 bug 值得专门测
+ *
+ * 2026-10-17 实测：`kindOr()` 从按事件字典取值时，拿到了 schemastery 的
+ * **ref 对象**（带 .get() 的包装）。它被原样拼进 PowerShell 的 `-Voice`/`-Rate`
+ * 参数，变成字符串 `"[object Object]"`：
+ *
+ *   - 弹窗**正常**（那部分参数没错）
+ *   - 声音**完全静默**（SAPI 收到非法参数，合成失败）
+ *
+ * 表象是"通知能用但没声音"，非常容易误判成音频设备或播放链路问题。
+ * 所以我之前查了半小时音源判断逻辑，真正的原因却在这里。
+ *
+ * ## 测试策略
+ *
+ * 直接测 `effectiveForClient` 的输出：它必须只产出**标量**，
+ * 任何对象（包括 ref 包装）都要被丢弃或解包成标量。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { effectiveForClient } from '../lib/index.js';
+
+/** 造一个 schemastery 风格的 ref（有 .get()）。 */
+function mkRef(value) {
+  return {
+    __isRef: true,
+    get() { return value; },
+  };
+}
+
+/** 基础 cfg 骨架。 */
+function mkCfg(over) {
+  return {
+    voice: true, volume: 80, audioSource: 'tts', showToast: true,
+    voiceMode: 'fixed', voiceName: 'zundamon-normal', ttsVoice: '', ttsRate: 0,
+    debounceMs: 60_000, globalCooldownMs: 0,
+    audioSourceByKind: {}, ttsTexts: {},
+    kindTtsVoice: {}, kindTtsRate: {}, kindVoiceMode: {},
+    kindVoiceName: {}, kindSystemSound: {}, customFiles: {},
+    ...over,
+  };
+}
+
+// ── X1: 字典里的 ref 对象必须被解包成标量 ────────────────────────────────
+test('X1: 按事件字典里的 ref 对象被解包成标量（不是 [object Object]）', () => {
+  const r = effectiveForClient(mkCfg({
+    kindTtsVoice: { done: mkRef('Microsoft Huihui Desktop') },
+    kindTtsRate: { done: mkRef(-3) },
+  }));
+
+  // 关键断言：必须是字符串/数字，不能是对象
+  assert.equal(typeof r.kindTtsVoiceDone, 'string',
+    `必须解包成字符串，实际 ${typeof r.kindTtsVoiceDone}`);
+  assert.equal(r.kindTtsVoiceDone, 'Microsoft Huihui Desktop');
+  assert.equal(typeof r.kindTtsRateDone, 'number');
+  assert.equal(r.kindTtsRateDone, -3);
+
+  // 绝对不能出现 "[object Object]"
+  assert.doesNotMatch(String(r.kindTtsVoiceDone), /\[object Object\]/);
+});
+
+// ── X2: 无法解包的对象被丢弃，而不是原样传出 ─────────────────────────────
+test('X2: 无法解包的对象被丢弃（宁可跟随全局，也不要脏值）', () => {
+  const r = effectiveForClient(mkCfg({
+    kindSystemSound: { fail: { some: 'object' } },
+    kindVoiceName: { question: ['array'] },
+  }));
+  assert.equal(r.kindSystemSoundFail, undefined,
+    '不可解包的对象应被丢弃，否则会变成 [object Object]');
+  assert.equal(r.kindVoiceNameQuestion, undefined);
+});
+
+// ── X3: 正常标量照常透传（防过度过滤）────────────────────────────────────
+test('X3: 正常标量不受影响', () => {
+  const r = effectiveForClient(mkCfg({
+    kindSystemSound: { done: 'Asterisk', fail: 'Hand' },
+    kindVoiceName: { question: 'ankomon' },
+    ttsTexts: { done: '搞定啦' },
+    customFiles: { approval: 'D:\\a.wav' },
+    kindTtsRate: { done: 5 },
+  }));
+  assert.equal(r.kindSystemSoundDone, 'Asterisk');
+  assert.equal(r.kindSystemSoundFail, 'Hand');
+  assert.equal(r.kindVoiceNameQuestion, 'ankomon');
+  assert.equal(r.ttsTextDone, '搞定啦');
+  assert.equal(r.customFileApproval, 'D:\\a.wav');
+  assert.equal(r.kindTtsRateDone, 5);
+});
+
+// ── X4: 所有按事件扁平键都必须是标量 ─────────────────────────────────────
+test('X4: 所有 kind* / ttsText* / customFile* 输出都是标量', () => {
+  // 故意塞入各种类型，看有没有漏出对象
+  const r = effectiveForClient(mkCfg({
+    kindTtsVoice: { done: mkRef('A'), fail: {}, question: [], approval: null, blocked: 0 },
+    kindTtsRate: { done: mkRef(1), fail: 'abc' },
+    kindVoiceMode: { done: mkRef('fixed') },
+    kindVoiceName: { done: 'x' },
+    kindSystemSound: { done: 'Beep' },
+    ttsTexts: { done: 'hi', fail: {} },
+    customFiles: { done: 'D:\\a.wav', fail: [] },
+  }));
+
+  const perKind = Object.keys(r).filter((k) => /^(kind|ttsText|customFile)[A-Z]/.test(k));
+  assert.ok(perKind.length > 0, '应有按事件扁平键');
+
+  const bad = perKind.filter((k) => {
+    const v = r[k];
+    return typeof v === 'object' || Array.isArray(v);
+  });
+  assert.deepEqual(bad, [],
+    '以下按事件键的值是对象，会被 PowerShell 读成 [object Object]：' + JSON.stringify(bad));
+});
+
+// ── X5: 解包失败时不能抛异常 ─────────────────────────────────────────────
+test('X5: ref.get() 抛异常时不崩，退回全局', () => {
+  const boom = { get() { throw new Error('boom'); } };
+  let r;
+  assert.doesNotThrow(() => {
+    r = effectiveForClient(mkCfg({ kindTtsVoice: { done: boom } }));
+  });
+  assert.equal(r.kindTtsVoiceDone, undefined, '解包失败应丢弃');
+});