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.

Plugin

Một Plugin là một plugin WebAssembly được định địa chỉ theo nội dung: một artifact .wasm lưu trữ trên OCI, được ghim bằng digest sha256, khai báo loại socket mà nó triển khai, 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ể này là bề mặt soạn thảo và siêu dữ liệu cho một plugin; quá trình phân giải phụ thuộc ghim artifact theo digest, và chính sách tin cậy theo từng registry xác minh chữ ký của nó 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 đã được ghim; runtime WebAssembly thực thi các byte.

Trang này trình bày bề mặt soạn thảo catalog Plugin theo từng trường. Về quy trình làm việc đầu-cuối của tác giả — plugin là gì, phần tự báo cáo describe(), vòng đời publish→pull→build, ký và quản lý phiên bản — xem Hướng dẫn dành cho nhà phát triển plugin Wasm. Về các điểm socket mà một plugin gắn vào và dạng đầu vào/đầu ra của chúng, xem Hợp đồng plugin Wasm.

Vai trò của Plugin

Một Plugin gắn một định danh plugin logic với một artifact .wasm cụ thể, cùng với siêu dữ liệu về năng lực và thời gian chạy mà host cần để tải và chạy nó một cách an toàn. Một bước pipeline hoặc một socket plugin tham chiếu thực thể này qua URI của nó; thực thể mang các năng lực đã khai báo, các giới hạn thời gian chạy và con trỏ chữ ký, còn digest nội dung đã phân giải nằm trong lockfile của release. Vị trí của .wasm được suy ra từ định danh của plugin — tọa độ có thể định địa chỉ plugin/<pluginType>/<name>, bản thân nó được ghép từ metadata.pluginType và metadata.name trần, cộng với registry đã cấu hình — và không phải là một trường do người viết khai báo. Việc đi gián tiếp qua thực thể là bắt buộc — một tham chiếu .wasm hoặc artifact trần sẽ bị từ chối khi tải vì không có thực thể nào khớp với nó.

Các khai báo của một Plugin được nhóm theo loại socket, và cách nhóm đó là nơi bắt đầu đọc thực thể:

  • Một khối cho mỗi loại socket — spec.provider, spec.pipelineStep, spec.parser, spec.importer. Một plugin mang đúng một khối mà metadata.pluginType của nó nêu tên, và mỗi khối chứa một danh sách capabilities: — được aggrega plugin gen-catalog ghi lại từ describe() của chính plugin — có ý nghĩa chỉ thuộc về riêng khối đó: danh sách của một provider nêu các năng lực mà nó phục vụ, danh sách của một bước pipeline nêu các năng lực provider mà bước đó tương thích, còn danh sách của một parser và của một importer nêu các định dạng nguồn, được viết là parse:<format> và import:<format>. Chính việc chứa trong khối mang lại ý nghĩa — không thể đến được một mục năng lực mà không đọc trước khối cho biết đó là loại khẳng định nào.
  • Một khối provider mang nhiều hơn danh sách của nó — spec.provider còn khai báo cách plugin dịch loại Workload, những annotation gốc của nền tảng mà nó đọc, và hợp đồng hành vi render của nó (spec.provider.contract: các loại đầu vào, cách lắp ráp ranh giới, các dấu phân cách artifact, việc tái sử dụng instance). Những thứ đó mô tả hành vi render chứ không phải một chiều được phục vụ, đó là lý do chúng nằm bên cạnh danh sách năng lực của provider chứ không nằm bên trong nó.
  • Một socket xuyên suốt không khai báo năng lực nào — một plugin linter, governance hoặc cli không mang khối nào trong bốn khối, vì nó không phục vụ chiều render nào và không phục vụ định dạng nguồn nào.
apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
# capabilities is recorded by `aggrega plugin gen-catalog` from the plugin's describe(); an author may narrow it.
capabilities:
- helm
- compose
signature:
type: sigstore-cosign
runtime:
maxMemoryPages: 256
timeoutMs: 5000
# hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it.
exports:
- name: fetch
operates: emit
scope: own
selector: external-secret resources for the bound credential

metadata

Siêu dữ liệu danh mục tiêu chuẩn. name, version và pluginType là bắt buộc; version là một Semantic Version nghiêm ngặt (ví dụ 1.2.0). Các trường tùy chọn — description, maintainers, license, repository, home, keywords — có cùng cấu trúc mà mọi thực thể danh mục đều mang, và metadata không chấp nhận khóa nào khác. Một phiên bản đã xuất bản là bất biến: việc xuất bản lại một phiên bản đã tồn tại sẽ bị từ chối tại cổng xuất bản.

metadata.name là tên trần — nó không mang tiền tố socket. Tọa độ định địa chỉ plugin/<pluginType>/<name> của plugin được suy ra từ metadata.pluginType và metadata.name trần; nó không được viết trực tiếp vào tên.

metadata.pluginType

