Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Editores, assistentes e outros frontends

O Aggrega é usado a partir de mais de um lugar: um terminal, a extensão do Visual Studio Code, um assistente de IA conectado pelo Model Context Protocol (MCP) e qualquer programa que controle o binário aggrega. Nenhum desses frontends carrega um compilador próprio. Cada um executa o binário aggrega, ou alcança um que já esteja em execução, e o consulta, de modo que a análise do YAML, a resolução do catálogo e a construção do grafo acontecem em um só lugar, e o que um frontend mostra é o que aquele binário compilou. Um frontend não reimplementa nada disso, então não existe uma segunda cópia que possa divergir da primeira.

Este capítulo descreve o contrato que esses frontends compartilham 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 ela nomeia, produz um grafo da representação intermediária (IR): cada nó, com o componente que ele instancia, a versão para a qual esse componente foi resolvido, a fronteira e o subsistema em que ele está e o arquivo que o declarou; cada conexão entre nós; as Features vinculadas a cada um; e os valores mapeados sobre eles, com a origem de cada um. É o snapshot do que o compilador está prestes a renderizar em artefatos.

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, então o esquema é o único lugar onde a forma evolui, e um frontend escrito em qualquer linguagem a acompanha da mesma maneira.

Os valores que um autor declarou sensíveis são retidos no grafo onde quer que ele seja entregue. Um frontend que precise deles em texto claro os pede explicitamente, e tudo o que a resposta alcançar a partir daí os carrega em texto 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 comando. aggrega build, aggrega inspect com uma Release e aggrega validate --release aceitam cada um --ir-graph, que grava na saída padrão, como JSON, o grafo calculado por aquela execução, além de tudo o que o comando já produz. --unredacted ao lado dele imprime os valores sensíveis. Consulte aggrega inspect.
  • A partir do daemon. Uma solicitação aggrega/irGraph ao aggrega serve, que nomeia a Release pelo seu caminho relativo à raiz do workspace, é respondida com o mesmo documento sob graph; unredacted: true pede os valores sensíveis. Consulte aggrega serve.
  • A partir de um assistente de IA. As ferramentas cli-inspect, cli-build e cli-validate do servidor MCP recebem o flag do comando como seu argumento ir_graph. Consulte aggrega mcp.

Cada resposta descreve a Release como ela estava quando a pergunta foi feita. Um frontend que acompanha edições pergunta de novo: a extensão do Visual Studio Code redesenha o seu grafo cada vez que um documento é salvo.

A extensão do Visual Studio Code

A extensão do Aggrega para o Visual Studio Code inicia o aggrega serve e o mantém em execução para o workspace. Cada resposta que ela mostra vem do binário aggrega: a maioria daquele daemon — entre elas os diagnósticos enquanto você edita, hover, autocompletar, ir para a definição, localizar referências, build e pré-visualização do build — e o restante da execução dos próprios comandos do binário.

O grafo de topologia dela é o grafo IR. A extensão envia aggrega/irGraph para a Release selecionada e desenha a resposta: fronteiras e subsistemas como contêineres aninhados, componentes como nós, conexões como arestas e, em um nó ou conexão selecionado, as Features vinculadas a ele. O compilador envia a topologia e nunca coordenadas; o layout é calculado no editor. Vincular uma Feature a partir do grafo também passa pelo daemon: o compilador nomeia o documento e o lugar dentro dele onde a vinculação deve ficar, e a extensão a escreve ali. Consulte o grafo de topologia para ver o que a visualização mostra e faz.

O servidor MCP

aggrega mcp executa o binário como um servidor Model Context Protocol, de modo que um assistente de IA descobre as operações do Aggrega e as chama em vez de ler a saída dos comandos. Pela entrada e saída padrão ele fala JSON-RPC 2.0 delimitado por quebras de linha, que é como um cliente que o inicia como subprocesso o alcança; por HTTP ele serve um único endpoint, /mcp, para chamadores em outras máquinas. Suas ferramentas são as operações do compilador — ler esquemas, descrever o workspace, validar, compilar, redigir e editar documentos — e cada chamada é respondida pelo mesmo binário que a linha de comando executa.

Conecte o servidor MCP explica como conectar 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. Ele mantém os documentos analisados, o catálogo resolvido e os diagnósticos entre as solicitações, de modo que um editor faz muitas perguntas pequenas sem pagar por um carregamento completo do catálogo a cada vez.

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 namespace aggrega/. Não é o Language Server Protocol, porque carrega operações para as quais esse protocolo não tem lugar, como a solicitação do grafo IR; uma extensão de editor traduz entre as solicitações do seu editor e esses métodos, e reutiliza as formas de posição, intervalo e localização desse protocolo onde elas se encaixam. Uma sessão começa com aggrega/initialize, que informa o workspace e a versão do binário que responde; o daemon envia diagnósticos com aggrega/publishDiagnostics; e a notificação aggrega/shutdown a encerra 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 se integra falando o mesmo protocolo. A referência do aggrega serve descreve cada método, o que ele lê e grava, e os erros que ele gera.