Hermes Agent 原理与实战——第3章 整体架构与核心组件

理解 Hermes Agent 最高效的方式，是先看它的"系统总图"，再逐个拆解。本章探究 Hermes 的整体架构、Agent Loop 内部机制、Prompt 组装、Provider 运行时解析以及会话存储等核心技术。通过本章，你将建立起对 Hermes 整体架构的"心理模型"，理解它为何能在 CLI、Telegram、IDE、API Server 等十余种入口下保持行为一致，以及核心组件之间如何协同工作。

2.1 系统总图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

┌─────────────────────────────────────────────────────────────────────┐
│                          入口层（Entry Points）                       │
│                                                                      │
│  CLI (cli.py)       Gateway (gateway/run.py)      ACP (acp_adapter/) │
│  Batch Runner       API Server                    Python Library     │
└──────────┬──────────────┬───────────────────────┬───────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  Agent 核心（AIAgent，run_agent.py）                  │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │ Prompt       │  │ Provider     │  │ Tool         │               │
│  │ Builder      │  │ Resolution   │  │ Dispatch     │               │
│  │ (prompt_     │  │ (runtime_    │  │ (model_      │               │
│  │  builder.py) │  │  provider.py)│  │  tools.py)   │               │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                 │                       │
│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐               │
│  │ Compression  │  │ 3 API Modes  │  │ Tool Registry│               │
│  │ & Caching    │  │ chat_compl.  │  │ (registry.py)│               │
│  │              │  │ codex_resp.  │  │ 68 tools     │               │
│  │              │  │ anthropic    │  │ 52 toolsets  │               │
│  └──────────────┘  └──────────────┘  └──────────────┘               │
└─────────┴─────────────────┴─────────────────┴───────────────────────┘
           │                                    │
           ▼                                    ▼
┌───────────────────┐              ┌──────────────────────┐
│ 会话存储           │              │ 工具后端              │
│ Session Storage   │              │ Tool Backends         │
│ (SQLite + FTS5)   │              │ Terminal (7 backends) │
│ hermes_state.py   │              │ Browser (5 backends)  │
│ gateway/session.py│              │ Web (4 backends)      │
└───────────────────┘              │ MCP (动态)            │
                                   │ File / Vision / ...   │
                                   └──────────────────────┘

Hermes 的整体架构是典型的 “多入口 → 单一 Agent 核心 → 多种后端” 分层结构：无论你从哪个入口（ CLI、Telegram bot、API Server、ACP IDE 还是 Python 库调用）进入，最终都会汇入同一个 AIAgent 核心，由它统一编排"提示词构建、Provider 选择、工具调度、会话持久化"。

这个架构有以下几个关键特征：

第一，入口多样化： Hermes 不把自己限定为"一个终端程序"或"一个聊天机器人"。它通过 CLI、Gateway、ACP Adapter、API Server、Batch Runner 和 Python Library 六种形态对外暴露能力。

第二，核心单一化： 所有入口最终都调用 run_agent.py 中的 AIAgent 类。该核心对象负责从 prompt 组装、Provider 选择、工具调度、生成响应的完整对话循环。入口层只负责"如何把外部输入翻译成 OpenAI 格式的消息"以及"如何把 Agent 的输出渲染回外部界面"，不参与任何对话逻辑。

第三，后端可插拔： Provider 层支持 20 余家模型供应商和 3 种 API 模式；工具层支持 7 种终端后端、5 种浏览器后端、4 种 Web 后端以及动态 MCP 服务；存储层基于 SQLite + FTS5，支持全文检索和会话追踪。这种"多后端"设计让 Hermes 在模型选择、执行环境和数据持久化上都具备极高的自由度。

2.2 仓库目录速览

熟悉仓库目录结构有助于更好的理解系统架构。以下是按功能组织的精简版目录解读。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

