<!-- Source: https://hermesbible.com/docs/developer-guide/architecture -->
Section: Developer Guide · URL: https://hermesbible.com/docs/developer-guide/architecture
本頁是 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. │ │ 70+ tools │ │
│ │ │ │ anthropic │ │ 28 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 — 核心對話迴圈（大型檔案）
├── cli.py # HermesCLI — 互動式終端 UI（大型檔案）
├── model_tools.py # 工具發現、Schema 收集、分派
├── toolsets.py # 工具分組與平台預設值
├── hermes_state.py # SQLite session/state 資料庫，含 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 # Auxiliary LLM，處理輔助任務（視覺、摘要）
│ ├── model_metadata.py # 模型 context 長度、token 估算
│ ├── models_dev.py # models.dev 註冊表整合
│ ├── anthropic_adapter.py # Anthropic Messages API 格式轉換
│ ├── display.py # KawaiiSpinner、工具預覽格式化
│ ├── skill_commands.py # Skill 斜線指令
│ ├── memory_manager.py # Memory manager 編排
│ ├── 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 + credentials
│ ├── models.py # 模型目錄、供應商模型清單
│ ├── model_switch.py # /model 指令邏輯（CLI + gateway 共用）
│ ├── setup.py # 互動式設定精靈（大型檔案）
│ ├── skin_engine.py # CLI 主題引擎
│ ├── skills_config.py # hermes skills — 按平台啟用/停用
│ ├── skills_hub.py # /skills 斜線指令
│ ├── tools_config.py # hermes tools — 按平台啟用/停用
│ ├── plugins.py # PluginManager — 發現、載入、hooks
│ ├── callbacks.py # 終端回調（clarify、sudo、approval）
│ └── gateway.py # hermes gateway start/stop
│
├── 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 # Subagent 委派
│ ├── mcp_tool.py # MCP client（大型檔案）
│ ├── credential_files.py # 檔案式憑證傳遞
│ ├── env_passthrough.py # 沙箱環境變數傳遞
│ ├── ansi_strip.py # ANSI 轉義字元去除
│ └── environments/ # 終端後端（local、docker、ssh、modal、daytona、singularity）
│
├── gateway/ # 訊息平台閘道
│ ├── run.py # GatewayRunner — 訊息分派（大型檔案）
│ ├── session.py # SessionStore — 對話持久化
│ ├── delivery.py # 出站訊息投遞
│ ├── pairing.py # DM 配對授權
│ ├── hooks.py # Hook 發現與生命週期事件
│ ├── mirror.py # 跨 session 訊息鏡像
│ ├── status.py # Token 鎖定、profile 感知的程序追蹤
│ ├── builtin_hooks/ # 始終註冊的 hook 擴充點（無預設 hook）
│ └── platforms/ # 20 個適配器：telegram、discord、slack、whatsapp、
│ # signal、matrix、mattermost、email、sms、
│ # dingtalk、feishu、wecom、wecom_callback、weixin、
│ # bluebubbles、qqbot、homeassistant、webhook、api_server、
│ # yuanbao
│
├── acp_adapter/ # ACP 伺服器（VS Code / Zed / JetBrains）
├── cron/ # 排程器（jobs.py、scheduler.py）
├── plugins/memory/ # Memory provider 外掛
├── plugins/context_engine/ # Context engine 外掛
├── skills/ # 內建 skills（始終可用）
├── optional-skills/ # 官方可選 skills（需手動安裝）
├── website/ # Docusaurus 文件網站
└── tests/ # Pytest 測試套件（約 25,000 個測試，分布在 ~1,250 個檔案中）
資料流
CLI Session
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
建議閱讀順序
如果你是這個程式碼庫的新手：
- 本頁 — 先建立整體認知
- Agent Loop 內部機制 — AIAgent 的運作方式
- Prompt 組裝 — System prompt 的建構過程
- Provider Runtime 解析 — Provider 的選取機制
- 新增 Provider — 新增 Provider 的實務指南
- Tools Runtime — 工具註冊表、分派、執行環境
- Session 儲存 — SQLite Schema、FTS5、Session 血緣追蹤
- Gateway 內部機制 — 訊息平台閘道
- Context 壓縮與 Prompt 快取 — 壓縮與快取機制
- ACP 內部機制 — IDE 整合
主要子系統
Agent Loop
同步編排引擎（run_agent.py 中的 AIAgent）。處理 Provider 選擇、Prompt 建構、工具執行、重試、降級、回調、壓縮與持久化。支援三種 API 模式對應不同的 Provider 後端。
Prompt 系統
橫跨對話生命週期的 Prompt 建構與維護：
system_prompt.py+prompt_builder.py— 組裝有序的 system prompt 層級（stable→context→volatile）：身份/工具指引/skills、context 檔案，然後是記憶/設定檔/時間戳區塊prompt_caching.py— 套用 Anthropic cache 斷點進行前綴快取context_compressor.py— 當 context 超過閾值時，摘要中間的對話輪次
→ Prompt 組裝、Context 壓縮與 Prompt 快取
Provider 解析
共用的 Runtime 解析器，被 CLI、gateway、cron、ACP 和輔助呼叫共同使用。將 (provider, model) 元組映射為 (api_mode, api_key, base_url)。處理 18+ 個 Provider、OAuth 流程、憑證池和別名解析。
Tool 系統
中央工具註冊表（tools/registry.py），包含 70+ 個已註冊工具，分布在約 28 個 toolset 中。每個工具檔案在 import 時自動自我註冊。註冊表處理 Schema 收集、分派、可用性檢查和錯誤封裝。Terminal 工具支援 6 種後端（local、Docker、SSH、Daytona、Modal、Singularity）。
Session 持久化
基於 SQLite 的 session 儲存，搭配 FTS5 全文搜尋。Session 具有血緣追蹤（壓縮時的 parent/child 關係）、按平台隔離、原子寫入與競爭處理機制。
訊息閘道
長駐運行的程序，搭載 20 個平台適配器、統一的 session 路由、使用者授權（允許清單 + DM 配對）、斜線指令分派、hook 系統、cron 排程和背景維護作業。
外掛系統
三種發現來源：~/.hermes/plugins/（使用者級）、.hermes/plugins/（專案級）和 pip entry points。外掛透過 context API 註冊 tools、hooks 和 CLI 指令。兩種特殊的外掛類型：memory provider（plugins/memory/）和 context engine（plugins/context_engine/). 兩者都是單選——同時只能啟用一個，透過 hermes plugins 或 config.yaml 設定。
Cron
一等公民的 agent 任務（非 shell 任務）。任務以 JSON 儲存，支援多種排程格式，可附加 skills 和 scripts，並可投遞至任意平台。
ACP 整合
透過 stdio/JSON-RPC 將 Hermes 暴露為編輯器原生 agent，支援 VS Code、Zed 和 JetBrains。
→ ACP 內部機制
軌跡
從 agent session 生成 ShareGPT 格式的軌跡，用於訓練資料生成。
→ 軌跡與訓練格式
設計原則
| 原則 | 實務意涵 |
|---|---|
| Prompt 穩定性 | System prompt 不會在對話中途變動。除了使用者明確操作（/model）外，不會產生破壞快取的變更。 |
| 可觀測執行 | 每次工具呼叫都透過回調對使用者可見。CLI 中有進度更新（spinner），gateway 中有聊天訊息回報。 |
| 可中斷 | API 呼叫和工具執行可在進行中被使用者輸入或訊號取消。 |
| 平台無關核心 | 單一 AIAgent 類別服務 CLI、gateway、ACP、batch 和 API server。平台差異僅存在於進入點，不在 agent 本身。 |
| 鬆散耦合 | 可選子系統（MCP、外掛、memory provider、RL 環境）使用註冊表模式和 check_fn 閘控，而非硬性依賴。 |
| Profile 隔離 | 每個 profile（hermes -p <name>）有自己的 HERMES_HOME、設定、記憶、sessions 和 gateway PID。多個 profile 可同時運行。 |
檔案依賴鏈
tools/registry.py (無依賴 — 被所有工具檔案 import)
↑
tools/*.py (每個檔案在 import 時呼叫 registry.register())
↑
model_tools.py (import tools/registry + 觸發工具發現)
↑
run_agent.py、cli.py、batch_runner.py、environments/
這條依賴鏈意味著工具註冊發生在 import 時段，在任何 agent 實例建立之前。任何在頂層包含 registry.register() 呼叫的 tools/*.py 檔案都會被自動發現——無需手動維護 import 清單。