agentic-flow-kit 1.2.1 → 1.2.2

package/modules/hosts/claude/commands/wf-sync-hosts.md

@@ -7,7 +7,10 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 # Sync-Hosts · 跨宿主适配层正文段同步
 
 > 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
-> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
+> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）；**修漂移用同一条命令**
+> `flow-kit sync-hosts --apply`——2026-10-07 起按**目标根**自动判布局（含 `templates/_agents` + `modules/hosts` → 包源：
+> 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
+> 目标根取 `--dir <目录>` > 当前目录。
 
 ## 何时跑
 
@@ -21,8 +24,9 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 ### 默认 `--diff`（仅报告）
 
 ```
-node bin/flow-kit.mjs sync-hosts --diff
-node bin/flow-kit.mjs sync-hosts --json   # 机器可读
+node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
+node bin/flow-kit.mjs sync-hosts --json      # 机器可读
+flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或用 --dir <项目根> 指定）
 ```
 
 输出三类：

package/modules/hosts/claude/commands/wf-test.md

@@ -56,7 +56,7 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 输出测试报告(通过项 / 失败项)
 - 失败项已修复并复测通过
 - **关单**（日常闭环点，不依赖是否上 prod）:
-  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
+  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
   - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
 **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。

package/modules/hosts/codex/commands/wf-sync-hosts.md

@@ -7,7 +7,10 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 # Sync-Hosts · 跨宿主适配层正文段同步
 
 > 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
-> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
+> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）；**修漂移用同一条命令**
+> `flow-kit sync-hosts --apply`——2026-10-07 起按**目标根**自动判布局（含 `templates/_agents` + `modules/hosts` → 包源：
+> 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
+> 目标根取 `--dir <目录>` > 当前目录。
 
 ## 何时跑
 
@@ -21,8 +24,9 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 ### 默认 `--diff`（仅报告）
 
 ```
-node bin/flow-kit.mjs sync-hosts --diff
-node bin/flow-kit.mjs sync-hosts --json   # 机器可读
+node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
+node bin/flow-kit.mjs sync-hosts --json      # 机器可读
+flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或用 --dir <项目根> 指定）
 ```
 
 输出三类：

package/modules/hosts/codex/commands/wf-test.md

@@ -56,7 +56,7 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 输出测试报告(通过项 / 失败项)
 - 失败项已修复并复测通过
 - **关单**（日常闭环点，不依赖是否上 prod）:
-  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
+  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
   - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
 **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。

package/modules/hosts/cursor/commands/wf-sync-hosts.md

@@ -7,7 +7,10 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 # Sync-Hosts · 跨宿主适配层正文段同步
 
 > 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
-> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
+> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）；**修漂移用同一条命令**
+> `flow-kit sync-hosts --apply`——2026-10-07 起按**目标根**自动判布局（含 `templates/_agents` + `modules/hosts` → 包源：
+> 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
+> 目标根取 `--dir <目录>` > 当前目录。
 
 ## 何时跑
 
@@ -21,8 +24,9 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 ### 默认 `--diff`（仅报告）
 
 ```
-node bin/flow-kit.mjs sync-hosts --diff
-node bin/flow-kit.mjs sync-hosts --json   # 机器可读
+node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
+node bin/flow-kit.mjs sync-hosts --json      # 机器可读
+flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或用 --dir <项目根> 指定）
 ```
 
 输出三类：

package/modules/hosts/cursor/commands/wf-test.md

@@ -56,7 +56,7 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 输出测试报告(通过项 / 失败项)
 - 失败项已修复并复测通过
 - **关单**（日常闭环点，不依赖是否上 prod）:
-  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
+  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
   - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
 **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。

package/modules/hosts/opencode/commands/wf-sync-hosts.md

@@ -7,7 +7,10 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 # Sync-Hosts · 跨宿主适配层正文段同步
 
 > 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
-> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
+> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）；**修漂移用同一条命令**
+> `flow-kit sync-hosts --apply`——2026-10-07 起按**目标根**自动判布局（含 `templates/_agents` + `modules/hosts` → 包源：
+> 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
+> 目标根取 `--dir <目录>` > 当前目录。
 
 ## 何时跑
 
@@ -21,8 +24,9 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 ### 默认 `--diff`（仅报告）
 
 ```
-node bin/flow-kit.mjs sync-hosts --diff
-node bin/flow-kit.mjs sync-hosts --json   # 机器可读
+node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
+node bin/flow-kit.mjs sync-hosts --json      # 机器可读
+flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或用 --dir <项目根> 指定）
 ```
 
 输出三类：

