第三章
整体架构一图看懂
🎧 语音播放
用一张图建立对 Hermes-Agent 的全局认知
🎯 本章目标
- 理解 Hermes-Agent 的分层架构
- 掌握各模块之间的调用关系
- 建立完整的系统认知地图
📚 前置知识
- 第二章的安装经验
- 知道什么是模块/类的概念
💡 学完收获
- 能够向别人解释 Hermes-Agent 的工作原理
- 阅读源码时知道该去哪个文件找
- 理解模块设计的思路
3.1 架构总览
Hermes-Agent 采用分层架构，每一层有明确的职责：
用户交互层 User Interface Layer
CLI 终端
交互式命令行界面
Gateway
消息网关，Telegram / Discord / Slack
ACP
VSCode / Zed 集成
Skills
可扩展技能系统
核心编排层 Core Orchestration
HermesCLI
命令解析、输入处理
cli.py
AIAgent
决策循环、任务执行
run_agent.py
工具编排层 Tool Orchestration
model_tools.py
工具发现 · 调度 · 结果处理 · OpenAI 兼容格式
工具注册层 Tool Registry
tools/registry.py
中央注册表 · Schema 管理 · 工具分发
工具实现层 Tool Implementation
file_tools
文件读写搜索
terminal
命令执行
web_tools
搜索抓取
browser
浏览器自动化
delegate
子代理
cronjob
定时任务
支撑系统 Support Systems
hermes_state
SQLite 会话存储 · FTS5 搜索
agent/
Prompt 构建 · 上下文压缩 · 记忆管理
skills/
可扩展技能系统
3.2 核心模块详解
3.2.1 入口点：cli.py
cli.py 是 CLI 模式的入口点，负责：
- 解析命令行参数
- 初始化用户界面（TUI）
- 处理用户输入
- 调用核心 AIAgent
💡 关键类：HermesCLI
HermesCLI 类是 CLI 的核心，它处理所有用户交互。当用户发送消息时，它调用 AIAgent.run_conversation() 来处理。
3.2.2 核心引擎：run_agent.py
run_agent.py 是整个项目的核心，包含：
AIAgent
主 Agent 类，决策循环
⭐⭐⭐⭐⭐
IterationBudget
控制最大迭代次数
⭐⭐⭐
_SafeWriter
安全输出，防崩溃
⭐⭐
3.2.3 工具编排：model_tools.py
model_tools.py 是工具系统的中央协调器：
_discover_tools()
发现所有工具
get_tool_definitions()
获取工具定义
handle_function_call()
执行工具调用
3.2.4 工具注册表：tools/registry.py
tools/registry.py 是工具的中央注册表，所有工具都向它注册：
ToolRegistry
register(name, toolset, schema, handler)
—
注册工具get_definitions(tool_names)
—
获取 Schemadispatch(name, args)
—
分发执行
3.3 数据流图
理解一条消息在系统中的完整旅程：
消息处理流程 Message Flow
flowchart TD
A["👤 用户输入"] --> B["🎛️ HermesCLI"]
B --> C["📝 构建 Prompt"]
C --> D["🧠 AIAgent.run_conversation"]
D --> E["📡 调用 LLM API"]
E --> F{"tool_calls?"}
F -->|是| G["🔧 执行工具"]
G --> H["📥 添加工具结果"]
H --> D
F -->|否| I["✅ 返回响应"]
I --> J["🖥️ 显示给用户"]
style A fill:#dbeafe,stroke:#2563eb
style G fill:#d1fae5,stroke:#059669
style I fill:#d1fae5,stroke:#059669
3.4 模块依赖关系
理解谁依赖谁，对于理解代码很重要：
模块依赖链 Dependency Chain
flowchart LR
A["📦 registry.py"] --> B["🛠️ tools/*.py"]
B --> C["🔧 model_tools.py"]
C --> D["🧠 run_agent.py"]
D --> E["🎛️ cli.py / gateway/"]
style A fill:#ede9fe,stroke:#7c3aed
style D fill:#dbeafe,stroke:#2563eb
💡 依赖方向的好处
依赖方向是从下往上的，这意味着：
- 最底层的
registry.py最稳定 - 改动上层不会影响下层
- 可以单独测试每一层
3.5 状态管理
Hermes-Agent 使用 SQLite 存储状态：
sessions 表
会话元数据 · 模型配置 · 统计信息
messages 表
每条消息 · role · content · tool_calls
FTS5 虚拟表
全文搜索 · 跨会话检索
3.6 学习建议
根据你的目标，选择不同的阅读路径：
🧠 理解 Agent 原理
run_agent.py → model_tools.py → tools/registry.py
🔧 添加新工具
tools/registry.py → 现有工具 → toolsets.py
📱 接入新平台
gateway/run.py → gateway/platforms/*.py
📝 自定义 Prompt
agent/prompt_builder.py → context_compressor.py
📚 本章总结
本章重点：
- 分层架构：UI层 → 核心层 → 工具层 → 支撑系统
- 核心流程：用户输入 → Prompt构建 → LLM调用 → 工具执行 → 响应
- 依赖方向：从下往上，最底层最稳定
一句话记忆点： Hermes-Agent 是一个"分层三明治"：输入在顶，核心在中间，工具在底层
延伸思考
- 为什么 Hermes-Agent 选择分层架构，而不是把所有代码写在一个文件里？
- 如果要在 Hermes-Agent 中添加"发送邮件"功能，你需要在哪一层做修改？
- 对比：传统 MVC 架构和 Hermes-Agent 的分层架构有什么异同？