夜雨聆风点击上方 前端Q，关注公众号
回复加群，加入前端Q技术交流群
我读 Hermes 源码的时候，第一件让我吃惊的事是 ——它的 Agent Loop 主循环不到 200 行代码。
我原以为像 Hermes 这种"自进化"系统，主循环至少得 1000 行起跳，里面塞满各种 Memory 注入、Skill 检索、状态机、错误处理。结果打开一看，主循环干干净净，做的事情就一句话：循环 → 拼提示词 → 调模型 → 看要不要调工具 → 检查是不是该退出。
那些复杂的事情都被推到了别的模块里。Loop 本身只是个调度器。
这种"克制"的设计，是 Hermes 真正聪明的地方。这一篇我们就把这个 200 行的主循环拆开看，搞清楚一次 Hermes 任务从启动到退出，内部到底发生了什么。
主循环就 5 个阶段
把 Hermes 的 Agent Loop 抽象出来，本质就 5 个阶段，循环跑：
- Receive Input：拿到 user message 或上一轮 tool result
- Build Prompt：拼 Memory + Skill + Context
- Call LLM：发请求 / 等响应 / 解析结果
- Execute Tool：模型要调工具就执行，不要就跳过
- Check Done：任务完成了？完了就退出，没完就回到第 1 步
我故意没用源码里的真实变量名，因为不同 Agent 框架（Hermes、LangGraph、Cursor、Claude Code）的命名都不一样，但本质都是这 5 个阶段。理解了这个抽象，再看任何一家的源码都能秒懂。
金句：Agent 不是一次性的调用，而是一个循环。
这是和"普通 Chat 应用"最根本的区别。Chat 是 request-response 模式，问一句答一句。Agent 是 task-completion 模式，给定一个目标，循环跑直到完成。
我看过有些团队做"Agent"，其实只是在 ChatCompletion 外面套了个 if-else，没有真正意义上的循环。这种东西做不出"自进化"。没有 Loop，就没有 Agent。
4 个核心模块各司其职
虽然主循环只有 5 个阶段，但 Hermes 在内部把每个阶段拆给了不同的模块。读源码时如果不搞清楚这套分层，会看得晕头转向。
模块 1：Loop Orchestrator（循环主控）
这就是那个 200 行的主循环本体。
它的职责非常窄：
它不知道 prompt 怎么拼，不知道模型怎么调，不知道工具怎么跑。它只知道"下一步该叫谁"。
这种"什么都不做"的设计反直觉，但其实是好架构的标志 ——主循环应该是最薄的那一层，重逻辑要推到下面。
模块 2：Prompt Builder（提示词组装）
这是 Hermes 里最复杂的模块之一（下一篇会专门讲）。
它要在每一轮做的事很多：
这一块独立出来的好处是：改 prompt 策略不需要动主循环。 你想加一种新的注入方式（比如加一个 RAG 检索结果），只改 Prompt Builder，Loop 完全不知道。
模块 3：执行层（LLM Adapter + Tool Runner）
这一层一轮内可能被多次调用。
这两个模块都是"无状态"的 —— 每次调用都是独立的，不依赖任何全局状态。这是工程上的好习惯，方便测试也方便并发。
模块 4：Trajectory Recorder（轨迹记录）
这一层是后台默默干活的：把循环里的每一个事件，写到一个结构化的 session trace 里。
为什么单独抽出来？因为这份 trace 是后续 Nudge Engine 和 Review Agent 的输入。把记录这件事和执行解耦，意味着即使你完全不开自学习功能，主循环也能正常跑（trace 写到 /dev/null 就行）。
金句：分得清楚，才能改得动。
我自己改过几次 Hermes 的 Loop 实现，每次都很顺手 —— 因为 4 个模块边界很清楚，改一个不会牵动其他。这是源码读起来体感最好的部分。
一轮内的完整时序
讲完模块结构，再看一轮内的"调用时序"是什么样。这部分必须画时序图才说得清楚。
按数字顺序看：
- Orchestrator → Prompt Builder：buildPrompt(state)
主循环把当前的状态（已有对话、用户输入、上一轮 tool result）打包，让 Prompt Builder 拼一份完整提示词。
- Prompt Builder → Orchestrator：return prompt
返回拼好的 messages 数组。这一步在 Hermes 里平均耗时 50-200ms（包含 Memory 检索、Skill 匹配的开销）。
- Orchestrator → LLM Adapter：callModel(prompt)
把 prompt 发给模型 API。这一步是整个循环里最慢的（通常 1-5 秒）。
- LLM Adapter → Orchestrator：return assistant message
返回模型的回复。这个回复可能是纯文本（任务完成），也可能包含 tool_calls（需要执行工具）。
- Orchestrator 自检：has tool_calls?
解析模型回复，看是不是要调工具。
- Orchestrator → Tool Runner：execute(tool_call)
如果有工具调用，逐个执行。注意 Hermes 里默认是串行执行（除非工具明确标注了"可并发"），这是为了避免并发副作用。
- Tool Runner → Orchestrator：return tool result
每个工具的结果包装成 tool_result 消息，准备塞进下一轮的 prompt。
- Orchestrator 自检：task done?
- 如果模型没有发起工具调用 → 任务完成，退出 Loop
- 如果有工具调用且都执行完了 → 回到第 1 步，开新一轮
金句：一轮 = 一次模型调用 + 0~N 次工具调用。
这个等式很重要。很多人以为"一轮 = 一次模型调用"，结果在算 token 和耗时时算偏了。实际上一轮里如果模型调了 5 个工具，那就是 1 次 LLM + 5 次 Tool。
一个有意思的细节：很多人觉得 tool_calls 应该并发跑，更快。Hermes 默认串行的原因是 —— 工具之间可能有顺序依赖（比如先 read_file 再 write_file），并发跑会出竞态。除非工具明确声明"我是只读、纯函数、可并发"，否则一律串行。
4 种退出姿势
Loop 必须知道什么时候停。这件事比看起来难得多。
我见过不少人写的"Agent"在测试环境跑得好好的，一上线就死循环跑爆 token 账单。原因都是 ——只考虑了"任务完成"这一种退出条件，没考虑兜底情况。
Hermes 里的 Loop 有 4 种退出姿势，缺一不可。
退出姿势 1：任务自然完成
最常见的一种：模型这一轮不再发起 tool_calls，直接给出 final answer。
判断条件就一句话：if (assistantMessage.tool_calls.length === 0) break;
我看了大概一周的运行日志，Hermes 里大约 70% 的任务是这种正常退出。
退出姿势 2：达到最大 turn 上限
兜底机制。哪怕模型疯了一直在调工具，到了 turn 上限也要强制退出。
Hermes 默认是 25 轮（小任务）或 50 轮（复杂任务）。这个数字是经验值 —— 太小会让正常任务被掐断，太大会让卡住的任务无限消耗 token。
特别坑的点：达到 turn 上限的退出不能算"任务完成"，否则 Review Agent 会把"卡住"当成"成功"去复盘，写出错的 Skill。Hermes 在这种情况下会显式标注 terminated_by: "max_turns"，让下游知道这次是异常结束。
退出姿势 3：用户主动打断
用户按 Ctrl+C、点击取消按钮、或者通过 Hook 阻断当前任务。
这种退出要做的工作比看起来多：
Hermes 的处理是：已经完成的工具调用保留结果，正在执行的工具尝试 cancel，模型流式输出直接丢弃。这套规则不是最优的，但是是"用户最容易理解"的。
退出姿势 4：不可恢复错误
模型 API 挂了、工具抛出未捕获异常、内存爆了 OOM。
这一类退出的关键是 "优雅" 二字。要做到：
Hermes 这块写得挺细的，不同类型的错误有不同的处理路径。我看源码时学到一招：所有从 Loop 抛出去的异常都要包装成 AgentError，带上错误码和上下文。这样不管在哪一层接住，都能拿到完整信息。
金句：一个好的 Loop，必须有 4 种退出姿势。
我现在自己写 Agent 时，第一个写的就是退出条件。先想清楚怎么停，再想怎么跑 —— 这是从 Hermes 学到的最重要的一条。
我自己读源码的几个发现
读 Hermes Loop 源码的过程中，有几处设计让我印象很深。
发现 1：Loop 内不做任何业务判断
Hermes 的 Loop 里没有任何 "if 任务类型 == X 那么..." 的代码。
业务差异（比如"代码任务要先 lint"、"文档任务要先 outline"）全都通过 Skill 注入到 prompt 里，由模型自己判断。Loop 永远是同一个流程。
这种"通用循环 + 差异化 prompt"的设计，让 Loop 可以在所有场景复用，不会因为加新功能而越来越臃肿。
发现 2：每一步事件都立刻落盘
Trajectory Recorder 不是任务结束才一次性写入，而是每一步事件实时写到磁盘。
我刚开始觉得这是性能浪费，后来想明白了 —— 如果任务跑到一半挂了，没落盘的事件就丢了，Review Agent 拿不到完整 trace。
实时落盘的代价是每秒多写几次 disk，收益是任何异常情况下都能事后复盘。这个 trade-off 很值。
发现 3：Tool 调用一定串行
前面提过，但我想再强调一次。Hermes 默认串行执行工具调用，不是性能不够，是为了正确性优先于速度。
我做实验把它改成默认并发，跑 100 个真实任务，发现 7% 的任务出现了"读到了上一步还没写完的数据"这种竞态。一旦出错，整个 trajectory 就变得无法复盘。
并发应该是个 opt-in 选项，不能是默认。
发现 4：状态机被刻意避免
很多 Agent 框架（比如 LangGraph）把 Loop 实现成显式状态机，节点之间有明确转移规则。
Hermes 没用状态机。Loop 就是个简单的 while 循环，状态全在变量里。
我刚开始觉得这是技术债，后来意识到这是有意为之 ——显式状态机会让 Loop 的每一种状态都需要预先定义，新增能力时改动巨大。简单的 while 循环灵活得多，新增能力只需要往 prompt 里加内容。
这两种风格各有适用场景。任务种类有限、流程稳定的场景用状态机（比如客服对话）；任务种类无限、需要高度灵活的场景用简单 Loop（比如通用 Coding Agent）。
我的看法
读完 Hermes 的 Agent Loop 源码，我最大的感受是 ——好的 Agent 框架，主循环越少越好。
把所有复杂逻辑都堆在主循环里，是初学者最容易犯的错。结果就是循环代码 5000 行，谁来都改不动，加任何新功能都怕踩坑。
Hermes 走了相反的路：
这种"主循环克制，外围灵活"的设计，让整个系统既好理解又好扩展。
更重要的是，它让"自进化"成为了一个可以叠加的能力，而不是嵌入的逻辑。Memory、Skill、Nudge、Review 都是从外部叠加到这个 Loop 上的，Loop 本身不知道它们的存在。哪天你不想要自学习了，把这些模块拔掉，Loop 照样能跑。
这种解耦在工程上极其值钱。任何想做长期演进的 Agent 系统，都应该把"基础执行能力"和"高阶能力"分得这么清楚。
下一篇我们深入 Prompt Builder ——Memory、Skill、Context Files 到底是怎么进入 system prompt 的，长度超了怎么裁剪、优先级怎么定。这是整个系统里真正"决定模型每一步看到什么"的关键。
往期推荐
