@tintinweb/pi-subagents

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

安装命令
pi install npm:@tintinweb/pi-subagents
临时试用 / 替代安装命令
pi -e npm:@tintinweb/pi-subagents
挂接事件钩子与注册入口
session_startinputtool_execution_startturn_endagent_endagent_settledsession_before_switchsession_shutdown
pi.registerCommand("agents")pi.registerMessageRenderer()pi.sendMessage()pi.appendEntry()pi.setActiveTools()ctx.ui.custom() / addAutocompleteProvider()

1. 是什么

@tintinweb/pi-subagents 是安全研究团队 tintinweb 开源的 Pi 子代理编排扩展。

它面向需要并发调度多个自定义 Agent 类型、并在终端里直观掌控所有子任务状态的开发者,同时兼容 Claude Code 风格的 Agent 定义格式。

2. 解决什么问题

多个子代理同时在后台跑起来后,用户很难判断哪几个卡住了、各自在调用什么工具、以及如何在跑偏时立刻纠偏,而不必等整批全部跑完再返工。

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

结合生命周期事件监听、自定义消息渲染器与全终端 TUI 组件,打造可视化与可中途干预的多代理控制台。

  • 启动时在 session_start 加载内置及兼容 Claude Code 目录格式的自定义 Agent 配置文件,并注册自动补全与 /agents 控制命令。
  • 派发并行任务后,扩展监听每个子会话的 tool_execution_start、turn_end、agent_end 和 agent_settled,持续刷新终端实时 widget 与 fleet 视图。
  • 扩展通过 pi.registerMessageRenderer() 自定义子代理调用块渲染样式,并利用 pi.sendMessage() 支持用户对仍在运行中的子代理做 mid-run steering(运行中追加指令纠偏)。
  • 在切换或关闭会话时(session_before_switch / session_shutdown)清理活跃子代理句柄并把状态写入会话日志(appendEntry)。

4. 怎么装与基本配置

  • 运行 pi install npm:@tintinweb/pi-subagents 安装扩展及随包附带的 skills。
  • 在会话内输入 /agents 打开交互面板查看和管理已注册的 Agent 类型与活跃舰队状态。
  • 如已有 .claude/agents/ 下的 Markdown Agent 定义,可直接沿用而无需全部重写。

5. 和同类怎么选

相比 pi-subagents,@tintinweb/pi-subagents 把大量精力放在终端可视化监控、运行中 steering 与 Claude Code 迁移兼容上。

与同类方案的选型对照

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

对比对象 机制差异 怎么选
pi-subagents 轻量按需激活,前后台分离稳健,支持独立二进制后台 runner,但交互界面相对克制。 日常单人开发追求少打扰、低 token 开销时选 pi-subagents。
@quintinshaw/pi-dynamic-workflows 核心抽象是 JS 工作流代码而非交互式 Fleet 控制台,支持更高上限的扇出并发与断点恢复。 任务可清晰拆解成代码化的 Map-Reduce 并行流时选 @quintinshaw/pi-dynamic-workflows。

同方向对比包与顺序阅读

pi-subagents

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

阅读该包机制详评

@quintinshaw/pi-dynamic-workflows

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

阅读该包机制详评

02 子代理与编排

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

返回方向总论页

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

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

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

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

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

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

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

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