@nathan33/nao-skill 0.10.0 → 0.12.0

package/.agents/checklists/pm.md

@@ -56,7 +56,7 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] Issue 与 `docs/` 双源（正文抄进 Issue，或状态只留平台）？
 - [ ] 未过验收 / 门禁未绿就打 tag 或 release，或 tag 指向非 main 合并提交？（见 `github-flow.md`）
 - [ ] `git push --force` 到 main/共享分支（未经用户明确授权并指明分支）？
-- [ ] release notes 不可读（纯编号/类名/路径），或未落盘 `docs/releases/`？（规范：@.agents/common/release-notes.md —— 面向用户简明版置顶、内部信息下沉、正文不用表格）
+- [ ] release notes 不可读（纯编号/类名/路径），或未落盘 `docs/releases/`？（规范：@.agents/common/release-notes.md —— 面向用户「本次更新」置顶、内部信息下沉、正文不用表格）
 - [ ] 降级（无 `gh` / 无远端）未在 `tasks-state` 与回执中标注？
 
 ## 交付检查清单（完整 36 项）

package/.agents/common/release-notes.md

@@ -11,7 +11,7 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
 
 ## 一、硬约束（必须遵守）
 
-1. **必须有「面向用户的简明版」，且置于正文最前。**
+1. **必须有面向用户的「本次更新」段，且置于正文最前。**
    - GitHub Release 正文 与 仓库 `docs/releases/vX.Y.Z.md` 的**顶部口径一致**（同一份文字、同一版本）。
    - 读者 = **最终用户**，不是开发者；看完前几行就知道「这版对我有什么变化」。
 2. **正文 ⛔ 不得出现内部术语 / 编号。** 一律不写：任务或缺陷编号（`DEF-xx` / `Txxx` / `#123`）、提交哈希、文件名与函数名、内部属性名（如 `aria-disabled` / `dirty`）、测试例数与通过率、守卫名、内部模块名。
@@ -28,9 +28,9 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
 3. **🐛 修好了** —— 修掉的问题（用户视角现象 → 现在）。
 4. **⚠️ 请留意** —— 行为变更 / 需要用户配合的事。
 5. **📦 更小更快** —— 体积 / 性能 / 启动等可感知收益。
-6. **已知但本期未处理** —— 已知问题与后续计划。
-7. **技术细节（可略过）** —— 编号 / 哈希 / 依赖版本 / 门禁数字 / 文档链接。
+6. **技术细节（可略过）** —— 编号 / 哈希 / 依赖版本 / 门禁数字 / 文档链接。
 
+- **已知问题出口**：会影响用户 ⇒ 写入「⚠️ 请留意」；否则下沉「技术细节（可略过）」。
 - **纯内部仓**（无面向用户交付）可省略第 2–5 段的「面向用户」写法，但**结构保留**（仍按「概括 → 变化 → 技术细节」分层）。
 - **排版**：本文件与其他文档同受 @.agents/checklists/deliverable-docs.md 「默认不使用表格」约束 —— release notes 正文尤其不要用表格。
 
@@ -43,10 +43,10 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
 
 ## 四、发布前核对
 
-- [ ] 正文最前有**面向用户的简明版**（用户看得懂）。
+- [ ] 正文最前有面向用户的**「本次更新」**段（用户看得懂）。
 - [ ] 正文**无**编号 / 哈希 / 文件名 / 函数名 / 内部属性名 / 测试例数 / 守卫名 / 内部模块名。
 - [ ] 行为变更写了**用户视角的后果**（不是内部机制）。
-- [ ] 结构完整（一句话 → 变化 → 已知 → 技术细节）；内部信息集中在「技术细节」段。
+- [ ] 结构完整（一句话 → 变化 → 技术细节）；内部信息集中在「技术细节」段。
 - [ ] 正文**未使用表格**（改用有序 / 无序列表；见 @.agents/checklists/deliverable-docs.md）。
 - [ ] `docs/releases/<version>.md` 与 GitHub Release 正文同源。
 
@@ -54,5 +54,5 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
 
 - [ ] 只写内部机制、用户看不懂？
 - [ ] 正文里直接出现编号 / 哈希 / 类名 / 属性名 / 测试例数？
