跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

Plugin

Plugin 是一种内容寻址的 WebAssembly 插件:一个托管在 OCI 上、按 sha256 摘要固定的 .wasm 制品,它声明自己实现的插槽类型、所面向的 ABI 版本、一个可选的签名指针,以及一个可选的运行时块。该实体是插件的编写与元数据界面;依赖解析按摘要固定该制品,各注册表的信任策略在拉取时验证其签名。编译器不解释插件的行为——它只路由被固定的引用;由 WebAssembly 运行时执行这些字节。

本页逐字段介绍 Plugin 目录的编写界面。关于端到端的作者工作流——插件是什么、describe() 自我报告、发布→拉取→构建的生命周期、签名以及版本管理——请参阅 Wasm 插件开发者指南。关于插件所挂接的插槽点及其输入/输出结构,请参阅 Wasm 插件契约。

Plugin 的作用

Plugin 将一个逻辑插件身份绑定到一个具体的 .wasm 制品,以及宿主安全加载和运行它所需的能力与运行时元数据。流水线步骤或插件插槽通过 URI 引用该实体;实体携带声明的能力、运行时限制和签名指针,而解析出的内容摘要保存在 release 锁文件中。.wasm 的位置由插件的身份推导得出——即可寻址坐标 plugin/<pluginType>/<name>(它本身由 metadata.pluginType 和不带前缀的 metadata.name 组成),再加上所配置的注册表——它不是一个由作者编写的字段。通过该实体进行间接引用是强制的——裸 .wasm 或制品引用会在加载时被拒绝,因为没有任何实体与之匹配。

Plugin 的声明按插槽类型分组,阅读该实体正是从这种分组开始的:

  • 每种插槽类型一个块——spec.provider、spec.pipelineStep、spec.parser、spec.importer。插件携带其 metadata.pluginType 所指定的那一个块,每个块都包含一个 capabilities: 列表(由 aggrega plugin gen-catalog 依据插件自身的 describe() 记录),其含义仅属于该块:provider 的列表列出它提供的能力,流水线步骤的列表列出其步骤所兼容的 provider 能力,而解析器和导入器的列表列出源格式,写作 parse:<format> 和 import:<format>。含义由包含关系承载——不先读到说明其属于哪类声明的块,就无法触及某个能力条目。
  • provider 块携带的不止是列表——spec.provider 还声明插件如何转换 Workload 类型、读取哪些平台原生注解,以及其渲染行为契约(spec.provider.contract:输入类型、边界组装、制品分隔符、实例复用)。这些描述的是渲染行为,而不是所提供的维度,因此它们位于 provider 能力列表旁边,而不是其中。
  • 横切插槽不声明任何能力——linter、governance 或 cli 插件不携带这四个块中的任何一个,因为它既不提供渲染维度,也不提供源格式。
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

标准的目录元数据。name、version 和 pluginType 为必填项;version 是严格的语义化版本(例如 1.2.0)。可选字段 description、maintainers、license、repository、home、keywords 与每个目录实体所带的结构相同,且 metadata 不接受其他任何键。已发布的版本不可变更:重新发布已有版本会在发布关口被拒绝。

metadata.name 是裸名称,不带套接字前缀。插件的可寻址坐标 plugin/<pluginType>/<name> 由 metadata.pluginType 和裸 metadata.name 派生而来,而不是写进名称中。

metadata.pluginType

该插件实现的 socket 类型。它与 name 和 version 一起位于寻址块中,因为它是插件身份的一部分:它提供派生坐标 plugin/<pluginType>/<name> 中的 <pluginType> 段。一个插件只实现一种 socket 类型,取自运行时识别的插件类型分类:

  • provider — 将 IR 节点渲染为 provider 原生的制品。
  • linter — 检查编写的内容并报告诊断。
  • pipeline-step — FeatureRecipe 或 Recipe 的 pipeline: 中的一个步骤,用于修补渲染出的文档集。
  • governance — 承担构建管道的治理角色。在拓扑构建阶段,它自动为拓扑图节点的标签打标记,返回 JSON Patch 文档,由宿主应用到图的仅含标签的投影上。在静态分析或渲染阶段,它评估 IR 图或渲染出的制品,并返回接受/拒绝的判定;规则未通过会使构建停止。决定它可以输出什么的是它所挂载的角色,而不是它的类型。
  • parser — 将外部源格式(HCL、TOML、YAML、JSON 等)解析为结构化的 JSON 树,使需要读取编译器不原生解析的格式的使用方能基于解析后的树而非原始文本工作。
  • importer — 将外部基础设施或 agent 定义源转换为 Aggrega 编写文件草稿,并以 import:<format> 能力的形式声明它所处理的格式。
  • cli — 提供一个运行时 aggrega <cmd> 子命令,供操作人员在命令行调用。这是一种运行时 socket,有别于编译时的渲染和管道 socket。

