agentic-flow-kit 0.2.0

package/templates/_agents/scripts/ensure-board.ps1

@@ -0,0 +1,48 @@
+# ensure-board.ps1 — 任务入口幂等拉起 workflow 看板（只起不关：Windows 重启即天然回收，无需 stop/status）
+# 行为：探活（端口占用者须响应 /api/board 才认定为看板，否则不动手、报占用者并 exit 1）
+#       → 前端或服务端任一代码早于进程 = 旧代码自动 kill 重启 → 全新启动成功后弹浏览器（重启/已运行不弹，SSE 自动重连）
+# 用法：powershell -NoProfile -File .agents/scripts/ensure-board.ps1 [-Port 8933] [-NoOpen]
+param(
+  [int]$Port = 8933,
+  [switch]$NoOpen
+)
+$ErrorActionPreference = 'Stop'
+$agentsDir = Split-Path -Parent $PSScriptRoot
+$server = Join-Path $PSScriptRoot 'workflow-board-server.mjs'
+$boardHtml = Join-Path $agentsDir 'board\index.html'
+$codeFiles = @($boardHtml, $server)   # 前端 + 服务端：任一更新都算「旧代码」
+$url = "http://127.0.0.1:$Port"
+
+$proc = $null
+$conn = Get-NetTCPConnection -LocalPort $Port -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1
+if ($conn) { $proc = Get-Process -Id $conn.OwningProcess -ErrorAction SilentlyContinue }
+
+$action = 'fresh start'
+if ($proc) {
+  # 身份校验：只有能返回带 cards 字段 JSON 的才是看板，否则绝不 kill（可能误杀用户自己的服务）
+  $isBoard = $false
+  try {
+    $body = (Invoke-WebRequest -Uri "$url/api/board" -TimeoutSec 2).Content
+    $isBoard = $null -ne ($body | ConvertFrom-Json).PSObject.Properties['cards']
+  } catch { $isBoard = $false }
+  if (-not $isBoard) {
+    Write-Output "board: 端口 $Port 被非看板进程占用（pid $($proc.Id) $($proc.ProcessName)），未做任何改动；请确认该进程后自行处理"
+    exit 1
+  }
+  $newest = ($codeFiles | ForEach-Object { (Get-Item $_).LastWriteTime } | Sort-Object -Descending)[0]
+  $stale = $newest -gt $proc.StartTime.AddSeconds(2)
+  if (-not $stale) {
+    Write-Output "board: already up-to-date at $url (pid $($proc.Id))"
+    exit 0
+  }
+  Stop-Process -Id $proc.Id -Force
+  Start-Sleep -Milliseconds 500
+  $action = 'restarted (stale code detected)'
+}
+
+Start-Process -FilePath 'node' -ArgumentList "`"$server`" --port $Port" -WindowStyle Hidden
+$deadline = (Get-Date).AddSeconds(8)
+do { Start-Sleep -Milliseconds 300; $up = [bool](Get-NetTCPConnection -LocalPort $Port -State Listen -ErrorAction SilentlyContinue) } while (-not $up -and (Get-Date) -lt $deadline)
+if (-not $up) { Write-Output "board: FAILED to start on $Port"; exit 1 }
+Write-Output "board: $action -> $url"
+if (-not $NoOpen -and $action -eq 'fresh start') { Start-Process $url }

package/templates/_agents/scripts/gen-wiki-board.mjs

@@ -0,0 +1,197 @@
+// wiki 索引生成器：磁盘 + INDEX 速览表「用途」列 → 自动重生成 INDEX 速览计数/映射表 + 看板 DATA
+// 2026-09-13 引入：消除三层手工双写（短板①）。人工只维护两样：磁盘文件本身 + 速览表用途列。
+// 用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--help]
+//   （收录/删除/移动 wiki 文件后必跑，随后跑 verify-wiki-consistency.mjs）
+// 测试：node .agents/scripts/gen-wiki-board.test.mjs（fixture 回归，须全绿）
+// 生成范围（锚点内整段重写，锚点外字节原样保留）：
+//   INDEX.md 速览表数据行 / 「合计」行数字 / 「## 文件 → 主题 → 归属目录 映射表」到「## 命名规则」之间
+//   看板 知识沉淀总览.html 的 `const DATA = {...};` 整块
+// 注意：映射表节内的手工注记会被清除——背景说明请写进速览表「用途」列（人工列，生成器不覆盖）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+const USAGE = `用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--help]
+
+事实源：磁盘 wiki/<主题>/ 一层文件 + INDEX.md 速览表「用途」列（人工列）。重生成：
+  - wiki/INDEX.md：速览表数据行与文件计数、「合计」行数字、映射表节
+    （「## 文件 → 主题 → 归属目录 映射表」到「## 命名规则」之间整段）
+  - wiki/知识沉淀总览.html：const DATA = {...} 整块（summary 统计 + topics 文件清单 + dir 链接）
+两处生成区手改会被覆盖；锚点外内容原样保留。人工只维护磁盘文件 + 速览表「用途」列。
+
+选项：
+  --dry-run   只打印将生成内容的摘要与逐行差异，不写盘
+  --help      打印本说明`;
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(USAGE);
+  process.exit(0);
+}
+const unknown = args.filter((a) => a !== '--dry-run');
+if (unknown.length) {
+  console.error(`❌ 未知参数：${unknown.join(' ')}\n\n${USAGE}`);
+  process.exit(1);
+}
+const DRY = args.includes('--dry-run');
+
+const WIKI = 'wiki';
+const INDEX_P = path.join(WIKI, 'INDEX.md');
+const BOARD_P = path.join(WIKI, '知识沉淀总览.html');
+
+// ---- 磁盘枚举（事实源：文件在哪个主题目录就属于哪个主题）----
+// 登记口径（2026-09-17 起，与 verify-wiki-consistency.mjs 保持一致）：
+//   主题目录顶层：全量文件登记（现状不变）；
+//   直属子目录：仅登记 md/html 知识文档（排除 *.visual-check.* 工具产物；.json/.png 不计入）；
+//   数据维护主题例外——其子目录（schema变更/<批次>/ 等）走 README.md 台账，不参与登记。
+const isKnowledgeDoc = (f) => /\.(md|html)$/i.test(f) && !/\.visual-check\./i.test(f);
+const diskTopics = new Map(); // name -> [{ name: '文件名或 子目录/文件名', dir: 'wiki/主题[/子目录]/' }]
+for (const d of fs.readdirSync(WIKI)) {
+  const p = path.join(WIKI, d);
+  if (!fs.statSync(p).isDirectory() || d === 'drafts-archive') continue;
+  const entries = fs.readdirSync(p)
+    .filter((f) => fs.statSync(path.join(p, f)).isFile())
+    .map((f) => ({ name: f, dir: `wiki/${d}/` }));
+  if (d !== '数据维护') {
+    for (const sub of fs.readdirSync(p)) {
+      const sp = path.join(p, sub);
+      if (!fs.statSync(sp).isDirectory()) continue;
+      for (const f of fs.readdirSync(sp)) {
+        if (fs.statSync(path.join(sp, f)).isFile() && isKnowledgeDoc(f)) {
+          entries.push({ name: `${sub}/${f}`, dir: `wiki/${d}/${sub}/` });
+        }
+      }
+    }
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name, 'zh'));
+  diskTopics.set(d, entries);
+}
+// gitignore 豁免（F4，incident 2026-09-23-code-review-f3-f4-closeout）：与 verify-wiki-consistency.mjs 同口径——
+// 排除 .gitignore 忽略的本机文件（如 *.xlsx），防止生成物计数在 fresh clone 漂移；git 不可用时退化为全量计数
+const gitIgnoredArchive = (() => {
+  try {
+    const out = execSync('git -c core.quotepath=false status --ignored=matching --porcelain -uall -- wiki/drafts-archive',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const prefix = 'wiki/drafts-archive/';
+    return new Set(out.split(/\r?\n/)
+      .filter((l) => l.startsWith('!! '))
+      .map((l) => l.slice(3).trim().replace(/\/$/, ''))
+      .filter((p) => p.startsWith(prefix))
+      .map((p) => p.slice(prefix.length)));
+  } catch {
+    return new Set();
+  }
+})();
+const archiveCount = (() => {
+  let n = 0;
+  const walk = (dir, rel = '') => {
+    for (const e of fs.readdirSync(dir)) {
+      const p = path.join(dir, e);
+      const r = rel ? `${rel}/${e}` : e;
+      if (fs.statSync(p).isDirectory()) walk(p, r);
+      else if (!gitIgnoredArchive.has(r)) n++;
+    }
+  };
+  walk(path.join(WIKI, 'drafts-archive'));
+  return n;
+})();
+
+// ---- 读 INDEX 现速览表：主题顺序 + 用途列（人工，不覆盖）----
+// 切行须容忍 CRLF：按 '\n' 切会在行尾留 '\r'，速览表行锚定正则（\|$）整表失配 →
+// 「用途」列（唯一人工维护位）被静默重置为 <待补>（papercut 2026-09-17；fixture 见 gen-wiki-board.test.mjs 场景 1）
+const indexText = fs.readFileSync(INDEX_P, 'utf8');
+const overview = []; // {name, usage}
+for (const line of indexText.split(/\r?\n/)) {
+  const m = line.match(/^\| ([^|]+) \| (\d+) \|([^|]*)\|$/);
+  if (m && m[1].trim() !== '主题') overview.push({ name: m[1].trim(), usage: m[3].trim() });
+}
+// 主题顺序 = 速览表现顺序在前，磁盘新主题按中文排序追加
+const ordered = [...overview.filter((o) => diskTopics.has(o.name))];
+for (const t of [...diskTopics.keys()].sort((a, b) => a.localeCompare(b, 'zh'))) {
+  if (!ordered.some((o) => o.name === t)) ordered.push({ name: t, usage: '<待补：新主题用途描述>' });
+}
+
+const totalFiles = [...diskTopics.values()].reduce((n, f) => n + f.length, 0);
+
+// ---- 生成 INDEX 三段 ----
+const eol = indexText.includes('\r\n') ? '\r\n' : '\n';
+const overviewRows = ordered.map((o) => `| ${o.name} | ${diskTopics.get(o.name).length} | ${o.usage} |`);
+const mappingSection = ordered.map((o) => {
+  const rows = diskTopics.get(o.name).map((e) => `| ${e.name} | ${o.name} | ${e.dir} |`);
+  return [`### ${o.name}（${diskTopics.get(o.name).length}）`, '', '| 文件名 | 主题 | 归属目录 |', '|---|---|---|', ...rows].join(eol);
+}).join(eol + eol);
+
+let out = indexText;
+// 速览表数据行（表头「| 主题 |」+ 分隔行之后的连续数据行整组替换）
+{
+  const lines = out.split(/\r?\n/);
+  const headIdx = lines.findIndex((l) => /^\| 主题 \|/.test(l));
+  if (headIdx < 0 || !/^[\|:\-\s]+$/.test(lines[headIdx + 1] || '')) {
+    console.error('❌ INDEX 速览表表头未找到，未写盘');
+    process.exit(1);
+  }
+  let lastData = headIdx + 1;
+  while (lastData + 1 < lines.length && lines[lastData + 1].startsWith('|')) lastData++;
+  const fixedRows = [...overviewRows, '| drafts-archive | — | 原文档备份（按 日期-主题 分目录） |'];
+  out = [...lines.slice(0, headIdx), '| 主题 | 文件数 | 用途 |', '|---|---|---|', ...fixedRows, ...lines.slice(lastData + 1)].join(eol);
+}
+// 合计行数字
+out = out.replace(/合计：\*\*\d+ 份\*\*知识文档，\*\*\d+ 个主题\*\*/, `合计：**${totalFiles} 份**知识文档，**${diskTopics.size} 个主题**`);
+// 映射表区（节标题之间整段重写）
+{
+  const lines = out.split(/\r?\n/);
+  const s = lines.findIndex((l) => l.startsWith('## 文件 → 主题 → 归属目录 映射表'));
+  const e = lines.findIndex((l) => l.startsWith('## 命名规则'));
+  if (s >= 0 && e > s) {
+    out = [...lines.slice(0, s + 1), '', mappingSection, '', '---', '', ...lines.slice(e)].join(eol);
+  }
+}
+
+// ---- 生成看板 DATA ----
+const boardText = fs.readFileSync(BOARD_P, 'utf8');
+const topicsJs = ordered.map((o) => {
+  // dir 相对看板自身（wiki/）——旧值带 wiki/ 前缀会被解析为 wiki/wiki/... 死链
+  const files = diskTopics.get(o.name).map((e) => `      { "file": ${JSON.stringify(e.name)}, "topic": ${JSON.stringify(o.name)}, "dir": ${JSON.stringify(`./${e.dir.slice('wiki/'.length)}`)} }`);
+  return `    { "name": ${JSON.stringify(o.name)}, "files": [\n${files.join(',\n')}\n    ]}`;
+}).join(',\n');
+const dataJs = `const DATA = {\n  "summary": { "total": ${totalFiles}, "topics": ${diskTopics.size}, "files": ${totalFiles}, "archive": ${archiveCount} },\n  "topics": [\n${topicsJs}\n  ]\n};`;
+const boardOut = boardText.replace(/const DATA = \{[\s\S]*?\n\};/, dataJs);
+if (boardOut === boardText && !/const DATA = \{[\s\S]*?\n\};/.test(boardText)) {
+  console.error('❌ 看板中未找到 const DATA = {...} 块，未写盘');
+  process.exit(1);
+}
+
+// ---- 写盘（dry-run 只预览差异）----
+if (DRY) {
+  console.log('🔎 --dry-run：未写盘，差异预览如下');
+  previewDiff('wiki/INDEX.md', indexText, out);
+  previewDiff('wiki/知识沉淀总览.html', boardText, boardOut);
+} else {
+  fs.writeFileSync(INDEX_P, out, 'utf8');
+  fs.writeFileSync(BOARD_P, boardOut, 'utf8');
+}
+
+const tail = DRY ? '将重写' : '已重写';
+console.log(`${DRY ? '🔎 [dry-run] 将生成' : '✅ 已生成'}：文件 ${totalFiles} 份 / 主题 ${diskTopics.size} 个 / 归档 ${archiveCount} 份；速览表 ${overviewRows.length} 行、映射表 ${ordered.length} 节、看板 DATA ${tail}`);
+console.log('   人工仅维护：磁盘文件 + 速览表「用途」列（新主题为 <待补> 的请补描述后重跑本脚本）');
+
+// dry-run 差异预览：首尾对齐后取中段变更块（逐行），各方向最多显示 10 行
+function previewDiff(label, before, after) {
+  if (before === after) {
+    console.log(`• ${label}：无变化`);
+    return;
+  }
+  const b = before.split(/\r?\n/);
+  const a = after.split(/\r?\n/);
+  let head = 0;
+  while (head < b.length && head < a.length && b[head] === a[head]) head++;
+  let tailN = 0;
+  while (tailN < b.length - head && tailN < a.length - head && b[b.length - 1 - tailN] === a[a.length - 1 - tailN]) tailN++;
+  const removed = b.slice(head, b.length - tailN);
+  const added = a.slice(head, a.length - tailN);
+  console.log(`• ${label}：第 ${head + 1} 行起变更，删 ${removed.length} 行 / 增 ${added.length} 行`);
+  for (const l of removed.slice(0, 10)) console.log(`    - ${l.slice(0, 120)}`);
+  if (removed.length > 10) console.log(`    - …（其余 ${removed.length - 10} 行略）`);
+  for (const l of added.slice(0, 10)) console.log(`    + ${l.slice(0, 120)}`);
+  if (added.length > 10) console.log(`    + …（其余 ${added.length - 10} 行略）`);
+}

