Hermes Agent 源码解读:一条消息经过的5层架构与7个核心机制

大家好，我是苍一，一个干了13年的后端开发，正在探索AI编程，从产品到开发的全生命周期最佳实践，如果您感兴趣，欢迎关注👇，看我如何自我革命。

背景

Hermes Agent 在 GitHub 上两个月拿了 47000 颗星。很多人拿它和其他框架做对比，但更关心的是它内部怎么运转的。读 Agent 源码最有效的路径：跟一条消息走一遍。

五层架构

Hermes 的整体结构可以分成五层：

入口层包括 CLI 和二十多个平台适配器，覆盖飞书、钉钉、Telegram、Discord、Slack、WhatsApp 等。网关层是 GatewayRunner 常驻进程，管理连接、会话生命周期和斜杠命令。执行层是 AIAgent，负责组装上下文、调用模型、执行工具、处理错误。扩展层包含工具注册中心、技能系统、子 Agent 委托和外部记忆 Provider。存储层用 SQLite + FTS5 做持久化。

一、适配器模式：内外统一的消息协议

终端是最直接的入口，但 Hermes 支持 20 多个平台。每个平台消息格式和通信方式都不一样。Hermes 给每个平台写了独立的适配器，全部继承 BasePlatformAdapter。基类只定义了 connect、disconnect、send 三个接口。

这是标准的适配器模式：进来时把外部差异统一成内部对象，出去时反向拆回各平台格式。想接新平台，写一个适配器就够了。

二、Gateway 的 Profile 隔离机制

每个 Profile 拥有独立的配置、密钥、记忆和会话历史。通过 HERMES_HOME 环境变量控制整棵目录树。一台机器可以同时运行工作 Agent 和个人 Agent，互不干扰。

三、Agent 主循环：三种退出路径与迭代预算

消息到达 AIAgent 后进入核心主循环。循环有三种退出方式：模型没有 tool_calls 时返回最终文本；迭代预算耗尽；用户中断。

1️⃣ PTC 机制与预算退还

当本轮工具调用只有 execute_code 一种时，刚扣掉的 1 次迭代会被退还。execute_code 是 PTC（Programmatic Tool Calling）：模型写一段 Python 脚本，脚本内部通过 RPC 把多个工具串起来执行。8 次信息获取走普通工具调用要 8 轮，走 PTC 只需 1 轮且预算退还后等于零成本。

2️⃣ 工具并行执行

系统维护三个集合决定工具能否并行：NEVER_PARALLEL_TOOLS、PARALLEL_SAFE_TOOLS 和 PATH_SCOPED_TOOLS。路径冲突检查会提取每次调用的目标路径，两两比对是否重叠。并行池最多 8 个工作线程。

3️⃣ delegate_task 子 Agent 委托

模型选 delegate_task 时会 fork 一个新的 AIAgent，有独立上下文和 50 轮迭代预算。子 Agent 被禁用 5 个工具防止套娃和越权。委托深度只有 1 层，并发上限 3 个。

四、系统提示词的组装策略

系统提示词拼接顺序：身份、工具行为引导、外部系统提示、记忆、技能索引、项目上下文、运行时元数据。越稳定的内容越靠前，配合前缀缓存命中。

4️⃣ 针对不同模型的约束注入

对 GPT、Gemini 家族，额外注入 TOOL_USE_ENFORCEMENT_GUIDANCE，应对”说做就做，别光说不动”等问题。Claude 不需要这段。

5️⃣ 项目上下文安全扫描

从工作区扫文件注入前过 10 条正则，覆盖常见 prompt injection 手法。命中任何一条，整个文件内容会被替换为 [BLOCKED: …]。

五、记忆系统：冻结快照与文件持久化

MEMORY.md 和 USER.md 按字符数限制，记忆在会话开始时注入系统提示词，之后整个会话期间不再更新。会话期间通过工具写入的记忆立刻持久化到磁盘，但系统提示词里的快照不变，下次新会话才加载最新。这是用一致性换前缀缓存命中率的工程权衡。

六、错误恢复：分类器驱动的精准恢复

Hermes 按错误分类走不同恢复路径，而不是一个大 try/except。FailoverReason 枚举归了 14 种错误，每个错误过分类器后只带四个布尔标记：retryable、should_compress、should_rotate_credential、should_fallback。

6️⃣ 上下文压缩

流程分四步：裁旧工具输出、保护头部、保护尾部、中间部分用便宜模型做摘要。每次压缩时 SQLite 里做三件事：结束当前 session 保留原始对话、开新 session 以摘要为起点、新 session 的 parent_session_id 指回旧 session。连续压缩形成链式结构，数据层所有原始消息完整保留。

七、自进化机制：后台复盘与技能沉淀

模型回答返回后还有三件事：落盘、记忆同步、后台复盘。对用户零感知。

技能是 Skills 目录里的 Markdown 文档。两条信号并行保证技能库增长：系统提示词里的主动引导，和后台每 10 轮推理触发的强制复盘。背景线程必须在回复已发给用户之后才启动，不和用户等待的响应抢资源。

小结

Hermes 的架构围绕几个核心工程决策：适配器模式屏蔽平台差异、冻结快照保前缀缓存命中、迭代预算控制成本、错误分类器精准恢复、后台线程异步沉淀经验。

源码地址：https://github.com/HermesAgent/Hermes