agentic-flow-kit 0.2.0

package/templates/_agents/scripts/verify-wiki-consistency.mjs

@@ -0,0 +1,192 @@
+// wiki 三方一致性验证：磁盘 ↔ INDEX.md ↔ 知识沉淀总览.html(DATA) ＋ 数据维护台账登记 ＋ 看板链接可达性
+// 用法: node .agents/scripts/verify-wiki-consistency.mjs   （不一致 exit 1）
+// 约定见 .agents/skills/wiki/SKILL.md；归档 drafts-archive 仅计数，不参与文件比对。
+// 口径（2026-09-17 起，与 gen-wiki-board.mjs 保持一致）：主题目录顶层全量文件登记 +
+//      直属子目录中的 md/html 知识文档（排除 *.visual-check.* 工具产物；数据维护主题例外——
+//      其子目录 schema变更/<批次>/ 等走 README 台账，不参与三方文件比对与 summary 统计）；
+//      递归扫描仅用于「断链守卫 + 数据维护批次台账登记」两项断言，避免改变既有统计口径误报。
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+const WIKI = 'wiki';
+const problems = [];
+const notes = [];
+
+// 递归列目录（相对 dir 的路径，仅正斜杠）；drafts-archive 由调用方排除
+const walkTree = (dir, rel = '') => {
+  const acc = { files: [], dirs: [] };
+  for (const e of fs.readdirSync(dir)) {
+    const p = path.join(dir, e);
+    const r = rel ? `${rel}/${e}` : e;
+    if (fs.statSync(p).isDirectory()) {
+      acc.dirs.push(r);
+      const sub = walkTree(p, r);
+      acc.files.push(...sub.files);
+      acc.dirs.push(...sub.dirs);
+    } else acc.files.push(r);
+  }
+  return acc;
+};
+
+// ---- 磁盘枚举（登记口径与 gen-wiki-board.mjs 一致）----
+const isKnowledgeDoc = (f) => /\.(md|html)$/i.test(f) && !/\.visual-check\./i.test(f);
+const diskFiles = new Set(); // "主题/文件名"（子目录文件名带 子目录/ 前缀）
+const diskTopics = new Set();
+const activeTree = { files: [], dirs: [] }; // 递归视图（断链守卫 / 台账登记断言用）
+for (const d of fs.readdirSync(WIKI)) {
+  const p = path.join(WIKI, d);
+  if (!fs.statSync(p).isDirectory()) continue;
+  if (d === 'drafts-archive') continue;
+  diskTopics.add(d);
+  for (const f of fs.readdirSync(p)) {
+    if (fs.statSync(path.join(p, f)).isFile()) diskFiles.add(`${d}/${f}`);
+  }
+  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)) diskFiles.add(`${d}/${sub}/${f}`);
+      }
+    }
+  }
+  const sub = walkTree(p, d);
+  activeTree.files.push(...sub.files);
+  activeTree.dirs.push(...sub.dirs);
+}
+
+// gitignore 豁免（F4，incident 2026-09-23-code-review-f3-f4-closeout）：drafts-archive 含
+// .gitignore 忽略的本机文件（如 *.xlsx），计入会使生成物计数在 fresh clone 必然漂移；
+// 口径 = 排除忽略文件（git 不可用/非仓库时退化为全量计数，fixture 环境不受影响）
+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 = walkTree(path.join(WIKI, 'drafts-archive')).files.filter((r) => !gitIgnoredArchive.has(r)).length;
+
+// ---- 看板 DATA 解析 ----
+const html = fs.readFileSync(path.join(WIKI, '知识沉淀总览.html'), 'utf8');
+const m = html.match(/const DATA = (\{[\s\S]*?\n\});/);
+if (!m) {
+  console.error('❌ 看板 DATA 解析失败：知识沉淀总览.html 中找不到 `const DATA = {...}`');
+  process.exit(1);
+}
+const DATA = eval('(' + m[1] + ')');
+const boardFiles = new Set();
+for (const t of DATA.topics) for (const f of t.files) boardFiles.add(`${t.name}/${f.file}`);
+const boardTopics = new Set(DATA.topics.map((t) => t.name));
+
+// ---- INDEX 映射表解析 ----
+const indexFiles = new Set();
+const indexTopicCounts = new Map(); // 速览表 topic → 文件数
+for (const line of fs.readFileSync(path.join(WIKI, 'INDEX.md'), 'utf8').split(/\r?\n/)) {
+  const mm = line.match(/^\| ([^|]+) \| ([^|]+) \| wiki\/([^/]+)\/[^|]*\|$/);
+  if (mm) indexFiles.add(`${mm[3].trim()}/${mm[1].trim()}`);
+  const ov = line.match(/^\| ([^|]+) \| (\d+) \|[^|]*\|$/);
+  if (ov && ov[1].trim() !== '主题') indexTopicCounts.set(ov[1].trim(), Number(ov[2]));
+}
+
+const diff = (a, b) => [...a].filter((x) => !b.has(x));
+const eq = (a, b) => a.size === b.size && diff(a, b).length === 0;
+
+// ---- 1. 文件级三方比对 ----
+for (const [label, extra] of [
+  ['看板→磁盘', diff(boardFiles, diskFiles)],
+  ['磁盘→看板', diff(diskFiles, boardFiles)],
+  ['INDEX→磁盘', diff(indexFiles, diskFiles)],
+  ['磁盘→INDEX', diff(diskFiles, indexFiles)],
+]) {
+  if (extra.length) problems.push(`文件集合不一致（${label}）: ${extra.join('；')}`);
+}
+if (problems.length === 0) notes.push(`文件级三方一致：${diskFiles.size} 份`);
+
+// ---- 2. 幽灵目录：磁盘有主题目录但看板没有 ----
+const ghosts = diff(diskTopics, boardTopics);
+if (ghosts.length) problems.push(`磁盘存在看板未登记的主题目录: ${ghosts.join('、')}`);
+
+// ---- 3. 占位主题（看板有、磁盘 0 文件）——允许，仅提示 ----
+for (const t of DATA.topics) {
+  if (t.files.length === 0 && fs.existsSync(path.join(WIKI, t.name))) {
+    const real = fs.readdirSync(path.join(WIKI, t.name)).filter((f) => fs.statSync(path.join(WIKI, t.name, f)).isFile()).length;
+    if (real > 0) problems.push(`看板主题「${t.name}」files 为空但磁盘有 ${real} 个文件`);
+    else notes.push(`占位主题「${t.name}」：0 文件（允许）`);
+  } else if (t.files.length === 0) {
+    problems.push(`看板主题「${t.name}」files 为空且磁盘无此目录`);
+  }
+}
+
+// ---- 4. INDEX 速览表文件数 vs 磁盘 ----
+for (const [topic, count] of indexTopicCounts) {
+  const actual = [...diskFiles].filter((f) => f.startsWith(topic + '/')).length;
+  if (!diskTopics.has(topic) && count > 0) problems.push(`INDEX 速览表主题「${topic}」(${count}) 磁盘无此目录`);
+  else if (actual !== count) problems.push(`INDEX 速览表「${topic}」标 ${count}，磁盘实际 ${actual}`);
+}
+
+// ---- 5. summary 统计字段 ----
+const s = DATA.summary;
+const sumChecks = [
+  ['summary.total', s.total, diskFiles.size],
+  ['summary.files', s.files, diskFiles.size],
+  ['summary.topics', s.topics, DATA.topics.length],
+  ['summary.archive', s.archive, archiveCount],
+];
+for (const [label, declared, actual] of sumChecks) {
+  if (declared !== actual) problems.push(`${label}=${declared}，实际 ${actual}`);
+}
+
+// ---- 6. 活跃文件禁 file:/// 绝对链（搬家断链防复发；递归覆盖子目录）----
+const badLinks = [];
+for (const f of activeTree.files) {
+  if (!/\.(md|html)$/i.test(f)) continue;
+  if (fs.readFileSync(path.join(WIKI, f), 'utf8').includes('file:///')) badLinks.push(f);
+}
+if (badLinks.length) problems.push(`以下活跃文件含 file:/// 绝对路径链接: ${badLinks.join('、')}`);
+
+// ---- 7. 数据维护台账登记：子目录（含批次目录）须在 wiki/数据维护/README.md 有登记行 ----
+// 「数据维护走 README 台账」是可选主题约定——目录不存在（新项目未建该主题）时整体跳过
+const maintLedger = path.join(WIKI, '数据维护', 'README.md');
+if (fs.existsSync(maintLedger)) {
+const maintReadme = fs.readFileSync(maintLedger, 'utf8');
+const maintReadmeFlat = maintReadme.replace(/\s+/g, ''); // README 标题写作「schema 变更」（带空格），故去空白再比对
+const maintDirs = activeTree.dirs.filter((d) => d.startsWith('数据维护/'));
+const unregistered = maintDirs
+  .map((d) => d.split('/').pop())
+  .filter((name) => !maintReadme.includes(name) && !maintReadmeFlat.includes(name.replace(/\s+/g, '')));
+if (unregistered.length) problems.push(`数据维护台账未登记（wiki/数据维护/README.md 无此行）：${unregistered.join('、')}`);
+else notes.push(`数据维护台账登记完整：${maintDirs.length} 个子目录（含批次目录）均有登记`);
+}
+
+// ---- 8. 看板链接可达性：DATA.dir（「打开目录」href）+ 静态相对 href 解析后须存在 ----
+const deadLinks = [];
+for (const t of DATA.topics) {
+  for (const f of t.files) {
+    const p = path.join(WIKI, f.dir); // 看板自身位于 wiki/，dir 为相对它解析
+    if (!fs.existsSync(p) || !fs.statSync(p).isDirectory()) deadLinks.push(`${t.name}/${f.file} → ${f.dir}`);
+  }
+}
+for (const m2 of html.matchAll(/href="([^"]+)"/g)) {
+  const href = m2[1];
+  if (/^(https?:|mailto:|#)/i.test(href) || href.includes('${')) continue; // 外链 / 锚点 / 模板占位
+  if (!fs.existsSync(path.join(WIKI, href))) deadLinks.push(`静态 href → ${href}`);
+}
+if (deadLinks.length) problems.push(`看板链接指向不存在的路径（相对 wiki/ 解析）: ${deadLinks.join('；')}`);
+
+// ---- 输出 ----
+for (const n of notes) console.log('ℹ️  ' + n);
+if (problems.length) {
+  console.error('\n❌ wiki 一致性校验失败：');
+  for (const p of problems) console.error('  - ' + p);
+  process.exit(1);
+}
+console.log(`✅ wiki 三方一致：文件 ${diskFiles.size} 份 / 主题 ${DATA.topics.length} 个（含占位）/ 归档 ${archiveCount} 份`);

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

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// wiki 活跃层全文检索（2026-09-13 引入；2026-09-21 起降为 kb-search.mjs 的 wiki 域转发壳）
+// —— 检索实现与降噪口径单一维护在 .agents/scripts/kb-search.mjs，本脚本保留以兼容既有文档 / SKILL §8 的命令。
+// 用法：node .agents/scripts/wiki-search.mjs <词1> [词2 ...]     多词 AND（全部命中才算）
+//       node .agents/scripts/wiki-search.mjs -t 数据维护 <词>    限定主题
+//       node .agents/scripts/wiki-search.mjs -n 0 <词>          输出上限（本脚本默认 20，0=不限）
+// 语料固定为 wiki 活跃层（含数据维护子目录；排除 drafts-archive、INDEX.md、知识沉淀总览.html）；
+// 默认跳过 .json/.csv、*.visual-check.* 与 >180KB bulk（--include-generated 纳入）。
+// 跨语料（workflow + wiki）请直接用：node .agents/scripts/kb-search.mjs "<词>"
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+// 兼容保留 P0 版默认输出上限 20；用户显式传 -n 时不覆盖；--scope wiki 追加在末尾以固定语料（后出现者生效）
+const pass = [...args, ...(args.includes('-n') ? [] : ['-n', '20']), '--scope', 'wiki'];
+const r = spawnSync(process.execPath, [path.join(here, 'kb-search.mjs'), ...pass], { stdio: 'inherit' });
+process.exit(r.status ?? 1);

package/templates/_agents/scripts/workflow-board-server.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+// workflow 实时看板服务：本地只读 http + SSE 文件监听，可视化 AI 执行流程（intents/incidents/plans/specs）。
+// 用法：node .agents/scripts/workflow-board-server.mjs [--port 8933]
+// 零依赖（node:http/node:fs/node:path/node:url/node:child_process）；只读 workflow/ 与 git，仅绑 127.0.0.1。
+// API：GET /（看板页） /marked.min.js（vendor） /api/board /api/doc?file=<相对路径> /api/history?file=<相对路径> /api/events（SSE）
+// 实时边界：文档内容与状态随落盘实时（fs.watch→SSE 推送）；git 历史仅含已提交记录（git 语义）。
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const WORKFLOW = path.join(ROOT, 'workflow');
+const BOARD_DIR = path.join(ROOT, '.agents', 'board');
+const DOC_TYPES = ['intents', 'incidents', 'plans', 'specs'];
+
+const portArg = process.argv.indexOf('--port');
+const PORT = portArg > 0 ? Number(process.argv[portArg + 1]) || 8933 : 8933;
+
+// ---- front matter + 标题解析（对照 _TEMPLATE.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*(.+)$/); // 去掉 "# INTENT — " 前缀，留主题
+  if (dash) title = dash[1];
+  return { meta, title };
+}
+
+// ---- 验收标准 checkbox 统计：仅「## 验收标准」节内（至下一个 ## 标题），无该节返回 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 };
+}
+
+// ---- 配对断裂检测：按 slug 聚合同族（同名 intent/incident/plan/spec），异常卡附 alerts ----
+// 规则（口径对齐 check-loop.sh 的硬断档 + 状态枚举，看板为预警层、不阻断）：
+//   孤儿 spec / 孤儿 plan（无同名 intent·incident 入口）；入口 done 但 plan 未终态（看板启发式）；
+//   入口缺 plan（intent 一律要求；incident 需非 legacy 且级别 L1/L2/L3）；L2/L3 入口缺同名 spec；
+//   spec L3 确认三件缺失（确认结果 / 确认时间 / 正文独立复核行）；
+//   状态不在枚举内或缺失（intent·spec·plan: approved/done/superseded/cancelled；incident: open/fixed/closed）
+const PLAN_TERMINAL = ['done', 'superseded', 'cancelled'];
+const STATUS_ENUM = {
+  intents: ['approved', 'done', 'superseded', 'cancelled'],
+  specs: ['approved', 'done', 'superseded', 'cancelled'],
+  plans: ['approved', 'done', 'superseded', 'cancelled'],
+  incidents: ['open', 'fixed', 'closed'],
+};
+const NO_STATUS = '（未填）';
+const L3_REVIEW = /^- 独立复核：[ \t]*[^<\s]/m; // 正文独立复核行须有实质内容（对照 check-loop 锚定）
+
+function detectAlerts(cards) {
+  const bySlug = new Map();
+  for (const c of cards) {
+    if (!bySlug.has(c.slug)) bySlug.set(c.slug, []);
+    bySlug.get(c.slug).push(c);
+  }
+  for (const c of cards) {
+    const fam = bySlug.get(c.slug) || [];
+    const types = new Set(fam.map((x) => x.type));
+    const alerts = [];
+    const isEntry = c.type === 'intents' || c.type === 'incidents';
+    // legacy 复盘件免配对类告警（口径同 check-loop）；孤儿 spec / 孤儿 plan 两条仍按 spec·plan 自身判定
+    const legacyIncident = c.type === 'incidents' && c.flow === 'legacy';
+    if (!STATUS_ENUM[c.type].includes(c.status))
+      alerts.push(`状态不在枚举内：须为 ${STATUS_ENUM[c.type].join('/')}（现 ${c.status === NO_STATUS ? '缺失' : c.status}）`);
+    if (c.type === 'specs' && !types.has('intents') && !types.has('incidents'))
+      alerts.push('孤儿 spec：无同名 intent/incident 入口');
+    if (c.type === 'plans' && !types.has('intents') && !types.has('incidents'))
+      alerts.push('孤儿 plan：无同名 intent/incident 入口');
+    if (c.type === 'plans') {
+      const entry = fam.find((x) => x.type === 'intents' || x.type === 'incidents');
+      if (entry && entry.status === 'done' && !PLAN_TERMINAL.includes(c.status))
+        alerts.push(`入口已 done，本 plan 未终态（现 ${c.status}）`);
+    }
+    if (isEntry && !legacyIncident && !types.has('plans') && (c.type === 'intents' || ['L1', 'L2', 'L3'].includes(c.level)))
+      alerts.push('入口缺 plan：无同名 plan');
+    if (isEntry && !legacyIncident && ['L2', 'L3'].includes(c.level) && !types.has('specs'))
+      alerts.push(`${c.level} 入口缺同名 spec`);
+    if (c.type === 'specs' && c.level === 'L3' && !['superseded', 'cancelled'].includes(c.status)) {
+      if (c.confirm !== 'approved') alerts.push(`L3 确认缺失：确认结果须为 approved（现 ${c.confirm || '缺失'}）`);
+      if (!c.confirmTime) alerts.push('L3 确认缺失：须记录确认时间');
+      if (!c.hasReview) alerts.push('L3 复核缺失：须记录新会话独立复核结论');
+    }
+    if (alerts.length) c.alerts = alerts;
+  }
+}
+
+// ---- 文档作者：单次 git log 批量取「文件 → 最早提交者」（--reverse 首次出现即创建者）----
+function gitAuthors() {
+  return new Promise((resolve) => {
+    const GIT = process.platform === 'win32' ? 'git.exe' : 'git';
+    execFile(GIT, ['-c', 'core.quotepath=off', 'log', '--reverse', '--pretty=format:%x00%an', '--name-only', '--', 'workflow'], { cwd: ROOT, maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
+      if (err) { console.error('git log 取作者失败（卡片 author 置空）:', err.message); return resolve(new Map()); }
+      const map = new Map();
+      let author = '';
+      for (const line of stdout.toString('utf8').split(/\r?\n/)) {
+        if (line.startsWith('\0')) author = line.slice(1);
+        else if (line.trim() && !map.has(line.trim())) map.set(line.trim(), author);
+      }
+      resolve(map);
+    });
+  });
+}
+
+// ---- 看板全量数据：每次请求现扫磁盘（数据量小，无缓存即无失效 bug）----
+async function scanBoard() {
+  const authors = await gitAuthors();
+  const cards = [];
+  const counts = {};
+  for (const type of DOC_TYPES) {
+    const dir = path.join(WORKFLOW, type);
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('_TEMPLATE'));
+    counts[type] = files.length;
+    for (const f of files) {
+      let text = '';
+      try { text = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; } // watch 触发瞬间可能正被写，跳过等下次推送
+      const { meta, title } = parseDoc(text);
+      const accept = parseAcceptance(text);
+      const name = f.slice(0, -3);
+      cards.push({
+        type,
+        file: `${type}/${f}`,
+        name,
+        slug: name.replace(/^\d{4}-\d{2}-\d{2}-/, ''),
+        date: meta['日期'] || name.slice(0, 10),
+        status: meta['状态'] || NO_STATUS,
+        level: meta['级别'] || '',
+        title: title || name,
+        author: authors.get(`workflow/${type}/${f}`) || '',
+        ...(accept ? { accept } : {}),
+        // 告警规则用到的 frontmatter / 正文锚点（对照 check-loop：legacy 豁免、L3 确认三件）
+        ...(meta['流程'] ? { flow: meta['流程'] } : {}),
+        ...(meta['确认结果'] ? { confirm: meta['确认结果'] } : {}),
+        ...(meta['确认时间'] ? { confirmTime: meta['确认时间'] } : {}),
+        ...(L3_REVIEW.test(text) ? { hasReview: true } : {}),
+      });
+    }
+  }
+  detectAlerts(cards);
+  cards.sort((a, b) => b.date.localeCompare(a.date) || a.type.localeCompare(b.type));
+  return { root: ROOT, counts, cards };
+}
+
+// ---- 路径白名单：resolve 后必须仍在 workflow/ 内 ----
+function safeDocPath(rel) {
+  const abs = path.resolve(WORKFLOW, rel);
+  if (!abs.startsWith(WORKFLOW + path.sep) || !abs.endsWith('.md')) return null;
+  return abs;
+}
+
+function gitLog(rel) {
+  return new Promise((resolve) => {
+    const GIT = process.platform === 'win32' ? 'git.exe' : 'git'; // Windows spawn 不补 .exe 扩展名
+    execFile(GIT, ['log', '--follow', '--date=short', '--pretty=%H|%ad|%s', '--', rel.split('/').join(path.sep)], { cwd: WORKFLOW, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+      if (err) { console.error('git log 失败:', rel, err.message); return resolve([]); }
+      resolve(stdout.toString('utf8').split(/\r?\n/).filter(Boolean).map((l) => {
+        const [hash, date, ...rest] = l.split('|');
+        return { hash, date, subject: rest.join('|') };
+      }));
+    });
+  });
+}
+
+// ---- SSE 广播：fs.watch 防抖 500ms（AI 写盘常连发多事件，合并为一次推送）----
+const sseClients = new Set();
+let debounceTimer = null;
+function broadcast(event) {
+  for (const res of sseClients) { if (!res.destroyed) res.write(`event: ${event}\ndata: {}\n\n`); }
+}
+try {
+  const watcher = fs.watch(WORKFLOW, { recursive: true }, () => {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => broadcast('changed'), 500);
+  });
+  // watch 中途失效（目录被动/杀软锁）：显式告知前端降级轮询，避免假实时
+  watcher.on('error', (e) => { console.error('fs.watch 失效，已通知前端降级轮询:', e.message); broadcast('watchdead'); });
+} catch (e) {
+  console.error('fs.watch 初始化失败（前端将走 60s 兜底轮询）:', e.message);
+}
+// 25s 心跳：防半开连接；顺带清理已断开的 client
+setInterval(() => { for (const res of sseClients) { if (res.destroyed) sseClients.delete(res); else res.write(': ping\n\n'); } }, 25000).unref();
+
+const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8' };
+
+function sendJson(res, code, obj) {
+  res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(obj));
+}
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
+  try {
+    if (url.pathname === '/api/events') {
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+      res.write('retry: 3000\n\n');
+      sseClients.add(res);
+      req.on('close', () => sseClients.delete(res));
+      return;
+    }
+    if (url.pathname === '/api/board') return sendJson(res, 200, await scanBoard());
+
+    if (url.pathname === '/api/doc' || url.pathname === '/api/history') {
+      const rel = url.searchParams.get('file') || '';
+      const abs = safeDocPath(rel);
+      if (!abs) return sendJson(res, 403, { error: '路径不在 workflow/ 白名单内' });
+      if (url.pathname === '/api/doc') {
+        try { return sendJson(res, 200, { text: fs.readFileSync(abs, 'utf8') }); }
+        catch { return sendJson(res, 404, { error: '文件不存在' }); }
+      }
+      return sendJson(res, 200, { commits: await gitLog(rel) });
+    }
+
+    // 静态文件：/ 与 /marked.min.js，同样防穿越
+    const rel = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
+    const abs = path.resolve(BOARD_DIR, rel);
+    if (!abs.startsWith(BOARD_DIR + path.sep) || !fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+      res.writeHead(404); return res.end('not found');
+    }
+    res.writeHead(200, { 'Content-Type': MIME[path.extname(abs)] || 'application/octet-stream' });
+    fs.createReadStream(abs).pipe(res);
+  } catch (e) {
+    sendJson(res, 500, { error: e.message });
+  }
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(`workflow 看板: http://127.0.0.1:${PORT}  （Ctrl+C 停止；只读 workflow/，不写任何文件）`);
+});

