从用户一句话到任务完成：Hermes Agent 一次请求完整链路详解

一、先说结论：Hermes 不是“问一句答一句”的普通聊天框

很多人理解 AI 应用时，会把它想成一个 Chatbot：用户发一句话，模型回一句话。但 Hermes Agent 的请求链路更像一个“任务操作系统”。用户的一句话进入系统后，Hermes 会先判断会话来源和历史状态，再组装项目上下文、长期记忆、技能索引、工具列表，最后让模型在 Agent Loop 中一步步决定：是直接回答，还是调用工具继续执行。

所以，完整链路可以概括成一句话：入口负责接人，会话负责接上下文，Prompt 负责接知识，Provider 负责接模型，Tools 负责接动作，Session 和 Memory 负责把过程沉淀下来。

二、入口层：请求先从 CLI、Gateway、API、ACP 或 Cron 进来

Hermes 的第一个特点，是入口不止一个。你可以在本地 CLI 里和它对话，也可以从 Telegram、Discord、Slack、WhatsApp 等平台发消息，还可以通过 API Server、ACP/IDE、Cron 自动化触发任务。不同入口的形态不同，但最终都要被转换成 Hermes 能理解的用户消息。

如果是聊天平台，Gateway 会负责平台适配、用户授权、消息路由和会话键构造；如果是 CLI，则直接进入本地交互；如果是 Cron，则像一个“定时用户”一样发起任务。

CLI/TUI：适合本地开发、终端操作、直接看工具输出。

Gateway：适合把 Hermes 放到服务器上，让用户从多个消息平台持续交互。

API Server：适合企业系统或其他程序把 Hermes 当成后端能力调用。

ACP/IDE：适合在编辑器场景里把任务交给 Hermes。

Cron：适合日报、巡检、备份、定时报告这类无人值守任务。

三、会话层：先确认“这是哪个用户、哪个平台、哪个任务”

请求进入后，Hermes 不会急着调模型，而是先处理 Session。Session 的作用是回答三个问题：这条消息来自谁？它属于哪个平台或频道？它应该接到哪个历史任务后面？

这一步非常关键。没有 Session，Agent 就会像普通 Chatbot 一样，每次都重新开始；有了 Session，用户今天在 Telegram 发起任务，明天在 CLI 或同一会话里继续追问，Hermes 还能把之前的消息、工具调用、模型配置和统计信息接上。

三.一、state.db 是跨平台延续任务的“账本”

Hermes 使用 ~/.hermes/state.db 保存会话元数据、完整消息历史、模型配置和检索索引。你可以把它理解成一本账本：每一轮用户消息、模型回复、工具结果、token 消耗、成本估算、父子会话关系都会被记录下来。

这样做有两个好处：第一，任务可以恢复；第二，历史可以检索。后续 Memory、Session Search、压缩后的 Session lineage，都是建立在这个会话存储能力之上的。

四、Prompt 层：把项目规则、记忆和技能装进“任务背景”

很多 AI 应用效果不好，不是因为模型不够强，而是因为模型不知道当前项目的规则。Hermes 在调用模型之前，会通过 prompt_builder.py 组装一套有效系统提示词。它不是只有一句“你是一个助手”，而是分层拼装：身份、工具使用规则、Memory 快照、User 快照、Skills 索引、项目 Context Files、时间和平台提示。

四.一、为什么要分层？

分层的好处是稳定、可控、可缓存。比如 SOUL.md 是 Agent 身份，MEMORY.md 和 USER.md 是长期记忆，AGENTS.md 或 .hermes.md 是项目规则，Skills 是可复用流程。它们都属于不同性质的信息，如果混在一起，后期会非常难维护。

四.二、这一步决定模型“站在哪个场景里思考”

同样一句“帮我修一下 bug”，如果没有项目上下文，模型只能泛泛而谈；如果 Prompt 里有项目入口、测试命令、代码规范、历史问题和可用工具，模型就能像一个熟悉项目的工程师一样行动。

五、Provider 层：选模型、选 API 模式、选凭证

Prompt 准备好之后，Hermes 还要决定这次请求用哪个模型、哪个供应商、哪个 API 模式。它会综合显式参数、配置文件、环境变量和 provider 插件默认值，解析出 provider、model、api_mode、base_url、api_key 等运行时信息。

这一步解决的是“模型供应商差异”问题。OpenAI 兼容接口、Codex Responses API、Anthropic Messages API 的消息格式和工具调用形式并不完全一样。Hermes 会在外层做转换，让 Agent 内部继续使用统一的消息结构。

六、Agent Loop：一次请求真正进入执行循环

进入 AIAgent 后，Hermes 会执行一轮标准生命周期。官方文档把这个过程拆成 9 步：生成 task_id、追加用户消息、构建或复用系统 Prompt、检查预压缩、构造 API 消息、注入临时提示、应用缓存标记、发起可中断模型调用、解析响应。

六.一、为什么叫 Loop，而不是一次调用？

