拆开 Hermes Agent 的引擎盖：八大子系统、37 个模块，一张地图讲清楚——底层系列开篇

TL;DR ：Hermes Agent 不是黑盒。从终端敲下 hermes 到 Agent 返回结果，中间经过 8 个子系统、37+ 个核心模块的精密协作。本文是「Hermes Agent 底层原理」系列开篇，用一张架构图和一份速查表，帮你建立完整的模块地图。不深入任何单个模块------那是后续每篇文章的事。

为什么需要这张"地图"

翻开源码之前，最怕的是不知道自己在哪。

Hermes Agent（由 Nous Research 开发，GitHub 100K+ Stars）是目前最活跃的开源 AI Agent 框架之一。它的源码目录里有 140+ 个 .py 文件，cli.py 超过 14,000 行，run_agent.py 超过 4,000 行。一头扎进去，很容易迷失方向。

这篇文章的目标很简单：给你一张地图。把 Hermes Agent 的底层模块按职责分成八大子系统，每个子系统的核心文件是什么、负责什么、在哪能找到，一目了然。

后续系列文章会逐个子系统深挖------从 Agent Loop 的每一次呼吸到 Hindsight 的向量召回机制。但今天，只看全景。

八大子系统速览

#	子系统	核心职责	关键文件
①	入口层	三个入口（CLI/Gateway/ACP），一个核心	`cli.py`、`gateway/run.py`、`acp_adapter/`
②	核心循环	`run_conversation()` --- Agent 的"心跳"	`run_agent.py`
③	提示词引擎	将记忆+技能+历史拼成 API 请求	`prompt_builder.py`、`context_engine.py`
④	模型调度	Provider 解析、凭据管理、API 适配	`runtime_provider.py`、`auth.py`
⑤	工具系统	70+ 工具注册、发现、分发	`tools/registry.py`、`model_tools.py`
⑥	记忆矩阵	三层记忆（文件+向量+SQLite）	`memory_manager.py`、Hindsight
⑦	技能进化	程序性记忆的创建、加载、更新	`skill_commands.py`、`skills/`
⑧	基础设施	Profile/Cron/MCP/Plugins/消息平台	`hermes_cli/config.py`、`cron/`

八大子系统逻辑拓扑（架构图 HTML 见本地文件）：

markdown 复制代码

                        ┌──────────────────────────────────┐
                        │        ① 入口层                  │
                        │  CLI · Gateway · ACP · WebUI     │
                        └──────────────┬───────────────────┘
                                       ▼
                        ┌──────────────────────────────────┐
                        │     ② 核心循环 run_agent.py     │
                        │    Agent Loop · 观察-思考-行动    │
                        └───────┬──────────┬───────────────┘
                                │          │
                   ┌────────────▼──┐  ┌────▼──────────────┐
                   │ ③ 提示词引擎  │  │ ④ 模型调度        │
                   │ Prompt Engine │  │ Provider & Model  │
                   └──────────┬────┘  └────┬──────────────┘
                              │            │
                   ┌──────────▼────────────▼──────────────┐
                   │      ⑤ 工具系统 · Tool System        │
                   │  70+ 工具 · 28 工具集 · 1 个注册表    │
                   └──────────────────┬───────────────────┘
                                      │
                   ┌──────────────────▼───────────────────┐
                   │  ⑥ 记忆矩阵 · Memory Matrix           │
                   │  MEMORY.md · Hindsight · state.db     │
                   └──────────────────┬───────────────────┘
                                      │
              ┌───────────────────────┼───────────────────────┐
              │                       │                       │
  ┌───────────▼──────────┐  ┌────────▼──────────┐
  │ ⑦ 技能进化 · Skills │  │ ⑧ 基础设施 Infra  │
  │ Skill Commands + 目录 │  │ Profile/Cron/MCP  │
  └──────────────────────┘  └───────────────────┘

① 入口层：不管你从哪来，最后都到同一个地方

Hermes Agent 设计了三个入口，覆盖了从个人开发到团队协作的全部场景：

