---
source: 微信公众号
url: https://mp.weixin.qq.com/s/Rao9okjfY7gzsHldjRKdDw
title: Hermes Agent 架构分析
tags: [hermes-agent, architecture, AI-agent]
---

# Hermes Agent 架构分析

## 系统全景
Hermes Agent 是一个**多平台、可扩展的 AI Agent 框架**，核心组件包括：
- **核心 Agent 引擎** — AIAgent 类（run_agent.py）
- **工具系统与注册中心** — registry 架构
- **网关与多平台适配** — 20+ 平台适配器
- **配置与状态管理** — 双轨配置 + SQLite 会话存储
- **安全模型** — 多层审批 + 纵深防御

---

## 核心 Agent 引擎

### AIAgent 类设计
采用**大类单文件设计**（run_agent.py），所有核心逻辑汇聚于一个文件中。

**60+ 构造器参数**按语义分区：
- 模型配置
- 工具控制（enabled/disabled_toolsets）
- 行为控制（quiet_mode, save_trajectories）
- 上下文标识（platform, session_id）
- 回调注入（clarify, approval, sudo, progress callbacks）

这是一种**配置注入（Configuration Injection）**模式。

### 双接口设计
```python
def chat(self, message: str) -> str:
    """简单接口 — 返回最终响应字符串"""

def run_conversation(self, ...) -> dict:
    """完整接口 — 返回字典"""
```
Facade + Full API 双层设计。

### 核心循环
```
while api_call_count < max_iterations and budget.remaining > 0:
    # 1. 预飞检查 — 上下文压缩
    # 2. API 调用
    # 3. 工具调用分支（支持并行执行）
    # 4. 终止条件
```

**关键设计决策：**
| 权衡 | 选择 | 理由 |
|------|------|------|
| 同步 vs 异步 | 同步循环 | 可预测性、调试简单 |
| 迭代控制 | 双重限制 | 线程安全预算管理 |
| 上下文压缩 | 触发式 | 仅在 token 上限时启动 |

### IterationBudget — 线程安全预算管理
使用 threading.Lock 实现，解决子代理委派场景下的预算共享问题。

### 上下文压缩（5 阶段管线）
1. **工具输出裁剪** — 截断超长返回值
2. **头部保护** — 锁定系统提示 + 前 N 轮
3. **Token 预算尾部定位** — 从尾部向前累积
4. **结构化摘要** — LLM 摘要被截断的中间部分
5. **工具对消毒** — 确保 tool_use/tool_result 成对出现

**防抖机制**：检测连续多次压缩则触发紧急降级。

### Prompt 缓存策略
Anthropic system_and_3 策略：系统提示 + 最后 3 条消息设置 cache_control 断点。

### 多 API 模式适配
支持 4 种 LLM API 协议：OpenAI、Anthropic、Google、OpenRouter，内部统一格式后在 API 调用前动态转换。

---

## 工具系统与注册中心

### Registry 架构（tools/registry.py）
```python
class ToolEntry:
    __slots__ = ('name', 'toolset', 'schema', 'handler', 'check_fn',
                 'requires_env', 'platform_filter', 'is_mcp')
```

**设计亮点：**
- **AST 自动发现** — 扫描 tools/ 目录的 registry.register() 调用，无需手动维护导入列表
- **MCP 影子保护** — MCP 工具同名时优先内置版本
- **__slots__ 优化** — 减少内存开销

### 工具分层（6 层）
从底层执行环境到顶层 Agent 循环，每一层单向依赖。

### 工具集定义
_HERMES_CORE_TOOLS 列表，用户通过 enabled/disabled_toolsets 精确控制。

### 工具调用生命周期（8 步流程）
LLM → tool_calls → model_tools.handle_function_call() → registry.dispatch() → 审批检查 → handler → JSON result → tool_result message

---

## 网关与多平台适配

### Gateway 架构
异步事件循环，20+ 平台适配器并发运行，统一路由到 AIAgent。

