dsh-notify-say 0.4.21 → 0.4.25

package/test/config-store.test.mjs

@@ -0,0 +1,256 @@
+/**
+ * config-store 测试：可持久配置层的正确性与 fail-closed 契约。
+ *
+ * 全部用合成 `$DSH_HOME`（临时目录），**不碰真实 profile / storages**。
+ *
+ * 覆盖重点（都是真会出事的路径）：
+ *  - 三层优先级：文件值覆盖 patch 值，patch 值覆盖 DEFAULTS
+ *  - fail-closed：坏 JSON 不被覆盖、不被当成"没有偏好"
+ *  - 白名单：未知键丢弃，不会污染配置文件
+ *  - 原子写：不留半截文件、不留 .tmp
+ *  - 越界值：volume 101 / -1 / NaN 一律拒绝
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  CONFIG_VERSION,
+  CONFIG_RELATIVE_PATH,
+  CONFIG_KEYS,
+  safeHome,
+  configPath,
+  sanitize,
+  readConfig,
+  writeConfig,
+  mergeConfig,
+} from '../lib/config-store.js';
+
+/** 造一个隔离的 $DSH_HOME。 */
+function mkHome() {
+  const dir = mkdtempSync(join(tmpdir(), 'notify-cfg-'));
+  return { dir, env: { DSH_HOME: dir } };
+}
+
+function cleanup(h) {
+  try { rmSync(h.dir, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
+// ── C1: 路径解析 ────────────────────────────────────────────────────────────
+test('C1: safeHome / configPath 正确解析 $DSH_HOME（含尾部斜杠）', () => {
+  assert.equal(safeHome({ DSH_HOME: 'D:\\DSH' }), 'D:\\DSH');
+  assert.equal(safeHome({ DSH_HOME: 'D:\\DSH\\\\' }), 'D:\\DSH');
+  assert.equal(safeHome({}), '', '根本没有 DSH_HOME 键时应返回空串');
+  assert.equal(safeHome({ DSH_HOME: '' }), '', 'DSH_HOME 为空串时应返回空串');
+  // null/undefined 的语义是「未提供」，按设计回退到 process.env ——
+  // 所以这里不能断言 ''（ci 环境可能真有 DSH_HOME）。只断言类型与幂等。
+  assert.equal(typeof safeHome(null), 'string');
+  assert.equal(typeof safeHome(undefined), 'string');
+  assert.equal(safeHome(null), safeHome(process.env), 'null 应等价于 process.env');
+
+  assert.equal(configPath({}), '', '$DSH_HOME 缺失时应返回空串而不是拼出相对路径');
+  assert.match(configPath({ DSH_HOME: 'D:\\DSH' }), /config\.json$/);
+  // 路径构成必须是本插件自己的目录
+  assert.match(configPath({ DSH_HOME: 'D:\\DSH' }).replace(/\\/g, '/'), /storages\/dsh-notify-say\/config\.json$/);
+});
+
+// ── C2: 文件不存在 = 没有偏好，不是错误 ─────────────────────────────────────
+test('C2: 文件不存在时返回 ok:true + 空值（调用方用 patch 默认值）', () => {
+  const h = mkHome();
+  try {
+    const r = readConfig(h.env);
+    assert.equal(r.ok, true);
+    assert.deepEqual(r.value, {});
+  } finally { cleanup(h); }
+});
+
+// ── C3: 写入后能读回；白名单外的键被丢弃 ────────────────────────────────────
+test('C3: 写入白名单键并读回；未知键被丢弃且不落盘', () => {
+  const h = mkHome();
+  try {
+    const w = writeConfig({ volume: 42, voiceName: 'ankomon', evilKey: 'x', __proto__: 'y' }, h.env);
+    assert.equal(w.ok, true, '写入应成功');
+    assert.deepEqual(w.written.sort(), ['voiceName', 'volume'], '只应写入白名单键');
+    assert.ok(w.dropped === undefined || w.dropped.includes('evilKey'));
+
+    const r = readConfig(h.env);
+    assert.equal(r.ok, true);
+    assert.equal(r.value.volume, 42);
+    assert.equal(r.value.voiceName, 'ankomon');
+    assert.equal(r.value.evilKey, undefined, '未知键不得落盘');
+
+    // 磁盘文件里也不该有 evilKey
+    const raw = readFileSync(configPath(h.env), 'utf8');
+    assert.ok(!raw.includes('evilKey'), '未知键不得出现在文件里');
+  } finally { cleanup(h); }
+});
+
+// ── C4: 部分写入是合并，不是覆盖 ────────────────────────────────────────────
+test('C4: 二次写入只改指定键，其余保留（合并语义）', () => {
+  const h = mkHome();
+  try {
+    writeConfig({ volume: 30, voiceName: 'ankomon' }, h.env);
+    writeConfig({ volume: 90 }, h.env);
+    const r = readConfig(h.env);
+    assert.equal(r.value.volume, 90, 'volume 应被更新');
+    assert.equal(r.value.voiceName, 'ankomon', '未指定的键必须保留');
+  } finally { cleanup(h); }
+});
+
+// ── C5: fail-closed —— 坏文件不被覆盖 ───────────────────────────────────────
+test('C5: 磁盘上是坏 JSON 时报告 corrupt，且**不覆盖**用户原文件', () => {
+  const h = mkHome();
+  try {
+    const p = configPath(h.env);
+    // 先建目录再写坏内容
+    writeConfig({ volume: 50 }, h.env);
+    const bad = '{ this is not json';
+    writeFileSync(p, bad, 'utf8');
+
+    const r = readConfig(h.env);
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'corrupt');
+
+    // 关键：写入必须被拒绝，且原文件字节不变
+    const w = writeConfig({ volume: 10 }, h.env);
+    assert.equal(w.ok, false, 'corrupt 时写入必须被拒绝');
+    assert.equal(w.reason, 'corrupt');
+    assert.equal(readFileSync(p, 'utf8'), bad, '坏文件必须原样保留，便于人工救');
+  } finally { cleanup(h); }
+});
+
+// ── C6: 版本不认识 → 也当 corrupt，不覆盖 ───────────────────────────────────
+test('C6: version 不匹配时报告 corrupt，不覆盖', () => {
+  const h = mkHome();
+  try {
+    writeConfig({ volume: 50 }, h.env);
+    const p = configPath(h.env);
+    writeFileSync(p, JSON.stringify({ version: 999, values: { volume: 1 } }), 'utf8');
+    const r = readConfig(h.env);
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'corrupt');
+    assert.equal(writeConfig({ volume: 2 }, h.env).ok, false, '未知版本不得被覆盖');
+  } finally { cleanup(h); }
+});
+
+// ── C7: 越界值被拒 ──────────────────────────────────────────────────────────
+test('C7: volume 越界/非法被拒，不写坏值', () => {
+  const h = mkHome();
+  try {
+    const bad = sanitize({ volume: 101 });
+    assert.equal(bad.value.volume, undefined, 'volume 101 必须被拒');
+    assert.equal(sanitize({ volume: -1 }).value.volume, undefined);
+    assert.equal(sanitize({ volume: 'abc' }).value.volume, undefined);
+    assert.equal(sanitize({ volume: NaN }).value.volume, undefined);
+    assert.equal(sanitize({ volume: 0 }).value.volume, 0, '0 是合法值（静音）');
+    assert.equal(sanitize({ volume: 100 }).value.volume, 100, '100 是合法值（上限）');
+    assert.equal(sanitize({ volume: 50.6 }).value.volume, 51, '小数应取整');
+  } finally { /* no home needed */ }
+});
+
+// ── C8: 原子写 —— 不留 .tmp / 半截文件 ──────────────────────────────────────
+test('C8: 写入后目录里只有 config.json，没有 .tmp 残留', () => {
+  const h = mkHome();
+  try {
+    writeConfig({ volume: 60 }, h.env);
+    const dir = join(h.dir, 'storages', 'dsh-notify-say');
+    const files = readdirSync(dir);
+    assert.deepEqual(files, ['config.json'], '不应留下 .tmp');
+    // 文件必须是完整可解析 JSON
+    const doc = JSON.parse(readFileSync(join(dir, 'config.json'), 'utf8'));
+    assert.equal(doc.version, CONFIG_VERSION);
+    assert.equal(doc.values.volume, 60);
+  } finally { cleanup(h); }
+});
+
+// ── C9: 三层优先级 ──────────────────────────────────────────────────────────
+test('C9: mergeConfig —— 文件值覆盖 patch 值；两者都没有的键不出现', () => {
+  const patch = { volume: 80, voiceName: 'zundamon-normal', idleGate: true };
+  const file = { volume: 100, voice: false };
+
+  const merged = mergeConfig(patch, file);
+  assert.equal(merged.volume, 100, '文件值必须覆盖 patch');
+  assert.equal(merged.voice, false, '文件里的布尔也要覆盖');
+  assert.equal(merged.voiceName, 'zundamon-normal', '文件没写的键沿用 patch');
+  assert.equal(merged.idleGate, true, '文件没写的键沿用 patch');
+
+  // 空 patch / 空 file 不应崩
+  assert.deepEqual(mergeConfig(undefined, undefined), {});
+  assert.deepEqual(mergeConfig(null, null), {});
+  assert.deepEqual(mergeConfig({ a: 1 }, null), { a: 1 });
+  assert.deepEqual(mergeConfig({ a: 1 }, { a: 2 }), { a: 2 });
+});
+
+// ── C10: 无 $DSH_HOME 时安全降级 ────────────────────────────────────────────
+test('C10: 缺 $DSH_HOME 时读写都安全失败，不抛异常', () => {
+  const env = {};
+  const r = readConfig(env);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'no-home');
+  const w = writeConfig({ volume: 10 }, env);
+  assert.equal(w.ok, false);
+  assert.equal(w.reason, 'no-home');
+});
+
+// ── C11: 白名单键清单稳定（防有人悄悄删键导致 GUI 存的配置被丢）──────────
+test('C11: CONFIG_KEYS 覆盖 GUI 需要的全部键', () => {
+  const need = ['voice', 'voiceMode', 'voiceName', 'volume',
+    'notifyOnComplete', 'notifyOnError', 'notifyOnBlocked',
+    'notifyOnApproval', 'notifyOnQuestion', 'subagents', 'idleGate'];
+  for (const k of need) {
+    assert.ok(CONFIG_KEYS.includes(k), `CONFIG_KEYS 缺少 ${k}`);
+  }
+});
+
+// ── S12-S15: v0.4.4 自定义音频路径校验 ────────────────────────────────────
+// 自定义音频只记**绝对路径**，不复制文件。所以路径校验就是唯一的安全边界：
+// 放行错了会让播放进程去读任意位置；放行相对路径则会随 cwd 漂移而随机失败。
+
+test('S12: customFile* 接受绝对路径（盘符与 UNC）', () => {
+  const a = sanitize({ customFileDone: 'D:\\Music\\a.mp3' });
+  assert.equal(a.value.customFileDone, 'D:\\Music\\a.mp3');
+
+  const b = sanitize({ customFileFail: '\\\\server\\share\\b.wav' });
+  assert.equal(b.value.customFileFail, '\\\\server\\share\\b.wav');
+
+  // 支持的扩展名
+  for (const ext of ['wav', 'mp3', 'm4a', 'flac', 'ogg', 'WAV']) {
+    const r = sanitize({ customFileDone: `D:\\a.${ext}` });
+    assert.ok(r.value.customFileDone, `应接受 .${ext}`);
+  }
+});
+
+test('S13: customFile* 拒绝相对路径（防随 cwd 随机失败）', () => {
+  for (const p of ['relative.mp3', './a.wav', 'sounds\\a.wav', '..\\a.wav']) {
+    const r = sanitize({ customFileDone: p });
+    assert.equal(r.value.customFileDone, undefined, `应拒绝: ${p}`);
+  }
+});
+
+test('S14: customFile* 拒绝设备命名空间前缀与非法扩展名', () => {
+  // \\?\ 与 \\.\ 能绕开路径规范化，必须挡掉
+  for (const p of ['\\\\?\\C:\\a.wav', '\\\\.\\PhysicalDrive0']) {
+    const r = sanitize({ customFileDone: p });
+    assert.equal(r.value.customFileDone, undefined, `应拒绝设备前缀: ${p}`);
+  }
+  // 非法扩展名
+  for (const p of ['D:\\a.exe', 'D:\\a.txt', 'D:\\a.bat']) {
+    const r = sanitize({ customFileDone: p });
+    assert.equal(r.value.customFileDone, undefined, `应拒绝扩展名: ${p}`);
+  }
+});
+
+test('S15: 五个事件的 customFile 键都可写', () => {
+  const patch = {
+    customFileDone: 'D:\\a.wav',
+    customFileFail: 'D:\\b.wav',
+    customFileQuestion: 'D:\\c.wav',
+    customFileApproval: 'D:\\d.wav',
+    customFileBlocked: 'D:\\e.wav',
+  };
+  const r = sanitize(patch);
+  assert.deepEqual(Object.keys(r.value).sort(), Object.keys(patch).sort(),
+    '五个事件键都应被白名单接受（否则配置存不进去，用户选了文件也不生效）');
+});

