Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Plugin

Plugin adalah plugin WebAssembly yang dialamatkan berdasarkan konten: artefak .wasm yang di-host di OCI dan dipatok dengan digest sha256, yang mendeklarasikan jenis soket yang diimplementasikannya, versi ABI yang ditargetkannya, penunjuk tanda tangan opsional, dan blok runtime opsional. Entitas ini adalah permukaan penulisan dan metadata untuk sebuah plugin; resolusi dependensi mematok artefak berdasarkan digest, dan kebijakan kepercayaan per registri memverifikasi tanda tangannya saat penarikan. Compiler tidak menafsirkan perilaku plugin — compiler meneruskan referensi yang dipatok; runtime WebAssembly mengeksekusi byte-nya.

Halaman ini membahas permukaan penulisan katalog Plugin per bidang. Untuk alur kerja penulis secara menyeluruh — apa itu plugin, laporan diri describe(), siklus hidup publish→pull→build, penandatanganan, dan pembuatan versi — lihat panduan pengembang plugin Wasm. Untuk titik soket tempat plugin terpasang serta bentuk input/output-nya, lihat kontrak plugin Wasm.

Peran Plugin

Sebuah Plugin mengikat identitas plugin logis ke artefak .wasm yang konkret serta ke metadata kapabilitas dan runtime yang dibutuhkan host untuk memuat dan menjalankannya dengan aman. Langkah pipeline atau soket plugin mereferensikan entitas tersebut melalui URI-nya; entitas membawa kapabilitas yang dideklarasikan, batas runtime, dan penunjuk tanda tangan, sedangkan digest konten yang telah di-resolve disimpan di lockfile release. Lokasi .wasm diturunkan dari identitas plugin — koordinat beralamat plugin/<pluginType>/<name>, yang tersusun dari metadata.pluginType dan metadata.name polos, ditambah registry yang dikonfigurasi — dan bukan merupakan field yang ditulis. Indireksi melalui entitas bersifat wajib — referensi .wasm atau artefak polos ditolak saat pemuatan karena tidak ada entitas yang cocok dengannya.

Deklarasi sebuah Plugin dikelompokkan berdasarkan jenis soket, dan pengelompokan itulah titik awal membaca entitas tersebut:

  • Satu blok per jenis soket — spec.provider, spec.pipelineStep, spec.parser, spec.importer. Sebuah plugin membawa satu blok yang disebut oleh metadata.pluginType-nya, dan setiap blok memuat daftar capabilities: — yang direkam oleh aggrega plugin gen-catalog dari describe() milik plugin itu sendiri — yang maknanya hanya milik blok tersebut: daftar milik provider menyebutkan kapabilitas yang dilayaninya, daftar milik langkah pipeline menyebutkan kapabilitas provider yang kompatibel dengan langkahnya, dan daftar milik parser serta importer menyebutkan format sumber, yang ditulis parse:<format> dan import:<format>. Penampunganlah yang membawa makna — sebuah entri kapabilitas tidak dapat dicapai tanpa terlebih dahulu membaca blok yang menyatakan jenis klaim apa entri tersebut.
  • Blok provider membawa lebih dari sekadar daftarnya — spec.provider juga mendeklarasikan cara plugin menerjemahkan jenis Workload, anotasi bawaan platform mana yang dibacanya, dan kontrak perilaku render-nya (spec.provider.contract: jenis input, perakitan batas, pembatas artefak, penggunaan ulang instans). Hal-hal tersebut menggambarkan perilaku render, bukan dimensi yang dilayani, sehingga semuanya diletakkan di samping daftar kapabilitas provider, bukan di dalamnya.
  • Soket lintas-fungsi tidak mendeklarasikan kapabilitas — plugin linter, governance, atau cli tidak membawa satu pun dari keempat blok tersebut, karena plugin itu tidak melayani dimensi render maupun format sumber apa pun.
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

Metadata katalog standar. name, version, dan pluginType wajib diisi; version adalah Semantic Version yang ketat (misalnya 1.2.0). Field opsional — description, maintainers, license, repository, home, keywords — mengikuti bentuk yang sama dengan yang dimiliki setiap entitas katalog, dan metadata tidak menerima kunci lain. Versi yang telah dipublikasikan tidak dapat diubah: publikasi ulang versi yang sudah ada ditolak pada gerbang publikasi.

metadata.name bersifat polos — tidak memuat prefiks soket. Koordinat yang dapat dialamatkan milik plugin, plugin/<pluginType>/<name>, diturunkan dari metadata.pluginType dan metadata.name yang polos; koordinat ini tidak ditulis ke dalam nama.

metadata.pluginType

