子代理与编排类包：把任务切给谁

一个代理写代码写到一半，前面的文件读取、测试输出、试错过程全堆在上下文里；等你让它"再检查一遍刚才的改动"，它已经忘了自己刚才改了什么。想让它并行干三件事，又只能顺序等——因为一个会话只有一个上下文。

生态给出的答案叫子代理：派一个隔离开的代理去干一小块活，主会话只拿回结论。但"子代理"这个词底下是九种差别很大的实现——有的只是换个会话跑一段提示词，有的拉起隔离子进程，有的直接开一整套 git worktree 流水线，有的干脆不是 CLI 而是带 Web 看板的桌面应用。

装之前不搞清楚这些差别，代价很实在：你以为买了并发，其实买的是串行；你以为任务隔离了，其实子代理和你共享同一份 transcript；你以为循环跑完了，其实它在一个已经废弃的提示词上打转。

Pi 官方不提供子代理和 plan mode，这层全是生态在做。这篇按编排形态（单委派 / 团队角色 / 流水线 / 循环 / 多节点应用）、上下文隔离方式（同会话共享 / fork 子进程 / worktree）、完成判定（模型自评 / judge 循环 / 外部验证）三个维度把九个包切开。读完你能按任务形态选型，也能认出每个包 README 里最容易被跳过的那句限制。

九个包各管什么

这张表里要分清两个容易混淆的词。 "子代理"（subagent）在这九个数包里都指"派出去的独立代理"，但"编排"（orchestration）指的是谁决定下一步做什么。pi-subagents 派出去就完了，主会话自己判断；pi-crew 有个 judge 在循环里替主会话做判断；taskplane 有一张依赖图在调度；fusion 有一整个看板在调度。

单委派：pi-subagents

它是这一类里最直接的一个：派一个子代理做一件子任务，拿回结果。

内置 7 个 agent，角色划分有明确意图：

scout             探路，快速摸清 unfamiliar 的代码区域
researcher        调研，收集外部信息
evidence-auditor  证据审计，核对结论是否有据
worker            执行者，干具体的活
reviewer          评审，检查产出
oracle            顾问，给判断和第二意见
delegate          委派者，把活再拆一层派出去

oracle 和 delegate 是两个有意思的设计。 oracle 不干活，只出判断——对应 /council 那种"多个顾问辩论"的用法。delegate 则说明嵌套是被明确支持的，不只是一层。

工具只有三个：subagent（派一个子代理）、subagents_enable（启用/禁用）、bg_wait（等待后台任务）。

bg_wait 的存在说明了"前台/后台双模式"是这包的核心能力。 前台模式是同步等结果，后台模式派完就走，bg_wait 用来收割。这让你能同时跑多个后台任务再统一取结果——这是真并发。

斜杠命令六个：/council（多顾问辩论）、/parallel-review（并行评审）、/review-loop（评审循环）、/subagents-doctor（诊断）、/subagents-fleet（舰队视图）、/subagents-guide（使用指南）。

peerDependencies 要求 pi-ai >=1.2.0——这是九个数包里对 pi-ai 要求最高的，装之前确认版本。

单委派（带配置层）：@tintinweb/pi-subagents

它做的事情和 pi-subagents 类似——自治子 agent 与工作流编排——但配置层的完整度完全是另一个量级。Claude Code 风格那套东西基本都搬过来了。

四个工具：

Agent                  派一个子 agent
get_subagent_result    取结果
steer_subagent         中途转向（steer）
SubagentWorkflow       工作流

steer_subagent 是这里的特色。 派出去之后还能中途改变方向，不用 kill 重来。

配置分两处：

项目配置覆盖全局配置。 全局那份是只读的，意味着你不能靠改它来调参数，得在项目里写。

关键配置项：

{
  "maxConcurrent": 10,
  "maxConcurrentForeground": 0,
  "maxTurns": 10,
  "graceTurns": 5,
  "maxSubagentDepth": 2,
  "fallbackSubagent": "general-purpose",
  "agentMentions": true,
  "backgroundByDefault": true,
  "worktreeIsolation": true,
  "strictAgentFiles": false,
  "packageAgents": false
}