-- [ ] 没有「面向用户简明版」，或它不在最前？
+- [ ] 没有面向用户的「本次更新」段，或它不在最前？
 - [ ] 盘上 release notes 与 Release 正文两处不一致？

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

@@ -21,7 +21,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，供残留检测/回收闸门）
@@ -824,7 +824,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"
 }

package/.agents/skills/github-flow.md

@@ -54,7 +54,7 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 - 门禁：AC 全过 + 验收闭环 + main 门禁全绿 + 工作区干净 + PR 已合并。
 - **优先 `gh`**：`gh release create <tag> --title "<用户可读标题>" --notes-file docs/releases/<version>.md`。
 - 探测：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 **仍可用**，可 `gh api user` 复核）；**不自动 `gh auth login`**（涉用户凭证）。
-- release notes 落盘 `docs/releases/<version>.md`（**写作规范（强约束）：@.agents/common/release-notes.md** —— 面向用户简明版置顶、内部编号 / 文件名 / 属性名一律下沉「技术细节」、正文不用表格；骨架见 @.agents/templates/release-notes.md.example）。
+- release notes 落盘 `docs/releases/<version>.md`（**写作规范（强约束）：@.agents/common/release-notes.md** —— 面向用户「本次更新」置顶、内部编号 / 文件名 / 属性名一律下沉「技术细节」、正文不用表格；骨架见 @.agents/templates/release-notes.md.example）。
 - 回滚：未 push → `git tag -d`；已 push → **不删远端 tag**，改发下一个 PATCH 修正（用户明确要求才删）。
 
 ## 离线 / 无远端降级

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

@@ -24,7 +24,7 @@
 - <命令纪律，如：禁 cat 全文读代码，用 CodeGraph 或 sed 行段>
 - <依赖限制 / 禁止事项>
 - **Git 流程（GitHub Flow）**：一个需求一条分支 `feat/<issue-id>-<slug>`；工作期 `wip()` 小步提交 + 路径级暂存（禁 `git add -A`）；**PM 验收通过后由 RD 在 PR 上 squash 合并**（main = 1 条/需求）；**禁直推 main**。
-- **发布与仓库治理**：PM 负责 Issue / PR 验收评论 / tag / release / `.github/` 模板（优先 `gh`，不可用降级 `git`）；**发版说明写法遵循 `@.agents/common/release-notes.md`**（面向用户简明版置顶、内部信息下沉、正文不用表格）。
+- **发布与仓库治理**：PM 负责 Issue / PR 验收评论 / tag / release / `.github/` 模板（优先 `gh`，不可用降级 `git`）；**发版说明写法遵循 `@.agents/common/release-notes.md`**（面向用户「本次更新」置顶、内部信息下沉、正文不用表格）。
 
 ## 与 nao 机制衔接
 
@@ -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/.agents/templates/release-notes.md.example

@@ -1,11 +1,11 @@
 <!--
   release notes 骨架 —— 复制为 docs/releases/<version>.md 后逐段填空。
   权威规范：@.agents/common/release-notes.md
-  用法：把「面向用户的简明版」放在最前；内部信息一律下沉「技术细节（可略过）」。
+  用法：把面向用户的「本次更新」放在最前；内部信息一律下沉「技术细节（可略过）」。
   ⛔ 自查：正文无编号 / 哈希 / 文件名 / 函数名 / 内部属性名 / 测试例数 / 守卫名 / 内部模块名；正文不要用表格。
 -->
 
-# 简明版（面向用户）
+# 本次更新
 
 **<一句话概括这版最大的变化；用用户能听懂的话。>**
 
@@ -28,10 +28,6 @@
 
 - <体积 / 性能 / 启动等可感知收益>。<!-- 没有就整节删除 -->
 
-## 已知但本期未处理
-
-- <已知问题 + 计划>。<!-- 没有就写「无」 -->
-
 ## 技术细节（可略过）
 
 - 版本号：<包名旧版本 → 新版本>（如涉及多个包，逐条列出）

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 步）
 
@@ -66,11 +79,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,7 +98,7 @@ 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 插件。
 
@@ -103,37 +116,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.10.0",
+  "version": "0.12.0",
   "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": {