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

Manifest

Manifest 实体的概念角色(领域 4——将抽象接口绑定到具体 Recipes 的映射表)见 architecture/04-entity-taxonomy.md。本页介绍 Manifest 的编写方式:它与 Release 如何并存、扁平 URI 映射的结构、通过 extends 进行组合、URI 简写规则、注解驱动的 Feature 绑定,以及平台保留的 aggrega.ai/ 前缀。

Manifest 与 Release:关注点分离

Manifest 和 Release 承担互不重叠的职责:

  • Manifest 决定由哪个 Recipe 实现每个目录类型,并通过该 Recipe 的 spec.capability 决定渲染它的 provider(例如 Helm、Helm-chart、Compose)。它是映射表:一份按项目提交到 Git 的记录,记载由哪个具体的 Recipe 实现每个抽象接口;构建要求这些 Recipes 符合的版本和摘要则单独固定在每个 Release 的锁文件中。
  • Release 决定目标位置(例如用于生成 GitOps 制品的物理输出文件夹)。它是部署路由器:一份按环境编写的描述,说明编译后的制品落在何处。

Release 的 schema 在任何嵌套层级都没有 provider 字段;provider 分派完全归属于 Manifest。

编译路径。 当用户运行 aggrega build --release release.yaml 时,编译器通过合并这两个来源来解析物理制品:

  1. 读取目标位置。 编译器扫描 Release 的边界,例如边界 ovh-cluster-3 包含组件 user-db(类型:core/postgres:1.0.0)。
  2. 扫描 Manifest。 编译器打开 Release 通过其 manifest: 字段所指向的 Manifest。
  3. 两级查找。 编译器先在 name 级中查找 "user-db"。若未找到,再在 type 级中依次查找 "core/postgres:1.0.0"(带版本)和 "core/postgres"(不带版本)。
  4. 解析 Recipe。 匹配条目的值是一个 Recipe URI;该 URI 所指的 Recipe 在 spec.capability 中声明由哪个 provider 渲染它。
  5. 生成输出。 此时编译器已知道目标文件夹(dist/boundaries/ovh-cluster-3/)、provider(通过 Wasm 进行 Helm 渲染)以及制品(该 Recipe 的源代码)。预先(ahead-of-time)确定的 GitOps 边界在端到端全程得到遵守。

扁平 URI 映射

Manifest 的 mappings: 块是一个扁平映射,从 component 类型 URI 映射到 Recipe URI(以及从 feature 类型 URI 映射到 FeatureRecipe URI)。在 Manifest 层面,该映射与 capability 无关;capability 的确定来自每个已解析 Recipe 在渲染时的 spec.capability 字段,而不是来自 Manifest 的结构形态。该块在两个顶层键下组织映射:

  • components.type 将 component 类型 URI 映射到 Recipe URI。所声明类型的每个 component 实例都解析到指定的 Recipe。该映射对每个 component 类型是一对一的。当没有键指名某实例的确切类型、且没有为同一基础部分编写其他键时,一个未指名该确切类型的键仍会通过类型的基础部分到达该实例——因此一个不带版本编写的键(core/postgres),或指名另一版本的键(core/postgres:1.0.0),都可以到达 core/postgres:2.0.0 的实例——但它所指名的 Recipe 必须实现每个此类实例自身的版本:以这种方式到达、并映射到声明了 implements: core/postgres:1.0.0 的 Recipe 的 core/postgres:2.0.0 实例会使构建停止。请用指名其版本的键(core/postgres:2.0.0)将此类实例映射到实现它的 Recipe。
  • features.type 将 feature 类型 URI 映射到 FeatureRecipe URI。所声明类型的每个 Feature 附件都解析到指定的 FeatureRecipe。凭据 Features(带有标签 feature.aggrega.ai/kind: secret)与运维 Features 位于同一个 features.type 映射中——即统一的 Feature 实体模型。

每个块还在 type 之外接受一个 name 层级,将特定的实例名称映射到 Recipe(或 FeatureRecipe)URI。name 层级优先于 type 层级:在 components.name 中指名的实例解析到该 Recipe,而同一类型的其他所有实例通过 components.type 解析。这表达了按实例的覆盖——同一 component 类型的两个实例可以通过两个不同的 Recipes 部署(例如,大多数数据库实例使用批量映射的 Recipe,而某一个实例固定到另一种物理实现),无需派生该 component 类型,也无需复制 Manifest。该覆盖统一生效:被指名的实例既通过覆盖 Recipe 渲染,也从覆盖 Recipe 固定其源代码。features.name 是对应于 Feature 附件的对称层级,以附件自身的名称为键——即它在某个 component 的 features: 中被写入时所用的键——而绝不是以它所附加到的 component 的名称为键。按实例 recipe 覆盖示例完整演示了一个最小的双实例场景。

