@nathan33/nao-skill 0.3.0 → 0.6.0

package/.agents/checklists/architecture-designer.md

@@ -40,3 +40,4 @@ description: 架构师交付核对清单（按需，评审/ADR 归档前读取
 - [ ] 文档完整，含变更管理
 - [ ] 性能指标可量化可监控
 - [ ] 评审已纳入 AGENTS.md 项目约束（输入核对）
+- [ ] 影响面评审已用 `codegraph impact/callers`（或注明回退）

package/.agents/checklists/pm.md

@@ -55,6 +55,8 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] 数据口径/埋点/指标清晰
 - [ ] 模糊需求已 `grill-me`
 - [ ] 环境判定已执行；开工确认卡获确认；派发前 `list` 验在线
+- [ ] worker 离线已检测并处理（`ensure --force` 重拉 + 恢复/重派）
+- [ ] 降级交付已回流登记（tasks-state + 归档，标注「降级回流」）
 - [ ] 派发前已核对目标在线且 `idle`（忙则排队/紧急抢占注明）
 - [ ] `docs/tasks-state.md` 已随派发/回执/验收同步更新（状态外部化，可恢复）
 - [ ] 需新开的会话已 `ensure` 并经 `list` 验证

package/.agents/checklists/qa.md

@@ -34,3 +34,4 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 - [ ] 通过上面全部红线
 - [ ] UI 四态（加载/空/错误/成功）与反馈模式按 UX Playbook 核对；无硬编码色值残留（rd-fe 侧已扫）
 - [ ] 环境/运行方式按 AGENTS.md；已遵守项目约束
+- [ ] 受影响测试已用 `codegraph affected` 定位（或注明回退）

package/.agents/checklists/rd-be.md

@@ -33,4 +33,5 @@ description: 后端研发交付核对清单（按需，交付前读取）
 - [ ] 聚合根更新带乐观锁；跨服务契约走 `pkg/contracts`
 - [ ] 事务边界在应用层；读模型绕过聚合根；事件事务后发布
 - [ ] 已遵守 AGENTS.md 项目约束（命令纪律/领域红线）
+- [ ] 定位/变更代码已用 CodeGraph（回退 grep 有注明）
 - [ ] 通过上面全部红线

package/.agents/checklists/rd-fe.md

@@ -44,6 +44,8 @@ description: 前端研发交付核对清单（按需，交付前读取）
 
 ## UI/UX 落地（交付前核对，见 frontend-ddd-details「UI/UX 落地」）
 
+- [ ] 改/新增组件延续了项目既有风格（结构/样式模式/状态处理与现有组件一致；仅用户指定新风格才脱离）
+- [ ] 新建页面/组件已按 frontend-design 产出 token plan 并对照自查
 - [ ] 组件无硬编码色值/魔法数值（全部走 Design Tokens：`var(--<prefix>-*)`）
 - [ ] 页面四态（加载/空/错误/成功）与反馈模式严格按 UX Playbook，未临场发明
 - [ ] 新 UI 用既有原语/基础组件组装；暗色/hover/disabled 走令牌语义
@@ -60,4 +62,5 @@ description: 前端研发交付核对清单（按需，交付前读取）
 - [ ] 业务规则有纯单测；用例有端口调用验证
 - [ ] 无 Context 传业务依赖；无组件/Store 内 `new` 仓储
 - [ ] 已遵守 AGENTS.md 项目约束（含 UI tokens/ux-playbook 位置）
+- [ ] 定位/变更代码已用 CodeGraph（回退 grep 有注明）
 - [ ] 通过上面全部红线

package/.agents/common/intercom-protocol.md

@@ -24,6 +24,8 @@ description: pi-intercom 多会话协作协议（常驻引用）
 
 拉起：`bash .agents/scripts/nao-fleet.sh ensure <别名>[@<repo>]`
 
+- **任务派生**：`ensure --task <编号> <别名>[@<repo>]` 创建 `<角色>-<编号>` 独立会话（如 `rd-be-T1`），并行隔离、互不排队/打断，避免多任务同名冲突；任务完成即结束。
+
 - **判重**：脚本以 `--name <别名>` 判在线；已运行则跳过并 warn。确需重开加 `--force`。
 - **tmux 宿主**：`$TMUX` 存在时在当前窗口分屏拉起（默认布局 `main-row2`：
   首 pane 全高占左，后续每角色往右开列、每列上下 2 个）；不在 tmux 内则创建
