企业官网建设流程全解析

大概在一年多前，我们团队开始做一件看起来挺激进的事：把软件研发流程里大量可重复的执行环节，交给一整套由大语言模型驱动的多智能体协作系统来跑。我们内部给它起的代号是 Agency Agents——它模拟了一个小型虚拟公司的岗位结构，从需求拆解、方案设计、编码提测到代码评审，全部由不同角色的智能体接力完成。这篇就当是阶段复盘，重点聊这套系统的架构是怎么设计的，以及真正落到真实项目里踩过的那些文档不会告诉你的问题。

先说结论：这套系统没有"取代工程师"，而是把团队里最耗精力的沟通、等待和重复劳动吸走了。它既不是某个"写了就能自动生成整个网站"的玩具脚本，也不是玄学式的全自动开发工具。它更像是一套把团队SOP（标准作业程序）变成可执行状态机，让一堆各司其职的智能体在共享工作区里协作的工程框架。这篇文章适合正在考虑引入AI Agent辅助研发、想搭建多智能体系统但又不知道从哪里入手的团队，也适合对"Agent协作到底靠不靠谱"持怀疑态度的人。

1. 为什么要把开发团队"重构"成多智能体协作系统

1.1 传统协作模式的三个瓶颈

在真正动手之前，我们先复盘了研发协作里的痛点。这些痛点任何超过五个人的技术团队应该都很熟悉。

第一个是信息衰减。一个需求从产品经理口头描述，到技术方案、任务拆分、编码、测试、上线，中间经过五六个环节。每一环都会丢失一部分上下文：接口参数写错、字段命名不一致、验收标准含糊、某个关键约束只存在于某个人的聊天记录里。信息一旦进入"人传人"的链路，就注定会失真。

第二个是事务性等待。开发等产品确认、前端等后端接口、后端等架构评审、测试等提测环境。据我观察，传统模式下工程师真正坐在那里写代码的时间，可能不到工作时间的四成，剩下的时间都在开会、同步、催人、改格式。这种等待不是某个人的问题，是流程本身没有闭环。

第三个是隐性知识独占。某个核心模块只有特定开发者能改，因为所有关键决策都存在他脑子里；他一旦休假或离职，就有一段明显的交付停滞期。团队的知识没有沉淀成显性资产，而是以"谁记得谁说了算"的方式存在。

这些瓶颈叠加起来，我们才意识到：与其继续优化人的沟通效率，不如试着把研发流程本身"降维"成一组可观测、可回放、可约束的任务流转。

1.2 重构的本质：让研发流程变成可编排的智能体流水线

所以标题里说的"重构开发团队"，重构的并不是人事结构，而是工作流结构。传统软件开发流程里，一个需求会经历"需求分析→设计→开发→测试→发布"，每一步都需要一个角色去执行。这些角色和步骤其实天然适合被形式化为状态机：每个Agent就是一个角色，每个角色有明确输入、输出和验收标准，任务在这些 Agent 之间流转。

这里要强调一个认知：多智能体协作系统的价值，不在于"某个Agent写代码有多厉害"，而在于多个Agent之间形成了分工、互验、反馈的闭环。单个大语言模型再强，也只是"一个人写完代码自己看"，很容易被自己的假设带偏；但让"后端Agent"和"代码评审Agent"分别站在不同角色的视角看同一个改动，就会产生真正的检查效应——它们会互相发现"你接口定义和调用方不匹配"、"你改了功能但没改测试用例"这类单点模式下最容易漏掉的问题。

引入这套系统前我们把SOP一字一句整理成了文档，包括需求如何拆、任务如何分、评审标准是什么、返工如何触发。这些文档原本只是挂在团队Wiki里吃灰的流程说明，现在变成了多智能体协作的协议。我的体感是：这套系统的架构，本质上就是团队协作规范的代码化。

2. Agency Agents 的四层架构：从角色定义到工具执行

2.1 角色层：每个Agent都有一份"岗位说明书"

