İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Dilin durumu

Bu sayfa, hangi Aggrega yüzeylerinin bugün kullanılabilir olduğu, hangilerinin belgelenmiş ancak derleyici tarafından henüz işlenmediği ve hangilerinin gelecekteki bir yineleme için planlandığı konusunda temel başvuru kaynağıdır. Dil genelindeki hazırlık durumunu tek bir yerde göstererek alana özgü bölümleri tamamlar.

Bu sayfaya iki okuyucu kitlesi başvurur. İlk kez yazanlar, tanımadıkları bir yüzeye karşı yazmadan önce, o yüzeyin bugün işlenmiş çıktı ürettiğini doğrulamak için sayfayı kontrol eder. Başvuru arayanlar, kullandıkları bir yüzey beklenmedik şekilde davrandığında sayfayı kontrol eder; örneğin YAML doğrulamadan geçtiği hâlde hiçbir çıktı üretilmediğinde, yüzeyin durumuna bakılacak ilk yer bu sayfadır. Geri dönen okuyucular da son okumalarından bu yana durum etiketleri arasında geçiş yapmış yüzeyleri belirlemek için sayfaya başvurur. Alana özgü bölümler ve varlık başvuruları yüzeyin nasıl çalışması gerektiğini açıklar; bu sayfa ise henüz çalışıp çalışmadığını açıklar.

Durum sınıflandırması

Bu sayfadaki her dil yüzeyi dört durum etiketinden birini taşır:

  • available (kullanılabilir). Şema yüzeyi kabul eder; derleyici onu işler; davranış belgelenen sözleşmeyle eşleşir. available bir yüzeyi kullanan yazarlar belgelenen sözleşmeyi alır.

  • accepted but inert (kabul edilmiş ancak etkisiz). Şema yüzeyi kabul eder (ona karşı yazılan içerik doğrulamadan geçer), ancak derleyici henüz ona göre işlem yapmaz. accepted but inert bir yüzey yazmak, söz konusu yüzey için oluşturulmuş hiçbir etkisi olmayan, sözdizimsel olarak geçerli bir derleme üretir; derleyici etkisiz yüzeyi adlandıran bir uyarı verebilir (önerilen kalıp budur) ya da mevcut bazı yüzeyler uyarı vermeden sessizce atlanır. Aşağıdaki bölüm girdileri belirli davranışı adlandırır.

  • accepted but blocked (kabul edilmiş ancak engellenmiş). Şema yüzeyi kabul eder (ona karşı yazılan içerik doğrulamadan geçer), ancak derleyici onu oluşturmak yerine derlemeyi durdurur. accepted but blocked bir yüzeye karşı yazılan içerik, oluşturma aşamasında bunun yerine ne yazılması gerektiğini belirten açık bir hatayla başarısız olur. Bir engel kalıcı olabilir: bu durumda yazılan şey, derleyicinin sizin adınıza çözmeyeceği bir belirsizliktir, çünkü sizin için tek bir yorumu seçmek istemediğiniz bir şeyin teslim edilmesine yol açabilir; ya da engel yalnızca yüzeyin arkasındaki davranış kullanıma sunulana kadar sürebilir. Etiketin vaat ettiği her iki durumda da aynıdır: şema onu kabul eder, derleme onu reddeder ve hata size nasıl düzelteceğinizi söyler.

  • planned (planlanmış). Yüzey tasarlandığı şekliyle belgelenmiştir, ancak henüz ne şema ne de derleyici onu kabul eder. planned bir yüzeye karşı yazılan içerik şema doğrulamasında başarısız olur. Sayfa, yazarların eksikliği derleme sırasında keşfetmek yerine bu yokluğa göre plan yapabilmeleri için planlanmış öğeleri gösterir.

Durum etiketleri mevcut derleyiciye göre değerlendirilir. Etkin geliştirme altındaki yüzeyler etiketler arasında geçiş yapabilir; bilinen bir geçiş planı varsa bölüm girdileri bunu açıklar.

Recipe girdi türleri

