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

aggrega scaffold

Bir varlık türü için bir başlangıç belgesi taslağı hazırlar ya da çalıştırılabilir bir örneği yeni bir dizine yazar

Kullanım

aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]

Açıklama

Draft a starter document for an entity kind from its schema, or write one of the documentation's runnable examples into a new directory.
Drafting a starter document
The kind is the lowercase-hyphenated schema token — for example component, aggregate, release, recipe, manifest, or feature. Run aggrega get-schema --list to print the whole set; a token no schema answers to is refused with that set in the message, so a typo is corrected without a second lookup.
The document is derived from that kind's own contract and from nothing else. It carries exactly the fields that kind's schema requires, with the fixed apiVersion and kind filled in and a placeholder everywhere a value is needed. It is not a worked example: there is no namespace, no category, no label set and no commented suggestion of what people usually write, because a catalog decides those for itself and a starter document that guessed at them would teach a requirement that does not exist.
The optional name seeds metadata.name for a kind whose schema requires one. Every other required value is left as a placeholder to fill in.
Nothing is written to disk. The document goes to standard output, so a redirect decides where it lands:
aggrega scaffold component my-service > my-service.yaml
The same starter document is served to an assistant by the scaffold tool that aggrega mcp exposes, which returns these bytes alongside a machine-readable payload; this command is the terminal route to the same drafting.
Writing a runnable example
With --example, the argument is the name of one of the runnable examples the documentation publishes, and the command writes that example's files into a new directory — the second argument, or a directory named after the example in the current directory when there is none — then prints the commands the example's own page gives for building it:
aggrega scaffold --example redis-cache
The directory must not exist yet, or must be empty; a directory holding anything is refused and left as it is. With --list, the command prints every example there is, each with its level and the first sentence of its page, and writes nothing:
aggrega scaffold --example --list
The examples are read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version. It is kept in the cache every project on this machine shares, so a second example needs no second download. It is fetched through the same network settings as every other registry read, and verified against this workspace's signature policy before it is kept or read; a bundle that does not verify is refused, never used. Offline, an example is written only from a copy already cached on this machine.
An example's files are written only as files and directories inside the directory named: a bundle carrying an entry that would land outside it, or a link, is refused whole and nothing is written.
The scaffold tool that aggrega mcp exposes, and the editor's language server that aggrega serve runs, write and list the examples on the same terms, with the directory named relative to the workspace root, and answer with the files written and these same commands.

Bayraklar

BayrakVarsayılanAçıklama
--examplefalseargümanın adlandırdığı çalıştırılabilir örneği imzalı dokümantasyon paketinden okuyarak yeni bir dizine yazar
--listfalse—example ile, dokümantasyonun yayımladığı her çalıştırılabilir örneği yazdırır ve hiçbir şey yazmaz

Ne yapar

Komutun iki biçimi vardır. aggrega scaffold <kind>, bir türün şemasından bir başlangıç belgesi taslağı oluşturur ve onu yazdırır; bu bölüm ve sonraki üç bölüm bunu anlatır. aggrega scaffold --example <name> ise bunun yerine belgelerin çalıştırılabilir örneklerinden birini yeni bir dizine yazar; bkz. Çalıştırılabilir bir örnekten başlamak.

aggrega scaffold <kind>, tek bir varlık türü için bir başlangıç belgesini standart çıktıya yazdırır. Belge, o türün şemasının gerektirdiği alanları tam olarak içerir: apiVersion ve kind doldurulur, çünkü şema bunları sabitler; diğer her gerekli değer ise sizin değiştirmeniz için bir yer tutucu olarak bırakılır.

İsteğe bağlı [name], şeması bir ad gerektiren bir tür için metadata.name alanının ilk değerini verir:

Terminal window
aggrega scaffold component my-service
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: my-service
version: ""
labels:
component.aggrega.ai/type: ""
spec: {}

Tür, küçük harfli ve tireli şema belirtecidir: component, aggregate, release, recipe, manifest, feature ve diğerleri. aggrega get-schema --list kümenin tamamını yazdırır; hiçbir şemaya karşılık gelmeyen bir belirteç, iletide bu küme gösterilerek reddedilir, böylece bir yazım hatası ikinci bir aramaya gerek kalmadan düzeltilir.

Ne döndürür, ne döndürmez

Belge, yalnızca türün kendi sözleşmesinden gelir, başka hiçbir şeyden değil. Bu, işlenmiş bir örnek değildir. Sizin için doldurulmuş bir ad alanı, kategori ya da etiket değeri yoktur; insanların genellikle ne yazdığına dair yorum satırı biçiminde bir öneri de yoktur, çünkü bunların hiçbiri derleyicinin gerektirdiği bir şey değildir. Bir katalog kendi adlandırmasını, kendi kategorilerini ve kendi dizin düzenini seçer; alanlara şema karar verir ve bu komutun okuduğu tek şey şemadır. Geri kalanı tahmin eden bir başlangıç belgesi size var olmayan bir kural öğretirdi.