package/modules/hosts/opencode/commands/wf-test.md

@@ -56,7 +56,7 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 输出测试报告(通过项 / 失败项)
 - 失败项已修复并复测通过
 - **关单**（日常闭环点，不依赖是否上 prod）:
-  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
+  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
   - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
 **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。

package/modules/hosts/trae/commands/wf-sync-hosts.md

@@ -8,7 +8,10 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 # Sync-Hosts · 跨宿主适配层正文段同步
 
 > 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
-> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
+> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）；**修漂移用同一条命令**
+> `flow-kit sync-hosts --apply`——2026-10-07 起按**目标根**自动判布局（含 `templates/_agents` + `modules/hosts` → 包源：
+> 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
+> 目标根取 `--dir <目录>` > 当前目录。
 
 ## 何时跑
 
@@ -22,8 +25,9 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 ### 默认 `--diff`（仅报告）
 
 ```
-node bin/flow-kit.mjs sync-hosts --diff
-node bin/flow-kit.mjs sync-hosts --json   # 机器可读
+node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
+node bin/flow-kit.mjs sync-hosts --json      # 机器可读
+flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或用 --dir <项目根> 指定）
 ```
 
 输出三类：

package/modules/hosts/trae/commands/wf-test.md

@@ -57,7 +57,7 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 输出测试报告(通过项 / 失败项)
 - 失败项已修复并复测通过
 - **关单**（日常闭环点，不依赖是否上 prod）:
