架构
本页面是 Hermes Agent 内部机制的顶层地图。用它来定位你在代码库中的位置，然后深入子系统特定的文档了解实现细节。
系统概览
┌─────────────────────────────────────────────────────────────────────┐
│ 入口点 │
│ │
│ CLI (cli.py) 网关 (gateway/run.py) ACP (acp_adapter/) │
│ 批处理运行器 API 服务器 Python 库 │
└──────────┬──────────────┬───────────────────────┬───────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ AIAgent (run_agent.py) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Prompt │ │ Provider │ │ 工具 │ │
│ │ 构建器 │ │ 解析 │ │ 调度 │ │
│ │ (prompt_ │ │ (runtime_ │ │ (model_ │ │
│ │ builder.py) │ │ provider.py)│ │ tools.py) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │
│ │ 压缩 │ │ 3 种 API 模式 │ │ 工具注册表 │ │
│ │ 与缓存 │ │ chat_compl. │ │ (registry.py)│ │
│ │ │ │ codex_resp. │ │ 47 个工具 │ │
│ │ │ │ anthropic │ │ 19 个工具集 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌───────────────────┐ ┌──────────────────────┐
│ 会话存储 │ │ 工具后端 │
│ (SQLite + FTS5) │ │ 终端 (6 个后端) │
│ hermes_state.py │ │ 浏览器 (5 个后端) │
│ gateway/session.py│ │ 网络 (4 个后端) │
└───────────────────┘ │ MCP（动态） │
│ 文件、视觉等 │
└──────────────────────┘
目录结构
hermes-agent/
├── run_agent.py # AIAgent — 核心对话循环（约 10,700 行）
├── cli.py # HermesCLI — 交互式终端 UI（约 10,000 行）
├── model_tools.py # 工具发现、schema 收集、调度
├── toolsets.py # 工具分组和平台预设
├── hermes_state.py # SQLite 会话/状态数据库（FTS5）
├── hermes_constants.py # HERMES_HOME、配置文件感知路径
├── batch_runner.py # 批处理轨迹生成
│
├── agent/ # Agent 内部机制
│ ├── prompt_builder.py # 系统提示组装
│ ├── context_engine.py # ContextEngine ABC（可插拔）
│ ├── context_compressor.py # 默认引擎 — 有损摘要
│ ├── prompt_caching.py # Anthropic prompt 缓存
│ ├── 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 # Skill 斜杠命令
│ ├── 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 + 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 # 终端回调（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 锁、配置文件作用域的进程跟踪
│ ├── 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/ # 内存 provider 插件
├── 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() → 循环
→ 最终响应 → 显示 → 保存到 SessionDB
Gateway 消息
平台事件 → Adapter.on_message() → MessageEvent
→ GatewayRunner._handle_message()
→ 授权用户
→ 解析会话 key
→ 使用会话历史创建 AIAgent
→ AIAgent.run_conversation()
→ 通过 adapter 投递响应
Cron 任务
调度器触发 → 从 jobs.json 加载到期任务
→ 创建新的 AIAgent（无历史）
→ 注入附加的技能作为上下文
→ 运行任务 prompt
→ 将响应投递到目标平台
→ 更新任务状态和 next_run
推荐阅读顺序
如果你是代码库的新手：
- 本页面 — 定位自己
- Agent 循环内部机制 — AIAgent 如何工作
- Prompt 组装 — 系统提示构建
- Provider 运行时解析 — Provider 如何被选择
- 添加 Provider — 添加新 provider 的实践指南
- 工具运行时 — 工具注册表、调度、环境
- 会话存储 — SQLite schema、FTS5、会话血统
- Gateway 内部机制 — 消息平台网关
- 上下文压缩与 Prompt 缓存 — 压缩和缓存
- ACP 内部机制 — IDE 集成
- 环境、基准测试与数据生成 — RL 训练
主要子系统
Agent 循环
同步编排引擎（run_agent.py 中的 AIAgent）。处理 provider 选择、prompt 构建、工具执行、重试、回退、回调、压缩和持久化。支持三种 API 模式用于不同的 provider 后端。
Prompt 系统
对话生命周期中的 prompt 构建和维护：
prompt_builder.py— 从以下内容组装系统提示：个性（SOUL.md）、内存（MEMORY.md、USER.md）、技能、上下文文件（AGENTS.md、.hermes.md）、工具使用指导、模型特定指令prompt_caching.py— 应用 Anthropic 缓存断点进行前缀缓存context_compressor.py— 当上下文超过阈值时摘要中间对话 turn
Provider 解析
CLI、gateway、Cron、ACP 和辅助调用共用的运行时解析器。将 (provider, model) 元组映射到 (api_mode, api_key, base_url)。支持 18+ 个 provider、OAuth 流程、凭证池和别名解析。
工具系统
中央工具注册表（tools/registry.py），19 个工具集中注册了 47 个工具。每个工具文件在导入时自注册。注册表处理 schema 收集、调度、可用性检查和错误包装。终端工具支持 6 个后端（local、Docker、SSH、Daytona、Modal、Singularity）。
→ 工具运行时
会话持久化
基于 SQLite 的会话存储，带 FTS5 全文搜索。会话具有血统跟踪（跨压缩的父/子关系）、按平台隔离和带竞争处理的原子写入。
→ 会话存储
消息网关
长期运行的进程，拥有 18 个平台适配器、统一会话路由、用户授权（白名单 + DM 配对）、斜杠命令调度、钩子系统、Cron 定时触发和后台维护。
插件系统
三个发现源：~/.hermes/plugins/（用户）、.hermes/plugins/（项目）和 pip 入口点。插件通过上下文 API 注册工具、钩子和 CLI 命令。存在两种专门的插件类型：内存 provider（plugins/memory/）和上下文引擎（plugins/context_engine/）。两者都是单选——同一时间只能各激活一个，通过 hermes plugins 或 config.yaml 配置。
Cron
一流的 agent 任务（而非 shell 任务）。任务存储在 JSON 中，支持多种调度格式，可以附加技能和脚本，并投递到任何平台。
ACP 集成
通过 stdio/JSON-RPC 将 Hermes 暴露为编辑器原生 agent，支持 VS Code、Zed 和 JetBrains。
→ ACP 内部机制
RL / 环境 / 轨迹
完整的评估和 RL 训练环境框架。集成 Atropos，支持多种工具调用解析器，生成 ShareGPT 格式的轨迹。
设计原则
| 原则 | 实践中的含义 |
|---|---|
| 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 （无依赖 — 被所有工具文件导入）
↑
tools/*.py （每个在导入时调用 registry.register()）
↑
model_tools.py （导入 tools/registry + 触发工具发现）
↑
run_agent.py、cli.py、batch_runner.py、environments/
这条依赖链意味着工具注册在导入时发生，早于任何 agent 实例的创建。任何带有顶层 registry.register() 调用的 tools/*.py 文件都会被自动发现——无需手动导入列表。
📝 本文由 AI 翻译，如有疑问请参考英文原版