企业官网建设流程全解析

1. 从单体脚本到智能体生态：这个项目到底在解决什么问题

第一次看到“Agency Agents”这个命名的时候，我脑子里冒出来的第一个念头是：又是一个把几个API调用包装一下、套个“智能体”壳子的玩具项目。但真正把它的架构文档和源码翻了一遍之后，我意识到这个判断下得太草率了。它要解决的核心问题，其实是当下AI编程工具最尴尬的一个断层——单个智能体再强，也只能干一件事；而真实的软件开发，从来都是一堆角色协作的结果。

你可以回忆一下自己用AI写代码的日常：让一个模型帮你写个函数，它写得挺好；让它帮你review代码，它也能挑出毛病；让它写测试用例，它也能凑合。但如果你想让这三件事在同一个项目里自动流转起来——写完代码自动触发review，review发现问题自动回退修改，改完再自动补测试——绝大多数工具就歇菜了。你要么手动在几个窗口之间来回粘贴，要么自己写一堆胶水脚本把API串起来，最后维护成本比手写代码还高。

Agency Agents瞄准的就是这个断层。它做的事情，用一句话概括：把不同职能的AI智能体（产品经理、架构师、前端、后端、测试、运维等）组织成一个有明确分工、有协作协议、有状态流转的“虚拟团队”，并且让这个团队能在不同的底层模型和运行平台之间自由迁移。这里的“跨平台”不是指Windows和Mac那种操作系统层面的跨平台，而是指跨模型平台——今天用这个厂商的模型，明天换成另一个厂商的，甚至本地跑一个开源模型，整个智能体团队的协作逻辑不用重写。

这个定位决定了它的目标用户不是“想让AI帮我写个爬虫”的轻度用户，而是已经在用AI辅助开发、但被碎片化工具折磨得够呛的中高级开发者，以及需要把AI编程能力集成到自己产品里的工程团队。如果你只是偶尔让AI帮你补全几行代码，这个项目对你来说太重了；但如果你正在搭建一套自动化的研发流水线，或者想让多个AI角色在一个项目里协同工作，那它值得你花时间研究。

我之所以对这个方向感兴趣，是因为过去大半年里，我陆续试过七八种“多智能体协作”的方案，大多数都死在两个坑里：一是角色定义太虚，所谓“产品经理智能体”和“开发智能体”的prompt区别只是换了个称呼，实际干的事情一模一样；二是状态管理太乱，几个智能体互相调用几轮之后，上下文爆炸，谁也记不清当前任务进行到哪一步了。Agency Agents在这两个问题上给出的解法，是我目前见过比较成体系的，这也是我决定写这篇拆解的原因。

2. 架构拆解：一个智能体团队是怎么被组织起来的

2.1 核心设计思路：角色即配置，协作即协议

Agency Agents最核心的设计决策，是把“智能体”这个概念从“一个prompt加一个模型”升级成了“一个带有明确职责边界、输入输出契约和工具权限的配置单元”。这个转变听起来简单，但它带来的连锁反应很大。

传统的多智能体方案里，你定义一个智能体大概是这样：给它一段系统提示词，告诉它“你是一个资深前端工程师”，然后把它接上模型。问题在于，这段提示词是自然语言，模型对它的理解每次都可能不一样，而且当多个智能体互相调用时，谁该在什么时候把什么信息传给谁，完全没有约束。

Agency Agents的做法是给每个智能体定义了一套结构化的配置，我把它拆成四个维度来看：

• 角色定义（Role）：这个智能体是谁，它的专业领域是什么，它不负责什么。注意最后一点很关键——明确“不负责什么”比“负责什么”更能约束模型的行为边界。
• 能力清单（Capabilities）：这个智能体可以调用哪些工具、访问哪些资源、执行哪些操作。比如代码审查智能体可以读取代码但不能修改，开发智能体可以修改代码但不能直接部署。
• 输入输出契约（IO Contract）：这个智能体接收什么格式的输入，产出什么格式的输出。这一层是保证协作不混乱的关键，后面会展开讲。
• 协作关系（Relations）：这个智能体在什么条件下会被触发，它的产出会流向哪个下游智能体，遇到什么情况需要回退到上游。

我实测下来，这套配置方式最大的好处是可调试性。当协作流程出问题时，你可以精确定位到是哪个环节的契约没对齐，而不是面对一堆自然语言prompt干瞪眼。

2.2 跨平台抽象层：为什么换模型不用重写逻辑

“跨平台”这个词在这个项目里有两层含义，我分开说。

第一层是跨模型提供商。Agency Agents在模型调用层做了一个抽象，把不同厂商的API差异（请求格式、参数命名、返回结构、流式输出方式）统一成一套内部接口。这意味着你在配置里写的是“使用推理能力较强的模型处理架构设计任务”，而不是写死某个具体的模型名称。底层具体路由到哪个模型，由运行时的适配器决定。

