Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

aggrega edit-document

Menerapkan satu suntingan terstruktur yang terbatas pada dokumen, dengan mempertahankan setiap byte yang tidak disentuhnya

Sinopsis

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

Deskripsi

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

FlagDefaultDeskripsi
--dry-runfalseLakukan semuanya kecuali menulis: kembalikan dokumen yang disunting sebagai konten, dengan menyebutkan berkas tujuannya, dan jangan membuat atau mengubah apa pun. Semua perilaku lainnya sama dengan penulisan, termasuk pemeriksaan skema. Tanpa opsi ini, dokumen ditulis
--name—Kunci tempat entri baru ditulis: nama instans komponen, nama lampiran, alias koneksi, atau kunci nilai
--node[]Satu segmen dari jalur struktural menuju node yang menjadi sasaran suntingan, dimulai dari akar dokumen. Ulangi opsi ini sekali per segmen, dimulai dari yang terluar. Opsi ini menerima satu segmen setiap kali, bukan satu jalur bertitik, karena titik adalah karakter yang sah dalam nama yang Anda ketik, sehingga jalur gabungan dapat mengarah ke kunci yang tidak pernah ditulis siapa pun
--socket—Socket dependensi tempat sebuah koneksi dihubungkan. Dibaca untuk wire-edge dan diabaikan untuk lainnya
--value—Apa yang dimuat entri, dibaca sebagai skalar YAML. Maknanya mengikuti suntingan: entitas yang diminta entri, node yang dituju koneksi, atau skalar yang ditetapkan sebagai nilai

Apa yang dilakukannya

aggrega edit-document <edit> <file> menerapkan satu suntingan terstruktur pada dokumen di workspace Anda dan membiarkan setiap byte yang tidak disentuhnya persis seperti yang Anda tulis. Suntingan disebutkan lebih dahulu dan dokumen kemudian:

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

Perintah ini ada untuk kasus ketika Anda lebih suka berkasnya disunting daripada diberi tahu di mana harus menyuntingnya. Jika Anda mengelola buffer dan riwayat urungkan sendiri, aggrega serve melaporkan sebuah posisi dan membiarkan Anda menempatkan teksnya sendiri; perintah ini menyusun entri dan menuliskannya.

Dokumen tersebut harus berada di dalam workspace Anda. Sebutkan dokumen itu relatif terhadap akar workspace atau dengan jalur absolutnya; dokumen di luar workspace ditolak tanpa ada yang dibaca atau ditulis, baik ditulis demikian maupun dicapai melalui tautan yang mengarah ke luar workspace — tautan ke berkas tersebut, atau direktori di sepanjang jalur yang merupakan tautan. Suntingan membaca dokumen sebelum menuliskannya kembali, sehingga dokumen di balik tautan seperti itu adalah berkas yang tidak dimuat workspace, dan penolakannya menyatakan hal itu:

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"

Untuk menyunting dokumen yang disimpan di tempat lain, jalankan perintah di workspace yang memuatnya. Suntingan dari language server dan alat asisten menerapkan aturan yang sama, karena ketiganya menerapkan satu suntingan yang sama. Dokumennya adalah satu-satunya jalur yang Anda ketik yang dibatasi pada workspace, seperti yang dijelaskan dalam Batas workspace.

Satu panggilan, satu entri, dan himpunannya tertutup

Ada empat suntingan dan tidak ada yang lain:

SuntinganApa yang ditambahkannya
add-componentinstans komponen di bawah kontainer komponen
attach-featurelampiran Feature pada node yang Anda sebutkan
wire-edgekoneksi di dalam salah satu socket dependensi node tersebut
set-valuesatu nilai pada node yang Anda sebutkan

Tidak ada suntingan yang menghapus, mengganti blok yang sudah Anda tulis, mengubah urutan apa pun, atau menulis byte yang Anda berikan apa adanya. Itulah keseluruhan desainnya, bukan pembatasan atasnya: nama di luar keempatnya sama sekali tidak memiliki jalur melalui perintah ini, sehingga ini bukan penulis berkas yang menyandang nama lebih sempit. Nama di luar himpunan ditolak alih-alih ditafsirkan.

Entri yang sudah ada dan memuat apa yang Anda minta tidak berpengaruh apa pun — perintah menyatakannya dan tidak menulis apa pun:

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

Entri dengan nama itu yang memuat sesuatu yang lain ditolak alih-alih diganti, karena mengganti apa yang Anda tulis bukan salah satu dari keempatnya.

Anda menyebutkan node sebagai jalur, satu segmen setiap kali

--node diulang sekali per segmen jalur dari akar dokumen, dimulai dari yang terluar:

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

Opsi ini sengaja menerima satu segmen setiap kali alih-alih satu jalur bertitik, dan alasannya menyangkut ketepatan. Titik adalah karakter yang sah dalam nama yang Anda ketik, sehingga tidak ada apa pun di luar dokumen yang dapat membedakan titik struktural dari titik di dalam nama. Jalur gabungan akan terbaca benar dan mengarah ke kunci yang tidak pernah ditulis siapa pun — dan karena add-component dapat membuat kontainer yang tidak dimuat dokumen, entri akan mendarat di bawah kunci rekaan itu alih-alih ditolak. Segmen menghilangkan ambiguitas alih-alih memindahkannya.

Untuk add-component, jalur menyebutkan kontainer komponen itu sendiri, karena entri yang ditambahkan adalah node-nya. Untuk tiga lainnya, jalur menyebutkan node yang menjadi sasaran suntingan, dan kontainernya mengikuti dari suntingan: lampiran masuk ke bawah features node itu, koneksi ke bawah uses-nya dan socket yang Anda sebutkan, nilai ke bawah values-nya.

