从用户一句话到任务完成：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 的作用是回答三个问题这条消息来自谁它属于哪个平台或频道它应该接到哪个历史任务后面这一步非常关键。没有 SessionAgent 就会像普通 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 更像“能长期记账、能执行动作、能沉淀经验的任务运行时”。十、完整链路总表一条请求到底经过了哪些站点链路阶段核心问题关键模块/文件输出结果入口接入消息从哪里来CLI / gateway/run.py / API / ACP / Cron标准化用户消息会话识别属于哪个用户和任务gateway/session.py / hermes_state.pySession ID / History上下文组装模型需要知道什么背景agent/prompt_builder.py系统 PromptProvider 解析该调用哪个模型runtime_provider.py / providers/api_mode / base_url / key模型调用下一步要做什么run_agent.py / adapters文本或 tool_calls工具执行怎么把决定变成动作model_tools.py / tools/registry.pyTool Result循环推进是否需要继续做AIAgent Loop继续调用模型或结束容错保护上下文、模型、预算失控怎么办context_compressor / fallback / IterationBudget压缩、切换、停止总结持久化过程如何保存state.db / MEMORY.md / Skills / trajectory可恢复、可检索、可复用十一、源码阅读路线按请求链路去看效率最高如果你想看 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 负责把这个判断放进一个可以长期运行、可以跨平台延续、可以安全执行动作的工程系统里。