企业官网建设流程全解析

1. 从单点工具到智能体协作：这个项目到底在解决什么问题

第一次看到“Agency Agents”这个命名，我的直觉是：这又是一个把多个AI能力串起来的编排层。但翻完它的设计文档和几个核心模块的实现之后，我发现它想做的事情比“编排”要重得多——它在尝试定义一套跨平台的智能体协作协议，让不同能力、不同运行环境的AI编程智能体能够像一支真正的开发团队那样分工、协商、交付。

说白了，过去我们用一个AI写代码，本质上是在用一个“超级个体”。你给它一个需求，它给你一段实现，中间的所有决策——架构怎么定、模块怎么拆、测试怎么写、边界怎么处理——全部压在一次对话里完成。这种方式在小型脚本或单一函数级别上表现不错，但一旦项目规模上去，问题就暴露了：上下文窗口不够用、职责边界模糊、错误无法回溯、多个智能体之间互相覆盖代码。

Agency Agents的核心思路是把“一个全能AI”拆成“一组有明确职责的智能体”，每个智能体有自己的系统提示、工具集、记忆空间和输出规范，然后通过一套调度层把它们组织起来。这套东西适合谁？我认为三类人最值得关注：一是正在做AI辅助开发工具链的工程师，二是需要把AI编程能力集成到现有CI/CD流程里的团队，三是对多智能体协作机制本身感兴趣的研究者。

这篇文章我会从架构设计、核心模块、实操部署、问题排查四个维度展开，把我在实际搭建和调试过程中踩过的坑、验证过的参数、以及一些文档里不会写的经验全部摊开来讲。你不需要有很深的AI背景，但最好对基本的编程工作流和命令行操作有概念。

2. 架构拆解：为什么是“跨平台”而不是“多模型”

2.1 跨平台的真实含义：运行环境解耦

很多人看到“跨平台”第一反应是“支持多个大模型API”。这个理解不算错，但不够准确。Agency Agents的跨平台指的是运行环境的解耦——同一个智能体定义，可以在本地终端、容器环境、远程开发机、甚至浏览器沙箱里运行，而它的行为逻辑保持一致。

这个设计决策背后有一个很实际的考量：AI编程智能体的执行往往需要访问文件系统、执行命令、读写Git仓库。如果你把智能体的定义和它的执行环境绑死，那换一个环境就要重写一遍。Agency Agents的做法是把智能体的“大脑”（决策逻辑）和“手脚”（工具执行）分离，中间通过一层抽象接口通信。

具体来说，每个智能体定义包含以下几个部分：

• 角色描述：这个智能体是谁，负责什么，不负责什么
• 工具清单：它能调用哪些工具（文件读写、命令执行、网络请求等）
• 记忆策略：它的上下文如何管理，哪些信息持久化，哪些用完即弃
• 输出契约：它的输出格式是什么，如何与其他智能体的输出对接
• 调度权重：在什么条件下它会被激活，优先级如何

这五个部分全部用声明式配置描述，不依赖具体的运行时。换句话说，你可以把同一个智能体定义丢给本地的一个Python进程执行，也可以丢给一个远程的容器化运行时执行，只要那个运行时实现了对应的工具接口。

注意：跨平台不等于跨模型。虽然Agency Agents在设计上允许你替换底层模型，但它的核心抽象层并不处理模型差异。模型切换带来的提示词适配、输出格式差异、工具调用协议差异，需要你在智能体定义层面自己处理。

2.2 智能体协作的三种模式

Agency Agents支持三种协作模式，理解这三种模式是理解整个架构的关键。

第一种是流水线模式。智能体按预定义的顺序依次执行，前一个的输出是后一个的输入。这种模式最简单，适合需求明确、步骤固定的场景，比如“需求分析→接口设计→代码生成→测试用例生成”这条链。它的优点是可控性强，每一步的输入输出都可以审计；缺点是缺乏反馈循环，如果第三步发现第二步的设计有问题，没法自动回退。

第二种是协商模式。多个智能体可以互相发送消息，就某个决策达成一致。比如一个“架构师”智能体提出方案，一个“评审员”智能体提出异议，两者来回讨论若干轮后输出最终方案。这种模式适合需要多角度审视的复杂决策，但它的开销明显更大，而且需要设计好终止条件，否则可能陷入无限循环。

第三种是竞标模式。针对同一个任务，多个智能体各自给出方案，然后由一个“裁判”智能体或一套评分规则选出最优解。这种模式在代码生成场景下特别有用——你可以让三个不同风格的智能体分别实现同一个函数，然后选可读性最好、测试通过率最高的那个。

