企业官网建设流程全解析

1. 从单兵作战到团队协同：Agency Agents 到底解决了什么问题

做过复杂项目的人都有一个共同感受：一个人写代码，效率其实不低，真正拖慢进度的是“协作”。需求在群里说一遍，产品理解成A，开发理解成B，测试理解成C，最后交付出去的东西跟最初想的完全不是一回事。更麻烦的是，当任务多起来之后，一个人要同时扮演产品经理、架构师、开发、测试、运维好几个角色，上下文频繁切换，脑子根本不够用。

Agency Agents 这套多智能体协作系统，核心要解决的就是这个问题。它把原本由一个人扛的多个角色，拆成一组各自有明确职责的智能体，让它们像一个小型开发团队一样分工协作。你可以把它理解成：给一个项目配了一个虚拟团队，里面有负责拆需求的、有负责写代码的、有负责审查的、有负责测试的，每个成员各司其职，通过一套约定好的协议互相传递信息、交接任务。

这套东西适合谁？如果你正在做以下这些事情，它值得你花时间研究：

• 手头项目模块多、角色杂，一个人维护上下文成本太高；
• 想让 AI 帮忙处理完整工作流，而不是只做单点问答；
• 团队里已经在用大模型辅助开发，但停留在“问一句答一句”的阶段，没有形成流水线；
• 对多智能体编排、任务分解、角色协作这类架构感兴趣，想自己搭一套。

需要先说明一点：Agency Agents 不是一个开箱即用的成品软件，它更像一套架构范式加一组可复用的协作模式。你要做的是理解它的设计思路，然后根据自己的场景去组装。这也是为什么很多人第一次接触会觉得“概念都懂，但不知道怎么落地”——因为落地靠的是你把角色、协议、工具链这三样东西拼起来。

下面我会从整体设计、核心细节、实操落地、问题排查四个层面，把我在实际搭建和调试过程中积累的东西完整拆开讲。内容会涉及具体的目录结构、角色定义方式、消息传递机制、任务编排逻辑，以及一堆踩过的坑。看完你应该能自己动手搭一个最小可用的多智能体协作系统。

2. 整体架构设计与角色拆解思路

2.1 为什么是“多智能体”而不是“一个大模型加长提示词”

很多人第一反应是：我写一个超长的系统提示词，把产品、开发、测试的要求全塞进去，让一个模型轮流扮演不就行了？我一开始也是这么想的，实测下来问题很明显。

第一，角色冲突。一个模型同时被要求“大胆设计架构”和“严格审查代码”，这两个目标在生成时是互相拉扯的。它要么设计得保守，要么审查得敷衍，很难同时做到位。第二，上下文污染。当对话轮次多了之后，前面产品阶段的需求描述会一直占着上下文，干扰后面代码阶段的判断。第三，无法并行。一个模型只能串行处理，而真实团队里设计和测试是可以并行的。

多智能体的本质，是把“角色约束”从提示词层面提升到架构层面。每个智能体有独立的系统提示、独立的上下文窗口、独立的工具权限。产品智能体只能读需求文档、写任务拆解，不能碰代码；开发智能体只能读任务、写代码，不能改需求。这种物理隔离带来的稳定性，是单模型加长提示词做不到的。

提示：不要一上来就追求智能体数量多。角色拆得太细，通信开销会指数级上升。一般从3到5个核心角色起步最稳。

2.2 核心角色划分与职责边界

一套能跑起来的多智能体开发系统，最少需要这几个角色。我按职责从上游到下游排：

这张表看起来简单，但每个角色的边界怎么划，直接决定系统能不能跑通。我踩过最大的坑就是“协调者”和“需求分析”职责重叠——协调者既拆任务又写需求，结果它拆出来的任务粒度忽大忽小，下游根本没法接。后来我把拆任务和写规格彻底分开，协调者只负责“把大目标切成有依赖关系的小块”，需求分析负责“把每个小块翻译成可执行的规格”，系统立刻稳定了。

2.3 通信拓扑：星型、链型还是网状

角色定好之后，下一个问题是它们怎么通信。常见的拓扑有三种：

• 星型：所有智能体都跟协调者通信，彼此不直接对话。优点是控制简单、日志清晰；缺点是协调者容易成为瓶颈，而且它要理解所有下游的细节。
• 链型：A交给B，B交给C，像流水线。优点是职责清晰、上下文传递自然；缺点是一旦中间某个环节卡住，整条链就停了，而且没法并行。
• 网状：智能体之间可以自由通信。优点是灵活；缺点是调试噩梦，消息满天飞，出了问题根本不知道是谁的锅。

