Plugin
Um Plugin é um plugin WebAssembly endereçado por conteúdo: um artefato .wasm hospedado em OCI, fixado pelo digest sha256, que declara o tipo de socket que implementa, a versão de ABI que tem como alvo, um ponteiro opcional de assinatura e um bloco runtime opcional. A entidade é a superfície de autoria e de metadados de um plugin; a resolução de dependências fixa o artefato pelo digest e a política de confiança por registro verifica sua assinatura no pull. O compilador não interpreta o comportamento do plugin — ele encaminha a referência fixada; o runtime WebAssembly executa os bytes.
Esta página cobre campo a campo a superfície de autoria do catálogo para Plugin. Para o fluxo de trabalho completo do autor — o que é um plugin, o autorrelato describe(), o ciclo de vida publish→pull→build, a assinatura e o versionamento — consulte o guia do desenvolvedor de plugins Wasm. Para os pontos de socket aos quais um plugin se anexa e seus formatos de entrada/saída, consulte o contrato de plugins Wasm.
O papel do Plugin
Um Plugin vincula uma identidade lógica de plugin a um artefato .wasm concreto e aos metadados de capacidades e de runtime de que o host precisa para carregá-lo e executá-lo com segurança. Um passo de pipeline ou um socket de plugin referencia a entidade pelo seu URI; a entidade traz as capacidades declaradas, os limites de runtime e o ponteiro de assinatura, enquanto o digest do conteúdo resolvido fica no lockfile da release. A localização do .wasm é derivada da identidade do plugin — a coordenada endereçável plugin/<pluginType>/<name>, composta por sua vez de metadata.pluginType e do metadata.name simples, mais o registro configurado — e não é um campo escrito pelo autor. A indireção pela entidade é obrigatória — uma referência direta a um .wasm ou a um artefato é rejeitada no carregamento porque nenhuma entidade corresponde a ela.
As declarações de um Plugin são agrupadas por tipo de socket, e é por esse agrupamento que a leitura da entidade começa:
- Um bloco por tipo de socket —
spec.provider,spec.pipelineStep,spec.parser,spec.importer. Um plugin traz o único bloco que seumetadata.pluginTypenomeia, e cada bloco contém uma listacapabilities:— registrada a partir do própriodescribe()do plugin poraggrega plugin gen-catalog— cujo significado pertence apenas a esse bloco: a lista de um provedor nomeia as capacidades que ele atende, a de um passo de pipeline nomeia as capacidades de provedor com as quais seu passo é compatível, e as de um parser e de um importador nomeiam formatos de origem, escritosparse:<format>eimport:<format>. É a contenção que carrega o significado — não é possível chegar a uma entrada de capacidade sem antes ler o bloco que diz de que tipo de afirmação se trata. - Um bloco de provedor traz mais do que sua lista —
spec.providertambém declara como o plugin traduz o tipo Workload, quais anotações nativas da plataforma ele lê e seu contrato de comportamento de renderização (spec.provider.contract: tipos de entrada, montagem de fronteiras, delimitadores de artefatos, reutilização de instâncias). Esses descrevem o comportamento de renderização, e não uma dimensão atendida, e é por isso que ficam ao lado da lista de capacidades do provedor, e não dentro dela. - Um socket transversal não declara capacidades — um plugin
linter,governanceouclinão traz nenhum dos quatro blocos, porque não atende 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 (por exemplo, 1.2.0). Os campos opcionais — description, maintainers, license, repository, home, keywords — seguem a mesma forma que toda entidade de catálogo tem, e metadata não aceita nenhuma outra chave. Uma versão publicada é imutável: republicar uma versão existente é rejeitado no controle de publicação.
metadata.name é simples — não traz nenhum prefixo de socket. A coordenada endereçável do plugin plugin/<pluginType>/<name> é derivada de metadata.pluginType e do metadata.name simples; ela não é escrita no nome.
metadata.pluginType
O tipo de socket que este plugin implementa. Ele 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, extraído da taxonomia de tipos de plugin que o runtime reconhece:
provider— renderiza nós IR em artefatos nativos do provedor.linter— inspeciona o conteúdo escrito 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— desempenha os papéis de governança do pipeline de build. Na construção da topologia, aplica automaticamente labels aos nós do grafo de topologia, retornando documentos JSON Patch que o host aplica a uma projeção do grafo que contém apenas os labels. Na análise estática ou no estágio de renderização, avalia o grafo IR ou os artefatos renderizados e retorna um veredito de aceitação/rejeição; uma regra não cumprida interrompe o build. É o papel ao qual está anexado, e não o seu tipo, que define o que ele pode emitir.parser— analisa um formato de origem externo (HCL, TOML, YAML, JSON, …) em uma árvore JSON estruturada, de modo que um consumidor que precisa ler um formato que o compilador não analisa nativamente trabalhe a partir de uma árvore analisada em vez do texto bruto.importer— transforma uma fonte externa de infraestrutura ou de definição de agentes em rascunhos de arquivos de autoria do Aggrega, anunciando os formatos que trata como capacidadesimport:<format>.cli— contribui com um subcomando de tempo de execuçãoaggrega <cmd>que um operador invoca na linha de comando. Um socket de tempo de execução, distinto dos sockets de renderização e de pipeline do tempo de compilação.
Obrigatório.
spec.abiVersion
A versão de ABI host/guest que o plugin tem como alvo. v1beta1 é o valor aceito; 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 solicita, ou um formato de origem que um build precisa ler. As capacidades de um plugin são registradas dentro do bloco que pertence ao seu tipo de socket, de modo que o bloco em que a lista fica é o que define o significado de suas entradas:
metadata.pluginType | Onde suas capacidades são declaradas | O que uma entrada nomeia |
|---|---|---|
provider | spec.provider.capabilities | Uma capacidade de renderização que este plugin atende, como helm ou compose. |
pipeline-step | spec.pipelineStep.capabilities | Um provedor 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 rascunha entidades, escrito import:<format>. |
linter, governance, cli | — | Nada. Esses sockets não atendem nenhuma capacidade, portanto não trazem nenhum dos quatro blocos. |
Um plugin implementa exatamente um tipo de socket, portanto sua entidade traz um único bloco. A lista é o próprio relato do plugin: aggrega plugin gen-catalog lê o describe() do plugin e grava no bloco cada capacidade que ele informa. Um autor pode restringir a lista antes de publicar, deixando de fora uma capacidade que o plugin informa mas que a entidade publicada não deve oferecer; aggrega validate <entity> --plugin <file.wasm> e aggrega push aceitam uma lista restrita e imprimem um aviso que nomeia cada capacidade informada pelo plugin que a lista deixa de fora. Nenhum dos dois aceita uma lista que nomeie uma capacidade que o plugin não informa: ambos a recusam, nomeando cada uma dessas capacidades e as capacidades que o plugin de fato informa, de modo que uma lista publicada nunca oferece mais do que o plugin fornece. Uma entidade pipeline-step cujo plugin informa helm e helm-chart, listando também compose, é recusada assim:
[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 do socket de provedor para um plugin pluginType: provider: as capacidades que ele atende, como traduz o tipo Workload aggrega.ai/v1beta1, de propriedade da plataforma, quais anotações nativas da plataforma ele lê e seu contrato de comportamento de renderização. O bloco está presente em todo plugin de renderização de provedor e ausente em qualquer outro tipo de plugin. Um provedor que renderiza apenas conteúdo sourced ou de artefatos, sem síntese de Workload, ainda assim carrega o bloco — ele declara ali suas capacidades e seu contrato, e simplesmente omite workloadSchema.
spec.provider.capabilities
As capacidades que este provedor atende — nomes de capacidades como helm ou compose — cuja forma de saída ele renderiza. Um provedor é genérico entre artefatos que compartilham a forma de saída de uma capacidade, não entre todas as capacidades, então a lista nomeia as capacidades que o próprio plugin informa: aggrega plugin gen-catalog a registra 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 registradas.
O destino de provedor solicitado por uma Recipe (spec.capability: helm) é resolvido para o plugin de provedor cuja lista contém esse destino. Quando mais de um plugin de provedor lista o mesmo destino, o workspace escolhe: a seleção plugins.providers na configuração do workspace indica qual plugin usar, é resolvida em aggrega pull e registrada no lockfile. Sem seleção e com exatamente um candidato, esse candidato é usado; sem seleção e com mais de um candidato, o build é interrompido e nomeia cada candidato. A ambiguidade é resolvida por workspace no ponto de uso, e não por uma regra de unicidade válida para todo o catálogo. Uma lista vazia ou ausente não declara nenhuma capacidade, então o plugin não atende nenhum destino.
Um nome de capacidade aqui não contém dois-pontos. O spec.capability de uma Recipe é lido como a capacidade até seus últimos dois-pontos, seguida de um pin de versão, então um nome que os contivesse nunca poderia ser solicitado; um plugin cujo describe() informa um nome assim é recusado ao ser carregado, e nenhuma entidade é gerada a partir dele para publicação. O mesmo vale para as capacidades de provedor que um plugin pipeline-step lista. Os dois-pontos em parse:<format> de um parser e em import:<format> de um importer fazem parte desses nomes e permanecem.
spec.provider.workloadSchema
Uma declaração em JSON Schema 2020-12 que documenta como este provedor traduz o tipo Workload aggrega.ai/v1beta1 em manifestos nativos do provedor. Por convenção, ela é declarada em um provedor que realiza síntese: um provedor assim declara workloadSchema como o contrato de tradução documentado, descrevendo quais campos do Workload o provedor consome, quais conjuntos fechados cada campo do tipo enumeração aceita e quais restrições de intervalo se aplicam.
O corpo é compilado para JSON Schema 2020-12 quando o Plugin é carregado — uma proteção 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 provedor vinculado, não pela presença deste campo: uma Recipe em modo sintetizado vinculada a um provedor que não consegue sintetizar é interrompida de forma explícita no momento da renderização. O catálogo da biblioteca padrão mantém workloadSchema sincronizado com a capacidade do provedor. O campo é o contrato documentado; nada mais o lê. Os próprios corpos de Workload são validados contra o esquema de Workload incorporado, de propriedade da plataforma, e não contra este campo por provedor.
spec.provider.wellKnownAnnotations
Um array ordenado que enumera as chaves de anotação bem conhecidas nativas da plataforma — as que estão sob o namespace reservado aggrega.ai/ — que este provedor lê, junto com o comportamento aplicado quando cada uma está ausente. Cada entrada carrega uma key (a anotação lida pelo provedor, por exemplo aggrega.ai/namespace), um purpose (o que a anotação controla quando está presente), um defaultBehavior opcional (o que o provedor faz quando a anotação está ausente) e um scope opcional que lista onde o provedor 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 do autor.
O campo é a declaração de suporte do provedor, e o compilador o lê de duas maneiras. Uma entrada cujo scope nomeia um tipo de entrada que o contract.inputKinds do próprio bloco não declara contradiz essa declaração, e o Plugin é recusado, com a indicação da chave e do scope. E quando um build renderiza por meio deste provedor, uma anotação aggrega.ai/ que nenhuma entrada cobre em nenhum dos tipos de entrada declarados pela renderização gera um aviso que nomeia a chave, o provedor e esses tipos de entrada; o valor ainda passa inalterado e o build não é interrompido. Se ausente, o campo não declara absolutamente nada, e nenhum aviso desse tipo é emitido para este provedor. A validação do esquema verifica apenas a forma de cada entrada (a chave fica sob o namespace aggrega.ai/, purpose está presente); ela é distinta da verificação em tempo de execução que rege a vinculação de um valor ao namespace 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 provedor e o conteúdo de workloadSchema que os provedores da biblioteca padrão fornecem 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 provedor não lê nenhuma das chaves de anotação bem conhecidas nativas da plataforma. É uma declaração de suporte que não cobre nenhuma chave, e ela diz algo que omitir tanto este campo quanto wellKnownAnnotations não diz: uma declaração ausente é silêncio, enquanto esta é a afirmação do próprio provedor de que não lê nada sob o namespace reservado aggrega.ai/. Um build que renderiza por meio de um provedor assim emite um aviso para cada anotação aggrega.ai/ que chega à renderização, nomeando a chave, o provedor e os tipos de entrada declarados pela renderização; o valor ainda passa inalterado e o build não é interrompido.
Somente true pode ser escrito, então omitir o campo continua sendo a única forma de não dizer nada. Ele não pode ser escrito junto com wellKnownAnnotations: um provedor que lê algumas das chaves as lista ali em vez disso. Ambas as recusas são em nível de esquema, então o Plugin é recusado quando é lido.
spec: provider: capabilities: - terraform readsNoWellKnownAnnotations: trueO provedor terraform da biblioteca padrão o declara; ../providers/terraform.md explica o que isso significa para uma Release renderizada por meio dele.
spec.provider.contract
O contrato de comportamento de renderização em tempo de compilação autodeclarado por um plugin de renderização de provedor: os tipos de entrada que ele renderiza, como monta a saída por nó de um grupo de despacho, o par de delimitadores de template que aplica aos arquivos de artefato importados, se uma única instância carregada pode atender a todas as travessias, se respeita entradas de omissão e se aceita os arquivos que uma Recipe contribui para a saída compartilhada de sua fronteira. Ele fica ao lado de capabilities no mesmo bloco, mas responde a uma pergunta diferente: a lista de capacidades diz quais capacidades este plugin atende, enquanto o contrato diz como ele as renderiza. aggrega plugin gen-catalog o registra a partir do autorrelato describe() do próprio plugin, e o host o confronta com esse autorrelato na publicação e no carregamento; uma divergência interrompe o processo. Se ausente, não declara nenhum contrato de comportamento de renderização, e a verificação cruzada compara apenas as declarações por export. Todos os campos são opcionais.
| Campo | Efeito |
|---|---|
inputKinds | Quais dos três tipos de entrada da Recipe o plugin renderiza, cada um uma declaração booleana independente: sourced (um conjunto de arquivos de origem — um chart, um módulo, um arquivo compose), synthesized (um Workload sintetizado) e artifactsStandalone (um nó independente que carrega documentos de artefato importados e nenhuma origem nem workload). O host verifica o tipo de entrada de um nó em relação a esse conjunto. |
boundaryAssembly | Como o plugin combina a saída de renderização por nó de um grupo de despacho: none grava a saída de cada nó diretamente no caminho de despacho; merge funde os fragmentos por nó em um único documento; nest coloca a saída de cada nó em sua própria posição dentro de uma estrutura guarda-chuva. Se ausente, não carrega nenhuma declaração de montagem. |
artifactDelimiters | O par de delimitadores de template Go que o plugin aplica aos arquivos de artefato importados, como left e right. Se ausente, vale o par padrão {{/}}; um plugin cuja sintaxe de destino colide com esse par declara um par alternativo (por exemplo [[/]]). |
reusableInstance | Se uma única instância carregada do plugin pode atender a todas as travessias de renderização, montagem e validação de um build, em vez de uma instância nova por travessia. Declarado true somente quando o plugin não mantém estado entre travessias, de modo que uma única instância produz saída idêntica byte a byte, seja reutilizada ou recém-carregada. Se ausente (false), uma instância nova é carregada por travessia, isolando um plugin que mantém estado por construção. aggrega build --verify-determinism comprova que a saída de um plugin reutilizável é estável renderizando cada nó duas vezes e interrompendo em qualquer diferença. |
omits | Se o plugin respeita entradas de omissão — entradas que nomeiam unidades renderizadas a deixar de fora da saída de um nó: ele deixa de fora do que renderiza toda unidade com a qual uma entrada corresponde, e informa quantas unidades cada entrada encontrou. O valor registra a declaração que o describe() do plugin informa, então true só é correto para um plugin que a informa, e um valor que difere do informado interrompe o processo. Se ausente (false), não declara tal suporte. |
boundaryArtifacts | Se o destino do plugin aceita os arquivos que uma Recipe contribui para a saída compartilhada da fronteira em que ele renderiza, sob o spec.boundary.artifacts da Recipe: o compilador grava cada um desses arquivos uma única vez, ao lado do que o plugin monta para a fronteira, e o destino o lê como parte dessa saída. O valor registra a declaração que o describe() do plugin informa, e um valor que difere do informado interrompe o processo. Se ausente (false), não declara tal suporte, e uma Recipe que declara o bloco para este plugin é recusada antes que qualquer coisa seja renderizada. |
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 etapa de pipeline para um plugin pluginType: pipeline-step. Seu único campo, capabilities, nomeia os provedores cuja saída renderizada a etapa do plugin sabe transformar — nomes de capacidades como helm ou compose. Uma etapa é escrita para a forma de saída de um provedor de cada vez, então a lista nomeia os provedores que o próprio plugin informa; as entradas mantêm a ordem em que são registradas. O bloco só está presente em plugins de etapa de pipeline.
O bloco é o registro, legível no catálogo, dessa declaração: aggrega plugin gen-catalog o registra a partir do autorrelato describe() do próprio plugin, e um autor pode restringi-lo antes de publicar. A aplicação lê a mesma declaração a partir do plugin: quando uma etapa toca um escopo, o build é interrompido, a menos que o provedor que renderiza os documentos desse escopo esteja entre os que o plugin declara. Uma lista vazia ou ausente não declara nenhuma compatibilidade, então nenhum escopo admite a etapa.
metadata: pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm - composespec.parser
O bloco de parser para um plugin pluginType: parser. Seu único campo, capabilities, nomeia os formatos de origem que o plugin transforma em uma árvore estruturada canônica, cada um escrito parse:<format>. O prefixo faz parte da entrada, então um plugin que lê vários formatos lista uma entrada por formato. aggrega plugin gen-catalog registra a lista a partir do describe() do próprio plugin, um autor pode restringi-la antes de publicar, e as entradas mantêm a ordem em que são registradas. O bloco só está presente em plugins de parser.
Um formato solicitado é resolvido 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 de um plugin de parser é interrompido como ambíguo, nomeando os candidatos — não há fallback, porque um parser não tem um padrão sem configuração ao qual recorrer. Uma lista vazia ou ausente não declara nenhum formato, então 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 importer para um plugin pluginType: importer. Seu campo capabilities nomeia os formatos de origem externos que o plugin transforma em rascunhos de arquivos de autoria do Aggrega, cada um escrito import:<format>. O prefixo faz parte da entrada, então um plugin que trata vários formatos lista uma entrada por formato. aggrega plugin gen-catalog registra a lista a partir do describe() do próprio plugin, um autor pode restringi-la antes de publicar, e as entradas mantêm a ordem em que são registradas. O bloco só está presente em plugins de importer.
Um formato de importação solicitado é resolvido para o importer cuja lista contém a entrada correspondente. Um formato que nenhum importer anuncia interrompe a importação, e um formato anunciado por mais de um plugin de importer é interrompido como ambíguo, nomeando os candidatos, a menos que uma entrada plugins.importer na configuração do workspace vincule um deles, que passa então a ser o que é executado. Uma lista vazia ou ausente não declara nenhum formato, então o plugin não importa nada.
Seu campo detect registra as assinaturas pelas quais uma origem desses formatos é reconhecida quando uma importação não nomeia nenhum formato. Ele pertence à máquina, como os registros de funções do host e de comandos: é derivado do que o describe() do plugin informa quando a entidade é gerada a partir do plugin, na ordem em que o plugin declara as assinaturas, e um autor não o escreve. Cada assinatura nomeia:
syntax— o formato sintático em que a origem é analisada, o formato que um plugin de parser anuncia comoparse:<syntax>, comojsonouyaml.files— padrões opcionais de nome de arquivo, comparados com o final do nome da origem: um padrão de um único segmento com o nome do próprio arquivo, um de vários segmentos separados por barras com a mesma quantidade de segmentos finais do seu caminho, de modo que.vscode/mcp.jsoncorresponde a um arquivo chamadomcp.jsonem um diretório chamado.vscode.*,?e[...]correspondem dentro de um segmento. Se ausente, a assinatura se aplica a uma origem que é um único arquivo, seja qual for seu nome, e a nenhum arquivo de um diretório. Os padrões das assinaturas de um importer também são o que decide quais arquivos de um diretórioaggrega importentrega a ele.match— os predicados que a árvore analisada deve satisfazer, todos eles. Cada um tem umpath, chaves unidas por pontos a partir da raiz da árvore, em que um segmento de número inteiro seleciona uma posição de array; umis, um entrepresent,absent,object,array,string,numbereboolean; e, opcionalmente,equals, uma string que o valor deve ser, ouprefix, uma string com a qual ele deve começar — no máximo um dos dois.
Quando uma importação não nomeia nenhum formato, as assinaturas de cada importer que o catálogo do workspace contém — todas as versões incluídas — e dos importers principais 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ê, por meio do parser que o catálogo do workspace fornece para essa sintaxe — ou, para uma sintaxe para a qual o catálogo não fornece nenhum parser, aquele que o próprio compilador inclui — e uma origem que não pode ser analisada em uma sintaxe não corresponde a nenhuma assinatura que a nomeie. Um diretório é comparado por meio de seus arquivos: cada assinatura é testada com os arquivos do diretório que seus padrões selecionam, em ordem de nome, e uma assinatura que não declara nenhum padrão não se aplica a nenhum deles. Uma origem com a qual uma assinatura corresponde é reconhecida como cada formato que seu importer anuncia. Quando exatamente um formato é reconhecido, a origem é lida nesse formato. Uma origem com a qual nenhuma assinatura corresponde é recusada, com o pedido do formato e a indicação dos formatos que os importers anunciam — ou, para um diretório, com o pedido de um de seus arquivos isoladamente ou de um formato cujo importer declare padrões de arquivo, indicando apenas esses; uma origem reconhecida como mais de um formato é recusada nomeando-os, com a condição More than one importer recognises the source (Mais de um importer reconhece a origem). Assim, um importer que anuncia mais de um formato tem toda origem com a qual suas assinaturas correspondem recusada como ambígua, e um importer cujas origens devam ser reconhecidas atende um único formato.
Onde a entidade registra detect, ele deve ser igual ao que o describe() do plugin informa, assinatura por assinatura e na mesma ordem: o carregamento do importer recusa um plugin cujo relato difere, nomeando importer.detect, e o mesmo faz sua publicação. Uma entidade que não registra detect não declara nada e não é comparada, então carrega quaisquer assinaturas que o describe() de seu plugin informe, e os formatos de seu importer passam a ser alcançados apenas nomeando-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 — ele registra, para quem lê o catálogo, onde a assinatura está e como foi produzida; ele não admite o plugin por si só. A verificação que se aplica é a política de confiança por registry aplicada no pull: uma assinatura é obtida como referrer OCI, verificada em relação às identidades confiáveis ou à chave fixada do registry, e registrada como um fato verificado no lockfile. Um registry que exige assinaturas interrompe o pull quando uma assinatura exigida está ausente, não é confiável 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 pela enumeração de referrers no pull, em vez de ser fixada aqui.publicKeyRef— um ponteiro para a chave pública com a qual a assinatura foi produzida, para uma assinatura com chave. A ausência indica uma assinatura sem chave (identidade OIDC), verificada em relação às identidades confiáveis do registry.
spec.runtime
Restrições de execução opcionais que o host aplica ao carregar e executar o plugin. O acesso de rede de saída não é um campo de autoria: um plugin nunca acessa a rede em tempo de build — a fronteira ahead-of-time — então não há aqui nenhum campo de lista de hosts permitidos. O conteúdo remoto de que um plugin precisa chega pelo canal de entrada externa mediado pelo host e fixado por digest, registrado no lockfile da Release, nunca por acesso de rede ambiente; o guia do desenvolvedor documenta o wrapper de busca 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 padrão da plataforma, então um carregamento nunca é ilimitado; uma anexação que precisa de mais aumenta este valor. |
timeoutMs | Limita por quanto tempo o próprio código do plugin pode ser executado durante uma chamada, em milissegundos, sem contar o tempo gasto dentro das funções do host que ele chama. No Linux, a medida é o tempo de processador, então o tempo gasto esperando por um processador em uma máquina ocupada não conta; em outros sistemas, é o tempo decorrido. A primeira chamada a um plugin recém-carregado também conta a própria inicialização do plugin. Zero ou ausente aplica o limite padrão da plataforma, então uma chamada nunca é impossível de cancelar; uma anexação que é executada por mais tempo aumenta este valor. |
hostFunctions | Os nomes das funções do host que o plugin importa. Derivado pela máquina e somente leitura — não o escreva você mesmo: aggrega plugin sync lê as funções do host da seção de importação do .wasm e registra este campo, a publicação recusa um registro que difere do binário, e o valor reflete o binário publicado, validado em relação à lista de permissões curada. O host registra exatamente esse conjunto, dando a cada plugin a superfície de host de privilégio mínimo de que seu binário precisa; o pull deriva novamente o carimbo e o verifica em relação ao binário. Para 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 na inicialização, como pares chave/valor de string para string. As entradas preservam a ordem do autor para que o registro emitido seja idêntico byte a byte entre execuções. Se ausente, a configuração vazia padrão do runtime permanece em vigor. |
spec.exports
Os exports que o plugin oferece, cada um com sua capacidade declarada, como uma lista ordenada que preserva a ordem do autor. Um export é um ponto de entrada nomeado para o qual o host despacha (por exemplo render_node, lint_naming, step); o bloco de capacidade por export indica o que esse export faz, conforme aggrega plugin gen-catalog o registra a partir do autorrelato describe() do plugin, e o host o confronta com esse autorrelato na publicação e no carregamento. Se ausente, não declara nenhuma superfície de export escrita pelo autor.
| Campo | Efeito |
|---|---|
name | O nome ABI do export — o nome para o qual o host despacha. Obrigatório para cada entrada. |
operates | A operação de pipeline que o export executa: patch (modificar um documento renderizado existente) ou emit (adicionar um novo documento). O host confronta o valor com o autorrelato do plugin; é uma declaração de capacidade validada, não um seletor de despacho — a operação que uma etapa executa é carregada pelo resultado retornado pelo guest. Se ausente, não carrega nenhuma declaração de operação. |
scope | A raiz de documentos sobre a qual o export opera: own (os próprios documentos renderizados do nó) ou host (os documentos do componente ao qual uma FeatureRecipe de escopo de componente está anexada). O host lê o escopo declarado antes da etapa para aplicar a compatibilidade de provedor em relação ao provedor que renderiza esse escopo. Se ausente, o padrão é own. |
selector | Uma descrição livre e legível por pessoas daquilo sobre o que o export atua (por exemplo workloads carrying a pod template). Documentação para quem lê o 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. Gerenciado pela máquina e somente leitura — não o escreva. aggrega plugin sync lê a superfície de comandos do autorrelato describe() do plugin e a registra aqui, para que os comandos que um plugin CLI instala possam ser lidos a partir da entidade sem carregar o .wasm. Um plugin que não seja cli não contribui comandos e registra uma lista vazia. O host instala exatamente este conjunto; um conjunto registrado que diverge do autorrelato describe() do plugin interrompe o carregamento, e a publicação recusa um conjunto fora de sincronia com o binário e orienta o autor a registrá-lo novamente. Para ressincronizar o registro 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 registra — 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 fornece vários comandos possa rotear de acordo com o comando chamado. Obrigatório em cada entrada. |
description | O texto de ajuda curto, de uma linha, do comando, exibido na listagem de comandos e na saída de ajuda. Apenas documentação; o host não age com base nele. |
flags | As flags do comando, na ordem declarada. Cada entrada registra uma flag no comando para que aggrega help <command> a exiba como a flag de um comando nativo. Um comando sem flags o deixa 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 comando. Obrigatório em cada entrada. |
shorthand | O alias curto opcional da flag — a forma -x que um operador pode passar no lugar 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 de uma linha da flag, exibido na saída de 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 o tipo de flag como o qual a ajuda a exibe. Se ausente, ela é exibida como uma flag de string. |
default | O valor padrão 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 padrão. |
Um plugin CLI declara seus comandos e as respectivas flags em describe(); o host registra exatamente essa superfície e exibe as flags de cada comando em aggrega help <command> da mesma forma que exibe as flags de um comando integrado.
O host verifica cada flag que um plugin declara ao adicionar os comandos do plugin, e um plugin cujas declarações falham é ignorado em vez de adicionado: nenhum de seus comandos é registrado, um aviso indica o plugin, o comando, a flag e o que há de errado com ela, e todos os outros comandos — integrados ou de outro plugin — continuam funcionando. Uma declaração falha quando:
- uma flag não tem nome, ou um comando declara o mesmo nome duas vezes;
- uma forma abreviada é algo diferente de uma única letra ou dígito ASCII, ou um comando declara a mesma forma abreviada para duas flags;
- um nome ou forma abreviada reutiliza uma flag que todo comando
aggregajá tem —--help, seu-h, e as flags globais como--offlinee--config; - um tipo é algo diferente de
string,boolouint; - um valor padrão não pode ser interpretado como o tipo da flag —
maybepara umbool,threepara umint.
A forma de um único caractere de shorthand e os três valores de type também fazem parte do schema desta entidade, de modo que uma entidade Plugin que registre qualquer outro valor é recusada quando o catálogo é carregado. Que um nome ou forma abreviada apareça uma vez por comando, que nenhum reutilize uma flag que todo comando tem e que um valor padrão seja interpretável como seu tipo é verificado apenas pelo host. A verificação cobre se o host consegue declarar uma flag para a ajuda tal como está escrita; ela não vê se o plugin lê as flags que declara, porque o plugin interpreta os 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> exibe um arquivo Plugin: sua identidade e tipo de socket, as capacidades que seu bloco declara, a tabela de capacidades por export na ordem do autor, as restrições de runtime e — com --detail — o ponteiro de assinatura e as chaves de configuração de runtime. Um Plugin é endereçável por caminho de arquivo ou por sua coordenada <pluginType>/<name> no catálogo. Consulte ../cli/aggrega-inspect.md.
Referências cruzadas
- Guia do desenvolvedor de plugins Wasm — o fluxo de trabalho completo do autor:
describe(), declarações de capacidade, limites de runtime, ciclo de vida, assinatura, versionamento. - Contrato de plugins Wasm — os pontos de socket aos quais um plugin se conecta e seus formatos de entrada e saída.
entities/featurerecipe.md— a superfíciepipeline:da FeatureRecipe que referencia um plugin por URI de entidade.cli/aggrega-lint.md— o linter de publicação, os critérios de incremento de versão e a aplicação de imutabilidade que regem a publicação de umPlugin.