架构
本页是 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. │ │ 47 tools │ │
│ │ │ │ anthropic │ │ 19 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 — 核心对话循环（约 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 prompt caching
│ ├── auxiliary_client.py # 辅助 LLM 客户端（视觉、摘要等）
│ ├── model_metadata.py # 模型上下文长度、token 估算
│ ├── models_dev.py # models.dev 注册表集成
│ ├── anthropic_adapter.py # Anthropic Messages API 格式转换
│ ├── display.py # KawaiiSpinner、工具预览格式化
│ ├── skill_commands.py # 技能斜杠命令
│ ├── memory_manager.py # 记忆管理器编排
│ ├── memory_provider.py # 记忆大模型提供商（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 # 模型目录、大模型提供商（provider）模型列表
│ ├── model_switch.py # `/model` 命令逻辑（CLI 与网关共享）
│ ├── 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 # 终端回调（clarify、sudo、approval）
│ └── 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 # 子代理委派
│ ├── 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 # token 锁与 profile 级进程跟踪
│ ├── builtin_hooks/ # 始终注册的钩子
│ └── platforms/ # 18 个适配器：telegram、discord、slack、whatsapp 等
│
├── acp_adapter/ # ACP 服务器（VS Code / Zed / JetBrains）
├── cron/ # 调度系统（jobs.py、scheduler.py）
├── plugins/memory/ # 记忆大模型提供商（provider）插件
├── plugins/context_engine/ # 上下文引擎插件
├── environments/ # RL 训练环境（Atropos）
├── skills/ # 内置技能（始终可用）
├── optional-skills/ # 官方可选技能（需显式安装）
├── website/ # Docusaurus 文档站点
└── tests/ # Pytest 测试套件（3,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
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
推荐阅读顺序
如果你是第一次阅读这个代码库，推荐按以下顺序进入：
- 本页 — 建立整体认识
- Agent Loop Internals — 理解 AIAgent 的工作方式
- Prompt Assembly — 理解系统提示如何构建
- Provider Runtime Resolution — 理解大模型提供商（provider）选择逻辑
- Adding Providers — 添加新大模型提供商（provider）的实践指南
- Tools Runtime — 工具注册、分发与环境
- Session Storage — SQLite 架构、FTS5、会话沿袭
- Gateway Internals — 消息平台网关实现
- Context Compression & Prompt Caching — 压缩与缓存
- ACP Internals — IDE 集成
- Environments, Benchmarks & Data Generation — RL 训练与评估
主要子系统
Agent Loop
同步编排引擎（run_agent.py 中的 AIAgent）。负责大模型提供商（provider）选择、提示构建、工具执行、重试、回退、回调、压缩和持久化，并支持三种 API 模式以适配不同后端。
Prompt System
贯穿整个对话生命周期的提示构建与维护：
prompt_builder.py— 从个性（SOUL.md）、记忆（MEMORY.md、USER.md）、技能、上下文文件（AGENTS.md、.hermes.md）、工具使用指导和模型特定指令组装系统提示prompt_caching.py— 为 Anthropic 前缀缓存应用 cache breakpointscontext_compressor.py— 当上下文超过阈值时，总结中间会话轮次
→ Prompt Assembly, Context Compression & Prompt Caching
Provider Resolution
CLI、网关、cron、ACP 与辅助调用共享的运行时解析器。它将 (provider, model) 元组映射为 (api_mode, api_key, base_url)，并处理 18+ 个大模型提供商（provider）、OAuth 流程、凭据池和别名解析。
Tool System
中央工具注册表（tools/registry.py）目前包含 19 个工具集中的 47 个注册工具。每个工具文件在 import 时自注册，注册表负责 schema 收集、分发、可用性检查和错误封装。终端工具支持 6 个后端（local、Docker、SSH、Daytona、Modal、Singularity）。
Session Persistence
基于 SQLite 的会话存储，带 FTS5 全文检索。支持会话沿袭追踪（压缩前后的 parent/child 关系）、按平台隔离，以及带争用处理的原子写入。
Messaging Gateway
长期运行的进程，包含 18 个平台适配器、统一会话路由、用户授权（allowlist + DM pairing）、斜杠命令分发、钩子系统、cron tick 和后台维护逻辑。
Plugin System
三类发现来源：~/.hermes/plugins/（用户）、.hermes/plugins/（项目）、pip entry points。插件通过上下文 API 注册工具、钩子和 CLI 命令。还存在两类专门插件：记忆大模型提供商（provider）（plugins/memory/）和上下文引擎（plugins/context_engine/）。两者都是单选型，同一时刻只能启用一个，通过 hermes plugins 或 config.yaml 配置。
→ Plugin Guide, Memory Provider Plugin
Cron
一等公民级的代理任务系统，而不是 shell 任务系统。作业以 JSON 形式存储，支持多种调度格式，可附加技能与脚本，并能投递到任意平台。
ACP Integration
通过 stdio/JSON-RPC 将 Hermes 作为编辑器原生代理暴露给 VS Code、Zed 和 JetBrains。
RL / Environments / Trajectories
完整的环境框架，用于评估与强化学习训练。可与 Atropos 集成，支持多种工具调用解析器，并生成 ShareGPT 格式轨迹。
→ Environments, Benchmarks & Data Generation, Trajectories & Training Format
设计原则
| Principle | What it means in practice |
|---|---|
| Prompt stability | 系统提示在对话中途不会变化。除显式用户动作（如 /model）外，不进行破坏缓存的中途变更。 |
| Observable execution | 每次工具调用都通过回调对用户可见。CLI 用 spinner、网关用聊天消息展示进度。 |
| Interruptible | API 调用和工具执行都可以被用户输入或信号中断。 |
| Platform-agnostic core | 一个 AIAgent 同时服务于 CLI、网关、ACP、batch 和 API server。平台差异停留在入口层，而不是 agent 核心。 |
| Loose coupling | MCP、插件、记忆大模型提供商（provider）、RL 环境等可选子系统通过注册表模式和 check_fn 门控接入，而不是硬依赖。 |
| Profile isolation | 每个 profile（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/
这条依赖链意味着工具注册发生在 import 阶段，也就是任何 agent 实例创建之前。只要 tools/*.py 文件中存在顶层 registry.register() 调用，它就会被自动发现，无需手动维护导入列表。