pi-super-devteam

简体中文 | English

给 pi 装上一套「项目总监固件」

让 Coding Agent 从“会写代码的通用助手”，升级为一支 可规划、可评审、可验收、可恢复、对交付结果负责的工程团队。

快速开始 · 核心能力 · 工作方式 · 命令参考 · 开发指南

---

pi 提供模型，以及读写文件、Shell、搜索等执行能力。pi-super-devteam 在此之上补齐一套工程交付机制：意图路由、可见计划、单写者纪律、只读评审、确定性验收、有界返工和诚实的交付语言。

它不需要额外的 API Key，也不会在旁边运行第二套推理服务。所有真实读写、构建和测试仍由 pi 完成。

[!TIP] 闲聊和纯解释请求保持零流程开销；只有需要修改工作区的任务，才会按复杂度启用对应的交付流程。

快速开始

环境要求

• pi ≥ 0.84
• Node.js ≥ 20

安装

# 用户级安装，对所有项目生效
pi install npm:pi-super-devteam

# 或只安装到当前项目
pi install npm:pi-super-devteam -l

也可以从 GitHub 安装，或仅在当前会话中试用：

pi install git:github.com/patrickleehua/pi-super-devteam
pi -e npm:pi-super-devteam

安装后直接运行 pi，无需额外配置：

pi

然后像平常一样描述目标：

> 为这个项目增加用户登录功能，并补齐测试

需要明确进入完整的项目总监路径时，使用：

/dev 为这个项目增加用户登录功能，并补齐测试

核心能力

能力	它解决的问题
意图路由	区分闲聊、解释、小改、调试和完整构建，避免小题大做或大题小做
可见计划 DAG	将目标拆成可验证步骤并落盘，中断后仍可恢复，而不是只存在于上下文里
单写者纪律	同一工作区同一时刻只有一个写者，减少并发覆盖和不透明修改
只读交叉评审	评审席运行在工具受限的隔离进程中，只能检查，不能偷偷改产物
确定性验收	以文件、命令输出和退出事实判定完成，不接受“测试应该能过”
有界返工	失败后生成定点修复单，默认最多额外修复 2 次，避免无限“再优化”
诚实交付	只按证据输出 Clean、Partial 或 Blocked，不把流程结束冒充质量通过
优雅降级	路由、计划、评审或教训检索不可用时退回确定性地板，不让增强能力卡死任务

工作方式

flowchart LR
    A[用户目标] --> B{意图路由}
    B -->|闲聊 / 解释| C[直接响应]
    B -->|明确小改| D[快速执行]
    B -->|调试 / 构建| E[可见计划 DAG]
    E --> F[受控实施]
    D --> G
    F --> G[确定性验收]
    G -->|失败且仍有预算| H[定点修复]
    H --> F
    G -->|fast| J
    G -->|standard / deep| I[只读评审]
    I --> J[Clean / Partial / Blocked]

意图分流

类别	典型场景	写工作区
chat	闲聊、询问能力	否
explain	代码讲解、只读分析	否
quick_edit	范围明确的小改动	是
debug	定位并修复缺陷	是
build	新功能、真实产品、非平凡改动	是

交付深度

深度	计划	评审席	适用场景
fast	无重型计划	0	小改、窄范围修复
standard	3–6 步 DAG	≤ 3	常规功能、中型改动
deep	5–8 步 DAG	≤ 8	复杂产品、高风险改动

四条工程宪法

1. 单写者：只有主会话能修改当前工作区，所有写步骤按计划串行执行。
2. 评审并行但只读：评审席只拥有 read / grep / find / ls，物理上无法修改产物。
3. 事实控环，意见辅助：是否继续由文件、构建结果和退出事实决定；评审意见只形成修复清单。
4. 增强能力可降级：任何增强环节失败，都回退到确定性地板，而不是阻塞整个交付。

命令参考

命令	作用
/dev <目标>	强制以 build 路由执行完整目标
/dev-status	查看当前路由、计划、验收和评审状态
/dev-fleet	查看并行子代理能力与舰队状态
/dev-off	关闭流程自动注入；不可逆动作确认门仍然有效
/dev-on	重新开启项目总监固件
/dev-unlock	在崩溃或中断后强制释放工作区写锁
/dev-adopt-legacy	显式把旧版工作区级状态复制到当前 session

