Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

aggrega scaffold

Soạn một tài liệu khởi đầu cho một loại thực thể, hoặc ghi một ví dụ có thể chạy vào một thư mục mới

Cú pháp

aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]

Mô tả

Draft a starter document for an entity kind from its schema, or write one of the documentation's runnable examples into a new directory.
Drafting a starter document
The kind is the lowercase-hyphenated schema token — for example component, aggregate, release, recipe, manifest, or feature. Run aggrega get-schema --list to print the whole set; a token no schema answers to is refused with that set in the message, so a typo is corrected without a second lookup.
The document is derived from that kind's own contract and from nothing else. It carries exactly the fields that kind's schema requires, with the fixed apiVersion and kind filled in and a placeholder everywhere a value is needed. It is not a worked example: there is no namespace, no category, no label set and no commented suggestion of what people usually write, because a catalog decides those for itself and a starter document that guessed at them would teach a requirement that does not exist.
The optional name seeds metadata.name for a kind whose schema requires one. Every other required value is left as a placeholder to fill in.
Nothing is written to disk. The document goes to standard output, so a redirect decides where it lands:
aggrega scaffold component my-service > my-service.yaml
The same starter document is served to an assistant by the scaffold tool that aggrega mcp exposes, which returns these bytes alongside a machine-readable payload; this command is the terminal route to the same drafting.
Writing a runnable example
With --example, the argument is the name of one of the runnable examples the documentation publishes, and the command writes that example's files into a new directory — the second argument, or a directory named after the example in the current directory when there is none — then prints the commands the example's own page gives for building it:
aggrega scaffold --example redis-cache
The directory must not exist yet, or must be empty; a directory holding anything is refused and left as it is. With --list, the command prints every example there is, each with its level and the first sentence of its page, and writes nothing:
aggrega scaffold --example --list
The examples are read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version. It is kept in the cache every project on this machine shares, so a second example needs no second download. It is fetched through the same network settings as every other registry read, and verified against this workspace's signature policy before it is kept or read; a bundle that does not verify is refused, never used. Offline, an example is written only from a copy already cached on this machine.
An example's files are written only as files and directories inside the directory named: a bundle carrying an entry that would land outside it, or a link, is refused whole and nothing is written.
The scaffold tool that aggrega mcp exposes, and the editor's language server that aggrega serve runs, write and list the examples on the same terms, with the directory named relative to the workspace root, and answer with the files written and these same commands.

Cờ

CờMặc địnhMô tả
--examplefalseghi ví dụ chạy được mà đối số nêu tên vào một thư mục mới, đọc từ gói tài liệu đã ký
--listfalsevới —example, in ra mọi ví dụ chạy được mà tài liệu công bố, và không ghi gì

Chức năng

Lệnh có hai dạng. aggrega scaffold <kind> soạn một tài liệu khởi đầu từ schema của một loại và in nó ra, đó là điều mà phần này và ba phần tiếp theo mô tả. aggrega scaffold --example <name> thì thay vào đó ghi một trong các ví dụ chạy được của tài liệu vào một thư mục mới — xem Bắt đầu từ một ví dụ chạy được.

aggrega scaffold <kind> in ra đầu ra chuẩn một tài liệu khởi đầu cho một loại thực thể. Tài liệu chứa đúng các trường mà schema của loại đó yêu cầu: apiVersion và kind được điền sẵn vì schema cố định chúng, còn mọi giá trị bắt buộc khác được để lại dưới dạng chỗ giữ chỗ để bạn thay thế.

Tham số tùy chọn [name] điền sẵn metadata.name cho một loại mà schema của nó yêu cầu trường này:

Terminal window
aggrega scaffold component my-service
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: my-service
version: ""
labels:
component.aggrega.ai/type: ""
spec: {}

Loại là token schema viết thường, nối bằng gạch ngang — component, aggregate, release, recipe, manifest, feature, và các loại còn lại. aggrega get-schema --list in ra toàn bộ tập hợp, và một token không khớp với schema nào sẽ bị từ chối kèm theo tập hợp đó trong thông báo, nên lỗi gõ được sửa mà không cần tra cứu lần thứ hai.

Những gì lệnh trả về và những gì không

Tài liệu được tạo từ chính hợp đồng của loại đó và không từ nguồn nào khác. Đây không phải là một ví dụ hoàn chỉnh. Không có namespace, không có danh mục, không có giá trị nhãn nào được điền sẵn cho bạn, và không có gợi ý dạng chú thích về những gì người ta thường viết — vì không thứ nào trong số đó là điều trình biên dịch yêu cầu. Một catalog tự chọn cách đặt tên, danh mục và cấu trúc thư mục của riêng nó; schema quyết định các trường, và schema là tất cả những gì lệnh này đọc. Một tài liệu khởi đầu đoán phần còn lại sẽ dạy bạn một quy tắc không hề tồn tại.