我实际用的是“星型为主、链型为辅”的混合拓扑。协调者负责全局调度和异常处理，但相邻角色之间（比如开发和审查）允许直接通信，减少一次中转。这样既保留了星型的可控性，又避免了所有消息都挤在协调者那里。

具体实现上，我用一个共享的消息队列加一个路由表。每个智能体启动时注册自己的ID和能处理的消息类型，协调者发消息时按类型路由。消息格式统一成JSON，包含发送者、接收者、消息类型、负载、时间戳五个字段。这个设计后面排查问题时帮了大忙——任何一次协作都能通过时间戳还原出完整链路。

2.4 状态管理与上下文隔离

多智能体系统最容易出问题的地方是状态。每个智能体都有自己的上下文，但任务的整体状态是共享的。如果处理不好，会出现“开发以为需求改了，需求以为开发没收到”这种经典事故。

我的做法是引入一个中心化的任务状态表，每个任务有明确的状态机：待分派、进行中、待审查、已完成、阻塞。智能体只能通过状态转移接口来改变任务状态，不能直接改。每次状态变更都记录操作者和时间。这样任何时刻你都能查到“这个任务现在在谁手里、卡了多久”。

上下文隔离则是通过“按需注入”实现的。开发智能体在开始写代码时，只注入跟它这个任务相关的需求片段和接口定义，而不是把整个需求文档全塞进去。这既省token，又避免无关信息干扰判断。实测下来，按需注入比全量注入的代码正确率高出不少，因为模型不会被无关的约束带偏。

3. 核心细节解析与实操要点

3.1 角色提示词怎么写才不打架

角色提示词是整个系统的灵魂。写得好，智能体各司其职；写得差，它们会互相甩锅或者越权。我总结了一个四段式模板，每个角色的提示词都按这个结构来：

1. 身份声明：你是谁，你在团队里的位置。
2. 职责清单：你负责什么，明确列出。
3. 禁止事项：你不负责什么，越界了会怎样。
4. 输出格式：你交付的东西长什么样，字段有哪些。

举个例子，审查测试角色的提示词大致是这样组织的：

你是团队中的质量审查员，只对代码质量和功能正确性负责。 你的职责： - 对照需求文档检查代码是否覆盖所有功能点 - 检查边界条件和异常处理 - 输出问题清单，每个问题标注严重级别 你不负责： - 修改代码（发现问题只报告，不修复） - 重新设计架构（架构问题只标记，交回架构角色） 输出格式： { "issues": [{"severity": "high/medium/low", "location": "...", "description": "..."}], "summary": "..." }

关键在“你不负责”这一段。我一开始没写这段，结果审查智能体发现架构问题后直接动手改代码，改完又引入新bug，整个流程乱套。加上禁止事项之后，它只报告不修改，问题交回对应角色处理，流程就顺了。

注意：禁止事项要写得具体，不能只写“不要越权”。要明确到“不要修改代码文件”“不要重新定义接口”这种可判断的行为。

3.2 任务拆解的粒度控制

协调者拆任务的粒度，直接决定下游能不能接。太粗，开发不知道从哪下手；太细，任务数量爆炸，通信开销吃掉所有收益。

我的经验是：一个任务应该能在一次智能体调用内完成，且产出物是一个可独立验证的单元。比如“实现用户登录功能”就太粗，它包含接口定义、密码加密、会话管理、错误处理好几件事；“写一个密码哈希函数”又太细，单独做这个没意义。

比较合适的粒度是“实现登录接口，输入用户名密码，返回会话令牌，包含密码校验和错误码”。这个任务有明确的输入输出，能独立测试，也不会大到一次做不完。

实际操作中，我会让协调者先粗拆一层，然后对每个粗任务再拆一层，形成两级任务树。第一级是模块级，第二级是功能级。开发智能体接的是第二级任务。如果某个第二级任务还是太大，就标记出来让协调者再拆。这个“按需再拆”的机制比一次性拆到底更稳，因为拆的时候还没有足够信息判断粒度。

3.3 消息协议设计：让交接不出错

智能体之间交接任务时，消息里带什么信息，决定了接收方能不能顺利接手。我见过太多系统因为消息字段不全，导致接收方反复回问，效率比单模型还低。

我的消息协议包含这几个必填字段：

