agentic-flow-kit 1.8.7 → 2.0.0

package/templates/engine/.agents/skills/csharp-quality-gates/scripts/quality-gates.mjs

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+// quality-gates.mjs — C# 后端质量门手动触发器（CRAP / 变异 / 重复）
+//
+// 定位：确定性动作下沉到本脚本（跑覆盖率、解析报告、汇总），模型只做判断（解读与优先级）。
+// 三道门与 Uncle Bob ub-mode 的对位：
+//   crapper  → dotnet-crap   （Crap4DotNet，CRAP = CC²×(1-cov)³+CC，公式一致）
+//   mutator  → dotnet stryker（Stryker.NET，自带覆盖率引擎，不依赖 coverlet）
+//   dryer    → PMD CPD       （--language cs，注意是 cs 不是 csharp）
+//
+// 关键约束（全部来自本仓 2026-10-31 实测，详见 .agents/skills/csharp-quality-gates/SKILL.md）：
+//   1. coverlet 在本机默认 TEMP 下会静默产出 0% 覆盖率 → 跑覆盖率前必须把 TEMP/TMP 改道到
+//      工作区内目录；脚本已内置，并在采集结果为 0 时大声报错而不是继续往下走。
+//   2. cobertura 落在 <results>/<guid>/coverage.cobertura.xml 子目录 → 脚本递归找最新的那个。
+//   3. dotnet-crap --coverage 只吃绝对路径。
+//   4. PMD 的 C# 语言标识是 cs；--no-cache 不是合法选项。
+//   5. 只跑单测工程（集成测试要 DB，CI mid 档也不跑它）；Stryker 必须定点，全量 2 万+ 变异点不可接受。
+//
+// 命令：doctor | coverage | crap | dup | mutate <glob> | all
+// 退出：0 通过；1 门未达标（有方法超阈值 / 有重复块）；2 用法·配置·采集失败。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, '..', '..', '..', '..');
+const WORK = path.join(REPO, '.agents', 'tmp', 'quality-gates');
+const TMP = path.join(WORK, 'tmp');
+const COV_DIR = path.join(WORK, 'coverage');
+const SOLUTION = path.join(REPO, 'Shipyard.Material.sln');
+const UNIT_TEST_PROJ = path.join(REPO, 'tests', 'Shipyard.Material.Tests', 'Shipyard.Material.Tests.csproj');
+const BACKEND = path.join(REPO, 'backend');
+
+const argv = process.argv.slice(2);
+const cmd = argv[0] && !argv[0].startsWith('-') ? argv[0] : '';
+
+class UsageError extends Error {}
+
+function opt(key, fallback) {
+  const prefix = `${key}=`;
+  const i = argv.indexOf(key);
+  if (i >= 0) {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith('--')) throw new UsageError(`${key} 缺少取值`);
+    return v;
+  }
+  const j = argv.indexOf(prefix);
+  if (j >= 0) {
+    const v = argv[j + 1];
+    if (v === undefined) throw new UsageError(`${key} 缺少取值`);
+    return v;
+  }
+  return fallback;
+}
+
+function positional() {
+  return argv.slice(1).filter((a) => !a.startsWith('-'));
+}
+
+// ── 工具解析：PATH → ~/.dotnet/tools → 已知安装位 ──────────────────────────
+function which(name) {
+  const exts = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const d of dirs) {
+    for (const e of exts) {
+      const p = path.join(d, name + e);
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) return p;
+    }
+  }
+  return null;
+}
+
+function resolveDotnetTool(name) {
+  return (
+    which(name) ||
+    (fs.existsSync(path.join(os.homedir(), '.dotnet', 'tools', `${name}.exe`))
+      ? path.join(os.homedir(), '.dotnet', 'tools', `${name}.exe`)
+      : null)
+  );
+}
+
+function resolveDotnet() {
+  return process.env.DOTNET_HOST_PATH || which('dotnet') || 'C:/Program Files/dotnet/dotnet.exe';
+}
+
+// PMD 是 Java 应用；不经过 pmd.bat（Windows 的 .bat 无法被 spawnSync 直接执行，
+// 静默失败会得到「0 重复」的假象），改为直接调 java + PMD 官方 main class。
+function resolvePmdHome() {
+  const candidates = [];
+  if (process.env.PMD_HOME) candidates.push(process.env.PMD_HOME);
+  const root = path.join(os.homedir(), '.agents', 'tools', 'pmd');
+  if (fs.existsSync(root)) {
+    for (const d of fs.readdirSync(root).filter((x) => x.startsWith('pmd-bin-')).sort().reverse()) {
+      candidates.push(path.join(root, d));
+    }
+  }
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, 'lib')) && fs.existsSync(path.join(c, 'conf'))) return c;
+  }
+  return null;
+}
+
+function resolveJava() {
+  return process.env.JAVA_HOME
+    ? path.join(process.env.JAVA_HOME, 'bin', 'java.exe')
+    : which('java') || 'java';
+}
+
+// ── 进程执行 ───────────────────────────────────────────────────────────────
+function run(file, args, opts = {}) {
+  const r = spawnSync(file, args, {
+    cwd: opts.cwd || REPO,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    env: { ...process.env, ...(opts.env || {}) },
+    shell: false,
+  });
+  if (r.error) {
+    // spawn 失败必须响亮：静默的空输出会被下游读成「0 重复 / 0 覆盖」这类假结论。
+    throw new Error(`无法执行 ${file}：${r.error.message}`);
+  }
+  return {
+    status: r.status === null ? -1 : r.status,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+  };
+}
+
+// ── 工具函数 ───────────────────────────────────────────────────────────────
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function newestFile(root, name) {
+  let best = null;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name === name) {
+        const t = fs.statSync(p).mtimeMs;
+        if (!best || t > best.t) best = { path: p, mtime: t };
+      }
+    }
+  };
+  walk(root);
+  return best ? best.path : null;
+}
+
+function readCoberturaStats(file) {
+  const xml = fs.readFileSync(file, 'utf8');
+  const root = /<coverage\b[^>]*>/.exec(xml);
+  if (!root) return null;
+  const attr = (k) => {
+    const m = new RegExp(`${k}="([^"]*)"`).exec(root[0]);
+    return m ? m[1] : null;
+  };
+  return {
+    lineRate: attr('line-rate'),
+    linesCovered: Number(attr('lines-covered') || 0),
+    linesValid: Number(attr('lines-valid') || 0),
+  };
+}
+
+// ── 命令实现 ───────────────────────────────────────────────────────────────
+function doctor() {
+  const rows = [];
+  const dotnet = resolveDotnet();
+  rows.push(['dotnet', dotnet, fs.existsSync(dotnet)]);
+  const crap = resolveDotnetTool('dotnet-crap');
+  rows.push(['dotnet-crap', crap || '(未安装)', !!crap]);
+  const stryker = resolveDotnetTool('dotnet-stryker');
+  rows.push(['dotnet-stryker', stryker || '(未安装)', !!stryker]);
+  const pmdHome = resolvePmdHome();
+  rows.push(['pmd', pmdHome || '(未安装)', !!pmdHome]);
+  const java = resolveJava();
+  rows.push(['java', java, fs.existsSync(java) || which('java') !== null]);
+  rows.push(['单测工程', UNIT_TEST_PROJ, fs.existsSync(UNIT_TEST_PROJ)]);
+  rows.push(['解决方案', SOLUTION, fs.existsSync(SOLUTION)]);
+
+  console.log('工具探测：');
+  for (const [n, p, ok] of rows) console.log(`  ${ok ? 'OK  ' : 'MISS'} ${n.padEnd(16)} ${p}`);
+  console.log('');
+  console.log('缺装时的安装命令：');
+  console.log('  dotnet tool install -g Crap4DotNet');
+  console.log('  dotnet tool install -g dotnet-stryker');
+  console.log('  PMD：下载 pmd-dist-<ver>-bin.zip 解压到 ~/.agents/tools/pmd/（语言标识是 cs）');
+  const missing = rows.filter((r) => !r[2]);
+  return missing.length ? 2 : 0;
+}
+
+function coverage() {
+  if (!fs.existsSync(UNIT_TEST_PROJ)) {
+    console.error(`单测工程不存在：${UNIT_TEST_PROJ}`);
+    return 2;
+  }
+  ensureDir(TMP);
+  ensureDir(COV_DIR);
+  // 关键：coverlet 在本机默认 TEMP 下会静默产出 0% 覆盖率 → 改道到工作区内目录。
+  const env = { TEMP: TMP, TMP: TMP };
+  console.log(`跑单测收覆盖率（TEMP 改道 → ${TMP}）…`);
+  const r = run('dotnet', ['test', UNIT_TEST_PROJ, '--collect:XPlat Code Coverage', `--results-directory=${COV_DIR}`], { env });
+  const tail = r.stdout.split(/\r?\n/).filter((l) => /已通过|失败|Passed!|Failed!|error/i.test(l)).slice(-3);
+  for (const l of tail) console.log(`  ${l.trim()}`);
+
+  const cov = newestFile(COV_DIR, 'coverage.cobertura.xml');
+  if (!cov) {
+    console.error('未产出 coverage.cobertura.xml —— 采集失败，勿把「无覆盖」当结论。');
+    return 2;
+  }
+  const stats = readCoberturaStats(cov);
+  console.log(`覆盖率文件：${cov}`);
+  console.log(`line-rate=${stats.lineRate}  lines-covered=${stats.linesCovered}/${stats.linesValid}`);
+  if (stats.linesValid > 0 && stats.linesCovered === 0) {
+    console.error('');
+    console.error('⚠ 采集结果为 0 命中 —— 这是采集故障，不是「代码没被测到」。');
+    console.error('  已知成因：coverlet 在某些 TEMP 目录下会丢失自己写的插桩模块，');
+    console.error('  testhost 退出时抛未处理 FileNotFoundException，命中数据不落报告。');
+    console.error(`  本脚本已把 TEMP 改道到 ${TMP}；仍为 0 则查该目录是否被清理/杀软拦截。`);
+    return 2;
+  }
+  console.log('');
+  console.log('下一步：node .agents/skills/csharp-quality-gates/scripts/quality-gates.mjs crap');
+  return 0;
+}
+
+function findCoverage() {
+  const explicit = opt('--coverage');
+  if (explicit) {
+    if (!fs.existsSync(explicit)) {
+      console.error(`覆盖率文件不存在：${explicit}`);
+      return null;
+    }
+    return explicit;
+  }
+  const cov = newestFile(COV_DIR, 'coverage.cobertura.xml');
+  if (!cov) {
+    console.error('未找到覆盖率文件——先跑 `coverage` 子命令（或用 --coverage <绝对路径> 指定）。');
+    return null;
+  }
+  const stats = readCoberturaStats(cov);
+  if (stats && stats.linesValid > 0 && stats.linesCovered === 0) {
+    console.error('⚠ 该覆盖率文件命中数为 0（采集故障），用它算 CRAP 会得到「纯复杂度排序」的假象。');
+    console.error('  请重跑 `coverage` 子命令（TEMP 改道后重采）。');
+    return null;
+  }
+  return cov;
+}
+
+function crap() {
+  const crapTool = resolveDotnetTool('dotnet-crap');
+  if (!crapTool) {
+    console.error('未找到 dotnet-crap —— 装：dotnet tool install -g Crap4DotNet');
+    return 2;
+  }
+  const cov = findCoverage();
+  if (!cov) return 2;
+
+  const threshold = Number(opt('--threshold', '30'));
+  const minCrap = Number(opt('--min-crap', '0'));
+  const topN = Number(opt('--top', '15'));
+  const outJson = path.join(WORK, 'crap-report.json');
+
+  console.log(`跑 CRAP 分析（threshold=${threshold}）…`);
+  const r = run(crapTool, ['analyze', SOLUTION, '--coverage', cov, '--output', outJson, '--threshold', String(threshold)]);
+  if (r.status === 2) {
+    console.error(r.stdout.trim() || r.stderr.trim());
+    return 2;
+  }
+  let j;
+  try {
+    j = JSON.parse(fs.readFileSync(outJson, 'utf8'));
+  } catch (e) {
+    console.error(`CRAP 报告解析失败：${e.message}`);
+    return 2;
+  }
+  const methods = j.methods || [];
+  const zero = methods.filter((m) => !m.coverage || m.coverage === 0);
+  const over = methods.filter((m) => (m.crap || 0) > threshold);
+  const danger = methods
+    .filter((m) => (!m.coverage || m.coverage === 0) && (m.crap || 0) > threshold)
+    .sort((a, b) => (b.crap || 0) - (a.crap || 0));
+
+  console.log('');
+  console.log(`方法总数 ${methods.length}  零覆盖 ${zero.length}（${Math.round((100 * zero.length) / (methods.length || 1))}%）  超阈值(>${threshold}) ${over.length}`);
+  console.log(`报告：${outJson}`);
+  console.log('');
+  console.log(`零覆盖且超阈值（补测优先级，按 CRAP 降序，取前 ${topN}）：`);
+  if (!danger.length) {
+    console.log('  （无）');
+  }
+  for (const m of danger.slice(0, topN)) {
+    const name = String(m.fullName || m.name || '').split('(')[0];
+    console.log(`  CRAP=${String(m.crap).padStart(8)}  CC=${String(m.complexity).padStart(3)}  cov=${m.coverage}  ${name}`);
+  }
+  if (minCrap > 0) {
+    const sel = methods.filter((m) => (m.crap || 0) >= minCrap).sort((a, b) => b.crap - a.crap);
+    console.log('');
+    console.log(`--min-crap ${minCrap} 命中 ${sel.length} 个方法（已含在报告中）`);
+  }
+  return over.length ? 1 : 0;
+}
+
+function dup() {
+  const pmdHome = resolvePmdHome();
+  if (!pmdHome) {
+    console.error('未找到 PMD —— 下载 pmd-dist-<ver>-bin.zip 解压到 ~/.agents/tools/pmd/（含 lib/ 与 conf/ 的那层）');
+    return 2;
+  }
+  const minTokens = opt('--minimum-tokens', '100');
+  const topN = Number(opt('--top', '10'));
+  const java = resolveJava();
+  const cp = [path.join(pmdHome, 'conf'), path.join(pmdHome, 'lib', '*')].join(path.delimiter);
+  console.log(`跑 PMD CPD 重复检测（--language cs --minimum-tokens ${minTokens}）…`);
+  const r = run(java, ['-cp', cp, 'net.sourceforge.pmd.cli.PmdCli', 'cpd', '--language', 'cs', '--minimum-tokens', minTokens, BACKEND]);
+  const text = r.stdout + r.stderr;
+  const blocks = [];
+  // 注意：PMD 输出里 "duplication in the following files:" 之后、行号之前都带尾随空格，
+  // 正则不容许它就会 0 匹配——静默变成「没有重复」。故此处 [ \t]* 必需。
+  const re = /Found a (\d+) line \((\d+) tokens\) duplication in the following files:[ \t]*\r?\n((?:Starting at line \d+ of [^\r\n]+\r?\n?)+)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const files = [];
+    const fre = /Starting at line (\d+) of ([^\r\n]+)/g;
+    let f;
+    while ((f = fre.exec(m[3])) !== null) files.push({ line: Number(f[1]), file: f[2].trim() });
+    blocks.push({ lines: Number(m[1]), tokens: Number(m[2]), files });
+  }
+  // 格式漂移守卫：文本里有 duplication 字样却一块没解析出来 → 解析器过期，不是「没有重复」。
+  if (!blocks.length && /duplication/i.test(text)) {
+    console.error('⚠ PMD 输出含 duplication 字样但未能解析出任何重复块——解析器可能已过期（PMD 升级改了输出格式）。');
+    console.error('  禁把本次结果当作「没有重复」；请人工看原始输出：');
+    console.error(text.split(/\r?\n/).slice(0, 20).join('\n'));
+    return 2;
+  }
+  console.log('');
+  console.log(`重复块数：${blocks.length}`);
+  const sorted = blocks.sort((a, b) => b.tokens - a.tokens);
+  for (const b of sorted.slice(0, topN)) {
+    const loc = b.files.map((x) => `${path.basename(x.file)}:${x.line}`).join('  |  ');
+    console.log(`  ${String(b.tokens).padStart(5)} tokens / ${String(b.lines).padStart(3)} 行   ${loc}`);
+  }
+  return blocks.length ? 1 : 0;
+}
+
+function mutate() {
+  const globs = positional();
+  if (!globs.length) {
+    console.error('用法：mutate <glob> [glob...]  —— 必须定点，全量 2 万+ 变异点不可接受');
+    console.error('例：mutate "**/PurchaseOrderService.cs"');
+    return 2;
+  }
+  const dotnet = resolveDotnet();
+  const args = [
+    'stryker',
+    '-p',
+    'Shipyard.Material.Application.csproj',
+    '--mutate',
+    globs[0],
+    '--skip-version-check',
+    '-O',
+    path.join(WORK, 'stryker'),
+  ];
+  for (const g of globs.slice(1)) args.push('--mutate', g);
+  console.log(`跑变异测试：${globs.join(' , ')}（可能耗时数分钟）…`);
+  const r = run(dotnet, args, { cwd: path.join(REPO, 'tests', 'Shipyard.Material.Tests') });
+  const out = r.stdout + r.stderr;
+  let willTest = null;
+  for (const l of out.split(/\r?\n/)) {
+    const m = /(\d+)\s+total mutants will be tested/.exec(l);
+    if (m) willTest = Number(m[1]);
+    if (/mutants created|NoCoverage|CompileError|mutation score|Killed:|Survived:/.test(l)) {
+      console.log(`  ${l.trim()}`);
+    }
+  }
+  // 假绿守卫：glob 没匹配到任何东西 → 0 个变异点待测 → 不是「通过」，是用法错。
+  if (willTest === 0) {
+    console.error('');
+    console.error('⚠ 0 个变异点待测 —— glob 没匹配到任何代码（Stryker 把全部变异点按 mutate 过滤掉了）。');
+    console.error('  禁把本次结果当作「变异测试通过」；请核对 glob（如 "**/PurchaseOrderService.cs"）与工程名。');
+    return 2;
+  }
+  console.log('');
+  console.log('解读要点：得分低先分清两种原因——');
+  console.log('  (a) 测试没断言到位（NoCoverage 少、被杀比例低）→ 测试无效');
+  console.log('  (b) 代码压根没被跑到（NoCoverage 多）→ 该路径缺测试，别急着加断言');
+  return r.status === 0 ? 0 : 1;
+}
+
+function all() {
+  console.log('══ 1/3 覆盖率 ══');
+  const c = coverage();
+  if (c !== 0) return c;
+  console.log('');
+  console.log('══ 2/3 CRAP ══');
+  const r1 = crap();
+  console.log('');
+  console.log('══ 3/3 重复代码 ══');
+  const r2 = dup();
+  console.log('');
+  console.log(`汇总：CRAP 门 ${r1 === 0 ? '通过' : '未达标'}；重复门 ${r2 === 0 ? '通过' : '未达标'}`);
+  console.log('（变异测试默认不跑：耗时长，需定点，见 `mutate <glob>`）');
+  return r1 === 0 && r2 === 0 ? 0 : 1;
+}
+
+const COMMANDS = { doctor, coverage, crap, dup, mutate, all };
+
+try {
+  if (!cmd) throw new UsageError('缺子命令');
+  const fn = COMMANDS[cmd];
+  if (!fn) throw new UsageError(`未知子命令：${cmd}`);
+  ensureDir(WORK);
+  process.exit(fn());
+} catch (e) {
+  if (e instanceof UsageError) {
+    console.error(`用法错误：${e.message}`);
+    console.error('命令：doctor | coverage | crap | dup | mutate <glob> | all');
+    process.exit(2);
+  }
+  console.error(`未预期错误：${e && e.stack ? e.stack : e}`);
+  process.exit(2);
+}

