做 Agent 开发有一段时间的朋友多半会被同一个问题卡住单条对话里的智能体再聪明任务稍微复杂一点它就顾此失彼。要同时改前端、写后端、补测试、查文档上下文长度有限工具调用频繁切换中间改一个需求前面全部乱掉。这也是我最近几个项目里把主力编码智能体换到 Pi 之后感触最深的一件事。这篇“多智能体与高级工作流篇”的实战记录就是想把我实际跑通的 Subagent 用法、工作流编排方式和 Skill 扩展技巧一次讲清楚给同样被单 Agent 上限折磨的人一条可复现的路径。先说明白这里的 Pi 不是树莓派也不是控制论里的比例积分控制器而是一个主打多智能体协作的编码助手。你如果已经在用 AI 写代码但总感觉效率没有想象中那么高这篇文章适合你。我会从架构关系讲到具体配置再到完整任务跑通的流程最后把踩过的坑列成表。内容偏实操看完可以直接在自己的项目里动手试。1. 先理清这里的 Pi 到底指什么1.1 别把 Pi 和树莓派、PI 控制器搞混每次在搜索引擎里输入 Pi返回结果都像开盲盒。一半内容是树莓派开发板一半是控制工程论文里的比例积分控制器参数偶尔还混进来“MMC 环流抑制器的 PI 参数”“PLL PI 控制带宽”这类自动控制题目。如果你是为了调电机闭环参数搜到这篇文章可以关掉了这里说的是 AI 编程圈子里讨论度很高的编码智能体工具 Pi。它跟硬件开发板、PID 控制器没有半点关系主打的是多智能体协同完成编程任务。我最初也是被热词搜索带偏翻了好几页自动控制论文才确认方向所以开头先把这件事说清楚免得你重复走我的弯路。有人会问一个编码工具而已为什么要专门写一篇多智能体和高级工作流答案很简单。单 Agent 的编码助手应付“帮我写个函数”“解释这段代码”这类小需求绰绰有余但一旦遇到“新做一个模块包含数据层、接口层、前端页面、测试用例还要符合团队规范”这种中型任务它就开始手忙脚乱。多智能体的价值恰恰是在这个临界点之后体现的。1.2 Pi 的几种打开方式怎么选按我的使用习惯Pi 常见的有三种形态命令行版 Pi CLI、桌面应用 Pi Desktop、网页版 Pi Web。它们共享同一套 Agent 内核差异集中在交互入口、文件系统访问和可视化程度上。我的选择逻辑很简单改一两个函数、问技术问题直接开 CLI启动快、路径短效率最高需要在多个 Agent 之间编排任务、观察它们交接产物时用 Desktop 更直观工作流一目了然偶尔在别的机器上临时验证想法打开 Web 版本就能跑。三种形态下创建的 Skill 和 Subagent 配置相互通用不存在“桌面版才支持多智能体”这种差别核心能力是一致的。补充一个容易忽略的细节CLI 和 Desktop 对本地仓库的访问方式略有不同Desktop 通常提供更直观的文件选择器和工作区视图CLI 则更依赖你在哪个目录下启动它。建议固定习惯所有项目都从项目根目录启动会话这样 Agent 对仓库结构的理解不会因为入口不同而变化。2. 多智能体架构的核心关系Agent、Subagent 与 Skill2.1 单一智能体撞上的天花板先用一个具体场景说明单 Agent 的困境。我让一个编码助手完成“给现有服务增加一个导出报表接口”它会先写接口再写 SQL再写路由注册最后还要补 Swagger 注释。前三个回合还好到第四回合它可能把“需求里要求按月份过滤”这个约束给忘了或者把无关模块的代码也一并改了。这不是模型偷懒而是上下文窗口和注意力分配的结构性限制在一个连续对话里较早的信息会被后续大量代码和工具输出稀释模型越来越难回溯最初的约束。更麻烦的是需求变更的连锁反应。原来的接口叫 report/list你中途说改成按周导出单 Agent 需要同时记住“改路由、改参数、改 SQL、改前端调用、更新测试”任何一个环节漏了结果就是接口文档和实现不一致。这个问题的根源不是某个模型能力不足而是单一上下文的天然瓶颈要突破它只能从架构层面下手。2.2 Subagent 解决的是“工作记忆污染”问题Subagent 的本质是把一个大任务的上下文切分成互相隔离的分区。每个子 Agent 只加载自己需要的输入只关注自己职责范围内的输出主 Agent 负责调度与汇总。这样负责 SQL 的 Agent 永远不需要浏览前端组件代码它的上下文里只有表结构和接口定义工作记忆自然“变长”了。我在 Pi 里跑多 Agent 后有两个直观变化。第一单次会话的有效长度明显增加因为每路 Agent 的输入都被收敛到很小范围第二跨 Agent 交接时更容易保持一致因为交接物是明确的一手产物而不是聊天记录里的只言片语。你可以把 Subagent 想成不同科室的医生——心内科医生只看心电图和化验单不会翻骨科病历单 Agent 则像一个全科医生接诊所有病病历越积越厚最后反而抓不住重点。2.3 Skill 是工作流的标准化积木如果 Subagent 回答的是“谁来干”Skill 回答的就是“按什么标准干”。Skill 是预先定义好的执行流程可以包含提示词、工具调用序列、输出格式规范甚至绑定外部命令。一个成熟团队通常会把“如何进行规范的技术评审”“如何按团队模板生成提交信息”这类高频流程写成 Skill让任何 Agent 都能随时调用。Skill 和 Subagent 经常被混用两者关系可以这样理解Subagent 是一个相对长期的角色拥有自己的系统提示词和职责边界Skill 则是一个任务级的动作模板可以被不同 Agent 在合适时机触发。一个 Agent 可以拥有多个 Skill同一个 Skill 也可以被多个 Agent 使用。把二者配合好才称得上高级工作流只创建一堆 Subagent 而没有任何 Skill充其量是把一个脏乱差的大上下文拆成了好几个脏乱差的小上下文。3. 实战第一步从一个任务演进到两个 Agent3.1 拆任务边界先做一张职责映射表很多人一上来就打开面板新建 Subagent结果建了五六个用起来却一团糟。根因是没做任务拆解。多 Agent 协作的成败在任务还没交给 Agent 之前就决定了。我习惯先把需求在纸上拆成一张简单的映射表列出每个参与角色的名称、职责、输入和输出。Agent 角色职责范围输入输出规划 Agent需求拆解、任务分配原始需求任务清单和边界定义接口 AgentAPI 设计与字段定义需求清单接口文档实现 Agent业务代码编写接口文档可运行代码审查 Agent代码审查与问题反馈实现代码审查报告测试 Agent测试用例设计与执行实现代码、需求测试报告这张表最大的价值是逼你提前想清楚 Agent 之间的交接物是什么。没有交接物两个 Agent 协作就会出现“你以为它做了它以为对方做了”的情况。拆表的过程花不了十分钟但能避免后面大量返工。3.2 创建 Subagent 时真正该填好的字段在 Pi 的 Desktop 或 Web 界面通常可以在 Agent 管理面板里找到“新建 Subagent”的入口。核心字段不多真正要上心的有三个名字、系统提示词、可用 Skill 与工具。名字建议直接用职责英文命名比如 api_designer、ui_builder、code_reviewer不要用 agent1 这种无意义的名字。后续编排时你会频繁在对话里引用它一个好记且语义明确的名字能明显降低沟通噪音。系统提示词请务必包含四块内容角色定位、工作边界、输出格式、完成标准。以代码审查 Agent 为例我会这样写你是一名资深代码审查者只负责发现逻辑缺陷、安全风险和可读性问题不修改代码。 不做不重构实现不替你写修复补丁只产出问题清单。 输入待审查的代码文件路径、相关需求说明。 输出按严重程度分级的 Markdown 审查报告每个问题注明文件、行号、原因和修改建议。 完成标准所有已知问题都被记录未发现问题时也需明确说明。不要小看“边界”这一项它是防止子 Agent 越权乱改资源的关键。可用 Skill 与工具的配置取决于职责接口 Agent 通常只需要读文件和写文档的能力实现 Agent 才需要真正动代码。这一步配置不对后续会出现“让接口 Agent 改代码”这种角色错乱。3.3 主 Agent 如何把任务转交出去有了两个 Subagent接下来就是编排。还是拿“新增导出报表接口”举例完整的主 Agent 指令可以是这个需求先由 api_designer Agent 负责设计接口与数据库字段完成后把接口文档交给我 我会把接口文档同步给实现 Agent由它完成代码。 实现完成后请 code_reviewer Agent 做一次独立审查审查问题列表回传给我再决定是否修复。仔细看这段指令它做了三件事指定执行角色、明确交接物方向、设定审查回传节点。这才是多 Agent 编排里主 Agent 该干的活——调度而不是亲自动手写所有代码。还有一点反直觉你不应该要求主 Agent 每一步都汇报那只会把上下文档塞满。更好的做法是让子 Agent 只回传结构化摘要详细产物写到文件中需要时再按路径调取。4. 高级工作流的四种编排套路与一次完整落地4.1 四种高频工作流模式跑过多个项目后我把实际用得上的工作流模式归成四类按使用频率排序。流水线模式需求依次经过规划、设计、实现、测试像工厂流水线。适合需求明确、流程稳定的模块优点是每步职责清晰缺点是总时长受串行环节限制。并行拆分模式一个大功能拆成互不依赖的多个任务同时交给多个实现 Agent最后统一合并。适合版本迭代中边界清晰、无耦合的大改动收益最高。主从审查模式实现 Agent 产出代码后审查 Agent 独立复查并返回问题清单实现 Agent 根据清单修正必要时循环。适合核心交易、支付这类质量要求极高的代码。反射迭代模式同一个 Agent 对自己的方案先质疑再修改反复两三轮。适合技术方案设计、架构文档这类需要自洽的内容。强调一句实际项目里几乎没有单一模式基本都是嵌套组合。比如并行拆分内部每个支线又是流水线整体完成后套一层主从审查。模式是工具箱里的锤子别一次只带一把。4.2 一次完整的多 Agent 任务例跑用一个内部小工具做具体演示。需求是做一个数据看板展示接口调用量趋势包含数据聚合、页面渲染、自动化测试三块。我的编排是规划 Agent 先把需求拆成三个工作包数据接入 Agent 与前端 Agent 并行执行前端完成后触发布局审查 Agent 检查界面合理性复审通过后测试 Agent 补齐用例。整个过程最关键的机制是交接物。规划 Agent 的产出是一份任务说明文档里面写明每个工作包的范围、接口约定、验收标准。比如接口约定部分可能会长这样## 工作包数据看板 ### 接口约定 - GET /api/statistics/trend?days7 - 返回字段date, total_count, success_count ### 前端要求 - 使用现有图表组件展示折线图 ### 验收标准 - 页面在 1024px 宽度下无横向滚动数据接入 Agent 只把聚合 API 的契约文档交给前端 Agent而不是把整个数据层代码扔过去前端 Agent 的产出自带自测清单测试 Agent 再基于需求和实现两边信息生成用例。我用这套跑下来整体返工量大概是单 Agent 硬做时的一半。前期设计交接物花的时间多一点但后面省下的时间远超这个数。5. Skill 的导入、自建与维护5.1 导入现成 Skill 的路径与验证Pi 的 Skill 支持外部导入社区里也有人分享现成的能力包。按我的经验导入路径通常有两个一是直接导入 Skill 文件在设置页面的“导入 Skill”入口选择文件即可二是从社区页面复制内容在 Workspace 里新建 Skill 后粘贴保存。两种方式结果一致区别只是来源。导入后我要给两个建议。第一先看元信息里的适用场景、依赖工具和输出说明别被名字迷惑。有的“代码审查”Skill 实际只对 Markdown 文件做检查未必接入了真实编译环境。第二导入后一定先做一次小范围验证——开一条新会话手动触发这个 Skill在迷你测试仓库上跑一遍确认它调用的确实是你预期的工具链。社区资源质量参差不齐有的是一整套流程有的只是包装过的提示词不验证就用于生产项目容易在关键时刻掉链子。5.2 自建 Skill 的四段式模板自建 Skill 更贴合团队习惯。我长期使用的模板分为四段元信息、触发条件、执行步骤、输出规范。一个简化示例--- name: review_code description: 对指定目录下的代码执行一次分级审查。 applies_to: [code_reviewer] commands: [run_lint, run_test] output: review_report.md ---元信息名称、描述、适用场景、依赖工具。触发条件说明 Agent 在什么情境下应该主动调用它例如“当用户要求新增一个列表页面且涉及数据表格展示时”。执行步骤有序列出每一步动作细化到具体命令或工具调用。输出规范明确交付物的格式、存放位置、完成标准。保存后先在新建对话里手动指定调用跑通流程后再放开自动触发。这样把“流程本身是否正确”和“自动识别是否准确”两个变量分开排查定位问题会容易得多。Skill 描述写得精确与否直接决定自动触发的准确率把适用场景写清楚永远比笼统地写“用于前端开发”有效。5.3 Skill 的更新与版本管理Skill 建完不是终点。团队流程一变老 Skill 就会变成执行障碍。我习惯把项目相关的 Skill 定义文件放进项目的 .ai/skills 目录下统一管理跟着 Git 走。任何一次流程调整都同步修改 Skill并在提交信息里说明原因。这样有两个好处一是新成员能通过代码评审看到 Skill 的演进历史二是换机器或换人时Skill 可以直接从仓库恢复不依赖个人聊天历史。特别提醒别把项目里的 Skill 和个人账户里的 Skill 混为一谈。凡是和具体项目强相关的 Skill尽量放在项目内维护纯通用的 Skill比如“按统一规范生成提交信息”可以放在个人或团队级级别。混放的结果往往是项目环境里出现一堆不相关 SkillAgent 自动触发时容易选错。6. 上下文管理、记忆落盘与效率调优6.1 把 Token 当预算来分配多 Agent 不是免 token 套餐只是把上下文变成可控预算。主 Agent 的上下文应该尽量留给目标状态和任务进度不需要沉淀大段代码子 Agent 的上下文留给输入交接物和产出物。信息流方向最好单向子 Agent 完成后只把摘要和文件路径回传主 Agent不把日志、编译输出整段塞回来。如果是长任务建议阶段完成任务后归档会话或清理任务列表避免历史任务长期占用活跃容量。一个具体的预算例子假设上下文足够容纳约 2 万 token 的对话我会把主 Agent 的活跃内容控制在约 4 千 token给规划类 Agent 的交接物留约 2 千实现类 Agent 因为要读代码预留最多 1.2 万审查类 Agent 预留约 2 千。这个比例不是死的但核心思路是别让主 Agent 变成信息仓库。6.2 用 AGENTS.md 把关键决策固化下来跨会话记忆永远是难题。项目里的隐含约定——目录结构、命名规范、已知坑、架构取舍——如果只存在于某次对话里下次新会话的 Agent 大概率不知道。我的解决办法是在项目根目录维护一份 AGENTS.md用简明语言记录关键约定三五十行即可# 项目约定 ## 技术栈 - Python 3.11 FastAPI SQLAlchemy ## 目录结构 - app/api 放路由app/services 放业务逻辑app/models 放数据模型 ## 规范 - 新接口必须带 Pydantic schema禁止直接返回 ORM 对象 ## 已知坑 - 数据库连接池默认 10并发测试时注意打满 ## 架构决策 - 所有外部 API 调用走 service 层禁止在路由层直接发请求每次新会话开始先让规划 Agent 读取 AGENTS.md 再开工。这个习惯的收益是跨会话的哪怕中间隔了几天Agent 依然能保持一致的项目上下文比依赖对话记忆可靠得多。6.3 效率调优的几条实测经验最后分享几条实测有效的调优经验未必都在官方文档里。第一子 Agent 的工具范围越窄越稳别给所有 Agent 都挂满权限。第二交接文档越短越好能写清接口契约就不要整段代码。第三审查类任务和实现类任务不要用同一个 Agent独立上下文才能提供独立视角。第四高频小任务不走多 Agent 流程主 Agent 直接完成避免为了协作而协作的仪式负担。这些规则都是我吃过几次亏之后才沉淀下来的现在基本是我所有项目的默认配置。7. 高频问题与避坑实录7.1 问题速查表把这段时间遇到的高频问题整理成表方便你遇到情况直接对照。现象可能原因处理方式子 Agent 答非所问系统提示词里边界不清补全职责范围和明确禁止项多个 Agent 产出互相矛盾交接物格式没有统一设计固定交接模板并要求严格遵守上下文快速耗尽主 Agent 接收了过多子 Agent 日志限制回传格式为摘要加文件路径Skill 从不自动触发描述与触发条件过于宽泛细化适用场景先手动验证某个子 Agent 出错拖垮全局没有失败恢复和超时控制增加错误返回路径让任务可重整并行执行产生文件冲突工作区没有做目录隔离按 Agent 拆分输出目录并移交给下游每条问题背后都对应一次实操教训。表里第一行最常出现——子 Agent 答非所问多半不是模型不好而是人给它的边界太模糊。把“什么不做”写清楚效果立竿见影。7.2 三个最值得记住的教训第一个教训是过度拆分。预估总耗时不到十分钟的小任务硬拆成三个 Agent 反而更慢因为交接文档的同步成本超过了任务本身。我的经验值很简单小事直接主 Agent 干只有任务清晰、规模大、需要多角色时才上多 Agent。第二个教训是串行陷阱。建了一堆 Subagent 却还是按顺序排队用等于放弃并行收益只是形式上多智能体。边界独立的任务应该同时派发否则时间依然翻倍。第三个教训是 Skill 维护赤字。建完从不更新的 Skill会在流程变化后变成执行障碍。把 Skill 纳入代码仓库管理定期审查比追求数量重要得多。8. 一点延伸想法与个人体会8.1 多智能体最终考验的是设计能力多智能体这套东西真正难的不是上线那一刻而是长期维持它的有效性。工具层面 Pi 已经给了足够的抓手Subagent 拆分职责Skill 固化标准Desktop 与 Web 提供不同操作入口。但最终能不能跑好取决于你是否把职责边界、交付格式、失败恢复这三件事想清楚。技术问题都能在文档里找到答案反而是“如何定义一份好的交接文档”“如何判断任务该拆不该拆”这类设计问题只能靠经验积累。8.2 给新手的三条起步建议如果你第一次尝试多智能体我建议从最小的两 Agent 流程开始比如主 Agent 加一个 code_reviewer跑熟之后再逐步扩展成完整流水线。第二条建议是给每个 Subagent 写清边界宁可多写也不要含糊这一条能帮你避开大部分答非所问的问题。第三条建议是要有耐心第一次编排失败非常正常我当时光是调整交接模板就重来了三轮。多踩几次坑之后你会认同一个判断稳定比花哨重要少而清晰的工作流远好过复杂但脆弱的编排。如果这篇记录里有一两条对你手头的项目管用它就没白写。