package/templates/_agents/skills/verify-ui/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: verify-ui
+description: 启动本地服务并用浏览器实测 UI 改动（只读验证、不留脏数据）；项目无测试基建时靠实测兜底。当用户要求"实测 / UI 验证 / 浏览器验证"时使用。
+---
+
+# verify-ui — UI 实测引导（骨架，项目按实际填「启动命令 / 实测入口」）
+
+## 1. 起服务
+
+- API：<待填：启动命令（见 .agents/notes/runtime-env.md §2）>
+- 前端：<待填：启动命令>
+
+进程清单记进 `.agents/notes/runtime-env.md`，实测结束必须关闭。
+
+## 2. 实测步骤
+
+1. 打开目标页面，按改动点逐项操作：正常路径一条 + 失败路径一条（校验/空态/权限）。
+2. 证据落盘：截图或关键控制台/网络报文，路径写在任务文档「验收标准」勾验项后。
+3. 不留脏数据：验证产生的临时数据当场删除或还原；不确定可回滚的操作先停下问用户。
+
+## 3. 收尾
+
+- 关闭本次起动的全部进程（按 §1 清单逐个停）。
+- 结论按「页面 / 步骤 / 期望 vs 实际 / 证据」回报；发现缺陷只记录定性，不修代码（修复走 build/maintain 流程）。

