Aggrega Wasm 导入器插槽 schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/wasm-import-v1beta1.schema.json
导入器插件插槽所消费(ImportInput)和输出(ImportOutput)的传输形态。导入器将外部基础设施描述转换为 Aggrega 实体:它读取指定格式的源字节,将每个源节点映射为一个目录实体,并返回它输出的实体、它做出的映射决策、它产生的诊断信息,以及它生成的脚手架文件。导入器在其描述符中以 import:
以下形态之一
ImportInputImportOutput
定义
ImportInput
importer guest 接收的载荷:选择如何读取字节的源格式、主源字节及读取这些字节的文件名、多文件导入时的任何具名源、使用方为 importer 特定行为提供的可选不透明选项文档、工作区目录所含 Components 的视图,以及导入为之起草的目标。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
format | string | 是 | 要导入的源格式名称,与 importer 声明的某个 import: |
bytes | string | 是 | 要导入的主源字节,importer 按所命名的格式读取:导入的源为单个文件时为整个文件;源为目录时为空,目录中的文件改为以具名源传入。每个工具包以自己的字段类型承载这些字节——该类型为字节类型时为原始字节,为字符串时为 base64 编码,由 importer 解码还原——生成的编码器在该字段与线路传输字节所用的形式之间进行转换。 |
name | string | 否 | 导入源的名称,前面不带目录,以便 importer 在其报告的内容和起草的内容中指明该源。源为单个文件时,它是该文件的基本名称:主字节不作为具名源到达,因此这是它们携带的唯一名称。源为目录时,它是该目录的基本名称,目录中的文件仍作为具名源到达,各自带有自己的名称,而主字节为空。源没有可提供的名称时不存在。 |
sources | ImportSource[] | 否 | 具名源,各自携带自己的字节,放在一个按名称排序的列表中。导入的源为目录时,importer 声明的文件模式所选中的每个文件对应一项,以其在目录内用斜杠分隔的路径命名。配置该 importer 的挂载在 with.sources 下声明的文件也在此承载,各以其基本名称命名;若从目录读取的某个文件与其中某个文件同名,宿主将拒绝该导入。两者均未提供任何源时不存在。 |
settings | any | 否 | 使用方为 importer 特定行为提供的不透明导入选项文档。宿主原样传递而不加解释;importer 读取其自身文档所述的任意形态。使用方未提供选项时不存在。 |
catalog | CatalogProjection | 否 | 工作区自身目录(即选出该 importer 的目录)所含 Components 的视图,使 importer 在将源节点映射到目录实体时可将它们作为候选进行权衡。宿主仅根据该本地目录构建它,且只携带名称、版本、标签和声明的结构:从不携带值、默认值或密钥。其顺序固定,因此同一目录产生同一字节序列。目录中没有 Component 时不存在。 |
target | string | 否 | 导入为之起草的提供程序能力,例如 compose 或 helm:即为导入指定的目标;对于刷新先前某次导入且自身未指定目标的导入,则为先前那次导入所记录的目标。importer 将仅该目标所需的内容作为声明写入草稿,并略去仅其他目标所需的内容。宿主在检查工作区目录中有某个 Recipe 绑定到该目标后,按原样传递它。导入未指定目标时不存在。 |
不允许其他属性。
CatalogProjection
importer 所见的工作区目录:目录所含的每个 Component 对应一项,各自携带 importer 为候选评分时所权衡的元数据。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
components | CatalogComponent[] | 是 | 目录所含的每个 Component 名称对应一项,按名称排序。目录中包含某个 Component 的多个版本时,其条目描述的是不带版本地引用该 Component 时所解析到的版本。 |
不允许其他属性。
CatalogComponent
工作区目录中的一个 Component:其名称和版本、标签、其 values 和 provides 声明的键名,以及它为依赖声明的插槽。扩展另一个 Component 的 Component 既携带自身声明的内容,也携带其继承的内容。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 该 Component 的名称,即其 metadata.name 所声明的名称——Aggregate 引用它所用的名称。 |
version | string | 是 | 该 Component 的版本,即其 metadata.version 所声明的版本。 |
labels | map of string | 否 | 该 Component 的标签,为字符串到字符串的映射。没有标签时不存在。 |
values | string[] | 否 | 该 Component 的 values 声明的顶层键名,已排序。仅为名称列表:从不携带值或默认值。其 values 未声明任何键时不存在。 |
provides | string[] | 否 | 该 Component 的 provides 声明的顶层键名,已排序。仅为名称列表:从不携带值。其 provides 未声明任何键时不存在。 |
sockets | CatalogSocket[] | 否 | 该 Component 为其依赖声明的插槽,按声明顺序排列:对于扩展另一个 Component 的 Component,继承的插槽在前,按被扩展 Component 的声明顺序排列,其后是它新增的插槽。未声明任何插槽时不存在。 |
不允许其他属性。
CatalogSocket
目录中某个 Component 为其依赖声明的一个插槽:插槽名称,以及通过它连接的依赖必须满足的标签选择器。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 插槽名称,即该 Component 的 usesSchema 所声明的名称。 |
selector | string | 是 | 插槽的标签选择器,原样保留,采用该 Component 编写时所用的 Kubernetes 风格语法:通过此插槽连接的依赖必须携带的标签。 |
不允许其他属性。
ImportSource
多文件或目录导入中的一个具名源:定位该源的名称及其自身的字节。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 此源在导入中的名称,例如相对文件路径。 |
bytes | string | 是 | 此源的字节。每个工具包以自己的字段类型承载这些字节——该类型为字节类型时为原始字节,为字符串时为 base64 编码,由 importer 解码还原——生成的编码器在该字段与线路传输字节所用的形式之间进行转换。 |
不允许其他属性。
ImportOutput
importer guest 返回的载荷:导入产生的实体、其背后的映射决策、导入引发的任何诊断信息,以及它产生的任何脚手架文件。每个字段都是可选的,因此未解析出任何内容的导入可以只返回诊断信息。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
entities | EmittedEntity[] | 否 | 导入产生的实体,每个要么是对现有目录实体的引用,要么是起草的实体主体。导入未输出任何实体时不存在。 |
decisions | ImportDecision[] | 否 | 导入做出的映射决策,每个已解析的源节点对应一项,记录所权衡的候选和所做的选择。导入未记录任何决策时不存在。 |
diagnostics | Diagnostic[] | 否 | 导入引发的诊断信息——例如未解析的源节点或有歧义的映射。导入未产生任何诊断信息时不存在。 |
files | ScaffoldFile[] | 否 | 导入随实体一同产生的脚手架文件,例如入门 aggregate 或 readme。导入未产生任何文件时不存在。 |
error | string | 否 | 当 guest 已运行但无法完成操作时设置的失败消息;成功时不存在。它与输出携带的任何诊断信息不同:诊断信息报告的是仍产生了结果的运行中发现的问题,而 error 报告的是操作本身未能完成。宿主将存在的 error 呈现为一次失败的插件调用。 |
不允许其他属性。
EmittedEntity
导入产生的一个实体:其种类、名称及输出方式——对现有目录实体的引用,或新起草的实体主体。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
kind | string | 是 | 所输出实体的种类。核心 importer 输出 Component、Aggregate 和 Release;读取方应容忍任何其他种类。 |
name | string | 是 | 所输出实体的名称。 |
mode | string(枚举) | 是 | 实体的输出方式:reference 按名称指向现有目录实体,draft 携带新起草的实体主体。允许的值:"reference"、"draft" |
body | string | 否 | 起草实体的原始 YAML 主体。对于纯引用为空,纯引用指名现有实体而非起草实体。 |
labels | map of string | 否 | 附加到所输出实体的标签,为字符串到字符串的映射。核心 importer 将其留空。 |
annotations | map of string | 否 | 附加到所输出实体的注解,为字符串到字符串的映射。核心 importer 将其留空。 |
sourceRef | string | 否 | 对该实体所源自的源节点的引用,使读取方可将实体追溯到其在导入源中的出处。 |
decisionRef | string | 否 | 对产生该实体的映射决策的引用,将其与所权衡的候选和所做的选择关联起来。 |
不允许其他属性。
ImportDecision
一个映射决策:导入器解析的源节点、它权衡的候选目录实体、它选中的候选,以及该选择背后的理由。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
sourceNode | DecisionSourceNode | 是 | 此决策解析的源节点:导入器从源中读取并映射到某个目录实体的节点。 |
candidates | ImportCandidate[] | 否 | 导入器为此源节点权衡的候选目录实体,每个都附带其得分以及该得分背后的逐信号明细。导入器未权衡任何候选时不存在。 |
chosen | DecisionChoice | 否 | 导入器为此源节点选中的候选,以及它的输出方式。导入器未做出选择时不存在。 |
rationale | string | 否 | 导入器做出此选择的原因的人类可读说明。 |
swapHint | string | 否 | 描述如何将所选映射替换为其他方案的提示,以便读者修改该决策。 |
不允许其他属性。
DecisionSourceNode
映射决策解析的源节点:一个标识符、源为其命名的类型,以及其参数的人类可读摘要。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
id | string | 是 | 源节点在导入源中的标识符。 |
type | string | 是 | 源节点的类型,即源为其命名的类型。 |
paramsSummary | string | 是 | 源节点参数的人类可读摘要,用于与决策一同显示。 |
不允许其他属性。
ImportCandidate
导入器为某个源节点权衡的一个候选目录实体:候选组件、其总得分、该得分所属的匹配等级,以及该得分背后的逐信号明细。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
componentName | string | 是 | 候选目录组件的名称。 |
score | number | 是 | 候选的总匹配得分,由逐信号明细汇总而得。 |
tier | string | 是 | 候选所属的匹配等级,即基于得分划分的粗略区间。 |
signals | CandidateSignals | 是 | 候选得分背后的逐信号明细。 |
不允许其他属性。
CandidateSignals
候选得分背后的逐信号明细:每个匹配信号一项贡献值。这是一个字段固定的对象,因此信号集合保持稳定,线上格式是确定性的。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
table | number | 是 | 来自映射表信号的得分贡献。 |
category | number | 是 | 来自类别信号的得分贡献。 |
domainLabels | number | 是 | 来自领域标签信号的得分贡献。 |
shape | number | 是 | 来自结构形态信号的得分贡献。 |
name | number | 是 | 来自名称信号的得分贡献。 |
不允许其他属性。
DecisionChoice
映射决策选中的候选:目标目录实体、其输出方式,以及该选择的匹配等级。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
target | string | 是 | 所选目标目录实体的名称。 |
mode | string | 是 | 所选目标的输出方式,与输出实体的模式一致:对现有实体的引用,或新起草的实体主体。 |
tier | string | 是 | 所选目标的匹配等级。 |
不允许其他属性。
ScaffoldFile
导入产生的一个脚手架文件:相对于导入输出根目录的路径,以及该文件的内容。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
path | string | 是 | 脚手架文件的路径,相对于导入输出根目录。 |
content | string | 是 | 脚手架文件的内容。 |
不允许其他属性。