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。