Editoren, Assistenten und andere Frontends
Aggrega wird von mehr als einer Stelle aus verwendet: einem Terminal, der Erweiterung für Visual Studio Code, einem KI-Assistenten, der über das Model Context Protocol (MCP) verbunden ist, und jedem Programm, das die Binärdatei aggrega ansteuert. Keines dieser Frontends bringt einen eigenen Compiler mit. Jedes führt die Binärdatei aggrega aus oder erreicht eine bereits laufende und fragt sie, sodass das Parsen von YAML, das Auflösen des Katalogs und der Aufbau des Graphen an einer Stelle stattfinden und das, was ein Frontend anzeigt, das ist, was diese Binärdatei kompiliert hat. Ein Frontend implementiert nichts davon neu, sodass es keine zweite Kopie gibt, die von der ersten abweichen könnte.
Dieses Kapitel beschreibt den Vertrag, den diese Frontends teilen, und was jedes davon von der Binärdatei anfordert.
Der IR-Graph ist der öffentliche Vertrag
Das Kompilieren eines Release mit dem Aggregate und dem Manifest, die es benennt, erzeugt einen Graphen der Zwischendarstellung (IR): jeden Knoten mit der Komponente, die er instanziiert, der Version, zu der diese Komponente aufgelöst wurde, der Boundary und dem Subsystem, in denen er liegt, und der Datei, die ihn deklariert hat; jede Verbindung zwischen Knoten; die an jeden angebundenen Features; und die darauf zugeordneten Werte, jeweils mit ihrer Herkunft. Er ist der Schnappschuss dessen, was der Compiler gleich in Artefakte rendern wird.
Die Form des Graphen wird als JSON Schema veröffentlicht, https://aggrega.ai/schemas/ir-v1beta1.schema.json, und die Referenz des IR-Schemas beschreibt jedes Feld. Ein Frontend liest den Graphen gegen dieses Schema, nicht gegen die Interna des Compilers, sodass das Schema die eine Stelle ist, an der sich die Form weiterentwickelt, und ein Frontend in jeder beliebigen Sprache ihr auf dieselbe Weise folgt.
Werte, die ein Autor als sensibel deklariert hat, werden im Graphen zurückgehalten, wo immer er herausgegeben wird. Ein Frontend, das sie im Klartext benötigt, fordert sie ausdrücklich an, und alles, was die Antwort dann erreicht, trägt sie im Klartext.
Drei Wege, den Graphen anzufordern
Derselbe Graph ist auf jeder Oberfläche verfügbar, und jede Antwort ist ein vollständiges Graph-Dokument:
- Von der Befehlszeile.
aggrega build,aggrega inspectmit einem Release undaggrega validate --releaseakzeptieren jeweils--ir-graph, das den in diesem Lauf berechneten Graphen zusätzlich zu allem, was der Befehl ohnehin erzeugt, als JSON auf die Standardausgabe schreibt.--unredacteddaneben gibt die sensiblen Werte aus. Sieheaggrega inspect. - Vom Daemon. Eine Anfrage
aggrega/irGraphanaggrega serve, die das Release über seinen Pfad relativ zum Stammverzeichnis des Workspace benennt, wird mit demselben Dokument untergraphbeantwortet;unredacted: truefordert die sensiblen Werte an. Sieheaggrega serve. - Von einem KI-Assistenten. Die Werkzeuge
cli-inspect,cli-buildundcli-validatedes MCP-Servers nehmen das Flag des Befehls als ihr Argumentir_graphentgegen. Sieheaggrega mcp.
Jede Antwort beschreibt das Release so, wie es zum Zeitpunkt der Frage stand. Ein Frontend, das Änderungen verfolgt, fragt erneut: Die Erweiterung für Visual Studio Code zeichnet ihren Graphen bei jedem Speichern eines Dokuments neu.
Die Erweiterung für Visual Studio Code
Die Aggrega-Erweiterung für Visual Studio Code startet aggrega serve und hält es für den Workspace in Betrieb. Jede Antwort, die sie anzeigt, stammt aus der Binärdatei aggrega: die meisten von diesem Daemon — darunter Diagnosen während der Bearbeitung, Hover, Vervollständigung, Gehe zu Definition, Verweise suchen, Build und Build-Vorschau — und der Rest aus der Ausführung der eigenen Befehle der Binärdatei.
Ihr Topologiegraph ist der IR-Graph. Die Erweiterung sendet aggrega/irGraph für das ausgewählte Release und zeichnet die Antwort: Boundaries und Subsysteme als verschachtelte Container, Komponenten als Knoten, Verbindungen als Kanten und, an einem ausgewählten Knoten oder einer ausgewählten Verbindung, die daran angebundenen Features. Der Compiler sendet Topologie und niemals Koordinaten; das Layout wird im Editor berechnet. Auch das Anbinden eines Feature aus dem Graphen läuft über den Daemon: Der Compiler benennt das Dokument und die Stelle darin, an die die Anbindung gehört, und die Erweiterung schreibt sie dorthin. Siehe den Topologiegraphen dazu, was die Ansicht zeigt und tut.
Der MCP-Server
aggrega mcp führt die Binärdatei als Model-Context-Protocol-Server aus, sodass ein KI-Assistent die Operationen von Aggrega entdeckt und sie aufruft, statt Befehlsausgaben zu lesen. Über Standardeingabe und -ausgabe spricht er zeilengetrenntes JSON-RPC 2.0, über das ihn ein Client erreicht, der ihn als Unterprozess startet; über HTTP stellt er einen einzigen Endpunkt, /mcp, für Aufrufer auf anderen Rechnern bereit. Seine Werkzeuge sind die Operationen des Compilers — Schemas lesen, den Workspace beschreiben, validieren, bauen, Dokumente entwerfen und bearbeiten —, und jeder Aufruf wird von derselben Binärdatei beantwortet, die auch die Befehlszeile ausführt.
Den MCP-Server verbinden behandelt das Verbinden jedes Clients, und Was Ihr Assistent mit Aggrega tun kann behandelt, was die Werkzeuge bieten.
Der Daemon aggrega serve
aggrega serve führt den Compiler als langlebigen Prozess für Editoren aus. Er hält die geparsten Dokumente, den aufgelösten Katalog und die Diagnosen über Anfragen hinweg vor, sodass ein Editor viele kleine Fragen stellen kann, ohne jedes Mal für ein vollständiges Laden des Katalogs zu bezahlen.
Das Protokoll ist JSON-RPC 2.0 über Standardeingabe und -ausgabe, wobei jeder Nachricht ein Header Content-Length vorangeht, mit Methoden im Namensraum aggrega/. Es ist nicht das Language Server Protocol, weil es Operationen transportiert, für die jenes Protokoll keinen Platz hat, etwa die Anfrage nach dem IR-Graphen; eine Editor-Erweiterung übersetzt zwischen den Anfragen ihres Editors und diesen Methoden und verwendet die Formen für Position, Bereich und Ort jenes Protokolls wieder, wo sie passen. Eine Sitzung beginnt mit aggrega/initialize, das den Workspace und die Version der antwortenden Binärdatei meldet; der Daemon sendet Diagnosen mit aggrega/publishDiagnostics; und die Benachrichtigung aggrega/shutdown beendet sie sauber.
Jeder Nachrichtenrumpf ist als Schema veröffentlicht, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, beschrieben in der Referenz der Nachrichtenform; die Erweiterung für Visual Studio Code bezieht ihre Nachrichtentypen daraus. Ein anderer Editor integriert sich, indem er dasselbe Protokoll spricht. Die Referenz zu aggrega serve beschreibt jede Methode, was sie liest und schreibt und welche Fehler sie auslöst.