pi-dev-pipeline · 通用多 Agent 协作编排系统（Pi 扩展包）

一套不绑定具体业务的多 Agent 协作编排系统，打包为 Pi 扩展包。底座是 Pi（agent harness），承载是 飞书（Base WBS 看板 + 任务 + 文档），核心机制是任务总线 + 回执闭环 + 标准对接格式 + RBAC 权限 + 分组分类的专业 WBS 看板。

📖 快速上手（使用手册）

安装后怎么用？见 docs/USAGE.md：安装 → 初始化 → 飞书群交互 → 角色 skill → 查进度 → 状态流转 → 排障。

一键安装

# 方式 1：本地目录安装（开发/测试）
pi install D:/code/wangjian/agents

# 方式 2：从 git 安装（发布后）
pi install git:github.com/<you>/pi-dev-pipeline

# 方式 3：从 npm 安装（发布后）
pi install npm:@<scope>/pi-dev-pipeline

# 方式 4：不安装，先试跑
pi -e D:/code/wangjian/agents

安装后跑初始化（检测依赖 skill、飞书通道包、校验结构、任务总线 smoke）：

npm run init      # 或 node scripts/init.js

新项目：把扩展带进项目自己的 .pi/

本包既支持全局安装（上述），也支持每个新项目自带一份副本——把可运行资源铺进项目的 .pi/ 目录，项目自包含、不依赖全局。pi 会在项目被信任后自动发现 .pi/extensions|skills|prompts。

# 在新项目目录（或指定 --target）执行：
node <pi-dev-pipeline>/scripts/scaffold.js --target /path/to/your-project --project-name "你的项目" --chat-id "群id"

它会铺进项目 .pi/：

你的项目/.pi/
├─ extensions/feishu-adapter.js   飞书长连接适配（pi 自动加载）
├─ lib/                           task-bus / feishu-wbs / project-registry
├─ skills/                        6 个角色 skill
├─ prompts/                       需求/PRD/交接模板
└─ README.md

feishu-adapter 的相对 require('../lib/') 在 .pi/ 内仍成立，副本完全可运行（已验证）。

快速验证

npm test          # 3 个测试套件：任务总线 / 飞书适配 / 多项目路由，20 断言
node extensions/feishu-adapter.js --mock   # 飞书适配逻辑自检（无凭证）
node scripts/wbs-init.js --dry-run         # 预览建表命令

目录结构（Pi 包）

pi-dev-pipeline/
├─ package.json           包元数据 + "pi-package" + pi manifest（extensions/skills/prompts）
├─ extensions/
│  └─ feishu-adapter.js   唯一的 Pi 扩展：监听飞书消息 → 路由项目 → 意图解析 → 写 WBS
├─ lib/                   内部模块（被 require，不被 pi 加载）
│  ├─ task-bus.js         任务总线：多渠道收口 + 状态机 + RBAC + 回执 + human_confirm gate
│  ├─ feishu-wbs.js       飞书 WBS Base 读写（createTask 写专业字段）
│  └─ project-registry.js 多项目注册表（chatId → 项目 WBS）
├─ skills/                每个角色 = 一个 skill（按需加载）
│  ├─ orchestrator-role/  PM：编排 + 兼任需求澄清
│  ├─ architect-role/     架构师
│  ├─ dev-role/           开发
│  ├─ reviewer-role/      审查
│  ├─ qa-role/            测试质检
│  └─ release-role/       集成发布
├─ prompts/               prompt templates（requirement / prd / handoff）
├─ schema/                标准对接格式（task-card / receipt / review-report / test-report）
├─ docs/
│  ├─ pipeline.md         全流程定义
│  ├─ state-machine.md    任务状态机（13 态）
│  ├─ skills-map.md       角色 × Skill × 交接标准
│  ├─ permissions.md      RBAC 权限边界
│  ├─ bootstrap.md        项目初始化判定（从零 vs 接手）
│  ├─ memory.md           单会话 + 压缩 + 三层记忆
│  ├─ human-confirm.md    人工确认节点
│  └─ setup.md            飞书接入配置
├─ scripts/
│  ├─ init.js             初始化：检测依赖 + 结构 + smoke
│  ├─ scaffold.js         新项目脚手架：把扩展铺进项目 .pi/（项目自包含）
│  ├─ wbs-init.js         项目初始化：自动建专业 WBS Base 表（分组分类视图）
│  ├─ live-listener.js    真实飞书长连接监听（收群消息 → 写 WBS）
│  └─ e2e-test.js         端到端测试（写 WBS + 状态流转 + 回读）
├─ tests/                 run.js + 3 套件
├─ projects.json          项目渠道注册表（chatId → 项目）
└─ README.md

依赖（外部，不进包，由 init.js 检测）

依赖	用途	安装方式
mattpocock 工程 skill（15 个）	grill/to-tickets/handoff/code-review/implement...	拷贝到 ~/.agents/skills/ 或 pi install
@amaster.ai/pi-channels	飞书长连接收发消息	pi install npm:@amaster.ai/pi-channels
@amaster.ai/pi-lark	飞书工作区操作（读写 Base/文档）	pi install npm:@amaster.ai/pi-lark

npm run init 自动检测三者，缺失会提示安装。

飞书接入（一次性 setup）

1. 凭证：在飞书开放平台建自建应用，开通权限（im:message 收发、bitable:app 多维表格、im.message.receive_v1 事件订阅 + 长连接），发布版本。
2. 配置：把 appId/appSecret 写入 ~/.pi/agent/settings.json（pi-channels.feishu 段，eventMode=websocket）。
3. 建 WBS 表：拿 workspace-token（我的空间文件夹 token），跑 node scripts/wbs-init.js --project-name <名> --chat-id <群id>，自动建专业 Base + 分组视图 + 注册项目。
4. 长连接监听：node scripts/live-listener.js，群里 @机器人 提需求 → 自动建 WBS 任务卡。

详细见 docs/setup.md。

专业 WBS 看板（分组 + 分类）

项目初始化自动建，21 字段 + 5 个分组视图：

• 字段：工作包名称 · WBS编号(自动) · 类别(需求/设计/开发/测试/发布/管理) · 模块/子系统(横向分类) · 所属阶段(启动/规划/执行/监控/收尾) · 状态(13态) · 负责人 · 优先级 · 里程碑 · 计划开始/完成 · 预估工时 · 依赖 · 交付物 · 验收标准 · 所属项目 · 返工次数 · 回执 · 更新时间 · 创建时间
• 视图：看板-类别 / 看板-模块 / 看板-阶段 / 看板-负责人 / 看板-状态

核心机制

• 多渠道收口：PM/飞书 Hook/Git Issue/CLI → 统一 task-card.json
• 回执闭环：每个状态迁移产出一份 receipt.json，返回到来源渠道
• 标准对接格式：每阶段输入/输出绑定 schema
• RBAC 权限：状态迁移须同时满足「状态机白名单」+「角色权限」，越权被拦截
• 直连返工：dev→qa 发现 bug → rejected 附 bug 详情 → 直连 dev，不走 PM 重派
• 人工确认门：done / delivered / cancelled 需 human_confirm（docs/human-confirm.md）
• WBS 单一事实来源：飞书 Base WBS 看板是 source of truth

状态机（13 态）

created → assigned → claimed → in_progress → ready_for_review → in_review → approved/rejected → done → delivered → archived （含 blocked / cancelled，详见 docs/state-machine.md）

角色（默认精简，按需扩展）

• 默认：PM（编排+澄清）→ Dev → Reviewer/QA → Release
• 按需：Architect（方案复杂）、PO（多需求源）、Archivist（交付后）