agentic-flow-kit 0.2.0

package/src/sync.mjs

@@ -0,0 +1,141 @@
+// flow-kit sync：按 .agents/kit.json 台账升级 managed 文件。
+// 三态：未改动（磁盘 sha==台账）→ 覆盖新版；本地已改 → 跳过并报告（--force 覆盖）；
+//       生成器目标（INDEX.md / wiki 看板）→ 不比对，收尾重跑生成器走锚点重写。
+// 附带：包内新增 managed 文件 → 安装；包内已删 → 仅报告不删盘、出台账；managed 缺失 → 恢复。
+// owned 文件永不触碰（两态模型，见 profiles.isOwned）。
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { renderTree, sha256 } from './render.mjs';
+import { HOSTS, pickStackVars, isOwned } from './profiles.mjs';
+import { doctor } from './doctor.mjs';
+
+function fail(msg) {
+  console.error(`❌ ${msg}`);
+  process.exit(1);
+}
+
+function runNode(target, script, args = []) {
+  const r = spawnSync(process.execPath, [script, ...args], { cwd: target, encoding: 'utf8' });
+  return { ok: r.status === 0, out: `${r.stdout || ''}${r.stderr || ''}` };
+}
+
+export function sync(args, pkgRoot) {
+  let target = process.cwd();
+  let force = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--dir') target = path.resolve(args[++i] || fail('--dir 缺少值'));
+    else if (args[i] === '--force') force = true;
+    else fail(`未知选项：${args[i]}（flow-kit sync --help 看全部）`);
+  }
+
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (!fs.existsSync(kitPath)) fail(`${target} 无 .agents/kit.json——先 flow-kit init（手动安装的旧项目无台账，不支持 sync）`);
+  let kit;
+  try {
+    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+  } catch (e) {
+    fail(`kit.json 解析失败：${e.message}`);
+  }
+  const opt = kit.options || {};
+  const hosts = Array.isArray(opt.hosts) ? opt.hosts : [];
+  const vars = { BOARD_PORT: String(opt.boardPort || '8933'), ...pickStackVars(opt.stack) };
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+  console.log(`▶ flow-kit sync → ${target}（台账版本 ${kit.version} → 包版本 ${pkg.version}）`);
+
+  // 当前包内存渲染到临时目录（只读比对源；不直接写目标——三态判定必须先于落盘）
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-kit-sync-'));
+  try {
+    // rel → 渲染产物（新包视角的"应有文件"清单）
+    const fresh = new Map();
+    const t = renderTree(path.join(pkgRoot, 'templates'), tmp, vars, { force: true });
+    for (const f of t.written) fresh.set(f.rel, { sha: f.sha256, abs: path.join(tmp, f.rel) });
+    for (const h of hosts) {
+      if (!HOSTS[h]) continue; // 台账里的宿主已不在包支持列表——只按模板层同步
+      const hr = renderTree(path.join(pkgRoot, 'modules', 'hosts', h), path.join(tmp, HOSTS[h].dir), vars, { force: true });
+      for (const f of hr.written) fresh.set(`${HOSTS[h].dir}/${f.rel}`, { sha: f.sha256, abs: path.join(tmp, HOSTS[h].dir, f.rel) });
+    }
+
+    const ledger = new Map((kit.managed || []).map((f) => [f.rel, f.sha256]));
+    const updated = [], skipped = [], restored = [], added = [], removed = [], newOwned = [];
+    let unchanged = 0;
+    const managedNew = [];
+
+    // 台账内文件：三方比对（台账 sha / 磁盘 sha / 新渲染 sha）
+    for (const [rel, ledgerSha] of ledger) {
+      const disk = path.join(target, rel);
+      const freshFile = fresh.get(rel);
+      if (!freshFile) {
+        removed.push(rel);
+        continue; // 包内已删：文件留在盘上，出台账（下次不再跟踪）
+      }
+      const diskSha = fs.existsSync(disk) ? sha256(fs.readFileSync(disk)) : null;
+      if (diskSha === null) {
+        fs.copyFileSync(freshFile.abs, disk);
+        restored.push(rel);
+        managedNew.push({ rel, sha256: freshFile.sha });
+        continue;
+      }
+      if (diskSha === ledgerSha) {
+        if (freshFile.sha === ledgerSha) { unchanged++; managedNew.push({ rel, sha256: ledgerSha }); }
+        else { fs.copyFileSync(freshFile.abs, disk); updated.push(rel); managedNew.push({ rel, sha256: freshFile.sha }); }
+        continue;
+      }
+      // 本地已改
+      if (freshFile.sha === diskSha) { unchanged++; managedNew.push({ rel, sha256: diskSha }); continue; } // 改动恰好等于新版
+      if (force) { fs.copyFileSync(freshFile.abs, disk); updated.push(`${rel}（--force 覆盖本地改动）`); managedNew.push({ rel, sha256: freshFile.sha }); }
+      else { skipped.push(rel); managedNew.push({ rel, sha256: diskSha }); } // 台账跟随磁盘，下次以当前盘面为基线
+    }
+
+    // 台账外的新文件：managed 类安装；owned 类只对「盘上缺失」的起步文档报告（已装的不动不报）
+    for (const [rel, freshFile] of fresh) {
+      if (ledger.has(rel)) continue;
+      if (isOwned(rel)) {
+        if (!fs.existsSync(path.join(target, rel))) newOwned.push(rel);
+        continue;
+      }
+      const disk = path.join(target, rel);
+      if (fs.existsSync(disk) && !force) { skipped.push(`${rel}（已存在未入台账）`); continue; }
+      fs.mkdirSync(path.dirname(disk), { recursive: true });
+      fs.copyFileSync(freshFile.abs, disk);
+      added.push(rel);
+      managedNew.push({ rel, sha256: freshFile.sha });
+    }
+
+    const list = (label, arr) => { if (arr.length) console.log(`  ${label}（${arr.length}）：${arr.join('、')}`); };
+    list('覆盖更新', updated);
+    list('恢复缺失', restored);
+    list('新增安装', added);
+    list('本地已改，跳过', skipped);
+    if (skipped.some((s) => !s.includes('未入台账'))) console.log('    ↑ --force 覆盖本地改动；git diff 自查差异');
+    list('包内已移除（文件保留在盘上，可手动删除）', removed);
+    list('新增 owned 起步文档（项目自持，未自动安装）', newOwned);
+    if (!updated.length && !restored.length && !added.length && !removed.length && !skipped.length && !newOwned.length) {
+      console.log(`  已是最新（${unchanged} 份 managed 无变化）`);
+    } else {
+      console.log(`  无变化 ${unchanged} 份`);
+    }
+
+    // 台账重写：版本对齐当前包；removed 出册；skipped 盘面基线化
+    kit.managed = managedNew.sort((a, b) => a.rel.localeCompare(b.rel));
+    kit.version = pkg.version;
+    fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
+
+    // 生成器目标走锚点重写（不参与 sha 比对）
+    const genIndex = runNode(target, '.agents/scripts/gen-workflow-index.mjs');
+    if (genIndex.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-workflow-index.mjs'))) {
+      console.log(genIndex.ok ? '  已重生成 workflow/INDEX.md（锚点内重写）' : `  ⚠️ gen-workflow-index 失败：${genIndex.out.split('\n')[0]}`);
+    }
+    const genBoard = runNode(target, '.agents/scripts/gen-wiki-board.mjs');
+    if (genBoard.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-wiki-board.mjs'))) {
+      console.log(genBoard.ok ? '  已重生成 wiki 速览与看板 DATA（锚点内重写）' : `  ⚠️ gen-wiki-board 失败：${genBoard.out.split('\n')[0]}`);
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+
+  console.log('▶ flow-kit doctor');
+  doctor(['--dir', target], pkgRoot);
+}

package/src/sync.test.mjs

@@ -0,0 +1,207 @@
+// sync.test.mjs — flow-kit sync 三态升级 + add-host / add-gate 行为验证。
+// 方法：迷你 fixture 包根（小模板树 + 假宿主 zcode + 假门禁 fakeg）+ 手工模拟 v1 安装态（kit.json 台账 + 盘面），
+// 子进程 driver 调真实 sync/add-host/add-gact（隔离 process.exit 与 doctor 尾部退出），断言盘面 + 台账 + stdout 标记。
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { sha256 } from './render.mjs';
+
+const SRC_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+
+let pass = 0, failCount = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { failCount++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+const W = (p, content) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, content); };
+const R = (p) => fs.readFileSync(p, 'utf8');
+
+// ---- fixture 包根（v2 形态：chg/host 变更、new 新增、gone 已删）----
+function mkFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-fixture-'));
+  W(path.join(root, 'package.json'), JSON.stringify({ name: 'fixture', version: '9.9.9', type: 'module' }));
+  W(path.join(root, 'templates/_agents/scripts/keep.txt'), 'keep v2\n');
+  W(path.join(root, 'templates/_agents/scripts/chg.txt'), 'chg v2 port {{BOARD_PORT}}\n');
+  W(path.join(root, 'templates/_agents/scripts/loc.txt'), 'loc v2\n');
+  W(path.join(root, 'templates/_agents/scripts/var.txt'), 'same {{BUILD_CMD}}\n');
+  W(path.join(root, 'templates/_agents/commands/new.txt'), 'new in v2\n');
+  W(path.join(root, 'templates/AGENTS.md'), 'owned skeleton v2\n');
+  W(path.join(root, 'modules/hosts/zcode/h.txt'), 'host v2 {{BOARD_PORT}}\n');
+  W(path.join(root, 'modules/gates/fakeg/gate.sh'), 'echo gate\n');
+  W(path.join(root, 'modules/gates/fakeg/README.md'), 'docs only\n');
+  W(path.join(root, 'modules/gates/fakeg/local-pre-commit.line'), 'sh .agents/hooks/gate.sh\n');
+  return root;
+}
+
+// ---- v1 安装态（managed 台账与盘面对应 v1 渲染产物）----
+function mkTarget(fixtureRoot) {
+  const t = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-target-'));
+  const files = {
+    '.agents/scripts/keep.txt': 'keep v2\n',
+    '.agents/scripts/chg.txt': 'chg v1 port 777\n',
+    '.agents/scripts/loc.txt': 'loc v1\n',
+    '.agents/scripts/var.txt': 'same <填写>\n',
+    '.agents/scripts/gone.txt': 'gone v1\n',
+    '.zcode/h.txt': 'host v1 777\n',
+    'AGENTS.md': 'owned skeleton v2\n',
+  };
+  for (const [rel, c] of Object.entries(files)) W(path.join(t, rel), c);
+  const managed = Object.entries(files)
+    .filter(([rel]) => rel !== 'AGENTS.md')
+    .map(([rel, c]) => ({ rel, sha256: sha256(Buffer.from(c, 'utf8')) }));
+  W(path.join(t, '.agents/kit.json'), `${JSON.stringify({
+    kit: 'agentic-flow-kit', version: '1.0.0', createdAt: '2026-09-23T00:00:00Z',
+    options: { hosts: ['zcode'], stack: 'none', boardPort: '777' },
+    managed, owned: [{ rel: 'AGENTS.md', sha256: sha256(Buffer.from('owned skeleton v2\n', 'utf8')) }],
+  }, null, 2)}\n`);
+  return t;
+}
+
+// ---- 子进程 driver：调真实实现，pkgRoot 指向 fixture ----
+function runCmd(cmd, fixtureRoot, target, extra = []) {
+  const driver = path.join(fixtureRoot, 'driver.mjs');
+  W(driver, `import { sync } from ${JSON.stringify(pathToFileURL(path.join(SRC_ROOT, 'sync.mjs')).href)};
+import { addHost } from ${JSON.stringify(pathToFileURL(path.join(SRC_ROOT, 'add-host.mjs')).href)};
+import { addGate } from ${JSON.stringify(pathToFileURL(path.join(SRC_ROOT, 'add-gate.mjs')).href)};
+const root = ${JSON.stringify(fixtureRoot)};
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === 'sync') sync(rest, root);
+else if (cmd === 'add-host') addHost(rest, root);
+else if (cmd === 'add-gate') addGate(rest, root);
+`);
+  return spawnSync(process.execPath, [driver, cmd, ...extra, '--dir', target], { encoding: 'utf8' });
+}
+
+// ============ 场景 1：sync 默认（无 --force）三态分派 ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  W(path.join(t, '.agents/scripts/loc.txt'), 'loc USER\n'); // 用户本地改动
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  // fixture 非完整安装：doctor 尾部按设计 FAIL 退出（status 1），此处只断言 sync 主流程走完且有分派报告
+  check('S1 sync 主流程走完（三态分派报告齐）', out.includes('覆盖更新') && out.includes('新增安装') && out.includes('doctor'), `status=${r.status} out=${out.slice(0, 200)}`);
+  check('S1 未改动+模板变更 → 覆盖（chg.txt → v2 且渲染端口）', R(path.join(t, '.agents/scripts/chg.txt')) === 'chg v2 port 777\n');
+  check('S1 宿主层同样覆盖（.zcode/h.txt → v2）', R(path.join(t, '.zcode/h.txt')) === 'host v2 777\n');
+  check('S1 本地改动 → 跳过（loc.txt 保持用户版）', R(path.join(t, '.agents/scripts/loc.txt')) === 'loc USER\n');
+  check('S1 跳过有报告标记', out.includes('本地已改，跳过') && out.includes('loc.txt'), out);
+  check('S1 无变化文件不动（keep/var）', R(path.join(t, '.agents/scripts/keep.txt')) === 'keep v2\n' && R(path.join(t, '.agents/scripts/var.txt')) === 'same <填写>\n');
+  check('S1 新增 managed 文件被安装', R(path.join(t, '.agents/commands/new.txt')) === 'new in v2\n');
+  check('S1 包内已删：文件留盘', fs.existsSync(path.join(t, '.agents/scripts/gone.txt')));
+  check('S1 包内已删有报告标记', out.includes('包内已移除'));
+  const kit = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  const rels = kit.managed.map((f) => f.rel);
+  check('S1 台账：版本对齐包版本', kit.version === '9.9.9');
+  check('S1 台账：gone 出册、new 入册', !rels.includes('.agents/scripts/gone.txt') && rels.includes('.agents/commands/new.txt'));
+  check('S1 台账：跳过文件基线化为用户版 sha', kit.managed.find((f) => f.rel === '.agents/scripts/loc.txt').sha256 === sha256(Buffer.from('loc USER\n')));
+  check('S1 台账：覆盖文件 sha 为新版', kit.managed.find((f) => f.rel === '.agents/scripts/chg.txt').sha256 === sha256(Buffer.from('chg v2 port 777\n')));
+  check('S1 owned 不触碰（AGENTS.md 原样）', R(path.join(t, 'AGENTS.md')) === 'owned skeleton v2\n');
+  check('S1 已装 owned 不误报新增', !out.includes('新增 owned 起步文档'), out);
+}
+
+// ============ 场景 2：sync --force 覆盖本地改动 ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  W(path.join(t, '.agents/scripts/loc.txt'), 'loc USER\n');
+  const r = runCmd('sync', fx, t, ['--force']);
+  check('S2 --force 覆盖本地改动（loc.txt → v2）', R(path.join(t, '.agents/scripts/loc.txt')) === 'loc v2\n', r.stdout + r.stderr);
+  check('S2 --force 有覆盖标记', (r.stdout + r.stderr).includes('--force 覆盖本地改动'));
+}
+
+// ============ 场景 3：managed 缺失 → 恢复 ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  fs.rmSync(path.join(t, '.agents/scripts/keep.txt'));
+  const r = runCmd('sync', fx, t);
+  check('S3 缺失 managed 被恢复', fs.existsSync(path.join(t, '.agents/scripts/keep.txt')) && R(path.join(t, '.agents/scripts/keep.txt')) === 'keep v2\n', r.stdout + r.stderr);
+  check('S3 恢复有报告标记', (r.stdout + r.stderr).includes('恢复缺失'));
+}
+
+// ============ 场景 4：本地改动恰好等于新版 → 视为无变化 ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  W(path.join(t, '.agents/scripts/chg.txt'), 'chg v2 port 777\n'); // == 新版渲染，但台账还是 v1 sha
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  check('S4 恰好等于新版不报跳过', !out.includes('本地已改，跳过'), out);
+  const kit = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  check('S4 台账 sha 更新为新版', kit.managed.find((f) => f.rel === '.agents/scripts/chg.txt').sha256 === sha256(Buffer.from('chg v2 port 777\n')));
+}
+
+// ============ 场景 5：无 kit.json → 明确报错引导 init ============
+{
+  const fx = mkFixture();
+  const t = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-empty-'));
+  const r = runCmd('sync', fx, t);
+  check('S5 无台账退出码 1', r.status === 1);
+  check('S5 报错引导 init', (r.stderr || '').includes('flow-kit init'), r.stderr);
+}
+
+// ============ 场景 6：全新 v2 包（台账空基线）→ 全量安装 + 未装 owned 起步文档报告 ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  fs.rmSync(path.join(t, 'AGENTS.md'), { force: true }); // 未装 owned 起步文档
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  check('S6 未装 owned 起步文档有报告且未自动安装', out.includes('新增 owned 起步文档') && !fs.existsSync(path.join(t, 'AGENTS.md')), out);
+}
+
+// ============ 场景 7：add-host 后补宿主 ============
+{
+  const fx = mkFixture();
+  const t = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-host-'));
+  W(path.join(t, '.agents/kit.json'), `${JSON.stringify({
+    kit: 'agentic-flow-kit', version: '1.0.0',
+    options: { hosts: [], stack: 'none', boardPort: '777' }, managed: [], owned: [],
+  }, null, 2)}\n`);
+  const r = runCmd('add-host', fx, t, ['zcode']);
+  const out = r.stdout + r.stderr;
+  check('S7 宿主文件就位（.zcode/h.txt 渲染）', R(path.join(t, '.zcode/h.txt')) === 'host v2 777\n', out);
+  const kit = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  check('S7 managed 台账补记（项目根相对路径）', kit.managed.some((f) => f.rel === '.zcode/h.txt'), JSON.stringify(kit.managed));
+  check('S7 options.hosts 补记', Array.isArray(kit.options.hosts) && kit.options.hosts.includes('zcode'));
+  check('S7 localOnly 宿主进 .gitignore', R(path.join(t, '.gitignore')).includes('.zcode/'));
+  const r2 = runCmd('add-host', fx, t, ['zcode']);
+  check('S7 重复装未 --force → 报错退出', r2.status === 1 && (r2.stderr || '').includes('--force'), r2.stderr);
+}
+
+// ============ 场景 8：add-gate 装门禁 + 幂等接线 ============
+{
+  const fx = mkFixture();
+  const t = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-gate-'));
+  W(path.join(t, '.agents/kit.json'), `${JSON.stringify({
+    kit: 'agentic-flow-kit', version: '1.0.0',
+    options: { hosts: [], stack: 'none', boardPort: '777' }, managed: [], owned: [],
+  }, null, 2)}\n`);
+  const r = runCmd('add-gate', fx, t, ['fakeg']);
+  const out = r.stdout + r.stderr;
+  check('S8 门禁文件落 .agents/hooks/', R(path.join(t, '.agents/hooks/gate.sh')) === 'echo gate\n', out);
+  check('S8 包内 README 不拷', !fs.existsSync(path.join(t, '.agents/hooks/README.md')));
+  check('S8 接线元数据不拷', !fs.existsSync(path.join(t, '.agents/hooks/local-pre-commit.line')));
+  check('S8 local-pre-commit 接线（缺失则建 set -e 头）', R(path.join(t, '.agents/hooks/local-pre-commit')) === '#!/bin/sh\nset -e\nsh .agents/hooks/gate.sh\n', out);
+  const kit = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  check('S8 owned 台账补记（归项目所有）', kit.owned.some((f) => f.rel === '.agents/hooks/gate.sh'));
+  runCmd('add-gate', fx, t, ['fakeg']); // 再跑一遍
+  check('S8 幂等：接线行不重复', R(path.join(t, '.agents/hooks/local-pre-commit')) === '#!/bin/sh\nset -e\nsh .agents/hooks/gate.sh\n');
+  const r3 = runCmd('add-gate', fx, t, ['nope']);
+  check('S8 未知门禁报错并列出可选', r3.status === 1 && (r3.stderr || '').includes('fakeg'), r3.stderr);
+}
+
+// ============ 场景 9：旧装态 local-pre-commit（尾部 exit 0）→ 归一化剥掉再接线 ============
+{
+  const fx = mkFixture();
+  const t = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-gate2-'));
+  W(path.join(t, '.agents/kit.json'), `${JSON.stringify({
+    kit: 'agentic-flow-kit', version: '1.0.0',
+    options: { hosts: [], stack: 'none', boardPort: '777' }, managed: [], owned: [],
+  }, null, 2)}\n`);
+  W(path.join(t, '.agents/hooks/local-pre-commit'), '#!/bin/sh\n# 旧装态注释\nexit 0\n');
+  const r = runCmd('add-gate', fx, t, ['fakeg']);
+  const out = r.stdout + r.stderr;
+  check('S9 旧装态归一化：剥掉尾部 exit 0', out.includes('归一化'), out);
+  check('S9 挂载行在 exit 0 原位之前追加', R(path.join(t, '.agents/hooks/local-pre-commit')) === '#!/bin/sh\n# 旧装态注释\nsh .agents/hooks/gate.sh\n', R(path.join(t, '.agents/hooks/local-pre-commit')));
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
+process.exit(failCount ? 1 : 0);

package/templates/.gitattributes

@@ -0,0 +1,6 @@
+# agentic-flow-kit：钩子与 shell 脚本必须 LF（CRLF 会破坏 Git Bash/MSYS 执行）；
+# 预算表按 LF 计量（rule-budget.sh 已显式去 \r，此条为双保险）。已有自有 .gitattributes 的项目合并这几条即可。
+*.sh text eol=lf
+.githooks/* text eol=lf
+.agents/hooks/local-pre-commit text eol=lf
+*.ps1 text eol=crlf

package/templates/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md — AI 工作流 + Wiki
+
+> 本文件由 agentic-flow-kit 生成：说明本仓库的 AI 工作流与 Wiki 用法。「项目适配区」由项目自行填写；工作流约定可增不可删。
+
+## AI工作流
+
+**闭环模型**：`workflow/` 是唯一真相源——intents（为什么做）→ specs（怎么设计）→ plans（怎么做）→ incidents（学到了什么）。单人 + AI 协作：AI 起草 / 实现 / 验证 / 自查，取舍与放行由用户拍板，确认在对话内一句话完成，追溯靠 git。文档协议（frontmatter 字段、状态枚举、命名规则）见 `workflow/README.md`。
+
+### 开工前必读
+
+1. **新需求 / 功能**：先立 `workflow/intents/` intent（复制 `_TEMPLATE.md`），对话内与用户确认后开工。
+2. **修复类任务**：先查 `workflow/incidents/` 同类历史；L1 以上立 incident（修复中即 intent 等价入口，L2/L3 与 spec/plan 同名配对）。
+3. **级别判断**（就高不就低）：实现级（页面 / 交互 / 样式）→ L1；改「规则 / 契约」→ L2；改「数据与运行时结构」（schema / 迁移 SQL / DI 链 / 认证与中间件管线）→ L3。细则见 `.agents/commands/new-task.md`。
+
+### 阶段路由
+
+总入口 `.agents/commands/new-task.md`：Plan `.agents/commands/plan.md` → Design `.agents/commands/design.md` → Build `.agents/commands/build.md` → Test `.agents/commands/test.md` → Deploy `.agents/commands/deploy.md` → Maintain `.agents/commands/maintain.md`；`.agents/commands/review.md` 为横切评审入口。
+
+### 子智能体
+
+公共角色契约在 `.agents/roles/`（`implementer` / `independent-reviewer` / `ui-verifier`），各宿主经薄适配层（`.opencode/agents/`、`.trae/agents/`、`.zcode/agents/` 等）注册，宿主不支持子智能体时按命令 frontmatter 的 `fallback` 执行。子智能体不跨用户确认门、不替用户批准、不自行提交。
+
+### 门禁与提交
+
+- `.githooks/`（经 `core.hooksPath` 挂载，本地 clone 后执行 `git config core.hooksPath .githooks`）：pre-commit（闭环配对 / wiki 台账 / 规则面预算 / 敏感信息扫描与条件构建）、pre-push（闭环断档扫描）、commit-msg、post-commit、pre-merge-commit。
+- **`git commit` / `git merge` / `git push` 三处一律禁 `--no-verify`**——被拦说明产出不合规，按提示修完原路重试。
+- 项目专属门禁挂 `.agents/hooks/local-pre-commit`。
+- 提交遵循 Conventional Commits 中文（feat / fix / docs / style / refactor / perf）；L1+ 入口文档 / spec / plan 随代码同一提交。
+
+### 检索、看板与量化
+
+- 跨语料检索：`node .agents/scripts/kb-search.mjs "<词>"`（workflow 节级定位 + wiki 全文）；活跃流程读 `workflow/INDEX.md`（状态变更后 `node .agents/scripts/gen-workflow-index.mjs` 重生成）。
+- workflow 看板：http://127.0.0.1:{{BOARD_PORT}}（任务入口幂等拉起 ensure-board；只读预警层，非门禁）。
+- 委派 / 自做结果留痕 `workflow/delegations.md`（聚合 `node .agents/scripts/agg-delegations.cjs`）；命令 / 技能卡壳记 `workflow/papercuts.md`，不当场顺手改。
+
+### 验证与关单
+
+验证入口 `.agents/commands/test.md`；**关单在 test**：逐条勾验入口文档「验收标准」并补证据后 intent → done，未勾验会被 check-loop 拦。上 prod 另走 `.agents/commands/deploy.md`（tag / 回滚 / 观察），不用 deploy 关单。
+
+## Wiki
+
+`wiki/` 是项目知识沉淀，按主题目录归位；原始 / 一次性文档归档 `wiki/drafts-archive/<日期-主题>/`（只读不增量）。
+
+- 人工只维护两样：**磁盘文件本身 + `wiki/INDEX.md` 速览表「用途」列**；计数 / 映射表 / 看板 DATA 均为生成区，勿手改——`node .agents/scripts/gen-wiki-board.mjs` 重生成，`node .agents/scripts/verify-wiki-consistency.mjs` 三方一致性验证（触及 `wiki/` 的提交会被 pre-commit 台账门禁校验）。
+- wiki 看板：`wiki/知识沉淀总览.html`。
+
+## 项目适配区（项目自填）
+
+- **构建 / 测试 / 类型检查命令**（静态门，各阶段命令引用此处口径）：构建 = {{BUILD_CMD}}；测试 = {{TEST_CMD}}；类型检查 = {{TYPECHECK_CMD}}
+- **运行时环境**（端口 / 进程 / 终端差异）：`.agents/notes/runtime-env.md`
+- **目录级规则**：如 `backend/AGENTS.md`、`frontend/AGENTS.md`（如有）——目录级约定不回填本文件
+- **权限与提交验证配置**：`.agents/settings.json`（allow / deny / ask）、`.agents/hooks/commit-check.config.json`（条件构建 / 质量检测命令与密钥白名单——质量检测只放秒级确定性检查（lint / 类型检查 / vet），测试不放提交门，关单在 test 阶段门）