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

Wasm 插件开发者指南

本文是编写 Aggrega WebAssembly(Wasm)插件并将其发布为目录实体的权威指南。它完整讲解插件作者需要遵守的契约:插件是什么,插件如何向宿主描述自身,如何编写插件的导出及其能力声明,宿主施加的运行时限制和提供的宿主函数,将插件带入目录的 Plugin 实体,Recipe 或 FeatureRecipe 如何引用插件,以及发布→拉取→构建的生命周期——它将插件从磁盘上的 .wasm 文件变为一个经过验证、按摘要固定、供构建使用的制品。

配套页面 plugin-contract.md 记录的是插槽——插件接入的流水线位置,以及每个插槽消费和产出的输入/输出结构。本指南记录的是插件——实体、能力范围和生命周期。阅读契约页面可了解你的插件面向哪个插槽;阅读本页面可了解如何编写和发布插件。

如果你需要的是完成整个任务的实践路线而不是参考说明,编写 provider 会从头到尾构建一个小型 provider guest——描述符、构建、实体、挂接,以及一次输出可供你阅读的渲染——其中还包括初稿通常会遇到的拒绝及其解读方法。

1. 什么是 Wasm 插件

Wasm 插件是在指定插槽处扩展编译器的 WebAssembly 模块。Go 宿主二进制文件不包含任何特定于云或基础设施的逻辑;所有领域相关的智能——模板渲染、格式转换、策略评估、lint 检查——都位于插件内部。宿主负责编排流水线,并将每个插槽的载荷跨越 ABI 边界传递给客户端(guest);客户端完成领域工作,并返回该插槽的结果结构。每个插槽的载荷和结果都以规范 CBOR 传输,但有两个例外:CLI 插件以 JSON 文本接收其参数向量,并以退出码及其流式输出的文本作答;describe 自我报告是 JSON 文本。插件契约中每个插槽的章节都说明了其编码,客户端通过其工具包的载荷类型已提供的入口点读写该编码,因此任何客户端都无需手动解析字节。

插件运行在一道提前(ahead-of-time)纯度防火墙之后。宿主通过内嵌的 Wasm 运行时,在拒绝所有能力的配置下加载并执行模块:没有网络套接字,没有文件系统,没有环境变量,标准输入输出被丢弃,可观测的挂钟时间被冻结在一个与构建无关的固定时刻。客户端尝试的任何 I/O 调用都会在调用边界处失败,因此插件无法获取运行时状态。编写插件时请考虑这道防火墙:插件转换交给它的载荷,并返回宿主原样使用的结果,而确定性由你负责——相同的输入必须产生相同的输出字节。获取远程内容的唯一许可通道是由宿主中介的外部输入获取(第 4 节),它在摘要固定的规则下提供字节,而不是让客户端直接访问网络。

插件可以面向的插槽——其中包括拓扑构建阶段的变更关卡、静态分析阶段的校验关卡、FeatureRecipe 流水线、带外 linter 以及 provider 渲染插槽——及其各插槽的输入/输出结构记录在 plugin-contract.md 中。插件服务于哪个插槽,由它在 metadata.pluginType 中声明的唯一值决定,该字段接受的全部取值见 entities/plugin.md §“metadata.pluginType” 中的参考条目。本指南中的示例使用 provider(将 IR 节点渲染为 provider 原生制品)、linter(检查编写的内容并报告诊断)和 pipeline-step(FeatureRecipe 或 Recipe 的 pipeline: 中修补已渲染文档集的步骤)。

你通过三语言插件开发工具包(PDK)——Go、Rust 或 TypeScript——针对宿主编写客户端。PDK 封装了底层的 Wasm 工具链,并为每个插槽承载的输入和输出结构提供 Aggrega 类型化的构建器。

2. describe() 自我报告

每个插件都导出一个 describe() 函数,返回插件的自我报告:它实现的套接字类型、它面向的 ABI 版本、它声明的能力(按套接字类型解读:对 provider 或流水线步骤而言是能力名称,对解析器或导入器而言是带前缀的源格式)、它导入的宿主函数,以及它提供的每个入口点的逐导出能力。describe() 是插件对自身是什么、做什么的自述。