必填。

spec.abiVersion

该插件所针对的宿主/客体 ABI 版本。v1beta1 是接受的值;新的 ABI 修订会再增加一个。必填。

声明能力:每种插槽类型一个块

能力是使用方向插件请求的东西——某个 Recipe 请求的渲染能力,或某次构建需要读取的源格式。插件的能力记录在其插槽类型所属的块中,因此列表所在的块决定了其条目的含义:

metadata.pluginType能力的声明位置条目指代的内容
providerspec.provider.capabilities该插件提供的渲染能力,例如 helm 或 compose。
pipeline-stepspec.pipelineStep.capabilities该插件的步骤与其渲染输出兼容的 provider。
parserspec.parser.capabilities该插件读取的源格式,写作 parse:<format>。
importerspec.importer.capabilities该插件据以起草实体的外部源格式,写作 import:<format>。
linter, governance, cli—无。这些插槽不提供任何能力,因此不带这四个块中的任何一个。

插件恰好实现一种插槽类型,因此其实体只携带一个块。该列表是插件自己的报告:aggrega plugin gen-catalog 读取插件的 describe(),并将其报告的每项能力写入该块。作者可以在发布前收窄该列表,省去插件报告了但已发布实体不应提供的能力;aggrega validate <entity> --plugin <file.wasm> 和 aggrega push 接受收窄后的列表,并打印一条通知,指出插件报告了而列表省去的每项能力。两者都不接受列出插件未报告的能力的列表:两者都会拒绝它,指出每项此类能力以及插件实际报告的能力,因此已发布的列表所提供的永远不会多于插件所提供的。一个 pipeline-step 实体,其插件报告 helm 和 helm-chart,却还列出了 compose,会像这样被拒绝:

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

使用方严格依据所列内容进行解析。

spec.provider

pluginType: provider 插件的 provider 插槽块:它所服务的能力、它如何翻译平台所有的 aggrega.ai/v1beta1 Workload 类型、它读取哪些平台原生注解,以及它的渲染行为契约。该块存在于每个渲染 provider 的插件上,在其他所有插件类型上都不存在。只渲染来源内容或制品内容、不进行 Workload 合成的 provider 仍然带有该块——它在其中声明自己的能力和契约,只是省略 workloadSchema。

spec.provider.capabilities

该 provider 所服务的能力——例如 helm 或 compose 这样的能力名称——即它所渲染的输出形态。provider 在共享某一能力输出形态的制品之间是通用的,而不是在所有能力之间通用,因此该列表列出的是插件自身报告的能力:aggrega plugin gen-catalog 依据插件的 describe() 记录它,作者可以在发布前收窄它。条目保持其被记录时的顺序。

Recipe 所请求的 provider 目标(spec.capability: helm)会解析到其列表包含该目标的 provider 插件。当多个 provider 插件列出同一目标时,由工作区来选择:工作区配置中的 plugins.providers 选择项指明使用哪个插件,在 aggrega pull 时解析并记录在锁文件中。没有选择项且恰好只有一个候选时,使用该候选;没有选择项且有多个候选时,构建会停止并列出每个候选。歧义在使用处按工作区解决,而不是通过整个目录范围的唯一性规则解决。列表为空或不存在时不声明任何能力,因此该插件不服务任何目标。

