Hermes Agent 原理与架构深度解析：从 ReAct 循环到自学习闭环（基于源码）

Hermes Agent 是 Nous Research 出品的自学习 AI Agent 系统，核心架构由六层组成：CLI/TUI 入口层、AIAgent 同步推理循环、工具注册中心、插件扩展系统、记忆与压缩管线、Curator 后台自学习器。本文基于 NousResearch/hermes-agent 仓库 AGENTS.md 与源码目录的真实结构（截至 2026-05-11）一次性讲清它的工作原理。

一、Hermes Agent 是什么：一句话定义

Hermes Agent 是一个带学习闭环的同步式工具调用 Agent——核心循环用最经典的"模型生成 → 工具执行 → 结果回喂"做迭代，外面套上自学习的 Curator、跨会话 FTS5 记忆搜索和 7 种部署后端。仓库官方 README 一句话："The agent that grows with you."

关键事实卡：

• 仓库：NousResearch/hermes-agent（截至 2026-05-11，142,830 star，5,079 open issues）
• 主语言：Python（CLI/agent 核心）+ TypeScript（Ink TUI）
• 入口类：AIAgent（run_agent.py，约 12k LOC）+ HermesCLI（cli.py，约 11k LOC）
• 测试规模：约 17,000 个测试 / 约 900 个测试文件（仓库 AGENTS.md 自述）

二、整体架构：六层骨架图

仓库官方目录结构（节选自 AGENTS.md）：

hermes-agent/
├── run_agent.py          # AIAgent 类 — 核心对话循环（~12k LOC）
├── model_tools.py        # 工具编排，discover_builtin_tools()，handle_function_call()
├── toolsets.py           # 工具集定义，_HERMES_CORE_TOOLS 列表
├── cli.py                # HermesCLI 类 — 交互式 CLI 编排（~11k LOC）
├── hermes_state.py       # SessionDB — SQLite 会话存储（FTS5 搜索）
├── agent/                # provider 适配器、记忆、缓存、压缩、Curator
├── hermes_cli/           # CLI 子命令、setup 向导、插件加载、skin 引擎
├── tools/                # 工具实现 — 通过 tools/registry.py 自动发现
│   └── environments/     # 终端后端（local/docker/ssh/modal/daytona/singularity）
├── gateway/              # 消息网关 — run.py + session.py + platforms/
├── plugins/              # 插件系统（memory / context_engine / model-providers / kanban / ...）
├── ui-tui/               # Ink (React) 终端 UI — `hermes --tui`
├── tui_gateway/          # TUI 的 Python JSON-RPC 后端
├── acp_adapter/          # ACP 服务器（VS Code / Zed / JetBrains 集成）
└── cron/                 # 调度器 — jobs.py / scheduler.py

按依赖关系自底向上是 6 层：

┌─────────────────────────────────────────────────────────┐
│ L6 入口/UI: cli.py / ui-tui (Ink) / gateway / acp_adapter│
├─────────────────────────────────────────────────────────┤
│ L5 编排: AIAgent (run_agent.py) — 同步对话循环           │
├─────────────────────────────────────────────────────────┤
│ L4 工具: model_tools + tools/registry.py — 自动发现     │
├─────────────────────────────────────────────────────────┤
│ L3 推理: agent/ — provider 适配器、缓存、压缩、Curator   │
├─────────────────────────────────────────────────────────┤
│ L2 持久化: hermes_state SQLite + FTS5 + plugins/memory   │
├─────────────────────────────────────────────────────────┤
│ L1 系统: ~/.hermes/ 配置 + .env + 7 种 environments      │
└─────────────────────────────────────────────────────────┘

三、核心循环：AIAgent 的同步式 Tool Calling

Hermes Agent 没有用 LangGraph/AutoGPT 那样的图编排，而是用极简的同步 while 循环。这是 AGENTS.md 中给出的核心代码结构（来自 run_agent.py::run_conversation）：

while (api_call_count < self.max_iterations and self.iteration_budget.remaining > 0) \or self._budget_grace_call:if self._interrupt_requested: breakresponse = client.chat.completions.create(model=model, messages=messages, tools=tool_schemas)if response.tool_calls:for tool_call in response.tool_calls:result = handle_function_call(tool_call.name, tool_call.args, task_id)messages.append(tool_result_message(result))api_call_count += 1else:return response.content

