agentic-flow-kit 1.2.0 → 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.0",
+  "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 <项目根> 指定）
 ```
 
 输出三类：

package/templates/_agents/commands/test.md

@@ -75,7 +75,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/templates/_agents/scripts/verify.mjs

@@ -10,8 +10,11 @@
 //   （窗口判定/门禁在消费方 confirm-doc 与 check-loop 检查 8）；消费语义 = 「按门跑了 verify 且全绿」，
 //   裸跑 npm test 不落账（对齐引导）。npm test 步骤输出从 inherit 改 pipe 捕获后回放（延迟显示，
 //   关单场景可接受）——仅为 best-effort 抓「合计: PASS n / FAIL n」计数行，抓不到则省略计数键。
+// 装户仓（根目录无 package.json，工程在子目录）下默认 npm test 恒 ENOENT（exit 4058）→ **显式跳过步骤 1**
+// 且**不落测试绿凭证**（凭证语义 = 测试真跑绿，跳过即无凭证，防假绿），并提示用
+// --test-cmd "<项目测试命令>" 指定；显式 --test-cmd 不受此判定影响（2026-10-07 papercut）。
 // 测试：node templates/_agents/scripts/verify.test.mjs（--test-cmd 注入假命令 + CHECK_LOOP_ROOT 注入夹具，不触真实 npm test 与 workflow）
-// 用法：node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"]（--test-cmd 仅供测试注入）
+// 用法：node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"]（--test-cmd 用于测试注入，或在无根 package.json 的装户仓指定项目测试命令）
 import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -19,19 +22,31 @@ import { fileURLToPath } from 'node:url';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
-const testCmd = args.includes('--test-cmd') ? args[args.indexOf('--test-cmd') + 1] : 'npm test';
+const explicitTestCmd = args.includes('--test-cmd') ? args[args.indexOf('--test-cmd') + 1] : null;
+const testCmd = explicitTestCmd ?? 'npm test';
 const checkLoop = path.join(SCRIPT_DIR, 'check-loop.mjs');
 const ROOT = process.env.CHECK_LOOP_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
 
-console.log(`[verify] ▶ 1/2 ${testCmd}`);
-const t = spawnSync(testCmd, { shell: true, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
-if (t.stdout) process.stdout.write(t.stdout);
-if (t.stderr) process.stderr.write(t.stderr);
-if (t.status !== 0) {
-  console.error(`[verify] ❌ 1/2 ${testCmd} 未通过（exit ${t.status ?? t.error?.code}）——修复后重跑，非绿不关单`);
-  process.exit(1);
+// 装户仓判定：默认命令只在**当前目录**有 package.json 时才跑（npm test 亦在该目录执行）。
+// 跳过时后续不落测试绿凭证（见文末落账段）。
+const hasRootPackageJson = fs.existsSync(path.join(process.cwd(), 'package.json'));
+const skipTest = explicitTestCmd === null && !hasRootPackageJson;
+let testStdout = '';
+
+if (skipTest) {
+  console.log('[verify] ⏭ 1/2 跳过 npm test：当前目录无 package.json（装户仓）——请按项目口径手工跑测试，或用 --test-cmd "<项目测试命令>" 指定后重跑');
+} else {
+  console.log(`[verify] ▶ 1/2 ${testCmd}`);
+  const t = spawnSync(testCmd, { shell: true, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  if (t.stdout) process.stdout.write(t.stdout);
+  if (t.stderr) process.stderr.write(t.stderr);
+  if (t.status !== 0) {
+    console.error(`[verify] ❌ 1/2 ${testCmd} 未通过（exit ${t.status ?? t.error?.code}）——修复后重跑，非绿不关单`);
+    process.exit(1);
+  }
+  testStdout = String(t.stdout || '');
+  console.log('[verify] ✅ 1/2 测试通过');
 }
-console.log('[verify] ✅ 1/2 测试通过');
 
 console.log('[verify] ▶ 2/2 check-loop');
 const c = spawnSync(process.execPath, [checkLoop], { stdio: 'inherit' });
@@ -41,15 +56,20 @@ if (c.status !== 0) {
 }
 console.log('[verify] ✅ 2/2 闭环校验通过');
 
-// 凭证落账：两步全绿才落（check-loop 红不产生凭证——凭证语义 = verify 全绿）；IO 失败出账不阻断
+// 凭证落账：两步全绿才落（check-loop 红不产生凭证——凭证语义 = verify 全绿）；**步骤 1 被跳过同样不落**
+// （测试未跑即无「测试绿」事实，落账即假绿）；IO 失败出账不阻断
 try {
-  const m = [...String(t.stdout || '').matchAll(/合计: PASS (\d+) \/ FAIL (\d+)/g)].pop();
-  const entry = { ts: new Date().toISOString(), exitCode: 0, suite: 'npm test' };
-  if (m) { entry.passed = Number(m[1]); entry.failed = Number(m[2]); }
-  if (process.env.PIPELINE_RUN_ID) entry.runId = process.env.PIPELINE_RUN_ID;
-  fs.mkdirSync(path.join(ROOT, '.agents'), { recursive: true });
-  fs.appendFileSync(path.join(ROOT, '.agents', 'verifications.jsonl'), `${JSON.stringify(entry)}\n`);
-  console.log(`[verify] 🧾 测试绿凭证已落账 verifications.jsonl${entry.passed !== undefined ? `（PASS ${entry.passed} / FAIL ${entry.failed}）` : ''}`);
+  if (skipTest) {
+    console.log('[verify] ⚠️ 步骤 1 已跳过——本次不落测试绿凭证（凭证语义 = 测试真跑绿）');
+  } else {
+    const m = [...testStdout.matchAll(/合计: PASS (\d+) \/ FAIL (\d+)/g)].pop();
+    const entry = { ts: new Date().toISOString(), exitCode: 0, suite: 'npm test' };
+    if (m) { entry.passed = Number(m[1]); entry.failed = Number(m[2]); }
+    if (process.env.PIPELINE_RUN_ID) entry.runId = process.env.PIPELINE_RUN_ID;
+    fs.mkdirSync(path.join(ROOT, '.agents'), { recursive: true });
+    fs.appendFileSync(path.join(ROOT, '.agents', 'verifications.jsonl'), `${JSON.stringify(entry)}\n`);
+    console.log(`[verify] 🧾 测试绿凭证已落账 verifications.jsonl${entry.passed !== undefined ? `（PASS ${entry.passed} / FAIL ${entry.failed}）` : ''}`);
+  }
 } catch (e) {
   console.error(`[verify] ⚠️ 凭证落账失败（${e.code || e.message}）——不阻断，关单门前置将按无凭证告警`);
 }

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

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // verify.mjs 的 fixture 测试（--test-cmd 注入假命令 + CHECK_LOOP_ROOT 注入夹具根，不触真实 npm test 与 workflow）
 // 断言：①绿路径（假过 + 空夹具闭环）exit 0；②步骤 1 假败 exit 1 且不出全绿；
-//       ③步骤 2 配对断裂夹具 exit 1（verify 自身标记断言——孙进程 stdio inherit 输出不进本测试管道）。
+// ③步骤 2 配对断裂夹具 exit 1（verify 自身标记断言——孙进程 stdio inherit 输出不进本测试管道）；
+// ④⑤⑥凭证落账三态（绿落 / check-loop 红不落 / 无汇总行省略计数键）；
+// ⑦装户仓（cwd 无 package.json）未给 --test-cmd → 跳过步骤 1、不落凭证、仍跑步骤 2、exit 0。
 // 用法：node templates/_agents/scripts/verify.test.mjs
 import fs from 'node:fs';
 import os from 'node:os';
@@ -116,6 +118,20 @@ const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv],
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 7：装户仓（cwd 无 package.json）且未给 --test-cmd → 跳过步骤 1、不落凭证、仍跑步骤 2 → exit 0 ----
+{
+ const root = mkfix();
+ const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-bare-'));
+ const r = run([], { cwd: bare, env: { ...process.env, CHECK_LOOP_ROOT: root } });
+ check('场景 7：exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+ check('场景 7：步骤 1 显式跳过（⏭ 1/2）、步骤 2 通过且全绿', r.stdout.includes('⏭ 1/2') && r.stdout.includes('✅ 2/2') && r.stdout.includes('全绿'), r.stdout);
+ check('场景 7：跳过时不落测试绿凭证（防假绿）',
+ !fs.existsSync(path.join(root, '.agents', 'verifications.jsonl')) && r.stdout.includes('不落测试绿凭证'),
+ r.stdout);
+ fs.rmSync(root, { recursive: true, force: true });
+ fs.rmSync(bare, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log('\n用法：node templates/_agents/scripts/verify.test.mjs');

package/templates/_agents/skills/verify-ui/SKILL.md

@@ -3,22 +3,59 @@ name: verify-ui
 description: 启动本地服务并用浏览器实测 UI 改动（只读验证、不留脏数据）；项目无测试基建时靠实测兜底。当用户要求"实测 / UI 验证 / 浏览器验证"时使用。
 ---
 
-# verify-ui — UI 实测引导（骨架，项目按实际填「启动命令 / 实测入口」）
+# verify-ui — UI 实测引导
+
+无测试基建时，UI 改动必须浏览器实测。步骤：
 
 ## 1. 起服务
 
-- API：<待填：启动命令（见 .agents/notes/runtime-env.md §2）>
-- 前端：<待填：启动命令>
+启动命令**不写死在本文件**（本文件是 managed 件，随包升级覆盖——项目特定值写这里会丢）：以 `.agents/notes/runtime-env.md`「本地端口与进程」节的记录为准；该节无记录时，先起服务并把命令补记进该文件再继续。
 
 进程清单记进 `.agents/notes/runtime-env.md`，实测结束必须关闭。
 
-## 2. 实测步骤
+## 2. 浏览器验证
+
+- 优先 `browser` 工具；不可用时用 `.agents/scripts/e2e/harness.mjs`（如项目已装；封装 `launch`/`seedSession`/`goto`/`hardGoto`/`clickText`/`pressKey`/`ensureClean`/`screenshot` + 网络/控制台/toast 采集器）；自写脚本优先复用其常量与函数。
+- 浏览器首选**较新的 Chromium 内核 headless**（如 Edge `--headless=new`）——旧版 Chrome 会把 antd 图标字体渲染成方框、表格 `waitFor` 超时（见下「浏览器选择」）。
+- 登录态：先调 API 登录拿 token，注入前端约定的 localStorage 键，**并整页重载**让前端状态库重读 token（仅改 hash 的导航不重建文档，会被路由守卫弹回登录页）。
+- 路由为 hash 模式时：`goto` 用 hash；深链接（query 变化）用 `hardGoto`（about:blank 中转强制新文档）。
+
+## 3. 实测步骤
 
 1. 打开目标页面，按改动点逐项操作：正常路径一条 + 失败路径一条（校验/空态/权限）。
 2. 证据落盘：截图或关键控制台/网络报文，路径写在任务文档「验收标准」勾验项后。
-3. 不留脏数据：验证产生的临时数据当场删除或还原；不确定可回滚的操作先停下问用户。
+3. **不留脏数据**：验证产生的临时数据当场删除或还原；清理**只按本次创建的 ID 精确删除**（ID 取自网络捕获的 POST 响应），**禁止按文案/字段模糊匹配**——模糊匹配会误删用户手建数据；清理脚本一律先备份再删；不确定可回滚的操作先停下问用户。
 
-## 3. 收尾
+## 4. 收尾
 
 - 关闭本次起动的全部进程（按 §1 清单逐个停）。
 - 结论按「页面 / 步骤 / 期望 vs 实际 / 证据」回报；发现缺陷只记录定性，不修代码（修复走 build/maintain 流程）。
+
+## 关键坑
+
+- API 用 **HTTP** 避开自签证书问题（HTTPS 自签证书会让浏览器/脚本报错或需额外信任配置）。
+- MCP 报「browser is already running」是残留实例占 MCP 专用 profile 锁（`~/.cache/chrome-devtools-mcp/`），清掉对应 chrome 进程重试即可，勿误判为 MCP 不可用。
+- 布局类修复用 `getBoundingClientRect` 程序化检测，比截图肉眼更可靠。
+- 后台任务生命周期不可依赖（实测可长可短）：长命服务一律独立进程起（如 PowerShell `Start-Process`）。
+- 用 shell 工具起长命服务时**勿在命令末尾接管道**（`| tail` 等）——子进程继承 stdout 句柄会让命令永不返回，直到被工具超时杀掉（并可能连带杀掉服务）。
+
+### 浏览器选择
+
+- 旧版 Chrome（实测 83）内核太旧 → antd 图标字体全渲染成方框、表格 `waitFor` 超时。**优先较新的 Chromium 内核**（如 Edge `--headless=new`）；harness 的 `CHROME` 常量按本机实际安装路径改。
+
+### antd 交互（JS `.click()` 不够）
+
+- 按钮文本内含空格（`确 定` / `保 存` / `取 消`）→ 匹配须去空白，勿用 `innerText === '确定'`。
+- Select / Picker / Dropdown 的 `.click()` 打不开弹层 → 须 `Input.dispatchMouseEvent`（mousedown+mouseup 序列）；普通按钮用 `clickText` 够用，弹层控件须补 `realClick`。
+- `new KeyboardEvent('Escape')` 关不掉弹层 → 须 `Input.dispatchKeyEvent`（rawKeyDown+keyUp）。
+- **关弹层慎用 Esc**：antd Drawer 同样响应 Esc，会连带关闭抽屉并 reset 表单（表现为「保存后列表无新行」，易误判为保存链路故障）——改点遮罩/关闭按钮。
+- 表格行常无 `tr[data-row-key]` 属性 → 用 `.ant-table-tbody > tr.ant-table-row` + textContent 过滤业务键（如单号）定位行。
+- 宽表 `:scroll="{x:N}"` 截图前把 `.ant-table-content` scrollLeft 置底，露出右侧列。
+- 虚拟滚动下拉（a-select）DOM 只渲染约 10 个节点 → **勿按 DOM 节点数断言选项条数**，按接口响应条数断言。
+
+### CDP 采集（SPA hash 导航不重建文档）
+
+- Log/Console 采集不随导航重置 → 每次导航前重置采集器，防上一页错误泄漏成后续页面的「控制台错误」。
+- toast 观察器须**导航前**安装；导航后装会漏首屏 toast。
+- 首屏无 token 被路由守卫落登录页：写 localStorage 后仅 hash 变化的 `Page.navigate` 不整页重载、前端状态库仍持空 token → 须 `about:blank` 中转强制新文档，或写后 `Page.reload`。
+- 同路由 hash query 变化不重挂载（`#/x?k=A` → `#/x?k=B`）→ 深链接用例走 `about:blank` 中转。