ACP-режим¶

ACP (Agent Client Protocol) — это открытый протокол взаимодействия AI-агентов с редакторами и IDE.

В ACP-режиме Koda CLI работает как сервер: IDE-клиент запускает его как подпроцесс и отправляет запросы по протоколу JSON-RPC 2.0 через stdin/stdout, а CLI возвращает ответы и потоковые обновления. ACP нужен, когда вы хотите использовать функционал Koda в вашей любимой IDE, для которого нет подходящего готового плагина.

Подготовка¶

Если Koda CLI ещё не установлен, поставьте Node.js версии 20 или новее и выполните:

npm install -g @kodadev/koda-cli@latest

Если CLI уже установлен, обязательно обновите его до актуальной версии:

npm install -g @kodadev/koda-cli@latest
koda --version

Запустить CLI без глобальной установки можно через npx:

npx -y @kodadev/koda-cli@latest

Специальная настройка самого ассистента не требуется, но перед подключением к IDE авторизуйтесь: запустите koda в обычном терминале и выполните команду /auth с выбором «Войти через Koda Auth».

Некоторым клиентам нужны абсолютные пути до исполняемых файлов node и koda. Узнать их можно так:

# linux/macos
which node npx koda

# windows cmd
where node npx koda

# windows powershell
(Get-Command node, npx, koda).Path

Запуск¶

ACP-режим включается флагом --acp.

IDE запускает koda --acp как подпроцесс и пишет запросы в stdin. Взаимодействие с агентом происходит через собственный UI среды разработки или редактора.

Аутентификация¶

Клиент выбирает способ аутентификации из методов, объявленных агентом:

• Войти через Koda Auth — вход через Koda Auth;
• Продолжить без аутентификации — работа без аутентификации.

Для долгих автоматических сценариев удобно заранее выполнить вход в обычном терминале, чтобы CLI не запрашивал его повторно. Токены хранятся в ~/.config/koda/credentials.json. Если этот файл нельзя создать или обновить, ACP-сессия в клиенте может не стартовать. Подробнее об авторизации — на странице авторизация.

Отладка¶

Поскольку stdout занят JSON-RPC фреймами, служебные сообщения пишутся в stderr. Wrapper-скрипты не должны выводить произвольный текст в stdout, чтобы не повредить транспорт.

Общий флаг отладки:

koda --acp --debug

Телеметрия включается отдельными флагами и может перенаправляться в файл:

koda --acp \
  --telemetry \
  --telemetry-target local \
  --telemetry-outfile /path/to/log.json

• --telemetry — включить отправку телеметрии;
• --telemetry-target — цель: local или gcp;
• --telemetry-outfile — перенаправить всю телеметрию в указанный файл.

Ограничения¶

• В ACP-режиме недоступен интерактивный TUI, поэтому работает только ограниченный набор слеш-команд: /about, /docs, /init, /compress, /help.
• Команды и действия, которым нужен интерактивный диалог или подтверждение в TUI, недоступны.
• Vim mode в ACP-сессии не поддерживается.
• stdout зарезервирован под протокол: любая посторонняя запись в stdout испортит обмен.

Протокол¶

Полная спецификация — на странице спецификация ACP-сервера. Там описаны транспорт, жизненный цикл соединения, методы агента и клиента, параметры сессии (session/new), восстановление и ветвление сессий, а также коды ошибок.

Устранение проблем¶