콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

편집기, 어시스턴트 및 기타 프런트엔드

Aggrega는 여러 곳에서 사용됩니다. 터미널, Visual Studio Code 확장, Model Context Protocol(MCP)을 통해 연결된 AI 어시스턴트, 그리고 aggrega 바이너리를 구동하는 모든 프로그램입니다. 이 프런트엔드 중 어느 것도 자체 컴파일러를 갖고 있지 않습니다. 각 프런트엔드는 aggrega 바이너리를 실행하거나 이미 실행 중인 바이너리에 접속해 질의합니다. 따라서 YAML 구문 분석, 카탈로그 해석, 그래프 구축은 한곳에서 이루어지며, 프런트엔드가 보여 주는 것은 그 바이너리가 컴파일한 결과입니다. 프런트엔드는 그 어느 것도 다시 구현하지 않으므로, 원본에서 어긋날 두 번째 사본이 존재하지 않습니다.

이 장에서는 이러한 프런트엔드가 공유하는 계약과, 각 프런트엔드가 바이너리에 무엇을 요청하는지 설명합니다.

IR 그래프는 공개 계약입니다

Release를 그것이 지정하는 Aggregate 및 Manifest와 함께 컴파일하면 중간 표현(IR) 그래프가 생성됩니다. 이 그래프에는 모든 노드(노드가 인스턴스화하는 컴포넌트, 그 컴포넌트가 해석된 버전, 노드가 속한 경계와 하위 시스템, 노드를 선언한 파일 포함), 노드 사이의 모든 연결, 각 노드에 부착된 Features, 그리고 이들에 매핑된 값과 각 값의 출처가 담깁니다. 이는 컴파일러가 아티팩트로 렌더링하려는 내용의 스냅샷입니다.

그래프의 형태는 JSON Schema https://aggrega.ai/schemas/ir-v1beta1.schema.json으로 게시되며, IR 스키마 참조에서 모든 필드를 설명합니다. 프런트엔드는 컴파일러 내부가 아니라 이 스키마를 기준으로 그래프를 읽으므로, 스키마가 형태가 발전하는 유일한 곳이 되고, 어떤 언어로 작성된 프런트엔드든 같은 방식으로 이를 따라갑니다.

작성자가 민감하다고 선언한 값은 그래프가 전달되는 모든 곳에서 숨겨집니다. 이 값을 평문으로 필요로 하는 프런트엔드는 명시적으로 요청하며, 그러면 그 응답이 전달되는 모든 곳에 값이 평문으로 담깁니다.

그래프를 요청하는 세 가지 방법

같은 그래프를 모든 표면에서 사용할 수 있으며, 각 응답은 하나의 완전한 그래프 문서입니다:

  • 명령줄에서. aggrega build, Release가 주어진 aggrega inspect, 그리고 aggrega validate --release는 각각 --ir-graph를 받으며, 이 플래그는 명령이 원래 생성하는 모든 출력에 더해 해당 실행이 계산한 그래프를 JSON으로 표준 출력에 기록합니다. 함께 지정한 --unredacted는 민감한 값을 출력합니다. aggrega inspect를 참조하십시오.
  • 데몬에서. aggrega serve에 보내는 aggrega/irGraph 요청에서 작업 공간 루트에 대한 상대 경로로 Release를 지정하면, 같은 문서가 graph 아래에 담겨 응답됩니다. unredacted: true는 민감한 값을 요청합니다. aggrega serve를 참조하십시오.
  • AI 어시스턴트에서. MCP 서버의 cli-inspect, cli-build, cli-validate 도구는 명령의 플래그를 ir_graph 인수로 받습니다. aggrega mcp를 참조하십시오.

각 응답은 질문한 시점의 Release를 설명합니다. 편집을 따라가는 프런트엔드는 다시 요청합니다. Visual Studio Code 확장은 문서가 저장될 때마다 그래프를 다시 그립니다.

Visual Studio Code 확장