Agency Agents 的底层是角色定义，这才是整个系统最核心的部分。一个 Agent 不是简单的一句"你是后端开发"，而是一整套完整的岗位说明书，包括职责边界、技术栈要求、可用工具白名单、产出物格式、质量标准和汇报口径。

我用一份简化版本来说明后端开发Agent的定义大概长什么样：

{ "role": "backend_developer", "responsibilities": [ "负责按Task描述实现后端接口", "必须为新增函数编写单元测试", "不得修改contract registry之外的接口定义" ], "tech_stack": ["Python", "FastAPI", "PostgreSQL"], "allowed_tools": ["read_module", "write_file", "run_test", "git_commit", "query_contract"], "output_schema": { "pull_request_title": "types/feature/xxx", "commit_message": "conventional-commits" }, "quality_bar": [ "所有测试通过", "接口字段与contract registry一致", "关键逻辑有单测覆盖" ] }

岗位说明书的意义在于把 Agent 的行为限制在可预期范围内。角色之间不直接聊天，而是通过共享工作区和事件总线来间接协作。设计初期我们试过让两个 Agent 直接在对话里来回商量，结果十个需求里至少有六个会在闲聊式对话里跑偏——A说你改一下，B说你改一下，最后谁都没改。后来才明白，人类聊天尚且会互相传染错误认知，模型之间直接对话更是上下文污染的重灾区。

2.2 编排层：SOP状态机与流水线调度

角色定义之上是编排层，这部分我们叫它 Orchestrator。它负责的事情包括：启动对应角色的 Agent、把任务事件传递给它们、监控执行超时、执行失败后的重试策略，以及把任务从一个状态推到下一个状态。

Agency Agents 的任务流转被建模成一张状态机，核心状态包括：

• 待拆分：需求进来，等待产品Agent拆解
• 开发中：任务被某个开发Agent领取
• 评审中：代码进入交叉评审队列
• 返工中：评审发现问题，打回开发Agent
• 已验收：通过全部检查，等待人工确认
• 已合并：人工点头，分支合入主干

我们在编排层实现了三种协作模式，分别应对不同场景，这里用表格做个对比：

我们主要采用第三种，因为软件开发不是一个单向流水线，它天然有返工、回归、变更评审这些反向依赖。状态机配合事件系统，能让整个研发过程在宏观上可追踪。

2.3 记忆与状态层：全局蓝图 + 短期上下文 + 长期沉淀

记忆设计是最容易在初期被忽略的部分，也是后来踩坑最深的区域。我们在 Agency Agents 里把记忆拆成了三层：

第一层叫全局蓝图（Blueprint），相当于项目的宪法。里面包括需求的用户故事、技术选型、模块划分、接口合约（contract registry）和非功能性要求。全局蓝图是共享的单一事实源，任何 Agent 都不能凭记忆修改它，必须通过专门工具提交变更。

第二层叫短期工作记忆，指 Agent 在某一项任务执行中需要马上用到的上下文，比如当前开发的 Task 卡片、相关模块的现有代码、最近一次测试输出。这部分会持续作为 prompt 内容传递给模型。

第三层叫长期沉淀，指历史决策、踩过的坑、可复用的代码模式，存放在向量数据库中，Agent 需要时通过检索工具按需读取，而不是一股脑塞进上下文。

分层的核心逻辑是：把"必须准确的信息"与"仅供参考的信息"分开。接口定义必须准确，所以放全局数据库；代码风格偏好可以参考，所以放向量库；执行过程中的日志和过程信息，则尽量不进上下文。这三层如果混在一起，Agent 很快就会被无关信息淹没。

2.4 执行层：沙箱、工具白名单与结果回执

最底层是执行环境。每个开发、测试类 Agent 都运行在独立的 Docker 沙箱里，拥有自己的文件系统副本、依赖目录和 Git 工作区。沙箱保证了一个 Agent 的破坏性操作不会影响其他任务，也方便任务失败后一键销毁重建。