package/templates/_agents/scripts/gen-wiki-board.test.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// gen-wiki-board.mjs 的 fixture 驱动测试（2026-09-21 随 CRLF 解析缺陷修复引入）
+// 现场构造临时 wiki 根，以「换 cwd」方式运行被测脚本（脚本按相对路径 'wiki/' 读盘，无需注入口）。
+// 断言：①CRLF 下速览表「用途」列（唯一人工维护位）重生成后保持——papercut 2026-09-17 缺陷回归；
+//       ②行尾保持（CRLF 不被改写成 LF）；③新增 wiki 文件后速览计数 / 合计行 / 看板 DATA 同步。
+// 用法：node .agents/scripts/gen-wiki-board.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-wiki-board.mjs');
+const USAGE = '用法：node .agents/scripts/gen-wiki-board.test.mjs';
+
+const USAGE_COL = '主题A 用途说明（人工列）';
+
+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}` : ''}`); }
+};
+
+// 行尾统计：验证 CRLF fixture 不被改写成 LF
+const eolStats = (p) => {
+  const b = fs.readFileSync(p);
+  let crlf = 0;
+  let lf = 0;
+  for (let i = 0; i < b.length; i++) {
+    if (b[i] === 10) { if (i > 0 && b[i - 1] === 13) crlf++; else lf++; }
+  }
+  return { crlf, lf };
+};
+
+// mkfix：建临时 wiki 根（INDEX 按 eol 拼装；看板 DATA 块固定 LF——与仓库现状一致）
+const mkfix = (eol) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gen-wiki-board-test-'));
+  fs.mkdirSync(path.join(root, 'wiki', '主题A'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'wiki', 'drafts-archive'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'wiki', '主题A', 'a.md'), '# a\n', 'utf8');
+  fs.writeFileSync(path.join(root, 'wiki', 'INDEX.md'), [
+    '# wiki 索引（fixture）',
+    '',
+    '| 主题 | 文件数 | 用途 |',
+    '|---|---|---|',
+    `| 主题A | 1 | ${USAGE_COL} |`,
+    '| drafts-archive | — | 原文档备份（按 日期-主题 分目录） |',
+    '',
+    '合计：**1 份**知识文档，**1 个主题**',
+    '',
+    '---',
+    '',
+    '## 文件 → 主题 → 归属目录 映射表',
+    '',
+    '### 主题A（1）',
+    '',
+    '| 文件名 | 主题 | 归属目录 |',
+    '|---|---|---|',
+    '| a.md | 主题A | wiki/主题A/ |',
+    '',
+    '---',
+    '',
+    '## 命名规则',
+    '',
+    '- fixture',
+    '',
+  ].join(eol), 'utf8');
+  fs.writeFileSync(path.join(root, 'wiki', '知识沉淀总览.html'), [
+    '<!doctype html><html><body>',
+    '<script>',
+    'const DATA = {',
+    '  "summary": { "total": 1, "topics": 1, "files": 1, "archive": 0 },',
+    '  "topics": [',
+    '    { "name": "主题A", "files": [',
+    '      { "file": "a.md", "topic": "主题A", "dir": "./主题A/" }',
+    '    ]}',
+    '  ]',
+    '};',
+    '</script>',
+    '</body></html>',
+    '',
+  ].join('\n'), 'utf8');
+  return root;
+};
+
+const runGen = (root) => spawnSync(process.execPath, [GEN], { cwd: root, encoding: 'utf8' });
+
+// ---- 场景 1：CRLF INDEX ——「用途」列重生成后保持 + 行尾保持（缺陷回归）----
+{
+  const root = mkfix('\r\n');
+  const r = runGen(root);
+  const out = fs.readFileSync(path.join(root, 'wiki', 'INDEX.md'), 'utf8');
+  const { crlf, lf } = eolStats(path.join(root, 'wiki', 'INDEX.md'));
+  check('场景 1：CRLF INDEX 生成器 exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check(`场景 1：「用途」列保持（CRLF 致整表解析为空即丢——papercut 2026-09-17）`, out.includes(USAGE_COL), out.split('\n').slice(0, 10).join('\n'));
+  check('场景 1：未退化为 <待补>', !out.includes('<待补'), out.split('\n').slice(0, 10).join('\n'));
+  check('场景 1：行尾保持 CRLF（未被改写为 LF）', crlf > 0 && lf === 0, `crlf=${crlf} bareLF=${lf}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 2：LF INDEX 对照 —— 用途保持（证明解析不依赖行尾）----
+{
+  const root = mkfix('\n');
+  const r = runGen(root);
+  const out = fs.readFileSync(path.join(root, 'wiki', 'INDEX.md'), 'utf8');
+  const { crlf, lf } = eolStats(path.join(root, 'wiki', 'INDEX.md'));
+  check('场景 2：LF INDEX 生成器 exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 2：「用途」列保持', out.includes(USAGE_COL), out.split('\n').slice(0, 10).join('\n'));
+  check('场景 2：行尾保持 LF', lf > 0 && crlf === 0, `crlf=${crlf} bareLF=${lf}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 3：新增 wiki 文件 —— 速览计数 / 合计行 / 看板 DATA 同步 ----
+{
+  const root = mkfix('\r\n');
+  fs.writeFileSync(path.join(root, 'wiki', '主题A', 'b.md'), '# b\n', 'utf8');
+  const r = runGen(root);
+  const index = fs.readFileSync(path.join(root, 'wiki', 'INDEX.md'), 'utf8');
+  const board = fs.readFileSync(path.join(root, 'wiki', '知识沉淀总览.html'), 'utf8');
+  check('场景 3：新增文件后生成器 exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 3：速览表计数同步为 2', /\| 主题A \| 2 \|/.test(index), index.split('\n').slice(0, 8).join('\n'));
+  check('场景 3：合计行同步为 2 份', index.includes('合计：**2 份**知识文档，**1 个主题**'), index.split('\n').slice(0, 12).join('\n'));
+  check('场景 3：看板 DATA 同步 total=2', /"summary": \{ "total": 2/.test(board), '');
+  check('场景 3：「用途」列保持', index.includes(USAGE_COL), '');
+  check('场景 3：映射表节收录新文件', index.includes('| b.md | 主题A | wiki/主题A/ |'), '');
+  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-index.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// workflow 活跃层索引生成器（2026-09-21，intent 2026-09-21-workflow-doc-retrieval）
+// 用法：node .agents/scripts/gen-workflow-index.mjs [--dry-run] [--check] [--help]
+//   --dry-run  只打印差异预览，不写盘
+//   --check    不写盘；与磁盘不一致时 exit 1 并打印差异（供 check-loop 漂移告警）
+// 测试：node .agents/scripts/gen-workflow-index.test.mjs（fixture 回归，须全绿）
+// 口径：扫磁盘（对照 gen-wiki-board.mjs 与看板）；排除 _TEMPLATE.md。活跃 = draft / approved / open
+//   逐行列出（在跑的工作）；其余状态折叠进「档案计数」——fixed 未 closed 的 incident 与 approved
+//   孤儿 plan 属「待收口」，看板会告警；查档案用 kb-search（默认含全部状态）。
+// 生成区：INDEX.md 的 GENERATED:BEGIN/END 锚点注释之间整段重写，锚点外内容原样保留。
+import fs from 'node:fs';
+import path from 'node:path';
+
+const USAGE = `用法：node .agents/scripts/gen-workflow-index.mjs [--dry-run] [--check] [--help]
+
+事实源：workflow/{intents,specs,plans,incidents}/*.md 的 frontmatter（状态/级别/日期/发现/模块）
+        + H1 标题 + 「## 验收标准」勾验统计；排除 _TEMPLATE.md。
+生成物：workflow/INDEX.md —— 活跃层逐行（类型|级别|状态|日期|模块|标题|验收）+ 档案计数（类型×模块）。
+选项：
+  --dry-run   只打印将生成内容的摘要与差异，不写盘
+  --check     不写盘；INDEX 与磁盘不一致时 exit 1（供 check-loop 漂移告警）
+  --help      打印本说明`;
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) { console.log(USAGE); process.exit(0); }
+const unknown = args.filter((a) => !['--dry-run', '--check'].includes(a));
+if (unknown.length) { console.error(`❌ 未知参数：${unknown.join(' ')}\n\n${USAGE}`); process.exit(1); }
+const DRY = args.includes('--dry-run');
+const CHECK = args.includes('--check');
+
+const WORKFLOW = 'workflow';
+const INDEX_P = path.join(WORKFLOW, 'INDEX.md');
+const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
+const TYPE_LABEL = { intents: 'INTENT', specs: 'SPEC', plans: 'PLAN', incidents: 'INCIDENT' };
+const ACTIVE_STATUS = ['draft', 'approved', 'open']; // 其余（done/fixed/closed/superseded/cancelled）折叠进档案计数
+
+const BEGIN = '<!-- GENERATED:BEGIN — gen-workflow-index.mjs 整段重写，手工说明写在本行之前 -->';
+const END = '<!-- GENERATED:END -->';
+const HEADER = `# workflow 索引 — 活跃层与档案（生成物，勿手改）
+
+> 生成器 \`node .agents/scripts/gen-workflow-index.mjs\`（状态变更 / 新建文档后重跑；\`--check\` 校验漂移，check-loop 会告警）。
+> 活跃 = draft / approved / open（在跑）；其余状态折叠进档案计数，检索用 \`node .agents/scripts/kb-search.mjs "<词>"\`（默认含全部状态、活跃优先排序）。
+> 模块词表见 \`.agents/workflow-modules.txt\`。
+`;
+
+// ---- frontmatter（受限子集：每行 `键: 值`）+ H1 标题（去「INTENT — 」前缀），对照 workflow/README.md 文档协议 ----
+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 };
+}
+
+// ---- 验收勾验统计：仅「## 验收标准」节内（至下一个 ## 标题），无该节返回 null（对照看板口径）----
+function parseAcceptance(text) {
+  const h = text.match(/^## 验收标准.*$/m);
+  if (!h) return null;
+  const rest = text.slice(h.index + h[0].length);
+  const next = rest.match(/^## /m);
+  const section = next ? rest.slice(0, next.index) : rest;
+  const total = (section.match(/^\s*[-*] \[[ xX]\]/gm) || []).length;
+  if (!total) return null;
+  const done = (section.match(/^\s*[-*] \[[xX]\]/gm) || []).length;
+  return { done, total };
+}
+
+const esc = (s) => String(s).replace(/\|/g, '\\|'); // 表格单元格内管道转义
+
+function scan() {
+  const docs = [];
+  for (const type of DOC_TYPES) {
+    const dir = path.join(WORKFLOW, type);
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+      const name = f.slice(0, -3);
+      const text = fs.readFileSync(path.join(dir, f), 'utf8');
+      const { meta, title } = parseDoc(text);
+      docs.push({
+        type,
+        file: `${type}/${f}`,
+        status: meta['状态'] || '（未填）',
+        level: meta['级别'] || '—',
+        date: meta['日期'] || meta['发现'] || name.slice(0, 10),
+        module: meta['模块'] || '—',
+        title: title || name,
+        accept: parseAcceptance(text),
+      });
+    }
+  }
+  return docs;
+}
+
+function render(docs) {
+  const active = docs.filter((d) => ACTIVE_STATUS.includes(d.status));
+  active.sort((a, b) => b.date.localeCompare(a.date) || a.type.localeCompare(b.type) || a.file.localeCompare(b.file));
+  const arch = docs.filter((d) => !ACTIVE_STATUS.includes(d.status));
+
+  const rows = active.map((d) =>
+    `| ${TYPE_LABEL[d.type]} | ${esc(d.level)} | ${esc(d.status)} | ${esc(d.date)} | ${esc(d.module)} | ${esc(d.title)} | ${d.accept ? `☑${d.accept.done}/${d.accept.total}` : '—'} |`);
+
+  const counts = new Map(); // `${type}|${module}` → 数量
+  for (const d of arch) {
+    const k = `${d.type}|${d.module}`;
+    counts.set(k, (counts.get(k) || 0) + 1);
+  }
+  const archRows = [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([k, n]) => {
+    const [type, module] = k.split('|');
+    return `| ${TYPE_LABEL[type]} | ${esc(module)} | ${n} |`;
+  });
+  const byStatus = new Map();
+  for (const d of arch) byStatus.set(d.status, (byStatus.get(d.status) || 0) + 1);
+  const statusLine = [...byStatus.entries()].sort((a, b) => b[1] - a[1]).map(([s, n]) => `${s} ${n}`).join(' · ');
+
+  return [
+    `## 活跃（${active.length}）`,
+    '',
+    '| 类型 | 级别 | 状态 | 日期 | 模块 | 标题 | 验收 |',
+    '|---|---|---|---|---|---|---|',
+    ...rows,
+    '',
+    `## 档案计数（${arch.length}，不进表）`,
+    '',
+    '| 类型 | 模块 | 数量 |',
+    '|---|---|---|',
+    ...archRows,
+    '',
+    `终态构成：${statusLine}；查档案用 \`node .agents/scripts/kb-search.mjs "<词>" --status all\`。`,
+  ].join('\n');
+}
+
+// ---- 组装：锚点内整段重写，锚点外（含首次创建时的 HEADER）原样保留 ----
+const docs = scan();
+const existing = fs.existsSync(INDEX_P) ? fs.readFileSync(INDEX_P, 'utf8') : '';
+const inner = `${BEGIN}\n\n${render(docs)}\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';
+}
+
+const nActive = docs.filter((d) => ACTIVE_STATUS.includes(d.status)).length;
+const nArch = docs.length - nActive;
+const summary = `活跃 ${nActive} 行 / 档案 ${nArch} 篇 / ${Buffer.byteLength(out, 'utf8')} B`;
+
+// 差异预览：首尾对齐后取中段变更块（逐行），各方向最多 10 行
+function previewDiff(before, after) {
+  if (before === after) return;
+  const b = before.split(/\r?\n/);
+  const a = after.split(/\r?\n/);
+  let head = 0;
+  while (head < b.length && head < a.length && b[head] === a[head]) head++;
+  let tailN = 0;
+  while (tailN < b.length - head && tailN < a.length - head && b[b.length - 1 - tailN] === a[a.length - 1 - tailN]) tailN++;
+  const removed = b.slice(head, b.length - tailN);
+  const added = a.slice(head, a.length - tailN);
+  console.log(`  第 ${head + 1} 行起变更：删 ${removed.length} 行 / 增 ${added.length} 行`);
+  for (const l of removed.slice(0, 10)) console.log(`    - ${l.slice(0, 140)}`);
+  if (removed.length > 10) console.log(`    - …（其余 ${removed.length - 10} 行略）`);
+  for (const l of added.slice(0, 10)) console.log(`    + ${l.slice(0, 140)}`);
+  if (added.length > 10) console.log(`    + …（其余 ${added.length - 10} 行略）`);
+}
+
+if (CHECK) {
+  if (out === existing) {
+    console.log(`✅ workflow/INDEX.md 与磁盘一致（${summary}）`);
+    process.exit(0);
+  }
+  console.error(`❌ workflow/INDEX.md 与磁盘不一致（${summary}）——跑 node .agents/scripts/gen-workflow-index.mjs 重新生成`);
+  previewDiff(existing, out);
+  process.exit(1);
+}
+
+if (DRY) {
+  console.log(`🔎 --dry-run：未写盘（${summary}）`);
+  if (out === existing) console.log('• workflow/INDEX.md：无变化');
+  else previewDiff(existing, out);
+} else {
+  fs.writeFileSync(INDEX_P, out, 'utf8');
+  console.log(`✅ 已生成 workflow/INDEX.md：${summary}`);
+}