agentic-flow-kit 0.2.0

package/modules/hosts/trae/hooks/post-edit-check.cjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse(Edit|Write) hook — 编辑 .cs 文件后即时跑架构红线检查
+ *
+ * Trae 宿主事实：PostToolUse 不能撤销已完成的编辑，但可用 hookSpecificOutput.additionalContext
+ * 把违例喂回模型，让它在提交前自行修掉；硬阻断在 PreToolUse 的 pre-shell-check.cjs（走 .githooks/pre-commit）。
+ *
+ * stdin: { tool_name, llm_tool_name, tool_input: { file_path, ... }, cwd, workspace_roots, ... }
+ */
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const { resolveShell } = require('./resolve-shell.cjs');
+
+// --- 读取 stdin ---
+let raw = '';
+try {
+  raw = fs.readFileSync(0, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+let data;
+try {
+  data = JSON.parse(raw);
+} catch {
+  process.exit(0);
+}
+
+const toolName = `${data.tool_name || ''} ${data.llm_tool_name || ''}`;
+if (!/edit|write/i.test(toolName)) {
+  process.exit(0);
+}
+
+// 文件路径字段名跨宿主/版本可能不同，逐个候选取第一个命中的
+function extractFilePath(input) {
+  if (!input || typeof input !== 'object') return '';
+  for (const k of ['file_path', 'filePath', 'path', 'target_file', 'file']) {
+    if (typeof input[k] === 'string' && input[k]) return input[k];
+  }
+  return '';
+}
+
+const filePath = extractFilePath(data.tool_input);
+if (!/\.cs$/i.test(filePath)) {
+  process.exit(0); // 非 .cs 文件，跳过
+}
+
+const projectRoot = data.cwd || (Array.isArray(data.workspace_roots) && data.workspace_roots[0]) || process.cwd();
+
+const shellBin = resolveShell();
+if (!shellBin) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: '⚠️ 架构红线检查未执行：未找到可用的 bash / sh。安装 Git for Windows 后重试，或提交前手动跑 .agents/hooks/check-architecture.sh。'
+    }
+  }));
+  process.exit(0);
+}
+
+// timeout 单位是毫秒：架构检查实测约 0.6 秒，30 秒预算够用；
+// （2026-09-19 修复：原值 30 是 30 毫秒，必然 ETIMEDOUT，导致每次 .cs 编辑都误报「发现违例」）
+try {
+  execFileSync(shellBin, ['.agents/hooks/check-architecture.sh'], {
+    cwd: projectRoot, stdio: ['ignore', 'pipe', 'pipe'], timeout: 30000
+  });
+  // 通过，无输出
+} catch (e) {
+  if (e.code === 'ETIMEDOUT') {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: '⚠️ 架构红线检查超时（30 秒）：本次编辑未验证，请在提交前手动跑 .agents/hooks/check-architecture.sh。'
+      }
+    }));
+    process.exit(0);
+  }
+  const err = String((e.stderr || '') + (e.stdout || '')).slice(0, 800);
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: `⚠️ 架构红线检查发现违例（check-architecture.sh）：\n${err}\n请在提交前修复；硬阻断在 git commit 时执行。`
+    }
+  }));
+}
+
+process.exit(0);