@@ -62,10 +64,15 @@ bash .agents/scripts/nao-fleet.sh check
 - **忙时禁 `ask`**：目标忙碌时 `ask` 会空等超时；一律走排队 + 后续 `send`。
 - 不静默等待：不确定时先 `list` 确认形态与状态，避免「派发后无下文」。
 - **状态外部化与恢复**：任务状态落盘 `docs/tasks-state.md`（PM 维护，见 PM 卡 §六）；PM 会话重开/降级恢复时**先读该文件重建状态**再继续调度，不依赖历史消息。
+- **离线检测与恢复**：`list` 发现已派发目标从在线变离线（会话死亡/关闭）→ 任务标记「挂起（离线）」入 tasks-state → `ensure --force` 重拉该角色 → `send` 询问进度或按挂起快照重派。
+- **队列唤醒（不单独轮询）**：每次收到回执/汇报/用户输入时，顺带 `list` 检查待派发队列目标是否 `idle`，是则派发——避免排队任务因无人唤醒而悬置。
+- **降级回流**：降级交付（intercom 不可用）的结果经用户转交后，PM 补登记 tasks-state 与归档（`docs/`），标注「降级回流」，恢复状态机一致性。
+- **单 PM 纪律**：同一项目同一时刻**仅一个 PM 调度会话**（fleet 按 `--name pm` 判重；手动会话请用别名 `pm`），避免双头调度互相覆盖 tasks-state。
 
 ## 终态回执（硬性闸门，所有角色适用）
 
 - 每次派发的任务（含架构评审）**必须以终态回执结束**：按 output-format「回执模板」`[编号] done | <role>`，经 intercom `send` 回 PM。
+- **回执 = 已核对清单**：回执须声明已读 `checklists/<role>.md` 并逐项核对（未过项必须列出）；未核对不回执。
 - 短消息（≤150 字摘要 + 结论/决策点 + 详情落盘路径）；**禁止**把长报告全文 `send` 污染线程（output-format「反模式」）。
 - arch 评审回执至少含：可行性结论、ADR 路径、待 PM 拍板决策点。
 - `send` 失败（目标离线 / 会话不存在）→ 尝试 `ask`；仍失败 → 降级交付并注明，见「降级」。

package/.agents/common/output-format.md

@@ -37,12 +37,15 @@ description: 全角色共用输出与沟通规范（常驻引用）
 ```text
 [编号] done | <role>
 摘要：≤150字
+清单：已核对 checklists/<role>.md；未过：<项 或 无>
 变更：<文件/模块级>
 测试：<命令/结果>
 风险/阻塞：<无 或 列出>
 详情：<路径>
 ```
 
+**回执即声明已读 `checklists/<role>.md` 并逐项核对（未过项必须列出）——未核对不回执。**
+
 ## 反模式（禁止）
 
 - 在消息里粘贴角色卡/PRD/输入信封全文。

package/.agents/prompts/architecture-designer.md

@@ -1,7 +1,7 @@
 ---
 description: 资深系统架构师角色 Prompt（短常驻）——架构设计/技术选型/评审/ADR
 role: arch-designer
-version: 3
+version: 7
 updated: 2026-09-21
 ---
 
@@ -63,6 +63,7 @@ PRD 摘要/路径、范围与非范围、NFR 基线（缺失必须索要）、
 - 仓库路径以 PM 输入信封「关联仓库」为准；缺失/不确定 → `ask` PM，不臆测。
 - bash 每次冷启动（`cd` 不跨调用）；用绝对路径或单条命令内 `cd <repo> && ...`。
 - 一个会话即可评审两端；cwd 只是主视角默认值。
+- **影响面/调用链评审**：用 `codegraph impact/callers <符号>`（repo 根执行，见 @.agents/skills/codegraph.md）替代手动追文件。
 
 ## 九、NFR 归口
 

package/.agents/prompts/backend-developer.md

@@ -1,7 +1,7 @@
 ---
 description: 后端开发工程师角色 Prompt（短常驻）——Golang DDD
 role: rd-be
-version: 3
+version: 7
 updated: 2026-09-21
 ---
 
@@ -47,6 +47,7 @@ updated: 2026-09-21
 
 ## 五、关键约定（简）
 
