dsh-notify-say 0.4.21 → 0.4.25

package/test/session-jump.test.mjs

@@ -0,0 +1,266 @@
+/**
+ * session-jump 测试：四种「跳转时机」组合的穷举验证。
+ *
+ * 这块的价值全在**不误跳**：跳错了会盖掉用户正在看的会话、抢走他自己点开的对话。
+ *
+ * 用户 2026-10-17 明确要求做成**两个独立开关**，因为他发现不同人诉求相反：
+ *   - 有人想"后台完成→回来就跳"
+ *   - 有人**故意不跳**，想自己回来按绿点逐个确认
+ *   - 有人希望"前台完成也跳，让我看一眼"
+ * 所以实现不该替用户选，而要把四种组合都支持。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  decideJump, JUMP_DECISIONS, DEFAULT_JUMP, isHidden, createLeaveTracker,
+} from '../lib/session-jump.js';
+
+const T0 = 1790000000000;
+
+/** 后台完成：用户先离开（T0-1000），通知后到（T0）。 */
+function bg(over) {
+  return {
+    jumpWhenBackground: true,
+    jumpWhenForeground: false,
+    consumed: false,
+    sessionId: 'sess-1',
+    notifiedAt: T0,
+    leftAt: T0 - 1000,
+    ...over,
+  };
+}
+
+/** 前台完成：通知先到（T0-5000），用户后离开（T0）。 */
+function fg(over) {
+  return {
+    jumpWhenBackground: true,
+    jumpWhenForeground: false,
+    consumed: false,
+    sessionId: 'sess-1',
+    notifiedAt: T0 - 5000,
+    leftAt: T0,
+    ...over,
+  };
+}
+
+// ── J1: 组合①（默认）后台跳、前台不跳 ─────────────────────────────────────
+test('J1: 组合① 后台→跳 / 前台→不跳（默认）', () => {
+  const b = decideJump(bg());
+  assert.equal(b.jump, true);
+  assert.equal(b.phase, 'background');
+
+  const f = decideJump(fg());
+  assert.equal(f.jump, false);
+  assert.equal(f.decision, JUMP_DECISIONS.SKIP_FOREGROUND);
+  assert.equal(f.phase, 'foreground');
+
+  // 默认值本身也要对
+  assert.equal(DEFAULT_JUMP.jumpWhenBackground, true);
+  assert.equal(DEFAULT_JUMP.jumpWhenForeground, false);
+});
+
+// ── J2: 组合② 都跳 ────────────────────────────────────────────────────────
+test('J2: 组合② 后台和前台都跳', () => {
+  const o = { jumpWhenBackground: true, jumpWhenForeground: true };
+  assert.equal(decideJump(bg(o)).jump, true);
+  const f = decideJump(fg(o));
+  assert.equal(f.jump, true);
+  assert.equal(f.phase, 'foreground');
+});
+
+// ── J3: 组合③ 只前台跳 ────────────────────────────────────────────────────
+test('J3: 组合③ 只前台跳（少见但允许）', () => {
+  const o = { jumpWhenBackground: false, jumpWhenForeground: true };
+  const b = decideJump(bg(o));
+  assert.equal(b.jump, false);
+  assert.equal(b.decision, JUMP_DECISIONS.SKIP_BACKGROUND);
+
+  assert.equal(decideJump(fg(o)).jump, true);
+});
+
+// ── J4: 组合④ 都不跳 ──────────────────────────────────────────────────────
+test('J4: 组合④ 都不跳（想自己按绿点确认的人）', () => {
+  const o = { jumpWhenBackground: false, jumpWhenForeground: false };
+  const b = decideJump(bg(o));
+  const f = decideJump(fg(o));
+  assert.equal(b.jump, false);
+  assert.equal(f.jump, false);
+  assert.equal(b.decision, JUMP_DECISIONS.SKIP_DISABLED);
+  assert.equal(f.decision, JUMP_DECISIONS.SKIP_DISABLED);
+});
+
+// ── J5: 10 分钟后回来仍然跳（不设时效）────────────────────────────────────
+test('J5: 隔很久才回来看，仍然跳（结果还没看过）', () => {
+  const tenMin = 10 * 60 * 1000;
+  assert.equal(decideJump(bg({ leftAt: T0 - tenMin })).jump, true);
+  const oneHour = 60 * 60 * 1000;
+  assert.equal(decideJump(bg({ leftAt: T0 - oneHour })).jump, true);
+});
+
+// ── J6: 缺省参数按默认语义 ────────────────────────────────────────────────
+test('J6: 不传开关时按默认（后台跳、前台不跳）', () => {
+  const b = decideJump({ consumed: false, sessionId: 's', notifiedAt: T0, leftAt: T0 - 1 });
+  assert.equal(b.jump, true, '未指定开关时默认后台跳');
+  const f = decideJump({ consumed: false, sessionId: 's', notifiedAt: T0 - 10, leftAt: T0 });
+  assert.equal(f.jump, false, '未指定开关时默认前台不跳');
+});
+
+// ── J7: 无待跳转 / 已消费 ─────────────────────────────────────────────────
+test('J7: 没有待跳转会话、或已消费时都不跳（防重复）', () => {
+  assert.equal(decideJump(bg({ sessionId: '' })).decision, JUMP_DECISIONS.SKIP_NO_PENDING);
+  assert.equal(decideJump(bg({ sessionId: undefined })).jump, false);
+  assert.equal(decideJump(bg({ consumed: true })).decision, JUMP_DECISIONS.SKIP_CONSUMED);
+});
+
+// ── J8: 不知道何时离开 → 保守不跳 ─────────────────────────────────────────
+test('J8: 无法得知用户何时离开时不跳（宁可漏跳，不可乱跳）', () => {
+  assert.equal(decideJump(bg({ leftAt: 0 })).decision, JUMP_DECISIONS.SKIP_UNKNOWN_LEFT);
+  assert.equal(decideJump(bg({ leftAt: undefined })).jump, false);
+  assert.equal(decideJump(bg({ leftAt: NaN })).jump, false);
+});
+
+// ── J9: 边界 —— 通知与离开同一毫秒 ───────────────────────────────────────
+test('J9: 通知时刻 == 离开时刻 视为后台（>=）', () => {
+  const r = decideJump(bg({ notifiedAt: T0, leftAt: T0 }));
+  assert.equal(r.jump, true);
+  assert.equal(r.phase, 'background');
+});
+
+// ── J10: 异常输入不崩 ────────────────────────────────────────────────────
+test('J10: 空/异常输入一律安全返回不跳', () => {
+  assert.doesNotThrow(() => decideJump());
+  assert.doesNotThrow(() => decideJump(null));
+  assert.doesNotThrow(() => decideJump({}));
+  assert.equal(decideJump(undefined).jump, false);
+  assert.equal(decideJump({}).jump, false);
+});
+
+// ── J11: isHidden 归一 ───────────────────────────────────────────────────
+test('J11: isHidden 兼容多种文档形态', () => {
+  assert.equal(isHidden({ visibilityState: 'hidden' }), true);
+  assert.equal(isHidden({ visibilityState: 'visible' }), false);
+  assert.equal(isHidden({ hidden: true }), true);
+  assert.equal(isHidden({ hidden: false }), false);
+  assert.equal(isHidden(null), true);
+  assert.equal(isHidden({}), false);
+});
+
+// ── J12: leaveTracker 只在"变为隐藏"的边沿记录 ──────────────────────────
+test('J12: leaveTracker 记录离开时刻，且不重复刷新', () => {
+  const tr = createLeaveTracker();
+  tr.onVisibility({ visibilityState: 'visible' }, T0);
+  assert.equal(tr.leftAt(), 0, '一直可见时没有离开时刻');
+
+  tr.onVisibility({ visibilityState: 'hidden' }, T0 + 1000);
+  assert.equal(tr.leftAt(), T0 + 1000);
+
+  tr.onVisibility({ visibilityState: 'hidden' }, T0 + 2000);
+  assert.equal(tr.leftAt(), T0 + 1000, '持续隐藏不应刷新');
+
+  tr.onVisibility({ visibilityState: 'visible' }, T0 + 3000);
+  assert.equal(tr.leftAt(), T0 + 1000, '回来后保留');
+
+  tr.onVisibility({ visibilityState: 'hidden' }, T0 + 9000);
+  assert.equal(tr.leftAt(), T0 + 9000, '再次离开要刷新');
+
+  tr.reset();
+  assert.equal(tr.leftAt(), 0, 'reset 后清零');
+});
+
+// ── J13: 端到端 —— 后台完成 → 回来 → 跳 ──────────────────────────────────
+test('J13: 端到端时序：离开 → 通知 → 回来 → 跳', () => {
+  const tr = createLeaveTracker();
+  tr.onVisibility({ visibilityState: 'hidden' }, T0);
+  const notifiedAt = T0 + 5000;
+  tr.onVisibility({ visibilityState: 'visible' }, T0 + 6000);
+
+  const r = decideJump({
+    jumpWhenBackground: true, jumpWhenForeground: false,
+    consumed: false, sessionId: 'sess-x',
+    notifiedAt, leftAt: tr.leftAt(),
+  });
+  assert.equal(r.jump, true);
+  assert.equal(r.phase, 'background');
+});
+
+// ── J14: 端到端 —— 前台完成 → 看过后离开再回来 → 不跳 ──────────────────────
+test('J14: 端到端时序：前台完成 → 离开再回来 → 默认不跳', () => {
+  const tr = createLeaveTracker();
+  tr.onVisibility({ visibilityState: 'visible' }, T0);
+  const notifiedAt = T0 + 1000;
+  tr.onVisibility({ visibilityState: 'hidden' }, T0 + 3000);
+  tr.onVisibility({ visibilityState: 'visible' }, T0 + 5000);
+
+  const r = decideJump({
+    jumpWhenBackground: true, jumpWhenForeground: false,
+    consumed: false, sessionId: 'sess-y',
+    notifiedAt, leftAt: tr.leftAt(),
+  });
+  assert.equal(r.jump, false);
+  assert.equal(r.phase, 'foreground');
+  assert.equal(r.decision, JUMP_DECISIONS.SKIP_FOREGROUND);
+});
+
+// ── J15: 回归 —— "离开过一次"不能让前台判定永久失效 ────────────────────────
+// 独立审查 2026-10-17 指出的严重缺陷：第一版只记 leftAt（离开时刻），
+// 于是用户离开过一次之后，leftAt 永远是旧值，此后任何通知都满足
+// notifiedAt >= leftAt → 被判成"后台完成" → 在用户眼前强行跳转。
+// 修法：同时记 returnedAt，用区间 [leftAt, returnedAt) 判定。
+test('J15: 离开过一次后回来的通知，不应被判成后台（关键回归）', () => {
+  const tr = createLeaveTracker();
+  // 用户在 T0 离开
+  tr.onVisibility({ visibilityState: 'hidden' }, 1000);
+  // 在 T0+5000 回来
+  tr.onVisibility({ visibilityState: 'visible' }, 5000);
+  // 回来后、正看着时，T0+9000 来了新通知
+  const r = decideJump({
+    jumpWhenBackground: true,
+    jumpWhenForeground: false,     // 默认：前台不跳
+    consumed: false,
+    sessionId: 's',
+    notifiedAt: 9000,
+    leftAt: tr.leftAt(),           // = 1000
+    returnedAt: tr.returnedAt(),   // = 5000
+  });
+  assert.equal(r.phase, 'foreground', '通知在回来之后到达，属于前台');
+  assert.equal(r.jump, false, '前台不该跳 —— 第一版在这里会误跳');
+});
+
+// ── J16: 离开期间到达的通知仍然算后台 ─────────────────────────────────────
+test('J16: 离开期间到达的通知仍判为后台', () => {
+  const tr = createLeaveTracker();
+  tr.onVisibility({ visibilityState: 'hidden' }, 1000);
+  tr.onVisibility({ visibilityState: 'visible' }, 9000);
+  const r = decideJump({
+    jumpWhenBackground: true,
+    jumpWhenForeground: false,
+    consumed: false,
+    sessionId: 's',
+    notifiedAt: 5000,              // 在 1000..9000 之间
+    leftAt: tr.leftAt(),
+    returnedAt: tr.returnedAt(),
+  });
+  assert.equal(r.phase, 'background');
+  assert.equal(r.jump, true);
+});
+
+// ── J17: tracker 正确记录回归时刻 ─────────────────────────────────────────
+test('J17: leaveTracker 记录 returnedAt，并在再次离开时清掉', () => {
+  const tr = createLeaveTracker();
+  tr.onVisibility({ visibilityState: 'visible' }, 0);
+  assert.equal(tr.returnedAt(), 0, '从未离开过 → 没有回归时刻');
+
+  tr.onVisibility({ visibilityState: 'hidden' }, 1000);
+  assert.equal(tr.returnedAt(), 0, '离开后还没回来');
+
+  tr.onVisibility({ visibilityState: 'visible' }, 5000);
+  assert.equal(tr.returnedAt(), 5000, '回来时记录时刻');
+
+  tr.onVisibility({ visibilityState: 'hidden' }, 8000);
+  assert.equal(tr.returnedAt(), 0, '再次离开要把旧的回来说明作废');
+
+  tr.reset();
+  assert.equal(tr.leftAt(), 0);
+  assert.equal(tr.returnedAt(), 0);
+});