package/modules/hosts/trae/hooks/pre-shell-check.cjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse(RunCommand) hook — 两道关卡：
+ * 1) deny/ask 命令门禁（口径同 .agents/settings.json 的 deny/ask 策略）
+ * 2) git commit / git push 前置检查：直接调 .githooks/pre-commit / pre-push
+ *
+ * 为什么调 .githooks/*：那是项目唯一的门禁权威（pre-commit 六项 + pre-push 闭环断档）。
+ * 本钩子是**宿主侧冗余**——core.hooksPath 漏配时 git 侧门禁静默失效（2026-09-16 Trae 侧缺档事故），
+ * 由这里在命令执行前拦下；门禁清单只维护 .githooks/ 一份，本文件不复制。
+ *
+ * Trae 宿主事实（docs.trae.ai/ide/hook-configuration-reference）：
+ *   - 终端工具的 matcher 名是 RunCommand（不是 Shell/Bash）；timeout 单位是**秒**。
+ *   - stdin: { session_id, cwd, hook_event_name, workspace_roots, tool_use_id, tool_name, llm_tool_name, tool_input }
+ *   - stdout: hookSpecificOutput.permissionDecision = allow / deny / ask；无输出 = 放行。
+ */
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const { resolveShell } = require('./resolve-shell.cjs');
+
+// --- 读取 stdin ---
+let raw = '';
+try {
+  raw = fs.readFileSync(0, 'utf8');
+} catch {
+  process.exit(0); // 无 stdin，放行
+}
+
+let data;
+try {
+  data = JSON.parse(raw);
+} catch {
+  process.exit(0); // JSON 解析失败，放行（不阻塞正常工作流）
+}
+
+// 工具名兼容：Trae 规范化名为 RunCommand，llm_tool_name 为原始名；保留 Claude 风格别名防宿主差异
+const toolName = `${data.tool_name || ''} ${data.llm_tool_name || ''}`;
+if (!/runcommand|bash|shell|terminal|executecommand/i.test(toolName)) {
+  process.exit(0);
+}
+
+// 取命令文本：优先约定的 command 字段；字段名缺失时退回扫描 tool_input 的字符串值
+// （信任边界上的宿主 payload，字段名跨版本可能不同——漏读会让门禁静默失效，故兜底扫描）
+function extractCommand(input) {
+  if (!input || typeof input !== 'object') return '';
+  if (typeof input.command === 'string' && input.command) return input.command;
+  return Object.values(input).filter(v => typeof v === 'string').join('\n');
+}
+
+const command = extractCommand(data.tool_input);
+if (!command) {
+  process.exit(0);
+}
+
+const projectRoot = data.cwd || (Array.isArray(data.workspace_roots) && data.workspace_roots[0]) || process.cwd();
+
+function deny(reason) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    }
+  }));
+  process.exit(0);
+}
+
+function ask(reason) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'ask',
+      permissionDecisionReason: reason
+    }
+  }));
+  process.exit(0);
+}
+
+// ── 1) deny/ask 命令门禁 ──────────────────────────────
+const denyList = [
+  { pat: 'dotnet ef',         reason: '禁 EF Migrations，Schema 由人工 SQL 维护' },
+  { pat: 'git reset --hard',  reason: '禁破坏性重置' },
+  { pat: 'git push --force',  reason: '禁强制推送' },
+  { pat: 'git push -f',       reason: '禁强制推送' },
+  { pat: 'drop database',     reason: '禁删库' }
+];
+const askList = [
+  { pat: 'git checkout',  reason: '可能切换/丢弃工作区改动' },
+  { pat: 'git clean',     reason: '可能删除未跟踪文件' },
+  { pat: 'git branch -D', reason: '可能删除未合并分支' },
+  { pat: 'rm -rf',        reason: '可能递归删除文件' }
+];
+
+for (const d of denyList) {
+  if (command.includes(d.pat)) {
+    deny(`禁止执行: ${d.pat}（项目红线：${d.reason}）`);
+  }
+}
+for (const a of askList) {
+  if (command.includes(a.pat)) {
+    ask(`需确认: ${a.pat}（项目 ask 策略：${a.reason}）`);
+  }
+}
+
+// ── 2) git commit / git push 前置检查 ──────────────────
+const isCommit = /git\s+commit/.test(command);
+const isPush = /git\s+push/.test(command);
+
+if (!isCommit && !isPush) {
+  process.exit(0); // 非 commit/push，放行
+}
+
+const shellBin = resolveShell();
+if (!shellBin) {
+  deny('门禁未执行：未找到可用的 bash / sh——请安装 Git for Windows，或在 Git Bash 终端手动跑 .githooks/pre-commit');
+}
+
+// runGate：把 .githooks/ 门禁原始输出透传给 AI；未执行（脚本缺失）与判定失败分开报，避免把 ENOENT 误报成代码违例
+function runGate(scriptRelPath, label, budgetMs) {
+  try {
+    execFileSync(shellBin, [scriptRelPath], {
+      cwd: projectRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: budgetMs
+    });
+  } catch (e) {
+    if (e.code === 'ETIMEDOUT') {
+      deny(`${label}超时（${scriptRelPath}，${Math.round(budgetMs / 1000)} 秒未完成）——检查 dotnet build / npm run build 是否卡住`);
+    }
+    if (e.code === 'ENOENT') {
+      deny(`门禁未执行（${label}）：${scriptRelPath} 不可达——确认仓库完整后重试`);
+    }
+    const err = String((e.stdout || '') + (e.stderr || '')).slice(0, 1200);
+    deny(`${label}未通过（${scriptRelPath}）：\n${err}`);
+  }
+}
+
+if (isCommit) {
+  // pre-commit 六项：架构红线 + 审计字段 + 删除拦截 + 闭环配对（增量）+ 敏感信息 + 条件编译
+  // 预算 5 分钟覆盖 dotnet build / npm run build（.githooks/pre-commit 内部无超时）
+  runGate('.githooks/pre-commit', '提交前门禁', 300000);
+}
+
+if (isPush) {
+  // pre-push：check-loop.sh 扫 workflow/ 闭环断档（hard-block = 配对断裂 / 回路断档 / 新建 done 未勾验）
+  // 预算 7 分钟：2026-09-19 实测 check-loop.sh 全量扫描耗时 2 分 53 秒（231 任务卡），
+  // 原定 2 分钟会误报超时——不要按「脚本应该很快」调小
+  runGate('.githooks/pre-push', '推送前闭环扫描', 420000);
+}
+
+// 全部通过，放行
+process.exit(0);

