多智能体系统的工程约束：从Uncle Bob到swarm-forge的启示

当你第一次看到unclebob / swarm-forge这个组合时，第一反应很可能是：搞了三十多年“整洁代码”的 Robert C. Martin，怎么和一个听起来像科幻片里“蜂群锻造厂”的名字放在一起了？这里有一种强烈的错位感，而错位感往往就是值得写文章的信号。Uncle Bob 代表的是工程约束、纪律和可维护性；swarm 代表的却是多智能体协作、涌现行为和难以预测的系统。两者放在一起，不是在凑热点，而是在提醒所有正在做 AI Agent 开发的人：多智能体系统的瓶颈，从来不是“模型不够聪明”，而是工程上缺乏约束、边界和可测试性。

我写这篇文章的核心判断是：swarm-forge这类项目真正值得学习的，不是某个魔法级的多 Agent 框架，而是它背后“把群体协作锻造为可控工程系统”的思路。这个思路和 Uncle Bob 几十年来强调的 SOLID、测试驱动、依赖倒置一脉相承。换句话说，AI 编程并没有让软件工程退休，反而让软件工程变得更加重要。读完这篇文章，你会得到一个可以落地的思维模型：如何用经典软件设计原则去设计多智能体系统，如何写一个最小可运行的 swarm-forge 风格编排器，如何用 TDD 保证 Agent 协作行为稳定，以及实际项目中会遇到哪些坑、怎么排查。

这篇文章适合正在做 Agent 编排、工作流自动化，或者团队已经开始把多个大模型任务串起来的开发者。你不用提前会 Rust 或 Go，我们统一用 Python 讲通思路。你也不需要懂很深的分布式系统，因为这篇文章的重点是“设计约束”，不是“网络性能”。如果你想做的是把 5 个、10 个甚至更多 Agent 串起来完成一个复杂任务，同时又不想让它变成一个黑盒失控现场，那么这篇文章就是为你准备的。

1. 为什么 Uncle Bob 会和 swarm-forge 产生交集

先澄清一个容易误解的地方：swarm-forge如果只看仓库名，它既可以是一个具体的开源项目，也可以是一个理念代号。由于公开信息有限，最稳妥的理解方式是把它拆开看。“swarm”强调多 Agent 协作、群体智能；“forge”强调锻造、铸造、工程化。合在一起，它描述的是一种“把不可预测的群体智能锻造成可交付软件系统”的工程能力。

Uncle Bob 在这个语境里的意义，并不是说他真的会去写某个 Agent 框架，而是他背后的工程价值观恰好切中了当前多智能体开发的痛点。过去几年，大家已经见识过单体 Prompt 的局限：一个 Prompt 塞入太多任务，模型容易混乱，输出不稳定，问题难以定位。于是开发者开始把任务拆给多个 Agent 执行，比如一个负责规划、一个负责写代码、一个负责审查。这个方向是对的，但很多人做出来的东西只是“多个 Prompt 顺序调用”，而不是“多角色协作系统”。这就像让多个程序员同时在一个仓库里写代码，却没有任何分支策略、代码审查和测试约定——最终必然陷入混乱。

swarm-forge要回答的，正是“如何在一个多智能体系统里建立纪律”。这也是 Uncle Bob 式的工程经验和现代 AI 应用开发的交汇点。你可以把 Agent 想象成开发团队里的成员，把编排器想象成项目经理，把工具协议想象成接口文档，把测试想象成 CI 流水线。如果没有这些约束，每个 Agent 都是自由发挥的个体，系统整体行为就不可能稳定。理解了这一点，再看 swarm-forge，它就不是什么神秘的新范式，而是一组经典的软件工程原则在 AI 时代的新应用场景。

2. 多智能体系统里最容易失控的三个问题

在进入具体设计之前，先建立一个共同的问题背景。很多从单体代码生成跳过来做多 Agent 协作的团队，第一次跑通 demo 时会很兴奋，但进入真实业务后很快会发现三个问题。

第一个是职责边界模糊。开发者通常会给每个 Agent 写一个“身份提示词”，比如“你是代码专家”，但实际执行时，代码专家可能在改架构，架构师可能在写单元测试，测试工程师又可能在回复用户消息。因为底层调用的是同一个大模型，角色边界只靠 Prompt 来维持，而 Prompt 是软约束，模型经常越界。真实项目里，职责必须落到代码层面，比如把工具权限分开、把输入输出协议定义清楚，而不是只靠一句“你是一名……”。