hermes-agent/
├── run_agent.py              # AIAgent —— 核心对话循环（约 15,000 行）
├── cli.py                    # HermesCLI —— 交互式终端 UI（约 11,500 行）
├── model_tools.py            # 工具发现、schema 收集、调度
├── toolsets.py               # 工具分组与平台预设
├── hermes_state.py           # SQLite 会话/状态库（带 FTS5）
├── hermes_constants.py       # HERMES_HOME、profile-aware 路径
├── batch_runner.py           # 批量轨迹生成
│
├── agent/                    # Agent 内部模块
│   ├── prompt_builder.py     # 系统提示拼装
│   ├── context_engine.py     # ContextEngine 抽象（可插拔）
│   ├── context_compressor.py # 默认引擎：有损摘要压缩
│   ├── prompt_caching.py     # Anthropic prompt caching 标记
│   ├── auxiliary_client.py   # 辅助 LLM（视觉、摘要、压缩）
│   ├── model_metadata.py     # 模型上下文长度、token 估算
│   ├── models_dev.py         # models.dev 注册表
│   ├── anthropic_adapter.py  # Anthropic Messages API 适配
│   ├── display.py            # KawaiiSpinner、工具预览渲染
│   ├── skill_commands.py     # 技能斜杠命令
│   ├── memory_manager.py     # 记忆管理编排
│   ├── memory_provider.py    # 记忆 Provider 抽象基类
│   └── trajectory.py         # 轨迹保存
│
├── hermes_cli/               # CLI 子命令与 setup
│   ├── main.py               # 入口：所有 `hermes` 子命令（约 10,400 行）
│   ├── config.py             # DEFAULT_CONFIG、OPTIONAL_ENV_VARS、迁移
│   ├── commands.py           # COMMAND_REGISTRY —— 集中式斜杠命令定义
│   ├── auth.py               # PROVIDER_REGISTRY、凭据解析
│   ├── runtime_provider.py   # Provider → api_mode + credentials
│   ├── models.py             # 模型目录、各家模型列表
│   ├── model_switch.py       # /model 命令逻辑（CLI 与 gateway 共享）
│   ├── setup.py              # 交互式 setup 向导（约 3,500 行）
│   ├── skin_engine.py        # CLI 主题引擎（皮肤）
│   ├── skills_config.py      # hermes skills —— 按平台启用/禁用
│   ├── skills_hub.py         # /skills 斜杠命令
│   ├── tools_config.py       # hermes tools —— 按平台启用/禁用
│   ├── plugins.py            # PluginManager：插件发现、加载、hook
│   ├── callbacks.py          # 终端回调（澄清、sudo、审批）
│   └── gateway.py            # hermes gateway start/stop
│
├── tools/                    # 工具实现（每个工具一个文件）
│   ├── registry.py           # 中央工具注册表
│   ├── approval.py           # 危险命令检测
│   ├── terminal_tool.py      # 终端编排
│   ├── process_registry.py   # 后台进程管理
│   ├── file_tools.py         # read_file、write_file、patch、search_files
│   ├── web_tools.py          # web_search、web_extract
│   ├── browser_tool.py       # 10 个浏览器自动化工具
│   ├── code_execution_tool.py # execute_code 沙箱
│   ├── delegate_tool.py      # 子代理委派
│   ├── mcp_tool.py           # MCP 客户端（约 3,100 行）
│   ├── credential_files.py   # 文件型凭据透传
│   ├── env_passthrough.py    # 环境变量透传到沙箱
│   ├── ansi_strip.py         # ANSI 转义清理
│   └── environments/         # 终端后端（local、docker、ssh、modal、daytona、singularity）
│
├── gateway/                  # 消息网关
│   ├── run.py                # GatewayRunner：消息分发（约 12,200 行）
│   ├── session.py            # SessionStore：对话持久化
│   ├── delivery.py           # 出站消息投递
│   ├── pairing.py            # DM 配对授权
│   ├── hooks.py              # Hook 发现与生命周期事件
│   ├── mirror.py             # 跨会话消息镜像
│   ├── status.py             # token 锁、profile 进程跟踪
│   └── platforms/            # 20 个平台 adapter：telegram、discord、slack、whatsapp 等
│
├── acp_adapter/              # ACP（Agent Client Protocol）适配器,VS Code/Zed/JetBrains
├── acp_registry/             # ACP 注册表
├── plugins/memory/           # 记忆提供者插件
├── plugins/context_engine/   # 上下文引擎插件
├── skills/                   # 内置技能集
├── optional-skills/          # 可选官方技能集
├── cron/                     # cron 调度器实现（jobs.py、scheduler.py）
├── scripts/                  # 安装、构建、运行测试脚本
├── docker/                   # docker 沙箱镜像与脚本
├── environments/             # Atropos RL 环境
├── pyproject.toml            # 包定义、可选依赖
└── setup-hermes.sh           # 一键开发者初始化

2.3 入口层：六种调用方式

Hermes 不是单一形态的程序，它通过六种入口对外提供同一个 AIAgent。