这个设计的好处在实际操作中非常明显。我做过一个测试：同一个智能体团队配置，上午跑在一个云端模型上，下午切换到本地部署的开源模型上，整个协作流程的代码一行没改，只是换了个适配器配置。当然，输出质量会有差异，但流程本身是通的，这已经省掉了大量的迁移成本。

第二层是跨运行环境。智能体团队可以跑在本地开发机上，也可以跑在容器里，还可以作为服务部署到服务器上。这一层靠的是把智能体的执行引擎和具体的运行环境解耦——执行引擎只负责调度和状态管理，具体的工具调用（读写文件、执行命令、调用API）通过一层适配接口来对接不同环境。

注意：跨平台抽象层虽然好用，但它不是免费的。抽象层本身会增加调试的复杂度，当出现问题时，你需要判断是模型的问题、适配器的问题还是协作逻辑的问题。我的经验是，在项目初期先把适配器层的日志级别调高，把每次模型调用的原始请求和响应都记录下来，排查效率会高很多。

2.3 状态流转机制：让多个智能体不打架的关键

多智能体协作最容易崩的地方就是状态管理。我见过太多方案，几个智能体互相调用几轮之后，要么上下文无限膨胀把token吃光，要么后一个智能体完全不知道前一个干了什么，开始重复劳动甚至互相覆盖对方的修改。

Agency Agents在这块的设计思路是把协作状态和对话历史分开管理。对话历史是每个智能体自己的上下文，而协作状态是一个全局的、结构化的数据对象，记录着当前任务进行到哪个阶段、每个阶段的产出是什么、有哪些待解决的问题。

这个全局状态对象大概长这样（我用伪代码表示）：

{ "task_id": "xxx", "current_phase": "code_review", "artifacts": { "design_doc": "...", "source_code": "...", "review_comments": ["...", "..."] }, "pending_issues": [ {"id": 1, "severity": "high", "description": "..."} ], "history": [ {"agent": "architect", "action": "produce_design", "timestamp": "..."}, {"agent": "developer", "action": "implement", "timestamp": "..."} ] }

每个智能体在执行时，拿到的是这个全局状态的一个视图——它只能看到自己需要的那部分信息，而不是全部。比如代码审查智能体拿到的是源代码和设计文档，但不需要看到架构师和产品经理之间的讨论细节。这个“视图隔离”的设计，既控制了上下文长度，也避免了智能体被无关信息干扰。

状态流转的触发条件也是配置化的。比如“当开发智能体完成代码提交后，自动触发代码审查智能体”，或者“当审查智能体发现高危问题时，自动回退到开发智能体并附带问题清单”。这些规则写在协作配置里，由执行引擎来驱动。

2.4 工具权限与安全边界

还有一个容易被忽视但非常重要的设计：工具权限的细粒度控制。在Agency Agents里，每个智能体能调用的工具是明确列出的，而且可以设置调用条件。

举个例子，开发智能体可以调用“写入文件”工具，但只能写入项目目录下的特定路径；部署智能体可以调用“执行部署命令”工具，但必须在前置检查全部通过之后才能触发。这种权限控制不是靠prompt里写一句“你不要乱改文件”来实现的，而是在执行引擎层面硬性拦截。

我踩过的一个坑是：早期测试时为了图方便，给所有智能体开了全量工具权限，结果一个负责写文档的智能体在“优化文档结构”的时候，顺手把项目里的配置文件给改了。虽然不是什么大事故，但足以说明权限控制不能靠自觉。

3. 工程实践：从零搭建一个智能体协作流程

3.1 环境准备与基础配置

先说环境。Agency Agents本身是一个Node.js项目，我用的版本是Node 20 LTS，包管理器用的是pnpm（npm也可以，但pnpm在依赖较多的项目里安装速度明显更快）。如果你打算用本地模型，还需要提前把模型服务跑起来，确保API端点可访问。

基础配置分三块：模型适配器配置、智能体定义、协作流程定义。我建议新手先从官方提供的示例配置改起，不要一上来就从零写。

模型适配器配置大概长这样：

adapters: - name: cloud-reasoning type: openai-compatible endpoint: https://api.example.com/v1 model: reasoning-model-v1 api_key_env: REASONING_API_KEY - name: local-fast type: openai-compatible endpoint: http://localhost:8080/v1 model: local-model-7b api_key_env: LOCAL_API_KEY

这里的关键是type字段统一用openai-compatible，因为现在绝大多数模型服务都兼容这个接口格式。如果你的模型服务不兼容，就需要自己写一个适配器，但这种情况越来越少了。

提示：API密钥不要直接写在配置文件里，用环境变量引用。我见过有人把密钥提交到代码仓库的，后果不用我多说。

3.2 定义一个最小可用的智能体团队