入口	形式	文件	适用场景
CLI	终端交互	`cli.py` (14,442 行)	本地开发 / 日常使用
Gateway	HTTP API 服务	`gateway/run.py`	消息平台接入（Telegram/Discord/Slack）
ACP	Python 库 / 子进程	`acp_adapter/`	被其他程序嵌入调用
WebUI	浏览器界面	端口 8787	图形化操作
BatchRunner	批量模式	`batch_runner.py`	轨迹生成 / 评测

核心逻辑 ：三个入口只是"门"不同，进门之后全部汇入同一个 run_agent.py。这意味着你在 CLI 里调教好的 Agent 行为，在 Telegram 上完全一致------因为跑的是同一段代码。

② 核心循环：Agent 的"心跳"

如果说 Hermes Agent 有一个心脏，那就是 run_agent.py 里的 run_conversation() 方法。

sql 复制代码

用户输入 → 拼装 System Prompt → 注入记忆 → 调用 LLM 
→ LLM 返回（文本 or 工具调用）→ 执行工具 → 观察结果 
→ 再次调用 LLM → ... 循环直到任务完成 or 达到上限

这个循环就是 AI Agent 区别于普通聊天机器人的本质：它不是一问一答，而是一个观察-思考-行动-再观察的自主循环。

关键模块：

模块	文件	职责
AIAgent	`run_agent.py`	核心会话循环，串联所有子系统
常量定义	`hermes_constants.py`	`HERMES_HOME`、Profile 路径解析
批量运行	`batch_runner.py`	批量轨迹生成
显示格式化	`agent/display.py`	KawaiiSpinner（加载动画）、工具预览

③ 提示词引擎：每一次 API 请求背后的"拼图游戏"

每次调用 LLM 之前，Hermes 需要在短短几毫秒内完成一个复杂的"拼图"：

加载你的 SOUL.md（Agent 人格定义）
注入 MEMORY.md（持久记忆快照）
加载匹配的 Skills（程序性记忆）
拼接对话历史
注入工具定义（JSON Schema）
如果上下文太长 → 触发 context_compressor 压缩历史

模块	文件	职责
Prompt Builder	`agent/prompt_builder.py`	系统提示词组装（核心）
Context Engine	`agent/context_engine.py`	ContextEngine ABC，可插拔设计
Context Compressor	`agent/context_compressor.py`	有损摘要------长对话压缩
Prompt Caching	`agent/prompt_caching.py`	Anthropic 提示缓存（省 Token）
Auxiliary Client	`agent/auxiliary_client.py`	辅助 LLM（视觉、摘要等侧任务）

一个关键设计 ：ContextEngine 是抽象基类（ABC），意味着上下文管理策略是可插拔的。你可以写自己的 ContextEngine 实现，替换默认的有损摘要策略。

④ 模型调度：从"选了 DeepSeek"到"请求发出"

你在 CLI 里敲 /model deepseek/deepseek-v4-pro 后发生了什么？

bash 复制代码

用户选择模型名 → runtime_provider.py 解析 Provider 
→ auth.py 查找凭据（.env / vault / 环境变量）
→ model_metadata.py 获取上下文长度限制
→ anthropic_adapter.py 做 API 格式转换（如果需要）
→ 发出 HTTP 请求

模块	文件	职责
Runtime Provider	`hermes_cli/runtime_provider.py`	Provider → api_mode + 凭据
Auth	`hermes_cli/auth.py`	PROVIDER_REGISTRY，凭据解析
Models	`hermes_cli/models.py`	模型目录，Provider 模型列表
Model Switch	`hermes_cli/model_switch.py`	`/model` 命令逻辑（CLI + Gateway 共享）
Model Metadata	`agent/model_metadata.py`	上下文长度估算、Token 计数
Anthropic Adapter	`agent/anthropic_adapter.py`	OpenAI ↔ Anthropic API 格式互转
Config	`hermes_cli/config.py`	DEFAULT_CONFIG、配置迁移

生产环境补充：如果你用了 LiteLLM 网关（集中管理多个 Provider 的 API Key），那么模型调度链路里还多一层------Hermes → LiteLLM → 真实 Provider。这部分会在后续专题文章里展开。

