Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Plugin

Un Plugin es un plugin WebAssembly direccionado por contenido: un artefacto .wasm alojado en OCI, fijado por su digest sha256, que declara el tipo de socket que implementa, la versión de ABI a la que se dirige, un puntero de firma opcional y un bloque runtime opcional. La entidad es la superficie de autoría y de metadatos de un plugin; la resolución de dependencias fija el artefacto por su digest y la política de confianza por registro verifica su firma en el pull. El compilador no interpreta el comportamiento del plugin — enruta la referencia fijada; el runtime de WebAssembly ejecuta los bytes.

Esta página cubre campo por campo la superficie de autoría del catálogo para Plugin. Para el flujo de trabajo completo del autor — qué es un plugin, el autoinforme describe(), el ciclo de vida publish→pull→build, la firma y el versionado — consulta la guía para desarrolladores de plugins Wasm. Para los puntos de socket a los que se vincula un plugin y sus formas de entrada/salida, consulta el contrato de plugins Wasm.

La función del Plugin

Un Plugin vincula una identidad lógica de plugin a un artefacto .wasm concreto y a los metadatos de capacidades y de runtime que el host necesita para cargarlo y ejecutarlo de forma segura. Un paso de pipeline o un socket de plugin hace referencia a la entidad por su URI; la entidad contiene las capacidades declaradas, los límites de runtime y el puntero de firma, mientras que el digest del contenido resuelto se encuentra en el lockfile de la release. La ubicación del .wasm se deriva de la identidad del plugin — la coordenada direccionable plugin/<pluginType>/<name>, compuesta a su vez de metadata.pluginType y del metadata.name simple, más el registro configurado — y no es un campo que se escriba. La indirección a través de la entidad es obligatoria — una referencia directa a un .wasm o a un artefacto se rechaza al cargar porque ninguna entidad le corresponde.

Las declaraciones de un Plugin se agrupan por tipo de socket, y la lectura de la entidad empieza por esa agrupación:

  • Un bloque por tipo de socket — spec.provider, spec.pipelineStep, spec.parser, spec.importer. Un plugin contiene el único bloque que nombra su metadata.pluginType, y cada bloque contiene una lista capabilities: — registrada a partir del propio describe() del plugin por aggrega plugin gen-catalog — cuyo significado pertenece solo a ese bloque: la lista de un proveedor nombra las capacidades que sirve, la de un paso de pipeline nombra las capacidades de proveedor con las que su paso es compatible, y las de un parser y un importador nombran formatos de origen, escritos parse:<format> e import:<format>. Es la contención lo que aporta el significado — no se puede llegar a una entrada de capacidad sin leer primero el bloque que dice de qué tipo de afirmación se trata.
  • Un bloque de proveedor contiene más que su lista — spec.provider declara también cómo traduce el plugin el tipo Workload, qué anotaciones nativas de la plataforma lee y su contrato de comportamiento de renderizado (spec.provider.contract: tipos de entrada, ensamblado de límites, delimitadores de artefactos, reutilización de instancias). Estos describen el comportamiento de renderizado en lugar de una dimensión servida, por lo que se sitúan junto a la lista de capacidades del proveedor y no dentro de ella.
  • Un socket transversal no declara capacidades — un plugin linter, governance o cli no contiene ninguno de los cuatro bloques, porque no sirve ninguna dimensión de renderizado ni ningún formato de origen.
apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
# capabilities is recorded by `aggrega plugin gen-catalog` from the plugin's describe(); an author may narrow it.
capabilities:
- helm
- compose
signature:
type: sigstore-cosign
runtime:
maxMemoryPages: 256
timeoutMs: 5000
# hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it.
exports:
- name: fetch
operates: emit
scope: own
selector: external-secret resources for the bound credential

metadata

Metadatos estándar del catálogo. name, version y pluginType son obligatorios; version es una Semantic Version estricta (p. ej., 1.2.0). Los campos opcionales — description, maintainers, license, repository, home, keywords — siguen la misma forma que tiene toda entidad de catálogo, y metadata no acepta ninguna otra clave. Una versión publicada es inmutable: volver a publicar una versión existente se rechaza en el control de publicación.

metadata.name es simple — no lleva ningún prefijo de socket. La coordenada direccionable del plugin plugin/<pluginType>/<name> se deriva de metadata.pluginType y del metadata.name simple; no se escribe en el nombre.

metadata.pluginType

