编程式集成

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 的说明​