package/test/stub-child-process.mjs

@@ -0,0 +1,43 @@
+/**
+ * ESM loader stub：把 `node:child_process` 换成记录型假实现。
+ *
+ * 用途：`test/fail-route.test.mjs` 要断言 **lib/index.js 运行时到底给 ps1 传了什么参数**
+ * （例如 error 回合是否真的传 `-Kind fail`）。若真去 spawn PowerShell：
+ * ① 会弹 Toast / 出声，污染用户桌面；② 需要真实 SystemRoot，与同目录其他测试的
+ * 隔离手法冲突（见踩坑 #424）。故在加载 lib 之前把这个模块注册为 loader，
+ * 让 `spawn()` 只把参数记进 `globalThis.__SPAWN_CALLS`，不起任何进程。
+ *
+ * 为什么不用 monkey-patch：lib 用的是 ESM 具名导入
+ * （`import { spawn } from 'node:child_process'`），导入绑定只读、不可重新赋值；
+ * 只有 loader 层能在模块解析阶段替换它。
+ *
+ * 该文件**不是测试文件**（不以 .test. 命名），不会被 `node --test` 当用例执行。
+ */
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier === 'node:child_process') {
+    return { url: 'stub:child_process', shortCircuit: true };
+  }
+  return nextResolve(specifier, context);
+}
+
+export async function load(url, context, nextLoad) {
+  if (url === 'stub:child_process') {
+    const source = `
+      // 记录每一次 spawn 的 (file, args) 供断言；返回一个不会真的启动进程的假句柄。
+      export function spawn(file, args, options) {
+        globalThis.__SPAWN_CALLS = globalThis.__SPAWN_CALLS || [];
+        globalThis.__SPAWN_CALLS.push({ file, args: Array.isArray(args) ? args.slice() : args, options });
+        return {
+          pid: 424242,
+          once() { return this; },
+          on() { return this; },
+          kill() { return true; },
+          unref() { return this; },
+        };
+      }
+      export default { spawn };
+    `;
+    return { format: 'module', shortCircuit: true, source };
+  }
+  return nextLoad(url, context);
+}

