Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

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 inspect z podaną encją Release oraz aggrega validate --release przyjmują --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 --unredacted wypisuje wartości wrażliwe. Zob. aggrega inspect.
  • Z demona. Żądanie aggrega/irGraph wysłane do aggrega serve, wskazujące encję Release przez jej ścieżkę względną wobec katalogu głównego obszaru roboczego, otrzymuje w odpowiedzi ten sam dokument pod graph; unredacted: true prosi o wartości wrażliwe. Zob. aggrega serve.
  • Z asystenta AI. Narzędzia cli-inspect, cli-build i cli-validate serwera MCP przyjmują flagę polecenia jako argument ir_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.