第二个是流程不可控。多 Agent 协作通常表现为“A 的输出作为 B 的输入”。一旦链路深度超过三层，中间任何一步的输出格式发生变化，后面所有 Agent 都会跟着失控。看到的现象就是日志混乱、结果质量飘忽不定。这种问题的根源是缺少显式的状态转移：下一个该调用谁、什么时候结束、最多运行几轮、出错怎么回退，都没有定义。

第三个是系统不可测试。如果每次运行都要真实调用大模型，测试成本会非常高，而且结果不稳定。今天跑通过，明天换一个版本模型又失败了。这会让团队下意识地不敢改代码，因为不知道改动会影响哪个环节。这时候，多智能体系统就会变成一台“灵车”，能跑但没人知道它为什么能跑。要解决这几个问题，就不能只靠调 Prompt，必须回到软件工程的基本功：接口、依赖注入、状态机、测试替身。

3. 用 SOLID 原则约束 Agent 系统：一个类比

很多开发者对 SOLID 的印象停留在“写 Java 时用的设计原则”，觉得和 AI 开发没关系。其实 SOLID 解决的是“当系统里有多个可替换组件时，如何让它们稳定协作”的问题，而这正是多 Agent 系统的核心问题。

先看单一职责原则。一个 Agent 不应该同时承担“规划任务”“读取代码”“生成代码”“运行测试”“给用户汇报”五件事。它只需要负责一件事，比如“根据上下文生成一份可执行的修改计划”。其他工作交给其他 Agent 或工具。这样做的好处是，当任务结果不理想时，你能快速定位是规划出了问题，还是执行出了问题，而不是在一片混乱里猜。

再看开放封闭原则。多 Agent 系统一定会不断加入新能力和新工具。如果你的系统每加一个 Agent 都要改一遍编排器主流程，这种设计就是脆弱的。正确做法是让 Agent 实现统一接口，编排器只依赖接口，新增能力时通过注册机制扩展，而不是修改原有逻辑。

里氏替换原则在 Agent 场景里尤其重要。它要求任何 Agent 实现都能替换另一个实现，并且不会破坏编排器的预期。今天你用一个 GPT 系列模型实现的 CodingAgent，明天换成一个开源模型实现的 CodingAgent，编排器和测试不应该有感知。如果做不到这一点，说明所谓的“Agent 系统”其实还是和具体模型强耦合，替换成本很高。

接口隔离原则提醒我们，不要把几十个方法塞进一个万能 Agent 接口。每个 Agent 只需要暴露run(task, context)这类最小方法，以及自己的名称和描述。工具接口也一样。依赖倒置原则更是一针见血：系统的高层策略不应该依赖某个具体的 LLM SDK，而应该依赖一个抽象的“模型调用接口”。这样你才能在测试里用 FakeModel 替代真实模型，也才能在将来从一家模型服务切换到另一家时不改业务代码。

用一个比喻来说，真正的蜂群并不是每个工蜂都拥有全部能力，而是分工明确、通过信息素和固定的舞步交流。多 Agent 系统也一样，约束不是限制，而是协作的基础。没有 SOLID 这个“巢穴结构”，再聪明的 Agent 也只是一群嗡嗡乱撞的蜜蜂。

4. swarm-forge 风格编排器的核心结构设计

先不讲完整代码，而是先设计一套最小但完整的结构。我们假设一个 swarm-forge 风格的最小多 Agent 系统由四层组成：Agent 层、工具层、编排器层、配置层。

Agent 层负责定义每个角色的行为。它不直接绑定大模型，而是依赖一个模型调用接口。每个 Agent 接收任务和上下文，返回一个标准化结果。工具层把外部能力封装成可执行的函数，比如读文件、写文件、搜索文档、执行测试。工具必须对自己的副作用负责，最好能在注册时声明权限级别。编排器层是整台机器的心脏，它维护当前 Agent 的流转状态，决定什么时候继续、什么时候结束、什么时候超时。配置层解决“不同环境下要不要启用不同 Agent、不同工具”的问题。

这套结构和传统后端系统的分层非常相似。如果你接触过 Spring 里的 Service 层和 Repository 层，或者写过带有 Controller/Service/Dao 的代码，你会发现多 Agent 系统的本质并没有跳出这个框架。只是把 Repository 换成了模型调用，把业务规则换成了任务状态机。

