Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

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 inspect dengan sebuah Release, dan aggrega validate --release masing-masing menerima --ir-graph, yang menulis graf hasil komputasi eksekusi tersebut ke keluaran standar sebagai JSON, selain semua yang sudah dihasilkan perintah. --unredacted di sampingnya mencetak nilai-nilai sensitif. Lihat aggrega inspect.
  • Dari daemon. Permintaan aggrega/irGraph ke aggrega serve, yang menyebut Release melalui path-nya relatif terhadap root workspace, dijawab dengan dokumen yang sama di bawah graph; unredacted: true meminta nilai-nilai sensitif. Lihat aggrega serve.
  • Dari asisten AI. Tool cli-inspect, cli-build, dan cli-validate milik server MCP menerima flag perintah sebagai argumen ir_graph. Lihat aggrega 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.