同步

InBox/Hermes Agent 架构分析.md

@@ -0,0 +1,227 @@
+---
+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 框架。