Loại socket mà plugin này triển khai. Trường này nằm trong khối định địa chỉ bên cạnh name và version vì nó là một phần định danh của plugin: nó cung cấp đoạn <pluginType> của tọa độ dẫn xuất plugin/<pluginType>/<name>. Mỗi plugin triển khai đúng một loại socket, lấy từ bảng phân loại plugin mà runtime nhận biết:

  • provider — kết xuất các nút IR thành các artifact gốc của provider.
  • linter — kiểm tra nội dung đã soạn và phát ra các 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 đã được render.
  • governance — đảm nhận các vai trò quản trị của pipeline build. Ở giai đoạn xây dựng topology, nó tự động gắn nhãn cho các nút của đồ thị topology, trả về các tài liệu JSON Patch mà host áp dụng lên một hình chiếu chỉ gồm nhãn của đồ thị. Ở giai đoạn phân tích tĩnh hoặc giai đoạn kết xuất, nó đánh giá đồ thị IR hoặc các artifact đã kết xuất và trả về phán quyết chấp nhận/từ chối; một quy tắc thất bại sẽ dừng build. 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 phép phát ra.
  • parser — phân tích một định dạng nguồn bên ngoài (HCL, TOML, YAML, JSON, …) thành một cây JSON có cấu trúc, nhờ đó một thành phần tiêu thụ cần đọc một định dạng mà trình biên dịch không phân tích sẵn có thể làm việc với cây đã phân tích thay vì văn bản thô.
  • importer — chuyển một nguồn định nghĩa hạ tầng hoặc agent bên ngoài thành các tệp soạn thảo Aggrega dạng bản nháp, công bố các định dạng mà nó xử lý dưới dạng các capability import:<format>.
  • cli — đóng góp một lệnh con runtime aggrega <cmd> mà người vận hành gọi từ dòng lệnh. Đây là một socket runtime, khác với các socket kết xuất và pipeline ở thời điểm biên dịch.

Bắt buộc.

spec.abiVersion

Phiên bản ABI host/guest mà plugin nhắm tới. v1beta1 là giá trị được chấp nhận; một bản sửa đổi ABI mới sẽ thêm một giá trị. Bắt buộc.

Khai báo capability: mỗi loại socket một khối

Một capability là thứ mà bên tiêu thụ yêu cầu ở một plugin — một capability render mà một Recipe yêu cầu, hoặc một định dạng nguồn mà một bản build cần đọc. Các capability của một plugin được ghi lại bên trong khối thuộc về loại socket của nó, vì vậy chính khối chứa danh sách là điều xác định ý nghĩa của các mục trong đó:

metadata.pluginTypeNơi khai báo các capabilityMột mục chỉ định điều gì
providerspec.provider.capabilitiesMột capability render mà plugin này phục vụ, chẳng hạn helm hoặc compose.
pipeline-stepspec.pipelineStep.capabilitiesMột provider mà bước của plugin này tương thích với đầu ra đã render của nó.
parserspec.parser.capabilitiesMột định dạng nguồn mà plugin này đọc, được viết là parse:<format>.
importerspec.importer.capabilitiesMột định dạng nguồn bên ngoài mà plugin này dùng để tạo bản nháp các thực thể, được viết là import:<format>.
linter, governance, cli—Không có. Các socket này không phục vụ capability nào, nên chúng không mang khối nào trong bốn khối trên.

Một plugin triển khai đúng một loại socket, nên thực thể của nó mang một khối. Danh sách là báo cáo của chính plugin: aggrega plugin gen-catalog đọc describe() của plugin và ghi từng capability mà nó báo cáo vào khối. Tác giả có thể thu hẹp danh sách trước khi xuất bản, bỏ đi một capability mà plugin báo cáo nhưng thực thể được xuất bản không nên cung cấp; aggrega validate <entity> --plugin <file.wasm> và aggrega push chấp nhận danh sách đã thu hẹp và in một thông báo nêu tên từng capability mà plugin báo cáo nhưng danh sách bỏ đi. Không lệnh nào chấp nhận một danh sách nêu một capability mà plugin không báo cáo: cả hai đều từ chối nó, nêu tên từng capability như vậy cùng các capability mà plugin thực sự báo cáo, nên một danh sách đã xuất bản không bao giờ cung cấp nhiều hơn những gì plugin cung cấp. Một thực thể pipeline-step mà plugin báo cáo helm và helm-chart nhưng lại liệt kê thêm compose sẽ bị từ chối như sau:

[E0080]
entity "probe-step:1.0.0-rc.1" lists capabilities ["compose"], which the plugin's describe() does not report (it reports ["helm" "helm-chart"]); remove them from the list, which may name only capabilities the plugin reports: wasm: entity contract claim does not match plugin describe()

Bên tiêu thụ phân giải đúng theo những gì được liệt kê.

spec.provider