package/templates/_agents/skills/wiki/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: wiki
+description: 项目 wiki 整理与验证技能。负责把项目内散落文档按主题归位到 wiki/，并维护 INDEX.md、知识沉淀总览.html、drafts-archive 归档一致性。当用户要求"整理 wiki/归类文档/建知识库/查文档归属"时使用。
+---
+
+# Wiki 整理与验证技能
+
+## 1. 何时调用本技能
+
+触发短语：
+- "整理 wiki / 归类文档 / 建知识库 / 同步知识沉淀看板"
+- "新增一篇文档到 wiki"
+- "校对 wiki 与 INDEX 是否一致"
+- "把 X.md 归到 wiki 的哪个主题"
+- "wiki 草稿归档 / 把原文归档"
+
+不要调用本技能的场景：
+- 询问文档内容本身（直接 Read 文件即可）
+- workflow/ 下文档（已明确排除）；`docs/`、`.trae/documents/` 均已于 2026-09-12 删除
+
+## 2. 核心约定（与 AGENTS.md 一致）
+
+- **范围**：主数据知识文档 + 全项目数据维护 SQL。MTO/采购/库存/UI 等非主数据知识文档原位不动，不入 wiki。
+- **目录结构**：`wiki/<主题>/<关键词文件>`，一级目录 = 主题，二级由文件组成（无强制二级子目录）。子目录（成套产物，见 INDEX 命名规则）中的 md/html 知识文档 2026-09-17 起计入登记与看板（`*.visual-check.*`/`.json`/`.png` 工具产物不计入；`数据维护` 主题子目录例外，仍走 README 台账）。看板中 html 格式文档的文件名为可点击链接（相对看板解析）。
+- **命名**：`<主题>-<关键词>[-范围/版本].ext`，例：`需求口径说明-正式.md`、`某系统-PRD-v3.0.md`。
+- **权威**：红线与闭环以 AGENTS.md / workflow 为准；wiki 承载当前态知识（领域 / 表 / 编码 / SQL 台账）。wiki 当前文档优于 `drafts-archive/`（归档仅历史快照）。
+- **双格式对（md + html 同内容）**：md 为权威内容源，html 为展示快照——内容冲突以 md 为准，改 md 后按需重出 html；速览表「用途」列标注权威关系。
+- **索引生成（2026-09-13 起）**：速览表计数/映射表/看板 DATA 由 `node .agents/scripts/gen-wiki-board.mjs` 自动生成——人工只维护磁盘文件 + 速览表「用途」列；收录/删除/移动文件后必跑生成器（新主题用途列为 `<待补>` 时补描述后重跑）。写盘前可先 `--dry-run` 看差异（`--help` 打印用法，未知参数 exit 1）。
+- **归档目录**：`wiki/drafts-archive/YYYY-MM-DD_<主题>/`，按整理批次日期+主题命名，保留原文件名。
+- **排除**：`workflow/`、依赖锁文件、IDE 配置。
+
+## 3. 标准操作流程
+
+### 3.1 整理（新建/批量归位）
+
+1. **识别范围**：列出候选文件后逐篇读首行判断主题——pwsh：`Get-ChildItem -Recurse -File -Include *.md` / `Get-Content <文件> -TotalCount 8`；POSIX：`find` / `head -8`。
+2. **主题判定**：主题由内容自决，不预设分类。当前已沉淀主题：`产品需求 / 项目计划 / 开发方案 / 用户功能 / 项目规范 / 测试报告 / 数据维护`。新增主题前先与用户对齐。
+3. **建目录**：pwsh `New-Item -ItemType Directory -Force wiki/<主题>`（POSIX：`mkdir -p`）；归档目录同理建 `wiki/drafts-archive/YYYY-MM-DD_<主题>`。
+4. **复制并改名**：pwsh `Copy-Item 原路径 wiki/<主题>/<新名>`（POSIX：`cp`）；来源为仓库内原位文件时，同时按原名复制一份到 `drafts-archive/YYYY-MM-DD_<主题>/` 留溯源。
+5. **生成索引**：跑 `node .agents/scripts/gen-wiki-board.mjs`（速览计数/映射表/看板 DATA 自动重生成）；新主题在速览表「用途」列补一行描述后重跑。
+6. **自检**：跑第 4 节"验证脚本"，确认三方一致、目录无孤儿。
+
+### 3.2 新增单篇文档（新产出直接落活跃层）
+
+新产出的文档**直接归入 `wiki/<主题>/`**，不强制进 `drafts-archive/`——归档只承载整理前的历史原位文档（口径见 §3.1 第 4 步）。
+
+```
+1. 读文件首行判定主题
+2. Copy-Item 原文件 wiki/<主题>/<主题>-<关键词>.<ext>   # POSIX：cp
+3. node .agents/scripts/gen-wiki-board.mjs              （索引自动生成，无需手工改映射表/看板）
+4. 跑 §4 验证
+```
+
+### 3.3 删除/归档 wiki 中错误归位
+
+```
+1. 从 wiki/<错误主题>/ 移到 wiki/<正确主题>/，若改名也同步
+2. drafts-archive 不动（归档记录原貌）
+3. node .agents/scripts/gen-wiki-board.mjs
+4. 跑 §4 验证
+```
+
+### 3.4 重建看板
+
+`wiki/知识沉淀总览.html` 的 DATA 块由生成器从磁盘 + 速览表用途列自动生成（2026-09-13 起）。看板与磁盘不一致时：先跑 `node .agents/scripts/gen-wiki-board.mjs` 再跑 §4 验证；仍不一致说明有人手改了生成区——以生成器输出为准。
+
+## 4. 验证脚本（必跑）
+一条命令完成全部校验（磁盘 ↔ INDEX ↔ 看板 DATA ↔ summary 统计 ↔ 幽灵目录 ↔ 活跃层 file:/// 断链守卫 ↔ 数据维护台账登记 ↔ 看板链接可达性）：
+
+```bash
+node .agents/scripts/verify-wiki-consistency.mjs
+```
+
+- 通过：输出 `✅ wiki 三方一致：文件 N 份 / 主题 N 个（含占位）/ 归档 N 份`，exit 0
+- 失败：逐条列出不一致项，exit 1。除文件集合 / 计数外还覆盖：`wiki/数据维护/` 下子目录（含批次目录）未在 `wiki/数据维护/README.md` 登记、看板「打开目录」链接（`DATA.dir`，相对看板自身 `wiki/` 解析）指向不存在的目录
+- 占位主题（磁盘有目录但 0 文件）只输出 `ℹ️` 提示、不算失败；当前 7 个主题均非空（`开发方案` 2026-09-12 起已有 2 份表设计 md+html）
+- 改了 wiki 内容/INDEX/看板任一处后必须重跑；三者任何一处漏同步都会被拦下
+
+## 5. 命名冲突与歧义处置
+
+- **同名不同扩展**：例如 `数据字典-修复.sql` 与 `数据字典-修复.md` —— 文件名可重复，但 `INDEX.md` 与看板 `DATA` 用 `file` 字段存完整文件名（含扩展）以区分。
+- **跨主题歧义**：用户说"X 放哪"拿不准时，读首行 + 第一段判断；仍无法判定就先与用户确认主题，不预设兜底主题、不自造归类。
+- **二进制（xlsx/csv/sql/json）**：允许直接归位到对应主题；不要为它们新建 markdown 索引——需要说明用途时写进 `wiki/INDEX.md` 速览表的「用途」列（唯一人工维护位，用例描述一句话；该表计数与映射表、看板 DATA 均为生成区，会被 `gen-wiki-board.mjs` 重写）。`wiki/数据维护/` 下的脚本与批次目录则在 `wiki/数据维护/README.md` 台账加登记行（verify 会拦未登记目录）。
+
+## 6. 已知边界
+
+- **workflow/ 永不入 wiki**：闭环工作流目录是项目规范明文排除项。
+- **非主数据知识文档不入 wiki**（MTO/采购/库存/UI 等）——有意决策（2026-09-13 显式化；债与扩展触发条件见 `wiki/INDEX.md` §范围边界决策）；数据维护 SQL 为全项目，不受此限。
+- **dependency 锁文件 / IDE 配置**：不入 wiki（`package-lock.json`、`pnpm-lock.yaml`、`*.sln`、`*.esproj` 等）。
+- **批量整理只动一份副本**：本技能只复制（`Copy-Item` / `cp`），不删除原文件；删除原文件需要用户在对话内单独确认（这是 STOP 线场景）。
+
+## 7. 与 AGENTS.md 衔接
+
+- 改动 `wiki/INDEX.md`、`wiki/知识沉淀总览.html`、`.agents/skills/wiki/SKILL.md` 属 docs 级改动，**豁免 intent**，走 Conventional Commits 直接 commit：`docs(wiki): <动作>`。
+- 若同时改 wiki 内某个具体知识文档（含路径变更/改名），按该文档原主题级别立 intent / incident。
+- wiki 不替代 AGENTS.md / workflow 的红线与闭环；与二者冲突时以 AGENTS.md / workflow 为准。wiki 与 `drafts-archive/` 冲突时以 wiki 当前文档为准。
+
+## 8. 失败模式与回滚
+
+- **忘跑生成器**：磁盘文件动了没跑 `gen-wiki-board.mjs` → §4 脚本报「仅在看板上 / 仅在磁盘上」差异 → 跑生成器即对齐。
+- **手改生成区**：速览计数/映射表/看板 DATA 是生成产物，手改会被 verify 拦且下次生成被覆盖——用途列才是人工编辑位。
+- **原文件误删**：本技能只复制（`Copy-Item` / `cp`），不删原文件；若用户单独要求删除原文件，必须先列目录确认（pwsh `Get-ChildItem` / POSIX `ls`）再操作。
+- **主题命名反复**：以 §4 脚本 A 段为最终事实；速览表用途列的 `<待补>` 提示新主题未补描述。
+- **全文检索**：找「哪个文件讲过 X」用 `node .agents/scripts/wiki-search.mjs <关键词>`（wiki 活跃层，多词 AND；不扫归档；默认跳过 json/csv、视觉校验产物与 >180KB bulk 文件，`--include-generated` 纳入）；跨语料（workflow 流程留痕 + wiki）用 `node .agents/scripts/kb-search.mjs "<词>"`。

