Schemat Aggrega Core (Plugin)
Dokumentacja wygenerowana automatycznie. Nie należy jej edytować ręcznie — należy ją wygenerować ponownie z opublikowanego JSON Schema.
Identyfikator schematu: https://aggrega.ai/schemas/plugin-v1beta1.schema.json
Wtyczka Wasm: moduł WebAssembly opublikowany w rejestrze OCI i identyfikowany przez swoje metadata.pluginType — gniazdo, które implementuje — oraz samo metadata.name, deklarujący docelową wersję ABI, opcjonalny wskaźnik podpisu i opcjonalny blok runtime. Encja i jej plik .wasm są publikowane jako jeden manifest OCI oznaczony tagiem metadata.version — YAML encji jako blob konfiguracji manifestu, .wasm jako warstwa inline, podpisane jednokrotnie. Tożsamość to współrzędna metadata.pluginType/metadata.name wraz z metadata.version encji; lokalizacja pliku .wasm jest wyprowadzana z tej współrzędnej i skonfigurowanego rejestru, a rozwiązany skrót treści znajduje się w pliku blokady, nie w encji. Plik blokady rejestruje skrót, a polityka zaufania danego rejestru weryfikuje podpis artefaktu przy pobieraniu. Kompilator nie interpretuje zachowania wtyczki — przekazuje odwołanie; środowisko uruchomieniowe WebAssembly wykonuje bajty.
Wskazówki dotyczące tworzenia encji Plugin opisuje przewodnik po tworzeniu encji Plugin; ta strona dokumentuje schemat strukturalny, który ten przewodnik opisuje.
Typ najwyższego poziomu: object
Właściwości
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | tak | Stała: "aggrega.ai/v1beta1" |
kind | const “Plugin” | tak | Stała: "Plugin" |
metadata | object | tak | |
spec | object | tak | Wersja ABI, do której kierowany jest plugin, opcjonalny wskaźnik podpisu oraz opcjonalny blok środowiska uruchomieniowego. Lokalizacja pliku .wasm pluginu jest wyprowadzana z tożsamości pluginu — jego metadata.pluginType (gniazda) i samej nazwy metadata.name — oraz ze skonfigurowanego rejestru; nie jest przechowywana w specyfikacji. |
Dodatkowe właściwości są niedozwolone.
plugin.metadata
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Co najmniej 1 znak. |
version | string | tak | Wersja encji Plugin zgodna ze ścisłym Semantic Versioning (np. 1.0.0). Wzorzec: ^(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) | tak | Typ gniazda implementowanego przez ten plugin. Plugin implementuje dokładnie jeden typ gniazda, wybrany z taksonomii typów pluginów rozpoznawanej przez środowisko uruchomieniowe: provider (renderuje węzły IR do artefaktów natywnych dla dostawcy), linter (analizuje utworzoną treść i zgłasza diagnostyki), pipeline-step (krok w pipeline: encji FeatureRecipe lub Recipe, który nakłada łatki na zbiór wyrenderowanych dokumentów), governance (pełni role nadzoru w potoku budowania — przekształca etykiety węzłów podczas konstruowania topologii albo wydaje werdykt akceptacji lub odrzucenia dla grafu IR podczas analizy statycznej lub dla wyrenderowanych artefaktów podczas renderowania; to rola, przy której jest dołączony, a nie jego rodzaj, określa, co może emitować), cli (dodaje uruchomieniowe podpolecenie aggrega <cmd> wywoływane przez operatora w wierszu poleceń — gniazdo uruchomieniowe, odrębne od gniazd renderowania i potoku działających w czasie kompilacji), parser (przekształca obcy tekst źródłowy w kanoniczne drzewo strukturalne, dzięki czemu konsument odczytuje drzewo bez własnego parsera języka; obsługiwane formaty ogłasza jako możliwości parse:<format>), importer (przekształca obce źródło infrastruktury lub definicji agenta w robocze pliki autorskie Aggrega; obsługiwane formaty ogłasza jako możliwości import:<format>). Dozwolone wartości: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer" |
description | string | nie | Czym jest ta encja i do czego służy, napisane dla osoby decydującej, czy jej użyć. Należy zacząć od zdania nazywającego rzecz, a następnie dodać to, czego czytelnik potrzebuje, aby ją wybrać i poprawnie jej użyć — czego oczekuje od kompilacji, która ją uruchamia, i co w jej zachowaniu może zaskoczyć. Zwykle wystarcza krótki akapit. |
maintainers | object[] | nie | Lista opiekunów, do których należy ta encja. |
license | string | nie | Identyfikator SPDX licencji oprogramowania opisywanego przez tę encję, np. MIT lub AGPL-3.0. Określa warunki tego oprogramowania, a nie warunki tego pliku. |
repository | string | nie | URL repozytorium Git, w którym znajdują się pliki źródłowe. |
home | string | nie | URL strony domowej, wiki lub dokumentacji tej encji. |
keywords | string[] | nie | Lista opisowych słów kluczowych ułatwiających wyszukiwanie w interfejsie użytkownika. |
Dodatkowe właściwości są niedozwolone.
plugin.metadata.maintainers[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | |
email | string | nie | |
url | string | nie |
Dodatkowe właściwości są niedozwolone.
plugin.spec
Wersja ABI, do której kierowany jest plugin, opcjonalny wskaźnik podpisu oraz opcjonalny blok środowiska uruchomieniowego. Lokalizacja pliku .wasm pluginu jest wyprowadzana z tożsamości pluginu — jego metadata.pluginType (gniazda) i samej nazwy metadata.name — oraz ze skonfigurowanego rejestru; nie jest przechowywana w specyfikacji.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
abiVersion | string (enum) | tak | Wersja ABI host/gość, do której kierowany jest plugin. v1beta1 jest jedyną akceptowaną wartością; encja Plugin deklarująca wersję ABI, której ten kompilator już nie obsługuje, jest odrzucana z podaniem wersji, względem której należy przebudować plugin. Dozwolone wartości: "v1beta1" |
signature | object | nie | Opcjonalny opisowy wskaźnik do dołączonego podpisu pluginu. Ten blok pełni wyłącznie funkcję dokumentacyjną — zapisuje dla czytelników katalogu, gdzie znajduje się podpis i jak został wytworzony; sam nie blokuje ani nie dopuszcza pluginu. Wiążącą kontrolą jest polityka zaufania danego rejestru stosowana przy pobieraniu: podpis jest pobierany jako OCI referrer, weryfikowany względem zaufanych tożsamości rejestru lub przypiętego klucza i zapisywany w pliku blokady jako zweryfikowany fakt. Rejestr wymagający podpisów przerywa pobieranie, gdy wymaganego podpisu brakuje, nie jest on zaufany lub jest nieprawidłowy. |
runtime | object | nie | Opcjonalne ograniczenia wykonania, które host stosuje podczas ładowania i uruchamiania pluginu. Wychodzący dostęp do sieci nie jest polem autorskim: plugin nigdy nie łączy się z siecią w czasie budowania (granica ahead-of-time), więc nie ma tu pola listy dozwolonych hostów do wypełnienia. |
exports | object[] | nie | Eksporty oferowane przez ten plugin, każdy z zadeklarowaną możliwością. Eksport to jeden nazwany punkt wejścia, do którego host kieruje wywołania (na przykład render_node, lint_naming, step); blok możliwości danego eksportu jest autorską deklaracją tego, co ten eksport robi, którą host porównuje z samoopisem pluginu przy publikacji i przy ładowaniu. Wpisy zachowują kolejność autora. Brak pola oznacza brak autorskiej powierzchni eksportów. |
commands | object[] | nie | Pole zarządzane maszynowo, nie należy go wypełniać: zapisywane przez aggrega plugin sync (lub aggrega plugin gen-catalog) na podstawie samoopisu pluginu. Polecenia najwyższego poziomu aggrega <command> dodawane przez plugin CLI są odczytywane z samoopisu pluginu i zapisywane tu w kolejności zadeklarowanej w samoopisie, dzięki czemu powierzchnię poleceń instalowaną przez plugin CLI można odczytać z encji bez ładowania pluginu. Plugin inny niż CLI nie dodaje poleceń i zapisuje pustą listę. Host instaluje dokładnie ten zbiór; zapisany zbiór niezgodny z samoopisem pluginu powoduje przerwanie przy ładowaniu, a publikacja odrzuca zbiór niezsynchronizowany z plikiem binarnym i kieruje autora do ponownego jego zapisania. |
provider | object | nie | Blok gniazda dostawcy dla pluginu pluginType: provider: obsługiwane przez niego możliwości, sposób tłumaczenia rodzaju aggrega.ai/v1beta1 Workload, odczytywane adnotacje natywne dla platformy oraz kontrakt zachowania renderowania. Występuje tylko w pluginach renderujących dostawcy; nie występuje w żadnym innym typie pluginu. |
pipelineStep | object | nie | Blok kroku potoku dla pluginu pluginType: pipeline-step: możliwości dostawcy, z którymi zgodny jest jego krok. Występuje tylko w pluginach kroku potoku; nie występuje w żadnym innym typie pluginu. |
parser | object | nie | Blok parsera dla pluginu pluginType: parser: formaty źródłowe, które przekształca w kanoniczne drzewo strukturalne. Występuje tylko w pluginach parsera; nie występuje w żadnym innym typie pluginu. |
importer | object | nie | Blok importera dla pluginu pluginType: importer: obce formaty źródłowe, które przekształca w robocze pliki autorskie Aggrega, oraz sygnatury, po których rozpoznawane jest źródło w tych formatach. Występuje tylko w pluginach importera; nie występuje w żadnym innym typie pluginu. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.signature
Opcjonalny opisowy wskaźnik do dołączonego podpisu pluginu. Ten blok pełni wyłącznie funkcję dokumentacyjną — zapisuje dla czytelników katalogu, gdzie znajduje się podpis i jak został wytworzony; sam nie blokuje ani nie dopuszcza pluginu. Wiążącą kontrolą jest polityka zaufania danego rejestru stosowana przy pobieraniu: podpis jest pobierany jako OCI referrer, weryfikowany względem zaufanych tożsamości rejestru lub przypiętego klucza i zapisywany w pliku blokady jako zweryfikowany fakt. Rejestr wymagający podpisów przerywa pobieranie, gdy wymaganego podpisu brakuje, nie jest on zaufany lub jest nieprawidłowy.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
type | const “sigstore-cosign” | tak | Schemat podpisu. sigstore-cosign jest obsługiwanym schematem. Stała: "sigstore-cosign" |
signatureRef | string | nie | Referencja OCI referrer dołączonego pakietu podpisu, służąca dokumentacji i wykrywaniu. Nie występuje, gdy podpis jest wykrywany przez wyliczenie referrerów przy pobieraniu, a nie przypięty tutaj. |
publicKeyRef | string | nie | Wskaźnik do klucza publicznego, którym wytworzono podpis, w przypadku podpisu z kluczem. Brak pola oznacza podpis bezkluczowy (oparty na tożsamości OIDC), weryfikowany względem zaufanych tożsamości rejestru. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.runtime
Opcjonalne ograniczenia wykonania, które host stosuje podczas ładowania i uruchamiania pluginu. Wychodzący dostęp do sieci nie jest polem autorskim: plugin nigdy nie łączy się z siecią w czasie budowania (granica ahead-of-time), więc nie ma tu pola listy dozwolonych hostów do wypełnienia.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
maxMemoryPages | integer | nie | Ogranicza pamięć liniową pluginu w stronach Wasm (64 KiB na stronę). Zero lub brak pola stosuje domyślny limit platformy, więc ładowanie nigdy nie jest nieograniczone; dołączenie, które potrzebuje więcej, podnosi tę wartość. Minimum: 0. |
timeoutMs | integer | nie | Ogranicza, jak długo własny kod pluginu może działać podczas jednego wywołania, w milisekundach, bez liczenia czasu spędzonego wewnątrz wywoływanych przez niego funkcji hosta. W systemie Linux mierzony jest czas procesora, więc czas oczekiwania na procesor na obciążonej maszynie się nie liczy; w innych systemach mierzony jest czas rzeczywisty. Pierwsze wywołanie świeżo załadowanego pluginu liczy też własne uruchomienie pluginu. Zero lub brak pola stosuje domyślny limit platformy, więc wywołanie nigdy nie jest niemożliwe do anulowania; dołączenie, które działa dłużej, podnosi tę wartość. Minimum: 0. |
hostFunctions | string[] | nie | Pole zarządzane maszynowo, nie należy go wypełniać: funkcje hosta importowane przez plugin, odczytywane z sekcji importu pliku .wasm przez aggrega plugin sync (lub aggrega plugin gen-catalog) i zapisywane tutaj w postaci kanonicznej (posortowanej, bez duplikatów). Publikacja ponownie wyprowadza je z pliku binarnego i odrzuca encję, której zapis się różni; pobieranie ponownie je wyprowadza i weryfikuje. Host rejestruje dokładnie ten wyprowadzony zbiór i sprawdza każdy wpis względem starannie dobranej listy dozwolonych. |
configKV | mapa string | nie | Konfiguracja specyficzna dla encji Plugin, którą środowisko uruchomieniowe przekazuje pluginowi przy starcie, w postaci par klucz/wartość typu string-string. Wpisy zachowują kolejność autora, dzięki czemu emitowany rekord jest identyczny bajt po bajcie między uruchomieniami. Brak pola pozostawia w mocy domyślną, pustą konfigurację środowiska uruchomieniowego. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.exports[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Nazwa ABI eksportu — nazwa, do której host kieruje wywołania (na przykład render_node, lint_naming, step). Co najmniej 1 znak. |
operates | string (enum) | nie | Operacja potoku wykonywana przez ten eksport: patch (modyfikuje istniejący wyrenderowany dokument) lub emit (dodaje nowy dokument). Brak pola nie niesie żadnej deklaracji operacji. Dozwolone wartości: "patch", "emit" |
scope | string (enum) | nie | Korzeń dokumentów, na którym działa ten eksport: own (własne wyrenderowane dokumenty węzła) lub host (dokumenty komponentu, do którego dołączona jest encja FeatureRecipe o zakresie komponentu). Brak pola nie niesie żadnej deklaracji zakresu. Dozwolone wartości: "own", "host" |
selector | string | nie | Dowolny, czytelny dla człowieka opis tego, na czym działa eksport (na przykład workloads carrying a pod template). Dokumentacja dla czytelników katalogu; kompilator jej nie interpretuje. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.commands[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Czasownik polecenia rejestrowany przez hosta — token aggrega <name> wywoływany przez operatora oraz wyróżnik, który host przekazuje pluginowi przy wywołaniu, aby pojedynczy plugin obsługujący kilka poleceń mógł rozpoznać, które polecenie wywołano. Co najmniej 1 znak. |
description | string | nie | Jednowierszowy krótki tekst pomocy polecenia, wyświetlany na liście poleceń i w wyniku pomocy. Wyłącznie dokumentacja; host nie podejmuje na jego podstawie żadnych działań. |
flags | object[] | nie | Flagi polecenia w zadeklarowanej kolejności. Każdy wpis dodaje jedną flagę, którą host rejestruje w poleceniu, tak aby aggrega help --help, -h oraz flag globalnych; host sprawdza to przy dodawaniu poleceń pluginu, a plugin, którego deklaracje nie przejdą sprawdzenia, nie zostaje dodany i pojawia się ostrzeżenie. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.commands[].flags[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Długa nazwa flagi — token —name, który operator przekazuje w wierszu poleceń. Każda zadeklarowana flaga musi ją podawać. Co najmniej 1 znak. |
shorthand | string | nie | Opcjonalny krótki alias flagi — forma -x, którą operator może przekazać zamiast długiej nazwy — w postaci pojedynczej litery lub cyfry ASCII. Brak pola oznacza, że flaga nie ma krótkiego aliasu. Wzorzec: ^[A-Za-z0-9]$. |
description | string | nie | Jednowierszowy tekst pomocy flagi, wyświetlany w wyniku pomocy polecenia. Jest to opcjonalna dokumentacja; host ani jej nie sprawdza, ani nie podejmuje na jej podstawie działań. |
type | string (enum) | nie | Typ wartości flagi — string, bool lub int — oraz rodzaj flagi, jako który wyświetla ją pomoc. Brak pola oznacza wyświetlanie jej jako flagi tekstowej. Dozwolone wartości: "string", "bool", "int" |
default | string | nie | Wartość domyślna flagi, gdy operator jej nie przekaże, wyrażona jako ciąg znaków. Dla flagi bool lub int jest to wartość tego typu. Brak pola oznacza, że flaga nie deklaruje wartości domyślnej. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.provider
Blok gniazda dostawcy dla pluginu pluginType: provider: obsługiwane przez niego możliwości, sposób tłumaczenia rodzaju aggrega.ai/v1beta1 Workload, odczytywane adnotacje natywne dla platformy oraz kontrakt zachowania renderowania. Występuje tylko w pluginach renderujących dostawcy; nie występuje w żadnym innym typie pluginu.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
capabilities | string[] | nie | Zapisywane z samoopisu pliku .wasm pluginu przez aggrega plugin gen-catalog, więc źródłem tej listy jest plugin. Autor może ją zawęzić przed publikacją, usuwając wpis, którego ta encja nie powinna oferować, ale nie może dodać żadnego, którego samoopis nie wymienia: publikacja oraz aggrega validate z plikiem .wasm pluginu podanym przez --plugin odrzucają listę wymieniającą możliwość, której samoopis nie wymienia. Publikacja wysyła encję w postaci, w jakiej została napisana, nigdy nie przepisując tej listy, i odnotowuje każdą możliwość wymienioną w samoopisie, którą lista pomija. Możliwości obsługiwane przez ten provider — nazwy możliwości, takie jak helm lub compose — których kształt wyjścia renderuje. Provider jest uniwersalny w obrębie artefaktów o wspólnym kształcie wyjścia danej możliwości, a nie wszystkich możliwości, więc lista jest jawną, przetestowaną deklaracją zgodności, a nie aspiracją. Wpisy zachowują kolejność autora. Docelowy provider żądany przez encję Recipe jest rozwiązywany do pluginu providera, którego lista zawiera ten cel; cel wymieniony przez więcej niż jeden plugin providera zatrzymuje kompilację jako niejednoznaczny, chyba że wybór plugins.providers w konfiguracji przestrzeni roboczej wskazuje, którego pluginu użyć. Pusta lub nieobecna lista nie deklaruje żadnej możliwości, więc plugin nie obsługuje żadnego celu. |
workloadSchema | string | nie | JSON Schema 2020-12 dokumentujący, jak ten provider tłumaczy rodzaj Workload z aggrega.ai/v1beta1 na manifesty natywne dla providera. Gdy jest obecny, provider obsługuje Recipes deklarujące blok workload: (tryb syntetyzowany) — provider tłumaczy encję Workload na manifesty natywne dla providera, posiłkując się tym schematem jako dokumentacją/kontraktem. O tym, czy encja Recipe z workload: jest obsługiwana, decyduje zdolność syntezy powiązanego providera, a nie obecność tego pola: encja Recipe w trybie syntetyzowanym powiązana z providerem, który nie potrafi syntetyzować, wyraźnie zatrzymuje się w czasie renderowania. Katalog biblioteki standardowej deklaruje workloadSchema w providerach syntetyzujących jako udokumentowany kontrakt, utrzymywany w zgodzie z tą zdolnością. Pole jest udokumentowanym kontraktem: treść jest kompilowana do JSON Schema 2020-12 przy ładowaniu w celu sprawdzenia poprawności i nic innego jej nie odczytuje. |
wellKnownAnnotations | object[] | nie | Deklaracja wsparcia providera: natywne dla platformy, dobrze znane klucze adnotacji (przestrzeń nazw aggrega.ai/), które ten provider odczytuje, każdy z zakresem, w którym jest odczytywany, i zachowaniem stosowanym w razie jego braku. Klucz należy deklarować tylko tam, gdzie provider go odczytuje — publikowana macierz wsparcia jest renderowana z tych deklaracji, więc klucz wymieniony tutaj to klucz, po którym autor może oczekiwać zmiany renderowanego wyniku w zakresie, który wskazuje. Kompilator odczytuje deklarację na dwa sposoby: scope wskazujący rodzaj wejścia, którego nie deklaruje własne contract.inputKinds providera, przeczy sąsiedniej deklaracji w tej samej encji, a kompilacja zatrzymuje się, podając klucz i sprzeczność; ponadto kompilacja ostrzega o adnotacji aggrega.ai/ docierającej do renderowania przez tego providera, gdy żaden wpis nie obejmuje jej w żadnym rodzaju wejścia deklarowanym przez to renderowanie. Pole jest odrębne od reguły rządzącej wiązaniem wartości pod zarezerwowanym prefiksem aggrega.ai/. Brak pola nie deklaruje żadnego wsparcia i dla tego providera takie ostrzeżenie nie jest zgłaszane; provider, który nie odczytuje żadnego z tych kluczy, deklaruje readsNoWellKnownAnnotations zamiast tej listy. Wpisy tworzą uporządkowaną listę i zachowują kolejność autora. |
readsNoWellKnownAnnotations | stała true | nie | Deklaruje, że ten provider nie odczytuje żadnego z natywnych dla platformy kluczy adnotacji w przestrzeni nazw aggrega.ai/, to jest kluczy, które w przeciwnym razie wymieniałoby wellKnownAnnotations: jest to deklaracja wsparcia nieobejmująca żadnego klucza, czyli wyraźne stwierdzenie tam, gdzie pominięcie zarówno tego pola, jak i wellKnownAnnotations jest milczeniem. Kompilacja ostrzega wtedy o każdej adnotacji aggrega.ai/, która dociera do renderowania przez tego providera, wymieniając klucz, providera i rodzaje wejścia deklarowane przez to renderowanie; wartość nadal przechodzi nietknięta, a kompilacja nie zostaje przerwana. Można wpisać tylko true, więc pominięcie pola pozostaje jedynym sposobem, by nic nie stwierdzać. Nie można go wpisać razem z wellKnownAnnotations: provider, który odczytuje niektóre z kluczy, wymienia je zamiast tego tam. Stała: true |
contract | object | nie | Samodzielnie zadeklarowany przez providera kontrakt zachowania renderowania: rodzaje wejścia, które renderuje, sposób składania wyjścia poszczególnych węzłów grupy dyspozycji i katalogi, w których to wyjście się znajduje, para ograniczników szablonu stosowana do importowanych plików artefaktów, czy jedna załadowana instancja może obsłużyć każde przejście, czy łączy krawędzie między granicami, czy respektuje wpisy omit, czy przyjmuje pliki, które encja Recipe wnosi do współdzielonego wyjścia swojej granicy, oraz których plików jego ekosystem nigdy nie dostarcza obok źródła. Jest to zapis z czasu publikacji samoopisu pluginu providera, który host porównuje krzyżowo z tym samoopisem przy publikacji i przy ładowaniu. Brak pola nie deklaruje żadnego kontraktu zachowania renderowania, a porównanie krzyżowe obejmuje wyłącznie deklaracje poszczególnych eksportów. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.provider.wellKnownAnnotations[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
key | string | tak | Natywny dla platformy, dobrze znany klucz adnotacji odczytywany przez providera (np. aggrega.ai/namespace). Znajduje się w zarezerwowanej dla platformy przestrzeni nazw adnotacji aggrega.ai/ — dyrektywach platformy odczytywanych przez providera. Wzorzec: ^aggrega\.ai/.+. |
purpose | string | tak | Co kontroluje adnotacja — zachowanie renderowania, na które wpływa, gdy jest obecna. |
defaultBehavior | string | nie | Zachowanie stosowane przez providera, gdy ta adnotacja jest nieobecna. |
scope | string (enum)[] | nie | Gdzie ten provider odczytuje klucz. Pierwsze trzy wartości to rodzaje wejścia encji Recipe i wskazują ścieżkę renderowania, na której klucz jest odczytywany — sourced to dostarczony zestaw plików, synthesized to encja Workload materializowana przez providera, artifactsStandalone to węzeł, którego całe wyjście stanowią importowane dokumenty artefaktów. Każda z nich musi być rodzajem wejścia deklarowanym przez contract.inputKinds tego providera; wskazanie niezadeklarowanego zatrzymuje kompilację. boundary służy dla klucza rozwiązywanego raz na granicę, a nie na węzeł — nazwy złożonego artefaktu lub kontekstu rozmieszczenia, z którego kształtowane jest odwołanie między granicami — gdzie rodzaj wejścia nie jest sensownym wymiarem, więc nie jest porównywany z contract.inputKinds. Klucz odczytywany na więcej niż jednej ścieżce wymienia każdą z nich. Brak pola nie składa deklaracji dla ścieżek: nic nie jest sprawdzane, a klucz stwierdza jedynie, że provider gdzieś go odczytuje. Co najmniej 1 wpis. Żaden wpis nie może wystąpić dwa razy. Dozwolone wartości każdego wpisu: "sourced", "synthesized", "artifactsStandalone", "boundary". |
Dodatkowe właściwości są niedozwolone.
plugin.spec.provider.contract
Samodzielnie zadeklarowany przez providera kontrakt zachowania renderowania: rodzaje wejścia, które renderuje, sposób składania wyjścia poszczególnych węzłów grupy dyspozycji i katalogi, w których to wyjście się znajduje, para ograniczników szablonu stosowana do importowanych plików artefaktów, czy jedna załadowana instancja może obsłużyć każde przejście, czy łączy krawędzie między granicami, czy respektuje wpisy omit, czy przyjmuje pliki, które encja Recipe wnosi do współdzielonego wyjścia swojej granicy, oraz których plików jego ekosystem nigdy nie dostarcza obok źródła. Jest to zapis z czasu publikacji samoopisu pluginu providera, który host porównuje krzyżowo z tym samoopisem przy publikacji i przy ładowaniu. Brak pola nie deklaruje żadnego kontraktu zachowania renderowania, a porównanie krzyżowe obejmuje wyłącznie deklaracje poszczególnych eksportów.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
inputKinds | object | nie | Które z trzech rodzajów danych wejściowych encji Recipe renderuje ten plugin: zestaw plików źródłowych, syntetyzowane obciążenie oraz samodzielny węzeł zawierający wyłącznie artefakty. Każde pole jest niezależną deklaracją. |
boundaryAssembly | string (enum) | nie | Sposób, w jaki plugin łączy wyniki renderowania poszczególnych węzłów grupy dyspozycyjnej: none zapisuje wynik każdego węzła bezpośrednio pod ścieżką dyspozycji; merge scala fragmenty poszczególnych węzłów w jeden dokument; nest umieszcza wynik każdego węzła na jego własnej pozycji w strukturze nadrzędnej. Brak pola oznacza brak deklaracji dotyczącej składania. Dozwolone wartości: "none", "merge", "nest" |
artifactDelimiters | object | nie | Para ograniczników szablonów Go, którą plugin stosuje do importowanych plików artefaktów. Brak pola oznacza domyślną parę {{/}}; plugin, którego składnia docelowa koliduje z tą parą, deklaruje tutaj alternatywną parę. |
assemblyNameAnnotation | object | nie | Adnotacja granicy, której rozwiązana wartość określa nazwę artefaktu składanego przez plugin z grupy dyspozycyjnej. Plugin, który scala granice wnoszące wkład do grupy w jeden nazwany zestaw, deklaruje odczytywany klucz adnotacji oraz to, czy wszystkie granice wnoszące wkład muszą mieć zgodną rozwiązaną wartość tej adnotacji. Brak pola oznacza, że plugin nadaje nazwę zestawowi wyłącznie na podstawie ścieżki dyspozycji. |
reusableInstance | logiczna | nie | Czy jedna załadowana instancja pluginu może obsłużyć każde przejście renderowania, składania i walidacji w kompilacji zamiast nowej instancji dla każdego przejścia. Deklarowane jako true tylko wtedy, gdy plugin nie przechowuje stanu między przejściami — jest czystą funkcją danych wejściowych danego przejścia — tak aby pojedyncza instancja dawała bajtowo identyczny wynik niezależnie od tego, czy jest używana ponownie, czy ładowana od nowa. Brak pola (false) powoduje ładowanie nowej instancji dla każdego przejścia, co izoluje plugin, który z założenia przechowuje stan. |
crossBoundaryLinking | logiczna | nie | Czy plugin łączy krawędź uses przekraczającą granicę — krawędź uses, której strona korzystająca i strona wykorzystywana są składane w różnych grupach dyspozycyjnych — emitując natywne dla dostawcy powiązania odwołań krzyżowych poprzez sparowany kontrakt eksportów link_publish/link_resolve. Deklarowane jako true tylko wtedy, gdy plugin eksportuje oba; deklaracja niezgodna z parą eksportów zatrzymuje ładowanie. Brak pola (false) oznacza brak łączenia między granicami, więc host nie kieruje do pluginu żadnego przejścia łączenia. |
omits | logiczna | nie | Czy dostawca respektuje wpisy omit — wpisy wskazujące renderowane jednostki, które należy pominąć w wyniku węzła: pomija w tym, co renderuje, każdą jednostkę dopasowaną przez wpis i raportuje, ile jednostek dopasował każdy wpis. Jest to zapis z chwili publikacji deklaracji omits składanej przez samoopis dostawcy, a wartość różna od tego raportu zatrzymuje ładowanie. Brak pola (false) oznacza brak takiej obsługi. |
boundaryArtifacts | logiczna | nie | Czy dostawca przyjmuje pliki, które encja Recipe wnosi do wspólnego wyniku granicy, w której jest renderowana, w ramach spec.boundary.artifacts tej encji Recipe: kompilator zapisuje każdy taki plik jeden raz, w katalogu zawierającym złożony wynik granicy, a cel dostawcy traktuje go jako część tego wyniku. Jest to zapis z chwili publikacji deklaracji boundary_artifacts składanej przez samoopis dostawcy, a wartość różna od tego raportu zatrzymuje ładowanie. Brak pola (false) oznacza brak takiej obsługi, a encja Recipe deklarująca ten blok dla tego dostawcy zostaje odrzucona, zanim cokolwiek zostanie wyrenderowane. |
nestSegment | string | nie | Katalog, pod którym cel tego dostawcy umieszcza własny podkatalog każdego współtwórcy, dla dostawcy, którego boundaryAssembly ma wartość nest — charts dla nadrzędnego chartu, modules dla modułu głównego. Kompilator łączy ten katalog, nazwę współtwórcy i własną ścieżkę każdego pliku. Odczytywane tylko dla dostawcy zagnieżdżającego. Brak pola powoduje umieszczenie podkatalogu każdego współtwórcy bezpośrednio w katalogu granicy. Wartość wskazuje jeden katalog, nigdy ścieżkę. |
sourceIgnore | object | nie | Pliki, których ekosystem tego dostawcy nigdy nie dostarcza obok renderowanego źródła, w postaci reguł ignorowania w składni gitignore — zapis z chwili publikacji reguł source_ignore deklarowanych przez jego samoopis. Gdy autor przypina encję Recipe lub FeatureRecipe, której możliwość obsługuje dla niego ten dostawca, reguły te są łączone z własnym plikiem .aggregaignore autora i zapisywane w entity.lock obok encji, wraz z nazwą tego pluginu, a każda późniejsza publikacja, porównanie i renderowanie lokalnego źródła encji stosuje zapisane reguły. Jeśli pole występuje, musi być równe temu, co deklaruje samoopis, a ładowanie odrzuca plugin, którego raport się różni; brak pola nie stanowi żadnej deklaracji i nie jest porównywany. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.provider.contract.inputKinds
Które z trzech rodzajów danych wejściowych encji Recipe renderuje ten plugin: zestaw plików źródłowych, syntetyzowane obciążenie oraz samodzielny węzeł zawierający wyłącznie artefakty. Każde pole jest niezależną deklaracją.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
sourced | logiczna | nie | Renderuje dostarczony zestaw plików (chart, moduł, plik compose). |
synthesized | logiczna | nie | Renderuje syntetyzowane obciążenie do artefaktów natywnych dla providera. |
artifactsStandalone | logiczna | nie | Renderuje samodzielny węzeł zawierający wyłącznie artefakty — z importowanymi dokumentami artefaktów, bez źródła i bez obciążenia. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.provider.contract.artifactDelimiters
Para ograniczników szablonów Go, którą plugin stosuje do importowanych plików artefaktów. Brak pola oznacza domyślną parę {{/}}; plugin, którego składnia docelowa koliduje z tą parą, deklaruje tutaj alternatywną parę.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
left | string | tak | Ogranicznik otwierający. |
right | string | tak | Ogranicznik zamykający. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.provider.contract.assemblyNameAnnotation
Adnotacja granicy, której rozwiązana wartość określa nazwę artefaktu składanego przez plugin z grupy dyspozycyjnej. Plugin, który scala granice wnoszące wkład do grupy w jeden nazwany zestaw, deklaruje odczytywany klucz adnotacji oraz to, czy wszystkie granice wnoszące wkład muszą mieć zgodną rozwiązaną wartość tej adnotacji. Brak pola oznacza, że plugin nadaje nazwę zestawowi wyłącznie na podstawie ścieżki dyspozycji.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
annotation | string | tak | Klucz adnotacji granicy, z którego plugin odczytuje nazwę złożonego artefaktu. |
requireUnique | logiczna | nie | Czy wszystkie granice współtworzące jedną grupę dyspozycji muszą być zgodne co do rozwiązanej wartości adnotacji. Gdy true, grupa, której granice rozwiązują adnotację do różnych wartości, zatrzymuje kompilację; gdy false, plugin przyjmuje pierwszą rozwiązaną wartość. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.provider.contract.sourceIgnore
Pliki, których ekosystem tego dostawcy nigdy nie dostarcza obok renderowanego źródła, w postaci reguł ignorowania w składni gitignore — zapis z chwili publikacji reguł source_ignore deklarowanych przez jego samoopis. Gdy autor przypina encję Recipe lub FeatureRecipe, której możliwość obsługuje dla niego ten dostawca, reguły te są łączone z własnym plikiem .aggregaignore autora i zapisywane w entity.lock obok encji, wraz z nazwą tego pluginu, a każda późniejsza publikacja, porównanie i renderowanie lokalnego źródła encji stosuje zapisane reguły. Jeśli pole występuje, musi być równe temu, co deklaruje samoopis, a ładowanie odrzuca plugin, którego raport się różni; brak pola nie stanowi żadnej deklaracji i nie jest porównywany.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
patterns | string[] | nie | Własne wzorce ignorowania ekosystemu, każdy odnoszący się do katalogu głównego lokalnego katalogu źródłowego, w kolejności, w jakiej są stosowane. |
files | string[] | nie | Nazwy plików ignorowania, które ekosystem respektuje wewnątrz źródła — .helmignore dla chartu. Wiersze każdego takiego pliku są kolejnymi wzorcami, odnoszącymi się do katalogu, który go zawiera. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.pipelineStep
Blok kroku potoku dla pluginu pluginType: pipeline-step: możliwości dostawcy, z którymi zgodny jest jego krok. Występuje tylko w pluginach kroku potoku; nie występuje w żadnym innym typie pluginu.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
capabilities | string[] | nie | Zapisywane z samoraportu pliku .wasm pluginu przez aggrega plugin gen-catalog, więc źródłem tej listy jest plugin. Autor może zawęzić ją przed publikacją, usuwając wpis, którego ta encja nie powinna oferować, ale nie może dodać żadnego, którego samoraport nie wymienia: publikacja oraz aggrega validate z plikiem .wasm pluginu podanym przez --plugin odrzucają listę wymieniającą możliwość, której samoraport nie wymienia. Publikacja wysyła encję w postaci, w jakiej ją napisano, nigdy nie przepisując tej listy, i odnotowuje każdą możliwość wymienioną w samoraporcie, którą lista pomija. Możliwości dostawców, z którymi zgodny jest krok potoku tego pluginu — nazwy możliwości dostawców, takie jak helm lub compose, których wyrenderowany wynik krok potrafi przekształcić. Krok jest pisany pod kształt wyniku jednego dostawcy naraz, więc lista jest jawną, przetestowaną deklaracją zgodności, a nie aspiracją. Wpisy zachowują kolejność nadaną przez autora. Jest to czytelny dla katalogu zapis tej deklaracji; kompilacja odczytuje tę samą deklarację z pluginu, gdy krok dotyczy zakresu, i zatrzymuje się, gdy dostawcy renderującego dokumenty tego zakresu nie ma wśród nich. Pusta lub nieobecna lista nie deklaruje zgodności, więc żaden zakres nie dopuszcza kroku. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.parser
Blok parsera dla pluginu pluginType: parser: formaty źródłowe, które przekształca w kanoniczne drzewo strukturalne. Występuje tylko w pluginach parsera; nie występuje w żadnym innym typie pluginu.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
capabilities | string[] | nie | Zapisywane z samoraportu pliku .wasm pluginu przez aggrega plugin gen-catalog, więc źródłem tej listy jest plugin. Autor może zawęzić ją przed publikacją, usuwając wpis, którego ta encja nie powinna oferować, ale nie może dodać żadnego, którego samoraport nie wymienia: publikacja oraz aggrega validate z plikiem .wasm pluginu podanym przez --plugin odrzucają listę wymieniającą możliwość, której samoraport nie wymienia. Publikacja wysyła encję w postaci, w jakiej ją napisano, nigdy nie przepisując tej listy, i odnotowuje każdą możliwość wymienioną w samoraporcie, którą lista pomija. Formaty źródłowe, które ten parser przekształca w kanoniczne drzewo strukturalne, każdy zapisany jako parse:<format> — na przykład parse:yaml. Prefiks jest częścią wpisu, więc plugin oferujący kilka formatów podaje jeden wpis na format. Wpisy zachowują kolejność nadaną przez autora. Żądany format jest rozwiązywany do parsera, którego lista zawiera pasujący wpis; format nieoferowany przez żaden parser zatrzymuje kompilację, a format oferowany przez więcej niż jeden plugin parsera zatrzymuje ją jako niejednoznaczny. Pusta lub nieobecna lista nie deklaruje żadnego formatu, więc plugin niczego nie parsuje. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.importer
Blok importera dla pluginu pluginType: importer: obce formaty źródłowe, które przekształca w robocze pliki autorskie Aggrega, oraz sygnatury, po których rozpoznawane jest źródło w tych formatach. Występuje tylko w pluginach importera; nie występuje w żadnym innym typie pluginu.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
capabilities | string[] | nie | Zapisywane z samoopisu wtyczki .wasm przez aggrega plugin gen-catalog, więc źródłem tej listy jest wtyczka. Autor może zawęzić ją przed publikacją, usuwając wpis, którego ta encja nie powinna oferować, ale nie może dodać żadnego, którego samoopis nie wymienia: publikacja oraz aggrega validate z plikiem .wasm wtyczki podanym przez --plugin odrzucają listę wymieniającą możliwość, której samoopis nie wymienia. Publikacja wysyła encję w postaci, w jakiej ją napisano, nigdy nie przepisując tej listy, i odnotowuje każdą możliwość wymienioną w samoopisie, którą lista pomija. Obce formaty źródłowe, które ten importer przekształca w robocze pliki autorskie Aggrega, każdy zapisany jako import:<format> — na przykład import:terraform. Prefiks jest częścią wpisu, więc jedna wtyczka deklarująca kilka formatów podaje po jednym wpisie na format. Wpisy zachowują kolejność nadaną przez autora. Żądany format importu jest rozwiązywany do importera, którego lista zawiera pasujący wpis; format, którego nie deklaruje żaden importer, zatrzymuje import, a format deklarowany przez więcej niż jedną wtyczkę importera zatrzymuje go jako niejednoznaczny, chyba że wpis plugins.importer w konfiguracji przestrzeni roboczej dołącza jedną z nich, która wtedy zostaje uruchomiona. Pusta lub nieobecna lista nie deklaruje żadnych formatów, więc wtyczka niczego nie importuje. |
detect | object[] | nie | Zarządzane przez maszynę, nie należy go tworzyć ręcznie: wyprowadzane z samoopisu wtyczki .wasm podczas generowania z niej encji i zapisywane tutaj w kolejności zadeklarowanej przez samoopis. Sygnatury, po których rozpoznawane jest źródło w formatach tego importera, gdy import nie wskazuje formatu. aggrega import odczytuje sygnatury każdego importera z katalogu przestrzeni roboczej, łącznie ze wszystkimi wersjami, oraz importerów wbudowanych w kompilator, dopasowuje je do źródła, nie wiedząc, czym jest którykolwiek format, i odczytuje źródło jako format tego jedynego importera, którego sygnatura pasuje; źródło, do którego nie pasuje żadna sygnatura, jest odrzucane z prośbą o podanie formatu, a źródło, do którego pasują sygnatury więcej niż jednego formatu, jest odrzucane z ich wymienieniem. Importer rozpoznający źródło rozpoznaje je jako każdy deklarowany przez siebie format, więc w przypadku importera deklarującego więcej niż jeden format każde dopasowanie jest odrzucane jako niejednoznaczne. Jeśli lista jest obecna, musi być równa temu, co deklaruje samoopis wtyczki, wpis po wpisie i w tej samej kolejności, a ładowanie i publikacja odrzucają wtyczkę, której zgłoszenie się różni, wskazując to pole. Brak pola nie deklaruje niczego i nie jest porównywany, a formaty importera są wtedy dostępne tylko przez ich jawne wskazanie. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.importer.detect[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
syntax | string | tak | Format składniowy, w jakim parsowane jest źródło — na przykład json lub yaml — czyli format, który wtyczka parsera deklaruje jako parse:<syntax>. Źródło jest parsowane parserem, który katalog przestrzeni roboczej udostępnia dla tej składni, a dla składni, dla której katalog nie udostępnia żadnego, parserem wbudowanym w kompilator, co najwyżej raz niezależnie od liczby sygnatur wskazujących tę składnię; źródło, które się w niej nie parsuje, nie pasuje do żadnej wskazującej ją sygnatury. Składnia, dla której żadne z nich nie udostępnia parsera, przerywa rozpoznawanie ze wskazaniem brakującego parsera. Co najmniej 1 znak. |
files | string[] | nie | Wzorce nazw plików, do których stosuje się sygnatura, dopasowywane do końca nazwy źródła z separatorami odczytywanymi jako ukośniki: wzorzec jednosegmentowy do samej nazwy pliku, a wzorzec złożony z kilku segmentów rozdzielonych ukośnikami do tylu samo końcowych segmentów jego ścieżki, więc .vscode/mcp.json pasuje do pliku o nazwie mcp.json w katalogu o nazwie .vscode. W obrębie segmentu * pasuje do dowolnego ciągu znaków, ? do jednego znaku, a [...] do jednego znaku z klasy. Sygnatura ma zastosowanie, gdy pasuje dowolny wzorzec. Brak lub pusta lista stosuje ją do źródła będącego jednym plikiem, niezależnie od jego nazwy, i do żadnego pliku katalogu. Wzorce sygnatur importera decydują również o tym, które pliki katalogu aggrega import mu przekazuje. |
match | object[] | nie | Predykaty, które musi spełniać sparsowane drzewo, wszystkie, w zadeklarowanej kolejności. Brak lub pusta lista nie wymaga od drzewa niczego poza sparsowaniem w danej składni. |
Dodatkowe właściwości są niedozwolone.
plugin.spec.importer.detect[].match[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
path | string | tak | Miejsce w drzewie, w którym predykat szuka, zapisane jako klucze połączone kropkami od wierzchołka drzewa: data.nodes wskazuje element nodes obiektu data najwyższego poziomu. Segment zapisany jako liczba całkowita, 0 lub większa, wybiera tę pozycję tablicy liczoną od zera, więc nodes.0.type wskazuje type pierwszego węzła; każdy inny segment wybiera element obiektu. Co najmniej 1 znak. |
is | string (enum) | tak | Do czego ścieżka musi dotrzeć: present jest spełnione, gdy dociera do wartości dowolnego rodzaju, w tym null; absent jest spełnione, gdy nie dociera do niczego; object, array, string, number i boolean są spełnione, gdy dociera do wartości danego rodzaju. Dozwolone wartości: "present", "absent", "object", "array", "string", "number", "boolean" |
equals | string | nie | Ciąg, któremu wartość osiągnięta przez ścieżkę musi być dokładnie równa; wartość niebędąca ciągiem nigdy nie jest mu równa. W jednym predykacie deklaruje się co najwyżej jedno z equals i prefix. Co najmniej 1 znak. |
prefix | string | nie | Ciąg, od którego musi zaczynać się wartość osiągnięta przez ścieżkę; wartość niebędąca ciągiem nigdy się od niego nie zaczyna. W jednym predykacie deklaruje się co najwyżej jedno z equals i prefix. Co najmniej 1 znak. |
Dodatkowe właściwości są niedozwolone.