@nathan33/nao-skill 0.7.1 → 0.9.3

package/.agents/skills/pm-routing.md

@@ -0,0 +1,31 @@
+---
+description: 按需技能——PM 路由与派单纪律（角色路由口诀 / 技术调研边界）
+---
+
+# PM 路由与派单纪律
+
+> 触发：**派发前**（决定派给谁）与**调研前**（判断是否越界）读取；其余时候不加载。
+> 角色清单与别名以 `.agents/roles.yaml` 为唯一事实来源；`rd-infra` 边界见 @.agents/prompts/infra-engineer.md §一。
+
+## 一、路由口诀
+
+> **改「业务行为」⇒ `rd-fe`/`rd-be`；改「怎么构建 / 怎么验 / 怎么发 / 怎么治理」⇒ `rd-infra`。**
+
+- **工程基座类 ⇒ `rd-infra`，不再由 `rd-be` 兜底**：CI 与流水线 · 构建/发布工具 · 脚本与守卫（`guard:*`、fleet 脚本） · 依赖与安全告警升级 · 仓库治理（分支/保护/清理/baseline 合并执行） · lint 与格式化工具链 · 跨项目安装器与分发 · 开发环境排障。
+- **兜底纪律（无匹配角色时）**：**显式声明 + 选最接近专精角色 + 临时附加清单 + 台账登记**——**不许默默兜底**。
+- 三条例外（避免口诀被滥用）：① 架构取舍（选型/分层/契约）先经 `arch-designer`，`rd-infra` 只落地已定方案；② 验收口径与断言归属 `qa`/`pm`，`rd-infra` **不自验自己的守卫**；③ 工程基座改动**触碰业务语义**时拆单，业务部分回 `rd-fe`/`rd-be`。
+
+## 二、技术调研边界
+
+> 依据：TASK-23 越界调研真实案例——PM 亲自读仓储实现 / sweep 机制 / 服务端 Go 源码 / 限流桶与排序语义，据此形成**错误前提**（误判服务端字段不可用），用户在错误前提下多做一轮选择，最终由 arch 以更硬理由拉回。**越界调研的实际成本 = 无效决策轮次。**
+
+- **PM 可自做（简略调研）**：① 粗略分析任务设计的**技术深度**（供范围划分与派发，不下结论）；② UI/文案/样式/交互的**落点确认**（组件在哪、有无可复用件、i18n 键、插槽/属性支持）；③ 读 `docs/prds` / `docs/adr` / `docs/tasks-state.md` 等**决策留痕**；④ 判断任务编号与范围划分；⑤ **产品形态业界调研**（同类功能有哪些功能点 / 属性 / 组织结构 / 视图 / 协作 / 生命周期；清单与检索纪律见 @.agents/skills/research.md）——只作**参考**，不得据此下技术结论。
+- **必须转角色（任一命中即转，PM 不自行下结论）**：
+  1. 出现「哪个方案更好」的**取舍**；
+  2. 需读 `packages/domain-*` / `packages/infrastructure` / 服务端 / 构建配置 / 同步链；
+  3. 结论会**改变 PRD 范围或 AC**；
+  4. 影响面跨 **>1 个包或 >1 个端**；
+  5. 涉及性能量级、限流、契约字段语义、枚举/排序语义；
+  6. 任何以外部文章/竞品做法为依据的**技术结论**（该用哪个方案/库/中间件）。
+- **转发对象**：技术选型与影响面 → `arch-designer`；验收策略与用例 → `qa`；实现细节 → `rd-fe` / `rd-be`；**工程基座（CI/构建/发布/脚本守卫/依赖安全/仓库治理）→ `rd-infra`**。
+- **判定口径**：不确定是否越界时**按越界处理**（转角色），不以「省一轮」为由自行下结论。

package/.agents/skills/qq-notify.md

