1. 项目概述当智能体遇上经典设计模式最近在捣鼓一个叫Trae-Agent的智能体项目这玩意儿本质上是一个能自主执行任务、与环境交互的软件实体。在给它“注入灵魂”的过程中我发现一个挺有意思的现象那些被我们念叨了无数遍的经典设计模式在这里不是生搬硬套的理论而是解决实际痛点的绝佳工具箱。很多新手朋友一听到“设计模式”就觉得头大感觉是面试时才用的八股文但在构建像Trae-Agent这样结构复杂、行为多变的系统时你会发现没有这些模式代码很快就会变成一团乱麻维护和扩展的成本高得吓人。Trae-Agent的核心目标是模拟一个具备感知、决策、执行能力的智能体。它可能需要从不同来源比如API、数据库、传感器获取信息根据一套复杂的逻辑或学习到的策略做出决策然后调用各种工具如发送请求、操作文件、控制硬件去执行。这个过程里变化是常态今天要接入一个新的数据源明天决策算法要升级后天执行器要换一种实现。如果代码写死了每变一次就得伤筋动骨。这时候设计模式的价值就凸显出来了——它们提供了一套经过验证的、优雅的“组装”蓝图让系统在面对变化时能保持灵活和稳定。这篇文章我就结合在Trae-Agent项目里的实际踩坑和填坑经历聊聊几个用起来特别“顺手”的设计模式。我不会空谈理论而是聚焦在“为什么用”、“怎么用”以及“用了之后到底解决了啥问题”上。无论你是正在构建自己的智能体项目还是单纯想看看设计模式在真实复杂系统里是怎么活起来的相信都能找到一些直接的参考和启发。我们避开那些教科书式的定义直接进入实战场景。2. 核心场景与模式选型逻辑在深入代码之前我们得先看清楚Trae-Agent面临的核心场景是什么以及这些场景天然地呼唤哪些设计模式。智能体不是个单体服务它是一个由多个职责分明、但又需要紧密协作的模块构成的生态系统。2.1 场景一异构工具的灵活接入与执行这是智能体的“手”和“脚”。一个智能体可能需要调用天气查询API、操作数据库、生成一份报告文件甚至控制一个机械臂。这些工具Tools的接口、调用方式、返回格式千差万别。最原始的写法可能是这样if (toolName.equals(“weather”)) { // 调用天气API的一堆代码 } else if (toolName.equals(“db_query”)) { // 拼接SQL、获取连接、执行查询的代码 } else if (toolName.equals(“file_write”)) { // 文件流操作代码 } // ... 每加一个工具这里就多一个if-else分支这种写法的弊端显而易见执行引擎的代码if-else部分与具体工具的实现代码高度耦合。添加新工具必须修改引擎的核心逻辑违反了开闭原则而且随着工具数量增长这个判断会变得极其臃肿难以维护。模式选型工厂方法模式 策略模式为什么是工厂方法我们需要一个统一的“创建者”来负责实例化具体的工具对象。执行引擎不关心工具是怎么来的它只关心得到一个能用的工具实例。工厂方法模式将对象的创建逻辑封装起来执行引擎只需依赖一个抽象的工厂接口或方法。为什么结合策略模式每个工具本质上都是一个具体的“算法”或“行为”。策略模式定义一族算法并将每一个算法封装起来让它们可以互相替换。在这里每个工具类就是一个具体的策略。执行引擎通过统一的接口来调用工具从而实现了执行逻辑与具体工具实现的解耦。2.2 场景二智能体状态与行为的动态管理智能体是有状态的。它可能处于“初始化”、“感知中”、“决策中”、“执行中”、“等待”、“错误”等状态。状态的变化驱动着行为的改变。例如在“错误”状态下智能体的行为可能是重试或通知用户而不是继续执行下一个任务。用一堆标志位和if-else来控制状态流转代码会迅速变得难以理解和调试。模式选型状态模式为什么是状态模式状态模式允许一个对象在其内部状态改变时改变它的行为对象看起来好像修改了它的类。它为每一种状态创建一个状态类将状态相关的行为封装到对应的类中。在Trae-Agent中我们可以为“初始化状态”、“执行状态”、“错误状态”等分别建立类。这样状态转移的逻辑和每个状态下的行为都变得清晰、内聚新增状态只需新增一个类无需修改其他状态的代码。2.3 场景三事件驱动的通信与日志记录智能体的各个组件之间需要通信。比如感知模块收到新数据后需要通知决策模块执行模块完成任务后需要通知日志系统记录也可能需要更新智能体的内部状态。如果采用模块间直接互相调用的方式会形成复杂的网状依赖任何一个模块的改动都可能产生涟漪效应。模式选型观察者模式为什么是观察者模式它定义了一种一对多的依赖关系当一个对象主题的状态发生改变时所有依赖于它的对象观察者都会得到通知并自动更新。在Trae-Agent中我们可以让核心事件如“任务开始”、“工具调用”、“状态变更”、“错误发生”作为主题。日志记录器、监控仪表盘、状态管理器等模块作为观察者订阅它们关心的事件。这样发布事件的模块完全不需要知道谁在监听实现了彻底的解耦。2.4 场景四复杂决策流程的构建智能体的决策过程可能是一连串的步骤先检查条件A再验证条件B然后执行策略C如果失败则回退到策略D。这个流程可能经常需要调整顺序或增删步骤。如果硬编码在某个决策方法里每次流程变更都是一次代码重构。模式选型责任链模式 模板方法模式为什么是责任链它可以将决策的多个步骤处理器连接成一条链。请求沿着链传递直到有一个处理器处理它为止。这非常适合用来实现规则引擎或过滤器链。例如一个决策请求先后经过“权限校验处理器”、“参数验证处理器”、“核心策略处理器”。为什么结合模板方法模板方法模式在父类中定义一个算法的骨架而将一些步骤延迟到子类中实现。我们可以定义一个抽象的“决策步骤”模板其中包含一些通用逻辑如日志记录、性能统计而将具体的决策逻辑留给子类实现。这样既保证了流程的稳定性又保留了具体步骤的灵活性。注意模式不是银弹。不要为了用模式而用模式。上述选型是基于Trae-Agent的典型复杂度得出的。如果你的智能体非常简单可能只需要其中一两种甚至不用。模式的引入会增加一定程度的抽象在简单场景下可能是过度设计。判断标准是当你在代码中频繁地因为添加新功能而修改旧代码或者发现模块间依赖混乱时就是考虑引入合适模式的时机了。3. 核心模式实现详解与代码实战理论说再多不如一行代码。我们挑两个在Trae-Agent中最核心、最体现价值的模式看看它们是如何落地的。3.1 策略模式与工厂方法构建灵活的工具库这是智能体的基石。我们的目标是执行引擎拿到一个工具名如”google_search”就能获得一个对应的工具实例并执行而引擎本身对此一无所知。第一步定义策略接口所有工具都必须遵守这个“契约”。public interface Tool { /** * 工具的唯一标识符 */ String getName(); /** * 工具的描述可用于Agent的自我提示 */ String getDescription(); /** * 执行工具的核心方法 * param input 工具执行的输入参数通常是JSON字符串或Map * return 执行结果 * throws ToolExecutionException 工具执行异常 */ String execute(String input) throws ToolExecutionException; }第二步实现具体策略工具每个工具都是一个独立的类实现Tool接口。// 网络搜索工具 public class GoogleSearchTool implements Tool { Override public String getName() { return “google_search”; } Override public String getDescription() { return “使用Google搜索网络信息。输入应为搜索关键词。”; } Override public String execute(String input) { // 模拟或实际调用Google Search API String apiKey Config.get(“google.api.key”); // ... 构造请求、发送、解析响应 return “搜索 ‘” input “‘ 的结果是...”; } } // 计算器工具 public class CalculatorTool implements Tool { Override public String getName() { return “calculator”; } Override public String getDescription() { return “执行数学计算。输入为数学表达式如 ‘2 3 * 4’。”; } Override public String execute(String input) { try { // 使用表达式引擎如 javax.script 或自己解析 ScriptEngineManager mgr new ScriptEngineManager(); ScriptEngine engine mgr.getEngineByName(“JavaScript”); Object result engine.eval(input); return “计算结果” result.toString(); } catch (ScriptException e) { throw new ToolExecutionException(“计算表达式无效: ” input, e); } } }第三步实现工厂工厂负责根据工具名创建对应的工具实例。这里我们用一种简单高效的注册表方式实现工厂。public class ToolFactory { // 工具注册表维护 工具名 - 工具类 的映射 private static final MapString, Class? extends Tool toolRegistry new HashMap(); static { // 静态初始化块注册所有已知工具 registerTool(“google_search”, GoogleSearchTool.class); registerTool(“calculator”, CalculatorTool.class); // registerTool(“weather”, WeatherTool.class); // registerTool(“db_query”, DatabaseQueryTool.class); } public static void registerTool(String name, Class? extends Tool toolClass) { toolRegistry.put(name, toolClass); } public static Tool createTool(String toolName) throws ToolCreationException { Class? extends Tool toolClass toolRegistry.get(toolName); if (toolClass null) { throw new ToolCreationException(“未找到工具: ” toolName); } try { // 假设工具类都有无参构造器 return toolClass.getDeclaredConstructor().newInstance(); } catch (Exception e) { throw new ToolCreationException(“创建工具实例失败: ” toolName, e); } } }第四步执行引擎如何使用现在执行引擎的代码变得极其简洁和稳定。public class AgentExecutionEngine { public String executeTask(String toolName, String input) { try { // 1. 通过工厂获取工具策略 Tool tool ToolFactory.createTool(toolName); // 2. 执行工具 String result tool.execute(input); // 3. 处理结果... return result; } catch (ToolCreationException | ToolExecutionException e) { // 统一异常处理 return “执行失败: ” e.getMessage(); } } }实操心得与避坑指南工具的动态注册上面的工厂使用静态注册适合工具集固定的场景。如果工具需要热插拔比如从配置文件或数据库加载可以将注册表toolRegistry改为非静态并提供registerTool和unregisterTool方法。更高级的做法是结合Java的SPIService Provider Interface机制实现工具的自动发现。工具实例的复用上面的createTool每次都会new一个新实例。如果工具是无状态的或者构造成本很高比如需要建立网络连接可以考虑在工厂内部使用对象池或缓存单例避免重复创建的开销。依赖注入如果具体工具类依赖其他服务如HTTP客户端、数据库连接池简单的newInstance()可能不够。可以考虑引入一个轻量级的依赖注入容器或者在工厂方法中传入必要的依赖项。一个折中的办法是让工具类实现一个initialize(MapString, Object context)方法由工厂在创建后调用。描述信息的利用getDescription()返回的信息非常有用可以自动生成智能体的“能力说明书”或者用于构造给大语言模型LLM的提示词Prompt让LLM知道智能体有哪些工具可用。3.2 观察者模式实现松耦合的事件总线智能体内部发生的事情很多模块都想知道。我们用观察者模式构建一个简单的事件总线。第一步定义事件对象事件是携带数据的消息体。public abstract class AgentEvent { private final String eventType; private final long timestamp; private final String sourceModule; public AgentEvent(String eventType, String sourceModule) { this.eventType eventType; this.sourceModule sourceModule; this.timestamp System.currentTimeMillis(); } // getters ... } // 具体事件工具调用事件 public class ToolInvokedEvent extends AgentEvent { private final String toolName; private final String input; private final String result; private final long durationMs; public ToolInvokedEvent(String sourceModule, String toolName, String input, String result, long durationMs) { super(“TOOL_INVOKED”, sourceModule); this.toolName toolName; this.input input; this.result result; this.durationMs durationMs; } // getters ... } // 具体事件状态变更事件 public class StateChangedEvent extends AgentEvent { private final String oldState; private final String newState; public StateChangedEvent(String sourceModule, String oldState, String newState) { super(“STATE_CHANGED”, sourceModule); this.oldState oldState; this.newState newState; } // getters ... }第二步定义观察者接口public interface EventListener { /** * 处理接收到的事件 * param event 事件对象 */ void onEvent(AgentEvent event); }第三步实现具体观察者// 日志观察者 public class LoggingEventListener implements EventListener { private final Logger logger LoggerFactory.getLogger(LoggingEventListener.class); Override public void onEvent(AgentEvent event) { // 可以根据事件类型进行不同详细程度的日志记录 if (event instanceof ToolInvokedEvent) { ToolInvokedEvent e (ToolInvokedEvent) event; logger.info(“工具调用 - 工具: {}, 耗时: {}ms, 结果: {}”, e.getToolName(), e.getDurationMs(), e.getResult().substring(0, Math.min(50, e.getResult().length()))); } else if (event instanceof StateChangedEvent) { StateChangedEvent e (StateChangedEvent) event; logger.info(“状态变更 - 从 [{}] 变为 [{}]”, e.getOldState(), e.getNewState()); } // 其他事件类型... } } // 监控指标观察者可用于Prometheus, Metrics等 public class MetricsEventListener implements EventListener { private final MeterRegistry meterRegistry; // 假设使用Micrometer public MetricsEventListener(MeterRegistry meterRegistry) { this.meterRegistry meterRegistry; } Override public void onEvent(AgentEvent event) { if (event instanceof ToolInvokedEvent) { ToolInvokedEvent e (ToolInvokedEvent) event; // 记录工具调用次数和耗时 Counter counter meterRegistry.counter(“agent.tool.invoked”, “tool”, e.getToolName()); counter.increment(); Timer timer meterRegistry.timer(“agent.tool.duration”, “tool”, e.getToolName()); timer.record(e.getDurationMs(), TimeUnit.MILLISECONDS); } } }第四步实现事件总线主题public class EventBus { // 维护事件类型到监听器列表的映射 private final MapString, ListEventListener listeners new ConcurrentHashMap(); /** * 订阅事件 * param eventType 事件类型如 “TOOL_INVOKED”。使用 “*” 订阅所有事件。 * param listener 监听器 */ public void subscribe(String eventType, EventListener listener) { listeners.computeIfAbsent(eventType, k - new CopyOnWriteArrayList()).add(listener); } public void unsubscribe(String eventType, EventListener listener) { ListEventListener list listeners.get(eventType); if (list ! null) { list.remove(listener); } } /** * 发布事件 */ public void publish(AgentEvent event) { // 通知订阅了该具体事件类型的监听器 notifyListeners(event.getEventType(), event); // 通知订阅了所有事件“*”的监听器 notifyListeners(“*”, event); } private void notifyListeners(String eventType, AgentEvent event) { ListEventListener list listeners.get(eventType); if (list ! null) { for (EventListener listener : list) { try { listener.onEvent(event); } catch (Exception e) { // 防止一个监听器的异常影响其他监听器 LoggerFactory.getLogger(EventBus.class).error(“事件监听器处理异常”, e); } } } } }第五步在智能体中使用在智能体初始化时建立事件总线并注册监听器。public class TraeAgent { private EventBus eventBus; private AgentExecutionEngine executionEngine; public void init() { eventBus new EventBus(); // 注册监听器 eventBus.subscribe(“TOOL_INVOKED”, new LoggingEventListener()); eventBus.subscribe(“STATE_CHANGED”, new LoggingEventListener()); eventBus.subscribe(“TOOL_INVOKED”, new MetricsEventListener(metricsRegistry)); // 可以订阅所有事件用于调试 // eventBus.subscribe(“*”, new DebugEventListener()); executionEngine new AgentExecutionEngine(); } public String runTask(String tool, String input) { // 发布任务开始事件... eventBus.publish(new TaskStartedEvent(“AgentCore”, tool, input)); long start System.currentTimeMillis(); String result executionEngine.executeTask(tool, input); long duration System.currentTimeMillis() - start; // 发布工具调用事件 eventBus.publish(new ToolInvokedEvent(“ExecutionEngine”, tool, input, result, duration)); // 发布任务结束事件... return result; } }实操心得与避坑指南异步事件处理上面的publish方法是同步的会阻塞发布者线程直到所有监听器处理完毕。如果监听器处理耗时如写数据库、发网络请求会严重影响主流程性能。务必将其改为异步。可以使用一个单线程或多线程的ExecutorService来提交监听任务。事件顺序保证改为异步后事件的发布顺序和监听器的执行顺序可能无法保证。如果业务对顺序有严格要求如状态变更事件需要额外处理比如使用单线程的队列消费者或者给事件加上序列号。避免内存泄漏监听器如果持有对发布者或其他大对象的引用并且没有正确取消订阅可能导致无法被垃圾回收。在组件销毁时如Servlet的destroy方法记得调用unsubscribe。事件泛滥不要事无巨细都发布事件。只发布真正有多个消费者关心的、重要的状态变化或业务里程碑。过度使用事件总线会使系统流程难以跟踪和调试。4. 状态模式与责任链模式在决策流中的应用智能体的“大脑”——决策模块是逻辑最复杂的地方。状态模式和责任链模式能在这里大显身手。4.1 状态模式管理智能体的生命周期假设我们的智能体有IDLE空闲、THINKING思考决策、ACTING执行动作、ERROR错误四个状态。不好的实现标志位switchpublic class BadAgent { private String state “IDLE”; public void handleEvent(String event) { switch (state) { case “IDLE”: if (“start”.equals(event)) { state “THINKING”; startThinking(); } break; case “THINKING”: if (“decision_made”.equals(event)) { state “ACTING”; startActing(); } else if (“error”.equals(event)) { state “ERROR”; enterErrorState(); } break; case “ACTING”: // ... 更多的if-else break; case “ERROR”: // ... break; } } // ... 各种状态下的方法 }这段代码的维护噩梦在于状态转移逻辑散落在巨大的switch或if-else中添加一个新状态需要修改所有相关case每个状态下的行为也和状态机代码混在一起。使用状态模式重构第一步定义状态接口public interface AgentState { /** * 状态名称 */ String getName(); /** * 处理事件并返回下一个状态可能还是自己 */ AgentState handleEvent(AgentContext context, String event); }第二步实现具体状态类每个状态类只关心自己状态下的行为和可能的状态转移。public class IdleState implements AgentState { Override public String getName() { return “IDLE”; } Override public AgentState handleEvent(AgentContext context, String event) { if (“start”.equals(event)) { System.out.println(“[IDLE] 收到开始指令进入思考状态。”); context.setCurrentTask(event.getTask()); // 执行一些进入THINKING状态的预处理... return new ThinkingState(); // 转移到思考状态 } // 其他事件在当前状态下不处理或处理了但状态不变 System.out.println(“[IDLE] 忽略事件: ” event); return this; // 保持空闲状态 } } public class ThinkingState implements AgentState { Override public String getName() { return “THINKING”; } Override public AgentState handleEvent(AgentContext context, String event) { if (“decision_made”.equals(event)) { System.out.println(“[THINKING] 决策已做出开始执行。”); // 可能调用决策引擎将决策结果存入context context.setDecision(event.getDecision()); return new ActingState(); // 转移到执行状态 } else if (“error”.equals(event)) { System.out.println(“[THINKING] 思考过程出错。”); context.setLastError(event.getError()); return new ErrorState(); // 转移到错误状态 } else if (“cancel”.equals(event)) { System.out.println(“[THINKING] 任务被取消回到空闲状态。”); return new IdleState(); } return this; } } // ActingState 和 ErrorState 类似实现第三步定义上下文Context上下文持有当前状态并将事件委托给当前状态处理。public class AgentContext { private AgentState currentState; private String currentTask; private Object decision; private String lastError; // ... 其他上下文信息 public AgentContext() { this.currentState new IdleState(); // 初始状态 } public void handleEvent(String event) { // 委托给当前状态处理 AgentState nextState this.currentState.handleEvent(this, event); if (nextState ! this.currentState) { System.out.println(“状态转移: ” this.currentState.getName() ” - ” nextState.getName()); this.currentState nextState; } } // getters and setters ... }使用方式AgentContext agent new AgentContext(); agent.handleEvent(“start”); // 输出: [IDLE] 收到开始指令进入思考状态。 状态转移: IDLE - THINKING agent.handleEvent(“decision_made”); // 输出: [THINKING] 决策已做出开始执行。 状态转移: THINKING - ACTING agent.handleEvent(“error”); // 在ACTING状态下处理error事件...模式带来的好处清晰性每个状态的行为被封装在独立的类中代码内聚易于理解。可维护性添加新状态只需新增一个类修改某个状态的行为只需改一个类符合开闭原则。可测试性每个状态类可以独立进行单元测试。4.2 责任链模式构建可插拔的决策过滤器智能体的决策过程可能需要经过多个环节的校验或处理比如输入安全过滤、参数标准化、调用LLM获取初步决策、后处理格式化等。这些环节构成一个处理链。第一步定义处理器接口public interface DecisionHandler { /** * 设置下一个处理器 */ void setNext(DecisionHandler next); /** * 处理请求 * param context 决策上下文 * return 是否继续传递。true表示已处理完毕false表示传递给下一个处理器。 */ boolean handle(DecisionContext context); }第二步实现抽象基类可选简化代码public abstract class AbstractDecisionHandler implements DecisionHandler { protected DecisionHandler next; Override public void setNext(DecisionHandler next) { this.next next; } /** * 传递给下一个处理器 */ protected boolean passToNext(DecisionContext context) { if (next ! null) { return next.handle(context); } // 链的末端默认返回true表示处理完成或未处理 return true; } }第三步实现具体处理器// 1. 输入安全处理器 public class SecurityHandler extends AbstractDecisionHandler { Override public boolean handle(DecisionContext context) { String userInput context.getRawInput(); if (userInput ! null userInput.contains(“script”)) { context.setError(“输入包含非法脚本!”); return true; // 发现安全问题终止链条不再向后传递 } System.out.println(“[SecurityHandler] 安全检查通过。”); return passToNext(context); // 安全传递给下一个 } } // 2. 参数标准化处理器 public class NormalizationHandler extends AbstractDecisionHandler { Override public boolean handle(DecisionContext context) { String input context.getRawInput(); if (input ! null) { context.setNormalizedInput(input.trim().toLowerCase()); } System.out.println(“[NormalizationHandler] 参数已标准化。”); return passToNext(context); } } // 3. 核心LLM调用处理器 public class LLMHandler extends AbstractDecisionHandler { private LLMClient llmClient; public LLMHandler(LLMClient client) { this.llmClient client; } Override public boolean handle(DecisionContext context) { try { String prompt “基于以下输入做出决策: ” context.getNormalizedInput(); String llmResponse llmClient.complete(prompt); context.setLlmRawResponse(llmResponse); System.out.println(“[LLMHandler] 已调用LLM获得响应。”); } catch (Exception e) { context.setError(“LLM调用失败: ” e.getMessage()); return true; // 出错终止 } return passToNext(context); } } // 4. 响应后处理处理器 public class PostProcessHandler extends AbstractDecisionHandler { Override public boolean handle(DecisionContext context) { String rawResponse context.getLlmRawResponse(); if (rawResponse ! null) { // 假设我们提取JSON部分 String finalDecision extractJsonFromResponse(rawResponse); context.setFinalDecision(finalDecision); System.out.println(“[PostProcessHandler] 响应后处理完成。”); } return passToNext(context); // 通常是链条的最后一环 } }第四步组装责任链并使用public class DecisionChainBuilder { public static DecisionHandler buildChain() { // 创建处理器 SecurityHandler security new SecurityHandler(); NormalizationHandler normalize new NormalizationHandler(); LLMHandler llm new LLMHandler(new LLMClient()); PostProcessHandler postProcess new PostProcessHandler(); // 组装链条security - normalize - llm - postProcess security.setNext(normalize); normalize.setNext(llm); llm.setNext(postProcess); return security; // 返回链头 } } // 使用 public class DecisionEngine { private DecisionHandler decisionChain; public DecisionEngine() { this.decisionChain DecisionChainBuilder.buildChain(); } public DecisionResult makeDecision(String userInput) { DecisionContext context new DecisionContext(); context.setRawInput(userInput); // 从链头开始执行 decisionChain.handle(context); if (context.getError() ! null) { return DecisionResult.error(context.getError()); } return DecisionResult.success(context.getFinalDecision()); } }模式带来的好处与进阶技巧灵活配置你可以轻松调整链条的顺序或者动态增删处理器。例如在调试阶段你可以在LLMHandler后面插入一个LoggingHandler来记录请求和响应。单一职责每个处理器只做一件事代码清晰易于测试。开闭原则要增加新的处理逻辑比如一个CacheHandler用于缓存重复决策只需新建一个处理器类并在构建链时插入合适的位置无需修改任何现有处理器代码。链的终止注意handle方法的返回值设计。这里我们设计为true表示“已处理完毕链应终止”false或调用passToNext表示继续传递。SecurityHandler在发现威胁时返回true有效阻止了后续处理。与模板方法结合AbstractDecisionHandler中的passToNext方法已经是一个简单的模板。你可以进一步定义doHandle抽象方法让子类实现而在handle方法中加入统一的日志、性能监控等逻辑这就是模板方法模式的典型应用。5. 其他模式的点睛之笔与综合应用除了上述核心模式在Trae-Agent的其他角落一些模式也以简洁有力的方式解决了特定问题。5.1 单例模式管理全局配置与共享资源智能体需要访问全局配置如API密钥、超时设置、共享的资源池如数据库连接池、HTTP客户端池、线程池。这些资源通常只需要一个实例。public class AgentConfig { private static volatile AgentConfig instance; private Properties properties; private AgentConfig() { // 私有构造器防止外部new loadConfig(); } public static AgentConfig getInstance() { if (instance null) { synchronized (AgentConfig.class) { if (instance null) { instance new AgentConfig(); } } } return instance; } private void loadConfig() { properties new Properties(); try (InputStream is getClass().getClassLoader().getResourceAsStream(“agent.properties”)) { properties.load(is); } catch (IOException e) { throw new RuntimeException(“Failed to load config”, e); } } public String getApiKey(String service) { return properties.getProperty(service “.api.key”); } // ... 其他getter方法 }使用方式String key AgentConfig.getInstance().getApiKey(“openai”);注意单例模式的争议。在现代开发中尤其是依赖注入DI框架如Spring普及后单例模式常常被框架管理的单例Bean所取代。它的主要问题是不利于测试因为硬编码的静态调用很难被Mock。在Trae-Agent中如果规模较小或框架不复杂使用经典单例模式是简单直接的。如果项目复杂强烈建议使用DI容器来管理这些全局依赖。5.2 建造者模式构造复杂的智能体配置对象一个智能体的初始化可能需要一大堆参数名称、模型类型、温度系数、最大令牌数、系统提示词、工具列表、回调地址等等。使用构造器或setter方法会非常冗长且容易出错。public class AgentConfiguration { private final String name; private final String model; private final double temperature; private final int maxTokens; private final ListTool tools; private final String systemPrompt; // ... 更多字段 // 私有构造器强制使用建造者 private AgentConfiguration(Builder builder) { this.name builder.name; this.model builder.model; this.temperature builder.temperature; this.maxTokens builder.maxTokens; this.tools builder.tools; this.systemPrompt builder.systemPrompt; } // 静态内部类 Builder public static class Builder { private String name; private String model “gpt-3.5-turbo”; // 默认值 private double temperature 0.7; private int maxTokens 1000; private ListTool tools new ArrayList(); private String systemPrompt “You are a helpful assistant.”; public Builder(String name) { this.name name; } public Builder model(String model) { this.model model; return this; } public Builder temperature(double temp) { this.temperature temp; return this; } public Builder maxTokens(int tokens) { this.maxTokens tokens; return this; } public Builder addTool(Tool tool) { this.tools.add(tool); return this; } public Builder systemPrompt(String prompt) { this.systemPrompt prompt; return this; } public AgentConfiguration build() { // 可以在此处进行参数校验 if (temperature 0 || temperature 2) { throw new IllegalArgumentException(“Temperature must be between 0 and 2”); } return new AgentConfiguration(this); } } // ... getters }使用方式AgentConfiguration config new AgentConfiguration.Builder(“MyTraderAgent”) .model(“gpt-4”) .temperature(0.2) // 更低温度输出更确定 .maxTokens(2000) .addTool(new StockQueryTool()) .addTool(new NewsFetchTool()) .systemPrompt(“你是一个专业的量化交易分析助手回答必须基于数据保持客观谨慎。”) .build();这种方式代码可读性极强并且能保证配置对象在构建完成后是不可变的final字段线程安全。5.3 组合模式构建层级化的技能或任务树如果智能体的能力可以组织成树形结构比如一个“文档处理”技能下包含“文本提取”、“摘要生成”、“翻译”等子技能组合模式就非常适用。它允许你以统一的方式处理单个对象和对象组合。// 组件接口 public interface SkillComponent { String getName(); String execute(String input); } // 叶子节点基础技能 public class BasicSkill implements SkillComponent { private String name; private Tool tool; // 关联一个工具 // ... 构造器、getters Override public String execute(String input) { return tool.execute(input); } } // 复合节点技能组 public class SkillComposite implements SkillComponent { private String name; private ListSkillComponent children new ArrayList(); public void add(SkillComponent component) { children.add(component); } public void remove(SkillComponent component) { children.remove(component); } Override public String getName() { return name; } Override public String execute(String input) { // 复合技能的执行逻辑可能是顺序执行所有子技能也可能是选择其中一个 // 这里示例顺序执行并将结果合并 StringBuilder result new StringBuilder(); for (SkillComponent child : children) { result.append(child.getName()).append(“: “).append(child.execute(input)).append(“\n”); } return result.toString(); } }使用方式你可以构建一个复杂的技能树然后对根节点调用execute它会递归地调用整个树。这对于实现“宏技能”或“工作流”非常有用。6. 模式应用的常见陷阱与性能考量在实际项目中应用设计模式如果使用不当反而会引入新的复杂度。下面是一些我踩过的坑和总结的经验。6.1 过度设计模式泛滥这是新手最容易犯的错误。看到一点if-else就想用策略模式看到几个属性就想用建造者。记住模式是手段不是目的。在Trae-Agent初期我曾为每个简单的工具都套上完整的策略工厂模式后来发现很多工具只用一次且逻辑简单直接内联反而更清晰。判断标准如果未来三个月内这个模块有超过一次变更的可能性并且变更点明确如新增类型、修改行为那么引入模式是划算的。否则先用最简单的实现等变化真的发生时再重构。6.2 抽象泄漏工厂与具体类的耦合在工具工厂的例子中我们使用了Class.forName或映射表。这里有一个隐藏的耦合工厂需要知道所有具体工具类的全限定名。当工具实现分散在不同模块或JAR包时注册会成为问题。解决方案使用配置文件将工具名类全名的映射写在配置文件中工厂启动时读取。使用SPI机制在META-INF/services目录下提供接口文件让Java ServiceLoader自动发现实现类。这是更优雅的解耦方式。依赖注入在Spring等框架中你可以将所有的Tool实现类都注入到一个MapString, Tool中键就是工具名工厂直接从这个Map里取。6.3 观察者模式的内存与性能陷阱同步阻塞如前所述同步事件发布是性能杀手。务必改为异步。可以使用一个ExecutorService甚至引入更成熟的消息队列如Disruptor、RabbitMQ来处理高吞吐场景。事件风暴如果事件发布过于频繁且观察者处理较慢会导致事件积压。需要监控事件总线的队列长度并考虑对事件进行合并如一段时间内的同类型状态变更只发布最后一次或采样。循环引用与内存泄漏如果观察者如一个UI组件直接引用了发布者如智能体核心并且没有正确取消订阅当UI组件销毁时由于仍被事件总线引用导致无法GC。务必在组件生命周期结束时取消订阅。6.4 状态模式的上下文膨胀AgentContext类很容易变成一个“上帝对象”里面塞满了所有状态类可能需要的字段。这违反了单一职责原则也让上下文变得难以维护。改善方法将上下文按功能拆分如ToolExecutionContext、DecisionMakingContext、UserSessionContext等状态类只注入它需要的那个上下文。使用参数传递在handleEvent方法中直接传递所需的数据而不是让状态类去上下文中抓取。6.5 责任链模式的调试困难当链条很长时如果一个请求没有达到预期结果很难一眼看出是哪个处理器出了问题或者链条是否被意外终止。调试技巧添加链路ID和日志在请求进入链时生成一个唯一ID并穿透所有处理器每个处理器都使用该ID记录日志。可视化链条可以写一个方法打印出当前责任链的处理器顺序。使用“调试处理器”在需要调试时在链条中插入一个DebugHandler它打印出入参和出参或者将上下文信息暂存起来供检查。设计模式是优秀工程师的通用语言和工具箱。在Trae-Agent这样的复杂智能体系统中恰当地运用它们就像给一座大厦搭好了坚固而灵活的钢结构。它不会让你的代码立刻变得高大上但会让它能从容应对未来的需求变化和规模增长。最关键的是要理解每个模式解决的核心问题是什么然后审视你自己的代码看是否遇到了同样的问题。如果是再优雅地引入它。记住最好的代码不是用了最多模式的代码而是最能平衡当下清晰度与未来扩展性的代码。在Trae-Agent的迭代过程中我也是先写出能跑的“烂代码”然后在它让我感到疼痛修改困难、bug频出时再运用模式去重构它这个过程本身就是对设计模式最深刻的学习。 智能体开发实战：设计模式在Trae-Agent中的核心应用与避坑指南
1. 项目概述当智能体遇上经典设计模式最近在捣鼓一个叫Trae-Agent的智能体项目这玩意儿本质上是一个能自主执行任务、与环境交互的软件实体。在给它“注入灵魂”的过程中我发现一个挺有意思的现象那些被我们念叨了无数遍的经典设计模式在这里不是生搬硬套的理论而是解决实际痛点的绝佳工具箱。很多新手朋友一听到“设计模式”就觉得头大感觉是面试时才用的八股文但在构建像Trae-Agent这样结构复杂、行为多变的系统时你会发现没有这些模式代码很快就会变成一团乱麻维护和扩展的成本高得吓人。Trae-Agent的核心目标是模拟一个具备感知、决策、执行能力的智能体。它可能需要从不同来源比如API、数据库、传感器获取信息根据一套复杂的逻辑或学习到的策略做出决策然后调用各种工具如发送请求、操作文件、控制硬件去执行。这个过程里变化是常态今天要接入一个新的数据源明天决策算法要升级后天执行器要换一种实现。如果代码写死了每变一次就得伤筋动骨。这时候设计模式的价值就凸显出来了——它们提供了一套经过验证的、优雅的“组装”蓝图让系统在面对变化时能保持灵活和稳定。这篇文章我就结合在Trae-Agent项目里的实际踩坑和填坑经历聊聊几个用起来特别“顺手”的设计模式。我不会空谈理论而是聚焦在“为什么用”、“怎么用”以及“用了之后到底解决了啥问题”上。无论你是正在构建自己的智能体项目还是单纯想看看设计模式在真实复杂系统里是怎么活起来的相信都能找到一些直接的参考和启发。我们避开那些教科书式的定义直接进入实战场景。2. 核心场景与模式选型逻辑在深入代码之前我们得先看清楚Trae-Agent面临的核心场景是什么以及这些场景天然地呼唤哪些设计模式。智能体不是个单体服务它是一个由多个职责分明、但又需要紧密协作的模块构成的生态系统。2.1 场景一异构工具的灵活接入与执行这是智能体的“手”和“脚”。一个智能体可能需要调用天气查询API、操作数据库、生成一份报告文件甚至控制一个机械臂。这些工具Tools的接口、调用方式、返回格式千差万别。最原始的写法可能是这样if (toolName.equals(“weather”)) { // 调用天气API的一堆代码 } else if (toolName.equals(“db_query”)) { // 拼接SQL、获取连接、执行查询的代码 } else if (toolName.equals(“file_write”)) { // 文件流操作代码 } // ... 每加一个工具这里就多一个if-else分支这种写法的弊端显而易见执行引擎的代码if-else部分与具体工具的实现代码高度耦合。添加新工具必须修改引擎的核心逻辑违反了开闭原则而且随着工具数量增长这个判断会变得极其臃肿难以维护。模式选型工厂方法模式 策略模式为什么是工厂方法我们需要一个统一的“创建者”来负责实例化具体的工具对象。执行引擎不关心工具是怎么来的它只关心得到一个能用的工具实例。工厂方法模式将对象的创建逻辑封装起来执行引擎只需依赖一个抽象的工厂接口或方法。为什么结合策略模式每个工具本质上都是一个具体的“算法”或“行为”。策略模式定义一族算法并将每一个算法封装起来让它们可以互相替换。在这里每个工具类就是一个具体的策略。执行引擎通过统一的接口来调用工具从而实现了执行逻辑与具体工具实现的解耦。2.2 场景二智能体状态与行为的动态管理智能体是有状态的。它可能处于“初始化”、“感知中”、“决策中”、“执行中”、“等待”、“错误”等状态。状态的变化驱动着行为的改变。例如在“错误”状态下智能体的行为可能是重试或通知用户而不是继续执行下一个任务。用一堆标志位和if-else来控制状态流转代码会迅速变得难以理解和调试。模式选型状态模式为什么是状态模式状态模式允许一个对象在其内部状态改变时改变它的行为对象看起来好像修改了它的类。它为每一种状态创建一个状态类将状态相关的行为封装到对应的类中。在Trae-Agent中我们可以为“初始化状态”、“执行状态”、“错误状态”等分别建立类。这样状态转移的逻辑和每个状态下的行为都变得清晰、内聚新增状态只需新增一个类无需修改其他状态的代码。2.3 场景三事件驱动的通信与日志记录智能体的各个组件之间需要通信。比如感知模块收到新数据后需要通知决策模块执行模块完成任务后需要通知日志系统记录也可能需要更新智能体的内部状态。如果采用模块间直接互相调用的方式会形成复杂的网状依赖任何一个模块的改动都可能产生涟漪效应。模式选型观察者模式为什么是观察者模式它定义了一种一对多的依赖关系当一个对象主题的状态发生改变时所有依赖于它的对象观察者都会得到通知并自动更新。在Trae-Agent中我们可以让核心事件如“任务开始”、“工具调用”、“状态变更”、“错误发生”作为主题。日志记录器、监控仪表盘、状态管理器等模块作为观察者订阅它们关心的事件。这样发布事件的模块完全不需要知道谁在监听实现了彻底的解耦。2.4 场景四复杂决策流程的构建智能体的决策过程可能是一连串的步骤先检查条件A再验证条件B然后执行策略C如果失败则回退到策略D。这个流程可能经常需要调整顺序或增删步骤。如果硬编码在某个决策方法里每次流程变更都是一次代码重构。模式选型责任链模式 模板方法模式为什么是责任链它可以将决策的多个步骤处理器连接成一条链。请求沿着链传递直到有一个处理器处理它为止。这非常适合用来实现规则引擎或过滤器链。例如一个决策请求先后经过“权限校验处理器”、“参数验证处理器”、“核心策略处理器”。为什么结合模板方法模板方法模式在父类中定义一个算法的骨架而将一些步骤延迟到子类中实现。我们可以定义一个抽象的“决策步骤”模板其中包含一些通用逻辑如日志记录、性能统计而将具体的决策逻辑留给子类实现。这样既保证了流程的稳定性又保留了具体步骤的灵活性。注意模式不是银弹。不要为了用模式而用模式。上述选型是基于Trae-Agent的典型复杂度得出的。如果你的智能体非常简单可能只需要其中一两种甚至不用。模式的引入会增加一定程度的抽象在简单场景下可能是过度设计。判断标准是当你在代码中频繁地因为添加新功能而修改旧代码或者发现模块间依赖混乱时就是考虑引入合适模式的时机了。3. 核心模式实现详解与代码实战理论说再多不如一行代码。我们挑两个在Trae-Agent中最核心、最体现价值的模式看看它们是如何落地的。3.1 策略模式与工厂方法构建灵活的工具库这是智能体的基石。我们的目标是执行引擎拿到一个工具名如”google_search”就能获得一个对应的工具实例并执行而引擎本身对此一无所知。第一步定义策略接口所有工具都必须遵守这个“契约”。public interface Tool { /** * 工具的唯一标识符 */ String getName(); /** * 工具的描述可用于Agent的自我提示 */ String getDescription(); /** * 执行工具的核心方法 * param input 工具执行的输入参数通常是JSON字符串或Map * return 执行结果 * throws ToolExecutionException 工具执行异常 */ String execute(String input) throws ToolExecutionException; }第二步实现具体策略工具每个工具都是一个独立的类实现Tool接口。// 网络搜索工具 public class GoogleSearchTool implements Tool { Override public String getName() { return “google_search”; } Override public String getDescription() { return “使用Google搜索网络信息。输入应为搜索关键词。”; } Override public String execute(String input) { // 模拟或实际调用Google Search API String apiKey Config.get(“google.api.key”); // ... 构造请求、发送、解析响应 return “搜索 ‘” input “‘ 的结果是...”; } } // 计算器工具 public class CalculatorTool implements Tool { Override public String getName() { return “calculator”; } Override public String getDescription() { return “执行数学计算。输入为数学表达式如 ‘2 3 * 4’。”; } Override public String execute(String input) { try { // 使用表达式引擎如 javax.script 或自己解析 ScriptEngineManager mgr new ScriptEngineManager(); ScriptEngine engine mgr.getEngineByName(“JavaScript”); Object result engine.eval(input); return “计算结果” result.toString(); } catch (ScriptException e) { throw new ToolExecutionException(“计算表达式无效: ” input, e); } } }第三步实现工厂工厂负责根据工具名创建对应的工具实例。这里我们用一种简单高效的注册表方式实现工厂。public class ToolFactory { // 工具注册表维护 工具名 - 工具类 的映射 private static final MapString, Class? extends Tool toolRegistry new HashMap(); static { // 静态初始化块注册所有已知工具 registerTool(“google_search”, GoogleSearchTool.class); registerTool(“calculator”, CalculatorTool.class); // registerTool(“weather”, WeatherTool.class); // registerTool(“db_query”, DatabaseQueryTool.class); } public static void registerTool(String name, Class? extends Tool toolClass) { toolRegistry.put(name, toolClass); } public static Tool createTool(String toolName) throws ToolCreationException { Class? extends Tool toolClass toolRegistry.get(toolName); if (toolClass null) { throw new ToolCreationException(“未找到工具: ” toolName); } try { // 假设工具类都有无参构造器 return toolClass.getDeclaredConstructor().newInstance(); } catch (Exception e) { throw new ToolCreationException(“创建工具实例失败: ” toolName, e); } } }第四步执行引擎如何使用现在执行引擎的代码变得极其简洁和稳定。public class AgentExecutionEngine { public String executeTask(String toolName, String input) { try { // 1. 通过工厂获取工具策略 Tool tool ToolFactory.createTool(toolName); // 2. 执行工具 String result tool.execute(input); // 3. 处理结果... return result; } catch (ToolCreationException | ToolExecutionException e) { // 统一异常处理 return “执行失败: ” e.getMessage(); } } }实操心得与避坑指南工具的动态注册上面的工厂使用静态注册适合工具集固定的场景。如果工具需要热插拔比如从配置文件或数据库加载可以将注册表toolRegistry改为非静态并提供registerTool和unregisterTool方法。更高级的做法是结合Java的SPIService Provider Interface机制实现工具的自动发现。工具实例的复用上面的createTool每次都会new一个新实例。如果工具是无状态的或者构造成本很高比如需要建立网络连接可以考虑在工厂内部使用对象池或缓存单例避免重复创建的开销。依赖注入如果具体工具类依赖其他服务如HTTP客户端、数据库连接池简单的newInstance()可能不够。可以考虑引入一个轻量级的依赖注入容器或者在工厂方法中传入必要的依赖项。一个折中的办法是让工具类实现一个initialize(MapString, Object context)方法由工厂在创建后调用。描述信息的利用getDescription()返回的信息非常有用可以自动生成智能体的“能力说明书”或者用于构造给大语言模型LLM的提示词Prompt让LLM知道智能体有哪些工具可用。3.2 观察者模式实现松耦合的事件总线智能体内部发生的事情很多模块都想知道。我们用观察者模式构建一个简单的事件总线。第一步定义事件对象事件是携带数据的消息体。public abstract class AgentEvent { private final String eventType; private final long timestamp; private final String sourceModule; public AgentEvent(String eventType, String sourceModule) { this.eventType eventType; this.sourceModule sourceModule; this.timestamp System.currentTimeMillis(); } // getters ... } // 具体事件工具调用事件 public class ToolInvokedEvent extends AgentEvent { private final String toolName; private final String input; private final String result; private final long durationMs; public ToolInvokedEvent(String sourceModule, String toolName, String input, String result, long durationMs) { super(“TOOL_INVOKED”, sourceModule); this.toolName toolName; this.input input; this.result result; this.durationMs durationMs; } // getters ... } // 具体事件状态变更事件 public class StateChangedEvent extends AgentEvent { private final String oldState; private final String newState; public StateChangedEvent(String sourceModule, String oldState, String newState) { super(“STATE_CHANGED”, sourceModule); this.oldState oldState; this.newState newState; } // getters ... }第二步定义观察者接口public interface EventListener { /** * 处理接收到的事件 * param event 事件对象 */ void onEvent(AgentEvent event); }第三步实现具体观察者// 日志观察者 public class LoggingEventListener implements EventListener { private final Logger logger LoggerFactory.getLogger(LoggingEventListener.class); Override public void onEvent(AgentEvent event) { // 可以根据事件类型进行不同详细程度的日志记录 if (event instanceof ToolInvokedEvent) { ToolInvokedEvent e (ToolInvokedEvent) event; logger.info(“工具调用 - 工具: {}, 耗时: {}ms, 结果: {}”, e.getToolName(), e.getDurationMs(), e.getResult().substring(0, Math.min(50, e.getResult().length()))); } else if (event instanceof StateChangedEvent) { StateChangedEvent e (StateChangedEvent) event; logger.info(“状态变更 - 从 [{}] 变为 [{}]”, e.getOldState(), e.getNewState()); } // 其他事件类型... } } // 监控指标观察者可用于Prometheus, Metrics等 public class MetricsEventListener implements EventListener { private final MeterRegistry meterRegistry; // 假设使用Micrometer public MetricsEventListener(MeterRegistry meterRegistry) { this.meterRegistry meterRegistry; } Override public void onEvent(AgentEvent event) { if (event instanceof ToolInvokedEvent) { ToolInvokedEvent e (ToolInvokedEvent) event; // 记录工具调用次数和耗时 Counter counter meterRegistry.counter(“agent.tool.invoked”, “tool”, e.getToolName()); counter.increment(); Timer timer meterRegistry.timer(“agent.tool.duration”, “tool”, e.getToolName()); timer.record(e.getDurationMs(), TimeUnit.MILLISECONDS); } } }第四步实现事件总线主题public class EventBus { // 维护事件类型到监听器列表的映射 private final MapString, ListEventListener listeners new ConcurrentHashMap(); /** * 订阅事件 * param eventType 事件类型如 “TOOL_INVOKED”。使用 “*” 订阅所有事件。 * param listener 监听器 */ public void subscribe(String eventType, EventListener listener) { listeners.computeIfAbsent(eventType, k - new CopyOnWriteArrayList()).add(listener); } public void unsubscribe(String eventType, EventListener listener) { ListEventListener list listeners.get(eventType); if (list ! null) { list.remove(listener); } } /** * 发布事件 */ public void publish(AgentEvent event) { // 通知订阅了该具体事件类型的监听器 notifyListeners(event.getEventType(), event); // 通知订阅了所有事件“*”的监听器 notifyListeners(“*”, event); } private void notifyListeners(String eventType, AgentEvent event) { ListEventListener list listeners.get(eventType); if (list ! null) { for (EventListener listener : list) { try { listener.onEvent(event); } catch (Exception e) { // 防止一个监听器的异常影响其他监听器 LoggerFactory.getLogger(EventBus.class).error(“事件监听器处理异常”, e); } } } } }第五步在智能体中使用在智能体初始化时建立事件总线并注册监听器。public class TraeAgent { private EventBus eventBus; private AgentExecutionEngine executionEngine; public void init() { eventBus new EventBus(); // 注册监听器 eventBus.subscribe(“TOOL_INVOKED”, new LoggingEventListener()); eventBus.subscribe(“STATE_CHANGED”, new LoggingEventListener()); eventBus.subscribe(“TOOL_INVOKED”, new MetricsEventListener(metricsRegistry)); // 可以订阅所有事件用于调试 // eventBus.subscribe(“*”, new DebugEventListener()); executionEngine new AgentExecutionEngine(); } public String runTask(String tool, String input) { // 发布任务开始事件... eventBus.publish(new TaskStartedEvent(“AgentCore”, tool, input)); long start System.currentTimeMillis(); String result executionEngine.executeTask(tool, input); long duration System.currentTimeMillis() - start; // 发布工具调用事件 eventBus.publish(new ToolInvokedEvent(“ExecutionEngine”, tool, input, result, duration)); // 发布任务结束事件... return result; } }实操心得与避坑指南异步事件处理上面的publish方法是同步的会阻塞发布者线程直到所有监听器处理完毕。如果监听器处理耗时如写数据库、发网络请求会严重影响主流程性能。务必将其改为异步。可以使用一个单线程或多线程的ExecutorService来提交监听任务。事件顺序保证改为异步后事件的发布顺序和监听器的执行顺序可能无法保证。如果业务对顺序有严格要求如状态变更事件需要额外处理比如使用单线程的队列消费者或者给事件加上序列号。避免内存泄漏监听器如果持有对发布者或其他大对象的引用并且没有正确取消订阅可能导致无法被垃圾回收。在组件销毁时如Servlet的destroy方法记得调用unsubscribe。事件泛滥不要事无巨细都发布事件。只发布真正有多个消费者关心的、重要的状态变化或业务里程碑。过度使用事件总线会使系统流程难以跟踪和调试。4. 状态模式与责任链模式在决策流中的应用智能体的“大脑”——决策模块是逻辑最复杂的地方。状态模式和责任链模式能在这里大显身手。4.1 状态模式管理智能体的生命周期假设我们的智能体有IDLE空闲、THINKING思考决策、ACTING执行动作、ERROR错误四个状态。不好的实现标志位switchpublic class BadAgent { private String state “IDLE”; public void handleEvent(String event) { switch (state) { case “IDLE”: if (“start”.equals(event)) { state “THINKING”; startThinking(); } break; case “THINKING”: if (“decision_made”.equals(event)) { state “ACTING”; startActing(); } else if (“error”.equals(event)) { state “ERROR”; enterErrorState(); } break; case “ACTING”: // ... 更多的if-else break; case “ERROR”: // ... break; } } // ... 各种状态下的方法 }这段代码的维护噩梦在于状态转移逻辑散落在巨大的switch或if-else中添加一个新状态需要修改所有相关case每个状态下的行为也和状态机代码混在一起。使用状态模式重构第一步定义状态接口public interface AgentState { /** * 状态名称 */ String getName(); /** * 处理事件并返回下一个状态可能还是自己 */ AgentState handleEvent(AgentContext context, String event); }第二步实现具体状态类每个状态类只关心自己状态下的行为和可能的状态转移。public class IdleState implements AgentState { Override public String getName() { return “IDLE”; } Override public AgentState handleEvent(AgentContext context, String event) { if (“start”.equals(event)) { System.out.println(“[IDLE] 收到开始指令进入思考状态。”); context.setCurrentTask(event.getTask()); // 执行一些进入THINKING状态的预处理... return new ThinkingState(); // 转移到思考状态 } // 其他事件在当前状态下不处理或处理了但状态不变 System.out.println(“[IDLE] 忽略事件: ” event); return this; // 保持空闲状态 } } public class ThinkingState implements AgentState { Override public String getName() { return “THINKING”; } Override public AgentState handleEvent(AgentContext context, String event) { if (“decision_made”.equals(event)) { System.out.println(“[THINKING] 决策已做出开始执行。”); // 可能调用决策引擎将决策结果存入context context.setDecision(event.getDecision()); return new ActingState(); // 转移到执行状态 } else if (“error”.equals(event)) { System.out.println(“[THINKING] 思考过程出错。”); context.setLastError(event.getError()); return new ErrorState(); // 转移到错误状态 } else if (“cancel”.equals(event)) { System.out.println(“[THINKING] 任务被取消回到空闲状态。”); return new IdleState(); } return this; } } // ActingState 和 ErrorState 类似实现第三步定义上下文Context上下文持有当前状态并将事件委托给当前状态处理。public class AgentContext { private AgentState currentState; private String currentTask; private Object decision; private String lastError; // ... 其他上下文信息 public AgentContext() { this.currentState new IdleState(); // 初始状态 } public void handleEvent(String event) { // 委托给当前状态处理 AgentState nextState this.currentState.handleEvent(this, event); if (nextState ! this.currentState) { System.out.println(“状态转移: ” this.currentState.getName() ” - ” nextState.getName()); this.currentState nextState; } } // getters and setters ... }使用方式AgentContext agent new AgentContext(); agent.handleEvent(“start”); // 输出: [IDLE] 收到开始指令进入思考状态。 状态转移: IDLE - THINKING agent.handleEvent(“decision_made”); // 输出: [THINKING] 决策已做出开始执行。 状态转移: THINKING - ACTING agent.handleEvent(“error”); // 在ACTING状态下处理error事件...模式带来的好处清晰性每个状态的行为被封装在独立的类中代码内聚易于理解。可维护性添加新状态只需新增一个类修改某个状态的行为只需改一个类符合开闭原则。可测试性每个状态类可以独立进行单元测试。4.2 责任链模式构建可插拔的决策过滤器智能体的决策过程可能需要经过多个环节的校验或处理比如输入安全过滤、参数标准化、调用LLM获取初步决策、后处理格式化等。这些环节构成一个处理链。第一步定义处理器接口public interface DecisionHandler { /** * 设置下一个处理器 */ void setNext(DecisionHandler next); /** * 处理请求 * param context 决策上下文 * return 是否继续传递。true表示已处理完毕false表示传递给下一个处理器。 */ boolean handle(DecisionContext context); }第二步实现抽象基类可选简化代码public abstract class AbstractDecisionHandler implements DecisionHandler { protected DecisionHandler next; Override public void setNext(DecisionHandler next) { this.next next; } /** * 传递给下一个处理器 */ protected boolean passToNext(DecisionContext context) { if (next ! null) { return next.handle(context); } // 链的末端默认返回true表示处理完成或未处理 return true; } }第三步实现具体处理器// 1. 输入安全处理器 public class SecurityHandler extends AbstractDecisionHandler { Override public boolean handle(DecisionContext context) { String userInput context.getRawInput(); if (userInput ! null userInput.contains(“script”)) { context.setError(“输入包含非法脚本!”); return true; // 发现安全问题终止链条不再向后传递 } System.out.println(“[SecurityHandler] 安全检查通过。”); return passToNext(context); // 安全传递给下一个 } } // 2. 参数标准化处理器 public class NormalizationHandler extends AbstractDecisionHandler { Override public boolean handle(DecisionContext context) { String input context.getRawInput(); if (input ! null) { context.setNormalizedInput(input.trim().toLowerCase()); } System.out.println(“[NormalizationHandler] 参数已标准化。”); return passToNext(context); } } // 3. 核心LLM调用处理器 public class LLMHandler extends AbstractDecisionHandler { private LLMClient llmClient; public LLMHandler(LLMClient client) { this.llmClient client; } Override public boolean handle(DecisionContext context) { try { String prompt “基于以下输入做出决策: ” context.getNormalizedInput(); String llmResponse llmClient.complete(prompt); context.setLlmRawResponse(llmResponse); System.out.println(“[LLMHandler] 已调用LLM获得响应。”); } catch (Exception e) { context.setError(“LLM调用失败: ” e.getMessage()); return true; // 出错终止 } return passToNext(context); } } // 4. 响应后处理处理器 public class PostProcessHandler extends AbstractDecisionHandler { Override public boolean handle(DecisionContext context) { String rawResponse context.getLlmRawResponse(); if (rawResponse ! null) { // 假设我们提取JSON部分 String finalDecision extractJsonFromResponse(rawResponse); context.setFinalDecision(finalDecision); System.out.println(“[PostProcessHandler] 响应后处理完成。”); } return passToNext(context); // 通常是链条的最后一环 } }第四步组装责任链并使用public class DecisionChainBuilder { public static DecisionHandler buildChain() { // 创建处理器 SecurityHandler security new SecurityHandler(); NormalizationHandler normalize new NormalizationHandler(); LLMHandler llm new LLMHandler(new LLMClient()); PostProcessHandler postProcess new PostProcessHandler(); // 组装链条security - normalize - llm - postProcess security.setNext(normalize); normalize.setNext(llm); llm.setNext(postProcess); return security; // 返回链头 } } // 使用 public class DecisionEngine { private DecisionHandler decisionChain; public DecisionEngine() { this.decisionChain DecisionChainBuilder.buildChain(); } public DecisionResult makeDecision(String userInput) { DecisionContext context new DecisionContext(); context.setRawInput(userInput); // 从链头开始执行 decisionChain.handle(context); if (context.getError() ! null) { return DecisionResult.error(context.getError()); } return DecisionResult.success(context.getFinalDecision()); } }模式带来的好处与进阶技巧灵活配置你可以轻松调整链条的顺序或者动态增删处理器。例如在调试阶段你可以在LLMHandler后面插入一个LoggingHandler来记录请求和响应。单一职责每个处理器只做一件事代码清晰易于测试。开闭原则要增加新的处理逻辑比如一个CacheHandler用于缓存重复决策只需新建一个处理器类并在构建链时插入合适的位置无需修改任何现有处理器代码。链的终止注意handle方法的返回值设计。这里我们设计为true表示“已处理完毕链应终止”false或调用passToNext表示继续传递。SecurityHandler在发现威胁时返回true有效阻止了后续处理。与模板方法结合AbstractDecisionHandler中的passToNext方法已经是一个简单的模板。你可以进一步定义doHandle抽象方法让子类实现而在handle方法中加入统一的日志、性能监控等逻辑这就是模板方法模式的典型应用。5. 其他模式的点睛之笔与综合应用除了上述核心模式在Trae-Agent的其他角落一些模式也以简洁有力的方式解决了特定问题。5.1 单例模式管理全局配置与共享资源智能体需要访问全局配置如API密钥、超时设置、共享的资源池如数据库连接池、HTTP客户端池、线程池。这些资源通常只需要一个实例。public class AgentConfig { private static volatile AgentConfig instance; private Properties properties; private AgentConfig() { // 私有构造器防止外部new loadConfig(); } public static AgentConfig getInstance() { if (instance null) { synchronized (AgentConfig.class) { if (instance null) { instance new AgentConfig(); } } } return instance; } private void loadConfig() { properties new Properties(); try (InputStream is getClass().getClassLoader().getResourceAsStream(“agent.properties”)) { properties.load(is); } catch (IOException e) { throw new RuntimeException(“Failed to load config”, e); } } public String getApiKey(String service) { return properties.getProperty(service “.api.key”); } // ... 其他getter方法 }使用方式String key AgentConfig.getInstance().getApiKey(“openai”);注意单例模式的争议。在现代开发中尤其是依赖注入DI框架如Spring普及后单例模式常常被框架管理的单例Bean所取代。它的主要问题是不利于测试因为硬编码的静态调用很难被Mock。在Trae-Agent中如果规模较小或框架不复杂使用经典单例模式是简单直接的。如果项目复杂强烈建议使用DI容器来管理这些全局依赖。5.2 建造者模式构造复杂的智能体配置对象一个智能体的初始化可能需要一大堆参数名称、模型类型、温度系数、最大令牌数、系统提示词、工具列表、回调地址等等。使用构造器或setter方法会非常冗长且容易出错。public class AgentConfiguration { private final String name; private final String model; private final double temperature; private final int maxTokens; private final ListTool tools; private final String systemPrompt; // ... 更多字段 // 私有构造器强制使用建造者 private AgentConfiguration(Builder builder) { this.name builder.name; this.model builder.model; this.temperature builder.temperature; this.maxTokens builder.maxTokens; this.tools builder.tools; this.systemPrompt builder.systemPrompt; } // 静态内部类 Builder public static class Builder { private String name; private String model “gpt-3.5-turbo”; // 默认值 private double temperature 0.7; private int maxTokens 1000; private ListTool tools new ArrayList(); private String systemPrompt “You are a helpful assistant.”; public Builder(String name) { this.name name; } public Builder model(String model) { this.model model; return this; } public Builder temperature(double temp) { this.temperature temp; return this; } public Builder maxTokens(int tokens) { this.maxTokens tokens; return this; } public Builder addTool(Tool tool) { this.tools.add(tool); return this; } public Builder systemPrompt(String prompt) { this.systemPrompt prompt; return this; } public AgentConfiguration build() { // 可以在此处进行参数校验 if (temperature 0 || temperature 2) { throw new IllegalArgumentException(“Temperature must be between 0 and 2”); } return new AgentConfiguration(this); } } // ... getters }使用方式AgentConfiguration config new AgentConfiguration.Builder(“MyTraderAgent”) .model(“gpt-4”) .temperature(0.2) // 更低温度输出更确定 .maxTokens(2000) .addTool(new StockQueryTool()) .addTool(new NewsFetchTool()) .systemPrompt(“你是一个专业的量化交易分析助手回答必须基于数据保持客观谨慎。”) .build();这种方式代码可读性极强并且能保证配置对象在构建完成后是不可变的final字段线程安全。5.3 组合模式构建层级化的技能或任务树如果智能体的能力可以组织成树形结构比如一个“文档处理”技能下包含“文本提取”、“摘要生成”、“翻译”等子技能组合模式就非常适用。它允许你以统一的方式处理单个对象和对象组合。// 组件接口 public interface SkillComponent { String getName(); String execute(String input); } // 叶子节点基础技能 public class BasicSkill implements SkillComponent { private String name; private Tool tool; // 关联一个工具 // ... 构造器、getters Override public String execute(String input) { return tool.execute(input); } } // 复合节点技能组 public class SkillComposite implements SkillComponent { private String name; private ListSkillComponent children new ArrayList(); public void add(SkillComponent component) { children.add(component); } public void remove(SkillComponent component) { children.remove(component); } Override public String getName() { return name; } Override public String execute(String input) { // 复合技能的执行逻辑可能是顺序执行所有子技能也可能是选择其中一个 // 这里示例顺序执行并将结果合并 StringBuilder result new StringBuilder(); for (SkillComponent child : children) { result.append(child.getName()).append(“: “).append(child.execute(input)).append(“\n”); } return result.toString(); } }使用方式你可以构建一个复杂的技能树然后对根节点调用execute它会递归地调用整个树。这对于实现“宏技能”或“工作流”非常有用。6. 模式应用的常见陷阱与性能考量在实际项目中应用设计模式如果使用不当反而会引入新的复杂度。下面是一些我踩过的坑和总结的经验。6.1 过度设计模式泛滥这是新手最容易犯的错误。看到一点if-else就想用策略模式看到几个属性就想用建造者。记住模式是手段不是目的。在Trae-Agent初期我曾为每个简单的工具都套上完整的策略工厂模式后来发现很多工具只用一次且逻辑简单直接内联反而更清晰。判断标准如果未来三个月内这个模块有超过一次变更的可能性并且变更点明确如新增类型、修改行为那么引入模式是划算的。否则先用最简单的实现等变化真的发生时再重构。6.2 抽象泄漏工厂与具体类的耦合在工具工厂的例子中我们使用了Class.forName或映射表。这里有一个隐藏的耦合工厂需要知道所有具体工具类的全限定名。当工具实现分散在不同模块或JAR包时注册会成为问题。解决方案使用配置文件将工具名类全名的映射写在配置文件中工厂启动时读取。使用SPI机制在META-INF/services目录下提供接口文件让Java ServiceLoader自动发现实现类。这是更优雅的解耦方式。依赖注入在Spring等框架中你可以将所有的Tool实现类都注入到一个MapString, Tool中键就是工具名工厂直接从这个Map里取。6.3 观察者模式的内存与性能陷阱同步阻塞如前所述同步事件发布是性能杀手。务必改为异步。可以使用一个ExecutorService甚至引入更成熟的消息队列如Disruptor、RabbitMQ来处理高吞吐场景。事件风暴如果事件发布过于频繁且观察者处理较慢会导致事件积压。需要监控事件总线的队列长度并考虑对事件进行合并如一段时间内的同类型状态变更只发布最后一次或采样。循环引用与内存泄漏如果观察者如一个UI组件直接引用了发布者如智能体核心并且没有正确取消订阅当UI组件销毁时由于仍被事件总线引用导致无法GC。务必在组件生命周期结束时取消订阅。6.4 状态模式的上下文膨胀AgentContext类很容易变成一个“上帝对象”里面塞满了所有状态类可能需要的字段。这违反了单一职责原则也让上下文变得难以维护。改善方法将上下文按功能拆分如ToolExecutionContext、DecisionMakingContext、UserSessionContext等状态类只注入它需要的那个上下文。使用参数传递在handleEvent方法中直接传递所需的数据而不是让状态类去上下文中抓取。6.5 责任链模式的调试困难当链条很长时如果一个请求没有达到预期结果很难一眼看出是哪个处理器出了问题或者链条是否被意外终止。调试技巧添加链路ID和日志在请求进入链时生成一个唯一ID并穿透所有处理器每个处理器都使用该ID记录日志。可视化链条可以写一个方法打印出当前责任链的处理器顺序。使用“调试处理器”在需要调试时在链条中插入一个DebugHandler它打印出入参和出参或者将上下文信息暂存起来供检查。设计模式是优秀工程师的通用语言和工具箱。在Trae-Agent这样的复杂智能体系统中恰当地运用它们就像给一座大厦搭好了坚固而灵活的钢结构。它不会让你的代码立刻变得高大上但会让它能从容应对未来的需求变化和规模增长。最关键的是要理解每个模式解决的核心问题是什么然后审视你自己的代码看是否遇到了同样的问题。如果是再优雅地引入它。记住最好的代码不是用了最多模式的代码而是最能平衡当下清晰度与未来扩展性的代码。在Trae-Agent的迭代过程中我也是先写出能跑的“烂代码”然后在它让我感到疼痛修改困难、bug频出时再运用模式去重构它这个过程本身就是对设计模式最深刻的学习。