dsh-notify-say 0.4.21 → 0.4.25

package/test/client-contract.test.mjs

@@ -0,0 +1,118 @@
+/**
+ * 客户端代码的静态契约测试（v0.4.23）。
+ *
+ * ## 为什么需要这一类测试
+ *
+ * 2026-10-18 外部代码审阅发现：`consumeLastSession()` 返回**字符串**，
+ * 调用方却按 `doc.sessionId` 访问 —— 类型不匹配，导致**会话跳转功能
+ * 从未生效过**，而且服务端信号已被 consume 清除，连重试机会都没有。
+ *
+ * 这类 bug 的特点：
+ *   · 两端各自"看起来都对"
+ *   · 跑起来不报错（只是静默不生效）
+ *   · 没有端到端测试就发现不了
+ *
+ * 所以这里用**源码静态断言**锁住契约。不是替代运行时测试，
+ * 而是防止"改一处忘另一处"的回归。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CLIENT = join(ROOT, 'lib', 'client.js');
+const NOTIFY_CONFIG = join(ROOT, 'tools', 'notify-config.ps1');
+
+const client = readFileSync(CLIENT, 'utf8');
+
+// ── C27: consumeLastSession 必须返回对象（不是裸字符串）──────────────────
+test('C27: consumeLastSession 返回 {sessionId, at} 对象而非裸字符串', () => {
+  const fn = client.match(/function consumeLastSession\(\)[\s\S]*?\n    \}/);
+  assert.ok(fn, '应能找到 consumeLastSession 定义');
+  const body = fn[0];
+
+  // 必须返回对象字面量
+  assert.match(body, /return\s*\{[\s\S]*sessionId:/,
+    'consumeLastSession 必须返回含 sessionId 的对象；'
+    + '返回裸字符串会让调用方的 doc.sessionId 恒为 undefined（2026-10-18 实际 bug）');
+
+  // 不得再有 `return doc.sessionId`（裸字符串返回）
+  assert.doesNotMatch(body, /return\s+doc\.sessionId\s*$/m,
+    '不得返回裸字符串 doc.sessionId');
+});
+
+// ── C28: 调用方与返回形状必须一致（防单边修改）──────────────────────────
+test('C28: 调用方按对象访问 sessionId（与 C27 形状一致）', () => {
+  const call = client.match(/consumeLastSession\(\)\.then\(function \(doc\) \{[\s\S]{0,400}/);
+  assert.ok(call, '应能找到调用点');
+  assert.match(call[0], /doc\.sessionId/,
+    '调用方应访问 doc.sessionId —— 每边都应跟着另一边改');
+  assert.match(call[0], /!doc \|\| !doc\.sessionId/,
+    '应保留空值短路判断');
+});
+
+// ── C29: jumpEnabled 必须"读不到配置就不跳" ─────────────────────────────
+test('C29: jumpEnabled 读不到配置时两个开关都为 false', () => {
+  // 用「从函数名到下一个 function/】」的宽松切片，避免依赖缩进宽度
+  const start = client.indexOf('function jumpEnabled()');
+  assert.ok(start >= 0, '应能找到 jumpEnabled 定义');
+  const rest = client.slice(start);
+  const endRel = rest.search(/\n\s*var onVisibility/);
+  const body = endRel > 0 ? rest.slice(0, endRel) : rest.slice(0, 2000);
+
+  // 原 bug：cfg.jumpWhenBackground !== false 在 {} 上求值为 true
+  //
+  // 注意：必须**剥掉注释行**再判断 —— 我们的修复注释里就写了
+  // `{}.jumpWhenBackground !== false` 来解释这个 bug，
+  // 直接搜全文会误报（第一次跑就是这么挂的）。
+  const codeOnly = body
+    .split('\n')
+    .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+    .join('\n');
+  assert.doesNotMatch(codeOnly, /jumpWhenBackground\s*!==\s*false/,
+    '不得用 `!== false` 判定 —— {} 会得到 true，与"拿不到就不跳"相反');
+
+  // 必须是严格等于 true
+  assert.match(body, /jumpWhenBackground:\s*v\.jumpWhenBackground === true/,
+    '必须严格判断 === true，缺失/undefined 都不跳');
+
+  // 必须显式处理空配置
+  assert.match(body, /Object\.keys\(v\)\.length === 0/,
+    '必须显式识别空配置（loadConfig 失败返回 {}）');
+});
+
+// ── C30: VOICE_KEYS 不得含许可被禁的音色 ────────────────────────────────
+test('C30: GUI 音色列表不含 kasukabe-tsumugi / mochiko', () => {
+  const m = client.match(/var VOICE_KEYS = \[[\s\S]*?\]/);
+  assert.ok(m, '应能找到 VOICE_KEYS');
+  const list = m[0];
+
+  for (const banned of ['kasukabe-tsumugi', 'mochiko']) {
+    // 只检查列表本体，注释里提到是可以的（那是解释为什么移除）
+    const inList = new RegExp(`'${banned}'`).test(list);
+    assert.equal(inList, false,
+      `${banned} 不得出现在 GUI 音色列表里 —— `
+      + '官方规约禁止再分发（见 docs/audio-audit/README.md）');
+  }
+});
+
+// ── C31: 安装提示不得指向不存在的脚本 ───────────────────────────────────
+test('C31: notify-config.ps1 不指向仓库里不存在的脚本', async () => {
+  const { existsSync } = await import('node:fs');
+  const src = readFileSync(NOTIFY_CONFIG, 'utf8');
+
+  // 找出所有 "powershell ... -File <某 .ps1>" 的提示
+  const refs = [...src.matchAll(/-File\s+\S*?([\w-]+\.ps1)/g)].map((m) => m[1]);
+  for (const script of new Set(refs)) {
+    const candidates = [
+      join(ROOT, 'tools', script),
+      join(ROOT, script),
+    ];
+    const found = candidates.some((p) => existsSync(p));
+    assert.ok(found,
+      `notify-config.ps1 提示用户运行 ${script}，但仓库里找不到它 —— `
+      + '这是"照着做就失败"的文档 bug');
+  }
+});

package/test/config-coverage.test.mjs

@@ -0,0 +1,109 @@
+/**
+ * 配置键覆盖检查（v0.4.18）。
+ *
+ * ## 为什么需要这条"元测试"
+ *
+ * 本项目反复栽在同一类错误上：**新加一个配置项，但某个环节忘了接**。
+ *
+ * 已发生 6 次：
+ *   v0.4.4  customFiles        写了但 store 白名单没有
+ *   v0.4.5  audioSourceByKind  同上
+ *   v0.4.10 debounceSeconds    normalizeConfig 算了，effectiveForClient 没映射
+ *   v0.4.11 devReload          GUI 有开关，白名单没有
+ *   v0.4.16 systemSound        同上
+ *   v0.4.18 voiceGain          又漏了 effectiveForClient（用户实测发现）
+ *
+ * 每次症状都一模一样：**设置能改，但保存后回读是旧值/默认值**，
+ * 用户以为"功能不存在"，我要花好几轮才定位。
+ *
+ * 人工"记得每次都改全"是不可靠的（已经证明漏了 6 次）。
+ * 所以改成**机器检查**：每个 CONFIG_KEYS 里的键，
+ * 都必须能在 effectiveForClient 的输出里找到。
+ *
+ * ## 为什么用"造一个全值 cfg"的方式测
+ *
+ * 直接读源码字符串太脆（改名/重构就误报）。
+ * 这里构造一个所有字段都有值的内部 cfg，跑一遍映射，
+ * 然后检查输出里有没对应键 —— 这是**行为级**检查，抗重构。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { CONFIG_KEYS } from '../lib/config-store.js';
+import { effectiveForClient } from '../lib/index.js';
+
+/**
+ * 造一个**每个已知字段都有值**的内部 cfg。
+ *
+ * 键名是 normalizeConfig 的输出形状（内部名，如 debounceMs），
+ * 不是 schema 键名。新增字段时这里也要补 —— 但即使忘了补，
+ * 只要 effectiveForClient 里有映射，本测试仍会通过（因为测试只查输出）。
+ */
+function mkFullCfg() {
+  const KINDS = ['done', 'fail', 'question', 'approval', 'blocked'];
+  const cap = (k) => k.charAt(0).toUpperCase() + k.slice(1);
+  const dict = (v) => Object.fromEntries(KINDS.map((k) => [k, v]));
+  return {
+    // 基础
+    voice: true, voiceMode: 'fixed', voiceName: 'zundamon-normal', volume: 80,
+    notifyOnComplete: true, notifyOnError: true, notifyOnBlocked: true,
+    notifyOnAborted: true, notifyOnApproval: true, notifyOnQuestion: true,
+    subagents: true, idleGate: true,
+    // 音源
+    audioSource: 'tts', showToast: true, ttsVoice: 'X', ttsRate: 1,
+    jumpWhenBackground: true, jumpWhenForeground: true, devReload: true,
+    // 冷却
+    debounceMs: 1000, globalCooldownMs: 2000, idleGateTimeoutMs: 3000,
+    // v0.4.16 增益
+    voiceGain: 2.5, normalizeCustomAudio: true,
+    // 按事件字典
+    audioSourceByKind: dict('tts'),
+    ttsTexts: dict('台词'),
+    customFiles: dict('D:\\a.wav'),
+    kindTtsVoice: dict('V'),
+    kindTtsRate: dict(1),
+    kindVoiceMode: dict('fixed'),
+    kindVoiceName: dict('N'),
+    kindSystemSound: dict('Beep'),
+  };
+}
+
+// ── K1: 核心保证 —— 每个配置键都能从 effectiveForClient 读回来 ───────────
+test('K1: CONFIG_KEYS 里的每个键都能从 effectiveForClient 读回', () => {
+  const out = effectiveForClient(mkFullCfg());
+
+  // 这两个是"内部字段"而非配置键，不参与比较
+  const INTERNAL = new Set(['debounceMs', 'globalCooldownMs', 'idleGateTimeoutMs']);
+
+  const missing = CONFIG_KEYS.filter((k) => {
+    if (INTERNAL.has(k)) return false;
+    // 出现即为映射成功（值可能 undefined 但键应存在）
+    return !(k in out);
+  });
+
+  assert.deepEqual(missing, [],
+    '以下配置键在 effectiveForClient 里没有映射 —— '
+    + 'GUI 会读不到值、保存后显示默认值（本项目已因此栽过 6 次）：\n  '
+    + missing.join('\n  '));
+});
+
+// ── K2: 映射出的值必须与输入一致（防"键在但值错"）───────────────────────
+test('K2: 映射后的值与内部 cfg 一致', () => {
+  const out = effectiveForClient(mkFullCfg());
+  assert.equal(out.voiceGain, 2.5);
+  assert.equal(out.normalizeCustomAudio, true);
+  assert.equal(out.volume, 80);
+  assert.equal(out.audioSource, 'tts');
+  assert.equal(out.debounceSeconds, 1, '1000ms 应映射成 1 秒');
+  assert.equal(out.globalCooldownSeconds, 2);
+});
+
+// ── K3: 默认值也必须能读回（不只是"设过才有"）───────────────────────────
+test('K3: 空配置时关键默认值仍可读（前端要显示默认、不能一片 undefined）', () => {
+  const out = effectiveForClient({});
+  // 增益必须有合理默认，否则滑杆位置无从确定
+  assert.equal(typeof out.voiceGain, 'number',
+    'voiceGain 必须给出数值，否则滑杆无法定位');
+  assert.ok(out.voiceGain >= 1 && out.voiceGain <= 4);
+  assert.equal(typeof out.normalizeCustomAudio, 'boolean');
+});

