Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

aggrega edit-document

Применение одной ограниченной структурной правки к документу с сохранением каждого байта, который она не затрагивает

Синтаксис

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

Описание

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.

Флаги

ФлагПо умолчаниюОписание
--dry-runfalseВыполнить всё, кроме записи: вернуть отредактированный документ как содержимое с указанием файла, к которому он относится, ничего не создавая и не изменяя. Всё остальное поведение совпадает с поведением при записи, включая проверку по схеме. Без этого флага документ записывается
--name—Ключ, под которым записывается новая запись: имя экземпляра компонента, имя вложения, псевдоним соединения или ключ значения
--node[]Один сегмент структурного пути к узлу, к которому относится правка, от корня документа. Повторяйте флаг по одному разу для каждого сегмента, начиная с внешнего. Он принимает по одному сегменту, а не один путь через точки, потому что точка — допустимый символ в вводимом имени, и составной путь мог бы адресовать ключ, которого никто не писал
--socket—Сокет зависимости, внутри которого подключается соединение. Читается для wire-edge и в остальных случаях игнорируется
--value—Содержимое записи, читаемое как скаляр YAML. Его смысл определяется правкой: сущность, которую запрашивает запись, узел, на который указывает соединение, или скаляр, которому присваивается значение

Что делает команда

aggrega edit-document <edit> <file> применяет одну структурную правку к документу в вашем рабочем пространстве и оставляет каждый байт, который она не затронула, ровно таким, каким вы его написали. Сначала указывается правка, затем документ:

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

Команда предназначена для случая, когда вы предпочитаете, чтобы файл был отредактирован, а не чтобы вам сообщили, где его редактировать. Если вы ведёте собственный буфер и собственную историю отмены, aggrega serve сообщает позицию и позволяет вам вставить текст самостоятельно; эта же команда составляет запись и записывает её.

Документ должен входить в ваше рабочее пространство. Укажите его относительно корня рабочего пространства или абсолютным путём; документ вне рабочего пространства отклоняется без какого-либо чтения или записи — независимо от того, записан ли путь так напрямую или ведёт за пределы рабочего пространства через ссылку: ссылку на сам файл или каталог на пути, являющийся ссылкой. Правка читает документ, прежде чем записать его обратно, поэтому документ за такой ссылкой — это файл, которого рабочее пространство не содержит, и отказ сообщает об этом:

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"

Чтобы отредактировать документ, хранящийся в другом месте, запустите команду в рабочем пространстве, которое его содержит. Правки языкового сервера и инструментов ассистента подчиняются тому же правилу, поскольку все три применяют одну и ту же правку. Её документ — это единственный вводимый вами путь, который ограничен рабочим пространством, как описано в разделе Граница рабочего пространства.

Один вызов — одна запись, и набор закрыт

Существует ровно четыре правки, и других нет:

ПравкаЧто она добавляет
add-componentэкземпляр компонента в контейнере компонентов
attach-featureподключение сущности Feature к указанному вами узлу
wire-edgeсоединение внутри одного из сокетов зависимостей этого узла
set-valueодно значение на указанном вами узле

Нет правки, которая удаляет, заменяет уже написанный вами блок, что-либо переупорядочивает или записывает переданные вами байты дословно. Это и есть замысел, а не ограничение, наложенное на него: у имени вне этих четырёх вообще нет пути через команду, так что это не средство записи файлов под более узким названием. Имя вне набора отклоняется, а не интерпретируется.

Запись, которая уже существует и содержит то, что вы запросили, ничего не меняет — команда сообщает об этом и ничего не записывает:

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

Запись с тем же именем, содержащая что-то другое, отклоняется, а не заменяется, потому что замена написанного вами не входит в эти четыре правки.

Узел задаётся путём, по одному сегменту за раз

--node повторяется по одному разу для каждого сегмента пути от корня документа, начиная с внешнего:

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

Флаг намеренно принимает по одному сегменту, а не один путь через точки, и причина связана с корректностью. Точка — допустимый символ в имени, которое вы вводите, поэтому ничто вне документа не может отличить структурную точку от точки внутри имени. Склеенный путь читался бы правильно, но адресовал бы ключ, который никто не писал, — а поскольку add-component может создать контейнер, которого в документе нет, запись оказалась бы под этим выдуманным ключом, вместо того чтобы быть отклонённой. Сегменты устраняют неоднозначность, а не переносят её в другое место.

Для add-component путь указывает на сам контейнер компонентов, потому что добавляемая запись и есть узел. Для остальных трёх правок путь указывает на узел, к которому относится правка, а контейнер следует из самой правки: привязка помещается в features этого узла, соединение — в его uses под указанным вами сокетом, значение — в его values.