我们为什么需要状态机？因为 Agent 是一个不可靠函数，同一个输入可能产生不同输出。如果流程靠文本自由流转，比如让模型直接输出 next_agent 字段，你就必须对取值做枚举校验，并且在默认情况下，不信任模型给出的下一个 Agent。一个更稳妥的设计是，由编排器基于 Agent 返回的状态码决定下一步，而不是让模型随心所欲地跳转。这样系统更可控，也更接近“工程系统”而不是“提示词剧本”。

5. 最小示例：用 Python 实现一个 ForgeOrchestrator

下面用一个最小可运行的 Python 示例来演示上述设计。这里的代码不是某个现成仓库的源码，而是帮助你理解 swarm-forge 风格系统的通用实现思路。你可以把它当作一个脚手架，后续替换成自己的 Agent 和工具。

先定义 Agent 接口。这个接口很小，只包含名称、描述和一次运行能力。

# swarm_forge/agents/base.py from abc import ABC, abstractmethod from dataclasses import dataclass from typing import Optional @dataclass class AgentResult: status: str output: str next_agent: Optional[str] = None class Agent(ABC): name: str = "" description: str = "" @abstractmethod def run(self, task: str, context: dict) -> AgentResult: """执行当前 Agent 的职责，并返回标准化结果。"""

这段代码里，我刻意没有让 Agent 直接依赖任何大模型 SDK。它是面向抽象编程的，具体模型调用应该放在实现了Agent的类里，并且通过构造函数注入。AgentResult有三个字段：status表示当前状态，output是结果文本，next_agent是可选的下一个 Agent 名称。只要约束住这个返回结构，编排器就可以稳定地做状态流转。

接下来定义工具接口。工具在多 Agent 系统里相当于 Agent 的“双手”，但它必须是受控的。

# swarm_forge/tools/base.py from abc import ABC, abstractmethod from dataclasses import dataclass @dataclass class ToolSpec: name: str description: str parameters: dict class Tool(ABC): spec: ToolSpec @abstractmethod def execute(self, **kwargs) -> str: """执行工具并返回字符串结果。"""

为什么工具接口只返回字符串？因为在生产环境里，工具结果通常会被拼进大模型上下文，结构化对象反而容易导致格式混乱。你可以把工具的返回值理解为“给模型看的证据文本”。如果工具返回的是一个复杂对象，就在内部先序列化好，再交给上层。这一层抽象也为后续做权限控制留下了位置。

最后是编排器。它本身不写 Prompt，也不调用模型，只负责按规则流转 Agent。

# swarm_forge/core/orchestrator.py from typing import Dict, Optional from swarm_forge.agents.base import Agent, AgentResult class ForgeOrchestrator: def __init__(self, agents: Dict[str, Agent], default_agent: str, max_rounds: int = 10): self._agents = agents self._default_agent = default_agent self._max_rounds = max_rounds def run(self, task: str, context: Optional[dict] = None) -> AgentResult: ctx = context or {} current_agent = self._default_agent for _ in range(self._max_rounds): agent = self._agents[current_agent] result = agent.run(task, ctx) ctx["last_agent"] = current_agent ctx["last_output"] = result.output if result.status == "done" or result.next_agent is None: return result if result.next_agent not in self._agents: raise KeyError(f"未知的下一个 Agent: {result.next_agent}") current_agent = result.next_agent raise RuntimeError("swarm run exceeded max_rounds")

这段编排逻辑非常朴素，但已经具备几个关键能力：默认进入哪个 Agent、最多运行几轮、状态为 done 时结束、未知转移目标马上报错。正是因为这些约束存在，系统才没有失控空间。实际项目中，max_rounds应该放在配置里，并且根据任务复杂度调优。你还可以在编排器里加入审计日志、人工审批钩子、调用链追踪等能力，但核心的结构不会变。

6. 用 TDD 锁定 Agent 协作行为

多 Agent 系统最大的问题是不可预测，而 TDD 是应对不可预测性的最好工具。你不需要在每次测试里真实调用大模型，只要用 FakeAgent 模拟出不同的协作结果，就能验证编排器是否做了正确的事情。

下面是一个基于 pytest 的测试示例。它的目标是验证：当 planner 返回“continue”并指定下一个 Agent 为 coder 时，编排器会正确地把任务交给 coder，并在 coder 返回 done 后结束。