• task_id：任务唯一标识，贯穿整个生命周期。
• from/to：发送方和接收方ID。
• type：消息类型，如 task_assign、task_result、task_blocked。
• payload：具体内容，结构随类型变化。
• context_ref：上下文引用，指向共享存储里的相关文档。
• timestamp：时间戳，用于排序和排查。

重点是context_ref这个字段。它不直接传大段内容，而是传一个引用，接收方按需去共享存储里取。这样消息体保持轻量，同时接收方能拿到完整上下文。共享存储我用的是简单的文件系统加索引，每个任务一个目录，里面放需求、架构、代码、测试报告。智能体通过引用路径访问，避免消息里塞大段文本。

3.4 工具权限的隔离与最小化

每个智能体能调用哪些工具，必须严格限制。这不是为了安全，而是为了稳定。一个能读写所有文件的智能体，很容易在“顺手”改掉不该改的东西。

我的权限分配原则是“最小必要”：

• 需求分析：只能读需求相关目录，只能写需求文档。
• 架构设计：能读需求和架构目录，能写架构文档，能读代码但不能写。
• 开发实现：能读架构和接口定义，能读写自己负责的代码目录，能执行代码。
• 审查测试：能读所有代码和需求，能执行测试，但不能写任何代码文件。

这个隔离在实现上就是给每个智能体配一个工具白名单，调用不在白名单里的工具直接拒绝并记录。实测下来，权限隔离之后，智能体“手贱”改坏东西的情况基本消失了。

4. 实操过程与核心环节实现

4.1 环境准备与目录结构

先说环境。这套系统对运行环境要求不高，一台能跑Python的机器就行。核心依赖是模型调用SDK和一个消息队列。消息队列我用的是轻量的文件队列，没必要上重型中间件，因为智能体数量不多，吞吐要求也不高。

目录结构我按角色和任务两个维度组织：

agency/ ├── agents/ # 各智能体定义 │ ├── coordinator/ │ │ ├── prompt.txt │ │ └── config.json │ ├── analyst/ │ ├── architect/ │ ├── developer/ │ └── reviewer/ ├── shared/ # 共享存储 │ ├── tasks/ # 任务状态表 │ ├── docs/ # 需求、架构文档 │ └── code/ # 代码产物 ├── queue/ # 消息队列 │ ├── pending/ │ └── processed/ └── logs/ # 运行日志

每个智能体目录下的config.json定义它的工具白名单、模型参数、最大重试次数。prompt.txt就是前面说的四段式提示词。这个结构的好处是新增角色只需要加一个目录，不用改核心代码。

4.2 协调者的调度循环实现

协调者是整个系统的心脏，它的调度循环逻辑大致是这样：

def coordinator_loop(): while not all_tasks_done(): # 1. 检查是否有新目标需要拆解 if has_new_goal(): tasks = decompose_goal(get_new_goal()) register_tasks(tasks) # 2. 找出所有可执行的任务 ready = find_ready_tasks() # 依赖已满足且未分派 # 3. 按优先级分派 for task in sort_by_priority(ready): agent = select_agent(task) assign_task(agent, task) # 4. 处理阻塞和异常 handle_blocked_tasks() # 5. 收集完成的任务，触发下游 collect_results() sleep(POLL_INTERVAL)

这里有几个关键点。find_ready_tasks要检查任务的依赖是否都完成了，这靠任务状态表里的依赖字段。select_agent要考虑智能体的当前负载，避免一个智能体排队太多。handle_blocked_tasks是异常处理，任务卡住超过阈值就重新分派或上报。

POLL_INTERVAL我设的是2秒。太短浪费资源，太长响应慢。实测2秒是个平衡点。

4.3 一个完整任务的流转实录

拿一个具体任务走一遍，你能更清楚整个流程。假设用户目标是在某个模拟项目里“增加一个数据导出功能”。

第一步，协调者收到目标，拆成三个一级任务：定义导出格式、实现导出逻辑、编写导出测试。这三个任务有依赖关系：实现依赖格式定义，测试依赖实现。

第二步，格式定义任务分派给需求分析智能体。它读取目标描述，输出一份格式规格文档，包含字段列表、数据类型、示例。完成后任务状态变为待审查。

第三步，协调者发现实现任务依赖的格式定义已完成，把实现任务分派给开发智能体。开发智能体按需注入格式规格，写出导出代码，执行自测，输出代码文件和自测报告。

第四步，测试任务依赖的实现已完成，分派给审查测试智能体。它读取代码和格式规格，编写测试用例，执行测试，输出测试报告。如果发现问题，生成问题清单，任务状态变为阻塞，交回开发。