package/templates/engine/.agents/skills/dev-tour/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: dev-tour
+description: 把 spec/plan 的步骤与改动文件生成可交互开发全景图（全景/时序/数据流/流程图 + 文件树 + 右侧变更说明）。用于 AI-Native 开发中「文档说明了但看不到改哪些文件」的断点。
+---
+
+# 开发全景图（Dev Tour）
+
+## 目标
+把 workflow 文档里的「步骤 × 改动文件」变成一张可点的图：左侧文件树（新增/修改/计划徽标）、中间全景图/时序图/数据流图/流程图、右侧每一步的变更说明与 diff。解决「spec/plan 读起来明白，但不知道 AI 正在改哪个文件」的断层。
+
+## 触发条件
+- 起草/确认 plan 后（`## 任务拆解` 或 `## 步骤` + `## 改动方案` 已落盘）→ 跑 `auto-tour.mjs` 自动拉起看板并出实时链接。
+- Build 阶段每完成一个批次 / 一个任务后刷新一次。
+- 关单前做范围对账：图里出现「文档外实际改动」必须先解释或回填 plan。
+- 用户说「看不到改哪些文件」「给我看时序/流程/全景」。
+
+## 数据契约（写文档时就这样写）
+生成器不另造台账，直接读文档 + git：
+
+1. **步骤**（优先级从高到低）
+   - `## 步骤`：`1. **T1 标题**：一句话说明`
+   - `## 任务拆解`：`- [ ] 1. 标题` + 缩进的 `- 文件：路径` / `- 判据：…` / `- 留痕：…`；或 `### T1 · 标题` 子标题（正文明细行随步骤收口）。**每个实现步骤至少一个文件；纯验证步骤在标题写明「验证步骤」**
+   - `## 改动面` / `## 改动方案` 下的 `### 批次 0a：…` 标题
+   - 都没有时：按文件所属架构层分组（**层兜底 = 解析失败信号**，生成器打印「解析命中」行、页面顶部出警告条；应规范标题后重生成，`--strict` 时拒产 exit 1）
+2. **每步文件**
+   - 在 `## 改动方案` 用 `- **T1**：` 或 `### T1` 与步骤编号对齐，块内写反引号路径。
+   - L1 单文件计划可直接在 `## 改动方案` 写 `- \`backend/.../Foo.cs\`：做什么`；每个顶层文件条目自动成为一站。
+   - 路径尽量写全；只写 `detail.vue` / `MaterialCodePushService.cs` 也能按仓库同名文件与步骤上下文解析，但全路径最稳。同名多候选时按步骤上下文打分猜一个：该文件条目带 `pathGuess` 标志（页面打「猜?」不确定徽标）、命中行计「路径猜测 Z 处」——basename 唯一命中是确定性的，不算猜测。
+   - 未反引号但带代码扩展名且可消解的中段路径也会被采集：步骤标题/正文/表格行里裸写的 `pml/index.vue` 这类 token（含 `/` + 已知代码扩展名 + 能消解到仓库真实文件）会入模归入所在步骤；杂型 token（`if/else` 等）一律拒收。未绑定步骤的文件靠正文兜底归步时（basename 或层词臂）均打 `pathGuess` 标；层词臂仅在恰一个步骤正文含该层词时才绑，多义不绑、留「未分步」可见。
+   - 表格行路径也会被采集：`## 改动方案` 的 `| \`path\` | 说明 |` 行归入当前块/批次锚（含 `### 批次` 子节内表格）；无锚时进「改动面（未分步）」。任务行标签支持并集式 `1. S1+S2：标题`（块锚按成员交集命中，括注 `（**S3**）` 同样成锚）；消解不伪造——目录反推/锚点拼接必须落到仓库真实文件，未落库路径原样保留为可见的未解析。
+3. **测试文件**：写在 `## 验证计划` 或对应步骤里，测试步骤会自动收口。
+4. **依赖**（可选，流程图旁路弧数据源）
+   - `## 执行顺序` 里的 `依赖：3 依赖 1；4/5 依赖 2 与 3；8 依赖 4~7；10 依赖全部` 子句行（箭头链行 `1 → 2 → 3` 本身由主链表达，不重复产边）。
+   - 或任务行内 `- 依赖：T1、T2`。
+   - 编号按步骤序号 / `Tn` / 标签 id 归一；解析不到的引用计入 `deps.unresolved` 并打印警告。
+5. **实际改动**：`git diff --base` 自动补状态、行数、diff；文档没登记的文件进「文档外实际改动」，不静默丢弃。
+
+## 生成 / 刷新
+```bash
+# 静态快照（默认 .agents/cache/tours/<type>-<name>.html）
+node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md
+
+# 对比已提交的整段任务（默认 HEAD = 当前未提交工作树）
+node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md --base origin/main
+
+# 只看模型（调试解析）
+node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md --json
+
+# 门禁化：层兜底/无步骤/实现步骤无文件时拒产（exit 1；纯验证步骤按标题豁免）
+node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md --strict
+```
+
+每次生成会打印「解析命中：直认 X/Y 步 … · 路径猜测 Z 处」行——直认率 <100% 先看是不是标题失约，再决定是否接受兜底归集；命中行之后逐条打印「⚠ 第 N 行：<标题>：<原因>」，把失约定位到行（步骤无对齐文件块 / 文件块锚点未对齐任何步骤 / 依赖引用未解析 / 层兜底触发，对应模型 `parseHealth.issues` 的 `{line,title,kind}`；`pathGuess` 与 issues 一律 advisory，不参与 `--strict` 拒产）。页面顶部警告条消费同一份 issues：按 `kind` 归并成「文件块未对齐 / 步骤缺文件 / 依赖未解析」几类，组内再展开逐行；`step-no-files` 中标题含「验证步骤/单测/UI 实测/静态门」的条目单列为“验证步骤”，不计入待修。
+
+实时版（推荐 Build 阶段一直开着）：
+```bash
+# 自动拉起看板 + 打印本 plan 的实时链接（幂等复用，不弹浏览器；拉不起来只告警不阻断）
+node .agents/scripts/auto-tour.mjs workflow/plans/<name>.md
+# → http://127.0.0.1:8933/tour?file=workflow/plans/<name>.md
+
+# 只拉看板不指定文档
+node .agents/scripts/ensure-board.mjs
+```
+实时页每 5s 拉 `/api/tour`，文档保存 / 工作树变化会自动重绘，保留当前选中步骤与视图。
+
+## 视图
+- **全景图**：默认网格（每站一张大卡，按编号阅读）；右上「布局」可切横向时间线；「专注全景」隐藏左右栏，6 站通常两行看完。
+- **时序图**：按每步文件的架构层（前端 → API → 应用 → 领域 → 基础设施 → DB）连箭头；测试步骤补虚线验证箭头。
+- **数据流图**：从 diff 新增行与文档正文静态识别跨文件数据对象（Dto/实体/表），按架构层泳道显示对象流经的层与文件，并列出「定义步骤 → 使用步骤」的传递边；点击对象联动步骤/文件（数据来自模型 dataflow，schema 2；无识别结果时该视图隐藏）。
+- **流程图**：计划 → 步骤 → 验证门 → 关单；验证门读 `## 验证计划`。模型 `deps.edges` 非空时，主链左侧细轨画出声明依赖的旁路弧（已传递归约、主链相邻边不重复画；指向先前行=异常反向虚线），hover 步骤高亮其上下游弧与对端步骤。
+- **需求**：跟随「对应入口/spec：…」链接读上游文档（一层不递归，最多 3 篇），渲染本档目标 + 上游 intent/spec/incident 的目标与行为/验收要点（模型 `doc.upstream`）；无上游文档时该视图隐藏，需求叙事只看本档 purpose。
+- **验证**：左侧计划清单（`## 验证计划`），右侧实际凭证——本机 `.agents/verifications.jsonl` 优先、仓库 `workflow/verify-evidence.md` 兜底合并（ts+head 去重），按文档日期时间窗取最近 10 条（模型 `evidence`）。关联语义是「任务时间窗内的验证凭证」非逐条绑定；流程图验证门同步显示窗内最近凭证；窗内无凭证时视图隐藏。
+- **联动**：点站点/文件/步骤卡/时序消息都会同步左侧树与右侧说明；`←/→` 切步骤，`Esc` 清除；「跟着流程走」自动播放。
+
+## 适用规模（2026-11-11 实测）
+复现：`node .agents/tests/tools/gen-synthetic-plan.mjs --bench`（合成 plan 落 `.agents/cache/tour-perf/`；build 计时走 `buildTour({git})` 注入 300 个修改文件，3 轮取最大；HTML 由 `gen-dev-tour.mjs --no-diff` 生成，git 面为当刻真实工作树，体积以文档面为主）。
+
+| 档位 | buildTour（300 diff 文件注入） | 静态 HTML 体积 |
+| --- | --- | --- |
+| 10 步 | 317–332 ms | ~100 KB |
+| 30 步 | 348–350 ms | ~131 KB |
+| 60 步 | 474–483 ms | ~178 KB |
+
+边界声明：实测覆盖 ≤60 步 / 300 diff 文件，且该范围内 build 耗时无拐点（远低于 5s）；超出范围未验证，不凭线性外推下结论。浏览器侧实测（Chrome，file:// 静态页，60 步档）：整页 1868 DOM 节点、加载 289ms、六视图切换各 14–22ms——该量级无需虚拟化。
+
+## 边界
+- 文档是计划面，git 是实际面；两者冲突时图上会分栏显示（计划 / 文档外）。
+- 不替代 plan 的验收判据与 `check-scope.mjs`；它只是把同一份事实可视化，不新增真相源。
+- 生成物默认在 `.agents/cache/tours/`，不提交；要留档用 `--out wiki/...` 或截图，不把 HTML 塞进 workflow/。
+- 视图用量数据（`/api/tour/usage`）只落本机 `.agents/cache/tour-usage.jsonl`，不提交不外发；一个迭代后按使用率裁剪最低使用视图（数据流图为首要观察对象），不建查询聚合页，直接用 node 统计。
+- 引擎面（`.agents/`）改动照常走 `check-scripts-syntax` 等门；本技能不豁免任何门禁。
+
+## 验收
+- [ ] 文档有 ≥1 个步骤；每步至少一个文件，或明确是「验证步骤」。
+- [ ] 「解析命中」无层兜底（页面无警告条）；有兜底 = 标题失约，先修文档。
+- [ ] 图上「文档外实际改动」为空，或有解释/回填。
+- [ ] 四种视图切换无空白；点文件能定位到步骤与 diff。
+- [ ] 实时页标题旁显示「实时」，断线时降级「轮询」。