自我报告是信任模型的锚点。将插件带入目录的 Plugin 实体(第 5 节)以作者声明的形式重述同样的事实,宿主会在两个时刻将实体的声明与插件的 describe() 输出进行交叉核对:发布时,在任何字节进入注册表之前;加载时,在插件运行之前。不一致会明确报错并中止。实体是人类可读、在目录中可见的界面;describe() 是宿主用来核验它的权威记录。编写时让两者保持一致;交叉核对的存在正是为了捕获两者出现偏差的情况。它核对的是实体声明了什么,而不是遗漏了什么:声明少于二进制所报告内容的实体——例如某次新增了导出的重新构建之后遗留下来的实体——仍然可以加载,只是不再描述该二进制所做的全部事情。

3. 编写导出及其能力声明

一个插件提供一个或多个导出——由宿主分派调用的具名入口点(例如 render_node、lint_naming、step)。每个导出带有一个能力块:作者对该导出所做之事的声明。导出的能力有四个字段:

  • name——导出的 ABI 名称,即宿主分派调用时使用的名称。必填。
  • operates——导出执行的流水线操作:patch(修改一个已渲染的现有文档)或 emit(添加一个新文档)。这是一项声明的能力声明。宿主在发布时和加载时将其与插件的 describe() 自我报告进行交叉核对,因此实体中编写的声明与插件自身的说明必须一致。它是关于该导出的一项经过验证的声明,而不是分派开关:在渲染时,步骤实际执行的操作由客体返回的结果携带,而不是从该字段中选择。缺省时不携带任何操作声明。
  • scope——导出所操作的文档根:own(节点自身渲染的文档)或 host(组件作用域的 FeatureRecipe 所附加到的组件的文档)。在流水线步骤的插件运行之前,宿主读取该步骤声明的导出作用域,并强制要求渲染该作用域文档的 provider 出现在插件的 spec.pipelineStep.capabilities(第 5 节)中——own 作用域的导出会对照渲染节点自身文档的 provider 进行检查,host 作用域的导出则对照宿主组件的 provider 进行检查,作用域为空时在此检查中默认视为 own。这就是在步骤之前运行的 provider 兼容性关卡;客体操作实际触及的文档在客体返回的结果中按操作逐一指明,而不是从这个声明字段中选择。缺省时默认为 own。
  • selector——对导出作用对象的自由格式、便于人阅读的描述(例如 workloads carrying a pod template)。它是面向目录读者和 aggrega inspect 界面的文档;编译器不会解释它。

按你希望的阅读顺序编写导出;条目在实体上和 inspect 中都保留作者的顺序。没有编写任何导出的插件不声明导出界面——对于其插槽不需要逐导出能力声明的插件,这是有效的。

4. 运行时限制与宿主函数

插件实体可以带有一个可选的 runtime 块,用于约束宿主加载和运行该插件的方式。

内存与时间限制。 maxMemoryPages 以 Wasm 页(每页 64 KiB)为单位限制插件的线性内存;timeoutMs 以毫秒为单位限制插件自身代码在一次调用中可运行的时长。在插件所调用的宿主函数内部花费的时间不计入其中。在 Linux 上,度量的是运行 guest 的线程的处理器时间,因此在繁忙机器上 guest 等待处理器的时间同样不计入;在其他系统上则为经过的时间。对新加载插件的首次调用还会计入 guest 语言运行时的一次性初始化,该初始化在这次调用内运行。两项限制都是可选的且有默认值:为零或缺省时采用平台默认上限。实体未声明限制时,加载器会以平台默认值约束每个插件,因此加载绝不会无上限,调用也绝不会无法取消。当某个挂载确实需要超出默认值的内存或时间时,在实体上调高相应限制。

宿主函数。 hostFunctions 记录插件导入的宿主函数名称。它是一个由机器推导的字段——不要手写。 aggrega plugin sync 会直接从 .wasm 的导入段读取宿主函数,并替你把该字段记录到实体文件中;发布时会从二进制重新推导这些函数,并拒绝记录与之不一致的实体;因此插件得到的正是其二进制实际导入的宿主函数,并会对照一份精选的允许列表进行校验(允许列表之外的导入会被明确拒绝)。该记录是已发布二进制的快照,正如内容寻址的 plugin: 引用是已发布字节的快照:它反映发布时的二进制,并在拉取插件时重新推导和校验。若要在发布前查看本地 .wasm 导入的宿主函数(即 aggrega plugin sync 记录的值),运行 aggrega inspect --plugin <file.wasm>。

