尧图网页设计 
Pi 这类工具用顺手之后单线程让它写代码会越来越不过瘾。前面几篇讲的是怎么让 Pi 完成单个任务比如改 bug、写测试、做代码审查但真实项目从来不是单任务战场一个需求拆下来少说有三四个模块要动前后端要配合文档要同步测试要跟上。如果全塞给一个主代理串行处理要么上下文越拖越长导致后期指令混乱要么一个文件改动引发连锁反应却没人提前兜底。这篇「Pi 实战 04」就专门讲多智能体与高级工作流带你把 Pi 从一个「能干的助手」升级成「一个能带队干活的小团队」。我会从 Pi 的多智能体机制讲起把主代理和子代理的分工逻辑说明白再给一套可以直接抄的工作流配置方案包括需求拆解、并行编码、代码审查、测试收尾这几个环节最后补充几个我在实际操作中踩过的坑。适合已经对 Pi 的基本用法有了解、想让协作效率再上一个台阶的朋友阅读读完你会发现多智能体不是把任务丢给多个 AI 而已关键在于编排、上下文控制和风险闸门。1. 为什么要搞多智能体单代理模式的瓶颈在哪1.1 单代理越长越笨的上下文问题先看单代理的工作方式。你给 Pi 一个需求它在一个对话上下文中连续读文件、改代码、跑测试所有历史记录都会保留。这个模式在任务范围小的时候非常稳但一旦任务复杂上下文窗口就会被逐步填满。文本一多Pi 的注意力就会分散经常出现「前面说好的命名规范后面改着改着就忘了」或者「明明刚刚确认过某个接口签名下一轮就开始自由发挥」这类现象。这其实是所有大模型应用都绕不开的问题。上下文越长模型对早期指令的遵循度就越低同时对 token 的消耗也越大。我实测过一个包含几十个文件的增量改造任务如果全程塞在主代理里跑到后半程 Pi 的决策质量会明显下降而且每次回复前的等待时间肉眼可见地变长。与其硬扛不如把任务拆开让每个子代理只处理一个局部范围上下文短、目标清晰、输出质量反而更稳定。1.2 Pi 的多智能体工作机制Pi 的多智能体采用的是「主代理调度 子代理执行」的架构。主代理负责接收你的指令、拆解需求、分配任务、汇总结果子代理是轻量级的执行单元每个子代理有自己独立的上下文和任务清单干完活之后把结论交回给主代理。这个机制里最关键的一点是子代理之间不直接互相通信所有信息都通过主代理中转。这样做的好处是避免了多智能体之间消息风暴和上下文串扰代价是主代理的上下文会成为信息集散地所以控制好每个子代理回传内容的粒度很重要。你可以让子代理「只返回结论 变更文件清单 需要主代理注意的风险点」而不是把完整的会话记录倒出来。1.3 多智能体真正解决的是什么多智能体不是「多个 AI 一起干活」这么简单它解决的问题有三个一是上下文隔离每个子代理只需要加载自己负责的那部分代码不用背着整个项目历史二是并行效率没有依赖关系的任务可以同时跑省掉串行等待时间三是角色专业化你可以给不同子代理设定不同的人设和能力边界比如一个只做代码审查、一个只做安全扫描、一个只写技术文档每个子代理都能做到术业有专攻。有个类比挺合适单代理模式就像你雇了一个全能实习生什么事情都喊他做他忙得晕头转向还容易出错多智能体模式像是你带了一支小队拆解、编码、审查、测试各有专人你只需要坐镇指挥。对项目管理者来说后者的体验要好太多。2. 动手前的基础准备初始化工作区与角色配置2.1 安装 Pi 并初始化项目工作区开始之前先确认 Pi 的版本多智能体功能在较新版本里才算完整建议保持最新版。项目里执行pi init这个命令会在当前目录生成.pi/工作区目录里面包含全局配置、技能目录、代理角色定义等基础文件。初始化完成后用pi doctor检查一下环境是否正常它会报告配置文件的解析情况、依赖项是否齐全、工作区里有没有明显冲突。我建议把.pi/目录纳入版本管理团队协作时每个人拉下来都能保持一致的行为配置。不过要注意如果你的项目里已经有旧的.pi/目录先备份再升级新版初始化会覆盖部分配置文件。2.2 用 Skill 扩展子代理的能力Pi 的 Skill 机制相当于给代理安装「专业技能包」。比如你要让子代理做前端代码审查没有对应的 Skill 它也能做但有了 Skill 之后它会更清楚项目的技术栈规范、目录约定、常见反模式。Skill 可以通过pi skill install从市场安装也可以自己写本质是一个带说明文档和规则提示的文件夹。我最常用的操作是导入项目自定义 Skill。在.pi/skills/下建一个目录里面放一个SKILL.md文件内容用简洁的自然语言描述这个技能的使用场景、检查要点和输出格式--- name: project-reviewer description: 针对本项目的代码审查技能关注接口兼容性、数据迁移、日志规范 --- 检查代码时请重点关注 1. 涉及数据库变更时是否提供了相应的迁移脚本说明 2. 新增接口是否向后兼容是否有版本兼容策略 3. 日志输出是否遵循项目的统一格式Skill 不要写得过于抽象直接告诉子代理「在这个项目里什么重要」是最有效的。子代理加载 Skill 之后它的行为会明显更贴合项目实际。2.3 创建你的第一份子代理角色清单子代理的配置在.pi/agents.toml里定义每个子代理包含名称、角色描述、可用 Skill、允许的操作范围、温度参数等字段。下面是一份我常用的最小配置[agent.reviewer] role 代码审查员 description 负责检查代码质量、发现潜在 bug 和安全隐患只读代码不直接修改文件 skills [project-reviewer] permissions [read, run-tests] temperature 0.2 [agent.doc-writer] role 文档工程师 description 负责从代码变更中提炼文档要点并生成 Markdown 文档不修改源代码 skills [doc-generator] permissions [read, write-docs] temperature 0.5 [agent.frontend] role 前端开发 description 负责前端页面与组件实现遵循项目前端目录规范和代码风格 skills [frontend-stack] permissions [read, write] temperature 0.3这里有几个设置要点。温度参数控制创意的随机性代码审查、测试这类任务建议调低到 0.2 左右追求严谨文档写作可以稍高一点。权限控制一定要收紧安全相关的子代理尽量只读避免 AI 审查代码时顺手帮你改了文件那会非常灾难。配置完成后执行pi agents list可以查看所有子代理的状态。如果某个角色的 Skill 没有正确加载这里会直接报出来趁早排查。3. 一套能直接复制的多智能体工作流3.1 阶段一需求拆解与调研并行化拿到一个中等规模的需求时不要直接下令「开始干活」先让主代理做需求拆解。我会在 Pi 里发起这样一场会话请根据以下需求进行任务拆解并把每个子任务分配给最合适的子代理 需求给订单系统增加批量导出功能支持 CSV 和 Excel 格式要求可以按时间范围筛选、按状态筛选导出时不能阻塞主服务。主代理会结合项目上下文把需求拆成几个典型的子任务后端接口设计、导出文件生成模块、前端操作入口、异步任务队列改造、测试与文档。拆解完成后主代理会生成任务依赖图比如「前端入口依赖后端接口完成」「Excel 导出依赖文件生成模块完成」。这个阶段适合并行的是「调研型任务」。比如让一个子代理梳理现有订单表结构和接口另一个子代理调研项目里是否有现成的异步任务队列第三个子代理查看前端订单列表页的实现方式。它们互不依赖可以同时跑。主代理会在收到所有调研结论后做汇总形成一份实现方案。3.2 阶段二按模块并行编码需求分析完成后进入编码阶段。这个阶段最常见的错误是强行把所有模块同时开工结果接口还没定义好前后端各自按自己的想象去实现最后联调时全是冲突。我的做法是让主代理先定义好「契约」。比如后端接口的出入参结构、导出文件的字段清单、错误码规范这些先确定下来再分发给各个子代理并行开发。配置一个并行任务组请调度以下子代理并行执行 - frontend实现订单列表页的批量导出按钮和筛选条件 - backend实现导出任务的创建接口和状态查询接口 - async-worker实现导出任务的后台处理逻辑 所有代理必须遵循已确认的接口契约完成后报告变更文件和测试结果。并行编码时代码仓的冲突控制要注意。最好是每个子代理负责完全不同的文件目录避免两个代理同时改同一个文件的尴尬情况。如果项目比较小、文件之间耦合度高并行未必有优势串行反而更稳妥。3.3 阶段三代码审查代理独立上线编码完成不等于可以交付。我很坚持的一点是负责写代码的子代理和负责审查代码的子代理必须是不同的角色。首先写代码的代理对代码有「感情」不容易发现自己的问题其次审查需要更低的温度和更挑剔的眼光和开发代理共用一个上下文会影响判断。启动审查代理的命令大概是请 reviewer 审查以下分支的变更重点关注数据库迁移是否遗漏、接口兼容性、异常处理路径、日志规范。不要修改代码只输出问题清单和修改建议。审查代理会从只读权限的文件系统里快速浏览变更结合 project-reviewer Skill 的检查要点输出风险分级清单。通常我会要求审查结果标注严重级别阻塞问题、建议修复、可选优化。阻塞问题直接打回给对应开发代理处理建议修复的排到下一轮迭代。3.4 阶段四测试与文档收尾代码通过审查之后测试子代理开始工作。它负责补单元测试、集成测试以及关键路径的端到端验证。这里有一个重要细节测试代理需要知道哪些是「关键路径」不能所有函数都无脑补测试产出质量反而不高。文档代理在编码阶段结束后介入根据代码变更记录、接口定义、测试报告自动生成技术文档和变更日志。文档代理的权限只允许写 docs 目录不允许碰源代码。三个代理测试、文档、以及可能的构建发布代理在这个阶段又形成一轮并行。整个工作流跑完之后主代理会输出一份完整的交付报告包含变更文件树、测试覆盖率、遗留问题、发布建议。你只需要做最后的人工复核而不需要盯每一行代码的编写过程。4. 高级工作流的编排技巧与上下文管理4.1 表达任务依赖串行、并行与汇合多子代理协作时最常见的需求就是「A 做完 B 才能做C 和 D 可以同时做最后 E 汇总」。Pi 的工作流里可以用depends_on字段显式声明依赖关系也可以用更直观的分组语法# workflow.yaml stages: - name: 调研 agents: [env-explorer,>[agent.reviewer] max_context_tokens 10000 max_output_tokens 4000同时在主代理的调度指令里强调输出的精简性让子代理只返回变更摘要而不是大段代码。还有一种更省钱的方式把子代理的中间产出直接写入仓库里的临时目录回传时只带文件路径主代理需要看时再读取。这种「外置记忆」能大幅降低上下文占用。4.3 人机协作的审批闸门多智能体全自动跑完整个工作流听起来很爽但在真实项目里我强烈建议在关键路径上设置人工审批闸门。比如「契约定义」完成后需要你确认接口设计「代码审查」完成后需要你确认问题清单的处理方式。闸门机制避免了一个小错误被流水线放大到不可收拾的地步。Pi 支持在 workflow.yaml 里声明approval.required: true运行到该节点时会暂停下来等你确认。你可以在交互界面上查看这个阶段产出的摘要、变更文件、风险提示选择「通过」「打回」或「修改后继续」。这个设计相当于给了人控制多智能体的方向盘而不是把整个项目全权交给 AI。4.4 多智能体的「会诊」式协作除了流水线式的分工协作还有一种更高级的用法针对疑难问题让多个子代理从不同视角进行分析然后汇合出综合方案。比如线上出现一个偶发的性能问题你可以同时让性能分析代理看慢查询日志让代码审查代理检查热点路径的代码让架构代理评估是否存在设计层面的瓶颈。三个代理看完之后主代理把所有分析结论汇总再输出一份「问题根因 解决路径」的报告。这种会诊式协作特别适合复盘场景。我第一次测试这个模式时效果超出预期一个我排查了两小时没头绪的问题四路并行下来很快就定位到了缓存穿透加 N1 查询叠加的根因。5. 常见问题与排查技巧实录5.1 多个子代理同时改代码冲突了怎么办并行编码最容易翻车的场景就是两个子代理改了同一个文件。即使你在任务分配时强调了文件边界子代理还是有可能会顺手调整公共模块。出现冲突时不要直接让主代理强行合并最好先把冲突文件交由一个子代理单独处理同时让其他代理暂停对相关文件的写入。我也学到一个更稳妥的做法在任务分配阶段就让子代理先输出「计划修改文件清单」由主代理检查是否存在重叠如果有重叠就重新划分边界。这个动作只花十几秒但能把冲突概率降到极低。5.2 子代理跑着跑着丢失了关键上下文子代理的执行时长较长时会出现上下文被清空或轮换的情况表现为它忘记了一开始的任务目标开始做一些偏离需求的操作。排查第一步是看任务日志里有没有上下文重置的记录第二步是检查子代理配置里max_context_tokens是否设置得太小。缓解手段有两种一种是把关键约束写进 Skill 文件让子代理每次唤起时都能重新读取另一种是设置阶段检查点每个阶段结束时让子代理把「当前进度 下一步计划」写回工作区文件。这样即使上下文重置它也能从检查点文件恢复状态。5.3 工作流卡住不动或超时工作流跑着跑着不动了通常原因是某个子代理在执行过程中抛出了异常但工作流没有配置失败处理策略就一直等待。排查时先看子代理的退出码和错误日志是文件读写权限问题、还是模型输出格式解析失败、还是依赖的 Skill 没有正确加载。我在配置工作流时习惯对每个阶段都加上超时时间和失败重试策略stages: - name: 实现 agents: [frontend, backend] mode: parallel timeout_seconds: 600 retry_count: 2 on_timeout: notifyon_timeout设为notify而不是fail能让你第一时间收到通知决定是让代理继续跑还是手动介入。这里建议把超时阈值设得比平时执行耗时多 30% 左右避免频繁误报。5.4 模型输出不稳定同一任务两次结果差异大温度参数对多智能体的输出稳定性影响非常大。同样的代码审查任务温度设为 0.8 时审查结果天马行空设为 0.2 时更贴合项目实际。如果你发现子代理的输出质量波动大第一件事就是检查它的temperature是否在合理范围。还有一个小技巧在子代理配置里加入output_schema规定返回结果必须是结构化格式[agent.reviewer] output_schema { result: pass|fail|warning, issues: [{file: , severity: blocker|suggestion, line: 0, message: }] } 格式化输出对后续主代理汇总结果非常有帮助省去了解析自然语言结果的成本。收尾关于多智能体的几句大实话折腾多智能体这么长时间我最大的体会是多智能体不是万能药它解决的是复杂任务的组织效率问题而不是模型能力问题。如果你的任务一张嘴就能说清楚比如「把这个函数改成支持可选参数」那就让主代理直接做完全没有必要调度子代理多智能体的调度开销反而成了负担。反之当任务涉及多个领域、多个模块、多个角色视角时多智能体的价值就体现出来了。最后分享一个经验从两个子代理起步一个负责开发、一个负责审查跑跑看效果再逐步增加文档、测试、调研等角色。不要一上来就配八个子代理跑一个超大工作流因为调度复杂度会指数级上升最后的瓶颈往往不是 AI 的能力而是你的流程设计是否合理。先把小闭环跑顺再扩大规模这样踩坑的成本更低也更清楚每个子代理到底能给你带来多少增量价值。 多智能体与高级工作流：用 Pi 打造 AI 协作开发团队
Pi 这类工具用顺手之后单线程让它写代码会越来越不过瘾。前面几篇讲的是怎么让 Pi 完成单个任务比如改 bug、写测试、做代码审查但真实项目从来不是单任务战场一个需求拆下来少说有三四个模块要动前后端要配合文档要同步测试要跟上。如果全塞给一个主代理串行处理要么上下文越拖越长导致后期指令混乱要么一个文件改动引发连锁反应却没人提前兜底。这篇「Pi 实战 04」就专门讲多智能体与高级工作流带你把 Pi 从一个「能干的助手」升级成「一个能带队干活的小团队」。我会从 Pi 的多智能体机制讲起把主代理和子代理的分工逻辑说明白再给一套可以直接抄的工作流配置方案包括需求拆解、并行编码、代码审查、测试收尾这几个环节最后补充几个我在实际操作中踩过的坑。适合已经对 Pi 的基本用法有了解、想让协作效率再上一个台阶的朋友阅读读完你会发现多智能体不是把任务丢给多个 AI 而已关键在于编排、上下文控制和风险闸门。1. 为什么要搞多智能体单代理模式的瓶颈在哪1.1 单代理越长越笨的上下文问题先看单代理的工作方式。你给 Pi 一个需求它在一个对话上下文中连续读文件、改代码、跑测试所有历史记录都会保留。这个模式在任务范围小的时候非常稳但一旦任务复杂上下文窗口就会被逐步填满。文本一多Pi 的注意力就会分散经常出现「前面说好的命名规范后面改着改着就忘了」或者「明明刚刚确认过某个接口签名下一轮就开始自由发挥」这类现象。这其实是所有大模型应用都绕不开的问题。上下文越长模型对早期指令的遵循度就越低同时对 token 的消耗也越大。我实测过一个包含几十个文件的增量改造任务如果全程塞在主代理里跑到后半程 Pi 的决策质量会明显下降而且每次回复前的等待时间肉眼可见地变长。与其硬扛不如把任务拆开让每个子代理只处理一个局部范围上下文短、目标清晰、输出质量反而更稳定。1.2 Pi 的多智能体工作机制Pi 的多智能体采用的是「主代理调度 子代理执行」的架构。主代理负责接收你的指令、拆解需求、分配任务、汇总结果子代理是轻量级的执行单元每个子代理有自己独立的上下文和任务清单干完活之后把结论交回给主代理。这个机制里最关键的一点是子代理之间不直接互相通信所有信息都通过主代理中转。这样做的好处是避免了多智能体之间消息风暴和上下文串扰代价是主代理的上下文会成为信息集散地所以控制好每个子代理回传内容的粒度很重要。你可以让子代理「只返回结论 变更文件清单 需要主代理注意的风险点」而不是把完整的会话记录倒出来。1.3 多智能体真正解决的是什么多智能体不是「多个 AI 一起干活」这么简单它解决的问题有三个一是上下文隔离每个子代理只需要加载自己负责的那部分代码不用背着整个项目历史二是并行效率没有依赖关系的任务可以同时跑省掉串行等待时间三是角色专业化你可以给不同子代理设定不同的人设和能力边界比如一个只做代码审查、一个只做安全扫描、一个只写技术文档每个子代理都能做到术业有专攻。有个类比挺合适单代理模式就像你雇了一个全能实习生什么事情都喊他做他忙得晕头转向还容易出错多智能体模式像是你带了一支小队拆解、编码、审查、测试各有专人你只需要坐镇指挥。对项目管理者来说后者的体验要好太多。2. 动手前的基础准备初始化工作区与角色配置2.1 安装 Pi 并初始化项目工作区开始之前先确认 Pi 的版本多智能体功能在较新版本里才算完整建议保持最新版。项目里执行pi init这个命令会在当前目录生成.pi/工作区目录里面包含全局配置、技能目录、代理角色定义等基础文件。初始化完成后用pi doctor检查一下环境是否正常它会报告配置文件的解析情况、依赖项是否齐全、工作区里有没有明显冲突。我建议把.pi/目录纳入版本管理团队协作时每个人拉下来都能保持一致的行为配置。不过要注意如果你的项目里已经有旧的.pi/目录先备份再升级新版初始化会覆盖部分配置文件。2.2 用 Skill 扩展子代理的能力Pi 的 Skill 机制相当于给代理安装「专业技能包」。比如你要让子代理做前端代码审查没有对应的 Skill 它也能做但有了 Skill 之后它会更清楚项目的技术栈规范、目录约定、常见反模式。Skill 可以通过pi skill install从市场安装也可以自己写本质是一个带说明文档和规则提示的文件夹。我最常用的操作是导入项目自定义 Skill。在.pi/skills/下建一个目录里面放一个SKILL.md文件内容用简洁的自然语言描述这个技能的使用场景、检查要点和输出格式--- name: project-reviewer description: 针对本项目的代码审查技能关注接口兼容性、数据迁移、日志规范 --- 检查代码时请重点关注 1. 涉及数据库变更时是否提供了相应的迁移脚本说明 2. 新增接口是否向后兼容是否有版本兼容策略 3. 日志输出是否遵循项目的统一格式Skill 不要写得过于抽象直接告诉子代理「在这个项目里什么重要」是最有效的。子代理加载 Skill 之后它的行为会明显更贴合项目实际。2.3 创建你的第一份子代理角色清单子代理的配置在.pi/agents.toml里定义每个子代理包含名称、角色描述、可用 Skill、允许的操作范围、温度参数等字段。下面是一份我常用的最小配置[agent.reviewer] role 代码审查员 description 负责检查代码质量、发现潜在 bug 和安全隐患只读代码不直接修改文件 skills [project-reviewer] permissions [read, run-tests] temperature 0.2 [agent.doc-writer] role 文档工程师 description 负责从代码变更中提炼文档要点并生成 Markdown 文档不修改源代码 skills [doc-generator] permissions [read, write-docs] temperature 0.5 [agent.frontend] role 前端开发 description 负责前端页面与组件实现遵循项目前端目录规范和代码风格 skills [frontend-stack] permissions [read, write] temperature 0.3这里有几个设置要点。温度参数控制创意的随机性代码审查、测试这类任务建议调低到 0.2 左右追求严谨文档写作可以稍高一点。权限控制一定要收紧安全相关的子代理尽量只读避免 AI 审查代码时顺手帮你改了文件那会非常灾难。配置完成后执行pi agents list可以查看所有子代理的状态。如果某个角色的 Skill 没有正确加载这里会直接报出来趁早排查。3. 一套能直接复制的多智能体工作流3.1 阶段一需求拆解与调研并行化拿到一个中等规模的需求时不要直接下令「开始干活」先让主代理做需求拆解。我会在 Pi 里发起这样一场会话请根据以下需求进行任务拆解并把每个子任务分配给最合适的子代理 需求给订单系统增加批量导出功能支持 CSV 和 Excel 格式要求可以按时间范围筛选、按状态筛选导出时不能阻塞主服务。主代理会结合项目上下文把需求拆成几个典型的子任务后端接口设计、导出文件生成模块、前端操作入口、异步任务队列改造、测试与文档。拆解完成后主代理会生成任务依赖图比如「前端入口依赖后端接口完成」「Excel 导出依赖文件生成模块完成」。这个阶段适合并行的是「调研型任务」。比如让一个子代理梳理现有订单表结构和接口另一个子代理调研项目里是否有现成的异步任务队列第三个子代理查看前端订单列表页的实现方式。它们互不依赖可以同时跑。主代理会在收到所有调研结论后做汇总形成一份实现方案。3.2 阶段二按模块并行编码需求分析完成后进入编码阶段。这个阶段最常见的错误是强行把所有模块同时开工结果接口还没定义好前后端各自按自己的想象去实现最后联调时全是冲突。我的做法是让主代理先定义好「契约」。比如后端接口的出入参结构、导出文件的字段清单、错误码规范这些先确定下来再分发给各个子代理并行开发。配置一个并行任务组请调度以下子代理并行执行 - frontend实现订单列表页的批量导出按钮和筛选条件 - backend实现导出任务的创建接口和状态查询接口 - async-worker实现导出任务的后台处理逻辑 所有代理必须遵循已确认的接口契约完成后报告变更文件和测试结果。并行编码时代码仓的冲突控制要注意。最好是每个子代理负责完全不同的文件目录避免两个代理同时改同一个文件的尴尬情况。如果项目比较小、文件之间耦合度高并行未必有优势串行反而更稳妥。3.3 阶段三代码审查代理独立上线编码完成不等于可以交付。我很坚持的一点是负责写代码的子代理和负责审查代码的子代理必须是不同的角色。首先写代码的代理对代码有「感情」不容易发现自己的问题其次审查需要更低的温度和更挑剔的眼光和开发代理共用一个上下文会影响判断。启动审查代理的命令大概是请 reviewer 审查以下分支的变更重点关注数据库迁移是否遗漏、接口兼容性、异常处理路径、日志规范。不要修改代码只输出问题清单和修改建议。审查代理会从只读权限的文件系统里快速浏览变更结合 project-reviewer Skill 的检查要点输出风险分级清单。通常我会要求审查结果标注严重级别阻塞问题、建议修复、可选优化。阻塞问题直接打回给对应开发代理处理建议修复的排到下一轮迭代。3.4 阶段四测试与文档收尾代码通过审查之后测试子代理开始工作。它负责补单元测试、集成测试以及关键路径的端到端验证。这里有一个重要细节测试代理需要知道哪些是「关键路径」不能所有函数都无脑补测试产出质量反而不高。文档代理在编码阶段结束后介入根据代码变更记录、接口定义、测试报告自动生成技术文档和变更日志。文档代理的权限只允许写 docs 目录不允许碰源代码。三个代理测试、文档、以及可能的构建发布代理在这个阶段又形成一轮并行。整个工作流跑完之后主代理会输出一份完整的交付报告包含变更文件树、测试覆盖率、遗留问题、发布建议。你只需要做最后的人工复核而不需要盯每一行代码的编写过程。4. 高级工作流的编排技巧与上下文管理4.1 表达任务依赖串行、并行与汇合多子代理协作时最常见的需求就是「A 做完 B 才能做C 和 D 可以同时做最后 E 汇总」。Pi 的工作流里可以用depends_on字段显式声明依赖关系也可以用更直观的分组语法# workflow.yaml stages: - name: 调研 agents: [env-explorer,>[agent.reviewer] max_context_tokens 10000 max_output_tokens 4000同时在主代理的调度指令里强调输出的精简性让子代理只返回变更摘要而不是大段代码。还有一种更省钱的方式把子代理的中间产出直接写入仓库里的临时目录回传时只带文件路径主代理需要看时再读取。这种「外置记忆」能大幅降低上下文占用。4.3 人机协作的审批闸门多智能体全自动跑完整个工作流听起来很爽但在真实项目里我强烈建议在关键路径上设置人工审批闸门。比如「契约定义」完成后需要你确认接口设计「代码审查」完成后需要你确认问题清单的处理方式。闸门机制避免了一个小错误被流水线放大到不可收拾的地步。Pi 支持在 workflow.yaml 里声明approval.required: true运行到该节点时会暂停下来等你确认。你可以在交互界面上查看这个阶段产出的摘要、变更文件、风险提示选择「通过」「打回」或「修改后继续」。这个设计相当于给了人控制多智能体的方向盘而不是把整个项目全权交给 AI。4.4 多智能体的「会诊」式协作除了流水线式的分工协作还有一种更高级的用法针对疑难问题让多个子代理从不同视角进行分析然后汇合出综合方案。比如线上出现一个偶发的性能问题你可以同时让性能分析代理看慢查询日志让代码审查代理检查热点路径的代码让架构代理评估是否存在设计层面的瓶颈。三个代理看完之后主代理把所有分析结论汇总再输出一份「问题根因 解决路径」的报告。这种会诊式协作特别适合复盘场景。我第一次测试这个模式时效果超出预期一个我排查了两小时没头绪的问题四路并行下来很快就定位到了缓存穿透加 N1 查询叠加的根因。5. 常见问题与排查技巧实录5.1 多个子代理同时改代码冲突了怎么办并行编码最容易翻车的场景就是两个子代理改了同一个文件。即使你在任务分配时强调了文件边界子代理还是有可能会顺手调整公共模块。出现冲突时不要直接让主代理强行合并最好先把冲突文件交由一个子代理单独处理同时让其他代理暂停对相关文件的写入。我也学到一个更稳妥的做法在任务分配阶段就让子代理先输出「计划修改文件清单」由主代理检查是否存在重叠如果有重叠就重新划分边界。这个动作只花十几秒但能把冲突概率降到极低。5.2 子代理跑着跑着丢失了关键上下文子代理的执行时长较长时会出现上下文被清空或轮换的情况表现为它忘记了一开始的任务目标开始做一些偏离需求的操作。排查第一步是看任务日志里有没有上下文重置的记录第二步是检查子代理配置里max_context_tokens是否设置得太小。缓解手段有两种一种是把关键约束写进 Skill 文件让子代理每次唤起时都能重新读取另一种是设置阶段检查点每个阶段结束时让子代理把「当前进度 下一步计划」写回工作区文件。这样即使上下文重置它也能从检查点文件恢复状态。5.3 工作流卡住不动或超时工作流跑着跑着不动了通常原因是某个子代理在执行过程中抛出了异常但工作流没有配置失败处理策略就一直等待。排查时先看子代理的退出码和错误日志是文件读写权限问题、还是模型输出格式解析失败、还是依赖的 Skill 没有正确加载。我在配置工作流时习惯对每个阶段都加上超时时间和失败重试策略stages: - name: 实现 agents: [frontend, backend] mode: parallel timeout_seconds: 600 retry_count: 2 on_timeout: notifyon_timeout设为notify而不是fail能让你第一时间收到通知决定是让代理继续跑还是手动介入。这里建议把超时阈值设得比平时执行耗时多 30% 左右避免频繁误报。5.4 模型输出不稳定同一任务两次结果差异大温度参数对多智能体的输出稳定性影响非常大。同样的代码审查任务温度设为 0.8 时审查结果天马行空设为 0.2 时更贴合项目实际。如果你发现子代理的输出质量波动大第一件事就是检查它的temperature是否在合理范围。还有一个小技巧在子代理配置里加入output_schema规定返回结果必须是结构化格式[agent.reviewer] output_schema { result: pass|fail|warning, issues: [{file: , severity: blocker|suggestion, line: 0, message: }] } 格式化输出对后续主代理汇总结果非常有帮助省去了解析自然语言结果的成本。收尾关于多智能体的几句大实话折腾多智能体这么长时间我最大的体会是多智能体不是万能药它解决的是复杂任务的组织效率问题而不是模型能力问题。如果你的任务一张嘴就能说清楚比如「把这个函数改成支持可选参数」那就让主代理直接做完全没有必要调度子代理多智能体的调度开销反而成了负担。反之当任务涉及多个领域、多个模块、多个角色视角时多智能体的价值就体现出来了。最后分享一个经验从两个子代理起步一个负责开发、一个负责审查跑跑看效果再逐步增加文档、测试、调研等角色。不要一上来就配八个子代理跑一个超大工作流因为调度复杂度会指数级上升最后的瓶颈往往不是 AI 的能力而是你的流程设计是否合理。先把小闭环跑顺再扩大规模这样踩坑的成本更低也更清楚每个子代理到底能给你带来多少增量价值。