Khối provider-socket dành cho một plugin pluginType: provider: các capability mà nó phục vụ, cách nó dịch kind Workload aggrega.ai/v1beta1 do nền tảng sở hữu, những annotation gốc của nền tảng mà nó đọc, và hợp đồng hành vi render của nó. Khối này có mặt trên mọi plugin render provider và vắng mặt trên mọi loại plugin khác. Một provider chỉ render nội dung sourced hoặc artifact mà không tổng hợp Workload vẫn mang khối này — nó khai báo các capability và hợp đồng của mình tại đó, và đơn giản là bỏ qua workloadSchema.

spec.provider.capabilities

Các capability mà provider này phục vụ — tên capability như helm hoặc compose — có hình dạng đầu ra mà nó render. Một provider mang tính tổng quát trên các artifact có chung hình dạng đầu ra của một capability, chứ không trên mọi capability, vì vậy danh sách nêu các capability mà chính plugin báo cáo: aggrega plugin gen-catalog ghi lại nó từ describe() của plugin, và tác giả có thể thu hẹp nó trước khi xuất bản. Các mục giữ nguyên thứ tự mà chúng được ghi lại.

Đích provider mà một Recipe yêu cầu (spec.capability: helm) được phân giải thành plugin provider có danh sách chứa đích đó. Khi nhiều plugin provider cùng liệt kê một đích, workspace sẽ chọn: lựa chọn plugins.providers trong cấu hình workspace nêu plugin nào được dùng, được phân giải tại aggrega pull và ghi vào lockfile. Khi không có lựa chọn và chỉ có đúng một ứng viên, ứng viên đó được dùng; khi không có lựa chọn và có nhiều ứng viên, quá trình build dừng lại và nêu tên mọi ứng viên. Sự mơ hồ được giải quyết theo từng workspace tại điểm sử dụng, chứ không bằng một quy tắc duy nhất trên toàn catalog. 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.

Tên capability ở đây không chứa dấu hai chấm. spec.capability của một Recipe được đọc là capability cho đến dấu hai chấm cuối cùng và một ghim phiên bản sau đó, nên một tên chứa dấu hai chấm sẽ không bao giờ được yêu cầu được; một plugin có describe() báo cáo tên như vậy sẽ bị từ chối khi nạp, và không entity nào được sinh từ nó để phát hành. Điều tương tự áp dụng cho các capability provider mà một plugin pipeline-step liệt kê. Dấu hai chấm trong parse:<format> của parser và import:<format> của importer là một phần của các tên đó và được giữ nguyên.

spec.provider.workloadSchema

Một khai báo JSON Schema 2020-12 mô tả cách provider này dịch kind Workload aggrega.ai/v1beta1 thành các manifest gốc của provider. Nó được khai báo theo quy ước trên một provider có tổng hợp: provider như vậy khai báo workloadSchema làm hợp đồng dịch được tài liệu hóa, mô tả những trường Workload mà provider sử dụng, những tập đóng mà mỗi trường dạng enum chấp nhận, và những ràng buộc phạm vi được áp dụng.

Phần thân được biên dịch thành JSON Schema 2020-12 khi Plugin được nạp — một hàng rào cấu trúc từ chối schema sai định dạng ngay lúc nạp thay vì lúc render. Việc một Recipe workload: có được hỗ trợ hay không được quyết định bởi khả năng tổng hợp của provider được gắn, chứ không bởi sự có mặt của trường này: một Recipe ở chế độ tổng hợp gắn với một provider không thể tổng hợp sẽ dừng lại rõ ràng lúc render. Catalog thư viện chuẩn giữ workloadSchema đồng bộ với capability của provider. Trường này là hợp đồng được tài liệu hóa; không có gì khác đọc nó. Bản thân các thân Workload được kiểm tra hợp lệ theo schema Workload nhúng do nền tảng sở hữu, chứ không theo trường riêng của từng provider này.

spec.provider.wellKnownAnnotations

Một mảng có thứ tự liệt kê các khóa annotation phổ biến gốc của nền tảng — những khóa nằm dưới namespace dành riêng aggrega.ai/ — mà provider này đọc, cùng với hành vi được áp dụng khi mỗi khóa vắng mặt. Mỗi mục mang một key (annotation mà provider đọc, ví dụ aggrega.ai/namespace), một purpose (điều annotation kiểm soát khi có mặt), một defaultBehavior tùy chọn (điều provider làm khi annotation vắng mặt), và một scope tùy chọn liệt kê nơi provider đọc khóa — sourced, synthesized hoặc artifactsStandalone, tức các loại đầu vào của Recipe, hoặc boundary cho một khóa được đọc một lần cho mỗi boundary. key và purpose là bắt buộc; các mục giữ nguyên thứ tự của tác giả.