package/test/tts-lines.test.mjs

@@ -0,0 +1,112 @@
+/**
+ * tts-lines 测试：台词选取与自定义文本校验。
+ *
+ * 覆盖用户 2026-10-17 的两个要求：
+ *   1. "台词随机" —— 不要把同一句念一天
+ *   2. "用户能不能自己输一段话" —— 可以，但有长度和格式限制
+ *
+ * 校验部分尤其重要：自定义文本会经 spawn argv 传给 PowerShell 再交给 SAPI。
+ * 虽然 argv 不经 shell 解释（无注入风险），但**超长文本**会让合成拖很久、
+ * **换行与控制字符**会让断句怪异，都必须挡掉。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  DEFAULT_LINES, FALLBACK_LINE, MAX_TEXT_LEN,
+  sanitizeTtsText, pickTtsText,
+} from '../lib/tts-lines.js';
+
+// ── T1: 内置库覆盖五种事件且每种多条 ──────────────────────────────────────
+test('T1: 内置台词库覆盖五种事件，每种至少 2 条', () => {
+  for (const kind of ['done', 'fail', 'question', 'approval', 'blocked']) {
+    const pool = DEFAULT_LINES[kind];
+    assert.ok(Array.isArray(pool), `${kind} 应有台词库`);
+    assert.ok(pool.length >= 2, `${kind} 至少 2 条才谈得上"随机"`);
+    for (const s of pool) {
+      assert.ok(typeof s === 'string' && s.length > 0, `${kind} 的台词不应为空`);
+      assert.doesNotMatch(s, /主人/, `${kind} 的台词不该含"主人"`);
+    }
+  }
+});
+
+// ── T2: 随机确实会取到不同条目 ────────────────────────────────────────────
+test('T2: 随机源不同则取到不同台词', () => {
+  const kind = 'done';
+  const pool = DEFAULT_LINES[kind];
+  // 用确定性的 rand 走遍所有下标
+  const seen = new Set();
+  for (let i = 0; i < pool.length; i++) {
+    const r = (i + 0.5) / pool.length;      // 落在第 i 个区间
+    seen.add(pickTtsText(kind, {}, () => r));
+  }
+  assert.equal(seen.size, pool.length, '每个下标都应能取到不同台词');
+});
+
+// ── T3: 随机源异常时兜底到第一条，不崩 ────────────────────────────────────
+test('T3: 随机源返回异常值时不崩、退回第一条', () => {
+  for (const bad of [() => NaN, () => -1, () => 99, () => { throw new Error('x'); }]) {
+    let got;
+    assert.doesNotThrow(() => { got = pickTtsText('done', {}, bad); });
+    assert.equal(got, DEFAULT_LINES.done[0]);
+  }
+});
+
+// ── T4: 未知事件类型用兜底句 ──────────────────────────────────────────────
+test('T4: 未知事件类型返回兜底句', () => {
+  assert.equal(pickTtsText('nonsense', {}), FALLBACK_LINE);
+  assert.equal(pickTtsText('', {}), FALLBACK_LINE);
+  assert.equal(pickTtsText(null, {}), FALLBACK_LINE);
+});
+
+// ── T5: 自定义台词优先于内置库 ────────────────────────────────────────────
+test('T5: 用户自定义台词优先', () => {
+  const cfg = { ttsTexts: { done: '我自己的台词' } };
+  assert.equal(pickTtsText('done', cfg), '我自己的台词');
+  // 未自定义的事件仍用内置库
+  assert.ok(DEFAULT_LINES.fail.includes(pickTtsText('fail', cfg)));
+});
+
+// ── T6: 空白自定义等于没自定义 ────────────────────────────────────────────
+test('T6: 空白自定义退回内置库', () => {
+  for (const blank of ['', '   ', '\n\t', undefined, null, 123]) {
+    const got = pickTtsText('done', { ttsTexts: { done: blank } }, () => 0);
+    assert.equal(got, DEFAULT_LINES.done[0], `空白值 ${JSON.stringify(blank)} 应退回内置库`);
+  }
+});
+
+// ── T7: 自定义文本的清洗 ──────────────────────────────────────────────────
+test('T7: 自定义文本会去掉换行与控制字符并压空白', () => {
+  assert.equal(sanitizeTtsText('  你好  '), '你好');
+  assert.equal(sanitizeTtsText('第一行\n第二行'), '第一行 第二行');
+  assert.equal(sanitizeTtsText('a\tb\r\nc'), 'a b c');
+  assert.equal(sanitizeTtsText('a\u0000b'), 'a b');
+  // 全角空格等不应被误删
+  assert.equal(sanitizeTtsText('你好 世界'), '你好 世界');
+});
+
+// ── T8: 超长文本被截断 ────────────────────────────────────────────────────
+test('T8: 超长自定义文本被截断到上限', () => {
+  const long = '很'.repeat(MAX_TEXT_LEN + 50);
+  const out = sanitizeTtsText(long);
+  assert.equal(out.length, MAX_TEXT_LEN, `应截断到 ${MAX_TEXT_LEN} 字`);
+  assert.ok(out.startsWith('很'), '截断后内容应保持');
+});
+
+// ── T9: 非字符串输入一律当作"未设置" ──────────────────────────────────────
+test('T9: 非字符串输入返回空串（表示未设置）', () => {
+  for (const v of [123, true, {}, [], null, undefined, () => {}]) {
+    assert.equal(sanitizeTtsText(v), '', `${typeof v} 应返回空串`);
+  }
+});
+
+// ── T10: 台词长度适合"一句话提醒" ─────────────────────────────────────────
+test('T10: 内置台词都足够短（念完约 5 秒内）', () => {
+  for (const [kind, pool] of Object.entries(DEFAULT_LINES)) {
+    for (const s of pool) {
+      assert.ok(s.length <= MAX_TEXT_LEN, `${kind} 的台词过长：${s}`);
+      // 经验值：中文 TTS 约 4 字/秒，所以 20 字上下最舒服
+      assert.ok(s.length <= 30, `${kind} 的台词建议不超过 30 字：${s}`);
+    }
+  }
+});

package/test/version-consistency.test.mjs

@@ -0,0 +1,98 @@
+/**
+ * 版本号一致性检查（v0.4.19）。
+ *
+ * ## 为什么需要这条检查
+ *
+ * 用户 2026-10-18 第三次指出："我感觉你的版本号经常会慢一点。"
+ *
+ * 确实如此。已发生 3 次：
+ *   · v0.4.13~15 只在**提交说明**里写了版本号，没改 package.json
+ *   · v0.4.17~18 又漏了两次，代码到 0.4.18 时文件还写 0.4.16
+ *
+ * 后果不是"难看"，而是**实质性的误导**：
+ *   · 插件管理页面显示 0.4.12，用户以为重启没生效
+ *   · 我判断"宿主加载了哪一版"时被这个数字骗过
+ *   · 排查时无法用版本号区分代码状态
+ *
+ * ## 为什么靠检查而不是靠"记得"
+ *
+ * 已经漏了 3 次，说明"提交前记得改"不可靠。
+ * 这条测试纳入 `npm run test:all`，改代码忘了升版本就会红。
+ *
+ * ## 检查什么
+ *
+ * 1. package.json 的 version 必须符合 semver
+ * 2. 源码里如果有版本标记（如注释里的 v0.4.x），不能高于 package.json
+ * 3. CHANGELOG（若有）的最新条目不能高于 package.json
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
+
+/** 把 "0.4.18" 解析成可比较的数字数组。 */
+function parseSemver(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v || ''));
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** a > b 返回 true。 */
+function gt(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return true;
+    if (a[i] < b[i]) return false;
+  }
+  return false;
+}
+
+// ── A1: version 必须是合法 semver ────────────────────────────────────────
+test('A1: package.json 的 version 是合法 semver', () => {
+  assert.ok(pkg.version, 'package.json 必须有 version');
+  const v = parseSemver(pkg.version);
+  assert.ok(v !== null, `version 不合法: ${pkg.version}`);
+  assert.ok(v[0] >= 0 && v[1] >= 0 && v[2] >= 0);
+});
+
+// ── A2: 源码里的版本标记不能超过 package.json ────────────────────────────
+test('A2: 源码注释里的 v0.4.x 标记不高于 package.json 的 version', () => {
+  const vPkg = parseSemver(pkg.version);
+  assert.ok(vPkg, 'version 无法解析');
+
+  // 扫描主要源码文件里出现的 v0.4.N 标记
+  const files = ['lib/index.js', 'lib/client.js', 'lib/config-store.js',
+    'lib/config-schema.js', 'dsh-notify.ps1', 'lib/wav-gain.ps1'];
+  const tooHigh = [];
+  for (const rel of files) {
+    const p = join(ROOT, rel);
+    if (!existsSync(p)) continue;
+    const src = readFileSync(p, 'utf8');
+    // 只认 v0.4.N 这种明确的版本标记
+    const re = /\bv0\.4\.(\d+)\b/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+      const n = Number(m[1]);
+      if (n > vPkg[2]) tooHigh.push(`${rel} 提到 v0.4.${n}`);
+    }
+  }
+  assert.deepEqual(tooHigh, [],
+    `源码里出现了高于 package.json (${pkg.version}) 的版本标记 —— `
+    + '说明改了代码但忘了升版本号：\n  ' + tooHigh.join('\n  '));
+});
+
+// ── A3: CHANGELOG 最新条目不能高于 package.json ──────────────────────────
+test('A3: CHANGELOG（若有）最新版本不高于 package.json', () => {
+  const p = join(ROOT, 'CHANGELOG.md');
+  if (!existsSync(p)) return;   // 还没建 CHANGELOG 时跳过
+  const text = readFileSync(p, 'utf8');
+  const m = /##\s*\[?v?(\d+\.\d+\.\d+)/.exec(text);
+  if (!m) return;
+  const vLog = parseSemver(m[1]);
+  const vPkg = parseSemver(pkg.version);
+  assert.ok(vLog && vPkg);
+  assert.ok(!gt(vLog, vPkg),
+    `CHANGELOG 最新是 ${m[1]}，高于 package.json 的 ${pkg.version}`);
+});

