跳到主要内容

ACP 编辑器集成

Hermes Agent 可以作为 ACP 服务器运行，让兼容 ACP 的编辑器通过 stdio 与 Hermes 通信，并渲染：

  • 聊天消息
  • 工具活动
  • 文件 diff
  • 终端命令
  • 审批提示
  • 流式思考 / 响应片段

如果你希望 Hermes 更像一个原生集成在编辑器中的编码智能体，而不是独立 CLI 或消息机器人，ACP 会是一个很合适的接入方式。

Hermes 在 ACP 模式下暴露什么​

Hermes 会使用一个专门为编辑器工作流整理过的 hermes-acp 工具集，其中包括：

  • 文件工具：read_file、write_file、patch、search_files
  • 终端工具：terminal、process
  • Web / 浏览器工具
  • memory、todo、session search
  • 技能
  • execute_code 和 delegate_task
  • 视觉能力

它会有意排除不适合典型编辑器交互体验的内容，例如消息投递和 cronjob 管理。

安装​

正常安装 Hermes 后，再安装 ACP 扩展依赖：

pip install -e '.[acp]'

这会安装 agent-client-protocol 依赖，并启用：

  • hermes acp
  • hermes-acp
  • python -m acp_adapter

启动 ACP 服务器​

以下任一命令都可以让 Hermes 以 ACP 模式启动：

hermes acp
hermes-acp
python -m acp_adapter

Hermes 会把日志写到 stderr，从而保证 stdout 只用于 ACP JSON-RPC 流量。

编辑器配置​

VS Code​

安装 ACP 客户端扩展，然后将其指向仓库中的 acp_registry/ 目录。

示例设置：

{
  "acpClient.agents": [
    {
      "name": "hermes-agent",
      "registryDir": "/path/to/hermes-agent/acp_registry"
    }
  ]
}

Zed​

示例设置：

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"],
    },
  },
}

JetBrains​

使用兼容 ACP 的插件，并将其指向：

/path/to/hermes-agent/acp_registry

注册清单​

ACP 注册清单位于：

acp_registry/agent.json

它声明了一个基于命令启动的智能体，其启动命令为：

hermes acp

配置与凭据​

ACP 模式与 CLI 共用同一套 Hermes 配置：

  • ~/.hermes/.env
  • ~/.hermes/config.yaml
  • ~/.hermes/skills/
  • ~/.hermes/state.db

大模型提供商（provider）解析沿用 Hermes 常规运行时解析器，因此 ACP 会继承当前已配置的大模型提供商（provider）和凭据。

会话行为​

ACP 会话由 ACP adapter 在服务器运行期间通过内存中的会话管理器进行跟踪。

每个会话会保存：

  • session ID
  • 工作目录
  • 选中的模型
  • 当前对话历史
  • cancel event

底层 AIAgent 仍会使用 Hermes 常规的持久化与日志路径，但 ACP 的 list/load/resume/fork 范围仅限于当前运行中的 ACP 服务器进程。

工作目录行为​

ACP 会话会把编辑器的 cwd 绑定到 Hermes 的 task ID，这样文件工具和终端工具都是相对于编辑器工作区运行，而不是相对于 ACP 服务器进程本身的 cwd。

审批​

危险的终端命令可以回传给编辑器作为审批提示。ACP 的审批选项比 CLI 更简单：

  • allow once
  • allow always
  • deny

如果超时或发生错误，审批桥接会默认拒绝该请求。

故障排查​

编辑器里看不到 ACP 智能体​

请检查：

  • 编辑器是否指向了正确的 acp_registry/ 路径
  • Hermes 是否已安装并在 PATH 中
  • ACP 扩展依赖是否已安装（pip install -e '.[acp]'）

ACP 启动后立刻报错​

可以先做这些检查：

hermes doctor
hermes status
hermes acp

缺少凭据​

ACP 模式没有自己独立的登录流程。它直接使用 Hermes 已有的大模型提供商（provider）配置。你可以通过下面方式配置凭据：

hermes model

或直接编辑 ~/.hermes/.env。

另见​