Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

aggrega edit-document

Eine begrenzte strukturierte Änderung auf ein Dokument anwenden und dabei jedes Byte erhalten, das sie nicht berührt

Übersicht

aggrega edit-document <edit> <file> [flags]

Beschreibung

Apply one bounded structured edit to a document in the workspace.
The edit is named first and the document second. One call adds one entry under one container, or sets one scalar, and it can do nothing else:
add-component add a component instance under a components container
attach-feature attach a Feature to the node you name
wire-edge wire a connection inside one of that node's sockets
set-value set one value on that node
There is no edit that deletes, replaces a block you already wrote, reorders anything, or writes bytes you supply verbatim. The edits this command applies are add-component, attach-feature, wire-edge, set-value, and a name outside that set is refused rather than interpreted.
Name the node with --node, once per path segment, from the document root. It is a segment at a time rather than one dotted string because a dot is a legal character in a name you type, so a joined path could address a key nobody wrote and the entry would be created there rather than refused:
aggrega edit-document add-component app.yaml \
--node spec --node components --name web --value example/service
aggrega edit-document wire-edge app.yaml \
--node spec --node components --node web \
--socket database --name db --value spec.components.store
For add-component the path names the components container itself, because the entry being added is the node. For the other three it names the node the edit is about, and the container follows from the edit.
--name is the key the entry is written under: the instance name, the attachment's name, the connection's alias, or the value's key. --value is what that entry carries, and what it means follows from the edit — the entity the entry requests, the node a connection points at, or the scalar a value is set to. It is read as a YAML scalar, so --value 3 sets a number, --value true a boolean, and --value '"3"' the string; omitting it sets nothing at all.
Every byte the edit does not touch survives. The document is parsed only to locate the container and the line its block ends at, so comments, blank lines, quoting style, folded and literal scalars and the trailing-newline shape all carry through, and the nesting step is measured from the document's own indentation rather than imposed. The same request against the same document produces the same bytes.
The result has to be a document you could have typed, and that is what the write is gated on: the composed document is checked against its own kind's schema and reaches disk only if that passes. A request that would produce something the schema refuses is refused, naming the property the schema would not admit and where, and the file is left byte-for-byte as it was — so a refused edit is indistinguishable from one never attempted and you can retry a corrected request against the document you started with.
An entry that is already there, carrying what you asked for, is a no-op. An entry of that name carrying something else is refused rather than replaced.
--dry-run does everything the plain command does except write: the edited document goes to standard output as content, naming the file it is for, and nothing is created — for a caller that puts the result in front of someone before it is saved. Every other behaviour is the write's, the schema gate included, so a request the write would refuse is refused under --dry-run too and its exit code predicts the write's. Without it the document is written.
Whether what you wire is semantically admissible is not decided here. Whether a socket is one the producer declares, or whether a Feature's applicability is satisfied, is what aggrega validate answers.

Flags

FlagStandardBeschreibung
--dry-runfalseAlles außer dem Schreiben ausführen: das bearbeitete Dokument als Inhalt zurückgeben, unter Angabe der Datei, für die es bestimmt ist, und nichts erstellen oder ändern. Jedes andere Verhalten entspricht dem des Schreibens, einschließlich der Schema-Prüfung. Ohne diese Option wird das Dokument geschrieben
--name—Der Schlüssel, unter dem der neue Eintrag geschrieben wird: der Name der Komponenteninstanz, der Name der Anbindung, der Alias der Verbindung oder der Schlüssel des Werts
--node[]Ein Segment des strukturellen Pfads zu dem Knoten, den die Bearbeitung betrifft, ausgehend von der Dokumentwurzel. Wiederholen Sie die Option einmal pro Segment, das äußerste zuerst. Sie nimmt jeweils ein Segment statt eines einzigen Pfads mit Punkten entgegen, weil ein Punkt ein zulässiges Zeichen in einem eingegebenen Namen ist, sodass ein zusammengesetzter Pfad einen Schlüssel adressieren könnte, den niemand geschrieben hat
--socket—Der Abhängigkeits-Socket, in dem eine Verbindung verdrahtet ist. Wird für wire-edge gelesen und andernfalls ignoriert
--value—Was der Eintrag enthält, gelesen als YAML-Skalar. Seine Bedeutung ergibt sich aus der Bearbeitung: die Entität, die der Eintrag anfordert, der Knoten, auf den eine Verbindung zeigt, oder der Skalar, auf den ein Wert gesetzt wird