几个值需要解释：maxConcurrentForeground: 0 表示无限——和 maxConcurrent: 10 一起读，后台最多 10 个并行，前台不限，用意是前台是你正盯着等的，本来就该按需阻塞。backgroundByDefault: true 意味着派出去默认就是后台的，这解释了为什么 get_subagent_result 是独立工具而不是同步返回。maxSubagentDepth: 2 是嵌套上限，默认关闭嵌套——pi-subagents 的 delegate 是能往下派的，这里的嵌套默认关着。fallbackSubagent: "general-purpose" 是兜底角色，请求的 agent 不存在时用它。strictAgentFiles 打开后，agent 定义必须严格符合格式，不符合的直接拒绝加载而不是宽松解析。

Agent 定义用 YAML frontmatter，放在 .pi/agents/<name>.md：

---
name: reviewer
description: 审阅改动，找 correctness 与安全缺陷
model: anthropic/claude-sonnet-4
---

你是一个严格的代码审阅者。只报告你能在代码里指出的问题，不确定就说不确定。

这包最容易被跳过的限制

这段是全篇最该抄进笔记的部分——README 里这些限制很不起眼，但踩中任意一条都会浪费半天：

最后两条最阴。node:vm 沙箱里 Date.now() 抛错，意味着任何依赖真实时间的 workflow 逻辑都得换写法——而这类脚本往往在写的时候想当然用了 Date.now()。model scope 的 glob 被静默丢弃更麻烦：你以为配了 */cheap-model 会自动路由到便宜模型，实际上这个配置被扔了，什么都没发生，也不报错。

还有一条涉及项目信任：package agent 的发现只读 Pi 已安装的 package。 官方原话是："a package listed only by an untrusted project stays invisible until you trust it"。也就是说，项目 settings 里声明的包提供的 agent，在信任之前完全不可见——不是加载失败，是看不见。

运行时依赖只有两个：croner（定时）和 nanoid（ID 生成）。

团队角色：pi-crew

它的工具数量听起来吓人，其实只有一个：team。57 个 action 全在这一个工具里。 这个设计的取舍很明确：工具列表干净，能力靠 action 覆盖——模型调用 team 时传不同的 action 参数，而不是面对 57 个工具名。

命令七个：/team-init（初始化）、/team-run（运行）、/team-status（状态）、/team-dashboard（仪表盘）、/team-config（配置）、/team-api（API）、/team-hooks（钩子）。

它有两个独到的地方。.dwf.ts 动态编排脚本——编排逻辑写在一个 TS 文件里，运行时加载执行，而不是让模型自己一步步决定，这意味着编排是确定性的，不依赖模型每次都做对。自主目标循环：worker → LLM judge → 反馈循环——这是九个包里唯一把"谁来判定做完了"显式交给一个 judge 模型的，worker 产出，judge 评估，不合格就带着反馈回去继续。

这就是它和 pi-subagents 最大的差别：完成判定权从主会话转到了 judge。 代价是多一次模型调用，收益是主会话不会被一堆子结果淹没。它也有 worktree 隔离。

依赖声明很有特点：全部 peerDependencies 都是 optional——pi-ai >=1.0.4、pi-tui、pi-agent-core、pi-coding-agent、typebox。全 optional 意味着宿主包版本不匹配时不会硬失败，扩展会降级运行。

进程隔离：pi-agent-flow

它的核心差异化只有一句话：fork 到子进程，只带必要上下文。

上下文隔离是它和 pi-subagents 最本质的区别。 pi-subagents 的子代理和主会话共享一份 transcript 的世界观；pi-agent-flow 是真的另起一个进程，父进程只把必要的东西传过去。这解决的正是"主线程被 transcript 撑爆"的问题——一个跑长时间任务的分支，在独立进程里跑完，父进程拿回的是结果而不是全过程。

工具七个：flow（主状态迁移）、trace（追踪）、batch（批处理）、batch_read（批量读）、batch_bash_poll（批量轮询 bash）、web（网络）、ask_user（问用户）。

ask_user 值得单独说。 编排到某一步需要人拍板（选哪个环境、要不要继续），它能在流程中间把这个提问抛回主界面。这是很多自动编排系统缺的环节。

命令 /flow:settings 带了一堆子项：show、steering、animation、glitch、tool-optimize、trace、batch-read、body、complexity、context-compression、max-concurrency、ask-user、reset。context-compression 是子项之一，说明上下文压缩是它的可调策略而不是硬编码；steering 则对应运行时干预——和 steer_subagent 是同一类能力。peerDependencies 全部 >=0.37.0，门槛低。