Trường này là tuyên bố hỗ trợ của provider, và trình biên dịch đọc nó theo hai cách. Một mục có scope nêu một loại đầu vào mà contract.inputKinds của chính khối không khẳng định thì mâu thuẫn với khẳng định đó, và Plugin bị từ chối, kèm tên khóa và phạm vi. Ngoài ra, khi một bản build render qua provider này, một annotation aggrega.ai/ mà không mục nào bao phủ trên bất kỳ loại đầu vào nào mà lần render đó khai báo sẽ gây ra một cảnh báo nêu tên khóa, provider và các loại đầu vào đó; giá trị vẫn được truyền qua nguyên vẹn và bản build không dừng. Khi vắng mặt, trường này không đưa ra tuyên bố nào, và không có cảnh báo nào như vậy được phát ra cho provider này. Việc kiểm tra schema chỉ kiểm tra hình dạng của mỗi mục (khóa nằm dưới namespace aggrega.ai/, purpose có mặt); nó khác với bước kiểm tra lúc chạy chi phối việc gắn một giá trị vào namespace dành riêng.

metadata:
pluginType: provider
spec:
abiVersion: v1beta1
provider:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm
workloadSchema: |
# how the Workload kind translates to this provider's native output
...
wellKnownAnnotations:
- key: aggrega.ai/namespace
purpose: Overrides the target namespace the provider renders into.
defaultBehavior: Renders into the boundary's default namespace.

Các tập annotation theo từng provider và nội dung workloadSchema mà các provider của thư viện chuẩn cung cấp được tài liệu hóa tại ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md và ../providers/compose.md.

spec.provider.readsNoWellKnownAnnotations

Khai báo rằng provider này không đọc bất kỳ khóa annotation phổ biến gốc của nền tảng nào. Đây là một tuyên bố hỗ trợ không bao phủ khóa nào, và nó nói lên điều mà việc bỏ qua cả nó lẫn wellKnownAnnotations không nói được: một tuyên bố vắng mặt là sự im lặng, còn tuyên bố này là lời khẳng định của chính provider rằng nó không đọc gì dưới namespace dành riêng aggrega.ai/. Một bản build render qua provider như vậy sẽ cảnh báo về mọi annotation aggrega.ai/ đến được lần render, nêu tên khóa, provider và các loại đầu vào mà lần render đó khai báo; giá trị vẫn được truyền qua nguyên vẹn và bản 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ì. Nó không thể được viết cùng với wellKnownAnnotations: một provider đọc một số khóa thì thay vào đó liệt kê chúng ở đó. Cả hai sự từ chối đều ở cấp schema, nên Plugin bị từ chối khi được đọc.

spec:
provider:
capabilities:
- terraform
readsNoWellKnownAnnotations: true

Provider terraform của thư viện chuẩn khai báo nó; ../providers/terraform.md cho biết điều đó có nghĩa gì đối với một Release được render qua nó.

spec.provider.contract

Hợp đồng hành vi render tại thời điểm biên dịch mà một plugin render provider tự khai báo: các loại đầu vào mà nó render, cách nó ghép đầu ra theo từng node của một nhóm dispatch, 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 giao hay không, liệu nó có tuân theo các mục omit hay không, và 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 boundary hay không. Khối này nằm cạnh capabilities trong cùng một block nhưng trả lời một câu hỏi khác: danh sách capability cho biết plugin này phục vụ những capability nào, còn hợp đồng cho biết nó render chúng như thế nào. aggrega plugin gen-catalog ghi lại nó từ bản tự báo cáo describe() của chính plugin, và host đối chiếu nó với bản tự báo cáo đó khi publish và khi nạp; nếu không khớp thì quá trình dừng lại. Khi vắng mặt, không có hợp đồng hành vi render nào được khai báo, và việc đối chiếu chỉ so sánh các tuyên bố theo từng export. Mọi trường đều là tùy chọn.