Funktionsweise

aggrega edit-document <edit> <file> wendet eine strukturierte Bearbeitung auf ein Dokument in Ihrem Workspace an und lässt jedes Byte, das sie nicht berührt hat, genau so, wie Sie es geschrieben haben. Zuerst wird die Bearbeitung angegeben, dann das Dokument:

Terminal window
aggrega edit-document add-component storefront.aggregate.yaml \
--node spec --node components \
--name checkout --value core/api-server:1.0.0

Er ist für den Fall gedacht, in dem Sie die Datei lieber bearbeiten lassen möchten, als gesagt zu bekommen, wo sie zu bearbeiten ist. Wenn Sie Ihren eigenen Puffer und Ihren eigenen Rückgängig-Verlauf verwalten, meldet aggrega serve eine Position und lässt Sie den Text selbst einfügen; dieser Befehl stellt den Eintrag zusammen und schreibt ihn.

Das Dokument ist eines, das Ihr Workspace enthält. Geben Sie es relativ zur Workspace-Wurzel oder über seinen absoluten Pfad an; eines außerhalb des Workspace wird abgelehnt, ohne dass etwas gelesen oder geschrieben wird, unabhängig davon, ob es so angegeben oder über einen Link erreicht wird, der aus dem Workspace hinausführt – einen Link auf die Datei oder ein Verzeichnis auf dem Weg, das ein Link ist. Eine Bearbeitung liest das Dokument, bevor sie es zurückschreibt, daher ist ein Dokument hinter einem solchen Link eine Datei, die der Workspace nicht enthält, und die Ablehnung sagt dies:

the document named leads outside the workspace through a link, and an edit is only applied to a document the workspace carries: "shared/storefront.aggregate.yaml"

Um ein Dokument zu bearbeiten, das anderswo liegt, führen Sie den Befehl in dem Workspace aus, der es enthält. Die Bearbeitungen des Language Servers und der Assistenten-Tools wenden dieselbe Regel an, weil alle drei eine einzige Bearbeitung anwenden. Ihr Dokument ist der eine Pfad, den Sie eingeben, der an den Workspace gebunden ist, wie Die Workspace-Grenze darlegt.

Ein Aufruf, ein Eintrag, und die Menge ist abgeschlossen

Es gibt vier Bearbeitungen und keine anderen:

BearbeitungWas sie hinzufügt
add-componenteine Komponenteninstanz unter einem Komponenten-Container
attach-featureeine Feature-Anbindung an dem Knoten, den Sie angeben
wire-edgeeine Verbindung in einem der Abhängigkeits-Sockets dieses Knotens
set-valueein Wert an dem Knoten, den Sie angeben

Es gibt keine Bearbeitung, die löscht, einen bereits geschriebenen Block ersetzt, etwas neu anordnet oder von Ihnen gelieferte Bytes wörtlich schreibt. Das ist das gesamte Design und keine Einschränkung davon: Ein Name außerhalb der vier hat überhaupt keinen Weg durch den Befehl, daher ist dies kein Dateischreiber unter einem engeren Namen. Ein Name außerhalb der Menge wird abgelehnt statt interpretiert.

Ein Eintrag, der bereits vorhanden ist und das enthält, was Sie angefordert haben, bewirkt nichts – der Befehl sagt dies und schreibt nichts:

storefront.aggregate.yaml already carries that entry; nothing was written

Ein Eintrag dieses Namens, der etwas anderes enthält, wird abgelehnt statt ersetzt, weil das Ersetzen dessen, was Sie geschrieben haben, nicht zu den vier gehört.

Sie geben den Knoten als Pfad an, Segment für Segment

--node wird einmal pro Segment des Pfads ab der Dokumentwurzel wiederholt, das äußerste zuerst:

Terminal window
aggrega edit-document wire-edge storefront.aggregate.yaml \
--node spec --node components --node web \
--socket database --name replica --value store