@@ -0,0 +1,87 @@
+---
+description: 按需技能——QQ 主动推送（关键节点通知；PM 在里程碑/阻塞时读取）
+---
+
+# QQ 主动推送（qq-notify）
+
+## 触发时机
+
+**仅关键节点**由 PM 使用，读本文件确认纪律后调用；日常轮次不加载、不发送。
+本能力**可选**：未配置 `pi-agent-qqbot` 时不要使用，按普通回执继续交付。
+
+## 定位与能力边界
+
+- 把「关键节点」用 QQ 官方机器人的**主动消息**推给 owner，让用户离开工位也能收到交付信号。
+- **主动消息**（不带 `msg_id`）受 **QQ 开放平台账号权限与月度配额**限制：配额用尽或未开通对应权限时发送会失败（exit 3），**不得重试轰炸**。
+- 只做**单向推送**，不做接收/被动回复；不做定时调度、不做退避重发（这些是平台与宿主的事）。
+- **默认 sandbox**：`pi-agent-qqbot.json` 中 `sandbox: true` 走测试环境，`false` 才走 `prod`。**两者权限与收件人不通用**，切换 prod 前先确认机器人已在正式环境配置好。
+
+## 何时用（四类节点，仅此四类）
+
+| 节点 | 典型内容 |
+| :--- | :--- |
+| 批次进度汇总 | 一个批次开始/收尾时的整体进度（不是每个子任务） |
+| 验收结论 | PM 验收通过 / 驳回，含 PR 编号与一句话结论 |
+| 发版或合并完成 | tag / Release / squash 合并完成，含版本号 |
+| 异常阻塞 | 需要用户决策、外部依赖卡住、门禁长期红 |
+
+## 纪律（禁刷屏）
+
+- **一个节点最多一条**；同一批次不逐任务推送。
+- 推文用**一句话**：`[编号] 结论 + 关键数字/链接`，不贴长正文（正文留 `docs/`）。
+- 用户未回应不重复推；阻塞未解除才允许在**跨天**时补一条。
+- **默认 sandbox**，仅在正式发布通知用户时考虑 prod（须用户明确知情）。
+
+## 调用禁令（⛔ 重要：曾因此误发过真实消息）
+
+本脚本是 **Node 程序**，文件头部的注释里写着用法示例。⛔ **禁止用 shell 把它当 shell 脚本逐行解释**：
+
+```text
+⛔ bash .agents/scripts/qq-notify "文本"     ← 错：shell 会执行注释里的示例
+```
+
+原因（实测）：`bash <本脚本>` 会把注释当命令执行——注释里的 `*` 触发 **glob 展开**（把 `AGENTS.md apps docs …` 当命令跑）、`--to <openid>` 变成 **重定向**、`echo "文本" | qq-notify` 变成 **真实管道**（PATH 命中同名脚本即**真发**）——本仓历史上正因此误发过一条真实 QQ 消息。
+
+**正确形式（三者等价，均 rc=0 且输出一致）**：
+
+```bash
+.agents/scripts/qq-notify "文本"      # ./ 直接执行（推荐）
+node .agents/scripts/qq-notify "文本"  # 显式用 node
+sh .agents/scripts/qq-notify "文本"    # 已加固：头部 exec 守卫自动转交 node
+```
+
+> 加固方式（v0.9.2）：第 1 行 `#!/bin/sh` + 第 2 行 `//bin/true; exec node "$0" "$@"`。
+> `sh/bash` 执行时第 2 行即 `exec node`（**自动转交**，注释不会再被 shell 解析）；`node` 执行时第 2 行是 JS 注释。
+> `nao-fleet.sh check` 已增加该守卫的存在性校验（缺失 ⇒ rc=1）。
+
+## 用法
+
+```bash
+# 安装后位于当前项目：.agents/scripts/qq-notify
+.agents/scripts/qq-notify "[T301] 验收通过 · PR #4 已合并 · v0.8.0"
+.agents/scripts/qq-notify --dry-run "连通性自检"      # 只取 token、不发送
+echo "文本" | .agents/scripts/qq-notify               # 从 stdin 读
+.agents/scripts/qq-notify --to <openid> "文本"        # 指定收件人
+.agents/scripts/qq-notify -h                          # 帮助
+```
+
+- 配置优先级：`--config <path>` > 环境变量 `QQ_NOTIFY_CONFIG` > `~/.pi/agent/pi-agent-qqbot.json`
+- 配置文件字段：`{ "appId", "clientSecret", "ownerOpenId", "sandbox" }`；**无此文件即视为未启用本能力**（exit 1）。
+
+## 退出码与失败回报
+
+| 退出码 | 含义 | 处理 |
+| :--- | :--- | :--- |
+| `0` | 发送成功（或 `--dry-run` 取 token 成功） | 正常，可在回执记一行 `notify=ok` |
+| `1` | 参数或配置错（缺文本 / 读不到配置 / 缺 `ownerOpenId`） | 按 stderr 的 `→` 提示修复；**不要重试**，先补配置 |
+| `2` | 取 access token 失败（网络 / 凭证错误） | 报出 `status` 与截断错误体；不重试轰炸 |
+| `3` | 发送失败（权限 / 配额 / openid 非法） | 报出 `status` 与截断错误体；主动消息受权限与配额限制 |
+
+- 失败时**不抛栈**：脚本输出 `FAIL: …` 与一行可执行修复提示，**非 0 退出码 + 截断错误体**即为回报内容。
+- 推送失败**不阻断交付**：把 `notify=fail(exit=<n>)` 写进回执的风险项，继续原流程。
+- **安全**：脚本绝不打印/落盘 `clientSecret` 与 `access_token`；回执中也不要粘贴这两者。
+
+## 跨项目用法
+
+安装后脚本固定位于 **`<项目>/.agents/scripts/qq-notify`**（随 `nao-skill install/update` 整目录分发）。
+在项目里直接用相对路径调用；从别的仓库操作时用绝对路径 `.agents/scripts/qq-notify`（可配 `NAO_SKILLS`）。

