hermes教程-ACP 编辑器集成

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

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

当你希望 Hermes 表现得像一个原生编辑器编码助手，而非独立的 CLI 或消息机器人时，ACP 非常适用。

Hermes 在 ACP 模式下暴露的功能

Hermes 运行时会加载一套专为编辑器工作流设计的精选 hermes-acp 工具集，包括：

• 文件工具：read_file、write_file、patch、search_files
• 终端工具：terminal、process
• 网页/浏览器工具
• memory、todo、session search
• skills
• execute_code 和 delegate_task
• vision

它有意排除了不适合典型编辑器用户体验的功能，例如 messaging delivery 和 cronjob management。

安装

正常安装 Hermes，然后添加 ACP 额外依赖：

pip install -e '.[acp]'

这会安装 agent-client-protocol 依赖，并启用以下命令：

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

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

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

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

启动 ACP 服务器

以下任一命令均可将 Hermes 启动为 ACP 模式：

hermes acp

hermes-acp

python -m acp_adapter

Hermes 将日志输出到 stderr，因此 stdout 仍保留给 ACP JSON-RPC 流量使用。

用于非交互式检查：

hermes acp --version
hermes acp --check

浏览器工具（可选）

浏览器工具（browser_navigate、browser_click 等）依赖 agent-browser npm 包和 Chromium，它们不包含在 Python wheel 中。可通过以下命令安装：

hermes acp --setup-browser           # 交互式（在下载约 400 MB 前会提示）
hermes acp --setup-browser --yes     # 非交互式接受下载

这是一个独立命令。Zed 注册表的终端认证流程（hermes acp --setup）也会在模型选择后提供浏览器引导作为后续问题，因此大多数用户无需直接运行 --setup-browser。

它的作用如下：

• 如果缺失，将 Node.js 22 LTS 安装到 ~/.hermes/node/
• 在该前缀下执行 npm install -g agent-browser @askjo/camofox-browser（无需 sudo —— npm 的 --prefix 指向用户可写的 Hermes 托管 Node）
• 安装 Playwright Chromium，或在检测到系统已安装 Chrome/Chromium 时使用现有版本

该引导过程是幂等的 —— 重复执行会很快跳过已完成的工作。

编辑器设置

VS Code

安装 ACP Client 扩展。

连接步骤：

1. 从 Activity Bar 打开 ACP Client 面板。
2. 在内置助手列表中选择 Hermes Agent。
3. 连接并开始对话。

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

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

Zed

Zed v0.221.x 及更新版本通过官方 ACP Registry 安装外部助手。

1. 打开 Agent Panel。
2. 点击 Add Agent，或运行 zed: acp registry 命令。
3. 搜索 Hermes Agent。
4. 安装并新建一个 Hermes 外部助手线程。

前置条件：

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

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

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

JetBrains

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

注册表清单

Hermes 官方 ACP Registry 元数据的源文件位于：

acp_registry/agent.json
acp_registry/icon.svg

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

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

注册表 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 会继承当前配置的提供商和凭证。Hermes 还为首次运行的注册表客户端提供终端认证方式（--setup）；这会打开 Hermes 的交互式模型/提供商设置。

会话行为

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

每个会话存储：

• session ID
• working directory
• selected model
• current conversation history
• cancel event

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

工作目录行为

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

审批

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

• allow once
• allow always
• deny

在超时或出错时，审批桥会拒绝请求。

会话范围的编辑自动审批

ACP 在 allow once 和 allow always 之间提供了第三层选项：Allow for session。从编辑器的权限提示中选择它时，仅将审批记录在当前 ACP 会话中 —— 该会话中后续所有匹配的命令都将直接通过，无需提示，但新的 ACP 会话（或重启编辑器）会重置记录，并在首次出现时重新提示。

allow_session 是编辑器工作流的合适默认值：你信任助手在完成某项任务期间的操作，但不想授予长期有效的白名单条目。安全权衡很直接：范围越广，编辑器打断你的次数越少，但行为异常的助手（或提示注入）在你察觉之前能造成的损害也越大。对不熟悉的命令先使用 allow_once；在观察到助手多次正确执行相同模式后，再提升到 allow_session；仅对真正幂等且永远信任的命令（例如 git status）保留 allow_always。

ACP 桥将这些选项映射到 Hermes 内部审批语义 —— allow_always 会像 CLI 一样写入永久白名单条目，而 allow_session 仅影响当前 ACP 会话的进程内审批缓存。

故障排查

ACP 助手未在编辑器中显示

请检查：

• 在 Zed 中，通过 zed: acp registry 打开 ACP Registry 并搜索 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 Internals
• Provider Runtime Resolution
• Tools Runtime