第1种、CLI 与 TUI（cli.py）

这是最常用的入口。在终端中输入 hermes 即可启动交互式会话。

CLI 入口的核心特性包括：

• 多行输入与斜杠命令补全：支持输入多行文本，以及 / 开头的斜杠命令自动补全；
• 流式输出与实时预览：模型生成内容时逐字显示，工具调用前会先展示工具预览（如"正在调用 terminal: ls -la"）；
• 可中断执行：Ctrl+C 可随时打断当前 API 调用或工具执行，且支持"边打断边发新消息"，无需等待上一次调用完成；
• 可换肤的视觉元素：Kawaii Spinner 等动画元素可通过 skin_engine.py 更换主题；
• 丰富的斜杠命令：/model 切换模型、/personality 切换人格、/new 新建会话、/reset 清空历史、/compress 手动压缩、/usage 查看用量、/insights 查看统计、/skills 管理技能、/<skill-name> 直接触发技能、/rollback 回滚到指定轮次、/checkpoint 打检查点、/cron 管理定时任务、/kanban 管理看板等。

CLI 的数据流如下：

1
2
3
4
5
6
7

用户输入 → HermesCLI.process_input()
  → AIAgent.run_conversation()  # 调用 AIAgent
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API 调用（chat_completions / codex_responses / anthropic_messages）
    → tool_calls? → model_tools.handle_function_call() → 循环
    → 最终响应 → 显示 → 保存至 SessionDB

第2种、Gateway（gateway/run.py）

hermes gateway start 启动一个常驻进程，把同一个 Agent 暴露给 20 余种消息平台，。每个平台都有独立的 adapter 实现，位于 gateway/platforms/<name>.py，遵循统一的 GatewayMessage 接口。

Gateway 支持的平台包括：Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、企业微信、飞书、钉钉、QQ、Yuanbao（腾讯元宝）、Open WebUI、Webhooks、Home Assistant 等。

Gateway 的核心价值在于解耦：平台 adapter 只负责"把平台消息格式翻译成标准openAI消息格式"，所有对话逻辑都在 AIAgent 中完成。这意味着一旦某个平台的消息协议发生变化，只需修改对应的 adapter 文件，无需触碰核心逻辑。

Gateway 的数据流如下：

1
2
3
4
5
6
7

平台事件 → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → 授权用户
    → 解析会话 key
    → 创建带会话历史的 AIAgent
    → AIAgent.run_conversation()
    → 通过适配器回传响应

第3种、 ACP Adapter（acp_adapter/）

ACP（Agent Client Protocol）是 Zed Industries 联合 JetBrains 在 2025 年推出的开放开源标准协议，类比 LSP（Language Server Protocol），专门标准化IDE / 编辑器（Client） ↔ AI Agent之间通信。已被 VS Code、Zed、JetBrains 等主流编辑器支持。Hermes 的 ACP Adapter 通过 stdio/JSON-RPC 与 IDE 通信，让开发者可以在 IDE内直接跟 Hermes 对话，工具调用、文件 diff、执行终端命令。

与其他入口相比，ACP 的独特之处在于上下文富化：IDE 可以自动把当前打开的文件、光标位置、选中的代码块作为上下文传递给 Agent。工具调用的结果（如文件修改、diff、终端输出）也会以 IDE 原生格式渲染，提供无缝的编程体验。

第4种、API Server

hermes api start 暴露一个 OpenAI-compatible HTTP 端点。任何兼容 OpenAI Chat API 的前端——如 Open WebUI、LobeChat、LibreChat、ChatBox 等——都可以直接接入 Hermes。

这相当于把 Hermes 变成了"你的私有 ChatGPT"，但背后拥有 Hermes 的全部能力：工具调用、会话持久化、多 Provider 切换、记忆系统等。

第5种、Batch Runner（batch_runner.py）

hermes batch run 用于在大量 prompt 上并行跑 Agent，输出结构化的 ShareGPT-format 轨迹数据，主要用于训练数据生成与评测。

Batch Runner 的典型用途包括：

• 生成大规模工具调用训练数据；
• 对不同模型进行 A/B 评测；
• 批量处理文档、代码审查等重复性任务。

第6种、Python Library

Hermes 也可以作为 Python 库直接嵌入你的程序：

1
2
3
4

from run_agent import AIAgent

agent = AIAgent(model="anthropic/claude-opus-4.6")
print(agent.chat("帮我把这个 CSV 转成 SQL INSERT 语句"))