--name adalah kunci tempat entri ditulis — nama instans, nama lampiran, alias koneksi, atau kunci nilai. --socket dibaca untuk wire-edge dan diabaikan untuk lainnya.

Nilai mempertahankan tipe yang dibawa karakternya

--value dibaca sebagai skalar YAML, yaitu cara yang sama karakter-karakter itu akan dibaca seandainya Anda mengetiknya ke dalam dokumen:

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

Jadi --value 4 menetapkan angka, --value true boolean, dan --value '"4"' string 4 — tanda kutip menyatakan “ini teks” di sini persis seperti di dalam dokumen. Menghilangkan --value tidak menetapkan apa pun. Mapping atau sequence ditolak, karena menuliskannya berarti menambahkan blok, dan itu bukan salah satu dari empat suntingan.

Semua yang tidak Anda sunting tetap utuh, dan permintaan yang sama menghasilkan byte yang sama

Dokumen hanya diurai untuk menemukan kontainer dan baris tempat bloknya berakhir; entri dirender dan disisipkan pada tingkat baris. Komentar, baris kosong, gaya tanda kutip, skalar folded dan literal, ekspresi template, serta bentuk baris baru di akhir semuanya terbawa tanpa perubahan, dan langkah penyarangan diukur dari indentasi dokumen itu sendiri alih-alih dipaksakan — sehingga entri mendarat dalam gaya yang sudah Anda gunakan.

Dengan dokumen yang sama dan permintaan yang sama, byte-nya selalu sama. Jadi Anda dapat membandingkan dua kali eksekusi, dan sebuah tinjauan membaca satu suntingan sebagai satu diff.

Hasilnya harus berupa dokumen yang bisa saja Anda ketik sendiri

Itulah syarat penulisan. Dokumen yang tersusun diperiksa terhadap skema jenisnya sendiri, yang dibaca dari dokumen alih-alih diberikan oleh Anda, dan byte-nya hanya sampai ke disk jika pemeriksaan itu lolos. Permintaan yang akan menghasilkan sesuatu yang ditolak skema akan ditolak, dengan menyebutkan properti yang tidak akan diterima skema dan letaknya:

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"

Berkas dibiarkan byte demi byte seperti semula, dan penulisannya sendiri bersifat atomik, sehingga suntingan yang ditolak atau terputus tidak dapat dibedakan dari suntingan yang tidak pernah dicoba, dan Anda dapat mencoba ulang permintaan yang telah diperbaiki terhadap dokumen awal Anda. Itu juga sebabnya tidak ada aturan penulisan yang diulang di sini: meminta dokumen Release memuat nilai pengembang ditolak oleh skema yang sama yang akan menolak dokumen yang diketik secara manual.

Apa yang dapat diterima secara semantik tidak diputuskan di sini. Apakah sebuah socket dependensi adalah socket yang dideklarasikan produsen, atau apakah keberlakuan sebuah Feature terpenuhi, merupakan bagian dari resolusi yang dilakukan build. Jadi Anda dapat menyebutkan koneksi yang belum pernah dikenal perintah ini, dan sebuah Aggregate dapat menulis socket yang tidak dideklarasikan sebelumnya oleh entitas katalognya; apa yang boleh dikonsumsi melalui socket tetap menjadi hal yang dideklarasikan produsen. Jalankan aggrega validate dengan menyebutkan sebuah Release jika itu pertanyaannya.

Melihat hasil sebelum disimpan

--dry-run melakukan semua yang dilakukan perintah biasa kecuali menulis: dokumen yang disunting dikirim ke output standar sebagai konten, dengan menyebutkan berkas tujuannya, dan tidak ada yang dibuat:

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

Tanpa opsi ini, dokumen ditulis. Perilaku bawaannya adalah penulisan, karena hasil perintah ini adalah dokumen yang disunting, dan perintah yang menghasilkan dokumen wajib menyerahkannya — permintaan yang tidak menyebutkan apa pun tentang penyerahan akan menyunting berkas.

Semua perilaku lainnya sama dengan penulisan, termasuk pemeriksaan validasi. Suntingan yang hasilnya akan ditolak skema juga ditolak dengan --dry-run, dengan menyebutkan properti yang sama dan membiarkan berkas persis seperti semula — jadi kode keluar yang Anda dapatkan dari dry run adalah kode keluar yang akan diberikan oleh penulisan.

Suntingan yang sama dari editor atau asisten

Byte-nya sama, antarmuka mana pun yang menerapkan suntingan. Editor yang mengendalikan aggrega serve menjangkaunya di aggrega/editDocument, dan asisten AI yang terhubung melalui aggrega mcp menjangkaunya sebagai alat tempat perintah ini diekspos di sana. Entri disusun, disisipkan, dan divalidasi di satu tempat, dan setiap antarmuka adalah titik masuk tipis ke tempat itu — sehingga dokumen yang Anda sunting di terminal dan dokumen yang disunting editor untuk Anda identik byte demi byte.

Satu-satunya perbedaan antarmuka adalah byte mana yang dibacanya. Perintah ini dan metode sesi sama-sama membaca berkas di disk, tidak pernah buffer yang belum disimpan: menulis dari buffer akan menempatkan konten yang belum Anda simpan ke halaman dengan dalih menerapkan satu entri. Simpan dahulu, lalu sunting.

Contoh

Tambahkan instans komponen di tingkat teratas sebuah Aggregate:

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

Lampirkan Feature ke komponen yang ditulis di dalam subsistem:

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

Atur sebuah nilai pada komponen yang ditulis di dalam subsistem:

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

Tinjau hasilnya sebelum apa pun ditulis:

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

Untuk mengetahui kontainer mana yang menjadi tempat sebuah entri sebelum Anda menyebutkannya, dan untuk membaca posisi tanpa menerapkan apa pun, lihat aggrega serve.