aggrega edit-document
Áp dụng một chỉnh sửa có cấu trúc, có giới hạn lên một tài liệu, giữ nguyên mọi byte mà nó không chạm tới
Cú pháp
aggrega edit-document <edit> <file> [flags]Mô tả
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.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--dry-run | false | Làm mọi việc trừ việc ghi: trả lại tài liệu đã chỉnh sửa dưới dạng nội dung, nêu tên tệp mà nó dành cho, và không tạo hay sửa đổi gì. Mọi hành vi khác đều giống như khi ghi, kể cả bước kiểm tra schema. Nếu không có cờ này, tài liệu sẽ được ghi |
--name | — | Khóa mà mục mới được ghi dưới đó: tên instance của component, tên của attachment, alias của kết nối, hoặc khóa của giá trị |
--node | [] | Một đoạn của đường dẫn cấu trúc tới nút mà thao tác chỉnh sửa nhắm đến, tính từ gốc tài liệu. Lặp lại cờ này một lần cho mỗi đoạn, đoạn ngoài cùng trước. Cờ nhận từng đoạn một thay vì một đường dẫn nối bằng dấu chấm vì dấu chấm là ký tự hợp lệ trong một tên bạn nhập, nên một đường dẫn nối lại có thể trỏ tới một khóa mà không ai viết |
--socket | — | Socket phụ thuộc mà một kết nối được nối bên trong. Được đọc với wire-edge và bị bỏ qua trong các trường hợp khác |
--value | — | Nội dung mà mục mang theo, được đọc như một scalar YAML. Ý nghĩa của nó tùy thuộc vào thao tác chỉnh sửa: thực thể mà mục yêu cầu, nút mà một kết nối trỏ tới, hoặc scalar mà một giá trị được đặt thành |
Chức năng
aggrega edit-document <edit> <file> áp dụng một thao tác chỉnh sửa có cấu trúc lên một tài liệu trong workspace của bạn và giữ nguyên mọi byte mà nó không chạm tới, đúng như bạn đã viết. Thao tác chỉnh sửa được nêu trước, tài liệu được nêu sau:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components \ --name checkout --value core/api-server:1.0.0Lệnh này dành cho trường hợp bạn muốn tệp được chỉnh sửa trực tiếp thay vì được chỉ cho biết chỗ cần chỉnh sửa. Nếu bạn tự quản lý buffer và lịch sử hoàn tác của riêng mình, aggrega serve sẽ báo một vị trí và để bạn tự đặt văn bản vào; còn lệnh này soạn mục nhập và ghi nó.
Tài liệu phải là một tài liệu mà workspace của bạn chứa. Hãy chỉ định nó bằng đường dẫn tương đối so với thư mục gốc của workspace hoặc bằng đường dẫn tuyệt đối; một tài liệu nằm ngoài workspace sẽ bị từ chối mà không có gì được đọc hay ghi, dù nó được viết theo cách đó hay được truy cập qua một liên kết dẫn ra ngoài workspace — một liên kết tới tệp, hoặc một thư mục trên đường đi là một liên kết. Một thao tác chỉnh sửa đọc tài liệu trước khi ghi lại, nên một tài liệu nằm sau liên kết như vậy là một tệp mà workspace không chứa, và thông báo từ chối nói rõ điều đó:
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"Để chỉnh sửa một tài liệu được lưu ở nơi khác, hãy chạy lệnh trong workspace chứa nó. Các thao tác chỉnh sửa của language server và của các công cụ trợ lý cũng áp dụng cùng quy tắc này, vì cả ba đều áp dụng cùng một thao tác chỉnh sửa. Tài liệu của nó là đường dẫn duy nhất bạn nhập bị giới hạn trong workspace, như Ranh giới workspace đã trình bày.
Một lệnh gọi, một mục, và tập hợp là đóng
Có bốn thao tác chỉnh sửa và không có thao tác nào khác:
| Thao tác chỉnh sửa | Nội dung được thêm vào |
|---|---|
add-component | một thể hiện component dưới một container components |
attach-feature | một gắn kết Feature trên nút bạn chỉ định |
wire-edge | một kết nối bên trong một trong các socket phụ thuộc của nút đó |
set-value | một giá trị trên nút bạn chỉ định |
Không có thao tác chỉnh sửa nào xóa, thay thế một khối bạn đã viết, sắp xếp lại bất cứ thứ gì, hoặc ghi nguyên văn các byte do bạn cung cấp. Đó chính là toàn bộ thiết kế chứ không phải một hạn chế đặt lên nó: một tên nằm ngoài bốn thao tác hoàn toàn không có đường đi nào qua lệnh này, vì vậy đây không phải là một công cụ ghi tệp khoác một cái tên hẹp hơn. Một tên nằm ngoài tập hợp sẽ bị từ chối thay vì được diễn giải.
Một mục đã có sẵn, mang đúng nội dung bạn yêu cầu, là một thao tác không làm gì (no-op) — lệnh sẽ thông báo như vậy và không ghi gì cả:
storefront.aggregate.yaml already carries that entry; nothing was writtenMột mục cùng tên nhưng mang nội dung khác sẽ bị từ chối thay vì bị thay thế, vì thay thế những gì bạn đã viết không phải là một trong bốn thao tác.
Bạn chỉ định nút dưới dạng một đường dẫn, từng đoạn một
--node được lặp lại một lần cho mỗi đoạn của đường dẫn tính từ gốc tài liệu, đoạn ngoài cùng trước:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket database --name replica --value storeViệc nhận từng đoạn một thay vì một đường dẫn nối bằng dấu chấm là có chủ đích, và lý do là vấn đề tính đúng đắn. Dấu chấm là một ký tự hợp lệ trong tên bạn nhập, nên không gì bên ngoài tài liệu có thể phân biệt một dấu chấm cấu trúc với một dấu chấm nằm trong tên. Một đường dẫn được nối lại sẽ trông có vẻ đúng nhưng lại trỏ tới một khóa không ai viết ra — và vì add-component có thể tạo ra một container mà tài liệu không có, mục sẽ được đặt dưới khóa bịa ra đó thay vì bị từ chối. Các đoạn loại bỏ sự mơ hồ thay vì chuyển nó sang chỗ khác.
Với add-component, đường dẫn chỉ định chính container chứa các component, vì mục được thêm vào chính là nút đó. Với ba thao tác còn lại, đường dẫn chỉ định nút mà thao tác chỉnh sửa nhắm tới, và container được suy ra từ thao tác: một attachment nằm dưới features của nút đó, một kết nối nằm dưới uses của nó và socket bạn đã chỉ định, một giá trị nằm dưới values của nó.
--name là khóa mà mục được ghi dưới đó — tên instance, tên của attachment, alias của kết nối, hoặc khóa của giá trị. --socket được đọc cho wire-edge và bị bỏ qua trong các trường hợp khác.
Một giá trị giữ kiểu mà các ký tự của nó mang
--value được đọc như một scalar YAML, đúng theo cách các ký tự đó sẽ được đọc nếu bạn gõ chúng vào tài liệu:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node components --node web --name workers --value 4 values: replicas: 3 workers: 4Vì vậy --value 4 đặt một số, --value true đặt một boolean, và --value '"4"' đặt chuỗi 4 — việc đặt trong dấu nháy ở đây nói “đây là văn bản” đúng như trong tài liệu. Bỏ qua --value thì không đặt gì cả. Một mapping hoặc một sequence bị từ chối, vì viết một mapping hay sequence là thêm một khối, và đó không phải là một trong bốn thao tác chỉnh sửa.
Mọi thứ bạn không chỉnh sửa đều được giữ nguyên, và cùng một yêu cầu tạo ra cùng các byte
Tài liệu chỉ được phân tích cú pháp để xác định vị trí của container và dòng mà khối của nó kết thúc; mục được kết xuất và chèn vào ở cấp dòng. Chú thích, dòng trống, kiểu đặt dấu ngoặc kép, scalar dạng gấp (folded) và dạng nguyên văn (literal), biểu thức template và dạng ký tự xuống dòng ở cuối đều được giữ nguyên không thay đổi, và bước lồng được đo từ chính thụt lề của tài liệu thay vì bị áp đặt — vì vậy một mục sẽ được đặt theo đúng phong cách bạn đang viết.
Với cùng một tài liệu và cùng một yêu cầu, các byte lần nào cũng giống nhau. Nhờ vậy bạn có thể so sánh hai lần chạy, và một lượt review đọc một lần chỉnh sửa như một diff.
Kết quả phải là một tài liệu mà bạn có thể tự gõ ra
Đó chính là điều kiện để ghi. Tài liệu sau khi ghép được kiểm tra theo schema của chính kind của nó, được đọc từ tài liệu thay vì do bạn cung cấp, và các byte chỉ được ghi xuống đĩa nếu kiểm tra đó thành công. Một yêu cầu sẽ tạo ra thứ mà schema từ chối thì bị từ chối, kèm theo tên thuộc tính mà schema không chấp nhận và vị trí của nó:
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"Tệp được giữ nguyên từng byte như ban đầu, và bản thân thao tác ghi là nguyên tử, nên một lần sửa bị từ chối hoặc bị gián đoạn không thể phân biệt được với một lần sửa chưa từng được thực hiện, và bạn có thể thử lại một yêu cầu đã sửa trên chính tài liệu ban đầu. Đó cũng là lý do không có quy tắc soạn thảo nào được nhắc lại ở đây: yêu cầu một tài liệu Release mang một giá trị dành cho nhà phát triển sẽ bị từ chối bởi chính schema vốn sẽ từ chối tài liệu được gõ tay.
Điều gì được chấp nhận về mặt ngữ nghĩa không được quyết định ở đây. Việc một socket phụ thuộc có phải là socket mà bên cung cấp khai báo hay không, hoặc khả năng áp dụng của một Feature có được thỏa mãn hay không, thuộc về quá trình phân giải mà một lần build thực hiện. Vì vậy bạn có thể đặt tên một kết nối mà lệnh này chưa từng biết đến, và một Aggregate có thể khai báo một socket mà thực thể catalog của nó không khai báo trước; còn những gì có thể được tiêu thụ qua một socket vẫn do bên cung cấp khai báo. Hãy chạy aggrega validate với tên một Release khi đó là điều bạn cần biết.
Xem kết quả trước khi lưu
--dry-run làm mọi việc mà lệnh thông thường làm, trừ việc ghi: tài liệu đã chỉnh sửa được đưa ra đầu ra chuẩn dưới dạng nội dung, kèm tên tệp mà nó dành cho, và không có gì được tạo ra:
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. ...Không có nó, tài liệu sẽ được ghi. Mặc định là ghi, vì sản phẩm của lệnh này là một tài liệu đã chỉnh sửa, và một lệnh tạo ra tài liệu như vậy phải giao nó — một yêu cầu không nói gì về cách giao sẽ chỉnh sửa tệp.
Mọi hành vi khác đều là của thao tác ghi, kể cả cổng kiểm tra hợp lệ. Một chỉnh sửa mà kết quả của nó bị schema từ chối cũng bị từ chối khi dùng --dry-run, nêu cùng thuộc tính đó và giữ nguyên tệp đúng như trước — vì vậy mã thoát bạn nhận được từ một lần chạy thử chính là mã thoát mà thao tác ghi lẽ ra sẽ trả về cho bạn.
Cùng một thao tác chỉnh sửa từ trình soạn thảo hoặc trợ lý
Các byte đều giống nhau bất kể giao diện nào áp dụng thao tác chỉnh sửa. Một trình soạn thảo điều khiển aggrega serve truy cập nó tại aggrega/editDocument, và một trợ lý AI kết nối qua aggrega mcp truy cập nó dưới dạng công cụ mà lệnh này được cung cấp ở đó. Mục được tạo, ghép vào và kiểm tra hợp lệ tại một nơi duy nhất, và mỗi giao diện chỉ là một điểm vào mỏng dẫn tới đó — vì vậy tài liệu bạn chỉnh sửa tại terminal và tài liệu mà trình soạn thảo chỉnh sửa cho bạn giống hệt nhau đến từng byte.
Điểm duy nhất mà các giao diện khác nhau là chúng đọc những byte nào. Lệnh này và phương thức phiên đều đọc tệp trên đĩa, không bao giờ đọc một bộ đệm chưa lưu: ghi từ bộ đệm sẽ đưa nội dung bạn chưa lưu vào trang dưới danh nghĩa áp dụng một mục. Hãy lưu trước, rồi mới chỉnh sửa.
Ví dụ
Thêm một thể hiện component ở cấp cao nhất của một Aggregate:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components --name checkout --value core/api-server:1.0.0Gắn một Feature vào một component được khai báo bên trong một hệ thống con:
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Đặt một giá trị trên một component được viết bên trong một subsystem:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node subsystems --node billing --node components --node ledger \ --name replicas --value 5Xem lại kết quả trước khi bất cứ thứ gì được ghi:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket cache --name sessions --value redis --dry-runĐể biết một mục thuộc về container nào trước khi bạn chỉ định một container, và để đọc một vị trí mà không áp dụng gì, xem aggrega serve.