Перейти до вмісту
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.