架構

本頁是 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() 列表中添加導入。