我在实际使用中的体会是：流水线模式适合80%的常规任务，协商模式适合架构设计阶段，竞标模式适合关键模块的实现。不要一上来就全部用协商模式，那个开销和不确定性会让你怀疑人生。

2.3 调度层的设计取舍

调度层是整个系统的心脏。Agency Agents的调度层做了几个我认为很关键的设计决策。

第一个决策是基于事件而非基于轮询。智能体之间的消息传递通过一个事件总线完成，而不是每个智能体不断轮询是否有新任务。这个设计在智能体数量少的时候看不出优势，但当你有十几个智能体同时运行时，轮询带来的资源浪费和延迟会非常明显。

第二个决策是状态外置。每个智能体的运行状态不保存在智能体内部，而是保存在一个外部的状态存储中。这样做的好处是智能体可以随时被销毁和重建，不会丢失进度。坏处是每次状态读写都有额外的开销，而且状态存储本身可能成为瓶颈。

第三个决策是工具调用的沙箱化。智能体执行命令、读写文件这些操作，全部在一个受限的沙箱环境中进行。沙箱的权限由调度层统一管理，智能体本身不能提权。这个设计在安全上是必要的，但也带来了一些限制——比如某些需要系统级权限的操作就没法直接执行。

3. 核心模块实操：从零搭建一个可运行的智能体团队

3.1 环境准备与依赖安装

在开始之前，你需要确认几个基础条件。首先是运行环境，我建议用Linux或macOS，Windows下虽然也能跑，但某些工具调用的行为会有差异。其次是Python版本，Agency Agents的核心运行时依赖Python 3.10以上，因为用到了不少3.10才引入的类型语法。

依赖安装本身不复杂，但有几个坑我提前说一下：

# 创建虚拟环境 python3.10 -m venv agency-env source agency-env/bin/activate # 安装核心包 pip install agency-agents-core # 安装工具集扩展 pip install agency-tools-fs agency-tools-shell agency-tools-git

第一个坑是工具集扩展的版本兼容性。agency-tools-shell这个包在不同版本间对命令执行超时的默认值改过好几次，如果你不锁定版本，可能会遇到命令执行到一半被强制终止的情况。我的建议是在requirements.txt里把版本号写死。

第二个坑是虚拟环境的路径问题。Agency Agents在启动时会尝试解析工具的可执行文件路径，如果你用的是conda环境或者某些特殊的venv配置，它可能找不到正确的路径。解决办法是在配置文件里显式指定工具路径。

第三个坑是权限配置。默认情况下，shell工具集只允许执行白名单内的命令。这个白名单在~/.agency/config/tools.yaml里配置。如果你需要执行自定义脚本，记得把这个脚本的路径加进去，否则智能体会一直报“命令不被允许”的错误。

3.2 定义第一个智能体：代码生成器

智能体定义文件是一个YAML格式的配置文件。我以一个“代码生成器”智能体为例，把每个字段的含义和配置要点讲清楚。

agent: name: code-generator role: "根据接口定义生成实现代码" model: "gpt-4-turbo" temperature: 0.2 max_tokens: 4096 tools: - fs.read - fs.write - shell.exec - git.diff memory: strategy: "sliding-window" window_size: 10 persist: true output: format: "unified-diff" target: "src/" constraints: - "不修改测试文件" - "不引入新的第三方依赖" - "生成的代码必须通过语法检查"

这里有几个参数值得展开说。temperature设为0.2是因为代码生成场景下我们需要的是确定性而非创造性，太高的温度会导致同一个输入产生差异很大的输出。max_tokens设为4096是一个折中值，太小了生成不完整，太大了会浪费上下文窗口。memory策略用sliding-window是因为代码生成任务通常不需要太长的历史记忆，保留最近10轮对话就够了。

输出格式我选了unified-diff，这意味着智能体不会直接覆盖文件，而是生成一个diff补丁。这样做的好处是你可以先审查再应用，避免智能体误改代码。如果你信任度比较高，也可以改成direct-write，但我不建议在初期这么做。

约束条件这部分是很多人会忽略的。不修改测试文件这条约束非常重要，因为有些智能体为了“让测试通过”会去改测试用例，这本质上是在作弊。不引入新的第三方依赖是为了避免依赖膨胀。生成的代码必须通过语法检查是一个硬性门槛，不满足这个条件的输出会被调度层直接丢弃。

3.3 定义第二个智能体：代码评审员

有了代码生成器，接下来需要一个评审员。评审员的配置和生成器有几个关键差异。