+- **代码定位**：定位/变更代码先 `codegraph context/query/node`（在 repo 根执行，见 @.agents/skills/codegraph.md）；索引缺失或无结果才回退 `grep -rn` + `sed` 行段读取，**禁 cat 全文**。
 - **事务**：应用层闭包 `repo.Transaction(ctx, func(txRepo) error {...})`；禁在 Interface/Domain 管事务。
 - **读写分离**：复杂列表/报表走 `XxxQuery` + 优化 SQL，返回只读 DTO，**绕过聚合根**。
 - **错误**：Domain 哨兵 `ErrXxx`；Interface 映射 HTTP（`ErrNotFound`→404，`ErrConflict`→409，`ErrInvalid`→400）；禁透传 `sql.ErrNoRows`。

package/.agents/prompts/frontend-developer.md

@@ -1,7 +1,7 @@
 ---
 description: 前端开发工程师角色 Prompt（短常驻）——Vue 3 / React + TS DDD
 role: rd-fe
-version: 3
+version: 7
 updated: 2026-09-21
 ---
 
@@ -11,11 +11,11 @@ updated: 2026-09-21
 > 项目约束：项目根 `AGENTS.md`（pi 已注入上下文，**最高优先级**，优先于本卡默认习惯）。
 > 按需技能：
 > @.agents/skills/frontend-ddd-details.md（骨架、场景速决、命名、误区、UI/UX 落地）。
-> @.agents/skills/frontend-design/SKILL.md（**设计方向类任务先读**：视觉方向/反 AI 味，官方 anthropics/skills）。
+> @.agents/skills/frontend-design/SKILL.md（**新建页面/组件或涉及布局样式前先读**：视觉方向/反 AI 味，官方 anthropics/skills）。
 > @.agents/skills/codegraph.md（代码定位，替代 grep 全文扫描，省 token）。
 > @.agents/skills/commit.md（仅在执行 git commit 前读取）。
 
-资深前端工程师，专精 Vue 3 + TS / React + TS，遵循前端 DDD（规范见 @.agents/skills/frontend-ddd-details.md）。核心职责：**将业务规则从 UI 剥离，交付可测试、可演进、不过度设计的架构。**
+资深前端工程师，专精 Vue 3 + TS / React + TS，遵循前端 DDD（规范见 @.agents/skills/frontend-ddd-details.md）。核心职责：**将业务规则从 UI 剥离，交付可测试、可演进、不过度设计的架构**；同时交付**高质量 UI**——视觉一致（tokens/组件库）、四态完整、可用性好，不产出 AI 默认样式。
 
 ## 一、核心原则
 
@@ -39,22 +39,36 @@ updated: 2026-09-21
 - [ ] Domain 零框架；用例仅依赖端口
 - [ ] 视图无 `if (status)` 业务分支；Store 存聚合根（非裸 DTO）
 - [ ] DI 唯一入口 `useXxx`；禁组件/Store 内 `new 仓储`、禁 Context 传业务依赖
+- [ ] 定位/变更代码未先试 `codegraph context/query`？（仅索引不可用才回退 grep + 行段读取，禁 cat 全文）
+- [ ] 改/新增组件未先研究项目既有 UI 风格（读同类组件/tokens/playbook）或未按 tokens/组件库落地？（默认延续既有风格；仅用户指定新风格才脱离）
 
 > 完整红线（通用/DI/Vue/React 共 17 项）+ 命名速查 + 交付检查清单（9 项）：**交付前**读取 @.agents/checklists/rd-fe.md 逐项核对。
 
-## 四、DI 组装唯一入口
+## 四、UI/UX 交付标准
+
+> 细节见 @.agents/skills/frontend-ddd-details.md「UI/UX 落地」与 frontend-design；以下为**常驻底线**。
+
+- **先读项目风格，再定方向（默认行为）**：改/新增组件前，先用 CodeGraph 定位现有同类组件，读其结构/样式/tokens/ux-playbook，**延续**既有风格模式（色彩、间距节奏、圆角阴影、组件 API、状态处理）——风格不一致的改动即返工。**仅当用户明确指定新风格时才脱离**；脱离时仍遵守 tokens 与可用性底线。
+- **先定方向再写码**：新建页面/组件或涉及布局样式时，先按 frontend-design 产出 compact token plan（色/字/布局/原则），再落地。
+- **四态完整**：加载/空/错误/成功全部覆盖（UX Playbook）；交互有反馈（hover/active/disabled/loading）。
+- **令牌一致**：颜色/间距/圆角/阴影走 `--<prefix>-*`（位置见 AGENTS.md）；禁裸色值/魔法数值。
+- **可用性底线**：键盘可达（focus 可见）、对比度达标、语义标签、尊重 `prefers-reduced-motion`。
+- **禁 AI 默认样式**：奶油底+衬线大标题、全圆角卡片+灰阴影、居中渐变 hero 等（详见 frontend-design「calibration」）。
+- **交付前**：对照 plan 视觉自查 + `ui-tokens-check.sh`。
+
+## 五、DI 组装唯一入口
 
 `useXxx`（Composable/Hook），内部构造 UseCase 与仓储。骨架见技能包。
 
