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

Aggrega Core(Plugin)schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/plugin-v1beta1.schema.json

一个 Wasm 插件:发布到 OCI 仓库的 WebAssembly 模块,由其 metadata.pluginType(它所实现的插槽)加上其裸 metadata.name 标识,声明它所针对的 ABI 版本、一个可选的签名指针和一个可选的运行时块。该实体及其 .wasm 作为一个以 metadata.version 为标签的 OCI manifest 发布:实体 YAML 作为 manifest 的 config blob,.wasm 作为内联层,只签名一次。身份由 metadata.pluginType/metadata.name 坐标加上实体的 metadata.version 构成;.wasm 的位置由该坐标加上所配置的仓库推导得出,解析后的内容摘要保存在 lockfile 中,而不在实体中。lockfile 记录该摘要,按仓库配置的信任策略在拉取时验证制品的签名。编译器不解释插件的行为:它只路由引用;WebAssembly 运行时执行这些字节。

关于编写 Plugin 实体的文字指南,请参阅 Plugin 编写参考;本页记录该参考所描述的结构化 schema。

顶层类型: object

属性

属性类型必需描述
apiVersionconst “aggrega.ai/v1beta1”是常量:"aggrega.ai/v1beta1"
kindconst “Plugin”是常量:"Plugin"
metadataobject是
specobject是插件所针对的 ABI 版本、可选的签名指针以及可选的运行时块。插件的 .wasm 位置由插件的标识——其 metadata.pluginType(插槽)加上其裸 metadata.name——以及所配置的注册表推导而来;它不在 spec 中携带。

不允许其他属性。

plugin.metadata

属性类型必需描述
namestring是长度至少为 1 个字符。
versionstring是Plugin 实体的严格语义化版本(例如 1.0.0)。模式:^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$。
pluginTypestring(枚举)是此插件实现的插槽类型。一个插件恰好实现一种插槽类型,取自运行时识别的插件类型分类:provider(将 IR 节点渲染为 provider 原生产物)、linter(检查编写的内容并发出诊断)、pipeline-step(FeatureRecipe 或 Recipe 的 pipeline: 中为渲染出的文档集打补丁的步骤)、governance(承担构建流水线的治理角色——在拓扑构建时转换节点标签,或在静态分析时针对 IR 图、在渲染时针对渲染产物给出接受/拒绝判定;决定其可输出内容的是它所挂载的角色,而非其类别)、cli(贡献一个操作者在命令行调用的运行时 aggrega <cmd> 子命令——这是一个运行时插槽,不同于编译时的渲染插槽和流水线插槽)、parser(将外部源文本转换为规范的结构化树,使使用方无需自带语言解析器即可读取该树,并以 parse:<format> 能力声明其处理的格式)、importer(将外部基础设施或智能体定义源转换为 Aggrega 编写文件草稿,并以 import:<format> 能力声明其处理的格式)。允许的值:"provider"、"linter"、"pipeline-step"、"governance"、"cli"、"parser"、"importer"
descriptionstring否说明该实体是什么、用于什么,面向正在决定是否使用它的人。先用一句话点明它是什么,再补充读者正确选择和使用它所需的信息——它对运行它的构建有什么要求,以及它的行为中任何出人意料之处。通常写一小段即可。
maintainersobject[]否拥有此实体的维护者列表。
licensestring否此实体所描述软件的许可证 SPDX 标识符,例如 MIT 或 AGPL-3.0。它记录的是该软件的条款,而不是此文件的条款。
repositorystring否源文件所在 Git 仓库的 URL。
homestring否此实体的主页、wiki 或文档的 URL。
keywordsstring[]否用于提升 UI 可发现性的描述性关键字列表。

不允许其他属性。

plugin.metadata.maintainers[]
属性类型必需描述
namestring是
emailstring否
urlstring否

不允许其他属性。

plugin.spec

插件所针对的 ABI 版本、可选的签名指针以及可选的运行时块。插件的 .wasm 位置由插件的标识——其 metadata.pluginType(插槽)加上其裸 metadata.name——以及所配置的注册表推导而来;它不在 spec 中携带。

