nao-skills

给你的 AI 编程助手配一支「开发小队」：你提需求，它自己找人干活、自己验收交付。

nao-skills 是一套 角色卡 + 协作规矩 + 小工具。装上以后，你的项目里会有 6 个分工明确的 AI 会话——产品经理负责拆需求、派活、验收；前端、后端、测试各自干活；工程基座管构建发布与治理。你只做两件事：回答问题、点确认。

基于 pi。Made by Nathan Lee。

它解决什么问题

一个人对着 AI 写代码，常见三个毛病：

安装（1 分钟）

前置依赖：pi。没装 pi 也能看到这套文件，但跑不起来舰队。

1. 把机制装进项目（项目级，版本 pin 在仓库里，团队 clone 即得同款）：

   cd 你的项目
   pi install --local npm:@nathan33/nao-skill@0.13.0   # 声明 pin + 把机制包物化到项目内 .pi/npm
   npx @nathan33/nao-skill init                        # 写入转发 shim + 生成 AGENTS.md

2. 装协作插件（多会话派活必需）：

   npx @nathan33/nao-skill plugins install-all

升级：改 .pi/settings.json 里的 pin 版本，再 pi update --extensions（机制以包为准，项目里只有 shim）。

老项目迁移（曾在项目里铺开整套 .agents/ 的）：

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 的语义是「本机已安装机制包版本」（供升级检测），不表达迁移状态——迁移状态由「是否还有旧资产」推断。

用起来（3 步）

.agents/scripts/nao-fleet.sh check                          # 体检：一行 OK 就能开工
.agents/scripts/nao-fleet.sh ensure pm arch rd-fe rd-be qa rd-infra   # 拉起 6 个角色会话

角色名可以写别名或规范名（两者等价）：arch = arch-designer、infra = rd-infra；上例里两者混用也照常拉起。完整别名表见 .agents/roles.yaml 或 nao-fleet.sh --help。

然后在 PM 会话里说需求就行，剩下的它自己流转。大概长这样：

你：想加个「导出 CSV」功能
PM：问几个问题 → 给出 PRD + 优先级 + 开工确认卡
你：开工
PM：拉起缺的角色 → 让 qa 先写用例 → 指派给 rd-be
rd-be：（做完）[T1] done | 测试：npm test exit=0 128例/0红 | PR #12
PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash 合并 → 归档 docs/prds/ → 回收后台会话

每个任务完成后都能在 docs/ 里找到痕迹（PRD、任务状态、回报），不依赖聊天记录——所以会话聊久了可以直接重开，不会丢事。

六个角色

不想要哪个角色，删掉对应文件即可；只留 PM + 一个研发角色也能跑。

可选：关键节点 QQ 主动推送

装上 pi-agent-qqbot 并配好 ~/.pi/agent/pi-agent-qqbot.json（appId / clientSecret / ownerOpenId / sandbox）后，PM 可把关键节点主动推到你 QQ——批次进度汇总、验收结论、发版或合并完成、异常阻塞：

$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 聊天，钱花在「它每轮要读多少字」。所以：

• 常驻的东西尽量小：每个角色卡只留最硬的红线，细节放到用到时才读的文件里。
• 按需才读：设计规范、检查清单、读代码手册，都是在需要那一刻才读进上下文。
• 不靠聊天记录记事：任务状态和待办写在 docs/ 文件里；会话重开先读文件恢复状态。
• 查代码用索引：配了 CodeGraph 就一次拿到相关代码块，比全文搜索省一个数量级。

一句话概括定位：这是在给 AI 做「上下文工程」——决定每个会话该看到什么、不该看到什么；在这之上再叠了多会话协作和交付纪律。它自己不跑 AI，产出的是给 AI 读的 Markdown。

常见问题

会改我的代码库吗？ 只会新增项目根 AGENTS.md、.pi/settings.json，以及一个转发入口 .agents/scripts/nao-fleet.sh；角色卡、清单、技能这些机制文件都在依赖包内，不再铺进你的仓库，也不碰你原有文件。

只能用 pi 吗？ 角色卡和技能本质就是 Markdown，Claude Code 等也能读；但"派活 / 回执"这种多会话协作依赖 pi + pi-intercom 插件。

它会在 GitHub 上开 PR 吗？ 会——每个需求一条分支、一个 PR（Draft 早开、CI 早跑），你确认验收后由研发角色 squash 合并，main 上只留 1 条可读提交。没有远端或 gh 时降级为本地分支，流程不变。

跑完的会话要留着吗？ 后台派生会话验收完可以回收：nao-fleet.sh close --task T1 rd-be（等价写法 nao-fleet.sh close rd-be-T1，直接用派生会话名即可）；常驻角色留着复用。nao-fleet.sh status 会提示哪些是残留。目标在别的项目里也能回收——close 会按名册/窗口标题跨项目定位；定位不到时会非 0 退出并打印诊断，不会假装已回收。

终端窗口太挤怎么办？ 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/），抓来的网页内容不会堆进聊天记录；技术选型仍然只由架构师定。

装完之后项目里多了什么？

你的项目/
├── AGENTS.md              # 项目级约定（PM 维护，AI 每次都会读）
├── .github/               # PR 模板（PM 建，GitHub Flow 用）
├── .pi/
│   ├── settings.json      # 记录机制包的 pin 版本（进仓库）
│   └── npm/               # pi 把机制包物化在这里（pi 自建 gitignore，不提交）
└── .agents/
    └── scripts/
        └── nao-fleet.sh    # 转发入口（shim）：自动定位包内机制并转发

机制本体（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 环境必读）

• .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: + 恢复命令。

下游仓库迁移（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/nao-skill 引用 ⇒ 迁移判定为纯文档迁移，不建转发入口（可显式 --shim 强制；也可 --no-shim 强制不建）；它的 .agents/commands/、.agents/prompts/ 不在 pi 的 skill 扫描面（pi 只扫 .agents/skills/**）。

想深入

README 只讲怎么用。真正的机制都在依赖包 @nathan33/nao-skill 的 .agents/ 里（会话里以 $NAO_SKILLS/.agents/ 指向），想改就从这几处入手：

License

MIT © 2026 Nathan Lee