这是最简单、最轻量的调用方式。AIAgent 对象初始化后，可以通过 chat() 或 run_conversation() 方法发起对话。

2.4 主要子系统

2.4.1 Agent 核心：AIAgent

run_agent.py 中的 AIAgent 类是 Hermes 的"心脏"，核心编排引擎。它的职责包括以下八个方面：

1. Prompt 组装：通过 prompt_builder.py 拼装系统提示与工具 schema；
2. Provider 选择：选择合适的 Provider 与 API 模式（chat_completions / codex_responses / anthropic_messages）；
3. 可中断调用：发起 可中断 的模型调用（_interruptible_api_call，支持随时打断）；
4. 工具执行：顺序或并发执行工具调用（带线程池）；
5. 会话历史维护：维护 OpenAI 格式的对话历史；
6. 容错处理：执行压缩、重试、回退、Provider 故障切换；
7. 预算追踪：跟踪父子 Agent 的迭代预算；
8. 记忆持久化：在上下文丢失前将持久化记忆刷写到磁盘。

1)、两个入口方法

AIAgent 对外暴露两个主要接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 简单接口 —— 返回最终响应字符串
response = agent.chat("Fix the bug in main.py")

# 完整接口 —— 返回包含消息、元数据、用量统计的 dict
result = agent.run_conversation(
    user_message="Fix the bug in main.py",
    system_message=None,           # 省略时自动构建
    conversation_history=None,      # 省略时自动从 session 加载
    task_id="task_abc123"
)

chat() 本质上是对 run_conversation() 的轻量封装，从结果字典中提取 final_response 字段。

2)、单轮生命周期

Agent Loop 的每次迭代（Turn）按以下严格顺序执行（即一次会话的处理流程）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

run_conversation()
  1. 若未提供则生成 task_id
  2. 将用户消息追加到对话历史
  3. 构建或复用已缓存的系统 prompt（prompt_builder.py）
  4. 检查是否需要预检压缩（上下文超过 50%）
  5. 从对话历史构建 API 消息
     - chat_completions：直接使用 OpenAI 格式
     - codex_responses：转换为 Responses API 输入项
     - anthropic_messages：通过 anthropic_adapter.py 转换
  6. 注入临时 prompt 层（预算警告、上下文压力提示）
  7. 若使用 Anthropic，应用 prompt 缓存标记
  8. 发起可中断的 API 调用（_interruptible_api_call）
  9. 解析响应：
     - 若有 tool_calls：执行工具，追加结果，回到步骤 5
     - 若为文本响应：持久化 session，按需刷写内存，返回

这个循环的精妙之处在于状态管理。当模型返回工具调用时，循环不会退出，而是把工具执行结果追加到对话历史，然后重新回到步骤 5 发起下一轮 API 调用。这种"推理 → 行动 → 观察 → 再推理"的模式，正是 ReAct（Reasoning + Acting）范式的工程实现。

3)、三种 API 模式

Hermes 支持三种 API 执行模式，通过 Provider 选择、显式参数和 base URL 启发式规则来确定。

模式选择优先级：构造参数 > Provider 检测 > base URL 启发式 > 默认 chat_completions。三种模式的消息编码、工具调用结构、流式与缓存机制都不同，但内部统一收敛为 OpenAI 风格的 role/content/tool_calls 字典。

4)、消息交替规则

所有消息在内部均使用兼容 OpenAI 的格式：

1
2
3
4

{"role": "system", "content": "..."}
{"role": "user", "content": "..."}
{"role": "assistant", "content": "...", "tool_calls": [...]}
{"role": "tool", "tool_call_id": "...", "content": "..."}

Agent Loop 强制执行严格的消息角色交替规则：

• 系统消息之后：User → Assistant → User → Assistant → ...。
• 工具调用期间：Assistant（含 tool_calls）→ Tool → Tool → ... → Assistant。
• 不允许连续出现两条 assistant 消息。
• 不允许连续出现两条 user 消息。
• 只有 tool 角色可以连续出现（并行工具结果）。

Provider 会验证这些序列，并拒绝格式错误的历史记录。Hermes 在构建 API 消息时会自动修复常见的交替错误，例如把连续的用户消息合并为一条，或在 tool_calls 后插入必要的 tool 响应。

2.4.2 Prompt 构建：冻结快照与槽位设计

系统提示由若干"槽位"组成，按固定顺序拼装。每个槽位都有清晰职责：