package/templates/engine/.agents/skills/dream/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: dream
+description: 离线梦境（Dreaming）——对照 Anthropic 记忆架构的周期性记忆维护：运行 dream-run 审计、读报告、委托 independent-reviewer 核验 AI Judge 抽样、回写 papercuts/修正笔记、处置冷数据候选；供主智能体在会话内执行 Dreaming 持续运行链路时使用。
+---
+
+# dream — 离线梦境（Dreaming）持续运行链路
+
+## 触发
+
+- post-commit 出现 `[dream]` advisory（距上次审计 ≥7 天或无报告）。
+- session-resume 重建时发现 `tmp/dream-report-*.md` 或 `tmp/dream-judge-brief-*.md`。
+- 用户主动要求「跑梦境审计 / Dreaming」。
+
+## 1. 运行审计
+
+```bash
+node .agents/scripts/dream-run.mjs              # dry-run：只读审计 + AI 抽样简报（默认）
+node .agents/scripts/dream-run.mjs --execute    # 执行安全修复（仅终态件归档 + 索引重生成）
+```
+
+- 报告落 `tmp/dream-report-<date>.md`（gitignore）；AI Judge 简报落 `tmp/dream-judge-brief-<date>.md`。
+- `--execute` 只做「终态件归档 + 索引重生成」，不改写任何文档内容。
+- 不自动 commit / push（根 AGENTS.md 禁令）。
+
+## 2. 读报告
+
+读最新 `tmp/dream-report-*.md`，关注：
+
+- A 终态件归档（archive-sweep，21 天窗口）；
+- B 索引漂移与 wiki 三方一致；
+- C 全量对账（check-loop，hard 6 段）；
+- D 错类候选（agg-judgments --retire-candidates）；
+- E 常驻面预算（rule-budget --all）；
+- E2 冷数据候选（agg-kb-usage --stale-days 90）——访问/命中遥测 + 置信度衰减，见 §5；
+- F AI Judge 抽样审计简报。
+
+## 3. 核验 AI Judge 抽样
+
+1. 读 `tmp/dream-judge-brief-*.md`；
+2. 复制简报末尾「Judge 委托模板」给 independent-reviewer 角色核验；
+3. 核验结论按 BLOCK / WARN / OK 处置：
+   - **BLOCK**：对照原始证据修正 workflow 文档声明（改后不自动 commit）；
+   - **WARN**：登记 papercuts 或补证据；
+   - **OK**：无动作。
+
+## 4. 回写
+
+- 错类候选：按 `.agents/skills/papercut-fix/SKILL.md` 错题回路处置（≥3 次立规则，落点阶梯 类型→门禁→测试→冒烟→prompt）。
+- 核验发现：修正笔记 / 登记 `workflow/papercuts.md`。
+
+## 5. 处置冷数据候选
+
+- 冷数据候选来自 `agg-kb-usage.mjs`（遥测口径：最近 90 天既未被 kb-search 命中、内容也未更新）。
+- 处置阶梯（由主智能体/用户裁决）：
+  1. 归档：`node .agents/scripts/archive-sweep.mjs --execute`（终态件，21 天窗口）；
+  2. 更新：走 wiki 技能更新知识；
+  3. 删除：**须用户单独指令**（根 AGENTS.md 不可逆操作红线）。
+
+## 红线
+
+- `--execute` 只做归档 + 索引重生成，不改写文档正文。
+- 不自动 commit / push；删除 wiki 文件须用户单独指令。
+- 本技能是执行链路：判断由 AI 执行，确定性脚本只做采样与证据收集（「确定性脚本管事实，模型管判断」）。

