02 子代理与编排

从单 Agent 到 Agent 团队:委派、并行与工作流编排

1. 这个方向的插件试图解决什么问题

单个对话进程既要做代码库侦察、又要做多文件修改、还要做审查验证,很快就会出现上下文污染和注意力漂移。把任务拆给独立上下文的子 Agent,并协调多节点并行或接力执行,是这一方向要解决的问题。

在单 Agent 循环里,探索过程中读入的大量无关文件会一直留在历史消息里,干扰后续修改判断;同时,全盘串行执行也让跨模块审查或大范围审计耗时过长。

当子代理数量增加后,又会衍生出新问题:如何隔离工作目录以免互相改写冲突、如何中途纠偏(steering)、如何统计多代理的 token 与成本、以及如何把临时委派固化为可断点恢复的编排脚本。

2. 在 Pi 里怎么体现

Pi 自身提供隔离的子会话、SDK 调用能力以及 git worktree 管理基础,扩展主要通过注册委派工具、监听 turn_end / agent_end / tool_execution_start、并用 ctx.ui.custom() 或 widget 在终端展示并发子代理面板。

例如 pi-subagents 提供默认角色与前后台委派工具;@tintinweb/pi-subagents 强化了实时 widget、fleet 视图与运行中 steering;@quintinshaw/pi-dynamic-workflows 则把单次请求编译成带 worktree 隔离与断点续跑的 JS 编排脚本。

涉及的 Pi 事件钩子与注册接口

pi.registerTool()pi.setActiveTools()pi.registerCommand()turn_endagent_endtool_execution_startctx.ui.custom()

3. 代表包与生态实例

下表包名均核实自 npm、GitHub 与 pi.dev/packages(核对日期 2026-11-22)。前 3 项已上线独立机制详评页,正文不展示容易过期的静态下载量快照。

包名 分发形态 主要作用 详情 / 源码
pi-subagents npm Pi 的单代理委派与脚本化多代理工作流扩展,内置 scout、researcher、worker、reviewer 等角色并支持前后台执行。
@tintinweb/pi-subagents npm 面向 Pi 的多子代理编排扩展,提供并行执行、实时状态 widget、fleet 视图、自定义代理类型与运行中 steering。
@quintinshaw/pi-dynamic-workflows npm 将单次请求转化为 JS 编排脚本,支持模型路由、token/成本核算、断点续跑、git-worktree 隔离与 /workflows TUI。
pi-advisor-flow npm 面向 Pi 的 Executor/Advisor 执行顾问双阶段工作流扩展,支持高度可配置的校验与流转。
pi-fabric npm 面向 Pi 的可编程工具与 Agent 运行时,整合 Code Mode、MCP、Actor、Steering 与 Swarm 编排。
pi-agent-bus npm 基于 MessageBus、Agent 与 TaskQueue 运行时的 Pi 扩展,提供发布订阅式的 Agent 协同通信桥接。

4. 怎么装

代表包安装命令示例
pi install npm:pi-subagents
  • 后台常驻型子代理(如 pi-subagents)会复用宿主 Pi 的 SDK 或独立 Node runner 运行子会话。
  • 使用带 git worktree 隔离的编排扩展前,需确认当前目录为合法 Git 仓库,以便自动切出隔离分支或工作树。
  • 多 Agent 并发会线性放大 API 并发与 token 消耗,建议在配置文件中为侦察/审查等子角色绑定更轻量的模型层级。

5. 和同类怎么选

包名编排模型关键能力适用场景
pi-subagents 单 Agent 委派 + 脚本化工作流 内置 scout/worker/reviewer/oracle 等角色,支持前后台运行与按需激活工具 日常开发里随时拆出侦察、实现、审查子任务
@tintinweb/pi-subagents 实时面板 + 运行中干预 Fleet 视图、实时 widget、运行中 steering、兼容 Claude Code 风格定义 需要直观监控多个并发子代理并随时人工介入
@quintinshaw/pi-dynamic-workflows JS 代码驱动动态工作流 用 agent()/parallel()/pipeline() 扇出至数百子代理,支持断点恢复与 worktree 隔离 全仓库安全审计、大规模并行重构与深度研究
pi-advisor-flow Executor / Advisor 双角色闭环 执行器与顾问模型分离,按可配置流转规则做复核 需要强制“执行后必须由独立顾问模型校验”的流程
pi-fabric 可编程工具与 Actor 运行时 把 MCP、Code Mode、Actor、Swarm 统一到同一运行时 需要自定义 Actor 消息与复杂多体协同拓扑
pi-agent-bus 消息总线与任务队列桥接 提供 MessageBus、Agent、TaskQueue 与发布订阅通信 面向事件驱动的多 Agent 解耦通信实验

看完「02 子代理与编排」后的下一步

可先读已公开的入门实操文章,或点击下方制作中项目表达关注度(不收集邮箱或隐私)

从 Claude Code / Codex 切到 Pi:最小可用配置单与实机演示视频

已上线入门参考: 《Pi 入门笔记》 (比 Codex 更自由,但也更折腾)

出口 1(配置单与实机演示制作中)

Coding Agent 实战交付课:如何可控地把想法做成线上产品

由 kuhung 策划主讲。面向希望把 Coding Agent 用到真实工程与产品交付的开发者,讲清需求拆解、上下文控制、安全边界与上线验证。

出口 2(实战交付课筹备中)