編程式集成

Hermes 提供了三種協議，用於從外部程序（如 IDE 插件、自定義 UI、CI 流水線、嵌入式子代理）驅動代理。請根據你的傳輸方式和消費者選擇匹配的協議。

協議	傳輸方式	適用場景	定義位置
ACP	基於 stdio 的 JSON-RPC	已經支持 Agent Client Protocol 的 IDE 客戶端（VS Code、Zed、JetBrains）	`acp_adapter/`
TUI 網關	基於 stdio（或 WebSocket）的 JSON-RPC	需要對會話、斜槓命令、審批和流式事件進行細粒度控制的自定義宿主	`tui_gateway/server.py`
API 服務器	HTTP + 服務器發送事件 (SSE)	兼容 OpenAI 的前端（Open WebUI、LobeChat、LibreChat……）以及語言無關的 Web 客戶端	`gateway/platforms/api_server.py`

這三種協議驅動的都是同一個 AIAgent 核心。它們的區別僅在於線路格式（wire format）以及所暴露的功能集。

ACP（Agent Client Protocol）

hermes acp 啟動一個通過 stdio 通信並遵循 ACP 協議的 JSON-RPC 服務器。它已被 VS Code（Zed Industries 的 ACP 擴展）、Zed 以及任何安裝了 ACP 插件的 JetBrains IDE 在生產環境中使用。

暴露的能力包括：會話創建、提示提交、流式代理消息片段、工具調用事件、權限請求、會話分支、取消以及身份驗證。工具輸出會被渲染為 IDE 可理解的 ACP Diff/ToolCall 內容塊。

完整的生命週期、事件橋接和審批流程詳見：ACP 內部機制。

hermes acp                  # serve ACP on stdio
hermes acp --bootstrap      # print install snippet for an ACP-capable IDE

TUI 網關 JSON-RPC

tui_gateway/server.py 是 Ink TUI（hermes --tui）和嵌入式儀表板 PTY 橋接所使用的協議。任何外部宿主都可以通過 stdio（或通過 tui_gateway/ws.py 使用 WebSocket）使用相同的協議進行通信。

方法目錄（精選）

prompt.submit           prompt.background       session.steer
session.create          session.list            session.active_list
session.activate        session.close           session.interrupt
session.history         session.compress        session.branch
session.title           session.usage           session.status
clarify.respond         sudo.respond            secret.respond
approval.respond        config.set / config.get commands.catalog
command.resolve         command.dispatch        cli.exec
reload.mcp              reload.env              process.stop
delegation.status       subagent.interrupt      spawn_tree.save / list / load
terminal.resize         clipboard.paste         image.attach

session.active_list、session.activate 和 session.close 是 TUI 會話切換器使用的進程內活躍會話控制方法。請使用 session.list / /resume 來發現已保存的轉錄記錄；僅對當前在 TUI 網關進程中打開的會話使用活躍會話方法。

回傳的事件流

message.delta、message.complete、tool.start、tool.progress、tool.complete、approval.request、clarify.request、sudo.request、secret.request、gateway.ready，以及會話生命週期和錯誤事件。

Pi 風格 RPC 映射

Pi-mono RPC 規範（issue #360）中的每個命令都有對應的 TUI 網關等效命令：

Pi 命令	Hermes 等效命令
`prompt`	`prompt.submit`（或 ACP `session/prompt`）
`steer`	`session.steer`
`follow_up`	在當前輪次後排隊的 `prompt.submit`
`abort`	`session.interrupt`
`set_model`	用於 `/model <provider:model>` 的 `command.dispatch`（會話中途，持久化）
`compact`	`session.compress`
`get_state`	`session.status`
`get_messages`	`session.history`
`switch_session`	`session.resume`
`fork`	`session.branch`
`ui_request` / `ui_response`	`clarify.respond` / `sudo.respond` / `secret.respond` / `approval.respond`

兼容 OpenAI 的 API 服務器

gateway/platforms/api_server.py 通過 HTTP 暴露 Hermes，適用於任何已經支持 OpenAI 格式的客戶端。當你需要 Web 前端、由 curl 驅動的 CI 運行器或非 Python 消費者時，這非常有用。

端點：

POST /v1/chat/completions        OpenAI Chat Completions (streaming via SSE)
POST /v1/responses               OpenAI Responses API (stateful)
POST /v1/runs                    Start a run, returns run_id (202)
GET  /v1/runs/{id}               Run status
GET  /v1/runs/{id}/events        SSE stream of lifecycle events
POST /v1/runs/{id}/approval      Resolve a pending approval
POST /v1/runs/{id}/stop          Interrupt the run
GET  /v1/capabilities            Machine-readable feature flags
GET  /v1/models                  Lists hermes-agent
GET  /health, /health/detailed

設置、頭部信息（X-Hermes-Session-Id、X-Hermes-Session-Key）以及前端連接配置詳見：API 服務器。

我該使用哪一個？

你正在編寫 IDE 插件，且該 IDE 已經支持 ACP → 使用 ACP。IDE 端無需進行額外的協議開發工作。
你正在編寫自定義桌面/Web/TUI 宿主，並希望使用所有 Hermes 功能（斜槓命令、審批、澄清、多代理、會話分支）→ 使用 TUI 網關 JSON-RPC。
你需要任何兼容 OpenAI 的前端、語言無關的 HTTP 客戶端，或由 curl 驅動的自動化 → 使用 API 服務器。
你想要無需子進程的 Python 進程內嵌入 → 直接導入 run_agent.AIAgent。詳見代理循環。

模型熱切換

會話中途的模型切換在所有界面上均有效——其底層實現是 /model 斜槓命令。

CLI / TUI： /model claude-sonnet-4 或 /model openrouter:anthropic/claude-sonnet-4.6
TUI 網關 RPC： 使用 {"command": "/model claude-sonnet-4"} 調用 command.dispatch
ACP： IDE 將斜槓命令作為提示發送；代理對其進行分發
API 服務器： 在請求體中包含 model 字段或設置 X-Hermes-Model

內置了感知提供商的解析功能（相同的模型名稱會根據你所在的提供商自動選擇正確的格式）。詳見 hermes_cli/model_switch.py。

關於 `--mode rpc` 的說明

Hermes 沒有 --mode rpc 標誌。上述三種協議已經涵蓋了各種用例——ACP 適用於 IDE 協議客戶端，TUI 網關適用於 stdio JSON-RPC 宿主，API 服務器適用於 HTTP。如果你發現它們都無法填補的實際空白，請針對你正在構建的具體消費者提交 issue。

ACP（Agent Client Protocol）​

TUI 網關 JSON-RPC​

方法目錄（精選）​

回傳的事件流​

Pi 風格 RPC 映射​

兼容 OpenAI 的 API 服務器​

我該使用哪一個？​

模型熱切換​

關於 --mode rpc 的說明​