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

aggrega scaffold

Menyusun draf dokumen awal untuk jenis entitas, atau menulis contoh yang dapat dijalankan ke direktori baru

Sinopsis

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

Deskripsi

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.

Flag

FlagDefaultDeskripsi
--examplefalsemenulis contoh yang dapat dijalankan yang disebut oleh argumen ke direktori baru, dibaca dari bundel dokumentasi yang ditandatangani
--listfalsedengan —example, mencetak setiap contoh yang dapat dijalankan yang diterbitkan dokumentasi, dan tidak menulis apa pun

Apa yang dilakukannya

Perintah ini memiliki dua bentuk. aggrega scaffold <kind> menyusun draf dokumen awal dari schema suatu jenis dan mencetaknya, yang dijelaskan oleh bagian ini dan tiga bagian berikutnya. aggrega scaffold --example <name> sebaliknya menulis salah satu contoh dokumentasi yang dapat dijalankan ke direktori baru — lihat Memulai dari contoh yang dapat dijalankan.

aggrega scaffold <kind> mencetak dokumen awal untuk satu jenis entitas ke output standar. Dokumen itu memuat persis kolom-kolom yang diwajibkan skema jenis tersebut: apiVersion dan kind sudah diisi, karena skema menetapkannya, dan setiap nilai wajib lainnya dibiarkan sebagai placeholder untuk Anda ganti.

[name] opsional mengisi awal metadata.name untuk jenis yang skemanya mewajibkannya:

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

Jenisnya adalah token skema huruf kecil yang dipisahkan tanda hubung — component, aggregate, release, recipe, manifest, feature, dan seterusnya. aggrega get-schema --list mencetak seluruh himpunannya, dan token yang tidak sesuai dengan skema mana pun ditolak dengan himpunan itu dalam pesannya, sehingga salah ketik dapat diperbaiki tanpa pencarian kedua.

Apa yang dikembalikannya, dan apa yang tidak

Dokumen itu berasal dari kontrak jenis itu sendiri dan bukan dari hal lain. Dokumen itu bukan contoh yang sudah dikerjakan. Tidak ada namespace, tidak ada kategori, tidak ada nilai label yang diisikan untuk Anda, dan tidak ada saran berkomentar tentang apa yang biasanya ditulis orang — karena tidak satu pun dari itu diwajibkan oleh compiler. Sebuah katalog memilih penamaannya sendiri, kategorinya sendiri, dan tata letak direktorinya sendiri; skema menentukan kolom-kolomnya, dan skema adalah satu-satunya yang dibaca perintah ini. Dokumen awal yang menebak sisanya akan mengajarkan Anda aturan yang tidak ada.

Penyusunan draf tidak menulis file. Dokumen dikirim ke output standar, sehingga pengalihan yang menentukan di mana ia mendarat, dan tidak ada apa pun di disk yang diganti tanpa Anda memintanya:

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

Ini bukan entitas yang sudah jadi, dan itulah arti placeholder. Nilai wajib yang kosong bukanlah nilai, sehingga menjalankan aggrega validate atas dokumen persis seperti yang dihasilkan akan menolaknya dan menyebut sekaligus setiap placeholder yang masih terutang, masing-masing beserta apa yang diterimanya — di atas, versi dan tipe komponen:

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

Apa yang diterima setiap nilai dibaca dari skema jenis itu sendiri: nilai-nilai yang diterimanya jika skema mencantumkannya, versi semantik jika skema memintanya, dan selain itu deskripsi kolom dari skema itu sendiri. Berikan nilai-nilai itu dan perintah yang sama akan menerima dokumen tersebut. Tidak ada bagian dari bentuknya yang harus berubah, karena bentuknya berasal dari skema.

Sebuah nilai tetap terutang bahkan di tempat skema akan menerimanya kosong. Recipe atau FeatureRecipe yang dibuat dengan scaffold membawa capability dan implements yang kosong. Skemanya menerima string kosong, tetapi string kosong tidak menyebut provider apa pun maupun tipe apa pun, sehingga aggrega validate menyebut keduanya masih terutang sampai Anda mengisinya. Pembacaan itu berlaku untuk validasi satu file entitas: eksekusi atas seluruh katalog, aggrega validate --release, dan aggrega build tidak menerapkannya. Lihat placeholder yang masih terutang untuk cakupannya. Recipe yang dibuat dengan scaffold juga tidak mendeklarasikan satu pun jenis input yang setidaknya satu di antaranya diminta oleh skemanya — source, valuesMapping, workload, atau artifacts — karena memilih yang sesuai adalah keputusan Anda, sehingga aggrega validate menolak spec-nya sampai Anda menambahkan satu.

Dokumen yang sama dari asisten atau editor

Dokumen awal terdiri dari byte yang sama, antarmuka mana pun yang memintanya. Asisten AI yang terhubung melalui aggrega mcp menjangkaunya sebagai alat scaffold, yang mengembalikan dokumen sebagai teks bersama payload yang dapat dibaca mesin. Editor yang menggerakkan aggrega serve menjangkaunya di aggrega/scaffoldEntity. Dokumen diturunkan dari skema satu kali, sehingga dokumen yang Anda buat di terminal dan dokumen yang dibuat asisten untuk Anda identik byte demi byte.