El tipo de socket que implementa este plugin. Se sitúa en el bloque de direccionamiento junto a name y version porque forma parte de la identidad del plugin: aporta el segmento <pluginType> de la coordenada derivada plugin/<pluginType>/<name>. Un plugin implementa exactamente un tipo de socket, tomado de la taxonomía de tipos de plugin que reconoce el runtime:

  • provider — renderiza los nodos IR en artefactos nativos del proveedor.
  • linter — inspecciona el contenido escrito y emite diagnósticos.
  • pipeline-step — un paso en el pipeline: de una FeatureRecipe o de una Recipe que aplica parches al conjunto de documentos renderizados.
  • governance — cumple las funciones de gobernanza de la pipeline de build. En la construcción de la topología asigna automáticamente etiquetas a los nodos del grafo de topología, devolviendo documentos JSON Patch que el host aplica a una proyección del grafo que contiene solo las etiquetas. En el análisis estático o en la etapa de renderizado evalúa el grafo IR o los artefactos renderizados y devuelve un veredicto de aceptación o rechazo; una regla incumplida detiene la compilación. Lo que puede emitir lo determina la función a la que está vinculado, no su tipo.
  • parser — analiza un formato de origen externo (HCL, TOML, YAML, JSON, …) y lo convierte en un árbol JSON estructurado, de modo que un consumidor que necesita leer un formato que el compilador no analiza de forma nativa trabaja a partir de un árbol analizado en lugar del texto sin procesar.
  • importer — convierte una fuente externa de infraestructura o de definición de agentes en borradores de archivos de autoría de Aggrega, anunciando los formatos que maneja como capacidades import:<format>.
  • cli — aporta un subcomando de tiempo de ejecución aggrega <cmd> que un operador invoca en la línea de comandos. Un socket de tiempo de ejecución, distinto de los sockets de renderizado y de pipeline del tiempo de compilación.

Obligatorio.

spec.abiVersion

La versión de ABI host/guest a la que se dirige el plugin. v1beta1 es el valor aceptado; una nueva revisión de la ABI añade uno. Obligatorio.

Declarar capacidades: un bloque por tipo de socket

Una capacidad es lo que un consumidor pide a un plugin — una capacidad de renderizado que solicita una Recipe, o un formato de origen que una compilación necesita leer. Las capacidades de un plugin se registran dentro del bloque que corresponde a su tipo de socket, por lo que el bloque en el que está la lista es lo que fija el significado de sus entradas:

metadata.pluginTypeDónde se declaran sus capacidadesQué nombra una entrada
providerspec.provider.capabilitiesUna capacidad de renderizado que sirve este plugin, como helm o compose.
pipeline-stepspec.pipelineStep.capabilitiesUn proveedor con cuya salida renderizada es compatible el paso de este plugin.
parserspec.parser.capabilitiesUn formato de origen que lee este plugin, escrito parse:<format>.
importerspec.importer.capabilitiesUn formato de origen externo a partir del cual este plugin redacta borradores de entidades, escrito import:<format>.
linter, governance, cli—Nada. Estos sockets no sirven ninguna capacidad, por lo que no contienen ninguno de los cuatro bloques.

Un plugin implementa exactamente un tipo de socket, por lo que su entidad contiene un solo bloque. La lista es el propio informe del plugin: aggrega plugin gen-catalog lee el describe() del plugin y escribe en el bloque cada capacidad que este informa. Un autor puede restringir la lista antes de publicar, omitiendo una capacidad que el plugin informa pero que la entidad publicada no debe ofrecer; aggrega validate <entity> --plugin <file.wasm> y aggrega push aceptan una lista restringida e imprimen un aviso que nombra cada capacidad informada por el plugin que la lista omite. Ninguno de los dos acepta una lista que nombre una capacidad que el plugin no informa: ambos la rechazan, nombrando cada una de esas capacidades y las capacidades que el plugin sí informa, de modo que una lista publicada nunca ofrece más de lo que el plugin proporciona. Una entidad pipeline-step cuyo plugin informa helm y helm-chart, y que además enumera compose, se rechaza así:

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

Un consumidor resuelve exactamente contra lo que está enumerado.

spec.provider

El bloque del socket de proveedor para un plugin pluginType: provider: las capacidades que sirve, cómo traduce el tipo Workload aggrega.ai/v1beta1, propiedad de la plataforma, qué anotaciones nativas de la plataforma lee y su contrato de comportamiento de renderizado. El bloque está presente en todo plugin de renderizado de proveedor y ausente en cualquier otro tipo de plugin. Un proveedor que solo renderiza contenido sourced o de artefactos, sin síntesis de Workload, también lleva el bloque — declara allí sus capacidades y su contrato, y simplemente omite workloadSchema.