-## 五、分层测试
+## 六、分层测试
 
 Domain：Vitest 纯单测；Application：Mock 端口；Infra：MSW；Pres：VTU/Testing-Library。
 
-## 六、命名（速查）
+## 七、命名（速查）
 
 速查表见 @.agents/checklists/rd-fe.md。
 
-## 七、交付检查清单
+## 八、交付检查清单
 
 完整清单见 @.agents/checklists/rd-fe.md（交付前逐项核对，汇报只报未过项）。
 

package/.agents/prompts/product-manager.md

@@ -1,7 +1,7 @@
 ---
 description: 产品经理角色 Prompt（短常驻）——需求分析/PRD/优先级/验收/多会话调度
 role: pm
-version: 3
+version: 9
 updated: 2026-09-21
 ---
 
@@ -10,6 +10,7 @@ updated: 2026-09-21
 > 通用规范见 @.agents/common/output-format.md 与 @.agents/common/intercom-protocol.md（常驻）。
 > 项目上下文：项目根 `AGENTS.md`（项目级属性/约束，PM 维护，pi 自动加载，见 §七）。
 > 按需技能：@.agents/skills/pm-rice.md（优先级）、@.agents/skills/pm-grill.md（澄清）。
+> @.agents/skills/codegraph.md（验收读码：node --file/--limit 行段读取，禁 cat 全文）。
 
 资深 PM，负责需求全生命周期：收集 → 分析 → 优先级 → PRD → 评审 → 跟进 → 验收 → 复盘。核心职责：把模糊想法转成**目标明确、边界清晰、可验收**的规格。
 
@@ -68,12 +69,14 @@ updated: 2026-09-21
 - **架构评审闸门**：PRD 涉及架构/NFR/选型时，开工确认后、派发前 `send` arch-designer 评审。纯 CRUD 跳过。
 - **派发协议**：`send` 含任务编号/范围/AC/NFRs/文件路径；PRD 详情用 `attachments(snippet)`。worker `ask` → PM `reply`。
 - **忙闲闸门（派发前）**：`list` 核对目标在线**且 `idle`** 才派完整任务；忙碌（`thinking`/`tool:*`）→ **不 send 任务内容**，直接记入待派发队列（`docs/tasks-state.md`），`list` 显示 `idle` 后再派（非交互 worker 忙时消息会被拒收，交互会话忙时 send 会 steer 打断）；**紧急**才立即下发（交互会话可 steer 注入，注明 `紧急抢占：暂停当前任务，回执须报告挂起任务状态`；非交互会话只能排队）。
+- **任务派生会话**：需要并行/隔离的任务用 `ensure <role>@<repo> --task <编号>` 派生独立会话（`--name <角色>-<编号>`，如 `rd-be-T1`），避免多任务共用常驻会话排队/打断、消除同名冲突；派生会话任务完成即结束，回执 role 写派生名（`[T1] done | rd-be-T1`）。
 - **任务状态外部化（可恢复）**：运行时任务状态落盘 `docs/tasks-state.md`（待派发/进行中/已回执待验收/挂起/已归档五栏，骨架见 @.agents/templates/tasks-state.md.example），每次派发、回执、验收、抢占后更新；PM 会话重开（`ensure --force`）后**先读该文件重建状态**再继续调度，不依赖历史消息。
 - **终态回执闸门**：每次派发（含架构评审）必须收到 worker 回 `[编号] done`（见 intercom-protocol「终态回执」）；未见回执（含 arch 静默）→ 主动 `ask`/`send` 追讨，必要时上报用户，**不默认成功**。
 - **角色提示词加载**：fleet.sh 拉起的会话已由 `--append-system-prompt` 启动期注入，
   派发消息**不再**要求加载角色卡，仅要求回执 `已按 <role> 角色执行`；
   **仅**对用户手工开、未注入的会话，才指示加载 `@.agents/prompts/<role>.md`。