精选的宿主接口。 其中三个宿主函数是通用的:aggrega_log(一个级别和一条消息,作为一行日志输出到宿主的日志目标)、aggrega_emit_warning(一个代码、一条消息和一个路径,累积为结构化警告,由宿主在调用结束后呈现)以及 aggrega_fetch_external_input(一个 URL,按下文的固定规则以该输入的字节作答)。PDK 在每种语言中都封装了这三个函数——Go:aggrega.Log、aggrega.EmitWarning、aggrega.FetchExternalInput;Rust:log、emit_warning、fetch_external_input;TypeScript:log、emitWarning、fetchExternalInput——因此 guest 调用的是有类型的函数,而不是原始 ABI。源与解析回调(供需要读取已获取源的片段或通过宿主获得解析树的 guest 使用),以及每个回调的槽位所承载的编码,列在 plugin-contract.md 中。

本地源内容经由宿主传入——绝不来自文件系统。 provider 渲染插件从不从磁盘读取其源;文件系统调用会在调用边界处失败。宿主在渲染载荷中交给 guest 一份源清单——每个条目相对于源根的路径以及它是否为目录,按排序顺序排列,不含文件内容——guest 对其应用自己的布局逻辑,然后通过源回调读回它所选择的那些文件,这些回调返回宿主在源根下读取的字节。各插槽的载荷结构和回调记录在 plugin-contract.md 中。

远程内容通过外部输入获取传入。 需要远程内容(chart 归档、远程 schema 文档)的插件会调用 PDK 的获取封装。在传输层,guest 以 UTF-8 文本将 URL 传给 aggrega_fetch_external_input,并收到一个规范 CBOR 格式的回复,其中要么是原样获取的字节,要么是一条错误消息及其可供机器匹配的代码;封装会将回复解码为字节或错误。字节按获取时的原样到达,包括非有效 UTF-8 的载荷,零长度载荷则以空字节返回而非错误。宿主按外部输入的固定规则提供该 URL:

  • 已在 Release 的 lockfile 中固定的 URL 从本地内容寻址存储中提供,每次读取都会对照其记录的摘要进行校验。缺失的存储 blob 会按记录的摘要从网络重新填充——经摘要校验的重新填充不会改变输出。
  • 未固定的 URL 会被拒绝,错误中会指明该 URL 及修复方法。构建渲染的是其 lockfile 记录的闭包,因此任何构建都不会获取未固定的引用,也没有任何设置能让构建这样做。
  • 固定发生在解析 Release 的依赖时:aggrega pull 渲染该 Release 以找出其渲染请求了哪些外部输入,逐一获取,并将其与依赖固定记录一起写入 lockfile。因此插件作者的工作循环是:解析一次,然后可随意多次离线构建。

允许的协议为 https、仅限回环主机的 http,以及 oci(按 manifest 摘要固定)。lockfile 记录每个已固定的输入——其 URL、sha256 摘要、大小以及需要它的插件——因此重新构建会从本地存储提供相同的字节:可复现,且固定后可离线。

使用 Go PDK:

import "github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
chart, err := aggrega.FetchExternalInput("https://charts.example.com/postgresql-16.3.2.tgz")
if err != nil {
// The error names the URL and the remedy — an unpinned URL reports exactly
// what to pin and how. Surface it as a render failure; do not mask it.
return fmt.Errorf("fetching chart archive: %w", err)
}

什么会失败,以及原因。

  • 文件系统或网络调用会在调用边界处失败:guest 没有预打开的目录,也没有套接字。这适用于所有代码路径,包括试图读取文件的库依赖——请改为通过源回调读取源。
  • 位于 wasi_snapshot_preview1、extism:host/env 和 extism:host/user 之外的模块下的导入会在加载时失败,诊断信息会指明该模块和导入。允许模块内的单个 WASI 函数名永远不会被审查——静态链接的语言运行时中未使用的文件系统和套接字导入没有问题,因为声明一个导入并不授予任何权限。
  • 获取 lockfile 未固定的 URL 会失败,错误中会指明该 URL;修复方法是运行 aggrega pull --release <release>,它会固定该 Release 渲染所消费的每个外部输入,然后再构建。

没有用于出站网络访问的主机允许列表字段。插件在构建时从不访问网络——这就是预先编译(ahead-of-time)的边界——因此不存在这样的字段可供编写。远程内容通过上述由宿主中介、按摘要固定的外部输入通道传入,绝不通过环境网络访问。

配置。 configKV 是运行时在启动时交给插件的字符串到字符串映射。条目保留作者编写的顺序,使输出的记录在多次运行间逐字节一致。缺省时沿用运行时默认的空配置。

