aggrega inspect
aggrega inspect 为任意 Aggrega 实体生成人类可读的视图:目录中的 Component、编写的实体文件、发布在注册表中的实体,或完全解析后的 Release。它是理解编译器将产生什么的标准调试界面:哪些 Components 扩展了哪些基础,每种类型映射到哪个 Recipe,每个节点附加了哪些 Features,以及每个 Feature 的贡献究竟来自何处。
每种实体类型都有一个自然的“契约”视图。inspect 展示的就是这个契约:Component 发布的 schema、Manifest 声明的映射、Aggregate 构建的拓扑、Release 解析得到的各节点 Feature 附加项。教程和概念性内容位于其他位置;inspect 回答的是“这个实体实际解析成什么?”
单个位置参数按内容形态路由,无需子命令。该命令按以下启发式规则分派:
| 标识符形态 | 分派 | 输出 |
|---|---|---|
以 ./、../ 或 / 开头,或以 .yaml / .yml 结尾 | 文件分支 | 按文件的 kind: 头部进行逐文件检查。 |
以 oci:// 开头 | 注册表分支 | 发布在该坐标处的实体,从其注册表读取,并以其类型的文件所用的视图呈现。参见读取已发布的实体。 |
| 其他任何形态 | 目录分支 | 在目录搜索栈中跨所有实体类型查找该标识符;解析 extends: 链;呈现匹配类型自身的视图。 |
三个详细级别
--list、默认级别和 --detail 构成统一的三级详细程度规则,每种实体类型都遵循这一规则。--list 与 --detail 互斥——同时传入两者会被拒绝,而不是被静默处理。
--list——仅显示标识符。Component 列出其名称及其 uses 插槽名称;MappingLibrary 列出其映射名称;Aggregate 列出其组件名称及其类型。- 默认——为交互式使用而调整的结构化概览。它首先显示实体的标识;对于除 Manifest 和 Release 之外的每种类型,若实体编写了描述,还会显示其描述;没有描述的实体不打印描述,而不是打印一个空行。其余结构因类型而异:Component 显示其 schema 和插槽;Aggregate 显示组件、组件的值、边及每个连接携带的附加项,以及依赖图;Release 显示按边界划分的节点树及 Feature 附加项,每个写在某个连接上的附加项都列在该连接下方。
--detail——完整的字段内容。显示该类型携带的全部内容:Component 增加其自注入机制、所需的 Features 和标签;MappingLibrary 展开每个映射的完整模板内容;Recipe 增加其 workload 内容、provides 和断言。
少数类型利用这些级别逐步展示更多的编写内容。MappingLibrary 在 --list 级别显示映射名称;在默认级别增加每个映射合成的用法示例;在 --detail 级别展开完整的模板内容。
解析:--raw 与 --resolved
每种类型都有其自然的默认解析深度(见下表)。--raw 和 --resolved 是始终可用的覆盖选项,二者互斥——同时传入会被拒绝,而不是被静默处理:
--raw退出所有解析——实体按编写时的原样直接从文件输出。--resolved启用该类型的完整解析深度。
对于默认按原样输出的类型,--raw 不起作用,--resolved 触发该类型所支持的解析。对于默认输出解析结果的类型,--raw 用于绕过解析、按原样输出。
--raw 会重现文件,因此作者声明为敏感的值会完全按编写时的原样出现在其中。这是契约,而非缺陷——一个悄悄隐去自身部分内容的原样视图就不再是原样了。处理 --raw 输出时,请像处理其来源实体文件一样对待。--output yaml 以同样的方式重现文件,适用于所有类型,包括 Release。
Release 还回答另外两个问题,每个问题对应一份不同的文档和各自的标志。Release 解析得到的编译图是 --ir-graph;其依赖闭包是 --closure。参见下文的机器可读输出和依赖闭包:--closure。
各类型的默认值
inspect 支持下表中可独立检查的类型。目录类型默认按编写原样渲染——它们的文件是自包含的契约。实例类型默认显示解析后的视图,因为其编写的 YAML 只是级联或流水线的起点。
| 类型 | 默认值 | “已解析”的含义 |
|---|---|---|
| Component | 按编写原样 | 该文件是自包含的契约;解析针对 Manifest 绑定进行,通过 --show-implements 呈现。 |
| Feature | 按编写原样 | 与 Component 相同。 |
| Recipe | 按编写原样 | --show-implements 解析 spec.implements 中的 Component 引用。 |
| FeatureRecipe | 按编写原样 | --show-implements 解析 spec.implements 中的 Feature 引用。 |
| MappingLibrary | 按编写原样 | 条目是不透明的 Go 模板字符串;渲染在使用时进行。 |
| SchemaLibrary | 按编写原样 | 条目是可复用的 schema 和模板定义,在使用时解析。 |
| WorkloadLibrary | 按编写原样 | 条目是 Recipe 导入的可复用 Workload 主体,在使用时求值。 |
| ArtifactLibrary | 按编写原样 | 条目是 Recipe 导入的可复用制品包,在使用时渲染。 |
| Plugin | 按编写原样 | 该文件是自包含的插件契约:插槽类型、各导出项的能力、运行时约束以及签名指针。可通过文件路径寻址,也可通过其在目录中的 <pluginType>/<name> 坐标寻址。 |
| Manifest | 已解析 | 应用 extends: 链;列出解析后的 component 和 feature 映射。 |
| Aggregate | 已解析 | 构建拓扑——计算 uses 图和排序。 |
| Release | 已解析 | 运行完整流水线:解析、展开注解、运行守卫、构建拓扑、构建 IR。 |
kind: 为 Workload 的文件会被拒绝:Workload 只嵌入在 Recipe 中存在,不是可独立检查的实体。要查看其 Workload,请检查对应的 Recipe。
各类型的解析深度
大多数类型没有流水线——inspect 读取文件并将其渲染。有三种实例类型会进行有实际意义的解析:
- Manifest 会应用其
extends:链(即跟随文件导入),并渲染合并后的 component 与 feature 映射。--raw显示按原样编写的文件。 - Aggregate 会构建其拓扑:构造 uses 图并计算依赖顺序。默认视图显示各 component 及其值和边,随后是依赖图。
--raw显示所编写的子系统树。 - Release 会运行直到 IR 为止的整个编译流水线——解析、展开注解、运行守卫、构建拓扑、构建 IR——并渲染按边界划分的节点树,以及每个节点的 Feature 附加项及其来源。塑造图的治理附加项会在该流水线中运行,而不会因为只是查看而被跳过,因此你读到的内容反映了它们所做的决定:
label-transform附加项的标签在任何匹配发生之前就已就位,annotation-transform附加项注入的注解会像你自己编写的注解一样展开为 Feature 附加项。如果某个附加项的 plugin 无法被该命令解析,命令会停止,而不是给你一张缺少该 plugin 决定的图。扩展另一个 Release 的 Release,在此视图和--ir-graph中都会被绘制为其extends:链组合而成的 Release,即构建它时所读取的那个 Release,因此只指明其父级的 Release 会以自己的名称显示父级的 Aggregate、Manifest 和边界。Release 所指明的 Manifest 同样会通过其自身的extends:链进行组合,无论该 Release 是否扩展了其他 Release,因此其映射为该 Manifest 继承所得的附加项会显示构建所使用的实现。--raw原样输出 Release 文件,不运行流水线。--closure针对同一个 Release 提出另一个问题,完全不运行流水线;参见依赖闭包:--closure。
没有单独的深度标志;--raw / --resolved 开关是唯一的解析控制,叠加在每种类型的自然默认值之上。
错误行为
被引用的同级文件一旦加载失败,命令会立即停止——例如某个 Release 指向缺失的 Aggregate,或搜索栈中某个 catalog 实体已损坏。命令会给出清晰的消息并停止,而不会渲染部分输出;加载失败也没有出错后继续的模式:一旦解析所需的某个文档无法读取,就没有可以继续解析的内容了。当名称解析停在一个被加载拒绝的 catalog 文档上时,消息只陈述一次该拒绝:先是带有类别的开头,若拒绝指明了某个条件,则附上其短代码,然后是该文档,再是它的问题所在——对于被其 kind 的 schema 拒绝的文档,给出行号及其违反的约束。消息不会建议移动该文件——catalog 已经读取了它,正因如此它才被拒绝。
组合被编译器检查拒绝的 Release 会被拒绝,而不会被渲染。 解析 Release 会构建图,构建对完成后的图所做的检查——目标不满足其 socket 的 selector: 的 uses: 边、附加到其 appliesTo: 不接纳的组件上的 Feature,等等——在这里同样会执行,并给出构建相同文档时打印的诊断。拒绝会在一次运行中列出所有问题,而不是在第一个问题处停止,因此一次运行就能让你看到需要更正的完整列表,而不只是其中第一项。正是这一点让该命令如实反映部署情况:如果视图渲染了构建会拒绝的组合,就会在工作区有问题时报告它没有问题。不进行任何解析的选项不受影响——--raw、--output yaml 和 --closure 会重现或解析你编写的内容,而不构建图。
如果 Release 的锁文件与其解析结果不再一致,该 Release 会被拒绝,并给出 aggrega build 打印的中止信息。当锁文件位于 Release 旁边时,每个会解析该 Release 的选项——默认视图、--resolved、--ir-graph 和 --closure——都会使用构建在渲染之前执行的漂移比较,检查锁文件是否与 Release 的解析结果一致。不再一致的锁文件会以构建的 E0130 拒绝中止该命令:先列出每个发生漂移的条目,再给出用于消除漂移的 aggrega pull --release <release>。不会向标准输出写入任何内容,命令以非零状态退出,因为根据当前状态的目录绘制出的图景,会展示该 Release 的任何构建都不会渲染出的内容。--raw 和 --output yaml 单独使用时既不读取锁文件也不读取目录,因此不受此约束。旁边没有锁文件的 Release 会基于当前状态的目录进行解析。
kind: 无法识别的文件会报告该未知 kind 及其来源文件。Workload 文件会报告该 kind 仅可嵌入,并指出它嵌入在哪个实体之下。无法读取的 oci:// 标识符会被拒绝,并给出说明原因的条件;读取已发布的实体列出了这些条件。
目录解析
目录搜索栈按分层优先级组装:--catalog 标志(按顺序前置)最先,其次是 .aggrega-config.yaml 中工作区的 catalog_dirs——对于配置在 workspace.releases 下为其单独提供目录的 Release,则在该位置使用该 Release 的目录——最后是工作区根目录下的 catalog 目录,无论是否有配置指向它,都会读取。catalog_dirs 写为空列表的工作区完全不读取本地目录。该栈采用先到先得:最早声明某个实体标识的目录拥有该实体,之后目录中的副本会被遮蔽。目录分支在该栈中按固定优先级跨所有实体种类解析标识符,并通过该种类自身的视图渲染第一个匹配项;当需要解析 Manifest 映射或 extends: 父项时,文件分支和 release 分支会从该栈加载被引用的目录实体。栈中没有的 extends: 父项会从构建读取它的位置读取:即从制品缓存中,依据某个 Release 的锁文件为其记录的固定版本读取——指定了 Release 时为该 Release 的锁文件,未指定时为工作区中每个 Release 的锁文件。因此,发布到注册表的基础项在 aggrega pull 拉取并固定它之后即可在此解析,而在此之前,该命令会被拒绝并指明 aggrega pull --release <release>。不会拉取任何内容。
按 Release 的条件查找名称
单独给出的名称在工作区自身的栈中查找。在其旁边给出 --release <release-path>,则改为在该 Release 的栈中查找名称——即工作区配置为该 Release 提供的目录,并前置任何 --catalog——这正是构建该 Release 时读取的内容。因此,对于每个 Release 保留一个目录变体、且每个变体都声明同一实体的工作区,查找名称时会得到该 Release 构建时所用的变体:
aggrega inspect core/datastore/mariadb --release release-helm-synth.yaml该 Release 的栈无法解析的名称会被拒绝,关于本地实体读取位置的说明会指出该 Release 在 workspace.releases 下的条目,因为查找读取的正是该条目。--release 选择查找名称所用的栈,因此它只适用于单独的名称:文件路径和注册表引用按原样读取,并会拒绝该标志。指向不存在的文件或指向目录的 --release 会在任何查找之前被拒绝。
读取已发布的实体
aggrega inspect oci://<host>/<repository>:<tag> 读取发布在该坐标处的实体;用 @<digest> 代替 :<tag> 可精确指定一个 manifest。这是查看仅存在于注册表中的实体的方式——仓库由种类段加上实体的标识组成,如 Catalog and Registry §6 所述;aggrega push 会打印它发布时所用的引用,在这里于其前面加上 oci:// 即可读取。
你看到的是实体发布时的样子。 连同其声明的文件一起发布的实体——带有本地 chart 或 lock 的 Recipe、带有所导入 schema 的 Component——以归档形式发布,实体从归档中解包:取归档根目录下声明了可发布种类的文档,因此随附的 chart 模板或 compose 片段不会被误认为该实体。未声明任何文件的实体按其文档原样发布;Plugin 的实体从其 manifest 读取,而不是从随其发布的可执行文件读取。随后该文档由与该种类文件相同的视图渲染,具有相同的详细级别以及相同的 --raw 和 --output yaml。不应用任何继承:视图反映的是发布者放在该坐标处的内容。可读布局最后列出所读取的内容:坐标、该坐标以归档还是以文档本身的形式保存该实体、其 manifest 声明的媒体类型,以及该 manifest 的摘要——以 @<digest> 代替 :<tag> 写出时,会再次读取相同的字节;--output yaml 只打印文档,其后不附加任何内容。
它检查什么,不检查什么。 获取的字节会与制品自身 manifest 为其记录的摘要进行比对,以确认它们就是该 manifest 所指定的字节。这是针对注册表所提供内容的检查,而不是针对任何事先记录内容的检查:不会验证附加在制品上的签名,也不会报告针对它记录的撤回。不写入任何内容——既无缓存条目也无 lockfile——因此读取一个坐标不会改变之后构建所解析的任何内容。
它会访问网络。 使用本机为该注册表持有的凭据连接注册表,凭据来自 aggrega push 和 aggrega pull 读取的同一存储;位于本机的注册表通过明文 HTTP 连接。处于离线状态的工作区会在发起任何连接之前拒绝读取。
无法给出结果的读取以非零状态退出,且不在标准输出上打印任何内容。 下面每种失败都会指明其条件以及应对方法;完全无法访问的注册表会报告导致读取中止的网络错误:
| 发生了什么 | 条件 |
|---|---|
| 该引用下没有发布任何内容 | E0137 |
| 注册表拒绝了凭据,或未为其存储凭据 | E0138 |
| 工作区处于离线状态 | E0125 |
| 制品是无法解包的归档 | E0300 |
| 归档根目录下没有实体文档 | E0298 |
| 归档根目录下有多个实体文档 | E0299 |
| 该文档不是注册表所发布种类的实体 | E0301 |
每个代码都列在错误参考中。未指定仓库、或既未指定标签也未指定摘要的引用会被拒绝,并给出应改写的形式。--ir-graph 和 --closure 会在获取任何内容之前被拒绝,因为注册表发布的种类中没有 Release。
弃用与撤回通知
发布者可以在发布制品之后为其记录一个标记,声明已发布的版本已弃用或已撤回。当目录分支解析一个实体时,inspect 会在该实体自身的视图下方报告任何此类标记——适用于它按名称解析的每一种类型,而不仅限于 Component。
通知会给出发布者记录的严重级别——warning、error 或 retracted——以及记录该标记的版本、原因、指定的替代项(如有)和发布日期。三种严重级别都会报告。这比会改变构建解析结果的那组级别更宽:标记为 retracted 的版本会被排除在版本选择之外,而 warning 和 error 仅作提示,仍会被选中。inspect 向你展示发布者说了什么;它不决定你得到什么。
通知读取自该实体所解析的注册表的本地索引,该索引由 aggrega registry update 构建——因此无需网络,在离线工作区中也能工作。由于索引是一个快照,通知末尾会说明该快照的生成时间,并给出刷新它的命令。未构建索引的工作区不会报告任何内容,因此没有通知意味着“此快照中没有记录”,而不是“没有记录”。
只有当标记自身的签名能通过注册表信任策略所认可的签名者验证时,才会报告该标记。未签名的标记,或签名无法验证的标记,不会被报告:无法认证的声明不会被当作事实呈现。
通知随人类可读的视图一同出现。--output yaml 和 --ir-graph 都不会附加通知,因此解析其中任一输出的使用方只会收到一份文档,别无其他。
示例详解
目录 Component 查找
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"默认视图会显示 Component 编写的描述(如有),然后是解析后的 schema(经过所有 extends: 合并之后)以及声明的 uses-socket。上面的 Component 没有编写描述,因此输出直接从 schema 开始。--detail 会额外显示自注入机制、所需的 Features 和标签;--list 只显示 Component 标识符及其 socket 名称。
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | values: { port?: int | *9090 }Uses sockets: backend: selector="component.aggrega.ai/type=stateful-server" inject: [env]Secret slots: token (required)Targeting: appliesTo: component.aggrega.ai/type=serverLabels: feature.aggrega.ai/category: observability使用 --show-implements 的 Recipe
Recipe 的默认视图为其声明的每种输入模式各显示一个部分,并显示其能力和值映射。--show-implements 会根据目录解析 spec.implements 引用,并渲染所绑定的 Component,以及该 Component 所需的附件:
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metrics声明多种输入模式的 Recipe
Recipe 的输入模式以叠加方式组合:要渲染的 source:、要合成的 workload: 和 artifacts: 映射各自产生输出,一个 Recipe 可以声明其中任意组合。inspect 会报告 Recipe 声明的每一种模式,而不是只挑选一种,因此你看到的就是你编写的集合:
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yaml各部分按 source: → workload: → artifacts: 的顺序排列,这与构建将 Recipe 解析为单一模式名称时,以及报告所绑定的 provider 无法支持哪种已声明模式时所用的顺序相同,因此此视图与构建的诊断信息以同一顺序列出各模式。既未声明 source: 也未声明 workload: 的 Recipe 会被报告为仅 artifacts,这是视图只列出单一模式的唯一情况。
Manifest(默认已解析)
$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings: Type → Recipe core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0 core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0 core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings: Type → FeatureRecipe core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings: (none)默认视图会应用 Manifest 的 extends: 链,并列出解析后的 component 和 feature 映射以及注解绑定。--raw 显示文件编写时的原样,即 extends 解析之前的内容。
Aggregate(默认已解析)
$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components: backend (type: core/compute/api-server) Values: (none) Uses: databases: - data.main-db frontend (type: core/compute/web-ui) Values: (none) Uses: apis: - my-api → backend main-db (type: core/datastore/postgres) Values: database_name: app_production Uses: (none)
Dependency Graph: data.main-db ↑ backend backend ↑ frontend默认视图会构建拓扑,显示每个 component 及其值和 uses 边,随后是计算出的依赖图。子系统树以嵌套方式渲染;--flat 为每个节点渲染一个部分,每个部分以其完整的点分路径为键。
以长格式编写的连接后面会跟着它所承载的附件,每个附件位于它在消费方 component 上所取的名称之下(即连接的别名与插槽以点连接),并附有它所指定的 Feature 类型,以及一个子句,说明它填充的插槽及其是否处理已声明为敏感的内容:
gateway (type: conn/gateway) Values: region: eu Uses: models: - gpt → model - gpt.credential (feature.conn/token) [slot: credential, sensitive]插槽和标记是部署此 Aggregate 的 Release 在构建时为该附件记录的事实,其读法与 Release 视图相同(参见附件连接、插槽与敏感性子句);它们来自 socket 的插槽声明和 Feature 自身的声明,因此不取决于由哪个 Release 部署该 Aggregate。Aggregate 不指定 Manifest,因此 Release 的 Manifest 为该附件选择的实现不会在此显示。此视图列出 component 的连接及其承载的内容;component 自身代码块中的附件显示在 Release 视图中。
Release(默认已解析)
Release 视图是影响最大的检查。它运行完整的流水线,并按边界渲染每个 Component 节点、其 uses 边,以及附加到该节点的每个 Feature(写在连接上的 Feature 显示在该连接的边之下),每个都附有其填充的附件插槽、是否处理已声明为敏感的内容以及实现它的 FeatureRecipe,另有一个来源括注,揭示该附件的来源:
$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns Directory: ./dist/backend Annotations (provider-consumed): aggrega.ai/namespace: backend-zone Component: backend (type: core/compute/api-server:1.0.0) Uses: data.main-db → data.main-db [cross-boundary] Features: (none)
Boundary: frontend-ns Directory: ./dist/frontend Annotations (provider-consumed): aggrega.ai/namespace: frontend-zone Component: frontend (type: core/compute/web-ui:1.0.0) Uses: my-api → backend [cross-boundary] Features: - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns Directory: ./dist/data Annotations (provider-consumed): aggrega.ai/namespace: database-zone Component: data.main-db (type: core/datastore/postgres:1.0.0) Features: (none)每个边界都带有其输出目录和由 provider 使用的注解;边界下的每个 component 都带有其 Aggregate component 类型、其 uses 边(跨边界的边会被标记),每条边后跟该连接承载的附件,以及该 component 自身的 Feature 附件,每个附件都带有其事实子句和来源括注。--flat 将边界树折叠为每个边界一个部分,以其完整路径为键。--raw 原样输出 Release 文件,不运行流水线。
YAML 输出
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: db: selector: component.aggrega.ai/type=stateful-server schema: values: port: {type: integer, default: 8080}按名称从 catalog 指定的 Component 会以 catalog 解析出的实体打印,因此在 extends: 合并之后,你看到的是合并后的实体,而不是编写的文件;Component 文件则按编写时的原样打印。
机器可读输出
有两个标志会产生机器可读输出,它们回答的是不同的问题。--output 为该命令本来就会渲染的文档选择一种格式;--ir-graph 则在此之外请求一份不同的文档——一个 Release 解析得到的编译图。二者相互独立:同时传入两者,你会得到图和按编写原样的 YAML,各一份。
--output yaml 按编写原样输出实体,适合用于管道传输和比对差异。该输出是逐字原样的,其中包括作者声明为敏感的值——一个声称重现输入的输出,不能隐去其中一部分却仍算是在重现它。请像对待其来源实体文件那样对它进行管道传输、存储和共享。
编译图:--ir-graph
aggrega inspect <release> --ir-graph 会将本次运行解析得到的图以 JSON 形式写入标准输出,位于该命令照常渲染的视图之前。输出为一个 JSON 文档加一个结尾换行符,因此解码该流的消费方读取完图后即停止。
它适用于 Release,这是唯一会解析为图的类型。若对其他任何类型,或按名称对目录实体使用,该命令会拒绝并说明原因,而不是渲染该实体自身的视图并悄悄忽略这一请求。
被编译器检查拒绝的组合不会产生图。错误行为中所述的拒绝发生在向此流写入任何内容之前,因此读取该流的管道绝不会收到一个对相同文档进行构建时会被拒绝的图——它收到的是构建会报告的相同发现,以及一个非零退出码。
aggrega build 和 aggrega validate 上也有同一个标志,含义相同:每个命令都会在其自身产出之外,返回该次运行计算出的图。编辑器集成通过守护进程的协议读取同一个图。
**--output yaml 不输出图。**它重现编写的 Release,与对其他所有类型的做法完全相同。需要图的管道应改为从 --ir-graph 读取,得到的是 JSON 而非 YAML。
**图会隐去敏感值。**它不是任何人编写的文件——而是编译根据 Aggregate、Release 和目录计算出的结果——因此不存在需要遵守的按编写原样的约定,支配可读布局的那些声明同样支配它。凡是图中带有作者声明为敏感的叶子,其值都会被替换为一个单键对象,标明该值已被隐去:
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}键会保留,因此图仍能回答一个节点及其附件带有哪些叶子;只有值被移除。同一载荷中未声明的同级项按编写原样输出——上例中的 secretName 是作者未声明的公开定位符,因此会被打印。标记附带的原因说明值缺失的理由:declared 表示叶子受某个声明覆盖,unreadable 表示载荷到达时的形态是该命令无法读取的,此时会隐去整个载荷,而不是猜测其中任何部分。
连接自身的配置也以同样方式隐去。Aggregate 在 uses 条目上编写的按连接的 values,以及 Release 在该条目上编写的按连接的 infra,都由消费组件的 socket 约束——即它声明的 valueSchema 和 infraSchema,也就是验证该配置所依据的契约——而绝不由目标的声明约束。任一契约声明了 sensitive: true 的叶子,会在边的 values 和 infra 中,以及在消费节点的 uses 条目(该条目按作者编写的原样携带这些值)中被标记替换;每条边会在 sensitive_payload_leaves 下列出它隐去的叶子,节点也用这个字段列出自己的叶子。在 socket 将其声明为可读的连接上,同名叶子会按编写的原样输出。
当管道确实需要这些值时,传入 --unredacted,并像对待实体文件本身那样对待其产出。aggrega build 和 aggrega validate 在 --ir-graph 之外也接受同一标志,条件相同:除非传入该标志,否则它们返回的图会隐去这些值。
守护进程的协议按相同规则提供同一个图。aggrega/irGraph 的响应会隐去这些值,只有对设置了 unredacted 字段(即该协议中此标志的写法)的请求才以明文返回。因此编辑器面板所绘制的内容遵循相同的声明,而显示这些值的客户端之所以显示,是因为它请求了这些值。
依赖闭包:--closure
aggrega inspect <release> --closure 报告该 Release 的依赖闭包:它所触及的每个目录实体及其各自解析到的版本,以及其两个指针所解析到的 Aggregate 和 Manifest 标识,还有这些实体所引用的共享文档。不渲染任何内容,也不生成任何产物——闭包只被解析,不被构建,因此回答它无需加载任何 provider。
**闭包与解析视图是不同的文档,二者都无法从对方还原。**解析视图——本命令默认为 Release 渲染的内容——说明部署的样子:它的边界、它的组件节点、什么连接到什么,以及每个节点上附加了什么。闭包说明为构建它引入了什么,以及引入的是哪些版本。一个实体可以被触及却从不作为节点出现——Manifest 将某个组件类型映射到的 Recipe 会被每次构建触及,却不是其中任何一次构建的节点——而一个节点记录的是它被声明时的组件类型,而不是该类型解析到的版本。因此,提出“这个版本为什么变了?”、“修改这个共享文档会影响什么?”或“这个部署实际依赖什么?”的读者,需要的是闭包;手持解析视图的读者,再怎么仔细阅读也得不到它。
**同一个词在每个界面上请求同一份文档。**这里的 --closure、守护进程协议上的 aggrega/releaseClosure(参见 aggrega serve “闭包不是图”),以及助手工具协议上 describe 工具的 release 模式,都回答关于某个 Release 的这一问题;通过其中任何一个传入 Release 名称都会得到相同的解析,因此三者不会在某个 Release 依赖什么这一点上出现分歧。如果 lockfile 已不再与该 Release 解析到的内容匹配,此命令和 describe 工具会以构建的漂移停止信息拒绝;而守护进程在编辑器编辑时为其提供服务,则照常作答。
它是一份独立的文档,因此要单独请求。--closure 选择闭包来代替解析视图,且不能与 --raw、--resolved、--output 或 --ir-graph 组合使用——这些选项各自请求关于同一 Release 的另一份文档,而一个接受两个请求的命令将不得不默默只回答其中一个。组合使用会被拒绝,并指出冲突的那对选项。
**它只适用于 Release,不适用于其他任何对象。**目录实体、Aggregate 文件、Manifest——它们都不解析闭包,因此该请求会被拒绝,而不是以渲染该对象自身视图并丢弃请求的方式作答。对调用方而言,被丢弃的请求读起来与一个闭包为空的对象完全一样。
**每种结果都彼此区分。**能够解析的 Release 以列表作答。指向不存在文件的 Release 路径会被拒绝,并说明该文件不存在。文件存在但其闭包无法解析的 Release 会被拒绝,并给出无法解析的内容及该引用的来源,随后列出目录加载时拒绝的所有文件——因为被拒绝的文件通常就是该 Release 所触及的实体缺失的原因。如果 Release 旁边的插件信任记录存在但无法读取,请求会被拒绝,并给出无法读取的内容,因为跳过该记录的列表会在根本无法检查的情况下报告没有被撤回的插件。lockfile 已不再与其解析结果匹配的 Release 会被拒绝,并给出构建所打印的漂移停止信息,如错误行为所述,因为列出的版本将是该 Release 的任何构建都不会使用的版本。这些情况的答案都绝不会是空列表:那样会把拼错的路径或损坏的工作区报告成一个不依赖任何东西的 Release。
三个详细级别的作用方式与其他所有类型相同。--list 只打印引用,每行一个,便于管道处理。默认级别还会加上解析后的标识、每个引用解析到的版本、所引用的共享文档、目标未实现其被映射类型的任何 Manifest 映射,以及针对该 Release 所依赖内容记录的任何弃用或撤回通知——即锁文件中针对已固定引用记录的通知,以及其旁边的插件信任记录中针对以返回接受或拒绝裁决的角色挂载的插件记录的通知——措辞与 aggrega build 为同一标记打印的相同。--detail 在引用位置记录了类型时,还会加上每个引用的类型——文档中有些位置说明了其指向的类型,有些则没有,因此只在已知时报告,而不会根据名称的形式猜测。
$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0 Aggregate: fullstack-app Manifest: prod-manifest Environment: production
Entities (11): ./aggregate.yaml ./manifest.yaml core/compute/api-server (1.0.0) core/compute/web-ui (1.0.0) core/datastore/postgres (1.0.0) core/k8s-dns-resolver (1.0.0) db-module (1.0.0) helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0) helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0) helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0) k8s-dns-patcher:1.0.0 (1.0.0)如果工作区已记录某个 Release 解析到哪些版本,该记录会作为解析的起点,因此报告的版本就是构建此部署所用的版本,而不是目录今天恰好持有的版本。没有此类记录的工作区则基于目录的当前状态进行解析。
附加项的连接、槽位与敏感性子句
Release 视图中的每个 Feature 附加项都带有一个子句,列出编译器针对该附加项本身记录的事实:它填充哪个附加槽位、是否处理声明为敏感的内容、实现它的 FeatureRecipe;对于写在组件某个连接上的附加项,还包括它所在的连接。该子句位于附加项名称与其来源括号之间,在下文两种来源形式中读法完全相同。
写在连接上的附加项列在 Uses: 中该连接所在行的下方,而不是 Features: 下,因此 Features: 只包含组件自身的附加项。其上方的一行通过别名及其到达的组件指明该连接,附加项自身的子句说明其余信息:
[socket: <socket>]—— 连接所经由的 socket,连接所在行并未指明它。它位于子句开头,因为它改变了其余部分的读法:随后的槽位部分指的是连接的 socket 声明的槽位,而不是组件为自身附加项声明的槽位。[connection: <alias> through socket <socket>]—— 对于其连接在Uses:块中没有对应行的附加项,表达同一事实;这种附加项列在Features:下,并在此处指明其连接。无论哪种方式,每个附加项的连接只指明一次,不会重复。[slot: <name>]—— 该附加项填充名为<name>的槽位。以槽位自身的名称附加一个 Feature 即填充该槽位,因此<name>是附加项书写时所用的名称,并与已声明的槽位进行匹配:对宿主 Component 自身的附加项,匹配其featuresSchema;对写在连接上的附加项,匹配该连接的 socket 声明的featuresSchema。[free]—— 该附加项未填充任何已声明的槽位:解析后的 Component 没有声明该名称的featuresSchema槽位。这是一项发现,而不是诊断。自由形式的附加项会被接受;想要禁止它的运维人员应将其表达为治理策略,而不是依赖工具拒绝它。[sensitive]—— 该附加项处理作者声明为敏感的内容,原因是所附加的 Feature 声明了敏感叶子,或其填充的槽位声明了sensitive: true,或两者兼有。[realization: <name>:<version>]—— Release 的 Manifest 为该附加项绑定的 FeatureRecipe:若 Manifest 映射了附加项自身的名称,则按该名称绑定(对于写在连接上的附加项,名称为别名与槽位以点号连接),否则按其 Feature 类型绑定。它是对同一组文档进行构建时渲染该附加项所用的实现,也是编译图在该附加项上以realization携带的同一个值(参见--ir-graph),因此该视图与编译图不可能指明不同的实现。它位于子句末尾。
多个事实同时适用时,它们共享一个子句。core/storage/s3-object-store 声明了一个标记为 sensitive: true 的 secret_access_key 槽位,因此以该名称附加的凭据会同时报告这两项事实;而以 Component 未声明槽位的名称附加的 Feature,既不报告槽位,也不报告敏感性。若 Manifest 将每个 Feature 类型映射到一个 FeatureRecipe,每一行还会指明其实现:
Features: - secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit] - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]某个组件的 models socket 声明了标记为 sensitive: true 的 credential 槽位,该组件以别名 gpt 连接了一个填充该槽位的连接,于是该附加项列在该连接下方;组件自身的凭据则仍列在 Features: 下:
Uses: gpt → model - gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit] Features: - db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]写在连接上的附加项从不报告 [free]:socket 只接受其声明的槽位,携带任何其他名称的连接会在构建加载时被拒绝。
当所有事实都不适用时,整个子句会被省略;各部分也会各自独立地省略:
- 没有 socket 或连接部分,表示该附加项写在组件自身的块中,或是从更宽的作用域或通过注解驱动的展开到达该组件。
- 没有槽位部分,表示宿主 Component 声明的槽位集合无法解析,例如其类型不匹配任何目录实体。这有意区别于
[free]:[free]回答的是“未声明该名称的槽位”,而缺少该部分表示这个问题根本无法回答。 - 没有
sensitive,记录的是没有任何声明标记该附加项。这比“该附加项不携带任何机密”的判定范围更窄;该维度报告的是声明,不会根据字段名称或其值进行任何推断。 - 没有实现部分,表示 Manifest 未将该附加项绑定到目录中存在的任何 FeatureRecipe。
声明名称恰好为 free 的槽位同样渲染为 [free],与自由形式的附加项无法区分——槽位命名空间中并未保留该词。
IR 来源括号语法
Release 视图中的每个 Feature 挂载都带有一个来源括号。括号可以采用紧凑形式(当挂载的来源在所有叶子上一致时,每个 Feature 一个括号),也可以采用逐叶子形式(当挂载的叶子来自不同来源时,每个叶子一个括号)。共有三种括号内容;它们在两种形式中的含义完全相同。
三种括号内容
-
[explicit]— 该 Feature 挂载由作者声明。Aggregate 或 Release 在受影响的节点上显式指定了该 Feature。显式挂载是优先级最高的来源;在同一叶子上,它总是胜过由注解驱动的贡献。 -
[annotation: <key> from <source>]— 该 Feature 挂载由注解驱动。编译器之所以合成它,是因为<source>上的某个注解匹配了声明此 Feature 的 Manifest 绑定。<key>是触发该绑定的注解键(例如business.aggrega.ai/team);<source>是携带该注解的实体(aggregate、release、component或manifest)。合成的挂载在结构上与显式挂载完全相同——下游渲染对两者一视同仁——但来源括号会区分它们,使调试始终可判定。 -
[explicit; overrides annotation: <key> from <source>]— 一种逐叶子形式,当某个叶子上的显式作者声明压制了本会设置同一叶子的注解贡献时出现。跨侧组合会产生这种情况:Aggregate 注解可能提供某个 Feature 的values:支柱,Release 注解提供其infra:支柱,而同一 Feature 上的显式 Release 声明覆盖了其中一个 infra 叶子。该叶子的括号同时记录显式作者和被压制的注解;被压制的注解不会影响渲染输出,但它的存在会显示在 inspect 视图中,以便操作者看到哪个注解在何处被覆盖。
紧凑形式与逐叶子形式
编译器通过遍历挂载的逐叶子来源并检查一致性,在紧凑渲染与逐叶子渲染之间做出选择。当每个已填充的叶子(跨 Feature 的 values: 和 infra: 支柱)具有相同的来源类型(显式或注解)、注解驱动时相同的注解键、相同的来源实体,且没有叶子带有“overrides annotation”标记时,该挂载的来源即为一致。来源一致时,编译器为每个挂载输出一个括号:
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]当来源不一致时——典型情况是跨侧组合,即在同一 Feature 上由 Aggregate 注解提供 values:、由 Release 注解提供 infra:——编译器为每个已填充的叶子输出一个括号:
- core/pii-redaction values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate] values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate] infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]遍历顺序是先 values 支柱(按作者顺序),再 infra 支柱(同样的规则)。支柱前缀(values. / infra.)和支柱内的点分路径准确指出每个括号所标注的叶子。
声明为敏感的值
如果某个叶子的 schema 声明了 sensitive: true,则会打印固定文本 <redacted> 来代替其值。键、支柱前缀和来源括号都会保留——只替换值——因此该布局仍能说明实体带有哪些叶子以及每个叶子的来源。受影响的可读输出有两处:Aggregate 的逐节点 Values: 块,以及已解析 Release 的逐叶子附加块——包括写在连接上、打印在该连接行下方的附加,它隐去的叶子与组件自身持有同一 Feature 时隐去的叶子完全相同。在 --ir-graph 下,Release 的编译图以机器可读输出中描述的结构化形式隐去相同的叶子。
Components: app (type: core/app) Values: appName: demo dbPassword: <redacted> tuning.poolSize: 25 tuning.adminToken: <redacted>只有声明过的叶子才会被隐去,附加级别的 [sensitive] 子句并不是隐去指令:它表示该附加处理机密材料,而不是说明其哪些叶子带有机密材料。凭据 Feature 发布的定位符——资源名称和数据键——是公开的,在标准库目录中特意未作声明,因此它们会以明文打印在不以明文打印的材料旁边:
- credentials (feature.test/db-credential) values.secretName: db-creds [explicit] values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]不会根据字段名称进行推断:名为 password 但没有声明的字段会打印其值,而名为 key 且已声明的字段则不会。脱敏只作用于工具打印的内容;它永远不会影响渲染出的制品,dist/ 的输出与渲染产生的结果完全一致。该关键字以及声明它所能达到效果的完整上限,见 vocabulary/compact-form-authoring.md 中的“Declaring a leaf sensitive”。
显示被隐去的值
--unredacted 会打印声明为敏感的值,而不是将其隐去,并同时作用于所有 inspect 输出——上述可读布局和 Release 的编译图均是如此。之所以提供它,是因为被隐去的值有时正是要排查的对象:当两者都显示为已隐去时,来自错误附加的凭据与来自正确附加的凭据看起来完全一样。
它的作用范围仅限于传入它的命令。aggrega build 和 aggrega validate 也接受它,在这两个命令中它只作用于 --ir-graph 返回的图,不影响其他内容;未请求图时,这两个命令会拒绝该标志。aggrega build --trace-unredacted 是同样的思路,作用于构建的跟踪文件,构建的这两个标志都不会影响对方的输出;dist/ 下渲染出的制品不受其中任何一个标志影响,因为无论传入什么,它都与渲染产生的结果完全一致。
此后,输出所到之处都会以明文带有这些值——终端、管道、文件、屏幕录制、粘贴的缺陷报告。跟踪文件各自以一个标头开头,说明它们是在未脱敏状态下捕获的;与之不同,终端上的输出没有任何此类标记:只有命令行能表明传入了该标志。
何时使用 inspect
- 调试“为什么这个 Feature 会在这里?” —— 由注解驱动的附加在 Aggregate 和 Release 的 YAML 文件中不可见(注解在文件中,但它们合成的 Feature 附加只存在于 IR 中)。inspect 会连同来源信息一起显示它们。
- 验证 schema 继承 ——
aggrega inspect <ComponentName>显示extends:链解析后合并得到的 schema;仅看编写的文件只能看到本地的增量部分。 - 诊断跨侧组合中的意外结果 —— 当 Aggregate 注解和 Release 注解都在同一个 Feature 上提供支柱负载时,在脑中重建解析后的叶子可能令人困惑。逐叶子的括号形式会把解析过程明确展示出来。
- 部署前验证检查 ——
aggrega inspect ./prod-release.yaml会在aggrega build生成产物之前列出每个 Component 上的每个 Feature;运维人员可以在将渲染出的清单提交到 GitOps 之前,确认拓扑与预期一致。
关于底层机制——注解如何级联、侧与支柱的划分如何将注解值路由到 Feature 支柱中,以及显式附加优先的规则如何与注解驱动的贡献相互作用——请参阅 providers/well-known-annotations.md 和 entities/manifest.md 中的“Annotation-Driven Feature Bindings”。
概要
aggrega inspect [identifier] [flags]说明
Render a readable view of any Aggrega entity — a catalog entity by name, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich bases, which Recipe maps to each type, which Features attach to each node,and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../or /, or ending in .yaml or .yml — is read as a file and inspected by its ownkind: header. A registry reference — oci://<host>/<repository>:<tag>, or@<digest> in place of :<tag> — is read from the registry that publishes it.Anything else is looked up by name in the catalog search stack: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor the entity exactly as authored and --resolved for the kind's full depth,also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — every catalog entity it reaches and the version each resolved to,which is what was pulled in to build the Release. An entity can be reachedwithout appearing as a node, and a node does not carry the version its typeresolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--catalog | [] | 目录路径;可重复指定。每个 —catalog <dir> 都会被添加到目录搜索栈的最前面(首个匹配者胜出):该栈为工作区的 catalog_dirs,或者,对于工作区配置在 workspace.releases 下为其单独指定目录的 Release,则为该 Release 的目录;如果工作区根目录下存在名为 catalog 的目录,该栈以它结尾。写为空列表的 catalog_dirs 完全不读取任何本地目录。 |
--closure | false | 报告该 Release 的依赖闭包——它所触及的每个目录实体,以及每个实体解析到的版本——以替代已解析节点视图。适用于 Release,它是唯一会解析闭包的类型;其他任何类型都会拒绝该请求,而不是静默忽略它。 |
--color | auto | 输出着色:auto|always|never。 |
--detail | false | 渲染完整的字段内容。 |
--flat | false | 将树形实体(Aggregate、Release)渲染为平铺列表,每个节点以其完整的点分路径为前缀。对表格类类型无效。 |
--ir-graph | false | 除该命令已生成的所有内容外,还将本次运行计算出的 IR 图以 JSON 格式写入 stdout。作者声明为敏感的值会在其中被隐去;传入 —unredacted 可改为打印它们。适用于 Release,它是唯一会解析为图的类型;其他任何类型都会拒绝该请求,而不是静默忽略它 |
--list | false | 仅渲染标识符。 |
--no-color | false | 禁用输出着色(—color=never 的别名)。 |
--output, -o | text | 输出格式:text|yaml。 |
--plugin | — | 指向原始 <file.wasm> 产物的文件系统路径;在 aggrega plugin sync 将其记录到 Plugin 实体之前,推导并打印它导入的宿主函数。不接受标识符参数。 |
--raw | false | 按编写时的原样渲染实体,不进行解析。 |
--release | — | 按此 Release 文件的条件查找目录名称:通过工作区配置为该 Release 指定的目录路径,并在前面加上 —catalog。适用于名称;文件或注册表引用会按原样检查,并拒绝此标志。相对路径相对于你运行命令的目录解析,而不是相对于工作区根目录。如果该目录不属于任何工作区且未指定根目录,绝对路径会从该 Release 自身所在的文件夹查找工作区 |
--resolved | false | 渲染完全解析后的实体。 |
--show-implements | false | 对于 Recipe 或 FeatureRecipe,根据目录解析 spec.implements,并渲染所绑定的 Component 或 Feature。 |
--unredacted | false | 打印作者声明为敏感的值,而不是将其隐去。此后输出所到达的任何地方——终端、管道、文件、屏幕录像——都会以明文携带这些值。 |