工具层是我们非常克制的地方。我没有开放"自由终端"给 Agent 随便执行 shell 命令，而是封装了一组领域工具：read_module、write_file、run_test、git_commit、query_contract、list_files、create_pr等等。工具的 Schema 里定义了每个参数的取值范围和校验规则。这样做的原因后面踩坑部分会讲，这里先记一个原则：Agent 能接触的指令范围越窄，越容易得到稳定行为。一个只需要提交代码的智能体，不应该被允许去执行rm -rf。

每次工具调用都会产生一个执行回执，包括标准输出、错误码、文件变更列表和耗时。回执会被 Orchestrator 摘录成简短的结果摘要，再追加回 Agent 的短期上下文。整个过程就像给 Agent 配了有限但好用的"手"，以及一双能不断收到反馈的"眼睛"。

3. 落地阶段的核心机制：任务拆分、验收闭环和人工审批

3.1 从一句话需求到可执行的Task清单

架构在纸面上成立之后，紧接着的问题是：一个真实需求进来，多智能体系统怎么把它变成能落地的任务？

我们的流程是：产品Agent先拿到需求描述，产出用户故事与验收标准，这里面必须写清楚"什么算做完"；然后架构Agent上场，结合全局蓝图把需求拆成模块级任务，输出每个模块的接口契约；最后任务进入任务池，各开发Agent按能力领取。

这里有一个特别重要的经验：任务粒度不要太大。一个任务应该对应一次可验证的代码变更，最好能在几百行代码以内完成。如果任务描述超过五六百字，Agent 的上下文就容易被冗长的叙述占满，注意力反而下降。我们一般控制每个 Task 的说明在二三百字左右，包含目标、涉及文件、接口依赖和验收标准。

一个典型Task卡片长这样：

Task A-102: 实现订单详情接口GET /orders/{id}

• 返回字段需与 contract registry 中order_detailschema 一致
• 使用仓库现有db.py的数据访问方式，不要引入新 ORM
• 新增单元测试覆盖正常/404/字段缺失三种情况
• 测试通过后提交 PR，PR 标题以feature/开头

任务拆分得越清晰，Agent 的完成质量越稳定。反过来，如果需求本身模糊，比如只写"把订单流程完善一下"，Agent 就会自己脑补一堆不必要的需求，产出必然跑偏。

3.2 交叉评审闭环：让智能体之间互相发现问题

拆解完任务只是开始，质量保障要靠评审闭环。开发Agent完成代码并自测通过后，会提交一个PR事件；这个事件会触发评审Agent（通常是另一个扮演架构师角色的Agent）来对改动做交叉检查。

评审Agent不是随便看一眼就给结论，它会拿改动和全局合约做对比，检查接口字段是否漂移、命名风格是否统一、测试是否覆盖到边缘情况，并把问题结构化输出。每条评论要分成三类：bug（功能缺陷）、spec（不符合规格）、quality（代码质量问题），同时标注严重级别和期望修正方向。

这套结构化评审机制解决了两个问题：一是反馈有了统一格式，开发Agent不用从大段自然语言里猜测对方真正想让自己改什么；二是评审意见本身就变成了返工任务的输入，可以直接驱动下一个状态，不需要人工转抄。我们规定同一任务最多返工三轮，超过三轮后 Orchestrator 自动把任务推给人工处理。这个熔断机制看着简单，实际省掉了大量"改来改去都改不对"的无限循环成本。

3.3 人工审批节点：在关键位置保留人的决策

多智能体系统再好用，我始终不建议让它在完全没有人类监督的情况下自动合并代码。Agency Agents 的流程里预设了五个人工审批节点：

• 分支合入主干之前
• 生成外部访问凭据或密钥
• 申请云资源、扩容、变更数据库结构
• 对存量核心模块的大规模重构
• 任何涉及对外接口的变更

人工审批节点的本质不是"再走一遍质量复核"，而是控制风险和成本。代码写错了可以回滚，密钥泄露了、数据库表被锁了、对外接口被下游依赖方投诉了，这些代价远高于一次人工点审批的时间成本。

