Aggrega 开发者意图(Aggregate)schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
递归的、参数化的 AI 架构。既作为一次构建的根,也作为可复用模块。
有关编写 Aggregate 实体的文字指导,请参阅 Aggregate 编写参考;本页记录该参考所描述的结构化 schema。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | 是 | 常量:"aggrega.ai/v1beta1" |
kind | const “Aggregate” | 是 | 常量:"Aggregate" |
metadata | object | 是 | |
defs | string[] | 否 | 可选块,用于标准 YAML 锚点(& 和 *),使 Aggregate 保持 DRY,同时为编译器维持扁平的 O(1) 字典。与 Manifest 上的对应块一致。 |
spec | object | 是 | 开发者意图层:全局参数契约、嵌套的 aggregate 导入、导出组件的公共 API、子系统分组,以及构成该模块的组件实例。 |
不允许其他属性。
aggregate.metadata
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 长度至少为 1 个字符。 |
version | string | 是 | aggregate 模块的严格语义化版本。模式:^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$。 |
description | string | 否 | |
maintainers | object[] | 否 | 拥有此实体的维护者列表。 |
license | string | 否 | 此实体所描述软件的许可证 SPDX 标识符,例如 MIT 或 AGPL-3.0。它记录的是该软件的条款,而不是此文件的条款。 |
repository | string | 否 | 源文件所在 Git 仓库的 URL。 |
home | string | 否 | 此实体的主页、wiki 或文档的 URL。 |
keywords | string[] | 否 | 用于提升 UI 可发现性的描述性关键字列表。 |
labels | map of string | 否 | 模块级鸭子类型标签,用于目录发现、策略评估以及 Studio/IDE 过滤。这些标签描述该 Aggregate 作为可复用模块的身份(例如 aggregate.aggrega.ai/tier: infrastructure、aggregate.aggrega.ai/compliance: pci-dss)。它们不会级联到子组件节点——组件标签仅来自 Domain 2 中的 Component 目录实体。 |
不允许其他属性。
aggregate.metadata.maintainers[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | |
email | string | 否 | |
url | string | 否 |
不允许其他属性。
aggregate.spec
开发者意图层:全局参数契约、嵌套的 aggregate 导入、导出组件的公共 API、子系统分组,以及构成该模块的组件实例。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
parameters | map of object | 否 | 全局环境契约。每个条目都是一个类型化契约对象,使用紧凑形式词汇的子集编写(type、description、default、enum、min/max、minLength/maxLength、pattern、format、validate、validateMessage、required、items、valuesType、properties)。嵌套结构通过类型化形式的 properties: 子字段表达。Release 的填充可以内联(parameters: {…}),也可以从单一来源文件导入(parameters: {$import: |
aggregates | map of object | 否 | 作为导入模块的嵌套 aggregate。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。 |
exportedComponents | map of string | 否 | 公共 API 接口。将对外公开的名称映射到内部组件 ID。导入此模块的父级 Aggregates 通过这些公共名称引用组件。 |
subsystems | map of subsystem | 否 | 将 Aggregate 的组件按名称进行逻辑分组而形成的子系统。与顶层 components 互斥——同时声明两者会被拒绝。作者命名为 default 的子系统是普通的已声明子系统,不同于编译器为仅含 components 的 Aggregate 合成的 default。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。 |
components | map of component_instance | 否 | 构成此 Aggregate 的逻辑原子组件的 map,直接在顶层编写。顶层 components 与 subsystems 互斥——同时声明两者会被拒绝。在此处编写 components(不含 subsystems)时,编译器会在加载时将它们合并到一个合成的 default 子系统中,并且 IR 会将该子系统标记为合成。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。 |
不允许其他属性。
定义
inject_delivery
单个交付机制,以条目数组的形式编写。每个条目包含一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制特定的键),外加 ‘from’(要解析的 provides 键)或 ‘value’(字面量字符串,可包含在 self-inject 解析时求值的 Go 模板表达式)二者之一,且只能有一个。在 uses[].inject 上下文中,‘from’ 针对目标的 provides 解析;在挂接的 features.
类型: object[]
inject_block
与内容无关的注入路由。将本地变量映射到目标的 provides 键(uses[].inject),映射到挂接的 FeatureRecipe 发布的 provides 键(features.
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
env | inject_delivery | 否 | 单个交付机制,以条目数组的形式编写。每个条目包含一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制特定的键),外加 ‘from’(要解析的 provides 键)或 ‘value’(字面量字符串,可包含在 self-inject 解析时求值的 Go 模板表达式)二者之一,且只能有一个。在 uses[].inject 上下文中,‘from’ 针对目标的 provides 解析;在挂接的 features. |
file | inject_delivery | 否 | 单个交付机制,以条目数组的形式编写。每个条目包含一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制特定的键),外加 ‘from’(要解析的 provides 键)或 ‘value’(字面量字符串,可包含在 self-inject 解析时求值的 Go 模板表达式)二者之一,且只能有一个。在 uses[].inject 上下文中,‘from’ 针对目标的 provides 解析;在挂接的 features. |
arg | inject_delivery | 否 | 单个交付机制,以条目数组的形式编写。每个条目包含一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制特定的键),外加 ‘from’(要解析的 provides 键)或 ‘value’(字面量字符串,可包含在 self-inject 解析时求值的 Go 模板表达式)二者之一,且只能有一个。在 uses[].inject 上下文中,‘from’ 针对目标的 provides 解析;在挂接的 features. |
component_uses_block
一个 component 连向其所依赖的 component 的连接,按 socket 作为键。每个 socket 列出其目标,或以别名命名每个连接。以别名命名的连接可以携带开发者为每个连接设置的值,以及填充该 socket 所声明槽位的附件。
键: 一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
值为 string[] or map of object。
不允许使用其他任何键。
feature_uses_block
已附加的 Feature 所建立的连接,以该 Feature 在其 usesSchema 中声明的 socket 作为键。每个 socket 列出其目标,或以别名命名每个连接。Feature 建立的连接自身不携带附件:它所需的凭据填充该 Feature 在自身 featuresSchema 中声明的槽位,并附加在该 Feature 旁边。
键: 一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
值为 string[] or map of object。
不允许使用其他任何键。
connection_attachment
连接所携带的一个附件:填充该连接的 socket 所声明槽位的 Feature,以及开发者为其提供的配置。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
type | string | 是 | 此附件所请求的 Feature 接口的 URI(例如 core/referenced-secret:1.0.0)。 |
description | string | 否 | 可选文档,说明此连接为何携带该附件。 |
values | object | 否 | 开发者为该 Feature 提供的配置,由其 schema 声明进行验证。 |
不允许其他属性。
subsystem
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
description | string | 否 | 可选文档,描述此 subsystem 的用途及其所代表的逻辑分组。 |
annotations | string、object 或 null 的映射 | 否 | 开发者为此 subsystem 编写的注解。值为字符串、结构化对象(子键到值的 map,与继承的结构化值按子键合并)或 null;对从父 subsystem 继承的键显式设置 null,会从此 subsystem 中移除继承的绑定(由注解驱动的 Feature 退出)。此处声明的注解由嵌套的 subsystem 和所包含的 component 继承;按键以更近的层级为准。向下级联到每个派生 IR 节点上的 .context.annotations.aggregate 存储桶。 |
features | map of object | 否 | 附加到此 subsystem 中所有 component 的横切 feature。与 component 级 feature 的 schema 相同(type、values、uses、inject)。在图最终确定时展开到每个 component 中,执行顺序位于 component 级 feature 之后。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。 |
subsystems | map of subsystem | 否 | 键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。 |
components | map of component_instance | 否 | 键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。 |
不允许其他属性。
component_instance
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
type | string | 是 | 所请求的抽象 Component,以引用形式给出:其 metadata.name 加上可选的 :version(例如 core/api-server:1.0.0),绝不是文件路径。通过三层实体解析模型(工作区 catalog 目录 → 缓存 → 注册表)解析:本地编写的 Component 放在工作区根目录下的 catalog/ 中,或放在 workspace.catalog_dirs 下列出的目录中;写成相对文件路径的 type 会作为没有任何目录持有的实体而使构建停止。 |
active | boolean 或 string | 否 | 该组件是否出现在编译后的拓扑中。值为一个布尔值,或一个基于 .parameters 的字符串模板,该模板必须解析为布尔值。解析为 false 时,该组件会从拓扑中裁剪掉,并级联到它的 uses 边及其附件。由参数驱动该值,可让 Release 通过满足该参数来切换组件是否存在。省略时默认为 true。默认值:true |
description | string | 否 | 可选文档,描述此组件实例在应用中的角色。会被带入 IR 图中。 |
annotations | string、object 或 null 的映射 | 否 | 开发者为此 component 编写的注解。值为字符串、结构化对象(子键到值的 map,与继承的结构化值按子键合并)或 null;对从父 subsystem 继承的键显式设置 null,会从此 component 中移除继承的绑定(由注解驱动的 Feature 退出)。Component 级注解按键覆盖继承的 subsystem 级注解;同一 subsystem 中的同级 component 各自独立保留自己的注解映射。 |
values | object | 否 | 传递给 Component 的不透明认知属性,由其 schema 校验。 |
uses | component_uses_block | 否 | 一个 component 连向其所依赖的 component 的连接,按 socket 作为键。每个 socket 列出其目标,或以别名命名每个连接。以别名命名的连接可以携带开发者为每个连接设置的值,以及填充该 socket 所声明槽位的附件。 |
inject | inject_block | 否 | 组件级自注入。将组件自身的值(通过 ‘value:‘)或自身的 provides 键(通过 ‘from:‘)直接注入到交付管道(.context.inject)。仅当 Component 目录实体以相应机制声明了 ‘spec.inject’ 时才允许。与 uses[].inject 中声明的键冲突的 inject 键,会作为跨 inject 来源的重复交付键而使构建停止。 |
features | map of object | 否 | 附加到此组件的 Features,以作者为每个附件指定的实例名为键。这是唯一的附加入口:运维 Feature、凭据 Feature(带有标签 feature.aggrega.ai/kind: secret 的 Feature)和身份 Feature 都在此处附加,使用相同的关键字和相同的结构。它们之间的区别在于附件产生的内容,而非声明方式。实例名与 Component 在 featuresSchema 中声明的槽位相匹配的附件会填充该槽位;其他任何实例名都是自由附件。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。 |
不允许其他属性。