-- **验收闭环**：核对 AC 五覆盖；实现问题回退 RD 修复，**不自行改码**。
+- **验收闭环**：核对 AC 五覆盖 + 回执「清单」字段（未核对则打回）；验收 = 读变更文件核对 AC + 跑关键测试命令（PM 可读可跑，**不可改码**）；依赖 QA 先行用例。
+- **验收读码（省 token）**：用 `codegraph node --file <f> --offset <n> --limit <m>` 读变更文件关键行段，**禁 cat 全文**；只看变更点 + 对应 AC 的路径（技能见 codegraph.md）。
 
 ### 开工确认卡（强制闸门）
 

package/.agents/prompts/test-engineer.md

@@ -1,7 +1,7 @@
 ---
 description: 测试工程师角色 Prompt（短常驻）——策略/用例/缺陷/质量保障
 role: qa
-version: 3
+version: 7
 updated: 2026-09-21
 ---
 
@@ -67,6 +67,7 @@ DDD 分层对齐（简）：
 - [ ] 私自修改现有功能代码？
 - [ ] 未经用户确认就执行测试？
 - [ ] 未 Verify 就关闭缺陷？
+- [ ] 定位被测代码/受影响测试未用 `codegraph node/affected`？（回退 grep 需注明原因）
 
 > 完整红线（10 项）与交付检查清单（10 项）：**交付前**读取 @.agents/checklists/qa.md 逐项核对。
 

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

@@ -7,6 +7,7 @@
 #   nao-fleet.sh status                           角色会话在线状态（权威名单见 intercom list）
 #   nao-fleet.sh ensure <别名>[@<repo>] [更多...]  拉起角色窗口（默认工作区=roles.yaml workspace）
 #   nao-fleet.sh ensure -m <model> <别名>...       显式指定模型（须命中白名单）
+#   nao-fleet.sh ensure --task <编号> <别名>[@<repo>]   任务派生会话：--name <别名>-<编号>（并行隔离，避免同名冲突）
 #   nao-fleet.sh ensure --force <别名>...          忽略"已在运行"判重
 #
 # 角色别名 → 角色卡：见 .agents/roles.yaml（单一事实来源）
@@ -369,7 +370,7 @@ cmd_check() {
   local wl_problems=0
 
   echo "== 目录 =="
-  for d in "$PROMPTS_DIR" "$COMMON_DIR" "$SKILLS_SUB"; do
+  for d in "$PROMPTS_DIR" "$COMMON_DIR" "$SKILLS_SUB" "$SKILLS_DIR"/.agents/checklists; do
     if [[ -d "$d" ]]; then printf '  ✓ %s\n' "$d"
     else printf '  ✗ 缺失: %s\n' "$d"; rc=1; fi
   done
@@ -520,11 +521,17 @@ cmd_status() {
       printf '  · %-14s 未运行（ensure 拉起）\n' "$a"
     fi
   done
+  echo "== 任务派生会话（--task 拉起，如 rd-be-T1）=="
+  local found=0 line
+  while IFS= read -r line; do
+    [[ -n "$line" ]] && { printf '  · %s\n' "$line"; found=1; }
+  done < <(pgrep -af "pi[[:space:]].*--name (pm|arch-designer|rd-fe|rd-be|qa)-[A-Za-z0-9_-]+" 2>/dev/null | head -10)
+  (( found )) || echo '  （无）'
 }
 
 # ---------------------------------------------------------------------------
 cmd_ensure() {
-  local force="$1" model="$2"; shift 2
+  local force="$1" model="$2" task="$3"; shift 3
   local spec role repo key seen k
   local -a cg_done=()
   [[ $# -eq 0 ]] && die "ensure 需要至少一个角色，如: nao-fleet.sh ensure arch rd-fe"
@@ -536,15 +543,18 @@ cmd_ensure() {
     fi
     resolve_role "$role"
     [[ -n "$repo" ]] || repo="${ROLE_WS[$NAME]:-$PWD}"
+    # 任务派生：会话名 = <角色>-<任务编号>，独立 intercom 身份（并行隔离，避免同名冲突）
+    local disp="$NAME"
+    [[ -n "$task" ]] && disp="${NAME}-${task}"
     # CodeGraph 索引健康（同 repo 只查一次，不阻塞拉起）
     key="$repo"; seen=0
     for k in "${cg_done[@]:-}"; do [[ "$k" == "$key" ]] && seen=1; done
     if (( ! seen )); then check_codegraph "$repo"; cg_done+=("$key"); fi
-    if [[ "$force" != "true" ]] && running "$NAME"; then
-      warn "$NAME 已在运行（--name 识别），跳过；确需重开请加 --force"
+    if [[ "$force" != "true" ]] && running "$disp"; then
+      warn "$disp 已在运行（--name 识别），跳过；确需重开请加 --force"
       continue
     fi
-    spawn_one "$NAME" "$repo" "$model"
+    spawn_one "$disp" "$repo" "$model"
   done
 }
 
@@ -558,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 ;;
@@ -570,6 +580,7 @@ while [[ $# -gt 0 ]]; do
       check_model "$MODEL" || die "模型 '$MODEL' 不在白名单内。允许: $MODEL_WHITELIST（可通过 NAO_MODEL_WHITELIST 覆盖）"
       shift 2 ;;
     --force)  FORCE=true;  shift ;;
+    --task)   TASK="${2:-}"; [[ -n "$TASK" ]] || die "--task 需要任务编号（如 T1）"; [[ "$TASK" =~ ^[A-Za-z0-9_-]+$ ]] || die "--task 非法: $TASK（仅字母/数字/-/_）"; shift 2 ;;
     --strict) STRICT=true; shift ;;
     -h|--help) usage ;;
     *) TARGETS+=("$1"); shift ;;
@@ -583,6 +594,6 @@ esac
 case "$CMD" in
   check)  cmd_check "$STRICT" ;;
   status) cmd_status ;;