我建议从三个智能体开始：规划者、执行者、审查者。这个最小组合能覆盖大多数开发场景的核心流程，而且足够简单，方便你理解协作机制。

规划者智能体的配置重点在于它的输出契约。它需要产出一个结构化的任务分解，而不是一段自然语言的描述。我通常要求它输出JSON格式，包含任务列表、每个任务的预期产出、依赖关系。这样下游的执行者才能可靠地解析。

执行者智能体的配置重点在于工具权限。它需要文件读写权限，但写入范围要限制在项目工作目录内。另外，我建议给它配置一个“请求澄清”的工具——当它遇到规划者描述不清楚的地方时，可以主动发起澄清请求，而不是自己瞎猜。

审查者智能体的配置重点在于它的评判标准。我一般会要求它从三个维度审查：功能正确性、代码规范、潜在风险。每个维度给出具体的检查项，而不是笼统地说“帮我看看有没有问题”。

这三个智能体的协作流程是：规划者产出任务分解 → 执行者按任务逐个实现 → 审查者检查产出 → 如果有问题，回退给执行者修改 → 全部通过后结束。

3.3 协作流程的配置与调试

协作流程的配置是整个项目里最需要耐心的部分。我把它比作给一个真实团队制定工作流程——你得想清楚每个环节的输入输出、异常处理、回退条件。

一个典型的协作流程配置包含以下要素：

我实测下来，最大迭代次数这个配置一定要设。我遇到过审查者和执行者互相“扯皮”的情况——审查者提了一个模糊的意见，执行者改了一版但没改到点子上，审查者又提了类似的意见，来回好几轮。设置一个合理的上限（比如5轮），超过就人工介入，能省很多token和时间。

调试的时候，我强烈建议开启详细日志，把每个阶段的输入输出都记录下来。Agency Agents的日志系统支持按阶段过滤，你可以只看某个智能体的所有交互记录。这个功能在排查“为什么审查者没发现问题”或者“为什么执行者理解错了任务”这类问题时特别有用。

3.4 一个完整的实操案例：自动化代码审查流程

我拿一个实际场景来演示：给一个已有的代码仓库加上自动化审查流程。

第一步，定义审查智能体。我给它配置了三个工具：读取文件、列出目录、写入审查报告。注意它没有修改代码的权限，这是故意的——审查和修改分离，避免“自己审自己改”导致问题被掩盖。

第二步，定义审查标准。我把审查标准写成一个结构化的清单，包含代码风格、潜在bug、性能问题、安全隐患四个大类，每个大类下面有具体的检查项。这个清单会作为审查智能体的输入之一。

第三步，配置触发条件。我设置的是当代码仓库有新的提交时触发审查流程。在实际操作中，可以通过文件监听或者版本控制钩子来实现。

第四步，运行并观察。第一次跑的时候，审查智能体输出了27条意见，其中大概有8条是误报（比如把正常的异步操作标记为“可能的竞态条件”）。我调整了审查标准里的描述，把“异步操作”相关的检查项改得更精确，第二次跑误报降到了3条。

第五步，接入回退机制。当审查发现高危问题时，自动触发一个“修复建议”流程，由另一个智能体生成修复方案，但不自动应用，而是输出为建议供人工确认。这个设计是刻意的——自动修复的风险太高，尤其是在生产代码上。

这个流程跑通之后，我把它用在了几个内部项目上，平均每次提交能提前发现2-3个真实问题，误报率控制在可接受范围内。当然，它不能替代人工审查，但能帮人工审查省掉大量机械性的检查工作。

4. 常见问题与排查技巧实录

4.1 智能体“不听话”怎么办

这是最高频的问题。你明明在配置里写了“不要修改配置文件”，它还是改了；你要求它输出JSON，它给你输出一段散文。我总结下来，原因通常有三个：

第一，约束写得太抽象。“不要修改配置文件”不如“你只能写入src/目录下的文件，其他路径的写入操作会被拒绝”来得有效。前者是意图，后者是规则。模型对规则的遵守度远高于对意图的猜测。

第二，约束没有在执行层落地。如果只在prompt里写约束，模型有概率忽略。正确的做法是在工具权限层面硬性拦截——它根本没有修改配置文件的工具权限，想改也改不了。

第三，模型能力不够。有些小模型对复杂约束的遵守能力确实有限。这种情况下，要么换模型，要么把约束拆得更细、更简单。

4.2 协作流程卡死或死循环

死循环的典型表现是两个智能体来回传递同一个问题，谁也解决不了。排查思路是：

1. 先看日志，确认是哪个环节开始出现重复。
2. 检查回退策略，看是不是回退得太远导致前面的工作被反复重做。
3. 检查审查标准，看是不是标准太模糊导致执行者无法判断“改到什么程度算通过”。
4. 设置最大迭代次数作为兜底。