package/modules/hosts/trae/hooks/resolve-shell.cjs

@@ -0,0 +1,21 @@
+// shell 探测（供 .trae/hooks/ 各钩子共用）
+// Windows 下 bash 常不在 PATH：优先 Git Bash 绝对路径，回退 PATH 的 bash/sh。
+// 返回 null 表示不可用——调用方须 fail-closed 报告「门禁未执行」，不要当成检查通过。
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+
+function resolveShell() {
+  const candidates = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe'
+  ];
+  for (const p of candidates) {
+    try { fs.accessSync(p); return p; } catch { /* 尝试下一个 */ }
+  }
+  for (const c of ['bash', 'sh']) {
+    try { execFileSync(c, ['-c', 'exit 0'], { stdio: 'pipe', timeout: 5000 }); return c; } catch { /* 尝试下一个 */ }
+  }
+  return null;
+}
+
+module.exports = { resolveShell };

package/modules/hosts/trae/hooks.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "RunCommand|Bash|Shell|Terminal",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .trae/hooks/pre-shell-check.cjs",
+            "timeout": 480
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .trae/hooks/post-edit-check.cjs",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

package/modules/hosts/trae/rules/beautify-input-chinese.md

@@ -0,0 +1,6 @@
+---
+alwaysApply: false
+scene: beautify_input
+---
+
+请使用中文回复。所有解释、说明、注释和对话均使用中文。

package/modules/hosts/trae/rules/git-commit-message.md

@@ -0,0 +1,10 @@
+---
+alwaysApply: false
+scene: git_message
+---
+
+提交信息一律中文，遵循 Conventional Commits：`<类型>(<范围>): <说明>`，例如 `fix(采购订单): 页签切换浮层收纳`、`docs(trae): 同步工作流适配层`。
+
+- 类型枚举：feat / fix / docs / style / refactor / perf；`.githooks/commit-msg` 按此硬校验首行，非枚举前缀会被拦下，merge / revert 提交豁免。
+- 范围可省：`fix: 说明` 同样合法；分隔符 `:` 或 `（` 均可。
+- 禁止 `[feat] 说明` 这类方括号写法。

package/modules/hosts/trae/rules/project-workflow.md

