Editor, asisten, dan frontend lainnya
Aggrega digunakan dari lebih dari satu tempat: terminal, ekstensi Visual Studio Code, asisten AI yang terhubung melalui Model Context Protocol (MCP), dan program apa pun yang mengendalikan biner aggrega. Tidak satu pun dari frontend ini membawa kompilernya sendiri. Masing-masing menjalankan biner aggrega, atau menjangkau biner yang sudah berjalan, lalu mengajukan permintaan kepadanya, sehingga parsing YAML, resolusi katalog, dan pembangunan graf terjadi di satu tempat, dan apa yang ditampilkan frontend adalah apa yang dikompilasi biner tersebut. Frontend tidak mengimplementasikan ulang satu pun darinya, sehingga tidak ada salinan kedua yang dapat menyimpang dari yang pertama.
Bab ini menjelaskan kontrak yang digunakan bersama oleh frontend tersebut, dan apa yang diminta masing-masing dari biner.
Graf IR adalah kontrak publik
Mengompilasi sebuah Release, bersama Aggregate dan Manifest yang dirujuknya, menghasilkan graf representasi perantara (IR): setiap node, beserta komponen yang diinstansiasinya, versi tempat komponen itu di-resolve, batas dan subsistem tempatnya berada, serta berkas yang mendeklarasikannya; setiap koneksi antar-node; Features yang dilampirkan pada masing-masing; dan nilai yang dipetakan ke sana, beserta asal masing-masing nilai. Graf ini adalah snapshot dari apa yang akan segera di-render kompiler menjadi artefak.
Bentuk graf dipublikasikan sebagai JSON Schema, https://aggrega.ai/schemas/ir-v1beta1.schema.json, dan referensi skema IR menjelaskan setiap field-nya. Frontend membaca graf berdasarkan skema tersebut, bukan berdasarkan internal kompiler, sehingga skema menjadi satu-satunya tempat bentuk itu berevolusi, dan frontend yang ditulis dalam bahasa apa pun mengikutinya dengan cara yang sama.
Nilai yang dideklarasikan sensitif oleh penulis disembunyikan dari graf di mana pun graf itu diserahkan. Frontend yang membutuhkan nilai tersebut dalam bentuk teks biasa memintanya secara eksplisit, dan apa pun yang kemudian dijangkau oleh jawaban tersebut akan membawanya dalam bentuk teks biasa.
Tiga cara meminta graf
Graf yang sama tersedia di setiap antarmuka, dan setiap jawaban adalah satu dokumen graf yang lengkap:
- Dari baris perintah.
aggrega build,aggrega inspectdengan sebuah Release, danaggrega validate --releasemasing-masing menerima--ir-graph, yang menulis graf hasil komputasi eksekusi tersebut ke keluaran standar sebagai JSON, selain semua yang sudah dihasilkan perintah.--unredacteddi sampingnya mencetak nilai-nilai sensitif. Lihataggrega inspect. - Dari daemon. Permintaan
aggrega/irGraphkeaggrega serve, yang menyebut Release melalui path-nya relatif terhadap root workspace, dijawab dengan dokumen yang sama di bawahgraph;unredacted: truememinta nilai-nilai sensitif. Lihataggrega serve. - Dari asisten AI. Tool
cli-inspect,cli-build, dancli-validatemilik server MCP menerima flag perintah sebagai argumenir_graph. Lihataggrega mcp.
Setiap jawaban menggambarkan Release sebagaimana keadaannya saat pertanyaan diajukan. Frontend yang mengikuti pengeditan bertanya lagi: ekstensi Visual Studio Code menggambar ulang grafnya setiap kali dokumen disimpan.
Ekstensi Visual Studio Code
Ekstensi Aggrega untuk Visual Studio Code menjalankan aggrega serve dan membuatnya tetap berjalan untuk workspace. Setiap jawaban yang ditampilkannya berasal dari biner aggrega: sebagian besar dari daemon itu — di antaranya diagnostik saat Anda mengedit, hover, pelengkapan, pergi ke definisi, cari referensi, build, dan pratinjau build — dan sisanya dari menjalankan perintah biner itu sendiri.
Graf topologinya adalah graf IR. Ekstensi mengirim aggrega/irGraph untuk Release yang dipilih dan menggambar jawabannya: batas dan subsistem sebagai kontainer bersarang, komponen sebagai node, koneksi sebagai edge, dan, pada node atau koneksi yang dipilih, Features yang dilampirkan padanya. Kompiler mengirim topologi dan tidak pernah mengirim koordinat; tata letak dihitung di editor. Melampirkan Feature dari graf juga melewati daemon: kompiler menyebut dokumen dan tempat di dalamnya tempat lampiran itu seharusnya berada, dan ekstensi menuliskannya di sana. Lihat graf topologi untuk apa yang ditampilkan dan dilakukan tampilan tersebut.
Server MCP
aggrega mcp menjalankan biner sebagai server Model Context Protocol, sehingga asisten AI menemukan operasi Aggrega dan memanggilnya alih-alih membaca keluaran perintah. Melalui masukan dan keluaran standar, server ini berbicara JSON-RPC 2.0 yang dipisahkan baris baru, yang merupakan cara klien yang menjalankannya sebagai subproses menjangkaunya; melalui HTTP, server ini melayani satu endpoint, /mcp, untuk pemanggil di mesin lain. Tool-nya adalah operasi kompiler — membaca skema, mendeskripsikan workspace, memvalidasi, membangun, membuat draf dan mengedit dokumen — dan setiap panggilan dijawab oleh biner yang sama yang dijalankan baris perintah.
Menghubungkan server MCP membahas cara menghubungkan setiap klien, dan Apa yang dapat dilakukan asisten Anda dengan Aggrega membahas apa yang ditawarkan tool-tool tersebut.
Daemon aggrega serve
aggrega serve menjalankan kompiler sebagai proses yang berjalan lama untuk editor. Proses ini menyimpan dokumen yang telah di-parse, katalog yang telah di-resolve, dan diagnostik di antara permintaan, sehingga editor dapat mengajukan banyak pertanyaan kecil tanpa menanggung biaya pemuatan katalog penuh setiap kali.
Protokolnya adalah JSON-RPC 2.0 melalui masukan dan keluaran standar, dengan setiap pesan didahului header Content-Length, dan metode berada di bawah namespace aggrega/. Protokol ini bukan Language Server Protocol, karena membawa operasi yang tidak memiliki tempat dalam protokol tersebut, seperti permintaan graf IR; ekstensi editor menerjemahkan antara permintaan editornya dan metode-metode ini, serta menggunakan kembali bentuk posisi, rentang, dan lokasi dari protokol tersebut jika sesuai. Sesi dibuka dengan aggrega/initialize, yang melaporkan workspace dan versi biner yang menjawab; daemon mendorong diagnostik dengan aggrega/publishDiagnostics; dan notifikasi aggrega/shutdown mengakhirinya dengan bersih.
Setiap badan pesan dipublikasikan sebagai skema, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, yang dijelaskan dalam referensi format wire; ekstensi Visual Studio Code mengambil tipe pesannya dari skema itu. Editor lain berintegrasi dengan menggunakan protokol yang sama. Referensi aggrega serve menjelaskan setiap metode, apa yang dibaca dan ditulisnya, serta galat yang dimunculkannya.