四个设计要点：

1. 同步而非异步：循环本身是同步的——异步只在 IO（流式 API、网关）边界存在。这避免了大部分 Agent 框架因 async/await 嵌套带来的调试黑洞。
2. 预算驱动而非步数驱动：max_iterations（默认 90）是硬上限，但实际用 iteration_budget 做软预算 + _budget_grace_call 留一次"恩典调用"做收尾。子代理与父代理共享预算。
3. 可中断：每轮检查 _interrupt_requested，CLI 里 Ctrl+C / TUI 里 /stop 都能立即把 Agent 拉出循环。
4. OpenAI message 格式为唯一事实：{"role": "system/user/assistant/tool", ...}，推理内容统一塞进 assistant_msg["reasoning"]——这让 provider 切换零代码改动。

AIAgent.__init__ 实际接收约 60 个参数（凭据、路由、回调、会话上下文、预算、凭据池等），但你日常只接触十来个核心字段：base_url / api_key / provider / model / max_iterations / enabled_toolsets / platform / session_id / credential_pool 等。

四、Provider 抽象层：跨厂商推理的关键

agent/ 目录下专门有一组 adapter 处理"不同厂商 API 长得不一样"的问题：

适配器文件	作用
anthropic_adapter.py	Anthropic Messages API（含 thinking 字段）
bedrock_adapter.py	AWS Bedrock 鉴权与请求转换
codex_responses_adapter.py	OpenAI Codex Responses API（不同于 chat completions）
gemini_native_adapter.py	Google Gemini 原生 API
gemini_cloudcode_adapter.py	Google Cloud Code Assist（OAuth 流）
copilot_acp_client.py	GitHub Copilot ACP 协议

api_mode 字段决定走哪条路径："chat_completions" / "codex_responses" / 原生 Anthropic / 原生 Gemini。这是 Hermes 能"一行命令切换 20 个 provider"的底层基础。

辅助：agent/auxiliary_client.py 处理副 LLM 任务（curator、vision、embedding、title generation、session search），每个任务可以独立 pin provider/model，避免占用主对话的预算。

五、工具系统：注册中心 + 自动发现

工具系统是 Hermes 最优雅的部分。AGENTS.md 节选：