第五步，所有任务完成，协调者汇总产物，输出最终交付物。

这个流程里，每个交接点都是通过消息队列和共享存储完成的，没有任何一个智能体需要知道全局所有细节。这就是多智能体协作的价值——每个角色只关注自己那一亩三分地，整体却能跑通。

4.4 参数调优：重试、超时与并发

系统跑起来之后，参数调优决定了它稳不稳。我调过的主要有这几个：

max_retry设3是有讲究的。第一次失败可能是偶发，第二次失败可能是上下文问题，第三次还失败基本就是任务定义有问题，再重试也是浪费。这时候应该上报给协调者重新拆解，而不是死磕。

max_concurrent要根据你的模型调用配额来定。我一开始设了8，结果大量请求被限流，反而更慢。降到4之后，虽然并发低了，但每个请求都能及时响应，整体吞吐反而更高。

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

5.1 智能体互相甩锅怎么办

这是最常见的问题。表现是任务在两个智能体之间来回传递，谁也不肯接手。根本原因通常是职责边界模糊，或者任务定义不满足任何角色的输入要求。

排查思路：先看任务状态表，找到来回传递的任务，看它的当前状态和最近几次操作记录。如果是在“需求分析”和“架构设计”之间来回，多半是需求文档不够明确，架构设计无法据此做决策。解决办法是让需求分析补充规格，或者让协调者重新拆解这个任务。

我的经验是，甩锅问题90%出在任务定义上，而不是智能体本身。与其调提示词，不如回头检查任务拆解是否合理。

5.2 上下文丢失导致重复劳动

表现是开发智能体写完代码后，审查智能体说“没看到需求文档”，要求重新提供。这通常是上下文引用失效导致的。

排查：检查消息里的context_ref字段指向的路径是否存在，共享存储里的文件是否被意外覆盖。我遇到过一次是因为两个任务用了同一个文档路径，后一个任务覆盖了前一个的产物。解决办法是给每个任务的产物路径加上任务ID前缀，彻底避免冲突。

注意：共享存储的路径规划要在一开始就做好，后期改路径会导致大量引用失效。

5.3 任务卡死与死锁

死锁在多智能体系统里很隐蔽。表现是所有任务都停在“进行中”，但没有任何智能体在工作。常见原因是循环依赖：A等B的输出，B等A的输出。

排查：把任务依赖关系画成图，找环。我写了个简单的脚本，每次调度前检查依赖图有没有环，有环就报警并打破其中一条依赖。这个检查花不了多少时间，但能避免整个系统卡死。

另一个卡死原因是智能体崩溃后没有释放任务。解决办法是给每个任务加心跳机制，智能体定期更新任务的心跳时间，超过阈值没更新就判定为崩溃，任务重新入队。

5.4 输出质量不稳定的排查清单

有时候系统能跑通，但产出质量忽好忽坏。我整理了一个排查清单，按顺序检查：

按这个清单走一遍，大部分质量问题都能定位到具体环节。我遇到最多的是上下文注入不精准，把无关的需求片段也塞进去了，导致模型被干扰。收紧注入过滤之后，输出质量明显稳定。

5.5 独家避坑技巧汇总

最后分享几个文档里不会写、但实际很管用的技巧：

• 给每个智能体加“自检”步骤：在输出前让它自己检查一遍是否符合格式要求，不符合就重来。这个自检能拦掉大部分格式错误，比事后修复便宜得多。
• 日志要记全：每次模型调用的输入输出都存下来。出问题时，能直接回放当时的完整上下文，比猜快一百倍。
• 先跑通两个角色的协作，再扩展：别一上来就搭五个角色。先用协调者加开发两个角色跑通一个简单任务，确认消息传递和状态管理没问题，再逐个加角色。这样出问题容易定位。
• 任务状态表要能人工干预：留一个手动改状态的接口。有时候智能体判断错了，你手动把任务状态改一下就能继续，不用重启整个系统。
• 定期清理共享存储：跑久了产物会堆积，影响检索速度。我设了个定时任务，每周清理超过一定时间的中间产物，只保留最终交付物。

这套系统我从最初的两三个角色，慢慢迭代到现在的完整团队，中间踩的坑基本都在这了。核心体会是：多智能体协作的难点不在模型能力，而在工程细节——消息怎么传、状态怎么管、权限怎么分、异常怎么处理。把这些工程问题解决好，模型的能力才能被真正释放出来。如果你也在搭类似的系统，建议从最小闭环开始，跑通一个完整任务流，再逐步加角色和功能，别想着一步到位。