ACP 協議

源码版本v2026.7.20

職責

ACP(Agent Client Protocol)是編輯器/IDE 與 agent 通訊的標準協議。acp_adapter/ 把 Hermes 暴露為 ACP server,讓支援 ACP 的客戶端(Zed、VS Code 擴充功能等)能直接驅動 Hermes:管理會話、讀寫資源(檔案/圖片)、審批編輯、追溯來源(provenance)、按權限隔離工具。這讓 Hermes 不止於訊息平台,也能嵌入開發工作流。

關鍵檔案

• server.py 頭部:1-92 — "ACP agent server — exposes Hermes Agent via the Agent Client Protocol"
• 資源處理:96-150 — _MAX_ACP_RESOURCE_BYTES、_resource_display_name、_is_text_resource / _is_image_resource
• 資源文字/圖片轉換:201-296 — _format_resource_text / _resource_link_to_parts / _image_data_url(資源→OpenAI content parts)
• SessionState / SessionManager:159-175 — ACP 會話狀態與管理
• cwd 翻譯:29-62 — _translate_acp_cwd / _normalize_cwd_for_compare(編輯器工作目錄對齊)
• toolsets 展開:129-159 — _expand_acp_enabled_toolsets
• class EditProposal:26-51 — 編輯提案(寫檔案 / patch)
• build_edit_proposal:178-220 — 從工具呼叫建構提案(write_file / patch_replace / patch_v4a)
• 審批請求器:51-69 — set_edit_approval_requester / token 機制
• permissions.py — 工具權限隔離
• provenance:22-111 — build_session_provenance / session_provenance_meta(操作來源追溯)
• auth.py / entry.py / events.py
• __main__.py — ACP server 啟動入口(5 行)
• acp_registry/agent.json — agent 元資料清單(供客戶端發現)
• acp_registry/icon.svg — 圖示

資料流

1. ACP 客戶端(編輯器)按 acp_registry/agent.json 發現並啟動 Hermes ACP server(acp_adapter/__main__.py)。
2. 客戶端發起會話 → SessionManager:175 建立 SessionState,對齊 cwd(acp_adapter/session.py:29)、展開 toolsets(acp_adapter/session.py:129)。
3. 客戶端發訊息/資源 → 資源轉換:201 把 ACP resource(檔案/圖片,受 acp_adapter/server.py:96 大小限制)轉成 OpenAI content parts,餵給 run_conversation:588。
4. agent 想改檔案時,工具呼叫經 build_edit_proposal:178 變成 EditProposal,經審批請求器(acp_adapter/edit_approval.py:51)彈給使用者確認。
5. 工具執行受 acp_adapter/permissions.py 權限管控;每次操作經 acp_adapter/provenance.py:22 記 provenance。
6. 串流輸出與事件(acp_adapter/events.py)回傳客戶端。

小結

ACP 讓 Hermes 嵌入編輯器工作流:會話管理、資源讀寫、編輯審批、權限隔離、來源追溯。核心是 server.py(協議適配)+ session.py(會話)+ edit_approval.py(人審編輯)。和網關層互補——網關接訊息平台,ACP 接 IDE。