实际操作中我们用了"自动完成90%，人工抽查10%"的节奏。低风险任务的合并可以由评审Agent通过后自动执行，但每周五我会抽几个已合并的PR做人工代码走查，检查Agent们是不是因为互相评审产生了"共谋式"的互相放水。好在目前没有发现系统性问题，但这个抽查习惯我会一直保留。

4. 工程实现细节：模型选型、工具接口与状态恢复

4.1 不要用一个大模型包办所有角色

很多初搭建多智能体系统的人会问：是不是只需要选一个最强的模型，所有角色都用它？我们的实测结论是：完全不是。不同角色对模型能力的需求完全不同，统一用强模型不仅贵，而且因为指令复杂反而更容易出问题。

架构师Agent和评审Agent需要强推理能力，用来理解抽象方案、比较多个约束之间的关系，我们用的是推理能力梯队里第一梯队的模型；开发Agent需要代码生成质量好、但不需要理解全局，我们尝试用中等规模的模型，单测覆盖率和代码质量已经足够；产品Agent和文档Agent基本就是信息抽取和重组，一个小型模型就能胜任，成本可以压到很低。

另一个关键设计是上下文预算管理。我们给每个 Agent 的短期上下文设了硬上限（通常16K tokens，复杂任务最高32K）。一旦超出，更早的内容会被自动归档到长期记忆里，而不是无限撑大上下文窗口。原因有两个：一是成本失控，token 长了开销是线性甚至超线性的；二是模型对过长的上下文指令遵循度会下降，经常读到后面忘了前面的命令。让 Agent 保持"短上下文、小任务、多轮反馈"是更可控的执行方式。

4.2 工具接口的两种实现：Function Calling 与 MCP

执行层的落地绕不开工具接口怎么暴露给 Agent。我们同时试过原生 Function Calling 和 MCP 两种方式，这里简单对比一下：

实际项目中两种可以共存：沙箱内的文件工具用 Function Calling 最顺手，跨系统的协作工具适合走 MCP。但无论哪种方式，我们都会统一经过一个 Executor 层。Executor 做的事情是校验参数、执行工具、截取输出摘要、记录审计日志。它像一个网关，Agent 不直接接触底层命令，所有操作都有迹可循。

我特别想强调工具 Schema 的设计：参数能具体就具体，能限定枚举就限定枚举。比如run_test工具，参数是测试文件路径和预期通过数量，而不是允许 Agent 自行拼接任意 pytest 命令。自由度过高的工具，早晚会变成幻觉的出口。

4.3 任务状态持久化与崩溃重启

多智能体协作系统跑久了之后，最容易被忽视的是运行时的可靠性。毕竟大语言模型调用、容器执行、网络请求，任何一个环节都可能中断。系统一旦崩溃，如果所有 Agent 的上下文都只存在内存里，整个任务线就全丢了。

我们把任务状态统一放在 PostgreSQL 里，每个任务有当前状态、所属Agent、重试次数、最近一次事件ID；每个 Agent 的执行日志也会持久化到对象存储。崩溃之后，Orchestrator 根据持久化状态重建上下文，从最近一个成功事件重新推送，而不是让 Agent 从空白开始。

一条典型的查询就能看到全局：

SELECT agent_id, task_id, state, current_stage, retry_count, updated_at FROM agent_tasks WHERE project = 'demo_project_x' AND state IN ('rework', 'running') ORDER BY updated_at DESC LIMIT 50;

除此之外，所有提交类操作都实现了幂等性。比如create_pr如果执行成功但没有收到回执，Agent 重试时不会生成两个重复的 PR；每次重试会带一个全局唯一的 request_id，工具层据此判断是否已处理过。这个细节如果不处理，Agent 一重试就会造成大量重复评论、重复合并，系统很快会乱成一锅粥。

5. 踩坑实录：四类典型故障的完整排查链路

