架构

本页面是 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 — core conversation loop (~9,200 lines)  
├── cli.py                    # HermesCLI — interactive terminal UI (~8,500 lines)  
├── model_tools.py            # Tool discovery, schema collection, dispatch  
├── toolsets.py               # Tool groupings and platform presets  
├── hermes_state.py           # SQLite session/state database with FTS5  
├── hermes_constants.py       # HERMES_HOME, profile-aware paths  
├── batch_runner.py           # Batch trajectory generation  
│  
├── agent/                    # Agent internals  
│   ├── prompt_builder.py     # System prompt assembly  
│   ├── context_engine.py     # ContextEngine ABC (pluggable)  
│   ├── context_compressor.py # Default engine — lossy summarization  
│   ├── prompt_caching.py     # Anthropic prompt caching  
│   ├── auxiliary_client.py   # Auxiliary LLM for side tasks (vision, summarization)  
│   ├── model_metadata.py     # Model context lengths, token estimation  
│   ├── models_dev.py         # models.dev registry integration  
│   ├── anthropic_adapter.py  # Anthropic Messages API format conversion  
│   ├── display.py            # KawaiiSpinner, tool preview formatting  
│   ├── skill_commands.py     # Skill slash commands  
│   ├── memory_manager.py    # Memory manager orchestration  
│   ├── memory_provider.py   # Memory provider ABC  
│   └── trajectory.py         # Trajectory saving helpers  
│  
├── hermes_cli/               # CLI subcommands and setup  
│   ├── main.py               # Entry point — all `hermes` subcommands (~5,500 lines)  
│   ├── config.py             # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration  
│   ├── commands.py           # COMMAND_REGISTRY — central slash command definitions  
│   ├── auth.py               # PROVIDER_REGISTRY, credential resolution  
│   ├── runtime_provider.py   # Provider → api_mode + credentials  
│   ├── models.py             # Model catalog, provider model lists  
│   ├── model_switch.py       # /model command logic (CLI + gateway shared)  
│   ├── setup.py              # Interactive setup wizard (~3,100 lines)  
│   ├── skin_engine.py        # CLI theming engine  
│   ├── skills_config.py      # hermes skills — enable/disable per platform  
│   ├── skills_hub.py         # /skills slash command  
│   ├── tools_config.py       # hermes tools — enable/disable per platform  
│   ├── plugins.py            # PluginManager — discovery, loading, hooks  
│   ├── callbacks.py          # Terminal callbacks (clarify, sudo, approval)  
│   └── gateway.py            # hermes gateway start/stop  
│  
├── tools/                    # Tool implementations (one file per tool)  
│   ├── registry.py           # Central tool registry  
│   ├── approval.py           # Dangerous command detection  
│   ├── terminal_tool.py      # Terminal orchestration  
│   ├── process_registry.py   # Background process management  
│   ├── file_tools.py         # read_file, write_file, patch, search_files  
│   ├── web_tools.py          # web_search, web_extract  
│   ├── browser_tool.py       # 11 browser automation tools  
│   ├── code_execution_tool.py # execute_code sandbox  
│   ├── delegate_tool.py      # Subagent delegation  
│   ├── mcp_tool.py           # MCP client (~2,200 lines)  
│   ├── credential_files.py   # File-based credential passthrough  
│   ├── env_passthrough.py    # Env var passthrough for sandboxes  
│   ├── ansi_strip.py         # ANSI escape stripping  
│   └── environments/         # Terminal backends (local, docker, ssh, modal, daytona, singularity)  
│  
├── gateway/                  # Messaging platform gateway  
│   ├── run.py                # GatewayRunner — message dispatch (~7,500 lines)  
│   ├── session.py            # SessionStore — conversation persistence  
│   ├── delivery.py           # Outbound message delivery  
│   ├── pairing.py            # DM pairing authorization  
│   ├── hooks.py              # Hook discovery and lifecycle events  
│   ├── mirror.py             # Cross-session message mirroring  
│   ├── status.py             # Token locks, profile-scoped process tracking  
│   ├── builtin_hooks/        # Always-registered hooks  
│   └── platforms/            # 15 adapters: telegram, discord, slack, whatsapp,  
│                             #   signal, matrix, mattermost, email, sms,  
│                             #   dingtalk, feishu, wecom, weixin, bluebubbles, homeassistant, webhook  
│  
├── acp_adapter/              # ACP server (VS Code / Zed / JetBrains)  
├── cron/                     # Scheduler (jobs.py, scheduler.py)  
├── plugins/memory/           # Memory provider plugins  
├── plugins/context_engine/   # Context engine plugins  
├── environments/             # RL training environments (Atropos)  
├── skills/                   # Bundled skills (always available)  
├── optional-skills/          # Official optional skills (install explicitly)  
├── website/                  # Docusaurus documentation site  
└── tests/                    # Pytest suite (~3,000+ tests)

