Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Редакторы, ассистенты и другие фронтенды

Aggrega используется из нескольких мест: из терминала, из расширения Visual Studio Code, из ИИ-ассистента, подключённого через Model Context Protocol (MCP), и из любой программы, которая управляет бинарным файлом aggrega. Ни один из этих фронтендов не содержит собственного компилятора. Каждый из них запускает бинарный файл aggrega или обращается к уже запущенному и отправляет ему запросы, поэтому разбор YAML, разрешение каталога и построение графа происходят в одном месте, а то, что показывает фронтенд, — это то, что скомпилировал этот бинарный файл. Фронтенд ничего из этого не реализует заново, поэтому нет второй копии, которая могла бы разойтись с первой.

В этой главе описан контракт, общий для этих фронтендов, и то, что каждый из них запрашивает у бинарного файла.

Граф IR — публичный контракт

Компиляция сущности Release вместе с сущностями Aggregate и Manifest, которые она называет, создаёт граф промежуточного представления (IR): каждый узел — с компонентом, экземпляр которого он создаёт, версией, до которой разрешился этот компонент, границей и подсистемой, в которых он находится, и файлом, который его объявил; каждое соединение между узлами; Features, подключённые к каждому из них; и значения, сопоставленные с ними, с указанием, откуда взялось каждое. Это снимок того, что компилятор собирается отрисовать в артефакты.

Структура графа опубликована как JSON Schema, https://aggrega.ai/schemas/ir-v1beta1.schema.json, а справочник по схеме IR описывает каждое поле. Фронтенд читает граф по этой схеме, а не по внутреннему устройству компилятора, поэтому схема — единственное место, где развивается структура, и фронтенд, написанный на любом языке, отслеживает её одинаково.

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

Три способа запросить граф

Один и тот же граф доступен на каждой поверхности, и каждый ответ — это один полный документ графа:

  • Из командной строки. aggrega build, aggrega inspect с указанной сущностью Release и aggrega validate --release принимают --ir-graph, который в дополнение ко всему, что команда уже выводит, записывает граф, вычисленный в ходе запуска, в стандартный вывод в формате JSON. --unredacted рядом с ним выводит конфиденциальные значения. См. aggrega inspect.
  • Из демона. Запрос aggrega/irGraph к aggrega serve, указывающий сущность Release по её пути относительно корня рабочей области, получает в ответ тот же документ в graph; unredacted: true запрашивает конфиденциальные значения. См. aggrega serve.
  • Из ИИ-ассистента. Инструменты cli-inspect, cli-build и cli-validate MCP-сервера принимают флаг команды в виде аргумента ir_graph. См. aggrega mcp.

Каждый ответ описывает сущность Release в том виде, в каком она была на момент запроса. Фронтенд, отслеживающий правки, запрашивает снова: расширение Visual Studio Code перерисовывает свой граф при каждом сохранении документа.

Расширение Visual Studio Code

Расширение Aggrega для Visual Studio Code запускает aggrega serve и поддерживает его работу для рабочей области. Каждый ответ, который оно показывает, поступает от бинарного файла aggrega: большинство от этого демона — среди них диагностика по мере редактирования, всплывающие подсказки, автодополнение, переход к определению, поиск ссылок, сборка и предварительная сборка, — а остальные от запуска собственных команд бинарного файла.

Его граф топологии — это граф IR. Расширение отправляет aggrega/irGraph для выбранной сущности Release и рисует ответ: границы и подсистемы как вложенные контейнеры, компоненты как узлы, соединения как рёбра, а на выбранном узле или соединении — подключённые к нему Features. Компилятор отправляет топологию и никогда не отправляет координаты; раскладка вычисляется в редакторе. Подключение сущности Feature из графа тоже проходит через демон: компилятор называет документ и место в нём, куда относится подключение, а расширение записывает его туда. О том, что показывает и делает это представление, см. граф топологии.

MCP-сервер

aggrega mcp запускает бинарный файл как сервер Model Context Protocol, поэтому ИИ-ассистент обнаруживает операции Aggrega и вызывает их, а не читает вывод команд. Через стандартные ввод и вывод он общается по JSON-RPC 2.0 с разделением сообщений символом новой строки, и именно так к нему обращается клиент, запускающий его как подпроцесс; через HTTP он обслуживает одну конечную точку, /mcp, для вызывающих на других машинах. Его инструменты являются операциями компилятора — чтение схем, описание рабочей области, валидация, сборка, создание черновиков и редактирование документов, — и на каждый вызов отвечает тот же бинарный файл, который запускает командная строка.

Раздел Подключение MCP-сервера описывает подключение каждого клиента, а раздел Что ваш ассистент может делать с Aggrega — возможности инструментов.

Демон aggrega serve

aggrega serve запускает компилятор как долгоживущий процесс для редакторов. Он хранит разобранные документы, разрешённый каталог и диагностику между запросами, поэтому редактор может задавать множество мелких вопросов, не расплачиваясь каждый раз за полную загрузку каталога.

Протокол — это JSON-RPC 2.0 через стандартные ввод и вывод, где каждому сообщению предшествует заголовок Content-Length, а методы находятся в пространстве имён aggrega/. Это не Language Server Protocol, поскольку он переносит операции, для которых в том протоколе нет места, например запрос графа IR; расширение редактора выполняет преобразование между запросами своего редактора и этими методами и там, где это уместно, повторно использует формы позиции, диапазона и местоположения из того протокола. Сеанс открывается методом aggrega/initialize, который сообщает рабочую область и версию отвечающего бинарного файла; демон отправляет диагностику через aggrega/publishDiagnostics; а уведомление aggrega/shutdown корректно завершает сеанс.

Тело каждого сообщения опубликовано как схема, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, описанная в справочнике по формату обмена; расширение Visual Studio Code берёт из неё свои типы сообщений. Другой редактор интегрируется, используя тот же протокол. Справочник по aggrega serve описывает каждый метод, что он читает и записывает, и ошибки, которые он выдаёт.