package/.agents/skills/research.md

@@ -16,7 +16,7 @@ description: 按需技能——外部调研协议（产品形态可查；技术
 | **RD** | 具体库/API/SDK 用法、报错与版本事实 | 自定架构方案（转 arch） |
 | **qa** | 测试策略、工具与业界用例惯例 | 替代 RD 定实现 |
 
-- PM 命中「不可调研」任一项 → **停止检索，转 arch**（见 PM 卡 §九）。
+- PM 命中「不可调研」任一项 → **停止检索，转 arch**（见 @.agents/skills/pm-routing.md §二）。
 - 不确定是否越界 → **按越界处理**。
 - 外部做法一律是**参考与候选**，不是既定前提；**技术前提只能由 arch 以 ADR 定**。
 

package/.agents/skills/test-design.md

@@ -12,6 +12,15 @@ description: 按需技能——用例设计、缺陷管理、性能安全、DDD
 - **场景法**：主路径 + 异常 + 边界
 - **错误推测**：并发、超时、断网、重复提交、空值、超长输入
 
+## 反事实守卫（把静态推断升级为实测结论）
+
+当要验证的是「实现/契约的静态推断」而非现成行为时，用**两段式探针**，避免只在单侧证据上下结论：
+
+- **S1 实际链路**：用**真实现 + 真编排**（如真 repo + 真 SyncService）跑端到端；mock 只复现**外部系统**（服务端/网络）的**真源语义**——引源码行号，不复制逻辑；有源码仓时优先临时单测直调真源函数（如 Go converter），测后删除。
+- **S2 反事实分支**：独立断言「假设推断成立」时的后果。两段合读才能区分：**命题为假** / **命题为真** / **命题的前置在上游先行被阻断**（最常见误区：推断的上游前提不成立）。
+- **守卫化**：S2 保留为**反事实守卫**（当前绿）——修复后它应**转红**，届时改为**正向不变量**（如「往返后必须命中」）并在文件头注明；放 `__tests__/**`，红/绿分列说明。
+- **绑定版本**：结论显式绑定被测外部系统版本（commit）；版本一变结论可能翻转（如服务端对齐修法）。
+
 ## DDD 分层对齐表
 
 | 层 | 测试方式 | 覆盖内容 |

package/README.md

@@ -2,7 +2,7 @@
 
 > 给你的 AI 编程助手配一支「开发小队」：你提需求，它自己找人干活、自己验收交付。
 
-nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，你的项目里会有 5 个分工明确的 AI 会话——产品经理负责拆需求、派活、验收；前端、后端、测试各自干活。你只做两件事：**回答问题**、**点确认**。
+nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，你的项目里会有 6 个分工明确的 AI 会话——产品经理负责拆需求、派活、验收；前端、后端、测试各自干活；工程基座管构建发布与治理。你只做两件事：**回答问题**、**点确认**。
 
 基于 [pi](https://pi.dev)。Made by [Nathan Lee](https://github.com/nathan)。
 
@@ -12,7 +12,7 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
 | 毛病 | nao-skills 的做法 |
 | --- | --- |
-| 一个会话什么都干，聊到后面就糊涂了 | 拆成 5 个专业角色，各管一段，互不干扰 |
+| 一个会话什么都干，聊到后面就糊涂了 | 拆成 6 个专业角色，各管一段，互不干扰 |
 | 需求没问清楚就开写，写完发现不对 | PM 先追问、写清 PRD 和目标，你点头才开工 |
 | 干完不知道算不算干完 | 每个任务必须「回执」并按清单自查，PM 逐条验收才归档 |
 
@@ -33,7 +33,7 @@ nao-skill plugins install-all   # 装协作插件（intercom 等），多会话
 
 ```bash
 .agents/scripts/nao-fleet.sh check                          # 体检：一行 OK 就能开工
-.agents/scripts/nao-fleet.sh ensure pm arch rd-fe rd-be qa   # 拉起 5 个角色会话
+.agents/scripts/nao-fleet.sh ensure pm arch rd-fe rd-be qa rd-infra   # 拉起 6 个角色会话
 ```
 
 然后**在 PM 会话里说需求**就行，剩下的它自己流转。大概长这样：
@@ -49,17 +49,29 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 
 每个任务完成后都能在 `docs/` 里找到痕迹（PRD、任务状态、回报），不依赖聊天记录——所以会话聊久了可以直接重开，不会丢事。
 
-## 五个角色
+## 六个角色
 
 | 角色 | 帮你干什么 |
 | --- | --- |
 | 产品经理 | 澄清需求、**调研同类产品形态**、写 PRD、定优先级、派活、验收、归档、**管 Issue 与发版**（PR 验收评论、tag/release，优先 `gh`；唯一的调度者，不写代码、不合并） |
 | 架构师 | 技术选型与方案评审（**对照业界成熟模式**并写明为何不采纳），出 ADR，评影响面 |
 | 前端 / 后端研发 | 各自实现，写完自己跑测试再回执 |
+| 工程基座 | CI 与流水线、构建/发布工具、脚本与守卫、依赖与安全告警升级、仓库治理 |
 | 测试工程师 | 按验收标准出用例、跑门禁、报缺陷 |
 
 不想要哪个角色，删掉对应文件即可；只留 PM + 一个研发角色也能跑。
 
+## 可选：关键节点 QQ 主动推送
+
+装上 [`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、不发送
+```
+
+**为什么默认不主动打扰**：这是**可选能力**——没配 `pi-agent-qqbot` 就自动视为未启用；四类节点之外不发，一个节点最多一条（禁刷屏）；推送失败只记回执行风险项，**不阻断交付**。默认走 sandbox（测试环境），正式发布通知才考虑 prod。能力边界、退出码与纪律见 `.agents/skills/qq-notify.md`。
+
 ## 为什么它省 token（这是本项目的核心追求）
 
 和 AI 聊天，钱花在「它每轮要读多少字」。所以：
@@ -81,6 +93,8 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 
 **跑完的会话要留着吗？** 后台派生会话验收完可以回收：`nao-fleet.sh close --task T1 rd-be`；常驻角色留着复用。`nao-fleet.sh status` 会提示哪些是残留。
 
+**终端窗口太挤怎么办？** 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/`），抓来的网页内容不会堆进聊天记录；技术选型仍然只由架构师定。
 
 **装完之后项目里多了什么？**
@@ -90,7 +104,7 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 ├── AGENTS.md              # 项目级约定（PM 维护，AI 每次都会读）
 ├── .github/               # PR 模板（PM 建，GitHub Flow 用）
 └── .agents/
-    ├── prompts/           # 5 张角色卡
+    ├── prompts/           # 6 张角色卡
     ├── common/            # 协作规矩、输出与回执规范
     ├── checklists/        # 各角色红线 / 交付清单 / 回执模板（按需读）
     ├── skills/            # 按需技能（DDD 细节、代码定位、提交规范…）

package/bin/nao-skill.js

@@ -11,10 +11,10 @@
  *   - 目标项目无 .agents/ → 完整复制
  *   - 已有 .agents/       → 合并：同名条目保留项目既有（--force 则备份后覆盖）
  *   - 无 AGENTS.md        → 由模板生成（项目级上下文，PM 维护）
- *   - 已有 AGENTS.md      → 提示按 PM 卡 §七 合并规则手动追加，不自动覆盖
+ *   - 已有 AGENTS.md      → 提示按 PM 卡 §七 / skills/pm-operations.md §四 合并规则手动追加，不自动覆盖
  *
  * 使用（安装后）
- *   bash .agents/scripts/nao-fleet.sh check / ensure arch rd-fe ...
+ *   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';
@@ -174,14 +174,14 @@ function install(target, force, verbose) {
     writeFileSync(agentsMd, tpl);
     log('已生成 AGENTS.md（项目级上下文，PM 维护；保持精简 <120 行）。');
   } else {
-    warn('AGENTS.md 已存在：按 PM 卡 §七 合并规则手动追加「nao 舰队接入」区块，勿覆盖原文。');
+    warn('AGENTS.md 已存在：按 PM 卡 §七 / skills/pm-operations.md §四 合并规则手动追加「nao 舰队接入」区块，勿覆盖原文。');
   }
 
   log('');
   log('✔ 安装完成。下一步：');
   log('  bash .agents/scripts/nao-fleet.sh check                       # 体检');
   log('  bash .agents/scripts/nao-fleet.sh status                      # 在线状态');
-  log('  bash .agents/scripts/nao-fleet.sh ensure arch rd-fe rd-be qa  # 拉起舰队');
+  log('  bash .agents/scripts/nao-fleet.sh ensure arch rd-fe rd-be qa rd-infra  # 拉起舰队');
   log('  角色卡：.agents/prompts/ · 技能：.agents/skills/ · 交付清单：.agents/checklists/');
 }
 

package/package.json

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