Jenis socket yang diimplementasikan oleh plugin ini. Field ini berada di blok pengalamatan di samping name dan version karena merupakan bagian dari identitas plugin: field ini menyediakan segmen <pluginType> dari koordinat turunan plugin/<pluginType>/<name>. Sebuah plugin mengimplementasikan tepat satu jenis socket, yang diambil dari taksonomi jenis plugin yang dikenali oleh runtime:

  • provider — merender node IR menjadi artefak native provider.
  • linter — memeriksa konten yang ditulis dan memunculkan diagnostik.
  • pipeline-step — langkah dalam pipeline: milik FeatureRecipe atau Recipe yang menambal himpunan dokumen yang telah di-render.
  • governance — menjalankan peran tata kelola build-pipeline. Pada tahap konstruksi topologi, plugin ini secara otomatis menandai label node graf topologi, dengan mengembalikan dokumen JSON Patch yang diterapkan host pada proyeksi graf yang hanya berisi label. Pada tahap analisis statis atau tahap render, plugin ini mengevaluasi graf IR atau artefak yang dirender dan mengembalikan putusan terima/tolak; aturan yang gagal menghentikan build. Peran tempat plugin ini dipasang, bukan jenisnya, yang menentukan apa yang boleh dikeluarkannya.
  • parser — mengurai format sumber asing (HCL, TOML, YAML, JSON, …) menjadi pohon JSON terstruktur, sehingga konsumen yang perlu membaca format yang tidak diurai secara native oleh compiler bekerja dari pohon hasil penguraian, bukan dari teks mentah.
  • importer — mengubah sumber infrastruktur atau definisi agen asing menjadi draf file penulisan Aggrega, dengan mengiklankan format yang ditanganinya sebagai kapabilitas import:<format>.
  • cli — menyumbangkan subperintah runtime aggrega <cmd> yang dipanggil operator di baris perintah. Ini adalah socket runtime, berbeda dari socket render dan pipeline pada waktu kompilasi.

Wajib.

spec.abiVersion

Versi ABI host/guest yang ditargetkan oleh plugin. v1beta1 adalah nilai yang diterima; revisi ABI baru menambahkan satu nilai. Wajib.

Mendeklarasikan kapabilitas: satu blok per jenis soket

Sebuah kapabilitas adalah apa yang diminta oleh konsumen dari sebuah plugin — kapabilitas render yang diminta oleh sebuah Recipe, atau format sumber yang perlu dibaca oleh sebuah build. Kapabilitas sebuah plugin direkam di dalam blok milik jenis soketnya, sehingga blok tempat daftar itu berada itulah yang menentukan arti entri-entrinya:

metadata.pluginTypeTempat kapabilitasnya dideklarasikanApa yang dinamai oleh sebuah entri
providerspec.provider.capabilitiesKapabilitas render yang dilayani plugin ini, seperti helm atau compose.
pipeline-stepspec.pipelineStep.capabilitiesSebuah provider yang keluaran hasil rendernya kompatibel dengan langkah plugin ini.
parserspec.parser.capabilitiesFormat sumber yang dibaca plugin ini, ditulis parse:<format>.
importerspec.importer.capabilitiesFormat sumber asing yang menjadi dasar plugin ini menyusun draf entitas, ditulis import:<format>.
linter, governance, cli—Tidak ada. Soket-soket ini tidak melayani kapabilitas apa pun, sehingga tidak memuat satu pun dari keempat blok tersebut.

Sebuah plugin mengimplementasikan tepat satu jenis soket, sehingga entitasnya membawa satu blok. Daftar tersebut adalah laporan milik plugin itu sendiri: aggrega plugin gen-catalog membaca describe() milik plugin dan menulis setiap kapabilitas yang dilaporkannya ke dalam blok. Penulis dapat mempersempit daftar sebelum publikasi, dengan menghilangkan kapabilitas yang dilaporkan plugin tetapi tidak seharusnya ditawarkan oleh entitas yang dipublikasikan; aggrega validate <entity> --plugin <file.wasm> dan aggrega push menerima daftar yang dipersempit dan mencetak pemberitahuan yang menyebut setiap kapabilitas yang dilaporkan plugin tetapi dihilangkan dari daftar. Keduanya tidak menerima daftar yang menyebut kapabilitas yang tidak dilaporkan plugin: keduanya menolaknya, dengan menyebut setiap kapabilitas tersebut beserta kapabilitas yang benar-benar dilaporkan plugin, sehingga daftar yang dipublikasikan tidak pernah menawarkan lebih dari yang disediakan plugin. Entitas pipeline-step yang plugin-nya melaporkan helm dan helm-chart, tetapi juga mencantumkan compose, ditolak seperti ini:

