Skip to main content

ACP 编辑器集成

Hermes Agent 可以作为 ACP 服务器运行，使兼容 ACP 的编辑器能够通过标准输入/输出（stdio）与 Hermes 通信，并渲染以下内容：

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

如果你希望 Hermes 更像编辑器内原生的代码助手，而不是独立的 CLI 或消息机器人，那么 ACP 会是很合适的接入方式。

Hermes 在 ACP 模式下提供的能力​

Hermes 在 ACP 模式下运行时，会启用一套专门为编辑器工作流设计的精简工具集，包括：

  • 文件工具：read_file、write_file、patch、search_files
  • 终端工具：terminal、process
  • 网络/浏览器工具
  • 记忆、待办事项、会话搜索
  • 技能（skills）
  • execute_code 和 delegate_task
  • 视觉理解（vision）

它有意排除了不适合典型编辑器用户体验的功能，例如消息发送和定时任务管理。

安装​

正常安装 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

提供商解析沿用 Hermes 的常规运行时逻辑，因此 ACP 会继承当前已经配置好的提供商及其凭证。

会话行为​

ACP 会话由 ACP 适配器的内存中会话管理器跟踪，仅在服务器运行期间有效。

每个会话存储以下信息：

  • 会话 ID
  • 工作目录
  • 选定的模型
  • 当前对话历史
  • 取消事件

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

工作目录行为​

ACP 会话会把编辑器的工作目录（cwd）绑定到 Hermes 的任务上下文中，因此文件工具和终端工具都会相对于编辑器工作区执行，而不是相对于 ACP 服务器进程本身的当前目录。

审批机制​

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

  • 仅允许一次
  • 始终允许
  • 拒绝

若超时或出错，审批桥接将拒绝该请求。

故障排查​

编辑器中未显示 ACP 代理​

请检查：

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

ACP 启动后立即报错​

尝试以下检查：

hermes doctor
hermes status
hermes acp

凭证缺失​

ACP 模式没有单独的登录流程，它直接复用 Hermes 已有的提供商配置。你可以通过下面的方式配置凭据：

hermes model

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

参考资料​