aggrega scaffold
Tworzy szkic dokumentu startowego dla rodzaju encji lub zapisuje uruchamialny przykład w nowym katalogu
Składnia
aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]Opis
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.Flagi
| Flaga | Domyślnie | Opis |
|---|---|---|
--example | false | zapisuje uruchamialny przykład wskazany przez argument do nowego katalogu, odczytując go z podpisanego pakietu dokumentacji |
--list | false | z —example wypisuje każdy uruchamialny przykład publikowany przez dokumentację i niczego nie zapisuje |
Działanie
Polecenie ma dwie formy. aggrega scaffold <kind> tworzy szkic dokumentu startowego na podstawie schematu danego rodzaju i go wypisuje — to opisuje ta sekcja i trzy kolejne. aggrega scaffold --example <name> zapisuje zamiast tego jeden z uruchamialnych przykładów z dokumentacji do nowego katalogu — zob. Zaczynanie od uruchamialnego przykładu.
aggrega scaffold <kind> wypisuje na standardowe wyjście dokument startowy dla jednego rodzaju encji. Dokument zawiera dokładnie te pola, których wymaga schemat danego rodzaju: apiVersion i kind są wypełnione, ponieważ schemat je ustala, a każda inna wymagana wartość pozostaje symbolem zastępczym do podmiany.
Opcjonalny argument [name] wypełnia metadata.name dla rodzaju, którego schemat go wymaga:
aggrega scaffold component my-serviceapiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-service version: "" labels: component.aggrega.ai/type: ""spec: {}Rodzaj to token schematu zapisany małymi literami z łącznikami — component, aggregate, release, recipe, manifest, feature i pozostałe. aggrega get-schema --list wypisuje cały zestaw, a token, któremu nie odpowiada żaden schemat, zostaje odrzucony z tym zestawem w komunikacie, dzięki czemu literówkę można poprawić bez ponownego sprawdzania.
Co zwraca, a czego nie
Dokument pochodzi wyłącznie z kontraktu danego rodzaju. Nie jest to gotowy przykład. Nie ma w nim przestrzeni nazw, kategorii ani wypełnionych wartości etykiet, nie ma też komentarzy podpowiadających, co zwykle się wpisuje — ponieważ niczego z tego kompilator nie wymaga. Katalog sam wybiera nazewnictwo, kategorie i układ katalogów; o polach decyduje schemat, a schemat jest jedynym, co to polecenie odczytuje. Dokument startowy, który zgadywałby resztę, uczyłby reguły, która nie istnieje.
Tworzenie szkicu nie zapisuje żadnego pliku. Dokument trafia na standardowe wyjście, więc o miejscu docelowym decyduje przekierowanie i nic na dysku nie zostaje zastąpione bez wyraźnego polecenia:
aggrega scaffold component my-service > my-service.yamlNie jest to gotowa encja i właśnie to oznacza symbol zastępczy. Pusta wymagana wartość nie jest wartością, więc uruchomienie aggrega validate na dokumencie w postaci, w jakiej został wygenerowany, kończy się jego odrzuceniem i wskazaniem naraz wszystkich symboli zastępczych do uzupełnienia, każdego z informacją, czego wymaga — powyżej wersji i typu komponentu:
Entity: my-service.yamlKind: 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, resourceTo, czego wymaga każda wartość, jest odczytywane ze schematu danego rodzaju: dopuszczalne wartości, jeśli schemat je wymienia, wersja semantyczna, jeśli jej wymaga, a w pozostałych przypadkach opis pola ze schematu. Po podaniu tych wartości to samo polecenie akceptuje dokument. Jego struktura nie musi się zmieniać, ponieważ pochodzi ze schematu.
Wartość jest wymagana nawet tam, gdzie schemat przyjąłby pustą. Wygenerowana encja Recipe lub FeatureRecipe zawiera puste capability i implements. Ich schemat dopuszcza pusty ciąg znaków, ale pusty ciąg nie wskazuje żadnego dostawcy ani typu, więc aggrega validate zgłasza oba pola jako wymagające uzupełnienia, dopóki nie zostaną wypełnione. Ta interpretacja dotyczy walidacji pojedynczego pliku encji: uruchomienie dla całego katalogu, aggrega validate --release oraz aggrega build jej nie stosują. Zakres opisano w sekcji symbole zastępcze do uzupełnienia. Wygenerowana encja Recipe nie deklaruje też żadnego z rodzajów wejścia, z których jej schemat wymaga co najmniej jednego — source, valuesMapping, workload ani artifacts — ponieważ wybór właściwego należy do autora, więc aggrega validate odrzuca jej spec, dopóki nie zostanie dodany jeden z nich.
Ten sam dokument z asystenta lub edytora
Dokument startowy ma te same bajty niezależnie od tego, która powierzchnia o niego prosi. Asystent AI połączony przez aggrega mcp uzyskuje go jako narzędzie scaffold, które zwraca dokument jako tekst wraz z danymi do odczytu maszynowego. Edytor korzystający z aggrega serve uzyskuje go przez aggrega/scaffoldEntity. Dokument jest wyprowadzany ze schematu jeden raz, więc dokument utworzony w terminalu i dokument przygotowany przez asystenta są identyczne co do bajtu.
Zapisywanie przykładów gotowych do uruchomienia i wyświetlanie ich listy jest dostępne w tych samych interfejsach, a nazwami pól są słowa samego polecenia. Aby zapisać przykład, należy wysłać do narzędzia scaffold lub do aggrega/scaffoldEntity pole example zamiast kind; pole dir, aby wskazać nowy katalog względem katalogu głównego obszaru roboczego — gdy go nie wysłano, jest to katalog nazwany od przykładu w tym miejscu — a samo list: true, aby otrzymać w odpowiedzi wszystkie przykłady. Przykład jest odczytywany z tego samego pakietu, weryfikowany według tej samej polityki i zapisywany przez to samo rozpakowanie, więc pliki i kolejne polecenia są takie same jak w terminalu, podobnie jak odmowy: katalog, który cokolwiek zawiera, wpis prowadzący poza katalog lub dowiązanie, pakiet nieakceptowany przez politykę, obszar roboczy offline bez niczego w pamięci podręcznej. Odpowiedź ma strukturę: dla listy — examples, każdy z name, level i summary; dla zapisu — example, dir, files — zapisane pliki, względem dir — next, polecenia podane na stronie przykładu, oraz version, wersja dokumentacji, z której odczytano przykład. Odpowiedź narzędzia scaffold na zapis zawiera też output_dir, położenie katalogu — pełne przez standardowe wejście i wyjście, aby asystent, który podał je względem obszaru roboczego, którego nie widzi, mógł odczytać, dokąd trafił przykład, a względne wobec katalogu głównego obszaru roboczego przez HTTP. Tekst narzędzia scaffold to opis, który wypisuje to polecenie, zakończony wierszem podającym to położenie, gdy różni się ono od dir. Pola dwóch form wysłane razem — na przykład kind z example — są odrzucane tymi samymi słowami w obu interfejsach, zanim cokolwiek zostanie odczytane. Edytor wskazuje obszar roboczy dla formy przykładu w workspaceRoot żądania, a dir musi być ścieżką względną, która pozostaje wewnątrz niego i nie prowadzi poza niego przez dowiązanie; przez HTTP narzędzie również ogranicza dir do obsługiwanego obszaru roboczego, a przez standardowe wejście i wyjście przyjmuje dir w podanej postaci, tak jak każdą ścieżkę. Indeks możliwości zgłasza narzędzie scaffold jako zapisujące, z powodu tej formy, a cli-scaffold, które uruchamia to polecenie w osobnym procesie, również jako zapisujące.
Zaczynanie od przykładu gotowego do uruchomienia
Dokumentacja zawiera przykłady gotowe do uruchomienia — każdy to katalog z encją Aggregate, jej encjami Releases i wszystkim innym, z czego jest budowany, wraz ze stroną opisującą, jak go zbudować. --example zapisuje jeden z nich do nowego katalogu, dzięki czemu można zacząć od działającego projektu, a nie od pustego:
aggrega scaffold --example redis-cacheWrote 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.Co jest zapisywane i gdzie. Pliki przykładu, w postaci, w jakiej zawiera je dokumentacja, trafiają do katalogu wskazanego jako drugi argument — albo, gdy żaden nie zostanie wskazany, do katalogu nazwanego od przykładu w folderze, w którym uruchomiono polecenie. Katalog nie może jeszcze istnieć lub musi być pusty. Wszystko inne jest odrzucane i pozostawiane dokładnie w dotychczasowym stanie: katalog zawierający plik, plik znajdujący się pod tą ścieżką lub dowiązanie. Nieistniejące jeszcze katalogi nadrzędne są tworzone. Żaden plik przykładu nie zostaje w innym miejscu i żaden nie trafia na swoje miejsce, zanim wszystkie nie zostaną zapisane: najpierw są zapisywane na boku, a przenoszone dopiero wtedy, gdy wszystkie są gotowe.
Polecenia wypisywane w następnej kolejności to te, które podaje strona samego przykładu: pierwszy blok sh, bash lub shell pod nagłówkiem ## Build strony, w postaci, w jakiej zapisała go strona, łącznie z komentarzami, poprzedzony poleceniem cd do tego katalogu. Dla przykładu, którego strona nie ma takiego bloku, odpowiedzią jest zamiast tego ścieżka do jego strony.
Jakie przykłady są dostępne. --list wypisuje każdy przykład, po jednym razie, w kolejności nauki przyjętej w dokumentacji — jego nazwę, poziom zadeklarowany przez jego stronę i pierwsze zdanie tej strony — i niczego nie zapisuje:
aggrega scaffold --example --listEXAMPLE 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....Lista jest własną listą przykładów dokumentacji, tą samą, która jest publikowana obok nich jako Przykłady według produktu i możliwości. Nazwa, pod którą pakiet nie zawiera żadnego przykładu, jest odrzucana ze wskazaniem --list i nic nie jest zapisywane.
Skąd pochodzą przykłady. Są odczytywane z pakietu dokumentacji — podpisanego archiwum opublikowanej dokumentacji, z którego aggrega explain odczytuje swoje omówienia — opublikowanego w domyślnym rejestrze obszaru roboczego. Odczytywany jest pakiet opublikowany dla uruchomionej wersji aggrega. Jeśli dla tej wersji żaden nie został opublikowany, odczytywany jest najnowszy pakiet opublikowany dla wcześniejszego wydania, a polecenie informuje o tym na standardowym wyjściu błędów:
note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before itKompilacja aggrega zbudowana z kilku commitów po wydaniu — taka, której aggrega version wygląda jak 0.9.0-12-g1a2b3c4d — odczytuje dokumentację wydania, po którym została zbudowana, tutaj 0.9.0, lub wcześniejszego, jeśli tamta nie została opublikowana. Kompilacja zbudowana z kilku commitów po wydaniu wstępnym, takim jak kandydat do wydania — taka, której aggrega version wygląda jak 0.9.0-rc.6-4-gc9db2f597 — odczytuje dokumentację tego wydania wstępnego, tutaj 0.9.0-rc.6, lub, jeśli tamta nie została opublikowana, najnowszą opublikowaną przed nim, wliczając wcześniejsze wydanie wstępne. Każda inna kompilacja odczytuje dokumentację wydania wstępnego tylko wtedy, gdy sama jest tym wydaniem wstępnym. Kompilacja bez numeru wydania odczytuje dokumentację własnej wersji albo żadną. aggrega explain w ten sam sposób wybiera pakiet, z którego odczytuje swoje omówienia krok po kroku.
Jeśli dla używanej wersji żaden pakiet nie został opublikowany, a najnowszy wcześniejszy ma format, którego ta wersja aggrega już nie odczytuje — na przykład w przypadku kandydata do wydania uruchomionego przed opublikowaniem jego własnej dokumentacji — polecenie odmawia, podając obie te informacje w jednym zdaniu, i niczego nie zapisuje:
[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 readPrzed użyciem jest weryfikowany. Pakiet jest pobierany z tymi samymi ustawieniami sieci co każdy inny odczyt z rejestru, a jego podpis jest sprawdzany względem polityki podpisów obszaru roboczego dla tego rejestru, zanim pakiet zostanie zachowany — i ponownie przed odczytaniem kopii, która już jest na maszynie, więc kopia wpuszczona przez luźniejszą politykę innego projektu nie zostanie użyta w ramach tej polityki. Pakiet, którego polityka nie akceptuje, jest odrzucany i nic nie jest zapisywane.
Jest pobierany raz na maszynę. Pakiet jest przechowywany w pamięci podręcznej współdzielonej przez wszystkie projekty Aggrega na maszynie — zob. aggrega cache — więc drugi przykład lub drugi projekt nie wymaga ponownego pobrania, a aggrega explain odczytuje tę samą kopię, gdy oba odczytują tę samą wersję.
W trybie offline odczytywane jest tylko to, co jest w pamięci podręcznej. W obszarze roboczym offline nic nie jest pobierane: przykład jest zapisywany z kopii, która już jest na maszynie i którą dopuszcza polityka — tej dla bieżącej wersji, a w przeciwnym razie najnowszej wcześniejszej z pamięci podręcznej — a gdy takiej nie ma, polecenie odmawia tą samą odmową offline, którą zwraca każdy odczyt sieciowy, wskazując, jak zezwolić na dostęp do sieci.
Pakiet zawierający coś nieoczekiwanego jest odrzucany w całości. Pakiet pochodzi z rejestru, więc rozpakowanie nie ufa niczemu w jego układzie: wpis, którego nazwa wskazywałaby miejsce poza wskazanym katalogiem lub poza pakietem, oraz wpis będący dowiązaniem lub czymkolwiek innym niż plik czy katalog — każdy z nich powoduje odrzucenie całego przykładu ze wskazaniem tego wpisu i nic nie jest zapisywane. Plik wykonywalny w przykładzie pozostaje wykonywalny.
Odczytywana jest konfiguracja obszaru roboczego. Pochodzą z niej domyślny rejestr i polityka podpisów, więc plik konfiguracyjny będący dowiązaniem prowadzącym poza obszar roboczy zatrzymuje formę przykładu, tak jak zatrzymuje każde inne polecenie odczytujące konfigurację — zob. granica obszaru roboczego.
Przykłady
Utworzenie nienazwanej encji Release i odczytanie jej w terminalu:
aggrega scaffold releaseUtworzenie encji Recipe bezpośrednio w pliku:
aggrega scaffold recipe postgres-helm > postgres-helm.yamlSprawdzenie, co pozostaje do uzupełnienia, przed wypełnieniem czegokolwiek:
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yamlAby sprawdzić, jakie przykłady gotowe do uruchomienia są dostępne, a następnie zapisać jeden z nich do wybranego katalogu:
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cacheCykl tworzenia, który rozpoczyna to polecenie — wygenerowanie struktury, wypełnienie symboli zastępczych, walidacja — opisano w rozdziale Tworzenie plików Aggrega.