spec.provider.capabilities

Las capacidades que sirve este proveedor — nombres de capacidades como helm o compose — cuya forma de salida renderiza. Un proveedor es genérico entre los artefactos que comparten la forma de salida de una capacidad, no entre todas las capacidades, así que la lista nombra las capacidades que el propio plugin informa: aggrega plugin gen-catalog la registra a partir del describe() del plugin, y un autor puede restringirla antes de publicar. Las entradas conservan el orden en que se registran.

El destino de proveedor que solicita una Recipe (spec.capability: helm) se resuelve en el plugin de proveedor cuya lista contiene ese destino. Cuando más de un plugin de proveedor lista el mismo destino, elige el espacio de trabajo: la selección plugins.providers en la configuración del espacio de trabajo indica qué plugin usar, se resuelve en aggrega pull y se registra en el lockfile. Sin selección y con exactamente un candidato, se usa ese candidato; sin selección y con más de un candidato, la compilación se detiene y nombra a cada candidato. La ambigüedad se resuelve por espacio de trabajo en el punto de uso, en lugar de mediante una regla de unicidad para todo el catálogo. Una lista vacía o ausente no declara ninguna capacidad, así que el plugin no sirve ningún destino.

Un nombre de capacidad aquí no lleva dos puntos. El spec.capability de una Recipe se lee como la capacidad hasta sus últimos dos puntos, seguida de un pin de versión, así que un nombre que los contuviera nunca podría solicitarse; un plugin cuyo describe() informa un nombre así se rechaza al cargarse, y no se genera a partir de él ninguna entidad para publicar. Lo mismo vale para las capacidades de proveedor que lista un plugin pipeline-step. Los dos puntos de parse:<format> de un parser y de import:<format> de un importer forman parte de esos nombres y se mantienen.

spec.provider.workloadSchema

Una declaración en JSON Schema 2020-12 que documenta cómo este proveedor traduce el tipo Workload aggrega.ai/v1beta1 a manifiestos nativos del proveedor. Por convención se declara en un proveedor que sintetiza: un proveedor así declara workloadSchema como el contrato de traducción documentado, describiendo qué campos del Workload consume el proveedor, qué conjuntos cerrados acepta cada campo de tipo enumeración y qué restricciones de rango se aplican.

El cuerpo se compila a JSON Schema 2020-12 cuando se carga el Plugin — una barrera estructural que rechaza un esquema mal formado en la carga y no en el renderizado. Si una Recipe workload: está soportada lo determina la capacidad de síntesis del proveedor vinculado, no la presencia de este campo: una Recipe en modo sintetizado vinculada a un proveedor que no puede sintetizar se detiene de forma explícita en el momento del renderizado. El catálogo de la biblioteca estándar mantiene workloadSchema sincronizado con la capacidad del proveedor. El campo es el contrato documentado; nada más lo lee. Los propios cuerpos de Workload se validan contra el esquema de Workload incrustado, propiedad de la plataforma, no contra este campo por proveedor.

spec.provider.wellKnownAnnotations

Un array ordenado que enumera las claves de anotación conocidas nativas de la plataforma — las que están bajo el espacio de nombres reservado aggrega.ai/ — que lee este proveedor, junto con el comportamiento que se aplica cuando cada una está ausente. Cada entrada lleva una key (la anotación que lee el proveedor, p. ej. aggrega.ai/namespace), un purpose (lo que controla la anotación cuando está presente), un defaultBehavior opcional (lo que hace el proveedor cuando la anotación está ausente) y un scope opcional que lista dónde lee el proveedor la clave — sourced, synthesized o artifactsStandalone, los tipos de entrada de la Recipe, o boundary para una clave que se lee una vez por frontera. key y purpose son obligatorios; las entradas conservan el orden del autor.

El campo es la declaración de soporte del proveedor, y el compilador lo lee de dos maneras. Una entrada cuyo scope nombra un tipo de entrada que el contract.inputKinds del propio bloque no declara contradice esa declaración, y el Plugin se rechaza, indicando la clave y el scope. Y cuando una compilación renderiza a través de este proveedor, una anotación aggrega.ai/ que ninguna entrada cubre en ninguno de los tipos de entrada que declara el renderizado produce una advertencia que nombra la clave, el proveedor y esos tipos de entrada; el valor sigue pasando sin cambios y la compilación no se detiene. Si está ausente, el campo no declara nada en absoluto, y no se emite ninguna advertencia de ese tipo para este proveedor. La validación del esquema solo comprueba la forma de cada entrada (la clave está bajo el espacio de nombres aggrega.ai/, purpose está presente); es distinta de la comprobación en tiempo de ejecución que rige la vinculación de un valor en el espacio de nombres reservado.

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