因为模型不一定第一次就能给出最终答案。它可能先调用 read_file 看代码，再调用 terminal 跑测试，再调用 patch 修改文件，再继续让模型判断下一步。每一次“模型思考 + 工具执行 + 结果回填”都是循环的一轮。

六.二、消息格式为什么重要？

Hermes 内部把消息统一成 system、user、assistant、tool 这样的结构。工具调用时，必须遵守“Assistant 带 tool_calls → Tool 返回结果 → Assistant 继续判断”的顺序。顺序错了，很多模型供应商会直接拒绝请求。

七、工具执行：模型负责决策，Hermes 负责落地

当模型返回 tool_calls 时，Hermes 会进入工具执行层。这个阶段不是模型自己去碰文件、终端或浏览器，而是模型声明“我要调用哪个工具、参数是什么”，Hermes 再从工具注册表里找到对应 handler。

七.一、工具执行的标准动作

先从 tools/registry.py 找到工具 handler。

触发 pre_tool_call hook，给插件或平台机会拦截。

如果是危险命令，进入审批逻辑，等待用户授权。

真正执行 handler，比如读文件、跑命令、调用 MCP Server。

触发 post_tool_call hook，记录执行后的状态。

把工具结果作为 tool message 写回对话历史。

七.二、并发执行提高效率，但交互工具要谨慎

如果模型一次返回多个普通工具调用，Hermes 可以用线程池并发执行；但像 clarify 这种需要用户交互的工具，不能并发乱跑，必须按顺序等待用户输入。

八、长任务保护：压缩、Fallback、预算控制

真实任务经常很长：读很多文件、跑很多测试、来回修很多轮。如果没有保护机制，Agent 很容易遇到三个问题：上下文太长、模型失败、循环太久。Hermes 在请求链路中加入了压缩、Fallback 和预算控制。

八.一、压缩：上下文太长就把中间过程总结掉

当对话超过模型上下文一定比例时，Hermes 会触发压缩。压缩前会先把 Memory 刷盘，防止重要事实丢失；然后把中间对话总结成更短的摘要，同时保留最近 N 条消息和工具调用/工具结果成对结构。

八.二、Fallback：主模型失败就换备用路线

如果主模型出现限流、服务端错误、鉴权问题，Hermes 会检查 fallback_providers，按顺序尝试备用模型或供应商。这样长任务不会因为一次模型失败就彻底中断。

八.三、预算控制：防止 Agent 无限跑下去

Hermes 会跟踪迭代预算。父 Agent 有自己的上限，子 Agent 也有独立上限。到达上限后，系统会停止并返回已完成工作的总结，而不是继续无休止消耗 token 和工具资源。

九、持久化：最终答案返回前后，Hermes 会把过程留下来

一次请求结束时，Hermes 不只是把答案发给用户，还会保存会话消息、工具调用、token 统计、Memory 更新等信息。这样，下一次用户追问“刚才那个任务继续”时，系统不是凭空猜，而是能从 Session 和 Memory 中找回依据。

从工程角度看，这就是 Hermes 和普通 Chatbot 的根本差异：普通 Chatbot 更像“当前窗口里的回复器”，Hermes 更像“能长期记账、能执行动作、能沉淀经验的任务运行时”。

十、完整链路总表：一条请求到底经过了哪些站点？

十一、源码阅读路线：按请求链路去看，效率最高

如果你想看 GitHub 源码，不建议直接从最大文件开始硬啃。更好的方式是顺着一次请求的生命周期看：入口怎么接入，会话怎么恢复，Prompt 怎么构造，Provider 怎么解析，模型怎么调用，工具怎么执行，最后状态怎么落盘。

第一步看 Architecture，先建立整体地图。

第二步看 Agent Loop Internals，理解 AIAgent 的主职责。

第三步看 Prompt Assembly，理解系统提示词从哪些来源组成。

第四步看 Provider Runtime Resolution，理解模型供应商如何统一。

第五步看 Tools Runtime，理解工具注册、Schema、Dispatch。

第六步看 Session Storage，理解跨平台任务如何延续。

第七步回到 run_agent.py，对照前面的概念读主循环。

十二、总结：一次用户请求进入 Hermes 后，本质经历了三次转换

第一，从“平台消息”转换成“标准任务”：入口层和会话层负责识别来源、用户、平台、历史上下文。

第二，从“自然语言”转换成“可执行循环”：Prompt Builder 把身份、记忆、技能、项目规则和工具说明装进模型上下文，AIAgent 再通过模型调用和工具调用循环推进任务。

第三，从“执行结果”转换成“长期资产”：Session 保存过程，Memory 保存事实，Skills 沉淀流程，Trajectory 留作调试和评测。这也是 Hermes 越用越像长期助手的原因。

所以，理解 Hermes Agent 的完整链路，不要只盯着模型。真正的主线应该是：入口、会话、上下文、模型、工具、容错、持久化。模型负责判断下一步，Hermes 负责把这个判断放进一个可以长期运行、可以跨平台延续、可以安全执行动作的工程系统里。