package/templates/engine/.agents/skills/eval/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: eval
+description: 盲评技能/提示词改动——A/B 两臂、同模型同上下文、已知答案任务集，算命中率与 Δ；供「这个技能改动真的有用吗」时使用。
+---
+
+# eval — 盲评改动
+
+## 触发
+
+- 新增/修改技能、提示词、结构，想知道是否真的改善行为。
+- `/reflect` 落了一次技能修改，需要证据决定保留/回退。
+- 两个方案争不出高下，用任务集裁决。
+
+## 步骤
+
+1. **定义任务集**：5–10 个任务，每个有**已知答案/验收判据**；正例与负例都要有。写成 TSV：
+   ```
+   task	expected	a	b
+   ```
+   `a`/`b` 先留空，跑完填 `pass`/`fail`。
+2. **定义两臂**：A = 带新技能/新提示；B = 不带/旧版。**同模型、同上下文、同任务**；评估者不知道哪臂是哪臂（盲评）。
+3. **跑**：每个任务用**新子代理**跑两臂，互不共享结论；记录实际结果对照 `expected`。
+4. **算**：`node .agents/skills/eval/scripts/eval-score.mjs <results.tsv>` → A/B 命中率、Δ、翻转任务。
+5. **判**：Δ 明显且翻转可解释 → 保留；Δ 接近 0 或负 → 回退/调整；翻转多 → 任务歧义，先修任务集。
+6. **落账**：结论写任务文档或 `workflow/reviews.d/<当月>.md`；机制改动更新 `mechanism-registry.md`。
+
+## 任务集模板
+
+```
+task	expected	a	b
+bug-fix-1	复现失败用例后修复，测试转绿		
+bug-fix-2	不修改测试断言，只改实现		
+feature-1	新增行为有边界用例		
+negative-1	拒绝在无 spec 时直接实现		
+```
+
+## 边界
+
+- 小 N 有噪声；Δ < 20pp 不要宣称有效。
+- 不盲评就不是 eval——评估者知道臂别会自我实现。
+- 不用同一模型跑两臂又当裁判；裁判用不同模型或人工。
+- 任务集要能区分「技能有用」与「模型本来就会」；负例是防自欺的关键。