此处的能力名称不含冒号。Recipe 的 spec.capability 被解读为:最后一个冒号之前是能力,之后是版本锁定,因此含有冒号的名称永远无法被请求;describe() 报告此类名称的插件会在加载时被拒绝,也不会从它生成任何用于发布的实体。pipeline-step 插件所列出的 provider 能力同样如此。parser 的 parse:<format> 和 importer 的 import:<format> 中的冒号是这些名称的一部分,予以保留。

spec.provider.workloadSchema

一个 JSON Schema 2020-12 声明,记录该 provider 如何将 aggrega.ai/v1beta1 Workload 类型翻译为 provider 原生的清单。按照约定,它声明在进行合成的 provider 上:此类 provider 将 workloadSchema 声明为文档化的翻译契约,描述该 provider 使用哪些 Workload 字段、每个枚举形态字段接受哪些封闭集合,以及适用哪些范围约束。

Plugin 加载时,该主体会被编译为 JSON Schema 2020-12——这是一道结构性护栏,在加载时而非渲染时拒绝格式错误的 schema。workload: Recipe 是否受支持,取决于所绑定 provider 的合成能力,而不取决于该字段是否存在:绑定到无法合成的 provider 的合成模式 Recipe 会在渲染时明确停止。标准库目录使 workloadSchema 与 provider 能力保持同步。该字段是文档化的契约;除此之外没有任何东西读取它。Workload 主体本身依据平台所有的内嵌 Workload schema 进行校验,而不是依据这个按 provider 定义的字段。

spec.provider.wellKnownAnnotations

一个有序数组,列举该 provider 读取的平台原生知名注解键(即位于保留的 aggrega.ai/ 命名空间下的键),以及每个键不存在时所采用的行为。每个条目带有 key(provider 读取的注解,例如 aggrega.ai/namespace)、purpose(该注解存在时控制什么)、可选的 defaultBehavior(该注解不存在时 provider 做什么),以及可选的 scope,列出 provider 在何处读取该键——sourced、synthesized 或 artifactsStandalone(即 Recipe 的输入类型),或表示每个边界读取一次的键的 boundary。key 和 purpose 为必填项;条目保留作者编写的顺序。

该字段是 provider 的支持声明,编译器以两种方式读取它。若某个条目的 scope 指明了该块自身的 contract.inputKinds 未声明的输入类型,则与该声明相矛盾,该 Plugin 会被拒绝,并指出该键和该 scope。此外,当构建通过此 provider 渲染时,若某个 aggrega.ai/ 注解在该次渲染声明的任何输入类型上都没有条目覆盖,就会引发一条警告,指出该键、该 provider 以及那些输入类型;该值仍原样传递,构建不会中止。若缺省,该字段不作任何声明,也不会为此 provider 引发此类警告。Schema 校验只检查每个条目的形态(键位于 aggrega.ai/ 命名空间下,purpose 存在);它不同于控制将值绑定到保留命名空间的运行时检查。

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.

标准库 provider 所附带的各 provider 注解集和 workloadSchema 内容记录在 ../providers/well-known-annotations.md、../providers/helm.md、../providers/helm-chart.md 和 ../providers/compose.md 中。

spec.provider.readsNoWellKnownAnnotations

声明此 provider 不读取任何平台原生的知名注解键。它是一个不覆盖任何键的支持声明,所表达的是同时省略它和 wellKnownAnnotations 所无法表达的内容:缺失的声明是沉默,而这一声明是 provider 自己表明它不读取保留的 aggrega.ai/ 命名空间下的任何内容。通过此类 provider 渲染的构建会对到达渲染的每个 aggrega.ai/ 注解发出警告,指出该键、该 provider 以及该次渲染声明的输入类型;该值仍原样传递,构建不会中止。

只能写 true,因此省略该字段仍是不作任何表述的唯一方式。它不能与 wellKnownAnnotations 一起书写:读取部分键的 provider 应改为在那里列出这些键。这两种拒绝都在 schema 层面,因此该 Plugin 在被读取时即被拒绝。

spec:
provider:
capabilities:
- terraform
readsNoWellKnownAnnotations: true

标准库的 terraform provider 声明了它;../providers/terraform.md 说明了这对通过它渲染的 Release 意味着什么。

spec.provider.contract

