@nathan33/nao-skill 0.11.0 → 0.12.1

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)
@@ -21,7 +22,7 @@
 #   NAO_TMUX_LAYOUT=main-row2|main-col|grid   tmux 布局（默认 main-row2）
 #   NAO_TMUX_MAIN_WIDTH=<10..90>             主 pane 宽度百分比（默认 35；main-row2/main-col 共用）
 #   NAO_TMUX_MIN_PANE_WIDTH=<10..80>         最小非主 pane 列宽守卫（默认 30；低于则回退）
-#   NAO_SKILLS=<dir>                          角色卡根目录（默认 <脚本>/../..）
+#   NAO_SKILLS=<dir>                          nao 机制包根目录（默认 <脚本>/../..；项目内 shim 会显式指向包根）
 #   NAO_MODEL_WHITELIST=<glob,...>            -m 白名单（默认空=不校验，支持 glob）
 #   NAO_CLOSE_BUSY_PATTERN=<ERE>             close 的在跑 turn 判定正则（默认内置 pi 状态行标记）
 #   NAO_TASKS_STATE=<path>                   任务状态文件（默认 docs/tasks-state.md，供残留检测/回收闸门）
@@ -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
@@ -824,7 +878,7 @@ build_system_prompt() {
   f="$(mktemp "/tmp/nao-fleet-$(basename "$card" .md)-XXXXXX.md")"
   {
     cat "$card"
-    printf '\n## 环境锚点\n- NAO_SKILLS=%s（@.agents/... 引用以会话 cwd 解析；cwd 无 .agents 时以 NAO_SKILLS 为根拼接绝对路径）\n' "$SKILLS_DIR"
+    printf '\n## 环境锚点\n- NAO_SKILLS=%s（nao 机制**包根**；@.agents/... 引用一律以 `$NAO_SKILLS/.agents/` 为根解析。注意：项目内 `.agents/` 只有 shim，不存机制副本）\n' "$SKILLS_DIR"
   } > "$f"
   echo "$f"
 }
@@ -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

@@ -0,0 +1,41 @@
+---
+name: nao-fleet
+description: nao 多角色 AI 开发舰队的单一入口。当用户要在当前项目启用/运行 nao 工作流时加载——按角色拉起 6 个常驻会话（pm / arch-designer / rd-fe / rd-be / qa / rd-infra）、跑机制体检 check、迁移旧版安装。本 skill 只做入口与说明书：加载后按指引调用项目内 `.agents/scripts/nao-fleet.sh`（shim）；角色卡仍由 fleet 以 `--append-system-prompt` 常驻注入，不由 skill 承载。
+---
+
+# nao 舰队入口
+
+nao 是一套「多角色 AI 开发舰队」：6 个分工明确的常驻会话（PM 拆需求/派活/验收，前端、后端、测试、架构、工程基座各自干活），用户只回答问题、点确认。
+
+## 何时加载
+
+- 用户要在当前项目**启用 nao 工作流**（立项、拆任务、派活、验收、发版）。
+- 用户要**拉起舰队**或查看会话状态。
+- 用户要**迁移旧版 nao 安装**（项目内平铺 `.agents/` → 包内单一来源 + 项目 shim）。
+
+## 机制在哪（单一事实来源）
+
+机制全部在 **nao 机制包内**，项目内只有 shim。包根由环境锚点 `$NAO_SKILLS` 给出（fleet 注入到会话系统提示）：
+
+- 角色清单：`$NAO_SKILLS/.agents/roles.yaml`（6 角色，id 即 intercom 会话名）
+- 角色卡：`$NAO_SKILLS/.agents/prompts/<card>.md`
+- 按需技能：`$NAO_SKILLS/.agents/skills/*.md`
+- 交付清单：`$NAO_SKILLS/.agents/checklists/<role>.md`
+- 协作协议 / 输出规范：`$NAO_SKILLS/.agents/common/`
+
+> 若 `$NAO_SKILLS` 未设置（普通会话），按本 SKILL.md 所在包解析（本文件位于 `<包根>/.agents/skills/nao-fleet/SKILL.md`，包根 = 本文件上两级）。
+
+## 怎么用
+
+1. **体检**：`bash .agents/scripts/nao-fleet.sh check`（exit=0 即可开工；非 0 看报告）。
+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 就位）。
+
+## 硬约束（勿违反）
+
+- **BR1**：角色仍是 6 个独立会话；本 skill 不合并角色。
+- **BR2**：角色卡必须继续由 fleet `--append-system-prompt` 常驻注入；**不得**改用 skill / prompt 按需加载。
+- 项目根 `AGENTS.md` 是项目级单一事实来源（PM 维护，pi 自动注入），本 skill 不复制其内容。
+- 机制自身零网络；shim 只用 node resolve 定位包，不调用 `pi`/`npm` 可执行文件。

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

@@ -36,6 +36,9 @@
 
 ## 指针（勿复制内容）
 