Los conjuntos de anotaciones por proveedor y el contenido de workloadSchema que incluyen los proveedores de la biblioteca estándar están documentados en ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md y ../providers/compose.md.

spec.provider.readsNoWellKnownAnnotations

Declara que este proveedor no lee ninguna de las claves de anotación conocidas nativas de la plataforma. Es una declaración de soporte que no cubre ninguna clave, y dice algo que omitir tanto este campo como wellKnownAnnotations no dice: una declaración ausente es silencio, mientras que esta es la afirmación del propio proveedor de que no lee nada bajo el espacio de nombres reservado aggrega.ai/. Una compilación que renderiza a través de un proveedor así advierte de cada anotación aggrega.ai/ que llega al renderizado, nombrando la clave, el proveedor y los tipos de entrada que declara el renderizado; el valor sigue pasando sin cambios y la compilación no se detiene.

Solo puede escribirse true, así que omitir el campo sigue siendo la única manera de no decir nada. No puede escribirse junto con wellKnownAnnotations: un proveedor que lee algunas de las claves las lista allí en su lugar. Ambos rechazos son a nivel de esquema, así que el Plugin se rechaza cuando se lee.

spec:
provider:
capabilities:
- terraform
readsNoWellKnownAnnotations: true

El proveedor terraform de la biblioteca estándar lo declara; ../providers/terraform.md explica qué significa eso para una Release renderizada a través de él.

spec.provider.contract

El contrato de comportamiento de renderizado en tiempo de compilación que declara por sí mismo un plugin de renderizado de proveedor: los tipos de entrada que renderiza, cómo ensambla la salida por nodo de un grupo de despacho, el par de delimitadores de plantilla que aplica a los archivos de artefacto importados, si una única instancia cargada puede servir a todos los cruces, si respeta las entradas de omisión y si acepta los archivos que una Recipe aporta a la salida compartida de su frontera. Se sitúa junto a capabilities en el mismo bloque, pero responde a una pregunta distinta: la lista de capacidades dice qué capacidades sirve este plugin, mientras que el contrato dice cómo las renderiza. aggrega plugin gen-catalog lo registra a partir del autoinforme describe() del propio plugin, y el host lo contrasta con ese autoinforme al publicar y al cargar; una discrepancia provoca la detención. Si está ausente, no declara ningún contrato de comportamiento de renderizado, y la comprobación cruzada solo compara las declaraciones por export. Todos los campos son opcionales.

CampoEfecto
inputKindsCuáles de los tres tipos de entrada de la Recipe renderiza el plugin, cada uno una declaración booleana independiente: sourced (un conjunto de archivos fuente — un chart, un módulo, un archivo compose), synthesized (un Workload sintetizado) y artifactsStandalone (un nodo independiente que lleva documentos de artefacto importados y ni fuente ni workload). El host comprueba el tipo de entrada de un nodo contra este conjunto.
boundaryAssemblyCómo combina el plugin la salida de renderizado por nodo de un grupo de despacho: none escribe la salida de cada nodo directamente en la ruta de despacho; merge fusiona los fragmentos por nodo en un único documento; nest coloca la salida de cada nodo en su propia posición dentro de una estructura paraguas. Si está ausente, no lleva ninguna declaración de ensamblado.
artifactDelimitersEl par de delimitadores de plantilla de Go que el plugin aplica a los archivos de artefacto importados, como left y right. Si está ausente, se usa el par predeterminado {{/}}; un plugin cuya sintaxis de destino colisiona con ese par declara un par alternativo (por ejemplo [[/]]).
reusableInstanceSi una única instancia cargada del plugin puede servir a todos los cruces de renderizado, ensamblado y validación de una compilación, en lugar de una instancia nueva por cruce. Se declara true solo cuando el plugin no conserva estado entre cruces, de modo que una única instancia produce una salida idéntica byte a byte, tanto si se reutiliza como si se carga de nuevo. Si está ausente (false), se carga una instancia nueva por cruce, lo que aísla a un plugin que conserva estado por construcción. aggrega build --verify-determinism demuestra que la salida de un plugin reutilizable es estable renderizando cada nodo dos veces y deteniéndose ante cualquier diferencia.
omitsSi el plugin respeta las entradas de omisión — entradas que nombran unidades renderizadas que deben quedar fuera de la salida de un nodo: deja fuera de lo que renderiza toda unidad con la que coincide una entrada, e informa de cuántas unidades coincidieron con cada entrada. El valor registra la declaración que informa el describe() del plugin, así que true solo es correcto para un plugin que la informa, y un valor que difiere del informe provoca la detención. Si está ausente (false), no declara tal soporte.
boundaryArtifactsSi el destino del plugin acepta los archivos que una Recipe aporta a la salida compartida de la frontera en la que renderiza, bajo el spec.boundary.artifacts de la Recipe: el compilador escribe cada uno de esos archivos una sola vez, junto a lo que el plugin ensambla para la frontera, y el destino lo lee como parte de esa salida. El valor registra la declaración que informa el describe() del plugin, y un valor que difiere del informe provoca la detención. Si está ausente (false), no declara tal soporte, y una Recipe que declara el bloque para este plugin se rechaza antes de que se renderice nada.
metadata:
pluginType: provider
spec:
provider:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm-chart
contract:
inputKinds:
sourced: true
synthesized: false
artifactsStandalone: false
boundaryAssembly: nest
artifactDelimiters:
left: "[["
right: "]]"
reusableInstance: true

