agentic-flow-kit 0.2.0

package/templates/_agents/scripts/gen-workflow-index.test.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// gen-workflow-index.mjs 的 fixture 驱动测试
+// 现场构造临时 workflow 根，以「换 cwd」方式运行被测脚本（脚本按相对路径 'workflow/' 读盘）。
+// 断言：①活跃（draft/approved/open）逐行出表、终态折叠进档案计数（含 fixed incident）、验收勾验统计；
+//       ②--check 一致 exit 0 / 漂移 exit 1（失败路径）；③缺 `模块:` 容忍显示 —。
+// 用法：node .agents/scripts/gen-workflow-index.test.mjs（在仓库任意目录执行均可）
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const GEN = path.join(SCRIPT_DIR, 'gen-workflow-index.mjs');
+const USAGE = '用法：node .agents/scripts/gen-workflow-index.test.mjs';
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
+};
+
+const doc = (fm, title, body = '') => `---\n${fm}\n---\n# ${title}\n\n${body}\n`;
+
+// mkfix：建临时 workflow 根（4 个子目录齐备——生成器按目录枚举，缺目录会 throw）
+const mkfix = () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gen-workflow-index-test-'));
+  for (const d of ['intents', 'specs', 'plans', 'incidents']) fs.mkdirSync(path.join(root, 'workflow', d), { recursive: true });
+  const w = path.join(root, 'workflow');
+  fs.writeFileSync(path.join(w, 'intents', '2026-09-21-alpha.md'), doc(
+    '状态: approved\n级别: L1\n日期: 2026-09-21\n模块: pipeline',
+    'INTENT — 在跑的需求甲',
+    '## 验收标准（可测试）\n- [x] 已验项（证据：实跑）\n- [ ] 未验项\n',
+  ), 'utf8');
+  fs.writeFileSync(path.join(w, 'plans', '2026-09-21-alpha.md'), doc(
+    '状态: approved\n级别: L1\n模块: pipeline',
+    'PLAN — 在跑的需求甲',
+  ), 'utf8');
+  fs.writeFileSync(path.join(w, 'plans', '2026-09-19-beta.md'), doc(
+    '状态: done\n级别: L1\n模块: material',
+    'PLAN — 已完结的需求乙',
+  ), 'utf8');
+  fs.writeFileSync(path.join(w, 'incidents', '2026-09-18-gamma.md'), doc(
+    '状态: fixed\n级别: L2\n发现: 2026-09-18\n模块: material',
+    'INCIDENT — 已修复未收口的事故丙',
+  ), 'utf8');
+  fs.writeFileSync(path.join(w, 'intents', '_TEMPLATE.md'), doc('状态: draft\n级别: L1', 'INTENT — 模板不该进表'), 'utf8');
+  return root;
+};
+
+const run = (root, args = []) => spawnSync(process.execPath, [GEN, ...args], { cwd: root, encoding: 'utf8' });
+
+// ---- 场景 1：主路径——活跃逐行 + 终态折叠 + 验收统计 ----
+{
+  const root = mkfix();
+  const r = run(root);
+  const idx = fs.readFileSync(path.join(root, 'workflow', 'INDEX.md'), 'utf8');
+  check('场景 1：生成器 exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 1：活跃 2 行（approved intent + approved plan）', idx.includes('## 活跃（2）'), idx.split('\n').slice(0, 14).join('\n'));
+  check('场景 1：活跃行含 7 字段（类型/级别/状态/日期/模块/标题/验收）',
+    /\| INTENT \| L1 \| approved \| 2026-09-21 \| pipeline \| 在跑的需求甲 \| ☑1\/2 \|/.test(idx),
+    idx.split('\n').filter((l) => l.startsWith('| INTENT')).join('\n'));
+  check('场景 1：终态折叠为档案 2 篇（done plan + fixed incident）', idx.includes('## 档案计数（2，不进表）'), '');
+  check('场景 1：档案按类型×模块计数', idx.includes('| PLAN | material | 1 |') && idx.includes('| INCIDENT | material | 1 |'), '');
+  check('场景 1：终态构成行含 done 1 · fixed 1', /终态构成：.*done 1.*fixed 1/.test(idx), idx.split('\n').slice(-2).join('\n'));
+  check('场景 1：_TEMPLATE.md 不进表', !idx.includes('模板不该进表'), '');
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 2：--check 一致 exit 0 / 漂移 exit 1 / 重生成后复原（失败路径）----
+{
+  const root = mkfix();
+  run(root);
+  const ok = run(root, ['--check']);
+  check('场景 2：生成后 --check exit 0', ok.status === 0, `exit=${ok.status}\n${ok.stdout}${ok.stderr}`);
+  const p = path.join(root, 'workflow', 'intents', '2026-09-21-alpha.md');
+  fs.writeFileSync(p, fs.readFileSync(p, 'utf8').replace('状态: approved', '状态: done'), 'utf8');
+  const drift = run(root, ['--check']);
+  check('场景 2：文档状态变更后 --check exit 1（漂移）', drift.status === 1, `exit=${drift.status}\n${drift.stdout}${drift.stderr}`);
+  check('场景 2：漂移提示含重生成命令', /gen-workflow-index\.mjs 重新生成/.test(drift.stderr), drift.stderr);
+  run(root);
+  const ok2 = run(root, ['--check']);
+  check('场景 2：重生成后 --check 复原 exit 0', ok2.status === 0, `exit=${ok2.status}\n${ok2.stdout}${ok2.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 3：缺 `模块:` 容忍显示 —（不报错、不阻断）----
+{
+  const root = mkfix();
+  const p = path.join(root, 'workflow', 'plans', '2026-09-21-alpha.md');
+  fs.writeFileSync(p, fs.readFileSync(p, 'utf8').replace('模块: pipeline\n', ''), 'utf8');
+  const r = run(root);
+  const idx = fs.readFileSync(path.join(root, 'workflow', 'INDEX.md'), 'utf8');
+  check('场景 3：缺模块字段仍 exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 3：模块列显示 —', /^\| PLAN \| L1 \| approved \| .* \| — \|/m.test(idx), idx.split('\n').filter((l) => l.startsWith('| PLAN | approved')).join('\n'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 4：非法参数 exit 1 ----
+{
+  const root = mkfix();
+  const r = run(root, ['--nope']);
+  check('场景 4：未知参数 exit 1', r.status === 1 && /未知参数/.test(r.stderr), `exit=${r.status}\n${r.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+if (fail) {
+  console.log(`\n${USAGE}`);
+  process.exit(1);
+}
+process.exit(0);

package/templates/_agents/scripts/gen-workflow-metrics.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// workflow 规模与规则面月度快照（2026-09-21，intent 2026-09-21-workflow-metrics-snapshot）
+// 用法：node .agents/scripts/gen-workflow-metrics.mjs [--month YYYY-MM] [--dry-run] [--help]
+// 目的：把「语料膨胀 + 常驻面体积」变成可观测趋势——每月（或按需）跑一次，往 workflow/metrics.md 追加/更新一行。
+// 口径：文档 = 磁盘（对照 gen-workflow-index / 看板，排除 _TEMPLATE.md）；常驻面 = `.agents/rule-budgets.txt`
+//   各条实测（单源，含预算上限），括号内给「预算占用峰值项」。
+// 不做 --check / 不挂门禁：快照是历史记录——任何文档改动都会让「当前值」漂移，拿它做漂移校验只会常红；
+//   规则面的机器约束由 pre-commit 的 rule-budget.sh 负责，本脚本只负责「看见趋势」。
+// 测试：node .agents/scripts/gen-workflow-metrics.test.mjs（fixture 回归，须全绿）
+import fs from 'node:fs';
+import path from 'node:path';
+
+const USAGE = `用法：node .agents/scripts/gen-workflow-metrics.mjs [--month YYYY-MM] [--dry-run] [--help]
+
+事实源：workflow/{intents,specs,plans,incidents}/*.md（排除 _TEMPLATE.md）+ workflow/INDEX.md + .agents/rule-budgets.txt
+产物：workflow/metrics.md —— 每月一行（同月重跑即更新该行，不重复追加）；明细打印在 stdout，不落表。
+选项：
+  --month YYYY-MM   指定月份键（默认取当前月；用于补记历史）
+  --dry-run         只打印将写入的行与明细，不写盘
+  --help            打印本说明`;
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) { console.log(USAGE); process.exit(0); }
+const DRY = args.includes('--dry-run');
+let month = '';
+for (let i = 0; i < args.length; i++) if (args[i] === '--month') month = args[++i] ?? '';
+const unknown = [];
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--dry-run' || a === '--help' || a === '-h') continue;
+  if (a === '--month') { i++; continue; }
+  unknown.push(a);
+}
+if (unknown.length) { console.error(`❌ 未知参数：${unknown.join(' ')}\n\n${USAGE}`); process.exit(1); }
+if (!month) month = new Date().toISOString().slice(0, 7);
+if (!/^\d{4}-\d{2}$/.test(month)) { console.error(`--month 须为 YYYY-MM（现 ${month || '空'}）\n\n${USAGE}`); process.exit(1); }
+
+const WORKFLOW = 'workflow';
+const METRICS_P = path.join(WORKFLOW, 'metrics.md');
+const BUDGETS = path.join('.agents', 'rule-budgets.txt');
+const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
+const ACTIVE_STATUS = ['draft', 'approved', 'open'];
+const BEGIN = '<!-- GENERATED:BEGIN — gen-workflow-metrics.mjs 整段重写，手工说明写在本行之前 -->';
+const END = '<!-- GENERATED:END -->';
+
+const kb = (b) => (b < 1024 * 1024 ? `${(b / 1024).toFixed(1)} KB` : `${(b / 1024 / 1024).toFixed(2)} MB`);
+
+// ---- 语料统计：按类型聚合文件数/字节 + 活跃终态 + 模块已填 ----
+function scanDocs() {
+  const perType = {};
+  let files = 0;
+  let bytes = 0;
+  let active = 0;
+  let withModule = 0;
+  for (const type of DOC_TYPES) {
+    let n = 0;
+    let b = 0;
+    const dir = path.join(WORKFLOW, type);
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+      const p = path.join(dir, f);
+      const text = fs.readFileSync(p, 'utf8');
+      const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      let status = '';
+      let mod = '';
+      if (fm) {
+        for (const line of fm[1].split(/\r?\n/)) {
+          const kv = line.match(/^(\S+):\s*(.*)$/);
+          if (!kv) continue;
+          if (kv[1] === '状态') status = kv[2].trim();
+          if (kv[1] === '模块') mod = kv[2].trim();
+        }
+      }
+      if (ACTIVE_STATUS.includes(status)) active++;
+      if (mod) withModule++;
+      n++;
+      b += fs.statSync(p).size;
+    }
+    perType[type] = { n, b };
+    files += n;
+    bytes += b;
+  }
+  return { perType, files, bytes, active, terminal: files - active, withModule };
+}
+
+// ---- 常驻面：按预算表逐条实测（<glob|dir/> <上限>）----
+// 峰值口径：逐文件条取「该文件」，glob 条取「单篇最大」，目录条取「合计」——三者不混（曾把目录合计除以单篇上限得出 548%）
+function scanSurface() {
+  if (!fs.existsSync(BUDGETS)) return { entries: [], total: 0, peak: null };
+  const entries = [];
+  for (const raw of fs.readFileSync(BUDGETS, 'utf8').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const [pat, limRaw] = line.split(/\s+/);
+    const lim = Number(limRaw);
+    if (!pat || !Number.isFinite(lim)) continue;
+    let sum = 0;
+    let max = 0;
+    let label = pat;
+    if (pat.endsWith('/')) {
+      const dir = pat.slice(0, -1);
+      for (const f of fs.readdirSync(dir)) sum += fs.statSync(path.join(dir, f)).size;
+      max = sum;
+      label = `${pat}（合计）`;
+    } else if (pat.includes('*')) {
+      const dir = path.dirname(pat);
+      const suffix = pat.slice(pat.indexOf('*') + 1);
+      for (const f of fs.readdirSync(dir)) {
+        if (!f.endsWith(suffix)) continue;
+        const s = fs.statSync(path.join(dir, f)).size;
+        sum += s;
+        if (s > max) max = s;
+      }
+      label = `${pat}（单篇最大）`;
+    } else {
+      sum = max = fs.statSync(pat).size;
+    }
+    entries.push({ pat, label, sum, max, lim, pct: (max / lim) * 100, isDir: pat.endsWith('/') });
+  }
+  const total = entries.filter((e) => !e.isDir).reduce((n, e) => n + e.sum, 0);
+  const peak = entries.slice().sort((a, b) => b.pct - a.pct)[0] || null;
+  return { entries, total, peak };
+}
+
+const idxText = fs.existsSync(path.join(WORKFLOW, 'INDEX.md')) ? fs.readFileSync(path.join(WORKFLOW, 'INDEX.md'), 'utf8') : '';
+const idxBytes = Buffer.byteLength(idxText, 'utf8');
+const idxActive = Number((idxText.match(/^## 活跃（(\d+)）/m) || [])[1] ?? NaN);
+
+const docs = scanDocs();
+const surf = scanSurface();
+const row = `| ${month} | ${docs.files}（活跃 ${docs.active} / 终态 ${docs.terminal}） | ${kb(docs.bytes)} | ${docs.withModule}/${docs.files} | ${kb(surf.total)}（峰值 ${surf.peak ? `${surf.peak.pct.toFixed(1)}% ${surf.peak.label}` : '—'}） | ${kb(idxBytes)}（${Number.isNaN(idxActive) ? '—' : idxActive} 行） |`;
+
+// ---- 明细（stdout，不落表）：类型分布 + 逐条预算占用 ----
+console.log(`📅 ${month} 快照`);
+console.log(`  文档：${docs.files} 篇 / ${kb(docs.bytes)}（活跃 ${docs.active} / 终态 ${docs.terminal}）；模块已填 ${docs.withModule}/${docs.files}`);
+for (const [t, v] of Object.entries(docs.perType)) console.log(`    ${t.padEnd(10)} ${String(v.n).padStart(3)} 篇 / ${kb(v.b)}`);
+console.log(`  索引：workflow/INDEX.md ${kb(idxBytes)}（活跃 ${Number.isNaN(idxActive) ? '—' : idxActive} 行）`);
+for (const e of surf.entries) console.log(`    ${e.label.padEnd(44)} ${String(e.max).padStart(6)} / ${String(e.lim).padStart(6)} B（${e.pct.toFixed(1)}%）`);
+console.log(`  常驻面合计：${kb(surf.total)}`);
+console.log(`  ${DRY ? '（--dry-run，未写盘）' : ''}`);
+
+if (DRY) { console.log(`\n将写入行：\n${row}`); process.exit(0); }
+
+// ---- 组装：GENERATED 区内的月表按月份键 upsert（同月重跑覆盖，行序按月升序）----
+const HEADER = `# workflow 规模与规则面月度快照
+
+> 生成器 \`node .agents/scripts/gen-workflow-metrics.mjs\`（每月或有需要时跑；同月重跑即更新该行）。明细（类型分布 / 逐条预算占用）看脚本 stdout，不落表。
+> 口径：文档 = 磁盘（排除 \`_TEMPLATE.md\`）；常驻面 = \`.agents/rule-budgets.txt\` 逐条实测，括号内为「预算占用峰值项」。
+`;
+const TABLE_HEAD = [
+  '| 月份 | 文档（活跃/终态） | 文档字节 | 模块已填/总 | 常驻面字节（预算峰值） | INDEX（活跃行） |',
+  '|---|---|---|---|---|---|',
+];
+const existing = fs.existsSync(METRICS_P) ? fs.readFileSync(METRICS_P, 'utf8') : '';
+let rows = [];
+if (existing.includes(BEGIN) && existing.includes(END)) {
+  rows = existing.slice(existing.indexOf(BEGIN), existing.indexOf(END))
+    .split(/\r?\n/)
+    .filter((l) => /^\|\s*\d{4}-\d{2}\s*\|/.test(l));
+}
+rows = rows.filter((l) => !l.startsWith(`| ${month} `));
+rows.push(row);
+rows.sort((a, b) => a.slice(2, 9).localeCompare(b.slice(2, 9)));
+const inner = `${BEGIN}\n\n${[...TABLE_HEAD, ...rows].join('\n')}\n\n${END}`;
+let out;
+if (existing.includes(BEGIN) && existing.includes(END)) {
+  out = existing.slice(0, existing.indexOf(BEGIN)) + inner + existing.slice(existing.indexOf(END) + END.length);
+} else {
+  out = (existing ? existing.replace(/\s*$/, '') + '\n\n' : HEADER) + inner + '\n';
+}
+fs.writeFileSync(METRICS_P, out, 'utf8');
+console.log(`✅ 已更新 workflow/metrics.md（${month} 行；共 ${rows.length} 个月）`);

package/templates/_agents/scripts/gen-workflow-metrics.test.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// gen-workflow-metrics.mjs 的 fixture 驱动测试
+// 现场构造临时语料（换 cwd 运行被测脚本，脚本按相对路径读 workflow/ 与 .agents/rule-budgets.txt）。
+// 断言：①主路径——类型聚合/活跃终态/模块已填/常驻面峰值/INDEX 活跃行；②同月重跑 upsert 不重复、跨月按月升序；
+//       ③失败路径——非法 --month / 未知参数 exit 1。
+// 用法：node .agents/scripts/gen-workflow-metrics.test.mjs（在仓库任意目录执行均可）
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const GEN = path.join(SCRIPT_DIR, 'gen-workflow-metrics.mjs');
+const USAGE = '用法：node .agents/scripts/gen-workflow-metrics.test.mjs';
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
+};
+
+const doc = (fm, title) => `---\n${fm}\n---\n# ${title}\n`;
+
+const mkfix = () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gen-workflow-metrics-test-'));
+  for (const d of ['intents', 'specs', 'plans', 'incidents']) fs.mkdirSync(path.join(root, 'workflow', d), { recursive: true });
+  fs.mkdirSync(path.join(root, '.agents', 'commands'), { recursive: true });
+  const w = path.join(root, 'workflow');
+  fs.writeFileSync(path.join(w, 'intents', '2026-09-21-a.md'), doc('状态: approved\n级别: L1\n日期: 2026-09-21\n模块: pipeline', 'INTENT — 甲'), 'utf8');
+  fs.writeFileSync(path.join(w, 'plans', '2026-09-21-a.md'), doc('状态: approved\n级别: L1\n模块: pipeline', 'PLAN — 甲'), 'utf8');
+  fs.writeFileSync(path.join(w, 'plans', '2026-09-19-b.md'), doc('状态: done\n级别: L1\n模块: material', 'PLAN — 乙'), 'utf8');
+  fs.writeFileSync(path.join(w, 'incidents', '2026-09-18-c.md'), doc('状态: closed\n级别: L2\n发现: 2026-09-18', 'INCIDENT — 丙'), 'utf8');
+  fs.writeFileSync(path.join(w, 'intents', '_TEMPLATE.md'), doc('状态: draft\n级别: L1', 'INTENT — 模板'), 'utf8');
+  fs.writeFileSync(path.join(w, 'INDEX.md'), '# index fixture\n\n## 活跃（2）\n\n| 类型 |\n|---|\n', 'utf8');
+  // 预算表：AGENTS.md 120B / 上限 100 → 峰值 120%；commands 单篇与合计都远低于上限
+  fs.writeFileSync(path.join(root, '.agents', 'rule-budgets.txt'), [
+    '# fixture 预算表',
+    'AGENTS.md 100',
+    '.agents/commands/*.md 50',
+    '.agents/commands/ 100',
+    '',
+  ].join('\n'), 'utf8');
+  fs.writeFileSync(path.join(root, 'AGENTS.md'), 'x'.repeat(120), 'utf8');
+  fs.writeFileSync(path.join(root, '.agents', 'commands', 'plan.md'), 'y'.repeat(10), 'utf8');
+  return root;
+};
+
+const run = (root, args) => spawnSync(process.execPath, [GEN, ...args], { cwd: root, encoding: 'utf8' });
+const readMetrics = (root) => fs.readFileSync(path.join(root, 'workflow', 'metrics.md'), 'utf8');
+
+// ---- 场景 1：主路径——一行算对 ----
+{
+  const root = mkfix();
+  const r = run(root, ['--month', '2026-09']);
+  const md = fs.existsSync(path.join(root, 'workflow', 'metrics.md')) ? readMetrics(root) : '';
+  check('场景 1：生成 exit 0 且落盘 workflow/metrics.md', r.status === 0 && md.length > 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 1：行含 4（活跃 2 / 终态 2）+ 模块 3/4', /\| 2026-09 \| 4（活跃 2 \/ 终态 2） \| .* \| 3\/4 \|/.test(md), md);
+  check('场景 1：常驻面峰值取最紧项（120.0% AGENTS.md）', /峰值 120\.0% AGENTS\.md/.test(md), md);
+  check('场景 1：常驻面合计 = AGENTS.md + commands 逐文件（130B → 0.1 KB）', /0\.1 KB（峰值/.test(md), md);
+  check('场景 1：INDEX 活跃行解析（2 行）', /（2 行） \|/.test(md), md);
+  check('场景 1：_TEMPLATE.md 不计入（4 篇而非 5 篇）', !/\| 5（/.test(md), md);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 2：同月重跑 upsert 不重复；跨月按月升序 ----
+{
+  const root = mkfix();
+  run(root, ['--month', '2026-09']);
+  run(root, ['--month', '2026-09']);
+  let md = readMetrics(root);
+  const n09 = (md.match(/^\| 2026-09 \|/gm) || []).length;
+  check('场景 2：同月重跑只保留一行', n09 === 1, `${n09} 行\n${md}`);
+  run(root, ['--month', '2026-08']);
+  md = readMetrics(root);
+  const i08 = md.indexOf('| 2026-08 |');
+  const i09 = md.indexOf('| 2026-09 |');
+  check('场景 2：跨月两行且按月升序', i08 > -1 && i09 > -1 && i08 < i09, md);
+  check('场景 2：HEADER 手工说明保留（生成区外内容不丢）', md.includes('# workflow 规模与规则面月度快照'), md);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 3：失败路径 + --dry-run 不写盘 ----
+{
+  const root = mkfix();
+  const bad = run(root, ['--month', '2026-9']);
+  check('场景 3：非法 --month exit 1', bad.status === 1 && /须为 YYYY-MM/.test(bad.stderr), `exit=${bad.status}\n${bad.stderr}`);
+  const unk = run(root, ['--bogus']);
+  check('场景 3：未知参数 exit 1', unk.status === 1 && /未知参数/.test(unk.stderr), `exit=${unk.status}\n${unk.stderr}`);
+  const dry = run(root, ['--dry-run']);
+  check('场景 3：--dry-run 不写盘且打印将写入行', dry.status === 0 && /将写入行/.test(dry.stdout) && !fs.existsSync(path.join(root, 'workflow', 'metrics.md')), dry.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+if (fail) {
+  console.log(`\n${USAGE}`);
+  process.exit(1);
+}
+process.exit(0);

package/templates/_agents/scripts/kb-cache-evict.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// kb-search 结构缓存推送式失效（2026-09-23 intent kb-cache-post-commit-evict）
+// 用途：.githooks/post-commit 把 `git diff-tree --name-only HEAD` 的清单经 stdin 传入，
+//   摘除本次提交触及的 workflow/、wiki/ 文件在 .agents/cache/kb-index.json 中的全部命名空间条目，
+//   收敛 [mtimeMs,size] 两元组的「同刻同尺寸」失效盲区至提交时点。
+// 语义：非阻断维护——一切坏输入（缺缓存/坏 JSON/stdin 不可读）静默 exit 0；命中才回写且保留原 fp。
+// 测试：node .agents/scripts/kb-cache-evict.test.mjs（--cache 指向临时文件，不触真实缓存）
+// 用法：kb-cache-evict.mjs [--files-from <path>] [--cache <path>]；二者缺省时读 stdin 与默认缓存。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const opt = (name) => {
+  const i = args.indexOf(name);
+  return i > -1 ? args[i + 1] : '';
+};
+
+function readList() {
+  const from = opt('--files-from');
+  if (from) {
+    try { return fs.readFileSync(from, 'utf8'); } catch { return ''; }
+  }
+  if (process.stdin.isTTY) return '';
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+const cacheFile = opt('--cache') || path.join(SCRIPT_DIR, '..', 'cache', 'kb-index.json');
+const files = [...new Set(
+  readList()
+    .split(/\r?\n/)
+    .map((s) => s.trim().replace(/\\/g, '/'))
+    .filter((s) => s.startsWith('workflow/') || s.startsWith('wiki/'))
+)];
+if (!files.length) process.exit(0);
+
+let j;
+try { j = JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch { process.exit(0); }
+if (!j || !j.files || typeof j.files !== 'object') process.exit(0);
+
+let removed = 0;
+for (const k of Object.keys(j.files)) {
+  const i = k.lastIndexOf('::');
+  if (i > -1 && files.includes(k.slice(i + 2))) { delete j.files[k]; removed++; }
+}
+if (removed) {
+  try { fs.writeFileSync(cacheFile, JSON.stringify(j)); } catch { /* 只读等写失败：下次查询两元组兜底 */ }
+}
+process.exit(0);

package/templates/_agents/scripts/kb-cache-evict.test.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// kb-cache-evict.mjs 的 fixture 测试（--cache 指临时文件，不触真实缓存）
+// 断言：①跨命名空间摘除命中 key、他 key 原样保留、fp 不变；②范围外清单不动缓存；
+//       ③坏输入（缺文件/坏 JSON/无 files 字段）静默 exit 0；④stdin 管道路径与 --files-from 等价。
+// 用法：node .agents/scripts/kb-cache-evict.test.mjs
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const EVICT = path.join(SCRIPT_DIR, 'kb-cache-evict.mjs');
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
+};
+
+const mkCache = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-evict-test-'));
+  const file = path.join(dir, 'kb-index.json');
+  const entry = (t) => ({ st: [111, 222], kind: 'wf', meta: { 状态: t }, title: 'T', lines: [[1, '(标题)', '# x']] });
+  fs.writeFileSync(file, JSON.stringify({
+    fp: 'FIXFP00000000000',
+    files: {
+      'CWD1::workflow/intents/a.md': entry('done'),
+      'CWD2::workflow/intents/a.md': entry('done'),
+      'CWD1::wiki/测试主题/b.md': entry('done'),
+      'CWD1::workflow/plans/keep.md': entry('approved'),
+      'CWD2::workflow/README.md': entry('draft'),
+    },
+  }), 'utf8');
+  return { dir, file };
+};
+
+const run = (argv, opts = {}) => spawnSync(process.execPath, [EVICT, ...argv], { encoding: 'utf8', ...opts });
+const load = (f) => JSON.parse(fs.readFileSync(f, 'utf8'));
+const LIST = 'workflow/intents/a.md\nwiki/测试主题/b.md\nbackend/Dtos/X.cs\n';
+
+// ---- 场景 1：跨命名空间摘除 + 他 key 与 fp 保留 ----
+{
+  const { dir, file } = mkCache();
+  const lf = path.join(dir, 'list.txt');
+  fs.writeFileSync(lf, LIST, 'utf8');
+  const r = run(['--files-from', lf, '--cache', file]);
+  const j = load(file);
+  check('场景 1：exit 0 且 stderr 空', r.status === 0 && !r.stderr, `exit=${r.status}\n${r.stderr}`);
+  check('场景 1：同 rel 跨两命名空间全摘（a.md×2 + b.md×1）',
+    !('CWD1::workflow/intents/a.md' in j.files) && !('CWD2::workflow/intents/a.md' in j.files) && !('CWD1::wiki/测试主题/b.md' in j.files), Object.keys(j.files).join('\n'));
+  check('场景 1：无关 key 原样保留（keep 与 README 完好，计数 2）',
+    Object.keys(j.files).length === 2 && j.files['CWD1::workflow/plans/keep.md']?.meta?.['状态'] === 'approved' && j.files['CWD2::workflow/README.md']?.meta?.['状态'] === 'draft', Object.keys(j.files).join('\n'));
+  check('场景 1：fp 保持不变', j.fp === 'FIXFP00000000000', j.fp);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ---- 场景 2：范围外清单 → 缓存文件逐字节不动 ----
+{
+  const { dir, file } = mkCache();
+  const before = fs.readFileSync(file);
+  const lf = path.join(dir, 'list.txt');
+  fs.writeFileSync(lf, 'backend/Dtos/X.cs\nwiki\n\n', 'utf8');
+  const r = run(['--files-from', lf, '--cache', file]);
+  check('场景 2：范围外清单 exit 0 且缓存字节不变', r.status === 0 && fs.readFileSync(file).equals(before), `exit=${r.status}`);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ---- 场景 3：坏输入三态静默 exit 0 ----
+{
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-evict-test-'));
+  const lf = path.join(dir, 'list.txt');
+  fs.writeFileSync(lf, 'workflow/intents/a.md\n', 'utf8');
+  const missing = path.join(dir, 'nope.json');
+  const garbage = path.join(dir, 'garbage.json');
+  fs.writeFileSync(garbage, 'not-json{{{', 'utf8');
+  const nofiles = path.join(dir, 'nofiles.json');
+  fs.writeFileSync(nofiles, JSON.stringify({ fp: 'x' }), 'utf8');
+  const a = run(['--files-from', lf, '--cache', missing]);
+  const b = run(['--files-from', lf, '--cache', garbage]);
+  const c = run(['--files-from', lf, '--cache', nofiles]);
+  check('场景 3：缺缓存/坏 JSON/无 files 字段均 exit 0 且无输出',
+    a.status === 0 && b.status === 0 && c.status === 0 && !a.stdout && !b.stdout && !c.stdout && !a.stderr && !b.stderr && !c.stderr,
+    `a=${a.status}/${a.stderr} b=${b.status}/${b.stderr} c=${c.status}/${c.stderr}`);
+  check('场景 3：清单文件缺失也静默 exit 0', run(['--files-from', path.join(dir, 'nope.txt'), '--cache', garbage]).status === 0);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ---- 场景 4：stdin 管道与 --files-from 等价（钩子实际走的路径） ----
+{
+  const { dir, file } = mkCache();
+  const r = run(['--cache', file], { input: LIST });
+  const j = load(file);
+  check('场景 4：stdin 路径摘除同果', r.status === 0 && Object.keys(j.files).length === 2 && !('CWD1::wiki/测试主题/b.md' in j.files), `exit=${r.status} keys=${Object.keys(j.files).join(',')}`);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+if (fail) {
+  console.log('\n用法：node .agents/scripts/kb-cache-evict.test.mjs');
+  process.exit(1);
+}
+process.exit(0);