属性类型必需描述
abiVersionstring(枚举)是插件所针对的宿主/客体 ABI 版本。v1beta1 是唯一可接受的值;声明了此编译器已不再支持的 ABI 版本的 Plugin 会被拒绝,并指明应据以重新构建插件的版本。允许的值:"v1beta1"
signatureobject否指向插件所附签名的可选描述性指针。此块仅作文档用途——它为目录读者记录签名所在位置及其生成方式;它本身并不把关或准入插件。起强制作用的检查是拉取时应用的按注册表信任策略:签名作为 OCI referrer 获取,依据注册表的受信任身份或固定密钥进行验证,并作为已验证事实记录在锁文件中。要求签名的注册表在所需签名缺失、不受信任或无效时会中止拉取。
runtimeobject否宿主在加载和运行插件时应用的可选执行约束。出站网络访问不是可编写的字段:插件在构建时从不访问网络(预先编译边界),因此这里没有需要编写的宿主允许列表字段。
exportsobject[]否此插件提供的导出,每个导出都带有其声明的能力。导出是宿主分派到的一个具名入口点(例如 render_node、lint_naming、step);每个导出的能力块是对该导出所做之事的编写声明,宿主会在发布时和加载时将其与插件的自我报告进行交叉核对。条目保留编写顺序。缺省表示未声明任何编写的导出面。
commandsobject[]否由机器维护,请勿编写:由 aggrega plugin sync(或 aggrega plugin gen-catalog)根据插件的自我报告记录。CLI 插件贡献的顶层 aggrega <command> 动词从插件的自我报告中读取,并按自我报告声明的顺序记录于此,因此无需加载插件即可从实体读出 CLI 插件所安装的命令面。非 CLI 插件不贡献命令,记录为空列表。宿主恰好安装此集合;记录的集合若与插件的自我报告不一致,会在加载时中止,且发布会拒绝与二进制文件不同步的集合,并指示作者重新记录。
providerobject否pluginType: provider 插件的 provider 插槽块:它所服务的能力、它如何转换 aggrega.ai/v1beta1 Workload 类别、它读取哪些平台原生注解,以及它的渲染行为契约。仅出现在执行 provider 渲染的插件上;其他所有插件类型均无此块。
pipelineStepobject否pluginType: pipeline-step 插件的 pipeline-step 块:其步骤兼容的 provider 能力。仅出现在 pipeline-step 插件上;其他所有插件类型均无此块。
parserobject否pluginType: parser 插件的 parser 块:它转换为规范结构化树的源格式。仅出现在 parser 插件上;其他所有插件类型均无此块。
importerobject否pluginType: importer 插件的 importer 块:它转换为 Aggrega 编写文件草稿的外部源格式,以及用于识别这些格式之源的特征。仅出现在 importer 插件上;其他所有插件类型均无此块。

不允许其他属性。

plugin.spec.signature

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

属性类型必需描述
typeconst “sigstore-cosign”是签名方案。sigstore-cosign 是受支持的方案。常量:"sigstore-cosign"
signatureRefstring否所附签名包的 OCI referrer 引用,用于文档和发现。当签名在拉取时通过 referrer 枚举发现、而非在此固定时,缺省。
publicKeyRefstring否对于有密钥签名,指向生成该签名所用公钥的指针。缺省表示无密钥(OIDC 身份)签名,依据注册表的受信任身份进行验证。

不允许其他属性。

plugin.spec.runtime

宿主在加载和运行插件时应用的可选执行约束。出站网络访问不是可编写的字段:插件在构建时从不访问网络(预先编译边界),因此这里没有需要编写的宿主允许列表字段。