-- 团队级协议/角色清单：`$NAO_SKILLS/.agents/common/` + `.agents/roles.yaml`
+> 项目内 `.agents/` **只有 shim**（`.agents/scripts/nao-fleet.sh`）；机制单一事实来源在 **nao 机制包**内，包根由 `NAO_SKILLS` 给出（fleet 注入到会话系统提示）。所有机制引用一律以 `$NAO_SKILLS/.agents/` 为根解析。
+
+- 团队级协议/角色清单：`$NAO_SKILLS/.agents/common/` + `$NAO_SKILLS/.agents/roles.yaml`
 - 角色卡：`$NAO_SKILLS/.agents/prompts/`
 - 按需技能：`$NAO_SKILLS/.agents/skills/`
+- 交付清单：`$NAO_SKILLS/.agents/checklists/`

package/README.md

@@ -18,16 +18,29 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
 ## 安装（1 分钟）
 
-```bash
-npm install -g @nathan33/nao-skill
-cd 你的项目
-nao-skill install            # 装 .agents/ 并生成 AGENTS.md（已有则提示按规则追加，不覆盖原文）
-nao-skill plugins install-all   # 装协作插件（intercom 等），多会话派活必需
-```
+> 前置依赖：[pi](https://pi.dev)。没装 pi 也能看到这套文件，但跑不起来舰队。
 
-升级用 `nao-skill update`（机制文件以包为准，你自己的改动会保留）。
+1. **把机制装进项目**（项目级，版本 pin 在仓库里，团队 clone 即得同款）：
 
-> 前置依赖：[pi](https://pi.dev)。没装 pi 也能看到这套文件，但跑不起来舰队。
+   ```bash
+   cd 你的项目
+   pi install --local npm:@nathan33/nao-skill@0.12.0   # 声明 pin + 把机制包物化到项目内 .pi/npm
+   npx @nathan33/nao-skill init                        # 写入转发 shim + 生成 AGENTS.md
+   ```
+
+2. **装协作插件**（多会话派活必需）：
+
+   ```bash
+   npx @nathan33/nao-skill plugins install-all
+   ```
+
+升级：改 `.pi/settings.json` 里的 pin 版本，再 `pi update --extensions`（机制以包为准，项目里只有 shim）。
+
+**老项目迁移**（曾在项目里铺开整套 `.agents/` 的）：
+
+```bash
+npx @nathan33/nao-skill migrate   # 旧文件备份到 .agents/.nao-obsolete/，shim 就位，旧命令照跑
+```
 
 ## 用起来（3 步）
 
@@ -36,6 +49,8 @@ nao-skill plugins install-all   # 装协作插件（intercom 等），多会话
 .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
@@ -66,11 +81,11 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 装上 [`pi-agent-qqbot`](https://github.com/Nathan3303) 并配好 `~/.pi/agent/pi-agent-qqbot.json`（`appId` / `clientSecret` / `ownerOpenId` / `sandbox`）后，PM 可把**关键节点**主动推到你 QQ——批次进度汇总、验收结论、发版或合并完成、异常阻塞：
 
 ```bash
-.agents/scripts/qq-notify "[T301] 验收通过 · PR #4 已合并 · v0.8.0"
-.agents/scripts/qq-notify --dry-run "连通性自检"      # 只取 token、不发送
+$NAO_SKILLS/.agents/scripts/qq-notify "[T301] 验收通过 · PR #4 已合并 · v0.8.0"
+$NAO_SKILLS/.agents/scripts/qq-notify --dry-run "连通性自检"      # 只取 token、不发送
 ```
 
-**为什么默认不主动打扰**：这是**可选能力**——没配 `pi-agent-qqbot` 就自动视为未启用；四类节点之外不发，一个节点最多一条（禁刷屏）；推送失败只记回执行风险项，**不阻断交付**。默认走 sandbox（测试环境），正式发布通知才考虑 prod。能力边界、退出码与纪律见 `.agents/skills/qq-notify.md`。
+**为什么默认不主动打扰**：这是**可选能力**——没配 `pi-agent-qqbot` 就自动视为未启用；四类节点之外不发，一个节点最多一条（禁刷屏）；推送失败只记回执行风险项，**不阻断交付**。默认走 sandbox（测试环境），正式发布通知才考虑 prod。能力边界、退出码与纪律见 `$NAO_SKILLS/.agents/skills/qq-notify.md`。
 
 ## 为什么它省 token（这是本项目的核心追求）
 
@@ -85,13 +100,13 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 
 ## 常见问题
 
-**会改我的代码库吗？** 只新增 `.agents/` 和项目根 `AGENTS.md`（已存在则在末尾追加一小段，可手动删掉回退），不碰你原有文件。
+**会改我的代码库吗？** 只会新增项目根 `AGENTS.md`、`.pi/settings.json`，以及一个转发入口 `.agents/scripts/nao-fleet.sh`；角色卡、清单、技能这些机制文件都在依赖包内，**不再铺进你的仓库**，也不碰你原有文件。
 
 **只能用 pi 吗？** 角色卡和技能本质就是 Markdown，Claude Code 等也能读；但"派活 / 回执"这种多会话协作依赖 pi + pi-intercom 插件。
 
 **它会在 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`。
 
@@ -103,37 +118,51 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 你的项目/
 ├── AGENTS.md              # 项目级约定（PM 维护，AI 每次都会读）
 ├── .github/               # PR 模板（PM 建，GitHub Flow 用）
+├── .pi/
+│   ├── settings.json      # 记录机制包的 pin 版本（进仓库）
+│   └── npm/               # pi 把机制包物化在这里（pi 自建 gitignore，不提交）
 └── .agents/
-    ├── prompts/           # 6 张角色卡
-    ├── common/            # 协作规矩、输出与回执规范
-    ├── checklists/        # 各角色红线 / 交付清单 / 回执模板（按需读）
-    ├── skills/            # 按需技能（DDD 细节、代码定位、提交规范…）
-    ├── templates/         # 项目接入用的骨架文件
-    └── scripts/           # nao-fleet.sh 等小工具
+    └── scripts/
+        └── nao-fleet.sh    # 转发入口（shim）：自动定位包内机制并转发
 ```
 
-**同步后在 fmt 校验里看到 `.agents/` 的格式差异？** 这是已知的**发布形态**，不是缺陷——`.agents/**` 以上游原始存储形态发布，**不要就地格式化**（会破坏下游同步的 sha 一致性校验）。完整约定见下一节。
+机制本体（6 张角色卡、协作规矩、清单、按需技能、小工具）都在 npm 包 `@nathan33/nao-skill` 的 `.agents/` 里——**包里是什么就是什么**，项目里不留副本。
+
+## 发布形态与完整性判据（0.12 起有变化）
+
+**从 0.12 起，机制不再铺进项目**：项目里只留一个转发入口，机制的**单一事实来源**是 npm 包 `@nathan33/nao-skill` 内的 `.agents/`。
+
+- **旧的完整性判据已失效**：以前下游靠「项目内 `.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 为准**。
+- **fmt 边界**：包内 `.agents/**` 仍以上游原始存储形态发布（部分 YAML / Markdown / MTS 未按 oxfmt / prettier 归一）。迁移期仍持有旧版全套 `.agents/**` 的仓库，继续把 `.agents/**` 排除出 fmt 校验即可，⛔ **不要为过 fmt 就地格式化**；新形态项目内只有转发入口，无需再处理。
+
+### 物化与离线（CI / 无 pi 环境必读）
 
-## `.agents/` 的发布形态（fmt 边界）
+- `.pi/npm/` 由 pi 管理并 **gitignore**。因此 **fresh clone 上没有 `.pi/npm/package.json` 与 lockfile**，`npm ci --prefix .pi/npm` 当前**不可用**。
+- 物化只有一条路：**显式执行** `pi install -l --approve npm:@nathan33/nao-skill@<pin>`（需要 pi 与网络，是有意为之的一步）。
+- **联动条款**：若某个仓库想把机制体检 `check` 放进 CI（即改变「下游 CI 零改动」的约定），**必须同时**用 `git add -f` 把 `.pi/npm/package.json`、`.pi/npm/package-lock.json` 纳入版本控制，`npm ci` 才有输入。
+- **pi 启动的隐式安装**：当 `.pi/npm/node_modules` 缺失时，pi 启动会隐式执行 `npm install --prefix .pi/npm --legacy-peer-deps`；离线且缓存为空会得到可读的 npm 报错，并让 pi 以非 0 退出（不会静默假装成功）。
+- **运行纪律**：**先显式物化，再 `PI_OFFLINE=1` 运行**。nao 机制自身（转发入口 / fleet / CLI / check）**零网络调用**；入口找不到机制包时不静默成功，而是 `exit 2` 并打印一行 `DEGRADED:` + 恢复命令。
 
-**`.agents/**` 的发布形态 = 本仓库里的原始存储形态**：其中部分 YAML / Markdown / MTS 未按 oxfmt / prettier 归一（实测命中如 `.agents/roles.yaml`、`.agents/scripts/intercom-probe.mts`）。因此下游把 `.agents/**` 纳入完整格式化校验（`vp check`、`prettier --check`、`oxfmt --check`…）时会看到几处格式差异——**属已知形态，不是缺陷**。
+## 下游仓库迁移（nao-todo / nao-todo-server / nue-ui）
 
-- **⛔ 不要为了通过 fmt 而格式化 `.agents/**`。** 下游同步的**唯一完整性判据**是「**脚本与上游逐字节 sha 一致**」（跨仓同步正是靠它证明机制文件没漏没改）；一旦就地格式化，sha 不再相等，同步完整性就无法再证明。规避方式二选一：把 `.agents/**` 排除出 fmt 校验范围，或接受这几处差异。
-- **类型安全另有保障**：`.agents/scripts/**/*.mts|ts` 由本仓 `npm run check:agents`（strict `tsc`，配置 `tsconfig.agents.json`）把关，并已串入 `test` 与 `prepack` ⇒ **每次发布前必过**。这来自 `0.9.4` 的教训（`DEF-66`）：探针 2 处 `TS7006` 曾让下游 TS 仓（nao-todo / nue-ui）required `check` 变红，`0.9.5` 修复并把该自检固化在上游。
-- **变更纪律**：将来若要「上游统一格式化」，必须作为**一次明确的基线变更**执行——改形态 + 通知**全部下游**重同步 + 说明 sha 基线变化；**不得顺手格式化**。
+- **迁移期零改动**：旧的全套 `.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/**`）。
 
 ## 想深入
 
-README 只讲怎么用。真正的机制都在上面那个 `.agents/` 里，想改就从这几处入手：
+README 只讲怎么用。真正的机制都在依赖包 `@nathan33/nao-skill` 的 `.agents/` 里（会话里以 `$NAO_SKILLS/.agents/` 指向），想改就从这几处入手：
 
 | 想看什么 | 去哪看 |
 | --- | --- |
 | 整体架构、分层与设计取舍 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
-| 派活 / 回执 / 忙闲与回收规矩 | `.agents/common/intercom-protocol.md` |
-| 输出格式与回执红线 | `.agents/common/output-format.md`、`.agents/checklists/comm-templates.md` |
-| 角色怎么定义 | `.agents/prompts/*.md` |
-| 各角色的红线与交付清单 | `.agents/checklists/*.md` |
-| 工具命令 | `bash .agents/scripts/nao-fleet.sh --help` |
+| 派活 / 回执 / 忙闲与回收规矩 | `$NAO_SKILLS/.agents/common/intercom-protocol.md` |
+| 输出格式与回执红线 | `$NAO_SKILLS/.agents/common/output-format.md`、`$NAO_SKILLS/.agents/checklists/comm-templates.md` |
+| 角色怎么定义 | `$NAO_SKILLS/.agents/prompts/*.md` |
+| 各角色的红线与交付清单 | `$NAO_SKILLS/.agents/checklists/*.md` |
+| 工具命令 | `bash .agents/scripts/nao-fleet.sh --help`（转发入口） |
 | 项目自己的约定 | 项目根 `AGENTS.md` |
 
 ## License

package/bin/nao-skill.js

@@ -17,8 +17,9 @@
  *   bash .agents/scripts/nao-fleet.sh check / ensure arch rd-fe rd-be qa rd-infra
  *   角色卡经 fleet 拉起时 --append-system-prompt 注入；checklists 按需读取
  */
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import {
+  chmodSync,
   cpSync,
   existsSync,
   mkdirSync,
@@ -28,17 +29,32 @@ import {
   rmSync,
   statSync,
 } from 'node:fs';
-import { join, resolve, basename } from 'node:path';
+import { join, resolve, basename, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const PKG = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url));
 const SRC = fileURLToPath(new URL('../.agents', import.meta.url));
 const TEMPLATE_AGENTS = fileURLToPath(new URL('../.agents/templates/AGENTS.md.example', import.meta.url));
+const SHIM_SRC = fileURLToPath(new URL('./shim/nao-fleet.sh', import.meta.url));
 
 // 已知废弃路径（相对项目根）：旧版遗留，update 时备份后移除
 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'];
+const LEGACY_TOP_FILES = ['roles.yaml'];
+const LEGACY_SCRIPT_FILES = ['nao-fleet.sh', 'intercom-probe.mts', 'qq-notify', 'ui-tokens-check.sh'];
+const LEGACY_SKILL_ENTRIES = [
+  'nao-fleet', 'frontend-design',
+  'arch-patterns.md', 'backend-ddd-details.md', 'codegraph.md', 'commit.md',
+  'frontend-ddd-details.md', 'github-flow.md', 'pm-grill.md', 'pm-operations.md',
+  'pm-rice.md', 'pm-routing.md', 'qq-notify.md', 'research.md', 'test-design.md',
+];
 
 const log = (...a) => console.log('[nao-skill]', ...a);
 const warn = (...a) => console.error('[nao-skill]', ...a);
@@ -218,23 +234,271 @@ function detectObsolete(target) {
   return OBSOLETE.filter((p) => existsSync(join(target, p)));
 }
 
+// ---------------------------------------------------------------------------
+// shim（项目内转发层）：定位包内机制，不复制机制副本
+// ---------------------------------------------------------------------------
+function shimContent() {
+  return readFileSync(SHIM_SRC, 'utf8');
+}
+
+function installShim(target, verbose) {
+  const dir = join(target, '.agents', 'scripts');
+  mkdirSync(dir, { recursive: true });
+  const dst = join(dir, 'nao-fleet.sh');
+  const content = shimContent();
+  const changed = !existsSync(dst) || readFileSync(dst, 'utf8') !== content;
+  if (changed) writeFileSync(dst, content);
+  chmodSync(dst, 0o755);
+  if (verbose) log(`  shim ${changed ? 'write' : 'same '}  .agents/scripts/nao-fleet.sh`);
+  return changed;
+}
+
+function writeVersion(target) {
+  mkdirSync(join(target, '.agents'), { recursive: true });
+  writeFileSync(join(target, VERSION_FILE), PKG.version);
+}
+
+function hasNaoPackageDeclared(target) {
+  try {
+    const s = JSON.parse(readFileSync(join(target, '.pi', 'settings.json'), 'utf8'));
+    return (s.packages || []).some((p) => String(p).startsWith(`npm:${PKG.name}`));
+  } catch {
+    return false;
+  }
+}
+
+// 旧版全套安装探测：返回命中的已知 nao 资产（相对项目根）
+// 注意：shim-only 项目里 .agents/scripts/nao-fleet.sh 就是 shim，不算旧版资产
+function isShimFile(p) {
+  try { return readFileSync(p, 'utf8').includes('NAO_SHIM_ENTERED'); } catch { return false; }
+}
+
+function detectLegacyAssets(target) {
+  const hits = [];
+  for (const d of LEGACY_TOP_DIRS) if (existsSync(join(target, '.agents', d))) hits.push(`.agents/${d}/`);
+  for (const f of LEGACY_TOP_FILES) if (existsSync(join(target, '.agents', f))) hits.push(`.agents/${f}`);
+  for (const f of LEGACY_SCRIPT_FILES) {
+    const p = join(target, '.agents', 'scripts', f);
+    if (!existsSync(p)) continue;
+    if (f === 'nao-fleet.sh' && isShimFile(p)) continue;
+    hits.push(`.agents/scripts/${f}`);
+  }
+  for (const e of LEGACY_SKILL_ENTRIES) if (existsSync(join(target, '.agents', 'skills', e))) hits.push(`.agents/skills/${e}`);
+  return hits;
+}
+
+// ---------------------------------------------------------------------------
+// init：干净项目 —— 写 shim + AGENTS.md（不复制机制；机制在 .pi/npm 包内）
+// ---------------------------------------------------------------------------
+function init(target, force, verbose) {
+  const legacy = detectLegacyAssets(target);
+  if (legacy.length) {
+    if (!force) {
+      warn('检测到旧版全套 .agents/ 安装（机制副本）：');
+      for (const p of legacy) warn(`  - ${p}`);
+      warn('请先运行 `nao-skill migrate`（备份到 .agents/.nao-obsolete/ + 就位 shim），勿直接 init。');
+      process.exit(1);
+    }
+    // F2：--force 不得绕过迁移守卫（否则 shim 覆盖 + 旧副本残留 = 混装，违 BR5/AC1 双注册）
+    log('init --force 检测到旧版 .agents/：改走 migrate（备份 + 精准移除 + shim），避免混装。');
+    return migrate(target, true, verbose);
+  }
+  installShim(target, verbose);
+  writeVersion(target);
+  if (!hasNaoPackageDeclared(target)) {
+    warn(`未在 .pi/settings.json 发现 npm:${PKG.name} 声明；请先执行 pi install --local npm:${PKG.name}@<pin>。`);
+  }
+
+  const agentsMd = join(target, 'AGENTS.md');
+  if (!existsSync(agentsMd)) {
+    let tpl = readFileSync(TEMPLATE_AGENTS, 'utf8');
+    tpl = tpl.replaceAll('<项目名>', basename(resolve(target)));
+    writeFileSync(agentsMd, tpl);
+    log('已生成 AGENTS.md（项目级上下文，PM 维护；保持精简 <120 行）。');
+  } else {
+    warn('AGENTS.md 已存在：按 PM 卡 §七 合并规则手动追加「nao 舰队接入」区块，勿覆盖原文。');
+  }
+
+  log('');
+  log('✔ 初始化完成（项目内仅 shim，机制在 .pi/npm 包内）。下一步：');
+  log('  bash .agents/scripts/nao-fleet.sh check     # 体检');
+  log('  bash .agents/scripts/nao-fleet.sh ensure pm arch-designer rd-fe rd-be qa rd-infra');
+}
+
+// ---------------------------------------------------------------------------
+// migrate：旧版全套安装 → 精准备份 .agents/.nao-obsolete/ + 移除 + shim 就位
+// ---------------------------------------------------------------------------
+function backupAndRemove(target, rel, stamp, verbose) {
+  const src = join(target, rel);
+  if (!existsSync(src)) return false;
+  const bak = join(target, '.agents', '.nao-obsolete', stamp, rel.replace(/^\.agents\//, ''));
+  mkdirSync(join(bak, '..'), { recursive: true });
+  const isDir = statIsDir(src);
+  cpSync(src, bak, { recursive: true });
+  rmSync(src, { recursive: isDir, force: true });
+  if (verbose) log(`  backup+remove ${rel} → .agents/.nao-obsolete/${stamp}/`);
+  return true;
+}
+
+// 共享目录精准删除：只删已知 nao 资产（保留项目其它 skill / 脚本）
+function migrateLegacy(target, stamp, verbose) {
+  const removed = [];
+  const rem = (rel) => { if (backupAndRemove(target, rel, stamp, verbose)) removed.push(rel); };
+  for (const d of LEGACY_TOP_DIRS) rem(`.agents/${d}`);
+  for (const f of LEGACY_TOP_FILES) rem(`.agents/${f}`);
+  for (const f of LEGACY_SCRIPT_FILES) {
+    // shim-only 项目里 nao-fleet.sh 是 shim，不是旧版资产 —— 不备份不移除
+    if (f === 'nao-fleet.sh' && isShimFile(join(target, '.agents', 'scripts', f))) continue;
+    rem(`.agents/scripts/${f}`);
+  }
+  for (const e of LEGACY_SKILL_ENTRIES) rem(`.agents/skills/${e}`);
+  const obsolete = join(target, '.agents', 'skills', 'checklists');
+  if (existsSync(obsolete)) rem('.agents/skills/checklists');
+  return removed;
+}
+
+// 文本级移除 JSON 对象的某个属性：仅删该属性所占字节，其余字节（含缩进/空白）不变
+function findJsonValueEnd(s, i) {
+  const ch = s[i];
+  if (ch === '{' || ch === '[') {
+    const close = ch === '{' ? '}' : ']';
+    let depth = 0, inStr = false, esc = false;
+    for (let k = i; k < s.length; k++) {
+      const c = s[k];
+      if (inStr) {
+        if (esc) esc = false;
+        else if (c === '\\') esc = true;
+        else if (c === '"') inStr = false;
+        continue;
+      }
+      if (c === '"') { inStr = true; continue; }
+      if (c === ch) depth++;
+      else if (c === close) { depth--; if (depth === 0) return k + 1; }
+    }
+    return -1;
+  }
+  if (ch === '"') {
+    let esc = false;
+    for (let k = i + 1; k < s.length; k++) {
+      const c = s[k];
+      if (esc) esc = false;
+      else if (c === '\\') esc = true;
+      else if (c === '"') return k + 1;
+    }
+    return -1;
+  }
+  const m = /^[^,\s}\]\n]+/.exec(s.slice(i));
+  return m ? i + m[0].length : -1;
+}
+
+function removeJsonProperty(raw, key) {
+  const re = new RegExp(`"${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"\\s*:`);
+  const m = re.exec(raw);
+  if (!m) return null;
+  let vs = m.index + m[0].length;
+  while (vs < raw.length && /\s/.test(raw[vs])) vs++;
+  const ve = findJsonValueEnd(raw, vs);
+  if (ve < 0) return null;
+  // 本属性所在行的起始位置（仅当该行确以 "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++;
+  // 是否还有后续属性（值后跟逗号）
+  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;
+}
+
+// §12-C：nao 包为唯一来源 —— 移除 skills-lock.json 里重复的 frontend-design 条目（原文件先备份）
+// F1：文本级删除单条，保留原缩进与其余字节（4 空格 / 2 空格均不重排）
+function stripLockDuplicate(target, stamp, verbose) {
+  const lock = join(target, 'skills-lock.json');
+  if (!existsSync(lock)) return false;
+  const raw = readFileSync(lock, 'utf8');
+  let data;
+  try { data = JSON.parse(raw); } catch { return false; }
+  if (!data.skills || !data.skills['frontend-design']) return false;
+  const next = removeJsonProperty(raw, 'frontend-design');
+  if (next == null) return false;
+  try {
+    const parsed = JSON.parse(next);
+    if (!parsed.skills || 'frontend-design' in parsed.skills) return false;
+  } catch { return false; }
+  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;
+}
+
+function migrate(target, force, verbose) {
+  const legacy = detectLegacyAssets(target);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  if (!legacy.length) {
+    log('未发现旧版全套 .agents/ 机制副本；按 init 处理。');
+    return init(target, force, verbose);
+  }
+  log(`迁移：发现 ${legacy.length} 处旧版 nao 资产，备份到 .agents/.nao-obsolete/${stamp}/ 后移除。`);
+  const removed = migrateLegacy(target, stamp, verbose);
+  stripLockDuplicate(target, stamp, verbose);
+  installShim(target, 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 ...');
+}
+
+// ---------------------------------------------------------------------------
+// exec：CI / 脚本用 —— 定位本包真实 nao-fleet.sh 并转发（不依赖 pi/npm）
+// ---------------------------------------------------------------------------
+function execFleet(args) {
+  const target = join(PKG_ROOT, '.agents', 'scripts', 'nao-fleet.sh');
+  if (!existsSync(target)) {
+    warn(`包内机制脚本缺失：${target}`);
+    process.exit(2);
+  }
+  const r = spawnSync('bash', [target, ...args], {
+    stdio: 'inherit',
+    env: { ...process.env, NAO_SKILLS: PKG_ROOT, NAO_SHIM_ENTERED: '1' },
+  });
+  process.exit(r.status ?? 1);
+}
+
 function help() {
-  console.log(`nao-skill v${PKG.version} — nao 多角色 AI 开发舰队安装器
+  console.log(`nao-skill v${PKG.version} — nao 多角色 AI 开发舰队（pi 原生分发）
 
 用法:
-  nao-skill install [dir] [--force] [-v]   安装/合并 .agents/ 到目标项目（默认当前目录；-v 显示每文件过程）
-  nao-skill install --plugins [-v]         项目接入时顺带安装 pi 舰队插件
-  nao-skill update [dir] [-v]              升级已有安装：源优先覆盖 + 清理废弃路径 + 保留项目自定义
+  nao-skill init [dir] [-v]           干净项目：写 shim + AGENTS.md（机制留在 .pi/npm 包内）
+  nao-skill migrate [dir] [-v]        迁移旧版全套 .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）
   nao-skill plugins install-all       安装全部舰队插件
   nao-skill --version                 显示版本
   nao-skill --help                    显示本帮助
 
-安装内容: 角色卡(prompts/) · 技能(skills/) · 交付清单(checklists/) · 协作协议(common/) ·
-          roles.yaml · 工具链(scripts/) · 模板(templates/) · AGENTS.md 生成/合并提示
+兼容（旧流程，建议迁移到 init/migrate）:
+  nao-skill install [dir] [--force]   复制全套 .agents/ 到项目（--plugins 顺带装插件）
+  nao-skill update [dir]              源优先覆盖升级旧版全套安装
 
-说明: 目标项目已有同名文件时默认保留（--force 覆盖）；AGENTS.md 已存在时按合并规则手动追加。
+安装后: bash .agents/scripts/nao-fleet.sh check / ensure pm arch-designer rd-fe rd-be qa rd-infra
+说明: 新形态项目内只有 shim；机制单一事实来源在 npm 包内（pi install --local 物化到 .pi/npm）。
 `);
 }
 
@@ -249,6 +513,26 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
   console.log(PKG.version);
 } else if (cmd === '--help' || cmd === '-h' || cmd === 'help' || !cmd) {
   help();
+} else if (cmd === 'init' || cmd === 'migrate') {
+  let target = process.cwd();
+  let force = false;
+  let verbose = 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] === '--target') target = resolve(rest[++i]);
+    else if (!rest[i].startsWith('-')) target = resolve(rest[i]);
+    else { warn(`未知参数: ${rest[i]}`); process.exit(2); }
+  }
+  if (!statIsDir(target)) {
+    warn(`目标目录无效: ${target}`);
+    process.exit(2);
+  }
+  if (cmd === 'init') init(target, force, verbose);
+  else migrate(target, force, verbose);
+} else if (cmd === 'exec') {
+  execFleet(args.slice(1));
 } else if (cmd === 'install' || cmd === 'i') {
   let target = process.cwd();
   let force = false;
@@ -298,6 +582,6 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
   }
   update(target, verbose);
 } else {
-  warn(`未知命令: ${cmd}（可用: install, update, plugins）`);
+  warn(`未知命令: ${cmd}（可用: init, migrate, exec, install, update, plugins）`);
   process.exit(2);
 }

package/bin/shim/nao-fleet.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# =============================================================================
+# nao-fleet.sh — 项目内兼容 shim（nao 机制包才是单一事实来源）
+#
+# 作用：定位 nao 机制包根，并把全部参数原样转发给包内
+#       `<包根>/.agents/scripts/nao-fleet.sh`。
+#
+# 解析序（D6）：
+#   1) NAO_SKILLS（显式）—— 直接采用（须含 .agents/scripts/nao-fleet.sh）
+#   2) 项目 .pi/npm（pin 主）—— 遍历 .pi/settings.json 的 npm 声明，node resolve
+#      出「含 nao 机制」的包，版本须与声明一致
+#   3) ~/.pi/agent/npm —— 仅当版本与 pin 完全一致时采用
+#   4) 显式失败（exit 2 + 单行 DEGRADED:）
+# 约定：按机制存在性识别包，**不硬编码包名**。
+#
+# 防重入（D7，双防护）：
+#   ① 环境标记 NAO_SHIM_ENTERED=1 已存在 ⇒ 立即失败（防 shim→shim 递归）
+#   ② 解析出的包根 == shim 自身所属项目根 ⇒ 立即失败（防自指）
+#
+# 纪律：nao 机制自身零网络；本 shim 只用 node resolve，不调用 pi / npm 可执行文件。
+# 生成：由 `nao-skill init` / `nao-skill migrate` 写入，勿手工编辑。
+# =============================================================================
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENTS_DIR="$(cd "$SHIM_DIR/.." && pwd)"
+PROJ_ROOT="$(cd "$AGENTS_DIR/.." && pwd)"
+SETTINGS="$PROJ_ROOT/.pi/settings.json"
+GLOBAL_MOD="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/npm/node_modules"
+
+DEGRADED_HINT='恢复：在项目根执行 `pi install -l --approve npm:@nathan33/nao-skill@<pin>`（或运行 pi 让其自动物化），再重试'
+
+degrade() {
+  printf 'DEGRADED: %s；%s\n' "$1" "$DEGRADED_HINT" >&2
+  exit 2
+}
+
+# D7①：标记命中即失败（防递归；也防 stale 导出把 shim 指回自身）
+[[ "${NAO_SHIM_ENTERED:-}" == "1" ]] && degrade "检测到 shim 递归调用（NAO_SHIM_ENTERED=1）"
+
+command -v node >/dev/null 2>&1 || degrade "未找到 node（用于解析机制包根）"
+
+# 在给定 node_modules 里找「含 nao 机制」的包（不硬编码包名）
+# 输出：<包根>\t<已装版本>\t<settings pin 版本>（未命中则空）
+resolve_nao_pkg() { # $1 = node_modules 目录
+  node -e '
+    (() => {
+    const fs = require("fs"), path = require("path");
+    const mod = process.argv[1], settings = process.argv[2];
+    const names = [];
+    try {
+      const s = JSON.parse(fs.readFileSync(settings, "utf8"));
+      for (const raw of (s.packages || [])) {
+        const m = /^npm:(.+?)(?:@([^@/]+))?$/.exec(String(raw));
+        if (!m) continue;
+        let name = m[1], ver = m[2] || "";
+        if (name.startsWith("@") && name.includes("/@")) {
+          const i = name.indexOf("/@");
+          ver = name.slice(i + 2);
+          name = name.slice(0, i);
+        }
+        names.push([name, ver]);
+      }
+    } catch {}
+    for (const [name, pin] of names) {
+      let pj;
+      try { pj = require.resolve(name + "/package.json", { paths: [mod] }); } catch { continue; }
+      const root = path.dirname(pj);
+      let installed = "";
+      try { installed = JSON.parse(fs.readFileSync(pj, "utf8")).version || ""; } catch {}
+      if (!fs.existsSync(path.join(root, ".agents", "scripts", "nao-fleet.sh"))) continue;
+      process.stdout.write(root + "\t" + installed + "\t" + pin);
+      return;
+    }
+    })();
+  ' "$1" "$SETTINGS" 2>/dev/null || true
+}
+
+PKG_ROOT=""
+PIN_VER=""
+
+# 1) 显式 NAO_SKILLS
+if [[ -n "${NAO_SKILLS:-}" ]]; then
+  [[ -d "$NAO_SKILLS" ]] || degrade "NAO_SKILLS 不是目录：$NAO_SKILLS"
+  PKG_ROOT="$(cd "$NAO_SKILLS" && pwd)"
+  [[ -f "$PKG_ROOT/.agents/scripts/nao-fleet.sh" ]] || degrade "NAO_SKILLS 指向的不是 nao 机制包：$PKG_ROOT"
+else
+  # 2) 项目 .pi/npm（pin 主）
+  FOUND="$(resolve_nao_pkg "$PROJ_ROOT/.pi/npm/node_modules")"
+  # 3) ~/.pi/agent/npm（须版本与 pin 一致才采用）
+  if [[ -z "$FOUND" ]]; then
+    CAND="$(resolve_nao_pkg "$GLOBAL_MOD")"
+    if [[ -n "$CAND" ]]; then
+      c_inst="${CAND#*$'\t'}"; c_inst="${c_inst%%$'\t'*}"
+      c_pin="${CAND##*$'\t'}"
+      [[ -n "$c_pin" && "$c_inst" == "$c_pin" ]] && FOUND="$CAND"
+    fi
+  fi
+  [[ -n "$FOUND" ]] || degrade "机制包未物化（.pi/npm 与 ~/.pi/agent/npm 均未找到含 .agents/scripts/nao-fleet.sh 的包）"
+
+  PKG_ROOT="${FOUND%%$'\t'*}"
+  REST="${FOUND#*$'\t'}"
+  INSTALLED="${REST%%$'\t'*}"
+  PIN_VER="${REST#*$'\t'}"
+  if [[ -n "$PIN_VER" && -n "$INSTALLED" && "$INSTALLED" != "$PIN_VER" ]]; then
+    degrade "机制包版本不符（pin=$PIN_VER，实得=$INSTALLED）"
+  fi
+fi
+
+# D7②：包根 != shim 自身所属项目根
+[[ "$PKG_ROOT" != "$PROJ_ROOT" ]] || degrade "解析出的包根与本项目根相同（$PKG_ROOT；shim 自指）"
+
+TARGET="$PKG_ROOT/.agents/scripts/nao-fleet.sh"
+[[ -f "$TARGET" ]] || degrade "机制包缺少 $TARGET"
+
+# 进入包内真实脚本（置标记；NAO_SKILLS=机制包根）
+export NAO_SHIM_ENTERED=1
+export NAO_SKILLS="$PKG_ROOT"
+exec bash "$TARGET" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathan33/nao-skill",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {
@@ -18,10 +18,17 @@
     "skills",
     "multi-agent",
     "pi",
+    "pi-package",
     "claude",
     "design-system",
     "codegraph"
   ],
+  "pi": {
+    "skills": [
+      "./.agents/skills/nao-fleet/SKILL.md",
+      "./.agents/skills/frontend-design/SKILL.md"
+    ]
+  },
   "author": "Nathan Lee",
   "license": "MIT",
   "publishConfig": {