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

Aggrega 开发者意图(Aggregate)schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/aggregate-v1beta1.schema.json

递归的、参数化的 AI 架构。既作为一次构建的根,也作为可复用模块。

有关编写 Aggregate 实体的文字指导,请参阅 Aggregate 编写参考;本页记录该参考所描述的结构化 schema。

顶层类型: object

属性

属性类型必需描述
apiVersionconst “aggrega.ai/v1beta1”是常量:"aggrega.ai/v1beta1"
kindconst “Aggregate”是常量:"Aggregate"
metadataobject是
defsstring[]否可选块,用于标准 YAML 锚点(& 和 *),使 Aggregate 保持 DRY,同时为编译器维持扁平的 O(1) 字典。与 Manifest 上的对应块一致。
specobject是开发者意图层:全局参数契约、嵌套的 aggregate 导入、导出组件的公共 API、子系统分组,以及构成该模块的组件实例。

不允许其他属性。

aggregate.metadata

属性类型必需描述
namestring是长度至少为 1 个字符。
versionstring是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-]+)*))?$。
descriptionstring否
maintainersobject[]否拥有此实体的维护者列表。
licensestring否此实体所描述软件的许可证 SPDX 标识符,例如 MIT 或 AGPL-3.0。它记录的是该软件的条款,而不是此文件的条款。
repositorystring否源文件所在 Git 仓库的 URL。
homestring否此实体的主页、wiki 或文档的 URL。
keywordsstring[]否用于提升 UI 可发现性的描述性关键字列表。
labelsmap of string否模块级鸭子类型标签,用于目录发现、策略评估以及 Studio/IDE 过滤。这些标签描述该 Aggregate 作为可复用模块的身份(例如 aggregate.aggrega.ai/tier: infrastructure、aggregate.aggrega.ai/compliance: pci-dss)。它们不会级联到子组件节点——组件标签仅来自 Domain 2 中的 Component 目录实体。

不允许其他属性。

aggregate.metadata.maintainers[]
属性类型必需描述
namestring是
emailstring否
urlstring否

不允许其他属性。

aggregate.spec

开发者意图层:全局参数契约、嵌套的 aggregate 导入、导出组件的公共 API、子系统分组,以及构成该模块的组件实例。

属性类型必需描述
parametersmap of object否全局环境契约。每个条目都是一个类型化契约对象,使用紧凑形式词汇的子集编写(type、description、default、enum、min/max、minLength/maxLength、pattern、format、validate、validateMessage、required、items、valuesType、properties)。嵌套结构通过类型化形式的 properties: 子字段表达。Release 的填充可以内联(parameters: {…}),也可以从单一来源文件导入(parameters: {$import: });参数契约层会在参数插值之前根据此契约校验合并后的 map。语言参考中的 Aggregate 页面讲解了完整词汇。
aggregatesmap of object否作为导入模块的嵌套 aggregate。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
exportedComponentsmap of string否公共 API 接口。将对外公开的名称映射到内部组件 ID。导入此模块的父级 Aggregates 通过这些公共名称引用组件。
subsystemsmap of subsystem否将 Aggregate 的组件按名称进行逻辑分组而形成的子系统。与顶层 components 互斥——同时声明两者会被拒绝。作者命名为 default 的子系统是普通的已声明子系统,不同于编译器为仅含 components 的 Aggregate 合成的 default。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
componentsmap 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..inject 上下文中,针对该挂接的 FeatureRecipe 发布的 provides 解析;在 component.inject 上下文中,则针对该 component 自身的 provides 解析。在挂接的 features..inject 中,如果 ‘from’ 指定了 FeatureRecipe 未发布的键,构建会中止,除非该 FeatureRecipe 在它针对挂接的渲染上下文求值的模板中(其 valuesMapping、workload、artifacts、omits,或某个 pipeline 步骤的 with 或 when——而非其 injectMapping)自行在 .inject 处读取挂接的条目,此时该键是它自己消费的键,而不是通过 component 的 .context.inject 交付的键。‘value’ 只在 component.inject 中交付:在 uses[].inject 或挂接的 features..inject 中携带它的条目会使构建中止,因为这些块只交付其他实体发布的键。

类型: object[]