连接所携带的附件以它在消费方 component 上的名称为键:<alias>.<slot>,即连接所写在的别名、一个点,以及该附件填充的槽位(参见 Aggregate 的连接条目)。因此,某个连接的凭据可以以不同于其类型的其他所有附件的方式实现:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

该条目与其他任何 name 层级条目一样被固定和校验,如下一段所述。附件所指名的 Feature 也会被固定和校验,方式与直接写在 component 上的附件的 Feature 完全相同,记录在其作者所写的连接条目下——参见 The lockfile。

name 键必须指名构建中存在的内容。 该层级按确切名称匹配,因此一个并非构建中 component 实例的 components.name 键,或一个并非构建中附件的 features.name 键——最常见的情况是在本应写附件自身名称的位置写了该附件所在 component 的名称——将不会被任何东西查阅,而它原本针对的实例会悄然通过 type 层级解析。对于这样的键,构建会在任何渲染之前停止,并指出该 Manifest、该键、构建中确实存在的同类名称,以及你可能想写的名称——参见 A Manifest name mapping names nothing in the build(Manifest 映射没有指名构建中的任何内容)。

按名称绑定的实现与按类型绑定的实现一样被固定和校验。 aggrega pull 获取任一层级绑定的每个 Recipe 和 FeatureRecipe——来自 catalog 目录、缓存或 registry——并将每一个连同其解析后的版本和内容摘要记录到 Release 的 lockfile 中,位于绑定它的映射条目下:name 层级条目为 manifest.spec.mappings.components.name.<instance>,与 type 层级条目的 manifest.spec.mappings.components.type.<type> 并列。aggrega build 要求其中每一个都符合其固定版本。如果 lockfile 中没有 Manifest 所绑定的某个实现的记录行,构建会以过期为由停止,并指出该实现及绑定它的条目;如果某个实现的内容自 pull 以来发生了变化,构建也会以同样方式停止,并给出两个摘要。在这两种情况下,aggrega pull --release <release> 都会按实现的当前状态记录它。与 type 条目一样,无论 Release 是否声明了该名称的实例,name 条目都会被固定,因此如果 name 条目指名的 Recipe 不存在于任何 catalog 或 registry 中,pull 会停止;指名构建中不存在的实例的 name 条目同样会被固定,并如上一段所述使构建停止。

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

渲染时确定 capability。 Manifest 条目将一个 component 类型绑定到一个 Recipe URI。Recipe URI 最多包含两个段——一个可选的前导 capability,然后是 recipe 名称——外加一个可选的 :version;解析器只在第一个 / 处拆分,因此带有第三个段的引用不指向任何 recipe,并会使解析停止。在渲染时,解析器通过针对 lockfile 和 catalog 的直接 URI 查找加载 Recipe,每个 Recipe 的 spec.capability 字段决定按 (path, capability) 的分派分组。无论更广泛的 catalog 支持多少个 providers,Manifest 的结构形态都保持扁平。

直接 URI 查找

Manifest 的映射值是一个 Recipe URI。编译器直接针对 lockfile 和 catalog 解析该 URI,返回匹配的 Recipe。它不会迭代 spec.implements 声明来寻找“实现”某个 component 类型的 Recipe。每个 Manifest 条目都将开发者编写的 component 类型绑定到一个特定的 Recipe URI;这一选择在 Manifest 内容中是明确且无歧义的。

spec.implements 是对映射表的一致性检查。 已解析 Recipe 的 spec.implements 值必须(MUST)与该映射条目的 Manifest component 类型键匹配——或与该键所 extends 的某个基类型匹配(可在继承链的任意深度),因为针对基类型编写的 Recipe 实现了所有扩展它的类型。两者都不匹配的值会产生 OPS_ERROR,并给出清晰的诊断,指出该 Manifest 条目、已解析的 Recipe 以及冲突的 spec.implements 值。该检查对每个 Manifest 映射条目执行一次,作用于组合后的 Manifest,且在解析任何 Recipe 之前进行——它是静态的、确定性的,除了被映射类型自身的 extends 链之外不遍历任何内容。若某个 components.type 键以其未指明的版本到达某个 component 实例,则会针对该实例以同样的方式再判定一次,此时由该实例自身的类型(取构建编译它时所用的版本)代替该键的位置,如 扁平 URI 映射 所述。关于基类型的 Recipe 能为特化类型省去什么、不能省去什么,参见 ../vocabulary/inheritance-and-interface.md。