安全与质量地板

系统提示词只是软约束，真正的安全地板由工具调用拦截强制执行。

• 不可逆动作确认：git push --force、rm -rf、npm publish、kubectl delete、terraform destroy、数据库 DROP、创建 PR 等操作，执行前必须逐条展示动作、目标、影响、可恢复性和确切命令。
• 业务批准与工具授权分离：同意实施方案，不等于授权推送、部署或删除数据。
• 单写者写锁：计划存在未结算步骤但没有步骤持有写锁时，写操作会被阻断。
• 受保护路径：.env、密钥文件、node_modules/、.git/ 和锁文件需要单独确认。

[!IMPORTANT] /dev-off 关闭的是流程增强，不是安全保护。不可逆动作确认门始终生效；无 UI 的非交互环境会直接阻断此类操作，不会静默放行。

完成如何判定

dev_verify 会为每个步骤使用适用范围内最强的验收标准：

验收标准	判定依据
build-test	执行项目的 build、test、lint、typecheck，并检查真实结果
contract	执行项目配置的合同检查命令
source-present	检查承诺的文件是否真实存在且非空
review-clean	确认只读评审流程已结算；不代表没有 finding
turn-settled	最弱地板，仅在无法机械验证时使用

跑不了的检查记为 unavailable，不适用的检查记为 skipped——两者都不算通过。

交付如何分级

状态	条件
Clean	全部步骤完成、全部验收通过、没有残留 finding、没有缺席席位
Partial	存在未结算步骤、残留 finding、缺席评审席或 unavailable 检查
Blocked	存在被阻塞步骤或失败验收

没有计划和验收证据时只能判定为 Partial。评审步骤的 done 仅表示有界流程已经结算，不代表所有评审席接受交付。

八个专业席位

项目内置八个稳定角色，按任务类型、评审面和交付深度动态召集，而不是每次都全员出动。

席位	关注点
产品经理	用户价值、需求边界、验收条件
架构师	系统边界、API 合同、数据模型、技术约束
UI/UX 设计师	设计系统、组件状态、可访问性、视觉辨识度
前端工程师	客户端实现、状态完整性、响应式、接口接入
后端工程师	服务端分层、接口一致性、错误处理、数据访问
QA 工程师	需求追踪、关键路径、边界和回归证据
安全工程师	认证授权、注入、秘密管理、输入输出安全
DevOps 工程师	构建、配置、部署和发布就绪度

每个评审席都在隔离子进程中返回统一裁决：

{
  "role": "qa-engineer",
  "accepts": false,
  "blocking": ["FR-12 的无权限路径没有测试"],
  "advisory": ["可以增加会话过期的边界测试"],
  "evidence": ["output/app-prd.md#FR-12", "tests/auth.spec.ts"]
}

某席超时、不可用或返回无法解析的 JSON 时，会被记为缺席：既不会卡死团队，也不会被当成通过。

如需定制某个席位，在项目中创建同名文件即可覆盖包内默认定义：

你的项目/.pi/agents/security-engineer.md

工具	作用
dev_route	确定类别、任务种类、深度和团队
dev_plan	创建或推进计划 DAG，认领步骤并获取写锁
dev_verify	执行确定性验收，通过后才允许标记完成
dev_review	并行召集只读评审席交叉评审
dev_dispatch	将独立步骤派发到隔离 worktree，需要 pi-subagents
dev_steer	向运行中的子代理补充信息或纠偏，需要 pi-subagents
dev_deliver	根据证据生成 Clean / Partial / Blocked 交付结论
dev_note	向共享黑板追加事实、决策、假设或待确认项
dev_lesson	沉淀有证据的教训，并按失败指纹累计复发次数

并行执行（可选）

安装 pi-subagents 后，会自动启用隔离 worktree 并行执行；未安装时保持串行运行，不构成硬依赖。

pi install npm:pi-subagents

并行派发前会强制检查：

1. 所有目标都是就绪的 build 步骤；
2. 批次内部没有相互依赖，外部依赖均已完成；
3. 各步骤承诺的产出路径不重叠。