⑤ 工具系统：Agent 的"手和脚"

LLM 本身只能"说"，不能"做"。工具系统让 Agent 拥有了真实的行动力。

Hermes Agent 内置 70+ 工具 ，分为 28 个工具集（toolsets），覆盖：

工具后端	数量	典型工具
终端	6 种后端	`terminal`、`process`、`execute_code`
浏览器	5 种后端	`browser_navigate`、`browser_click`、`browser_snapshot`
Web	4 种后端	`web_search`、`web_extract`
MCP	动态	外部 MCP Server 的工具全部自动注册
文件	---	`read_file`、`write_file`、`search_files`、`patch`
其他	---	`memory`、`session_search`、`delegate_task`、`cronjob`

核心架构 ：tools/registry.py 是中央注册表。每个工具文件在模块顶层调用 registry.register() 自注册。当 Agent 启动时，按 toolsets.py 的分组配置决定加载哪些工具。

模块	文件	职责
工具注册表	`tools/registry.py`	中央 Registry，工具自注册
工具发现分发	`model_tools.py`	Schema 采集、工具分发
工具分组	`toolsets.py`	28 个工具集，按平台/场景预设
工具实现	`tools/*.py` (70+)	每个工具一个文件

⑥ 记忆矩阵：Agent 不会忘记你

Hermes 的记忆系统不是单一数据库，而是 三层架构：

sql 复制代码

第一层：MEMORY.md + USER.md（文件记忆）
  ↓ 每次 Session 启动时作为快照注入 System Prompt
第二层：Hindsight（外部向量记忆服务）
  ↓ 语义搜索 + 实体图谱 + 重排序召回
第三层：state.db（SQLite + FTS5 全文索引）
  ↓ 会话历史、消息存储、session_search 全文检索

模块	文件	职责
Memory Manager	`agent/memory_manager.py`	记忆编排------协调三层记忆的读写
Memory Provider	`agent/memory_provider.py`	Memory Provider ABC（可插拔）
文件记忆	`MEMORY.md` + `USER.md`	原生记忆：偏好、画像、工作笔记
Hindsight	外部服务 (8888)	向量语义检索 + 实体图谱
会话状态	`hermes_state.py` + `state.db`	SQLite 会话存储 + FTS5 全文搜索

关键细节 ：MEMORY.md 只在 Session 启动时注入------会话中途写入的记忆要下次 Session 才生效。而 Hindsight 是实时可检索的。这两者的"生效时机"差异是一个常被忽略的坑。

⑦ 技能进化：Agent 学会的东西不会丢

技能（Skill）是 Hermes Agent 最具特色的一套系统。它不是预先写死的脚本，而是 Agent 在完成任务后自主提炼的可复用工作流。

当你完成一次复杂任务（5+ 次工具调用、踩过坑、最终成功），Agent 会：

总结这次任务的关键步骤
创建 SKILL.md（含 YAML 前置元信息 + Markdown 步骤）
存入 ~/.hermes/skills/<category>/<skill-name>/

下次遇到相似任务时，Agent 自动加载匹配的 Skill 作为"经验参考"。

模块	文件	职责
Skill 命令	`agent/skill_commands.py`	Skill 斜杠命令
Skill 存储	`~/.hermes/skills/`	程序性记忆文件目录
Skill 配置	`hermes_cli/skills_config.py`	`hermes skills` --- 按平台启用/禁用

此外还有 hermes_cli/commands.py 定义了 COMMAND_REGISTRY------所有 / 斜杠命令（包括 Skill 命令）的统一注册中心。

⑧ 基础设施：让 Agent 跑在生产环境

前七个子系统是 Agent 的"大脑和四肢"，第八个子系统是让它真正跑在生产环境里所需的地基：

