Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

aggrega edit-document

Stosuje do dokumentu jedną ograniczoną edycję strukturalną, zachowując każdy bajt, którego nie dotyka

Składnia

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

Opis

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.

Flagi

FlagaDomyślnieOpis
--dry-runfalseWykonuje wszystko poza zapisem: zwraca edytowany dokument jako treść, wskazując plik, którego dotyczy, i niczego nie tworzy ani nie modyfikuje. Każde inne zachowanie jest takie samo jak przy zapisie, łącznie z bramką schematu. Bez tej flagi dokument zostaje zapisany
--name—Klucz, pod którym zapisywany jest nowy wpis: nazwa instancji komponentu, nazwa załącznika, alias połączenia lub klucz wartości
--node[]Jeden segment ścieżki strukturalnej do węzła, którego dotyczy edycja, liczonej od korzenia dokumentu. Należy ją powtórzyć raz dla każdego segmentu, zaczynając od najbardziej zewnętrznego. Przyjmuje po jednym segmencie zamiast jednej ścieżki rozdzielonej kropkami, ponieważ kropka jest dozwolonym znakiem w wpisywanej nazwie, więc złączona ścieżka mogłaby wskazać klucz, którego nikt nie napisał
--socket—Gniazdo zależności, wewnątrz którego podłączane jest połączenie. Odczytywane dla wire-edge i ignorowane w pozostałych przypadkach
--value—Zawartość wpisu, odczytywana jako skalar YAML. Jej znaczenie wynika z edycji: encja, której żąda wpis, węzeł, na który wskazuje połączenie, lub skalar, na który ustawiana jest wartość

Działanie

aggrega edit-document <edit> <file> stosuje jedną edycję strukturalną do dokumentu w obszarze roboczym i pozostawia każdy bajt, którego nie dotknęła, dokładnie w takiej postaci, w jakiej został zapisany. Najpierw podaje się nazwę edycji, a potem dokument:

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

Polecenie istnieje na wypadek, gdy wygodniej jest, by plik został zmieniony, niż by wskazano, gdzie go zmienić. Jeśli utrzymuje się własny bufor i własną historię cofania, aggrega serve zgłasza pozycję i pozwala samodzielnie wstawić tekst; to polecenie składa wpis i go zapisuje.

Dokument musi należeć do obszaru roboczego. Należy go wskazać względem katalogu głównego obszaru roboczego lub ścieżką bezwzględną; dokument spoza obszaru roboczego jest odrzucany bez odczytu i zapisu czegokolwiek, niezależnie od tego, czy tak zapisano ścieżkę, czy prowadzi do niego dowiązanie wychodzące poza obszar roboczy — dowiązanie do pliku albo katalog po drodze, który jest dowiązaniem. Edycja odczytuje dokument przed jego ponownym zapisaniem, więc dokument za takim dowiązaniem jest plikiem, którego obszar roboczy nie zawiera, i odmowa to stwierdza:

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"

Aby edytować dokument przechowywany gdzie indziej, należy uruchomić polecenie w obszarze roboczym, który go zawiera. Edycje serwera językowego i narzędzi asystenta podlegają tej samej zasadzie, ponieważ wszystkie trzy stosują jedną edycję. Jej dokument to jedyna wpisywana ścieżka, która jest ograniczona do obszaru roboczego, jak opisuje Granica obszaru roboczego.

Jedno wywołanie, jeden wpis, a zbiór jest zamknięty

Istnieją cztery edycje i żadnych innych:

EdycjaCo dodaje
add-componentinstancję komponentu w kontenerze komponentów
attach-featuredołączenie encji Feature do wskazanego węzła
wire-edgepołączenie w jednym z gniazd zależności tego węzła
set-valuejedną wartość we wskazanym węźle