团队角色（带依赖图）：taskplane

它和 pi-crew 同属团队角色，但流程更接近软件工程管理：spec → tasks → 批量执行 → 评估。

靠 prompt.md 和 status.md 两个文件做持久记忆。 这是它的关键设计——编排状态不放在内存里，放在磁盘上的文件里。进程崩了、换个会话，状态还在。

四种 agent 角色 + 依赖图调度 + 检查点提交。"检查点纪律"这个词说明它假设 agent 会跑偏，所以在每个批次之间留可回滚的提交点。

工具只有一个：review_step——worker 内联评审，也就是评审发生在 worker 自己的流程里，不是外挂的一步。

命令十个：/orch（主编排）、/orch-plan（规划）、/orch-status（状态）、/orch-pause（暂停）、/orch-resume（恢复）、/orch-abort（中止）、/orch-deps（依赖图）、/orch-sessions（会话）、/orch-integrate（集成）、/taskplane-settings（设置）。

/orch-pause 和 /orch-resume 的存在说明它假定了长时间运行。 十个命令里有三个（pause/resume/abort）是在处理"中途停下来"这件事——这只有在真的打算跑长任务时才会设计。

流水线：@juicesharp/rpiv-pi

它把开发流程切成 Skill：discover → research → design → plan → implement → validate。配套还有 revise、outline-test-cases、write-test-cases、annotate-guidance、annotate-inline、migrate-to-guidance 这些专项 Skill（总共 14 个）。

它的独特设计是"配命名 subagent 做并行分析"。 分析阶段不是一步做完，而是派多个专职 agent 同时看代码的不同侧面：

codebase-analyzer     codebase-locator      codebase-pattern-finder
integration-scanner   precedent-locator     test-case-locator
thoughts-analyzer     thoughts-locator      web-search-researcher

靠 session 生命周期 hook 自动注入上下文——不用模型显式调用"加载上下文"，包在合适的时机自己挂上。

四个工具：code-review（代码评审）、commit（提交）、create-handoff（创建交接）、resume-handoff（恢复交接）。create-handoff / resume-handoff 这一对是流水线类型包的共性需求：一个会话做一半，下个会话接着做。

这个包有三个必须知道的坑

第一，它已经搬家了。 juicesharp 的所有独立仓库都已迁移到 juicesharp/rpiv-mono monorepo（npm 最新 2.15.0，peer 已切至 @earendil-works/pi-*）。旧仓库 README 顶部有迁移提示，里面写的 peer 是 @mariozechner/pi-*——更早的宿主命名。你要是照着旧 README 抄依赖声明，会拿到一个装不上的包。

第二，/rpiv-setup 在 headless 模式会失败。 无头调用（pi -p）时这个命令起不来，得在交互式会话里跑一次。

第三，agent 并发默认是 4，需要提到 48。 这个数字跨度很大——默认配置对大仓库并行分析是明显不够的。

还有一条：首次会话有副作用。 它会写 .pi/agents/、创建 thoughts/ 和 shared/ 目录。不是 bug，但第一次跑完你会发现工作区多了东西。

多节点应用：@runfusion/fusion

这是九个包里唯一不是 CLI 工具而是完整产品的。它的流程是：

需求 → 规划 agent 写 PROMPT.md → 看板（Plan → Review → Execute → Review）
     → 隔离 git worktree 执行 → 合并 / PR

看板是核心。 四个阶段是显式的状态，不是隐式的提示词约定。每张卡片有明确的产出物（PROMPT.md 就是规划 agent 的产出），Review 出现在 Execute 前后两次。

扩展注册了 77 个 fn_* 工具。 这是本文所有包里最多的——但它们统一 fn_ 前缀，模型看到的是"一组 fusion 功能"。命令 /fn 带三个子命令：/fn stop、/fn status、/fn <port>。<port> 暴露的是 Web 看板。 除了 CLI，它还有配套的 Web 看板、CLI、桌面端和移动端——四个界面。

