Editor, assistenti e altri frontend
Aggrega si usa da più di un posto: un terminale, l’estensione per Visual Studio Code, un assistente IA collegato tramite il Model Context Protocol (MCP) e qualsiasi programma che pilota il binario aggrega. Nessuno di questi frontend contiene un compilatore proprio. Ciascuno esegue il binario aggrega, o ne raggiunge uno già in esecuzione, e lo interroga, così l’analisi dello YAML, la risoluzione del catalogo e la costruzione del grafo avvengono in un solo posto, e ciò che un frontend mostra è ciò che quel binario ha compilato. Un frontend non ne reimplementa nulla, quindi non esiste una seconda copia che possa divergere dalla prima.
Questo capitolo descrive il contratto che quei frontend condividono e che cosa ciascuno chiede al binario.
Il grafo IR è il contratto pubblico
Compilare una Release, con l’Aggregate e il Manifest che nomina, produce un grafo della rappresentazione intermedia (IR): ogni nodo, con il componente che istanzia, la versione a cui quel componente si è risolto, il confine e il sottosistema in cui si trova e il file che lo ha dichiarato; ogni connessione tra nodi; le Features associate a ciascuno; e i valori mappati su di essi, con la provenienza di ciascuno. È l’istantanea di ciò che il compilatore sta per rendere in artefatti.
La forma del grafo è pubblicata come JSON Schema, https://aggrega.ai/schemas/ir-v1beta1.schema.json, e il riferimento dello schema IR descrive ogni campo. Un frontend legge il grafo in base a quello schema, non in base agli interni del compilatore, quindi lo schema è l’unico posto in cui la forma evolve, e un frontend scritto in qualsiasi linguaggio lo segue allo stesso modo.
I valori che un autore ha dichiarato sensibili vengono trattenuti dal grafo ovunque esso venga consegnato. Un frontend che ne ha bisogno in chiaro li chiede esplicitamente, e tutto ciò che la risposta raggiunge da quel momento li porta in chiaro.
Tre modi per chiedere il grafo
Lo stesso grafo è disponibile su ogni superficie, e ogni risposta è un documento di grafo completo:
- Dalla riga di comando.
aggrega build,aggrega inspectcon una Release eaggrega validate --releaseaccettano ciascuno--ir-graph, che scrive sull’output standard come JSON il grafo calcolato da quell’esecuzione, oltre a tutto ciò che il comando produce già.--unredactedaccanto a esso stampa i valori sensibili. Vediaggrega inspect. - Dal daemon. Una richiesta
aggrega/irGraphadaggrega serve, che nomina la Release con il suo percorso relativo alla radice del workspace, riceve come risposta lo stesso documento sottograph;unredacted: truechiede i valori sensibili. Vediaggrega serve. - Da un assistente IA. Gli strumenti
cli-inspect,cli-buildecli-validatedel server MCP accettano il flag del comando come loro argomentoir_graph. Vediaggrega mcp.
Ogni risposta descrive la Release com’era nel momento in cui è stata posta la domanda. Un frontend che segue le modifiche chiede di nuovo: l’estensione per Visual Studio Code ridisegna il suo grafo ogni volta che un documento viene salvato.
L’estensione per Visual Studio Code
L’estensione Aggrega per Visual Studio Code avvia aggrega serve e lo mantiene in esecuzione per il workspace. Ogni risposta che mostra viene dal binario aggrega: la maggior parte da quel daemon — tra cui la diagnostica durante la modifica, l’hover, il completamento, vai alla definizione, trova riferimenti, la build e l’anteprima della build — e il resto dall’esecuzione dei comandi del binario stesso.
Il suo grafo della topologia è il grafo IR. L’estensione invia aggrega/irGraph per la Release selezionata e disegna la risposta: confini e sottosistemi come contenitori annidati, componenti come nodi, connessioni come archi e, su un nodo o una connessione selezionati, le Features associate. Il compilatore invia la topologia e mai le coordinate; il layout viene calcolato nell’editor. Anche associare una Feature dal grafo passa per il daemon: il compilatore nomina il documento e il punto al suo interno a cui appartiene l’associazione, e l’estensione la scrive lì. Vedi il grafo della topologia per ciò che la vista mostra e fa.
Il server MCP
aggrega mcp esegue il binario come server Model Context Protocol, così un assistente IA scopre le operazioni di Aggrega e le chiama invece di leggere l’output dei comandi. Su input e output standard parla JSON-RPC 2.0 delimitato da newline, che è il modo in cui lo raggiunge un client che lo avvia come sottoprocesso; su HTTP serve un unico endpoint, /mcp, per chiamanti su altre macchine. I suoi strumenti sono le operazioni del compilatore — leggere schemi, descrivere il workspace, validare, eseguire la build, redigere e modificare documenti — e a ogni chiamata risponde lo stesso binario eseguito dalla riga di comando.
Collega il server MCP spiega come collegare ogni client, e Che cosa può fare il tuo assistente con Aggrega spiega che cosa offrono gli strumenti.
Il daemon aggrega serve
aggrega serve esegue il compilatore come processo di lunga durata per gli editor. Mantiene tra una richiesta e l’altra i documenti analizzati, il catalogo risolto e la diagnostica, così un editor pone molte piccole domande senza pagare ogni volta il caricamento completo del catalogo.
Il protocollo è JSON-RPC 2.0 su input e output standard, con ogni messaggio preceduto da un’intestazione Content-Length e con i metodi sotto lo spazio dei nomi aggrega/. Non è il Language Server Protocol, perché trasporta operazioni per cui quel protocollo non ha posto, come la richiesta del grafo IR; un’estensione per editor traduce tra le richieste del proprio editor e questi metodi, e riusa le forme di posizione, intervallo e collocazione di quel protocollo dove si adattano. Una sessione si apre con aggrega/initialize, che riporta il workspace e la versione del binario che risponde; il daemon invia la diagnostica con aggrega/publishDiagnostics; e la notifica aggrega/shutdown la chiude in modo pulito.
Ogni corpo di messaggio è pubblicato come schema, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, descritto nel riferimento della forma dei messaggi; l’estensione per Visual Studio Code ne ricava i propri tipi di messaggio. Un altro editor si integra parlando lo stesso protocollo. Il riferimento di aggrega serve descrive ogni metodo, che cosa legge e scrive e gli errori che solleva.