每个读取 Release 依赖的命令都会运行该检查,并各自决定检查结果的含义:aggrega build 和 aggrega pull 会停止,因为两者产生的都是你接下来要使用的东西;而 aggrega validate 和 aggrega lint 会将其与其他检查结果一起报告,并以非零状态退出;编辑器则将其作为众多诊断之一发布。对于针对实例的判定,aggrega lint 是例外:它判定的是映射条目,而不是这些条目所到达的实例,因此不会报告该结果,而 aggrega build、aggrega pull 和 aggrega validate --release 会报告。关于该诊断及其修复方法,参见 ../errors/fatal-halts.md。

一致性检查是唯一读取 extends 链的映射环节。Recipe 的选择仍然严格基于映射键:扩展了某个已映射基类型的 component 类型仍需要在此拥有自己的条目,不会通过继承获得条目。

spec.implements 还会提示候选项。 如果某个实例的类型没有 Manifest 映射,构建会以 OPS_ERROR 停止,并列出其 spec.implements 能够实现该类型的 recipes 作为固定候选项;编辑器在补全映射值时也会将这些匹配的 recipes 排在最前。这两个环节都针对所请求的类型本身读取 spec.implements,因此实现该类型某个基类型的 recipe 不会作为候选项提供,尽管该映射会被判定为一致。因此,spec.implements 声明的是 recipe 能够实现什么,并为人的选择提供参考——在一致性检查、无映射诊断和补全中——但它从不决定构建。Manifest 映射是用户明确的部署选择,固定在 lockfile 中以保证可复现;catalog 从不代替用户选择部署。

URI 版本段的三种形式

Manifest 中的 Recipe URI 可以用以下三种形式之一携带版本:

  • 精确 — helm/postgres:1.2.0。lockfile 必须锁定的正是这个版本;首次解析 lockfile 时,解析器锁定该版本;如果解析时目录或注册表中不包含该版本,工作区加载将报错中止。
  • 范围 — helm/postgres:^1.2.0。采用标准 MVS 规则的 Semver 范围;首次解析 lockfile 时,解析器锁定满足该范围的最高可用版本。
  • 无版本 — helm/postgres。不带 :version 后缀;首次解析 lockfile 时,解析器锁定最新的可用版本。

后续构建使用 lockfile 中锁定的版本,与用户书写的形式无关。重新解析到更新的版本需要用户显式操作——aggrega pull --upgrade --release <release> <uri> 在保留其他所有锁定的同时重新解析单个依赖,aggrega pull --upgrade --release <release> 则重新解析全部依赖——lockfile 是构建的事实来源;用户书写的形式是用户在编写时表达版本约束的方式。

限定 capability 的引用

目录中 Recipe 的标识按 capability 划分作用域:两个 recipe 可以共享同一个 metadata.name 和版本,同时声明不同的 spec.capability 值。注册表标识为 recipe/{capability}/{name}:{version},由 recipe 的 kind、其 spec.capability(不含它可能携带的任何版本固定)和名称派生;按照约定,标准库目录树在 recipe/{capability}/{name}/ 处镜像这一坐标。Manifest 映射值可以用以下任一精度命名 recipe:

  • 裸名 — mariadb:1.0.0。当目录中恰好只有一个 recipe 使用该名称时解析成功;这是实践中最常用的形式。
  • 限定 capability — compose/mariadb:1.0.0。第一个 / 之前的段命名 recipe 的 spec.capability,且不带其版本固定——写入引用中的版本固定会被拒绝(E0095)。当多个 recipe 使用相同名称时必须使用此形式:匹配两个 recipe 的裸名引用存在歧义,会在解析时显式中止,而不是静默选取其中一个。

Recipe URI 没有更多位置。解析器只在第一个 / 处拆分,因此 compose/mariadb 命名 capability compose 和 recipe mariadb,而三段式引用在任一精度下都匹配不到 recipe。