inject_block

与内容无关的注入路由。将本地变量映射到目标的 provides 键(uses[].inject),映射到挂接的 FeatureRecipe 发布的 provides 键(features..inject),或映射到字面量字符串 / 模板表达式以及该 component 自身的 provides 键(component.inject)。每种交付机制(env、file、arg 或自定义)都以 {in, from?, value?} 条目数组的形式编写——显式的 ‘from’ 用于 provides 引用,‘value’ 用于字面量。自定义机制可以使用除 all 以外的任何名称:模板会在 .context.inject.all 处读取合并为一个视图的所有机制,因此名为 all 的机制会被该视图遮蔽,使用该名称会使构建中止。

属性类型必需描述
envinject_delivery否单个交付机制,以条目数组的形式编写。每个条目包含一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制特定的键),外加 ‘from’(要解析的 provides 键)或 ‘value’(字面量字符串,可包含在 self-inject 解析时求值的 Go 模板表达式)二者之一,且只能有一个。在 uses[].inject 上下文中,‘from’ 针对目标的 provides 解析;在挂接的 features..inject 上下文中,针对该挂接的 FeatureRecipe 发布的 provides 解析;在 component.inject 上下文中,则针对该 component 自身的 provides 解析。在挂接的 features..inject 中,如果 ‘from’ 指定了 FeatureRecipe 未发布的键,构建会中止,除非该 FeatureRecipe 在它针对挂接的渲染上下文求值的模板中(其 valuesMapping、workload、artifacts、omits,或某个 pipeline 步骤的 with 或 when——而非其 injectMapping)自行在 .inject 处读取挂接的条目,此时该键是它自己消费的键,而不是通过 component 的 .context.inject 交付的键。‘value’ 只在 component.inject 中交付:在 uses[].inject 或挂接的 features..inject 中携带它的条目会使构建中止,因为这些块只交付其他实体发布的键。
fileinject_delivery否单个交付机制,以条目数组的形式编写。每个条目包含一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制特定的键),外加 ‘from’(要解析的 provides 键)或 ‘value’(字面量字符串,可包含在 self-inject 解析时求值的 Go 模板表达式)二者之一,且只能有一个。在 uses[].inject 上下文中,‘from’ 针对目标的 provides 解析;在挂接的 features..inject 上下文中,针对该挂接的 FeatureRecipe 发布的 provides 解析;在 component.inject 上下文中,则针对该 component 自身的 provides 解析。在挂接的 features..inject 中,如果 ‘from’ 指定了 FeatureRecipe 未发布的键,构建会中止,除非该 FeatureRecipe 在它针对挂接的渲染上下文求值的模板中(其 valuesMapping、workload、artifacts、omits,或某个 pipeline 步骤的 with 或 when——而非其 injectMapping)自行在 .inject 处读取挂接的条目,此时该键是它自己消费的键,而不是通过 component 的 .context.inject 交付的键。‘value’ 只在 component.inject 中交付:在 uses[].inject 或挂接的 features..inject 中携带它的条目会使构建中止,因为这些块只交付其他实体发布的键。
arginject_delivery否单个交付机制,以条目数组的形式编写。每个条目包含一个 ‘in’(本地标识符——环境变量名、文件路径、参数标志或自定义机制特定的键),外加 ‘from’(要解析的 provides 键)或 ‘value’(字面量字符串,可包含在 self-inject 解析时求值的 Go 模板表达式)二者之一,且只能有一个。在 uses[].inject 上下文中,‘from’ 针对目标的 provides 解析;在挂接的 features..inject 上下文中,针对该挂接的 FeatureRecipe 发布的 provides 解析;在 component.inject 上下文中,则针对该 component 自身的 provides 解析。在挂接的 features..inject 中,如果 ‘from’ 指定了 FeatureRecipe 未发布的键,构建会中止,除非该 FeatureRecipe 在它针对挂接的渲染上下文求值的模板中(其 valuesMapping、workload、artifacts、omits,或某个 pipeline 步骤的 with 或 when——而非其 injectMapping)自行在 .inject 处读取挂接的条目,此时该键是它自己消费的键,而不是通过 component 的 .context.inject 交付的键。‘value’ 只在 component.inject 中交付:在 uses[].inject 或挂接的 features..inject 中携带它的条目会使构建中止,因为这些块只交付其他实体发布的键。

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,以及开发者为其提供的配置。

