agentic-flow-kit 0.3.1 → 0.5.0

package/templates/_agents/scripts/doctor.test.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// doctor 加 owned 漂移校验后的 fixture 驱动测试（2026-09-25 wf-runtime 复盘）
+// 测试 src/doctor.mjs 导出的 checkOwnedDrift(target)：覆盖 4 场景——
+//   ① owned 全对齐 → drift=0 gone=[] total>0 skipped=false
+//   ② 手改装副本（盘面 sha 变） → drift=1 gone=[] total=1
+//   ③ owned 文件缺失 → drift=0 gone=[rel] total=1
+//   ④ kit.json 无 owned 字段 → skipped=true total=0
+// 用法：node .agents/scripts/doctor.test.mjs（在仓库根执行，需 src/doctor.mjs 存在——dogfooding 模式）
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+// 上溯三级：templates/_agents/scripts/ → 仓库根
+const ROOT = path.resolve(SCRIPT_DIR, '..', '..', '..');
+const SRC = path.join(ROOT, 'src', 'doctor.mjs');
+if (!fs.existsSync(SRC)) {
+  console.error(`doctor.test.mjs：未找到 ${SRC}——仅在包源仓库（dogfooding）跑 npm test 时调用`);
+  process.exit(1);
+}
+const { checkOwnedDrift, checkAdapterDrift } = await import(pathToFileURL(SRC).href);
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
+};
+
+const sha256Of = (s) => createHash('sha256').update(s).digest('hex');
+
+const mkfix = ({ kitContent, files }) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-owned-test-'));
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify(kitContent, null, 2));
+  for (const [rel, content] of Object.entries(files || {})) {
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  return root;
+};
+
+const mkKit = (owned) => ({
+  kit: 'agentic-flow-kit',
+  version: '0.4.0',
+  options: { hosts: [], stack: 'none', boardPort: '8933' },
+  managed: [],
+  owned,
+});
+
+// ---- 场景 1：owned 全对齐 → drift=0 gone=[] total=1 skipped=false ----
+{
+  const AGENTS_BODY = '# test AGENTS.md\n';
+  const root = mkfix({
+    kitContent: mkKit([{ rel: 'AGENTS.md', sha256: sha256Of(AGENTS_BODY) }]),
+    files: { 'AGENTS.md': AGENTS_BODY },
+  });
+  const r = checkOwnedDrift(root);
+  check('场景 1：owned 全对齐 → drift=0 gone=[] total=1 skipped=false',
+    r.drift === 0 && r.gone.length === 0 && r.total === 1 && r.skipped === false,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 2：手改装副本（盘面 sha 变）→ drift=1 ----
+{
+  const OLD_BODY = '# old version\n';
+  const NEW_BODY = '# new version — hand-edited\n';
+  const root = mkfix({
+    kitContent: mkKit([{ rel: 'AGENTS.md', sha256: sha256Of(OLD_BODY) }]), // 台账是旧 sha
+    files: { 'AGENTS.md': NEW_BODY },                                       // 盘面是新 sha
+  });
+  const r = checkOwnedDrift(root);
+  check('场景 2：手改装副本 → drift=1 gone=[] total=1 skipped=false',
+    r.drift === 1 && r.gone.length === 0 && r.total === 1 && r.skipped === false,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 3：owned 文件缺失 → drift=0 gone=['AGENTS.md'] ----
+{
+  const root = mkfix({
+    kitContent: mkKit([{ rel: 'AGENTS.md', sha256: 'a'.repeat(64) }]),
+    files: {}, // 不写 AGENTS.md
+  });
+  const r = checkOwnedDrift(root);
+  check('场景 3：owned 文件缺失 → drift=0 gone=["AGENTS.md"] total=1 skipped=false',
+    r.drift === 0 && r.gone.length === 1 && r.gone[0] === 'AGENTS.md' && r.total === 1 && r.skipped === false,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 4：kit.json 无 owned 字段 → skipped=true total=0 ----
+{
+  const kit = { kit: 'agentic-flow-kit', version: '0.4.0', options: {}, managed: [] };
+  const root = mkfix({ kitContent: kit, files: { 'AGENTS.md': '# any\n' } });
+  const r = checkOwnedDrift(root);
+  check('场景 4：kit.json 无 owned 字段 → skipped=true total=0',
+    r.skipped === true && r.total === 0,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 5：kit.json 不存在 → skipped=true ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-owned-test-'));
+  const r = checkOwnedDrift(root);
+  check('场景 5：kit.json 不存在 → skipped=true total=0',
+    r.skipped === true && r.total === 0,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 6：kit.json 解析失败 → skipped=true 含 error ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-owned-test-'));
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), '{ broken json');
+  const r = checkOwnedDrift(root);
+  check('场景 6：kit.json 解析失败 → skipped=true 含 error',
+    r.skipped === true && typeof r.error === 'string' && r.error.length > 0,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 7：多个 owned 文件，部分漂移 → drift=1 gone=[other] ----
+{
+  const root = mkfix({
+    kitContent: mkKit([
+      { rel: 'AGENTS.md', sha256: sha256Of('# a\n') },
+      { rel: 'workflow/incidents/_TEMPLATE.md', sha256: sha256Of('# tpl\n') },
+      { rel: 'wiki/INDEX.md', sha256: sha256Of('# w\n') },
+    ]),
+    files: {
+      'AGENTS.md': '# a\n',                                   // 对齐
+      'wiki/INDEX.md': '# w\n',                                // 对齐
+      // workflow/incidents/_TEMPLATE.md 不写 → 缺失
+    },
+  });
+  const r = checkOwnedDrift(root);
+  check('场景 7：多个 owned 一个缺失 → drift=0 gone=1项 total=3 skipped=false',
+    r.drift === 0 && r.gone.length === 1 && r.gone[0] === 'workflow/incidents/_TEMPLATE.md' && r.total === 3 && r.skipped === false,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 8：owned 漂移 WARN 已严化为 FAIL（2026-09-25 doctor-owned-drift-strict 复盘）----
+// 源码层断言：src/doctor.mjs 第 6.6 节主流程输出必须用 add('FAIL', …) 而非 add('WARN', …)；
+// 这是规则严度参数化的最小防回归——不依赖运行时执行 doctor（避免造完整 fixture）。
+{
+  const doctorSrc = fs.readFileSync(SRC, 'utf8');
+  // 断言：owned 漂移分支必须用 'FAIL'
+  const failDrift = /ownedRes\.drift\)\s*add\('FAIL'/.test(doctorSrc);
+  check('场景 8a：src/doctor.mjs 第 6.6 节 owned 漂移分支已用 add(\'FAIL\', …)',
+    failDrift,
+    `src/doctor.mjs 第 6.6 节应为 add('FAIL', ...) 而非 add('WARN', ...)`);
+  // 断言：owned gone 分支必须用 'FAIL'
+  const failGone = /ownedRes\.gone\.length\)\s*add\('FAIL'/.test(doctorSrc);
+  check('场景 8b：src/doctor.mjs 第 6.6 节 owned gone 分支已用 add(\'FAIL\', …)',
+    failGone,
+    `src/doctor.mjs 第 6.6 节 gone 分支应为 add('FAIL', ...)`);
+  // 断言：doctor 主流程 results 含 FAIL 时 process.exit(1)（fail-loud）
+  const failLoud = /results\.some\(\(r\)\s*=>\s*r\.level\s*===\s*'FAIL'\)\s*\?\s*1\s*:\s*0/.test(doctorSrc);
+  check('场景 8c：doctor 主流程 results 含 FAIL 时 exit 1（fail-loud）',
+    failLoud,
+    `src/doctor.mjs 应保留 process.exit(1) fail-loud 行为`);
+}
+
+// ---- 场景 9-14：checkAdapterDrift（2026-09-25 cross-host-sync）—— 装户侧跨宿主薄适配正文段漂移 ----
+const mkfixAdapter = ({ authority, adapters, pkgMarker }) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-adapter-test-'));
+  // authorityRoot：.agents/{commands,roles}
+  if (authority) {
+    for (const [rel, content] of Object.entries(authority)) {
+      const abs = path.join(root, '.agents', rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content);
+    }
+  }
+  // adapters：<HOST_DIR>/<sub>/<file>
+  if (adapters) {
+    for (const [rel, content] of Object.entries(adapters)) {
+      const abs = path.join(root, rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content);
+    }
+  }
+  // pkgMarker：模拟包源（templates/_agents + modules/hosts）
+  if (pkgMarker) {
+    fs.mkdirSync(path.join(root, 'templates/_agents'), { recursive: true });
+    fs.mkdirSync(path.join(root, 'modules/hosts'), { recursive: true });
+  }
+  return root;
+};
+
+const ROLE_BODY = '# Implementer\n\n正文 role v1\n';
+const CMD_BODY = '# Build\n\n正文 build v1\n';
+
+// ---- 场景 9：装户侧薄适配全对齐 → drift=0 ----
+{
+  const root = mkfixAdapter({
+    authority: {
+      'commands/build.md': `---\ndesc: x\n---\n\n${CMD_BODY}`,
+      'roles/implementer.md': `---\ndesc: r\n---\n\n${ROLE_BODY}`,
+    },
+    adapters: {
+      '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
+      '.trae/commands/wf-build.md': `---\nname: wf-build\ndesc: trae\n---\n\n${CMD_BODY}`,
+      '.zcode/agents/implementer.md': `---\nname: impl\ndesc: zcode\n---\n\n${ROLE_BODY}`,
+      '.opencode/agents/implementer.md': `---\nname: impl\ndesc: oc\n---\n\n${ROLE_BODY}`,
+    },
+  });
+  const r = checkAdapterDrift(root);
+  check('场景 9：装户全对齐 → drift=0 total=4 skipped=false（1 cmd×2 适配 + 1 role×2 适配 .zcode+.opencode）',
+    r.drift === 0 && r.total === 4 && r.skipped === false,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 10：薄适配正文漂移 → drift > 0 ----
+{
+  const root = mkfixAdapter({
+    authority: {
+      'roles/implementer.md': `---\ndesc: r\n---\n\n${ROLE_BODY}`,
+    },
+    adapters: {
+      '.zcode/agents/implementer.md': `---\nname: impl\ndesc: zcode\n---\n\n# Implementer\n\n漂移正文 role v1\n`,
+    },
+  });
+  const r = checkAdapterDrift(root);
+  check('场景 10：薄适配正文漂移 → drift=1 total=1',
+    r.drift === 1 && r.total === 1 && r.skipped === false,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 11：包源环境 → skipped=true（不参与装户比对） ----
+{
+  const root = mkfixAdapter({
+    pkgMarker: true,
+    authority: { 'commands/build.md': `---\ndesc: x\n---\n\n${CMD_BODY}` },
+    adapters: { '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n漂移` },
+  });
+  const r = checkAdapterDrift(root);
+  check('场景 11：包源环境（templates/ + modules/ 同时存在）→ skipped=true',
+    r.skipped === true && typeof r.note === 'string' && r.note.includes('包源'),
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 12：.agents 目录不存在 → skipped=true ----
+{
+  const root = mkfixAdapter({});
+  const r = checkAdapterDrift(root);
+  check('场景 12：权威源目录不存在 → skipped=true 含 note',
+    r.skipped === true && typeof r.note === 'string' && r.note.includes('.agents'),
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 13：frontmatter 差异不计漂移（B-b 语义：仅正文段比对） ----
+{
+  const root = mkfixAdapter({
+    authority: { 'roles/implementer.md': `---\ndesc: r\n---\n\n${ROLE_BODY}` },
+    adapters: {
+      '.zcode/agents/implementer.md': `---\nname: impl\ndesc: 自定义 zcode 风格\n---\n\n${ROLE_BODY}`,
+    },
+  });
+  const r = checkAdapterDrift(root);
+  check('场景 13：frontmatter 差异不算正文漂移 → drift=0 total=1',
+    r.drift === 0 && r.total === 1 && r.skipped === false,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 14：薄适配缺失不在 drift 统计（apply 不自动创建） ----
+{
+  const root = mkfixAdapter({
+    authority: {
+      'commands/build.md': `---\ndesc: x\n---\n\n${CMD_BODY}`,
+      'roles/implementer.md': `---\ndesc: r\n---\n\n${ROLE_BODY}`,
+    },
+    adapters: {
+      '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
+    },
+  });
+  const r = checkAdapterDrift(root);
+  check('场景 14：薄适配缺失不在 drift 统计 → drift=0 total=1',
+    r.drift === 0 && r.total === 1 && r.skipped === false,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// ensure-board.mjs — workflow 看板按需手动拉起（默认不自动开启；只起不关：OS 重启即天然回收，无需 stop/status）
+// 跨平台单入口（零依赖，Windows/Linux/macOS 同一脚本，取代旧 ensure-board.ps1）：
+//   基端口（--port 显式 > kit.json boardPort > 8933）向上探测首个可用端口（窗口 10）——
+//   端口空闲 → 全新启动；探活 /api/board 比对 root：本项目看板 → 复用（代码文件晚于服务端 startedAt = 旧代码自动 kill 重启）；
+//   他人进程（其他项目看板 / 非看板服务）不动手不 kill，跳过试下一端口；全新启动成功后弹浏览器（重启/已运行不弹，SSE 自动重连）
+// 身份与陈旧判定全部来自 /api/board 自报（pid/startedAt）——不碰 OS 专属的端口属主 / 进程启动时间 API。
+// 用法：node .agents/scripts/ensure-board.mjs [--port 8933] [--no-open]
+import net from 'node:net';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(SCRIPT_DIR, '../..'); // 与 server 的 ROOT 同口径
+const SERVER = path.join(SCRIPT_DIR, 'workflow-board-server.mjs');
+const CODE_FILES = [path.join(ROOT, '.agents', 'board', 'index.html'), SERVER]; // 前端 + 服务端：任一更新都算「旧代码」
+const WINDOW = 10;
+
+// ---- 参数与基端口 ----
+const argv = process.argv;
+const flagIdx = argv.indexOf('--port');
+const eqArg = argv.find((a) => a.startsWith('--port='));
+const portArg = flagIdx > -1 ? argv[flagIdx + 1] : eqArg && eqArg.slice('--port='.length);
+const noOpen = argv.includes('--no-open');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+let BASE_PORT;
+if (portArg && Number(portArg)) {
+  BASE_PORT = Number(portArg);
+} else {
+  // 基端口取 kit 台账（init 询问值，与命令文档 8933 同源）；无台账或解析失败回落 8933
+  try { BASE_PORT = Number(JSON.parse(fs.readFileSync(path.join(ROOT, '.agents', 'kit.json'), 'utf8')).options.boardPort) || 8933; }
+  catch { BASE_PORT = 8933; }
+}
+
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+
+// ---- 探活：端口占用用 net.connect；看板身份/属主用 /api/board 自报（isBoard=含 cards 字段；ours=root 指向本项目）----
+// 不用全局 fetch：undici 连接池 keep-alive 句柄会拖住/污染退出（Windows 上强退触发 libuv 断言）
+function portBusy(port) {
+  return new Promise((resolve) => {
+    const s = net.connect({ host: '127.0.0.1', port });
+    s.setTimeout(800);
+    s.on('connect', () => { s.destroy(); resolve(true); });
+    s.on('timeout', () => { s.destroy(); resolve(true); }); // 超时从保守视作占用；localhost 上近乎不存在
+    s.on('error', () => resolve(false));
+  });
+}
+
+// /api/board 用 http.get 正规解包（server 响应为 chunked，手工拼包解析不了）；Connection: close + 默认 agent 不进连接池，无残留句柄
+function httpProbe(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/api/board', headers: { Connection: 'close' }, timeout: 2000 }, (res) => {
+      let buf = '';
+      res.on('data', (d) => { buf += d; });
+      res.on('end', () => resolve({ status: res.statusCode, json: () => { try { return JSON.parse(buf); } catch { return null; } } }));
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ status: 0 }); });
+    req.on('error', () => resolve({ status: 0 }));
+  });
+}
+
+async function probeBoard(port) {
+  const none = { isBoard: false };
+  const r = await httpProbe(port);
+  if (r.status !== 200) return none;
+  const j = r.json();
+  if (!j || typeof j !== 'object' || !('cards' in j)) return none;
+  return { isBoard: true, ours: !!(j.root && samePath(path.resolve(String(j.root)), ROOT)), pid: j.pid, startedAt: j.startedAt };
+}
+
+// 陈旧判定：代码文件最新 mtime 晚于服务端启动时刻（2s 容差）= 旧代码；无 startedAt（旧版服务端）返回 null 无法判定
+function staleCode(startedAt) {
+  if (!startedAt) return null;
+  const newest = Math.max(...CODE_FILES.filter((f) => fs.existsSync(f)).map((f) => fs.statSync(f).mtimeMs));
+  return newest > startedAt + 2000;
+}
+
+// ---- 动作：kill / 拉起（detached + windowsHide，父进程退出后存活）/ 等监听 / 弹浏览器 ----
+function startServer(port) {
+  const c = spawn(process.execPath, [SERVER, '--port', String(port)], { detached: true, stdio: 'ignore', windowsHide: true });
+  c.unref();
+}
+
+async function waitListen(port) {
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline) {
+    if (await portBusy(port)) return true;
+    await sleep(300);
+  }
+  return false;
+}
+
+// intentional-simple: 弹浏览器 best-effort 三平台分流（win: cmd start / mac: open / linux: xdg-open），失败不打扰——链接已在输出里
+function openBrowser(url) {
+  try {
+    if (process.platform === 'win32') spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    else spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+  } catch { }
+}
+
+// ---- 主流程（返回退出码，自然排水退出——不用 process.exit：强退在 Windows 上会触发 libuv 断言）----
+async function main() {
+  const skipped = [];
+  let action = null;
+  let port = 0;
+  let board = null;
+
+  for (let p = BASE_PORT; p < BASE_PORT + WINDOW; p++) {
+    if (!(await portBusy(p))) { port = p; action = 'fresh start'; break; }
+    const b = await probeBoard(p);
+    if (b.ours) {
+      port = p;
+      board = b;
+      const stale = staleCode(b.startedAt);
+      if (stale === true) {
+        try { process.kill(b.pid); } catch { } // 进程可能已自行退出，忽略
+        await sleep(500);
+        action = 'restarted (stale code detected)';
+      } else if (stale === null) {
+        action = 'legacy';
+      } else {
+        action = 'up-to-date';
+      }
+      break;
+    }
+    skipped.push(`端口 ${p}（pid ${b.pid ?? '未知'}）`);
+  }
+  const url = `http://127.0.0.1:${port}`;
+
+  if (!action) {
+    console.log(`board: 端口 ${BASE_PORT}..${BASE_PORT + WINDOW - 1} 均被他人进程占用（未动手不 kill）：${skipped.join('；')}；可 --port 指定其他基端口`);
+    return 1;
+  }
+  if (action === 'legacy') {
+    console.log(`board: ${url} 是本项目旧版看板（无 startedAt，无法判定代码新旧），未自动重启；如需更新请手动重启`);
+    return 0;
+  }
+  if (action === 'up-to-date') {
+    console.log(`board: already up-to-date at ${url} (pid ${board.pid ?? '未知'})`);
+    return 0;
+  }
+  if (skipped.length) console.log(`board: 基端口段他人进程已跳过：${skipped.join('；')}`);
+
+  startServer(port);
+  if (!(await waitListen(port))) {
+    console.log(`board: FAILED to start on ${port}`);
+    return 1;
+  }
+  console.log(`board: ${action} -> ${url}`);
+  if (!noOpen && action === 'fresh start') openBrowser(url);
+  return 0;
+}
+
+process.exitCode = await main();

package/templates/_agents/scripts/fill-intent.mjs

@@ -0,0 +1,59 @@
+// flow-kit fill-intent：起草 intent 草稿（背景与问题/目标/非目标/约束/影响面/触达红线/验收标准 共 7 节）
+// 读 workflow/intents/_TEMPLATE.md 的节标题 → 输出符合 frontmatter 受限子集（5 字段）的草稿到指定文件
+// 用法：node .agents/scripts/fill-intent.mjs --module pipeline --level L1 --topic "test" --output /tmp/x.md
+// 零依赖；CLI 解析用最简字符串匹配；不替代 AI 起草——本工具只输出模板与提示句
+import fs from 'node:fs';
+import path from 'node:path';
+import { ENUMS } from './workflow-enums.mjs';
+
+const TODAY = new Date().toISOString().slice(0, 10);
+const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
+
+function parseArgs(argv) {
+  const out = { topic: null, module: null, level: 'L1', output: null, notes: '' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => { const v = argv[++i]; if (v === undefined) return null; return v; };
+    if (a === '--topic') out.topic = next();
+    else if (a === '--module') out.module = next();
+    else if (a === '--level') out.level = next();
+    else if (a === '--output') out.output = next();
+    else if (a === '--notes') out.notes = next() || '';
+  }
+  return out;
+}
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+const SECTIONS = [
+  { title: '背景与问题', hint: '<为什么做；写明需求来源（工单 / 沟通记录 / 待办事项）>' },
+  { title: '目标', hint: '- <可验证的目标>' },
+  { title: '非目标（L1 微改动无实质内容可删本节，不硬填）', hint: '- <明确不做的，防止范围蔓延>' },
+  { title: '约束（L1 微改动无实质内容可删本节，不硬填）', hint: '- <复用什么、不许动什么>' },
+  { title: '影响面', hint: '- 模块：<词表之一，见 .agents/workflow-modules.txt>\n- 数据库：无 / <表名>（涉及 schema 变更 → L3；无 schema 的运行时 / 管线结构面亦为 L3，判据见 .agents/commands/new-task.md §级别判断）\n- 前端页面：<路由或组件，无则删本行>' },
+  { title: '触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 中说明）', hint: '- [ ] <按本项目 AGENTS.md 红线逐行补；无则删本行>\n- [ ] 规则 / 契约变更（编码权威 / 共享契约 / 接口签名 / 既有参数语义 / 全局口径）→ 级别至少 L2\n- [ ] schema / 迁移 SQL / DI 链 / 认证与中间件管线 → 级别 L3\n\n> 触及任一红线即为 L2 / L3，必须立 ../specs/YYYY-MM-DD-<主题>.md 写明如何满足，方可起草 plan。' },
+  { title: '验收标准（可测试）', hint: '- [ ] <逐条可测试；写不出可测试判据 = 还没想清楚>\n\n> **闭环对账**：关单在 test 阶段（不依赖 deploy）。intent 置 done 前逐条勾验，每条勾选项后补证据——`- [x] <判据>（证据：<commit SHA / 测试用例名 / 冒烟脚本输出>）`。\n> done 状态仍有未勾项会被 check-loop 拦截（2026-09-12 起新建 intent 为 hard-block，存量 intent 仅 warning 提示）；勾选但缺「证据：」为 warning。' },
+];
+
+export function renderIntent({ topic, module, level, notes, date = TODAY }) {
+  if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
+  const fm = '---\n状态: draft\n级别: ' + level + '\n日期: ' + date + '\n模块: ' + module + '\n备注: ' + (notes || '<可选：附注自由文本，check-loop 不解析>') + '\n---\n';
+  let body = '# INTENT — ' + topic + '\n\n<!-- 复制本模板为 YYYY-MM-DD-<主题>.md 后填写；plans/ 下同名文件与本文件配对 -->\n<!-- frontmatter 受限子集（2026-09-13）：每行 键: 值；状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->\n\n';
+  for (const { title, hint } of SECTIONS) {
+    body += '## ' + title + '\n\n' + hint + '\n\n';
+  }
+  body += '## 确认与复核\n\n- 确认日期：\n- 确认人：用户（对话内一句"可以"即确认）\n- 确认范围：\n- 复核：L1 不要求独立复核\n';
+  return { frontmatter: fm, body: fm + body, sections: SECTIONS.map((s) => s.title) };
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('fill-intent.mjs');
+if (isMain) {
+  const a = parseArgs(process.argv.slice(2));
+  if (!a.topic || !a.module || !a.output) fail('必填：--topic / --module / --output；选填：--level（默认 L1）/ --notes');
+  if (!LEVELS.includes(a.level)) fail('level 必须在 ' + LEVELS.join('|') + '：' + a.level);
+  const { body } = renderIntent(a);
+  fs.mkdirSync(path.dirname(a.output), { recursive: true });
+  fs.writeFileSync(a.output, body);
+  console.log('✅ 已生成 intent 草稿：' + a.output + '（状态 draft / 级别 ' + a.level + ' / 模块 ' + a.module + '）');
+}
+export default renderIntent;

package/templates/_agents/scripts/fill-intent.test.mjs

@@ -0,0 +1,73 @@
+// fill-intent.test.mjs — fill-intent 工具测试（2026-09-25 doc-fill-tools）
+// 方法：直接 import 模块调 renderIntent 拿字符串（不写盘），断言 frontmatter 字段 + 节数 + 枚举值合法性
+// 用法：node .agents/scripts/fill-intent.test.mjs
+import { renderIntent } from './fill-intent.mjs';
+
+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 : '')); }
+}
+
+// ---- 场景 1：L1 必填 frontmatter 字段都在 ----
+{
+  const { body } = renderIntent({ topic: 'test', module: 'pipeline', level: 'L1' });
+  const fm = body.match(/^---([\s\S]*?)---/);
+  check('S1 frontmatter 含状态 draft', /状态:\s*draft/.test(fm[1]));
+  check('S1 frontmatter 含级别 L1', /级别:\s*L1/.test(fm[1]));
+  check('S1 frontmatter 含日期 YYYY-MM-DD', /日期:\s*\d{4}-\d{2}-\d{2}/.test(fm[1]));
+  check('S1 frontmatter 含模块 pipeline', /模块:\s*pipeline/.test(fm[1]));
+  check('S1 frontmatter 含备注', /备注:/.test(fm[1]));
+}
+
+// ---- 场景 2：L2/L3 frontmatter 同样含完整字段 ----
+{
+  for (const level of ['L2', 'L3']) {
+    const { body } = renderIntent({ topic: 't', module: 'pipeline', level });
+    const fm = body.match(/^---([\s\S]*?)---/);
+    check('S2 级别 ' + level + ' frontmatter 完整', /状态:\s*draft/.test(fm[1]) && /级别:\s*/.test(fm[1]) && /日期:/.test(fm[1]));
+  }
+}
+
+// ---- 场景 3：非法 level 抛错（枚举严格）----
+{
+  let threw = false;
+  try { renderIntent({ topic: 't', module: 'pipeline', level: 'L9' }); } catch { threw = true; }
+  check('S3 非法 level 抛错', threw);
+}
+
+// ---- 场景 4：7 节正文齐 ----
+{
+  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1' });
+  const expectedSections = ['背景与问题', '目标', '非目标', '约束', '影响面', '触达红线', '验收标准', '确认与复核'];
+  for (const s of expectedSections) check('S4 含节 ## ' + s, body.includes('## ' + s));
+  check('S4 共 8 节标题', (body.match(/^##\s/gm) || []).length === 8);
+}
+
+// ---- 场景 5：备注字段透传 ----
+{
+  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1', notes: '自定义备注' });
+  check('S5 自定义备注透传', body.includes('备注: 自定义备注'));
+  const { body: body2 } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1' });
+  check('S5 默认备注占位', body2.includes('备注: <可选：附注自由文本，check-loop 不解析>'));
+}
+
+// ---- 场景 6：日期默认今日 ----
+{
+  const today = new Date().toISOString().slice(0, 10);
+  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1' });
+  check('S6 日期默认今日 ' + today, body.includes('日期: ' + today));
+  const { body: body2 } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1', date: '2026-01-15' });
+  check('S6 自定义日期透传', body2.includes('日期: 2026-01-15'));
+}
+
+// ---- 场景 7：导出函数可单元测试 ----
+{
+  check('S7 renderIntent 是函数', typeof renderIntent === 'function');
+  // 边界：缺 topic 应返回字符串（渲染时缺 topic → topic 是 undefined 字符串，不抛错——按 design 透传）
+  const r = renderIntent({ module: 'pipeline', level: 'L1' });
+  check('S7 缺 topic 仍可渲染（透传设计）', typeof r.body === 'string' && r.body.includes('INTENT — undefined'));
+}
+
+console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
+process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/fill-plan.mjs

@@ -0,0 +1,60 @@
+// flow-kit fill-plan：起草 plan 草稿（L1 极简 2 节 / L2-L3 完整 4 节）
+// 用法：node .agents/scripts/fill-plan.mjs --level L1 --topic "test" --output /tmp/x.md
+// L1：改动面（必填）+ 验证方式（必填）
+// L2/L3：改动面 + 任务拆解 + 执行顺序 + 验证方式
+import fs from 'node:fs';
+import path from 'node:path';
+import { ENUMS } from './workflow-enums.mjs';
+
+const TODAY = new Date().toISOString().slice(0, 10);
+const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
+
+function parseArgs(argv) {
+  const out = { topic: null, level: 'L1', output: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => { const v = argv[++i]; if (v === undefined) return null; return v; };
+    if (a === '--topic') out.topic = next();
+    else if (a === '--level') out.level = next();
+    else if (a === '--output') out.output = next();
+  }
+  return out;
+}
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+const L1_SECTIONS = [
+  { title: '改动面（L1 极简形态主节；L2/L3 可作任务拆解的汇总或删本节）', hint: '- <文件/组件>：<做什么；判据细节直接写进条目，如「L771 message.success 改『更新成功』>' },
+  { title: '验证方式', hint: '- 静态门：项目构建命令（+ 项目测试命令，测试项目就绪后）\n- 前端：cd frontend && npm run build（vue-tsc）\n- UI：.agents/commands/test.md（涉及页面改动必走，headless Chrome 实测）\n- L2 追加：<契约 / 规则面比对：编码结果抽样 / 接口契约断言 / 口径对账>\n- L3 追加：<含 schema 变更：备份 + 回滚 SQL 就绪后执行；仅运行时 / 管线：回退上一 release tag + 配置开关预案>' },
+];
+
+const FULL_SECTIONS = [
+  L1_SECTIONS[0],
+  { title: '任务拆解（L2/L3 必填；L1 仅多文件多步骤时用，单任务微改动删本节）', hint: '1. <任务>\n   - 判据：<怎样算完成；尽量对应一个测试或可复现操作>\n   - 风险：低 / 中 / 高（<原因>）\n2. <任务>\n   - 判据：…\n   - 风险：…' },
+  { title: '执行顺序（L2/L3 必填；L1 单文件微改动删本节）', hint: '<1 → 2 → 3；标注依赖关系>' },
+  L1_SECTIONS[1],
+];
+
+export function renderPlan({ topic, level = 'L1', date = TODAY }) {
+  if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
+  const sections = level === 'L1' ? L1_SECTIONS : FULL_SECTIONS;
+  const fm = '---\n状态: draft\n级别: ' + level + '\n模块: pipeline\n---\n';
+  let body = '# PLAN — ' + topic + '\n\n<!-- 与 intents/ 或 incidents/ 下同名入口文档配对；L2/L3 必须先有 ../specs/ 同名 spec 确认通过；AI 起草、用户对话内确认后开工 -->\n<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled；级别∈L0/L1/L2/L3；正文不再写状态/级别行 -->\n<!-- L1 极简形态（2026-09-13 瘦身，L1 默认）：单/少文件微改动只填「改动面」+「验证方式」两节——改动面逐条列改哪个文件做什么（判据细节直接写进条目），验证一行静态门 + 按需 UI 实测；任务拆解/执行顺序仅 L1 多文件多步骤时保留 -->\n\n对应入口：../intents/YYYY-MM-DD-<主题>.md 或 ../incidents/YYYY-MM-DD-<主题>.md（保留实际一项）\n对应 spec：../specs/YYYY-MM-DD-<主题>.md（L1 可省略）\n\n';
+  for (const { title, hint } of sections) {
+    body += '## ' + title + '\n\n' + hint + '\n\n';
+  }
+  body += '## 确认与复核\n\n> 确认 = 用户在对话内一句话通过；确认后本 plan 状态 draft → approved 并回填本节（确认环节的机器可见态），done 只在关单出现——禁从 draft 直跳 done（2026-09-22 papercut）。\n- 确认结果：approved（YYYY-MM-DD 用户对话内确认）；done（YYYY-MM-DD 关单，随入口文档置终态）\n- 确认门记录：plan 草稿全文过目 + 改动清单确认（build.md 两道门，逐次，不合并）\n- 复核：L1 不要求独立复核\n';
+  return { frontmatter: fm, body: fm + body, sections: sections.map((s) => s.title) };
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('fill-plan.mjs');
+if (isMain) {
+  const a = parseArgs(process.argv.slice(2));
+  if (!a.topic || !a.output) fail('必填：--topic / --output；选填：--level（默认 L1）');
+  if (!LEVELS.includes(a.level)) fail('level 必须在 ' + LEVELS.join('|') + '：' + a.level);
+  const { body } = renderPlan(a);
+  fs.mkdirSync(path.dirname(a.output), { recursive: true });
+  fs.writeFileSync(a.output, body);
+  console.log('✅ 已生成 plan 草稿：' + a.output + '（状态 draft / 级别 ' + a.level + ' / ' + (a.level === 'L1' ? '极简 2 节' : '完整 4 节') + '）');
+}
+export default renderPlan;