渲染 provider 的插件自行声明的编译期渲染行为契约:它渲染的输入种类、它如何组装一个分发组的逐节点输出、它应用于导入的制品文件的模板分隔符对、一个已加载的实例是否可以服务每一次跨越、它是否遵循 omit 条目,以及它是否接受 Recipe 向其边界共享输出贡献的文件。它与 capabilities 位于同一块中,但回答的是不同的问题:能力列表说明该插件服务哪些能力,而契约说明它如何渲染这些能力。aggrega plugin gen-catalog 根据插件自身的 describe() 自我报告记录它,宿主在发布时和加载时将其与该自我报告进行交叉核对;不一致时停止。缺省时不声明任何渲染行为契约,交叉核对只比较逐导出的声明。所有字段均为可选。

字段作用
inputKinds插件渲染三种 Recipe 输入种类中的哪些,每一种都是独立的布尔声明:sourced(来源文件集——一个 chart、一个模块、一个 compose 文件)、synthesized(合成的 Workload)以及 artifactsStandalone(携带导入的制品文档、没有来源或 workload 的独立节点)。宿主依据该集合对节点的输入种类进行把关。
boundaryAssembly插件如何组合一个分发组的逐节点渲染输出:none 将每个节点的输出直接写入分发路径;merge 将逐节点的片段合并为一个文档;nest 将每个节点的输出放在一个总括结构中其自身的位置下。缺省时不携带任何组装声明。
artifactDelimiters插件应用于导入的制品文件的 Go 模板分隔符对,以 left 和 right 表示。缺省时表示默认的 {{/}} 对;目标语法与该对冲突的插件会声明一对替代分隔符(例如 [[/]])。
reusableInstance一个已加载的插件实例是否可以服务一次构建中的每一次渲染、组装和校验跨越,而不是每次跨越使用一个新实例。仅当插件在跨越之间不持有状态时才声明为 true,这样无论复用还是重新加载,单个实例都会产生逐字节相同的输出。缺省(false)时每次跨越加载一个新实例,从而隔离在构造上携带状态的插件。aggrega build --verify-determinism 通过将每个节点渲染两次并在出现任何差异时停止,来证明可复用插件的输出是稳定的。
omits插件是否遵循 omit 条目——即指明要从节点输出中排除的已渲染单元的条目:它会从渲染结果中排除某条目匹配的每个单元,并报告每个条目匹配了多少个单元。该值记录插件的 describe() 所报告的声明,因此只有对报告了该声明的插件,true 才是正确的;与报告不一致的值会导致停止。缺省(false)时不声明此类支持。
boundaryArtifacts插件的目标是否接受 Recipe 在其 spec.boundary.artifacts 下向插件所渲染的边界的共享输出贡献的文件:编译器将每个此类文件写入一次,放在插件为该边界组装的内容旁边,目标将其作为该输出的一部分读取。该值记录插件的 describe() 所报告的声明,与报告不一致的值会导致停止。缺省(false)时不声明此类支持,为该插件声明此块的 Recipe 会在任何渲染开始之前被拒绝。
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

pluginType: pipeline-step 插件的流水线步骤块。它唯一的字段 capabilities 列出该插件的步骤知道如何转换其渲染输出的 provider,即 helm 或 compose 这样的能力名称。一个步骤每次只针对一个 provider 的输出结构编写,因此该列表列出的是插件自身报告的 provider;条目保持其被记录时的顺序。该块只出现在 pipeline-step 插件上。

该块是这一声明的可供目录读取的记录:aggrega plugin gen-catalog 依据插件自身的 describe() 自我报告记录它,作者可以在发布前收窄它。强制检查从插件读取同一声明:当一个步骤涉及某个作用域时,除非渲染该作用域文档的 provider 在插件声明的 provider 之中,否则构建会中止。空列表或缺省列表不声明任何兼容性,因此没有任何作用域接纳该步骤。

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

spec.parser

用于 pluginType: parser 插件的 parser 块。它唯一的字段 capabilities 列出该插件可转换为规范结构化树的源格式,每项写作 parse:<format>。前缀是条目的一部分,因此读取多种格式的插件为每种格式列出一个条目。aggrega plugin gen-catalog 依据插件自身的 describe() 记录该列表,作者可以在发布前收窄它,条目保持其被记录时的顺序。该块仅出现在 parser 插件上。

