agentic-flow-kit 0.4.0 → 0.5.0

package/src/doctor.mjs

@@ -50,8 +50,11 @@ export function doctor(args, pkgRoot) {
     '.agents/board/index.html',
     '.agents/hooks/commit-check.cjs',
     '.agents/workflow-modules.txt',
+    '.agents/workflow-enums.txt',
     '.agents/rule-budgets.txt',
     '.agents/settings.json',
+    '.agents/workflows/_TEMPLATE.md',
+    '.agents/scripts/check-loop.mjs',
     '.githooks/pre-commit',
     '.githooks/pre-push',
     '.githooks/commit-msg',
@@ -127,22 +130,63 @@ export function doctor(args, pkgRoot) {
     else add('WARN', `delegations 台账结构漂移——${String(agg.stderr || agg.stdout || '').split('\n')[0]}`);
   }
 
-  // 7. check-loop——先探 sh 可用性（对齐 run-tests.mjs 先例）：Windows PowerShell 常无 sh，
-  //    ENOENT 曾被吞进 hard-block 分支报成空原因假警报（incident 2026-09-24-doctor-sh-enoent）。
-  //    git 钩子门禁不受此影响——git 以自带 sh 执行钩子，与用户 PATH 无关。
-  const shProbe = spawnSync('sh', ['-c', 'true'], { encoding: 'utf8' });
-  if (shProbe.status !== 0) {
-    add('WARN', '环境无 sh——check-loop 未跑，勿当作通过；装 Git Bash / WSL 后重跑 doctor（git 钩子门禁不受影响，git 以自带 sh 执行）');
+  // 6.6 owned 漂移校验（kit.owned 列表盘面 sha 不一致；engine 双源纪律对 owned 走「项目自持 + 哈希记账不约束」，
+  //     漂移信号靠本校验给装户可见性。2026-09-25 wf-runtime 复盘：包源改了装副本未同步 = 漂移但 sync 不报。）
+  const ownedRes = checkOwnedDrift(target);
+  if (ownedRes.error) {
+    add('WARN', `owned 校验跳过（kit.json 解析失败：${ownedRes.error}）`);
+  } else if (ownedRes.skipped) {
+    add('PASS', 'owned 校验跳过（kit.json 无 owned 条目）');
+  } else if (ownedRes.total === 0) {
+    add('PASS', 'owned 校验跳过（kit.json 无 owned 条目）');
+  } else if (ownedRes.drift === 0 && ownedRes.gone.length === 0) {
+    add('PASS', `owned ${ownedRes.total} 份无漂移（装副本与台账 sha 对齐）`);
   } else {
-    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 警告）` : ''}`);
+    // owned 漂移已严化为 FAIL（2026-09-25 doctor-owned-drift-strict 复盘；首次引入用 WARN，installed 装户吃过警告后升级）
+    if (ownedRes.drift) add('FAIL', `owned 漂移 ${ownedRes.drift} 份——装副本手改未跑 sync 刷台账 / 包源改了装副本未同步；须手动同步装副本后跑 node bin/flow-kit.mjs sync 刷台账（见 incidents/2026-09-25-wf-runtime 复盘）`);
+    if (ownedRes.gone.length) add('FAIL', `owned 文件缺失：${ownedRes.gone.join('、')}——sync 恢复或手动恢复`);
+  }
+
+  // 6.7 跨宿主薄适配正文段漂移校验（2026-09-25 cross-host-sync，参见 workflows/intents/2026-09-25-cross-host-sync.md）
+  //     装户侧视角：.agents/{commands,roles}/*.md 是权威源；4 宿主目录（.zcode/.omp/.opencode/.trae）下的
+  //     {agents,commands}/*.md 是薄适配。按正文段 sha 比对（B-b 语义，frontmatter 不计入漂移），
+  //     trae commands 加 wf- 前缀映射。首次引入为 WARN（沿用 wf-runtime 复盘「先 WARN 升级 FAIL」路径），
+  //     待装户升级视反馈升级 FAIL。包源侧对应工具是 flow-kit sync-hosts（src/sync-hosts.mjs）。
+  const adapterRes = checkAdapterDrift(target);
+  if (adapterRes.skipped) {
+    add('PASS', `跨宿主薄适配校验跳过（${adapterRes.note || '权威源目录不存在'}）`);
+  } else if (adapterRes.drift === 0) {
+    add('PASS', `跨宿主薄适配 ${adapterRes.total} 对无正文漂移（装副本引擎 vs 4 宿主薄适配，B-b 语义）`);
+  } else {
+    add('WARN', `跨宿主薄适配正文漂移 ${adapterRes.drift} 对——权威源与薄适配正文段 sha 不一致；按 .agents/commands/sync-hosts.md 跑 flow-kit sync-hosts --apply 单向同步薄适配正文（frontmatter 不动）；装户可在 bin/flow-kit.mjs sync 时一并修复`);
+  }
+
+  // 6.8 workflows 编排脚本 lint（stages 表解析校验：role/step/after 引用、无环、三形态互斥、数值枚举；
+  //     2026-09-25 workflows-linter 把 _TEMPLATE.md「解析校验先行」从 prose 变机器门。首次引入 WARN
+  //     （沿用 wf-runtime 复盘「先 WARN 升级 FAIL」渐进路径），装户吃过警告后可升 FAIL。
+  //     旧版装户 sync 前 .agents/scripts/workflows-check.mjs 不存在 → 自然跳过不误报）
+  if (fs.existsSync(path.join(target, '.agents/scripts/workflows-check.mjs')) && fs.existsSync(path.join(target, '.agents/workflows'))) {
+    const wf = spawnSync(process.execPath, ['.agents/scripts/workflows-check.mjs'], { cwd: target, encoding: 'utf8' });
+    if (wf.status === 0) {
+      const warnN = (String(wf.stdout || '').match(/- ⚠️ W\d/g) || []).length;
+      add('PASS', `workflows 编排脚本 lint 干净${warnN ? `（${warnN} 条 advisory 告警）` : ''}`);
     } else {
-      add('FAIL', `check-loop 有 hard-block：\n${String(cl.stderr || '').split('\n').slice(0, 8).join('\n')}`);
+      const firstHit = String(wf.stdout || wf.stderr || '').split('\n').find((l) => / E\d/.test(l)) || `exit ${wf.status}`;
+      add('WARN', `workflows 编排脚本 lint 未过——${firstHit.trim()}；修 .agents/workflows/ 编排脚本（role/step/after 引用、三形态、retries）后重跑`);
     }
   }
 
+  // 7. check-loop——2026-09-26 check-loop-node 起 node 实现直跑（sh 版曾需先探 sh 可用性：Windows
+  //    PowerShell 常无 sh，ENOENT 曾被吞进 hard-block 分支报成空原因假警报，incident 2026-09-24-doctor-sh-enoent；
+  //    迁移后无 sh 依赖，探针退役。check-loop.sh 为兼容 shim，pre-push 钩子路径照常）
+  const cl = spawnSync(process.execPath, ['.agents/scripts/check-loop.mjs'], { 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';
@@ -162,3 +206,86 @@ function print(results) {
   const warns = results.filter((r) => r.level === 'WARN').length;
   console.log(`\ndoctor：${results.length - fails - warns} PASS ｜ ${warns} WARN ｜ ${fails} FAIL`);
 }
+
+// owned 漂移校验（独立 export 供 doctor 主流程 + 单元测试共用；2026-09-25 wf-runtime 复盘）
+// 返回：{ drift, gone, total, skipped, error? }
+//   - skipped=true：kit.json 不存在或解析失败/无 owned 字段
+//   - drift：盘面 sha != kit.owned sha 的文件数
+//   - gone：盘面缺失的文件 rel 列表
+//   - total：kit.owned 列表总文件数
+export function checkOwnedDrift(target) {
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (!fs.existsSync(kitPath)) return { drift: 0, gone: [], total: 0, skipped: true };
+  let kit;
+  try {
+    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+  } catch (e) {
+    return { drift: 0, gone: [], total: 0, skipped: true, error: e.message };
+  }
+  const owned = Array.isArray(kit.owned) ? kit.owned : [];
+  if (owned.length === 0) return { drift: 0, gone: [], total: 0, skipped: true };
+  let drift = 0;
+  const gone = [];
+  for (const f of owned) {
+    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) drift++;
+  }
+  return { drift, gone, total: owned.length, skipped: false };
+}
+
+// 跨宿主薄适配正文段漂移校验（独立 export 供 doctor 主流程 + 单元测试共用；2026-09-25 cross-host-sync）
+// 装户侧视角：.agents/{commands,roles}/*.md 是权威源；4 宿主目录（zcode→.zcode、omp→.omp、
+// opencode→.opencode、trae→.trae）下 {agents,commands}/*.md 是薄适配。按正文段 sha 比对
+// （B-b 语义；frontmatter 不计入漂移）；trae commands 加 wf- 前缀映射。
+// 返回：{ drift, total, skipped, note? }
+//   - skipped=true：权威源目录不存在 / 包源环境 / 无 .md 文件
+//   - drift：权威源正文段与薄适配正文段 sha 不一致的对数
+//   - total：参与比对的对数（权威源文件 × 适配数）
+export function checkAdapterDrift(target) {
+  const authorityRoot = path.join(target, '.agents');
+  if (!fs.existsSync(authorityRoot)) return { drift: 0, total: 0, skipped: true, note: '.agents 目录不存在' };
+  // 包源环境检测：包源仓库同时含 templates/ 与 modules/，装户不应有；包源下跑 doctor §7.x 永远是
+  // drift（装副本是历史 init 渲染产物，不会随包源改动而重渲），无信息价值——直接 skip
+  if (fs.existsSync(path.join(target, 'templates', '_agents')) && fs.existsSync(path.join(target, 'modules', 'hosts'))) {
+    return { drift: 0, total: 0, skipped: true, note: '包源环境（templates/ + modules/ 同时存在）——§7.x 仅在装户环境有意义' };
+  }
+  // 4 宿主目录映射（与 src/profiles.mjs#HOSTS 同源：装副本目录名前缀带点）
+  const HOST_DIR = { zcode: '.zcode', omp: '.omp', opencode: '.opencode', trae: '.trae' };
+  const splitFm = (text) => {
+    const m = String(text || '').match(/^---\r?\n([\s\S]*?\r?\n)---\r?\n?([\s\S]*)$/);
+    if (!m) return { fm: '', body: String(text || '') };
+    return { fm: `---\n${m[1]}---\n`, body: m[2] };
+  };
+  const bodySha = (p) => {
+    try { return createHash('sha256').update(splitFm(fs.readFileSync(p, 'utf8')).body).digest('hex'); } catch { return null; }
+  };
+  let total = 0;
+  let drift = 0;
+  const listMd = (dir) => fs.existsSync(dir) && fs.statSync(dir).isDirectory() ? fs.readdirSync(dir).filter((f) => f.endsWith('.md')) : [];
+  for (const sub of ['commands', 'roles']) {
+    const subAbs = path.join(authorityRoot, sub);
+    for (const f of listMd(subAbs)) {
+      const authRel = `${sub}/${f}`;
+      const authSha = bodySha(path.join(authorityRoot, authRel));
+      const name = f.slice(0, -'.md'.length);
+      // 构建映射：commands/* → opencode/commands/<name>.md + trae/commands/wf-<name>.md；roles/* → 4 宿主 agents/<name>.md
+      const targets = [];
+      if (sub === 'commands') {
+        targets.push([HOST_DIR.opencode, 'commands', `${name}.md`], [HOST_DIR.trae, 'commands', `wf-${name}.md`]);
+      } else {
+        for (const h of Object.keys(HOST_DIR)) targets.push([HOST_DIR[h], 'agents', `${name}.md`]);
+      }
+      for (const [hostDir, subDir, fileName] of targets) {
+        const adapterAbs = path.join(target, hostDir, subDir, fileName);
+        const adapterSha = bodySha(adapterAbs);
+        if (adapterSha === null) continue; // 缺失不在 drift 统计（apply 不自动创建）
+        total++;
+        if (authSha !== adapterSha) drift++;
+      }
+    }
+  }
+  if (total === 0) return { drift: 0, total: 0, skipped: true, note: '权威源无 commands/roles .md 文件' };
+  return { drift, total, skipped: false };
+}

package/src/init.test.mjs

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
-// init.mjs 交互解析纯函数测试（normalizeStack / parseChoices）——不触真实安装与 stdin
+// init.mjs 交互解析纯函数测试（normalizeStack / parseChoices）+ 装户面断言——解析层不触真实安装与 stdin；
+// 装户面节对真实 templates/ 树跑 renderTree（init/sync 同一装户路径），断言编排 runner 与 workflows 目录在装户清单内。
 // 断言：①ts/js 别名归一 node；②序号/名称/混输/全角逗号/空白分隔解析正确（去重保序）；
-//       ③非法输入返回 null（就地重问信号）；④空输入回默认（EOF/直接回车安全回退）。
+//       ③非法输入返回 null（就地重问信号）；④空输入回默认（EOF/直接回车安全回退）；⑥装户面含 runner/workflows。
 // 用法：node src/init.test.mjs
 import { normalizeStack, parseChoices, hasAgentsSkeleton, mergeAgents } from './init.mjs';
+import { renderTree } from './render.mjs';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 let pass = 0;
 let fail = 0;
@@ -48,6 +54,23 @@ check('合并：原内容尾部空白折叠不产生连续空行',
   mergeAgents('# A\n内容\n\n\n', '<!-- m -->\n# B') === '# A\n内容\n\n<!-- m -->\n# B\n');
 check('合并：原内容为空时骨架即全文', mergeAgents('', '<!-- m -->\n# B') === '<!-- m -->\n# B\n');
 
+// ---- ⑥ 装户面：真实模板树含编排机制件（init/sync 同走 renderTree，结构保证装户必有） ----
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-surface-'));
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const t = renderTree(path.join(pkgRoot, 'templates'), tmp, { BOARD_PORT: '8933' }, { force: true });
+  const rels = new Set(t.written.map((w) => w.rel));
+  check('装户面含机制文档与编排脚本示例（_TEMPLATE + 示例 .md）',
+    rels.has('.agents/workflows/_TEMPLATE.md') && rels.has('.agents/workflows/示例-并行实现评审.md'),
+    [...rels].filter((r) => r.includes('workflows')).join('、'));
+  check('装户面含 steps 扩展点示例', rels.has('.agents/workflows/steps/示例-部署验证.md'),
+    [...rels].filter((r) => r.includes('steps')).join('、'));
+  check('装户面无 orchestrate 命令残留（编排机制为目录约定，2026-09-25-wf-runtime）',
+    ![...rels].some((r) => r.includes('orchestrate')),
+    [...rels].filter((r) => r.includes('orchestrate')).join('、'));
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log('\n用法：node src/init.test.mjs');

package/src/pack.test.mjs

@@ -0,0 +1,24 @@
+// pack.test.mjs — npm 打包防线断言：templates/_agents/cache（运行时生成、gitignore）不得进发布包。
+// 0.4.0 实发包含测试残留 kb-index.json（incident 2026-09-24-npm-pack-cache-leak）——files 白名单列出
+// templates 后 npm-packlist 不再按根 .gitignore 排除目录内文件，须显式负向排除；prepack 兜底物理清除。
+// 此处断言配置层两道防线在位（npm 10/11 双版本 pack 行为已在 incident 实测验证）。
+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 pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+
+let pass = 0, fail = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+
+const files = pkg.files || [];
+const prepack = pkg.scripts?.prepack || '';
+check('P1 files 负向排除 cache 目录与内容', files.includes('!templates/_agents/cache') && files.includes('!templates/_agents/cache/**'), JSON.stringify(files));
+check('P2 prepack 兜底清除 cache 目录', /templates[\\/]_agents[\\/]cache/.test(prepack) && /rmSync/.test(prepack), prepack || 'scripts.prepack 缺失');
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/src/run-tests.mjs

@@ -1,5 +1,6 @@
-// run-tests.mjs — 全套测试入口（npm test）：CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs + check-loop bash 套件。
-// 顺序执行、任一非零整体失败（exit 1）；无 sh 环境（极简 Windows）跳过 bash 套件并显著提示。
+// run-tests.mjs — 全套测试入口（npm test）：CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs 套件。
+// 顺序执行、任一非零整体失败（exit 1）。check-loop 套件自 2026-09-26 check-loop-node 起为 node 实现
+// （check-loop.test.mjs 由下方 glob 自动发现——旧 bash 特判与「无 sh 跳过」提示随迁移退役）。
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -10,6 +11,7 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const nodeSuites = [
   'src/sync.test.mjs',
   'src/init.test.mjs',
+  'src/pack.test.mjs',
   ...fs.readdirSync(path.join(ROOT, 'templates/_agents/scripts'))
     .filter((f) => f.endsWith('.test.mjs'))
     .sort()
@@ -23,14 +25,5 @@ for (const rel of nodeSuites) {
   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);

package/src/sync-hosts.mjs

@@ -0,0 +1,193 @@
+// flow-kit sync-hosts：跨宿主适配层正文段漂移检查 + 单向同步（B-b 方案，2026-09-25）
+// 目的：改权威源（templates/_agents/{commands,roles}/*.md）正文要同步到 N 份薄适配
+// （modules/hosts/<h>/{agents,commands}/*.md）的对应正文段；薄适配 frontmatter 保留宿主特化字段
+// （trae commands 加 name: wf-X、opencode/zcode/omp 各自原描述），不在同步范围。
+// B-b 语义：sha 比对与 apply 只动正文段，frontmatter 双方各自维护。
+// 算法：diffHosts 抽为 pure function（authorityRoot + adaptersRoot 两个根）；
+//       sync-hosts CLI 在 pkgRoot 跑（包源视角）；doctor §7.x 在 target 跑（装户视角）——同源逻辑。
+import fs from 'node:fs';
+import path from 'node:path';
+import { HOSTS } from './profiles.mjs';
+import { sha256 } from './render.mjs';
+
+function fail(msg) {
+  console.error(`❌ ${msg}`);
+  process.exit(1);
+}
+
+// 剥离 frontmatter 返回 { fm, body }；无 frontmatter 时 fm = ''，body = 整文件
+// frontmatter 形如 "---\n...\n---\n"，位于文件首；其后（含分隔空行）为正文段。
+function splitFm(text) {
+  const m = String(text || '').match(/^---\r?\n([\s\S]*?\r?\n)---\r?\n?([\s\S]*)$/);
+  if (!m) return { fm: '', body: String(text || '') };
+  // fm 还原为带分隔横线的形式；body 保留首部空行
+  return { fm: `---\n${m[1]}---\n`, body: m[2] };
+}
+
+// bodySha：剥离 frontmatter 后的正文段 sha256（缺失返 null）
+function bodySha(p) {
+  try {
+    const { body } = splitFm(fs.readFileSync(p, 'utf8'));
+    return sha256(Buffer.from(body, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// listMd：列目录下 .md 文件（同步当前层；不递归）
+function listMd(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+}
+
+// pairsFor：权威源文件 → 薄适配 rel 列表（与 sync-hosts 早版同映射；trae commands 加 wf- 前缀）
+function pairsFor(authRel) {
+  const out = [];
+  const norm = authRel.split(path.sep).join('/');
+  if (norm.startsWith('commands/') && norm.endsWith('.md')) {
+    const name = norm.slice('commands/'.length, -'.md'.length);
+    out.push({ adapterRel: `opencode/commands/${name}.md` });
+    out.push({ adapterRel: `trae/commands/wf-${name}.md` });
+  } else if (norm.startsWith('roles/') && norm.endsWith('.md')) {
+    const name = norm.slice('roles/'.length, -'.md'.length);
+    for (const h of Object.keys(HOSTS)) out.push({ adapterRel: `${h}/agents/${name}.md` });
+  }
+  return out;
+}
+
+// diffHosts：权威源正文段 vs 薄适配正文段的漂移分析（B-b 语义；pure function）。
+// authorityRoot：权威源根（含 commands/ + roles/）
+// adaptersRoot：薄适配根（含 <h>/{agents,commands}/）
+// 返回：{ drift, inSync, authorityMissing, adapterOrphans, note }
+//   drift       = 正文段 sha 不一致（权威源改 / 薄适配手改 都计入；不区分方向）
+//   inSync      = 正文段 sha 对齐的文件对数
+//   authorityMissing = 权威源声明但薄适配文件不存在（apply 不自动创建——薄适配须经 add-host 接管）
+//   adapterOrphans   = 薄适配存在但权威源无对应文件（apply 不删——可能是宿主特化或历史残留）
+export function diffHosts({ authorityRoot, adaptersRoot }) {
+  if (!fs.existsSync(authorityRoot)) return { drift: [], inSync: 0, authorityMissing: [], adapterOrphans: [], note: `权威源根不存在：${authorityRoot}` };
+
+  const drift = [];
+  let inSync = 0;
+  const adapterSeen = new Set();
+  const authorityMissing = [];
+
+  // 扫权威源 commands/ + roles/
+  for (const sub of ['commands', 'roles']) {
+    const subAbs = path.join(authorityRoot, sub);
+    for (const f of listMd(subAbs)) {
+      const authRel = `${sub}/${f}`;
+      const authAbs = path.join(authorityRoot, authRel);
+      const authSha = bodySha(authAbs);
+      const pairs = pairsFor(authRel);
+      if (pairs.length === 0) continue;
+      for (const { adapterRel } of pairs) {
+        adapterSeen.add(adapterRel);
+        const adapterAbs = path.join(adaptersRoot, adapterRel);
+        const adapterSha = bodySha(adapterAbs);
+        if (adapterSha === null) {
+          authorityMissing.push({ authRel, adapterRel });
+          continue;
+        }
+        if (authSha === adapterSha) { inSync++; continue; }
+        drift.push({ authRel, adapterRel, authSha, adapterSha });
+      }
+    }
+  }
+
+  // 扫薄适配找孤儿（权威源无对应文件）
+  const adapterOrphans = [];
+  for (const h of Object.keys(HOSTS)) {
+    for (const sub of ['agents', 'commands']) {
+      const subAbs = path.join(adaptersRoot, h, sub);
+      for (const f of listMd(subAbs)) {
+        const adapterRel = `${h}/${sub}/${f}`;
+        if (adapterSeen.has(adapterRel)) continue;
+        let authGuess;
+        if (h === 'trae' && sub === 'commands' && f.startsWith('wf-')) {
+          authGuess = `commands/${f.slice('wf-'.length)}`;
+        } else if (sub === 'agents') {
+          authGuess = `roles/${f}`;
+        } else {
+          authGuess = `commands/${f}`;
+        }
+        adapterOrphans.push({ adapterRel, authGuess });
+      }
+    }
+  }
+
+  return { drift, inSync, authorityMissing, adapterOrphans };
+}
+
+// printDiff：人类可读 diff 报告（B-b 语义：正文段比对 + frontmatter 双方不动）
+function printDiff(result) {
+  const { drift, inSync, authorityMissing, adapterOrphans, note } = result;
+  if (note) console.log(`ℹ️  ${note}\n`);
+  console.log(`  正文对齐：${inSync} 对`);
+  if (authorityMissing.length) {
+    console.log(`  权威源声明但薄适配缺失（${authorityMissing.length}，apply 不自动创建——薄适配须经 add-host 接管）：`);
+    for (const { authRel, adapterRel } of authorityMissing) console.log(`    - ${authRel} → ${adapterRel}`);
+  }
+  if (drift.length) {
+    console.log(`  正文段漂移（${drift.length}，权威源与薄适配正文 sha 不一致——可能是权威源改了或薄适配正文手改了；run with --apply to sync 正文段，frontmatter 不动）：`);
+    for (const { authRel, adapterRel } of drift) console.log(`    - ${authRel} → ${adapterRel}`);
+  } else if (!authorityMissing.length) {
+    console.log('  无漂移 ✅');
+  }
+  if (adapterOrphans.length) {
+    console.log(`  ⚠️  孤儿薄适配（${adapterOrphans.length}，权威源无对应文件，可能是历史残留或宿主特化；apply 不删）：`);
+    for (const { adapterRel, authGuess } of adapterOrphans) console.log(`    - ${adapterRel}（推测权威源：${authGuess}）`);
+  }
+}
+
+// applyForward：把权威源正文段同步到薄适配（保留薄适配原 frontmatter）
+// 返回：{ synced: [{adapterRel}] }
+function applyForward({ authorityRoot, adaptersRoot }, drift) {
+  const synced = [];
+  for (const { authRel, adapterRel } of drift) {
+    const authAbs = path.join(authorityRoot, authRel);
+    const adapterAbs = path.join(adaptersRoot, adapterRel);
+    const authText = fs.readFileSync(authAbs, 'utf8');
+    const adapterText = fs.readFileSync(adapterAbs, 'utf8');
+    const { body } = splitFm(authText);
+    const { fm } = splitFm(adapterText);
+    // 拼接：薄适配 frontmatter + 权威源正文段
+    fs.mkdirSync(path.dirname(adapterAbs), { recursive: true });
+    fs.writeFileSync(adapterAbs, `${fm}${body}`);
+    synced.push(adapterRel);
+  }
+  return { synced };
+}
+
+export function syncHosts(args, pkgRoot) {
+  let apply = false;
+  let json = false;
+  for (const a of args) {
+    if (a === '--diff') apply = false;
+    else if (a === '--apply') apply = true;
+    else if (a === '--json') json = true;
+    else fail(`未知选项：${a}（flow-kit sync-hosts --help）`);
+  }
+  if (!pkgRoot) fail('sync-hosts 缺少 pkgRoot（开发模式入口）');
+
+  const authorityRoot = path.join(pkgRoot, 'templates', '_agents');
+  const adaptersRoot = path.join(pkgRoot, 'modules', 'hosts');
+  const result = diffHosts({ authorityRoot, adaptersRoot });
+
+  if (apply && result.drift.length > 0) {
+    const { synced } = applyForward({ authorityRoot, adaptersRoot }, result.drift);
+    console.log(`▶ flow-kit sync-hosts --apply → ${pkgRoot}`);
+    console.log(`  按权威源正文覆盖薄适配正文段 ${synced.length} 份（薄适配 frontmatter 不动）：`);
+    for (const rel of synced) console.log(`    - ${rel}`);
+    const after = diffHosts({ authorityRoot, adaptersRoot });
+    console.log(`  同步后正文对齐：${after.inSync} 对；权威源缺失：${after.authorityMissing.length}；正文漂移：${after.drift.length}`);
+    return after.drift.length === 0 && after.authorityMissing.length === 0 ? 0 : 1;
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    console.log(`▶ flow-kit sync-hosts --diff → ${pkgRoot}`);
+    printDiff(result);
+  }
+  return 0;
+}

package/src/sync-hosts.test.mjs

@@ -0,0 +1,170 @@
+// sync-hosts.test.mjs — flow-kit sync-hosts B-b 语义四场景（2026-09-25）
+// 方法：迷你 fixture 包根（权威源 templates/_agents + 薄适配 modules/hosts/<h>/{agents,commands}/
+//       与权威源正文段一致，frontmatter 各异）+ 子进程 driver 调真实 sync-hosts（隔离 process.exit）
+// 判据：①全对齐 → inSync=28, drift 空  ②权威源改 → drift 列  ③apply → 正文一致，frontmatter 各自保留
+//       ④薄适配 frontmatter 手改 → 不进 drift  ⑤薄适配正文手改 → drift 列，apply 覆盖
+//       ⑥薄适配缺失 → authorityMissing 列；apply 不自动创建
+// 用法：node src/sync-hosts.test.mjs
+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';
+
+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 包根：权威源 + 4 宿主薄适配（正文段与权威源一致，frontmatter 各异） ----
+function mkFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-synchosts-'));
+  // 权威源（2 commands + 1 role，简化测试体量；权威源也带 frontmatter 保证 body 段含前导空行，与薄适配对齐）
+  W(path.join(root, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'templates/_agents/commands/test.md'),
+    `---\ndescription: Test 阶段\nstage: Test\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  W(path.join(root, 'templates/_agents/roles/implementer.md'),
+    `---\ndescription: Implementer 角色契约\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  // 薄适配：commands 权威源 → opencode + trae（trae 加 wf- 前缀 + name）
+  W(path.join(root, 'modules/hosts/opencode/commands/build.md'),
+    `---\ndescription: Build · opencode 风格\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'modules/hosts/trae/commands/wf-build.md'),
+    `---\nname: wf-build\ndescription: Build · trae 风格\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'modules/hosts/opencode/commands/test.md'),
+    `---\ndescription: Test · opencode 风格\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  W(path.join(root, 'modules/hosts/trae/commands/wf-test.md'),
+    `---\nname: wf-test\ndescription: Test · trae 风格\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  // roles 权威源 → 4 宿主 agents（omp/zcode 中文风格 + trae name）
+  W(path.join(root, 'modules/hosts/zcode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: 在已批准工作包内实现\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/omp/agents/implementer.md'),
+    `---\nname: implementer\ndescription: omp 本机风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/opencode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: opencode 英文风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/trae/agents/implementer.md'),
+    `---\nname: implementer\ndescription: trae 英文风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  // 孤儿薄适配：权威源无对应文件
+  W(path.join(root, 'modules/hosts/opencode/commands/orphan.md'), '# orphan\n');
+  return root;
+}
+
+// ---- 子进程 driver：调真实 sync-hosts ----
+function runSyncHosts(fixtureRoot, extra = []) {
+  const driver = path.join(fixtureRoot, 'driver.mjs');
+  W(driver, `import { syncHosts } from ${JSON.stringify(pathToFileURL(path.join(SRC_ROOT, 'sync-hosts.mjs')).href)};
+const root = ${JSON.stringify(fixtureRoot)};
+syncHosts(process.argv.slice(2), root);
+`);
+  return spawnSync(process.execPath, [driver, ...extra], { encoding: 'utf8' });
+}
+
+// ============ 场景 1：全对齐（正文段与权威源一致，frontmatter 各异）→ drift 空 ============
+{
+  const fx = mkFixture();
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S1 全对齐：正文对齐 8 对（2 commands×2 适配 + 1 role×4 宿主）', /正文对齐：\s*8\s*对/.test(out), out);
+  check('S1 全对齐：报告无漂移', /无漂移/.test(out), out);
+  check('S1 全对齐：exit 0', r.status === 0, `status=${r.status}`);
+}
+
+// ============ 场景 2：权威源改了正文，薄适配未跟 → drift 列 4 处（build→opencode+trae, test→opencode+trae）============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v2\n\n权威源正文 build v2\n`);
+  W(path.join(fx, 'templates/_agents/commands/test.md'),
+    `---\ndescription: Test 阶段\nstage: Test\n---\n\n# Test · v2\n\n权威源正文 test v2\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S2 权威源改了 → 正文漂移 4（build×2 + test×2）', /正文段漂移（4/.test(out), out);
+  check('S2 列出 opencode/commands/build.md', out.includes('commands/build.md → opencode/commands/build.md'), out);
+  check('S2 列出 trae/commands/wf-build.md（trae wf- 前缀映射）', out.includes('commands/build.md → trae/commands/wf-build.md'), out);
+  check('S2 正文对齐 = 4（1 role × 4 宿主 implementer 未改）', /正文对齐：\s*4\s*对/.test(out), out);
+  check('S2 exit 0（diff 模式不阻断）', r.status === 0);
+}
+
+// ============ 场景 3：apply 后正文段 sha 一致，frontmatter 各自保留 ============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v2\n\n权威源正文 build v2\n`);
+  const r = runSyncHosts(fx, ['--apply']);
+  const out = r.stdout + r.stderr;
+  check('S3 apply：报告同步 2 份（opencode + trae）', /按权威源正文覆盖薄适配正文段\s*2\s*份/.test(out), out);
+  check('S3 apply：opencode 正文已同步到 v2', R(path.join(fx, 'modules/hosts/opencode/commands/build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：trae 正文已同步到 v2', R(path.join(fx, 'modules/hosts/trae/commands/wf-build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：opencode frontmatter 保留（仍无 name 字段）', !R(path.join(fx, 'modules/hosts/opencode/commands/build.md')).match(/^name:/m));
+  check('S3 apply：trae frontmatter 保留（仍含 name: wf-build）', R(path.join(fx, 'modules/hosts/trae/commands/wf-build.md')).match(/^name:\s*wf-build/m) !== null);
+  check('S3 apply：权威源不动', R(path.join(fx, 'templates/_agents/commands/build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：再次 diff 应显示对齐 8', true); // 二次扫描由 sync-hosts 内部做
+}
+
+// ============ 场景 4：薄适配 frontmatter 手改 → 不进 drift（正文段比对不受影响）============
+{
+  const fx = mkFixture();
+  // trae frontmatter description 改成"自定义"——正文段未动
+  W(path.join(fx, 'modules/hosts/trae/commands/wf-build.md'),
+    `---\nname: wf-build\ndescription: trae 自定义描述\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S4 frontmatter 差异不计正文段漂移', /正文对齐：\s*8\s*对/.test(out) && /无漂移/.test(out), out);
+}
+
+// ============ 场景 5：薄适配正文手改 → drift 列出，apply 覆盖（不污染权威源）============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'modules/hosts/zcode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: zcode 风格\n---\n\n# Implementer · v1\n\n薄适配手改 implementer v1\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S5 薄适配正文手改 → 正文段漂移 1', /正文段漂移（1/.test(out), out);
+  const r2 = runSyncHosts(fx, ['--apply']);
+  check('S5 apply 后：薄适配正文回到权威源（含「权威源正文 implementer v1」）', /权威源正文 implementer v1/.test(R(path.join(fx, 'modules/hosts/zcode/agents/implementer.md'))));
+  check('S5 apply 不污染权威源（权威源仍 v1）', !R(path.join(fx, 'templates/_agents/roles/implementer.md')).includes('薄适配手改'));
+  // apply 后再 diff 一次，diff 应显示"无漂移"
+  const r3 = runSyncHosts(fx, ['--diff']);
+  check('S5 apply 后再 diff 应无漂移', /无漂移/.test(r3.stdout + r3.stderr), r3.stdout + r3.stderr);
+}
+
+// ============ 场景 6：薄适配文件不存在 → authorityMissing 列出，apply 不创建 ============
+{
+  const fx = mkFixture();
+  fs.rmSync(path.join(fx, 'modules/hosts/opencode/commands/build.md'));
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S6 薄适配缺失 → authorityMissing 列', /权威源声明但薄适配缺失（/.test(out) && out.includes('opencode/commands/build.md'), out);
+  const r2 = runSyncHosts(fx, ['--apply']);
+  check('S6 apply 不自动创建薄适配（仍缺失）', !fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/build.md')));
+}
+
+// ============ 场景 7：--json 机器可读输出 ============
+{
+  const fx = mkFixture();
+  const r = runSyncHosts(fx, ['--json']);
+  const out = r.stdout + r.stderr;
+  let parsed = null;
+  try { parsed = JSON.parse(out); } catch {}
+  check('S7 --json 输出可解析', parsed && typeof parsed === 'object' && Array.isArray(parsed.drift));
+  check('S7 --json 含 inSync = 8', parsed && parsed.inSync === 8, parsed ? JSON.stringify(parsed) : 'null');
+}
+
+// ============ 场景 8：孤儿薄适配（权威源无对应文件）→ adapterOrphans 列，apply 不删 ============
+{
+  const fx = mkFixture();
+  // orphan.md 已在 mkFixture 写入
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S8 孤儿薄适配 → adapterOrphans 列', /孤儿薄适配（/.test(out) && out.includes('opencode/commands/orphan.md'), out);
+  const r2 = runSyncHosts(fx, ['--apply']);
+  check('S8 apply 不删孤儿薄适配', fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/orphan.md')));
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
+process.exit(failCount ? 1 : 0);

package/src/sync.mjs

@@ -74,6 +74,7 @@ export function sync(args, pkgRoot) {
       }
       const diskSha = fs.existsSync(disk) ? sha256(fs.readFileSync(disk)) : null;
       if (diskSha === null) {
+        fs.mkdirSync(path.dirname(disk), { recursive: true }); // 父目录可能整目录缺失（如 localOnly 宿主目录被清），copyfile 不建目录
         fs.copyFileSync(freshFile.abs, disk);
         restored.push(rel);
         managedNew.push({ rel, sha256: freshFile.sha });