ACP 编辑器集成

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

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

当你希望 Hermes 表现得像一个编辑器原生的编码 Agent，而非独立的 CLI 或消息机器人时，ACP 是理想选择。

Hermes 在 ACP 模式下暴露的内容

Hermes 以专为编辑器工作流设计的 hermes-acp 工具集运行，包括：

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

它有意排除了不适合编辑器 UX 的内容，例如消息投递和定时任务管理。

安装

正常安装 Hermes，然后添加 ACP 扩展：

pip install -e '.[acp]'

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

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

对于 Zed 注册表安装，Zed 通过官方 ACP 注册表条目启动 Hermes。该条目使用 uvx 分发，运行：

uvx --from 'hermes-agent[acp]==<version>' hermes-acp

在使用注册表安装路径之前，请确保 uv 在 PATH 中可用。

启动 ACP 服务器

以下任意命令均可以 ACP 模式启动 Hermes：

hermes acp

hermes-acp

python -m acp_adapter

Hermes 将日志输出到 stderr，以保持 stdout 专用于 ACP JSON-RPC 流量。

对于非交互式检查：

hermes acp --version
hermes acp --check

编辑器配置

VS Code

安装 ACP Client 扩展。

连接步骤：

1. 从活动栏打开 ACP Client 面板。
2. 从内置 Agent 列表中选择 Hermes Agent。
3. 连接并开始对话。

如果想手动定义 Hermes，可通过 VS Code 设置中的 acp.agents 添加：

{
  "acp.agents": {
    "Hermes Agent": {
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

Zed

Zed v0.221.x 及更高版本通过官方 ACP 注册表安装外部 Agent。

1. 打开 Agent 面板。
2. 点击添加 Agent，或运行 zed: acp registry 命令。
3. 搜索 Hermes Agent。
4. 安装它并启动一个新的 Hermes 外部 Agent 线程。

先决条件：

• 首先使用 hermes model 配置 Hermes 提供商凭证，或在 ~/.hermes/.env / ~/.hermes/config.yaml 中设置。
• 安装 uv，以便注册表启动器能够运行 uvx --from 'hermes-agent[acp]==<version>' hermes-acp。

在注册表条目可用之前进行本地开发时，请在 Zed 设置中使用自定义 Agent 服务器：

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

JetBrains

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

/path/to/hermes-agent/acp_registry

注册表清单

Hermes 官方 ACP 注册表元数据的源副本位于：

acp_registry/agent.json
acp_registry/icon.svg

上游注册表 PR 会将这些文件复制到 agentclientprotocol/registry 的顶层 hermes-agent/ 目录中。

注册表条目使用 uvx 分发，直接指向 hermes-agent PyPI 发布版本：

uvx --from 'hermes-agent[acp]==<version>' hermes-acp

注册表 CI 会验证固定版本在 PyPI 上存在，因此清单中的 version 和 uvx package 固定版本必须始终与 pyproject.toml 匹配。scripts/release.py 会自动保持它们同步。

配置与凭证

ACP 模式使用与 CLI 相同的 Hermes 配置：

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

提供商解析使用 Hermes 的正常运行时解析器，因此 ACP 会继承当前已配置的提供商（Provider）和凭证（Credentials）。Hermes 还提供了一个终端认证方法（--setup），用于首次运行注册表客户端；这会打开 Hermes 的交互式模型/提供商设置。

会话行为

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

每个会话存储以下内容：

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

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

工作目录行为

ACP 会话将编辑器的 cwd 绑定到 Hermes 的任务 ID，因此文件和终端工具相对于编辑器工作区运行，而非服务器进程的 cwd。

审批

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

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

超时或发生错误时，审批桥接器会拒绝请求。

故障排查

ACP Agent 未出现在编辑器中

检查：

• 在 Zed 中，使用 zed: acp registry 打开 ACP 注册表并搜索 Hermes Agent。
• 对于手动/本地开发，验证自定义 agent_servers 命令是否指向 hermes acp。
• Hermes 是否已安装且在 PATH 中。
• ACP 扩展是否已安装（pip install -e '.[acp]'）。
• 如果从官方 Zed 注册表条目启动，请确保已安装 uv。

ACP 启动后立即报错

尝试以下检查：

hermes acp --version
hermes acp --check
hermes doctor
hermes status

缺少凭证

ACP 模式使用 Hermes 现有的提供商配置。通过以下命令配置凭证：

hermes model

或直接编辑 ~/.hermes/.env。注册表客户端也可以触发 Hermes 的终端认证流程，这会运行相同的交互式提供商/模型设置。

Zed 注册表启动器无法找到 uv

从官方 uv 安装文档安装 uv，然后从 Zed 重试 Hermes Agent 线程。

另请参阅

• ACP 内部机制
• 提供商运行时解析
• 工具运行时