ARTICLE · 1376067
翻完 LobeHub 的源码,我觉得 Super Agent 最难的不是多 Agent
MASON BUILDS / 源码拆解
一个 Agent 怎样接手事情、交给别人、等结果回来,然后不把现场搞乱。
图 1|一条未明确 @ Bot 的群消息,先进入 Wake 判断;只有允许唤醒的分支才会进入 Agent 运行。虚线表示不唤醒时停止处理。
文 / Mason Builds · 2026.11 · 对照 LobeHub 开源仓库 canary 分支
假设团队群里有人丢了一句:“导出接口慢得离谱,谁有空看下?”
没人 @ 机器人,也没有明确创建任务。如果群里恰好有一个负责工程问题的 Agent,它要不要接话?接话以后,是自己去看代码,还是找擅长性能的 Agent?如果测试需要五分钟,它还要一直挂着聊天请求吗?
这些事听上去像“让模型更聪明”就能解决。可真翻到 LobeHub 的源码,会发现大部分麻烦根本不在模型那里。
我最初是冲着它的 Group Orchestration 去的,想看 Supervisor 怎么安排其他 Agent。一路往下读,反而被几处很朴素的代码吸引住:它什么时候选择闭嘴、什么时候停止当前循环、什么时候允许一次工作接着上次继续。
这篇就从这些细节讲起。不是官方功能清单,也不把一张总览图当成架构分析。
01 / AGENT LOOP
先别急着叫 Worker,单 Agent 的循环得先站稳
最容易写出来的 Agent,差不多就是一个循环:问模型,拿工具调用,执行,再把结果发回去。十几行代码就能演示。
问题出在第二天。你给它加上多个工具并行、人工审批、用户取消、调用超时,原先那个循环会越来越像补丁大会。
LobeHub 在这里做了一个明确的拆分:负责“决定做什么”的组件,和负责“真的去做”的组件,不是同一个。前者在源码里能看到 GeneralChatAgent,后者是 AgentRuntime。
图 2|GeneralChatAgent 产生 AgentInstruction[],AgentRuntime.step() 选择 Executor 执行,并将结果写回 State;下一轮继续由 Brain 决策。
在 packages/agent-runtime/src/core/runtime.ts 里,step() 的关键动作很清楚:获取指令、选择 Executor、执行、更新 State。模型的意思需要先变成 call_llm、call_tool、request_human_approve 或 finish 这样的类型化指令。
这里真正有价值的,不是多加了一层抽象,而是把“模型想做什么”和“系统允许怎么做”隔开了。
当模型输出不可靠,甚至被外部内容诱导时,这条边界能让工具执行、审批与权限检查有一个确定的位置。它不自动解决所有安全问题,但至少不把安全寄托在模型会不会听话上。
02 / GROUP ORCHESTRATION
我以为 Supervisor 在思考,结果它主要在处理结果
多 Agent 部分最容易让人误会的是名字。GroupOrchestrationSupervisor 听起来像一个会深思熟虑的总指挥。实际打开类文件,它是个相当明确的状态机。
它拿到上一轮的 ExecutorResult,通过 decide() 返回下一条 SupervisorInstruction。如果上一次结果说的是“speak”,就执行指定 Agent;“broadcast”,就并行调度;“delegate”,就把控制权交出去;“finish”,就结束。
SOURCE SKETCH / TYPE SCRIPT
switch (decision) { case 'speak': return { type: 'call_agent', ... }; case 'broadcast': return { type: 'parallel_call_agents', ... }; case 'delegate': return { type: 'delegate', ... }; case 'finish': return { type: 'finish', ... }; }这段是按源码逻辑缩写的示意,不是可直接粘贴运行的完整实现。真正由模型决定策略的是上层的 Supervisor Agent,状态机负责把决策接成下一步执行。
图 3|上层 Supervisor Agent 产出策略,GroupOrchestrationSupervisor.decide() 确定下一项动作。speak、broadcast、delegate 与 finish 是不同出口,不代表默认并行。
这种分法有一个意外的好处:你可以单独测试“收到某种结果,下一步应该执行什么”,而不用每次都启动真实模型。
代码里还设置了轮次上限。客户端群组编排的默认 DEFAULT_MAX_ROUNDS 是 10。别小看这个常量。多 Agent 最常见的失败,不一定是完全不工作,也可能是彼此非常礼貌地讨论下去,最后花完预算。
03 / HANDOFF
一行 stop: true,解决的是交接顺序
继续翻 packages/builtin-tool-group-management/src/executor.ts,我遇到一个比“支持广播和委派”更值得说的细节。
Supervisor 发出 speak 时,工具并不立即在当前调用栈里塞进另一个 Agent。它先注册 registerAfterCompletion 回调,然后返回 stop: true。
SOURCE SKETCH / TYPE SCRIPT
ctx.registerAfterCompletion(() => ctx.groupOrchestration.triggerSpeak({ ... }) ); return { success: true, stop: true };这个动作的意思是:让我先把当前这轮收干净,再把活交给下一个 Agent。
为什么要多绕一下?想象 Supervisor 的工具消息还没提交,另一个 Agent 已经开始写新消息。如果两边更新同一条对话树,顺序、归属和前端显示都可能乱掉。
先结束当前运行,再进入下一个执行边界,不够酷,但很像真正写过异步系统的人会选择的办法。
图 4|Group Management 工具注册 afterCompletion 并返回 stop: true;当前 Operation 完成收尾后,才派发下一位 Agent。箭头按时间顺序排列。
04 / PAUSE & RESUME
任务暂停的时候,才看得出 Runtime 的成色
我认为这部分比多 Agent 本身更值得精读。
假设 Agent 要删改一批文件,操作需要人批准。另一种情况是它启动一个耗时的子 Agent,结果还没回来。两种场景看起来都叫“等待”,但后续执行方式完全不同。
图 5|waiting_for_human 会结束原 Operation 并在确认后以新 Operation 恢复;waiting_for_async_tool 保持同一 Operation;waiting_for_client 有客户端结果回传路径。
在 AgentState 中,LobeHub 分出了 waiting_for_human、waiting_for_async_tool、waiting_for_client。再看 AgentRuntimeCoordinator,会发现一个很耐人寻味的集合:
SOURCE SKETCH / TYPE SCRIPT
const STREAM_END_STATUSES = new Set([ 'done', 'error', 'interrupted', 'waiting_for_human', ]);waiting_for_async_tool 不在里面。
原因写在代码注释里:人工审批时,当前 Operation 的事件流可以结束,用户作出决定后通过新的 Operation 续跑;异步工具则可能在结果回填之后,继续同一个 Operation。如果把异步等待也算作“流已经结束”,前端就可能提前给任务画上句号。
这里还涉及步骤锁、执行权校验和持久化状态。服务端的 executeStep() 不是简单地调用一次模型就返回,而要确认这一步究竟归哪个 Worker 执行,以及谁有权保存最终结果。
因为任务队列会重试,服务进程会重启,网络会中断。一个执行了 20 秒的工具调用如果在第 19 秒断开,恢复时能不能避免重复改文件、重复发消息,比 prompt 写得多优雅重要得多。
05 / WAKE
为什么有时让 Agent 不说话,比让它说话更重要
现在回到开头那条群消息。谁都没有明确叫机器人。它凭什么决定插话?
LobeHub 在 conversationWake 里没有直接交给一个大模型决定一切。明确 @ 或回复 Bot,有快速路径;没有明确呼叫,再交给规则、会话状态和分类判断。
图 6|显式 @ 或回复 Bot 可走快捷唤醒;其他消息由规则与按需使用的 Classifier / Duty 判断。shadow 是记录策略结果的模式,不是额外的强制校验节点。
源码里可以看到两个不同的问题。一个是 “这句话是不是在对我说?”,对应 Classifier。另一个是 “没人叫我,但这是不是我应该管的事?”,对应 Duty Judge。
它们不能混成一个“消息相关性评分”。否则团队群里的“数据库又慢了”会被误判成有人向机器人下了命令,群聊很快就会变成一群 Bot 争相表态。
我还挺喜欢这里的 shadow 模式:策略可以先只记录判断,不实际决定是否唤醒。真正在群里部署之前,先看看它会误触发多少次,再考虑开启 enforce。
Classifier 里还有限时两秒的路径。更有意思的是,不同策略在超时后的退化结果并不一样,尤其不能把“没判断出来”无条件等同于“应该主动介入”。这其实是产品边界,不只是技术实现。
06 / TASK / OPERATION / STEP
Task 管的是工作,不是某次模型请求
聊天是一次交互,工作却可能持续几天。一个“每周检查性能问题”的目标,需要负责人、周期、历史运行结果和验收,而不是让某条 HTTP 请求一直活着。
这里要分清三个词:Task 是持续存在的工作;Operation 是某一次运行;Step 是这次运行里的一次推进。还有 Topic / Thread,保存相关对话与工作上下文。
图 7|一个 Task 可以按不同触发时间产生多个 Operation,各 Operation 有自己的 Step 和结束状态。日期与步骤数量只用于示意;Topic / Thread 表示可关联的上下文。
设备执行也不需要和模型挤在同一个进程。LobeHub 的 DeviceGateway 能把文件、Git、终端等操作路由给授权设备。云端负责规划和维护状态,真正动手的可以是本地机器。
上下文也不是一个巨大的“记忆箱”。ContextEngine 负责组织历史、记忆和项目相关信息;而 WorldSnapshot 是本次运行所依赖的稳定事实。它们不是必须前后串接的两道工序,而是从不同角度给 Runtime 提供运行所需的信息。
图 8|ContextEngine 组织上下文,WorldSnapshot 固定本轮事实,两者为不同的信息来源。需要使用设备工具时,请求经 DeviceGateway 授权才到达本地设备,结果沿另一通道返回。
几套机制凑起来,才让“帮我持续处理这个问题”不再等于“请你在一个聊天窗口里一直说话”。
07 / MY TAKEAWAY
看完以后,我反而不想先做多 Agent 了
如果从零做一个 Agent Harness,我会先把单 Agent 的执行现场管好:工具调用前有校验,调用后能关联结果;人工介入能暂停;任务中断后知道从哪一步恢复;重复投递不会让同一件事做两遍。
然后再接 Supervisor。等协作链路稳定了,才让 Agent 主动听群消息、判断职责、创建长期任务。顺序反过来,Demo 往往会很热闹,运维会更热闹。
真正的 Super Agent 不是“模型能安排多少个 Agent”,而是“一个不确定的决定,能不能被系统可靠地执行、暂停、追踪和收尾”。
当然,源码能证明这些边界在设计上存在,证明不了长时间自主任务的成功率,也不能直接得出唤醒准确率已经足够高。那些问题仍然要靠真实工作负载、失败样本和重复测试回答。
但有一点已经很清楚:LobeHub 值得研究的,恰好是那些不会出现在宣传首页的细节。















































