Die Option nimmt bewusst jeweils ein Segment statt eines einzigen Pfads mit Punkten entgegen, und der Grund ist einer der Korrektheit. Ein Punkt ist ein zulässiges Zeichen in einem eingegebenen Namen, daher kann nichts außerhalb des Dokuments einen strukturellen Punkt von einem Punkt innerhalb eines Namens unterscheiden. Ein zusammengesetzter Pfad würde korrekt gelesen und einen Schlüssel adressieren, den niemand geschrieben hat – und weil add-component einen Container anlegen kann, den das Dokument nicht enthält, würde der Eintrag unter diesem erfundenen Schlüssel landen, statt abgelehnt zu werden. Segmente beseitigen die Mehrdeutigkeit, statt sie zu verlagern.

Bei add-component benennt der Pfad den Komponenten-Container selbst, weil der hinzugefügte Eintrag der Knoten ist. Bei den anderen drei benennt er den Knoten, den die Bearbeitung betrifft, und der Container ergibt sich aus der Bearbeitung: Eine Anbindung kommt unter features dieses Knotens, eine Verbindung unter sein uses und den angegebenen Socket, ein Wert unter sein values.

--name ist der Schlüssel, unter dem der Eintrag geschrieben wird – der Instanzname, der Name der Anbindung, der Alias der Verbindung oder der Schlüssel des Werts. --socket wird für wire-edge gelesen und andernfalls ignoriert.

Ein Wert behält den Typ, den seine Zeichen tragen

--value wird als YAML-Skalar gelesen, also genauso, wie die Zeichen gelesen würden, wenn Sie sie in das Dokument eingegeben hätten:

Terminal window
aggrega edit-document set-value storefront.aggregate.yaml \
--node spec --node components --node web --name workers --value 4
values:
replicas: 3
workers: 4

So setzt --value 4 eine Zahl, --value true einen booleschen Wert und --value '"4"' die Zeichenkette 4 – Anführungszeichen besagen hier „dies ist Text“, genau wie im Dokument. Wird --value weggelassen, wird überhaupt nichts gesetzt. Eine Mapping- oder eine Sequenzstruktur wird abgelehnt, weil das Schreiben einer solchen das Hinzufügen eines Blocks wäre, und das gehört nicht zu den vier Bearbeitungen.

Alles, was Sie nicht bearbeitet haben, bleibt erhalten, und dieselbe Anfrage erzeugt dieselben Bytes

Das Dokument wird nur geparst, um den Container und die Zeile zu finden, an der sein Block endet; der Eintrag wird gerendert und auf Zeilenebene eingefügt. Kommentare, Leerzeilen, Anführungsstil, gefaltete und literale Skalare, Template-Ausdrücke und die Form des abschließenden Zeilenumbruchs bleiben unverändert erhalten, und die Einrückungsstufe wird aus der eigenen Einrückung des Dokuments ermittelt, statt vorgegeben zu werden – so landet ein Eintrag in dem Stil, in dem Sie bereits schreiben.

Bei demselben Dokument und derselben Anfrage sind die Bytes jedes Mal dieselben. So können Sie zwei Läufe vergleichen, und ein Review liest eine Bearbeitung als einen Diff.

Das Ergebnis muss ein Dokument sein, das Sie selbst hätten tippen können

Daran ist das Schreiben gebunden. Das zusammengesetzte Dokument wird gegen das Schema seiner eigenen Art geprüft, das aus dem Dokument gelesen und nicht von Ihnen geliefert wird, und die Bytes gelangen nur dann auf die Festplatte, wenn diese Prüfung besteht. Eine Anfrage, die etwas erzeugen würde, das das Schema ablehnt, wird abgelehnt, unter Angabe der Eigenschaft, die das Schema nicht zulassen würde, und der Stelle:

the edit was refused because the resulting document would not be valid, and nothing
was written: document envelope validation failed (Release, at prod.release.yaml);
15:7: spec.components.web.values: … unexpected property: "values"

Die Datei bleibt Byte für Byte so, wie sie war, und das Schreiben selbst ist atomar, sodass eine abgelehnte oder unterbrochene Bearbeitung nicht von einer nie versuchten zu unterscheiden ist und Sie eine korrigierte Anfrage gegen das Ausgangsdokument erneut ausführen können. Deshalb wird hier auch keine Authoring-Regel wiederholt: Die Anforderung, dass ein Release-Dokument einen Entwicklerwert enthalten soll, wird von demselben Schema abgelehnt, das auch das von Hand geschriebene Dokument ablehnen würde.

