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()
  -> load ~/.hermes/.env
  -> configure stderr logging
  -> construct HermesACPAgent
  -> acp.run_agent(agent)

标准输出保留用于 ACP JSON-RPC 传输。人类可读的日志会转到 stderr。

主要组件

`HermesACPAgent`

acp_adapter/server.py 实现 ACP 代理协议。

职责：

初始化/验证
新的/加载/恢复/分叉/列表/取消会话方法
提示执行
会话模型切换
将同步 AIAgent 回调连接到 ACP 异步通知中

`SessionManager`

acp_adapter/session.py 跟踪实时 ACP 会话。

每个会话存储：

session_id
agent
cwd
model
history
cancel_event

管理器是线程安全的并支持：

创造
得到
消除
叉
列表
清理
CWD更新

事件桥

acp_adapter/events.py 将 AIAgent 回调转换为 ACP session_update 事件。

桥接回调：

tool_progress_callback
thinking_callback
step_callback
message_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 安全

会话生命周期

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()
导致提示响应返回 stop_reason="cancelled"

分叉

fork_session() 将消息历史记录深度复制到新的实时会话中，保留对话状态，同时为分叉提供自己的会话 ID 和 cwd。

大模型提供商（provider）/身份验证行为

ACP 没有实现自己的身份验证存储。

相反，它重用了 Hermes 的运行时解析器：

acp_adapter/auth.py
hermes_cli/runtime_provider.py

因此，ACP 会通告并使用当前配置的 Hermes 大模型提供商（provider）/凭证。

工作目录绑定

ACP 会话带有编辑器 cwd。

会话管理器通过任务范围的终端/文件覆盖将该 cwd 绑定到 ACP 会话 ID，因此文件和终端工具相对于编辑器工作区进行操作。

重复的同名工具调用

事件桥跟踪每个工具名称的工具 ID FIFO，而不仅仅是每个名称一个 ID。这对于以下方面很重要：

并行同名通话
一步重复同名通话

如果没有 FIFO 队列，完成事件将附加到错误的工具调用。

审批回调恢复

ACP 在提示执行期间临时在终端工具上安装批准回调，然后恢复之前的回调。这可以避免永久在全局安装特定于 ACP 会话的批准处理程序。

目前的限制

从 ACP 服务器的角度来看，ACP 会话是进程本地的
当前在请求文本提取中忽略非文本提示块
特定于编辑器的用户体验因 ACP 客户端实现而异

启动流程​

主要组件​

HermesACPAgent​

SessionManager​

事件桥​

权限桥​

工具渲染助手​

会话生命周期​

取消​

分叉​

大模型提供商（provider）/身份验证行为​

工作目录绑定​

重复的同名工具调用​

审批回调恢复​

目前的限制​

相关文件​