Taslak oluşturma hiçbir dosya yazmaz. Belge standart çıktıya gider; böylece nereye yazılacağına bir yönlendirme karar verir ve diskteki hiçbir şey siz istemeden değiştirilmez:

Terminal window
aggrega scaffold component my-service > my-service.yaml

Tamamlanmış bir varlık değildir ve yer tutucu da tam olarak bu anlama gelir. Boş bir gerekli değer bir değer değildir; bu nedenle belge, çıktığı haliyle aggrega validate üzerinden çalıştırıldığında reddedilir ve hâlâ doldurulması gereken her yer tutucu, her birinin ne aldığıyla birlikte bir kerede adlandırılır; yukarıda bunlar sürüm ve bileşen türüdür:

Entity: my-service.yaml
Kind: Component
[E0215]
document envelope validation failed: 2 placeholders still owed in my-service.yaml; an empty required value is not a value, so each of these needs one before the document validates:
5:3: metadata.version takes a semantic version, such as 1.0.0
7:5: metadata.labels.component.aggrega.ai/type takes one of: server, worker, task, function, stateful-server, resource

Her değerin ne aldığı türün kendi şemasından okunur: şemanın listelediği yerde kabul ettiği değerler, bir anlamsal sürüm istediği yerde anlamsal sürüm, aksi halde şemanın alana ilişkin kendi açıklaması. Bu değerleri sağladığınızda aynı komut belgeyi kabul eder. Belgenin biçiminde hiçbir şeyin değişmesi gerekmez, çünkü biçim şemadan gelmiştir.

Şema boş değeri kabul edecek olsa bile bir değer doldurulmalıdır. Taslağı hazırlanan bir Recipe ya da FeatureRecipe, boş bir capability ve implements içerir. Şemaları boş bir dizeyi kabul eder, ancak boş bir dize hiçbir sağlayıcıyı ve hiçbir türü adlandırmaz; bu nedenle aggrega validate, siz doldurana kadar ikisini de hâlâ doldurulması gereken olarak adlandırır. Bu yorum tek bir varlık dosyasının doğrulanmasına aittir: tüm kataloğu kapsayan bir çalıştırma, aggrega validate --release ve aggrega build bunu uygulamaz. Neleri kapsadığı için hâlâ doldurulması gereken yer tutuculara bakın. Taslağı hazırlanan bir Recipe ayrıca şemasının en az birini istediği girdi türlerinden — source, valuesMapping, workload veya artifacts — hiçbirini bildirmez, çünkü hangisinin uygun olduğunu seçmek size kalmıştır; bu nedenle aggrega validate, siz birini ekleyene kadar onun spec alanını reddeder.

Bir asistandan ya da bir düzenleyiciden aynı belge

Başlangıç belgesi, hangi arayüz isterse istesin aynı baytlardan oluşur. aggrega mcp üzerinden bağlanan bir yapay zekâ asistanı belgeye scaffold aracı olarak erişir; bu araç belgeyi, makine tarafından okunabilir bir yükle birlikte metin olarak döndürür. aggrega serve ile çalışan bir düzenleyici belgeye aggrega/scaffoldEntity üzerinden erişir. Belge şemadan bir kez türetilir; böylece bir terminalde sizin hazırladığınız taslak ile bir asistanın sizin için hazırladığı taslak bayt bayt aynıdır.