TrườngTác dụng
inputKindsPlugin render những loại nào trong ba loại đầu vào của Recipe, mỗi loại là một tuyên bố boolean độc lập: sourced (một tập tệp có nguồn — một chart, một module, một tệp compose), synthesized (một Workload được tổng hợp), và artifactsStandalone (một node độc lập mang các tài liệu artifact được nhập và không có source hay workload). Host kiểm soát loại đầu vào của một node dựa trên tập này.
boundaryAssemblyCách plugin kết hợp đầu ra render theo từng node của một nhóm dispatch: none ghi đầu ra của từng node trực tiếp tại đường dẫn dispatch; merge gộp các phân đoạn theo từng node thành một tài liệu; nest đặt đầu ra của từng node vào 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ố ghép nào.
artifactDelimitersCặp dấu phân cách Go-template mà plugin áp dụng cho các tệp artifact được nhập, dưới dạng left và right. Khi vắng mặt nghĩa là dùng cặp mặc định {{/}}; một plugin có cú pháp đích xung đột với cặp đó sẽ khai báo một cặp thay thế (ví dụ [[/]]).
reusableInstanceLiệu một instance plugin đã nạp có thể phục vụ mọi lần chuyển giao render, assemble và validate của một bản build thay vì một instance mới cho mỗi lần chuyển giao hay không. Chỉ khai báo true khi plugin không giữ trạng thái giữa các lần chuyển giao, để một instance duy nhất tạo ra đầu ra giống hệt từng byte dù được dùng lại hay nạp mới. Khi vắng mặt (false), một instance mới được nạp cho mỗi lần chuyển giao, cô lập một plugin vốn mang trạng thái theo cấu tạo. aggrega build --verify-determinism chứng minh đầu ra của một plugin dùng lại được là ổn định bằng cách render mỗi node hai lần và dừng lại khi có bất kỳ khác biệt nào.
omitsLiệu plugin có tuân theo các mục omit hay không — các mục chỉ định những đơn vị được render cần loại khỏi đầu ra của một node: plugin loại mọi đơn vị mà một mục khớp ra khỏi những gì nó render, và báo cáo mỗi mục đã khớp bao nhiêu đơn vị. Giá trị ghi lại tuyên bố mà describe() của plugin báo cáo, nên true chỉ đúng với một plugin có báo cáo điều đó, và một giá trị khác với báo cáo sẽ khiến quá trình dừng lại. Khi vắng mặt (false), không khai báo hỗ trợ như vậy.
boundaryArtifactsLiệu đích của plugin 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 boundary mà nó render trong đó hay không, theo spec.boundary.artifacts của Recipe: compiler ghi mỗi tệp như vậy một lần, bên cạnh những gì plugin ghép cho boundary, và đích đọc nó như một phần của đầu ra đó. Giá trị ghi lại tuyên bố mà describe() của plugin báo cáo, và một giá trị khác với báo cáo sẽ khiến quá trình dừng lại. Khi vắng mặt (false), không khai báo hỗ trợ như vậy, và một Recipe khai báo block này cho plugin này sẽ bị từ chối trước khi bất cứ thứ gì được render.
metadata:
pluginType: provider
spec:
provider:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm-chart
contract:
inputKinds:
sourced: true
synthesized: false
artifactsStandalone: false
boundaryAssembly: nest
artifactDelimiters:
left: "[["
right: "]]"
reusableInstance: true

spec.pipelineStep

Khối pipeline-step dành cho một plugin pluginType: pipeline-step. Trường duy nhất của khối, capabilities, nêu tên các provider mà bước của plugin biết cách biến đổi đầu ra đã render của chúng — các tên capability như helm hoặc compose. Mỗi 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 này nêu các provider mà chính plugin báo cáo; các mục giữ nguyên thứ tự mà chúng được ghi lại. Khối này chỉ có mặt trên các plugin pipeline-step.

Khối này là bản ghi có thể đọc từ catalog của tuyên bố đó: aggrega plugin gen-catalog ghi lại nó từ bản tự báo cáo describe() của chính plugin, và tác giả có thể thu hẹp nó trước khi xuất bản. Cơ chế thực thi đọc cùng tuyên bố đó từ plugin: khi một bước chạm vào một phạm vi, quá trình build dừng lại trừ khi provider render các tài liệu của phạm vi đó nằm trong số những provider mà plugin tuyên bố. 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 đó.

metadata:
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm
- compose

spec.parser

Khối parser dành cho một plugin pluginType: parser. Trường duy nhất của khối, capabilities, nêu tên các định dạng nguồn mà plugin chuyển thành một cây có cấu trúc chuẩn tắc, mỗi định dạng được viết là parse:<format>. Tiền tố là một phần của mục, nên một plugin đọc nhiều định dạng sẽ liệt kê một mục cho mỗi định dạng. aggrega plugin gen-catalog ghi lại danh sách từ describe() của chính plugin, tác giả có thể thu hẹp nó trước khi xuất bản, và các mục giữ nguyên thứ tự mà chúng được ghi lại. Khối chỉ có mặt trên các plugin parser.

Một định dạng được yêu cầu sẽ được phân giải tới parser có danh sách chứa mục tương ứng. Một định dạng không parser nào công bố sẽ làm dừng bản build, và một định dạng được nhiều hơn một plugin parser công bố sẽ dừng do mơ hồ, nêu tên các ứng viên — không có phương án dự phòng, vì một parser không có mặc định không cần cấu hình nào để dự phòng. Một 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 phân tích gì cả.

metadata:
pluginType: parser
spec:
abiVersion: v1beta1
parser:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- parse:hcl
- parse:toml

spec.importer

Khối importer dành cho một plugin pluginType: importer. Trường capabilities của nó nêu tên các định dạng nguồn bên ngoài mà plugin 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 là import:<format>. Tiền tố là một phần của mục, vì vậy một plugin xử lý nhiều định dạng sẽ liệt kê một mục cho mỗi định dạng. aggrega plugin gen-catalog ghi lại danh sách từ describe() của chính plugin, tác giả có thể thu hẹp nó trước khi xuất bản, và các mục giữ nguyên thứ tự mà chúng được ghi lại. Khối này chỉ có mặt trên các plugin importer.