package/test/dev-reload.test.mjs

@@ -0,0 +1,132 @@
+/**
+ * dev-reload 测试：热重载的核心纯逻辑。
+ *
+ * ## 为什么这些能单独测
+ *
+ * 真正的 `selfReload()` 要操作活的 ctx / fiber / registry，只能在宿主里验。
+ * 但**最容易写错、也最致命**的部分是纯逻辑：
+ *
+ *   - `packageCacheKeys` 该选哪些缓存键（选错 → 重载拿到旧代码，白折腾）
+ *   - `purgeCaches` 是否真的删掉（用错 delete → 同上）
+ *   - `restoreCaches` 能否完整回滚（回滚不全 → 插件半死）
+ *
+ * 这些都可以用**假 cache**（一个真 Map）穷举验证。
+ *
+ * ## 关键回归
+ *
+ * 上游 FreeModel 的注释明确记载：Node 24 的 `loadCache` 是 Map 子类，
+ * **它自己的 `.delete` 只清"类型槽"**，模块本体仍在。必须用
+ * `Map.prototype.delete.call(cache, key)`。本文件用"子类覆写 delete 但不清本体"
+ * 的假 cache 来锁住这条 —— 如果用 `cache.delete()`，模块不会被真正删除。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  packageCacheKeys, purgeCaches, restoreCaches, packageUrlOf, entryUrlOf,
+} from '../lib/dev-reload.js';
+
+const PKG = 'file:///plugins/dsh-notify-say/';
+
+// ── D1: 只选中本包的键 ────────────────────────────────────────────────────
+test('D1: packageCacheKeys 只选本包路径下的键', () => {
+  const cache = new Map([
+    ['file:///plugins/dsh-notify-say/lib/index.js', 'a'],
+    ['file:///plugins/dsh-notify-say/lib/client.js', 'b'],
+    ['file:///plugins/other-plugin/index.js', 'c'],
+    ['file:///plugins/dsh-notify-say-extra/index.js', 'd'],   // 前缀相似但不是本包
+  ]);
+  const keys = packageCacheKeys(cache, PKG);
+  assert.deepEqual(keys.sort(), [
+    'file:///plugins/dsh-notify-say/lib/client.js',
+    'file:///plugins/dsh-notify-say/lib/index.js',
+  ], '不该选中 other-plugin 或 dsh-notify-say-extra');
+});
+
+// ── D2: 大小写与百分号编码容错 ────────────────────────────────────────────
+test('D2: 键比较容忍大小写与百分号编码差异', () => {
+  const cache = new Map([
+    ['file:///PLUGINS/dsh-notify-say/lib/index.js', 'x'],       // 大写
+    ['file:///plugins/dsh-notify-say/lib/a%20b.js', 'y'],        // 含编码
+  ]);
+  const keys = packageCacheKeys(cache, PKG);
+  assert.equal(keys.length, 2, '大写路径与含编码的路径都应命中');
+});
+
+// ── D3: 非字符串键不崩 ────────────────────────────────────────────────────
+test('D3: 非字符串键被跳过，不抛异常', () => {
+  const cache = new Map([[Symbol('s'), 'x'], [42, 'y'], ['file:///plugins/dsh-notify-say/a.js', 'z']]);
+  assert.doesNotThrow(() => packageCacheKeys(cache, PKG));
+  assert.equal(packageCacheKeys(cache, PKG).length, 1);
+});
+
+// ── D4: purge 真的删掉（关键：必须清微模块本体）────────────────────────────
+test('D4: purgeCaches 用 Map.prototype.delete 真正删掉模块本体', () => {
+  // 模拟 Node 24 的 LoadCache：是 Map 子类，自己的 delete 只清"类型槽"
+  class FakeLoadCache extends Map {
+    constructor(entries) {
+      super(entries);
+      this.types = new Map();
+      for (const k of this.keys()) this.types.set(k, 'esm');
+    }
+
+    // ⚠️ 故意写坏：只清类型槽，不清本体 —— 这正是 Node 24 的行为
+    delete(key) {
+      this.types.delete(key);
+      return true;
+    }
+  }
+
+  const pkgEntry = 'file:///plugins/dsh-notify-say/lib/index.js';
+  const other = 'file:///plugins/other/index.js';
+  const cache = new FakeLoadCache([[pkgEntry, { id: 'old-index' }], [other, { id: 'other' }]]);
+
+  const backup = purgeCaches({ loadCache: cache }, PKG);
+
+  assert.equal(backup.esm.size, 1, '应备份 1 个本包模块');
+  assert.equal(backup.esm.get(pkgEntry)?.id, 'old-index');
+
+  // 关键断言：本体必须被真正删除
+  assert.equal(Map.prototype.has.call(cache, pkgEntry), false,
+    '模块本体必须被删掉；若用 cache.delete(key) 只会清类型槽，本体仍在 → 重载拿到旧代码');
+  // 别人的模块不受影响
+  assert.equal(Map.prototype.has.call(cache, other), true, '不该动其它包的模块');
+});
+
+// ── D5: 回滚能把缓存写回去 ────────────────────────────────────────────────
+test('D5: restoreCaches 完整回滚', () => {
+  const pkgEntry = 'file:///plugins/dsh-notify-say/lib/index.js';
+  const cache = new Map([[pkgEntry, { id: 'old' }]]);
+
+  // 清空并快照（用原生 Map，行为等价）
+  const snap = new Map(cache);
+  cache.clear();
+  assert.equal(cache.size, 0);
+
+  restoreCaches({ loadCache: cache }, { esm: snap, cjs: new Map() });
+  assert.equal(cache.get(pkgEntry)?.id, 'old', '回滚后应恢复原模块');
+});
+
+// ── D6: 结构缺失时不崩 ────────────────────────────────────────────────────
+test('D6: loadCache 缺失/畸形时安全返回空备份', () => {
+  for (const internal of [undefined, null, {}, { loadCache: null }, { loadCache: {} }]) {
+    let backup;
+    assert.doesNotThrow(() => { backup = purgeCaches(internal, PKG); });
+    assert.equal(backup.esm.size, 0, '拿不到缓存应返回空备份，而不是抛');
+    assert.doesNotThrow(() => restoreCaches(internal, backup));
+  }
+});
+
+// ── D7: URL 推导 ──────────────────────────────────────────────────────────
+test('D7: packageUrlOf / entryUrlOf 正确推导', () => {
+  const mod = 'file:///plugins/dsh-notify-say/lib/dev-reload.js';
+  assert.equal(packageUrlOf(mod), 'file:///plugins/dsh-notify-say/');
+  assert.equal(entryUrlOf(mod), 'file:///plugins/dsh-notify-say/lib/index.js');
+});
+
+// ── D8: 空 cache 不产生假备份 ─────────────────────────────────────────────
+test('D8: 本包不在缓存里时返回空备份（调用方据此放弃重载）', () => {
+  const cache = new Map([['file:///plugins/other/index.js', {}]]);
+  const backup = purgeCaches({ loadCache: cache }, PKG);
+  assert.equal(backup.esm.size, 0, '没清到任何东西 → 调用方应放弃，而不是当成成功');
+});

package/test/effective-for-client.test.mjs

@@ -0,0 +1,142 @@
+/**
+ * effectiveForClient 测试：内部 cfg → 前端 schema 形状的映射。
+ *
+ * ## 为什么单独测这一层
+ *
+ * 2026-10-17 连续踩了两个坑，都是这一层的：
+ *
+ * ① `getEffective: () => effectiveForClient()` **忘了传 cfg** ——
+ *    返回全空对象，于是界面上所有设置都显示默认值。
+ *    用户看到的是"冷却调成 0 却显示 60 秒""选了音源却还是跟随默认"。
+ *
+ * ② 直接把内部 cfg 交给前端 —— cfg 用毫秒字段名（debounceMs），
+ *    前端读秒字段名（debounceSeconds），键名对不上，同样显示默认值。
+ *
+ * 这两类错误**都不会让任何既有测试失败**，因为它们只影响"读回来的形状"。
+ * 所以必须专门测映射函数本身。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { effectiveForClient } from '../lib/index.js';
+
+/** 造一个典型的内部 cfg（normalizeConfig 的产物形状）。 */
+function mkCfg(over) {
+  return {
+    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,
+    jumpWhenBackground: true,
+    jumpWhenForeground: false,
+    devReload: false,
+    debounceMs: 60_000,
+    globalCooldownMs: 0,
+    audioSourceByKind: {},
+    ttsTexts: {},
+    kindTtsVoice: {},
+    kindTtsRate: {},
+    kindVoiceMode: {},
+    kindVoiceName: {},
+    kindSystemSound: {},
+    customFiles: {},
+    ...over,
+  };
+}
+
+// ── E1: 基础字段直传 ──────────────────────────────────────────────────────
+test('E1: 基础字段原样透传', () => {
+  const r = effectiveForClient(mkCfg({ volume: 55, voice: false }));
+  assert.equal(r.volume, 55);
+  assert.equal(r.voice, false);
+  assert.equal(r.audioSource, 'tts');
+  assert.equal(r.showToast, true);
+});
+
+// ── E2: 毫秒 → 秒（关键：键名必须变）──────────────────────────────────────
+test('E2: debounceMs 映射成 debounceSeconds（键名与单位都要变）', () => {
+  const r = effectiveForClient(mkCfg({ debounceMs: 0, globalCooldownMs: 120_000 }));
+  assert.equal(r.debounceSeconds, 0, '60 秒的默认值不能盖掉真实的 0');
+  assert.equal(r.globalCooldownSeconds, 120);
+  // 内部字段名不应泄漏到前端形状里
+  assert.equal(r.debounceMs, undefined, '前端不该看到毫秒字段名');
+  assert.equal(r.globalCooldownMs, undefined);
+});
+
+// ── E3: 字典 → 扁平键 ────────────────────────────────────────────────────
+test('E3: 按事件的字典映射回扁平键', () => {
+  const r = effectiveForClient(mkCfg({
+    audioSourceByKind: { done: 'tts', fail: 'system' },
+    ttsTexts: { done: '搞定啦' },
+    kindSystemSound: { fail: 'Hand' },
+    kindTtsVoice: { done: 'Microsoft Huihui Desktop' },
+    kindVoiceName: { question: 'ankomon' },
+    customFiles: { approval: 'D:\\a.wav' },
+  }));
+  // audioSourceByKind 两种形态都要有
+  assert.deepEqual(r.audioSourceByKind, { done: 'tts', fail: 'system' },
+    '字典形态要保留（GUI 的按事件覆盖读它）');
+  assert.equal(r.kindSourceFail, 'system', '扁平形态也要有（便于排查）');
+  assert.equal(r.kindSourceDone, 'tts');
+  assert.equal(r.ttsTextDone, '搞定啦');
+  assert.equal(r.kindSystemSoundFail, 'Hand');
+  assert.equal(r.kindTtsVoiceDone, 'Microsoft Huihui Desktop');
+  assert.equal(r.kindVoiceNameQuestion, 'ankomon');
+  assert.equal(r.customFileApproval, 'D:\\a.wav');
+});
+
+// ── E4: 空字典不产生多余的键 ──────────────────────────────────────────────
+test('E4: 字典为空时不产生扁平键（保持响应精简）', () => {
+  const r = effectiveForClient(mkCfg());
+  assert.deepEqual(r.audioSourceByKind, {});
+  assert.equal(r.kindSourceFail, undefined);
+  assert.equal(r.ttsTextDone, undefined);
+  assert.equal(r.kindSystemSoundFail, undefined);
+});
+
+// ── E5: 传 undefined / null 不崩（这就是那个忘传参数的 bug）───────────────
+test('E5: 传 undefined/null 时返回空对象而不是抛（防"忘传 cfg"）', () => {
+  for (const bad of [undefined, null, 0, '', 'x', []]) {
+    let r;
+    assert.doesNotThrow(() => { r = effectiveForClient(bad); },
+      `传 ${JSON.stringify(bad)} 不应抛`);
+    assert.equal(typeof r, 'object');
+    assert.ok(r !== null);
+  }
+});
+
+// ── E6: 忘传 cfg 的后果可被识别 ───────────────────────────────────────────
+test('E6: 忘传 cfg 时结果是"全空"，不是"看起来正常"', () => {
+  const empty = effectiveForClient();
+  // 关键：全空意味着所有值都是 undefined，
+  // 前端会因此回落到默认值 —— 这正是用户看到"改了没生效"的原因。
+  assert.equal(empty.volume, undefined);
+  // debounceSeconds 会算成 0（Number(undefined)||0 → 0），不是 undefined。
+  // 这反而是好事：宁可显示 0（关闭），也不要 NaN。
+  assert.equal(empty.debounceSeconds, 0);
+  assert.deepEqual(empty.audioSourceByKind, {});
+});
+
+// ── E7: 非法数值不产生 NaN ───────────────────────────────────────────────
+test('E7: 冷却值非法时归零而不是 NaN', () => {
+  for (const bad of [undefined, null, NaN, 'abc', -1]) {
+    const r = effectiveForClient(mkCfg({ debounceMs: bad }));
+    // 用 `=== 0` 而不是 assert.equal：-1/1000 四舍五入得 -0，
+    // 而 Node 的严格断言把 -0 与 0 视为不同（Object.is 语义）。
+    assert.ok(r.debounceSeconds === 0,
+      `debounceMs=${String(bad)} 应归零，实际 ${String(r.debounceSeconds)}`);
+    assert.ok(Number.isFinite(r.debounceSeconds), '不该出现 NaN');
+  }
+});