Việc soạn bản nháp không ghi tệp nào. Tài liệu được đưa ra đầu ra chuẩn, nên việc chuyển hướng quyết định nơi nó được ghi, và không gì trên đĩa bị thay thế nếu bạn không yêu cầu:

Terminal window
aggrega scaffold component my-service > my-service.yaml

Đây chưa phải là một thực thể hoàn chỉnh, và đó chính là ý nghĩa của chỗ giữ chỗ. Một giá trị bắt buộc để trống không phải là một giá trị, nên chạy aggrega validate trên tài liệu đúng như khi nó được tạo ra sẽ từ chối nó và nêu tên cùng lúc mọi chỗ giữ chỗ còn thiếu, kèm theo những gì mỗi chỗ cần — ở trên là phiên bản và loại component:

Entity: my-service.yaml
Kind: Component
[E0215]
document envelope validation failed: 2 placeholders still owed in my-service.yaml; an empty required value is not a value, so each of these needs one before the document validates:
5:3: metadata.version takes a semantic version, such as 1.0.0
7:5: metadata.labels.component.aggrega.ai/type takes one of: server, worker, task, function, stateful-server, resource

Những gì mỗi giá trị cần được đọc từ chính schema của loại đó: các giá trị được chấp nhận khi schema liệt kê chúng, một phiên bản ngữ nghĩa khi schema yêu cầu, và nếu không thì là mô tả của chính schema về trường đó. Cung cấp các giá trị này và cùng lệnh đó sẽ chấp nhận tài liệu. Không có gì về cấu trúc của nó phải thay đổi, vì cấu trúc đến từ schema.

Một giá trị vẫn còn thiếu ngay cả khi schema chấp nhận giá trị trống. Một Recipe hoặc FeatureRecipe được soạn sẵn chứa capability và implements để trống. Schema của chúng chấp nhận chuỗi rỗng, nhưng một chuỗi rỗng không chỉ định provider nào và không chỉ định kiểu nào, nên aggrega validate nêu tên cả hai là còn thiếu cho đến khi bạn điền vào. Cách đọc này chỉ áp dụng khi xác thực một tệp thực thể: một lần chạy trên toàn bộ catalog, aggrega validate --release và aggrega build không áp dụng nó. Xem các chỗ giữ chỗ còn thiếu để biết phạm vi của nó. Một Recipe được soạn sẵn cũng không khai báo loại đầu vào nào trong số các loại mà schema của nó yêu cầu ít nhất một — source, valuesMapping, workload hoặc artifacts — vì chọn loại nào phù hợp là việc của bạn, nên aggrega validate từ chối spec của nó cho đến khi bạn thêm một loại.

Cùng một tài liệu từ trợ lý hoặc trình soạn thảo

Tài liệu khởi đầu là cùng các byte bất kể giao diện nào yêu cầu nó. Một trợ lý AI kết nối qua aggrega mcp truy cập nó dưới dạng công cụ scaffold, công cụ này trả về tài liệu dưới dạng văn bản cùng với một payload máy đọc được. Một trình soạn thảo điều khiển aggrega serve truy cập nó tại aggrega/scaffoldEntity. Tài liệu được suy ra từ schema một lần, nên tài liệu bạn soạn tại terminal và tài liệu một trợ lý soạn cho bạn giống hệt nhau từng byte.

Việc ghi và liệt kê các ví dụ chạy được cũng có trên cùng các giao diện đó, với chính các từ của lệnh làm tên trường. Gửi cho công cụ scaffold, hoặc aggrega/scaffoldEntity, example thay cho kind để ghi một ví dụ, dir để đặt tên thư mục mới tương đối với thư mục gốc của workspace — khi bạn không gửi, đó là một thư mục mang tên ví dụ tại đó — và chỉ list: true để nhận về mọi ví dụ. Ví dụ được đọc từ cùng một gói, được xác minh theo cùng một chính sách và được ghi bằng cùng một bước giải nén, nên các tệp và các lệnh tiếp theo giống như tại terminal, và các trường hợp từ chối cũng vậy: một thư mục chứa bất cứ thứ gì, một mục dẫn ra ngoài thư mục hoặc một liên kết, một gói mà chính sách của bạn không chấp nhận, một workspace ngoại tuyến không có gì trong cache. Câu trả lời có cấu trúc: với một danh sách, examples, mỗi mục có name, level và summary; với một lần ghi, example, dir, files — các tệp đã ghi, tương đối với dir — next, các lệnh mà trang của ví dụ đưa ra, và version, phiên bản tài liệu mà ví dụ được đọc từ đó. Câu trả lời của công cụ scaffold cho một lần ghi cũng mang output_dir, vị trí của thư mục — đầy đủ qua đầu vào và đầu ra chuẩn, để một trợ lý đã nêu tên nó tương đối với một workspace mà nó không nhìn thấy đọc được ví dụ đã được ghi vào đâu, và tương đối với thư mục gốc của workspace qua HTTP. Văn bản của công cụ scaffold là phần tường thuật mà lệnh này in ra, kết thúc bằng một dòng nêu vị trí đó khi nó khác với dir. Các trường của hai dạng được gửi cùng nhau — chẳng hạn kind với example — bị từ chối bằng cùng một câu chữ trên cả hai, trước khi bất cứ thứ gì được đọc. Một trình soạn thảo nêu tên workspace trong workspaceRoot của yêu cầu cho dạng ví dụ, và dir phải là một đường dẫn tương đối nằm bên trong workspace đó và không dẫn ra ngoài qua một liên kết; qua HTTP, công cụ cũng giới hạn dir trong workspace mà nó phục vụ, còn qua đầu vào và đầu ra chuẩn, nó nhận dir đúng như được nêu, như nó nhận mọi đường dẫn. Chỉ mục khả năng báo cáo công cụ scaffold là có ghi, vì dạng đó, và cli-scaffold, vốn chạy lệnh này trong một tiến trình riêng, cũng là có ghi.