Một định dạng nhập được yêu cầu sẽ được phân giải về 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 nhập, và một định dạng được nhiều hơn một plugin importer quảng bá sẽ dừng với lý do mơ hồ, nêu tên các ứng viên, trừ khi một mục plugins.importer trong cấu hình workspace gắn một trong số chúng, khi đó importer đó là importer được chạy. Một 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 nhập gì cả.

Trường detect của nó ghi lại các chữ ký mà nhờ đó một nguồn thuộc các định dạng ấy được nhận diện khi một lần nhập không nêu tên định dạng. Trường này do máy sở hữu, giống như các bản ghi host-function và command: nó được suy ra từ những gì describe() của plugin báo cáo khi thực thể được sinh ra từ plugin, theo thứ tự plugin khai báo các chữ ký, và tác giả không tự viết nó. Mỗi chữ ký nêu:

  • syntax — định dạng cú pháp mà nguồn được phân tích theo, tức định dạng mà một plugin parser quảng bá dưới dạng parse:<syntax>, chẳng hạn json hoặc yaml.
  • files — các mẫu tên tệp tùy chọn, được so khớp với phần cuối của tên nguồn: một mẫu gồm một đoạn được so với chính tên tệp, một mẫu gồm nhiều đoạn phân tách bằng dấu gạch chéo được so với chừng ấy đoạn cuối của đường dẫn, vì vậy .vscode/mcp.json khớp với một tệp tên mcp.json trong một thư mục tên .vscode. *, ? và [...] khớp trong phạm vi một đoạn. Khi vắng mặt, chữ ký á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 mà aggrega import chuyển cho nó.
  • match — các vị từ mà cây đã phân tích phải thỏa mãn, tất cả chúng. Mỗi vị từ có một path, các khóa nối bằng dấu chấm từ gốc của cây, trong đó một đoạn là số nguyên chọn một vị trí trong mảng; một is, là một trong present, absent, object, array, string, number và boolean; và tùy chọn equals, một chuỗi mà giá trị phải bằng, hoặc prefix, một chuỗi mà giá trị phải bắt đầu bằng — tối đa một trong hai.

Khi một lần nhập không nêu tên định dạng, cá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 được so khớp với nguồn. Nguồn được phân tích một lần cho mỗi cú pháp mà một chữ ký áp dụng cho tên của nó đọc nó theo, thông 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, parser do chính trình biên dịch mang theo — và một nguồn không phân tích được theo một cú pháp sẽ không khớp chữ ký nào nêu tên cú pháp đó. Một thư mục được so khớp thông qua các tệp của nó: mỗi chữ ký được thử với các tệp của thư mục mà các mẫu của nó chọn, theo thứ tự tên, và một chữ ký không khai báo mẫu nào không áp dụng cho tệp nào. Một nguồn khớp với một chữ ký được nhận diện là mọi định dạng mà importer của chữ ký đó quảng bá. Khi nhận diện được đúng một định dạng, đó là định dạng nguồn được đọc theo. 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à tên các định dạng mà các importer quảng bá — hoặc, với một thư mục, kèm yêu cầu chỉ định riêng một trong các tệp của nó hoặc một định dạng có importer khai báo mẫu tệp, chỉ nêu tên các định dạng đó; một nguồn được nhận diện là nhiều hơn một định dạng sẽ bị từ chối kèm tên các định dạng đó, với điều kiện More than one importer recognises the source (Có nhiều hơn một importer nhận diện nguồn). Vì vậy, một importer quảng bá nhiều hơn một định dạng sẽ khiến mọi nguồn khớp với chữ ký của nó bị từ chối vì mơ hồ, và một importer muốn các nguồn của mình được nhận diện thì chỉ phục vụ một định dạng.

Khi entity ghi lại detect, giá trị này phải bằng đúng những gì describe() của plugin báo cáo, khớp từng chữ ký và theo đúng thứ tự: việc nạp importer sẽ từ chối một plugin có báo cáo khác biệt, nêu tên importer.detect, và việc phát hành nó cũng vậy. Một entity không ghi lại detect thì không đưa ra khẳng định nào và không bị so sánh, nên nó nạp bất kỳ chữ ký nào mà describe() của plugin báo cáo, và khi đó các định dạng của importer chỉ được dùng đến khi chúng được nêu tên.

metadata:
pluginType: importer
spec:
abiVersion: v1beta1
importer:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- import:langflow
detect:
- syntax: json
match:
- path: data.nodes
is: array

spec.signature