Auto-discovery: any tools/*.py file with a top-level registry.register() call is imported automatically — no manual import list to maintain. Wiring into a toolset is still a deliberate, manual step.

依赖链：

tools/registry.py  (零依赖 — 被所有工具文件导入)↑
tools/*.py  (每个文件在 import 时调用 registry.register())↑
model_tools.py  (导入 tools/registry + 触发工具发现)↑
run_agent.py / cli.py / batch_runner.py / environments/

仓库 tools/ 目录里实际存在的核心工具（节选）：

• 代码与文件：code_execution_tool.py、file_operations.py、file_state.py、file_tools.py、file_safety.py
• 浏览器与 GUI：browser_tool.py、browser_cdp_tool.py、browser_camofox.py、browser_supervisor.py、computer_use_tool.py
• 代理协作：delegate_tool.py、mixture_of_agents_tool.py、kanban_tools.py
• MCP 协议：mcp_tool.py、mcp_oauth.py、mcp_oauth_manager.py、managed_tool_gateway.py
• 第三方集成：feishu_doc_tool.py、feishu_drive_tool.py、discord_tool.py、microsoft_graph_client.py、homeassistant_tool.py
• Agent 元能力：memory_tool.py、approval.py、clarify_tool.py、interrupt.py、checkpoint_manager.py、cronjob_tools.py

两阶段暴露：自动发现只解决"工具被注册"，要让 Agent 真正能用，还必须把工具名加到 toolsets.py::_HERMES_CORE_TOOLS 或新建 toolset。AGENTS.md 明确强调：

_HERMES_CORE_TOOLS 不是死代码——它是每个平台 base toolset 都继承的默认 bundle。

Agent 级工具特殊路径：todo、memory 这类直接影响对话状态的工具，由 run_agent.py 在 handle_function_call() 之前拦截，不走标准 dispatch。

六、插件系统：把扩展从 core 解耦出去

plugins/ 目录是 Hermes 扩展性的真正核心，目录结构：

插件目录	用途
plugins/memory/	记忆 provider — Honcho、mem0、supermemory 等
plugins/context_engine/	上下文引擎插件
plugins/model-providers/	推理后端 — openrouter、anthropic、gmi 等
plugins/kanban/	多代理看板 + worker 派发
plugins/observability/	指标 / trace / 日志
plugins/image_gen/	图像生成 provider
plugins/hermes-achievements/	成就跟踪（gamification）

用户插件走相同协议：~/.hermes/plugins/<name>/plugin.yaml + __init__.py，在 __init__.py 里调 ctx.register_tool(...)。AGENTS.md 强烈建议：

大多数自定义或本地工具，不要改 Hermes core，走插件路径。插件 toolset 自动发现，可以独立启停。

七、记忆与跨会话搜索：FTS5 的妙用

会话存储在 hermes_state.py::SessionDB——SQLite + FTS5 全文索引。意义在于：

• 每次对话写入 SQLite
• FTS5 提供毫秒级关键词召回
• LLM 摘要做语义压缩
• 加上 agent/context_compressor.py 做主动压缩，避免上下文溢出

跨会话搜索通过 agent/insights.py 和 auxiliary 配置中的 session_search 任务驱动。关键体验："上次我们聊到 X，继续……"——Hermes 会在 FTS5 里命中相关历史片段，再用 LLM 摘要塞回当前 context，预算可控。

衍生记忆 plugin 三家：

• Honcho（plastic-labs/honcho）：辩证用户建模
• mem0：通用键值记忆
• supermemory：多模态长期记忆

八、自学习闭环：Curator 是核心

agent/curator.py（约 75KB 源码）是 Hermes 区别于 OpenClaw 的最大差异：

• 后台运行（config.yaml::curator.enabled）
• 周期触发（interval_hours）
• 仅在 idle 时间窗（min_idle_hours）工作，避开主对话
• 自动归档过时 skill（stale_after_days / archive_after_days）
• 备份钩子（backup 嵌套配置）

简化逻辑：Agent 每完成复杂任务 → Curator 提炼模式 → 写成 skill → 下次同类任务直接命中。这就是 README 自述"creates skills from experience, improves them during use"的工程实现。

九、CLI 与 TUI 双前端：Ink + JSON-RPC

Hermes 同时维护两个前端：经典 prompt_toolkit CLI（cli.py）和 React/Ink TUI（ui-tui/）。两者通过 tui_gateway/ 的 newline-delimited JSON-RPC over stdio 通信：

hermes --tui└─ Node (Ink)  ──stdio JSON-RPC──  Python (tui_gateway)│                                  └─ AIAgent + tools + sessions└─ 渲染 transcript / composer / prompts / activity

设计原则（AGENTS.md 原文强调）：

TypeScript owns the screen. Python owns sessions, tools, model calls, and slash command logic.

Slash 命令在两端共用同一份 COMMAND_REGISTRY（hermes_cli/commands.py）——CLI 派发、Gateway 派发、Telegram BotCommand 菜单、Slack 子命令路由、Autocomplete、/help 文本，全部从这一处衍生。新增一个命令只需在 registry 里加一行 CommandDef，所有派生面自动更新。

十、消息网关：22+ 平台同源派发

gateway/platforms/ 是 Hermes 多平台对接的真相所在。一个目录一个适配器：

telegram、discord、slack、whatsapp、homeassistant、signal、matrix、mattermost、email、sms、dingtalk、wecom、weixin、feishu、qqbot、bluebubbles、yuanbao、webhook、api_server……

每个 adapter 实现统一的 send_message / receive_event 接口，再通过 gateway/run.py 路由到 AIAgent。新增平台只需写 adapter + 注册到 gateway/platforms/__init__.py，参考 ADDING_A_PLATFORM.md。

十一、配置与环境：三层加载、严格分工

Hermes 的配置加载有三个入口（AGENTS.md 表格原文）：

加载器	用于	位置
load_cli_config()	CLI 模式	cli.py——合并 CLI 默认 + 用户 YAML
load_config()	hermes tools / hermes setup 等子命令	hermes_cli/config.py——合并 DEFAULT_CONFIG + 用户 YAML
Direct YAML load	Gateway 运行时	gateway/run.py + gateway/config.py——读用户 YAML 原始值

严格分工：

• config.yaml 放非密配置（timeout、阈值、feature flag、路径、显示偏好）
• .env 只放秘密（API Key、Token、密码）

工作目录约定：CLI 用 os.getcwd()，messaging 用 terminal.cwd（gateway 桥接到 TERMINAL_CWD 环境变量给子工具）。MESSAGING_CWD 已废弃，如果还在 .env 里，配置加载器会打印 deprecation warning。

十二、终端后端：7 种部署形态

tools/environments/ 提供 7 种执行环境：

• local — 本地 shell
• docker — 容器隔离
• ssh — 远程主机
• singularity — HPC 容器
• modal — Serverless GPU 后端
• daytona — Serverless 持久化沙箱
• vercel sandbox — 边缘运行时

Modal 与 Daytona 支持"闲置休眠 + 调用唤醒"的 Serverless 持久化，让 Agent 能跑在 $5 VPS 上几乎零成本。这是 Hermes 比 OpenClaw"能跑在更便宜的基础设施上"的工程实现。

十三、常见问题

Q：Hermes Agent 用的是 ReAct、Plan-and-Execute 还是别的范式？
A：核心是 OpenAI 风格的 tool calling 循环（接近 ReAct 的 reason→act→observe，但由模型 native function calling 驱动而非 prompt 提示）。计划/子代理工作流通过 plan 和 subagent-driven-development 这两个 skill 实现，不是写死在 core。

Q：max_iterations=90 用完了会怎样？
A：循环退出，但有一次 _budget_grace_call——让模型再调一次做收尾响应。子代理和父代理共享同一个预算池（iteration_budget），避免子代理无限派发。

Q：跨会话记忆是怎么实现的？为什么不用向量库？
A：核心走 SQLite + FTS5 全文索引（毫秒级关键词召回） + LLM 摘要做语义压缩，没用向量库。这让一台 $5 VPS 也能跑得动。需要语义检索时通过 plugins/memory/ 接 Honcho / mem0 / supermemory 等向量后端。

Q：怎么自己写一个工具/插件？
A：自定义工具走插件路径（~/.hermes/plugins/<name>/plugin.yaml + __init__.py，调 ctx.register_tool(...)）；贡献给 core 走 tools/your_tool.py + toolsets.py 注册。AGENTS.md 明确反对"为本地工具改 core"。

Q：Agent 能并行跑子任务吗？
A：能。tools/delegate_tool.py 派发独立 subagent；plugins/kanban/ 提供 dispatcher + worker 多代理看板。但同一个 AIAgent 实例的对话循环是同步的——并行通过派发独立实例实现。

Q：CLI 和 TUI 共享上下文吗？
A：共享。两者都连接到同一个 AIAgent 实例（TUI 通过 tui_gateway 的 JSON-RPC 后端调用），会话、工具、slash 命令逻辑住在 Python 层，TypeScript 只管屏幕渲染。

十四、结论

Hermes Agent 的架构哲学可以浓缩成三句话：循环要简单（同步 while + 预算）、扩展要解耦（plugin 优先于改 core）、记忆要工程化（SQLite + FTS5 + Curator 做长期成长）。它不是抽象 Agent 框架的"更好版本"，而是一份对真实工程问题给出务实答案的代码库——20 个 provider 的统一抽象、22+ 通讯渠道、7 种执行后端、约 17,000 个测试，全部围绕一个目标：让 Agent 能稳定跑在用户日常工具链里，并随时间自我成长。

本文所有架构细节、文件路径、循环代码、目录列表、约 17k 测试 / 约 900 测试文件、142,830 star / 5,079 issue 等数据均直接来自 NousResearch/hermes-agent 仓库的 AGENTS.md、agent/、tools/、plugins/、gateway/ 等真实文件（数据时间 2026-05-11），建议每次大版本升级后复核架构变动。

延伸资源：

• 兼容 OpenAI/Anthropic 双标准的多 provider 网关（可作为 Hermes custom provider）：portal.qiniu.com/ai-inference/api-key
• Hermes Agent 仓库：https://github.com/NousResearch/hermes-agent
• 架构开发指南原文：https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md