多 Agent 编排调度系统 — 让 AI agent 组队协作
pi-multi-agent 是一个运行在 pi-coding-agent 之上的多 Agent 编排层。它不是一个新的运行时，而是一个扩展——给 pi 装上了调度器、任务队列、黑板、Dashboard 和工作流引擎，让你能在一次对话里派遣多个 AI agent 并行工作。
想象一下：你说"帮我重构这个模块"，编排器自动组建架构委员会（2 个 analyzer 辩论方案）→ 工程团队（2 个 coder 并行实现）→ 质保团队（测试 + 审查），全程你只需要看 Dashboard。
pi-multi-agent/
├── packages/
│ ├── pi-multi-agent-core/ ← 编排引擎
│ │ ├── extension/index.ts # 入口 · 17 个 agent 工具
│ │ ├── extension/public-api.ts # 对外接口（dashboard 唯一入口）
│ │ ├── extension/dispatcher.ts # 调度核心
│ │ ├── extension/fleet.ts # Agent 驻点注册
│ │ ├── extension/event-bus.ts # 事件系统
│ │ ├── extension/scheduler.ts # 子 Agent 调度
│ │ ├── extension/workflow.ts # 工作流模板
│ │ └── extension/agents/ # Agent 类型定义
│ │
│ └── pi-multi-agent-dashboard/ ← 仪表盘（独立扩展）
│ ├── extension/index.ts # Dashboard 入口
│ ├── extension/dashboard-server.ts # HTTP Server
│ ├── extension/widget.ts # 状态栏组件
│ ├── extension/overlay.ts # Fleet 浮层面板
│ └── extension/dashboard-web/ # SPA 前端
| 包 | 定位 | 依赖 |
|---|---|---|
| pi-multi-agent-core | 编排引擎 —— agent 生命周期、事件持久化、工作流 | @earendil-works/pi-coding-agent |
| pi-multi-agent-dashboard | 仪表盘 —— Web UI + TUI overlay，leader/follower 选举 | pi-multi-agent-core (public-api) |
Dashboard 只通过 public-api.ts 读取 core 数据，不碰内部模块。不装 dashboard 也能用 core。
| 概念 | 说明 |
|---|---|
| 编排器 (Orchestrator) | 运行在 pi 会话里的调度器，控制 agent 的一生 |
| Agent | 独立的 AI 工作单元 —— coder（写代码）、analyzer（分析）、git-ops（Git 操作） |
| Station | Agent 在工作目录里的"工位"，记录路径、身份、状态 |
| Fleet | 所有 Station 的注册表，全局可见 |
| 黑板 (Blackboard) | Agent 之间的共享内存，键值对读写 |
| Memory | 滑动窗口记忆，跨 turn 保持上下文 |
| 事件系统 | 所有状态变更写入 events.jsonl，重启可恢复 |
# 进入 core 包
cd packages/pi-multi-agent-core
# 安装依赖
npm install
# 运行测试
npm test
# 类型检查
npx tsc --noEmitDashboard 由 pi-coding-agent 自动加载，无需手动启动。浏览器打开 http://127.0.0.1:7878 即可看到。
所有工具由编排器（Orchestrator）在对话中调用：
| 工具 | 功能 |
|---|---|
agent_setup |
一站式派遣：定义类型 → 派到路径 → 设置身份 |
agent_command |
向 agent 发异步任务，立即返回句柄 |
agent_command_batch |
批量并行派发，消除串行瓶颈 |
agent_recall |
召回 agent，释放资源 |
agent_status |
查看所有 agent 状态和队列 |
agent_forward |
通过黑板在 agent 间传递数据 |
agent_queue |
任务队列：排队 / 执行 / 清理 |
agent_logs |
查看 agent 执行历史和输出 |
agent_open_dashboard |
获取 Dashboard URL |
agent_compact |
压缩 agent 上下文（防 token 溢出） |
agent_clear |
清空 agent 上下文，从零开始 |
agent_stop |
立即中断 agent 当前任务 |
agent_identity |
设置 agent 的显示名称和角色定位 |
agent_fork |
克隆 agent 到隔离工作目录 |
agent_merge |
把 fork agent 的改动合并回来 |
agent_config |
用户配置管理（持久化到 .multi-agent/config.json） |
agent_workflow |
工作流模板：查看 / 获取详情 |
agent_setup({ type: "coder", path: "/project" })
agent_command("coder-1", "修一下 login 页面的 bug")
1. 架构委员会：2 个 analyzer 独立分析 → 辩论 → 共识
2. 工程团队：2 个 coder 并行实现
3. 质保团队：测试 + 架构审查 → 签字
4. 合并 → 清理
agent_fork("coder-1", { branch: "feature/auth" }) → 创建隔离副本
agent_command("coder-4", "实现登录功能") → 在副本工作
agent_merge("coder-4") → 合回主干
Web Dashboard (http://127.0.0.1:7878) —— 实时监控所有 pi session 的 agent 活动：
- 按 session tab 分组，多会话同时监控
- Agent 状态卡片（空闲/运行/错误）
- Context bar（绿色/黄色/红色）
- Token 消耗趋势图
- 流水线可视化
- leader/follower 自动选举，跨 session 聚合
TUI Overlay (Ctrl+Alt+Shift+A) —— 终端内的 fleet 总览面板，无需切浏览器。
| 项目 | 说明 |
|---|---|
| pi-orchestrator | pi 原生编排器 —— session 拆分、子 agent 执行 |
| pi-toolbox | pi 工具箱 —— better-copy、model-stats、mac-notify 等 |
| pi-extension | pi 扩展注册中心 |
MIT © 2026 GOODDAYDAY