错误转换规范
Aggrega 的编译流水线会从许多层面产生错误:schema 校验器、解析器、IR 构建器、各个 provider、Go 模板引擎,以及 provider 所封装的底层 YAML / Helm / docker-compose 库。冒泡到 CLI 的错误以一个方括号头部开始,其中最多指明两项内容:一个类别,说明应关注哪个方面(对大多数取值而言,即出错的编写层面);以及导致构建中止的条件的短代码。头部之后是源位置指针和一条消息。当条件由插件引发时,代码会以引发它的插件加以限定,因为不止一个插件可能报告同一个条件。本页说明该输出的格式,以便作者能直接理解错误消息。
逐条错误目录(每个致命中止及其修复指导)见 fatal-halts.md。四个 schema 校验层及其错误格式之间的相互关系见 vocabulary/validation-surface.md。
错误类别
类别标签指明应关注哪个方面。大多数类别指向需要修复的编写面;其余类别指向并非任何人编写失误的方面——获取制品、治理裁决,或信任与签名——而在每种情况下,头部中类别旁边的短代码才是标识具体条件的依据:
[DEVELOPER_ERROR]—— 故障归属于 Aggregate 的编写。修复位置在 Aggregate YAML 中,或在目录中由开发者编写的部分(Component 的 values、uses插座、Feature 挂载)。示例场景:解析器因 Aggregate 侧问题而停止;Aggregate 所写内容违反选择器和appliesTo。[OPS_ERROR]—— 故障归属于运维人员自己的文档,即 Release 和 Manifest。修复位置在 Release YAML 中(边界拓扑、参数值、Release 级别的 Feature 挂载),或在 Manifest YAML 中(某个类型通过哪个 Recipe 部署,以及写在其旁的注解绑定)。示例场景:Release schema 校验;边界路径模板求值;跨 provider 的subDirectory冲突;Manifest 映射和注解绑定被拒绝;规则拒绝 Release 连接的某个连接,或拒绝它在连接上填充的挂载——插座的选择器、槽的选择器、插座声明为必需的槽;规则拒绝仅由 Release 挂载到组件或边界上的 Feature——该 Feature 的appliesTo、槽的选择器、其声明的 schema。[CATALOG_ERROR]—— 故障归属于某个目录实体(Recipe、FeatureRecipe、Component、Feature、Plugin)。修复位置在目录内容中。示例场景:Recipe 形态规则;WorkloadfeaturesSchema交叉检查;目录编写的模板中的模板解析错误。[TRANSLATION_ERROR]—— 故障归属于 provider 侧的合成(provider 插件尝试将 Workload、valuesMapping 输出或来源覆盖层转换为 provider 原生制品)。修复位置通常在 Workload 的services/containers/volumes形态、Recipe 的valuesMapping模板输出,或源模式覆盖层结构中。[FETCH_ERROR]—— 故障归属于从注册表或远程源获取已固定的依赖,而不归属于任何编写面。修复通常属于运维操作:向注册表认证(docker login <registry>)、恢复连接,或重新固定已漂移或被篡改的制品(aggrega pull --upgrade --release <release>)。示例场景:在注册表中找不到目录实体或 chart;需要认证或认证失败;网络不可达;缓存制品的摘要与锁文件不匹配。获取错误会在消息中给出具体的修复指引。[POLICY_ERROR]—— 构建被挂载在治理裁决角色上的策略插件拒绝。这不是编写面的故障:输入格式正确,但未通过该插件强制执行的治理规则(合规、FinOps 或安全)。修复方法是使你编写的内容符合所强制执行的策略,或重新考虑该策略的挂载。消息会指出拒绝的插件,并附带它提供的规则消息。[TRUST_ERROR]—— 信任与签名层拒绝了该操作。该类别指向一个方面而非编写面,它涵盖两种修复方式,可通过旁边的短代码加以区分。**你的信任配置有误:**信任策略无法读取、已固定的信任根无法加载、无密钥策略未声明任何可信身份、签名策略要求你正在发布的制品类型带有签名,或某个插件被记录为某个裁决挂载的可信插件,而你的配置已不再挂载它。**该制品未通过验证:**签名无法通过信任锚验证、制品在需要签名时未携带签名、签名来自真实但不受信任的签名者,或插件记录的可信身份与实际解析结果不再匹配。第一种情况的修复位置在你的配置或已提交的信任记录中;第二种情况则需要对制品做出决定——恢复已审查的版本,或审查变更内容并重新记录。
关于 Feature 挂载的发现归属于写入它的文档
Feature 可以在任一文档中挂载——Aggregate 将其挂载在组件或子系统上,Release 将其挂载在某个组件的条目或边界上——因此,关于挂载的发现,其类别取决于挂载的写入位置,而不是它所作用的组件。该发现定位在写入该挂载的文档中的 features: 条目,并归入该文档的作者名下:仅由 Release 做出的挂载在 Release 自己的路径上报告为 [OPS_ERROR],由 Aggregate 做出的挂载在 Aggregate 的路径上报告为 [DEVELOPER_ERROR]。
[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 指定其 Feature,Release 确定其规模——关于整个挂载的发现定位在其 Feature 被指定的位置,即 Aggregate。关于其配置某一部分的发现定位在该部分的写入位置:其 values 属于开发者,在 Aggregate 中;其 infra 属于运维人员,在 Release 中。由注解驱动的展开所产生的挂载并非由任何 features: 条目写入,因此关于它的发现定位在组件上,即声明该组件的文档中,类别为 [DEVELOPER_ERROR]。
**留空的必需槽是唯一没有任何文档写入的情况。**没有可指向的挂载,因此该发现停留在 Aggregate 中的组件上,归为 [DEVELOPER_ERROR],其修复建议同时提及两个文档,因为任一文档都可以填充该槽:“在 Aggregate 或 Release 中,于该组件上或其上层作用域,以该名称挂载一个 Feature。”
编辑器采用相同的定位:定位在 Release 中的发现显示在 Release 的文档上、写入它的键上,而完全不显示在 Aggregate 的文档上;定位在 Aggregate 所导入模块的文档中的发现,同样显示在该模块的文档上。
输出形式
打印出的诊断信息以方括号中的头部和源指针开头,并把消息放在单独的缩进行上:
[CATEGORY SHORTCODE] <source> <message>头部包含两个标记,它们回答不同的问题。类别是上述类别之一,说明应查看哪个关注点。短代码由字母 E 和四位数字组成,它指明使构建停止的确切条件:在报告中引用它、在搜索中输入它,或在 sentinels.md 中列出所有条件的表里查找它。两者都无法从对方推导出来,因此两者都会打印;当一个类别涵盖多种修复方式时(如 [TRUST_ERROR]),短代码告诉你遇到的是哪一种。
插件引发的代码由引发它的插件限定
每个短代码都指向 Aggrega 声明的一个条件,且没有两个条件共用同一个短代码:在另一个条件已占用的编号下声明的条件,会在编译器读取任何输入之前被拒绝。插件不会分配自己的代码。插件报告失败时,会指明 Aggrega 声明的条件之一——描述插件如何失败的几个通用条件之一,或在适用时更具体的条件——并提供说明实际发生了什么的语句。因此两个插件可以报告同一个短代码,而当它们这样做时,报告的是同一个条件。
代码无法说明的是哪个插件遇到了该条件;报告插件所引发条件的头部会在代码前紧接着带上该插件的标识:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>短代码始终是最后一段:即最后一个 / 之后的字母 E 和四位数字。插件标识本身带有分隔符,还可能带有版本号,因此要从末尾而不是从第一个 / 读取,才能从任何头部中取出代码。最后一段之前的全部内容都是插件。
无论由哪个插件引发,最后一段都像其他任何短代码一样解析:sentinels.md 中列出所有条件的表会列出它,aggrega explain 也能解析它。只引用最后一段——限定部分说明的是哪个插件遇到了该条件,而不是它是哪个条件。如果插件指明了 Aggrega 未声明的代码——没有任何条件占用的编号,或已停用的编号——该代码不会被打印:构建会以 E0293 中止,并以该插件加以限定,其消息会引用插件给出的代码、列出那些通用条件,并保留插件自己的语句。
打印裸短代码的头部报告的是 Aggrega 自身引发的条件,其中包括插件失败但未指明自己任何条件的情况。此时使构建停止的是编译器通用的插件失败条件,具体细节由插件的消息给出。
任一标记都可能缺失,缺失的标记会被省略
诊断信息中没有的标记,绝不会用任何东西代替:没有占位符,也没有空方括号。头部有三种缩短的方式,每一种都传达了某些信息:
- 没有短代码。 该失败未指明 Aggrega 自身的任何条件,最常见的是编译器所封装的库报告的故障。头部只打印类别,因此你仍然知道应查看哪个层面。
- 没有类别。 该失败没有可以引导你去查看的关注点,因此不会去猜测。头部只打印短代码,你要查找的就是这个代码。有两种情况会产生这种形式,它们读起来相似,因为对你而言它们确实相似:两者都不告诉你该看哪里,而代码告诉你发生了什么。一种是编译器本身的故障,此时消息会说明这一点并请你报告;实际出现的情况是编译器自身对目录的各个视图彼此不一致。另一种是指明了条件、但从未经过将其归入某个关注点的层面的失败,这通常是在命令边界处引发的拒绝的形式。绝不会为填补空缺而编造类别,这正是省略的意义所在,而非它的局限:类别回答的是“我该查看哪个关注点”,在问题本无答案之处给出的答案并不是谨慎的答案,而是错误的答案,而且会被最先采取行动。还值得说明的是,反向推断并不成立:确实带有类别的头部并不总是指向你编写的内容,因为
[FETCH_ERROR]、[POLICY_ERROR]和[TRUST_ERROR]各自指明的是一个关注点,而不是编写层面。 - 两者皆无。 方括号被完全省略,诊断信息就是其消息本身。这种失败既未指明 Aggrega 自身的任何条件,也没有可以引导你去查看的关注点:命令拒绝其参数、无法读取的文件、取消操作,或编译器所封装的库报告的、下层没有我们任何条件的故障。没有可在
sentinels.md中查找的内容,消息就是该失败要说明的全部。
同一错误压缩为一行(适用于日志输出而非终端的形式)时,保留类别并去掉短代码:
[CATEGORY] <source>: <message>头部中缺失的类别在这里同样缺失,连同方括号一起,因此这一行绝不会是 [] <source>: <message>。单行形式会在失败向上传递时被重新包装进外层帧,因此空标签会被带入其中的每一帧。
源是一个结构化指针:在有 YAML 位置时通常为 <file>:<line>:<column>,在不适用文件位置时则为逻辑标识符(目录实体名称、Release 名称、边界路径)。第三种形式 <file> at <key> 出现在指针知道文档及其中的编写键、但不知道字节位置的情况下:文件是你要打开的,键是打开后要查看的。消息是各层面各自的诊断信息。
关于构建中某个实例的失败——一个组件、一个由模块提供的组件,或模块本身——会在位置之后以 (instance <name>) 的形式指明该实例,因此 aggregate.yaml (instance shop) 表示声明了模块 shop 的 Aggregate。当失败没有可指向的文档时,实例单独出现,形式为 instance <name>:在渲染组件 adminer 时失败的 provider 会打印 [TRANSLATION_ERROR E0082] instance adminer,其下方的各行承载失败的其余内容,包括它所指明的任何文档。该名称是 Aggregate 声明该组件时使用的名称;由模块提供的组件以其经过模块的路径命名,例如 shop.cart。实例从不会打印在应当出现文件的位置,因此源指针开头的内容总是一个你可以打开的文档,或者上文所述的逻辑标识符之一。
在完成的图上求值的规则以第三种形式报告,当仅凭消息无法区分两个发现时,键可以将它们区分开。这类规则指明的是声明该组件的类型而非实例,因此同一类型的两个组件违反同一规则时,会针对同一文件给出相同的消息:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.checkout missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.inventory missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")键是唯一不同的部分,它指明要编辑两个组件中的哪一个。两个发现带有相同的短代码,因为它们是同一条件出现了两次:短代码指明规则,键指明具体出现之处。
对于带有相应上下文的失败,该形式还包括另外两行:失败的模板表达式,以及失败处作用域内各支柱的快照:
[CATEGORY SHORTCODE] <source> <message> expression: <the template excerpt that triggered the failure> active pillars: <one line per top-level pillar key in scope at the point of failure>expression: 行包含触发失败的模板片段。active pillars: 块列出失败处可用的顶层支柱键,让作者看到可以查询的内容。当失败不带有这两者时,两者都会被省略。
嵌套的上下文帧
一个错误在到达 CLI 的途中往往会跨越多个层面:加载阶段包装具体的实体失败,而该实体失败本身又包装了一个解释规则的 sentinel。这样的链中每个带类别的帧都会渲染——最外层的帧以上述形式作为头部,每个嵌套帧作为缩进的 caused by: 续行,带有自己的类别标签、源指针和消息。最内层指向文件的帧始终可见:
[CATALOG_ERROR E0094] aggrega-catalog catalog load caused by: [CATALOG_ERROR] aggrega-catalog/recipe/compose/mariadb-copy/1.0.0/recipe.yaml duplicate entity identity within a single catalog directory (recipe identity "compose/mariadb:1.0.0")**只有头部带有短代码,续行只带类别。**条件只在读者遇到该失败的位置命名一次;caused by: 标记下方的帧是从更深处看到的同一个失败,因此在每一帧上重复其标识符只会增加行数而不会增加事实。note: 块不是续行,不遵循此规则——它报告的是其他文档的条件,而不是从更深处看到的同一个条件;下文一节对此进行了说明。头部打印的代码是该链所命名的代码——此处为最底部的规则——因此顶部的阶段上下文帧仍能标识其下的条件。
自上而下阅读:失败的阶段,然后是导致它的实体(及其文件路径),然后是它违反的规则。相对于父帧没有增加任何内容的嵌套帧(相同的类别、相同的源、父帧已包含的消息)会被去重而不是重复显示;末端说明仅在其上方的帧尚未包含其文本时才会渲染。
失败在向外传递时跨越的层面越多,链就越深,而该规则在每一层深度都成立。在 Recipe 合成的 Workload 中被拒绝的模板会跨越三个层面——正在渲染的节点、该 Recipe 的模板层面,以及模板本身:
[CATALOG_ERROR E0060] instance db rendering node "db" caused by: [CATALOG_ERROR] recipe "mariadb" workload template caused by: [CATALOG_ERROR] workload[mariadb] template references a root the render context does not define (template "workload[mariadb]" references ".nosuchroot.database", the render context defines .context, .values, .infra, .locals, .provides, .features, .metadata, .attachment_name, .inject, .inject_raw, .steps, .source, .workload, .boundary)仍按前述方式自上而下阅读,并注意额外深度所揭示的三点。短代码只出现一次,在头部,无论其后跟有多少续行。最内层的帧是条件本身那句话所在的位置,因此最深的一行既是用于匹配的那一行,也是说明需要修改什么的那一行。并且没有源指针的帧只打印其类别:上例中间的帧在其消息中命名了失败所在的层面,因为该层面是模板而不是文件,没有可指向的位置。
当失败在某个帧下方分叉时——即某个阶段在停止前收集了多个独立的违规——续行会带有一个计数,每个收集到的失败都在其下方渲染,并以下文多错误链所用的同一 --- 分隔线隔开:
[OPS_ERROR E0099] recipe resolution caused by (2): [OPS_ERROR] .spec.components.edge no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.edge, "edge", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it --- [OPS_ERROR] .spec.components.internal no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.internal, "internal", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it计数下方收集到的失败也是续行,因此它们都不会重复头部的短代码——正因如此,包含十几个违规的分叉不会将同一标识符打印十几次。
全文适用同一套分隔符语法:同级失败之间用 ---,嵌套上下文帧之间用 caused by:。
被拒绝的目录文件及其所解释的失败
为解析 Release 的依赖而加载目录时,加载过程有意采取宽容策略:无法读取的文件,或无法解析或索引的 Aggrega 文档,会被拒绝并记录下来,而不会中止整个加载。正因如此,你的 Release 从未涉及的损坏实体不会导致无关的构建失败。
其后果是,被拒绝的文件会悄无声息地从目录中缺失——而如果你的 Release 确实用到了它,失败的将是解析指向该文件所声明内容的引用这一尝试。该失败是拒绝的后果,而非拒绝本身,因此只要报告能够准确指出那次拒绝,就会按因果顺序排列两者:
[CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema note: this file was skipped at load, so the catalog holds nothing under the identity it declares. This Release reaches that identity, so what failed is the attempt to resolve the reference to it: resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"拒绝排在最前,带有它自己的类别和短代码,因为它指出的是你可以着手处理的问题:修复方法是在 Recipe 中补上缺失的 implements:,而与如何在注册表中查找引用无关。解析失败仍会在其下方报告,因为正是它说明了为何需要那个文档。
只有当恰好一个被拒绝的文件声明了失败引用所指的标识时,拒绝才会排在最前。 匹配依据是每个文档为自身声明的标识——其 kind、名称、版本,对于 recipe 还包括限定其范围的 spec.capability——因此,声明了引用所请求内容的被拒绝文件,正是该引用本应解析到的文件。由此有两个推论。声明版本范围而非具体版本的引用不指向任何单一文档,因此不会单独指出任何文件。而格式严重错误、连文件头都无法读取的文档根本没有声明任何标识,因此永远不会被指为任何问题的原因。
如果没有被拒绝的文件声明该标识,或有多个文件声明了它,报告就与没有拒绝记录时相同:失败排在最前,所有拒绝都列在其下方,供你斟酌。指错原因文件比不指出任何文件更糟,因为你会据此采取行动。
[E0105] resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe" note: catalog files skipped at load. A refusal outside this Release's closure is tolerated and never fails a build, so this failure is explained only by a refusal naming something this Release reaches: - Recipe "server-recipe" (catalog/recipes/helm/server.yaml): [CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml: document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema关于第二种形式,有几点值得了解,因为每一点都回答了该输出块原本会引出的一个问题。
头部指出的是失败,而不是拒绝。 顶部的短代码是解析失败所产生的代码,因为此处排在最前的是该失败——没有单独指出任何被拒绝的文件,因此它们都不位于首行。它旁边没有类别,因为这条路径上没有任何环节将该失败归入某一关注领域。每个拒绝自己的头部位于下方各自的条目中,你应在那里阅读。
列出所有拒绝,而不只是起作用的那一个。 出现这种形式意味着记录无法单独指出其中一个,因此 note 会说明区分方法而不是去猜测:位于此 Release 闭包之外的拒绝会被容忍,不可能是失败的原因,于是只有指向该 Release 所用到内容的拒绝才是能解释失败的条目。请对照你的 Release 实际使用的内容来阅读这些条目。
每个条目都带有自己的方括号头部——自己的类别和自己的短代码。 这是诊断头部以下唯一会出现短代码的地方,它并不是上述延续规则的例外,而恰恰是该规则的推论:note: 下的条目不是从更深处看到的同一个失败,而是由另一个文档引发的另一个情况。指出其情况,你才能查找该拒绝并修复文件,而这正是该输出块存在的意义。
头部格式严重错误、无法恢复其所声明身份的被拒文件,只按路径列出。这是对一个无从窥探的文档的如实解读,而路径仍足以让你打开该文件。如果文件格式错误到连其种类都无法读取——例如无法解析为 YAML——但它声明了 Aggrega 的 apiVersion,即有一行不缩进、以 apiVersion: 开头且值以 aggrega.ai/ 开头,那么它也会以这种方式列出,并附上解析器自身给出的原因:所在的行,以及解析器在那里期望的内容。声明了其他 apiVersion 或未声明 apiVersion 的 YAML 文件不是 Aggrega 文档——例如 chart 的模板,或存放在实体旁边的配置文件——因此无论格式错误多严重,都不会被列出。
声明了任何 catalog 都不包含的种类的文件,只在它能解释失败时才会被指出。 声明了 Aggrega apiVersion 以及任何 catalog 都不包含的 kind(例如拼错的 Componnent)的文档,会被每次加载跳过,因此它不属于拒绝,也不会列在拒绝之中。当失败的引用所要求的名称正是该文件声明的名称,并且在引用指明了版本时版本也相同,报告会在失败下方用一条单独的注释指出该文件,无论该引用是作为哪种种类收集的——这适用于下面列出的每个界面,也适用于 aggrega build,无论它是读取现有的 lockfile 还是先填充一个:
[E0114] resolve: no entity in the catalog matches this URI: entity "<reference>" (referenced from <referring paths>) note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: - Componnent "<name>" (<path>): [CATALOG_ERROR E0371] <path>: 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 都不包含的种类、但声明了其他名称的文件,无法说明这次失败的任何原因,也不会被提及。aggrega serve 的消息只有一行,它会在该行中带上同样的注释——note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it:,后跟该文件的拒绝——并且从不把此类文件列入加载时跳过的文件之中;aggrega mcp 的 describe 工具在被要求按某个 Release 的条件查询一个名称时,同样会指出该文件,以代替那段说明。整个 catalog 范围的 aggrega validate 和 aggrega lint 会报告每个此类文件,无论是否有任何内容到达它——参见 fatal-halts.md §“A catalog document declares a kind a catalog does not hold (catalog 文档声明了 catalog 不包含的种类)”。
无论得到哪种形式,失败都保留其自身的标识。 note 是附加到失败上的,而不是覆盖失败进行渲染;让拒绝排在最前只改变你先读到的内容——因此无论哪种情况,失败所引发的情况都保持不变:其短代码仍可查询,按该情况进行匹配的工具也仍能匹配。
当被拒绝的文档本身就是某条命令要报告的对象时,拒绝只陈述一次。 aggrega inspect <name> 以严格方式加载目录,因此加载过程拒绝的文档会使其停止,它输出的是该文档的拒绝,作为单个诊断:头部带有拒绝的类别和短代码,以该文档作为来源,其下方是该文档的问题所在——对于 schema 违规,即违规的键及其行号和列号,以及建议。引发它的加载过程经过了正在遍历的目录和读取该文件的步骤,但这些不会作为单独的帧打印,因为每一帧都只会再次指出同一个文档,而不增加任何事实。当 aggrega serve 被问及某个名称指向什么、而某个被拒绝的文档声明了该名称时,它会在一行中用相同的措辞给出同样的拒绝,随后附上该文件在加载时被跳过的 note。与上文一样,无论哪种情况,拒绝的情况都仍可匹配。
无论该解析在何处运行,你都会得到这两种形式。 aggrega build、aggrega pull、aggrega validate --release 和 aggrega inspect --closure 会在终端中输出它们,对某个 implements 目标未找到的 Recipe 运行的 aggrega validate 也是如此;通过 aggrega mcp 连接的 AI 助手会从 build 和 validate 工具收到相同的说明,并且在以 catalog:// 读取某个被拒绝文件所声明的实体时,会在一行中收到排在最前的拒绝。你从哪个界面发起请求,都不会改变你被指引去打开的文件——通过 HTTP 访问 aggrega mcp 的调用方得到的是相对于工作区根目录的路径,且不会被告知该服务器所服务工作区之外的文件——并且当拒绝排在最前时,答复所指向的编写契约是该被拒绝文档所声明 kind 的契约,而不是失败引用的 kind 的契约。
文档信封失败类别
每个实体文档(目录实体、Aggregates、Manifests、Releases)在加载时、类型化解析之前,都会依据其类型发布的 JSON schema 进行校验。违反信封的文档(未知键、缺少必填字段、形状错误的值、被禁止的结构,例如 Release values:)会显式中止,并给出一条诊断:先说明条件,然后是实体类型和文件,接着是每个出错的键或形状及其所在的行和列,最后说明如何处理:
[OPS_ERROR E0215] release.yaml document envelope validation failed (Release, at release.yaml); 12:7: spec.boundaries.main.values: against /$defs/boundary: unexpected property: "values". correct the document to match its kind's schema诊断以条件开头,指明类型和文件,并以处理建议结尾;其间的每项违规只带 line:column,因为开头已经指明了文件。每个出错的键都在它自己的位置上报告,而不是在包含它的块的位置上,因此行和列指向的正是你需要修改的键。如果该位置的形状来自 schema 中的可复用定义,诊断会在单词 against 之后指明该定义(上例中为 against /$defs/boundary),这样可以清楚看出该键是依据哪个契约衡量的,而该定义也不会被误读为你所写键路径中的又一步。包含多项违规的文档会按键的顺序在各自位置上逐一列出,报告在列出四项后停止,并给出其余项的数量。
关于位置指向哪里,有两点值得了解,因为两者都有用,而非出人意料:
- 缺少的必填键没有自己的位置——按定义,它不存在于文档中。违规会改为指向外层的键,也就是缺少的条目应当所在的地方。因此
spec.capability: missing required property指向spec:,你就在那里添加它。 - 自身名称包含点号的键——所有
component.aggrega.ai/…标签和features.aggrega.ai/…注解——会在包含它的块上报告,而不是在条目本身上,因为点号会被解读为深入文档的层级。标签上的违规指向labels:。
如果违规指明的键在文档中根本不存在(例如整个 metadata: 块被遗漏),则会省略位置而不是猜测,违规仅显示为键路径和消息。一个你不得不怀疑的位置,比没有位置更糟。
类别取决于编写面:目录实体为 [CATALOG_ERROR],Aggregates 为 [DEVELOPER_ERROR],Releases 和 Manifests 为 [OPS_ERROR]。同一道关卡在每个加载实体的界面上运行——aggrega build、aggrega lint、aggrega validate,以及 aggrega serve 发布的编辑器诊断——因此多余或拼写错误的键无论在哪里首次读取文档都会被拒绝,而不会被静默丢弃。这些界面都以相同方式解析位置,因此指向同一个键,并且都从条件本身读取条件的语句:编辑器划线的行就是终端指明的行,编辑器条目开头的语句就是终端开头的语句。两个界面不共享的是完整消息,这是有意为之——终端将每项发现归入同一个标题之下,并以针对该路径的建议结尾;而编辑器为每项发现发出一个条目,定位在其自身的键上,既不重复它已附着的文件,也不重复原本会在每处划线都说一遍的建议。因此,趋于一致的部分正是你用来识别条件的部分。
多错误链
当一次编译检测到多个相互独立的违规时(最常见于静态分析阶段,此时每个选择器和 appliesTo 违规都会在任何一个中止构建之前被收集),这些错误会合并为一条链。CLI 遍历该链,并独立渲染每个子错误,各子错误之间以一条水平分隔线隔开:
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge.uses.reviewed_upstream.internal selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.---[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge2.uses.reviewed_upstream.internal selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.--- 分隔符是字面量——读者和下游工具可以按它拆分,以逐一列出合并的错误。每个子错误本身就是一个独立的失败,而不是其相邻错误的细节,因此每个子错误都带有自己的头部:它自己的类别和它自己的短代码,各自在存在时才出现,如关于缺失标记的章节所述。违反同一规则的两个违规给出相同的短代码,如上例所示;违反不同规则的两个违规给出不同的短代码。
从头到尾解读一条错误
在大多数编写场景中,类别前缀与源位置指针合起来即可确定需要修复的内容:
| 类别 | 修复所在位置 | 示例表现 |
|---|---|---|
[DEVELOPER_ERROR] | Aggregate YAML | Aggregate 所写内容上的选择器 / appliesTo 违规;Aggregate 一侧的 uses 插槽不匹配;解析器因开发者编写的内容而中止。 |
[OPS_ERROR] | Release YAML / Manifest YAML | 边界路径模板引用了不受支持的字段;subDirectory 导致路径冲突;解析器因 Release 编写的内容而中止;Release 连接的某个连接,或它在某个连接上填充的附加项,被插槽或槽位的规则拒绝;仅由 Release 附加到某个组件或某个边界的 Feature,被该 Feature 或槽位的规则拒绝;某个 Manifest 映射或注解绑定被拒绝。 |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Recipe 结构规则;FeatureRecipe 模板在 executionScope: boundary 下引用了仅限单个组件的字段;Workload featuresSchema 交叉校验失败。 |
[TRANSLATION_ERROR] | Workload / valuesMapping 输出 / 源覆盖层 | Helm 探针端口解析;跨边界的 compose 服务名冲突;两个 compose 贡献方以相互冲突的内容声明同一个顶层卷名或配置名;helm-chart 伞形 chart 上的 chart 名称不匹配。 |
[FETCH_ERROR] | 注册表 / 远程源获取(属于运维问题,而非编写问题) | 在注册表中找不到制品;需要身份验证;网络不可达;缓存的摘要与锁文件不一致。修复:进行身份验证、恢复网络连接,或执行 aggrega pull --upgrade --release <release>。 |
[POLICY_ERROR] | 策略插件(治理规则) | 附加在治理裁决角色上的某个策略插件,依据其执行的规则拒绝了组装后的构建。修复:满足所执行的策略,或重新考虑该附加。 |
[TRUST_ERROR] | 信任配置,或制品自身的签名(属于关注点,而非编写面) | 无法读取的信任策略或固定的信任根;未声明任何受信任身份的无密钥策略;要求所发布的类型必须带签名的签名策略;配置已不再附加的、已记录的裁决附加关卡。或者:无法验证的签名;在要求签名时未携带签名的制品;不受信任的签名者;记录的受信任身份已不再匹配的插件。修复:更正配置或已提交的信任记录,或对该制品作出决定——短代码会指明是哪一种。 |
按 provider 区分的上下文前缀(helm: node "<id>": ...、compose: node "<id>": ...)出现在 [TRANSLATION_ERROR] 和 [CATALOG_ERROR] 输出的消息部分中,用于在涉及多个 provider 时定位出错的 provider。
库原生错误
源自底层库的错误(Helm SDK 的 chart 加载错误、docker-compose YAML 解析器错误、因源路径缺失而产生的文件 I/O 错误)会被加上按 provider 区分的上下文前缀,并根据其触发于合成阶段还是目录内容加载阶段,出现在 [TRANSLATION_ERROR] 或 [CATALOG_ERROR] 之下。被包装的库消息会逐字保留原工具的诊断信息,以便作者将其与该工具自身的文档进行对照。
交叉引用
fatal-halts.md— 按错误列出的所有致命中止的目录,包含预期消息和修复方法。warnings.md— 编译器发出的非致命提示。vocabulary/validation-surface.md— 四个 schema 校验层,以及它们的错误形态如何相互作用。