# tests/test_orchestrator.py from swarm_forge.core.orchestrator import ForgeOrchestrator from swarm_forge.agents.base import Agent, AgentResult class FakeAgent(Agent): def __init__(self, name: str, result: AgentResult): self.name = name self.result = result def run(self, task: str, context: dict) -> AgentResult: return self.result def test_planner_hands_off_to_coder(): planner = FakeAgent( "planner", AgentResult(status="continue", output="plan ready", next_agent="coder"), ) coder = FakeAgent( "coder", AgentResult(status="done", output="code written"), ) orchestrator = ForgeOrchestrator( agents={"planner": planner, "coder": coder}, default_agent="planner", max_rounds=10, ) result = orchestrator.run("build login module") assert result.status == "done" assert result.output == "code written"

这个测试没有调用任何大模型，但它验证了整个流程最关键的部分：状态流转是否正确。你还可以继续写“未知 next_agent 时报错”的测试、“超过 max_rounds 时报错”的测试，以及“某 Agent 输出为空时如何处理”的测试。这些测试让你的系统在重构时不会突然崩掉。

运行测试的命令也很简单：

python -m pytest tests/test_orchestrator.py -q

如果代码正确，你会看到类似下面的输出：

1 passed in 0.03s

一旦测试通过，你就可以放心进入真实模型接入阶段。真实的 Agent 类应该把模型调用藏在内部，但对外仍然遵守同一个Agent接口。这样设计的好处是，你可以把“与模型相关的风险”和“与流程相关的风险”分开。流程问题用 FakeAgent 测，模型问题单独用集成测试去覆盖。对多 Agent 系统来说，这种分层测试策略非常重要。

7. 配置驱动：让 Agent 协作关系不再写在代码里

在真实业务中，不同项目可能需要不同数量的 Agent 和工具。如果每次调整都要改代码、重新部署，代价太高。配置文件是工程化的第一步。下面是一个简化的 YAML 配置示例，演示如何描述 Agent 注册、工具列表和全局参数。

# config/agents.yaml agents: planner: class: "app.agents.PlannerAgent" model: "llm_api_model_name" temperature: 0.2 tools: - "search_docs" max_steps: 5 coder: class: "app.agents.CoderAgent" model: "llm_api_model_name" temperature: 0.4 tools: - "read_file" - "write_file" - "run_tests" reviewer: class: "app.agents.ReviewerAgent" model: "llm_api_model_name" temperature: 0.1 tools: - "diff_check" default_agent: "planner" max_rounds: 20 safety: require_human_approval: true banned_tools: - "drop_database" - "rm_rf"

注意，这里我把模型名写成llm_api_model_name，因为具体模型名取决于你所在公司可用的模型服务，不要照搬任何固定版本。这段配置的重点是：Agent 的名称、实现类、模型参数、工具列表都被抽离出来。编排器在启动时读取配置，通过反射或工厂方法创建对象，并执行注册。这样，新增一个 Agent 只需要新增一个类、在配置里加一段描述，不需要改动编排器源码。

配置中safety部分值得单独强调。多 Agent 系统一旦拥有执行工具的能力，安全控制就不能只依赖开发人员的自觉。banned_tools是一个简单硬编码黑名单，更完整的方案是设置工具级 RBAC，例如某些 Agent 只能读文件、不能写文件，某些 Agent 只能在测试环境执行命令。人工审批钩子也很重要，尤其是涉及数据库变更、生产环境部署、对外发送消息等高风险动作时。这个钩子可以在ForgeOrchestrator里加一个回调，在调用特定工具前暂停并等待确认。

8. 常见问题与排查思路

即使设计再完整，多 Agent 系统也难免出问题。下面按高频到低频列出我见过的几个典型问题，以及它们的排查思路。

排查多 Agent 问题时，第一原则是“先看流转，再看 Prompt，最后看模型”。大多数问题不是模型智商不够，而是流程没有给模型足够的约束。日志里只要能清晰看到每个 Agent 的输入、输出、转移目标，问题就解决了一半。因此，从第一天起就要在编排器里加入结构化日志。每条日志至少包含：任务 ID、当前 Agent、当前状态、输出摘要、下一个 Agent、耗时和 token 消耗。

另外要特别注意提示词注入问题。由于 Agent 会读取外部文本、文件内容、网页内容，攻击者可能在这些内容里植入恶意指令，诱导 Agent 执行危险工具。这属于多 Agent 系统特有的安全风险。防御措施包括：对输入内容做指令边界标记，核心系统提示词不拼接不可信内容，高危工具默认禁止，以及输出经过白名单校验后再执行。