Menulis dan mencantumkan contoh yang dapat dijalankan juga tersedia di permukaan yang sama, dengan kata-kata perintah itu sendiri sebagai nama field. Kirimkan ke tool scaffold, atau ke aggrega/scaffoldEntity, example alih-alih kind untuk menulis satu contoh, dir untuk menamai direktori baru relatif terhadap root workspace — direktori yang dinamai menurut contoh tersebut di sana jika Anda tidak mengirimkannya — dan hanya list: true untuk dijawab dengan setiap contoh. Contoh dibaca dari bundel yang sama, diverifikasi terhadap kebijakan yang sama, dan ditulis oleh ekstraksi yang sama, sehingga file dan perintah berikutnya sama seperti di terminal, begitu pula penolakannya: direktori yang berisi apa pun, entri yang mengarah ke luar direktori atau sebuah link, bundel yang tidak diterima kebijakan Anda, workspace offline tanpa apa pun di cache. Jawabannya terstruktur: untuk daftar, examples, masing-masing dengan name, level, dan summary; untuk penulisan, example, dir, files — file yang ditulis, relatif terhadap dir — next, perintah yang diberikan halaman contoh, dan version, versi dokumentasi tempat contoh dibaca. Jawaban tool scaffold untuk penulisan juga membawa output_dir, lokasi direktori tersebut — lengkap melalui input dan output standar, sehingga asisten yang menyebutkannya relatif terhadap workspace yang tidak dapat dilihatnya dapat membaca ke mana contoh ditulis, dan relatif terhadap root workspace melalui HTTP. Teks tool scaffold adalah uraian yang dicetak perintah ini, ditutup dengan baris yang menyebutkan lokasi tersebut jika berbeda dari dir. Field dari dua bentuk yang dikirim bersamaan — misalnya kind dengan example — ditolak dengan kata-kata yang sama di keduanya, sebelum apa pun dibaca. Editor menyebutkan workspace di workspaceRoot permintaan untuk bentuk contoh, dan dir harus berupa path relatif yang tetap berada di dalamnya dan tidak mengarah ke luarnya melalui link; melalui HTTP, tool juga membatasi dir pada workspace yang dilayaninya, dan melalui input dan output standar, tool menerima dir sebagaimana disebutkan, seperti halnya setiap path. Indeks kapabilitas melaporkan tool scaffold sebagai alat yang menulis, karena bentuk tersebut, dan cli-scaffold, yang menjalankan perintah ini dalam proses terpisah, juga sebagai alat yang menulis.

Memulai dari contoh yang dapat dijalankan

Dokumentasi menyertakan contoh yang dapat dijalankan — masing-masing berupa direktori yang berisi sebuah Aggregate, Releases-nya, dan apa pun lainnya yang menjadi bahan build-nya, dengan halaman yang menjelaskan cara mem-build-nya. --example menulis salah satunya ke direktori baru, sehingga Anda dapat memulai dari proyek yang berfungsi alih-alih dari proyek kosong:

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.

Apa yang ditulis, dan di mana. File contoh, sebagaimana disertakan dokumentasi, ditulis ke direktori yang Anda sebutkan sebagai argumen kedua — atau, jika Anda tidak menyebutkannya, ke direktori yang dinamai menurut contoh tersebut di folder tempat Anda menjalankan perintah. Direktori itu belum boleh ada, atau harus kosong. Selain itu, ditolak dan dibiarkan persis seperti semula: direktori yang berisi file, file yang berada di path tersebut, atau link. Direktori di atasnya yang belum ada akan dibuat. Tidak ada file contoh yang tertinggal di tempat lain, dan tidak ada yang ditempatkan sebelum semuanya ditulis: file-file itu ditulis di tempat terpisah terlebih dahulu lalu dipindahkan setelah semuanya ada.

Perintah yang dicetaknya berikutnya adalah perintah yang diberikan halaman contoh itu sendiri: blok sh, bash, atau shell pertama di bawah judul ## Build halaman tersebut, sebagaimana ditulis halaman itu, termasuk komentarnya, setelah cd ke direktori tersebut. Contoh yang halamannya tidak memiliki blok semacam itu dijawab dengan path halamannya sebagai gantinya.

Contoh apa saja yang ada. --list mencetak setiap contoh, masing-masing sekali, dalam urutan dokumentasi mengajarkannya — namanya, level yang dideklarasikan halamannya, dan kalimat pertama halamannya — dan tidak menulis apa pun:

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.
...

Daftar ini adalah daftar contoh milik dokumentasi itu sendiri, yang dipublikasikan bersama contoh-contoh tersebut sebagai Contoh berdasarkan produk dan kapabilitas. Nama yang tidak memiliki contoh di dalam bundel ditolak, dengan mengarahkan Anda ke --list, dan tidak ada yang ditulis.