Bir Recipe, çıktısını üç girdi türünden oluşturur — kaynaklı, sentezlenmiş ve yapıtlar — bunlar 16-recipe-input-composition.md içinde açıklanır. Girdi türüne göre durum:

  • source: + valuesMapping: (kaynaklı) — available. Derleyici source: URI’sini çözümler, valuesMapping şablonunu (satır içi, dosya $import: veya kütüphane $import:) değerlendirir ve sonucu işleme için hedef provider’a iletir. helm, helm-chart, compose, terraform ve cloudformation provider’ları tarafından tüketilir.

  • workload: (sentezlenmiş) — available. Recipe, workload: alanını ya satır içi (Workload YAML’ını taşıyan blok skaler) ya da $import: (dosya yolu) aracılığıyla bildirir. Derleyici şablonlanmış Workload’u ayrıştırır, gömülü Workload şemasına göre doğrular ve hedef provider’ın workload sentezleyicisine yönlendirir. helm ve compose provider’ları tarafından tüketilir. helm-chart provider’ı, sentezlenmiş K8s manifest’leri için yazarları açıkça helm provider’ına yönlendirir. Workload sentezini uygulamayan bir provider’a karşı workload: bildiren bir Recipe, işleme sırasında bir CATALOG_ERROR ile durur.

  • artifacts: (yapıtlar) — available. Alan, adlandırılmış girdilerden oluşan bir eşlemdir; her girdi satır içi yazılır veya girdi başına $import: ile yüklenir. Girdiler, Workload ayrıştırıldıktan ve kaynak çözümlendikten sonra değerlendirilir; böylece .workload ve .source dahil tüm şablon bağlamı onlar için kullanılabilir olur; metadata taşıyan belgelerde köken bilgisi metadata.labels ve metadata.annotations içine birleştirilir (karakter kümesi açısından güvensiz anahtarlar — recipe-uri, boundary-path, sync-wave — helm provider’larının uyguladığı ayrımın aynısıyla annotation olarak) ve Recipe’nin kaynaktan işlenmiş veya workload’dan sentezlenmiş çıktısının yanında ayrı dosyalar olarak üretilir. Provider’a göre dağıtım — düz helm provider’ı, bağımsız dosyaları sınır çıktı dizininin içinde, onları bildiren component’in adını taşıyan bir dizin altına üretir, çünkü anahtar dosyayı adlandırır ama onu hangi component’in yazdığı hakkında bir şey söylemez; compose provider’ı ürettiklerini Release sonundaki birleştirici üzerinden yönlendirir; helm-chart provider’ı her girdiyi [[ ]] Aggrega sınırlayıcılarıyla değerlendirir, böylece aynı dosyadaki Helm’in {{ }} sözdizimi sonraki işlemeye kadar korunur, ardından her girdiyi yazıldığı biçime göre yerleştirir — $import: ile yüklenen bir girdiyi boundaries/<bp>/charts/<nodeID>/templates/<authored-key> konumuna (bir paketin dosyaları bu anahtarın altına iç içe), kaynaklı chart’ın kendi şablonlarının yanına; satır içi içerikli bir girdiyi ise chart kökü olan boundaries/<bp>/charts/<nodeID>/<authored-key> konumuna yerleştirir; chart’ın kendi şablonları onu buradan .Files.Get / .Files.Glob ile okur; terraform provider’ı her girdiyi olduğu gibi, sınırın modules/ ağacı altındaki component’in kendi dizinine yazar; cloudformation provider’ı ise bir yığın parçası olan her girdiyi, o çıktı dizini için birleştirilen tek yığına katar. Girdi türü kökenleri arasındaki dosya adı çakışmaları (kaynaktan işlenmiş, workload’dan sentezlenmiş veya yapıt olarak üretilmiş çıktı), işleme sırasında kökenler arası çakışma algılayıcısı tarafından yakalanır ve her katkıda bulunanı adlandıran bir CATALOG_ERROR üretir.

Recipe yazım yüzeyi ve girdi türü oluşturma kuralları için entities/recipe.md; Recipe biçim kuralları için errors/fatal-halts.md; provider başına matris için ise aşağıdaki Providers bölümüne bakın.

Eşleme dilleri