@@ -0,0 +1,14 @@
+---
+alwaysApply: true
+---
+
+本项目工作流唯一权威是根目录 `AGENTS.md`：开工前必须完整读取并严格遵循（任务流程 / 通用 Working rules / 目录级规则 / 运行时与验证标准），本规则只做入口指针，不复制内容。
+
+- 规则加载是惰性的：根 `AGENTS.md` 常驻；目录级 `AGENTS.md`（如有，如 `backend/AGENTS.md`、`frontend/AGENTS.md`）只在该目录文件被读取或被提及时才生效——动对应目录前先主动读，别凭记忆。
+- 终端环境差异（shell 可用性 / 退出码取法 /「命令不存在 ⇒ 假绿」）见 `.agents/notes/runtime-env.md` §1。
+- 闭环流程目录：`workflow/`（intents / specs / plans / incidents / delegations.md 委派台账 / papercuts.md 留痕）。
+- 6 阶段命令：按用户触发短语路由到 `.trae/commands/wf-*.md`（new-task / plan / design / build / test / deploy / maintain / review）。
+- 子智能体（`.trae/agents/*.md`）按适配器委派；Trae 子智能体为 Beta 功能、需在设置中开启，未开启时按权威命令的 fallback 执行——`fallback: new-session` 必须另开新会话，不得由原会话自查冒充。
+- 闭环兜底以 `.githooks/` 为准（门禁清单以各 hook / `.agents/scripts/check-loop.sh` 头部注释为准，不在本文件复述）；`.trae/hooks/` 在命令执行前再拦一次，`core.hooksPath` 漏配时它是唯一门禁。
+- 委派完成后在 `workflow/delegations.md` 追加一行留痕；命令 / 技能卡壳误导时在 `workflow/papercuts.md` 记一行，不当场顺手改。
+- 中文为项目唯一语言；提交遵循 Conventional Commits 中文。

package/modules/hosts/zcode/agents/implementer.md

@@ -0,0 +1,11 @@
+---
+name: implementer
+description: 在已批准且边界明确的工作包内实现改动或补测试；超出授权文件范围即停
+---
+开工前读项目根 `AGENTS.md` 与 `.agents/roles/implementer.md`，并**完全遵循**该角色契约（必需输入 / 授权文件 / 验收与停止条件）。
+
+宿主适配说明（本机 ZCode）：
+- 只改派单**授权文件**范围内的内容；需偏离（改公共接口 / 动未列文件 / 引新依赖 / 改验收判据）→ **停下报 blocker**，不自行扩大范围。
+- **禁** `git commit` / `git push` / `git reset --hard`；提交与推送由主智能体在复核后执行。
+- 不跑全量静态门（构建 / 测试 / 类型检查，命令见 `.agents/commands/test.md` 项目适配区）——由主智能体在改动面收敛后统一跑；本角色只做与工作包直接相关的最小验证。
+- 派单缺授权文件清单或可执行验收判据时，**返回 blocker 且不动文件**。

package/modules/hosts/zcode/agents/independent-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: independent-reviewer
+description: 只读独立复核（spec 或实现 diff）；不改动文件、不替用户批准
+---
+开工前读项目根 `AGENTS.md` 与 `.agents/roles/independent-reviewer.md`，并**完全遵循**该角色契约（输入 / 只读约束 / 产出格式 / 停止条件）。
+
+宿主适配说明（本机 ZCode）：
+- 只读复核：**不改任何文件**、不跑写操作命令；结论按角色契约的分级清单（P0/P1/P2 + 位置 + 触发条件 + 影响）回报。
+- 不替用户批准——复核结论交主智能体汇总，由用户对话内拍板。
+- 复核范围内引用不到的必读材料（spec / diff / 关联实现）→ 报 blocker，不猜。

package/modules/hosts/zcode/agents/ui-verifier.md

@@ -0,0 +1,10 @@
+---
+name: ui-verifier
+description: 浏览器实测 UI 改动（只读验证、不留脏数据）；结论按页面/步骤/证据回报
+---
+开工前读项目根 `AGENTS.md` 与 `.agents/roles/ui-verifier.md`，并**完全遵循**该角色契约（输入 / 验证步骤 / 不留脏数据约束 / 产出格式）。
+
+宿主适配说明（本机 ZCode）：
+- 只做只读验证与既定步骤操作；**不保存/提交业务数据**，验证产生的临时数据按契约清理。
+- 不修代码——发现缺陷记录「页面 / 步骤 / 期望 vs 实际 / 截图或报文证据」，交主智能体定性。
+- 验证完成后关闭起动的本地进程（按 `.agents/notes/runtime-env.md` §2 的进程清单）。

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "agentic-flow-kit",
+  "version": "0.2.0",
+  "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
+  "type": "module",
+  "scripts": {
+    "test": "node src/run-tests.mjs"
+  },
+  "bin": {
+    "flow-kit": "bin/flow-kit.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "modules",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai-native",
+    "workflow",
+    "agent",
+    "scaffold",
+    "cli",
+    "wiki",
+    "check-loop",
+    "closed-loop"
+  ],
+  "license": "MIT",
+  "private": false
+}

