企业官网建设流程全解析

做 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 与 Skill

2.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. 实战第一步：从一个任务演进到两个 Agent

3.1 拆任务边界：先做一张职责映射表

很多人一上来就打开面板新建 Subagent，结果建了五六个，用起来却一团糟。根因是没做任务拆解。多 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?days=7 - 返回字段：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，比如“按统一规范生成提交信息”，可以放在个人或团队级级别。混放的结果往往是项目环境里出现一堆不相关 Skill，Agent 自动触发时容易选错。

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 答非所问，多半不是模型不好，而是人给它的边界太模糊。把“什么不做”写清楚，效果立竿见影。

7.2 三个最值得记住的教训

第一个教训是过度拆分。预估总耗时不到十分钟的小任务，硬拆成三个 Agent 反而更慢，因为交接文档的同步成本超过了任务本身。我的经验值很简单：小事直接主 Agent 干，只有任务清晰、规模大、需要多角色时才上多 Agent。第二个教训是串行陷阱。建了一堆 Subagent 却还是按顺序排队用，等于放弃并行收益，只是形式上多智能体。边界独立的任务应该同时派发，否则时间依然翻倍。第三个教训是 Skill 维护赤字。建完从不更新的 Skill，会在流程变化后变成执行障碍。把 Skill 纳入代码仓库管理，定期审查，比追求数量重要得多。

8. 一点延伸想法与个人体会

8.1 多智能体最终考验的是设计能力

多智能体这套东西，真正难的不是上线那一刻，而是长期维持它的有效性。工具层面 Pi 已经给了足够的抓手，Subagent 拆分职责，Skill 固化标准，Desktop 与 Web 提供不同操作入口。但最终能不能跑好，取决于你是否把职责边界、交付格式、失败恢复这三件事想清楚。技术问题都能在文档里找到答案，反而是“如何定义一份好的交接文档”“如何判断任务该拆不该拆”这类设计问题，只能靠经验积累。

8.2 给新手的三条起步建议

如果你第一次尝试多智能体，我建议从最小的两 Agent 流程开始，比如主 Agent 加一个 code_reviewer，跑熟之后再逐步扩展成完整流水线。第二条建议是给每个 Subagent 写清边界，宁可多写也不要含糊，这一条能帮你避开大部分答非所问的问题。第三条建议是要有耐心，第一次编排失败非常正常，我当时光是调整交接模板就重来了三轮。多踩几次坑之后你会认同一个判断：稳定比花哨重要，少而清晰的工作流，远好过复杂但脆弱的编排。如果这篇记录里有一两条对你手头的项目管用，它就没白写。