上述版本段形式适用于这两种形态。

映射中的注册表发布实体

从注册表而非本地目录使用的实体,其引用方式与本地实体使用的标识完全相同:引用不携带注册表主机,也不携带实体 kind 段。解析器按照下文的 Context-Aware Shorthand URIs(上下文感知的简写 URI) 规则补全两者——主机取自工作区配置的默认注册表,kind 段取自引用在 schema 中所处的位置。当本地 catalog 目录和缓存都不持有副本时,aggrega pull(或以 --auto-pull 运行的构建)会从派生出的位置获取该实体并缓存,再将解析出的版本和内容摘要锁定到 lockfile 中;后续构建无需网络访问即可使用缓存。

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

由于主机和实体 kind 段是派生而非 编写的,将其中任一写入引用都无法定位到 已发布的实体——这会产生一个没有任何目录条目使用的标识。 Component 或 Feature 引用就是其原样的 metadata.name 加上 可选的 :version,无论该实体是从本地目录、 缓存还是注册表解析。使用私有 注册表的工作区应在自己的配置中指定该主机,而不是在每个 引用中指定。

完整性检查

所有映射解析完成后,编译器会验证开发者 Aggregate 中的每个 component 和 attachment 实例(凭据 Feature 与其他 attachment 一样,也是 attachment)都有已解析的 Recipe 或 FeatureRecipe。未映射的实体会导致致命中止,并给出明确的诊断,列出每个缺失的实体,并建议添加哪个 components.type 或 features.type 键来补全缺口。

使用 YAML 锚点保持 manifest 简洁(DRY)

为避免大型映射集中 YAML 过度膨胀,Manifest 支持一个可选的 defs: 块,用于标准 YAML 锚点(& 和 *):

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Feature 协商

capability 握手使用相同的扁平 URI 映射:

  1. 开发者在 Aggregate 中将 core/data-masking 附加到某个 component,放在该 component 的 features: 映射中一个独立的名称下。
  2. 编译器在 Manifest 的 features.type 映射中查找 core/data-masking。
  3. 如果查找解析到一个 FeatureRecipe URI(例如 helm/data-masking-litellm:1.0.0),则该 capability 存在,FeatureRecipe 的流水线按定义的顺序执行。
  4. 如果 features.type 中没有匹配的条目,编译器会中止构建并列出未映射的 Feature。

Manifest 还接受一个 features.annotations 块——这是一个并行的编写界面,允许 Release 或 Aggregate 子系统按注解键附加 Features,而不是按每个 component 逐一声明。绑定的形态、决定哪个编写界面使用哪些路由路径的 side 与 pillar 划分、显式附加优先的原则,以及 schema 默认值规则,详见下文专门的 Annotation-Driven Feature Bindings(注解驱动的 Feature 绑定) 一节。

通过 extends 组合

一个 Manifest 可以声明单个 extends: 引用,指向一个基础 Manifest,并继承其 mappings。**该引用不是 URI,也从不通过目录解析:**Manifest 属于部署侧,与 Release 一同编写而不发布,因此该值要么是指向 Manifest 文件的相对路径——./base-manifest.yaml——要么是位于该 Release 自身目录中的某个 Manifest 的裸 metadata.name。相对路径必须指向工作区内的 Manifest;若 Release 是在工作区之外指定的(在命令行上,或由工作区配置指定),则必须指向存放该 Release 的目录内;对于你在命令行上单独指定且位于工作区之外的 Manifest,则必须指向存放该 Manifest 的目录内。向上越出该目录、或经由符号链接越出该目录的路径,会在读取其指向的文件之前被拒绝(参见 errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside(对另一文件的引用越出了它必须停留的目录)”)。键冲突时,子级映射覆盖基础映射,从而支持环境叠加模式(staging/prod 一致,并按环境精确修改差异)以及本地开发模式,而无需完整复制编写。

合并语义。当本地 Manifest 扩展基础 Manifest 时,编译器按层级执行浅层键替换——type 和 name 字典各自独立合并,而非深度合并——这保证了 O(1) 的字典查找,并使继承行为可预测。在每个层级内,子级键覆盖父级键。