Nie ma edycji, która usuwa, zastępuje już napisany blok, zmienia kolejność czegokolwiek lub zapisuje dosłownie podane bajty. To jest cały projekt, a nie ograniczenie go: nazwa spoza tych czterech nie ma żadnej drogi przez polecenie, więc nie jest to narzędzie do zapisu plików pod węższą nazwą. Nazwa spoza zbioru jest odrzucana, a nie interpretowana.

Wpis, który już istnieje i zawiera to, o co poproszono, jest operacją pustą — polecenie to zgłasza i niczego nie zapisuje:

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

Wpis o tej nazwie zawierający coś innego jest odrzucany, a nie zastępowany, ponieważ zastąpienie tego, co zostało napisane, nie należy do tych czterech edycji.

Węzeł wskazuje się jako ścieżkę, po jednym segmencie

--node powtarza się raz dla każdego segmentu ścieżki od korzenia dokumentu, zaczynając od najbardziej zewnętrznego:

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

Przyjmowanie po jednym segmencie zamiast jednej ścieżki rozdzielanej kropkami jest celowe, a powodem jest poprawność. Kropka jest dozwolonym znakiem w wpisywanej nazwie, więc nic poza dokumentem nie odróżni kropki strukturalnej od kropki wewnątrz nazwy. Połączona ścieżka wyglądałaby poprawnie, a wskazywałaby klucz, którego nikt nie napisał — a ponieważ add-component może utworzyć kontener, którego dokument nie zawiera, wpis trafiłby pod ten wymyślony klucz, zamiast zostać odrzucony. Segmenty usuwają niejednoznaczność, zamiast ją przenosić.

W przypadku add-component ścieżka wskazuje sam kontener komponentów, ponieważ dodawany wpis jest węzłem. W przypadku pozostałych trzech wskazuje węzeł, którego dotyczy edycja, a kontener wynika z edycji: dołączenie trafia pod features tego węzła, połączenie pod jego uses i wskazane gniazdo, a wartość pod jego values.

--name to klucz, pod którym zapisywany jest wpis — nazwa instancji, nazwa dołączenia, alias połączenia lub klucz wartości. --socket jest odczytywane dla wire-edge, a w pozostałych przypadkach ignorowane.

Wartość zachowuje typ, który niosą jej znaki

--value jest odczytywana jako skalar YAML, czyli tak samo, jak zostałyby odczytane te znaki, gdyby wpisano je bezpośrednio w dokumencie:

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

Tak więc --value 4 ustawia liczbę, --value true wartość logiczną, a --value '"4"' ciąg znaków 4 — cudzysłów oznacza tu „to jest tekst” dokładnie tak samo jak w dokumencie. Pominięcie --value nie ustawia niczego. Mapowanie lub sekwencja zostają odrzucone, ponieważ zapisanie ich oznaczałoby dodanie bloku, a to nie jest żadna z czterech edycji.

Wszystko, czego nie edytowano, pozostaje, a to samo żądanie daje te same bajty

Dokument jest parsowany wyłącznie w celu zlokalizowania kontenera i wiersza, w którym kończy się jego blok; wpis jest renderowany i wstawiany na poziomie wierszy. Komentarze, puste wiersze, styl cudzysłowów, skalary zwijane i dosłowne, wyrażenia szablonów oraz kształt końcowego znaku nowego wiersza przechodzą bez zmian, a krok zagnieżdżenia jest mierzony na podstawie wcięć samego dokumentu, a nie narzucany — dzięki temu wpis trafia do dokumentu w stylu, w którym jest on już pisany.

Dla tego samego dokumentu i tego samego żądania bajty są za każdym razem takie same. Można więc porównać dwa uruchomienia, a w przeglądzie jedna edycja odpowiada jednemu diffowi.

Wynik musi być dokumentem, który można by wpisać ręcznie

Od tego zależy zapis. Złożony dokument jest sprawdzany względem schematu jego własnego rodzaju, odczytanego z dokumentu, a nie podanego przez użytkownika, a bajty trafiają na dysk tylko wtedy, gdy to sprawdzenie się powiedzie. Żądanie, które dałoby wynik odrzucany przez schemat, zostaje odrzucone ze wskazaniem właściwości, której schemat by nie dopuścił, i miejsca, w którym występuje:

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"

