多 Agent 不是多开几个终端Pi 的 Sub-agent 取舍三个 Agent 同时进入一个仓库一个改认证接口一个补前端调用一个修测试。十分钟后它们都说任务完成了。合并时才发现前端基于旧接口生成测试重写了共享 Fixture认证 Agent 又在最后一次格式化中覆盖了另一条分支的改动。从进程列表看这是多 Agent。从工程结果看它只是多个模型同时碰同一份状态。启动第二个 Pi 进程并不难。工程难点是谁定义子任务谁拥有工作区什么上下文可以传递失败怎样传播取消后如何处理已发生的副作用结果凭什么进入主分支。本文的核心结论是可控的 Sub-agent 需要一条清晰主线Task Contract 固定任务工作区和权限限制执行Artifact Envelope 返回证据独立 Review Gate 决定是否接收。Pi 的小核心选择正好暴露了这条边界。它不在核心规定一种 Sub-agent 拓扑但提供进程、Session、SDK、Extension 和 Package 等组合入口。团队可以据此构建自己的流程也必须自己承担调度语义。一、先区分“第二个执行者”和“受控子任务”一个 Shell 命令可以启动另一个 Pi一个 SDK 调用可以创建另一个AgentSessionExtension 也可以注册一个调用子进程的 Tool。这些能力证明第二个执行者可以存在却没有自动回答下面的问题任务从哪个父任务产生 它读取的是哪个代码快照 允许修改哪些文件和外部系统 完成、部分完成、失败和取消分别怎样表达 结果由谁验收什么时候才允许合并这条主线背后需要检查七类对象对象需要回答的问题Task要解决的具体问题是什么Context允许依赖哪些事实与代码快照Capability可以调用哪些工具、凭证和网络Workspace在哪里读写谁拥有这些写入Run当前执行到了哪个状态Artifact返回了什么可检查的结果与证据Gate谁决定接受、重试、拒绝或合并缺少其中任何一项主 Agent 得到的往往只是一段“我完成了”的自然语言而不是可接管的工作。二、Pi 实际提供了什么又刻意没有提供什么Piv0.82.1README 明确把 Sub-agent 排除在核心默认能力之外并给出 tmux、Extension 或第三方Package 等组合方向。到 2026-08-12 检查当前main小核心立场仍然存在。当前 SDK 文档同时把“构建能启动 Sub-agent 的自定义 Tool”列为程序化用例Extension 示例目录也提供相关示例。这组事实应该被准确表述为Pi core 不内置唯一的 Sub-agent 工作流。 Pi 提供足以构建多会话、多进程与自定义工具的组合原语。 示例与原语不等于生产级调度、隔离、恢复和验收已经成立。这种选择有合理收益。不同团队需要的拓扑差异很大只读研究可以共享代码目录。并行改动可能需要独立 Worktree。高风险操作需要隔离凭证。长任务需要持久 DAG。简单审查只需一次父子调用。若核心固定其中一种其他场景就要围绕它迁就。代价也不能省略状态协议、并发限制、日志、取消、重试、产物格式和合并策略都转移给 Extension作者或外部 Orchestrator。Pi 的可扩展性减少了核心预设并没有让控制面免费出现。三、先写 Task Contract再写 Prompt主 Agent 对子 Agent 说“检查一下认证模块”看似简洁实际上把范围、证据、权限和终态全部留给模型猜。可靠的交接应先变成可验证合同task_id:auth-race-reviewparent_task_id:release-20260812objective:找出刷新令牌流程中的并发安全问题input_revision:5f2c1a7scope:read:[src/auth/**,tests/auth/**]write:[]capabilities:[read,search,test_list]constraints:network:deniedsecrets:denieddeliverables:-artifacts/auth-review.md-artifacts/claims.jsonlexit_criteria:-覆盖登录、刷新和登出三条路径-每条确认结论带文件、Symbol 与证据级别Prompt 负责帮助模型理解任务。合同负责让系统判断任务是否越界、产物是否齐全。两者的区别在失败时最明显Prompt 失败通常只能重读对话合同失败可以指出缺少哪个字段、哪项退出条件未满足。合同还应固定input_revision。如果子 Agent 在旧提交上完成分析而主分支已经移动调度器不能把“内容看起来合理”当作仍然有效。它要么重新基线化要么把结果标成 stale交给人工决定是否还能复用。四、Context Isolation 会省上下文也会损失证据Sub-agent 常见卖点是子 Agent 自己阅读大量文件只把摘要交给主 Agent。它确实能保护主会话避免把几十次搜索和失败尝试全部塞进主上下文。但摘要是一种有损压缩它可能丢掉被否定的假设和失败命令。两个来源之间的冲突。“尚未验证”被压成肯定句的边界。只在特定版本成立的限制。结果生成时所依赖的代码快照。所以交接不能只有summary。更稳妥的 Artifact Envelope 至少包含{taskId:auth-race-review,status:partial,summary:确认一处竞态另有一处受缺失集成环境阻断,claims:artifacts/claims.jsonl,evidence:[src/auth/token.ts#refresh,artifacts/test.log],inputRevision:5f2c1a7,unverified:[数据库事务隔离级别],sideEffects:[],recommendedNextAction:启动测试数据库后复跑用例}主 Agent 平时读取摘要关键判断再沿证据句柄回查。这样 Context Isolation 才是“把细节移出主上下文”而不是“把细节永久丢掉”。五、并行写入先划定共享状态与所有权两个 Agent 修改不同文件也可能冲突。一个改 OpenAPI Schema另一个按旧 Schema 写客户端。一个更新依赖另一个基于旧锁文件运行测试。两个任务都写同一个生成目录或测试数据库也会互相污染。因此并发决策应基于共享状态而不是只比较文件路径。至少要检查代码与配置依赖 Schema 与生成物 数据库与消息队列 缓存、构建目录和测试端口 Git Index 与工作树 远端 API 和外部副作用对于会写代码的任务独立 Worktree 或临时 Clone 是更清楚的起点。每个任务绑定自己的 Revision、分支和输出目录。合并由主流程串行执行。即便如此也不能自动宣称没有冲突Gate 仍要重新运行共享测试、Schema 校验和语义审查。一种实用的写权限策略是研究与审查默认只读。实现任务获得明确目录或 Worktree。数据库迁移、部署、发布、删除和外部消息继续保留人工门。并行度应由可隔离状态决定而不是由可用模型数决定。六、状态必须持久化取消必须处理副作用如果任务状态只存在主 Agent 的自然语言记忆里主会话压缩、进程退出或模型失败都会让调度信息消失。一个最小 Run Record 应放在模型之外{runId:run-0182,taskId:auth-race-review,status:running,attempt:2,worker:review-agent,workspace:worktrees/auth-review,startedAt:2026-08-12T10:00:0008:00,deadlineAt:2026-08-12T10:20:0008:00,budget:{maxTurns:16},dependsOn:[map-auth-flow]}建议至少区分queued → claimed → running ↘ succeeded → reviewing → accepted | rejected ↘ failed → retrying | escalated ↘ cancelling → cancelled_with_effects | cancelled_cleancancelled不应只有一个布尔值。若子 Agent 已写文件、创建 Issue、修改数据库或触发远端任务停止模型输出并不会撤销副作用。控制面需要记录sideEffects、清理动作和迟到结果策略。旧 Attempt 在取消后返回的产物必须携带版本号不能覆盖新 Attempt 的结果。重试也必须幂等。安全重试可以复用同一个task_id并增加attempt。具有外部写入的步骤则需要幂等键、补偿动作或人工确认。否则“自动恢复”可能把一次失败变成两次扣款、两条消息或两次发布。七、第一项多 Agent 能力独立只读审查多 Agent 并不天然提高质量。若多个 Agent 使用相同模型、相同上下文和相同提示它们可能复制相同假设。并行写代码还会增加合并成本。最容易得到正收益的第一步通常是实现 Agent 产生 Diff 与测试证据 ↓ 只读 Review Agent 独立检查当前产物 ↓ 主流程按严重程度决定修复、拒绝或接受这条路线的优势很具体审查 Agent 不需要写权限不会制造第二份冲突 Diff。输入可以冻结为当前SHA。输出是问题清单和证据不需要复杂合并。生产者与审核者分离也能降低“自己证明自己正确”的确认偏差。Review Gate 不应只问“另一个 Agent 是否说通过”而应检查产物 SHA 是否与审核对象一致。审核者是否没有参与该产物生产。事实、测试、边界和未验证项是否分别记录。失败是否只有一条明确返工路线。修改后哪些结论可以继承哪些必须失效。这条链路的质量增量来自角色和权限分离而非 Agent 数量。八、什么时候应该并行什么时候坚持单 Agent可以用五个问题做拆分判断问题是时更适合拆分否时的风险子任务是否真正独立可并行读取或在隔离工作区写入等待与合并成本吞掉加速是否需要不同权限研究只读、实现可写、审查只读所有 Agent 权限过宽是否需要不同专长安全、前端、数据各有明确产物只是重复生成相似答案是否能定义验收产物有 Schema、Diff、测试或报告主 Agent 只能相信摘要失败是否可隔离恢复有 Attempt、取消和补偿语义一个失败污染整个工作区小改动、强顺序依赖、共享状态很多或无法定义退出条件时单 Agent 往往更快也更可靠。多 Agent降低的是部分墙钟时间不保证降低 Token、工具调用和人工审核总成本。本文没有运行真实 Pi 多Agent Orchestrator因此具体加速比与成本保持UNKNOWN_REAL_COST_AND_SPEEDUP。九、按风险逐级升级从独立只读审查开始先固定输入 SHA、审查范围、问题格式和接受门槛。它稳定后再并行代码搜索、资料核对和测试失败分类等只读任务。只有任务边界、依赖图和合并测试都清楚才让实现 Agent 在独立Worktree 写入。任务跨会话或跨机器时再引入持久任务图、租约、心跳、重试与补偿。每次升级前都要实测 Token、墙钟时间、问题发现率和人工成本上一层无法证明收益时不增加并发。Pi 没有把单一 Sub-agent 调度拓扑写死在核心。工程团队应先把任务、状态、证据、权限和验收从模型上下文中拿出来。做到这一步第二个 Agent 才是可管理的执行单元。否则它只是第二个不受控变量。参考资料Pi Coding Agent READMEv0.82.1固定版本的小核心与 Sub-agent 组合立场检查日期 2026-08-12。Pi Coding Agent READMEmain当前 Philosophy、Session 与扩展入口检查日期 2026-08-12。Pi SDK DocumentationAgentSession与程序化工作流能力检查日期 2026-08-12。Pi Extensions Documentation自定义 Tool、事件与 Extension 能力检查日期 2026-08-12。Pi Sub-agent Extension Example当前示例入口。仅作为组合实现样本不作为生产调度验证。