Bắt đầu từ một ví dụ chạy được

Tài liệu có kèm các ví dụ chạy được — mỗi ví dụ là một thư mục chứa một Aggregate, các Releases của nó và mọi thứ khác mà nó được build từ đó, cùng một trang hướng dẫn cách build. --example ghi một trong số đó vào một thư mục mới, để bạn có thể bắt đầu từ một dự án hoạt động được thay vì từ một dự án trống:

Terminal window
aggrega scaffold --example redis-cache
Wrote the example redis-cache into redis-cache (12 files).
Next:
cd redis-cache
# Local development (Docker Compose), no authentication
aggrega build --release release-compose.yaml --auto-pull
...
Its page, redis-cache/README.md, explains what it shows.

Ghi gì và ghi vào đâu. Các tệp của ví dụ, đúng như tài liệu chứa chúng, được ghi vào thư mục bạn nêu làm đối số thứ hai — hoặc, khi bạn không nêu, vào một thư mục mang tên ví dụ trong thư mục nơi bạn chạy lệnh. Thư mục đó phải chưa tồn tại, hoặc phải trống. Mọi trường hợp khác đều bị từ chối và được giữ nguyên như cũ: một thư mục chứa một tệp, một tệp nằm ở đường dẫn đó, hoặc một liên kết. Các thư mục cấp trên chưa tồn tại sẽ được tạo. Không tệp nào của ví dụ bị bỏ lại ở nơi khác, và không tệp nào được đặt vào chỗ trước khi tất cả đã được ghi: chúng được ghi ra một chỗ riêng trước rồi chuyển vào khi tất cả đã có mặt.

Các lệnh nó in ra tiếp theo là các lệnh mà chính trang của ví dụ đưa ra: khối sh, bash hoặc shell đầu tiên dưới tiêu đề ## Build của trang, đúng như trang viết, kể cả chú thích, sau một lệnh cd vào thư mục. Một ví dụ có trang không có khối như vậy sẽ được trả lời bằng đường dẫn của trang đó.

Có những ví dụ nào. --list in ra mọi ví dụ, mỗi ví dụ một lần, theo thứ tự mà tài liệu giảng dạy chúng — tên, cấp độ mà trang của nó khai báo, và câu đầu tiên của trang — và không ghi gì:

Terminal window
aggrega scaffold --example --list
EXAMPLE LEVEL DESCRIPTION
...
redis-cache start This lean example compiles a single **Redis** in-memory cache (Redis wire protocol) from one Developer-authored `Aggregate` to two realizations.
...

Danh sách này là danh sách ví dụ của chính tài liệu, danh sách được xuất bản cùng các ví dụ dưới tên Ví dụ theo sản phẩm và khả năng. Một tên mà gói không chứa ví dụ nào sẽ bị từ chối, kèm chỉ dẫn tới --list, và không có gì được ghi.

Các ví dụ đến từ đâu. Chúng được đọc từ gói tài liệu — kho lưu trữ đã ký của tài liệu đã xuất bản mà aggrega explain đọc phần giải thích từ đó — được xuất bản trên registry mặc định của workspace của bạn. Gói được đọc là gói được xuất bản cho phiên bản aggrega bạn đang chạy. Khi không có gói nào được xuất bản cho phiên bản đó, gói được đọc là gói mới nhất được xuất bản cho một bản phát hành trước đó, và lệnh sẽ báo điều này trên luồng lỗi chuẩn:

note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before it

