dsh-notify-say 0.4.21 → 0.4.25

package/test/fail-voice.test.mjs

@@ -0,0 +1,193 @@
+/**
+ * dsh-notify-desktop 失败语音（fail 池）测试 —— v0.3.1。
+ *
+ * 覆盖两处：
+ *  A. lib/index.js：error 分支必须走 psKind='fail'；blocked 必须仍是 'chime'
+ *     （语义不同：error=跑了但失败，blocked=被拦下没跑起来）。
+ *  B. dsh-notify.ps1：fail 池**不得**回落到 done 池 / master-voice / 梗音效池
+ *     ——否则失败时会播「主人、任務完了です！」，语义完全相反。
+ *
+ * B 用 PowerShell 子进程真跑 ps1（-Preview 只出声不弹 Toast），断言其 pick= 字段。
+ *
+ * ⚠️ **本文件故意不 import ../lib/index.js，也不改 SystemRoot**（三条实测踩坑，别踩）：
+ * ① 别的测试文件用 `process.env.SystemRoot = '<不存在>'` 来让 spawn 失效；
+ *    若本文件也这么干，**PowerShell 子进程会启动失败**（报 `8009001d`
+ *    "Loading managed Windows PowerShell failed"——CLR 找不到 .NET），
+ *    表现为 stdout 全空、5 条断言全红，**极易误判成"代码坏了"**。
+ *    本文件只读源码文本、只跑 ps1，不需要那个隔离。
+ * ② 不能用 `node --test ... -- <args>` 传参：`node --test` 会把 `--` 之后的参数当
+ *    **测试文件**加载，`.ps1` 触发 `ERR_UNKNOWN_FILE_EXTENSION`，且 argv 取不到值。
+ * ③ 不能用 `execFileSync` 抓 stdout（本机 `node --test` 下拿不到）；用 `spawnSync`。
+ *
+ * ⚠️ worktree 长路径限制（实测）：MCI 在 >130 字符的 wav 路径上 open 返回 304，
+ * 故本文件**只断言"选到了哪个文件"**（pick= 字段，纯字符串判定），
+ * **不断言"是否真的出声"**——后者在 worktree 里必假失败，是环境限制非代码缺陷。
+ * 真机播放已在短路径（模拟部署）下人工验证通过。
+ *
+ * 运行：node --test tools/plugins/dsh-notify-desktop/test/
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PLUGIN = join(HERE, '..');
+const PS1 = join(PLUGIN, 'dsh-notify.ps1');
+const FAIL_POOL = join(PLUGIN, 'sounds', 'voice-lines', 'fail');
+/** done 池 = voice-lines 根目录（那批是说「任務完了です」的，失败时不该播）。 */
+const DONE_POOL = join(PLUGIN, 'sounds', 'voice-lines');
+const LIB = join(PLUGIN, 'lib', 'index.js');
+
+/** 跑 ps1 -Preview，返回 stdout / stderr / exit code。用 spawnSync（见文件头踩坑③）。 */
+function runPs1(args) {
+  const r = spawnSync('powershell',
+    ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', PS1, ...args],
+    { encoding: 'utf8', timeout: 60_000 });
+  return {
+    out: String(r.stdout || ''),
+    err: String(r.stderr || ''),
+    code: typeof r.status === 'number' ? r.status : 1,
+  };
+}
+
+/** 从输出里提取 pick=<name>。 */
+function pickOf(out) {
+  const m = /pick=([^\s+]+)/.exec(out);
+  return m ? m[1] : '';
+}
+
+// ── A. lib 源码分支路由（读源码文本断言，不起进程）─────────────────────────
+test('A1: lib 源码中 error 分支走 fail 池，blocked 仍走 chime（exact）', () => {
+  const src = readFileSync(LIB, 'utf8');
+  assert.match(src, /gate = cfg\.notifyOnError; psKind = 'fail';/,
+    "error 分支必须设为 psKind='fail'（否则失败不播 fail 池）");
+  assert.match(src, /gate = cfg\.notifyOnBlocked; psKind = 'chime';/,
+    "blocked 必须保持 psKind='chime'（它是'被拦下没跑起来'，不是'跑了但失败'）");
+  // 负例：error 不得再是 chime —— 那正是本次要改掉的旧行为
+  assert.doesNotMatch(src, /gate = cfg\.notifyOnError; psKind = 'chime';/,
+    "error 不应再走 chime");
+});
+
+// ── B. ps1 池选择与语义护栏（真跑 ps1）──────────────────────────────────────
+test('B0: fail 池资产存在且为 48 条（3 句 × 16 音色）', () => {
+  assert.equal(existsSync(FAIL_POOL), true, 'fail 池目录必须存在');
+  const files = readdirSync(FAIL_POOL).filter((f) => f.endsWith('.wav'));
+
+  // ⚠️ 不能硬编码"48 条 / 16 音色"。
+  //
+  // 自用版有 16 个音色的 fail 语音，但**发布版只带 1 个音色**。
+  // 硬编码会在发布包里必然失败 —— 而那个失败是"测试假设了开发环境"，
+  // 不是资产真的有问题。外部用户跑 `npm test` 看到红灯，会以为包坏了。
+  //
+  // 判据改为：**按 fail 池自己出现的音色集合**推算应有条数。
+  // 每个音色在 fail 池应有 3 个变体（~1/~2/~3）。
+  const byVoice = new Map();
+  for (const f of files) {
+    const m = /^(.+)~(\d)\.wav$/.exec(f);
+    if (!m) continue;
+    const [, base, n] = m;
+    if (!byVoice.has(base)) byVoice.set(base, new Map());
+    byVoice.get(base).set(n, (byVoice.get(base).get(n) || 0) + 1);
+  }
+  assert.ok(byVoice.size > 0, 'fail 池至少要有一个音色');
+
+  // 每个音色的三个变体都应恰好各 1 条（不是"某些音色有 3 条、某些只有 1 条"）
+  for (const [base, variants] of byVoice) {
+    assert.deepEqual(
+      [...variants.keys()].sort(),
+      ['1', '2', '3'],
+      `音色 ${base} 应恰好有 ~1/~2/~3 三个变体，实际 ${[...variants.keys()].join(',')}`,
+    );
+    for (const [n, count] of variants) {
+      assert.equal(count, 1, `音色 ${base} 的 ~${n} 变体不应重复（实际 ${count} 条）`);
+    }
+  }
+
+  // 总数 = 音色数 × 3
+  assert.equal(
+    files.length,
+    byVoice.size * 3,
+    `fail 池应为 ${byVoice.size} 音色 × 3 变体 = ${byVoice.size * 3} 条，实际 ${files.length}`,
+  );
+});
+
+test('B1: -Kind fail + 固定音色 → 选到 fail 池的 ~N 变体（不是 done 池同名文件）', () => {
+  const { out, err, code } = runPs1(['-Kind', 'fail', '-Preview', '-Voice', 'zundamon-normal', '-Volume', '0']);
+  assert.equal(code, 0, `ps1 应正常退出；stderr=${err.slice(0, 200)}`);
+  const pick = pickOf(out);
+  assert.match(pick, /^zundamon-normal~\d\.wav$/, `应选 fail 池 ~N 变体，实际 pick=${pick}`);
+  // 负例：不得选到 done 池根目录的同名（无 ~）文件
+  assert.doesNotMatch(pick, /^zundamon-normal\.wav$/, '不得选到 done 池根目录的同名文件');
+});
+
+test('B2: -Kind fail + random → 仍限定在 fail 池（不回落到庆祝音）', () => {
+  const { out, code } = runPs1(['-Kind', 'fail', '-Preview', '-Mode', 'random', '-Volume', '0']);
+  assert.equal(code, 0, 'ps1 应正常退出');
+  const pick = pickOf(out);
+  assert.match(pick, /~\d\.wav$/, `random 应选 fail 池 ~N 变体，实际 pick=${pick}`);
+  assert.doesNotMatch(pick, /master-voice/, '不得回落 master-voice（那是"任務完了"）');
+  assert.doesNotMatch(pick, /\.mp3$/, '不得回落梗音效池（庆祝音）');
+});
+
+test('B3: fail 池缺该音色 → 在 fail 池内换音色，**绝不回落到 done 池**（关键护栏）', () => {
+  // 独立复核 I-1 提出后（2026-10-17）行为已加强：池内换音色 > 没台词。
+  // 用 done 池里真实存在、但 fail 池不覆盖的 key（如 -kansai-1 变体）来测这条路径。
+  const { out, code } = runPs1(['-Kind', 'fail', '-Preview', '-Voice', 'ameharu-hau-kansai-1', '-Volume', '0']);
+  assert.equal(code, 0, 'ps1 应正常退出');
+  const pick = pickOf(out);
+
+  // ① 必须仍从 fail 池取到台词（不能因为缺该音色就哑掉）
+  assert.match(pick, /~\d\.wav$/, `应在 fail 池内换音色，实际 pick=${pick}`);
+
+  // ② 本测试最重要的一条：绝不回落到 done 池（那会播「主人、任務完了です！」语义相反）。
+  // ⚠️ 不能写 `assert.doesNotMatch(out, /pick=\S*voice-lines\\/)`——`pick=` 只含**叶文件名**、
+  // 从不含目录，该断言**永远为真 = 空断言**（自查时发现并改掉）。
+  // 有效做法：拿 done 池根目录的真实文件名清单，断言 pick 不等于其中任何一个。
+  const doneNames = new Set(readdirSync(DONE_POOL).filter((f) => f.endsWith('.wav')));
+  assert.ok(!doneNames.has(pick), `pick=${pick} 落在 done 池里（说明回落到"完成"语音）`);
+
+  // ③ 也不许回落到 master-voice / 梗音效（庆祝音）
+  assert.doesNotMatch(out, /master-voice/, '不得回落 master-voice');
+  assert.doesNotMatch(pick, /\.mp3$/, '不得回落梗音效池');
+});
+
+test('B3b: 完全不存在该音色 → 仍在 fail 池内取台词（不哑）', () => {
+  const { out, code } = runPs1(['-Kind', 'fail', '-Preview', '-Voice', 'no-such-voice-xyz', '-Volume', '0']);
+  assert.equal(code, 0, 'ps1 应正常退出');
+  const pick = pickOf(out);
+  assert.match(pick, /~\d\.wav$/, `应在 fail 池内换音色，实际 pick=${pick}`);
+  const doneNames = new Set(readdirSync(DONE_POOL).filter((f) => f.endsWith('.wav')));
+  assert.ok(!doneNames.has(pick), `pick=${pick} 落在 done 池里`);
+});
+
+test('B3c: fail 池整目录缺失 → 落到蜂鸣（不变哑巴，也不越池到 done）', () => {
+  // 用 chime 模拟"子池取不到"这层保护：chime 恒不取语句，其兜底必须是蜂鸣而非 done 池。
+  const { out, code } = runPs1(['-Kind', 'chime', '-Preview', '-Volume', '0']);
+  assert.equal(code, 0, 'ps1 应正常退出');
+  assert.equal(pickOf(out), 'chime', 'chime 应标为 chime（走蜂鸣）');
+  assert.doesNotMatch(out, /pick=\S+\.wav/, 'chime 不得取到任何语句文件');
+});
+
+test('B4: -Kind chime → 不选语句（pick 标为 chime，只蜂鸣）', () => {
+  const { out, code } = runPs1(['-Kind', 'chime', '-Preview', '-Volume', '0']);
+  assert.equal(code, 0, 'ps1 应正常退出');
+  // 既有行为：chime 的展示标签就是 'chime'（ps1 的 pickedName 分支），不是 'none'。
+  // 关键断言是「没有选到任何 wav 语句」——chime 必须既不是 fail 池也不是 done 池。
+  assert.equal(pickOf(out), 'chime', `chime 的 pick 标签应为 chime，实际=${pickOf(out)}`);
+  assert.doesNotMatch(out, /pick=\S+\.wav/, 'chime 不得选到任何语音文件');
+});
+
+test('B5: -Kind done 未回归（仍从 done 池选）', () => {
+  const { out, code } = runPs1(['-Kind', 'done', '-Preview', '-Voice', 'zundamon-normal', '-Volume', '0']);
+  assert.equal(code, 0, 'ps1 应正常退出');
+  const pick = pickOf(out);
+  assert.match(pick, /^(zundamon-normal|master-voice)\.wav$/, `done 应走 done 池/master，实际 pick=${pick}`);
+});
+
+test('B6: 未知 Kind 被 ValidateSet 拒绝（fail-closed，不会静默走错池）', () => {
+  const { code } = runPs1(['-Kind', 'bogus-kind', '-Preview']);
+  assert.notEqual(code, 0, 'ValidateSet 应拒绝未知 Kind');
+});