请求的格式解析为其列表包含匹配条目的 parser。没有任何 parser 声明的格式会使构建中止;由多个 parser 插件声明的格式会因歧义而中止,并列出候选项——不存在回退,因为 parser 没有可供回退的零配置默认值。空列表或缺失的列表不声明任何格式,因此该插件不解析任何内容。

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

spec.importer

pluginType: importer 插件的 importer 块。其 capabilities 字段列出该插件可转换为 Aggrega 草稿编写文件的外部源格式,每项写作 import:<format>。前缀是条目的一部分,因此处理多种格式的插件为每种格式列出一个条目。aggrega plugin gen-catalog 依据插件自身的 describe() 记录该列表,作者可以在发布前收窄它,条目保持其被记录时的顺序。该块仅出现在 importer 插件上。

请求的导入格式解析到其列表包含匹配条目的 importer。没有任何 importer 声明的格式会使导入中止;由多个 importer 插件声明的格式会因歧义而中止,并列出候选项,除非工作区配置中的 plugins.importer 条目挂接了其中之一,此时运行的就是该插件。列表为空或缺失表示不声明任何格式,因此该插件不导入任何内容。

其 detect 字段记录在导入未指定格式时用于识别这些格式之源的签名。它与主机函数记录和命令记录一样由机器维护:在从插件生成实体时,它由插件的 describe() 所报告的内容派生,顺序与插件声明签名的顺序一致,作者不编写它。每个签名指定:

  • syntax:解析源时采用的语法格式,即 parser 插件以 parse:<syntax> 声明的格式,例如 json 或 yaml。
  • files:可选的文件名模式,与源名称的末尾匹配:单段模式与文件自身的名称匹配,由斜杠分隔的多段模式与其路径末尾同样数量的段匹配,因此 .vscode/mcp.json 匹配名为 .vscode 的目录中名为 mcp.json 的文件。*、? 和 [...] 在段内匹配。缺省时,该签名适用于单个文件的源(无论其名称如何),而不适用于目录中的任何文件。importer 各签名的模式也决定了 aggrega import 将目录中的哪些文件交给它。
  • match:解析后的树必须全部满足的谓词。每个谓词包含一个 path,即从树顶部开始以点连接的键,其中整数段选择数组位置;一个 is,取值为 present、absent、object、array、string、number 和 boolean 之一;以及可选的 equals(值必须等于的字符串)或 prefix(值必须以之开头的字符串),二者至多取其一。

当导入未指定格式时,工作区目录所含每个 importer(包括其每个版本)以及编译器核心 importer 的签名都会与源进行匹配。对于适用于该源名称的签名所读取的每种语法,源都会被解析一次,使用工作区目录为该语法提供的 parser;若目录未为该语法提供 parser,则使用编译器自带的 parser。无法以某种语法解析的源不匹配任何指定该语法的签名。目录通过其文件进行匹配:每个签名按名称顺序依次尝试其模式所选中的目录文件,未声明模式的签名不适用于其中任何文件。被某个签名匹配的源被识别为其 importer 声明的每种格式。恰好识别出一种格式时,源即按该格式读取。没有签名匹配的源会被拒绝,要求指定格式并列出各 importer 声明的格式——对于目录,则要求单独指定其中某个文件,或指定一种其 importer 声明了文件模式的格式,并只列出这些格式;被识别为多种格式的源会被拒绝并列出这些格式,报告条件为 More than one importer recognises the source(有多个 importer 识别该源)。因此,声明多种格式的 importer,其签名匹配的每个源都会因歧义而被拒绝;希望其源能被识别的 importer 应只提供一种格式。

若实体记录了 detect,它必须与插件的 describe() 所报告的内容逐个签名、按顺序一致:加载 importer 时会拒绝报告不一致的插件,并指出 importer.detect,发布时同样如此。未记录 detect 的实体不作声明,也不进行比较,因此会加载其插件 describe() 报告的任何签名,此时其 importer 的格式只能通过显式指定来使用。

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