属性类型必需描述
maxMemoryPagesinteger否以 Wasm 页(每页 64 KiB)为单位限制插件线性内存的上限。为零或缺省时应用平台默认上限,因此加载永远不会没有上限;需要更多内存的挂载应提高此值。最小值:0。
timeoutMsinteger否限制插件自身代码在一次调用中可运行的时长,单位为毫秒,不计入在其所调用的宿主函数内部花费的时间。在 Linux 上衡量的是处理器时间,因此在繁忙机器上等待处理器的时间不计入;在其他系统上衡量的是经过时间。对新加载插件的首次调用还会计入插件自身的启动时间。为零或缺省时应用平台默认上限,因此调用永远不会无法取消;运行时间更长的挂载应提高此值。最小值:0。
hostFunctionsstring[]否由机器维护,请勿编写:插件导入的宿主函数,由 aggrega plugin sync(或 aggrega plugin gen-catalog)从 .wasm 的导入段读取,并以规范形式(已排序、已去重)记录于此。发布时会从二进制文件重新派生它们,并拒绝记录不一致的实体;拉取时会再次重新派生并验证它们。宿主仅注册这一派生集合,并根据精选的允许列表验证每个条目。
configKVmap of string否运行时在启动时传给插件的 Plugin 特定配置,形式为字符串到字符串的键/值对。条目保留作者编写的顺序,使输出的记录在多次运行之间逐字节一致。缺省时,运行时默认的空配置生效。

不允许其他属性。

plugin.spec.exports[]
属性类型必需描述
namestring是导出的 ABI 名称,即宿主分派调用的名称(例如 render_node、lint_naming、step)。长度至少为 1 个字符。
operatesstring(枚举)否此导出执行的流水线操作:patch(修改已有的渲染文档)或 emit(添加新文档)。缺省表示不声明任何操作。允许的值:"patch"、"emit"
scopestring(枚举)否此导出所操作的文档根:own(节点自身的渲染文档)或 host(组件作用域的 FeatureRecipe 所挂载到的组件的文档)。缺省表示不声明任何作用域。允许的值:"own"、"host"
selectorstring否对该导出所作用对象的自由格式、人类可读的描述(例如 workloads carrying a pod template)。供目录读者参考的文档;编译器不对其进行解释。

不允许其他属性。

plugin.spec.commands[]
属性类型必需描述
namestring是宿主注册的命令动词,即操作者调用的 aggrega <name> 令牌,也是宿主在调用时传给插件的区分符,使支撑多个命令的单个插件能够根据被调用的命令进行路由。长度至少为 1 个字符。
descriptionstring否命令的单行简短帮助文本,显示在命令列表和帮助输出中。仅作文档用途;宿主不据此执行任何操作。
flagsobject[]否命令的标志,按声明顺序排列。每个条目贡献一个宿主在该命令上注册的标志,使 aggrega help 像渲染核心命令的标志一样渲染它。没有标志的命令将其留空。在一个命令内,每个标志名称和每个简写只出现一次,且均不得复用每个 aggrega 命令都已具有的标志,即 --help、-h 以及全局标志;宿主在添加插件的命令时检查这一点,声明未通过检查的插件不会被添加,并给出警告。

不允许其他属性。

plugin.spec.commands[].flags[]
属性类型必需描述
namestring是标志的长名称,即操作者在命令行上传入的 —name 令牌。每个声明的标志都必须指定它。长度至少为 1 个字符。
shorthandstring否标志的可选短别名,即操作者可代替长名称传入的 -x 形式,为单个 ASCII 字母或数字。缺省表示该标志没有短别名。模式:^[A-Za-z0-9]$。
descriptionstring否标志的单行帮助文本,显示在命令的帮助输出中。它是可选的文档;宿主既不验证它,也不据此执行任何操作。
typestring(枚举)否标志的值类型(string、bool 或 int),也决定帮助输出将其渲染为哪种标志。缺省时渲染为字符串标志。允许的值:"string"、"bool"、"int"
defaultstring否操作者未传入该标志时的默认值,以字符串表示。对于 bool 或 int 标志,它是该类型的值。缺省表示该标志未声明默认值。

不允许其他属性。

plugin.spec.provider

pluginType: provider 插件的 provider 插槽块:它所服务的能力、它如何转换 aggrega.ai/v1beta1 Workload 类别、它读取哪些平台原生注解,以及它的渲染行为契约。仅出现在执行 provider 渲染的插件上;其他所有插件类型均无此块。