package/test/fail-route.test.mjs

@@ -0,0 +1,128 @@
+/**
+ * dsh-notify-desktop「运行时路由」测试 —— v0.3.1。
+ *
+ * 与另外两个测试文件的分工：
+ *  - `fail-voice.test.mjs`：真跑 ps1，验**池选择**与语义护栏（但用的是自己传的 -Kind）。
+ *  - 本文件：验 **lib/index.js 运行时到底给 ps1 传了什么 -Kind**
+ *    ——即"error 回合真的会走 fail 池吗"这条**端到端接线**。
+ *
+ * 为什么必须单独验：`fail-voice.test.mjs` 的 A1 只读**源码文本**（`psKind = 'fail'`），
+ * 证明不了"事件进来后实际传出的参数就是 fail"。这两者之间隔着
+ * `handleDone` 的分支选择 + `emitDone`/`notify` 的参数透传，任一环写错都会让
+ * 失败语音静默失效，而纯文本断言**照样全绿**。
+ *
+ * 隔离手法：用 `--import` 前置的 loader stub 替换 `node:child_process`，
+ * 让 spawn 只记录参数、**不起进程**（不弹 Toast、不出声、不依赖 SystemRoot）。
+ * 见 `stub-child-process.mjs` 的注释；踩坑 #424 的教训是别在这里设 SystemRoot。
+ *
+ * ⚠️ 运行方式：本文件需要 `--import` loader，**不能用默认 `node --test`**。
+ * 用专用脚本 `npm run test:route`，或：
+ *   node --import ./test/route-loader-register.mjs --test test/fail-route.test.mjs
+ * 为免误跑，默认的 `node --test` 会跳过它（本文件首个用例会检测并 skip）。
+ *
+ * 运行：npm run test:route
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PLUGIN = join(HERE, '..');
+
+// ⚠️ 必须在 import lib/index.js **之前**把 DSH_HOME 指到空目录。
+//
+// 为什么：插件启动时会读 `$DSH_HOME/storages/dsh-notify-desktop/config.json`
+// 作为"运行时覆盖层"，其优先级**高于** apply() 传入的 config。
+// 如果测试用真实 DSH_HOME，用户只要在 GUI 里改过任何一项
+// （实测：把 notifyOnAborted 打开），R4「aborted 默认不播」就会失败——
+// 那是用户配置导致的，不是代码缺陷。测试必须与用户真实配置隔离。
+const ISOLATED_HOME = mkdtempSync(join(tmpdir(), 'notify-route-home-'));
+process.env.DSH_HOME = ISOLATED_HOME;
+process.on('exit', () => {
+  try { rmSync(ISOLATED_HOME, { recursive: true, force: true }); } catch { /* best effort */ }
+});
+
+/** 只有 loader 生效时 `__SPAWN_CALLS` 才可能被写入；否则说明没用 --import 跑。 */
+function stubActive() {
+  return globalThis.__STUB_CHILD_PROCESS__ === true;
+}
+
+/** 造最小 ctx 替身。 */
+function mkCtx() {
+  const handlers = new Map();
+  return {
+    handlers,
+    on(name, fn) { if (!handlers.has(name)) handlers.set(name, []); handlers.get(name).push(fn); },
+    get() { return undefined; },
+    effect(fn) { const d = fn(); return () => { if (typeof d === 'function') d(); }; },
+    emit(name, ...args) { for (const fn of handlers.get(name) || []) fn(...args); },
+  };
+}
+
+function mkAgent(id, { origin, parentSession, status = 'idle' } = {}) {
+  return { id, status, session: { id, header: { id, origin, parentSession } } };
+}
+
+/** 从记录的 spawn 调用里取出所有传给 ps1 的 -Kind 值。 */
+function kindsOf(calls) {
+  const out = [];
+  for (const c of calls || []) {
+    const args = Array.isArray(c.args) ? c.args : [];
+    const i = args.indexOf('-Kind');
+    if (i >= 0 && i + 1 < args.length) out.push(String(args[i + 1]));
+  }
+  return out;
+}
+
+/** 跑一次「turn/end(kind) + agent 状态 running→idle」并返回本次 spawn 的 -Kind 列表。 */
+async function runTurnAndCollectKind(turnKind, { idleGate = true, subagents = false } = {}) {
+  // 每次重新 import 会命中模块缓存，apply 可重复调用（插件本就是可多次 apply 的）
+  const { apply } = await import('../lib/index.js');
+  const agent = mkAgent('sess-1', { status: 'running' });
+  const ctx = mkCtx();
+  globalThis.__SPAWN_CALLS = [];
+  apply(ctx, { idleGate, subagents, voice: true, volume: 0 });
+  ctx.emit('session/event', agent.session, { type: 'turn/end', data: { turn: 1, reason: { kind: turnKind } } });
+  agent.status = 'idle';
+  ctx.emit('agent/status', { agent, status: 'running' });
+  ctx.emit('agent/status', { agent, status: 'idle' });
+  // spawn 是同步调用（fire-and-forget），无需等待
+  return kindsOf(globalThis.__SPAWN_CALLS);
+}
+
+test('R0: loader stub 生效（否则本文件的断言无意义）', { skip: !process.env.DSH_ROUTE_LOADER && '需 npm run test:route（带 --import loader）；默认 node --test 跳过' }, () => {
+  assert.equal(stubActive(), true, 'stub 未生效：必须用 npm run test:route 跑');
+});
+
+test('R1: error 回合 → ps1 收到 -Kind fail（exact，不是 chime）', { skip: !process.env.DSH_ROUTE_LOADER && '需 npm run test:route' }, async () => {
+  const kinds = await runTurnAndCollectKind('error');
+  assert.deepEqual(kinds, ['fail'], `error 应传出 ['fail']，实际 ${JSON.stringify(kinds)}`);
+  // 负例：绝不能还是 chime（那正是本次要改掉的旧行为）
+  assert.ok(!kinds.includes('chime'), 'error 不应再传 chime');
+});
+
+test('R2: blocked 回合 → ps1 收到 -Kind chime（维持蜂鸣，语义不同）', { skip: !process.env.DSH_ROUTE_LOADER && '需 npm run test:route' }, async () => {
+  const kinds = await runTurnAndCollectKind('blocked');
+  assert.deepEqual(kinds, ['chime'], `blocked 应传出 ['chime']，实际 ${JSON.stringify(kinds)}`);
+  assert.ok(!kinds.includes('fail'), 'blocked 不应传 fail（它是"被拦下"不是"失败"）');
+});
+
+test('R3: completed 回合（无在飞工作）→ ps1 收到 -Kind done', { skip: !process.env.DSH_ROUTE_LOADER && '需 npm run test:route' }, async () => {
+  const kinds = await runTurnAndCollectKind('completed');
+  assert.deepEqual(kinds, ['done'], `completed 应传出 ['done']，实际 ${JSON.stringify(kinds)}`);
+});
+
+test('R4: aborted 回合 → 默认不播（无 spawn 调用）', { skip: !process.env.DSH_ROUTE_LOADER && '需 npm run test:route' }, async () => {
+  const kinds = await runTurnAndCollectKind('aborted');
+  assert.deepEqual(kinds, [], `aborted 默认静默，实际 ${JSON.stringify(kinds)}`);
+});
+
+test('R5: error 在 idleGate=true 下**立即**播（不过空闲门）', { skip: !process.env.DSH_ROUTE_LOADER && '需 npm run test:route' }, async () => {
+  // 即便开着空闲门，error 也必须立刻出声（失败要马上知道）——本用例断言"有 spawn 发出"，
+  // 即没有被挂起吞掉。挂起路径不会调 notify()，故 spawn 计数为 0 就说明被吞了。
+  const kinds = await runTurnAndCollectKind('error', { idleGate: true });
+  assert.deepEqual(kinds, ['fail'], `error 开着空闲门也应立即播出 ['fail']，实际 ${JSON.stringify(kinds)}`);
+});