pi-subagents

Pi 生态下载量最高的子代理扩展,支持单代理委派、角色预设、前后台运行与链式工作流。

安装命令
pi install npm:pi-subagents
临时试用 / 替代安装命令
pi -e npm:pi-subagents
挂接事件钩子与注册入口
session_startbefore_agent_starttool_callagent_endsession_shutdown
pi.registerTool()(subagent / subagents_enable / bg_wait)pi.setActiveTools()skills 与 prompts 清单自动注册

1. 是什么

pi-subagents 是 nicobailon 开发的 Pi 子代理与多代理工作流扩展,要求 Pi 1.2.0 或更高版本。

它把主会话之外的工作拆给独立上下文的 Pi 子进程或会话运行,开箱附带 scout、researcher、evidence-auditor、worker、reviewer、oracle、delegate 七类内置角色。

2. 解决什么问题

如果在主会话里直接做大范围源码侦察、网页调研和多轮审查,大量中间文本会撑大主上下文并干扰后续代码修改。

同时,很多简单委派并不希望一开始就往上下文里塞进庞大的子代理参数 schema,造成主模型 Prompt Cache 失效或误触发。

3. 作用原理(事件钩子与工具注册层)

通过按需加载工具与前后台分离的子会话执行器,让主会话把侦察、实现和审计拆给独立子会话。

  • 针对支持动态加工具的模型,新会话初始仅暴露轻量的 subagents_enable 加载器,避免无授权时加载完整 subagent schema;当用户请求或项目指令明确授权委派时,模型先调用 subagents_enable,下一轮请求再激活完整 subagent 工具。对于不支持动态加工具且会损失缓存的 Provider,则直接以激活状态启动。
  • 前台子代理(foreground)作为隔离会话在当前 Pi 进程内运行,并向对话流式返回结果;后台子代理(background)通过独立分离的 Node runner(或 Pi 1.2.0+ 独立二进制的嵌入式 SDK runner)持续运行。
  • 主会话可通过 bg_wait 等待后台子代理完成或接收监督消息回传,每个子代理只携带自身角色所需的系统提示与上下文。

4. 怎么装与基本配置

  • 安装后无需额外建配置即可直接用自然语言调用内置角色,例如要求“Use reviewer to review this diff”或“Use scout to map this module”。
  • 如需使用 researcher 或 evidence-auditor 做外部网页验证,需同步安装并启用 pi-web-access。
  • 可通过 toolActivation 等配置项调整 subagents_enable 的延迟加载策略或自定义角色定义。

5. 和同类怎么选

在 3 个子代理代表包中,pi-subagents 最偏实用稳健与省上下文;另外两个分别侧重实时面板控制和大规模 JS 代码编排。

与同类方案的选型对照

聚焦机制差异与适用边界,结合自身运行环境判断是否引入或保留同类替代包。

对比对象 机制差异 怎么选
@tintinweb/pi-subagents 提供类似 Claude Code 的实时 fleet 状态面板、自定义组件与运行中人工 steering。 看重终端实时可视化监控以及随时干预运行中子代理时选 @tintinweb/pi-subagents。
@quintinshaw/pi-dynamic-workflows 不走通用 subagent 工具调用,改为让模型现场编写 JS 编排脚本进行大规模并行扇出与断点续跑。 需要成百上千次并行扫描、git-worktree 隔离和跨阶段聚合时选 @quintinshaw/pi-dynamic-workflows。

同方向对比包与顺序阅读

@quintinshaw/pi-dynamic-workflows

让 Pi 把复杂请求写成可断点恢复的 JS 编排脚本,扇出至数十上百个隔离模型实例并行执行。

阅读该包机制详评

@tintinweb/pi-subagents

带实时 Fleet 面板、终端 Widget、运行中 Steering 与 Claude Code 兼容风格的子代理编排器。

阅读该包机制详评

02 子代理与编排

回到该演进方向总论,查看完整痛点拆解、通用安装注意事项与全部收录清单。

返回方向总论页

看完「pi-subagents」后的下一步

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

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

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

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

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

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

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