程序化集成
Hermes 提供了三种协议，用于从外部程序驱动代理——IDE 插件、自定义 UI、CI 流水线、嵌入式子代理。选择与您的传输层和消费者相匹配的协议。
| 协议 | 传输层 | 最适合 | 定义位置 |
|---|---|---|---|
| ACP | 基于 stdio 的 JSON-RPC | 已支持代理客户端协议的 IDE 客户端（VS Code、Zed、JetBrains） | acp_adapter/ |
| TUI 网关 | 基于 stdio（或 WebSocket）的 JSON-RPC | 想要细粒度控制会话、斜杠命令、审批和流式事件的自定义宿主 | tui_gateway/server.py |
| API 服务器 | HTTP + Server-Sent Events | 兼容 OpenAI 的前端（Open WebUI、LobeChat、LibreChat…）和语言无关的 Web 客户端 | gateway/platforms/api_server.py |
三者都驱动相同的 AIAgent 核心。它们仅在传输格式和暴露的功能集上有所不同。
ACP（代理客户端协议）
hermes acp 启动一个基于 stdio 的 JSON-RPC 服务器，支持 ACP 协议。在生产环境中被 VS Code（Zed Industries 的 ACP 扩展）、Zed 和任何带有 ACP 插件的 JetBrains IDE 使用。
暴露的能力：会话创建、提示词提交、流式代理消息块、工具调用事件、权限请求、会话分支、取消和认证。工具输出被渲染为 IDE 能理解的 ACP Diff/ToolCall 内容块。
完整的生命周期、事件桥接和审批流程：ACP 内部。
hermes acp # 在 stdio 上提供 ACP 服务
hermes acp --bootstrap # 打印支持 ACP 的 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.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
流式事件返回
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 | 通过 command.dispatch 执行 /model <provider:model>（会话中，持久化） |
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（通过 SSE 流式传输）
POST /v1/responses OpenAI Responses API（有状态）
POST /v1/runs 启动运行，返回 run_id（202）
GET /v1/runs/{id} 运行状态
GET /v1/runs/{id}/events 生命周期事件的 SSE 流
POST /v1/runs/{id}/approval 解决待处理的审批
POST /v1/runs/{id}/stop 中断运行
GET /v1/capabilities 机器可读的功能标志
GET /v1/models 列出 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，说明您正在构建的具体消费者。