spec.pipelineStep

El bloque de paso de pipeline para un plugin pluginType: pipeline-step. Su único campo, capabilities, nombra los proveedores cuya salida renderizada sabe transformar el paso del plugin — nombres de capacidades como helm o compose. Un paso se escribe para la forma de salida de un proveedor a la vez, así que la lista nombra los proveedores que el propio plugin informa; las entradas conservan el orden en que se registran. El bloque solo está presente en los plugins de paso de pipeline.

El bloque es el registro, legible desde el catálogo, de esa declaración: aggrega plugin gen-catalog lo registra a partir del autoinforme describe() del propio plugin, y un autor puede restringirlo antes de publicar. La aplicación lee la misma declaración del plugin: cuando un paso toca un scope, la compilación se detiene a menos que el proveedor que renderiza los documentos de ese scope esté entre los que declara el plugin. Una lista vacía o ausente no declara ninguna compatibilidad, así que ningún scope admite el paso.

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

spec.parser

El bloque de parser para un plugin pluginType: parser. Su único campo, capabilities, nombra los formatos de origen que el plugin convierte en un árbol estructurado canónico, cada uno escrito parse:<format>. El prefijo forma parte de la entrada, así que un plugin que lee varios formatos lista una entrada por formato. aggrega plugin gen-catalog registra la lista a partir del describe() del propio plugin, un autor puede restringirla antes de publicar, y las entradas conservan el orden en que se registran. El bloque solo está presente en los plugins de parser.

Un formato solicitado se resuelve en el parser cuya lista contiene la entrada correspondiente. Un formato que ningún parser anuncia detiene la compilación, y un formato que anuncia más de un plugin de parser se detiene como ambiguo, nombrando a los candidatos — no hay alternativa de respaldo, porque un parser no tiene un valor predeterminado sin configuración al que recurrir. Una lista vacía o ausente no declara ningún formato, así que el plugin no analiza nada.

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

spec.importer

El bloque de importer para un plugin pluginType: importer. Su campo capabilities nombra los formatos de origen externos que el plugin convierte en borradores de archivos de autoría de Aggrega, cada uno escrito import:<format>. El prefijo forma parte de la entrada, así que un plugin que maneja varios formatos lista una entrada por formato. aggrega plugin gen-catalog registra la lista a partir del describe() del propio plugin, un autor puede restringirla antes de publicar, y las entradas conservan el orden en que se registran. El bloque solo está presente en los plugins de importer.

Un formato de importación solicitado se resuelve en el importer cuya lista contiene la entrada correspondiente. Un formato que ningún importer anuncia detiene la importación, y un formato que anuncia más de un plugin de importer se detiene como ambiguo, nombrando a los candidatos, a menos que una entrada plugins.importer en la configuración del espacio de trabajo vincule uno de ellos, que es entonces el que se ejecuta. Una lista vacía o ausente no declara ningún formato, así que el plugin no importa nada.

