Edytory, asystenci i inne frontendy
Z Aggrega korzysta się w więcej niż jednym miejscu: w terminalu, w rozszerzeniu Visual Studio Code, w asystencie AI połączonym przez Model Context Protocol (MCP) oraz w dowolnym programie, który steruje plikiem binarnym aggrega. Żaden z tych frontendów nie ma własnego kompilatora. Każdy z nich uruchamia plik binarny aggrega lub łączy się z już działającym i wysyła do niego zapytania, więc parsowanie YAML, rozwiązywanie katalogu i budowanie grafu odbywają się w jednym miejscu, a to, co pokazuje frontend, jest tym, co skompilował ten plik binarny. Frontend niczego z tego nie implementuje ponownie, więc nie ma drugiej kopii, która mogłaby rozjechać się z pierwszą.
Ten rozdział opisuje kontrakt wspólny dla tych frontendów oraz to, o co każdy z nich prosi plik binarny.
Graf IR jest publicznym kontraktem
Kompilacja encji Release wraz ze wskazanymi przez nią encjami Aggregate i Manifest tworzy graf reprezentacji pośredniej (IR): każdy węzeł wraz z komponentem, który instancjonuje, wersją, do której ten komponent został rozwiązany, granicą i podsystemem, w których się znajduje, oraz plikiem, który go zadeklarował; każde połączenie między węzłami; Features dołączone do każdego z nich; oraz wartości na nie zmapowane, wraz z pochodzeniem każdej z nich. Jest to migawka tego, co kompilator za chwilę wyrenderuje do artefaktów.
Kształt grafu jest publikowany jako JSON Schema, https://aggrega.ai/schemas/ir-v1beta1.schema.json, a dokumentacja referencyjna schematu IR opisuje każde pole. Frontend odczytuje graf na podstawie tego schematu, a nie wewnętrznych mechanizmów kompilatora, więc schemat jest jedynym miejscem, w którym kształt ewoluuje, a frontend napisany w dowolnym języku śledzi go w ten sam sposób.
Wartości, które autor zadeklarował jako wrażliwe, są ukrywane w grafie wszędzie tam, gdzie jest on przekazywany. Frontend, który potrzebuje ich w postaci jawnej, prosi o nie wprost, a wszystko, do czego następnie trafi odpowiedź, otrzymuje je w postaci jawnej.
Trzy sposoby uzyskania grafu
Ten sam graf jest dostępny na każdej powierzchni, a każda odpowiedź to jeden kompletny dokument grafu:
- Z wiersza poleceń.
aggrega build,aggrega inspectz podaną encją Release orazaggrega validate --releaseprzyjmują--ir-graph, który oprócz wszystkiego, co polecenie już generuje, zapisuje na standardowe wyjście w formacie JSON graf obliczony w danym uruchomieniu. Podany obok niego--unredactedwypisuje wartości wrażliwe. Zob.aggrega inspect. - Z demona. Żądanie
aggrega/irGraphwysłane doaggrega serve, wskazujące encję Release przez jej ścieżkę względną wobec katalogu głównego obszaru roboczego, otrzymuje w odpowiedzi ten sam dokument podgraph;unredacted: trueprosi o wartości wrażliwe. Zob.aggrega serve. - Z asystenta AI. Narzędzia
cli-inspect,cli-buildicli-validateserwera MCP przyjmują flagę polecenia jako argumentir_graph. Zob.aggrega mcp.
Każda odpowiedź opisuje encję Release w stanie z chwili zadania pytania. Frontend, który śledzi zmiany, pyta ponownie: rozszerzenie Visual Studio Code przerysowuje swój graf przy każdym zapisaniu dokumentu.
Rozszerzenie Visual Studio Code
Rozszerzenie Aggrega dla Visual Studio Code uruchamia aggrega serve i utrzymuje go w działaniu dla obszaru roboczego. Każda odpowiedź, którą pokazuje, pochodzi z pliku binarnego aggrega: większość z tego demona — m.in. diagnostyka podczas edycji, podpowiedzi po najechaniu, uzupełnianie, przejście do definicji, wyszukiwanie odwołań, budowanie i podgląd budowania — a reszta z uruchamiania własnych poleceń pliku binarnego.
Jego graf topologii to graf IR. Rozszerzenie wysyła aggrega/irGraph dla wybranej encji Release i rysuje odpowiedź: granice i podsystemy jako zagnieżdżone kontenery, komponenty jako węzły, połączenia jako krawędzie, a na wybranym węźle lub połączeniu dołączone do niego Features. Kompilator przesyła topologię, nigdy współrzędne; układ jest obliczany w edytorze. Dołączanie encji Feature z poziomu grafu również przechodzi przez demona: kompilator wskazuje dokument i miejsce w nim, do którego należy dołączenie, a rozszerzenie zapisuje je tam. Zob. graf topologii, aby dowiedzieć się, co pokazuje i robi ten widok.
Serwer MCP
aggrega mcp uruchamia plik binarny jako serwer Model Context Protocol, dzięki czemu asystent AI odkrywa operacje Aggrega i je wywołuje, zamiast czytać wyjście poleceń. Przez standardowe wejście i wyjście komunikuje się za pomocą JSON-RPC 2.0 rozdzielanego znakami nowego wiersza i właśnie w ten sposób łączy się z nim klient, który uruchamia go jako podproces; przez HTTP udostępnia jeden punkt końcowy, /mcp, dla wywołujących na innych maszynach. Jego narzędzia to operacje kompilatora — odczyt schematów, opis obszaru roboczego, walidacja, budowanie, tworzenie szkiców i edycja dokumentów — a na każde wywołanie odpowiada ten sam plik binarny, który uruchamia wiersz poleceń.
Strona Podłączanie serwera MCP opisuje podłączanie każdego klienta, a strona Co asystent może zrobić z Aggrega opisuje, co oferują narzędzia.
Demon aggrega serve
aggrega serve uruchamia kompilator jako długo działający proces dla edytorów. Przechowuje sparsowane dokumenty, rozwiązany katalog i diagnostykę między żądaniami, dzięki czemu edytor może zadawać wiele drobnych pytań bez ponoszenia za każdym razem kosztu pełnego wczytania katalogu.
Protokołem jest JSON-RPC 2.0 przez standardowe wejście i wyjście, przy czym każdą wiadomość poprzedza nagłówek Content-Length, a metody znajdują się w przestrzeni nazw aggrega/. Nie jest to Language Server Protocol, ponieważ przenosi operacje, dla których tamten protokół nie ma miejsca, takie jak żądanie grafu IR; rozszerzenie edytora tłumaczy między żądaniami swojego edytora a tymi metodami i tam, gdzie to pasuje, wykorzystuje kształty pozycji, zakresu i lokalizacji z tamtego protokołu. Sesję otwiera aggrega/initialize, które zgłasza obszar roboczy i wersję odpowiadającego pliku binarnego; demon wypycha diagnostykę za pomocą aggrega/publishDiagnostics; a powiadomienie aggrega/shutdown czysto ją kończy.
Każda treść wiadomości jest publikowana jako schemat, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, opisany w dokumentacji referencyjnej formatu wymiany; rozszerzenie Visual Studio Code pobiera z niego swoje typy wiadomości. Inny edytor integruje się, posługując się tym samym protokołem. Dokumentacja referencyjna aggrega serve opisuje każdą metodę, co odczytuje i zapisuje oraz jakie błędy zgłasza.