7.1 KiB
source, url, title, tags
| source | url | title | tags | |||
|---|---|---|---|---|---|---|
| 微信公众号 | https://mp.weixin.qq.com/s/Rao9okjfY7gzsHldjRKdDw | Hermes 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）**模式。
双接口设计
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 阶段管线）
- 工具输出裁剪 — 截断超长返回值
- 头部保护 — 锁定系统提示 + 前 N 轮
- Token 预算尾部定位 — 从尾部向前累积
- 结构化摘要 — LLM 摘要被截断的中间部分
- 工具对消毒 — 确保 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）
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）
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 写重试。
安全模型
多层审批体系
- 环境检测豁免 → 2. YOLO 模式 → 3. LLM 智能评估 → 4. 人工审批回调
危险模式检测（30+ 模式）
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 框架。