Aggregate
Aggregate 实体的概念角色(领域 1——开发者的声明式拓扑蓝图)见 architecture/04-entity-taxonomy.md。组合模式(子系统、嵌套 aggregate、零端口约定、参数提升)见 architecture/06-data-taxonomy-and-composition.md。本页介绍 Aggregate 目录的编写接口——具体而言,即编写用于目录分发的可复用 Aggregate 模块。
Component 作用域:默认 subsystem
一个 Aggregate 将组件组织为子系统:针对横切关注点(数据层、边缘层)的命名分组,各自带有自己的注解级联。大多数 Aggregates 只有一个分组,因此无需任何繁琐声明。
**单一作用域(默认)。**直接在 spec.components: 下编写组件,并省略 subsystems: 块:
spec: components: api: type: core/server:1.0.0 worker: type: core/worker:1.0.0编译器会将这些组件归入一个合成的 default 子系统。节点标识保持不变:api 仍是 api,绝不会变成 default.api。因此以这种方式编写的 Aggregate 与显式的单子系统形式可以互换,对它的寻址(在 uses: 目标中、在诊断信息中)使用不带前缀的 spec.components.<name> 路径。合成的作用域会如实记录在导出的 IR 中(带有合成子系统标记),但它绝不会出现在作者编写或阅读的路径中。
**多个作用域。**当组件分属不同的横切分组时,在 subsystems: 下声明命名子系统。每个子系统带有自己的组件和注解级联,并且可以进一步嵌套子系统。
互斥。在 Aggregate 根级,spec.components: 与 spec.subsystems: 互斥:只能编写其中之一,不能同时编写。同时声明两者的文档会在加载时因信封错误而终止。(开发者显式命名为 default 的子系统是一个普通的已声明子系统,通过其限定路径 spec.subsystems.default.components.<name> 寻址:合成作用域的路径省略依据的是来源,而不是名称。)
可复用的 Aggregate 模块
Aggregates 既可作为 Release 所构建的根 Aggregate,也可作为可复用模块。父 Aggregate 可以像声明组件一样声明子 Aggregate,并将 parameters 向下传入。为避免紧耦合,子 Aggregates 暴露一个 exportedComponents: 契约,建立稳定的公共接口名称。父级只能通过该接口访问模块的组件:uses: 目标由模块名称、一个点号和该模块的一个已导出别名组成,编译器会将该边连接到该别名所指的内部组件。以其他任何名称深入模块的目标——模块内部组件的名称,或指向其内部嵌套模块的路径——都会中止构建,并指出该模块及其导出的别名;参见 A uses target names a module’s component the module does not export (目标指向了模块未导出的模块组件)。
为何需要显式的 exportedComponents: 列表。 模块的作者决定其哪些组件构成公共接口,哪些仍属于实现细节。由于父级只能指名该列表所发布的内容,模块的内部可以重构——重命名一个组件、将一个组件拆分为两个、用托管服务替换一个 worker——而不会破坏任何父级,只要每个已发布的名称仍指向某个组件。该列表的代价是每个已发布组件一个条目;当某个组件自身的名称正是导入方应使用的名称时,可以用该名称发布它(store: store)。同一规则在组合内部同样适用:一个模块通过其所导入模块的已导出别名来访问该模块。Release 可以将同一模块的两个组件相互连接,因为这种连接不跨越任何模块的接口。
重新导出嵌套模块的接口。 exportedComponents: 条目可以指向嵌套子 aggregate 的导出别名,而不是直接声明的组件——即模块以自己的接口名称(并可选地使用新名称)重新发布其导入模块的一部分。以这种重新导出别名为目标的 uses: 边会沿链传递解析到具体的内部节点,因此模块可以将更深层的模块组合进自己的公共接口,而无需暴露它们的内部布局,使用方也永远不需要知道目标嵌套了多深。稳定接口的约束在每一跳都成立:每个模块只重新导出它选择发布的内容。解析不到任何内部节点的重新导出目标,会像直接悬空的目标一样明确地中止;而闭合回自身的重新导出链会被拒绝,而不是无限追踪下去。
模块的声明会像 Aggregate 的声明一样受到检查。 只有在构建导入某个模块的组合时,才会读取该模块的文档,并从那时起检查其声明,无论嵌套多深。模块组件自身的 inject: 块受其类型的 spec.inject 允许列表约束,也受禁止两次声明同一投递键、禁止读取类型未发布的键的规则约束。在模块自身某个子系统上编写的附加只能指定其 Feature 声明的套接字,Release 针对模块所贡献组件编写的附加也是如此。
模块的子系统附加会作用于其组件。 模块在其自身某个子系统上附加的 Feature 会级联到模块在该子系统下声明的每个组件(包括嵌套子系统中的组件),与 Aggregate 中的子系统附加完全相同——并且只作用于这些组件,绝不会作用于导入方 Aggregate 中同名子系统下的组件。它在组件自身的附加之后立即求值,外层子系统先于内层。对于两者都写入的字段,组件自身的同名附加优先,而它未写入的字段保留子系统的值。它所到达的每个组件都会按该 Feature 的 appliesTo 对其进行检查。关于模块自身声明的发现会指明模块及其文档中的键——例如 .spec.subsystems.<subsystem>.features.<attachment>——因此应在声明所在的模块中进行修改,而不是在导入它的 Aggregate 中。
目录位置
可复用的 Aggregate 模块位于 aggregate/ 类型目录下,路径与其 metadata.name 逐段对应,叶级为版本目录:
aggrega-catalog/└── aggregate/ └── {module-name}/ # the module's metadata.name, segment for segment └── {version}/ # the module's metadata.version └── aggregate.yaml # The module definition模块名称可以带有一个开头的 {publisher} 段,用于命名供应商或作者——标准库为 core,企业为 acme——已发布的标准库模块就是这样命名的:core/agenta 位于 aggregate/core/agenta/1.0.0/aggregate.yaml。单个标记的名称则浅一层,位于 aggregate/{module-name}/{version}/aggregate.yaml。两种形式都是合法的;名称由作者书写,目录与之对应。这种对应是目录的约定,而不是编译器检查的内容——模块是通过其声明的名称找到的,而不是通过其文件所在的位置。
OCI URI:hub.aggrega.ai/aggregate/{module-name}:{version},转为小写——因此名为 core/agenta 的模块发布到 hub.aggrega.ai/aggregate/core/agenta:1.0.0,名为 db-module 的模块发布到 hub.aggrega.ai/aggregate/db-module:1.0.0。
模块模式
子模块(aggregate/child-database-module/1.0.0/aggregate.yaml,发布为 hub.aggrega.ai/aggregate/child-database-module:1.0.0):
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"父 Aggregate:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db模块标签
当 Aggregate 作为可复用模块发布到目录时,可以在其 YAML 信封上携带 metadata.labels——例如 aggregate.aggrega.ai/tier: infrastructure 或 aggregate.aggrega.ai/compliance: pci-dss。这些标签描述模块的身份,并随发布的模块文档一起携带;目前还没有任何命令读取它们。目录搜索不为 Aggregates 建立索引,构建图既不携带模块的标签,也不携带其目录名称,因此治理策略无法按组件所来自的模块来选择组件。
关键区别。 Aggregate 标签描述的是目录中可复用模块的身份。它们不会向下级联到子组件节点。组件标签仅来自 Domain 2 中的 Component 目录实体。如果开发者导入了标有 aggregate.aggrega.ai/tier: infrastructure 的模块,该模块内的各个组件只保留其自身在目录中定义的标签(例如 component.aggrega.ai/type: stateful-server)。Aggregate 标签永远不会被注入到 IR 节点的 labels 字典中。
有关完整的 Composite Aggregates / Module Pattern 讨论(包括 Components 不得含有子组件的规则)以及 subsystems 横切分组机制,请参见 architecture/06-data-taxonomy-and-composition.md §6。有关类型化 parameters 契约的编写方式,请参见 vocabulary/data-pillars。
类型化参数契约
Aggregate 的 spec.parameters: 块为 Release 所填充的参数声明类型化契约。每个参数槽带有声明的 type、可选的 description、可选的 default、可选的取值空间约束,以及(对于对象类型的槽)嵌套结构。编译器在解析期间、参数插值运行之前,依据该契约校验 Release 提供的每个值。
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: web-app version: 1.0.0spec: parameters: region: type: string description: Cloud region the deployment targets enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1] default_locale: type: string description: Default UI locale presented to end users enum: [en-US, en-GB, fr-FR, ja-JP] default: en-US enable_debug: type: boolean description: Toggle verbose request logging default: false feature_flags: type: object description: Per-feature enablement map valuesType: { type: boolean } default: {} allowed_hosts: type: array description: Hostnames the ingress accepts items: { type: string, format: hostname } min: 1 default: ["web-app.example.com"]
components: web: type: core/web-server:1.0.0 values: default_locale: "{{ .parameters.default_locale }}" region: "{{ .parameters.region }}" debug: {{ .parameters.enable_debug }}每个引用上的引号是有意为之的:它决定了提升后的值以何种类型到达。参见 templates/parameters-context.md。
参数槽词汇
类型化的 parameters: 块接受紧凑形式词汇:type、description、default、enum、min、max、pattern、minLength、maxLength、format、validate 和 validateMessage(自定义检查及其报告的消息)、items(用于数组)、properties(用于对象)、valuesType(用于类型化值映射),以及 required: true(逐槽标记)。其中三个关键字以契约而非普通设置作为其值——items、valuesType 以及 properties 下的每个条目——在参数槽上,该嵌套契约采用与外围槽相同的类型化形式书写:valuesType: { type: boolean },而不是 valuesType: boolean。在插值之前,编译器直接依据这些声明检查合并后的参数映射:任何槽都未声明的参数会被拒绝;标记为 required: true 的槽若既未由 Release 填充,也没有 default 提供值,则构建中止;每个提供的值都会依据其槽声明的 type、enum 成员、字符串槽上的 minLength 和 maxLength 边界、pattern 正则表达式及 format,以及 min 和 max 边界——数值槽的值、字符串槽的长度和数组槽的元素个数——进行检查。对象槽和数组槽会递归检查:properties 下的每个条目以及依据 items 的每个元素都以同样方式检查,valuesType 契约约束 properties 未列出的键,任何声明都未列出的嵌套键会被拒绝。完整的关键字词汇(包括 schema: 支柱对这些关键字的不同拼写)参见 vocabulary/compact-form-authoring.md。
以下关键字还会在读取任何 Release 值之前,对声明本身进行检查,因此一个无法约束任何内容的槽即使没有 Release 为其提供值,也会中止构建:
- 长度边界为零或更大。 参数自身声明上的负数
minLength或maxLength会在 Aggregate 加载时被 Aggregate 的 schema 拒绝,并指出该参数和该键。在嵌套契约内——items、properties或valuesType之下——长度边界按书写原样读取,在 Aggregate 加载时不受该下限约束,因此在那里也应写为零或更大:负数minLength不施加任何约束,而负数maxLength会拒绝所有值。 min和max必须有所约束。 在布尔槽或对象槽上,这对边界约束不了任何东西,因此写在那里的min或max会在 Aggregate 加载时被拒绝,并指出该参数和该键。- 模式必须能够编译。 读取参数契约时,每个
pattern都会被编译为正则表达式——无论在槽本身上,还是在任意深度的嵌套契约内——无法编译的模式会被拒绝,并指出该参数、该模式及原因。每次到达该 Aggregate 的构建、拉取和 Release 校验都会读取该契约,无论它是 Release 自身的 Aggregate,还是该 Aggregate 导入的模块。随后的值检查会用同一个已编译的表达式匹配每个提供的值。 - 格式必须是编译器会检查的格式之一。
format指定email、uri、hostname、ipv4、ipv6、uuid、date-time和date之一,拼写与 JSON Schema 相同。任何其他名称——拼写错误如emial,或 JSON Schema 未定义的名称如password——都会在 Aggregate 加载时被拒绝,并指出该参数且列出支持的名称:在槽本身上由 Aggregate 的 schema 拒绝,在任意深度的嵌套契约内则在读取参数契约时拒绝。随后,不符合指定格式的字符串值会被拒绝,并指出该参数、该值和该格式。每个名称检查的内容参见vocabulary/compact-form-authoring.md。
对象类型和数组类型的参数
参数槽接受紧凑形式支持的任何类型,包括嵌套对象和类型化元素的数组:
spec: parameters: database_config: type: object description: Database connection configuration properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full], default: require } pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels: type: array description: Custom Prometheus labels to attach to scraped metrics items: type: object properties: name: { type: string, required: true } value: { type: string, required: true }Release 使用结构化 YAML 填充对象类型的参数;编译器在插值之前依据声明的 schema 校验其结构。引用对象字段的模板使用标准 Go 模板语法:{{ .parameters.database_config.host }}、{{ .parameters.database_config.port }} 等。
参数契约校验
契约本身在被读取时首先接受检查,即上文“参数槽词汇”中的长度界限检查和 pattern 检查。随后,编译器在参数处理期间执行三个子步骤:
- 默认值填充:定义了
default:且没有 Release 提供值的槽会获得其默认值。嵌套对象参数对父槽的省略、显式为空和部分编写三种情况有不同的编写语义:省略父槽会填充子项的默认值;将父槽写为{}会保留显式的空值(不填充子项的默认值);将父槽写为非空映射则只填充 Release 未提供的子项。YAML 示例以及“何时使用每种形式”的决策指南,参见templates/parameters-context.md。 - 契约校验:合并后映射中的每个值,无论由 Release 提供还是由
default:填充,都要依据声明的type/enum/min/max/pattern/ 嵌套结构约束进行校验。校验失败会使构建中止,并给出明确的错误,指出出错的槽、所提供的值以及被违反的约束。缺少必需参数且没有default:时,也会以类似方式中止,并给出槽名。 - 插值:编译器在将 Aggregate 作为 YAML 读取之前,先将其全文作为模板求值,并用解析后的值替换每个
{{ .parameters.<slot> }}引用(通常位于 component / feature / 子 aggregate 的values:字符串中);文本中的其他{{也会被当作模板语法读取,因此若某个值自身带有双花括号(例如某个流程平台导出的定义),需要将每个{{写为{{"{{"}},如自身带有双花括号的文本所述。此轮处理之后,值模板表面使用的是已插值的字面量,其模板上下文中不会收到.parameters。
合并后的参数映射在整个渲染过程中保持存活,以支持 path-template 求值。运维人员在 Release 边界上编写的 directory: 和 subDirectory: 模板,会在渲染时依据一个封闭的允许列表直接读取 .parameters.<slot>;路径输出需要区域 / 环境词汇来实现按环境划分的制品布局,而这种不对称的授权使运维方面的关注点保留在运维表面之内,无需经由 Aggregate 的 values 往返传递。该映射在所有渲染阶段完成之前一直可读,且只能从为其解析的那次编译中访问;使用开发者编写的 values: 的 recipe 看到的是插值后的字符串,而路径模板在整个渲染过程中看到的是实时的 .parameters 数据。路径模板可用性矩阵参见 templates/expansion-matrix.md 第 3 行,路径模板变量允许列表参见 path-template-variables.md。
更完整的参数提升检查清单(Aggregate 声明 → values 引用 → Release 履行 → Recipe 使用)以及跨支柱机制,参见 vocabulary/data-pillars.md §“Parameters”和 §“The parameter-hoisting checklist”。插值期间公开的模板上下文字段以及路径模板的例外情况,参见 templates/parameters-context.md。
uses 边是 Aggregate 声明的一次调用
uses 边是 Aggregate 关于一个组件调用另一个组件的声明。编译器将目标发布的值传入调用方,且不做任何限制:边本身既不放行调用方,也不拒绝其他任何人;没有边而访问到目标地址的工作负载,同样能访问到它。
限制谁可以调用一个组件、以及该组件可以调用什么,由运维人员决定,并在 Release 中按环境设定。当 Release 将标准库目录中的 core/caller-allowlist Feature 附加到一个组件时,构建会写出一条网络策略,仅放行那些 uses 边指向它的组件、该组件自身的 pod,以及该附加项所指定的来源。其出站对应项 core/egress-allowlist 让所附加的组件只能访问其自身 uses 边所指向的组件、其自身的 pod、集群的 DNS,以及 Release 列出的地址范围。这样,Aggregate 未声明为边的调用,凡是集群的网络插件执行网络策略之处,都可能在任一端被集群拒绝。因此,请为你的组件发起的每一次调用都写一条边,包括不注入任何值的调用:缺失的边就是一次可能被受隔离组件拒绝的调用。model-server-caller-allowlist 展示了一个只能通过其前方网关访问的模型服务器。
连接自身的附件:uses 条目上的 features
组件以详细 uses: 形式绘制的连接是一个独立的条目,除 target、inject 和 values 之外,它还可以在 features: 下携带附件。每个附件都以插座声明的槽位为键:消费方 Component 在插座的 featuresSchema 中列出经由该插座连接的每个连接可以填充的槽位(参见拓扑插座)。借此,一个组件可以为它所访问的每个组件持有不同的凭据——例如网关用两个密钥调用两个模型,或智能体向模型出示自己的密钥。
spec: parameters: openai_key_secret: { type: string } components: router: type: core/gateway/litellm # its `models` socket declares a `credential` slot values: { model: gpt } # the alias it publishes as its model uses: models: gpt: target: gpt features: credential: type: core/referenced-secret values: origin: "{{ .parameters.openai_key_secret }}" key: api-key plain: target: plain # this connection carries no attachment gpt: type: core/ai-model/openai values: { model: gpt-4o-mini } plain: type: core/ai-model/ollama values: { model: llama3.1 }连接上的附件携带 type(必填)、可选的 description,以及该 Feature 的 values。它不携带 uses,也不携带 inject:连接上的附件不会嵌套,其内容如何到达消费方由消费方组件的 Recipe 决定,而不是由 inject 块决定。写了其中任一项的文档会在加载时被拒绝,并指出该键。
**仅限插座声明的槽位。**如果附件使用的名称未列在插座的 featuresSchema 中,构建会在加载时中止,并指出该连接、插座、组件以及插座实际声明的槽位——如果该名称与其中某个槽位只差一处编辑,还会给出该槽位作为可能想写的拼写。已填充的槽位随后在每个连接上都要符合该槽位自身的声明:Feature 的标签不满足的 selector 会在此条目处中止,任何连接上留空的 required 槽位会中止并指出该连接。未声明任何槽位的插座不接受其连接上的任何附件,临时插座——即 Aggregate 连接但 Component 未声明的插座——同样如此,因为它根本没有声明槽位。子模块贡献的组件遵循同样的规则,问题会指向子模块自身的文档。参见 A connection carries an attachment under a name its socket declares no slot for(连接以其插座未声明槽位的名称携带附件)。
**Feature 绘制的连接不携带附件。**附加的 Feature 自身的 uses: 块——无论位于组件还是子系统上——写法形状相同,但在文档加载时拒绝 features:。此类连接所需的凭据填充 Feature 在其自身 featuresSchema 中声明的槽位,并附加在该 Feature 旁;参见 Feature 自身的凭据。
附件采用的名称。每个连接附件都成为消费方组件的一个附件,名为 <alias>.<slot>——即连接所使用的别名、一个点和槽位:上例中为 gpt.credential。点是为编译器组合的名称保留的分隔符,Aggregate 中的别名、槽位或附件名称都不能包含它,因此组合出的名称永远不会与组件自身 features: 块上写的名称相同;在组件或边界上写出该名称的 Release 会被拒绝(参见逐边连接配置)。它是 Manifest 的逐实例层用来为该附件设键的名称(参见扁平 URI 映射),是诊断信息和 IR 图报告它时使用的名称,也是该附件的 FeatureRecipe 以 .attachment_name 读取的值(参见从连接附件派生的名称)。
此后它的解析与任何附件相同:Manifest 将其 Feature 类型绑定到一个 FeatureRecipe,其 values 依据该 Feature 的 schema 进行校验——校验失败会在写入这些值的连接条目处报告——其 FeatureRecipe 则依据该附件自身的 values 和 infra 进行渲染。它与组件自身附件有两点不同:
- **它不在消费方 Recipe 的
.features中。**该支柱只携带写在组件自身块上的附件,因此按类型在.features中查找自身附件的 Recipe 永远不会拿到连接的凭据。Recipe 从连接本身读取连接的附件,位置为.context.uses.<alias>.features.<slot>,形状与.features所携带的相同——包括其已解析的provides(参见连接的附件)。 - **它只落在消费方上。**无论到达目标的连接携带什么,目标的渲染输出都相同。
**图中保存的编写块副本。**IR 图按编写原样保留每个组件的 uses: 块,其中连接附件保留其 type 和 description,不保留任何 values。这些值只出现一次,位于消费方所携带的附件上,其中 Feature 声明为敏感的值会被隐去。
Release 可以用 infra 为此处声明的附件设定规模,也可以在其访问的连接上附加自己的附件——参见逐边连接配置。
关闭 component 或模块:active:
component 实例和子 aggregate 模块都接受一个 active: 开关,用于决定该实体是否属于编译后的拓扑。省略它时实体存在;这是默认情况,也是常见情况。
spec: parameters: enable_cache: type: boolean default: false components: api: type: core/server:1.0.0 redis: type: core/redis:1.0.0 active: "{{ .parameters.enable_cache }}" aggregates: reporting: type: my-catalog/reporting-module:1.0.0 active: false可以直接写一个布尔值,或者写一个基于 .parameters 并解析为布尔值的模板。模板形式正是这个开关存在的原因:它让 Release 通过填写参数来决定实体是否存在,因此一个 Aggregate 就能覆盖部署内容不同的多个环境——而 Release 无需声明任何 Aggregate 未声明的内容。
值为 false 的开关会移除什么。 实体在构建图之前被剪除,并且剪除会级联:component 会连同自己的 uses: 边及其附加的 Features 一起移除,模块会移除它贡献的一切——它的 components、这些 components 的边和附加项。被剪除实体带来的任何内容都不会被渲染。剪除不会触及的是来自保留下来的位置对它的引用,这正是下一段的内容。
保留下来的 component 若仍指向被剪除的 component,构建会中止。 如果 api 声明了指向 redis 的 uses: 边,而 redis 被关闭,构建会停止,而不是让这条边消失,否则 api 的注入值会在部署时悄无声息地为空。请决定这两者中哪一个属于当前环境:重新打开目标,用同一个参数控制使用方以便两者一同移除,或者从使用方的 uses: 块中删除这条边。
写出的开关必须解析为布尔值,而空值不是布尔值。 开关在其模板解析之后被严格读取,无法解析为布尔值的字面量会终止构建,而不会回退为任何默认值。值得留意的情况是开关读取了一个没有值的参数:它解析为空,而若把空读作“存在”,就会部署你本想用该参数控制的那个实体。因此,写出 active: 却不跟任何内容,与省略该键并不相同——只有无人写出的开关才默认为存在。请在 spec.parameters 中为该参数提供 default:,让每个环境都有确定的值,或在 Release 中满足该参数。要让实体无条件存在,请删除 active: 键,而不是将其置空。该终止情况在终止条件参考中以“An active: toggle does not resolve to true or false(active: 开关未解析为 true 或 false)”为题说明。
被关闭的 component 仍可在 Release 中被引用。 Release 仍可在 boundary 中引用它,这是有意为之:关闭 component 是一种编写行为,而配置它的 Release 不应被要求在同一次修改中重写。
子系统与组件上的注解
子系统和组件实例都带有 annotations: 字段。开发者在 Aggregate 层面编写的注解驱动 Aggregate 侧的注解级联:子系统注解会传播到每个嵌套子系统和其包含的每个组件,并按键粒度由更近层级覆盖。Manifest 的 mappings.features.annotations 映射声明了绑定,这些绑定在构建时将注解键转换为合成的 Feature 附加项。Aggregate-as-Authoring-Surface 不变式限制这些注解只能通过绑定的 maps.values 路径进行路由;仅声明 maps.infra 路径的绑定从 Release 侧触发,而不是从 Aggregate 侧触发。
值的形式
每个注解键采用以下四种形式之一,用于区分“我不表态”“我声明一个值”(标量或结构化对象)和“我选择退出”:
- 缺省键:该作用域不为此注解声明值。嵌套子系统和所包含的组件会继承祖先作用域中的任何绑定。
- 标量字符串:单个值。Manifest 绑定必须总共恰好声明一个路径;该标量路由到此路径。
- 结构化对象:子键到子值的映射。对象的每个子键通过 Manifest 绑定的
maps路由到所声明支柱上对应的 Feature schema 字段。 - 显式 YAML
null:该作用域从其子树中移除此键的任何继承绑定。同级组件和同级子系统保留其继承;只有选择退出的作用域失去该绑定。
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker components: api: type: core/server:1.0.0 # inherits feature.myco/db-pool: "shared-pool" worker: type: core/server:1.0.0 annotations: feature.myco/db-pool: null # opts out for this component only special: type: core/server:1.0.0 annotations: feature.myco/db-pool: "vip-pool" # closer-level override多字段 Features 的结构化值
具有多个可配置字段的 Feature 适合使用结构化注解值:一个注解键在一次声明中为多个 Feature schema 字段携带值。Aggregate 侧只触发绑定映射支柱为 values 的子键;路由到 infra 的子键应写在 Release 侧注解上。
spec: subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5 components: api: type: core/server:1.0.0 annotations: feature.myco/db-pool: db_name: "api-override" # closer-level override at subkey granularity # read_replicas not listed → inherits 5 from parent analytics: type: core/server:1.0.0 annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-out结构化值按子键深度合并进行级联:更近层级的子键覆盖父级子键;子键上的显式 null 会在该作用域中屏蔽继承的子键,而同级子键保持不变。关于结构化值的完整说明(与 Release 侧 infra 子键的跨侧组合、按子键的类型校验、未声明 type 的 schema 字段所采用的宽松默认规则),参见 providers/well-known-annotations.md §“Structured annotation values”。
按键独立
每个注解键独立地继承、覆盖和选择退出。声明 annotations.feature.myco/db-pool: null 的组件只退出该键;从外层子系统继承的其他键继续传播到该组件。同一子系统中的同级组件各自独立保留自己的注解映射:一个组件的退出不会影响同级组件。
顶层组件注解
顶层组件(直接声明在 spec.components 下而非子系统内)没有继承的级联。其 annotations: 字段直接在组件作用域上声明值;展开时,对于 Manifest 中具有匹配绑定的每个已声明注解,都会合成 Feature 附加项。
关于应用于绑定的 Aggregate 侧级联规则、侧与支柱的划分,以及展示绑定如何将注解转换为合成 Feature 附加项的端到端示例,参见 providers/well-known-annotations.md §“Aggregate-side annotation cascade”。
YAML 锚点模式(defs: 块)
Aggregate schema 接受一个可选的根级 defs: 块:这是一个 YAML 字符串列表,仅用作标准 YAML 锚点(&anchor)和引用(*anchor)的宿主。编译器从不读取该块的内容;它的存在是为了让作者在一处声明锚点定义,并在 Aggregate 的其余部分引用这些锚点,从而在保持重复值 DRY 的同时,不失去编译器所遍历的扁平 O(1) 字典。该机制与 Manifest 实体上对应的 defs: 块相同。
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: anchored-app version: 1.0.0defs: - &default_log_level "info"spec: components: primary: type: core/compute/api-server:1.0.0 values: log_level: *default_log_level secondary: type: core/compute/python:1.0.0 values: log_level: *default_log_level锚点在 YAML 解析时解析,因此在编译器读取 values 块时,*default_log_level 已经是字符串 "info"。按照约定,defs: 块是存放锚点定义的位置;YAML 允许在任何位置声明锚点,但将它们集中放置可以保持 Aggregate 其余部分的可读性。该块是可选的:不需要锚点的 Aggregates 可以完全省略它。