Recipes (ve FeatureRecipes), Aggrega bağlamını alttaki provider’ın tükettiği values sözlüğüne çevirmek için tek bir eşleme alanına bağlanır. valuesMapping: alanı, içerik biçimine göre seçilen üç yazım modunu destekler:

  • valuesMapping: — Mod 1-3 kullanılabilir. Mod 1: satır içi Go şablonu (blok skaler). Mod 2: dosya $import: (yalnızca yerel bir dosya yoluyla $import: içeren bir eşlem). Mod 3: kütüphane $import: (yalnızca bir MappingLibrary girdisine yalın adlı kimlik başvurusuyla, <Library>#/mappings/<entry>, isteğe bağlı olarak bir :<version> alt sınırıyla $import: içeren bir eşlem). Derleyici içerik biçimine göre yönlendirir: blok skaler Mod 1’e, dosya yolu içeren $import: Mod 2’ye, yalın adlı kütüphane başvurusu içeren $import: Mod 3’e. Üçü de çözümlenen Go şablonunu values eşlemesi sırasında Recipe’nin şablon bağlamına karşı değerlendirir (Sprig yardımcı kütüphanesi önceden kayıtlıdır); Mod 3 girdiyi yerel kataloğa ve lockfile ile sabitlenmiş kütüphanelere karşı çözümler, host içeren bir başvuru ise reddedilir. Yönlendirme mekanizması ve işlenmiş örnekler için entities/recipe.md içindeki “The valuesMapping field — three authoring modes” bölümüne bakın.

Recipe yazım yüzeyi ve eşleme dili tasarımı için entities/recipe.md sayfasına, Mod 3’ü destekleyen kütüphane varlığı için entities/mappinglibrary.md sayfasına bakın.

Inject sözdizimi

inject: bloğunun her yerleşimde tek bir sözdizimi vardır — bir bileşenin kendi inject alanında, bir uses bağlantısında ve bir ekte.

  • Mekanizma başına bir girdi listesi ([{in: ..., from: ...}], [{in: ..., value: ...}]) — kullanılabilir. Her teslim mekanizması bir listedir; her girdi yerel tanımlayıcısını (ortam değişkeni adı, dosya yolu, argüman bayrağı) in: ile adlandırır ve from: (provides anahtarı başvurusu) ya da value: (sabit dize) değerlerinden tam olarak birini taşır. Liste yerine eşlem olarak yazılmış bir mekanizma ya da her iki anahtar sözcüğü taşıyan bir girdi, derlemeyi Aggregate’in belge zarfında durdurur ve yolu belirtir.

  • value: yalnızca bir bileşenin kendi inject alanında. Sabit değer, bileşenin kendi inject alanına aittir ve onu bu alan iletir. Bir uses bağlantısında value:, An inject: entry on a connection carries a literal (Bir bağlantıdaki girdi sabit değer taşıyor) sayfasında açıklandığı gibi derlemeyi durdurur; bir ekin kendi inject alanında da An inject: entry on an attached Feature carries a literal (Eklenmiş bir Feature üzerindeki girdi sabit değer taşıyor) sayfasında açıklandığı gibi derlemeyi durdurur: ikisi de yalnızca başka bir varlığın yayımladığı ve from: ile adlandırılan anahtarları iletir.

Çift durumlu bağlam anlamı, anahtar çakışması kuralları ve çalışılmış örnekler dahil olmak üzere Injection Contract belirtiminin tamamı için vocabulary/topology-triad.md sayfasına bakın.

Şablon motoru

Aggrega’nın Go şablon motoru, Recipe ve FeatureRecipe şablonlarını şablon bağlamına karşı, Şablon Genişletme Matrisi’nin belgelediği site başına aşamada değerlendirir. Sprig yardımcı kitaplığı, oluşturucunun değerlendirdiği her yüzeyde Aggrega’nın kendi yardımcılarıyla birlikte önceden kaydedilmiştir; tek bir istisna vardır: yapılandırılmış bir source: koordinatının çözümlenmesi yalnızca Aggrega’nın yardımcılarını kaydeder. Orada optional ve capitalizedWords kullanılabilir, Sprig’in işlevleri kullanılamaz; bu nedenle bir source: alanındaki ya da yapılandırılmış bir source: taşıyan bir varlıktaki locals: girdisindeki Sprig çağrısı ayrıştırma zamanında durdurulur. Bu yüzeye ayrı bir bölüm ayıran errors/fatal-halts.md sayfasına bakın. Değerlendirme, ayrıştırma ve Sprig entegrasyonu bugün kullanılabilir.

Eksik anahtar davranışı — değer şablonlarında tolere edilir; yol şablonlarında, onaylamalarda ve bir source: koordinatında katı missingkey=error. Değer şablonları Go’nun missingkey=zero seçeneğiyle değerlendirilir; bu nedenle bağlanmamış bir anahtara başvuran bir şablon (ör. .values.unset_field) hata vermez ve okuma hiçbir şey oluşturmaz. {{ .values.optional_field | default "fallback" }} gibi katalog kalıpları bu politika altında çalışmaya devam eder, çünkü ayarlanmamış bir değer default için boş sayılır. Yol şablonları (Release sınırlarındaki directory: / subDirectory:) kapalı bir izin listesine karşı missingkey=error ile değerlendirilir; sessiz yol hataları, operatörlerin ancak derlemeden sonra fark ettiği bozuk dosya sistemi düzenleri üretir ve bu katılık hatayı daha erken yakalar. Aynı nedenle iki yüzey daha aynı katı politikayı uygular: orada boş bir oluşturma, yazarın geri okuyabileceği bir alan yerine yanlış bir karar ya da yanlış bir sabitleme üretir. Bunlar, bir Component, Feature, Recipe veya FeatureRecipe üzerindeki assertions: girdisi ile bir Recipe veya FeatureRecipe üzerindeki yapılandırılmış bir source: bloğunun şablonlu alanlarıdır. errors/fatal-halts.md, her yüzeyin politikasını tek tek açıklar ve katı politika altında çalışan varlığa duyarlı biçimleri verir.

optional ile varlığa duyarlı geri dönüş. Bir Recipe yazarının “anahtar yok” ile “anahtar sıfır / boş / false değerle var” durumunu ayırt etmesi gerektiğinde (Sprig’in default işlevinin yapamadığı ayrım), oluşturucu optional yardımcısını sunar: {{ optional .infra "replicas" 1 }}, varsa yazılmış infra.replicas değerini (yazılmış bir 0 dahil) döndürür ve yalnızca anahtar yoksa 1 değerine geri döner. Tam anlamlar için templates/sprig-functions.md sayfasına bakın.

capitalizedWords ile ad katlama. Bir hedefin kaynakları adreslediği adlarda yalnızca harf ve rakam kabul ettiği durumlarda, {{ capitalizedWords .context.instance_id }} kimliği, bu alfabenin dışındaki herhangi bir şeyle ayrılmış sözcükler olarak okur ve her sözcüğün ilk harfini büyük yapar; böylece payments-db, PaymentsDb verir. Katlama her ayırıcıyı atar, dolayısıyla yalnızca noktalama işaretleriyle farklılaşan iki kimlik aynı ada ulaşır; tek bir ad altında iki kaynak üretecek bir derleme durur ve her iki kimliği de adlandırır. Tam anlamlar için templates/sprig-functions.md sayfasına bakın.

Bildirim katmanında parametre sözleşmesinin uygulanması. Release’in sağlamadığı zorunlu parametreler, çözümlemenin ilk denetlediği şey olan parametre sözleşmesi katmanında, parametreyi ve sözleşmeyi adlandıran dosya:satır kaynak bilgisiyle açık hatalar üretir. Tür / kısıt ihlalleri de aynı şekilde ortaya çıkar. Eksik anahtarın asıl denetimi budur: türler, aşağı akıştaki şablon değerlendirme zamanında değil, geliştiricinin amacının bulunduğu yerde (Aggregate’in parameters: bildirimi) denetlenir. Bkz. entities/aggregate.md §“Typed parameter contracts”.

Aggregate parameters: için tek bildirim dilbilgisi. Her parametre yuvası türlü sözleşme nesnesi olarak yazılır (key: { type: <type>, default: <value>, ... }). Çıplak skaler kısaltma (key: <value>), Aggregate’in belge zarfında, parametreyi adlandıran ve bir nesne beklendiğini söyleyen bir hatayla reddedilir. Türlü sözleşme sözcük dağarcığı type:, required: ve kısıt anlamlarını bildirim katmanında açık hale getirir; Release karşılaması, sözleşmenin bildirilen türüne göre skaler değerler kullanmaya devam eder.

Şablon sitesi başına değerlendirme matrisi için templates/expansion-matrix.md, şablonlamaya genel bakış için 05-templates.md sayfasına bakın.

Derleme işlem hattı aşamaları

Aggrega derleme işlem hattı ../architecture/10-compilation-pipeline.md içinde belgelenmiştir. Aşama bazında durum:

  • Çözümleme, topoloji oluşturma, grafiğin sonlandırılması, statik analiz ve işleme — kullanılabilir.
  • Inject eşlemesi (injectMapping işleme öncesi araya girme) ve temel işlemenin her alt aşaması — locals yayımlama, değer eşleme, workload sentezi, artifact değerlendirmesi, provider işlemesi, feature işlemesi ve kimlik bilgisi FeatureRecipe kaynak üretimi — kullanılabilir.
  • Plugin işlem hattı (pipeline: Wasm yürütmesi) — kullanılabilir. Boş olmayan pipeline: adımları bildiren bir Recipe veya FeatureRecipe’in her adımı bildirilen sırayla yürütülür: derleyici, adımda adı verilen Wasm plugin’ini işlenmiş çıktı üzerinde çağırır, döndürülen JSON Patch işlemlerini hedeflenen belgelere uygular ve adımın yan etkilerini üretir. when: koşulu yanlış değerli olarak işlenen bir adım, belge kümesini değiştirmeden geçiş olarak atlanır. JSONPatch tarzı değişiklikleri (Envoy sidecar enjeksiyonu, secret VolumeMount vb.) hedefleyen yazarlar bunları bu yüzey üzerinden gerçekleştirir.

Providers

Aggrega standart kütüphanesi beş işleme sağlayıcısıyla gelir — helm, helm-chart, compose, terraform ve cloudformation. Sağlayıcı bazında durum:

  • helm — kullanılabilir. Kaynaklı mod (Helm SDK aracılığıyla Helm chart işleme) ve sentezlenmiş mod (Workload → Workload’un form alanına göre seçilen bir denetleyici nesnesi — Deployment, StatefulSet, DaemonSet, Job veya CronJob — ve ayrıca Service’ler ve PVC’ler) birlikte sunulur.
  • helm-chart — kullanılabilir. Kaynaklı mod (şemsiye chart birleştirme) sunulur. Sentezlenmiş girdi türü bu sağlayıcı için geçerli değildir; K8s manifest sentezine ihtiyaç duyan yazarlar helm sağlayıcısını workload: ile kullanır.
  • compose — kullanılabilir. Kaynaklı mod (compose parça katmanı) ve sentezlenmiş mod (Workload → compose servisi + volume’lar + ağlar) birlikte sunulur. Sınır bazında docker-compose.yaml çıktısı, Release düzeyindeki birleştirici aracılığıyla oluşturulur.
  • terraform — kullanılabilir. Kaynaklı mod ve yapıtlar birlikte sunulur; her sınır tek bir kök yapılandırma olan aggrega.modules.tf dosyasını alır; bu dosya her bileşeni, dosyaları modules/ altındaki kendi dizininde bulunan bir module bloğu olarak bildirir. Sentezlenmiş girdi türü bu sağlayıcı için geçerli değildir.
  • cloudformation — kullanılabilir. Kaynaklı mod ve yapıtlar (yığın parçaları) birlikte sunulur; tek bir çıktı dizinine işlenen her bileşen, saf JSON olarak üretilen tek bir yığın şablonunda birleştirilir. Sentezlenmiş girdi türü bu sağlayıcı için geçerli değildir.

Provider render işlemi, pluginType: provider değerine sahip bir Plugin tarafından gerçekleştirilir; sağlayıcı render eden Plugin’in yazım yüzeyi için entities/plugin.md sayfasına, sağlayıcı başına başvuru sayfaları için 06-providers.md sayfasına bakın.

Ek açıklama güdümlü genişletme

Manifests, ek açıklama anahtarlarını Feature türlerine eşleyen bir features.annotations: bağlama bölümü ile her bağlamanın hangi Feature şema özelliklerini doldurabileceğini belirten, sütunlara göre gruplanmış bir yönlendirme tablosu (maps.infra / maps.values) taşır. entities/manifest.md ve providers/well-known-annotations.md içinde belgelenmiştir; işlem hattındaki yeri için ../architecture/10-compilation-pipeline.md, katalog yükleme ve inceleme zamanı mekanizmaları için ../architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion” bölümüne bakın.

  • Manifest features.annotations bağlamaları — kullanılabilir. Çözümlemenin ek açıklama genişletme alt aşaması uçtan uca sunulmaktadır. Release sınırlarını (dıştan içe) ve Aggregate alt sistemlerini (dıştan içe) dolaşır; bileşen başına etkin ek açıklama kümesini, tüm değer ve alt anahtar başına null ile devre dışı bırakmayı destekleyen kademelendirme + geçersiz kılma yoluyla hesaplar; her ek açıklama değerini bir skaler, yapılandırılmış bir eşlem ya da açık bir null olarak ayrıştırır; alt anahtar başına yönlendirmeyi, taraf-sütun denetimiyle (Aggregate tarafı maps.values tetikler; Release tarafı maps.infra tetikler) bağlamanın maps bildirimi üzerinden yapar; yaprak başına türleri hedef Feature’ın spec.schema tanımına göre doğrular ve IR grafiğinin origin: annotation ile işaretlediği sentetik Feature eklerini enjekte eder. Taraflar arası birleştirme, IR oluşturma zamanında sütun ve alan başına, alan başına açık değerin kazandığı şekilde yapılır; aggrega inspect her yaprak için köken parantezlerini gösterir. Katalog yüklemedeki bağlama hedefi doğrulaması, şema-sütun çakışma lint denetimi ve bağlama haritası çakışma lint denetimi bu yolu denetler. Yalın aggrega.ai/ öneki bağlama anahtarı olarak kullanıldığında Manifest yüklenirken reddedilir — bu önek platforma özgü ek açıklamalar için ayrılmıştır; bağlamalar feature.aggrega.ai/ veya özel bir alan adı kullanır.

Sürüm eşleştirme

Recipes ve FeatureRecipes, uyguladıkları Component veya Feature arayüzünü implements: anahtar sözcüğüyle bildirir. implements: hiçbir zaman bir Recipe seçmez: seçimi Manifest’in eşlemesi yapar ve türünü hiçbir eşlemenin kapsamadığı bir örnek, o türü uygulayabilen implements: değerine sahip Recipes’i aday olarak listeleyen bir hatayla durur. implements: değerinin yönlendirdiği şey, her Manifest eşleme girdisinin Recipe’inin eşlenen türü ya da o türün extends ile genişlettiği bir temeli uygulayıp uygulamadığının denetimidir. Eşlenen tür, girdinin anahtarıdır ve bir components.type anahtarı için aynı zamanda anahtarın adlandırmadığı bir sürümde ulaştığı her bileşen örneğinin türüdür — sürüm olmadan yazılmış bir anahtar için ulaştığı her örnek —; bu tür, derlemenin o örneği derlediği sürümde alınır: örneğin adlandırdığı sürüm ya da hiçbir sürüm adlandırmayan bir örnek için kataloğun barındırdığı o Component’in en yüksek sürümü. Biçim başına durum:

  • Tam (core/api-server:1.0.0) — kullanılabilir. Eşlenen tür o sürüm olmalıdır.
  • Ana sürümle uyumlu aralık (core/api-server:^1.0.0) — kullanılabilir. Şapka biçimi bir SemVer kısıtıdır (örnek için >=1.0.0, <2.0.0); eşlenen türün sürümü bu kısıtı karşılamalıdır.
  • Sürümsüz (core/api-server) — kullanılabilir. Türün herhangi bir sürümü bunu karşılar.

Recipe’inin implements: değeri ne eşlenen türle ne de onun temellerinden herhangi biriyle eşleşen bir eşleme girdisi, derlemeyi girdiyi, Recipe’i ve onun implements: değerini adlandıran bir OPS_ERROR ile durdurur. Bir anahtarın başka bir sürümde ulaştığı ve sürümünü Recipe’in implements: değerinin karşılamadığı bir bileşen örneği, derlemeyi aynı OPS_ERROR ile durdurur; bu hata örneği, türünü — ve hiçbir sürüm adlandırmayan bir örnek için derlendiği sürümü —, anahtarı, Recipe’i ve onun implements: değerini adlandırır. Şapka biçimi, ana sürümle uyumlu eşleştirme için standart yazım yüzeyidir.

implements: tasarım yüzeyi için vocabulary/inheritance-and-interface.md sayfasına, Manifest başına eşleme katmanının yapısı için entities/manifest.md sayfasına bakın.

Metadata zarfı

Katalog varlık zarfları metadata.labels, metadata.annotations ve (Release’te) metadata.environment alanlarını taşır. Yüzey başına durum:

metadata.labels ve metadata.annotations kullanılabilirliği — yedi türde. Bu alanları taşıyan varlık zarfları şunlardır: Component (labels zorunlu, zorunlu component.aggrega.ai/type anahtarıyla birlikte; annotations isteğe bağlı), Feature (her ikisi de isteğe bağlı), dört kütüphane türü SchemaLibrary, MappingLibrary, WorkloadLibrary ve ArtifactLibrary (her ikisi de isteğe bağlı) ve Aggregate (yalnızca labels, isteğe bağlı). Geri kalan varlıklar — Recipe, FeatureRecipe, Manifest, Release, Plugin — zarf düzeyinde metadata.labels veya metadata.annotations kabul etmez.

Release’te metadata.environment — zorunlu. Release şeması environment alanını zorunlu bir metadata alanı olarak listeler; derleme, bu alanın değerini işlenmiş çıktıya aggrega.ai/environment etiketi olarak işler. Environment Metadata bölümünün beş pratik kullanım senaryosu (OTel/FinOps maliyet atfı, OTel iz/günlük filtreleme, Kubernetes operatörü hedefleme, çok bölgeli üretim ayrımı, uyumluluk kapsamı belirleme) için entities/release.md sayfasına bakın.

metadata anahtarlarına uygulanan alan harf düzeni disiplini için 02-naming-conventions.md sayfasına, her varlığın bugün kabul ettiği zarf biçimleri için ise varlık başına başvuru sayfalarına bakın.

CLI komutları

Aggrega CLI, derleme hattını ve iç gözlem komutlarını kaydeder. Komut bazında durum:

  • aggrega build — kullanılabilir. Bir Release dosyasını okur, Aggregate + Manifest’i çözümler, derleme hattını çalıştırır ve işlenmiş yapıtları sınır çıktı dizinlerine yazar. Bir kilit dosyası varsa bağımlılıkları ona göre doğrular; yoksa bir pull isteyerek durur ya da --auto-pull veya auto_pull bunu istiyorsa önce kilit dosyasını doldurur.
  • aggrega inspect — kullanılabilir. Bir katalog varlığını, bir varlık dosyasını, bir kayıt defterinde yayımlanmış bir varlığı ya da bir Release’i inceler ve çözümlenmiş biçimini raporlar. Bkz. cli/aggrega-inspect.md.
  • aggrega pull — kullanılabilir. Bir Release’in tüm bağımlılıklarını çözümler ve her katalog varlığını ve kaynak yapıtı bir sürüme ve içerik özetine, Release’in işlemesinin istediği her dış girdiyi de bir içerik özetine sabitleyen, Release’e özgü bir kilit dosyası yazar; getirilen içeriği .aggrega/cache altında önbelleğe alır. --verify, mevcut bir kilit dosyasını güncel duruma karşı denetler. Bkz. cli/aggrega-pull.md.
  • aggrega push — kullanılabilir. Bir katalog varlığını bir OCI kayıt defterine yayımlar; aggrega push --list-kinds hangi türleri kabul ettiğini raporlar. Bkz. cli/aggrega-push.md.
  • aggrega lint — kullanılabilir. Yayımlama disiplini kurallarını warn önem düzeyinde tüm katalog, bir Release’in bağımlılık kapanışı ya da tek bir varlık üzerinde çalıştırır; tek bir varlıkta --pre-publish, varlığın şu anda yayımlanmış sürümüne karşı bir sürüm artırma denetimi ekler ve uyuşmazlık durdurur. Kurallar, isteğe bağlı olarak etkinleştirilen bir Wasm eklentisi olarak gelir. Bkz. cli/aggrega-lint.md.
  • aggrega serve — kullanılabilir. Düzenleyici ve IDE entegrasyonu için stdin/stdout üzerinden JSON-RPC 2.0 konuşan, uzun süre çalışan bir hizmet olarak derleyici arka plan süreci. Sunduğu yöntemler için bkz. cli/aggrega-serve.md.
  • aggrega version — kullanılabilir. CLI sürümünü yazdırır; -o json makine tarafından okunabilir bir sürüm nesnesi üretir.
  • aggrega validate — kullanılabilir. Tüm katalog, bir Release ya da tek bir varlık genelinde doğruluğu denetler ve yapıt işlemeden tanılamaları raporlar.
  • aggrega search — kullanılabilir. Yapılandırılmış kayıt defterlerinin yerel dizininde yayımlanmış varlıkları arar; dizin aggrega registry update tarafından oluşturulur ve yenilenir.
  • aggrega registry — kullanılabilir. Kayıt defterlerini ve imza güven ilkelerini yönetir; registry add bir kayıt defterini kaydeder, registry update ise aggrega search komutunun sorguladığı yerel dizini oluşturur.
  • aggrega push-artifact — kullanılabilir. Varlık yayımlayan push komutunun yanı sıra, bağımsız bir veri yapıtını (örneğin bir belge paketini) bir OCI kayıt defterine yayımlar.
  • aggrega sign — kullanılabilir. Daha önce yayımlanmış bir veya daha fazla yapıtı imzalar ve imzalarını ekler.
  • aggrega deprecate — kullanılabilir. Daha önce yayımlanmış bir yapıta imzalı bir kullanımdan kaldırma işareti ekler.
  • aggrega login ve aggrega logout — kullanılabilir. Bir OCI kayıt defterinde kimlik doğrular ve kimlik bilgisini saklar ya da saklanan bir kimlik bilgisini kaldırır.
  • aggrega auth — kullanılabilir. Yapıtları imzalamak için kullanılan yerel imzalama kimliğini yönetir.
  • aggrega config — kullanılabilir. Çalışma alanı yapılandırmasını inceler ve yönetir; alt komutlar birleştirilmiş etkin yapılandırmayı ve her ayarın nereden geldiğini gösterir, bir kayıt defteri ve onun imza güven ilkesiyle çalışan bir yapılandırma oluşturur ve etkin, derleme açısından kritik yapılandırmayı çalışma alanına dondurur; böylece çalışma alanı, makinenin genel yapılandırmasına dayanmadan aynı şekilde derlenir.
  • aggrega get-schema — kullanılabilir. Bir varlık veya sözleşme türü için JSON Schema’yı yazdırır.
  • aggrega plugin — kullanılabilir. CLI’nin çözümleyebildiği Wasm eklentilerini inceler; alt komutlar bunları listeler, yapılandırılmış eklentileri ekler ve kaldırır, bir eklentinin makineye ait kayıtlarını eşitler ve bunların bir katalog görünümünü oluşturur.
  • aggrega cache — kullanılabilir. Disk üzerindeki önbellekleri inceler ve bakımını yapar; alt komutlar durumu raporlar, budar, çıkarır ve temizler.
  • aggrega mcp — kullanılabilir. stdio üzerinden ya da başka bir makinedeki bir istemci için HTTPS üzerinden bir Model Context Protocol sunucusu çalıştırır ve derleyicinin iç gözlem yeteneklerini yapay zekâ asistanı entegrasyonlarına açar.
  • aggrega completion — kullanılabilir. CLI için kabuk otomatik tamamlama betiğini oluşturur.
  • CLI uzantısı alt komutları — kullanılabilir. pluginType: cli konuğu olarak yayımlanan bir Wasm eklentisi çözümlenir ve bir aggrega alt komutu olarak kaydedilir; böylece kurulu bir uzantı, yerleşik komutların yanında aggrega <extension> olarak çalışır.
  • aggrega import — kullanılabilir. Yabancı, bildirimsel bir ajan tanımı kaynağını (Langflow, Flowise, n8n) taslak Aggregate ve Component yazım dosyalarına dönüştürür ve her düğüm için deterministik, güven puanlı bir katalog yeniden kullanım kararı kaydeder. Biçime özgü eşleme, çalışma alanının kaynak biçim için çözümlediği bir içe aktarıcı eklenti tarafından sağlanır: kataloğunun içerdiği bir eklenti ya da derleyicinin her derleyici sürümüyle birlikte derlenip yayımlanan Langflow, Flowise ve n8n içe aktarıcılarından biri. İkili dosya bunların Plugin varlıklarını taşır ancak modüllerini taşımaz; bu nedenle her çalışma alanında kendi biçimlerine hizmet ederler: makinede bulunmayan birine ihtiyaç duyan ilk içe aktarma onu çalışma alanının varsayılan kayıt defterinden getirir, doğrular ve sonraki her içe aktarma için içerik önbelleğinde tutar. Bir kaynak, çalışma alanının kataloğunun onun sözdizimi için sunduğu ayrıştırıcıyla ya da katalog hiçbirini sunmuyorsa derleyicinin taşıdığı ayrıştırıcıyla ayrıştırılır; böylece kataloğunda hiç ayrıştırıcı bulunmayan bir çalışma alanı da bunlardan biriyle içe aktarır.
  • aggrega scaffold — kullanılabilir. Herhangi bir varlık türü için o türün şemasından bir başlangıç belgesi taslağı oluşturur — gerektirdiği her alanı içerir, değer gereken yerlere bir yer tutucu koyar — ve bunu standart çıktıya yazar; --example ile, imzalı belge paketinden okunan, belgelerin çalıştırılabilir örneklerinden birini yeni bir dizine yazar.
  • aggrega explain — kullanılabilir. Kısa bir kodun (örneğin E0007) veya açıklayıcı bir kodun adlandırdığı durdurma koşulunu açıklar.
  • aggrega edit-document — kullanılabilir. Bir belgeye sınırlı, yapılandırılmış tek bir düzenleme uygular — bir bileşen eklemek, bir Feature eklemek, bir bağlantı kurmak veya tek bir değer ayarlamak — ve dokunmadığı her baytı korur.
  • aggrega pin — kullanılabilir. Bir Recipe veya FeatureRecipe’in yanındaki entity.lock dosyasına, varlığın kendi belgesinin dışından okuduğu her girdi için içerik sabitlemesini kaydeder.
  • aggrega skills — kullanılabilir. Aggrega becerisini bir AI asistanına kurar.

CLI’ye genel bakış için bkz. 07-cli.md, komut bazında tüm başvuru sayfaları için bkz. Dil Başvurusu dizini.

Düzenleyiciler ve diğer ön yüzler

Her ön yüz aggrega ikili dosyasının derlediğini gösterir; hiçbiri kendine ait bir derleyici taşımaz. Yüzey başına durum:

  • IR grafiği sözleşmesi — kullanılabilir. Her ön yüzün grafiği okurken temel aldığı sözleşme olan IR grafiği şeması, Aggrega şema dağıtımının bir parçası olarak sunulur; bkz. IR şema başvurusu.
  • Grafiği bir komuttan okuma — kullanılabilir. aggrega build, --ir-graph seçeneğini kabul eder; bir Release verilen aggrega inspect ve aggrega validate --release de kabul eder; bu bayrak, komutun zaten ürettiklerine ek olarak o çalıştırmanın çözümlediği grafiği JSON olarak stdout’a yazar. Bir daemon oturumu aynı grafiği aggrega/irGraph üzerinden okur; MCP sunucusunun cli-inspect, cli-build ve cli-validate araçları ise bunu ir_graph argümanı olarak alır.
  • Visual Studio Code’da topoloji grafiği — kullanılabilir. Visual Studio Code için Aggrega uzantısı, seçili Release’in IR grafiğini etkileşimli bir grafik olarak çizer ve ondan Features ekler; ikisi için de aggrega serve daemon’una başvurur.
  • Başsız CLI akış modu — planlandı. Başsız mod, topoloji değiştikçe bir ön yüzün tüketmesi için IR grafiğini stdout’a satır ayrımlı JSON olarak yayar. Bugün sunulan, bir akış yerine çağrı başına tek bir belgedir: hiçbir komut, bir topoloji değiştikçe tek bir stdout üzerinde bir grafik dizisi yaymaz.

Düzenleyicinin, asistanın ve daemon’un derleyiciye nasıl ulaştığı için bkz. ../architecture/15-editors-assistants-and-frontends.md.

Tasarım yönleri

Yukarıdaki durum sınıflandırması, dil genelinde yüzey başına durumu sınıflandırır; bu bölüm ise mimari bölümlerinde belgelenen daha geniş tasarım yönlerinin durumunu kaydeder.

Tüm ortamı kapsayan uyumluluk planlanan bir yön değildir: bir yönetişim kuralını, çalışma alanındaki her derlemeyi bağlayacak şekilde bir kez belirtmek, yönetişim soketi aracılığıyla bugün kullanılabilir durumdadır. Çalışma alanı yapılandırmasının plugins.governance anahtarına bağlanan bir plugin, o çalışma alanındaki her derlemeyi değerlendirir: karar rolü, kuralı ihlal eden bir grafiği veya işlenmiş bir yapıtı reddeder; dönüştürme rolü ise bir geliştiricinin hiçbir zaman yazmadığı türetilmiş meta verileri sağlar. Bkz. ../architecture/11-governance-and-compliance.md.

  • Arayüz eşliği ve otomatik uygulama — kullanılabilir. Temel bir Component’e karşı yazılmış bir Recipe, zincirin herhangi bir derinliğinde onu genişleten her Component’e hizmet eder; Mimar’ın yinelenen bir Recipe yazmasına gerek kalmaz. Genişleten Component schema: inherited yazar; böylece values / infra / provides alanlarına temelin Recipe’inin tüketemeyeceği hiçbir kök anahtar eklemez; kendi şemasıyla extends bildiren bir Component, belge zarfında reddedilir. Manifest, genişleten türü yine kendi girdisiyle eşler ve eşleme denetimi, eşlenen Recipe’in implements değeri o türü ya da genişlettiği herhangi bir temeli adlandırdığında bunu kabul eder. ../architecture/02-ecosystem-philosophy.md içinde belgelenmiştir.
  • Ghost Infrastructure Tracker — kullanılabilir. Bir işleme aşaması korkuluğu, bir yazarın bildirdiği bir anahtar bir düğüme ulaştığında ve bağlı Recipe’in bildirdiği hiçbir şablon onu okumadığında bir uyarı üretir; böylece yazarın bildirdiği ve şablonun sessizce düşürdüğü bir değer kaybolmak yerine adlandırılır. Bu, aynı şekil eşleştirme tasarımının işleme aşamasındaki yarısıdır. Bkz. errors/warnings.md.

Mimari bölümleri tasarım yüzeylerini açıklar; bu sayfa ise uygulama durumunu izler.