Plik pozostaje bajt w bajt taki, jaki był, a sam zapis jest atomowy, więc odrzuconej lub przerwanej edycji nie da się odróżnić od takiej, której nigdy nie podjęto, i można ponowić poprawione żądanie względem dokumentu wyjściowego. Z tego też powodu nie powtarza się tu żadnej reguły tworzenia dokumentów: żądanie, by dokument Release zawierał wartość dewelopera, zostaje odrzucone przez ten sam schemat, który odrzuciłby dokument wpisany ręcznie.

To, co jest dopuszczalne semantycznie, nie jest tu rozstrzygane. To, czy gniazdo zależności jest gniazdem deklarowanym przez producenta lub czy warunki stosowalności encji Feature są spełnione, należy do rozwiązywania wykonywanego przez kompilację. Można więc wskazać połączenie, o którym to polecenie nigdy nie słyszało, a encja Aggregate może definiować gniazdo, którego jej encja katalogowa wcześniej nie deklaruje; to, co może być konsumowane przez gniazdo, pozostaje do zadeklarowania przez producenta. Gdy o to właśnie chodzi, należy uruchomić aggrega validate, wskazując encję Release.

Podgląd wyniku przed zapisaniem

--dry-run wykonuje wszystko to, co polecenie bez tej flagi, z wyjątkiem zapisu: edytowany dokument trafia na standardowe wyjście jako treść, ze wskazaniem pliku, którego dotyczy, i nic nie zostaje utworzone:

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

Bez tej flagi dokument zostaje zapisany. Domyślnym działaniem jest zapis, ponieważ produktem tego polecenia jest edytowany dokument, a polecenie, które go wytwarza, jest zobowiązane go dostarczyć — żądanie, które nic nie mówi o sposobie dostarczenia, edytuje plik.

Każde inne zachowanie jest takie samo jak przy zapisie, łącznie z bramką walidacji. Edycja, której wynik schemat by odrzucił, zostaje odrzucona również z --dry-run, ze wskazaniem tej samej właściwości i bez jakiejkolwiek zmiany pliku — dlatego kod wyjścia uzyskany z próbnego uruchomienia jest tym samym kodem wyjścia, który zwróciłby zapis.

Ta sama edycja z edytora lub asystenta

Bajty są takie same niezależnie od tego, która powierzchnia stosuje edycję. Edytor korzystający z aggrega serve sięga do niej przez aggrega/editDocument, a asystent AI połączony przez aggrega mcp sięga do niej jako narzędzie, pod którym to polecenie jest tam udostępnione. Wpis jest składany, wstawiany i poddawany bramce walidacji w jednym miejscu, a każda powierzchnia jest cienkim punktem wejścia do niego — dlatego dokument edytowany w terminalu i dokument, który edytuje edytor, są identyczne bajt w bajt.

Jedyne, czym powierzchnie się różnią, to bajty, które odczytują. To polecenie i metoda sesji odczytują plik na dysku, nigdy niezapisany bufor: zapis z bufora umieściłby na stronie niezapisaną treść pod pozorem zastosowania jednego wpisu. Najpierw należy zapisać plik, a dopiero potem edytować.

Przykłady

Dodanie instancji komponentu na najwyższym poziomie encji Aggregate:

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

Dołączenie encji Feature do komponentu zdefiniowanego wewnątrz podsystemu:

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

Ustawienie wartości w komponencie zdefiniowanym wewnątrz podsystemu:

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

Przejrzenie wyniku, zanim cokolwiek zostanie zapisane:

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

Aby sprawdzić, do którego kontenera należy wpis, zanim się go wskaże, oraz odczytać pozycję bez stosowania czegokolwiek, zob. aggrega serve.