agent: name: code-reviewer role: "审查代码实现，检查逻辑正确性和边界处理" model: "gpt-4-turbo" temperature: 0.1 max_tokens: 2048 tools: - fs.read - git.diff - shell.exec memory: strategy: "full-history" persist: true output: format: "structured-review" schema: - field: "severity" values: ["blocker", "major", "minor", "suggestion"] - field: "location" type: "file:line" - field: "description" type: "string" - field: "suggestion" type: "string" constraints: - "不直接修改代码" - "每个问题必须给出具体位置" - "blocker级别问题必须给出修复建议"

评审员的temperature设得更低（0.1），因为评审需要的是严谨而非发散。memory策略改成了full-history，因为评审员需要看到完整的变更上下文才能做出准确判断。输出格式用了结构化schema，这样调度层可以自动解析评审结果，根据severity决定是否阻断流水线。

提示：评审员的输出schema里，severity的四个级别是有明确含义的。blocker表示必须修复否则不能合并，major表示应该修复但不阻断，minor表示可以后续处理，suggestion表示纯建议。你在配置调度规则时，可以设定“存在blocker时自动回退到生成器重新生成”。

3.4 编排流水线：把智能体串起来

单个智能体定义好之后，下一步是编排。Agency Agents的编排配置也是一个YAML文件，我把它叫做“团队定义”。

team: name: "feature-development" mode: "pipeline" stages: - name: "generate" agent: "code-generator" input: "${task.requirement}" output: "${stage.generate.result}" - name: "review" agent: "code-reviewer" input: "${stage.generate.result}" output: "${stage.review.result}" on_blocker: "retry:generate" max_retries: 3 - name: "apply" agent: "code-applier" input: "${stage.review.result}" condition: "no_blocker"

这个编排定义里，on_blocker: "retry:generate"是一个关键配置。它的意思是：如果评审阶段发现了blocker级别的问题，自动回退到生成阶段重新生成，最多重试3次。这个机制在实际使用中非常有用，它把“生成→评审→修复”这个循环自动化了。

但这里有一个坑：重试次数不要设太大。我一开始设了10次，结果遇到一个智能体反复生成同样有问题的代码，10次重试全部失败，浪费了大量token和时间。3次是一个比较合理的值，超过3次还修不好，说明问题可能出在需求描述本身，需要人工介入。

另一个坑是阶段之间的数据传递。${stage.generate.result}这种引用语法看起来简单，但实际运行时如果生成阶段的输出格式不符合预期，评审阶段会直接报解析错误。我的建议是在每个阶段后面加一个“格式校验”步骤，确保输出符合下一个阶段的输入要求。

4. 实操过程中的典型问题与排查思路

4.1 智能体“卡死”不动了怎么办

这是最常见的问题。智能体启动后没有任何输出，日志里也看不到明显错误。可能的原因有几种：

第一种可能是工具调用超时。智能体在执行某个shell命令时卡住了，而超时时间设得太长（或者没设）。排查方法是查看调度层的日志，找到最后一条工具调用记录。解决办法是在工具配置里设置合理的超时时间，我一般设30秒。

第二种可能是上下文窗口溢出。智能体的记忆策略配置不当，导致上下文不断增长直到超过模型限制。排查方法是查看当前上下文的token数量。解决办法是调整memory策略，或者设置上下文压缩规则。

第三种可能是模型API限流。如果你用的是按量付费的API，并发请求过多时会被限流。排查方法是查看API返回的状态码。解决办法是降低并发数，或者在调度层加一个请求队列。

4.2 生成代码质量不稳定的排查

同一个需求，有时候生成得很好，有时候一塌糊涂。这个问题困扰了我很久，后来发现根源在几个地方。

提示词模板的稳定性。如果你的智能体定义里用了动态生成的提示词，确保每次生成的提示词结构一致。我见过一个案例，提示词里有一段“参考以下示例”，但示例内容是从一个集合里随机选的，导致每次生成的代码风格都不一样。

温度参数的设置。前面说了代码生成建议用低温度，但如果你用的是某些对温度特别敏感的模型，0.2可能还是太高。可以试试0.1甚至0。

输入需求的清晰度。这个听起来像废话，但确实是最常见的原因。如果需求描述本身有歧义，智能体就会在不同轮次给出不同理解。解决办法是在需求进入流水线之前，先经过一个“需求澄清”智能体，把模糊的地方明确化。

4.3 多智能体之间的“冲突”

当多个智能体同时操作同一批文件时，冲突几乎不可避免。Agency Agents提供了一套冲突检测机制，但它的默认行为是“后写覆盖先写”，这在某些场景下会导致数据丢失。

我的做法是在调度层加一个文件锁机制。具体来说，当一个智能体要写入某个文件时，先申请锁；如果锁被占用，就等待或者排队。这个机制在Agency Agents里没有内置，需要你自己在工具层实现。