Một con trỏ mô tả tùy chọn trỏ tới chữ ký được đí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 chấp nhận plugin. Bước kiểm tra có hiệu lực thực thi là chính sách tin cậy theo từng registry được áp dụng khi pull: chữ ký được tải về dưới dạng một OCI referrer, được xác minh dựa trên các danh tính tin cậy hoặc khóa được ghim của registry, và được ghi lại như một sự thật đã 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ệ.

  • type — lược đồ chữ ký. sigstore-cosign là lược đồ được hỗ trợ. Bắt buộc khi có khối này.
  • signatureRef — tham chiếu OCI referrer của gói chữ ký được đính kèm, phục vụ tài liệu và việc khám phá. Vắng mặt khi chữ ký được khám phá bằng cách liệt kê referrer lúc pull thay vì được ghim tại đây.
  • publicKeyRef — một con trỏ tới khóa công khai đã được dùng để tạo chữ ký, đối với chữ ký có khóa. Khi vắng mặt, điều đó cho biết đây là chữ ký không dùng khóa (danh tính OIDC), được xác minh dựa trên các danh tính tin cậy của registry.

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 ra ngoài không phải là một trường do người viết khai báo: plugin không bao giờ truy cập mạng tại thời điểm build — ranh giới ahead-of-time — nên ở đây không có trường danh sách cho phép host. Nội dung từ xa mà plugin cần được đưa đến qua kênh đầu vào bên ngoài do host làm trung gian, được ghim theo digest và ghi lại trong lockfile của Release, không bao giờ qua quyền truy cập mạng sẵn có; hướng dẫn cho nhà phát triển mô tả wrapper fetch và nguyên tắc ghim.

TrườngTác dụng
maxMemoryPagesGiới hạn bộ nhớ tuyến tính của plugin theo số trang Wasm (64 KiB mỗi trang). Giá trị 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 thì tăng giá trị này.
timeoutMsGiới hạn thời gian mà mã riêng của plugin được chạy trong một lần gọi, tính bằng mili giây, không tính thời gian ở 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 không được tính; trên các hệ thống khác, đó là thời gian thực đã trôi qua. 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 của chính plugin. Giá trị 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 thì tăng giá trị này.
hostFunctionsTên các hàm host mà plugin import. Được máy suy ra và chỉ đọc — đừng tự khai báo: aggrega plugin sync đọc các hàm host từ phần import của .wasm và ghi vào trường này, lệnh publish từ chối một bản ghi khác với binary, và giá trị phản ánh binary đã publish, được kiểm tra đối chiếu với danh sách cho phép đã chọn lọc. Host đăng ký đúng tập hợp này, cấp cho mỗi plugin bề mặt host với đặc quyền tối thiểu mà binary của nó cần; lệnh pull suy ra lại và xác minh giá trị đã ghi so với binary. Để xem trước giá trị trước khi publish, hãy chạy aggrega inspect --plugin <file.wasm>.
configKVCấu hình riêng của Plugin mà runtime trao 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 đến từng byte qua 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.

spec.exports

Các export mà plugin cung cấp, mỗi export kèm năng lực đã khai báo của nó, dưới dạng một danh sách có thứ tự giữ nguyên thứ tự của tác giả. 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 năng lực của từng export nêu việc export đó làm, theo cách aggrega plugin gen-catalog ghi lại từ bản tự khai báo describe() của plugin, và host đối chiếu nó với bản tự khai báo đó khi publish và khi tải. Nếu vắng mặt thì không khai báo bề mặt export nào do tác giả viết.

TrườngTác dụng
nameTên ABI của export — tên mà host điều phối tới. Bắt buộc cho mỗi mục.
operatesThao tác pipeline mà export thực hiện: patch (sửa đổi một tài liệu đã render sẵn có) hoặc emit (thêm một tài liệu mới). Host đối chiếu giá trị này với bản tự khai báo của plugin; đây là một tuyên bố năng lực được xác thực, không phải một công tắc điều phối — thao tác mà một bước thực hiện được mang trong kết quả do guest trả về. Nếu vắng mặt thì không mang tuyên bố thao tác nào.
scopeGốc tài liệu mà export 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). Host đọc phạm vi đã khai báo trước bước để thực thi tính tương thích provider với provider đang render phạm vi đó. Nếu vắng mặt thì mặc định là own.
selectorMột mô tả dạng tự do, dễ đọc cho con người về đối tượng mà export tác động (ví dụ workloads carrying a pod template). Đây là tài liệu cho người đọc catalog và bề mặt inspect; trình biên dịch không diễn giải nó.

spec.commands

Các động từ cấp cao nhất aggrega <command> mà một plugin cli đóng góp, dưới dạng một danh sách có thứ tự giữ nguyên thứ tự mà bản tự khai báo describe() của plugin khai báo. Do máy sở hữu và chỉ đọc — đừng tự viết trường này. aggrega plugin sync đọc bề mặt lệnh từ bản tự khai báo describe() của plugin và ghi lại ở đây, nhờ đó có thể đọc các lệnh mà một plugin CLI cài đặt ngay từ entity mà không cần tải .wasm. 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 hợp này; một tập hợp đã ghi lại khác với bản tự khai báo describe() của plugin sẽ bị dừng khi tải, và publish từ chối một tập hợp không đồng bộ với tệp nhị phân và hướng dẫn tác giả ghi lại nó. Để đồng bộ lại bản ghi sau khi thay đổi plugin, hãy chạy aggrega plugin sync.