9. 最佳实践与工程建议

结合前面的代码和问题，给出几条我在实际工程中认为最值得遵守的建议。

第一，每个 Agent 必须有一个明确且可验证的职责。判断标准很简单：如果这个 Agent 失败了，你能用一句话说明哪里失败了吗？如果你说不清楚，说明职责还是太宽。建议在 Agent 实现类里只写一种行为，所有复杂任务通过编排器拆解成子任务，而不是靠一个万能 Agent 不断加 Prompt。

第二，外部调用必须经过接口。这里的外部调用包括大模型、数据库、文件系统、外部 API。不要让业务代码直接import openai或直接执行 subprocess。所有访问都通过 Tool 接口或 Model 接口，这样你才能方便地替换实现、加日志、加权限控制。这也是依赖倒置原则在 AI 时代最直接的应用。

第三，建立完整的可观测性。多 Agent 系统的调试难度远高于单体应用。建议为每次任务生成一个唯一 trace ID，贯穿所有 Agent 和工具调用。每个工具调用都记录参数摘要和返回结果长度，出现异常时能按 trace ID 快速检索。这个成本不高，但收益极大。

第四，把人工审批放在关键路径上，而不是放在发现问题之后。多 Agent 系统最危险的时刻是“看着一切正常，但某一步悄悄越界”。在高风险操作前阻塞并让人类确认，虽然会降低自动化程度，但能避免灾难性后果。更合理的做法是分场景：低风险任务全自动，中风险任务半自动，高风险任务强制人工。

第五，用版本控制管理 Agent 行为和 Prompt 变更。很多团队把 Prompt 存在数据库或代码里，改完没有评审和回滚机制。更稳妥的做法是把 Prompt 当作代码的一部分，纳入 Git 管理，每次修改都有 diff，可以评审，可以回滚。Agent 系统的输出和质量会随模型版本变化而变化，因此也要记录模型版本，方便归因。

第六，不要追求“所有任务都由多个 Agent 协作”。两个 Agent 能完成的事，不要拆成五个。Agent 数量越多，上下文传递越复杂，出错的概率越高。swarm 系统看起来聪明的关键在于角色分工合理，而不是数量多。最好的系统是“最少 Agent 完成目标，且每个 Agent 边界清晰”。

10. 更进一步：从 Agent 编排到真正的大型协作系统

如果你已经照着上面的结构跑通了一个最小系统，下一步可以关注几个方向。第一个方向是事件驱动。当前的编排器是顺序调度，真正的 swarm 系统可能需要异步事件和消息队列。每个 Agent 变成事件消费者，事件总线负责路由。这个方向适合 Agent 数量多、任务并行度高的场景。

第二个方向是 Saga 模式。当你把 Agent 的行为扩展到真实业务事务中，比如“创建订单→扣减库存→调用外部支付”，就需要考虑部分成功、部分失败的情况。Saga 模式提供了一种在分布式场景下处理补偿事务的思路，这套思路完全可以迁移到多 Agent 系统中。Agent 之间不再是简单链式调用，而是一个需要回滚和补偿的业务流程。

第三个方向是强化对模型不确定性的理解。多 Agent 系统的许多问题源于模型输出的概率性。与其完全消除随机性，不如在设计上接受随机性，并通过校验、重试和回退机制来兜底。Uncle Bob 的测试驱动开发哲学在这里依然有效：如果连测试都无法稳定运行，就不应该把它放进生产环境。

最后，无论你是否使用 swarm-forge 这个名字，我都建议你把这次实践当成一次“软件工程回归训练”。你会发现，面对 AI 系统时，真正稀缺的不是“会写 Prompt”，而是“会设计约束”。把任务拆小、把接口收紧、把流程测稳，这套方法论已经帮助软件行业走过了几十年，它依然会在 AI 时代继续证明自己的价值。

如果你接下来想在团队里落地这套思路，建议先从一个小任务开始：把现有最长的一条“人工串 Prompt”流程，改造成 3 个职责明确的 Agent，加上 FakeAgent 测试、配置文件和 trace 日志。先跑通一个最小闭环，再逐步扩展。相信你会感受到，多智能体系统从一个“实验玩具”变成一个“可交付工程”的关键，并不是更强的模型，而是更扎实的工程纪律。