属性类型必需描述
capabilitiesstring[]否由 aggrega plugin gen-catalog 根据插件 .wasm 的自我报告记录,因此该列表的来源是插件本身。作者可以在发布前缩小该列表,删除此实体不应提供的条目,但不能添加自我报告未列出的条目:发布,以及通过 --plugin 提供插件 .wasm 的 aggrega validate,都会拒绝列出自我报告未列出之能力的列表。发布按原样发送实体,从不改写此列表,并会注明自我报告列出而该列表遗漏的每项能力。此 provider 所服务的能力——如 helm 或 compose 这样的能力名称——即它所渲染的输出形态。provider 在共享同一能力输出形态的制品之间是通用的,而非在所有能力之间通用,因此该列表是一项明确的、经过测试的兼容性声明,而非愿景。条目保留编写顺序。Recipe 请求的 provider 目标解析为其列表包含该目标的 provider 插件;被多个 provider 插件列出的目标会因歧义而中止,除非工作区配置的 plugins.providers 选择指明使用哪个插件。空列表或缺省列表不声明任何能力,因此该插件不服务任何目标。
workloadSchemastring否JSON Schema 2020-12,记录此 provider 如何将 aggrega.ai/v1beta1 Workload 类型转换为 provider 原生清单。存在时,provider 支持声明了 workload: 块的 Recipes(合成模式)——provider 将 Workload 转换为 provider 原生清单,并以此 schema 作为文档/契约参考。是否支持 workload: Recipe 取决于所绑定 provider 的合成能力,而非此字段是否存在:绑定到无法合成的 provider 的合成模式 Recipe 会在渲染时显式中止。标准库目录在可合成的 provider 上声明 workloadSchema 作为文档化契约,并与该能力保持同步。该字段是文档化契约:其内容在加载时编译为 JSON Schema 2020-12 以检查格式是否正确,此外没有任何东西读取它。
wellKnownAnnotationsobject[]否provider 的支持声明:此 provider 读取的平台原生知名注解键(aggrega.ai/ 命名空间),每个键附带其读取的作用域以及缺省时应用的行为。仅在 provider 确实读取某个键时才声明它——公开的支持矩阵由这些声明渲染生成,因此此处列出的键,就是作者可以预期会在其指定作用域内改变渲染输出的键。编译器以两种方式读取该声明:若 scope 指定的输入类型不在 provider 自身 contract.inputKinds 的声明之中,则与同一实体中的相邻声明相矛盾,构建会中止并指出该键及矛盾之处;若某个 aggrega.ai/ 注解经由此 provider 到达某次渲染,而该渲染声明的任何输入类型上都没有条目涵盖它,构建会发出警告。它不同于管辖在保留的 aggrega.ai/ 前缀下绑定值的规则。缺省表示不声明任何支持,也不会为此 provider 发出此类警告;不读取任何这些键的 provider 则声明 readsNoWellKnownAnnotations,而不是此列表。条目为有序列表,并保留编写顺序。
readsNoWellKnownAnnotations常量 true否声明此 provider 不读取 aggrega.ai/ 命名空间中的任何平台原生注解键,即原本会在 wellKnownAnnotations 中列出的那些键:这是一个不涵盖任何键的支持声明,是一种明确的表态,而同时省略此字段和 wellKnownAnnotations 则是沉默。此后,构建会针对每个经由此 provider 到达某次渲染的 aggrega.ai/ 注解发出警告,并指出该键、该 provider 以及该渲染声明的输入类型;该值仍原封不动地通过,构建也不会中止。只能写 true,因此省略该字段仍是不作任何表态的唯一方式。它不能与 wellKnownAnnotations 同时编写:读取部分键的 provider 改为在那里列出这些键。常量:true
contractobject否provider 自行声明的渲染行为契约:它渲染的输入类型、如何汇编一个分派组的逐节点输出以及该输出位于哪些目录下、它应用于导入制品文件的模板分隔符对、一个已加载实例是否可服务每次跨越、是否连接跨边界的边、是否遵循 omit 条目、是否接受 Recipe 向其边界共享输出贡献的文件,以及其生态系统从不随源一同分发哪些文件。它是 provider 插件自我报告在发布时的记录,宿主会在发布时和加载时将其与该自我报告进行交叉核对。缺省表示不声明渲染行为契约,此时交叉核对仅比较逐导出的声明。