Su campo detect registra las firmas por las que se reconoce una fuente de esos formatos cuando una importación no nombra ningún formato. Pertenece a la máquina, como los registros de funciones del host y de comandos: se deriva de lo que informa el describe() del plugin cuando la entidad se genera a partir del plugin, en el orden en que el plugin declara las firmas, y un autor no lo escribe. Cada firma nombra:

  • syntax — el formato sintáctico en el que se analiza la fuente, el formato que un plugin de parser anuncia como parse:<syntax>, como json o yaml.
  • files — patrones opcionales de nombre de archivo, comparados con el final del nombre de la fuente: un patrón de un solo segmento con el nombre del propio archivo, uno de varios segmentos separados por barras con otros tantos segmentos finales de su ruta, de modo que .vscode/mcp.json coincide con un archivo llamado mcp.json en un directorio llamado .vscode. *, ? y [...] coinciden dentro de un segmento. Si está ausente, la firma se aplica a una fuente que es un solo archivo, se llame como se llame, y a ningún archivo de un directorio. Los patrones de las firmas de un importer son también lo que decide qué archivos de un directorio le entrega aggrega import.
  • match — los predicados que el árbol analizado debe cumplir, todos ellos. Cada uno tiene un path, claves unidas por puntos desde la raíz del árbol, donde un segmento de número entero selecciona una posición de array; un is, uno de present, absent, object, array, string, number y boolean; y opcionalmente equals, una cadena que el valor debe ser, o prefix, una cadena por la que debe empezar — como mucho uno de los dos.

Cuando una importación no nombra ningún formato, las firmas de cada importer que contiene el catálogo del espacio de trabajo — todas las versiones incluidas — y de los importers básicos del compilador se comparan con la fuente. La fuente se analiza una vez por cada sintaxis en la que la lee una firma aplicable a su nombre, mediante el parser que el catálogo del espacio de trabajo sirve para esa sintaxis — o, para una sintaxis para la que el catálogo no sirve ningún parser, el que incluye el propio compilador — y una fuente que no se puede analizar en una sintaxis no coincide con ninguna firma que la nombre. Un directorio se compara a través de sus archivos: cada firma se prueba con los archivos del directorio que seleccionan sus patrones, en orden de nombre, y una firma que no declara ningún patrón no se aplica a ninguno de ellos. Una fuente con la que coincide una firma se reconoce como cada formato que anuncia su importer. Si se reconoce exactamente un formato, la fuente se lee en ese formato. Una fuente con la que no coincide ninguna firma se rechaza, pidiendo el formato y nombrando los formatos que anuncian los importers — o, para un directorio, pidiendo uno de sus archivos por separado o un formato cuyo importer declare patrones de archivo, nombrando solo esos; una fuente reconocida como más de un formato se rechaza nombrándolos, con la condición More than one importer recognises the source (Más de un importer reconoce la fuente). Así, un importer que anuncia más de un formato ve rechazada como ambigua toda fuente con la que coinciden sus firmas, y un importer cuyas fuentes deban reconocerse sirve un solo formato.

Donde la entidad registra detect, debe ser igual a lo que informa el describe() del plugin, firma por firma y en el mismo orden: la carga del importer rechaza un plugin cuyo informe difiere, nombrando importer.detect, y lo mismo hace su publicación. Una entidad que no registra detect no declara nada y no se compara, así que carga las firmas que informe el describe() de su plugin, y entonces a los formatos de su importer solo se llega nombrándolos.

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

spec.signature

Un puntero descriptivo opcional a la firma adjunta del plugin. El bloque es solo documentación — registra para los lectores del catálogo dónde está la firma y cómo se produjo; no admite el plugin por sí mismo. La comprobación que la hace cumplir es la política de confianza por registry aplicada en el pull: una firma se obtiene como referrer OCI, se verifica contra las identidades de confianza o la clave fijada del registry, y se registra como un hecho verificado en el lockfile. Un registry que exige firmas detiene el pull cuando una firma requerida falta, no es de confianza o no es válida.

  • type — el esquema de firma. sigstore-cosign es el esquema admitido. Obligatorio cuando el bloque está presente.
  • signatureRef — la referencia de referrer OCI del paquete de firma adjunto, para documentación y descubrimiento. Ausente cuando la firma se descubre mediante la enumeración de referrers en el pull en lugar de fijarse aquí.
  • publicKeyRef — un puntero a la clave pública con la que se produjo la firma, para una firma con clave. Su ausencia indica una firma sin clave (identidad OIDC), verificada contra las identidades de confianza del registry.

spec.runtime

