aggrega edit-document
Applica a un documento una modifica strutturata e circoscritta, preservando ogni byte che non tocca
Sinossi
aggrega edit-document <edit> <file> [flags]Descrizione
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.Flag
| Flag | Predefinito | Descrizione |
|---|---|---|
--dry-run | false | Fa tutto tranne scrivere: restituisce il documento modificato come contenuto, indicando il file a cui è destinato, e non crea né modifica nulla. Ogni altro comportamento è quello della scrittura, controllo dello schema incluso. Senza di esso il documento viene scritto |
--name | — | La chiave sotto cui viene scritta la nuova voce: il nome dell’istanza del componente, il nome dell’allegato, l’alias della connessione o la chiave del valore |
--node | [] | Un segmento del percorso strutturale verso il nodo a cui si riferisce la modifica, a partire dalla radice del documento. Ripetilo una volta per segmento, partendo dal più esterno. Accetta un segmento alla volta invece di un unico percorso puntato perché il punto è un carattere valido in un nome che scrivi, quindi un percorso unito potrebbe indirizzare una chiave che nessuno ha scritto |
--socket | — | Il socket di dipendenza all’interno del quale è collegata una connessione. Letto per wire-edge e ignorato altrimenti |
--value | — | Ciò che la voce contiene, letto come scalare YAML. Il suo significato dipende dalla modifica: l’entità richiesta dalla voce, il nodo a cui punta una connessione o lo scalare a cui viene impostato un valore |
Cosa fa
aggrega edit-document <edit> <file> applica una modifica strutturata a un documento nel tuo workspace e lascia ogni byte che non ha toccato esattamente come l’hai scritto. Si indica prima la modifica e poi il documento:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components \ --name checkout --value core/api-server:1.0.0Esiste per il caso in cui preferisci che il file venga modificato piuttosto che sentirti dire dove modificarlo. Se gestisci il tuo buffer e la tua cronologia di annullamento, aggrega serve riporta una posizione e ti lascia inserire il testo da solo; questo comando compone la voce e la scrive.
Il documento è uno che il tuo workspace contiene. Indicalo relativamente alla radice del workspace o con il suo percorso assoluto; uno esterno al workspace viene rifiutato senza leggere né scrivere nulla, sia che sia scritto così sia che venga raggiunto tramite un link che porta fuori dal workspace — un link al file, o una directory lungo il percorso che è un link. Una modifica legge il documento prima di riscriverlo, quindi un documento dietro un tale link è un file che il workspace non contiene, e il rifiuto lo dice:
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"Per modificare un documento conservato altrove, esegui il comando nel workspace che lo contiene. Le modifiche del language server e degli strumenti dell’assistente applicano la stessa regola, perché tutti e tre applicano un’unica modifica. Il suo documento è l’unico percorso che scrivi a essere vincolato al workspace, come spiega Il confine del workspace.
Una chiamata, una voce, e l’insieme è chiuso
Ci sono quattro modifiche e nessun’altra:
| Modifica | Cosa aggiunge |
|---|---|
add-component | un’istanza di componente sotto un contenitore di componenti |
attach-feature | un allegato di una Feature sul nodo che indichi |
wire-edge | una connessione all’interno di uno dei socket di dipendenza di quel nodo |
set-value | un valore sul nodo che indichi |
Non esiste alcuna modifica che elimini, sostituisca un blocco che hai già scritto, riordini qualcosa o scriva testualmente byte forniti da te. Questo è il design nel suo insieme, non una sua restrizione: un nome al di fuori dei quattro non ha alcun percorso attraverso il comando, quindi questo non è uno scrittore di file con un nome più ristretto. Un nome al di fuori dell’insieme viene rifiutato anziché interpretato.
Una voce già presente, che contiene ciò che hai chiesto, non ha effetto — il comando lo dice e non scrive nulla:
storefront.aggregate.yaml already carries that entry; nothing was writtenUna voce con quel nome che contiene qualcos’altro viene rifiutata anziché sostituita, perché sostituire ciò che hai scritto non è una delle quattro.
Indichi il nodo come percorso, un segmento alla volta
--node si ripete una volta per ogni segmento del percorso dalla radice del documento, partendo dal più esterno:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket database --name replica --value storeAccetta un segmento alla volta invece di un unico percorso puntato di proposito, e la ragione è di correttezza. Il punto è un carattere valido in un nome che scrivi, quindi nulla al di fuori del documento può distinguere un punto strutturale da uno interno a un nome. Un percorso unito verrebbe letto correttamente e indirizzerebbe una chiave che nessuno ha scritto — e poiché add-component può creare un contenitore che il documento non contiene, la voce finirebbe sotto quella chiave inventata invece di essere rifiutata. I segmenti eliminano l’ambiguità invece di spostarla.
Per add-component il percorso indica il contenitore dei componenti stesso, perché la voce che si aggiunge è il nodo. Per le altre tre indica il nodo a cui si riferisce la modifica, e il contenitore deriva dalla modifica: un allegato va sotto features di quel nodo, una connessione sotto il suo uses e il socket che hai indicato, un valore sotto il suo values.
--name è la chiave sotto cui viene scritta la voce — il nome dell’istanza, il nome dell’allegato, l’alias della connessione o la chiave del valore. --socket viene letto per wire-edge e ignorato altrimenti.
Un valore mantiene il tipo che i suoi caratteri esprimono
--value viene letto come scalare YAML, che è lo stesso modo in cui verrebbero letti i caratteri se li avessi scritti nel documento:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node components --node web --name workers --value 4 values: replicas: 3 workers: 4Quindi --value 4 imposta un numero, --value true un booleano e --value '"4"' la stringa 4 — le virgolette dicono «questo è testo» qui esattamente come nel documento. Omettere --value non imposta nulla. Una mappa o una sequenza viene rifiutata, perché scriverla significherebbe aggiungere un blocco, e questa non è una delle quattro modifiche.
Tutto ciò che non hai modificato sopravvive, e la stessa richiesta produce gli stessi byte
Il documento viene analizzato solo per individuare il contenitore e la riga in cui termina il suo blocco; la voce viene resa e inserita a livello di riga. Commenti, righe vuote, stile delle virgolette, scalari folded e literal, espressioni di template e la forma del newline finale passano tutti invariati, e il passo di annidamento viene misurato dall’indentazione del documento stesso invece di essere imposto — così una voce finisce nello stile in cui stai già scrivendo.
Dati lo stesso documento e la stessa richiesta, i byte sono gli stessi ogni volta. Così puoi confrontare due esecuzioni, e una review legge una modifica come un unico diff.
Il risultato deve essere un documento che avresti potuto scrivere a mano
È questa la condizione per la scrittura. Il documento composto viene verificato rispetto allo schema del suo tipo, letto dal documento invece che fornito da te, e i byte raggiungono il disco solo se la verifica passa. Una richiesta che produrrebbe qualcosa che lo schema rifiuta viene rifiutata, indicando la proprietà che lo schema non ammetterebbe e dove:
the edit was refused because the resulting document would not be valid, and nothingwas written: document envelope validation failed (Release, at prod.release.yaml);15:7: spec.components.web.values: … unexpected property: "values"Il file resta byte per byte com’era, e la scrittura stessa è atomica, quindi una modifica rifiutata o interrotta è indistinguibile da una mai tentata e puoi riprovare una richiesta corretta sul documento da cui eri partito. È anche il motivo per cui qui non viene ripetuta alcuna regola di authoring: chiedere a un documento Release di contenere un valore dello sviluppatore viene rifiutato dallo stesso schema che rifiuterebbe il documento scritto a mano.
Ciò che è semanticamente ammissibile non si decide qui. Se un socket di dipendenza è uno che il produttore dichiara, o se l’applicabilità di una Feature è soddisfatta, spetta alla risoluzione eseguita da una build. Quindi puoi indicare una connessione di cui questo comando non ha mai sentito parlare, e un Aggregate può scrivere un socket che la sua entità di catalogo non predichiara; ciò che può essere consumato attraverso un socket resta da dichiarare al produttore. Esegui aggrega validate indicando una Release quando la domanda è questa.
Vedere il risultato prima che venga salvato
--dry-run fa tutto ciò che fa il comando semplice tranne scrivere: il documento modificato va sullo standard output come contenuto, indicando il file a cui è destinato, e non viene creato nulla:
aggrega edit-document attach-feature storefront.aggregate.yaml \ --node spec --node components --node web \ --name tls --value core/tls:1.0.0 --dry-rundocuments: - path: storefront.aggregate.yaml content: | # The storefront application. ...Senza di esso il documento viene scritto. Il comportamento predefinito è la scrittura, perché il prodotto di questo comando è un documento modificato e un comando che ne produce uno è tenuto a consegnarlo — una richiesta che non dice nulla sulla consegna modifica il file.
Ogni altro comportamento è quello della scrittura, controllo di validazione incluso. Una modifica il cui risultato lo schema rifiuterebbe viene rifiutata anche con --dry-run, indicando la stessa proprietà e lasciando il file esattamente com’era — così il codice di uscita che ottieni da un dry run è il codice di uscita che ti avrebbe dato la scrittura.
La stessa modifica da un editor o da un assistente
I byte sono gli stessi qualunque superficie applichi la modifica. Un editor che pilota aggrega serve la raggiunge su aggrega/editDocument, e un assistente AI connesso tramite aggrega mcp la raggiunge come lo strumento con cui questo comando è esposto lì. La voce viene composta, inserita e sottoposta a validazione in un unico punto, e ogni superficie è un sottile punto di ingresso verso di esso — così il documento che modifichi da terminale e il documento che un editor modifica per te sono identici byte per byte.
L’unico punto in cui le superfici differiscono è quali byte leggono. Questo comando e il metodo di sessione leggono entrambi il file su disco, mai un buffer non salvato: scrivere da un buffer metterebbe sulla pagina contenuto che non avevi salvato con il pretesto di applicare una sola voce. Salva prima, poi modifica.
Esempi
Aggiungi un’istanza di componente al livello superiore di un Aggregate:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components --name checkout --value core/api-server:1.0.0Allega una Feature a un componente scritto all’interno di un sottosistema:
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.0Imposta un valore su un componente scritto all’interno di un sottosistema:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node subsystems --node billing --node components --node ledger \ --name replicas --value 5Rivedi il risultato prima che venga scritto qualcosa:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket cache --name sessions --value redis --dry-runPer scoprire a quale contenitore appartiene una voce prima di indicarne uno, e per leggere una posizione senza applicare nulla, vedi aggrega serve.