我遇到过一次比较隐蔽的死循环：审查者要求“补充错误处理”，执行者加了一个try-catch，审查者认为“错误处理不够全面”，执行者又加了一层，审查者还是不满意。问题出在审查标准里“全面”这个词没有量化。后来我改成“每个外部调用必须有对应的错误处理分支，且错误信息必须包含调用参数”，问题就解决了。

4.3 上下文爆炸与token消耗失控

多智能体协作的token消耗是单智能体的好几倍，这是必然的。控制消耗的关键在于视图隔离——每个智能体只拿到自己需要的信息，而不是全量上下文。

我做过一个对比：不做视图隔离的情况下，一个中等复杂度的任务消耗了大约12万token；做了视图隔离之后，降到了4万左右。差距主要来自两个方面：一是智能体不再需要阅读无关的历史对话，二是全局状态对象只传递结构化数据，比自然语言描述紧凑得多。

另外，我建议给每个智能体的单次输入设置一个上限，超过就触发摘要或者分片处理。这个上限根据你用的模型来定，一般不要超过模型上下文窗口的60%，留出空间给输出。

4.4 跨平台切换后的兼容性问题

虽然抽象层解决大部分差异，但切换模型平台时还是可能遇到一些边角问题。我整理了一个速查表：

提示：切换平台后，先用一个小任务跑通全流程，确认没有兼容性问题再跑正式任务。我吃过亏，直接拿正式任务测试，结果跑到一半发现工具调用格式不兼容，浪费了大量token。

4.5 智能体之间的“理解偏差”

这个问题比较微妙。规划者说“实现用户登录功能”，执行者理解成“写一个登录页面”，审查者理解成“检查登录接口的安全性”。三方对同一个词的理解不一致，导致产出对不上。

解决思路是在协作流程中引入“术语表”。把项目中的关键概念、缩写、业务术语提前定义好，作为所有智能体的共享上下文。比如“登录功能”在术语表里明确定义为“包含前端页面、后端接口、数据库查询、会话管理的完整链路”。这样三方就有了统一的参照。

这个术语表不需要很大，但一定要在流程启动前就确定好。我通常会在规划阶段让规划者先输出一份术语表，人工确认后再进入执行阶段。

5. 工具选型与扩展思路

5.1 模型选择：没有最好的，只有最合适的

在Agency Agents的架构下，不同智能体可以用不同的模型。我的配置策略是：

• 规划者和审查者用推理能力较强的模型，因为它们需要理解复杂需求、做出判断。
• 执行者用代码生成能力强的模型，因为它的主要工作是写代码。
• 格式化、摘要类任务用速度快、成本低的模型。

这个策略的核心逻辑是把贵的算力用在需要判断力的环节，把便宜的算力用在机械性环节。我实测下来，整体成本能降低40%左右，而输出质量没有明显下降。

5.2 扩展方向：从代码开发到其他领域

Agency Agents的架构本身是领域无关的，智能体的角色定义和协作流程都可以替换。我试过把它用在技术文档写作上：规划者拆解文档大纲，执行者写初稿，审查者检查准确性和一致性。效果比单模型直接写好很多，尤其是在需要多轮修改的场景下。

另一个我比较看好的方向是数据分析流程。数据清洗、特征工程、建模、结果解读，这几个环节天然适合用不同智能体来分工。而且数据分析对“可复现性”要求很高，Agency Agents的状态管理机制正好能满足这个需求。

不过要提醒一点：扩展到新领域时，协作流程的设计比智能体的定义更重要。我见过有人把智能体定义写得很漂亮，但协作流程就是简单的“A做完给B，B做完给C”，结果遇到问题完全没有回退和迭代机制，整个流程非常脆弱。

5.3 性能优化的几个实操技巧

最后分享几个我在实际使用中总结的优化技巧：

第一，缓存重复调用。有些智能体的输出在多次运行中是稳定的（比如代码风格检查），可以把结果缓存起来，避免重复消耗token。

第二，并行化独立任务。如果两个任务之间没有依赖关系，让它们并行执行。Agency Agents的执行引擎支持并行调度，但需要你在协作流程配置里显式声明。

第三，定期清理历史状态。长流程运行久了，全局状态对象会越来越大。我一般会在每个阶段结束后，把已经确认无用的中间产物清理掉，只保留最终产出和关键决策记录。

第四，给智能体设置“超时”。有些模型在遇到复杂问题时响应特别慢，设置一个合理的超时时间，超时后触发降级策略（比如换一个更快的模型重试），能避免整个流程被一个环节拖死。

这些技巧都不是什么高深的东西，但组合起来用，能让整个系统的稳定性和效率提升一个档次。我在实际项目里踩过的坑、调过的参数、改过的配置，基本都在这了。如果你也在折腾多智能体协作，希望这些经验能帮你少走点弯路。