agentic-flow-kit 0.2.0

package/src/doctor.mjs

@@ -0,0 +1,150 @@
+// flow-kit doctor：安装体检——布局 / git 钩子 / managed 台账 / 占位符残留 / 索引漂移 / check-loop
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync, spawnSync } from 'node:child_process';
+import net from 'node:net';
+import { createHash } from 'node:crypto';
+
+function sh(cmd, cwd) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }) };
+  } catch (e) {
+    return { ok: false, out: String((e.stdout || '') + (e.stderr || '')) };
+  }
+}
+
+function portInUse(port) {
+  return new Promise((resolve) => {
+    const s = net.connect({ port: Number(port), host: '127.0.0.1', timeout: 400 });
+    s.on('connect', () => { s.destroy(); resolve(true); });
+    s.on('error', () => resolve(false));
+    s.on('timeout', () => { s.destroy(); resolve(false); });
+  });
+}
+
+export function doctor(args, pkgRoot) {
+  let target = process.cwd();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--dir') target = path.resolve(args[++i]);
+  }
+  const results = []; // {level:'PASS'|'WARN'|'FAIL', msg}
+  const add = (level, msg) => results.push({ level, msg });
+
+  // 1. Node 版本
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= 18) add('PASS', `Node ${process.versions.node}（≥18）`);
+  else add('FAIL', `Node ${process.versions.node} 过低（引擎脚本需 ≥18）`);
+
+  // 2. 目录布局
+  const required = [
+    'AGENTS.md',
+    '.agents/commands/new-task.md',
+    '.agents/roles/implementer.md',
+    '.agents/roles/independent-reviewer.md',
+    '.agents/roles/ui-verifier.md',
+    '.agents/scripts/check-loop.sh',
+    '.agents/scripts/kb-search.mjs',
+    '.agents/scripts/gen-workflow-index.mjs',
+    '.agents/scripts/gen-wiki-board.mjs',
+    '.agents/scripts/workflow-board-server.mjs',
+    '.agents/board/index.html',
+    '.agents/hooks/commit-check.cjs',
+    '.agents/workflow-modules.txt',
+    '.agents/rule-budgets.txt',
+    '.agents/settings.json',
+    '.githooks/pre-commit',
+    '.githooks/pre-push',
+    '.githooks/commit-msg',
+    '.githooks/post-commit',
+    '.githooks/pre-merge-commit',
+    'workflow/README.md',
+    'workflow/intents/_TEMPLATE.md',
+    'workflow/specs/_TEMPLATE.md',
+    'workflow/plans/_TEMPLATE.md',
+    'workflow/incidents/_TEMPLATE.md',
+    'wiki/INDEX.md',
+  ];
+  const missing = required.filter((p) => !fs.existsSync(path.join(target, p)));
+  if (missing.length === 0) add('PASS', `目录布局完整（${required.length} 个关键路径）`);
+  else add('FAIL', `布局缺失：${missing.join('、')}`);
+
+  // 3. git 仓库与钩子
+  const isRepo = sh('git rev-parse --git-dir', target).ok;
+  if (isRepo) {
+    const hp = sh('git config core.hooksPath', target);
+    if (hp.ok && hp.out.trim() === '.githooks') add('PASS', 'core.hooksPath=.githooks（钩子已挂载）');
+    else add('FAIL', `core.hooksPath 当前为「${(hp.ok ? hp.out : '').trim() || '未设置'}」——执行 git config core.hooksPath .githooks`);
+  } else {
+    add('WARN', '不在 git 仓库内——钩子未挂载（git init 后执行 git config core.hooksPath .githooks）');
+  }
+
+  // 4. kit.json managed 台账（sha 校验：本地改动 → WARN，缺失 → FAIL）
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (!fs.existsSync(kitPath)) {
+    add('WARN', '无 .agents/kit.json（非 flow-kit 安装或旧版手动安装）');
+  } else {
+    try {
+      const kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+      let ok = 0;
+      let modified = 0;
+      const gone = [];
+      for (const f of kit.managed || []) {
+        const p = path.join(target, f.rel);
+        if (!fs.existsSync(p)) { gone.push(f.rel); continue; }
+        const h = createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+        if (h === f.sha256) ok++; else modified++;
+      }
+      add('PASS', `kit.json v${kit.version}：managed ${ok + modified} 份校验通过`);
+      if (modified) add('WARN', `managed 本地改动 ${modified} 份（升级时 flow-kit sync 会要求合并）`);
+      if (gone.length) add('FAIL', `managed 文件缺失：${gone.join('、')}`);
+    } catch (e) {
+      add('FAIL', `kit.json 解析失败：${e.message}`);
+    }
+  }
+
+  // 5. 占位符残留
+  const phFiles = ['AGENTS.md', 'workflow/README.md', '.agents/notes/runtime-env.md']
+    .concat(fs.existsSync(path.join(target, '.agents/commands')) ? fs.readdirSync(path.join(target, '.agents/commands')).filter((f) => f.endsWith('.md')).map((f) => `.agents/commands/${f}`) : []);
+  const phHits = [];
+  for (const rel of phFiles) {
+    const p = path.join(target, rel);
+    if (!fs.existsSync(p)) continue;
+    const txt = fs.readFileSync(p, 'utf8');
+    for (const m of txt.matchAll(/\{\{([A-Z][A-Z0-9_]*)\}\}/g)) phHits.push(`${rel}: {{${m[1]}}}`);
+  }
+  if (phHits.length === 0) add('PASS', '无占位符残留');
+  else add('WARN', `占位符残留 ${phHits.length} 处（init 变量缺失或需手改）：${phHits.slice(0, 5).join('；')}${phHits.length > 5 ? ' …' : ''}`);
+
+  // 6. workflow 索引漂移
+  const idx = spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs', '--check'], { cwd: target, encoding: 'utf8' });
+  if (idx.status === 0) add('PASS', 'workflow/INDEX.md 无漂移');
+  else add('WARN', `workflow/INDEX.md 漂移——跑 node .agents/scripts/gen-workflow-index.mjs 重生成`);
+
+  // 7. check-loop
+  const cl = spawnSync('sh', ['.agents/scripts/check-loop.sh'], { cwd: target, encoding: 'utf8' });
+  if (cl.status === 0) {
+    const warnTxt = String(cl.stderr || '').trim();
+    add('PASS', `check-loop 干净${warnTxt ? `（${warnTxt.split('\n').filter((l) => l.includes('WARN')).length} 条 advisory 警告）` : ''}`);
+  } else {
+    add('FAIL', `check-loop 有 hard-block：\n${String(cl.stderr || '').split('\n').slice(0, 8).join('\n')}`);
+  }
+
+  // 8. 看板端口（信息级）
+  const kit = fs.existsSync(kitPath) ? JSON.parse(fs.readFileSync(kitPath, 'utf8')) : null;
+  const port = kit?.options?.boardPort || '8933';
+  portInUse(port).then((inUse) => {
+    print(results);
+    console.log(inUse
+      ? `ℹ️  看板端口 ${port} 已有监听（幂等拉起会探活复用；他人进程不 kill，见 workflow/README.md）`
+      : `ℹ️  看板端口 ${port} 空闲（首次访问任务入口时由 ensure-board 拉起，或手动 node .agents/scripts/workflow-board-server.mjs）`);
+    process.exit(results.some((r) => r.level === 'FAIL') ? 1 : 0);
+  });
+}
+
+function print(results) {
+  const icon = { PASS: '✅', WARN: '⚠️ ', FAIL: '❌' };
+  for (const r of results) console.log(`${icon[r.level]} ${r.msg}`);
+  const fails = results.filter((r) => r.level === 'FAIL').length;
+  const warns = results.filter((r) => r.level === 'WARN').length;
+  console.log(`\ndoctor：${results.length - fails - warns} PASS ｜ ${warns} WARN ｜ ${fails} FAIL`);
+}

