架构

本页是 Hermes Agent 内部结构的顶层概览。请使用它来了解代码库的整体布局，然后深入各个子系统文档以获取实现细节。

系统概览

┌─────────────────────────────────────────────────────────────────────┐
│                        Entry Points                                  │
│                                                                      │
│  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 Modes  │ │ Tool Registry│                │
│  │ & Caching    │ │ chat_compl.  │ │ (registry.py)│                │
│  │              │ │ codex_resp.  │ │ 48 tools     │                │
│  │              │ │ anthropic    │ │ 40 toolsets   │                │
│  └──────────────┘ └──────────────┘ └──────────────┘                │
└─────────────────────────────────────────────────────────────────────┘
           │                                    │
           ▼                                    ▼
┌───────────────────┐              ┌──────────────────────┐
│ 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 —— 核心对话循环（约 9,200 行）
├── cli.py                    # HermesCLI —— 交互式终端界面（约 8,500 行）
├── model_tools.py            # Tool 发现、Schema 收集与分发
├── toolsets.py               # Tool 分组与平台预设
├── hermes_state.py           # SQLite 会话 / 状态数据库与 FTS5
├── hermes_constants.py       # HERMES_HOME 与 profile 感知路径
├── batch_runner.py           # 批量轨迹生成
│
├── agent/                    # Agent 内部结构
│   ├── prompt_builder.py     # System Prompt 组装
│   ├── context_engine.py     # ContextEngine ABC（可插拔）
│   ├── context_compressor.py # 默认引擎——有损摘要
│   ├── prompt_caching.py     # Anthropic Prompt 缓存
│   ├── auxiliary_client.py   # 用于辅助任务的辅助 LLM（Vision、总结）
│   ├── model_metadata.py     # Model Context 长度与 Token 估算
│   ├── models_dev.py         # models.dev 注册表集成
│   ├── anthropic_adapter.py  # Anthropic 消息 API 格式转换
│   ├── display.py            # KawaiiSpinner、Tool 预览格式
│   ├── skill_commands.py     # Skill 斜杠命令
│   ├── memory_manager.py    # Memory 管理器编排
│   ├── memory_provider.py   # Memory Provider ABC
│   └── trajectory.py         # 轨迹保存助手
│
├── hermes_cli/               # CLI 子命令和设置
│   ├── main.py               # 入口点 —— 所有 `hermes` 子命令
│   ├── config.py             # DEFAULT_CONFIG、OPTIONAL_ENV_VARS、迁移
│   ├── commands.py           # COMMAND_REGISTRY — 中央斜线命令定义
│   ├── auth.py               # PROVIDER_REGISTRY，凭证解析
│   ├── runtime_provider.py   # Provider → `api_mode` + 凭证
│   ├── models.py             # Model 目录、Provider 模型列表
│   ├── 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/                    # Tool 实现（每个 Tool 一个文件）
│   ├── registry.py           # 中央 tool 注册表
│   ├── approval.py           # 危险命令检测
│   ├── terminal_tool.py      # 终端编排
│   ├── process_registry.py   # 后台进程管理
│   ├── file_tools.py         # 读文件、写文件、补丁、搜索文件
│   ├── web_tools.py          # 网络搜索、网络提取
│   ├── browser_tool.py       # 11 个浏览器自动化 Tool
│   ├── code_execution_tool.py # `execute_code` 沙箱
│   ├── delegate_tool.py      # Subagent 委派
│   ├── mcp_tool.py           # MCP 客户端（约 2,200 行）
│   ├── credential_files.py   # 基于文件的凭证传递
│   ├── env_passthrough.py    # 沙箱的环境变量直通
│   ├── ansi_strip.py         # ANSI 逃逸剥离
│   └── environments/         # 终端后端（本地、Docker、SSH、Modal、Daytona、Singularity）
│
├── gateway/                  # 消息平台 Gateway
│   ├── run.py                # GatewayRunner —— 消息分发（约 7,500 行）
│   ├── session.py            # SessionStore — 会话持久化
│   ├── delivery.py           # 出站消息传递
│   ├── pairing.py            # DM配对授权
│   ├── hooks.py              # 钩子发现和生命周期事件
│   ├── mirror.py             # 跨session消息镜像
│   ├── status.py             # Token 锁，profile 范围内的进程跟踪
│   ├── builtin_hooks/        # 始终注册的钩子
│   └── platforms/            # 15 个适配器：telegram、discord、slack、whatsapp、
│                             #   signal、matrix、mattermost、电子邮件、短信、
│                             #   dingtalk、feishu、wecom、weixin、bluebubbles、家庭助理、webhook
│
├── acp_adapter/              # ACP 服务器（VS 代码 / Zed / JetBrains）
├── cron/                     # 调度程序（jobs.py、scheduler.py）
├── plugins/memory/           # Memory provider 插件
├── plugins/context_engine/   # Context 引擎插件
├── environments/             # 强化学习训练环境 (Atropos)
├── skills/                   # 捆绑 skills（始终可用）
├── optional-skills/          # 官方可选skills（显式安装）
├── website/                  # Docusaurus 文档网站
└── tests/                    # Pytest 套件（“0”，000+ 测试）