1. Agent 身份（Identity）：优先使用 ~/.hermes/SOUL.md，否则回退到 prompt_builder.py 中的 DEFAULT_AGENT_IDENTITY
2. 工具感知行为指导：如何正确使用工具、何时使用 session_search 回忆历史、对 GPT/Codex 模型的工具使用强制要求等
3. Honcho 静态块（激活时）：来自 Honcho 记忆 Provider 的人格/上下文数据。
4. 可选系统消息：来自 config 或 API 参数的用户配置覆盖。
5. 冻结MEMORY （环境/工作约定）快照：来自 ~/.hermes/memories/MEMORY.md 的持久记忆，约 800 token；
6. 冻结USER PROFILE（用户画像）快照：来自 ~/.hermes/memories/USER.md的用户画像，约 500 token；
7. Skills 索引：当前可用技能的 {name, description, category} 列表，约 3k token
8. 上下文文件：自动发现项目级文档 .hermes.md、AGENTS.md、CLAUDE.md、.cursorrules 等。
9. 时间戳 / 可选会话 ID。
10. 平台提示：如"You are a CLI AI Agent. Try not to use markdown…"

当设置了 skip_context_files（例如子 agent 委托）时，不会加载 SOUL.md，而是使用硬编码的 DEFAULT_AGENT_IDENTITY。

关键设计：记忆与身份采用**冻结快照（frozen snapshot）**模式：记忆与身份在会话开始时一次性注入系统 prompt，期间即便 Agent 修改了文件，已构建的系统 prompt 也不会改变。这有两大好处：

• 保留缓存命中率：Anthropic 的 prefix cache 要求系统 prompt 前缀保持稳定。如果每轮都重新加载记忆文件，缓存会频繁失效，导致 token 成本大幅上升。
• 语义清晰性：Agent 在单轮对话中看到的"记忆"是静态的，不会因自己的写入操作而产生自我引用混乱。最新的记忆值始终通过 tool response 返回给 Agent。

具体示例：组装后的系统 prompt

以下是所有层都存在时最终系统 prompt 的简化视图（注释说明每个部分的来源）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# Layer 1: Agent Identity (from ~/.hermes/SOUL.md)
You are Hermes, an AI assistant created by Nous Research.
You are an expert software engineer and researcher.
You value correctness, clarity, and efficiency.
...

# Layer 2: Tool-aware behavior guidance
You have persistent memory across sessions. Save durable facts using
the memory tool: user preferences, environment details, tool quirks,
and stable conventions. Memory is injected into every turn, so keep
it compact and focused on facts that will still matter later.
...
When the user references something from a past conversation or you
suspect relevant cross-session context exists, use session_search
to recall it before asking them to repeat themselves.

# Tool-use enforcement (for GPT/Codex models only)
You MUST use your tools to take action — do not describe what you
would do or plan to do without actually doing it.
...

# Layer 3: Honcho static block (when active)
[Honcho personality/context data]

# Layer 4: Optional system message (from config or API)
[User-configured system message override]

# Layer 5: Frozen MEMORY snapshot
## Persistent Memory
- User prefers Python 3.12, uses pyproject.toml
- Default editor is nvim
- Working on project "atlas" in ~/code/atlas
- Timezone: US/Pacific

# Layer 6: Frozen USER profile snapshot
## User Profile
- Name: Alice
- GitHub: alice-dev

# Layer 7: Skills index
## Skills (mandatory)
Before replying, scan the skills below. If one clearly matches
your task, load it with skill_view(name) and follow its instructions.
...
<available_skills>
  software-development:
    - code-review: Structured code review workflow
    - test-driven-development: TDD methodology
  research:
    - arxiv: Search and summarize arXiv papers
</available_skills>

# Layer 8: Context files (from project directory)
# Project Context
The following project context files have been loaded and should be followed:

## AGENTS.md
This is the atlas project. Use pytest for testing. The main
entry point is src/atlas/main.py. Always run `make lint` before
committing.

# Layer 9: Timestamp + session
Current time: 2026-03-30T14:30:00-07:00
Session: abc123

# Layer 10: Platform hint
You are a CLI AI Agent. Try not to use markdown but simple text
renderable inside a terminal.

2.4.3 Provider 运行时：模型选择与故障切换

hermes_cli/runtime_provider.py + agent/auxiliary_client.py 协同决定每次调用走哪家：