package/src/init.mjs

@@ -0,0 +1,190 @@
+// flow-kit init：无参数 → 交互确认环节；带参数 → 直接执行。
+// 渲染模板树 + 宿主适配层 → 生成 owned 基线配置 → 挂 git 钩子 → 写 kit.json → 跑生成器与 doctor
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { execSync, spawnSync } from 'node:child_process';
+import { renderTree, sha256 } from './render.mjs';
+import { HOSTS, STACKS, settingsJson, commitCheckConfig, 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 || ''}` };
+}
+
+// makePrompt：行队列式问答（比逐次 rl.question 稳——管道/EOF 提前关闭时不会抛错，安全回退默认值或取消）
+// ask(question, def)：def 为默认值（空输入 / EOF 回退）；无 def 时空输入返回 ''（用于必须显式确认的问句）
+function makePrompt() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+  const lines = [];
+  const waiters = [];
+  let ended = false;
+  rl.on('line', (l) => { const w = waiters.shift(); if (w) w(l.trim()); else lines.push(l.trim()); });
+  rl.on('close', () => { ended = true; while (waiters.length) waiters.shift()(''); });
+  return {
+    ask(question, def) {
+      return new Promise((resolve) => {
+        process.stdout.write(def ? `${question}（直接回车=${def}）：` : `${question}：`);
+        const fin = (a) => resolve(a || def || '');
+        const l = lines.shift();
+        if (l !== undefined) fin(l);
+        else if (ended) fin('');
+        else waiters.push(fin);
+      });
+    },
+    close() { rl.close(); },
+  };
+}
+
+// 交互确认环节：宿主多选 → 看板端口 → 显式确认（EOF / 非 y 一律取消，不装）
+async function interactive() {
+  const p = makePrompt();
+  console.log('▶ flow-kit init（交互模式——裸跑无参数时进入；带参数则直接执行，见 flow-kit --help）');
+  console.log('  将在当前目录安装：.agents/ ｜ .githooks/ ｜ workflow/ ｜ wiki/ ｜ AGENTS.md（已存在的文件保守跳过）');
+  try {
+    const hosts = await p.ask('1/3 选择 agent 宿主（逗号分隔：zcode / opencode / trae / omp）', 'zcode');
+    const stack = await p.ask('2/3 技术栈——决定编译检查与自检验命令初值（dotnet / node / python / go / none）', 'none');
+    const boardPort = await p.ask('3/3 workflow 看板端口', '8933');
+    const yes = await p.ask('确认安装到当前目录？(y/n)');
+    if (!/^(y|yes)$/i.test(yes)) {
+      console.log('已取消（未做任何改动）');
+      process.exit(0);
+    }
+    return { hosts, stack, boardPort, dir: process.cwd(), force: false };
+  } finally {
+    p.close();
+  }
+}
+
+export async function init(args, pkgRoot) {
+  let opt;
+  if (args.length === 0) {
+    opt = await interactive();
+  } else {
+    opt = { hosts: 'zcode', stack: 'none', boardPort: '8933', dir: process.cwd(), force: false };
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      const next = () => {
+        const v = args[++i];
+        if (v === undefined) fail(`选项 ${a} 缺少值`);
+        return v;
+      };
+      if (a === '--hosts') opt.hosts = next();
+      else if (a === '--stack') opt.stack = next();
+      else if (a === '--board-port') opt.boardPort = next();
+      else if (a === '--dir') opt.dir = next();
+      else if (a === '--force') opt.force = true;
+      else fail(`未知选项：${a}（flow-kit init --help 看全部）`);
+    }
+  }
+
+  if (!STACKS[opt.stack]) fail(`未知技术栈：${opt.stack}（可选 dotnet | node | python | go | none——对应编译检查与自检验命令初值）`);
+  const hosts = opt.hosts.split(',').map((s) => s.trim()).filter(Boolean);
+  for (const h of hosts) {
+    if (!HOSTS[h]) fail(`未知宿主：${h}（可选 ${Object.keys(HOSTS).join(' | ')}）`);
+  }
+
+  const target = path.resolve(opt.dir);
+  if (!fs.existsSync(target)) fail(`目标目录不存在：${target}`);
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (fs.existsSync(kitPath) && !opt.force) {
+    fail(`${target} 已安装 agentic-flow-kit（.agents/kit.json 存在）。重装/修复用 --force；升级将由 flow-kit sync 提供。`);
+  }
+
+  const vars = { BOARD_PORT: String(opt.boardPort), ...pickStackVars(opt.stack) };
+
+  console.log(`▶ flow-kit init → ${target}`);
+  console.log(`  宿主：${hosts.join(', ')} ｜ 技术栈：${opt.stack} ｜ 看板端口：${opt.boardPort}`);
+
+  // 1) 模板树（保守：已存在文件跳过，--force 覆盖）
+  const t = renderTree(path.join(pkgRoot, 'templates'), target, vars, { force: opt.force });
+  // 2) 宿主适配层
+  const hostResults = {};
+  for (const h of hosts) {
+    hostResults[h] = renderTree(path.join(pkgRoot, 'modules', 'hosts', h), path.join(target, HOSTS[h].dir), vars, { force: opt.force });
+  }
+
+  // 3) 生成的 owned 基线配置（引擎按固定路径读取；存在则跳过，永不覆盖；技术栈命令由项目在文件内自填）
+  const generated = {
+    '.agents/settings.json': settingsJson(opt.stack),
+    '.agents/hooks/commit-check.config.json': commitCheckConfig(opt.stack),
+  };
+  const ownedGenerated = [];
+  for (const [rel, content] of Object.entries(generated)) {
+    const p = path.join(target, rel);
+    if (fs.existsSync(p)) { console.log(`  跳过（已存在）：${rel}`); continue; }
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+    ownedGenerated.push({ rel, sha256: sha256(Buffer.from(content, 'utf8')) });
+  }
+
+  // 4) .gitignore 追加（缺哪条补哪条）
+  const giPath = path.join(target, '.gitignore');
+  const giNeed = ['.agents/cache/', ...(hosts.filter((h) => HOSTS[h].localOnly).map((h) => `${HOSTS[h].dir}/`))];
+  let giText = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
+  const giAdd = giNeed.filter((l) => !giText.split(/\r?\n/).some((x) => x.trim() === l));
+  if (giAdd.length) {
+    giText = (giText.endsWith('\n') || giText === '' ? giText : giText + '\n') + '# agentic-flow-kit\n' + giAdd.join('\n') + '\n';
+    fs.writeFileSync(giPath, giText);
+    console.log(`  .gitignore 追加：${giAdd.join('、')}`);
+  }
+
+  // 5) git 钩子挂载
+  try {
+    execSync('git rev-parse --git-dir', { cwd: target, stdio: 'pipe' });
+    execSync('git config core.hooksPath .githooks', { cwd: target, stdio: 'pipe' });
+    console.log('  已挂载 git 钩子：core.hooksPath=.githooks（pre-commit / pre-push / commit-msg / post-commit / pre-merge-commit）');
+    try {
+      execSync('git config merge.ours.driver true', { cwd: target, stdio: 'pipe' });
+      console.log('  已启用 merge.ours driver（.gitattributes 的 merge=ours 生效）');
+    } catch { /* 可选配置，失败不阻断 */ }
+  } catch {
+    console.log('  ⚠️ 目标不是 git 仓库——钩子未挂载；git init 后手动执行：git config core.hooksPath .githooks');
+  }
+
+  // 6) kit.json：managed（模板/适配层，升级可覆盖）与 owned（基线配置+起步文档，升级不动）台账
+  const managed = [
+    ...t.written.filter((f) => !isOwned(f.rel)),
+    // 宿主文件渲染时相对宿主根，入台账须还原为项目根相对路径
+    ...hosts.flatMap((h) => hostResults[h].written.map((f) => ({ ...f, rel: `${HOSTS[h].dir}/${f.rel}` }))),
+  ];
+  const owned = [...t.written.filter((f) => isOwned(f.rel)), ...ownedGenerated];
+  const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+  fs.mkdirSync(path.dirname(kitPath), { recursive: true });
+  fs.writeFileSync(kitPath, `${JSON.stringify({
+    kit: 'agentic-flow-kit',
+    version: pkg.version,
+    createdAt: new Date().toISOString(),
+    options: { hosts, stack: opt.stack, boardPort: String(opt.boardPort) },
+    managed,
+    owned,
+  }, null, 2)}\n`);
+  console.log(`  kit.json 台账：managed ${managed.length} 份 ｜ owned ${owned.length} 份（版本 ${pkg.version}）`);
+
+  // 7) 生成器首跑（幂等）：workflow/INDEX.md 活跃层索引 + wiki 速览计数与看板 DATA
+  const genIndex = runNode(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');
+  console.log(genBoard.ok ? '  已生成 wiki 速览计数与知识沉淀总览 DATA' : `  ⚠️ gen-wiki-board 失败：${genBoard.out.split('\n')[0]}`);
+
+  // 8) 自检
+  console.log('▶ flow-kit doctor');
+  doctor(['--dir', target], pkgRoot);
+
+  if (t.skipped.length) console.log(`  跳过（已存在，未覆盖）：${t.skipped.join('、')}`);
+  for (const h of hosts) if (hostResults[h].skipped.length) console.log(`  跳过（${h} 已存在）：${hostResults[h].skipped.join('、')}`);
+  console.log('\n✅ 安装完成。下一步：');
+  if (opt.stack === 'none') {
+    console.log('  1. 技术栈未配置（none）：填 AGENTS.md「项目适配区」构建/测试命令 + .agents/hooks/commit-check.config.json 的 builds（编译检查）+ settings.json allow（自检验命令权限）');
+  } else {
+    console.log('  1. 按需微调 AGENTS.md「项目适配区」与 .agents/hooks/commit-check.config.json（已按技术栈预填初值）');
+  }
+  console.log('  2. 按项目模块改 .agents/workflow-modules.txt 词表与 .agents/rule-budgets.txt 预算');
+  console.log('  3. 第一个任务从 .agents/commands/new-task.md 流程发起（立 intent → 与用户确认）');
+}

package/src/profiles.mjs

@@ -0,0 +1,101 @@
+// 宿主注册表 + 技术栈 profile + init 生成的 owned 基线配置
+// stack 决定门禁配置三处：commit-check 的条件构建（builds）与质量检测（checks，秒级确定性
+// 检查——lint/类型/vet；测试不放提交门，关单在 test.md 阶段门）、settings.json 的自检验
+// 命令权限（allow）、AGENTS.md「项目适配区」命令预填；不改工作流流程本身。
+// checks.when = 配置文件存在才启用（如 tsconfig.json / go.mod / ruff.toml）——没有对应
+// 配置的项目自动跳过，不 fail-closed 误拦。none = 不配置（项目日后自填）。
+export const HOSTS = {
+  zcode: { dir: '.zcode', localOnly: true },
+  opencode: { dir: '.opencode', localOnly: false },
+  trae: { dir: '.trae', localOnly: false },
+  omp: { dir: '.omp', localOnly: true },
+};
+
+const ESLINT_CONFIGS = [
+  'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs',
+  '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml', '.eslintrc',
+];
+
+export const STACKS = {
+  dotnet: {
+    build: 'dotnet build',
+    test: 'dotnet test',
+    typecheck: 'dotnet build（编译即类型检查）',
+    builds: [{ name: 'backend', command: 'dotnet build', ext: ['.cs', '.sln', '.csproj'] }],
+    checks: [{ name: 'format', command: 'dotnet format --verify-no-changes', ext: ['.cs'], when: ['*.sln'] }],
+    allow: ['dotnet build', 'dotnet run', 'dotnet test', 'dotnet format'],
+  },
+  node: {
+    build: 'npm run build',
+    test: 'npm test',
+    typecheck: 'npx tsc --noEmit（或 npm run typecheck）',
+    builds: [{ name: 'build', command: 'npm run build', ext: ['.ts', '.tsx', '.vue', '.js', '.jsx', '.mjs', '.cjs'] }],
+    checks: [
+      { name: 'typecheck', command: 'npx tsc --noEmit', ext: ['.ts', '.tsx'], when: ['tsconfig.json'] },
+      { name: 'lint', command: 'npx eslint .', ext: ['.ts', '.tsx', '.js', '.jsx', '.vue'], when: ESLINT_CONFIGS },
+    ],
+    allow: ['npm test'],
+  },
+  python: {
+    build: '（Python 无统一构建命令，按项目填）',
+    test: 'python -m pytest',
+    typecheck: '（可选：mypy）',
+    builds: [{ name: 'tests', command: 'python -m pytest', ext: ['.py'] }],
+    checks: [{ name: 'lint', command: 'ruff check .', ext: ['.py'], when: ['ruff.toml', '.ruff.toml'] }],
+    allow: ['python -m pytest', 'pytest', 'ruff check'],
+  },
+  go: {
+    build: 'go build ./...',
+    test: 'go test ./...',
+    typecheck: 'go vet',
+    builds: [{ name: 'build', command: 'go build ./...', ext: ['.go'] }],
+    checks: [{ name: 'vet', command: 'go vet ./...', ext: ['.go'], when: ['go.mod'] }],
+    allow: ['go build', 'go test', 'go vet'],
+  },
+  none: {
+    build: '<填写>',
+    test: '<填写>',
+    typecheck: '<填写>',
+    builds: [],
+    checks: [],
+    allow: [],
+  },
+};
+
+// AGENTS.md「项目适配区」的命令预填变量（技术栈未知时留 <填写> 占位）
+export function pickStackVars(stackKey) {
+  const s = STACKS[stackKey] || STACKS.none;
+  return { BUILD_CMD: s.build, TEST_CMD: s.test, TYPECHECK_CMD: s.typecheck };
+}
+
+// 两态文件模型的归属判定：managed（随包升级）之外皆 owned（项目内容，sync 永不覆盖）
+// local-pre-commit 是项目门禁挂载点——一旦接线即含项目内容，按 owned 起步（旧台账里若在 managed，改动后 sync 也会保守跳过）
+export function isOwned(rel) {
+  return rel === 'AGENTS.md' || rel === '.gitattributes' || rel.startsWith('workflow/') || rel.startsWith('wiki/')
+    || rel.startsWith('.agents/notes/')
+    || rel === '.agents/workflow-modules.txt' || rel === '.agents/rule-budgets.txt'
+    || rel === '.agents/hooks/local-pre-commit';
+}
+
+export function settingsJson(stackKey) {
+  const allow = [...new Set([
+    'node', 'git status', 'git diff', 'git add', 'git commit', 'git log', 'git push',
+    'npm run', 'npm install', 'npm ci',
+    ...(STACKS[stackKey]?.allow || []),
+  ])];
+  return `${JSON.stringify({
+    permissions: {
+      allow,
+      deny: ['git reset --hard', 'git push --force', 'git push -f', 'drop database'],
+      ask: ['git checkout', 'git clean', 'git branch -D', 'rm -rf'],
+    },
+  }, null, 2)}\n`;
+}
+
+export function commitCheckConfig(stackKey) {
+  return `${JSON.stringify({
+    knownPatterns: [],
+    builds: STACKS[stackKey]?.builds || [],
+    checks: STACKS[stackKey]?.checks || [],
+  }, null, 2)}\n`;
+}

package/src/render.mjs

@@ -0,0 +1,68 @@
+// 模板树渲染：目录名前缀 _ 映射为点目录（_agents→.agents）；文本文件做 {{KEY}} 占位符替换
+// 返回写入清单（rel + sha256），供 kit.json managed 台账与 doctor 校验
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const PH_RE = /\{\{([A-Z][A-Z0-9_]*)\}\}/g;
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// relOf：模板内相对路径 → 目标相对路径（仅顶层 _ 前缀目录转点目录）
+function relOf(absFile, srcRoot) {
+  const parts = path.relative(srcRoot, absFile).split(path.sep);
+  if (parts.length > 1 && parts[0].startsWith('_')) parts[0] = '.' + parts[0].slice(1);
+  return parts.join('/');
+}
+
+export function renderTree(srcRoot, targetRoot, vars, { force = false } = {}) {
+  const written = [];   // { rel, sha256 }
+  const skipped = [];   // rel（已存在，保守跳过）
+  const warnings = [];  // 未知占位符等
+  const dirs = [];
+
+  (function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        dirs.push(relOf(abs, srcRoot));
+        walk(abs);
+        continue;
+      }
+      const rel = relOf(abs, srcRoot);
+      const target = path.join(targetRoot, rel);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      if (fs.existsSync(target) && !force) {
+        skipped.push(rel);
+        continue;
+      }
+      const raw = fs.readFileSync(abs);
+      let out = raw;
+      if (raw.length < 512 * 1024 && !raw.includes(0)) {
+        const text = raw.toString('utf8');
+        const used = new Set();
+        const replaced = text.replace(PH_RE, (m, key) => {
+          if (Object.prototype.hasOwnProperty.call(vars, key)) {
+            used.add(key);
+            return vars[key];
+          }
+          return m; // 未知占位符原样保留，doctor 会告警
+        });
+        if (replaced.includes('{{')) {
+          for (const m of replaced.matchAll(/\{\{([A-Z][A-Z0-9_]*)\}\}/g)) {
+            if (!Object.prototype.hasOwnProperty.call(vars, m[1])) warnings.push(`${rel}: 未知占位符 {{${m[1]}}}（原样保留）`);
+          }
+        }
+        out = Buffer.from(replaced, 'utf8');
+      }
+      fs.writeFileSync(target, out);
+      written.push({ rel: rel.split(path.sep).join('/'), sha256: sha256(out) });
+    }
+  })(srcRoot);
+
+  return { written, skipped, warnings, dirs };
+}
+
+export { sha256 };

package/src/run-tests.mjs

@@ -0,0 +1,35 @@
+// run-tests.mjs — 全套测试入口（npm test）：CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs + check-loop bash 套件。
+// 顺序执行、任一非零整体失败（exit 1）；无 sh 环境（极简 Windows）跳过 bash 套件并显著提示。
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const nodeSuites = [
+  'src/sync.test.mjs',
+  ...fs.readdirSync(path.join(ROOT, 'templates/_agents/scripts'))
+    .filter((f) => f.endsWith('.test.mjs'))
+    .sort()
+    .map((f) => `templates/_agents/scripts/${f}`),
+];
+
+let failed = 0;
+for (const rel of nodeSuites) {
+  console.log(`\n===== ${rel} =====`);
+  const r = spawnSync(process.execPath, [path.join(ROOT, rel)], { cwd: ROOT, stdio: 'inherit' });
+  if (r.status !== 0) failed++;
+}
+
+const shSuite = 'templates/_agents/scripts/check-loop.test.sh';
+if (spawnSync('sh', ['-c', 'true']).status === 0) {
+  console.log(`\n===== ${shSuite}（bash 套件） =====`);
+  const r = spawnSync('sh', [path.join(ROOT, shSuite)], { cwd: ROOT, stdio: 'inherit' });
+  if (r.status !== 0) failed++;
+} else {
+  console.warn(`\n⚠️ 环境无 sh——跳过 ${shSuite}（装 Git Bash / 在 WSL 里补跑，勿静默当作通过）`);
+}
+
+console.log(`\n${failed ? `❌ ${failed} 个套件失败` : '✅ 全部套件通过'}`);
+process.exit(failed ? 1 : 0);