Редактори, асистенти та інші фронтенди
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 описує кожен метод, що він читає й записує, і помилки, які він породжує.