aggrega edit-document
Bir belgeye, dokunmadığı her baytı koruyarak sınırlı tek bir yapısal düzenleme uygular
Kullanım
aggrega edit-document <edit> <file> [flags]Açıklama
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.Bayraklar
| Bayrak | Varsayılan | Açıklama |
|---|---|---|
--dry-run | false | Yazma dışında her şeyi yapar: düzenlenmiş belgeyi, hangi dosya için olduğunu belirterek içerik olarak geri verir ve hiçbir şey oluşturmaz ya da değiştirmez. Şema denetimi dahil diğer tüm davranışlar yazmayla aynıdır. Bu bayrak olmadan belge yazılır |
--name | — | Yeni girdinin altına yazıldığı anahtar: component örneğinin adı, ekin adı, bağlantının takma adı ya da değerin anahtarı |
--node | [] | Düzenlemenin ilgili olduğu düğüme belge kökünden giden yapısal yolun bir segmenti. Her segment için bir kez, en dıştaki önce olmak üzere tekrarlanır. Noktalı tek bir yol yerine her seferinde bir segment alır, çünkü nokta, yazdığınız bir adda geçerli bir karakterdir; bu yüzden birleştirilmiş bir yol, kimsenin yazmadığı bir anahtarı adresleyebilir |
--socket | — | Bir bağlantının içinde kablolandığı bağımlılık soketi. wire-edge için okunur, diğer durumlarda yok sayılır |
--value | — | Girdinin taşıdığı, bir YAML skaleri olarak okunan değer. Anlamı düzenlemeden çıkar: girdinin istediği varlık, bir bağlantının işaret ettiği düğüm ya da bir değerin ayarlandığı skaler |
Ne yapar
aggrega edit-document <edit> <file>, çalışma alanınızdaki bir belgeye tek bir yapısal düzenleme uygular ve dokunmadığı her baytı tam olarak sizin yazdığınız gibi bırakır. Önce düzenleme, ardından belge belirtilir:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components \ --name checkout --value core/api-server:1.0.0Komut, düzenlemenin nereye yapılacağının size söylenmesi yerine dosyanın doğrudan düzenlenmesini tercih ettiğiniz durum için vardır. Kendi arabelleğinizi ve kendi geri alma geçmişinizi tutuyorsanız, aggrega serve bir konum bildirir ve metni kendiniz yerleştirmenize izin verir; bu komut ise girdiyi oluşturur ve yazar.
Belge, çalışma alanınızın içerdiği bir belgedir. Belgeyi çalışma alanı köküne göreli olarak ya da mutlak yoluyla belirtin; çalışma alanının dışındaki bir belge, ister bu şekilde yazılmış olsun ister çalışma alanının dışına çıkan bir bağlantı üzerinden ulaşılmış olsun — dosyaya giden bir bağlantı ya da yol üzerindeki bir bağlantı olan bir dizin — hiçbir şey okunmadan veya yazılmadan reddedilir. Bir düzenleme, belgeyi geri yazmadan önce okur; dolayısıyla böyle bir bağlantının ardındaki belge, çalışma alanının içermediği bir dosyadır ve ret bunu belirtir:
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"Başka bir yerde tutulan bir belgeyi düzenlemek için komutu o belgeyi içeren çalışma alanında çalıştırın. Dil sunucusunun ve asistan araçlarının düzenlemeleri de aynı kuralı uygular, çünkü üçü de tek bir düzenlemeyi uygular. Bu düzenlemenin belgesi, Çalışma alanı sınırı bölümünde açıklandığı gibi, yazdığınız ve çalışma alanıyla sınırlandırılan tek yoldur.
Tek çağrı, tek giriş ve küme kapalıdır
Dört düzenleme vardır, başkası yoktur:
| Düzenleme | Ne ekler |
|---|---|
add-component | bir components kapsayıcısının altına bir bileşen örneği |
attach-feature | adını verdiğiniz düğüme bir Feature eki |
wire-edge | o düğümün bağımlılık soketlerinden birinin içine bir bağlantı |
set-value | adını verdiğiniz düğüme tek bir değer |
Silen, önceden yazdığınız bir bloğu değiştiren, herhangi bir şeyi yeniden sıralayan veya sağladığınız baytları olduğu gibi yazan bir düzenleme yoktur. Bu, tasarıma getirilmiş bir kısıtlama değil, tasarımın ta kendisidir: dördünün dışındaki bir adın komut içinden hiçbir yolu yoktur, dolayısıyla bu, daha dar bir ad taşıyan bir dosya yazıcısı değildir. Kümenin dışındaki bir ad yorumlanmaz, reddedilir.
Zaten var olan ve istediğinizi taşıyan bir giriş, etkisiz bir işlemdir — komut bunu belirtir ve hiçbir şey yazmaz:
storefront.aggregate.yaml already carries that entry; nothing was writtenAynı adlı ama başka bir şey taşıyan bir giriş değiştirilmez, reddedilir; çünkü yazdığınızı değiştirmek dört düzenlemeden biri değildir.
Düğümü bir yol olarak, her seferinde bir segment vererek adlandırırsınız
--node, belge kökünden başlayan yolun her segmenti için bir kez, en dıştaki ilk olmak üzere tekrarlanır:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket database --name replica --value storeTek bir noktalı yol yerine her seferinde bir segment alması bilinçli bir tercihtir ve nedeni doğrulukla ilgilidir. Nokta, yazdığınız bir adda geçerli bir karakterdir; bu nedenle belgenin dışındaki hiçbir şey yapısal bir noktayı bir adın içindeki noktadan ayırt edemez. Birleştirilmiş bir yol doğru okunur ama kimsenin yazmadığı bir anahtarı adresler; add-component belgede bulunmayan bir kapsayıcı oluşturabildiği için de giriş reddedilmek yerine bu uydurulmuş anahtarın altına yerleşir. Segmentler belirsizliği başka bir yere taşımak yerine ortadan kaldırır.
add-component için yol, bileşen kapsayıcısının kendisini adlandırır, çünkü eklenen giriş düğümün ta kendisidir. Diğer üçü için yol, düzenlemenin ilgili olduğu düğümü adlandırır ve kapsayıcı düzenlemeden çıkar: bir ek o düğümün features anahtarının, bir bağlantı uses anahtarının ve adlandırdığınız soketin, bir değer ise values anahtarının altına girer.
--name, girişin altına yazıldığı anahtardır: örnek adı, ekin adı, bağlantının takma adı ya da değerin anahtarı. --socket yalnızca wire-edge için okunur, diğer durumlarda yok sayılır.
Bir değer, karakterlerinin taşıdığı türü korur
--value bir YAML skaleri olarak okunur; bu, karakterleri belgeye kendiniz yazmış olsaydınız okunacakları yolun aynısıdır:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node components --node web --name workers --value 4 values: replicas: 3 workers: 4Dolayısıyla --value 4 bir sayı, --value true bir boolean, --value '"4"' ise 4 dizesini ayarlar; tırnak içine almak burada da belgede olduğu gibi tam olarak “bu metindir” anlamına gelir. --value atlandığında hiçbir şey ayarlanmaz. Bir eşleme ya da dizi reddedilir, çünkü bunlardan birini yazmak bir blok eklemek olur ve bu, dört düzenlemeden biri değildir.
Düzenlemediğiniz her şey korunur ve aynı istek aynı baytları üretir
Belge yalnızca kapsayıcıyı ve bloğunun bittiği satırı bulmak için ayrıştırılır; girdi oluşturulur ve satır düzeyinde araya eklenir. Yorumlar, boş satırlar, tırnaklama stili, katlanmış ve harfi harfine skalerler, şablon ifadeleri ve sondaki satır sonu biçimi değişmeden korunur; iç içe geçme adımı ise dayatılmak yerine belgenin kendi girintisinden ölçülür. Böylece bir girdi, zaten yazmakta olduğunuz stilde yer alır.
Aynı belge ve aynı istek verildiğinde baytlar her seferinde aynıdır. Böylece iki çalıştırmayı karşılaştırabilirsiniz ve bir inceleme tek bir düzenlemeyi tek bir fark olarak okur.
Sonuç, elle yazabileceğiniz bir belge olmalıdır
Yazma işlemi buna bağlıdır. Oluşturulan belge, sizin sağladığınız değil belgenin kendisinden okunan kendi türünün şemasına göre denetlenir ve baytlar diske yalnızca bu denetim geçerse ulaşır. Şemanın reddedeceği bir şey üretecek bir istek reddedilir; şemanın kabul etmeyeceği özellik ve konumu belirtilir:
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"Dosya bayt bayt eski hâlinde bırakılır ve yazma işleminin kendisi atomiktir; böylece reddedilen ya da yarıda kesilen bir düzenleme hiç denenmemiş olandan ayırt edilemez ve düzeltilmiş bir isteği başladığınız belgeye karşı yeniden deneyebilirsiniz. Burada hiçbir yazım kuralının yeniden belirtilmemesinin nedeni de budur: bir Release belgesinden bir geliştirici değeri taşımasını istemek, elle yazılmış belgeyi reddedecek aynı şema tarafından reddedilir.
Neyin anlamsal olarak kabul edilebilir olduğuna burada karar verilmez. Bir bağımlılık soketinin üreticinin bildirdiği bir soket olup olmadığı ya da bir Feature’ın uygulanabilirliğinin karşılanıp karşılanmadığı, bir derlemenin gerçekleştirdiği çözümlemeye aittir. Bu nedenle bu komutun hiç duymadığı bir bağlantıyı adlandırabilirsiniz ve bir Aggregate, katalog varlığının önceden bildirmediği bir soketi yazabilir; bir soket üzerinden neyin tüketilebileceğini bildirmek ise üreticiye kalır. Soru bu olduğunda bir Release adlandırarak aggrega validate komutunu çalıştırın.
Sonucu kaydedilmeden önce görmek
--dry-run, yazma dışında düz komutun yaptığı her şeyi yapar: düzenlenen belge, hangi dosya için olduğu belirtilerek içerik olarak standart çıktıya gider ve hiçbir şey oluşturulmaz:
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. ...Bu seçenek olmadan belge yazılır. Varsayılan davranış yazmadır, çünkü bu komutun ürünü düzenlenmiş bir belgedir ve böyle bir belge üreten bir komut onu teslim etmekle yükümlüdür — teslimat hakkında hiçbir şey söylemeyen bir istek dosyayı düzenler.
Diğer tüm davranışlar, doğrulama kapısı da dahil, yazmanınkiyle aynıdır. Sonucunu şemanın reddedeceği bir düzenleme --dry-run altında da reddedilir; aynı özellik belirtilir ve dosya tam olarak olduğu gibi bırakılır — dolayısıyla bir deneme çalıştırmasından aldığınız çıkış kodu, yazmanın size vereceği çıkış kodunun aynısıdır.
Bir düzenleyiciden veya bir asistandan aynı düzenleme
Düzenlemeyi hangi yüzey uygularsa uygulasın baytlar aynıdır. aggrega serve komutunu kullanan bir düzenleyici ona aggrega/editDocument üzerinden ulaşır ve aggrega mcp aracılığıyla bağlanan bir yapay zekâ asistanı ona, bu komutun orada sunulduğu araç olarak ulaşır. Girdi tek bir yerde oluşturulur, yerine eklenir ve doğrulamadan geçirilir; her yüzey ona açılan ince bir giriş noktasıdır — dolayısıyla bir terminalde düzenlediğiniz belge ile bir düzenleyicinin sizin için düzenlediği belge bayt bayt aynıdır.
Yüzeylerin farklılaştığı tek nokta, hangi baytları okudukları konusudur. Bu komut ve oturum yöntemi her ikisi de diskteki dosyayı okur, asla kaydedilmemiş bir arabelleği okumaz: bir arabellekten yazmak, tek bir girdi uyguluyormuş görüntüsü altında kaydetmediğiniz içeriği sayfaya koyardı. Önce kaydedin, sonra düzenleyin.
Örnekler
Bir Aggregate’in en üst düzeyine bir bileşen örneği ekleyin:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components --name checkout --value core/api-server:1.0.0Bir alt sistem içinde tanımlanmış bir bileşene bir Feature bağlayın:
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.0Bir alt sistem içinde yazılmış bir bileşende bir değer ayarlayın:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node subsystems --node billing --node components --node ledger \ --name replicas --value 5Herhangi bir şey yazılmadan önce sonucu inceleyin:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket cache --name sessions --value redis --dry-runBir girdinin hangi kapsayıcıya ait olduğunu, bir kapsayıcı adlandırmadan önce öğrenmek ve hiçbir şey uygulamadan bir konumu okumak için aggrega serve sayfasına bakın.