模块	文件	职责
Profile	`hermes_constants.py`	多身份隔离------不同 Profile 有独立的 config/skills/memory
Cron	`cron/` + cronjob 工具	定时自主任务调度
MCP	MCP 适配层	Model Context Protocol------接入外部工具服务器
Plugins	`plugins/`	插件系统------工具/钩子/命令扩展
消息平台	`gateway/` 适配器	Telegram / Discord / Slack / WhatsApp / Signal
WebUI	前端项目	浏览器端聊天界面
Setup	`hermes_cli/setup.py`	交互式安装向导
Skin	`hermes_cli/skin_engine.py`	CLI 主题引擎

系列后续预告

今天只是把地图摊开。接下来的系列文章，会逐个子系统深入：

篇次	主题	核心问题
02	Agent Loop 深度拆解	`run_conversation()` 的每一次循环发生了什么？
03	提示词引擎	System Prompt 是如何从零拼装出来的？
04	工具系统	从 Tool Registry 到安全沙箱的全链路
05	记忆矩阵	MEMORY.md vs Hindsight vs state.db 的协同与边界
06	模型调度	Provider 解析、API 适配、多模型切换的 infra 设计
07	技能进化	Skill 如何被创建、加载、退化？
08	基础设施	Profile 隔离、Cron 调度、MCP 协议

模块速查总表

以下是本文覆盖的全部 37 个核心模块的文件索引：

#	模块	路径	子系统
1	CLI	`cli.py`	① 入口层
2	Gateway	`gateway/run.py`	① 入口层
3	ACP Adapter	`acp_adapter/`	① 入口层
4	WebUI	端口 8787	① 入口层
5	Batch Runner	`batch_runner.py`	① 入口层
6	AIAgent	`run_agent.py`	② 核心循环
7	Constants	`hermes_constants.py`	② 核心循环
8	Display	`agent/display.py`	② 核心循环
9	Prompt Builder	`agent/prompt_builder.py`	③ 提示词引擎
10	Context Engine	`agent/context_engine.py`	③ 提示词引擎
11	Context Compressor	`agent/context_compressor.py`	③ 提示词引擎
12	Prompt Caching	`agent/prompt_caching.py`	③ 提示词引擎
13	Auxiliary Client	`agent/auxiliary_client.py`	③ 提示词引擎
14	Runtime Provider	`hermes_cli/runtime_provider.py`	④ 模型调度
15	Auth	`hermes_cli/auth.py`	④ 模型调度
16	Models	`hermes_cli/models.py`	④ 模型调度
17	Model Switch	`hermes_cli/model_switch.py`	④ 模型调度
18	Model Metadata	`agent/model_metadata.py`	④ 模型调度
19	Anthropic Adapter	`agent/anthropic_adapter.py`	④ 模型调度
20	Tool Registry	`tools/registry.py`	⑤ 工具系统
21	Model Tools	`model_tools.py`	⑤ 工具系统
22	Toolsets	`toolsets.py`	⑤ 工具系统
23	Tool Implementations	`tools/*.py` (70+)	⑤ 工具系统
24	Memory Manager	`agent/memory_manager.py`	⑥ 记忆矩阵
25	Memory Provider	`agent/memory_provider.py`	⑥ 记忆矩阵
26	File Memory	`MEMORY.md` + `USER.md`	⑥ 记忆矩阵
27	Hindsight	外部服务 (8888)	⑥ 记忆矩阵
28	State DB	`hermes_state.py` + `state.db`	⑥ 记忆矩阵
29	Skill Commands	`agent/skill_commands.py`	⑦ 技能进化
30	Skill Store	`~/.hermes/skills/`	⑦ 技能进化
31	Skills Config	`hermes_cli/skills_config.py`	⑦ 技能进化
32	Command Registry	`hermes_cli/commands.py`	⑦ 技能进化
33	Setup Wizard	`hermes_cli/setup.py`	⑧ 基础设施
34	Config	`hermes_cli/config.py`	⑧ 基础设施
35	Skin Engine	`hermes_cli/skin_engine.py`	⑧ 基础设施
36	Cron	`cron/` + cronjob 工具	⑧ 基础设施
37	Session (Gateway)	`gateway/session.py`	⑧ 基础设施

本系列基于 Hermes Agent v0.15.2 源码分析。官方架构文档：hermes-agent.nousresearch.com/docs/develo...