Một bản build của aggrega được tạo từ một số commit sau một bản phát hành — bản có aggrega version hiển thị dạng 0.9.0-12-g1a2b3c4d — đọc tài liệu của bản phát hành mà nó được build sau đó, ở đây là 0.9.0, hoặc một bản trước đó nếu tài liệu đó không được xuất bản. Một bản build được tạo từ một số commit sau một bản tiền phát hành, chẳng hạn một bản ứng viên phát hành — bản có aggrega version hiển thị dạng 0.9.0-rc.6-4-gc9db2f597 — đọc tài liệu của bản tiền phát hành đó, ở đây là 0.9.0-rc.6, hoặc, nếu tài liệu đó không được xuất bản, tài liệu mới nhất được xuất bản trước nó, kể cả một bản tiền phát hành trước đó. Mọi bản build khác chỉ đọc tài liệu của một bản tiền phát hành khi chính nó là bản tiền phát hành đó. Một bản build không được đóng dấu số phát hành sẽ đọc tài liệu của chính phiên bản của nó hoặc không đọc gì. aggrega explain chọn gói mà nó đọc các phần hướng dẫn từng bước theo cùng cách đó.

Khi không có gói nào được phát hành cho phiên bản của bạn và gói mới nhất trước đó ở định dạng mà phiên bản aggrega này không còn đọc được — chẳng hạn một bản ứng viên phát hành được chạy trước khi tài liệu của chính nó được phát hành — lệnh sẽ từ chối, nêu cả hai điều trong một câu, và không có gì được ghi:

[E0137]
hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the examples cannot be read

Gói được xác minh trước khi sử dụng. Gói được tải về qua cùng các thiết lập mạng như mọi lần đọc registry khác, và chữ ký của nó được kiểm tra theo chính sách chữ ký của workspace bạn cho registry đó trước khi được giữ lại — và kiểm tra lại trước khi đọc một bản sao đã có trên máy, nên một bản sao được chính sách lỏng hơn của một dự án khác cho vào sẽ không được dùng dưới chính sách của bạn. Một gói mà chính sách của bạn không chấp nhận sẽ bị từ chối, và không có gì được ghi.

Gói được tải về một lần cho mỗi máy. Gói được giữ trong cache mà mọi dự án Aggrega trên máy dùng chung — xem aggrega cache — nên ví dụ thứ hai, hay dự án thứ hai, không cần tải về lần thứ hai, và aggrega explain đọc cùng bản sao đó khi cả hai đọc cùng một phiên bản.

Khi ngoại tuyến, chỉ đọc những gì đã có trong cache. Trong một workspace ngoại tuyến không có gì được tải về: ví dụ được ghi từ một bản sao đã có trên máy mà chính sách của bạn chấp nhận — bản cho phiên bản này, hoặc nếu không thì bản trước đó mới nhất có trong cache — và khi không có bản nào, lệnh từ chối bằng lời từ chối ngoại tuyến mà mọi lần đọc mạng đều đưa ra, kèm cách cho phép truy cập mạng.

Một gói chứa thứ gì đó không mong đợi sẽ bị từ chối toàn bộ. Gói đến từ một registry, nên bước giải nén không tin tưởng bất cứ điều gì về cấu trúc của nó: một mục có tên sẽ rơi ra ngoài thư mục bạn đã nêu, hoặc ra ngoài gói, và một mục là liên kết hoặc bất cứ thứ gì khác ngoài tệp hay thư mục, mỗi trường hợp đều khiến toàn bộ ví dụ bị từ chối, kèm tên mục đó, và không có gì được ghi. Một tệp thực thi trong ví dụ vẫn giữ quyền thực thi.

Cấu hình của workspace được đọc. Registry mặc định và chính sách chữ ký đến từ đó, nên một tệp cấu hình là liên kết dẫn ra ngoài workspace sẽ chặn dạng ví dụ giống như nó chặn mọi lệnh khác đọc cấu hình — xem ranh giới workspace.

Ví dụ

Soạn một Release không tên và đọc nó trên terminal:

Terminal window
aggrega scaffold release

Soạn một Recipe thẳng vào một tệp:

Terminal window
aggrega scaffold recipe postgres-helm > postgres-helm.yaml

Kiểm tra những gì bạn còn thiếu trước khi điền bất cứ thứ gì:

Terminal window
aggrega scaffold component my-service > my-service.yaml
aggrega validate my-service.yaml

Xem có những ví dụ chạy được nào, rồi ghi một ví dụ vào thư mục bạn chọn:

Terminal window
aggrega scaffold --example --list
aggrega scaffold --example redis-cache my-cache

Về vòng lặp soạn thảo mà lệnh này khởi đầu — soạn cấu trúc, điền các chỗ giữ chỗ, xác thực — xem Soạn thảo tệp Aggrega.