package/test/http-guard.test.mjs

@@ -0,0 +1,143 @@
+/**
+ * HTTP 路由防护测试（v0.4.24）。
+ *
+ * ## 背景：这不是理论风险，是实测出来的
+ *
+ * 2026-10-18 实测：
+ *   GET  /api                        → 401  宿主有鉴权
+ *   POST /api/dsh-notify-say/config/set（**不带任何凭据**）→ 200，配置真的被改
+ *
+ * 也就是说插件通过 `webServer.register()` 注册的路由**绕过了宿主鉴权**。
+ * 恶意网页可以用 `<img>` / 自动提交的 `<form>` 打到 127.0.0.1 上，
+ * 这类"简单请求"不触发 CORS 预检，所以浏览器不会拦。
+ *
+ * ## 本测试锁住什么
+ *
+ * 1. 防护函数的判定规则（单元级，纯逻辑）
+ * 2. 源码里确实接上了防护（防"写了模块但没接线"）
+ * 3. 限流确实生效
+ */
+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';
+
+import { checkLocalOrigin, throttle, __resetThrottle } from '../lib/http-guard.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const GOOD = 'http://127.0.0.1:62120';
+
+/** 造一个 req 形状。 */
+function req(headers) {
+  return { headers };
+}
+
+// ── H1: 本机来源放行 ────────────────────────────────────────────────────
+test('H1: 本机回环 Origin 的读请求放行', () => {
+  for (const origin of [GOOD, 'http://localhost:62120', 'http://[::1]:62120']) {
+    const r = checkLocalOrigin(req({ origin }));
+    assert.equal(r.ok, true, `${origin} 应放行，实际拒绝：${r.reason}`);
+  }
+});
+
+// ── H2: 外部 Origin 必须拒绝（核心：恶意网页）───────────────────────────
+test('H2: 外部域 Origin 一律拒绝', () => {
+  for (const origin of [
+    'https://evil.com',
+    'http://evil.com:62120',
+    'https://127.0.0.1.evil.com',   // 前缀伪装
+    'file://',
+  ]) {
+    const r = checkLocalOrigin(req({ origin }));
+    assert.equal(r.ok, false, `${origin} 必须拒绝`);
+  }
+});
+
+// ── H3: null Origin 拒绝（沙箱 iframe / file://）────────────────────────
+test('H3: Origin: null 拒绝', () => {
+  const r = checkLocalOrigin(req({ origin: 'null' }));
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'null-origin');
+});
+
+// ── H4: Sec-Fetch-Site: cross-site 优先拒绝 ─────────────────────────────
+test('H4: Sec-Fetch-Site 为 cross-site 时拒绝（即使 Origin 看着正常）', () => {
+  const r = checkLocalOrigin(req({
+    origin: GOOD,
+    'sec-fetch-site': 'cross-site',
+  }));
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'cross-site');
+});
+
+// ── H5: 写操作必须 JSON（堵死表单提交）──────────────────────────────────
+test('H5: 写操作用表单 content-type 时拒绝', () => {
+  const r = checkLocalOrigin(
+    req({ origin: GOOD, 'content-type': 'application/x-www-form-urlencoded' }),
+    { write: true },
+  );
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'write-requires-json',
+    '<form> 发不出 application/json —— 强制 JSON 等于堵死跨站表单提交');
+});
+
+// ── H6: 写操作无 Origin 也拒绝 ──────────────────────────────────────────
+test('H6: 写操作缺少 Origin/Referer 时拒绝', () => {
+  const r = checkLocalOrigin(
+    req({ 'content-type': 'application/json' }),
+    { write: true },
+  );
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'write-without-origin');
+});
+
+// ── H7: 正常写操作放行 ──────────────────────────────────────────────────
+test('H7: 本机 Origin + JSON 的写操作放行', () => {
+  const r = checkLocalOrigin(
+    req({ origin: GOOD, 'content-type': 'application/json; charset=utf-8' }),
+    { write: true },
+  );
+  assert.equal(r.ok, true);
+});
+
+// ── H8: 限流生效 ────────────────────────────────────────────────────────
+test('H8: throttle 在间隔内拒绝第二次', () => {
+  __resetThrottle();
+  assert.equal(throttle('preview', 3000).ok, true, '第一次应放行');
+  const second = throttle('preview', 3000);
+  assert.equal(second.ok, false, '间隔内第二次必须拒绝');
+  assert.ok(second.retryAfterMs > 0, '应给出剩余等待时间');
+});
+
+// ── H9: 不同路由的限流互不影响 ──────────────────────────────────────────
+test('H9: 不同 key 的限流相互独立', () => {
+  __resetThrottle();
+  assert.equal(throttle('preview', 3000).ok, true);
+  assert.equal(throttle('selftest', 3000).ok, true,
+    'selftest 不该被 preview 的限流影响');
+});
+
+// ── H10: 源码确实接上了防护（防"写了模块没接线"）────────────────────────
+test('H10: index.js 实际调用了 checkLocalOrigin 与 throttle', () => {
+  const src = readFileSync(join(ROOT, 'lib', 'index.js'), 'utf8');
+  assert.match(src, /import\s*\{[^}]*checkLocalOrigin/,
+    '必须 import checkLocalOrigin');
+  assert.match(src, /checkLocalOrigin\(req/,
+    '必须在请求处理里调用 checkLocalOrigin');
+  assert.match(src, /throttle\(/,
+    '必须对 preview/selftest 调用 throttle');
+  assert.match(src, /reason: guard\.reason/,
+    '拒绝时应把 reason 回给调用方，便于诊断');
+});
+
+// ── H11: config-route 必须有请求体上限 ──────────────────────────────────
+test('H11: config-route 有请求体大小上限（不只是超时）', () => {
+  const src = readFileSync(join(ROOT, 'lib', 'config-route.js'), 'utf8');
+  assert.match(src, /MAX_BODY_BYTES/,
+    '必须有大小上限常量 —— 3 秒超时不等于限流，慢速大包能绕过');
+  assert.match(src, /__tooLarge/,
+    '超限必须能被调用方识别');
+  assert.match(src, /413/,
+    '超限应回 413（与 400 格式错区分）');
+});

package/test/http-integration.test.mjs

@@ -0,0 +1,284 @@
+/**
+ * HTTP 端到端集成测试（v0.4.25）。
+ *
+ * ## 为什么这类测试必须有
+ *
+ * 2026-10-18 的教训：我为 `/consume` 加了"写操作必须 JSON"的防护，
+ * 但客户端仍然用 **GET 无 body** 调用它 —— 结果实测 `GET /consume → 403`，
+ * 会话跳转刚修好又被我自己打断。
+ *
+ * 单元测试全绿（H1~H11），因为它们各自只看自己那一半：
+ *   · http-guard 的测试说"写操作要 JSON" ✅
+ *   · client 的测试说"返回值是对象" ✅
+ *   · **没有测试把两端接起来跑一次真实请求** ❌
+ *
+ * 所以这个文件起一个**真实的 HTTP 服务器**（用 Node 内置 http），
+ * 把插件的真实 handler 挂上去，再用**客户端真实的调用方式**打过去。
+ *
+ * 这样"客户端怎么发"和"服务端怎么判"就在同一个测试里对齐了。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { once } from 'node:events';
+
+import { createConfigRoute } from '../lib/config-route.js';
+import { createSessionBridge, ROUTE_PREFIX } from '../lib/session-bridge.js';
+import { checkLocalOrigin, throttle, __resetThrottle } from '../lib/http-guard.js';
+
+/**
+ * 起一个临时服务器，把「路由分流 + guard」按 index.js 的方式接起来。
+ *
+ * 刻意**复制** index.js 的分流逻辑而不是 import 它：
+ * index.js 会加载整个插件（依赖 DSH 上下文），在纯 Node 里跑不起来。
+ * 代价是这份逻辑与 index.js 有重复 —— 所以下面 E7 会断言两者的
+ * 关键判据一致，防止单边漂移。
+ */
+async function startServer() {
+  const bridge = createSessionBridge();
+  const configRoute = createConfigRoute({
+    read: () => ({}),
+    effective: () => ({}),
+    notifyChanged: () => {},
+  });
+
+  const server = createServer((req, res) => {
+    const raw = String(req.url || '');
+    const pathname = raw.split('?')[0].split('#')[0];
+    const rest = pathname.startsWith(ROUTE_PREFIX)
+      ? pathname.slice(ROUTE_PREFIX.length)
+      : pathname;
+    const head = rest.replace(/^\/+/, '').split('/')[0];
+
+    // 与 index.js 完全一致的两条判定
+    const isWriteRoute = (head === 'config' && /\/set\b/.test(pathname)) || head === 'consume';
+    const guard = checkLocalOrigin(req, { write: isWriteRoute });
+    if (!guard.ok) {
+      res.writeHead(403, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, reason: guard.reason }));
+      return;
+    }
+
+    if (head === 'config') return configRoute.handler(req, res);
+    if (head === 'preview' || head === 'selftest') {
+      const g = throttle(head, 3000);
+      if (!g.ok) {
+        res.writeHead(429, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, reason: 'throttled' }));
+        return;
+      }
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, kind: head }));
+      return;
+    }
+    return bridge.handler(req, res);
+  });
+
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const { port } = server.address();
+
+  return {
+    port,
+    base: `http://127.0.0.1:${port}`,
+    bridge,
+    async close() {
+      server.close();
+      await once(server, 'close');
+    },
+  };
+}
+
+/** 发一个真实请求（可控 method / headers / body）。 */
+async function call(base, path, { method = 'GET', headers = {}, body } = {}) {
+  const res = await fetch(base + ROUTE_PREFIX + path, { method, headers, body });
+  const text = await res.text();
+  return { status: res.status, text, json: text ? JSON.parse(text) : null };
+}
+
+/**
+ * 从 client.js 源码里解析出 consume 的真实调用方式。
+ *
+ * ## 为什么要这么绕
+ *
+ * 我第一版 E1 是**手写**一份"看起来对"的请求（POST + JSON）。
+ * 但这有个致命弱点（实测暴露）：把客户端改回 GET 后，E1 依然全绿 ——
+ * 因为它根本没读客户端代码，测的是我自己写的那份。
+ *
+ * 现在改成**从源码里抠出 method / 是否要求 JSON**，
+ * 客户端一改回 GET，这里解析结果就变，E1 立刻变红。
+ */
+function clientConsumeShape() {
+  const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const src = readFileSync(join(ROOT, 'lib', 'client.js'), 'utf8');
+
+  // 定位 consume 那一段 fetch（从 apiUrl('consume') 起 300 字符内）
+  const at = src.indexOf("apiUrl('consume')");
+  assert.ok(at >= 0, 'client.js 里应有 apiUrl(\'consume\')');
+  const seg = src.slice(at, at + 400);
+
+  const method = /method:\s*'([A-Z]+)'/.exec(seg);
+  const hasJson = /content-type'\s*:\s*'application\/json'/.test(seg);
+  return {
+    method: (method ? method[1] : 'GET').toUpperCase(),
+    hasJson,
+    seg,
+  };
+}
+
+// ── E0: 客户端 consume 必须是 POST + JSON（源码级契约）───────────────────
+test('E0: client.js 里 consume 的调用必须是 POST 且带 JSON content-type', () => {
+  const shape = clientConsumeShape();
+  assert.equal(shape.method, 'POST',
+    'consume 会清除服务端状态，必须用 POST；用 GET 会被 guard 拒绝（实测 403）');
+  assert.equal(shape.hasJson, true,
+    '必须声明 content-type: application/json —— 否则写操作会被 guard 拒为 write-requires-json');
+});
+
+// ── E1: 客户端真实调用方式能消费成功（核心回归）──────────────────────────
+test('E1: 按 client.js 的真实调用形状发请求能拿到会话（不是 403）', async () => {
+  __resetThrottle();
+  const srv = await startServer();
+  try {
+    srv.bridge.setLast('sess-e1', Date.now());
+
+    // **用客户端源码里解析出的形状**，而不是手写一份
+    const shape = clientConsumeShape();
+    const headers = { origin: srv.base };
+    if (shape.hasJson) headers['content-type'] = 'application/json';
+    const r = await call(srv.base, '/consume', {
+      method: shape.method,
+      headers,
+      body: shape.method === 'POST' ? '{}' : undefined,
+    });
+
+    assert.equal(r.status, 200,
+      `按客户端形状（${shape.method}）应 200，实际 ${r.status}：${r.text}`);
+    assert.equal(r.json.sessionId, 'sess-e1', '应拿到刚设置的会话');
+  } finally {
+    await srv.close();
+  }
+});
+
+// ── E2: 旧的 GET 调用必须被拒（锁住"必须 POST"的契约）──────────────────
+test('E2: GET /consume 被拒绝（405 或 403，但不是 200）', async () => {
+  const srv = await startServer();
+  try {
+    srv.bridge.setLast('sess-e2', Date.now());
+    const r = await call(srv.base, '/consume', {
+      method: 'GET',
+      headers: { origin: srv.base },
+    });
+    assert.notEqual(r.status, 200,
+      'GET 不应消费成功 —— 这个动作会清除服务端状态，必须 POST');
+    // 405 是服务端语义拒绝；403 是 guard 拒绝。两者都算正确拦截。
+    assert.ok([405, 403].includes(r.status), `应是 405 或 403，实际 ${r.status}`);
+  } finally {
+    await srv.close();
+  }
+});
+
+// ── E3: 消费后信号被清（不会重复跳转）──────────────────────────────────
+test('E3: consume 之后 last-session 为空（消费即清）', async () => {
+  const srv = await startServer();
+  try {
+    srv.bridge.setLast('sess-e3', Date.now());
+    await call(srv.base, '/consume', {
+      method: 'POST',
+      headers: { origin: srv.base, 'content-type': 'application/json' },
+      body: '{}',
+    });
+    const r = await call(srv.base, '/last-session', {
+      method: 'GET',
+      headers: { origin: srv.base },
+    });
+    assert.equal(r.status, 204, `消费后应 204，实际 ${r.status}`);
+  } finally {
+    await srv.close();
+  }
+});
+
+// ── E4: 外部 Origin 写配置被拒（真实请求，不是单测）────────────────────
+test('E4: 外部 Origin 的 config/set 被 403 拒绝', async () => {
+  const srv = await startServer();
+  try {
+    const r = await call(srv.base, '/config/set', {
+      method: 'POST',
+      headers: { origin: 'https://evil.com', 'content-type': 'application/json' },
+      body: JSON.stringify({ values: { volume: 99 } }),
+    });
+    assert.equal(r.status, 403);
+    assert.equal(r.json.reason, 'foreign-origin');
+  } finally {
+    await srv.close();
+  }
+});
+
+// ── E5: 表单式跨站提交被拒（<form> 发不出 JSON）────────────────────────
+test('E5: 表单 content-type 的 config/set 被拒绝', async () => {
+  const srv = await startServer();
+  try {
+    const r = await call(srv.base, '/config/set', {
+      method: 'POST',
+      headers: {
+        origin: srv.base,
+        'content-type': 'application/x-www-form-urlencoded',
+      },
+      body: 'volume=99',
+    });
+    assert.equal(r.status, 403);
+    assert.equal(r.json.reason, 'write-requires-json');
+  } finally {
+    await srv.close();
+  }
+});
+
+// ── E6: 限流在真实请求下生效 ────────────────────────────────────────────
+test('E6: 连续两次 preview，第二次 429', async () => {
+  __resetThrottle();
+  const srv = await startServer();
+  try {
+    const h = { origin: srv.base };
+    const a = await call(srv.base, '/preview?kind=done', { headers: h });
+    const b = await call(srv.base, '/preview?kind=done', { headers: h });
+    assert.equal(a.status, 200, '第一次应放行');
+    assert.equal(b.status, 429, '第二次应被限流');
+  } finally {
+    await srv.close();
+  }
+});
+
+// ── E7: 本测试的分流逻辑必须与 index.js 一致（防单边漂移）───────────────
+test('E7: index.js 的 isWriteRoute 判据与集成测试一致', async () => {
+  const { readFileSync } = await import('node:fs');
+  const { join, resolve, dirname } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const src = readFileSync(join(ROOT, 'lib', 'index.js'), 'utf8');
+
+  assert.match(src, /head === 'consume'/,
+    "index.js 必须把 consume 当作写路由 —— 与集成测试一致");
+  assert.match(src, /checkLocalOrigin\(req, \{ write: isWriteRoute \}\)/,
+    'index.js 必须用同一个 guard 调用形状');
+});
+
+// ── E8: config-route 超限回 413 而不是断连 ──────────────────────────────
+test('E8: 超过 64 KB 的请求体得到 413（连接未被重置）', async () => {
+  const srv = await startServer();
+  try {
+    const big = 'x'.repeat(70 * 1024);
+    const r = await call(srv.base, '/config/set', {
+      method: 'POST',
+      headers: { origin: srv.base, 'content-type': 'application/json' },
+      body: JSON.stringify({ values: { pad: big } }),
+    });
+    // 关键：能读到 status 就说明连接没被提前切断
+    assert.equal(r.status, 413, `应 413，实际 ${r.status}`);
+    assert.equal(r.json.reason, 'body-too-large');
+  } finally {
+    await srv.close();
+  }
+});