H繁中版
文件核心功能acp
<!-- Source: https://hermesbible.com/docs/user-guide/features/acp -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/acp

Hermes Agent 可以作為 ACP 伺服器運行，讓相容 ACP 的編輯器透過 stdio 與 Hermes 通訊，並呈現：

  • 聊天訊息
  • 工具活動
  • 檔案差異
  • 終端機指令
  • 審核提示
  • 串流思考 / 回應片段

當你希望 Hermes 以編輯器原生的 coding agent 方式運作，而非獨立的 CLI 或訊息機器人時，ACP 是一個很好的選擇。

Hermes 在 ACP 模式下暴露的功能

Hermes 使用專為編輯器工作流程設計的 hermes-acp 工具集運行，包含：

  • 檔案工具：read_file、write_file、patch、search_files
  • 終端機工具：terminal、process
  • 網頁 / 瀏覽器工具
  • 記憶體、todo、session 搜尋
  • 技能
  • execute_code 和 delegate_task
  • 視覺

它刻意排除了不適合典型編輯器 UX 的功能，例如訊息投遞和 cronjob 管理。

安裝

正常安裝 Hermes，然後加入 ACP 額外依賴：

pip install -e '.[acp]'

這會安裝 agent-client-protocol 依賴並啟用：

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

對於 Zed registry 安裝，Zed 透過官方 ACP Registry 項目啟動 Hermes。該項目使用 uvx 發行方式執行：

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

在使用 registry 安裝路徑之前，請確保 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

瀏覽器工具（選用）

瀏覽器工具（browser_navigate、browser_click 等）依賴 agent-browser npm 套件和 Chromium，這些不包含在 Python wheel 中。請透過以下指令安裝：

hermes acp --setup-browser           # 互動式（下載前約 400 MB 會先提示確認）
hermes acp --setup-browser --yes     # 非互動式接受下載

這是獨立指令。Zed registry 的 terminal-auth 流程（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. 從活動列開啟 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 external-agent 討論串。

先決條件：

  • 先使用 hermes model 設定 Hermes provider 憑證，或在 ~/.hermes/.env / ~/.hermes/config.yaml 中設定。
  • 安裝 uv，使 registry 啟動器能執行 uvx --from 'hermes-agent[acp]==<version>' hermes-acp。

在 registry 項目尚未上線前的本地開發，可在 Zed 設定中使用自訂代理伺服器：

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

JetBrains

使用相容 ACP 的插件，並將其指向：

/path/to/hermes-agent/acp_registry

Registry 設定檔

Hermes 官方 ACP Registry 元資料的原始副本位於：

acp_registry/agent.json
acp_registry/icon.svg

上游 registry PR 會將這些檔案複製至 agentclientprotocol/registry 中的頂層 hermes-agent/ 目錄。

Registry 項目使用 uvx 發行方式，直接指向 hermes-agent PyPI 發佈版：

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

Registry CI 會驗證鎖定版本是否存在於 PyPI，因此 manifest 的 version 和 uvx package 鎖定必須與 pyproject.toml 保持一致。scripts/release.py 會自動保持它們同步。

設定與憑證

ACP 模式使用與 CLI 相同的 Hermes 設定：

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

Provider 解析使用 Hermes 一般運行時解析器，因此 ACP 繼承目前設定的 provider 和憑證。Hermes 也提供 terminal auth 方法（--setup）給首次運行的 registry 用戶端；這會開啟 Hermes 的互動式模型 / provider 設定。

Session 行為

ACP session 由 ACP 適配器的記憶體內 session 管理器在伺服器運行期間追蹤。

每個 session 儲存：

  • session ID
  • 工作目錄
  • 選擇的模型
  • 當前對話歷史
  • 取消事件

底層的 AIAgent 仍使用 Hermes 一般的持久化 / 日誌路徑，但 ACP 的 list/load/resume/fork 僅限於當前運行的 ACP 伺服器程序範圍。

工作目錄行為

ACP session 將編輯器的 cwd 綁定至 Hermes task ID，使檔案和終端機工具相對於編輯器工作區執行，而非伺服器程序的 cwd。

審核

危險的終端機指令可作為審核提示回傳至編輯器。ACP 審核選項比 CLI 流程更簡潔：

  • 允許一次
  • 永久允許
  • 拒絕

逾時或錯誤時，審核橋接器會拒絕請求。

Session 範圍的編輯自動審核

ACP 在 允許一次 和 永久允許 之間提供第三個層級：允許本次 Session。從編輯器的權限提示中選擇它，會將審核僅記錄於當前 ACP session — 該 session 中所有後續相符的指令都會直接執行，不會再提示。但新的 ACP session（或重新啟動編輯器）會重置狀態，並在首次操作時重新提示。

選項編輯器標籤範圍跨重啟持久化
allow_once允許一次僅此次工具呼叫否
allow_session允許本次 Session此 ACP session 中所有相符的呼叫否 — session 結束時清除
allow_always永久允許所有未來的 session是（寫入 Hermes 永久允許清單）
deny拒絕僅此次工具呼叫否

allow_session 適合作為編輯器工作流程的預設選項 — 當你在某個任務期間信任代理，但不想授予長期允許清單條目時使用。安全性權衡很直接：範圍越廣，編輯器越少打斷你，但行為異常的代理（或 prompt injection）在你察覺之前可能造成的損害也越大。對不熟悉的指令先使用 allow_once；當你看到代理正確執行相同模式幾次後，再提升為 allow_session；將 allow_always 保留給你永遠信任的真正冪等指令（例如 git status）。

ACP 橋接器將這些選項映射至 Hermes 內部的審核語意 — allow_always 以與 CLI 相同的方式寫入永久允許清單條目，而 allow_session 僅影響當前 ACP session 的程序內審核快取。

疑難排解

ACP 代理未出現在編輯器中

請檢查：

  • 在 Zed 中，使用 zed: acp registry 開啟 ACP Registry 並搜尋 Hermes Agent。
  • 若為手動 / 本地開發，確認自訂 agent_servers 指令指向 hermes acp。
  • Hermes 已安裝且在你的 PATH 中。
  • ACP 額外依賴已安裝（pip install -e '.[acp]'）。
  • 若從官方 Zed registry 項目啟動，需安裝 uv。

ACP 啟動後立即報錯

嘗試以下檢查：

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

缺少憑證

ACP 模式使用 Hermes 現有的 provider 設定。使用以下指令設定憑證：

hermes model

或直接編輯 ~/.hermes/.env。Registry 用戶端也可觸發 Hermes 的 terminal auth 流程，該流程執行相同的互動式 provider / 模型設定。

Zed registry 啟動器找不到 uv

從官方 uv 安裝文件安裝 uv，然後在 Zed 中重試 Hermes Agent 討論串。

另請參閱

API Server

api server