同一工作区同一时刻仍然只有一个写者。worktree 是相互隔离的独立工作区；合并回主干必须串行，且每个分支都要先通过自己的验收地板。

状态与配置

运行期状态全部落盘到项目内，确保中断后可恢复、交付过程可审计：

.pi/dev/                         # 运行期状态，已 gitignore
├── preferences.json              # 项目级固件开关
├── write-lock.json               # 项目级单写者锁及其 session 所有者
├── lessons.jsonl                 # 项目级教训库
├── config.json                   # 可选的验收命令覆盖
└── sessions/<session-id>/        # 当前 Pi session 独有的工作流
    ├── state.json                # QC 计数等 session 状态
    ├── route.json                # 当前路由卡
    ├── plan.json                 # 可恢复的计划 DAG
    ├── blackboard.md             # 决策、假设、待确认项
    ├── ledger.jsonl              # append-only 审计账本
    └── evidence/                 # 命令输出与评审原文

output/
└── <slug>-delivery.md     # 最终交付说明

自定义验收命令

项目会自动探测 npm、pnpm、yarn、bun、Cargo、Go 和 pytest。需要覆盖时，创建 .pi/dev/config.json：

{
  "build": "pnpm build",
  "test": "pnpm test -- --run",
  "lint": "pnpm lint",
  "typecheck": "tsc --noEmit",
  "contract": "node scripts/check-openapi-drift.js"
}

未配置 contract 时，合同检查会如实报告 unavailable，不会假装通过。

开发指南

git clone https://github.com/patrickleehua/pi-super-devteam.git
cd pi-super-devteam
npm install

npm test
npm run typecheck

当前回归套件包含 230 项断言：

检查组	断言数	覆盖重点
不可逆动作门	70	27 类危险命令、易误报项、受保护路径和写工具判定
注册链路	51	9 个工具、7 个命令、4 个事件、schema、结果渲染降级与 session 生命周期
会话状态	18	session 隔离、checkpoint 恢复、fork 分叉、跨 session 写锁和 legacy 迁移
业务不变量	32	计划 DAG、阻塞级联、单写者、交付判定、失败指纹
界面渲染	28	widget 门槛、中文对齐、图标宽度和评审进度
并行派发	31	依赖、产出冲突、脚本转义和 RPC 超时降级

测试运行在 pi 自己的扩展加载器中，不需要 API Key，也不会消耗模型调用。

会话状态按 Pi session 隔离：/new 不继承旧面板，/resume 恢复对应工作流，/fork 复制分叉点状态并独立演进。启动时如果要进入最近会话，请使用 pi -c；扩展会为 Pi 选中的会话恢复匹配的 super-devteam 状态。旧版 .pi/dev/ 状态不会自动附着到空白新会话，可在确认后使用 /dev-adopt-legacy。

pi 自己决定进程退出码，扩展中设置 process.exitCode 不会生效。因此 CI 会检查 stderr 中的 CHECKS_FAILED 标记，并确认输出包含测试汇总。手动检查可以使用：

npm test 2>&1 | tee out
! grep -q CHECKS_FAILED out

本地调试

将仓库入口写入目标项目的 .pi/settings.json，修改代码后在 pi 中执行 /reload：

{
  "extensions": ["/绝对路径/pi-super-devteam/src/index.ts"]
}

发布

发布由 Git tag 自动触发：

npm version patch     # 或 minor / major
git push --follow-tags

CI 会依次校验版本、执行类型检查和回归检查、使用 provenance 发布 npm 包，最后创建 GitHub Release。首次发版前需要在仓库中配置 npm Automation Token：NPM_TOKEN。

致谢

项目的业务模型迁移自 UmaDev：包括团队宪法、意图路由、显式团队、可恢复计划、确定性验收、有界返工、知识复利和可审计交付。

pi-super-devteam 是针对 pi 扩展体系的独立 TypeScript 实现，不复用 UmaDev 的 Rust 源码，也不依赖它的 CLI 或运行时。

License

基于 MIT License 开源。

---

让 Agent 不只是“做过”，而是能够证明“交付成立”。