package/test/config-route.test.mjs

@@ -0,0 +1,212 @@
+/**
+ * config-route 测试：HTTP 配置读写的完整验证。
+ *
+ * ## 为什么必须有
+ *
+ * 这是**唯一会写用户配置文件的代码路径**。它写错的表现是静默的：
+ * 用户的音量/音色被改掉而不知道，或者配置被写坏后插件行为异常。
+ *
+ * ## 覆盖
+ *
+ * - R1  GET 返回**生效值**，不是文件层（关键：patch 的 volume=100 不能被显示成 80）
+ * - R2  保存后响应仍返回生效值（防止其它控件回弹）
+ * - R3  保存单个开关只写那一个键，不动其它
+ * - R4  非法输入被拒绝，不写盘
+ * - R5  只认 /config/set 为写，且必须 POST
+ * - R6  clear 后返回生效值（回到 patch/schema 层）
+ * - R7  路径分流辅助：/config vs /consume 不会互相误判
+ * - R8  文件损坏时不覆盖（fail-closed）
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+// ⚠️ 必须在 import 前隔离 DSH_HOME
+const HOME = mkdtempSync(join(tmpdir(), 'notify-cfgroute-'));
+process.env.DSH_HOME = HOME;
+process.on('exit', () => { try { rmSync(HOME, { recursive: true, force: true }); } catch { /* ignore */ } });
+
+const { createConfigRoute } = await import('../lib/config-route.js');
+const { configPath } = await import('../lib/config-store.js');
+
+/** 造一个记录 code/body 的假 res。 */
+function mkRes() {
+  const o = {
+    code: 0, body: null,
+    writeHead(c) { o.code = c; },
+    end(t) { o.body = t == null ? '' : String(t); },
+  };
+  return o;
+}
+
+/** 调一次 handler 并解析 JSON。 */
+async function call(route, { method = 'GET', url, body } = {}) {
+  const res = mkRes();
+  await route.handler({ method, url, body }, res);
+  let doc = null;
+  try { doc = res.body ? JSON.parse(res.body) : null; } catch { doc = null; }
+  return { code: res.code, doc };
+}
+
+/**
+ * 每次测试用全新 route，并**清掉文件层**，避免用例之间串味。
+ *
+ * ⚠️ 所有用例共享同一个 $DSH_HOME（同一个 config.json），
+ * 不清的话前一个用例写的 volume=55 会留到后一个，导致假失败（实测踩到）。
+ */
+function mkRoute(effective) {
+  const p = configPath();
+  try { if (p && existsSync(p)) unlinkSync(p); } catch { /* ignore */ }
+  return createConfigRoute({
+    onChanged: () => {},
+    getEffective: () => effective,
+  });
+}
+
+const GET_URL = '/api/dsh-notify-say/config';
+const SET_URL = '/api/dsh-notify-say/config/set';
+
+// ── R1: GET 返回生效值 ─────────────────────────────────────────────────────
+test('R1: GET 返回生效值，而不是文件层覆盖值', async () => {
+  // patch 里 volume=100，文件层什么都没存 —— 这正是真实的默认状态
+  const effective = { voice: true, volume: 100, voiceMode: 'fixed', voiceName: 'zundamon-normal', idleGate: true };
+  const r = mkRoute(effective);
+  const { code, doc } = await call(r, { url: GET_URL });
+
+  assert.equal(code, 200);
+  assert.equal(doc.ok, true);
+  assert.equal(doc.values.volume, 100,
+    '必须显示生效值 100；显示 80 会让用户误拖滑块把 100 覆盖成 80');
+  assert.equal(doc.values.voiceMode, 'fixed');
+  // 文件层覆盖值单独给出，便于判断"哪些是用户显式设过的"
+  assert.ok(doc.overrides && typeof doc.overrides === 'object');
+});
+
+// ── R2: 保存后响应仍是生效值 ───────────────────────────────────────────────
+test('R2: 保存一个开关后，响应里其它键仍是生效值（不回弹）', async () => {
+  // 用一个可变的"生效配置"模拟 host：保存后 onChanged 会刷新它
+  let effective = { voice: true, volume: 100, voiceMode: 'fixed', voiceName: 'zundamon-normal', idleGate: true };
+  const r = createConfigRoute({
+    onChanged: () => {
+      // 模拟 refreshConfig：把文件层合并进生效值
+      effective = { ...effective, idleGate: false };
+    },
+    getEffective: () => effective,
+  });
+
+  const { code, doc } = await call(r, {
+    method: 'POST', url: SET_URL, body: { values: { idleGate: false } },
+  });
+
+  assert.equal(code, 200);
+  assert.equal(doc.ok, true);
+  assert.equal(doc.values.idleGate, false, '改动应生效');
+  assert.equal(doc.values.volume, 100,
+    'volume 不在这次写入里，响应必须仍返回 100；否则 client 会把它覆盖成硬编码 80');
+});
+
+// ── R3: 只写指定的键 ──────────────────────────────────────────────────────
+test('R3: 保存只写指定键，不污染其它配置', async () => {
+  const r = mkRoute({ voice: true, volume: 100, voiceMode: 'fixed' });
+  await call(r, { method: 'POST', url: SET_URL, body: { values: { volume: 55 } } });
+
+  // 直接读文件层，确认只写了 volume
+  const raw = JSON.parse(readFileSync(configPath(), 'utf8'));
+  assert.equal(raw.values.volume, 55);
+  assert.equal(raw.values.voice, undefined, '不该写入未提交的键');
+  assert.equal(raw.values.voiceMode, undefined);
+});
+
+// ── R4: 非法输入被拒绝 ────────────────────────────────────────────────────
+test('R4: 非法输入被拒绝且不写盘', async () => {
+  const r = mkRoute({ volume: 100 });
+
+  // 未知键
+  let res = await call(r, { method: 'POST', url: SET_URL, body: { values: { notAKey: 1 } } });
+  assert.equal(res.code, 400);
+  assert.equal(res.doc.ok, false);
+
+  // 越界值
+  res = await call(r, { method: 'POST', url: SET_URL, body: { values: { volume: 9999 } } });
+  assert.equal(res.code, 400);
+
+  // 空 body
+  res = await call(r, { method: 'POST', url: SET_URL, body: {} });
+  assert.equal(res.code, 400);
+
+  // 全部拒绝后，文件层应仍是空的
+  const p = configPath();
+  if (existsSync(p)) {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    assert.deepEqual(raw.values || {}, {}, '非法写入不应留下任何键');
+  }
+});
+
+// ── R5: 方法与路径 ────────────────────────────────────────────────────────
+test('R5: 只认 /config/set 为写，且必须 POST', async () => {
+  const r = mkRoute({ volume: 100 });
+
+  // POST 到 /config（不是 /set）不应被当成写
+  const res1 = await call(r, { method: 'POST', url: GET_URL, body: { values: { volume: 7 } } });
+  assert.equal(res1.code, 200, 'POST /config 应按读处理');
+  assert.equal(res1.doc.values.volume, 100, '不应写入');
+
+  // GET 到 /config/set 应被拒（405）
+  const res2 = await call(r, { method: 'GET', url: SET_URL });
+  assert.equal(res2.code, 405);
+});
+
+// ── R6: clear 返回生效值 ──────────────────────────────────────────────────
+test('R6: clear 清掉文件层后返回生效值（回到 patch/schema）', async () => {
+  let effective = { volume: 100 };
+  const r = createConfigRoute({
+    onChanged: () => { effective = { volume: 100 }; },   // clear 后回到 patch 值
+    getEffective: () => effective,
+  });
+
+  // 先存一个覆盖
+  await call(r, { method: 'POST', url: SET_URL, body: { values: { volume: 30 } } });
+
+  // 再清空
+  const { code, doc } = await call(r, { method: 'POST', url: SET_URL, body: { clear: true } });
+  assert.equal(code, 200);
+  assert.equal(doc.values.volume, 100, '清空后应回到 patch 的 100，不是空对象');
+
+  assert.equal(existsSync(configPath()), false, 'clear 应删除文件层');
+});
+
+// ── R7: 路径分流 ──────────────────────────────────────────────────────────
+test('R7: 路径按段分流，查询串里的 /config 不会误判', () => {
+  const PREFIX = '/api/dsh-notify-say';
+  function route(raw) {
+    const pathname = raw.split('?')[0].split('#')[0];
+    const rest = pathname.startsWith(PREFIX) ? pathname.slice(PREFIX.length) : pathname;
+    const head = rest.replace(/^\/+/, '').split('/')[0];
+    return head === 'config' ? 'config' : 'bridge';
+  }
+  assert.equal(route('/api/dsh-notify-say/config'), 'config');
+  assert.equal(route('/api/dsh-notify-say/config/set'), 'config');
+  assert.equal(route('/api/dsh-notify-say/consume'), 'bridge');
+  assert.equal(route('/api/dsh-notify-say/consume?next=/config'), 'bridge',
+    '查询串不应影响分流');
+  assert.equal(route('/api/dsh-notify-say/last-session'), 'bridge');
+});
+
+// ── R8: 文件损坏时不覆盖 ──────────────────────────────────────────────────
+test('R8: 文件层损坏时拒绝写入（不覆盖用户数据）', async () => {
+  const p = configPath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, '{ this is not valid json', 'utf8');
+
+  // ⚠️ 不能用 mkRoute —— 它会先删掉 config.json，把这个用例精心造的损坏文件清掉。
+  const r = createConfigRoute({ onChanged: () => {}, getEffective: () => ({ volume: 100 }) });
+  const { code, doc } = await call(r, { method: 'POST', url: SET_URL, body: { values: { volume: 42 } } });
+
+  assert.equal(code, 409, '损坏的文件不该被覆盖');
+  assert.equal(doc.ok, false);
+
+  // 原文件必须保持原样，供人工救
+  assert.equal(readFileSync(p, 'utf8'), '{ this is not valid json');
+});