Visual Studio Code용 Aggrega 확장은 aggrega serve를 시작하고 작업 공간을 위해 계속 실행합니다. 확장이 보여 주는 모든 응답은 aggrega 바이너리에서 나옵니다. 대부분은 그 데몬에서 오며 — 편집 중 진단, 호버, 자동 완성, 정의로 이동, 참조 찾기, 빌드와 미리 보기 빌드 등이 포함됩니다 — 나머지는 바이너리 자체의 명령을 실행해서 얻습니다.

확장의 토폴로지 그래프는 IR 그래프입니다. 확장은 선택한 Release에 대해 aggrega/irGraph를 보내고 응답을 그립니다. 경계와 하위 시스템은 중첩된 컨테이너로, 컴포넌트는 노드로, 연결은 엣지로 그리며, 선택한 노드나 연결에는 거기에 부착된 Features를 표시합니다. 컴파일러는 토폴로지를 보낼 뿐 좌표는 보내지 않으며, 레이아웃은 편집기에서 계산됩니다. 그래프에서 Feature를 부착하는 작업도 데몬을 거칩니다. 컴파일러가 부착이 속할 문서와 그 안의 위치를 지정하면, 확장이 그곳에 기록합니다. 뷰가 보여 주는 내용과 기능은 토폴로지 그래프를 참조하십시오.

MCP 서버

aggrega mcp는 바이너리를 Model Context Protocol 서버로 실행하므로, AI 어시스턴트는 명령 출력을 읽는 대신 Aggrega의 작업을 발견하고 호출합니다. 표준 입출력에서는 줄바꿈으로 구분된 JSON-RPC 2.0으로 통신하며, 이를 하위 프로세스로 시작하는 클라이언트는 이 방식으로 접근합니다. HTTP에서는 다른 컴퓨터의 호출자를 위해 엔드포인트 하나, /mcp를 제공합니다. 도구는 컴파일러의 작업이며 — 스키마 읽기, 작업 공간 설명, 검증, 빌드, 문서 초안 작성과 편집 — 각 호출에는 명령줄이 실행하는 것과 같은 바이너리가 응답합니다.

MCP 서버 연결에서는 각 클라이언트를 연결하는 방법을, 어시스턴트가 Aggrega로 할 수 있는 일에서는 도구가 제공하는 기능을 다룹니다.

aggrega serve 데몬

aggrega serve는 편집기를 위해 컴파일러를 장기 실행 프로세스로 실행합니다. 구문 분석된 문서, 해석된 카탈로그, 진단을 요청 간에 유지하므로, 편집기는 매번 전체 카탈로그를 로드하는 비용을 치르지 않고 작은 질문을 많이 할 수 있습니다.

프로토콜은 표준 입출력 위의 JSON-RPC 2.0이며, 각 메시지 앞에 Content-Length 헤더가 붙고 메서드는 aggrega/ 네임스페이스 아래에 있습니다. 이는 Language Server Protocol이 아닙니다. IR 그래프 요청처럼 그 프로토콜에는 자리가 없는 작업을 전달하기 때문입니다. 편집기 확장은 해당 편집기의 요청과 이 메서드들 사이를 변환하며, 맞는 곳에서는 그 프로토콜의 위치(position), 범위(range), 로케이션(location) 형태를 재사용합니다. 세션은 aggrega/initialize로 시작하며, 이는 작업 공간과 응답하는 바이너리의 버전을 보고합니다. 데몬은 aggrega/publishDiagnostics로 진단을 푸시하고, aggrega/shutdown 알림이 세션을 깔끔하게 종료합니다.

모든 메시지 본문은 스키마 https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json으로 게시되며 와이어 형태 참조에서 설명합니다. Visual Studio Code 확장은 메시지 타입을 여기서 가져옵니다. 다른 편집기는 같은 프로토콜을 사용하여 통합합니다. aggrega serve 참조는 각 메서드와 그것이 읽고 쓰는 내용, 발생시키는 오류를 설명합니다.