数据流

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

Gateway 消息

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

Cron 任务

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 Loop 内部机制——AIAgent 如何工作
3. Prompt 组装——系统 prompt 构建
4. Provider 运行时解析——Provider 如何被选择
5. 添加 Provider——添加新 provider 的实用指南
6. 工具运行时——工具注册、分发、环境
7. 会话存储——SQLite schema、FTS5、会话世系
8. Gateway 内部机制——消息平台网关
9. 上下文压缩与 Prompt 缓存——压缩和缓存
10. ACP 内部机制——IDE 集成
11. 环境、基准测试与数据生成——RL 训练

主要子系统

Agent Loop

同步编排引擎（run_agent.py 中的 AIAgent）。处理 provider 选择、prompt 构建、工具执行、重试、回退、回调、压缩和持久化。支持三种 API 模式用于不同的 provider 后端。

-> Agent Loop 内部机制

Prompt 系统

跨对话生命周期的 prompt 构建和维护：

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

-> Prompt 组装、上下文压缩与 Prompt 缓存

Provider 解析

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

-> Provider 运行时解析

工具系统

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

-> 工具运行时

会话持久化

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

-> 会话存储

消息网关

长运行进程，具有 14 个平台 adapter、统一会话路由、用户授权（白名单 + DM 配对）、slash 命令分发、Hook 系统、cron 定时和后台维护。

-> Gateway 内部机制

插件系统

三个发现来源：~/.hermes/plugins/（用户）、.hermes/plugins/（项目）和 pip entry point。插件通过上下文 API 注册工具、Hook 和 CLI 命令。存在两种专用插件类型：记忆 provider（plugins/memory/）和上下文引擎（plugins/context_engine/）。两者都是单选——每种同时只能激活一个，通过 hermes plugins 或 config.yaml 配置。

-> 插件指南、记忆 Provider 插件

Cron

一等 Agent 任务（非 Shell 任务）。任务存储在 JSON 中，支持多种调度格式，可以附加技能和脚本，并投递到任何平台。

-> Cron 内部机制

ACP 集成

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

-> ACP 内部机制

RL / 环境 / 轨迹

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

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

设计原则

原则	实际含义
Prompt 稳定性	系统 prompt 不会在对话中途改变。除了显式用户操作（/model）外没有缓存破坏性变更。
可观察执行	每个工具调用通过回调对用户可见。CLI（旋转器）和 gateway（聊天消息）中都有进度更新。
可中断	API 调用和工具执行可以被用户输入或信号中途取消。
平台无关的核心	一个 AIAgent 类服务于 CLI、gateway、ACP、批处理和 API 服务器。平台差异体现在入口点而非 agent 中。
松耦合	可选子系统（MCP、插件、记忆 provider、RL 环境）使用注册表模式和 check_fn 门控，而非硬依赖。
配置文件隔离	每个配置文件（hermes -p <name>）拥有独立的 HERMES_HOME、配置、记忆、会话和 gateway 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() 列表中添加一个导入。