@nathan33/nao-skill 0.12.0 → 0.13.0

package/.agents/scripts/nao-fleet.sh

@@ -10,8 +10,9 @@
 #   nao-fleet.sh ensure -m <model> <别名>...       显式指定模型（须命中白名单）
 #   nao-fleet.sh ensure --task <编号> <别名>[@<repo>]   任务派生会话：--name <别名>-<编号>（并行隔离，避免同名冲突）
 #   nao-fleet.sh ensure --force <别名>...          忽略"已在运行"判重
-#   nao-fleet.sh close <别名|会话名> [--task <编号>] [--force]
-#                                                 回收已完成会话（闸门：在跑 turn / tasks-state 未推进 → 拒绝，--force 跳过）
+#   nao-fleet.sh close <别名|派生会话名> [--task <编号>] [--force]
+#                                                 回收已完成会话（派生名如 rd-be-T1；跨仓定位；定位失败/名册报在线但无句柄 ⇒ 非 0 + 诊断）
+#                                                 （闸门：在跑 turn / tasks-state 未推进 → 拒绝，--force 跳过）
 #
 # 角色别名 → 角色卡：见 .agents/roles.yaml（单一事实来源）
 #   当前：pm / arch-designer(arch) / rd-fe / rd-be / qa / rd-infra(infra)
@@ -132,7 +133,7 @@ load_manifest() {
   while IFS=$'\t' read -r k v w rest; do
     case "$k" in
       ROLE)  ROLE_ORDER+=("$v"); ROLE_CARDS["$v"]="$w"; ROLE_WS["$v"]="$rest" ;;
-      ALIAS) ALIAS_ROLE["$v"]="$w" ;;
+      ALIAS) ALIAS_ROLE["$w"]="$v" ;;   # 别名 → 角色 id（消费方 resolve_role/close 按此方向取值）
     esac
   done <<< "$out"
 }
@@ -206,6 +207,39 @@ check_roles_indent() {
   ' "$MANIFEST"
 }
 