不允许其他属性。

plugin.spec.provider.wellKnownAnnotations[]
属性类型必需描述
keystring是provider 读取的平台原生知名注解键(例如 aggrega.ai/namespace)。位于平台保留的 aggrega.ai/ 注解命名空间之下——即由 provider 读取的平台指令。模式:^aggrega\.ai/.+。
purposestring是该注解控制的内容——即其存在时所影响的渲染行为。
defaultBehaviorstring否此注解缺省时 provider 应用的行为。
scopestring (enum)[]否此 provider 读取该键的位置。前三个值是 Recipe 输入类型,指明读取该键的渲染路径——sourced 为一个 vendored 文件集,synthesized 为由 provider 实体化的 Workload,artifactsStandalone 为整个输出均为导入制品文档的节点。其中每一个都必须是此 provider 的 contract.inputKinds 所声明的输入类型;指定未声明的类型会中止构建。boundary 用于每个边界而非每个节点解析一次的键——即汇编制品的名称,或构造跨边界引用所依据的放置上下文——此时输入类型不是有意义的维度,因此不与 contract.inputKinds 匹配。在多条路径上读取的键需列出每一条路径。缺省表示不作逐路径声明:不进行任何检查,该键仅表明 provider 会在某处读取它。至少 1 个条目。任何条目不得出现两次。每个条目允许的值:"sourced"、"synthesized"、"artifactsStandalone"、"boundary"。

不允许其他属性。

plugin.spec.provider.contract

provider 自行声明的渲染行为契约:它渲染的输入类型、如何汇编一个分派组的逐节点输出以及该输出位于哪些目录下、它应用于导入制品文件的模板分隔符对、一个已加载实例是否可服务每次跨越、是否连接跨边界的边、是否遵循 omit 条目、是否接受 Recipe 向其边界共享输出贡献的文件,以及其生态系统从不随源一同分发哪些文件。它是 provider 插件自我报告在发布时的记录,宿主会在发布时和加载时将其与该自我报告进行交叉核对。缺省表示不声明渲染行为契约,此时交叉核对仅比较逐导出的声明。

属性类型必需描述
inputKindsobject否该插件渲染三种 Recipe 输入类型中的哪几种:sourced 文件集、合成的 workload,以及独立的仅含 artifacts 的节点。每个字段都是一项独立的声明。
boundaryAssemblystring(枚举)否插件如何组合一个分发组中各节点的渲染输出:none 将每个节点的输出直接写入分发路径;merge 将各节点的片段合并为一个文档;nest 将每个节点的输出放在一个总括结构中它自己的位置下。缺省时不作任何组装声明。允许的值:"none"、"merge"、"nest"
artifactDelimitersobject否插件应用于导入的 artifact 文件的 Go 模板分隔符对。缺省时表示默认的 {{/}} 分隔符对;目标语法与该分隔符对冲突的插件在此声明另一对分隔符。
assemblyNameAnnotationobject否一个边界注解,其解析后的值为插件从分发组组装出的 artifact 命名。将一个组中参与的各边界合并为一个具名组装结果的插件,声明它读取的注解键,以及是否要求每个参与的边界在该注解的解析值上保持一致。缺省时表示插件仅根据分发路径为其组装结果命名。
reusableInstance布尔值否是否可以由一个已加载的插件实例服务于一次构建中的每次 render、assemble 和 validate 调用,而不是每次调用都使用新实例。仅当插件在各次调用之间不保留任何状态(即它是其单次调用输入的纯函数)时才声明为 true,这样无论复用还是重新加载,单个实例都会产生逐字节相同的输出。缺省(false)时每次调用都加载新实例,从而隔离那些在构造上就带有状态的插件。
crossBoundaryLinking布尔值否插件是否连接跨边界的 uses 边(即消费端与被消费端组装到不同分发组中的 uses 边),方式是通过成对的 link_publish/link_resolve 导出契约生成 provider 原生的交叉引用连接。仅当插件同时导出这两者时才声明为 true;与导出对不符的声明会在加载时中止。缺省(false)时不声明跨边界链接,因此宿主不会将任何 link 调用路由到该插件。
omits布尔值否provider 是否遵循 omit 条目(即指定要从节点输出中排除的渲染单元的条目):它会将条目匹配到的每个单元排除在渲染结果之外,并报告每个条目匹配了多少个单元。它是 provider 自我报告所作 omits 声明在发布时的记录,与该报告不一致的值会在加载时中止。缺省(false)时表示不声明此类支持。
boundaryArtifacts布尔值否provider 是否接受 Recipe 在其 spec.boundary.artifacts 下为其所渲染边界的共享输出贡献的文件:编译器将每个此类文件写入一次,放在存放该边界组装输出的目录中,provider 的目标将其视为该输出的一部分。它是 provider 自我报告所作 boundary_artifacts 声明在发布时的记录,与该报告不一致的值会在加载时中止。缺省(false)时表示不声明此类支持,为该 provider 声明此块的 Recipe 会在任何渲染开始前被拒绝。
nestSegmentstring否对于 boundaryAssembly 为 nest 的 provider,该 provider 的目标将每个贡献者自己的子目录放在其下的目录,例如 chart 总括结构使用 charts,根模块使用 modules。编译器将此目录、贡献者名称和每个文件自身的路径拼接起来。仅对嵌套型 provider 读取。缺省时将每个贡献者的子目录直接放在边界自身的目录下。该值只命名一个目录,而绝不是路径。
sourceIgnoreobject否该 provider 的生态系统从不随其渲染的源一起发布的文件,以 gitignore 语法的忽略规则表示,是其自我报告所声明的 source_ignore 规则在发布时的记录。当作者固定一个由该 provider 为其服务相应能力的 Recipe 或 FeatureRecipe 时,这些规则会与作者自己的 .aggregaignore 组合,并连同该插件的名称一起记录在实体旁的 entity.lock 中,此后对该实体本地源的每次发布、比较和渲染都会应用所记录的规则。存在时,它必须与自我报告所声明的内容相同,加载会拒绝报告不一致的插件;缺省时不作声明,也不进行比较。

不允许其他属性。

plugin.spec.provider.contract.inputKinds

该插件渲染三种 Recipe 输入类型中的哪几种:sourced 文件集、合成的 workload,以及独立的仅含 artifacts 的节点。每个字段都是一项独立的声明。

属性类型必需描述
sourced布尔值否渲染引入的文件集(chart、模块、compose 文件)。
synthesized布尔值否将合成的工作负载渲染为 provider 原生制品。
artifactsStandalone布尔值否渲染独立的纯制品节点——即携带导入的制品文档、不含 source 或工作负载的节点。

不允许其他属性。

plugin.spec.provider.contract.artifactDelimiters

插件应用于导入的 artifact 文件的 Go 模板分隔符对。缺省时表示默认的 {{/}} 分隔符对;目标语法与该分隔符对冲突的插件在此声明另一对分隔符。

属性类型必需描述
leftstring是开始定界符。
rightstring是结束定界符。

不允许其他属性。

plugin.spec.provider.contract.assemblyNameAnnotation

一个边界注解,其解析后的值为插件从分发组组装出的 artifact 命名。将一个组中参与的各边界合并为一个具名组装结果的插件,声明它读取的注解键,以及是否要求每个参与的边界在该注解的解析值上保持一致。缺省时表示插件仅根据分发路径为其组装结果命名。

属性类型必需描述
annotationstring是插件从中读取组装制品名称的边界注解键。
requireUnique布尔值否参与同一分发组的每个边界是否必须在该注解的解析值上一致。为 true 时,若一个组中参与的边界将该注解解析为不同的值,构建将中止;为 false 时,插件接受第一个解析值。

不允许其他属性。

plugin.spec.provider.contract.sourceIgnore

该 provider 的生态系统从不随其渲染的源一起发布的文件,以 gitignore 语法的忽略规则表示,是其自我报告所声明的 source_ignore 规则在发布时的记录。当作者固定一个由该 provider 为其服务相应能力的 Recipe 或 FeatureRecipe 时,这些规则会与作者自己的 .aggregaignore 组合,并连同该插件的名称一起记录在实体旁的 entity.lock 中,此后对该实体本地源的每次发布、比较和渲染都会应用所记录的规则。存在时,它必须与自我报告所声明的内容相同,加载会拒绝报告不一致的插件;缺省时不作声明,也不进行比较。

属性类型必需描述
patternsstring[]否该生态系统自身的忽略模式,每个模式都限定于本地 source 目录的根,按其生效顺序排列。
filesstring[]否该生态系统在 source 内部遵循的忽略文件的名称——对于 chart 是 .helmignore。每个此类文件的各行是进一步的模式,限定于包含该文件的目录。

不允许其他属性。

plugin.spec.pipelineStep

pluginType: pipeline-step 插件的 pipeline-step 块:其步骤兼容的 provider 能力。仅出现在 pipeline-step 插件上;其他所有插件类型均无此块。

属性类型必需描述
capabilitiesstring[]否由 aggrega plugin gen-catalog 从插件 .wasm 的自报告中记录,因此该列表的来源是插件本身。作者可以在发布前缩小该列表,删除此实体不应提供的条目,但不得添加自报告中未列出的条目:发布以及通过 --plugin 传入插件 .wasm 的 aggrega validate 都会拒绝列出自报告中未列出的能力的列表。发布会按原样发送实体,从不改写此列表,并会注明自报告列出但该列表遗漏的每项能力。该插件的流水线步骤所兼容的 provider 能力,即 helm 或 compose 等 provider 能力名称,该步骤知道如何转换其渲染输出。一个步骤每次只针对一个 provider 的输出形态编写,因此该列表是一项明确的、经过测试的兼容性声明,而非愿景。条目保留作者给出的顺序。它是该声明在目录中可读的记录;当步骤作用于某个作用域时,构建会从插件读取同一声明,如果渲染该作用域文档的 provider 不在其中,构建将中止。列表为空或缺省时表示不作兼容性声明,因此没有任何作用域接纳该步骤。

不允许其他属性。

plugin.spec.parser

pluginType: parser 插件的 parser 块:它转换为规范结构化树的源格式。仅出现在 parser 插件上;其他所有插件类型均无此块。

属性类型必需描述
capabilitiesstring[]否由 aggrega plugin gen-catalog 从插件 .wasm 的自报告中记录,因此该列表的来源是插件本身。作者可以在发布前缩小该列表,删除此实体不应提供的条目,但不得添加自报告中未列出的条目:发布以及通过 --plugin 传入插件 .wasm 的 aggrega validate 都会拒绝列出自报告中未列出的能力的列表。发布会按原样发送实体,从不改写此列表,并会注明自报告列出但该列表遗漏的每项能力。该解析器转换为规范结构化树的源格式,每项写作 parse:<format>,例如 parse:yaml。前缀是条目的一部分,因此声明多种格式的插件会为每种格式列出一个条目。条目保留作者给出的顺序。请求的格式解析到列表中包含匹配条目的解析器;没有任何解析器声明的格式会中止构建,由多个解析器插件声明的格式会因歧义而中止。列表为空或缺省时表示不作格式声明,因此该插件不解析任何内容。

不允许其他属性。

plugin.spec.importer

pluginType: importer 插件的 importer 块:它转换为 Aggrega 编写文件草稿的外部源格式,以及用于识别这些格式之源的特征。仅出现在 importer 插件上;其他所有插件类型均无此块。

