Интеграция с ACP-редакторами

VibeOS может работать как ACP-сервер, позволяя ACP-совместимым редакторам взаимодействовать с VibeOS через stdio и отображать:

• сообщения чата
• активность инструментов
• различия в файлах
• терминальные команды
• запросы на подтверждение
• потоковые фрагменты размышлений/ответов

ACP хорошо подходит, когда вы хотите, чтобы VibeOS вел себя как встроенный в редактор агент кодирования, а не как отдельный CLI или чат-бот.

Что VibeOS предоставляет в режиме ACP

VibeOS запускается с подобранным набором инструментов vibeos-acp, предназначенным для рабочих процессов в редакторе. Он включает:

• файловые инструменты: read_file, write_file, patch, search_files
• терминальные инструменты: terminal, process
• веб/браузерные инструменты
• память, список задач, поиск по сессиям
• навыки
• execute_code и delegate_task
• зрение

Он намеренно исключает то, что не вписывается в типичный пользовательский опыт редактора, например, доставку сообщений и управление cron-задачами.

Установка

Установите VibeOS обычным способом, затем добавьте ACP-дополнение:

pip install -e '.[acp]'

Это установит зависимость agent-client-protocol и включит:

• vibeos acp
• vibeos-acp
• python -m acp_adapter

Для установок через реестр Zed, Zed запускает VibeOS через официальную запись в реестре ACP. Эта запись использует дистрибутив uvx, который выполняет:

uvx --from 'vibeos-agent[acp]==<version>' vibeos-acp

Убедитесь, что uv доступен в PATH перед использованием пути установки через реестр.

Запуск ACP-сервера

Любая из следующих команд запускает VibeOS в режиме ACP:

vibeos acp

vibeos-acp

python -m acp_adapter

VibeOS пишет логи в stderr, поэтому stdout остается зарезервированным для ACP JSON-RPC трафика.

Для неинтерактивных проверок:

vibeos acp --version
vibeos acp --check

Браузерные инструменты (опционально)

Браузерные инструменты (browser_navigate, browser_click и т.д.) зависят от npm-пакета agent-browser и Chromium, которые не входят в состав Python-пакета. Установите их с помощью:

vibeos acp --setup-browser           # интерактивно (запрашивает подтверждение перед загрузкой ~400 МБ)
vibeos acp --setup-browser --yes     # принять загрузку без интерактивного запроса

Это отдельная команда. Поток терминальной аутентификации реестра Zed (vibeos acp --setup) также предлагает настройку браузера в качестве дополнительного вопроса после выбора модели, поэтому большинству пользователей никогда не придется запускать --setup-browser напрямую.

Что она делает:

• Устанавливает Node.js 22 LTS в ~/.vibeos/node/, если отсутствует
• Выполняет npm install -g agent-browser @askjo/camofox-browser в этот префикс (не требуется sudo — npm с --prefix указывает на управляемый VibeOS каталог Node, доступный для записи пользователем)
• Устанавливает Playwright Chromium или использует обнаруженный системный Chrome/Chromium, если он доступен

Настройка идемпотентна — повторный запуск выполняется быстро и пропускает уже выполненную работу.

Настройка редактора

VS Code

Установите расширение ACP Client.

Для подключения:

1. Откройте панель ACP Client на боковой панели.
2. Выберите VibeOS из встроенного списка агентов.
3. Подключитесь и начните чат.

Если вы хотите определить VibeOS вручную, добавьте его в настройках VS Code в разделе acp.agents:

{
  "acp.agents": {
    "VibeOS": {
      "command": "vibeos",
      "args": ["acp"]
    }
  }
}

Zed

Zed версии 0.221.x и новее устанавливает внешние агенты через официальный реестр ACP.

1. Откройте панель агентов.
2. Нажмите Add Agent или выполните команду zed: acp registry.
3. Найдите VibeOS.
4. Установите его и запустите новый поток внешнего агента VibeOS.

Предварительные требования:

• Сначала настройте учетные данные провайдера VibeOS с помощью vibeos model или установите их в ~/.vibeos/.env / ~/.vibeos/config.yaml.
• Установите uv, чтобы загрузчик реестра мог выполнить uvx --from 'vibeos-agent[acp]==<version>' vibeos-acp.

Для локальной разработки до появления записи в реестре используйте пользовательский сервер агента в настройках Zed:

{
  "agent_servers": {
    "vibeos-agent": {
      "type": "custom",
      "command": "vibeos",
      "args": ["acp"]
    }
  }
}

JetBrains

Используйте ACP-совместимый плагин и укажите в нем путь:

/path/to/vibeos-agent/acp_registry

Манифест реестра

Исходная копия официальных метаданных реестра ACP для VibeOS находится по адресу:

acp_registry/agent.json
acp_registry/icon.svg

