@nathan33/nao-skill 0.12.1 → 0.16.0

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

@@ -34,6 +34,7 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 - **禁止** `git push` 到 main、**禁止绕过 PR 合并**；feature 分支允许 `--force-with-lease`（改基 / 压缩历史时）。
 - 提交规范、`wip()` 前缀、路径级暂存、可读性：见 @.agents/skills/commit.md。
 - **squash 后 main 上的提交信息 = PR 标题 + PR 正文** → **可读性硬性落在 PR 标题**（用户可见行为，禁纯编号/类名/路径）。
+- ⚠️ **单提交 PR 的 squash 陷阱（T511 实测 3/3 仓中招）**：`gh pr merge --squash` 在 PR **只有 1 条提交**时，取的是**该提交的 subject**（**不是** PR 标题）⇒ 分支纪律的 `wip(<编号>):` 前缀会直接进主干。**合并命令必须显式指定**：`gh pr merge <n> --squash --delete-branch --subject "<用户可读主题>" --body "<摘要>"`；或合并前把分支压成一条用户可读提交。主干受保护（禁 force-push / `enforce_admins=true`）时该偏差**不可回溯**，只能记录。
 
 ## Issue 与状态（避免双源）
 

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

@@ -31,7 +31,10 @@ 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 就位）。
+   - 实验场清理：`cleanup -S <隔离socket>`（强制显式 socket；无 `-S`/指向默认 socket ⇒ exit 2 拒绝）
+     ⚠ 实验纪律：实验/夹具一律 `env -u TMUX` + `-S <隔离socket>`——tmux 客户端在 `$TMUX` 已设时
+     无视 `TMUX_TMPDIR`，裸 `tmux`/`kill-server` 会连坐真实 server（T515 两次自灭根因）
+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.14.0   # 声明 pin + 把机制包物化到项目内 .pi/npm
    npx @nathan33/nao-skill init                        # 写入转发 shim + 生成 AGENTS.md
    ```
 
@@ -36,11 +36,7 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
 升级：改 `.pi/settings.json` 里的 pin 版本，再 `pi update --extensions`（机制以包为准，项目里只有 shim）。
 
-**老项目迁移**（曾在项目里铺开整套 `.agents/` 的）：
-
-```bash
-npx @nathan33/nao-skill migrate   # 旧文件备份到 .agents/.nao-obsolete/，shim 就位，旧命令照跑
-```
+**老项目迁移**（曾在项目里铺开整套 `.agents/` 的）：执行 `npx @nathan33/nao-skill migrate` 即可，细则见文末「老用户迁移与维护者注记」。
 
 ## 用起来（3 步）
 
@@ -51,6 +47,8 @@ npx @nathan33/nao-skill migrate   # 旧文件备份到 .agents/.nao-obsolete/，
 
 角色名可以写**别名**或**规范名**（两者等价）：`arch` = `arch-designer`、`infra` = `rd-infra`；上例里两者混用也照常拉起。完整别名表见 `.agents/roles.yaml` 或 `nao-fleet.sh --help`。
 
+**不在 tmux 里也能用**：默认每个角色开一个**看得见的终端窗口**（走 `xdg-terminal-exec`，窗口标识 `org.nao.<角色>`），不是后台黑箱；无图形会话（如 SSH）默认拒绝，需显式 `--background` 才建后台会话，并打印可复制的 `tmux attach` 命令。宿主的完整选择顺序与降级边界见 `nao-fleet.sh --help`。不过我们**推荐装 tmux**——多数能力在 tmux 宿主下体验最完整，理由见下方常见问题。
+
 然后**在 PM 会话里说需求**就行，剩下的它自己流转。大概长这样：
 
 ```text
@@ -76,17 +74,6 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 
 不想要哪个角色，删掉对应文件即可；只留 PM + 一个研发角色也能跑。
 