依赖是清一色的 @earendil-works/pi-* 1.1.0：pi-ai、pi-agent-core、pi-coding-agent、pi-tui、pi-client、pi-codemode、pi-mcp、pi-protocol、pi-telemetry。注意后三个（pi-client、pi-protocol、pi-telemetry）其它包都不依赖。 这反映了它的定位——它要跟远端节点通信、要埋点。

安装路径的一个坑

它的 README 里没有 pi install 字样。 官方安装路径是 npx runfusion.ai、curl install.sh | sh、brew install fusion 或 npm install -g @runfusion/fusion。

package.json 里确实有 pi 清单字段，所以技术上可以 pi install npm:@runfusion/fusion——但那不是官方声明的路径。想要官方支持的就用上面那四条。

状态方面：early preview / beta。Hermes、Paperclip、OpenClaw 三个运行时插件是 experimental。

支持本地模型：可选 llama.cpp HTTP server，默认地址 http://127.0.0.1:8080。

循环：@tmustier/pi-ralph-wiggum

它把 Geoffrey Huntley 的 ralph-loop 适配到 Pi：同一会话内反复迭代同一份任务清单，直到验证通过。

这是个很原始但很有效的思路——不给模型一个长提示词让它一次做完，而是给它一份清单，让它一轮一轮地啃，每轮啃掉一点。

先说清它的位置：真实仓库是 tmustier/pi-extensions，这个包是它的子目录 pi-ralph-wiggum/。

命令：/ralph start <name|path>（开始）、/ralph resume <name>（恢复）、/ralph stop 与 /ralph-stop（停止，后者是别名）、/ralph status、/ralph list --archived（列出已归档）、/ralph archive <name>、/ralph clean [--all]、/ralph cancel <name>、/ralph nuke [--yes]（彻底清除）。

start 的选项：

两个工具：ralph_start、ralph_done。任务文件 .ralph/<name>.md，状态文件 .ralph/<name>.state.json。

五个必须知道的限制

这个包是 flat 实现，没有 subagent。 循环在同一个代理里跑，不是多代理协作。

每次迭代是同一 Pi 会话内的一个新 turn，不是新的上下文窗口。 上下文还是那一个，只是又转了一圈。

不启动新的 Pi 进程。 和 pi-agent-flow 的 fork 子进程是完全相反的取向。

loop 归属于启动它的会话。 换个会话想接着跑，必须 /ralph resume <name> 把归属转过去。不 resume 就开新会话，loop 就成了孤儿。

Completion gate 要求很硬。 想让循环判定完成，必须发 <promise>COMPLETE</promise>，而且在此之前要保留构建产物，并记录确切的命令、工作目录、环境变量、输出摘要。这不是形式主义——它要的是可复现的证据。

Stale prompt guard 管的是另一种事故：一个已经完成的 loop 收到过期提示词时，会先读 state.json 确认状态，而不是盲目重启。

流水线（学术向）：@companion-ai/feynman

先纠正一个常见误解：它不是"Feynman 学习法"。 它是一个开源 AI 研究代理，在 stock Pi 上跑 researcher / verifier / reviewer / writer 四个子代理，做文献综述、深度调研、论文评审和复现计划。

真实仓库是 Companion-Inc/feynman（一万多 star），不是 companion-ai/feynman。

四个子代理的分工很清晰：researcher 找文献做调研、verifier 核实说法、reviewer 评审论文质量、writer 写产出。

命令覆盖了研究工作的各个阶段：/deepresearch、/lit、/review、/audit、/replicate、/recipe、/compare、/draft、/autoresearch、/summarize。/audit 和 /review 分开的思路值得注意——核实和评审是两种不同的严格度。

peerDependencies 四个 pi 包全部用 @earendil-works/pi-*。它需要 API key——feynman setup 登录模型 provider；另外 OPENALEX_API_KEY 和 SEMANTIC_SCHOLAR_API_KEY 是可选的（文献检索用）。同时支持本地模型。

遥测用 PostHog，发的内容有明确边界：命令、模型、token 数、错误栈——不发 prompt、不发输出、不发论文内容。FEYNMAN_TELEMETRY=off 可以关掉。

/replicate 必须先由用户选择环境——它要在什么环境里跑复现，这一步不能自动决定。结果落在 outputs/，草稿落在 papers/。

横向对比

编排形态

上下文隔离