本地开发桥接模式。extends 的一种常见用法是在本地原型开发时替换凭据 FeatureRecipe,而无需改动 Aggregate。在生产环境中,基础 Manifest 在 features.type 层级下将凭据 Feature core/aws-secrets-manager 映射到一个生产用 FeatureRecipe。对于本地原型开发,平台团队提供一个 local-manifest,它扩展基础 Manifest,并精确覆盖该凭据 Feature 的映射,改用 host-env-injector——这是一个本地 FeatureRecipe,它将凭据以变量引用(如 ${SECRET_NAME})的形式写入 Compose 文件,Docker Compose 在栈启动时从 shell 环境或 .env 文件中替换该变量。开发者获得标准的本地工作流,而 Aggregate 在生产环境中仍与具体能力无关。

上下文感知的简写 URI

Aggrega 编译器在解析 Manifests 中的 OCI URI 时使用上下文感知推断。如果工程师省略了完全限定域名(FQDN)和架构实体类型,编译器会自动回退到默认注册表(在 .aggrega-config.yaml 中配置),并根据该字符串在 schema 中所处的位置推断实体类型。

推断规则:

  1. **域名默认值:**任何缺少域名的 URI(例如 python-worker-helm:1.0)都会加上所配置的 default_registry 作为前缀(默认值:hub.aggrega.ai/)。
  2. **上下文实体扩展:**编译器根据严格的 schema 字典追加正确的实体路径:
    • Aggregate.spec.components[].type 下的字符串扩展为 /component/。
    • Aggregate.spec.aggregates[].type 下的字符串扩展为 /aggregate/。
    • Manifest.spec.mappings.components.type 或 Manifest.spec.mappings.components.name 下的字符串扩展为 /recipe/。
    • Manifest.spec.mappings.features.type 或 Manifest.spec.mappings.features.name 下的字符串扩展为 /featurerecipe/。这也包括凭据 Features(带有标签 feature.aggrega.ai/kind: secret)——它们使用相同的 FeatureRecipe 路径。
    • 赋给 pipeline[].plugin 的字符串扩展为 /plugin/。
  3. **三层优先级:**在应用 OCI 推断之前,编译器会按照三层实体解析模型的定义,先搜索工作区的 catalog 目录和制品缓存(工作区与缓存层)。只有当实体到达注册表层时,才会应用 OCI 推断。映射的键或值从不被当作文件路径读取:在本地编写的 Recipe 或 FeatureRecipe 位于某个 catalog 目录中——工作区根目录下的 catalog/,或 workspace.catalog_dirs 列出的某个目录——并通过其引用来命名。

简写的实际用法:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

**没有 ops/ 前缀。**Recipe 名称不带 ops/ 前缀——OCI 分类体系中的 recipe/ 实体类型目录已经标识了该领域,Recipes 以 recipe/{capability}/{name} 的形式发布,不再附加其他前缀。Manifests 通过 {capability}/{name} 引用 Recipes,或在上下文感知推断下使用裸名称。完整的 OCI 分类体系请参见 architecture/13-catalog-and-registry.md §6。

注解驱动的 Feature 绑定

Manifest 的 features.annotations 块声明注解键与 Feature 类型之间的绑定,以及每个绑定传递注解值所经过的路由路径。该绑定是一个编写入口,用于将重复的逐组件 Feature 附加——即某个边界内数十个组件各自携带相同 features: 块的模式——压缩为 Release 边界或 Aggregate 子系统上的单个注解声明。

Schema 结构:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

一个绑定包含一个 feature 字段(指定目标 Feature 类型)和一个 maps 块(按目标支柱对点分路径子键路由进行分组)。feature 字段引用的 Feature 类型也必须出现在同级的 features.type 部分中(FeatureRecipe 的版本绑定位于该部分)。maps 块声明两个按支柱分键的列表——maps.infra 和 maps.values——每个列表包含指向目标 Feature 的 spec.schema.<pillar>.<path> 属性的点分路径字符串。一个绑定必须在这两个列表中至少声明一条路径(JSON Schema 对 maps 强制执行 minProperties: 1)。

同一注解键的 Provider 多态——例如 feature.aggrega.ai/rewrite-host 在 Kubernetes 部署中绑定到 core/k8s-dns-resolver,而在本地 Compose 部署中绑定到 core/compose-bridge——通过在不同 Manifests 中选择不同的 Feature 类型来表达;每个 Manifest 将该注解绑定到一个 Feature,所选 Feature 的 FeatureRecipe 承载特定于 provider 的实现。

