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

aggrega explain

解释某代码所指的中止条件

概要

aggrega explain <code>

说明

Explain the halting condition a code names.
A halting diagnostic opens with the category the failure is attributable to and the condition's short code — the letter E and four digits, as in [CATALOG_ERROR E0209]. That short code is the one to pass here; it is fixed once a condition is published, so a code quoted out of an old report still names the same condition.
aggrega explain E0209
The descriptive code is accepted too — the hyphenated one naming the condition in words, which a structured diagnostic carries as a field of its own. A condition's two codes name the same condition and reach different readers, so either is a code you may be holding, and the condition above is registered under recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-source
Every condition is declared inside this binary, so the identifiers and the sentence are reported without a network or a cache. The published reference supplies the walk-through of the authoring fix for every condition, and nothing else is resolved against it. It is read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version — kept in the cache every project on this machine shares, acquired on first use when that cache holds no copy this workspace's signature check admits. Where it cannot be acquired, the condition is still reported and the reason the walk-through is missing is stated.
A number that named a condition and no longer does is reported as retired, with what it named, so a code quoted from an old report is never answered with a different condition.

功能说明

构建停止时,会打印一个带方括号的头部,其中指明失败所归属的类别以及该条件的短代码——字母 E 加四位数字:

[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...

aggrega explain E0209 会将该代码转换为它所指的条件,以及修复编写问题的详细步骤:

Terminal window
aggrega explain E0209

回复开头给出该条件的两个标识符,以及其诊断信息开头的固定语句,随后重现解释该条件成因和需要修改之处的条目——与 fatal-halts.md 中发布的条目相同。

要传入的代码

条件的两个代码均可接受,因为它们分别通过不同的途径呈现给你。

短代码是终端显示给你的代码;当你手头只有打印输出时,应使用它。编号一经分配便固定不变,因此你一年前粘贴到报告中的短代码,至今仍指向当时所指的条件。

描述性代码是带连字符的代码,结构化诊断信息将其作为单独的字段携带,程序据此进行分支判断。它用文字命名条件且不带前缀,因此即使编译器围绕它进行了重组,它也保持不变。如果你手头的是这个代码,就改为传入它——上述条件注册在 recipe-values-mapping-requires-source 之下:

Terminal window
aggrega explain recipe-values-mapping-requires-source

条件的两个代码指向同一个条件,因此两种写法得到的回复完全相同。短代码匹配时不区分大小写,因为它是你从屏幕上读取并重新输入的值。

sentinels.md 介绍了条件携带的三个标识符,以及各自的使用时机。

答案的来源

**此二进制文件声明的每个条件都由二进制文件直接回答。**它的两个代码及其诊断信息开头的语句都在编译器内部声明,因此这部分内容无需网络、缓存或配置。

此二进制文件未声明的代码会在已发布的参考文档中查找。 插件通过选择编译器声明的条件来报告中止,因此不会在其他任何地方声明条件。已发布的参考文档 sentinels.md 列出了产品声明的每个条件,而它的发布版本可能与你正在运行的二进制文件不同——因此,从较新或较旧版本生成的报告中引用的代码仍可能在那里得到解析。

详细步骤同样是已发布的文档,从 fatal-halts.md 读取。这两个页面都来自文档包,文档包在每台机器上保存一份,位于所有 Aggrega 项目共享的缓存中,每个注册表和版本各一份副本——参见 aggrega cache。读取的文档包是为你正在运行的 aggrega 版本发布的那一个;如果没有为该版本发布文档包,则读取为更早版本发布的最新文档包——与 aggrega scaffold --example 所做的选择相同,因此两者永远不会读取不同的文档。更早版本的参考文档中没有的代码,可能指向此后才声明的条件,因此它会被作为无法确定的代码拒绝,而不是作为不指向任何条件的代码拒绝,并且拒绝信息会说明读取的是哪个版本的参考文档。由你的工作区决定文档包来自哪个注册表,即其默认注册表,并决定是否可以读取机器上已有的副本:在提供页面之前,副本旁保存的签名会按照你的工作区针对该注册表的签名检查重新验证,与获取文档包时所需通过的检查相同。该检查在离线时同样运行。如果它固定了密钥或信任根,则只读取这些;如果两者都未固定(官方 hub 的内置检查即是如此),则依据公共 Sigstore 信任根进行验证,而离线工作区无法获取该信任根——因此离线时,它依据此前在本机上在线获取时留在你主目录下 .sigstore 中的信任根进行验证,不获取任何内容。当机器上没有副本,或没有能通过你的检查的副本时,该命令会按照该检查获取一份副本,仅此一次,此后从缓存读取。同一份副本还用于助手通过 aggrega mcp 读取的文档,以及编辑器通过 aggrega serve 显示的解释。

有三种回复值得留意,因为每种都要求你采取不同的行动。

**尚无条目的条件。**会报告代码和语句,并附注说明中止条件页面没有该条件的详细步骤。所有条件仍列于 sentinels.md 中。

**没有可用的文档。**对于编译器声明的条件,仍会报告代码和语句,并附注指明无法读取的文档包及其版本。对于此二进制文件未声明的代码,则没有任何内容可供回答,因此该代码会被拒绝——拒绝信息会说明无法读取参考文档,因为没有它,就无法区分来自其他版本的代码与拼写错误,并保留两种修复方式:更正代码,或获取文档。常见原因是工作区被固定为离线,或从未连接过其注册表。如果机器上的副本未能通过你的工作区的签名检查——例如另一个项目在更宽松的设置下获取的副本,或者离线工作区因本机从未获取过其检查所依据的公共信任根而无法检查的副本——附注会说明该副本是被拒绝而非缺失,并说明原因。如果没有为你的版本发布文档包,且最新的更早文档包所用的格式是此版本的 aggrega 已不再读取的——例如在其自身文档发布之前运行的候选发布版本——附注会用一句话同时说明这两点:

hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the walk-through is not shown here; every condition, including the ones a provider declares, is published at aggrega-docs/language-reference/errors/sentinels.md, and the walk-through of each authoring fix at aggrega-docs/language-reference/errors/fatal-halts.md

**已停用的编号。**曾经指向某个条件、如今不再指向的编号,会被回答为已停用,并说明它曾指向什么,而不是被当作从未存在的代码——它也绝不会被回答为另一个条件,因为已停用的编号不会被重新分配。

示例

直接解释失败构建输出的代码:

Terminal window
aggrega build --release release.yaml || aggrega explain E0209

解释程序匹配到的代码:

Terminal window
aggrega explain plugin-value-not-representable

从助手获得相同的答案

通过 aggrega mcp 连接的 AI 助手可以通过 explain-error 工具获得同样的展开内容。应将诊断文本而非单独的代码交给它——助手掌握的是构建打印的内容——当该文本以短代码开头时,答案会包含该条件、其诊断信息开头的语句,以及修复编写问题的已发布详细步骤,组织方式与上述回复相同。答案还包含描述性代码,以便助手据此而非依据消息措辞进行分支判断,以及该条件的发布地址。

上文关于缺少详细步骤的说明在此同样适用:页面中没有条目的条件,以及无法读取文档的工作区,都会使该条件得到回答并附注说明属于哪种情况。已停用的编号在此同样被回答为已停用,并说明它曾指向什么,因此拿到旧诊断信息的助手会得知该编号已不再使用,而不会被引导到讲述其他内容的页面。助手途径在会话开启时获取一次文档,因此展开时读取的是已缓存的内容。

守护进程为编辑器回答同样的问题,依据的是代码而非诊断信息。三者是同一展开内容的三种呈现,而不是恰好一致的三个答案。