另一个做法是分区管理。把不同的文件目录分配给不同的智能体，从源头上避免冲突。比如代码生成器只能写src/目录，测试生成器只能写tests/目录。这个做法更简单，但灵活性差一些。

4.4 常见问题速查表

5. 性能调优与扩展思路

5.1 减少不必要的模型调用

Agency Agents的默认行为是每个阶段都调用一次模型。但在实际使用中，有些阶段其实不需要模型参与。比如“格式校验”阶段，完全可以用一个正则表达式或者JSON Schema校验器来完成，没必要浪费一次模型调用。

我的做法是在编排配置里加一个type字段，区分“模型阶段”和“脚本阶段”。脚本阶段直接执行预定义的脚本，不经过模型。这个改动看起来小，但在流水线较长的时候能省下可观的成本。

另一个优化点是缓存。如果同一个需求被多次提交，或者某个阶段的输入没有变化，可以直接复用上一次的输出。Agency Agents支持在阶段级别配置缓存策略，我一般对“需求分析”和“接口设计”这两个阶段开启缓存，因为这两个阶段的输出在需求不变的情况下是确定的。

5.2 扩展新的智能体类型

Agency Agents的智能体类型是可扩展的。你可以定义自己的智能体，只要它满足几个基本条件：有明确的角色描述、有工具清单、有输出契约。

我扩展过一个“文档生成器”智能体，它的职责是根据代码变更自动生成CHANGELOG。这个智能体的配置和代码生成器类似，但工具集只需要fs.read和fs.write，输出格式是Markdown。它被编排在“apply”阶段之后，作为一个后置步骤运行。

扩展智能体时需要注意一点：新智能体的输出格式必须与现有流水线兼容。如果你的文档生成器输出的是纯文本，而下游有一个“格式校验”阶段期望的是JSON，那就会报错。解决办法是在智能体定义里明确声明输出格式，并在编排层做兼容性检查。

5.3 监控与日志

Agency Agents自带了一套日志系统，但默认的日志级别是INFO，很多调试信息看不到。我建议在开发阶段把日志级别调到DEBUG，上线后再调回INFO。

日志里最有价值的信息是每个阶段的耗时和token消耗。通过分析这些数据，你可以找到流水线的瓶颈。比如我发现“评审”阶段的耗时通常是“生成”阶段的1.5倍，因为评审需要读取更多上下文。针对这个瓶颈，我调整了评审员的memory策略，从full-history改成了sliding-window，耗时降了大约30%。

另一个有用的监控指标是重试率。如果某个阶段的重试率超过20%，说明这个阶段的输入或配置有问题。我的经验是，重试率超过10%就需要关注，超过30%就必须停下来排查。

6. 一些踩过坑之后的个人体会

这套东西我从去年开始折腾，中间经历了好几次“推倒重来”。最大的教训是：不要试图一次性把所有智能体都定义完美。我一开始花了大量时间设计一个“全能架构师”智能体，结果发现它在实际任务中的表现还不如一个简单的“需求拆解器”。后来我改变了策略，先定义最小可用的智能体集合（生成器+评审员），跑通流水线之后再逐步增加新的角色。

另一个体会是：约束条件比角色描述更重要。角色描述告诉智能体“你是谁”，约束条件告诉智能体“你不能做什么”。在实际运行中，约束条件对输出质量的影响更大。我现在的习惯是，每定义一个智能体，至少写三条约束条件，而且这些约束条件必须是可验证的——比如“不修改测试文件”可以通过检查文件路径来验证，“生成的代码必须通过语法检查”可以通过运行语法检查器来验证。

还有一个很实用的技巧：给智能体起一个具体的名字。不要叫“agent-1”“agent-2”，而是叫“code-generator”“code-reviewer”“test-writer”。这个名字会出现在日志里、消息传递里、状态存储里。一个有意义的名字能让你在排查问题时快速定位到是哪个环节出了状况。

最后说一个关于成本控制的经验。Agency Agents的流水线模式在智能体数量增加时，token消耗是线性增长的。如果你的预算有限，可以考虑在非关键阶段使用更便宜的模型。比如“格式校验”阶段可以用一个小模型，“代码生成”阶段再用大模型。Agency Agents支持在智能体级别指定模型，这个灵活性还是挺好的。

这套架构目前还在快速迭代中，我上面提到的配置和参数可能会随着版本更新而变化。但核心的设计思路——职责分离、声明式配置、事件驱动调度、沙箱化执行——我认为是稳定的，也是这套方案最有价值的部分。如果你正在做类似的事情，希望这些经验能帮你少走一些弯路。