Dari mana contoh-contoh berasal. Contoh dibaca dari bundel dokumentasi — arsip bertanda tangan dari dokumentasi yang dipublikasikan, tempat aggrega explain membaca penjelasan langkah demi langkahnya — yang dipublikasikan di registry default workspace Anda. Bundel yang dibaca adalah bundel yang dipublikasikan untuk versi aggrega yang sedang Anda jalankan. Jika tidak ada yang dipublikasikan untuk versi itu, yang dibaca adalah bundel terbaru yang dipublikasikan untuk rilis sebelumnya, dan perintah memberitahukannya di standard error:

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

Build aggrega yang dibuat dari beberapa commit setelah suatu rilis — yang aggrega version-nya terbaca seperti 0.9.0-12-g1a2b3c4d — membaca dokumentasi rilis yang menjadi dasar build tersebut, di sini 0.9.0, atau rilis sebelumnya jika dokumentasi itu tidak dipublikasikan. Build yang dibuat dari beberapa commit setelah suatu pra-rilis seperti kandidat rilis — yang aggrega version-nya terbaca seperti 0.9.0-rc.6-4-gc9db2f597 — membaca dokumentasi pra-rilis tersebut, di sini 0.9.0-rc.6, atau, jika dokumentasi itu tidak dipublikasikan, dokumentasi terbaru yang dipublikasikan sebelumnya, termasuk pra-rilis yang lebih awal. Build lain mana pun hanya membaca dokumentasi suatu pra-rilis jika build itu sendiri adalah pra-rilis tersebut. Build yang tidak dicap dengan nomor rilis membaca dokumentasi versinya sendiri atau tidak membaca dokumentasi sama sekali. aggrega explain memilih bundel tempat ia membaca panduan langkah demi langkahnya dengan cara yang sama.

Jika tidak ada yang dipublikasikan untuk versi Anda dan bundel terbaru sebelumnya menggunakan format yang tidak lagi dibaca oleh versi aggrega ini — misalnya kandidat rilis yang dijalankan sebelum dokumentasinya sendiri dipublikasikan — perintah menolak, menyebutkan keduanya dalam satu kalimat, dan tidak ada yang ditulis:

[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

Bundel diverifikasi sebelum digunakan. Bundel diambil melalui pengaturan jaringan yang sama dengan setiap pembacaan registry lainnya, dan tanda tangannya diperiksa terhadap kebijakan tanda tangan workspace Anda untuk registry tersebut sebelum disimpan — dan sekali lagi sebelum salinan yang sudah ada di mesin dibaca, sehingga salinan yang diloloskan oleh kebijakan proyek lain yang lebih longgar tidak digunakan di bawah kebijakan Anda. Bundel yang tidak diterima kebijakan Anda ditolak, dan tidak ada yang ditulis.

Bundel diambil sekali per mesin. Bundel disimpan di cache yang dibagikan setiap proyek Aggrega di mesin tersebut — lihat aggrega cache — sehingga contoh kedua, atau proyek kedua, tidak memerlukan unduhan kedua, dan aggrega explain membaca salinan yang sama jika keduanya membaca versi yang sama.

Saat offline, hanya yang ada di cache yang dibaca. Di workspace offline tidak ada yang diambil: contoh ditulis dari salinan yang sudah ada di mesin dan diizinkan kebijakan Anda — salinan untuk versi ini, atau jika tidak ada, salinan terbaru dari versi sebelumnya yang ada di cache — dan jika tidak ada sama sekali, perintah menolak dengan penolakan offline yang diberikan setiap pembacaan jaringan, dengan menyebutkan cara mengizinkan jaringan.

Bundel yang membawa sesuatu yang tidak terduga ditolak seluruhnya. Bundel berasal dari registry, sehingga ekstraksi tidak memercayai apa pun tentang tata letaknya: entri yang namanya akan berada di luar direktori yang Anda sebutkan, atau di luar bundel, dan entri yang berupa link atau apa pun selain file atau direktori, masing-masing menolak seluruh contoh, dengan menyebutkan entri tersebut, dan tidak ada yang ditulis. File yang dapat dieksekusi dalam contoh tetap dapat dieksekusi.

Konfigurasi workspace dibaca. Registry default dan kebijakan tanda tangan berasal dari konfigurasi itu, sehingga file konfigurasi yang berupa link yang mengarah ke luar workspace menghentikan bentuk contoh sebagaimana menghentikan setiap perintah lain yang membaca konfigurasi — lihat batas workspace.

Contoh

Buat draf Release tanpa nama dan baca di terminal:

Terminal window
aggrega scaffold release

Buat draf Recipe langsung ke dalam file:

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

Periksa apa yang masih terutang sebelum mengisi apa pun:

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

Lihat contoh apa saja yang dapat dijalankan, lalu tulis salah satunya ke direktori pilihan Anda:

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

Untuk siklus penulisan yang dimulai perintah ini — membuat draf bentuk, mengisi placeholder, memvalidasi — lihat Menulis file Aggrega.