Интеграция ACP

Подключите редактор к CodeGraph через Agent Client Protocol (ACP), чтобы отправлять промпты, получать потоковые обновления и обрабатывать запросы на чтение файлов, команды терминала и разрешения. Справочник помогает разработчикам интеграций выбрать транспорт и реализовать соединение JSON-RPC. ACP v1 — основной профиль, совместимый с промышленным контуром. Экспериментальный профиль ACP v2 alpha включается через CODEGRAPH_ACP_EXPERIMENTAL_V2=true. Метод initialize выбирает профиль на весь срок соединения; сменить его без нового соединения нельзя.

Оба профиля используют общее ядро сессий CodeGraph, ограничения рабочего каталога, запросы разрешений и мост Model Context Protocol (MCP). Возможности обработки изображений и аудио сервер не объявляет.

Транспорты и маршруты

Управление HTTP-сессиями доступно через GET /api/v1/admin/runtime/acp/sessions и DELETE /api/v1/admin/runtime/acp/sessions/{session_id}. Состояние протокола и сессии HTTP изолированы по аутентифицированному субъекту и проекту. Для WebSocket область проекта берётся из токена, машинной учётной записи или явно включённого локального контура разработки.

HTTP собирает уведомления обработки промпта в ACP v1 и возвращает их в result._meta.codegraph.sessionUpdates. В ACP v2 метод session/prompt работает асинхронно и требует потоковый транспорт. HTTP отклоняет такой запрос кодом JSON-RPC -32004 до выполнения хода агента.

Граница аутентификации

Для HTTP JSON-RPC и маршрутов сессий нужны роль администратора, разрешение admin:all либо сервисная учётная запись с разрешением scenarios:execute. Обход аутентификации на localhost возможен только при явно включённом параметре local_dev_unauthenticated_surfaces_enabled.

WebSocket принимает токен доступа Bearer или ключ API. Для машинной учётной записи сервер также проверяет область проекта, версию X-CodeGraph-Machine-Contract, политику интерфейса и требования mTLS. Аутентификация транспорта завершается до разбора JSON-RPC-параметров. Оба профиля ACP возвращают пустой список authMethods; поэтому устаревший v1-метод authenticate работает только внутри уже проверенной транспортной границы.

Методы ACP v1

В уже аутентифицированном транспортном соединении отправьте минимальный запрос инициализации:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}

Сопоставьте ответ по id: 1 и проверьте result.protocolVersion: 1. Ответ с ошибкой не инициализирует соединение. Этот запрос сам по себе не создаёт сеанс и не выполняет промпт.

Сначала вызовите initialize с protocolVersion: 1. До инициализации сервер отклоняет остальные методы с кодом -32002.

Стандартная поверхность v1 включает session/new, session/load, session/prompt и session/cancel. Во время обработки промпта сервер может вызвать у клиента fs/read_text_file, fs/write_text_file, терминальные методы и session/request_permission. Клиент должен связывать ответы по идентификатору JSON-RPC и одновременно обрабатывать уведомления session/update.

При обработке промпта ACP v1 эти клиентские вызовы включаются явно через расширение _meta.codegraph.clientContext у блока содержимого. Массив readTextFiles принимает объекты с полем path. Каждый объект массива terminals содержит command, массив строк args и необязательные cwd, env или outputByteLimit. CodeGraph вызывает только возможности, объявленные клиентом при initialize, добавляет возвращённый редакторский текст и результат терминала в текущий prompt и всегда освобождает созданный терминал. Эти метаданные — расширение CodeGraph, а не новый стандартный метод ACP.

Расширения CodeGraph используют пространство имён _codegraph/:

• _codegraph/thread/start, _codegraph/thread/resume, _codegraph/thread/fork, _codegraph/thread/list, _codegraph/thread/archive и _codegraph/thread/compact;
• _codegraph/turn/start и _codegraph/turn/interrupt;
• _codegraph/diagnostics/subscribe, _codegraph/diagnostics/unsubscribe и _codegraph/hover/request;
• _codegraph/item/fileChange/respondApproval.

Прежние имена без префикса доступны через явный адаптер совместимости. Такой ответ содержит _meta.codegraph.legacyMethod; новые клиенты должны использовать методы с пространством имён.

Экспериментальный профиль ACP v2

Если задано CODEGRAPH_ACP_EXPERIMENTAL_V2=true, соединение можно инициализировать с protocolVersion: 2, info.name и info.version. Профиль поддерживает session/new, session/list, session/resume, session/close, session/delete, session/prompt, session/cancel и $/cancel_request.

