К содержимому
BuildNexus

Agent Gateway: один интерфейс, три транспорта

Проект — обычные файлы, так что шаблоны, стили, скрипты и модули можно править в любом редакторе. А для страниц, разделов, меню и настроек проекта есть Agent Gateway — локальный интерфейс к открытой Studio.

Он не привязан к конкретному клиенту и даёт три равноправных способа доступа:

  • MCP — конфиги для общего адаптера и для Cursor;
  • CLI — команда bnx-agent для POSIX, Git Bash и Windows;
  • HTTP/JSON — локальный адрес и токен из discovery-файла проекта.

MCP не обязателен: CLI и HTTP подойдут любому агенту, который умеет запустить команду или сделать локальный запрос.

Как подключиться

В Studio выберите «Открыть папку сайта в IDE». Studio сама определяет установленные редакторы и готовит конфиги подключения, не трогая ваши собственные MCP-серверы.

Два условия: Studio запущена и проект открыт. Адреса и токены действуют только для текущей сессии и обновляются при повторном открытии папки — после перезапуска Studio повторите команду.

Что может агент в вашей IDE

Через шлюз доступны те же доменные операции, что и в редакторе Studio:

  • страницы — найти, прочитать, создать, поменять SEO-поля;
  • разделы — добавить, заполнить по контракту, переставить, удалить;
  • меню и настройки проекта — пункты, переменные, общие секции;
  • модули — читать, создавать, править контракт и шаблоны, собирать;
  • файлы проекта — чтение и запись в границах проекта;
  • проверка результата — получить отрендеренный HTML или скриншот страницы песочницы, не открывая превью;
  • логи и компиляция SCSS — увидеть ошибки до сохранения.

Пример вызова через CLI:

.bnx/bin/bnx-agent health
.bnx/bin/bnx-agent tools
.bnx/bin/bnx-agent call page_read '{"name":"home"}'
.bnx/bin/bnx-agent call view_get_rendered_html '{"scope":"skin","page":"home"}'

В Windows удобнее передавать сложный JSON файлом или через stdin — это исключает ошибки экранирования между оболочками.

Почему не править JSON напрямую

Шлюз проверяет права, сверяет поля с контрактом модуля и ведёт ревизии — так две стороны (вы в редакторе и агент в IDE) не затирают работу друг друга. Прямая запись в pages.json, pages/*.json, project.json и menus/*.json эти проверки обходит.

Агенты внутри Studio

Встроенная панель агента работает через тот же шлюз и те же проверки. Подключить можно как облачных провайдеров по ключу, так и подписки вроде Claude Code и Codex, и локальные модели через Ollama или LM Studio.

Если выбираете облачного провайдера, посмотрите сервисы подписок и API нейросетей из России. Там разобраны различия способов доступа и расчёт токенов; поддержку конкретной подписки или API проверяйте в своём инструменте.

Работа с несколькими проектами

Проекты можно открыть в отдельных рабочих пространствах Studio. Задание встроенного агента сохраняет свой проект и ИИ-подключение, пока вы работаете в другом окне. Одновременно допускается до четырёх заданий разных проектов, остальные ожидают запуска. Закрытие окна не останавливает задание, пока Studio работает.

Подключения Agent Gateway разделены по проектам. В IDE открывайте папку нужного сайта и используйте её конфигурацию шлюза. Очередь и фоновое выполнение Studio относятся к встроенному агенту; внешние инструменты IDE управляют своими заданиями самостоятельно.

Безопасный цикл изменения

Шлюз агента использует те же проверки, что и Studio. Минимальный цикл работы из терминала:

.bnx/bin/bnx-agent health
.bnx/bin/bnx-agent tools --names
.bnx/bin/bnx-agent tools page_read
.bnx/bin/bnx-agent call page_read @page-read.json
  1. Проверьте соединение и получите актуальный список инструментов.
  2. Прочитайте страницу, раздел, меню или коллекцию.
  3. Получите схему нужной команды, а для модуля ещё и его контракт.
  4. Внесите узкое изменение через доменный инструмент.
  5. Перечитайте сущность и сравните число записей, поля и ревизию.
  6. Проверьте итоговый HTML, снимок и консоль страницы.

Большой JSON передавайте через @request.json, а большой ответ сохраняйте параметром --output. Это не меняет модель прав: все операции всё равно проходят через локальный шлюз Studio.

Ревизии и открытый редактор

Ревизия защищает изменения от тихой перезаписи. Для операции «прочитать, изменить, сохранить»:

  1. получите сущность через page_read, section_read, project_read, menu_read или collection_read;
  2. сохраните возвращённую ревизию;
  3. передайте её изменяющей команде, если этого требует схема;
  4. при конфликте перечитайте актуальные данные и повторно примените свою правку;
  5. после сохранения выполните повторное чтение.

Закрывать страницу в Studio перед работой агента не нужно. Если в редакторе есть несохранённые изменения, Studio не должна незаметно затереть их внешней записью и покажет конфликт.

Коллекции требуют особой осторожности: collection_query возвращает выборку, а не полный документ. Для изменения прочитайте всю коллекцию, измените полный массив записей и сохраните его с собственной ревизией коллекции.

Сессионные токены шлюза слушают только локальный адрес и не предназначены для Git, публикации или передачи другому процессу.

Диагностика страницы без ручного просмотра

Агент может проверить страницу в отдельном headless-браузере, даже если Preview в Studio не открыт.

  • view_get_rendered_html показывает итоговую серверную разметку.
  • view_screenshot проверяет внешний вид на заданной ширине и умеет прокручивать страницу.
  • view_dom_query находит элементы, тексты, атрибуты и вычисленные размеры.
  • view_overflow обнаруживает горизонтальное переполнение и текст за границами блока.
  • view_hit_test показывает, доходит ли реальное касание до кнопки и что её перекрывает.
  • view_console собирает ошибки браузерных модулей.
  • view_network показывает запросы и не загрузившиеся ресурсы.
  • section_render_debug раскрывает токены и записи, которые получил шаблон раздела.

Проверяйте как минимум настольную ширину и 375–390 px. Для элементов ниже первого экрана используйте прокрутку, для меню настоящее наведение, а для достижимости кнопки реальное касание, а не программный вызов click().