Mỗi mục lệnh mang:

TrườngTác dụng
nameĐộng từ lệnh mà host đăng ký — token aggrega <name> mà người vận hành gọi, đồng thời là giá trị phân biệt mà host trao cho plugin khi gọi, để một plugin duy nhất đứng sau nhiều lệnh có thể định tuyến theo lệnh đã được gọi. Bắt buộc cho mỗi mục.
descriptionVă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ó.
flagsCác cờ của lệnh, theo thứ tự đã khai báo. Mỗi mục đăng ký một cờ trên lệnh để aggrega help <command> hiển thị nó giống như cờ của một lệnh lõi. Một lệnh không có cờ để trống trường này.

Mỗi mục flags khai báo một cờ:

TrườngTác dụng
nameTên dài của cờ — token --name mà người vận hành truyền trên dòng lệnh. Bắt buộc cho mỗi mục.
shorthandBí 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.
descriptionVă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. Là tài liệu tùy chọn; host không xác thực cũng không xử lý nó.
typeKiểu giá trị của cờ — string, bool hoặc int — và là loại cờ mà phần trợ giúp hiển thị. Nếu vắng mặt thì cờ được hiển thị như một cờ chuỗi.
defaultGiá 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.

Một plugin CLI khai báo các lệnh và cờ của chúng trong describe(); host đăng ký đúng bề mặt đó và hiển thị các cờ của từng lệnh trong aggrega help <command> giống như cách nó hiển thị cờ của một lệnh tích hợp sẵn.

Host kiểm tra mọi cờ mà một plugin khai báo khi thêm các lệnh của plugin đó, và một plugin có khai báo không hợp lệ sẽ bị bỏ qua thay vì được thêm vào: không lệnh nào của nó được đăng ký, một cảnh báo nêu tên plugin, lệnh, cờ và lỗi của cờ đó, và mọi lệnh khác — tích hợp sẵn hoặc từ plugin khác — vẫn hoạt động. Một khai báo không hợp lệ khi:

  • một cờ không có tên, hoặc một lệnh khai báo cùng một tên hai lần;
  • một shorthand không phải là một chữ cái hoặc chữ số ASCII duy nhất, hoặc một lệnh khai báo cùng một shorthand cho hai cờ;
  • một tên hoặc shorthand dùng lại một cờ mà mọi lệnh aggrega đều đã có — --help, dạng -h của nó, và các cờ toàn cục như --offline và --config;
  • một kiểu không phải là string, bool hoặc int;
  • một giá trị mặc định không phân tích được theo kiểu của cờ — maybe cho một bool, three cho một int.

Dạng một ký tự của shorthand và ba giá trị của type cũng là một phần của schema của entity này, nên một entity Plugin ghi lại bất kỳ giá trị nào khác sẽ bị từ chối khi catalog được tải. Việc một tên hoặc shorthand chỉ xuất hiện một lần mỗi lệnh, việc không tên nào dùng lại một cờ mà mọi lệnh đều có, và việc một giá trị mặc định phân tích được theo kiểu của nó chỉ do host kiểm tra. Việc kiểm tra này xác định liệu host có thể khai báo một cờ cho phần trợ giúp như đã viết hay không; nó không biết liệu plugin có đọc các cờ mà nó khai báo hay không, vì plugin tự phân tích các đối số của mình.

metadata:
pluginType: cli
spec:
abiVersion: v1beta1
# commands is recorded by `aggrega plugin sync` from the plugin's describe() — do not author it.
commands:
- name: greet
description: Print a friendly greeting
flags:
- name: name
shorthand: n
description: Who to greet
type: string
default: world

Kiểm tra một Plugin

aggrega inspect <path-to-Plugin.yaml> hiển thị một tệp Plugin: danh tính và loại socket của nó, các khả năng mà khối của nó khai báo, bảng khả năng theo từng export theo thứ tự của tác giả, các ràng buộc thời gian chạy, và — ở mức --detail — con trỏ chữ ký cùng các khóa cấu hình thời gian chạy. Có thể tham chiếu một Plugin bằng đường dẫn tệp, hoặc bằng tọa độ <pluginType>/<name> của nó trong catalog. Xem ../cli/aggrega-inspect.md.

Tham chiếu chéo

  • Hướng dẫn phát triển plugin Wasm — quy trình làm việc đầy đủ của tác giả: describe(), khai báo năng lực, giới hạn thời gian chạy, vòng đời, ký số, quản lý phiên bản.
  • Hợp đồng plugin Wasm — các điểm socket mà một plugin gắn vào và cấu trúc đầu vào/đầu ra của chúng.
  • entities/featurerecipe.md — bề mặt pipeline: của FeatureRecipe, nơi tham chiếu một plugin qua URI của thực thể.
  • cli/aggrega-lint.md — trình kiểm tra xuất bản, bộ tiêu chí tăng phiên bản và cơ chế bảo đảm tính bất biến chi phối việc xuất bản một Plugin.