aggrega build
aggrega build 将一对 Aggregate + Release 编译为 provider 原生的产物(Helm 清单、可再分发的 Helm chart、docker-compose YAML),输出到工作区根目录下的 dist/ 中,详见输出。Release 是唯一的入口:它指定 Aggregate 和 Manifest,声明边界,并将组件路由到各个 provider。
常用标志
有两个标志的行为无法仅凭下面的标志参考说明清楚:
--catalog <dir>— 一个包含 catalog 实体的目录,即 Component、Feature、Recipe 和 FeatureRecipe 这些编写类型,以及各库类型、Aggregates 和 Plugins,会被递归加载。每个--catalog目录都按给出的顺序,先于已配置的目录被搜索。要在共享 catalog 之外同时搜索项目本地的 catalog,请同时传入两者(--catalog ./catalog --catalog ../shared-catalog),或将它们列在catalog_dirs下。使用--detail时,被更高优先级目录遮蔽的任何实体都会与其他构建警告一起报告到 stderr。不存在的--catalog目录会使构建停止,并给出该目录名。列在catalog_dirs下但实际上不是目录的目录也同样如此:它会在读取或写入任何内容之前使构建停止,并给出该条目以及列出它的配置文件和行,参见本地实体从何处读取。因某个引用解析为空而停止的构建,会在停止信息下方的说明中,于加载时跳过的 catalog 文件之列,给出这些目录中每个声明了 Aggrega apiVersion(即有一行不缩进、以apiVersion:开头且值以aggrega.ai/开头)却无法加载的文件(例如无法解析为 YAML 的文件),并附上解析器自身给出的原因;声明了其他 apiVersion 或未声明 apiVersion 的 YAML 文件不是 Aggrega 文档,绝不会在那里列出。--detail— 报告 pull 步骤做了什么,即与aggrega pull --detail输出的相同的临时 pull 事件诊断。决定是否有内容可报告的,是是否请求了 pull 步骤(通过--auto-pull,或启用auto_pull),而不是 lockfile 是否已存在:被请求的 pull 步骤无论如何都会运行,缺少 lockfile 时填充它,已有 lockfile 时遵循其中的固定版本。没有 pull 步骤运行时,该标志向 stdout 打印一行说明并继续执行,它从不虚构已提交的 lockfile 中没有的解析层级。要查看 Release 依赖在 pull 之后的解析状态,请使用aggrega inspect。
--dry-run 在预览构建而不写入中介绍,--trace 和 --trace-unredacted 在下文的跟踪输出和显示被隐去的值中介绍。
在构建过程中填充 lockfile
默认情况下,构建对依赖是只读的:它需要一个 lockfile,且不写入任何 lockfile。--auto-pull 以及 auto_pull 工作区设置会把拉取步骤加入构建,这样一条命令即可解析 Release 的依赖,并基于解析结果进行编译。
对 Release 的编辑会被 lockfile 察觉。 lockfile 按内容摘要记录该 Release 及其扩展的每个 Release,因此如果在拉取之后编辑了 Release,只读构建会在任何渲染开始前停止,指出该文件并提示你运行 aggrega pull --release <release>,该命令会记录这次编辑,同时遵循其他所有固定版本。注释或空白的改动同样计入,因为摘要覆盖的是原样的字节。自动拉取的构建会自行运行该拉取步骤,因此会记录这次编辑并完成构建。
Release 只渲染一次。 一个 Release 使用哪些外部输入,取决于对它的渲染,而不取决于其文档声明的任何内容,因此拉取步骤会渲染该 Release 来确定这一点,而这次渲染就是构建所用的渲染。因此,自动拉取的构建只需一次渲染,与在已有 lockfile 的情况下进行普通构建相同。
影响渲染的标志同样作用于这次渲染。 --trace、--verify-determinism、--disable-plugin-cache 和 --no-unsupported-field-warnings 作用于自动拉取构建所执行的渲染,方式与作用于普通构建相同,因此在单命令构建中请求跟踪或确定性检查,同样会得到结果。--dry-run 是例外,而且它会被拒绝而不是被静默忽略:试运行不写入任何内容,而拉取步骤会写入,因此两者同时使用时会在任何工作开始前停止(参见预览构建而不写入)。
构建如何读取 lockfile 固定的内容
lockfile 中的固定项指明的是内容(一个摘要),而不是位置。对于实体,它是该实体的一次发布所携带内容的摘要,即其文档及其指明的文件,因此实体在 catalog 目录中的副本与保存其发布内容的缓存条目具有相同的固定项,详见 lockfile。构建从机器上已有的来源读取每个固定的依赖:与其他地方一样,先读取 catalog 目录,再读取 .aggrega/cache 下的内容缓存。读取这些来源不会访问任何 registry;只有 pull 步骤(在构建运行该步骤时)才会进行获取。
不再保存其固定内容的缓存条目会被跳过。 就地编辑的实体(在相同 version 下的新内容)会使内容缓存在该名称和版本下仍保存先前的内容。如果某个 catalog 目录中有一个内容摘要与固定项一致的副本,构建就会读取该副本而不读取该条目,并在标准错误输出中说明这一点,指明该条目及两个摘要:
reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytes如果没有任何 catalog 目录包含该实体,则恰好保存固定字节的完整缓存条目会被作为该依赖读取,因此在获取其已发布副本之后从 catalog 目录中移除的实体,仍然可以从该副本构建。
如果没有任何来源保存固定的字节,构建会在渲染任何内容之前停止,报告 E0135;如果缓存条目的 manifest 不是 lockfile 固定的那个,则报告 E0133。停止信息会指明该固定项、缓存条目及其保存的摘要,以及该实体在每个 catalog 目录中的副本及其摘要,或者指明没有任何 catalog 目录包含它。解决办法是在 registry 可访问时执行 pull,它会重新获取固定的版本,并按固定项校验所获取的内容;关于 registry 不再提供这些字节时 pull 的行为,参见 遵循与更新。
aggrega pull 为发现外部输入而运行的渲染,以及通过 aggrega serve 或 aggrega mcp 进行的构建或预览,都以相同方式读取其固定项。
构建时的外部输入
渲染可以从远程 URL 请求内容(例如带有远程引用的 chart values schema),而构建从不为了将其加入渲染可读取的内容而去获取它。对 lockfile 已固定的 URL 的请求,由工作区的输入存储提供,并在任何字节到达渲染之前根据记录的摘要进行校验。对未固定 URL 的请求会停止,并指出该 URL 以及固定它的步骤;没有任何设置能把这种停止变成一次获取,因为悄悄扩大构建读取的输入集合,正是可复现构建唯一绝不能做的事。
如果存储中某个已固定输入的副本丢失,则仅按 lockfile 已记录的摘要重新获取该输入,并在写入或返回任何内容之前根据该摘要进行校验。这不会改变渲染所见的内容(摘要在固定该输入时就已确定),因此它是修复存储,而不是扩大闭包,lockfile 保持逐字节不变。在离线模式下,连这一步也没有传输途径,丢失的副本会导致停止,并指出该模式。
固定发生在解析 Release 的依赖项时,因此构建可以读取什么在构建开始之前就已确定。aggrega pull 就是这一步,而且是唯一的一步。
插件信任记录
构建的多项行为取决于 plugins-trust.yaml:这是 Release 锁文件旁边一个已提交的文件,记录每个返回裁定的挂载解析到了哪个插件,即担任 ir-verdict 或 render-verdict 角色的 plugins.governance 挂载,以及每个 plugins.linter 挂载。aggrega pull 负责写入该文件,插件信任记录 schema 描述其字段;下文只说明构建本身如何使用它。
在上述任何插件运行之前,构建都要以该记录为准。 从缓存提供的插件,如果其制品摘要与记录的不一致,会被拒绝而不会运行。这类挂载通常就是这样解析的,aggrega pull 说明了还有哪些解析方式不受记录的摘要约束。此外,如果某条记录的条目在 .aggrega-config.yaml 中已没有任何挂载与之对应,构建会中止:去掉一道关卡不会改变任何渲染出的字节,因此在没有经过审查的关卡的情况下产生的输出,看起来与该关卡批准的输出完全一样。中止信息会指出该插件,并根据你的本意给出两种补救办法:如果移除是误操作,就重新挂载;如果不是,就显式请求移除。它还会打印可直接运行的命令。记录中尚未包含的挂载属于首次出现,两项比对都不会因它而中止。
构建以每个插件条目记录的签名来约束该插件,与以锁文件条目记录的内容来约束该条目的方式完全相同。 如果条目记录了已验证的 signature,构建会在任何渲染之前重新计算该事实在缓存中指向的签名包的哈希,签名包缺失或不一致时以 E0144 停止。对于从内容缓存读取的插件,构建还会从该签名包中读出签名是为哪个制品生成的;如果签名是为与构建所读插件不同的插件生成的(从另一个条目复制过来的 signature 就是这种情况),则无论签名要求如何,都会以 E0332 停止。对于由内容缓存提供的插件,这两种拒绝都会给出 aggrega pull --release <release>:下一次 pull 会重新验证插件的签名,记录插件自身的签名并缓存其指向的签名包,同时重写与摘要不再匹配的缓存副本。如果工作区的信任配置要求构建从内容缓存读取的插件带有签名(与会使 aggrega pull 拒绝未签名插件的设置相同,因此 skip_signature_verification 和 advisory 注册表允许构建继续,正如它们允许 pull 继续一样),那么条目没有记录签名,或该插件根本没有条目,都会使构建以 E0331 停止,并指出该插件、plugins-trust.yaml 以及要求签名的设置。补救办法是运行 aggrega pull --release <release>,它每次运行都会在插件的注册表上验证其签名并加以记录。从你的某个目录提供的插件,或从编译器二进制文件内的副本提供的插件,永远不受该要求约束。与构建的其余部分一样,这一过程只读取机器上已有的文件,不向任何注册表发出请求。
构建会列出该记录中的每一项撤回,以及锁文件中的每一项撤回。 aggrega pull 针对这些插件之一记录的标记,无论严重级别如何,都会以一行 deprecation: 报告,给出该插件、所记录的严重级别和发布者的消息;build.halt_on_deprecated_severity 按照它对固定引用所用的同一规则,决定该标记是否还会使构建停止。其他每个报告 Release 的界面都会以相同措辞列出同一组撤回,且它们都不会因此停止:aggrega validate --release、aggrega lint --release、aggrega inspect --closure、语言服务器的验证与闭包应答,以及助手工具的 describe 和 validate。存在但无法读取的记录会使构建停止,而不会被当作什么都没记录的记录放行。
aggrega build --upgrade 会重写该文件。 它隐含 --auto-pull,并执行一次不带目标的完整刷新,重新解析每个依赖,因而重新解析并重写每个已记录的身份,同时删除所有没有挂载对应的条目。所以,如果升级构建之后该文件出现修改,原因就在于此:该标志的作用范围是所有依赖,而已记录的身份虽然不是锁文件固定项,也属于被重新解析的内容。与 aggrega pull --upgrade 不同,该构建标志不接受目标,因此无法缩小到单个插件:要采用或删除单个身份,请改为运行 aggrega pull --upgrade --release <release> <plugin>,它不会触动其他任何固定项和已记录的身份。
由于作用范围涵盖一切,它会在开始前先询问。 aggrega build --upgrade 确认刷新的方式与不带目标的 aggrega pull --upgrade 相同:两者是同一操作,所以提出同样的问题。在非交互场景下,传入 --yes 预先作答;如果标准输入不是终端且未传入 --yes,构建会拒绝执行,而不是等待一个无人能给出的回答。不进行刷新的构建不会询问任何问题。
工作区解析与确定性
Release 的 schema 所要求的 manifest: 引用相对于 Release
文件解析。相对的 catalog_dirs 条目(以及相对的文件系统插件路径)相对于
声明它的那个 .aggrega-config.yaml 所在目录解析——“相对”
始终指相对于你写下它的那个文件,因此无论你从哪里调用 aggrega,
同一个路径的含义都相同。--catalog 标志没有
声明文件,因此相对于当前工作目录解析。注册表
引用(oci://…、hub 引用)保持原样。
工作区根目录是最近的、带有 workspace: 块的祖先 .aggrega-config.yaml 所在的目录,或 --workspace-root 指定的目录。当根目录以这种方式固定时,构建与调用位置无关:从项目根目录和从子目录运行 aggrega build 会生成逐字节相同的 IR 和渲染产物,因为所搜索的目录以及输出中记录的源路径不会随工作目录而改变。(如果既没有 workspace: 标记也没有 --workspace-root,则工作目录即为根目录,输出因此锚定在那里——除非工作目录不锚定任何内容,且 --release 以绝对路径指定 Release:此时会从 Release 自身所在的文件夹重新发现根目录,因此所搜索的目录和输出中记录的路径都属于该 Release 所在的项目,无论你从哪里运行该命令。参见 configuration.md。)如果这样也找不到工作区,且没有任何东西指定工作区,构建会在标准错误中警告它用作根目录的文件夹不在任何工作区内,并给出使其成为工作区的命令;而要求先解析其依赖项的构建会在获取任何内容之前被拒绝,因为该解析所填充的缓存会写入那个文件夹,并使其成为一个工作区。不先解析任何内容的构建仍会渲染,但出于同样的原因,锁文件固定而缓存中已不再保存的外部输入不会被重新获取:请求它的插件会收到拒绝的说明语句来代替该输入,就像它会收到离线模式的说明语句一样,构建会报告该插件对此的处理结果。--workspace-root 或 AGGREGA_WORKSPACE_ROOT 指定了不存在的文件夹时,构建会在执行其他任何操作之前拒绝,并指出是两者中的哪一个提供了该值。
环境变量
build 读取的工作区设置可以通过环境变量覆盖,其优先级高于已提交的配置、低于任何标志:AGGREGA_OFFLINE、AGGREGA_AUTO_PULL、AGGREGA_CATALOG_DIRS(以操作系统路径列表分隔符分隔;请提供绝对路径)、AGGREGA_ARTIFACT_CACHE_DIR、AGGREGA_DEFAULT_REGISTRY 和 AGGREGA_WORKSPACE_ROOT。完整列表和优先级模型参见 environment-variables.md。
输出
无论从哪个文件夹运行命令——工作区根目录本身、其下的某个文件夹,或者其他位置的文件夹(此时由 --workspace-root 或 AGGREGA_WORKSPACE_ROOT 指定根目录)——渲染出的工件都会落在工作区根目录下的 dist/ 中,最后一行会给出该目录的完整路径:
Build completed: 4 files written to <workspace>/dist此处 <workspace> 代表工作区根目录,该行会将其写成完整路径。如果找不到工作区,也没有任何设置指定工作区,则运行命令所在的文件夹即为根目录,dist/ 会写在那里。如果 dist 是一个指向工作区之外的链接,则在删除或写入其中任何内容之前就会被拒绝。未声明任何边界的 Release 按 provider 写入:dist/<provider>/<files>。未设置 directory: 的已声明边界按边界、再按 provider 写入:dist/boundaries/<boundary-path>/<provider>/<files>。运维人员在 Release 边界上编写的 directory: 和 subDirectory: 覆盖项会改变目标路径;按 (path, provider) 进行的合并会将解析到同一求值路径的贡献者合并在一起。
构建未写入的文件
构建写入它自己的文件,不删除任何并非由它写入的内容,只有一个例外:dist/boundaries/ 由构建完整地重新生成,因此会在写入之前被清空,这样另一个变体的构建遗留在那里的文件就不会保留到一棵已不再生成它的树中。dist/ 中的其他所有内容都保持原样——无论是先前的构建写入、而本次构建已不再生成的文件,还是某个边界的 directory: 在先前一次运行中放在那里的文件,抑或是你自己放在那里的文件,都是如此——因为构建无法区分遗留文件和你有意保存在那里的文件。
它转而做的是告诉你。写完自己的文件后,构建会查看 dist/ 本身,以及其下它写入过文件或为写入更深层文件而经过的每个目录,并在标准错误上的一条警告中列出其中每一个并非由本次运行写入的文件。这些文件以相对于 dist/ 的路径列出并已排序,因此同一棵树在每次运行中都以相同的方式报告:
warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"随后,最后一行会统计它们的数量:
Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not write构建既未向其中写入任何内容、也未向其下写入任何内容的目录不会被查看,因此你自己保存在 dist/ 下的文件夹不会被逐个文件列出。没有发现此类文件的构建不会打印警告,其最后一行就是 输出 下所示的那一行。无论哪种情况,构建写入的文件都是相同的字节。要比较两次构建,或从零开始,请在构建之前删除 dist/。
aggrega serve 的 aggrega/build 请求和助手的 build 工具(aggrega mcp)通过同一个步骤写入,因此它们会用同一句话列出相同的文件:守护进程将其作为响应的 notices 之一,工具则将其作为 advisories 的最后一项。试运行不写入任何内容,因此不会报告这些内容。
YAML 缩进
每个渲染出的 YAML 工件——docker-compose 文件、Helm chart 模板和 values,以及 Kubernetes manifests——都以统一的缩进宽度输出。宽度由 .aggrega-config.yaml 中的 build.yaml_indent 设置,默认为 2(这些格式的约定宽度):
build: yaml_indent: 2 # default; accepts 2 through 9该宽度在所有渲染器共享的单一序列化点上应用,因此相同输入的多次运行输出保持字节一致。[2, 9] 范围之外的值会被配置 schema 校验拒绝。
交回编译后的图
--ir-graph 会将本次构建解析出的图以 JSON 形式写入标准输出。它是附加的:工件仍会写入 dist/,摘要仍会打印,渲染出的字节不变。该图先于构建在标准输出打印的其他所有内容输出——一个 JSON 文档加一个结尾换行符——因此解码该流的使用方读取它后即可停止。
交回的图正是渲染所使用的图,因此它准确描述了生成旁边这些工件的那次构建,而不是对同一 Release 的第二次解析。它可以与 --dry-run 组合使用:先写出图,随后是工件报告,不向磁盘写入任何内容。
作者声明为敏感的值会从图中隐去(在消费组件的 socket 将某个叶子声明为敏感时,连接的 values 和 infra 也包括在内),其结构化形式见 aggrega inspect。--unredacted 与 --ir-graph 一起使用时会改为打印这些值,条件与 aggrega inspect --unredacted 所述相同:它只作用于图,不涉及其他内容——trace 文件有自己的 --trace-unredacted,渲染出的工件从不隐去任何值——而输出到达的任何地方都将以明文携带这些值。不带 --ir-graph 传入时它会被拒绝,因为没有任何可供它揭示的内容。
aggrega inspect 和 aggrega validate 上也有同一个标志,含义相同。
预览构建而不写入
--dry-run 运行与构建相同的编译——相同的依赖关卡、相同的渲染、相同的 provider——并打印它将输出的内容,而不是写入。每个产物都会连同它将占用的路径和将包含的内容一起报告:
aggrega build --release releases/production.yaml --dry-run==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==apiVersion: v1kind: ConfigMap...
Total build time: 2.5sDry run: 1 file would be written to <workspace>/dist; nothing was written产物按构建写入它们的顺序报告,因此相同的输入会以相同的顺序报告相同的字节;报告的路径就是构建将写入的路径——位于工作区根目录之下,在上文 <workspace> 所在之处写出完整路径。
不会写入的内容。 输出目录保持原样——也不会被清理,因此先前构建的输出在试运行后完整保留。不会写入锁文件。不会向 .trace/ 写入任何内容。
外部输入的行为与普通构建完全相同,遵循构建时的外部输入所述的条件。因此,试运行读取的固定闭包与它所代表的构建将读取的相同,它展示的就是该构建将写入的内容。
如果某个引用被拒绝,运行会列出它无法访问的每一个引用,并指向用于固定它们的命令:
note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit: - https://charts.example.com/values-schema.json Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run again运行一次 aggrega pull,试运行就具备了所需的一切;它的其他方面不会改变。
试运行需要锁文件,且从不填充锁文件。 构建默认是只读的,无论以何种方式请求填充,试运行都坚持这一点。--auto-pull 和 --upgrade 会被直接拒绝(见下文);auto_pull 工作区设置在该次调用中被覆盖,因此默认会填充的工作区仍然可以预览。没有锁文件时,试运行会停止,并给出与普通只读构建相同的补救措施:先运行 aggrega pull。
它拒绝的标志。 有三个标志会执行写入,因此将它们与试运行搭配没有诚实的结果——忽略写入会让请求的填充凭空消失,而执行写入会打破试运行做出的唯一承诺。每种搭配都会在任何工作开始前停止,并指出你传入的标志以及应改为运行的步骤:
| 搭配的标志 | 拒绝原因 |
|---|---|
--auto-pull | 会填充锁文件;请将 aggrega pull 作为单独的步骤运行 |
--upgrade | 会重新解析每个依赖并重写锁文件;请将 aggrega pull --upgrade 作为单独的步骤运行 |
--trace | 会向 .trace/ 写入逐节点文件;请在不带 --dry-run 的情况下运行带追踪的构建 |
其他一切都可以正常组合。--verify-determinism 会将每个节点渲染两次并比较字节,但不写入任何内容;--catalog、--quiet、--progress、--debug 和警告过滤器的行为与执行写入的构建完全相同。
它的用途,以及它不适用的场合。 试运行回答的是“这个 Release 会输出什么”,这个问题只有渲染才能回答——因此它不能替代 aggrega validate(不渲染即检查正确性),也不能替代 aggrega inspect(在渲染前查询图)。当你想要的答案就是产物本身时,请使用试运行:审查某个 Release 变更对输出的影响,或在向 dist/ 提交任何内容之前检查对 Recipe 的编辑。
跟踪输出
--trace 标志会开启按节点的调试转储,记录编译器的每一个中间状态。输出位于工作区根目录下的 .trace/,与 dist/ 并列(绝不在其下;这种同级布局遵循 .git/、.terraform/、node_modules/ 的约定,并让 dist/ 保持纯粹可部署)。
目录布局按边界、按实例组织:
.trace/└── boundaries/ └── <boundary-path>/ └── <instance-id>/ ├── 01-pillars-initial.yaml ├── 02-provides-evaluation.yaml ├── 03-inject-hydration.yaml ├── 04-inject-mapping.yaml ├── 05-source-resolution.yaml ├── 06-source-locals.yaml ├── 07-values-mapping.yaml ├── 08-workload-synthesis.yaml ├── 09-artifact-evaluation/ │ └── <per-artifact-file>.yaml ├── 09b-feature-rendering-boundary.yaml ├── 10-engine-synthesis/ │ └── <per-synthesized-file>.yaml ├── 11-engine-emission.log └── 12-labels-injected.log每个槽位记录一个特定的编译器状态:
01-pillars-initial.yaml— 模板所读取上下文的按节点快照,在解析之后、任何按阶段变更之前获取。包含.values、.infra、.context、.parameters、.metadata。02-provides-evaluation.yaml— provides 求值之后已解析的provides:输出。03-inject-hydration.yaml— inject 填充之后合并的.context.inject管道(上游provides在消费方的视图)。04-inject-mapping.yaml— FeatureRecipe 的injectMapping重写之后的.context.inject管道。05-source-resolution.yaml— provider 将要消费的已解析source:内容。仅当 Recipe 声明了source:时存在。06-source-locals.yaml— 已解析的locals:块。source 解析会在对source:模板求值之前发布.locals,因此无论 Recipe 是否声明source:,都会写入此槽位。07-values-mapping.yaml— 渲染后的valuesMapping:输出(provider 接收的字典)。仅当 Recipe 声明了valuesMapping:时存在。08-workload-synthesis.yaml— 对workload:模板求值并解析其输出时的上下文。仅当 Recipe 声明了workload:(内联或通过$import:加载)时存在。解析后的Workload本身不在此槽位中:它从09-artifact-evaluation/起出现,此时它已确定,而不是仍在处理中。09-artifact-evaluation/— 每个已求值的制品一个文件。仅当 Recipe 声明了artifacts:(条目内联或逐条通过$import:加载)时存在。09b-feature-rendering-boundary.yaml— 节点渲染结束时的上下文,即附加到该节点的 FeatureRecipes 生成其资源之后的上下文,旁边附有解析后的workload。为每个节点写入。10-engine-synthesis/— provider 从 Workload 生成的每个合成清单一个文件(helm/compose workload 模式)。仅当 provider 执行了合成路径时存在。11-engine-emission.log— 该节点的输出后摘要(文件数、输出路径)。12-labels-injected.log— 为该节点写入渲染输出的来源标签和注解。
从 03-inject-hydration.yaml 起,凡是显示节点上下文的槽位,只要其捕获的管道通过任意机制交付了至少一个键,就会带有 .context.inject 块:这些机制包括 env、file、arg,或由 inject 映射、FeatureRecipe 的 injectMapping 或组件自身的 inject: 块写入的其他名称的机制。仅通过此类自定义机制交付的节点同样会显示该块,该机制以其自身名称出现,其键位于 all 中,而声明为敏感的值在这两处都显示为 <redacted>。在管道未交付任何内容时取得的槽位不含 .context.inject 块。
跟踪写入器是非阻塞的:跟踪与编译同时写入磁盘,而不位于编译的路径上。编译延迟不受跟踪 I/O 影响——无论 --trace 开启与否,同一次编译都在相同的实际耗时内完成。
trace 中声明为敏感的值
作者声明为敏感的数据——带有 sensitive: true 的 schema 叶子,或其内容来自带有该声明的 provides 键的交付键——在 trace 中写为固定文本 <redacted>。键会保留,只替换值,因此槽位仍能显示节点携带了哪些叶子和哪些交付键。同一块中未声明的同级项会原样打印其值;替换只依据声明,不依据其他任何因素。
FeatureRecipe 通过其自身的 injectMapping 交付的值同样会被隐去。声明空 inject 列表的槽位正是把交付交给这一途径,仅注入的凭据实现也走这一途径。这种映射写入的交付键本身是模板,因此没有任何声明为其命名;读取的是映射自身的文本。当该文本引用了所附加 Feature 声明为 sensitive: true 的 values 或 infra 叶子时,该映射产生的每个交付键都显示为 <redacted>——包括不携带任何敏感内容的键,因为判断是按附加而非按键进行的。未引用任何已声明内容的映射会原样打印其键。
由模板根据声明为敏感的数据计算得出的值也会被隐去,即使其自身的键不带任何声明。识别依据是作者写下的引用:模板读取了声明为敏感的叶子的 locals: 条目会被隐去,这样做的 source: 字段也会被隐去。该判断是保守的——访问整个对象的模板会访问其下每个已声明的叶子,因此只要 creds 下有任何内容被声明,{{ range $k, $v := .values.creds }} 的输出就会被隐去——读取已被隐去的同级项的 locals: 条目也会随之被隐去。形状相同但未读取任何已声明内容的同级条目会原样打印。
经由 uses 边传递的值依据目标的声明而非消费节点的声明被隐去,并且在该边所传往的两个位置上都会被隐去。.context.uses.<alias>.provides 重现目标 component 发布的内容,因此决定这些值的是目标的 schema:目标声明为敏感的 provides 键在消费者的槽位上显示为 <redacted>,即使消费者完全没有任何声明。当边自身的 inject 块将该键路由到消费 component 的某个交付键上时,.context.inject 也会隐去该交付键——这与附加的 inject 映射已遵循的规则相同,读取的是同一声明。隐去按边进行,因此发布同名 provides 键的两条边各自独立解析:其目标声明了该键的那条被隐去,另一条原样打印。边的其余部分——其目标、其 socket、其标签以及 inject 映射自身的键名——不受目标的 provides 声明约束,会原样打印。
在边上直接编写的按连接的 values 和 infra 则由消费组件的 socket 约束:即该 socket 声明的 valueSchema 和 infraSchema,它们是验证该配置所依据的契约。任一契约声明了 sensitive: true 的叶子,在 .context.uses.<alias>.values 或 .context.uses.<alias>.infra 处显示为 <redacted>,键保留;取值为契约所声明默认值的叶子也是如此;未声明的同级项原样打印。目标的声明在此不起作用,且隐去按连接进行,因此在 socket 将其声明为可读的连接上,同名叶子会原样打印。
写在连接上的附加显示在该连接的边之下,位于 .context.uses.<alias>.features.<slot>,每个附加都依据其自身 Feature 的声明被隐去——与 component 直接持有该 Feature 时约束它的声明相同。Feature 声明为 sensitive: true 的 values 或 infra 叶子显示为 <redacted>,Feature 声明为敏感的附加已解析 provides 中的键也是如此;每个键都会保留。附加的类型、版本和标签,以及其 Feature 未声明的每个叶子和 provides 键,都会原样打印,因此已发布的定位符在其所定位的内容旁仍可读。隐去按连接和槽位进行,因此写在两个连接上的同一 Feature 会在每个连接上分别解析。声明 sensitive: true 的槽位——无论在 component 上还是在其 socket 上——表示该附加处理机密内容,其本身不隐去任何叶子:隐去哪些叶子由 Feature 声明。component 自身的附加不在槽位显示的块之列,因为 trace 不携带 .features 块;workload: 模板从中读取的内容由下文的重新渲染覆盖。
解析后的 Workload 是一次重新渲染,而不是对构建所输出文档的捕获,携带它的槽位——09-artifact-evaluation/、10-engine-synthesis/ 和 09b-feature-rendering-boundary.yaml——会在其旁的 workload_note 条目中说明这一点。渲染后的文档不记录某个字符来自哪个声明,因此其中没有可替换的键。trace 显示的是同一个 workload: 模板的第二次求值,所用上下文中声明为敏感的数据已显示为 <redacted>。由于模板在原本是字符串的位置看到的仍是字符串,结果保留了所输出文档的形状:相同的字段、相同的位置,<redacted> 位于被隐去数据本身的位置,其周围的字面文本保持不变。
重新渲染与实际输出在两方面不同,注释中均有说明:
- 根据值的内容进行分支的模板会渲染出不同结果。 针对特定值的
eq、长度测试、对其进行的哈希或编码:每一种都会看到<redacted>并产生不同结果——不同的分支、不同的长度、不同的摘要。这就是 trace 从不声称显示所输出文档的原因。 - 未被任何声明命名的数据会原样传递。 替换覆盖该机制所命名的内容——已声明的
values/infra叶子、已标记的交付键、component 自身的 Component 声明为敏感的provides键、所消费目标已声明的provides、连接自身的values或infra中由其 socket 声明为敏感的叶子、component 自身持有的附加(在.features.<name>处读取)或写在连接上的附加的已声明叶子或provides键,以及由上述任一项计算得出的locals:或source:值。模板引发的拒绝也是依据同样的数据被隐去的。通过其他任何途径到达模板的数据,例如未被任何声明命名、其值由 Recipe 根据已声明叶子计算得出的provides键,在重新渲染中的呈现与在所输出文档中完全相同。
当完全无法生成重新渲染时,槽位会保留 workload: 键,并将文档替换为一行说明此情况并提及 --trace-unredacted 的文字。这样做是有意的:直接消失的投影将无法与根本未声明 workload: 的 Recipe 区分开来。
在将 .trace/ 视为安全之前,有一个限制值得了解:dist/ 不会被脱敏。 渲染产物按渲染生成的原样输出,因为它们是可部署的内容,trace 的重新渲染从不触及它们——无论 --trace 开启与否,相同的输入都会渲染出逐字节相同的结果。
应将 .trace/ 视为携带机密内容,并像处理 dist/ 那样处理它。
显示被隐去的值
--trace-unredacted 与 --trace 一同使用时,会将声明为敏感的值写入跟踪文件,而不是写入替代它们的文本。之所以提供该标志,是因为被隐去的值有时正是需要调试的对象:当两个凭据都显示为已隐去时,来自错误挂载的凭据与来自正确挂载的凭据看起来完全相同。
这也是捕获构建实际输出的文档的方式:没有任何值被隐去,也就没有需要替换的内容,因此 workload: 槽位承载的是输出的文档本身,而不是它的重新渲染,并且不会出现 workload_note 条目。
它受以下三个特性约束:
- 它写入的每个文件都会说明自身的性质。 本次运行生成的每个跟踪文件都以一条注释开头,注释中指明该标志,并说明下文以明文形式显示声明为敏感的值,因此日后附加到缺陷报告中或留在共享目录中的文件会自带警告。该注释在文件自身的格式中是合法的,因此文件仍可被解析。
- 它只影响
.trace/,不影响其他任何内容。 无论是否使用它,渲染出的制品都逐字节相同:它改变的是调试文件显示的内容,而不是构建产出的内容;aggrega inspect的布局以及构建失败时打印的诊断文本在两种状态下也完全相同。 - 它只在单次调用中生效。 没有对应的配置项,因此无法一次开启后,对之后构建该工作区的所有人一直保持开启。在未使用
--trace的情况下请求它,会使构建停止,并给出一条同时指明这两个标志的消息,而不是接受一个无法满足的请求。
与跟踪无关,构建会针对每个以字面值形式承载声明为敏感的内容的投递键打印一条提示,指明对应的 component、目标、挂载和投递键。该提示从不停止构建,--no-unsupported-field-warnings 也不会屏蔽它:该标志涵盖的是目标无法支持的你所编写的内容,属于另一类情况。
该关键字、它的两个编写位置、该提示的确切措辞,以及声明它所能达到效果的完整上限,见 vocabulary/compact-form-authoring.md 中的“Declaring a leaf sensitive”。
何时使用 --trace
- 诊断渲染出的 manifest 为何缺少预期的值:逐一查看每个 pass 的转储,找到该值首次缺失的槽位。
- 在编译器升级后验证确定性:对同一输入使用
--trace编译两次,会生成字节完全相同的跟踪转储;任何按槽位比较出的差异都能定位回归问题。 - 迭代编写 catalog:比较
04-inject-mapping.yaml和06-source-locals.yaml快照,可以看出该 Recipe 的模板在求值时看到的内容。
示例
针对本地 catalog 编译一个 Release:
aggrega build --release releases/production.yaml使用单独的 catalog 目录进行编译:
aggrega build --release releases/production.yaml --catalog ../platform-catalog/查看一个 Release 将会输出的内容,而不写入任何文件:
aggrega build --release releases/production.yaml --dry-run编译时生成 trace 转储以便调试:
aggrega build --release releases/production.yaml --trace编译完成后,检查 .trace/boundaries/<boundary>/<instance>/ 以查看每个阶段的状态。每次使用 --trace 运行时,.trace/ 目录都会被覆盖;之前的 trace 状态不会跨编译保留。
交叉引用
aggrega-pull— 从 OCI 镜像仓库将目录实体拉取到本地目录。aggrega-validate— 检查目录、Release 闭包或单个实体的正确性,不生成制品;即构建所执行的依赖校验,但不进行渲染。aggrega-lint— 在相同的三个范围内检查目录发布约定。aggrega-inspect— 在图最终确定后查询 IR 图,而不继续进行渲染。- 错误 — 在 CLI 中呈现的分类错误渲染格式。
概要
aggrega build [flags]说明
Compile an Aggregate and Release pair into provider-native artifacts under eachboundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,declares the boundaries, and routes each component to a provider. What aprovider emits is the provider's own shape — Helm manifests, a redistributableHelm chart, docker-compose YAML — so the output directory holds whatever theproviders this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder thecommand is run from, and the closing line names it in full. A run that finds noworkspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first tocreate one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makesthe rendered tree reviewable as a diff.标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--auto-pull | false | 在构建前运行拉取步骤:在进程内将该 Release 的依赖解析到 lockfile 和缓存中,然后基于它们进行构建。这与工作区 auto_pull 设置所执行的进程内填充相同,只是无需编辑工作区配置即可为单次构建启用。单独使用时它是增量填充——保留现有的固定版本,并解析和添加没有固定版本的引用 |
--catalog | [] | 目录路径;可重复指定。每个 —catalog <dir> 都会被添加到目录搜索栈的最前面(首个匹配者胜出):该栈为工作区的 catalog_dirs,或者,对于工作区配置在 workspace.releases 下为其单独指定目录的 Release,则为该 Release 的目录;如果工作区根目录下存在名为 catalog 的目录,该栈以它结尾。写为空列表的 catalog_dirs 完全不读取任何本地目录。 |
--debug | false | 在 stderr 上输出人类可读的详细诊断信息——各阶段的实际耗时以及实体/依赖数量。优先于 —quiet:详细输出总会输出。不同于 —trace,后者将机器可读的逐节点中间文件写入 .trace/ |
--detail | false | 构建默认是只读的,且不打印解析详情。当拉取步骤运行时——因为传入了 —auto-pull 或工作区启用了 auto_pull——无论 lockfile 是否已存在,构建都会在进程内填充它,此标志会针对每个已解析的实体打印该填充所做的操作:从镜像仓库新拉取、复用缓存槽、在本地目录中找到、由编译器二进制文件内部提供,或外部(该 Release 自身的 Aggregate 或 Manifest,从 Release 指定的文件或条目中读取)。未运行拉取步骤时,它会打印一行说明这一点,而不是逐实体的行。仅输出到 stdout;不持久化 |
--disable-plugin-cache | false | 本次构建跳过持久化的磁盘插件编译缓存,改为在内存缓存中重新编译插件 guest,该缓存在构建结束时丢弃。默认关闭,即在多次构建之间复用共享的磁盘缓存。不改变渲染输出 |
--dry-run | false | 渲染该 Release 并打印其将要生成的内容,而不是写入:每个制品的预期路径及其内容输出到 stdout,输出目录和 lockfile 保持不变。外部输入的行为与普通构建完全相同——已固定的输入由内容寻址存储提供(blob 缺失时按摘要重新填充),请求未固定外部 URL 的渲染会停止并指出该 URL——因此试运行显示的就是构建将写入的内容。拒绝与 —auto-pull、—upgrade 或 —trace 组合使用,因为它们都会写入——请将依赖填充或带追踪的构建作为单独的步骤运行。可与 —policy-input 组合使用,此时该标志的文件是它唯一写入的内容 |
--ir-graph | false | 除该命令已生成的所有内容外,还将本次运行计算出的 IR 图以 JSON 格式写入 stdout。作者声明为敏感的值不会包含在其中;传入 —unredacted 可改为打印这些值。制品仍会写入,摘要仍会打印;图在两者之前写出 |
--no-unsupported-field-warnings | false | 屏蔽不受支持字段这一类警告:即目标针对你编写的、它无法遵从的内容发出的提示——它无法表达的 Workload 字段(例如 compose 这类低保真目标),或它对该节点的输入类型不予处理的 aggrega.ai/ 注解。其他渲染警告仍会显示。仅影响显示;不改变渲染输出 |
--policy-input | — | 将每个治理角色交给附加在该处的插件的负载写入此目录,每个负载为一行 JSON:与构建交给插件的内容完全一致,构建对插件隐去的每个值也同样被隐去。对于 annotation-transform、label-transform 和 ir-verdict,该文件就是该角色上的策略所读取的 input 文档。对于 render-verdict,策略引擎会在策略读取之前重塑负载——每个制品的 documents 都从中解析得到——因此内置引擎上的 render-verdict 策略要在构建中测试,并以报告级别为 warn 或 info 的方式附加;对于你自己构建其 .wasm 的插件,aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json 会在该文件上运行它。没有任何附加项的角色也会被写入,内容是一个没有来源、没有设置的附加项将收到的负载,因此可以在附加策略之前编写它。每个角色写入 <role>.json(annotation-transform、label-transform、ir-verdict、render-verdict);如果同一角色上的附加项收到不同的负载——其中一个带有自己的来源或设置,或者某个转换改变了下一个所读取的内容——则每个附加项改为写入 <role>.<position>.<plugin>.json,其中 position 按工作区配置列出它们的顺序从 1 开始为该角色的附加项计数,plugin 是插件引用中不含版本的最后一段,文件名无法容纳的字符都会被转义。目录中已有的同名文件会被替换,其中的其他内容不受影响。无论构建完成还是停止,这些文件都会被写入;在某个角色运行之前停止的构建会指出它没有为之写入文件的每个角色。请求这些文件不会改变任何制品,也不会改变任何裁决。可与 —dry-run 组合使用,此时它只写入这些文件:输出目录和 lockfile 保持不变 |
--progress | false | 即使 stderr 不是终端,也强制开启构建进度显示,在每个步骤完成时打印一行纯文本及其耗时。默认值为 auto:仅当 stderr 是能解释转义序列的终端时才显示交互式阶段清单,不能解释的终端会得到相同的纯文本行,而重定向或管道输出则不显示任何内容。—quiet 和 —debug 都会覆盖 —progress |
--quiet | false | 屏蔽 stderr 上的构建进度显示。不影响 stdout。优先于 —progress |
--release | — | Release YAML 文件的路径(必填)。相对路径相对于你运行命令所在的目录解析,而不是相对于工作区根目录。当该目录不属于任何工作区且未指定根目录时,绝对路径会从该 Release 自身所在的文件夹查找工作区 |
--trace | false | 将逐节点的中间文件写入工作区根目录下的 .trace/(与 dist/ 并列),用于事后检查 |
--trace-unredacted | false | 将声明为敏感的值写入 .trace/ 文件,而不是用来代替它们的 |
--unredacted | false | 打印作者声明为敏感的值,而不是隐去它们。输出所到之处——终端、管道、文件、屏幕录制——都将以明文携带这些值。只作用于 —ir-graph 写出的图,因此需要 —ir-graph;.trace/ 文件则改用 —trace-unredacted |
--upgrade | false | 使自动拉取步骤成为完全刷新:丢弃现有的 lockfile,并根据镜像仓库的当前状态重新解析每个依赖,将每个依赖浮动到可用的最高版本,而不是保留现有的固定版本。隐含 —auto-pull——单独使用时会在构建前运行完全刷新的拉取。它不接受目标,因此无法缩小到单个依赖:如需采用或移除单个固定版本,请改为运行 aggrega pull —upgrade —release |
--verify-determinism | false | 将每个节点渲染两次并比较生成的字节,如果任一节点的两次渲染结果不同则停止构建。默认关闭。可用它确认 provider 的渲染是确定性的——相同的输入产生字节完全相同的输出——GitOps 差异比较和字节一致输出的保证都依赖于此 |
--yes | false | 预先应答 —upgrade 的确认,用于非交互式场景。它只作用于这一个提示:不进行刷新的构建不会询问任何内容,因此在那里传入它不会改变任何行为 |