acp internals — The Hermes Bible

ACP 適配器將 Hermes 的同步 AIAgent 封裝在一個非同步的 JSON-RPC stdio 伺服器中。

主要實作檔案：

acp_adapter/entry.py
acp_adapter/server.py
acp_adapter/session.py
acp_adapter/events.py
acp_adapter/permissions.py
acp_adapter/tools.py
acp_adapter/auth.py
acp_registry/agent.json

啟動流程

hermes acp / hermes-acp / python -m acp_adapter
  -> acp_adapter.entry.main()
  -> parse --version / --check / --setup before server startup
  -> load ~/.hermes/.env
  -> configure stderr logging
  -> construct HermesACPAgent
  -> acp.run_agent(agent, use_unstable_protocol=True)

Zed ACP Registry 路徑透過 uvx --from 'hermes-agent[acp]==<version>' hermes-acp 啟動相同的適配器，指向 hermes-agent PyPI 發佈版。

Stdout 保留給 ACP JSON-RPC 傳輸使用。人類可讀的日誌訊息會輸出到 stderr。

主要元件

`HermesACPAgent`

acp_adapter/server.py 實作了 ACP 代理程式協定。

職責：

初始化 / 認證
新建/載入/恢復/分支/列出/取消 session 方法
提示詞執行
Session 模型切換
將同步 AIAgent 回呼函式橋接到 ACP 非同步通知

`SessionManager`

acp_adapter/session.py 追蹤活躍的 ACP session。

每個 session 儲存：

session_id
agent
cwd
model
history
cancel_event

管理器是執行緒安全的，支援：

create（建立）
get（取得）
remove（移除）
fork（分支）
list（列出）
cleanup（清理）
cwd 更新

事件橋接器

acp_adapter/events.py 將 AIAgent 回呼函式轉換為 ACP session_update 事件。

橋接的回呼函式：

tool_progress_callback
thinking_callback（在 ACP 橋接器中目前設為 None — 推理結果透過 step_callback 轉發）
step_callback

因為 AIAgent 在工作者執行緒中運行，而 ACP I/O 在主事件迴圈上運行，所以橋接器使用：

asyncio.run_coroutine_threadsafe(...)

權限橋接器

acp_adapter/permissions.py 將危險的終端機核准提示轉換為 ACP 權限請求。

對應關係：

allow_once -> Hermes once
allow_always -> Hermes always
拒絕選項 -> Hermes deny

逾時和橋接失敗時預設為拒絕。

工具渲染輔助函式

acp_adapter/tools.py 將 Hermes 工具對應到 ACP 工具類型，並建構編輯器端的內容。

範例：

patch / write_file -> 檔案差異
terminal -> shell 命令文字
read_file / search_files -> 文字預覽
大型結果 -> 為了 UI 安全性而截斷的文字區塊

Session 生命週期

new_session(cwd)
  -> create SessionState
  -> create AIAgent(platform="acp", enabled_toolsets=["hermes-acp"])
  -> bind task_id/session_id to cwd override

prompt(..., session_id)
  -> extract text from ACP content blocks
  -> reset cancel event
  -> install callbacks + approval bridge
  -> run AIAgent in ThreadPoolExecutor
  -> update session history
  -> emit final agent message chunk

取消操作

cancel(session_id)：

設定 session 取消事件
在可用時呼叫 agent.interrupt()
導致提示詞回應返回 stop_reason="cancelled"

分支操作

fork_session() 將訊息歷史深度複製到一個新的活躍 session 中，在保留對話狀態的同時，為分支賦予自己的 session ID 和 cwd。

Provider/認證行為

ACP 不實作自己的認證儲存。

它改為複用 Hermes 的執行階段解析器：

acp_adapter/auth.py
hermes_cli/runtime_provider.py

因此 ACP 會宣告並使用目前設定的 Hermes provider/認證資訊。它還始終宣告一個終端機設定認證方法（hermes-setup，參數 --setup），以便首次執行的 registry 客戶端可以在開始正常 ACP session 之前開啟 Hermes 的互動式模型/ provider 配置介面。

工作目錄綁定

ACP session 攜帶一個編輯器 cwd。

Session 管理器透過任務範圍的終端機/檔案覆寫將該 cwd 綁定到 ACP session ID，使檔案和終端機工具相對於編輯器工作區進行操作。

重複同名工具呼叫

事件橋接器追蹤每個工具名稱的 FIFO 工具 ID 佇列，而不僅僅是一個名稱對應一個 ID。這對於以下情況很重要：

並行的同名呼叫
在一個步驟中重複的同名呼叫

如果沒有 FIFO 佇列，完成事件會附加到錯誤的工具呼叫上。

核准回呼函式還原

ACP 在提示詞執行期間暫時安裝一個核准回呼函式到終端機工具上，執行後恢復之前的回呼函式。這樣可以避免 ACP session 特定的核准處理器永遠留在全域範圍中。

目前的限制

ACP session 會持久化到共用的 ~/.hermes/state.db（SessionDB），並在程式重新啟動時透明地還原；它們會出現在 session_search 中
非文字提示詞區塊目前在請求文字擷取時會被忽略
編輯器特定的使用者體驗因 ACP 客戶端實作而異