package/test/config-schema.test.mjs

@@ -0,0 +1,147 @@
+/**
+ * config-schema 测试：官方 Config schema 的正确性与降级安全。
+ *
+ * 这是「设置页 GUI」的地基，错一处就整块报废（官方报错：
+ * `Plugin entry "<ns>" has no volatile fields` / `Config field "<path>" is not volatile`），
+ * 或更糟：schema 加载失败把插件一起拖挂。所以两类都测。
+ *
+ * 覆盖：
+ *  - S1  schema 能从 $DSH_HOME 侧解析到 schemastery
+ *  - S2  **每个字段**都有 volatile 标记（漏一个就是 has no volatile fields）
+ *  - S3  默认值正确，且 readConfig 能从 ref 取值
+ *  - S4  越界值被 schema 拒绝（volume 边界）
+ *  - S5  降级：$DSH_HOME 缺失时 loadSchema 返回 null 且不抛
+ *  - S6  降级：$DSH_HOME 指向不存在的目录时同样安全返回 null
+ *  - S7  readConfig 兼容「普通对象」（Loader 已解析）与「缺失键」
+ *  - S8  插件模块的 Config 导出与本 schema 一致（防两处各写一份漂移）
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  safeHome, loadSchema, buildConfig, readConfig, FIELD_DEFAULTS,
+} from '../lib/config-schema.js';
+
+const HAS_HOME = typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME.length > 0;
+
+// ── S1: 能解析到 schemastery ────────────────────────────────────────────────
+test('S1: 从 $DSH_HOME 侧能解析 @deepseek-ai/schemastery',
+  { skip: !HAS_HOME && '需要真实 $DSH_HOME（本机有；纯沙盒环境跳过）' }, () => {
+    const z = loadSchema(process.env);
+    assert.ok(z, '应解析到 schemastery');
+    assert.equal(typeof z.object, 'function', 'schemastery 应提供 z.object');
+  });
+
+// ── S2: 每个字段都必须 volatile（官方硬契约）────────────────────────────────
+test('S2: 每个字段都带 volatile 标记（漏一个设置页就报废）', () => {
+  const z = loadSchema(process.env);
+  if (!z) return; // 降级环境跳过（S5/S6 覆盖降级本身）
+  const Config = buildConfig(z);
+  const dict = Config.dict;
+  assert.ok(dict, 'schema 应有 dict');
+
+  const missing = [];
+  for (const key of Object.keys(FIELD_DEFAULTS)) {
+    const field = dict[key];
+    if (!field) { missing.push(key + '(字段不存在)'); continue; }
+    if (!field.meta || field.meta.volatile !== true) missing.push(key);
+  }
+  assert.deepEqual(missing, [],
+    `以下字段缺少 .volatile()，会导致 "Plugin entry has no volatile fields"：${missing.join(', ')}`);
+});
+
+// ── S3: 默认值与取值 ────────────────────────────────────────────────────────
+test('S3: 默认值正确，readConfig 能从 schemastery ref 取值', () => {
+  const z = loadSchema(process.env);
+  if (!z) return;
+  const Config = buildConfig(z);
+  const inst = Config({});
+  const vals = readConfig(inst);
+
+  assert.equal(vals.voice, FIELD_DEFAULTS.voice);
+  assert.equal(vals.voiceMode, FIELD_DEFAULTS.voiceMode);
+  assert.equal(vals.voiceName, FIELD_DEFAULTS.voiceName);
+  assert.equal(vals.volume, FIELD_DEFAULTS.volume);
+  assert.equal(vals.idleGate, FIELD_DEFAULTS.idleGate);
+  assert.equal(Object.keys(vals).length, Object.keys(FIELD_DEFAULTS).length,
+    'readConfig 应返回与 FIELD_DEFAULTS 同样多的键');
+});
+
+// ── S4: 越界值被拒 ──────────────────────────────────────────────────────────
+test('S4: volume 越界被 schema 拒绝（0-100）', () => {
+  const z = loadSchema(process.env);
+  if (!z) return;
+  const Config = buildConfig(z);
+  assert.throws(() => Config({ volume: 101 }), /volume|100/, 'volume=101 应被拒');
+  assert.throws(() => Config({ volume: -1 }), /volume|0/, 'volume=-1 应被拒');
+  // 边界值合法
+  assert.equal(readConfig(Config({ volume: 0 })).volume, 0);
+  assert.equal(readConfig(Config({ volume: 100 })).volume, 100);
+});
+
+// ── S5: 降级 —— 没有 $DSH_HOME ──────────────────────────────────────────────
+test('S5: $DSH_HOME 缺失时 loadSchema 安全返回 null（不抛）', () => {
+  assert.doesNotThrow(() => {
+    const z = loadSchema({});
+    assert.equal(z, null, '没有 $DSH_HOME 时应返回 null 而不是抛异常');
+  });
+  assert.equal(safeHome({}), '');
+  assert.equal(safeHome({ DSH_HOME: '' }), '');
+});
+
+// ── S6: 降级 —— $DSH_HOME 指向不存在的地方 ──────────────────────────────────
+test('S6: $DSH_HOME 指向不存在的目录时安全返回 null', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'notify-schema-'));
+  try {
+    // 用一个空临时目录当 DSH_HOME：没有任何 package.json 锚点
+    assert.doesNotThrow(() => {
+      const z = loadSchema({ DSH_HOME: dir });
+      assert.equal(z, null, '解析不到 schemastery 应返回 null');
+    });
+  } finally {
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+});
+
+// ── S7: readConfig 的兼容性 ─────────────────────────────────────────────────
+test('S7: readConfig 兼容普通对象 / 缺失键 / null', () => {
+  // Loader 已解析成普通对象的情况
+  const plain = { volume: 42, voice: false, voiceMode: 'random' };
+  const got = readConfig(plain);
+  assert.equal(got.volume, 42);
+  assert.equal(got.voice, false);
+  assert.equal(got.voiceMode, 'random');
+  // 缺失的键用默认值补齐（避免下游拿到 undefined 后静默走错分支）
+  assert.equal(got.idleGate, FIELD_DEFAULTS.idleGate, '缺失键应回落到默认值');
+
+  // null / undefined 不能崩
+  assert.doesNotThrow(() => readConfig(null));
+  assert.doesNotThrow(() => readConfig(undefined));
+  assert.equal(readConfig(null).volume, FIELD_DEFAULTS.volume);
+});
+
+// ── S8: 插件导出的 Config 与本 schema 一致（防两处漂移）────────────────────
+test('S8: lib/index.js 导出的 Config 与 buildConfig 结构一致', async () => {
+  const mod = await import('../lib/index.js');
+  assert.equal(typeof mod.apply, 'function', 'apply 必须导出');
+  const z = loadSchema(process.env);
+  if (!z) {
+    assert.equal(mod.Config, undefined, '降级环境下 Config 应为 undefined');
+    return;
+  }
+  assert.equal(typeof mod.Config, 'function', 'Config 应导出且可实例化');
+  const mine = buildConfig(z);
+  // 字段集合必须一致（防止 index.js 里另写一份）
+  assert.deepEqual(
+    Object.keys(mod.Config.dict).sort(),
+    Object.keys(mine.dict).sort(),
+    'index.js 导出的 Config 字段集合与 config-schema.js 必须一致',
+  );
+  // volatile 契约同样成立
+  for (const key of Object.keys(FIELD_DEFAULTS)) {
+    assert.equal(mod.Config.dict[key].meta.volatile, true, `${key} 在导出的 Config 里必须 volatile`);
+  }
+});