架构

本页是 Hermes Agent 内部结构的高层概览。用它来定位你在代码库中的方向，然后深入到特定子系统的文档以获取实现细节。

系统概述

┌─────────────────────────────────────────────────────────────────────┐
│                        入口点                                        │
│                                                                      │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)     │
│  Batch Runner    API Server                  Python Library         │
└──────────┬──────────────┬───────────────────────┬───────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                          │
│                                                                      │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                │
│  │ Prompt       │ │ Provider     │ │ Tool         │                │
│  │ Builder      │ │ Resolution   │ │ Dispatch     │                │
│  │ (prompt_     │ │ (runtime_    │ │ (model_      │                │
│  │  builder.py) │ │  provider.py)│ │  tools.py)   │                │
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘                │
│         │                │                │                          │
│  ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐                │
│  │ Compression  │ │ 3 API 模式   │ │ Tool Registry │                │
│  │ & Caching    │ │ chat_compl.  │ │ (registry.py)│                │
│  │              │ │ codex_resp.  │ │ 47 个工具    │                │
│  │              │ │ anthropic    │ │ 19 个工具集   │                │
│  └──────────────┘ └──────────────┘ └──────────────┘                │
└─────────────────────────────────────────────────────────────────────┘
           │                                    │
           ▼                                    ▼
┌───────────────────┐              ┌──────────────────────┐
│ Session Storage   │              │ Tool Backends         │
│ (SQLite + FTS5)   │              │ Terminal (6 backends) │
│ hermes_state.py   │              │ Browser (5 backends)  │
│ gateway/session.py│              │ Web (4 backends)      │
└───────────────────┘              │ MCP (dynamic)         │
                                   │ File, Vision, etc.    │
                                   └──────────────────────┘

目录结构

hermes-agent/
├── run_agent.py              # AIAgent — 核心对话循环（约 10,700 行）
├── cli.py                    # HermesCLI — 交互式终端 UI（约 10,000 行）
├── model_tools.py            # 工具发现、schema 收集、分发
├── toolsets.py               # 工具分组和平台预设
├── hermes_state.py           # 带 FTS5 的 SQLite 会话/状态数据库
├── hermes_constants.py       # HERMES_HOME、profile 感知路径
├── batch_runner.py           # 批量轨迹生成
│
├── agent/                    # Agent 内部
│   ├── prompt_builder.py     # 系统提示词组装
│   ├── context_engine.py     # ContextEngine ABC（可插拔）
│   ├── context_compressor.py # 默认引擎 — 有损摘要算法
│   ├── prompt_caching.py     # Anthropic 提示词缓存
│   ├── auxiliary_client.py   # 辅助 LLM 客户端，用于辅助任务（视觉、摘要）
│   ├── model_metadata.py     # 模型上下文长度、令牌估算
│   ├── models_dev.py         # models.dev 注册集成
│   ├── anthropic_adapter.py  # Anthropic Messages API 格式转换
│   ├── display.py            # KawaiiSpinner、工具预览格式化
│   ├── skill_commands.py     # 技能斜杠命令
│   ├── memory_manager.py     # 记忆管理器编排
│   ├── memory_provider.py    # Memory Provider ABC
│   └── trajectory.py         # 轨迹保存辅助函数
│
├── hermes_cli/               # CLI 子命令和设置
│   ├── main.py               # 入口点 — 所有 `hermes` 子命令（约 6,000 行）
│   ├── config.py             # DEFAULT_CONFIG、OPTIONAL_ENV_VARS、迁移
│   ├── commands.py           # COMMAND_REGISTRY — 中央斜杠命令定义
│   ├── auth.py               # PROVIDER_REGISTRY、凭据解析
│   ├── runtime_provider.py   # Provider → api_mode + 凭据
│   ├── models.py             # 模型目录、提供商模型列表
│   ├── model_switch.py       # /model 命令逻辑（CLI 和 gateway 共享）
│   ├── setup.py              # 交互式设置向导（约 3,100 行）
│   ├── skin_engine.py        # CLI 主题引擎
│   ├── skills_config.py      # hermes skills — 每个平台启用/禁用
│   ├── skills_hub.py         # /skills 斜杠命令
│   ├── tools_config.py       # hermes tools — 每个平台启用/禁用
│   ├── plugins.py            # PluginManager — 发现、加载、钩子
│   ├── callbacks.py          # 终端回调（澄清、sudo、批准）
│   └── gateway.py            # hermes gateway 启动/停止
│
├── tools/                    # 工具实现（每个工具一个文件）
│   ├── registry.py           # 中央工具注册表
│   ├── approval.py           # 危险命令检测
│   ├── terminal_tool.py      # 终端编排
│   ├── process_registry.py   # 后台进程管理
│   ├── file_tools.py         # read_file、write_file、patch、search_files
│   ├── web_tools.py          # web_search、web_extract
│   ├── browser_tool.py       # 10 个浏览器自动化工具
│   ├── code_execution_tool.py # execute_code 沙箱
│   ├── delegate_tool.py      # 子 agent 委托
│   ├── mcp_tool.py           # MCP 客户端（约 2,200 行）
│   ├── credential_files.py   # 基于文件的凭据传递
│   ├── env_passthrough.py    # 沙箱环境变量传递
│   ├── ansi_strip.py         # ANSI 转义序列剥离
│   └── environments/         # 终端后端（local、docker、ssh、modal、daytona、singularity）
│
├── gateway/                  # 消息平台网关
│   ├── run.py                # GatewayRunner — 消息分发（约 9,000 行）
│   ├── session.py            # SessionStore — 对话持久化
│   ├── delivery.py           # 出站消息投递
│   ├── pairing.py            # DM 配对授权
│   ├── hooks.py              # 钩子发现和生命周期事件
│   ├── mirror.py             # 跨会话消息镜像
│   ├── status.py             # 令牌锁、profile 作用域进程跟踪
│   ├── builtin_hooks/        # 始终注册的钩子
│   └── platforms/            # 18 个适配器：telegram、discord、slack、whatsapp、
│                             #   signal、matrix、mattermost、email、sms、
│                             #   dingtalk、feishu、wecom、wecom_callback、weixin、
│                             #   bluebubbles、qqbot、homeassistant、webhook、api_server
│
├── acp_adapter/              # ACP 服务器（VS Code / Zed / JetBrains）
├── cron/                     # 调度器（jobs.py、scheduler.py）
├── plugins/memory/            # 记忆提供程序插件
├── plugins/context_engine/    # 上下文引擎插件
├── environments/              # RL 训练环境（Atropos）
├── skills/                   # 捆绑技能（始终可用）
├── optional-skills/          # 官方可选技能（显式安装）
├── website/                  # Docusaurus 文档站点
└── tests/                    # Pytest 测试套件（3,000+ 测试）