Çalıştırılabilir örnekleri yazma ve listeleme de aynı yüzeylerde bulunur ve alan adları olarak komutun kendi sözcükleri kullanılır. Bir örnek yazmak için scaffold aracına ya da aggrega/scaffoldEntity yöntemine kind yerine example gönderin; yeni dizini çalışma alanı köküne göreli olarak adlandırmak için dir gönderin — hiç göndermediğinizde orada örneğin adını taşıyan bir dizin kullanılır — ve tüm örnekleri yanıt olarak almak için yalnızca list: true gönderin. Örnek aynı paketten okunur, aynı politikaya göre doğrulanır ve aynı çıkarma işlemiyle yazılır; bu nedenle dosyalar ve sonraki komutlar terminaldekiyle aynıdır, retler de öyle: herhangi bir şey içeren bir dizin, dizinin dışına çıkan bir girdi ya da bir bağlantı, politikanızın kabul etmediği bir paket, hiçbir şeyin önbelleğe alınmadığı çevrimdışı bir çalışma alanı. Yanıt yapılandırılmıştır: bir liste için examples, her biri name, level ve summary ile; bir yazma için example, dir, files — yazılan dosyalar, dir dizinine göreli — next, örneğin sayfasının verdiği komutlar, ve version, örneğin okunduğu belge sürümü. scaffold aracının bir yazmaya verdiği yanıt ayrıca dizinin nerede olduğunu gösteren output_dir alanını taşır — standart girdi ve çıktı üzerinden tam yol olarak, böylece onu göremediği bir çalışma alanına göreli olarak adlandıran bir asistan örneğin nereye gittiğini okuyabilir; HTTP üzerinden ise çalışma alanı köküne göreli olarak. scaffold aracının metni, bu komutun yazdırdığı açıklamadır ve bu konum dir değerinden farklı olduğunda onu adlandıran bir satırla biter. İki formun alanları birlikte gönderildiğinde — örneğin kind ile example — herhangi bir şey okunmadan önce her ikisinde de aynı sözcüklerle reddedilir. Bir düzenleyici, örnek formu için çalışma alanını isteğin workspaceRoot alanında adlandırır ve dir, onun içinde kalan ve bir bağlantı üzerinden onun dışına çıkmayan göreli bir yol olmalıdır; HTTP üzerinden araç dir değerini hizmet verdiği çalışma alanıyla da sınırlar, standart girdi ve çıktı üzerinden ise her yolu aldığı gibi dir değerini de verildiği gibi alır. Yetenek dizini, o form nedeniyle scaffold aracını yazan bir araç olarak bildirir; bu komutu ayrı bir süreçte çalıştıran cli-scaffold aracını da yazan bir araç olarak bildirir.

Çalıştırılabilir bir örnekten başlamak

Belgeler çalıştırılabilir örnekler içerir — her biri bir Aggregate, onun Releases’ı ve derlemesinin dayandığı diğer her şeyi barındıran bir dizindir ve nasıl derleneceğini anlatan bir sayfayla birlikte gelir. --example bunlardan birini yeni bir dizine yazar; böylece boş bir projeden değil, çalışan bir projeden başlayabilirsiniz:

Terminal window
aggrega scaffold --example redis-cache
Wrote the example redis-cache into redis-cache (12 files).
Next:
cd redis-cache
# Local development (Docker Compose), no authentication
aggrega build --release release-compose.yaml --auto-pull
...
Its page, redis-cache/README.md, explains what it shows.

Neyi, nereye yazar. Örneğin dosyaları, belgelerin içerdiği hâliyle, ikinci bağımsız değişken olarak adlandırdığınız dizine yazılır — ya da hiçbirini adlandırmadığınızda, komutu çalıştırdığınız klasörde örneğin adını taşıyan bir dizine. Dizin henüz var olmamalı ya da boş olmalıdır. Başka her durum reddedilir ve tam olarak olduğu gibi bırakılır: bir dosya içeren bir dizin, o yolda duran bir dosya ya da bir bağlantı. Üstündeki henüz var olmayan dizinler oluşturulur. Örneğin hiçbir dosyası başka bir yerde bırakılmaz ve tümü yazılmadan hiçbiri yerine konmaz: önce bir kenara yazılır, her biri hazır olduğunda içeri taşınır.

Ardından yazdırdığı komutlar, örneğin kendi sayfasının verdikleridir: sayfanın ## Build başlığı altındaki ilk sh, bash ya da shell bloğu, sayfanın yazdığı biçimde, yorumlar dâhil, dizine giren bir cd komutundan sonra. Sayfasında böyle bir blok olmayan bir örnek için bunun yerine sayfasının yolu verilir.

Hangi örnekler var. --list her örneği, her birini bir kez, belgelerin onları öğrettiği sırayla yazdırır — adını, sayfasının bildirdiği düzeyi ve sayfasının ilk cümlesini — ve hiçbir şey yazmaz:

Terminal window
aggrega scaffold --example --list
EXAMPLE LEVEL DESCRIPTION
...
redis-cache start This lean example compiles a single **Redis** in-memory cache (Redis wire protocol) from one Developer-authored `Aggregate` to two realizations.
...

Liste, belgelerin kendi örnek listesidir; örneklerin yanında Ürüne ve yeteneğe göre örnekler olarak yayımlanan listenin ta kendisidir. Paketin altında hiçbir örnek taşımadığı bir ad, sizi --list seçeneğine yönlendirerek reddedilir ve hiçbir şey yazılmaz.

Örnekler nereden gelir. Belge paketinden okunurlar — aggrega explain komutunun adım adım açıklamalarını okuduğu, yayımlanmış belgelerin imzalı arşivi — ve bu paket çalışma alanınızın varsayılan kayıt defterinde yayımlanır. Okunan paket, çalıştırdığınız aggrega sürümü için yayımlanmış olandır. O sürüm için yayımlanmış bir paket yoksa daha önceki bir sürüm için yayımlanmış en yeni paket okunur ve komut bunu standart hata çıktısında belirtir:

