Aggrega Wasm Describe Socket schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/wasm-describe-v1beta1.schema.json
每个 Wasm 插件从其 describe() 导出返回的传输形态(PluginDescriptor)。describe() 是插件的自我声明,宿主在加载插件时读取一次,内容包括:guest 所绑定的 ABI 版本、插件类型、插件提供的导出及每个导出的能力声明、插件级的能力自我报告、可选的 provider 渲染行为契约、可选的 importer 识别契约、可选的 CLI 命令、可选的设置 schema,以及可选的作者元数据。同一个形态涵盖所有插件类型——provider、linter、feature-recipe-pipeline 步骤、governance、CLI、parser 和 importer。宿主在分派任何其他导出之前先读取 describe(),并拒绝它无法接纳的描述符,而不是在分派时错误地调用该插件。
以下形态之一
PluginDescriptor
定义
PluginDescriptor
插件的完整自我声明,由 describe() 返回,并在加载时读取一次。它包含 ABI 兼容性握手、插件类型、所提供的导出,以及可选的按类型划分的接口面(provider 的渲染行为契约、importer 的识别契约、CLI 插件的命令、设置 schema、作者元数据)。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
abi_version | const “v1beta1” | 是 | guest 所绑定的插件 ABI。宿主只接受此版本;针对任何其他 ABI 构建的 guest 会在加载时被拒绝,而不会在分派时被错误调用。常量:"v1beta1" |
plugin_type | string(枚举) | 是 | 插件的种类。它决定宿主校验的最小导出规则,并与导出名称一起决定默认的输入传递模式。governance 插件承担构建流水线中的转换和裁决角色;决定它可以输出什么的是它所挂接的角色,而不是它的种类。允许的值:"provider"、"linter"、"pipeline-step"、"governance"、"cli"、"parser"、"importer" |
capabilities | string[] | 否 | 插件所服务的对象。该列表在传输格式中是扁平的,由相邻的必需字段 plugin_type 决定每个条目属于四种含义中的哪一种:对于 provider,是其渲染的输出形态所对应的 capability 名称(如 helm 或 compose);对于 feature-recipe-pipeline 步骤,是该步骤兼容的 provider capability;对于 parser,是它转换为规范结构化树的源格式,每项写作 parse: |
exports | PluginExport[] | 是 | 插件提供的导出,按声明顺序排列。宿主会校验按类型要求的最小导出是否存在,并在调用每个导出之前绑定该导出对应的宿主接口面。 |
contract | ProviderContract | 否 | provider 的渲染行为自我报告:它渲染的输入种类、它如何组装分派组的逐节点输出,以及它应用的 artifact 模板分隔符对。它描述的是整个 provider,而不是任何单个导出。对于不声明渲染行为契约的插件,此项缺失。 |
importer | ImporterContract | 否 | importer 的自我报告,说明在导入未指定格式时,如何识别属于其所声明格式的源。只有 plugin_type 为 importer 的插件可以声明它;任何其他插件声明它都会在加载时被拒绝。对于未声明识别方式的 importer,此项缺失,其格式只能通过显式指定来使用。 |
description | string | 否 | 插件自身对其功能的单行可读描述,区别于各导出的描述和实体的元数据描述。它仅供参考;宿主既不验证它,也不据此执行任何操作。 |
commands | PluginCLICommand[] | 否 | CLI 插件提供的顶层 aggrega 命令动词,每个都有自己的简短帮助行。一个 CLI 插件可以提供多个命令;宿主为每个条目注册一个命令,并在调用时将解析出的命令名称传给 guest。非 CLI 插件此项留空。 |
settings_schema | object | 否 | 插件声明的可选 JSON Schema 文档,用于为其挂接所携带的、由操作者提供的设置定义类型。存在时,宿主在加载时编译它,并在分派时、调用插件之前根据它验证挂接的设置;不符合的设置会中止构建。缺失时,插件不声明任何形态,设置按原样传递。该 schema 是插件自身的自由格式声明;宿主对其执行通用的 JSON Schema 验证,不解读设置的含义。 |
metadata | PluginDescriptorMeta | 否 | 可选的作者和构建来源信息。它不包含任何行为契约,宿主既不验证它,也不据此执行任何操作。 |
不允许其他属性。
PluginExport
插件提供的一个导出,在 describe() 中声明。宿主按名称分派到该导出,并绑定该导出所声明的宿主函数所需的最小权限宿主接口面。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 导出的 ABI 名称,例如 render_node、assemble_boundary、lint_rules 或 step。宿主按此名称分派到该导出。 |
input_pattern | string(枚举) | 否 | 宿主传递导出输入的方式:b 内联传递完整载荷,guest 仅凭载荷即可渲染;a 传递一个小载荷,由 guest 通过宿主函数补充。省略此字段的导出采用其插件类型和名称对应的默认值。允许的值:"a"、"b" |
host_functions | string[] | 否 | 此导出导入的宿主函数名称。每个名称都必须在宿主函数允许列表中。该声明具有权威性,并会在加载时与 guest 实际从其模块导入的函数进行交叉核对,因此不会与 guest 真正调用的函数产生偏差。 |
description | string | 否 | 描述该导出的可选可读文本。它是供目录读者参考的文档;宿主既不验证它,也不据此执行任何操作。 |
stability | string(枚举) | 否 | 导出的稳定性级别。省略该值表示不声明稳定性。允许的值:"stable"、"experimental"、"deprecated" |
operates | string(枚举) | 否 | 此导出执行的流水线操作:patch 修改已有的渲染文档,emit 添加新文档。该值在加载时进行形态检查;运行时在分派该步骤时读取它。允许的值:"patch"、"emit" |
scope | string(枚举) | 否 | 此导出操作的文档根:own 是节点自身的渲染文档,host 是 component 作用域的 feature recipe 所挂接的 component 的文档。该值在加载时进行形态检查;运行时在分派时解析该作用域的文档。允许的值:"own"、"host" |
selector | string | 否 | 对该导出所作用对象的自由格式可读描述。它是供目录读者参考的文档;宿主既不验证其内容,也不据此执行任何操作。 |
input | object | 否 | step 导出声明的可选 JSON Schema 文档,用于为流水线条目通过其 with 块提供的步骤本地输入定义类型。存在时,它描述步骤的 with 输入所满足的形态;缺失时,该导出不声明任何输入契约。该 schema 是导出自身对流水线作者针对此导出所面向的输入接口面的自由格式声明。 |
output | object | 否 | step 导出声明的可选 JSON Schema 文档,用于为其在一个步骤中返回的输出定义类型,即步骤提供给后续步骤或模板读取的可寻址输出的形态。存在时,它描述这些返回输出的形态;缺失时,该导出不声明任何输出契约。该 schema 是导出自身对其产生的输出接口面的自由格式声明。 |
不允许其他属性。
PluginCLICommand
CLI 插件提供的一个顶层 aggrega 命令动词,在 describe() 中声明。宿主为每个条目注册一个命令,并在调用时将解析出的命令名称传回 guest,因此单个 guest 可以支撑多个命令,并根据名称选择其行为。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 宿主注册的命令动词,即操作者调用的 aggrega 令牌,也是宿主交给 guest 的判别值,使其能根据被调用的命令进行路由。每个声明的命令都必须指定它。 |
description | string | 否 | 命令的单行简短帮助文本,显示在命令列表和帮助输出中。它是可选的文档;宿主既不验证它,也不据此执行任何操作。 |
flags | PluginCommandFlag[] | 否 | 命令的标志,按声明顺序排列。每个条目提供一个由宿主在该命令上注册的标志,使 aggrega help |
不允许其他属性。
PluginCommandFlag
CLI 插件在某个命令上声明的一个标志,在 describe() 中报告。宿主将其注册到该命令上,使 aggrega help
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 标志的长名称,即操作者在命令行上传入的 —name 令牌。每个声明的标志都必须指定它。长度至少为 1 个字符。 |
shorthand | string | 否 | 标志可选的单字符短别名,即操作者可以代替长名称传入的 -x 形式。缺失表示该标志没有短别名。 |
description | string | 否 | 标志的单行帮助文本,显示在命令的帮助输出中。它是可选的文档;宿主既不验证它,也不据此执行任何操作。 |
type | string | 否 | 标志的值类型,例如 string、bool 或 int。缺失时不声明任何类型。 |
default | string | 否 | 操作者未传入该标志时的默认值,以字符串表示。缺失表示该标志不声明默认值。 |
不允许其他属性。
PluginDescriptorMeta
插件在 describe() 中声明的可选作者信息和构建来源元数据。它仅供参考;宿主不验证它,也不据此执行任何操作。version 和 commit 字段是在构建时写入 guest 的构建来源信息;未写入这些信息的构建会省略它们。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
author | string | 否 | 插件的作者。 |
repository | string | 否 | 插件的源代码仓库。 |
license | string | 否 | 插件的许可证标识符。 |
version | string | 否 | 构建时写入 guest 的构建来源版本。未写入构建来源信息的构建会省略它。 |
commit | string | 否 | 构建 guest 所基于的构建来源短 commit。未写入构建来源信息的构建会省略它。 |
不允许其他属性。
ProviderContract
provider 对其在所渲染的各节点上执行的编译期渲染行为的自我声明:它接受的输入类型、是否以及如何将一个分派组的逐节点输出组装为单个产物、它应用于导入的产物文件的 Go 模板分隔符对、它是否接受 Recipe 向其边界共享输出贡献的文件,以及其生态系统从不随源一起分发的文件。它描述的是整个 provider,而不是某一个导出。加载关卡会将其与实体中编写的声明进行交叉核对。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
input_kinds | InputKinds | 是 | 插件渲染三种 Recipe 输入类型中的哪些:有源文件集、合成的 workload,以及独立的仅含产物的节点。 |
boundary_assembly | string(枚举) | 是 | 插件如何组合一个分派组的逐节点渲染输出:none 将每个节点的输出直接写入分派路径,merge 将逐节点片段合并为一个文档,nest 将每个节点的输出放在一个总括结构中其各自的位置下。空值不声明任何组装方式。允许的值:"none"、"merge"、"nest"、"" |
artifact_delimiters | ArtifactDelimiters | 否 | 插件应用于导入的产物文件的 Go 模板分隔符对。缺失表示使用默认的开始/结束分隔符对;目标语法与该分隔符对冲突的插件在此报告另一组分隔符对。 |
assembly_name_annotation | AssemblyNameAnnotation | 否 | 一个边界注解,其解析后的值为插件从分派组组装出的产物命名。缺失表示插件仅根据分派路径为其组装结果命名。 |
reusable_instance | 布尔值 | 否 | 是否可以由一个已加载的插件实例处理构建中的每一次渲染、组装和验证调用,而不是每次调用使用一个新实例。仅当插件在各次调用之间不保留任何状态时,才将其声明为 true。缺失(false)是安全的默认值:宿主为每次调用加载一个新实例。 |
cross_boundary_linking | 布尔值 | 否 | 插件是否通过其 link_publish 和 link_resolve 导出生成 provider 原生的交叉引用连接,从而连接跨边界的 uses 边,即消费端和被消费端组装到不同分派组中的边。仅当插件同时导出这两者时,才将其声明为 true。缺失(false)是安全的默认值:插件不连接任何跨边界的边。 |
omits | 布尔值 | 否 | 插件是否遵循 render_node 输入所携带的 omit 条目:它将条目匹配的每个渲染单元排除在其返回的所有内容之外,并在输出的 omitted 中为传给它的每个条目报告一个计数。仅当插件两者都做到时,才将其声明为 true。缺失(false)是安全的默认值:插件不声明会排除任何内容。 |
boundary_artifacts | 布尔值 | 否 | 插件的目标是否接受 Recipe 向其渲染所在边界的共享输出贡献的文件。宿主对这些文件求值,并将每个文件写入一次,写入保存该分派组组装输出的目录中,与插件组装写入的内容并列;这些文件均不传给插件,插件也不读取它们,因此该声明表示其目标将放置在那里的文件视为边界输出的一部分。缺失(false)是安全的默认值:为该插件声明此类文件的 Recipe 会在任何渲染开始之前被拒绝。 |
nest_segment | string | 否 | 对于嵌套分派组逐节点输出的插件,其目标在该目录下放置每个贡献者各自的子目录。宿主将此段、贡献者的编写级名称以及每个文件自身的路径拼接起来。仅当 boundary_assembly 为 nest 时才读取。缺失时,宿主将每个贡献者的子目录直接放在分派位置,不带外层目录。该值只命名一个目录,绝不是路径:包含路径分隔符或指向当前目录或父目录的值会被拒绝,因为宿主会将贡献者的名称拼接进去,而路径片段会使贡献者的文件被放到分派位置之下以外的地方。 |
source_ignore | SourceIgnore | 否 | 该插件的生态系统从不随其渲染的源一起分发的文件,以忽略规则声明。当作者固定一个由该插件为其提供能力的 Recipe 或 FeatureRecipe 时,宿主读取该声明:它将这些规则与作者自己的忽略文件组合,将组合后的规则记录在实体旁的实体锁中,此后该实体的每次发布、其本地源的每次比较以及它的每次渲染都应用所记录的规则,而不再询问插件。因此,为某项能力发布的 Recipe 携带其发布者规则所保留的文件;当插件使用相同的 ABI 版本、其契约与其实体的声明相符,且不需要该集合之外的任何文件时,插件即可渲染它。需要该集合遗漏的文件的插件必须让其构建明确失败并指出该文件;宿主的职责是拒绝打包或读取集合中不包含的文件,并指出该文件。缺失时不声明任何忽略规则,此时插件渲染的源保留作者自己的规则所保留的每个文件。 |
不允许其他属性。
SourceIgnore
插件的生态系统应用于源目录的忽略规则,采用 gitignore 语法:不含斜杠或仅含末尾斜杠的模式匹配任意深度的名称;含有其他斜杠的模式从其作用目录的根开始解读;末尾斜杠仅匹配目录;开头的 ! 恢复先前规则所排除的内容。规则按顺序应用,后面的匹配覆盖前面的匹配。被规则排除的目录不会被进入,因此除非先恢复该目录本身,否则其下的任何内容都不会恢复。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
patterns | string[] | 否 | 生态系统自身的忽略模式,每个模式均作用于所遍历的本地源目录的根,按应用顺序排列。缺失或为空表示不声明任何模式。 |
files | string[] | 否 | 生态系统在源内部遵循的忽略文件的名称,例如 chart 的 .helmignore。在遍历源时,只要找到具有这些名称之一的文件,就会将其各行作为同一语法的附加模式读取,每个模式作用于保存该文件的目录,并在上述模式之后应用;空行和以 # 开头的行会被跳过。具有此类名称的文件本身会被保留,除非有规则将其排除。缺失或为空表示不指定任何文件名。 |
不允许其他属性。
InputKinds
插件渲染哪些 Recipe 输入类型。每个字段都是一项独立的声明;插件可以报告任意组合。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
sourced | 布尔值 | 是 | 插件是否渲染有来源的文件集(chart、模块、compose 文件)。 |
synthesized | 布尔值 | 是 | 插件是否渲染合成的 workload。 |
artifacts_standalone | 布尔值 | 是 | 插件是否渲染独立的仅含制品的节点,即携带导入的制品文档、但没有来源或 workload 的节点。 |
不允许其他属性。
ArtifactDelimiters
插件对导入的制品文件应用的 Go 模板定界符对,在与默认定界符对不同时报告。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
left | string | 是 | 开始定界符。 |
right | string | 是 | 结束定界符。 |
不允许其他属性。
AssemblyNameAnnotation
其解析值为插件的组装制品命名的边界注解,在插件将一个分发组中参与的各边界合并为一个具名组装结果时报告。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
annotation | string | 是 | 插件从中读取组装制品名称的边界注解键。 |
require_unique | 布尔值 | 否 | 参与同一分发组的每个边界是否必须在该注解的解析值上一致。为 true 时,若一个组中参与的边界将该注解解析为不同的值,构建将中止;为 false 时,插件接受第一个解析值。 |
不允许其他属性。
ImporterContract
导入器在公布其格式之外对这些格式所做的声明:用于识别这些格式的来源的签名。当一次导入未指定格式时,宿主读取该导入可从中选择的每个导入器所记录的签名(即工作区目录中的导入器以及编译器的核心导入器,其 Plugin 实体由二进制文件携带),在不了解任何格式含义的情况下将每个签名与来源进行匹配,并按签名匹配的那一个导入器的格式读取该来源。没有任何签名匹配的来源会被拒绝,并要求指定格式;有多个格式的签名匹配的来源会被拒绝,并列出这些格式。Plugin 实体记录同一列表,宿主会拒绝 describe() 报告与该记录不符的导入器。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
detect | DetectSignature[] | 否 | 按声明顺序排列、用于识别此导入器格式的来源的签名;只要其中任意一个匹配,来源即被识别。被某个导入器识别的来源会被识别为该导入器公布的每一种格式,因此公布多种格式的导入器的每次匹配都会因歧义而被拒绝,而其来源需要被识别的导入器应只公布一种格式。缺失或为空时不声明任何签名,此时只能通过指定名称来使用该导入器的格式。 |
不允许其他属性。
DetectSignature
识别来源的一种方式:读取来源所用的语法、签名适用的文件名,以及解析后的树必须满足的谓词。它匹配这样的文件:其名称与它的某个文件模式匹配(若它未声明任何模式,则为任意名称的单文件来源),其字节能以它的语法解析,且其解析后的树满足它的每一个谓词。当它匹配某个目录中由其模式选中的某个文件时,它即匹配该目录,因此未声明模式的签名不匹配任何目录。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
syntax | string | 是 | 解析来源所用的语法格式,例如 json 或 yaml,即解析器插件以 parse: |
files | string[] | 否 | 签名适用的文件名模式,与来源名称的末尾进行匹配,其中分隔符按正斜杠读取:单段模式与文件自身的名称匹配,由斜杠分隔的多段模式与其路径末尾相同数量的段匹配,因此 .vscode/mcp.json 匹配名为 .vscode 的目录中名为 mcp.json 的文件。在一个段内,* 匹配任意长度的字符序列,? 匹配一个字符,[…] 匹配某个字符类中的一个字符。只要任一模式匹配,签名即适用。格式不正确的模式在加载时被拒绝。缺失或为空时,签名适用于任意名称的单文件来源,而不适用于目录中的任何文件。导入器各签名的模式也决定一次导入将目录中的哪些文件交给它。 |
match | PathMatch[] | 否 | 解析后的树必须按声明顺序全部满足的谓词。缺失或为空时,除能以该语法解析外,对树没有任何要求。 |
不允许其他属性。
PathMatch
针对解析后的树的一个谓词:路径所到达的值、该值必须属于的种类,以及(可选)该值必须等于或以之开头的字符串。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
path | string | 是 | 谓词在树中查看的位置,写作从树顶层开始以点连接的键:data.nodes 指顶层 data 对象的 nodes 成员。写作 0 或更大整数的段从零开始计数,选择数组的对应位置,因此 nodes.0.type 指第一个节点的 type;其他每个段选择对象的一个成员。本身包含点的键无法被指定。长度至少为 1 个字符。 |
is | string(枚举) | 是 | 路径必须到达的内容:present 在路径到达任意种类的值(包括 null)时成立;absent 在路径未到达任何值时成立;object、array、string、number 和 boolean 分别在路径到达该种类的值时成立。允许的值:"present"、"absent"、"object"、"array"、"string"、"number"、"boolean" |
equals | string | 否 | 路径所到达的值必须完全等于的字符串。非字符串的值永远不等于它。一个谓词上最多声明 equals 和 prefix 中的一个,同时声明两者的谓词在加载时被拒绝。长度至少为 1 个字符。 |
prefix | string | 否 | 路径所到达的值必须以之开头的字符串。非字符串的值永远不以它开头。一个谓词上最多声明 equals 和 prefix 中的一个,同时声明两者的谓词在加载时被拒绝。长度至少为 1 个字符。 |
不允许其他属性。