5. Plugin 实体

插件以 Plugin 实体的形式进入目录——这是插件的编写与元数据界面。该实体声明插件是什么,并指向 .wasm 制品;编译器不解释插件的行为,只路由已固定的引用,而由 Wasm 运行时执行这些字节。

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
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

字段如下:

  • 有意不设制品位置字段。 该实体不携带指向 .wasm 的指针,schema 也不接受此类字段。插件的制品位置由其身份推导得出——即 metadata.pluginType/metadata.name 坐标,它构成仓库路径 plugin/<pluginType>/<name>——再加上工作区所配置的注册表,因此没有需要编写的位置,也就不会写错。解析得到的内容摘要按 Release 记录在该 Release 的锁文件中,构建时会据此校验拉取到的字节:身份在实体中,经校验的字节在锁文件中。
  • metadata.version——该实体发布的版本,必须与 guest 自身在 describe() 中报告的构建来源版本一致。插件作者在构建时为 .wasm 确定版本——构建会将版本写入 guest,而从发布标签获取版本的构建只会在该标签所指的提交上写入发布版本——实体的 metadata.version 则指明同一个版本。发布环节会交叉核对两者,出现不一致时即中止,因此实体总是指明其所交付二进制的确切版本。aggrega plugin gen-catalog --plugin(见下文)会将 guest 报告的版本复制到它生成的实体中;当 guest 由带标签的提交构建时,这就是发布版本。必填。
  • metadata.pluginType——该插件实现的插槽类型,取值为 provider、linter、pipeline-step、governance、cli、parser 和 importer 之一。一个插件恰好实现其中一种。它位于寻址块中,与 name 和 version 并列,并提供推导坐标中的 <pluginType> 段。必填。
  • spec.abiVersion——插件所针对的 host/guest ABI 版本。可接受的值为 v1beta1;未来的 ABI 修订会增加可接受的值。必填。
  • 你的插槽类型所对应的块,携带 capabilities——插件在其 metadata.pluginType 所属的块中声明它提供什么,由该块确定条目的含义。spec.provider.capabilities 列出 provider 提供的能力(如 helm 或 compose 之类的能力名称)。spec.pipelineStep.capabilities 列出与你的步骤兼容其渲染输出的 provider。spec.parser.capabilities 列出 parser 读取的源格式,每项写作 parse:<format>。spec.importer.capabilities 列出 importer 据以起草实体的外部格式,每项写作 import:<format>。用 Go 编写的 importer 可以从 Go 工具包的 importer 包 github.com/aggrega-ai/aggrega-pdk/go/pkg/importer 中获取所有与格式无关的部分——评分、引用还是起草的决策、草稿及其渲染,以及其设置。linter、governance 或 cli 插件不提供能力,不携带这四个块中的任何一个。条目保留作者顺序,且每个列表都是明确的、经过测试的声明:请声明你实际构建并测试过插件所针对的内容,因为使用方会严格按照所列内容进行解析。对于流水线步骤,该声明在渲染时强制执行——当某个步骤涉及某个作用域时,除非渲染该作用域文档的 provider 在你的插件所声明的范围内,否则构建中止——因此空列表不匹配任何 provider,该步骤在任何地方都不被接纳。
  • spec.signature——指向插件所附签名(第 8 节)的可选描述性指针。该块仅用于文档:它为目录读者记录签名的位置及其生成方式;它本身并不接纳插件。真正执行检查的是拉取时应用的按注册表划分的信任策略。
  • spec.runtime——第 4 节中的可选执行约束块。作者编写 maxMemoryPages、timeoutMs 和 configKV;hostFunctions 由机器推导,由 aggrega plugin sync 记录并在发布时校验,无需编写。
  • spec.exports——第 3 节中按导出划分的能力声明(name、operates、scope、selector)。

从你的 .wasm 生成实体。 你不必手写实体中由机器管理的部分。aggrega plugin gen-catalog --plugin <file.wasm> 读取 guest 的 describe() 自报告,并据此加上你提供的一小段编写覆盖层(身份、运行时限制以及任何 provider 块),生成可直接发布的 Plugin 实体。生成器写入以二进制为事实来源的字段——导出声明、能力契约、命令镜像和宿主函数记录——并从 guest 的 describe() 构建来源版本复制 metadata.version,而覆盖层只提供二进制未报告的内容。这是第三方插件作者的受支持路径:构建 .wasm 并为其确定版本,然后重新生成实体,使其机器管理的字段与二进制保持同步。版本是唯一一个指明发布版本而非字节事实的复制字段,因此请从该版本标签所指提交的构建生成——或者,若从开发构建开始,请在为承载它的提交打标签之前,在生成的实体中将 metadata.version 设为该发布版本。不携带构建来源版本的 guest 无法生成带版本的实体——请先在构建时为 guest 确定版本。