--name — это ключ, под которым записывается запись: имя экземпляра, имя привязки, псевдоним соединения или ключ значения. --socket читается для wire-edge и игнорируется в остальных случаях.

Значение сохраняет тип, который задают его символы

--value читается как скаляр YAML — так же, как были бы прочитаны эти символы, если бы вы ввели их в документ:

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

Поэтому --value 4 задаёт число, --value true — логическое значение, а --value '"4"' — строку 4: кавычки здесь означают «это текст» точно так же, как в документе. Если --value не указан, ничего не задаётся. Отображение или последовательность отклоняются, потому что их запись означала бы добавление блока, а это не одна из четырёх правок.

Всё, что вы не редактировали, сохраняется, а один и тот же запрос даёт одни и те же байты

Документ разбирается только для того, чтобы найти контейнер и строку, на которой заканчивается его блок; запись формируется и вставляется на уровне строк. Комментарии, пустые строки, стиль кавычек, свёрнутые и буквальные скаляры, шаблонные выражения и форма завершающего перевода строки переносятся без изменений, а шаг вложенности измеряется по собственным отступам документа, а не навязывается, — поэтому запись оказывается в том стиле, в котором вы уже пишете.

При одном и том же документе и одном и том же запросе байты каждый раз одинаковы. Поэтому можно сравнить два запуска, а при ревью одна правка читается как один diff.

Результат должен быть документом, который вы могли бы набрать вручную

Именно от этого зависит запись. Составленный документ проверяется по схеме его собственного вида, которая берётся из самого документа, а не передаётся вами, и байты попадают на диск, только если проверка пройдена. Запрос, который дал бы то, что схема отвергает, отклоняется с указанием свойства, которое схема не допустила бы, и места, где оно находится:

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"

Файл остаётся побайтно таким же, каким был, а сама запись атомарна, поэтому отклонённое или прерванное редактирование неотличимо от того, которое никогда не предпринималось, и можно повторить исправленный запрос к исходному документу. По этой же причине здесь не повторяется ни одно правило написания: попытка поместить в документ сущности Release значение разработчика отклоняется той же схемой, которая отвергла бы документ, набранный вручную.

Что допустимо семантически, здесь не решается. Объявляет ли производитель данный сокет зависимости и выполнено ли условие применимости сущности Feature — это относится к разрешению, которое выполняет сборка. Поэтому можно указать соединение, о котором эта команда никогда не слышала, а сущность Aggregate может задать сокет, который её сущность каталога заранее не объявляет; что может быть потреблено через сокет, по-прежнему объявляет производитель. Если вопрос именно в этом, запустите aggrega validate с указанием сущности Release.

Просмотр результата перед сохранением

--dry-run делает всё то же, что и команда без флага, кроме записи: отредактированный документ выводится в стандартный вывод как содержимое с указанием файла, к которому он относится, и ничего не создаётся:

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

Без него документ записывается. По умолчанию выполняется запись, потому что результат этой команды — отредактированный документ, а команда, которая его создаёт, обязана его выдать: запрос, в котором ничего не сказано о способе выдачи, редактирует файл.

Всё остальное поведение совпадает с поведением записи, включая проверку перед записью. Правка, результат которой схема отклонила бы, отклоняется и с --dry-run: с указанием того же свойства и без изменения файла, поэтому код выхода, полученный при пробном запуске, совпадает с кодом выхода, который вернула бы запись.

То же редактирование из редактора или ассистента

Байты одинаковы, какая бы поверхность ни применяла редактирование. Редактор, работающий через aggrega serve, обращается к нему по aggrega/editDocument, а ИИ-ассистент, подключённый через aggrega mcp, — как к инструменту, под которым эта команда там доступна. Запись составляется, вставляется и проходит проверку валидации в одном месте, а каждая поверхность — лишь тонкая точка входа в него, поэтому документ, который вы редактируете в терминале, и документ, который редактор редактирует за вас, идентичны байт в байт.

Единственное, чем поверхности различаются, — какие байты они читают. Эта команда и метод сеанса читают файл на диске, а не несохранённый буфер: запись из буфера поместила бы на страницу содержимое, которое вы не сохранили, под видом применения одной записи. Сначала сохраните, затем редактируйте.

Примеры

Добавить экземпляр компонента на верхнем уровне сущности Aggregate:

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

Подключить сущность Feature к компоненту, описанному внутри подсистемы:

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

Задать значение компоненту, описанному внутри подсистемы:

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

Просмотреть результат до того, как что-либо будет записано:

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

Чтобы узнать, в какой контейнер относится запись, прежде чем указывать его, и чтобы прочитать позицию, ничего не применяя, см. aggrega serve.