PR в вышестоящий реестр копирует эти файлы в каталог верхнего уровня vibeos-agent/ в agentclientprotocol/registry.

Запись в реестре использует дистрибутив uvx, который указывает непосредственно на PyPI-релиз vibeos-agent:

uvx --from 'vibeos-agent[acp]==<version>' vibeos-acp

CI реестра проверяет, что указанная версия существует на PyPI, поэтому version в манифесте и пакет package в uvx должны всегда совпадать с pyproject.toml. scripts/release.py автоматически синхронизирует их.

Конфигурация и учетные данные

Режим ACP использует ту же конфигурацию VibeOS, что и CLI:

• ~/.vibeos/.env
• ~/.vibeos/config.yaml
• ~/.vibeos/skills/
• ~/.vibeos/state.db

Разрешение провайдера использует стандартный механизм разрешения времени выполнения VibeOS, поэтому ACP наследует текущего настроенного провайдера и учетные данные. VibeOS также предлагает метод терминальной аутентификации (--setup) для клиентов реестра при первом запуске; он открывает интерактивную настройку модели/провайдера VibeOS.

Поведение сессий

Сессии ACP отслеживаются менеджером сессий адаптера ACP в памяти, пока сервер работает.

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

• идентификатор сессии
• рабочую директорию
• выбранную модель
• текущую историю разговора
• событие отмены

Базовый AIAgent по-прежнему использует стандартные пути VibeOS для сохранения/логирования, но операции ACP list/load/resume/fork ограничены текущим запущенным процессом ACP-сервера.

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

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

Подтверждения

Опасные терминальные команды могут быть направлены обратно в редактор в виде запросов на подтверждение. Варианты подтверждения ACP проще, чем в CLI:

• разрешить один раз
• разрешить всегда
• запретить

При тайм-ауте или ошибке мост подтверждения отклоняет запрос.

Автоматическое подтверждение правок в рамках сессии

ACP предоставляет третий уровень между разрешить один раз и разрешить всегда: Разрешить для сессии. Выбор этого варианта в окне разрешений редактора записывает подтверждение только в текущую сессию ACP — каждая последующая соответствующая команда в этой сессии выполняется без запроса, но новая сессия ACP (или перезапуск редактора) сбрасывает состояние и снова запрашивает подтверждение при первом использовании.

Опция	Название в редакторе	Область действия	Сохраняется после перезапуска
allow_once	Разрешить один раз	Этот один вызов инструмента	Нет
allow_session	Разрешить для сессии	Все соответствующие вызовы в этой сессии ACP	Нет — очищается при завершении сессии
allow_always	Разрешить всегда	Все будущие сессии	Да (записывается в постоянный список разрешений VibeOS)
deny	Запретить	Этот один вызов инструмента	Нет

allow_session — правильный выбор по умолчанию для рабочего процесса в редакторе, когда вы доверяете агенту на время выполнения задачи, но не хотите предоставлять долгосрочную запись в списке разрешений. Компромисс безопасности очевиден: чем шире область действия, тем реже редактор будет вас прерывать, и тем больше вреда может нанести некорректно работающий агент (или инъекция промпта) до того, как вы это заметите. Начинайте с allow_once для незнакомых команд; переходите на allow_session, когда увидите, что агент несколько раз правильно выполнил один и тот же шаблон; оставьте allow_always для действительно идемпотентных команд, которым вы доверяете навсегда (например, git status).

Мост ACP сопоставляет эти опции с внутренней семантикой подтверждения VibeOS — allow_always записывает постоянную запись в список разрешений так же, как это делает CLI, в то время как allow_session влияет только на кэш подтверждений в процессе для текущей сессии ACP.

Устранение неполадок

ACP-агент не отображается в редакторе

Проверьте:

• В Zed откройте реестр ACP с помощью zed: acp registry и найдите VibeOS.
• Для ручной/локальной разработки убедитесь, что пользовательская команда agent_servers указывает на vibeos acp.
• VibeOS установлен и находится в вашем PATH.
• Установлено ACP-дополнение (pip install -e '.[acp]').
• Установлен uv, если запуск осуществляется через официальную запись реестра Zed.

ACP запускается, но сразу выдает ошибку

Попробуйте следующие проверки:

vibeos acp --version
vibeos acp --check
vibeos doctor
vibeos status

Отсутствуют учетные данные

Режим ACP использует существующую настройку провайдера VibeOS. Настройте учетные данные с помощью:

vibeos model

или отредактировав ~/.vibeos/.env. Клиенты реестра также могут запустить поток терминальной аутентификации VibeOS, который выполняет ту же интерактивную настройку провайдера/модели.

Загрузчик реестра Zed не может найти uv

Установите uv из официальной документации по установке uv, затем повторите попытку запуска потока VibeOS из Zed.

См. также

• Внутреннее устройство ACP
• Разрешение провайдера во время выполнения
• Среда выполнения инструментов