Plugin
Um Plugin é um plugin WebAssembly endereçado por conteúdo: um artefacto .wasm alojado em OCI, fixado pelo digest sha256, que declara o tipo de socket que implementa, a versão de ABI a que se destina, um ponteiro opcional para uma assinatura e um bloco runtime opcional. A entidade é a superfície de criação e de metadados de um plugin; a resolução de dependências fixa o artefacto pelo digest e a política de confiança por registo verifica a sua assinatura no pull. O compilador não interpreta o comportamento do plugin — encaminha a referência fixada; o runtime WebAssembly executa os bytes.
Esta página abrange a superfície de criação do Plugin no catálogo, campo a campo. Para o fluxo de trabalho completo do autor — o que é um plugin, o autorrelatório describe(), o ciclo de vida publicar→pull→build, a assinatura e o versionamento — consulte o guia do programador de plugins Wasm. Para os pontos de socket a que um plugin se liga e as respetivas formas de entrada/saída, consulte o contrato de plugins Wasm.
O papel do Plugin
Um Plugin associa uma identidade lógica de plugin a um artefacto .wasm concreto e aos metadados de capacidade e de runtime de que o anfitrião precisa para o carregar e executar em segurança. Um passo de pipeline ou um socket de plugin referencia a entidade pelo seu URI; a entidade contém as capacidades declaradas, os limites de runtime e o ponteiro para a assinatura, enquanto o digest de conteúdo resolvido reside no lockfile da versão. A localização do .wasm é derivada da identidade do plugin — a coordenada endereçável plugin/<pluginType>/<name>, ela própria composta a partir de metadata.pluginType e do metadata.name simples, mais o registo configurado — e não é um campo criado. A indireção através da entidade é obrigatória — um .wasm simples ou uma referência de artefacto é rejeitado no carregamento porque nenhuma entidade lhe corresponde.
As declarações de um Plugin estão agrupadas por tipo de socket, e esse agrupamento é por onde começa a leitura da entidade:
- Um bloco por tipo de socket —
spec.provider,spec.pipelineStep,spec.parser,spec.importer. Um plugin contém o único bloco que o seumetadata.pluginTypeindica, e cada bloco contém uma listacapabilities:— registada a partir do própriodescribe()do plugin poraggrega plugin gen-catalog— cujo significado pertence apenas a esse bloco: a lista de um fornecedor indica as capacidades que serve, a de um passo de pipeline indica as capacidades de fornecedor com que o seu passo é compatível, e as de um parser e de um importador indicam formatos de origem, escritosparse:<format>eimport:<format>. É a contenção que transporta o significado — não é possível chegar a uma entrada de capacidade sem primeiro ler o bloco que diz de que tipo de afirmação se trata. - Um bloco de fornecedor contém mais do que a sua lista —
spec.providerdeclara também como o plugin traduz o tipo Workload, que anotações nativas da plataforma lê e o seu contrato de comportamento de renderização (spec.provider.contract: tipos de entrada, montagem de fronteiras, delimitadores de artefactos, reutilização de instâncias). Estes descrevem o comportamento de renderização e não uma dimensão servida, e é por isso que ficam ao lado da lista de capacidades do fornecedor e não dentro dela. - Um socket transversal não declara capacidades — um plugin
linter,governanceouclinão contém nenhum dos quatro blocos, porque não serve nenhuma dimensão de renderização nem nenhum formato de origem.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: 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 credentialmetadata
Metadados padrão do catálogo. name, version e pluginType são obrigatórios; version é uma Semantic Version estrita (p. ex., 1.2.0). Os campos opcionais — description, maintainers, license, repository, home, keywords — seguem a mesma forma que todas as entidades de catálogo têm, e metadata não aceita nenhuma outra chave. Uma versão publicada é imutável: voltar a publicar uma versão existente é rejeitado no controlo de publicação.
metadata.name é simples — não tem nenhum prefixo de socket. A coordenada endereçável do plugin plugin/<pluginType>/<name> é derivada de metadata.pluginType e do metadata.name simples; não é escrita no nome.
metadata.pluginType
O tipo de socket que este plugin implementa. Fica no bloco de endereçamento ao lado de name e version porque faz parte da identidade do plugin: fornece o segmento <pluginType> da coordenada derivada plugin/<pluginType>/<name>. Um plugin implementa exatamente um tipo de socket, retirado da taxonomia de tipos de plugin que o runtime reconhece:
provider— renderiza nós da IR em artefactos nativos do fornecedor.linter— inspeciona o conteúdo criado e emite diagnósticos.pipeline-step— um passo nopipeline:de uma FeatureRecipe ou de uma Recipe que aplica patches ao conjunto de documentos renderizados.governance— serve os papéis de governação do pipeline de build. Na construção da topologia, etiqueta automaticamente os nós do grafo de topologia, devolvendo documentos JSON Patch que o anfitrião aplica a uma projeção do grafo apenas com etiquetas. Na análise estática ou na fase de renderização, avalia o grafo da IR ou os artefactos renderizados e devolve um veredicto de aceitação/rejeição; uma regra falhada interrompe o build. É o papel em que está anexado, e não o seu tipo, que determina o que pode emitir.parser— analisa um formato de origem externo (HCL, TOML, YAML, JSON, …) para uma árvore JSON estruturada, para que um consumidor que precise de ler um formato que o compilador não analisa nativamente trabalhe a partir de uma árvore analisada e não do texto em bruto.importer— transforma uma origem externa de infraestrutura ou de definição de agentes em ficheiros de criação Aggrega provisórios, anunciando os formatos que trata como capacidadesimport:<format>.cli— contribui com um subcomandoaggrega <cmd>de runtime que um operador invoca na linha de comandos. Um socket de runtime, distinto dos sockets de renderização e de pipeline em tempo de compilação.
Obrigatório.
spec.abiVersion
A versão de ABI host/guest a que o plugin se destina. v1beta1 é o valor aceite; uma nova revisão da ABI acrescenta um. Obrigatório.
Declarar capacidades: um bloco por tipo de socket
Uma capacidade é aquilo que um consumidor pede a um plugin — uma capacidade de renderização que uma Recipe pede, ou um formato de origem que um build precisa de ler. As capacidades de um plugin são registadas dentro do bloco que pertence ao seu tipo de socket, pelo que o bloco em que a lista se encontra é o que determina o significado das suas entradas:
metadata.pluginType | Onde são declaradas as suas capacidades | O que uma entrada indica |
|---|---|---|
provider | spec.provider.capabilities | Uma capacidade de renderização que este plugin serve, como helm ou compose. |
pipeline-step | spec.pipelineStep.capabilities | Um fornecedor com cuja saída renderizada o passo deste plugin é compatível. |
parser | spec.parser.capabilities | Um formato de origem que este plugin lê, escrito parse:<format>. |
importer | spec.importer.capabilities | Um formato de origem externo a partir do qual este plugin cria entidades provisórias, escrito import:<format>. |
linter, governance, cli | — | Nada. Estes sockets não servem nenhuma capacidade, pelo que não contêm nenhum dos quatro blocos. |
Um plugin implementa exatamente um tipo de socket, pelo que a sua entidade contém um único bloco. A lista é o relatório do próprio plugin: aggrega plugin gen-catalog lê o describe() do plugin e escreve no bloco cada capacidade que este reporta. Um autor pode restringir a lista antes de publicar, omitindo uma capacidade que o plugin reporta mas que a entidade publicada não deve oferecer; aggrega validate <entity> --plugin <file.wasm> e aggrega push aceitam uma lista restringida e imprimem um aviso que indica cada capacidade reportada pelo plugin que a lista omite. Nenhum dos dois aceita uma lista que indique uma capacidade que o plugin não reporta: ambos a recusam, indicando cada uma dessas capacidades e as capacidades que o plugin efetivamente reporta, pelo que uma lista publicada nunca oferece mais do que o plugin fornece. Uma entidade pipeline-step cujo plugin reporta helm e helm-chart, e que lista também compose, é recusada desta forma:
[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()Um consumidor resolve exatamente com base no que está listado.
spec.provider
O bloco de socket de fornecedor de um plugin pluginType: provider: as capacidades que serve, como traduz o tipo Workload aggrega.ai/v1beta1 gerido pela plataforma, que anotações nativas da plataforma lê e o seu contrato de comportamento de renderização. O bloco está presente em todos os plugins de renderização de fornecedores e ausente em todos os outros tipos de plugin. Um fornecedor que renderiza apenas conteúdo com origem ou de artefactos, sem síntese de Workload, continua a ter o bloco — declara aí as suas capacidades e o seu contrato e simplesmente omite workloadSchema.
spec.provider.capabilities
As capacidades que este fornecedor serve — nomes de capacidades como helm ou compose — cuja forma de saída renderiza. Um fornecedor é genérico entre artefactos que partilham a forma de saída de uma capacidade, não entre todas as capacidades, pelo que a lista indica as capacidades que o próprio plugin reporta: aggrega plugin gen-catalog regista-a a partir do describe() do plugin, e um autor pode restringi-la antes de publicar. As entradas mantêm a ordem em que são registadas.
O destino de fornecedor pedido por uma Recipe (spec.capability: helm) resolve-se para o plugin de fornecedor cuja lista contém esse destino. Quando mais do que um plugin de fornecedor lista o mesmo destino, é o espaço de trabalho que escolhe: a seleção plugins.providers na configuração do espaço de trabalho indica que plugin usar, resolvida no aggrega pull e registada no lockfile. Sem seleção e com exatamente um candidato, é usado esse candidato; sem seleção e com mais do que um candidato, o build é interrompido e indica todos os candidatos. A ambiguidade é resolvida por espaço de trabalho no ponto de utilização e não por uma regra de unicidade ao nível de todo o catálogo. Uma lista vazia ou ausente não declara nenhuma afirmação de capacidade, pelo que o plugin não serve nenhum destino.
Um nome de capacidade aqui não contém dois pontos. O spec.capability de uma Recipe é lido como a capacidade até aos últimos dois pontos e uma fixação de versão depois deles, pelo que um nome que os contenha nunca poderia ser pedido; um plugin cujo describe() indique um nome desses é recusado quando é carregado, e nenhuma entidade é gerada a partir dele para publicação. O mesmo se aplica às capacidades de fornecedor que um plugin pipeline-step lista. Os dois pontos em parse:<format> de um parser e em import:<format> de um importador fazem parte desses nomes e mantêm-se.
spec.provider.workloadSchema
Uma declaração de JSON Schema 2020-12 que documenta como este fornecedor traduz o tipo Workload aggrega.ai/v1beta1 em manifestos nativos do fornecedor. É declarada por convenção num fornecedor que sintetiza: um fornecedor desse tipo declara workloadSchema como o contrato de tradução documentado, descrevendo que campos de Workload o fornecedor consome, que conjuntos fechados cada campo com forma de enum aceita e que restrições de intervalo se aplicam.
O corpo é compilado para JSON Schema 2020-12 quando o Plugin é carregado — uma salvaguarda estrutural que rejeita um esquema malformado no carregamento e não na renderização. Se uma Recipe workload: é suportada é determinado pela capacidade de síntese do fornecedor associado, não pela presença deste campo: uma Recipe em modo sintetizado associada a um fornecedor que não consegue sintetizar é interrompida ruidosamente no momento da renderização. O catálogo da biblioteca padrão mantém workloadSchema sincronizado com a capacidade do fornecedor. O campo é o contrato documentado; nada mais o lê. Os próprios corpos de Workload são validados contra o esquema de Workload incorporado gerido pela plataforma, não contra este campo por fornecedor.
spec.provider.wellKnownAnnotations
Um array ordenado que enumera as chaves de anotações bem conhecidas nativas da plataforma — as que estão no espaço de nomes reservado aggrega.ai/ — que este fornecedor lê, juntamente com o comportamento aplicado quando cada uma está ausente. Cada entrada contém uma key (a anotação lida pelo fornecedor, p. ex., aggrega.ai/namespace), um purpose (o que a anotação controla quando está presente), um defaultBehavior opcional (o que o fornecedor faz quando a anotação está ausente) e um scope opcional que lista onde o fornecedor lê a chave — sourced, synthesized ou artifactsStandalone, os tipos de entrada da Recipe, ou boundary para uma chave lida uma vez por fronteira. key e purpose são obrigatórios; as entradas preservam a ordem de criação.
O campo é a afirmação de suporte do fornecedor, e o compilador lê-o de duas formas. Uma entrada cujo scope indica um tipo de entrada que o próprio contract.inputKinds do bloco não afirma contradiz essa afirmação, e o Plugin é recusado, com a indicação da chave e do âmbito. E quando um build renderiza através deste fornecedor, uma anotação aggrega.ai/ que nenhuma entrada cobre em nenhum dos tipos de entrada que a renderização declara gera um aviso que indica a chave, o fornecedor e esses tipos de entrada; o valor continua a passar inalterado e o build não é interrompido. Se estiver ausente, o campo não faz qualquer afirmação, e não é emitido nenhum aviso desse tipo para este fornecedor. A validação do esquema verifica apenas a forma de cada entrada (a chave está no espaço de nomes aggrega.ai/, purpose está presente); é distinta da verificação em tempo de execução que rege a associação de um valor ao espaço de nomes reservado.
metadata: pluginType: providerspec: 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.Os conjuntos de anotações por fornecedor e o conteúdo de workloadSchema que os fornecedores da biblioteca padrão disponibilizam estão documentados em ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md e ../providers/compose.md.
spec.provider.readsNoWellKnownAnnotations
Declara que este fornecedor não lê nenhuma das chaves de anotações bem conhecidas nativas da plataforma. É uma afirmação de suporte que não cobre nenhuma chave, e diz algo que omitir tanto este campo como wellKnownAnnotations não diz: uma afirmação ausente é silêncio, enquanto esta é a declaração do próprio fornecedor de que não lê nada no espaço de nomes reservado aggrega.ai/. Um build que renderiza através de um fornecedor assim emite um aviso para cada anotação aggrega.ai/ que chega à renderização, indicando a chave, o fornecedor e os tipos de entrada que a renderização declara; o valor continua a passar inalterado e o build não é interrompido.
Só pode ser escrito true, pelo que omitir o campo continua a ser a única forma de não dizer nada. Não pode ser escrito juntamente com wellKnownAnnotations: um fornecedor que lê algumas das chaves lista-as aí em vez disso. Ambas as recusas são ao nível do esquema, pelo que o Plugin é recusado quando é lido.
spec: provider: capabilities: - terraform readsNoWellKnownAnnotations: trueO fornecedor terraform da biblioteca padrão declara-o; ../providers/terraform.md explica o que isso significa para uma Release renderizada através dele.
spec.provider.contract
O contrato de comportamento de renderização em tempo de compilação autodeclarado por um plugin de renderização de fornecedor: os tipos de entrada que renderiza, como monta a saída por nó de um grupo de despacho, o par de delimitadores de template que aplica aos ficheiros de artefactos importados, se uma única instância carregada pode servir todas as travessias, se respeita entradas de omissão e se aceita os ficheiros que uma Recipe contribui para a saída partilhada da sua fronteira. Fica ao lado de capabilities no mesmo bloco, mas responde a uma pergunta diferente: a lista de capacidades diz que capacidades este plugin serve, enquanto o contrato diz como as renderiza. aggrega plugin gen-catalog regista-o a partir do próprio autorrelatório describe() do plugin, e o anfitrião verifica-o face a esse autorrelatório na publicação e no carregamento; uma divergência interrompe o processo. A ausência não declara nenhum contrato de comportamento de renderização, e a verificação cruzada compara apenas as afirmações por exportação. Todos os campos são opcionais.
| Campo | Efeito |
|---|---|
inputKinds | Quais dos três tipos de entrada de Recipe o plugin renderiza, cada um uma afirmação booleana independente: sourced (um conjunto de ficheiros com origem — um chart, um módulo, um ficheiro compose), synthesized (um Workload sintetizado) e artifactsStandalone (um nó autónomo que contém documentos de artefactos importados e nenhuma origem ou carga de trabalho). O anfitrião condiciona o tipo de entrada de um nó a este conjunto. |
boundaryAssembly | Como o plugin combina a saída de renderização por nó de um grupo de despacho: none escreve a saída de cada nó diretamente no caminho de despacho; merge integra os fragmentos por nó num único documento; nest coloca a saída de cada nó na sua própria posição numa estrutura agregadora. A ausência não transporta nenhuma afirmação de montagem. |
artifactDelimiters | O par de delimitadores de template Go que o plugin aplica aos ficheiros de artefactos importados, como left e right. A ausência significa o par predefinido {{/}}; um plugin cuja sintaxe de destino colida com esse par declara um par alternativo (por exemplo, [[/]]). |
reusableInstance | Se uma única instância carregada do plugin pode servir todas as travessias de renderização, montagem e validação de um build, em vez de uma instância nova por travessia. Declarado true apenas quando o plugin não mantém estado entre travessias, para que uma única instância produza uma saída idêntica byte a byte, quer seja reutilizada quer seja carregada de novo. A ausência (false) carrega uma instância nova por travessia, isolando um plugin que mantém estado por construção. aggrega build --verify-determinism prova que a saída de um plugin reutilizável é estável renderizando cada nó duas vezes e interrompendo o build perante qualquer diferença. |
omits | Se o plugin respeita entradas de omissão — entradas que indicam unidades renderizadas a deixar de fora da saída de um nó: deixa de fora do que renderiza cada unidade a que uma entrada corresponde e indica a quantas unidades cada entrada correspondeu. O valor regista a afirmação que o describe() do plugin indica, pelo que true só é correto para um plugin que o indique, e um valor que difira do relatório interrompe o processo. A ausência (false) não declara tal suporte. |
boundaryArtifacts | Se o destino do plugin aceita os ficheiros que uma Recipe contribui para a saída partilhada da fronteira em que renderiza, sob o spec.boundary.artifacts da Recipe: o compilador escreve cada um desses ficheiros uma vez, ao lado do que o plugin monta para a fronteira, e o destino lê-o como parte dessa saída. O valor regista a afirmação que o describe() do plugin indica, e um valor que difira do relatório interrompe o processo. A ausência (false) não declara tal suporte, e uma Recipe que declare o bloco para este plugin é recusada antes de qualquer renderização. |
metadata: pluginType: providerspec: 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: truespec.pipelineStep
O bloco de passo de pipeline de um plugin pluginType: pipeline-step. O seu único campo, capabilities, indica os fornecedores cuja saída renderizada o passo do plugin sabe transformar — nomes de capacidades como helm ou compose. Um passo é escrito para a forma de saída de um fornecedor de cada vez, pelo que a lista indica os fornecedores que o próprio plugin reporta; as entradas mantêm a ordem em que são registadas. O bloco só está presente em plugins de passo de pipeline.
O bloco é o registo, legível no catálogo, dessa afirmação: aggrega plugin gen-catalog regista-o a partir do próprio autorrelatório describe() do plugin, e um autor pode restringi-lo antes de publicar. A imposição lê a mesma afirmação a partir do plugin: quando um passo toca num âmbito, o build é interrompido, a menos que o fornecedor que renderiza os documentos desse âmbito esteja entre os que o plugin afirma. Uma lista vazia ou ausente não declara nenhuma afirmação de compatibilidade, pelo que nenhum âmbito admite o passo.
metadata: pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm - composespec.parser
O bloco de parser de um plugin pluginType: parser. O seu único campo, capabilities, indica os formatos de origem que o plugin transforma numa árvore estruturada canónica, cada um escrito parse:<format>. O prefixo faz parte da entrada, pelo que um plugin que lê vários formatos lista uma entrada por formato. aggrega plugin gen-catalog regista a lista a partir do próprio describe() do plugin, um autor pode restringi-la antes de publicar, e as entradas mantêm a ordem em que são registadas. O bloco só está presente em plugins de parser.
Um formato pedido resolve-se para o parser cuja lista contém a entrada correspondente. Um formato que nenhum parser anuncia interrompe o build, e um formato anunciado por mais do que um plugin de parser interrompe-o por ambiguidade, indicando os candidatos — não há recurso alternativo, porque um parser não tem nenhuma predefinição sem configuração a que recorrer. Uma lista vazia ou ausente não declara nenhuma afirmação de formato, pelo que o plugin não analisa nada.
metadata: pluginType: parserspec: abiVersion: v1beta1 parser: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - parse:hcl - parse:tomlspec.importer
O bloco de importador de um plugin pluginType: importer. O seu campo capabilities indica os formatos de origem externos que o plugin transforma em ficheiros de criação Aggrega provisórios, cada um escrito import:<format>. O prefixo faz parte da entrada, pelo que um plugin que trata vários formatos lista uma entrada por formato. aggrega plugin gen-catalog regista a lista a partir do próprio describe() do plugin, um autor pode restringi-la antes de publicar, e as entradas mantêm a ordem em que são registadas. O bloco só está presente em plugins de importador.
Um formato de importação pedido resolve-se para o importador cuja lista contém a entrada correspondente. Um formato que nenhum importador anuncia interrompe a importação, e um formato anunciado por mais do que um plugin de importador interrompe-a por ambiguidade, indicando os candidatos, a menos que uma entrada plugins.importer na configuração do espaço de trabalho anexe um deles, que passa a ser o que é executado. Uma lista vazia ou ausente não declara nenhuma afirmação de formato, pelo que o plugin não importa nada.
O seu campo detect regista as assinaturas pelas quais uma origem desses formatos é reconhecida quando uma importação não indica nenhum formato. É gerido pela máquina, tal como os registos de funções do anfitrião e de comandos: é derivado do que o describe() do plugin indica quando a entidade é gerada a partir do plugin, pela ordem em que o plugin declara as assinaturas, e um autor não o escreve. Cada assinatura indica:
syntax— o formato sintático com que a origem é analisada, o formato que um plugin de parser anuncia comoparse:<syntax>, comojsonouyaml.files— padrões de nomes de ficheiros opcionais, comparados com o final do nome da origem: um padrão de um segmento com o próprio nome do ficheiro, um de vários segmentos separados por barras com o mesmo número de segmentos finais do seu caminho, pelo que.vscode/mcp.jsoncorresponde a um ficheiro chamadomcp.jsonnum diretório chamado.vscode.*,?e[...]correspondem dentro de um segmento. Na ausência, a assinatura aplica-se a uma origem que seja um único ficheiro, seja qual for o seu nome, e a nenhum ficheiro de um diretório. Os padrões das assinaturas de um importador são também o que decide que ficheiros de um diretório oaggrega importlhe entrega.match— os predicados que a árvore analisada tem de satisfazer, todos eles. Cada um tem umpath, chaves unidas por pontos a partir do topo da árvore, em que um segmento com um número inteiro seleciona uma posição de array; umis, um depresent,absent,object,array,string,numbereboolean; e, opcionalmente,equals, uma string que o valor tem de ser, ouprefix, uma string com que tem de começar — no máximo um dos dois.
Quando uma importação não indica nenhum formato, as assinaturas de todos os importadores que o catálogo do espaço de trabalho contém — incluindo todas as versões — e dos importadores centrais do compilador são comparadas com a origem. A origem é analisada uma vez para cada sintaxe em que uma assinatura aplicável ao seu nome a lê, através do parser que o catálogo do espaço de trabalho serve para essa sintaxe — ou, para uma sintaxe para a qual o catálogo não serve nenhum parser, o que o próprio compilador contém — e uma origem que não seja analisada numa sintaxe não corresponde a nenhuma assinatura que a indique. Um diretório é comparado através dos seus ficheiros: cada assinatura é experimentada contra os ficheiros do diretório que os seus padrões selecionam, por ordem de nome, e uma assinatura que não declare nenhum padrão não se aplica a nenhum deles. Uma origem a que uma assinatura corresponde é reconhecida como todos os formatos que o seu importador anuncia. Exatamente um formato reconhecido é aquele com que a origem é lida. Uma origem a que nenhuma assinatura corresponde é recusada, pedindo o formato e indicando os formatos que os importadores anunciam — ou, para um diretório, pedindo um dos seus ficheiros isoladamente ou um formato cujo importador declare padrões de ficheiro, indicando apenas esses; uma origem reconhecida como mais do que um formato é recusada indicando-os, com a condição More than one importer recognises the source (Mais do que um importador reconhece a origem). Assim, um importador que anuncie mais do que um formato vê todas as origens a que as suas assinaturas correspondem serem recusadas por ambiguidade, e um importador cujas origens devam ser reconhecidas serve um único formato.
Quando a entidade regista detect, este tem de ser igual ao que o describe() do plugin indica, assinatura a assinatura e pela mesma ordem: o carregamento do importador recusa um plugin cujo relatório difira, indicando importer.detect, e a publicação também. Uma entidade que não registe nenhum detect não faz nenhuma afirmação e não é comparada, pelo que carrega as assinaturas que o describe() do seu plugin indicar, e os formatos do seu importador só são então alcançados indicando-os.
metadata: pluginType: importerspec: abiVersion: v1beta1 importer: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - import:langflow detect: - syntax: json match: - path: data.nodes is: arrayspec.signature
Um ponteiro descritivo opcional para a assinatura anexada do plugin. O bloco é apenas documentação — regista, para os leitores do catálogo, onde a assinatura reside e como foi produzida; não admite ele próprio o plugin. A verificação que impõe é a política de confiança por registo aplicada no pull: uma assinatura é obtida como referrer OCI, verificada face às identidades de confiança ou à chave fixada do registo, e registada como um facto verificado no lockfile. Um registo que exige assinaturas interrompe o pull quando uma assinatura exigida está em falta, não é de confiança ou é inválida.
type— o esquema de assinatura.sigstore-cosigné o esquema suportado. Obrigatório quando o bloco está presente.signatureRef— a referência de referrer OCI do pacote de assinatura anexado, para documentação e descoberta. Ausente quando a assinatura é descoberta por enumeração de referrers no pull, em vez de ser fixada aqui.publicKeyRef— um ponteiro para a chave pública com que a assinatura foi produzida, para uma assinatura com chave. A ausência indica uma assinatura sem chave (identidade OIDC), verificada face às identidades de confiança do registo.
spec.runtime
Restrições de execução opcionais que o anfitrião aplica ao carregar e executar o plugin. O acesso à rede de saída não é um campo de criação: um plugin nunca acede à rede no momento do build — a fronteira ahead-of-time — pelo que não existe aqui nenhum campo de lista de permissões de hosts. O conteúdo remoto de que um plugin precisa chega através do canal de entradas externas mediado pelo anfitrião e fixado por digest, registado no lockfile da Release, nunca através de acesso ambiente à rede; o guia do programador documenta o wrapper de obtenção e a disciplina de fixação.
| Campo | Efeito |
|---|---|
maxMemoryPages | Limita a memória linear do plugin em páginas Wasm (64 KiB por página). Zero ou ausente aplica o limite predefinido da plataforma, pelo que um carregamento nunca é ilimitado; uma anexação que precise de mais aumenta este valor. |
timeoutMs | Limita o tempo durante o qual o próprio código do plugin pode ser executado numa chamada, em milissegundos, sem contar o tempo passado dentro das funções do anfitrião que invoca. No Linux, a medida é o tempo de processador, pelo que o tempo passado à espera de um processador numa máquina ocupada não conta; noutros sistemas, é o tempo decorrido. A primeira chamada a um plugin acabado de carregar conta também o próprio arranque do plugin. Zero ou ausente aplica o limite predefinido da plataforma, pelo que uma chamada nunca é impossível de cancelar; uma anexação que seja executada durante mais tempo aumenta este valor. |
hostFunctions | Os nomes das funções do anfitrião que o plugin importa. Derivado pela máquina e só de leitura — não o crie: aggrega plugin sync lê as funções do anfitrião a partir da secção de importação do .wasm e regista este campo, a publicação recusa um registo que difira do binário, e o valor reflete o binário publicado, validado face à lista de permissões selecionada. O anfitrião regista exatamente este conjunto, dando a cada plugin a superfície de anfitrião de privilégio mínimo de que o seu binário precisa; o pull volta a derivar e verifica o carimbo face ao binário. Para pré-visualizar o valor antes de publicar, execute aggrega inspect --plugin <file.wasm>. |
configKV | Configuração específica do Plugin que o runtime entrega ao plugin no arranque, como pares chave/valor de string para string. As entradas preservam a ordem do autor, para que o registo emitido seja idêntico byte a byte entre execuções. Se ausente, mantém-se em vigor a configuração vazia predefinida do runtime. |
spec.exports
As exportações que o plugin oferece, cada uma com a sua capacidade declarada, como uma lista ordenada que preserva a ordem de criação. Uma exportação é um ponto de entrada com nome para o qual o anfitrião despacha (por exemplo render_node, lint_naming, step); o bloco de capacidade por exportação indica o que essa exportação faz, tal como aggrega plugin gen-catalog o regista a partir do autorrelatório describe() do plugin, e o anfitrião verifica-o face a esse autorrelatório na publicação e no carregamento. A ausência não declara nenhuma superfície de exportação criada pelo autor.
| Campo | Efeito |
|---|---|
name | O nome ABI da exportação — o nome para o qual o anfitrião despacha. Obrigatório em cada entrada. |
operates | A operação de pipeline que a exportação efetua: patch (modificar um documento renderizado existente) ou emit (acrescentar um novo documento). O anfitrião verifica o valor face ao autorrelatório do plugin; é uma afirmação de capacidade validada, não um comutador de despacho — a operação que um passo efetua é transportada pelo resultado devolvido pelo guest. A ausência não transporta nenhuma afirmação de operação. |
scope | A raiz de documentos sobre a qual a exportação opera: own (os documentos renderizados do próprio nó) ou host (os documentos do componente a que uma FeatureRecipe com âmbito de componente está anexada). O anfitrião lê o âmbito declarado antes do passo para impor a compatibilidade de fornecedor face ao fornecedor que renderiza esse âmbito. A ausência assume own por predefinição. |
selector | Uma descrição livre e legível por humanos daquilo sobre que a exportação atua (por exemplo, workloads carrying a pod template). Documentação para os leitores do catálogo e para a superfície de inspeção; o compilador não a interpreta. |
spec.commands
Os verbos de nível superior aggrega <command> que um plugin cli contribui, como uma lista ordenada que preserva a ordem declarada pelo autorrelato describe() do plugin. Gerido pela máquina e só de leitura — não o escreva. aggrega plugin sync lê a superfície de comandos do autorrelato describe() do plugin e regista-a aqui, para que os comandos que um plugin CLI instala sejam legíveis a partir da entidade sem carregar o .wasm. Um plugin que não seja cli não contribui comandos e regista uma lista vazia. O host instala exatamente este conjunto; um conjunto registado que divirja do autorrelato describe() do plugin interrompe o carregamento, e a publicação recusa um conjunto dessincronizado do binário e indica ao autor que o volte a registar. Para ressincronizar o registo depois de alterar o plugin, execute aggrega plugin sync.
Cada entrada de comando contém:
| Campo | Efeito |
|---|---|
name | O verbo de comando que o host regista — o token aggrega <name> que um operador invoca, e o discriminador que o host entrega ao plugin na invocação, para que um único plugin que suporte vários comandos encaminhe consoante o comando chamado. Obrigatório em cada entrada. |
description | O texto de ajuda breve do comando, numa linha, mostrado na listagem de comandos e na saída da ajuda. Apenas documentação; o host não age com base nele. |
flags | As flags do comando, pela ordem declarada. Cada entrada regista uma flag no comando para que aggrega help <command> a apresente como a flag de um comando principal. Um comando sem flags deixa-o vazio. |
Cada entrada de flags declara uma flag:
| Campo | Efeito |
|---|---|
name | O nome longo da flag — o token --name que um operador passa na linha de comandos. Obrigatório em cada entrada. |
shorthand | O alias curto opcional da flag — a forma -x que um operador pode passar em vez do nome longo — como uma única letra ou dígito ASCII. Se ausente, a flag não tem alias curto. |
description | O texto de ajuda da flag, numa linha, mostrado na saída da ajuda do comando. Documentação opcional; o host não o valida nem age com base nele. |
type | O tipo de valor da flag — string, bool ou int — e, por isso, o tipo de flag com que a ajuda a apresenta. Se ausente, é apresentada como flag de string. |
default | O valor predefinido da flag quando o operador não a passa, expresso como string. Para uma flag bool ou int, é um valor desse tipo. Se ausente, a flag não declara valor predefinido. |
Um plugin CLI declara os seus comandos e as respetivas flags em describe(); o host regista exatamente essa superfície e apresenta as flags de cada comando em aggrega help <command> da mesma forma que apresenta as flags de um comando nativo.
O host verifica todas as flags que um plugin declara quando adiciona os comandos do plugin, e um plugin cujas declarações falhem é ignorado em vez de adicionado: nenhum dos seus comandos é registado, um aviso indica o plugin, o comando, a flag e o que está errado nela, e todos os outros comandos — nativos ou de outro plugin — continuam a funcionar. Uma declaração falha quando:
- uma flag não tem nome, ou um comando declara o mesmo nome duas vezes;
- um atalho é algo diferente de uma única letra ou dígito ASCII, ou um comando declara o mesmo atalho para duas flags;
- um nome ou atalho reutiliza uma flag que todos os comandos
aggregajá têm —--help, o seu-h, e as flags globais como--offlinee--config; - um tipo é algo diferente de
string,boolouint; - um valor predefinido não é interpretável como o tipo da flag —
maybepara umbool,threepara umint.
A forma de um único carácter de shorthand e os três valores de type fazem também parte do esquema desta entidade, pelo que uma entidade Plugin que registe qualquer outro valor é recusada quando o catálogo é carregado. Que um nome ou atalho apareça uma vez por comando, que nenhum reutilize uma flag que todos os comandos têm e que um valor predefinido seja interpretável como o seu tipo são verificações feitas apenas pelo host. A verificação cobre se o host consegue declarar uma flag para a ajuda tal como está escrita; não vê se o plugin lê as flags que declara, porque o plugin interpreta os seus próprios argumentos.
metadata: pluginType: clispec: 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: worldInspecionar um Plugin
aggrega inspect <path-to-Plugin.yaml> apresenta um ficheiro Plugin: a sua identidade e o tipo de socket, as capacidades que o seu bloco declara, a tabela de capacidades por export pela ordem do autor, as restrições de runtime e — com --detail — o ponteiro da assinatura e as chaves de configuração do runtime. Um Plugin é endereçável pelo caminho do ficheiro, ou pela sua coordenada <pluginType>/<name> no catálogo. Consulte ../cli/aggrega-inspect.md.
Referências cruzadas
- Guia do programador de plugins Wasm — o fluxo de trabalho completo do autor:
describe(), declarações de capacidades, limites de runtime, ciclo de vida, assinatura, controlo de versões. - Contrato de plugins Wasm — os pontos de socket a que um plugin se liga e as respetivas formas de entrada/saída.
entities/featurerecipe.md— a superfíciepipeline:da FeatureRecipe que referencia um plugin pelo URI da entidade.cli/aggrega-lint.md— o linter de publicação, a grelha de incremento de versão e a aplicação da imutabilidade que regem a publicação de umPlugin.