Restricciones de ejecución opcionales que el host aplica al cargar y ejecutar el plugin. El acceso de red saliente no es un campo de autoría: un plugin nunca accede a la red en tiempo de compilación — la frontera ahead-of-time — así que aquí no hay ningún campo de lista de hosts permitidos. El contenido remoto que necesita un plugin llega a través del canal de entrada externa mediado por el host y fijado por digest, registrado en el lockfile de la Release, nunca a través de un acceso de red ambiental; la guía para desarrolladores documenta el envoltorio de obtención y la disciplina de fijación.

CampoEfecto
maxMemoryPagesLimita la memoria lineal del plugin en páginas Wasm (64 KiB por página). Cero o ausente aplica el límite predeterminado de la plataforma, así que una carga nunca es ilimitada; un acoplamiento que necesita más aumenta este valor.
timeoutMsLimita cuánto tiempo puede ejecutarse el código propio del plugin durante una llamada, en milisegundos, sin contar el tiempo pasado dentro de las funciones del host que llama. En Linux la medida es el tiempo de procesador, así que el tiempo de espera de un procesador en una máquina ocupada no cuenta; en otros sistemas es el tiempo transcurrido. La primera llamada a un plugin recién cargado cuenta también el arranque del propio plugin. Cero o ausente aplica el límite predeterminado de la plataforma, así que una llamada nunca es imposible de cancelar; un acoplamiento que se ejecuta durante más tiempo aumenta este valor.
hostFunctionsLos nombres de las funciones del host que importa el plugin. Derivado por la máquina y de solo lectura — no lo escribas tú: aggrega plugin sync lee las funciones del host de la sección de importación del .wasm y registra este campo, la publicación rechaza un registro que difiere del binario, y el valor refleja el binario publicado, validado contra la lista de permitidos seleccionada. El host registra exactamente este conjunto, dando a cada plugin la superficie de host de mínimo privilegio que necesita su binario; el pull vuelve a derivar el sello y lo verifica contra el binario. Para previsualizar el valor antes de publicar, ejecuta aggrega inspect --plugin <file.wasm>.
configKVConfiguración específica del Plugin que el runtime le entrega al iniciarse, como pares clave/valor de cadena a cadena. Las entradas conservan el orden del autor para que el registro emitido sea idéntico byte a byte entre ejecuciones. Si está ausente, rige la configuración vacía predeterminada del runtime.

spec.exports

Los exports que ofrece el plugin, cada uno con su capacidad declarada, como una lista ordenada que conserva el orden del autor. Un export es un punto de entrada con nombre al que el host despacha (por ejemplo render_node, lint_naming, step); el bloque de capacidad por export indica lo que hace ese export, tal como aggrega plugin gen-catalog lo registra a partir del autoinforme describe() del plugin, y el host lo contrasta con ese autoinforme al publicar y al cargar. Si está ausente, no declara ninguna superficie de export escrita por el autor.

CampoEfecto
nameEl nombre ABI del export — el nombre al que despacha el host. Obligatorio para cada entrada.
operatesLa operación de pipeline que realiza el export: patch (modificar un documento renderizado existente) o emit (añadir un documento nuevo). El host contrasta el valor con el autoinforme del plugin; es una declaración de capacidad validada, no un conmutador de despacho — la operación que realiza un paso la lleva el resultado que devuelve el invitado. Si está ausente, no lleva ninguna declaración de operación.
scopeLa raíz de documentos sobre la que opera el export: own (los documentos renderizados del propio nodo) o host (los documentos del componente al que está adjunta una FeatureRecipe de ámbito de componente). El host lee el scope declarado antes del paso para hacer cumplir la compatibilidad de proveedor con el proveedor que renderiza ese scope. Si está ausente, el valor predeterminado es own.
selectorUna descripción libre y legible por personas de aquello sobre lo que actúa el export (por ejemplo workloads carrying a pod template). Documentación para los lectores del catálogo y la superficie de inspección; el compilador no la interpreta.

spec.commands

Los verbos de nivel superior aggrega <command> que aporta un plugin cli, como una lista ordenada que conserva el orden que declara el autoinforme describe() del plugin. Gestionado por la máquina y de solo lectura — no lo escribas. aggrega plugin sync lee la superficie de comandos del autoinforme describe() del plugin y la registra aquí, de modo que los comandos que instala un plugin CLI se pueden leer desde la entidad sin cargar el .wasm. Un plugin que no es cli no aporta comandos y registra una lista vacía. El host instala exactamente este conjunto; un conjunto registrado que difiere del autoinforme describe() del plugin detiene la carga, y la publicación rechaza un conjunto desincronizado con el binario e indica al autor que lo vuelva a registrar. Para volver a sincronizar el registro después de cambiar el plugin, ejecuta aggrega plugin sync.