侧与支柱的划分。 Aggregate-as-Authoring-Surface 不变式将每个编写侧限制为一个支柱的路由路径。Aggregate 侧注解只通过 maps.values 路径路由;Release 侧注解只通过 maps.infra 路径路由。在两个支柱中都声明路径的绑定支持跨侧组合:Aggregate 侧注解触发 values 支柱子集;针对同一键的 Release 侧注解触发 infra 支柱子集;两者的贡献组合为每个(Component, Feature)对的一个 Feature 附加,两个支柱都被填充。侧与支柱不匹配——例如,Aggregate 侧注解针对只声明了 maps.infra 的绑定——会以明确的诊断中止构建,该诊断指出注解键、路由的支柱、编写侧和源位置,并归入编写该注解值的文档所属的域。

路径目标校验。 在加载目录时,编译器会校验 maps.infra 和 maps.values 下声明的每条点分路径都对应目标 Feature 的 spec.schema.<pillar> 实际声明的属性。路由到 Feature schema 未列出的路径的绑定会以明确的 OPS_ERROR 中止目录加载,该错误指出绑定、目标 Feature 以及其路由经过的支柱和路径。无法通过简单属性遍历处理的 schema 结构($ref、patternProperties、oneOf / anyOf / allOf 组合)会在该分支终止静态检查,由下游 schema 校验捕获任何不匹配。

注解值的形态。 绑定接受三种形态的注解值。标量——单个 YAML 值(字符串、数字、布尔值)。标量与在两个支柱中总共恰好声明一条路径的绑定配对时,值路由到该单一路径;标量与声明多于一条路径的绑定配对属于歧义路由,会以明确的诊断中止构建,并归入编写该注解值的文档所属的域。结构化——一个 YAML 映射,其每个顶层子键都匹配 maps.infra 或 maps.values 下的一个点分路径条目;每个子键独立路由到其声明的支柱,侧与支柱的划分按子键适用。显式 YAML null——在级联作用域退出继承的绑定(结构化值内的逐子键 null 可退出单个子键,同级子键保留)。关于结构化值的规范编写说明——按子键的级联合并、跨侧组合、按子键的类型校验、未声明 type 的 schema 字段的宽松默认规则——参见 providers/well-known-annotations.md §“Structured annotation values”。

键冲突时显式附加优先。 当一个 Release 组件或 Aggregate 组件同时带有显式 features: 条目和展开为同一 Feature 键的注解时,保留显式条目,该组件上该键的注解展开不执行任何操作。合成附加从不覆盖作者声明的 Feature 实例。因此,作者可以对大部分组件使用注解展开,并通过编写具有相同键的显式 features: 条目来精确覆盖个别组件——显式条目承载逐组件的定制,注解则原样级联到其他所有组件。

跨侧组合中按叶节点的显式优先。 当显式附加和注解贡献填充同一个 Feature 实例但写入不同叶节点时,两者的贡献都保留,最终的 Feature 带有两个叶节点,并以逐叶节点的来源记录各叶节点的出处。当显式附加和注解贡献针对同一支柱内的同一叶节点时,显式贡献优先,IR 将被抑制的注解来源作为该叶节点上的覆盖标记记录下来。目录加载会在构建时通过一条提示性的 lint 警告呈现此覆盖,该警告指出被抑制的注解键及其来源。

展开时的 schema 默认值。 注解展开生成的合成 Feature 附加只包含注解值通过绑定声明的路径所填充的叶节点。目标 Feature 的 spec.schema 上声明的 schema 默认值不会在展开时合并到合成附加中。默认值的具体化由 FeatureRecipe 渲染层负责,并统一应用于显式附加和合成附加,使两条路径对相同的有效配置产生相同的下游输出。

注解命名空间划分:

前缀所有者用途
aggrega.ai/仅限 Aggrega 平台由 provider 直接读取的平台原生注解(例如 aggrega.ai/namespace)。
feature.aggrega.ai/官方标准库在 Manifest 中绑定的 Feature 注解快捷方式。
{any-other-domain}/企业 / 社区自定义 Feature 注解快捷方式。

aggrega.ai/ 前缀保留

Manifest 的 features.annotations 绑定不能使用裸 aggrega.ai/ 前缀——该前缀保留给编译器生成的平台原生注解(OTel/来源标签等)。限定作用域的子前缀(component.aggrega.ai/*、compliance.aggrega.ai/*、企业的 acme.aggrega.ai/*)仍可供用户编写使用。平台保留的注解集参见 providers/well-known-annotations。