-## 可选：关键节点 QQ 主动推送
-
-装上 [`pi-agent-qqbot`](https://github.com/Nathan3303) 并配好 `~/.pi/agent/pi-agent-qqbot.json`（`appId` / `clientSecret` / `ownerOpenId` / `sandbox`）后，PM 可把**关键节点**主动推到你 QQ——批次进度汇总、验收结论、发版或合并完成、异常阻塞：
-
-```bash
-$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。能力边界、退出码与纪律见 `$NAO_SKILLS/.agents/skills/qq-notify.md`。
-
 ## 为什么它省 token（这是本项目的核心追求）
 
 和 AI 聊天，钱花在「它每轮要读多少字」。所以：
@@ -108,6 +95,15 @@ $NAO_SKILLS/.agents/scripts/qq-notify --dry-run "连通性自检"      # 只取
 
 **跑完的会话要留着吗？** 后台派生会话验收完可以回收：`nao-fleet.sh close --task T1 rd-be`（等价写法 `nao-fleet.sh close rd-be-T1`，直接用派生会话名即可）；常驻角色留着复用。`nao-fleet.sh status` 会提示哪些是残留。目标在别的项目里也能回收——`close` 会按名册/窗口标题跨项目定位；定位不到时会**非 0 退出并打印诊断**，不会假装已回收。
 
+**推荐用 tmux 吗？** **推荐**——装上 tmux 后，舰队机制的使用体验最完整：
+
+- **布局可控**：6 个角色会话在 tmux 里按三种布局自动排布（`main-row2` / `main-col` / `grid`），间距与列宽可用 `NAO_TMUX_*` 变量调，不会把桌面铺满一圈窗口。
+- **后台会话可回看**：后台派生的会话随时 `tmux attach` 进去看，不挑图形环境（SSH 无图形会话也能用）。
+- **定位回收更可靠**：`status` 查残留、`close` 跨项目回收，都是按会话名册与窗口标题定位的——tmux 宿主下窗口标题稳定可寻，误判和找不到的概率最低。
+- **多种宿主探测路径**：机制里 tmux 属首选阶梯；非 tmux 宿主走外部终端窗口，探测与降级链路更长。
+
+没装 tmux 也能正常用（见「不在 tmux 里也能用」），只是上述便利项会依次降级。
+
 **终端窗口太挤怎么办？** 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`。
 
 **它会自己上网查吗？** 会，但有分工：产品经理查同类功能的**产品形态**（有哪些功能点、属性、视图、协作方式），架构师对照**业界成熟的架构模式**。两者都必须把来源和「适不适用本项目」落成文件（`docs/research/`），抓来的网页内容不会堆进聊天记录；技术选型仍然只由架构师定。
@@ -128,29 +124,35 @@ $NAO_SKILLS/.agents/scripts/qq-notify --dry-run "连通性自检"      # 只取
 
 机制本体（6 张角色卡、协作规矩、清单、按需技能、小工具）都在 npm 包 `@nathan33/nao-skill` 的 `.agents/` 里——**包里是什么就是什么**，项目里不留副本。
 
-## 发布形态与完整性判据（0.12 起有变化）
+## 老用户迁移与维护者注记（新用户可跳过）
+
+本节面向**已有旧版安装**或需要维护使用机制的仓库 CI 的读者，新用户可以直接跳到「想深入」。
+
+### 老项目迁移（migrate）
+
+```bash
+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` 的语义是「本机已安装机制包版本」（供升级检测），**不表达迁移状态**——迁移状态由「是否还有旧资产」推断。
+
+### 发布形态与完整性判据（0.12 起有变化）
 
 **从 0.12 起，机制不再铺进项目**：项目里只留一个转发入口，机制的**单一事实来源**是 npm 包 `@nathan33/nao-skill` 内的 `.agents/`。
 
-- **旧的完整性判据已失效**：以前下游靠「项目内 `.agents/**` 与上游逐字节 sha 一致」证明机制没漏没改；现在项目内不再有机制副本，这条判据不再适用。
+- **旧的完整性判据已失效**：以前靠「项目内 `.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 就地格式化**；新形态项目内只有转发入口，无需再处理。
+- **版本权威口径**：`.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 环境必读）
 
 - `.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` 才有输入。
+- **联动条款**：若某个仓库想把机制体检 `check` 放进 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:` + 恢复命令。
 
-## 下游仓库迁移（nao-todo / nao-todo-server / nue-ui）
-
-- **迁移期零改动**：旧的全套 `.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 只讲怎么用。真正的机制都在依赖包 `@nathan33/nao-skill` 的 `.agents/` 里（会话里以 `$NAO_SKILLS/.agents/` 指向），想改就从这几处入手：

package/bin/nao-skill.js

@@ -42,18 +42,16 @@ 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'];
 const LEGACY_TOP_FILES = ['roles.yaml'];
-const LEGACY_SCRIPT_FILES = ['nao-fleet.sh', 'intercom-probe.mts', 'qq-notify', 'ui-tokens-check.sh'];
+const LEGACY_SCRIPT_FILES = ['nao-fleet.sh', 'intercom-probe.mts', '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',
+  'pm-rice.md', 'pm-routing.md', 'research.md', 'test-design.md',
 ];
 
 const log = (...a) => console.log('[nao-skill]', ...a);
@@ -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.1",
+  "version": "0.16.0",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {

package/.agents/scripts/qq-notify

@@ -1,199 +0,0 @@
-#!/bin/sh
-//bin/true; exec node "$0" "$@"
-//
-// qq-notify —— QQ 官方机器人「主动消息」推送器（舰队可选能力）
-//
-// 用法（三种形式等价：./qq-notify · node qq-notify · sh qq-notify）
-//   ./qq-notify "文本"                发给配置中的 ownerOpenId（默认收件人）
-//   ./qq-notify --to OPENID "文本"    发给指定 openid
-//   ./qq-notify --dry-run "文本"      只取 token、不发送（连通性自检）
-//   ./qq-notify --config PATH "文本"  指定配置文件
-//   ./qq-notify --help                显示帮助
-//   stdin 管道                         无参数时从标准输入读取文本
-//
-// 配置优先级：--config PATH > 环境变量 QQ_NOTIFY_CONFIG > ~/.pi/agent/pi-agent-qqbot.json
-// 退出码：0 成功 · 1 参数/配置错 · 2 取 token 失败 · 3 发送失败
-// 安全：绝不打印/落盘 clientSecret 与 access_token；错误输出截断。
-//
-// ⛔ 禁用 `bash <本脚本>` 这类「用 shell 逐行解释 Node 脚本」的调用方式：
-//    shell 会把注释里的示例当命令执行（管道、重定向、glob），可能触发意外发送
-//    （本仓历史上正因此误发过一条真实消息）。正确形式：./qq-notify 或 node qq-notify。
-//    第 2 行的 exec 守卫已使 sh/bash 调用自动转交 node，但仍不建议依赖该行为。
-//
-// 实现说明：本文件无扩展名，需同时兼容宿主项目 package.json 的
-// "type": "module" 与 CommonJS 两种解析；因此只用动态 import()（两种格式都合法）
-// 并包在 async IIFE 中，避免静态 import / 顶层 await / require。
-;(async () => {
-  const fs = await import('node:fs')
-  const os = await import('node:os')
-  const path = await import('node:path')
-
-  const EXIT = { OK: 0, ARG: 1, TOKEN: 2, SEND: 3 }
-  const DEFAULT_CFG = path.join(os.homedir(), '.pi/agent/pi-agent-qqbot.json')
-  const TOKEN_URL = 'https://bots.qq.com/app/getAppAccessToken'
-  const BODY_LIMIT = 300
-
-  const USAGE = [
-    'qq-notify —— QQ 官方机器人「主动消息」推送器',
-    '',
-    '用法',
-    '  qq-notify "文本"                 发给配置中的 ownerOpenId',
-    '  qq-notify --to <openid> "文本"   发给指定 openid',
-    '  echo "文本" | qq-notify          从 stdin 读取文本',
-    '  qq-notify --dry-run "文本"       只取 token、不发送（连通性自检）',
-    '  qq-notify --config <path> ...    指定配置文件',
-    '  qq-notify -h | --help            显示本帮助',
-    '',
-    '配置（优先级从高到低）',
-    '  1) --config <path>',
-    '  2) 环境变量 QQ_NOTIFY_CONFIG',
-    '  3) ' + DEFAULT_CFG,
-    '  字段：{ "appId": "...", "clientSecret": "...", "ownerOpenId": "...", "sandbox": true }',
-    '',
-    '退出码',
-    '  0 成功   1 参数/配置错   2 取 token 失败   3 发送失败',
-    '',
-    '说明',
-    '  · 主动消息受 QQ 开放平台权限与月度配额限制；sandbox 与 prod 权限不通用',
-    '  · 绝不打印或落盘 clientSecret / access_token',
-  ].join('\n')
-
-  const trunc = (v, n = BODY_LIMIT) => {
-    const s = String(v ?? '')
-    return s.length > n ? s.slice(0, n) + '…(截断)' : s
-  }
-  // 从任何即将打印的文本中抹去已知凭证值（客户端密钥 / access_token）
-  const redact = (v, secrets = [], n = BODY_LIMIT) => {
-    let s = String(v ?? '')
-    for (const sec of secrets) {
-      if (sec && String(sec).length >= 6) s = s.split(String(sec)).join('***')
-    }
-    return trunc(s, n)
-  }
-  const maskId = (v) => (v ? String(v).slice(0, 6) + '…' : '<无>')
-  const fail = (code, msg, hint) => {
-    process.stderr.write('FAIL: ' + msg + '\n')
-    if (hint) process.stderr.write('  → ' + hint + '\n')
-    process.exit(code)
-  }
-
-  // ---- 参数解析 -----------------------------------------------------------
-  const argv = process.argv.slice(2)
-  let to = null
-  let cfgPath = null
-  let dry = false
-  let text = null
-  let endOpts = false
-
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (endOpts) {
-      if (text === null) { text = a; continue }
-      fail(EXIT.ARG, '多余的位置参数: ' + trunc(a, 60), '文本请用引号括起为一个参数')
-    }
-    if (a === '-h' || a === '--help') { process.stdout.write(USAGE + '\n'); process.exit(EXIT.OK) }
-    else if (a === '--dry-run') dry = true
-    else if (a === '--') endOpts = true
-    else if (a === '--to') {
-      const v = argv[++i]
-      if (!v || v.startsWith('--')) fail(EXIT.ARG, '--to 缺少 openid', '用法：qq-notify --to <openid> "文本"')
-      to = v
-    } else if (a.startsWith('--to=')) {
-      to = a.slice(5)
-      if (!to) fail(EXIT.ARG, '--to 缺少 openid', '用法：qq-notify --to <openid> "文本"')
-    } else if (a === '--config') {
-      const v = argv[++i]
-      if (!v || v.startsWith('--')) fail(EXIT.ARG, '--config 缺少路径', '用法：qq-notify --config <path> "文本"')
-      cfgPath = v
-    } else if (a.startsWith('--config=')) {
-      cfgPath = a.slice(9)
-      if (!cfgPath) fail(EXIT.ARG, '--config 缺少路径', '用法：qq-notify --config <path> "文本"')
-    } else if (a.startsWith('-') && a !== '-') {
-      fail(EXIT.ARG, '未知参数: ' + trunc(a, 60), '查看帮助：qq-notify --help')
-    } else {
-      if (text === null) text = a
-      else fail(EXIT.ARG, '多余的位置参数: ' + trunc(a, 60), '文本请用引号括起为一个参数')
-    }
-  }
-
-  if (!text && !process.stdin.isTTY) {
-    try {
-      const piped = fs.readFileSync(0, 'utf8').trim()
-      if (piped) text = piped
-    } catch { /* 无 stdin：忽略 */ }
-  }
-  if (!text) fail(EXIT.ARG, '缺少推送文本', '用法：qq-notify "文本"  或  echo "文本" | qq-notify')
-
-  // ---- 配置 ---------------------------------------------------------------
-  const cfgFile = cfgPath || process.env.QQ_NOTIFY_CONFIG || DEFAULT_CFG
-  let cfg
-  try {
-    cfg = JSON.parse(fs.readFileSync(cfgFile, 'utf8'))
-  } catch (e) {
-    if (e && e.code === 'ENOENT') {
-      fail(EXIT.ARG, '读不到配置：' + cfgFile,
-        '创建该 JSON（appId / clientSecret / ownerOpenId / sandbox），或用 --config <path> / QQ_NOTIFY_CONFIG=<path> 指定')
-    }
-    fail(EXIT.ARG, '配置解析失败：' + cfgFile + '：' + trunc(e && e.message, 160), '确认该文件是合法 JSON')
-  }
-  if (!cfg || typeof cfg !== 'object') fail(EXIT.ARG, '配置内容非法：' + cfgFile, '应为 JSON 对象')
-  if (!cfg.appId || !cfg.clientSecret) fail(EXIT.ARG, '配置缺少 appId 或 clientSecret', '检查 ' + cfgFile)
-
-  const target = to || cfg.ownerOpenId
-  if (!target) {
-    fail(EXIT.ARG, '没有收件人：配置缺 ownerOpenId，且未传 --to',
-      '在配置中填 ownerOpenId，或 qq-notify --to <openid> "文本"')
-  }
-  const env = cfg.sandbox ? 'sandbox' : 'prod'
-  const base = cfg.sandbox ? 'https://sandbox.api.sgroup.qq.com' : 'https://api.sgroup.qq.com'
-
-  // ---- 取 access token（绝不打日志） --------------------------------------
-  let tokenRes
-  try {
-    tokenRes = await fetch(TOKEN_URL, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ appId: cfg.appId, clientSecret: cfg.clientSecret }),
-    })
-  } catch (e) {
-    fail(EXIT.TOKEN, '取 token 网络错误：' + trunc(e && e.message, 160), '检查网络/代理后重试')
-  }
-  let tokenJson = {}
-  try { tokenJson = await tokenRes.json() } catch { /* 非 JSON 响应 */ }
-  if (!tokenRes.ok || !tokenJson.access_token) {
-    fail(EXIT.TOKEN, '取 token 失败：status=' + tokenRes.status + ' body=' + redact(JSON.stringify(tokenJson), [cfg.clientSecret]),
-      '核对 appId/clientSecret，并确认 QQ 开放平台应用已开通机器人能力')
-  }
-
-  if (dry) {
-    process.stdout.write('OK (dry-run) 取 token 成功 · env=' + env + ' · to=' + maskId(target) + '\n')
-    process.exit(EXIT.OK)
-  }
-
-  // ---- 发送主动消息（不带 msg_id） ----------------------------------------
-  let res
-  try {
-    res = await fetch(base + '/v2/users/' + encodeURIComponent(target) + '/messages', {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        authorization: 'QQBot ' + tokenJson.access_token,
-      },
-      body: JSON.stringify({ content: text, msg_type: 0 }),
-    })
-  } catch (e) {
-    fail(EXIT.SEND, '发送网络错误：' + trunc(e && e.message, 160), '检查网络后重试')
-  }
-  const body = await res.text().catch(() => '')
-  if (res.ok) {
-    process.stdout.write('OK env=' + env + ' to=' + maskId(target) + ' ' + redact(body, [cfg.clientSecret, tokenJson.access_token], 120) + '\n')
-    process.exit(EXIT.OK)
-  }
-  fail(EXIT.SEND, '发送失败：status=' + res.status + ' body=' + redact(body, [cfg.clientSecret, tokenJson.access_token]),
-    '核对收件人 openid、主动消息权限与月度配额；sandbox 与 prod 权限不通用')
-})().catch((e) => {
-  // 兜底：任何未预期错误都不抛栈（此处不依赖 IIFE 内作用域）
-  const msg = String((e && e.message) ? e.message : e)
-  process.stderr.write('FAIL: 未预期错误：' + (msg.length > 200 ? msg.slice(0, 200) + '…(截断)' : msg) + '\n')
-  process.exit(1)
-})