实体旁的 .wasm。 在你编写插件期间,还没有任何已发布的内容可供构建获取,因此构建会从某个目录文件夹中该插件的 Plugin 实体旁读取插件的 .wasm,其文件名由实体的插件类型和名称派生:对于 pipeline-step/patch,文件名为 pipeline-step--patch.wasm。小写字母、数字和大多数连字符按原样写入该名称;其他任何字符都以转义形式写入,少数位置上的连字符也是如此 — 因此在需要时,缺少 .wasm 时的拒绝信息 A plugin’s .wasm is not on this machine (插件的 Wasm 模块不在此机器上) 会给出完整的名称。除非二进制文件本身携带该插件,aggrega lint <plugin.yaml> 会从同一位置读取 .wasm — 即在给定的实体文件旁,无论该文件位于哪个目录 — 并针对 .wasm 报告而实体遗漏的每个导出、能力或契约打印一条通知。若该处没有 .wasm,lint 会说明它跳过了该报告,并指出它查找的文件和目录,其结果不会改变。

逐字段参考请参阅实体页面 ../entities/plugin.md。

6. 引用插件

流水线步骤或插件插槽通过 Plugin 实体 URI 引用插件——即该实体的标识,而不是直接引用 .wasm 制品。实体是承载摘要固定、能力声明、运行时限制和签名的那一层;引用实体正是使用方获取所有这些内容的方式。

留在 plugin 字段中的裸 .wasm 路径或原始制品引用会在加载时被拒绝:没有任何 Plugin 实体与之匹配,因此插件解析会明确报错失败。实体 URI 是必需的——经由实体的这层间接引用就是契约,而非可有可无的便利。FeatureRecipe 流水线步骤在 pipeline[].plugin 中指定该实体;流水线的编写方式参见 ../entities/featurerecipe.md。

当两个或多个插件相互耦合时——它们必须就一个共享的交接契约达成一致,例如在 Fetcher 与 Injector 组合中,一个插件的输出是另一个插件的输入(即 plugin-contract.md 中描述的两部分 Plugin 原则(Two-Part Plugin Principle))——应只编写一次该契约,并让每个插件都依赖这唯一的定义,而不是在每个插件中各自重复声明 JSON 交接结构。共享的结构是插件之间交换的 JSON 结构,它可以存放在两个插件都引用的同一个 SchemaLibrary 条目中。契约只有单一来源,能让耦合的插件在契约演进时保持同步;各自独立的重复声明会逐渐偏离,而这种偏离只有在两者运行时不再一致时才会暴露出来。建议共享的是契约,而不是 Wasm 代码——每个插件仍然是各自独立的制品。

7. 发布 → 拉取 → 构建的生命周期

插件经过三个阶段,从磁盘上的 .wasm 文件变为可供构建使用、经过验证的制品。

发布。 aggrega push 将一个 Plugin 实体及其 .wasm 一起发布为单个 OCI manifest,并以 metadata.version 作为标签:实体 YAML 是该 manifest 的配置 blob,.wasm 则作为同一 manifest 的一个层。将这一对内容作为一个带标签的 manifest 发布,正是推送具有原子性的原因——不存在一半已发布而另一半未发布的时间窗口——这也是对该 manifest 的一个签名能同时覆盖两部分的原因。两部分都在 manifest 上命名,因此拉取该版本标签的通用 OCI 客户端会将实体写入 entity.yaml,将可执行文件写入 entity.wasm。

