Düzenleyiciler, asistanlar ve diğer ön uçlar
Aggrega birden fazla yerden kullanılır: bir terminal, Visual Studio Code uzantısı, Model Context Protocol (MCP) üzerinden bağlanan bir yapay zekâ asistanı ve aggrega ikili dosyasını yöneten herhangi bir program. Bu ön uçların hiçbiri kendi derleyicisini taşımaz. Her biri aggrega ikili dosyasını çalıştırır ya da zaten çalışan birine ulaşır ve ona sorar; böylece YAML ayrıştırma, kataloğu çözümleme ve grafiği oluşturma tek bir yerde gerçekleşir ve bir ön ucun gösterdiği, o ikili dosyanın derlediği şeydir. Bir ön uç bunların hiçbirini yeniden uygulamaz; bu yüzden birinciden sapacak ikinci bir kopya yoktur.
Bu bölüm, bu ön uçların paylaştığı sözleşmeyi ve her birinin ikili dosyadan ne istediğini açıklar.
IR grafiği herkese açık sözleşmedir
Bir Release’i, adını verdiği Aggregate ve Manifest ile birlikte derlemek bir ara temsil (IR) grafiği üretir: örneklediği bileşen, o bileşenin çözümlendiği sürüm, içinde bulunduğu sınır ve alt sistem ve onu bildiren dosyayla birlikte her düğüm; düğümler arasındaki her bağlantı; her birine eklenen Features; ve bunlara eşlenen değerler, her birinin nereden geldiğiyle birlikte. Bu, derleyicinin yapıtlara dönüştürmek üzere olduğu şeyin anlık görüntüsüdür.
Grafiğin yapısı bir JSON Schema olarak yayımlanır, https://aggrega.ai/schemas/ir-v1beta1.schema.json, ve IR şeması başvurusu her alanı açıklar. Bir ön uç grafiği derleyicinin iç yapısına göre değil, bu şemaya göre okur; bu nedenle şema, yapının geliştiği tek yerdir ve herhangi bir dilde yazılmış bir ön uç onu aynı şekilde izler.
Bir yazarın hassas olarak bildirdiği değerler, grafik nereye verilirse verilsin grafikte gizlenir. Bunlara açık metin olarak ihtiyaç duyan bir ön uç bunları açıkça ister ve ardından yanıt nereye ulaşırsa ulaşsın, onları açık metin olarak taşır.
Grafiği istemenin üç yolu
Aynı grafik her yüzeyde kullanılabilir ve her yanıt tek ve eksiksiz bir grafik belgesidir:
- Komut satırından.
aggrega build, bir Release verildiğindeaggrega inspectveaggrega validate --releasekomutlarının her biri--ir-graphseçeneğini kabul eder; bu seçenek, komutun zaten ürettiği her şeye ek olarak o çalıştırmanın hesapladığı grafiği JSON olarak standart çıktıya yazar. Yanında verilen--unredactedhassas değerleri yazdırır. Bkz.aggrega inspect. - Daemon’dan.
aggrega serve’e gönderilen ve Release’i çalışma alanı köküne göreli yoluyla belirten biraggrega/irGraphisteği, aynı belgeyigraphaltında yanıt olarak döndürür;unredacted: truehassas değerleri ister. Bkz.aggrega serve. - Bir yapay zekâ asistanından. MCP sunucusunun
cli-inspect,cli-buildvecli-validatearaçları, komutun seçeneğiniir_graphbağımsız değişkeni olarak alır. Bkz.aggrega mcp.
Her yanıt, Release’i sorunun sorulduğu andaki hâliyle açıklar. Düzenlemeleri izleyen bir ön uç yeniden sorar: Visual Studio Code uzantısı, bir belge her kaydedildiğinde grafiğini yeniden çizer.
Visual Studio Code uzantısı
Visual Studio Code için Aggrega uzantısı aggrega serve’i başlatır ve çalışma alanı için çalışır durumda tutar. Gösterdiği her yanıt aggrega ikili dosyasından gelir: çoğu o daemon’dan — aralarında düzenleme sırasında tanılamalar, üzerine gelince bilgi, tamamlama, tanıma git, başvuruları bul, derleme ve önizleme derlemesi vardır — geri kalanı ise ikili dosyanın kendi komutlarını çalıştırmaktan gelir.
Topoloji grafiği IR grafiğidir. Uzantı, seçili Release için aggrega/irGraph gönderir ve yanıtı çizer: sınırlar ve alt sistemler iç içe kapsayıcılar olarak, bileşenler düğümler olarak, bağlantılar kenarlar olarak ve seçili bir düğümde ya da bağlantıda ona eklenmiş Features. Derleyici topolojiyi gönderir, koordinatları asla göndermez; yerleşim düzenleyicide hesaplanır. Grafikten bir Feature eklemek de daemon üzerinden geri gider: derleyici eklemenin ait olduğu belgeyi ve onun içindeki yeri belirtir, uzantı da onu oraya yazar. Görünümün ne gösterdiği ve ne yaptığı için bkz. topoloji grafiği.
MCP sunucusu
aggrega mcp, ikili dosyayı bir Model Context Protocol sunucusu olarak çalıştırır; böylece bir yapay zekâ asistanı komut çıktısını okumak yerine Aggrega’nın işlemlerini keşfeder ve onları çağırır. Standart girdi ve çıktı üzerinden satır sonuyla ayrılmış JSON-RPC 2.0 konuşur; onu bir alt süreç olarak başlatan bir istemci ona bu şekilde ulaşır. HTTP üzerinden ise diğer makinelerdeki çağıranlar için tek bir uç nokta, /mcp, sunar. Araçları derleyicinin işlemleridir — şemaları okuma, çalışma alanını tanımlama, doğrulama, derleme, belge taslağı oluşturma ve düzenleme — ve her çağrıyı, komut satırının çalıştırdığı aynı ikili dosya yanıtlar.
MCP sunucusunu bağlayın her istemcinin bağlanmasını, Asistanınızın Aggrega ile yapabilecekleri ise araçların sunduklarını ele alır.
aggrega serve daemon’ı
aggrega serve, derleyiciyi düzenleyiciler için uzun süre çalışan bir süreç olarak çalıştırır. Ayrıştırılmış belgeleri, çözümlenmiş kataloğu ve tanılamaları istekler boyunca tutar; böylece bir düzenleyici her seferinde tam bir katalog yüklemesinin bedelini ödemeden çok sayıda küçük soru sorabilir.
Protokol, standart girdi ve çıktı üzerinden JSON-RPC 2.0’dır; her iletinin önünde bir Content-Length başlığı bulunur ve yöntemler aggrega/ ad alanı altındadır. Bu, Language Server Protocol değildir, çünkü IR grafiği isteği gibi o protokolde yeri olmayan işlemleri taşır; bir düzenleyici uzantısı, kendi düzenleyicisinin istekleri ile bu yöntemler arasında çeviri yapar ve uygun düştüğü yerlerde o protokolün konum (position), aralık (range) ve yer (location) yapılarını yeniden kullanır. Bir oturum, çalışma alanını ve yanıt veren ikili dosyanın sürümünü bildiren aggrega/initialize ile açılır; daemon tanılamaları aggrega/publishDiagnostics ile gönderir; aggrega/shutdown bildirimi ise oturumu temiz bir şekilde sonlandırır.
Her ileti gövdesi bir şema olarak yayımlanır, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, ve iletim biçimi başvurusunda açıklanır; Visual Studio Code uzantısı ileti türlerini buradan alır. Başka bir düzenleyici aynı protokolü konuşarak entegre olur. aggrega serve başvurusu her yöntemi, neyi okuyup yazdığını ve hangi hataları ürettiğini açıklar.