• Provider Routing：多家 Provider 排序成优先级链；
• Fallback Providers：主 Provider 报错（限流/网络/5xx）时自动切到下一家；视觉、压缩等辅助任务可以走单独的 fallback；
• Credential Pool：同一家 Provider 可挂多把 Key，按 round-robin / 限流自动轮换；
• Auxiliary Client：视觉描述、长 chat 摘要、压缩等"次要任务"走更便宜/更快的辅助模型。

模式解析顺序：显式 api_mode 参数 → Provider 特定检测（anthropic → anthropic_messages）→ Base URL 启发式（api.anthropic.com → anthropic_messages）→ 默认 chat_completions。

三种模式只是"运输方式"不同，内部统一收敛为 OpenAI 风格的 role/content/tool_calls 字典，可无感切换。

2.4.4 工具运行时

工具系统是 Hermes 与外部世界交互的"手脚"。它由三层组成：Registry（注册表）、Toolsets（分组）和 Dispatch（调度）。

1）三层架构

工具系统由三层组成：

1. Registry：tools/registry.py 集中注册全部工具，每个工具是一个 Python 函数 + JSON Schema；
2. Toolsets：toolsets.py 把工具按用途分组（web、terminal、file、browser、memory、delegation 等共 52 组）；同时维护 平台预设（hermes-cli、hermes-telegram、hermes-discord、hermes-wecom 等），定义"在某平台默认开哪些组"；
3. Dispatch：model_tools.py 在每次推理前把当前启用的工具 schema 收集起来作为可用工具列表，模型返回 tool_calls 后再调度执行。

2）工具发现机制

工具注册发生在导入时，早于任何 Agent 实例的创建。依赖链如下：

1
2
3
4
5
6
7

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