package/src/add-gate.mjs

@@ -0,0 +1,83 @@
+// flow-kit add-gate <门禁>：装门禁模块到 .agents/hooks/ 并接线 local-pre-commit 挂载点。
+// 模块约定：modules/gates/<gate>/ 下源文件拷入 .agents/hooks/（平铺，README.md 与 local-pre-commit.line 为包内元数据不拷）；
+// local-pre-commit.line 内容 = 需追加进 .agents/hooks/local-pre-commit 的挂载行（存在同名行则不重复追加，幂等）。
+// 门禁装后归项目所有：入 owned 台账，sync 永不覆盖（改红线/删不适用条目自行编辑——见各模块 README）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { sha256 } from './render.mjs';
+
+function fail(msg) {
+  console.error(`❌ ${msg}`);
+  process.exit(1);
+}
+
+const META = new Set(['README.md', 'local-pre-commit.line']); // 包内文档/接线元数据，不装进项目
+
+export function addGate(args, pkgRoot) {
+  const gatesRoot = path.join(pkgRoot, 'modules', 'gates');
+  const available = fs.existsSync(gatesRoot) ? fs.readdirSync(gatesRoot, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
+  const gate = args[0];
+  if (!gate || gate.startsWith('--')) fail(`缺少门禁参数（可选：${available.join(' | ') || '无'}）`);
+  if (!available.includes(gate)) fail(`未知门禁：${gate}（可选：${available.join(' | ') || '无'}）`);
+
+  let target = process.cwd();
+  let force = false;
+  for (let i = 1; 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]}`);
+  }
+
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (!fs.existsSync(kitPath)) fail(`${target} 无 .agents/kit.json——先 flow-kit init`);
+  const kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+
+  const srcRoot = path.join(gatesRoot, gate);
+  const hooksDir = path.join(target, '.agents', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  console.log(`▶ flow-kit add-gate ${gate} → ${target}`);
+
+  const installed = [], skipped = [];
+  let wireLine = null;
+  for (const entry of fs.readdirSync(srcRoot, { withFileTypes: true })) {
+    if (entry.isDirectory()) fail(`门禁模块含子目录（${entry.name}）——平铺约定不支持，请检查模块内容`);
+    if (entry.name === 'local-pre-commit.line') { wireLine = fs.readFileSync(path.join(srcRoot, entry.name), 'utf8').trim(); continue; }
+    if (META.has(entry.name)) continue;
+    const dst = path.join(hooksDir, entry.name);
+    if (fs.existsSync(dst) && !force) { skipped.push(entry.name); continue; }
+    fs.copyFileSync(path.join(srcRoot, entry.name), dst);
+    installed.push(entry.name);
+  }
+  console.log(installed.length ? `  安装到 .agents/hooks/：${installed.join('、')}` : '  无新文件');
+  if (skipped.length) console.log(`  跳过（已存在，--force 覆盖）：${skipped.join('、')}`);
+
+  // 接线 local-pre-commit（幂等：挂载行已存在不重复；旧装态尾部 exit 0 会吞掉其后门禁的失败——归一化剥掉）
+  if (wireLine) {
+    const lpPath = path.join(hooksDir, 'local-pre-commit');
+    const cur = fs.existsSync(lpPath) ? fs.readFileSync(lpPath, 'utf8') : '';
+    if (cur.split(/\r?\n/).some((l) => l.trim() === wireLine)) {
+      console.log('  local-pre-commit 已接线（幂等跳过）');
+    } else {
+      let lines = cur.split(/\r?\n/);
+      while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+      if (lines.length && lines[lines.length - 1].trim() === 'exit 0') {
+        lines.pop();
+        console.log('  local-pre-commit 归一化：剥掉尾部 exit 0（旧装态，会吞掉其后门禁的失败）');
+      }
+      const body = lines.length ? `${lines.join('\n')}\n` : '#!/bin/sh\nset -e\n';
+      fs.writeFileSync(lpPath, `${body}${wireLine}\n`);
+      console.log(`  local-pre-commit 接线：+ ${wireLine}`);
+    }
+  }
+
+  // owned 台账补记（归项目所有，sync 永不覆盖）
+  const ownedLedger = new Map((kit.owned || []).map((f) => [f.rel, f]));
+  for (const name of installed) {
+    const rel = `.agents/hooks/${name}`;
+    ownedLedger.set(rel, { rel, sha256: sha256(fs.readFileSync(path.join(hooksDir, name))) });
+  }
+  kit.owned = [...ownedLedger.values()].sort((a, b) => a.rel.localeCompare(b.rel));
+  fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
+
+  console.log('✅ 门禁已装（归项目所有，sync 不覆盖）。装后首个 commit 前先核对脚本头部 CONFIG 的目录/类型名——门禁 fail-closed，目标缺失会拦截提交。');
+}

package/src/add-host.mjs

@@ -0,0 +1,63 @@
+// flow-kit add-host <宿主>：init 后补装宿主适配层。
+// 渲染 modules/hosts/<h> → HOSTS[h].dir → managed 台账按 rel 去重补记 → options.hosts 补记
+// → localOnly 宿主（zcode/omp）.gitignore 追加 → doctor
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderTree } from './render.mjs';
+import { HOSTS, pickStackVars } from './profiles.mjs';
+import { doctor } from './doctor.mjs';
+
+function fail(msg) {
+  console.error(`❌ ${msg}`);
+  process.exit(1);
+}
+
+export function addHost(args, pkgRoot) {
+  const host = args[0];
+  if (!host || host.startsWith('--')) fail(`缺少宿主参数（可选 ${Object.keys(HOSTS).join(' | ')}）`);
+  if (!HOSTS[host]) fail(`未知宿主：${host}（可选 ${Object.keys(HOSTS).join(' | ')}）`);
+
+  let target = process.cwd();
+  let force = false;
+  for (let i = 1; 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]}`);
+  }
+
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (!fs.existsSync(kitPath)) fail(`${target} 无 .agents/kit.json——先 flow-kit init`);
+  const kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+  kit.options = kit.options || {};
+  const already = Array.isArray(kit.options.hosts) && kit.options.hosts.includes(host);
+  if (already && !force) fail(`${host} 已安装（options.hosts 在册）。覆盖更新用 --force`);
+
+  const vars = { BOARD_PORT: String(kit.options.boardPort || '8933'), ...pickStackVars(kit.options.stack) };
+  console.log(`▶ flow-kit add-host ${host} → ${target}${already ? '（--force 覆盖更新）' : ''}`);
+
+  // 宿主层渲染（已存在保守跳过；--force 覆盖）
+  const r = renderTree(path.join(pkgRoot, 'modules', 'hosts', host), path.join(target, HOSTS[host].dir), vars, { force });
+  if (!r.written.length && r.skipped.length) console.log('  跳过（已存在，未覆盖）：' + r.skipped.join('、'));
+  else console.log(`  安装 ${r.written.length} 份${r.skipped.length ? `，跳过已存在 ${r.skipped.length} 份` : ''}`);
+
+  // managed 台账按 rel 去重补记
+  const ledger = new Map((kit.managed || []).map((f) => [f.rel, f]));
+  for (const f of r.written) ledger.set(`${HOSTS[host].dir}/${f.rel}`, { rel: `${HOSTS[host].dir}/${f.rel}`, sha256: f.sha256 });
+  kit.managed = [...ledger.values()].sort((a, b) => a.rel.localeCompare(b.rel));
+  if (!already) kit.options.hosts = [...(kit.options.hosts || []), host];
+  fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
+
+  // localOnly 宿主进 .gitignore（缺才补）
+  if (HOSTS[host].localOnly) {
+    const giPath = path.join(target, '.gitignore');
+    const line = `${HOSTS[host].dir}/`;
+    const giText = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
+    if (!giText.split(/\r?\n/).some((x) => x.trim() === line)) {
+      fs.writeFileSync(giPath, (giText.endsWith('\n') || giText === '' ? giText : giText + '\n') + line + '\n');
+      console.log(`  .gitignore 追加：${line}`);
+    }
+  }
+
+  console.log('▶ flow-kit doctor');
+  doctor(['--dir', target], pkgRoot);
+}