属性类型必需描述
capabilitiesstring[]否由 aggrega plugin gen-catalog 从插件 .wasm 的自报告中记录,因此该列表的来源是插件本身。作者可以在发布前缩小该列表,删除此实体不应提供的条目,但不得添加自报告中未列出的条目:发布以及通过 --plugin 传入插件 .wasm 的 aggrega validate 都会拒绝列出自报告中未列出的能力的列表。发布会按原样发送实体,从不改写此列表,并会注明自报告列出但该列表遗漏的每项能力。此导入器转换为 Aggrega 草稿编写文件的外部源格式,每项写作 import:<format>——例如 import:terraform。前缀是条目的一部分,因此一个声明多种格式的插件为每种格式列出一个条目。条目保留作者顺序。请求的导入格式解析到其列表包含匹配条目的导入器;没有任何导入器声明的格式会使导入中止,而由多个导入器插件声明的格式会因歧义而中止,除非工作区配置中的 plugins.importer 条目挂接其中之一,此时运行该导入器。列表为空或缺失表示不声明任何格式,因此该插件不导入任何内容。
detectobject[]否由机器维护,请勿手写:在从插件的 .wasm 自报告生成实体时派生,并按自报告声明的顺序记录于此。当导入未指定格式时,用于识别此导入器格式的源的签名。aggrega import 读取工作区目录所含每个导入器(包括每个版本)以及编译器核心导入器的签名,在不了解任何格式含义的情况下将它们与源进行匹配,并将源按签名匹配的唯一导入器的格式读取;没有签名匹配的源会被拒绝并要求指定格式,而有多个格式的签名匹配的源会被拒绝并列出这些格式。导入器识别某个源时,会将其识别为它声明的每一种格式,因此声明多种格式的导入器的每次匹配都会因歧义而被拒绝。存在时,该列表必须逐项且按顺序等于插件自报告所声明的内容,加载和发布会拒绝报告不一致的插件,并指出此字段。缺失时不作声明也不进行比较,此时只能通过指定格式名称来使用该导入器的格式。

不允许其他属性。

plugin.spec.importer.detect[]
属性类型必需描述
syntaxstring是源被解析所用的语法格式——例如 json 或 yaml——即解析器插件以 parse:<syntax> 声明的格式。源通过工作区目录为该语法提供的解析器进行解析;对于目录未提供解析器的语法,则通过编译器自带的解析器解析。无论有多少签名指定该语法,最多只解析一次,且无法以该语法解析的源不匹配任何指定该语法的签名。若两者都不为某语法提供解析器,识别会停止,并指出缺少该解析器。长度至少为 1 个字符。
filesstring[]否签名适用的文件名模式,与源名称的末尾进行匹配,其中的分隔符按正斜杠读取:单段模式与文件自身的名称匹配,由斜杠分隔的多段模式与其路径末尾相同数量的段匹配,因此 .vscode/mcp.json 匹配位于名为 .vscode 的目录中、名为 mcp.json 的文件。在一个段内,* 匹配任意字符序列,? 匹配一个字符,[...] 匹配某个字符类中的一个字符。任一模式匹配时签名即适用。缺失或为空时,签名适用于单个文件构成的源(无论其名称为何),而不适用于目录中的任何文件。导入器签名的模式还决定 aggrega import 将目录中的哪些文件交给它。
matchobject[]否解析后的树必须按声明顺序全部满足的谓词。缺失或为空时,除能以该语法解析外,对树没有任何要求。

不允许其他属性。

plugin.spec.importer.detect[].match[]
属性类型必需描述
pathstring是谓词在树中查找的位置,写作从树的顶层开始以点连接的键:data.nodes 指顶层 data 对象的 nodes 成员。写作 0 或更大整数的段从零开始计数,选择数组中的该位置,因此 nodes.0.type 指第一个节点的 type;其他每个段都选择对象的一个成员。长度至少为 1 个字符。
isstring(枚举)是路径必须到达的内容:present 在路径到达任意类型的值(包括 null)时成立;absent 在路径未到达任何内容时成立;object、array、string、number 和 boolean 分别在路径到达该类型的值时成立。允许值:"present", "absent", "object", "array", "string", "number", "boolean"
equalsstring否路径所到达的值必须与之完全相等的字符串;不是字符串的值永远不等于它。一个谓词上最多声明 equals 和 prefix 中的一个。长度至少为 1 个字符。
prefixstring否路径所到达的值必须以之开头的字符串;不是字符串的值永远不会以它开头。一个谓词上最多声明 equals 和 prefix 中的一个。长度至少为 1 个字符。

不允许其他属性。