指向插件所附签名的可选描述性指针。该块仅用于文档:它为目录读者记录签名所在的位置及其生成方式;它本身并不准入插件。真正执行检查的是拉取时应用的按注册表划分的信任策略:签名作为 OCI referrer 被获取,依据注册表的受信身份或固定密钥进行验证,并作为已验证的事实记录在锁文件中。要求签名的注册表在所需签名缺失、不受信任或无效时会中止拉取。

  • type — 签名方案。受支持的方案是 sigstore-cosign。存在该块时必填。
  • signatureRef — 所附签名包的 OCI referrer 引用,用于文档和发现。若签名是在拉取时通过 referrer 枚举发现的,而不是在此处固定的,则省略该字段。
  • publicKeyRef — 指向生成签名所用公钥的指针,适用于有密钥签名。省略表示无密钥(OIDC 身份)签名,依据注册表的受信身份进行验证。

spec.runtime

宿主在加载和运行插件时应用的可选执行约束。出站网络访问不是一个编写字段:插件在构建时从不访问网络(这是预先编译的边界),因此这里没有主机允许列表字段。插件所需的远程内容通过由宿主中介、按摘要固定的外部输入通道到达,并记录在 Release 的锁文件中,从不通过环境网络访问获得;开发者指南记录了获取包装器和固定规程。

字段作用
maxMemoryPages以 Wasm 页(每页 64 KiB)为单位限制插件的线性内存上限。为零或缺省时应用平台默认上限,因此加载从不无界;需要更多内存的挂载应调高此值。
timeoutMs限制插件自身代码在一次调用中可运行的时长,单位为毫秒,不计入在其调用的宿主函数内部花费的时间。在 Linux 上,度量的是处理器时间,因此在繁忙机器上等待处理器的时间不计入;在其他系统上为经过的时间。对新加载插件的首次调用还会计入插件自身的启动时间。为零或缺省时应用平台默认上限,因此调用从不会无法取消;运行时间更长的挂载应调高此值。
hostFunctions插件导入的宿主函数名称。由机器派生且只读,不要编写它:aggrega plugin sync 从 .wasm 导入段读取宿主函数并记录此字段,发布时会拒绝与二进制文件不一致的记录,该值反映已发布的二进制文件,并根据精选的允许列表进行验证。宿主恰好注册这一集合,为每个插件提供其二进制文件所需的最小权限宿主接口;拉取时会重新派生该值,并对照二进制文件验证所记录的值。要在发布前预览该值,请运行 aggrega inspect --plugin <file.wasm>。
configKVPlugin 特定的配置,由运行时在启动时交给插件,形式为字符串到字符串的键/值对。条目保留作者编写的顺序,因此输出的记录在多次运行之间逐字节一致。缺省时,运行时默认的空配置生效。

spec.exports

插件提供的导出,每个导出都带有其声明的能力,以保留作者顺序的有序列表形式给出。导出是宿主分派到的一个具名入口点(例如 render_node、lint_naming、step);每个导出的能力块说明该导出所做之事,由 aggrega plugin gen-catalog 根据插件的 describe() 自我报告记录,宿主在发布时和加载时会将其与该自我报告进行交叉核对。缺省时不声明任何编写的导出面。

字段作用
name导出的 ABI 名称,即宿主分派到的名称。每个条目必填。
operates导出执行的流水线操作:patch(修改已渲染的现有文档)或 emit(添加新文档)。宿主会将该值与插件的自我报告进行交叉核对;它是经过验证的能力声明,而不是分派开关——步骤执行的操作由客体返回的结果承载。缺省时不承载任何操作声明。
scope导出所操作的文档根:own(节点自身渲染的文档)或 host(组件作用域的 FeatureRecipe 所附加到的组件的文档)。宿主在步骤之前读取声明的作用域,以针对渲染该作用域的 provider 强制执行 provider 兼容性。缺省时默认为 own。
selector对导出作用对象的自由格式、人类可读的描述(例如 workloads carrying a pod template)。供目录读者和 inspect 界面参考的文档;编译器不会解释它。

spec.commands

