Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Editores, asistentes y otros frontends

Aggrega se usa desde más de un lugar: una terminal, la extensión de Visual Studio Code, un asistente de IA conectado mediante el Model Context Protocol (MCP) y cualquier programa que controle el binario aggrega. Ninguno de estos frontends lleva un compilador propio. Cada uno ejecuta el binario aggrega, o se comunica con uno que ya está en ejecución, y le pregunta, de modo que el análisis del YAML, la resolución del catálogo y la construcción del grafo ocurren en un solo lugar, y lo que muestra un frontend es lo que ese binario compiló. Un frontend no reimplementa nada de ello, así que no hay una segunda copia que pueda desviarse de la primera.

Este capítulo describe el contrato que comparten esos frontends y lo que cada uno le pide al binario.

El grafo IR es el contrato público

Compilar una Release, con el Aggregate y el Manifest que nombra, produce un grafo de representación intermedia (IR): cada nodo, con el componente que instancia, la versión a la que se resolvió ese componente, la frontera y el subsistema en que se encuentra y el archivo que lo declaró; cada conexión entre nodos; las Features asociadas a cada uno; y los valores mapeados sobre ellos, con la procedencia de cada uno. Es la instantánea de lo que el compilador está a punto de renderizar en artefactos.

La forma del grafo se publica como JSON Schema, https://aggrega.ai/schemas/ir-v1beta1.schema.json, y la referencia del esquema IR describe cada campo. Un frontend lee el grafo según ese esquema, no según los detalles internos del compilador, así que el esquema es el único lugar donde evoluciona la forma, y un frontend escrito en cualquier lenguaje la sigue de la misma manera.

Los valores que un autor declaró sensibles se retienen en el grafo dondequiera que se entregue. Un frontend que los necesita en claro los pide explícitamente, y todo lo que alcance entonces la respuesta los lleva en claro.

Tres formas de pedir el grafo

El mismo grafo está disponible en todas las superficies, y cada respuesta es un documento de grafo completo:

  • Desde la línea de comandos. aggrega build, aggrega inspect con una Release y aggrega validate --release aceptan cada uno --ir-graph, que escribe en la salida estándar como JSON el grafo que calculó esa ejecución, además de todo lo que el comando ya produce. --unredacted junto a él imprime los valores sensibles. Consulta aggrega inspect.
  • Desde el daemon. Una solicitud aggrega/irGraph a aggrega serve, que nombra la Release por su ruta relativa a la raíz del espacio de trabajo, se responde con el mismo documento bajo graph; unredacted: true pide los valores sensibles. Consulta aggrega serve.
  • Desde un asistente de IA. Las herramientas cli-inspect, cli-build y cli-validate del servidor MCP toman el flag del comando como su argumento ir_graph. Consulta aggrega mcp.

Cada respuesta describe la Release tal como estaba cuando se hizo la pregunta. Un frontend que sigue las ediciones vuelve a preguntar: la extensión de Visual Studio Code vuelve a dibujar su grafo cada vez que se guarda un documento.

La extensión de Visual Studio Code

La extensión de Aggrega para Visual Studio Code inicia aggrega serve y lo mantiene en ejecución para el espacio de trabajo. Cada respuesta que muestra procede del binario aggrega: la mayoría de ese daemon —entre ellas los diagnósticos mientras editas, el hover, el autocompletado, ir a la definición, buscar referencias, la compilación y la vista previa de la compilación— y el resto de ejecutar los propios comandos del binario.

Su grafo de topología es el grafo IR. La extensión envía aggrega/irGraph para la Release seleccionada y dibuja la respuesta: las fronteras y los subsistemas como contenedores anidados, los componentes como nodos, las conexiones como aristas y, en un nodo o una conexión seleccionados, las Features asociadas a él. El compilador envía la topología y nunca coordenadas; la disposición se calcula en el editor. Asociar una Feature desde el grafo también pasa por el daemon: el compilador nombra el documento y el lugar dentro de él donde corresponde la asociación, y la extensión la escribe allí. Consulta el grafo de topología para ver lo que muestra y hace la vista.

El servidor MCP

aggrega mcp ejecuta el binario como servidor Model Context Protocol, de modo que un asistente de IA descubre las operaciones de Aggrega y las llama en lugar de leer la salida de los comandos. Por la entrada y la salida estándar habla JSON-RPC 2.0 delimitado por saltos de línea, que es como lo alcanza un cliente que lo inicia como subproceso; por HTTP sirve un único endpoint, /mcp, para quienes lo llaman desde otras máquinas. Sus herramientas son las operaciones del compilador —leer esquemas, describir el espacio de trabajo, validar, compilar, redactar y editar documentos— y cada llamada la responde el mismo binario que ejecuta la línea de comandos.

Conecta el servidor MCP explica cómo conectar cada cliente, y Qué puede hacer tu asistente con Aggrega explica lo que ofrecen las herramientas.

El daemon aggrega serve

aggrega serve ejecuta el compilador como un proceso de larga duración para editores. Conserva entre solicitudes los documentos analizados, el catálogo resuelto y los diagnósticos, de modo que un editor hace muchas preguntas pequeñas sin pagar cada vez una carga completa del catálogo.

El protocolo es JSON-RPC 2.0 sobre la entrada y la salida estándar, con cada mensaje precedido por una cabecera Content-Length y con métodos bajo el espacio de nombres aggrega/. No es el Language Server Protocol, porque transporta operaciones para las que ese protocolo no tiene lugar, como la solicitud del grafo IR; una extensión de editor traduce entre las solicitudes de su editor y estos métodos, y reutiliza las formas de posición, rango y ubicación de ese protocolo donde encajan. Una sesión se abre con aggrega/initialize, que informa del espacio de trabajo y de la versión del binario que responde; el daemon envía los diagnósticos con aggrega/publishDiagnostics; y la notificación aggrega/shutdown la termina limpiamente.

Cada cuerpo de mensaje se publica como esquema, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, descrito en la referencia del formato de los mensajes; la extensión de Visual Studio Code toma de él sus tipos de mensaje. Otro editor se integra hablando el mismo protocolo. La referencia de aggrega serve describe cada método, lo que lee y escribe, y los errores que genera.