エディタ、アシスタント、その他のフロントエンド
Aggrega は複数の場所から使われます。ターミナル、Visual Studio Code 拡張機能、Model Context Protocol(MCP)を通じて接続された AI アシスタント、そして aggrega バイナリを駆動するあらゆるプログラムです。これらのフロントエンドはいずれも独自のコンパイラを持ちません。各フロントエンドは aggrega バイナリを実行するか、すでに実行中のバイナリに接続して問い合わせます。そのため、YAML の解析、カタログの解決、グラフの構築は 1 か所で行われ、フロントエンドが表示するものはそのバイナリがコンパイルしたものです。フロントエンドはそのどれも再実装しないため、最初のものから乖離する 2 つ目のコピーは存在しません。
この章では、これらのフロントエンドが共有するコントラクトと、それぞれがバイナリに何を要求するかを説明します。
IR グラフは公開コントラクト
Release を、それが指定する Aggregate および Manifest とともにコンパイルすると、中間表現(IR)グラフが生成されます。このグラフには、すべてのノード(インスタンス化するコンポーネント、そのコンポーネントが解決されたバージョン、配置されている境界とサブシステム、それを宣言したファイルを含む)、ノード間のすべての接続、それぞれにアタッチされた Features、そしてそれらにマッピングされた値とそれぞれの出所が含まれます。これは、コンパイラがこれからアーティファクトへレンダリングしようとする内容のスナップショットです。
グラフの形は JSON Schema https://aggrega.ai/schemas/ir-v1beta1.schema.json として公開されており、IR スキーマリファレンスがすべてのフィールドを説明しています。フロントエンドはコンパイラの内部ではなくそのスキーマに照らしてグラフを読むため、スキーマが形の変化する唯一の場所となり、どの言語で書かれたフロントエンドも同じ方法でそれに追従します。
作成者が機密と宣言した値は、グラフが渡されるあらゆる場所で伏せられます。それらを平文で必要とするフロントエンドは明示的に要求し、その場合、応答が届く先ではどこでも平文で保持されます。
グラフを要求する 3 つの方法
同じグラフがすべてのサーフェスで利用でき、各応答は 1 つの完全なグラフドキュメントです:
- コマンドラインから。
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 上では、他のマシンの呼び出し元向けに 1 つのエンドポイント /mcp を提供します。ツールはコンパイラの操作 — スキーマの読み取り、ワークスペースの記述、検証、ビルド、ドキュメントの下書きと編集 — であり、各呼び出しにはコマンドラインが実行するのと同じバイナリが応答します。
MCP サーバーの接続では各クライアントの接続方法を、アシスタントが Aggrega でできることではツールが提供する機能を説明しています。
aggrega serve デーモン
aggrega serve は、エディタ向けにコンパイラを長時間実行プロセスとして実行します。解析済みのドキュメント、解決済みのカタログ、診断をリクエスト間で保持するため、エディタは毎回カタログ全体を読み込むコストを払うことなく、多数の小さな問い合わせを行えます。
プロトコルは標準入出力上の JSON-RPC 2.0 で、各メッセージの前に Content-Length ヘッダーが付き、メソッドは aggrega/ 名前空間の下にあります。これは Language Server Protocol ではありません。IR グラフのリクエストのように、そのプロトコルには居場所のない操作を運ぶためです。エディタ拡張機能は、エディタのリクエストとこれらのメソッドとの間を変換し、適合する箇所ではそのプロトコルの位置、範囲、ロケーションの形を再利用します。セッションは aggrega/initialize で開始され、ワークスペースと応答するバイナリのバージョンを報告します。デーモンは aggrega/publishDiagnostics で診断をプッシュします。そして aggrega/shutdown 通知がセッションを正常に終了させます。
すべてのメッセージ本文はスキーマ https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json として公開されており、ワイヤー形式リファレンスで説明されています。Visual Studio Code 拡張機能はメッセージ型をそこから取得しています。他のエディタは同じプロトコルを話すことで統合できます。aggrega serve リファレンスでは、各メソッド、その読み書きする内容、発生させるエラーを説明しています。