数据流

CLI 会话

用户输入 → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API 调用 (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → 循环
    → 最终响应 → display → 保存到 SessionDB

Gateway 消息

平台事件 → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → 授权用户
    → 解析会话键
    → 使用会话历史创建 AIAgent
    → AIAgent.run_conversation()
    → 通过适配器投递响应

Cron 任务

调度器 tick → 从 jobs.json 加载到期任务
  → 创建新的 AIAgent（无历史）
  → 将附加的技能作为上下文注入
  → 运行任务提示词
  → 将响应投递到目标平台
  → 更新任务状态和 next_run

主要子系统

Agent 循环

同步编排引擎（run_agent.py 中的 AIAgent）。处理提供商选择、提示词构建、工具执行、重试、回退、回调、压缩和持久化。支持三种 API 模式以适应不同的提供商后端。

→ Agent 循环内部原理

提示词系统

在整个对话生命周期中的提示词构建和维护：

prompt_builder.py — 从以下内容组装系统提示词：人格（SOUL.md）、记忆（MEMORY.md、USER.md）、技能、上下文文件（AGENTS.md、.hermes.md）、工具使用指导，和模型特定指令
prompt_caching.py — 应用 Anthropic 缓存断点以进行前缀缓存
context_compressor.py — 当上下文超过阈值时对中间对话轮次进行摘要

→ 提示词组装、上下文压缩与提示词缓存

提供商解析

CLI、gateway、cron、ACP 和辅助调用使用的共享运行时解析器。将 (provider, model) 元组映射到 (api_mode, api_key, base_url)。处理 18+ 个提供商、OAuth 流程、凭据池和别名解析。

→ 提供商运行时解析

工具系统

中央工具注册表（tools/registry.py），包含跨 19 个工具集的 47 个注册工具。每个工具文件在导入时自我注册。注册表处理 schema 收集、分发、可用性检查和错误包装。终端工具支持 6 个后端（local、Docker、SSH、Daytona、Modal、Singularity）。

→ 工具运行时

会话持久化

基于 SQLite 的会话存储，带 FTS5 全文搜索。会话有谱系跟踪（压缩时的父/子）、每个平台的隔离，以及具有竞争处理的原子写入。

→ 会话存储

消息网关

长期运行的进程，包含 18 个平台适配器、统一会话路由、用户授权（允许列表 + DM 配对）、斜杠命令分发、钩子系统、 cron ticking 和后台维护。

→ Gateway 内部原理

插件系统

三个发现源：~/.hermes/plugins/（用户）、.hermes/plugins/（项目）和 pip 入口点。插件通过上下文 API 注册工具、钩子和 CLI 命令。存在两种专门的插件类型：记忆提供程序（plugins/memory/）和上下文引擎（plugins/context_engine/）。两者都是单选的 — 任何时候只能激活一个，配置通过 hermes plugins 或 config.yaml。

→ 插件指南、记忆提供程序插件

Cron

一等公民 agent 任务（不是 shell 任务）。任务以 JSON 存储，支持多种调度格式，可以附加技能和脚本，并投递到任何平台。

→ Cron 内部原理

ACP 集成

通过 stdio/JSON-RPC 将 Hermes 暴露为编辑器原生 agent，用于 VS Code、Zed 和 JetBrains。

→ ACP 内部原理

RL / 环境 / 轨迹

用于评估和 RL 训练的完整环境框架。与 Atropos 集成，支持多种工具调用解析器，并生成 ShareGPT 格式的轨迹。

→ 环境、基准测试与数据生成、轨迹与训练格式

设计原则

| 原则 | 实际含义 | | |-----------|--------------------------| | 提示词稳定性 | 系统提示词在对话期间不会改变。除显式用户操作（/model）外，没有缓存破坏的变更。 | | 可观察执行 | 每个工具调用都通过回调对用户可见。CLI 中的进度更新（旋转器）和 gateway 中的聊天消息。 | | 可中断 | API 调用和工具执行可以被用户输入或信号在飞行中取消。 | | 平台无关核心 | 一个 AIAgent 类服务于 CLI、gateway、ACP、batch 和 API 服务器。平台差异存在于入口点，而非 agent。 | | 松耦合 | 可选子系统（MCP、插件、记忆提供程序、RL 环境）使用注册表模式和 check_fn 门控，而非硬依赖。 | | Profile 隔离 | 每个 profile（hermes -p <name>）获得自己的 HERMES_HOME、配置、记忆、会话和 gateway PID。多个 profile 可以并发运行。 |

文件依赖链

tools/registry.py  （无依赖 — 被所有工具文件导入）
       ↑
tools/*.py  （每个在导入时调用 registry.register()）
       ↑
model_tools.py  （导入 tools/registry + 触发工具发现）
       ↑
run_agent.py, cli.py, batch_runner.py, environments/

这条链意味着工具注册发生在导入时，在创建任何 agent 实例之前。任何带有顶层 registry.register() 调用的 tools/*.py 文件都会被自动发现 — 无需维护手动导入列表。

架构

系统概述

目录结构

数据流

CLI 会话

Gateway 消息

Cron 任务

推荐阅读顺序

主要子系统

Agent 循环

提示词系统

提供商解析

工具系统

会话持久化

消息网关

插件系统

Cron

ACP 集成

RL / 环境 / 轨迹

设计原则

文件依赖链

相关文档

系统概述​

目录结构​

数据流​

CLI 会话​

Gateway 消息​

Cron 任务​

推荐阅读顺序​

主要子系统​

Agent 循环​

提示词系统​

提供商解析​

工具系统​

会话持久化​

消息网关​

插件系统​

Cron​

ACP 集成​

RL / 环境 / 轨迹​

设计原则​

文件依赖链​

相关文档​

系统概述

目录结构

数据流

CLI 会话

Gateway 消息

Cron 任务

推荐阅读顺序

主要子系统

Agent 循环

提示词系统

提供商解析

工具系统

会话持久化

消息网关

插件系统

Cron

ACP 集成

RL / 环境 / 轨迹

设计原则

文件依赖链

相关文档