Tina 小姐姐前阵子我把 Moltbot（内部早期代号 Clawdbot）这套系统做了一次完整的架构梳理。很多项目做久了都会有这个问题：功能一直在加，代码一直在补，但你很难用一句话说清楚“它到底是怎么工作的”。Moltbot 是个偏自动化的智能体运行时，核心目标不是把大模型封装得多聪明，而是把模型决策、工具调用、任务状态、人工介入这些环节稳定地串起来。这篇内容不是产品介绍，而是一份架构分析的复盘，重点拆解事件驱动内核怎么取代早期的超级大循环、工具连接器怎么抽象、跨会话任务状态怎么持久化，以及为什么可观测性在 Agent 系统里比传统后端更关键。适合正在做智能体平台、自动化工作流或者类 Agent 框架的开发者参考，同样也适合架构设计岗的朋友当案例看。
整个架构并不是一开始就长这样。Clawdbot 时代它更像一把乱抓的“爪子”，业务需要什么工具就硬接什么工具，调用链到处飞。后来改名为 Moltbot，本质是一次内核级重构。下面我按一次架构分析报告的思路，从背景、分层、事件机制、连接器、持久化、可观测性几个维度逐步拆开讲。
1. 项目背景与架构目标：先搞清楚 Moltbot 到底在避免什么
Moltbot 最初不叫这个名字，团队里叫 Clawdbot。它面向的是一类很具体的需求：把“人来按顺序执行一堆脚本和 API 调用”变成“Agent 根据目标自动规划并执行”。打个比方，日常工作中经常有这种流程——查监控数据、定位异常、调接口下线服务、发通知。传统做法是每次手动登录机器跑命令，或者写一个死板的定时脚本。Clawdbot 想做的事情，就是让人用自然语言描述目标，由系统自行决定调用哪些工具、按什么顺序执行、失败怎么重试、中间要不要问人。
这类系统的最大痛点不在模型，而在工程。模型负责生成调用意图，但调用可能失败、参数可能是错的、工具可能比预期慢、任务可能跨好几个小时。这些都需要一套可靠的运行架构兜底。
1.1 从 Clawdbot 到 Moltbot：改名背后的架构分水岭
Clawdbot 这个名字其实很形象，claw 代表“爪子”，暗示这系统要能抓住各种各样的工具。早期版本做得比较粗糙，代码里一个 run 函数从早跑到晚，遇到工具调用就直接等待结果。后来做了一次比较大的架构重构，顺手把项目代号换成了 Moltbot，Molt 有“蜕皮、转变”的意思，想表达的是内核换掉了，不再靠蛮力跑任务。
这次重组的核心差异有三个。第一，执行逻辑从“大循环”变成了“事件驱动状态机”；第二，工具接入从“硬编码函数”变成了“连接器协议”；第三，任务状态从“内存变量”变成了“持久化的事件日志”。这三个变化不是赶时髦，而是被线上问题逼出来的。
早期 Clawdbot 跑一个长任务时经常出问题：用户等了一个多小时，结果中间某个工具超时，整个任务状态卡在内存里，服务一重启全没了。工具越来越多了之后，新增一个工具往往要改主流程代码，风险极高。最让人难受的是，当任务需要等待人工审批时，整个执行线程就占着不动，占着数据库连接，占着运行资源。这些场景用传统的同步编码思路很难优雅解决，必须把“任务进行到哪一步”和“这一步结果的触发条件”解耦开。
1.2 架构目标不是功能列表，而是一组可靠性约束
复盘的时候我们给 Moltbot 定了六个架构目标，现在看仍然很关键：
- 任何单一工具失败不能拖垮整个任务。
- 任务状态必须可恢复，进程崩溃后能接着跑。
- 新工具接入不需要改动内核核心代码。
- 执行过程中的任何一次决策，都要能追溯当时输入输出。
- 支持人工在关键节点介入，而不是永远全自动。
- 同一个模型内核可以换，甚至未来支持多个模型协同。
这六条基本决定了后面的架构形态。比如“任何单一工具失败不能拖垮任务”这一条，就要求每个工具调用必须独立隔离，超时、重试、错误处理都要收缩在连接器层。再比如“任务状态必须可恢复”，这直接否定了“用一个长长循环推进任务”的方案，因为大循环意味着状态要么存在局部变量里，要么存在数据库临时表里，恢复逻辑非常难写。顺着这些约束推导，事件驱动和状态机几乎是必然选择。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 架构全景：五层一总线的具体划分
Moltbot 当前版本的结构可以用“五层一总线”来概括。从下往上分别是：接入层、内核控制层、任务编排层、工具连接器层、能力提供层。中间横跨的是一条事件总线。很多文章喜欢画复杂的三维架构图，但落地时最常用的反而是这种能直接映射到代码模块的分层。
2.1 接入层与控制层怎么分工
接入层负责处理外部交互入口，包括 WebSocket 会话、Webhook 回调、控制台指令。这一层只做协议转换，把不同入口的输入统一转成内部事件。控制层是 Moltbot 的内核，包含事件分发、模型推理封装、状态机迁移逻辑。控制层不关心具体业务工具，只关心“用户想达成什么目标”和“当前该执行什么动作”。
为什么要单独拆接入层？因为 Agent 系统的输入源越来越多。最开始只有对话框，后来加上了定时触发、事件订阅、外部系统 webhook。如果接入逻辑和执行逻辑耦合在一起，每多一个入口就要动一遍核心流程。现在所有入口全部转成内部统一事件后，新增入口的成本只剩一个转换器。
2.2 编排层和连接器层的职责边界
很多人会把编排逻辑写在内核里，然后让内核直接调用工具函数，Moltbot 早期也是这么干的，结果非常痛苦。现在的处理方式是：内核只负责产生意图并发出执行事件，真正的任务编排由编排层负责。
编排层维护任务的有向图或者状态机实例，它知道一个复杂目标需要拆成哪些子步骤，哪些步骤可以并行，哪一步必须等上一步的结果。连接器层做的事情更单纯——把一份“工具调用请求”翻译成具体系统能执行的命令或 API 请求。用一个例子解释：编排层决定“先检查服务状态，再决定是否发布”，连接器层只负责执行“调用健康检查接口”，并返回成功或失败。
这样分下来，内核层几乎不感知具体工具语义，模型换掉也不会影响整个系统。执行层也不感知模型参数，换工具时内核不用改。
2.3 架构层面的“微服务克制”
这套架构并没有拆成大量独立微服务，原因是 Moltbot 的并发模型偏向“任务级并行”，而不是“请求级高并发”。如果一个 Agent 系统按微服务拆得特别碎，每个工具一个服务，然后通过 RPC 或者 REST 调用，链路会非常长，状态传递会非常复杂。对实时交互类 Agent 来说，几十毫秒的链路开销是能感知的。
所以 Moltbot 的实际部署是一个主进程加多个独立连接器进程。主进程负责内核、编排和状态，连接器进程负责执行具体的外部调用。这样做既保留了模块边界，又避免了进程间高频通信。连接器如果任务很重可以单独扩容，比如浏览器自动化连接器就在独立进程里跑。
3. 事件内核：从 Clawdbot 时代的“超级大循环”到 Moltbot 状态机
Moltbot 架构里最核心的变化就是内核执行模型。这个部分值得单独拿出来讲，因为它是整个系统从“能跑”到“能稳定跑”的分水岭。
3.1 Clawdbot 时代的超级大循环问题
Clawdbot 早期实现是一个典型的大循环伪代码：
python复制while True:
message = receive_message() # 等用户输入
plan = llm_plan(message) # 让模型做规划
for step in plan:
result = execute_tool(step) # 执行计划里的每一步
observation = llm_observe(result) # 观察结果并决定下一步
reply = llm_generate(observation)
send_message(reply)
这个模型写 Demo 特别快，看起来逻辑也通顺。但上线后就发现几个致命问题。
第一，整个任务就是一个阻塞式循环。如果任务里有一个工具需要人工审批，这个循环就彻底卡住，而卡住的 thread 还要继续持有内存、数据库连接和日志句柄。跑长任务的进程长年累月不退出，运维非常痛苦。
第二，任务状态全散落在变量里。比如 plan 是局部变量、execution_step 是循环遍历索引，这些状态进程一崩就没了。更麻烦的是，如果中间用户突然插进来一句“改一下目标”，这个大循环根本响应不了，因为它正忙于等待上次工具结果。
第三，事件来源太单一。它只允许“用户输入”驱动流程，没办法自然接入定时器、外部系统状态变更触发这类机制。想加一个“每 5 分钟自动巡检”的能力，就得再造一套调度系统，与主循环并行跑，最后状态冲突一堆。
3.2 Moltbot 的状态机与事件驱动模型
重构后，Moltbot 不再有大循环，取而代之的是一个事件循环加状态机集合。任务被抽象成有限状态机的实例，每个状态机只关心自己受理的事件。核心事件集合类似这样：
UserMessageReceived：用户输入了新的消息。ModelPlanningFinished：模型产出下一批工具调用计划。ToolCallRequested：编排层请求执行某个工具。ToolCallSucceeded或ToolCallFailed：工具执行完成。HumanApprovalRequired：流程需要人工审批。HumanDecisionMade：人工给出审批结论。TaskTimeout：子步骤超时。
状态机的迁移变成了事件分发时自动触发。上面思路用代码表示大概是：
python复制class AgentTaskStateMachine:
def __init__(self, task_id):
self.task_id = task_id
self.state = "idle"
def handle(self, event):
if event.type == "UserMessageReceived":
self.state = "planning"
kernel.request_model_plan(event.message)
elif event.type == "ModelPlanningFinished":
self.state = "executing"
orchestrator.dispatch_steps(event.plan)
elif event.type == "ToolCallSucceeded":
self.state = "deciding"
kernel.explain_tool_result(event.result)
elif event.type == "HumanDecisionMade":
self.state = "executing"
orchestrator.resume_step(event.decision)
这看起来比大循环简单，但真实的架构里每个状态机实例是独立注册到事件总线的，事件循环拿到消息后按 task_id 找到对应状态机，调用它的 handle 方法。状态机迁移完成后返回需要产生的下一批事件，再交给调度器继续分发。这种“事件进来 -> 状态迁移 -> 产出新事件”的模式，可以完美支撑异步、长耗时和人工介入。
3.3 为什么事件驱动比线程阻塞更适合 Agent 场景
Agent 任务天然是异步的。模型推理需要两三秒，工具调用可能需要几十秒甚至几分钟，中间还可能要等人工审批。如果每个任务占一个线程去阻塞等待，在 Kanban 上一目了然：任务一多，资源全被“等”耗光了。
事件驱动相当于把所有“等待”都变成了状态。等待工具返回时，任务状态停在 executing_tool，但它的关联资源几乎不占用，下次工具结果回来时通过事件重新唤起它。这样就支持上万任务实例同时挂在系统里，真正占资源的只包括事件消息、状态机对象和少量临时上下文。
另一个巨大的优势是重试和恢复逻辑很自然。一个工具失败后，状态机会收到 ToolCallFailed 事件，它可以选择重试当前步骤、跳过步骤、终止任务，或者转人工审批。每一种选择都是状态迁移的一种路径，而不是代码里一堆散落的 if 分支。
3.4 从“超级大循环”到事件驱动的迁移过程
迁移不是把代码重写一遍就完事，最麻烦的是把旧任务迁到新架构。当时我们做了一套兼容层，旧任务在启动时被包装成一个“异步恢复任务”，它的每一步都转成持久化事件再走新链路。
当时还定了一个原则：任何需要被长期追踪的执行单元，都不能直接挂在函数调用栈里。如果一个执行过程超过 30 秒，它的推进必须依赖持久化事件或数据库状态。这个原则后来成了代码 review 的铁律，执行链路上禁止出现“超过几秒的同步等待逻辑”。
4. 连接器层：工具不是插件，是“爪子”契约
Agent 系统最终要落地到“能干活”，干的活来自工具。Moltbot 里“工具”这个概念比很多人理解的要大，它不只指大模型能看到的 function 列表，还包括背后一整条执行链路。
4.1 工具描述的规范：先想想“模型需要看到什么”
大模型要正确调用工具，必须有一份清晰、准确、精简的说明。Moltbot 早期犯过一个典型错误：把工具描述写得很长，希望模型充分理解每一个参数，结果反而导致模型乱填参数。后来的准则是：描述里只说“这个工具帮你做什么”和“关键参数怎么填”，不要写实现细节。
一份工具描述用 JSON Schema 表达，下面是一个例子：
json复制{
"name": "restart_service",
"description": "重启指定环境下的服务，执行前会检查服务当前状态，如果服务不在运行则不执行重启",
"parameters": {
"type": "object",
"properties": {
"environment": {
"type": "string",
"enum": ["staging", "production"],
"description": "目标环境"
},
"service_name": {
"type": "string",
"description": "服务名，例如 api-gateway"
},
"force": {
"type": "boolean",
"default": false,
"description": "只有首次重启失败时允许置为 true"
}
},
"required": ["environment", "service_name"]
}
}
再往下是连接器，必须自己执行鉴权、超时、重试和错误解析。
4.2 连接器接口拆到什么程度才合适
连接器层拆得好不好，直接决定后续新增工具的效率。Moltbot 现在的连接器接口收敛成四个方法，非常小：
validate(request)：在真正执行前校验参数是否合法。execute(request)：执行具体操作。cancel(session_id)：取消执行中的任务。status(session_id)：查询异步操作的状态。
为什么需要的额外方法这么少？因为同步操作直接在 execute 返回，异步操作则先返回一个 session_id，后续通过 status 轮询或者事件回调获取最终结果。这样不管是调用 HTTP API、执行 SSH 命令、操作数据库，还是控制浏览器自动化，都能统一成同一套抽象。
很多项目会犯一个毛病——为了让连接器适配所有场景，把接口设计得特别重，动不动就十几个方法，新写一个连接器要被文档淹死。Moltbot 的经验是，宁可让连接器内部复杂一些，也要对外暴露的契约极小。
4.3 超时、重试与副作用：这层必须防呆
工具调用最大的坑是副作用不可控。举例，“删除一个云主机”和“读取一段日志”的语义风险完全不同。Moltbot 在连接器层做了“危险度”分级，并配合特殊机制。
高危险操作在调用前必须由用户再次确认，或者在工具描述里就要求模型提供双击确认参数。这实际是向模型传递一个显式约束：你调用时如果没确认就不能传 dangerous 确认字段。再叠加人工审批节点，能极大降低事故率。
超时处理也需要跨连接器统一。我们给每个连接器配置了默认超时时间，HTTP 类调用默认 30 秒，但文件传输类调用可以到 10 分钟。超时触发后连接器必须返回一个可识别的失败原因，而不是把整个进程卡死。重试逻辑只在连接器内部进行，最多 3 次，指数退避。内核层不允许做无脑重试，因为有些工具调用本身是幂等的，有些不是。如果连接器自己最清楚工具是否幂等，那重试策略就应该封装在连接器里。
4.4 连接器注册与模型字面量的同步问题
一个新连接器接入 Moltbot 后，必须把它的工具列表同步给模型。以前这里经常出现“模型看到的工具和系统里能执行的不一致”，比如模型已经调用了下线接口，但实际连接器已经被摘掉，直接导致失败。
Moltbot 的做法是做一个工具注册中心。连接器启动后向注册中心上报自己提供的工具列表，注册中心统一生成模型 API 使用的 tools 参数。每次模型请求发出前会基于订单实时算一遍可调用工具列表，保证模型看到的一定是注册中心里健康状态正常、版本匹配的工具。这其实是一个很细的工程点，但在生产环境真的能救命。
5. 跨会话状态与任务恢复：长任务不丢上下文的底气
前面说得再漂亮，如果任务状态不能持久化，一旦进程重启，事件驱动也白搭。Moltbot 架构里状态的持久化策略经过了几轮调整，现在比较稳定。
5.1 内存状态、最终状态与事件日志的分层
我们现在把状态分成三层：
- 瞬时状态：模型上下文、面板临时消息、等待窗口的缓冲区，只存在内存里。
- 任务业务状态：当前阶段、已完成的步骤、等待人工处理的事项，存在关系数据库，每次状态迁移都同步更新。
- 全量事件日志：每一条进入系统的重要事件都追加到事件表，用于排查、回溯和重放。
为什么需要全量事件日志？因为很多 Agent 问题没法靠当前状态解释。比如“为什么昨天这个任务没执行成功”，只看业务状态表未必能还原当时的决策链路。事件日志记录的是当时模型看到什么、选择了什么工具、工具返回什么异常，这些是审计和调试的关键。在需要重做某一步时，也可以基于事件日志做一个较短周期的时空穿越。
5.2 持久化设计里最容易翻车的点
Agent 任务状态频繁更新，如果每步都写数据库且事务范围过大，性能会很差。这里有几个实操经验。
第一，状态表不能设计成“只有一行最新状态”加一个超大 JSON。因为你永远不知道后续要按什么维度排查问题。最好拆成 task 表存基本信息，task_step 表存子步骤状态，event_log 表存事件流水，必要时 tool_call 表存每次工具调用的参数和结果。
第二，写库要异步批量化。工具执行结果回到状态机后，先把状态更新丢到一个队列里，由 writer 批量写入。但关键状态比如“任务已取消”必须同步持久化后再回复用户，避免异步丢失造成误反馈。
第三，事件日志统一用 message envelope。每条事件至少要包含 event_id、task_id、occurred_at、event_type、payload 和 trace_id。没有 trace_id 的事件日志在排查关联场景时价值为零。
5.3 任务崩溃后的恢复链路
Moltbot 崩溃恢复的流程大概是这样：进程启动后，先从数据库查最后一个持久化稳定点。对于正在执行工具的任务，状态是 executing_tool，并有对应的 tool_call_id。恢复时会先问连接器执行结果到底返回没有，因为有可能数据库落后于真实执行结果。
这里涉及一个关键设计：工具执行必须返回一个稳定的台账标识。连接器每次执行一个操作，都生成 execution_id，并在任务表里记录。如果进程重启后不确定这个操作是否已完成，就通过连接器的 status(execution_id) 查询。如果已完成，直接把结果作为事件补录进状态机；如果连接器不可查，则按业务约定选择标记失败或继续等待。
所以说 Agent 系统的恢复不是“把内存里的东西再灌回来”，而是要把不确定的步骤重新确认一遍。这是一个需要业务来定的设计，无法完全自动化。
6. 运行时观测：Agent 架构里真正的“生产验证”
Moltbot 上线稳定运行一段时间后，我问过自己一个问题：如果现在出故障，我能在多少分钟内定位到根因？认真想了下，早期答案是非常尴尬的“要看运气”。后来补了可观测性体系，情况才明显改善。
6.1 Agent 链路追踪与传统后端追踪的差异
传统后端请求链路是相对确定的，一个请求会经过网关、服务 A、服务 B、数据库、缓存。但 Agent 系统不一样，同一个任务可能调用几次模型、执行哪些工具、走到哪一步需要人工介入，完全取决于运行时决策。你没法提前画出一棵标准的 Span 树，也不能靠固定埋点理解所有路径。
Moltbot 用三个维度的关联 ID 串起整个链路：
task_id：代表一次完整的用户目标执行。trace_id：每次请求模型或执行工具时生成的调用链 ID。plan_iteration_id：代表模型的一轮规划。
一次任务可以包含多轮 model plan，每轮 plan 里又有多个 tool calls。如果只靠 task_id 去查日志，查询结果会非常杂。只有把这三个 ID 同时打进日志和 trace，才能很快定位到“任务卡在哪一轮规划、哪个工具调用上”。
6.2 日志与事件的无缝连接
Moltbot 的日志规范很严格：所有结构化日志必须携带 task_id、plan_iteration_id、event_type。不能用任何一套完整的事件状态来代替日志，因为事件是业务语义，日志是系统记录，两者并不是同一件事。
举个例子，当连接器发起 HTTP 请求时，业务层会打一条事件日志，记录“准备调用外部系统”。连接器的 HTTP client 会再打一条底层日志，包含完整 URL、状态码、耗时。这种情况下，通过事件日志判断业务走向，通过底层日志判断请求细节，两者通过同一个 execution_id 关联。
6.3 从监控指标反向改进架构
上线后我们监控的核心指标不是“任务成功率”这么笼统的东西，而是更细的四组指标。
- 连接器失败率与失败原因分布：超过 10% 失败就必须处理。
- 工具平均执行时长与 P99 时长：用来评估任务耗时的瓶颈。
- 状态机重试次数：重试太多往往代表工具异常或描述误导模型。
- 模型调用轮次：一次任务如果产生非常多的模型调用轮次，大概率是规划逻辑有问题，比如反复调整同一个步骤。
有一次我们发现某个特定场景下的重试率特别高，顺着 trace 排查后发现问题出在工具描述里对参数 force 的定义不够严格，模型频繁使用危险参数触发人工审批，审批人会拒绝，然后又回到模型重新规划。后来把描述改成“只有首次重启失败时才允许置为 true”，模型调用该参数的比例立刻下降，任务失败率也降了不少。
所以说可观测性对 Agent 架构而言不只是运维需求，它还会反向暴露产品设计层面的问题。
7. 复盘后我仍会调整的三个设计决策
每次架构分析报告最后，如果不给自己留几个待改进项，报告就失去参考价值。这里说三个我现在依然觉得有机会做得更好的地方。
第一，连接器协议还可以更薄，但配置化要更强。目前实现一个新连接器，仍然要写不少代码。如果能把参数定义、鉴权方式和调用方式全部用声明式配置表达，新工具接入的时间可以从一天压缩到几小时。后续计划是把连接器的骨架生成器做得更完善，让接入人员只需要填充业务调用即可。
第二，状态机的状态和事件定义需要版本化。协议还在演进，不同版本可能对同一个状态做了细微调整。现在我们是兼容新旧字段，但没有真正实现事件协议灰度。更理想的方式是事件携带 schema_version，并由注册中心统一管理版本，这样升级内核时不需要所有存量任务一次性兼容。
第三，人工介入的体验还不够“轻”。现在人工审批是一个独立页面或者独立消息节点，从用户体感上始终是打断式的。后续想做成“旁路监督”模式，让人可以随时看到任务在进行，能暂停、改指令、纠偏，而不是必须到审批点才跳出来。这需要架构进一步支持干预事件，本质上又是一个新的状态迁移路径。
Moltbot 的架构迭代过程给我最大的一个体会是：不要一开始就追求设计一个复杂的执行引擎，先把流程跑通，再把“状态混乱”和“卡死”这类真实痛点提炼成架构需求。事件驱动、连接器抽象、持久化设计、可观测性，这些不是纸面上的名词，它们全是被线上问题一个一个逼出来的解决方案。如果你也在做类似的 Agent 运行时或自动化编排系统，希望这份复盘能帮你少踩几个同样的坑。