任何在顶层调用 registry.register() 的 tools/*.py 文件都会被自动发现——无需手动维护导入列表。这种设计让新增工具变得极其简单：创建一个 Python 文件，写好函数和 schema，调用 register()，重启 Hermes 即可生效。

3）终端工具

终端工具是 Hermes 最强大的工具之一，支持 7 种后端：

切换只需一条命令：hermes config set terminal.backend docker。不同后端共享相同的工具接口（terminal 工具的参数和返回值格式一致），Agent 无需关心命令实际运行在哪个环境中。

4）工具审批与安全

工具执行支持 并发（tool_concurrency） 与 审批回调（approval）：

• 危险命令（rm -rf /、修改 /etc、数据库删除等）会触发 tools/approval.py 的检测；
• CLI 用户会看到一个"是否允许"的交互式 prompt；
• Gateway 用户可以接到 DM 配对授权流程；
• 用户可在 ~/.hermes/config.yaml 中添加白名单，跳过特定命令的审批。

2.4.5 会话存储：SQLite + FTS5

Hermes 使用单一 SQLite 数据库 ~/.hermes/state.db 持久化所有会话数据。这替代了早期的逐会话 JSONL 文件方案，提供了更强的查询能力和一致性保证。

存储内容：

• 每条对话历史（与 OpenAI 格式 1:1 对应，便于恢复）；
• 任务（task_id）、迭代、token usage、cost；
• 工具调用日志、轨迹；
• Skills 元数据；
• Cron 任务与执行历史。

Kanban 独立使用 kanban.db。启用 FTS5 全文索引，让 session_search 工具可快速检索。Gateway 自己也维护一份 gateway/session.py 中的 SessionStore，多平台对话与 Profile 相互隔离。

会话具有血缘追踪（跨压缩的父/子关系）、按平台隔离，以及带竞争处理的原子写入。

2.4.6 学习闭环：Memory + Skills + Curator + Honcho

Hermes 的"自我提升"机制由 4 个协作模块构成，形成从记忆沉淀→生成技能→自动梳理→用户精细化建模的完整闭环：

1. Memory Manager（agent/memory_manager.py）：Memory Manager 是记忆系统的编排中枢。它向 Agent 暴露 memory(action=add|replace|remove, target=memory|user, content=...) 工具，让 Agent 在对话中随时读写持久记忆。

   记忆分为两类：

   • MEMORY.md：环境约定、项目规范、工具 quirks 等"事实性"记忆，约 800 token；
   • USER.md：用户画像、偏好、习惯等"人格性"记忆，约 500 token。

   这两份文件在会话开始时作为冻结快照注入系统 prompt。Agent 的写入操作会更新磁盘文件，但不会修改当前会话的系统 prompt——直到新会话开始时才生效。

2. Skills Manager（hermes_cli/skills_config.py + skills/）：管理 ~/.hermes/skills/ 下的所有技能；自动把每个技能注册成 /<skill-name> 斜杠命令；Skills 采用进度披露式加载（progressive disclosure）：

   • Level 0：仅注入 Skills 索引（{name, description, category} 列表），约 3k token；
   • Level 1：当 Agent 调用 skill_view(name) 时，注入该 Skill 的全文；
   • Level 2：Skill 引用文件按需加载。

   这种设计让 Agent 在"知道有什么技能"和"知道技能详细内容"之间取得了平衡。

3. Curator：Curator 是一个周期性"提示"机制。它会在适当时机（如会话结束、空闲时段）提醒 Agent 整理记忆、搬运重要事实、识别可技能化的步骤。

   Curator 的工作包括：

   • 识别对话中反复出现的模式，建议写入 MEMORY.md；
   • 发现用户偏好的变化，更新 USER.md；
   • 识别可复用的工作流，提示创建新 Skill；
   • 清理过时或冗余的记忆条目。

4. Honcho Memory Provider（plugins/memory/honcho/）：Honcho 是一个可选的辩证用户建模后端，把零散的"用户偏好"整合成更紧凑的 `USER.md。与普通记忆系统不同，Honcho 不简单地"追加"用户偏好，而是：

   • 收集零散的"用户偏好"证据；
   • 进行辩证推理（考虑矛盾偏好、时效性变化）；
   • 整合成更紧凑、更准确的 USER.md。

   这种"建模"而非"记录"的方式，能显著减少用户画像中的噪声和矛盾。

这四大模块联动形成可持续自进化体系，让 Agent 在你的工作流里"越用越聪明"。

2.4.7 Gateway 内部：多平台分发

Gateway 是 Hermes 连接外部消息平台的桥梁。它把平台细节与 Agent 核心完全解耦，支持 Hermes 同时对接 20 +种消息平台。

1
2
3
4
5
6
7
8

Telegram / Discord / Slack / WeCom / Feishu / DingTalk / ...
                ↓ Adapter 把平台事件统一为 GatewayMessage
        gateway/run.py 的 GatewayRunner（消息泵）
                ↓ 根据 conversation_id 找对应 SessionStore 的会话
              AIAgent.run_conversation(...)
                ↓ 文本/语音/图片附件 → 转成 OpenAI 格式
              gateway/delivery.py 出站投递
                ↓ 按平台 adapter 还原成 Telegram/Discord/Slack 的消息

关键能力：

• DM Pairing：陌生人发起对话需要先经过授权。默认情况下，所有 IM 平台拒绝未授权的私聊（DM），只有显式配对的用户才能让 Agent 干活。这是防止 Agent 被滥用的第一道防线。
• Cross-Session Mirror（gateway/mirror.py）：在不同平台的对话之间镜像消息，实现"在 Telegram 跟它说话，在 Slack 也能看到上下文"；
• Status / Token Lock（gateway/status.py）：Profile 被多个进程同时启动。当 Gateway 正在运行时，CLI 或其他 Gateway 实例会检测到锁文件并给出友好提示。
• Hooks（gateway/hooks.py）：基于 ~/.hermes/hooks/ 下的 HOOK.yaml + handler.py 监听生命周期事件。可监听的事件包括 agent:start、agent:end、command:*、message:received、message:sent 等。Hooks 让 Hermes 能集成自定义的告警、日志、审批流程。

2.4.8 自动化层：Cron、Kanban、Webhook

除了即时对话，Hermes 还提供三种自动化机制，把它从"对话助手"升级为"自动化操作系统"。

1）Cron 调度器（cron/）

cron/ 模块独立维护一份调度表，每个 job 都跑在全新的 Agent 会话中。这意味着：

• 定时任务不会污染你的主会话历史；
• 每个任务都有独立的迭代预算和容错机制；
• 可以挂 0/1/N 个 skill，让任务按预定义工作流执行；
• 可以指定结果投递目标（telegram://chat_id、wecom、邮件、文件等）。

Cron 任务以 JSON 格式存储，支持多种调度格式（类 crontab 表达式、自然语言时间等）。

2）Kanban 看板（hermes kanban）

hermes kanban + kanban_* 工具组提供了多 Profile 协作的 SQLite 任务板。

Kanban 与 delegate_task 的区别在于持久化和可恢复性：

• delegate_task 是"一次性"的子 Agent 委派，任务完成后子 Agent 销毁；
• Kanban 是"持久化"的任务板，任务可以在多个 Profile 之间流转，支持人工介入、状态跟踪、历史回溯。

Kanban 适合"需要跨天执行、持久化、可恢复、需要人审批介入"的复杂工作流。

3）Webhook 集成

Gateway 的 webhook 平台 adapter 可以接收外部事件（GitHub PR、Stripe 支付、Slack action）并 trigger Hermes 任务。

典型场景：

• GitHub PR 创建 → Webhook → Hermes 执行代码审查 → 在 PR 中发表评论；
• Stripe 支付成功 → Webhook → Hermes 发送确认邮件；
• Slack action 点击 → Webhook → Hermes 执行指定工作流。

2.4.9 安全与隔离

Hermes 把"安全"作为一等公民：

• 危险命令检测：tools/approval.py 内置了多层危险命令检测：正则模式匹配 rm -rf /、mkfs.*、dd if=/dev/zero 等高危命令；用户可在 ~/.hermes/config.yaml 加白名单；
• Container Isolation：Docker 后端默认运行用户级容器，--read-only：根文件系统只读；--cap-drop=ALL：丢弃所有 Linux capabilities；--network=none：禁止网络访问等可选；
• DM Pairing：所有 IM 平台默认拒绝未授权 DM，只有显式配对的用户才能让 Agent 干活；
• Credential Files：API Key、SSH key 等敏感信息通过 tools/credential_files.py 以文件形式透传到沙箱，避免直接 export 到环境变量。这减少了凭据在进程列表、日志、崩溃报告中泄露的风险。

2.11 研究与训练：Atropos / Trajectory

Hermes 把日常 Agent 跑出来的对话/工具调用直接当成 RL 训练数据：

• batch_runner.py 跑大量 prompt，输出 ShareGPT/Trajectory；
• environments/ 里实现了若干 Atropos 兼容的 RL 环境；
• trajectory_compressor.py 提供轨迹压缩，便于训练；
• tinker-atropos、mini_swe_runner.py 等脚手架让研究者能直接基于 Hermes 训练新一代工具调用模型，无需从零构建环境。

2.5 设计原则

Hermes 的六项核心设计原则，它们是理解架构决策的"北极星"：

2.6 关键概念词典

本章小结

本章建立了 Hermes 架构的完整"心智模型"。用十个要点回顾：

1. 多入口、单核心、多后端的分层结构是 Hermes 的骨架。CLI、Gateway、ACP、API Server、Batch Runner、Python Library 六种形态共享同一个 AIAgent 核心。

2. AIAgent 是心脏。这个核心类负责 Prompt 组装、Provider 选择、工具调度、历史维护、容错处理、预算追踪和记忆持久化。

3. 三种 API 模式（chat_completions、codex_responses、anthropic_messages）让 Hermes 能跨 OpenAI/Codex/Anthropic 不变形地使用工具调用。模式选择遵循"构造参数 > Provider 检测 > base URL 启发式 > 默认"的优先级链。

4. Prompt 由 10 个槽位拼成，采用冻结快照与进度披露两种机制平衡 token 消耗与信息新鲜度。系统 prompt 在会话期间保持稳定，以最大化 Provider 侧缓存命中率。

5. Provider Runtime 通过解析优先级链、Fallback Providers、Credential Pool 和 Auxiliary Client，解决了"模型自由度"问题——用户可以在数十家 Provider 之间无缝切换。

6. 7 种终端后端（local、docker、ssh、modal、daytona、singularity、tmux）解决了"运行环境自由度"问题。切换只需一条配置命令，工具接口完全统一。

7. SQLite + FTS5 是会话与任务的统一存储。FTS5 支持全文搜索。

8. Memory + Skills + Curator + Honcho 形成学习闭环。Agent 在日常对话中积累记忆、提炼技能、更新用户画像，实现"越用越聪明"。

9. Gateway 通过统一 Adapter 接口让 Hermes 同时在 20+ 平台上活着。DM Pairing、Cross-Session Mirror、Hooks 等机制保证了安全性与可扩展性。

10. Cron + Kanban + Webhook 把 Hermes 从"对话助手"升级为自动化操作系统，支持定时任务、持久化工作流和外部事件触发。

理解这些概念后，你已经具备了阅读 Hermes 源码、排查问题和定制扩展所需的全景视角。