cli 插件提供的顶层 aggrega <command> 动词,以有序列表形式给出,保留插件 describe() 自报告声明的顺序。由机器维护且只读——不要手写此字段。aggrega plugin sync 从插件的 describe() 自报告读取命令接口并记录在此,因此无需加载 .wasm 即可从实体中读出 CLI 插件安装的命令。非 cli 插件不提供命令,记录为空列表。宿主恰好安装这一组命令;记录的命令组若与插件的 describe() 自报告不一致,则在加载时中止,发布时也会拒绝与二进制文件不同步的命令组,并指示作者重新记录。修改插件后如需重新同步记录,请运行 aggrega plugin sync。

每个命令条目包含:

字段作用
name宿主注册的命令动词——即操作者调用的 aggrega <name> 标记,也是宿主在调用时传给插件的判别值,使支撑多个命令的单个插件能根据被调用的命令进行路由。每个条目必填。
description命令的单行简短帮助文本,显示在命令列表和帮助输出中。仅作文档用途;宿主不据此执行任何操作。
flags命令的标志,按声明顺序排列。每个条目在命令上注册一个标志,使 aggrega help <command> 像渲染核心命令的标志一样渲染它。没有标志的命令将其留空。

每个 flags 条目声明一个标志:

字段作用
name标志的长名称——即操作者在命令行上传入的 --name 标记。每个条目必填。
shorthand标志可选的短别名——操作者可用来代替长名称传入的 -x 形式——为单个 ASCII 字母或数字。缺省表示该标志没有短别名。
description标志的单行帮助文本,显示在命令的帮助输出中。可选的文档;宿主既不校验也不据此执行任何操作。
type标志的值类型——string、bool 或 int——也是帮助将其渲染成的标志种类。缺省时渲染为字符串标志。
default操作者未传入该标志时的默认值,以字符串表示。对于 bool 或 int 标志,它是该类型的值。缺省表示该标志未声明默认值。

CLI 插件在 describe() 中声明其命令及标志;宿主恰好注册这一接口,并在 aggrega help <command> 中以渲染内置命令标志的相同方式渲染每个命令的标志。

宿主在添加插件的命令时检查插件声明的每个标志,声明未通过检查的插件会被跳过而不是被添加:其命令均不注册,一条警告会指出该插件、命令、标志及其问题所在,而其他所有命令——无论是内置的还是来自其他插件的——都照常工作。以下情况声明不通过:

  • 标志没有名称,或某个命令两次声明同一名称;
  • 短别名不是单个 ASCII 字母或数字,或某个命令为两个标志声明同一短别名;
  • 名称或短别名重用了每个 aggrega 命令都已有的标志——--help、其 -h,以及 --offline 和 --config 等全局标志;
  • 类型不是 string、bool 或 int;
  • 默认值无法按标志的类型解析——例如 bool 的 maybe,int 的 three。

shorthand 的单字符形式和 type 的三个取值也是该实体 schema 的一部分,因此记录了其他值的 Plugin 实体会在目录加载时被拒绝。名称或短别名在每个命令中只出现一次、没有重用每个命令都有的标志、默认值能按其类型解析,这些只由宿主检查。该检查涵盖宿主能否按所写内容为帮助声明标志;它无法得知插件是否读取其声明的标志,因为插件自行解析其参数。

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

检查 Plugin

aggrega inspect <path-to-Plugin.yaml> 渲染 Plugin 文件:其标识和插槽类型、其块声明的能力、按作者顺序排列的各导出能力表、运行时约束,以及在 --detail 级别下的签名指针和运行时配置键。Plugin 可通过文件路径寻址,也可通过其在目录中的 <pluginType>/<name> 坐标寻址。参见 ../cli/aggrega-inspect.md。

交叉引用

  • Wasm 插件开发者指南 — 端到端的编写流程:describe()、能力声明、运行时限制、生命周期、签名、版本管理。
  • Wasm 插件契约 — 插件挂接的插槽点及其输入/输出结构。
  • entities/featurerecipe.md — FeatureRecipe 的 pipeline: 接口,它通过实体 URI 引用插件。
  • cli/aggrega-lint.md — 约束 Plugin 发布的发布检查器、版本升级评判标准以及不可变性强制执行机制。