@nathan33/nao-skill 0.5.1 → 0.6.0

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

@@ -568,7 +568,7 @@ usage() {
 }
 
 # ---- 入口 ----
-CMD=""; FORCE=false; STRICT=false; MODEL=""; TARGETS=()
+CMD=""; FORCE=false; STRICT=false; MODEL=""; TASK=""; TARGETS=()
 while [[ $# -gt 0 ]]; do
   case "$1" in
     check)  CMD="check";  shift ;;

package/README.md

@@ -84,6 +84,12 @@ PM 是任务状态权威，以状态机驱动执行：
 
 - **忙闲闸门**：`list` 的 live status（`idle`/`thinking`/`tool:*`）为判定依据；忙时**不 send 任务内容**（非交互拒收 / 交互 steer 打断），直接排队；紧急才抢占（交互可 steer 注入 + 注明挂起，非交互只能排队）。
 - **状态外部化**：`docs/tasks-state.md` 五栏（待派发/进行中/待验收/挂起/已归档）随每次派发·回执·验收更新；PM 会话重开先读文件重建状态，不依赖历史消息。
+- **回执 = 已核对清单**：回执须声明已读 `checklists/<role>.md`（未过项必列），未核对不回执。
+- **离线检测与恢复**：`list` 发现已派发目标离线 → 标记挂起 → `ensure --force` 重拉 → 按挂起快照重派。
+- **队列唤醒**：回执/汇报/用户输入时顺带检查待派发队列（不单独轮询），避免排队任务悬置。
+- **降级回流**：intercom 不可用的降级交付经用户转交后，PM 补登记 tasks-state + 归档（标注「降级回流」）。
+- **常驻 vs 派生**：串行任务用常驻角色（忙闲排队）；并行/隔离任务用派生会话 `ensure --task <编号>`（`<角色>-<编号>`，如 `rd-be-T1`，任务完成即结束）。
+- **单 PM 纪律**：同一项目同一时刻仅一个 PM 调度会话。
 
 - **终态回执硬闸门**：所有角色（含 arch 评审）必须以回执模板结束任务；`send` 失败降级 `ask` → 再失败才降级交付。
 - **卡片版本同步**：改卡 bump `version` 并广播 `card <role> vN`（不贴全文）；worker 接任务前核对版本，stale 则重读。
@@ -93,6 +99,8 @@ PM 是任务状态权威，以状态机驱动执行：
 
 `@.agents/skills/codegraph.md`（按需）——`query`/`context`/`node`/`callers`/`callees`/`impact`/`affected` 速查 + token 纪律 + 降级 grep 规则。索引项目级维护：`status` → `init`/`sync`；`nao-fleet.sh` 的 `check`/`ensure` 自动探测索引健康并提醒。
 
+**全角色行为指令**（非可选引用）：rd-be 关键约定「先 codegraph 后 grep」、rd-fe 硬性红线「未先试 codegraph 即违规」、qa `node/affected` 定位被测代码、arch `impact/callers` 影响面评审、PM 验收 `node --file/--limit` 行段读取——**禁 cat 全文**是本机制通用读码纪律。
+
 ## UI/UX 落地（三层，不绑定组件库）
 
 | 层 | 载体 | 职责 |
@@ -107,7 +115,7 @@ PM 是任务状态权威，以状态机驱动执行：
 
 | Prompt | Role | 核心职责 |
 | --- | --- | --- |
-| `product-manager.md` | 产品经理（调度者） | 需求全生命周期、9 模块 PRD、RICE、多会话调度、终态回执闸门、**§七 AGENTS.md 项目上下文治理**、§十一 docs/prds 归档 |
+| `product-manager.md` | 产品经理（调度者） | 需求全生命周期、9 模块 PRD、RICE、多会话调度、终态回执闸门、**§七 AGENTS.md 项目上下文治理**、§十一 docs/prds 归档、验收读码（codegraph 行段） |
 | `architecture-designer.md` | 系统架构师（评审/咨询） | 技术选型四步法、评审签字 + ADR、终态回执 PM、降级规则 |
 | `frontend-developer.md` | 前端研发 | 前端 DDD 五层、UI/UX 三层落地（先读项目既有风格→定方向→tokens/组件库，引用 frontend-design） |
 | `backend-developer.md` | 后端研发 | Go DDD 四层、依赖倒置、事务/事件/错误约定 |
@@ -157,6 +165,7 @@ nao-skill update                             # 升级已有安装（源优先 +
 - **update（升级）**：机制文件源优先覆盖（项目定制应放 `AGENTS.md`）、备份清理已知废弃路径（如旧版 `skills/checklists/`，防 skill 冲突）到 `.agents/.nao-obsolete/`、保留项目自定义文件。
 - **旧版检测**：install 发现版本落后或废弃路径 → 提示运行 `update`。
 - **安装内容**：`.agents/` 全套（角色卡 / 技能 / 交付清单 / 协议 / roles.yaml / 工具链 / 模板）+ 生成 `AGENTS.md`（已存在则提示按 §七 合并，不覆盖）。
+- **pi 插件管理**：`nao-skill plugins list` / `install <名...>` / `install-all`——舰队生态插件（intercom / ask-me / subagents / web-access / codegraph），透传 `pi install npm:<pkg>`，幂等跳过已装。
 - **发布**：`npm publish --access public`（scope 包需 `--access public`）。
 
 ## 目录结构

package/bin/nao-skill.js

@@ -43,26 +43,39 @@ const VERSION_FILE = '.agents/.nao-version';
 const log = (...a) => console.log('[nao-skill]', ...a);
 const warn = (...a) => console.error('[nao-skill]', ...a);
 
-function copyDir(src, dst, force) {
-  const entries = readdirSync(src, { withFileTypes: true });
-  let copied = 0, skipped = 0, overwritten = 0;
-  for (const e of entries) {
-    const s = join(src, e.name);
-    const d = join(dst, e.name);
-    if (existsSync(d)) {
-      if (force) {
-        rmSync(d, { recursive: true, force: true });
-        cpSync(s, d, { recursive: true });
-        overwritten++;
+function syncTree(src, dst, { mode, force, verbose }) {
+  // 递归文件级同步：mode='install'（保守）| 'update'（源优先）
+  // 源文件 → 目标无：copy；同内容：same（跳过）；不同内容：install 默认 keep（--force 覆盖）/ update 总是 overwrite
+  // 目标独有：不动（项目自定义保留）
+  const stats = { copied: 0, overwritten: 0, same: 0, kept: 0 };
+  const base = dst;
+  const rel = (p) => p.replace(base + '/', '');
+  const walk = (s, d) => {
+    if (!existsSync(d)) mkdirSync(d, { recursive: true });
+    for (const e of readdirSync(s, { withFileTypes: true })) {
+      const sp = join(s, e.name);
+      const dp = join(d, e.name);
+      if (e.isDirectory()) { walk(sp, dp); continue; }
+      if (!existsSync(dp)) {
+        cpSync(sp, dp);
+        stats.copied++;
+        if (verbose) log(`  copy      ${rel(dp)}`);
+      } else if (readFileSync(sp).equals(readFileSync(dp))) {
+        stats.same++;
+        if (verbose) log(`  same      ${rel(dp)}`);
+      } else if (mode === 'update' || force) {
+        rmSync(dp, { force: true });
+        cpSync(sp, dp);
+        stats.overwritten++;
+        if (verbose) log(`  overwrite ${rel(dp)}`);
       } else {
-        skipped++;
+        stats.kept++;
+        if (verbose) log(`  keep      ${rel(dp)}（内容不同，--force 覆盖）`);
       }
-    } else {
-      cpSync(s, d, { recursive: true });
-      copied++;
     }
-  }
-  return { copied, skipped, overwritten };
+  };
+  walk(src, dst);
+  return stats;
 }
 
 // 已知 pi 插件（nao 舰队生态），name → npm 包
@@ -126,7 +139,7 @@ function pluginsInstall(names, all = false) {
   }
 }
 
-function install(target, force) {
+function install(target, force, verbose) {
   if (!existsSync(SRC)) {
     warn(`包内 .agents 缺失：${SRC}（发布物损坏？）`);
     process.exit(1);
@@ -137,10 +150,10 @@ function install(target, force) {
     cpSync(SRC, dst, { recursive: true });
     log(`已完整安装 .agents/ → ${dst}`);
   } else {
-    const r = copyDir(SRC, dst, force);
-    log(`合并完成：复制 ${r.copied}，跳过 ${r.skipped}（已存在），覆盖 ${r.overwritten}`);
-    if (r.skipped > 0 && !force) {
-      warn('同名文件保留项目既有版本（避免覆盖自定义）；需要覆盖加 --force。');
+    const r = syncTree(SRC, dst, { mode: 'install', force, verbose });
+    log(`合并完成：复制 ${r.copied}，覆盖 ${r.overwritten}，相同跳过 ${r.same}，保留项目版 ${r.kept}`);
+    if (r.kept > 0 && !force) {
+      warn('内容不同的文件保留项目既有（避免覆盖自定义）；--force 覆盖，或 update 模式源优先。');
     }
   }
 
@@ -172,21 +185,15 @@ function install(target, force) {
   log('  角色卡：.agents/prompts/ · 技能：.agents/skills/ · 交付清单：.agents/checklists/');
 }
 
-function update(target) {
+function update(target, verbose) {
   // 源优先升级：机制文件以包为权威（项目定制应放 AGENTS.md，不在机制文件里改）
   const dst = join(target, '.agents');
   if (!existsSync(dst)) {
     log('目标无 .agents/，直接完整安装。');
-    return install(target, false);
-  }
-  let overwritten = 0;
-  for (const e of readdirSync(SRC)) {
-    const s = join(SRC, e);
-    const d = join(dst, e);
-    rmSync(d, { recursive: true, force: true });
-    cpSync(s, d, { recursive: true });
-    overwritten++;
+    return install(target, false, verbose);
   }
+  const r = syncTree(SRC, dst, { mode: 'update', force: true, verbose });
+  log(`升级完成：复制 ${r.copied}，覆盖 ${r.overwritten}，相同跳过 ${r.same}（项目自定义保留）`);
   // 清理已知废弃路径（先备份到 .agents/.nao-obsolete/）
   for (const p of OBSOLETE) {
     const full = join(target, p);
@@ -215,9 +222,9 @@ function help() {
   console.log(`nao-skill v${PKG.version} — nao 多角色 AI 开发舰队安装器
 
 用法:
-  nao-skill install [dir] [--force]   安装/合并 .agents/ 到目标项目（默认当前目录）
-  nao-skill install --plugins          项目接入时顺带安装 pi 舰队插件
-  nao-skill update [dir]              升级已有安装：源优先覆盖 + 清理废弃路径 + 保留项目自定义
+  nao-skill install [dir] [--force] [-v]   安装/合并 .agents/ 到目标项目（默认当前目录；-v 显示每文件过程）
+  nao-skill install --plugins [-v]         项目接入时顺带安装 pi 舰队插件
+  nao-skill update [dir] [-v]              升级已有安装：源优先覆盖 + 清理废弃路径 + 保留项目自定义
   nao-skill plugins list              列出已知 pi 插件与安装状态
   nao-skill plugins install <名...>   安装指定插件（intercom/ask-me/subagents/web-access/codegraph）
   nao-skill plugins install-all       安装全部舰队插件
@@ -246,10 +253,12 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
   let target = process.cwd();
   let force = false;
   let withPlugins = 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] === '--plugins') withPlugins = 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); }
@@ -258,7 +267,7 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
     warn(`目标目录无效: ${target}`);
     process.exit(2);
   }
-  install(target, force);
+  install(target, force, verbose);
   if (withPlugins) pluginsInstall([], true);
 } else if (cmd === 'plugins' || cmd === 'plugin') {
   const sub = args[1];
@@ -275,9 +284,11 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
   }
 } else if (cmd === 'update' || cmd === 'u') {
   let target = process.cwd();
+  let verbose = false;
   const rest = args.slice(1);
   for (let i = 0; i < rest.length; i++) {
-    if (rest[i] === '--target') target = resolve(rest[++i]);
+    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); }
   }
@@ -285,7 +296,7 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
     warn(`目标目录无效: ${target}`);
     process.exit(2);
   }
-  update(target);
+  update(target, verbose);
 } else {
   warn(`未知命令: ${cmd}（可用: install, update, plugins）`);
   process.exit(2);

package/package.json

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