-  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
+  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
   - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
 **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow-kit",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
   "type": "module",
   "scripts": {

package/src/cli.mjs

@@ -52,7 +52,9 @@ init 选项（全部可选，均有默认值）：
   --force              覆盖已存在的同名文件（默认保守跳过）
 
 sync / add-host 选项：--dir <目录>、--force（覆盖本地已改 / 已装内容）；add-gate 选项：--dir <目录>、--force。
-sync-hosts 选项：--diff（默认，仅报告，不修改）/ --apply（单向同步到薄适配）/ --json（机器可读输出）。
+sync-hosts 选项：--diff（默认，仅报告，不修改）/ --apply（单向同步到薄适配）/ --json（机器可读输出）/ --dir <目录>（目标项目根，默认当前目录）。
+sync-hosts 双布局（2026-10-07）：包源仓（含 templates/_agents + modules/hosts）比对 templates/_agents ↔ modules/hosts；
+装户仓（含 .agents）比对 .agents ↔ 各宿主目录（.opencode/.trae/.omp/.zcode…）——同一命令两处都可用。
 
 示例：
   npx agentic-flow-kit init                        # 交互模式：宿主 → 技术栈 → 端口 → 确认安装

package/src/sync-hosts.mjs

@@ -45,17 +45,19 @@ function listMd(dir) {
 // pairsFor：权威源文件 → 薄适配 rel 列表（映射单源见 profiles.mjs#HOSTS.commandPrefix）
 //   commands 权威源 → 带 commandPrefix 的宿主各一份（<dir>/commands/<prefix><name>.md）
 //   roles    权威源 → 全部宿主 agents 各一份
-function pairsFor(authRel) {
+// hostDirOf：宿主 → 适配目录名。包源布局 = 宿主键（modules/hosts/opencode/…）；装户布局 = HOSTS[h].dir
+// （项目根下 .opencode/…，带点）——2026-10-07 sync-hosts-target-fix 加装户支持时引入。
+function pairsFor(authRel, hostDirOf = (h) => h) {
   const out = [];
   const norm = authRel.split(path.sep).join('/');
   if (norm.startsWith('commands/') && norm.endsWith('.md')) {
     const name = norm.slice('commands/'.length, -'.md'.length);
     for (const [h, v] of Object.entries(HOSTS)) {
-      if (v.commandPrefix) out.push({ adapterRel: `${h}/commands/${v.commandPrefix}${name}.md` });
+      if (v.commandPrefix) out.push({ adapterRel: `${hostDirOf(h)}/commands/${v.commandPrefix}${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` });
+    for (const h of Object.keys(HOSTS)) out.push({ adapterRel: `${hostDirOf(h)}/agents/${name}.md` });
   }
   return out;
 }
@@ -63,12 +65,13 @@ function pairsFor(authRel) {
 // diffHosts：权威源正文段 vs 薄适配正文段的漂移分析（B-b 语义；pure function）。
 // authorityRoot：权威源根（含 commands/ + roles/）
 // adaptersRoot：薄适配根（含 <h>/{agents,commands}/）
+// hostDirOf：宿主 → 适配目录名（默认宿主键 = 包源布局；装户布局传 (h) => HOSTS[h].dir）
 // 返回：{ drift, inSync, authorityMissing, adapterOrphans, note }
-//   drift       = 正文段 sha 不一致（权威源改 / 薄适配手改 都计入；不区分方向）
-//   inSync      = 正文段 sha 对齐的文件对数
-//   authorityMissing = 权威源声明但薄适配文件不存在（apply 不自动创建——薄适配须经 add-host 接管）
-//   adapterOrphans   = 薄适配存在但权威源无对应文件（apply 不删——可能是宿主特化或历史残留）
-export function diffHosts({ authorityRoot, adaptersRoot }) {
+// drift = 正文段 sha 不一致（权威源改 / 薄适配手改 都计入；不区分方向）
+// inSync = 正文段 sha 对齐的文件对数
+// authorityMissing = 权威源声明但薄适配文件不存在（apply 不自动创建——薄适配须经 add-host 接管）
+// adapterOrphans = 薄适配存在但权威源无对应文件（apply 不删——可能是宿主特化或历史残留）
+export function diffHosts({ authorityRoot, adaptersRoot, hostDirOf = (h) => h }) {
   if (!fs.existsSync(authorityRoot)) return { drift: [], inSync: 0, authorityMissing: [], adapterOrphans: [], note: `权威源根不存在：${authorityRoot}` };
 
   const drift = [];
@@ -83,14 +86,16 @@ export function diffHosts({ authorityRoot, adaptersRoot }) {
       const authRel = `${sub}/${f}`;
       const authAbs = path.join(authorityRoot, authRel);
       const authSha = bodySha(authAbs);
-      const pairs = pairsFor(authRel);
+      const pairs = pairsFor(authRel, hostDirOf);
       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 });
+          // 未安装的宿主不算「缺失」——那是没装，不是漂移（2026-10-07：装户只装部分宿主时，
+          // 旧行为会把未装宿主的全部适配文件列成 authorityMissing，装户 --apply 恒 exit 1 且刷屏）
+          if (fs.existsSync(path.dirname(adapterAbs))) authorityMissing.push({ authRel, adapterRel });
           continue;
         }
         if (authSha === adapterSha) { inSync++; continue; }
@@ -103,9 +108,9 @@ export function diffHosts({ authorityRoot, adaptersRoot }) {
   const adapterOrphans = [];
   for (const h of Object.keys(HOSTS)) {
     for (const sub of ['agents', 'commands']) {
-      const subAbs = path.join(adaptersRoot, h, sub);
+      const subAbs = path.join(adaptersRoot, hostDirOf(h), sub);
       for (const f of listMd(subAbs)) {
-        const adapterRel = `${h}/${sub}/${f}`;
+        const adapterRel = `${hostDirOf(h)}/${sub}/${f}`;
         if (adapterSeen.has(adapterRel)) continue;
         let authGuess;
         const prefix = HOSTS[h] && HOSTS[h].commandPrefix;
@@ -168,24 +173,42 @@ function applyForward({ authorityRoot, adaptersRoot }, drift) {
 export function syncHosts(args, pkgRoot) {
   let apply = false;
   let json = false;
-  for (const a of args) {
+  let dir = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
     if (a === '--diff') apply = false;
     else if (a === '--apply') apply = true;
     else if (a === '--json') json = true;
+    else if (a === '--dir') { dir = args[++i]; if (!dir) fail('--dir 缺少参数（目标项目根）'); }
     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 });
+  // 目标根：--dir > cwd > pkgRoot（兜底）。
+  // 2026-10-07 sync-hosts-target-fix：此前恒用 pkgRoot——装户里跑 `flow-kit sync-hosts` 时 pkgRoot
+  // 解析为**包安装目录**，于是 doctor §7.x 报漂移、照提示跑 `--apply` 会去改包源仓（装户自己的适配层纹丝不动）。
+  const target = path.resolve(dir || process.cwd() || pkgRoot);
+  // 布局判定（与 doctor.checkAdapterDrift 同口径）：
+  //   包源（templates/_agents 与 modules/hosts 同时存在）→ 权威源 = <target>/templates/_agents，薄适配根 = <target>/modules/hosts
+  //   装户（其余）→ 权威源 = <target>/.agents，薄适配根 = <target>（宿主目录 .opencode/.trae/… 直接位于项目根）
+  const isSourceRepo = fs.existsSync(path.join(target, 'templates', '_agents'))
+    && fs.existsSync(path.join(target, 'modules', 'hosts'));
+  const authorityRoot = isSourceRepo ? path.join(target, 'templates', '_agents') : path.join(target, '.agents');
+  const adaptersRoot = isSourceRepo ? path.join(target, 'modules', 'hosts') : target;
+  if (!fs.existsSync(authorityRoot)) {
+    fail(`未找到权威源目录：${authorityRoot}——目标根 ${target} 既非包源（无 templates/_agents）也非装户（无 .agents）；用 --dir <项目根> 指定`);
+  }
+  const layout = isSourceRepo ? '包源' : '装户';
+  // 适配目录名：包源 = 宿主键（modules/hosts/opencode/…）；装户 = HOSTS[h].dir（项目根下 .opencode/…）
+  const hostDirOf = isSourceRepo ? (h) => h : (h) => (HOSTS[h] && HOSTS[h].dir) || h;
+  const result = diffHosts({ authorityRoot, adaptersRoot, hostDirOf });
 
   if (apply && result.drift.length > 0) {
     const { synced } = applyForward({ authorityRoot, adaptersRoot }, result.drift);
-    console.log(`▶ flow-kit sync-hosts --apply → ${pkgRoot}`);
+    console.log(`▶ flow-kit sync-hosts --apply → ${target}（${layout}布局）`);
     console.log(`  按权威源正文覆盖薄适配正文段 ${synced.length} 份（薄适配 frontmatter 不动）：`);
     for (const rel of synced) console.log(`    - ${rel}`);
-    const after = diffHosts({ authorityRoot, adaptersRoot });
+    const after = diffHosts({ authorityRoot, adaptersRoot, hostDirOf });
     console.log(`  同步后正文对齐：${after.inSync} 对；权威源缺失：${after.authorityMissing.length}；正文漂移：${after.drift.length}`);
     return after.drift.length === 0 && after.authorityMissing.length === 0 ? 0 : 1;
   }
@@ -193,7 +216,7 @@ export function syncHosts(args, pkgRoot) {
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   } else {
-    console.log(`▶ flow-kit sync-hosts --diff → ${pkgRoot}`);
+    console.log(`▶ flow-kit sync-hosts --diff → ${target}（${layout}布局）`);
     printDiff(result);
   }
   return 0;

package/src/sync-hosts.test.mjs

@@ -1,9 +1,10 @@
 // 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 不自动创建
+// 判据：①全对齐 → inSync=28, drift 空 ②权威源改 → drift 列 ③apply → 正文一致，frontmatter 各自保留
+// ④薄适配 frontmatter 手改 → 不进 drift ⑤薄适配正文手改 → drift 列，apply 覆盖
+// ⑥薄适配缺失 → authorityMissing 列；apply 不自动创建
+// ⑦--json ⑧孤儿薄适配 ⑨装户布局（--dir / cwd 指向装户根 → 按 .agents ↔ 宿主目录比对）
 // 用法：node src/sync-hosts.test.mjs
 import fs from 'node:fs';
 import path from 'node:path';
@@ -66,13 +67,25 @@ function mkFixture() {
 }
 
 // ---- 子进程 driver：调真实 sync-hosts ----
-function runSyncHosts(fixtureRoot, extra = []) {
+// 2026-10-07 起 sync-hosts 目标根 = --dir > cwd > pkgRoot，故测试必须用 --dir 锁定 fixture，
+// 否则会落到「跑测试时所在的仓库」（实仓 = 包源，会把断言全带偏）。
+function runSyncHosts(fixtureRoot, extra = [], opts = {}) {
   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' });
+  return spawnSync(process.execPath, [driver, '--dir', fixtureRoot, ...extra], { encoding: 'utf8', ...opts });
+}
+
+// 不传 --dir 形态：把 cwd 设为 fixture（验「默认当前目录」解析；装户布局靠 cwd 判定）
+function runSyncHostsByCwd(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', cwd: fixtureRoot });
 }
 
 // ============ 场景 1：全对齐（正文段与权威源一致，frontmatter 各异）→ drift 空 ============
@@ -179,9 +192,44 @@ syncHosts(process.argv.slice(2), root);
   check('S8 apply 不删孤儿薄适配', fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/orphan.md')) && fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/wf-legacy.md')));
 }
 
+// ============ 场景 9：装户布局（.agents 为权威源 + 宿主目录为薄适配，无 templates/modules）============
+// 2026-10-07 sync-hosts-target-fix：此前目标根恒为 pkgRoot（= 包安装目录），装户跑 sync-hosts
+// 会去改包源仓。本场景钉住「--dir / cwd 指向装户根 → 按装户布局比对」。
+{
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-synchosts-inst-'));
+ W(path.join(root, '.agents/commands/test.md'),
+ `---\ndescription: Test 阶段\n---\n\n# Test · v2\n\n权威源正文 test v2\n`);
+ W(path.join(root, '.opencode/commands/wf-test.md'),
+ `---\ndescription: Test · opencode\n---\n\n# Test · v1\n\n旧正文 test v1\n`);
+ W(path.join(root, '.trae/commands/wf-test.md'),
+ `---\nname: wf-test\ndescription: Test · trae\n---\n\n# Test · v1\n\n旧正文 test v1\n`);
+
+ // 9a：--dir 指向装户根 → 布局判定「装户」，列出 2 处漂移
+ const r1 = runSyncHosts(root, ['--diff']);
+ const out1 = r1.stdout + r1.stderr;
+ check('S9 装户布局：--dir 指向装户根 → 头部标「装户布局」', /装户布局/.test(out1), out1);
+ check('S9 装户布局：列出 2 处正文漂移', /正文段漂移（2/.test(out1), out1);
+ // 未装宿主（claude/cursor/codex）目录不存在 → 不算「缺失」（否则装户刷屏 + apply 恒 exit 1）
+ check('S9 装户布局：未装宿主不进「权威源声明但薄适配缺失」', !/权威源声明但薄适配缺失/.test(out1), out1);
+
+ // 9b：不传 --dir（cwd = 装户根）→ 同样命中装户布局（旧行为会误指包源）
+ const r2 = runSyncHostsByCwd(root, ['--diff']);
+ const out2 = r2.stdout + r2.stderr;
+ check('S9 cwd 默认：装户布局解析正确（不再误指包源）', /装户布局/.test(out2) && !/包源布局/.test(out2), out2);
+
+ // 9c：apply → 正文段对齐、薄适配 frontmatter 保留
+ const r3 = runSyncHosts(root, ['--apply']);
+ const out3 = r3.stdout + r3.stderr;
+ const bodyOf = (p) => { const t = R(p); const m = t.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/); return t.slice(m ? m[0].length : 0); };
+ check('S9 装户布局 apply：opencode 正文段对齐', bodyOf(path.join(root, '.opencode/commands/wf-test.md')) === bodyOf(path.join(root, '.agents/commands/test.md')), out3);
+ check('S9 装户布局 apply：trae frontmatter 保留（name: wf-test）', /^---\nname: wf-test/m.test(R(path.join(root, '.trae/commands/wf-test.md'))), out3);
+ // 未装宿主不计缺失 → apply 摘要「权威源缺失：0」且 exit 0
+ check('S9 装户布局 apply：未装宿主不计缺失 → 权威源缺失 0 且 exit 0', /权威源缺失：0/.test(out3) && r3.status === 0, `status=${r3.status}\n${out3}`);
+}
+
 {
-  const pkg = path.resolve(SRC_ROOT, '..');
-  const r = diffHosts({
+ const pkg = path.resolve(SRC_ROOT, '..');
+ const r = diffHosts({
     authorityRoot: path.join(pkg, 'templates', '_agents'),
     adaptersRoot: path.join(pkg, 'modules', 'hosts'),
   });

package/templates/_agents/commands/sync-hosts.md

@@ -20,7 +20,10 @@ next: .agents/commands/build.md（漂移属 build 改权威源未同步导致的
 # Sync-Hosts · 跨宿主适配层正文段同步
 
 > 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
-> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
+> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）；**修漂移用同一条命令**
+> `flow-kit sync-hosts --apply`——2026-10-07 起按**目标根**自动判布局（含 `templates/_agents` + `modules/hosts` → 包源：
+> 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
+> 目标根取 `--dir <目录>` > 当前目录。
 
 ## 何时跑
 
@@ -34,8 +37,9 @@ next: .agents/commands/build.md（漂移属 build 改权威源未同步导致的
 ### 默认 `--diff`（仅报告）
 
 ```
-node bin/flow-kit.mjs sync-hosts --diff
-node bin/flow-kit.mjs sync-hosts --json   # 机器可读
+node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
+node bin/flow-kit.mjs sync-hosts --json      # 机器可读
+flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或用 --dir <项目根> 指定）
 ```
 
 输出三类：