Перейти к основному содержимому

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

ACP-адаптер оборачивает синхронный AIAgent из VibeOS в асинхронный 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

Процесс запуска​

vibeos acp / vibeos-acp / python -m acp_adapter
  -> acp_adapter.entry.main()
  -> парсинг --version / --check / --setup до запуска сервера
  -> загрузка ~/.vibeos/.env
  -> настройка stderr-логирования
  -> создание VibeOSACPAgent
  -> acp.run_agent(agent, use_unstable_protocol=True)

Путь через реестр Zed ACP запускает тот же адаптер с помощью uvx --from 'vibeos-agent[acp]==<version>' vibeos-acp, указывая на PyPI-релиз vibeos-agent.

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

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

VibeosACPAgent​

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 (в настоящее время установлен в None в ACP-мосте — рассуждения передаются через step_callback)
  • step_callback

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

asyncio.run_coroutine_threadsafe(...)

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

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

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

  • allow_once -> VibeOS once
  • allow_always -> VibeOS always
  • варианты отклонения -> VibeOS deny

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

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

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

Примеры:

  • patch / write_file -> файловые diff'ы
  • terminal -> текст команды оболочки
  • read_file / search_files -> текстовые превью
  • большие результаты -> усечённые текстовые блоки для безопасности интерфейса

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

new_session(cwd)
  -> создание SessionState
  -> создание AIAgent(platform="acp", enabled_toolsets=["vibeos-acp"])
  -> привязка task_id/session_id к переопределению cwd

prompt(..., session_id)
  -> извлечение текста из ACP-блоков контента
  -> сброс события отмены
  -> установка колбэков + моста разрешений
  -> запуск AIAgent в ThreadPoolExecutor
  -> обновление истории сессии
  -> отправка финального фрагмента сообщения агента

Отмена​

cancel(session_id):

  • устанавливает событие отмены сессии
  • вызывает agent.interrupt() при доступности
  • приводит к возврату stop_reason="cancelled" в ответе на промпт

Форкинг​

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

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

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

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

  • acp_adapter/auth.py
  • vibeos_cli/runtime_provider.py

Таким образом, ACP рекламирует и использует текущего настроенного провайдера/учётные данные VibeOS. Он также всегда рекламирует метод аутентификации настройки терминала (vibeos-setup, аргументы --setup), чтобы клиенты реестра при первом запуске могли открыть интерактивную конфигурацию модели/провайдера VibeOS перед началом обычной ACP-сессии.

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

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

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

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

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

  • параллельных вызовов с одинаковыми именами
  • повторяющихся вызовов с одинаковыми именами в одном шаге

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

Восстановление колбэка разрешений​

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

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

  • ACP-сессии сохраняются в общую базу данных ~/.vibeos/state.db (SessionDB) и прозрачно восстанавливаются после перезапуска процесса; они отображаются в session_search
  • нетекстовые блоки промптов в настоящее время игнорируются при извлечении текста запроса
  • UX, специфичный для редактора, различается в зависимости от реализации ACP-клиента

Связанные файлы​

  • tests/acp/ — тестовый набор ACP
  • toolsets.py — определение набора инструментов vibeos-acp
  • vibeos_cli/main.py — подкоманда CLI vibeos acp
  • pyproject.toml — опциональная зависимость [acp] + скрипт vibeos-acp