agentic-flow-kit 0.2.0

package/templates/_agents/scripts/kb-search.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+// 跨语料检索入口（2026-09-21，intent 2026-09-21-workflow-doc-retrieval）
+// 用法：node .agents/scripts/kb-search.mjs [选项] <词1> [词2 ...]（多词 AND，全部命中才算）
+//
+// 语料与口径
+//   workflow（流程留痕）：只搜 frontmatter + H1 + 指定节（背景 / 目标 / 根因 / 复盘三件套 / 验收标准 / 影响面），
+//     默认全状态可命中、活跃（draft/approved/open）排序 ×1.3 优先；输出带「节名 + 行号」便于节级读取。
+//   wiki（领域知识）：沿用 2026-09-21 降噪口径——默认跳过 .json/.csv、*.visual-check.* 与 >180KB bulk 文件。
+//   两侧排序均为 命中数/√文件KB（防大文件靠体量霸榜）；`-n` 为每语料展示上限。
+// 结构缓存（2026-09-23 intent kb-search-structure-cache）：可检索子集预提取进 .agents/cache/kb-index.json，
+//   按 [mtimeMs,size] 逐文件失效，口径指纹变化整份作废；匹配/排序/输出路径不变（三路输出与冷扫逐字节一致）；
+//   缓存任何读写异常静默回退全扫。`--include-generated` 走纯扫（bulk 文件不入缓存）。
+// 测试：node .agents/scripts/kb-search.test.mjs（fixture 回归，须全绿）
+// 模块词表：.agents/workflow-modules.txt（--module 取值校验，单源）
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MODULES_FILE = path.join(SCRIPT_DIR, '..', 'workflow-modules.txt');
+
+const USAGE = `用法: node .agents/scripts/kb-search.mjs [选项] <词1> [词2 ...]（多词 AND）
+
+  --scope <workflow|wiki|all>   检索语料，默认 all（指定 -t 时默认转 wiki）
+  --type <intents,specs,plans,incidents>   workflow：限定文档类型（逗号分隔）
+  --module <词表token>           workflow：按 frontmatter 模块过滤（词表见 .agents/workflow-modules.txt）
+  --status <all|active|terminal> workflow：状态过滤，默认 all（active = draft/approved/open）
+  -t <主题>                      wiki：限定主题目录（如 数据维护）
+  -n <N>                         每语料展示文件数上限，默认 10；0 = 不限
+  --include-generated            wiki：纳入默认跳过的 json/csv、*.visual-check.* 与 >180KB bulk 文件（走纯扫，不吃缓存）
+  --no-cache                     禁用结构缓存，全量扫（与缓存热路径输出逐字节一致）
+  --rebuild                      忽略现有缓存重建后回写
+  --help                         打印本说明
+
+退出码：0 正常（含无命中）；1 参数错误（无词 / 未知选项 / 非法枚举值）`;
+
+const args = process.argv.slice(2);
+let scope = '';
+let scopeExplicit = false;
+let typeFilter = null;
+let moduleFilter = '';
+let statusFilter = 'all';
+let topicFilter = '';
+let limit = 10;
+let limitRaw = '10';
+let includeGenerated = false;
+let noCache = false;
+let rebuild = false;
+const words = [];
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--scope') { scope = args[++i] || ''; scopeExplicit = true; }
+  else if (a === '--type') typeFilter = (args[++i] || '').split(',').map((s) => s.trim()).filter(Boolean);
+  else if (a === '--module') moduleFilter = args[++i] || '';
+  else if (a === '--status') statusFilter = args[++i] || '';
+  else if (a === '-t') topicFilter = args[++i] || '';
+  else if (a === '-n') { limitRaw = args[++i] ?? ''; limit = Number(limitRaw); }
+  else if (a === '--include-generated') includeGenerated = true;
+  else if (a === '--no-cache') noCache = true;
+  else if (a === '--rebuild') rebuild = true;
+  else if (a === '--help' || a === '-h') { console.log(USAGE); process.exit(0); }
+  else words.push(a);
+}
+if (!words.length) { console.error(USAGE); process.exit(1); }
+if (!Number.isFinite(limit) || limit < 0) { console.error(`-n 须为非负整数（现 ${limitRaw}）\n\n${USAGE}`); process.exit(1); }
+if (!scope) scope = topicFilter ? 'wiki' : 'all';
+if (!['workflow', 'wiki', 'all'].includes(scope)) { console.error(`--scope 须为 workflow|wiki|all（现 ${scope}）\n\n${USAGE}`); process.exit(1); }
+if (!['all', 'active', 'terminal'].includes(statusFilter)) { console.error(`--status 须为 all|active|terminal（现 ${statusFilter}）\n\n${USAGE}`); process.exit(1); }
+const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
+if (typeFilter && typeFilter.some((t) => !DOC_TYPES.includes(t))) {
+  console.error(`--type 取值须为 ${DOC_TYPES.join('|')}（现 ${typeFilter.join(',')}）\n\n${USAGE}`);
+  process.exit(1);
+}
+const MODULES = fs.readFileSync(MODULES_FILE, 'utf8').split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+if (moduleFilter && !MODULES.includes(moduleFilter)) {
+  console.error(`--module 未知模块：${moduleFilter}（词表见 .agents/workflow-modules.txt：${MODULES.join(' / ')}）\n\n${USAGE}`);
+  process.exit(1);
+}
+
+const ACTIVE_STATUS = ['draft', 'approved', 'open']; // 与 workflow/INDEX.md 活跃口径一致（fixed 归档案，默认也可命中）
+const WF_SECTIONS = ['背景', '目标', '根因', '复盘三件套', '验收标准', '影响面'];
+const WIKI_EXCLUDE = new Set(['INDEX.md', '知识沉淀总览.html']);
+const WIKI_MAX_KB = 180;
+
+// ---- frontmatter（受限子集：每行 `键: 值`）+ H1 标题（去「INTENT — 」前缀）----
+function parseDoc(text) {
+  const meta = {};
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (m) {
+    for (const line of m[1].split(/\r?\n/)) {
+      const kv = line.match(/^(\S+):\s*(.*)$/);
+      if (kv) meta[kv[1].trim()] = kv[2].trim();
+    }
+  }
+  const h1 = text.match(/^# (.+)$/m);
+  let title = h1 ? h1[1] : '';
+  const dash = title.match(/\S+\s*[—–-]+\s*(.+)$/);
+  if (dash) title = dash[1];
+  return { meta, title };
+}
+
+// ---- workflow 侧可检索行：frontmatter + H1 + 指定节（节名随 `## ` 标题滚动）；词过滤在调用方，缓存存词无关子集 ----
+function workflowLines(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let i = 0;
+  if (/^---\s*$/.test(lines[0] || '')) {
+    out.push({ ln: 1, section: '(frontmatter)', line: lines[0] });
+    for (i = 1; i < lines.length; i++) {
+      out.push({ ln: i + 1, section: '(frontmatter)', line: lines[i] });
+      if (/^---\s*$/.test(lines[i])) { i++; break; }
+    }
+  }
+  let section = '';
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    const h2 = line.match(/^## (.+?)\s*$/);
+    if (h2) section = h2[1];
+    if (/^# /.test(line) && !/^## /.test(line)) { out.push({ ln: i + 1, section: '(标题)', line }); section = ''; continue; }
+    if (WF_SECTIONS.some((s) => section.startsWith(s))) out.push({ ln: i + 1, section, line });
+  }
+  return out;
+}
+
+function matchWords(lines, words) {
+  const byWord = words.map((w) => lines.filter((x) => x.line.includes(w)));
+  if (byWord.some((h) => h.length === 0)) return null; // AND：任一词未命中即跳过
+  const total = byWord.reduce((n, h) => n + h.length, 0);
+  const shown = [...new Map(lines.map((x) => [x.ln, x])).values()].sort((a, b) => a.ln - b.ln).slice(0, 3);
+  return { total, shown };
+}
+
+// ---- 结构缓存：可检索子集预提取，[mtimeMs,size] 两元组逐文件失效，指纹变即整份作废 ----
+// 键 = <检索根 cwd>::<相对路径>（多语料根共存一文件，fixture 临时目录天然隔离）；读写任何异常静默回退全扫。
+const CACHE_DIR = path.join(SCRIPT_DIR, '..', 'cache');
+const CACHE_FILE = path.join(CACHE_DIR, 'kb-index.json');
+const ROOT_NS = `${path.resolve('.')}::`;
+const CFG_FP = createHash('sha256').update(JSON.stringify({
+  v: 1, WF_SECTIONS, ACTIVE_STATUS, WIKI_MAX_KB, excl: [...WIKI_EXCLUDE],
+  exts: ['md', 'sql', 'html', 'txt', 'gen:csv|json'],
+  fns: [parseDoc.toString(), workflowLines.toString(), matchWords.toString()],
+})).digest('hex').slice(0, 16);
+const cacheUsable = !noCache && !includeGenerated;
+let cache = null;
+const touched = new Set();
+if (cacheUsable) {
+  try {
+    const j = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    cache = j && j.fp === CFG_FP && j.files && typeof j.files === 'object' ? j.files : {};
+  } catch { cache = {}; }
+  if (rebuild) cache = {};
+}
+
+const serializeLines = (lines, kind) => lines.map((x) => (kind === 'wf' ? [x.ln, x.section, x.line] : [x.ln, x.line]));
+const reviveLines = (lines, kind) => lines.map((a) => (kind === 'wf' ? { ln: a[0], section: a[1], line: a[2] } : { ln: a[0], line: a[1] }));
+
+// 取一个源文件的缓存条目；miss 时 build()（读全文提取可检索子集）并登记回写。返回 {st, meta?, title?, lines}
+function cachedEntry(relPath, kind, build) {
+  const abs = path.resolve(relPath);
+  if (!cache) {
+    const e = build();
+    e.st = [fs.statSync(abs).mtimeMs, fs.statSync(abs).size];
+    return e;
+  }
+  const key = ROOT_NS + relPath.split(path.sep).join('/');
+  const st = fs.statSync(abs);
+  const sig = [st.mtimeMs, st.size];
+  const e = cache[key];
+  if (e && e.kind === kind && Array.isArray(e.st) && e.st[0] === sig[0] && e.st[1] === sig[1]) {
+    touched.add(key);
+    return { st: e.st, meta: e.meta, title: e.title, lines: reviveLines(e.lines, kind) };
+  }
+  const built = build();
+  cache[key] = {
+    st: sig, kind,
+    ...(kind === 'wf' ? { meta: built.meta, title: built.title } : {}),
+    lines: serializeLines(built.lines, kind),
+  };
+  touched.add(key);
+  return { st: sig, meta: built.meta, title: built.title, lines: built.lines };
+}
+
+function saveCache() {
+  if (!cache) return;
+  try {
+    for (const k of Object.keys(cache)) {
+      if (!k.startsWith(ROOT_NS) || touched.has(k)) continue;
+      const rel = k.slice(ROOT_NS.length).replace(/\//g, path.sep);
+      try {
+        const st = fs.statSync(rel);
+        const e = cache[k];
+        if (e.st[0] !== st.mtimeMs || e.st[1] !== st.size) delete cache[k];
+      } catch { delete cache[k]; }
+    }
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({ fp: CFG_FP, files: cache }));
+  } catch { /* 只读目录 / 并发写等异常：放弃回写，下次重建 */ }
+}
+
+// ---- workflow 检索 ----
+function searchWorkflow(words) {
+  const results = [];
+  for (const type of (typeFilter || DOC_TYPES)) {
+    const dir = path.join('workflow', type);
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+      const p = path.join(dir, f);
+      const e = cachedEntry(p, 'wf', () => {
+        const text = fs.readFileSync(p, 'utf8');
+        const { meta, title } = parseDoc(text);
+        return { meta, title, lines: workflowLines(text) };
+      });
+      const meta = e.meta || {};
+      const status = meta['状态'] || '';
+      const module = meta['模块'] || '—';
+      if (moduleFilter && module !== moduleFilter) continue;
+      if (statusFilter === 'active' && !ACTIVE_STATUS.includes(status)) continue;
+      if (statusFilter === 'terminal' && ACTIVE_STATUS.includes(status)) continue;
+      const hits = matchWords(e.lines.filter((x) => words.some((w) => x.line.includes(w))), words);
+      if (!hits) continue;
+      const kb = e.st[1] / 1024;
+      const active = ACTIVE_STATUS.includes(status);
+      results.push({
+        file: `${type}/${f}`, title: e.title || '', status, level: meta['级别'] || '—', module,
+        total: hits.total, shown: hits.shown, kb,
+        score: (hits.total / Math.sqrt(Math.max(kb, 0.1))) * (active ? 1.3 : 1),
+      });
+    }
+  }
+  return results.sort((a, b) => b.score - a.score);
+}
+
+// ---- wiki 检索（口径同 2026-09-21 降噪版 wiki-search）----
+const WIKI_EXTS = includeGenerated ? /\.(md|sql|html|csv|json|txt)$/i : /\.(md|sql|html|txt)$/i;
+const walkWiki = (dir, rel) => {
+  const out = [];
+  for (const e of fs.readdirSync(dir)) {
+    const p = path.join(dir, e);
+    if (fs.statSync(p).isDirectory()) { out.push(...walkWiki(p, `${rel}/${e}`)); continue; }
+    if (!WIKI_EXTS.test(e) || WIKI_EXCLUDE.has(e)) continue;
+    out.push({ fsPath: p, key: `${rel}/${e}` });
+  }
+  return out;
+};
+
+function searchWiki(words) {
+  const results = [];
+  let skipped = 0;
+  if (!fs.existsSync('wiki')) return { results, skipped };
+  for (const d of fs.readdirSync('wiki')) {
+    const dir = path.join('wiki', d);
+    if (!fs.statSync(dir).isDirectory() || d === 'drafts-archive') continue;
+    if (topicFilter && d !== topicFilter) continue;
+    for (const { fsPath: p, key } of walkWiki(dir, d)) {
+      const size = fs.statSync(p).size;
+      if (!includeGenerated && (/\.visual-check\./i.test(path.basename(p)) || size > WIKI_MAX_KB * 1024)) { skipped++; continue; }
+      const e = cachedEntry(p, 'wiki', () => {
+        let text;
+        try { text = fs.readFileSync(p, 'utf8'); } catch { return { lines: [] }; }
+        return { lines: text.split('\n').map((line, i) => ({ ln: i + 1, line })) };
+      });
+      if (!e.lines.length) continue;
+      const hits = matchWords(e.lines.filter((x) => words.some((w) => x.line.includes(w))), words);
+      if (!hits) continue;
+      const kb = size / 1024;
+      results.push({ file: key, total: hits.total, shown: hits.shown, kb, score: hits.total / Math.sqrt(Math.max(kb, 0.1)) });
+    }
+  }
+  return { results: results.sort((a, b) => b.score - a.score), skipped };
+}
+
+// ---- 输出 ----
+const top = (arr) => (limit ? arr.slice(0, limit) : arr);
+let anyHits = 0;
+
+if (scope === 'workflow' || scope === 'all') {
+  const res = searchWorkflow(words);
+  anyHits += res.length;
+  const shown = top(res);
+  console.log(`── workflow（${res.length} 个文件命中${res.length > shown.length ? `，展示前 ${shown.length}` : ''}）──`);
+  for (const r of shown) {
+    console.log(`📄 workflow/${r.file} — ${r.status || '未填状态'} · ${r.level} · ${r.module} · ${r.total} 处命中 / ${r.kb < 10 ? r.kb.toFixed(1) : Math.round(r.kb)}KB`);
+    for (const h of r.shown) console.log(`   [${h.section}] L${h.ln}: ${h.line.trim().slice(0, 130)}`);
+  }
+  if (!res.length) console.log('（无命中）');
+}
+
+if (scope === 'wiki' || scope === 'all') {
+  const { results: res, skipped } = searchWiki(words);
+  anyHits += res.length;
+  const shown = top(res);
+  console.log(`── wiki（${res.length} 个文件命中${res.length > shown.length ? `，展示前 ${shown.length}` : ''}）──`);
+  for (const r of shown) {
+    console.log(`📄 wiki/${r.file} — ${r.total} 处命中 / ${r.kb < 10 ? r.kb.toFixed(1) : Math.round(r.kb)}KB`);
+    for (const h of r.shown) console.log(`   L${h.ln}: ${h.line.trim().slice(0, 130)}`);
+  }
+  if (!res.length) console.log('（无命中）');
+  if (skipped) console.log(`（wiki 跳过 ${skipped} 个产物/大文件——--include-generated 纳入）`);
+}
+
+console.log(`\n${anyHits ? `合计 ${anyHits} 个文件命中（${words.join(' AND ')}）` : `无命中（${words.join(' AND ')}）`}` +
+  `；排序：命中数/√文件KB${scope === 'workflow' ? '' : '（workflow 侧活跃 ×1.3）'}` +
+  (scope === 'all' ? '；`--scope` 限定语料、`--status all` 显式全量' : ''));
+
+saveCache();

package/templates/_agents/scripts/kb-search.test.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// kb-search.mjs 的 fixture 驱动测试
+// 现场构造临时 workflow 语料（换 cwd 运行被测脚本，脚本按相对路径 'workflow/' 读盘）。
+// 断言：①AND 语义与「节限定」（指定节外的内容不参与命中）；②活跃优先排序（同命中近同体积时 active 在前）；
+//       ③过滤与上限（--type / --module / --status / -n）；④失败路径（非法模块、无词 → exit 1）；
+//       ⑤结构缓存三路逐字节等值（cold/warm/--no-cache）；⑥增量失效（改 1 文件仅该文件重解析）；
+//       ⑦口径指纹变化整份作废；⑧缓存损坏静默回退全扫。
+// 用法：node .agents/scripts/kb-search.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 KB = path.join(SCRIPT_DIR, 'kb-search.mjs');
+const CACHE_FILE = path.join(SCRIPT_DIR, '..', 'cache', 'kb-index.json');
+const USAGE = '用法：node .agents/scripts/kb-search.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, sections) =>
+  `---\n${fm}\n---\n# ${title}\n\n${sections.map(([h, body]) => `## ${h}\n${body}\n`).join('\n')}\n`;
+
+// mkfix：甲（closed，incidents）/ 乙（approved，intents）同命中近同体积（验活跃优先）；
+//       丙（approved，plans）只含单词（验 AND）、其「非目标」节含标记词（验节限定）
+const mkfix = () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-search-test-'));
+  for (const d of ['intents', 'plans', 'incidents']) fs.mkdirSync(path.join(root, 'workflow', d), { recursive: true });
+  const w = path.join(root, 'workflow');
+  const hit = (tag) => [
+    ['目标', `- 统一口径：编码模板与分类层级，冲突处理见 A/B${tag}`],
+    ['非目标', '- MARKER_ONLY_OUTSIDE_SECTIONS（本节不参与检索，词：编码模板）'],
+  ];
+  fs.writeFileSync(path.join(w, 'incidents', '2026-09-01-aaa.md'), doc('状态: closed\n级别: L2\n发现: 2026-09-01\n模块: material', 'INCIDENT — 甲事故', hit('甲')), 'utf8');
+  fs.writeFileSync(path.join(w, 'intents', '2026-09-21-bbb.md'), doc('状态: approved\n级别: L1\n日期: 2026-09-21\n模块: pipeline', 'INTENT — 乙需求', hit('乙')), 'utf8');
+  fs.writeFileSync(path.join(w, 'plans', '2026-09-20-ccc.md'), doc('状态: approved\n级别: L1\n模块: purchase', 'PLAN — 丙计划', [['目标', '- 只讲编码模板，不提另一个词'], ['非目标', '- MARKER_ONLY_OUTSIDE_SECTIONS（本节不参与检索）']]), 'utf8');
+  // wiki 侧最小语料（验结构缓存对 wiki 行数组的存取路径）
+  fs.mkdirSync(path.join(root, 'wiki', '测试主题'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'wiki', '测试主题', '说明.md'), '# 说明\n\n编码模板的领域知识条目。\n', 'utf8');
+  return root;
+};
+
+const run = (root, args) => spawnSync(process.execPath, [KB, ...args], { cwd: root, encoding: 'utf8' });
+const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l.replace('📄 ', ''));
+
+// ---- 场景 1：主路径——AND 语义 / 节限定 / 输出字段 / 活跃优先 ----
+{
+  const root = mkfix();
+  const r = run(root, ['--scope', 'workflow', '编码模板', '冲突']);
+  check('场景 1：检索 exit 0', r.status === 0, `exit=${r.status}\n${r.stderr}`);
+  check('场景 1：AND——两词齐全才命中（甲/乙，丙被排除）', files(r.stdout).length === 2 && !r.stdout.includes('2026-09-20-ccc.md'), r.stdout);
+  check('场景 1：活跃优先——approved 的乙排在 closed 的甲之前', files(r.stdout)[0]?.includes('2026-09-21-bbb.md'), files(r.stdout).join('\n'));
+  check('场景 1：输出行含 状态·级别·模块', /📄 workflow\/intents\/2026-09-21-bbb\.md — approved · L1 · pipeline ·/.test(r.stdout), r.stdout);
+  check('场景 1：命中带节名与行号', /\[目标\] L\d+: /.test(r.stdout), r.stdout);
+  const outside = run(root, ['--scope', 'workflow', 'MARKER_ONLY_OUTSIDE_SECTIONS']);
+  check('场景 1：节外内容不参与检索（仅标记词 → 无命中）', files(outside.stdout).length === 0 && /（无命中）/.test(outside.stdout), outside.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 2：过滤与上限（--type / --module / --status / -n）----
+{
+  const root = mkfix();
+  const t = run(root, ['--scope', 'workflow', '--type', 'plans', '编码模板']);
+  check('场景 2：--type plans 仅出 plans', files(t.stdout).length === 1 && files(t.stdout)[0].includes('plans/'), t.stdout);
+  const m = run(root, ['--scope', 'workflow', '--module', 'pipeline', '编码模板']);
+  check('场景 2：--module pipeline 仅出该模块', files(m.stdout).length === 1 && files(m.stdout)[0].includes('2026-09-21-bbb.md'), m.stdout);
+  const a = run(root, ['--scope', 'workflow', '--status', 'active', '编码模板']);
+  check('场景 2：--status active 排除终态', !a.stdout.includes('2026-09-01-aaa.md') && a.stdout.includes('2026-09-21-bbb.md'), a.stdout);
+  const term = run(root, ['--scope', 'workflow', '--status', 'terminal', '编码模板']);
+  check('场景 2：--status terminal 仅终态', term.stdout.includes('2026-09-01-aaa.md') && !term.stdout.includes('2026-09-21-bbb.md'), term.stdout);
+  const n1 = run(root, ['--scope', 'workflow', '-n', '1', '编码模板']);
+  check('场景 2：-n 1 只展示 1 个文件', files(n1.stdout).length === 1, n1.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 3：失败路径（非法模块 / 无词 / 无命中）----
+{
+  const root = mkfix();
+  const bad = run(root, ['--module', '不存在的模块', '编码模板']);
+  check('场景 3：非法 --module exit 1 且提示词表', bad.status === 1 && /未知模块/.test(bad.stderr), `exit=${bad.status}\n${bad.stderr}`);
+  const empty = run(root, []);
+  check('场景 3：无词 exit 1', empty.status === 1, `exit=${empty.status}`);
+  const none = run(root, ['--scope', 'workflow', 'zzz-绝不存在-zzz']);
+  check('场景 3：无命中 exit 0 且提示', none.status === 0 && /（无命中）/.test(none.stdout), none.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 4：结构缓存三路逐字节等值（cold 首建 / warm 命中 / --no-cache），workflow+wiki 双侧 ----
+{
+  const root = mkfix();
+  const cold = run(root, ['编码模板']);                                   // 该临时根 ns 无条目 → cold
+  const warm = run(root, ['编码模板']);                                   // 全命中缓存
+  const nocache = run(root, ['--no-cache', '编码模板']);
+  check('场景 4：cold/warm exit 0 且 warm 确有缓存回写', cold.status === 0 && warm.status === 0 && fs.existsSync(CACHE_FILE), `cold=${cold.status} warm=${warm.status}`);
+  check('场景 4：cold ≡ warm（逐字节）', cold.stdout === warm.stdout, `cold:\n${cold.stdout}\nwarm:\n${warm.stdout}`);
+  check('场景 4：cold ≡ --no-cache（逐字节）', cold.stdout === nocache.stdout, `cold:\n${cold.stdout}\nnocache:\n${nocache.stdout}`);
+  check('场景 4：双侧均有命中（workflow 3 + wiki 1）', files(cold.stdout).length === 3 && /wiki\/测试主题/.test(cold.stdout), cold.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 5：增量失效——warm 后改 1 个源文件，仅该文件重解析且输出与纯扫一致 ----
+{
+  const root = mkfix();
+  const base = run(root, ['编码模板']);
+  const planP = path.join(root, 'workflow', 'plans', '2026-09-20-ccc.md');
+  fs.appendFileSync(planP, '\n## 影响面\n- 新标记NEWWORD：编码模板修订\n', 'utf8');
+  const after = run(root, ['编码模板', 'NEWWORD']);
+  const scan = run(root, ['--no-cache', '编码模板', 'NEWWORD']);
+  check('场景 5：改动文件被重解析（NEWWORD 命中该篇）', after.status === 0 && after.stdout.includes('2026-09-20-ccc.md'), after.stdout);
+  check('场景 5：增量结果与纯扫逐字节一致', after.stdout === scan.stdout, `after:\n${after.stdout}\nscan:\n${scan.stdout}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 6：口径指纹变化 → 整份作废重建，无旧口径残留 ----
+{
+  const root = mkfix();
+  run(root, ['编码模板']); // 建缓存
+  const j = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+  const fpBefore = j.fp;
+  j.fp = 'ffffffffffffffff';
+  fs.writeFileSync(CACHE_FILE, JSON.stringify(j), 'utf8');
+  const after = run(root, ['编码模板']);
+  const scan = run(root, ['--no-cache', '编码模板']);
+  check('场景 6：指纹不符 → 输出仍与纯扫逐字节一致', after.status === 0 && after.stdout === scan.stdout, `after:\n${after.stdout}\nscan:\n${scan.stdout}`);
+  const j2 = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+  check('场景 6：回写恢复正确指纹', j2.fp === fpBefore && j2.fp !== 'ffffffffffffffff', `fp=${j2.fp}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 7：缓存损坏 → 静默回退全扫（不报错、输出与 --no-cache 一致） ----
+{
+  const root = mkfix();
+  fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+  fs.writeFileSync(CACHE_FILE, 'not-json{{{', 'utf8');
+  const r = run(root, ['编码模板']);
+  const scan = run(root, ['--no-cache', '编码模板']);
+  check('场景 7：损坏缓存 exit 0（stderr 无泄漏）', r.status === 0 && !r.stderr, `exit=${r.status}\n${r.stderr}`);
+  check('场景 7：损坏后输出与纯扫逐字节一致', r.stdout === scan.stdout, `r:\n${r.stdout}\nscan:\n${scan.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/rule-budget.sh

@@ -0,0 +1,68 @@
+#!/bin/sh
+# 常驻面体积预算检查（单源：本脚本 + .agents/rule-budgets.txt；两个触发点共用）
+# 用法：sh .agents/scripts/rule-budget.sh [--all|--staged]
+#   --all     查「提交后树」全量（check-loop.sh 检查 13 调用，warning 侧）
+#   --staged  仅查本次暂存触及的条目 + 触及目录的合计（.githooks/pre-commit 调用，超限即硬拦）
+# 退出码：0 通过；1 有超限（违例逐条打到 stdout，调用方决定警告还是阻断）
+# 「提交后树」= 索引（index）内容：staged 版优先于 HEAD；无 git（fixture 沙箱）时回退工作区文件。
+# 预算表按字节读，显式去 \r——本仓库 core.autocrlf=true，表文件检出即 CRLF，行尾残留会让数值比较失配。
+# 字节口径 = 索引 / HEAD 内容（git cat-file，LF 归一）。**禁用 wc -c 核对**——工作区文件是 CRLF，量出来系统性偏大
+# （2026-09-21 实测 .agents/commands/ 工作区 39963B vs 索引 39451B，差 ~500B，一度误判「已超限」）。
+cd "$(git rev-parse --show-toplevel 2>/dev/null)" || true   # 非 git 环境（fixture）留在原地
+MODE=${1:---all}
+BUDGETS=.agents/rule-budgets.txt
+[ -f "$BUDGETS" ] || exit 0
+
+# 取「提交后」字节数：索引 → HEAD → 工作区
+fsize() { # <path>
+  if git cat-file -e ":$1" 2>/dev/null; then git cat-file -s ":$1"
+  elif git cat-file -e "HEAD:$1" 2>/dev/null; then git cat-file -s "HEAD:$1"
+  else wc -c < "$1" 2>/dev/null | tr -d '[:space:]'
+  fi
+}
+
+staged_list=""
+if [ "$MODE" = "--staged" ]; then
+  staged_list=$(git -c core.quotepath=off diff --cached --name-only 2>/dev/null)
+fi
+
+viol=0
+while IFS= read -r line; do
+  line=$(printf '%s' "$line" | tr -d '\r')
+  pat=${line%% *}
+  lim=${line##* }
+  case "$pat" in ''|'#'*) continue ;; esac
+  case "$lim" in ''|*[!0-9]*) continue ;; esac
+  case "$pat" in
+    */) # 目录合计：--staged 下仅当暂存触及该目录内文件才查
+      if [ "$MODE" = "--staged" ]; then
+        printf '%s\n' "$staged_list" | grep -q "^${pat}" || continue
+      fi
+      total=0
+      for f in "$pat"*; do
+        [ -f "$f" ] || continue
+        total=$((total + $(fsize "$f")))
+      done
+      if [ "$total" -gt "$lim" ]; then
+        echo "常驻面超限：${pat} 合计 ${total}B > 上限 ${lim}B"
+        viol=1
+      fi
+      ;;
+    *) # 逐文件（glob 刻意不加引号以展开；无命中时 [ -f ] 兜住）
+      for f in $pat; do
+        [ -f "$f" ] || continue
+        if [ "$MODE" = "--staged" ]; then
+          printf '%s\n' "$staged_list" | grep -qxF "$f" || continue
+        fi
+        b=$(fsize "$f")
+        if [ "$b" -gt "$lim" ]; then
+          echo "常驻面超限：$f = ${b}B > 上限 ${lim}B"
+          viol=1
+        fi
+      done
+      ;;
+  esac
+done < "$BUDGETS"
+
+[ "$viol" -eq 0 ] || exit 1
+exit 0