"worktree 隔离"和"上下文隔离"是两回事，这张表最容易被误读。worktree 隔离的是文件写入——多个 agent 改代码不会互相踩。但它们的上下文该多长还是多长。真正做上下文隔离的只有 pi-agent-flow 的 fork 子进程。

完成判定

判定方式决定了系统的可靠性上限。 模型自评是最弱的——子代理和主会话共享同一个"我完成了"的幻觉。pi-crew 的 judge 好一些，但 judge 也是模型。pi-ralph-wiggum 的 gate 最硬，因为它的完成信号里必须带可复现的外部证据。

并发与嵌套

@tintinweb/pi-subagents 的并发是后台 maxConcurrent: 10、前台 maxConcurrentForeground: 0（无限），派出去默认就是后台的（backgroundByDefault: true），嵌套深度上限 maxSubagentDepth: 2 且默认关闭。@juicesharp/rpiv-pi 的 agent 并发默认 4，需要提到 48。pi-subagents 的嵌套是支持的，有专门的 delegate 角色。

谁负责什么

三种场景的可观察结果

场景一：想让三个互不相关的调查同时跑，主会话不被撑爆。 装 pi-subagents，用后台模式派出去，用 bg_wait 收割。可观察结果是三个子代理的进度同时推进，而主会话历史里只有三段结论——如果主会话也在积累子代理的中间过程，说明你用的是共享上下文的形态，需要考虑 pi-agent-flow 的 fork。

场景二：想要"改代码不打架"的隔离。 用 worktree 类：taskplane、pi-crew 或 @runfusion/fusion。可观察结果是多个 agent 并发改文件时 git 状态互不干扰，但要注意这隔离的是文件不是上下文——上下文压力还在。想要连上下文一起隔离，得用 pi-agent-flow。

场景三：一个任务反复失败，改几轮就好，需要它一直磨到真的通过。 用 @tmustier/pi-ralph-wiggum。可观察结果是 .ralph/<name>.md 的清单项在减少、.ralph/<name>.state.json 的迭代计数在涨，完成时你会看到构建产物和一条确切的验证命令，而不是模型说"应该好了"。

你现在能做什么

• 装 pi-subagents，跑一次 /council，观察多个顾问的辩论在同一会话里怎么呈现；再用后台模式派两个任务，对比 bg_wait 的收割时机。
• 装 @tintinweb/pi-subagents，用 /agents 打开菜单把 maxConcurrent 调高，写一个 .pi/agents/<name>.md（YAML frontmatter）验证它能被选中；顺便验证 pi -p '@plan ...' 确实报 File not found——mentions 只在 TUI 可用。
• 装 pi-crew，起一个 .dwf.ts 编排脚本，故意在里面写 Date.now()，确认它抛错而不是静默返回假时间。
• 装 pi-agent-flow，用 /flow:settings 看 max-concurrency 和 context-compression 两项，再跑一个 fork 任务，确认它是独立进程。
• 装 taskplane，跑一遍 /orch-plan → /orch，检查 prompt.md 和 status.md 是否生成；中途 /orch-pause 再 /orch-resume，验证状态确实落盘了。
• 装 @juicesharp/rpiv-pi，在交互式会话里（不是 headless）跑 /rpiv-setup，把 agent 并发从 4 调到 48，验证首次会话写出的 .pi/agents/、thoughts/、shared/。
• 装 @tmustier/pi-ralph-wiggum，跑 /ralph start demo，观察 .ralph/demo.md 和 .ralph/demo.state.json；换个会话用 /ralph resume demo 验证归属转移。
• 装 @companion-ai/feynman，跑 feynman setup 配 provider，然后 /lit 做一次检索；用 FEYNMAN_TELEMETRY=off 跑一遍确认遥测关掉了。

排障速查

参考资料

• 官方文档：Pi Packages
• 官方文档：Extensions
• 官方文档：Command Line
• 官方仓库
• Pi 包画廊
• pi-subagents 仓库
• @tintinweb/pi-subagents 仓库
• pi-crew 仓库
• pi-agent-flow 仓库
• taskplane 仓库
• rpiv-mono 仓库（@juicesharp/rpiv-pi）
• Runfusion/Fusion 仓库（@runfusion/fusion）
• pi-extensions 仓库（pi-ralph-wiggum 子目录）
• Companion-Inc/feynman 仓库