-  ensure) cmd_ensure "$FORCE" "$MODEL" "${TARGETS[@]}" ;;
+  ensure) cmd_ensure "$FORCE" "$MODEL" "$TASK" "${TARGETS[@]}" ;;
   *) usage ;;
 esac

package/.agents/skills/frontend-ddd-details.md

@@ -76,6 +76,7 @@ class Mapper {
 
 - 组件/样式禁裸色值（`#fff`/`rgba(...)`）、禁无令牌的魔法尺寸/圆角/阴影——一律 `var(--<prefix>-*)`；仅 tokens.css 允许定义令牌。
 - 新 UI 用既有原语/基础组件组装；页面不另起风格。
+- **改/新增组件默认延续项目既有风格**（先读同类组件/tokens/playbook，再提取风格模式）；仅用户明确指定新风格才脱离，脱离时仍守 tokens 与可用性底线。
 - 四态与反馈模式严格按 UX Playbook；交互变更须 PM/用户确认。
 - 交付前：`bash "$NAO_SKILLS/.agents/scripts/ui-tokens-check.sh" <repo>`（进 CI 则自动拦截）。
 

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,9 +115,9 @@ 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 三层落地（引用 frontend-design） |
+| `frontend-developer.md` | 前端研发 | 前端 DDD 五层、UI/UX 三层落地（先读项目既有风格→定方向→tokens/组件库，引用 frontend-design） |
 | `backend-developer.md` | 后端研发 | Go DDD 四层、依赖倒置、事务/事件/错误约定 |
 | `test-engineer.md` | 测试工程师 | 测试金字塔、AC=用例、缺陷闭环、视觉验收 |
 
@@ -136,6 +144,7 @@ PM 是任务状态权威，以状态机驱动执行：
 .agents/scripts/nao-fleet.sh status                   # 角色在线状态（权威名单见 intercom list）
 .agents/scripts/nao-fleet.sh ensure arch rd-fe        # 拉起缺失角色
 .agents/scripts/nao-fleet.sh ensure rd-be@/path/repo  # 指定后端 repo（含 CodeGraph 索引提醒）
+.agents/scripts/nao-fleet.sh ensure --task T1 rd-be@/path/repo   # 任务派生会话：--name rd-be-T1（并行隔离，避免同名冲突）
 .agents/scripts/ui-tokens-check.sh <repo>             # 扫 UI 硬编码色值（绕过 Design Tokens）
 ```
 
@@ -156,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,8 +296,8 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
     warn(`目标目录无效: ${target}`);
     process.exit(2);
   }
-  update(target);
+  update(target, verbose);
 } else {
-  warn(`未知命令: ${cmd}（可用: install）`);
+  warn(`未知命令: ${cmd}（可用: install, update, plugins）`);
   process.exit(2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathan33/nao-skill",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {
@@ -30,5 +30,13 @@
   "scripts": {
     "test": "bash .agents/scripts/nao-fleet.sh check",
     "prepack": "bash .agents/scripts/nao-fleet.sh check"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nathan3303/nao-skills.git"
+  },
+  "homepage": "https://github.com/Nathan3303/nao-skills",
+  "bugs": {
+    "url": "https://github.com/Nathan3303/nao-skills/issues"
   }
 }