Lược đồ Aggrega Core (Plugin)
Tài liệu tham khảo được sinh tự động. Không chỉnh sửa thủ công — hãy sinh lại từ JSON Schema đã xuất bản.
Id lược đồ: https://aggrega.ai/schemas/plugin-v1beta1.schema.json
Một plugin Wasm: một mô-đun WebAssembly được phát hành lên một registry OCI và được nhận diện bằng metadata.pluginType của nó — socket mà nó triển khai — cùng với metadata.name trần của nó, khai báo phiên bản ABI mà nó nhắm tới, một con trỏ chữ ký tùy chọn và một khối runtime tùy chọn. Thực thể và tệp .wasm của nó được phát hành dưới dạng một manifest OCI duy nhất được gắn thẻ theo metadata.version — YAML của thực thể làm config blob của manifest, tệp .wasm làm một layer nội tuyến, được ký một lần. Danh tính là tọa độ metadata.pluginType/metadata.name cộng với metadata.version của thực thể; vị trí của tệp .wasm được suy ra từ tọa độ đó cộng với registry đã cấu hình, và digest nội dung đã phân giải nằm trong lockfile, không nằm trong thực thể. Lockfile ghi lại digest, và chính sách tin cậy theo từng registry xác minh chữ ký của artifact khi pull. Trình biên dịch không diễn giải hành vi của plugin — nó định tuyến tham chiếu; runtime WebAssembly thực thi các byte.
Xem tài liệu tham khảo về việc viết Plugin để có hướng dẫn bằng văn xuôi về cách viết các thực thể Plugin; trang này mô tả lược đồ cấu trúc mà tài liệu tham khảo đó trình bày.
Kiểu cấp cao nhất: object
Thuộc tính
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | có | Hằng số: "aggrega.ai/v1beta1" |
kind | const “Plugin” | có | Hằng số: "Plugin" |
metadata | object | có | |
spec | object | có | Phiên bản ABI mà plugin nhắm tới, một con trỏ chữ ký tùy chọn và một khối runtime tùy chọn. Vị trí .wasm của plugin được suy ra từ danh tính của plugin — metadata.pluginType (socket) cộng với metadata.name trần của nó — và registry đã cấu hình; nó không được mang trong spec. |
Không cho phép thuộc tính bổ sung.
plugin.metadata
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Dài ít nhất 1 ký tự. |
version | string | có | Phiên bản theo Semantic Versioning nghiêm ngặt của thực thể Plugin (ví dụ: 1.0.0). Mẫu: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
pluginType | string (enum) | có | Loại socket mà plugin này triển khai. Một plugin triển khai đúng một loại socket, lấy từ phân loại plugin-type mà runtime nhận biết: provider (render các nút IR thành các artifact gốc của provider), linter (kiểm tra nội dung được soạn và đưa ra chẩn đoán), pipeline-step (một bước trong pipeline: của một FeatureRecipe hoặc một Recipe, vá tập tài liệu đã render), governance (đảm nhận các vai trò quản trị của build-pipeline — biến đổi nhãn nút khi xây dựng topology, hoặc đưa ra phán quyết chấp nhận/từ chối trên đồ thị IR ở giai đoạn phân tích tĩnh hoặc trên các artifact đã render ở giai đoạn render; chính vai trò mà nó được gắn vào, chứ không phải loại của nó, quyết định những gì nó có thể phát ra), cli (đóng góp một lệnh con runtime aggrega <cmd> mà người vận hành gọi tại dòng lệnh — một socket runtime, khác với các socket render và pipeline ở thời điểm biên dịch), parser (chuyển một văn bản nguồn ngoại lai thành một cây có cấu trúc chuẩn để bên tiêu thụ đọc cây mà không cần mang trình phân tích ngôn ngữ riêng, công bố các định dạng nó xử lý dưới dạng capability parse:<format>), importer (chuyển một nguồn hạ tầng hoặc định nghĩa agent ngoại lai thành các tệp soạn thảo Aggrega nháp, công bố các định dạng nó xử lý dưới dạng capability import:<format>). Giá trị cho phép: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer" |
description | string | không | Thực thể này là gì và dùng để làm gì, viết cho người đang cân nhắc có nên dùng nó hay không. Mở đầu bằng một câu gọi tên nó, sau đó bổ sung những gì người đọc cần để chọn và dùng nó đúng cách — nó kỳ vọng gì từ bản build chạy nó, và bất cứ điều gì bất ngờ trong cách nó hoạt động. Độ dài thông thường là một đoạn văn ngắn. |
maintainers | object[] | không | Danh sách những người bảo trì sở hữu thực thể này. |
license | string | không | Mã định danh SPDX cho giấy phép của phần mềm mà thực thể này mô tả, chẳng hạn MIT hoặc AGPL-3.0. Nó ghi lại các điều khoản của phần mềm đó, không phải các điều khoản của tệp này. |
repository | string | không | URL đến kho Git chứa các tệp nguồn. |
home | string | không | URL của trang chủ, wiki hoặc tài liệu của thực thể này. |
keywords | string[] | không | Danh sách các từ khóa mô tả giúp dễ tìm kiếm trên giao diện người dùng. |
Không cho phép thuộc tính bổ sung.
plugin.metadata.maintainers[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | |
email | string | không | |
url | string | không |
Không cho phép thuộc tính bổ sung.
plugin.spec
Phiên bản ABI mà plugin nhắm tới, một con trỏ chữ ký tùy chọn và một khối runtime tùy chọn. Vị trí .wasm của plugin được suy ra từ danh tính của plugin — metadata.pluginType (socket) cộng với metadata.name trần của nó — và registry đã cấu hình; nó không được mang trong spec.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
abiVersion | string (enum) | có | Phiên bản ABI host/guest mà plugin nhắm tới. v1beta1 là giá trị duy nhất được chấp nhận; một Plugin khai báo phiên bản ABI mà trình biên dịch này không còn hỗ trợ sẽ bị từ chối, kèm theo tên phiên bản cần dùng để build lại plugin. Giá trị cho phép: "v1beta1" |
signature | object | không | Một con trỏ mô tả tùy chọn tới chữ ký đính kèm của plugin. Khối này chỉ mang tính tài liệu — nó ghi lại chữ ký nằm ở đâu và được tạo ra như thế nào cho người đọc catalog; bản thân nó không kiểm soát hay chấp nhận plugin. Việc kiểm tra có tính cưỡng chế là chính sách tin cậy theo từng registry được áp dụng khi pull: chữ ký được lấy về dưới dạng OCI referrer, được xác minh với các danh tính tin cậy hoặc khóa đã ghim của registry, và được ghi lại như một dữ kiện đã xác minh trong lockfile. Một registry yêu cầu chữ ký sẽ dừng việc pull khi một chữ ký bắt buộc bị thiếu, không được tin cậy hoặc không hợp lệ. |
runtime | object | không | Các ràng buộc thực thi tùy chọn mà host áp dụng khi nạp và chạy plugin. Quyền truy cập mạng đi ra không phải là một trường soạn thảo: plugin không bao giờ truy cập mạng ở thời điểm build (ranh giới ahead-of-time), nên không có trường host-allowlist nào để soạn ở đây. |
exports | object[] | không | Các export mà plugin này cung cấp, mỗi export kèm capability đã khai báo. Một export là một điểm vào có tên mà host điều phối tới (ví dụ render_node, lint_naming, step); khối capability theo từng export là tuyên bố được soạn về việc export đó làm gì, được host đối chiếu với bản tự báo cáo của plugin khi publish và khi nạp. Các mục giữ nguyên thứ tự của tác giả. Nếu vắng mặt thì không khai báo bề mặt export nào được soạn. |
commands | object[] | không | Do máy quản lý, không tự soạn: được ghi lại bởi aggrega plugin sync (hoặc aggrega plugin gen-catalog) từ bản tự báo cáo của plugin. Các động từ cấp cao nhất aggrega <command> mà một plugin CLI đóng góp được đọc từ bản tự báo cáo của plugin và được ghi lại ở đây theo thứ tự mà bản tự báo cáo khai báo, nên bề mặt lệnh mà một plugin CLI cài đặt có thể đọc được từ thực thể mà không cần nạp plugin. Một plugin không phải CLI không đóng góp lệnh nào và ghi lại một danh sách rỗng. Host cài đặt đúng tập này; một tập đã ghi lại khác với bản tự báo cáo của plugin sẽ dừng khi nạp, và publish từ chối một tập không đồng bộ với binary và hướng dẫn tác giả ghi lại nó. |
provider | object | không | Khối provider-socket cho một plugin pluginType: provider: các capability nó phục vụ, cách nó dịch kind Workload aggrega.ai/v1beta1, các annotation gốc của nền tảng mà nó đọc, và hợp đồng hành vi render của nó. Chỉ có mặt trên các plugin render provider; vắng mặt trên mọi loại plugin khác. |
pipelineStep | object | không | Khối pipeline-step cho một plugin pluginType: pipeline-step: các capability của provider mà bước của nó tương thích. Chỉ có mặt trên các plugin pipeline-step; vắng mặt trên mọi loại plugin khác. |
parser | object | không | Khối parser cho một plugin pluginType: parser: các định dạng nguồn mà nó chuyển thành một cây có cấu trúc chuẩn. Chỉ có mặt trên các plugin parser; vắng mặt trên mọi loại plugin khác. |
importer | object | không | Khối importer cho một plugin pluginType: importer: các định dạng nguồn ngoại lai mà nó chuyển thành các tệp soạn thảo Aggrega nháp, và các dấu hiệu nhận biết một nguồn thuộc các định dạng đó. Chỉ có mặt trên các plugin importer; vắng mặt trên mọi loại plugin khác. |
Không cho phép thuộc tính bổ sung.
plugin.spec.signature
Một con trỏ mô tả tùy chọn tới chữ ký đính kèm của plugin. Khối này chỉ mang tính tài liệu — nó ghi lại chữ ký nằm ở đâu và được tạo ra như thế nào cho người đọc catalog; bản thân nó không kiểm soát hay chấp nhận plugin. Việc kiểm tra có tính cưỡng chế là chính sách tin cậy theo từng registry được áp dụng khi pull: chữ ký được lấy về dưới dạng OCI referrer, được xác minh với các danh tính tin cậy hoặc khóa đã ghim của registry, và được ghi lại như một dữ kiện đã xác minh trong lockfile. Một registry yêu cầu chữ ký sẽ dừng việc pull khi một chữ ký bắt buộc bị thiếu, không được tin cậy hoặc không hợp lệ.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
type | const “sigstore-cosign” | có | Lược đồ chữ ký. sigstore-cosign là lược đồ được hỗ trợ. Hằng số: "sigstore-cosign" |
signatureRef | string | không | Tham chiếu OCI referrer của gói chữ ký đính kèm, phục vụ tài liệu và khám phá. Vắng mặt khi chữ ký được khám phá bằng cách liệt kê referrer khi pull thay vì được ghim ở đây. |
publicKeyRef | string | không | Một con trỏ tới khóa công khai đã dùng để tạo chữ ký, đối với chữ ký có khóa. Nếu vắng mặt thì đó là chữ ký không khóa (danh tính OIDC), được xác minh với các danh tính tin cậy của registry. |
Không cho phép thuộc tính bổ sung.
plugin.spec.runtime
Các ràng buộc thực thi tùy chọn mà host áp dụng khi nạp và chạy plugin. Quyền truy cập mạng đi ra không phải là một trường soạn thảo: plugin không bao giờ truy cập mạng ở thời điểm build (ranh giới ahead-of-time), nên không có trường host-allowlist nào để soạn ở đây.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
maxMemoryPages | integer | không | Giới hạn bộ nhớ tuyến tính của plugin theo số trang Wasm (64 KiB mỗi trang). Bằng không hoặc vắng mặt sẽ áp dụng giới hạn mặc định của nền tảng, nên việc nạp không bao giờ là không giới hạn; một attachment cần nhiều hơn sẽ tăng giá trị này. Tối thiểu: 0. |
timeoutMs | integer | không | Giới hạn thời gian mà mã riêng của plugin có thể chạy trong một lần gọi, tính bằng mili giây, không tính thời gian dành bên trong các hàm host mà nó gọi. Trên Linux, thước đo là thời gian bộ xử lý, nên thời gian chờ bộ xử lý trên một máy bận rộn không được tính; trên các hệ thống khác, đó là thời gian trôi qua thực tế. Lần gọi đầu tiên tới một plugin vừa được nạp cũng tính cả thời gian khởi động riêng của plugin. Bằng không hoặc vắng mặt sẽ áp dụng giới hạn mặc định của nền tảng, nên một lần gọi không bao giờ là không thể hủy; một attachment chạy lâu hơn sẽ tăng giá trị này. Tối thiểu: 0. |
hostFunctions | string[] | không | Do máy quản lý, không tự viết: các hàm host mà plugin import, được aggrega plugin sync (hoặc aggrega plugin gen-catalog) đọc từ phần import của .wasm và ghi lại tại đây ở dạng chuẩn (đã sắp xếp, đã loại trùng). Publish suy ra lại chúng từ binary và từ chối một thực thể có bản ghi khác; pull suy ra lại và xác minh chúng một lần nữa. Host đăng ký đúng tập đã suy ra này và kiểm tra mọi mục với allowlist được tuyển chọn. |
configKV | map của string | không | Cấu hình dành riêng cho Plugin mà runtime truyền cho plugin khi khởi động, dưới dạng các cặp khóa/giá trị chuỗi-sang-chuỗi. Các mục giữ nguyên thứ tự của tác giả để bản ghi được xuất ra giống hệt nhau từng byte giữa các lần chạy. Nếu vắng mặt, cấu hình rỗng mặc định của runtime sẽ có hiệu lực. |
Không cho phép thuộc tính bổ sung.
plugin.spec.exports[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Tên ABI của export — tên mà host điều phối tới (ví dụ render_node, lint_naming, step). Dài ít nhất 1 ký tự. |
operates | string (enum) | không | Thao tác pipeline mà export này thực hiện: patch (sửa đổi một tài liệu đã render) hoặc emit (thêm một tài liệu mới). Nếu vắng mặt thì không khai báo thao tác nào. Giá trị cho phép: "patch", "emit" |
scope | string (enum) | không | Gốc tài liệu mà export này thao tác trên đó: own (các tài liệu đã render của chính node) hoặc host (các tài liệu của component mà một FeatureRecipe phạm vi component được gắn vào). Nếu vắng mặt thì không khai báo phạm vi nào. Giá trị cho phép: "own", "host" |
selector | string | không | Mô tả tự do, dễ đọc cho con người về đối tượng mà export tác động (ví dụ workloads carrying a pod template). Là tài liệu cho người đọc catalog; trình biên dịch không diễn giải nó. |
Không cho phép thuộc tính bổ sung.
plugin.spec.commands[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Động từ lệnh mà host đăng ký — token aggrega <name> mà người vận hành gọi, và là giá trị phân biệt mà host trao cho plugin khi gọi để một plugin phục vụ nhiều lệnh có thể định tuyến theo lệnh đã được gọi. Dài ít nhất 1 ký tự. |
description | string | không | Văn bản trợ giúp ngắn một dòng của lệnh, hiển thị trong danh sách lệnh và đầu ra trợ giúp. Chỉ là tài liệu; host không xử lý nó. |
flags | object[] | không | Các cờ của lệnh, theo thứ tự khai báo. Mỗi mục đóng góp một cờ mà host đăng ký trên lệnh để aggrega help --help, -h và các cờ toàn cục; host kiểm tra điều này khi thêm các lệnh của plugin, và một plugin có khai báo không hợp lệ sẽ không được thêm, kèm một cảnh báo. |
Không cho phép thuộc tính bổ sung.
plugin.spec.commands[].flags[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Tên dài của cờ — token —name mà người vận hành truyền trên dòng lệnh. Mọi cờ được khai báo đều phải đặt tên này. Dài ít nhất 1 ký tự. |
shorthand | string | không | Bí danh ngắn tùy chọn của cờ — dạng -x mà người vận hành có thể truyền thay cho tên dài — là một chữ cái hoặc chữ số ASCII duy nhất. Nếu vắng mặt nghĩa là cờ không có bí danh ngắn. Mẫu: ^[A-Za-z0-9]$. |
description | string | không | Văn bản trợ giúp một dòng của cờ, hiển thị trong đầu ra trợ giúp của lệnh. Đây là tài liệu tùy chọn; host không kiểm tra cũng không xử lý nó. |
type | string (enum) | không | Kiểu giá trị của cờ — string, bool hoặc int — và loại cờ mà phần trợ giúp hiển thị nó. Nếu vắng mặt, nó được hiển thị như một cờ chuỗi. Giá trị cho phép: "string", "bool", "int" |
default | string | không | Giá trị mặc định của cờ khi người vận hành không truyền nó, được biểu diễn dưới dạng chuỗi. Với một cờ bool hoặc int, đó là một giá trị thuộc kiểu ấy. Nếu vắng mặt nghĩa là cờ không khai báo giá trị mặc định. |
Không cho phép thuộc tính bổ sung.
plugin.spec.provider
Khối provider-socket cho một plugin pluginType: provider: các capability nó phục vụ, cách nó dịch kind Workload aggrega.ai/v1beta1, các annotation gốc của nền tảng mà nó đọc, và hợp đồng hành vi render của nó. Chỉ có mặt trên các plugin render provider; vắng mặt trên mọi loại plugin khác.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
capabilities | string[] | không | Được aggrega plugin gen-catalog ghi lại từ bản tự báo cáo của .wasm của plugin, nên plugin là nguồn của danh sách này. Tác giả có thể thu hẹp nó trước khi xuất bản, loại bỏ một mục mà thực thể này không nên cung cấp, và không được thêm mục nào mà bản tự báo cáo không nêu: việc xuất bản, và aggrega validate khi được cung cấp .wasm của plugin qua --plugin, sẽ từ chối một danh sách nêu một capability mà bản tự báo cáo không nêu. Việc xuất bản gửi thực thể đúng như đã viết, không bao giờ viết lại danh sách này, và ghi chú mỗi capability mà bản tự báo cáo nêu nhưng danh sách bỏ sót. Các capability mà provider này phục vụ — các tên capability như helm hoặc compose — có dạng đầu ra mà nó kết xuất. Một provider là tổng quát trên các artifact có chung dạng đầu ra của một capability, không phải trên mọi capability, nên danh sách này là một tuyên bố tương thích tường minh, đã được kiểm thử, chứ không phải một mong muốn. Các mục giữ nguyên thứ tự của tác giả. Đích provider mà một Recipe yêu cầu được phân giải tới plugin provider có danh sách chứa đích đó; một đích được nhiều hơn một plugin provider liệt kê sẽ dừng vì mơ hồ, trừ khi lựa chọn plugins.providers trong cấu hình workspace chỉ định plugin nào được dùng. Một danh sách rỗng hoặc vắng mặt không khai báo tuyên bố capability nào, nên plugin không phục vụ đích nào. |
workloadSchema | string | không | JSON Schema 2020-12 mô tả cách provider này chuyển đổi kind Workload aggrega.ai/v1beta1 thành các manifest gốc của provider. Khi có mặt, provider hỗ trợ các Recipes khai báo một khối workload: (chế độ tổng hợp) — provider chuyển đổi Workload thành các manifest gốc của provider, dựa trên schema này như tài liệu/hợp đồng. Việc một Recipe workload: có được hỗ trợ hay không do khả năng tổng hợp của provider được liên kết quyết định, không phải do sự có mặt của trường này: một Recipe ở chế độ tổng hợp được liên kết với một provider không thể tổng hợp sẽ dừng rõ ràng khi kết xuất. Catalog thư viện chuẩn khai báo workloadSchema trên các provider có khả năng tổng hợp như hợp đồng được tài liệu hóa, được giữ đồng bộ với khả năng đó. Trường này là hợp đồng được tài liệu hóa: phần thân được biên dịch sang JSON Schema 2020-12 khi nạp để kiểm tra tính hợp lệ, và không có gì khác đọc nó. |
wellKnownAnnotations | object[] | không | Tuyên bố hỗ trợ của provider: các khóa annotation well-known gốc của nền tảng (namespace aggrega.ai/) mà provider này đọc, mỗi khóa kèm phạm vi nó được đọc và hành vi được áp dụng khi nó vắng mặt. Chỉ khai báo một khóa khi provider thực sự đọc nó — ma trận hỗ trợ được công bố được kết xuất từ các khai báo này, nên một khóa được liệt kê ở đây là khóa mà tác giả có thể kỳ vọng sẽ thay đổi đầu ra được kết xuất ở phạm vi nó chỉ định. Trình biên dịch đọc khai báo theo hai cách: một scope chỉ định một input kind mà chính contract.inputKinds của provider không tuyên bố sẽ mâu thuẫn với một tuyên bố liền kề trong cùng entity, và quá trình build dừng lại, nêu tên khóa và mâu thuẫn; và một build cảnh báo về một annotation aggrega.ai/ đến được một lượt kết xuất thông qua provider này khi không có mục nào bao gồm nó ở bất kỳ input kind nào mà lượt kết xuất đó khai báo. Trường này khác với quy tắc chi phối việc gán một giá trị dưới tiền tố dành riêng aggrega.ai/. Nếu vắng mặt thì không khai báo tuyên bố hỗ trợ nào, và không có cảnh báo nào như vậy được đưa ra cho provider này; một provider không đọc khóa nào trong số này sẽ khai báo readsNoWellKnownAnnotations thay cho danh sách này. Các mục là một danh sách có thứ tự và giữ nguyên thứ tự của tác giả. |
readsNoWellKnownAnnotations | hằng số true | không | Khai báo rằng provider này không đọc khóa nào trong số các khóa annotation gốc của nền tảng trong namespace aggrega.ai/, tức là các khóa mà nếu không thì wellKnownAnnotations sẽ liệt kê: một tuyên bố hỗ trợ không bao gồm khóa nào, tức là một lời khẳng định, trong khi bỏ qua cả trường này lẫn wellKnownAnnotations là sự im lặng. Khi đó, một build cảnh báo về mọi annotation aggrega.ai/ đến được một lượt kết xuất thông qua provider này, nêu tên khóa, provider và các input kind mà lượt kết xuất đó khai báo; giá trị vẫn đi qua nguyên vẹn và quá trình build không dừng. Chỉ có thể viết true, nên bỏ qua trường này vẫn là cách duy nhất để không nói gì. Không thể viết trường này cùng với wellKnownAnnotations: một provider đọc một số khóa thì thay vào đó liệt kê các khóa ấy ở trường kia. Hằng số: true |
contract | object | không | Hợp đồng hành vi kết xuất do provider tự khai báo: các input kind mà nó kết xuất, cách nó ghép đầu ra theo từng node của một dispatch group và đầu ra đó nằm dưới những thư mục nào, cặp dấu phân cách template mà nó áp dụng cho các tệp artifact được nhập, liệu một instance đã nạp có thể phục vụ mọi lần chuyển tiếp hay không, liệu nó có nối các cạnh xuyên ranh giới hay không, liệu nó có tuân theo các mục omit hay không, liệu nó có chấp nhận các tệp mà một Recipe đóng góp vào đầu ra dùng chung của ranh giới hay không, và những tệp nào hệ sinh thái của nó không bao giờ phân phối cạnh một nguồn. Đây là bản ghi tại thời điểm xuất bản của bản tự báo cáo của plugin provider, mà host đối chiếu với chính bản tự báo cáo đó khi xuất bản và khi nạp. Nếu vắng mặt thì không khai báo hợp đồng hành vi kết xuất nào, và việc đối chiếu chỉ so sánh các tuyên bố theo từng export. |
Không cho phép thuộc tính bổ sung.
plugin.spec.provider.wellKnownAnnotations[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
key | string | có | Khóa annotation well-known gốc của nền tảng mà provider đọc (ví dụ: aggrega.ai/namespace). Nằm dưới namespace annotation aggrega.ai/ do nền tảng dành riêng — các chỉ thị nền tảng do provider đọc. Mẫu: ^aggrega\.ai/.+. |
purpose | string | có | Những gì annotation kiểm soát — hành vi kết xuất mà nó tác động khi có mặt. |
defaultBehavior | string | không | Hành vi mà provider áp dụng khi annotation này vắng mặt. |
scope | string (enum)[] | không | Nơi provider này đọc khóa. Ba giá trị đầu là các input kind của Recipe và chỉ định đường kết xuất mà khóa được đọc trên đó — sourced là một tập tệp được vendor, synthesized là một Workload mà provider hiện thực hóa, artifactsStandalone là một node có toàn bộ đầu ra là các tài liệu artifact được nhập. Mỗi giá trị đó phải là một input kind mà contract.inputKinds của provider này tuyên bố; chỉ định một giá trị không được tuyên bố sẽ làm dừng build. boundary dành cho một khóa được phân giải một lần cho mỗi ranh giới thay vì cho mỗi node — tên của một artifact được ghép, hoặc ngữ cảnh vị trí mà một tham chiếu xuyên ranh giới được định hình từ đó — nơi input kind không phải là một trục có ý nghĩa, nên nó không được đối chiếu với contract.inputKinds. Một khóa được đọc trên nhiều đường thì liệt kê tất cả các đường. Nếu vắng mặt thì không có tuyên bố theo từng đường: không có gì được kiểm tra, và khóa chỉ cho biết provider đọc nó ở đâu đó. Ít nhất 1 mục. Không mục nào được xuất hiện hai lần. Giá trị cho phép cho mỗi mục: "sourced", "synthesized", "artifactsStandalone", "boundary". |
Không cho phép thuộc tính bổ sung.
plugin.spec.provider.contract
Hợp đồng hành vi kết xuất do provider tự khai báo: các input kind mà nó kết xuất, cách nó ghép đầu ra theo từng node của một dispatch group và đầu ra đó nằm dưới những thư mục nào, cặp dấu phân cách template mà nó áp dụng cho các tệp artifact được nhập, liệu một instance đã nạp có thể phục vụ mọi lần chuyển tiếp hay không, liệu nó có nối các cạnh xuyên ranh giới hay không, liệu nó có tuân theo các mục omit hay không, liệu nó có chấp nhận các tệp mà một Recipe đóng góp vào đầu ra dùng chung của ranh giới hay không, và những tệp nào hệ sinh thái của nó không bao giờ phân phối cạnh một nguồn. Đây là bản ghi tại thời điểm xuất bản của bản tự báo cáo của plugin provider, mà host đối chiếu với chính bản tự báo cáo đó khi xuất bản và khi nạp. Nếu vắng mặt thì không khai báo hợp đồng hành vi kết xuất nào, và việc đối chiếu chỉ so sánh các tuyên bố theo từng export.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
inputKinds | object | không | Plugin này kết xuất những loại đầu vào nào trong ba loại đầu vào của Recipe: một tập tệp có nguồn, một workload được tổng hợp, và một nút độc lập chỉ gồm artifact. Mỗi trường là một tuyên bố độc lập. |
boundaryAssembly | string (enum) | không | Cách plugin kết hợp đầu ra kết xuất theo từng nút của một nhóm điều phối: none ghi đầu ra của từng nút trực tiếp tại đường dẫn điều phối; merge gộp các phân đoạn theo từng nút thành một tài liệu; nest đặt đầu ra của từng nút dưới vị trí riêng của nó trong một cấu trúc bao trùm. Khi vắng mặt, không có tuyên bố nào về cách lắp ráp. Giá trị cho phép: "none", "merge", "nest" |
artifactDelimiters | object | không | Cặp dấu phân cách Go-template mà plugin áp dụng cho các tệp artifact được nhập. Khi vắng mặt, dùng cặp mặc định {{/}}; một plugin có cú pháp đích xung đột với cặp đó khai báo một cặp thay thế tại đây. |
assemblyNameAnnotation | object | không | Annotation ranh giới có giá trị đã phân giải đặt tên cho artifact mà plugin lắp ráp từ một nhóm điều phối. Một plugin gộp các ranh giới đóng góp của một nhóm thành một bản lắp ráp có tên sẽ khai báo khóa annotation mà nó đọc và việc mọi ranh giới đóng góp có phải thống nhất về giá trị đã phân giải của annotation đó hay không. Khi vắng mặt, plugin đặt tên bản lắp ráp chỉ từ đường dẫn điều phối. |
reusableInstance | boolean | không | Liệu một phiên bản plugin đã tải có thể phục vụ mọi lượt gọi render, assemble và validate của một bản build thay vì một phiên bản mới cho mỗi lượt gọi hay không. Chỉ khai báo true khi plugin không giữ trạng thái giữa các lượt gọi — là một hàm thuần của đầu vào theo từng lượt gọi — để một phiên bản duy nhất tạo ra đầu ra giống hệt từng byte dù được dùng lại hay tải mới. Khi vắng mặt (false), một phiên bản mới được tải cho mỗi lượt gọi, cô lập một plugin vốn mang trạng thái theo cấu tạo. |
crossBoundaryLinking | boolean | không | Liệu plugin có nối một cạnh uses xuyên ranh giới — một cạnh uses có đầu tiêu thụ và đầu được tiêu thụ lắp ráp vào các nhóm điều phối khác nhau — bằng cách phát ra liên kết tham chiếu chéo gốc của provider thông qua một hợp đồng export ghép cặp link_publish/link_resolve hay không. Chỉ khai báo true khi plugin export cả hai; một tuyên bố không khớp với cặp export sẽ dừng khi tải. Khi vắng mặt (false), không khai báo liên kết xuyên ranh giới, nên host không chuyển lượt gọi liên kết nào tới plugin. |
omits | boolean | không | Liệu provider có tôn trọng các mục omit — các mục đặt tên những đơn vị được kết xuất cần loại khỏi đầu ra của một nút — hay không: provider loại mọi đơn vị mà một mục khớp khỏi những gì nó kết xuất, và báo cáo mỗi mục đã khớp bao nhiêu đơn vị. Đây là bản ghi tại thời điểm publish của tuyên bố omits mà bản tự báo cáo của provider đưa ra, và một giá trị khác với báo cáo đó sẽ dừng khi tải. Khi vắng mặt (false), không khai báo hỗ trợ như vậy. |
boundaryArtifacts | boolean | không | Liệu provider có chấp nhận các tệp mà một Recipe đóng góp vào đầu ra dùng chung của ranh giới mà nó kết xuất trong đó, dưới spec.boundary.artifacts của Recipe, hay không: trình biên dịch ghi mỗi tệp như vậy một lần, trong thư mục chứa đầu ra đã lắp ráp của ranh giới, và đích của provider coi nó là một phần của đầu ra đó. Đây là bản ghi tại thời điểm publish của tuyên bố boundary_artifacts mà bản tự báo cáo của provider đưa ra, và một giá trị khác với báo cáo đó sẽ dừng khi tải. Khi vắng mặt (false), không khai báo hỗ trợ như vậy, và một Recipe khai báo khối này cho provider này sẽ bị từ chối trước khi bất cứ thứ gì được kết xuất. |
nestSegment | string | không | Thư mục mà đích của provider này đặt thư mục con riêng của mỗi bên đóng góp vào bên dưới, đối với một provider có boundaryAssembly là nest — charts cho một chart bao trùm, modules cho một root module. Trình biên dịch nối thư mục này, tên của bên đóng góp và đường dẫn riêng của từng tệp. Chỉ được đọc đối với một provider lồng. Khi vắng mặt, thư mục con của mỗi bên đóng góp được đặt trực tiếp tại thư mục riêng của ranh giới. Giá trị này đặt tên một thư mục và không bao giờ là một đường dẫn. |
sourceIgnore | object | không | Các tệp mà hệ sinh thái của provider này không bao giờ phát hành cùng một nguồn mà nó kết xuất, dưới dạng quy tắc bỏ qua theo cú pháp gitignore — bản ghi tại thời điểm publish của các quy tắc source_ignore mà bản tự báo cáo của nó khai báo. Khi một tác giả ghim một Recipe hoặc FeatureRecipe có capability mà provider này phục vụ cho họ, các quy tắc này được kết hợp với .aggregaignore riêng của tác giả và được ghi trong entity.lock bên cạnh thực thể, cùng với tên của plugin này, và mọi lần publish, so sánh và kết xuất nguồn cục bộ của thực thể về sau đều áp dụng các quy tắc đã ghi. Khi có mặt, nó phải bằng những gì bản tự báo cáo khai báo, và việc tải sẽ từ chối một plugin có báo cáo khác; khi vắng mặt, không có tuyên bố nào và không được so sánh. |
Không cho phép thuộc tính bổ sung.
plugin.spec.provider.contract.inputKinds
Plugin này kết xuất những loại đầu vào nào trong ba loại đầu vào của Recipe: một tập tệp có nguồn, một workload được tổng hợp, và một nút độc lập chỉ gồm artifact. Mỗi trường là một tuyên bố độc lập.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
sourced | boolean | không | Kết xuất một tập tệp được lấy từ nguồn (một chart, một module, một tệp compose). |
synthesized | boolean | không | Kết xuất một workload được tổng hợp thành các artifact gốc của provider. |
artifactsStandalone | boolean | không | Kết xuất một node độc lập chỉ chứa artifact — node mang các tài liệu artifact được nhập và không có source hay workload. |
Không cho phép thuộc tính bổ sung.
plugin.spec.provider.contract.artifactDelimiters
Cặp dấu phân cách Go-template mà plugin áp dụng cho các tệp artifact được nhập. Khi vắng mặt, dùng cặp mặc định {{/}}; một plugin có cú pháp đích xung đột với cặp đó khai báo một cặp thay thế tại đây.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
left | string | có | Dấu phân cách mở. |
right | string | có | Dấu phân cách đóng. |
Không cho phép thuộc tính bổ sung.
plugin.spec.provider.contract.assemblyNameAnnotation
Annotation ranh giới có giá trị đã phân giải đặt tên cho artifact mà plugin lắp ráp từ một nhóm điều phối. Một plugin gộp các ranh giới đóng góp của một nhóm thành một bản lắp ráp có tên sẽ khai báo khóa annotation mà nó đọc và việc mọi ranh giới đóng góp có phải thống nhất về giá trị đã phân giải của annotation đó hay không. Khi vắng mặt, plugin đặt tên bản lắp ráp chỉ từ đường dẫn điều phối.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
annotation | string | có | Khóa annotation của boundary mà plugin đọc tên của artifact được lắp ráp từ đó. |
requireUnique | boolean | không | Mọi boundary đóng góp vào một nhóm dispatch có phải thống nhất về giá trị đã phân giải của annotation hay không. Khi là true, một nhóm có các boundary đóng góp phân giải annotation thành các giá trị khác nhau sẽ dừng bản build; khi là false, plugin chấp nhận giá trị được phân giải đầu tiên. |
Không cho phép thuộc tính bổ sung.
plugin.spec.provider.contract.sourceIgnore
Các tệp mà hệ sinh thái của provider này không bao giờ phát hành cùng một nguồn mà nó kết xuất, dưới dạng quy tắc bỏ qua theo cú pháp gitignore — bản ghi tại thời điểm publish của các quy tắc source_ignore mà bản tự báo cáo của nó khai báo. Khi một tác giả ghim một Recipe hoặc FeatureRecipe có capability mà provider này phục vụ cho họ, các quy tắc này được kết hợp với .aggregaignore riêng của tác giả và được ghi trong entity.lock bên cạnh thực thể, cùng với tên của plugin này, và mọi lần publish, so sánh và kết xuất nguồn cục bộ của thực thể về sau đều áp dụng các quy tắc đã ghi. Khi có mặt, nó phải bằng những gì bản tự báo cáo khai báo, và việc tải sẽ từ chối một plugin có báo cáo khác; khi vắng mặt, không có tuyên bố nào và không được so sánh.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
patterns | string[] | không | Các mẫu bỏ qua riêng của hệ sinh thái, mỗi mẫu được tính từ gốc của thư mục nguồn cục bộ, theo thứ tự chúng được áp dụng. |
files | string[] | không | Tên các tệp bỏ qua mà hệ sinh thái tuân theo bên trong một nguồn — .helmignore đối với một chart. Các dòng của mỗi tệp như vậy là các mẫu bổ sung, được tính từ thư mục chứa tệp đó. |
Không cho phép thuộc tính bổ sung.
plugin.spec.pipelineStep
Khối pipeline-step cho một plugin pluginType: pipeline-step: các capability của provider mà bước của nó tương thích. Chỉ có mặt trên các plugin pipeline-step; vắng mặt trên mọi loại plugin khác.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
capabilities | string[] | không | Được aggrega plugin gen-catalog ghi lại từ bản tự báo cáo của .wasm của plugin, nên plugin là nguồn của danh sách này. Tác giả có thể thu hẹp danh sách trước khi publish, loại bỏ một mục mà thực thể này không nên cung cấp, nhưng không được thêm mục nào mà bản tự báo cáo không nêu: publish, và aggrega validate khi được truyền .wasm của plugin qua --plugin, từ chối một danh sách nêu một capability mà bản tự báo cáo không nêu. Publish gửi thực thể đúng như đã viết, không bao giờ viết lại danh sách này, và ghi chú mỗi capability mà bản tự báo cáo nêu nhưng danh sách bỏ sót. Các capability của provider mà bước pipeline của plugin này tương thích — các tên capability của provider, chẳng hạn helm hoặc compose, có đầu ra kết xuất mà bước này biết cách biến đổi. Một bước được viết cho hình dạng đầu ra của một provider tại một thời điểm, nên danh sách là một tuyên bố tương thích rõ ràng, đã được kiểm thử, chứ không phải một mong muốn. Các mục giữ nguyên thứ tự của tác giả. Đây là bản ghi mà catalog đọc được của tuyên bố đó; bản build đọc cùng tuyên bố đó từ plugin khi một bước chạm tới một phạm vi và dừng khi provider kết xuất các tài liệu của phạm vi đó không nằm trong số đó. Một danh sách rỗng hoặc vắng mặt không khai báo tuyên bố tương thích nào, nên không phạm vi nào chấp nhận bước này. |
Không cho phép thuộc tính bổ sung.
plugin.spec.parser
Khối parser cho một plugin pluginType: parser: các định dạng nguồn mà nó chuyển thành một cây có cấu trúc chuẩn. Chỉ có mặt trên các plugin parser; vắng mặt trên mọi loại plugin khác.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
capabilities | string[] | không | Được aggrega plugin gen-catalog ghi lại từ bản tự báo cáo của .wasm của plugin, nên plugin là nguồn của danh sách này. Tác giả có thể thu hẹp danh sách trước khi publish, loại bỏ một mục mà thực thể này không nên cung cấp, nhưng không được thêm mục nào mà bản tự báo cáo không nêu: publish, và aggrega validate khi được truyền .wasm của plugin qua --plugin, từ chối một danh sách nêu một capability mà bản tự báo cáo không nêu. Publish gửi thực thể đúng như đã viết, không bao giờ viết lại danh sách này, và ghi chú mỗi capability mà bản tự báo cáo nêu nhưng danh sách bỏ sót. Các định dạng nguồn mà parser này chuyển thành một cây có cấu trúc chuẩn, mỗi định dạng được viết dưới dạng parse:<format> — ví dụ parse:yaml. Tiền tố là một phần của mục, nên một plugin quảng bá nhiều định dạng liệt kê một mục cho mỗi định dạng. Các mục giữ nguyên thứ tự của tác giả. Một định dạng được yêu cầu phân giải tới parser có danh sách chứa mục khớp; một định dạng không parser nào quảng bá sẽ dừng bản build, và một định dạng được nhiều hơn một plugin parser quảng bá sẽ dừng vì mơ hồ. Một danh sách rỗng hoặc vắng mặt không khai báo tuyên bố định dạng nào, nên plugin không phân tích gì cả. |
Không cho phép thuộc tính bổ sung.
plugin.spec.importer
Khối importer cho một plugin pluginType: importer: các định dạng nguồn ngoại lai mà nó chuyển thành các tệp soạn thảo Aggrega nháp, và các dấu hiệu nhận biết một nguồn thuộc các định dạng đó. Chỉ có mặt trên các plugin importer; vắng mặt trên mọi loại plugin khác.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
capabilities | string[] | không | Được aggrega plugin gen-catalog ghi lại từ bản tự báo cáo của tệp .wasm của plugin, nên plugin là nguồn của danh sách này. Tác giả có thể thu hẹp danh sách trước khi xuất bản, loại bỏ một mục mà thực thể này không nên cung cấp, nhưng không được thêm mục nào mà bản tự báo cáo không nêu: việc xuất bản, và aggrega validate khi được truyền tệp .wasm của plugin qua --plugin, từ chối một danh sách nêu một capability mà bản tự báo cáo không nêu. Việc xuất bản gửi thực thể đúng như đã viết, không bao giờ viết lại danh sách này, và ghi chú mỗi capability mà bản tự báo cáo nêu nhưng danh sách bỏ sót. Các định dạng nguồn ngoại lai mà importer này chuyển thành các tệp soạn thảo Aggrega dạng nháp, mỗi định dạng được viết dưới dạng import:<format> — ví dụ import:terraform. Tiền tố là một phần của mục, nên một plugin quảng bá nhiều định dạng sẽ liệt kê một mục cho mỗi định dạng. Các mục giữ nguyên thứ tự của tác giả. Một định dạng import được yêu cầu sẽ được phân giải tới importer có danh sách chứa mục tương ứng; một định dạng không importer nào quảng bá sẽ dừng quá trình import, và một định dạng được nhiều hơn một plugin importer quảng bá sẽ dừng vì mơ hồ, trừ khi một mục plugins.importer trong cấu hình workspace gắn một trong số chúng, và khi đó importer đó sẽ chạy. Danh sách rỗng hoặc vắng mặt không khai báo định dạng nào, nên plugin không import gì. |
detect | object[] | không | Do máy quản lý, không tự soạn: được suy ra từ bản tự báo cáo của tệp .wasm của plugin khi thực thể được sinh ra từ nó, và được ghi lại ở đây theo thứ tự mà bản tự báo cáo khai báo. Các chữ ký giúp nhận diện một nguồn thuộc các định dạng của importer này khi một lần import không nêu định dạng nào. aggrega import đọc chữ ký của mọi importer mà catalog của workspace chứa, bao gồm mọi phiên bản, và của các importer lõi của trình biên dịch, đối chiếu chúng với nguồn mà không cần biết bất kỳ định dạng nào là gì, và đọc nguồn theo định dạng của importer duy nhất có chữ ký khớp; một nguồn không khớp chữ ký nào sẽ bị từ chối kèm yêu cầu nêu định dạng, và một nguồn khớp chữ ký của nhiều hơn một định dạng sẽ bị từ chối kèm tên các định dạng đó. Một importer nhận diện một nguồn thì nhận diện nó là mọi định dạng mà importer đó quảng bá, nên một importer quảng bá nhiều hơn một định dạng sẽ có mọi kết quả khớp bị từ chối vì mơ hồ. Khi có mặt, danh sách phải bằng đúng những gì bản tự báo cáo của plugin khai báo, từng mục một và theo đúng thứ tự, và quá trình nạp cũng như quá trình xuất bản sẽ từ chối một plugin có báo cáo khác, kèm tên trường này. Khi vắng mặt, trường này không khẳng định gì và không được so sánh, và khi đó các định dạng của importer chỉ được dùng khi nêu tên chúng. |
Không cho phép thuộc tính bổ sung.
plugin.spec.importer.detect[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
syntax | string | có | Định dạng cú pháp mà nguồn được phân tích theo — ví dụ json hoặc yaml — là định dạng mà một plugin parser quảng bá dưới dạng parse:<syntax>. Nguồn được phân tích qua parser mà catalog của workspace cung cấp cho cú pháp đó, hoặc, với cú pháp mà catalog không cung cấp parser nào, qua parser mà trình biên dịch mang sẵn, tối đa một lần dù có bao nhiêu chữ ký nêu cú pháp đó, và một nguồn không phân tích được theo cú pháp đó sẽ không khớp chữ ký nào nêu nó. Một cú pháp mà cả hai đều không cung cấp parser sẽ dừng quá trình nhận diện, kèm thông báo nêu rõ parser đó vắng mặt. Dài ít nhất 1 ký tự. |
files | string[] | không | Các mẫu tên tệp mà chữ ký áp dụng, được đối chiếu với phần cuối của tên nguồn, trong đó các dấu phân cách được đọc là dấu gạch chéo xuôi: một mẫu gồm một đoạn được đối chiếu với tên riêng của tệp, và một mẫu gồm nhiều đoạn phân cách bằng dấu gạch chéo được đối chiếu với đúng bấy nhiêu đoạn cuối của đường dẫn, nên .vscode/mcp.json khớp với một tệp tên mcp.json trong một thư mục tên .vscode. Trong một đoạn, * khớp với một chuỗi ký tự bất kỳ, ? khớp với một ký tự, và [...] khớp với một ký tự thuộc một lớp. Chữ ký được áp dụng khi có bất kỳ mẫu nào khớp. Khi vắng mặt hoặc rỗng, chữ ký được áp dụng cho một nguồn là một tệp, bất kể tên gì, và không áp dụng cho tệp nào của một thư mục. Các mẫu trong chữ ký của một importer cũng là thứ quyết định những tệp nào của một thư mục được aggrega import chuyển cho importer đó. |
match | object[] | không | Các vị từ mà cây đã phân tích phải thỏa mãn, tất cả chúng, theo thứ tự khai báo. Khi vắng mặt hoặc rỗng, không yêu cầu gì ở cây ngoài việc phân tích được theo cú pháp đó. |
Không cho phép thuộc tính bổ sung.
plugin.spec.importer.detect[].match[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
path | string | có | Vị trí trong cây mà vị từ xem xét, được viết dưới dạng các khóa nối bằng dấu chấm từ đỉnh của cây: data.nodes chỉ thành viên nodes của đối tượng data cấp cao nhất. Một đoạn được viết dưới dạng số nguyên, từ 0 trở lên, chọn vị trí đó của một mảng khi đếm từ 0, nên nodes.0.type chỉ type của node đầu tiên; mọi đoạn khác chọn một thành viên của một đối tượng. Dài ít nhất 1 ký tự. |
is | string (enum) | có | Những gì đường dẫn phải đạt tới: present đúng khi đường dẫn đạt tới một giá trị thuộc bất kỳ loại nào, kể cả null; absent đúng khi đường dẫn không đạt tới gì; object, array, string, number và boolean mỗi cái đúng khi đường dẫn đạt tới một giá trị thuộc loại đó. Giá trị cho phép: "present", "absent", "object", "array", "string", "number", "boolean" |
equals | string | không | Một chuỗi mà giá trị đường dẫn đạt tới phải bằng chính xác; một giá trị không phải chuỗi không bao giờ bằng nó. Trên một vị từ chỉ khai báo tối đa một trong hai equals và prefix. Dài ít nhất 1 ký tự. |
prefix | string | không | Một chuỗi mà giá trị đường dẫn đạt tới phải bắt đầu bằng nó; một giá trị không phải chuỗi không bao giờ bắt đầu bằng nó. Trên một vị từ chỉ khai báo tối đa một trong hai equals và prefix. Dài ít nhất 1 ký tự. |
Không cho phép thuộc tính bổ sung.