228 lines
7.1 KiB
Markdown
228 lines
7.1 KiB
Markdown
---
|
||
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 框架。
|