Hermes Agent 学习笔记
学习日期: 2026-04-16
项目版本: v0.9.0
项目位置: C:\github\hermes-agent
1. 项目概述
1.1 一句话简介
Hermes Agent 是 Nous Research 开发的自学习 AI Agent 框架，具备闭环学习循环（技能自动创建→使用中自我改进→知识持久化→跨会话搜索→用户画像建模），支持 20+ 消息平台、200+ LLM 模型、40+ 内置工具、MCP 扩展、子代理委派、cron 调度，以及 RL 训练环境。
1.2 核心价值
| 维度 | 价值 |
|---|
| 自学习闭环 | Agent 在复杂任务后自动创建技能，使用中自我改进，周期性提醒自己持久化知识，搜索历史会话（FTS5），通过 Honcho 方言式对话构建用户模型 |
| 多平台覆盖 | Telegram、Discord、Slack、WhatsApp、Signal、飞书、钉钉、企微、QQ、Matrix、Mattermost、iMessage(BlueBubbles)、Email、SMS、Webhook、Home Assistant —— 统一网关进程 |
| 模型无关 | Nous Portal、OpenRouter(200+模型)、OpenAI、Anthropic、Mistral、HuggingFace、z.ai/GLM、Kimi/Moonshot、MiniMax、小米 MiMo、本地端点 —— 一行命令切换 |
| 多执行环境 | 本地、Docker、SSH、Daytona、Singularity、Modal —— 从 $5 VPS 到 GPU 集群，支持 serverless 闲置计费 |
| 研究就绪 | 批量轨迹生成、Atropos RL 环境、轨迹压缩，用于训练下一代工具调用模型 |
| 多实例隔离 | Profile 机制，每个实例拥有独立的 config/sessions/memory/skills/gateway |
| OpenClaw 迁移 | 内置hermes claw migrate命令，自动导入 SOUL.md、记忆、技能、API 密钥 |
1.3 ⭐ 学习难度评估
| 维度 | 评级 | 说明 |
|---|
| 代码规模 | ★★★★☆ | 1685 个文件，核心 run_agent.py 超 10000 行，cli.py 超 10000 行，gateway/run.py 超 9000 行 |
| 架构复杂度 | ★★★★★ | 工具注册表+工具集+编排层三层解耦，20+ 平台适配器，6 种终端后端，Profile 隔离，同步/异步混合调用 |
| 领域知识 | ★★★★☆ | 需要理解 LLM API (OpenAI 兼容)、工具调用协议、MCP 标准、FTS5 全文搜索、RL 训练流程 |
| 上手门槛 | ★★★☆☆ | 一键安装脚本，交互式 setup 向导，文档完善，但源码阅读需要耐心 |
| 依赖管理 | ★★★☆☆ | pyproject.toml 管理清晰，20+ optional extras 分组合理，但[all]依赖链较长 |
1.4 项目活跃度评估
| 指标 | 值 |
|---|
| 版本 | v0.9.0 |
| 许可证 | MIT |
| 语言 | Python 3.11+ |
| 最后提交 | 2026-04-14（16f9d020） |
| 测试规模 | 556 个测试文件，约 3000 个测试用例 |
| 代码文件 | 1685 个 |
| 内置技能 | 26 个目录（涵盖软件开发、研究、DevOps、智能家居等） |
| 平台适配器 | 24 个 Python 文件（20+ 消息平台） |
| 工具模块 | 17 个*_tool.py文件 |
| Stars | 项目活跃，PR 频繁（最近 PR #9475, #9543, #9538, #9483） |
2. 系统架构
2.1 整体架构图
┌──────────────────────────────────────────────────────────────────┐ │ 用户入口 │ │ ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────┐ │ │ │ CLI │ │ Gateway │ │ ACP │ │ Webhook │ │ │ │ (cli.py) │ │(gateway/run)│ │(acp_*) │ │ Server │ │ │ └─────┬─────┘ └──────┬───────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ │ └───────────────┴───────┬───────┴──────────────┘ │ │ │ │ │ ┌─────────────────────────────▼─────────────────────────────┐ │ │ │ AIAgent (run_agent.py) │ │ │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ │ │PromptBuilder│ │ContextCompr. │ │ Model Metadata │ │ │ │ │ │(prompt_ │ │(context_ │ │ (model_ │ │ │ │ │ │ builder.py) │ │ compressor) │ │ metadata.py) │ │ │ │ │ └─────────────┘ └──────────────┘ └─────────────────┘ │ │ │ └─────────────────────────┬───────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────▼───────────────────────────────────┐ │ │ │ model_tools.py (编排层) │ │ │ │ get_tool_definitions() / handle_function_call() │ │ │ └─────────────────────────┬───────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────▼───────────────────────────────────┐ │ │ │ toolsets.py (工具集定义) │ │ │ │ 40+ 工具 → 20+ 工具集 → 平台工具集(hermes-telegram等) │ │ │ └─────────────────────────┬───────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────▼───────────────────────────────────┐ │ │ │ tools/registry.py (中央注册表) │ │ │ │ ToolRegistry 单例 → ToolEntry(name,schema,handler,check) │ │ │ └─────────────────────────┬───────────────────────────────────┘ │ │ │ │ │ ┌──────┬──────┬──────┬───┴───┬──────┬──────┬──────┬──────┐ │ │ │ Web │Term │ File │Vision │Browser│Skills│Memory │ MCP │ ... │ │ │Tools │Tool │Tools │Tools │Tool │Tool │Tool │Tool │ │ │ └──────┴──────┴──────┴───────┴──────┴──────┴──────┴──────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 持久化层 │ │ │ │ hermes_state.py (SQLite + FTS5) │ Memory Files │ Skills │ │ │ └─────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────┘
2.2 关键架构决策
| 决策 | 选择 | 理由 |
|---|
| 工具系统 | 三层架构：registry → toolsets → model_tools | 解耦注册、分组、编排；工具文件自注册，新增工具仅需 3 个文件变更 |
| 对话循环 | 同步阻塞式 while 循环 | 简单可靠，子代理用 ThreadPoolExecutor 并行 |
| 会话存储 | SQLite + WAL + FTS5 | 支持网关多平台并发读写，全文搜索历史对话 |
| 上下文压缩 | 辅助模型摘要中间轮次 | 保护头部（系统提示+首轮）和尾部（最近 ~20K tokens），仅压缩中间 |
| Profile 隔离 | HERMES_HOME 环境变量重定向 | 119+ 处引用自动作用域切换，零侵入 |
| 提示缓存 | 禁止运行时修改系统提示 | 避免破坏 Anthropic prompt caching，仅在压缩时重写 |
| 工具 Schema | OpenAI function calling 格式 | 统一模型接口，所有处理器必须返回 JSON 字符串 |
| 异步桥接 | 持久化事件循环 + worker 线程本地循环 | 避免 asyncio.run() 的 create-destroy 生命周期导致的 “Event loop is closed” 错误 |
2.3 核心文件结构树
hermes-agent/ ├── run_agent.py # AIAgent 核心对话引擎 (~10K 行) ├── model_tools.py # 工具编排层 (~600 行) ├── toolsets.py # 工具集定义 (~350 行) ├── cli.py # CLI 交互式 TUI (~10K 行) ├── hermes_state.py # SQLite 会话存储 + FTS5 (~1.2K 行) ├── hermes_constants.py # 全局常量/路径工具 ├── agent/ # Agent 内部模块 │ ├── prompt_builder.py # 系统提示组装 (~1K 行) │ ├── context_compressor.py # 上下文自动压缩 (~800 行) │ ├──
