aggrega scaffold
Ein Startdokument für eine Entitätsart entwerfen oder ein ausführbares Beispiel in ein neues Verzeichnis schreiben
Übersicht
aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]Beschreibung
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.Flags
| Flag | Standard | Beschreibung |
|---|---|---|
--example | false | schreibt das ausführbare Beispiel, das das Argument nennt, in ein neues Verzeichnis, gelesen aus dem signierten Dokumentationspaket |
--list | false | gibt mit —example jedes ausführbare Beispiel aus, das die Dokumentation veröffentlicht, und schreibt nichts |
Funktionsweise
Der Befehl hat zwei Formen. aggrega scaffold <kind> entwirft ein Startdokument aus dem Schema einer Art und gibt es aus; das beschreiben dieser Abschnitt und die nächsten drei. aggrega scaffold --example <name> schreibt stattdessen eines der ausführbaren Beispiele der Dokumentation in ein neues Verzeichnis – siehe Von einem ausführbaren Beispiel ausgehen.
aggrega scaffold <kind> gibt ein Startdokument für eine Entitätsart auf der Standardausgabe aus. Das Dokument enthält genau die Felder, die das Schema dieser Art verlangt: apiVersion und kind sind ausgefüllt, weil das Schema sie festlegt, und jeder andere erforderliche Wert bleibt als Platzhalter stehen, den Sie ersetzen.
Das optionale [name] belegt metadata.name vor, bei einer Art, deren Schema einen verlangt:
aggrega scaffold component my-serviceapiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-service version: "" labels: component.aggrega.ai/type: ""spec: {}Die Art ist das kleingeschriebene, mit Bindestrichen versehene Schema-Token — component, aggregate, release, recipe, manifest, feature und die übrigen. aggrega get-schema --list gibt die gesamte Menge aus, und ein Token, dem kein Schema entspricht, wird mit dieser Menge in der Meldung abgelehnt, sodass ein Tippfehler ohne zweites Nachschlagen korrigiert wird.
Was es zurückgibt und was nicht
Das Dokument stammt aus dem eigenen Vertrag der Art und aus nichts anderem. Es ist kein ausgearbeitetes Beispiel. Es gibt keinen Namespace, keine Kategorie, keine für Sie ausgefüllten Label-Werte und keinen auskommentierten Vorschlag dafür, was man üblicherweise schreibt — denn nichts davon verlangt der Compiler. Ein Katalog wählt seine eigene Benennung, seine eigenen Kategorien und sein eigenes Verzeichnislayout; das Schema bestimmt die Felder, und das Schema ist alles, was dieser Befehl liest. Ein Startdokument, das den Rest erriete, würde Ihnen eine Regel beibringen, die es nicht gibt.
Beim Entwerfen wird keine Datei geschrieben. Das Dokument geht auf die Standardausgabe, sodass eine Umleitung entscheidet, wo es landet, und nichts auf der Festplatte ersetzt wird, ohne dass Sie es verlangen:
aggrega scaffold component my-service > my-service.yamlEs ist keine fertige Entität, und genau das bedeutet ein Platzhalter. Ein leerer erforderlicher Wert ist kein Wert, daher lehnt aggrega validate, ausgeführt über das Dokument genau so, wie es ausgegeben wurde, es ab und nennt auf einmal jeden noch offenen Platzhalter, jeweils mit dem, was er annimmt — oben die Version und den Komponententyp:
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, resourceWas jeder Wert annimmt, wird aus dem eigenen Schema der Art gelesen: die Werte, die es akzeptiert, wo das Schema sie auflistet, eine semantische Version, wo es eine verlangt, und andernfalls die eigene Beschreibung des Feldes im Schema. Geben Sie diese Werte an, und derselbe Befehl akzeptiert das Dokument. An seiner Form muss sich nichts ändern, weil die Form aus dem Schema stammt.
Ein Wert ist auch dort offen, wo das Schema ihn leer akzeptieren würde. Ein entworfenes Recipe oder FeatureRecipe trägt leere capability und implements. Ihr Schema lässt eine leere Zeichenkette zu, doch eine leere benennt keinen Provider und keinen Typ, daher nennt aggrega validate beide als noch offen, bis Sie sie ausfüllen. Diese Lesart gehört zur Validierung einer einzelnen Entitätsdatei: Ein Lauf über den gesamten Katalog, aggrega validate --release und aggrega build wenden sie nicht an. Siehe noch offene Platzhalter für das, was sie abdeckt. Ein entworfenes Recipe deklariert außerdem keine der Eingabearten, von denen sein Schema mindestens eine verlangt — source, valuesMapping, workload oder artifacts —, weil die Wahl der passenden bei Ihnen liegt; daher lehnt aggrega validate seine spec ab, bis Sie eine hinzufügen.
Dasselbe Dokument von einem Assistenten oder Editor
Das Startdokument besteht aus denselben Bytes, gleich welche Oberfläche danach fragt. Ein über aggrega mcp verbundener KI-Assistent erreicht es als Werkzeug scaffold, das das Dokument als Text zusammen mit einer maschinenlesbaren Nutzlast zurückgibt. Ein Editor, der aggrega serve ansteuert, erreicht es unter aggrega/scaffoldEntity. Das Dokument wird einmal aus dem Schema abgeleitet, sodass das, das Sie an einem Terminal entwerfen, und das, das ein Assistent für Sie entwirft, Byte für Byte identisch sind.
Das Schreiben und Auflisten ausführbarer Beispiele steht auf denselben Oberflächen zur Verfügung, mit den eigenen Wörtern des Befehls als Feldnamen. Senden Sie dem Tool scaffold oder aggrega/scaffoldEntity example statt kind, um eines zu schreiben, dir, um das neue Verzeichnis relativ zur Workspace-Wurzel zu benennen — dort ein nach dem Beispiel benanntes Verzeichnis, wenn Sie keines senden —, und list: true allein, um als Antwort jedes Beispiel zu erhalten. Das Beispiel wird aus demselben Bundle gelesen, gegen dieselbe Richtlinie geprüft und von derselben Extraktion geschrieben, sodass die Dateien und die nächsten Befehle dieselben sind wie am Terminal, ebenso die Ablehnungen: ein Verzeichnis, das irgendetwas enthält, ein Eintrag, der aus dem Verzeichnis hinausführt oder ein Link ist, ein Bundle, das Ihre Richtlinie nicht akzeptiert, ein Offline-Workspace, in dessen Cache nichts liegt. Die Antwort ist strukturiert: für eine Liste examples, jedes mit seinem name, level und summary; für ein Schreiben example, dir, files — die geschriebenen Dateien, relativ zu dir —, next, die Befehle, die die Seite des Beispiels angibt, und version, die Version der Dokumentation, aus der das Beispiel gelesen wurde. Die Antwort des Tools scaffold auf ein Schreiben enthält außerdem output_dir, den Ort des Verzeichnisses — über Standardein- und -ausgabe vollständig, damit ein Assistent, der es relativ zu einem Workspace benannt hat, den er nicht sehen kann, liest, wohin das Beispiel geschrieben wurde, und über HTTP relativ zur Workspace-Wurzel. Der Text des Tools scaffold ist der Bericht, den dieser Befehl ausgibt, abgeschlossen von einer Zeile, die diesen Ort nennt, wo er von dir abweicht. Felder zweier Formen, die zusammen gesendet werden — etwa kind mit example —, werden auf beiden Oberflächen mit denselben Worten abgelehnt, bevor irgendetwas gelesen wird. Ein Editor nennt den Workspace für die Beispielform im workspaceRoot der Anfrage, und dir muss ein relativer Pfad sein, der darin bleibt und nicht über einen Link aus ihm hinausführt; über HTTP bindet das Tool dir ebenfalls an den Workspace, den es bedient, und über Standardein- und -ausgabe nimmt es dir so, wie es genannt ist, wie es jeden Pfad nimmt. Der Fähigkeitsindex weist das Tool scaffold wegen dieser Form als schreibend aus, und ebenso cli-scaffold, das diesen Befehl in einem separaten Prozess ausführt.
Von einem ausführbaren Beispiel ausgehen
Die Dokumentation enthält ausführbare Beispiele — jedes ein Verzeichnis mit einem Aggregate, seinen Releases und allem anderen, woraus es gebaut wird, dazu eine Seite, die beschreibt, wie es gebaut wird. --example schreibt eines davon in ein neues Verzeichnis, sodass Sie von einem funktionierenden Projekt statt von einem leeren ausgehen können:
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.Was es schreibt, und wohin. Die Dateien des Beispiels, so wie die Dokumentation sie enthält, in das Verzeichnis, das Sie als zweites Argument nennen — oder, wenn Sie keines nennen, in ein nach dem Beispiel benanntes Verzeichnis in dem Ordner, in dem Sie den Befehl ausführen. Das Verzeichnis darf noch nicht existieren oder muss leer sein. Alles andere wird abgelehnt und genau so belassen, wie es war: ein Verzeichnis, das eine Datei enthält, eine Datei, die unter diesem Pfad liegt, oder ein Link. Darüberliegende Verzeichnisse, die noch nicht existieren, werden angelegt. Keine Datei des Beispiels bleibt anderswo zurück, und keine wird an ihren Platz gestellt, bevor alle geschrieben sind: Sie werden zuerst beiseite geschrieben und hineinverschoben, sobald jede von ihnen da ist.
Die Befehle, die es danach ausgibt, sind diejenigen, die die eigene Seite des Beispiels angibt: der erste Block sh, bash oder shell unter der Überschrift ## Build der Seite, so wie die Seite ihn schreibt, Kommentare eingeschlossen, nach einem cd in das Verzeichnis. Für ein Beispiel, dessen Seite keinen solchen Block hat, wird stattdessen der Pfad seiner Seite ausgegeben.
Welche Beispiele es gibt. --list gibt jedes Beispiel einmal aus, in der Reihenfolge, in der die Dokumentation sie lehrt — seinen Namen, die Stufe, die seine Seite deklariert, und den ersten Satz seiner Seite — und schreibt nichts:
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....Die Liste ist die eigene Beispielliste der Dokumentation, dieselbe, die neben ihnen als Beispiele nach Produkt und Fähigkeit veröffentlicht ist. Ein Name, unter dem das Bundle kein Beispiel enthält, wird mit einem Verweis auf --list abgelehnt, und nichts wird geschrieben.
Woher die Beispiele kommen. Sie werden aus dem Dokumentations-Bundle gelesen — dem signierten Archiv der veröffentlichten Dokumentation, aus dem aggrega explain seine Schritt-für-Schritt-Erklärungen liest —, das in der Standard-Registry Ihres Workspace veröffentlicht ist. Gelesen wird das Bundle, das für die Version von aggrega veröffentlicht ist, die Sie ausführen. Ist für diese Version keines veröffentlicht, ist es das neueste, das für eine frühere Version veröffentlicht wurde, und der Befehl meldet dies auf der Standardfehlerausgabe:
note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before itEin Build von aggrega, der aus einigen Commits nach einer Version erstellt wurde — einer, dessen aggrega version etwa 0.9.0-12-g1a2b3c4d lautet —, liest die Dokumentation der Version, nach der er gebaut wurde, hier 0.9.0, oder die einer früheren, wo diese nicht veröffentlicht ist. Ein Build, der aus einigen Commits nach einer Vorabversion wie etwa einem Versionskandidaten erstellt wurde — einer, dessen aggrega version etwa 0.9.0-rc.6-4-gc9db2f597 lautet —, liest die Dokumentation dieser Vorabversion, hier 0.9.0-rc.6, oder, wo diese nicht veröffentlicht ist, die neueste davor veröffentlichte, eine frühere Vorabversion eingeschlossen. Jeder andere Build liest die Dokumentation einer Vorabversion nur, wenn er selbst diese Vorabversion ist. Ein Build, der keine Versionsnummer trägt, liest die Dokumentation seiner eigenen Version oder keine. aggrega explain wählt das Paket, aus dem es seine Schritt-für-Schritt-Erläuterungen liest, auf dieselbe Weise.
Wo für Ihre Version keines veröffentlicht ist und das neueste frühere in einem Format vorliegt, das diese Version von aggrega nicht mehr liest – etwa bei einer Vorabversion, die ausgeführt wird, bevor ihre eigene Dokumentation veröffentlicht ist –, verweigert der Befehl den Vorgang, nennt beides in einem Satz, und nichts wird geschrieben:
[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 readEs wird vor der Verwendung geprüft. Das Bundle wird über dieselben Netzwerkeinstellungen abgerufen wie jeder andere Registry-Lesevorgang, und seine Signatur wird gegen die Signaturrichtlinie Ihres Workspace für diese Registry geprüft, bevor es aufbewahrt wird — und erneut, bevor eine bereits auf dem Rechner vorhandene Kopie gelesen wird, sodass eine Kopie, die die lockerere Richtlinie eines anderen Projekts zugelassen hat, unter Ihrer nicht verwendet wird. Ein Bundle, das Ihre Richtlinie nicht akzeptiert, wird abgelehnt, und nichts wird geschrieben.
Es wird einmal pro Rechner abgerufen. Das Bundle wird im Cache aufbewahrt, den sich jedes Aggrega-Projekt auf dem Rechner teilt — siehe aggrega cache —, sodass ein zweites Beispiel oder ein zweites Projekt keinen zweiten Download braucht, und aggrega explain liest dieselbe Kopie, wo beide dieselbe Version lesen.
Offline liest es nur, was zwischengespeichert ist. In einem Offline-Workspace wird nichts abgerufen: Ein Beispiel wird aus einer bereits auf dem Rechner vorhandenen Kopie geschrieben, die Ihre Richtlinie zulässt — der für diese Version oder sonst der neuesten früheren im Cache —, und gibt es keine, lehnt der Befehl mit der Offline-Ablehnung ab, die jeder Netzwerk-Lesevorgang gibt, und nennt, wie das Netzwerk zugelassen wird.
Ein Bundle, das etwas Unerwartetes enthält, wird als Ganzes abgelehnt. Das Bundle stammt aus einer Registry, daher vertraut die Extraktion nichts an seinem Aufbau: Ein Eintrag, dessen Name außerhalb des von Ihnen genannten Verzeichnisses oder außerhalb des Bundles landen würde, und ein Eintrag, der ein Link oder etwas anderes als eine Datei oder ein Verzeichnis ist, lehnen jeweils das ganze Beispiel ab, wobei der Eintrag genannt wird, und nichts wird geschrieben. Eine ausführbare Datei im Beispiel bleibt ausführbar.
Die Konfiguration des Workspace wird gelesen. Die Standard-Registry und die Signaturrichtlinie stammen aus ihr, sodass eine Konfigurationsdatei, die ein aus dem Workspace hinausführender Link ist, die Beispielform so stoppt, wie sie jeden anderen Befehl stoppt, der die Konfiguration liest — siehe die Workspace-Grenze.
Beispiele
Ein unbenanntes Release entwerfen und im Terminal lesen:
aggrega scaffold releaseEin Recipe direkt in eine Datei entwerfen:
aggrega scaffold recipe postgres-helm > postgres-helm.yamlPrüfen, was Sie noch schulden, bevor Sie etwas ausfüllen:
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yamlSehen Sie nach, welche ausführbaren Beispiele es gibt, und schreiben Sie dann eines in ein Verzeichnis Ihrer Wahl:
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cacheFür den Authoring-Zyklus, den dieser Befehl beginnt — die Form entwerfen, die Platzhalter ausfüllen, validieren —, siehe Aggrega-Dateien verfassen.