[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()

Konsumen melakukan resolusi persis terhadap apa yang tercantum.

spec.provider

Blok soket provider untuk plugin pluginType: provider: kapabilitas yang dilayaninya, cara plugin tersebut menerjemahkan jenis Workload aggrega.ai/v1beta1 yang dimiliki platform, anotasi bawaan platform mana yang dibacanya, serta kontrak perilaku render-nya. Blok ini ada pada setiap plugin yang merender sebagai provider dan tidak ada pada jenis plugin lainnya. Provider yang hanya merender konten bersumber atau konten artefak tanpa sintesis Workload tetap membawa blok ini — provider tersebut mendeklarasikan kapabilitas dan kontraknya di sana, dan cukup menghilangkan workloadSchema.

spec.provider.capabilities

Kapabilitas yang dilayani provider ini — nama kapabilitas seperti helm atau compose — yang bentuk keluarannya dirender olehnya. Sebuah provider bersifat generik terhadap artefak yang berbagi bentuk keluaran suatu kapabilitas, bukan terhadap semua kapabilitas, sehingga daftar ini menyebut kapabilitas yang dilaporkan oleh plugin itu sendiri: aggrega plugin gen-catalog merekamnya dari describe() milik plugin, dan penulis dapat mempersempitnya sebelum publikasi. Entri mempertahankan urutan saat direkam.

Target provider yang diminta oleh sebuah Recipe (spec.capability: helm) di-resolve ke plugin provider yang daftarnya memuat target tersebut. Jika lebih dari satu plugin provider mencantumkan target yang sama, workspace yang memilih: pilihan plugins.providers dalam konfigurasi workspace menyebutkan plugin mana yang digunakan, di-resolve saat aggrega pull dan dicatat dalam lockfile. Tanpa pilihan dan dengan tepat satu kandidat, kandidat itu yang digunakan; tanpa pilihan dan dengan lebih dari satu kandidat, build berhenti dan menyebutkan setiap kandidat. Ambiguitas diselesaikan per workspace pada titik penggunaan, bukan melalui aturan keunikan di seluruh katalog. Daftar yang kosong atau tidak ada tidak mendeklarasikan klaim kapabilitas apa pun, sehingga plugin tidak melayani target apa pun.

Nama kapabilitas di sini tidak mengandung titik dua. spec.capability milik sebuah Recipe dibaca sebagai kapabilitas hingga titik dua terakhirnya dan sebuah pin versi sesudahnya, sehingga nama yang mengandung titik dua tidak akan pernah dapat diminta; plugin yang describe()-nya melaporkan nama seperti itu ditolak saat dimuat, dan tidak ada entitas yang dihasilkan darinya untuk publikasi. Hal yang sama berlaku untuk kapabilitas provider yang dicantumkan oleh plugin pipeline-step. Titik dua dalam parse:<format> milik parser dan import:<format> milik importer merupakan bagian dari nama tersebut dan tetap dipertahankan.

spec.provider.workloadSchema

Deklarasi JSON Schema 2020-12 yang mendokumentasikan cara provider ini menerjemahkan jenis Workload aggrega.ai/v1beta1 menjadi manifest bawaan provider. Deklarasi ini dibuat berdasarkan konvensi pada provider yang melakukan sintesis: provider semacam itu mendeklarasikan workloadSchema sebagai kontrak terjemahan yang terdokumentasi, yang menjelaskan field Workload apa yang dikonsumsi provider, himpunan tertutup apa yang diterima oleh setiap field berbentuk enum, dan batasan rentang apa yang berlaku.

Isinya dikompilasi menjadi JSON Schema 2020-12 saat Plugin dimuat — sebuah pengaman struktural yang menolak skema yang salah bentuk saat pemuatan, bukan saat render. Apakah sebuah Recipe workload: didukung ditentukan oleh kapabilitas sintesis provider yang terikat, bukan oleh keberadaan field ini: Recipe mode tersintesis yang terikat ke provider yang tidak dapat melakukan sintesis akan berhenti secara eksplisit saat render. Katalog pustaka standar menjaga workloadSchema tetap selaras dengan kapabilitas provider. Field tersebut adalah kontrak yang terdokumentasi; tidak ada hal lain yang membacanya. Isi Workload itu sendiri divalidasi terhadap skema Workload tertanam yang dimiliki platform, bukan terhadap field per provider ini.

spec.provider.wellKnownAnnotations

Array berurutan yang menyebutkan kunci anotasi umum bawaan platform — yang berada di bawah namespace aggrega.ai/ yang dicadangkan — yang dibaca oleh provider ini, beserta perilaku yang diterapkan ketika masing-masing tidak ada. Setiap entri membawa key (anotasi yang dibaca provider, misalnya aggrega.ai/namespace), purpose (apa yang dikendalikan anotasi tersebut ketika ada), defaultBehavior opsional (apa yang dilakukan provider ketika anotasi tersebut tidak ada), dan scope opsional yang mencantumkan di mana provider membaca kunci tersebut — sourced, synthesized, atau artifactsStandalone, yaitu jenis input Recipe, atau boundary untuk kunci yang dibaca sekali per boundary. key dan purpose wajib diisi; entri mempertahankan urutan penulis.

Field ini merupakan klaim dukungan provider, dan compiler membacanya dengan dua cara. Entri yang scope-nya menyebut jenis input yang tidak diklaim oleh contract.inputKinds milik blok itu sendiri bertentangan dengan klaim tersebut, dan Plugin ditolak, dengan menyebut kunci dan scope-nya. Selain itu, ketika sebuah build merender melalui provider ini, anotasi aggrega.ai/ yang tidak dicakup oleh entri mana pun pada jenis input apa pun yang dideklarasikan render tersebut memicu peringatan yang menyebutkan kunci, provider, dan jenis-jenis input tersebut; nilainya tetap diteruskan tanpa diubah dan build tidak berhenti. Jika tidak ada, field ini tidak membuat klaim apa pun, dan tidak ada peringatan semacam itu yang dimunculkan untuk provider ini. Validasi skema hanya memeriksa bentuk setiap entri (kunci berada di bawah namespace aggrega.ai/, purpose ada); validasi ini berbeda dari pemeriksaan runtime yang mengatur pengikatan nilai ke namespace yang dicadangkan.

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.

Himpunan anotasi per provider dan konten workloadSchema yang disertakan oleh provider pustaka standar didokumentasikan di ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md, dan ../providers/compose.md.

spec.provider.readsNoWellKnownAnnotations

Mendeklarasikan bahwa provider ini tidak membaca satu pun kunci anotasi well-known native platform. Ini adalah klaim dukungan yang tidak mencakup kunci apa pun, dan menyatakan sesuatu yang tidak dinyatakan dengan menghilangkan field ini sekaligus wellKnownAnnotations: klaim yang tidak ada adalah diam, sedangkan klaim ini adalah pernyataan provider itu sendiri bahwa ia tidak membaca apa pun di bawah namespace aggrega.ai/ yang dicadangkan. Build yang merender melalui provider semacam itu memperingatkan setiap anotasi aggrega.ai/ yang mencapai render, dengan menyebutkan kunci, provider, dan jenis input yang dideklarasikan render tersebut; nilainya tetap diteruskan tanpa diubah dan build tidak berhenti.

Hanya true yang boleh ditulis, sehingga menghilangkan field ini tetap menjadi satu-satunya cara untuk tidak menyatakan apa pun. Field ini tidak dapat ditulis bersama wellKnownAnnotations: provider yang membaca sebagian kunci mencantumkannya di sana sebagai gantinya. Kedua penolakan berada di tingkat skema, sehingga Plugin ditolak saat dibaca.

spec:
provider:
capabilities:
- terraform
readsNoWellKnownAnnotations: true

Provider terraform dari pustaka standar mendeklarasikannya; ../providers/terraform.md menjelaskan apa artinya bagi Release yang dirender melaluinya.

spec.provider.contract

Kontrak perilaku render waktu kompilasi yang dideklarasikan sendiri oleh plugin perender provider: jenis input yang direndernya, cara plugin merangkai output per node dari sebuah grup dispatch, pasangan pembatas templat yang diterapkannya pada berkas artefak yang diimpor, apakah satu instans yang dimuat boleh melayani setiap persilangan, apakah plugin menghormati entri omit, dan apakah plugin menerima berkas yang disumbangkan sebuah Recipe ke output bersama boundary-nya. Blok ini berada di samping capabilities dalam blok yang sama tetapi menjawab pertanyaan yang berbeda: daftar kapabilitas menyatakan kapabilitas mana yang dilayani plugin ini, sedangkan kontrak menyatakan bagaimana plugin merendernya. aggrega plugin gen-catalog mencatatnya dari laporan diri describe() milik plugin itu sendiri, dan host memeriksanya silang terhadap laporan diri tersebut saat publikasi dan saat pemuatan; ketidaksesuaian menghentikan proses. Jika tidak ada, tidak ada kontrak perilaku render yang dideklarasikan, dan pemeriksaan silang hanya membandingkan klaim per ekspor. Semua field bersifat opsional.

FieldEfek
inputKindsJenis input Recipe mana dari ketiganya yang dirender plugin, masing-masing berupa klaim boolean yang independen: sourced (sekumpulan berkas bersumber — sebuah chart, sebuah modul, sebuah berkas compose), synthesized (sebuah Workload yang disintesis), dan artifactsStandalone (node mandiri yang membawa dokumen artefak yang diimpor tanpa sumber atau workload). Host membatasi jenis input sebuah node berdasarkan himpunan ini.
boundaryAssemblyCara plugin menggabungkan output render per node dari sebuah grup dispatch: none menulis output setiap node langsung di jalur dispatch; merge melipat fragmen per node menjadi satu dokumen; nest menempatkan output setiap node di bawah posisinya sendiri dalam sebuah struktur payung. Jika tidak ada, tidak ada klaim perangkaian.
artifactDelimitersPasangan pembatas templat Go yang diterapkan plugin pada berkas artefak yang diimpor, sebagai left dan right. Jika tidak ada, berarti pasangan bawaan {{/}}; plugin yang sintaksis targetnya berbenturan dengan pasangan itu mendeklarasikan pasangan alternatif (misalnya [[/]]).
reusableInstanceApakah satu instans plugin yang dimuat boleh melayani setiap persilangan render, assemble, dan validate dalam sebuah build, alih-alih instans baru per persilangan. Dideklarasikan true hanya jika plugin tidak menyimpan state antarpersilangan, sehingga satu instans menghasilkan output yang identik byte demi byte, baik digunakan ulang maupun baru dimuat. Jika tidak ada (false), instans baru dimuat per persilangan, sehingga plugin yang secara konstruksi membawa state terisolasi. aggrega build --verify-determinism membuktikan bahwa output plugin yang dapat digunakan ulang stabil dengan merender setiap node dua kali dan berhenti pada perbedaan apa pun.
omitsApakah plugin menghormati entri omit — entri yang menamai unit hasil render yang harus dikeluarkan dari output sebuah node: plugin mengeluarkan setiap unit yang cocok dengan sebuah entri dari apa yang direndernya, dan melaporkan berapa banyak unit yang cocok dengan setiap entri. Nilai ini mencatat klaim yang dilaporkan describe() milik plugin, sehingga true hanya benar untuk plugin yang melaporkannya, dan nilai yang berbeda dari laporan tersebut menghentikan proses. Jika tidak ada (false), tidak ada dukungan semacam itu yang dideklarasikan.
boundaryArtifactsApakah target plugin menerima berkas yang disumbangkan sebuah Recipe ke output bersama dari boundary tempat plugin merender, di bawah spec.boundary.artifacts milik Recipe tersebut: compiler menulis setiap berkas tersebut satu kali, di samping apa yang dirangkai plugin untuk boundary itu, dan target membacanya sebagai bagian dari output tersebut. Nilai ini mencatat klaim yang dilaporkan describe() milik plugin, dan nilai yang berbeda dari laporan tersebut menghentikan proses. Jika tidak ada (false), tidak ada dukungan semacam itu yang dideklarasikan, dan Recipe yang mendeklarasikan blok tersebut untuk plugin ini ditolak sebelum apa pun dirender.
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

Blok pipeline-step untuk plugin pluginType: pipeline-step. Satu-satunya field-nya, capabilities, menyebutkan provider yang output render-nya dapat ditransformasi oleh langkah plugin tersebut — nama kapabilitas seperti helm atau compose. Sebuah langkah ditulis untuk bentuk output satu provider pada satu waktu, sehingga daftar ini menyebut provider yang dilaporkan oleh plugin itu sendiri; entri mempertahankan urutan saat direkam. Blok ini hanya ada pada plugin pipeline-step.

Blok ini adalah catatan klaim tersebut yang dapat dibaca katalog: aggrega plugin gen-catalog merekamnya dari laporan diri describe() milik plugin itu sendiri, dan penulis dapat mempersempitnya sebelum publikasi. Penegakannya membaca klaim yang sama dari plugin: ketika sebuah langkah menyentuh suatu cakupan, build dihentikan kecuali provider yang me-render dokumen cakupan tersebut termasuk di antara yang diklaim plugin. Daftar yang kosong atau tidak ada tidak menyatakan klaim kompatibilitas apa pun, sehingga tidak ada cakupan yang menerima langkah tersebut.

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

spec.parser

Blok parser untuk plugin pluginType: parser. Satu-satunya field-nya, capabilities, menyebutkan format sumber yang diubah oleh plugin menjadi pohon terstruktur kanonis, masing-masing ditulis parse:<format>. Prefiks tersebut merupakan bagian dari entri, sehingga plugin yang membaca beberapa format mencantumkan satu entri per format. aggrega plugin gen-catalog merekam daftar tersebut dari describe() milik plugin itu sendiri, penulis dapat mempersempitnya sebelum publikasi, dan entri mempertahankan urutan saat direkam. Blok ini hanya ada pada plugin parser.

Format yang diminta di-resolve ke parser yang daftarnya memuat entri yang cocok. Format yang tidak diiklankan oleh parser mana pun menghentikan build, dan format yang diiklankan oleh lebih dari satu plugin parser dihentikan sebagai ambigu, dengan menyebutkan kandidatnya — tidak ada fallback, karena parser tidak memiliki default tanpa konfigurasi yang dapat dijadikan fallback. Daftar yang kosong atau tidak ada tidak menyatakan klaim format apa pun, sehingga plugin tidak mem-parse apa pun.

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

spec.importer

Blok importer untuk plugin pluginType: importer. Field capabilities-nya menyebutkan format sumber asing yang diubah oleh plugin menjadi draf berkas penulisan Aggrega, masing-masing ditulis import:<format>. Prefiks tersebut merupakan bagian dari entri, sehingga plugin yang menangani beberapa format mencantumkan satu entri per format. aggrega plugin gen-catalog merekam daftar tersebut dari describe() milik plugin itu sendiri, penulis dapat mempersempitnya sebelum publikasi, dan entri mempertahankan urutan saat direkam. Blok ini hanya ada pada plugin importer.

Format impor yang diminta diselesaikan ke importer yang daftarnya memuat entri yang cocok. Format yang tidak diiklankan oleh importer mana pun menghentikan impor, dan format yang diiklankan oleh lebih dari satu plugin importer berhenti sebagai ambigu dengan menyebutkan kandidatnya, kecuali jika entri plugins.importer dalam konfigurasi workspace melampirkan salah satunya, yang kemudian menjadi importer yang dijalankan. Daftar yang kosong atau tidak ada tidak menyatakan klaim format apa pun, sehingga plugin tidak mengimpor apa pun.

Field detect-nya mencatat tanda pengenal yang digunakan untuk mengenali sumber dengan format-format tersebut ketika impor tidak menyebutkan format. Field ini dimiliki oleh mesin, seperti catatan fungsi host dan perintah: field ini diturunkan dari apa yang dilaporkan describe() milik plugin ketika entitas dihasilkan dari plugin, dalam urutan plugin mendeklarasikan tanda pengenal tersebut, dan penulis tidak menulisnya. Setiap tanda pengenal menyebutkan:

  • syntax — format sintaksis yang digunakan untuk mengurai sumber, yaitu format yang diiklankan plugin parser sebagai parse:<syntax>, seperti json atau yaml.
  • files — pola nama berkas opsional, dicocokkan dengan bagian akhir nama sumber: pola satu segmen dicocokkan dengan nama berkas itu sendiri, pola beberapa segmen yang dipisahkan garis miring dicocokkan dengan sejumlah segmen akhir yang sama dari path-nya, sehingga .vscode/mcp.json cocok dengan berkas bernama mcp.json di direktori bernama .vscode. *, ? dan [...] mencocokkan di dalam satu segmen. Jika tidak ada, tanda pengenal berlaku untuk sumber berupa satu berkas, apa pun namanya, dan tidak berlaku untuk berkas mana pun dari sebuah direktori. Pola-pola dari tanda pengenal importer juga yang menentukan berkas mana dari sebuah direktori yang diserahkan aggrega import kepadanya.
  • match — predikat yang harus dipenuhi oleh pohon hasil penguraian, semuanya. Masing-masing memiliki path, yaitu kunci yang digabungkan dengan titik dari puncak pohon, dengan segmen bilangan bulat memilih posisi array; sebuah is, salah satu dari present, absent, object, array, string, number dan boolean; dan secara opsional equals, string yang harus menjadi nilainya, atau prefix, string yang harus mengawali nilainya — paling banyak salah satu dari keduanya.

Ketika impor tidak menyebutkan format, tanda pengenal dari setiap importer yang ada dalam katalog workspace — termasuk setiap versinya — dan dari importer inti compiler dicocokkan dengan sumber. Sumber diurai satu kali untuk setiap sintaksis yang digunakan oleh tanda pengenal yang berlaku untuk namanya, melalui parser yang disediakan katalog workspace untuk sintaksis tersebut — atau, untuk sintaksis yang tidak memiliki parser dalam katalog, parser yang dibawa oleh compiler itu sendiri — dan sumber yang tidak dapat diurai dalam suatu sintaksis tidak cocok dengan tanda pengenal mana pun yang menyebutkan sintaksis tersebut. Direktori dicocokkan melalui berkas-berkasnya: setiap tanda pengenal dicoba terhadap berkas-berkas direktori yang dipilih oleh polanya, dalam urutan nama, dan tanda pengenal yang tidak mendeklarasikan pola tidak berlaku untuk berkas mana pun. Sumber yang cocok dengan suatu tanda pengenal dikenali sebagai setiap format yang diiklankan importernya. Tepat satu format yang dikenali adalah format yang digunakan untuk membaca sumber. Sumber yang tidak cocok dengan tanda pengenal mana pun ditolak, dengan meminta format dan menyebutkan format yang diiklankan para importer — atau, untuk direktori, dengan meminta salah satu berkasnya secara tersendiri atau format yang importer-nya mendeklarasikan pola berkas, dengan hanya menyebutkan format-format tersebut; sumber yang dikenali sebagai lebih dari satu format ditolak dengan menyebutkan format-format tersebut, dengan kondisi More than one importer recognises the source (Lebih dari satu importer mengenali sumber). Jadi, importer yang mengiklankan lebih dari satu format membuat setiap sumber yang cocok dengan tanda pengenalnya ditolak sebagai ambigu, dan importer yang sumbernya ingin dikenali menyediakan satu format.

Jika entitas mencatat detect, nilainya harus sama dengan apa yang dilaporkan describe() milik plugin, tanda pengenal demi tanda pengenal dan sesuai urutan: pemuatan importer menolak plugin yang laporannya berbeda, dengan menyebutkan importer.detect, demikian pula saat memublikasikannya. Entitas yang tidak mencatat detect tidak membuat klaim dan tidak dibandingkan, sehingga entitas tersebut memuat tanda pengenal apa pun yang dilaporkan describe() milik plugin-nya, dan format importernya kemudian hanya dapat dijangkau dengan menyebutkannya.

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

Penunjuk deskriptif opsional ke tanda tangan yang dilampirkan pada plugin. Blok ini hanya berfungsi sebagai dokumentasi — blok ini mencatat lokasi tanda tangan dan cara tanda tangan itu dibuat bagi pembaca katalog; blok ini sendiri tidak menerima plugin. Pemeriksaan yang menegakkannya adalah kebijakan kepercayaan per registri yang diterapkan saat pull: tanda tangan diambil sebagai OCI referrer, diverifikasi terhadap identitas tepercaya atau kunci yang disematkan milik registri, lalu dicatat sebagai fakta terverifikasi dalam lockfile. Registri yang mewajibkan tanda tangan menghentikan pull ketika tanda tangan yang diwajibkan tidak ada, tidak tepercaya, atau tidak valid.

  • type — skema tanda tangan. sigstore-cosign adalah skema yang didukung. Wajib ada ketika blok ini ada.
  • signatureRef — referensi OCI referrer dari bundel tanda tangan yang dilampirkan, untuk dokumentasi dan penemuan. Tidak ada ketika tanda tangan ditemukan melalui enumerasi referrer saat pull, alih-alih disematkan di sini.
  • publicKeyRef — penunjuk ke kunci publik yang digunakan untuk membuat tanda tangan, untuk tanda tangan berkunci. Jika tidak ada, tanda tangan tersebut adalah tanda tangan tanpa kunci (identitas OIDC), yang diverifikasi terhadap identitas tepercaya milik registri.

spec.runtime

Batasan eksekusi opsional yang diterapkan host saat memuat dan menjalankan plugin. Akses jaringan keluar bukan field yang ditulis oleh penulis: plugin tidak pernah menjangkau jaringan pada waktu build — batas ahead-of-time — sehingga tidak ada field daftar host yang diizinkan di sini. Konten jarak jauh yang dibutuhkan plugin tiba melalui saluran input eksternal yang dimediasi host dan disematkan dengan digest, yang dicatat dalam lockfile Release, tidak pernah melalui akses jaringan ambien; panduan pengembang mendokumentasikan pembungkus pengambilan dan disiplin penyematan.

FieldEfek
maxMemoryPagesMembatasi memori linear plugin dalam halaman Wasm (64 KiB per halaman). Nilai nol atau tidak ada menerapkan batas bawaan platform, sehingga pemuatan tidak pernah tanpa batas; lampiran yang membutuhkan lebih banyak menaikkan nilai ini.
timeoutMsMembatasi berapa lama kode milik plugin itu sendiri dapat berjalan selama satu panggilan, dalam milidetik, tidak termasuk waktu yang dihabiskan di dalam fungsi host yang dipanggilnya. Di Linux ukurannya adalah waktu prosesor, sehingga waktu menunggu prosesor pada mesin yang sibuk tidak dihitung; di sistem lain ukurannya adalah waktu yang berlalu. Panggilan pertama ke plugin yang baru dimuat juga menghitung waktu start-up plugin itu sendiri. Nilai nol atau tidak ada menerapkan batas bawaan platform, sehingga panggilan tidak pernah tidak dapat dibatalkan; lampiran yang berjalan lebih lama menaikkan nilai ini.
hostFunctionsNama fungsi host yang diimpor plugin. Diturunkan oleh mesin dan hanya-baca — jangan menuliskannya: aggrega plugin sync membaca fungsi host dari bagian impor .wasm dan merekam field ini, publish menolak catatan yang berbeda dari biner, dan nilainya mencerminkan biner yang dipublikasikan, divalidasi terhadap daftar izin yang dikurasi. Host mendaftarkan tepat himpunan ini, memberi setiap plugin permukaan host dengan hak akses minimum yang dibutuhkan binernya; pull menurunkan ulang dan memverifikasi cap tersebut terhadap biner. Untuk melihat pratinjau nilainya sebelum mempublikasikan, jalankan aggrega inspect --plugin <file.wasm>.
configKVKonfigurasi khusus Plugin yang diserahkan runtime kepada plugin saat mulai, berupa pasangan kunci/nilai string-ke-string. Entri mempertahankan urutan penulis sehingga rekaman yang dihasilkan identik per byte di setiap eksekusi. Jika tidak ada, konfigurasi kosong bawaan runtime tetap berlaku.

spec.exports

Ekspor yang ditawarkan plugin, masing-masing dengan kapabilitas yang dideklarasikannya, sebagai daftar berurutan yang mempertahankan urutan penulis. Sebuah ekspor adalah satu titik masuk bernama yang menjadi tujuan dispatch host (misalnya render_node, lint_naming, step); blok kapabilitas per ekspor menyatakan apa yang dilakukan ekspor tersebut, sebagaimana dicatat oleh aggrega plugin gen-catalog dari laporan diri describe() milik plugin, dan host memeriksanya silang terhadap laporan diri tersebut saat publish dan saat dimuat. Jika tidak ada, tidak ada permukaan ekspor tertulis yang dideklarasikan.

FieldEfek
nameNama ABI ekspor — nama yang menjadi tujuan dispatch host. Wajib untuk setiap entri.
operatesOperasi pipeline yang dilakukan ekspor: patch (mengubah dokumen hasil render yang sudah ada) atau emit (menambahkan dokumen baru). Host memeriksa silang nilai ini terhadap laporan diri plugin; nilai ini adalah klaim kapabilitas yang divalidasi, bukan sakelar dispatch — operasi yang dilakukan sebuah langkah dibawa oleh hasil yang dikembalikan guest. Jika tidak ada, tidak ada klaim operasi yang dibawa.
scopeAkar dokumen tempat ekspor beroperasi: own (dokumen hasil render milik node itu sendiri) atau host (dokumen dari komponen tempat FeatureRecipe bercakupan komponen dilampirkan). Host membaca cakupan yang dideklarasikan sebelum langkah dijalankan untuk menegakkan kompatibilitas provider terhadap provider yang merender cakupan tersebut. Jika tidak ada, nilai bawaannya adalah own.
selectorDeskripsi bebas yang dapat dibaca manusia tentang apa yang menjadi sasaran ekspor (misalnya workloads carrying a pod template). Dokumentasi untuk pembaca katalog dan permukaan inspect; compiler tidak menafsirkannya.

spec.commands

Verba tingkat atas aggrega <command> yang disumbangkan oleh plugin cli, sebagai daftar berurutan yang mempertahankan urutan yang dideklarasikan oleh laporan diri describe() plugin tersebut. Dimiliki mesin dan hanya-baca — jangan menulisnya. aggrega plugin sync membaca permukaan perintah dari laporan diri describe() plugin dan mencatatnya di sini, sehingga perintah yang dipasang oleh plugin CLI dapat dibaca dari entitas tanpa memuat .wasm. Plugin non-cli tidak menyumbangkan perintah dan mencatat daftar kosong. Host memasang tepat himpunan ini; himpunan tercatat yang menyimpang dari laporan diri describe() plugin akan dihentikan saat pemuatan, dan publish menolak himpunan yang tidak sinkron dengan biner serta mengarahkan penulis untuk mencatatnya ulang. Untuk menyinkronkan ulang catatan setelah mengubah plugin, jalankan aggrega plugin sync.

Setiap entri perintah memuat:

FieldEfek
nameVerba perintah yang didaftarkan host — token aggrega <name> yang dipanggil operator, dan diskriminator yang diberikan host kepada plugin saat pemanggilan sehingga satu plugin yang mendukung beberapa perintah dapat merutekan berdasarkan perintah mana yang dipanggil. Wajib untuk setiap entri.
descriptionTeks bantuan singkat satu baris untuk perintah, yang ditampilkan dalam daftar perintah dan keluaran bantuan. Hanya dokumentasi; host tidak bertindak berdasarkannya.
flagsFlag perintah, dalam urutan yang dideklarasikan. Setiap entri mendaftarkan satu flag pada perintah sehingga aggrega help <command> menampilkannya seperti flag perintah inti. Perintah tanpa flag membiarkannya kosong.

Setiap entri flags mendeklarasikan satu flag:

FieldEfek
nameNama panjang flag — token --name yang diberikan operator pada baris perintah. Wajib untuk setiap entri.
shorthandAlias pendek opsional flag — bentuk -x yang dapat diberikan operator sebagai pengganti nama panjang — berupa satu huruf atau digit ASCII. Jika tidak ada, flag tidak memiliki alias pendek.
descriptionTeks bantuan satu baris untuk flag, yang ditampilkan dalam keluaran bantuan perintah. Dokumentasi opsional; host tidak memvalidasi maupun bertindak berdasarkannya.
typeTipe nilai flag — string, bool atau int — dan jenis flag yang ditampilkan oleh bantuan. Jika tidak ada, flag ditampilkan sebagai flag string.
defaultNilai default flag ketika operator tidak memberikannya, dinyatakan sebagai string. Untuk flag bool atau int, nilainya adalah nilai dari tipe tersebut. Jika tidak ada, flag tidak mendeklarasikan nilai default.

Plugin CLI mendeklarasikan perintah dan flag-nya dalam describe(); host mendaftarkan tepat permukaan tersebut dan menampilkan flag setiap perintah dalam aggrega help <command> dengan cara yang sama seperti menampilkan flag perintah bawaan.

Host memeriksa setiap flag yang dideklarasikan plugin ketika menambahkan perintah plugin tersebut, dan plugin yang deklarasinya gagal akan dilewati alih-alih ditambahkan: tidak ada satu pun perintahnya yang didaftarkan, sebuah peringatan menyebutkan plugin, perintah, flag, dan apa yang salah dengannya, dan setiap perintah lain — bawaan atau dari plugin lain — tetap berfungsi. Deklarasi gagal ketika:

  • flag tidak memiliki nama, atau suatu perintah mendeklarasikan nama yang sama dua kali;
  • shorthand berupa apa pun selain satu huruf atau digit ASCII, atau suatu perintah mendeklarasikan shorthand yang sama untuk dua flag;
  • nama atau shorthand menggunakan ulang flag yang sudah dimiliki setiap perintah aggrega — --help, -h-nya, dan flag global seperti --offline dan --config;
  • tipe berupa apa pun selain string, bool atau int;
  • nilai default tidak dapat diurai sebagai tipe flag — maybe untuk bool, three untuk int.

Bentuk satu karakter dari shorthand dan tiga nilai type juga merupakan bagian dari skema entitas ini, sehingga entitas Plugin yang mencatat nilai lain akan ditolak saat katalog dimuat. Bahwa nama atau shorthand muncul sekali per perintah, bahwa tidak ada yang menggunakan ulang flag yang dimiliki setiap perintah, dan bahwa nilai default dapat diurai sebagai tipenya hanya diperiksa oleh host. Pemeriksaan ini mencakup apakah host dapat mendeklarasikan flag untuk bantuan sebagaimana tertulis; pemeriksaan ini tidak melihat apakah plugin membaca flag yang dideklarasikannya, karena plugin mengurai argumennya sendiri.

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

Memeriksa Plugin

aggrega inspect <path-to-Plugin.yaml> menampilkan sebuah berkas Plugin: identitas dan jenis socket-nya, kapabilitas yang dideklarasikan oleh bloknya, tabel kapabilitas per ekspor dalam urutan penulis, batasan runtime, serta — pada --detail — penunjuk tanda tangan dan kunci konfigurasi runtime. Sebuah Plugin dapat dirujuk melalui jalur berkas, atau melalui koordinat <pluginType>/<name> miliknya terhadap katalog. Lihat ../cli/aggrega-inspect.md.

Rujukan silang

  • Panduan pengembang plugin Wasm — alur kerja penulis dari awal hingga akhir: describe(), klaim kapabilitas, batas runtime, siklus hidup, penandatanganan, pembuatan versi.
  • Kontrak plugin Wasm — titik soket tempat plugin terpasang beserta bentuk input/output-nya.
  • entities/featurerecipe.md — permukaan pipeline: FeatureRecipe yang merujuk plugin melalui URI entitas.
  • cli/aggrega-lint.md — linter publikasi, rubrik kenaikan versi, dan penegakan imutabilitas yang mengatur publikasi Plugin.