pi teammate extension

为 pi 提供类似 Claude Code Agent Teams 的多智能体协作能力。

一个主会话作为 lead，创建多个拥有独立上下文窗口的持久 worker。Worker 共享任务列表、可直接互发消息，并能在收到消息时自动继续工作。适合大型任务拆分、并行调研、交叉审查和对抗式假设验证。

当前为 MVP。核心协作模型参考 Claude Code Agent Teams，但不是其内部实现的复制。

技术设计

• 中文技术实现解析
• 中文架构图（GPT Image 2）

功能

• 1–8 个独立 worker，会话内持续存在
• Worker 之间点对点消息与广播
• 消息自动唤醒空闲 worker
• Lead 自动接收 worker 消息并继续推理
• 共享任务列表：领取、分配、依赖、状态和完成证据
• 三种协作模式：
  • parallel：独立并行、减少重叠
  • debate：独立立论、互相质疑、尝试证伪、修正结论
  • review：生产者/批评者结构和质量门禁
• TUI 状态组件：worker 活动、任务进度和消息数量
• Worker 轮次上限和团队消息预算，降低失控循环风险
• 会话关闭或 /reload 时自动中止并释放 worker
• Worker token、轮次和费用统计
• 直接复用 lead 的完整 ModelRuntime，保留 OAuth、刷新状态、headers/env 与动态 Provider

安装

从 npm 安装

pi install npm:pi-teammate-extension

临时加载而不写入设置：

pi -e npm:pi-teammate-extension

开发方式

npm install
mkdir -p ~/.pi/agent/extensions/teammate
ln -sfn "$(pwd)/index.ts" ~/.pi/agent/extensions/teammate/index.ts
ln -sfn "$(pwd)/src" ~/.pi/agent/extensions/teammate/src

然后在 pi 中执行：

/reload

也可以临时测试：

pi -e ./index.ts

项目级安装

mkdir -p .pi/extensions/teammate
ln -sfn "/absolute/path/to/teammate/index.ts" .pi/extensions/teammate/index.ts
ln -sfn "/absolute/path/to/teammate/src" .pi/extensions/teammate/src

项目级扩展只会在项目被信任后加载。

使用

直接用自然语言要求 lead 创建团队：

创建 4 个 teammates 调查这个偶发连接中断问题。
分别从网络、状态机、并发和反方证伪角度分析；
让他们互相发送证据并尝试推翻对方假设，最后给我共识和剩余不确定性。

或者进行大型功能开发：

创建一个 parallel teammate 团队：
- architect 负责架构和接口边界
- backend 负责服务端模块
- frontend 负责 UI
- critic 负责测试、安全和反例
先明确任务依赖与文件所有权，再开始实现。

team_create 在 TUI/RPC 模式下会显示确认框。每个 worker 都会使用独立模型上下文，因此 token 消耗大致随 worker 数量增长。

Lead 工具

| 工具 | 用途 | |---|---| | team_create | 创建团队并异步启动 worker | | team_message | 私聊 worker 或用 * 广播 | | team_task | 管理共享任务、依赖和所有权 | | team_status | 查看 worker、任务、消息及费用状态 | | team_wait | 等待全部空闲、任务完成或新消息 | | team_shutdown | 停止单个 worker 或清理整个团队 |

Worker 只获得 team_message 和 team_task 协作工具，不能创建嵌套团队。

用户命令

/teammates
/team-tasks
/teammate-message <worker|*> <message>
/teammate-stop [worker|all]

工作机制

用户
  │
  ▼
Lead（当前 pi 会话）
  ├── shared task board
  ├── worker A（独立 AgentSession）◄──► worker B
  ├── worker C（独立 AgentSession）◄──► worker D
  └── 自动接收 worker 报告并综合结论

每个 worker：

1. 使用 pi SDK 创建独立的内存 AgentSession。
2. 共享 lead 会话背后的同一个 ModelRuntime，不复制、转换或输出认证信息。
3. 加载相同工作目录；信任项目时加载项目 context/skills。
4. 使用独立上下文，但共享同一个内存任务板和消息路由器。
5. 通过 custom message 接收队友消息；空闲时自动触发新一轮。
6. 结束一轮却未主动报告时，扩展会把其最终输出兜底发送给 lead。

安全与资源控制

• 创建团队前会提示 worker 数量及额外 token 成本。
• 未信任项目不会向 worker 加载自动发现的 context 文件或 skills。
• Worker 不加载其他 pi 扩展，避免递归创建团队以及无 UI 扩展产生副作用。
• 可为每个 worker 设置内置工具白名单；默认包含完整编码工具。
• 队友消息被明确标记为不可信协作输入，不能作为用户授权。
• 默认每个 worker 最多 8 个唤醒轮次，团队最多 200 条消息。
• 并行编辑同一文件仍可能产生语义冲突；应在任务中明确文件所有权。

当前限制

• 团队仅存在于当前 lead 会话；/reload、/new、/resume 后不会恢复 worker 上下文。
• 暂无 tmux/iTerm2 分屏和逐 worker 完整 transcript UI；当前通过状态组件及命令查看。
• 所有 worker 默认使用创建团队时 lead 的模型和 thinking level。
• Worker 运行时不加载用户的其他扩展，因此其中的自定义安全钩子不会自动继承。
• 异步 worker 的 usage 会显示在 team_status，目前不并入 lead 底部的会话总费用。
• 共享任务和消息当前存储在内存，不跨 pi 进程共享。

开发

npm run typecheck
npm test
npm run check

要求 Node.js 22.19+ 和 @earendil-works/pi-coding-agent 0.82.1+。

设计参考

• Claude Code: Orchestrate teams of Claude Code sessions
• pi docs/extensions.md
• pi docs/sdk.md
• pi examples/extensions/subagent/