属性类型必需描述
typestring是此附件所请求的 Feature 接口的 URI(例如 core/referenced-secret:1.0.0)。
descriptionstring否可选文档,说明此连接为何携带该附件。
valuesobject否开发者为该 Feature 提供的配置,由其 schema 声明进行验证。

不允许其他属性。

subsystem

属性类型必需描述
descriptionstring否可选文档,描述此 subsystem 的用途及其所代表的逻辑分组。
annotationsstring、object 或 null 的映射否开发者为此 subsystem 编写的注解。值为字符串、结构化对象(子键到值的 map,与继承的结构化值按子键合并)或 null;对从父 subsystem 继承的键显式设置 null,会从此 subsystem 中移除继承的绑定(由注解驱动的 Feature 退出)。此处声明的注解由嵌套的 subsystem 和所包含的 component 继承;按键以更近的层级为准。向下级联到每个派生 IR 节点上的 .context.annotations.aggregate 存储桶。
featuresmap of object否附加到此 subsystem 中所有 component 的横切 feature。与 component 级 feature 的 schema 相同(type、values、uses、inject)。在图最终确定时展开到每个 component 中,执行顺序位于 component 级 feature 之后。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
subsystemsmap of subsystem否键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
componentsmap of component_instance否键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。

不允许其他属性。

component_instance

属性类型必需描述
typestring是所请求的抽象 Component,以引用形式给出:其 metadata.name 加上可选的 :version(例如 core/api-server:1.0.0),绝不是文件路径。通过三层实体解析模型(工作区 catalog 目录 → 缓存 → 注册表)解析:本地编写的 Component 放在工作区根目录下的 catalog/ 中,或放在 workspace.catalog_dirs 下列出的目录中;写成相对文件路径的 type 会作为没有任何目录持有的实体而使构建停止。
activeboolean 或 string否该组件是否出现在编译后的拓扑中。值为一个布尔值,或一个基于 .parameters 的字符串模板,该模板必须解析为布尔值。解析为 false 时,该组件会从拓扑中裁剪掉,并级联到它的 uses 边及其附件。由参数驱动该值,可让 Release 通过满足该参数来切换组件是否存在。省略时默认为 true。默认值:true
descriptionstring否可选文档,描述此组件实例在应用中的角色。会被带入 IR 图中。
annotationsstring、object 或 null 的映射否开发者为此 component 编写的注解。值为字符串、结构化对象(子键到值的 map,与继承的结构化值按子键合并)或 null;对从父 subsystem 继承的键显式设置 null,会从此 component 中移除继承的绑定(由注解驱动的 Feature 退出)。Component 级注解按键覆盖继承的 subsystem 级注解;同一 subsystem 中的同级 component 各自独立保留自己的注解映射。
valuesobject否传递给 Component 的不透明认知属性,由其 schema 校验。
usescomponent_uses_block否一个 component 连向其所依赖的 component 的连接,按 socket 作为键。每个 socket 列出其目标,或以别名命名每个连接。以别名命名的连接可以携带开发者为每个连接设置的值,以及填充该 socket 所声明槽位的附件。
injectinject_block否组件级自注入。将组件自身的值(通过 ‘value:‘)或自身的 provides 键(通过 ‘from:‘)直接注入到交付管道(.context.inject)。仅当 Component 目录实体以相应机制声明了 ‘spec.inject’ 时才允许。与 uses[].inject 中声明的键冲突的 inject 键,会作为跨 inject 来源的重复交付键而使构建停止。
featuresmap of object否附加到此组件的 Features,以作者为每个附件指定的实例名为键。这是唯一的附加入口:运维 Feature、凭据 Feature(带有标签 feature.aggrega.ai/kind: secret 的 Feature)和身份 Feature 都在此处附加,使用相同的关键字和相同的结构。它们之间的区别在于附件产生的内容,而非声明方式。实例名与 Component 在 featuresSchema 中声明的槽位相匹配的附件会填充该槽位;其他任何实例名都是自由附件。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。

不允许其他属性。