这一部分我想认真写。因为真正让一个多智能体系统从"演示级"走向"生产级"的，不是架构图画得多漂亮，而是能不能把故障一个个按下去。

5.1 "甩锅"事件：接口到底做没做？

我们遇到的第一个大坑，是前端Agent在联调时反复报告"后端接口不存在"；后端Agent则一口咬定"接口早就提交了"。两边互不相让，评审Agent也判断不了谁对，任务卡在返工中停了一整天。

排查链路是这样的：我先查了任务事件日志，确认后端Agent确实执行过接口创建操作；再拉全局契约注册表的变更记录，发现里面根本没有对应的接口 schema 新增条目——后端Agent的"提交"只写进了自己沙箱里的代码文件，没有同步到全局合约。也就是说，前端Agent查询合约时当然查不到。

根因找到了：两个Agent各自维护了一份对"接口状态"的记忆，而这两份记忆没能收敛到同一个事实源。修复方式是我们加了一个硬规则——接口定义的变更必须通过update_contract工具写入合同注册表，否则不算完成库，而且所有Agent只能从注册表读取接口信息，禁止从自己的会话历史里推断接口存在与否。这次事件让我们把"单一事实源"从原则变成了强制执行机制。

5.2 死循环与返工风暴：Token成本暴涨

运行到第三周时，某条任务线上出现了一次惊人的 token 消耗：一个返回上传接口的小改动，评审Agent连续打回四次，开发Agent每次都按照字面意见改了，但评审Agent总能找到新问题。到第四次时，两个Agent的上下文都已经塞满了几千行对话历史，费用几乎够平时跑几十个任务。

排查过程让我意识到一个结构性缺陷：评审Agent的反馈没有收敛标准，返工也就没有终点。第一轮说"缺少错误处理"，开发Agent加了 try-except；第二轮说"错误处理太宽泛，吞了异常"，开发Agent改成精确捕获；第三轮说"变量命名不符合团队规范"……每一轮都能找到一个新角度，看起来是在改问题，实际是两个模型在一场没有终止条件的博弈里互相放大偏见。

解决办法是把评审反馈严格结构化，并要求每次返工必须显式声明"解决了哪一条反馈、对应影响是什么"；同时给同一任务设置返工上限（我们设为三轮），超过后自动上报人工。另外，我将对话式历史改成只保留最近两轮原始信息，更早的评审结论则压缩成摘要。加了这两道闸之后，返工风暴基本绝迹。

5.3 上下文污染：Agent"失聪"不听话

第三个坑有点隐蔽。某个编码Agent跑了十几个小时后，开始出现"指令失聪"：明明角色定义里写了用 TypeScript，它却开始写 JavaScript；说好了 commit message 用 conventional 规范，它又提交了随手写的中文说明。

第一反应是提示词被覆盖了，但检查后发现角色定义并没有变。真正的问题出在上下文内容上——该Agent最近几轮任务里，每次执行构建都输出了上万字的构建日志，这些日志被完整地塞进了短期上下文。日志里的告警、过时信息和旧版命令干扰了模型对指令的注意力，它在后续任务里学到的不是"按规范写代码"，而是"模仿日志里的混乱状态"。

我们的修复方式是执行层全面改造：构建日志写文件、不上送，只把结构化摘要（成功/失败、错误code、关键输出行）追加到上下文；Agent的历史消息在上下文超过预算时按"结论优先"的策略压缩，而不是简单丢弃。从那以后，"指令失聪"就很少出现了。这也再次验证了：给 Agent 的信息不是越多越好，上下文也需要设计。

5.4 幻觉工具调用：参数里的"胡言乱语"

第四个高频问题是幻觉参数。某Agent调用read_module时传入了一个不存在的路径，导致任务失败；最典型的时候，Agent会强行引用一个根本不存在的接口 schema 版本号。它不是故意出错，而是模型在不确定时倾向于"编一个合理答案"。