数据流

CLI 会话

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

网关消息

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

定时任务

Scheduler tick → load due jobs from jobs.json
  → create fresh AIAgent (no history)
  → inject attached skills as context
  → run job prompt
  → deliver response to target platform
  → update job state and next_run

推荐阅读顺序

如果你是代码库的新手：

1. 本页 —— 了解整体架构
2. Agent 循环内部机制 —— AIAgent 的工作原理
3. 提示词组装 —— 系统提示词的构建
4. 提供者运行时解析 —— 提供者的选择机制
5. 添加提供者 —— 添加新提供者的实践指南
6. 工具运行时 —— 工具注册表、分发与运行环境
7. 会话存储 —— SQLite 模式、FTS5、会话传承关系
8. 网关内部机制 —— 消息平台网关
9. 上下文压缩与提示词缓存 —— 上下文压缩与缓存机制
10. ACP 内部机制 —— IDE 集成
11. 环境、基准测试与数据生成 —— 强化学习训练

主要子系统

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、网关、定时任务、ACP 和辅助调用共用的运行时解析器。将 (provider, model) 元组映射为 (api_mode, api_key, base_url)。支持 18+ 个提供者，处理 OAuth 流程、凭证池和别名解析。

→ 提供者运行时解析

工具系统

中央工具注册表（tools/registry.py），包含 20 个工具集中的 47 个已注册工具。每个工具文件在导入时自动注册。注册表负责模式收集、分发、可用性检查和错误包装。终端工具支持 6 种后端（本地、Docker、SSH、Daytona、Modal、Singularity）。

→ 工具运行时

会话持久化

基于 SQLite 的会话存储，支持 FTS5 全文搜索。会话具备传承追踪（压缩过程中的父子关系）、跨平台隔离，以及带竞争处理的原子写入。

→ 会话存储

消息网关

长期运行的进程，包含 14 个平台适配器，统一会话路由、用户授权（白名单 + 私信配对）、斜杠命令分发、钩子系统、定时任务触发和后台维护。

→ 网关内部机制

插件系统

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

→ 插件指南，记忆提供者插件

定时任务

原生的 Agent 任务（非 shell 任务）。任务以 JSON 格式存储，支持多种调度格式，可附加技能和脚本，并可发送至任意平台。

→ 定时任务内部机制

ACP 集成

通过 stdio/JSON-RPC 将 Hermes 作为编辑器原生 Agent 暴露给 VS Code、Zed 和 JetBrains。

→ ACP 内部机制

强化学习 / 环境 / 轨迹

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

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

设计原则

原则	实际含义
提示稳定性	系统提示在对话过程中不会改变。除用户显式操作（如 /model）外，不会出现破坏缓存的变更。
可观察的执行	每个工具调用都会通过回调对用户可见。CLI 中显示进度（旋转图标），网关中显示聊天消息。
可中断性	用户输入或信号可随时取消正在进行的 API 调用和工具执行。
平台无关的核心	一个 AIAgent 类同时支持 CLI、网关、ACP、批处理和 API 服务器。平台差异仅存在于入口点，而非 Agent 本身。
松耦合	可选子系统（MCP、插件、记忆提供者、强化学习环境）使用注册表模式和 check_fn 门控机制，而非硬依赖。
配置文件隔离	每个配置文件（hermes -p <name>）拥有独立的 HERMES_HOME、配置、记忆、会话和网关 PID。多个配置文件可并发运行。

文件依赖链

tools/registry.py  (no deps — imported by all tool files)
       ↑
tools/*.py  (each calls registry.register() at import time)
       ↑
model_tools.py  (imports tools/registry + triggers tool discovery)
       ↑
run_agent.py, cli.py, batch_runner.py, environments/

该依赖链意味着工具注册在导入时完成，早于任何 Agent 实例的创建。添加新工具需要在 model_tools.py 的 _discover_tools() 列表中添加导入。