Editores, assistentes e outros frontends
O Aggrega é utilizado a partir de mais de um lugar: um terminal, a extensão do Visual Studio Code, um assistente de IA ligado através do Model Context Protocol (MCP) e qualquer programa que controle o binário aggrega. Nenhum destes frontends traz um compilador próprio. Cada um executa o binário aggrega, ou chega a um que já esteja em execução, e interroga-o, pelo que a análise do YAML, a resolução do catálogo e a construção do grafo acontecem num só lugar, e o que um frontend mostra é o que esse binário compilou. Um frontend não reimplementa nada disso, pelo que não existe uma segunda cópia que possa divergir da primeira.
Este capítulo descreve o contrato que esses frontends partilham e o que cada um pede ao binário.
O grafo IR é o contrato público
Compilar uma Release, com o Aggregate e o Manifest que nomeia, produz um grafo de Representação Intermédia (IR): cada nó, com o componente que instancia, a versão para a qual esse componente foi resolvido, a fronteira e o subsistema em que se encontra e o ficheiro que o declarou; cada ligação entre nós; as Features anexadas a cada um; e os valores mapeados sobre eles, com a proveniência de cada um. É o instantâneo do que o compilador está prestes a renderizar em artefactos.
A forma do grafo é publicada como um JSON Schema, https://aggrega.ai/schemas/ir-v1beta1.schema.json, e a referência do esquema IR descreve cada campo. Um frontend lê o grafo de acordo com esse esquema, não com os detalhes internos do compilador, pelo que o esquema é o único lugar onde a forma evolui, e um frontend escrito em qualquer linguagem acompanha-a da mesma maneira.
Os valores que um autor declarou sensíveis são retidos no grafo onde quer que este seja entregue. Um frontend que precise deles em claro pede-os explicitamente, e tudo aquilo a que a resposta chegar a partir daí transporta-os em claro.
Três formas de pedir o grafo
O mesmo grafo está disponível em todas as superfícies, e cada resposta é um documento de grafo completo:
- A partir da linha de comandos.
aggrega build,aggrega inspectcom uma Release eaggrega validate --releaseaceitam cada um--ir-graph, que escreve na saída padrão, em JSON, o grafo que essa execução calculou, além de tudo o que o comando já produz.--unredactedao lado dele imprime os valores sensíveis. Consulteaggrega inspect. - A partir do daemon. Um pedido
aggrega/irGraphaoaggrega serve, que nomeia a Release pelo seu caminho relativo à raiz do espaço de trabalho, é respondido com o mesmo documento sobgraph;unredacted: truepede os valores sensíveis. Consulteaggrega serve. - A partir de um assistente de IA. As ferramentas
cli-inspect,cli-buildecli-validatedo servidor MCP recebem a opção do comando como o seu argumentoir_graph. Consulteaggrega mcp.
Cada resposta descreve a Release tal como estava quando a pergunta foi feita. Um frontend que acompanha as edições volta a perguntar: a extensão do Visual Studio Code redesenha o seu grafo sempre que um documento é guardado.
A extensão do Visual Studio Code
A extensão do Aggrega para o Visual Studio Code inicia o aggrega serve e mantém-no em execução para o espaço de trabalho. Cada resposta que mostra vem do binário aggrega: a maioria desse daemon — entre elas os diagnósticos durante a edição, o hover, a conclusão automática, ir para a definição, localizar referências, a compilação e a pré-visualização da compilação — e o resto da execução dos próprios comandos do binário.
O seu grafo de topologia é o grafo IR. A extensão envia aggrega/irGraph para a Release selecionada e desenha a resposta: fronteiras e subsistemas como contentores aninhados, componentes como nós, ligações como arestas e, num nó ou ligação selecionado, as Features anexadas a ele. O compilador envia a topologia e nunca coordenadas; a disposição é calculada no editor. Anexar uma Feature a partir do grafo também passa pelo daemon: o compilador nomeia o documento e o local dentro dele onde o anexo deve ficar, e a extensão escreve-o aí. Consulte o grafo de topologia para ver o que a vista mostra e faz.
O servidor MCP
aggrega mcp executa o binário como um servidor Model Context Protocol, pelo que um assistente de IA descobre as operações do Aggrega e chama-as em vez de ler a saída dos comandos. Pela entrada e saída padrão fala JSON-RPC 2.0 delimitado por quebras de linha, que é a forma como um cliente que o inicia como subprocesso chega até ele; por HTTP serve um único endpoint, /mcp, para chamadores noutras máquinas. As suas ferramentas são as operações do compilador — ler esquemas, descrever o espaço de trabalho, validar, compilar, redigir e editar documentos — e cada chamada é respondida pelo mesmo binário que a linha de comandos executa.
Ligar o servidor MCP explica como ligar cada cliente, e O que o seu assistente pode fazer com o Aggrega explica o que as ferramentas oferecem.
O daemon aggrega serve
aggrega serve executa o compilador como um processo de longa duração para editores. Mantém os documentos analisados, o catálogo resolvido e os diagnósticos entre pedidos, pelo que um editor faz muitas perguntas pequenas sem pagar de cada vez um carregamento completo do catálogo.
O protocolo é JSON-RPC 2.0 sobre a entrada e a saída padrão, com cada mensagem precedida por um cabeçalho Content-Length e com métodos sob o espaço de nomes aggrega/. Não é o Language Server Protocol, porque transporta operações para as quais esse protocolo não tem lugar, como o pedido do grafo IR; uma extensão de editor traduz entre os pedidos do seu editor e estes métodos, e reutiliza as formas de posição, intervalo e localização desse protocolo onde se adequam. Uma sessão abre com aggrega/initialize, que indica o espaço de trabalho e a versão do binário que responde; o daemon envia diagnósticos com aggrega/publishDiagnostics; e a notificação aggrega/shutdown termina-a de forma limpa.
Cada corpo de mensagem é publicado como um esquema, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, descrito na referência do formato das mensagens; a extensão do Visual Studio Code obtém dele os seus tipos de mensagem. Outro editor integra-se falando o mesmo protocolo. A referência do aggrega serve descreve cada método, o que lê e escreve, e os erros que gera.