package/templates/_agents/workflow-modules.txt

@@ -0,0 +1,11 @@
+# workflow 文档模块词表（单源：check-loop.sh 与 .agents/scripts/gen-workflow-index.mjs、kb-search.mjs 共读）
+# 用法：workflow/{intents,specs,plans,incidents} 文档 frontmatter `模块:` 取下列之一（单值，取主导模块；
+#       跨模块任务取承载任务意图的模块，检索面由 kb-search 全文兜住）。
+# 新建文档必填；check-loop 只警告不阻断。按项目模块自行改这张表（改后同步 workflow/README.md「文档协议」段说明）。
+backend
+frontend
+ui
+infra
+integration
+pipeline
+wiki

package/templates/_githooks/commit-msg

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Git commit-msg hook：提交类型枚举校验（自 pre-commit 迁入，2026-09-18 papercut 升级修复）
+# AGENTS.md「git提交」：Conventional Commits 中文，feat/fix/docs/style/refactor/perf
+# merge/revert 提交豁免（含自定义小写 merge:/revert: 前缀）；$1 为 git 传入的本次消息文件（真实待提交内容）
+
+msg=$(head -1 "$1" 2>/dev/null)
+case "$msg" in
+  [Mm]erge*|[Rr]evert*|"") ;;
+  *)
+    if ! echo "$msg" | grep -qE "^(feat|fix|docs|style|refactor|perf)(\(|:|（)"; then
+      echo "commit-msg: 提交类型须为 feat/fix/docs/style/refactor/perf（AGENTS.md「git提交」），当前首行：$msg" >&2
+      exit 1
+    fi
+    ;;
+esac

package/templates/_githooks/post-commit

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Git 原生 post-commit hook（经 core.hooksPath 挂载，git commit 后触发）
+# 非阻断缓存维护：把本次提交触及的 workflow/、wiki/ 文件从 kb-search 结构缓存
+#   （.agents/cache/kb-index.json）摘除，收敛 [mtimeMs,size] 两元组的
+#   「同刻同尺寸」失效盲区至提交时点。
+# 判据与设计：workflow/intents/2026-09-23-kb-cache-post-commit-evict.md
+# 失败绝不影响提交结果：post-commit 本身非阻断 + evict 脚本坏输入静默 exit 0 + 此处 || true 三重兜底。
+git diff-tree --no-commit-id --name-only -r HEAD \
+  | node .agents/scripts/kb-cache-evict.mjs 2>/dev/null || true
+exit 0