package/test/voice-availability.test.mjs

@@ -0,0 +1,90 @@
+/**
+ * 语音包可用性判定测试（v0.4.15）。
+ *
+ * ## 这里踩过的坑
+ *
+ * 用户选 `audioSource=bundled`，实际播放的却是系统蜂鸣。
+ * 诊断日志显示：
+ *
+ *   `[voice-check] exists=true wav=-3 dir=E:\...\sounds\voice-lines`
+ *
+ * `existsSync` 为 true，但 `readdirSync` **抛异常**（-3 是 catch 标记）。
+ * 原因是**宿主进程运行在沙箱里，fs 读取受限**；而 `dsh-notify.ps1`
+ * 是独立子进程、不受此约束 —— 所以 ps1 明明能读到 103 个 wav 并正常播放，
+ * 宿主却判定"没有语音包"，把用户主动选择降级成了蜂鸣。
+ *
+ * ## 核心原则
+ *
+ * **判断不了 ≠ 没有。** 只有"目录明确不存在"才是确定的坏状态；
+ * 读取失败必须乐观放行，由真正能读的 ps1 裁决。
+ *
+ * 这些用例直接测 `effectiveSource` 的回退链——它是"选语音包却听蜂鸣"的决策点。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { effectiveSource, resolveSource } from '../lib/audio-source.js';
+
+// ── V1: 判定为可用时必须保持 bundled，绝不回退 ────────────────────────────
+test('V1: hasBundledVoice=true 时保持 bundled（不回退到 system）', () => {
+  const r = effectiveSource('bundled', {
+    hasTtsVoice: true, hasBundledVoice: true, hasCustomFile: false,
+  });
+  assert.equal(r.source, 'bundled', '用户选了语音包就该放语音包');
+  assert.equal(r.fellBack, false, '不该发生回退');
+  assert.equal(r.from, 'bundled');
+});
+
+// ── V2: 确实没有语音包时才回退（这是正确的降级）──────────────────────────
+test('V2: hasBundledVoice=false 时回退到 system', () => {
+  const r = effectiveSource('bundled', {
+    hasTtsVoice: true, hasBundledVoice: false, hasCustomFile: false,
+  });
+  assert.equal(r.source, 'system');
+  assert.equal(r.fellBack, true);
+});
+
+// ── V3: 关键——"读取失败"必须传 true，不能传 false ─────────────────────────
+// hasVoiceLine 在 readdirSync 抛异常时应返回 true。这里锁住它的后果：
+// 只要传 true，就不会降级成蜂鸣。
+test('V3: 沙箱读不到文件时（应传 true）不会降级为蜂鸣', () => {
+  // 模拟 hasVoiceLine 修复后的返回值：读不了 -> true
+  const readFailedAssumeYes = true;
+  const r = effectiveSource('bundled', {
+    hasTtsVoice: true,
+    hasBundledVoice: readFailedAssumeYes,
+    hasCustomFile: false,
+  });
+  assert.equal(r.source, 'bundled',
+    '读不到不等于没有；降级会把用户选的语音包变成蜂鸣（实测事故）');
+});
+
+// ── V4: resolveSource 在无覆盖时返回全局 bundled ──────────────────────────
+test('V4: 无按事件覆盖时 resolveSource 返回全局音源', () => {
+  assert.equal(resolveSource('done', { audioSource: 'bundled', audioSourceByKind: {} }), 'bundled');
+  assert.equal(resolveSource('fail', { audioSource: 'bundled' }), 'bundled');
+});
+
+// ── V5: 按事件覆盖优先于全局（且不影响其它事件）──────────────────────────
+test('V5: 按事件覆盖只作用于该事件', () => {
+  const cfg = { audioSource: 'bundled', audioSourceByKind: { fail: 'system' } };
+  assert.equal(resolveSource('done', cfg), 'bundled', 'done 仍用语音包');
+  assert.equal(resolveSource('fail', cfg), 'system', 'fail 用系统音');
+});
+
+// ── V6: 回退链最终不会返回空 ──────────────────────────────────────────────
+test('V6: 任何组合下 effectiveSource 都返回合法音源', () => {
+  const sources = ['tts', 'bundled', 'system', 'custom', 'none'];
+  const avails = [
+    { hasTtsVoice: true, hasBundledVoice: true, hasCustomFile: true },
+    { hasTtsVoice: true, hasBundledVoice: false, hasCustomFile: false },
+    { hasTtsVoice: false, hasBundledVoice: false, hasCustomFile: false },
+  ];
+  for (const src of sources) {
+    for (const av of avails) {
+      const r = effectiveSource(src, av);
+      assert.ok(sources.includes(r.source),
+        `${src} + ${JSON.stringify(av)} 返回了非法音源: ${r.source}`);
+    }
+  }
+});