<div align="center">

<img src="./pi-super-devteam-logo.svg" alt="pi-super-devteam logo" width="160" />

# pi-super-devteam

[简体中文](README.md) | [English](README_EN.md)

**给 [pi](https://github.com/earendil-works/pi) 装上一套「项目总监固件」**

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

[![npm version](https://img.shields.io/npm/v/pi-super-devteam?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/pi-super-devteam)
[![CI](https://img.shields.io/github/actions/workflow/status/patrickleehua/pi-super-devteam/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/patrickleehua/pi-super-devteam/actions/workflows/ci.yml)
[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![License](https://img.shields.io/github/license/patrickleehua/pi-super-devteam?style=flat-square&color=22c55e)](LICENSE)

[快速开始](#quick-start) · [核心能力](#core-capabilities) · [工作方式](#how-it-works) · [命令参考](#command-reference) · [开发指南](#development)

</div>

---

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

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

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

<a id="quick-start"></a>

## 快速开始

### 环境要求

- pi ≥ 0.84
- Node.js ≥ 20

### 安装

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

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

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

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

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

```bash
pi
```

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

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

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

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

<a id="core-capabilities"></a>

## 核心能力

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

<a id="how-it-works"></a>

## 工作方式

```mermaid
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. **增强能力可降级**：任何增强环节失败，都回退到确定性地板，而不是阻塞整个交付。

<a id="command-reference"></a>

## 命令参考

| 命令 | 作用 |
|---|---|
| `/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 工程师 | 构建、配置、部署和发布就绪度 |

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

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

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

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

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

<details>
<summary><strong>模型工具参考（9 个）</strong></summary>

| 工具 | 作用 |
|---|---|
| `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` | 沉淀有证据的教训，并按失败指纹累计复发次数 |

</details>

## 并行执行（可选）

安装 [`pi-subagents`](https://github.com/nicobailon/pi-subagents) 后，会自动启用隔离 worktree 并行执行；未安装时保持串行运行，不构成硬依赖。

```bash
pi install npm:pi-subagents
```

并行派发前会强制检查：

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

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

## 状态与配置

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

```text
.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`：

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

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

<a id="development"></a>

## 开发指南

```bash
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`。

<details>
<summary><strong>为什么 CI 不直接相信测试进程退出码？</strong></summary>

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

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

</details>

### 本地调试

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

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

### 发布

发布由 Git tag 自动触发：

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

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

## 致谢

项目的业务模型迁移自 [UmaDev](https://github.com/umacloud/umadev)：包括团队宪法、意图路由、显式团队、可恢复计划、确定性验收、有界返工、知识复利和可审计交付。

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

## License

基于 [MIT License](LICENSE) 开源。

---

<div align="center">

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

</div>