+# 别名解析守卫（#19）：独立重解析 roles.yaml（不依赖可能被写反的 ALIAS_ROLE），校验
+#   ① 每个声明的别名可解析为「声明它的角色」（对 ALIAS_ROLE 键值方向敏感）
+#   ② 每个角色 canonical id 已登记于 aliases（BR2：canonical 须可解析为自身）
+#   ③ 别名不跨角色重名
+check_alias_resolution() {
+  local rc=0 ga gr
+  local -A owner=()
+  while IFS=$'\t' read -r ga gr; do
+    [[ -n "$ga" && -n "$gr" ]] || continue
+    if [[ -n "${owner[$ga]:-}" && "${owner[$ga]}" != "$gr" ]]; then
+      printf '  ✗ 别名 %s 跨角色重名：%s 与 %s\n' "$ga" "${owner[$ga]}" "$gr"; rc=1
+    fi
+    owner["$ga"]="$gr"
+    if [[ "${ALIAS_ROLE[$ga]:-}" != "$gr" ]]; then
+      printf '  ✗ 别名 %s 解析异常：roles.yaml 声明属 %s，实际解析为 %s（ALIAS_ROLE 键值方向可能反写）\n' \
+        "$ga" "$gr" "${ALIAS_ROLE[$ga]:-<未登记>}"; rc=1
+    fi
+  done < <(awk -F'\t' '
+      /^  [^ ][^:]*:[[:space:]]*$/ { c=$0; sub(/^  /,"",c); sub(/:[[:space:]]*$/,"",c); next }
+      c!="" && /^    aliases:[[:space:]]*\[/ {
+        v=$0; sub(/^    aliases:[[:space:]]*\[/,"",v); sub(/\].*/,"",v)
+        n=split(v, a, /,/)
+        for (i=1;i<=n;i++){ gsub(/^[[:space:]]+|[[:space:]]+$/, "", a[i]); if(a[i]!="") print a[i] "\t" c }
+      }' "$MANIFEST")
+  for gr in "${ROLE_ORDER[@]}"; do
+    if [[ "${owner[$gr]:-}" != "$gr" ]]; then
+      printf '  ✗ 角色 %s 的 canonical id 未登记于 aliases（BR2：canonical 须可解析为自身）\n' "$gr"; rc=1
+    fi
+  done
+  (( rc == 0 )) && printf '  ✓ 别名解析守卫：全部别名可解析且无跨角色重名\n'
+  return $rc
+}
+
 # qq-notify 主动推送器契约：存在 + 可执行 + EOL 全 LF + 无 Tab + node --check 语法
 check_qq_notify() {
   local rc=0 f="$SKILLS_DIR/.agents/scripts/qq-notify"
@@ -372,6 +406,15 @@ intercom_online() {
   return 1
 }
 
+# 名册中该会话的 cwd（跨仓 close 需按目标仓定位；无记录则空）
+intercom_cwd_for() {
+  local n c
+  while IFS=$'\t' read -r n c; do
+    [[ "$n" == "$1" ]] && { printf '%s\n' "$c"; return 0; }
+  done < <(intercom_roster)
+  return 0
+}
+
 # 会话所在的 tmux pane。三层后备（标题可被外部改写，如 "pi:c"）：
 #   ① 终端标题契约 "π - <会话名> - <repo basename>"（pi 自设；最快）
 #   ② pi-intercom 名册 tmuxPane（注册时读 $TMUX_PANE；与标题改名无关，权威）
@@ -484,6 +527,17 @@ find_pane_for() {
   return 0
 }
 
+# 跨仓 pane 定位：不限定 repo（标题任意仓 basename / 名册 tmuxPane 不限 cwd）
+# close 的目标可能在别的仓（roles.yaml workspace 恒为本仓）⇒ 不能用 find_pane_for 的 repo 约束。
+find_pane_for_any_repo() {
+  local name="$1" pane=""
+  pane="$(find_pane_by_title "$name" "")"
+  [[ -n "$pane" ]] && { printf '%s\n' "$pane"; return 0; }
+  pane="$(intercom_pane_for "$name" "")"
+  if [[ -n "$pane" ]] && tmux_pane_live "$pane"; then printf '%s\n' "$pane"; return 0; fi
+  return 0
+}
+
 # 该会话名对应的 pi 进程 PID（经 pane 句柄取 pane_pid 及其子进程中 comm=pi 者）
 pi_pids_for() {
   local pane root pid
@@ -882,6 +936,7 @@ cmd_check() {
   echo "== 角色清单 roles.yaml =="
   load_manifest
   printf '  ✓ 解析成功，%d 个角色: %s\n' "${#ROLE_ORDER[@]}" "${ROLE_ORDER[*]}"
+  check_alias_resolution || rc=1
 
   echo "== 常驻角色卡（阈值 ${CARD_MAX_LINES} 行，frontmatter 校验）=="
   local a role version updated
@@ -1106,14 +1161,39 @@ cmd_status() {
 # ---------------------------------------------------------------------------
 # 回收已完成会话：闸门（tasks-state 已推进 + 无在跑 turn）+ 落地（pane/会话/screen/进程）
 cmd_close() {
-  local force="$1" task="$2" target="$3"
-  [[ -n "$target" ]] || die "close 需要目标：角色别名或派生会话名（如 rd-be / rd-be-T1 或 rd-infra / rd-infra-T1）"
-  local name repo cls bus pane pids r ok st
+  local force="$1" task="$2" target="${3:-}"
+  [[ -n "$target" ]] || die "close 需要目标：角色别名或派生会话名（如 rd-be / rd-be-T1 / qa-T1）"
+  local name repo cls bus pane pids st tgt a best=""
   intercom_list_json >/dev/null 2>&1 || true   # 预热名册缓存
-  if [[ -n "$task" ]]; then
-    resolve_role "$target"
-    name="${NAME}-${task}"
-    repo="${ROLE_WS[$NAME]:-$PWD}"
+
+  # ---- 目标解析：别名/canonical id | 派生会话名 <角色>-<编号> ----
+  # 派生名（如 qa-T508）可直接作目标；也兼容 close --task T508 qa 与 close --task T508 qa-T508。
+  tgt=""
+  if [[ -n "${ALIAS_ROLE[$target]:-}" ]]; then
+    tgt="$target"
+  elif [[ -n "$task" && "$target" == *-"$task" && -n "${ALIAS_ROLE[${target%-"$task"}]:-}" ]]; then
+    tgt="${target%-"$task"}"
+  else
+    # 未带 --task 的派生名：取最长可解析前缀为角色，余下为任务编号
+    for a in "${!ALIAS_ROLE[@]}"; do
+      [[ "$target" == "$a"-* ]] || continue
+      if [[ -z "$best" || ${#a} -gt ${#best} ]]; then best="$a"; fi
+    done
+    if [[ -n "$best" ]]; then tgt="$best"; task="${target#"$best"-}"; fi
+  fi
+  if [[ -z "$tgt" ]]; then
+    die "未知角色或派生会话名: $target（可用角色: ${ROLE_ORDER[*]}；派生名形如 rd-be-T1 / qa-T1，亦可用 close --task <编号> <角色>）"
+  fi
+  resolve_role "$tgt"
+  name="$NAME"
+  [[ -n "$task" ]] && name="${NAME}-${task}"
+  # 目标仓：名册 cwd 优先（跨仓会话真实仓），否则回退 roles.yaml workspace / 当前目录
+  repo="$(intercom_cwd_for "$name")"
+  [[ -n "$repo" ]] || repo="${ROLE_WS[$NAME]:-$PWD}"
+
+  if [[ -z "$task" ]]; then
+    warn "常驻会话 $name：任务闭环后应 ensure --force 重开，而非回收（仅在本批不再需要该角色时回收）"
+  else
     # 闸门①：tasks-state 未推进 → 拒绝（验收未过需原会话返工，回收会丢上下文）
     cls="$(task_state_class "$task")"
     if [[ "$cls" == "active" && "$force" != true ]]; then
@@ -1124,20 +1204,25 @@ cmd_close() {
     [[ "$cls" == "absent" ]] && warn "tasks-state 全文无 $task 记录（仅按会话名回收）"
     [[ "$cls" == "mentioned" ]] && log "tasks-state 仅散文提及 $task（非表内记录，不阻塞回收）"
     [[ "$cls" == "nofile" ]] && log "未启用 $TASKS_STATE（跳过状态闸门）"
-  elif [[ -n "${ALIAS_ROLE[$target]:-}" ]]; then
-    name="${ALIAS_ROLE[$target]}"; repo="${ROLE_WS[$name]:-$PWD}"
-    warn "常驻会话 $name：任务闭环后应 ensure --force 重开，而非回收（仅在本批不再需要该角色时回收）"
-  else
-    name="$target"
-    [[ "$name" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*$ ]] || die "非法会话名: $name"
-    # 非别名的目标必须是 <已知角色>-<编号>，否则视为拼错（防静默 no-op）
-    ok=0
-    for r in "${ROLE_ORDER[@]}"; do [[ "$name" == "$r-"* ]] && ok=1; done
-    (( ok )) || die "未知角色或派生会话名: $name（可用: ${ROLE_ORDER[*]}；派生名形如 rd-be-T1 / rd-infra-T1）"
-    repo="$PWD"
   fi
 
-  if ! running "$name" "$repo"; then
+  # ---- 宿主句柄定位（跨仓）：pane 按标题任意仓 basename / 名册 tmuxPane 不限定 cwd ----
+  pane="$(find_pane_for_any_repo "$name")"
+  if [[ -z "$pane" ]]; then
+    # nao-<会话名> detached tmux / screen 会话（不依赖 repo）
+    if command -v tmux >/dev/null 2>&1 && tmux has-session -t "nao-$name" 2>/dev/null; then
+      if tmux kill-session -t "nao-$name" 2>/dev/null; then log "已回收 $name（tmux 会话 nao-$name）@ $repo"; return 0; fi
+    fi
+    if command -v screen >/dev/null 2>&1 && screen -ls 2>/dev/null | grep -q "nao-$name"; then
+      if screen -S "nao-$name" -X quit 2>/dev/null; then log "已回收 $name（screen 会话 nao-$name）@ $repo"; return 0; fi
+    fi
+    # 无任何可杀句柄：名册若报在线 ⇒ 定位失败，必须非静默（禁止「未运行」而 pane 仍在）
+    if intercom_online "$name"; then
+      warn "无法回收 $name：pi-intercom 名册报在线（cwd=${repo}）但未定位到存活 pane/会话"
+      warn "  标题契约 / 名册 tmuxPane 均未命中；tmuxPane 可能滞后或未注册"
+      warn "  请用 intercom({action:'list'}) 人工核对；确认已退出后忽略，或按 pane_id 手工处理"
+      return 1
+    fi
     if offline_verifiable; then
       log "$name 未运行（无需回收）"; return 0
     fi
@@ -1148,48 +1233,37 @@ cmd_close() {
   fi
 
   # 闸门②：在跑 turn（pane 标记 + roster 状态双重信号）
-  pane="$(find_pane_for "$name" "$repo")"
   bus=""
   # 显式双分支赋值：pane 空闲时 bus 必须落为 ""。
   # 曾用 `pane_busy "$pane" && bus=…`：pane_busy 为假时 && 短路，bus 在 set -u 下未绑定 → 行 1007 崩溃。
-  if [[ -n "$pane" ]] && pane_busy "$pane"; then
+  if pane_busy "$pane"; then
     bus="tmux pane $pane 显示在跑 turn"
   fi
-  st="$(intercom_status_for "$name" "$repo")"
+  st="$(intercom_status_for "$name")"
   if [[ -z "$bus" ]]; then
     case "$st" in
       ""|idle|\?) ;;   # 无状态或空闲 → 不阻塞
       *) bus="pi-intercom 名册状态=$st（在跑 turn）" ;;
     esac
   fi
-  # 既无 pane 也无名册状态 ⇒ 确实无法判定 → 拒绝（不静默 no-op）
-  if [[ -z "$bus" && -z "$pane" && -z "$st" ]]; then
-    if command -v tmux >/dev/null 2>&1; then
-      bus="tmux 宿主但未定位到该会话的 pane（标题契约 / 名册 tmuxPane / 仓库兜底均未命中）"
-    else
-      bus="非 tmux 宿主，无法确认是否在跑 turn"
-    fi
-  fi
   if [[ -n "$bus" && "$force" != true ]]; then
     warn "拒绝回收 $name：$bus"
     warn "  等它停；回执与产物核对见 checklists/pm.md「会话回收 / 收窗核对」（或 --force 强制）"
     return 1
   fi
 
-  if [[ -n "$pane" ]] && tmux kill-pane -t "$pane" 2>/dev/null; then
+  # 回收前以 pane 真实 cwd 校正日志中的仓（名册可能缺记录）
+  local pcwd
+  pcwd="$(tmux display-message -p -t "$pane" '#{pane_current_path}' 2>/dev/null || true)"
+  [[ -n "$pcwd" ]] && repo="$pcwd"
+  if tmux kill-pane -t "$pane" 2>/dev/null; then
     log "已回收 $name（tmux pane $pane）@ $repo"; return 0
   fi
-  if command -v tmux >/dev/null 2>&1 && tmux has-session -t "nao-$name" 2>/dev/null && tmux kill-session -t "nao-$name" 2>/dev/null; then
-    log "已回收 $name（tmux 会话 nao-$name）@ $repo"; return 0
-  fi
-  if command -v screen >/dev/null 2>&1 && screen -ls 2>/dev/null | grep -q "nao-$name" && screen -S "nao-$name" -X quit 2>/dev/null; then
-    log "已回收 $name（screen 会话 nao-$name）@ $repo"; return 0
-  fi
   pids="$(pi_pids_for "$name" "$repo" | tr '\n' ' ')"
   if [[ -n "$pids" ]] && kill $pids 2>/dev/null; then
     log "已回收 $name（结束进程: $pids）@ $repo"; return 0
   fi
-  warn "未找到 $name 的 pane/会话/进程（可能刚好退出）"; return 1
+  warn "已定位到 $name 的 pane $pane 但回收失败（pane 可能刚好退出；核对 pane 已消失后可忽略）"; return 1
 }
 
 # ---------------------------------------------------------------------------

package/.agents/skills/nao-fleet/SKILL.md

@@ -31,7 +31,7 @@ nao 是一套「多角色 AI 开发舰队」：6 个分工明确的常驻会话
 2. **拉起舰队**：`bash .agents/scripts/nao-fleet.sh ensure pm arch-designer rd-fe rd-be qa rd-infra`
    - 任务派生（并行隔离）：`ensure --task <编号> <别名>`
    - 状态 / 回收：`status` / `close --task <编号> <别名>`
-3. **迁移旧版安装**：`npx @nathan33/nao-skill migrate`（旧文件备份到 `.agents/.nao-obsolete/`，shim 就位）。
+3. **迁移旧版安装**：`npx @nathan33/nao-skill migrate`（旧文件备份到 `.agents/.nao-obsolete/`）。是否写 shim 由**判定式**决定（旧脚本 / 已有 shim / 全仓 `nao-fleet|nao-skill|NAO_SKILLS` 引用 ⇒ 写）；纯文档仓判定为跳过并显式告知，可用 `--shim` / `--no-shim` 覆盖。
 
 ## 硬约束（勿违反）
 

package/.agents/templates/AGENTS.md.example

@@ -36,7 +36,7 @@
 
 ## 指针（勿复制内容）
 
-> 项目内 `.agents/` **只有 shim**（`.agents/scripts/nao-fleet.sh`）；机制单一事实来源在 **nao 机制包**内，包根由 `NAO_SKILLS` 给出（fleet 注入到会话系统提示）。所有机制引用一律以 `$NAO_SKILLS/.agents/` 为根解析。
+> 项目内 `.agents/` **只有 shim**（`.agents/scripts/nao-fleet.sh`）；机制单一事实来源在 **nao 机制包**内，包根由 `NAO_SKILLS` 给出（fleet 注入到会话系统提示）。所有机制引用一律以 `$NAO_SKILLS/.agents/` 为根解析。**例外：无脚本、无引用的纯文档仓不建 shim**（迁移判定式自动跳过，可用 `--shim` 覆盖）。
 
 - 团队级协议/角色清单：`$NAO_SKILLS/.agents/common/` + `$NAO_SKILLS/.agents/roles.yaml`
 - 角色卡：`$NAO_SKILLS/.agents/prompts/`

package/README.md

@@ -24,7 +24,7 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
    ```bash
    cd 你的项目
-   pi install --local npm:@nathan33/nao-skill@0.12.0   # 声明 pin + 把机制包物化到项目内 .pi/npm
+   pi install --local npm:@nathan33/nao-skill@0.13.0   # 声明 pin + 把机制包物化到项目内 .pi/npm
    npx @nathan33/nao-skill init                        # 写入转发 shim + 生成 AGENTS.md
    ```
 
@@ -39,9 +39,11 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 **老项目迁移**（曾在项目里铺开整套 `.agents/` 的）：
 
 ```bash
-npx @nathan33/nao-skill migrate   # 旧文件备份到 .agents/.nao-obsolete/，shim 就位，旧命令照跑
+npx @nathan33/nao-skill migrate   # 旧文件备份到 .agents/.nao-obsolete/，再按需写入转发入口
 ```
 
+迁移默认按**判定式**决定是否写转发入口（shim）：仓里还有旧的 `nao-fleet.sh`、或已存在 shim、或全仓有 `nao-fleet` / `nao-skill` / `NAO_SKILLS` 引用，就写；**无脚本、无引用的纯文档仓会被判定跳过**，并打印一行告知。要改变判定结果，显式加 `--shim`（强制写）或 `--no-shim`（强制不写），两者不能同时给（`exit 2`）。旧版的 `.agents/.nao-migrated` 标记**已废弃**：迁移不再读写它，可安全删除。`.agents/.nao-version` 的语义是「本机已安装机制包版本」（供升级检测），**不表达迁移状态**——迁移状态由「是否还有旧资产」推断。
+
 ## 用起来（3 步）
 
 ```bash
@@ -49,6 +51,8 @@ npx @nathan33/nao-skill migrate   # 旧文件备份到 .agents/.nao-obsolete/，
 .agents/scripts/nao-fleet.sh ensure pm arch rd-fe rd-be qa rd-infra   # 拉起 6 个角色会话
 ```
 
+角色名可以写**别名**或**规范名**（两者等价）：`arch` = `arch-designer`、`infra` = `rd-infra`；上例里两者混用也照常拉起。完整别名表见 `.agents/roles.yaml` 或 `nao-fleet.sh --help`。
+
 然后**在 PM 会话里说需求**就行，剩下的它自己流转。大概长这样：
 
 ```text
@@ -104,7 +108,7 @@ $NAO_SKILLS/.agents/scripts/qq-notify --dry-run "连通性自检"      # 只取
 
 **它会在 GitHub 上开 PR 吗？** 会——每个需求一条分支、一个 PR（Draft 早开、CI 早跑），你确认验收后由研发角色 squash 合并，main 上只留 1 条可读提交。没有远端或 `gh` 时降级为本地分支，流程不变。
 
-**跑完的会话要留着吗？** 后台派生会话验收完可以回收：`nao-fleet.sh close --task T1 rd-be`；常驻角色留着复用。`nao-fleet.sh status` 会提示哪些是残留。
+**跑完的会话要留着吗？** 后台派生会话验收完可以回收：`nao-fleet.sh close --task T1 rd-be`（等价写法 `nao-fleet.sh close rd-be-T1`，直接用派生会话名即可）；常驻角色留着复用。`nao-fleet.sh status` 会提示哪些是残留。目标在别的项目里也能回收——`close` 会按名册/窗口标题跨项目定位；定位不到时会**非 0 退出并打印诊断**，不会假装已回收。
 
 **终端窗口太挤怎么办？** tmux 宿主支持三种布局：默认 `main-row2`（主会话占左，其余往右分列）、`main-col`（其余在右列竖排）、`grid`（等大网格）。窗口太窄时 `main-row2` 会**自动回退** `main-col`、仍不够再退 `grid`，并打印带数字的提示（不中断拉起）；用 `NAO_TMUX_LAYOUT` / `NAO_TMUX_MAIN_WIDTH` / `NAO_TMUX_MIN_PANE_WIDTH` 调整，详见 `bash .agents/scripts/nao-fleet.sh --help`。
 
@@ -132,7 +136,7 @@ $NAO_SKILLS/.agents/scripts/qq-notify --dry-run "连通性自检"      # 只取
 
 - **旧的完整性判据已失效**：以前下游靠「项目内 `.agents/**` 与上游逐字节 sha 一致」证明机制没漏没改；现在项目内不再有机制副本，这条判据不再适用。
 - **新的完整性判据：以 pin 的包版本为准**。`.pi/settings.json` 记录版本，`pi install/update` 从包物化；包里是什么就是什么，不存在「项目内被就地改动」的问题。转发入口是生成的固定文本，可用 `npx @nathan33/nao-skill init` 幂等重写核对。
-- **版本权威口径**：`.pi/settings.json` 里的 pin 是**唯一权威**（`pi install/update` 据此物化到 `.pi/npm`）；`.agents/.nao-version` 只是本机安装标记（供升级检测与迁移提示），**不作为版本依据**；两者不一致时**以 pin 为准**。
+- **版本权威口径**：`.pi/settings.json` 里的 pin 是**唯一权威**（`pi install/update` 据此物化到 `.pi/npm`）；`.agents/.nao-version` 的语义是**本机已安装机制包版本**（供升级检测），**不表达迁移状态**、**不作为版本依据**；两者不一致时**以 pin 为准**。
 - **fmt 边界**：包内 `.agents/**` 仍以上游原始存储形态发布（部分 YAML / Markdown / MTS 未按 oxfmt / prettier 归一）。迁移期仍持有旧版全套 `.agents/**` 的仓库，继续把 `.agents/**` 排除出 fmt 校验即可，⛔ **不要为过 fmt 就地格式化**；新形态项目内只有转发入口，无需再处理。
 
 ### 物化与离线（CI / 无 pi 环境必读）
@@ -147,7 +151,7 @@ $NAO_SKILLS/.agents/scripts/qq-notify --dry-run "连通性自检"      # 只取
 
 - **迁移期零改动**：旧的全套 `.agents/scripts/nao-fleet.sh` 照常可用，这些仓库的 CI 目前不调用 `check`，不受影响。
 - 想切到新形态时，在各仓执行 `npx @nathan33/nao-skill migrate`：只删**已知 nao 资产**（共享的 `.agents/skills/` 里项目自有的技能会保留），并把 `skills-lock.json` 里重复的 `frontend-design` 来源收敛为「机制包唯一来源」。
-- **`nao-todo-minimal` 特例**：无脚本、无 nao-fleet 引用 ⇒ **不建转发入口**，按纯文档/指针迁移；它的 `.agents/commands/`、`.agents/prompts/` 不在 pi 的 skill 扫描面（pi 只扫 `.agents/skills/**`）。
+- **纯文档仓（如 `nao-todo-minimal`）特例**：无脚本、无 `nao-fleet`/`nao-skill` 引用 ⇒ 迁移判定为**纯文档迁移，不建转发入口**（可显式 `--shim` 强制；也可 `--no-shim` 强制不建）；它的 `.agents/commands/`、`.agents/prompts/` 不在 pi 的 skill 扫描面（pi 只扫 `.agents/skills/**`）。
 
 ## 想深入
 

package/bin/nao-skill.js

@@ -42,8 +42,6 @@ const SHIM_SRC = fileURLToPath(new URL('./shim/nao-fleet.sh', import.meta.url));
 const OBSOLETE = ['.agents/skills/checklists'];
 // 安装版本标记（install/update 写入，供下次检测升级）
 const VERSION_FILE = '.agents/.nao-version';
-// 迁移一次性提示标记（BR4：每版本最多提示一次）
-const MIGRATED_FILE = '.agents/.nao-migrated';
 
 // 旧版全套安装的已知 nao 资产（迁移时**精准**备份+移除；共享目录不得整目录删）
 const LEGACY_TOP_DIRS = ['prompts', 'common', 'checklists', 'templates'];
@@ -287,10 +285,67 @@ function detectLegacyAssets(target) {
   return hits;
 }
 
+// ---------------------------------------------------------------------------
+// F4 shim 判定式：needsShim = A ∨ A′ ∨ B（Node 实现，无 shell grep / 无网络时间依赖）
+//   A  旧版真脚本存在 · A′ 已存在 shim · B 存在外部调用点
+//   IGNORE = .git/** · node_modules/** · .pi/** · .agents/.nao-obsolete/** · 二进制 · >1MiB
+//   B 额外排除待移除旧资产（legacyAssetPaths）；.pi/** 必须排除，否则已物化仓恒真
+// ---------------------------------------------------------------------------
+const SHIM_SCAN_IGNORE_TOP = new Set(['.git', 'node_modules', '.pi']);
+const SHIM_REF_RE = /nao-fleet|nao-skill|NAO_SKILLS/;
+
+function detectShimNeed(target) {
+  const shim = join(target, '.agents', 'scripts', 'nao-fleet.sh');
+  if (existsSync(shim)) return { needed: true, reason: isShimFile(shim) ? 'shim-present' : 'legacy-script' };
+  const legacyRel = detectLegacyAssets(target);
+  const isLegacyPath = (rel) => legacyRel.some((l) => (l.endsWith('/') ? rel.startsWith(l) : rel === l));
+  const stack = [target];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      const rel = relative(target, p);
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) {
+        if (SHIM_SCAN_IGNORE_TOP.has(rel.split('/')[0]) || e.name === 'node_modules') continue;
+        if (rel === '.agents/.nao-obsolete' || rel.startsWith('.agents/.nao-obsolete/')) continue;
+        stack.push(p);
+        continue;
+      }
+      if (!e.isFile() || isLegacyPath(rel)) continue;
+      let st;
+      try { st = statSync(p); } catch { continue; }
+      if (st.size > 1024 * 1024) continue;
+      let buf;
+      try { buf = readFileSync(p); } catch { continue; }
+      if (buf.includes(0)) continue;   // 二进制（含 NUL 字节）
+      if (SHIM_REF_RE.test(buf.toString('utf8'))) return { needed: true, reason: `reference:${rel}` };
+    }
+  }
+  return { needed: false, reason: 'no-reference' };
+}
+
+function resolveShim(target, mode) {
+  if (mode === 'shim') return { needed: true, reason: 'forced' };
+  if (mode === 'no-shim') return { needed: false, reason: 'forced-off' };
+  return detectShimNeed(target);
+}
+
+function applyShim(target, decision, verbose) {
+  if (decision.needed) { installShim(target, verbose); return; }
+  if (decision.reason === 'forced-off') {
+    warn('按 --no-shim 跳过 shim 安装（项目内将没有 .agents/scripts/nao-fleet.sh；需要时用 --shim 覆盖）。');
+  } else {
+    warn('未发现 nao 脚本/引用 → 判定为纯文档迁移，未写 shim（可用 --shim 强制）。');
+  }
+}
+
 // ---------------------------------------------------------------------------
 // init：干净项目 —— 写 shim + AGENTS.md（不复制机制；机制在 .pi/npm 包内）
 // ---------------------------------------------------------------------------
-function init(target, force, verbose) {
+function init(target, force, verbose, shimMode = 'shim', decision = null) {
   const legacy = detectLegacyAssets(target);
   if (legacy.length) {
     if (!force) {
@@ -301,9 +356,9 @@ function init(target, force, verbose) {
     }
     // F2：--force 不得绕过迁移守卫（否则 shim 覆盖 + 旧副本残留 = 混装，违 BR5/AC1 双注册）
     log('init --force 检测到旧版 .agents/：改走 migrate（备份 + 精准移除 + shim），避免混装。');
-    return migrate(target, true, verbose);
+    return migrate(target, true, verbose, shimMode === 'no-shim' ? 'no-shim' : 'shim');
   }
-  installShim(target, verbose);
+  applyShim(target, decision || resolveShim(target, shimMode), verbose);
   writeVersion(target);
   if (!hasNaoPackageDeclared(target)) {
     warn(`未在 .pi/settings.json 发现 npm:${PKG.name} 声明；请先执行 pi install --local npm:${PKG.name}@<pin>。`);
@@ -399,69 +454,82 @@ function removeJsonProperty(raw, key) {
   while (vs < raw.length && /\s/.test(raw[vs])) vs++;
   const ve = findJsonValueEnd(raw, vs);
   if (ve < 0) return null;
-  // 本属性所在行的起始位置（仅当该行确以 "key" 开头时才做行级删除，防异形格式误伤）
+  // 行级删除（保缩进/其余字节）：仅当该属性独占一行（行首即 key）时适用
   let lineStart = m.index;
   while (lineStart > 0 && raw[lineStart - 1] !== '\n') lineStart--;
   let nl = raw.indexOf('\n', lineStart);
   if (nl === -1) nl = raw.length;
-  if (!raw.slice(lineStart, nl).trim().startsWith(`"${key}"`)) return null;
-  // 本属性值闭合所在行之后（含换行）
-  let lineEnd = ve;
-  while (lineEnd < raw.length && raw[lineEnd] !== '\n') lineEnd++;
-  if (lineEnd < raw.length) lineEnd++;
-  // 是否还有后续属性（值后跟逗号）
+  if (raw.slice(lineStart, nl).trim().startsWith(`"${key}"`)) {
+    // 本属性值闭合所在行之后（含换行）
+    let lineEnd = ve;
+    while (lineEnd < raw.length && raw[lineEnd] !== '\n') lineEnd++;
+    if (lineEnd < raw.length) lineEnd++;
+    // 是否还有后续属性（值后跟逗号）
+    let after = ve;
+    while (after < raw.length && (raw[after] === ' ' || raw[after] === '\t')) after++;
+    if (raw[after] === ',') {
+      return raw.slice(0, lineStart) + raw.slice(lineEnd);
+    }
+    // 末位属性：删本行，并去掉前一属性末尾的逗号
+    let out = raw.slice(0, lineStart) + raw.slice(lineEnd);
+    let p = lineStart;
+    while (p > 0 && /[ \t\r\n]/.test(out[p - 1])) p--;
+    if (out[p - 1] === ',') out = out.slice(0, p - 1) + out.slice(p);
+    return out;
+  }
+  // F7 属性级回退（单行/异形格式）：删「属性 token + 一个分隔逗号」，其余字节不动
   let after = ve;
-  while (after < raw.length && (raw[after] === ' ' || raw[after] === '\t')) after++;
-  if (raw[after] === ',') {
-    return raw.slice(0, lineStart) + raw.slice(lineEnd);
-  }
-  // 末位属性：删本行，并去掉前一属性末尾的逗号
-  let out = raw.slice(0, lineStart) + raw.slice(lineEnd);
-  let p = lineStart;
-  while (p > 0 && /[ \t\r\n]/.test(out[p - 1])) p--;
-  if (out[p - 1] === ',') out = out.slice(0, p - 1) + out.slice(p);
-  return out;
+  while (after < raw.length && /\s/.test(raw[after])) after++;
+  if (raw[after] === ',') return raw.slice(0, m.index) + raw.slice(after + 1);
+  // 末位属性：删前一个分隔逗号 + 本属性 token
+  let p = m.index;
+  while (p > 0 && /[ \t\r\n]/.test(raw[p - 1])) p--;
+  if (raw[p - 1] === ',') return raw.slice(0, p - 1) + raw.slice(ve);
+  return null;
 }
 
 // §12-C：nao 包为唯一来源 —— 移除 skills-lock.json 里重复的 frontend-design 条目（原文件先备份）
 // F1：文本级删除单条，保留原缩进与其余字节（4 空格 / 2 空格均不重排）
+// F7：三态返回 ok | absent | failed；failed 时恰一行 warn（不静默）且不改写
 function stripLockDuplicate(target, stamp, verbose) {
   const lock = join(target, 'skills-lock.json');
-  if (!existsSync(lock)) return false;
+  if (!existsSync(lock)) return 'absent';
   const raw = readFileSync(lock, 'utf8');
   let data;
-  try { data = JSON.parse(raw); } catch { return false; }
-  if (!data.skills || !data.skills['frontend-design']) return false;
+  try { data = JSON.parse(raw); } catch { return 'absent'; }
+  if (!data.skills || !data.skills['frontend-design']) return 'absent';
+  const failWarn = () => warn('skills-lock.json 存在重复 frontend-design，但无法安全文本删除：请手工移除该条目；其余迁移步骤不受影响。');
   const next = removeJsonProperty(raw, 'frontend-design');
-  if (next == null) return false;
+  if (next == null) { failWarn(); return 'failed'; }
   try {
     const parsed = JSON.parse(next);
-    if (!parsed.skills || 'frontend-design' in parsed.skills) return false;
-  } catch { return false; }
+    if (!parsed.skills || 'frontend-design' in parsed.skills) { failWarn(); return 'failed'; }
+  } catch { failWarn(); return 'failed'; }
   const bak = join(target, '.agents', '.nao-obsolete', stamp, 'skills-lock.json');
   mkdirSync(join(bak, '..'), { recursive: true });
   cpSync(lock, bak);
   writeFileSync(lock, next);
   if (verbose) log('  strip  skills-lock.json → 文本级移除 frontend-design（其余字节不变）');
-  return true;
+  return 'ok';
 }
 
-function migrate(target, force, verbose) {
+function migrate(target, force, verbose, shimMode = 'auto') {
   const legacy = detectLegacyAssets(target);
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  // F4 判定式必须在备份/移除之前采样（B 需排除待移除旧资产）
+  const decision = resolveShim(target, shimMode);
+  // B2：去重置于早退判断之前 —— 无 legacy 资产（走 init 路径）时同样生效
+  stripLockDuplicate(target, stamp, verbose);
   if (!legacy.length) {
     log('未发现旧版全套 .agents/ 机制副本；按 init 处理。');
-    return init(target, force, verbose);
+    return init(target, force, verbose, shimMode, decision);
   }
   log(`迁移：发现 ${legacy.length} 处旧版 nao 资产，备份到 .agents/.nao-obsolete/${stamp}/ 后移除。`);
   const removed = migrateLegacy(target, stamp, verbose);
-  stripLockDuplicate(target, stamp, verbose);
-  installShim(target, verbose);
+  applyShim(target, decision, verbose);
   writeVersion(target);
-  mkdirSync(join(target, '.agents'), { recursive: true });
-  writeFileSync(join(target, MIGRATED_FILE), PKG.version);
-  log(`✔ 迁移完成：移除 ${removed.length} 项已知 nao 资产（备份在 .agents/.nao-obsolete/${stamp}/）；shim 已就位。`);
-  log('  旧命令照跑：bash .agents/scripts/nao-fleet.sh check / ensure ...');
+  log(`✔ 迁移完成：移除 ${removed.length} 项已知 nao 资产（备份在 .agents/.nao-obsolete/${stamp}/）。`);
+  if (decision.needed) log('  旧命令照跑：bash .agents/scripts/nao-fleet.sh check / ensure ...');
 }
 
 // ---------------------------------------------------------------------------
@@ -484,8 +552,8 @@ function help() {
   console.log(`nao-skill v${PKG.version} — nao 多角色 AI 开发舰队（pi 原生分发）
 
 用法:
-  nao-skill init [dir] [-v]           干净项目：写 shim + AGENTS.md（机制留在 .pi/npm 包内）
-  nao-skill migrate [dir] [-v]        迁移旧版全套 .agents/：备份 .nao-obsolete/ + 移除 + shim 就位
+  nao-skill init [dir] [-v] [--shim|--no-shim]     干净项目：写 shim + AGENTS.md（默认写）
+  nao-skill migrate [dir] [-v] [--shim|--no-shim]  迁移旧版全套 .agents/：备份 .nao-obsolete/ + 移除 + shim
   nao-skill exec <参数...>            转发给包内 nao-fleet.sh（CI/脚本用；NAO_SKILLS=包根）
   nao-skill plugins list              列出已知 pi 插件与安装状态
   nao-skill plugins install <名...>   安装指定插件（intercom/ask-me/subagents/web-access/codegraph）
@@ -493,6 +561,11 @@ function help() {
   nao-skill --version                 显示版本
   nao-skill --help                    显示本帮助
 
+shim 判定式（migrate 默认；init 默认装）:
+  needsShim = A ∨ A′ ∨ B（Node 扫描，跳过 >1MiB 与二进制，排除 .git/.pi/node_modules/.nao-obsolete）
+    A  旧版真脚本存在 · A′ 已存在 shim · B 全仓有 nao-fleet|nao-skill|NAO_SKILLS 引用（排除待移除旧资产）
+  判定为纯文档迁移时不写 shim，并打印显式告知；用 --shim / --no-shim 覆盖（互斥 → exit 2）
+
 兼容（旧流程，建议迁移到 init/migrate）:
   nao-skill install [dir] [--force]   复制全套 .agents/ 到项目（--plugins 顺带装插件）
   nao-skill update [dir]              源优先覆盖升级旧版全套安装
@@ -517,20 +590,29 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
   let target = process.cwd();
   let force = false;
   let verbose = false;
+  let wantShim = false;
+  let wantNoShim = false;
   const rest = args.slice(1);
   for (let i = 0; i < rest.length; i++) {
     if (rest[i] === '--force' || rest[i] === '-f') force = true;
     else if (rest[i] === '--verbose' || rest[i] === '-v') verbose = true;
+    else if (rest[i] === '--shim') wantShim = true;
+    else if (rest[i] === '--no-shim') wantNoShim = true;
     else if (rest[i] === '--target') target = resolve(rest[++i]);
     else if (!rest[i].startsWith('-')) target = resolve(rest[i]);
     else { warn(`未知参数: ${rest[i]}`); process.exit(2); }
   }
+  if (wantShim && wantNoShim) {
+    warn('--shim 与 --no-shim 互斥，不能同时使用。');
+    process.exit(2);
+  }
   if (!statIsDir(target)) {
     warn(`目标目录无效: ${target}`);
     process.exit(2);
   }
-  if (cmd === 'init') init(target, force, verbose);
-  else migrate(target, force, verbose);
+  const shimMode = wantShim ? 'shim' : wantNoShim ? 'no-shim' : (cmd === 'init' ? 'shim' : 'auto');
+  if (cmd === 'init') init(target, force, verbose, shimMode);
+  else migrate(target, force, verbose, shimMode);
 } else if (cmd === 'exec') {
   execFleet(args.slice(1));
 } else if (cmd === 'install' || cmd === 'i') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathan33/nao-skill",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {