Редакторы, ассистенты и другие фронтенды
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-validateMCP-сервера принимают флаг команды в виде аргумента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 описывает каждый метод, что он читает и записывает, и ошибки, которые он выдаёт.