在写入任何字节之前,发布会先运行检查。首先按照 Plugin schema 读取实体,方式与目录加载读取它的方式相同,因此不是语义化版本的 metadata.version——或任何其他偏离 schema 的情况——会在读取 .wasm 之前被拒绝。随后加载 .wasm,并将其 describe() 自报告与实体中编写的能力声明进行交叉核对——不一致会明确报错并中止,因此已发布的实体永远不会声明其附带的插件未报告的内容。如果 guest 的 describe() 构建来源版本带有 -dirty 标记(从含有未提交更改的工作树构建时会被打上此标记),则会被拒绝:该版本指向的提交并不包含实际构建的内容。从某个提交构建的开发版本(1.0.0-3-g1a2b3c4)和预发布版本(1.0.0-rc.1)可以发布。记录的 metadata.version 会与 guest 的 describe() 构建来源版本交叉核对,两者不一致会中止发布,因此两者必须一致。这两种拒绝的解决方式相同:从该版本的标签所指向提交的干净检出构建插件,使其报告的就是该发布版本本身——对于新版本,先将实体与其发布的源代码一起提交,并为该提交打上标签。将开发构建报告的版本复制到实体中并不能解决问题:这会以一个没有任何发布标签指向的版本发布该构建。.wasm 导入的宿主函数从二进制文件推导得出,并与 spec.runtime.hostFunctions 中已提交的记录进行比较;不一致会中止发布并提示 aggrega plugin sync,该命令会重新记录此字段,因为该字段由机器维护,且发布永远不会改写已提交的实体文件。已发布的实体携带已标记的宿主函数记录;.wasm 内容摘要是这一对内容所发布成的 manifest 的属性,它为使用方记录在 Release 锁文件中,而不是写入实体。

拉取。 aggrega pull 解析一个 Release 的所有依赖,并写入一个按 Release 划分的锁文件,将每个目录实体和远程制品固定到某个版本和内容摘要。已发布的 Plugin 通过这一依赖解析进行解析;其 .wasm 随承载它的 manifest 一起获取,并根据锁文件记录的内容摘要验证字节。拉取还会从经过验证的 .wasm 重新推导宿主函数,并与已标记的 hostFunctions 记录核对,两者不一致时中止——这是在摘要固定之上的纵深防御检查,可以发现标记并非由其自身导入生成的二进制文件。如果注册表的信任策略要求签名,则在此阶段获取并验证实体的签名,并将其作为已验证的事实记录在锁文件中(第 8 节)。验证发生在拉取阶段,绝不在构建阶段——构建保持预先编译的纯粹性。

构建。 aggrega build 使用已解析依赖中经过固定和验证的插件。编译器传递经摘要固定的引用,由 Wasm 运行时执行这些字节;加载关卡会在插件运行前重新执行 describe() 交叉核对以及宿主函数和运行时限制的强制检查。

8. 签名与信任

Plugin 实体的签名方式与其他所有目录实体完全相同:对 manifest 的摘要进行签名,并将签名作为 OCI referrer 附加。.wasm 构件不单独签名,也无需单独签名——它本身就是被签名摘要所属 manifest 的一个层,因此签名直接覆盖它:篡改 .wasm 会改变 manifest 摘要,从而使签名失效。

签名在发布时是可选的;验证则在拉取时由各 registry 的信任策略强制执行。配置为要求签名的 registry 会在所需签名缺失、不受信任或无效时中止拉取。实体上的 spec.signature 块是一个文档指针,指明签名存放的位置及其生成方式;它为目录读者记录事实,本身并不控制准入。起准入控制作用的是拉取时的策略。

这些命令及其标志与发布和使用接口一同记录——参见 ../cli/aggrega-sign.md、../cli/aggrega-push.md 和 ../cli/aggrega-pull.md。本指南不再重复标志表;这些页面是命令接口的唯一说明来源。

9. 实体的版本管理

Plugin 实体在 metadata.version 中携带一个严格的语义化版本。已发布的版本不可变:以不同内容重新发布注册表中已存在的版本,会在发布关口被拒绝。

当你修改插件实体并重新发布时,发布规程会将该变更与先前发布的版本进行比对分类,并要求版本递增与之相符。分类依据版本递增准则:仅涉及文档或注释的变更为 PATCH;严格增量的变更(新增可选字段、新增条目)为 MINOR;删除、类型收窄,或先前可选的字段变为必填,则为 MAJOR。超额递增始终允许;递增不足则会中止,并给出指明所需递增的诊断信息。实体的首次发布会跳过递增检查,并给出未执行任何验证的警告。发布前可使用 aggrega lint --pre-publish 运行该检查;完整准则和逐条规则的设置参见 ../cli/aggrega-lint.md。

Plugin 没有 extends 接口,因此约束目录中 Components 和 Features 的继承规则不适用于它。版本递增准则与不可变性就是约束插件实体的版本管理规程。

10. 交叉引用