### 平台适配器模式（Template Method + Strategy）
```python
class BasePlatformAdapter(ABC):
    # 4 个必须实现的抽象方法
    async def send_text(self, chat_id, text): ...
    async def send_typing(self, chat_id): ...
    async def get_display_name(self, user_id): ...
    async def start(self): ...
    # 10+ 可选覆盖方法
```

支持 20+ 适配器：Telegram、Discord、Slack、WhatsApp、QQ、Signal、HomeAssistant、WeChat（元宝）等。

### 会话管理
- 双写持久化：SQLite（主）+ JSONL（向后兼容）
- 重置策略：idle（空闲超时）/ daily（每日定时）

### Agent 缓存（LRU）
最大 128 个 Agent 实例的资源感知缓存。

---

## 数据流转

### 主流程（键盘 → 屏幕）
CLI 入口 → Agent 循环 → LLM API → 工具执行 → 流式渲染 → 会话持久化

### 工具调用流细节
- **Agent 级拦截**：todo_tool、memory_tool 直接处理不进 registry
- **审批流程**：环境豁免 → YOLO 模式 → LLM 智能评估 → 人工审批

---

## 配置与状态管理

### 双轨配置系统
```
~/.hermes/
├── config.yaml      # 结构化配置 (YAML)
├── .env             # 环境变量 (API keys)
├── skins/           # 自定义皮肤
├── skills/          # 已安装技能
└── sessions/        # 会话数据 (SQLite + FTS5)
```

### 三套配置加载器
- load_cli_config() — CLI 交互模式
- load_config() — 子命令
- 直接 YAML 加载 — Gateway

### SessionDB
SQLite + FTS5 全文搜索，WAL 模式读写并发，自动迁移，Jitter 写重试。

---

## 安全模型

### 多层审批体系
1. 环境检测豁免 → 2. YOLO 模式 → 3. LLM 智能评估 → 4. 人工审批回调

### 危险模式检测（30+ 模式）
```python
DANGEROUS_PATTERNS = [
    r"rm\s+(-[rf]+\s+)?/",    # 文件系统破坏
    r"curl.*\|\s*(bash|sh)",   # 网络风险
    r"sudo\s+",                # 权限提升
    # ...
]
```
Unicode 规范化防绕过（NFKC + 零宽字符移除）。

### 凭证保护
- 环境变量黑名单（工具执行时自动过滤）
- 敏感路径保护（~/.ssh/, ~/.gnupg/ 等）

### SSRF 防护
在平台适配器基类中验证 URL，阻止内网/回环地址访问。

### 安全设计哲学
纵深防御（Defense in Depth）：最小特权、分层检查、反绕过、环境隔离、凭证隔离。

---

## 可扩展性体系

### 工具扩展（最核心的扩展机制）
添加新工具仅需 2 个文件 + AST 自动发现。零配置。

### 技能系统（Skills）
纯文本能力增强（~/.hermes/skills/），通过自然语言描述注入系统提示。

### MCP 生态
Hermes 同时作为 MCP Server 和 MCP Client。

### 皮肤系统
纯数据扩展（YAML），运行时通过 /skin 命令即时切换。

---

## 设计哲学

### 核心原则
- **实用主义胜于教条主义** — 大文件不如过度拆分
- **回调注入实现界面无关** — 4 个入口共享同一个 AIAgent
- **分层而非分片** — 6 层清晰分层
- **安全作为一等公民** — 深度嵌入架构
- **约定优于配置** — 自动发现、自动加载、自动集成

### 主要权衡
| 权衡 | 选择 | 收益 |
|------|------|------|
| 大文件 vs 小模块 | 大文件 | 核心逻辑内聚 |
| 同步 vs 异步 | 同步 | 可预测性 |
| 单进程 vs 微服务 | 单进程 | 部署简单 |
| AST 发现 vs 显式注册 | 动态发现 | 零配置 |

### 一句话总结
> Hermes 是一个以实用主义为导向、以可扩展性为骨架、以安全性为底线的工业级 AI Agent 框架。