Was semantisch zulässig ist, wird hier nicht entschieden. Ob ein Abhängigkeits-Socket einer ist, den der Produzent deklariert, oder ob die Anwendbarkeit eines Feature erfüllt ist, gehört zur Auflösung, die ein Build durchführt. Sie können also eine Verbindung angeben, von der dieser Befehl nie gehört hat, und ein Aggregate kann einen Socket verfassen, den seine Katalogentität nicht vorab deklariert; was über einen Socket konsumiert werden darf, bleibt Sache des Produzenten, es zu deklarieren. Führen Sie aggrega validate mit Angabe eines Release aus, wenn das die Frage ist.

Das Ergebnis sehen, bevor es gespeichert wird

--dry-run tut alles, was der einfache Befehl tut, außer zu schreiben: Das bearbeitete Dokument geht als Inhalt an die Standardausgabe, unter Angabe der Datei, für die es bestimmt ist, und es wird nichts erstellt:

Terminal window
aggrega edit-document attach-feature storefront.aggregate.yaml \
--node spec --node components --node web \
--name tls --value core/tls:1.0.0 --dry-run
documents:
- path: storefront.aggregate.yaml
content: |
# The storefront application.
...

Ohne diese Option wird das Dokument geschrieben. Standard ist das Schreiben, weil das Produkt dieses Befehls ein bearbeitetes Dokument ist und ein Befehl, der eines erzeugt, es auch liefern muss – eine Anfrage, die nichts über die Zustellung sagt, bearbeitet die Datei.

Jedes andere Verhalten entspricht dem des Schreibens, einschließlich der Validierungsprüfung. Eine Bearbeitung, deren Ergebnis das Schema ablehnen würde, wird auch unter --dry-run abgelehnt, unter Angabe derselben Eigenschaft und ohne Änderung der Datei – der Exit-Code eines Probelaufs ist also der Exit-Code, den Ihnen das Schreiben geliefert hätte.

Dieselbe Bearbeitung aus einem Editor oder einem Assistenten

Die Bytes sind dieselben, gleich welche Oberfläche die Bearbeitung anwendet. Ein Editor, der aggrega serve ansteuert, erreicht sie unter aggrega/editDocument, und ein über aggrega mcp verbundener KI-Assistent erreicht sie als das Tool, unter dem dieser Befehl dort bereitgestellt wird. Der Eintrag wird an einer einzigen Stelle zusammengesetzt, eingefügt und an die Validierung gebunden, und jede Oberfläche ist ein schlanker Einstiegspunkt dorthin – so sind das Dokument, das Sie im Terminal bearbeiten, und das Dokument, das ein Editor für Sie bearbeitet, Byte für Byte identisch.

Der einzige Unterschied zwischen den Oberflächen besteht darin, welche Bytes sie lesen. Dieser Befehl und die Sitzungsmethode lesen beide die Datei auf der Festplatte, nie einen ungespeicherten Puffer: Aus einem Puffer zu schreiben, würde Inhalte, die Sie nicht gespeichert haben, unter dem Anschein, einen einzigen Eintrag anzuwenden, auf die Seite bringen. Erst speichern, dann bearbeiten.

Beispiele

Eine Komponenteninstanz auf der obersten Ebene eines Aggregate hinzufügen:

Terminal window
aggrega edit-document add-component storefront.aggregate.yaml \
--node spec --node components --name checkout --value core/api-server:1.0.0

Ein Feature an eine Komponente anbinden, die innerhalb eines Subsystems verfasst ist:

Terminal window
aggrega edit-document attach-feature storefront.aggregate.yaml \
--node spec --node subsystems --node billing --node components --node ledger \
--name audit-log --value core/observability/audit-log:1.0.0

Einen Wert auf einer Komponente setzen, die innerhalb eines Subsystems verfasst ist:

Terminal window
aggrega edit-document set-value storefront.aggregate.yaml \
--node spec --node subsystems --node billing --node components --node ledger \
--name replicas --value 5

Das Ergebnis prüfen, bevor etwas geschrieben wird:

Terminal window
aggrega edit-document wire-edge storefront.aggregate.yaml \
--node spec --node components --node web \
--socket cache --name sessions --value redis --dry-run

Um herauszufinden, in welchen Container ein Eintrag gehört, bevor Sie einen angeben, und um eine Position zu lesen, ohne etwas anzuwenden, siehe aggrega serve.