🏠 Главная › Документация › Разработчикам

Внутреннее устройство ACP

Адаптер ACP оборачивает синхронный AIAgent Hermes в асинхронный JSON-RPC stdio-сервер.

Ключевые файлы реализации:

Процесс загрузки

hermes acp / hermes-acp / python -m acp_adapter
  -> acp_adapter.entry.main()
  -> load ~/.hermes/.env
  -> configure stderr logging
  -> construct HermesACPAgent
  -> acp.run_agent(agent, use_unstable_protocol=True)

Stdout зарезервирован для ACP JSON-RPC транспорта. Человекочитаемые логи направляются в stderr.

Основные компоненты

HermesACPAgent

acp_adapter/server.py реализует протокол ACP-агента.

Обязанности:

SessionManager

acp_adapter/session.py отслеживает активные ACP-сессии.

Каждая сессия хранит:

Менеджер потокобезопасен и поддерживает:

Мост событий

acp_adapter/events.py преобразует колбэки AIAgent в события ACP session_update.

Проксируемые колбэки:

Поскольку AIAgent выполняется в рабочем потоке, а ACP I/O работает в главном цикле событий, мост использует:

asyncio.run_coroutine_threadsafe(...)

Мост разрешений

acp_adapter/permissions.py адаптирует опасные запросы подтверждения терминала в запросы разрешений ACP.

Соответствие:

Таймауты и ошибки моста по умолчанию отклоняют запрос.

Вспомогательные функции рендеринга инструментов

acp_adapter/tools.py сопоставляет инструменты Hermes с видами инструментов ACP и формирует контент для редактора.

Примеры:

Жизненный цикл сессии

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

Форк

fork_session() делает глубокую копию истории сообщений в новую активную сессию, сохраняя состояние разговора и присваивая форку собственный ID сессии и cwd.

Поведение провайдера/аутентификации

ACP не реализует собственное хранилище аутентификации.

Вместо этого он использует рантайм-резолвер Hermes:

Таким образом, ACP использует текущий настроенный провайдер/учётные данные Hermes.

Привязка рабочей директории

ACP-сессии содержат cwd редактора.

Менеджер сессий привязывает этот cwd к ID ACP-сессии через переопределения терминала/файлов в рамках задачи, поэтому инструменты терминала и файлов работают относительно рабочей области редактора.

Дублирующиеся вызовы инструментов с одинаковыми именами

Мост событий отслеживает ID инструментов в порядке FIFO для каждого имени инструмента, а не только один ID на имя. Это важно для:

Без очередей FIFO события завершения привязывались бы к неверному вызову инструмента.

Восстановление колбэка подтверждения

ACP временно устанавливает колбэк подтверждения на инструменте терминала во время выполнения prompt, а затем восстанавливает предыдущий колбэк. Это предотвращает бессрочную глобальную установку обработчиков подтверждения, специфичных для ACP-сессии.

Текущие ограничения