Cada entrada de comando contiene:

CampoEfecto
nameEl verbo de comando que registra el host — el token aggrega <name> que invoca un operador, y el discriminador que el host pasa al plugin en la invocación para que un único plugin que respalda varios comandos pueda enrutar según el comando invocado. Obligatorio en cada entrada.
descriptionEl texto de ayuda breve de una línea del comando, que se muestra en el listado de comandos y en la salida de ayuda. Solo documentación; el host no actúa en función de él.
flagsLos flags del comando, en el orden declarado. Cada entrada registra un flag en el comando para que aggrega help <command> lo muestre como el flag de un comando nativo. Un comando sin flags lo deja vacío.

Cada entrada de flags declara un flag:

CampoEfecto
nameEl nombre largo del flag — el token --name que un operador pasa en la línea de comandos. Obligatorio en cada entrada.
shorthandEl alias corto opcional del flag — la forma -x que un operador puede pasar en lugar del nombre largo — como una sola letra o dígito ASCII. Si falta, el flag no tiene alias corto.
descriptionEl texto de ayuda de una línea del flag, que se muestra en la salida de ayuda del comando. Documentación opcional; el host no lo valida ni actúa en función de él.
typeEl tipo de valor del flag — string, bool o int — y el tipo de flag con el que la ayuda lo muestra. Si falta, se muestra como un flag de cadena.
defaultEl valor predeterminado del flag cuando el operador no lo pasa, expresado como cadena. Para un flag bool o int es un valor de ese tipo. Si falta, el flag no declara ningún valor predeterminado.

Un plugin CLI declara sus comandos y sus flags en describe(); el host registra exactamente esa superficie y muestra los flags de cada comando en aggrega help <command> del mismo modo en que muestra los flags de un comando integrado.

El host comprueba cada flag que declara un plugin al añadir los comandos del plugin, y un plugin cuyas declaraciones fallan se omite en lugar de añadirse: no se registra ninguno de sus comandos, una advertencia indica el plugin, el comando, el flag y qué tiene de incorrecto, y todos los demás comandos — integrados o de otro plugin — siguen funcionando. Una declaración falla cuando:

  • un flag no tiene nombre, o un comando declara el mismo nombre dos veces;
  • una forma abreviada es algo distinto de una sola letra o dígito ASCII, o un comando declara la misma forma abreviada para dos flags;
  • un nombre o una forma abreviada reutiliza un flag que ya tiene todo comando aggrega — --help, su -h, y los flags globales como --offline y --config;
  • un tipo es algo distinto de string, bool o int;
  • un valor predeterminado no se puede interpretar como el tipo del flag — maybe para un bool, three para un int.

La forma de un solo carácter de shorthand y los tres valores de type también forman parte del esquema de esta entidad, por lo que una entidad Plugin que registre cualquier otro valor se rechaza al cargarse el catálogo. Que un nombre o una forma abreviada aparezca una vez por comando, que ninguno reutilice un flag que tiene todo comando y que un valor predeterminado se interprete como su tipo lo comprueba solo el host. La comprobación abarca si el host puede declarar un flag para la ayuda tal como está escrito; no ve si el plugin lee los flags que declara, porque el plugin interpreta sus propios argumentos.

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

Inspeccionar un Plugin

aggrega inspect <path-to-Plugin.yaml> muestra un archivo Plugin: su identidad y su tipo de socket, las capacidades que declara su bloque, la tabla de capacidades por export en el orden del autor, las restricciones de runtime y — con --detail — el puntero de firma y las claves de configuración de runtime. Un Plugin es direccionable por ruta de archivo, o por su coordenada <pluginType>/<name> en el catálogo. Consulta ../cli/aggrega-inspect.md.

Referencias cruzadas

  • Guía para desarrolladores de plugins Wasm — el flujo de trabajo completo del autor: describe(), declaraciones de capacidades, límites de runtime, ciclo de vida, firma, versionado.
  • Contrato de plugins Wasm — los puntos de socket a los que se conecta un plugin y sus formas de entrada y salida.
  • entities/featurerecipe.md — la superficie pipeline: de la FeatureRecipe que hace referencia a un plugin por URI de entidad.
  • cli/aggrega-lint.md — el linter de publicación, los criterios de incremento de versión y la aplicación de la inmutabilidad que rigen la publicación de un Plugin.