第一章 架构总览

理解 Hermes Agent 的内部架构，是定制和扩展的基础。本章带你从全局视角俯瞰整个系统。

系统架构图

┌───────────────────────────────────────────────────┐
│                   入口层                           │
│                                                    │
│   CLI (cli.py)  ──  Gateway (gateway/)  ──  ACP   │
│   批处理 runner    API Server         Python 库    │
└──────┬──────────────┬──────────────────┬──────────┘
       │              │                  │
       ▼              ▼                  ▼
┌───────────────────────────────────────────────────┐
│              AIAgent (run_agent.py)                │
│              核心对话循环                           │
│                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Prompt   │  │ Provider │  │  Tool    │        │
│  │ Builder  │  │ Resolver │  │ Dispatch │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
│       │              │              │              │
│  ┌────┴─────┐  ┌────┴─────┐  ┌────┴─────┐        │
│  │压缩与缓存 │  │ 3种API模式│  │Tool Registry│      │
│  │          │  │ chat/codex│  │ 47+ 工具   │      │
│  │          │  │ /anthropic│  │ 20 工具集  │      │
│  └──────────┘  └──────────┘  └──────────┘        │
└───────────────────────────────────────────────────┘
       │                              │
       ▼                              ▼
┌──────────────┐              ┌──────────────┐
│ Session 存储  │              │  工具后端     │
│ SQLite+FTS5  │              │ Terminal(6)  │
│              │              │ Browser      │
│              │              │ File         │
│              │              │ Web          │
│              │              │ Cron         │
└──────────────┘              └──────────────┘

---

核心子系统

1. Agent Loop（核心循环）

Agent Loop 是 Hermes 的心脏，位于 run_agent.py（约 9,200 行）。它是一个同步编排引擎，处理：

• Provider 选择与回退
• Prompt 构建与维护
• 工具执行与结果处理
• 重试与错误处理
• 上下文压缩
• 会话持久化

工作流程：

用户消息 → Prompt 构建 → LLM 调用 → 解析响应
                                         ↓
                                    有工具调用？
                                    ├─ 是 → 执行工具 → 结果加入上下文 → 再次调用 LLM
                                    └─ 否 → 返回文本响应 → 结束

2. Provider Resolution（模型路由）

共享的运行时解析器，被 CLI、Gateway、Cron、ACP 共同使用。

• 支持 18+ 提供商
• 三种 API 模式：chat_completion、codex_response、anthropic
• OAuth 流程处理
• Credential Pool（多 Key 轮换）
• 别名解析（如 zai = glm）

3. Tool System（工具系统）

中央工具注册表位于 tools/registry.py：

• 47 个注册工具，分布在 20 个工具集中
• 每个工具文件在 import 时自注册
• 支持 6 种终端后端（local、Docker、SSH、Daytona、Modal、Singularity）
• Schema 收集、调度、可用性检查

4. Session Storage（会话存储）

基于 SQLite + FTS5 全文搜索：

• 会话有血缘追踪（压缩前后的父子关系）
• 按平台隔离
• 原子写入与并发处理

5. Messaging Gateway（消息网关）

长运行进程，包含：

• 14 个平台适配器
• 统一的会话路由
• 用户授权（Allowlist + DM 配对）
• 斜杠命令分发
• Hook 系统
• Cron 定时检查
• 后台维护任务

6. Plugin System（插件系统）

三个发现源：

• ~/.hermes/plugins/（用户级）
• .hermes/plugins/（项目级）
• pip entry points

两种专用插件类型：

• Memory Provider：外部记忆服务（Honcho、Mem0 等）
• Context Engine：上下文处理引擎

---

目录结构

hermes-agent/
├── run_agent.py              # AIAgent 核心循环 (~9,200 行)
├── cli.py                    # CLI 交互界面 (~8,500 行)
├── model_tools.py            # 工具发现、Schema 收集、调度
├── toolsets.py               # 工具集分组与平台预设
├── hermes_state.py           # SQLite 会话/状态数据库
├── hermes_constants.py       # HERMES_HOME、Profile 路径
│
├── agent/                    # Agent 内部模块
│   ├── prompt_builder.py     # 系统 Prompt 组装
│   ├── context_compressor.py # 上下文压缩
│   ├── auxiliary_client.py   # 辅助 LLM 调用
│   ├── memory_manager.py     # 记忆管理
│   └── ...
│
├── hermes_cli/               # CLI 子命令
│   ├── main.py               # 所有 hermes 子命令
│   ├── config.py             # 默认配置
│   ├── commands.py           # 斜杠命令注册
│   ├── auth.py               # 提供商认证
│   └── ...
│
├── tools/                    # 工具实现
│   ├── registry.py           # 工具注册中心
│   ├── terminal.py           # 终端工具
│   ├── browser.py            # 浏览器工具
│   └── ...
│
├── gateway/                  # 消息网关
│   ├── run.py                # Gateway 入口
│   ├── adapters/             # 平台适配器
│   └── ...
│
└── plugins/                  # 插件系统
    ├── memory/               # 记忆提供商插件
    └── context_engine/       # 上下文引擎插件

---

设计原则

Hermes Agent 遵循几个核心设计原则：

1. 自注册模式

工具在 import 时自动注册。添加新工具只需：

1. 创建工具文件
2. 在 model_tools.py 的 _discover_tools() 中添加 import

2. 配置驱动

行为由配置决定，不是代码决定。大部分定制可以通过 config.yaml 和 .env 完成。

3. 失败安全

所有关键操作遵循 fail-closed 原则：

• 审批超时 → 拒绝
• API 失败 → 回退到 fallback model
• 会话写入 → 原子操作

4. 渐进式复杂度

• 新手：用默认配置直接跑
• 进阶：修改 config.yaml
• 高级：开发自定义 Skill
• 专家：写插件、改源码

---

数据流

CLI 交互流程

用户输入 → cli.py → AIAgent → Prompt Builder
                                    ↓
                            LLM API 调用
                                    ↓
                           解析工具调用
                                    ↓
                        Tool Registry 查找
                                    ↓
                          执行工具 → 返回结果
                                    ↓
                           加入上下文 → 再次调用 LLM
                                    ↓
                           最终响应 → 显示给用户
                                    ↓
                           Session Storage 持久化

Gateway 消息流程

平台消息 → Adapter → Gateway Router → 用户授权检查
                                          ↓
                                    Session 查找/创建
                                          ↓
                                      AIAgent 处理
                                          ↓
                                    响应 → Adapter → 平台

---

推荐阅读顺序

如果你想深入源码，建议按以下顺序：

1. Architecture（本文）— 建立全局视野
2. Agent Loop Internals — 理解核心循环
3. Prompt Assembly — 理解上下文构建
4. Tool System — 理解工具注册和执行
5. Gateway Internals — 理解消息路由
6. Session Storage — 理解数据持久化

深入阅读

• 官方 Architecture 文档
• Agent Loop Internals

---