排查时我们看了 Executor 日志，发现多数幻觉都发生在任务接近完成、上下文已经很长、置信度开始下滑的阶段。这类问题靠提示词很难根治，我们用了三层防护：

• 工具层做严格参数校验：路径不存在时立刻返回结构化错误，并在错误信息里列出当前目录下最相似的路径候选项；
• Executor 对确定的枚举参数（如 schema 版本号）强制从注册表读取，不信任Agent传入值；
• 工具调用前增加一次"意图确认"：如果 Agent 要调用的工具涉及删除、覆盖或提交操作，而指令里没有明确授权，直接拒绝。

这三层下来，因为幻觉参数导致的任务失败率降了大约一半，剩下的一半基本能从错误反馈里自愈。这也让我确信，多智能体系统的稳定性，很大程度上是靠"不给模型犯错机会"的边缘约束堆出来的。

6. 跑了两个季度之后的效果评估与下一步

6.1 用数据说话：重构前后的指标变化

两个季度跑下来，我们做了一次对照评估。这里不追求严谨的统计显著性，放几个差异明显的指标：

交付速度的提升主要来自两个地方：一是等待时间被削掉了不少，Agent不需要等另一个Agent"有空"再来处理；二是评审Agent随叫随到，不像人肉评审那样要排队。但必须诚实地说，需求理解环节并没有显著改善，如果原始需求写得含糊，Agent产出的方向照样会偏，只不过程序化之后偏得更一致、也更容易被人工发现。

架构设计的质量受制于初始蓝图。如果架构Agent在第一步就把模块边界划错了，后面开发Agent的执行再完美，整体架构也救不回来。所以每次新需求进来，我们仍然会安排一名工程师在需求拆解阶段做一次深度介入——这一步目前还离不开人。

6.2 人机协同的黄金位置在哪

用了这么久，我逐渐找到了这套系统里"人最不可替代"的位置。

需求澄清和验收标准定义，必须人来把关。Agent擅长把描述变成文字和代码，但它不能替业务方回答"到底想要什么"；所以需求进入系统之前，我们坚持由产品负责人和工程师一起写清楚用户故事。

风险性决策必须人来拍板。涉及线上数据迁移、对外接口变更、第三方依赖升级、安全合规判断，我们从来不让Agent自动推进。它可以产出分析报告和风险评估，但最终签字永远是人。

除此之外的绝大多数执行型工作——按规范写代码、补单测、更新文档、初步代码审查、跑测试、整理变更日志——现在已经完全交给 Agent 流水线处理。工程师的日常工作从"写代码"逐步变成了"写好的任务描述 + 审Agent的产出 + 处理上报的异常"。这个转变初期不太适应，但两个季度之后，团队普遍认可这种状态：那些重复劳动不再消磨精力，剩下的时间确实用在了判断和决策上。

6.3 下一步：给Agent建立自己的CI

最后一个想说的是后续方向。多智能体系统本身也是一套"软件系统"，如果它的行为无人约束，也会像代码一样悄然腐化。所以我们下一步的重点不是堆更多Agent，而是给Agent行为建立回归测试机制：沉淀一套高质量需求作为评估集，每次修改角色定义或提示词时，先用这套评估集跑一遍，看完成率、返工次数、指令遵循度有没有退化。相当于给智能体系统装上CI，让行为变更变得可回归、可比较。

另一个方向是让Agent具备从线上监控到自动修复的闭环能力。目前系统在生产环境发现异常后，还只能输出告警和可能原因，修复仍然靠人工。如果能把监控指标、链路追踪和日志检索也封装成Agent的领域工具，在低风险场景下让运维Agent独立执行回滚或配置修正，闭环就算真正打通了。

回看这一年，从最初想让Agent"全自动把活干完"，到后来接受"人机协同、流程重构"的定位，最大的改变其实是我对Agent系统的预期管理。多智能体协作不是让系统替团队思考，而是让团队知道如何把思考转化为约束和流程，再交给一批各司其职的执行者去运转。这个思路，应该会比具体某个模型版本更长久。