Hermes Agent v0.8.0 · 源码解析

01一句话总结

Hermes Agent 是一个多平台入口、同一个 agent 循环、可插拔 LLM provider、可插拔 terminal 后端、 可插拔 skills + MCP + plugins 的 Python agent 框架。它的最关键设计不是 LLM 能力,而是 把"跟 agent 说话"、"agent 跑代码"、"agent 用工具"、"agent 记忆"四件事完全正交: 你可以从 CLI / Telegram / Slack / Discord / WhatsApp / Signal / 邮件 / Matrix / 钉钉 / 飞书 / WeChat 任意入口发消息,同一个 AIAgent 实例处理,代码执行可以转发到本地 / Docker / SSH 远程 / Daytona / Modal / Singularity 任意沙箱,而模型 provider 从 OpenRouter / Nous / Anthropic / OpenAI / z.ai / Kimi / MiniMax / Google AI Studio / HuggingFace / 任意 OpenAI 兼容 custom endpoint 任选。

所有这些都可以在运行时用 /model 切换,不重启,不丢上下文。

02取证方式 · 不是 AI 猜的

本文的每一条技术断言都基于对实际源码的阅读,格式是 file:line 引证。 证据来源:

• git clone https://github.com/NousResearch/hermes-agent.git 到 ~/Projects/research/20260413-hermes-source-analysis/source/
• 顶层仓库文件:AGENTS.md(20 KB 开发者指南)、README.md、 RELEASE_v0.8.0.md(209 PR / 82 issue 合并日志)、Dockerfile、 pyproject.toml、docker/entrypoint.sh
• 核心代码文件:run_agent.py(10 578 行)、cli.py(9 920 行)、 gateway/run.py(8 844 行)、hermes_state.py(1 238 行)、 tools/registry.py、model_tools.py

03三个入口脚本

pyproject.toml pyproject.toml:112-115 定义了 3 个可执行入口:

核心类 AIAgent 定义在 run_agent.py:492。 交互 CLI 的 HermesCLI 定义在 cli.py:1574。 消息网关的 GatewayRunner 定义在 gateway/run.py:512。 这三个类是理解 Hermes 的三把钥匙。

04整体架构

05仓库结构地图

来源:AGENTS.md 第 12-64 行 + 实际 ls 验证。

06核心:AIAgent 类

class AIAgent 定义在 run_agent.py:492。构造函数接受 50+ 参数, 但核心字段几个:

注意 run_agent.py:504-505 的 _context_pressure_last_warned — 这是一个类级别的 dict,用来跨实例去重"上下文压力警告"。原因写在注释里: gateway 会为每条消息创建一个新 AIAgent 实例,所以实例级的 flag 每次都重置,需要类级共享状态。 这个细节暴露了 Gateway 的真实调用模式:每消息一个实例,但实例是从 cache 里拿的(见 gateway/run.py:577-584 的 _agent_cache)。

07Agent 主循环

主循环在 run_conversation(),入口 run_agent.py:7528, 核心 while 在 run_agent.py:7850:

while (api_call_count < self.max_iterations and self.iteration_budget.remaining > 0) or self._budget_grace_call:
    self._checkpoint_mgr.new_turn()
    if self._interrupt_requested:
        interrupted = True
        break
    api_call_count += 1
    ...
    # 调 LLM
    response = client.chat.completions.create(model=model, messages=messages, tools=tool_schemas)
    if response.tool_calls:
        for tool_call in response.tool_calls:
            result = handle_function_call(tool_call.name, tool_call.args, task_id)
            messages.append(tool_result_message(result))
    else:
        return response.content

这个简化版是 AGENTS.md 第 112-122 行给的示意。真实代码在 7850-10213 之间展开了 ~2000 行复杂度,处理:

• 中断(run_agent.py:7855)— 用户发新消息时打断当前循环
• 迭代预算(run_agent.py:7871)— consume() 消费 1 次,共享预算
• _budget_grace_call(run_agent.py:7869)— 预算耗尽给模型 1 次总结机会
• step_callback 发给 gateway 做 agent:step hook(run_agent.py:7878-7902)
• Skill 使用计数器 _iters_since_skill(run_agent.py:7906-7908)— 每 N 轮未用 skill 会 nudge 模型考虑 skill_manage
• 消息消毒:_sanitize_messages_surrogates()(run_agent.py:356) 和 _sanitize_messages_non_ascii()(run_agent.py:413)— 处理奇怪 unicode 导致的 provider 报错

08工具注册表(插件化核心)