package/src/cli.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// flow-kit CLI 入口：init（安装）/ sync（升级）/ add-host（补宿主）/ add-gate（装门禁）/ doctor（体检）/ help
+import { init } from './init.mjs';
+import { doctor } from './doctor.mjs';
+import { sync } from './sync.mjs';
+import { addHost } from './add-host.mjs';
+import { addGate } from './add-gate.mjs';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const HELP = `flow-kit — AI-Native 闭环工作流 + wiki 知识层脚手架（agentic-flow-kit）
+
+用法：
+  flow-kit init             安装到当前项目（裸跑无参数 → 交互确认环节；带参数直接执行）
+  flow-kit sync             升级 managed 文件（未改动→覆盖新版；本地已改→跳过并报告，--force 才覆盖；
+                            INDEX/看板等生成器目标重跑锚点重写；owned 文件永不触碰）
+  flow-kit add-host <宿主>  后补宿主适配层：zcode | opencode | trae | omp
+  flow-kit add-gate <门禁>  装门禁模块并接线 local-pre-commit（当前：dotnet-ca；装后归项目所有）
+  flow-kit doctor           体检：目录布局 / git 钩子 / managed 清单 / 索引漂移 / check-loop
+
+init 选项（全部可选，均有默认值）：
+  --stack <技术栈>     dotnet | node | python | go | none（默认 none）——门禁配置三处：commit-check
+                       条件编译检查（builds）与质量检测（checks：lint/类型/vet 等秒级确定性检查，
+                       有对应配置文件才启用）、settings.json 自检验命令权限（allow）、
+                       AGENTS.md「项目适配区」命令预填
+  --hosts <宿主列表>   逗号分隔：zcode,opencode,trae,omp（默认 zcode；zcode/omp 为本地配置，自动进 .gitignore）
+  --board-port <端口>  workflow 看板端口（默认 8933）
+  --dir <目录>         目标项目根（默认当前目录）
+  --force              覆盖已存在的同名文件（默认保守跳过）
+
+sync / add-host 选项：--dir <目录>、--force（覆盖本地已改 / 已装内容）；add-gate 选项：--dir <目录>、--force。
+
+示例：
+  npx agentic-flow-kit init                        # 交互模式：宿主 → 技术栈 → 端口 → 确认安装
+  npx agentic-flow-kit init --stack node --hosts zcode,opencode
+  npx agentic-flow-kit sync                        # 包出新版后升级（本地改过的 managed 文件会跳过并报告）
+  npx agentic-flow-kit add-host opencode           # 后补宿主
+  npx agentic-flow-kit add-gate dotnet-ca          # 装 Clean Architecture 门禁
+
+装完即自包含：项目不依赖本包运行；AGENTS.md 生成「AI工作流 + Wiki」骨架，项目细节在「项目适配区」自填。`;
+
+export function run(argv) {
+  const cmd = argv[0];
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(HELP);
+    return;
+  }
+  if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
+    const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+    console.log(pkg.version);
+    return;
+  }
+  if (cmd === 'init') {
+    init(argv.slice(1), PKG_ROOT).catch((e) => {
+      console.error(`❌ ${e?.message || e}`);
+      process.exit(1);
+    });
+    return;
+  }
+  if (cmd === 'sync') {
+    sync(argv.slice(1), PKG_ROOT);
+    return;
+  }
+  if (cmd === 'add-host') {
+    addHost(argv.slice(1), PKG_ROOT);
+    return;
+  }
+  if (cmd === 'add-gate') {
+    addGate(argv.slice(1), PKG_ROOT);
+    return;
+  }
+  if (cmd === 'doctor') {
+    doctor(argv.slice(1), PKG_ROOT);
+    return;
+  }
+  console.error(`未知命令：${cmd}\n\n${HELP}`);
+  process.exit(1);
+}