aggrega edit-document
Aplicar a un documento una edición estructurada y acotada, conservando cada byte que no toca
Sinopsis
aggrega edit-document <edit> <file> [flags]Descripción
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
| Flag | Predeterminado | Descripción |
|---|---|---|
--dry-run | false | Hacer todo excepto escribir: devolver el documento editado como contenido, nombrando el archivo al que corresponde, y no crear ni modificar nada. Todo lo demás se comporta como la escritura, incluida la validación con el esquema. Sin esta opción, el documento se escribe |
--name | — | La clave bajo la que se escribe la nueva entrada: el nombre de la instancia del componente, el nombre de la vinculación, el alias de la conexión o la clave del valor |
--node | [] | Un segmento de la ruta estructural hasta el nodo al que se refiere la edición, desde la raíz del documento. Repítela una vez por segmento, empezando por el más externo. Recibe un segmento cada vez en lugar de una única ruta con puntos porque el punto es un carácter válido en un nombre que escribes, así que una ruta unida podría direccionar una clave que nadie escribió |
--socket | — | El socket de dependencia dentro del cual se conecta una conexión. Se lee para wire-edge y se ignora en otro caso |
--value | — | Lo que contiene la entrada, leído como un escalar YAML. Su significado depende de la edición: la entidad que solicita la entrada, el nodo al que apunta una conexión o el escalar al que se asigna un valor |
Qué hace
aggrega edit-document <edit> <file> aplica una edición estructurada a un documento de tu workspace y deja cada byte que no tocó exactamente como lo escribiste. Primero se nombra la edición y después el documento:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components \ --name checkout --value core/api-server:1.0.0Existe para el caso en que prefieres que se edite el archivo en lugar de que se te diga dónde editarlo. Si gestionas tu propio búfer y tu propio historial de deshacer, aggrega serve informa de una posición y te deja colocar el texto tú mismo; este comando compone la entrada y la escribe.
El documento es uno que contiene tu workspace. Nómbralo relativo a la raíz del workspace o por su ruta absoluta; uno fuera del workspace se rechaza sin leer ni escribir nada, tanto si está escrito así como si se llega a él a través de un enlace que sale del workspace — un enlace al archivo, o un directorio en el camino que es un enlace. Una edición lee el documento antes de volver a escribirlo, así que un documento detrás de un enlace así es un archivo que el workspace no contiene, y el rechazo lo indica:
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"Para editar un documento guardado en otro lugar, ejecuta el comando en el workspace que lo contiene. Las ediciones del servidor de lenguaje y de las herramientas del asistente aplican la misma regla, porque las tres aplican una única edición. Su documento es la única ruta que escribes que está restringida al workspace, como expone El límite del workspace.
Una llamada, una entrada, y el conjunto es cerrado
Hay cuatro ediciones y ninguna otra:
| Edición | Qué añade |
|---|---|
add-component | una instancia de componente bajo un contenedor de componentes |
attach-feature | una vinculación de una Feature en el nodo que nombras |
wire-edge | una conexión dentro de uno de los sockets de dependencia de ese nodo |
set-value | un valor en el nodo que nombras |
No hay ninguna edición que elimine, reemplace un bloque que ya escribiste, reordene nada o escriba literalmente bytes que proporcionas. Ese es el diseño completo y no una restricción sobre él: un nombre fuera de los cuatro no tiene ningún camino a través del comando, así que esto no es un escritor de archivos con un nombre más restringido. Un nombre fuera del conjunto se rechaza en lugar de interpretarse.
Una entrada que ya existe y contiene lo que pediste no tiene efecto — el comando lo indica y no escribe nada:
storefront.aggregate.yaml already carries that entry; nothing was writtenUna entrada con ese nombre que contiene otra cosa se rechaza en lugar de reemplazarse, porque reemplazar lo que escribiste no es una de las cuatro.
Nombras el nodo como una ruta, un segmento cada vez
--node se repite una vez por cada segmento de la ruta desde la raíz del documento, empezando por el más externo:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket database --name replica --value storeRecibe un segmento cada vez en lugar de una única ruta con puntos a propósito, y el motivo es de corrección. El punto es un carácter válido en un nombre que escribes, así que nada fuera del documento puede distinguir un punto estructural de uno dentro de un nombre. Una ruta unida se leería correctamente y direccionaría una clave que nadie escribió — y como add-component puede crear un contenedor que el documento no contiene, la entrada acabaría bajo esa clave inventada en lugar de rechazarse. Los segmentos eliminan la ambigüedad en lugar de desplazarla.
Para add-component, la ruta nombra el propio contenedor de componentes, porque la entrada que se añade es el nodo. Para las otras tres, nombra el nodo al que se refiere la edición, y el contenedor se deduce de la edición: una vinculación va bajo features de ese nodo, una conexión bajo su uses y el socket que nombraste, un valor bajo su values.
--name es la clave bajo la que se escribe la entrada — el nombre de la instancia, el nombre de la vinculación, el alias de la conexión o la clave del valor. --socket se lee para wire-edge y se ignora en otro caso.
Un valor conserva el tipo que expresan sus caracteres
--value se lee como un escalar YAML, que es la misma forma en que se leerían los caracteres si los hubieras escrito en el documento:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node components --node web --name workers --value 4 values: replicas: 3 workers: 4Así, --value 4 asigna un número, --value true un booleano y --value '"4"' la cadena 4 — las comillas dicen «esto es texto» aquí exactamente igual que en el documento. Omitir --value no asigna nada en absoluto. Un mapa o una secuencia se rechaza, porque escribirlo supondría añadir un bloque, y eso no es una de las cuatro ediciones.
Todo lo que no editaste se conserva, y la misma solicitud produce los mismos bytes
El documento se analiza solo para localizar el contenedor y la línea en la que termina su bloque; la entrada se genera y se inserta a nivel de línea. Los comentarios, las líneas en blanco, el estilo de comillas, los escalares plegados y literales, las expresiones de plantilla y la forma del salto de línea final se conservan sin cambios, y el paso de anidamiento se mide a partir de la propia sangría del documento en lugar de imponerse — así, una entrada queda en el estilo en el que ya escribes.
Con el mismo documento y la misma solicitud, los bytes son los mismos cada vez. Así puedes comparar dos ejecuciones, y una revisión lee una edición como un único diff.
El resultado tiene que ser un documento que podrías haber escrito tú
De eso depende la escritura. El documento compuesto se comprueba contra el esquema de su propio tipo, leído del documento en lugar de proporcionado por ti, y los bytes llegan al disco solo si esa comprobación se supera. Una solicitud que produciría algo que el esquema rechaza se rechaza, nombrando la propiedad que el esquema no admitiría y dónde:
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"El archivo queda byte a byte como estaba, y la propia escritura es atómica, así que una edición rechazada o interrumpida es indistinguible de una que nunca se intentó y puedes reintentar una solicitud corregida contra el documento con el que empezaste. Por eso tampoco se repite aquí ninguna regla de autoría: pedir que un documento Release contenga un valor de desarrollador lo rechaza el mismo esquema que rechazaría el documento escrito a mano.
Lo que es semánticamente admisible no se decide aquí. Si un socket de dependencia es uno que declara el productor, o si se cumple la aplicabilidad de una Feature, corresponde a la resolución que realiza un build. Así que puedes nombrar una conexión de la que este comando nunca ha oído hablar, y un Aggregate puede escribir un socket que su entidad de catálogo no declara previamente; lo que puede consumirse a través de un socket sigue siendo algo que debe declarar el productor. Ejecuta aggrega validate nombrando una Release cuando esa sea la pregunta.
Ver el resultado antes de guardarlo
--dry-run hace todo lo que hace el comando simple excepto escribir: el documento editado va a la salida estándar como contenido, nombrando el archivo al que corresponde, y no se crea nada:
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. ...Sin esta opción, el documento se escribe. El comportamiento predeterminado es la escritura, porque el producto de este comando es un documento editado y un comando que produce uno debe entregarlo — una solicitud que no dice nada sobre la entrega edita el archivo.
Todo lo demás se comporta como la escritura, incluida la validación. Una edición cuyo resultado rechazaría el esquema también se rechaza con --dry-run, nombrando la misma propiedad y dejando el archivo exactamente como estaba — así, el código de salida que obtienes de una ejecución de prueba es el código de salida que te habría dado la escritura.
La misma edición desde un editor o un asistente
Los bytes son los mismos sea cual sea la superficie que aplique la edición. Un editor que controla aggrega serve llega a ella en aggrega/editDocument, y un asistente de IA conectado a través de aggrega mcp llega a ella como la herramienta con la que este comando se expone allí. La entrada se compone, se inserta y se somete a validación en un único lugar, y cada superficie es un punto de entrada ligero hacia él — así, el documento que editas en un terminal y el documento que un editor edita por ti son idénticos byte a byte.
El único punto en que las superficies difieren es qué bytes leen. Este comando y el método de sesión leen ambos el archivo en disco, nunca un búfer sin guardar: escribir desde un búfer pondría en la página contenido que no habías guardado con la apariencia de aplicar una sola entrada. Guarda primero y luego edita.
Ejemplos
Añadir una instancia de componente en el nivel superior de un Aggregate:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components --name checkout --value core/api-server:1.0.0Vincular una Feature a un componente escrito dentro de un subsistema:
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.0Establece un valor en un componente escrito dentro de un subsistema:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node subsystems --node billing --node components --node ledger \ --name replicas --value 5Revisar el resultado antes de escribir nada:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket cache --name sessions --value redis --dry-runPara averiguar a qué contenedor pertenece una entrada antes de nombrar uno, y para leer una posición sin aplicar nada, consulta aggrega serve.