ACP 内部机制

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 agent 协议。

职责：

初始化 / 认证

新建/加载/恢复/fork/列出/取消会话方法

prompt（提示词）执行

会话模型切换

将同步 AIAgent 回调接入 ACP 异步通知

`SessionManager`

acp_adapter/session.py 跟踪活跃的 ACP 会话。

每个会话存储：

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 位于主事件循环，桥接使用：

权限桥接

acp_adapter/permissions.py 将危险终端审批 prompt 适配为 ACP 权限请求。

映射关系：

allow_once -> Hermes once

allow_always -> Hermes always

拒绝选项 -> Hermes deny

超时和桥接失败默认拒绝。

工具渲染辅助

acp_adapter/tools.py 将 Hermes 工具映射到 ACP 工具类型，并构建面向编辑器的内容。

示例：

patch / write_file -> 文件 diff

terminal -> shell 命令文本

read_file / search_files -> 文本预览

大型结果 -> 截断文本块（保障 UI 安全）

会话生命周期

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)：

设置会话取消事件

在可用时调用 agent.interrupt()

使 prompt 响应返回 stop_reason="cancelled"

Fork

fork_session() 将消息历史深拷贝至新的活跃会话，在保留对话状态的同时为 fork 分配独立的 session ID 和 cwd。

Provider/认证行为

ACP 不实现自己的认证存储。

而是复用 Hermes 的运行时解析器：

acp_adapter/auth.py

hermes_cli/runtime_provider.py

因此 ACP 通告并使用当前配置的 Hermes provider/凭据。它还始终通告一个终端 setup 认证方法（hermes-setup，参数 --setup），以便首次运行的 registry 客户端在启动正常 ACP 会话前可以打开 Hermes 的交互式模型/provider 配置。

工作目录绑定

ACP 会话携带编辑器 cwd。

会话管理器通过任务作用域的终端/文件覆盖将该 cwd 绑定到 ACP session ID，使文件和终端工具相对于编辑器工作区运行。

重复同名工具调用

事件桥接按工具名称以 FIFO 队列跟踪工具 ID，而非每个名称仅保留一个 ID。这对以下场景至关重要：

并行同名调用

单步内重复同名调用

若不使用 FIFO 队列，完成事件将附加到错误的工具调用上。

审批回调恢复

ACP 在 prompt 执行期间临时在终端工具上安装审批回调，执行完成后恢复之前的回调。这避免了将 ACP 会话特定的审批处理器永久全局安装。

当前限制

ACP 会话持久化至共享的 ~/.hermes/state.db（SessionDB），在进程重启后透明恢复；它们会出现在 session_search 中

非文本 prompt 块在请求文本提取时当前被忽略

编辑器特定的 UX 因 ACP 客户端实现而异

"ACP 内部机制"

ACP 内部机制

启动流程

主要组件

`HermesACPAgent`

`SessionManager`

事件桥接

权限桥接

工具渲染辅助

会话生命周期

取消

Fork

Provider/认证行为

工作目录绑定

重复同名工具调用

审批回调恢复

当前限制

相关文件

"ACP 内部机制"

ACP 内部机制#

启动流程#

主要组件#

HermesACPAgent#

SessionManager#

事件桥接#

权限桥接#

工具渲染辅助#

会话生命周期#

取消#

Fork#

Provider/认证行为#

工作目录绑定#

重复同名工具调用#

审批回调恢复#

当前限制#

相关文件#

ACP 内部机制

启动流程

主要组件

`HermesACPAgent`

`SessionManager`

事件桥接

权限桥接

工具渲染辅助

会话生命周期

取消

Fork

Provider/认证行为

工作目录绑定

重复同名工具调用

审批回调恢复

当前限制

相关文件