note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before it

Bir sürümden sonraki bazı commit’lerden derlenmiş bir aggrega — aggrega version çıktısı 0.9.0-12-g1a2b3c4d gibi görünen bir derleme — derlendiği sürümün belgelerini, burada 0.9.0, ya da o yayımlanmamışsa daha önceki bir sürümün belgelerini okur. Sürüm adayı gibi bir ön sürümden sonraki bazı commit’lerden derlenmiş bir derleme — aggrega version çıktısı 0.9.0-rc.6-4-gc9db2f597 gibi görünen bir derleme — o ön sürümün belgelerini, burada 0.9.0-rc.6, ya da o yayımlanmamışsa ondan önce yayımlanmış en yeni belgeleri, daha önceki bir ön sürüm de dahil olmak üzere, okur. Diğer her derleme, bir ön sürümün belgelerini yalnızca kendisi o ön sürüm olduğunda okur. Sürüm numarası damgalanmamış bir derleme, kendi sürümünün belgelerini okur ya da hiçbirini okumaz. aggrega explain de adım adım anlatımlarını okuduğu paketi aynı şekilde seçer.

Sürümünüz için hiçbiri yayımlanmamışsa ve daha önceki en yeni paket bu aggrega sürümünün artık okumadığı bir biçimdeyse — örneğin kendi belgeleri yayımlanmadan önce çalıştırılan bir sürüm adayı — komut, her ikisini tek bir cümlede belirterek reddeder ve hiçbir şey yazılmaz:

[E0137]
hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the examples cannot be read

Kullanılmadan önce doğrulanır. Paket, diğer her kayıt defteri okumasıyla aynı ağ ayarları üzerinden getirilir ve saklanmadan önce imzası, çalışma alanınızın o kayıt defteri için imza politikasına göre denetlenir — makinede zaten bulunan bir kopya okunmadan önce de yeniden denetlenir; böylece başka bir projenin daha gevşek politikasının içeri aldığı bir kopya sizin politikanız altında kullanılmaz. Politikanızın kabul etmediği bir paket reddedilir ve hiçbir şey yazılmaz.

Makine başına bir kez getirilir. Paket, makinedeki her Aggrega projesinin paylaştığı önbellekte tutulur — bkz. aggrega cache — bu nedenle ikinci bir örnek ya da ikinci bir proje ikinci bir indirme gerektirmez ve ikisi aynı sürümü okuduğunda aggrega explain de aynı kopyayı okur.

Çevrimdışıyken yalnızca önbellekte olanı okur. Çevrimdışı bir çalışma alanında hiçbir şey getirilmez: bir örnek, makinede zaten bulunan ve politikanızın kabul ettiği bir kopyadan yazılır — bu sürüme ait olan ya da yoksa önbellekteki daha önceki en yeni kopya — ve hiçbiri yoksa komut, her ağ okumasının verdiği çevrimdışı retle reddeder ve ağa nasıl izin verileceğini belirtir.

Beklenmedik bir şey taşıyan paket bütünüyle reddedilir. Paket bir kayıt defterinden gelir, bu nedenle çıkarma işlemi düzeni hakkında hiçbir şeye güvenmez: adı belirttiğiniz dizinin ya da paketin dışına düşecek bir girdi ve bir bağlantı ya da dosya veya dizin dışında herhangi bir şey olan bir girdi, girdiyi adlandırarak örneğin tamamını reddeder ve hiçbir şey yazılmaz. Örnekteki yürütülebilir bir dosya yürütülebilir kalır.

Çalışma alanının yapılandırması okunur. Varsayılan kayıt defteri ve imza politikası ondan gelir; bu nedenle çalışma alanının dışına çıkan bir bağlantı olan bir yapılandırma dosyası, yapılandırmayı okuyan diğer her komutu durdurduğu gibi örnek formunu da durdurur — bkz. çalışma alanı sınırı.

Örnekler

Adsız bir Release taslağı hazırlayın ve terminalde okuyun:

Terminal window
aggrega scaffold release

Doğrudan bir dosyaya bir Recipe taslağı hazırlayın:

Terminal window
aggrega scaffold recipe postgres-helm > postgres-helm.yaml

Herhangi bir şeyi doldurmadan önce hâlâ neleri doldurmanız gerektiğini denetleyin:

Terminal window
aggrega scaffold component my-service > my-service.yaml
aggrega validate my-service.yaml

Hangi çalıştırılabilir örneklerin bulunduğunu görün, ardından birini seçtiğiniz bir dizine yazın:

Terminal window
aggrega scaffold --example --list
aggrega scaffold --example redis-cache my-cache

Bu komutun başlattığı yazma döngüsü (biçimin taslağını hazırlama, yer tutucuları doldurma, doğrulama) için Aggrega dosyalarını yazma sayfasına bakın.