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

致命中止

致命中止是一种编译期错误,它会在产生任何输出之前终止构建。每个中止都会指明出错的文件、实体和字段,说明编译器无法解析的内容,并指出修复它的具体编写改动。编译器从不静默地修复或改写你的输入——如果有问题,构建就会停止并告诉你问题所在。

本目录按每个中止发生时所处的编译阶段组织。

下面每个条目都引用了构建针对其所记录的条件打印的消息:先是陈述该条件的固定语句,然后是该次出现所提供的内容。在终端中,这条消息出现在一个框架内——一个带方括号的头部,包含类别和该条件的短代码;一个指向出错文件和键的指针,其后以 (instance <name>) 的形式给出该失败所涉及的实例(在不涉及文件时,则只有该实例,形式为 instance <name>);以及下一行的消息——因此从构建中粘贴的整行不会与这里的条目匹配,而其中的消息会匹配;error-translation.md 完整说明了该框架。

如果你从构建中带着一个短代码而来——即诊断信息方括号头部中的字母 E 加四位数字——请从本页底部的根据构建打印的短代码查找中止开始,那里列出了此处收录的每个条件及构建为其打印的短代码。

加载文件时

编译器读取构建所引用的每个 Aggregate、Manifest、Component、Feature、Recipe、FeatureRecipe、Plugin 和 Release,按各自的 schema 校验每一个,并将 Release 中的类型化参数插值到 Aggregate 中。

YAML anchor aliased inside its own content(YAML 锚点在其自身内容中被别名引用)

文档用 &name 为一个节点设置锚点,然后在该锚点所覆盖内容中的某处用 *name 对其进行别名引用。展开该别名会重现该锚点,而锚点的内容又包含该别名,因此文档描述的是一个没有尽头的结构。没有任何有限的内容可以读取,更不用说校验,因此构建会停止,而不是开始一次无法完成的遍历。

将 YAML 读取为树时不会展开别名,因此这种形态的文档读取时不会报错,只有在被遍历时才会失败。因此拒绝发生在读取与遍历之间——而构建会在不止一处读取所编写的 YAML,所以同一条件可能在不止一处遇到。有四处会报告它,每处都用该位置上用于定位文档的信息来包装同一段说明:

  • 实体文件,在读取时。 构建在该实体按其 schema 校验之前停止,因此该中止指出的是锚点而非字段,且不带行号和列号:此时文档还没有可供诊断有效指向的位置。
  • schema 主体,在编译时。 spec.schema: 数据支柱在其文件被读取之后才从紧凑形式编译为 JSON Schema 文档,因此该中止在编译期间而非编译之前触发,并且带有行号。较早的读取无法捕获的形态是 $jsonschema: 逃生舱口主体:在读取外围文件时,逃生舱口主体是一个块标量——纯文本,不含锚点——其锚点只有在该文本本身被解析时(下降一层)才成为锚点。如果循环位于这样的块中,该中止还会将 $jsonschema 指为其主体包含该循环的关键字。
  • 提供程序 Plugin 的 workload schema,在 Plugin 加载时。 spec.provider.workloadSchema 以块标量编写:读取 Plugin 文件本身时它是纯文本,此时不含锚点,其锚点只有在该文本作为独立文档被解析时(下降一层)才成为锚点。该解析及随后的编译都发生在 Plugin 加载时,因此该中止在那时触发,而不是在读取文件时,并且带有行号。如果循环位于 schema 主体中的 $jsonschema: 逃生舱口内,该中止还会将 $jsonschema 指为其主体包含该循环的关键字。该字段的编写方式参见 ../entities/plugin.md。
  • 渲染后的 CloudFormation 片段,在提供程序读取时。 cloudformation Recipe 编写的是片段,而 artifacts: 主体是模板——因此提供程序读取的是该模板渲染出的文本,这些内容在读取你的文件时尚不存在。因此该中止在渲染输出时触发,此时所有 schema 检查都已通过。片段的编写方式参见 ../providers/cloudformation.md。

被拒绝的是递归,而绝非复用或深度。为共享内容设置锚点并从多处引用它是受支持的编写模式——参见 ../entities/aggregate.md 中的“YAML anchor patterns (defs: block)”和 ../entities/manifest.md 中的“YAML anchors for DRY manifests”——能够展开并终止的引用会正常加载,无论它出现多少次、文档嵌套多深;深度本身绝不是该中止的原因。导致中止的是在构建仍处于某锚点内部时又到达该锚点,包括通过其下声明的第二个锚点间接到达的情况。消息指出的是循环闭合回到的那个锚点,它不一定是文档中最外层的锚点。

输出的消息。 四处都带有相同的说明,这是有意为之:它是在四处遇到的同一个条件,作者学会读懂一次后不应再重新学习。不同的只是定位文档的外框。

anchor &<anchor> is aliased by *<anchor> inside its own content, so the document expands without end; point that alias at content declared outside &<anchor>, or write the content out in full(锚点在其自身内容中被别名引用,因此文档会无限展开;请将该别名指向在该锚点之外声明的内容,或完整写出该内容)

实体文件由正在读取它的信封检查以及读取它的路径来包装:

document envelope validation failed: envelope: parse <path>: <the explanation above>(文档信封校验失败:信封:解析该路径时出错:附上述说明)

schema 主体由其在 schema 中的位置包装,当循环位于 $jsonschema: 块内时还由该逃生舱口关键字包装。构建在 CATALOG_ERROR 标签下报告它,该标签还会指出文件、实体以及主体编译失败的数据支柱:

compactform at <schema-path>:<line> (keyword "$jsonschema"): <the explanation above>(紧凑形式出错,位于该 schema 路径及行号处,附关键字及上述说明)

提供程序 Plugin 的 workload schema 带有同样的紧凑形式外框;不同的是其外围的 CATALOG_ERROR 标签,它指出的是 Plugin 和 spec.provider.workloadSchema,而不是实体及其数据支柱。

渲染后的片段由读取它的提供程序包装:

cloudformation-provider: parse fragment: <the explanation above>(cloudformation-provider:解析片段时出错,附上述说明)

修复方法: 将别名指向在其当前所在锚点之外声明的内容,或在使用处完整写出重复的内容。在 Aggregate 或 Manifest 上,根级 defs: 块是共享锚点的自然位置——它位于所有引用它的块之外,因此在那里声明的锚点无法从其自身内部到达。在没有 defs: 块的其他实体类型上,将共享内容的锚点设在引用块的祖先以外的某处。锚点可以从任意多处、任意深度被引用;它唯一不能采取的形态,是引用落回该锚点所覆盖的内容之内。

无论在何处遇到该中止,补救方法都相同,外框会告诉你该打开哪个文档:实体文件本身、schema 数据支柱中的 $jsonschema: 块、提供程序 Plugin 中的 workloadSchema 主体,或者提供程序读取了其渲染输出的 artifacts: 主体。在最后一种情况下,锚点位于你编写的模板中,而不在渲染后的文本中——渲染只是如实地重现了它。

Parameter type mismatch / contract violation (参数类型不匹配 / 违反契约)

Release 提供的值,其类型或结构与 Aggregate 为该参数声明的不一致。参数契约校验器会在任何模板插值运行之前,捕获类型不匹配、枚举违规、范围违规、模式违规、不是其声明 format 有效实例的字符串、validate: 谓词失败以及缺失的必需参数。format 可取的名称及各自的检查内容,列在命名格式下。

输出的消息——先是陈述该条件的句子,然后是出错的实体、字段路径和约束详情:

parameter contract violated (Aggregate, at .spec.parameters.<parameter>, parameter "<parameter>" expected type <declared type>; got <received type>)(违反参数契约:参数的类型与声明的类型不符)

对于声明了 required: true、没有 default: 且 Release 未提供值的参数,报告会给出不同的条件和不同的短代码:

required parameter not supplied (Aggregate, at .spec.parameters.<parameter>, parameter "<parameter>" is required but not supplied by Release)(未提供必需参数:该参数为必需,但 Release 未提供)

只有字段路径之后的详情会随未满足的约束而变化。 句子及其外围的括号框架每次都相同,因此句子是用于匹配的部分,详情是用于阅读的部分。构建输出的详情如下,每种约束一条:

parameter "<parameter>" value <value> not in enum [<members>](参数值不在枚举中) parameter "<parameter>" value "<value>" does not match pattern "<pattern>"(参数值与模式不匹配) parameter "<parameter>" value "<value>" is not a valid <format>: <reason>(参数值不是有效的格式) parameter "<parameter>" value <value> above max <max>(参数值超过最大值) parameter "<parameter>" failed validate predicate(参数未通过 validate 谓词) parameter "<parameter>" validate predicate error: <detail>(参数的 validate 谓词出错)

格式失败的 <reason> 以该格式自身的术语说明值的问题。嵌套契约中的值以其路径命名,因此 items: 契约声明的 format 会在每个元素上检查,报告会指出失败的那个元素:hosts 参数的第二个元素报告于 .spec.parameters.hosts.1,其详情指出 "hosts.1"。

声明了 validateMessage: 的参数会用自己的文本替换整个详情,因此报告为 parameter contract violated (Aggregate, at .spec.parameters.<parameter>, <the validateMessage you wrote>)——框架不变,你写的句子位于约束详情原本所在的位置。

同一条件也涵盖按所写内容无法约束任何东西的契约。不是有效正则表达式的 pattern: 会在读取 Aggregate 的参数契约时被拒绝,早于检查任何 Release 值,因此无论 Release 是否提供该参数,它都会中止构建。报告指向该键——.spec.parameters.<parameter>.pattern,或穿过嵌套契约的路径,如 .spec.parameters.<parameter>.items.pattern——其详情指出声明、模式和原因:

parameter "<parameter>" pattern "<pattern>" does not compile: <reason>(参数的模式无法编译)

指定受支持集合之外格式的 format: 同样无法约束任何东西,它在同一时刻被拒绝,早于检查任何 Release 值,因此无论 Release 是否提供该参数,它也会中止构建。在嵌套契约中——位于 items:、properties: 或 valuesType: 下——拒绝它的正是这一条件:报告指向该键,如 .spec.parameters.<parameter>.items.format,其详情指出声明、所写的格式以及所有受支持的名称:

parameter "<parameter>.items": format "<format>" is not supported; the supported formats are email, uri, hostname, ipv4, ipv6, uuid, date-time, date(不支持该格式;支持的格式为 email、uri、hostname、ipv4、ipv6、uuid、date-time、date)

在参数自身的声明上,同一名称会提前一步被 Aggregate 的 schema 拒绝,该 schema 的 format 只接受受支持的名称。这一拒绝是文档未通过其类型的 schema——一个不同的条件,有自己的短代码 E0215——aggrega pull 和 aggrega validate --release 会在报告 Release 的 aggregate: 引用无法解析(E0170)之后列出它,因为携带该名称的 Aggregate 未能加载:

document envelope validation failed (Aggregate, at <path>); <line>:<column>: spec.parameters.<parameter>.format: enum: <format> does not equal any of: [email uri hostname ipv4 ipv6 uuid date-time date]. correct the document to match its kind’s schema(文档信封校验失败:format 的值不等于任何受支持的格式。请修正文档,使其符合其类型的 schema)

谓词错误详情涵盖 validate: 谓词无法得出判定的两种情况:调用了该表面未注册的函数,以及引用了 .value 以外的内容。两者都针对谓词而非值报告,并指出无法解析的内容。

validate: 谓词以 .value 读取待校验的值,这是它定义的唯一名称。引用其他任何名称的谓词会在运行前被拒绝,因此拼错的引用会被如实报告为命名错误,而不会解析为空、进而表现为校验失败的值。

修复方法: 修改 Release 值以符合参数声明的 type / enum / min / max / pattern / format 约束;提供缺失的必需参数;修正无法编译的 pattern:;将指定不受支持格式的 format: 替换为命名格式之一或将其删除;修正引用 .value 以外内容或渲染结果不是 true 或 false 的 validate: 谓词;或放宽 Aggregate 的声明,以接受你实际需要的结构。

Recipe 形状规则

Recipe 由三种输入类型组合出其输出——sourced、synthesized 和 artifacts——详见 ../../architecture/16-recipe-input-composition.md。有效 Recipe 的形状受下列组合规则约束。这些规则的检查时机各不相同——在加载 Recipe 时、在节点渲染时,或在发出输出时——因此请阅读每一条目,了解其条件在何时检查。

每条规则都以其约束的对象命名。规则没有编号,也没有保留编号:名称指明应打开 Recipe 的哪一部分,并且无论下面的列表如何增长或重新排序,它都始终如此。需要持久记录某个条件时——在 CI 关卡、issue 或运行手册中——请使用其代码,即 sentinels.md 为该条件列出的标识符,它在周围的软件包演进时保持不变。

Recipe 形状类终止的消息也以相同方式组成。它以陈述规则的句子开头,然后指出该 Recipe 提供了什么,最后是针对它的细节:

<the rule's sentence>(Recipe <name>:<version>,规则 <rule-name>,位于 <position>)。<rule-specific detail>

开头的句子对每条规则是固定的——无论哪个阶段检测到,该规则每次终止时都是同样的文本——因此它是输出中用来匹配的部分,也是 sentinels.md 为该规则的条件列出的文本。其后的所有内容随出错的 Recipe 而变化:括号中的值说明是哪个文档、按名称是哪条规则以及位置,结尾的句子则是针对该次出现的建议。当规则针对整个文档时,位置是加载该 Recipe 的文件;当规则针对其中的某一项时,位置是指向你所写键的点分路径——.spec.outputComponentLabels.hosting;自身带有点的键无法写成多一个路径段而不被同样读作两个段,因此路径止于包含它的块,并由建议引用该键。

构建在 CATALOG_ERROR 标签下打印整行,表示该失败归因于目录实体(Recipe 或其绑定的 provider),而非 Aggregate 或 Release。加载该 Recipe 的文件打印在标签旁边,因此定位到某个键的规则仍会告诉你应打开哪个文件。

valuesMapping requires source(valuesMapping 需要 source)

某个 Recipe 声明了 valuesMapping,但没有声明 source。没有可叠加的 source,映射的值就无处接收。此规则在加载 Recipe 时检查。

发出的消息:

Recipe: valuesMapping requires source (Recipe <name>:<version>, rule values-mapping, at <path>). declare a source: pointer alongside valuesMapping (or remove the valuesMapping if no overlay is intended)(Recipe:valuesMapping 需要 source。请在 valuesMapping 旁声明 source: 指针;若无意进行覆盖,则移除 valuesMapping)

**修复方法:**在 valuesMapping 旁添加一个 source: 指针(chart、module 或 compose 文件引用),或删除 valuesMapping 并改用其他输入类型(workload: 用于合成输出,artifacts: 用于直接发出清单)。

workload: requires a provider that can synthesize(workload: 需要能够进行合成的 provider)

某个 Recipe 为一个未实现 Workload 合成的 provider 声明了 workload:(合成模式)。是否支持合成模式是 provider 的属性——按照约定,标准库目录会在具备合成能力的 provider 上声明 workloadSchema,但检查依据的是 provider 的能力,而不是该字段是否存在。

有两个界面报告它,而只有其中一个决定构建结果。该终止在渲染时引发,即节点的 provider 绑定之后、其 Recipe 声明的输入类型被读取之后,因此该报告指出的是节点。aggrega validate 更早报告同一发现,在任何节点绑定之前单独读取 Recipe——因此该报告指出的是 Recipe 及其版本。两者读取的 Recipes 集合并不相同:早期报告针对任何声明了 workload: 的 Recipe 引发,而终止针对节点声明的、其 provider 无法支持的每一种输入类型引发。因此,同时具有 workload: 和 source: 的 Recipe 仍会终止,且因 workload 而终止——声明一种 provider 能渲染的输入类型,并不能让不受支持的类型通过检查。

对此唯一的限制是:只有当 artifacts: 是节点唯一声明的类型时,才会根据独立 artifacts 支持检查它。与 source: 或 workload: 并存时,其文件作为组合输出随之传递,不受该能力约束。

渲染时发出的消息。失败所归属的类别出现在诊断的方括号头部中,而不在消息内部。消息以陈述条件的固定句子开头,然后指出节点、provider、被拒绝的声明类型,以及该 provider 支持的类型。当一个节点声明了两种其 provider 无法支持的类型时,报告按 source → workload → artifacts 顺序中的第一种,使该发现只关乎你的 Recipe 中的一行:

provider does not support the node’s input kind (node "<node-id>"). provider "<provider-name>" does not support <mode> recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports <mode>(provider 不支持该节点的输入类型。该 provider 不支持此模式的 recipe;请声明其支持的输入类型之一,或改用支持该模式的 provider)

头部带有类别和此条件的短代码 E0265,当你需要持久地命名此终止时——在持续集成关卡、issue 或运行手册中——应记录的就是这个标识符。编号一经分配即固定不变,因此无论其周围的措辞如何改进,它都保持不变;所有条件的表格可以解析它;当你依据文本而非标识符排查时,上面的开头句子就是用于匹配的部分。

aggrega validate 在包含该块的 Recipe 下报告同一条款,以读取它的界面作为前缀,并以该条件的短代码开头,因为这一早期报告就是同一条件:

input-kind: [E0265] Recipe "<name>:<version>": provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized(输入类型:该 provider 不支持合成式 recipe;请声明其支持的输入类型之一,或改用支持合成的 provider)

对整个目录进行检查时,这是一行;使用 --release 时,头部单独位于该条款上方的一行。编辑器针对同一发现给出的诊断以 E0265 作为其代码。

**修复方法:**将 Recipe 绑定到能够合成的 provider(最常见的是 helm 或 compose),或将 Recipe 迁移到其他输入类型(artifacts: 用于直接发出清单;如果存在 chart/module,则使用 source: + valuesMapping:)。

按 provider 的 Workload 内容校验。 目前 provider 的 workloadSchema 仅用于文档,并不校验 Workload 主体;主体依据平台拥有的内嵌 Workload schema 进行校验。基于 Wasm 的 Workload 合成器发布后,workloadSchema 将成为按 provider 的契约,合成器依据它校验 Workload 主体(一种独立的、内容层面的中止)。

The provider does not support omits(provider 不支持 omits)

某个 Recipe 或 FeatureRecipe 声明了 omits:,而渲染它的 provider 并未声明自己会略去已渲染的文档。从 source 渲染的内容中略去某个文档只有 provider 能做到——只有 provider 知道 source 会渲染哪些文档以及每个文档的名称——因此不支持此功能的 provider 会渲染条目所列出的每个文档并报告成功。构建会在任何内容渲染之前拒绝,从而确保该键绝不会悄无声息地不起作用。

provider 是否会略去文档,是从 provider 自身关于其支持能力的声明中读取的,而不是从编译器维护的 provider 列表中读取。每个条目都会计入,无论其 when: 渲染为何,因为 provider 能否遵循该键并不取决于构建保留了哪些条目。helm、compose 和 cloudformation provider 会遵循该键。helm-chart 和 terraform 会将其 source 交由部署时渲染,因此构建时不存在可略去的已渲染文档,两者都会被拒绝。

一旦每个 component 的 Recipe 和每个 attachment 的 FeatureRecipe 都已绑定,且每个 provider 都已描述自身,就会判定是否拒绝——这发生在第一个 component 渲染之前、任何条目求值之前,因此在此被拒绝的构建不会渲染任何内容。每个渲染 source 的文档都会接受此检查:component 的 Recipe;attachment 在 component 上绑定的 FeatureRecipe,对携带该 attachment 的每个 component 各检查一次;以及为 boundary 生成一次的 FeatureRecipe,在声明它的 boundary 处检查一次。所有出错的文档会在一次构建中全部报告;出错文档不止一个时,结果归组在 documents declaring omits whose provider does not honour them 之下。绑定到构建无法解析的 provider 的文档不会在此报告:该构建会在选择 provider 时中止,并指出该绑定。

输出的消息:对于 Recipe 的条目,定位到 components: 下该 component 自身的键(写在 subsystem 内的 component 会先定位到该 subsystem 的键下);对于 component 上的 FeatureRecipe 的条目,定位到写下该 attachment 的 features: 块中该 attachment 的键;对于为其 boundary 生成一次的 FeatureRecipe,定位到 Release 中的 .spec.boundaries.<boundary>.features.<attachment>。类别通过方括号中的头部传达给你;消息先指出 provider,再指出该文档为之渲染的 component:

provider does not support omits ("<provider-name>", node "<node-id>"). this provider’s contract does not declare that it leaves rendered documents out; remove the omits key, or render the source through a provider whose contract declares it(provider 不支持 omits(provider 及节点如上)。该 provider 的契约未声明它会略去已渲染的文档;请删除 omits 键,或通过契约声明了这一点的 provider 渲染该源)

FeatureRecipe 的结果会在 component 之后指出 attachment——node "<node-id>", attachment "<attachment>"——而为其 boundary 生成一次的 FeatureRecipe 则以 boundary 和 attachment 代替 component:boundary "<boundary>", attachment "<attachment>"。

头部携带此情况的短代码 E0335。

**修复方法:**移除 omits: 键,或通过遵循该键的 provider 渲染该 source。若 helm-chart 或 terraform Recipe 的 source 是本地 chart 或 module,可在 Recipe 旁的 .aggregaignore 中添加一行,从下次固定该 Recipe 起略去该 source 中的某个文件——参见 aggrega pin。

The provider does not support boundary artifacts(provider 不支持 boundary artifacts)

某个 Recipe 声明了 spec.boundary.artifacts——用于其所在 boundary 共享输出的文件——而渲染它的 provider 并未声明接受此类文件。编译器会自行写入这些文件,放在 provider 为该 boundary 组装的内容旁边,且不会将其中任何文件交给 provider,因此放在那里的文件是否有意义取决于 provider 的目标。不读取它的目标会将其发布却忽略它,其携带的配置永远不会生效;因此构建会在任何内容渲染之前拒绝。

provider 是否接受这些文件,是从 provider 自身关于其支持能力的声明中读取的,而不是从编译器维护的 provider 列表中读取。任何条目都会计入,无论它会渲染为何。terraform provider 接受这些文件,并将每个文件写在 boundary 的根配置旁;helm、compose、helm-chart 和 cloudformation 不接受,会被拒绝。

一旦每个 component 的 Recipe 都已绑定,且每个 provider 都已描述自身,就会判定是否拒绝——这发生在第一个 component 渲染之前、任何条目求值之前,因此在此被拒绝的构建不会渲染任何内容。所有出错的 Recipe 会在一次构建中全部报告,对其渲染的每个 component 各报告一次;结果不止一个时,归组在 Recipes declaring boundary artifacts whose provider does not accept them 之下。绑定到构建无法解析的 provider 的 Recipe 不会在此报告:该构建会在选择 provider 时中止,并指出该绑定。

输出的消息,定位到 Recipe 中的 .spec.boundary,即需要修改之处。类别通过方括号中的头部传达给你;消息先指出 provider,再指出该 Recipe 为之渲染的 component:

provider does not support boundary artifacts ("<provider-name>", node "<node-id>"). this provider’s contract does not declare that it accepts files written to a boundary’s shared output; remove the boundary block, or render the Recipe through a provider whose contract declares it(provider 不支持边界制品(provider 及节点如上)。该 provider 的契约未声明它接受写入边界共享输出的文件;请删除 boundary 块,或通过契约声明了这一点的 provider 渲染该 Recipe)

头部携带此情况的短代码 E0351。

**修复方法:**移除 boundary: 块,或通过接受它的 provider 渲染该 Recipe。属于 component 而非 boundary 的文件应改为 artifacts: 条目。

At least one input kind must be present(必须至少存在一种输入类型)

某个 Recipe 未声明任何输入类型:没有与 valuesMapping 配对的 source,没有 workload:,也没有 artifacts:。这样的 Recipe 不产生任何输出,也没有渲染面。此规则在加载 Recipe 时检查。

这种形状的 Recipe 文件会先遇到 Recipe schema:该 schema 在每个 provider 上都要求 source、valuesMapping、workload 或 artifacts 之一,因此在该规则运行之前,文档信封检查就会以 E0215 拒绝该文件,并为每个键给出一个分支:

document envelope validation failed (Recipe, at <path>); <line>:<column>: spec: no anyOf branch matched: branch[0]: validation: required: missing properties: [“source”]; branch[1]: validation: required: missing properties: [“valuesMapping”]; branch[2]: validation: required: missing properties: [“workload”]; branch[3]: validation: required: missing properties: [“artifacts”]. correct the document to match its kind’s schema(文档信封校验失败(Recipe):spec 中没有匹配的 anyOf 分支:分支 0 缺少必需属性 “source”;分支 1 缺少必需属性 “valuesMapping”;分支 2 缺少必需属性 “workload”;分支 3 缺少必需属性 “artifacts”。请更正文档,使其符合其类型的 schema)

发出的消息:

Recipe: at least one input kind required (Recipe <name>:<version>, rule input-kinds, at <path>). declare one of: source (with valuesMapping), workload, artifacts(Recipe:至少需要一种输入类型(Recipe、规则 input-kinds 及位置如上)。请声明以下之一:source(配合 valuesMapping)、workload、artifacts)

修复方法: 添加与 Recipe 编写意图相符的输入类型。用于构建不负责供应的服务(已在别处运行的数据库或 API)的 Recipe,应声明一个 form: reference 的 workload: 及其 endpoint(以及可选的 port),并像任何 Recipe 一样在 provides: 下发布其连接值:helm 将其渲染为 ExternalName Service,compose 不为其渲染任何内容,而在这两者上,其使用方都会读取所发布的值。

artifacts: 条目键必须唯一

某个 Recipe 在 artifacts: 下声明了两个或更多具有相同键的条目。键决定输出的文件名(无论条目主体是内联编写还是通过每个条目的 $import: 加载);重复的键会向同一 boundary 目录输出同名文件。

构建会在将文档解码为其类型化形式时拒绝该 Recipe,并指出重复的键及其再次出现的行。该步骤在信封 schema 检查之后、形状规则之前运行,因此带有重复 artifacts: 键的 Recipe 会先报告 schema 有效,然后报告此中止,其余形状规则不会对其报告。

**修复方法:**重命名其中一个冲突的条目键,使每个 artifacts: 条目都有唯一的文件名。

Emission-time filename collision across input kinds(输出时跨输入类型的文件名冲突)

Recipe 和 FeatureRecipe 各自声明会生成文件的输入类型:由 provider 渲染的 source:、由 provider 合成的 workload:、artifacts: 条目,以及其步骤可能输出文件的 pipeline:。它们各自独立选择输出名称,且没有任何声明保证这些名称互不相同,因此其中两个可能以同一名称生成文件,而两者中只有一个会保留下来。构建会中止,并给出该输出名称以及生成它的每个块。

该检查对每个输出文档运行一次,在该文档自身的输出完成之后、其输出加入任何组装之前进行。有三种文档会输出,并各自单独检查:组件自身的 Recipe、附加项绑定在组件上的 FeatureRecipe,以及边界作用域附加项绑定的 FeatureRecipe。将它们分开,诊断才能指出正确的文档——附加项的文件以其宿主组件的身份渲染,因此附加项 FeatureRecipe 中的冲突会针对该 FeatureRecipe 报告,而不是针对宿主。

每个冲突名称单独报告,因此若一个文档的块在两个名称上冲突,会报告两项。每项发现都定位到你为修复它而需编辑的文档:对 Recipe 定位到组件实例,对附加项定位到 FeatureRecipe 本身,其发现还会指出该附加项——一个组件或边界可能绑定多个附加项。

一个块以同一名称输出多个文件不属于此中止。那是单个贡献者,而非两个块相遇;同一块内重复的 artifacts: 键会在解码文档时被拒绝。

发出的消息:

filename collision across input kinds: two input-kind blocks produced a file under one output name (output name <filename>, produced by <origin1>, <origin2>)(跨输入类型的文件名冲突:两个输入类型块以同一个输出名称生成了文件,并给出该输出名称及生成它的各个块)

FeatureRecipe 中的冲突还会带上附加项:

filename collision across input kinds: two input-kind blocks produced a file under one output name (output name <filename>, produced by <origin1>, <origin2>, attachment <instance>)(跨输入类型的文件名冲突:两个输入类型块以同一个输出名称生成了文件,并给出该输出名称、生成它的各个块及所属附件)

**修复方法:**在你所控制的输入类型中重命名冲突的文件。如果冲突涉及由 Workload 转换而来的文件名和一个 artifacts: 条目,Workload 转换的名称遵循 provider 的转换约定(例如 helm 的 <release-name>-deployment.yaml,其中 release 名称为 {{ .context.rendered_name }})——请将 artifacts: 文件名调整为 provider 不会合成的名称。

An output-label key uses a reserved namespace(输出标签键使用了保留命名空间)

Recipe 指定了位于 aggrega.ai/ 或 app.kubernetes.io/ 下的标签键——在 outputLabels:(向渲染输出写入字面标签的块)中,或在 outputComponentLabels:(指定其值被提升到输出上的组件标签键的块)中。这两个前缀属于平台自身的来源键空间:它们是构建自己写入的键,因此写入其中之一的 Recipe 就是在写入表明资源来源的空间。保留它们也使 Recipe 的标签集与来源标签集互不相交,合并时无需协调二者。此规则在加载 Recipe 时检查。

保留仅针对裸根。若一个键只是在其自身命名空间的更深处包含保留根——例如 component.aggrega.ai/hosting——则属于平台不拥有的另一键空间,仍可编写。

输出的消息。同一条件涵盖两个块,因此其语句无法说明编写的是哪一个;其后的建议通过引用你输入的键以及你输入它的块来指出该块:

recipe output-labels constraint: key uses a reserved namespace (Recipe <name>:<version>, rule output-labels, at .spec.outputLabels). key "<key>" in outputLabels uses a reserved namespace ("aggrega.ai/" and "app.kubernetes.io/" are reserved for platform provenance)(Recipe 的输出标签约束:键使用了保留命名空间;outputLabels 中的该键使用了保留命名空间,这两个前缀保留用于平台来源信息)

写在提升块中的键以该块的规则名报告,并在建议中指出该块:

recipe output-labels constraint: key uses a reserved namespace (Recipe <name>:<version>, rule output-component-labels, at .spec.outputComponentLabels). key "<key>" in outputComponentLabels uses a reserved namespace ("aggrega.ai/" and "app.kubernetes.io/" are reserved for platform provenance)(Recipe 的输出标签约束:键使用了保留命名空间;outputComponentLabels 中的该键使用了保留命名空间,这两个前缀保留用于平台来源信息)

字面块的键按排序顺序检查,提升块的键按你编写的顺序检查,因此在多处违反规则的 Recipe 总是先报告同一项。

**修复方法:**将该键移到你拥有的命名空间中——你自己的域名,或带子前缀的命名空间,如 component.aggrega.ai/…——如果你想要的值是构建已写入的值,则删除它。渲染资源所携带的来源键列于 ../providers/well-known-annotations.md;读取它们无需任何 Recipe 声明。

A promoted component label is also declared literally(提升的组件标签也被字面声明)

Recipe 在 outputComponentLabels: 和 outputLabels: 中都指定了同一个键。这两个块从不同来源写入同一标签面——前者提升组件携带的值,后者写入 Recipe 作者输入的值——因此在两处都指定的键会带着两个候选值到达,且没有任何依据决定哪个胜出。此规则在加载 Recipe 时、在上述保留命名空间规则之后检查,因此同时违反两者的 Recipe 会先报告保留命名空间:该错误的修复不取决于另一块的内容。

发出的消息:

recipe output-component-labels constraint: key is also declared in outputLabels (Recipe <name>:<version>, rule output-component-labels, at .spec.outputComponentLabels.<key>). key "<key>" is promoted through outputComponentLabels and also declared literally in outputLabels; keep whichever source the label should come from and drop the other(Recipe 的输出组件标签约束:该键也在 outputLabels 中声明;该键既通过 outputComponentLabels 提升,又在 outputLabels 中按字面声明;保留标签应来自的那个来源,删除另一个)

**修复方法:**确定标签值的来源,并删除另一处声明。当值应跟随组件所携带的值、使绑定到同一 Recipe 的两个组件写入各自的值时,保留 outputComponentLabels: 条目;当值属于 Recipe 自身、无论 Recipe 绑定在何处都相同时,保留 outputLabels: 条目。

FeatureRecipe 结构规则

FeatureRecipe 由与 Recipe 相同的输入类型组成其输出,下文的组合规则约束它的方式与约束 Recipe 相同。该规则在加载 FeatureRecipe 时检查,并以 Recipe 结构中止的形式报告——规则的语句,然后是出错的文档、规则名称以及针对该次出现的建议——带有 CATALOG_ERROR 标签。

这里刻意没有“至少一个输入类型”规则,这正是与 Recipe 的区别。只声明 provider 及其实现内容的 FeatureRecipe 是合法的纯连接附加项:它不渲染任何内容,其作用是其所实现的 Feature 携带的连接。只声明 injectMapping: 的 FeatureRecipe 同样合法。

A FeatureRecipe’s valuesMapping requires source(FeatureRecipe 的 valuesMapping 需要 source)

某个 FeatureRecipe 声明了 valuesMapping,但没有声明 source。values mapping 是一种覆盖层,没有可供覆盖的 chart、模块或文件,映射的值就无处可达。

发出的消息:

FeatureRecipe: valuesMapping requires source (FeatureRecipe <name>:<version>, rule values-mapping, at <path>). declare a source: pointer alongside valuesMapping (or remove the valuesMapping if no overlay is intended)(FeatureRecipe:valuesMapping 需要 source(所示 FeatureRecipe、规则 values-mapping、所示路径处)。请在 valuesMapping 旁声明一个 source: 指针(如果不打算叠加,则移除 valuesMapping))

修复方法: 添加该覆盖层所针对的 source: 指针,或删除 valuesMapping,让该挂载以其他方式完成工作——用 artifacts: 输出自己的文件,用 injectMapping: 重塑其交付的内容,或两者都不用,作为纯连线挂载。

A pipeline declares one step id twice (流水线将同一个步骤 id 声明了两次)

Recipe 或 FeatureRecipe 在其 spec.pipeline 的两个步骤上声明了相同的 id。步骤会以其 id 发布它返回的输出,同一流水线中后续的步骤以 .steps.<id>.outputs 读取这些输出,因此两个步骤共用一个 id 会让后续步骤读取两者中最后发布的那个,而不是你想要的那个。

该规则只涵盖一个文档自身的流水线。组件的 Recipe 和附加到该组件的 FeatureRecipes 各自单独运行其流水线,并且每条流水线开始时都没有任何步骤输出,因此 Recipe 的步骤和附加的 FeatureRecipe 的步骤可以使用相同的 id。

没有任何 schema 能表达这条规则——JSON Schema 没有任何关键字可以表示条目按其中某个字段唯一的列表——因此支持 schema 的编辑器会接受这样的文档,而该检查在读取文档时运行,紧接在 schema 检查之后。每个读取 Recipe 或 FeatureRecipe 的界面都会报告它:针对该文件或整个 catalog 运行的 aggrega validate、加载 catalog 的构建、接纳所获取实体的拉取、编辑器的诊断,以及文档编辑——该编辑会被拒绝而不会写入。同时未通过其 schema 的文档会先报告 schema 的检查结果,待这些问题修复后再报告此拒绝。

每次重复都是一条独立的检查结果,定位在重复的 id 处,并指出最先声明该 id 的步骤及其行号和列号。当某个 id 出现三次时,后面两个步骤都会指向第一个。

以下是针对第二个步骤重复了第一个步骤 id 的 FeatureRecipe 输出的消息。类别以及该条件的短代码 E0370 会出现在方括号中的头部:

a pipeline declares one step id twice (FeatureRecipe, at <path>); <line>:<column>: spec.pipeline[1].id: step id "<id>" is already declared at spec.pipeline[0].id (line <line>, column <column>). give each step of the pipeline its own id, and point every .steps.<id> reference a later step makes at the step it means (流水线将同一个步骤 id 声明了两次:spec.pipeline[1].id 的步骤 id 已在 spec.pipeline[0].id 处声明。请为流水线的每个步骤指定各自的 id,并让后续步骤中的每个步骤引用都指向它所指的步骤)

修复方法: 将两个步骤之一重命名,使每个 id 只声明一次。然后检查每个后续步骤的 with: 和 when: 模板中指向你所保留 id 的 .steps.<id> 引用,并让每个引用指向它真正需要其输出的那个步骤——正是重命名让两个步骤的输出能够分别被访问。

A document declares an API version this compiler no longer reads(文档声明了此编译器不再读取的 API 版本)

文档的 apiVersion 行声明了 aggrega.ai/v1alpha1。每一种带有 apiVersion 行的文档类型都声明 aggrega.ai/v1beta1,这是此编译器读取的唯一版本,并且不会从较早的版本进行任何转换:文档在读取时即被拒绝,早于任何其他检查,因为其他任何发现都将针对编译器不读取的文档版本。

每个读取文档的界面都会报告此情况:aggrega validate、构建、接纳所获取实体的 pull、编辑器的诊断,以及文档编辑。声明了编译器从未读取过的版本的文档,则改由其类型的模式拒绝,代码为 E0215。

针对 Component 输出的消息。类别和此条件的短代码 E0373 会在方括号括起的消息头中呈现给你:

a document declares an API version this compiler no longer reads (Component, at <path>); 1:1: apiVersion: the document declares aggrega.ai/v1alpha1, and this compiler reads aggrega.ai/v1beta1. change the apiVersion line to apiVersion: aggrega.ai/v1beta1(文档声明了此编译器不再读取的 API 版本(Component);1:1: apiVersion:文档声明了 aggrega.ai/v1alpha1,而此编译器读取 aggrega.ai/v1beta1。请将 apiVersion 行改为 aggrega.ai/v1beta1)

**修复方法:**将文档的 apiVersion 行改为 apiVersion: aggrega.ai/v1beta1。各类型的字段在两个版本之间没有变化,因此这一行就是全部改动。

A plugin declares a plugin ABI version this compiler no longer speaks(插件声明了此编译器不再支持的插件 ABI 版本)

插件声明了插件 ABI v1alpha1。此编译器支持插件 ABI v1beta1,不支持其他版本,因此针对较早版本构建的插件会被拒绝,而不会被运行。插件在两处声明其 ABI,每一处都在这同一个条件下被拒绝:其访客模块在加载时返回的 describe() 报告,以及其 Plugin 实体的 spec.abiVersion,后者在读取实体时即被拒绝,早于任何其他检查。声明了此编译器从未支持过的 ABI 版本的插件同样会被拒绝,由描述符检查(E0085)或 Plugin 模式(E0215)拒绝。

针对加载时的访客模块输出的消息。类别和此条件的短代码 E0374 会在方括号括起的消息头中呈现给你:

plugin "<plugin>" declares abi_version “v1alpha1”, and this compiler speaks “v1beta1”; rebuild the plugin against the current plugin kit and publish it again: a plugin declares a plugin ABI version this compiler no longer speaks(插件声明了 abi_version “v1alpha1”,而此编译器支持 “v1beta1”;请针对当前的插件工具包重新构建插件并重新发布:插件声明了此编译器不再支持的插件 ABI 版本)

针对 Plugin 实体输出的消息:

a plugin declares a plugin ABI version this compiler no longer speaks (Plugin, at <path>); <line>:<column>: spec.abiVersion: the Plugin declares abiVersion v1alpha1, and this compiler speaks v1beta1. rebuild the plugin against the current plugin kit and publish it again; its Plugin entity then declares abiVersion: v1beta1(插件声明了此编译器不再支持的插件 ABI 版本(Plugin);spec.abiVersion:该 Plugin 声明了 abiVersion v1alpha1,而此编译器支持 v1beta1。请针对当前的插件工具包重新构建插件并重新发布;之后其 Plugin 实体会声明 abiVersion v1beta1)

**修复方法:**针对其插件工具包的当前版本重新构建插件,该版本会将 v1beta1 写入访客模块的 describe() 报告,然后重新发布,这样在它旁边生成的实体也会声明 abiVersion: v1beta1。仅编辑实体的那一行是不够的:访客模块本身仍会报告较早的 ABI,并在加载时被拒绝。

An artifact carries a media type this compiler no longer reads(制品带有此编译器不再读取的媒体类型)

从注册中心获取的制品带有较早版本发布时所用的媒体类型——即带后缀的 application/vnd.aggrega.<kind>.v1alpha1,出现在清单的制品类型、其配置或其某一层上。此编译器发布并读取 v1beta1 媒体类型,因此在读取其清单时,该制品即被点名拒绝,早于获取其任何内容:无论是目录实体、插件及其可执行文件,还是文档包,都是如此。对注册中心建立索引时会跳过此类制品,并说明原因。Aggrega 自身的 application/vnd.aggrega. 命名空间之外的媒体类型绝不属于此条件。

针对由较早版本发布的 Component 输出的消息。类别和此条件的短代码 E0375 会在方括号括起的消息头中呈现给你:

"<reference>" carries media type “application/vnd.aggrega.component.v1alpha1+yaml”, and this compiler reads “application/vnd.aggrega.component.v1beta1+yaml”; publish the artifact again with the current release: oci: artifact carries a media type this compiler no longer reads(带有媒体类型 “application/vnd.aggrega.component.v1alpha1+yaml”,而此编译器读取 “application/vnd.aggrega.component.v1beta1+yaml”;请使用当前版本重新发布该制品:oci: 制品带有此编译器不再读取的媒体类型)

**修复方法:**使用 aggrega 的当前版本重新发布该制品,该版本会写入 v1beta1 媒体类型。他人发布的制品需由其本人重新发布;在此之前,它无法被读取。

A file cannot be read, or its bytes do not parse(文件无法读取,或其字节无法解析)

构建必须读取的某个文件,或全 catalog 检查在 catalog 目录下读取的某个 Aggrega 文档,没有产出指定或读取它的那个表面可以使用的任何内容。要么无法从磁盘读取该文件,要么其字节经过解析但未能干净地解析。下游不会基于它运行任何步骤,因为没有可对照 schema 检查的内容,没有可放置的组件,也没有可渲染的模板。

该条件不指明任何格式,这是有意为之。它涵盖的大多数文件按 YAML 读取;而 Recipe 的 workload、values-mapping 和 artifact 正文按 Go 模板源码读取,根本不会被解析。如果句子承诺是 YAML,那么针对模板文件的诊断就会以一个关于该文件格式的错误断言开头。发生的是两种失败中的哪一种、针对哪类文件,由句子之后的从句说明。

构建的起点文档——Aggregate、Release 和 Manifest——是最常见的对象,在读取这三者之一的每个位置都会引发此中止。诊断会指明正在读取的是哪个文档,以及读取它的路径。路径用于区分文件缺失与文件格式错误:读取失败会引用操作系统自身给出的原因,解析失败会引用 YAML 解析器给出的原因,其中包含解析器放弃解析的那一行。

文件无法读取时输出的消息:

file load failed: the file could not be read, or its bytes did not parse (Aggregate, at <path>, failed to read file: <underlying reason>)(文件加载失败:无法读取该文件,或其字节无法解析;读取文件失败)

以及其文本无法解析时:

file load failed: the file could not be read, or its bytes did not parse (Aggregate, at <path>, failed to unmarshal YAML: <underlying reason>)(文件加载失败:无法读取该文件,或其字节无法解析;YAML 反序列化失败)

当正在读取的文档是 Release 或 Manifest 时,消息中会以它们代替 Aggregate。同一条件还涵盖从 Aggregate 声明的 parameters: 块中读取的参数契约,该契约在任何内容插值进去之前,从 Aggregate 自身的文本中读取。

如果 Release 的 parameters: { $import: … } 指向构建无法获取的文件,也会在此报告,且两种情况都包括:路径指向的不是构建可读取的文件,或者文件已读取但其字节无法解析。此时对象是 Release,从句会指明指向该文件的键:

file load failed: the file could not be read, or its bytes did not parse (Release, at .spec.parameters.$import: <path>, failed to read file: <underlying reason>)(文件加载失败:无法读取该文件,或其字节无法解析;读取文件失败) file load failed: the file could not be read, or its bytes did not parse (Release, at .spec.parameters.$import: <path>, failed to unmarshal YAML: <underlying reason>)(文件加载失败:无法读取该文件,或其字节无法解析;YAML 反序列化失败)

相对路径从写入它的 Release 所在目录解析——即命令指定的 Release,或其 extends: 链中的某一环——无论命令从何处运行,因此命令行和编辑器读取的是同一个文件;绝对路径则指明其自身位置。请确认构建所基于的检出在该位置包含此文件:在你的机器上存在但被排除在版本控制之外的参数文件,在持续集成运行期间并不存在,这是遇到此问题的常见方式。指向工作区之外的路径——或者对于在工作区外指定的 Release,指向该 Release 自身目录之外的路径——根本不会被读取,并在下文“A reference to another file leads out of the directory it must stay inside(对另一文件的引用超出了它必须保持在内的目录)”下报告。

如果 schema 的 $import: 指向构建无法获取的文件,也会在此报告,因为故障是相同的:该指令格式正确,但它指向的文件没有产出文档。此时对象是一个目录实体,而不是上述三者之一,因此从句会指明它当时正在解析的 schema 界面——spec.schema、它的某个支柱(如 spec.schema.values),或某个 usesSchema 插槽的 valueSchema——源指针则是编写该指令的那一行:

file load failed: the file could not be read, or its bytes did not parse. <surface>: read imported schema <value>: <the operating system's reason>(文件加载失败:无法读取该文件,或其字节无法解析;读取导入的 schema)

若根本无法确定该实体自身所在的目录(这种失败较少见),消息中以 resolve imported schema path 代替 read;若文件已读取但其文本不是格式正确的 YAML,则为 parse imported schema。你所写指令本身的错误——其旁边有同级键、值不是路径,或导入的内容已解析但不是 map——属于另一种情况,报告于下文的“A schema $import: cannot be applied(无法应用该 schema 导入指令)”。

Recipe 或 FeatureRecipe 的 valuesMapping:、workload: 或 artifacts.<name>: 导入也会在此报告,原因和修复方法相同:该指令格式正确,但它指向的文件没有产出内容。这三种正文是 Go 模板源码而非文档,因此只有读取可能失败——此时不会解析它们。实体和指明路径的键会出现在从句中,源指针则是被导入文件自身的路径:

file load failed: the file could not be read, or its bytes did not parse (Recipe <name> valuesMapping file import, <the operating system's reason>). if you meant a library entry rather than a file, the reference needs its fragment — an $import: carrying none is read as a file path, and an unquoted value ends where a space before # starts a comment, so quote the whole reference(文件加载失败:无法读取该文件,或其字节无法解析;valuesMapping 文件导入。如果你指的是库条目而非文件,引用需要带上其片段——不带片段的 $import: 会被当作文件路径读取,而未加引号的值会在 # 前的空格开始注释处结束,因此请给整个引用加上引号) file load failed: the file could not be read, or its bytes did not parse (Recipe <name> workload file import, <the operating system's reason>). if you meant a library entry rather than a file, the reference needs its fragment — an $import: carrying none is read as a file path, and an unquoted value ends where a space before # starts a comment, so quote the whole reference(文件加载失败:无法读取该文件,或其字节无法解析;workload 文件导入。如果你指的是库条目而非文件,引用需要带上其片段——不带片段的 $import: 会被当作文件路径读取,而未加引号的值会在 # 前的空格开始注释处结束,因此请给整个引用加上引号) file load failed: the file could not be read, or its bytes did not parse (Recipe <name> artifact <key> file import, <the operating system's reason>). if you meant a library entry rather than a file, the reference needs its fragment — an $import: carrying none is read as a file path, and an unquoted value ends where a space before # starts a comment, so quote the whole reference(文件加载失败:无法读取该文件,或其字节无法解析;artifact 文件导入。如果你指的是库条目而非文件,引用需要带上其片段——不带片段的 $import: 会被当作文件路径读取,而未加引号的值会在 # 前的空格开始注释处结束,因此请给整个引用加上引号)

片段用于区分库引用和路径:<Library>#/mappings/<entry> 针对库进行解析,而去掉片段的同一文本就是普通的相对路径。片段很容易在不知不觉中丢失,因为普通 YAML 值会在 # 前的空格开启注释处结束——所以 $import: LibBeta:1.0.0 #/workloads/Web 到达构建时变成 LibBeta:1.0.0,构建随后会在 Recipe 旁查找同名文件。请给整个引用加上引号以保留片段。

FeatureRecipe 上的这三个键报告相同的条件,读法也相同。在 Release 的生命周期中,artifacts 导入会被读取两次——一次是 aggrega pull 冻结其内容固定版本时,另一次是渲染该条目时——因此同一个缺失文件会在你先到达的那一次报告此条件。指令本身的形状故障,例如 $import: 旁有同级键,或带主机的 oci:// 引用,属于另一种条件,在其各自的条目下报告。

全 catalog 的 aggrega lint 和 aggrega validate 也在此报告,针对 catalog 目录下声明了 Aggrega apiVersion 的文档——即以无缩进的 apiVersion: 开头、值以 aggrega.ai/ 开头的一行——且该文档无法读取、无法解析,或无法解码为检查所读取的信封结构,例如写成列表的 metadata。没有任何作者写过指向它的路径:检查之所以读取它,是因为它位于 catalog 目录中。每个检查都会在中止前读取所有文件,因此一次运行就会指明所有此类文档,并且不检查其他任何内容,也不打印摘要。未声明 Aggrega apiVersion 的 YAML(其中包括 Helm chart 的模板)会被跳过。消息头统计文档数量并指明其文件,每个文档都列在其下方,并附有读取或解析器自身给出的原因:

<n> documents under the catalog directories declare an Aggrega apiVersion and could not be loaded, so nothing was checked: <path>, <path>(catalog 目录下有若干文档声明了 Aggrega apiVersion 但无法加载,因此未检查任何内容) file load failed: the file could not be read, or its bytes did not parse (catalog document, failed to unmarshal YAML: <the parser's reason>)(文件加载失败:无法读取该文件,或其字节未能解析(catalog 文档,YAML 反序列化失败))

对于能够解析但无法解码的文档,结尾为 failed to decode the envelope: 加上行号以及解码器在该处发现的内容——对于写成列表的 metadata,为 line 4 (metadata): a list is written where a map is expected;对于无法读取的文件,结尾为 failed to read file: 加上操作系统给出的原因。能够加载但声明了任何 catalog 都不包含的种类的文档,会由同一个中止指出,计入同一个头部的计数,并列在其自身的条件之下——参见下文“A catalog document declares a kind a catalog does not hold (catalog 文档声明了 catalog 不包含的种类)”。

**修复方法:**阅读消息中的路径,而不是文档名称——每当引用解析到意外位置时,两者就会不同。对于读取失败,请确认文件存在于该路径,路径的拼写与引用它的文档所写一致,并且构建有权限读取它;文件在本地存在而在构建代理的检出中缺失是常见情况。对于解析失败,请打开文件并定位到解析器指出的那一行——包含冒号的未加引号的值、用于缩进的制表符,以及缩进在错误键下的列表项,是导致大多数解析失败的三种原因。

A catalog document declares a kind a catalog does not hold (catalog 文档声明了 catalog 不包含的种类)

catalog 目录下的某个文档声明了 Aggrega apiVersion——即某一行不带缩进地以 apiVersion: 开头,且其值以 aggrega.ai/ 开头——并声明了任何 catalog 都不包含的 kind:拼写错误,例如 Componnent;大小写错误的种类,例如 component;或者根本没有 kind。catalog 按每个文档声明的种类来归档它,因此这样的文档不会进入任何 catalog:构建、inspect 以及其他所有加载 catalog 的命令都会跳过它,而对它本应声明的实体的引用将解析不到任何内容。

catalog 包含 Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary、Aggregate 和 Plugin 文档。另有三种种类可以合理地位于其目录中,并且此处从不报告它们:与实体放在一起的 Manifest 和 Release,以及位于导入它的 Recipe 或 FeatureRecipe 所在目录中的 Workload。

整个 catalog 范围的 aggrega validate 和 aggrega lint,以及遍历相同目录的 Release 范围的 lint,都会报告它。每个命令都会在中止前读取所有文件,因此一次运行会在同一个头部下列出所有此类文档以及任何根本无法加载的文档,该头部会统计它们的数量并列出它们的文件;不会检查任何内容,也不会打印摘要。每个文档都会与其声明的种类一起列出,该行末尾列出 catalog 所包含的种类:

<n> documents under the catalog directories declare an Aggrega apiVersion and could not be loaded, so nothing was checked: <path>, <path> (catalog 目录下有若干文档声明了 Aggrega apiVersion 但无法加载,因此未检查任何内容) catalog document declares a kind a catalog does not hold (kind “Componnent”). a catalog holds Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary, Aggregate and Plugin documents, and passes over a Workload, a Manifest or a Release; correct the kind, or move the file out of the catalog directories (catalog 文档声明了 catalog 不包含的种类。catalog 包含 Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary、Aggregate 和 Plugin 文档,并会跳过 Workload、Manifest 或 Release;请更正种类,或将该文件移出 catalog 目录)

对于未声明任何种类的文档,会以 no kind 代替 kind "<kind>"。

构建不会因这样的文档而停止:它会像每次加载一样跳过该文档,而任何 Release 都未到达的文档永远不会导致构建失败。当某个 Release 确实到达该实体时,构建会在该引用处停止,归于下文的“A reference names no entity the catalog holds (引用未指向 catalog 所包含的任何实体)”,并且当该文件声明了引用所要求的名称时,该失败下方的注释会指出该文件——参见该条目。

修复方法: 打开消息中指出的文件,将其 kind 更正为该文档实际的种类——拼写和大小写都很重要。根本不是 catalog 实体的文件不应放在 catalog 目录下;请将其移出,或者如果它是其他工具的文档,为它指定一个不属于 Aggrega 的 apiVersion。

A path names content outside the entity’s own directory(路径指向实体自身目录之外的内容)

实体的内容位于实体自身的目录中,因为实体的发布所携带的每个文件都取自该目录。离开该目录的路径指向一个不会随实体一起传递的文件,因此任何接收该实体的人都拿不到这个文件,而基于它记录的 pin 所担保的字节,他们也无法获取。

因此,实体为其携带的内容所写的每个路径,都相对于包含该实体文件的目录来解析,并且必须留在该目录内。这涵盖 Recipe 和 FeatureRecipe 的 source:(裸路径,或结构化形式中的 url:)、每个 valuesMapping:、workload: 和 artifacts: 条目通过 $import: 导入的文件,以及 Component 或 Feature 导入的每个 schema,无论是整体导入、按支柱导入,还是为 usesSchema 插座的 valueSchema 和 infraSchema 导入。有三种形式会离开该目录:向上越出目录的路径;绝对路径,它指向编写时所在机器上的某个位置;以及写在目录内、但途经的符号链接将其带出目录的路径——即路径沿途的某个目录或末端的文件是一个指向实体目录之外的链接。向上后又回到目录内的路径(./charts/../values.tmpl)是目录内的普通路径,经过指向目录内其他位置的链接的路径也是如此。通过目录自身名称重新进入目录的向上路径(在名为 1.0.0 的目录中写 ../1.0.0/values.tmpl)会被拒绝,因为目录名称不属于随实体传递的内容:已发布的实体是从使用方缓存命名的目录中读取的,在那里该名称找不到任何东西。经过向外链接的路径会被拒绝,因为否则发布就会以实体内部的名称,携带该链接所指向的字节,无论它指向何处。

**无论在何处读取该实体,都会被拒绝。**整个 catalog 的 aggrega validate、针对实体自身文件的 aggrega validate、aggrega pull 和 aggrega build 在读取实体文件时就会拒绝它;对 Recipe 或 FeatureRecipe 执行的 aggrega pin,以及对这四种类型中任一种执行的 aggrega push 也会拒绝,且在获取、写入或发布任何内容之前。以模板形式编写的 source: 在构建对其求值之前不指向任何东西,因此生成目录外路径的模板会在值产生的那一刻被构建拒绝。

**Release 不同,实体引用也不同。**Release 指向其他实体(它的 Aggregate、它的 Manifest、它所扩展的 Release),且从不发布,因此它读取的任何内容都不会传递到任何地方:这些路径以及 Release 的 parameters: 导入的文件都按原样读取。Aggregate 的 type 通过标识指向另一个实体,而不是该 Aggregate 携带的内容,因此同样按其自身规则解析:通过 catalog 目录、缓存和 registry 解析,绝不作为文件路径。

输出的消息,给出按原样书写的路径:

a path names content outside the entity’s own directory ("<path>"). remediation: move the file into the directory holding the entity, or a directory beneath it, and name it with a path relative to that directory. An entity’s content lives in the entity’s own directory because every file a publication of it carries is taken from there; a path that leaves it points at a file that would not travel with the entity(路径指向了实体自身目录之外的内容(即上述路径)。补救方法:将该文件移入存放该实体的目录或其下级目录,并使用相对于该目录的路径来指定它。实体的内容位于实体自身的目录中,因为实体的发布所携带的每个文件都取自该目录;离开该目录的路径指向的文件不会随实体一起分发)

对于被链接带出目录的路径,还会给出该链接及其指向的位置:

a path names content outside the entity’s own directory ("./frag/fragment.yaml", the link <entity-directory>/frag leads to <elsewhere>/frag). remediation: replace the link with a copy of what it leads to, placed inside the directory holding the entity. An entity’s content lives in the entity’s own directory because every file a publication of it carries is taken from there; a link leading out of it would carry the bytes it points at under a name inside the entity(路径指向了实体自身目录之外的内容(即上述路径,其中的链接指向目录之外的位置)。补救方法:将该链接替换为其所指内容的副本,并放在存放该实体的目录中。实体的内容位于实体自身的目录中,因为实体的发布所携带的每个文件都取自该目录;指向该目录之外的链接会以实体内部的名称携带其所指向的字节)

读取该路径的字段会在消息上方一行给出:resolve Recipe source …、resolve Recipe artifact "<key>" $import target …、spec.schema.values: imported schema …,对于模板化的 source 则为 node "<name>" source。

**修复方法:**将文件移入实体的目录或其子目录,并使用相对于该目录的路径。如果是链接将路径带出,请用链接所指内容的副本替换该链接,并放在实体目录内。多个 Recipes 共享的 chart 应复制到每个 Recipe 的目录中,因为每个 Recipe 都单独发布;多个 Components 共享的 schema 应放入 SchemaLibrary,再由每个 Component 按标识引用;多个 Recipes 共享的 mapping、workload 或 artifact 内容则应放入对应的库类型。

A Recipe’s source: names a kind nothing knows how to acquire(Recipe 的 source 指定了一个无从获取的种类)

Recipe 的 source: 说明它指向的是哪种东西——chart、模块、compose 项目——每种类型都由服务该类型的 source adapter 获取。此条件报告的是没有任何 source adapter 服务的类型,因此本程序所包含的任何部分都无法获取该源。FeatureRecipe 的 source: 遵循同一规则。

它在读取文档时、获取任何内容之前就被拒绝:单独检查该 Recipe 会拒绝它,每个到达它的 Release 也会拒绝它。没有进行任何尝试,因为没有任何东西能够尝试——这正是它与已运行但失败的获取的区别。

输出的消息,指明文档、所写的类型以及受支持的类型:

no source adapter serves the source kind (Recipe <name>:<version>, rule source-kind, at <file>). the source names kind "<kind>"; name a kind a source adapter serves (<the served kinds>), or write the source as a single URI whose shape names its kind(没有 source adapter 服务该源类型(Recipe,规则 source-kind)。源指定了该类型;请指定某个 source adapter 服务的类型,或将源写成一个其形式即表明类型的单一 URI)

**修复方法:**将 source: 上的类型更正为工具链支持的类型——拼写错误与确实没有适配器的类型会产生相同的消息,且消息会在受支持的类型旁引用你所写的类型,因此首先应对照该列表检查拼写,Recipe 页面 也描述了该列表。如果类型的拼写符合你的本意,那么该类型不是本次构建能够获取的,对 Recipe 的任何编写修改都无法改变这一点;请改为让 source: 指向受支持的形式,或将其写成一个其形式即表明类型的单一 URI。

No source adapter is registered in this program for a source kind(本程序中没有为某个源类型注册 source adapter)

源由为其类型注册的适配器获取。此条件报告的是按没有注册适配器的类型分派的获取。没有适配器服务的编写类型会在读取其 Recipe 时被拒绝(见上文“A Recipe’s source: names a kind nothing knows how to acquire(Recipe 的源指定了一种无从获取的类型)”),因此作者所写的任何内容都不会到达这里:它报告的是组装时缺少其所服务类型的适配器的程序,或基于 Aggrega 的 Go 包构建、分派其自行组装的类型的程序。

输出的消息,指明类型:

kind "<kind>": no source adapter is registered in this program for the source kind(本程序中没有为该源类型注册 source adapter)

**修复方法:**这并非由你的实体文件引起。请将其报告给构建你所运行的二进制文件的人。

A source URL carries a credential(源 URL 携带了凭据)

源 url 按你所写的样子记录——记录在 Release 的 lockfile 中、Recipe 旁的 entity.lock 中以及源缓存中——而 Recipe 本身是你提交并可能发布的文件。因此,写入 URL 的凭据会随 URL 传到任何地方。此条件报告 Recipe 的 source: 的 url 在主机之前写了用户的情况:https://user:token@host/…,或单独写成 https://token@host/… 的令牌,因为通过 HTTP 访问的服务通常在用户的位置接受令牌。对于 http 和 https,写在那里的任何用户都算数;对于其他协议,只有密码才算,因为单独写在那里的用户指定的是一个账户——ssh://git@github.com/… 会被接受,由 SSH agent 提供其密钥。FeatureRecipe 的 source: 遵循同一规则。

它在读取文档时、获取任何内容之前就被拒绝:单独检查该 Recipe 会拒绝它,每个到达它的 Release 在校验、pull、pin 或构建时也会拒绝它。消息会指明主机,但绝不会包含凭据。检查只读取 URL 中写在主机之前的部分,不读其他部分,因此放在查询字符串或路径中的令牌不会被检测到——并会像 URL 的其余部分一样按原样记录。

通过 http 或 https 时输出的消息,指明文档、键和主机,然后说明凭据应放在哪里:

the source URL carries a credential (Recipe <name>:<version>, rule source-url, at <file>). spec.source.url names a user or password for host <host>; remove it from the URL and write the credential in the netrc file instead, as an entry “machine <host> login <user> password <secret>” (the file NETRC names, else .netrc in your home directory, or _netrc in %USERPROFILE% on Windows)(源 URL 携带了凭据(Recipe,规则 source-url)。spec.source.url 为该主机指定了用户或密码;请将其从 URL 中删除,改为在 netrc 文件中以 machine、login、password 条目的形式写入凭据(即 NETRC 指定的文件,否则为主目录中的 .netrc,在 Windows 上为 %USERPROFILE% 中的 _netrc))

而对于其他协议,补救办法是删除密码:

the source URL carries a credential (Recipe <name>:<version>, rule source-url, at <file>). spec.source.url names a password for host <host>; remove it from the URL, which is written into the lockfile and the cache as authored(源 URL 携带了凭据(Recipe,规则 source-url)。spec.source.url 为该主机指定了密码;请将其从 URL 中删除,因为 URL 会按所写原样写入 lockfile 和缓存)

**修复方法:**从 url 中删除用户和密码,保留指定主机的 URL。对于通过 http 或 https 获取的源,请在 netrc 文件中为该主机的 machine 条目写入凭据;通过 HTTP 或 HTTPS 获取经典 Helm chart 仓库、compose 片段或 Git 仓库时都会读取该文件——身份验证 说明了是哪个文件、哪个条目。对于通过 SSH 访问的 Git 仓库,由 SSH agent 提供密钥,用户可以保留。如果 Recipe 已在包含凭据的情况下提交或发布,凭据就已在该历史中:也请在服务器端更换它。

A {{ .parameters.* }} reference cannot be interpolated(无法插值 .parameters.* 引用)

Aggregate 的文本在作为文档读取之前,会先作为模板求值,从而将 {{ .parameters.<key> }} 引用替换为 Release 为其提供的值。当该求值无法完成时,即文本无法解析为模板,或能够解析但在运行时失败,就会触发此中止。

插值发生在 Aggregate 被解析为 YAML 之前,因此此处的错误针对整个 Aggregate 报告,而不是针对其中的某个键——此时文档还没有任何键。这也是引用可以不加引号的原因:替换发生在原始字节中,随后由 YAML 自身的引号规则决定值的类型,因此不加引号的引用得到值的自然类型,加引号的引用得到字符串。

引用了 Release 未提供的键不属于此中止。缺失的键在此处解析为空值,并由上文“Parameter type mismatch / contract violation(参数类型不匹配/契约违例)”中描述的参数检查连同其类型和契约一起捕获。此中止报告的是模板引擎根本无法处理的文本——未闭合的 {{、拼写错误的函数名、各阶段无法衔接的管道。当 Release 未提供某个参数时,通过 index 读取该参数({{ index .parameters "db_size" }})属于运行时失败,由此中止承载并指出该键:如下文“A template indexes a map with a key the map does not hold(模板使用映射中不存在的键索引映射)”所述,在每个模板表面上,index 遇到映射中不存在的键都会中止。

完全无法解析的文本会被拒绝,并指出 Aggregate 自身的路径,因为在任何读取发生之前该文件就已在手。组合所导入的模块在下一层以相同方式求值,其文本从目录中读取,而不是交给构建。无论哪种情况,该中止都是同一条件并带有同一代码;对于模块,它还会指出所跟随的导入以及读取模块文本的文件,而它携带的消息只指出种类——因此该消息给出的位置是模块自身文本中的位置,而不是你所起始的 Aggregate 中的位置。

输出的消息,依次对应无法解析的模板、组合所导入模块中的同一错误,以及运行时失败的模板:

invalid parameter reference: check the {{ .parameters.* }} expression names a declared parameter and parses as a Go template (Aggregate <path>, “template parse error: <underlying reason>”)(无效的参数引用:请检查 {{ .parameters.* }} 表达式是否指向已声明的参数并能解析为 Go 模板) invalid parameter reference: check the {{ .parameters.* }} expression names a declared parameter and parses as a Go template (Aggregate, template parse error: <underlying reason>)(无效的参数引用:请检查 {{ .parameters.* }} 表达式是否指向已声明的参数并能解析为 Go 模板) invalid parameter reference: check the {{ .parameters.* }} expression names a declared parameter and parses as a Go template (Aggregate, template execution error: <underlying reason>)(无效的参数引用:请检查 {{ .parameters.* }} 表达式是否指向已声明的参数并能解析为 Go 模板)

Aggregate 的文本只有一个根 .parameters,因此通过任何其他根的引用——{{ .values.app_token }} 或 {{ $.values.app_token }}——读不到任何内容,并在运行时失败。此时原因的开头会指明它所读取的引用:

invalid parameter reference: check the {{ .parameters.* }} expression names a declared parameter and parses as a Go template (Aggregate, the template reads <reference>, and an Aggregate’s text defines no root but .parameters; template execution error: <underlying reason>)(无效的参数引用:请检查 parameters 表达式是否指向已声明的参数并能作为 Go 模板解析(Aggregate,模板读取了该引用,而 Aggregate 的文本除 .parameters 外未定义任何根;模板执行错误))

修复方法:打开 Aggregate 并阅读底层原因,其中指出了文本中的位置以及失败的结构。确认每个 {{ 都有对应的 }},所调用的函数是该表面提供的函数——参数插值只提供 Sprig 的函数,因此 optional 辅助函数在此处不可用——并确认管道的各阶段能接受前一阶段的输出。若原因指出 index 未找到某个键,请用点号({{ .parameters.db_size }})或通过 Sprig 的 get 或 hasKey 读取可能未设置的参数。若原因指出的是通过其他根的引用,请将该值声明为 Aggregate 的参数,并以 {{ .parameters.<key> }} 读取。若原因指出的内容你本意并非模板——例如来自 n8n 表达式的 undefined variable "$json",或以 Flowise 节点命名的函数——说明文本自带双花括号(包括注释中的):如 自带双花括号的文本 所述,将其中每个 {{ 写成 {{"{{"}}。

The Release directory declares one Aggregate or Manifest twice(Release 目录中重复声明了同一个 Aggregate 或 Manifest)

aggregate: 或 manifest: 引用为裸标识的 Release,会首先扫描该 Release 自身所在的目录来解析,而该扫描发现了两个带有相同 metadata.name 的 Aggregates(或两个 Manifests)。裸标识引用按该名称指向实体,因此一个被声明两次的名称,目录无法给出唯一答案。

**扫描会拒绝整个目录,而不仅是引用所请求的名称。**它会读取与 Release 同处的每个 Aggregate 和每个 Manifest,因此即使冲突的一对未被任何引用指向,也会停止构建:无论该 Release 是否正要读取该实体,目录本身都存在歧义。以路径形式书写的引用(./aggregate.yaml、../shared/manifest.yaml)指向文件而非实体,解析时不进行扫描,因此 aggregate: 和 manifest: 均为路径的 Release 永远不会运行该扫描。

这是目录层级重复标识拒绝在同一目录下的对应情况,二者分开报告,以便消息指出你当前所在的目录,而不是你可能没有想到的某个目录层级。

发出的消息:

duplicate Aggregate/Manifest identity (metadata.name) in the Release directory: Aggregate "<name>" declared more than once in <release-directory>(Release 目录中存在重复的 Aggregate/Manifest 标识(metadata.name):Aggregate 被多次声明)

当两个 Manifests 冲突时,以 Manifest 代替 Aggregate。

**修复方法:**为两个实体之一指定不同的 metadata.name,或将其移出 Release 所在目录。确实部署同名但不同 Aggregates 的两个 Releases 应分别放在各自的目录中;将 Release 复制到同级文件却未重命名其所携带的内容,是出现此问题的常见原因。

A Release’s aggregate: or manifest: reference resolves to nothing(Release 的 aggregate: 或 manifest: 引用解析不到任何实体)

某个 Release 以裸标识指向一个 Aggregate 或 Manifest,但在查找裸标识的所有表面上都未找到该名称的实体:Release 自身目录、目录(catalog)以及注册表。

在任何地方都未匹配时输出的消息:

aggregate/manifest reference unresolvable: no Aggregate named "<reference>" in the Release directory, catalog, or registry(aggregate/manifest 引用无法解析:Release 目录、catalog 或注册表中均无该名称的 Aggregate)

Release 目录中若有无法建立索引的文件,报告内容会改变,因为这会改变能够如实断言的内容。这样的文件可能正是目标实体,因此消息会如实说明,而不是断言一个无法证实的缺失,并附上导致其无法读取的解析失败:

aggregate/manifest reference unresolvable: Aggregate "<reference>" not found; unparseable file <path> could not be indexed and may be it: <parse failure>(aggregate/manifest 引用无法解析:未找到该 Aggregate;无法解析的文件未能建立索引,可能就是该实体)

以及当引用直接指向的正是一个无法解析的文件时:

aggregate/manifest reference unresolvable: needed Aggregate "<reference>" is the unparseable file <path>: <parse failure>(aggregate/manifest 引用无法解析:所需的 Aggregate 是一个无法解析的文件)

**修复方法:**若引用的实体确实不存在,请更正其拼写——标识是实体的 metadata.name,而不是文件名——或将该实体添加到 Release 所在目录或构建读取的目录中。若消息指出了无法解析的文件,请先修复该文件:消息中引用了其解析失败信息,修复它通常能在同一次编辑中解决该引用。./ 或 ../ 引用是路径而非标识,并按路径解析,因此开头的点号决定了你要查找的是这两类错误中的哪一类。

A component is placed in more than one boundary(一个组件被放置在多个边界中)

某个 Release 的边界树把同一个组件放在了两个不同的边界中。这两处放置既不会合并,也不会排定优先级,而且也无法这样做:组件的边界决定其输出写到哪里、落在哪个子目录、加入哪个同步波次,以及继承哪些边界注解和边界基础设施;而它的逐边 uses: 接口则由另一次独立的遍历读取。被命名两次的组件会从一处放置取得输出位置,又从另一处取得逐边配置。

边界放置组件的方式有三种,三种都算数。 直接在 components: 下按组件在组合完成后所带的 id 命名它,即放置了它。在路由条目自身的 components: 中按组件在该子模块内所带的本地名称命名它,同样放置了它。在 aggregates: 下把整个子模块路由进来,则放置了该模块包含的每一个组件。因此,此中止也涵盖以下情况:一个子模块被路由进两个边界;一个模块被路由进一个边界,而嵌套在其中的模块被路由进另一个边界;一个组件在某个边界中被命名,而包含它的模块被路由进另一个边界。

把一个模块路由进某个边界,同时又在同一个边界下命名其某个组件,并不构成冲突——两处放置对组件所属位置的判断一致——可以正常构建。但在同一个边界下把一个 id 写两次,即使在这里也是冲突:边界的 components: 中的条目,与该边界路由条目内针对同一组件的条目,是为同一组件携带配置的两个条目,无从取舍。

每一处违规放置都会被报告。 如果一个 Release 把多个组件各放置了两次,它会在一次构建中针对每个违规条目各中止一次,每条都指向它所针对的条目的键——因此多条这样的消息合起来是一次构建列出它发现的全部问题,而不是同一个错误被写了多遍。

消息报告为“已生效”的那处放置,并不总是文件中先写的那一处。边界自身的 components: 条目先于其路由条目所命名的组件、也先于它所路由的子模块被读取,而边界先于嵌套在其中的边界被读取;并列书写的边界按出现顺序读取。如果有多处更早的放置发生冲突,则报告最先读取的那一处。无论先后如何,两处位置都会被列出,且二者之间不分高下。

输出的消息。句子陈述规则;其后依次列出出错的条目、两处放置各自所在的边界、各自所写的块,以及同时包含它们的文件。当某个边界的 components: 下的条目遇到另一个边界中更早的条目时:

component declared in more than one boundary: declare each component in exactly one boundary (Release <name>, at <field-path>, "<component>", named in the components block of boundary "<boundary-b>", while it is already named in the components block of boundary "<boundary-a>", that earlier entry naming "<component>", both declared in "<path>")(组件在多个边界中声明:每个组件只能在一个边界中声明)

命名边界的两个子句,其措辞取决于各条目所写的块。出错的条目采用以下之一:

  • named in the components block of boundary "<boundary>"——边界自身的 components: 映射;
  • named inside a routing entry in boundary "<boundary>"——该边界 aggregates: 下某个路由条目的 components: 映射;
  • routed as a sub-module into boundary "<boundary>"——路由条目本身。

更早的放置在同一句中接续,采用以下之一:

  • while it is already named in the components block of boundary "<boundary>";
  • while it is already named inside a routing entry in boundary "<boundary>";
  • while it is already placed by a sub-module routed into boundary "<boundary>"。

这两个子句是独立选择的,因此可能出现任意组合;that earlier entry naming 携带的是那处更早放置所指向的内容:组件的 id,或者当放置它的是被路由的子模块时,该子模块的前缀。

当出错的条目本身是路由条目时,它指向的是子模块而不是单个组件,消息会如实说明,而不会把模块前缀当作组件名呈现——下例中它遇到了一个更早被路由进另一个边界的子模块:

component declared in more than one boundary: declare each component in exactly one boundary (Release <name>, at <field-path>, sub-module "<module>", routed as a sub-module into boundary "<boundary-b>", while it is already placed by a sub-module routed into boundary "<boundary-a>", that earlier entry naming "<module>", both declared in "<path>")(组件在多个边界中声明:每个组件只能在一个边界中声明)

修复方法: 删除两处放置中你并非本意的那一处。消息会列出两处,因此由你而不是编译器来选择。当直接声明与被路由的模块不一致时,请决定该组件应随其模块放置还是单独放置:路由模块会把它与模块包含的其他内容放在一起,直接命名则把它与这些内容分开。当两个路由条目争夺同一个模块时,删除你并非本意的路由——把模块路由进边界会把它包含的每个组件都放到那里,因此两个这样的条目争夺的是同一组组件。

A Manifest annotation binding claims the reserved aggrega.ai/ prefix(Manifest 注解绑定占用了保留的 aggrega.ai/ 前缀)

某个 Manifest 在以裸 aggrega.ai/ 前缀开头的键下声明了注解绑定。该前缀是构建为自身输出的键打标的位置,因此占用其中某个键的绑定会把你的路由与平台自身的输出放进同一个键空间,争夺相同的名称。

它会中止,而且不可能只是一条建议。 这一保留正是该键空间归平台所有的全部依据;接纳该绑定再事后提示,会把冲突留在构建中。

该规则针对的是编写的绑定所占用的键空间,因此所呈现的 Manifest 未为其声明绑定的键会被跳过而不被报告——不存在可违规的绑定。

输出的消息。违规的键排在最前,因为句子说的就是它,其后的各个值都以其含义作为引导:

manifest annotation binding uses reserved prefix (Manifest, at <field-path>, "<key>", reserved prefix "aggrega.ai/", routing to Feature "<feature-uri>", author the binding under a domain of your own such as "feature.<your-domain>/")(Manifest 注解绑定使用了保留前缀)

修复方法: 把绑定键重命名到你所控制的命名空间中。带子前缀的键是受支持的形式,不属于保留范围:标准库快捷方式使用 feature.aggrega.ai/…,企业自有的则使用你自己的域名——acme.aggrega.ai/…、compliance.example.com/…。重命名键会改变作者在组件上为触发该绑定所写的内容,因此请在同一次编辑中更新使用它的注解。平台自身在裸前缀下的键列在 ../providers/well-known-annotations.md 中。

Two Manifest annotation bindings compete for one routing slot(两个 Manifest 注解绑定争用同一个路由槽位)

同一个 Manifest 中的两个注解绑定通过同一个支柱、在同一路径上路由到同一个 Feature。绑定的作用是说明注解的值落在何处,而两个绑定指向同一目标,会让该值有两条路由,在展开时无从选择。

对每个目标 Feature,一个给定的路径与支柱组合只能由一个绑定声明。两个绑定以不同路径指向同一个 Feature 属于正常写法,可以构建;两个绑定把同一路径路由到两个不同的 Features 也一样。

绑定按 Manifest 声明它们的顺序遍历,因此消息中先列出的绑定总是你文档中较早的那个。

发出的消息:

manifest annotation bindings collide on same Feature path+pillar (Manifest, at <path>, annotation bindings "<first-key>" and "<second-key>" both target Feature "<feature-uri>" with path "<path>" routing to pillar "<pillar>"; only one binding may declare a given (path, pillar) pair per Feature)(Manifest 注解绑定在同一 Feature 的路径+支柱上冲突)

**修复方法:**决定由哪个绑定拥有该目标,并从另一个绑定的 maps.infra 或 maps.values 列表中删除该路径,或者直接删除第二个绑定。如果这两个绑定存在是因为你希望两个注解键到达同一个 Feature 字段,保留一个绑定,让两个注解键都经由它路由;如果是因为两个不同的值本应落在两个位置,则更正写错的那个路径。

A Release reached resolution without passing through the load path(Release 未经加载路径就进入了解析)

一个 Release 进入解析时,同时带有非空的顶层 components: 表面和一个合成的 default 边界。正常加载的 Release 不会产生这种组合:加载路径会把顶层 components: 块并入默认边界并将其清空,而直接同时编写两者的文档在到达这一步之前就会被其 schema 拒绝。

因此,这个中止并不是报告你写的任何内容。它报告的是有东西绕过加载路径进入了解析——最常见的是由嵌入程序在内存中构造、而非从文件读取的 Release——并在此停止,而不是让构建在两个组件表面不一致的文档上继续进行。无论按哪种顺序读取它们,都会产生静默遗漏或重复组件的输出,而且边界遍历与逐边遍历甚至在遗漏或重复哪些组件上都无法达成一致。

发出的消息:

release reached resolve un-normalized (non-empty root components alongside a synthesized default boundary): construct releases through the normalization core (types.NormalizeRelease via the load path), not a hand-built literal(release 未经规范化就进入解析:请通过规范化核心构造 release,而不是手工构建字面量)

**修复方法:**如果你在编写 YAML,则无需任何操作——从 aggrega build、aggrega validate 或编辑器遇到这个中止,意味着编译器存在值得报告的缺陷,你正在构建的 Release 没有问题。如果你在嵌入编译器并在自己的代码中构建 Release 值,请通过加载路径构造它,而不是直接组装结构体,这样才会运行把根组件并入默认边界的规范化。

A library reference expands into itself(库引用展开为自身)

一条跨文档引用链回到了它已经到达过的文档,因此展开永远不会结束。有两种编写方式会导致这种情况,两者都是库实体之间的链,而不是单个文件内部的问题:从 schema 支柱指向某个 SchemaLibrary 条目的 $ref:,而该条目又辗转引用回来;以及指向某个 MappingLibrary 或 WorkloadLibrary 条目的 $import:,情况相同。

链按规范键比较——即库的标识和条目名称,去掉任何注册表主机和版本写法——因此循环无法通过在路径上用两种不同方式命名同一条目来逃过检查。能展开并终止的引用无论出现多少次、链有多深都没有问题;深度本身绝不会导致此中止,而从多处复用同一个库条目正是库存在的意义。

对于 $import: 链,输出的消息按遍历顺序列出整个循环,便于你看出是哪一步闭合了它:

circular reference expansion: <Library>#/mappings/<entry> -> <Library>#/mappings/<entry> -> <Library>#/mappings/<entry>(循环引用展开)

$ref: 链则由紧凑形式编译器报告,它会附上当时正在读取的文档和关键字:

compactform at <consumer-file> (keyword "$ref"): circular cross-document $ref expansion: <Library>#/schemas/<entry> -> <Library>#/schemas/<entry> -> <Library>#/schemas/<entry>(循环的跨文档 $ref 展开)

**修复方法:**阅读消息中的链,在不符合本意的那一步将其断开。循环通常意味着两个库条目各自被写成扩展对方;把共享部分提取到两者都引用的第三个条目中,或将其内联到其中一个条目。显示的最后一步是闭合循环的那一步,但它不一定是错误的那一步——之所以打印整条链,正是因为切断哪个环节由你决定。

同一条件也支撑着上文“YAML anchor aliased inside its own content(YAML 锚点在其自身内容中被别名引用)”中记录的锚点递归拒绝。那一种是单个文档自身文本内部的循环;这一种是文档之间的循环。消息中的链可以让你一眼区分两者:文档之间的循环列出库条目,文档内部的循环列出锚点。

A declared schema cannot be resolved(声明的 schema 无法解析)

某个 schema 到了要用于校验的时候,却根本无法组装成 schema。最常见的原因是 $ref: 指向了无法解析的目标;不满足 JSON Schema 元 schema 的 schema 也会导致同样的中止,条件关键字下无法单独解析的 then: 或 else: 分支也是如此。

拒绝发生在依据该 schema 校验任何内容之前,这一顺序正是关键所在。跳过无法读取的 schema 会让它覆盖的所有内容都得不到校验,而构建却报告成功——一项已停止运行的检查,却没有任何东西表明它已停止。

输出的消息列出 schema 内的位置、无法解析的关键字,以及解析报告的内容:

validator/jsonschema: schema resolution failed (at <path-inside-the-schema>, keyword "<keyword>", <what resolution reported>)(schema 解析失败)

如果失败发生在 schema 的根部,而不是其中的某个关键字,则省略位置和关键字,句子只包含报告的原因。

**修复方法:**在消息指出的位置打开 schema。$ref: 通常是罪魁祸首:确认目标存在,文档内引用的 #/$defs/… 路径拼写完全正确,跨文档引用指向的 SchemaLibrary 条目确实在构建的依赖闭包中。如果消息指出的是 then: 或 else: 分支,该分支本身就是一个 schema,必须能够独立解析。

An x-aggrega-when: or x-aggrega-validate: predicate cannot be evaluated(x-aggrega-when: 或 x-aggrega-validate: 谓词无法求值)

某个 schema 声明了两个以模板为值的扩展关键字之一,而该模板无法使用:它不是字符串、无法解析为模板、运行时失败,或者渲染出了 true 或 false 以外的内容。

x-aggrega-when: 决定 schema 的某个条件分支是否适用;x-aggrega-validate: 决定某个值是否满足 schema 自身关键字无法表达的规则。两者都被当作判定结果读取,因此不是判定结果的输出会被拒绝,而不是被解释:渲染出空字符串的谓词会被读作 false,从而悄无声息地废除它本应执行的规则。

发出的消息:

validator/jsonschema: x-aggrega extension evaluation failed (at <path-inside-the-schema>, keyword "x-aggrega-validate", <what evaluation reported>)

当出错的是条件分支的谓词时,关键字处为 "x-aggrega-when",所报告的原因会指出模板错误:解析位置、缺失的函数,或模板产生的非布尔值。

**修复方法:**在消息指出的位置打开 schema,阅读所报告的原因。确认该关键字的值是字符串、模板可以解析,并且它访问的每条路径都是被验证的值实际具有的——谓词以 .value 读取该值,而去读取其他内容是最常见的错误。如果原因指出 index 未找到某个键,请改用 hasKey 检测该键,或用 get 读取它:index 遇到映射中不存在的键时会中止,详见下文“A template indexes a map with a key the map does not hold(模板使用映射中不存在的键索引映射)”。确保模板最终产生 true 或 false:比较运算会产生,而仅渲染该值的模板不会。

A Workload does not satisfy the Workload schema(Workload 不满足 Workload schema)

某个 Recipe 或 FeatureRecipe 的 workload: 块已被读取并对照 Workload schema 检查,其中一个或多个字段不满足该 schema——拼错的键、类型错误的值、遗漏的必填字段、超出声明范围或枚举的值。

该报告是分组的:一次中止会列出所有出错字段,因此有四处错误的 Workload 会在一次构建中告诉你全部四处,而不是每次构建报一处。标题指出该 Workload、声明它的 Recipe 以及文件;其下每条结果指出 Workload 内的字段路径、schema 在该处的要求,以及可给出时的修复方法。

发出的消息:

workload validation failed (Workload in Recipe <name>:<version>, at <path>, schema stage): .containers.<name>.<field>: <what the schema required> — <the fix, where one can be stated> .initContainers[<i>].<field>: <what the schema required> — <the fix, where one can be stated>

没有逐字段详情的失败——即该块根本无法读取,而不是读取后发现不符合——会改为把完整原因作为其唯一一条结果。

**当 workload: 模板读取了声明为敏感的值时,任何结果都不会引用值。**由于无法判断渲染文档的哪个字段来自该值,因此每条文本可能携带值的结果都会在值的位置用 <redacted> 表述 schema 的约束,并以一条说明原因的提示结尾,且不附带任何由该值推导出的修复方法:

.containers.main.imagePullPolicy: against /$defs/container: enum: <redacted> does not satisfy enum ["Always","Never","IfNotPresent"] (the value is withheld because the template that rendered this document reads a value declared sensitive)

不引用值的结果——缺失的键、Workload 不接受的键——与其他模板的情况相同。参见 vocabulary/compact-form-authoring.md “What a refusal says about a declared value”。

构建以 CATALOG_ERROR 标签报告此中止,因为 workload: 块由 Recipe 的作者编写,而不是由 Aggregate 或 Release 编写。

**修复方法:**在列出的字段路径处打开 Recipe,逐一更正。路径从 Workload 自身的根开始给出,因此 .containers.main.health.ready 是 main 容器的 health 键下的 ready 块。具名容器按其键寻址,init 容器按其位置寻址,这就是两者写法不同的原因。每个字段接受什么,请参见 Workload 编写参考。

schema 要求为文本的字段因值是数字或布尔值而被拒绝,几乎总是意味着模板表达式没有加引号。workload: 块在检查之前先被渲染,因此未加引号的表达式会展开为裸文本,YAML 随后按其外观读取该文本。整核的规格数量、纯数字组成的版本号、端口,以及 yes、no、on 和 off 这些词,都会被读成文本以外的类型。结果会说明 YAML 读成了什么类型,解决办法是在 Recipe 中给表达式加引号——写 cpu: "{{ .infra.compute.cpu }}" 而不是 cpu: {{ .infra.compute.cpu }}——这样无论运维人员提供什么,值都保持为文本。注意,这里运维人员自己的值没有错,在 Release 中给它加引号也无济于事:引号必须在 Recipe 中,加在表达式周围。

A Workload attachment names a slot the entity does not declare, or a delivery the slot forbids(Workload 附件指定了实体未声明的插槽,或插槽禁止的交付方式)

workload: 块中某个容器的 attachments: 条目引用了一个附件插槽,而该引用与 Component 或 Feature 在其 featuresSchema 中声明的插槽不一致;或者,对于用 connection: 指定连接的条目,与该连接的套接字所声明的插槽不一致。指定连接的 envFrom 条目同样遵循这些连接规则。诊断结果会说明你遇到的是哪种情况。

  • 插槽未声明。 条目的 from: 指定了实体的 featuresSchema 中不存在的插槽:可能是拼写错误,也可能是插槽只在一侧被重命名。
  • 插槽为黑盒。 该插槽声明了空的 inject: 允许列表,这表示交付保留给 Recipe 自身的内部管道。此类插槽在内部填充和使用,因此 Workload 无法访问它。
  • 交付方式不在插槽的允许列表中。 条目的 as: 指定了插槽的 inject: 列表不允许的机制。
  • 该连接不是组件所建立的连接。 条目的 connection: 指定的别名下没有该组件的任何连接。
  • 连接的套接字未声明该插槽。 条目的 from:(在 envFrom 上则为 secret:)指定的插槽,未在该连接所经由的套接字中声明。
  • 插槽使用了组合名称。 条目的 from:(或 secret:)是连接的附件在组件上所取的名称,即别名、一个点和插槽名,且未写 connection:。连接的插槽只能通过指定该连接来访问。

所有容器中的每个违规条目会一并报告,因此一次构建即可列出全部问题。诊断结果归在同一个标题下,该标题指明 Workload、其 Recipe 和文件。

发出的消息:

workload featuresSchema cross-check failed (Workload in Recipe <name>:<version>, at <path>, featuresSchema stage): .containers.<name>.attachments.<KEY>.from: references slot "<slot>" which is not declared in the Component’s featuresSchema — either declare the slot in the Component (or Feature) featuresSchema, or rename the reference to an existing slot .containers.<name>.attachments.<KEY>.from: slot "<slot>" is blackbox (no inject: allowlist) and cannot be referenced from a Workload attachments entry — blackbox slots are delivered by Recipe-internal plumbing; remove the Workload-side reference, or widen the slot’s inject allowlist if Workload-side delivery is intended .containers.<name>.attachments.<KEY>.as: delivery mechanism "<as>" is not permitted by slot "<slot>" (inject allowlist: [<mechanisms>]) — use one of the allowlisted delivery mechanisms ([<mechanisms>]), or widen the slot’s inject allowlist in the Component/Feature featuresSchema .containers.<name>.attachments.<KEY>.connection: names connection "<alias>" for slot "<slot>", but the component draws no connection under that alias — name a connection the component draws (<aliases>), or remove connection to read a slot the Component declares for its own attachments .containers.<name>.attachments.<KEY>.from: names slot "<slot>" of connection "<alias>", which socket "<socket>" does not declare — name a slot socket "<socket>" declares (<slots>), or declare the slot in that socket’s featuresSchema .containers.<name>.attachments.<KEY>.from: names "<alias>.<slot>", the name the compiler composes for slot "<slot>" of connection "<alias>"; a slot a connection’s socket declares is named by naming the connection — write connection: <alias> beside from: <slot>

在 envFrom 条目上,相同的诊断结果位于 .containers.<name>.envFrom[<i>].connection 和 .containers.<name>.envFrom[<i>].secret。

修复方法: 每条诊断结果都会指明双方,因此需要选择修改哪一方。对于未声明的插槽,修正 from: 的拼写,或在实体的 featuresSchema 中声明该插槽;字段路径的 .from 后缀指向该引用。对于黑盒插槽,删除 Workload 侧的引用,让 Recipe 交付该内容;除非确实需要由 Workload 侧交付,此时为插槽提供 inject: 允许列表。对于被拒绝的机制,将 as: 改为允许列表中的某个机制,或将你的机制加入列表。对于组件未建立的连接,将别名改为诊断结果列出的某个别名,或在 Aggregate 或 Release 中建立该连接。对于套接字未声明的插槽,指定诊断结果列出的某个插槽,或在 Component 上该套接字的 featuresSchema 中声明该插槽。对于组合名称,按诊断结果所示分别写出连接和插槽。

A Workload references a slot whose fill publishes no locator(Workload 引用的插槽,其填充未发布定位符)

容器的 attachments: 条目通过引用指定了一个插槽,而填充该插槽的附件没有发布此类引用所读取的 provides 键。按名称引用插槽,意味着要求在渲染输出中对其所代表的资源进行寻址:通过资源的名称,以及资源内的字段。两者都不发布的填充没有可指向的定位符,因此该引用无法转换为任何内容。

所需的键取决于条目,诊断结果会说明它需要哪些键。自行指定 key: 的条目本身提供了字段,因此只需发布资源的 name,这使其能够引用多键资源。未指定 key: 的条目读取插槽唯一发布的字段,因此 name 和 key 都必须存在。

该检查只判断这些键是否存在,从不检查其值。所有违规条目会在同一个标题下一并报告。

发出的消息:

workload attachment slot is not referenceable (Workload in Recipe <name>:<version>, at <path>, slotReferenceability stage): .containers.<name>.attachments.<KEY>.from: slot "<slot>" is not referenceable: its resolved provides does not expose "<key>" (a workload attachment reference reads the provides keys name and key) — reference a slot filled by an attachment whose schema.provides declares the keys this reference reads, or deliver it through the slot’s inject pipe rather than a workload reference

修复方法: 有两个方向,哪个正确取决于你的本意。如果引用是正确的,需要修改的是填充该插槽的附件:附加一个其 schema.provides 声明了 name(以及在条目未自行指定时声明 key)的 Feature,使其有可指向的定位符。如果该内容本就不打算在输出中按名称寻址,则删除该引用,改为通过插槽的 inject: 管道交付;该管道传递的是值本身,而不是指向其所在位置的指针。

A container gives one environment variable two values(一个容器为同一个环境变量赋了两个值)

workload: 块中的某个容器两次命名了同一个环境变量:一次作为其 variables 的键,一次作为以 as: env 交付的 attachments 条目的键。主容器和 init 容器都会被检查,无论是组件的 Recipe 渲染的 Workload,还是 FeatureRecipe 渲染的 Workload(无论是附加到组件上的,还是在边界上声明的),检查读取的都是其模板渲染后的 Workload。

为什么停止而不是择一使用。 容器的环境按固定顺序由这两个集合写出:helm 和 compose provider 先写所有从 attachment 读取的条目,再写普通的 variables。因此,以两种方式写出的同一名称到达进程时,取值由该顺序决定谁胜出,这取决于两类条目落在何处,而不是你所写的内容,所以构建会拒绝这一对,而不是将其渲染出来。无论由哪个 provider 渲染该 Workload,该检查都只运行一次,在 Workload 的其他检查之后、artifacts: 条目求值或任何 provider 接收该 Workload 之前进行,因此被拒绝的一对永远不会被渲染。以 as: file 交付的 attachments 条目被挂载为文件,而不是设置在环境中,因此不会构成一对。

该检查只比较名称;它从不读取值,因此任何结果都不会引用值。有两类环境条目不在比较范围内:envFrom 条目设置的是它所命名的 ConfigMap 或 Secret 的键,这些键在构建运行时并不可知;而流水线步骤写入渲染文档的条目不属于该检查读取的 Workload。

每一对都是一个单独的结果,定位在声明该 Workload 的 Recipe 或 FeatureRecipe 的 workload: 键上,并给出变量名和容器:主容器按其键给出,init 容器按其在 initContainers 列表中的位置给出。结果先列出主容器,按编写顺序排列,然后按位置列出 init 容器;同一容器内按其 attachments 条目的编写顺序排列。

输出的消息(针对 Recipe 的 Workload 中某个主容器上的一对)。类别和此情况的短代码 E0345 出现在方括号标头中,位置显示为 <path> at .spec.workload:

a container declares one environment variable twice ("<NAME>", container "<container>"). Rename one of the two, or write them under complementary template conditions so that only one of them renders(一个容器两次声明了同一个环境变量。请重命名其中之一,或将它们写在互补的模板条件下,使其中只有一个被渲染)

init 容器上的一对则给出它在列表中的位置:init container "initContainers[<i>]";FeatureRecipe 的结果会在容器之后给出绑定它的 attachment,即 attachment "<attachment>",因为一个组件可能带有多个 attachment,而它们的 FeatureRecipes 是各自独立的文档。

当一个 Workload 带有多对时,结果会归组在一行给出文档的标题下:containers of the Workload this Recipe renders name one environment variable twice,或者对于 FeatureRecipe,containers of the Workload rendered by the FeatureRecipe that attachment "<attachment>" binds name one environment variable twice。

构建在 CATALOG_ERROR 标签下报告此停止,因为 workload: 块由 Recipe 或 FeatureRecipe 的作者编写,而不是由 Aggregate 或 Release 编写。

修复方法: 决定容器应当接收两者中的哪一个。如果两者都需要,重命名其中之一,使进程看到两个变量。如果它们互为替代(例如没有附加凭据时使用的普通回退值),则用互补条件保护它们,使恰好只有一个被渲染:将变量写在 {{ if not (hasKey (default dict .features) "<slot>") }} 之下,将 attachments 条目写在 {{ if hasKey (default dict .features) "<slot>" }} 之下,或写在同一个 {{ if }}/{{ else }} 的两个分支中。以这种方式保护的一对永远不会进入该检查,因为渲染后的 Workload 中只有其中一个。

Release 的 parameters: 块不符合其两种形式中的任何一种

Release 以两种方式之一满足 Aggregate 声明的参数,该块按其形式读取。它要么是一个将参数名映射到就地写出的值的映射,要么是只有一个键 $import: 的映射,其值为存放这些值的 YAML 文件路径。两者都不是的块会在读取时被拒绝,早于任何依据 Aggregate 声明检查值的步骤。

有三种形式会被拒绝。根本不是映射的 parameters: 值,即标量或列表。在其他键旁边带有 $import: 的映射,它同时要求导入的值和写出的值,却没有给出合并它们的规则。以及值不是普通字符串的 $import:,它没有指明任何文件。

Release schema 声明了同样的两种形式,因此包含这三种情况之一的 Release 文件会先遇到文档信封检查,归于 E0215,该检查会尝试两种形式并说明每种为何失败——以下是列表的情况:

document envelope validation failed (Release, at <path>); <line>:<column>: spec.parameters: no oneOf branch matched (2 branches tried): branch[0]: type: expected object, got array; branch[1]: type: expected object, got array. correct the document to match its kind’s schema(文档信封校验失败(Release):spec.parameters:没有匹配的 oneOf 分支(尝试了 2 个分支):branch[0]:类型:期望对象,得到数组;branch[1]:类型:期望对象,得到数组。请更正文档以匹配其类型的 schema)

对于与其他键并列的 $import:,第二个分支以 additionalProperties: unexpected property: "<key>" 结尾;对于写成列表而非字符串的 $import:,则以 validation: type: array has type "array", want "string" 结尾。

值不是映射时输出的消息,指明在该处所写的内容——例如 a list:

parameters: shape must be an inline object or {$import: }: line <line>: <shape> is written where a map is expected(parameters:形式必须是内联对象或仅含 $import 的映射:在需要映射的位置写入了其他形式)

以及 $import: 与其他内容共处同一映射,或指明的不是路径时:

parameters: shape must be an inline object or {$import: }: $import: must be the only key (got <n> keys) at line <line>(parameters:形式必须是内联对象或 $import 映射:$import: 必须是唯一的键,在所示行得到了多个键) parameters: shape must be an inline object or {$import: }: $import value must be a string scalar at line <line>(parameters:形式必须是内联对象或 $import 映射:在所示行,$import 的值必须是字符串标量)

修复方法: 在消息给出的行打开该 Release。在 parameters: 下就地写出值,或将整个块替换为单个 $import: 条目,其值为带引号的路径。如果你既想要写出的值,又想要一个包含共享默认值的导入文件,请将写出的值移到一个 extends: 持有该导入的 Release 的 Release 中:叠加多个参数来源正是 extends: 链的用途,而这个键按设计只从单一来源读取。

An inline-or-import field is written in neither shape(内联或导入字段未按两种形状中的任何一种书写)

Recipe 或 FeatureRecipe 书写的三个字段——artifacts.<name>: 条目、valuesMapping: 和 workload:——接受相同的两种形状。要么在原处书写主体,作为字符串标量(多行内容通常使用 | 块),要么值是一个仅含一个键 $import: 的映射,指明主体所在的位置。$import: 可以指向什么因字段而异:artifacts 条目导入本地路径或 ArtifactLibrary 中的一个 bundle,而 valuesMapping: 和 workload: 导入本地路径或按标识指定的库中条目。

三个字段由同一个读取器检查,因此无论哪个字段出错,拒绝情形都是相同的三种:映射包含多个键;映射的唯一键不是 $import;$import: 的值不是普通字符串。既不是标量也不是映射的值(最常见的是列表)仅凭其形状即被拒绝。

Recipe 和 FeatureRecipe 的 schema 为这三个字段中的每一个都声明了同样的两种形式,因此包含上述任一情况的文件会先遇到文档信封检查,归于 E0215,该检查会指明字段并说明每种形式为何失败——第一个分支是就地编写的形式,第二个是 $import: 形式:

document envelope validation failed (Recipe, at <path>); <line>:<column>: spec.artifacts.<name>: no oneOf branch matched (2 branches tried): branch[0]: validation: type: object has type “object”, want “string”; branch[1]: additionalProperties: unexpected property: “<key>”. correct the document to match its kind’s schema(文档信封校验失败(Recipe):spec.artifacts 下的该条目没有匹配的 oneOf 分支(尝试了 2 个分支):branch[0]:校验:类型为对象,需要字符串;branch[1]:additionalProperties:意外的属性。请更正文档以匹配其类型的 schema)

这是一个在 $import: 旁带有其他键的映射。不是 $import 的单个键以 required: missing required property: $import, additionalProperties: unexpected property: "<key>" 结尾,列表以 type: expected object, got array 结尾,而不是字符串的 $import: 会指明在需要字符串之处发现的类型,如 type: array has type "array", want "string"。

输出的消息。每条消息以出错字段对应的句子开头,然后说明读取器发现了什么以及位置:

artifacts entry: shape must be a string scalar or {$import: }: got <n> keys at line <line>(artifacts 条目:形式必须是字符串标量或 $import 映射:发现多个键) valuesmapping: shape must be a string scalar or {$import: }: got key "<key>" at line <line>(valuesmapping:形式必须是字符串标量或 $import 映射:发现了其他键) workload: shape must be a string scalar or {$import: }: $import value must be a string scalar at line <line>(workload:形式必须是字符串标量或 $import 映射:$import 的值必须是字符串标量)

三个字段中的任何一个都可能报告上述任一结尾;既不属于任一形式的值以 line <line>: <shape> is written where text or a map is expected 结尾,并指明所写的内容——最常见的是 a list。

**修复方法:**打开该实体中消息指出的行。将主体作为块标量在原处书写,或将整个值替换为单个 $import: 条目。同时包含 $import: 和其他内容的映射不属于两种形状之一——将多余的键移到被导入的文件中,或在原处书写主体。拼写错误的 $import(最常见的是缺少 $)会被当作普通键读取,并被报告为不是 $import 的唯一键。

A reference to a library entry carries whitespace(对库条目的引用包含空白)

指向库内条目的引用写作一个不间断的记号:库名、可选的 :<version> 下限,然后是 # 和条目路径——BaseWorkloads:1.0.0#/workloads/StatelessService。其中任何部分都不允许空白。库名和条目名都被库 schema 限定为标识符拼写,而版本就是版本,因此引用中任何位置的空格、制表符或换行都不属于这三者中的任何一个。

该拒绝覆盖所有按标识引用库条目的位置:写作 $import: 的 valuesMapping:、workload: 和 artifacts.<name>: 条目,以及 schema 的 $ref:。写作 $import: 的本地路径不含 #,不是对库条目的引用,因此包含空格的路径不受影响。

之所以拒绝而不是整理,是因为这类值的前半部分通常本身就是一个引用。在空白处截断会解析那个引用,并悄悄丢弃作者写下的其余内容——而构建的两个部分不一定丢弃相同的量,因此一方可能记录了另一方从未见过的依赖。拒绝可以确保该值只表示一种含义。

该拒绝在读取引用的文档中的对应行报告:

library reference: a reference to a library entry carries no whitespace or line break: $import target "<reference>" at line <line>(库引用:对库条目的引用不能包含空白或换行:$import 目标)

引用还可能从另一个地方进入构建:构建已解析的某个库条目的主体,其第一行的字段根 $import: 指向另一个库的条目。该引用从未从构建打开的文档中读取,因此报告时不带行号:

library reference: a reference to a library entry carries no whitespace or line break: "<reference>"(库引用:对库条目的引用不能包含空白或换行)

**修复方法:**打开该实体中消息指出的行,合拢引用,使其成为一个记号。最常见的原因是 # 之前的换行——为适应列宽而折成两行的引用,对 YAML 来说是一个值,在这里却是一个断开的引用,因此无论多长都应写在一行。另一个原因是右引号前的尾随空格:它落在版本下限中,指向一个没有任何已发布制品具有的版本。对于第二种形式,引用位于消息中紧挨其前列出的库内;请在该库声明该条目的位置修正它。

A library entry’s body is not the shape that library holds(库条目的主体不是该库所容纳的形状)

库发布具名主体供其他实体导入,每种库类型容纳一种形状。MappingLibrary 条目和 WorkloadLibrary 条目各容纳一个模板主体,因此条目的值是标量——实际中是一个 | 块。ArtifactLibrary 条目容纳一个 bundle:在同一名称下归属在一起的文件,因此条目是输出文件名到该文件主体的映射,其下每个主体都是标量。

主体按原样捕获,在库加载时不解析。其中的模板在被导入处解析,这就是这里只检查形状的原因——根本不是模板的主体也能顺利加载,并在某处渲染它时失败。

输出的消息,每条都指明行号以及在该处所写的内容——例如 a list:

mappinglibrary: entry body must be a string scalar: line <line>: <shape> is written where text is expected(mappinglibrary:条目主体必须是字符串标量:在需要文本的位置写入了其他形式) workloadlibrary: entry body must be a string scalar: line <line>: <shape> is written where text is expected(workloadlibrary:条目主体必须是字符串标量:在需要文本的位置写入了其他形式) artifactlibrary: entry must be a mapping of filename to a string body: line <line>: <shape> is written where a map is expected(artifactlibrary:条目必须是从文件名到字符串主体的映射:在需要映射的位置写入了其他形式)

以及对于条目是映射、但其中某个文件不是标量的 bundle,消息会指出该文件:

artifactlibrary: entry must be a mapping of filename to a string body: file "<filename>": line <line>: <shape> is written where text is expected(artifactlibrary:条目必须是从文件名到字符串主体的映射:该文件在需要文本的位置写入了其他形式)

构建在 CATALOG_ERROR 标签下报告这些错误,标签中指出正在读取的文件,其下附上上述句子。

**修复方法:**在其键下将主体写作块标量。第一行看起来像 YAML 键的主体(生成 YAML 的模板通常如此)除非使用块标量,否则会被读作嵌套映射,这是常见原因。对于 ArtifactLibrary,每个输出文件名写一个键,每个主体各自写作块标量;将 bundle 写成单个主体是另一种常见的形状错误。

无法解析 $instantiate: 引用

SchemaLibrary 可以在 spec.templates 下声明可复用的结构,每个结构都有自己的 $params;之后,schema 条目在 $instantiate: 下指定其名称,并在 $args: 下提供参数,从而实例化该结构。替换是字面替换:模板主体中的 $<name> 标量会被替换为对应参数的值。不支持表达式求值、条件和循环,被替换进来的值按原样插入,不会再扫描其中的其他标记。

以下三种错误会导致实例化被拒绝:$instantiate: 下的名称不是该库声明的名称;模板声明的某个参数没有 default:,而 $args: 下也没有对应条目;或者某个参数值的类型与其参数声明的类型不符。此外,$args: 中指向未声明参数的键也按同样方式报告,而不是被忽略,因此拼错的参数名会导致拒绝,而不会让参数悄无声息地取默认值。

输出的消息:

schemalibrary: template not found: "<template-name>" not declared in spec.templates schemalibrary: template parameter missing: "<parameter-name>" (template "<template-name>") schemalibrary: template parameter type mismatch: <what the type check found> schemalibrary: template parameter type mismatch: argument "<argument-name>" is not declared in template "<template-name>"’s $params

修复方法: 如果找不到模板,请将名称改为该库在 spec.templates 下声明的名称,并检查导入的是否是你想要的库。如果缺少参数,请将其添加到 $args:,或在模板中为该参数设置 default:,以便调用方可以省略它。如果类型不匹配,请将参数值改为声明的类型,或放宽该参数的 type:;如果消息指出某个参数未声明,请更正其拼写或将其删除。

A schema uses a JSON Schema keyword the library does not admit(schema 使用了库不允许的 JSON Schema 关键字)

SchemaLibrary 内容中不允许使用 $dynamicAnchor 和 $dynamicRef。它们会把引用解析到哪个 schema 推迟到值被校验时才决定,这使库条目的含义取决于它从何处被导入,而不是取决于它本身写了什么;而编译器会在任何校验之前解析库的结构,因此被推迟的引用没有可供解析的对象。

该拒绝在三个位置执行,共同堵住了该关键字可能进入的两条途径。schema 条目在库加载时被扫描。模板主体在库加载时被扫描,因此字面包含该关键字的模板会在此时失败,而不是在首次实例化它的构建中失败。实例化后,替换后的主体会再次被扫描,因此把该关键字作为参数值传入也无法绕过前两道检查。

发出的消息:

schemalibrary: forbidden JSON Schema keyword: "$dynamicRef" at line <line>

修复方法: 将被推迟的引用替换为直接指向某个 $defs 条目的 $ref。如果结构确实因使用场景而异,请将这种差异表达为带 $params 的模板,并在每次使用时实例化:这正是此处提供的替换机制,它会在任何针对结果的校验之前完成解析。

A document nests deeper than the reader will descend(文档嵌套层级超过读取器允许的深度)

每个编写的映射都会被读入一个保留键书写顺序的结构,因为该顺序会进入渲染输出,是构建在多次运行中保持字节级一致的因素之一。该读取器只下降有限的层数(一百层),拒绝继续深入,因此原本会耗尽读取器自身栈空间的输入会以拒绝的形式如实报告。

发出的消息:

a document nests too many levels deep: it is read at most 100 levels deep(文档嵌套层级过深:最多读取 100 层)

修复方法: 实际编写的文档通常只嵌套几层,因此达到一百层的文档多半是生成的、机器翻译的,或意外自引用的。请查找展开成自身的值:引用自身所在内容的 YAML 锚点会被上文对应的中止条件拒绝,但反复输出同一结构的生成器不会。如果深度确实必要,请将较深的分支提取为独立的实体,并按名称引用它。

A provider declares a well-known annotation at a scope it does not render(provider 在其不渲染的作用域上声明了 well-known 注解)

为 provider 提供服务的 Plugin 会声明关于自身的两件事,二者必须一致。在 spec.provider.wellKnownAnnotations 下,它列出其处理的注解,以及读取每个注解的作用域。在 contract.inputKinds 下,它声明自己会渲染哪些输入类型。如果某个键声明在一个作用域上,而该作用域对应的输入类型并未被同一实体声明,那么这两项声明就在同一文件中相互矛盾,因此该实体在加载时会被拒绝。

该检查是将实体与其自身进行比较,因此不需要插件二进制文件,并且在任何读取该实体的地方都会触发,包括在从未拉取过该制品的机器上遍历目录时。

有两类条目有意不参与比较。boundary 作用域的条目不指定输入类型,因为它针对整个 boundary 解析一次,而不是在某个节点的渲染路径上解析。完全未声明作用域的条目不对任何路径作出声明:它只表示插件会在某处读取该键。

该拒绝不能证明保留下来的声明是真实的。没有任何方法能证明为 provider 提供服务的插件确实读取了它声称读取的键;比较两个编写的字段所能做到的,只是拒绝不可能同时成立的组合。如果某个键声明在 provider 确实渲染的作用域上,而其插件在那里什么也不读取,它也能通过此检查。

发出的消息:

provider "<plugin-name>" declares well-known annotation "<key>" at scope "<scope>", but its contract.inputKinds.<field> is not claimed; declare the key only at a scope the provider renders, or claim the input kind: wellKnownAnnotations: a key is declared at a scope the provider’s contract does not render

修复方法: 消息会指出矛盾的两方面。要么从该注解的 scope: 列表中删除该作用域,只保留 provider 确实渲染的作用域;要么,如果 provider 确实渲染该输入类型,就在 contract.inputKinds 下声明它。

A compact-form schema uses a keyword the compact form does not know(紧凑格式 schema 使用了紧凑格式不认识的关键字)

以紧凑格式编写的 schema 带有一个键,它既不是紧凑格式关键字,也不是该格式透传的 JSON Schema 关键字,也不是该格式保留的三个标记之一——$jsonschema:、$mode: 和 $ref:。未知键在读取 schema 时即被拒绝,而不是被丢弃,因为被忽略的拼写错误约束等于完全没有约束,而一个看似在强制约束、实际什么都不强制的 schema 比直接失败的 schema 更糟。

凡是编译 schema 的地方都会遇到这一拒绝。SchemaLibrary 的条目在加载 catalog 时编译;Component 的 spec.schema、其按 socket 声明的 valueSchema 和 infraSchema,以及 Feature 和 provider Plugin 声明的 schema,在读取 catalog 时编译。Component 或 Feature 的 spec.schema 会自行报告此条件,并指明实体和字段;socket 的 valueSchema 或 infraSchema 则在下文的“A declared schema contract cannot be read as a schema(声明的 schema 契约无法作为 schema 读取)”之中报告,并以此处引用的语句作为其详情。

紧凑格式编译器自身的语句会指出 schema 内的位置、源代码行,以及它无法识别的键:

compactform at <path-inside-the-schema>:<line> (keyword "<key>"): unknown keyword

写在跨文档 $ref: 旁边的键也在同一条件下报告,但使用单独的语句,因为这类引用只允许三个同级键:

compactform at <path-inside-the-schema>:<line> (keyword "<key>"): cross-document $ref sibling not allowed (allowed: properties, required, description)

如果该同级键试图重新开放合并后的结构,语句会给出替代做法:

compactform at <path-inside-the-schema>:<line> (keyword "additionalProperties"): cross-document $ref sibling not allowed (allowed: properties, required, description); use $jsonschema: to embed an open-object schema if the merged shape must accept arbitrary properties

它记录所属的条件是 compactform: unknown keyword,也就是其短代码所对应的条件。

**修复方法:**对照 compact-form-authoring.md 中的关键字词汇表,修正语句所指位置上的键——拼写错误是最常见的原因。如果该结构确实需要紧凑格式不支持的 JSON Schema 关键字,就把该片段写在 $jsonschema: 下,它会原样嵌入 JSON Schema。在跨文档引用旁边只保留 properties:、required: 和 description:;其他内容应写在该引用指向的库条目中。

紧凑形式的 schema 声明了一个字面名为 type 的字段

紧凑格式根据映射内容的结构判断其含义:type: 键表示约束叶节点,结构性 JSON Schema 关键字表示需要透传的片段,而由普通名称组成的映射表示子项均为 schema 的对象。声明一个名为 type 的字段的 schema,正是这几种解读无法区分的唯一结构——它看起来像约束叶节点,实际意图却是只有一个字段的对象——因此该格式要求作者通过设置为 compact 或 jsonschema 的 $mode: 键来说明是哪一种。

$mode: 写成其他任何值时,报告的就是这一条件。该标记的存在是为了消除歧义,因此无法消除任何歧义的值会被拒绝,而不是被猜测。

紧凑格式编译器自身的语句:

compactform at <path-inside-the-schema>:<line> (keyword "$mode"): value must be compact or jsonschema

它记录所属的条件是 compactform: ambiguous dispatch — $mode required,也就是其短代码所对应的条件。

**修复方法:**如果该映射是一个紧凑格式对象,只是其字段中恰好有一个名为 type,就设置 $mode: compact;如果该映射是要按原样采用的 JSON Schema 片段,就设置 $mode: jsonschema。如果两种解读都不是本意,重命名该字段即可消除歧义,完全不需要标记。

$jsonschema: 逃生舱口所含的内容不是 schema

$jsonschema: 键会原样嵌入一个 JSON Schema 片段,用于紧凑格式无法表达的结构。它嵌入的内容按原样采用,从不转换,因此它本身必须是一个 schema:一个可解析为 YAML 的块标量,或一个嵌套映射。两者都不是的内容会在此处被拒绝,而不是被传递下去用作校验依据——否则失败会针对该 schema 的使用方报告,而不是针对 schema 本身。

有四种结构会在此条件下报告,语句会说明你遇到的是哪一种。转义体无法解析为 YAML。转义的值既不是块标量也不是映射。properties: 键的内容不是名称到 schema 的映射。以及,在最外层,交给编译器的文档为空,或包含读取器没有处理规则的节点。

紧凑格式编译器自身的语句:

compactform at <path-inside-the-schema>:<line> (keyword "$jsonschema"): escape content does not parse as YAML: <what the parse reported> compactform at <path-inside-the-schema>:<line> (keyword "$jsonschema"): expected block-scalar string or nested mapping compactform at <path-inside-the-schema>:<line> (keyword "properties"): expected a mapping of property names to schemas compactform: unsupported YAML node kind

它记录所属的条件是 compactform: $jsonschema content invalid,也就是其短代码所对应的条件。

**修复方法:**在 $jsonschema: 下把转义体写成块标量——否则首行看起来像 YAML 键的转义体会被并入外围映射,这是常见原因——并检查其内容本身是否为有效的 JSON Schema。如果该片段足够小、可以用紧凑格式表达,去掉转义是更简单的做法。

A compact-form constraint does not apply to the type it was written on(紧凑格式约束不适用于其所在的类型)

紧凑格式约束按字段声明的类型分派:min: 和 max: 在数字上成为数值界限,在字符串上成为长度界限,在数组上成为数量界限。因此约束必须位于类型接受它的字段上,而且类型必须是单一值,分派才有结果。

有四种结构会在此条件下报告。约束所在之处缺少 type: 或其指定的是联合类型,因而无法确定指的是哪种界限。约束写在不接受此类界限的类型上——对象或布尔值。type: 的值既不是标量名称也不是名称序列。以及 valuesType: 被赋予标量名称以外的内容。

紧凑格式编译器自身的语句:

compactform at <path-inside-the-schema>:<line> (keyword "<constraint>"): constraint applies to a single declared type (integer/number/string/array); type: is unresolved (union or absent) — narrow type: to a single value or remove this constraint compactform at <path-inside-the-schema>:<line> (keyword "<constraint>"): constraint applies to integer/number/string/array; declared type is <the type as written> compactform at <path-inside-the-schema>:<line> (keyword "type"): expected a scalar type name or a sequence of type names (JSON Schema 2020-12 array-of-types); got unsupported node kind compactform at <path-inside-the-schema>:<line> (keyword "valuesType"): expected a scalar type name

它记录所属的条件是 compactform: constraint not valid for declared type,也就是其短代码所对应的条件。

**修复方法:**语句会指出两方面——约束及其遇到的类型。type: 为联合类型时将其收窄为单一名称,缺失时补上,如果该字段确实可以取多种类型之一,则去掉该约束。需要随类型变化的界限,应在 $jsonschema: 下表达为一组备选项,每个分支带有各自的类型和界限。

A $ref: is not written in a form the compiler can resolve($ref: 的写法不是编译器能够解析的形式)

schema 通过 $ref: 引用另一个结构,可以在同一文档内引用,也可以跨文档引用某个 SchemaLibrary 条目。引用失败有两种方式,分别由两个条件覆盖,诊断语句会告诉你属于哪一种:引用的写法不是编译器能读取的形式;或者引用格式正确,但所指的目标不存在。

引用无法读取。 值为空,或其跨文档形式不是 <Library>#/schemas/<Entry>,或用 @ 分隔版本。最后一种情况报告时会给出修正后的写法,而不是笼统的报错,因为这是该形式最常见的错误:

compactform at <path-inside-the-schema>:<line> (keyword "$ref"): expected a non-empty reference URL(应为非空的引用 URL) compactform at <consumer-document> (keyword "$ref"): cross-document $ref shape must be <LibraryName>#/schemas/<EntryName>: <the value as written>(跨文档 $ref 的形式必须是库名#/schemas/条目名) compactform at <consumer-document> (keyword "$ref"): cross-document $ref version separator is ’:’, not ’@’ — use <the corrected value>: <the value as written>(跨文档 $ref 的版本分隔符是“:”而不是“@”,请使用更正后的值)

这些情况记录在条件 compactform: $ref unresolvable 之下。

目标不存在。 引用的写法正确,但库或库中的条目不存在,或者根本没有提供可供解析的库目录:

compactform at <consumer-document> (keyword "$ref"): SchemaLibrary <library> not found in catalog (referenced from <consumer-document>): <the value as written>(在目录中找不到该 SchemaLibrary) compactform at <consumer-document> (keyword "$ref"): entry <entry> not found in SchemaLibrary <library>: <the value as written>(在该 SchemaLibrary 中找不到该条目) compactform at <path-inside-the-schema>:<line> (keyword "$ref"): cross-document $ref but no SchemaLibrary catalog supplied: <the value as written>(存在跨文档 $ref,但未提供 SchemaLibrary 目录)

这些情况记录在条件 compactform: cross-document $ref target not found 之下。

将两者区分开,报告才具有可操作性:前者是需要在你正在查看的文档中改写的值,后者则是构建能看到什么的问题。展开为自身的引用又是第三种情况,报告为上文的“A library reference expands into itself (库引用展开为自身)”。

如何修复: 对于无法读取的引用,改写其值:跨文档引用写作 <Library>#/schemas/<Entry>,同一文档内的引用写作 #/$defs/<name>;版本下限前使用 : 而不是 @。对于不存在的目标,对照发布该条目的库确认条目名称,并确认该库可从 Release 的依赖闭包中到达:没有任何实体声明依赖的库不会被加载,因此即使引用写法正确,也仍然解析不到任何内容。

库仅位于制品缓存中的情况。缓存保存的是获取操作放入其中的内容,而缓存中的库只有在该 Release 的锁文件中有条目为其摘要作保时,才算作目录内容。当缓存中存放着一个既没有任何锁文件条目固定、也没有任何 catalog 目录提供的 SchemaLibrary 时,报告之后会跟随一行 remediation:,列出每个这样的库,以及对报告它的命令有效的操作:

  • aggrega build 和 aggrega validate --release 会读取该 Release 的锁文件,因此它们的这一行会指出 aggrega pull --release <release>(它会解析该库并记录其条目),或者在 catalog 目录下编写该库。
  • 不带参数的 aggrega validate,以及带实体路径的 aggrega validate(无论是否给出 --release),只从 catalog 目录读取库,不读取任何锁文件,因此已记录的条目不会改变它们的结论。它们的这一行会说明这一点,并指引你在 catalog 目录下编写该库,或先运行 aggrega pull --release <release>,再运行 aggrega validate --release <release>,后者会依据 Release 的锁文件所固定的库来检查该 Release。

找不到此类库的拉取会在 A reference names no entity the catalog holds(引用指向目录中不存在的实体) 下报告它,并单独给出一行。

A $ref: addresses a library by registry location($ref: 通过注册表位置寻址库)

跨文档 $ref: 按标识命名其库,即库的裸名称,后接 # 和条目路径,而从不按库恰好发布到的注册表命名。名称通过哪个注册表解析由工作区配置决定,使用哪个版本由锁文件决定,因此带有主机的引用会把本应由构建决定的两件事固定在 schema 中,并且 schema 在工作区之间移动时会变成损坏的引用。

如果带主机的值仍能解析出库和条目,诊断语句会给出应改用的标识形式写法:

compactform at <consumer-document> (keyword "$ref"): cross-document $ref carries a registry host; reference the library by identity (use <Library>#/schemas/<Entry>): <the value as written>(跨文档 $ref 带有注册表主机;请按标识引用该库)

如果无法解析,诊断语句在值之后结束:

compactform at <consumer-document> (keyword "$ref"): cross-document $ref carries a registry host; reference the library by identity: <the value as written> (跨文档 $ref 带有注册表主机;请按标识引用库)

该情况记录在条件 compactform: cross-document $ref carries a registry host; reference the library by identity 之下,其短代码即解析为此条件。

**修复方法:**删除主机以及库名之前的所有内容,只保留 <Library>#/schemas/<Entry>。如需版本下限,在库名之后写作 :<version>。同一规则也适用于 Recipe 和 FeatureRecipe 上的 $import: 字段,这些字段在下文“A library $import: addresses its library by registry location(库导入按注册表位置寻址其库)”下单独报告。

A schema $import: cannot be applied(无法应用 schema 导入指令)

Component 或 Feature 的 spec.schema(整个块或其中一个支柱),以及 usesSchema 插槽的 valueSchema: 或 infraSchema:,都可以写成 $import:,指向实体旁边的某个文件。导入在加载实体时应用,因此之后的每个读取方看到的都是导入的契约,而不是指针。当你所写的内容有误时,就会出现此条件:可能是指令本身有误,也可能是它所指文件中的内容结构有误。

这些错误归为同一个条件,因为每一种都会使同一个位置无法使用,并且需要你做同一件事:修正指令或它所指的文件。诊断以固定语句开头,随后说明是哪种错误,因此应匹配该语句,并根据其后的子句采取行动:

a schema $import: could not be applied. <surface>: <the clause for this occurrence>(无法应用 schema 导入指令。随后依次为所读取的位置及本次出现对应的子句)

子句会指出所读取的位置,即 spec.schema、其中的某个支柱(如 spec.schema.values)或某个插槽的 valueSchema,随后给出具体错误。各错误及其含义如下:

  • $import: must be the only key when a schema is imported from a file.(从文件导入 schema 时,该导入指令必须是唯一的键。) 该指令与手写的 schema 内容共用同一个映射。$import: 会替换整个值,因此同级的键没有可以合并的对象。
  • $import: value must be a path to a file.(该导入指令的值必须是文件路径。) 该值为空,或者不是单个字符串。
  • $import: takes a file path beside this entity, not a registry location <value>.(该导入指令接受的是此实体旁边的文件路径,而不是注册表位置。) 该值指向了一个注册表。名称通过哪个注册表解析属于工作区配置,因此 schema 位置从不携带注册表;消息会给出应改用的引用形式。
  • $import: takes a file path beside this entity; reference the SchemaLibrary entry <value> with $ref: instead.(该导入指令接受的是此实体旁边的文件路径;请改为用引用关键字引用该 SchemaLibrary 条目。) 该值指向了一个库条目。库条目应被引用,而不是导入——$ref: 才是解析库条目的关键字。
  • imported schema <value> must be a YAML map of schema content; it is not.(导入的 schema 必须是包含 schema 内容的 YAML 映射,但实际不是。) 文件已找到、读取并解析,但解析结果是标量或序列,因此没有可替换的 schema 内容。

头部包含类别和此条件的短代码 E0266。当你需要持久地标识此中止时(例如在持续集成门禁、问题单或运维手册中),应记录该标识符。编号一经分配便固定不变,因此无论其周围的措辞如何改进,它都保持不变;所有条件的表可解析该编号。

格式正确、但所指文件构建无法获取的指令,会在别处以不同代码报告。 无法解析的路径、不存在或无法读取的文件,以及无法解析为 YAML 的字节,都不是你所写内容的错误(因为没有可供判断的导入文档),因此它们按加载错误报告,归在上文的“A file cannot be read, or its bytes do not parse (文件无法读取,或其字节无法解析)”之下,该处说明了每种情况所带的子句。如果你要捕获的是缺失或无法读取的导入文件,请匹配该条件并记录其代码。

路径相对于包含实体文件的目录进行解析,这与其他所有带导入的字段使用的基准相同。如果导入的内容本身又声明了 $import:,会继续跟随;若导入链返回到某个正在处理中的文件,则报告为上文的“A library reference expands into itself (库引用展开为自身)”,而不在此处报告。写在由导入引入的文件中的指令,会在该文件及其中的行处报告,因为那里才是需要修正的地方;写在实体中的指令则在实体处报告。

如何修复: 使 $import: 成为其映射中唯一的键,并为其提供指向实体旁边某个 YAML 文件的相对路径,该文件的顶层须为包含 schema 内容的映射。要使用 SchemaLibrary 发布的结构,请改用 $ref: <Library>#/schemas/<Entry>:库条目应被引用,而不是导入。

A schema block names a key that is not a data pillar (schema 块中出现了不是数据支柱的键)

Component 或 Feature 的 spec.schema 块承载实体的数据支柱,它只接受三个键:values,即开发者为每个实例填写的结构;infra,即运维人员提供的物理规格;以及 provides,即实体向其使用方公开的键。当该块的顶层出现其他键时,就会出现此条件。

该集合是封闭的而非开放的,原因与每个支柱自身内容按封闭方式校验相同:一个列举合法范围的块,会使该范围之外的任何内容成为错误。无法识别的键所承载的契约永远不会被编译、用于校验或交给使用方,因此你在其下写的内容看起来已声明,实则不起作用。这比根本没写契约更难察觉,所以编译器拒绝整个块,而不是忽略多余的键。

诊断以固定语句开头,随后指出实体、规则、键所写的位置,以及应改写为什么:

a schema block declares a key that names no data pillar (<Kind> <name>, rule schema-pillars, at .spec.schema.<key>). rename "<key>" to one of the pillar keys, or remove it and the contract beneath it; allowed: values, infra, provides. See vocabulary/data-pillars.md for the canonical pillar set.(schema 块声明了一个不对应任何数据支柱的键。请将该键重命名为某个支柱键,或删除它及其下的契约;允许的键:values、infra、provides。规范的支柱集合见 vocabulary/data-pillars.md。)

头部包含类别和此条件的短代码 E0267。当你需要持久地标识此中止时(例如在持续集成门禁、问题单或运维手册中),应记录该标识符。编号一经分配便固定不变,因此无论其周围的措辞如何改进,它都保持不变;所有条件的表可解析该编号。

写在该位置的两种内容不属于此集合的键,也都不在此处报告。 指向实体旁边文件的 $import: 会在读取该块之前被替换为该文件的内容,因此此条件检查的是导入文档自身的顶层:导入文件内部的多余键会在此处报告,而指令本身从不会。此外,声明了 extends 的 Component 会在该块的位置写入裸字符串 inherited,它是一个不含任何键的标量。

如何修复: 诊断语句会给出它遇到的键以及允许的三个键,因此最常见的原因(拼写错误,或在支柱名为复数处写成了单数)仅凭诊断即可看出。如果多余键下的内容属于某个支柱,请按其归属将其移到 values:、infra: 或 provides: 之下;data-pillars.md 说明了各支柱分别负责什么。如果它本意是独立的 schema 内容,则应再深一层,放在某个支柱内部,而不是与支柱并列。SchemaLibrary 发布的结构应通过写在支柱内部的 $ref: <Library>#/schemas/<Entry> 引用,而不是写在块这一层。

A plugin asks the host to parse a source while a parse is already running for it(插件在宿主已为其运行解析时请求宿主解析源)

插件可以请求宿主解析一个源并返回结果,这样需要某种格式文档的插件就不必自带该格式的读取器。宿主会运行产生该解析的插件,并返回其产出。本条件指的是:以这种方式被调用的插件又发起了自己的解析请求。该请求会重新进入它当前正运行于其中的同一机制,宿主会拒绝而不是继续向下递归。该机制只提供一层这样的调用,而拒绝正是将其限制在一层的手段。

拒绝传达给插件,而不是构建。 宿主不会就此停止并回退;它以一个失败信封响应该调用,信封中携带下面的句子和一个指明该拒绝的代码,发起请求的插件会将其作为请求的应答收到。构建随后如何进行,取决于该插件如何处理这个应答:将其视为致命错误的插件会终止构建,而报告后继续执行的插件则不会。无论哪种情况,拒绝本身都相同。

这并不特别是某一个插件的过错:该防护覆盖请求所经过的任意一对插件,而不是某个指定的配对,因此无论在何处重新进入该机制,都会遇到同样的拒绝。

插件收到的输出消息:

aggrega_parse_source: producer-consumption re-entry denied: a producer reached through the host may not issue a further producer-consumption call(aggrega_parse_source:拒绝生产者消费重入:通过宿主调用的生产者不得再发起生产者消费调用)

如何修复: 你自己的文件中没有任何内容会导致此问题,也没有任何编写上的修改能消除它——这是构建所配置插件的一种属性。需要修正的是在解析内部请求解析的那个插件,因此请将此情况报告给该插件的发布者,并附上该消息。如果该插件是你自己的,请让它直接读取交给它的源,而不是在自身正在提供解析时请求宿主解析另一个源。

The workspace configuration is invalid(工作区配置无效)

工作区由其根目录下的 .aggrega-config.yaml 描述:它向哪个 registry 发布、从哪个 registry 拉取,制品缓存位于何处,哪些插件挂载在哪些 socket 上,以及每个 registry 的签名立场是什么。该文件会在打开任何实体文件之前被读取并按其 schema 检查,因为后续的一切都从它读出。

**缺少文件并不是失败。**没有配置文件的工作区会获得文档所述的默认值,因此这一终止从不指向不存在的文件。它指向承载该值的文件;对于由环境变量覆盖、schema 从未见到的设置,则指向该变量。

检查在文档被转换为类型化设置之前运行。正是这一顺序让消息能够指出 schema 所反对的字段路径,而不是在后续某处报告一个无字段可指的类型不匹配。

除普通的 schema 反对外,以下形态也在此报告,原因都是仅凭 schema 只能给出过于笼统、无法据以处理的说明:下面什么也没写的 workspace: 键;本应位于顶层却写在 workspace: 下的键;以文件不使用的名称书写的 cache: 块;未按 registry 主机写法书写的 registry 主机;以及 schema 允许但工作区无法使用其值的三项设置——为绝对路径或指向工作区根目录本身的 artifact_cache_dir,指向非可发布制品类型的 signing.kinds 条目,以及 uri 为以 oci:// 书写的注册表位置的 plugins.providers 或 providers_append 条目。provider 绑定按插件的标识指明其插件,即 provider/<name>,可带可选的 :<version>,因为解析 capability 时,绑定正是按这个标识进行匹配的;注册表位置说明的是插件发布在哪里,而不是它是哪个插件,因此写成注册表位置的条目永远无法选中任何东西。以 function: 指明入口函数却没有 uri: 的条目也在此报告,前提是它是 plugins.linter 或 linter_append 条目,或者是处于裁定角色(ir-verdict 或 render-verdict)的 plugins.governance 或 governance_append 条目:这些挂接项按 uri 选择其插件,因此这样的条目不挂接任何插件,它指明的函数也永远不会被调用——lint 会像该条目不存在一样继续运行,而构建只会在稍后、要解析一个该条目从未指明的插件时才停止。

配置列出的 catalog 目录——无论列在 workspace.catalog_dirs 或 catalog_dirs_append 下,还是列在 workspace.releases 下某个 Release 自己的条目中,也无论位于读取配置的哪个文件里——若不是目录,也会在此报告:该路径上什么都不存在,或者那里是一个文件或一个不指向任何地方的链接。该判断在即将通过它读取 catalog 时进行,因此每个读取 catalog 的命令都会在读取或写入任何内容之前拒绝它,而不读取 catalog 的命令仍会运行。若不顾它继续读取,构建所依据的 catalog 就会比你列出的少,且没有任何信息说明少了哪些。AGGREGA_CATALOG_DIRS 列出的目录遵循同样的规则,拒绝信息会指出该变量而不是文件。

registry 主机——即 registries 条目的 host,或 default_registry 开头的主机(当它未通过 name: 指向这些条目之一时;若指向了,则代表该条目的主机)——按主机本身书写:小写,包含点号,或为 localhost,或为单个名称后跟端口,或为 IP 地址(IPv6 地址加方括号),均可带可选的 :port,且不含 scheme 或凭据。registries 条目的主机不带路径;default_registry 可在主机后跟 / 和仓库路径——由 / 连接的小写段,不带标签、摘要或末尾的 /。以其他拼写指向某主机的值会被拒绝,并给出应写的拼写(对于 default_registry,给出包括路径在内的完整位置),以便该主机下保存的信任策略适用于它;这包括通过 HTTPS 访问的主机上的 443 端口,因为那是该主机的默认端口。不是仓库路径的路径会被拒绝,并指出其前面的主机;条目的 name: 后跟路径会被拒绝,并给出应改写的两种拼写:仅写名称,或写该条目的主机后跟路径,因为名称代表其条目的主机,而非其下的某个位置。完全不指向主机的值——没有条目使用、也不带端口的单个名称,含空格或花括号的文本——会作为非主机被拒绝,对于 default_registry,拒绝消息还会说明使用条目名称同样可行。AGGREGA_DEFAULT_REGISTRY 按相同方式解读并以相同方式被拒绝,消息指出该变量。

**发出的消息。**schema 反对会指出文件、字段路径以及 schema 的说明:

workspaceconfig: <path>: <field-path>: <the schema's own objection>: workspace configuration is invalid(工作区配置无效)

修复提示形式以文件开头,并用一句针对具体形态的说明代替字段路径和 schema 的反对。指向工作区根目录的 artifact_cache_dir:

<path>: artifact_cache_dir "<value>" names the workspace root itself; a catalog directory at the workspace root would then be stepped over as cache, leaving nothing to load — give the cache its own subdirectory (for example .aggrega/cache): workspace configuration is invalid(artifact_cache_dir 的值指向了工作区根目录本身;这样位于工作区根目录的目录会被当作缓存跳过,导致没有可加载的内容——请为缓存指定单独的子目录:工作区配置无效)

不可用的 signing.kinds 条目,消息还会给出涵盖所有类型的通配符:

<path>: signing.kinds entry "<kind>" is not a signable artifact kind; use a catalog entity or plugin kind, or "all" for every kind: workspace configuration is invalid(signing.kinds 中的该条目不是可签名的制品种类;请使用目录实体种类或插件种类,或使用表示所有种类的通配值:工作区配置无效)

写成注册表位置的 provider 绑定,它会指出该条目、capability 以及应写的形式:

<path>: plugins.providers[<n>] binds capability "<capability>" to "oci://<registry>/<repository>", which is where a plugin is published rather than which plugin it is; a provider binding names its plugin by its identity — write uri: provider/<name>, with an optional :<version>: workspace configuration is invalid(plugins.providers 条目把 capability 绑定到了注册表位置,而注册表位置说明的是插件发布在哪里,而不是它是哪个插件;provider 绑定按插件的标识指明其插件——请在 uri 中写插件的标识,可带可选的版本:工作区配置无效)

指明了入口函数却没有指明插件的 linter 挂接项或裁定角色的治理挂接项,该消息会指出列表、条目和函数,此处以 plugins.linter 为例:

<path>: plugins.linter[<n>] names the entry function "<function>" but no plugin uri; an attachment on this list selects its plugin by uri, so this one attaches no plugin and "<function>" is never called — add the uri of the plugin that exports it: workspace configuration is invalid(plugins.linter 中的条目指明了入口函数,但没有指明插件的 URI;此列表上的挂接项按 URI 选择其插件,因此该条目不挂接任何插件,该函数永远不会被调用——请添加导出该函数的插件的 URI:工作区配置无效)

以其他拼写书写的 registry 主机,此处为 HUB.AGGREGA.AI:

<path>: default_registry "HUB.AGGREGA.AI" is not written as the registry host it names; write "hub.aggrega.ai" — lowercase, with no scheme, path, credentials or default port — which is the spelling that host’s trust policy is kept under: workspace configuration is invalid(default_registry 的值没有按其所指注册表主机的写法书写;请改用小写、不带协议、路径、凭据或默认端口的写法,该主机的信任策略正是以这一写法存放的:工作区配置无效)

默认 registry 的主机在其仓库路径前以其他拼写书写,此处为 GHCR.io/acme,消息给出应写的完整位置:

<path>: default_registry "GHCR.io/acme" is not written as the registry location it names; write "ghcr.io/acme" — the registry host lowercase, with no scheme, credentials or default port, followed by the repository path — which keeps that host’s trust policy applying to it: workspace configuration is invalid(default_registry 的值没有按其所指注册表位置的写法书写;请将注册表主机写为小写、不带协议、凭据或默认端口,后接仓库路径,这样该主机的信任策略才会继续适用于它:工作区配置无效)

条目名称后跟路径,此处为 local/acme,而名为 local 的条目对应 127.0.0.1:5000:

<path>: default_registry "local/acme" is the name of the registries entry "local" followed by a path, and an entry’s name stands for that entry’s host alone; write "local" to use the entry, or its host followed by the path, "127.0.0.1:5000/acme": workspace configuration is invalid(default_registry 的值是 registries 条目的名称后接路径,而条目名称只代表该条目的主机;若要使用该条目,请只写条目名称,或写该条目的主机后接路径:工作区配置无效)

不指向任何主机的值,其说明会列出主机可采用的形式:

<path>: registries[<n>].host "<value>" is not a registry host; write a lowercase host name containing a dot (registry.example.com), localhost, a single name followed by a port (registry:5000), or an IP address, an IPv6 one in brackets — each with an optional :port and nothing else: workspace configuration is invalid(不是 registry 主机;请写包含点号的小写主机名(registry.example.com)、localhost、单个名称后跟端口(registry:5000),或 IP 地址(IPv6 地址加方括号)——均可带可选的 :port,不含其他内容:工作区配置无效)

列出的 catalog 目录处什么都不存在时,消息会指出文件和行、列表、按原样书写的条目及其解析到的路径——列表为 workspace.catalog_dirs、workspace.catalog_dirs_append,或某个 Release 条目的列表,例如 `catalog_dirs` of the `workspace.releases` entry "release.yaml":

<path>:<line>: the `workspace.catalog_dirs` entry "<entry>" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalid(该条目指明的目录不存在;请创建该目录,或删除该条目:工作区配置无效)

以及空的 workspace: 标记:

workspaceconfig: <path>: workspace must be a mapping; write workspace: {} to mark a workspace root with no catalog directories: workspace configuration is invalid(workspace 必须是映射;若要标记一个没有目录的工作区根目录,请写一个空映射:工作区配置无效)

另外两种指出写错位置的键——default_registry、offline、auto_pull 和 artifact_cache_dir 都位于顶层而非 workspace: 之下,解析缓存的块是 parse_cache:。每条消息都会说明所指的键及其应在的位置。

**如何修复:**打开消息指出的文件,找到它引用的字段路径。消息带有修复提示时,它会直接给出正确的拼写或位置,无需进一步查阅。若带的是 schema 反对,字段路径即出错的键,反对说明了 schema 在该处期望什么——实体页面并不约束此文件,因此请阅读该反对说明,而不是去查找实体契约。artifact_cache_dir 相对于工作区根目录书写,且需要独立的子目录,这样位于工作区根目录的目录才不会被误认为缓存而被跳过。写成注册表位置的 provider 绑定需要手动改写为插件的标识——oci://hub.aggrega.ai/plugin/provider/compose 改为 provider/compose——因为在改写之前,所有读取该文件的命令都会拒绝它,aggrega plugin remove 也不例外;aggrega plugin add provider 本身就会写出标识形式。指明了函数却没有指明插件的 linter 条目或裁定角色的治理条目,应补上导出该函数的插件的 uri;若没有插件导出它,则删除该条目——在 linter 列表上,标准 linter 随后会像未配置任何 linter 时那样运行。列出的 catalog 目录若不是目录,就在拒绝信息指出的路径上创建它,或从拒绝信息指出的那一行删除其条目;对于复制时未带上其所列同级检出的项目副本,删除该条目。

A plugin binding sets a key the socket it attaches to does not read(插件绑定设置了其所挂接的插槽不读取的键)

工作区配置中的插槽以两种不同方式挂接插件,属于其中一种方式的键在另一种方式上没有任何意义。配置不会接受该键并悄悄忽略它,而是被拒绝,这样运维人员能得知该设置不起作用,而不是事后疑惑它为何没有效果。

这两种不匹配互为镜像。

  • 按能力绑定的横切插槽。 governance、linter 和 importer 插槽直接通过 uri: 挂接插件。governance 或 linter 插件不提供任何能力,因此那里的 capability: 绑定会针对空集查找、匹配不到任何东西——这是一个永远无法解析的挂接。importer 确实会声明它处理的格式,但需要哪种格式应由导入来指定,而非由挂接指定:importer 挂接通过 uri: 指定其 importer,正是这一点决定了在声明某次导入所需格式的多个 importer 中选择哪一个。
  • provider 插槽设置了没有指代对象的键。 provider 绑定指定一个能力以及提供该能力的插件,而该插件驱动的是一组固定的导出,而不是一个可选择的入口,因此 function: 在其上不指代任何东西。with: 被拒绝则出于另一个原因:provider 的渲染配置写在 Recipe 中,把它放在工作区绑定上,就把它放到了开发者与运维人员分工的错误一侧。

发出的消息。 横切插槽上的能力:

workspaceconfig: the <socket> socket is bound by capability "<capability>", but the cross-cutting sockets attach by uri: their plugin serves no capability, so a capability lookup matches nothing; attach it with uri: instead: a cross-cutting socket is bound by capability but attaches by uri(该插槽按 capability 绑定,但横切插槽按 uri 附加:其插件不提供任何 capability,因此按 capability 查找匹配不到任何内容;请改为按 uri 附加:横切插槽按 capability 绑定,但它按 uri 附加)

provider 绑定上不起作用的 function::

workspaceconfig: the provider socket binding for capability "<capability>" sets function:, but a provider drives a fixed set of phase-keyed exports rather than one selectable entry, so function: names nothing there; remove it: a provider socket binding sets a field with no referent on that socket(该 capability 的 provider 插槽绑定设置了 function 字段,但 provider 驱动的是一组固定的、按阶段键控的导出,而不是一个可选择的入口,因此该字段在此不指向任何内容;请删除它:provider 插槽绑定设置了一个在该插槽上没有指代对象的字段)

以及不起作用的 with:,它以相同形式报告,并指出该配置应放在何处:

workspaceconfig: the provider socket binding for capability "<capability>" sets with:, but provider render configuration belongs in the Recipe, not the workspace provider binding; remove it: a provider socket binding sets a field with no referent on that socket(该 capability 的 provider 插槽绑定设置了 with 字段,但 provider 的渲染配置应写在 Recipe 中,而不是工作区的 provider 绑定中;请删除它:provider 插槽绑定设置了一个在该插槽上没有指代对象的字段)

写在 .aggrega-config.yaml 中的 function: 不会到达上面那条语句:工作区配置的 schema 在 provider 绑定上没有声明这样的键,因此该文件会先被拒绝,归于 E0224,补救办法相同——删除该键:

workspaceconfig: <file>: plugins.providers[<index>].function: against /$defs/FixedEntryPluginRef: unexpected property: “function”: workspace configuration is invalid(workspaceconfig:plugins.providers 条目的 function:对照 /$defs/FixedEntryPluginRef:意外的属性 “function”:工作区配置无效)

修复方法: 修改位于 .aggrega-config.yaml 中,每条消息都指出了确切的修改。在 governance、linter 或 importer 挂接上,将 capability: 替换为你想挂接的插件的 uri:。在 provider 绑定上,删除所指出的键——如果它是 with:,则将该配置移到通过该 provider 渲染的 Recipe 中,那才是读取它的位置。

A capability is bound to more than one provider plugin(一个能力绑定到了多个 provider 插件)

一个能力代表将 workload 转换为制品的一种方式,在已解析的工作区中恰好由一个插件提供。同一能力有两个绑定时,就无法回答由哪一个渲染;而工作区配置由多个层组装而成——共享文件、工作区文件,以及每个文件可提供的追加配套文件——因此第二个绑定往往来自一个其作者看不到第一个绑定的层。

拒绝正是让这一点变得可见的方式。如果悄悄让其中一个绑定胜出,渲染输出就会取决于碰巧最后读取的是哪一层。

发出的消息,指出能力和规则:

workspaceconfig: capability "<capability>" is bound to more than one provider plugin; keep exactly one plugins.providers entry per capability: capability is bound to more than one provider plugin(该 capability 绑定到了多个 provider 插件;每个 capability 只保留一个 plugins.providers 条目:capability 绑定到了多个 provider 插件)

修复方法: 为消息所指的能力保留一个 plugins.providers 条目,删除另一个。如果两者来自不同的配置层,应修改你控制的那一层——删除自己的条目即采用共享层提供的条目,而保留自己的条目则意味着必须删除共享层的条目。确实都服务于该工作区的两个插件提供的是两个不同的能力,因此如果两者都需要,应为每个插件指定各自的能力,而不是将一个能力绑定两次。

An importer is attached by more than one plugins.importer entry(一个导入器被多个 plugins.importer 条目附加)

plugins.importer 条目挂接其 uri 所指的 importer:当该 importer 声明了某次导入所需的格式时,该条目决定运行它的哪个版本,并将条目的 with.sources 和 with.settings 交给它。一个条目对应一个 importer,因此指向同一 importer 的第二个条目——相同身份,无论版本相同与否——不会被任何东西读取,其 with 也会在毫无提示的情况下到达不了任何 importer。因此配置会在加载时被拒绝,无论是哪个命令读取它。

工作区配置由多个文件组装而成——全局文件、从项目根目录到命令运行目录的每个 .aggrega-config.yaml、每个文件可附带的 importer_append 配套文件,以及流水线的 .aggrega-config-append-ci.yaml——因此第二个条目往往写在与第一个不同的文件中。消息会指出该 importer 和两个条目,先列出较早的一个,每个条目都给出其所在的键和位置、所在文件,以及其在该处所写的 uri。

只检查 importer 列表:governance 和 linter 列表接受同一插件被多次挂接,每次挂接携带各自的 with。uri 为文件系统路径的条目不指向任何 importer,因此不参与比较。

发出的消息:

importer "<identity>" is attached by <key>[<position>] in <file> (uri "<uri>") and again by <key>[<position>] in <file> (uri "<uri>"); keep exactly one plugins.importer entry per importer, its uri naming the version you want: importer is attached by more than one plugins.importer entry(该导入器由一个文件中的某个条目附加,又由另一个条目再次附加;每个导入器只保留一个 plugins.importer 条目,并让其 uri 指明你需要的版本:导入器被多个 plugins.importer 条目附加)

修复方法: 为消息所指的 importer 保留一个条目——其 uri 指向你想要的版本,并携带你想交给该 importer 的 with——删除另一个。如果两者位于不同文件中,应修改你控制的那个文件:删除你的条目即采用另一个文件的条目,而保留你的条目则意味着必须删除另一个文件中的条目。

A provider binding names a capability containing a colon(provider 绑定指定的能力包含冒号)

Recipe 的 capability: 被解读为:最后一个冒号之前是能力名称,之后是版本固定——helm:1.0.0 请求版本为 1.0.0 的能力 helm。plugins.providers 条目按该名称查找,因此绑定指定的能力从不包含冒号,而能力包含冒号的条目是任何 Recipe 都无法到达的。配置不会让它未经读取地留在其中,而是在加载时被拒绝,无论是哪个命令读取它。

只检查 provider 列表。importer 列表的条目形式相同,但其插件通过 uri: 挂接,并以 import:<format> 命名其格式,其中冒号是名称的一部分。绑定的 uri: 仍可以以 :<version> 结尾;这不是本规则读取的部分。

发出的消息,指出能力:

the provider socket binding for capability "<capability>": a Recipe’s capability reference is read as the capability up to its last colon and a version pin after it, so the capability a binding names carries no colon; bind the capability name alone and let each Recipe pin the version it needs: a provider socket binding names a capability containing a colon, which no Recipe can select(该 capability 的 provider 插槽绑定:Recipe 的 capability 引用被解读为最后一个冒号之前的 capability 名称和其后的版本锁定,因此绑定所指定的 capability 不含冒号;请只绑定 capability 名称,由各个 Recipe 锁定各自需要的版本:provider 插槽绑定指定了一个包含冒号的 capability,任何 Recipe 都无法选中它)

修复方法: 在条目中只写能力名称——capability: helm——并在应有的位置固定版本:Recipe 在自己的 capability: 中固定其所需的 provider 版本,而需要选择其插件特定版本的绑定则将版本写在插件身份上,即 uri: provider/helm:1.0.0。

A governance attachment declares no role, or one that is not a known role(治理挂载未声明角色,或声明了未知角色)

治理挂载带有一个角色,而决定该挂载在何处运行、可以做什么的是这个角色,而不是插件自身声明的类型:它是接受还是拒绝构建,以及它读取的是图还是渲染出的工件。挂载按读取到的角色进行分派,因此没有角色或角色无人识别的挂载不会挂接到任何地方,并被悄无声息地跳过。

拒绝正是为了防止这种悄无声息。一个已配置但从未被调用的治理插件,产生的输出与从未经过治理的构建完全相同,而结果中没有任何信息表明你拿到的是哪一种。

发出的消息,两者都会指出该挂载并列出现有的角色。缺少角色时:

workspaceconfig: governance attachment "<uri>" declares no role; set role: to one of <the known roles>: a governance attachment declares no role or an unknown role(workspaceconfig:该 governance 挂载未声明角色;请将 role 设为已知角色之一:governance 挂载未声明角色或声明了未知角色)

角色无法识别时:

workspaceconfig: governance attachment "<uri>" declares unknown role "<role>"; use one of <the known roles>: a governance attachment declares no role or an unknown role(workspaceconfig:该 governance 挂载声明了未知角色;请使用已知角色之一:governance 挂载未声明角色或声明了未知角色)

**修复方法:**在 plugins.governance 下的挂载上,将 role: 设置为消息列出的角色之一。选择哪一个,取决于你希望插件做什么,而不取决于插件本身:接受或拒绝类的角色读取构建并返回裁决,而转换类的角色则是一条明确的指令,允许插件修改它所接收的内容。消息会列出完整的角色集合,因此应使用的拼写就在消息中。

A registry alias matches more than one host(注册表别名匹配多个主机)

可以在工作区配置中为注册表指定一个简短别名,使命令和引用无需写出其主机即可指代它。一个别名只选择一个主机。当某个标记同时匹配两个注册表条目的别名时,就会报告此情况:无法确定指的是哪个主机,而擅自选择一个会悄无声息地将工件发送到作者未指定的注册表,或从中拉取工件。

发出的消息,指出该别名、声明它的条目数量以及对应的主机:

registry alias "<alias>" matches <count> hosts (<hosts>); address the registry by host or remove the duplicate alias: registry alias matches more than one host(该 registry 别名匹配了多个主机;请按主机寻址该 registry,或删除重复的别名:registry 别名匹配了多个主机)

**修复方法:**打开 .aggrega-config.yaml,将该别名只分配给消息列出的其中一个主机,或者按主机指定注册表并从引用中去掉别名。消息会列出持有该别名的每个主机,因此要查看哪些条目就在消息中。如果这些条目来自不同的配置层,请编辑你所拥有的那一层。

The lockfile does not satisfy its schema(lockfile 不符合其 schema)

release 的 lockfile 记录构建解析到的结果:对于它所触及的每个实体、库和插件,记录所选版本以及该版本字节内容的摘要。它在被转换为类型化的锁定项之前,会先被读取并按其 schema 进行检查,因此不符合的文档会被拒绝,并给出其失败处的字段路径,而不是悄无声息地生成残缺的锁定项。

lockfile 由机器写入。它由解析 release 的 pull 生成,并被提交,以便同一构建日后以相同方式解析。因此,schema 校验失败几乎总是由手动编辑、使文档处于半解析状态的合并,或者为该文件的早期形态而写的 lockfile(例如其 entities 不带 kind)导致,而不是有意编写的结果。

缺少 lockfile 是另一种情况,报告方式也不同——lockfile 是必需的,因此在构建查找它的位置会报告其缺失,并提示运行生成它的 pull。

发出的消息,指出该文件、字段路径以及 schema 自身给出的异议:

lockfile: <path>: <field-path>: <the schema's own objection>: lockfile: file failed schema validation(lockfile:文件未通过 schema 校验)

构建以及 aggrega pull --verify 会附加重新写入 lockfile 的命令:

…: lockfile: file failed schema validation; run aggrega pull --release <release> to write it again from the Release(lockfile:文件未通过 schema 校验;请运行该命令,根据 Release 重新写入它)

完全为空的文档会单独报告,因为没有可以指出的字段:

lockfile: <path>: document is empty(lockfile:文档为空)

**修复方法:**不要手动修复 lockfile。为该 release 重新运行 pull,它会根据所执行的解析重写文档,然后提交结果——重新解析才能生成锁定项与 release 实际触及内容一致的文档。如果失败发生在合并之后,通过重新 pull 而不是编辑来解决冲突,才能避免得到一个可以解析却锁定了错误版本的文档。建议先阅读消息中的字段路径:它会告诉你损坏是在某个条目中,还是在文档的整体结构上。

解析目录时

加载完成后,编译器遍历 Manifest 的两个层级(先类型映射,后名称映射),为每个 Component 选出 Recipe,并遍历 Manifests、Components 或 Features 上的所有 extends 链。Release 自身的 extends 链由同一遍历处理,只是提前一步:它在解析 Release 时即被跟随,早于查找该 Release 所指定的 Manifest 或 Aggregate,因此下列情况针对 Release 报告,而不是针对该链本应提供的同级指针报告。

Cyclic extends chain(循环的 extends 链)

一条 extends 指针链绕回到自身。每个声明 extends 的类型——Component、Feature、Manifest 和 Release——都由同一个链遍历处理,因此无论在何处发现循环,报告的措辞都相同。

发出的消息。消息以指出该情况的句子开头,随后是解析起始的实体和拒绝它的规则,然后是闭合该循环的边——即带有出错 extends: 的实体及其声明的引用:

cyclic extends chain (<kind> <name>, rule extends). <entity> extends <reference>, which is already in the chain; remove the extends on <entity>, or point it at an entity outside the chain(extends 链存在循环:该实体所扩展的引用已在链中;请删除该实体上的 extends,或将其指向链外的实体)

最先列出的实体与边中列出的实体通常不同,这正是关键所在:循环会针对其上的每个实体报告,而需要编辑的 extends: 行是边所指出的那一行。请按边去找,而不是按标题。

对于 Manifest,<kind> 显示为 Manifest,每个实体以其 metadata.name 命名,<reference> 是与原文完全一致的 extends: 值——相对路径(如 ./base.yaml),或 Release 旁某个 Manifest 的裸 metadata.name。你使用两种形式中的哪一种,不会改变报告内容:Manifest 链接指的是它解析到的文件,因此两个恰好声明相同 metadata.name 的 Manifest 文件是两个链接,经过两者的链并不构成循环。

Release 的情况相同,而且文件身份这一点在这里更重要,因为它所保护的结构很常见:<kind> 显示为 Release,<reference> 是 extends: 指定的相对路径,Release 链接指的是它解析到的文件。两个以所部署系统而非环境命名的 Release 文件——都是 metadata.name: shared-release,其中一个扩展另一个——是两个链接,经过两者的链并不构成循环。

**无论循环多长,都作为循环报告。**链遍历只对有终点的链应用深度上限,因此跨越实体数超过上限的循环仍在此处报告,而不是作为过深的链报告——解决循环的办法从来不是缩短它。

**修复方法:**打开边所指出的实体,移除其 extends:,或将其指向不在该链上的实体。如果多个层级原本是为了共享内容,将重复内容合并到单个基础实体中,可同时消除循环和重复。

Recipe implements does not match the mapped component type(Recipe 的实现声明与所映射的组件类型不匹配)

Manifest 的映射条目指向一个 Recipe,而该 Recipe 的 spec.implements: 声明与该映射条目的组件类型键不匹配。spec.implements 是一致性锚点,而非分派机制:映射值直接指定 Recipe,此检查确认作者指定的 Recipe 确实声明了他们所映射的类型。

该检查在解析任何 Recipe 之前读取组合后的 Manifest,因此报告的是作者所写的映射条目,而不是其下游症状。

发出的消息:

manifest mapping entry’s recipe spec.implements does not match the mapped component-type / feature-type key (manifest mapping "<component-type>" -> "<recipe-uri>", recipe spec.implements is "<recipe-implements>", expected "<component-type>", or a type "<component-type>" extends)(Manifest 映射条目所指 Recipe 的 spec.implements 与所映射的组件类型或特性类型键不匹配;期望值为该组件类型,或该组件类型所扩展的类型)

每个读取 Release 依赖项的命令都会执行此检查;不同之处在于各命令如何处理结果。aggrega build 和 aggrega pull 会停止,因为两者产出的东西你接下来会使用——渲染产物和 lockfile。aggrega validate 和 aggrega lint 会将该发现与它们找到的其他所有诊断一并报告,然后以非零状态退出:它们的任务是告诉你工作区中所有的问题,因此单个错误不会使报告中断。在编辑器中,该发现作为诊断与其他诊断一起发布,该文档需要报告的其他内容不受影响。注意它出现的位置:编辑器将该发现发布在写有该映射的 Manifest 上,位于它所指明的映射条目的键上,而不是发布在 Aggregate 上——如果 Manifest 的已打开文本中没有写出该条目(例如通过 extends 继承的条目),则发布在 Manifest 的第一行。Release 的其他依赖级发现不指向你工作区中的任何文档,仍然留在 Aggregate 上。运行 aggrega validate 则无论打开哪个文档都会报告它。

映射条目指定了目录中不存在的 Recipe,不属于此情况:检查无从比较,会跳过该条目,无法解析的 Recipe 会在解析 recipe 时报告。

FeatureRecipe 条目遵循相同结构;features.type 映射检查会发出 manifest feature mapping ... featurerecipe spec.implements is ... (expected ...),且特性分支直接按映射键本身匹配,因此不会列出 extends 备选项。

**只要 components.type 键到达另一版本的实例,它也会按实例逐一判定。**不指明实例确切类型的键,会在没有键指明该确切类型、且没有其他键为同一基础类型编写时,通过该类型的基础类型到达该实例——因此不带版本编写的键,或指明另一版本的键,都可能到达它。仅凭条目本身无法判断其 Recipe 是否适用,因此对于该键以这种方式到达的每个组件实例,构建都会再次判定该 Recipe,并以构建编译该实例时所用版本下的实例自身类型代替键的位置:即实例指明的版本,或者对于未指明版本的实例,catalog 中该 Component 的最高版本。若 Recipe 的 spec.implements: 不满足实例的版本——无论是精确匹配、按 caret 范围、因无版本,还是通过实例类型所 extends 的基础类型——都会引发此条件,并在实例的 .spec.components.<instance> 路径处报告,而不是在 Manifest 文件处报告:

manifest mapping entry’s recipe spec.implements does not match the mapped component-type / feature-type key (Manifest, at .spec.components.<instance>, "<instance>", of type "<component-type>", compiled as "<component-type>:<version>", reached through manifest mapping key "<key>", mapped to recipe "<recipe-uri>", whose spec.implements is "<recipe-implements>"). map this type at this version to a recipe that implements it, with a mapping key naming the version(Manifest 映射条目所指 recipe 的 spec.implements 与所映射的组件类型 / 功能类型键不匹配(Manifest,该实例的类型与编译版本,经由该映射键到达,所映射的 recipe 的 spec.implements 不满足它)。请将此版本的此类型映射到实现它的 recipe,并使用指明该版本的映射键)

compiled as 值只会出现在类型未指明版本的实例上;指明了版本的实例会在 of type 中显示其版本。指明实例自身版本的键无需第二次判定,因为对条目的检查已经判定过它;已因其键被拒绝的条目只报告一次(如上所述),而不会针对每个实例再报告一次。aggrega build 和 aggrega pull 会因此中止,aggrega validate --release 会报告它并以非零状态退出。aggrega lint 判定的是 Manifest 的映射条目,而不是它们到达的实例,因此不会报告它。

**修复方法:**更正 Recipe 的 spec.implements: 声明,使其与 Manifest 的组件类型键匹配;或修改 Manifest 条目,使其指向 spec.implements: 与该组件类型键匹配的 Recipe。对于某个键在另一版本到达的实例,请添加一个指明该实例版本的映射键,并将其映射到实现它的 Recipe,或让到达它的键指向这样的 Recipe。

Manifest mapping value is not a shape a recipe reference accepts(Manifest 映射值的形式不是 recipe 引用所接受的形式)

Manifest 映射值以引用语法无法表达的形式指定 Recipe 或 FeatureRecipe。recipe 引用接受裸名称、带版本的名称、带能力限定的名称,或带能力限定且带版本的名称——最多一个 /。超出此范围的值(例如 core/helm/eso-aws-fetcher:1.0.0 这样的组件类型式路径),无论目录中有什么,都不可能指向目录实体。

该形式在组合 Manifest 时、在任何查找之前判定——结论来自统计字符串中的分隔符,因此完全不需要目录。在此处判定正是让诊断准确的原因:该值本意指向的 recipe 往往存在且命名正确,若被告知它缺失,会让你去找错误的东西。每个解析 Release 依赖项的命令都以相同方式报告它,因此不取决于你碰巧运行哪个命令。

发出的消息:

malformed recipe reference in a Manifest mapping value: spec.mappings.components.type.<key> maps to <value>, which carries <n> slash-separated segments; a recipe reference accepts "name", "name:version", "capability/name" or "capability/name:version"; correct the mapping value in the Manifest(Manifest 映射值中的 recipe 引用格式错误:该映射值包含的斜杠分隔段过多;recipe 引用只接受名称、带版本的名称、带能力限定的名称或带能力限定且带版本的名称;请更正 Manifest 中的映射值)

features 部分会针对其自身坐标产生相同的消息,并将其称为 feature recipe 引用。

能力段带有版本固定的值——compose:1.2.3/svc:1.0.0——会以同样的方式被拒绝,且发生在查找任何内容之前,因此不会从 registry 获取任何内容。版本固定应写在 Recipe 声明的 capability 上,在那里它选择由服务该能力的插件的哪个版本来渲染它;引用则以裸能力名指明 Recipe(compose/svc:1.0.0)。

malformed recipe reference in a Manifest mapping value: spec.mappings.components.type.<key> maps to <value>, which carries a version pin in its capability segment <segment>; a pin belongs on the capability the recipe declares, and a recipe reference names the recipe by its bare capability, as "name", "name:version", "capability/name" or "capability/name:version"; correct the mapping value in the Manifest(Manifest 映射值中的 recipe 引用格式错误:该映射键映射到的值在其能力段中带有版本固定;版本固定应写在 recipe 声明的 capability 上,recipe 引用以裸能力名指明 recipe;请更正 Manifest 中的映射值)

**修复方法:**将映射值缩短为语法接受的形式。recipe 由其自身的 metadata.name 标识——可选地加上其 spec.capability 前缀和版本后缀——而不是由它所实现的组件类型路径标识。映射的键是组件类型;映射的值是 recipe。

不要混淆形式正确但指向目录中不存在的 recipe 的值:那是确实缺失的实体,仍按缺失实体报告,并列出 URI 和引用它的映射条目。

Several Recipes implement one Component type(多个 Recipes 实现同一个 Component 类型)

两个或更多 Recipes 在 spec.implements: 下声明了同一个 Component 类型:同一类型有两个精确版本的 Recipes,或者一个无版本的 Recipe 与一个已固定版本的 Recipe 并存。

这种情况本身不会引发停止,也不是构建需要解决的歧义。 Recipe 的选择只依据映射:没有任何环节会读取 spec.implements: 并在候选项中挑选,因此无论有多少 Recipes 实现某个类型,渲染实例的始终是 Manifest 将其映射到的那个。spec.implements: 被用作一致性锚点(确认作者映射的 Recipe 确实声明了映射时所用的类型),以及停止时所建议的固定候选项的来源。它从不参与选择。

你实际遇到的是针对 Manifest 未映射到任何对象的实例的停止,该停止会列出实现该类型的每个 Recipe,以便你固定其中一个,参见下文的“No Recipe is mapped for a component or feature instance(没有为组件或特性实例映射 Recipe)”。无论实现该类型的 Recipe 是一个还是五个,它的报告方式都相同,因此没有单独的歧义条件需要查找。

**修复方法:**添加映射。以类型为键的条目会路由该类型的每个实例;以名称为键的条目路由一个具名实例并且优先读取,因此这也是为某个实例指定不同于其同级实例的 Recipe 的方式。

Divergent Release (extends + aggregate pointer)(分歧的 Release(extends + aggregate 指针))

一个 Release 使用 extends: 继承基础 Release,但同时又声明了自己的 aggregate: 指针。Release 的 JSON Schema 在 schema 校验(第 1 层,即信封检查)阶段通过 allOf 约束拒绝这种形态:存在 extends: 时禁止 aggregate:;不存在 extends: 时,aggregate: 和 manifest: 都是必需的。

它作为普通的信封违规而停止,因此诊断采用该类别的形态(参见 error-translation.md 中的“The document-envelope failure class(文档信封失败类别)”),并且该结果指向此处不允许出现的键:

document envelope validation failed (Release, at <path>); <line>:<column>: spec.aggregate: value matches a shape that is not allowed here. correct the document to match its kind’s schema(文档信封验证失败(Release,位于上述路径及行列):spec.aggregate:值匹配了此处不允许的形态。请修正文档,使其符合其 kind 的 schema)

**修复方法:**从子 Release 中移除 aggregate: 字段。继承有意强制子 Release 部署与其父级相同的开发者意图;如果需要部署不同的 Aggregate,请编写一个不带 extends: 的新 Release。

A feature attached by both the Aggregate and the Release cannot be merged(同时由 Aggregate 和 Release 附加的功能无法合并)

当本地 Manifest extends 一个基础 Manifest 时,两个层级(type: 映射、name: 映射)各自独立合并。在每个层级内,子级键在顶层覆盖父级键,这是浅替换,而不是深度合并。子级中某个键的条目会完全替换父级中该键的条目。

当同一个特性实例名称同时出现在 Aggregate 侧和 Release 侧,且存在冲突的不可合并状态(超出允许的 infra 分层)时,编译器会停止,并将诊断定位到它无法协调的附件上。两个冲突的声明按固定顺序列出:先是 Aggregate 声明的类型,再是 Release 声明的类型,因此无需打开两个文档即可分辨各自的声明。

发出的消息:

feature merge conflict: reconcile the Aggregate and Release declarations for the feature (Aggregate <name>, at .spec.components.<component>.features.<attachment>, "<aggregate-declared-type>", "<release-declared-type>")(功能合并冲突:请协调该功能在 Aggregate 与 Release 中的声明(Aggregate 声明的类型、Release 声明的类型))

连接所携带的附件同样如此。当 Aggregate 的连接条目与 Release 中同一连接的条目都在同一个槽位下写入附件并指定了不同的 Features 时,构建会在组合展平后于 Release 的条目处(即写入第二个类型的位置)停止,并列出两个类型、槽位、连接、插座和组件:

feature merge conflict: reconcile the Aggregate and Release declarations for the feature (Release <release-name>, at .spec.boundaries.<boundary>.components.<component>.uses.<socket>.<alias>, the Aggregate names "<aggregate-declared-type>", the Release names "<release-declared-type>", for the slot "<slot>", on the connection "<alias>", through socket "<socket>", of component "<component>"). Drop the type from the Release’s entry so it sizes the attachment the Aggregate declares, or name the same Feature in both documents.(feature 合并冲突:请协调该 feature 在 Aggregate 与 Release 中的声明(给出该 Release 及其条目路径、Aggregate 与 Release 各自指定的类型,以及所涉及的 slot、连接、socket 和 component)。请从 Release 的条目中删除该类型,使其为 Aggregate 声明的附件确定规格,或在两个文档中指定同一个 Feature。)

**修复方法:**协调这两个声明。同一特性实例在 Aggregate 侧和 Release 侧的声明按支柱组合:Aggregate 提供 values,Release 提供 infra。如果两侧都指定了同一个非支柱字段(例如 type:),其值必须一致;请修正其中一侧以与另一侧一致,或删除多余的声明。

Annotation binding does not resolve against its target Feature(注解绑定无法针对其目标 Feature 解析)

Manifest 注解绑定的 feature: 字段指定了目录未加载的 Feature,或者绑定的 maps.infra / maps.values 列表声明了所指定 Feature 的 spec.schema 实际并不包含的点分路径。任一情况都会使工作区加载停止:该绑定会合成 Feature 附件,把值路由到运行时无法解析的路径中。

一个条件涵盖绑定路由无法解析的三种情形,诊断会指明遇到的是哪一种:

  • 未找到 Feature。 feature: 的值引用了已加载目录中不存在的 Feature URI。
  • Feature schema 无法解析。 所指定的 Feature 已加载,但其 spec.schema: 无法解析为 JSON Schema 2020-12 表示:内容格式错误,或引用了无法追踪的跨文档引用。此变体在其后附带解析失败本身的诊断,因此可以从同一个停止中读到 schema 未能解析的原因。
  • 绑定路径不在目标 schema 中。 绑定的 maps.infra 或 maps.values 条目指定了 Feature 的 spec.schema.<pillar>.<path> 未声明的点分路径。

发出的消息(未找到 Feature 变体):

annotation binding does not resolve against its target Feature (Manifest, at .spec.mappings.features.annotations.<key>, "<key>", routes to Feature "<feature-uri>", which this build’s catalog does not hold; correct or publish the Feature named under "feature")(注解绑定无法针对其目标 Feature 解析(Manifest,该注解键路由到的 Feature 不在本次构建的目录中;请修正或发布 feature 字段下指定的 Feature))

发出的消息(schema 无法解析变体):

annotation binding does not resolve against its target Feature (Manifest, annotation binding routes to Feature "<feature-uri>", whose declared schema does not resolve: <resolution failure>)(注解绑定无法针对其目标 Feature 解析(Manifest,注解绑定路由到的 Feature 所声明的 schema 无法解析,并附上解析失败的原因))

此变体指明 Feature 和解析失败,但既不包含绑定键,也不包含源位置:故障位于 Feature 自身的 spec.schema: 中,绑定只是引用了它。可以在 mappings.features.annotations 中搜索消息所引用的 Feature URI 来找到出问题的绑定。

发出的消息(未找到路径变体):

annotation binding does not resolve against its target Feature (Manifest, at .spec.mappings.features.annotations.<key>, "<key>", routes to Feature "<feature-uri>", at pillar "<pillar>", and path "<path>", which that Feature does not declare a property for under "schema")(注解绑定无法针对其目标 Feature 解析(Manifest,该注解键路由到 Feature 的某个 pillar 和路径,而该 Feature 未在 schema 下为此路径声明属性))

**修复方法:**确认绑定的 feature: URI 存在于目录中,并与 Recipe implements: 中区分大小写的 URI 一致。如果未找到路径变体在 Feature schema 确实声明了的路径上触发,请确认点分路径的拼写(区分大小写)以及支柱名称(infra 还是 values)。

A bound annotation value does not conform to the target Feature’s schema(绑定的注解值不符合目标 Feature 的 schema)

你编写的注解通过某个绑定将一个值路由到目标 Feature 上的某个路径,而该值不满足 Feature 在该路径声明的子 schema,或者 Feature 在那里根本没有声明属性。该条件针对的是值而非绑定,因此它与上面的绑定目标中止是分开的:那一条拒绝的是 Manifest 声明的内容,这一条拒绝的是通过它写入的内容。

在已定位的路径上做完整校验;仅当路径无法定位时才软跳过。 一旦定位到绑定子键的子 schema,就会在该路径上按照完整的 JSON Schema 2020-12 约束集(类型、enum、pattern、数值范围、嵌套对象/数组结构)校验该值——末端的 $ref / allOf / oneOf 会依据 schema 的定义解析并校验,而不是跳过。软跳过规则仅适用于导航:当遍历器在中间段(到达绑定的叶子之前)遇到逃生舱口($ref、patternProperties、oneOf/anyOf/allOf,或带 schema 体的 additionalProperties)时,该路径无法静态解析,因此校验器继续执行而不报错,以免误中止;该绑定仍由运行时负责校验。

发出的消息(值不符合变体):

annotation subkey does not conform to the target Feature’s schema at the routed pillar: annotation subkey <subkey> value <value> does not conform to Feature <feature-uri> spec.schema.<pillar>.<subkey>: <constraint failure>(注解子键在路由到的支柱上不符合目标 Feature 的 schema:该注解子键的值不符合该 Feature 在 spec.schema 中对应支柱与子键处的声明,并附约束失败信息)

发出的消息(未声明子键变体):

annotation subkey does not conform to the target Feature’s schema at the routed pillar: annotation subkey <subkey> is not declared at Feature <feature-uri> spec.schema.<pillar>.<subkey>(注解子键在路由到的支柱上不符合目标 Feature 的 schema:该注解子键未在该 Feature 的 spec.schema 中对应支柱与子键处声明)

该中止针对所写的注解触发,发生在注解展开为 Feature 附件之前,因此诊断信息会指明编写该值时所在的文档和作用域(对 Release 侧注解是边界和组件,对 Aggregate 侧注解是组件路径)以及它所来自的注解键。

**由治理插件注入的注解也以同样方式判定,并且诊断信息会说明是谁写入的。**附加用于注入注解的插件会在 Release 组件上设置其值,因此该值的检查方式与运维人员在那里写入的值完全相同——但诊断信息指向的那一行 Release 并不是任何人写的。因此诊断信息会补充说明是哪个插件注入了该值以及它所附加的治理角色,而修复应在该插件的决策中进行,而不是在 Release 中。

修复方法: 修正绑定的值以满足声明的子 schema;如果该值合理,则放宽该属性的 schema。未声明子键变体通常会被上面的绑定目标中止提前拦截;若遇到它,说明绑定声明了该路径而 Feature 的 schema 没有包含它,因此修正两者中错误的一方。当中间的组合运算符导致路径无法解析、而运行时随后拒绝了它时,请收窄 schema,使该属性直接出现在绑定的路径上。

An annotation subkey is not routed by its binding(注解子键未被其绑定路由)

你编写的注解在某个 Manifest 注解绑定所声明的键下带有子键,而其中一个子键的名称不在该绑定的路由范围内:它既未列在 maps.infra 下,也未列在 maps.values 下。每个子键都单独路由到绑定为其声明的 Feature 路径,因此绑定未指明的子键无处可去。若在缺少它的情况下展开注解,你写的某个值就会被悄无声息地排除在构建之外,而通常的原因是子键拼写错误——因此构建会中止,并指明该子键、它所在的注解键,以及该绑定确实路由的每个子键。

该中止针对所写的注解触发,发生在注解展开为 Feature 附件之前,与它旁边的两个条件一样:上文的“A bound annotation value does not conform to the target Feature’s schema(绑定的注解值不符合目标 Feature 的 schema)”在 Feature 拒绝其值时拒绝绑定所路由的子键,下文的“An annotation routes through a pillar its authoring side may not use(注解经由其编写方不得使用的支柱路由)”则拒绝经由错误支柱路由的子键。没有任何绑定声明的键不属于此条件:没有任何东西路由它,构建会跳过它。

输出的消息,指明文档和编写注解的位置、子键、注解键以及绑定所路由的子键:

annotation subkey is not routed by the annotation’s binding (Release <release-name>, at .spec.boundaries.<boundary>.annotations, "<subkey>", written under annotation "<key>", whose binding routes only "<subkey>, <subkey>")(注解子键未被该注解的绑定路由(Release,该子键写在该注解下,而其绑定只路由所列的子键))

写在 Aggregate 中的注解以同样方式指明,即其在该处被编写的位置——对于写在子系统上的注解,为 (Aggregate <name>, at .spec.subsystems.<subsystem>.annotations, …)。构建按编写它的文档,将 Release 侧注解归于 OPS_ERROR 标签、将 Aggregate 侧注解归于 DEVELOPER_ERROR 标签报告。

**修复方法:**将该子键与消息列出的子键进行比较。如果是拼写错误,请将其更正为绑定所路由的子键。如果该值本应到达 Feature,则绑定必须路由它:在 Manifest 中将该路径添加到绑定的 maps.infra 或 maps.values——须是 Feature 的 schema 所声明的路径——或从注解中删除该子键。

A bare annotation value does not route to exactly one path of its binding(裸注解值未能路由到其绑定中恰好一条路径)

你以裸值形式编写的注解——feature.aggrega.ai/monitoring: "30s",而不是子键映射——没有指明任何子键,因此其中没有任何内容说明它填充哪条 Feature 路径。它会被放到绑定声明的唯一一条路径上,maps.infra 和 maps.values 合并计数。声明了多条路径的绑定会让该值有多个去处,却没有任何依据在其中做出选择,因此构建会中止,而不是任选其一。计数跨越两个列表,因此一条路径通过 infra 路由、另一条通过 values 路由的绑定,无论裸值写在哪个文档中都会拒绝它。

与相邻的几个条件一样,该中止针对按原样编写的注解引发,发生在它被展开为 Feature 附件之前,因此诊断信息会指明该值所在的文档和编写位置。每个你编写的注解只检查一次:写在边界或子系统上的值会在那里被拒绝一次,无论其中的组件是否采用它。构建中每一个这样的值都会被报告,而不仅是第一个。构建会依据编写注解的文档,将 Release 一侧的注解报告在 OPS_ERROR 标签下,将 Aggregate 一侧的注解报告在 DEVELOPER_ERROR 标签下。该条件为 a scalar annotation value does not route to exactly one path of its binding,这正是 aggrega explain 针对其代码打印的内容。

输出的消息,指明注解所在的文档和编写位置、注解键、值,以及绑定所路由的路径:

a scalar annotation value does not route to exactly one path of its binding (Release <release-name>, at .spec.boundaries.<boundary>.annotations, "<key>", carrying the bare value "<value>", whose binding routes "<path>, <path>, <path>")(标量注解值未能路由到其绑定中恰好一条路径:Release 中的该注解携带裸值,而其绑定路由的是所列路径)

空值不会写入任何内容,因此只要两个列表之一恰好包含一条路径,它就会被放置在那里,只有在两个列表都不满足时才会被拒绝。完全没有声明路径的绑定会在加载 Manifest 时被拒绝,因为 Manifest 的 schema 要求声明一条路径,所以构建不会以这种方式到达此条件。

治理插件注入的注解以同样方式判定,并且与相邻的条件一样,其诊断信息会补充是哪个插件注入了该值,以及该插件所挂接的治理角色。

修复方法: 将注解写成映射,为每个值指明其对应的子键——feature.aggrega.ai/monitoring: {interval: 30s}——使每个值按自己的名称路由;或者在另一个注解键下为这个单一值提供一个独立的绑定,只声明它所填充的那条路径。

An annotation routes through a pillar its authoring side may not use(注解经由其编写侧不得使用的支柱进行路由)

注解按编写侧划分,这一划分与管理其他所有编写支柱的划分相同:Aggregate 侧注解只能经由目标为 values 的绑定路径路由,Release 侧注解只能经由目标为 infra 的路径路由。其他任何组合都会中止。

正是这一划分阻止了注解捷径成为编写另一侧支柱的途径。开发者的注解贡献 values;运维人员的注解贡献 infra 规格。在两个支柱中都声明路径的绑定本身并不是错误——每一侧只路由其被允许的子集,另一侧的路径从这一侧根本无法到达。

最常触发此中止的情形,是一个绑定在两个支柱列表中都声明了同一路径。路由的决胜规则会让这样的路径经由 infra,使其从 Aggregate 侧无法到达,于是路由到它的 Aggregate 侧注解在此中止。在构建到达此中止之前指出这种绑定形态的提示,见 warnings.md。

发出的消息:

annotation routes through a pillar its authoring side may not use: annotation <key> at <source> routes through pillar <pillar> at path <path>, but <side>-side annotations may only route through pillar <permitted-pillar>(注解经由其编写方不得使用的支柱路由:位于给定来源的该注解在给定路径上经由某一支柱路由,但该编写方的注解只能经由其被允许的支柱路由)

治理插件注入的注解位于 Release 组件上,因此它是 Release 侧注解,同样的划分也适用于它。其诊断信息会补充说明是哪个插件注入了它以及它所附加的治理角色,因为它所指向的 Release 键并不是任何人写的。

修复方法: 从绑定目标支柱所属的一侧路由该注解,或者在其自己的注解键下添加一个绑定,使其路径指向该编写侧被允许的支柱。若一个绑定在两个支柱列表中声明了同一路径,请将其拆分为两个绑定,使每一侧都有可到达的路径。若诊断信息指明了注入插件,则该注解来自该插件的决策:请更正该插件,或更正它注入时所依据的绑定。

Authored values or infra do not conform to the declared schema(编写的 values 或 infra 不符合声明的 schema)

某个组件实例(或某个附加的 Feature)解析后的 values: 或 infra: 不符合声明的目录 schema。构建在渲染前会按各支柱声明的 schema 校验它们,因此拼错的键、类型错误的值、超出范围的数字或缺失的必填字段会在源头被捕获,而不会在部署时产生损坏的清单。

该检查覆盖标准的 schema 约束:类型错误的值(schema 声明为整数处给了字符串)、超出声明范围或 enum 的值、不满足声明的 pattern 的值、不是其声明的 format(命名格式之一)有效实例的字符串,以及未提供的必填字段。格式失败会指出关键字,并附带该值、格式及其问题——例如 aggrega pull 和 aggrega validate --release 对给定 :::: 的 uri 字段打印的 "format", "value \"::::\" is not a valid uri: a URI begins with a scheme followed by a colon, such as https:"。该检查感知默认值:schema 为其提供了 default: 的字段即使省略也视为已提供,因此带默认值的必填字段永远不会触发“缺失”检查。

values 支柱是开发者的编写面。它以封闭方式校验——schema 未声明的属性会被视为可能的拼写错误而被拒绝。在自身文档内组合的 values schema(本地 #/$defs $ref 或 allOf)会在该定义上下文中解析并校验。

infra 支柱是运维人员的规格面,仅当 Component 声明了 schema.infra 支柱时才会检查——该声明就是组件选择加入的契约。它仅依据该声明以封闭方式校验,与 values 支柱依据 schema.values 校验完全相同:Component 未声明的键会被视为拼写错误而被拒绝,已声明的键则强制检查其类型和范围。希望 replicas 这类由 provider 分层的键被校验的组件,应在自己的 schema.infra 中声明该键;provider 接受的词汇通过其 Recipe 的 valuesMapping 来达成,而不是叠加到编写的 infra 面上。

该检查会衡量 Release 放置的每个组件的规格,完全没有写 infra: 块的条目也会被衡量:缺失的块即为空块,因此没有 default: 的 required: 键会被报告为缺失——这正是此类键存在的目的。两种放置组件的方式都算数。在边界的 components 下指名它会放置它,在 aggregates 下路由贡献它的子模块也会放置它;路由条目放置组件时不会对其中任何一个做出说明,因此以这种方式放置的组件从空的规格块开始,其类型上没有默认值的 required: 键会被报告为缺失。Release 未通过任一途径放置的组件则完全不会依据此契约衡量。它存在另一种错误,构建会改为报告那一个:某个组件未被放置在任何边界中,并指出放置它的两种方式。

无论组件在何处编写,该契约都对其生效:子模块贡献的组件与 Release 自身的 Aggregate 声明的组件按完全相同的方式衡量。组件嵌套多深,不会改变其类型的哪些约束适用。

Feature 附件以同样的方式校验,依据所附加 Feature 声明的 schema.values / schema.infra。附件共用同一个界面,因此凭据类 Feature(即标记为 feature.aggrega.ai/kind: secret 的 Feature)与其他任何附件一样,依据其自身声明的 schema 进行衡量。被检查的值是附件值跨作用域(组件、子系统、边界以及组件特定作用域)级联之后的有效合并结果,因此一个在某个作用域合法引入、但在更具体的作用域被覆盖为非法值的值,会在合并结果上而非片段上被捕获。类型未声明 schema 的附件不做校验;附件的 infra 依据附件自身的 schema.infra 校验(附件是一层覆盖,不携带 provider 联合)。

附件的检查结果在写入失败 pillar 的文档中报告,使用该文档的名称,并归到其作者名下。其 values 在写入它们的 Aggregate 块处报告——即组件自身的 features: 条目 .spec.components.<component>.features.<attachment>.values.<field>,优先于作用到该组件的子系统块——作为开发者错误。其 infra 在写入它的 Release 块处报告——即 Release 中该组件的条目,位于命名该组件的边界之下,优先于边界自身的 features: 块——作为运维者错误。拥有某个 pillar 的文档未写入该 pillar 时,在附件本身被写入的位置报告,也就是其 type 被命名之处。因此,一个仅由 Release 创建、不携带 values 的附件,若其 Feature 的 values 要求某个字段,会在 Release 的条目处作为运维者错误报告,路径位于 Release 持有的位置——组件的条目,或者对于边界为其下每个组件创建的附件,则是边界的 features: 块:

[OPS_ERROR E0168] .spec.boundaries.main.components.app.features.check.values.schema
authored pillar does not conform to its declared schema (Release probe, at .spec.boundaries.main.components.app.features.check.values.schema, values pillar does not conform to the Feature schema: missing required property: schema (required))

同一附件若写在 Aggregate 中的组件上,则在 .spec.components.app.features.check.values.schema 处报告 [DEVELOPER_ERROR E0168],使用该 Aggregate 的名称。编辑器会在写入它的文档上、在该文档所持有的该路径最深的键上显示每一条。

连接所携带的附件以同样方式衡量,并在写入失败 pillar 的文档的连接条目处报告,而不是在组件自身的 features: 块处报告,因为该块并不持有它。其 values 在 Aggregate 的连接条目 .spec.components.<component>.uses.<socket>.<alias>.features.<slot>.values.<field> 处报告——对于子模块贡献的组件,位于该子模块自身的文档中——其 infra 则在 Release 中该连接的条目处报告;若 Release 命名了边界,则位于命名该组件的边界之下。仅由 Release 创建的附件,两个 pillar 都在 Release 的条目处报告:这种附件不携带 values,因此若 Feature 的 values 要求某个字段,会在该处、即运维者写入的条目处报告其缺失。

每条边的连接配置以同样方式依据 socket 的每边契约校验:边上由开发者编写的 values 依据 socket 的 valueSchema,边上由运维者编写的 infra(来自 Release)依据 socket 的 infraSchema。若 socket 未为某个 pillar 声明每边 schema,则该 pillar 不接受任何需校验的配置(省略 = 无契约,无需检查)。诊断信息按消费者、socket 和别名指明该边。对于 Release 自身的 Aggregate 声明的组件,Release 为其某个连接写入的每个条目都会衡量运维者的 infra——包括不携带 infra 的条目,没有默认值的 required: 键正是由此被报告为缺失——并在 Release 中的该条目处报告;若 Release 命名了边界,则位于命名该组件的边界之下,这也是运维者编辑它的位置;开发者的 values 在 Aggregate 中的连接条目处报告。

声明了 sensitive: true 的叶子节点,其约束失败信息会被隐去。 失败文本会引用出错的值,而构建诊断信息任何关注构建的人都能读到,因此在声明为敏感的叶子节点上——或声明为敏感的对象内部的任何位置——下方的 <constraint failure> 会显示为 <redacted>。在其下方包含声明为敏感的叶子节点的位置也是如此,包括 pillar 本身:与其他关键字并列编写的 $ref 会在其编写位置作为整体检查,因此其所指定义内部的失败会在该位置报告,否则就会引用该叶子节点的值。实体、字段路径、pillar 和契约名称仍会全部列出,因此诊断信息仍能告诉你失败发生在哪里;只有会重现该值的文本被去掉。敏感性按 pillar 读取,因此在 values 和 infra 中同名的叶子节点,只在声明它的 pillar 中被隐去。

发出的消息:

authored pillar does not conform to its declared schema (Aggregate <name>, at .spec.components.<component>.values.<field>, “values.<field>”, “<keyword>”, “<constraint failure>”)(编写的支柱不符合其声明的 schema) authored pillar does not conform to its declared schema (Release <release-name>, at .spec.components.<component>.infra.<field>, “infra.<field>”, “<keyword>”, “<constraint failure>”)(编写的支柱不符合其声明的 schema) authored pillar does not conform to its declared schema (Aggregate <name>, at .spec.components.<component>.features.<attachment>.values.<field>, values pillar does not conform to the Feature schema: <constraint failure>)(编写的支柱不符合其声明的 schema:values 支柱不符合该 Feature 的 schema) authored pillar does not conform to its declared schema (Release <release-name>, at .spec.boundaries.<boundary>.components.<component>.features.<attachment>.infra.<field>, infra pillar does not conform to the Feature schema: <constraint failure>)(编写的支柱不符合其声明的 schema:infra 支柱不符合该 Feature 的 schema) authored pillar does not conform to its declared schema (Release <release-name>, at .spec.boundaries.<boundary>.features.<attachment>.values.<field>, values pillar does not conform to the Feature schema: <constraint failure>)(编写的支柱不符合其声明的 schema:values 支柱不符合该 Feature 的 schema) authored pillar does not conform to its declared schema (Aggregate <name>, at .spec.components.<component>.uses.<socket>.<alias>.values.<field>, “values.<field>”, “<keyword>”, “<constraint failure>”)(编写的支柱不符合其声明的 schema) authored pillar does not conform to its declared schema (Aggregate <name>, at .spec.components.<component>.uses.<socket>.<alias>.features.<slot>.values.<field>, values pillar does not conform to the Feature schema: <constraint failure>)(编写的支柱不符合其声明的 schema:values 支柱不符合该 Feature 的 schema) authored pillar does not conform to its declared schema (Release <release-name>, at .spec.components.<component>.uses.<socket>.<alias>.features.<slot>.values.<field>, values pillar does not conform to the Feature schema: <constraint failure>)(编写的支柱不符合其声明的 schema:values 支柱不符合该 Feature 的 schema) authored pillar does not conform to its declared schema (Release <release-name>, at .spec.boundaries.<boundary>.components.<component>.uses.<socket>.<alias>.infra.<field>, “infra.<field>”, “<keyword>”, “<constraint failure>”)(编写的支柱不符合其声明的 schema)

**修复方法:**修正出错的值以满足声明的 schema;或者,如果该值是合理的,放宽声明它的 schema(Component 的 schema.values/schema.infra,或所附加 Feature 的 schema)以容纳它。使用 aggrega inspect <component-type> 查看 Component 声明的 schema,了解每个 pillar 期望的确切类型、范围、默认值和必填字段。

A declared schema contract cannot be read as a schema(声明的 schema 契约无法作为 schema 读取)

某个 Component 或 Feature 声明的 schema 契约无法产生任何可供校验的内容,因此它所覆盖的配置实际上没有经过任何校验。有三种契约可能出现此错误,各自在自己的字段中编写:实体自身的 spec.schema,以及依赖 socket 声明的两个逐边契约——用于连接开发者一侧的 valueSchema 和用于运维者一侧的 infraSchema。这些契约可以引用的 SchemaLibrary 条目也可能出现下文所列的第三种错误;该情况如何报告见下文。

有三种错误会导致此中止,其中两种很容易被忽略,因为契约看起来没有问题。 socket 契约可能根本无法编译为 JSON Schema 2020-12——最常见的原因是关键字拼写错误;实体自身的 spec.schema 若无法编译,则改为按其编译所遇到的紧凑形式条件报告(未知关键字为 E0120,其类型不接受的约束为 E0116)。也可能编译顺利却仍无法构建出校验器:其内容可以按紧凑形式读取,但并不是任何东西都能据以校验的 schema,例如在应为属性 schema 的位置写了一个裸标量(items: nonsense)。还可能在其他各方面都格式正确,却指定了一个不在支持集合内的格式——format: password,或 format: emial 这样的拼写错误——无论是否有值到达该字段,这都会被拒绝,而不是被当作一个什么都不检查的约束来读取;format 可取的名称列在 Named formats 中。这三种属于同一种情况,因为修复方法相同,放过其中任何一种的后果也相同。

未声明契约与声明了无法读取的契约是两种不同的情况,构建对它们的处理也不同。 什么都不声明的字段会被跳过:逐 pillar 和逐边的一致性校验是可选启用的,因此一个对两个 pillar 都不加约束的 socket 属于正常编写,不会产生诊断。声明了无法读取内容的字段会被拒绝。若放过它,它所覆盖的每个载荷都将不经校验,而构建却报告成功——检查已经停止运行,却没有任何提示说明它已停止。因此正是这种拒绝把两者区分开:没有输出意味着没有需要检查的内容,而中止意味着有需要检查的内容但无法读取。

拒绝信息指出的是声明该契约的实体,而不是编写该配置的文档,因为修正应在那里进行。拿到一个契约无法读取的组件类型的 Aggregate 作者,在自己的文件中没有任何需要修改的内容。该错误在读取目录时出现,此时声明实体、pillar、所编写的字段和源代码行都是已知的——因此无论你是通过构建、通过 aggrega validate,还是通过 aggrega mcp 提供的构建工具遇到它,同一错误的报告都完全相同。实体通过 $import: 读取的契约——它的整个 spec.schema、其中的一个 pillar,或某个 socket 的契约——会在被导入的文件处报告:位置指明该文件以及其中编写该片段的行,而消息仍会指明声明该契约的实体和字段。实体自身的 spec.schema 遇到的紧凑格式中止也以同样方式定位。

指定了不在支持集合内的格式的 SchemaLibrary 条目,会在读取其所属库时导致此中止,拒绝信息会指出该库和该条目,并指向库文件中的该条目。对整个目录运行 aggrega validate 会读取每个库,因此无论是否有 schema 引用该条目,它都会报告该条目;而依赖解析从未到达该库的 Release 不会读取它。其 schema 通过 $ref: 确实到达该条目的 Release 同样会被拒绝,但拒绝信息不会指出该格式:aggrega pull 报告在目录中找不到该库(E0114),aggrega validate --release 报告找不到该引用的目标(E0121)。对目录运行 aggrega validate 即可看到出错的条目和名称。

消息按遇到失败的工具所报告的原样携带失败信息:对于编译失败,包括契约内的键、源代码行和出错的关键字;对于无法构建校验器的内容,包括校验器拒绝的位置;对于不在支持集合内的格式名称,包括字段、关键字 format、所写的名称以及所有支持的名称。socket 契约中的跨文档 $ref: 若其 SchemaLibrary 条目不在已加载的闭包中,在 aggrega validate 检查该实体或 Release 时也会导致同样的中止;在实体自身的 spec.schema 中,它按上文“A $ref: is not written in a form the compiler can resolve(引用未以编译器可解析的形式书写)”所述报告。aggrega pull 会为 Release 所需的库读取这两处,因此无论由两者中的哪一处引用,目录中缺失的库都会更早地使拉取停止,如“A reference names no entity the catalog holds(引用指向目录中不存在的实体)”(E0114)所述——而目录中存在的库,无论被哪一处引用,都会在锁文件中固定。

与无法读取的约束并列的格式正确的约束不会被执行。 契约作为一个整体文档读取,因此单个无法读取的片段会使与其一同声明的所有约束失效。这就是此中止比它所损失的约束更有价值的原因:另一种结果是一个看起来在执行、读起来在执行、实际上什么都不执行的契约。

输出的消息依次指出带版本的实体和声明该契约的字段、该契约约束的 pillar,然后是失败信息——此处为一个带有拼写错误关键字的 socket 契约:

declared schema contract could not be compiled into a usable schema, so nothing was validated against it: correct the contract where it is declared, or remove it if the configuration it covers needs no validation. Component "<type>:<version>": spec.usesSchema.<socket>.valueSchema declares a schema no validator can be built from, so the values it constrains would go unmeasured: compactform at <key>:<line> (keyword "<keyword>"): unknown keyword(声明的 schema 契约无法编译为可用的 schema,因此未据此校验任何内容:请在声明处修正该契约,或在其覆盖的配置无需校验时将其移除。Component:spec.usesSchema 中某个 socket 的 valueSchema 声明了一个无法据以构建校验器的 schema,因此它所约束的值将无法得到衡量:compactform 位于所示的键和行(所示关键字):未知关键字)

以及 Component 的 values pillar 中一个不在支持集合内的格式名称:

declared schema contract could not be compiled into a usable schema, so nothing was validated against it: correct the contract where it is declared, or remove it if the configuration it covers needs no validation. Component "<type>:<version>": spec.schema.values declares a schema no validator can be built from, so the values it constrains would go unmeasured: validator/jsonschema: schema resolution failed (at values.<field>, keyword "format", format "<format>" is not supported; the supported formats are email, uri, hostname, ipv4, ipv6, uuid, date-time, date)(声明的 schema 契约无法编译为可用的 schema,因此未据此校验任何内容:请在声明处修正该契约,或在其覆盖的配置无需校验时将其移除。spec.schema.values 声明的 schema 无法构建校验器,因此其约束的值将不会被校验)

Feature 以 Feature "<name>:<version>" 的形式指出,socket 的契约以其自身字段指出,例如 spec.usesSchema.<socket>.infraSchema,pillar 则以该契约所约束的那个指出——values、infra 或 provides。对实体自身文件运行的 aggrega validate 指出实体时不带版本。SchemaLibrary 条目以其库和条目指出:

declared schema contract could not be compiled into a usable schema, so nothing was validated against it: correct the contract where it is declared, or remove it if the configuration it covers needs no validation. SchemaLibrary "<library>": schema "<entry>" names a format no validator can check, so the values it constrains would go unmeasured: validator/jsonschema: schema resolution failed (at <field>, keyword "format", format "<format>" is not supported; the supported formats are email, uri, hostname, ipv4, ipv6, uuid, date-time, date)(声明的 schema 契约无法编译为可用的 schema,因此未据此校验任何内容:请在声明处修正该契约,或在其覆盖的配置无需校验时将其移除。该 schema 指定了校验器无法检查的格式,因此其约束的值将不会被校验)

修复方法: 打开诊断指出的字段,修正所报告的键和行处的片段——最常见的是关键字拼写错误(请对照 vocabulary/compact-form-authoring.md 中的关键字词汇表检查),或在应为嵌套 schema 的位置写了一个值。若失败信息指出的是不受支持的格式,请改写为某个命名格式或移除 format:;承载机密内容的字段应改为声明 sensitive: true,因为 password 不是一种格式。对于 SchemaLibrary 条目,修正应在诊断指出的库文件中进行。若失败信息指出的是跨文档引用,请确认该 SchemaLibrary 条目存在,且该库可从 Release 的依赖闭包中到达。如果该字段覆盖的配置确实无需校验,请移除该字段,而不要留下一个无法读取的契约。

Recipe source: is an empty string(Recipe 的 source 字段为空字符串)

某个 Recipe 声明了 source: "",即一个空字符串。Recipe 的 source: 用于在两种编写模式之间进行选择:sourceless 模式,没有外部制品,输出完全由该 Recipe 的其他输入类型生成;以及 sourced 模式,由 source: 指定一个外部 chart、模块或文件作为渲染来源。省略该字段即选择前者,非空值选择后者,而空字符串两者都不选择,因此它是一种歧义,而不是一个有意义的值。写为 null 的 source: 等同于省略它。

该 Recipe 会被拒绝,而不是由编译器替你在两种解读中选择一种。写出空 source: 最常见的方式是删除了 URI 却留下了键:本意是 sourced 模式,而若把空字符串当作 sourceless 接受,就会交付一个缺少制品的组件,且从不说明采用了哪种解读。

此规则在加载 Recipe 时检查,严格按照你写下的值读取,因此每个加载该 Recipe 的命令都会在任何环节尝试使用该空值之前指出这一条件。对该 Recipe 文件运行的 aggrega validate 会拒绝它;aggrega pull、构建、aggrega validate --release 以及 aggrega mcp 提供的构建工具会针对到达该 Recipe 的 Release 报告它,并排在因此而无法再解析的该 Recipe 引用之前。因此,pull 会指出这一条件,而不是将空引用报告为无法判断其源类型的引用。它在读取是否声明了源的规则之前检查,因此 source: 为空的 Recipe 会被告知 source: 的问题,而不是被告知某个无可叠加内容的 valuesMapping 或缺失的输入类型。

发出的消息定位在写有空 source: 的 Recipe 文件及其中的键 .spec.source,而不是绑定该 Recipe 的某个组件,因为该条目由所有绑定它的组件共享:

recipe source is an empty string, which names neither sourceless mode nor sourced mode (Recipe <name>:<version>, at .spec.source). omit the source field for sourceless mode, or name a non-empty path or URI for sourced mode(recipe 的 source 为空字符串,既未指定 sourceless 模式,也未指定 sourced 模式。若为 sourceless 模式,请省略 source 字段;若为 sourced 模式,请指定非空的路径或 URI)

构建会在带有该条件短代码 E0251 的 CATALOG_ERROR 标签下打印这一行,并在旁边给出该 Recipe 文件。

修复方法: 如果该 Recipe 是 sourceless 的,完全省略 source: 字段(或将其设为 null);如果该 Recipe 是 sourced 的,提供非空的路径 / URI / 结构化来源对象。

No Recipe is mapped for a component or feature instance(没有为组件或特性实例映射 Recipe)

某个实例的类型没有能解析到目录中已有 Recipe 的 Manifest 映射。Recipe 的选择仅基于映射:编译器从不通过读取 spec.implements: 并在候选者中挑选来选定 Recipe,因此无论有多少 Recipes 实现了某个未映射的类型,构建都会停止。implements 为选择提供信息;由作者做出选择;由 Manifest 记录选择。

同一条件也涵盖存在但无处可达的映射:一个具有可接受引用形态的值,指向目录中没有的 Recipe,包括该 Recipe 存在但版本与该值固定的版本不同的情况,以及其裸名称同时由两个能力提供的情况。两者都无法解析到一个可以说是作者所选的 Recipe。形态无法用任何引用表达的映射值会单独报告,见上文“Manifest mapping value is not a shape a recipe reference accepts(Manifest 映射值不是 recipe 引用所接受的形态)”,因此“某实体不存在”的判断只会针对本可以解析的引用作出。

针对组件实例发出的消息。当映射存在但指向不存在的内容时:

no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.<instance>, "<instance>", of type "<type>", mapped to recipe "<uri>"). correct the mapping value in the Manifest, or publish the recipe it names(未能为 component/feature 实例解析出 recipe:请为其类型添加显式的 Manifest 映射(上述 Manifest 位置、实例、类型及所映射的 recipe)。请更正 Manifest 中的映射值,或发布其所指定的 recipe)

当映射不存在而有实现该类型的 Recipes 时,它们会作为可供固定的候选列出:

no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.<instance>, "<instance>", of type "<type>", recipes implementing it "<recipe-uris>"). pin one of them in the Manifest(未能为 component/feature 实例解析出 recipe:请为其类型添加显式的 Manifest 映射(上述 Manifest 位置、实例、类型及实现该类型的 recipe)。请在 Manifest 中固定其中一个)

而当根本没有任何内容实现该类型时,就没有可列出的内容:

no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.<instance>, "<instance>", of type "<type>"). no recipe in the catalog implements this type; write one, then map the type to it(未能为 component/feature 实例解析出 recipe:请为其类型添加显式的 Manifest 映射(上述 Manifest 位置、实例及类型)。catalog 中没有任何 recipe 实现该类型;请编写一个,再将该类型映射到它)

在未指定任何目录文件夹的工作区中,搜索的 Recipes 仅限于 lockfile 固定的那些:registry 中的那些不会被列出,而未为该类型映射任何条目的 Manifest 也不会固定任何条目。在这种情况下,当没有任何已固定的 Recipe 实现该类型时,关于缺失的说法针对的是已固定的内容而非目录,并且消息会明确说明这一点:

no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.<instance>, "<instance>", of type "<type>"). no recipe the lockfile pins implements this type; with no catalog directory, the recipes searched are only those the lockfile pins, not a registry’s; pin one a registry publishes in the Manifest, or write one, then map the type to it(没有为组件/功能实例解析出任何配方:请在 Manifest 中为其类型添加显式映射(Manifest,位于所示位置,针对所示实例和类型)。lockfile 固定的配方中没有任何一个实现此类型;由于没有目录文件夹,搜索的配方仅限于 lockfile 固定的那些,而非 registry 中的;请在 Manifest 中固定一个 registry 发布的配方,或者编写一个,然后将该类型映射到它)

Aggregate 中未写版本的类型,会获得实现构建编译它时所用版本的 Recipes,即目录中该 Component 的最高版本。对于 core/datastore/postgres 的一个实例,若目录中该 Component 的版本为 1.0.0,则会获得所有声明 spec.implements: core/datastore/postgres:1.0.0 的 Recipe,以及任何声明未带版本的该类型或声明接受 1.0.0 的 caret 范围的 Recipe。对于目录中没有对应 Component 的类型,只会获得声明该未带版本类型本身的 Recipes。

功能实例以自己的形式报告这些情况,每种情况都位于该条件的句子之后。Aggregate 中未写版本的功能类型会像组件类型一样,按构建编译它时所用的版本进行匹配——即目录中该 Feature 的最高版本——而指明 <type>:<version> 的消息指的是该版本的类型,也就是在目录中搜索的对象。当某个附加项的组件所映射到的 Recipe 已知时,FeatureRecipes 按该 Recipe 所绑定的能力加以区分:绑定到该组件能力的会优先提供,而绑定到其他能力的 FeatureRecipe 仍会渲染,作为组件输出旁边的独立输出,而不是渲染到组件输出之中;因此,当没有任何一个绑定到该组件的能力时,就改为提供那些。指向空处的映射显示为 feature "<instance>" (type "<type>"): the Manifest maps it to feature recipe "<uri>", which is not in the catalog。当有 FeatureRecipes 为该组件的能力实现该类型时,只列出这些:feature "<instance>" (type "<type>"); feature recipes implementing it for capability "<capability>", the capability its component's Recipe binds to: [<recipe-uris>]; pin one in the Manifest。当它们只为其他能力实现该类型时:feature "<instance>" (type "<type>"); no feature recipe in the catalog implements <type>:<version> for capability "<capability>", the capability its component's Recipe binds to; feature recipes implementing it for other capabilities: [<recipe-uris>]; pin one of those in the Manifest, and it renders as its own output beside the component's, or write one for "<capability>", then map the type to it。当根本没有任何一个实现该类型时:feature "<instance>" (type "<type>"); no feature recipe in the catalog implements <type>:<version>; write one, then map the type to it。而当能力未知时——组件自身的映射未解析到任何 Recipe(这一点会单独报告),或者附加项写在某个边界上,而该边界中的组件可能通过多种能力渲染——则列出每个实现者:feature "<instance>" (type "<type>"); feature recipes implementing it: [<recipe-uris>]; pin one in the Manifest。在未指定任何目录文件夹的工作区中,搜索的 FeatureRecipes 仅限于 lockfile 固定的那些:registry 中的那些不会被列出,而未为该类型映射任何条目的 Manifest 也不会固定任何条目。在这种情况下,关于缺失的说法针对的是已固定的内容而非目录,并且消息会明确说明这一点。当没有任何一个实现该类型时:feature "<instance>" (type "<type>"); no feature recipe the lockfile pins implements <type>:<version> for capability "<capability>", the capability its component's Recipe binds to; with no catalog directory, the feature recipes searched are only those the lockfile pins, not a registry's; pin one a registry publishes in the Manifest, where one for another capability renders as its own output beside the component's, or write one for "<capability>", then map the type to it——而当能力未知时,消息不指明任何能力,并以 pin one a registry publishes in the Manifest, or write one, then map the type to it 结尾。当已固定的 FeatureRecipes 只为其他能力实现该类型时,该情况的消息会以 no feature recipe the lockfile pins implements 代替 no feature recipe in the catalog implements,能力之后的从句相同。

修复方法: 在 Manifest 的 spec.mappings.components.type 下添加消息要求的映射,以组件类型为键、以 Recipe 为值。当消息列出候选时,从中选择一个:该列表正是声明在构建所解析的版本上实现该类型的那些 Recipes。当消息指出某个 Recipe 不在目录中时,要么更正该值,要么将该 Recipe 添加到构建读取的目录中;值中的版本必须与目录中已有的版本匹配。当没有任何内容实现该类型时,缺少的就是 Recipe 本身。当消息说明搜索的配方或功能配方仅限于 lockfile 固定的那些时,说明工作区未读取任何目录文件夹,因此 registry 仍可能发布实现该类型的 Recipe 或 FeatureRecipe:在 Manifest 中将该类型映射到它,才会让 pull 获取并固定它。

A Manifest name mapping names nothing in the build(Manifest 的 name 映射未指向构建中的任何内容)

spec.mappings.components.name 或 spec.mappings.features.name 下的某个键未指向构建中存在的任何组件实例或任何附件。name 层按被实现对象的确切名称匹配:components.name 键与 Aggregate 中所写的组件实例名称匹配,features.name 键与附件自身的名称匹配——即它在组件的 features: 中所写的键,或者对于写在连接上的附件为 <alias>.<slot>——绝不与附件所在组件的名称匹配。一个不指向任何内容的键永远不会被查阅:它原本针对的每个实例都会通过 type 层解析,构建会顺利完成,对被忽略的条目只字不提。因此构建会在渲染任何内容之前中止。

消息会指出 Manifest、该键及其所在的节、构建中确实存在的该类名称——在条目的 Recipe 或 FeatureRecipe 所实现的类型已知且构建中存在该类型时,范围缩小到该类型——并在能够判断时指出你可能想写的名称:对于写成组件名称的 features.name 键,给出该组件所携带的该类型的附件;对于写成附件名称的 components.name 键,给出携带该附件的组件;其他情况下给出只差一次编辑的名称。

输出的消息,针对写成附件所在组件名称的 features.name 键:

a Manifest name mapping’s key names no component instance or attachment in this build, so the entry binds nothing: Manifest "<manifest>", key "<component>" under mappings.features.name: no attachment in this build is named "<component>"; a features.name key names an attachment by its own name — the key it is written under in a component’s features, or <alias>.<slot> for one written on a connection — never the component it is attached to; attachments of type "<feature-type>" in this build: "<attachments>"; "<component>" is a component, and a features.name key names the attachment rather than the component it is attached to — did you mean "<attachment>"?(Manifest 的 name 映射的键未指向此构建中的任何组件实例或附件,因此该条目不绑定任何内容:Manifest 的 mappings.features.name 下的该键:此构建中没有以此命名的附件;features.name 键按附件自身的名称指向附件——即它在组件的 features 中所写的键,或对写在连接上的附件为别名加槽位——绝不指向它所附加的组件;此构建中该类型的附件如上所列;该名称是一个组件,而 features.name 键指向的是附件,而不是它所附加的组件——你想写的是否是所示附件?)

以及针对与某个实例名称只差一次编辑的 components.name 键:

a Manifest name mapping’s key names no component instance or attachment in this build, so the entry binds nothing: Manifest "<manifest>", key "<key>" under mappings.components.name: no component instance in this build is named "<key>"; a components.name key names a component instance exactly as the Aggregate writes it; component instances of type "<component-type>" in this build: "<instances>"; did you mean "<instance>"?(Manifest 的 name 映射的键未指向此构建中的任何组件实例或附件,因此该条目不绑定任何内容:Manifest 的 mappings.components.name 下的该键:此构建中没有以此命名的组件实例;components.name 键按 Aggregate 中所写的名称原样指向组件实例;此构建中该类型的组件实例如上所列;你想写的是否是所示实例?)

每个不指向任何内容的键都会在一次构建中报告,顺序与 Manifest 中的书写顺序一致。

**如何修复:**将该键重命名为消息建议的名称,或其列出的名称之一——对于附件,应使用它所写在其下的名称,而不是其组件的名称。如果不再需要该条目,就将其删除;该类型的实例随后会通过 type 层解析。

A Manifest maps two version-distinct keys onto one type(某个 Manifest 将两个版本不同的键映射到同一类型)

一次类型查找匹配到了不止一个 Manifest 映射键。类型键以容忍版本的方式匹配,因此分别作为映射键写出的 core/api-server、core/api-server:1.0.0 和 core/api-server:2.0.0 都对应同一个基础类型;而命中其中两个的查找就有两个 Recipes 可选,且没有优先选择其一的规则。

构建会停止,而不是解析碰巧先读到的那个键。选择其一会使渲染输出取决于遍历映射的顺序,而这正是字节一致的输出所排除的。

发出的消息:

manifest maps multiple version-distinct keys to the same base type; the type-to-recipe lookup is ambiguous: type "<type>" matches version-distinct keys [<keys>] — pin the authored type’s version or remove the duplicate mapping keys(manifest 将多个版本不同的键映射到同一基础类型;类型到 recipe 的查找存在歧义:该类型匹配了上述多个版本不同的键——请固定所编写类型的版本,或删除重复的映射键)

修复方法: 有两个方向,消息都会指出。删除重复的映射键,保留应当对应该类型的那个:当多余的键是版本升级遗留下来的时,这样做是对的。或者在编写侧固定版本,使组件声明的类型指向你想要的确切键:当多个键是有意为之、不同组件确实需要不同的 Recipes 时,这样做是对的。

Two catalog entities in one directory share an identity(同一目录中的两个编目实体共享同一标识)

从同一个编目目录加载的两个同类实体带有相同的标识。标识是引用所指向的对象,因此两个文件声明同一个标识,会让指向它的每个引用都有两个答案。

在同一目录内会停止;跨目录则不会。 同一标识出现在两个不同的编目目录中时,按先到先得的遮蔽方式解析——先列出的目录胜出——正是这一点让本地目录可以有意覆盖已发布的实体。只有发生在同一目录内部的冲突才是编写错误,没有任何解读能让它成为有意为之。

该规则对每种被索引的类型都相同:Component、Feature、Recipe、FeatureRecipe、Plugin、SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary 和 Aggregate。该停止定位在第二个文件上,并指出发生冲突的类型和标识。

发出的消息:

duplicate entity identity within a single catalog directory (Component identity "<identity>")(单个目录目录内实体身份重复)

其中 Component 会替换为该类型自己的词——recipe identity、feature recipe identity、Plugin identity、SchemaLibrary identity 等。

修复方法: 重命名两个实体之一,或将其移到单独的目录中。对于 Recipe 或 FeatureRecipe,标识包含 provider 作用域和版本,因此仅版本不同的两个文件不会冲突——此处出现真正的冲突意味着同一版本被发布了两次。最常见的原因是复制一个实体文件来新建实体,却忘了修改 metadata.name。

有两个位置是整体读取而非逐个文件读取的:编目目录,按名称查找可能从其下的任一文档得到答案;以及存放 Release 的目录,按标识引用其 Aggregates 和 Manifests 的 Release 会针对该目录解析。这些文件中的符号链接可以指向机器上的任何位置,因此每个这样的目录都有一个其读取必须留在其内的目录,指向其外的链接不会被读取。工作区边界说明了此处所应用的规则,以及它约束的其他路径。

具体是哪个目录,取决于被读取的目录所在的位置:

  • 工作区,适用于位于工作区内的编目目录或 Release 目录。这也适用于无人指定时工作区按约定使用的 catalog 目录——即仅因其存在而被读取时:此时它属于工作区自身,因此本身是指向工作区之外的链接的 catalog 不会被读取。
  • 你指定的位于工作区之外的目录,适用于其下的内容:你通过 --catalog 传入的编目目录,或工作区配置在 catalog_dirs 下列出的编目目录——无论针对整个工作区还是某个 Release——以及你指定的或配置指定的、位于工作区之外的 Release 目录。目录本身按你指定的方式使用——若它是链接,则在其指向处读取——而其下读取的内容必须留在其内。这也包括你指定后的约定 catalog 目录:在 catalog_dirs 下列出或通过 --catalog 传入时,作为指向工作区之外的链接的 catalog 会在其指向处读取,与你指定的任何其他目录一样。改为指定它所指向的位置(无论以何种写法),或该位置的上级目录,也等同于指定了它:你指定的目录已会读取那里的内容,因此它只会通过该目录读取一次。在配置中指定目录,是工作区读取存放在其外部的实体的方式。

受到判定的是读取会从中获取内容的每个条目:指向以 YAML 文档命名的文件的链接,以及指向目录的链接(目录中可能有自己的文档)。指向读取必须留在其内的目录内部某处的链接,会在遍历遇到它的位置读取。指向任何编目读取都不会获取内容的文件(如说明文件、chart 归档)的链接不在此判定,而不指向任何东西的链接背后没有可读的内容。

编译所依赖的查找会在此类链接处停止,而不是跳过它。 链接背后的实体可能正是某个引用所指向的那个,若悄无声息地跳过它,就会让来自后面编目目录的另一个同名实体顶替其位置被解析。因此 aggrega build、aggrega pull、aggrega validate、读取编目时的 aggrega inspect、对单个 Release 的 lint,以及编辑器和助手对 Release 进行构建、预览、绘图、验证或描述的请求,都会在解析任何内容之前停止,并指出该链接。对整个编目的 lint 也以同样方式停止:其结论覆盖编目目录中的每个文档,因此在其中某个文档无法读取时,它不会报告编目是干净的。只要 Release 按标识引用其 Aggregate 或 Manifest,或某个 Manifest 以这种方式引用它所扩展的 Manifest,Release 的目录也遵循同一规则;即使链接不是引用所指向的那个,扫描也会在 Release 旁的文档中遇到链接时停止,理由与该处出现重复时停止相同:只要其中某个文档无法读取,该目录就无法为一个名称给出答案。操作所指定的 Release——或你单独检查的 Manifest——不属于这些文档:它是在被指定的位置读取的,因此本身是指向外部的链接的 Release 会在其指向处读取,而它所引用的内容会在链接旁、即你指定它所在的目录中查找(A Release or a Manifest named through a link(通过链接指定的 Release 或 Manifest))。

列表则会跳过此类链接,不列出其背后的任何内容。 编辑器的实体索引、其补全以及它提供的候选项,都不会列出指向外部的链接所代表的实体,而实体索引会将工作区内的此类链接列入它未读取的链接中。

**工作区的配置文件同样受工作区约束。**从工作区根目录到命令运行所在目录的每个 .aggrega-config.yaml,以及流水线在其中任何一个旁边保存的 .aggrega-config-append-ci.yaml,都是工作区自身的内容。若其中某个文件是指向工作区之外的链接,或经由指向工作区之外的目录链接才能到达,则不会被读取;由于每个命令、编辑器的语言服务器以及助手的工具都会先读取配置,它们都会在此停止并指出该链接,而不是基于剩余内容拼成的配置继续运行。对于这样的工作区,语言服务器以及通过自身流通信的助手服务器仍会启动:其 Releases 和实体的列表照常应答,在不加任何配置的情况下读取,并在未读取的链接中列出该文件;而由配置决定的其他所有请求都会以此条件被拒绝,并指出该链接。此消息给出的补救方式属于配置本身:全局配置文件是无论存放在何处都会被读取的那一个配置,通过 --config 或 AGGREGA_CONFIG 指定。

Release 的锁文件同样受此约束,读取时与写入时一致。 Release 旁的锁文件会被读取,以供构建、拉取、验证、lint、检查、aggrega cache prune 以及编辑器和助手的请求据其中的固定版本进行解析;它受其写入所受的同一目录约束:工作区,或对于在工作区外指定的 Release,则为该 Release 自己的目录。作为指向外部的链接的锁文件不会被读取,上述各操作都会停止并指出该链接,而不是依据存放在机器其他位置的固定版本进行解析,或在没有固定版本的情况下解析。此消息给出的补救措施针对锁文件本身:它只有一个位置,即 Release 旁、由拉取写入的位置。

**实体旁读取的文件也以同样方式约束。**有两种操作读取的是位于实体自身文档旁边的文件,而不是引用所指的文件。固定(pin)或发布一个实体时,会读取该实体目录中的其他每个 YAML 文档,以判断是否有另一个实体与之共用该目录。加载在目录(catalog)目录中编写的 Plugin 实体时,会读取放在其旁边的已构建 .wasm。每个文件都受限于读取该实体自身文档时所在的目录——工作区、你在工作区外指定的目录目录,或者对于你通过在工作区外指定其文档来固定或发布的实体,则是该文档自身所在的目录——其中指向该目录之外的链接不会被读取。aggrega pin、带或不带 --dry-run 的 aggrega push、会执行固定的 pull,以及编辑器和助手的固定与发布操作都会停止并指出该链接,因为未被读取的文档可能正是造成冲突的实体。加载该插件的 build 或 pull 也会停止并指出该链接,而不是运行保存在机器其他位置的字节,或转而到别处查找该插件。此消息给出的补救措施针对实体旁的文件:把文件本身放在那里。

**工作区的制品缓存也以同样方式约束,读取时与写入时一致。**从 artifact_cache_dir 下的缓存中读取的所有内容——缓存的实体、插件或库及其旁边的 manifest、源归档及其元数据、固定的外部输入、签名包、注册表的本地搜索索引——以及 aggrega cache status、aggrega cache prune 和 aggrega cache clear 列出的每个工作区条目,都受限于写入缓存时所受限的目录:缓存目录本身,默认的 .aggrega/cache 与配置指定的、越出工作区根目录的缓存目录同样如此。其中任何指向缓存目录之外的链接——无论指向工作区内其他位置还是任何别处——都不会被读取;写在工作区根目录内、但自身是指向工作区之外的链接的缓存目录,其后的任何内容也不会被读取:build、pull、validation、search、这三个缓存命令,以及编辑器和助手读取缓存的请求都会停止并指出该链接——缓存以记录的摘要保存的内容也不例外,因为摘要说明的是字节是什么,而不是可以从哪里读取。写在工作区根目录内、指向工作区内其他位置的缓存目录,会在其指向的位置被读取。aggrega inspect 打印的弃用通知不决定任何事,因此不在此列。prune 或 clear 若遇到缓存自身的某个目录是指向缓存目录之外的链接,或缓存目录自身是指向工作区之外的链接,会在列出任何内容之前,将其视为它将要执行的删除,按 “A path the operation writes leads through a link out of the directory it must stay inside(操作写入的路径经由链接通向其必须限定的目录之外)” 处理。此消息给出的补救措施针对缓存:移除链接后,pull 会重新填充缓存;保存在别处的缓存应通过相对于工作区根目录的 artifact_cache_dir 指定,而不是通过链接访问。

**源获取的仓库受限于其自身的检出目录。**当 pull——aggrega pull,或解析 Release 依赖项的 build、编辑器或助手的请求——获取 git-repository 源时,会检出该仓库并归档源所指定的目录,而检出目录是独立的目录:仓库携带的每个链接,包括 module_subdir 本身,都受限于它。指向仓库内文件或目录的链接会以链接的名称归档为其所指向的内容。指向仓库之外的链接——它可能指向运行 pull 的机器上的任何文件——不会被读取:pull 会停止并指出该链接及其指向的位置,且不缓存任何内容。检出目录是 pull 停止后即被删除的临时目录,因此消息按链接在仓库中的位置指出该链接——chart/secret.txt,出现在命令行第一行和句子中——并将其必须限定的目录表述为源所指定的仓库和修订版本:which must stay inside the repository <url> at <ref> (commit <commit>),若源未指定 ref 或直接指定了提交本身,则为 at commit <commit>。链接指向的位置则按它在你机器上的实际位置给出。此消息给出的补救措施针对仓库:链接是在那里提交的,因此要在那里修改——使其指向仓库内部,或替换为文件本身——然后让源指定包含该修改的修订版本。若目录链接指回归档已经通过它读取的目录,pull 也会停止,因为它所代表的树没有尽头;这种拒绝是普通错误,而不是此条件。

目录生成读取的覆盖层也以同样方式约束。aggrega plugin gen-catalog --from-embedded 会读取给定覆盖层目录下的每个覆盖层——通过 --overlay 输入、在编辑器中选择或由助手指定——并将每个覆盖层限定在读取该覆盖层目录时所在的目录内:对于工作区内的覆盖层目录是工作区,对于在工作区外指定的覆盖层目录则是该覆盖层目录本身。覆盖层目录按你指定的方式使用——若它是链接,则在其指向的位置读取。其下若有覆盖层是指向其所受限目录之外的链接,则不会被读取,指向该目录之外的目录链接(其中可能包含自己的覆盖层)也不会被读取:生成会停止并指出该链接,不写入任何内容,而不是在缺少该覆盖层的情况下生成。指向其所受限目录内其他位置的覆盖层链接会在其指向的位置被读取;指向该目录内部的目录链接则不会被进入。此消息给出的补救措施针对覆盖层:把覆盖层本身放在覆盖层目录下,或将包含所有覆盖层的目录指定为覆盖层目录。

**你导入的目录受限于其自身。**给定目录的 aggrega import、助手的导入工具和会话的 aggrega/import 方法,会把该目录中由导入器文件模式选中的文件交给导入器,每个文件都以其在目录中的位置传递,因此无论该目录位于何处——工作区内与工作区外同样如此——这些读取都限定在该目录内。被判定的是导入会从中获取内容的每个条目:指向相关模式所选中文件的链接——即服务于所指定格式的导入器的模式,或在格式被识别时,导入所选择范围内每个导入器的模式,包括编译器的核心导入器——以及指向目录的链接,后者永远不会被进入。指向该目录之外(工作区内其他位置或任何别处)的链接不会被读取:导入会在打开该目录的任何文件之前停止并指出该链接,不写入任何内容。被选中的、指向该目录内其他位置文件的链接会在其指向的位置以链接自身的名称被读取,而指向任何模式都未选中的文件的链接既不判定也不读取。目录本身按你指定的方式使用——若它是链接,则在其指向的位置读取。通过监听器访问时,助手的工具按链接在工作区中的位置指出该链接,且不提及它指向何处。此消息给出的补救措施针对导入的目录:把文件本身而不是指向它的链接放在目录中,或导入链接所指向的目录。

发出的消息。消息以该条件自身的句子开头,接着是读取到达的路径、它必须限定的目录、途中遇到的链接以及该链接指向的位置,然后是补救措施:

此操作读取的文件通过一个链接通向了它必须保持在其内的目录之外(正在读取 <workspace>/catalog-local/component/app/1.0.0/component.yaml,它必须保持在 <workspace> 之内,链接 <workspace>/catalog-local/component/app/1.0.0/component.yaml 通向 <elsewhere>/component.yaml)。未通过该链接读取任何内容。请移除该链接,或使其通向 <workspace> 内的某个位置。要读取保存在外部的内容,请在工作区配置中将存放它的目录列为 catalog 目录,而不是通过其下的链接访问:列出的目录会在其指向的位置读取,即使它本身是一个链接

该诊断不带类别:出错的是磁盘上的布局,而不是你编写的任何文档。

**修复方法:**将链接替换为它所指向内容的副本,或删除该链接;或者,如果该实体本应保留在工作区之外,在工作区配置的 catalog_dirs 下列出存放它的目录,或通过 --catalog 传入,使该目录作为独立的 catalog 目录被读取。要列出的是链接指向的目录,而不是链接所在的目录:无论某个目录是如何被读取的,其下遇到的链接都按同样方式判定,因此列出链接所在的目录不会改变任何结果。如果链接就是工作区按约定使用的 catalog 目录本身,那么在 catalog_dirs 下列出 catalog(或它指向的目录),或通过 --catalog 传入其中任一个即可,因为你指定的目录会按其指向的位置读取。如果链接是某个 Release 的 lockfile,删除它并重新 pull 该 Release,这会在其旁边写入一个新的 lockfile。Manifest 没有 catalog 层级,因此 Release 读取的 Manifest 保存在该 Release 本身旁边。如果链接是配置文件,将其替换为保存在工作区中的副本;要在多个工作区之间共享的配置,可通过 --config 或 AGGREGA_CONFIG 将其指定为全局配置文件来读取,它位于各工作区自身文件之下。如果链接位于正在 pin 或发布的实体旁边,将其替换为文件本身,或把作为实体的文档移到单独的目录中;如果它是 Plugin 实体旁边的 .wasm,请在那里放置构建好的 .wasm 本身。如果链接是制品缓存目录或其中的某项,删除它(pull 会重新填充缓存),或者,若要将缓存放在别处,将 artifact_cache_dir 设置为该目录,写成相对于工作区根目录的路径(../shared-cache)。如果链接提交在 git-repository 源所获取的仓库中,请在该仓库中修改它(使其指向仓库内部,或提交文件本身),并指定包含该修改的修订版本。如果链接是目录生成的 overlay 目录下的某个 overlay,将其替换为 overlay 本身,或将包含所有 overlay 的目录指定为 overlay 目录。如果链接位于你导入的目录中,请在该目录中保存文件本身而不是指向它的链接,或者导入链接所指向的目录。

A reference to another file leads out of the directory it must stay inside(对另一文件的引用指向了它必须留在其中的目录之外)

Release 和 Manifest 可以通过路径指定另一个文件:Release 中写作 ./… 或 ../… 的 aggregate: 和 manifest:、它的 extends:、Manifest 中写作路径的 extends:,以及 Release 的 parameters: { $import: … }。工作区中的文档以这种方式只能访问工作区内的文件。位于工作区之外的 Release(你在命令行上指定的,或工作区配置指定的),以及你在工作区之外于命令行上单独指定的 Manifest,只能访问其自身目录内的文件:该目录本身就是一个根,与你在工作区之外指定的目录一样,并且其 extends: 链所指向的每个 Release 都受限于同一目录。按书写形式就跳出该目录的路径,以及按书写形式留在目录内、但途中遇到指向目录外的符号链接的路径,都会被拒绝,且不会从它们指定的文件中读取任何内容。指向该目录下尚不存在的文件的路径不会在此处被拒绝;它会报告为无法读取的文件。工作区边界说明了为什么引用和你指定的路径一样受到限制。

路径从何处解析,遵循语言参考为每个键说明的同一规则:Release 的 aggregate: 和 manifest:,以及 Manifest 的 extends:,相对于命令或请求所指定的 Release 解析——对于你单独指定的 Manifest,则相对于该 Manifest 解析;Release 的 extends: 和 parameters 的 $import:,相对于书写它的 Release 解析,因此 extends: 链的每一环都相对于自身指定其父级。诊断会给出解析所依据的目录。

名称(而非路径)不在此处判定——aggregate: payments、extends: base-manifest。它会在 Release 旁的文档中查找,对于 Aggregate 还会在目录(catalog)目录中查找,这些目录受上文 “A file the operation reads leads through a link out of the directory it must stay inside(操作读取的文件通过链接指向了它必须留在其中的目录之外)” 中的规则约束。

每个解析 Release 所指定内容的入口都会在读取文件之前因此停止:aggrega pull、aggrega build、aggrega validate、对 Release 或 Manifest 执行的 aggrega inspect、对单个 Release 的 lint,以及编辑器和助手发起的构建、预览、绘制图、验证或描述 Release 的请求。在编辑器中,诊断会标注在 Release 中指向该文件的键上。

发出的消息。以该条件自身的句子开头,然后依次是按书写形式的引用、对于 extends: 和 parameters 的 $import: 还有书写它的文档、解析所依据的目录、它指向的位置、它必须留在其中的目录,以及将其带出目录的链接(如有);然后是补救措施。对于工作区中的文档:

a reference a document makes to another file leads out of the directory it must stay inside (.spec.aggregate: ../shared/app.yaml, resolved from <workspace>, which leads to <elsewhere>/shared/app.yaml, outside the workspace <workspace>). nothing was read from that file. A document in the workspace reaches only files inside <workspace>: move the file there — or, where a link carries the reference out, make the link lead there — or open the workspace at a directory holding both documents. An Aggregate kept outside that directory is reached by its name rather than a path, from a catalog directory the workspace configuration lists(文档对另一文件的引用指向了它必须留在其中的目录之外(该引用从工作区解析,指向工作区之外的位置)。没有从该文件读取任何内容。工作区中的文档只能访问工作区内的文件:将该文件移到工作区内——或者,在由链接把引用带出的情况下,让该链接指向工作区内——或者在同时包含这两个文档的目录处打开工作区。保存在该目录之外的 Aggregate 通过其名称而非路径,从工作区配置列出的目录目录中访问)

对于在工作区之外指定的 Release 或 Manifest,其自身目录即是它必须留在其中的目录:

a reference a document makes to another file leads out of the directory it must stay inside (.spec.aggregate: ../aggregates/app.yaml, resolved from <directory>, which leads to <parent>/aggregates/app.yaml, outside <directory>, the directory of a document named outside the workspace <workspace>). nothing was read from that file. A Release or a Manifest named outside the workspace — on the command line, or by the workspace configuration — reaches only files inside its own directory <directory>: move the file there — or, where a link carries the reference out, make the link lead there — or name the document from a workspace holding both documents. An Aggregate kept outside that directory is reached by its name rather than a path, from a catalog directory the workspace configuration lists(文档对另一文件的引用指向了它必须留在其中的目录之外(该引用从在工作区之外指定的文档所在目录解析,指向该目录之外的位置)。没有从该文件读取任何内容。在工作区之外指定的 Release 或 Manifest——无论是在命令行上,还是由工作区配置指定——只能访问其自身目录内的文件:将该文件移到该目录内——或者,在由链接把引用带出的情况下,让该链接指向该目录内——或者从同时包含这两个文档的工作区中指定该文档。保存在该目录之外的 Aggregate 通过其名称而非路径,从工作区配置列出的目录目录中访问)

对于 extends: 或 parameters 的 $import:,引用之后会附上 written in <document>;若是链接将路径带出,末尾会附上 the link <link> leads to <place>。aggregate: 或 manifest: 引用不给出文档:扩展另一个 Release 的 Release 可能从链上更上层的 Release 继承了它,无论哪种情况,它都相对于命令所指定的 Release 解析。

该诊断的类别为 [OPS_ERROR]:引用写在 Release 或 Manifest 中。

**修复方法:**对于保存在工作区之外的 Aggregate,写出其 metadata.name 而不是路径,并在工作区配置的 catalog_dirs 下列出包含它的目录,或通过 --catalog 传入——目录目录是工作区访问其外部实体的方式。Manifest、extends: 指定的 Release 以及 parameters 文件都相对于 Release 读取,从不按名称查找,因此请将它们保留在工作区内,或在同时包含该 Release 和该文件的目录处打开工作区。对于你从工作区之外指定的 Release 或 Manifest,将它所指定的内容保存在其自身目录中,或在同时包含它及其所指定内容的工作区中构建它。若是链接将路径带出,用链接所指内容的副本替换该链接,或让它指向目录内部。

No catalog version satisfies a version constraint(没有满足版本约束的目录版本)

引用指定了目录中存在的实体,却固定了目录中不存在的版本:一个不存在的精确版本,或一个没有任何可用版本匹配的 caret 范围。这与单纯的未命中不同——后者是名称本身未知;而这里实体存在,只是版本无法满足,因此消息会如实说明,而不是报告实体缺失,让你去查找名称中的拼写错误。

每种类型都通过同一种选择到达此处,因此无法满足的版本固定无论写在何处,表现都相同:Manifest 的 Recipe 映射上的版本拼写错误,与组件类型上的相同拼写错误会以完全相同的方式被拒绝。

该条件是可恢复的,因此编辑器能在你继续输入时将其显示为诊断,而不是放弃该文档。在命令行上,它会被并入一次停止。

输出的消息,针对 Release 的依赖所触及的引用——组件类型、Manifest 映射值——并指出它是在何处收集到的:

no catalog version satisfies the referenced version constraint: entity "<reference>" (referenced from <referring paths>)(没有任何目录版本满足所引用的版本约束:所示实体,以及引用它的位置)

发出的消息,针对 extends: 指针上的版本固定:

no catalog version satisfies the referenced version constraint (Component <name>, at .extends, no catalog version satisfies extends parent "<reference>")(没有目录版本满足所引用的版本约束:该 Component 的 extends 父项引用没有可满足的目录版本)

若版本固定位于 Feature 的链上,则以 Feature 代替 Component。

**修复方法:**将版本固定改为目录中存在的版本,或将该版本添加到目录中。aggrega inspect 会列出实体可用的版本。不匹配任何版本的 caret 范围通常意味着可用版本都低于它指定的下限——放宽范围,或发布该引用所等待的版本。

不属于任何版本固定形式的版本固定是另一种条件,见下文 “A version pin is none of the forms a pin takes(版本固定不属于任何版本固定形式)”。

A version pin is none of the forms a pin takes(版本锁定不属于任何一种锁定形式)

引用指向另一个实体,并可在冒号后锁定所需版本,形式有两种:精确锁定,即语义化版本,例如 1.0.0(也是每个实体的 metadata.version 所用的形式);或 caret 锁定,即 ^ 后跟一个版本,例如 ^1.0.0,它选择与该版本兼容的最高版本。两者都不是的锁定(caret 后的文本不能解读为版本范围,如 ^garbage;或精确锁定不是语义化版本,如 1.x、1.0 或 v1.0.0)根本不指代任何版本,因此任何目录都不可能包含它所要求的内容。

这样的锁定会被报告为格式错误,而不是报告为目录中没有的实体或版本,因此诊断会引导你检查自己输入的文本,而不是去寻找不存在的东西。无论锁定写在哪里,都是同一个条件:component 或 feature 的 type、Component 或 Feature 的 extends:、Manifest 映射的键或值、Release 的 spec.aggregate、Recipe 或 FeatureRecipe 的 implements:、选择为 Recipe 的 capability: 提供服务的插件时该字段锁定的版本,以及流水线步骤的 plugin:。

它在报告引用解析失败的位置报告,因此格式错误的锁定永远不会改变哪些引用能够解析,只会改变失败信息的内容。格式正确但没有可用版本满足的锁定,仍保持该处为其报告的条件:上文的“No catalog version satisfies a version constraint(没有目录版本满足版本约束)”,或所在位置的未找到条件。

只有最后一个冒号之后的文本才是锁定,且仅当其中不含 / 时。因此,指向带端口的注册表主机的引用,例如 localhost:5000/core/api-server,不带锁定(端口冒号之后的文本是引用的延续),也永远不会被报告为格式错误的锁定。

发出的消息,以 component type 上的 caret 锁定为例:

reference carries a malformed version pin (reference "<reference>", pin "<pin>", the text after ^ is not a version range, referenced from <authored location>). write the reference as , as : with a semantic version such as 1.0.0, or as :^ for the highest version compatible with it(引用带有格式错误的版本锁定:^ 之后的文本不是版本范围。请将引用写为仅名称、名称加语义化版本(如 1.0.0),或名称加 ^ 和版本以选择与之兼容的最高版本)

精确锁定会以 an exact pin must be a semantic version 代替 caret 子句。其后的值说明引用写在何处,用词取决于报告它的位置:referenced from 加编写位置、in the Release's spec.aggregate 或 in the recipe's spec.implements。当 Manifest 映射与其 Recipe 的 implements: 进行比对时,映射条目以及其中哪一侧带有锁定(in the mapping key 或 in the recipe's spec.implements)会改为出现在引用之前;Component 或 Feature 的 extends: 则在其前面写出扩展的实体和字段。

**如何修复:**将锁定改写为两种形式之一,或删除锁定以选择可用的最高版本。通配符如 1.x 应写为 caret 锁定 ^1.0.0;带前导 v 或少于三个数字的版本应写完整,即 1.0.0。

Every version a reference could select has been withdrawn(引用可选择的每个版本都已撤回)

引用解析到注册表中存在的一个仓库,而版本发现可能从中选择的每个版本都已被标记为撤回。已没有可供选择的合格版本。

**这有意不被报告为缺失的实体。**该仓库存在且仍包含这些版本;称其不存在会指错问题,让你去找拼写错误,并且看起来像是一次悄然的回退,而不是它实际上的拒绝。消息会列出每个撤回的版本及针对其记录的原因,因此你得到的信息就是发布者所记录的。

直接指定一个已撤回的版本不会触发此停止。精确版本完全绕过版本发现,因此锁定它正是你有意继续使用它的方式;构建会报告该撤回并继续进行。

发出的消息:

every published version this reference could select has been withdrawn: <reference>: withdrawn: <version> (<recorded reason>), <version> (<recorded reason>)(该引用可选择的每个已发布版本均已被撤回,并列出各版本及其记录的原因)

**如何修复:**阅读记录的原因,其中通常会指明应迁移到什么。迁移到替代已撤回实体的内容,这正是撤回所期望的结果。如果暂时必须保留旧版本,请在引用中锁定精确版本:指定版本即表示你接受它,此后构建每次都会报告该撤回,而不是拒绝。

A plugins.providers binding names a plugin that does not serve the capability(该绑定指定的插件不提供此能力)

工作区的 plugins.providers 块为某项能力选择了一个插件标识,但没有任何提供该能力的 provider 渲染 Plugin 带有该标识。该绑定是目录无法满足的显式选择,因此会停止,而不是悄然回退到另一个插件:回退会通过你已声明不使用的插件渲染输出,且不作任何提示。

绑定按插件的坐标标识进行选择,即插件类型和插件名称(也是 lockfile 所锁定的内容),其后可以带一个版本。

**无论是否有 Recipe 请求该能力,都会对其进行判定。**否则,只有当 Recipe 的 capability: 指定某个绑定时才会读取它,于是能力拼写错误的绑定既不会被查阅,也不会被报告。因此,每次构建和每次 aggrega validate --release 都会检查每个指定了插件的绑定:无论是否有 Recipe 使用,pull 都会解析这样的绑定,因此构建持有该插件并知道它提供什么,而该插件不提供的能力必定是错误的。该检查读取的是工作区配置中的绑定,而不是 lockfile,并且不会改变由哪个插件渲染 Recipe,这仍由 lockfile 决定。指定了构建未持有的插件(尚未被任何 pull 获取的注册表插件)的绑定,在 pull 获取它之前不会被判定。未指定插件的绑定则以另一种方式判定,作为建议:参见下文“Conditions that do not halt a build”下的“A provider binding names a capability no plugin the build reads serves(provider 绑定指定的能力不由构建所读取的任何插件提供)”。

发出的消息,会补充所指定插件实际提供的能力,以及当绑定的能力与之只差一次编辑时的相应拼写:

plugins.providers entry names a plugin no provider-rendering plugin serving the capability matches: capability "<capability>" is bound to plugin "<plugin-identity>", but no provider-rendering plugin serving "<capability>" matches that identity; "<plugin-identity>" serves "<served capability>", and "<capability>" is one edit from "<served capability>"(plugins.providers 条目指定的插件与任何提供该能力的 provider 渲染插件都不匹配;消息还会给出所指定插件实际提供的能力,以及相差一处编辑的拼写)

当绑定指定的插件不在构建所读取的目录中时,消息在“matches that identity”之后结束,因为关于它提供什么已无可说明。

**如何修复:**首先对照插件自身的坐标检查绑定的拼写:在应写插件的位置写了能力,是常见的失误。如果消息指出了一个与你所写能力只差一次编辑的能力,那么拼写错误就在绑定的 capability: 中。然后确认该插件在构建所读取的目录中,并且在 spec.provider.capabilities 下列出了此能力;曾经提供该能力但已不再声明它的插件,恰好会产生此消息。如果只有一个插件提供该能力,删除绑定就是正确的修复方式,因为此时绑定已没有需要消除歧义的对象。

No provider plugin version satisfies a Recipe’s provider pin(没有 provider 插件版本满足 Recipe 的 provider 版本固定)

某个 Recipe 绑定了一个固定版本的 provider(helm:1.0.0 或 helm:^1.0.0),但没有任何渲染 provider 的 Plugin 版本满足该版本固定。版本固定是一个明确的请求,因此构建会停止,而不是忽略它并通过恰好服务该 provider 的任意版本进行渲染;静默覆盖版本固定会产生作者自己的声明认为不应存在的输出。

有两种情况会导致此停止,消息会加以区分:根本没有任何插件服务该 capability,或者有插件服务它但其所有版本都不满足该约束。

这与上文无法满足的实体版本不同。那种情况针对的是以目录中不存在的版本引用的目录实体;这种情况针对的是选择渲染某个 capability 的插件。

输出的消息:

no provider-rendering plugin version satisfies the recipe’s provider version pin: capability "<capability>" pins "<version>" but no provider-rendering plugin serves it no provider-rendering plugin version satisfies the recipe’s provider version pin: capability "<capability>" pins "<version>" but no serving plugin version satisfies it

**如何修复:**放宽或更正 Recipe 的 capability: 字段中的版本固定,或者将它所要求的插件版本添加到目录中。caret 版本固定匹配同一主版本内不低于下限的版本,因此无论 1.x 插件多新,都不满足 ^2.0.0 的版本固定。如果消息表明没有任何插件服务该 capability,那么问题不在版本固定:插件完全缺失,去掉版本固定也无济于事。

No plugin advertises a requested parse or import format(没有插件声明所请求的解析或导入格式)

请求了某种格式,但没有插件声明它。按格式路由的两个插槽各有自己的条件,二者的区别仅在于所请求的工作:parser 插件读取外部源格式,importer 插件将外部内容作为 Aggrega 实体导入。

格式空间是开放的,完全属于插件。两个插槽都不持有编译器已知的格式列表:插件将其处理的格式声明为 capability,新格式以新插件的形式发布,无需修改编译器。因此,此停止报告的是当前已声明的集合,而不是固定的枚举,并且每次未命中都会明确报出:请求要么有声明者,要么无法满足。缺失的插件不会被任何东西替代,唯一的例外是编译器自带的 parser,见下文。

输出的消息:

no parser plugin advertises the requested format: no parser plugin advertises "parse:<format>" no importer plugin advertises the requested format: no importer plugin advertises "import:<format>"

如果单个 parser 插件声明了该格式,但其版本形式无法解析,则会被视为没有声明者,而不是静默通过,并会如此说明:

no parser plugin advertises the requested format: no parser plugin version resolves for "parse:<format>"

**解析会回退到编译器自带的 parser。**构建会解析它交给 render-verdict 策略、且格式并非该策略原生可读的每个文件,importer 通过其指定语法的 parser 读取源,未指定格式的导入则按每个适用签名指定的语法解析源。对于每种语法,使用工作区目录提供的 parser;如果目录没有提供,则使用编译器自身为该语法自带的 parser——其中包括构建读取 Terraform 输出所用的 HCL parser,以及编译器的 core importers 所使用的 JSON parser,因此无论是针对 Terraform 输出的策略,还是通过 core importer 进行的导入,都不需要目录中有 parser。如果目录确实为某种语法提供了 parser,编译器自带的就不起作用,而目录中两个不同名称的 parser 会按照 A parse or import format is advertised by more than one plugin(某种解析或导入格式由多个插件声明) 所述被拒绝。因此,此停止指出的是目录和编译器都未提供 parser 的语法。

**如何修复:**确认格式的拼写与插件声明的一致——capability 由插槽前缀和格式名组成,因此声明 parse:hcl 的插件只服务 hcl 格式。然后确认该插件存在于构建所读取的目录中。如果该格式不存在任何插件,那么缺少的就是这个插件;编译器无法读取没有任何插件声明的格式。

A parse or import format is advertised by more than one plugin(某种解析或导入格式由多个插件声明)

两个或更多不同的插件声明了同一种格式,若不猜测使用哪一个,就无法路由该请求。

**同时包含二者的目录是合法的,加载时不会报错。**两个发布者可以各自为同一格式发布 parser 或 importer,联合它们的目录是受支持的做法。这种歧义是使用点条件:只有在实际请求有争议的格式时才会停止,因此位于构建范围之外的竞争插件对永远不会阻塞构建。

所有候选项都会被列出并排序,因此每次运行的消息都相同。

输出的消息:

format is advertised by more than one parser plugin: format "<format>" is advertised by parser plugins [<plugin-names>] format is advertised by more than one importer plugin: format "<format>" is advertised by importer plugins [<plugin-names>]

对于 importer,此停止还有另一种形式:工作区的 plugins.importer 条目挂载了多个声明该格式的 importer,此时消息列出的 importer 就是被挂载的那些。

导入可选择的 importer 包括工作区目录中的 importer 和编译器的 core importers,后者在每个工作区中都会声明其格式。因此,如果目录为某个 core importer 所服务的格式(import:langflow 或 import:flowise)持有另一个名称的自有 importer,那么在两者都未挂载的导入中就会遇到此停止,消息会将 core importer 与目录中的 importer 一并列出。目录中以 core importer 自身名称持有的 importer 不算第二个声明者:同一名称内会选择最高版本,与 core importer 版本相同、且旁边带有其模块的那个会替代它运行。旁边没有模块的那个,在有可运行的同名 importer 声明该格式时不是候选,详见与你自己的导入器并存时运行哪一个。

**如何修复:**对于 importer,将二者都保留在目录中——或将你自己的保留在 core importer 旁边——并挂载你想要的那个:一个 plugins.importer 条目,其 uri 通过标识和版本指定它,即 uri: importer/<name>:<version>,与 aggrega plugin add importer 写入的形式相同。被挂载的 importer 会在声明该格式的 importer 中被选中,正如 plugins.providers 条目在 provider 插槽上从服务某个 capability 的插件中进行选择,详见下文“A capability is served by more than one provider plugin(某个 capability 由多个 provider 插件服务)”。如果列出的 importer 是你的条目所挂载的,保留你想要的那个条目并删除另一个。parse 插槽没有这种选择机制,因此对于 parser,补救方法是缩小构建所读取的目录,使其中只包含你想要的插件——将 --catalog 指向存放你所选插件的目录是最直接的方式。

A plugins.importer entry pins a version of its importer the catalog does not hold(该条目固定了目录中不存在的导入器版本)

plugins.importer 条目通过身份和版本挂接一个导入器——精确版本 uri: importer/<name>:1.2.0,或范围 uri: importer/<name>:^1.2.0——该导入器声明了导入所请求的格式,但导入可选的版本中没有一个满足该固定版本。可选的版本是工作区目录中持有的版本,对于核心导入器还包括编译器自身的版本:精确版本不存在,或没有任何版本落在该范围内。版本是一个显式选择,因此导入会在任何导入器运行之前被拒绝,而不是改用该导入器的其他版本运行。

这与上文所述的没有导入器声明该格式不同:这里的导入器在导入可选范围内且声明了该格式,缺少的只是条目所指定的版本。不属于任何版本固定形式的固定值(例如 :latest)则会被报告为格式错误,如“A version pin is none of the forms a pin takes(版本固定值不属于任何固定形式)”所述。

输出的消息,指明该格式的能力以及条目固定的版本:

no importer plugin version satisfies the plugins.importer entry’s version pin: capability "import:<format>" pins "<version>" but no serving plugin version satisfies it(没有导入器插件版本满足 plugins.importer 条目的版本固定:该能力固定了某个版本,但没有提供服务的插件版本满足它)

**修复方法:**将条目 uri 中的版本改为目录中持有的版本(对于核心导入器,编译器自身的版本也算一个),或放宽范围,或将条目指定的版本添加到目录中。脱字符范围匹配同一主版本内不低于其下限的版本,因此无论 1.x 导入器多新,都不满足 ^2.0.0。

A plugin reference carries a registry host or an artifact path(插件引用带有注册表主机或制品路径)

Plugin 引用以形如注册表主机的段开头——包含点或冒号,如 DNS 名称或主机加端口——或以制品路径开头。Plugin 通过其坐标身份寻址:插件类型、斜杠、名称,以及可选的版本。拉取时会加上所配置的注册表和插件路径作为前缀,从而将该身份绑定到物理位置,因此已带有这些内容的引用会被加两次前缀,绑定到一个无法获取的位置。

该引用在构造位置时即被拒绝,而不是在获取时,因此消息会指出你所写的内容,而不是之后以难以理解的标签错误出现。

输出的消息,由正在构造位置的拉取操作引出,下一行给出修复方法:

catalog: tier-3 pull <uri>: wasm plugin reference must be the plugin coordinate identity (<pluginType>/<name>:<version>), not a registry-qualified or artifact path: "<identity>"(目录:第 3 层拉取:wasm 插件引用必须是插件坐标标识,而不是带注册表限定的路径或制品路径) remediation: remove the registry host and the artifact path, leaving the coordinate alone — <pluginType>/<name>:<version>, for example provider/helm:1.0.0; the pull prefixes the configured registry itself, so a reference that already carries one is prefixed twice(修复建议:删除注册表主机和制品路径,只保留坐标;拉取会自行添加所配置注册表的前缀,因此已带有前缀的引用会被重复添加前缀)

**修复方法:**删除插件类型之前的所有内容,只保留坐标——写 provider/helm:1.0.0,而不是 hub.example.com/plugin/provider/helm:1.0.0。构建所拉取的注册表属于工作区配置,而不是身份的一部分,正因如此,一个目录可以由多个注册表提供,而无需编辑其中的实体。

A plugin or recipe reference carries no scope(插件或 recipe 引用缺少作用域)

Plugin 或 Recipe 引用缺少开头的作用域段——完全没有斜杠,或斜杠前为空,如 /name。这两种实体都由两部分标识,第一部分用于区分同名实体:Plugin 由其插件类型和名称标识,Recipe 由其provider和名称标识。两个插槽可以各有一个名为 redact 的插件,两个 provider 也可以各自发布名为 postgres 的 recipe,因此作用域是身份的一部分,而不是装饰。

由空作用域构造的位置会带有一个空路径段——即双斜杠——无法解析,因此该引用在构造位置时即被拒绝,而不是留到之后以难以理解的获取失败出现。

这两种修复方法与上文带限定的插件情况相反,彼此之间也相反,因此各自单独表述:这里的引用缺少一个段,需要添加;而带限定的引用多了一个段,需要删除。

输出的消息,各自由拉取操作引出,下方附有各自的修复方法:

catalog: tier-3 pull <uri>: wasm plugin reference must carry a pluginType scope (<pluginType>/<name>); an empty scope cannot bind to an OCI location: "<identity>"(目录:第 3 层拉取:wasm 插件引用必须带有 pluginType 作用域;空作用域无法绑定到 OCI 位置) remediation: add the missing pluginType segment — write the reference as <pluginType>/<name>, for example provider/helm or governance/redact, using the pluginType the plugin entity declares under metadata.pluginType(修复建议:补上缺失的 pluginType 段,使用插件实体所声明的 pluginType)

catalog: tier-3 pull <uri>: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "<identity>"(目录:第 3 层拉取:recipe 引用必须带有 provider 作用域;空 provider 无法绑定到 OCI 位置) remediation: no local catalog directory held this reference, so it was looked for in the registry, where a provider segment is required; re-run as aggrega pull --release <release> --catalog <dir> so the directory that holds it is searched first (--catalog is repeatable)(修复建议:没有本地目录包含此引用,因此在注册表中查找,而注册表要求 provider 段;请指定包含它的目录重新运行,使该目录优先被搜索,该参数可重复使用)

**修复方法:**对于插件,加上 Plugin 实体在 metadata.pluginType 下声明的插件类型作为前缀。对于 recipe,加上 Recipe 在 spec.capability 下声明的 provider 作为前缀。recipe 的修复提示指出了另一种值得注意的可能:既然到达了注册表,就说明已先搜索过本地目录且都不持有该引用,因此如果该 recipe 本应来自本地目录,请将构建指向该目录,而不是添加作用域。

The build consumes an artifact its publisher has deprecated(构建使用了其发布者已弃用的制品)

此次构建解析的某个引用带有其发布者记录的弃用标记,且该标记的严重级别达到或高于工作区配置的停止阈值。标记是在制品发布之后才附加上去的,因此昨天还能干净构建的制品,今天可能就带上了标记,而你自己的文件没有任何改动。

**报告与停止是分开的,只有停止是可配置的。**每个已记录的标记都会被报告,无论严重级别如何,且没有任何配置能关闭这一点。标记是否还会停止构建,由 halt_on_deprecated_severity 决定:它按 warning < error < retracted 的顺序,将记录的严重级别与配置的阈值进行比较。未配置阈值时,不会停止任何构建,每个标记都只是提示。超出这三者的严重级别或阈值永远不会达到:格式错误的值既不能导致停止,也不能抑制停止。

构建停止前会打印所有通知,而不只是导致停止的那一条,因此提高阈值永远不会让你漏掉任何发现——停止本身会指出它停在的那一个引用。发现按引用排序,因此同一个 lockfile 每次运行都报告相同的顺序,导致停止的那一条也总是相同的。

会检查两个存储,且两者的报告方式相同:lockfile 固定的引用,以及为接受或拒绝判定而记录为受信任的插件。两项检查都不会访问仓库——两者都读取已记录的内容——因此构建保持预先编译(ahead-of-time)。

发出的消息。每个发现在遍历时打印,随后停止会重复达到阈值的那一条,并指出停止构建的设置:

deprecation: <reference> is retracted: <the publisher's recorded message> (recorded in the lockfile at pull, as of <when>; re-run `aggrega pull` to refresh it)

deprecation: build consumes a deprecated entity: <reference> is retracted: <the publisher's recorded message> (recorded in the lockfile at pull, as of <when>; re-run aggrega pull to refresh it): halt_on_deprecated_severity is "error"

处于两个提示性严重级别之一的标记,会以 deprecated (warning) 或 deprecated (error) 代替 retracted 表述。保留这一区分,是因为两者含义不同——不建议使用但仍可选择,与被排除在选择之外——把较强的报告为较弱的,会低估实际发生的情况。

**修复方法:**阅读记录的消息,它是发布者本人关于应迁移到何处的说明,然后进行迁移。如果暂时无法迁移,提高 halt_on_deprecated_severity——或取消设置——会把停止重新变为你会持续看到的提示;这是一种有意的接受,而不是变通手段,通知仍会持续打印。针对你已不再使用的版本记录的标记,会在用 aggrega pull 刷新 lockfile 后消失。

A trusted plugin’s recorded digest disagrees with the cached artifact(受信任插件的记录摘要与缓存的制品不一致)

以接受或拒绝构建的角色附加的插件,有一个为其记录为受信任的摘要,而该插件缓存的 manifest 报告了不同的摘要。两者在读取插件的可执行文件之前进行比较,不一致时解析就此停止。

正是这一比较让记录的摘要成为权威,而不只是重复陈述。没有它,插件的字节只会与一个固定值比对,而该固定值恰恰派生自它随后要验证其字节的那个 manifest——这在构造上就是自洽的,无法察觉整个制品已被替换。将记录的内容与 manifest 当前报告的内容进行比较,才为该检查提供了外部视角。

这不同于内容摘要不匹配,后者报告的是解析出的字节与为其声明的摘要不一致。此处尚未读取任何内容,字节也很可能与 manifest 一致;不一致的是到底在解析哪个制品。区分两者很重要,因为补救方法相反——一种是损坏或被篡改的制品,另一种是合法变更、其新身份尚未经审查的插件。

发出的消息:

resolve cached plugin "<plugin-identity>": the digest recorded as trusted for it is <recorded-digest>, but the plugin manifest in the content cache reports <cached-digest>; review what changed and re-record the trusted digest, or restore the recorded artifact: the digest recorded as trusted for this plugin does not match the digest its cached manifest reports

**修复方法:**在重新记录任何内容之前,先查明发生了什么变化——这是一个可以拒绝你的构建的插件,而记录的摘要表明有人审查过它。如果变化是预期的,因为你有意升级了插件,请审查新制品并为其重新记录受信任的摘要。如果变化不在预期之内,请恢复记录所指的制品;这一不一致正在告诉你,身份在没有任何人决定的情况下发生了变化。

无法组装 extends: 链

某个 Component、Feature、Manifest 或 Release 的 extends: 链指向了一个无法解析的父级,因此该链无法合并为单个已解析的实体。

它不同于循环:循环有自己的条件和补救方法,参见上文的“Cyclic extends chain”;也不同于超出深度上限的链,后者在下文有自己的条件;还不同于无法满足的版本固定,那种情况下父级存在,只是版本不存在。

发出的消息,其中指明带有无法解析的 extends: 的实体及其声明的引用:

inheritance merge failed (Component <name>, at .spec.extends, <entity> extends <reference>, which no catalog entity provides). Verify the extends reference names an entity present in the catalog(继承合并失败:该实体所扩展的引用没有任何 catalog 实体提供。请确认 extends 引用指向 catalog 中存在的实体)

当报告该问题的检查按 lockfile 的 pin 从制品缓存中读取父级时——即构建和 aggrega validate --release 的 extends 检查、针对整个目录的 aggrega validate、aggrega inspect,以及从编辑器和助手的 validate 工具运行的相同检查——建议还会进一步指明 pull:“a base published to a registry is fetched by aggrega pull --release <release>”(发布到注册表的基础实体通过所示命令获取)。验证单个实体文件不读取 lockfile,因此 pull 不会改变它读取的任何内容,其消息止于目录。

如果失败的是某个 Feature 的链,消息中会以 Feature 代替 Component。与循环的情况一样,最先指明的实体是解析的起点,而边中指明的实体才是需要打开其 extends: 行的实体;在多层链中,二者并不相同。

Manifest 的 extends: 针对另一个位置解析,因此给出的建议也不同。 Manifest 是与 Release 一同编写的运维配置,而不是目录内容;它的 extends: 指向一个相对路径文件,或该 Release 自身目录中某个 Manifest 的 metadata.name,而绝不是目录实体。因此,其消息末尾会说明该引用未能解析到什么,以及应改为查看何处:

inheritance merge failed (Manifest <name>, at .spec.extends, <entity> extends <reference>, which could not be resolved: <what looking produced>). Verify the extends reference is a relative path or the name of a Manifest in the Release’s directory(继承合并失败:该实体所扩展的引用无法解析。请确认 extends 引用是相对路径,或是 Release 所在目录中某个 Manifest 的名称)

末尾的细节是查找过程本身报告的失败:无法读取的文件,或在该名称下未索引到任何 Manifest 的扫描。因此它通常会说明尝试的是两种形式中的哪一种,以及为何没有结果。

Release 的 extends: 针对一个目录解析,并且只接受一种形式。 Release 以相对路径指定其父级:./base-release.yaml 或 ../shared/base-release.yaml。解析所依据的目录是包含写下该引用的 Release 的目录,并且链上的每一环都针对其自身所在目录解析:因此,放在子目录中的链中间的 Release 应指向与其自身同目录的父级,无论命令所指定的 Release 位于何处。裸标记不是路径,也不指向编译器会去查找的 Release,因此会在此处报告,而不会到一个不可能找到它的地方去搜索:

inheritance merge failed (Release <name>, at .spec.extends, <entity> extends <reference>, which could not be resolved: <what looking produced>). Verify the extends reference is a relative path to a Release file, such as ./base-release.yaml, resolved from the directory holding this Release(继承合并失败:该实体所扩展的引用无法解析。请确认 extends 引用是指向某个 Release 文件的相对路径,例如 ./base-release.yaml,并从包含此 Release 的目录解析)

**修复方法:**对于 Component 或 Feature,确认 extends: 的值指向目录中存在的实体,且拼写与该实体自身的 metadata.name 一致,包括大小写。发布到注册表的基础实体会按 Release 的 lockfile 为其记录的 pin 从制品缓存中读取,因此当基础实体位于注册表中时,请运行 aggrega pull --release <release>:pull 会沿链追溯、获取基础实体并将其固定。对于 Manifest,确认文件位于相对路径所指的位置,或者 Release 目录中存在具有该 metadata.name 的 Manifest 且能够解析。对于 Release,确认该值以 ./ 或 ../ 开头,且其指向的文件存在并能解析为 Release。

extends: 链超出深度上限

某个 Component、Feature、Manifest 或 Release 的 extends: 链能够正常结束,但经过的实体数超过了上限 10 所允许的数量。

它有自己的条件,而不与上一条共用,因为两者的补救方法毫无共同之处:缺失的父级是需要更正的引用,而过深的链是需要扁平化的结构。该上限是防范编写失误的保护措施,而不是结构上的限制:架构师通常只在基线之上扩展一到两层,深达十层的链通常是不断生长的基础树,而非有意的设计。

只有能够结束的链才会触及它。 回环到自身的链无论长度如何都按循环报告,因此该条件绝不会代替循环出现,其建议(缩短链)也绝不会针对循环给出。

发出的消息,其中指明上限和链达到的长度:

extends chain exceeds maximum depth (Component <name>, rule extends). the bound is 10 and this chain reaches <length>; shorten the chain, or extend a base that sits closer to its root(extends 链超出最大深度:上限为 10,而此链超出了该上限;请缩短该链,或扩展一个更靠近根的基础实体)

如果失败的是 Feature、Manifest 或 Release 的链,消息中会以 Feature、Manifest 或 Release 代替 Component。对于每种声明 extends 的类型,上限都是同样的 10,且计算的是链上的实体数而不是实体之间的链接数:恰好包含 10 个实体的链可以构建,第 11 个实体才是此处报告的对象。因此,一个实体扩展一个基础,而该基础又扩展另一个基础(3 个实体,2 个链接),计为 3。

**修复方法:**合并链的中间部分。如此深的链通常意味着每一层只增加了少量内容,将若干层合并为一个基础实体既是修复方法,也是更清晰的结构。如果各层确实各不相同,链中较下方的实体可以直接扩展更靠近根的基础,而不必经由中间的每一层继承。如此深的 Manifest 链通常是按环境叠加的覆盖层栈:把没有人改动的层合并到它所覆盖的基础中。

同一断言名称在 extends: 链上被声明了两次

某个实体及其所扩展的对象都以相同名称声明了断言,且两者声明的规则不同。扩展实体的断言是对其基础断言的补充,绝不会替换其中任何一个。因此,以两条不同规则两次声明同一名称,会悄无声息地废除基础的不变式,这与扩展实体的目的恰恰相反。

以完全相同的规则声明同一名称不算冲突,可以构建。正是这一点使检查在链上保持幂等:否则,三层深的链每次都会与其自身的中间层发生冲突。

顺序是契约的一部分,而非偶然。断言按合并后的顺序求值,第一个失败的断言会中止构建,因此基础的不变式先于后代的不变式被检查;沿着链,断言集合从根向下累积。

发出的消息:

assertion name declared twice across the extends chain (Component <name>:<version>, rule assertions, at .spec.assertions.<key>). assertion "<key>" is already declared by the base Component "<base>", carrying a different rule; rename the extending entity’s assertion; an extending entity’s assertions add to the base’s and never replace one(断言名称在 extends 链中被声明了两次:该断言已由基础 Component 以不同的规则声明;请重命名扩展实体的断言;扩展实体的断言是对基础实体断言的补充,从不替换其中任何一个)

**修复方法:**重命名扩展实体的断言,消息中会指明该断言以及已声明它的基础。如果你本意是替换基础的规则,扩展并不支持这样做:可以收窄基础的断言,使其对每个扩展它的实体都成立,或者将该规则下移到真正需要它的实体上。如果两条规则本应相同,请使其文本完全一致,冲突即会消失。

Release 以两种方式之一路由其 Aggregate 的组件:boundaries: 下的命名边界,或 components: 下的顶层组件。两者互斥,同时声明两者的单个文档在读取时即被拒绝。本条件是同一规则在 extends: 链上的体现:声明命名边界的基础文档和声明顶层组件的子文档各自都是格式正确的,只有将它们合并时,才会把两种选择带入同一个解析后的 Release。

两个文档单独来看都没有错,因此消息会同时给出两者及其两个键。只给出构建所指向的 Release 的诊断,会把你引向一个本身没有任何问题的文件。

各环节一致的链不受影响。 每个环节都声明命名边界时可正常组合,每个环节都声明顶层组件时也是如此。只有混用才会中止。

输出的消息,给出两个文件以及各自声明的键:

release extends chain composes both named boundaries and top-level components: declare one routing shape across the chain, never both (Release <release-file>, boundaries declared by "<file>", components declared by "<file>")(release extends 链同时组合了命名边界和顶层组件:在整条链中声明一种路由形态,切勿两者兼用;依次指出 Release 文件、声明边界的文件和声明组件的文件)

如何修复: 选择链应使用的路由形态,并在整条链中一贯使用。如果基础文档声明命名边界,想要配置组件的子文档应在包含这些组件的边界内对其进行配置,而不是在 Release 根级——这也使它能够更改某个组件的规格而无需重述拓扑。如果基础文档声明顶层组件,需要命名边界的子文档所描述的路由形态与其基础不同,更适合编写为独立的 Release,而不是作为该 Release 的子文档。

An external input’s URL uses a scheme that is not allowed(外部输入的 URL 使用了不允许的协议)

某个实体指向的 URL 使用了允许集合之外的协议。允许的协议有三种:https;http,但仅限于回环主机,因此明文传输只能到达本机;以及 oci,用于从注册表拉取的内容。

针对非回环主机的 http URL 以及任何其他协议,发出的消息分别为:

externalinputs: "<url>": plain http is allowed for loopback hosts only (allowed schemes: https, http to a loopback host, oci): externalinputs: URL scheme is not allowed(仅允许对回环主机使用明文 http(允许的协议:https、指向回环主机的 http、oci):URL 协议不被允许) externalinputs: "<url>": scheme "<scheme>" is not allowed (allowed schemes: https, http to a loopback host, oci): externalinputs: URL scheme is not allowed(协议不被允许(允许的协议:https、指向回环主机的 http、oci):URL 协议不被允许)

**如何修复:**将 URL 改为 https,或者在内容发布于注册表时改为 oci。指向远程主机的明文 http URL 会被直接拒绝而不是降级处理,因此修复方法是将其改为安全协议;本地开发服务器仍可通过 http 正常工作,因为回环主机是允许的。

A render requests an external input the lockfile does not pin(渲染请求了 lockfile 未固定的外部输入)

构建所需的某项内容要从一个 lockfile 未固定的 URL 获取。构建只渲染其 lockfile 记录的闭包,不获取任何内容,因此不存在能让本次运行转而获取该 URL 的设置:冻结的闭包正是构建可重现的原因,而悄悄扩大输入集恰恰是它绝不能做的事。

因此,遇到这一中止本身就提供了信息,而不是配置错误。解析该 Release 时固定项是完整的,所以现在出现未固定的 URL,意味着此后发生了变化:某个值改变了渲染所请求的引用、某个 chart 开始指向新的位置,或者 lockfile 是针对另一个 Release 解析的。

发出的消息:

"<url>" is not pinned in the lockfile; run aggrega pull --release <release> to pin every external input this Release’s render consumes, then build again: externalinputs: acquisition is disabled for unpinned inputs(该 URL 未在 lockfile 中固定;请运行该命令以固定此 Release 渲染所使用的每个外部输入,然后重新构建:对未固定的输入禁止获取)

**如何修复:**固定该输入。aggrega pull --release <path> 会渲染该 Release 以确定它使用哪些外部输入,逐个获取,并将其摘要记录在 lockfile 中依赖固定项的旁边;此后每次构建都从固定记录提供该输入,完全不需要网络。如果该 URL 是因为你编写的内容开始指向它而新出现的,那么被跳过的步骤就是重新解析该 Release;如果它出乎意料,那么在固定之前,值得先找出引入它的引用。

Fetched bytes do not match a pinned digest(获取的字节与固定的摘要不匹配)

某个已固定的 URL 因其存储副本缺失而被重新获取,但返回的内容与 lockfile 固定的不一致。**记录的摘要始终优先:**不会向存储写入任何内容,也不会返回任何字节。

补充获取按记录的摘要进行,而不是按 URL 的标签,因此即使标签被移动到指向不同内容,也无法改变固定条目提供的内容。所以遇到这一中止意味着摘要背后的内容本身未能完整返回。

针对从注册表拉取的内容以及通过 HTTPS 获取的内容,发出的消息分别为:

externalinputs: "<url>": refilled manifest digest is <digest>, pinned digest is <digest>: externalinputs: fetched bytes mismatch the pinned digest(补充获取的 manifest 摘要与固定的摘要不一致:获取的字节与固定的摘要不匹配) externalinputs: "<url>": refetched bytes hash to <digest>, pinned digest is <digest>: externalinputs: fetched bytes mismatch the pinned digest(重新获取的字节哈希与固定的摘要不一致:获取的字节与固定的摘要不匹配)

**如何修复:**首先将其视为供应链问题,而不是需要刷新的 lockfile:固定项声明了你构建时所依据的正是这些确切字节,而拒绝正是该声明在起作用。确认来源仍在发布该摘要所指的内容,并检查你与来源之间是否有任何环节在改写响应;提供替代内容的代理或镜像是常见原因。只有在你知道发生了什么变化并接受它之后,才应使用 aggrega pull 重新固定,它会记录新的摘要。

A stored external input no longer matches its record(存储的外部输入与其记录不再匹配)

从本地存储读回的某个已固定输入与为它固定的记录不匹配。该检查在每次读取时、提供字节之前运行,因此被损坏或篡改的存储会在使用时暴露出来,而不会悄悄地供给构建。

比较的内容取决于输入的固定方式。通过 HTTPS 获取的内容通过对载荷计算哈希来固定,因此每次读取都会重新计算哈希,并报告两个摘要。从注册表拉取的内容按其 manifest 摘要固定,该摘要通过注册表自身的 manifest 关联到载荷,而不是直接对载荷计算哈希,因此存储副本会与记录的大小进行比对;完整的摘要验证则在获取时以及每次按摘要寻址的补充获取时进行。

输出的消息:

externalinputs: "<url>": store blob sha256 is <digest>, pinned digest is <digest>: externalinputs: store blob mismatches its pinned record(存储 blob 的 sha256 与固定的摘要不一致:存储 blob 与其固定记录不匹配) externalinputs: "<url>": store blob sha256/<digest> is <n> bytes but the pinned record says <n>: externalinputs: store blob mismatches its pinned record(存储 blob 的字节数与固定记录不一致:存储 blob 与其固定记录不匹配)

**如何修复:**从存储中删除出问题的 blob,让下一次运行从来源重新补充获取;写入任何内容之前都会先与记录的摘要进行验证。如果随后补充获取也报告摘要不匹配,那么分歧出在上游而非本地,应阅读上面的条目。在多台机器之间共享的存储,或从写入过程中所做备份恢复的存储,是常见的本地原因。

A guard needs a catalog entity the build resolved and cannot see(守卫需要一个构建已解析但无法看到的目录实体)

某个语义守卫去获取某个组件类型背后的目录实体,但该实体不在守卫所获得的视图中,尽管解析阶段已将该类型作为目录引用解析。真正无法解析的引用会更早地在解析阶段中止,因此在守卫处发现实体缺失,意味着构建的已解析集合与守卫的视图出现了分离。

构建会停止,而不是跳过守卫。跳过会撤销一项检查却没有任何提示,守卫所针对的组件将未经检查就通过,而构建却报告成功。

以相对路径(以 ./ 或 ../ 开头)书写的类型不在此处判断:类型从不作为文件读取,因此这样的值根本不指向任何目录实体,会在更早的阶段——解析 Release 的依赖时——作为目录中不存在的引用被拒绝。只有裸标记形式的目录引用才会触发这一中止。

无论在何处满足该条件,它都以相同的措辞报告,因此文本指明的是类型和故障,而不是引发它的检查。

它也不指明任何文档或文档中的键,这是有意为之,也是这一中止与其他所有中止唯一不同的地方。其他每种中止都会定位到你为消除它而需要编辑的文件和字段;这里不存在这样的文件,因此给出位置只会把你引向一个并无过错的键。取而代之的是报告两个视图存在分歧的类型,因为这能让调查者重现这一分歧。

发出的消息:

the compiler’s own views of the catalog disagree (internal error: this build resolved a component type that the catalog it reads then held no entry for. This is a fault in the compiler rather than in an authored document, so there is nothing to correct in the Aggregate, the Release or the catalog. Please report it, naming the command that produced this build and the type the views disagree on: "<type>")(编译器自身的目录视图存在分歧(内部错误:本次构建解析了一个组件类型,而它随后读取的目录中没有该类型的条目。这是编译器的故障,而不是所编写文档的问题,因此 Aggregate、Release 或目录中都没有需要更正的内容。请报告此问题,并注明产生本次构建的命令以及视图存在分歧的类型))

**如何修复:**你自己的文件中没有需要修改的内容:这报告的是编译器内部的不一致,而不是你所编写内容中的故障,值得连同消息中指明的类型作为缺陷报告。该组件的类型几乎可以肯定没有问题。

A reference names no entity the catalog holds(引用指向的实体不在目录中)

在构建渲染任何内容之前,会遍历 Release 所依赖的全部实体并逐一固定版本,使 lockfile 准确记录构建将要读取的内容。目录无法解析的引用会中止这次遍历:无法为它固定任何内容,若继续执行,写出的 lockfile 会缺少构建稍后需要的条目,且不会有任何提示。

拒绝信息会指出该引用及其被收集的位置,因为同一个实体可从多处到达,而命名它的位置正是需要修改的地方。库引用会单独报告,不附带收集路径——库是从 $ref 或 $import 它的实体到达的,失败的名称本身就是全部问题所在。

针对目录实体输出的消息——末尾部分列出引用它的位置:

resolve: no entity in the catalog matches this URI: entity "<reference>" (referenced from <referring paths>)(resolve:目录中没有与此 URI 匹配的实体:该实体及引用它的位置见前文)

针对库:

resolve: no entity in the catalog matches this URI: library "<reference>"(resolve:目录中没有与此 URI 匹配的实体:所示库)

以及针对绑定到 provider 插槽的插件,它以承载它的工作区配置键命名,而不是以目录文档命名:

resolve: no entity in the catalog matches this URI: entity "<reference>" (referenced from .aggrega-config.yaml.plugins.providers)(resolve:目录中没有与此 URI 匹配的实体:所示实体,引用自 .aggrega-config.yaml.plugins.providers)

当 catalog 目录下的某个文件以任何 catalog 都不包含的种类(例如拼错的 kind)声明了引用所要求的名称时,此失败下方的注释会指出该文件、它声明的种类以及 catalog 所包含的种类,并省略关于本地实体从何处读取的建议;无论是填充 lockfile 的构建还是读取 lockfile 的构建,以及报告此失败的其他所有界面,都是如此;参见 被拒绝的 catalog 文件及其所解释的失败。

**修复方法:**按消息引用的原样阅读该引用。不存在的名称、从未发布的版本,以及工作区未指向其注册表的裸名称,都会以完全相同的方式到达这里,因此按以下顺序检查这三点:更正拼写;确认该版本存在;确认存放它的注册表已配置且可访问。如果该实体是你在本地编写的,请确认文件位于构建所遍历的目录内。

当 aggrega pull 或 aggrega build --auto-pull 因某个库引用而停止,而制品缓存中存有一个既没有锁文件条目固定、也没有任何目录文件夹提供的 SchemaLibrary 时,消息后会跟随一行 remediation:,列出每个这样的库。缓存中的库只有在锁文件条目为其摘要作保时才算作目录内容,而拉取操作会从提供该库的注册表记录这一条目。在离线模式下,拉取操作既无法获取该库,也无法为其记录条目,因此该行会提示在能够访问注册表的地方运行 aggrega pull --release <release>,或者在目录文件夹下编写该库。联网时,拉取操作读取的目录文件夹或注册表都不提供该库,因此没有可记录的条目,该行会指向在目录文件夹下编写该库。

A library reference is not written in the identity form(库引用未以身份形式书写)

跨库的 $ref: 或 $import: 先按身份命名库,再命名库内的条目:库的裸名称,可选地加上 : 和版本下限,然后是 # 以及该字段所读取表面上条目的路径。这种形式中不包含注册表主机。名称通过哪个注册表解析属于工作区配置,构建使用哪个版本由 lockfile 决定,因此携带其中任何一项的引用,都会在文档中固定本应由构建决定的内容。

此处拒绝以下情况:携带注册表主机的值;在期望跨库引用的位置写了文档内锚点;空的库名称;以及使用 @ 作为版本分隔符——这种情况会附带更正后的写法报告,而不是作为笼统的形式错误,因为这是这种形式最常见的错误。

发出的消息:

resolve: invalid library reference URI: "<the value as written>"(resolve:无效的库引用 URI:所示为按原样写出的值)

以及在使用 @ 作为分隔符时,引用该值应有的写法:

resolve: invalid library reference URI: version separator is ’:’, not ’@’ — use "<the corrected value>"(resolve:无效的库引用 URI:版本分隔符是 ’:‘,而不是 ’@‘——请使用所示的更正后的值)

**修复方法:**将值改写为 <Library>#<entry-path>,仅在需要限定可选版本的下限时,才在库名称后添加 :<version>。去掉任何注册表主机。如果该引用原本要指向同一文档内部,文档内锚点与库引用是不同的东西,而你所写的字段期望的是库形式。

Two consumers of one library require incompatible versions(同一库的两个使用方要求不兼容的版本)

多个实体可以引用同一个库,每个实体指定一个版本下限或不指定,构建选择的版本是它们所指定的最高下限。正因如此,要求较低的使用方仍能获得满足其要求的版本;也正因如此,添加一个下限更高的使用方会让所有使用方一起升级,而不是让构建分裂为两个副本。

这一规则只在各下限的主版本号一致时成立。指定不同主版本的两个使用方,实际上是在请求两个碰巧同名的库,没有任何单一选择能同时满足两者——因此构建不会选其一而让另一个使用方读取并非为它编写的结构,而是停止并指出这一分歧。未指定下限的使用方不参与此处的决定:选择由固定了版本的使用方决定。

输出的消息。使用方按排序顺序比较:第一个指定下限的使用方确定主版本,消息列出每个参与比较的使用方及其要求的版本,直到并包括第一个下限指定了不同主版本的使用方——因此相同的文档总是列出相同的使用方:

resolve: minimal version selection conflict — incompatible library version requirements: library "<library>" has consumers requiring incompatible majors: <consumer> wants <version>; <consumer> wants <version>(resolve:最小版本选择冲突——库版本要求不兼容:所示库的使用方要求互不兼容的主版本,各使用方及其要求的版本见前文)

**修复方法:**将较低使用方的下限提高到相同的主版本;当所有人都需要较新的结构时,这是通常的做法。如果确实同时需要两个主版本,它们就是两个库:将较旧的结构以独立的名称发布,并让需要它的使用方指向那里,使每个引用都指向它所针对编写的内容。

The chain of module imports is deeper than the pin walk descends(模块导入链的深度超过了固定遍历所能下探的深度)

固定版本时会遍历 Aggregate 导入的每个模块,再遍历这些模块导入的每个模块,使整个集合都进入 lockfile,而不仅是第一层。已记录的模块不会被再次遍历,这正是普通循环得以终止的原因——Aggregate 导入一个又反过来导入它的模块时,会在各记录一次后正常结束,不会报错。

深度上限为十,用于兜底重复检测无法发现的链:每一层都呈现新身份的链,例如每一步都以新版本重新发布的模块。该上限与图构建器所用的上限相同,因此能完成固定的组合也能完成构建。

发出的消息:

resolve: sub-aggregate inclusion depth exceeded: "<module>" at depth <depth>(resolve:子 aggregate 包含深度超限:所示模块及其所在深度见前文)

**修复方法:**缩短该链。这么深的链通常反映的是组织结构,而不是部署结构,因此请找出本身不贡献任何组件的层级,并将其合并到父级中。如果每一层的存在只是为了以新版本重新发布其下一层,那么这些版本本身就构成了这条链:直接导入你真正需要的模块,并使用你需要的版本。

这是固定遍历的上限。图构建器会应用它自己的上限,在下文“Sub-aggregate nesting depth exceeded(超出子聚合嵌套深度)”中报告;两者是同一限制在两个阶段分别触发的报告——前者发生在填写 lockfile 时,后者发生在构建图时。

The catalog view a build was given cannot load the bodies pinning needs(提供给构建的目录视图无法加载固定所需的内容主体)

固定遍历的其中两个维度需要的不只是目录给出的版本答复:它们需要文档本身。Aggregate 导入的模块必须被读取,才能找到它们又导入了什么。构建所绑定的 Recipes、FeatureRecipes 和 Plugins 必须被读取,才能找到它们所指定的制品和库。能解析版本却无法返回这些主体的目录视图,会使这两个维度都无内容可读。

两者都会被提前拒绝而不是跳过,原因在于跳过会产生的结果:一个缺少整类条目的 lockfile,在没有任何报错的情况下写出,之后的构建如实重建它时才发现它不完整。这两条消息都不携带自己的值,因为它们都与你编写的文档无关——每条消息说明的是哪个维度无法计算:

resolve: catalog lookup cannot load resolved sub-aggregate bodies(resolve:目录查找无法加载已解析的子聚合主体) resolve: catalog lookup cannot load resolved recipe and plugin bodies(resolve:目录查找无法加载已解析的 recipe 和 plugin 主体)

**修复方法:**你的文件中没有任何内容会导致这两种情况,也没有任何编写上的修改能消除它们——问题在于构建的接线方式,而不在于要求它构建的内容。请报告此问题,并附上你运行的命令及其所依据的工作区配置。

An annotation-transform plugin names a component it was not given, or injects a value no annotation takes(注解转换插件指定了未提供给它的组件,或注入了任何注解都不接受的值)

运维人员可以以添加注解的角色挂载治理插件,而这种挂载是一种声明:转换是运维人员要求的,因此插件添加的内容是显式的,而不是在任何人不知情时注入的。该角色的权限也相应受限。插件接收你的文档所声明的组件坐标,并且可以在这些坐标上添加注解,每个注解携带一个你本可以亲自写在该注解上的值:一个字符串,或一个由子键组成的对象。它返回的结构不接受其他任何字段,因此在应用其输出时剩下需要检查的是:每一次注入所指定的坐标是否都是提供给它的坐标,以及每个值是否都是注解所接受的值。

如果某次注入指定的边界与组件组合不在该集合中,构建将停止。插件若触及你的文档从未暴露的组件,就等于在配置无人声明的基础设施;而它添加的注解会像手写的注解一样展开为 Feature 挂载,其后果就是从运维人员并未交给它的组件中冒出资源。

值为 null、列表、数字、布尔值或没有子键的对象的注入同样会使构建停止。null 和空对象被读作你为使组件退出它本会继承的注解而写的值,而该角色只添加注解,不移除注解;其他形态则不是注解所接受的值。整个输出会在应用其中任何部分之前接受检查,因此被拒绝的输出不会改变任何内容。

每一次被接受的注入还会附带一个伴随注解 aggrega.ai/injected-by,指明执行注入的插件。该注解由宿主写入;插件无法提供它,因此关于注入注解来源的说法不由插件决定。

输出的消息,分别针对未提供给插件的坐标和任何注解都不接受的值:

annotation-transform plugin output was rejected: an injection targets a component coordinate the host did not supply, or carries a value that is not a string or an object of subkeys: injection targets boundary "<boundary>" component "<component>" (annotation "<key>")(注解转换插件的输出被拒绝:某次注入的目标是宿主未提供的组件坐标,或携带的值既不是字符串也不是由子键组成的对象:注入的目标为所示边界中的所示组件(所示注解)) annotation-transform plugin output was rejected: an injection targets a component coordinate the host did not supply, or carries a value that is not a string or an object of subkeys: injection for boundary "<boundary>" component "<component>" (annotation "<key>") carries a list; an injected annotation value is a string or an object of subkeys(注解转换插件的输出被拒绝:某次注入的目标是宿主未提供的组件坐标,或携带的值既不是字符串也不是由子键组成的对象:针对所示边界中所示组件(所示注解)的注入携带了一个列表;注入的注解值应为字符串或由子键组成的对象)

**修复方法:**错误在于插件而不在于你的文档——修正插件,使其只注入到提供给它的坐标上(这些坐标都会出现在它的输入中),并且只以字符串或由子键组成的对象作为值。如果消息中的组件是你期望插件能看到的,请检查 Release 是否在某个边界内声明了它:只有已声明的组件坐标才会被传递给插件。在修正插件期间,从 plugins.governance 中移除该挂载是解除构建阻塞的直接方法。

A plugin reference is not a Plugin entity(插件引用不是 Plugin 实体)

插件通过其 Plugin 实体来引用,并且始终以插件自身的插槽类型作为作用域:<pluginType>/<name>,可选择附带版本,例如 parser/yaml 或 parser/yaml:1.0.0。作用域是必需的,而不是多种形式之一——不带作用域的 name:version 会被拒绝,因为两个插槽可能各有一个同名插件,而作用域正是使实体可解析的关键。实体所指向的二进制文件通过实体来获取,从不直接指定,因此由实体承载能力声明、运行时限制以及加载时用于核对二进制文件的已记录命令集。因此,未指向任何 Plugin 实体的引用就没有可用于核对二进制文件的依据,构建会停止,而不会依据未经核对的引用加载字节。

有两种情形会在此报告,它们在不同时刻被检查。形式上不可能是实体的引用——文件系统路径,或者制品引用,例如 oci:// URL、裸 .wasm 或 @sha256: 摘要——会在只接受实体引用的位置上被提前拒绝。未指向任何地方所持有的实体的引用会在查找之后被拒绝,而消息内容取决于它的写法:Plugin 实体 URI——<pluginType>/<name>,可选择附带版本——会被报告为没有任何目录持有、二进制文件未携带、也没有任何 pull 获取过的实体;其他任何引用则会被告知应采用该形式。两种情形报告的是同一条件,因此构建对两者的响应相同。

**pull 会在构建遇到第二种情形之前拒绝它。**Recipe 或 FeatureRecipe 的 pipeline 所指定的每个 Plugin 都会与 Release 的其余依赖一起解析——来源可以是目录、编译器二进制文件内的副本、内容缓存或注册表——若其中都没有持有它,aggrega pull 会在写入 lockfile 之前以该条件和相同的消息停止,并指明其 pipeline 引用了该插件的 Recipe 或 FeatureRecipe。

**并非每个位置都会拒绝非实体形式。**流水线插件位置只接受实体引用;而运维人员直接挂载插件的位置接受任何形式,并将非实体引用交由制品解析。因此,同一个引用可能在一个挂载点被接受,在另一个挂载点被拒绝,这种差异源于位置,而非引用本身。

发出的消息。文件系统路径:

plugin reference is not a Plugin entity: "<reference>" is a filesystem path, but a pipeline plugin must be a plugin-type-scoped Plugin entity URI (<pluginType>/<name>, optionally versioned, as in parser/yaml or parser/yaml:1.0.0)(插件引用不是 Plugin 实体:该引用是文件系统路径,但流水线插件必须是以插件类型为作用域的 Plugin 实体 URI,可带版本,格式如上所示)

制品引用:

plugin reference is not a Plugin entity: "<reference>" is an artifact reference (an oci:// scheme, a bare .wasm, or an @sha256: digest), but a pipeline plugin must be a plugin-type-scoped Plugin entity URI (<pluginType>/<name>, optionally versioned, as in parser/yaml or parser/yaml:1.0.0)(插件引用不是 Plugin 实体:该引用是制品引用(OCI 协议、裸 Wasm 文件或 SHA-256 摘要),但流水线插件必须是以插件类型为作用域的 Plugin 实体 URI,可带版本,格式如上所示)

无人持有的 Plugin 实体 URI:

plugin reference is not a Plugin entity: "<reference>" is a Plugin entity URI, but no catalog directory holds the entity it names, the binary does not carry it, and no pull has fetched it into the content cache; place the Plugin entity in a catalog directory, or publish it to a registry and run aggrega pull(插件引用不是 Plugin 实体:该引用是 Plugin 实体 URI,但没有任何目录目录包含它所指的实体,编译器二进制文件中也不带该实体,且没有任何拉取将其获取到内容缓存中;请将该 Plugin 实体放入目录目录,或将其发布到注册表后运行上述拉取命令)

以及其他任何未指向实体的引用——没有插件类型作用域、在版本之前有多个 /,或带有注册表主机:

plugin reference is not a Plugin entity: "<reference>" must be a plugin-type-scoped Plugin entity URI (<pluginType>/<name>, optionally versioned, as in parser/yaml or parser/yaml:1.0.0); a bare .wasm reference or an artifact reference names no Plugin entity(插件引用不是 Plugin 实体:该引用必须是以插件类型为作用域的 Plugin 实体 URI,可带版本,格式如上所示;裸 Wasm 文件引用或制品引用不指向任何 Plugin 实体)

**修复方法:**将引用写成 Plugin 实体以插槽类型为作用域的标识,可选择附带版本——<pluginType>/<name> 或 <pluginType>/<name>:<version>。如果你原本直接指向文件或制品,请为其发布或编写一个 Plugin 实体,然后改为引用该实体——加载时所核对的声明就存放在实体中,因此不存在可跳过实体的等效形式。如果消息说明该引用是 Plugin 实体 URI,则其形式正确,缺少的是实体本身:将 Plugin 实体放入工作区所列出的某个目录,并在其旁边放置构建好的 .wasm;或者将插件发布到工作区读取的注册表,然后运行 aggrega pull 将其获取到内容缓存中——并确认你指定的版本确实存在。

A cached signature bundle does not match the digest recorded for it(缓存的签名包与为其记录的摘要不匹配)

在获取时已验证签名的制品,会在其 lockfile 条目上(对于以裁决角色挂载的插件,则在其 plugins-trust.yaml 条目上)延续这一事实,形式为签名材料的已记录摘要,该材料与制品一同缓存。在任何渲染开始之前,构建会针对其读取的每个记录了摘要的条目(任意种类的目录实体、库、插件)重新读取该缓存材料并重新计算哈希,且哈希必须与记录的一致。lockfile 固定的插件以及以裁决角色挂载的插件,在加载其字节时还会再次检查其材料,这也覆盖了在构建之外加载插件的命令,其中包括 aggrega lint --release 和 aggrega validate --release。签名包缺失、不可读或哈希不一致,意味着经过审核的材料已不是当前磁盘上的内容,运行会停止,而不会使用签名证据已在记录之下发生变化的制品。

重新检查只是哈希比较,仅此而已。 它不重新验证任何签名,不访问网络,也不查询任何信任材料,因此在完全没有网络访问的构建中同样成立——这正是一次验证过的制品能在之后的离线构建中保持已验证状态的原因。

下一次 pull 会修复它。 pull 会对内容缓存提供的每个条目执行相同的检查;当检查拒绝某个条目时,无论签名要求如何规定,它都会再次向该制品的仓库查询签名(经过与其获取的制品相同的验证),将验证结果记录到条目上,并缓存其指向的签名包,改写已不再匹配其摘要的缓存副本。以裁决角色挂载的插件,无论其条目记录了什么,每次 pull 都会重新验证,其签名包也以相同方式缓存。因此,针对内容缓存提供的条目,消息会指明该 pull。从目录目录、编译器二进制内的副本或 Release 旁边读取的条目,从不会在仓库处查询,因此 pull 会保留其上记录的签名不变,其消息也不指明任何 pull。

发出的消息,指明制品、缓存文件,以及(对于内容缓存提供的条目)修复它的 pull、记录签名的文件和它拉取的 Release。来自构建的检查,不可读或缺失时:

artifact "<reference>": cached signature bundle <path> is unreadable: cached signature bundle does not match its recorded digest. remediation: run aggrega pull --release <release> to verify the artifact’s signature at its registry again, record it in <file> and cache the bundle it names(制品:缓存的签名包不可读:缓存的签名包与其记录的摘要不匹配。修复:运行上述命令,在制品的注册表重新验证其签名,将其记录到上述文件中,并缓存其指定的签名包)

以及发生偏移时:

artifact "<reference>": cached signature bundle <path> has digest <actual>, recorded digest is <recorded>: cached signature bundle does not match its recorded digest. remediation: run aggrega pull --release <release> to verify the artifact’s signature at its registry again, record it in <file> and cache the bundle it names(制品:缓存的签名包的摘要与记录的摘要不同:缓存的签名包与其记录的摘要不匹配。修复:运行上述命令,在制品的注册表重新验证其签名,将其记录到上述文件中,并缓存其指定的签名包)

以及从内容缓存加载插件字节时,还会指明其来源:

plugin "<reference>" resolved from <source>: cached signature bundle <path> is unreadable: cached signature bundle does not match its recorded digest. remediation: run aggrega pull --release <release> to verify the artifact’s signature at its registry again, record it in <file> and cache the bundle it names(插件从上述来源解析:缓存的签名包不可读:缓存的签名包与其记录的摘要不匹配。修复:运行上述命令,在制品的注册表重新验证其签名,将其记录到上述文件中,并缓存其指定的签名包)

plugin "<reference>" resolved from <source>: cached signature bundle <path> has digest <actual>, recorded digest is <recorded>: cached signature bundle does not match its recorded digest. remediation: run aggrega pull --release <release> to verify the artifact’s signature at its registry again, record it in <file> and cache the bundle it names(插件从上述来源解析:缓存的签名包的摘要与记录的摘要不同:缓存的签名包与其记录的摘要不匹配。修复:运行上述命令,在制品的注册表重新验证其签名,将其记录到上述文件中,并缓存其指定的签名包)

<file> 是该 Release 的 lockfile,或该 Release 目录中的 plugins-trust.yaml。对于 pull 不会查询的条目,消息在 remediation: 之前结束。

没有仓库可查询的 pull 会改为停止。 目录实体或库在命名时不带仓库,通过工作区的 default_registry 绑定到某个仓库。如果工作区未指定仓库(记录签名时指定了,现在不再指定),就没有配置可用于再次查询该条目的仓库,因此 pull 会以此情形停止,而不会写入下一次构建会拒绝的 lockfile,并保持 lockfile 原样。其消息在 pull 正在执行的步骤之后包含:

verify: "<reference>" records a signature a build does not accept, and no registry is configured to ask about it again: cached signature bundle <path> is unreadable: cached signature bundle does not match its recorded digest(验证:该引用记录了构建不接受的签名,且未配置可重新查询的注册表:缓存的签名包不可读:缓存的签名包与其记录的摘要不匹配)

如何修复: 这并非由你的实体文件引起——缓存属于构建,而不属于你。运行消息中指明的命令 aggrega pull --release <release>:它会重新验证制品的签名,并同时写入签名及其签名包,从而修复自缓存它的那次 pull 以来被删除或篡改的签名包。在离线模式下,该 pull 会停止——要么给出离线拒绝,因为修复需要查询仓库;要么对于以裁决角色挂载的插件,在此之前就指出无法解析该插件的 .wasm,因为 pull 会从插件的仓库解析该 .wasm;为这一次运行允许网络访问即可修复。如果 pull 停止并提示没有配置可查询该条目的仓库,请将 default_registry 设置为拉取该制品的仓库,然后再次 pull。如果工作区对该制品跳过签名验证,pull 会改为不在条目上记录签名,构建在同一设置下会接受这种情况。如果仓库提供的签名无法通过验证,pull 会以该验证自身的拒绝停止:记录的签名与发布者提供的材料确实不一致,这需要由该制品的发布者处理。对于消息中未指明 pull 的条目(从目录目录、编译器二进制内的副本或 Release 旁边读取的条目),请从其条目中删除 signature:此类条目从不受签名要求约束,因此之后构建即可继续。

A recorded signature was made for a different artifact(记录的签名是为另一个制品生成的)

签名会说明它是为哪个制品生成的。当一次 pull 验证某个制品的签名时,它会将这一事实记录在该制品的 lockfile 条目上(对于挂载在裁决角色上的插件,则记录在其 plugins-trust.yaml 中的条目上),并缓存它所验证的签名。在任何内容渲染之前,构建会从内容缓存所提供的每个条目的缓存签名中读取它是为哪个制品生成的,而这必须是构建自身为该条目读取的制品:即其清单与其字节一同保存在内容缓存中的那个制品,而绝不是条目所记录的任何内容。为另一个制品生成的签名会使构建停止。这正是把一个 signature 从一个条目复制到另一个条目时的表现:它所指向的缓存签名是完整的(仍与为其记录的摘要相符),但它是为另一个条目的制品生成的。

它不依赖于签名要求。 无论是否要求签名,记录的签名都要符合它所声称的内容,就像检查缓存签名是否与其记录的摘要相符一样。

无论插件在何处加载,都以同样方式检查。 对于 lockfile 固定的插件以及挂载在裁决角色上的插件,当其字节从内容缓存加载时,其记录的签名都要与这些字节被读取为的制品相符;这一检查也覆盖在构建之外加载插件的命令,包括 aggrega lint --release 和 aggrega validate --release,以及通过 aggrega serve 和 aggrega mcp 执行的相同操作。

检查读取什么,以及它无法分辨什么。 它读取缓存签名和制品旁边的清单,并比较哈希:它不验证任何签名,不访问网络,也不查阅任何信任材料,因此在完全没有网络访问的构建中也成立。它以 pull 所接受的两种形式读取签名是为哪个制品生成的:直接对制品本身生成的签名(工具链自带的签名器生成的就是这种),以及指明该制品的已签名声明。因此,从一个条目复制到另一个条目的签名,无论哪种形式都会被拒绝。这与 pull 对其接受的每个签名所做的读取相同:如果签名能通过验证,但读取发现它并非为该制品生成,或根本无法从中读出制品,pull 就会拒绝它,因此 pull 记录的签名不会有检查无法读取的。从目录目录、编译器二进制内的副本或 Release 旁边读取的条目不带清单,因此其记录的签名只需与其记录的摘要相符;以这两种形式之外的形式手动放入缓存的签名也是如此。而且由于不验证任何签名,手动写入缓存、为该条目自身制品生成的签名,无法与 pull 验证过的签名区分开。

下一次 pull 会修复它。 pull 会对内容缓存提供的每个条目执行同样的检查,当检查拒绝某个条目时,它会再次向该制品的仓库查询签名(无论签名要求如何规定),并将验证结果记录在该条目上,取代被复制的签名。挂载在裁决角色上的插件在每次 pull 时都会重新验证,无论其条目记录了什么。只有内容缓存提供的条目才会检查其签名是为哪个制品生成的,因此构建或插件加载对该情况的每次拒绝都会指明那次 pull。

输出的消息会指明条目、记录签名的文件、缓存签名、构建为该条目读取的清单,以及修复它的 pull。来自构建检查的消息:

artifact "<reference>": signing: the recorded signature was made for a different artifact (<file> records it, cached signature bundle <path>, the artifact read has manifest <manifest-digest>). remediation: run aggrega pull --release <release> to verify the artifact’s signature at its registry again, record it in <file> and cache the bundle it names(工件:签名:记录的签名是为另一个工件生成的(由所示文件记录,所示缓存签名 bundle,所读工件具有所示 manifest)。修复方法:运行所示 pull 命令,在工件的注册表中重新验证其签名,将其记录到所示文件中,并缓存其指向的 bundle)

以及在加载插件字节时,还会指明其来源:

plugin "<reference>" resolved from <source>: signing: the recorded signature was made for a different artifact (<file> records it, cached signature bundle <path>, the artifact read has manifest <manifest-digest>). remediation: run aggrega pull --release <release> to verify the artifact’s signature at its registry again, record it in <file> and cache the bundle it names(从所示来源解析的插件:签名:记录的签名是为另一个工件生成的(由所示文件记录,所示缓存签名 bundle,所读工件具有所示 manifest)。修复方法:运行所示 pull 命令,在工件的注册表中重新验证其签名,将其记录到所示文件中,并缓存其指向的 bundle)

<file> 是该 Release 的 lockfile,或该 Release 目录中的 plugins-trust.yaml。

没有可查询仓库的 pull 会改为停止,与缓存签名包不再匹配其摘要时相同:当目录实体或库带有被复制的签名,而工作区不再指定可绑定的 default_registry 时,pull 会因该情况停止,并保持 lockfile 原样。其消息在 pull 当时执行的步骤之后包含:

verify: "<reference>" records a signature a build does not accept, and no registry is configured to ask about it again: signing: the recorded signature was made for a different artifact (cached signature bundle <path>, the artifact read has manifest <manifest-digest>)(验证:所示引用记录了构建不接受的签名,且未配置可再次查询的注册表:签名:记录的签名是为另一个工件生成的(所示缓存签名 bundle,所读工件具有所示 manifest))

如何修复: 这并非由你的实体文件引起,而是条目记录的签名属于另一个制品。运行消息中指明的命令 aggrega pull --release <release>:它会在仓库验证该条目自身的签名,并以其取代被复制的签名,对 lockfile 条目和挂载在裁决角色上的插件都适用。如果文件已提交,从版本控制中恢复该条目自身记录的签名也可以。在离线模式下,pull 会停止:因为修复需要查询仓库,所以会给出离线拒绝;对于挂载在裁决角色上的插件,则在此之前就会停止,并指出插件的 .wasm 无法解析,因为 pull 要从插件的仓库解析该 .wasm。仅为这一次运行允许网络访问即可修复。如果 pull 停止并提示未配置可查询该条目的仓库,请将 default_registry 设置为拉取该制品的仓库,然后重新 pull。如果工作区对该制品跳过签名验证,pull 则不在条目上记录签名,而构建在同一设置下会接受这一点。

No verified signature is recorded for an artifact that requires one (要求签名的制品未记录已验证的签名)

从 registry 获取制品的 pull 会依据该 registry 的信任策略验证其签名,并将已验证的事实记录在该制品的 lockfile 条目上。构建不访问任何 registry,因此它读取记录的事实,而不是再次验证;在任何内容渲染之前,它会以 pull 获取该制品时所应用的要求来检查它读取的每个条目。若某个条目由内容缓存提供、对应的制品要求签名,却没有记录已验证的签名,构建就会停止:构建所掌握的任何信息都无法表明它即将用于渲染的制品曾经被验证过。

要求与 pull 的要求逐项一致。 当工作区范围的签名策略覆盖该制品的种类时,或当 registry 在 .aggrega-config.yaml 中的自身条目(对于没有自身条目的 hub.aggrega.ai,则为官方 hub 的内置策略)要求签名时,就要求签名;在策略生效时,无法确定种类的制品按要求签名计算。凡是让 pull 接受无签名制品的设置,也让构建接受其条目:顶层的 skip_signature_verification、registry 自身条目上的同一开关(工作区范围策略要求的种类除外),以及标记为 advisory 的 registry。

条目的来源从构建中读取,绝不从 lockfile 中读取。 内容缓存提供的每个条目都会受到检查,无论该条目还记录了什么,因此将条目的 manifest digest 连同其签名一起删除并不能使其豁免。从 catalog 目录、编译器二进制文件内的副本或 Release 旁边读取的条目永远不受检查,因为不是来自 registry 的字节不存在 registry 签名。所有部分的条目——catalog 实体、库和插件制品——都同样受到检查,且检查拒绝的每个条目都会在同一次运行中列出。

附加在 verdict 角色上的插件通过 plugins-trust.yaml 受到同一检查。 处于 ir-verdict 或 render-verdict 角色的 plugins.governance 附加项,以及每个 plugins.linter 附加项,不影响任何渲染出的字节,因此没有 lockfile 条目;改由 lockfile 旁边的记录携带其已验证的签名。构建从内容缓存读取的每个此类插件都以相同的设置受到相同的要求:该记录中未记录签名的条目会使构建停止,该插件完全没有条目同样如此——删除该记录并不能使其豁免。从 catalog 目录或编译器二进制文件内的副本提供的插件不受检查。只要此类插件为某个 Release 加载,该要求就适用,而不仅限于构建:aggrega lint --release 和 aggrega validate --release,以及通过 aggrega serve 和 aggrega mcp 进行的相同操作,在加载它时都会因此情况而失败。

输出的消息会列出该条目、未为其记录签名的文件、要求其签名的设置,以及将签名记录到该文件中的命令。对于 lockfile 条目,列出 lockfile:

signing: no verified signature is recorded for an artifact that requires one ("<reference>", <lockfile-path> records no signature for it, required by <the settings that require it>). remediation: run aggrega pull --release <release> to verify the artifact’s signature at its registry and record it in <lockfile-path>(签名:要求签名的制品未记录经过验证的签名(锁文件未为该制品记录签名,由相应设置要求)。修复:运行 pull 命令,在制品的注册表处验证其签名并将其记录到锁文件中)

对于附加在 verdict 角色上的插件,列出其记录:

signing: no verified signature is recorded for an artifact that requires one ("<plugin>", <record-path> records no signature for it, required by <the settings that require it>). remediation: run aggrega pull --release <release> to verify the plugin’s signature at its registry and record it in <record-path>(签名:要求签名的制品未记录经过验证的签名(信任记录未为该插件记录签名,由相应设置要求)。修复:运行 pull 命令,在插件的注册表处验证其签名并将其记录到信任记录中)

两个文件都以其在命令所给 Release 旁边的路径命名:<lockfile-path> 是该 Release 的 lockfile,<record-path> 是该 Release 目录中的 plugins-trust.yaml。

设置以配置文件自身的措辞命名: `signing.required` at the top level of the workspace configuration、 `signing.required` on the `registries` entry for "<host>" 或 the official hub's built-in signature requirement for "hub.aggrega.ai",适用多项时会连在一起列出。

修复方法: 运行消息中指出的 pull。对于内容缓存提供的、在要求签名时未记录签名的条目,pull 会按该条目记录的 manifest digest 向制品的 registry 请求其签名,方式与它获取制品时完全相同,并将已验证的签名记录到该条目上——这样下一次构建就能读取到它。附加在 verdict 角色上的插件无论如何都会在每次 pull 时被查询,pull 会将验证结果记录到 plugins-trust.yaml 中该插件的条目上,没有条目时会创建一个。若 registry 未附加签名,或附加的签名不被信任配置接受,该 pull 会转而停止并列出该制品,这需要由其发布者处理。在离线模式下 pull 无法查询:对于 lockfile 条目,它会拒绝并说明如何为单次运行允许网络访问;对于附加在 verdict 角色上的插件,它会在查询之前停止,并将该插件的 .wasm 列为无法解析的文件,因为 pull 从插件的 registry 解析该 .wasm。在缓存仍持有该记录所指签名材料的情况下,从版本控制中恢复条目记录的签名可以在不联网的情况下消除此问题。若该制品本就不打算签名,应修改的是要求本身,消息会指出是哪项设置——但放宽它意味着该 registry 的制品在 pull 时也不再受检查,因此应优先缩小工作区范围策略所覆盖的种类,而不是关闭某项要求。

A recorded signature is not the one a pull would record(记录的签名不是 pull 将记录的签名)

aggrega pull --verify 报告此刻运行 aggrega pull 是否会改变 pull 提交的文件,而 pull 为某个制品验证的签名是其写入内容的一部分:锁文件条目上的 signature,以及对于挂接在裁决角色上的插件,plugins-trust.yaml 条目上的签名。本条件是 verify 针对普通 pull 会以不同方式写入的每个已记录签名所报告的内容:在未记录签名处会记录一个,会替换一个,或会清除一个。verify 不写入任何一个文件,并在同一次运行中列出两个文件中所有此类条目。

有两类锁文件条目无需询问注册表即会被报告,因为无论注册表如何应答,pull 都会重写它们,因此在离线模式下也会报告:内容缓存提供的、在信任配置要求签名处未记录签名的条目(pull 会记录该制品的签名,或在无法确立签名时停止),以及其记录的签名是为另一个制品所做的条目,pull 会将其替换为该制品自身的签名。

pull 会重新查找的其他每个条目都会被询问,因为只有注册表的应答才能说明 pull 是否会改变它:因内容缓存未持有其字节而由 verify 获取的条目,以及其缓存的签名包已被移除、不可读或被篡改的条目。verify 像 pull 一样询问注册表,在应答会记录、替换或清除其签名时报告该条目,并像 pull 一样缓存它验证过的签名包。在离线模式下,此类条目不会被询问,也不会被报告:verify 会打印一行,列出该条目并说明其签名未经检查。

**对于插件信任记录,**每次 pull 都会在注册表处验证挂接在裁决角色上的每个插件的签名,verify 也是如此:若该验证会记录、替换或清除某个条目的签名,则报告该条目;若记录中没有某插件的条目,而构建因其未记录签名而拒绝它,也会报告该插件,因为 pull 会写入一个带有其签名的条目,而在此之前构建会拒绝该插件。记录中尚未持有的其他插件属于首次出现,不会被报告。在离线模式下,verify 不就这些插件询问任何注册表:它像构建一样从内容缓存读取每个插件,并像联网的 verify 一样核对其身份和宿主函数。它无需询问即报告构建因未记录签名而拒绝的插件(其条目未记录签名,或记录中没有它的条目),以及构建因其条目记录的签名是为另一个制品所做而拒绝的插件,因为无论注册表如何应答,pull 都会重写该条目;对于其他每个条目,它会打印一行,列出该条目并说明其签名未经检查。

**弃用标记不参与比较。**在 pull 之后附加到制品上的标记属于注册表的状态,会在工作区内无任何改动的情况下发生变化,因此若 verify 因此失败,就会让一项检查在无人改动的文件上失败。这也是已记录的标记只对构建给出提示而不使其停止的原因。

输出的消息,每个条目一条,列出该条目、文件及其记录的内容、pull 将改为记录的内容,以及使该文件保持最新的 pull。当注册表的应答或记录自身的验证给出了 pull 将记录的签名时:

signing: a recorded signature is not the one a pull would record ("<reference>", <file> records <signature>, a pull would record <signature>). remediation: run aggrega pull --release <release> to bring <file> up to date(签名:已记录的签名与 pull 将记录的签名不一致(该条目所在文件记录了一个签名,而 pull 将记录另一个签名)。修复方法:运行该 pull 命令,使该文件保持最新)

对于在要求签名处未记录签名的条目(锁文件条目,或在离线模式下插件信任记录中的条目):

signing: a recorded signature is not the one a pull would record ("<reference>", <file> records no signature, a pull would ask its registry for the signature a requirement asks for and record it). remediation: run aggrega pull --release <release> to bring <file> up to date(签名:已记录的签名与 pull 将记录的签名不一致(该文件未记录签名,pull 将向其 registry 请求某项要求所需的签名并记录下来)。修复方法:运行该 pull 命令,使该文件保持最新)

对于其记录的签名是为另一个制品所做的条目(锁文件条目,或在离线模式下插件信任记录中的条目):

signing: a recorded signature is not the one a pull would record ("<reference>", <file> records <signature>, made for another artifact, a pull would ask its registry for this artifact’s own signature and record it). remediation: run aggrega pull --release <release> to bring <file> up to date(签名:已记录的签名与 pull 将记录的签名不一致(该文件记录的签名是为另一个制品生成的,pull 将向其 registry 请求该制品自身的签名并记录下来)。修复方法:运行该 pull 命令,使该文件保持最新)

以及对于记录中没有其条目、且构建因其未记录签名而拒绝的插件(第二种形式用于离线模式,此时 verify 不询问任何注册表):

signing: a recorded signature is not the one a pull would record ("<plugin>", <record-path> records no entry for it and a signature is required for it, a pull would record <signature>). remediation: run aggrega pull --release <release> to bring <record-path> up to date(签名:已记录的签名与 pull 将记录的签名不一致(该记录文件中没有该插件的条目,而该插件需要签名,pull 将记录一个签名)。修复方法:运行该 pull 命令,使该记录文件保持最新)

signing: a recorded signature is not the one a pull would record ("<plugin>", <record-path> records no entry for it and a signature is required for it, a pull would ask its registry for the signature a requirement asks for and record it). remediation: run aggrega pull --release <release> to bring <record-path> up to date(签名:已记录的签名与 pull 将记录的签名不一致(该记录文件中没有该插件的条目,而该插件需要签名,pull 将向其 registry 请求某项要求所需的签名并记录下来)。修复方法:运行该 pull 命令,使该记录文件保持最新)

<signature> 以签名的模式、签名者及其签名包的摘要来表述签名,即 a keyed signature by keyed:sha256:<fingerprint> with bundle digest sha256:<digest>,对于无密钥签名,会在签名者之后加上 issued by <issuer>;或者为 no signature。<file> 是 Release 的锁文件 <lockfile-path>,或 Release 目录中的 plugins-trust.yaml,即 <record-path>。

**修复方法:**运行消息中给出的 pull。它会将消息所述的签名写入指明的文件,并缓存其签名包,从而使下一次 verify 通过。当消息说明 pull 将询问注册表时,pull 会记录注册表验证的内容;若注册表附加了信任配置不接受的签名,或在要求签名处未附加签名,pull 则会停止并列出该制品,这需要由其发布者处理。在离线模式下,该 pull 会停止:对于锁文件条目,它会以离线拒绝停止,因为它必须询问注册表;对于挂接在裁决角色上的插件,它会在此之前停止,将该插件的 .wasm 列为无法解析的文件,因为 pull 从插件的注册表解析该 .wasm。为这一次运行允许网络访问即可使文件保持最新。当消息说明 pull 将不记录签名时,说明注册表已不再附加签名,且没有任何设置要求签名:pull 会清除该条目的签名,而构建在相同设置下会接受这一点。如果你未预料到注册表会停止为该制品签名,这同样需要询问其发布者。

A plugin’s .wasm is not on this machine(插件的 wasm 模块不在本机上)

插件的 .wasm 从以下四处之一读取,顺序如下:编译器二进制文件内置的插件、目录目录中该插件 Plugin 实体旁的文件、引用指明的显式文件系统路径,以及由 aggrega pull 填充的工作区内容缓存。解析插件只读取本机上已有的内容,不获取任何内容,因此本条件报告的是四处均未持有这些字节,而不是下载失败。**有一个插件例外:导入所需的核心导入器。**它的模块只从二进制文件或内容缓存读取,从不从目录实体旁读取;若两者均未持有,导入会从工作区的默认注册表获取一次;此时本条件还会报告该获取也无法进行:工作区处于离线状态、其注册表无法访问或未持有该模块,或者工作区未指明默认注册表。已获取但未通过验证的模块会改由其自身的条件拒绝,即摘要不匹配或签名拒绝,且不会保留任何内容。

实体旁的文件以该实体的插件类型和名称命名,下文 pull 的拒绝消息会给出该名称:对于 pipeline-step/patch,它是 pipeline-step--patch.wasm,位于该实体文档所在的目录中。

在你的某个目录目录中编写的 Plugin 实体,会在 pull 解析它时被拒绝。 pull 从不获取此类实体的 .wasm:它只在上述四个位置查找,与构建查找的位置完全相同。pipeline step、provider 或挂接在 verdict 角色上的插件完全不会被固定,构建每次都从目录目录读取其实体。挂接在 transform 角色上的插件会被固定,因为其字节决定渲染输出:pull 记录其实体以及在该处找到的 .wasm 的内容摘要,构建会拒绝不再匹配的 .wasm。因此,在四个位置都找不到制品的 pull 会就此停止,在写入 lockfile 或任何 entity.lock 之前停止,而不是留待构建在加载该插件的步骤中才失败。二进制文件自带的 .wasm,或已在内容缓存中的 wasm 模块,满足 pull 的方式与满足构建的方式完全相同,因此随编译器一同发布的插件,其实体旁边不需要任何文件。

输出的消息。pull 的拒绝消息,指向它期望文件所在的目录,并在其下给出它查询的解析情况:

plugin artifact not found on this machine (Plugin entity "<reference>" is authored in a catalog directory, expected <file> in <directory>). Place the built .wasm beside the entity under that name, or publish the plugin and reference the published Plugin entity instead of the one in the catalog directory(本机上未找到插件制品(该 Plugin 实体编写在目录目录中,预期在所示目录中找到所示文件)。请将构建好的 .wasm 以该名称放在实体旁边,或发布该插件并引用已发布的 Plugin 实体,而不是目录目录中的那个)

对于构建或导入加载、但没有任何来源持有其字节的插件,以及在离线模式下 aggrega pull --verify 像构建一样从内容缓存读取的、挂接在裁决角色上的插件。当该插件的 Plugin 实体位于目录文件夹中时,消息会指出它所处的版本以及其模块应放置的位置:

plugin "<reference>" at version <version> is not on this machine; place its module, named <file>, beside its Plugin entity in <directory>: plugin artifact not found on this machine(该版本的插件不在本机上;请将其模块以所示文件名放在所示目录中其 Plugin 实体的旁边:在本机上找不到插件制品)

其他情况下,消息会指出查找该模块的每一个位置:

plugin "<reference>" is not on this machine: the binary does not carry its module, no catalog folder holds its Plugin entity and the content cache a pull fetches into does not hold it: plugin artifact not found on this machine(该插件不在本机上:二进制文件未携带其模块,没有任何目录文件夹持有其 Plugin 实体,拉取所写入的内容缓存中也没有它:在本机上找不到插件制品)

lint 只在二进制文件中查找,因此只指出上述位置中的第一个。

对于以注册表位置形式编写的引用,情况相同:

plugin "<reference>" not resolvable: an OCI plugin URI requires a prior aggrega pull --release <release> (so its bytes are cached) or an explicit local path; plugin resolution does not fetch from a registry: plugin artifact not found on this machine(该插件无法解析:OCI 插件 URI 需要事先针对该 release 运行 aggrega pull(以便缓存其字节)或提供显式本地路径;插件解析不会从 registry 获取:本机上未找到插件制品)

对于导入既无法读取也无法获取的核心导入器,消息列出该导入器、其版本和原因(此处为工作区处于离线状态),然后说明如何将其模块放到本机上:

core importer "<importer>" at version <version> is not on this machine, and the workspace is offline, so its registry <host> is not asked for it; run the import once with the network available, which fetches it from the workspace’s default registry, verifies it and keeps it in the content cache for every later import, or place its module, named <file>, beside a Plugin entity of <importer> at <version> in a catalog folder: plugin artifact not found on this machine(该版本的核心导入器不在本机上,且工作区处于离线状态,因此不会向其 registry 请求它;请在网络可用时运行一次导入,这会从工作区的默认 registry 获取它、验证它,并将其保存在内容缓存中供之后的每次导入使用;或者将其模块以所示文件名放在目录文件夹中该导入器该版本的 Plugin 实体旁边:本机上未找到插件制品)

其他原因为 its registry <host> could not be reached (<cause>)、its registry <host> holds no <location>:<version> 和 the workspace names no default registry to fetch it from;后两者只给出第二种补救措施,因为在网络可用时运行并不会改变它们。

**修复方法:**若该实体由你编写,请构建插件,并将其 .wasm 以消息给出的名称放在实体旁;或者使用 aggrega push 发布该插件,并引用已发布的实体来代替目录中的副本,因为 pull 和构建都不会获取你目录中实体的 .wasm。若该插件是你从注册表使用的,请为该 release 运行 aggrega pull,它会缓存该插件。若你期望编译器自身携带该插件,请检查你运行的二进制文件是否携带:aggrega plugin list 会列出内置的插件。若它是核心导入器,请在工作区能访问其默认注册表的环境中运行一次导入,这次运行会获取、验证并缓存它,之后的每次导入都可离线进行;或者,若该注册表未持有它,请将其模块以消息给出的名称放在目录文件夹中该导入器对应版本的 Plugin 实体旁;之后该实体将代替核心导入器运行。

A plugin recorded as a trusted gate is no longer attached(记录为受信任门禁的插件已不再挂接)

对构建返回接受或拒绝判定的插件在解析后会被记录下来,因此工作区保存着一份记录,说明哪些门禁经过了审查。当某个已记录的门禁不再被任何配置挂接时,报告的就是此条件。它之所以中止构建而不是静默通过,是因为否则其输出将与该门禁批准过的输出无法区分:门禁被悄然移除的构建与门禁放行的构建会产生相同的文件,审查结果的人无法判断手中拿到的是哪一种。

这与插件字节发生漂移是不同的问题。那种情况拒绝运行一个并非已审查版本的插件——这是身份问题。这里拒绝在已审查门禁完全缺失的情况下进行构建——这是存在问题。相应的补救办法也不同:前者恢复制品,后者恢复挂接。

它能确认什么,不能确认什么。 让配置与记录保持一致,可以确认每个已记录的门禁仍然挂接,且每个门禁的制品都是记录中的那个。但它无法确认已挂接的门禁是否真的返回判定:如果某个挂接的入口函数指向一个已声明但不返回判定的导出,它会运行、不报告任何内容并放行构建,而与记录的任何比对都不会察觉——运行的插件正是记录中的那个,只是它什么也没执行。有两种相邻的情况确实会中止构建,在此点明,以免这一界限被理解得比实际更宽:入口函数指向插件未声明的导出时,会在插件加载时被拒绝;输出中带有判定结构未声明的键时,会被拒绝,而不会被当作空的判定列表读取。

发出的消息,指明记录、被移除的门禁以及两种补救办法:

a plugin recorded as trusted for an accept-or-reject verdict is no longer attached at any verdict role: <record-path> records <plugin> as trusted, but no verdict attachment in the workspace configuration names it; a gate that was reviewed and is now absent leaves output indistinguishable from output that gate approved. Attach the plugin again under plugins.governance at an ir-verdict or render-verdict role, or under plugins.linter; or, if it was meant to go, run aggrega pull --upgrade --release <release> <plugin> to drop it from the record — an ordinary aggrega pull leaves the record as it is, so only an explicit upgrade removes an entry(一个被记录为可信、用于给出接受或拒绝裁决的插件已不再挂接在任何裁决角色上:该记录文件将此插件记录为可信,但工作区配置中没有任何裁决挂接指向它;一个经过审查、如今缺失的关卡,会使输出与该关卡批准的输出无从区分。请在 plugins.governance 下以 ir-verdict 或 render-verdict 角色重新挂接该插件,或挂接在 plugins.linter 下;或者,如果本就打算移除它,请运行上述定向升级命令将其从记录中删除——普通的 pull 会保持记录不变,因此只有显式升级才会删除条目)

如果移除了多个门禁,它们会在同一条升级命令中一并列出,而不是每个一条命令:定向升级可以接受多个目标,并保持所有未指明的固定版本不变,因此一并列出既更简短,范围也比另一种做法所需的完全刷新更窄。

如何修复: 消息给出两种补救办法,因为只有你知道哪一种适用。如果门禁是被误删的,请在 plugins.governance 下以判定角色重新挂接该插件,或在 plugins.linter 下挂接。如果本意就是移除它,请使用消息中给出的定向升级明确表明这一点,正是它会删除该条目。不要为消除此错误而编辑或删除记录——它是已提交的审查记录,普通的 pull 会有意保持其不变,因为静默接受移除正是此拒绝要防止的情况。

A gate recorded as trusted resolves to a different identity(记录为受信任的门禁解析到了不同的身份)

对构建返回接受或拒绝判定的插件在解析后会被记录下来,同时记录它解析到的版本和制品摘要。当后续解析对记录中已有的门禁得到不同的版本或不同的字节,而本次运行并未要求采用该身份时,报告的就是此条件。

版本变动和字节变动由同一个条件涵盖,因为记录以插件的身份为键,并将版本和摘要作为同一条目的字段:将解析结果与之比对是一次比对,只有一个结果。对审查者而言,未改变字节的重新发布与同一版本的重新推送是同一件事——身份已不再是经过审查的那个。

这与已记录的门禁不再被任何配置挂接是不同的问题,后者是存在问题而非身份问题。它也不同于插件缓存的字节与记录的摘要不一致:那种情况拒绝运行并非已审查版本的插件,补救办法是恢复或重新记录制品;而这里拒绝在未被要求时采用新身份,补救办法是在升级中指明该插件。两种补救办法,两个条件。

要求采用新身份正是 pull 已经提供的功能,有两种方式。 完全刷新会重新解析所有内容,定向升级会重新解析其指明的插件;两者都被视为已要求采用新身份,记录随之更新。其他任何 pull 都会保持已记录的身份并停止,这正是记录它的意义所在——如果记录接受下一次解析到的任何结果,它就只是跟随解析,而不是约束解析。首次出现并不构成不一致:记录中尚未保存的身份会被直接填入。

比对也会在仅做验证的 pull 上运行,这种 pull 既不写入记录也不写入 lockfile。如果验证在检查旁边的 lockfile 时跳过记录,就会报告一个它从未核查过的一致结果。

发出的消息,指明插件、两个身份以及两种补救办法:

plugin "<plugin-identity>": <record-path> records version <recorded-version> with digest <recorded-digest> as trusted for it, but this resolution reports version <resolved-version> with digest <resolved-digest>; review what changed and adopt it with aggrega pull --upgrade --release <release> <plugin>, or restore the recorded identity: the plugin identity recorded as trusted no longer matches what this resolution reports(插件:记录文件将某个版本及其摘要记录为该插件的可信身份,但本次解析报告的是另一个版本及摘要;请审查变更内容,并使用上述定向升级命令采用它,或恢复所记录的身份:被记录为可信的插件身份与本次解析报告的结果不再一致)

如何修复: 判断两个身份中哪一个是你想要的,因为只有你能做出判断。如果这一变动是你有意为之——门禁已重新发布且你已审查了变更内容——请使用消息中给出的定向升级采用它,这会重新解析该插件并重写其条目。如果你并未预料到它,那么已记录的身份才是经过审查的那个:请恢复记录中指明的版本或制品,并调查引用为何现在解析到了别处。不要为消除此错误而编辑记录——它是已提交的审查声明,普通的 pull 会有意保持其不变,因为静默采用已变更的门禁正是此拒绝要防止的情况。

Plugin 实体的声明与插件自身的自我报告不一致

Plugin 实体声明它所指向的插件提供什么:有哪些导出、每个导出作用于什么以及在什么范围内,以及(对于为 provider 服务的插件)渲染时的行为。插件在加载时也会报告关于自身的同样内容。两者不一致时报告此情况。

比较按导出逐一进行,以名称为键,并且是单向的:**实体声明的一切都必须匹配,而插件可以提供更多。**只描述插件部分接口的实体无需列举其余部分,因此插件声明而实体省略的导出不算不一致。不一致是指:声明的导出插件并未声明,或声明的导出其 operates 或 scope 与插件报告的不同。自由格式的 selector 不参与比较。

如果实体还编写了渲染行为块,则逐个比较其字段:输入种类、组装模式、artifact 模板定界符对、组装名称注解、可复用实例声明、跨边界链接声明、省略条目声明以及嵌套目录;报告第一个不一致的字段。未编写此类块的实体完全跳过这项比较。

同样的检查也在发布时运行,因此不匹配通常会在实体发布之前暴露,而不是在构建加载它时。

发出的消息。插件没有的声明导出:

entity "<entity>" claims export "<export>", which the plugin’s describe() does not declare: wasm: entity contract claim does not match plugin describe()(实体声明了一个导出,但插件的 describe() 并未声明该导出:wasm:实体契约声明与插件 describe() 不匹配)

声明导出上的某个字段:

entity "<entity>" export "<export>" declares operates "<claimed>" but the plugin’s describe() reports "<reported>": wasm: entity contract claim does not match plugin describe()(实体的某个导出声明的 operates 与插件 describe() 报告的值不同:wasm:实体契约声明与插件 describe() 不匹配)

以及渲染行为字段,其报告形式相同,并指出不一致的字段:

entity "<entity>" declares boundary_assembly "<claimed>" but the plugin’s describe() reports "<reported>": wasm: entity contract claim does not match plugin describe()(实体声明的 boundary_assembly 与插件 describe() 报告的值不同:wasm:实体契约声明与插件 describe() 不匹配)

**如何修复:**需要更正的是 Plugin 实体的声明,而不是你的 Aggregate 或 Release。使声明与插件报告的内容一致:消息会给出两个值,因此应朝哪个方向修改在消息中一目了然。如果实体由你发布,从二进制文件重新生成它是使两者一致的可靠方法;如果你使用的是已发布的实体,请选择声明与其所指二进制文件匹配的版本,并将不一致报告给其发布者。

Plugin 实体记录的命令集与插件不匹配

提供终端命令的插件,其命令记录在它的 Plugin 实体中。该记录由机器写入而非人工编写:它从插件中读出并写下,因此精确反映二进制文件。记录不再反映二进制文件时报告此情况,即命令名称、简短帮助文本或命令声明顺序存在差异。

**比较要求完全相等,这是有意为之。**实体上其他位置的能力声明和导出声明是人工整理的:作者可以合理地只描述部分接口而省略其余部分,因此这些按子集检查。命令记录不是人工整理的,因此任何不完全一致都意味着记录已偏离插件实际提供的内容,而接近但不正确的命令列表正是会导致调用路由错误的原因。

**不带实体加载的插件不在此检查。**记录存放在实体上,因此直接加载的字节不带记录,比较没有可对照的对象。

发出的消息,指出两个命令集以及如何重新记录它们:

wasm: plugin "<plugin>": recorded command mirror <recorded set> does not match the plugin describe() commands <reported set>; re-run aggrega plugin sync and commit the result: wasm: recorded command mirror does not match plugin describe()(wasm:插件记录的命令镜像与插件 describe() 的命令不匹配;请重新运行 sync 命令并提交结果:wasm:记录的命令镜像与插件 describe() 不匹配)

发布时的同一比较会报告两个命令集,但不附带重新记录的说明:

plugin "<plugin>": recorded command mirror <recorded set> does not match the plugin describe() commands <reported set>: wasm: recorded command mirror does not match plugin describe()(插件记录的命令镜像与插件 describe() 的命令不匹配:wasm:记录的命令镜像与插件 describe() 不匹配)

**如何修复:**从二进制文件重新记录命令集并提交结果,消息中给出了执行此操作的命令。不要手动编辑记录使其匹配:记录归机器所有,今天恰好一致的手动编辑会在下次记录时被重新推导并覆盖。如果你使用而非发布该已发布实体,说明该实体发布时所带的记录不受其自身二进制文件支持,这需要由其发布者处理。

Plugin 实体记录的版本与插件不匹配

插件会报告其构建时记录在其中的版本,其 Plugin 实体也记录了一个版本;两者必须是相同的字符串。构建 Aggrega 插件所用的构建配方从发布该插件的标签获取版本:随编译器发布的插件使用编译器自身的标签,独立于编译器发布的插件使用插件自己的标签。因此,构建标签所指的提交会报告发布版本,构建其他任何提交则报告开发版本,例如 1.0.0-3-g1a2b3c4。两者分离时报告此情况,并且在发布任何字节之前进行检查,使不一致的组合不会进入目录。

比较是精确的字符串匹配。构建时未记录版本的插件报告空版本,实体的版本也必须等于该空值:检查不会把“未报告版本”视为“接受任何版本”,因为其目的在于使已发布实体的版本始终表明其二进制文件实际报告的内容。

发出的消息:

plugin "<plugin>": recorded metadata.version "<recorded>" does not match the plugin describe() version "<reported>": wasm: entity metadata.version does not match plugin describe()(插件记录的 metadata.version 与插件 describe() 报告的版本不匹配:wasm:实体 metadata.version 与插件 describe() 不匹配)

在发布时,拒绝信息还会指出实体文件、.wasm 以及修复方法:

Plugin <plugin>: metadata.version in <entity-path> does not match the .wasm describe() version at <path> — set metadata.version to the release you are publishing and build the plugin from a clean checkout of the commit that release’s tag names, so it reports that version itself; for a new release, commit the entity with the source it releases and tag that commit first: plugin "<plugin>": recorded metadata.version "<recorded>" does not match the plugin describe() version "<reported>": wasm: entity metadata.version does not match plugin describe()(实体文件中的 metadata.version 与 .wasm 的 describe() 版本不匹配——请将 metadata.version 设为你要发布的版本,并从该版本标签所指提交的干净检出构建插件,使其自身报告该版本;对于新版本,请先将实体与其发布的源码一并提交,并为该提交打标签:插件记录的 metadata.version 与插件 describe() 报告的版本不匹配:wasm:实体 metadata.version 与插件 describe() 不匹配)

**如何修复:**将实体的 metadata.version 设为你要发布的版本,并从该版本标签所指提交的干净检出构建插件,使其自身报告该版本。对于新版本,请先将实体与其发布的源代码一起提交并为该提交打标签:标签必须指向已包含该实体的提交。不要把插件报告的版本复制到实体中:构建其他任何提交都会报告开发版本,复制它会使该构建以一个没有任何发布标签对应的版本发布。如果插件完全不报告版本,说明它构建时未记录版本;请在记录版本的情况下构建它。

A plugin was built from a working tree with uncommitted changes(插件是从带有未提交更改的工作树构建的)

插件的构建会根据其所基于的提交记录版本,而从带有未提交更改的工作树进行的构建会在该版本末尾带上 -dirty 标记:位于标签处时为 1.0.0-dirty,越过标签时为 1.0.0-3-g1a2b3c4-dirty。这样的版本是有效的语义化版本,但它指向的提交并不包含实际构建出的字节,因此任何人都无法依据它将要发布时所用的版本重新构建出将要发布的内容。发布 Plugin 时,如果插件自身的版本带有该标记,会被拒绝,拒绝发生在发布任何字节之前,也在联系注册表之前;试运行(dry run)同样会拒绝。

只有该标记会被拒绝。从某个提交构建出的开发版本(例如 1.0.0-3-g1a2b3c4)指向的提交确实包含所构建的内容,可以发布;预发布版本(例如 1.0.0-rc.1)也可以。在发布之外根据实体验证插件不会触发此条件,因为开发中的构建通常就是从已编辑的工作树进行的。

该检查读取插件关于自身构建所报告的版本,并在与实体的 metadata.version 比较之前运行,因此,如果插件带有未提交更改构建,而实体记录的是干净版本,就会在此处报告,而不是报告为记录的版本与插件不匹配。

发出的消息,指明插件、其报告的版本以及补救方法:

Plugin <plugin>: the .wasm at <path> was built from a working tree with uncommitted changes — set metadata.version in <entity-path> to the release you are publishing and build the plugin from a clean checkout of the commit that release’s tag names, so it reports that version itself; for a new release, commit the entity with the source it releases and tag that commit first: plugin was built from a working tree with uncommitted changes, so no commit reproduces the version it reports (plugin "<plugin>", describe() version "<version>", which ends with "-dirty")(该 Plugin 位于所示路径的 .wasm 是从含有未提交更改的工作树构建的——请将实体文件中的 metadata.version 设为你要发布的 release,并从该 release 的标签所指提交的干净检出构建插件,使其自身报告该版本;对于新的 release,请先将实体与其发布的源码一同提交,并为该提交打标签:插件是从含有未提交更改的工作树构建的,因此没有任何提交能复现它报告的版本(其 describe() 版本以 -dirty 结尾))

**修复方法:**从该版本标签所指提交的干净检出构建插件,使其报告实体所记录的发布版本。若要发布该更改本身,请将实体的 metadata.version 设置为新版本,将实体与更改一起提交,为该提交打标签,然后在那里构建。仅提交更改并重新构建并不能为发布扫清障碍:重新构建的插件报告的是开发版本,而把它复制到实体中会以一个没有任何发布标签指向的版本发布该构建。

A Plugin entity’s recorded host functions do not match the binary(Plugin 实体记录的宿主函数与二进制文件不匹配)

插件会声明它使用宿主自身的哪些调用,该集合在插件发布时记录在其 Plugin 实体上,它是从二进制文件本身读出的,而不是编写的。获取插件时,会根据刚刚完成内容验证的字节重新推导该集合,并与记录进行比较。任一方向上的差异都会停止获取。

此检查叠加在内容固定之上,而不是重复它,它能捕获仅靠固定无法发现的两种情况:通过常规发布路径以外的方式发布的二进制文件,它不带记录,或带有不描述其自身字节的记录;以及记录步骤本身的故障。固定确认这些字节就是被固定的字节;此检查确认关于它们所记录的内容对它们是真实的。

不带记录的实体会与空集比较,这与不使用任何宿主调用的插件相匹配——无论从哪个方向看都是同样无害的一致,因此不带记录的实体不会因缺少记录而被拒绝。

发出的消息,指明插件、两个集合以及字节来源的制品:

plugin "<plugin>": stamped spec.runtime.hostFunctions <recorded set> does not match <derived set> derived from the verified .wasm <artifact>: wasm: stamped host-function record does not match .wasm imports(插件上标记的 spec.runtime.hostFunctions 记录集合与从已验证的 .wasm 制品推导出的集合不一致:wasm:标记的宿主函数记录与 .wasm 导入不一致)

在验证插件时运行的同一比较会报告两个集合,但不包含制品:

plugin "<plugin>": recorded host-function record <recorded set> does not match the .wasm imports <derived set>: wasm: stamped host-function record does not match .wasm imports(插件记录的宿主函数集合与 .wasm 的导入集合不一致:wasm:标记的宿主函数记录与 .wasm 导入不一致)

**修复方法:**这不是你的实体文件导致的,任何编写上的更改都无法消除它。请通过常规发布路径重新发布插件,该路径会从二进制文件推导记录,并将二者一起写入。如果你使用的是已发布的插件,说明实体与其指向的二进制文件发布时不同步,请将不匹配报告给其发布者,并引用消息中的两个集合;不要手动编辑记录使其一致,因为它是推导出来的而非编写的,下一次推导会丢弃该编辑。

The lockfile no longer matches what the release resolves to(lockfile 不再与 release 解析出的结果一致)

release 的 lockfile 固定该 release 所触及的每个实体、库和插件,每项都带有所选版本和摘要;它还按内容摘要记录 release 文件本身——即该 release 及其扩展的每个 release。实体的摘要涵盖其发布所携带的内容:其文档以及它在旁边指名的每个文件,每个文件按路径和字节计算。库和插件的摘要涵盖其字节。再次解析该 release 会产生同一组结果,然后对两者进行比较。此条件报告的就是两者不一致的情况。

在报告任何不一致之前,会先收集所有不一致,范围涵盖 lockfile 固定的全部内容,因此一次运行就能告诉你完整情况,而不是一次只报告一个条目。

会报告以下几种不一致,值得加以区分,因为补救方法各不相同:

  • lockfile 未固定的引用。 release 现在触及了 lockfile 中没有条目的内容——即在写入该 lockfile 的那次 pull 之后添加的依赖。条目会指出 release 在何处请求它,因此 Manifest 绑定的 Recipe 或 FeatureRecipe 会连同绑定它的映射条目一起报告,而由 name 层级绑定的则会指出为其选择它的实例或附件。
  • 版本与摘要对发生变化的已固定引用。 lockfile 固定了一个版本与摘要对,而解析产生了另一个。这意味着 vendored 内容的字节发生了变化,或者工作区中的某些内容发生了变化:实体或库的文档被编辑;实体指名的某个文件——其 source 下的 chart、它导入的文件、它旁边的 entity.lock——被编辑、添加或删除;或者插件实体旁边的 .wasm 被替换。条目指出的是实体而不是文件;普通的 aggrega pull --release <release> 会指出在 Recipe 或 FeatureRecipe 的 lock 下发生变化的文件,如 An entity reads an input the lock beside it records no pin for(实体读取了其旁边的 lock 未记录固定的输入) 所述。registry 在已固定的版本下提供其他字节的情况不在此报告:获取这些字节的 pull 会拒绝它们,如 Fetched or cached bytes do not match the digest committed for them(获取或缓存的字节与为其提交的摘要不匹配) 所述。
  • release 不再触及的已固定引用。 lockfile 仍固定着 release 中已不再有任何内容依赖的某项。
  • 自 pull 以来被编辑过的 release 文件。 该 release 或它扩展的某个 release 不再包含 lockfile 为其记录的字节。release 请求的一切——获取哪个 source 版本、将哪些组件放在何处——都根据该文件的内容解析,因此记录的固定项可能已不再描述它现在的请求。此情况在任何渲染之前于此处报告,而不是以渲染本会失败的原因报告:否则,被编辑的 source 版本会在稍后表现为一次找不到固定项的获取。完全没有记录 release 文件的 lockfile 会将该 release 报告为未记录,而 release 不再扩展的 release 文件会被报告为不再读取。
  • 在远端发生变化的 source 引用。 以 git ref: 写出的 source 会按该 ref 解析到的提交记录。每次非升级的 pull 都会询问远端该 ref 现在指向何处,在可访问网络时 aggrega pull --verify 也会这样做;解析到不同提交的 ref 会在此报告,而不会被采用。只有这两者会报告它:构建读取记录的提交,不会询问。

比较基于内容,因此通过不同途径获得的相同内容不会产生漂移:要触发此条件,必须是字节不同。对于 release 文件,这包括注释或空白的改动,与该 release 指名的 Aggregate 和 Manifest 完全相同。对于实体,比较的是其所携带内容的内容,因此从 catalog 目录读取的同一实体与从 registry 获取的同一实体不会产生漂移;文件仅在权限位(包括执行位)上不同的检出,以及归档压缩方式不同的发布,也都不会产生漂移。

输出的消息。消息以该条件自身的句子开头,随后是收集到的每一处不一致,每一处都指明其轴——对于实体,还指明其种类,因为实体由其种类和 URI 共同标识,所以 Aggregate 与 Manifest 同名的 Release 会有两个条目,对其中任一个的编辑都会针对被编辑的那一个报告:

lockfile: out of date; it no longer matches what its Release resolves to: entity "<uri>" (<kind>) not in lockfile (referenced from <site>)(lockfile:已过期;它不再与其 Release 解析出的结果一致:实体(及其种类)不在 lockfile 中,并附有引用它的位置) <axis> "<uri>" changed: lockfile=(<version>,<digest>) current=(<version>,<digest>)(所示轴上的所示引用已更改:lockfile 中的版本和摘要与当前的不同) entity "<uri>" (<kind>) changed: lockfile=(<version>,<digest>) current=(<version>,<digest>)(所示种类的所示实体已更改:lockfile 中的版本和摘要与当前的不同) <axis> "<uri>" no longer used by the release(所示轴上的所示引用不再被该发布使用) release document "<file>" was edited after the lockfile was written: its content no longer matches the recorded digest (lockfile=<digest> current=<digest>), so the pins may no longer describe what it asks for; re-resolving the Release records the files it reads as they now stand(所示发布文档在写入 lockfile 之后被编辑过:其内容不再与记录的摘要一致,因此这些 pin 可能不再描述它所请求的内容;重新解析该 Release 会按文件当前的状态记录它读取的文件)

<site> 是 release 请求该引用的位置,写作指向指名它的条目的路径——例如 manifest.spec.mappings.components.name.db-primary——最多按排序列出三个这样的位置,更多时在其后加 ...。解析未记录此类位置的引用在报告时不带括号部分。

报告 source 引用发生变化的 pull 会按作者所写的方式指出该制品,在 source 指名时带上 chart= 和 module_subdir=:

source-artifact kind=<kind> url=<url>: reference "<ref>" moved — the lockfile pins <commit>, and it now resolves to <commit>; adopt where it now points with aggrega pull --upgrade --release <release>

构建会在条目之后打印补救方法:

run aggrega pull --release <release> to re-resolve the Release and rewrite its lockfile

哪些命令会让发布受其 lockfile 约束。 aggrega build 在渲染之前进行比较并中止。aggrega validate --release,以及每个解析发布的 aggrega inspect 选择——默认视图、--resolved、--ir-graph 和 --closure——会在发布的依赖解析完成后立即运行同样的比较,并以相同的消息和修复建议中止,不向标准输出写入任何内容;因此两者都不会放过构建以漂移为由拒绝的 lockfile。助手工具中的 build、带 release 的 validate 以及带 release 的 describe 也按同样的条件拒绝。aggrega pull 针对它即将写入的 lockfile 运行该比较,aggrega pull --verify 则针对磁盘上的 lockfile 运行。不解析任何发布的命令——不带参数(此时它读取 lockfile 的 pin 仅用于查找 extends 父级)或带实体路径的 aggrega validate,以及不带 --ir-graph 的 aggrega inspect --raw 或 --output yaml——不受 lockfile 约束,旁边没有 lockfile 的发布也不受约束。编辑器的语言服务器会因此中止其构建,并在图请求中将其作为 lockfile 上的警告报告,同时仍然绘制该图。

如何修复: 重新解析 release 并提交重写后的 lockfile。对于构建报告的所有情况,一次普通的 aggrega pull --release <release>——即构建打印的命令——就是完整的修复:它按 release 的当前状态解析,重写发生变化的固定项并保留其余所有固定项,因此你未改动的内容都不会浮动。如果发生变化的是 Recipe 或 FeatureRecipe 本地 source 下的文件,该 pull 会先停止,并为该实体指出 aggrega pin,因为在其旁边记录新的固定项是作者的步骤;运行它,或向 pull 传入 --pin-sources,pull 即可清除漂移。普通 pull 唯一不能清除的条目是在远端发生变化的 source 引用,因为清除它意味着采用该引用当前指向的提交:aggrega pull --upgrade --release <release> 会这样做,条目也会说明这一点——如果 Recipe 的 entity.lock 记录了该 source,升级同样会停止,直到新提交在其旁边被固定。执行之前请先阅读这些条目,因为第三种情况值得停下来想一想:release 不再触及的引用通常是你有意移除的依赖,但如果不是你移除的,那就是其他某些变化使其无法触及。在你未改动的引用上发生变化的版本与摘要对,意味着该版本的内容不是经过审查的内容,这应当去问提供它的人,而不是不加查看就采用。

pull 会针对即将写入的 lockfile 运行同样的比较,并且不会写入比较所拒绝的 lockfile,因此对于给定相同输入的构建,pull 刚写入的 lockfile 能够通过比较。如果在一次已完成的 pull 之后立即再次出现此条件,说明两次运行被给定了不同的输入:某个 catalog 目录只传给了其中一次,或者两次之间编辑了工作区配置。请在相同的输入上运行 pull 和构建。

An artifact is not at the source the build was told to find it(制品不在构建被告知的来源处)

目录引用指定一个制品和一个版本。此条件报告没有任何东西对应该组合——无论是在该引用解析到的 registry 中,还是在构建读取的本地制品缓存中。

构建读取缓存;它不会自行访问外部。 获取是一个独立步骤:解析 release 的 pull 会获取该 release 所需的内容并写入缓存,随后构建读取缓存中已有的内容。因此,此条件对构建而言表现为缓存未命中,对 pull 而言表现为 registry 中没有该制品。如果构建被配置为在启动时填充其 lockfile,它所执行的获取就是同一个 pull。

输出的消息。registry 中没有该 tag,以及获取时解析到的 manifest 缺少其内容 blob:

oci: "<reference>:<version>": oci: artifact not found at remote source(在远程来源中未找到制品)

oci: content for "<reference>:<version>": oci: artifact not found at remote source(在远程来源中未找到制品)

缓存读取未找到条目,这是构建遇到的形式:

oci: cache miss for <reference>@<version>: oci: artifact not found at remote source(在远程来源中未找到制品)

以及已缓存制品旁缺少其 manifest 时的相同情形:

oci: manifest cache miss for <reference>@<version>: oci: artifact not found at remote source(在远程来源中未找到制品)

如何修复: 先检查引用和版本——已不存在的版本与拼写错误的名称会产生相同的结果,消息会同时引用两者,以便与目录对照。如果引用正确,说明该制品尚未被获取:为该 release 运行 pull,它会获取该 release 所涉及的内容并填充缓存。如果工作区处于离线状态,该 pull 必须在能访问网络的地方运行;离线构建只读取已缓存的内容,当缓存中没有所需内容时,就会报告此条件。

The registry will not serve an artifact without credentials it accepts(没有其接受的凭据,registry 不会提供制品)

registry 作出了响应,但拒绝了请求:要么未提供凭据,要么提供的凭据未被接受。这与根本无法访问的 registry 不同——此处通信已经发生,而答复是拒绝。

有四个时刻会报告此条件,均发生在获取或发布制品期间:解析引用、拉取其内容、列出仓库所含的版本,以及在存储凭据时校验该凭据。

输出的消息,每条都指明所请求的内容并引用 registry 的答复:

oci: resolve "<reference>:<version>": <what the registry replied>: oci: authentication required or failed(需要身份验证或身份验证失败)

列出仓库的版本时,改为指明状态码:

oci: tags/list "<repository>": status <code>: oci: authentication required or failed(需要身份验证或身份验证失败)

以及在存储凭据时校验该凭据:

oci: verify credential for "<host>": <what the registry replied>: oci: authentication required or failed(需要身份验证或身份验证失败)

如果该失败由提供修复建议的步骤报告,该行末尾会给出针对其推导出的主机所要执行的登录命令:

remediation: aggrega login <host> (or docker login <host>) before re-running aggrega pull —release <release>(修复建议:在重新运行 aggrega pull —release 之前,对所示主机执行 aggrega login(或 docker login))

以及,当导入正在获取编译器的某个核心导入器时,在重新运行导入之前执行同样的登录:

remediation: aggrega login <host> (or docker login <host>) before re-running the import(修复建议:在重新运行导入之前执行 aggrega login(或 docker login))

通过 http 或 https 获取的经典 Helm chart 仓库或 chart 归档、compose 片段以及 Git 仓库,在服务器以未授权为由拒绝请求时也会报告此情况,而它们的补救措施指明的是要添加的 netrc 条目而非登录,因为这些获取正是从该文件读取凭据的:

remediation: add an entry for <host> (machine <host> login <user> password <secret>) to the netrc file <path>, then run the command again(补救措施:在 netrc 文件中为该主机添加一个条目(包含 machine、login 和 password),然后重新运行该命令)

如何修复: 这是运维人员的问题,而非实体作者的问题——Aggregate、Component 或 Recipe 中的任何内容都不会导致它。官方 hub hub.aggrega.ai 向任何人提供其发布的内容,因此从中读取无需凭据,而向其发布则需要;其他 registry 可能在读取时也要求凭据。登录消息中指明的主机——或者,对于通过 http 或 https 获取的源,添加补救措施中指明的 netrc 条目——然后重新执行获取。如果你已经登录,说明凭据存储中的凭据不被该主机接受用于该仓库:重新登录以刷新凭据,并检查该账户是否对引用解析到的仓库具有读取权限,因为私有仓库对无权查看它的账户的答复正是如此。如果引用解析到了你未预期的主机,说明 .aggrega-config.yaml 中的 registry 别名或默认 registry 指向了别处。

The netrc file cannot be read(无法读取 netrc 文件)

经典的 Helm chart 仓库或 chart 归档、compose 片段,以及通过 http 或 https 获取的 Git 仓库,都从 netrc 文件获取凭据,该文件在获取此类来源时读取——由拉取、固定,或填充锁文件的构建读取。读取哪个文件、由哪个条目响应请求,见 Authentication。此条件报告的是一个存在但无法使用的 netrc 文件:它无法读取——例如它是一个目录,或你没有读取权限——或者它不符合 netrc 格式。格式会被严格读取,因为一个读错位置的单词会使其后的每个单词错位:拼错的关键字会把其后的密码变成下一个关键字,请求就会在不带凭据或带着错误凭据的情况下发出,而文件看起来却没有问题。

不存在的文件不属于此条件:它不持有任何凭据,需要凭据的请求会由服务器的拒绝来回应。本机其他用户可以读取的文件也不属于此条件:在 Linux 和 macOS 上,它会引发一条指出该文件的警告,但仍会被读取。

消息会指出该文件,对于格式错误还会指出行号,并且只用格式本身的术语说明问题——绝不引用文件中的任何单词,因为放错位置的单词可能是密码。该诊断不带类别:netrc 文件是你自己的凭据文件,而不是构建所读取的文档。

针对格式错误输出的消息,格式错误包括:应为关键字的位置出现了一个单词;关键字后面没有跟随其值;login、password 或 account 出现在任何 machine 或 default 条目之前;以及带引号的单词未在其开始的那一行闭合:

the netrc file could not be read (file <path>, line <line>, a word stands where a keyword is expected (machine, default, login, password, account or macdef)). Correct the file, or set NETRC to the path of another netrc file to read instead(无法读取 netrc 文件(所示文件和行:应为关键字(machine、default、login、password、account 或 macdef)的位置出现了一个单词)。请修正该文件,或将 NETRC 设置为另一个要读取的 netrc 文件的路径)

以及针对无法读取的文件,并引述原因:

the netrc file could not be read (file <path>, <why it could not be read>). Correct the file, or set NETRC to the path of another netrc file to read instead(无法读取 netrc 文件(所示文件及无法读取的原因)。请修正该文件,或将 NETRC 设置为另一个要读取的 netrc 文件的路径)

**如何修复:**打开消息中指出的文件。对于格式错误,转到它指出的那一行:每个条目都是 machine <host>——或 default——后跟 login <user> 和 password <secret>,拼错的关键字或缺少值的关键字是常见原因。对于无法读取的文件,使其成为你可以读取、且只有你自己可读的文件(chmod 600)。如果该文件不是你想要读取的那个,请将 NETRC 设置为你想要的文件的路径。

The registry could not be reached(无法访问 registry)

与 registry 的通信从未发生:名称解析、连接或安全握手失败。它与作出响应但拒绝请求的 registry 相对应——此处无论哪种情况都未建立任何连接,因此远端制品的状态是未知的,而不是已知缺失。

在获取 Recipe 的来源期间,没有更具体原因的传输失败也会报告此条件,因此它是该路径上通用的“无法访问远端”答复,而不是关于哪一层失败的论断。

输出的消息,指明正在获取的来源并引用底层传输失败,附带该条件所给出的修复建议:

sourceresolver: kind=<kind> url=<url> version=<version>: oci: network unreachable (cause: <the transport failure>); remediation: check network connectivity to <host>; corporate proxies typically need HTTPS_PROXY exported(网络不可达;修复建议:检查到该主机的网络连接;企业代理通常需要导出 HTTPS_PROXY)

如何修复: 修复由运维人员负责,且不在你的目录范围内。检查消息中的主机能否从运行命令的位置访问。如果环境通过代理访问网络,必须将代理导出到环境中,修复建议中已指明这一点——仅为浏览器或包管理器配置的代理不会被采用。如果手动可以访问该主机但从此处不行,差异通常在于代理处的凭据,或握手未接受的拦截证书。制品缓存之后,后续构建会读取缓存,完全不需要网络。

A server did not answer in time (服务器未及时应答)

请求一直在等待其所指向的服务器——注册中心,或命令访问的任何其他服务器,例如记录签名的透明日志——随后被撤回。请求完整发出后,最多等待 30 秒让服务器开始应答;对于已在到达中的应答,最多等待 30 秒接收其下一部分;超过其中任一时限,请求即以此条件被拒绝,并指明服务器和等待时长。接受连接却从不应答的服务器会产生这一结果,从不接受连接的地址也会产生这一结果,而不是让命令无限等待。遍历注册中心整个仓库列表的操作则在每一页上等待,最长可达遍历允许运行的时长,并由其自己的条件 E0377 加以限制。

受限的只有等待。持续传输的下载或上传需要多久就花多久,因为只有在没有任何数据到达时才计算等待时间。Recipe 的 source: 通过 HTTPS 获取的 Helm chart 只受应答开始前的等待时限约束,这一超时会以网络库自己的措辞报告,而不是以此条件报告。命令在超时后本就会重新发出的请求——aggrega registry update 期间的读取、发布期间的写入——会先被重新发出,因此拒绝是其最后一次尝试之后剩下的结果。

注册中心未应答版本列表请求时发出的消息:

aggrega plugin add: 127.0.0.1:18471: list versions for plugin/cli/mo: oci: list tags: Get “http://127.0.0.1:18471/v2/plugin/cli/mo/tags/list”: 127.0.0.1:18471 did not answer within 30s: egress: the server did not answer in time (aggrega plugin add: 127.0.0.1:18471: 列出 plugin/cli/mo 的版本: oci: 列出标签: Get: 127.0.0.1:18471 未在 30s 内应答: egress: 服务器未及时应答)

以及应答中途停止时:

<host> stopped answering: nothing more of its answer arrived for 30s: egress: the server did not answer in time (停止应答: 30s 内其应答再无任何内容到达: egress: 服务器未及时应答)

如何修复:修复由运维人员负责,且不在你的目录范围内。检查消息所指的服务器是否已启动,并且可从命令运行的位置访问;负载过高或正在维护的注册中心稍后会恢复应答,只需再次运行该命令即可。如果环境通过代理访问网络,请检查代理是否转发了请求而不是将其扣留。等待时长是固定的;没有任何设置可以延长它。

A registry’s repository listing did not end in time (注册中心的仓库列表未及时结束)

对注册中心整个仓库列表的遍历运行了五分钟仍未到达列表末尾,因而被停止。有两个命令会遍历该列表:aggrega plugin add,仅当没有插件恰好使用所给的名称、它转而查找名称包含该名称的插件时才会遍历;以及 aggrega registry update,它会先列出注册中心的仓库,再逐一读取。无休止地不断列出新仓库的列表,以及注册中心提供得太慢而无法完成的列表,都会在这里结束,而不是让命令一直挂起;此时遍历不会产生任何仓库,因此不会从被截断的列表中选择或索引任何内容。消息会说明停止时列表已列出了多少个仓库。

查询内容为名称一部分的插件添加操作所发出的消息:

aggrega plugin add: 127.0.0.1:18472: no cli plugin is named “mo”, and searching every repository for a name containing it did not finish; name the plugin exactly, as aggrega plugin add cli <name>: the walk was stopped after 5m0s, before the listing ended (repositories named so far: 146): registry: the repository listing did not end in time (aggrega plugin add: 127.0.0.1:18472: 没有名为“mo”的 cli 插件,并且在每个仓库中搜索包含该名称的插件未能完成;请准确指定插件名称,例如 aggrega plugin add cli 后接插件名称: 遍历在 5m0s 后、列表结束前被停止 (目前已列出的仓库数: 146): registry: 仓库列表未及时结束)

如何修复:对于 aggrega plugin add,请准确指定插件名称——使用 aggrega plugin add cli moo 而不是 aggrega plugin add cli mo——这样会用一次请求按该名称查找插件,而从不遍历列表。对于 aggrega registry update,原因在于注册中心的列表:请与运行该注册中心的人确认其列表会结束,并在列表能够结束后再次运行更新。五分钟的上限是固定的;没有任何设置可以延长它。

A registry kept asking to slow down (注册表持续要求放慢速度)

过于繁忙的注册表会回答 429 Too Many Requests,或带有说明需等待多久的 Retry-After 标头的 503 Service Unavailable。命令向注册表发出的每个请求都会按注册表要求的时间等待(未说明时为十秒),然后再次发送;发往该注册表的每个请求都会随之等待,向其并发发送的请求也会减少,直到它再次正常回答。如果注册表在五分钟内只回答“放慢速度”,则以此条件拒绝,并指出该注册表、其最后一次回答以及它只给出这一回答的时长;在等待期间自身时间限制到期的请求也同样如此。随后 aggrega registry update 会将该注册表报告为未编入索引,而它保留运行前的索引。

发出的消息,针对要求放慢速度达五分钟的注册表:

<host> kept asking to slow down: its last answer was 429 Too Many Requests, and it had answered nothing else for 5m0s: oci: the registry kept asking to slow down (持续要求放慢速度:其最后一次回答是 429 Too Many Requests,且在 5m0s 内未回答其他内容:oci: 注册表持续要求放慢速度)

以及针对自身时间限制结束了等待的请求:

<host> kept asking to slow down: its last answer was 429 Too Many Requests, and it had answered nothing else for <how long> when the request’s own time ran out: oci: the registry kept asking to slow down (持续要求放慢速度:其最后一次回答是 429 Too Many Requests,且直到请求自身时间用尽时仍未回答其他内容:oci: 注册表持续要求放慢速度)

如何修复:原因在于注册表的速率限制,而不是你编写的任何内容。限制客户端请求频率的注册表通常会限制来自同一地址的所有请求,因此请检查该地址背后是否有其他命令或机器在同时向它发出请求,并在它们完成后再次运行命令。如果注册表由你运营,请检查其速率限制。五分钟的上限是固定的;没有任何设置可以延长它。

获取或缓存的字节与为其承诺的摘要不匹配

每个制品都带有一个 manifest,承诺其内容的摘要,而 lockfile 独立地固定该 manifest 的摘要。这两项承诺都通过对手头的字节重新计算哈希并进行比较来检查。比较失败时报告的就是此条件,且它对刚获取的字节和从缓存读回的字节以相同方式触发。

两个条件,触发的是哪一个,就说明是哪一层不一致。 一个指出内容与其自身 manifest 承诺的摘要不匹配。另一个指出缓存的 manifest 与 lockfile 为其固定的摘要不匹配——这项检查防止被篡改的 manifest 成为之后内容检查所信任的依据。固定值使第二项检查有意义:它来自 lockfile,而不是从缓存字节中重新推导 manifest,因此两者真正相互独立。

随后,实体以其自身的记录行为准,而不是以字节所携带的内容为准。 一旦缓存实体的字节与其 manifest 一致,就会将其与 lockfile 为该实体记录的摘要进行比较;该摘要覆盖其发布所携带的文件——每个文件按其路径和字节计算——而不是压缩后的字节。因此,以不同压缩方式发布的相同文件仍然一致,而同一版本下的不同文件则不一致,这种不一致在内容条件下报告。遵循固定值的 pull 会对 registry 在固定版本下提供的内容做同样的比较。

这些检查都不需要网络。 每项检查都是对手头已有字节的哈希比较,这使得完全离线的构建仍能确认它所读取的正是被固定的内容。

输出的消息。 内容与其 manifest 比较:

oci: content digest <computed> != manifest layer <committed>: oci: content digest mismatch(内容摘要与 manifest 层不一致:内容摘要不匹配)

插件实体,manifest 在不同位置对其作出承诺:

oci: config digest <computed> != manifest config <committed>: oci: content digest mismatch(config 摘要与 manifest config 不一致:内容摘要不匹配)

缓存的 manifest 与固定摘要比较:

oci: cached manifest digest <computed> != pinned <pinned>: oci: cached manifest digest mismatch(缓存的 manifest 摘要与固定值不一致:缓存的 manifest 摘要不匹配)

缓存实体与其记录行比较,以及 registry 在固定版本下提供了其他内容:

catalog: cached <uri> content digest <computed> does not match lockfile pin <pinned>: oci: content digest mismatch(缓存实体的内容摘要与 lockfile 中固定的摘要不匹配:内容摘要不匹配)

oci: content digest mismatch: pinned entity "<uri>": registry now serves digest <computed> for the pinned version, not the pinned digest <pinned>; run aggrega pull --upgrade --release <release> to update the pin(内容摘要不匹配:registry 现在为固定版本提供的摘要不是固定的摘要;运行上述命令以更新固定值)

两者都以当时正在读取的对象为框架。若一个固定的实体在其固定值处没有任何来源持有:缓存条目的 manifest 不一致时为 manifest 的条件,否则为内容的条件:

pinned entity <uri>: no source holds the pinned bytes <pinned> (<what each source it read held>); with a registry reachable, aggrega pull --release <release> fetches the pinned version again: <the message above>(固定的实体:没有任何来源持有固定的字节;在 registry 可访问时,上述命令会重新获取固定版本:后接上面的消息)

指向逃出归档之外路径的归档条目也在内容条件下报告,因为尝试这样做的 bundle 并不是被承诺的那个 bundle:

path traversal entry "<name>": oci: content digest mismatch(路径穿越条目:内容摘要不匹配)

在报告它的步骤提供修复建议时,两者都带有相同的修复建议:

remediation: run aggrega pull —upgrade —release <release> to refresh the lockfile and cache(修复建议:运行该命令以刷新 lockfile 和缓存)

修复方法: 这不是由你的实体文件引起的,任何编写上的修改都无法消除它。使用 aggrega pull --upgrade --release <release> 同时刷新缓存和 lockfile,该命令会从来源重新获取并重写两者。如果这样能解决,说明缓存副本在写入后被修改或截断了。如果刷新后不匹配依然存在,说明发布者提供的字节确实与被固定的内容不同——即版本被重新发布,这需要询问其发布者,而且值得在采用新摘要之前而不是之后询问。

manifest 没有预期类型的层,或有多个

制品的 manifest 列出其各层,承载内容的那一层按其媒体类型而不是位置选出。这使得制品可以打包多个层——例如一个 chart 旁边附带独立的来源证明层——同时仍能可靠地选出内容。

有两种情形导致无从选择。没有预期类型的层,意味着 manifest 描述的是与读取该引用时所认定的不同的东西。有多个则意味着选择没有答案,取第一个有时正确,有时会悄无声息地出错。

输出的消息,每条都指出预期的媒体类型。没有时:

oci: manifest has no layer of media type "<media-type>": oci: manifest has no layer of the expected content media type(manifest 中没有该媒体类型的层:manifest 中没有预期内容媒体类型的层)

以及有多个时,还会指出数量:

oci: manifest has <count> layers of media type "<media-type>"; expected exactly one: oci: manifest has multiple layers of the expected content media type(manifest 中有多个该媒体类型的层,预期恰好一个:manifest 中有多个预期内容媒体类型的层)

修复方法: 修复由发布者而不是你负责——manifest 不是 catalog 作者编写的内容。首先检查引用是否指向你想要的位置:解析到不同制品类型的引用会产生第一种情形,因为该 manifest 是另一种东西的真实 manifest。如果引用正确,说明该制品发布时所用的 manifest 没有将其描述为它所声称的类型,因此请将消息中的媒体类型告知其发布者。通过常规发布路径发布会产生恰好有一个内容层的 manifest,因此出现任一情形的制品都是以其他方式组装的。

A published bundle holds no entity, or holds two(已发布的包中没有实体,或有两个实体)

在其文档旁声明文件的实体(例如一个 Recipe 的本地 chart 或其锁文件、一个 Component 导入的 schema)会以 .tar.gz 形式发布,将实体与这些文件打包在一起。读回时需要在这些文件中重新找到该实体;而实体所在的文件可以取任何名字,因此识别它的依据是它携带的实体前导部分,而不是文件名。包顶层中 kind: 为可发布实体类型的文档就是该实体;位于其旁的 compose 片段、chart 模板或 Kubernetes 清单都不是,位于 source/ 树更深处的实体文档也不是,那是实体所携带的内容,而非实体本身。

有两种形态会导致无可选择,二者都取决于制品的发布方式。

包顶层没有实体文档。 打包时顶层没有放入实体:其文档被遗漏,或被放在子目录中,而不是与它携带的文件并列。消息会列出包顶层实际包含的内容,通常足以看出是哪种情况。

包顶层有两个实体文档。 该包是从一个编写了两个实体的整个目录打包而成的。aggrega push 从不这样做,因为每个实体只携带它声明的文件,但其他客户端可能会这样做。以这种方式打包后,两个实体各自的发布坐标携带的是相同的字节,因此无论用哪一个来响应,都可能在所请求的名称下返回另一个实体,而下游无从察觉。不存在安全的选择,所以不作选择。

输出的消息,会列出所找到的内容。没有实体、但包中有其他文件时:

bundle root carries no entity document among <file>, <file>: oci: published bundle carries no entity document(包根目录的上述文件中没有实体文档:oci:已发布的包中没有实体文档)

没有实体、且包中什么都没有时:

bundle root carries no files at all: oci: published bundle carries no entity document(包根目录中没有任何文件:oci:已发布的包中没有实体文档)

有多个实体时,会同时给出数量和冲突的文档:

bundle root carries <count> entity documents (<file>, <file>): oci: published bundle carries more than one entity document(包根目录含有多个实体文档:oci:已发布的包中含有不止一个实体文档)

修复方法: 这两种情况都应由发布者而不是你来解决,修复点在实体发布时所在的版本目录。为每个实体提供独立的版本目录,使该目录只包含一个实体及属于它的文件。这正是每个已发布实体都遵循的布局:目录以实体的 metadata.version 命名,并位于实体自身名称之下。然后以新版本重新发布:已发布的字节是冻结的,因此在现有版本上重新发布会被拒绝,而不会被更正。如果你是使用方而非发布方,请将该消息提供给制品的发布者;消息中的文件名指明了需要拆分的目录。

A published artifact cannot be read as an entity(已发布的制品无法作为实体读取)

从实体的发布坐标读取实体,起点是 registry 在该坐标提供的字节:aggrega inspect oci://… 会读取这些字节供你查看,依赖拉取也以同样方式读取归档的字节,以找到它所固定的版本。这些字节有两种形态不包含可读取的实体。

无法解包的归档。 带有其声明文件的实体以 .tar.gz 形式发布,字节开头也确实如此,但压缩流或其中的归档格式不正确,最常见的原因是被截断。这些字节仍与制品自身清单中记录的摘要一致,因此它们正是当初发布的内容:损坏发生在发布之前或发布过程中,而不是在传输给你的途中。

不是实体的文档。 该坐标只携带一个文档,但它无法解析、没有声明 kind:,或声明了一种从不发布的类型,例如 Release 或 Manifest。这说明该引用指向的是在目录之外另行发布的东西而不是实体,例如用 aggrega push-artifact 发布的数据制品。

输出的消息。 压缩流格式不正确的归档,附带导致中止的错误:

oci: unbundle gzip: <archive error>: oci: published bundle cannot be unpacked(oci:解包 gzip 失败:oci:已发布的包无法解包)

在某个文件中途中断的归档:

read <file> from the published bundle: <archive error>: oci: published bundle cannot be unpacked(从已发布的包中读取文件失败:oci:已发布的包无法解包)

声明了从不发布的类型的文档:

the published document declares kind <kind>, which a registry does not publish: oci: published artifact is not an entity document(已发布的文档声明了 registry 不发布的 kind:oci:已发布的制品不是实体文档)

以及根本不是文档的字节:

the published bytes do not parse as a document (<parse error>): oci: published artifact is not an entity document(已发布的字节无法解析为文档:oci:已发布的制品不是实体文档)

修复方法: 无法解包的归档应由发布者替换。已发布的字节是冻结的,因此补救办法是以新版本重新发布该实体;如果你是使用方,请将该消息提供给其发布者。不是实体的文档几乎总是意味着该引用不是你想要的那个:检查它是否指向实体的发布坐标,即 aggrega push 发布实体时打印的引用。

The registry could not answer what is attached to an artifact(registry 无法回答制品附带了什么)

签名和其他附件挂在制品之外,而不是位于制品内部,查找它们需要向 registry 发起查询。此情况表示该查询没有得到回答:registry 不提供这种查找,附件所挂靠的制品无法定位,或请求本身失败。

这与“没有任何附件”的回答不同,而防止把两者混为一谈正是此情况存在的目的。 确实不带签名的制品会正常解析,并得到一个空列表。而此情况表示从未获得该列表,因此对附件一无所知。

是否中止取决于是否要求签名,两种走向都是有意为之:

  • 要求签名。 构建停止。无法运行的必需检查不算通过,接受该制品就意味着依赖于一个无人成功提出的问题。
  • 不要求签名。 构建继续,并明确地说明这一点,而不是默默进行。这次查找无论如何都没有产生可验证的内容,因此拒绝就等于凭一个未获回答的问题来拒绝制品;但保持沉默又会被理解为一次干净的无签名拉取,而事实并非如此。

输出的消息。 registry 不提供该查找时:

oci: target does not support referrer discovery: <target kind>: oci: referrer discovery could not be completed(oci:目标不支持 referrer 发现:oci:referrer 发现无法完成)

制品本身无法定位时:

oci: resolve subject "<reference>": <the underlying failure>: oci: referrer discovery could not be completed(oci:解析 subject 失败:oci:referrer 发现无法完成)

以及查找失败时:

oci: list referrers of "<reference>": <the underlying failure>: oci: referrer discovery could not be completed(oci:列出 referrer 失败:oci:referrer 发现无法完成)

不要求签名时,相同的文本会改为以通知形式出现:

signature verification could not run for <uri> (the registry could not answer the signature lookup and no signature is required; continuing): <the message above>(无法执行签名验证(registry 无法应答签名查询,且不要求签名;继续运行))

修复方法: 这应由运维人员修复,问题出在 registry 而不是你的目录。如果 registry 根本不提供附件查找,它就无法携带签名,因此要么将制品镜像到支持签名的 registry,要么在 .aggrega-config.yaml 中取消对该主机的签名要求;并记下你选择了哪一种,因为后者意味着不再检查来自该主机的签名。如果 registry 确实提供该查找但查找失败,则这是附件端点上特有的传输或权限问题,待 registry 可访问后重新运行即可解决。

An artifact that must be signed carries no signature(必须签名的制品未携带签名)

当工作区自身的签名策略覆盖某个制品的种类,或该制品所来自的 registry 被配置为要求签名时,该制品就需要签名。此情况表示 registry 回应了附件查询,但没有任何附件,而签名是必需的。

**这两项要求是同一立场在两个范围上的体现。**工作区范围的策略会对范围内的种类强制要求签名,即使该主机自身的条目不要求签名;因此,一个不作任何要求的主机并不能豁免工作区范围策略所覆盖的制品。

**在不要求签名的情况下,这根本不是失败。**若存在签名,制品会被验证;若没有签名,则静默通过。正因如此,未配置立场的主机无需任何繁琐步骤即可使用。

在工作区范围策略生效时,无法确定种类的制品会被视为需要签名,而非被豁免,因此无法归类的制品无法绕过已开启的策略。

输出的消息,以所检查的引用为前缀:

verifying the signature of <uri>: signing: no signature found for an artifact that requires one(正在验证该 URI 的签名:signing:要求签名的制品未找到签名)

**如何修复:**这需要由运维人员或发布者来修复,而非实体作者。如果你预期该制品应已签名,说明它在发布时没有签名——请将该引用告知其发布者,因为只有他们才能附加签名。如果该制品本就不打算签名,那么需要更改的是这项要求:它来自 .aggrega-config.yaml 中该 registry 的条目,或来自工作区范围的签名策略,消息中的引用会告诉你应查看哪个主机。关闭某项要求意味着来自该主机的制品将不再被检查,因此应优先将策略范围收窄到某个种类,而不是直接将其关闭。

A signature does not verify(签名验证未通过)

已找到并检查了签名,但检查失败。这是该检查的通用否定结果,涵盖以下情形:证书链未以信任材料为根;在要求透明日志记录时签名没有该记录;签名针对的是与手头制品不同的制品;签名包已被篡改;以及签名包针对固定的密钥进行检查却无法通过验证。

**它被刻意与签名者不受信任的签名区分开。**后者结构上完好,只是由错误的签名者签署;而此情况则根本未通过检查。将二者分开,你才能区分“该制品并非被签名的那个”与“该制品由你尚未接受的人签名”。

**签名针对的是哪个制品,会被检查两次。**签名的密码学检查通过后,工具链会从签名本身读取它是为哪个制品所做——之后每次构建都会依据同样的读取结果来核对所记录的签名,正是这一点使构建无需验证任何内容即可拒绝从一个制品复制到另一个制品上的签名——如果读取结果所指的不是手头的制品,或签名的形式使读取无法确定对应的制品,工具链就会拒绝该签名。拉取所接受的两种形式都会被读取:对制品本身所做的签名,以及指明该制品的已签名声明。读取遵循密码学检查自身的规则,因此对于该检查所接受的签名,二者结论一致;出现此类拒绝即意味着二者不一致,值得附上引用和消息进行报告,而不是通过配置绕过。

如果某个 registry 的条目将验证标记为建议性,相同的文本会作为通知报告,运行继续进行。

**输出的消息。**来自检查本身,引用验证器报告的内容:

signing: signature bundle does not verify: <what the verifier reported>(signing:签名包未通过验证,后附验证器报告的内容)

以及在密码学检查通过、但对签名所针对制品的读取结果不一致时:

signing: signature bundle does not verify: its cryptographic check holds, but it does not name <manifest-digest> as the artifact it was made for(signing:签名包未通过验证:其密码学检查成立,但它未将所示清单摘要指明为其签名所针对的制品)

signing: signature bundle does not verify: its cryptographic check holds, but it is in a form from which the artifact it was made for cannot be read(signing:签名包未通过验证:其密码学检查成立,但其形式无法读取出其所针对的制品)

每条都以正在验证的引用为前缀:

verifying the signature of <uri>: <the message above>(正在验证该 URI 的签名,后附上述消息)

以及在 registry 的条目将验证设为建议性时,作为通知而非中止:

signature verification failed for <uri> (advisory; continuing): <the message above>(该 URI 的签名验证失败(仅作提示;继续执行),后附上述消息)

**如何修复:**这并非由你的实体文件引起,任何编写上的修改都无法消除它。应将其视为关于制品而非关于你的配置的陈述:手头的字节不是被签名的字节,或签名不是所配置的信任材料能够检查的签名。首先重新获取该制品,因为被截断或被篡改的缓存副本恰好会以这种方式失败,重新获取即可消除。如果重新获取后问题依旧,请将引用和验证器的原话告知该制品的发布者。不要借助建议性设置来绕过它——该设置会让检查继续运行但不再中止,这是有意选择接受来自该主机的未验证制品,而不是修复问题的方法。

A signature verifies but its signer is not one the registry trusts(签名验证通过,但其签名者不受该 registry 信任)

签名检查通过——证书链以信任材料为根,透明记录也存在——但该证书中的身份与为该 registry 配置为可接受的所有身份都不匹配。该制品由一个真实但尚未被接受的签名者签署。

身份的两个部分都会被比较,即主体和为其担保的签发者,任何一方都可能是不匹配的那一个。只要能从证书中读出,消息会同时给出二者,因为若不同时显示,一个在无人接受的签发者下呈现预期主体的签名者,看起来与主体错误完全相同。

输出的消息。两个部分均可读取时:

signing: signature identity is not trusted for this registry: <what the verifier reported>; signer presented issuer "<issuer>" with identity "<subject>", but no trusted identity permits that issuer(signing:该签名身份不受此 registry 信任,后附验证器报告的内容;签名者出示了所示颁发者及身份,但没有任何受信任的身份允许该颁发者)

以及无法读取时,回退为验证器自身的报告:

signing: signature identity is not trusted for this registry: <what the verifier reported>(signing:该签名身份不受此 registry 信任,后附验证器报告的内容)

**如何修复:**这由运维人员决定,而且是一个真正的决定,而非走形式。将消息中的签发者和身份与 .aggrega-config.yaml 中为该 registry 配置的受信任身份进行比较。如果该签名者是你打算接受的,就添加它——一个条目指明一个身份(或匹配身份的模式)以及签发者,二者都必须正确。如果不是,则该制品由你尚未接受的人签名,为让构建通过而添加该身份正是应当避免的做法。对于公布了自身信任策略的 registry,可以在添加该 registry 时固定其策略,这样无需手动转录即可引入预期的身份。

A keyless trust policy names no acceptable signer(无密钥信任策略未指定任何可接受的签名者)

无密钥验证通过将签名证书中的身份与一组配置为可接受的身份进行匹配,来决定是否接受某个制品。空集合会被拒绝,而不会被视为一项策略:与空集合匹配要么接受所有签名者,要么拒绝所有签名者,而这两者都不是配置了验证的操作员的本意。

输出的消息,即该情况本身的表述:

signing: keyless verification requires at least one trusted identity(signing:无密钥验证至少需要一个受信任的身份)

**修复方法:**在 .aggrega-config.yaml 中为该注册表配置至少一个受信任的身份。一个条目指定身份(精确的主体,或与之匹配的模式),以及为其担保的签发者,两者都是必需的。如果注册表公布了自己的信任策略,在添加注册表时固定该策略,即可用注册表发布的内容填充该集合。如果你根本不打算验证来自该注册表的签名,那是与空身份集合不同的另一项设置,应显式设置它来表明这一点。

The pinned trust root cannot be read(无法读取固定的信任根)

在工作区中固定的信任根,使无密钥检查无论在何处运行都无需网络访问即可完成验证:它是一个文件,其内容是所有签名据以检查的材料。此情况表示,配置路径上的文件无法转换为可用的信任材料:文件不存在、不可读,或其内容不是信任根。

**它会中止,而不是回退。**固定信任根是一种有意的选择,即依据你所控制的材料检查签名;如果改为悄悄获取一个信任根,就会用另一种选择取代这一选择,并产生无人要求的验证结果。

输出的消息,指明路径并引用读取时报告的内容:

signing: cannot load pinned trust root: <path>: <what the read reported>(signing:无法加载固定的信任根)

**修复方法:**这由操作员处理。检查为信任根配置的路径是否存在,且运行命令的用户是否可读:相对于其他工作目录的路径,以及存在但不可读的文件,都会在此报告。如果文件存在且可读,说明其内容不是信任根,此时应从你获取它的来源换上一个最新的包,而不是编辑它。如果并不打算固定信任根,需要修改的是配置:取消该固定,验证就会使用原本会提供给它的材料。

A pinned verification key is not the key profile the verifier accepts(固定的验证密钥不属于验证器接受的密钥配置)

使用持有的密钥进行签名和验证时只采用一种密钥配置,任何其他类型的密钥都会被拒绝,而不会尝试使用。这是关于密钥类型的判断,与它能否验证任何内容无关。

**它在两个时刻报告,对应两项不同的工作。**一是加载用于签名的密钥,发生在发布制品时;二是依据为注册表固定的密钥检查签名,发生在验证制品时。两种情况下的拒绝是相同的。

输出的消息,各自指明实际提供的密钥的算法——an RSA key 或 an Ed25519 key。对于固定的验证密钥:

signing: unsupported held-key type: pinned key is <the key's algorithm>, want ECDSA P-256(签名:不支持的持有密钥类型:固定的密钥为所示算法,要求为 ECDSA P-256)

对于加载用于签名的密钥:

signing: unsupported held-key type: held key is <the key's algorithm>, want ECDSA P-256(签名:不支持的持有密钥类型:持有的密钥为所示算法,要求为 ECDSA P-256)

**修复方法:**提供消息所指明配置的密钥。如果你在验证,该密钥是 .aggrega-config.yaml 中为注册表固定的密钥,它必须是发布者签名所用密钥的公钥部分;此处不匹配通常意味着固定了错误的文件,因为类型正确但密钥错误时,报告的会是签名无法验证。如果你在签名,请生成所指明配置的密钥,或使用无密钥方式,它完全不需要持有密钥。

The workspace is offline and the step needs the network(工作区处于离线状态,而该步骤需要网络)

工作区可以标记为离线,该设置是一种拒绝而非偏好:每个会访问网络的步骤都会在构造时被拒绝,早于任何连接发起。提前拒绝使失败信息能够说明“此工作区处于离线状态”,而不是稍后表现为一个没有任何解释的超时。

**一项决定,在一处读取。**需要预先知道能否访问网络的步骤,所询问的问题与获取操作本身所询问的相同,因此检查与它所守护的操作不会得出不同的结论。

它涉及多种工作,都属于同一种拒绝:从注册表获取制品、通过网络获取 Recipe 的源、获取外部输入、获取用于签名的身份,以及获取信任材料。读取已填充缓存的构建不会涉及其中任何一项,这正是该设置的意义所在。

如果整个命令就是一次网络往返,拒绝会最先发生,而不是最后。push、push-artifact 和 registry update 的存在就是为了访问注册表,因此它们会在读取你的实体或遍历你的仓库之前就给出拒绝,并指明是三处中的哪一处设置了该状态:你输入的标志、环境变量,或文件及其中的键。--dry-run 是例外,之所以例外,在于它所做的事而非它的名称:它报告将要发布的内容而不调用任何东西,因此它是离线安全的发布形式,仍可正常工作。

输出的消息,自带修复方法,即该情况本身的表述:

egress: network access refused because the workspace is offline; remediation: pass --offline=false to allow the network for this one run, or clear the top-level offline key in the configuration file (or AGGREGA_OFFLINE) to allow it from now on; where the work is a build that needs content the machine does not have, run aggrega pull --release <release> from a connected environment first to populate the cache(出站:由于工作区处于离线状态,网络访问被拒绝;补救方法:传入上述标志以仅在本次运行中允许网络访问,或清除配置文件中的顶层离线键(或 AGGREGA_OFFLINE)以从此允许网络访问;如果所做的工作是需要本机所没有内容的构建,请先在联网环境中运行上述 pull 命令来填充缓存)

外层包裹的是需要网络的操作,例如获取 Recipe 的源:

sourceresolver: kind=<kind> url=<url> version=<version>: <the message above>

在离线工作区中添加官方 hub 不会被拒绝:hub 以其内置基线添加,通知会说明由于工作区处于离线状态,未向 hub 请求其信任策略。

**修复方法:**消息列出了三种方式,选用哪一种由你决定。如果已设置该状态而你想在这一条命令中绕过它,请传入 --offline=false;这正是该标志的用途,也是并非亲自编写配置文件的人唯一可用的办法。如果工作区本就应当离线,需要修复的是缺失的内容:在有网络访问的地方运行 pull,使缓存包含该 release 涉及的一切,之后离线构建就不再需要其他任何东西。如果工作区根本不应离线,请在源头清除该设置:.aggrega-config.yaml 中顶层的 offline 键,或消息所指明的环境变量;环境变量最容易让人疏忽,因为它不在任何文件中。注意,离线工作区完全无法使用无密钥方式签名,因为签发证书和记录证书都是网络操作,没有离线形式。

构建拓扑时

当每个 Component 都有了已解析的 Recipe 后,编译器读取每个 Component 的 uses: 块,并交叉引用目标和 feature 附件,从而将各 Components 拼接成 IR 图。

Dangling uses target (悬空的 uses 目标)

某条 uses: 边指向的目标组件在已解析的拓扑中不存在。该中止与来源无关——开发者编写的 Aggregate 边和 Release 连接的边都会同样被捕获。悬空目标是致命中止,而不是静默丢弃:否则指向不存在目标的边会消失,使消费方注入的值在部署时静默为空。它是下文未声明 socket 中止在结构上的姊妹检查:无论连接接入哪个 socket,在对边进行类型检查之前,其目标都必须解析为一个已存在的组件。

发出的消息。先给出拒绝,然后是不对应任何对象的目标以及该连接所接入的 socket——最后是处理方法:

uses edge target does not exist ("<target>", wired into socket "<socket>"). Point the target at a component the Aggregate declares, or declare a component under that name. (uses 边的目标不存在(括号内为该目标及其所接入的 socket)。请将目标指向该 Aggregate 声明的某个 component,或以该名称声明一个 component。)

该发现定位在它所涉及的编写条目上,即该条目所在的文档中,因此由组件自身 uses: 块绘制的连接、由附件投射的连接,以及由 Release 连接的连接,都会各自在其所属的块处报告。每条违规连接都作为单独的发现报告,因此一次构建会列出全部违规,而不是在第一个处停止。

修复方法: 声明缺失的目标组件,或更正 uses: 条目中的目标名称,使其与已存在的组件一致。

Two connections of one component under one alias(同一组件的两个连接使用同一别名)

组件按别名读取它的每个连接——别名即该连接写入时所在的键;对于以列表条目形式写入的连接,别名是其目标自身的名称。Recipe 模板仅按别名读取组件的连接,而断言先按 socket 再按别名读取,因此同一组件在同一别名下的两个连接,至少会在其中一种视图里共用一个槽位:后者会占据它,另一个则不会出现在模板或断言所见的内容中。因此,一个别名只指代组件的一个连接——无论各自接入哪个 socket,无论由什么绘制(组件自身的 uses: 块、任意作用域下附件的 uses: 块,或 Release 的逐边条目),也无论其目标是什么。一旦图最终确定,在任何断言运行之前、任何内容渲染之前,这样的一对连接就会中止构建。

这样的一对连接源于在各个层面单独看都合法的编写:组件自身的条目与附件的条目位于同一 socket 和别名上;一个列表两次列出同一目标(models: [llama, llama]);同一别名写在两个 socket 上(models: { local: … } 与 databases: { local: … } 并列);两个附件连接同一别名;或者 Release 条目在 Aggregate 未绑定的 socket 上绘制连接,而所用别名 Aggregate 已在另一个 socket 上使用。有两种相近的形式不会触发此中止:在同一个键控条目块中两次写同一个键会导致文档加载失败;而 Release 条目若位于另一个块已绘制的 socket 和别名上,则会配置该连接——或者在指向不同目标时作为重定向而中止——而不是绘制第二个连接。

发出的消息。先给出拒绝,然后是别名和组件,接着是本连接的 socket、目标及其条目的编写位置,再是已占用该别名的连接的相同信息——最后是处理方法:

connection alias is already used by another connection of the same component ("<alias>", on component "<component>", this connection wired into socket "<socket>", with target "<target>", written in "<file>", at "<key path>", the connection already holding the alias wired into socket "<socket>", with target "<target>", written in "<file>", at "<key path>"). Give one of the two connections an alias of its own: a component reads each connection by its alias, whatever socket it is wired into. A list entry takes its target’s name as its alias, so a target listed twice is listed once, or written as two keyed entries under two aliases. (该连接别名已被同一 component 的另一个连接使用(括号内依次为别名、component、本连接所接入的 socket、目标、编写所在的文件和键路径,以及已占用该别名的连接的 socket、目标、文件和键路径)。请为两个连接之一指定单独的别名:component 按别名读取每个连接,无论其接入哪个 socket。列表条目以其目标的名称作为别名,因此被列出两次的目标应只列出一次,或写成两个使用不同别名的键控条目。)

如果两个连接写在同一键路径下——即一个列表两次列出同一目标——则每个连接还会以其在该列表中的位置来指明,如 list entry "2" 与 list entry "1",这是区分这两个条目的唯一依据。

该发现定位在后一个连接自身的条目上——即第二个绘制的连接,也就是本会占据该别名槽位的那个——位于该条目所在的文档中。因此,Release 条目或 Release 编写的附件会被归为运维问题,而 Aggregate 中的条目则被归为开发者问题。每条违规连接都作为单独的发现报告,因此一次构建会列出全部违规。

有些形式的指明不那么精确。在多个作用域声明的附件名称——例如同时在组件和包含它的子系统上声明——会从每个声明块各绘制一个连接,而构建仅以附件名称记录这两者。此时两个连接都会指明在其中一个声明块上——即组件自身的附件块(只要该名称在那里声明),且都不带列表位置。在导入的 Aggregate 内部也是如此,其声明块——组件的声明块和该模块自身某个子系统的声明块——在模块自身的文档中指明。在所有这些形式中,这对连接仍然会被拒绝。

修复方法: 为两个连接之一赋予独立的别名。对于两次列出同一目标的列表,只列出一次该目标,或将两个连接写成两个别名下的键控条目。对于两个 socket 上的同一别名,重命名两个键之一。若附件以组件已使用的别名连接某个 socket,则在附件自身的 uses: 块中改用另一个键。

uses: socket not declared in the owning entity’s usesSchema(socket 未在所属实体的 usesSchema 中声明)

某个 uses: 块命名了一个插槽,而拥有该声明面的实体并未在其 usesSchema 中声明它;这只发生在仅允许命名已声明插槽的两个声明面之一:Feature 附件的 uses:,其插槽必须在所附加的 Feature 上声明;以及 Release 的逐边 uses:,其插槽必须在消费方 Component 上声明。Release 只能在 Component 的 usesSchema 已声明的插槽内连接或配置边。

附件表面会在编写附件的每个作用域上检查:在组件上,在子系统上——无论属于该 Aggregate 还是它导入的模块——在 Release 边界上,以及在 Release 组件条目上,包括模块所贡献组件的条目。模块自身的声明在导入它的组合构建完成后检查,发现会指明该模块的 Aggregate 及其文档中的键。

组件自身的 uses: 块被有意排除在这些声明面之外,因此该终止不会对其触发。开发者拥有 Aggregate 所声明的拓扑,可以命名目录未声明的插槽;目录对某个插槽保持沉默,意味着该连接未被预见,而不是被禁止。这样的插槽是合法的,其边也会被构建——它放弃的是已声明插槽所带有的选择器和逐边契约。因此,在那里拼错插槽名称不会导致终止,而是自成一个临时连接,并以同时列出两种拼写的警告报告——参见 warnings.md “Uses-socket near-miss lint”。

发出的消息:

unknown uses socket: name a socket the entity declares in its usesSchema — only a component’s own uses block may name one the catalog did not declare (Release <release-name>, at .spec.components.<component>, "<component-type>", "<socket-name>", "<declared-sockets>")(未知的 uses socket:请指定该实体在其 usesSchema 中声明的 socket——只有组件自身的 uses 块可以指定目录未声明的 socket;括号中依次给出 Release、位置、组件类型、socket 名称及已声明的 socket)

附件分支以 feature 类型代替组件类型;如果所附加的 Feature 根本未声明 usesSchema,则改为报告不允许为其使用 uses: 声明。

**修复方法:**在附件上,将插槽名称更正为所附加 Feature 声明的插槽,或在该 Feature 的 usesSchema 中声明该插槽。在 Release 逐边条目上,将插槽名称更正为消费方 Component 声明的插槽——Release 不能引入 Component 未声明的插槽,受支持的做法是将声明移入目录实体。如果目录实体根本未声明 usesSchema,则它在该声明面上不接受任何 uses: 声明——请删除该块。

A connection carries an attachment under a name its socket declares no slot for(连接以其插槽未声明槽位的名称携带附件)

某个连接条目的 features: 块命名了一个附件,而该连接插槽的任何槽位都未声明它。连接携带的附件是一个封闭集合:连接所经由的插槽在消费方 Component 的 usesSchema 条目上的 featuresSchema 中声明了其上连接可以填充的每个槽位,任何其他名称下的附件都会在构建加载时被拒绝。未声明 featuresSchema 的插槽不允许其连接携带任何附件;Aggregate 命名但 Component 未声明的插槽同样如此——这样的插槽不声明任何槽位。

该规则适用于编写连接附件的两种文档:Aggregate 中组件 uses: 下的连接条目,以及 Release 的逐边 uses: 条目。对于子 aggregate 提供的组件,开发者的名称在读取该子 aggregate 自身的文档后检查,发现项会指明该文档的文件及其中的组件条目。Release 的名称在组合展平后,针对 Release 所涉及的每个组件进行检查,发现项会指明 Release 自身的条目——位于其所在的边界内,或位于到达子 aggregate 组件的路由条目下。Release 条目位于 Component 未声明的插槽上时,由上文的未声明插槽终止报告(它会列出实际存在的插槽),而不是由本终止报告。

发出的消息。先是拒绝,然后是文档和条目、附件名称、连接、插槽、组件以及插槽声明的槽位——最后是处理方法:

a connection carries an attachment under a name its socket declares no slot for (Aggregate <aggregate-name>, at .spec.components.<component>.uses.<socket>.<alias>, "<attachment>", on the connection "<alias>", through socket "<socket>", of component "<component>", the socket declaring the slots "<slots>"). Write the attachment under one of the slots the socket declares, or declare this slot in the socket’s featuresSchema on the Component.(连接以其 socket 未声明槽位的名称携带了一个附件;括号中给出 Aggregate、条目路径、附件名称、连接、socket、组件以及该 socket 声明的槽位。请将附件写在该 socket 声明的某个槽位下,或在 Component 上该 socket 的 featuresSchema 中声明此槽位。)

如果该名称与插槽声明的某个槽位只差一处编辑——字符调换、缺失、重复或错误,即拼写错误的常见形态——则紧随其后指明该槽位,使可能的预期拼写出现在同一句中:

a connection carries an attachment under a name its socket declares no slot for (Release <release-name>, at .spec.boundaries.<boundary>.components.<component>.uses.<socket>.<alias>, "credentail", near the declared slot "credential", on the connection "<alias>", …)(连接以其 socket 未声明槽位的名称携带了一个附件;括号中给出 Release、条目路径、附件名称、与之接近的已声明槽位以及连接等)

对于这样的名称,不会另外发出提示。在组件自身的 features: 块上,与已声明槽位相差一处编辑的名称是合法的,只会触发下文“An attachment name is one edit from a declared slot(附件名称与已声明槽位相差一处编辑)”中的提示;而在连接上,该名称会被拒绝,拒绝信息本身即包含这一配对。

如果插槽不声明任何槽位,则不显示列表,建议为“The socket declares no slots, so no connection wired through it carries an attachment: remove the attachment, or declare the slot in the socket’s featuresSchema on the Component.(该插槽不声明任何槽位,因此经由它的连接都不携带附件:请删除该附件,或在 Component 上该插槽的 featuresSchema 中声明该槽位。)”如果 Component 根本未声明该插槽,则建议为“The component’s type does not declare this socket, so the socket declares no slots and no connection wired through it carries an attachment: remove the attachment, or declare the socket and its slot in the Component’s usesSchema.(该组件的类型未声明此插槽,因此该插槽不声明任何槽位,经由它的连接都不携带附件:请删除该附件,或在 Component 的 usesSchema 中声明该插槽及其槽位。)”

每个违规附件都作为单独的发现项报告,因此一次构建即可列出全部。

**修复方法:**将附件写在插槽声明的槽位下;或者,如果连接需要插槽中没有的槽位,则在 Component 上该插槽的 featuresSchema 中声明它。对于 Component 未声明的插槽,请在 Component 的 usesSchema 中声明该插槽及其槽位,或删除该附件。

Release retargets a developer-declared edge(Release 重新指定了开发者声明的边的目标)

某个 Release 的逐边 uses: 条目指定的目标,与开发者已为同一 socket 和别名连接的目标不同。Release 可以配置开发者声明的边(设置逐边 infra,指定相同的目标或省略目标),也可以把一条边连接到已声明但未绑定的 socket,但不能重新指定开发者所声明的边的目标——开发者拥有其编写的架构。

两个目标按编写时的形式比较,而不是按解析后的结果比较。target: 可以指定子 aggregate 发布的别名而非 component id,该别名解析为模块为其发布的 component——因此,重复开发者所写的同一别名的 Release 条目属于配置,会被接受,与重复一个普通 component id 完全相同。

无论此中止是否触发,该边都保留开发者给定的目标,且 Release 条目的 infra: 不会应用于它。被拒绝的重新指定目标永远不会只应用一半。

发出的消息。先是拒绝,然后是开发者声明的目标、Release 指定的目标以及 socket——最后是处理方法:

release edge retargets a developer-declared edge (declared target "<declared-target>", target the Release names "<release-target>", wired into socket "<socket>"). Drop the target from the Release entry to configure the connection as it was declared, or change the target where the connection is declared.(Release 边重新指定了开发者声明的边的目标(括号中依次为声明的目标、该 Release 指定的目标以及所接入的 socket)。请从 Release 条目中删除目标,以按声明配置该连接;或者在声明该连接的位置修改目标。)

该发现定位在声明该连接的文档中、声明该连接的编写条目上。每个违规条目都作为单独的发现报告,因此一次构建会列出所有违规条目,而不是每次运行只列出一个。

**修复方法:**从 Release 的 uses: 条目中删除不同的 target,以配置现有的边(仅逐边 infra);或者,如果该连接确实属于另一个 socket,则通过开发者未绑定的 socket 连接它。要更改目标本身,请在编写拓扑的 Aggregate 中更改。

Release per-edge configuration has no edge to apply to(Release 逐边配置没有可应用的边)

某个 Release 的逐边 uses: 条目设置了 infra:、features: 下的附件或两者,但在构建中的所有边都绘制完成后,其指定的消费者、socket 和别名处不存在任何边。

Release 条目能做的两件事是连接一条边和配置一条边,做哪一件取决于它是否指定了 target:。带目标的条目会创建它所配置的边。不带目标的条目配置的边必须已经存在——由开发者在 Aggregate 中声明,或由附加的 Feature 提供。因此,未指定目标且不匹配任何现有边的条目不会应用于任何对象:infra: 块及其下的附件永远不会进入任何输出。构建会停止,而不是接受毫无作用的编写,因为否则一次成功的构建会被理解为确认基础设施已应用、连接携带了条目为其设置的内容。

别名是条目指定内容的一部分,因此配置开发者从未声明过的别名的条目不会到达任何边,即使该 socket 以另一个别名绑定。指定了 Aggregate 未声明的 component 的条目也是如此。

两种相邻的情况由各自的中止报告,而不是由此中止报告,因为它们各自能提供更多信息。消费方 Component 的 usesSchema 未声明的 socket 会作为未声明的 socket 报告,该报告可以列出确实存在的 socket。未指向任何 component 的 target: 会作为悬空目标报告。被 active: 开关关闭的 component 按设计会带走它的边,因此遗留在其上的条目会被接受,而不会中止。

**每个违规条目都会被报告。**包含多个未到达任何边的条目的 Release,会在一次构建中按文档声明顺序为每个条目各报告一次此中止,而不是只报告第一个、把其余留给下一次构建。

发出的消息(条目指定的 component 存在时)。它带有条目本身的路径,因此指出的是需要编辑的那一行,而不是包含它的 component:

release per-edge configuration has no edge to apply to (Release <release-name>, at .spec.boundaries.<boundary>.components.<consumer>.uses.<socket>.<alias>, "<consumer>", on socket "<socket>", under alias "<alias>"). Give the entry a target to wire the edge, or remove it: an entry with no target configures an edge that must already exist.(Release 的逐边配置没有可应用的边(括号中依次为该 Release、条目路径、消费方组件、socket 和别名)。请为该条目指定目标以连接该边,或删除该条目:没有目标的条目配置的是一条必须已经存在的边。)

在顶层而非 boundaries 下指定其 component 的 Release,会采用作者编写的形式——.spec.components.<consumer>.uses.<socket>.<alias>——而在 aggregates: 路由条目中指定的 component 则通过该条目、以其在那里的本地名称来指出。

当条目指定的 component 未在 Aggregate 中声明时,该中止来自构建的更早阶段,内容如下,并指出条目设置的内容——infra、features 或 infra and features:

release per-edge configuration has no edge to apply to: release edge <consumer>/<socket>/<alias> sets <infra|features|infra and features> on <consumer>, which is not a component in the topology(Release 的逐边配置没有可应用的边:该 Release 边在一个并非拓扑中组件的消费方上设置了 infra、features 或两者)

**修复方法:**为条目添加 target:,以连接该边并将配置应用于它;将别名更正为 Aggregate 为该连接声明的别名,使条目配置现有的边;将 component 名称更正为 Aggregate 声明的名称;或者,如果不再需要该配置,则删除该条目。

A Release attachment takes the name of a connection’s attachment(Release 附加项占用了某个连接的附加项名称)

Release 在某个名称下写了一个附加项,而该名称正是某个组件的某个连接上的附加项所使用的名称:连接的别名、一个点,以及该附加项填充的槽位——例如,填充连接 gpt 上 credential 槽位的附加项名为 gpt.credential。连接的附加项写在其连接条目上——即 Aggregate 中组件 uses: 下的连接,或 Release 中针对同一连接的逐边 uses: 条目——并以该组合名称成为消费方组件的附加项。Release 还会在另外两个作用域中写附加项,其键可以包含点,因此组合名称也可以写在那里:

  • 组件条目自身的 features: 块,附加到该组件。
  • 边界自身的 features: 块,附加到放置在该边界或嵌套于其中的边界内的每个组件——包括该边界未逐一命名而引入的子 aggregate 的组件。其中的某个键只要等于它所触及的任一组件上的组合名称,无论是否指定了 type:,都会导致中止。

构建会停止,而不是将其中任一项合并到连接的附加项中,因为那样的话,两个文档都无法完整展示构建对它所做的处理。套接字的槽位按连接、由连接自身的条目填充,绝不会由从更宽作用域级联下来的附加项填充。如果某个带点的键不是其所触及组件的任何连接附加项所使用的名称,它就是一个普通的附加项名称,不会被拒绝。

该检查涵盖任一文档放在连接上的附加项,既涵盖 Aggregate 声明的组件,也涵盖子 aggregate 贡献的组件。

输出的消息(针对组件条目上的键)。先给出拒绝原因,然后是 Release 和组件条目、Release 写入的键、组件、连接、套接字和槽位——最后是应写入的连接条目:

a Release attachment takes the name of an attachment one of a component’s connections carries (Release <release-name>, at .spec.components.<component>, "<alias>.<slot>", of component "<component>", on the connection "<alias>", through socket "<socket>", in the slot "<slot>"). Write it on the connection entry, under uses.<socket>.<alias>.features.<slot>, and remove "<alias>.<slot>" from this entry’s features: an attachment a connection carries is written on that connection and nowhere else.(某个 Release 附件使用了某个组件的一条连接所携带附件的名称。请将其写在该连接条目上,并从此条目的 features 中移除该键:连接所携带的附件只写在该连接上,不写在其他任何地方。)

输出的消息(针对边界上的键)。它会指明该边界的附加项块,以及其连接携带该附加项的组件:

a Release attachment takes the name of an attachment one of a component’s connections carries (Release <release-name>, at .spec.boundaries.<boundary>.features, "<alias>.<slot>", of component "<component>", on the connection "<alias>", through socket "<socket>", in the slot "<slot>"). Write it on component "<component>"’s connection entry, under uses.<socket>.<alias>.features.<slot>, and remove "<alias>.<slot>" from this boundary’s features: an attachment a connection carries is written on that connection and nowhere else.(某个 Release 附件使用了某个组件的一条连接所携带附件的名称。请将其写在该组件的连接条目上,并从此边界的 features 中移除该键:连接所携带的附件只写在该连接上,不写在其他任何地方。)

如果边界上的某个键触及多个组件,而这些组件的连接都携带该组合名称,则会针对每个组件各报告一次,因为每个连接都需要单独修改。

该发现定位在写入该键的块上——组件条目或边界的 features:——因为键本身包含点,位置无法寻址这样的键;改为在消息中指明该键。在命名了边界的 Release 中,组件条目显示为 .spec.boundaries.<boundary>.components.<component>;在 aggregates: 路由条目中命名的组件通过该条目、以其在那里使用的本地名称来指明;嵌套边界的块显示为 .spec.boundaries.<outer>.boundaries.<inner>.features。

**修复方法:**将该附加项移到 Release 中该连接的条目上——即组件下的 uses.<socket>.<alias>.features.<slot>——若要为 Aggregate 声明的附加项设定规模,只在那里写 infra:;若是仅由 Release 创建的附加项,则写 type: 和 infra:;然后从组件或边界的 features: 中删除该带点的键。面向多个组件连接的边界级键,需要在每个连接上各写一次。

A Release connection attachment names no Feature type(Release 连接附加项未指定 Feature 类型)

Release 的逐边 uses: 条目在某个连接上放置了附加项,其所在槽位在该连接上没有 Aggregate 声明的附加项,且未指定 type:。Release 写在连接上的附加项只能是以下两种之一:要么为 Aggregate 已在同一连接上声明的附加项设定规模,此时无需指定类型,因为 Aggregate 的声明已指定;要么是仅由 Release 创建的附加项,此时 Release 条目是其 Feature 类型的唯一来源。缺少类型时,无法为该附加项选择 FeatureRecipe。

该检查既涵盖 Aggregate 声明的组件,也涵盖子 aggregate 贡献的组件。被 active: 开关关闭的组件会连同其连接一起移除,因此遗留在其上的条目不会被检查。

输出的消息。先给出拒绝原因,然后是 Release 和连接条目、槽位、连接、套接字和组件——最后是处理方法:

a Release connection attachment names no Feature type, and the type is required for an attachment only the Release makes (Release <release-name>, at .spec.components.<component>.uses.<socket>.<alias>, "<slot>", on the connection "<alias>", through socket "<socket>", of component "<component>"). Name the Feature this attachment attaches under its type, or declare the attachment on the Aggregate’s connection entry and size it here.(某个 Release 连接附件未指定 Feature 类型,而仅由 Release 创建的附件必须指定类型。请在其类型下指定此附件所挂载的 Feature,或在 Aggregate 的连接条目上声明该附件,并在此处设定其规格。)

每个违规附件都作为单独的发现项报告,因此一次构建即可列出全部。

**修复方法:**添加 type:,指明该附加项所附加的 Feature;或者,如果该附加项应由开发者声明,则在 Aggregate 的连接条目上连同其 values: 一起声明,并在 Release 条目上只保留 infra:。

Component identity cannot be stamped on what it emits(组件标识无法标记到其发出的资源上)

组件的标识不只是你的 Aggregate 中的一个键——它还是集群中的一个名称。组件发出的每个资源都会以 aggrega.ai/component-id 和 app.kubernetes.io/name 标记该标识,而工作负载合成器也以它为所发出的内容命名。因此,该标识必须是目标能够接受的名称,并且必须名副其实。

你编写的名称会原样进入输出,正因如此,你的 Aggregate 中的名称才是你能在集群中查找到的名称。这一点很有价值,也正是因此,目标会拒绝的标识在这里报告,而不是被悄悄修复成你从未编写过的内容。

只有一个字符是例外,而且你无法写出它:连接模块名称与其内部组件名称的点号。它被保留在你编写的所有名称之外,正是为了让这种连接没有歧义;在标记之前,它会从标识中改写掉——data-layer.main-db 被标记为 data-layer-zdmain-db。这不会占用任何人输入的名称,而且正是它让导入的 Aggregate 所贡献的组件得以被标记:点号不是 Service 名称接受的字符,而且在集群地址中它用于分隔服务与其命名空间,因此作为主机名交给使用方的带点名称会解析到另一个服务,而不是失败。

有两种形式会被拒绝。

标记字母表无法承载的标识。 标识会写入每个发出资源所带的标签值中,该字母表允许字母、数字、-、_ 和 .,并要求该值以字母或数字开头和结尾。编写名称的规则与此相近但不相同——它们允许名称以 - 或 _ 开头或结尾——因此 _api 和 api- 都是你可以编写的名称,但都无法被标记。

这里不检查名称可以有多长。 这取决于组件所部署到的目标,而不同目标的答案不同:此条件涵盖的是任何目标都无法承载的形式。因长度而被拒绝的名称改由目标自身的拒绝报告,其中会给出该目标的原因及其可接受的长度。

以组合标识的方式开头的标识。 Feature 发出的资源无法用你编写的组件名称标记,因此 Aggrega 会用你确实编写的部分为它们组合出一个标识,并在前面加上一个固定的开头,说明该 Feature 附加在何处。当 Feature 附加到单个组件时,标识由该组件和该 Feature 附加时所用的键组合而成,并以 cfr-- 开头。当它附加到整个边界时,没有任何单个组件的名称适用,因此标识由边界的路径和该 Feature 附加时所用的名称组合而成,并以 bfr-- 开头。正是这个开头告诉读者,资源来自这两者中的哪一个,而不是来自某个组件。因此 bfr-- 和 cfr-- 都被保留,不能用作组件标识的开头。 名为 bfr--api 或 cfr--api 的组件会被标记得与组合标识完全相同,而发出的输出中没有任何内容能区分二者。只有完整的开头被保留:名为 bfr、cfr、bfr-api 或 bfrontend 的组件是普通名称,可以正常构建。

该检查读取的是组件实际携带的标识;对于由导入的 Aggregate 贡献的组件,这是限定标识——模块名称、一个点号,再加上组件自身的名称。因此,两个各自都可接受的名称仍可能连接成一个不可接受的标识:名为 bfr--x 的模块与其内部名为 y 的组件连接成 bfr--x.y,它以组合标识的方式开头。该中止会给出连接后的标识,同时指向你编写的键。

针对目标会拒绝的标识,发出的消息:

component identity cannot be the name its emitted resources are stamped with: rename the component (Aggregate, at <field-path>, "<identity>", which must "<rule>")(组件标识不能作为其发出的资源所标记的名称:请重命名该组件;括号内依次为 Aggregate、字段路径、该标识及其必须满足的规则)

针对以组合标识的方式开头的标识,发出的消息如下,其中 <opening> 是该名称所匹配的保留开头:

component identity cannot be the name its emitted resources are stamped with: rename the component (Aggregate, at <field-path>, "<identity>", which must not open with the reserved "<opening>")(组件标识不能作为其发出的资源所标记的名称:请重命名该组件;括号内依次为 Aggregate、字段路径、该标识及其不得使用的保留开头)

修复方法: 在所有提及该组件的地方重命名它——声明它的 Aggregate,以及放置和配置它的 Release。为它取一个以字母或数字开头和结尾、且不以 bfr-- 或 cfr-- 开头的名称。重命名组件会改变其资源在集群中携带的名称,因此对于已部署的应用,请像对待其他任何资源重命名一样处理。

The target will not accept a name derived from an authored identity(目标不接受由编写的标识派生的名称)

每个目标都会从组件的标识派生出自己的名称:chart 安装器派生 release 名称,容器编排器派生服务名称。此终止表示该目标无法使用其中某个名称。

**Aggrega 不持有任何目标的命名规则。**它不知道名称可以多长、目标接受哪些字符,也不知道目标的语法对名称开头有什么要求——这是有意为之,因为这些规则因目标而异,因名称所落到的资源种类而异,有时甚至因同一个 provider 内的某个服务而异。因此,在名称确定之前,编译器会询问将渲染该组件的 provider,此终止报告的就是 provider 的答复。这就是为什么消息中带有目标自己对拒绝对象的称呼(release name、Service name)以及目标自己给出的原因,而不是写入编译器的某条规则。

**为什么拒绝名称而不是缩短它。**你编写的名称就是你的工作负载的部署名称:缩短它会重命名每个现有输出中的每个资源,而且是在你未要求的情况下代你这样做。能够选择另一个名称的人正是编写这个名称的人,因此该终止指向你编写的 spec.components 键,而不改动名称。Aggrega 自己组合的名称——例如挂接到整个边界的 Feature 的标识——则会被缩短,因为它们由分散在多个文档中的部分拼装而成,没有哪一位作者能看到它们最终达到的长度。

**目标可能给出两种答复,它们导向不同的处理。**如果更短的名称可以被接受,该终止会说明可行的长度,这样新名称只需选择一次而不是两次。如果任何长度都无济于事——即目标的语法在某个位置拒绝落在该处的字符——则不说明长度,因为缩短无法解决这个问题。第二类最常见的情况是:名称只允许小写的目标会对每个不接受的字符进行转义,而每个转义都以连字符开头,因此首个字符被转义的名称会生成以连字符开头的名称。要求该位置为小写字母或数字的目标,无论其余部分多短都会拒绝它。目标也可能让名称开头遵循以其命名的资源的更严格规则:helm 目标拒绝以数字开头的名称,并报告为 Service name,因为 Helm 接受这样的 release 名称,而集群会拒绝以其命名的 Kubernetes Service。

第三种形式仅出现在组合名称上:目标可能给出一个比编译器用所给部分能组合出的最短标识还短的长度,因为组合标识会为区分符预留空间。此时该终止会说明这一点并给出补救办法——缩短编写的部分——而不是将 provider 报告为有缺陷。

有些名称只为组件渲染的工作负载而存在。 在该组件的 Workload 解析完成后才会询问 provider,询问中带有该 Workload 的 form 及其 Service 键,因此目标也可以评判它由这些内容构建的名称。在 helm 目标下,这会增加两个名称:一个 CronJob name,最多 52 个字符,且仅针对 scheduled Workload 进行评判,因为集群会以 CronJob 的名称加上后缀来命名每次运行的 Job;以及每个 Service name,即 <release name>-<service key>,最多 63 个字符。Service 名称由两位作者的部分构成——你的组件名称,以及工作负载在 Recipe 或 FeatureRecipe 中声明的键——因此其原因会在你所写字段的旁边,指明该键以及工作负载声明它的位置 spec.workload.services.<key>。若某个键长到不给任何组件名称留下空间,则不会给出可供选择的长度,原因会说明需要缩短的是该键。对于附加到整个边界的 Feature,不会评判这些名称:它的标识在其 Workload 解析之前就已确定,因为其输出在何处组装可能取决于该标识。

针对编写的标识发出的消息:

the target will not accept a name derived from this component’s authored identity: rename the component (component "<identity>", written at <field-path>, which the target cannot use as a <name-kind>, <the target's reason>). choose a name of at most <n> characters that the target accepts(目标不接受从该组件所编写的标识派生出的名称:请重命名该组件,并选择一个长度不超过所述字符数、且目标可以接受的名称)

**修复方法:**在每个命名该组件的位置——声明它的 Aggregate,以及放置并配置它的 Release——将其重命名为目标接受的名称。如果消息说明了长度,请不要超出。如果没有说明,请阅读目标给出的原因:通常是目标不接受的某个字符,最常见的是名称开头的大写字母——或者在 helm 目标下,开头的数字。优先使用小写字母和数字,单词之间用连字符分隔;命名章节说明了在每类目标下名称的代价。如果原因指明了某个 Service 键,也可以在工作负载声明该键的位置缩短它来腾出长度——而如果原因说明该键没有留下空间,则只有这样做才行。重命名组件会改变其资源所带的名称,因此对于已部署的应用,请像对待任何其他资源重命名一样处理。

如果该标识是编译器组合的而不是你编写的,同一终止会报告组合后的值,并要求你缩短构成它的部分——你挂接 Feature 所用的名称,以及你挂接到的边界路径。

A provider never accepted a name the compiler composed(provider 始终不接受编译器组合的名称)

此项报告的是插件中的缺陷,而不是你编写的任何内容中的问题。

确定组合名称是一个交换过程:编译器提出一个标识,provider 要么接受,要么说明需要缩短到多短,编译器再组合一个更短的标识,然后再次询问 provider。第二次拒绝是正常且预期的——缩短到某个长度可能使某个字符落在目标语法不允许的位置,而 provider 指出这一点,正是不了解任何目标语法的编译器与了解语法的 provider 达成一致的方式。

不正常的是始终不接受任何名称的 provider:它给出一个长度,收到该长度的名称后又再次拒绝。这个交换过程有上限,达到上限时构建会停止并指出该 provider,而不是使用 provider 从未同意的名称。通过放弃而确定的名称会被标记到真实资源上,而输出中没有任何记录表明未达成一致,其后果会在 apply 时才显现,而不是在生成它的构建中。

发出的消息:

provider guest never accepted a component identity the compiler composed for it (provider guest "<provider>", refused <n> proposals, the last of them "<identity>"). report the defect to whoever maintains that provider plugin(provider guest 始终未接受编译器为其组合的组件标识:请将该缺陷报告给该 provider 插件的维护者)

**修复方法:**将其报告给所指 provider 插件的维护者,并引用消息中的最后一个提议。没有任何编写层面的更改可以绕过它:编译器已经提供了 provider 要求的每个长度。如果该 provider 由你维护,需要检查的是:按其给出的上限截断的名称,之后确实会被它接受。

Required uses: socket not populated(必需的 socket 未填充)

某个 Component 在其 usesSchema 中声明了一个标记为 required: true 的插槽,而对于该 Component 的某个实例,构建中没有任何内容在该插槽上连接一条连接。

**有三个位置可以连接它,只有三者都为空时才会触发该中止。**Aggregate 中该实例自身的 uses: 块;Release 中指定了 target: 的逐边 uses: 条目,它会在一个已声明但未绑定的插槽上创建连接;以及组合产生的连接集合,对于由导入的 Aggregate 提供的组件,由它来负责——这类组件的 uses: 块位于该 Aggregate 自己的文档中,只有在组合组装完成后才会读取。由于第三个位置最后才完整,检查会在整个组合存在之后运行,而不是在读取两个编写的文档时运行,并且无论组件由哪个文档声明,都会对每个组件提出同样的问题。

有两种看似应当填充该插槽的形式实际上并不会。未指定 target: 的 Release 条目配置的是一条必须已经存在的连接,而不是创建一条,因此它不连接任何内容(并且当它带有 infra: 时,会由上文中它自己的中止报告)。而 Feature 附件的 uses: 指定的是所附加 Feature 上声明的插槽,这是另一个实体上的另一组插槽,因此附件永远无法填充 Component 自身的插槽。

发出的消息:

required uses socket not populated (Component, at .spec.components.<instance>.uses.<socket>, "<socket-name>", declared required by component type "<component-type>")(必需的 uses socket 未填充:所示位置的该 socket 由所示组件类型声明为必需)

该发现定位在作者需要编写的插槽条目 .spec.components.<instance>.uses.<socket> 上。其中的实例名是组件在声明它的文档中所使用的名称,因此对于由导入的 Aggregate 提供的组件,该定位符指向的是该 Aggregate 自身文件中包含的键,而不是组合赋予它的带前缀名称。

每个组件上每个未填充的必需插槽都会被报告:一次构建会告诉你所有这些问题,而不只是第一个。

**修复方法:**为该必需插槽添加一个 uses: 条目,将其连接到该插槽的 selector: 接受的目标;或者在 Release 中使用指定了 target: 的条目来连接它。如果该插槽不应再是必需的,请更新该 Component 的 usesSchema,设置 required: false 或移除 required 声明。

Sub-aggregate nesting depth exceeded(子 aggregate 嵌套深度超限)

一条子 aggregate 导入链超过了编译器的最大嵌套深度。该限制可防止深度嵌套的拓扑失控展开,并在超过阈值时迫使进行架构拆分。

发出的消息:

max sub-aggregate nesting depth exceeded: depth <depth> at prefix <flattened-prefix>.(超出子聚合的最大嵌套深度:在对应前缀处达到对应深度。)

**修复方法:**重构 aggregate 拓扑以减少嵌套。如此深的嵌套通常表明 Aggregate 的结构反映的是组织层级而非部署拓扑——可以考虑将若干组子 aggregate 展平为同一个父 Aggregate 中的对等子系统。

Feature type mismatch between Aggregate and Release(Aggregate 与 Release 之间 Feature 类型不匹配)

Aggregate 和 Release 都以相同的实例名称附加了一个 feature,但各自声明了不同的 type:,而 Release 的附件是从某个边界的 features: 到达该组件的。如果 Release 改为在其针对该组件的条目上书写它,同样的冲突会更早被拒绝,并作为 E0153 报告,见上文“A feature attached by both the Aggregate and the Release cannot be merged(Aggregate 和 Release 同时附加的 feature 无法合并)”。

发出的消息:

feature type mismatch between Aggregate and Release (node <node-id>, attachment <instance-name>, existing type <type-in-aggregate> conflicts with <type-in-release>)(Aggregate 与 Release 之间的 feature 类型不匹配:该节点上该附加项在 Aggregate 中的已有类型与 Release 中的类型冲突)

**修复方法:**要么从 Release 中去掉 type:(它将继承 Aggregate 的类型),要么修改其中一方,使两者声明相同的类型。Release 可以省略 type: 或重复 Aggregate 的类型,但不能替换为不同的类型。

Cyclic extends on Components or Features(Components 或 Features 上的循环 extends)

某个 Component 的 extends: 链或某个 Feature 的 extends: 链回绕到了自身。

发出的消息,当形成循环的是 Feature 链时,以 Feature 代替 Component:

cyclic extends chain (Component <name>, rule extends). <entity> extends <reference>, which is already in the chain; remove the extends on <entity>, or point it at an entity outside the chain(extends 链存在循环:某实体所继承的引用已在链中;请移除该实体上的 extends,或将其指向链外的实体)

**修复方法:**打开该边所指的实体——在三个或更多实体组成的链中,它并不是消息开头所指的实体——然后移除其 extends: 或将其重新指向。

A component the composition holds is placed in no boundary(组合中的某个组件未放入任何边界)

Release 可以通过两种方式将组件放入边界,任一种都有效。一种是在某个边界的 components 下指定该组件,以整个组合展平后组件所使用的 id 来寻址。另一种是在 aggregates 下将提供该组件的模块路由到某个边界,这会一次性放置该模块包含的所有组件。

两种方式都未覆盖的组件会渲染在 Release 声明的所有边界之外。此时它的输出目录、同步波次、注解以及逐组件的 infra 都无从获得——而构建本会成功、输出产物,并且对运维人员的配置从未应用于它这一点只字不提。被这条界线分开的两个组件还会渲染到不同的输出中,失去它们放在一起时所具有的顺序。

有两种形式刻意不会触发它。声明顶层 components 而非命名边界的 Release 会放置它所列出的所有组件:规范化这样的 Release 时,会为其生成一个恰好包含这些组件的专属边界。而对于其整个模块都未被 Release 放置的组件,则改为针对该模块报告一次,见下文条目——一个错误、一种修复、一个要编辑的键——而不是对每个自身声明正确的组件各报告一次。

发出的消息。末尾的值是组合展平后组件所使用的 id,对于由模块提供的组件,它是该模块的名称、一个点号,再加上组件自身的名称:

component placed in no boundary: name it under a boundary’s components, or place the sub-module that contributes it under aggregates (Release <name>, at <authored key>, "<component-id>")(组件未被放入任何边界:请在某个边界的 components 下列出它,或将贡献它的子模块放在 aggregates 下)

**修复方法:**在某个边界的 components 下指定该组件,并严格使用消息中引用的 id——对于由模块提供的组件,这是带前缀的 id,而不是模块自身文件中写的名称。或者,当整个模块都属于同一个边界时,在 aggregates 下将其路由到该边界,使其包含的所有组件一次性得到放置。

子模块的组件未放入任何边界

上一条规则的模块级形式:组合引入的某个模块贡献了组件,但没有任何边界容纳其中任何一个。它按模块报告一次,而不是按组件逐个报告,因为一个未放置的模块是一个编写错误,只有一种修复方式、对应一个键——按组件报告则会点名那些自身声明完全正确的组件。

该规则检查的是放置情况而非写法,因此如果一个模块的每个组件都在某个边界的 components 下被逐一点名,该模块即视为已放置并通过检查:因缺少路由条目而拒绝它,会否定语言所允许的一种编写形式。仅部分放置的模块同样通过——它的哪些组件有自己的条目是组件规则要回答的问题,遗漏的组件会在那里报告,各自定位到自己的键。

未贡献任何组件的模块不会触发此错误:没有需要放置的内容。被值为 false 的 active: 开关移除的模块也不会触发,因为它根本未被组合。

发出的消息,定位于声明该模块的 aggregates 条目,使用导入文档所写的本地名称:

sub-module placed in no boundary: route it into a boundary under aggregates, or name its components there under components (Release <name>, at <authored key>, "<module-path>")(子模块未被放入任何边界:请在 aggregates 下将其路由到某个边界,或在 components 下逐一列出其组件)

修复方法: 在该模块所属的边界下为其添加一个 aggregates 条目,这会放置它贡献的每个组件。或者,若其组件属于不同的边界,则在各自所属的边界下逐一点名,使用它们展平后携带的带前缀 id。

边界点名了组合中不存在的组件

这是上面两条规则在多余点名方面的对应规则,是一个独立的问题,而非其中任何一条的分支:那两条针对组件询问是否有东西放置了它,这一条针对 Release 写下的条目询问是否有东西与之对应。两者互不蕴含。Release 可以点名一个不存在的组件,同时每个存在的组件都已正确放置;它也可以遗漏一个真实组件未放置,同时它写下的每个条目都能解析。

不指向任何东西的条目不配置任何东西:它的 directory、subDirectory、syncWave、注解和按组件的 infra 是为一个不存在的组件编写的,因此不会有任何内容在它们之下渲染,否则构建会成功,而运维人员的配置会悄无声息地失效。

边界有两种方式点名组件,两者都会被检查。在 components 下,条目通过组合展平后组件携带的 id 来寻址——因此模块贡献的组件要在其自身名称前写上该模块的前缀。在 aggregates 路由条目内,条目通过组件在该模块内携带的本地名称来寻址,它解析为同一个 id。消息引用的是条目所寻址的 id,在路由这一维度上,它并不是文件所写的名称:文件携带本地部分,模块补足其余部分。

子系统不会为组件的 id 贡献任何内容,因此在子系统内声明的组件以其裸名称寻址。把子系统当作 id 一部分来编写的条目不指向任何东西,会触发此错误。

被值为 false 的 active: 开关关闭的组件不会触发此错误。关闭组件是一种编写行为,不要求在同一次编辑中改写配置它的 Release——拒绝该条目会导致只要还有任何 Release 点名该组件,开关就无法使用。

发出的消息:

boundary names a component the composition does not hold: correct the name, or remove the entry (Release <name>, at <authored key>, "<addressed id>")(边界列出了组合中不存在的组件:请更正名称,或删除该条目)

修复方法: 将消息引用的 id 与组合中实际存在的组件进行比对。缺少模块前缀和把子系统名称写入 id 是两种常见原因;去掉子系统、加上模块前缀,或更正拼写。若该条目是已删除或已重命名组件的遗留条目,请删除它。

uses 边的目标组件已被 active: 开关移除

这是上文悬空目标中止的姊妹情况,单独报告是为了告诉作者目标缺失的原因。目标缺失并不是因为从未声明——它已声明,只是因为其 active: 开关解析为 false 而被有意从本次构建中移除,连同它的边一起。某个保留下来的组件仍然依赖它,如果任由这条边消失,该使用方注入的值会在部署时悄无声息地为空。

发出的消息。先是拒绝原因,然后是被开关移除的目标以及连接所接入的插槽——最后是处理办法:

uses edge target was pruned because its active toggle resolved to false ("<target>", wired into socket "<socket>"). Keep the target’s active toggle true, or drop the dependency on it.(uses 边的目标因其 active 开关解析为 false 而被移除。请将目标的 active 开关保持为 true,或删除对它的依赖。)

该问题定位于其所涉及的编写条目,路径与上文悬空目标中止所指的相同,并且会报告每一个有问题的连接,而不仅是第一个。

修复方法: 判断两者中哪一个应属于此环境。重新开启目标——若其开关读取某个参数,则意味着为此 Release 提供该参数。或者让使用方也受同一开关控制,使两者一同移除,不留下指向空处的边。或者,若使用方确实不再需要它,从使用方的 uses: 块中删除这条边。

A uses target names a module’s component the module does not export(uses 目标指向了模块未导出的组件)

模块在 exportedComponents: 下发布其接口,导入该模块的文档只能通过这些名称到达模块的组件:模块名称、一个点,以及其别名之一。以任何其他方式到达模块内部组件的 uses: 目标——通过组件在模块内的名称,或通过穿过该模块进入其内部嵌套模块的路径——都会使构建中止,因为该连接会绑定到模块作者未发布、且可以随意重命名或删除的东西上。组件自身的 uses: 块、附件的块以及由 Release 连接的连接都同样受此约束。连接会进入哪些模块,是根据其消费方所在的位置读取的,因此同一模块中两个组件之间的连接——包括 Release 将它们彼此相连的情况——不跨越任何接口,不会被拒绝。不对应任何组件的目标改由悬空目标中止报告,因此一个拼错的名称只会报告一次。

输出的消息。首先是拒绝,然后是所写的目标、它所进入的模块及该模块导出的别名,以及 socket——然后是应如何处理:

uses edge target names a component its module does not export ("<target>", module "<module>", which exports "<aliases>", wired into socket "<socket>"). Name the component through one of the module’s exported aliases, or list it under the module’s exportedComponents.(uses 边的目标指向了其模块未导出的组件(依次为目标、模块及其导出的别名、所接入的 socket)。请通过模块导出的别名之一指向该组件,或将其列在模块的 exportedComponents 下。)

不导出任何内容的模块会被表述为导出 "nothing"。该发现定位于绘制该连接的文档中所写的条目。

**如何修复:**通过模块导出的别名指向该组件——用 finance-db-subsystem.primary_db 而不是 finance-db-subsystem.internal-pg-primary——或者,如果模块由你编写且你打算发布该组件,请将其列在模块的 exportedComponents 下;如果导入方应使用其自身名称,就以其自身名称列出。

active: 开关未解析为 true 或 false

active: 开关到达图构建器时已解析为字面量——要么是直接写下的布尔值,要么是在读取文档之前已代入 Release 值的参数引用。随后它被严格读取:非布尔值的字面量会中止构建,而不是回退到任何默认值。组件的开关和模块的开关适用同一规则。

空字面量是值得单独说明的情况,因为未满足的参数产生的正是它。读取 {{ .parameters.<key> }} 的开关在该参数没有值时解析为空,若把空读作“存在”,就会部署作者特意用该参数控制的那个实体。只有无人编写的开关才默认为存在,而这是根据开关的缺失而非其值来判断的——这就是为什么写下 active: 而后面什么都不写,与省略该键并不相同。

发出的消息:

active toggle did not resolve to a boolean (node "<node>", active resolved to "<value>")(active 开关未解析为布尔值)

若它解析为空,则附带指出常见原因的建议:

active toggle did not resolve to a boolean (node "<node>", active resolved to ""). a toggle reading a parameter resolves to nothing until that parameter is fulfilled(active 开关未解析为布尔值。读取参数的开关在该参数被满足之前解析为空)

修复方法: 写入 true 或 false。若开关读取某个参数,请在 Release 中提供该参数,或在 Aggregate 中声明该参数处为其设置 default:,使每个环境都有值。要使实体无条件存在,请删除 active: 键,而不是将其留空。

A module a composition imports cannot be loaded, or imports itself(组合导入的模块无法加载,或导入了自身)

一个 Aggregate 通过在 aggregates: 下命名其他 Aggregates 来组合它们,并依次加载和遍历每一个,使其组件加入图中。在这里,有两种情况会中止这一遍历。

一是模块根本无法加载:该引用解析不到目录能够返回的任何内容,或者其背后的文档无法读取。加载器给出的原因附在该中止之下,而不是并入其中,因此失败的内容以加载器自己的措辞报告。

二是模块命名了一个已经位于正在遍历的链上的类型。展开它会重现包含它的那条链,永无止境。该问题在引用闭合环路的位置报告,并同时指出该类型及其在组合中所处的位置。

针对循环引用发出的消息:

sub-aggregate load failed (circular sub-aggregate reference "<module-type>", at "<path in the composition>")(子聚合加载失败:存在循环的子聚合引用,位于组合中的上述路径)

针对加载失败,该中止仅显示这一句,定位在模块的路径上,加载器自己的原因附在其下:

sub-aggregate load failed(子 aggregate 加载失败)

**修复方法:**对于加载失败,阅读该中止下方的原因:常见情况是目录无法响应的名称或版本,修正应写在命名它的 aggregates: 条目中。对于循环引用,需打破环路:消息中的路径是链闭合之处,沿途的某个模块必须停止导入那个导入它的模块。如果两个模块确实需要彼此的组件,共享部分应放入两者都导入的第三个模块。

Two instances flatten to one identifier(两个实例展平为同一个标识符)

组合一个 Aggregate 会把所有组件展平为单一集合,模块贡献的组件带有该模块的名称、一个点号以及它自己的名称。该集合拒绝在同一标识符下保存两个条目:第二个会替换第一个,两个组件之一会在没有任何提示的情况下从输出中消失。

该中止在合并模块的组件时触发,而编写界面并不提供会导致它的名称。模块贡献的每个组件都在自身名称前带有该模块的名称;实例名称由字母、数字、- 和 _ 组成,因此不能包含用于连接两者的点号,由不同模块名称构建的两个标识符也就不可能相同。以同一名称导入的两个模块是一个重复键,文档会在加载时被拒绝。因此,这是针对通过普通编写路径以外的方式组装的组合的兜底检查,遇到它时值得报告,而不是绕过它。

同一个 Aggregate 的两个组件得到同一个标识符是另一种中止,而且普通的编写就会导致它,参见下文的 Two subsystems declare a component under one name(两个子系统以同一名称声明组件)。

发出的消息:

flattened node ID collision: rename one of the colliding instances so their flattened IDs differ (id "<identifier>", path "<path in the composition>", collides with existing entry from "<the other contributor>")(扁平化后的节点 ID 冲突:请重命名其中一个冲突的实例,使其扁平化后的 ID 不同;该 ID 与另一贡献方已有的条目冲突)

**修复方法:**重命名消息所指的两个实例之一,既要在声明它的文档中修改,也要在每个引用它的 Release 条目中修改。

Two subsystems declare a component under one name(两个子系统以同一名称声明组件)

子系统为读者以及向下级联的内容对一个 Aggregate 的组件进行分组;它们不会限定组件所对应的名称。在 subsystems.frontend 下声明的组件以 api 寻址,而不是 frontend.api;模块贡献的组件带有该模块的名称,而不是子系统的名称。因此,同一个 Aggregate 的两个子系统可以各自声明一个名为 api 的组件,而这两者随后会对应同一个标识符。

该文档格式正确:两者是不同代码块中的不同键,这正是之前没有任何环节拒绝它的原因。但一个标识符只能属于一个组件。构建会中止,而不是保留最后读取的那个并像只声明了一个组件那样进行渲染。

在同一个子系统中两次使用同一名称是另一种错误:那是同一键下的两个条目,文档会在读取时被拒绝。

发出的消息:

components in different subsystems take the same identity: rename one of them, since a subsystem contributes nothing to a component’s identity (Aggregate, at .spec.subsystems.<second>.components.<identifier>, "<identifier>", declared under subsystems "<first>, <second>")(不同子系统中的组件具有相同的标识:请重命名其中一个,因为子系统不参与构成组件的标识)

**修复方法:**重命名两个组件之一,既要在声明它的文档中修改,也要在每个引用它的 Release 条目中修改。如果两者确实是希望出现在两处的同一组件,则只声明一次,并从另一个子系统依赖它。重命名子系统无济于事:子系统不是名称的一部分。

A re-published component alias points back at itself(重新发布的组件别名指回自身)

模块通过以别名导出组件来发布自身的一部分,导入它的 Aggregate 可以用自己的名称重新发布其中某个别名。解析这样的别名时,会沿着重新发布的链一直追溯到它最终指向的组件,使指向公开名称的边能够到达一个真实组件。

在到达组件之前重新访问某个别名的链永远不会落地。遍历会停止,而不是无限追溯下去,并指出它所遍历的链,使闭合环路的那一环可见。

你能编写的任何内容都不会产生这样的链。导入树是无环的,且每一环所指的内容都比前一环嵌套得更深,因此由导入组装的链会逐层下降并终止。因此,这是针对通过普通编写路径以外的方式组装的别名表的兜底检查,而不是针对 Aggregate 可以声明的某种结构。

发出的消息:

re-exported component alias forms a cycle (alias chain <first> -> <second> -> <first>)(重新导出的组件别名形成了循环,见所示别名链)

**修复方法:**你的文件中没有任何内容会导致它,也没有可以消除它的编写修改。请报告该问题,并附上你运行的命令以及消息所指出的别名链,该细节说明了环路在何处闭合。

An Aggregate reached graph building without being normalised(Aggregate 未经规范化就进入了图构建)

在顶层写组件的 Aggregate 与使用命名子系统编写的 Aggregate,在读取时会变成同一种结构:顶层组件被并入编译器提供的一个子系统,顶层则被清空。正是这一合并让下游所有环节都能对同一种结构提出同一个问题。

进入图构建时两者都已填充的 Aggregate 并不是由上述读取过程产生的。两种结构在编写时互斥(同时声明两者的文档会在加载时被拒绝),而合并则在之后使它们成为同一种结构,因此作者能编写的任何内容都不会到达这里。这是针对通过普通加载路径以外的方式组装的 Aggregate 的兜底检查,遇到它时值得报告,而不是绕过它。

其消息开头为:

aggregate reached topology un-normalized (non-empty root components alongside a synthesized default subsystem)(aggregate 未经规范化就进入了拓扑(非空的根组件与合成的默认子系统并存))

随后是编译器预期的构造路径,这是给调试构建的人看的说明,而不是编写指引。

**修复方法:**你的文件中没有任何内容会导致它,也没有可以消除它的编写修改。请报告该问题,并附上你运行的命令。

label-transform 插件的补丁超出了节点标签的范围

以 label-transform 角色挂接的治理插件会拿到图的一个投影——每个节点一个条目,携带该节点的标签以及其实例所声明的值,其中其 Component 声明为敏感的值会被隐去——并返回针对节点标签的补丁。宿主只将这些补丁应用于标签,然后检查返回的结果是否仍是那个标签视图:节点相同,每个节点只携带标签,每个标签值都是字符串。

其他任何情况都会被拒绝,构建随之停止。添加或删除节点,或修改节点中标签以外的字段,恰恰就是无人声明的基础设施悄然出现——因此,构建不会吸收该角色不涵盖的更改,而是指出补丁违反了哪条限制规则。标签是该角色的全部作用面,挂接插件的操作者声明的正是这些,仅此而已。

发出的消息。补丁在应用之前被拒绝:

mutator patch rejected: patch <n> does not decode as a JSON Patch document: <what the reader could not do>(变更器补丁被拒绝:该补丁无法解码为 JSON Patch 文档) mutator patch rejected: patch <n> does not apply to the node-label surface: <what the patch engine refused>(变更器补丁被拒绝:该补丁无法应用于节点标签视图)

或者应用补丁后的结果不是宿主交出的那个视图:

mutator patch rejected: mutated node set changed size (a mutator may not add or remove nodes)(变更器补丁被拒绝:变更后的节点集合大小发生了变化(变更器不得添加或删除节点)) mutator patch rejected: mutated node set introduced node "<node>" (a mutator may not add nodes)(变更器补丁被拒绝:变更后的节点集合引入了新节点(变更器不得添加节点)) mutator patch rejected: node "<node>" gained a field outside "labels" (a mutator may only touch labels)(变更器补丁被拒绝:节点获得了标签之外的字段(变更器只能修改标签)) mutator patch rejected: node "<node>" lost its "labels" field(变更器补丁被拒绝:节点丢失了其标签字段) mutator patch rejected: node "<node>" carries a non-string label value after patching: <what the reader found>(变更器补丁被拒绝:应用补丁后节点带有非字符串的标签值)

**修复方法:**问题出在插件,而不在你的文档。修正插件,使其返回的每个操作都指向某个节点 labels 下的条目,并且只设置字符串值——常见的情况是数字或布尔类型的标签值,因为该作用面只接受字符串。在修正插件期间,从 plugins.governance 中移除该挂接是让构建立即恢复的办法。

有意省略:拓扑不要求无环

Aggrega 允许拓扑中存在环:它不要求依赖图是有向无环图。智能体到智能体的架构、回调模式以及双向认证对都会产生成环的边,编译器会接受它们。部署时的顺序由渲染器负责(通过按边界设置的 syncWave 或等效机制),而不是由 IR 图负责。

检查 inject 契约时

编译器遍历每个 inject: 块——包括 self-inject(Component 注入自身)和 uses-inject(跨 Component 连接)——并根据目标 Component 的 provides: schema、Feature 的标签分区以及已声明的投递键集合来校验投递契约。Aggregate 自身组件所写块上的 from: 键在目录解析完成后立即检查,因此会针对你所写的那一行报错;模块所贡献组件的块上的此类键在导入该模块的组合构建完成后检查,并针对模块自身文档中的那一行报错;由已附加 Feature 贡献的连接上的 from: 键,则在每个能够绘制连接的表面都完成贡献后才检查,这是此类连接可供检查的最早时间点。

注入的 from 键不在目标的 provides 中

某个 inject: 条目引用了一个 from: 键,而它所读取的来源并未发布该键:对于组件自身的块或连接,来源是目标 Component 的 provides: schema;对于附加的 Feature 自身的 inject: 块,来源是该附加 Feature 的 FeatureRecipe。

无论连接写在何处,检查都适用。 一个 uses: 连接可以从多个编写表面进入构建出的拓扑——Component 自身的 uses: 块,以及附加到它的 Feature 的 uses: 块,无论该附加写在组件上、子系统上、Release 边界上,还是 Release 边界的组件条目上——同一个拼错的键在每一处都会被拒绝。诊断指向编写它的作者所在的块:即附加自身的 uses: 条目,位于声明该附加的位置,而不是消费组件的 uses: 块,因为对于被贡献的连接,该块中什么也没有。

引用解析到何处取决于它所在的位置。Component 级 self-inject 的 from: 针对同一 Component 自身的 provides: 解析。uses: 连接上的 from: 针对该连接所指向组件的 provides: 解析——当两个表面写入同一个 socket 和同一个别名时,每个连接都针对它自己所指定的目标解析,而同一次构建会因二者共享别名而拒绝这一对。未声明 provides: 的 Component 会拒绝所有指向它的 from: 引用。

附加的 Feature 自身的 inject: 块。 此处的 from: 针对该 Feature 的 FeatureRecipe 在其 provides: 中发布的键进行解析,按该 Feature 所附加到的组件求值,并在该组件渲染时检查。FeatureRecipe 未发布的键不会向组件的环境、文件或参数中放入任何内容,因此构建会停止——除非 FeatureRecipe 自己读取附加 Feature 的条目,即在 .inject 处、在它针对附加 Feature 自身渲染上下文求值的模板中读取;该上下文就是携带 .inject 的那个:它的值映射、它的工作负载、它的制品、它的省略项,或某个流水线步骤的 with: 或 when:,无论是内联编写还是导入的。它的 locals:、provides:、source: 和 assertions: 不携带 .inject,而它的 injectMapping: 是针对组件的上下文求值的,因此在其中任何一处的读取都不算数。这样的 FeatureRecipe 会按编写原样接收每个条目,并以自己的方式交付,因此它的条目不会被拒绝;它未发布的键不会通过组件自身的交付传递任何内容,而是留给该 FeatureRecipe 使用。FeatureRecipe 是否读取 .inject,取决于其模板所指定的路径:将整个上下文传递出去的模板(toJson .),或通过诸如 index . "inject" 之类的函数访问条目的模板,都不算读取这些条目,其指定未发布键的条目会被拒绝。附加在某个边界上、其 FeatureRecipe 针对该边界只渲染一次的 Feature,会针对那一次求值进行检查;如果没有任何包含该组件的边界产生过这样的求值,就没有可用于检查其键的依据,这些键也不会被拒绝。指定已发布键的 from: 照常交付。该发现定位在附加 Feature 自身的条目上,位于编写它的文档中——例如 Aggregate 中的 .spec.components.<component>.features.<attachment>——而如果某个条目的交付键也已被另一个 inject 来源持有,它还会在“An attachment delivers a key another inject source already claimed(某个附加项交付了另一个 inject 来源已占用的键)”下报告,因为二者各需各自的修复。

在组件自身的 inject: 块上,value: 条目携带的是字面值,不针对任何内容解析,因此恰好看起来像 provides 键的字面值在那里不会被拒绝;在连接上,value: 条目会被拒绝,如下文“An inject: entry on a connection carries a literal(连接上的 inject 条目携带了字面值)”所述。只有 from: 指定键。

Release 自身的逐边 uses: 表面携带 target 和 infra,不带 inject:,因此在那里连接的连接不指定任何投递,也没有需要检查的 from: 键。

对于在 Component 自身 inject: 块上读取的 from:,发出的消息如下。先是拒绝原因,然后是出错的键、解析所针对的组件类型,以及该类型按排序列出的已声明键——即可供选择的替代项:

invalid inject key: the from-key must name a provides key its source publishes (Aggregate <name>, at .spec.components.<component>.inject.<mechanism>.<delivery-key>, "<from-key>", "<component-type>", "<key-1>", "<key-2>")(无效的 inject 键:from-key 必须指定其来源所发布的 provides 键)

对于在 uses: 连接上读取的 from:,消息同样以该拒绝原因开头,并且条目所在的机制和投递键排在出错的键之前:

invalid inject key: the from-key must name a provides key its source publishes (Aggregate <name>, at .spec.components.<component>.uses.<socket>.<alias>, "<mechanism>", "<delivery-key>", "<from-key>", "<component-type>", "<key-1>")(无效的 inject 键:from-key 必须指定其来源所发布的 provides 键)

对于在附加 Feature 自身的 inject: 块上读取的 from:,出错的键排在最前面,然后是该条目的 in: 和机制、解析时所依据的 FeatureRecipe,以及该 FeatureRecipe 发布的每个键,按排序顺序列出:

invalid inject key: the from-key must name a provides key its source publishes (Aggregate <name>, at .spec.components.<component>.features.<attachment>, "<from-key>", in "<in>", mechanism "<mechanism>", FeatureRecipe "<feature-recipe>", publishes "<key-1>", publishes "<key-2>")(无效的 inject 键:from-key 必须指定其来源所发布的 provides 键)

当目标完全未声明 provides: 键时,没有可列出的替代项,因此消息在组件类型之后结束——或者在附加 Feature 的块上,在 FeatureRecipe 之后结束。

修复方法: 将 from: 键改为消息中列出的某个已声明键,或者扩展目标 Component 的 provides: schema,声明你所需的键。在附加 Feature 的块上,将 from: 键改为 FeatureRecipe 发布的某个键;或者——如果该 FeatureRecipe 是你的——在其 provides: 中发布该键;或者,如果它以自己的方式交付该值,让它自己在 .inject 处读取该条目。

Required feature not attached(未附加必需的 feature)

该 Component 声明了一个存在性强制要求——即 features.aggrega.ai/requiredType.<label> 注解——所指定的 Feature 类型不在此组件实例最终拥有的附加项中,统计范围涵盖所有作用域:Aggregate 的组件级和子系统级块、Release 的边界级和组件级块,以及注解驱动的展开。

发出的消息:

missing required feature: attach a Feature of the required type to the component (<required-type>, required by component type <component-type>, under the requirement label <label>)(缺少必需的 feature:请将所需类型的 Feature 附加到该组件)

三个值依次是强制要求所需的 Feature 类型——上面的句子已提到它,因此它不带说明——然后是声明该强制要求的组件类型,以及该强制要求携带的标签,后两者各带说明,以便读者区分两个实体引用。要求两种不同类型的组件会报告两条不同的消息,而从不同类型声明该强制要求的两个组件会被告知各项要求来自哪个类型。报告定位在该组件于 components: 下的自身键上,写在子系统内的组件则先定位到该子系统的键下。

附加项所用的名称在此无关紧要:强制要求只检查是否存在指定类型的附加项。绑定一个 slot 可以满足它,以任何其他名称写的附加项也可以。

修复方法: 在 Aggregate 或 Release 中将所需类型的 Feature 附加到该组件,或附加到该组件继承的更大作用域上。如果该 Component 不应再要求它,请从其目录声明中移除该强制要求注解。

Malformed attachment requirement(格式错误的附加要求)

存在性强制要求的声明无法求值。注解值是不透明的字符串,因此在编译器读取之前,没有任何东西校验其格式:不是 Feature 类型 URI 的值,或者指定了强制要求族但前缀后没有标签的键,会被报告为损坏的声明,而不是未满足的要求——拼写错误绝不能被当作已满足的要求。

输出的消息:

附加要求格式错误(<key>,由组件类型 <component-type> 声明,无法求值,因为该值必须是形如 <publisher>/<name> 的 Feature 类型 URI,各段为小写 kebab 格式,例如 core/prometheus-exporter)。请在该组件类型的目录实体上更正该注解。

附加要求格式错误(<key>,由组件类型 <component-type> 声明,无法求值,因为该键需要一个为该要求命名的标签,例如 features.aggrega.ai/requiredType.database)。请在该组件类型的目录实体上更正该注解。

消息以注解键开头——即该中止所涉及的声明——随后指出声明损坏的组件类型,因此即使报告定位在使用该类型的组件实例上,它也指明了需要更正的实体:实例是你看到问题的地方,而目录实体是修复问题的地方。

此中止在组合装配完成时立即触发,早于所有读取最终图的检查。因此,带有损坏强制要求的构建只会单独报告它:之后本应运行的检查不会执行,因为它们需要依据声明的内容进行推理,而该声明无法读取。更正它并重新构建即可看到其余问题。

修复方法: 更正 Component 目录实体。修复位于目录中,而不在 Aggregate 中——这正是此中止区别于“Required feature not attached(未附加必需的 feature)”的原因,后者需要修改的是你自己的文档。

Required attachment slot not bound(必需的附加槽未绑定)

某个目录实体在其 featuresSchema 中声明了带 required: true 的附加槽,而该实体的某个实例上没有任何内容绑定该槽的名称。该检查针对所有作用域折叠之后实例最终拥有的附加项进行——包括 Aggregate 的组件级和子系统级 features: 块、Release 的边界级和组件级块,以及由注解驱动扩展产生的附加项——因此,在实例所继承的某个作用域上附加一次的凭据,与在实例上编写的填充一样,都能绑定该槽。

发出的消息:

required attachment slot unfilled (<slot>, declared required by component type <component-type>). Attach a Feature at that name, in the Aggregate or in the Release, on the component or at a scope above it.(必需的附加槽位未填充:该槽位由所示组件类型声明为必需。请在 Aggregate 或 Release 中,在该组件上或其上层作用域中,以该名称附加一个 Feature。)

这两个值是槽本身的名称和声明该槽的组件类型,因此一个实例有两个槽未绑定时,会报告两条不同的消息。报告定位于 Aggregate 中该组件 features: 块下该槽的键;由于缺失的正是这个键,编辑器会把它放在最近的已存在的键上——组件写了 features: 块时放在该块上,没有写时放在组件本身上。缺失的附加项没有人编写,因此不会单独归咎于任何文档的作者:报告停留在组件上,并作为开发者错误归档;修复建议同时提及两份文档,因为任一份都可以填充该槽——Aggregate 可在该组件或包含它的子系统上填充,Release 可在该组件的条目或包含它的边界上填充。

由套接字声明的槽——位于某个 usesSchema 条目的 featuresSchema 中——是对通过该套接字连接的每个连接的要求,而不是对组件的要求:每个连接都要在 Aggregate 或 Release 中各自的条目上自行填充它,上层作用域无法触及它。因此,一个有两个连接的套接字,若其中一个填充了该槽,则只报告另一个,并指明其名称:

required attachment slot unfilled ("<slot>", declared required by socket "<socket>", of component type "<component-type>", left unfilled by the connection "<alias>"). Attach a Feature under that slot in this connection’s features, on its entry in the Aggregate or in the Release.(必需的附加槽位未填充:该槽位由所示组件类型的所示 socket 声明为必需,所示连接未填充它。请在该连接的 features 中、在其于 Aggregate 或 Release 中的条目上,以该槽位附加一个 Feature。)

该报告定位于绘制该连接的文档中该连接的条目——Aggregate 的 uses: 条目,或者对于由 Release 连接的连接,是 Release 的逐边条目。由已附加的 Feature 绘制的连接,连接到的是该 Feature 声明的套接字,而不是组件的套接字,因此组件的套接字槽不由它填充。

**如何修复:**在 Aggregate 或 Release 中,以该槽的名称附加一个 Feature——附加在组件上,或附加在该槽所有使用者共享的更广作用域上;对于套接字的槽,附加在报告指明的连接上。以其他名称附加不会绑定该槽:槽是一个具名的绑定点,名称即是绑定。如果该槽不再需要设为必需,请更新目录实体的 featuresSchema——组件自身的或套接字的——删除 required 声明。

Two Features declared to conflict reach one component(两个声明为冲突的 Features 到达同一个组件)

Feature 的 interoperability.conflictsWith 列出了它不能与之同时附加的 Features,而某个组件最终同时带有该 Feature 和它列出的某个 Feature。该检查针对所有作用域折叠之后组件最终拥有的附加项进行——包括 Aggregate 的组件级和子系统级 features: 块、Release 的边界级块(组件所在的每个边界,包括嵌套的边界)和组件级条目,以及由注解驱动扩展产生的附加项。因此,当两者都写在组件上、其中一个位于包含该组件的边界或子系统上,或者一个位于外层边界而另一个位于嵌套其中的边界上时,都会停止。附加在不共享任何组件的兄弟边界上的两个 Features 永远不会相遇,不包含任何组件的边界也不会到达任何内容,因此两者都不会停止。

一处声明即足够:只要任一 Feature 的列表列出了另一个,就会触发停止。比较名称时双方都会去掉版本,因此一个条目匹配它所指 Feature 的所有版本。编译器将 Feature 作者声明的名称与组件所带的 Features 进行比较,不对任何一方作额外解读。

发出的消息:

a Feature reaches a component alongside a Feature it declares a conflict with ("<feature>", attached in the Release on boundary "<boundary-path>", conflicts with "<other-feature>", attached in the Aggregate on component "<component>", on component "<component>"). Attach only one of the two where they meet: remove one attachment, or move it to a scope that does not hold this component.(一个 Feature 与其声明冲突的另一个 Feature 同时到达同一组件:所示两个 Feature 及其各自的附加位置和交汇的组件如上所列。请在二者交汇处只附加其中一个:移除一个附加,或将其移到不包含该组件的作用域。)

第一个值是其列表列出另一个的 Feature——即上面句子所指的那个——其后是它被附加的每个位置;然后是与之冲突的 Feature,及其被附加的每个位置;最后是它们相遇的组件。每个位置都用你要打开以修改它的那份文档的措辞表述:attached in the Aggregate on component、attached in the Aggregate on subsystem、attached in the Release on boundary(嵌套边界的路径用 / 连接各层级)、attached in the Release on the entry for component 后接 in boundary,或者 attached by annotation-driven expansion of 加上注解,再后接 declared at 及其编写位置。写在连接上的附加项表述为该连接的条目,因为编辑它的地方是该条目而不是组件自身的块:attached in the Aggregate on the connection 后接 through socket 和 of component,或 attached in the Release on the connection 后接 through socket、of the entry for component 和 in boundary。附加在两处的 Feature 会列出两处。报告定位于 components: 下该组件自身的键;在多个组件上相遇的一对会为每个组件各报告一次,顺序与 Aggregate 声明组件的顺序一致。

**如何修复:**在它们相遇处只附加其中一个——删除其中一个附加项,或将其中一个移到不包含此组件的作用域,例如兄弟边界。如果附加项来自注解驱动扩展,需要修改的是注解,而不是它扩展到的块。如果这两个 Features 实际上可以组合使用,那么错的是声明:从声明方 Feature 的目录实体上的 conflictsWith 列表中删除另一个 Feature。

Attachment does not conform to its declared slot shape(附加项不符合其声明的槽位结构)

附加项绑定了一个已声明的槽位,但与该槽位声明的结构不匹配。常见情况是交付:槽位的 inject 允许列表列出填充项可用于交付其材料的机制,而空的允许列表即为黑盒——由 Recipe 在内部交付材料,填充项不能指定任何交付方式。空的 inject: {} 块不指定任何交付方式,因此对每个槽位都符合结构,包括允许列表为空的槽位,并且无论附加项写在何处,都会得到相同的结论:在 Aggregate 声明的组件上、在导入的模块提供的组件上,或在更宽的作用域上。以任何槽位都未声明的名称写入的附加项是自由附加项,不受槽位约束。

输出的消息,针对附件指定了其槽位不接受的交付方式的情况——先是槽位,然后是机制,再是槽位的 inject 允许列表所接受的每个机制,按槽位声明它们的顺序排列(允许列表为空时后面不跟任何机制):

attachment does not conform to its declared slot shape (Aggregate <name>, at .spec.components.<component>.features.<attachment>, "<slot>", "<mechanism>", "<permitted-mechanism>")(附件不符合其声明的槽位形态)

由导入的模块提供的组件,会在导入它的组合构建完成后检查,并以第二种形式报告。它会指明该模块的 Aggregate,以及模块文档中槽位未声明的键——附件的 inject: 块下的某个机制,或者在允许列表为空的槽位上指明了任何机制的 inject: 块本身:

attachment does not conform to its declared slot shape (Aggregate <name>, at .spec.components.<component>.features.<attachment>.<key>, attachment does not conform to the declared slot shape: this key is not part of the slot’s declaration — <remedy>)(附件不符合其声明的槽形状:该键不属于槽的声明)

其中 <remedy> 取决于该键:

  • remove it,用于在允许列表为空的槽位上指明某个机制的 inject: 块;
  • remove it, or add it to the slot's inject allowlist in the entity's featuresSchema,用于槽位允许列表可以列出的机制——env、file 或 arg;
  • remove it: a slot's inject allowlist in the entity's featuresSchema accepts only env, file and arg,用于任何其他机制,这类机制没有任何槽位能够声明。

在更宽范围声明的附加项——作用于整个子系统、级联到其下每个组件——同样须符合该结构,并会针对它到达的每个组件上的槽位分别检查。因此,同一附加项可能对一个组件符合结构,对另一个组件却不符合;所以这种形式会指出组件及其未通过检查的槽位,并将附加项定位到其声明所在的范围,而不是其交付块内的某个键:

attachment does not conform to its declared slot shape (Aggregate <name>, at .spec.subsystems.<scope>.features.<attachment>, this attachment is declared at a scope that reaches component <component>, whose attachment slot <slot> does not accept the delivery it carries: move the attachment down to the components that may receive it)(附件不符合其声明的槽形状:该附件声明所在的作用域覆盖了某个组件,而该组件的附件槽不接受此附件携带的交付方式:请将该附件下移到可以接收它的组件上)

连接携带的附加项永远不会触发此终止。其结构在写入处即是封闭的:在 Aggregate 的连接条目上,它接受 type、description 和 values;在 Release 的连接条目上,接受 type、description 和 infra;因此它根本不能指定任何交付——在那里写入的 inject: 会在文档加载时被拒绝,并指出该键——而交付它的 Workload 条目则改为受套接字槽位的 inject 允许列表约束。也没有任何范围能到达套接字的槽位,因此上述范围级形式在连接上没有对应形式。

修复方法: 这几种形式需要两种不同的修改,字段路径会告诉你遇到的是哪一种。如果它指向组件上的某个附加项,或其中的某个键,则问题在于交付:删除它,或将其条目移到槽位的 inject 允许列表所列出的某个机制下。如果材料确实应当通过槽位未列出的机制到达 workload,可以放宽目录实体 featuresSchema 中的允许列表——但只能加入 env、file 或 arg 这几种槽位可以声明的机制;在那里列出任何其他机制的 Component 会在加载时验证失败,因此对于任何其他机制,删除它是唯一的修复方法。如果它指向某个范围上的附加项,则附加项本身格式正确,问题在于其放置位置:将它下移到槽位接受该交付的组件上,让那些将交付保留给其 Recipe 的组件处于其作用范围之外。

Duplicate delivery key across inject sources(跨 inject 来源的重复交付键)

同一个交付键(例如同一个环境变量名)在某个组件由开发者编写的 inject 来源中被声明了两次——在 Component 层级和某个 uses[] 条目下、在同一组件的两个 uses[] 条目中,或在该 Component 自身 inject: 块的两种交付机制下。交付不能同时来自两个地方,因此被声明两次的键是一个矛盾,而不是谁胜出的问题。

构建会在四个地方读取这一点,因为它们看到的编写来源和依赖连接集合不同,对其提出的问题也不同,并且各自以自己的形式报告。

第一处读取你在 Aggregate 中编写的连接,并在解析你的文件时报告。它依次给出交付机制、键,以及按编写顺序第一个同样声明该键的连接的 socket 和别名:

duplicate delivery key across inject sources(多个 inject 来源之间存在重复的交付键) (Aggregate <name>, at .spec.components.<component>.inject.<mechanism>.<key>, "<mechanism>", "<key>", "<socket>", "<alias>")

第二处读取同一个编写的块,但提出不同的问题:组件是否在其自身的两种交付机制下声明了同一个键,完全不涉及连接。它对每个声明该键的机制各报告一次,定位在该机制自身的条目上,并依次给出报告所针对的机制、键,以及按编写顺序列出的其他所有声明该键的机制:

duplicate delivery key across inject sources(多个 inject 来源之间存在重复的交付键) (Aggregate <name>, at .spec.components.<component>.inject.<mechanism>.<key>, "<mechanism>", "<key>", "<other-mechanism>")

两个机制都不是肇事者,两份报告都由你来修改:在其中一个机制下重命名该键,或删除两次交付之一。组件究竟可以使用哪些机制是另一个问题,由其 spec.inject 允许列表回答——参见下文“Self-inject mechanism not in the component’s allowlist(自注入机制不在组件的允许列表中)”。

模块所贡献的组件同样会遇到前两种形式,在导入该模块的组合构建完成后从模块自身的文档中读取;此时它们会指明该模块的 Aggregate 及其文档中的键。

第三处读取最终拓扑所携带的连接,其中包括 Feature 附件代你添加的连接。它在任何渲染之前运行,并给出你编写的交付键以及同样交付该键的依赖 socket:

duplicate delivery key across self-inject and uses-inject(self-inject 与 uses-inject 之间存在重复的交付键) ("<key>", socket "<socket>")

一个编写的键经由两个依赖 socket 交付时,每个 socket 报告一次,因此一次构建就会告诉你所有这些 socket,而不只是最先到达的那个。

第四处读取同一个最终拓扑,但提出不同的问题:组件自身的两个依赖连接是否交付了同一个键,而组件本身并未声明任何键。它在每个连接处各报告一次,定位在该连接自身的交付条目上,并给出该条目的路径,后跟每个交付该键的 socket:

duplicate delivery key across inject sources(多个 inject 来源之间存在重复的交付键) ("inject.<mechanism>.<key>", "<socket>", "<socket>")

同一个 socket 出现两次,说明这两个连接位于同一个 socket 上、使用不同的别名——此时只有位置能区分它们,因此请读取两份报告各自的字段路径,而不是 socket 名称。

两个连接都不是肇事者,两者都由你来修改:重命名其中一个键,或删除两次交付之一。

当键是路径时,字段路径改为指向该机制的块。 交付键的写法由机制自己决定,而 file 机制交付到挂载路径——因此这样的键包含点号,而字段路径也用点号分隔自身的各级。字段路径会停在它能无歧义命名的最后一级,而不是写出一个会被读成穿过你的文档中并不存在的键的路径,因此对于 /etc/app/config.yaml 这样的键,它读作 .spec.components.<component>.inject.<mechanism> 并停在那里。无论哪种情况,消息都会给出该键,这使报告同样可据以行动——但在上述四种形式中,键在消息中的位置各不相同,因此请通过字段路径找到块,再从你遇到的那种形式中取出键:细节以交付机制开头时,键是紧随其后的带引号的值;细节单独以键开头时,键是第一个带引号的值;细节以交付条目自身的路径开头时,键是该路径的最后一级。

如何修复: 重命名其中一个冲突的键,或删除重复的声明。注意,FeatureRecipe 的 injectMapping 改写组件自身 inject: 块或其某个连接的 inject: 块所交付的键,属于有意的拦截,在此处及其他任何地方都不会被标记。

由附加到组件的 Feature 声明的键,从其三个编写面中的第三个进入同一个共享空间,并在下文“An attachment delivers a key another inject source already claimed(附件交付了另一个 inject 来源已声明的键)”下报告;由两个附加的 Features 交付、且两者中后者通过其 FeatureRecipe 的 injectMapping 交付的键,在“Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping(两个附加的 Features 交付同一个键,后者通过其 FeatureRecipe 的 injectMapping 交付)”下报告。

Self-inject on a component without an allowlist(在没有允许列表的组件上自注入)

开发者编写了组件级的 inject: 块,但 Component 目录实体没有声明 spec.inject。没有 spec.inject 允许列表的 Components 是黑盒类型——它们不接收开发者编写的注入。

发出的消息:

self-inject on component without spec.inject allowlist (Aggregate <name>, at .spec.components.<component>.inject, "inject", "<component-type>")(在未声明 spec.inject 允许列表的组件上使用自注入)

报告定位在 inject: 块本身,即需要删除的元素。

如何修复: 从该 Component 实例中删除 inject: 块,或改用目录声明中包含 spec.inject 的白盒 Component 类型。

Self-inject mechanism not in the component’s allowlist(自注入机制不在组件的允许列表中)

开发者编写了组件级的 inject: 块,所使用的机制(例如 env 或某种特定的文件挂载形式)未列在该 Component 的 spec.inject 允许列表中。

发出的消息:

self-inject on component without spec.inject allowlist (Aggregate <name>, at .spec.components.<component>.inject.<mechanism>, "<component-type>", "<mechanism>", "<allowlisted-mechanism-1>", "<allowlisted-mechanism-2>", …)(在未声明 spec.inject 允许列表的组件上使用自注入)

该类型允许的机制跟在被指定的机制之后,因此消息同时包含所写的内容和该类型所允许的内容。完全没有声明允许列表的类型只报告被指定的机制,其后不跟任何内容。

此规则和上一条规则都适用于模块所贡献的组件,在导入该模块的组合构建完成后生效;此时报告会指明该模块的 Aggregate 及其文档中的键。

如何修复: 改用允许列表中的机制;或者,如果该 Component 应当支持你需要的机制,则扩展其目录中的 spec.inject 允许列表。

uses edge dictates delivery on a socket that allowlists none(uses 边在未设置任何允许列表的套接字上指定了交付方式)

uses: 边上的 inject: 块连接到一个插槽,而该插槽的 usesSchema 条目未声明 inject: 允许列表,或声明了空列表。这样的插槽是黑盒连接:声明它的实体在内部处理依赖的值,因此消费方接受生产方 Recipe 发出的任何内容,不选择交付形式。缺少 inject: 键与 inject: [] 是同一声明。

套接字按声明它的实体读取:在 Feature 附加上编写的边依据所附加 Feature 的 usesSchema 解析,其他所有边则依据进行消费的 Component 的相应声明解析。

发出的消息。先是拒绝说明,然后是该边指定的机制、插槽以及被读取其声明的实体,最后是处理方法:

uses-edge inject dictates a delivery mechanism the socket does not permit ("<mechanism>", on socket "<socket>", declared on the component type "<component-type>"). The socket declares no delivery allowlist, so it permits no dictation at all — the entity that declared it delivers the dependency’s values itself. Remove the inject block from this connection and read the values from the connection’s provides in the consuming Recipe, or declare the mechanisms the socket permits in its usesSchema entry.(uses 边的 inject 指定了该套接字不允许的交付机制(上述机制、套接字及其声明所在的组件类型)。该套接字未声明交付允许列表,因此完全不允许指定——声明它的实体会自行交付依赖的值。请从此连接中移除 inject 块,并在进行消费的 Recipe 中从该连接的 provides 读取这些值,或在该套接字的 usesSchema 条目中声明它允许的机制。)

该结果定位在其所涉及的已编写条目上,位于编写该条目的文档中:对于组件自身 uses: 块绘制的边,为 .spec.components.<consumer>.uses.<socket>.<alias>;对于附件绘制的边,为 .spec.components.<consumer>.features.<attachment>.uses.<socket>.<alias>,其根是声明该附件的块,可能是某个子系统或边界的块,而不是组件自身的块。若插槽声明在所附的 Feature 上,消息会用 feature 类型代替组件类型。每条违规的边都作为单独的结果报告,因此一次构建即可列出全部。

修复方法: 从该边移除 inject: 块,改为在消费方 Recipe 中从 .context.uses.<alias>.provides.<name> 读取依赖的值;或者,如果该连接本应是透明的,在其 usesSchema 条目的 inject: 允许列表中声明该插槽允许的交付机制。

声明实体从未声明过的插槽属于另一种情况,此处不会拒绝:临时插槽不带允许列表,因此边不存在超出范围的问题。

uses edge dictates a delivery mechanism outside the socket’s allowlist(uses 边指定了套接字允许列表之外的交付机制)

uses: 边上的 inject: 块指定了插槽的 inject: 允许列表中未列出的交付机制。允许列表是声明实体对其入口点实际能从哪些交付形式读取依赖值的陈述,因此列表之外的机制交付的值不会被任何东西使用。

该块指定的每个机制都会被检查,允许列表之外的每一个都会被报告,因此一次构建即可列出全部,而不是每次运行只报告一个。

发出的消息。先是拒绝说明,然后是被拒绝的机制、插槽、该插槽实际允许的机制,以及被读取其声明的实体:

uses-edge inject dictates a delivery mechanism the socket does not permit ("<mechanism>", on socket "<socket>", which permits "<mechanism-1>, <mechanism-2>", declared on the component type "<component-type>"). Dictate one of the mechanisms the socket permits, or widen that socket’s inject allowlist in the declaring entity’s usesSchema entry.(uses 边的 inject 指定了该套接字不允许的交付机制(上述机制、套接字、其允许的机制及其声明所在的组件类型)。请指定该套接字允许的机制之一,或在声明实体的 usesSchema 条目中扩大该套接字的 inject 允许列表。)

该结果定位在其所涉及的已编写条目上,路径与上一项拒绝所列的相同。若插槽声明在所附的 Feature 上,消息会用 feature 类型代替组件类型。

修复方法: 改用允许列表中的某个机制;或者,如果该实体应支持你需要的机制,在其目录 usesSchema 条目中扩展该插槽的 inject: 允许列表。

An inject: entry carries both a literal and a source key(一个 inject: 条目同时带有字面值和来源键)

inject: 条目交付两者之一:写在 value: 下的字面值——在组件自身的块上,这是交付字面值的唯一位置——或写在 from: 下、从连接所指组件读取的键。同时带有两者的条目同时表达了两件事,且没有提供在两者之间选择的规则,因此它会被拒绝,而不是让其中一个悄然胜出。

编写 schema 只接受这对字段中的恰好一个,因此从文件读取的文档在加载时就会被拒绝。本检查是那项检查背后的保障:它在解析 Aggregate 和 Release 这两个文档时读取它们携带的每个 inject: 块,因此通过文件以外的其他途径构建的文档,在据其构建任何内容之前仍会被拒绝,而不是被悄然选取其中一个字段。它覆盖的块与下文的形状检查相同。

每个含有违规条目的交付机制都作为单独的发现报告,定位在编写它的文档中的该机制处——对于组件自身的块为 .spec.components.<component>.inject.env——构建中的所有此类发现会一次性全部报告。发现会先指明该机制,然后列出该机制列表中每个违规条目的 in:。

发出的消息:

inject entry carries both value: and from:; schema requires exactly one ("<mechanism>", "<in-1>", "<in-2>")(inject 条目同时带有字面值和来源键;schema 要求只能有其中一个)

修复方法: 打开消息列出的每个条目,删除它不需要的那一个。若值应来自连接所指的组件,保留 from:——它指定该组件的 provides: 所声明的键。若值是本方在组件自身的块上提供的字面值,保留 value:;在连接上以及在附加 Feature 自身的块上,字面值会被拒绝,因此在那里保留 from:。

An inject: entry on a connection carries a literal(连接上的注入条目携带字面值)

连接向使用方组件交付其所指组件发布的内容:连接的 inject: 块中的每个条目都在 from: 下指定该组件的某个 provides: 键。写在 value: 下的字面值不指向目标发布的任何内容,因此它在连接上没有位置,该条目会被拒绝而不是被丢弃。组件交付给自身的字面值应放在组件自身的 inject: 块中,那里允许使用 value:。

无论连接由哪个文档绘制,每个连接都会被检查:组件自身 uses: 块上的连接、Aggregate 中挂载的 Feature 所绘制的连接,以及 Release 中编写的挂载所绘制的连接。它在任何渲染之前就会被拒绝,因此 aggrega validate --release 与 aggrega build 都会报告它。

每个违规条目都作为单独的发现报告,定位在绘制该连接的文档中的连接条目处——组件自身的连接为 .spec.components.<component>.uses.<socket>.<alias>,挂载所绘制的连接为 .spec.components.<component>.features.<attachment>.uses.<socket>.<alias>,而在 Release 中则是挂载条目下的相同路径,例如 .spec.boundaries.<boundary>.components.<component>.features.<attachment>.uses.<socket>.<alias>——构建中的所有此类发现会一次性全部报告。Aggregate 中的发现归入 DEVELOPER_ERROR,Release 中的发现归入 OPS_ERROR。发现会指明机制以及该条目的 in:。

发出的消息:

inject entry on a connection carries value:; a connection delivers the target’s published keys, each named with from: ("<mechanism>", "<in>")(连接上的 inject 条目携带字面值;连接交付的是目标发布的键,每个键都以来源键指定)

修复方法: 如果该值是目标发布的值,将 value: 替换为指定该 provides: 键的 from:。如果它是使用方组件需要的字面值,将该条目移到该组件自身的 inject: 块中,其机制受其 Component 类型的 spec.inject 允许列表约束。

An inject: entry on an attached Feature carries a literal(附加 Feature 上的注入条目携带了字面值)

写在附加 Feature 上的 inject: 块会将该附加项的 FeatureRecipe 所发布的内容交付给组件:每个条目指定 FeatureRecipe 的 provides: 所发布的某个键,写在 from: 下。写在 value: 下的字面值并不指定该附加项发布的任何内容,因此在该条目的 in: 下不会有任何内容到达组件;该条目会被拒绝,而不是被构建后丢弃。组件需要的字面值应放在组件自身的 inject: 块中,在那里 value: 会被接受并交付。

Aggregate 在其上编写 inject: 块的每个附加项都会被检查:组件自身 features: 块中的附加项,以及子系统 features: 块中的附加项——后者会作用于该子系统包含的每个组件——范围包括 Release 所指定的 Aggregate,以及该 Aggregate 在 aggregates: 下导入的每个模块,无论层级多深。附加项绘制的连接携带其自己的 inject: 块,那里的字面值属于上文所述的连接拒绝情形。Release 中的附加项不编写自己的 inject: 块。该条目会在任何渲染之前被拒绝,因此 aggrega validate --release 与 aggrega build 一样会报告它。

每个有问题的条目都作为独立的发现报告,以 DEVELOPER_ERROR 归入编写该块的文档所属的 Aggregate——对于在模块中编写的附加项,即模块自身的文档——并定位在该文档中附加项块内的交付机制处:.spec.components.<component>.features.<attachment>.inject.<mechanism>,或者对于子系统的附加项,.spec.subsystems.<subsystem>.features.<attachment>.inject.<mechanism>。同一文档中的所有此类条目会一次性报告;导入模块中的条目会在导入它的 Aggregate 通过之后报告。该发现指出机制和条目的 in:。同时携带 value: 和 from: 的条目只报告一次,见上文“An inject: entry carries both a literal and a source key(注入条目同时携带字面值和来源键)”。

发出的消息:

inject entry on an attachment carries value:; an attachment delivers the keys its FeatureRecipe publishes, each named with from:, and a literal belongs in the component’s own inject block ("<mechanism>", "<in>")(附加项上的 inject 条目携带了字面值;附加项交付其 FeatureRecipe 发布的键,每个键都以来源键指定,而字面值应放在组件自身的 inject 块中)

修复方法: 如果该值是附加项的 FeatureRecipe 所发布的值,将 value: 替换为指定该 provides: 键的 from:。如果它是组件需要的字面值,将该条目移到组件自身的 inject: 块中,该块的机制由其 Component 类型的 spec.inject 允许列表管理:

components:
api:
type: core/api
inject:
env:
- in: LITERAL_NAME
value: a-literal # the literal, delivered by the component's own block
features:
token:
type: core/token
inject:
env:
- in: TOKEN_NAME
from: name # a key the attachment's FeatureRecipe publishes

An inject: delivery is not a list of entries(注入交付不是条目列表)

inject: 块中的每个交付机制——env、file、arg,或与它们并列命名的机制——都是一个条目列表,每个条目带有 in:,以及 from: 或 value: 中的恰好一个。机制若包含其他内容,例如名称到键的映射,则不会交付编译器能读取的任何东西,因此会被拒绝而不是被丢弃。完全没有写值的机制不交付任何内容,不会被拒绝。

编写 schema 只接受列表,因此从文件读取的文档在加载时就会作为不符合其类型 schema 的文档被拒绝。本检查是那项检查背后的保障:它在解析 Aggregate 和 Release 这两个文档时读取它们携带的每个 inject: 块,因此通过文件以外的其他途径构建的文档,在据其构建任何内容之前仍会被拒绝,而不是让交付悄然消失。它覆盖两个文档携带的所有块:在 Aggregate 中,包括组件自身的块、挂载的块,以及二者所绘制的连接上的块;在 Release 中,包括其挂载所绘制的连接上的块。

每个违规机制都作为单独的发现报告,定位在编写它的文档中的该机制处并指明该机制,构建中的所有此类发现会一次性全部报告。Aggregate 的发现先于 Release 的发现报告。

发出的消息:

inject delivery: shape must be a list of entries, each in: with exactly one of from: or value: ("<mechanism>")(inject 交付:形状必须是条目列表,每个条目带有目标位置,以及来源键或字面值中的恰好一个)

位置是作者所写的键路径。在 Aggregate 中,组件自身的块为 .spec.components.<component>.inject.<mechanism>,其某个连接上的块为 .spec.components.<component>.uses.<socket>.<alias>.inject.<mechanism>,挂载的块为 .spec.components.<component>.features.<attachment>…,组件或挂载声明所在的每个子系统都会加上 .subsystems.<name>。在 Release 中,是挂载所绘制的连接上的块,经由该挂载表示——在整个边界范围挂载的为 .spec.boundaries.<boundary>.features.<attachment>.uses.<socket>.<alias>.inject.<mechanism>,挂载在组件上的为 .spec.boundaries.<boundary>.components.<component>.features.<attachment>…,每个嵌套边界加上 .boundaries.<name>,组件所经由的每个路由条目加上 .aggregates.<module>。

修复方法: 将消息指出的每个机制写成列表。env: 下的条目 DB_URL: host 变为 - in: DB_URL:当 host 指定一个 provides: 键时——在连接上是所连接组件的键,在组件自身的块上是组件自己的键——配以 from: host;或者,在组件自身的块上,当它是本方提供的字面值时,配以 value: host。

The Feature filling an attachment slot does not satisfy the slot’s selector(填充挂载槽的 Feature 不满足该槽的选择器)

Component 为其预期的 Features 声明具名绑定点,槽可以声明一个 selector:,用于约束填充它的任何内容的标签。挂载通过携带槽的名称来绑定该槽;绑定时,所指 Feature 的标签会与该约束进行匹配,不满足约束的填充会使构建停止。未声明约束的槽接受任何填充。

槽是否可以不绑定,是另一个问题,补救方法也不同,由上文其自身的中止条件报告:本条件以存在填充为前提,只判断该填充是否可接受,因此未绑定的槽不在其范围之内。

此条件下会报告两种结果,消息通过其最后一个值区分二者。不满足约束的填充会列出其标签未匹配的 Feature。根本无法读取的约束则改为列出原因——标签匹配器无法求值的表达式——这是槽自身声明的错误,而非挂载到它的内容的错误。

填充的标签不满足约束时发出的消息:

attachment slot selector unsatisfied ("<selector>", declared on slot "<slot>", not satisfied by the labels of the Feature filling it, "<feature-type>"). Add the labels the slot’s selector requires to the Feature’s labels, or fill the slot with a Feature that already carries them.(附件槽位选择器未满足:槽位上声明的选择器未被填充该槽位的 Feature 的标签满足。请将该槽位选择器要求的标签添加到该 Feature 的标签中,或改用已带有这些标签的 Feature 填充该槽位。)

约束本身无法求值时:

attachment slot selector unsatisfied ("<selector>", declared on slot "<slot>", which could not be evaluated: "<why it could not be evaluated>"). Correct the selector on the slot’s declaration in the component’s catalog entity.(附件槽位选择器未满足:槽位上声明的选择器无法求值。请在该组件的目录实体中修正该槽位声明上的选择器。)

该结果定位在编写该填充的文档中填充所在的键上,并归属于该文档的作者:Aggregate 中 component 的 features: 块属于开发者错误;仅由 Release 做出的填充——位于其该 component 的条目上,或位于包含它的边界上——属于运维人员错误,在 Release 自身的路径上报告:

[OPS_ERROR E0008] release.yaml at .spec.boundaries.main.components.app.features.identity
attachment slot selector unsatisfied ("feature.aggrega.ai/kind!=secret", declared on slot "identity", not satisfied by the labels of the Feature filling it, "core/secret-value"). Add the labels the slot's selector requires to the Feature's labels, or fill the slot with a Feature that already carries them.

在 Aggregate 中的 component 上编写的同一填充会报告 [DEVELOPER_ERROR E0008] aggregate.yaml at .spec.components.app.features.identity。

由 socket 声明的槽——位于 usesSchema 条目的 featuresSchema 中——同样要求每个连接的填充满足其 selector:。连接在该槽中携带的挂载会与约束进行匹配,不被接受的填充会使构建停止,消息中除槽之外还会列出 socket 和连接:

attachment slot selector unsatisfied ("<selector>", declared on slot "<slot>", of socket "<socket>", filled on the connection "<alias>", not satisfied by the labels of the Feature filling it, "<feature-type>"). Add the labels the slot’s selector requires to the Feature’s labels, or fill the slot with a Feature that already carries them.(附件槽位选择器未满足:该插座的槽位上声明、在该连接上填充的选择器未被填充该槽位的 Feature 的标签满足。请将该槽位选择器要求的标签添加到该 Feature 的标签中,或改用已带有这些标签的 Feature 填充该槽位。)

该结果定位在编写该填充的文档中、该连接的 features: 下挂载所在的键上:即 Aggregate 的连接条目,或者对于仅由 Release 做出的填充,为 Release 的逐边条目。

语法无法读取的槽位选择器,在任何内容填充该槽位之前也会被拒绝。 aggrega validate 无论针对整个目录,还是针对单个 Component 或 Feature,都会读取该实体自身文档所声明的每个槽位选择器——Component 自身的槽位、其套接字声明的槽位,以及 Feature 的槽位——并在同一条件下拒绝语法无法读取的选择器,无论是否有内容填充该槽位。消息采用上文的“无法求值”形式;由套接字声明的槽位还会附加该套接字:

attachment slot selector unsatisfied ("<selector>", declared on slot "<slot>", of socket "<socket>", which could not be evaluated: "<why it could not be evaluated>"). Correct the selector on the slot’s declaration in the socket’s featuresSchema on the component’s catalog entity.(附加槽位选择器未满足:在套接字的槽位上声明的选择器无法求值。请在组件目录实体上该套接字的 featuresSchema 中,更正该槽位声明上的选择器。)

对于 Feature 的槽位,修复建议改为指明该 Feature 的目录实体。尚无任何内容填充该槽位,因此错误在于目录实体:它被归类为 CATALOG_ERROR,并指明该实体的文件。

**修复方法:**对于不满足约束的填充,挂载一个标签满足约束的 Feature——消息中的选择器说明了所要求的标签——或者在声明该槽的 Component 中放宽槽的 selector:。如果消息表明约束无法求值,则错误在于选择器表达式:请在 Component 的槽声明或 socket 的槽声明中修正它。

An attachment written under another name fits a slot its component leaves empty(以其他名称编写的挂载适合其 component 留空的槽)

Component 自身的挂载面是开放的:名称未被任何槽声明的挂载是自由挂载,是合法的。但该挂载面上有一种形态会导致中止,因为这正是本应填充某个槽的内容以错误名称编写时的形态。当某个挂载同时满足以下所有条件时,构建停止:

  • 它编写在 component 本身上——位于 Aggregate 中该 component 自身的 features: 块,或 Release 中针对该 component 的条目;
  • 其名称不是该 component 类型声明的槽;
  • 其 Feature 的标签满足该类型所声明的某个槽的 selector:;
  • 所有作用域合并之后,该 component 上没有任何内容绑定该槽。

如果不加处理,这样的挂载会成为自由挂载,而它本应填充的槽仍为空——留空的可选槽构建会通过,却不交付任何内容。此规则适用于每个 Feature,而不仅限于凭据。

该挂载面上的其他一切仍是自由的。Feature 不适合任何已声明槽的挂载可以构建;在已有内容绑定的槽旁边的额外挂载也可以构建,只要它适合的其他槽都没有留空。component 从子系统或 Release 边界继承的挂载永远不会被判定,因此共享形态——在多个 component 所在的作用域中挂载一次凭据,且没有 component 填充该槽——可以构建。未声明 selector: 的槽没有说明它面向哪个 Feature,因此不会以这种方式要求任何挂载。连接所携带的挂载在此也不会被判定:socket 的槽是封闭集合,连接上的任何其他名称都会在“A connection carries an attachment under a name its socket declares no slot for(连接携带的挂载所用名称未被其 socket 声明为槽)”下中止。

发出的消息。首先是该条件的语句,然后是挂载所用的名称、component、其挂载的 Feature 以及它适合的空槽——最后是处理方法:

attachment written under a name no slot declares fits a slot its component leaves empty ("<attachment>", on component "<component>", attaching the Feature "<feature-type>", which fits the empty slot "<slot>"). Attach it as "<slot>" to fill the slot.(以任何槽位都未声明的名称编写的附件符合其组件留空的一个槽位:该组件上的此附件所附加的 Feature 符合该空槽位。请以该槽位的名称附加它,以填充该槽位。)

如果该 Feature 适合多个空槽,消息会按 component 类型声明它们的顺序逐一列出,并由你来选择:

attachment written under a name no slot declares fits a slot its component leaves empty ("<attachment>", on component "<component>", attaching the Feature "<feature-type>", which fits the empty slot "<slot>", and the empty slot "<another-slot>"). Attach it under the name of the slot it is meant to fill.(以任何槽位都未声明的名称编写的附件符合其组件留空的一个槽位:该组件上的此附件所附加的 Feature 符合多个空槽位。请以它要填充的那个槽位的名称附加它。)

该结果定位在编写该挂载的文档中挂载所在的键上,并归属于该文档的作者。Aggregate 中 component 自身 features: 块上的挂载在 .spec.components.<component>.features.<attachment> 处报告,属于开发者错误;仅由 Release 在其该 component 的条目上编写的挂载在该处报告——位于列出该 component 的边界下,.spec.boundaries.<boundary>.components.<component>.features.<attachment>——属于运维人员错误:

[OPS_ERROR E0328] release.yaml at .spec.boundaries.main.components.app.features.metrics
attachment written under a name no slot declares fits a slot its component leaves empty ("metrics", on component "app", attaching the Feature "core/prometheus-exporter", which fits the empty slot "identity"). Attach it as "identity" to fill the slot.

如果空槽是必需的,它本身是一个单独的结果,在 Aggregate 中的 component 处以“Required attachment slot not bound(必需的挂载槽未绑定)”报告。

与近似匹配提示的区别。“An attachment name is one edit from a declared slot(挂载名称与已声明的槽仅差一次编辑)”下的提示关注名称的拼写:名称与某个槽仅差一次编辑,而挂载的 Feature 不满足该槽的 selector:,此时构建通过并报告警告。本中止条件关注 Feature 适合什么,与名称无关:名称可以是任何内容,而它适合的槽必须为空。如果名称与某个槽仅差一次编辑,且其 Feature 确实适合该槽,则不会发出提示;若该槽为空,本中止条件就是唯一报告的结果。

**修复方法:**以槽的名称进行挂载,使其填充该槽——消息会列出该槽,若有多个候选则列出全部。如果它确实是一个单独的挂载,也请填充该槽,因为一旦它适合的每个槽都已绑定,额外挂载就是自由的;或者,如果它要作用于多个 component,请将其挂载在这些 component 所在的子系统或 Release 边界上。如果该 Feature 永远不应填充该槽,请在声明该槽的 Component 中收窄槽的 selector:。

An attachment delivers a key another inject source already claimed(挂载交付的键已被另一个注入来源占用)

有三个编写面通过 inject: 块向同一个 component 的注入管道交付:component 自身的 inject: 块、其依赖块各条目上的 inject: 块,以及挂载到它的每个 Feature 上的块。它们按交付机制共享同一个键空间,因此被其中两者同时占用的键会使到达的值产生歧义,构建会停止,而不是让一个编写面静默取代另一个。挂载的 Feature 还可以通过第二种方式交付,即其 FeatureRecipe 的 injectMapping;该途径在所有块交付之后才进入同一空间,并在下文“Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping(两个挂载的 Features 交付同一个键,后者通过其 FeatureRecipe 的 injectMapping 交付)”下报告。

本条件对应该空间中挂载块的一侧。当挂载自身的 inject: 块占用了某个先前交付已持有的键时报告——上文“Duplicate delivery key across inject sources(跨注入来源的重复交付键)”下的条目是从开发者编写一侧解读的同一规则,二者合起来覆盖了每个块的占用。

**顺序决定谁发生了冲突。**某个键下的第一个占用持有该键,之后的占用才会被报告——因此键已被占用的挂载会收到报告,而最先占用的挂载不会因为之后一个未取代任何内容的占用而收到报告。根本没有交付任何内容的占用不会占用该键,也不参与上述任何判定。

该结果定位在 component 的块中该挂载自身的条目上,即需要编辑的位置;消息会列出该键及其所在键空间的机制。每个冲突的键单独报告,因此重复了两个键的挂载会告诉你这两个键。

发出的消息:

duplicate delivery key across attachment-inject and another inject source(挂载注入与另一个注入来源之间存在重复交付键)("<key>", mechanism "<mechanism>")

**修复方法:**双方都不是过错方,两者都可以由你修改。在你能控制的一侧重命名该键——通常是 component 自身的 inject: 条目,因为 Feature 的映射编写在 catalog 文档中——或者去掉两个交付之一。如果确实应由该挂载提供该值,请删除开发者编写的占用,而不是挂载的占用。注意,Feature 的 FeatureRecipe injectMapping 写入某个键属于另一条途径,不在此处报告:改写 component 自身 inject: 块或其某个连接所交付的键属于拦截,完全不会报告;写入另一个挂载的 Feature 已交付的键则在下面的条目下报告。

Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping(两个挂载的 Feature 交付同一个键,后者通过其 FeatureRecipe 的 injectMapping)

一个附加的 Feature 通过两条路径向其组件的注入管道交付:写在该附件上的 inject: 块,以及其 FeatureRecipe 的 injectMapping,后者的输出指定交付键,该键通常来自附件携带的某个值,例如凭据所选的环境变量。当两个附加的 Features 在同一交付机制下到达同一个键,且两者中较晚的那个是通过其映射到达时,构建会停止。如果任其运行,组件将读取碰巧最后写入的那个值,于是一个凭据可能被另一个凭据顶替,而输出中没有任何提示。

它涵盖每个挂载的 Feature,无论挂载在何处:component 自身的 features: 块、子系统、Release 边界或 component 条目、注解的展开,以及连接的 features: 条目。两个交付中较早的一个可以是另一个 Feature 的映射,也可以是其自身的 inject: 块——构建会在这一个条件下报告这两种组合。

**顺序决定谁发生了冲突。**每个 inject: 块都在任何映射渲染之前交付,而映射按一个固定顺序渲染——即注入映射遍历 component 所挂载 Features 的顺序,见编译流水线——因此某个键下的第一个交付持有该键,后到的 Feature 会被报告。仅凭是否存在来判定:不比较值,因此两个 Features 在同一个键下交付相同的值仍会被报告。映射输出中根本不包含的键不算交付;包含但值为空的键算作交付,因为空值会替换原有内容。同一个键在两种不同交付机制下是两个键,不算冲突。

**不会报告的情况。**FeatureRecipe 的 injectMapping 改写 component 自身 inject: 块或其某个连接的 inject: 块所交付的键属于拦截——例如路由 Feature 限定主机、防护组件重定向上游——映射的值会替换该条目。Feature 的映射改写其自身 inject: 块所交付的键,是该 Feature 在转换自己的交付,同样不会报告。

该结果定位在后到 Feature 自身的条目上——位于 component 的 features: 块中;对于连接携带的 Feature,则位于编写它的文档中该连接下的条目,例如 Aggregate 中的 .spec.components.<component>.uses.<socket>.<alias>.features.<slot>。消息会列出该键、交付机制,以及两个 Features 在该 component 上所用的名称;连接携带的 Feature 以连接的别名和它填充的槽命名,二者以点连接。每个冲突的键单独报告。

发出的消息:

duplicate delivery key across two attachments: an attachment’s FeatureRecipe writes a delivery key another attachment already delivered ("<key>", mechanism "<mechanism>", attachment "<attachment>", delivered first by attachment "<other-attachment>"). Give one of the two attachments a key of its own, or attach one fewer: the key this attachment delivers under is chosen by its FeatureRecipe, which can read the attachment’s own values and infra, and the other’s is chosen the same way or by its own inject block where it delivered through one. A Release sets an attachment’s infra and never its values, so where a key is chosen by a value, attach that attachment in the Aggregate with the value, and keep giving the rest from the Release.(两个挂载之间的投递键重复:某个挂载的 FeatureRecipe 写入了另一个挂载已经投递过的投递键。请为两个挂载之一提供独立的键,或少挂载一个:此挂载用于投递的键由其 FeatureRecipe 选择,该 FeatureRecipe 可以读取挂载自身的 values 和 infra;另一个挂载的键以同样的方式选择,或者在它通过自身的 inject 块投递时由该块选择。Release 设置挂载的 infra,但从不设置其 values,因此当键由某个值选择时,请在 Aggregate 中挂载这一项并写入该值,其余部分继续由 Release 提供。)

**修复方法:**为两个 Features 之一提供独立的键——对于凭据 Feature,通常是其值所指定的键——或者删除两个挂载之一。如果两者都打算提供同一个变量,请决定 component 应读取哪一个,并只挂载那一个。Release 自行挂载的两个凭据都会到达其 Feature 默认指定的键下,因为 Release 无法写入挂载的 values:请在 Aggregate 中挂载其中一个,并写入指定其键的值,再在同一条目上从 Release 提供其来源。

A component declares an inject mechanism the attached Feature maps nothing to(组件声明了已挂接 Feature 未映射任何内容的注入机制)

Component 的 spec.inject 允许列表可以指定标准机制以外的交付机制——即组件自身管道能理解的机制,任何向其交付的内容都必须为它产生一个值。当 Feature 挂接到这样的组件时,由 FeatureRecipe 的 injectMapping 说明它产生的每个值在哪种机制下交付。组件声明了、而映射没有为其产生任何键的机制,就是一次会静默永不发生的交付,因此构建会停止。

对机制只字未提的映射,并不是声明没有机制的映射。 映射渲染为扁平交付字典的 FeatureRecipe 完全不对机制做任何声明——这是 Feature 产生环境变量交付的常规写法——绑定了没有可求值映射的 FeatureRecipe 的挂接也是如此。这两种情况都不在此报告;本条件仅针对指定了机制却遗漏了组件所声明机制的映射。

每个未映射的机制都是一个单独的发现,因此组件声明了两个机制而挂接都未映射时,两者都会告诉你。该发现定位在你自己文件中的挂接条目,并同时指出 FeatureRecipe——因为映射写在那个文档中,而它位于完全不同的地方。

发出的消息:

custom inject mechanism has no matching key in injectMapping output; add the mechanism’s key to the Recipe injectMapping ("<mechanism>", recipe "<featurerecipe>")(自定义注入机制在 injectMapping 输出中没有匹配的键;请将该机制的键添加到 Recipe 的 injectMapping 中)

修复方法: 消息指出了两方面。将该机制的键添加到 FeatureRecipe 的 injectMapping,使 Feature 为其产生一个值;或者在不期望有任何内容通过该机制交付时,从 Component 的 spec.inject 允许列表中删除该机制。如果该 FeatureRecipe 属于他人的目录,第三种做法是挂接一个映射覆盖该机制的 Feature。

An attached Feature’s injectMapping output cannot be read(已附加 Feature 的 injectMapping 输出无法读取)

FeatureRecipe 的 injectMapping 是一个模板,它产生的内容会作为 YAML 读取:要么是以交付机制为键的字典——env、file、arg 或组件自己的某种机制——要么是由环境变量交付组成的扁平字典。当输出两者都不是时,其中任何键都无法交付,因此构建会停止,而不是像已附加的 Feature 什么都没有交付那样渲染该组件。凭据是最关键的情形:否则,一个期望得到密码却从未收到的组件可能会在没有密码的情况下运行,而输出中没有任何内容会指出这一点。

常见原因是模板将某个值原样写在引号之间。值中的双引号会提前结束带引号的标量,反斜杠则会开始一个 YAML 可能无法识别的转义序列,因此对大多数值都能正确渲染的映射,会在遇到包含此类字符的值时出错——这个值往往是密码。为空的输出,或解析为不交付任何内容的字典的输出,不属于此条件:它什么都不交付,而这正是它所表达的。

消息上方的那一层会指明正在渲染的组件,然后以附件在该组件上所用的名称指明附件,并指明编写该映射的 FeatureRecipe,形式为 feature "<attachment>" (recipe "<featurerecipe>") injectMapping output。消息下方是无法读取输出的原因——行号以及 YAML 在该处发现的内容,例如 yaml: line 2: found unknown escape character。如果模板读取了作者声明为敏感的值,且原因取决于该值的内容,则原因会被隐去,并由一句说明此情况的话代替,因此该中止永远不会引用导致输出损坏的值。构建会在 CATALOG_ERROR 标签下报告该中止,因为映射是由 FeatureRecipe 的作者编写的。

发出的消息:

FeatureRecipe injectMapping output could not be read as a dictionary of deliveries(FeatureRecipe 的 injectMapping 输出无法作为交付项字典读取)

修复方法: 在 FeatureRecipe 的 injectMapping 中,通过 toJson 写入每个值——{{ .values.key }}: {{ .values.origin | toJson }}——这样会将其写为一个 JSON 字符串,无论其中包含什么字符,YAML 都能原样读回。如果该 FeatureRecipe 属于他人的目录,也可以在映射修复之前修改该值,使其不包含双引号或反斜杠。

An attached Feature’s injectMapping output writes deliveries under a key nothing delivers(已附加 Feature 的 injectMapping 输出将交付项写在一个不会交付任何内容的键下)

FeatureRecipe 的 injectMapping 输出按其顶层键合并到组件的注入管道中。env、file 和 arg 会作为相应的机制交付,任何其他键都会以该名称作为一种独立机制交付,组件的 Recipe 在 .context.inject.<name> 处读取它。all 视图则不同:它是在合并之后由各机制构建的,从不从某个输出合并而来,因此映射写在 all: 下的值不会到达任何地方。输出仍能被正常读取,因此如果没有此中止,以可选方式读取这些值的构建会在缺少这些值的情况下成功——写在那里的凭据永远不会到达组件,而构建中没有任何内容会指出丢失它的映射。

只要 all: 至少包含一个条目,无论是单独出现还是与其他机制并列,此条件都适用;同一输出中的其他机制并不是问题所在,而写为空的 all: 不会丢失任何内容,也不会被报告。恰好包含一个名为 all、只有单个值的键的扁平字典,是一个名为 all 的环境变量交付,而不属于此条件。

该发现定位在你自己文件中附件的条目处,并指明该键以及编写映射的 FeatureRecipe——因为那才是需要修改的文档,而它完全位于别处——同时列出输出可以携带的键。每个这样的键都是一个单独的发现。构建会在 CATALOG_ERROR 标签下报告它。

发出的消息:

FeatureRecipe injectMapping output writes a key no delivery mechanism of the host reads ("all", recipe "<featurerecipe>", an output may carry "env, file, arg, or a custom mechanism the host's Recipe reads under its own name")(FeatureRecipe 的 injectMapping 输出写入了宿主的任何交付机制都不读取的键,并列出该 recipe 以及输出可以携带的键)

修复方法: 在 FeatureRecipe 的 injectMapping 中,将 all: 下的条目移到组件读取它们的机制下——通常是 env:,或者组件的 Recipe 所读取的机制名称。如果该 FeatureRecipe 属于他人的目录,请改为附加一个其映射会交付该值的 Feature。

渲染输出时

所有契约验证完毕后,编译器会对 Component 的值、FeatureRecipe 的 injectMapping 块以及 Recipe 和 FeatureRecipe 的源求值 Go 模板,然后将结果交给渲染器。

provides: template references a non-self-contained root (provides 模板引用了非自包含的根)

某个 Recipe 的 provides: 模板引用了自包含集合之外的根。provides 块在 provides 求值阶段求值,此时 inject 管道尚未填充,跨节点边也尚未遍历,因此它只能引用属于自身节点的数据:.context.instance_id、.context.rendered_name(仅当节点的 provider 报告了该值时)、.values、.infra、节点已解析的 .locals,以及静态字符串。该检查是正向允许列表,因此任何其他根都会中止构建——.context.inject 和 .context.uses(跨节点)、.context.annotations.*、.context.labels、.context.metadata 和 .metadata.*(与放置或部署耦合的数据,provides 表面不暴露这些数据),以及 .attachment_name(基础 Recipe 的 provides 阶段不解析任何附加)。引用其中任何一个都会显式中止,而不是静默渲染出空值。

.locals 在该表面之内:节点的 locals 在同一阶段的前导部分、先于其 provides 解析,因此 provides 模板可以读取它们并得到已解析的值。

发出的消息:

provides block references a root outside the self-contained set ("<expression>")(provides 块引用了自包含集合之外的根)

该中止定位到声明该条目的 Recipe 及其中编写的键——.spec.provides.<name>——因此它指出的是需要编辑的块,而不是绑定该 Recipe 的组件。所有越出该表面的条目都会在同一次构建中报告;多于一个时,这些发现归入 provides entries that reach outside the data they are evaluated against 分组下。

**如何修复:**重构模板,使其只从该 Recipe 自身的支柱中取值。如果该值依赖另一个节点的输出,这一依赖应放在调用方的 uses[].inject 块中,而不是目标的 provides 中。如果该值是计算得出的,把表达式放进一个 locals: 条目,再从 provides 读取它——这样表达式只存在于一处。如果你是想用部署命名空间(或其他放置数据)来构造跨命名空间的主机名,请在此处发布裸主机名,并在消费方用路由 feature 加以限定——生产方的 provides 不得依赖其部署位置。

FeatureRecipe 的 provides: 遵循相同的 locals 规则:它自身的 locals: 先于其 provides: 解析,因此 FeatureRecipe 的 provides 条目同样可以读取 .locals。

locals: entry references a sibling defined later in the same block (locals 条目引用了同一块中稍后定义的同级条目)

locals: 块按条目的书写顺序解析,一个条目只能读取定义在其上方的同级条目。直接以 .locals.<key> 引用块中后面才定义的条目会中止构建:编译器从不为了让引用得以解析而对块进行排序或重排,因为那样发出的输出将遵循推断而非编写的内容。如果没有这一中止,该引用会经由缺失键策略解析为空字符串,派生出的主机名或 secret 名称会静默丢失构造它所用的那一段。

locals: 块的两种解析都会判定这一错误,其中之一是固定(pinning)。一个块会出于两种不同目的被解析:一是让该 Recipe 自身的模板在渲染制品时读取它,二是让结构化的 source: 坐标得以解析并固定它所指向的制品。该错误依据声明的键顺序和编写的文本判定,这已是它所需的全部信息,因此两种解析都会触及它并报告相同的情况——aggrega pull 以及填充 lockfile 的构建,会与渲染一样拒绝该块。编写时有两点值得了解。解析坐标时会读取整个块,因此即使每个 source: 字段都是字面值、不读取任何 local,顺序错误的条目也会中止构建。而 source: 为普通字符串、或根本未声明 source: 的 Recipe 不解析任何坐标,因此在这类 Recipe 上,该错误会在渲染输出时报告。

发出的消息,针对组件 Recipe 自身 locals: 块中的条目。它定位到该 Recipe 中编写的键,所有出错条目都在同一次构建中报告;多于一个时,这些发现归入 locals entries that read a sibling they cannot 分组下:

locals entry references a sibling defined later in the same block ("<expression>", the key it names is "<referenced>", resolved at this point "<the locals available here>", reached through the component "<component>"). define "<referenced>" above "<key>" in the locals block(locals 条目引用了同一块中稍后定义的同级条目:给出表达式、其引用的键、此处已解析的 locals 以及经由的组件。请在 locals 块中将被引用的键定义在当前键之上)

自引用属于同一情况——该键已声明但未解析——且任何重排都无法修复,因此消息会以说明这一点来代替移动条目的指示:

locals entry references a sibling defined later in the same block ("<expression>", the key it names is "<key>", resolved at this point "<the locals available here>", reached through the component "<component>"). a locals entry cannot read itself; compute the value from .values and .infra directly(locals 条目引用了同一块中稍后定义的同级条目:给出表达式、其引用的键、此处已解析的 locals 以及经由的组件。locals 条目不能读取自身;请直接根据 .values 和 .infra 计算该值)

**一个 Recipe 会被许多组件绑定,因此共享块中的一个错误会针对每个绑定它的组件各报告一次——而 reached through the component 正是区分这些发现的依据。**它们共享同一位置,因为都涉及同一文档中同一个编写的条目;位置指出在哪里编辑,组件名称则指出每个发现对应你的哪个组件。这些发现不会合并为一个,因为合并只能说明有问题,却无法说明问题影响到哪些组件,而那正是你需要处理的部分。

Feature 的 recipe 所声明的 locals: 块中出现同样的错误时,报告方式相同:定位到该 recipe 中编写的键,以附加所在的组件命名,并与带有相同错误的同级条目归为一组。当该 recipe 附加在多处时,每处各报告一次——每个附加都独立绑定该块,因此每次都是独立的一次出现,而不是同一次的重复。

当这种形式报告自引用时,其位置子句指向发起引用的条目本身而非后面的条目,因为键就位于那里。

**如何修复:**将被引用的条目移到读取它的条目上方。只要有一个条目读取另一个,重排 locals: 块就是一项行为变更,因此修复方式恰好是消息所指出的那次重排。自引用——条目引用其自身的键——无法通过重排修复;请改为直接从 .values 和 .infra 计算该值,消息会以此代替移动条目的指示。

locals: key does not exist(键不存在)

模板读取 .locals.<key>,但该键在 locals: 块中根本没有声明——拼写错误,或者该键已被重命名或删除。每个读取该支柱的位置都会引发此终止:locals: 条目、provides: 模板、Recipe 的 source: 模板,以及结构化 source: 坐标的解析(它会读取整个块以固定该坐标所指的制品)。locals 支柱是一个开放的键控映射,因此其下的未知键会通过根检查,否则会解析为空字符串;此终止正是阻止该空值进入发出制品的机制。

当出错的引用位于 provides: 模板中时,发出的消息:

template references a key the locals block does not declare (Recipe <recipe> provides[<key>] references <expression>, the locals block declares no <referenced>, it declares <the keys it does declare>). correct the key name(模板引用了 locals 块未声明的键。请更正键名)

当引用位于 locals: 条目本身时,发出的消息。它带有绑定该块所经由的组件,原因与上文顺序终止中所述相同——一个共享块会针对每个绑定它的组件各报告一次,而这正是区分这些发现的依据:

template references a key the locals block does not declare ("<expression>", the missing key is "<referenced>", the block declares "<the keys it does declare>", reached through the component "<component>"). correct the key name(模板引用了 locals 块未声明的键。请更正键名)

**修复方法:**将键名更正为块中已声明的键;消息会列出这些键。此终止与上文的顺序终止不同,因为两者的补救方式不同——任何重排都无法让不存在的键得到解析。

该检查读取的是引用解析到的路径,而不是其字面写法,因此会跟随块的别名:通过 with .locals 主体重新绑定的点访问的键,或通过绑定到 .locals 的变量访问的键,都会按与直接写法完全相同的条件检查,并以同样方式终止;从加括号的块上读取的键——{{ (.locals).nope }} 或 {{ ($.locals).nope }}——也是如此,因为括号产生的就是块本身,别无其他。只有一种写法会绕过检查:通过调用访问的键,而模板文本无法指明该调用的结果——{{ index .locals "nope" }} 或 {{ (default dict .locals).nope }}——因为此类调用产生什么是在模板运行时决定的,而不是由写法决定。作为此类调用结果上的字段读取的不存在的键——即 (default dict .locals).nope 形式——不会终止,并会渲染模板引擎的占位文本 <no value>。通过 index 访问不存在的键会终止,但报告为下文的“A template indexes a map with a key the map does not hold(模板使用映射中不存在的键对映射进行索引)”,而不是本检查:index 遇到映射中不存在的任何键都会终止。因此,index 仍是访问名称本身经计算得出的键的方式,而块中未声明的计算名称仍会按其键报告。

Template references a root the render context does not define(模板引用了渲染上下文未定义的根)

模板引用了一个顶层根(即开头的点之后的第一个路径段),而其渲染上下文并未定义该根:例如拼写错误 {{ .valeus.port }},或者在当前编写的表面上不存在的根。该检查是针对根名称的正向允许列表,允许的集合由渲染上下文自身的结构推导而来,而不是在其旁边另行维护一份列表,因此构建所拒绝的集合与上下文实际提供的集合不会出现偏差。诊断信息会指出出错的引用,并列出该上下文确实定义的根。

无论引用是直接书写,还是包裹在 default、if、with 或 range 回退中,该中止都会以相同方式触发,而包裹的写法恰恰最为关键:包裹器可以为已定义根下缺失的键提供回退值,但永远无法为缺失的根提供回退值,因此如果没有这一中止,包裹的形式会悄无声息地解析为空值,并让构建成功完成。已定义根下缺失的键不受影响,仍然遵循下文“Missing template key — asymmetric policy(缺失模板键——非对称策略)”中所述值模板的 missingkey=zero 策略,因此 {{ .values.optional_field | default "fallback" }} 这类可选键写法仍然有效。

同一中止也适用于结构已声明的支柱下一层中拼错的键。 有些支柱拥有编译器定义的键集合:Recipe 和 FeatureRecipe 渲染上下文中的 .context、.metadata、.inject、.workload 和 .boundary,以及路径模板中的 .manifest。引用这些支柱未定义的键({{ .context.nmae }}、{{ .metadata.typo }}、{{ .workload.containres }}、{{ .boundary.nmae }})会与错误的根一样中止,诊断信息会列出该支柱定义的键。在 Feature 挂载自身的模板中,除 env、file、arg 和 all 之外,.inject 还会为挂载自身的 inject: 块所指定的每种投递机制多定义一个键:写入 vault_ref: 机制的挂载在 {{ .inject.vault_ref.VAULT_PATH }} 处读取,诊断信息会将 .inject.vault_ref 列为 .inject 定义的键之一。挂载未指定的机制即使位于 if 或 with 内部也会中止,因为引用会在模板运行之前接受检查。若要读取挂载可能未指定的机制,请加以保护:{{ with .inject }}{{ if hasKey . "vault_ref" }}{{ index . "vault_ref" "VAULT_PATH" }}{{ end }}{{ end }}。无论挂载是否指定该机制,也无论它是否写入了 inject: 块,这对受保护的结构都能构建成功——此时 .inject 不包含任何内容,因此 with 会跳过其主体,而直接对 .inject 使用 hasKey 则会因值不是映射而中止。在保护内部,index 仍会因所指定机制不包含的键而中止。其他支柱是开放的,因为它们保存的是带键的数据,而不是编译器声明的集合,其中包括渲染上下文中的 .values、.infra、.locals、.provides、.features 和 .steps,以及路径模板中的 .parameters 和 .parent_boundary。开放支柱接受任意键。开放支柱下缺失的键不属于此中止,而是遵循下文“Missing template key — asymmetric policy(缺失模板键——非对称策略)”中所述该表面的缺失键策略,因此 {{ .values.optional_field | default "fallback" }} 以及其他所有可选键写法都仍然有效。

哪些支柱是已声明的、哪些是开放的,是表面的属性,而不是模板能够影响的:编译器从它即将提供的渲染上下文的结构中读取这一信息。正因如此,拼写错误中止和可选键渲染可以出现在同一个模板上。

表面也可以收窄其支柱原本定义的某个键,这类报告并非拼写错误。 当某个键在某个特定表面上承载的答案毫无意义(或属于另一个节点)时,该表面会拒绝该引用,而不是将其解析为错误的内容,诊断信息会列出它确实定义的键。需要了解两种情况,均为 {{ .context.rendered_name }}。在 Feature 附件自身的模板中,该键承载的是宿主组件由宿主自身的 provider 报告的名称,因此当宿主的 provider 不报告名称时(宿主单独放置一组制品,或通过不推导此类名称的 provider 进行渲染),附件上会拒绝该键,而在其他所有宿主上都允许。{{ .context.instance_id }} 在该表面上是允许的,它指向附件正在为之解析的宿主组件,在这类宿主上,宿主自身的资源正是以此命名的。在 Recipe 的 locals: 条目中,无论节点的 provider 报告什么,该键都会被拒绝:local 与 Recipe 的 source: 模板共享上下文,而节点是否提供 source 正是名称所依赖的因素之一,因此此处不提供该名称。诊断信息会将 .context.instance_id 列为 .context 在此处定义的唯一键;请改为在 provides: 条目或内联模板中读取渲染名称。关于这两个键各自指代什么以及各自在何处可读,参见 ../templates/rendered-resource-names.md。

根本身未定义时输出的消息:

template references a root the render context does not define(模板引用了渲染上下文未定义的根)(template <template-name> references <dotted-path>, the render context defines <the roots that context defines>)

根正确但已声明支柱下的某个键不正确时:

template references a root the render context does not define(模板引用了渲染上下文未定义的根)(template <template-name> references <dotted-path>, <pillar> defines <the keys that pillar defines>)

修复方法: 将引用更正为诊断信息所列的某一项,大多数报告是 .values、.infra 或 .context 的拼写错误,或者是 .context 或 .metadata 下某个键的拼写错误。移除回退包裹器无法消除该中止,添加包裹器也从未能抑制它;包裹器只是掩盖了哪个引用出错。如果数据确实属于另一个节点,它应通过 inject 管道到达此模板(在消费方上用 uses[].inject 条目进行连接,并从 .context.inject 读取),而不是通过它自己的根。

该检查覆盖渲染器求值的每一个模板表面,每个表面都按其自身定义的引用集合进行检查:Recipe 和 FeatureRecipe 的 valuesMapping、injectMapping、workload、artifacts: 主体、provides: 和 locals: 条目、source:、pipeline 步骤的 when: 和 with: 主体、assertions:,Aggregate 中组件级自注入的 value: 模板,以及 Release 边界路径模板(directory: / subDirectory:)。其中两个表面会用各自的诊断信息报告某些拒绝情况,因为它们描述的错误比“此引用不存在”更具体:路径模板引用了未提供给它的变量,由下文“Path-template references a variable outside the allowlist(路径模板引用了允许列表之外的变量)”覆盖;边界范围的 FeatureRecipe 引用了按组件划分的支柱,由“FeatureRecipe template references a field outside its scope’s allowlist(FeatureRecipe 模板引用了其作用域允许列表之外的字段)”覆盖。这两个表面拒绝的其他所有情况(包括它们所允许的支柱下拼错的键)都报告此中止,因此不会有诊断信息把你的引用误报为别的东西。

An artifacts: template reads a pillar the Recipe does not declare(artifacts 模板读取了 Recipe 未声明的支柱)

某个 artifacts: 条目的模板在未声明 workload: 的 Recipe 中读取了 .workload 或其下的某个键;或者在未声明 source: 的 Recipe 中读取了 .source 或其下的某个键。这两个支柱在 artifacts 渲染上下文中始终存在——它们是该表面定义的根——因此引用本身格式正确,此中止针对的是声明缺失,而不是引用写错。从合成的 workload 渲染 Deployment 的 Recipe 与从 source 渲染 chart 的 Recipe 是两种不同的形态,为其中一种编写的 artifacts: 主体会去读取另一种从不填充的支柱。

该检查在条目求值之前运行,正是这一顺序让报告有用。缺失的支柱以空值的形式到达模板,因此如果交给求值处理,构建要么不向输出文件拼接任何内容,要么以模板引擎对从空值读取键所给出的任意错误失败——两者都不会指出该支柱或缺失的声明。先行拒绝使此中止能够指出读取该支柱的确切表达式,并按你编写的原样引用。

已声明但渲染为空字符串的 source: 被视为完全没有 source,因为检查读取的是其自身模板求值之后的 source。这正是 provider 随后用于渲染的值,因此 source: 解析为空的 Recipe 也没有 source 可提供给 artifacts: 主体。

发出的消息,无论 artifacts: 条目写在哪里,形式都相同。变化的不是句子,而是其后的说明,它们指出哪个文档包含该条目。

模板中的每一个违规引用都会被指出,因此读取两个缺失支柱的主体会同时告诉你两者,而不只是先出现的那个。每个引用都在声明该条目的文档处报告,按你编写的原样引用,并附上它所属输出的说明:

artifact template references a pillar the Recipe does not declare (<expression>, artifact <output-name>)(artifact 模板引用了 Recipe 未声明的支柱)

表达式的第一个段指出了支柱,由此可知缺少哪个声明:.source.chart 读取的是 source:,.workload.containers 读取的是 workload:。

组件自身 Recipe 声明的条目针对该 Recipe 的 artifacts: 块报告。

FeatureRecipe 声明的条目——作为 feature 附加到组件,或在边界上声明——会针对该 FeatureRecipe 声明的支柱而非宿主组件的支柱进行检查,针对该 FeatureRecipe 的 artifacts: 块报告,并额外带有一条指出绑定它的附加项的说明:

artifact template references a pillar the Recipe does not declare (<expression>, artifact <output-name>, attachment <attachment-name>)(artifact 模板引用了 Recipe 未声明的支柱)

附加项说明提供了位置本身无法表达的信息:一个组件可以带有多个附加项,而在边界上声明的附加项会作用于该边界包含的每个组件。无论哪种路径,句子本身都指称一个 Recipe;位置与附加项说明结合起来才指出应打开哪个文档。

当一个模板包含多个引用时,每个引用都有各自的报告,位于一行指出它们共同所属条目的行之下,该行也会指出文档:

artifact <output-name> references pillars its Recipe does not declare(该 artifact 引用了其 Recipe 未声明的支柱)

artifact <output-name> references pillars the FeatureRecipe attachment <attachment-name> binds does not declare(该 artifact 引用了所绑定附件的 FeatureRecipe 未声明的支柱)

无论涉及哪个文档,这些报告都带有相同的中止条件,因此按条件而非文本进行匹配的任何工具都看不出它们之间的区别。

**如何修复:**要么声明模板读取的支柱,要么停止读取它。当 artifacts: 主体确实属于该 Recipe 形态时,修复方法是声明它——添加模板中容器、端口或卷引用所需的 workload:,或添加其插值所用 chart 或模块路径对应的 source:。当主体是针对另一个 Recipe 编写、复用了不适用于此处的片段时,修复方法是删除该引用;如果该值确实来自别处,请通过生产节点的 provides: 发布它,并从 inject 管道读取,而不是去读取此 Recipe 不填充的支柱。用回退包装器保护该引用无法清除此中止——缺失的是支柱,而不是其下的键——将引用移到同一 Recipe 的另一个条目中也不行,因为同一 artifacts: 块中的每个条目都针对相同的支柱求值。

此中止不同于上文的“Template references a root the render context does not define(模板引用了渲染上下文未定义的根)”,二者值得区分,因为修复方法不同。那个中止在引用表面根本未定义的根时触发,或在形态固定的支柱下出现拼写错误的键时触发——例如在确实声明了 workload 的 Recipe 上使用 {{ .workload.containres }}。而此中止在对一个根本不存在的支柱进行拼写正确的引用时触发。

A template reads a rendered name the node’s provider does not report(模板读取了节点的 provider 未报告的渲染名称)

模板读取 {{ .context.rendered_name }}——即绑定的 provider 为该节点渲染的输出所起的名称,这些输出来自作者提供的源,或来自它合成的 workload——而该节点的 provider 并不报告这样的名称。引用格式正确,该键也是渲染上下文定义的键;缺少的是针对此节点的答案。

之所以拒绝,是因为另一种结果比停止更糟。该名称以普通字符串的形式传入模板,因此没有名称的节点会把引用渲染为空,输出一个少了一段的地址——本应是主机名的地方变成 .svc.cluster.local——并以退出码 0 结束,构建中没有任何可供查看的信息。这样的产物能够部署,但它指向的东西并不存在。在求值之前就拒绝,才能把错误报告在作者编写的模板上。

节点的 provider 是否报告这样的名称,由 Recipe 绑定决定,早于任何求值,因此这里没有任何猜测。

报告有两种,你得到哪一种取决于节点,而不取决于引用写在哪里。 一个节点若不提供自己的源,且其 provider 不为它报告名称,那么它的资源以节点的标识命名,因此存在一个正确的值,报告会指出它。一个节点若提供了源,且其 provider 不为它推导名称,则没有替代值——在这种情况下给出标识,会把你引向一个与该节点的任何资源都不对应的值,因此报告会直接说明这一点。

节点不提供自己的源时,发出的消息:

template reads the name the target gives the resources it renders for the node, and this node’s provider reports no such name; a conforming template reads a value the node’s own provider supplies (".context.rendered_name", provider "<provider>"). read {{ .context.instance_id }} instead: this node supplies no source of its own, so its resources are named after the node’s identity(模板读取了目标为该节点所渲染资源指定的名称,而该节点的 provider 不报告这样的名称;合规的模板应读取该节点自身的 provider 提供的值。请改为读取实例 ID:该节点不自带源,因此其资源以该节点的标识命名)

而节点提供了源、且其 provider 不推导这样的名称时:

template reads the name the target gives the resources it renders for the node, and this node’s provider reports no such name; a conforming template reads a value the node’s own provider supplies (".context.rendered_name", provider "<provider>"). write a value that does not depend on a name this target derives: it reports none for the output it renders from supplied source, so there is nothing of that kind to read here(模板读取了目标为该节点所渲染资源指定的名称,而该节点的 provider 不报告这样的名称;合规的模板应读取该节点自身的 provider 提供的值。请编写一个不依赖该目标所派生名称的值:对于从所提供的源渲染的输出,它不报告任何名称,因此这里没有此类内容可读)

当引用位于 provides: 条目以外的模板中时,报告还会指出它所在的字段——field "valuesMapping"、field "artifacts[probe.tf.json]"——因为 artifacts: 条目的键是输出文件名,其中含有位置信息用来分隔各段的字符,所以位置信息止于包含该条目的块。

它覆盖哪些模板: Recipe 内联编写的每个模板——它的 provides: 条目、valuesMapping:、workload: 主体、每个 artifacts: 条目,以及每个流水线步骤的 with: 和 when:。有一类模板不在其中:通过 $import: 提供的 valuesMapping:、workload: 或 artifacts: 条目——无论导入的是本地文件还是库条目——在渲染解析它之前,在 Recipe 中不含任何文本,因此这类主体中的引用会渲染为空值,而不会停止构建。

如何修复: 读取报告指出的键。若节点的输出是在不报告名称的 provider 下为它构建的东西——合成的 workload、放置的产物集——那么 {{ .context.instance_id }} 就是这些资源实际使用的名称,它是正确的值,而非后备值。若节点提供了自己的 chart 或模块,而报告没有给出替代值,那么你想读取的名称并不是该 provider 推导的名称:请发布不依赖于它的内容,或者在你提供的源中为资源命名,并从你设置的值中读回该名称。../templates/rendered-resource-names.md 说明了哪些 provider 报告名称,以及对其余每个 provider 而言为何没有可报告的名称。

A template reads its callers’ render facts without declaring it(模板读取了调用方的渲染事实但未声明)

附加到某个 component 的 FeatureRecipe 中的模板读取了 .context.used_by 下的 render_facts——即连接到该附加宿主的各 component 报告的有关自身渲染的信息——而该 FeatureRecipe 没有设置 readsCallerRenderFacts: true。

该键决定附加何时渲染。没有它,附加会紧接在其所附加的 component 之后渲染,而在构建顺序中排在后面的连接方 component 此时尚未渲染,因此它所输出的内容不可能在那里供读取。在任何渲染之前拒绝该模板,可以把缺失的声明报告在你编写的字段上,而不是产生一个模板只读到部分调用方输出的构建。

发出的消息:

template reads its callers’ render facts, but the FeatureRecipe does not set readsCallerRenderFacts (<reference>, written in <field>)(模板读取了其调用方的渲染事实,但该 FeatureRecipe 未设置 readsCallerRenderFacts)

引用相对于读取它的连接进行引述——.render_facts 或 .render_facts.<name>——因为模板每次读取一个连接上的调用方,位于 {{ range .context.used_by }} 内部,或取自它选出的某个连接。字段指出模板所在的块:valuesMapping、workload 或 artifacts[<output-name>]。流水线步骤的 with: 或 when: 读取相同事实时,无论 FeatureRecipe 如何设置,都改由下一个条目报告,因为设置该键并不能让步骤读取它们。当多个字段读取这些事实时,每个字段各自得到一条报告,位于一行说明它们共同点的文字之下:

attachment templates reading their callers’ render facts without declaring it(附加模板读取了调用方的渲染事实但未声明)

如何修复: 在 FeatureRecipe 的 spec 中设置 readsCallerRenderFacts: true。这会让它的附加在所有 component 渲染完毕后再渲染,而不改变它们渲染内容的任何其他方面——参见 FeatureRecipe 实体页面。该键才是契约,此停止只帮助你找到明显需要它的模板:检查读取的是所写的模板,因此在模板运行时构建的引用,或写在从文件或库导入的内容中的引用,不会导致停止——对这样的 FeatureRecipe 也照样设置该键。模板若从 .context.used_by 旁边的其他列表读取名为 render_facts 的字段,同样会停止;在其旁边的 {{ with .context }} 内以 .render_facts 读取宿主自身事实的模板也会停止——请把宿主自身的事实完整写作 .context.render_facts,它永远不会被当作调用方的事实;设置该键可以清除这两种情况,代价只是渲染推后。

为某个边界只渲染一次的 FeatureRecipe(executionScope: boundary)不在此检查:生成其资源的模板没有可读取的 .context,对它的引用会改为作为超出其作用域允许列表的字段而被拒绝。

A pipeline step reads its callers’ render facts(流水线步骤读取其调用方的渲染事实)

挂接到某个组件的 FeatureRecipe 中,某个流水线步骤的 with: 或 when: 读取了 .context.used_by 之下的 render_facts,即连接到该挂接宿主的各组件就其自身渲染所报告的内容。

流水线步骤永远看不到这些连接。步骤可以改写宿主组件自身的文档,而无论谁连接到组件,组件自身的输出都保持不变,因此步骤的模板在求值时不带 .context.used_by:对每个 FeatureRecipe 都是如此,无论它是否设置了 readsCallerRenderFacts: true。该键决定挂接何时渲染,从不决定步骤能看到什么。因此,读取调用方事实的步骤将读不到任何内容;构建会在任何渲染开始之前停止,而不是把这次读取渲染为空值。

发出的消息:

pipeline step reads its callers’ render facts, but a pipeline step does not read the components connecting to its host; it reads only the host’s own render facts (<reference>, written in <field>)(流水线步骤读取了其调用方的渲染事实,但流水线步骤不读取连接到其宿主的组件;它只读取宿主自身的渲染事实)

引用相对于读取它的那个连接引用,即 .render_facts 或 .render_facts.<name>,与上一条相同;字段按 id 指明步骤:pipeline[<step>].with 或 pipeline[<step>].when。多个步骤读取这些事实时,每个步骤各有一份报告,位于一行指明它们共同之处的说明之下:

pipeline steps reading their callers’ render facts(读取其调用方渲染事实的流水线步骤)

**修复方法:**在步骤中,通过完整写出的 .context.render_facts 读取宿主自身的渲染事实:它们来自宿主自身的渲染,因此读取它们不会让任何内容依赖于谁连接到宿主。调用方的事实则应改在生成挂接自身资源的模板中读取,即其 valuesMapping:、workload: 或 artifacts:,并设置 readsCallerRenderFacts: true,如 FeatureRecipe 实体页面所述。仅设置该键并不能消除此停止。检查按模板的书写内容读取,其限制如上一条所述:在模板运行时构建的引用,或写在从文件或库导入的内容中的引用,不会导致停止;而步骤若在 .context.used_by 旁的其他列表上读取名为 render_facts 的字段,或在其旁的 {{ with .context }} 中以 .render_facts 读取宿主自身的事实,同样会停止。

针对边界只渲染一次的 FeatureRecipe(executionScope: boundary)不在此处检查,原因见上一条。

A template reads its targets’ render facts without declaring it(模板未声明即读取其目标的渲染事实)

挂接到某个组件的 FeatureRecipe 中的模板读取了 .context.uses 之下的 render_facts,即该挂接宿主所连接到的各组件就其自身渲染所报告的内容,而该 FeatureRecipe 没有设置 readsTargetRenderFacts: true。

该键决定两件事。其一,它让挂接在每个组件都渲染完成后才渲染:没有它,挂接会紧随其所挂接的组件渲染,而在构建顺序中位于其后的目标此时尚未渲染。其二,正是它把每个目标的事实放到挂接所读取的连接上:没有它,.context.uses 的任何条目都不带 .render_facts。在任何渲染开始之前拒绝该模板,会针对你所写的字段报告缺失的声明,而不是产出一个在期望目标事实之处什么也读不到的构建。

发出的消息:

template reads the render facts of a component its host is wired to, but the FeatureRecipe does not set readsTargetRenderFacts (<reference>, written in <field>)(模板读取了其宿主所连接组件的渲染事实,但该 FeatureRecipe 未设置 readsTargetRenderFacts)

引用即模板所写的那个:完整写在某个连接的别名之下,即 .context.uses.<alias>.render_facts 或 .context.uses.<alias>.render_facts.<name>;或者,在模板逐个读取连接时,位于 {{ range .context.uses }}、{{ with .context.uses.<alias> }} 中或其选取的某个连接上,相对于该连接引用:.render_facts 或 .render_facts.<name>。字段指明模板所在的块:valuesMapping、workload 或 artifacts[<output-name>]。流水线步骤的 with: 或 when: 读取相同事实时,无论 FeatureRecipe 如何设置,都改由下一条报告。多个字段读取这些事实时,每个字段各有一份报告,位于一行指明它们共同之处的说明之下:

attachment templates reading the render facts of the components their host is wired to, without declaring it(未声明即读取其宿主所连接组件渲染事实的挂接模板)

**修复方法:**在 FeatureRecipe 的 spec 中设置 readsTargetRenderFacts: true。readsCallerRenderFacts: true 不能消除此停止,因为它把事实放在连接到宿主的组件上,而不是宿主所连接的组件上。该设置会让其挂接在每个组件都渲染完成后再渲染,并把每个目标的事实放到对应连接上,除此之外不改变它们渲染的任何内容,参见 FeatureRecipe 实体页面。该键才是契约,此停止只是帮助你找到明显需要它的模板:检查按模板的书写内容读取,因此在模板运行时构建的引用,或写在从文件或库导入的内容中的引用,不会导致停止,这样的 FeatureRecipe 也照样要设置该键。只要模板读取了 .context.uses,同时又在其他值上读取名为 render_facts 的字段(包括在 {{ range .context.used_by }} 中读取调用方的事实),同样会停止;请设置该键,并在模板读取调用方事实时一并设置 readsCallerRenderFacts。

针对边界只渲染一次的 FeatureRecipe(executionScope: boundary)不在此处检查,原因见上文关于调用方的条目。

A pipeline step reads its targets’ render facts(流水线步骤读取其目标的渲染事实)

挂接到某个组件的 FeatureRecipe 中,某个流水线步骤的 with: 或 when: 读取了 .context.uses 之下的 render_facts,即该挂接宿主所连接到的各组件就其自身渲染所报告的内容。

步骤读取其宿主建立的连接,方式与宿主自身的 Recipe 相同,但从不读取这些连接目标的渲染事实:对每个 FeatureRecipe 都是如此,无论它是否设置了 readsTargetRenderFacts: true。步骤可以改写宿主组件自身的文档,而宿主自身的渲染读取的是其目标发布的内容,从不读取它们输出的内容,因此步骤的模板在求值时不带这些事实。读取它们的步骤将读不到任何内容;构建会在任何渲染开始之前停止,而不是把这次读取渲染为空值。

发出的消息:

pipeline step reads the render facts of a component its host is wired to, but a pipeline step reads only the host’s own render facts (<reference>, written in <field>)(流水线步骤读取了其宿主所连接组件的渲染事实,但流水线步骤只读取宿主自身的渲染事实)

引用的写法与上一条相同,字段按 id 指明步骤:pipeline[<step>].with 或 pipeline[<step>].when。多个步骤读取这些事实时,每个步骤各有一份报告,位于一行指明它们共同之处的说明之下:

pipeline steps reading the render facts of the components their host is wired to(读取其宿主所连接组件渲染事实的流水线步骤)

**修复方法:**在步骤中,通过完整写出的 .context.render_facts 读取宿主自身的渲染事实。目标的事实则应改在生成挂接自身资源的模板中读取,即其 valuesMapping:、workload: 或 artifacts:,并设置 readsTargetRenderFacts: true,如 FeatureRecipe 实体页面所述。仅设置该键并不能消除此停止。检查按模板的书写内容读取,其限制如上一条所述。

针对边界只渲染一次的 FeatureRecipe(executionScope: boundary)不在此处检查,原因见上文关于调用方的条目。

Cross-node type safety violation via selector:(通过选择器产生的跨节点类型安全违规)

目录作者为约束可连接或可附加的内容而编写的两种标签表达式,由同一个中止覆盖,因为两者以相同方式失败:某个标签集不满足目录实体声明的表达式。

目标不满足其 socket 的 selector: 的 uses: 边。 某个 usesSchema socket 声明了一个 selector: 字段,排除了附加在边另一端的目标 Component。selector 是目录作者表达“此 socket 只接受标签匹配此表达式的目标”的方式;一条满足 socket 名称查找但不满足 selector 表达式的边属于类型安全违规。

发出的消息:

selector violation ("", declared on socket "", not satisfied by the labels of ""). Add the labels the selector requires to the target’s component type, or wire the socket to a component that already carries them.(选择器违规:目标的标签不满足该插槽上声明的选择器表达式。请为目标的组件类型添加选择器要求的标签,或将该插槽连接到已带有这些标签的组件。)

组件不满足 Feature 的 appliesTo: 的附加。 Feature 在 appliesTo: 和 appliesToAnyOf: 上声明它可以附加到哪些组件。单个表达式的各项要求须同时成立,各备选项则择一成立,任意一个即可;两处都必须成立,而 Feature 省略的那一处被任何内容满足。若附加的组件所携带的标签不被该 Feature 的声明接受,则与上面的边情形属于同一类违规。

发出的消息:

selector violation ("", declared by Feature "", not satisfied by the labels of ""). Add the labels the Feature’s appliesTo requires to this component’s type, or attach a Feature whose applicability the component already satisfies.(选择器违规:组件的标签不满足该 Feature 声明的 appliesTo 表达式。请为该组件的类型添加该 Feature 的 appliesTo 要求的标签,或附加一个该组件已满足其适用条件的 Feature。)

两种表达式也都可能以标签语法完全无法读取的形式编写。这会报告为同一个中止,但其最后一个值是无法读取的原因,而不是未能满足它的标签集——正是这一点把无法求值的表达式与已求值但结果为假的表达式区分开来:

selector violation ("", declared by Feature "", which could not be evaluated: ""). Correct the appliesTo selector on the Feature’s catalog entity.(选择器违规:该 Feature 声明的 appliesTo 表达式无法求值。请更正该 Feature 目录实体上的 appliesTo 选择器。)

语法无法读取的套接字选择器,在任何内容连接该套接字之前也会被拒绝。 aggrega validate 无论针对整个目录,还是针对单个 Component 或 Feature,都会读取该实体自身文档所声明的每个套接字选择器,并在同一条件下拒绝语法无法读取的选择器,无论是否有边通过该套接字连接:

selector violation ("", declared on socket "", which could not be evaluated: ""). Correct the selector on the socket’s declaration in the component type’s usesSchema.(选择器违规:在套接字上声明的选择器无法求值。请在组件类型的 usesSchema 中更正该套接字声明上的选择器。)

对于 Feature 的套接字,修复建议改为指明该 Feature 的 usesSchema。尚无任何内容连接该套接字,因此错误在于目录实体:它被归类为 CATALOG_ERROR,并指明该实体的文件。

该中止携带其所涉及的编写键——uses: socket 条目,或命名该附加的 features: 条目——以及声明它的文件,因此它报告的位置是你要编辑的条目,而不是文档开头。在子系统内编写的 Component 定位在其所属的子系统,逐级定位。附加定位在编写它的文档中编写它的 features: 条目,并归于该文档的作者:Aggregate 中组件自身的块或子系统的块,属于开发者错误;对于仅由 Release 产生的附加,则是其对该组件的条目或包含该组件的边界的 features: 块,属于运维者错误。若两个文档都编写了该附加,则定位在命名其 type 的位置,而 Aggregate 总会命名它。编写在连接上的附加定位在该连接的 features: 下的键,位于编写它的文档中——Aggregate 的连接条目,或对于仅由 Release 产生的附加,Release 的逐边条目。仅由 Release 附加到其声明不接受的组件上的 Feature 显示为:

[OPS_ERROR E0007] release.yaml at .spec.boundaries.main.components.app.features.metrics
selector violation ("component.aggrega.ai/type in (server, worker)", declared by Feature "core/prometheus-exporter", not satisfied by the labels of "app"). Add the labels the Feature's appliesTo requires to this component's type, or attach a Feature whose applicability the component already satisfies.

而在 Aggregate 中编写在该组件上的同一附加显示为 [DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.app.features.metrics。由注解驱动展开产生的附加不是由任何 features: 条目编写的,因此它定位在声明该组件的文档中该组件自身的 features: 键,作为开发者错误。

**如何修复边违规:**将 uses: 边路由到标签满足该 selector 的 Component,或调整目录实体中的 selector 表达式以接受预期的目标类别。使用 aggrega inspect 查看目标 Component 的 metadata.labels,确认它携带哪些标签。

**如何修复附加违规:**将该 Feature 附加到其声明接受其标签的组件,或放宽该 Feature 的 appliesTo:——若该 Feature 确实服务于多个组件类别,则在 appliesToAnyOf: 下添加一个备选项。若组件本应符合却不符合,缺少的通常是某个标签:使用 aggrega inspect 查看它,并在该 Component 的 metadata.labels 上添加表达式所要求的内容。

Unknown provider(未知的 provider)

某个 Recipe 声明了 capability: <name>,而 <name> 并非编译器所提供的任何 provider。编译器无法将渲染分派给它从未知晓的 provider。

发出的消息:

unknown provider: <provider-name>(未知的 provider)

**如何修复:**确认 provider 名称拼写正确——cloudformation、compose、helm、helm-chart 和 terraform 是内置 provider 插件所提供的名称。如果你想使用自定义的企业 provider,请确保构建所指向的目录工作区中存在提供该名称的 provider 渲染 Plugin(pluginType: provider,且其 spec.provider.capabilities 中包含该名称)。

A capability is served by more than one provider plugin(某个能力由多个 provider 插件提供)

构建遇到某个能力——或拉取解析某个能力——而它由多个 provider 渲染 Plugin 提供(pluginType: provider,各自在其 spec.provider.capabilities 中列出该能力),且工作区尚未选定由哪一个渲染。构建不会随意挑选 provider,而是中止并列出两个候选项。目录中为同一能力携带两个插件是合法的——两个发布者可以各自为 helm 或 compose 发布一个插件,目录会同时接受。歧义只在使用时显现:中止在构建或拉取实际遇到有争议的能力时触发,而不是在加载时。

发出的消息。导致构建中止的规则在前,具体信息——哪个能力、哪些候选项以及要编写的绑定——紧随其后:

capability is served by more than one provider plugin; add a plugins.providers entry to select one: capability "<capability-name>" is served by more than one provider plugin (<plugin-1>, <plugin-2>); add a plugins.providers entry for "<capability-name>" selecting one(该能力由多个 provider 插件提供;请添加一个 plugins.providers 条目以选择其中之一)

**如何修复:**在工作区配置中添加一个以该能力为键的 plugins.providers 条目,其值选定渲染该能力的插件标识。在联合目录中保留两个插件;该绑定告诉此工作区对有争议的能力应分派给哪一个。

The plugin serving a provider cannot assemble what that provider combines(服务某个 provider 的插件无法组装该 provider 所合并的内容)

provider 会声明一个分派组的逐节点输出如何处理:每个节点的输出直接写到分派路径,各片段折叠为一个文档,或者每个节点放在一个外层结构内各自的位置下。若 provider 声明输出是合并的(合并后的 compose 文件、umbrella chart),服务它的插件就必须提供执行合并的导出。若插件未提供,就会触发此终止:插件声明了逐节点渲染(render_node),却没有对应的 assemble_boundary,因此该组的节点可以渲染,其输出却无法合并。

这一不一致的两方面都属于插件。分派组的输出如何处理,是插件在加载时报告的自身信息的一部分;而执行合并的导出是 Plugin 实体 spec.exports 下的条目之一,并会与同一份报告交叉核对。因此,此终止指出的是一个声明了组装、而其导出面并未提供组装的插件。

构建会终止,而不是跳过组装。跳过组装会把每个节点的片段写到原本预期存放一个制品的路径上并报告成功,而后续环节无法将这些片段与不声明组装的 provider 按设计输出的扁平逐节点输出区分开来,因此缺失的制品会在应用输出时才暴露,而不是在构建时。

没有分派路径的分派组会被跳过。写在无路径处的输出是逐节点输出,因此那里不进行组装,也就没有需要合并声明来约束的内容。

发出的消息:每个出错的分派组一条结果,指出 provider 以及该组组装所在的路径:

provider expected to assemble its dispatch group provides no boundary assembler ("<provider>", dispatch path "<path>")(预期组装其分派组的 provider 未提供边界组装器)

若有多个分派组出错,这些结果会一并归在报告 dispatch groups whose provider offers no boundary assembler 下。

**修复方法:**使用同时声明 render_node 和 assemble_boundary 的插件来服务该能力。关于 spec.exports 的编写面,参见 ../entities/plugin.md;关于组装导出接收的内容,参见 ../schema/plugins/wasm-provider.md。若插件由你编写,两方面由你来对齐:添加组装导出,或者不报告组装声明,让每个节点的输出不经合并地落到分派路径。若你使用的是已发布的插件,请选择提供这两个导出的版本,或者选择其 provider 对该能力不声明组装的插件。

A boundary-level Feature’s output reaches no assembled file(边界级 Feature 的输出未进入任何组装文件)

挂载在边界的 features: 下、且其 FeatureRecipe 声明了 executionScope: boundary 的 Feature,会为整个边界渲染一次,其输出写入边界自身的 directory: 和 subDirectory: 为它求值得到的目录。将输出合并为一个文档的 provider——compose 合并为一个 docker-compose.yaml,cloudformation 合并为一个栈——只会把此类 Feature 的贡献作为它在该处根据边界的组件组装出的文件的一部分写出。只有当至少一个组件的输出在同一 provider 下落入同一目录时,该文件才存在。

当边界的组件落在别处时,该文件就不存在:例如它们位于嵌套边界中,而这些边界的 subDirectory: 把它们送往别处——比如 "{{ .component_id }}",让每个组件各得一个文件——或者位于 Feature 的输出不共享的目录下。Feature 的目录中没有组装任何内容,因此其输出将无处写入——对 compose 桥接而言,就是一个没有任何文件承载的网关服务——而构建却会报告成功。因此构建会改为中止。

provider 将每份贡献写为独立文件的 Feature——helm、helm-chart 和 terraform——不受影响:无论旁边是否组装了任何内容,这些文件都会被写出。

输出的消息——每个违规 Feature 一条发现,定位在其位于边界 features: 下的条目处,指明边界、Feature、其输出被路由到的分派路径以及 provider:

boundary-level Feature’s output is routed to a dispatch path nothing assembles (boundary "<boundary>", feature "<instance>", dispatch path "<path>", provider "<provider>"). attach the Feature at a boundary whose output path also receives its components, or give the boundary’s components the directory the Feature’s output is routed to(边界级 Feature 的输出被路由到一个没有任何内容组装的分派路径。请将该 Feature 挂载到其输出路径同时接收其组件的边界上,或者为该边界的组件指定 Feature 输出被路由到的目录)

挂载在父边界 bridge 上的 compose 桥接,若其唯一的子边界将每个组件放在 subDirectory: "{{ .component_id }}" 下,会输出:

[OPS_ERROR E0365] release-compose.yaml at .spec.boundaries.bridge.features.gateway
boundary-level Feature's output is routed to a dispatch path nothing assembles (boundary "bridge", feature "gateway", dispatch path "bridge/compose", provider "compose"). attach the Feature at a boundary whose output path also receives its components, or give the boundary's components the directory the Feature's output is routed to

当违规的 Feature 不止一个时,这些发现会一起归在报告 boundary-level Features whose output is routed to a dispatch path nothing assembles 之下。

修复方法: 让 Feature 的目录成为其边界的组件也会落入的目录。要么将 Feature 挂载到其自身输出路径接收这些组件的边界上,要么为这些组件指定 Feature 输出被路由到的目录——对于子边界,使用 directory: "{{ .parent_boundary.directory }}" 且不设置自己的 subDirectory:,使它们共享父边界的文件。消息会指明 Feature 输出被路由到的目录,也就是需要共享的那个目录。

Path-template references a variable outside the allowlist(路径模板引用了允许列表之外的变量)

directory: 或 subDirectory: 模板引用了路径模板变量允许列表中不包含的变量名,例如 {{ .parmaeters.region }} 这样的拼写错误,或者某个存在于 Recipe 渲染上下文中、但不向路径模板公开的字段(如 .context.inject 或 .values)。同一终止也涵盖 directory: 模板中的 {{ .component_id }}:该变量存在,subDirectory: 模板也可以读取它,但边界的 directory: 对整个边界只求值一次,而不是每个组件求值一次,因此在那里使用逐组件变量会使生成的路径取决于恰好最先求值的是哪个组件。

路径模板在解析时、任何渲染工作开始之前进行校验,校验依据是路径模板上下文定义的变量减去特定编写面拒绝的变量。编译器还以 missingkey=error 语义对路径模板求值,因此一个在允许列表内、但求值时未定义的引用会产生明确的错误,而不是悄悄地把空字符串渲染进目录路径。

此终止针对的是变量。若在允许的变量之下拼错了键,例如 {{ .manifest.recipe_nmae }},则会报告上文的“Template references a root the render context does not define(模板引用了渲染上下文未定义的根)”,并列出 .manifest 确实定义的键,因为变量本身已被接受,只是键错了。

发出的消息:

path template references a field not in the documented allowlist ("<dotted-path>", written in "<directory|subDirectory>", the render context defines "<the variables that field may read>")(路径模板引用了不在文档所列允许列表中的字段)

**修复方法:**将字段名改为路径模板允许列表中的名称,或者删除该引用。directory: 的允许列表为 {{ .capability }}、{{ .boundary_name }}、{{ .parameters.X }}、{{ .manifest.recipe_name }} 和 {{ .parent_boundary.* }};subDirectory: 另外增加 {{ .component_id }}。其他编写面(Recipe valuesMapping、FeatureRecipe injectMapping 等)使用不同的上下文结构;对 .context.*、.values、.infra 或 .locals 的引用有意不向路径模板公开,因为路径生成是结构层面的问题,而不是值渲染层面的问题。

Path collision: two contributors emit at incompatible paths(路径冲突:两个贡献者在不兼容的路径上输出)

两个边界的路径声明求值为同一组装路径,却经由不同的 provider 路由。两者都在那里组装,各自写入对方毫不知情的文件,因此其中一个会在磁盘上悄悄覆盖另一个,而产出被覆盖输出的那次构建看起来却是成功的。

默认的 subDirectory: 会给每个 provider 一个独立的子路径,因此只有当声明被写成求值结果相同时,两个 provider 才会落到同一路径,例如两个边界共用一个 directory:,并且都把 subDirectory: 固定为同一个字面值。

**发出的消息。**每个参与的边界报告一条结果,因此输出到达该路径的每个边界都会被单独指出,而不是在一条消息里合并成列表。故障在于两个 provider 落到同一路径,所以结果总是至少有两条,并且它们会一并归在一份说明其共同点的报告下:

assembly paths reached by more than one provider(被多个 provider 到达的组装路径)

每条结果指出路径、输出到达该路径的边界,以及该边界经由的 provider:

dispatch path produced multiple provider outputs ("<path>", boundary "<boundary>", provider "<provider>")(分派路径产生了多个 provider 的输出)

若某次构建的 api-net 和 db-net 两个边界都声明了 directory: ./dist/shared 和 subDirectory: merged,一个经由 helm 路由,另一个经由 compose,则会打印:

[OPS_ERROR E0048]
assembly paths reached by more than one provider
caused by (2):
[OPS_ERROR]
dispatch path produced multiple provider outputs ("dist/shared/merged", boundary "db-net", provider "compose")
---
[OPS_ERROR]
dispatch path produced multiple provider outputs ("dist/shared/merged", boundary "api-net", provider "helm")

报告带有短代码,其下的每条结果只带各自的类别,这是所有汇总失败报告共用的结构,该语法参见 error-translation.md。

**修复方法:**要么给每个边界不同的 directory:(使它们组装到不同路径),要么让 subDirectory: 保持默认值,使每个 provider 的输出落到各自的子路径。compose-bridge 模式有意将两个子边界合并为一个组装路径;该模式要求两个边界指向同一个 provider,并带有兼容的、经级联解析的注解。

A boundary’s output directory is not a directory beneath the output root(boundary 的输出目录不是输出根目录下的目录)

boundary 的 directory: 和 subDirectory: 经求值后拼接成写入其输出的目录,该路径会清理一次:out/a、out//a、./out/a 和 out/a/ 是同一个目录。若清理后的路径不是输出根目录下的目录,构建会在写入任何内容之前停止。这包括跳出输出根目录的路径(..、../escape、a/../..)、绝对路径(/srv/out),或根本不指向任何目录的路径:空值,或清理后即为输出根目录本身的值,例如禁用子目录时的 directory: "."。

路径按求值后的结果检查,因此判断的是模板的结果,而不是书写的文本。消息会指出问题来源的字段——当目录本身已离开输出根目录,或其上未拼接任何子目录时为 directory:,否则为 subDirectory:——并给出该字段求值得到的值及其生成的路径。

发出的消息:

boundary output directory does not name a directory beneath the output root (Release "<release>", boundary "<boundary>", directory: "<value>", output path "<path>"). write a directory beneath the output root, such as “deploy/prod” — no leading ”/”, no ”..” climbing above it, and not the output root itself(边界输出目录未指向输出根目录下的某个目录(依次为 Release、边界、directory 的值与输出路径)。请写一个输出根目录下的目录,例如 “deploy/prod”——不要以 “/” 开头,不要用 “..” 向上越出根目录,也不能是输出根目录本身)

若问题出在子目录,第三个值改为 subDirectory: "<value>"。

**修复方法:**将消息指出的字段写成输出根目录下的目录。原本打算放在输出根目录旁边的目录应改放在其内部。若要将 boundary 的输出直接写入其 directory:,请设置 subDirectory: "."——目录本身仍必须指向一个独立的目录。

A boundary-level Feature is named . or ..(边界级 Feature 的名称为单点或双点)

为每个贡献者分配独立目录的 provider——terraform 放在 modules/ 下,helm-chart 放在 charts/ 下——会把附加在 boundary 上的 Feature 放到一个仅以实例命名的目录中,与该 boundary 的组件并列。boundary 的 features: 键接受 . 和 ..,但两者都不是目录名:. 会把该 Feature 的文件放进容纳所有贡献者的目录,.. 则放进其上一级目录,于是文件会落在 provider 为该 Feature 分配的位置之外。因此构建会停止。其他名称均不受影响,包括带点的名称,例如 audit.v2。

发出的消息:

boundary-level Feature instance name is not a directory name (Release "<release>", boundary "<boundary>", feature "<instance>"). rename the Feature instance under the boundary’s features to an ordinary name, such as “audit”(边界级 Feature 实例名称不是目录名(依次为 Release、边界与 feature 实例)。请将该边界 features 下的 Feature 实例重命名为普通名称,例如 “audit”)

**修复方法:**将 boundary 的 features: 下的实例重命名为普通名称。

Instance-ID collision across boundaries assembling to the same path(组装到同一路径的多个 boundary 之间发生实例 ID 冲突)

两个组装到同一 (path, provider) 元组的 boundary 贡献了实例 ID 相同的组件。合并后的组装无法区分这两个组件片段——单个 Helm chart 不能包含两个名为 web-server 的 Deployment,单个 docker-compose 文件也不能包含两个名为 api 的服务。

发出的消息:

multiple contributors share an instance ID at the same dispatch path: dispatch path "<path>" provider "<provider>" already contains node "<instance-id>" (contributing boundaries: [<boundaries>]); component instance IDs must be unique within an assembly group(多个贡献者在同一分发路径上共用一个实例 ID:该分发路径与 provider 下已包含同名节点(并列出参与贡献的边界);组件实例 ID 在一个组装组内必须唯一)

**修复方法:**在 Aggregate 中重命名其中一个冲突的组件,或将两个 boundary 拆分到不同的 directory: 路径,使每个组件实例落在各自的组装中。

Two contributors write the same output path(两个贡献者写入同一输出路径)

一次组装的两个贡献者在同一输出路径上生成了文件。这与上文的实例 ID 冲突不同:这些组件名称不同,组装也能区分它们——是它们生成的文件落在了同一路径上。这种情况最常发生在 provider 将各贡献者的输出并排写出、而非放在按组件划分的位置之下时,于是 Recipes 生成相同文件名的两个组件(例如两个都命名为 main.tf 的 artifacts: 条目)会在同一路径相遇。组装器自身的输出也可能以同样方式与某个贡献者的文件冲突。

发出同一文件名的两个贡献者是否冲突,取决于其 provider 如何放置它们。将每个贡献者嵌套在组装中各自位置下的 provider 会让两个同名文件互不干扰;并排写入贡献者的 provider 则不会。比较的是文件最终将写入的路径,而不是贡献者发出的名称,因此嵌套的情况不会被报告。

构建会停止,而不是写入两个文件中的一个并丢弃另一个。不存在正确的静默解决方式:重命名或为某个文件加后缀会凭空造出一个无人编写的名称,合并其内容则会凭空造出一个无人编写的文档。每个冲突路径都会被报告,写入该路径的每个贡献者都会被列出,因此一次构建就能告诉你全貌,而不是一次只报一个冲突。

**发出的消息。**每个冲突路径报告一条发现——只报一次,无论有多少 boundary 为发生冲突的组装提供了输入——因此贡献者在两个路径上相遇的构建会告诉你两处冲突,且每处都不会重复报告:

assembled output collision: two contributors write the same output path (output path "<output-path>", written by "<contributor-1> and <contributor-2>", assembled within "<boundary-1> and <boundary-2>")(组装输出冲突:两个贡献者写入同一输出路径(依次为输出路径、写入它的贡献者,以及组装所在的边界))

每个贡献者按其类型命名,这也说明了其名称写在何处:组件实例为 component <name>,附加在 boundary 上的 feature 为 feature <name>,组装自身合并的输出为 the <provider> assembly。贡献者按名称顺序列出,因此对相同输入的每次构建,这句话都相同。

**Recipe 向 boundary 共享输出贡献的文件同样适用此规则。**Recipe 的 boundary: 块将其文件写在 provider 自身组装输出的旁边,每个文件名一次。多个组件以相同字节声明同一名称时视为同一个文件,永不冲突;以不同字节声明则会在此冲突,消息会指出该文件及声明它的每个组件;与 provider 组装自身写入的名称相同也会冲突——例如 terraform 的 aggrega.modules.tf,此时贡献者中会列出 the terraform assembly。多个组件以相同内容声明的文件若与组装自身的文件相遇,会列出所有这些组件,形如 component <name-1> and component <name-2>。

为该组装提供输入的 boundary 也会被列出,而且是全部列出,而非单独指出某一个。directory: 声明求值结果相同的 boundary 会作为一个整体组装,而冲突本身无法说明相遇的贡献者声明在其中哪一个里——因此这条发现会给出声明可能将它们分开的每个 boundary,且不断言其中任何一个就是出错的那个。出于同样的原因,这条发现针对整个 Release 文档报告:指出其中某个 boundary 可能会把你引向一个对该路径毫无贡献的文档。

当多个路径发生冲突时,这些发现会一并归在一条说明其共同点的报告下:

assembled output paths written by more than one contributor(被多个贡献者写入的组装输出路径)

**如何修复:**在你能控制的那个 Recipe 中重命名所生成的文件——artifacts: 键、boundary: 块的键,或 Workload 转换所派生的文件名——使两者不再相遇。如果两个 Recipes 声明了同一个共享文件且表示相同的配置,请让它们的声明逐字节一致。如果两个贡献者确实属于不同的输出,请为它们的边界指定不同的 directory: 路径,使各自独立组装。

The same name is derived more than once inside the output(输出中同一名称被派生了不止一次)

一个装配最终在其发出的文件内部把同一个名称用了两次,而该处只容得下一个。这有两种情况:两个贡献者派生出同一个名称,或者单个贡献者自身的输出两次携带该名称。这与上面的两种冲突不同:涉及两个贡献者时,这些组件名称不同,其文件也落在不同路径上,因此装配的结构本身没有问题——问题在于内容中的某个名称,例如目标用来寻址某个资源的标识符,或某个输出发布时供他处引用的名称。

**比较哪些名称,取决于 provider 如何处理装配的输出。**若 provider 将该输出合并为单个文档——一个栈模板、一个 compose 文件——则比较的是该文档内部的名称彼此之间,而输出被写成独立文件的贡献者位于该文档之外。它的名称不会与任何其他名称相遇,因此它们之间不会中止,你改任何名称也不会改变这一点。若 provider 改为把每个贡献者的输出写成各自的文件——一次 chart 渲染、一组清单——则装配的每个贡献者都会与其他每个贡献者比较,因为此类输出中的名称须在把这些文件作为一个集合读取的整体范围内唯一,而不只是在单个文件内唯一。

FeatureRecipe 自身的资源与其宿主组件的资源走同样的路径,因为附加项会贡献到其宿主所属的装配中。因此在 provider 合并时,附加项的名称会与其宿主组件的名称以及其他每个附加项的名称比较,与两个组件名称之间的比较完全相同:它们都会进入同一个文档,两个相同名称中的一个会在其中取代另一个。在 provider 不合并时,附加项的资源写在以其所附加组件命名的目录下,其名称仍会与装配的每个贡献者比较——须在整个集群内唯一的资源标识正是在这里被发现的。因此两种情况下的比较是相同的,不同的只是将被取代的名称最终位于何处。

这一中止的另一半不受上述任何影响:单个贡献者自身的输出两次携带同一个名称。这是在一个贡献者所写的输出中两次使用同一个名称,因此无论该输出写在哪里都会中止,而需要区分的两者总是在该输出内部。

此类名称大多由 provider 自己派生,来源于组件实例和资源,因此只要派生所依据的各部分一致,两个组件就可能得到同一个名称——一个组件也可能以同样方式两次得到同一个名称,即其自身的两个资源由一致的部分构建而成。由于名称存在于文件自身的字节中,装配无法看到它:provider 报告它派生的名称,由构建对其进行比较。

有一种名称属于构建自身而非 provider,其报告方式相同:FeatureRecipe 发出的每个资源所标注的标识,它以 aggrega.ai/component-id 标签的形式进入你的输出。它以名称种类 component-id 报告,因此你可以在自己发出的输出中找到同一个字符串。若 FeatureRecipe 合成其资源,这些资源也以该标识命名;若它渲染其作者提供的 chart 或片段,该渲染中的名称仍为宿主组件的名称,只有标签携带该标识。

对于附加到组件的 feature,它由该 feature 所附加的组件和你在 features: 下写的键组成,前面带有固定的开头。宿主组件之所以是值的一部分,是因为附加到多个组件的同一个 feature 名称会在每个组件上发出一组独立的资源,而每组都需要自己的标识。

对于附加到边界的 feature,它由该 feature 的名称和边界路径的每个段组成,前面带有其自己的开头。两处都采用组合而非替换:标签字母表不接受的字符会被写出而非替换,各部分由任何写出部分都不可能包含的字符序列连接,因此你能区分的两个附加项总会得到两个标识。唯一的残余问题是长度:对标签值而言过长的组合标识会围绕其整体的摘要被缩短,而两个缩短后的标识在理论上可能相遇。此中止报告的正是在名称被比较的两个贡献者之间发生的这种相遇;一个组件上的两个附加项,凡其宿主的 provider 将它们装配在一起之处,都是这样的两个贡献者。每种标识如何构建,参见 ../providers/well-known-annotations.md。

Kubernetes 渲染会报告一种自己的名称:其自身渲染产生的每个资源在 metadata.name 中携带的名称。此类名称须在其 kind 内唯一——对于集群按命名空间保存的种类,还须在其命名空间内唯一——而不是在整个输出中唯一,因此名称种类会说明它的作用域。它以 resource-names 开头,然后携带资源的 kind 以及资源所落入的命名空间,即资源为自己指定的命名空间,若未指定,则为边界所标注的命名空间。因此 resource-names:Service--default 是落入 default 的 Services 的名称。Kubernetes API 保存在所有命名空间之外的种类——ClusterRole、StorageClass、CustomResourceDefinition——以及同一渲染中某个 CustomResourceDefinition 以作用域 Cluster 声明的自定义种类,只携带其 kind,无论其文档写的是哪个命名空间:resource-names:ClusterRole 是输出携带的每个 ClusterRole 的名称。字母和数字之外的任何字符都会被写出而非替换,两部分由任何写出部分都不可能包含的字符序列连接,因此两个不同的组合永远不会得到同一个名称种类,单独的种类也永远不会得到种类加命名空间的名称种类。Service 和 Deployment 可以同名,两个命名空间也可以各自持有同一个命名空间级种类的名称,因此这两种情况都不会中止。名称本身完全按你的 chart 所写的方式报告,因此它就是你在模板中要搜索的字符串。

因此,同一输出的两个贡献者若各自以同一个名称写入一个集群级对象,即使 Release 将它们放在两个命名空间中也会中止,因为同时应用两者会把该对象写两次;一个 chart 若在两个不同命名空间下写入这样的对象(渲染会将其发出为两个文件),则作为单个贡献者两次携带该名称而中止。渲染中没有任何内容对其分类的种类——其 CustomResourceDefinition 未被该渲染发出的自定义种类,或未指定 apiVersion 的文档——会像命名空间级种类一样在其命名空间内比较,因为渲染中没有任何内容表明集群将其保存在命名空间之外;因此两个贡献者在两个命名空间中写入这样一个对象不会相遇。

名称在同一输出的贡献者之间比较,从不在两个输出之间比较。两个边界各自拥有自己的目录时——它指定的目录,或每个未指定 directory: 的边界被赋予的目录——它们就是两个输出,而构建中没有任何内容表明两个输出是应用到同一个集群还是两个集群:某个 operator 的 CustomResourceDefinition 分发到两个集群,就是两个输出中的同一个名称,这是正确的。因此,两个边界各自以同一个名称写入一个集群级对象时,即使两者都应用到同一个集群也会构建成功;若确实如此,请只从其中一个边界发出该对象。

最常触发此中止的情形,是在一个 component 上挂载两个 Features,每个都交付其作者提供的 chart。两个 chart 都以同一个 release 名称渲染——即宿主 component 的名称,这样挂载 chart 不会重命名其作者已声明并部署的资源——而以 release 名称命名资源是 chart 最常见的做法之一。输出的结构没有任何问题:只是两个资源带有同一个名称。若该 component 的 provider 写出彼此独立的文档,则每个挂载写在各自的目录下,同时应用两者只会留下最后应用的那个;若它把其组折叠为一个文档,则两个挂载都向该文档贡献内容,两个名称中的一个会在其中覆盖另一个。请在你能控制的 chart 中重命名该资源,或给它一个带有能区分两个挂载的信息的名称——必须让挂载信息到达模板,因为两个 chart 都以宿主的 release 名称渲染,所以仅重命名挂载不会改变任何东西。通过该 FeatureRecipe 的 valuesMapping: 将 .attachment_name 传入 chart,并将其设置到 chart 自身用于构建资源名称的那个值上。

第二种情形以一个 Feature 而非两个触发同一中止:一个 chart 的模板以字面量写出资源名称,并被挂载到两个 component 上。每个宿主都以各自的 release 名称渲染它,因此字面量是两个副本带有同一名称的唯一原因——以 .Release.Name 命名该资源,宿主就重新成为名称的一部分,这正是根据 release 标识构建资源名称的 chart 本来的做法。

第三种情形结构相同,只是在编写层面更深一层:一个 FeatureRecipe 通过 artifacts: 而非 chart 交付其资源,以同一名称挂载到两个 component 上,且其主体以字面量写出资源名称。每个挂载的输出都落在以其宿主命名的目录下,因此输出路径不同,输出的结构也没有任何问题——但两个主体带有同一名称,同时应用两者只会留下最后应用的那个。artifacts 主体中的名称与 chart 渲染出的名称以完全相同的方式比较:两者描述同一集群中的同一资源,因此名称来自何处,对两者都被应用时发生的事情没有任何影响。这种解读的前提是两个名称被一起读取,这发生在 provider 将每个贡献者的输出写为目标作为一个集合读取的文件时。若 provider 改为将一次组装的输出合并为单个文档,则每个挂载的文件都位于该文档之外,其中某个文件内的名称仅限于该文件范围,因此两个这样的挂载永远不会相遇,构建会继续进行。

并非每个名称都会被报告,因此未中止的构建并不能证明其输出最终带有的每个名称都已被比较。留给集群命名的资源——声明 generateName 而非 name 的资源——此时尚无名称,因此没有可报告的内容。而写入其他某个字段、供控制器稍后读取的名称不是资源名称,因此不会被比较。这两个限制都源于对输出文档的读取,因此它们对 artifacts 主体的适用方式与对渲染后的 chart 模板完全相同。

artifacts: 主体是模板,因此其中必须按宿主区分的名称应当组合构成,而不是写成字面量。.context.rendered_name 是宿主 component 自己的 provider 为其指定的名称——在 helm 下即其 release 名称,以 Kubernetes 名称允许的字符拼写——而 .attachment_name 是你挂载它时使用的键,因此 {{ .context.rendered_name }}-{{ .attachment_name }} 会在每个宿主、每个挂载下为资源提供独有的名称。若宿主的 provider 不报告这样的名称,则改用宿主的标识 .context.instance_id 来组合。一份编写的主体会携带其中的所有名称到达它挂载的每个宿主,而字面量在所有宿主上都相同——因此,对必须在集群中唯一的名称,请采用上述形式。

名称的含义不会被解释——两个被报告的名称要么是相同的文本,要么不是——因此同一份报告涵盖每一种名称,无论由谁派生。

对于一个 component,一个名称可能出现在多份报告中,因为 component 的每个部分在渲染时都会各自报告。这是一个资源出现在它所属的每份报告中,而不是一个名称被使用两次,不会中止构建。会中止的是单份报告中同一名称出现两次,因为该报告描述的输出中该名称确实被使用了两次。

这种解读取决于什么算作一个贡献者,对于 component-id 这种名称,答案是挂载,而不是它所在的 component 或 boundary。一个挂载由你为它写下的两个坐标共同标识——它所挂载的 component 加上 features: 下的键,或 boundary 路径加上该 boundary 下的名称——因此同一个 component 上的两个挂载是两个贡献者,与不同 component 上的两个挂载完全一样;在两个 boundary 上写下的同一 feature 名称也是两个贡献者,即使每处的名称相同。作为两个贡献者,正是使它们的标识在上述每种情形中可比较的原因;而它们之间究竟是否会被比较,遵循与此处其他所有名称相同的规则,因此在 provider 进行合并时,输出被写为独立文件的挂载位于合并文档之外,只与自身比较。因此,两个挂载得到同一标识时,只要其输出能相互触及,就会中止,且每条结果都会给出其两个坐标,以便你判断要区分哪两者。由于两个坐标都是组合值的一部分,两个可区分的挂载在任何合适的长度下都会得到两个标识——因此触发此中止的情形,是某个值对其目标而言过长而被缩短,且两个缩短后的值相遇。若两个缩短后的标识相遇,而其输出无法相互触及——同一 component 上的两个挂载,处于进行合并的 provider 下,且各自被写为独立文件——则没有任何东西会比较它们,两组资源将共用同一个 aggrega.ai/component-id。

有一种情形值得明确说明,因为它看起来应当中止却不会:在两个 component 上以同一名称挂载 feature 是完全支持的,无需重命名。component 是组合值的一部分,因此 api 上的 metrics 与 web 上的 metrics 会得到两个标识,每个 component 的资源都有各自的标识——这一点很重要,因为按设计在多个 component 间生成同一挂载名称的级联,不会给作者留下可写的其他名称。FeatureRecipe 交付资源的每种方式都会把其标识加在输出内容上,包括仅引入源并按原样渲染的方式,因此每种方式都会被比较;FeatureRecipe 完全不输出任何内容的 feature 则没有可比较的东西。

构建会中止,而不是保留一个、丢弃另一个。不存在正确的静默解决方式:保留第一个会把你声明的某个资源从输出中完全丢弃,同时构建仍报告成功,而引用被丢弃资源的任何内容都会悄然解析到保留下来的那个。每个冲突的名称都会被报告,各自附上其名称种类,并列出派生它的每个贡献者——因此一次构建就能让你看到全貌,而不是一次一个冲突。自身输出中带有两次该名称的贡献者,会被标为多次派生了该名称,由此可知需要区分的两者位于该 component 内部,而不是在两个 component 之间。

发出的消息。 每个冲突名称的每个贡献者各报告一条发现,因此派生该名称的每个贡献者都会单独列出,而不是合并到一条消息内的列表中。当两个贡献者派生了该名称时,至少会有两条发现,它们会一起出现在一份说明其共同点的报告之下:

dispatch groups whose contributors derive one name more than once in one key space(其贡献者在同一键空间中多次派生同一名称的分派组)

每条发现会给出该名称、名称的种类、派生它的贡献者,以及其输出所合并到的装配的 provider 和路径:

derived name collision: one name is derived more than once in one key space(派生名称冲突:同一名称在同一键空间中被多次派生) ("<name>", key space "<kind-of-name>", derived by component "<contributor>", provider "<provider>", dispatch path "<path>")

贡献者按其类别来命名,这也说明了其名称写在何处:组件实例为 derived by component,附加到边界的 feature 为 derived by feature。

当贡献者自身的名称不足以单独标识它时,后面会跟上第二个坐标,具体是哪一个取决于种类。附加到边界的 feature 带有该边界的路径,因为同一个 feature 名称可能写在多个边界上:

derived name collision: one name is derived more than once in one key space(派生名称冲突:同一名称在同一键空间中被多次派生) ("<name>", key space "<kind-of-name>", derived by feature "<feature-name>", attached at boundary "<boundary-path>", provider "<provider>", dispatch path "<path>")

组件带有其渲染派生了该名称的那个附加项的键,因为组件对你写下的每个键各带一个附加项:

derived name collision: one name is derived more than once in one key space(派生名称冲突:同一名称在同一键空间中被多次派生) ("<name>", key space "<kind-of-name>", derived by component "<component>", carrying attachment "<attachment-key>", provider "<provider>", dispatch path "<path>")

组件自身的渲染——即其 provider 为组件本身而非为其某个附加项派生的名称——不带第二个坐标,因此该发现以组件名称结束。

当单个贡献者自身的输出中两次出现该名称时,该贡献者就是唯一的发现,因此它会单独出现,上方没有报告——并且它会被标记为多次派生了该名称,而不是与另一个贡献者相遇:

derived name collision: one name is derived more than once in one key space(派生名称冲突:同一名称在同一键空间中被多次派生) ("<name>", key space "<kind-of-name>", derived more than once by component "<contributor>", provider "<provider>", dispatch path "<path>")

此处第二个坐标同样按上述条件跟在贡献者之后,因此某个附加项自身输出中的重复会指明该附加项,而不只是携带它的组件。

修复方法: 当列出两个贡献者时,在 Aggregate 中重命名其中一个,使由它派生的名称不再与另一个的相同。当名称种类为 component-id 时,每条发现已经指明了要重命名的对象:carrying attachment "…" 是该组件 features: 块下的键,而 feature "…" attached at boundary "…" 是该边界 features: 块下的名称。当两条发现仅在所指边界上不同时,说明这两个附加项在两个边界上使用了同一名称——重命名其中一个,或为两个边界设置不同的 directory: 路径,使其输出不再合并。当两个名称是构建组合出来的时,它们只可能是在为适应目标而被截短后才相遇的,因此请自行缩短组成它们的部分,而不要交给构建去截短。当两个名称都派生自你显式设置的内容——Recipe 传给 provider 的某个值,或 provider 读取的某个注解——请在你能控制的那一方修改它。当两个贡献者确实属于不同的输出时,为它们的边界设置不同的 directory: 路径,使各自独立装配,两个名称永不相遇。当单个贡献者被标记为多次派生了该名称时,两个冲突对象都在该组件内部:找到其 Recipe 生成的、名称相同的两个资源,修改其中一个的命名依据——它声明所用的键,或构建它的某个值——使 provider 为每个资源派生不同的名称。当名称种类本身是集群作用域的种类(例如 resource-names:ClusterRole)时,无论这些文档被放在哪个命名空间,它们描述的都是集群中的同一个对象:只从一个贡献者发出它——通过其 chart 提供的某个值,例如安装其定义的开关——或者,若两者本应是两个对象,就在你能控制的 chart 或主体中为其中一个赋予独立的名称;若单个贡献者因此被列出两次,说明它把该对象写在了两个命名空间下,应删除其中一个文档。

An authored export name is one the build derives for a cross-stack reference(编写的导出名称与构建为跨栈引用派生的名称相同)

cloudformation Recipe 的 Outputs: 块是编写的 CloudFormation,其中的条目可以带有自己的 Export: 和 Name:;该名称会原样进入组装后的栈。另外,当一条 uses 边从一个边界跨到另一个边界时,provider 会把被消费的值发布为一个栈 Output,并带有一个 Export,其名称由 release、边界、组件和提供的键派生而来。此终止在两者相遇时触发:你编写的名称正是同一次构建中派生得到的名称,因此栈会从两处声明同一个导出名称,而导出名称必须唯一。

只有这种重合才会终止构建。在 Outputs 条目上声明导出名称是受支持的,与任何派生名称都不匹配的导出名称会与派生名称一同发布,不会有任何提示——但跨栈引用为其消费的某个键发布自身导出所用的那个栈输出除外。那里的 Export: 只要不是恰好携带派生名称就会终止构建;这种情况见 The output a cross-stack reference publishes on already carries an Export(跨栈引用发布所在的输出已带有 Export)。

该终止会给出派生的导出名称及构成它的四个部分,以便你看出是哪个跨边界引用产生了它;它还会指出你的声明所在的栈输出——并标明这是 provider 组装的名称,而不是 Recipe 编写的名称,因为 provider 会把组件和条目编码为逻辑 ID 所允许的字母和数字来构建该名称,所以它不是两者原本写成的字符串。**要搜索的是导出名称。**你的条目对它的拼写与终止信息完全相同,这正是两者构成冲突的原因,因此它是同时出现在消息和你自己的文件中的唯一字符串。

比较的范围限于一个栈:该栈声明的导出名称,与为发布到该栈的跨边界引用所派生的名称进行比较。两个栈之间不会相互比较;以 CloudFormation 内部函数写成的导出名称在部署时才解析,因此没有可比较的名称。一个名称与某账户和区域中已部署的导出之间是否冲突,属于部署的性质,构建无法观察到。

发出的消息。条件给出失败的类型,provider 自己的句子说明发生了什么;外围报告还会指出正在连接的 uses 边:

two things a plugin produced occupy one name in its output(插件生成的两项内容在其输出中占用了同一个名称) cloudformation-provider: an export name a cross-boundary link derives is already declared by another Outputs entry in the same stack: the link derives the export name <export-name> for provides key <provides-key> of component <component> in boundary <boundary> of Release <release>, and another Outputs entry of the same stack already declares that same export name — that declaration sits under the stack output <stack-output>, a name this provider assembles rather than one a Recipe wrote; each shadowing Outputs entry spells its export name exactly as the halt does, so searching your Recipes for that name reaches the entry — rename the export name the entry declares, or remove that entry’s Export block and let the link publish the export(cloudformation-provider:跨边界链接派生的导出名称已由同一栈中的另一个 Outputs 条目声明:该链接为某个 Release 中某个边界内某个组件的某个 provides 键派生出该导出名称,而同一栈的另一个 Outputs 条目已声明了相同的导出名称——该声明位于某个栈输出之下,该名称由此 provider 组装,而非由 Recipe 编写;每个与之冲突的 Outputs 条目拼写其导出名称的方式与该终止信息完全一致,因此在你的 Recipes 中搜索该名称即可找到该条目——请重命名该条目声明的导出名称,或删除该条目的 Export 块,让链接发布该导出)

**修复方法:**在你的 Recipes 中搜索终止信息给出的导出名称——声明它的 Outputs 条目拼写完全相同——然后要么重命名该导出名称使其不再匹配,要么删除该条目的 Export: 块,让跨栈连接自行发布该导出。如果该条目的存在就是为了导出边所消费的同一个值,删除它通常是正确的做法:provider 无论如何都会为该值发布一个 Export,因此编写的那个毫无作用。如果该条目是为另一个以你选定的名称导入该值的消费者导出该值,则保留编写的 Export: 并改为重命名它。

The output a cross-stack reference publishes on already carries an Export(跨栈引用发布所在的输出已带有 Export)

当一条 uses 边从一个边界跨到另一个边界时,provider 会把被消费值的 Export 发布在它为生产方组件和所提供的键组装的栈输出上——当 cloudformation Recipe 的 Outputs: 块在该键下写入条目时,到达的也是同一个输出。该输出上已有的 Export: 只有在其 Name: 恰好是 provider 派生的名称时才会保留:那是先前指向同一个值的跨栈引用已经发布的导出,因此所有消费者导入的都是同一个名称。那里的任何其他 Export: 都会终止构建,因为写入 provider 的导出会覆盖你编写的内容,而保留你的导出则会让所有消费者导入一个该引用从未发布的名称。

该输出上的 Export: 有四种形态会触发此终止:

  • Name: 是另一个字符串;
  • Name: 以 CloudFormation 内部函数写成,它在部署时才解析,因此 provider 无法读出其拼写;
  • Export: 块未给出任何名称;
  • Export: 写成了普通值而不是块。

你在任何其他 Outputs 条目上声明的导出名称会单独比较,见 An authored export name is one the build derives for a cross-stack reference(编写的导出名称与构建为跨栈引用派生的名称相同)。

发出的消息。条件给出失败的类型,provider 自己的句子说明发生了什么;外围报告还会指出正在连接的 uses 边:

two things a plugin produced occupy one name in its output(插件生成的两项内容在其输出中占用了同一个名称) cloudformation-provider: the stack output a cross-boundary link publishes its export on already carries an Export the link did not write: the link derives the export name <export-name> for provides key <provides-key> of component <component> in boundary <boundary> of Release <release>, and the stack output this provider assembles for that key and component <what-it-found>; remove that entry’s Export block and let the link publish the export every consumer imports(cloudformation-provider:跨边界链接发布其导出所在的栈输出已带有一个并非该链接写入的 Export:该链接为某个 Release 中某个边界内某个组件的某个 provides 键派生出该导出名称,而此 provider 为该键和组件组装的栈输出存在所发现的情况;请删除该条目的 Export 块,让链接发布所有消费者导入的导出)

<what-it-found> 为以下之一,顺序与上述形态一致:

already declares the export name <name>(已声明该导出名称) already declares an export name that is not a string — one given as an intrinsic, which resolves at deploy time, so this provider cannot read what it spells(已声明一个不是字符串的导出名称——以内部函数给出,在部署时才解析,因此此 provider 无法读出其拼写) already carries an Export block declaring no export name(已带有一个未声明导出名称的 Export 块) already carries an Export that is not a block, where CloudFormation expects one carrying a Name(已带有一个不是块的 Export,而 CloudFormation 期望的是一个带有 Name 的块)

**修复方法:**在终止信息所指组件的 Recipe 中,找到写在其所指提供键下的 Outputs 条目,删除该条目的 Export: 块——跨栈连接随后会发布所有消费者导入的导出。如果你还需要以自己的名称导出该值,供本次构建之外的消费者使用,请把该 Export: 写在另一个键下的 Outputs 条目上:那里的导出名称是受支持的,只要它不是构建派生的名称。

Chart-name mismatch on a merged helm-chart umbrella(合并的 helm-chart umbrella 上 chart 名称不一致)

两个或多个边界向同一个 helm-chart-provider 组装路径提供内容,但它们实际生效的 aggrega.ai/chart-name 注解(通过边界注解级联解析)不一致。一个 Helm umbrella chart 只有一个 chart 名称;渲染器无法在相互冲突的候选中选出一个。

**发出的消息。**每个参与的边界报告一条发现,各自带有该边界解析得到的值,因此不一致的名称每条发现一个,而不是作为一个打印出的集合。它们所归属的报告说明了它们的共同点:

merged dispatch groups whose boundaries disagree on the assembly name(边界在组装名称上不一致的合并分派组)

每条发现给出该边界解析得到的值、读取该值的注解、边界、provider,以及它们合并到的路径:

merged-path assembly has conflicting assembly-name annotation values(合并路径的组装存在相互冲突的组装名称注解值)("<value>", annotation "<annotation>", boundary "<boundary>", provider "<provider>", dispatch path "<path>")

**修复方法:**在每个参与的边界上声明一致的 aggrega.ai/chart-name 注解(当这些参与者共享一个父边界时,级联机制可避免重复——在父边界上声明一次即可),或者把这些边界拆分到不同的 directory: 路径,使每个边界获得自己的 umbrella chart。

FeatureRecipe template references a field outside its scope’s allowlist(FeatureRecipe 模板引用了其作用域允许列表之外的字段)

一个带有 executionScope: boundary 的 FeatureRecipe 在为边界只运行一次的模板中——其 locals:、provides:、valuesMapping:、artifacts:,或某个 pipeline 步骤的 with: 或 when:——引用了仅限单个组件的字段,例如 .context.instance_id、.context.inject 或 .context.uses——这些字段在边界作用域中没有有意义的值。反之亦然:组件作用域的 FeatureRecipe(默认)引用 .boundary.* 字段时,会在同一个验证器处失败。验证在解析时针对相应作用域的字段允许列表运行,早于任何渲染工作。边界作用域 FeatureRecipe 的 injectMapping 不在此检查:它在挂载所到达的每个组件的上下文中为该组件各运行一次,因此读取的是 .context.*,其中对 .boundary 的引用由上文“Template references a root the render context does not define(模板引用了渲染上下文未定义的根)”报告。

发出的消息:

FeatureRecipe template references a per-component-only field with executionScope: boundary ("<dotted-path>", written in "<field>", the render context defines "<the roots the boundary-scope context defines>")(executionScope 为 boundary 的 FeatureRecipe 模板引用了仅限每个组件的字段)

valuesMapping 读取 .context.instance_id 的边界作用域 FeatureRecipe 会输出:

[CATALOG_ERROR E0039] scope-probe-fr at .spec.valuesMapping
FeatureRecipe template references a per-component-only field with executionScope: boundary (".context.instance_id", written in "valuesMapping", the render context defines ".values, .infra, .locals, .provides, .features, .metadata, .steps, .source, .boundary")

**修复方法:**按照该作用域可用的字段重写模板,或更改 FeatureRecipe 的 executionScope。边界作用域的 FeatureRecipes 引用 .boundary.path、.boundary.boundary_name、.boundary.components、.boundary.*_uses_edges 集合、.boundary.labels、.boundary.annotations 和 .boundary.feature_attachments。Component 作用域的 FeatureRecipes 引用 .context.instance_id、.context.inject、.context.uses、.context.labels、.context.annotations。两种作用域共享 .values、.infra、.locals、.provides、.steps 和 .metadata。Release 参数在此接口上不是独立的支柱——它通过引用它的 values 或 infra 条目进入 FeatureRecipe 模板。

Self-inject value template references cross-node data(自注入值模板引用了跨节点数据)

组件级 inject: value: 模板从 .context.inject 或 .context.uses 读取数据。注入管道正是本轮处理所要构建的内容——组件自身的自注入值中的模板无法从中读取。

这是由该表面的 .context 决定的:它只携带 instance_id、labels 和 annotations,别无其他。因此,.context.inject 和 .context.uses 是该表面的上下文未定义的键,该引用会按上文“Template references a root the render context does not define(模板引用了渲染上下文未定义的根)”所述,在解析时、任何渲染开始之前停止构建。诊断信息会指出该模板所属的机制和交付键,并列出 .context 在此处定义的键——因此同一份报告既涵盖真正试图读取跨节点数据的情况,也涵盖诸如 {{ .context.nmae }} 这样的普通拼写错误;后者是更常见的错误,否则会被渲染为空。

发出的消息——引用层面的细节;外围报告还会指出节点、机制和交付键:

template references a root the render context does not define(模板引用了渲染上下文未定义的根)(模板 self-inject.<mechanism>[<key>] 引用了 .context.inject,而 .context 定义的是 .context.instance_id、.context.labels、.context.annotations)

报告的每一帧都属于开发者域,因为组件级 inject: 块是在 Aggregate 中编写的。

**修复方法:**将跨组件连接移到 uses[].inject 条目中——跨节点上下文在那里可用。让组件级自注入 value: 模板只使用组件自身的 values 和 infra、其 .context.instance_id / .context.labels / .context.annotations,以及 .metadata。

Missing template key — asymmetric policy(缺失模板键——非对称策略)

缺失键的处理方式取决于模板表面。当空渲染结果落在有界的位置——作者可以回读的 manifest 字段——时,缺失会被容忍,读取渲染为空。当空渲染结果反而会产生错误的结构或错误的判定时,该表面会拒绝该引用,而不是将其解析为空。

  • Aggregate 中的参数插值——即 Aggregate 自身文本中携带的 {{ .parameters.<key> }} 引用——是这些表面中最早的一个:它在 catalog 解析之前对原始文档运行,因此其策略作用于其他表面尚未见过的文本。对 Release 从未填充的参数的引用渲染为空,而作用于此类读取的 default 管道或 if 守卫的行为与作用于未填充参数时完全相同。模板迭代的引用会继续按空迭代,这正是遍历可选列表所需的行为——除非文本同时也打印它,此时会按下文“A template reads and iterates a path that holds nothing(模板读取并迭代一个不包含任何内容的路径)”所述中止。父级缺失的引用——在未填充 db 参数时的 .parameters.db.host——仍会中止,因为没有可以深入的内容,而补上父级会以一个悄然出错的产物换取中止。有一个边界值得作为边界而非策略来说明: 锚定在该表面未定义的根上的引用会被原样保留,而不是渲染为空,因此它会以模板引擎自身的占位文本 <no value> 留存到插值后的文档中。该表面上没有任何机制会因此中止,因此请将每个参数引用锚定在 .parameters 上,并将零散出现的 <no value> 视为拼写错误的根。
  • 路径模板(Release 边界的 directory: / subDirectory:)使用 missingkey=error 求值。对该表面未提供的变量的引用会在解析时中止——参见上文“Path-template references a variable outside the allowlist(路径模板引用了允许列表之外的变量)”——在 .manifest 下拼错的键也是如此,因为其键是已声明的。允许但在求值时未定义的引用,例如 Release 未提供的 .parameters 键,会产生明确的错误,而不是悄然将空字符串渲染进目录路径。
  • assertions(位于 Component、Feature、Recipe 或 FeatureRecipe 上)使用 missingkey=error 求值。对未定义键的引用会以一条“无此键”诊断中止,该诊断会指明实体、实例和断言。正是这种严格性使断言值得信赖:若谓词的引用渲染为空值,它会与空值比较并通过,因此一个拼写错误就会悄然废止该断言本应强制执行的规则。由于裸引用会在任何回退运行之前中止,在此表面上单纯的 default 无法提供可选字段回退——请用 hasKey 守卫该引用,或使用直接执行存在性检查的 optional 辅助函数。通过 index 读取该键也无法提供回退:index 会在映射中不存在该键时中止,并指明该键。
  • 值模板(Recipe 的 valuesMapping、locals: 和 provides: 条目、artifacts: 主体、Workload 主体、FeatureRecipe 的 injectMapping 和 pipeline.with,以及组件级自注入的 value: 模板)使用 missingkey=zero 求值,因此对未定义键的引用不会中止构建——该读取渲染为空,到达产物的也正是这个空值。在此表面上仍然会中止的,是穿过作者从未提供的容器向下访问的引用——在没有编写 tls 时的 .values.tls.ca——因为没有可以深入的内容。只有所有容器都存在的引用,其最后一个键才会渲染为空。上下文定义了但其中没有任何内容的顶层字段——不合成任何内容的 Recipe 上的 .workload、没有附件的组件上的 .features——在整体读取时同样渲染为空。无论如何书写,一个引用就是一个引用:.values.list、$.values.list 和 (.values).list 指的是同一个键,因此以一种写法遍历它就等于以所有写法遍历它,而从加括号的 pillar 上读取的键,其渲染或中止方式与直接写法完全相同。模板遍历的键在未设置时会继续按空迭代,而模板既打印又遍历的键在未设置时会中止——参见下文“A template reads and iterates a path that holds nothing(模板读取并迭代一个不包含任何内容的路径)”。守卫按预期工作:{{ .values.optional_field | default "fallback" }} 确实会提供回退值,因为未设置的值对 default 而言算作空,对 if 而言算作假。需要区分缺失与零值——区分“键不存在”与“键存在但为空”——的作者,可以使用 templates/sprig-functions.md 中记录的 optional 辅助函数,并在每个模板中只用一种方式读取某个键:同一模板也以 .values.<key> 形式读取的键会被视为存在,因此 optional 会报告其空值而不是回退值。此策略不涵盖通过 index 进行的读取:用映射中不存在的键对映射进行索引时,这里与在每个表面上一样,都会中止并指明该键——参见下文“A template indexes a map with a key the map does not hold(模板使用映射中不存在的键对映射进行索引)”。
  • source: 坐标——Recipe 或 FeatureRecipe 上结构化 source: 块中的模板化字段(version、ref、chart、module_subdir)——使用 missingkey=error 求值。对无人提供的键的引用会中止并指明该 source 字段,而不是解析为空:空的 version 或 ref 会锁定一个与作者所指定的不同的产物,而该锁定正是之后每次构建所复现的内容。此表面也是可用函数集有所不同之处,并且块自身作者顺序所拒绝的 locals: 引用也会在任何求值之前于此中止——见下文。
  • 类型化参数契约在参数契约层、插值运行之前捕获缺少必需参数和违反契约的情况——参见上文“Parameter type mismatch / contract violation(参数类型不匹配/违反契约)”。

值模板、路径模板和断言的辅助函数集相同:Sprig 的函数加上 Aggrega 自身的函数(optional 和 capitalizedWords)。Sprig 的 fail 也在其中,因此值模板可以用自己的消息停止构建,如下文“A value template failed while it ran(值模板在运行时失败)”所述;断言则是专为此而写的表面,因为中止构建正是它的全部目的。这三者之间的差异在于缺失键策略——optional 在路径模板中也可用,它可以从 .parameters 中读取键,而不会先触发严格策略。解析 source: 坐标的差异在于函数集本身,下文有其专门的小节。Aggregate 中的参数插值仅提供 Sprig 的函数,因此两个 Aggrega 辅助函数在那里都不可用。有一个函数在所有这些表面上(包括坐标和插值)的读取方式都相同:index,当其读取的映射中不存在该键时,它会中止并指明该键。

路径模板缺失时打印的消息引用于记录该情况的条目下,即上文“Path-template references a variable outside the allowlist(路径模板引用了允许列表之外的变量)”,因此只写一次,不在此重复。

**修复方法:**对于路径模板缺失,将字段名更正为 path-template-variables.md 中记录的允许列表中的名称。对于断言缺失,更正该引用——大多数报告是拼错的键——或者在该字段确实可选时,用 hasKey 守卫它或使用 optional 辅助函数;将裸引用包裹在 default 中无法消除中止,因为引用在回退运行之前就已解析,通过 index 读取也不行,因为 index 会在映射中不存在该键时中止。对于不希望空渲染的值模板缺失,请使用 optional 辅助函数,或者将缺失的键作为 Aggregate 上带有 Release 值的类型化 parameters.* 声明、作为通过 uses[].inject 连接的上游 Component 的 provides: 条目,或作为同一实体上的 locals: 条目来提供。

Resolving a source: coordinate registers a narrower function set(解析 source: 坐标时注册的函数集更窄)

结构化的 source: 块会被解析,以便固定它所指定的制品,而这次解析注册的是 Aggrega 自己的辅助函数,别无其他:optional 和 capitalizedWords 可用,index 在映射不包含所请求的键时会停止,与 Recipe 渲染时完全一致;Sprig 的函数则不可用。在 Recipe 或 FeatureRecipe 编写模板的各个表面中,只有这一个表面的函数集不同,因此在同一 Recipe 其他位置能正确渲染的表达式,在这里可能被拒绝。函数集更窄是有意为之:固定什么由作者提供的 values 和 infra 决定,而 Sprig 的函数中有些会读取时钟、环境、随机源或网络。

在 source: 字段中,或在该字段读取的 locals: 条目中调用 Sprig 函数,会在解析时停止。该诊断以 E0111 开头,并指出该条目、读取它的 source: 字段、无法解析的函数,以及此表面确实注册的辅助函数:

resolve: parse template at <name>:<version>.spec.locals.<key>, read by <name>:<version>.spec.source.<field>: resolve: source-template parse error (cause: template: <name>:<version>.spec.locals.<key>:1: function "<function>" not defined); a source field, and every locals entry it reads, is evaluated when the source is resolved with Aggrega’s own helpers only (optional, capitalizedWords and index), not the Sprig functions a render adds; write the value without that function, or move the value into a locals entry no source field reads

source: 字段自身调用该函数时,以相同方式报告,只指出该字段。

作用范围是坐标读取的条目。 解析坐标时,会对 source: 字段读取的每个 locals: 条目求值,并依次对这些条目读取的每个条目求值,此外不求值其他条目。没有 source: 字段触及的条目,在解析源时不会被求值、解析或检查,因此渲染所需的 local(例如用 Sprig 函数做算术,或依据 .context.instance_id 命名资源)对固定制品没有影响;它会在 Recipe 渲染时求值,其中的任何错误也在那时报告。字段读取哪些条目由其文本决定,因此以不指明具体条目的方式读取 .locals 的字段(如 {{ index .locals "version" }}、将整个块传给 optional 或绑定到变量)会使所有条目都被求值,而通过这种方式触及的条目的诊断会说明这一点:它不写 read by <field>,而是写 evaluated for <field>, which reads the locals block as a whole rather than by entry, so every entry is evaluated。

有两种形态不在此表面之内,了解 Recipe 属于哪一种,就能解释为什么同一表达式在一个 Recipe 中被接受而在另一个中被拒绝:

  • 写成普通字符串的 source:(URI 或本地路径,而非映射)按原样使用,因此没有需要求值的字段,locals: 块在此处完全不会被解析。
  • 未声明 source: 的实体不解析任何坐标,因此其 locals: 块只在该实体自身渲染时解析,此时适用完整的函数集。

对于坐标读取的每个条目,引用顺序契约在这里同样适用。 解析坐标时,在其求值的每个条目中拒绝的引用与渲染时拒绝的相同:读取该块中在其下方声明的同级条目的条目,以及读取该块未声明的键的任何模板。两者都报告上文“locals: entry references a sibling defined later in the same block(locals: 条目引用了同一块中稍后定义的同级条目)”和“locals: key does not exist(locals: 键不存在)”下记录的条件——无论哪一种解析先遇到,条件相同,补救方法也相同——并且报告会指明该条目为之求值的 source: 字段。对于没有任何 source: 字段读取的条目,其中的错误会在 Recipe 渲染时以同一条件被拒绝。

此表面确实会跳过的,是坐标确实无法解析的条目:即读取仅在渲染制品时才存在的数据的条目,.context.instance_id 正是这种情况。此类条目会被跳过,因此坐标仅在未执行的分支上触及该条目的 Recipe 仍会被固定。如果坐标本身需要该条目,解析就会停止并指出 source: 字段(即上文为此表面描述的缺失键报告,以 E0110 开头),并在无法读取的键旁引述该条目在此处为何没有值:

resolve: evaluate template at <name>:<version>.spec.source.<field>: resolve: source-template evaluation failure at lock time (cause: template: … map has no entry for key "<key>"); it reads <name>:<version>.spec.locals.<key>, which could not be evaluated here (cause: template: … map has no entry for key "context")

source: 字段及其读取的 locals: 条目都不得读取 .provides。 locals: 块为 provides: 块提供输入,反之则不行,因此此表面上读取 .provides 的模板会作为反向引用被拒绝,而不会解析为空。这种拒绝并非之后某个阶段会补足的锁定时缺失(任何顺序都无法使该引用有效),因此无论坐标在何处解析,报告方式都相同。该诊断以 E0112 开头;它指出该字段,或该条目及读取它的字段,说明引用的问题所在,并给出表达式可以改为读取的表面:

source-version template at <name>:<version>.spec.source.<field> references .provides, which is an invalid reverse reference (locals feed provides, never the reverse) — refactor to read only .values and .infra (and .locals over the same): resolve: source-template references .provides (invalid reverse reference)

停止出现的时机: 在填充或刷新 lockfile 时,即 aggrega pull,或填充它的构建(--auto-pull、--upgrade 或工作区的 auto_pull 设置)。每个失败都报告为一条诊断,以出错内容的代码开头:无法解析的模板为 E0111,.provides 引用为 E0112,已解析但无法求值的模板为 E0110;在终端中和连接到 aggrega serve 的编辑器中都是如此。source: 字段上的缺失键与不可用函数不同,在执行时而非解析时报告,并指出该字段及其无法读取的键。

如何修复: optional 在此表面以及每个值模板、路径模板和断言上都已注册,因此是可移植的选择:用 {{ optional .values "chart_version" "25.0.8" }} 代替 {{ default "25.0.8" .values.chart_version }}。替换前请了解语义差异:optional 在键不存在时生效,而 default 在值为空时生效,因此编写为空字符串或零的键,在 optional 下保留其编写的值,在 default 下则被替换。如果表达式确实需要 Sprig 函数(例如重塑字符串,而非提供回退值),请将其置于坐标读取的范围之外:放在没有 source: 字段读取的 locals: 条目中,或放在使用它的表面上(valuesMapping、Workload 主体、artifacts: 条目)。

A template indexes a map with a key the map does not hold(模板使用映射中不存在的键索引该映射)

模板通过 index 读取映射——{{ index .values "replicas" }},或使用模板计算出的键名的 {{ index .context.inject.env $apiKeyVar }}——而映射中没有所请求的键。index 会在此处停止并给出该键名,这适用于所有求值模板的位置:值模板、locals: 与 provides: 条目、路径模板、断言、结构化的 source: 坐标、Aggregate 中的参数插值及其参数的 validate: 谓词,以及 schema 的 x-aggrega-when: 与 x-aggrega-validate: 谓词。

**这只是 index 自身的特性,任何表面的缺失键策略都不会改变它。**在开放 pillar 下用点号读取未设置的键,在值模板上仍然渲染为空,如上文“Missing template key — asymmetric policy(缺失模板键——非对称策略)”所述;测试作者是否提供了此类键的模板也不受影响。会停止的是向 index 请求映射中不存在的键。index 是模板访问名称由其计算得出的键的方式——例如按使用方 Recipe 选定的变量名读取凭据——如果没有这次停止,该读取会把模板引擎的占位文本 <no value> 写入产物,而构建却成功了:服务器以这段文本作为其密钥启动。index 给出的其他所有结果都是模板引擎自身的行为:列表或字符串中的位置、越界位置、映射中存在的键——包括值为 null 的键,它会输出 <no value>。

发出的消息,作为报告的最后一行——其上方的各层给出节点和模板所在的字段;对于 Recipe 或 FeatureRecipe 的值模板,报告头部带有本条件的代码:

template: <template>:<line>:<column>: executing "<template>" at <index <map> <key>>: error calling index: template indexes a map with a key the map does not hold (key "<key>"). read a key that may be absent through a function that tests for it first, such as optional, get or hasKey(模板使用映射中不存在的键索引该映射;请通过先检测键是否存在的函数读取可能缺失的键,例如 optional、get 或 hasKey)

在以自身条件报告模板失败的表面上——provides: 条目(“A provides: template could not be evaluated”(无法对 provides: 模板求值))、参数插值(“A {{ .parameters.* }} reference cannot be interpolated”(无法插值 .parameters.* 引用))、schema 谓词(“An x-aggrega-when: or x-aggrega-validate: predicate cannot be evaluated”(无法对 x-aggrega-when: 或 x-aggrega-validate: 谓词求值))、source: 坐标(“Resolving a source: coordinate registers a narrower function set”(解析 source: 坐标时注册的函数集更窄))——报告头部带有该条件的代码,而上面那一行就是它所携带的原因,其中包含该键。

**如何修复:**判断该键是否可以合理地缺失。

  • **可以缺失。**通过先检测键的函数读取它:{{ optional .values "replicas" 1 }} 在键缺失时返回回退值,存在时返回其值(无论是什么);Sprig 的 get 对缺失的键返回空字符串;hasKey 只检测而不读取。除参数插值以及参数或 schema 的谓词(它们提供 Sprig 的 get 和 hasKey)外,optional 在所有位置均已注册;source: 坐标注册了 optional,但不注册 Sprig。
  • **不能缺失。**提供该键。消息中给出的键就是模板请求的键,常见原因包括:键以另一个名称发布——凭据的 key 不是 Recipe 读取的变量名——模板或编写的值中键名拼写错误,以及本应提供该键的连接未接线。

A template reads and iterates a path that holds nothing(模板读取并迭代一个不包含任何内容的路径)

模板既按原样打印某个路径,又对同一路径进行迭代——比如在同一个 valuesMapping 中同时写 "user": "{{ .values.user }}" 和 "users": "{{ range .values.user }}…{{ end }}"——而数据在该处不包含任何内容:该键未设置、其值为 null,或者它是上下文定义了但没有为其提供任何内容的顶层字段,例如在不合成任何工作负载的 Recipe 上的 .workload。构建会在模板运行之前中止并指出该路径,凡是将未设置的值渲染为空的地方都是如此:上文“Missing template key — asymmetric policy(缺失模板键——非对称策略)”列出的值模板,以及 Aggregate 中的参数插值。

每种读取单独来看都有答案。被打印的未设置值渲染为空,被迭代的未设置值不产生任何迭代。以两种方式读取的路径则两种答案都无法成立:将其渲染为空会使 range 在文本上失败,而保持未设置则会在构建成功的同时把模板引擎的占位文本 <no value> 打印到制品中。因此两种答案都不给出,构建改为停止。

什么算作打印该路径,范围很窄,界线划在模板必定会打印它的地方:

  • 会被打印:当某个动作仅由该路径构成、别无其他时——{{ .values.user }}、{{ $.values.user }}、{{ (.values).user }},或绑定到该路径的变量,即 {{ $u := .values.user }} 之后的 {{ $u }}——且位于模板每次运行都会到达的位置。
  • 不会被打印:当读取位于 if、with 或 range 主体内,或位于 else 分支中时,因为该读取是否运行取决于某个条件,而该条件可能正是防止它遇到空内容的那个测试——因此在 range .values.user 旁边的 {{ if .values.user }}{{ .values.user }}{{ end }} 会像以往一样渲染。当它是守卫自身的测试、变量的赋值,或函数的参数时——{{ .values.user | quote }}、{{ toYaml .values.user }}——也不算打印,因为其输出是函数的结果而不是占位符。

在确实会运行的主体中打印不包含任何内容的路径,仍会写出 <no value>,这超出了本检查的范围。同一路径的一种写法与其他任何写法都是同一路径,因此以一种写法进行的打印与以另一种写法进行的 range 会被放在一起判断,消息引用模板最先写出的那种写法。包含值的路径会像以往一样打印和迭代,而父级不包含任何内容的路径则交由穿过空内容向下取值时本就会引发的中止来处理。

发出的消息,作为报告的最后一行——其上方的帧指出节点和模板,消息头带有本条件的代码:

template reads a path as a value and iterates it, and the data holds nothing at that path (path <path>). supply a value at the path, guard the printed read with an if or with over the path, or read it one way only(模板将某个路径作为值读取并对其进行迭代,而数据在该路径上不包含任何内容。请在该路径上提供一个值,用针对该路径的 if 或 with 守护被打印的读取,或只以一种方式读取它)

Aggregate 中的参数插值同样以本条件的代码报告同一行。provides: 条目在“A provides: template could not be evaluated(该模板无法求值)”下报告模板失败,因此在那里消息头带有该条件的代码,而上面这一行是它所带的原因,其中包含路径。

如何修复: 判断模板指的是两种读取中的哪一种。

  • 该路径必须存在。 提供它——在 Aggregate 的 values:、Release 的 infra: 或 Release 填写的参数中——或在管辖它的 schema 中将其声明为必填,使其缺失在编写处即被报告。
  • 该路径可以缺失。 守护被打印的读取:{{ with .values.user }}{{ . }}{{ end }} 或 {{ if .values.user }}{{ .values.user }}{{ end }} 在其未设置时不打印任何内容,而旁边的 range 继续按空内容迭代。
  • 一种读取就够了。 只以一种方式读取该路径——一个同时写出所需内容的 range,或通过 toYaml 或 join 这类自身就能为未设置值给出结果的函数进行打印。

A value template failed while it ran(值模板在运行时失败)

Recipe 或 FeatureRecipe 的值模板——上文“Missing template key — asymmetric policy(缺失模板键——非对称策略)”所列的模板之一,其中包括 Workload 主体、artifacts: 主体或 locals: 条目——已完成解析并开始运行,却在生成文本之前停止。使其停止的是模板引擎自身给出的原因,中止信息会将其附在下方:引用穿过了未提供任何内容的容器,例如在未编写 tls 的情况下引用 {{ .values.tls.ca }};比较两种不同类型的值,例如 {{ if eq .context.instance_id 1 }},它将文本与数字比较,并以 cannot compare text with a number 中止;或者调用 Sprig 的 fail,值模板可以借此用自己的消息拒绝某个输入。

这些模板上有四种失败会改为在各自的条件下报告。provides: 条目在下文“A provides: template could not be evaluated(该模板无法求值)”下报告,其消息中包含本句以及引擎给出的原因。对映射中不存在的键进行 index 读取,在上文“A template indexes a map with a key the map does not hold(模板以映射中不存在的键索引映射)”下报告。打印并迭代同一个不包含任何内容的路径的模板,会在运行之前被拒绝,在上文“A template reads and iterates a path that holds nothing(模板读取并迭代一个不包含任何内容的路径)”下报告。而无法解析的模板在运行之前就会停止,因此不属于本条件。

输出的消息——其上方的帧指明组件实例和模板,例如 recipe "<recipe>" workload template 或 Recipe "<recipe>" locals["<key>"],模板引擎自身的那一行跟在其下方:

a value template failed while it ran(值模板在运行时失败)

引擎的那一行为 template: <template>:<line>:<column>: executing "<template>" at <<expression>>: <reason>——对于调用 fail 的情况,则为 error calling fail: <the message the template wrote>。构建以 CATALOG_ERROR 标签报告该中止,因为模板由 Recipe 或 FeatureRecipe 的作者编写。aggrega pull 在渲染 Release 以发现其读取的外部输入时也会遇到同样的失败:它会报告该失败,仍会写入 lockfile 的依赖固定项,并说明外部输入的固定项可能不完整;构建则会因此中止。

修复方法: 阅读报告末尾引擎给出的原因——它会指明模板、行号和列号,以及停止时所在的表达式。对于未提供任何内容的容器,请提供它,或者对读取加以保护,使其永远不会深入不存在的内容:{{ with .values.tls }}{{ .ca }}{{ end }},或使用 optional 辅助函数。对于比较了两种类型的情况,请同类相比——数字与不加引号书写的数字比较,文本与加引号书写的文本比较——或者用 toString 将一侧转换为文本。对于调用 fail 的情况,消息出自模板作者,它说明了该 Recipe 需要什么:提供它,或者将组件映射到接受你所写内容的 Recipe。

A governance plugin rejected the build(治理插件拒绝了构建)

运维人员可以以裁决角色挂接治理插件,作用于编译器构建的图或其渲染的产物。此类插件只读取并返回裁决。宿主没有任何途径应用从插件返回的更改,因此裁决角色可以拒绝构建,但不能将构建改写为合规——拒绝就是它能做的全部,要改什么留给阅读者决定。

只有 halt 裁决会停止构建。warn 和 info 裁决会被报告,构建继续进行。插件返回的每个 halt 裁决都会按插件发出的顺序报告,因此一次运行即可获知全部裁决。

构建打印的消息是插件自己的消息,按返回时的原样呈现,仅以返回它的插件作为外层说明——因此消息的具体程度和可操作性由插件而非编译器决定。裁决携带的任何可选细节随后在方括号中列出,每项都带名称:代码、规则标识符、分类、来源引用、位置、建议。它被记录的条件是 policy violation,即诊断头部的短代码所对应的条件。

该拒绝归属于治理挂接而非你的某个文档,因此不带文件位置:没有哪个键导致了它,解决办法要么是满足该策略,要么是重新考虑该挂接。

发出的消息:

policy plugin "<plugin>" rejected the build: <the plugin's own message> [code=<code>; rule_id=<rule>; classification=<class>; source_ref=<reference>; location=<where>; suggest=<suggestion>](策略插件拒绝了构建)

方括号部分仅在裁决携带细节时出现,其中每一项仅在插件设置了它时出现。

**如何修复:**阅读插件的消息,以及插件提供的建议(如有)。如果判定正确,修改它所反对的内容。如果该策略不应适用于此 Release,那就是关于挂接的问题:治理挂接在工作区配置的 plugins.governance 下配置,哪个插件以哪个角色运行由运维人员决定,文档无法覆盖。

A governance attachment’s settings do not match the plugin’s declared schema(治理挂接的设置与插件声明的 schema 不匹配)

治理插件可以为其挂接传给它的设置声明 schema。写在挂接 with.settings 下的设置会在插件被调度之前按该 schema 检查,因此配置错误的挂接会作为配置错误本身报告,而不是以结构不正确的输入到达插件,再以插件对它的任意处理结果返回。

这一顺序正是该检查的意义所在。它也使本条件与拒绝明确区分:插件尚未运行,没有得出裁决,构建的任何方面都没有被评判。未声明设置 schema 的插件接受任何设置,因此针对此类插件的挂接不会遇到此条件。

**该检查覆盖每一种治理角色。**在 ir-verdict、render-verdict、label-transform 或 annotation-transform 编写的挂接,其设置都会在调度插件之前按 schema 检查——with.settings 在每个角色上都是同一个编写键,每个角色都会先按 schema 读取它。转换角色在构建应用它的地方运行,对于先执行拉取的构建,就是在该拉取期间,因此那里的消息以调度它的步骤开头,例如 auto-pull: label-transform:。

发出的消息——先是挂接编写所在的角色及其指定的插件,然后是固定语句,最后是 schema 检查的结果:

ir-verdict: plugin "<the attachment's uri>": with.settings does not satisfy the plugin’s declared settings schema: <what the schema check found>: policy attachment settings do not satisfy the plugin’s declared settings schema(策略挂接的设置不满足插件声明的设置 schema)

对于在 render-verdict 角色编写的挂接,开头一句为该角色名。schema 检查的结果是 schema 校验器自己的报告,会超过一行。

**如何修复:**在 plugins.governance 中修正该挂接 with.settings 下的设置。消息中间的细节给出出错的键以及 schema 在该处期望的内容;插件自身的参考文档说明了它声明的设置。

A pipeline step failed(流水线步骤失败)

FeatureRecipe 可以声明一条流水线:一系列步骤,每个步骤在节点已发出的文档上调用一个插件导出,使 Feature 能够塑造该组件自身 Recipe 生成的输出。步骤因任何原因失败时都在此条件下报告,唯一的例外是补丁指向文档集合中不存在的内容,那种情况在下文有单独的报告。

失败的对象以步骤的 id 和索引命名,其后的子句说明是哪一部分出了问题:渲染步骤的 with 输入、调用本身、宿主无法读取的输出、插件返回的错误、插件发出的错误级别诊断、补丁引擎拒绝的补丁,或者命名了遍历中不存在的作用域的补丁。

失败的步骤会被整体回滚。 文档恢复到该步骤运行之前的状态,步骤自身的输出也随之丢弃,因此后续步骤的 when 或 with 无法读取到部分结果。声明了 optional: true 的步骤随后以警告形式报告,遍历继续进行;非可选的步骤则会停止构建。optional: 不容忍的是违反已声明的契约——见下一条。

输出的消息:

pipeline step failed: step "<id>" (index <n>) with: <what the render could not do> pipeline step failed: step "<id>" (index <n>) invoke: <what the call could not do> pipeline step failed: step "<id>" (index <n>) error diagnostic: <the plugin's message> pipeline step failed: scope "<scope>" key "<key>": <what the patch engine refused> pipeline step failed: unknown patch scope "<scope>"

修复方法: 先看步骤 id,再看索引之后的子句——它说明应检查步骤的哪一半。with 失败是步骤自身 with: 块中的模板问题,需要你来修复。错误诊断是插件针对你的输入给出的原话。被拒绝的补丁和未知作用域是插件输出与节点所发出内容之间的问题,归插件作者处理。如果某个步骤确实允许失败——是可选的增强而非必需的转换——就将其声明为 optional: true,但要记住,这容忍的是失败,而不是被破坏的契约。

A pipeline step’s typed input or output does not satisfy its declared contract(流水线步骤的类型化输入或输出不满足其声明的契约)

插件导出可以为其接收的输入和返回的输出声明 schema。两者都会被检查:调用前检查渲染后的 with 值,调用后检查返回的输出。严重级别未在共享契约中声明的诊断,也以同样的依据被拒绝。

即使步骤声明了 optional: true,这也会停止构建,而这一区别正是该条件独立于步骤失败的全部原因。可选容忍的是无法完成工作的步骤——调用失败、插件提出异议。它不容忍宿主无法路由的输出,也不容忍从未符合导出所声明形状的输入:已声明的契约是一种承诺,如果构建悄悄跳过契约被破坏的步骤,就等于在一个什么都没做的 Feature 之上报告成功。

输出的消息:

pipeline step "<id>" with input does not satisfy the declared input contract: <what the schema check found>: pipeline step typed-I/O contract violation pipeline step "<id>" returned outputs that do not satisfy the declared output contract: <what the schema check found>: pipeline step typed-I/O contract violation

对于契约未声明的诊断严重级别,消息出现在步骤失败的框架内:

pipeline step failed: step "<id>" (index <n>): <the severity the host could not route>: pipeline step typed-I/O contract violation

如果步骤的 with 模板读取了声明为敏感的值,输入违规不会列出任何值。 schema 检查的发现会被替换为每个失败位置及拒绝它的关键字,最后附上一条说明原因的提示——at '/origin': pattern (the value is withheld because the template that rendered this input reads a value declared sensitive)——因此需要修正的字段仍会被指出。参见 vocabulary/compact-form-authoring.md “What a refusal says about a declared value”。

修复方法: 对于输入违规,按照其导出声明的 schema 修正步骤的 with: 块——详细信息会指出字段及期望的内容。输出违规和未声明的严重级别需要由插件修复;出错的不是步骤的声明,因此将其标记为可选也无法消除其中任何一种。

A pipeline patch addresses a document the set does not hold, or one with no tree to address(流水线补丁指向集合中不存在的文档,或指向没有可寻址树结构的文档)

流水线步骤通过作用域和键来定位文档,有两种形式的地址会被拒绝。

集合中不存在该文档。 步骤所修补的作用域与键的组合不在交给它的文档之中。这样不会编辑任何内容,因此遍历不会对空对象应用补丁并报告成功,而是停止:

pipeline patch targets a document not present in the set: scope "<scope>" key "<key>"

它没有可寻址的树结构。 有些单元没有补丁可以指向的结构——二进制内容、自由文本、provider 无法安全遍历的区域。这类单元仍会交给步骤,并标注其媒体类型和字节,以便被选中并整体发出;它不能被修补,因为没有任何东西可供路径解析。针对此类单元的补丁会停止构建,而不是被悄悄跳过:

pipeline patch targets an opaque (non-structured) unit: scope "<scope>" key "<key>"

什么算作结构化,取决于 provider 自己对该单元的解读,而非固定的判断标准,因此同一内容在一个 provider 下可寻址,在另一个 provider 下可能是不透明的。

两者都是遍历自身的拒绝,构建会针对其流水线生成该补丁的节点报告它们,因此上述消息出现在一条指出该节点的停止信息之下。该停止信息是这两种寻址错误导致构建停止的形式,记录在下文“A pipeline step addresses documents the node does not have(流水线步骤指向节点不具有的文档)”中——该条目还涵盖步骤可能无法定位任何内容的第三种地址:在不对应任何宿主组件的位置请求宿主组件的文档。

修复方法: 两者都归插件作者而非你处理。步骤会收到它所运行的文档集合,并能读取其中有哪些键,因此目标不存在意味着步骤指向了该节点未发出的文档——请修补存在的文档,或者先发出你想要的文档,再在后续步骤中修补它。对于不透明单元,用整体发出该单元来替代补丁:不透明内容只能被替换,而不能被编辑。

A patch’s test operation did not match the document(补丁的 test 操作与文档不匹配)

补丁可以携带一个 test 操作,用于在应用其后的操作之前断言某个路径上的内容。断言不成立时,引擎会拒绝整个补丁,正是这一点使条件补丁真正有条件,而不是乐观地执行:先测试再编辑的插件,表明它不会修改自己无法识别的文档。

有两种情形会以此报告。一种是该路径上根本没有任何值,消息会说明这一点。另一种是存在一个值,但不是所断言的值,此时只报告拒绝本身——既不引用断言的值,也不引用实际找到的值。

输出的消息:

jsonpatch: test operation failed: no value at path(jsonpatch:test 操作失败:路径上没有值) jsonpatch: test operation failed(jsonpatch:test 操作失败)

如果补丁来自某个流水线步骤的输出,该拒绝会出现在该步骤的失败之下,并指明该步骤。如果补丁来自标签转换插件,则会出现在标签补丁的拒绝之下。

**如何修复:**问题出在插件,而不是你的文档。测试所期望的值在文档中不存在,通常意味着插件正运行在它并非为之编写的结构上——另一个 provider 的输出,或者已被同一流水线中较早步骤修改过的文档。如果补丁由你负责修正,可以将测试放宽为文档实际携带的内容,或者让步骤的 when 条件跳过该情况,而不是在补丁内部对其进行测试。

A workload: form and the fields beside it do not agree(workload: 的 form 与其旁边的字段不一致)

workload: 声明一个 form:——即所运行事物的形态,用每个目标都能理解的术语表述,而不是任何单一目标的词汇。有些字段只在某一种 form 上才有意义,而声明了 form 却缺少其所需字段,就没有任何一致的内容可渲染。两个方向都会检查,且在任何目标翻译该 workload 之前进行,因此这种不一致只针对你所写的内容报告一次,而不是每个目标以各自的说法各报告一次。

共强制检查 5 种配对,每种都会报告自己的一句话,指出两方以及应当如何书写:

workload declares a persistentTemplate volume but is not form: stateful; declare form: stateful(workload 声明了 persistentTemplate 卷,但不是 form: stateful;请声明 form: stateful) workload is form: reference but declares no endpoint; set endpoint to the external host or URL the reference points at(workload 为 form: reference,但未声明 endpoint;请将 endpoint 设为该引用指向的外部主机或 URL) workload declares an endpoint but is not form: reference; declare form: reference or remove the endpoint(workload 声明了 endpoint,但不是 form: reference;请声明 form: reference 或移除 endpoint) workload is form: scheduled but declares no schedule; set schedule to a 5-field cron expression or an @-macro (e.g. @daily)(workload 为 form: scheduled,但未声明 schedule;请将 schedule 设为 5 字段 cron 表达式或 @ 宏(例如 @daily)) workload declares a schedule but is not form: scheduled; declare form: scheduled or remove the schedule(workload 声明了 schedule,但不是 form: scheduled;请声明 form: scheduled 或移除 schedule)

每条报告都定位到正在读取其 workload 的组件实例,并作为翻译错误报告,因为这种不一致存在于同一个编写块的两个字段之间。

它们所记录的条件,也就是其短代码所解析到的内容,分别是 persistentTemplate volume requires form: stateful、form: reference requires an endpoint、endpoint requires form: reference、form: scheduled requires a schedule 和 schedule requires form: scheduled。

**有一种配对只单向检查。**没有逐副本声明模板的 form: stateful workload 是普通情况,不会引发任何报告——规则是声明模板需要只有该 form 才提供的稳定逐副本标识,而不是该 form 需要声明模板。另外两种配对则双向检查,因为 endpoint 和 schedule 各自都只在唯一一种 form 上有意义。

两个 endpoint 配对也写在 Workload schema 中,因此违反其中任一配对的 workload 会在 schema 阶段以 E0214 被拒绝,早于上述对应语句。在 reference 以外的任何形式上的 endpoint:——包括省略的 form:,因为它被视为 stateless——会被拒绝为

workload validation failed (Workload in Recipe <name>:<version>, at <path>, schema stage): .endpoint: value matches a shape that is not allowed here(workload 验证失败,schema 阶段:endpoint 的值匹配了此处不允许的形状)

而没有 endpoint: 的 form: reference 则改为以 .endpoint: missing required property: endpoint 结尾。补救方法即该配对语句所给出的方法。

**如何修复:**每句话都指出了两个字段,并给出了两种解决方式。添加该 form 所需的字段,或将 form 改为该字段所属的 form,或者在字段是编辑后遗留下来时将其移除——删除了 schedule: 的值却保留了键,是最常引发此问题的情形。

A workload schedule: is not an expression the check accepts(workload 的 schedule: 不是检查所接受的表达式)

form: scheduled 的 workload 携带一个 schedule:,说明其运行时间,该值会在任何目标读取之前进行结构检查。接受两种写法:5 个宏 @hourly、@daily、@weekly、@monthly 和 @yearly 之一,或者一个 5 字段 crontab 表达式,其字段只使用数字和字符 *、,、- 和 /。

**检查会读取什么、不会读取什么。**它计算字段数并查看其中的字符。它不求值范围、步长运算或星期名称,因此数字超出范围的 5 字段表达式会在此处通过,由目标负责拒绝。带有前导秒字段的 6 字段表达式会被拒绝:此处只接受 5 个字段,需要秒的目标会以其他方式获取。

发出的消息:

workload schedule is not a valid cron expression; use a 5-field crontab expression (e.g. “0 0 * * *”) or one of @hourly, @daily, @weekly, @monthly, @yearly(workload 的 schedule 不是有效的 cron 表达式;请使用 5 字段 crontab 表达式(例如 “0 0 * * *”)或 @hourly、@daily、@weekly、@monthly、@yearly 之一)

它所记录的条件是 schedule is not a valid cron expression,也就是其短代码所解析到的内容。

**如何修复:**先数字段——有 4 个或 6 个字段的 schedule 是最常见的原因,而某个字段内多余的空格会把它拆成两个。将星期或月份名称替换为对应的数字,如果某个宏正好表达了你的意思,就使用该宏。

A workload suspend: is set on a form other than scheduled(workload 的暂停字段设置在定时以外的形式上)

suspend: true 会暂停 form: scheduled workload 的周期性调度:定时资源仍会被渲染,但在恢复之前不会按其调度启动任何运行。其他形式都不带调度,因此在其他任何形式上,该字段没有可暂停的对象,构建会中止,而不是渲染一个悄然丢弃该字段的 workload。该检查与其他形式配对检查一同运行,早于任何目标转换该 workload,且省略的 form: 在此同样被视为 stateless。

发出的消息:

workload declares suspend but is not form: scheduled; declare form: scheduled with a schedule or remove suspend(workload 声明了 suspend,但不是 form: scheduled;请声明带有调度的 form: scheduled,或移除 suspend)

它定位在正在读取其 workload 的组件实例处,并作为转换错误报告。它所记录的条件为 suspend requires form: scheduled,这也是其短代码所解析到的内容。

**该规则只单向生效,且只针对 true。**没有 suspend: 的 form: scheduled workload 是普通情况,会按其调度运行;而 suspend: false(默认值)在任何形式上都不会引发任何报告。

修复方法: 如果该 workload 本意是只在有人启动时运行,就将其设为带有 schedule: 的 form: scheduled,并保留 suspend: true;否则保留所写的形式并移除 suspend:,其他形式都不会读取它。

库 $import: 未以裸名称形式书写

Recipe 和 FeatureRecipe 上有三个字段可以从库中获取其主体,而不是就地书写:artifacts.<name>: 条目、valuesMapping: 和 workload:。每个字段都以库的裸名称书写 $import:,然后是 #,再然后是该字段所读取的表面上的条目路径——分别为 #/artifacts/、#/mappings/ 和 #/workloads/。不符合该形式的值不指向构建能够解析的任何内容,会在解析该字段时被拒绝。

这三个字段被有意设计为彼此镜像,因此该错误在三者上的表述相同,只有表面不同:

artifacts $import: is not a bare-name artifact-library reference (#/artifacts/): "<the value as written>"(artifacts $import: 不是裸名称的 artifact-library 引用) valuesMapping $import: is not a bare-name mapping-library reference (#/mappings/): "<the value as written>"(valuesMapping $import: 不是裸名称的 mapping-library 引用) workload $import: is not a bare-name workload-library reference (#/workloads/): "<the value as written>"(workload $import: 不是裸名称的 workload-library 引用)

以 @ 书写的版本会在报告中附上应改用的写法,而不是落入“未找到库”的报错,因为这是该形式最常见的错误:

artifacts $import: is not a bare-name artifact-library reference (#/artifacts/): version separator is ’:’, not ’@’ — use "<the corrected value>"(artifacts 的 $import: 不是裸名称形式的制品库引用:版本分隔符是 ’:‘,而不是 ’@‘,请改用修正后的值)

还有一种情形也在此报告,而它并非拼写错误。 ArtifactLibrary bundle 自身的文件主体不能本身是对另一个 bundle 的 $import::一个文件槽位无法展开为多个文件,因此嵌套导入会被拒绝,而不会被解析成作者未曾书写的内容。请改为在使用这些 bundle 的位置组合它们。

组件自身 Recipe 书写的 artifacts: 条目在任何渲染之前就已确定,因此报告定位在该 Recipe 中的 artifacts: 块,并指出该引用、bundle、主体中带有嵌套导入的文件,以及书写该导入的条目。bundle 中所有属于该情形的文件都会在一次构建中报告;如果不止一个,这些结果会归组在 artifacts entries whose library import the compiler cannot resolve 之下:

artifacts $import: is not a bare-name artifact-library reference (#/artifacts/) ("<the value as written>", bundle "<bundle>", bundle file "<filename>", artifacts entry "<key>"). a bundle file body cannot import another bundle — compose the two at the artifacts entry that consumes them(artifacts $import: 不是裸名称的 artifact-library 引用。bundle 文件主体不能导入另一个 bundle——请在使用它们的 artifacts 条目处组合二者)

FeatureRecipe 书写的 artifacts: 条目会在解析 bundle 时报告相同的情况,并指出第一个属于该情形的文件:

artifacts $import: is not a bare-name artifact-library reference (#/artifacts/): bundle "<bundle>" file "<filename>" body is a field-root $import: (nested library import inside a bundle file is not supported; compose at the consumption site)(artifacts $import: 不是裸名称的 artifact-library 引用:bundle 文件主体是字段根级 $import:(不支持在 bundle 文件内嵌套库导入;请在使用处组合))

组件自身 Recipe 书写的 valuesMapping: 在任何渲染之前就已确定,因此报告定位在该 Recipe 中的 valuesMapping: 键,并附上应使用的写法:

valuesMapping $import: is not a bare-name mapping-library reference (#/mappings/) ("<the value as written>"). name the library and the entry either side of the fragment — write #/mappings/(valuesMapping 的 $import: 不是裸名称形式的映射库引用。请在片段两侧分别写出库名和条目名)

FeatureRecipe 书写的 valuesMapping: 会在解析引用时报告,形式与上面列表中的相同。

组件自身 Recipe 书写的 workload: 在任何渲染之前就已确定,因此报告定位在该 Recipe 中的 workload: 键,并附上应使用的写法:

workload $import: is not a bare-name workload-library reference (#/workloads/) ("<the value as written>"). name the library and the entry either side of the fragment — write #/workloads/(workload 的 $import: 不是裸名称形式的工作负载库引用。请在片段两侧分别写出库名和条目名)

FeatureRecipe 书写的 workload: 会在解析引用时报告,形式与上面列表中的相同。

**如何修复:**将该值改写为 <Library>#<entry-path>,仅在需要为可选版本设定下限时,才在库名称之后添加 :<version>。检查片段是否与字段匹配——在 workload: 上使用 #/mappings/… 的条目路径,指向的是该字段不读取的表面,会在此报告,而不是作为缺失条目报告。同样的身份形式也适用于 schema 的 $ref:,其拒绝情况记录在上文的“A $ref: is not written in a form the compiler can resolve(未以编译器能够解析的形式书写)”中。

A library $import: names a library or an entry the catalog does not hold(库导入指向的库或条目不在目录中)

$import: 写法正确,但它指向的内容不存在。共有六种情况,覆盖三种库类型下引用的两个部分;你遇到的是哪一种,就说明该检查哪一部分:要么库本身不在构建可见的范围内,要么库存在但未发布该条目。

引用解析所依据的集合,是工作区自身的目录,加上 lockfile 已固定并在构建加载时引入的库。因此,如果 Release 的依赖闭包中没有任何内容声明对某个库的依赖,该库就不在这个集合中,无论指向它的引用写得多么正确。

库不存在:

artifact-library import references an ArtifactLibrary not present in the catalog: ArtifactLibrary "<library>" (bundle "<entry>")(artifact-library 导入引用了目录中不存在的 ArtifactLibrary) mapping-library import references a MappingLibrary not present in the catalog: MappingLibrary "<library>" (entry "<entry>")(mapping-library 导入引用了目录中不存在的 MappingLibrary) workload-library import references a WorkloadLibrary not present in the catalog: WorkloadLibrary "<library>" (entry "<entry>")(workload-library 导入引用了目录中不存在的 WorkloadLibrary)

条目不存在:

artifact-library import references a bundle not present in the ArtifactLibrary: bundle "<entry>" in ArtifactLibrary "<library>"(artifact-library 导入引用了 ArtifactLibrary 中不存在的 bundle) mapping-library import references an entry not present in the MappingLibrary: entry "<entry>" in MappingLibrary "<library>"(mapping-library 导入引用了 MappingLibrary 中不存在的条目) workload-library import references an entry not present in the WorkloadLibrary: entry "<entry>" in WorkloadLibrary "<library>"(workload-library 导入引用了 WorkloadLibrary 中不存在的条目)

**组件自身 Recipe 编写的 artifacts: 条目会以其专有形式报告缺失的 bundle。**该条目在任何渲染之前即已确定,因此报告定位在该 Recipe 的 artifacts: 块,并在引用的两个部分之外,同时指出导入所在的条目:

artifact-library import references a bundle not present in the ArtifactLibrary ("<entry>", ArtifactLibrary "<library>", artifacts entry "<key>")(artifact-library 导入引用了 ArtifactLibrary 中不存在的 bundle)

组件自身 Recipe 编写的 valuesMapping: 会以其专有形式报告缺失的条目,原因相同:它同样在任何渲染之前即已确定,因此报告定位在该 Recipe 的 valuesMapping: 键,并指出引用的两个部分:

mapping-library import references an entry not present in the MappingLibrary ("<entry>", MappingLibrary "<library>")(mapping-library 导入引用了 MappingLibrary 中不存在的条目)

组件自身 Recipe 编写的 workload: 会以其专有形式报告缺失的条目,原因相同:它同样在任何渲染之前即已确定,因此报告定位在该 Recipe 的 workload: 键,并指出引用的两个部分:

workload-library import references an entry not present in the WorkloadLibrary ("<entry>", WorkloadLibrary "<library>")(workload-library 导入引用了 WorkloadLibrary 中不存在的条目)

FeatureRecipe 编写的 artifacts: 条目、FeatureRecipe 编写的 valuesMapping: 或 workload:,以及所有指向构建不可见之库的引用,都在引用解析时报告,形式即上面两个列表所列。

无论哪一部分失败,每条报告都会同时指出库和条目,因此只需一条报告,无需打开任何文件,即可区分是库缺失还是条目缺失。

**修复方法:**对于缺失的条目,对照库所发布的内容检查名称——条目名称是该库自身映射中的键,区分大小写。对于缺失的库,引用通常是正确的,不足的是依赖闭包:声明对该库的依赖以便加载它,并刷新 lockfile 以固定它。某个库在一个工作区可达而在另一个工作区不可达,是同一故障从另一面看到的样子。

A library $import: addresses its library by registry location(库导入按注册表位置寻址其库)

库 $import: 按身份指定其库,绝不按它恰好发布到的 registry 指定。一个名称通过哪个 registry 解析属于工作区配置,使用哪个版本由 lockfile 决定;因此,携带主机的引用会在目录文档中固定两件本应由构建决定的事——该文档随后在任何配置不同的工作区中都将失效。

**这类引用实际仍能触发此中止的范围比看上去要窄。**Recipe 和 FeatureRecipe 自身的 $import: 字段会更早地被其 schema 拒绝,该 schema 在三个位置都不接受 registry 前缀。剩下的是没有任何 schema 描述的引用:从库条目自身主体中读出的引用,使用它的实体并未编写它,且在主体解析之前无法看到它。

发出的消息,来自 valuesMapping: 和 workload: 两个表面,解析器在此只报告该值:

library $import: carries a registry host; reference the library by bare-name identity: "<the value as written>"(库 $import: 携带了 registry 主机;请按裸名称身份引用该库)

artifacts: 条目不会触发此中止,如果你在那里寻找它,了解原因会有帮助。它自身的引用与其他所有位置一样,随文档其余部分一起被拒绝;而与另外两个表面不同,主体本身是导入的 bundle 文件会被拒绝而不是被跟随——因此不存在可让携带主机的引用到达的主体。

**修复方法:**删除主机以及库名称之前的所有内容,只保留 <Library>#<entry-path>。如果出错的值位于你使用而非发布的库中,修正应由该库的作者完成;在修正发布之前,导入其他条目或就地编写主体即可使构建通过。

Two artifact outputs of one Recipe carry the same filename(同一 Recipe 的两个 artifact 输出使用了相同的文件名)

Recipe 的 artifacts: 块每个键命名一个输出,在某个键处导入的 bundle 会将其文件放在该键之下。两个输出落到同一文件名意味着一个会覆盖另一个,因此构建会停止,而不是选择保留哪一个。

**这是一个残余防护,说明这一点也是它的意义所在。**输出以其编写时所在的键命名,映射键在一个文档内唯一,且编写表面将一个键限定为单个文件名——因此两个编写的条目不可能冲突,一个键也无法拼出另一个键的 bundle 所产生的嵌套名称。该防护仍覆盖的,是未经过已编写文档自身重复键拒绝就到达投影的内容:在构建运行期间组装、而非从文件读取的状态。因此此处报告的冲突指向的是构建的组装方式,而不是你能看到的某一行。

它按 Recipe 针对该 Recipe 自身的输出触发,这正是它与组装中两个不同贡献者落到同一路径的区别——后者是上文的“Two contributors write the same output path(两个贡献者写入同一输出路径)”,补救方法不同。

发出的消息:

artifacts output filename collision: two artifact outputs carry the same filename (Recipe "<recipe>", artifact output "<filename>" emitted more than once)(artifacts 输出文件名冲突:两个 artifact 输出使用了相同的文件名)

**修复方法:**打开消息指出的 Recipe,对照其导入的任何 bundle 所贡献的文件检查其 artifacts: 键。如果这些键确实各不相同而冲突依然存在,则文档本身没有问题,值得将此报告反馈给构建的维护者。

An ArtifactLibrary bundle file names no file of its own under the key it was imported at(ArtifactLibrary bundle 文件在其导入所在的键下未指定属于自己的文件)

导入 bundle 的 artifacts: 条目会展开为该 bundle 中每个文件对应的一个输出,每个输出都嵌套在编写该导入时所在的键之下。因此,该键指定一个目录,bundle 贡献的每个文件都以自己的名称归属于该目录之下。若文件名爬出该目录、指定绝对位置或根本未指定任何内容,则不满足这一点,构建会停止,而不是把文件放到使用它的 Recipe 从未选择的位置。

“未指定任何内容”涵盖所有不是键之下某个文件唯一写法的名称。 . 和 ./,以及会折叠回键本身的名称(如 x/..),指的都是键本身,因此该文件会被写到键的目录所在之处。带有末尾或重复 / 的名称,或含有 . 或 .. 部分的名称——x/、a//b、./a、a/./b、a/../b——是另一个名称也可指向的文件的第二种写法:a//b 与 a/b 并存就是同一文件的两个名称,其中一个会覆盖另一个,且不报告任何冲突。空名称同样会被拒绝。

它防止的是静默的重新布局,而不是写到输出目录之外。 文件写入的位置另有防护,因此爬得足够远的名称无论如何都会在那里被拒绝。能通过该防护的名称是恰好向上爬一级的名称:它会落回输出目录之内,处于一个无人选择的位置。这比被拒绝的写入更糟,因为这条路径上的每个冲突防护都按名称的组合形式而非解析结果来读取——因此两个这样的文件可能解析到同一个输出,而没有任何冲突报告,最终保留哪一个也不由任何人编写的内容决定。

在键之内直接编写的嵌套布局不受影响。 bundle 可以自由携带自己的子目录,例如 rbac/role.yaml,将它们嵌套在使用键之下正是键的用途。仅在某个部分内包含点号的名称,例如 ..config 或 role.v1.yaml,是普通名称。

使用方 Recipe 与发布的 bundle 通常由不同作者编写,因此消息会同时指出这两方以及修复方法。

组件自身 Recipe 编写的 artifacts: 条目在任何渲染之前就已确定,因此报告定位在该 Recipe 中的 artifacts: 块,先指出文件,再指出它来自的库以及使用它的条目。bundle 中所有名称被拒绝的文件都会在一次构建中报告;若有多个,结果会归组在 artifacts entries whose library import the compiler cannot resolve 之下:

artifact-library bundle file name does not name a file of its own beneath the artifacts key its output is nested under ("<filename>", ArtifactLibrary "<library>", artifacts entry "<key>"). rename the file inside the ArtifactLibrary bundle to an ordinary file name beneath the artifacts key it is consumed at, such as “config.yaml” or “rbac/role.yaml” — no ”.” or ”..” part, and no leading, trailing or doubled ”/“(artifact-library bundle 文件名未在其输出所嵌套的 artifacts 键之下指定属于自己的文件。请将 ArtifactLibrary bundle 中的该文件重命名为其使用所在 artifacts 键之下的普通文件名,例如 “config.yaml” 或 “rbac/role.yaml”——不含 ”.” 或 ”..” 部分,也不含开头、末尾或重复的 ”/”)

FeatureRecipe 编写的 artifacts: 条目会在解析 bundle 时报告同一情况,指出编写它的 recipe 以及第一个此类文件:

artifact-library bundle file name does not name a file of its own beneath the artifacts key its output is nested under (Recipe "<recipe>", artifact "<key>", bundle file "<filename>"). rename the file inside the ArtifactLibrary bundle to an ordinary file name beneath the artifacts key it is consumed at, such as “config.yaml” or “rbac/role.yaml” — no ”.” or ”..” part, and no leading, trailing or doubled ”/“(artifact-library bundle 文件名未在其输出所嵌套的 artifacts 键之下指定属于自己的文件。请将 ArtifactLibrary bundle 中的该文件重命名为其使用所在 artifacts 键之下的普通文件名,例如 “config.yaml” 或 “rbac/role.yaml”——不含 ”.” 或 ”..” 部分,也不含开头、末尾或重复的 ”/”)

修复方法: 将 ArtifactLibrary 中的该文件重命名为键之下的普通文件名。若该库不归你所有,在上游修正期间,导入另一个 bundle 或就地编写该条目即可使构建通过。打算落到完全不同位置的文件,应作为其所属键下的第二个 artifacts: 条目,而不是用一个走到那里的名称。

An imported artifact no longer matches the digest recorded beside its Recipe(导入的制品与其 Recipe 旁记录的摘要不再一致)

导入本地文件的 artifacts: 条目会在 Recipe 被固定时固定其内容——通过 aggrega pin,或通过被要求执行同一步骤的 pull 或 push:文件字节的摘要会记录在 Recipe 旁的 entity.lock 中。Recipe 的 boundary.artifacts: 中的条目也以同样方式固定和比较,记录在 boundary/<key> 下,消息中也使用这个名称。每次构建都会重新读取文件、再次计算摘要,并拒绝不一致——因此固定之后被编辑的文件绝不会像已经过检查一样被渲染。aggrega pull --verify 进行同样的比较,并以相同消息报告不一致。

比较的是条目的内容,而不是渲染它所产生的结果。 制品正文是一个模板,对其求值会代入每个组件实例各不相同的值,因此基于输出计算的摘要对每个值不同的实例都会不一致。记录的内容对绑定该 Recipe 的每个实例都是相同文本,这正是一个记录的摘要适合作为比较对象的原因。

无人固定过的 Recipe 旁没有固定记录,构建也不会比较它。 对构建而言,缺少固定记录并不是不匹配,而是意味着没有可比较的内容。对这样的 Recipe 执行 pull 则会停止,如 An entity reads an input the lock beside it records no pin for(实体读取了其旁边的锁未记录固定的输入) 所述。在文件被编辑之前写入的 lockfile 会先报告,因为实体的行同样涵盖导入的文件,如 A local source no longer matches the pins recorded beside its Recipe(本地源与其 Recipe 旁记录的固定不再一致) 所述,该节同时说明了构建何时遇到的是此项比较。

三个场景对不同文档执行同一检查——组件自身的 Recipe、附加到组件的 Feature,以及附加到边界的 Feature——因此 FeatureRecipe 的内容是与 FeatureRecipe 旁记录的摘要比较,而不是与宿主组件 Recipe 旁的摘要比较。在两个附加场景中,消息还会指出该附加项,由此可知应打开哪个文档。

输出的消息:

imported artifact content does not match the digest recorded for it in entity.lock ("<artifact>", imported file "<path>", its content digests to "<digest>", the recorded pin is "<digest>"). If the file was changed on purpose, run aggrega pin on the entity that imports it to record its new digest; otherwise restore the file(导入的 artifact 内容与 entity.lock 中为其记录的摘要不匹配。如果文件是有意修改的,请对导入它的实体运行 pin 以记录新摘要;否则请恢复该文件) imported artifact content does not match the digest recorded for it in entity.lock ("<artifact>", imported file "<path>", its content digests to "<digest>", the recorded pin is "<digest>", attachment "<attachment>"). If the file was changed on purpose, run aggrega pin on the entity that imports it to record its new digest; otherwise restore the file(导入的 artifact 内容与 entity.lock 中为其记录的摘要不匹配,并给出附加项。如果文件是有意修改的,请对导入它的实体运行 pin 以记录新摘要;否则请恢复该文件)

修复方法: 有两种答案,取决于该编辑是否有意为之。若是有意的,对该 Recipe 运行 aggrega pin,从文件当前字节重新固定,并提交它重写的 entity.lock。若不是,请恢复该文件——记录的摘要是对已固定字节的记录,渲染已更改文件的构建将交付未经任何验证的内容。

A local source no longer matches the pins recorded beside its Recipe(本地源与其 Recipe 旁记录的固定值不再匹配)

如果某个 Recipe 或 FeatureRecipe 的 source: 指向其旁边的目录或文件,那么在固定该实体时(通过 aggrega pin,或通过被要求执行同一步骤的 pull 或 push),该源也会被固定。实体旁的 entity.lock 为该源贡献给实体发布内容的每个文件记录一个摘要,以文件路径为键。一旦锁文件记录了这些摘要,每次构建都会在 provider 读取源之前,将源的当前状态与这些固定值比较,并拒绝不一致的情况,因此固定之后被编辑的 chart 或模块绝不会被当作已检查过的内容来渲染。aggrega pull --verify 执行相同的比较,并以相同的消息报告不一致。构建会指出它正在解析其源的组件实例,以及其下的 Recipe 文档。

**源作为一个文件集合进行比较。**内容发生变化的文件、新增到源中的文件以及从源中移除的文件,都会改变实体的渲染依据,因此每一种都会被报告,同时给出文件当前的摘要和为其记录的摘要。实体旁不属于源贡献的文件(例如 Recipe 旁的说明或 README)不参与比较。以模板形式编写的源,例如 ./charts/{{ .values.flavour }},会贡献实体目录中的所有文件,因为它指向哪个目录由每个 Release 决定;对于这种形式,目录中任何文件的编辑都会被报告。

**如果 Recipe 的锁文件没有为其源记录固定值,构建就没有可比较的内容。**构建不会拒绝它;不执行固定的 pull 或 push 则会拒绝,如 An entity reads an input the lock beside it records no pin for(实体读取了其旁锁文件未记录固定值的输入) 所述。对于 Recipe 已不再声明的本地源,锁文件中仍记录的固定值不固定它读取的任何内容,因此不与任何内容比较。从注册表经 pull 解析的 Recipe,则改由 lockfile 为其发布内容记录的摘要来覆盖。

**在更改之前写入的 lockfile 会先报告。**lockfile 按实体所携带的内容记录实体,而源的文件是其中的一部分,因此持有在文件变动前写入的 lockfile 的构建或 aggrega pull --verify 会在此比较运行之前停止,并由 The lockfile no longer matches what the release resolves to(lockfile 与 release 的解析结果不再匹配) 指出该实体及两个摘要。普通的 aggrega pull 会通过 An entity reads an input the lock beside it records no pin for(实体读取了其旁锁文件未记录固定值的输入) 指出变动的文件。导入的文件同样如此。**如果 lockfile 中没有该实体自己的条目,构建和验证性 pull 遇到的就是此比较:**如果 Manifest 引用某个 Recipe 或 FeatureRecipe 所用的引用名同时也是 Release 所达到的某个 Component 或 Feature 的名称,它会以该引用记录为 Component 或 Feature,因此 Recipe 的文件变化时,lockfile 中没有任何内容发生变化。

输出的消息:

the files of the entity’s local source do not match the pins recorded for them in entity.lock (file <path> digests to <digest> and its recorded pin is <digest>). If the source was changed on purpose, run aggrega pin on the entity to record its files again; otherwise restore the files(实体本地源的文件与 entity.lock 中为其记录的固定值不匹配(该文件的摘要与为其记录的固定值不同)。如果源是有意更改的,请对该实体运行 aggrega pin 以重新记录其文件;否则请恢复这些文件) the files of the entity’s local source do not match the pins recorded for them in entity.lock (file <path> digests to <digest> and no pin is recorded for it). If the source was changed on purpose, run aggrega pin on the entity to record its files again; otherwise restore the files(实体本地源的文件与 entity.lock 中为其记录的固定值不匹配(该文件有摘要,但没有为其记录固定值)。如果源是有意更改的,请对该实体运行 aggrega pin 以重新记录其文件;否则请恢复这些文件) the files of the entity’s local source do not match the pins recorded for them in entity.lock (file <path> is no longer in the source and its recorded pin is <digest>). If the source was changed on purpose, run aggrega pin on the entity to record its files again; otherwise restore the files(实体本地源的文件与 entity.lock 中为其记录的固定值不匹配(该文件已不在源中,但仍记录有其固定值)。如果源是有意更改的,请对该实体运行 aggrega pin 以重新记录其文件;否则请恢复这些文件)

**修复方法:**与导入的文件一样,有两种做法,哪种正确取决于更改是否有意为之。如果是有意的,请对该 Recipe 运行 aggrega pin,重新固定其源的文件,并提交它重写的 entity.lock。如果不是,请恢复消息中指出的文件。

实体发布所携带的每个文件都从实体自己的目录中读取,其中的符号链接会被拒绝,而不会被跟随。跟随它会以链接自身的名称发布其所指向的字节(无论指向何处,包括实体目录之外),并放入一个随后会被计算摘要、在适用签名时还会被签名的制品中。而跳过它则会发布一个内容与你的目录悄然不同的制品。因此,所有形式的链接都以相同方式被拒绝:指向文件的链接、指向目录的链接、不指向任何位置的链接、指向自身的链接,以及相互指向的两个链接。

凡是读取实体文件的地方都会执行此拒绝:aggrega pin、在打包任何内容之前的发布(包括试运行)、以 entity.lock 核对实体文件的 pull 和验证性 pull、将本地源与其固定值比较的构建,以及在向 provider 交付任何内容之前读取本地源目录的渲染。消息按链接相对于实体文档的路径指出该链接,诊断定位在链接本身。

被你的忽略规则排除的链接不是实体携带的文件,因此它会像这些规则排除的其他文件一样被跳过,且绝不会被跟随。这些规则是固定实体时记录在 entity.lock 中的规则,因此你添加到 .aggregaignore 的行会在你重新固定该实体时生效。

发出的消息:

a symbolic link sits among the files an entity carries (<path>). remediation: replace the link with a copy of what it points to, placed inside the entity’s own directory. A link met inside a source directory can instead be left out with a line in the .aggregaignore beside the entity, which takes effect when the entity is pinned again. A link is refused rather than followed because the bytes it points to would travel under the link’s name, from wherever it points(实体携带的文件中存在符号链接。补救方法:将该链接替换为其所指内容的副本,并放在实体自身的目录中。对于源目录中遇到的链接,也可以在实体旁的 .aggregaignore 中添加一行将其排除,该设置在重新固定实体时生效。链接会被拒绝而不是被跟随,因为它所指向的字节无论来自何处,都会以该链接的名称被携带)

**修复方法:**如果实体需要链接所指向的内容,请将链接替换为实体目录中该内容的副本,然后重新固定实体。如果链接只是为了你自己的方便而存在、实体并不读取它,请将其路径添加到实体文档旁的 .aggregaignore 中,然后重新固定。Which files ship with an entity 介绍了决定实体携带哪些内容的规则。

An entity reads an input the lock beside it records no pin for(实体读取了其旁锁文件未记录固定值的输入)

Recipe 或 FeatureRecipe 可以依赖其自身文档之外的字节:完整写出坐标的远程 source:、artifacts 条目通过 $import 导入的文件,以及指向其旁边目录或文件的 source: 的文件。每一项的固定值都记录在实体旁的 entity.lock 中,而记录固定值是实体作者的步骤,即 aggrega pin。因此 pull 不会自行记录这些固定值:对于 Release 构建的、位于你某个目录中的实体,它会将该步骤将要记录的内容与锁文件中的内容比较,当锁文件缺少某个固定值(或持有的固定值与输入不再匹配)时停止,而不会未经要求就写入作者的目录。填充自身 lockfile 的构建也是一次 pull,会以同样的方式停止。

**push 会针对它即将发布的那个实体,在同样的比较上停止。**在构建 bundle 之前、联系任何注册表之前,它会将该步骤将为该实体记录的内容与实体旁的锁文件比较,并以同样的方式拒绝(包括试运行),除非 push 被要求自行执行该步骤。两者在消息末尾给出的建议不同,因为每个命令都有自己记录固定值的方式;报告的内容则相同。

**本地源作为一个文件集合与其固定值核对。**如果锁文件未记录任何固定值,源贡献的每个文件都会在此报告为缺失。如果已记录,则固定之后新增的文件报告为缺失,而被更改或移除的文件报告为与输入不再匹配的固定值;构建则将同样的更改报告为 A local source no longer matches the pins recorded beside its Recipe(本地源与其 Recipe 旁记录的固定值不再匹配)。对于 Recipe 已不再声明的本地源(其 source: 被移除,或现在指向远程制品),锁文件中仍记录的固定值不固定 Recipe 读取的任何内容,因此它们不会使 pull、push、验证性 pull 或构建停止;下一次 aggrega pin 会删除它们。

**消息按类别列出所缺的每个输入。**每一项为 remote source(以其 url 及解析到的版本指出)、imported file(以使用它的 artifacts 键指出)或 local source file(以其相对于实体的路径指出),因此你可以知道需要固定的是源还是文件。Release 中所有此类实体都会在一次运行中报告。

**从注册表解析的实体绝不会被 pull 以此核对,因为它在发布时已经核对过。**它位于内容缓存中,而不是你编写的目录中,因此 pull 既不读取也不写入其旁的锁文件,其源则以 Release 的 lockfile 核对。使用 aggrega push 发布的实体,除非其锁文件记录了该步骤当时将为其记录的每个固定值,否则在发布时就会被拒绝,而该锁文件会随已发布的 bundle 一起传递。

输出的消息(分别来自 pull 和 push):

an input the entity reads has no pin recorded for it in the entity.lock beside it (Recipe "<name>", remote source <url>@<version>: no pin recorded, imported file <key>: the recorded pin no longer matches it). remediation: run aggrega pin <entity-path> and commit the entity.lock it writes beside the entity; to have every pull in this workspace record the pins itself instead, set pin_sources_at_pull: true in the workspace configuration an input the entity reads has no pin recorded for it in the entity.lock beside it (Recipe "<name>", remote source <url>@<version>: no pin recorded). remediation: run aggrega pin <entity-path> and commit the entity.lock it writes beside the entity; to have this publication record the pins itself instead, re-run it with --pin-sources; to have every publication in this workspace record them, set pin_sources_at_push: true in the workspace configuration

发布消息的中间子句指出你所用的发布入口接受的选项:终端中的 --pin-sources、守护进程上的 pinSources 字段,以及助手工具的 pin_sources 参数。

**修复方法:**如果实体是你的,请对其运行 aggrega pin 并提交它写入的 entity.lock,然后重新 pull 或 push;或者使用 --pin-sources 执行 push,它会在构建 bundle 之前执行该步骤。如果实体属于他人(你从其自身目录使用的目录),说明其发布者尚未固定它;请在工作区配置中设置 pin_sources_at_pull: true,让每次 pull 自行记录固定值,或者为单次 pull 传入 --pin-sources。aggrega pin 完整介绍了该步骤。

A provides: template could not be evaluated(provides 模板无法求值)

provides: 条目是一个模板,生成另一个组件通过依赖连接读取的值。无法求值的条目会报告此情况:模板无法解析、调用了此入口未注册的函数、引用经过了渲染上下文未提供的内容,或者 index 读取了映射中不存在的键。

它不同于在同一块上于求值之前执行的两种拒绝:引用自包含集合之外的根,以及块自身编写顺序所拒绝的引用,两者均已在上文说明。那两种会指出需要更改的表达式;而此情况携带求值本身报告的内容,因此会在旁边指出该条目。

输出的消息,指出组件实例、块内的条目以及求值报告的内容:

provides template evaluation failed (node "<instance>", provides["<key>"], <what the evaluation reported>)

无论求值报告了什么,首行都带有此条件的代码 E0056。 如果求值因其自身的某个中止条件而停止——最常见的是对映射中不存在的键进行 index 读取——该条件会报告在此条件之下,而不是取代它:在 caused by (2): 之下,先是此条件的语句,其次是求值自身的报告,包括其语句。因此,按代码匹配的读者会将每个失败的 provides: 条目都对应到 E0056,并从其下的条件中读出导致求值失败的原因;该条件的语句在所有条件的表格中对应其自身的代码——缺失的键对应 E0327。

**修复方法:**打开 Recipe 的 provides: 块中消息指出的键,阅读报告的原因,它通常会指出解析位置或函数。此入口对缺失键的处理是将缺失的末级键渲染为空而不是失败,因此此处的失败属于结构性错误:模板无法解析、引用经过了从未提供的容器,或者 index 读取了映射中不存在的键,报告的原因会指出是哪一种。如果该值确实是可选的,请通过 optional 辅助函数读取,而不要深入可能不存在的内容。

A Recipe or FeatureRecipe does not publish a provides key its contract declares(Recipe 或 FeatureRecipe 未发布其契约所声明的键)

Component 和 Feature 各自在 schema.provides 下声明绑定它们的任何实体将发布的键——即消费者据以编写其连接的输出契约。绑定到 Component 的 Recipe 和绑定到 Feature 的 FeatureRecipe 必须产出该契约列出的每个键。未做到的会被拒绝,因为缺失的键否则将什么也不传递:消费者的引用会以未设置的变量、空参数或不存在的文件到达,且不会给出任何原因。

**该契约只关乎键是否存在,仅此而已。**每个声明的键都必须出现;允许有额外的键。值本身从不被检查——它们是以字符串传递的不透明指针,因此契约声明的类型只是对消费者的说明,而不是构建执行的检查。

**每一处缺失都会被报告。**缺少三个键的 Recipe 会产生三条发现,每条都定位到该 Recipe 的 provides: 块中各自的条目,因此一次构建即可修正全部三处。消息会指出缺失的键、其契约声明该键的类型,以及该 Recipe 所绑定的实例——当一个 Recipe 服务于同一类型的多个实例时,最后这一项用来区分两条发现。

发出的消息:

Recipe or FeatureRecipe does not publish a provides key its abstract entity’s schema.provides contract declares ("<key>", declared by component type "<type>", bound to component instance "<instance>")(Recipe 或 FeatureRecipe 未发布其抽象实体的 schema.provides 契约所声明的 provides 键)

Feature 与 FeatureRecipe 的配对通过该挂载自身的解析报告同一情况,并指出该配对和键:

Recipe or FeatureRecipe does not publish a provides key its abstract entity’s schema.provides contract declares (<attachment context>, <the FeatureRecipe> does not publish provides key "<key>" declared by <the Feature>’s schema.provides contract)(Recipe 或 FeatureRecipe 未发布其抽象实体的 schema.provides 契约所声明的 provides 键)

在此情况下,它按排序顺序报告第一个缺失的键后即停止,因此该配对每次构建只指出一个键,而 Component 配对会指出全部缺失的键。两种情况下键都按排序顺序遍历,这使得两者在多次运行之间结果一致。

**如何修复:**将缺失的键添加到 Recipe 或 FeatureRecipe 的 provides: 块中,或者在不期望任何实体发布它时,将其从 Component 或 Feature 的 schema.provides 中移除。模板渲染为空的键仍会被发布,其值为空字符串,因此存在但为空的条目满足契约,不会在此报告。如果空值必须使构建停止,请在断言中拒绝它:Recipe 的断言会读取其解析后的 provides: 值。

An assertion stopped the build(断言使构建停止)

Component、Feature、Recipe 或 FeatureRecipe 可以带有 assertions:——这是一些具名模板,其用途是拒绝某个输入,而不是生成文本。断言会调用 fail,调用它就会使构建停止;其参数是作者为遇到它的人所写的消息。

断言在两个时间点求值,以便规则读取它所关注的状态:Component 或 Feature 上的断言在目录解析完成后、任何内容渲染之前运行;Recipe 或 FeatureRecipe 上的断言在绑定确定后、该绑定渲染之前运行。

**引用一个没有任何来源提供的键也会在此报告。**该表面以严格的缺失键处理方式求值,正是为了让引用渲染为空的谓词无法与“无”比较并悄然通过——否则一个拼写错误就会使断言本应强制执行的规则失效。这也是为什么普通的 default 在此表面上无法提供回退值:裸引用会在回退执行之前就停止求值。请用 hasKey 守护该引用,或使用 optional 辅助函数;通过 index 读取同样会停止并指出该键,如“A template indexes a map with a key the map does not hold(模板使用映射中不存在的键进行索引)”所述。

发出的消息,指出实体种类和类型、实例以及断言,随后附上断言自身编写的消息:

<entity-kind> "<type>" instance "<instance>" assertion "<name>": assertion "<kind>/<type>/<instance>/<name>": template: <kind>/<type>/<instance>/<name>:<line>:<column>: executing "<kind>/<type>/<instance>/<name>" at <fail …>: error calling fail: assertion failed: <the message the assertion wrote>(调用 fail 时出错:断言失败)

而对于没有任何内容提供的键,条件自身的语句之后是模板引擎的语句:

<entity-kind> "<type>" instance "<instance>" assertion "<name>": assertion "<kind>/<type>/<instance>/<name>": assertion failed: template: <kind>/<type>/<instance>/<name>:<line>:<column>: executing "<kind>/<type>/<instance>/<name>" at <.reference>: map has no entry for key "<key>"(断言失败:模板执行时映射中没有该键的条目)

以及当失败的是求值而非谓词时:

<entity-kind> "<type>" instance "<instance>" assertion "<name>": assertion "<kind>/<type>/<instance>/<name>" parse: <what the parse reported>

**声明为敏感的值不会出现在消息中。**当断言读取此类值,并以完整写成单个带引号字符串的语句调用 fail 时(即 fail "…",既没有通过管道传入任何内容,也没有进行任何拼接),无论该值的内容是什么,消息都会原样包含该语句,因为该语句没有引用断言读取的任何内容。当其消息引用了该值时,消息会在该值的位置显示 <redacted>。当消息以其他任何方式拼接而成,且断言的行为取决于该值的内容时,失败表达式之后的消息会被替换为 failure text withheld: this template reads a value declared sensitive, and the failure depends on what that value holds;停止及其代码保持不变。哪些算作已声明,以及哪些拒绝不在此范围内,参见 vocabulary/compact-form-authoring.md 中的“What a refusal says about a declared value”。

**单独检查实体时,失败的断言会作为警告报告。**给定 Recipe 文件的 aggrega validate、编辑器通过 aggrega serve 对该文件的检查,以及给定 entity 的 aggrega mcp 的 validate 工具,都会基于占位符和 schema 默认值而非 Release 设置的值来构建该 Recipe,因此无法区分等待 Release 的断言与已损坏的断言。在这些场景中,调用 fail 的断言——无论是 Recipe 自身的,还是它所实现的 Component 声明的——会作为警告报告,附带上述消息,并以句子 A Release must satisfy this assertion before a build of it can pass. 结尾,检查仍会通过。引用无来源提供的键以及无法解析的断言不属于失败的断言:二者都是断言自身文本中的错误,该检查会像对待其他错误一样判定它们。构建总是有一个 Release,并会按此处所述在断言上停止;参见失败的断言是一个警告。

**如何修复:**最后一个冒号之后的消息由断言作者编写,它说明了需要更改什么——断言的写法就是让遇到它的人知道答案。如果报告的是缺失的键而非作者的句子,则问题出在断言本身:修正该引用,或按上文所述对其加以守护。如果该规则不应适用于此 Release,这是关于带有该断言的实体的问题,而不是关于你自己文件的问题。

A pipeline step addresses documents the node does not have(流水线步骤寻址了节点没有的文档)

流水线步骤通过作用域和键来寻址文档。有三种情况涵盖了地址指向空无的各种方式,每种都会停止构建,而不是让步骤在从未发生的编辑上报告成功。

节点没有发出该文档。 补丁指定的作用域与键组合不在该节点生成的文档之中:

node "<instance>": pipeline PATCH targets a document the node did not emit(节点:管道 PATCH 指向该节点未输出的文档)

没有可寻址的宿主。 某个步骤在一个不面向任何宿主组件的位置访问宿主组件的文档——例如组件自身的流水线(其唯一作用域是它自己的输出),或附加到边界而非单个组件的 Feature。在这类流水线运行的任何位置,宿主作用域都是空的,因此对它的寻址解析不到任何东西:

node "<instance>": pipeline /host operation from a step with no host component(节点:来自没有宿主组件的步骤的管道 /host 操作)

文档没有可寻址的树。 有些单元没有可供路径指向的结构——二进制内容、自由文本、目标无法安全遍历的区域。这样的单元仍会交给步骤,以便整体选中和发出;但它不能被打补丁:

node "<instance>": pipeline PATCH target is not parseable structured YAML/JSON(节点:管道 PATCH 目标不是可解析的结构化 YAML/JSON) pipeline PATCH target is not parseable structured YAML/JSON (node "<instance>", document "<key>")(管道 PATCH 目标不是可解析的结构化 YAML/JSON,附节点与文档)

每种情况都附带遍历过程本身对其下地址的说明,并定位到由其流水线产生该操作的组件实例。

三种情况中有两种也会在任何遍历之前报告。 一个位置是否有宿主文档取决于流水线写在哪里,因此,在没有宿主文档的位置声明自己操作宿主文档的步骤,会在构建得知每个插件的声明后立即被指出,无需等待节点渲染——对于附加到边界的 Feature,会与该步骤一同被指出:

pipeline /host operation from a step with no host component(来自没有宿主组件的步骤的管道 /host 操作) pipeline /host operation from a step with no host component ("<attachment>")(来自没有宿主组件的步骤的管道 /host 操作,附挂载)

这两种报告是对同一情况的划分,而不是同一发现报告两次:声明能确定的由声明确定,只有运行时才能看到的留给运行——声明了自身作用域的步骤仍可能返回针对另一作用域的操作。

这三种情况是流水线遍历本身所报告的寻址拒绝的构建停止形式,见上文的“A pipeline patch addresses a document the set does not hold, or one with no tree to address(流水线补丁寻址了集合中不存在的文档,或没有可寻址树的文档)”。

如何修复: 这三种情况都属于步骤作者,而不是你。对于目标不存在的情况,给节点确实发出的文档打补丁,或在较早的步骤中发出你想要的文档,再在之后的步骤中给它打补丁——步骤可以读取它收到了哪些键。对于缺少宿主的情况,将步骤移到面向宿主组件的位置,改为寻址该位置自身的文档,或删除该步骤。对于没有树的单元,将补丁替换为整体发出该单元:不透明内容只能被替换,而不能被编辑。

A pipeline patch addresses output that has not been assembled yet(流水线补丁寻址了尚未组装的输出)

有些 provider 会把一个分派组的逐节点输出合并为一个文档——合并后的 compose 文件、umbrella chart。在合并发生之前不存在离散的文档,只有片段,因此寻址其中某个文档的补丁无处可指。所以,针对此类组件的流水线会整体延后,在合并产生文档后重放,这是常规路径,不需要作者做任何事。

当补丁仍然落到片段上时,构建就会遇到这一情况。它所指的是附加 Feature 自身的输出。当组件的 provider 合并其分组时,附加项的整个流水线会被推迟到合并产生文档之后——而重放所收到的只有组件的文档。针对 Feature 自身输出的步骤只在组件渲染期间提供,那时合并尚未发生,因此它没有可寻址的对象。无论 Feature 自身输出如何传递都是如此:无论它加入合并还是作为独立文档写出,它自身的作用域都不会是重放所携带的作用域。

发出操作从不受影响。 发出是添加文档而不是编辑文档,并且对每个 provider 都按节点运行,因此完全不在此范围内。

该情况会在任何遍历之前根据插件和 provider 的声明报告,并在节点渲染时作为兜底再次报告。发出的消息:

pipeline PATCH targets an assembler provider’s pre-assembly fragments ("<attachment>")(管道 PATCH 指向组装型 provider 的组装前片段,附挂载) pipeline PATCH targets an assembler provider’s pre-assembly fragments (node "<instance>", <scope>-scope document "<key>" is rendered by an assembler provider). the post-assembly phase re-runs this PATCH once the documents are discrete(管道 PATCH 指向组装型 provider 的组装前片段,该作用域的文档由组装型 provider 渲染;文档分离后,组装后阶段会重新运行此 PATCH)

如何修复: 改为寻址组件的文档而不是 Feature 自身的文档,这是合并后会被重放的形式;或者把组件放到不合并分派组的 provider 上;或者删除该步骤。三者中哪一个合适取决于该步骤要修改什么,消息会指出它寻址的作用域,便于你判断。修改 FeatureRecipe 自身的 capability: 不在其中:它不会改变合并后重放所收到的作用域,而这正是该情况所关注的。

A pipeline step’s plugin does not claim the provider rendering what it addresses(流水线步骤的插件未声明支持渲染其寻址内容的 provider)

流水线步骤所用的插件可以声明它已测试过的 provider。该列表是明确的声明,而不是隐含的“任何相似的都行”:针对未列出的 provider 运行插件,可能应用为另一种输出形态编写的补丁,因此构建会停止,而不是去尝试。

步骤所匹配的 provider,是渲染该步骤所寻址文档的那个 provider——针对组件文档的步骤匹配组件自身的 provider,针对 Feature 文档的步骤匹配 Feature 自身的 provider。在附加到组件的 Feature 上,两者都会出现,它们是来自两个不同文档的两个不同值。

空的或缺失的声明列表不匹配任何 provider,因此使用此类插件的每个步骤都会在此报告。构建无法询问的插件是另一种情况,不会在此报告:无法获取的自我报告是声明的缺失而非空声明,这样的步骤会因解析、加载或自我报告失败本身而停止,那才是需要修复的地方。

该情况在构建得知每个插件对自身的声明之后、在会调用该步骤的运行之前报告,并且按每个编写的步骤报告一次,而非每次构建报告一次——因此作者可以通过一次构建看到管道中所有出错的步骤。Provider 名称按精确匹配。

发出的消息,第一条来自组件自身的流水线,第二条来自 Feature 的流水线,后者还会指出附加项:

pipeline plugin is not compatible with the rendering provider ("<provider>")(管道插件与执行渲染的 provider 不兼容,附 provider) pipeline plugin is not compatible with the rendering provider ("<attachment>", "<provider>")(管道插件与执行渲染的 provider 不兼容,附挂载与 provider)

如何修复: 该发现定位到所编写的步骤,其指出的 provider 就是声明需要与之协调的对象。如果插件是你的,在针对该 provider 测试后,将其加入插件声明的兼容性中。如果不是,选择一个声明支持该 provider 的插件版本,通过该插件确实支持的 provider 渲染该作用域,或删除该步骤。

A provider refused a node’s input(provider 拒绝了节点的输入)

provider 可以在渲染某个 component 之前检查交给它的输入,并报告其发现。halt 严重级别的发现会停止构建;warning 和 information 严重级别的发现会与构建输出一并呈现,不会改变所发出的字节。

这是 provider 自己对你的输入的解读,而不是编译器的解读,因此它反对什么、说得有多具体,都由 provider 决定。编译器会指明 component 和 provider,并按原样携带 provider 返回的消息;当 provider 报告了多条消息时,它们会以分号分隔一起到达,因此一次构建就能告诉你全部问题。

无论输入属于 component 自己的 Recipe 还是附加的 Feature,使用的都是同一路由,因此 provider 的检查在两者上读起来完全相同。

发出的消息:

provider rejected node input: node "<instance>", provider "<provider>": <the provider's messages>

**修复方法:**阅读 provider 的消息——它们指出了已解析输入中它无法接受的内容。输入由 Recipe 的值和 component 自身的配置组装而成,因此修正通常在这两者之一;provider 自己的参考页面说明了它的要求。如果 provider 反对的是你无法通过文档更改的内容,那就需要询问编写该 Recipe 或插件的人。

A provider rendered the same input twice and produced different output(provider 对同一输入渲染两次产生了不同的输出)

给定相同的输入,构建会产生相同的输出——这是评审工具和部署工具解读构建结果所依据的契约。一种需主动启用的构建模式会直接检查这一点:每个 component 从相同输入渲染两次,并比较发出的字节。两次渲染结果不一致的 provider 在两次之间携带了状态,或在其他方面不是其输入的函数,此时构建停止。

普通构建对每个 component 只渲染一次,因此只有在检查模式下才会遇到这一情况。该模式的存在不会改变普通构建的任何行为。

比较的是 provider 原始发出的输出——即切分出渲染产物的那些字节——因此它所产生内容中任何位置的差异都会被捕获,而不只是保留到最终文件中的差异。

发出的消息:

rendering node "<instance>": node "<instance>" (provider "<provider>"): two renders of identical input produced different output: provider render is not deterministic

**修复方法:**首先找出消息所指 component 两次构建之间的差异——构建两次并比较输出。如果差异是你引用的 chart 在每次渲染时重新生成的值——随机密码、生成的密钥、Secret 或 ConfigMap 中的时间戳——那么问题出在该 chart 的输出而不是 provider,你可以通过以下两种方式之一自行解决。通过 chart 为该值提供的任意设置,从 Recipe 的 valuesMapping: 提供该值,使 chart 不再生成它。或者,如果生成的文档是 Release 不应交付的——例如由运维人员单独提供的 Secret——则用 Recipe 上的 omits: 条目将其排除在构建之外;参见 Recipe → omits: 字段。否则,问题出在 provider 而不是你的文档,你写什么都无法解决。请将其报告给提供该 provider 的插件的发布者,并指明消息所标识的 component——常见原因是时间戳、随机值,或按 map 迭代顺序而非作者编写顺序进行的排序。在修复之前,普通构建模式不受影响,将插件固定到通过检查的版本是切实可行的办法。

An omits entry left out nothing the source rendered(omits 条目没有排除任何源渲染的内容)

Recipe 或 FeatureRecipe 的 omits: 列表中适用于某次构建的每个条目——其 when: 缺省、为空或为 true——都必须从输出中排除至少一项源渲染的内容:chart 渲染的文档、compose 文件声明的 service、volume 或 config,或 CloudFormation 模板声明的资源。渲染该源的 provider 会将每个条目与其渲染结果匹配,并报告每个条目排除了多少个单元;未排除任何内容的条目会停止构建。

不匹配任何内容的条目,是对源的一个已不再成立的陈述。常见原因是源升级重命名或删除了条目所指的内容——而被重命名的文档或 service 随后会以新名称出现在输出中,这恰恰是该条目要排除的——另一个原因是条目本身有误。忽略它会交付本应排除的内容,因此构建停止并指明该条目。

消息会指明节点、provider、声明该条目的文档、该条目在该文档 omits: 列表中的位置(从 0 开始计数),以及该条目解析出的 kind、name 和 namespace,namespace 仅在条目指定时给出。对于附加到 component 的 FeatureRecipe,节点即该 component;对于附加到 boundary 的 FeatureRecipe,消息上方一行会指明该附加项及其 boundary。当多个条目都未匹配任何内容时,指明的是按你编写顺序的第一个,因此每次运行指明的都是同一条目。若某字段的模板读取了声明为敏感的值,则显示为 <redacted>,而不是其解析结果。被其 when: 丢弃的条目永远不会交给 provider,也永远不会被检查。

发出的消息。类别出现在方括号标头中:

an omits entry left out nothing the source rendered (node "<node-id>", provider "<provider>", "<document>" omits[<position>], kind "<kind>", name "<name>", namespace "<namespace>"). correct the entry so it names something the source renders, or remove it; a source upgrade that renamed or removed it is the usual cause

标头中带有此情况的短代码 E0334。

**修复方法:**将条目与源当前渲染的内容进行比较——移除该条目后构建,查看 component 渲染了什么——然后修正条目的 kind、name 或 namespace,或在其所指内容已不存在时移除该条目。对于 chart,条目通过文档自身的 kind、metadata.name 以及(当条目指定 namespace 时)文档所在的 namespace 来指定文档;对于 compose 文件,它通过键来指定 service、volume 或 config;对于 CloudFormation 模板,它通过 Type 和逻辑 ID 来指定资源,可以位于源的任意模板中。参见 Recipe → omits: 字段。

A provider’s omitted counts do not match the omits entries it was handed(provider 的省略计数与交给它的 omits 条目不匹配)

声明会省略已渲染单元的 provider,会针对交给它的每个 omits: 条目报告该条目匹配了多少个单元:每个条目一个计数,顺序与条目交付的顺序一致。如果报告缺失、计数过少或过多,或者含有小于零的计数,就无法判断某个条目究竟是否省略了任何内容,因此构建停止。这不是你编写的内容造成的:它报告的是一个返回输出不遵守其所声明契约的 provider。

发出的消息。消息会指出节点和 provider,然后是交付了多少个条目以及返回了什么:要么是计数的个数,要么是小于零的计数及其所对应的条目:

a provider’s omitted counts do not match the omits entries it was handed (node "<node-id>", provider "<provider>", handed <n> omits entries, returned <m> omitted counts)(provider 的省略计数与交给它的 omits 条目不匹配)

消息头带有该情况的短代码 E0336。

**如何修复:**将其报告给提供该 provider 的插件的发布者,并指明消息所标识的组件。provider 应履行的义务载于插件契约的省略已渲染单元一节。

Assembled output still carries a cross-boundary placeholder(组装后的输出仍带有跨边界占位符)

当一条依赖连接跨越两个组装输出时,在渲染消费方时无法得知它所携带的值:该值由另一方发布,并在双方都组装完成后才解析。因此,构建会在消费方组件的输入中写入一个占位符,provider 在组装结果存在后再将其替换为自己形式的交叉引用。

该情况报告的是在替换后仍残留的占位符。残留意味着解析从未到达它:值落在了 provider 无法寻址的位置(最常见的是被拼接进更长的字符串,而不是作为完整的值存在),或者某个跨越被标记了,但另一方没有任何东西来解析它。占位符永远不是有效输出,因此构建停止,而不会发布包含占位符的文件。

消息会指出写入该文件的 provider 以及文件所在的路径:路径仅在一次组装内唯一,因此二者合起来才能标识一个文件。所有出错的文件都会被报告,而不只是第一个;无论有多少个边界汇入该文件所在的组装,每个文件只报告一次。它针对整个 Release 文档报告,而不是针对其中的某个边界:问题出在值到达该文件的方式,而不在边界声明中,因此不需要修改任何边界声明。

发出的消息:

assembled output retains an unresolved cross-boundary link placeholder ("<provider>", "<output-path>")(组装后的输出保留了未解析的跨边界链接占位符)

**如何修复:**最常见的原因是消费方将某个值插入到了更长的字符串中。交叉引用必须作为其注入目标值的整体存在,因此请修改 Recipe 的映射,使其完整交付该值,并改用目标自身的词汇在其周围进行组合。如果该值已完整存在而占位符仍然残留,问题就在解析过程中 provider 的一侧,应由该插件的发布者处理。

模板可以直接从连接上读取生产方的值,位于 .context.uses.<alias>.provides;在边界作用域的 FeatureRecipe 中,则从 .boundary 下的边界连接读取。如果该连接连接的两个 component 渲染到不同的输出中,并且 provider 用它自己的引用来连接它,那么这些值中的每一个都会以占位符的形式到达模板,provider 会在两个输出都组装完成后替换它:替换为跨栈引用,或替换为值本身。因此,模板只能复制这样的值:完整写出它、把它写在更长的字符串中,或通过一个保持其不变的函数(例如 quote)写出。

比较、分支、长度,或改变值的函数(eq、if、len、upper、trimPrefix)都会针对占位符而不是值本身作出判断,而且不会有任何提示。构建会通过对模板求值两次来检查这一点:一次基于占位符,一次基于真实值;在把每个占位符写回之后,如果两者不一致,构建就会中止。这适用于读取此类连接的每个模板:Recipe 自身的模板、所挂载 FeatureRecipe 的 injectMapping:,以及边界作用域 FeatureRecipe 的模板。

消息会指出该模板(字段及其所属的 Recipe),并针对差异所依赖的每个 provides 值,指出消费方 component、连接的别名和插座,以及生产方 component。模板仅复制的值不会被列出。

发出的消息:

a template does more than copy a value it reads off a cross-boundary link (template "<template>", provides key "<key>" that component "<consumer>" reads off its connection "<alias>" on socket "<socket>" to component "<producer>"). Copy the value as it stands, whole or inside a larger string, because the provider writes in its place what the value becomes in the other output, and branch on a value of the component’s own instead(模板对从跨边界链接读取的值所做的不只是复制:消息列出模板、provides 键、通过某个插座上的连接读取该键的消费方组件,以及生产方组件。请按原样复制该值,完整写出或放在更长的字符串中,因为 provider 会在其位置写入该值在另一个输出中的形式;请改为基于组件自身的值进行分支)

**修复方法:**复制消息指出的值,而不是对其进行测试或转换,并基于消费方 component 自己编写的值(它自身的某个 values 或 infra 键)作出判断,而不是基于其连接读取到的值。CloudFormation provider 说明了被复制的值在另一个栈中会变成什么。

A provider named a directory for a contributor that is not one directory(provider 为贡献者指定的目录不是单个目录)

如果 provider 将每个贡献者放在同一个外层输出内各自的位置下,它会声明这些位置所在的目录,构建再将每个组件的标识组合进去。该值必须恰好指定一个目录:带有路径分隔符的值,或指向当前目录或父目录的值,会把组件的文件放到其自身位置之外的地方:要么完全在组装之外,要么在组装内部被悄然重新排列。

构建停止,而不会组合这样的路径。消息会指出声明该值的 provider 以及该值本身,因此可以清楚地知道要修改哪个 provider 以及它声明了什么。

**未声明此类目录的 provider 不受影响。**此时每个贡献者以自己的名称直接位于部署目录下,因此不指定外层目录是一种合理的做法,而不是遗漏。

发出的消息:

provider named a directory for each contributor’s own sub-directory that is not a single directory name: provider "<provider>" declared nest_segment "<value>"; the value must name one directory, carrying no path separator and naming neither the current nor the parent directory(provider 为每个贡献者自身子目录指定的目录不是单个目录名:该值必须指定一个目录,不含路径分隔符,且既不指向当前目录也不指向父目录)

**如何修复:**任何目录文档都不会产生该值,因此你自己的文件中没有需要更正的地方:它来自提供该 provider 的插件。请将其报告给该插件的发布者,并引用消息中指出的值。如果插件是你的,请声明单个目录名,或不声明目录,让每个贡献者直接位于部署目录下。

A boundary-scope Feature is attached only to a component(边界作用域的 Feature 仅附加在组件上)

FeatureRecipe 可以声明它针对一个边界只生成一次,而不是针对每个组件各生成一次:为该边界包含的所有内容生成一个共享资源,而不是每个组件一个。因此,此类附加必须写在边界上:仅针对组件编写的同名附加没有为该 recipe 指定可生成的作用域,于是没有任何东西能决定它在哪个边界运行、读取哪些值,或其输出写到哪里。

**同时在组件上编写它是正常的,不会被报告。**在边界上声明的附加会作用于该边界包含的每个组件,包括嵌套在其中的作用域内的组件,因此组件带有它是正常形态。检查的是组件自身的作用域或某个外层作用域是否声明了该名称:搜索从组件所在位置向外遍历,并在第一个声明了该名称的作用域处停止。组件在自身上重述其外层作用域已声明的附加,渲染结果与仅在作用域上声明的形式完全相同,出于同样的原因也会被接受。

不属于任何作用域的组件没有可遍历的范围,因此其上的边界作用域附加会在此处被报告:这是如实的解读,因为不存在这样的 recipe 可以生成的作用域。

发出的消息,指出附加以及组件所在的作用域:

attachment binds a FeatureRecipe with executionScope: boundary and no boundary holding the component declares it ("<attachment>", on a component in boundary "<boundary>")(附加绑定了 executionScope: boundary 的 FeatureRecipe,但包含该组件的边界均未声明它)

对于不属于任何作用域的组件,不提供此类值:

attachment binds a FeatureRecipe with executionScope: boundary and no boundary holding the component declares it ("<attachment>")(附加绑定了 executionScope: boundary 的 FeatureRecipe,但包含该组件的边界均未声明它)

**如何修复:**在它应当为之生成的边界(组件所在的作用域或某个外层作用域)的 features: 下声明该附加,而不是只在组件上声明。如果你想要的是按组件生成,请改为附加一个其 FeatureRecipe 未声明边界作用域的 Feature。

The sandbox refused a plugin(沙箱拒绝了一个插件)

每个插件在获准执行任何工作之前,都会报告自己是什么以及需要什么,沙箱会将该报告与自己准备授予的权限进行比对。此条件涵盖沙箱不接受的所有报告类别,其消息语句会说明被拒绝的是哪一部分:宿主不支持的插件接口版本、宿主没有对应词汇的插件类型、请求出站网络访问或文件系统访问的插件、指名宿主所提供集合之外的宿主调用或从宿主所允许集合之外的命名空间导入的插件、缺失或格式错误的导出、取值超出其封闭集合的字段,或者完全无法读取的自我报告。

拒绝发生在插件运行之前,被拒绝的插件会在失败传递出去之前被关闭,因此它请求的任何权限都不会被授予,哪怕是短暂的。

插件无法获得的某些能力不在此处检查,因为它们从不被授予。 宿主为 guest 提供一个冻结的时钟,不提供文件系统、不提供环境,其自身的输出也无处可去,因此试图访问其中任何一项的 guest 会在尝试时失败,而不是被预先拒绝。此条件涵盖的是插件关于自身所做的报告,在其启动前进行检查。

发出的消息。 每条消息都以该条件的语句结尾,其前面的部分指明插件及其报告中被拒绝的部分。宿主不支持的接口版本:

plugin "<plugin>" declares abi_version "<declared>"; host speaks "<supported>": wasm: plugin rejected by the sandbox(插件声明的 abi_version 与宿主支持的版本不符:wasm:插件被沙箱拒绝)

宿主没有对应词汇的插件类型:

plugin "<plugin>" declares unknown plugin_type "<declared>": wasm: plugin rejected by the sandbox(插件声明了未知的 plugin_type:wasm:插件被沙箱拒绝)

无法读取的自我报告:

wasm: plugin "<plugin>" describe() output is not valid JSON: <what the read reported>: wasm: plugin rejected by the sandbox(wasm:插件的 describe() 输出不是有效的 JSON:wasm:插件被沙箱拒绝)

缺少其类型所要求导出的插件,该导出取自读取类型本身的同一注册表:

<kind> plugin "<plugin>" declares no "<export>" export: wasm: plugin rejected by the sandbox(插件未声明其类型所要求的导出:wasm:插件被沙箱拒绝)

限定于固定集合的字段携带了其他值——同样的形式也适用于装配模式,以及每个导出的 operates 和 scope 字段:

plugin "<plugin>" export "<export>" declares unknown scope "<declared>" (want "own", "host", or empty): wasm: plugin rejected by the sandbox(插件的导出声明了未知的 scope:wasm:插件被沙箱拒绝)

声明了成对能力却未同时提供两个导出,或提供了导出却未声明该能力:

plugin "<plugin>" declares the cross-boundary linking capability but does not export both "link_publish" and "link_resolve": wasm: plugin rejected by the sandbox(插件声明了跨边界链接能力,但未同时导出 link_publish 和 link_resolve:wasm:插件被沙箱拒绝)

Recipe 永远无法选择的能力名称——提供某个含冒号名称的 provider,或与之兼容的流水线步骤——因为 Recipe 的 capability: 会被解读为最后一个冒号之前的名称加上其后的版本固定。解析器的 parse:<format> 和导入器的 import:<format> 不会被拒绝:冒号是这些名称的一部分,并且它们按格式查找,而不是通过 Recipe。同样的拒绝也会阻止为发布而生成此类插件的实体:

plugin "<plugin>" (plugin_type "provider") serves the capability "<name>", which contains a colon; a Recipe’s capability reference is read as the capability up to its last colon and a version pin after it, so no Recipe can name "<name>": report the capability name without a colon: wasm: plugin rejected by the sandbox(插件提供的能力名称包含冒号;Recipe 的能力引用以最后一个冒号之前的部分作为能力名称、之后的部分作为版本固定,因此任何 Recipe 都无法引用该名称:请报告不含冒号的能力名称:wasm:插件被沙箱拒绝)

以及插件声明的宿主调用与其二进制实际使用的宿主调用不一致,这会双向检查,因此插件既不能宣称自己未使用的接口面,也不能隐藏自己使用的接口面:

plugin "<plugin>" declares host function "<name>" in describe() that its wasm does not import: wasm: plugin rejected by the sandbox(插件在 describe() 中声明了其 wasm 并未导入的宿主函数:wasm:插件被沙箱拒绝) plugin "<plugin>" imports host function "<name>" that its describe() does not declare: wasm: plugin rejected by the sandbox(插件导入了其 describe() 未声明的宿主函数:wasm:插件被沙箱拒绝)

如何修复: 你的实体文件不会导致此问题,任何编写上的修改也无法消除它——被拒绝的是插件自己的报告。如果你使用的是已发布的插件,请将该消息报告给插件的发布者,并在此期间选择宿主接受的版本。如果插件是你自己的,消息会指明字段及两个值,因此修正就是该语句所指向的内容:使用宿主支持的接口版本,声明宿主已知的类型,让每个字段保持在其封闭集合之内,声明你的类型所要求的导出,并准确声明你的二进制所使用的宿主调用——不多也不少。

A plugin is not the kind of plugin the socket expects(插件不是插槽所期望的插件类型)

每个挂接点都声明它分派到哪种类型的插件,而每个插件都会报告自己的类型。此条件报告的就是两者之间的不一致:一个服务于 provider 的插件被挂接到期望 linter 的位置,一个解析器被挂接到期望导入器的位置,一个不是终端命令的插件被当作终端命令运行。检查在插件加载时进行,因此类型错误的插件永远不会触及它本将被要求执行的工作。

之所以停止而不是继续尝试,是因为各类型不共享接口。另一种类型的插件会通过它并不具备的导出被调用,而返回的内容会按照它从未产生过的形态来读取。

在不断言类型的情况下读取插件的自我报告不受影响。 只想了解插件如何描述自身的接口面——列出已配置的内容、为某个插件生成实体——不声明任何期望,因此此处会跳过该检查。

发出的消息,指明插件和两种类型,期望的类型既以文字给出,也以其声明值给出:

wasm: plugin "<plugin>": expected a <kind in words> plugin (plugin type "<expected>") but its describe() reports plugin type "<reported>": wasm: declared plugin type does not match plugin describe()(wasm:插件类型与预期不符,其 describe() 报告了另一种插件类型:wasm:声明的插件类型与插件的 describe() 不匹配)

如何修复: 挂接一个属于该挂接点所接受类型的插件——消息会指明期望的类型。如果插件正是你想要的那个,那么挂接位置有误:将其移到其类型所属的接口面。如果插件由你编写且它本应是期望的类型,那么它报告了错误的自身类型,这需要在插件中修正,而不是在挂接它的配置中修正。

A plugin failed while it was running(插件在运行时失败)

被要求执行某项工作的插件没有返回结果。有三种情况涵盖这一点,它们之间的区别仅在于失败的传递方式:插件崩溃、插件自行停止执行,以及插件运行到结束并报告无法完成所要求的工作。它们被有意归为同一分类,使构建以相同方式对待插件可能失败的每一种方式。

插件崩溃。 插件内部的大多数故障(不可达指令、除以零、越出其内存的读取)在返回途中会被转换为普通失败,永远不会到达这一情况。这一情况是该路径背后的兜底,用于捕获逃逸出该路径的崩溃。

插件自行停止执行。 请求退出的插件所做的事情在插件模型中没有用途:插件通过调用它的那次调用返回结果,而不是通过退出。停止的只是它自身的执行;构建进程不受影响。

插件报告了失败。 插件返回的结果信封中有一个位置,供它声明自己无法完成;表明这一点的消息会作为失败传递,而不会被当作结果读取。

输出的消息,每条都指明插件或导出,并携带失败所提供的任何内容。崩溃携带恢复出的值:

wasm: guest plugin "<plugin>" panicked in <export>: <the recovered value>: wasm: guest plugin panicked during call(wasm:guest 插件在所调用的导出中发生 panic,并附上恢复的值:wasm:guest 插件在调用期间发生 panic)

自行停止的插件携带其停止时的代码:

wasm: plugin "<plugin>" call to <export> invoked proc_exit(<code>): wasm: plugin invoked proc_exit(wasm:插件在调用导出时以给定的退出码调用了 proc_exit:wasm:插件调用了 proc_exit)

报告的失败则携带插件自己的消息:

call "<export>": wasm: guest plugin reported an error: <the plugin's message>(调用该导出:wasm:guest 插件报告了错误,并附上插件自身的消息)

如何修复: 这三种情况都不是由你的实体文件引起的,也没有任何编写上的修改能消除它们,每一种都是插件内部的故障。将消息报告给插件的发布者,指明消息所标识的导出,并在修复期间将插件固定到一个可正常工作的版本。如果插件是你自己的:通过结果信封返回失败,而不是崩溃或退出,使构建获得一条可以展示的消息;如果报告的失败是插件经过考虑后的回答,那么它的消息就是读者将看到的内容,因此值得说明它无法接受输入中的哪一部分。

A plugin returned something that is not the shape the socket reads(插件返回的内容不是插槽所读取的结构)

每个挂接点都会按照它所期望的结构读取返回的结果,并拒绝其他任何内容:结构未声明的字段、值不是为其声明的类型的字段,或者根本不是格式正确的结果的字节。

它选择拒绝,而不是读取能读取的部分,原因在于读取能读取的部分是静默的。 挂接调用哪个导出可以按挂接选择,因此一个挂接可能指向一个结果结构完全不同的导出。跳过不匹配的部分会得到一个空结果,而空结果本身就是合法的回答:没有返回裁决,没有提出发现。两者将无法区分,构建会像插件已经批准了它一样继续进行。

输出的消息指明结果来自哪个导出,并携带读取失败的原因,两者结合起来可以确定该挂接本应指向的导出:

call "<export>": wasm: guest plugin returned an output that is not the shape the socket reads: <what could not be read>(调用该导出:wasm:guest 插件返回的输出不是插槽所读取的结构,并附上无法读取的内容)

如何修复: 将挂接指定的入口函数与插件声明的导出进行核对,挂接指向错误的导出是常见原因,消息中的原因会指明不该出现的字段。如果导出是正确的,那么插件返回的是挂接点不读取的结构,需要在插件中修正;请将其报告给插件的发布者,同时引用导出和原因。

A plugin returned a diagnostic at a severity that is not declared(插件返回的诊断使用了未声明的严重级别)

插件可以在结果之外返回观察项,每个观察项都带有一个来自封闭集合的严重级别:一种会停止构建并指明需要修复的内容,一种会在仍然完成的构建旁边显示,还有一种只记录观察项而不改变任何东西。超出该集合的严重级别是宿主没有处理路径的级别,构建会停止。

它选择拒绝,而不是自行选择处理路径,因为两种替代方案都更糟。 忽略一个无法路由的观察项相当于把它当作无需处理,而在插件决定是否接受构建的场合,这就等同于批准:插件提出的异议会让构建通过,却从未被展示。把它当作停止级别,则会因为一个没有人选择的值而拒绝构建。两者都是静默的,因此宿主会指出该值有误,由插件进行修正。

该检查只在读取结果时运行一次,而不是在之后每个展示观察项的地方运行;这也是唯一仍然掌握插件身份的时刻,因为合并进报告的观察项已不再知道是哪个插件提出的。

输出的消息指明插件、导出、出错的观察项、其值以及已声明的值:

plugin "<plugin>" call "<export>": wasm: guest plugin returned a diagnostic whose severity the contract does not declare: diagnostic <index> has severity "<value>"; the declared severities are "halt", "warn" and "info"(插件调用该导出:wasm:guest 插件返回的诊断的严重级别未在契约中声明:给出该诊断的索引及其严重级别;已声明的严重级别为 halt、warn 和 info)

如何修复: 这不是由你的实体文件引起的,该值来自插件。请将其报告给插件的发布者,并引用消息中指明的值。如果插件是你自己的,请输出三种已声明严重级别之一;消息会列出它们,索引会告诉你应查看哪个观察项。

A provider returned two output files under one path(提供者在同一路径下返回了两个输出文件)

提供者以文件列表的形式返回输出,每个文件都指明其写入路径。宿主按路径收集这些文件,并原样写入每个文件的字节,不运行自己的任何序列化器。两个文件指明同一路径,会使该集合中一个键对应两个值。

它选择拒绝,而不是任选其一,因为事后无法区分这两种选择。 保留最后一个会丢弃提供者要求写入的一个文件;保留第一个则会丢弃后面的那个。无论哪种方式,磁盘上的输出都格式正确但少了一个文件,且没有任何记录表明有文件被丢弃;而保留下来的路径本来就会保留,因此结果中没有任何迹象表明发生过冲突。本意是哪一个,只有提供者才能回答。

凡是提供者返回文件的地方都会触发该情况:渲染单个节点时,以及将一个分派组的输出组装为一个制品时。两处的情况和修复方法相同,因此都会报告它。

输出的消息指明被返回两次的路径,以及返回该路径所针对的节点或分派路径:

provider guest returned two output files under one path; a conforming guest returns each output path at most once (path "<path>", node "<node>")(provider guest 在同一路径下返回了两个输出文件;符合规范的 guest 对每个输出路径最多返回一次,并给出该路径和节点)

如何修复: 这不是由你的实体文件引起的,路径来自提供者。请将其报告给提供者的发布者,并引用消息中指明的路径。如果提供者是你自己的,请确保每个输出路径最多返回一次:用集合来构建路径列表,使同一路径上的第二个文件在产生时就被发现;如果两个文件都需要,请为第二个文件指定不同的路径。

A provider reported a render fact whose value is not a list(provider 报告的渲染事实的值不是列表)

provider 可以在其文件之外报告关于其渲染输出的事实——每个事实包含一个名称和一个值,使用该 provider 自己文档中定义的词汇——挂接到 component 上的 Features 会在其模板中读取这些事实。每个事实的值都是一个列表,即使只有一个条目:同一个名称可能由 component 的多次渲染报告,包括其自身 provider 的调用以及挂接到它的 Features 的渲染,这些列表会在该名称下合并为一个,供读取它的模板使用。provider 在渲染时无法知道自己的报告是否会是该名称下唯一的一个,因此值为对象、字符串、数字、布尔值或 null 时,会在 provider 交出它时被拒绝,对每次渲染都如此,无论是否有模板读取该事实。

输出的消息,指明该事实、报告它所针对的节点、报告它的 provider,以及值的类型:

provider guest reported a render fact whose value is not a list; a conforming guest reports every render fact’s value as a JSON array, even with one entry (fact "<fact>", node "<node>", provider "<provider>", its value is <kind>)(provider guest 报告的渲染事实的值不是列表;符合规范的 guest 会将每个渲染事实的值报告为 JSON 数组,即使只有一个条目)

**如何修复:**你的实体文件中没有任何内容会导致此问题——该值来自 provider。请将其报告给该 provider 的发布者,并引用消息中指明的事实。如果 provider 是你自己的,请将该事实的值报告为 JSON 数组——单个对象变为包含该对象的列表——并在你的 provider 所报告的事实文档中将其记为列表;参见报告 guest 输出内容的相关事实。

当一个连接跨越两个分发组时,会请求两侧的 provider 进行连线:被消费端发布一个标识,消费端据此进行解析,并且每一端都可以返回要应用于其所在组输出的结构化连线。每段连线都指明其所应用的输出文件。随后的一轮处理会切分该文件、应用这些操作,并以字节保真的方式重新组装它。

**名称不匹配任何已输出文件时,该轮处理就没有可切分的内容,此时它会拒绝,而不是跳过该连线。**连线携带的操作正是解析该连接的手段,因此丢弃它们会使组装后的输出引用一个无人连线的端点——这会在部署时失败,远离导致问题的 provider,而且看起来像是连接本身的错误,而不是连线的错误。

一段连线可以指明的文件,就是该组自身渲染所返回的文件。这些文件会在同一次调用中交给 provider,因此 provider 无需猜测名称:它从所给的集合中选择一个即可。

输出的消息,指明连线所请求的文件以及返回该连线所针对的端点:

link patch names an output file the dispatch group did not emit; a conforming link patch names a file the group’s own render returned (file "<file>", node "<node>")(link patch 指定了一个分派组未输出的输出文件;符合规范的 link patch 指定的是该组自身渲染返回的文件)

**如何修复:**你的实体文件中没有任何内容会导致此问题——该名称来自 provider。请将其报告给该 provider 的发布者,并引用消息中指明的文件。如果 provider 是你自己的,请从调用交给你的已组装文件中选取文件名,而不是使用独立构造的名称——手工拼出的路径会在生成它的渲染发生变化时立即失效,而这正是其表现。

A pipeline step’s file emission carries no file(流水线步骤的文件输出未携带文件)

流水线步骤可以在其修补的文档之外输出新文档。每项输出都声明其类型,文件类型的输出会携带它要写入的文件:路径和内容。

这里类型正确而文件缺失,因此该步骤声明了一个其回复并未执行的意图。这正是它与下文未定义类型中止的区别:宿主完全知道如何处理 emit_file 输出,却没有可处理的对象。

**它会拒绝,而不是什么都不输出,因为悄悄地不贡献任何文件的输出是不可见的。**输出文档的步骤往往就是它出现在流水线中的全部理由,其输出是一个此前不存在的文件——因此跳过它的构建会产生缺少一个文档的输出,而该步骤却报告自己已运行。

输出的消息,指明节点以及该步骤的哪一项输出有问题:

emit_file side effect carries no file; a conforming emit_file side effect carries a file with its path and content (node "<node>", side effect <index>)(emit_file 副作用未携带文件;符合规范的 emit_file 副作用会携带一个包含路径和内容的文件)

**如何修复:**你的实体文件中没有任何内容会导致此问题——该回复来自插件。请将其报告给该插件的发布者,并引用消息中指明的索引。如果插件是你自己的,请在每个 emit_file 输出上填写 file 成员,同时包含路径和内容;索引指明应查看该步骤回复中的哪一项输出。

A pipeline step declares an emission kind the contract does not define(流水线步骤声明了契约未定义的输出类型)

流水线步骤返回的每项输出都声明其类型,契约定义了两种:一种写入文件,一种贡献自定义资源文档。类型在传输中是开放字符串,这使得以后可以添加新类型而不破坏现有插件。

**正是这种开放性,使未定义的类型会被拒绝而不是被跳过。**仅凭形状,宿主无法区分一个它未定义的值和一个将来版本会定义的值——因此跳过它的宿主会在每次构建中悄悄丢弃该步骤想要表达的内容,而该步骤却报告成功。拒绝使扩展点保持开放而不成为漏洞:本次构建未定义的类型会被报告为未定义,并引用步骤发送的值,而不是被接受后忽略。

输出的消息,指明节点、哪一项输出有问题以及它声明的类型:

side effect declares a kind the plugin contract does not define; a conforming side effect declares emit_file or emit_crd (node "<node>", side effect <index>, kind "<value>")(副作用声明了插件契约未定义的种类;符合规范的副作用声明 emit_file 或 emit_crd)

**如何修复:**你的实体文件中没有任何内容会导致此问题——该值来自插件。请将其报告给该插件的发布者,并引用消息中指明的类型。如果插件是你自己的,请声明消息所列的类型之一;常见原因是已定义类型的拼写错误,消息中回显的值就是你发送的值。

A provider’s reassembly is handed a unit its own carve never produced(provider 的重组收到了其自身切分从未产生的单元)

输出结构无法直接寻址的 provider 可以自行切分:它把一个输出文件拆分为可寻址的单元,每个单元对应一个令牌,然后交回。随后流水线步骤通过该令牌寻址某个单元,重组则把编辑后的单元按字节保真地拼接回文件。这两半是同一个契约——文件切分时使用的令牌,就是其重组时解析的令牌。

当重组收到的令牌并非由同一文件的切分产生时,编辑后的内容就没有可放回的字节范围。 它会拒绝,而不是丢弃该单元,因为丢弃单元会产生一个格式正确却缺少某个步骤被要求进行的编辑的文件:没有任何失败,没有任何格式错误,只是编辑不见了。

只有当两半被拆开时它们才可能不一致——即一个编解码器自行切分,而其余部分借用标准的结构化重组。此时按一组令牌切分、却按另一组令牌重组,就会恰好产生这种情况。同时拥有两半的编解码器不会遇到它:它自己的重组负责它自己的令牌。

输出的消息,指明未解析到任何内容的令牌及其所针对的文件:

reassemble names a patched unit token the carve did not produce; a conforming codec carves and reassembles a file under the same tokens (token "<token>", file "<file>")(reassemble 指定了 carve 未产生的已修补单元 token;符合规范的 codec 会在相同的 token 下切分并重组文件)

如何修复: 这并非由你的实体文件引起。如果该 provider 是你的,请让一半产生的令牌正是另一半解析的令牌:只派生一次并传递下去,而不是在两侧各自独立派生;如果切分在拆分前会重写文件,请针对同样重写后的形式进行重组。如果该 provider 不是你的,请向其发布者报告,并引用消息中指明的令牌。

A workload declares a form compose cannot express(workload 声明了 compose 无法表达的形式)

compose provider 渲染长期运行的服务。声明每台机器运行一个副本、按计划运行或运行一次即结束的 workload,没有干净的单机等价形式,因此渲染会停止,而不是输出一个普通服务——那样会启动它、保持其运行,并歪曲所请求的内容。

输出的消息。条件指明失败的类型——provider 无法表达构建所声明的某项内容——而 provider 自己的句子指明它收到的形式:

a plugin has no expression for a construct this build declares(插件无法表达此次构建所声明的构造) compose: workload form "<form>" has no compose mapping; compose supports stateless and stateful only: compose cannot express this workload form(compose:该 workload 形式没有 compose 映射;compose 仅支持 stateless 和 stateful:compose 无法表达此 workload 形式)

如何修复: 如果目标确实是单机 compose 环境,请把这项工作表达为长期运行的服务——stateless 和 stateful 形式是它渲染的两种形式。如果该形式正是你的本意,请通过目标具有等价形式的 provider 渲染该边界:每机一个副本、计划运行和运行至完成的作业在其他地方都有直接的表达,而 provider 的选择属于边界,而不是 workload。

A container declares a field compose has no primitive for(容器声明了 compose 没有对应原语的字段)

有两个容器字段没有 compose 等价物,二者都会停止渲染,而不是被丢弃。

在容器启动或即将停止时运行的钩子。 compose 没有任何运行它们的机制,而悄无声息地不运行的钩子是一种正确性意外,会在运行时而非构建时才暴露。

从命名对象获取的批量环境变量。 compose 可以从文件读取变量,但对对象的引用并不是文件——把一个重新解释为另一个,会在不加说明的情况下改变容器得到的内容。

普通容器和在主容器之前运行的容器都会检查这两项,因此同一字段无论在哪里声明都会停止,并且消息会指明它来自哪个容器。

输出的消息。 两者报告同一条件——provider 无法表达构建所声明的某项内容——而 provider 自己的句子说明是哪个字段:

a plugin has no expression for a construct this build declares(插件无法表达此次构建所声明的构造) compose: node "<node>" container "<container>": compose: node "<node>" declares container lifecycle hooks; compose has no lifecycle-hook primitive: compose has no lifecycle-hook primitive; container declares lifecycle hooks(compose:节点、容器:compose:该节点声明了容器生命周期钩子;compose 没有生命周期钩子原语:compose 没有生命周期钩子原语;容器声明了生命周期钩子)

a plugin has no expression for a construct this build declares(插件无法表达此次构建所声明的构造) compose: node "<node>" container "<container>": compose: node "<node>" declares container envFrom; compose has no env-from-object primitive: compose has no env-from-object primitive; container declares envFrom(compose:节点、容器:compose:该节点声明了容器 envFrom;compose 没有 env-from-object 原语:compose 没有 env-from-object 原语;容器声明了 envFrom)

如何修复: 对于 compose 目标,请移除该字段并以其他方式完成其工作——启动工作应放在主容器之前运行的容器中,关闭工作应放在容器自身的信号处理中;批量环境变量可以写成显式变量,或从 compose 目标可读取的文件提供。如果该字段正是你的本意,请通过目标具有该原语的 provider 渲染该边界。

An omits entry names a kind or a namespace a compose file does not have(omits 条目指定了 compose 文件没有的 kind 或 namespace)

在引用 compose 文件的 Recipe 或 FeatureRecipe 上,omits: 条目会省略该文件的一个顶层单元,而 compose 文件中条目可以指定的 kind 恰好有三种——service、volume 和 config,分别以 services:、volumes: 或 configs: 下的键标识——且没有 namespace。指定任何其他 kind(包括 chart 文档的 Secret 或 compose 的 network)或带有 namespace 的条目,所指的内容都不是文件能省略的,因此渲染会停止,而不是把该条目视为未匹配任何内容。kind 按精确匹配比较,因此在本应写 service 的地方写 Service 会被拒绝。在省略任何内容之前会检查每个条目,按条目书写顺序第一个出错的条目就是被指明的那个。

输出的消息。 两者都报告 provider 无法表达某个构造的条件,而 provider 自己的句子指明该条目及其接受的 kind。模板读取了被声明为敏感的值的字段显示为 <redacted>:

a plugin has no expression for a construct this build declares(插件无法表达此次构建所声明的构造) compose: an omits entry (name "<name>") names kind "<kind>": compose leaves out a service, a volume or a config, each named by its key under services:, volumes: or configs:, and no other kind(compose:某个 omits 条目指定了该 kind:compose 只会省略 service、volume 或 config,分别以其在 services:、volumes: 或 configs: 下的键命名,不支持其他 kind)

a plugin has no expression for a construct this build declares(插件无法表达此次构建所声明的构造) compose: an omits entry (kind "<kind>", name "<name>") names namespace "<namespace>", and a compose file has no namespaces: compose leaves out a service, a volume or a config, each named by its key under services:, volumes: or configs:, and no other kind; remove the namespace from the entry(compose:某个 omits 条目指定了 namespace,而 compose 文件没有 namespace:compose 只会省略 service、volume 或 config,分别以其在 services:、volumes: 或 configs: 下的键命名,不支持其他 kind;请从该条目中删除 namespace)

如何修复: 按 compose 文件的方式指定单元——kind: service、volume 或 config,name: 为其在对应部分下的键——并去掉 namespace:。参见 compose → 引用模式。

An omits entry names a namespace a CloudFormation template does not have(omits 条目指定了 CloudFormation 模板中不存在的命名空间)

在引入 CloudFormation 模板的 Recipe 或 FeatureRecipe 上,一个 omits: 条目会略去一个资源,该资源以其 Type 作为条目的 kind、以其逻辑 ID 作为条目的 name 来指定。模板没有命名空间,因此带有 namespace 的条目指定的不是模板能够略去的任何内容,渲染会停止,而不是把该条目当作未匹配任何内容的条目处理。在略去任何内容之前会检查每个条目,按条目的书写顺序,第一个带有命名空间的条目会被指出。

**输出的消息。**它报告的是提供者对某个构造没有表达方式这一条件,提供者自己的语句会指出该条目以及此提供者会略去什么。若某字段的模板读取了声明为敏感的值,该字段显示为 <redacted>:

a plugin has no expression for a construct this build declares cloudformation-provider: an omits entry (kind "<kind>", name "<name>") names namespace "<namespace>", and a CloudFormation template has no namespaces: cloudformation leaves out a resource, named by its Type as the entry’s kind and its logical ID under Resources as the entry’s name; remove the namespace from the entry

**如何修复:**从条目中删除 namespace:,条目仅凭资源的 Type 和逻辑 ID 来指定资源。参见 cloudformation → 从引入的模板中略去资源。

A published port declares a transport compose cannot spell(发布的端口声明了 compose 无法表示的传输协议)

compose 中发布的端口以条目上的后缀表示其传输协议,该后缀有两种写法。声明其他任何传输协议的端口在 compose 中都没有对应写法。

它会停止,而不是丢弃该后缀,因为一个悄然回退到默认传输协议的发布端口在启动后承载的流量是其客户端无法到达的——这恰恰是声明传输协议所要防止的故障,却在转换时被重新引入。

**未声明传输协议的端口不受影响。**它不带后缀发布,与从未带有传输协议的端口完全相同。

输出的消息。条件指出故障的类型——某个值在提供者输出的内容中没有表示形式——其后是提供者自己的语句:

a plugin has no representation for a value it was given compose: node "<node>" apply service ports: compose publishes a port’s transport as a tcp or udp suffix; this port declares a transport compose cannot express

**如何修复:**对于 compose 目标,将端口的传输协议声明为 compose 能表示的两种之一,或不声明,让条目不带后缀发布。若该传输协议正是你的本意,请通过目标能够表达它的提供者来渲染该边界。

A resources quantity cannot be converted to a compose value(资源数量无法转换为 compose 值)

容器的处理器和内存数量,以及其 nvidia.com/gpu 数量,均以 Kubernetes 表示资源的记法书写,而 compose 以自己的单位承载它们——GPU 数量会变为 NVIDIA 设备预留的数量——因此每一项都按数量读取,并根据其值转换。有两种情况会阻止这一过程,消息会说明遇到的是哪一种:根本不是数量的值,以及 compose 没有精确形式的数量——负数、不是整数字节的内存量、精度超过核心九位小数的处理器量、不是整数个设备的 GPU 数量,或超出 compose 能容纳的最大值的量。若容器的 nvidia.com/gpu 请求和限制要求不同的数量,也会停止,因为 compose 为一个服务只预留一个数量。它会停止,而不是对值取整或输出近似值,因为一个悄然与所要求的限制不同的限制,正是那种在某个东西因超出它而被停止之前无人察觉的差异。

**输出的消息。**每条消息都以条件开头——某个值在提供者输出的内容中没有表示形式——然后指出资源、该值是请求还是限制、它在 Workload 中的路径以及该值。对于不是数量的值,其后会说明它为何不是数量,以及数量应采用的形式:

a plugin has no representation for a value it was given compose: node "<node>" container "<container>": compose: the <cpu|memory|nvidia.com/gpu> <request|limit> at <path>: "<value>" is not a quantity: <reason>; a quantity is a number such as 2, 0.5 or 1.5, with an optional sign and at most one of an integer exponent (1e3, 5E-2) or a unit suffix (n, u, m, k, M, G, T, P, E, Ki, Mi, Gi, Ti, Pi, Ei): resources quantity cannot be converted to a compose deploy.resources value

对于 compose 无法表示的数量,其后会给出 compose 对该资源所能容纳的范围:

a plugin has no representation for a value it was given compose: node "<node>" container "<container>": compose: the memory <request|limit> at <path> is "<value>", a quantity compose cannot represent exactly; a compose memory value is a whole number of bytes from 0 to 9223372036854775807: resources quantity cannot be converted to a compose deploy.resources value

a plugin has no representation for a value it was given compose: node "<node>" container "<container>": compose: the cpu <request|limit> at <path> is "<value>", a quantity compose cannot represent exactly; a compose cpus value is a core count from 0 to 9223372036.854775807 with at most nine decimal places: resources quantity cannot be converted to a compose deploy.resources value

a plugin has no representation for a value it was given compose: node "<node>" container "<container>": compose: the nvidia.com/gpu <request|limit> at <path> is "<value>", a quantity compose cannot represent exactly; a compose device count is a whole number of devices from 0 to 9223372036854775807: resources quantity cannot be converted to a compose deploy.resources value

GPU 请求和限制要求不同数量时,消息会指出两个路径和两个数量:

a plugin has no representation for a value it was given compose: node "<node>" container "<container>": compose: the nvidia.com/gpu request at <path> and the limit at <path> ask for different counts (<request> and <limit>); compose reserves one device count for a service, so write the same count in both or only the limit: resources quantity cannot be converted to a compose deploy.resources value

若 Workload 的模板读取了作者声明为敏感的值,任何消息都不会引用它所拒绝的值,两个数量也会以同样方式省略。

**如何修复:**若该值不是数量,请按 Workload → 资源数量中所述的形式书写;像 m 这样的单独后缀,是模板所插入的值为空时留下的结果,因此需要修复的是模板读取的输入。若它是 compose 无法表示的数量,请写一个在消息所述范围内的量——内存以任意单位写成整数字节(用 1536Mi 而不是 1.5001Gi),处理器时间最多精确到核心的九位小数,GPU 数量写成整数个设备(1,而不是 0.5 或 500m)。若 GPU 请求和限制不一致,请在两者中写相同的数量,或只写限制,这也是 Kubernetes 为同一 Workload 调度的数量。

A resource quantity the helm provider emits is not a quantity(helm provider 输出的资源数量不是数量)

helm provider 会将每个资源数量原样复制到它输出的清单中——每个容器和 init 容器的 resources.requests 与 resources.limits 值(包括扩展资源),以及每个卷的 ephemeral.sizeLimit、persistent.size 和 persistentTemplate.size——并先按 Recipe 的模板求值后的 Workload,逐一对照数量格式检查。不符合该格式的值会在此处中止构建;否则构建会顺利完成,却在安装 chart 时被集群拒绝。

输出消息。 消息以该条件开头,然后给出节点、字段在 Workload 中的路径、值以及它不是数量的原因,并说明数量应采用的格式:

a plugin has no representation for a value it was given helm: node "<node>": <path>: "<value>" is not a quantity: <reason>; a quantity is a number such as 2, 0.5 or 1.5, with an optional sign and at most one of an integer exponent (1e3, 5E-2) or a unit suffix (n, u, m, k, M, G, T, P, E, Ki, Mi, Gi, Ti, Pi, Ei)

修复方法: 按 Workload → 资源数量 中规定的格式写入该值。若字段使用了模板,需要修复的是模板读取的值:像 m 或 Mi 这样单独的后缀,是模板插入的值为空时留下的结果;而 Release 参数会按其原样传到该字段。

A service type the helm provider cannot render(helm provider 无法渲染的服务类型)

helm provider 将每个 Workload services 条目渲染为一个 Kubernetes Service,其类型为该条目的 type。Loopback 条目要求其端口只能从主机自身的回环地址访问,而 Kubernetes Service 没有能做到这一点的类型:NodePort Service 在哪些节点地址上监听,是整个集群的设置,而不是单个 Service 的设置。因此构建会在写入任何资源之前,于第一个 Loopback 条目处停止(按服务声明的顺序)。

构建会停止,而不是将该条目渲染为其他类型,因为 Service 现有的每种类型都会改变端口的可达范围:ClusterIP Service 会丢掉条目所要求的对外发布,而 NodePort Service 会在集群允许的每个节点地址上发布该端口——这正是该条目要避免的更大暴露面。

输出消息。 消息以该条件开头,然后给出节点、服务在 Workload 中的路径以及类型:

a plugin has no representation for a value it was given helm: node "<node>": services.<service>: type “Loopback” publishes the service’s ports on the host’s loopback address only, and a Kubernetes Service has no type that does; declare ClusterIP to keep the ports inside the cluster, or NodePort or LoadBalancer to publish them outside it

修复方法: 对于 helm 目标,声明能说明端口在集群中可达范围的类型——ClusterIP 将其保留在集群内,NodePort 或 LoadBalancer 将其发布出去。Loopback 条目用于 compose 目标,它会在 127.0.0.1 上发布端口;参见 Workload → services。

A Kubernetes version the helm provider cannot render a chart for(helm provider 无法为其渲染 chart 的 Kubernetes 版本)

helm provider 从源码渲染 chart 时,使用组件或其边界上 aggrega.ai/kubernetes-version 注解所指定的 Kubernetes 版本,并以 helm template --kube-version 读取其标志的方式读取该值。该标志会拒绝的值——"one.two"、"latest"、像 "1" 这样的单个数字、像 "01.20" 这样带前导零的数字——无法提供可供 chart 以 .Capabilities.KubeVersion 读取的版本,因此构建会在渲染 chart 之前停止。

构建会停止,而不是按默认版本渲染 chart,因为 chart 会读取版本来选择 API 版本、字段乃至整个机制;为非你所指定的版本渲染的 chart 会输出适用于那个版本的结构——而它所部署到的集群可能无法运行该结构。

空值不会被拒绝。 它被视为未设置,chart 按默认版本渲染:即同一 helm 发行版的原生 helm template 所渲染的版本。

输出消息。 消息以该条件开头,然后给出节点及其所在的边界、注解、值以及它不是版本的原因,并说明应写入的格式:

a plugin has no representation for a value it was given helm: node "<node>" in boundary "<boundary>": annotation aggrega.ai/kubernetes-version: "<value>" is not a Kubernetes version a chart can be rendered for: <reason>; write the version of the cluster the chart deploys to, such as “1.31” or “v1.31.2”, on the component or on its boundary

消息同时给出节点及其边界,因为 provider 会一并读取组件的注解和其边界的注解,以组件自身的值为准,所以该值可能写在其中任意一处。

修复方法: 在组件或其边界上写入 chart 所部署到的集群的版本——主版本加次版本,如 "1.31",或完整版本,如 "v1.31.2"——或者删除该注解,按默认版本渲染。参见 helm → 渲染 chart 所用的 Kubernetes 版本。

A health probe cannot be turned into a compose healthcheck(健康探针无法转换为 compose healthcheck)

声明的健康探针会转换为 compose healthcheck,有两种情况会阻止这一转换。

在未发布任何端口的容器上,通过 HTTP 检查路径的探针。 该检查被构建为对容器某个端口的请求,因此没有声明端口时,就没有可以构建检查的地址。

完全没有声明检查方式的探针——既没有路径,也没有要连接的端口,也没有要运行的命令。没有可以转换为检查的内容。这是 schema 之后的一道防护,而不是你可能会写出的结构:探针在到达此处之前,就已检查是否具备这三者之一。

输出消息。 两者报告同一条件——provider 需要的某项内容无法解析为恰好一个值——并由 provider 自己的语句说明是哪一种:

a plugin could not resolve something it requires to exactly one value compose: node "<node>" container "<container>": probe http: requires at least one container port; container declares none

a plugin could not resolve something it requires to exactly one value compose: node "<node>" container "<container>": probe declares no shape (http/tcp/exec)

修复方法: 在探针所在的同一容器上声明检查所针对的端口——HTTP 探针读取第一个容器端口,因此必须存在该端口才能构建检查。若容器确实不发布任何端口,请换一种方式检查:运行命令的探针不需要端口。对于未声明检查方式的探针,为其指定三者之一。

A configmap volume has no file behind it(configmap 卷背后没有文件)

挂载配置的卷通过 compose 自身的相应机制交付,按名称引用,而保存内容的条目来自 Recipe 输出的文件。引用找不到匹配条目时报告的就是这一状况:文件不存在,因此挂载点背后没有任何内容,容器启动时读取的将是一个空路径。

该检查针对整个组装后的输出运行,而不是按 component 逐个运行,这是有意为之:引用和保存内容的条目经由不同途径到达,并且可能来自同一组中的不同 component,因此组装后的输出是两者同时存在的第一个时点。按 component 检查会拒绝一个由同组另一个 component 提供内容的引用。

报告的是所有未解析的引用,而不只是第一个,并且顺序稳定,因此一次构建就能列出全部引用。

输出的消息。先给出状况,然后是每个 service、它所做的引用以及其挂载位置:

a plugin could not resolve something it requires to exactly one value(插件无法将其所需的某项解析为唯一值) compose AssembleBoundary: service "<service>" references config "<name>" mounted at "<path>"; declare each one as a top-level configs: entry from the Recipe’s artifacts: input: configmap volume requires a file emitted via the Recipe’s artifacts: input; none found

**修复方法:**从 Recipe 的 artifacts: 输入中,以卷所引用的名称输出该文件——两者按该名称匹配,因此卷所请求的与 Recipe 输出的不一致是常见原因。如果内容本应来自其他地方,卷就不是合适的机制:属于环境变量的值应放到环境中。

What an omits entry left out is still named by the compose file(omits 条目省略的内容仍被 compose 文件引用)

omits: 条目会从来源 compose 文件中省略某个 service、volume 或 config,而 compose 会拒绝引用了未声明对象的文件。因此,在移除条目对应的单元后,文件其余部分对其中任一单元的每个引用都会停止渲染:由 depends_on、links、volumes_from、extends、build.additional_contexts 值或 service: 网络、IPC、PID、UTS 模式引用的 service;作为 volumes: 条目来源引用的 volume;由 configs: 条目引用的 config——在每个 service、每个 service 的 pre_start 钩子以及每个 job 中读取。完整列表以及只是看起来像引用的值,见 compose → Sourced mode。

该检查读取声明该条目的 Recipe 或 FeatureRecipe 自身的文件,因此即使同一组装文件的另一个贡献者声明了与被省略单元同名的单元,渲染仍会停止。报告的是所有引用,而不只是第一个——先按键顺序列出 services,然后是 jobs,每个 service 的钩子紧随其后——因此一次构建就能列出全部引用。

输出的消息。先给出状况,然后是每个引用方条目、它引用的单元以及引用所在的字段:

a plugin could not resolve something it requires to exactly one value(插件无法将其所需的某项解析为唯一值) compose: what an omits entry left out is still named by the file: service "<service>" names <kind> "<name>" at <field>; compose refuses a file naming a service, a volume or a config it does not declare: leave out what names it as well, change the reference through valuesMapping, or remove the entry

若某单元条目的名称由声明为敏感的值构建,则显示为 <redacted>。

**修复方法:**确定你本意是两者中的哪一种。如果引用方 service 仍需要该单元,就保留它:移除该条目。如果不需要,通过 Recipe 的 valuesMapping: 修改引用——其中的列表会替换基础文件的列表,因此 depends_on: [] 可将其清空——或用单独的条目将引用方 service 也省略掉。

What an omits entry left out is still named by a CloudFormation template(omits 条目省略的内容仍被 CloudFormation 模板引用)

omits: 条目会从来源 CloudFormation 模板中省略某个资源,而 CloudFormation 会拒绝引用了未声明资源的模板。因此,在移除条目对应的资源后,其余模板对其中任一资源的每个引用都会停止渲染:Ref、列表形式或点分字符串形式的 Fn::GetAtt、资源的 DependsOn,或 Fn::Sub 的变量——在每个资源的主体和每个输出中的任何位置读取。完整列表以及只是看起来像引用的值,见 cloudformation → Leaving resources out of a sourced template。

该检查一并读取声明该条目的 Recipe 或 FeatureRecipe 自身的模板:对这些模板中另一个仍在声明的逻辑 ID 的引用不会被停止,而对被省略资源的引用即使在另一个 component 声明了该逻辑 ID 的资源时也会停止渲染。报告的是所有引用,而不只是第一个——按来源中模板的顺序逐个模板,每个模板先资源后输出,均按键顺序——因此一次构建就能列出全部引用。

输出的消息。先给出状况,然后是每个引用:所在模板、引用的资源、引用方式,以及以模板根开始的路径表示的位置:

a plugin could not resolve something it requires to exactly one value(插件无法将其所需的某项解析为唯一值) cloudformation-provider: what an omits entry left out is still named by the source’s templates: template "<template>" names resource "<logical-id>" (type "<type>") by <Ref|Fn::GetAtt|DependsOn|Fn::Sub> at <path>; CloudFormation refuses a template naming a resource it does not declare: leave out what names it as well, or remove the entry

若条目的字段由声明为敏感的值构建,其资源的逻辑 ID 和类型显示为 <redacted>,路径中拼出该逻辑 ID 的任何一步也同样如此。

**修复方法:**确定你本意是两者中的哪一种。如果引用方资源仍需要被省略的资源,就保留它:移除该条目。如果不需要,用单独的条目将引用方资源也省略掉——绑定到参数的值只替换对该参数的引用,因此无法用它修改对资源的引用。引用该资源的输出无法被省略,因此被输出引用的资源会保留。

A valuesMapping key names no parameter of a sourced CloudFormation template(valuesMapping 键未对应来源 CloudFormation 模板的任何参数)

来源 CloudFormation 模板通过其声明的 Parameters 接收值,引入它的 Recipe 或 FeatureRecipe 的 valuesMapping 为其填充的每个参数写一个键。如果某个键对应的参数在来源的任何模板中都未声明,它就无处可去,因此渲染会停止而不是丢弃它——这正是 CloudFormation 自身会针对未知参数报告的失败,只是在你仍能修复时报告。只有 valuesMapping 填充参数:未被映射的值从不以这种方式读取,因此 component 或 attachment 为其他输入编写的自身值不会遇到此问题。

输出的消息。先给出状况,然后是每个未对应任何参数的键,以及来源中每个模板声明的内容:

a plugin could not resolve something it requires to exactly one value(插件无法将其所需的某项解析为唯一值) cloudformation-provider: the Recipe’s or FeatureRecipe’s valuesMapping writes the key "<key>", and no template of the source declares a parameter of that name: template "<template>" declares "<parameter>", …; a sourced template takes values only through the parameters it declares, so rename the key to the parameter it is meant for, or remove it from the valuesMapping

**修复方法:**将该键与消息列出的参数进行比较——拼写错误的键是常见原因——然后重命名它,或将其从 valuesMapping 中移除。参见 cloudformation → Values for a sourced template’s parameters。

另一个组件引用了已由来源模板绑定填充的 CloudFormation 参数

通过来源该模板的 Recipe 或所附加 Feature 的 FeatureRecipe 的 valuesMapping 填充来源模板的参数,会替换该来源每个模板中对它的每一处引用,并移除其声明。此后,同一组装 stack 中来自其他地方的内容——另一个组件的片段或来源模板,或 Feature 所附加组件的片段——如果仍通过 Ref、Fn::Sub 变量或规则的 Fn::ValueOf 引用该参数,就引用了 stack 不再声明的东西,CloudFormation 会在 stack 部署时拒绝,因此组装停止。stack 中某个组件仍声明的名称(作为其自身的参数或资源的逻辑 ID)是 stack 能够解析的引用,不会被停止。

输出的消息。先给出条件,然后是每一处引用:所在的组件和模板、参数,以及其 Recipe 或所附加 FeatureRecipe 的 valuesMapping 填充了它的组件——附加到组件的 Feature 以该组件命名,附加到边界的 Feature 以其资源作为 aggrega.ai/component-id 携带的标识命名,该标识由边界路径和附加名称组成,例如 bfr--stack--aux:

a plugin could not resolve something it requires to exactly one value(插件无法将其所需的某项解析为恰好一个值) cloudformation-provider: a parameter a sourced template’s binding filled is still referenced from elsewhere in the assembled stack: component "<component>"’s template "<template>" references parameter "<parameter>", which the valuesMapping of a Recipe or FeatureRecipe rendering for component "<component>" binds; …; binding a parameter removes its declaration from the source that declares it, and no template in the stack declares it any more, so the reference names nothing CloudFormation can resolve: reference what the binding component publishes instead, declare the parameter in the template that references it, or remove the key from the valuesMapping(来源模板绑定填充的参数仍在组装 stack 的其他地方被引用……绑定参数会从声明它的来源中移除其声明,stack 中已没有模板声明它,因此该引用指向 CloudFormation 无法解析的内容:改为引用绑定组件发布的内容,在引用它的模板中声明该参数,或从 valuesMapping 中移除该键)

**修复方法:**如果引用组件需要该值,让填充它的组件通过 provides 发布它并引用之;或在引用模板中声明该参数,使其取自己的值;或从 valuesMapping 中移除该键,使参数保持声明,每个组件都读取 stack 部署时传入的值。参见 cloudformation → 来源模板参数的值。

绑定到 CloudFormation 参数的值无法采用该参数的类型

绑定到参数的字面量按照 CloudFormation 在 stack 部署时转换为该参数 Type 传入的同一值的方式进行转换。如果不存在这样的转换,渲染停止:绑定到 Number 或 List<Number> 的非数字值,绑定到只取单个值的参数的列表或映射,以及绑定到 AWS::SSM::Parameter::Value<…> 参数的任何字面量(CloudFormation 从 Parameter Store 而非模板读取其值)。绑定到被模板作为 Fn::Sub 变量引用的参数的列表同样会停止渲染,因为变量替换的是一个字符串。

输出的消息。先给出条件,然后是参数、其模板和类型,以及该值为何不匹配;不引用任何值:

a plugin has no representation for a value it was given(插件无法表示所给的值) cloudformation-provider: parameter "<parameter>" of template "<template>" is of type <type>, and <why the value does not fit>(模板的参数属于该类型,且值不匹配的原因)

**修复方法:**绑定符合参数类型的值——对于 Parameter Store 类型,则绑定 {{resolve:ssm:…}} 动态引用或内部函数——或不绑定该参数,改由 stack 部署时传入值。

绑定到 CloudFormation 参数的值被其约束拒绝

绑定到参数的字面量会按照模板为其声明的约束进行检查——AllowedValues、AllowedPattern、MinLength、MaxLength、MinValue 和 MaxValue——这是 CloudFormation 对 stack 部署时传入的值所做的检查,被移到构建时进行,从而填充参数不会移除模板声明的任何检查。内部函数和动态引用留给 CloudFormation 检查,因为其值在 stack 部署前并不存在。

输出的消息。先给出条件,然后是参数、其模板和约束;不引用任何值:

a plugin has no representation for a value it was given(插件无法表示所给的值) cloudformation-provider: the value bound to parameter "<parameter>" of template "<template>" does not satisfy its <constraint>, which CloudFormation would refuse when the stack deploys; bind a value the parameter admits(绑定到模板参数的值不满足其约束,CloudFormation 会在 stack 部署时拒绝;请绑定参数允许的值)

**修复方法:**绑定约束允许的值;模板自身对该参数的声明列出了允许的内容。

绑定到 CloudFormation 参数的机密会被写入模板

绑定到参数的值会写入模板,任何能读取 stack 模板的人都能读到它。对于绑定到模板声明为 NoEcho 的参数的字面量,渲染会停止;如果 Recipe 或 FeatureRecipe 的 valuesMapping 读取了作者声明为敏感的值,则该映射绑定的每个字面量都会使渲染停止,因为其任何输出都无法追溯到其来源值。动态引用和内部函数按原样写入(包括内部函数中的文本),因此映射拼接到 Fn::Sub 字符串中的敏感值会以该文本形式进入模板,只有动态引用能让机密本身不进入模板。

输出的消息。先给出条件,然后是参数以及应改为绑定的内容;不引用任何值。为以下之一:

a plugin has no representation for a value it was given(插件无法表示所给的值) cloudformation-provider: parameter "<parameter>" of template "<template>" is declared NoEcho, and the value bound to it would be written into the template as it stands; bind a dynamic reference ({{resolve:secretsmanager:…}} or {{resolve:ssm-secure:…}}) or an intrinsic function instead, or leave the parameter unbound for a deploy-time value(模板的参数声明为 NoEcho,绑定到它的值会原样写入模板;请改为绑定动态引用或内部函数,或不绑定该参数以使用部署时的值)

cloudformation-provider: the Recipe’s or FeatureRecipe’s valuesMapping reads a value declared sensitive, so a literal it produces is refused, and binding parameter(s) "<parameter>", … would write a literal into the template as it stands; …(Recipe 或 FeatureRecipe 的 valuesMapping 读取了声明为敏感的值,因此其产生的字面量被拒绝,绑定这些参数会将字面量原样写入模板;……)

**修复方法:**将机密存储在 Secrets Manager 中或作为 Parameter Store 安全字符串存储,并绑定指向它的动态引用——{{resolve:secretsmanager:<secret>}} 或 {{resolve:ssm-secure:<name>}}——而不是将其拼接到内部函数的文本中;或不绑定该参数,改由 stack 部署时传入值。参见 cloudformation → 来源模板参数的值。

A dynamic reference is bound where CloudFormation does not resolve it(动态引用被绑定到 CloudFormation 不解析它的位置)

CloudFormation 会解析资源属性中的动态引用,但不解析 EC2 用户数据和 AWS::CloudFormation::Init 元数据中的动态引用,并且会将模板的 Outputs 展示给任何读取该堆栈的人。因此,如果某个动态引用绑定到的参数被该来源的任一模板在 UserData 属性、该元数据或其 Outputs 中引用,渲染就会停止,而不是让它到达一个要么无法部署、要么会被暴露的位置。

输出的消息。先是该情况,然后是参数、模板以及该模板引用它的位置;不引用任何值:

a plugin has no representation for a value it was given (插件无法表示给定的某个值) cloudformation-provider: the value bound to parameter "<parameter>" is a dynamic reference, and template "<template>" references the parameter in <where>, where CloudFormation does not resolve a dynamic reference or shows it to whoever reads the stack; bind an intrinsic function instead, or leave the parameter unbound for a deploy-time value (cloudformation-provider:绑定到该参数的值是一个动态引用,而该模板在 CloudFormation 不解析动态引用或会将其展示给任何读取栈的人的位置引用了该参数;请改为绑定一个内部函数,或不绑定该参数以使用部署时传入的值)

**修复方法:**不绑定该参数,在堆栈部署时传入其值;或者绑定一个能产生模板在该处所需内容的内部函数。

A rule reads a bound CloudFormation parameter by name(规则按名称读取已绑定的 CloudFormation 参数)

模板 Rules 中的 Fn::ValueOf 通过逻辑 ID 而非 Ref 指定参数,并读取堆栈部署时为其传入的值。绑定该参数会从该来源的每个模板中移除其声明,这会使规则(无论位于哪个模板中)指向不存在的内容,因此渲染会停止。

输出的消息。先是该情况,然后是规则、其模板和参数:

a plugin has no expression for a construct this build declares (插件无法表达本次构建声明的某个构造) cloudformation-provider: rule "<rule>" of template "<template>" reads parameter "<parameter>" through Fn::ValueOf, which names a declared parameter by its logical ID, and binding the parameter removes its declaration from the source; leave the parameter unbound so the rule can read it at deploy (cloudformation-provider:该模板的规则通过 Fn::ValueOf 读取该参数,Fn::ValueOf 按逻辑 ID 指名一个已声明的参数,而绑定该参数会从来源中移除其声明;请不绑定该参数,以便规则在部署时读取它)

**修复方法:**从 valuesMapping 中移除该参数的键,使参数保持声明状态,规则读取堆栈部署时传入的值。

The assembled CloudFormation stack cannot carry a transform(组装后的 CloudFormation 堆栈无法承载某个转换)

组装后堆栈的 Transform 由每个 component 的转换构建而成,而转换会处理整个模板,因此,效果不局限于为其编写的内容的转换会被拒绝,而不允许它改变另一个 component 的内容的部署方式:AWS::CodeDeployBlueGreen 和 AWS::Include 始终被拒绝;你的账户定义的宏和 AWS::ServiceCatalog 在与任何其他 component 并存时被拒绝;AWS::LanguageExtensions 在与另一个 component 的 serverless 内容并存时被拒绝;AWS::Serverless-2016-10-31 在其 Globals 会影响另一个 component 的 serverless 资源,或其某个事件源指向另一个 component 声明的资源时被拒绝。完整的表格见 cloudformation → 组装后堆栈中的顶级部分。

输出的消息。先是该情况,然后是堆栈中的每个 component、该转换和声明它的 component,以及无法承载的原因:

a plugin has no expression for a construct this build declares (插件无法表达本次构建声明的某个构造) cloudformation-provider: the assembled stack of component "<component>", … cannot carry the transform "<transform>", declared by component "<component>": <why> (cloudformation-provider:由这些组件组装的栈无法承载该组件声明的 transform,原因如上)

**修复方法:**将声明该转换的 component 放入一个独立的 boundary,使其堆栈中不包含该转换可能改变的内容;或者,当消息指出的是另一个 component 声明的内容时,将该内容移到声明该转换的 component 中。

Two components order one pair of transforms oppositely(两个 component 对同一对转换的排序相反)

组装后的堆栈按一种顺序运行其转换,该顺序由每个 component 自己的顺序和 CloudFormation 文档记载的顺序构建而成。当两种顺序无法同时成立时(两个 component 以相反方式列出同一对转换,或某个 component 将 AWS::Serverless-2016-10-31 列在 AWS::LanguageExtensions 之前,而 CloudFormation 文档记载的是相反顺序),就无法写出唯一的顺序,因此渲染会停止。

输出的消息。先是该情况,然后是这对转换以及各自以何种方式排序的来源:

a plugin could not resolve something it requires to exactly one value (插件无法将其所需的某项解析为唯一的值) cloudformation-provider: the transforms "<first>" and "<second>" are ordered both ways — "<first>" before "<second>" by <who>, and "<second>" before "<first>" by <who> — and the assembled stack’s Transform runs them in one order; declare them in one order (cloudformation-provider:这两个 transform 被以相反的两种顺序排列,而组装后栈的 Transform 只按一种顺序运行它们;请按同一种顺序声明它们)

**修复方法:**在每个同时列出这两个转换的 component 中按同一顺序声明它们;若 CloudFormation 文档记载了顺序,则遵循该顺序。

Two entries reach one stack output name(两个条目得到同一个堆栈输出名称)

堆栈输出名称只允许字母和数字,因此名称是由你编写的内容构建而成的:对该字母表不允许的字符进行编码,而不是丢弃它们。因此,你分开编写的两个条目会保持区分,而此中止报告的是其中两个条目仍然得到同一名称的情况。渲染会停止,而不是在编写了两个条目的地方只输出一个,那样会静默丢弃其中一个。

每个有两个或更多条目汇聚的名称都会被报告,且每个名称背后的每个条目都会按稳定的顺序列出——因此一次构建就能让你看到完整的冲突,而不是只看到其中一方。

输出的消息,以该情况开头,然后是 provider 自己的详细信息:

two things a plugin produced occupy one name in its output (插件产出的两项内容在其输出中占用了同一个名称) cloudformation-provider: two entries an author wrote reach one stack Output name: <the entries that met> reach the Output name "<name>"; an Output name is built by encoding the component and the entry into the letters and digits a logical id admits, rather than by dropping what it does not, so two entries an author wrote apart stay apart — renaming either end clears the build (cloudformation-provider:作者编写的两个条目得到了同一个栈 Output 名称;Output 名称通过将组件和条目编码为逻辑 ID 允许的字母和数字构建,而不是丢弃不允许的字符,因此作者分开编写的两个条目会保持区分——重命名任意一方即可让构建通过)

**修复方法:**重命名其中一个条目或其中一个 component,使两者不再得到同一名称——消息会列出双方。名称保留你编写的标点和大小写,经编码而非丢弃,因此两者中任一方面的差异都会保留在名称中,写法不同的两个条目会得到不同的名称。

A CloudFormation fragment writes one key twice(CloudFormation 片段将同一个键写了两次)

映射中每个键只保存一个值,因此将同一个键写两次的片段会保留最后出现的内容体,丢弃另一个。当该映射是保存资源或输出的块时,被丢弃的内容体就是一个已编写但不会出现在结果中的资源或输出。渲染会改为停止。

该键被写入的两个位置都会被报告,因为一个键被写两次通常是两处本应是两个不同键的编辑——作者需要看到两处才能判断该改哪一个。

输出的消息,以该情况开头,然后是 provider 自己的详细信息:

two things a plugin produced occupy one name in its output (插件产出的两项内容在其输出中占用了同一个名称) cloudformation-provider: one mapping key is written more than once: the key "<key>" is written at line <first> and again at line <second>; a mapping holds one value per key, so one of the two bodies would be dropped — remove one, or rename one so each key is written once (cloudformation-provider:一个映射键被写入了不止一次;映射中每个键只保存一个值,因此两个主体中的一个会被丢弃——请删除其中一个,或重命名其中一个,使每个键只写入一次)

**修复方法:**打开该片段中消息指出的两行。如果这两个内容体本应是同一项,删除现已多余的那个;如果本应是两项,重命名其中一个,使每个都有自己的键。该片段是模板,因此当键是组合生成而非按字面编写时,请检查渲染后的文本,而不仅是源文件。

A cross-boundary reference has no consuming stack to be written into(跨边界引用没有可写入的消费方栈)

当一条依赖连接跨越两个分别组装的输出时,消费方会先以占位符渲染,待两侧都存在后再写入引用。此情况发生在消费方组装出的输出中根本没有栈模板时:没有可写入引用的文档,因此占位符无法被替换。

发出的消息。条件指明失败的类型,provider 自身的语句说明是哪个输入:

a plugin could not resolve something it requires to exactly one value cloudformation-provider: cross-boundary link resolve received no consumer stack template

**修复方法:**你在消费方组件内写的任何内容都不会导致此问题——这是其边界所组装内容的形态造成的。请检查消费方是否确实由 CloudFormation provider 渲染:跨入组装其他内容的边界的连接,没有可供引用落入的栈,这种连接应位于由同一 provider 组装的两个边界之间。若两侧都应是 CloudFormation,则说明消费方边界没有产生栈模板,这需要向为其提供内容的 Recipes 的作者询问。

A cross-boundary reference was spliced into a longer string(跨边界引用被拼接进了更长的字符串)

CloudFormation 跨引用是一个对象而非文本,因此只能整体替换一个值。此情况是在更大的字符串内部发现占位符时报告的——即值是围绕占位符组合而成的,而不是作为注入内容的整体交付。没有可以替换为该对象的内容,因此渲染会停止,而不是以目标无法读取的形态输出引用。

发出的消息。先是条件,然后是该值及其到达所经的连接:

a plugin has no representation for a value it was given cloudformation-provider: cross-boundary link value is interpolated into a larger string; only a whole-scalar injection can carry a cross-stack reference: output key "<key>" on socket "<socket>"

**修复方法:**整体交付该值,而不是围绕它进行组合。若消费方需要将该值放在更长的字符串中——如连接字符串、URL——请用目标自身的词汇基于引用构建该组合,而不是在引用存在之前在 Recipe 的模板中构建。拼接发生在注入该值的映射处,因此要修改的就是那一行。

Two rendered resources land at one output file(两个渲染出的资源落到同一个输出文件)

每个渲染出的资源都会写入一个文件,文件名取决于资源的类型及其名称。两者相同的两个资源会得到相同的文件名,因此一个会占据另一个的位置,渲染会停止,而不是在渲染了两个资源的地方只输出一个文件。

**渲染结果完全相同的两个资源不算冲突。**内容逐字节一致时,保留其中一个不会丢失任何内容,渲染会继续——因此被包含两次且结果相同的模板不会被报告。

发出的消息。先是条件,然后是产生它们的两个模板以及它们相遇的文件:

two things a plugin produced occupy one name in its output helm: node "<node>": rendered resources "<one template>" and "<the other>" both derive output "<file>" with differing content: two rendered resources derive the same output filename with differing content

**修复方法:**为两个资源赋予不同的标识——通常不同的是名称,文件名由名称而来。消息会列出两个模板,打开它们检查各自产生的内容:两个模板以同一名称渲染同一资源,往往是其中一个是旧副本。若两者都需要,它们就是两个资源,各需自己的名称。

A synthesized StatefulSet has no single service to govern it(合成的 StatefulSet 没有唯一的管理服务)

声明了按实例存储的 workload 会被渲染为 StatefulSet,而 StatefulSet 会指定一个管理它的服务——即为每个实例提供稳定地址的服务。该服务是声明时没有自身集群地址的那个。有两种形态会停止渲染:一个都没有声明,因而无可指定;以及声明了多个,因而无法确定由哪个管理。两者都会产生目标拒绝的 StatefulSet,因此渲染会停止,而不是输出它。

**发出的消息。**两者报告同一条件——provider 所需的某项内容无法解析为唯一值——provider 自身的语句说明遇到的是哪种形态。每条消息都打印在指明节点的框架之下:

a plugin could not resolve something it requires to exactly one value synthesized StatefulSet requires a headless governing Service (declare a service with type: Headless); none found: synthesized StatefulSet has no headless governing Service

a plugin could not resolve something it requires to exactly one value synthesized StatefulSet declares more than one headless Service; the governing Service is ambiguous (declare exactly one type: Headless service): synthesized StatefulSet has more than one headless Service

**修复方法:**在该 workload 上恰好声明一个 headless 类型的服务。若一个都没有声明,请添加——具有按实例存储的 workload 需要它,它为每个实例提供一个始终跟随该实例的地址。若声明了多个,保留应作为管理者的那个,将其他的改为普通类型或删除;第二个 headless 服务通常本不需要是 headless 的。

A plugin reported a failure it did not classify(插件报告了一个未分类的失败)

停止构建的插件会报告两件事:一句说明发生了什么的自身语句,以及该语句所指的失败类型。这些类型是编译器声明的一个小集合——没有表达方式的构造、无法解析为唯一值的输入、争用同一名称的两个产物、没有表示形式的值——而此条件是插件在其失败不符合其中任何一种时所选择的。

它是一种兜底,而不是归宿。在其他类型适用时仍选择它的插件,告诉你的比它所知道的少;而措辞明确表示插件拒绝分类,而不仅是出了问题——因此被滥用的兜底是可识别的,而不会与正确的报告混为一谈。

发出的消息。先是条件,随后是插件自身的语句:

a plugin reported a failure that none of the declared kinds names <the plugin's own sentence>

**修复方法:**阅读插件自身的语句,与你的构建相关的所有具体信息都在其中。条件本身只告诉你插件没有适合它的类型。若插件是你的,请选择该失败实际所属的类型;若不是,请将该语句提供给插件的发布者。

A plugin named a condition the socket does not declare(插件指明了 socket 未声明的条件)

插件报告的是本编译器声明的条件,而不是自行编造编号,因此你收到的标识符始终是 aggrega explain 能够解释的。此中止是报告指明其他任何东西时产生的:没有任何条件注册在其下的编号、已停用的编号、拼写与其解析到的注册不同的短代码,或指明两个不同条件的一对标识符。

它会停止,而不是悄悄撤下该报告。 丢弃标识符而让通用的插件失败条件成立,产生的构建看起来与一个根本未指明条件的插件所产生的构建完全一样,因此需要修复它的人永远不会知道有东西需要修复。改为报告所给出的编号,则会交给你一个解析不到任何东西的标识符。

你的构建仍会得到使其停止的原因。 该中止会引用出错的编号,说明它为何解析不到任何条件,列出插件在没有更合适的标识时可使用的通用条件,并原样带上插件自己的句子。

发出的消息:

wasm: guest plugin named a condition the socket does not declare: the guest named "<offered>", and <why it resolves to no condition>; a plugin names a condition this compiler declares, and reaches for one of <the generic conditions and their codes> when it has none better: <the plugin's own sentence>(wasm:guest 插件指定了 socket 未声明的条件:guest 指定的标识符及其无法解析为任何条件的原因;插件应指定本编译器声明的条件,没有更合适的条件时使用所列通用条件之一;随后是插件自己的说明)

修复方法: 你的实体文件中没有任何内容会导致此问题——出错的是插件的报告,而它所报告的失败是真实存在的。请根据插件自己的句子(即消息的最后一部分)采取行动。如果插件是你的,请报告本编译器声明的条件——在失败不符合任何更具体的条件时,使用消息列出的通用类型之一;如果插件不是你的,请把出错的编号提供给其发布者。

A source artifact is cached without a workspace root to anchor it(缓存 source 制品时没有可锚定的工作区根目录)

获取到的 source 制品存储在工作区制品缓存下的一个槽位中,指向该槽位的路径从工作区根目录向外构建。此条件报告的是根目录为空,这会使槽位路径成为相对路径——相对于写入字节时进程恰好所在的任意目录来解析,把缓存放到无人选择的位置。

它会被拒绝而不是被解析,因为写到错误位置的槽位比没有槽位更糟:之后的读取会在正确的位置查找,什么也找不到,于是重新获取,你看到的将是一个似乎永远存不住任何东西的缓存,且没有其他线索指出原因。

发出的消息。以该条件自己的句子开头,随后是标识该制品的信息:

cacheslot: empty workspaceRoot (kind=<kind> url=<url> chart=<chart> version=<version>)(cacheslot:workspaceRoot 为空,括号中为标识该制品的信息)

修复方法: 你的实体文件中没有任何内容会导致此问题,任何编写修改也无法消除它——工作区根目录由驱动构建的一方提供,而不是写在目录中。请在工作区内运行构建,使根目录被自动发现,而不是传入空值。如果你通过自己的软件驱动编译器,请显式传入工作区根目录;确实希望缓存相对于当前目录的调用方应传入单个点,这是被接受的,并明确表达了这一意图。

A value would place a cached file outside the cache(某个值会把缓存文件放到缓存之外)

缓存的实体和缓存的 source 制品各自位于缓存为其命名的槽位中,该槽位由值组成:实体的引用及其解析到的版本,或 source 的类型、url、chart、module_subdir、版本和摘要。每个值指明布局中的一个位置。此条件报告的是会把为其写入的内容移到它所指明位置之外的值——移到另一个槽位旁边,或完全移出缓存——并在该处写入或读取任何内容之前拒绝它。

这些值大多来自缓存无法控制的地方:注册表提供的内容、从磁盘读回的记录、Recipe 或 FeatureRecipe 作者编写的坐标。是路径而非版本的版本、向上越出其位置的 url 路径或 module_subdir,以及解析为点目录的引用,都会在此被拒绝。指明单个目录的值——以及停留在其位置或其下的 url 路径或 module_subdir——不受影响。

向上越界的 module_subdir 会在获取任何内容之前被拒绝。 对于 git-repository source,同一个值还指明拉取所归档的仓库目录,向上越出仓库的值会让拉取读取其检出目录旁边的文件。因此拉取会在获取仓库之前判断 module_subdir,并以此条件拒绝向上越界的值,在其键下引用该值:不会获取任何内容,也不会读取检出目录旁边的任何内容。其中的反斜杠按分隔符读取,就像 Windows 路径那样,因此 ..\shared 在每台机器上都会被拒绝,而不是在某台机器上从检出目录旁边读取;值开头或结尾的分隔符会被去掉,因此 /charts/app 指明的是 charts/app。

发出的消息。以该条件自己的句子开头,随后是按编写时的键给出的原值,以及补救方法:

a value a cache location is built from would place cached files outside the place it names in the cache (version "../../../etc" for entity "demo/app/web"). a version, a name, a kind or a host names one directory of the cache, so it carries no / or \ and is neither . nor ..; a URL path or a module subdirectory may name directories beneath its place but may not climb above it. Correct the value where it was written, or, where a registry served it, ask its publisher to publish a version that carries a well-formed one(用于构建缓存位置的某个值会把缓存文件放到它在缓存中所指位置之外。版本、名称、种类或主机只指定缓存中的一个目录,因此不能包含路径分隔符,也不能是当前目录或上级目录;URL 路径或模块子目录可以指定其位置之下的目录,但不能向上越出该位置。请在写入该值的地方更正它;如果该值由注册表提供,请让其发布者发布一个带有格式正确的值的版本)

修复方法: 如果该值是你编写的——Recipe 或 FeatureRecipe 的 source.version、url 或 module_subdir——请将其更正为指明单个目录,或停留在其位置之内的路径;消息会引用该值及读取它的键。如果它由注册表提供,则已发布的实体带有不合格的版本或坐标,你的任何修改都无法修复:消息会指明所获取的内容,补救需由其发布者进行。

有些操作会自行写入或删除文件,位置由它们自己推算,而不是由你指定:构建的输出目录及其在其中写入的每个文件,以及带追踪的构建所替换的 .trace 目录;Release 的锁文件及其旁边的插件信任记录,由 pull 写入;实体旁边的 entity.lock,由 aggrega pin 写入,固定源的 pull 也会在其固定的每个实体旁边写入它;工作区的 .aggrega-config.yaml,在命令写入工作区配置时写入;制品缓存及其每个子树,由 pull 填充,由 aggrega cache clear 和 aggrega cache prune 清空;pull 为每个已验证签名的制品在该缓存中保存的签名包;aggrega import 写入的草稿;aggrega plugin gen-catalog 在其输出目录下写入的 Plugin 实体;以及编辑器语言服务器在记录默认 Release 时写入的 .aggrega/active-release 标记和包含它的 .aggrega 目录。无论操作由哪个入口发起——命令行、编辑器语言服务器还是助手的工具——都同样适用。工作区边界说明了此处应用的规则,以及有意通向工作区之外的路径。

上述每个位置都有一个必须保持在内的目录,具体是哪个目录取决于操作在哪个目录下组合出该位置:

  • 工作区,适用于在其中组合出的一切。这是常见情况,对于你指定的、位于工作区内的目录同样适用。无论构建从哪个文件夹运行,构建的 dist 和 .trace 始终在此处、在工作区根目录下组合,未指定输出目录的导入所生成的草稿也是如此。
  • 你指定的、位于工作区之外的目录,适用于在其下组合出的一切:你传给 aggrega plugin gen-catalog 或 aggrega import 的输出目录;你指定的或工作区配置指定的、位于工作区之外的 Release 所在目录,适用于其旁边的锁文件和信任记录;以及你传给 aggrega pin 的实体所在目录,或你用 --catalog 指定、或配置在 catalog_dirs 下列出的目录,适用于其中每个实体旁边的 entity.lock。目录本身按你指定的方式使用——如果它是链接,就穿过链接写入其指向的位置——而写在其下的内容保持在其内。
  • 制品缓存目录本身,适用于写入其下缓存的一切,以及 aggrega cache clear 和 aggrega cache prune 在其中删除的一切——默认的 .aggrega/cache 与配置中写成从工作区根目录向上跳出的 artifact_cache_dir(../shared-cache)同样适用。缓存自身的某个目录或其中的某个文件,如果是通向缓存目录之外的链接,即使它指向工作区内的其他位置也会被拒绝,因此写入缓存的任何内容、清理或修剪删除的任何内容,都不会落到缓存之外的文件上。首先判断缓存目录本身的位置:写在工作区根目录内的缓存目录,在工作区内无论指向何处都会被跟随,而指向工作区之外时会被拒绝,即限定在工作区内;写成从工作区根目录向上跳出的缓存目录则按你指定的方式使用,如果它是链接,就穿过链接写入其指向的位置。

在这些位置写入或删除任何内容之前都会先进行检查。路径中已存在的最深部分(跟随途经的每个符号链接后)必须是其必须保持在内的目录,或位于该目录之下。途中任何通向该目录之外的链接——链接到别处目录的 dist、链接到另一个项目中文件的锁文件、链接到与其他工作共享目录的 .aggrega/cache、gen-catalog 输出目录下链接到别处的目录——都会使写入或删除落在外部,因此操作会停止,该路径保持原样。这对构建最为重要:否则,清理并重写一个作为链接的输出目录,就会删除并重写机器上其他位置的某个目录。

不指向任何地方的链接按其实际情况处理——视为不存在的东西——因此检查的是包含它的目录。如果这样的链接恰好位于操作即将创建的路径末尾,文件会被创建在链接指向的位置,因此也会检查它指向的位置。指向路径必须保持在内的目录之内某处的链接,照常跟随。

发出的消息。消息以该条件自身的语句开头,随后是操作即将写入或删除的路径(由 writing 或 removing 表明是哪一种)、其必须保持在内的目录、途中遇到的链接及该链接指向的位置,然后是修复办法。dist 是通向工作区之外的链接的构建,会在它要触及的第一件事——清理先前的输出——时停止:

a path this operation writes or deletes leads through a link out of the directory it must stay inside (removing <workspace>/dist/boundaries, which must stay inside <workspace>, the link <workspace>/dist leads to <elsewhere>/dist-target). nothing was written to or removed from that path. Remove the link, or make it lead to a place inside <workspace>, and run the operation again(此操作写入或删除的路径经由一个链接通向它必须留在其中的目录之外(括号中依次给出正在删除的路径、它必须留在其中的目录、该链接及其指向的位置)。该路径未被写入或删除任何内容。请移除该链接,或使其指向工作区内的某个位置,然后重新运行该操作)

该诊断不带类别:出错的是磁盘上的布局,而不是你编写的任何文档。

**修复方法:**删除消息中指出的链接并重新运行操作,使其在该位置创建真实的目录或文件;或者让该链接指向消息中指出的目录内的某处,这样它会被跟随。此问题并非由你的实体文件引起,任何编写上的修改都无法消除它。

A name the operation writes holds a part Windows cannot hold(操作写入的名称含有 Windows 无法容纳的部分)

在 Windows 上,有些名称无法按原样写入文件。Windows 为设备保留的名称——CON、PRN、AUX、NUL、CONIN$、CONOUT$、COM0 至 COM9 和 LPT0 至 LPT9,以及带上标一、二或三的 COM 和 LPT 名称——指向的是设备而不是文件,与字母大小写无关,也与其后的扩展名无关,因此 nul、Aux.yaml 和 com1.txt 都是设备。此外,以句点或空格结尾的路径部分可能被 Windows 截掉,而不是按原样保留。写入这样的名称会把其字节放到该名称所指文件以外的地方。

因此,当某个操作即将在 Windows 机器上的某个目录下写入一个并非由它自己选择的名称时,含有此类部分的名称会在写入任何内容之前被拒绝:源制品或目录实体所携带归档中的条目(在缓存展开归档以供读取时);构建渲染到其输出目录中的文件;导入器返回给 aggrega import 的草稿(无论是试运行还是实际写入);以及 aggrega edit-document 写回的文档(无论由哪个界面发起编辑)。名称的每个部分都会按 Windows 的方式判定,反斜杠视为分隔符——因此 aux/x.yaml 因其目录 aux 被拒绝,report. 因其末尾的句点被拒绝,.. \evil.yaml 因其第一部分(两个点加一个空格)被拒绝。一组名称中只要有一个被拒绝,其余名称也都不会写入:归档不会展开,构建的输出不会被清除或写入,也没有草稿写入磁盘。

在 Linux 和 macOS 上,这些名称会按原样写入,此条件永远不会触发。爬出其所写入目录的名称属于另一种错误,在所有平台上都会以该操作自己的消息被拒绝,且在检查本条件之前进行。

输出的消息。消息以该条件本身的句子开头,然后是名称、Windows 无法容纳的部分以及该名称原本要写入的目录,最后是修复方法:

a name this operation writes holds a path segment Windows cannot hold as written (the name "aux/x.yaml", its segment "aux", beneath <directory>). It was not written. Windows reserves device names such as CON, PRN, AUX, NUL, COM1 and LPT1, in any letter case and whatever extension follows, and does not hold a segment ending in a full stop or a space as written; rename that segment where the name is produced(此操作写入的名称包含一个 Windows 无法按原样保存的路径段(即上述名称、其中的路径段以及其所在的目录)。该名称未被写入。Windows 保留 CON、PRN、AUX、NUL、COM1 和 LPT1 等设备名,不区分字母大小写,也不论其后跟随何种扩展名;并且不会按原样保存以句点或空格结尾的路径段。请在生成该名称之处重命名该路径段)

该诊断不带类别:名称来自生成它的任何一方——归档的发布者、Recipe 或库、导入器、编辑所指定的路径——而不是来自编译器可以归咎的某一个文档。

**修复方法:**在名称的来源处重命名消息所指出的部分。对于归档条目,来源是已发布的源制品或实体,只有其发布者才能更改。对于渲染出的文件,来源是 Recipe 或 ArtifactLibrary 为其指定的输出名称;对于草稿,是为其命名的导入器;对于编辑,是文档的路径。无论如何调整 Windows 机器,都无法让该名称按原样可用。

不会中止构建的情况

上面的每种情况都会中止构建。有些情况带有自己的短代码和消息,却从不中止构建;这里将它们一并收录,这样无论你从哪个页面来到这里,手中的代码总能找到对应的条目。

它们分为四类,在着手寻找修复方法之前,值得先了解其中的区别。

  • 提示。 构建会报告它并继续进行,无论你是否处理,渲染输出都相同。每一项都在 warnings.md 中有完整说明——什么会触发它、它在编译的哪个阶段被检查、它输出什么,以及如何处理——下面的条目只指明对应的章节,不在此重复。
  • 由编辑器吸收的情况。 它由编辑器集成自身处理,既不会进入构建输出,也不会产生诊断。
  • 位于更早拒绝之后的防护。 它所保护的规则已由一个确实会中止构建的情况提前执行,因此构建会先遇到那个更早的情况。
  • 非构建命令上的拒绝。 它是硬性停止,并有切实的补救方法——它会结束遇到它的命令,且不会发布、写入或更改任何内容——但编译的任何阶段都不会到达它,因此没有构建会报告它。发布或签名制品、固定实体的输入、添加 registry、编辑文档、将外部源描述转换为草稿编写文件,以及检查整个 catalog(检查其正确性或是否符合发布约定),都是会遇到这些情况的场合;每个条目都会说明它属于哪个命令,以及由谁负责修复。

注解绑定在两个支柱列表中声明了同一路径

提示。某个 Manifest 注解绑定在其 maps.infra 和 maps.values 列表中都列出了同一个点分路径。声明这种重叠是合法的,编译器也不会对其加以管控:路由的决胜规则会确定性地将该路径经由 infra 发送,这使得该路径的 values 一侧无法从 Aggregate 到达。

其消息开头为:

annotation binding declares one path in both pillar lists(注解绑定在两个支柱列表中声明了同一路径)

它会在构建遇到上文“An annotation routes through a pillar its authoring side may not use(注解经由其编写方不得使用的支柱进行路由)”中描述的中止之前向你发出警告——提示是早期的呈现面,而那个中止则是执行面。该 lint 在 warnings.md 的“Binding-map-overlap lint”下讲解。

附件名称与某个已声明的槽只差一次编辑

提示。某个组件以一个名称附加了 Feature,该名称不是其类型声明的槽之一,但与其中某个槽只差一次编辑——这正是槽名拼写错误的样子。以未被任何槽声明的名称进行附加是合法的,因此不会中止;该提示指出的是其后果:该附件是一个自由附件,而不是填充你本意要填的槽,该槽仍保持为空。在连接上,同样的拼写错误不合法,会改为中止并指出相近的槽;参见“A connection carries an attachment under a name its socket declares no slot for(连接以其插座未声明槽的名称携带附件)”。如果该附件的 Feature 满足相近槽的 selector:,则不会发出该提示:这种配对由“An attachment written under another name fits a slot its component leaves empty(以另一名称编写的附件适合其组件留空的槽)”下的中止来判断,它会在该槽留空时报告。

其消息开头为:

attachment name is a near miss for a declared slot(附件名称与某个已声明的槽相近)

在 warnings.md 的“Attachment-slot near-miss lint”下讲解,包括配对阈值以及它有意不捕获的情况。

uses: 插座名称与某个已声明的插座只差一次编辑

提示。某个组件自身的 uses: 块列出了一个其类型未声明、但与某个已声明插座只差一次编辑的插座。开发者拥有 Aggregate 所声明的拓扑,可以使用 catalog 未预料到的插座名称,因此在该呈现面上类型未声明的插座名称是合法的,不会中止。该提示指出的是其后果:拼错的名称会生成一个独立的临时连接,不携带选择器,也没有逐边契约,而你本意要连接的插座仍未接线。

其消息开头为:

uses socket name is a near miss for a declared socket(uses 插座名称与某个已声明的插座相近)

详见 warnings.md 中的“Uses-socket near-miss lint”。所属实体的 usesSchema 中缺少的 socket 名称确实会中止构建的两个相邻场景,见上文“uses: socket not declared in the owning entity’s usesSchema(socket 未在所属实体中声明)”。

Recipe 发布了其 Component 未声明的 provides 键

提示。绑定到某个组件的 Recipe 在 provides: 下发布了一个键,而该组件的类型未在其 spec.schema.provides: 契约中声明该键。发布多于 Component 所声明的内容是合法的,并将一直合法——该契约要求子集、允许超集。该提示指出的是一个从任何一侧都看不到的后果:沿 uses: 边读取的消费方看到的是目标已声明的契约,而不是其 Recipe 实际输出的内容,因此未声明的键不会被传递,读取它的消费模板会渲染为空。

其消息开头为:

Recipe publishes a provides key its Component does not declare(Recipe 发布了其 Component 未声明的 provides 键)

相反的情况则不是提示:Component 声明了其 Recipe 未发布的键,会使契约未被履行并导致中止。在 warnings.md 的“Undeclared-provides-key lint”下讲解。

已声明的参数未被任何内容读取

提示。某个 Aggregate 在 spec.parameters: 下声明了一个条目,但该 Aggregate 自身文本中没有任何 {{ .parameters.<key> }} 引用读取它,因此无论 Release 为其提供什么值,渲染输出都相同。编译器不管控作者暴露哪些调节项,而且参数可以合理地先于将来读取它的引用而声明,因此这里只给出提示而不中止。

其消息开头为:

declared parameter is read by no reference in the Aggregate(已声明的参数未被 Aggregate 中的任何引用读取)

在 warnings.md 的“Unread declared-parameter warnings”下讲解,包括为何默认值不构成豁免,以及该检查能看到和看不到哪些引用。

provider 绑定指定了构建所读取的任何插件都不提供的能力

提示。某个 plugins.providers 条目指定了一项能力但未指定插件,而构建所读取的 provider 插件——无论位于 catalog 目录中、编译器内部,还是 lockfile 记录的插件之中——都不提供该能力。这正是能力名拼写错误的样子,而这样的条目不会被任何内容读取:只有当 Recipe 请求其能力时才会查阅绑定,而一个未指定插件的绑定,所选中的不会超出没有它时该能力的解析本来就会选中的内容。

它只给出建议而不中止构建,是因为构建无法确定。绑定为整个工作区编写一次,而一次构建只针对一个 Release,因此提供该能力的插件可能只有另一个 Release 会读取。指定了插件的条目则按不同方式判断,并在确定有误时中止——见上文“A plugins.providers binding names a plugin that does not serve the capability(plugins.providers 绑定指定的插件不提供该能力)”。

其消息开头为:

plugins.providers entry names a capability no provider-rendering plugin the build reads serves(plugins.providers 条目指定了构建所读取的任何 provider 渲染插件都不提供的能力)

随后是该能力,以及(如果存在)一个只差一次编辑的已提供能力。在 warnings.md 的“Provider-binding unserved-capability warning”下讲解。

An editor position falls outside the document(编辑器位置超出文档范围)

由编辑器吸收的情况。依赖光标位置的编辑器功能(跳转到定义、悬停提示、补全)会先在文档的解析结构中定位光标。当位置指向文档中不存在的行时,该步骤会报告此情况。这种情况会在编辑进行中短暂出现:编辑器发送的位置是基于文档已经更新过的旧文本测量的。

其消息为:

position out of range(位置超出范围)

它不会进入任何构建,也不会产生任何诊断。 每个可能遇到它的功能都会返回空结果,而不是抛出错误,这正是编辑器协议要求的行为:无法应答的请求不返回任何内容,编辑器会在下一次按键后再次请求。

你的文件中没有需要修复的内容,构建中也不会出现任何信息。如果某个功能在下一次编辑后仍未恢复响应,值得将其作为缺陷报告。

schema 合并步骤自身的输入保护

构建不会触及的保护。当一个 Component 或 Feature 扩展另一个,且两者都声明了 schema 时,这些 schema 会被合并为一个。执行合并的库会拒绝无法在结构上合并的输入:

merger: invalid merge input(merger:无效的合并输入)

它属于合并步骤,而构建确实会到达该步骤:只要扩展实体及其基础实体都声明了 schema。它防范的是传入空链,或某个链条目缺少 schema;而调用方两者都不会传入:它只用已确认存在的 schema 组装链,并且只在链非空时才执行合并。

保留这一保护,是因为它是一个导出库对格式错误输入的拒绝。移除它不会移除任何构建可以触及的中止;反而会让编译器之外传入此类输入的调用方从得到明确的拒绝变为崩溃,这只会更糟。

链本身不是此步骤关心的内容。 循环的链和超过深度上限的链,会在合并任何 schema 之前由唯一的一次 extends: 遍历拒绝——见上文“Cyclic extends chain(循环的 extends 链)”和“An extends: chain runs past the depth bound(继承链超过深度上限)”。

之所以收录它,是因为它已被声明并拥有自己的代码,这样手中的代码总能查到对应条目。你编写的任何内容都不会产生它;如果遇到,就意味着上述安排不再成立,值得作为缺陷报告,而不是绕过它。

An explicit value displaced one an annotation supplied(显式值取代了注解提供的值)

提示性信息。注解驱动的展开会把 Aggregate 或 Release 携带的注解转换为带有自身配置的 Feature 挂载。如果同一挂载还带有显式编写的配置(在 component 上、在其上层作用域中,或在 Release 中),那么在两者都覆盖的每个键上,显式值优先。这是预期规则,输出也没有错误,因此构建会完成。该提示指出的是其后果:注解对该键的贡献在输出中已不可见,而编写注解的作者可能并不知道它被覆盖了。

它会报告每一次取代,而不仅是改变了结果的那些。合并会覆盖被取代的值,因此已无从比较,也无法判断两者是否一致;取代发生过的记录就是全部证据。它在整个挂载级联与展开合并完成后读取,这是该记录最早存在的时刻。

其消息开头为:

annotation contribution overridden by an explicit value(注解的贡献被显式值覆盖)

随后依次给出被取代的注解、取代它的键的坐标,以及被取代注解的编写位置。其前面的位置是该发现所在的文档及其中的键:

<file> at <authored key>: annotation contribution overridden by an explicit value ("<annotation-key>", component "<component>", attachment "<attachment>", pillar "<pillar>", key "<the key at issue>", annotation declared at "<where the annotation was written>")

其中两个值容易误读。component 仅在取代条目拥有 component 时才给出:为整个作用域编写的条目没有自己的 component,给出一个它从未有过的 component 会把读者引向一个没人写过的键。而 annotation declared at 指的是被取代注解的编写位置;如果注解并非写在取代它的 component 上,这就是它被继承来源的作用域,因此它并不是换了标题重复的 component 键。

如何处理: 如果显式值正是你想要的,则无需处理。该提示的存在是为了让优先级成为一种选择而非意外。如果不是你想要的,有两种办法,作用范围不同。删除显式条目,注解的值就会传递到该键。或者从携带注解的 component 或作用域上移除注解,这样就完全不会产生贡献,这也会影响该注解提供的其他所有键。如果两者都需要但用于不同的键,就收窄作用范围超出预期的一方,使两者不再重叠。

A connection crosses between two different providers’ assembled outputs(连接跨越两个不同 provider 的组装输出)

当依赖连接的两端组装到不同输出中时,声明支持跨边界链接的 provider 会以原生方式连接它:在生产端发布引用,在消费端解析引用。这种连接以某个 provider 自身的词汇编写,一个 provider 无法解析另一个 provider 发布的引用。因此,两端通过不同 provider 渲染的连接,两者都不会为其建立连接。

这只是提示,不会中止构建。 连接仍然携带其值:注入契约会像在其他任何地方一样,把生产端的标量传递到消费端,因此得到的是一个以普通方式连接、可正常工作的连接,而不是损坏的连接。该发现告诉你的是,你可能期望的原生连接没有发生;无论你是否处理,输出都不变。

只要有一个 provider 声明支持链接就会报告。 不需要两端都声明:一个声明就意味着原生连接被期望却无法实现,而挂载该 provider 的作者正是期望它的人。如果要求两端都声明,那么在常见的混合部署中(一个 provider 支持链接而另一个不支持)就不会有任何报告,而这正是此提示针对的情形。

两端的放置位置不影响判断。 组装输出由其路径和 provider 共同标识,因此 provider 不同的两端无论如何放置,总是位于不同输出中。读取的只是两个 provider 及其两项声明。

每个此类连接报告一次,位置是编写该连接的文档和键。

输出的消息,先给出远端,再给出 socket 和两端各自的 provider:

cross-boundary link between endpoints rendered by different providers is not supported(不支持由不同 provider 渲染的端点之间的跨边界链接) ("<target-component>", socket "<socket>", consumer provider "<provider>", target provider "<provider>")

如何修复: 如果连接已携带的标量值足够,就无需处理,这只是通知而非故障。如果需要原生连接,两端必须通过同一个 provider 渲染:将一端移到经由另一端 provider 路由的边界中,或用一个 provider 同时提供两项能力。如果两者都不可行,部署使用的就是携带值的形式,连接仍可正常工作。

A command-line plugin runner was built without a way to find plugins(命令行插件运行器在构建时缺少查找插件的途径)

贡献终端命令的插件由一个组件运行,该组件首先要把插件的引用转换为字节。此情况报告的是该组件在构建时缺少负责这一转换的部分,因此从引用到可运行之物之间没有路径。

它涉及的是终端命令而非构建,因此编译的任何阶段都不会触及它:它在分派已安装命令时引发,其结果是该命令无法启动,而不是任何构建的中止。

随附的命令行工具中没有任何路径会引发它。 该工具构建该组件的每一处都提供了查找功能,因此只有在其他代码构建该组件且遗漏查找功能时,此防护才会触发。

输出的消息,即该情况本身的表述:

cliplugin: no plugin resolver configured(cliplugin:未配置插件解析器)

如何修复: 你的实体文件不会导致此问题,在目录或工作区中写入任何内容也无法消除它。如果你运行的是已发布的命令行工具,你不会遇到此情况——无法启动的已安装命令报告的是别的问题,应阅读它打印的消息。如果你在自己的软件中嵌入插件运行器,请在构造它时提供将插件引用解析为其字节的查找功能。

A registry alias is already bound to another host(注册表别名已绑定到另一个主机)

这是向工作区添加注册表时的拒绝,而非构建时的拒绝。别名是选择某个注册表条目的短名称,因此在所有条目中唯一。注册一个已被其他主机占用的别名会被拒绝,而不是允许它遮蔽现有绑定,否则会悄无声息地改变每个使用该别名的引用所指向的位置。

以现有别名重新添加同一主机不算冲突——这会原地更新该条目,重新运行该命令以更改主机的其他设置正是如此。

输出的消息,指明别名以及已占用它的主机:

workspaceconfig: registry alias "<alias>" is already used by host "<host>"; choose a different alias or address that host directly: registry alias is already used by another host(workspaceconfig:该 registry 别名已被该主机使用;请选择其他别名,或直接使用该主机地址:registry 别名已被另一主机使用)

如何修复: 修复由操作者在命令行完成。为新注册表指定一个不同的别名,或不设别名并通过主机引用它。如果你本意是将该别名转移到新主机,请先在 .aggrega-config.yaml 中从消息所指的条目里移除它——此拒绝的存在,是为了让转移别名成为你有意为之的操作,而不是添加注册表的副作用。

A registry serves a trust document that cannot be read as one(注册表提供的信任文档无法作为信任文档读取)

这是添加注册表时的拒绝,而非构建时的拒绝。注册表可以发布它期望制品所使用的签名身份,使添加注册表时能够固定这些身份,而无需操作者手动抄录。此情况报告注册表返回的文档无法用作信任策略。

正因为端点作出了响应,它才是硬性拒绝。 注册表什么都不发布是普通的、预期中的结果,可以容忍;发布了无法读取的内容则是配置错误,若从中什么都不固定,注册表会在看似已固定的情况下悄无声息地处于未固定状态。

有三种情形在此报告:内容根本无法解码,包括文档带有格式未定义的字段;身份条目既未指明确切身份也未指明模式;身份条目没有签发者。后两种被拒绝,是因为这样的条目永远无法匹配任何签名,它会在看似加强固定的同时削弱固定。

输出的消息。 内容无法解码:

registrytrust: advertised trust config is malformed: <what the decoder reported>(registrytrust:所发布的信任配置格式错误:解码器报告的内容)

身份条目没有可匹配的内容:

registrytrust: advertised trust config is malformed: <list>[<index>]: an identity entry must set identity or identity_regexp(registrytrust:所发布的信任配置格式错误:列表中对应索引的条目:身份条目必须设置 identity 或 identity_regexp)

以及没有签发者的条目:

registrytrust: advertised trust config is malformed: <list>[<index>]: an identity entry must set issuer(registrytrust:所发布的信任配置格式错误:列表中对应索引的条目:身份条目必须设置 issuer)

每条消息前都带有遇到它的命令:

aggrega registry add: <the message above>

如何修复: 修复归注册表的运营者负责,而不是你——把消息转告他们,因为它指明了确切的条目及其缺少的内容。在此期间若要继续,可以添加注册表而不固定其公布的策略,并自行提供身份或密钥;该命令可直接接受它们,对于根本不发布策略的注册表也是这样做的。

A registry publishes no trust document(注册表未发布信任文档)

这是普通的、预期中的结果而非故障,不会阻止任何操作。注册表可以发布它期望的签名身份,而大多数并不发布。被请求时,这样的注册表会回答它没有,添加注册表照常继续——该结果作为通知报告,身份改为手动固定。

它有意区别于无法访问的注册表。此处注册表作出了响应;回答是它不发布策略。将两者分开,才能在容忍有意缺失的同时,让可达性问题仍以其本来面目显现。

作为通知报告,指明注册表、它的响应以及应改为如何操作:

Notice: <host> publishes no trust policy (HTTP 404); pin its trust by hand with —identity or —key(提示:该主机未发布信任策略(HTTP 404);请使用 —identity 或 —key 手动固定其信任)

它所记录的情况是 registrytrust: registry advertises no trust config。

官方 hub 是例外:它带有内置基线,因此在它不发布文档时会改为固定该基线,通知会说明 hub 的响应以及改用基线,而不会要求你固定身份。

如何修复: 没有任何问题。如果你希望检查来自该注册表的签名,请在添加时按通知所说提供身份或密钥——这是不发布策略的注册表的常规做法。如果不需要,注册表会在没有签名立场的情况下添加,来自它的制品仅在带有签名时才会被验证。

离线添加 registry 时没有可固定的信任策略

这是添加 registry 时的拒绝,而非构建时的拒绝。添加 registry 是固定其信任的唯一时机:它公布的签名身份只获取一次,之后的每次拉取都依据这份固定的副本进行验证。工作区处于离线状态时无法执行这次获取,因此根本不会询问该 registry。为避免写入一个什么都不信任的条目(而之后的每次拉取都会按此条目要求该 registry),添加官方 hub 以外的 registry 会被拒绝,除非你自行提供策略。

有三种情况不会被拒绝。 提供身份或密钥时,只登记所提供的这些内容,完全不执行获取,因此离线与在线时行为相同。官方 hub 以其内置基线添加,无论是否执行获取,它都带有该基线。而要求不执行获取(--fetch-trust=false)时,会根据标志登记该条目,与在线时完全相同。

凡是添加 registry 的地方都会遇到它:aggrega registry add、aggrega config init --registry <host>、aggrega serve 的 aggrega/registryAdd 和 aggrega/configInit 请求(其错误消息在句子前带有短代码),以及运行这些命令的 aggrega mcp 登记工具。初始化配置时不接受身份或密钥,因此离线时只能初始化 hub;其他 registry 请改用 aggrega registry add 添加。

输出的消息,即该情况本身的表述:

a registry other than the official hub is not registered offline without a trust policy supplied by hand, because the policy it advertises cannot be fetched; register it once while online, or pin its trust by hand with aggrega registry add <host> --identity <identity>=<issuer> or --key <public-key-file>(离线时,除官方 hub 外的注册表若没有手动提供的信任策略则不会被注册,因为无法获取其公布的策略;请在联网时注册一次,或使用上述 identity 或 key 参数手动固定其信任)

并以遇到它的命令及其指明的 registry 作为前缀:

aggrega registry add: <host>: <the message above>

修复方法: 在工作区在线时登记该 registry 一次(为这一次运行传入 --offline=false,或清除 offline 设置),以便获取并固定其公布的策略;之后无需重复,因为后续拉取都依据固定的副本进行验证。无法联网时,手动提供策略:对于无密钥的 registry,提供一个或多个 --identity <identity>=<issuer> 条目;对于有密钥的 registry,用 --key 指向其公钥文件。这正是你本会从其公布内容中固定的信息。

tag 已以不同内容发布

这是发布时的拒绝,而非构建时的拒绝。已发布的字节是冻结的:在上传任何内容之前,会查找目标版本,并将其指向的摘要与手头内容将产生的摘要进行比较。已指向不同内容的版本会被拒绝。

重新发布字节完全相同的内容不算冲突。 摘要一致,不会上传任何内容,命令会报告该版本已发布。因此重新运行部分成功的发布是安全的,并且会完成该发布:附加该版本仍缺少的发布日期,以及推送进行签名时的签名;两者都不缺的版本则不附加任何内容,如补全先前推送遗留的不完整发布所述。

没有可覆盖此行为的标志。 变更后的内容以新版本发布,这样使用方得到的是一个可以有意迁移过去的版本,而不是一个在他们不知情时发生了变化的版本。

输出的消息,指明版本、其持有的摘要以及提交的摘要。发布目录实体时,消息还会指明验证版本升级的检查:

aggrega push: <reference>:<version> is already published as <existing digest>; refusing to overwrite with <proposed digest> — publish a new version (aggrega lint —pre-publish verifies the bump): oci: tag already published with different content(该引用的此版本已以现有摘要发布;拒绝用提议的摘要覆盖——请发布新版本(aggrega lint —pre-publish 会验证版本提升):oci:该标签已以不同内容发布)

发布数据制品时:

aggrega push-artifact: <reference>:<version> is already published as <existing digest>; refusing to overwrite with <proposed digest> — publish a new version: oci: tag already published with different content(该引用的此版本已以现有摘要发布;拒绝用提议的摘要覆盖——请发布新版本:oci:该标签已以不同内容发布)

修复方法: 提升版本并重新发布。对于目录实体,这意味着修改 metadata.version 以及实体所在的按版本划分的目录,两者同步变动。在此之前,请确认这项变更是你有意为之的:在你认为未改动过的版本上两个摘要不同,意味着磁盘上的内容并非已发布的内容,查明原因比覆盖发布更有价值。消息中提到的发布前检查会将一个版本与其前一版本进行比较,可用来确认版本升级是否正确。

实体与另一个实体共用目录

这是固定和发布时的拒绝,而非构建时的拒绝。除工作区根目录中并列存放的三种实体(Aggregate、Release 和 Manifest)外,每种实体类型都有自己的目录。已发布的实体在每个版本下是位于一个坐标的一个制品,其编写所在的目录与此相对应:固定步骤写入目录中唯一能容纳的那个 entity.lock,而发布则从实体所在目录打包该实体。因此,任何其他类型的实体旁边若有另一个实体,在这两个时机都会被拒绝:由 aggrega pin 拒绝,由要求代表作者进行固定的拉取或推送拒绝,以及由 aggrega push 拒绝(无论是否进行固定)。拒绝发生在获取任何内容之前,且不会写入任何内容。

包含多个实体的目录仍可加载、lint、验证和构建。 只有在从该目录生成内容时才会检查布局,这也是消息能够指明碍事实体的时机。不进行固定的拉取不会在实体旁写入任何内容,因此不会被拒绝。

所谓实体旁边的实体,是指直接位于同一目录中、kind: 为实体类型的任何其他 YAML 文档。chart 自身的文件、compose 片段、Kubernetes manifest 或 README 都不是实体;子目录(本地 chart、source/ 树)无论包含什么,都不算在实体旁边。每个相邻文件只读取其类型和名称,因此相邻文件声明的任何内容都不会改变判定结果。

不检查目录名称。 独占目录的实体无论该目录位于何处,都会按其声明的版本进行固定和发布;标准库目录采用的 <name>/<version>/ 布局是一种约定,而不是一项检查。

输出的消息,指明该实体、其旁边的每个实体以及需要移动的文件:

the entity shares its directory with another entity, and an entity of its kind has a directory of its own (Recipe "<name>", beside it: Recipe "<name>" in <file>). remediation: give each entity a directory of its own — move <file> into a directory of its own, together with any file only that entity reads; only the Aggregate, Manifest and Release kinds may share a directory with other entities(该实体与另一个实体共用目录,而该类型的实体应拥有自己的目录。修复方法:为每个实体提供独立目录——将所列文件连同仅该实体读取的文件一起移入独立目录;只有 Aggregate、Manifest 和 Release 类型可以与其他实体共用目录)

修复方法: 将消息指明的每个实体移入其独立目录,并带上仅它读取的文件(本地 chart、导入的文件,以及记录了该实体固定信息的 entity.lock),然后对每个读取远程源或导入文件的实体运行 aggrega pin,使每个 lock 只记录其自身实体。将每个实体按 <kind>/<provider-or-publisher>/…/<name>/<version>/ 布局存放,可使其位置与标准库目录存放所有实体的方式一致。目录是通过遍历找到的,因此移动之后,基于该目录的构建会渲染出相同的输出。

An entity kind has no artifact media type(实体类型没有制品媒体类型)

这是发布时的拒绝,而不是构建时的。每种可发布的实体类型,对其制品的两种形式(单独的文档,或文档及其声明的文件组成的归档)各有一个媒体类型,打包实体时按类型查找。此情况报告的是没有对应条目的类型。

**任何构建都不会触及此情况。**执行同一查找的唯一其他位置会将缺失的条目视为“这不是一个库”并继续执行,因此此情况永远不会在那里显现。

输出的消息:该情况本身的表述,前后由命令及其正在打包的文件包围:

aggrega push: bundle <path>: oci: unknown entity kind for mediatype dispatch(aggrega push:bundle:oci:用于媒体类型分派的实体类型未知)

**修复方法:**将你要发布的文件的 kind: 字段与 aggrega push --list-kinds 打印的类型进行核对——拼写错误或不受支持的类型会在此报告,更正该字段即可完全解决。如果该类型包含在该列表中,则这是工具链的缺陷而非你的实体的问题,值得附上该类型名称进行报告。

A published archive carries an entry Windows cannot use(发布的归档包含 Windows 无法使用的条目)

这是发布实体时发出的提示;它从不阻止任何操作,构建也不会发出它。在文档之外还携带文件的实体会以归档形式发布,归档中的每个名称(先是实体文档自身的文件名,然后是它携带的每个文件)都按照上文停止项“A name the operation writes holds a part Windows cannot hold(操作写入的名称包含 Windows 无法容纳的部分)”在 Windows 上所采用的规则进行判断:Windows 为设备保留的部分(不区分大小写,无论后跟什么扩展名),或以句点或空格结尾的部分。因此 aux/x.yaml 会因其目录 aux 触发该提示,report. 会因结尾的句点触发,名为 con.yaml 且导入了 schema 文件的文档会因其自身名称触发。不携带任何文件的实体仅以其文档发布,放在产品选定的名称下,而 Plugin 不发布归档,因此两者都不会触发。

**它在所有平台上都会发出,且不拒绝任何操作。**Windows 上的工作区会在该停止项下拒绝布置此类条目,因此无法使用该版本;这条提示让发布者在 Windows 用户发现之前就得知此事。发布或其试运行会照常继续或停止,与没有该提示时完全相同。

每个发布实体的入口都会发出它,各有其形式。aggrega push 及其 --dry-run 会在标准错误中为每个条目输出一行,每行以 warning: 开头。助手的 publish-entity 工具以 windows_unusable_entries 返回这些条目,回复文本中也会列出它们。aggrega serve 在对 aggrega/publishEntity 的回复中以 windowsUnusableEntries 返回它们,并将警告行本身传递给请求了报告的请求。没有此类条目时,各回复都会省略该字段。

其消息开头为:

an entry this publication carries cannot be used on Windows(此次发布携带的某个条目无法在 Windows 上使用)

随后给出该条目及其中第一个 Windows 无法容纳的部分,然后是修复方法。详见 warnings.md 中的“A published archive carries an entry Windows cannot use(发布的归档包含 Windows 无法使用的条目)”。

**修复方法:**在磁盘上以及实体声明中引用该文件的所有位置,重命名消息指出的部分,然后重新发布。如果该版本本就不打算在 Windows 上使用,则无需做任何更改。

Two catalog identities publish to one repository location(两个目录标识发布到同一个仓库位置)

这是检查整个目录时的拒绝,而不是构建时的拒绝。实体发布到的位置由其标识派生并转为小写,因此两个仅在字母大小写上不同的标识会落到同一位置。同时发布两者会使一个实体的字节被另一个实体的字节覆盖,而两个实体中都没有任何内容表明这一点。

该检查一次性在整个目录上运行,因为冲突是一对实体的属性,而不是其中任一实体自身的属性——单独看两者都没有错,孤立地读取任一实体也看不出任何问题。

输出的消息。消息以 catalog 检查的外层前缀开头,接着是该情况本身的表述,然后列出每个冲突组,每组给出共享的位置以及到达该位置的标识:

catalog validation failed: oci: distinct catalog identities map to the same OCI repository location:(目录校验失败:oci:不同的目录标识映射到同一个 OCI 仓库位置:)

  • <location> <- <identity>, <identity>

**如何修复:**重命名消息所列实体中的一个,修改其 metadata.name 以及与之对应的目录。重命名哪一个由你选择;仅大小写不同的一对是常见情形,选定一种拼写并始终一致地使用,才能避免这对冲突再次出现。重命名是对实体标识的真实更改,因此任何引用旧名称的内容都必须随之修改——这也是应在任一名称发布之前而非之后解决冲突的原因。

Keyless signing was asked for without the services it needs(请求了无密钥签名,但缺少其所需的服务)

这是发布过程中签名时的拒绝,而不是构建时的拒绝。无密钥签名没有离线形式:它获取一个身份,为该身份签发一张短期证书,将签名记录在之后可供检查的位置,然后丢弃密钥。其中每一步都是与一个运行中的服务的交互。该情况表示签名流程所依赖的身份不可用,因此流程被拒绝,而不是开始后中途放弃。

有两种情形会报告该情况:根本没有配置任何提供身份的来源,以及配置了来源但未产生任何内容。

离线工作区的报告方式不同,它归入涵盖所有网络步骤的拒绝之下,因为该拒绝发生在请求身份之前。

**输出的消息。**没有身份来源:

signing: keyless signing requires a live identity provider, Fulcio, and Rekor: an identity token source is required(signing:无密钥签名需要可用的身份提供方、Fulcio 和 Rekor:需要一个身份令牌来源)

以及来源未产生任何内容:

signing: keyless signing requires a live identity provider, Fulcio, and Rekor: an identity token is required(signing:无密钥签名需要可用的身份提供方、Fulcio 和 Rekor:需要一个身份令牌)

**如何修复:**修复由操作者负责,在于发布的运行方式。在自动化流水线中,身份来自流水线自身的凭据,因此这通常意味着该作业未被授予签发凭据的权限。交互式运行时,身份来自登录,命令会提示你登录。如果你完全不需要实时身份,请改用持有的密钥签名——这种方式不需要上述任何服务,从无法访问这些服务的环境中应使用这种方式。

An unsigned publish targets a registry or a policy that requires a signature(未签名的发布指向了要求签名的注册表或策略)

这是发布时的拒绝,而不是构建时的拒绝。在要求签名的地方,未签名的内容不会被发布。该检查在上传任何字节之前运行,因此不会有不完整的内容到达注册表。

**两种情况,因为要求有两个来源,且修复方法不同。**一种是目标注册表自身的立场,适用于在该处发布的所有内容。另一种是工作区的签名策略,它覆盖一组制品类型,无论它们发布到何处。两者同时成立时,报告注册表的情况,因为指明目标是两者中更有用的。

**这里没有可以发布未签名内容的标志。**显式关闭签名并不会放宽该拒绝——它只会改变签名为可选的制品的默认行为。

签名在上传之前而非之后生成,因此签名失败也会归入此处,并且不会发布任何内容。

**输出的消息。**注册表自身的要求:

aggrega push: registry "<host>" requires signatures; re-run signing the artifact (there is no flag to push unsigned content here): signing: registry requires signatures; refusing to push unsigned content(aggrega push:该 registry 要求签名;请对制品签名后重新运行(此处没有用于推送未签名内容的标志):signing:registry 要求签名;拒绝推送未签名内容)

工作区策略的要求,它会指明使该制品纳入范围的类型:

aggrega push: the signing policy requires a signature for kind "<kind>"; re-run signing the artifact (there is no flag to push unsigned content here): signing: signing policy requires a signature for this artifact kind; refusing to push unsigned content(aggrega push:签名策略要求该 kind 必须签名;请对制品签名后重新运行(此处没有用于推送未签名内容的标志):signing:签名策略要求此制品类型必须签名;拒绝推送未签名内容)

以及无法生成签名的情况,它归入注册表的情况报告,并引用底层失败:

aggrega push: sign <reference>:<version>: <the underlying failure>: signing: registry requires signatures; refusing to push unsigned content(aggrega push:对该引用及版本签名时发生底层失败:signing:registry 要求签名;拒绝推送未签名内容)

有一种签名失败会被专门指出,因为笼统的拒绝会让人去重新获取一个无济于事的凭据:

aggrega push: sign <reference>:<version>: the identity token carries no verified email or subject claim — the OIDC flow/client did not return an email-scoped identity (re-exporting or re-acquiring the token will not help); configure the identity provider/client/scope to return one: <the underlying failure>: signing: registry requires signatures; refusing to push unsigned content(aggrega push:对该引用及版本签名:身份令牌不含经过验证的 email 或 subject 声明——OIDC 流程/客户端没有返回带 email 作用域的身份(重新导出或重新获取令牌无济于事);请配置身份提供方/客户端/作用域以返回此类身份:底层失败:signing:registry 要求签名;拒绝推送未签名内容)

**如何修复:**修复由操作者负责。对制品签名后重新发布——使用持有的密钥或无密钥方式,以工作区的配置为准。如果你没有预料到需要签名,消息会说明是哪个来源提出的要求:注册表自身的立场位于 .aggrega-config.yaml 中该注册表的条目里,按类型的要求位于工作区范围的签名策略中。放宽其中任何一个,都是在决定你愿意发布哪些未签名内容,因此缩小策略的范围通常比完全关闭它更好。

一起签名的引用需要不同的签名凭据

这是签名时的拒绝,而非构建时的拒绝。给定多个引用的 aggrega sign,以及给定批处理文件的 aggrega deprecate --from,会用同一个凭据签名所给的全部内容:单个持有的密钥,或单个无密钥身份。一个引用需要哪个凭据,由其注册表的配置决定——适用于该注册表的 signing.key_path 选定它所指定的密钥,没有适用的配置时,该引用以无密钥方式签名。当一起指定的引用需要不同的凭据时——一个注册表需要密钥而另一个不需要,或需要两个不同的密钥——不会签名任何内容,消息会列出每一方的注册表。

该检查在请求身份之前、读取任何注册表之前运行,因此不会签名或附加任何内容,也不会为一次不会继续进行的运行提示任何人。签名一旦被他人获取便无法收回,因此该运行会被拒绝,而不是使用其中某个引用所需的凭据进行签名。

通过 --key 传入的密钥对每个引用都起决定作用。 无论配置对各个注册表如何规定,它都适用于所指定的每个引用,因此这样的运行永远不会在此处被拒绝。

凡是对一批内容签名的地方都会遇到它:aggrega sign、aggrega deprecate --from、aggrega serve 的 aggrega/signArtifacts 和 aggrega/deprecateArtifact 请求(其错误消息在句子前带有短代码),以及 aggrega mcp 的 sign-artifacts 和 deprecate-artifact 工具。通过监听器到达服务器的工具调用从不使用配置所指定的密钥,因此在那里每个引用都使用调用所发送的身份签名,调用不会在此处被拒绝。

输出的消息。以该条件本身的句子开头,随后列出每个凭据及其将要签名的注册表,最后是补救办法:

aggrega sign: signing: the references named together need different signing credentials, so nothing was signed (<registry> signs with the held key signing.key_path names, <registry> signs keyless: no signing.key_path applies). remediation: sign them in separate runs, one per credential: the references on <registry>, then the references on <registry>; each run signs as it would on its own(aggrega sign:签名:一起指定的引用需要不同的签名凭据,因此未签名任何内容(一个 registry 使用 signing.key_path 指定的持有密钥签名,另一个 registry 无密钥签名:没有适用的 signing.key_path)。修复方法:按凭据分开运行签名,每个凭据一次:先签名一个 registry 上的引用,再签名另一个 registry 上的引用;每次运行的签名方式与单独运行时相同)

以及当批次中某个注册表要求签名时,在补救办法末尾指出它:

aggrega sign: signing: the references named together need different signing credentials, so nothing was signed (<registry> signs with the held key signing.key_path names, <registry> signs keyless: no signing.key_path applies). remediation: sign them in separate runs, one per credential: the references on <registry>, then the references on <registry>; each run signs as it would on its own, and <registry> requires signatures, so this refusal holds back signing that would otherwise have gone ahead rather than signing that cannot be done(aggrega sign:签名:一起指定的引用需要不同的签名凭据,因此未签名任何内容(一个 registry 使用 signing.key_path 指定的持有密钥签名,另一个 registry 无密钥签名:没有适用的 signing.key_path)。修复方法:按凭据分开运行签名,每个凭据一次:先签名一个 registry 上的引用,再签名另一个 registry 上的引用;每次运行的签名方式与单独运行时相同,且所指 registry 要求签名,因此此次拒绝阻止的是本可进行的签名,而非无法完成的签名)

第二个拥有自己密钥的注册表会被描述为“with a different held key”(使用另一个持有的密钥)签名。密钥的路径从不打印:消息给出的是设置项,也就是你可以更改的内容。

如何修复: 按其注册表所需的凭据拆分引用,每个凭据运行一次——一次 aggrega sign 指定使用密钥签名的注册表上的引用,另一次指定其余引用;对于 aggrega deprecate --from,每个凭据使用一个批处理文件。这样每次运行的签名方式都与其单独运行时相同。若要改为在单次运行中用一个密钥签名所有引用,请通过 --key 传入该密钥。

分离签名无法用所提供的密钥验证

在完全离线的情况下,用公钥检查针对某个载荷的裸签名所得出的否定结果:载荷与被签名的内容不同,签名已被篡改,或者该密钥不是生成签名的那个密钥。

随附的工具链中没有任何部分会触及它。 它所属的检查除自身测试外没有调用方,因此用户运行的任何命令——构建、拉取或发布——都不会报告它。之所以在此编目,是为了让该代码能解析到某个条目,而不是因为构建会打印它。拉取实际执行的验证针对的是完整的签名包,并单独报告。

输出的消息,引用验证器报告的内容:

signing: signature does not verify: <what the verifier reported>(签名:签名验证未通过:附验证器报告的内容)

如何修复: 这不是由你的实体文件导致的,你在目录或工作区中写入任何内容也无法消除它。如果你运行的是已发布的命令行工具,则不会遇到此条件,你实际看到的签名问题是由上文某个签名包验证条件报告的。如果你在自己的软件中直接使用签名包,那么载荷、签名和密钥必须是相互对应的三者——常见原因是载荷在签名和验证之间被重新序列化,这样即使内容读起来相同,字节也不同了。

解析出的制品不是文档包

解析为其他类型制品(目录实体、插件)的引用会被拒绝,而不会作为文档缓存,因此指向错误的引用会在其指向处失败,而不是在之后作为无法读取的包失败。

出现位置。 文档包从工作区所配置的注册表中保留的 docs 命名空间下获取,存入机器上所有项目共享的缓存:面向助手的服务器在启动时、回答任何请求之前获取一次;aggrega explain 和编辑器对代码的解释在首次需要时获取;aggrega scaffold --example 也会获取——每种情况都仅在机器上没有工作区签名检查所接受的副本时才获取。这是每次获取都会对返回内容执行的检查。

它从不中止会话。 获取过程在服务器的日志流中报告结果,连接无论如何都会继续;被拒绝的制品的代价是文档资源,这些资源在该会话中会返回 not-found。aggrega scaffold --example 没有文档包就没有内容可写,因此在那里它表现为该命令的拒绝,并且不会写入任何内容。

输出的消息,给出引用和两种媒体类型:

docscache: <reference>@<version> has media type "<what was found>", want "<what a documentation bundle is>": docscache: artifact is not a documentation bundle(docscache:该引用的该版本的媒体类型为所发现的类型,而期望的是文档包的媒体类型:docscache:制品不是文档包)

如何修复: 这不是由你的实体文件导致的,任何编写上的改动都无法消除它。获取所用的引用指向了并非文档包的内容——请检查工作区所配置的注册表,因为包引用由它派生;而格式正确但指向其他制品的引用会成功解析,只在此处失败。

文档包中缺少某个页面

文档包已缓存且其内容已验证,但所请求的页面(或者,对于 aggrega scaffold --example 而言,示例的目录)不在其中。这与完全没有文档包不同:文档包存在且完好,只是其中缺少该条目。

它不会影响任何构建。 向编辑器或助手提供文档页面的接口会将其转换为针对所请求资源的普通 not-found 应答。aggrega scaffold --example 不写入任何内容,并将其报告为一次拒绝,指出该示例和文档包,随后提示使用 aggrega scaffold --example --list,该命令会打印文档包确实包含的示例。

值得分清你得到的是两种 not-found 应答中的哪一种,尽管接口对它们的呈现相同。这一种表示文档包已缓存且完好,但页面不在其中。另一种——没有工作区可读取的文档包,因为没有缓存,或唯一的副本被工作区的签名检查拒绝——表示获取未完成,服务器的日志流会说明原因。

输出的消息,给出页面以及查找该页面的文档包:

page "<page>" in <reference>@<version>: docscache: page not found in documentation bundle(docscache:在文档包中未找到该页面)

如何修复: 你的文件没有任何问题。文档包中缺少某个页面,是因为该文档包早于该页面,或者所请求的路径不是该页面的发布路径——文档包按服务器报告的自身版本获取,因此在该版本之后添加的页面不在其中。如果该页面从未存在过,说明请求指定了文档不使用的路径,请在已发布的文档中找到它实际使用的路径。

编辑会生成其 schema 拒绝的文档

这是文档编辑时的拒绝,而非构建时的拒绝。一次结构化编辑——添加组件、附加 Feature、连接边或设置值——被组合并拼接到文档中,然后按该文档类型的 schema 检查结果。若该检查提出异议,编辑会被拒绝,不写入任何内容。它属于 aggrega edit-document,也属于编辑器通过 aggrega serve 或助手所使用的同一能力,它们都是同一实现之上的轻量入口。

类型从文档中读取,从不由调用方提供。 由调用方指定类型可能会指定错误的类型,结果就会按文档并未遵循的 schema 进行检查——这恰恰会放行本检查所要拒绝的编辑。

文件逐字节保持原样,且写入是原子的,因此被拒绝的编辑与从未尝试过的编辑无法区分,修正后的请求可以针对你最初的文档重试。

它针对的是格式正确的请求。 请求指定了本能力适用的编辑,而它将生成的文档是你手工输入时编写 schema 也会拒绝的文档——这就是为什么不为它重述任何编写规则:要求 Release 携带开发者值,无论哪种方式都会被同一 schema 拒绝。从未构成编辑的请求——节点路径在文档中找不到任何内容、需要标量处却写成了映射、已存在的条目携带其他内容——会按其自身原因被拒绝,各接口会通过各自的渠道报告。

原本就无效的文档同样会报告。 即使编辑没有改变任何内容,检查也会运行,因此针对产品会拒绝读取的文档进行的编辑会如实报告,而不是报告成功。

该检查与每次读取文档时应用的检查相同,因此它也会拒绝流水线将同一个步骤 id 声明了两次的 Recipe 或 FeatureRecipe,这是任何 schema 都无法表达的规则;此时该句之后的异议会以该条件自身的句子和建议开头,如 A pipeline declares one step id twice (流水线将同一个步骤 id 声明了两次) 中所述。

输出的消息,在句子之后附上 schema 本身的异议——先是文档类型和文件,然后是位置、出错的键以及 schema 在该处的说明——最后给出建议:

the edit was refused because the resulting document would not be valid, and nothing was written: document envelope validation failed (<kind>, at <path>); <line>:<column>: <field-path>: … <the schema's own objection>. correct the document to match its kind’s schema(编辑被拒绝,因为生成的文档将无效,且未写入任何内容:文档封装校验失败,后附出错位置、字段路径及 schema 自身的异议。请更正文档,使其符合其类型的 schema)

如何修复: 打开文档中消息引用的位置并阅读异议,它说明了 schema 在该键处的要求。需要修改的通常是请求而不是文档——请求该位置 schema 所接受的条目,同样的请求即可顺利应用。如果该键是这种文档类型根本不能携带的,它应属于可以携带它的编写接口,该类型的实体页面列出了它声明的字段。语义上是否可接受不在此处判定——例如某个依赖插槽是否由生产方声明——因此这种拒绝始终关乎文档的结构,从不关乎跨连接可以使用什么。

注解键使用了平台保留的前缀

这是按发布约定检查实体时的拒绝,而非构建时的拒绝。aggrega.ai/ 前缀,以及 Feature 之外的 feature.aggrega.ai/,归平台所有:写在这些前缀下的键带有平台赋予的含义,因此你自己的实体若写在其中,就是在占用一个不属于它的命名空间。

它在编写时给出建议,在发布关口拒绝,两种情况都指向这同一个条件。发现的内容相同,只是后果不同。此处编目的大多数发布约定规则都是这样表现的,因此只在此说明一次,下文未另行说明的条目均默认如此——与已发布版本进行比较的两条规则会在各自条目中说明,因为它们根本无法针对本地内容运行。

其消息开头为:

an annotation key on the entity uses a prefix the platform reserves(实体上的某个注解键使用了平台保留的前缀)

如何修复: 将该键移到你自己组织拥有的前缀下。如果工作区确有理由仍要写在保留前缀下,该规则属于 aggrega-lint.md 中“The discipline rules”下所述的可选退出项之一。

实体名称不符合其类型预期的形式

这是对照发布约定检查实体时的拒绝,而非构建时的拒绝。每种实体类型都带有一项名称形式约定——云原生类型规定段数,库类型采用 PascalCase——而此实体声明的名称与其类型预期的形式不符。

其消息开头为:

the entity’s name does not follow the documented name shape for its kind(实体名称不符合其类型的文档化名称形式)

**修复方法:**将实体重命名为其类型预期的形式;各类型的约定列在 aggrega-lint.md 的“The discipline rules”下,其中还说明了供有意按自己方式命名实体的目录使用的退出选项。

schema 使用了无法提前解析的动态引用

这是对照发布约定检查实体时的拒绝,而非构建时的拒绝。实体携带的某个 schema 使用了动态引用结构,其目标是在验证文档时选定的,而不是在编写 schema 时固定的。此处引用会被提前展开,因此不存在可供此类结构解析所依据的进行中的验证。

其消息开头为:

a schema in the entity uses a dynamic reference construct that cross-document reference resolution cannot follow(实体中的某个 schema 使用了跨文档引用解析无法追踪的动态引用结构)

**修复方法:**将动态结构替换为直接指明目标的普通引用。如果该 schema 确实需要此结构且不会被跨文档引用,该规则带有一个退出选项,说明见 aggrega-lint.md 的“The discipline rules”。

schema 声明了平台所拥有的标识符

这是对照发布约定检查实体时的拒绝,而非构建时的拒绝。实体携带的某个 schema 声明了自己的标识符,而规范标识符是从实体的身份派生的。声明的标识符会取代派生的标识符,因此按规范标识符编写的引用将无法解析。

其消息开头为:

a schema in the entity declares an identifier of its own, where the platform owns that schema’s identity(实体中的某个 schema 声明了自己的标识符,而该 schema 的身份归平台所有)

**修复方法:**删除声明的标识符,让其自动派生。供有意以自有标识符发布的 schema 使用的退出选项,说明见 aggrega-lint.md 的“The discipline rules”。

Component 的类别标签与其所在目录指明了不同的类别

这是对照发布约定检查实体时的拒绝,而非构建时的拒绝。Component 带有一个类别标签,并归档在某个类别目录下;约定是两者指明同一类别,这样读者浏览的目录与选择器匹配的标签就不会不一致。

其消息开头为:

the entity’s category label does not match the category directory the entity is filed under(实体的类别标签与其所归档的类别目录不匹配)

**修复方法:**修改两者中错误的一方使其一致——要么将文件移到其标签指明的目录下,要么将标签改为目录指明的类别。类别的封闭集合以及退出选项,见 aggrega-lint.md 的“The discipline rules”。

schema 扩展被直接写入 schema 内容

这是对照发布约定检查实体时的拒绝,而非构建时的拒绝。某个 Component 或 Feature 将 Aggrega schema 扩展直接写入其 schema 内容,而该实体本有用于声明同一内容的一等接口。直接编写的形式可以工作,约定之所以偏好声明接口,是因为实体页面教授的、工具读取的都是它。

这是该组中唯一一条构建也会报告的规则,作为不会中止构建的建议。在发布关口对照发布约定检查实体时,同一发现会被提升为拒绝。

其消息开头为:

the entity writes an Aggrega schema extension directly into schema content instead of declaring it under usesSchema or featuresSchema(该实体将 Aggrega schema 扩展直接写入 schema 内容,而不是在上述两个字段之一下声明它)

**修复方法:**将扩展移到实体自身的 socket 或 attachment 接口上,component.md 和 feature.md 的实体页面正是在那里声明它。退出选项见 aggrega-lint.md 的“The discipline rules”。

Plugin 未固定任何运行时上限,因此采用平台自身的上限

这是对照发布约定检查实体时发出的建议,编写时和发布关口都会发出;它从不中止任何操作,构建也不会发出它。Plugin 声明宿主在加载和运行该插件时施加的内存上限和时间限制。两者都未声明的 Plugin 在平台默认值下运行,这是受支持的结果而非错误——因此它报告的是默认值正在生效,以及可以显式固定这些值。

其消息开头为:

the Plugin entity declares no runtime resource cap of its own, so the platform defaults apply(该 Plugin 实体未声明自己的运行时资源上限,因此采用平台默认值)

**修复方法:**固定插件实际需要的上限,或有意保留默认值。它没有退出设置,原因是它报告的是关于实体的事实而非对实体的评判:没有什么需要放宽。相关字段见 plugin.md。

attachment 槽位只接受机密材料,却未声明它会处理机密

这是对照发布约定检查实体时发出的建议,编写时和发布关口都会发出;它从不中止任何操作,构建也不会发出它。attachment 槽位可以通过其选择器固定只有携带机密的 Feature 才能填充它,也可以另行记录填充它的任何内容都会处理机密材料。选择器说明哪些填充是可接受的;记录说明如何处理。固定了前者而省略了后者的槽位,会让处理方式只能从选择器推断,而不能直接从槽位读出。实体声明的每个槽位都会被检查:其自身 attachment 块中的槽位,以及在 Component 上,依赖 socket 为经其连接的每个连接声明的槽位——关于 socket 槽位的发现会在槽位旁指明该 socket。

其消息开头为:

an attachment slot admits only secret material and does not declare that it handles it(attachment 槽位只接受机密材料,且未声明它会处理机密)

**修复方法:**在槽位上固定它的选择器旁声明处理方式。它没有退出设置,原因与 Plugin 上限规则相同:它报告的是关于实体的事实,决定权留给你。

Recipe 发布了其 Component 未声明的 provides 键,在发布时检查

这是对照发布约定检查实体时发出的建议,编写时和发布关口都会发出;它从不中止任何操作,构建也不会发出它。某个 Recipe 在 provides: 下发布了一个键,而该 Recipe 所实现的 Component 未在其 schema 的 provides 支柱中声明该键。跨连接接线的消费者读取的是 Component 声明的契约,而不是 Recipe 输出的任何内容,因此该键被生成后,会在有东西尝试消费它时被拒绝。

🔴 **有两个条件描述此情况,它们并不相同。**构建报告的建议记录在上文“A Recipe publishes a provides key its Component does not declare”下;这一条在对照发布约定检查实体时发出,并带有自己的代码。该发现是在两个接口上遇到的同一事实——读取诊断中的代码即可分辨你遇到的是哪一个。

其消息开头为:

the Recipe publishes a provides key the Component it implements does not declare, so a consumer wiring that key is refused(该 Recipe 发布了其所实现的 Component 未声明的 provides 键,因此接线该键的消费者会被拒绝)

**修复方法:**在 Component 上声明该键,使消费者读取的契约包含 Recipe 输出的内容——或者在没有东西需要消费它时,停止从 Recipe 发布它。退出选项见 aggrega-lint.md 的“The discipline rules”。

Component 的指标注解与其 provides 键不一致

在对照发布约定检查实体时提出的建议,编写期间和发布关口都会提出;它从不中止任何操作,构建也不会提出它。Component 可以在其注解 observability.aggrega.ai/metrics-credential 中说明其产品的指标如何认证——none、target-key 或 separate-token——也可以声明 provides 键 metrics_credential_required,其每个 Recipes 都发布该键,以说明一个实例的指标是否需要凭据。二者是从两个方面看到的关于产品的同一事实,因此声明其指标不需要凭据的 Component 不声明该键,而声明需要凭据的则声明该键。此条件报告二者不一致的 Component,并指出该 Component、注解的值以及多出或缺失的键。

其消息开头为:

a Component’s annotation stating how its metrics authenticate disagrees with whether it declares the provides key saying an instance’s metrics need a credential(Component 说明其指标如何认证的注解,与它是否声明表示实例指标需要凭据的 provides 键不一致)

**修复方法:**更正二者中错误的一方——在指标需要凭据的情况下,在 provides 支柱中声明 metrics_credential_required,并从每个 Recipe 发布它;在不需要凭据的情况下将其移除;或者将注解改为描述该产品的值。它没有退出设置,原因与 Plugin 上限规则没有退出设置相同;它读取哪些值、不读取哪些 Components,见 aggrega-lint.md 中的“The discipline rules”。

连接与其到达的目标未指向同一个密钥

在对照发布约定检查 Release 时提出的建议;它从不中止任何操作,构建也不会提出它。检查密钥的服务器将其验证的密钥保存在自己的槽中,而调用方在其到达该服务器所经的连接上出示密钥。两端都看不到对方的密钥,因此二者之所以是同一个密钥,只是因为其作者在两端写了相同的定位符。此条件报告这样一个连接:其目标为它要求调用方提供的密钥声明了槽,但二者不一致:连接携带凭据而目标的密钥槽未填写,目标的密钥槽已填写而连接不携带凭据,或者两者都已填写但定位符写法不同。

与上面的规则不同,此规则读取整个 Release 而非单个实体,因此只在检查 Release 时才会遇到,在发布关口永远不会遇到,因为发布关口单独检查一个实体;无论在何处报告,它都只是建议。该发现会指出组件、连接、目标和两个槽,但从不引用任何一个定位符。抓取——scrape_target 插座上的连接——按其目标对自身指标的说明来判断:目标的 observability.aggrega.ai/metrics-credential 注解为 none 时完全不判断,为 separate-token 时从不对照目标的密钥判断,其他情况下与任何其他连接一样判断;任何其他插座上的连接,无论目标如何说明都会被判断。

其消息开头为:

a connection and the target it reaches do not name one key: they write different locators for it, or only one of them names one(连接与其到达的目标未指向同一个密钥:二者为它写了不同的定位符,或者只有其中一方指定了密钥)

**修复方法:**让两端读取同一个参数——连接的 credential 和目标的 api_key——这样调用方出示的密钥与服务器验证的密钥就不会被写得不同;或者,在连接本就不应出示密钥的情况下,去掉其凭据。读取哪些槽、比较什么以及退出方式,见 aggrega-lint.md 中的“The discipline rules”。

正在发布的变更超出了演进准则允许的范围

在发布之前的检查中被拒绝,而非在构建中。正在发布的版本会与此前已发布的版本进行比较,二者的差异会依据一份有文档说明的准则进行分类。此条件报告该差异是准则所反对的。

它需要一个已发布的前一版本用于比较,因此它和下文的版本升级检查是本组中仅有的两条无法仅基于本地内容运行的规则:不查询注册表时没有可比较的对象,该检查会被跳过,而不是视为通过。

其消息开头为:

the version being published changes the published predecessor in a way the documented evolution rubric objects to(正在发布的版本以有文档说明的演进准则所反对的方式更改了已发布的前一版本)

**修复方法:**阅读诊断中的分类,其中指出了准则反对该变更的哪一方面,然后使变更保持兼容,或者以允许该变更的版本发布。该准则见 aggrega-lint.md 中的“The version-bump rubric”。

提供的版本升级幅度小于变更所要求的幅度

在发布之前的检查中被拒绝,而非在构建中。正在发布的变更会依据演进准则进行分类,而为其提供的版本比该分类要求的步幅更小——例如,将一次移除或收窄作为补丁版本提供。过度升级总是被接受;在此处中止的是升级不足。

**与上面的规则不同,此规则在此处判定,而不是由约定插件判定。**提供的是哪种升级只有在发布时才知道,而那时没有编译在运行,因此分类与所提供版本之间的比较在那时进行。

其消息开头为:

the version bump being published is smaller than the evolution check’s classification of the change requires(正在发布的版本升级小于演进检查对该变更的分类所要求的幅度)

**修复方法:**以分类所要求的版本发布;诊断会指出是哪个版本。如果你认为变更比其被分类的幅度更小,aggrega-lint.md 中“The version-bump rubric”下的准则说明了变更归入各类别的依据。实体的首次发布没有前一版本,因此比较会被跳过,并报告为未执行,而不是视为通过。

导入在转换源的过程中途停止

在将外部源描述转换为草稿编写文件时被拒绝,而非在构建中。导入器报告了一个严重到足以中止转换的诊断,因此其产出是不完整的:源的一部分成为了草稿编写文件,另一部分没有。

**不完整的结果是有意为之,而非残骸。**它指出的是结果而非原因——无法转换的内容会在其旁边的诊断中报告,导入器无法转换的每个构造各对应一条,使用导入器自己的措辞。此条件使调用方能够区分“导入已停止并产出了部分结果”与“导入彻底失败”,这是两种不同的情况,后续步骤也不同。

其消息开头为:

the importer reported a diagnostic that stops the import, so the source was not fully turned into draft authoring files(导入器报告了一个中止导入的诊断,因此源未被完全转换为草稿编写文件)

**修复方法:**阅读其旁边报告的诊断——每条诊断都指出源中导入器无法转换的一个构造。修复在于你提交的源,或者手动完成草稿:导入产出的是一个供编辑的起点,因此未能在转换中保留的构造,应在 Aggrega 一侧直接编写。aggrega-import.md 描述了该命令产出什么以及写入何处。

More than one importer recognises the source(不止一个导入器识别出该源)

这是在将外部源描述转换为草稿编写文件时的拒绝,而非构建时的拒绝。导入未指定格式,因此根据各导入器声明的签名来识别格式——工作区目录中的导入器与编译器的核心导入器都是如此,每个签名都指明读取源所用的语法、适用的文件名,以及其解析树必须或不得包含的路径——而服务于不止一种格式的导入器的签名都匹配了该源。导入不会在它们之间做选择:源属于哪种格式是导入器的陈述,而非编译器的陈述;替它选择只是一种猜测,可能会把源交给并非为它而设的导入器。

这与同一格式由不止一个导入器声明的情况不同,后者见上文“A parse or import format is advertised by more than one plugin(一种解析或导入格式由不止一个插件声明)”。在那里格式已确定,服务于它的各导入器相互竞争,因此由 plugins.importer 条目在其中选择;而这里格式本身就不同,因此任何挂接都无法解决,指定格式才能解决。导入器识别某个源时,会将其识别为它声明的每一种格式,因此一个声明了不止一种格式、且其中一个签名匹配的导入器,在这里同样会被拒绝。

其消息开头为:

more than one importer recognises the source

消息的其余部分按导入器的标识与版本顺序列出该源及其被识别成的每种格式,然后给出补救措施:

more than one importer recognises the source (source "<source>", recognised as "<format>", "<format>"). Pass —format to name the one to read it as (for example —format <format> or —format <format>)

如何修复: 指定格式——在 aggrega import 上使用 --format,或在助手的导入工具和会话的 aggrega/import 方法上使用 format。如果其中某个导入器本不应识别此类源,则应修改该导入器的签名,签名由其作者在其 describe() 自述中声明,并在生成其 Plugin 实体时记录在其中;或者,如果它是工作区目录中的导入器,则将其排除在工作区读取的目录之外——核心导入器始终在尝试之列,因此若某个核心导入器与另一个导入器同时识别出某个源,就需通过指定格式来解决。aggrega-import.md 说明了格式是如何识别的。

No importer recognises the source(没有导入器识别出该源)

这是在将外部源描述转换为草稿编写文件时的拒绝,而非构建时的拒绝。导入未指定格式,因此根据各导入器声明的签名来识别格式——工作区目录中的导入器与编译器的核心导入器都是如此——而没有任何格式的签名匹配该源。导入不会猜测:把源交给从未声明能读取该形态的导入器,会基于一个可能并非为它而设的源生成草稿。

这与上文的“More than one importer recognises the source(不止一个导入器识别出该源)”相对应。 在那里多种格式都认领该源;在这里没有任何格式认领。两种情况下,指定格式都能解决问题,并且在指定之前不会写入任何内容。

其消息开头为:

no importer recognises the source

消息的其余部分列出该源,然后按读取顺序给出补救措施以及目录中导入器声明的每种格式:

no importer recognises the source (source "<source>"). Pass —format to name it explicitly (for example —format <format> or —format <format>)

如果没有任何导入器声明格式,补救措施会说明这一点,以代替示例。

目录会得到不同的补救建议,因为随便指定一个格式对它并无帮助。 目录只通过其导入器声明的文件模式来读取,而未声明任何文件模式的签名不适用于目录中的任何文件——因此,一个只包含(比如)一个 Langflow 导出文件的目录不会被任何签名识别,而指定 langflow 格式又会依据 An importer that declares no file patterns is handed a directory(未声明文件模式的导入器收到了一个目录) 被拒绝。因此,对目录的拒绝会将其指明为目录,并建议单独导入其中一个文件,或指定一个其导入器声明了文件模式的格式——只列出这些格式,取自各导入器自身的声明:

no importer recognises the source (directory "<directory>"). Import one of the directory’s files on its own, or pass —format naming a format whose importer reads a directory through the file patterns it declares (for example —format <format> or —format <format>)(没有导入器能识别该源(目录)。请单独导入该目录中的一个文件,或传入 —format 指定一个格式,其导入器通过自己声明的文件模式读取目录(例如 —format 或 —format))

如果没有任何导入器声明文件模式,该拒绝会建议单独导入目录中的一个文件,并说明编目中没有任何导入器声明用于读取目录的文件模式。

如何修复: 指定格式——在 aggrega import 上使用 --format,或在助手的导入工具和会话的 aggrega/import 方法上使用 format,它们各自围绕所接受的字段来表述该拒绝,并以此条件的短代码开头;会话的应答还会在其数据中携带该条件的两个代码。对于目录,请单独导入你想要的那个文件——不指定任何文件的签名适用于单独导入的文件,无论其名称为何——或者指定拒绝中列出的某个格式。如果该源本应被识别,则应修改服务于其格式的导入器的签名,签名由其作者在其 describe() 自述中声明,并在生成其 Plugin 实体时记录在其中。aggrega-import.md 说明了格式是如何识别的。

An importer that declares no file patterns is handed a directory(未声明文件模式的导入器被交给了一个目录)

这是在将外部源描述转换为草稿编写文件时的拒绝,而非构建时的拒绝。所指定的源是一个目录,而目录交给导入器时,恰好是该导入器声明的文件模式所选中的那些文件——因此导入器读取目录中的哪些文件,由导入器自己陈述。服务于该源格式的导入器未声明任何文件模式:它只读取一个文件,并未说明目录中哪些文件归它处理。

不会打开任何文件。 导入在解析出导入器之后、读取目录中任何文件之前即停止,而不是把目录中的所有文件都交给导入器。

其消息开头为:

the importer serving the source’s format declares no file patterns, so it reads one file and cannot read a directory

消息的其余部分列出格式、导入器以及你所指定的目录,然后给出补救措施:

the importer serving the source’s format declares no file patterns, so it reads one file and cannot read a directory (format "<format>", importer "importer/<name>", directory "<directory>"). Import one of the directory’s files on its own instead; the importer reads a directory once it declares the file patterns its files are named by

如何修复: 单独导入该格式的一个文件。要让导入器读取其格式的目录,其作者需声明其文件的命名模式——即其 describe() 自述中识别签名的 files,并在生成其 Plugin 实体时记录在其中。aggrega-import.md 说明了导入目录时会读取什么。

No file in the directory matches the importer’s file patterns(目录中没有文件匹配导入器的文件模式)

这是在将外部源描述转换为草稿编写文件时的拒绝,而非构建时的拒绝。所指定的源是一个目录,格式已确定,服务于它的导入器也声明了文件模式——但目录中任何深度的文件都不匹配其中任何一个模式。若完全不给导入器任何源,它会因空源而失败,且报错措辞针对内容而非读取了哪些文件,因此导入在此停止,不读取任何内容。

如果格式是识别出来的而非指定的,那么通过签名识别出该目录的导入器已匹配了其中一个文件,因此只有当实际运行的导入器不是它时才会遇到此情况——即由 plugins.importer 条目选中的同一格式的另一个导入器,或它的另一个版本。

其消息开头为:

no file in the directory matches the file patterns the importer serving the source’s format declares

消息的其余部分列出格式、导入器、你所指定的目录以及导入器声明的每个模式,然后给出补救措施:

no file in the directory matches the file patterns the importer serving the source’s format declares (format "<format>", importer "importer/<name>", directory "<directory>", file patterns "<pattern>", "<pattern>"). Name a directory holding a file one of those patterns matches, or the format of an importer whose patterns match the files this directory holds

如何修复: 导入包含该格式文件的目录——模式与文件在目录内路径的末尾进行匹配,因此任何深度的文件都算数——或者指定该目录中文件所属的格式。aggrega-import.md 说明了导入目录时会读取什么。

从目录读取的文件与 importer 的 with.sources 中指定的文件同名

这是在将外部源描述转换为草稿编写文件时的拒绝,而不是构建时的拒绝。所指定的源是一个目录,其文件作为具名源交给导入器,每个文件以其在目录内的路径命名。挂接该导入器的 plugins.importer 条目在 with.sources 下指定了自己的文件,这些文件同样作为具名源交给导入器,每个以其基本名称命名——而有一个名称被两者同时使用。导入器依靠名称区分不同的源,因此把两者都交给它,会使其中一个遮蔽另一个,且无从得知是哪一个;于是导入在此停止,不交出任何内容。

其消息开头为:

a file read from the directory and a file named in the importer’s with.sources have the same name

消息的其余部分会给出该名称和 with.sources 中的文件,然后给出补救方法:

a file read from the directory and a file named in the importer’s with.sources have the same name (name "<name>", the with.sources file "<path>"). Each source reaches the importer under one name, so rename one of the two files, or leave the file out of the importer’s with.sources

**修复方法:**将两个文件之一重命名,或者在目录已包含该文件时,将其从条目的 with.sources 中移除。with.sources 中的文件保留其基本名称,因此与之冲突的是目录顶层的同名文件;位于下级目录中的文件,其名称会带上该目录。哪个导入器将源转换为草稿介绍了条目的 with.sources。

An import’s target names a capability no Recipe in the catalog binds to(导入的目标指定了目录中没有任何 Recipe 绑定的能力)

这是在将外部源描述转换为草稿编写文件时的拒绝,而不是构建时的拒绝。导入被指定了一个目标——aggrega import 上的 --target,或助手导入工具及会话 aggrega/import 方法上的 target——以便起草一个 Manifest,将每个起草出的组件类型映射到该 provider 的一个 Recipe。目标是一种 provider 能力,会与工作区目录中每个 Recipe 所绑定的 spec.capability 进行匹配,而那里没有任何 Recipe 绑定到所给的能力。为它起草的 Manifest 将什么都映射不到,于是每个组件类型都会显示为目录中缺失,而真正出错的是该选项本身——最常见的是拼写错误。

**不运行任何内容,也不写入任何内容。**导入在目录加载完成后、识别源格式之前、导入器运行之前停止,因此不会生成草稿,也不会写入文件,试运行时同样如此。

其消息开头为:

no Recipe in the workspace’s catalog binds to the capability the import’s target names

消息的其余部分会按原样给出 target,以及该目录中 Recipes 实际绑定的 capability(每个只列一次,按排序顺序),然后给出补救办法:

no Recipe in the workspace’s catalog binds to the capability the import’s target names (target "<target>", the catalog’s Recipes bind to "<capability>", "<capability>"). Name one of those capabilities as the target, or leave the target out and no Manifest is drafted; nothing was drafted or written

如果目录中根本没有 Recipe,消息会以此说明代替列表,补救方法是向目录添加该 provider 的一个 Recipe。

**修复方法:**指定消息所列能力之一——例如 compose 或 helm,按 Recipe 的 spec.capability 中的写法——或省略目标,这样不会起草 Manifest。如果你想要的 provider 在目录中还没有 Recipe,请先将其 Recipes 添加到工作区读取的目录文件夹中。aggrega-import.md 介绍了指定目标的导入会起草什么。

A child Release inherits a boundary directory that resolves where its parent writes(子 Release 继承的边界目录解析到其父级写入的位置)

这是一条提示。一个 Release 扩展另一个 Release 并从中继承了某个边界的输出目录,而该目录不含模板变量——因此它对两者解析为同一路径,构建子级时会写入构建父级时写入的位置。

**继承目录是受支持的形态,而不是错误。**目录是一个模板,因此父级只需写一次,而满足某个参数的子级会将其解析到别处,无需任何重复;这正是子级无需重述其父级边界拓扑的原因。这里指出的是一个范围狭窄但真实存在的残留情况:目录中没有变量,就没有任何可以不同地解析的内容。

**它不会停止构建,这是该规则本身的性质,而不是出于谨慎。**写入同一解析路径可能正是作者的合理意图——例如子级只替换渲染用的 Recipes 以比较其输出,或只更改规格大小——因此基于推断而停止的规则会凭猜测拒绝合法输入。

其消息开头为:

inherited boundary directory carries no template variable, so it resolves to the path the extended Release writes to

**修复方法:**如果两者本应写入不同位置,请在目录中放入一个参数引用,并让每个 Release 满足它。如果写入同一路径正是你的意图,则无需更改——该提示已告诉你它将如何处理,无论哪种情况构建都会产生输出。

根据构建打印的短代码查找停止条件

停止构建的诊断信息的方括号开头部分会指明该失败所归属的类别;若该失败对应本页所列的某个条件,还会给出该条件的短代码——字母 E 加四位数字,例如 [CATALOG_ERROR E0209]。编号一经分配便固定不变,因此你粘贴到报告或搜索中的短代码,始终指向你记录它时所指的那个条件。条件所带的另外两个标识符,以及何时该使用三者中的哪一个,详见 sentinels.md。

条件自身的消息行以一个陈述该条件的固定句子开头。该句之后的内容随每次出现而变化——出错的文档、编写的键、违规的值以及针对该次出现的建议——上文各条目引用了其所记录条件的完整形式。固定句子是每次都相同的部分,因此正是应当用于匹配的部分。

下表将两者配对,范围限于本页:对于本页所列的每个条件,列出构建打印的短代码及其消息行开头的句子,并对应上文说明编写修复方法的条目。条目标题按原文引用,因此在本页搜索某个标题即可定位到其条目。所有条件的表可以在编译器声明的所有条件中解析短代码,包括本页没有条目覆盖的条件。

若同一条目对应两个短代码,则它涵盖两个不同的条件,且每个条件都登记了各自的句子;要判断构建报告的是哪一个,请看句子,而不是共用的标题。

aggrega explain <code> 可在终端中替你完成这一查找:它接受条件的任一代码,并打印该条件以及上文记录它的条目。详见 aggrega explain。

短代码开头句子记录于
E0001cliplugin: no plugin resolver configuredA command-line plugin runner was built without a way to find plugins(命令行插件运行器在构建时缺少查找插件的途径)
E0003malformed attachment requirementMalformed attachment requirement(格式错误的附加要求)
E0004annotation contribution overridden by an explicit valueAn explicit value displaced one an annotation supplied(显式值取代了注解提供的值)
E0005policy violationA governance plugin rejected the build(治理插件拒绝了构建)
E0006required attachment slot unfilledRequired attachment slot not bound(必需的附加槽未绑定)
E0007selector violationCross-node type safety violation via selector:(通过选择器产生的跨节点类型安全违规)
E0008attachment slot selector unsatisfiedThe Feature filling an attachment slot does not satisfy the slot’s selector(填充挂载槽的 Feature 不满足该槽的选择器)
E0009pipeline step typed-I/O contract violationA pipeline step’s typed input or output does not satisfy its declared contract(流水线步骤的类型化输入或输出不满足其声明的契约)
E0010pipeline step failedA pipeline step failed(流水线步骤失败)
E0011pipeline patch targets a document not present in the setA pipeline patch addresses a document the set does not hold, or one with no tree to address(流水线补丁指向集合中不存在的文档,或指向没有可寻址树结构的文档)
E0012pipeline patch targets an opaque (non-structured) unitA pipeline patch addresses a document the set does not hold, or one with no tree to address(流水线补丁指向集合中不存在的文档,或指向没有可寻址树结构的文档)
E0013feature type mismatch between Aggregate and ReleaseFeature type mismatch between Aggregate and Release(Aggregate 与 Release 之间 Feature 类型不匹配)
E0014inject entry carries both `value:` and `from:`; schema requires exactly oneAn inject: entry carries both a literal and a source key(一个 inject: 条目同时带有字面值和来源键)
E0015uses-edge inject dictates a delivery mechanism the socket does not permituses edge dictates delivery on a socket that allowlists none(uses 边在未设置允许列表的套接字上指定了投递方式); uses edge dictates a delivery mechanism outside the socket’s allowlist(uses 边指定了套接字允许列表之外的投递机制)
E0016jsonpatch: test operation failedA patch’s test operation did not match the document(补丁的 test 操作与文档不匹配)
E0017annotation-transform plugin output was rejected: an injection targets a component coordinate the host did not supply, or carries a value that is not a string or an object of subkeysAn annotation-transform plugin names a component it was not given, or injects a value no annotation takes(注解转换插件指定了未提供给它的组件,或注入了任何注解都不接受的值)
E0018policy attachment settings do not satisfy the plugin's declared settings schemaA governance attachment’s settings do not match the plugin’s declared schema(治理挂接的设置与插件声明的 schema 不匹配)
E0019endpoint requires form: referenceA workload: form and the fields beside it do not agree(workload: 的 form 与其旁边的字段不一致)
E0020schedule is not a valid cron expressionA workload schedule: is not an expression the check accepts(workload 的 schedule: 不是检查所接受的表达式)
E0021persistentTemplate volume requires form: statefulA workload: form and the fields beside it do not agree(workload: 的 form 与其旁边的字段不一致)
E0022pipeline PATCH target is not parseable structured YAML/JSONA pipeline step addresses documents the node does not have(流水线步骤寻址了节点没有的文档)
E0023form: reference requires an endpointA workload: form and the fields beside it do not agree(workload: 的 form 与其旁边的字段不一致)
E0024schedule requires form: scheduledA workload: form and the fields beside it do not agree(workload: 的 form 与其旁边的字段不一致)
E0025form: scheduled requires a scheduleA workload: form and the fields beside it do not agree(workload: 的 form 与其旁边的字段不一致)
E0026imported artifact content does not match the digest recorded for it in entity.lockAn imported artifact no longer matches the digest recorded beside its Recipe(导入的制品与其 Recipe 旁记录的摘要不再一致)
E0027artifacts $import: is not a bare-name artifact-library reference (<Library>#/artifacts/<entry>)库 $import: 未以裸名称形式书写
E0028artifacts output filename collision: two artifact outputs carry the same filenameTwo artifact outputs of one Recipe carry the same filename(同一 Recipe 的两个 artifact 输出使用了相同的文件名)
E0029artifact template references a pillar the Recipe does not declareAn artifacts: template reads a pillar the Recipe does not declare(artifacts 模板读取了 Recipe 未声明的支柱)
E0030artifact-library import references a bundle not present in the ArtifactLibraryA library $import: names a library or an entry the catalog does not hold(库导入指向的库或条目不在目录中)
E0031artifact-library import references an ArtifactLibrary not present in the catalogA library $import: names a library or an entry the catalog does not hold(库导入指向的库或条目不在目录中)
E0032assembled output collision: two contributors write the same output pathTwo contributors write the same output path(两个贡献者写入同一输出路径)
E0033assertion failedAn assertion stopped the build(断言使构建停止)
E0034duplicate delivery key across attachment-inject and another inject sourceAn attachment delivers a key another inject source already claimed(挂载交付的键已被另一个注入来源占用)
E0035provider expected to assemble its dispatch group provides no boundary assemblerThe plugin serving a provider cannot assemble what that provider combines(服务某个 provider 的插件无法组装该 provider 所合并的内容)
E0036merged-path assembly has conflicting assembly-name annotation valuesChart-name mismatch on a merged helm-chart umbrella(合并的 helm-chart umbrella 上 chart 名称不一致)
E0037cross-boundary link between endpoints rendered by different providers is not supportedA connection crosses between two different providers’ assembled outputs(连接跨越两个不同 provider 的组装输出)
E0038derived name collision: one name is derived more than once in one key spaceThe same name is derived more than once inside the output(输出中同一名称被派生了不止一次)
E0039FeatureRecipe template references a per-component-only field with executionScope: boundaryFeatureRecipe template references a field outside its scope’s allowlist(FeatureRecipe 模板引用了其作用域允许列表之外的字段)
E0040library $import: carries a registry host; reference the library by bare-name identityA library $import: addresses its library by registry location(库导入按注册表位置寻址其库)
E0041multiple contributors share an instance ID at the same dispatch pathInstance-ID collision across boundaries assembling to the same path(组装到同一路径的多个 boundary 之间发生实例 ID 冲突)
E0042locals entry references a sibling defined later in the same blocklocals: entry references a sibling defined later in the same block (locals 条目引用了同一块中稍后定义的同级条目)
E0043template references a key the locals block does not declarelocals: key does not exist(键不存在)
E0044mapping-library import references an entry not present in the MappingLibraryA library $import: names a library or an entry the catalog does not hold(库导入指向的库或条目不在目录中)
E0045valuesMapping $import: is not a bare-name mapping-library reference (<Library>#/mappings/<entry>)库 $import: 未以裸名称形式书写
E0046mapping-library import references a MappingLibrary not present in the catalogA library $import: names a library or an entry the catalog does not hold(库导入指向的库或条目不在目录中)
E0047assembled output retains an unresolved cross-boundary link placeholderAssembled output still carries a cross-boundary placeholder(组装后的输出仍带有跨边界占位符)
E0048dispatch path produced multiple provider outputsPath collision: two contributors emit at incompatible paths(路径冲突:两个贡献者在不兼容的路径上输出)
E0049path template references a field not in the documented allowlistPath-template references a variable outside the allowlist(路径模板引用了允许列表之外的变量)
E0050pipeline /host operation from a step with no host componentA pipeline step addresses documents the node does not have(流水线步骤寻址了节点没有的文档)
E0051pipeline PATCH targets an assembler provider's pre-assembly fragmentsA pipeline patch addresses output that has not been assembled yet(流水线补丁寻址了尚未组装的输出)
E0052pipeline PATCH targets a document the node did not emitA pipeline step addresses documents the node does not have(流水线步骤寻址了节点没有的文档)
E0053pipeline plugin is not compatible with the rendering providerA pipeline step’s plugin does not claim the provider rendering what it addresses(流水线步骤的插件未声明支持渲染其寻址内容的 provider)
E0054provider rejected node inputA provider refused a node’s input(provider 拒绝了节点的输入)
E0055Recipe or FeatureRecipe does not publish a provides key its abstract entity's schema.provides contract declaresA Recipe or FeatureRecipe does not publish a provides key its contract declares(Recipe 或 FeatureRecipe 未发布其契约所声明的键)
E0056provides template evaluation failedA provides: template could not be evaluated(provides 模板无法求值)
E0057provides block references a root outside the self-contained setprovides: template references a non-self-contained root (provides 模板引用了非自包含的根)
E0058provider render is not deterministicA provider rendered the same input twice and produced different output(provider 对同一输入渲染两次产生了不同的输出)
E0059duplicate delivery key across self-inject and uses-injectDuplicate delivery key across inject sources(跨 inject 来源的重复交付键)
E0060template references a root the render context does not defineTemplate references a root the render context does not define(模板引用了渲染上下文未定义的根); Self-inject value template references cross-node data(自注入值模板引用了跨节点数据)
E0061unknown providerUnknown provider(未知的 provider)
E0062custom inject mechanism has no matching key in injectMapping output; add the mechanism's key to the Recipe injectMappingA component declares an inject mechanism the attached Feature maps nothing to(组件声明了已挂接 Feature 未映射任何内容的注入机制)
E0063workload-library import references an entry not present in the WorkloadLibraryA library $import: names a library or an entry the catalog does not hold(库导入指向的库或条目不在目录中)
E0064workload $import: is not a bare-name workload-library reference (<Library>#/workloads/<entry>)库 $import: 未以裸名称形式书写
E0065workload-library import references a WorkloadLibrary not present in the catalogA library $import: names a library or an entry the catalog does not hold(库导入指向的库或条目不在目录中)
E0066uses edge target does not existDangling uses target (悬空的 uses 目标)
E0067active toggle did not resolve to a booleanactive: 开关未解析为 true 或 false
E0068max sub-aggregate nesting depth exceededSub-aggregate nesting depth exceeded(子 aggregate 嵌套深度超限)
E0069mutator patch rejectedlabel-transform 插件的补丁超出了节点标签的范围
E0070re-exported component alias forms a cycleA re-published component alias points back at itself(重新发布的组件别名指回自身)
E0071release edge retargets a developer-declared edgeRelease retargets a developer-declared edge(Release 重新指定了开发者声明的边的目标)
E0072sub-aggregate load failedA module a composition imports cannot be loaded, or imports itself(组合导入的模块无法加载,或导入了自身)
E0073flattened node ID collision: rename one of the colliding instances so their flattened IDs differTwo instances flatten to one identifier(两个实例展平为同一个标识符)
E0074release per-edge configuration has no edge to apply toRelease per-edge configuration has no edge to apply to(Release 逐边配置没有可应用的边)
E0075aggregate reached topology un-normalized (non-empty root components alongside a synthesized default subsystem)An Aggregate reached graph building without being normalised(Aggregate 未经规范化就进入了图构建)
E0076sub-module placed in no boundary: route it into a boundary under `aggregates`, or name its components there under `components`子模块的组件未放入任何边界
E0077uses edge target was pruned because its active toggle resolved to falseuses 边的目标组件已被 active: 开关移除
E0078producer-consumption re-entry denied: a producer reached through the host may not issue a further producer-consumption callA plugin asks the host to parse a source while a parse is already running for it(插件在宿主已为其运行解析时请求宿主解析源)
E0079wasm: recorded command mirror does not match plugin describe()Plugin 实体记录的命令集与插件不匹配
E0080wasm: entity contract claim does not match plugin describe()Plugin 实体的声明与插件自身的自我报告不一致
E0081wasm: guest plugin returned a diagnostic whose severity the contract does not declareA plugin returned a diagnostic at a severity that is not declared(插件返回的诊断使用了未声明的严重级别)
E0082wasm: guest plugin reported an errorA plugin failed while it was running(插件在运行时失败)
E0083wasm: guest plugin panicked during callA plugin failed while it was running(插件在运行时失败)
E0084wasm: stamped host-function record does not match .wasm importsA Plugin entity’s recorded host functions do not match the binary(Plugin 实体记录的宿主函数与二进制文件不匹配)
E0085wasm: plugin rejected by the sandboxThe sandbox refused a plugin(沙箱拒绝了一个插件)
E0086wasm: plugin invoked proc_exitA plugin failed while it was running(插件在运行时失败)
E0087wasm: declared plugin type does not match plugin describe()A plugin is not the kind of plugin the socket expects(插件不是插槽所期望的插件类型)
E0088wasm: entity metadata.version does not match plugin describe()Plugin 实体记录的版本与插件不匹配
E0089every published version this reference could select has been withdrawnEvery version a reference could select has been withdrawn(引用可选择的每个版本都已撤回)
E0090format is advertised by more than one importer pluginA parse or import format is advertised by more than one plugin(某种解析或导入格式由多个插件声明)
E0091format is advertised by more than one parser pluginA parse or import format is advertised by more than one plugin(某种解析或导入格式由多个插件声明)
E0092capability is served by more than one provider plugin; add a plugins.providers entry to select oneA capability is served by more than one provider plugin(某个能力由多个 provider 插件提供)
E0093manifest maps multiple version-distinct keys to the same base type; the type-to-recipe lookup is ambiguousA Manifest maps two version-distinct keys onto one type(某个 Manifest 将两个版本不同的键映射到同一类型)
E0094duplicate entity identity within a single catalog directoryTwo catalog entities in one directory share an identity(同一目录中的两个编目实体共享同一标识)
E0095malformed recipe reference in a Manifest mapping valueManifest mapping value is not a shape a recipe reference accepts(Manifest 映射值的形式不是 recipe 引用所接受的形式)
E0096manifest mapping entry's recipe spec.implements does not match the mapped component-type / feature-type keyRecipe implements does not match the mapped component type(Recipe 的实现声明与所映射的组件类型不匹配)
E0097no importer plugin advertises the requested formatNo plugin advertises a requested parse or import format(没有插件声明所请求的解析或导入格式)
E0098no parser plugin advertises the requested formatNo plugin advertises a requested parse or import format(没有插件声明所请求的解析或导入格式)
E0099no recipe resolved for component/feature instance: add an explicit Manifest mapping for its typeNo Recipe is mapped for a component or feature instance(没有为组件或特性实例映射 Recipe)
E0100plugins.providers entry names a plugin no provider-rendering plugin serving the capability matchesA plugins.providers binding names a plugin that does not serve the capability(该绑定指定的插件不提供此能力)
E0101no provider-rendering plugin version satisfies the recipe's provider version pinNo provider plugin version satisfies a Recipe’s provider pin(没有 provider 插件版本满足 Recipe 的 provider 版本固定)
E0102wasm plugin reference must be the plugin coordinate identity (<pluginType>/<name>:<version>), not a registry-qualified or artifact pathA plugin reference carries a registry host or an artifact path(插件引用带有注册表主机或制品路径)
E0103no catalog version satisfies the referenced version constraintNo catalog version satisfies a version constraint(没有满足版本约束的目录版本)
E0104wasm plugin reference must carry a pluginType scope (<pluginType>/<name>); an empty scope cannot bind to an OCI locationA plugin or recipe reference carries no scope(插件或 recipe 引用缺少作用域)
E0105recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI locationA plugin or recipe reference carries no scope(插件或 recipe 引用缺少作用域)
E0106resolve: invalid library reference URIA library reference is not written in the identity form(库引用未以身份形式书写)
E0107resolve: minimal version selection conflict — incompatible library version requirementsTwo consumers of one library require incompatible versions(同一库的两个使用方要求不兼容的版本)
E0108resolve: catalog lookup cannot load resolved sub-aggregate bodiesThe catalog view a build was given cannot load the bodies pinning needs(提供给构建的目录视图无法加载固定所需的内容主体)
E0109resolve: catalog lookup cannot load resolved recipe and plugin bodiesThe catalog view a build was given cannot load the bodies pinning needs(提供给构建的目录视图无法加载固定所需的内容主体)
E0110resolve: source-template evaluation failure at lock timeResolving a source: coordinate registers a narrower function set(解析 source: 坐标时注册的函数集更窄)
E0111resolve: source-template parse errorResolving a source: coordinate registers a narrower function set(解析 source: 坐标时注册的函数集更窄)
E0112resolve: source-template references .provides (invalid reverse reference)Resolving a source: coordinate registers a narrower function set(解析 source: 坐标时注册的函数集更窄)
E0113resolve: sub-aggregate inclusion depth exceededThe chain of module imports is deeper than the pin walk descends(模块导入链的深度超过了固定遍历所能下探的深度)
E0114resolve: no entity in the catalog matches this URIA reference names no entity the catalog holds(引用指向的实体不在目录中)
E0115compactform: ambiguous dispatch — $mode required紧凑形式的 schema 声明了一个字面名为 type 的字段
E0116compactform: constraint not valid for declared typeA compact-form constraint does not apply to the type it was written on(紧凑格式约束不适用于其所在的类型)
E0117compactform: $jsonschema content invalid$jsonschema: 逃生舱口所含的内容不是 schema
E0118compactform: cross-document $ref carries a registry host; reference the library by identityA $ref: addresses a library by registry location($ref: 通过注册表位置寻址库)
E0119compactform: $ref unresolvableA $ref: is not written in a form the compiler can resolve($ref: 的写法不是编译器能够解析的形式)
E0120compactform: unknown keywordA compact-form schema uses a keyword the compact form does not know(紧凑格式 schema 使用了紧凑格式不认识的关键字)
E0121compactform: cross-document $ref target not foundA $ref: is not written in a form the compiler can resolve($ref: 的写法不是编译器能够解析的形式)
E0122deprecation: build consumes a deprecated entityThe build consumes an artifact its publisher has deprecated(构建使用了其发布者已弃用的制品)
E0123docscache: artifact is not a documentation bundle解析出的制品不是文档包
E0124docscache: page not found in documentation bundle文档包中缺少某个页面
E0125egress: network access refused because the workspace is offline; remediation: pass `--offline=false` to allow the network for this one run, or clear the top-level `offline` key in the configuration file (or AGGREGA_OFFLINE) to allow it from now on; where the work is a build that needs content the machine does not have, run `aggrega pull --release <release>` from a connected environment first to populate the cacheThe workspace is offline and the step needs the network(工作区处于离线状态,而该步骤需要网络)
E0126externalinputs: acquisition is disabled for unpinned inputsA render requests an external input the lockfile does not pin(渲染请求了 lockfile 未固定的外部输入)
E0127externalinputs: fetched bytes mismatch the pinned digestFetched bytes do not match a pinned digest(获取的字节与固定的摘要不匹配)
E0128externalinputs: URL scheme is not allowedAn external input’s URL uses a scheme that is not allowed(外部输入的 URL 使用了不允许的协议)
E0129externalinputs: store blob mismatches its pinned recordA stored external input no longer matches its record(存储的外部输入与其记录不再匹配)
E0130lockfile: out of date; it no longer matches what its Release resolves toThe lockfile no longer matches what the release resolves to(lockfile 不再与 release 解析出的结果一致)
E0131lockfile: file failed schema validationThe lockfile does not satisfy its schema(lockfile 不符合其 schema)
E0132oci: manifest has multiple layers of the expected content media typemanifest 没有预期类型的层,或有多个
E0133oci: cached manifest digest mismatch获取或缓存的字节与为其承诺的摘要不匹配
E0135oci: content digest mismatch获取或缓存的字节与为其承诺的摘要不匹配
E0136oci: network unreachableThe registry could not be reached(无法访问 registry)
E0137oci: artifact not found at remote sourceAn artifact is not at the source the build was told to find it(制品不在构建被告知的来源处)
E0138oci: authentication required or failedThe registry will not serve an artifact without credentials it accepts(没有其接受的凭据,registry 不会提供制品)
E0139oci: tag already published with different contenttag 已以不同内容发布
E0140oci: manifest has no layer of the expected content media typemanifest 没有预期类型的层,或有多个
E0141oci: distinct catalog identities map to the same OCI repository locationTwo catalog identities publish to one repository location(两个目录标识发布到同一个仓库位置)
E0142oci: referrer discovery could not be completedThe registry could not answer what is attached to an artifact(registry 无法回答制品附带了什么)
E0143oci: unknown entity kind for mediatype dispatchAn entity kind has no artifact media type(实体类型没有制品媒体类型)
E0144cached signature bundle does not match its recorded digestA cached signature bundle does not match the digest recorded for it(缓存的签名包与为其记录的摘要不匹配)
E0145plugin reference is not a Plugin entityA plugin reference is not a Plugin entity(插件引用不是 Plugin 实体)
E0146circular reference expansionA library reference expands into itself(库引用展开为自身)
E0147registrytrust: advertised trust config is malformedA registry serves a trust document that cannot be read as one(注册表提供的信任文档无法作为信任文档读取)
E0148registrytrust: registry advertises no trust configA registry publishes no trust document(注册表未发布信任文档)
E0149attachment name is a near miss for a declared slot附件名称与某个已声明的槽只差一次编辑
E0150attachment does not conform to its declared slot shapeAttachment does not conform to its declared slot shape(附加项不符合其声明的槽位结构)
E0151component declared in more than one boundary: declare each component in exactly one boundaryA component is placed in more than one boundary(一个组件被放置在多个边界中)
E0152duplicate Aggregate/Manifest identity (metadata.name) in the Release directoryThe Release directory declares one Aggregate or Manifest twice(Release 目录中重复声明了同一个 Aggregate 或 Manifest)
E0153feature merge conflict: reconcile the Aggregate and Release declarations for the featureA feature attached by both the Aggregate and the Release cannot be merged(同时由 Aggregate 和 Release 附加的功能无法合并)
E0154the compiler's own views of the catalog disagreeA guard needs a catalog entity the build resolved and cannot see(守卫需要一个构建已解析但无法看到的目录实体)
E0155duplicate delivery key across inject sourcesDuplicate delivery key across inject sources(跨 inject 来源的重复交付键)
E0156invalid inject key: the from-key must name a provides key its source publishes注入的 from 键不在目标的 provides 中
E0158invalid parameter reference: check the {{ .parameters.* }} expression names a declared parameter and parses as a Go templateA {{ .parameters.* }} reference cannot be interpolated(无法插值 .parameters.* 引用)
E0160manifest annotation bindings collide on same Feature path+pillarTwo Manifest annotation bindings compete for one routing slot(两个 Manifest 注解绑定争用同一个路由槽位)
E0161manifest annotation binding uses reserved prefixA Manifest annotation binding claims the reserved aggrega.ai/ prefix(Manifest 注解绑定占用了保留的 aggrega.ai/ 前缀)
E0162missing required feature: attach a Feature of the required type to the componentRequired feature not attached(未附加必需的 feature)
E0163required uses socket not populatedRequired uses: socket not populated(必需的 socket 未填充)
E0164parameter contract violatedParameter type mismatch / contract violation (参数类型不匹配 / 违反契约)
E0165required parameter not suppliedParameter type mismatch / contract violation (参数类型不匹配 / 违反契约)
E0167Recipe publishes a provides key its Component does not declareRecipe 发布了其 Component 未声明的 provides 键
E0168authored pillar does not conform to its declared schemaAuthored values or infra do not conform to the declared schema(编写的 values 或 infra 不符合声明的 schema)
E0169self-inject on component without spec.inject allowlistSelf-inject on a component without an allowlist(在没有允许列表的组件上进行自注入); Self-inject mechanism not in the component’s allowlist(自注入机制不在组件的允许列表中)
E0170aggregate/manifest reference unresolvableA Release’s aggregate: or manifest: reference resolves to nothing(Release 的 aggregate: 或 manifest: 引用解析不到任何实体)
E0171unknown uses socket: name a socket the entity declares in its usesSchema — only a component's own uses block may name one the catalog did not declareuses: socket not declared in the owning entity’s usesSchema(socket 未在所属实体的 usesSchema 中声明)
E0172release reached resolve un-normalized (non-empty root components alongside a synthesized default boundary)A Release reached resolution without passing through the load path(Release 未经加载路径就进入了解析)
E0173declared parameter is read by no reference in the Aggregate已声明的参数未被任何内容读取
E0174uses socket name is a near miss for a declared socketuses: 插座名称与某个已声明的插座只差一次编辑
E0175file load failed: the file could not be read, or its bytes did not parseA file cannot be read, or its bytes do not parse(文件无法读取,或其字节无法解析)
E0176signing: keyless signing requires a live identity provider, Fulcio, and RekorKeyless signing was asked for without the services it needs(请求了无密钥签名,但缺少其所需的服务)
E0177signing: no signature found for an artifact that requires oneAn artifact that must be signed carries no signature(必须签名的制品未携带签名)
E0178signing: keyless verification requires at least one trusted identityA keyless trust policy names no acceptable signer(无密钥信任策略未指定任何可接受的签名者)
E0179signing: signature does not verify分离签名无法用所提供的密钥验证
E0180signing: signature bundle does not verifyA signature does not verify(签名验证未通过)
E0181signing: signing policy requires a signature for this artifact kind; refusing to push unsigned contentAn unsigned publish targets a registry or a policy that requires a signature(未签名的发布指向了要求签名的注册表或策略)
E0182signing: cannot load pinned trust rootThe pinned trust root cannot be read(无法读取固定的信任根)
E0183signing: registry requires signatures; refusing to push unsigned contentAn unsigned publish targets a registry or a policy that requires a signature(未签名的发布指向了要求签名的注册表或策略)
E0184signing: unsupported held-key typeA pinned verification key is not the key profile the verifier accepts(固定的验证密钥不属于验证器接受的密钥配置)
E0185signing: signature identity is not trusted for this registryA signature verifies but its signer is not one the registry trusts(签名验证通过,但其签名者不受该 registry 信任)
E0186no source adapter serves the source kindA Recipe’s source: names a kind nothing knows how to acquire(Recipe 的 source 指定了一个无从获取的种类)
E0187cacheslot: empty workspaceRootA source artifact is cached without a workspace root to anchor it(缓存 source 制品时没有可锚定的工作区根目录)
E0188artifacts entry: shape must be a string scalar or {$import: <local-path>}An inline-or-import field is written in neither shape(内联或导入字段未按两种形状中的任何一种书写)
E0189artifactlibrary: entry must be a mapping of filename to a string bodyA library entry’s body is not the shape that library holds(库条目的主体不是该库所容纳的形状)
E0190schemalibrary: forbidden JSON Schema keywordA schema uses a JSON Schema keyword the library does not admit(schema 使用了库不允许的 JSON Schema 关键字)
E0191mappinglibrary: entry body must be a string scalarA library entry’s body is not the shape that library holds(库条目的主体不是该库所容纳的形状)
E0192a document nests too many levels deepA document nests deeper than the reader will descend(文档嵌套层级超过读取器允许的深度)
E0193parameters: shape must be an inline object or {$import: <local-path>}Release 的 parameters: 块不符合其两种形式中的任何一种
E0194schemalibrary: template not found无法解析 $instantiate: 引用
E0195schemalibrary: template parameter missing无法解析 $instantiate: 引用
E0196schemalibrary: template parameter type mismatch无法解析 $instantiate: 引用
E0197valuesmapping: shape must be a string scalar or {$import: <path-or-library-identity>}An inline-or-import field is written in neither shape(内联或导入字段未按两种形状中的任何一种书写)
E0198wellKnownAnnotations: a key is declared at a scope the provider's contract does not renderA provider declares a well-known annotation at a scope it does not render(provider 在其不渲染的作用域上声明了 well-known 注解)
E0199workloadlibrary: entry body must be a string scalarA library entry’s body is not the shape that library holds(库条目的主体不是该库所容纳的形状)
E0200workload: shape must be a string scalar or {$import: <path-or-library-identity>}An inline-or-import field is written in neither shape(内联或导入字段未按两种形状中的任何一种书写)
E0201assertion name declared twice across the extends chain同一断言名称在 extends: 链上被声明了两次
E0202cyclic extends chainCyclic extends chain(循环的 extends 链); Cyclic extends on Components or Features(Components 或 Features 上的循环 extends)
E0204FeatureRecipe: valuesMapping requires sourceA FeatureRecipe’s valuesMapping requires source(FeatureRecipe 的 valuesMapping 需要 source)
E0205inheritance merge failed无法组装 extends: 链
E0207recipe output-component-labels constraint: key is also declared in outputLabelsA promoted component label is also declared literally(提升的组件标签也被字面声明)
E0208recipe output-labels constraint: key uses a reserved namespaceAn output-label key uses a reserved namespace(输出标签键使用了保留命名空间)
E0209Recipe: valuesMapping requires sourcevaluesMapping requires source(valuesMapping 需要 source)
E0210Recipe: at least one input kind requiredAt least one input kind must be present(必须至少存在一种输入类型)
E0211filename collision across input kinds: two input-kind blocks produced a file under one output nameEmission-time filename collision across input kinds(输出时跨输入类型的文件名冲突)
E0212workload attachment slot is not referenceableA Workload references a slot whose fill publishes no locator(Workload 引用的插槽,其填充未发布定位符)
E0213workload featuresSchema cross-check failedA Workload attachment names a slot the entity does not declare, or a delivery the slot forbids(Workload 附件指定了实体未声明的插槽,或插槽禁止的交付方式)
E0214workload validation failedA Workload does not satisfy the Workload schema(Workload 不满足 Workload schema)
E0215document envelope validation failedYAML anchor aliased inside its own content(YAML 锚点在其自身内容中被别名引用); Divergent Release (extends + aggregate pointer)(分歧的 Release(extends + aggregate 指针))
E0216validator/jsonschema: x-aggrega extension evaluation failedAn x-aggrega-when: or x-aggrega-validate: predicate cannot be evaluated(x-aggrega-when: 或 x-aggrega-validate: 谓词无法求值)
E0218validator/jsonschema: schema resolution failedA declared schema cannot be resolved(声明的 schema 无法解析)
E0220extends chain exceeds maximum depthextends: 链超出深度上限
E0221merger: invalid merge inputschema 合并步骤自身的输入保护
E0222registry alias matches more than one hostA registry alias matches more than one host(注册表别名匹配多个主机)
E0223a cross-cutting socket is bound by capability but attaches by uriA plugin binding sets a key the socket it attaches to does not read(插件绑定设置了其所挂接的插槽不读取的键)
E0224workspace configuration is invalidThe workspace configuration is invalid(工作区配置无效)
E0225capability is bound to more than one provider pluginA capability is bound to more than one provider plugin(一个能力绑定到了多个 provider 插件)
E0226registry alias is already used by another hostA registry alias is already bound to another host(注册表别名已绑定到另一个主机)
E0227a governance attachment declares no role or an unknown roleA governance attachment declares no role, or one that is not a known role(治理挂载未声明角色,或声明了未知角色)
E0228a provider socket binding sets a field with no referent on that socketA plugin binding sets a key the socket it attaches to does not read(插件绑定设置了其所挂接的插槽不读取的键)
E0229position out of rangeAn editor position falls outside the document(编辑器位置超出文档范围)
E0246the digest recorded as trusted for this plugin does not match the digest its cached manifest reportsA trusted plugin’s recorded digest disagrees with the cached artifact(受信任插件的记录摘要与缓存的制品不一致)
E0247a plugin recorded as trusted for an accept-or-reject verdict is no longer attached at any verdict roleA plugin recorded as a trusted gate is no longer attached(记录为受信任门禁的插件已不再挂接)
E0248wasm: guest plugin returned an output that is not the shape the socket readsA plugin returned something that is not the shape the socket reads(插件返回的内容不是插槽所读取的结构)
E0250provider named a directory for each contributor's own sub-directory that is not a single directory nameA provider named a directory for a contributor that is not one directory(provider 为贡献者指定的目录不是单个目录)
E0251recipe source is an empty string, which names neither sourceless mode nor sourced modeRecipe source: is an empty string(Recipe 的 source 字段为空字符串)
E0252artifact-library bundle file name does not name a file of its own beneath the artifacts key its output is nested underAn ArtifactLibrary bundle file names no file of its own under the key it was imported at(ArtifactLibrary bundle 文件在其导入所在的键下未指定属于自己的文件)
E0253annotation binding does not resolve against its target FeatureAnnotation binding does not resolve against its target Feature(注解绑定无法针对其目标 Feature 解析)
E0254annotation subkey does not conform to the target Feature's schema at the routed pillarA bound annotation value does not conform to the target Feature’s schema(绑定的注解值不符合目标 Feature 的 schema)
E0255annotation routes through a pillar its authoring side may not useAn annotation routes through a pillar its authoring side may not use(注解经由其编写侧不得使用的支柱进行路由)
E0256annotation binding declares one path in both pillar lists注解绑定在两个支柱列表中声明了同一路径
E0257declared schema contract could not be compiled into a usable schema, so nothing was validated against it: correct the contract where it is declared, or remove it if the configuration it covers needs no validationA declared schema contract cannot be read as a schema(声明的 schema 契约无法作为 schema 读取)
E0259attachment binds a FeatureRecipe with executionScope: boundary and no boundary holding the component declares itA boundary-scope Feature is attached only to a component(边界作用域的 Feature 仅附加在组件上)
E0260component placed in no boundary: name it under a boundary's `components`, or place the sub-module that contributes it under `aggregates`A component the composition holds is placed in no boundary(组合中的某个组件未放入任何边界)
E0261boundary names a component the composition does not hold: correct the name, or remove the entry边界点名了组合中不存在的组件
E0262component identity cannot be the name its emitted resources are stamped with: rename the componentComponent identity cannot be stamped on what it emits(组件标识无法标记到其发出的资源上)
E0263the target will not accept a name derived from this component's authored identity: rename the componentThe target will not accept a name derived from an authored identity(目标不接受由编写的标识派生的名称)
E0264provider guest never accepted a component identity the compiler composed for itA provider never accepted a name the compiler composed(provider 始终不接受编译器组合的名称)
E0265provider does not support the node's input kindworkload: requires a provider that can synthesize(workload: 需要能够进行合成的 provider)
E0266a schema `$import:` could not be appliedA schema $import: cannot be applied(无法应用 schema 导入指令)
E0267a schema block declares a key that names no data pillarA schema block names a key that is not a data pillar (schema 块中出现了不是数据支柱的键)
E0268reassemble names a patched unit token the carve did not produce; a conforming codec carves and reassembles a file under the same tokensA provider’s reassembly is handed a unit its own carve never produced(provider 的重组收到了其自身切分从未产生的单元)
E0269provider guest returned two output files under one path; a conforming guest returns each output path at most onceA provider returned two output files under one path(提供者在同一路径下返回了两个输出文件)
E0270link patch names an output file the dispatch group did not emit; a conforming link patch names a file the group's own render returnedA provider’s link wiring names an output file that was never emitted(provider 的链接连线指向一个从未输出的输出文件)
E0271emit_file side effect carries no file; a conforming emit_file side effect carries a file with its path and contentA pipeline step’s file emission carries no file(流水线步骤的文件输出未携带文件)
E0272side effect declares a kind the plugin contract does not define; a conforming side effect declares emit_file or emit_crdA pipeline step declares an emission kind the contract does not define(流水线步骤声明了契约未定义的输出类型)
E0273template reads the name the target gives the resources it renders for the node, and this node's provider reports no such name; a conforming template reads a value the node's own provider suppliesA template reads a rendered name the node’s provider does not report(模板读取了节点的 provider 未报告的渲染名称)
E0274the plugin identity recorded as trusted no longer matches what this resolution reportsA gate recorded as trusted resolves to a different identity(记录为受信任的门禁解析到了不同的身份)
E0275the edit was refused because the resulting document would not be valid, and nothing was written编辑会生成其 schema 拒绝的文档
E0276the version being published changes the published predecessor in a way the documented evolution rubric objects to正在发布的变更超出了演进准则允许的范围
E0277an annotation key on the entity uses a prefix the platform reserves注解键使用了平台保留的前缀
E0278the entity's name does not follow the documented name shape for its kind实体名称不符合其类型预期的形式
E0279a schema in the entity uses a dynamic reference construct that cross-document reference resolution cannot followschema 使用了无法提前解析的动态引用
E0280a schema in the entity declares an identifier of its own, where the platform owns that schema's identityschema 声明了平台所拥有的标识符
E0281the entity's category label does not match the category directory the entity is filed underComponent 的类别标签与其所在目录指明了不同的类别
E0282the entity writes an Aggrega schema extension directly into schema content instead of declaring it under usesSchema or featuresSchemaschema 扩展被直接写入 schema 内容
E0283the Plugin entity declares no runtime resource cap of its own, so the platform defaults applyPlugin 未固定任何运行时上限,因此采用平台自身的上限
E0284an attachment slot admits only secret material and does not declare that it handles itattachment 槽位只接受机密材料,却未声明它会处理机密
E0285the Recipe publishes a provides key the Component it implements does not declare, so a consumer wiring that key is refusedRecipe 发布了其 Component 未声明的 provides 键,在发布时检查
E0286the version bump being published is smaller than the evolution check's classification of the change requires提供的版本升级幅度小于变更所要求的幅度
E0287the importer reported a diagnostic that stops the import, so the source was not fully turned into draft authoring files导入在转换源的过程中途停止
E0288a plugin has no expression for a construct this build declaresA workload declares a form compose cannot express(workload 声明了 compose 无法表达的形式); A container declares a field compose has no primitive for(容器声明了 compose 没有对应原语的字段); An omits entry names a kind or a namespace a compose file does not have(omits 条目指定了 compose 文件中不存在的类型或命名空间); An omits entry names a namespace a CloudFormation template does not have(omits 条目指定了 CloudFormation 模板中不存在的命名空间); A rule reads a bound CloudFormation parameter by name(规则按名称读取已绑定的 CloudFormation 参数); The assembled CloudFormation stack cannot carry a transform(组装出的 CloudFormation 堆栈无法携带 transform)
E0289a plugin could not resolve something it requires to exactly one valueA health probe cannot be turned into a compose healthcheck(健康探针无法转换为 compose healthcheck); A configmap volume has no file behind it(configmap 卷背后没有文件); What an omits entry left out is still named by the compose file(omits 条目排除的内容仍被 compose 文件引用); What an omits entry left out is still named by a CloudFormation template(omits 条目排除的内容仍被 CloudFormation 模板引用); A valuesMapping key names no parameter of a sourced CloudFormation template(valuesMapping 键未指向所引入 CloudFormation 模板的任何参数); Another component references a CloudFormation parameter a sourced template’s binding filled(另一个组件引用了由所引入模板的绑定填充的 CloudFormation 参数); Two components order one pair of transforms oppositely(两个组件以相反顺序排列同一对 transform); A cross-boundary reference has no consuming stack to be written into(跨边界引用没有可写入的消费堆栈); A synthesized StatefulSet has no single service to govern it(合成的 StatefulSet 没有唯一的 service 来管理它)
E0290two things a plugin produced occupy one name in its outputAn authored export name is one the build derives for a cross-stack reference(编写的导出名称与构建为跨堆栈引用派生的名称相同); The output a cross-stack reference publishes on already carries an Export(跨堆栈引用所发布到的输出已带有 Export); Two entries reach one stack output name(两个条目指向同一个堆栈输出名称); A CloudFormation fragment writes one key twice(CloudFormation 片段将同一个键写入两次); Two rendered resources land at one output file(两个渲染出的资源落在同一个输出文件中)
E0291a plugin has no representation for a value it was givenA published port declares a transport compose cannot spell(发布的端口声明了 compose 无法表示的传输协议); A resources quantity cannot be converted to a compose value(resources 数量无法转换为 compose 值); A resource quantity the helm provider emits is not a quantity(helm provider 输出的资源数量不是有效数量); A service type the helm provider cannot render(helm provider 无法渲染的 service 类型); A Kubernetes version the helm provider cannot render a chart for(helm provider 无法为其渲染 chart 的 Kubernetes 版本); A value bound to a CloudFormation parameter cannot take the parameter’s type(绑定到 CloudFormation 参数的值无法采用该参数的类型); A value bound to a CloudFormation parameter is one its constraints refuse(绑定到 CloudFormation 参数的值被其约束拒绝); A secret bound to a CloudFormation parameter would be written into the template(绑定到 CloudFormation 参数的 secret 会被写入模板); A dynamic reference is bound where CloudFormation does not resolve it(动态引用被绑定在 CloudFormation 不解析它的位置); A cross-boundary reference was spliced into a longer string(跨边界引用被拼接进了更长的字符串)
E0292a plugin reported a failure that none of the declared kinds namesA plugin reported a failure it did not classify(插件报告了一个未分类的失败)
E0293wasm: guest plugin named a condition the socket does not declareA plugin named a condition the socket does not declare(插件指明了 socket 未声明的条件)
E0294components in different subsystems take the same identity: rename one of them, since a subsystem contributes nothing to a component's identityTwo subsystems declare a component under one name(两个子系统以同一名称声明组件)
E0295library reference: a reference to a library entry carries no whitespace or line breakA reference to a library entry carries whitespace(对库条目的引用包含空白)
E0296release extends chain composes both named boundaries and top-level components: declare one routing shape across the chain, never bothRelease 链中的各环节对路由形态的选择不一致
E0297inherited boundary directory carries no template variable, so it resolves to the path the extended Release writes toA child Release inherits a boundary directory that resolves where its parent writes(子 Release 继承的边界目录解析到其父级写入的位置)
E0298oci: published bundle carries no entity documentA published bundle holds no entity, or holds two(已发布的包中没有实体,或有两个实体)
E0299oci: published bundle carries more than one entity documentA published bundle holds no entity, or holds two(已发布的包中没有实体,或有两个实体)
E0300oci: published bundle cannot be unpackedA published artifact cannot be read as an entity(已发布的制品无法作为实体读取)
E0301oci: published artifact is not an entity documentA published artifact cannot be read as an entity(已发布的制品无法作为实体读取)
E0302an input the entity reads has no pin recorded for it in the entity.lock beside itAn entity reads an input the lock beside it records no pin for(实体读取了其旁锁文件未记录固定值的输入)
E0303the entity shares its directory with another entity, and an entity of its kind has a directory of its own实体与另一个实体共用目录
E0304a path names content outside the entity's own directoryA path names content outside the entity’s own directory(路径指向实体自身目录之外的内容)
E0305the files of the entity's local source do not match the pins recorded for them in entity.lockA local source no longer matches the pins recorded beside its Recipe(本地源与其 Recipe 旁记录的固定值不再匹配)
E0306plugin artifact not found on this machineA plugin’s .wasm is not on this machine(插件的 wasm 模块不在本机上)
E0307a value a cache location is built from would place cached files outside the place it names in the cacheA value would place a cached file outside the cache(某个值会把缓存文件放到缓存之外)
E0308a Feature reaches a component alongside a Feature it declares a conflict withTwo Features declared to conflict reach one component(两个声明为冲突的 Features 到达同一个组件)
E0309a symbolic link sits among the files an entity carriesA symbolic link sits among the files an entity carries(实体携带的文件中存在符号链接)
E0310a registry other than the official hub is not registered offline without a trust policy supplied by hand, because the policy it advertises cannot be fetched; register it once while online, or pin its trust by hand with `aggrega registry add <host> --identity <identity>=<issuer>` or `--key <public-key-file>`离线添加 registry 时没有可固定的信任策略
E0311reference carries a malformed version pinA version pin is none of the forms a pin takes(版本锁定不属于任何一种锁定形式)
E0312a provider socket binding names a capability containing a colon, which no Recipe can selectA provider binding names a capability containing a colon(provider 绑定指定的能力包含冒号)
E0313plugins.providers entry names a capability no provider-rendering plugin the build reads servesprovider 绑定指定了构建所读取的任何插件都不提供的能力
E0314plugin was built from a working tree with uncommitted changes, so no commit reproduces the version it reportsA plugin was built from a working tree with uncommitted changes(插件是从带有未提交更改的工作树构建的)
E0315a connection carries an attachment under a name its socket declares no slot forA connection carries an attachment under a name its socket declares no slot for(连接以其插槽未声明槽位的名称携带附件)
E0316a Release attachment takes the name of an attachment one of a component's connections carriesA Release attachment takes the name of a connection’s attachment(Release 附加项占用了某个连接的附加项名称)
E0317a Release connection attachment names no Feature type, and the type is required for an attachment only the Release makesA Release connection attachment names no Feature type(Release 连接附加项未指定 Feature 类型)
E0318duplicate delivery key across two attachments: an attachment's FeatureRecipe writes a delivery key another attachment already deliveredTwo attached Features deliver one key, the later through its FeatureRecipe’s injectMapping(两个挂载的 Feature 交付同一个键,后者通过其 FeatureRecipe 的 injectMapping)
E0319connection alias is already used by another connection of the same componentTwo connections of one component under one alias(同一组件的两个连接使用同一别名)
E0320a path this operation writes or deletes leads through a link out of the directory it must stay insideA path the operation writes leads through a link out of the directory it must stay inside(操作写入的路径经由链接通向其必须保持在内的目录之外)
E0321a file this operation reads leads through a link out of the directory it must stay insideA file the operation reads leads through a link out of the directory it must stay inside(操作读取的文件通过链接指向了它必须留在其内的目录之外)
E0323template reads its callers' render facts, but the FeatureRecipe does not set readsCallerRenderFactsA template reads its callers’ render facts without declaring it(模板读取了调用方的渲染事实但未声明)
E0324a reference a document makes to another file leads out of the directory it must stay insideA reference to another file leads out of the directory it must stay inside(对另一文件的引用指向了它必须留在其中的目录之外)
E0325provider guest reported a render fact whose value is not a list; a conforming guest reports every render fact's value as a JSON array, even with one entryA provider reported a render fact whose value is not a list(provider 报告的渲染事实的值不是列表)
E0326pipeline step reads its callers' render facts, but a pipeline step does not read the components connecting to its host; it reads only the host's own render factsA pipeline step reads its callers’ render facts(流水线步骤读取其调用方的渲染事实)
E0327template indexes a map with a key the map does not holdA template indexes a map with a key the map does not hold(模板使用映射中不存在的键索引该映射)
E0328attachment written under a name no slot declares fits a slot its component leaves emptyAn attachment written under another name fits a slot its component leaves empty(以其他名称编写的挂载适合其 component 留空的槽)
E0329a connection and the target it reaches do not name one key: they write different locators for it, or only one of them names one连接与其到达的目标未指向同一个密钥
E0330signing: the references named together need different signing credentials, so nothing was signed一起签名的引用需要不同的签名凭据
E0331signing: no verified signature is recorded for an artifact that requires oneNo verified signature is recorded for an artifact that requires one (要求签名的制品未记录已验证的签名)
E0332signing: the recorded signature was made for a different artifactA recorded signature was made for a different artifact(记录的签名是为另一个制品生成的)
E0333signing: a recorded signature is not the one a pull would recordA recorded signature is not the one a pull would record(记录的签名不是 pull 将记录的签名)
E0334an omits entry left out nothing the source renderedAn omits entry left out nothing the source rendered(omits 条目没有排除任何源渲染的内容)
E0335provider does not support omitsThe provider does not support omits(provider 不支持 omits)
E0336a provider's omitted counts do not match the omits entries it was handedA provider’s omitted counts do not match the omits entries it was handed(provider 的省略计数与交给它的 omits 条目不匹配)
E0337no importer plugin version satisfies the plugins.importer entry's version pinA plugins.importer entry pins a version of its importer the catalog does not hold(该条目固定了目录中不存在的导入器版本)
E0338importer is attached by more than one plugins.importer entryAn importer is attached by more than one plugins.importer entry(一个导入器被多个 plugins.importer 条目附加)
E0339more than one importer recognises the sourceMore than one importer recognises the source(不止一个导入器识别出该源)
E0340a name this operation writes holds a path segment Windows cannot hold as writtenA name the operation writes holds a part Windows cannot hold(操作写入的名称含有 Windows 无法容纳的部分)
E0341the importer serving the source's format declares no file patterns, so it reads one file and cannot read a directoryAn importer that declares no file patterns is handed a directory(未声明文件模式的导入器被交给了一个目录)
E0342no file in the directory matches the file patterns the importer serving the source's format declaresNo file in the directory matches the importer’s file patterns(目录中没有文件匹配导入器的文件模式)
E0343a file read from the directory and a file named in the importer's `with.sources` have the same name从目录读取的文件与 importer 的 with.sources 中指定的文件同名
E0344an entry this publication carries cannot be used on WindowsA published archive carries an entry Windows cannot use(发布的归档包含 Windows 无法使用的条目)
E0345a container declares one environment variable twiceA container gives one environment variable two values(一个容器为同一个环境变量赋了两个值)
E0346a Component's annotation stating how its metrics authenticate disagrees with whether it declares the provides key saying an instance's metrics need a credentialComponent 的指标注解与其 provides 键不一致
E0347template reads the render facts of a component its host is wired to, but the FeatureRecipe does not set readsTargetRenderFactsA template reads its targets’ render facts without declaring it(模板未声明即读取其目标的渲染事实)
E0348pipeline step reads the render facts of a component its host is wired to, but a pipeline step reads only the host's own render factsA pipeline step reads its targets’ render facts(流水线步骤读取其目标的渲染事实)
E0349no Recipe in the workspace's catalog binds to the capability the import's target namesAn import’s target names a capability no Recipe in the catalog binds to(导入的目标指定了目录中没有任何 Recipe 绑定的能力)
E0350no importer recognises the sourceNo importer recognises the source(没有导入器识别出该源)
E0351provider does not support boundary artifactsThe provider does not support boundary artifacts(provider 不支持 boundary artifacts)
E0352boundary output directory does not name a directory beneath the output rootA boundary’s output directory is not a directory beneath the output root(boundary 的输出目录不是输出根目录下的目录)
E0353boundary-level Feature instance name is not a directory nameA boundary-level Feature is named . or ..(边界级 Feature 的名称为单点或双点)
E0354a template does more than copy a value it reads off a cross-boundary linkA template did more than copy a value it read off a cross-boundary link(模板对从跨边界链接读取的值所做的不只是复制)
E0355inject delivery: shape must be a list of entries, each `in:` with exactly one of `from:` or `value:`An inject: delivery is not a list of entries(注入交付不是条目列表)
E0356suspend requires form: scheduledA workload suspend: is set on a form other than scheduled(workload 的暂停字段设置在定时以外的形式上)
E0357a Manifest name mapping's key names no component instance or attachment in this build, so the entry binds nothingA Manifest name mapping names nothing in the build(Manifest 的 name 映射未指向构建中的任何内容)
E0358uses edge target names a component its module does not exportA uses target names a module’s component the module does not export(uses 目标指向了模块未导出的组件)
E0359no source adapter is registered in this program for the source kindNo source adapter is registered in this program for a source kind(本程序中没有为某个源类型注册 source adapter)
E0360the netrc file could not be readThe netrc file cannot be read(无法读取 netrc 文件)
E0361the source URL carries a credentialA source URL carries a credential(源 URL 携带了凭据)
E0362inject entry on a connection carries `value:`; a connection delivers the target's published keys, each named with `from:`An inject: entry on a connection carries a literal(连接上的注入条目携带字面值)
E0363annotation subkey is not routed by the annotation's bindingAn annotation subkey is not routed by its binding(注解子键未被其绑定路由)
E0364a value template failed while it ranA value template failed while it ran(值模板在运行时失败)
E0365boundary-level Feature's output is routed to a dispatch path nothing assemblesA boundary-level Feature’s output reaches no assembled file(边界级 Feature 的输出未进入任何组装文件)
E0366FeatureRecipe injectMapping output could not be read as a dictionary of deliveriesAn attached Feature’s injectMapping output cannot be read(已附加 Feature 的 injectMapping 输出无法读取)
E0367a scalar annotation value does not route to exactly one path of its bindingA bare annotation value does not route to exactly one path of its binding(裸注解值未能路由到其绑定中恰好一条路径)
E0368FeatureRecipe injectMapping output writes a key no delivery mechanism of the host readsAn attached Feature’s injectMapping output writes deliveries under a key nothing delivers(已附加 Feature 的 injectMapping 输出将交付项写在一个不会交付任何内容的键下)
E0369template reads a path as a value and iterates it, and the data holds nothing at that pathA template reads and iterates a path that holds nothing(模板读取并迭代一个不包含任何内容的路径)
E0370a pipeline declares one step id twiceA pipeline declares one step id twice (流水线将同一个步骤 id 声明了两次)
E0371catalog document declares a kind a catalog does not holdA catalog document declares a kind a catalog does not hold (catalog 文档声明了 catalog 不包含的种类)
E0372inject entry on an attachment carries `value:`; an attachment delivers the keys its FeatureRecipe publishes, each named with `from:`, and a literal belongs in the component's own inject blockAn inject: entry on an attached Feature carries a literal(附加 Feature 上的注入条目携带了字面值)
E0373a document declares an API version this compiler no longer readsA document declares an API version this compiler no longer reads(文档声明了此编译器不再读取的 API 版本)
E0374a plugin declares a plugin ABI version this compiler no longer speaksA plugin declares a plugin ABI version this compiler no longer speaks(插件声明了此编译器不再支持的插件 ABI 版本)
E0375oci: artifact carries a media type this compiler no longer readsAn artifact carries a media type this compiler no longer reads(制品带有此编译器不再读取的媒体类型)
E0376egress: the server did not answer in timeA server did not answer in time (服务器未及时应答)
E0377registry: the repository listing did not end in timeA registry’s repository listing did not end in time (注册中心的仓库列表未及时结束)
E0378oci: the registry kept asking to slow downA registry kept asking to slow down (注册表持续要求放慢速度)

linter 领域(非致命)

编译器对执行严格不预设立场。对于仅仅可疑的模式——未使用的值、孤立的 secret、未连接的目标——它从不中止构建。这样的模式至多引出一条提示:对于上文“不会中止构建的情况”中收录的少数几种(例如没有任何内容读取的已声明参数),是构建自身的提示;其余的则属于 linter 领域,企业可以选择启用 Wasm 插件来强制执行其自身的约定。

孤立的凭据

挂载了凭据 Feature 却没有 inject: 交付契约,并不是编译错误。核心编译器在 IR 图中保留该声明,且不发出警告。企业的 linter 插件可以检测此模式并发出警告;企业的渲染器也可以选择按照其自身的 Black-Box 约定隐式挂载孤立的 secret。由于两种解释都成立,核心编译器不偏向任何一方。