На session/prompt сервер отвечает до завершения хода агента. Затем клиент получает уведомления session/update, в том числе переходы состояния и обновления вызовов инструментов. Для этого потока нужен stdio или WebSocket. Повторный initialize с другой версией протокола отклоняется; откройте новое соединение.

Для отката задайте CODEGRAPH_ACP_EXPERIMENTAL_V2=false и перезапустите ACP-соединения. Работа ACP v1 от флага v2 не зависит.

MCP-серверы и запрос разрешения

session/new и соответствующие операции resume/load принимают ACP-дескрипторы MCP для транспортов stdio и http. Stdio-команда преобразуется в путь к исполняемому файлу и запускается как список аргументов без оболочки. Переменные окружения и заголовки передаются объектами с полями name и value. Сервер проверяет имена и запрещает NUL, возврат каретки и перевод строки в значениях.

Для MCP через HTTP разрешены только публичные адреса HTTPS. Сервер отклоняет учётные данные в URL, query string, fragment, loopback, приватные и link-local адреса, а также обычный HTTP. Администратор платформы может разрешить дополнительные адреса через явный список. Проверка адреса выполняется перед подключением. Для сервера с перенаправлениями настройте ограничения исходящей сети, которые охватывают и конечные адреса переходов.

При создании сессии должны подключиться все объявленные MCP-серверы. Если хотя бы один сервер недоступен, CodeGraph закрывает уже открытые соединения и удаляет незавершённую ACP-сессию. Перед вызовом MCP-инструмента агент отправляет session/request_permission; отказ или тайм-аут отменяет вызов. Закрытие сессии или транспорта освобождает дочерние процессы MCP и сетевые соединения.

Ограничения рабочего каталога и терминала

Файловые методы требуют абсолютные workspaceRoot и path. Если целевой путь после нормализации находится вне корня, сервер возвращает outside workspace root. При записи также запрещены чувствительные фрагменты пути: .git, .env, .ssh, .aws, .credentials, __pycache__ и node_modules. Проверка ищет эти фрагменты в любой части нормализованного пути, приведённого к нижнему регистру, а не только в полных именах каталогов.

Терминальные методы используют тот же абсолютный workspaceRoot; cwd должен оставаться внутри него. Команда запускается как список аргументов с shell=False. В репозитории задан ограниченный список разрешённых команд сборки и чтения. Интерпретаторы и оболочки python, powershell, pwsh, cmd, bash, sh, py, python3 и node запрещены. Аргументы передаются нативным списком строк без NUL, перевода строки и возврата каретки.

Сетевые маршруты используют аутентификацию транспорта и область проекта. Проверки рабочего каталога и терминала действуют внутри этой области.

Согласование файловых изменений

Сервер объявляет процесс согласования и отправляет уведомление item/fileChange/requestApproval. Клиент отвечает каноническим методом _codegraph/item/fileChange/respondApproval; ответ без префикса принимает адаптер совместимости. Если ответ не поступил до тайм-аута, запрос отклоняется.

Метод fs/write_text_file записывает файл после проверки пути внутри рабочего каталога. Для записи с подтверждением человека клиент сначала получает и сохраняет согласование, затем предоставляет операцию записи. Это отдельный шаг клиентского рабочего процесса.

Ограничения среды выполнения

Значения ACPRuntimeConfig по умолчанию ограничивают сервис 100 одновременными сессиями с тайм-аутом 60 минут, 128 ожидающими запросами агента к клиенту на соединение, очередью из 256 stdio-уведомлений и тайм-аутом согласования 300 секунд. Та же конфигурация задаёт время ожидания и завершения терминала, интервалы опроса мостов и размер потоковых фрагментов. Развёртывание может переопределить эти значения через общую конфигурацию среды выполнения; клиент не должен полагаться на сохранение значений по умолчанию.

Восстановление

1. Проверьте префикс /api/v1/admin/runtime/acp: исторический /acp больше не используется.
2. Проверьте аутентификацию транспорта до разбора параметров JSON-RPC.
3. Отправьте один запрос initialize и сохраняйте выбранный профиль до закрытия соединения.
4. Для промптов ACP v2 и запросов агента к клиенту используйте stdio или WebSocket.
5. При ошибке файлового или терминального метода держите абсолютные workspaceRoot, path и cwd внутри одного корня.
6. Запрет исполняемого файла, отклонение адреса MCP или отсутствие разрешения означает отказ политики; обходить его через shell нельзя.