Hermes 的工具系统是"tool 文件自注册"模型。每个 tools/*.py 在模块 import 时调用 registry.register(...) 把自己挂上去。看 tools/registry.py 的类定义:

tools/registry.py:48
class ToolRegistry:
    """Singleton registry that collects tool schemas + handlers from tool files."""

    def __init__(self):
        self._tools: Dict[str, ToolEntry] = {}
        self._toolset_checks: Dict[str, Callable] = {}

    def register(
        self,
        name: str,
        toolset: str,
        schema: dict,          # OpenAI function schema
        handler: Callable,     # 实际执行函数
        check_fn: Callable = None,   # 可用性检查(env 变量等)
        requires_env: list = None,
        is_async: bool = False,
        description: str = "",
        emoji: str = "",
        max_result_size_chars: int | float | None = None,
    ): ...

关键设计:

• 单例:tools/registry.py:290 registry = ToolRegistry(), 模块级对象,任意文件 from tools.registry import registry 拿到同一个
• check_fn:tools/registry.py:117-143 get_definitions() 先跑 check, 失败的 tool 不会出现在发给 LLM 的 schema 列表里。这是 Hermes 实现"API key 缺失时工具消失"的机制
• MCP 动态注入:tools/registry.py:95-110 有 deregister(), 专门给 MCP 服务发 notifications/tools/list_changed 时 nuke-and-repave 用
• dispatch() 同时支持同步 / 异步:tools/registry.py:149-166 — 如果 entry.is_async,从 model_tools._run_async() 桥接跑
• tool_error / tool_result helper:tools/registry.py:309-335 强制所有 tool handler 返回 JSON 字符串,消除了几百次 json.dumps() 样板

09工具编排层(sync/async 桥接)

model_tools.py 的顶部(model_tools.py:1-22)自述为 "thin orchestration layer over the tool registry"。它只做两件事:

1. 触发 tool 发现:import 所有 tools/*.py,让它们 self-register
2. sync→async 桥接:_run_async() 位于 model_tools.py:81-120+

_run_async() 背后有一个很讲究的设计 —— 三种 loop 策略:

这段代码读下来能看出 Hermes 是经过大量实战打磨的 —— _get_worker_loop() 的文档注释 直接说"这是为了避免某个 PR 引入的 'Event loop is closed' bug"。

10会话存储 + FTS5 搜索

hermes_state.py 的 SessionDB 类是整个 agent 的记忆骨架。路径:

hermes_state.py:32  DEFAULT_DB_PATH = get_hermes_home() / "state.db"
hermes_state.py:34  SCHEMA_VERSION = 6
hermes_state.py:115 class SessionDB

表结构

sessions 表 hermes_state.py:41-69 存每个会话的元数据:

• id, source — 会话 ID + 来源("cli" / "telegram" / "discord" / ...)
• parent_session_id — 父会话链,上下文压缩时切片新会话,父子关系保持
• input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens — 5 种 token 统计
• estimated_cost_usd, actual_cost_usd, cost_status, cost_source, pricing_version — 成本追踪
• billing_provider, billing_base_url, billing_mode — 计费 provider 单独记录(因为 OAuth pool 会轮换)

messages 表 hermes_state.py:71-85 存每条消息: session_id, role, content, tool_call_id, tool_calls, tool_name, timestamp, token_count, finish_reason, reasoning, reasoning_details, codex_reasoning_items。

注意 reasoning_details 和 codex_reasoning_items 是两种不同 provider 的 thinking 格式 —— Anthropic thinking blocks 和 OpenAI Codex reasoning item,各自持久化。

FTS5 全文搜索

hermes_state.py:93-112 定义了 FTS5 虚拟表 + 3 个触发器:

CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
    content,
    content=messages,
    content_rowid=id
);

CREATE TRIGGER messages_fts_insert AFTER INSERT ON messages BEGIN
    INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content);
END;
CREATE TRIGGER messages_fts_delete AFTER DELETE ON messages BEGIN
    INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.id, old.content);
END;
CREATE TRIGGER messages_fts_update AFTER UPDATE ON messages BEGIN
    INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.id, old.content);
    INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content);
END;

content=messages, content_rowid=id 是 FTS5 的外部内容模式(external content table)— 索引数据不重复存储,直接引用 messages 表的 id。节省一半磁盘。

_sanitize_fts5_query() hermes_state.py:938 实现了 FTS5 查询消毒 —— 原因:FTS5 自己有查询语法,用户输入的 -、"、(、) 要么 escape 要么会抛错。这个函数的注释明确说明"wrap unquoted hyphenated and dotted terms in quotes so FTS5's tokenizer doesn't split them"(因为 FTS5 会按点和连字符分词)。

高并发写

hermes_state.py:123-136 的类常量:

• _WRITE_MAX_RETRIES = 15
• _WRITE_RETRY_MIN_S = 0.020(20 ms)
• _WRITE_RETRY_MAX_S = 0.150(150 ms)
• _CHECKPOINT_EVERY_N_WRITES = 50(每 50 次写触发一次 PASSIVE WAL checkpoint)

注释解释:SQLite 自带 busy handler 用确定性 sleep 导致"convoy effect"(高并发时互相卡成一队), 所以 Hermes 在应用层做抖动重试,让多个 writer 自然错开。这是细节工程能力的体现。

11消息网关

class GatewayRunner gateway/run.py:512。 启动入口 async def start_gateway() gateway/run.py:8634。

关键实例字段

• adapters: Dict[Platform, BasePlatformAdapter] gateway/run.py:536 — 每个启用的平台加载一个 adapter(telegram / discord / slack / ...)
• session_store = SessionStore(...) gateway/run.py:553 — 会话持久化,wrap SessionDB
• _running_agents: Dict[str, AIAgent] gateway/run.py:573 — 每 session 的活 agent,用于中断/查询
• _pending_messages gateway/run.py:575 — 中断期间用户发的新消息先排队
• _agent_cache gateway/run.py:583 — 这是 prompt caching 能用的关键。每 session 缓存 (AIAgent, config_signature), 同一个 session 复用同一个 instance,避免重建 system prompt 和内存,保证 Anthropic prefix cache 命中
• _session_model_overrides gateway/run.py:588 — /model 指令切换模型,每 session 一份
• _pending_approvals gateway/run.py:591 — 危险命令审批的待响应状态

临时配置注入

gateway/run.py:540-549:

self._prefill_messages = self._load_prefill_messages()
self._ephemeral_system_prompt = self._load_ephemeral_system_prompt()
self._reasoning_config = self._load_reasoning_config()
self._service_tier = self._load_service_tier()
self._show_reasoning = self._load_show_reasoning()
self._busy_input_mode = self._load_busy_input_mode()
self._restart_drain_timeout = self._load_restart_drain_timeout()
self._provider_routing = self._load_provider_routing()
self._fallback_model = self._load_fallback_model()
self._smart_model_routing = self._load_smart_model_routing()

这些都标注为"ephemeral, injected at API-call time only and never persisted" — 典型做法:保留功能,但不污染持久化会话,这样切换配置不会破坏历史 cache。

1222 个平台适配器

gateway/platforms/ 目录实际文件清单(ls 核对):

api_server.py         base.py             bluebubbles.py    dingtalk.py
discord.py            email.py            feishu.py         helpers.py
homeassistant.py      matrix.py           mattermost.py     signal.py
slack.py              sms.py              telegram.py       telegram_network.py
webhook.py            wecom.py            wecom_callback.py wecom_crypto.py
weixin.py             whatsapp.py

base.py 定义 BasePlatformAdapter 抽象基类,其他文件继承实现。 ADDING_A_PLATFORM.md 在同目录下给开发者文档。

特殊的几个:

• api_server.py — REST API 入口,暴露 OpenAI 兼容 /v1/*(就是你跑起来的那个)
• webhook.py — 通用 webhook(接 Home Assistant、自定义集成)
• wecom.py + wecom_callback.py + wecom_crypto.py — 企业微信,因为要做 XML 加密所以拆 3 个文件
• telegram_network.py — 专门处理 Telegram 网络层的 retry / dedup / fallback IP(中国访问常见问题)
• bluebubbles.py — iMessage 桥接(通过 BlueBubbles 项目)

136 种 Terminal 后端

tools/environments/ 目录(共 3285 行代码):

14Skills 系统

Skills 是 Hermes 的"过程性记忆"—— markdown 文件描述某类任务的步骤。skills/ 目录:

26 个顶层 + 78 个 bundled skill 文件(入口日志 "78 total bundled" 匹配)。 每个 skill 是 SKILL.md,YAML frontmatter 带 metadata。例:

---
name: dogfood
description: Systematic exploratory QA testing of web applications ...
version: 1.0.0
metadata:
  hermes:
    tags: [qa, testing, browser, web, dogfood]
    related_skills: []
---

# Dogfood: Systematic Web Application QA Testing
...

来源:skills/dogfood/SKILL.md:1-11

Skills 的注入策略:agent/skill_commands.py 扫描 ~/.hermes/skills/, 用户打 /skillname 触发时,注入为用户消息(不是系统提示词), 这样不破坏 prompt caching —— 见 AGENTS.md:135(原文: "Skill slash commands: scans skills dir, injects as user message (not system prompt) to preserve prompt caching")。

此外,skills 还支持"自我进化"—— 独立仓库 hermes-agent-self-evolution 用 DSPy + GEPA 对 skill 做基于轨迹的 prompt 优化。

15Slash 命令中心化注册

所有 /command 定义在 hermes_cli/commands.py 的 COMMAND_REGISTRY(AGENTS.md:137-148)。 一次定义,多处消费:

• CLI 分发:cli.py HermesCLI.process_command() cli.py:5192
• Gateway 分发:gateway/run.py + GATEWAY_KNOWN_COMMANDS 冻结集
• Gateway 帮助:gateway_help_lines() 自动生成 /help
• Telegram 菜单:telegram_bot_commands() 生成 BotCommand 数组
• Slack 子命令:slack_subcommand_map() 生成 /hermes sub 路由
• 自动补全:COMMANDS flat dict 喂给 SlashCommandCompleter
• CLI 帮助:COMMANDS_BY_CATEGORY 喂给 show_help()

加一条 slash 命令只需要在 CommandDef 数组里加一行 + 各自 process_command() 里加 elif canonical == "mycommand": 分支。 加别名更简单 —— 只动 aliases 元组,所有下游自动同步 (dispatch、help、Telegram 菜单、Slack 映射、autocomplete)。

16Profile 多实例支持

Hermes 支持多个完全隔离的实例,每个有独立 HERMES_HOME。核心机制:

hermes_cli/main.py 中的 _apply_profile_override()
    在任何模块 import 之前设置 HERMES_HOME 环境变量
    → 所有 119+ 个 get_hermes_home() 调用自动 scope 到活 profile

安全规则(AGENTS.md:376-420):

• 禁止硬编码 Path.home() / ".hermes"(会破坏 profiles)
• 用 get_hermes_home() 读路径,display_hermes_home() 展示
• 平台 adapter 连接时用 acquire_scoped_lock() 防两个 profile 共用同一个 bot token
• Profile 列表本身不存在 HERMES_HOME,存在 Path.home() / ".hermes" / "profiles", 这样 hermes -p coder profile list 能看到所有 profile(包括非活动的)

17v0.8.0 重要变化

来源:RELEASE_v0.8.0.md(2026-04-08 发布,209 PR / 82 issue 合并)。挑出最关键的:

A. 自我进化的证据

#6120 — "Self-Optimized GPT/Codex Tool-Use Guidance"。原文: "The agent diagnosed and patched 5 failure modes in GPT and Codex tool calling through automated behavioral benchmarking"。这句话很重:agent 用自己的行为基准测试发现自己的问题, 然后自己写了修复。不是团队加提示词,是 agent 闭环在做迭代。

B. 后台任务自动通知

#5779 — notify_on_complete。起一个长任务(训练、测试、部署), agent 不需要 polling,完成时自动收通知。这是长时间任务场景的核心优化。

C. 闲置超时替代墙钟超时

#5389 — 原文:"Gateway and cron timeouts now track actual tool activity instead of wall-clock time"。这个改动让"跑 20 分钟的 build 不会被超时杀掉", 前提是它一直在有工具活动。

D. 实时模型切换

#5181 / #5742 — /model 从 CLI、Telegram、Discord、Slack 都能切。 Telegram 和 Discord 还给了 inline 按钮 picker。

E. 安全加固打包

#5944 + #5613 + #5629 — "Security Hardening Pass":

• SSRF 保护统一化
• 时序攻击(timing attack)缓解
• tar 遍历防护(解压恶意包)
• 凭证泄漏防护
• cron 路径遍历加固
• 跨会话隔离
• 所有 terminal 后端的 workdir 消毒

F. MCP OAuth 2.1 PKCE

#5420 — 完整的 OAuth 2.1 (带 PKCE) 接入任意 MCP server。 #5305 — 自动 OSV 漏洞库扫描 MCP 扩展包(防供应链投毒)。

G. Google AI Studio 原生 provider

#5577 — Gemini 直连,不再必须过 OpenRouter。还集成了 models.dev 注册表 自动检测任意 provider 的 context length。

H. 集中式日志 + 结构验证

#5430 — ~/.hermes/logs/agent.log + errors.log, hermes logs 命令跟踪过滤。#5426 — 启动时验证 config.yaml 结构。

18Docker 运行时

Dockerfile

来源:Dockerfile:1-46(46 行,简短)。三阶段构建:

1. ghcr.io/astral-sh/uv:0.11.6-python3.13-trixie 作为 uv 源 Dockerfile:1
2. tianon/gosu:1.19-trixie 作为 gosu 源 Dockerfile:2 — gosu 是用来丢 root 权限的轻量替代 su
3. debian:13.4 作为最终 base Dockerfile:3

关键环境变量 Dockerfile:7-10:

• PYTHONUNBUFFERED=1 — 实时刷日志
• PLAYWRIGHT_BROWSERS_PATH=/opt/hermes/.playwright — "Store Playwright browsers outside the volume mount so the build-time install survives the /opt/data volume overlay at runtime"。这是典型的 Docker volume 覆盖细节问题 — 如果装在 /opt/data 下,runtime mount 覆盖会抹掉安装

APT 包列表 Dockerfile:14-15: build-essential nodejs npm python3 ripgrep ffmpeg gcc python3-dev libffi-dev procps —— 注意:这里没有 git。这是我们昨天部署时踩到的坑, npm install 需要 git 但 Dockerfile 没装,导致 build 失败,需要 sed 补丁。

entrypoint.sh

docker/entrypoint.sh:1-64:

• root → hermes 降权(docker/entrypoint.sh:11-30): 如果以 root 启动,先检查并重映射 hermes 用户的 UID/GID(通过 HERMES_UID/HERMES_GID 环境变量),fix 数据卷所有权,然后 exec gosu hermes "$0" "$@"
• 目录结构初始化(docker/entrypoint.sh:42): mkdir -p $HERMES_HOME/{cron,sessions,logs,hooks,memories,skills,skins,plans,workspace,home} —— 最后那个 home 很巧妙,注释解释:"Without it those tools [git, ssh, gh, npm] write to /root which is ephemeral and shared across profiles"
• 首次启动 seed 默认文件:如果 .env / config.yaml / SOUL.md 不存在,从 INSTALL_DIR 的 example 文件复制
• 同步 bundled skills(docker/entrypoint.sh:60-62): python3 $INSTALL_DIR/tools/skills_sync.py 基于 manifest,保留用户编辑
• 最后 exec hermes "$@"

19设计洞察(主观)

读完之后几个主观结论 —— 不是源码里写的,是我看源码之后的归纳:

1. 模块化的纪律比任何单点技术重要

Hermes 能支持 22 个消息平台 + 6 种终端后端 + 11 个 LLM provider + 78 个 skill,不是因为每个都写得多好, 而是因为工具注册表 + 抽象基类 + slash 命令中心化让新增成本低到可接受。 看 BasePlatformAdapter、BaseEnvironment、ToolRegistry、 COMMAND_REGISTRY 这 4 个抽象,就明白为什么 v0.8 能在一个周期合并 209 个 PR。

2. 真正的性能优化都在"不重建"上

Gateway 的 _agent_cache、_tool_loop 的持久 loop、Anthropic 的 prompt cache 保护…… 所有优化都是"能不重建就不重建"。这让 Hermes 对 prompt caching 友好的 LLM(Anthropic)比对不友好的 便宜 10 倍。这不是理论 —— AGENTS.md:339-347 把这个原则写成铁律。

3. 它把"agent 能跑哪"和"agent 用啥模型"解耦了

传统 agent 把两件事绑一起。Hermes 的终端后端和 LLM provider 是两个独立的抽象: 你可以把 agent 放在 $5 VPS 上,代码执行转发到 Modal 上的 GPU 实例,模型调 Anthropic Opus, 三者都可以独立换。这个解耦是真正的产品差异化。

4. 它承认自己是"一个会用工具的 LLM",而不是"有 LLM 的应用"

主循环本质就是 while: LLM call → handle tool calls → repeat。 Hermes 的所有复杂度都在工具生态、平台适配、状态持久化、安全边界上 —— agent loop 本身 2000 行里大部分是错误处理、重试、审批、中断、预算、流式回调,而不是"AI 逻辑"。 这符合"agent 是一个模式,不是一种算法"的设计哲学。

5. 自进化不是魔法,是 DSPy + 基准测试闭环

v0.8 的 "Self-Optimized GPT/Codex Tool-Use Guidance"(#6120)揭示了自进化的实现路径: 跑 benchmark → 识别失败模式 → 用 DSPy/GEPA 优化 prompt → 回灌。 独立仓库 hermes-agent-self-evolution 印证这点。 换句话说,自进化是工程,不是玄学。