目录与注册表
本章定义平台如何通过开放容器倡议(OCI)目录在整个企业范围内扩展:目录如何布局、引用如何解析、实体如何发布和固定,以及目录实体遵循的名称形式。
Aggrega 目录:注册表分类体系与解析
Aggrega 编译器依赖一个强类型、受 OAM 启发的注册表,将抽象的开发者意图(Domain 1)解析为具体的运维现实(Domain 3)。为了在保持流畅开发者体验的同时支持开放的分布式生态系统,所有 schema、基础设施绑定、可编程策略和适配器插件都遵循标准化的开放容器倡议(OCI)URI 分类体系。由于每个目录实体都可以通过 URI 寻址,aggrega pull 会将 Release 所需的实体获取到缓存中并在其锁文件中固定它们,构建则从那里读取它们。开发者的本地工作区只包含其 Aggregate 和 Release 文件,而不包含目录的副本。
1. 核心目录结构(目录)
标准库的 aggrega-catalog 文件夹(以及任何合规的第三方目录)的组织方式在物理上强制实现关注点分离。该结构明确地将抽象接口与其具体的基础设施实现分开。
对于 Components 和 Features,URI 段与文件系统路径段一一对应。Components 使用三段式 URI({publisher}/{category}/{name}),其中 category 段取自一个封闭的认知类别集合——与该组件的 component.aggrega.ai/category 标签是同一个词(即一一对应的目录镜像,由发布 linter 的 category-matches-directory 规则检查)。Features 保持扁平结构({publisher}/{name})——数量少,增长缓慢。运维本体分类(stateful-server、server 等)位于 component.aggrega.ai/type 标签中,从不体现在目录结构中;认知能力标签(datastore.aggrega.ai/engine、agent.aggrega.ai/autonomy……)在其上叠加行为子集。Hub Web UI 使用标签进行过滤和搜索;类别既服务于文件系统导航,也作为目录的浏览轴。
下面的树在内容上是示意性的,在结构上是精确的。凡是完整绘出的实体,都一直延伸到其叶子文件,因此可以从图中读出一条完整的真实路径:哪一级目录承载哪个 URI 段,必需的版本段位于何处,以及每种实体类型在叶子处使用哪个文件名。它在每一级只展示少量条目,而非目录的全部内容——... 表示省略,写在其旁边的名称是同一级的其他条目。
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraform组件类别是一个封闭集合,类别的权威来源是该集合,而不是文件系统。尚无实体的类别值属于保留词汇:浏览轴保持稳定,作者也知道未来的组件将落在何处,因此空的货架是正确的,而不是一个亏欠占用者的空缺。由于目录不包含占位文件,此类值的目录会在其第一个实体落入时创建。
权威列表——每个类别、它容纳的内容、其实体通常携带的运维 type 值,以及存在哪些目录——见目录约定指南的 Component Categories(组件类别) 一节,该指南与其所管辖的标准库目录一同发布。
type 轴只承载运维原语——认知词汇从不出现在其上,且已发布的 Component schema 枚举了该保留键可取的值,因此写在那里的认知词汇会在文档加载时被拒绝。三轴划分:运维 type(基础设施如何对待该组件)、认知 category(它是什么,由目录镜像),以及按角色划分的能力标签(行为子集——一个实体是 category: datastore,再加上其自身产品身份所对应的 datastore.aggrega.ai/engine 值,因此 core/datastore/qdrant 携带 vector,core/datastore/redis 携带 kv,两个轴都可查询)。取决于作者配置的能力根本不由目录承载:它在编译时由治理插槽的 label-transform 角色注入,该角色读取开发者声明的 values。纯 AI 类别带有 ai- 前缀;两用类别不带前缀,其 AI 属性由能力标签表达。类别的选择依据是用户如何导航和浏览,而非编译器如何分类——类别词汇和能力标签是编译器用来匹配选择器的,编译器不会从中解读任何含义。组件的名称不会重复其类别:标准库中的 OpenAI 模型是 core/ai-model/openai,而不是 core/ai-model/openai-model。
2. 拆分式 Schema 与桥接合成流水线
为消除每个 Component 中围绕拓扑插槽声明的样板代码,Aggrega 将校验拆分为两部分,并在各自主体所在之处分别把关:
usesSchema(声明式 YAML)。 声明目录实体提供的拓扑插槽,并为每个插槽给出契约。Go CLI 原生读取它,以便在静态分析期间提取用于标签匹配的selector:字符串,并校验允许的inject机制。每个插槽条目支持一个可选的required: true字段(默认为false)——设置后,如果该插槽中没有声明任何依赖,编译器会发出校验错误。这是featuresSchema条目上required: true语义在插槽上的对应物:二者都会终止构建。在此声明插槽是标准库目录的做法,也仍是更好的途径——但这并不是开发者绘制边的唯一方式。Aggregate 作者可以在自己的组件上命名一个此usesSchema未声明的插槽,包括在完全未声明usesSchema的实体上;这种临时插槽不带选择器、不带inject允许列表,也不带逐边 schema,正是因为这里没有条目来承载它们。Feature 挂载的uses与 Release 的逐边uses不以这种方式开放——二者都只能命名已声明的插槽。完整契约以及临时插槽所放弃的内容,参见 dependency-resolution §“Domain 2: The Split Schema”。- 去语法糖。 如果开发者使用 YAML 数组简写(
uses: databases: ["db1"]),CLI 会将其规范化为映射({"db1": {"target": "db1"}})。 - 桥接合成。 编译器将
featuresSchema:插槽表投射为一个 JSON Schema 2020-12 片段——每个挂载槽对应一个属性,描述可绑定该槽的填充值的形状;在声明了inject允许列表的槽上带有x-aggrega-inject:扩展关键字。JSON Schema 校验在结构校验期间会忽略扩展关键字,也没有任何东西从该片段中读回它:需要某个槽允许列表的检查会直接读取该槽本身。usesSchema:插槽表不会被投射为任何片段。插槽的selector:与inject:保留在 Architect 编写的类型化 YAML 中并从那里读取,而插槽的逐边valueSchema:/infraSchema:会被单独包装和编译,不会在其周围凭空添加约束。 - 组合。 平台架构师编写严格的
schema:声明(紧凑形式或完整 JSON Schema 2020-12),定义values、infra和provides。该声明是实体自身的契约,并被单独编译:插槽片段和插槽表都不会合并进去。每个层面都在其主体所在之处检查,因此插槽错误会针对架构师编写的插槽条目报告,而不是报告在schema:块内的某个路径上——并且架构师仍无需编写任何uses样板代码。
示例——一个插槽声明以及编译器如何处理它: Platform Architect 的 YAML
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}编译器如何处理它
插槽表按其本身的类型化 YAML 读取:selector: 字符串交给原生标签匹配引擎,inject: 列表约束经过该插槽的边可以命名哪些交付机制。schema: 块被单独编译,作为实体自身的 values / infra / provides 契约。Static Analyzer 从 Architect 编写的插槽条目中读取 selector: 字符串——连同 Feature 实体中的 appliesTo / appliesToAnyOf——并针对每个目标的 metadata.labels 评估标签匹配,以校验跨节点类型安全。
usesSchema 中的 Kubernetes 风格选择器
Go 编译器的原生标签匹配引擎使用标准 Kubernetes 风格的选择语义评估选择器字符串(逗号表示 AND,in() 表示 OR,!=/notin() 表示 NOT)。同一引擎——以及同一选择器字符串语法——也用于评估 Feature 挂载选择器(appliesTo,以及 appliesToAnyOf 的每一项)。选择器层严格来说只是拓扑闸门——各支柱的 schema: 声明独立校验 values、infra 和 provides 的内容。Go 编译器在拓扑构建阶段绘制拓扑边之后,Static Analyzer 从 Architect 编写的插槽条目中读取 selector 字符串,并针对目标节点的 Catalog labels 进行评估,以校验跨节点类型安全。
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"引擎无法将其读作六种需求形式之一的选择器——空需求、键中含有空白或 =、!、(、) 及逗号之一、未闭合的集合——会在它所守护的每条边上中止构建,而不会被当作其他选择器读取。选择器语法列出了这些形式以及每一种拒绝情况。
3. Schema 格式与组合
为了同时提供严格的校验和标准的目录元数据(作者、版本、描述),Domain 2(接口)和 Domain 3(实现)的定义以 YAML 信封的形式编写。Domain 2 使用内嵌的 schema: 声明,以紧凑形式(默认;约 15 个关键字,可机械地转换为 JSON Schema 2020-12)或完整的 JSON Schema YAML 表达。
为什么每个目录 YAML 都重复信封。 信封(apiVersion、kind、metadata 块)出现在每个目录文件的顶部——Component、Feature、Recipe、FeatureRecipe、Aggregate、Manifest、Release、Plugin——无论正文多短。这种重复是有意为之:每个文件都被设计为可作为独立制品进行解析、校验、lint 和检查。从 OCI 仓库拉取的单个文件、放入 CI 沙箱的文件,或在第三方编辑器中打开的文件,都必须携带足够的自描述信息,使下游工具能够识别它代表哪种实体,以及适用哪个 schema 版本。目录位置从不代替信封:每个解析器、校验器和 linter 都从信封中读取实体的类型和 schema 版本。代价是每个文件都有机械性的样板代码;好处是独立工具保证在 OCI 分发层面、本地文件系统以及 IDE / CI / inspect 层面都成立。作者在编写新的目录内容时从现有文件复制信封,或从 aggrega scaffold <kind> 开始,它会为该类型打印一份已填好 apiVersion 和 kind 的起始文档。
为了遵循 DRY(Don’t Repeat Yourself,不要重复自己)原则,Catalog 采用两种不同的组合机制:
- 共享的 SchemaLibrary 条目(跨文档
$ref:): 可复用的 JSON Schema 定义存储在 SchemaLibrary 目录实体中(Tier 3)。任何使用方 Component 或 Feature 的 schema 都通过跨文档$ref:(<library>#/schemas/<entry>,不含主机——版本来自 lockfile)按标识引用它们。该引用链在编译时被遍历。库实体的编写形状参见 entities/schemalibrary,解析语义参见 vocabulary/cross-document-ref。 - 单继承(
extends): 对于完整的组件基线,实体可以使用extends: "URI"属性。Go 编译器递归读取父链,并深度合并 YAML 元数据(冲突时覆盖标签,数组则追加)。随后,两种目录类型在数据支柱上分道扬镳。Feature 的schema:按照 JSON Schema 2020-12 组合规则与其基类的组合。扩展的 Component 完全不编写支柱内容:它写下字面标记schema: inherited,并在继承链的每一层都原样接收其基类编写的schema:块。这样的 Component 组合的是结构——其挂载槽(featuresSchema)、拓扑插座(usesSchema)、自注入允许列表(inject)和命名的assertions都沿继承链合并。基类与子组件的扩展示例参见 entities/component,继承在构造上确定了什么、哪些仍是发布纪律规则,参见 governance-and-compliance §“Inheritance and publishing discipline”。
基类与子组件的扩展示例参见 entities/component,包含完整示例的 Recipe 指针与映射器编写方式参见 entities/recipe。
4. 工作区配置(.aggrega-config.yaml)
位于工作区根目录的 .aggrega-config.yaml 文件是项目的工作区配置——即工作区自身的声明,适合像 go.mod 或 package.json 那样纳入源代码管理。按照约定,.aggrega/ 目录不纳入源代码管理——把它列入 .gitignore,就像你对 node_modules/ 或 .terraform/ 所做的那样。
workspace 部分是根标记:它的存在标志着工作区根目录,并且只携带定义根的目录路径——catalog_dirs,以及为 Release 提供其自有目录路径的 releases 映射。其他所有设置都位于顶层。许多是单个值;另一些是将同一关注点的设置归集到一个键下的分节。每个字段都是可选的,并有文档说明的默认值。完整的、当前的顶层键集合(每个键及其类型、默认值和含义)由 schema 生成,见 schema/other/aggrega-config;下面的示例展示了根标记以及几个单值设置:
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootsigning: 块携带 aggrega push --sign 和 aggrega sign 使用的制品签名默认值,可同时位于顶层(全局)和每个仓库下:
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pem每个字段的优先级为:CLI 标志 > 每仓库 signing > 全局 signing > 公益默认值。Fulcio 和 Rekor 默认使用公益的 Sigstore 实例,因此是可选的;timestamp_url 没有默认值——无密钥的可信时间戳来自 Rekor 透明日志的收录,RFC3161 时间戳机构需选择启用(设置 timestamp_url 或 --timestamp-url,并提供完整端点以启用)。安全: signing: 块不携带任何机密材料——OIDC 身份令牌从不作为配置字段(它是短期机密,在签名时提供:在交互式终端中通过浏览器流程获取,或在 GitHub Actions 上从工作流获取,否则通过 --identity-token 传入,或导出为 AGGREGA_IDENTITY_TOKEN 或 SIGSTORE_ID_TOKEN),私钥也从不内联;key_path 是指向密钥文件的路径。这是与验证端有意为之的不对称:验证端固定一个内联公钥,而签名端始终只接受密钥路径。
写下 workspace: {} 即可标记一个不含内置目录的根。catalog_dirs 列表支持共享目录位于同级目录中的 monorepo 布局。编译器按顺序检查每个目录。offline: true 标志禁止任何网络访问——编译器只使用本地路径和缓存,若在本地找不到实体则终止。各分节设置各自归集一个关注点。其中包括:构建时严格程度开关和编写提示;工作区级 Wasm 挂载插座(governance、linter、importer、providers、cli),每个都接受一个插件引用列表;按规则的 lint 严格程度,包括发布纪律策略开关;守护进程的解析缓存调优及其请求分发工作池大小;以及全机共享的已编译模块存储的大小上限。另一些则携带签名和签名信任默认值以及守护进程自身的行为。每个顶层键都在 schema/other/aggrega-config 中有完整说明。
有三种不同的缓存可以配置,值得花点时间区分它们,因为它们名称相似而作用范围不同。artifact_cache_dir 指定下文所述的每工作区磁盘内容缓存。parse_cache 限制守护进程的内存解析缓存,它只在守护进程存活期间存在。compiled_module_cache 限制已编译插件机器码的磁盘存储——这是机器上所有工作区共享的缓存之一,因为插件的编译形式取决于插件本身,而与使用它的项目无关:
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the cap在机器上所有项目共享的缓存中,它是可能占据大部分磁盘缓存用量的那一个,因为机器运行的每个插件都会被编译进其中一次并保留下来,所以它是唯一设有常驻大小上限的缓存。每次打开该存储的调用都会在编译任何内容之前应用上限,按编译时间从旧到新删除整个条目,直到剩余部分符合上限。(使用 --disable-plugin-cache 运行的构建改为编译到内存中,因此既不会扩大存储,也不会裁剪它。)删除一个条目的代价只是之后需要重新编译,别无其他,这使得降低上限是安全的,在同一机器上有其他构建运行时应用上限也是安全的。请将上限设置为高于单次构建所编译的量:由于上限在编译之前应用,低于单次构建自身工作集的上限会使每次构建都丢弃并重新编译相同的模块;出于同样的原因,存储在两次构建之间可能高于上限,并在下一次构建开始时再次被裁剪。aggrega cache status 报告存储的大小,aggrega cache evict --max-size 按需将其裁剪到命令行给出的上限。
artifact_cache_dir 根目录包含三个并列的子树,由一次 aggrega pull 调用统一填充,每类固定依赖各对应一个:<artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ 用于目录实体(Components、Features、Recipes、FeatureRecipes、Aggregates、各类库,以及 Plugins 及其发布的可执行文件),其中的类型是实体发布时所属的类型,因此共享同一引用和版本的两个不同类型的实体——同名的一个 Component 和一个 Recipe——占用两个槽;<artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ 用于从 Recipe / FeatureRecipe 的 spec.source 字段拉取的源制品(Helm chart、compose 片段);<artifact_cache_dir>/inputs/sha256/<hex-digest> 用于外部输入,即 provider 在渲染时向宿主请求的远程文档,例如 chart 的 values.schema.json 中指向某个 URL 的 $ref。每个源制品缓存槽包含权威的 .tgz 归档、一个在每次构建读取时重新生成的派生 extracted/ 目录,以及一个记录制品 {kind, url, version, digest, mediatype, pulled_at} 标识的 metadata.yaml 文件。每个实体缓存槽包含获取时的已发布制品,以及用于校验它的 OCI manifest。对于文档可以引用其旁边文件的那几类实体(Recipe、FeatureRecipe、Component、Feature),其缓存槽还包含一个派生的 extracted/ 目录,存放该制品携带的文件,位于以制品内容摘要命名的目录中:若实体以归档形式发布,则为文档及实体声明的文件;若以文档本身发布,则仅为文档(§6)。实体的目录在每次读取时都会从已校验的制品中重新铺设,与源制品的文件相同:每个文件都会与制品比对,手动在该目录中修改或添加的文件会被丢弃而不会被读取,extracted/ 下的其他内容均不会被读取,未通过校验的制品会在铺设任何内容之前被拒绝。一次读取只重写与制品不同的部分,因此同时读取同一缓存的构建(aggrega serve 并行处理的请求,或针对同一工作区的两条命令)各自都能得到完整的文件。12 个字符的 <digest-prefix> 段将在不同上游摘要下重新打标签的同一 {kind, url, version} 区分到不同的槽中。外部输入不需要这样的槽:它存储为单个文件,以 lockfile 固定的内容摘要命名,因此之后的构建读取的内容由固定值寻址,而不是由字节来源的 URL 寻址,这使得该构建在禁止网络访问时仍能提供该输入。
在这三个目录旁边还可能出现另外三个目录,它们都不存放固定的依赖内容:index/ 存放 aggrega registry update 写入的按 registry 划分的可搜索快照(§8),signatures/ 将每个已校验的签名包缓存在其自身的摘要下,因此之后的读取会将缓存的 blob 与记录时的摘要重新比对,而不是再次获取签名包,catalog-snapshots/ 则保存导入读取过的每个已发布目录快照(§8)——归档及其清单存放在以清单摘要命名的槽位中,每次读取时都从归档展开目录树,另有一个 current 文件,在没有其他内容指定别的快照时,指明工作区读取的快照。
文档包不在其中。它的字节只取决于发布到的 registry 和发布的版本,因此每台机器只保存一份,与编译模块存储并列,位于同一个按用户划分的缓存根目录下的 docs-bundles/<encoded-reference>/<encoded-version>/:包括文档包、用于校验它的 manifest,以及获取时校验过的签名。artifact_cache_dir 不涉及它。在从中读取页面之前,这些签名会在读取方工作区针对该文档包 registry 自己的签名检查下再次校验,因此一个工作区较宽松的设置所放入的副本,不会提供给签名检查拒绝它的工作区——参见 aggrega-explain 和 aggrega-cache。
artifact_cache_dir 相对于工作区根目录书写,无论命令从哪个目录调用、扫描哪些目录,它都表示同一个目录。绝对路径值会在加载配置时被拒绝,并给出指明该字段的诊断:该设置的每个读取方都相对于工作区根目录解析它,因此绝对路径会指向一个它们都无法到达的位置,否则这个失败将是无声的——pull 写入的缓存会悄然不再是 build 读取的缓存。缓存可以位于某个目录目录内部,在默认布局中正是如此,因为目录目录通常就是工作区根目录本身。它不能做的是成为一个目录目录:目录扫描会跳过缓存,因此同时也是目录目录的缓存目录会将该目录的全部内容排除在每次扫描之外。artifact_cache_dir: . 指向工作区根目录,在默认布局中恰好就是这种情况,它会在加载配置时被拒绝并给出指明该字段的诊断——任何其他归约为工作区根目录的写法也是如此。这两种形式加上上述绝对路径,是配置检查能够自行识别的情况。指向其他目录目录的值(例如在 catalog_dirs 列出 sub 的工作区中使用 sub)会被正常加载,唯一的症状是其下的实体不再能被找到。因此,让缓存不位于 workspace.catalog_dirs 中列出的任何目录,是编写配置时需要自行注意的,而不是配置替你检查的事项。
跳过缓存可以防止解析产物被当作作者编写的内容读取。缓存槽保存的是 registry 获取放入的字节,存储在获取时的坐标下,并由 lockfile 摘要担保;如果扫描将其当作作者编写的目录内容拾取,就会采用未经任何校验的字节,而且位于作者无法编辑的路径上。有一个后果值得明确说明:如果缓存中存有一个没有任何 lockfile 固定的实体(由中断的 pull 遗留、手动复制进来,或在 Release 不再引用它时被遗弃),该实体对目录扫描不可见,依赖它的构建或校验会停止并报告找不到该实体。解决方法是重新 pull 该 Release,使实体通过 lockfile 解析并记录其摘要;停止信息会指明该实体,以便识别缺失的固定项。另一种做法——无论如何都解析它——正是跳过缓存所要防止的未经校验的读取。
lockfile 按 Release 划分:解析 release.yaml 会在其旁边写入 release.lock(Release 文件名主干加上 .lock)。aggrega pull 解析依赖并写入 lockfile;aggrega build 读取它,并使用其中固定的版本,而不论构建时 registry 的状态如何。当跨机器的构建可复现性很重要时,工作区会提交 lockfile;当工作区中的某个实体、库、插件或 Release 本身发生变化后,aggrega pull --release <release> 会刷新它,重新解析发生变化的部分,同时保留其他所有固定项;而 aggrega pull --upgrade --release <release> 则用于采用 registry 现在提供的更新版本。lockfile 记录每个已解析的实体,包括其类型、按编写形式的 URI、解析出的版本、内容摘要以及引用位置。类型与 URI 共同标识一个条目,因此 Aggregate 与 Manifest 同名的 Release 会为二者各记录一个条目,而对其中任一者的修改都会使下一次构建中止,直到某次 pull 将其记录下来:
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1每个固定条目都包含类型 + URI + 解析出的版本 + 内容寻址摘要。每次获取时都会校验摘要;与固定摘要不匹配的字节会以完整性错误中止构建。实体的摘要基于其发布所包含的内容计算——即其文档以及它在旁边声明的每个文件,各按其路径和字节——而不是基于其传输时的字节,因此同一实体无论是从 catalog 目录读取还是从 registry 获取,都会记录相同的摘要,无论其归档如何压缩,也无论检出时为其文件赋予了何种权限位(包括可执行位)。获取时首先校验的是 registry 自身对已发布字节的摘要,这通过 manifest 进行;对于经 registry 解析的条目,manifest 的摘要会记录在条目自身摘要的旁边。
5. 三层实体解析模型
编译器通过严格的级联查找来解析编译期间遇到的每个实体引用。这三层——本地路径、工作区与缓存、registry——对应健康的 Aggrega 项目中并存的三种编写工作流:Release 指向其旁边的文件;团队使用已签入的 catalog 以及先前拉取的缓存;以及拉取操作为尚未获取的工件访问 registry。同一级联中的工作区与缓存层和 registry 层用于求值 Aggregates 中的 type 字段、Manifest 映射中的 URI 值、Recipes 和 FeatureRecipes 上的 implements 声明,以及 Recipe 和 FeatureRecipe 流水线中的 plugin 引用;只有 Release 及其 Manifest 所指向的文件才会到达本地路径层。
本地路径。 Release 的 aggregate、manifest 或 extends 引用,或 Manifest 的 extends,若以 ./ 或 ../(POSIX 相对路径前缀)开头,会相对于 Release 直接从磁盘读取。不进行 catalog 查找,也不调用 registry。显式前缀在语法层面区分了本地路径意图与名称查找:Release 写 aggregate: ./aggregate.yaml 指向一个文件;aggregate: checkout 则按 metadata.name 指向一个 Aggregate。解析器从不通过探测字符串内容来决定适用哪一层——前缀就是判别依据。其他所有引用,包括 Aggregate 中的 Component type,都通过工作区与缓存层和 registry 层解析:本地编写的实体放在工作区根目录的 catalog/ 下,或放在 workspace.catalog_dirs 列出的目录中;写成相对文件路径的 type 会被视为没有任何 catalog 包含的实体,从而终止构建。
工作区与缓存。 不带显式本地路径前缀的引用,首先在 workspace.catalog_dirs 列出的目录中搜索(编写于或 vendor 到仓库中的项目本地 catalog 树——配置形式见 §4)——或者,对于配置在 workspace.releases 下为其单独指定目录的 Release,则在该 Release 的目录中搜索——然后在工作区根目录的 catalog/ 目录中搜索,最后在 artifact_cache_dir 中搜索(即被 gitignore 的 .aggrega/cache/ 位置,存放先前 registry 解析所拉取的工件,其子树见 §4)。第二次及后续构建时的缓存命中,使得即使项目依赖远程 catalog 内容,内循环也无需网络。
Registry。 如果工作区与缓存层没有匹配,aggrega pull——或使用 --auto-pull 或工作区 auto_pull 设置运行的构建——会针对 default_registry(默认为 hub.aggrega.ai)发起基于 ORAS 的 OCI 拉取,将工件解包到缓存中供后续构建使用,然后使用解析出的实体继续。两者皆无的构建只读取其锁文件所固定的内容,并在锁文件缺失时终止并提示 aggrega pull。registry 调用所构造的 OCI URI 形式遵循 §6(工件打包与 OCI 分类法)中描述的实体类型分类法。Aggregates 和 Manifests 中的简写 URI 会在 registry 调用之前展开为完整的 OCI 形式;驱动该展开的推断规则见 Manifest 的上下文感知简写 URI 参考以及下文 §8。
优先级与遮蔽。 解析优先级严格为本地路径 > 工作区与缓存 > registry。本地 catalog 目录中与 registry 实体具有相同标识的实体会遮蔽该 registry 实体——这是有意为之,让 catalog 作者可以在发布前试验修改。同样的遮蔽也适用于 catalog_dirs 与缓存之间:工作区 catalog 目录中存在的实体优先于缓存副本,确保对 vendor 的 catalog 所做的本地编辑立即生效。
在工作区与缓存层内,catalog_dirs 是一个有序的先胜出优先级栈。当同一实体标识出现在多个列出的 catalog 目录中时,先列出的目录胜出,后出现者被遮蔽——被覆盖、不加载,且不算错误。这让项目可以把自己的 catalog 目录叠放在共享或 vendor 的目录之前,按标识覆盖选定的实体,其余实体则回落到共享目录。覆盖是可观察的:解析详情会报告哪个目录胜出、哪个被遮蔽,因此分层永远不会静默发生。遮蔽只在跨目录时适用;同一个目录中声明相同标识的两个文件属于编写错误,会中止加载。被多次指定的目录——由 --catalog 标志和 catalog_dirs 同时指定,或在列表中出现两次——是栈中的一个条目,在其首次被指定的位置搜索一次,因此遮蔽总是涉及两个不同的文件,绝不会是一个目录与自身对照读取。由于优先级遵循作者控制的目录顺序,解析结果集是确定的。
工作区根目录的 catalog/ 目录加入该栈的末尾而非开头,且仅在该目录存在时加入——因此项目列出的任何内容在冲突时都胜过它,而列出一个无关的目录也绝不会悄然使它不再被读取。当某个列出的条目已经覆盖到它时,它会被跳过,因为对列出目录的遍历是递归的,而包含工作区根目录的栈已经读取过它。省略 catalog_dirs 与将其写为空列表是不同的声明:省略时,工作区仍会读取 catalog/;写为 [] 时,则完全不读取本地 catalog,工作区正是以此声明自己没有本地 catalog。
离线(air-gapped)构建。 设置 offline: true(§4)会完全跳过 registry 层。在本地路径层或工作区与缓存层无法解析的引用会报告实体缺失错误,而不会静默尝试网络调用,这为依规不能访问网络的 CI 流水线提供了确定性的快速失败契约。
级联的作用范围。 级联将实体获取到内存中;在其之上叠加的进一步解析机制——Manifest 的 type 与 name 两层查找、implements 的三种版本匹配形式(精确 / 主版本兼容范围 / 无版本,见 vocabulary/inheritance-and-interface),以及按 provider 和 component 实例对各轴进行的 Recipe 选择——都作用于解析器已经通过此级联拉取的实体。
6. 工件打包与 OCI 分类法(以能力作为首段)
Aggrega 对待基础设施逻辑的方式与 Docker 对待容器镜像的方式相同,通过 ORAS(OCI Registry As Storage)使用开放容器倡议(OCI)标准。用户可以将其 Aggrega catalog 托管在任何标准 registry 上(GHCR、AWS ECR、Aggrega Hub)。
由于 Recipes 与渲染能力严格一一对应——一个 Recipe 在 spec.capability 中指定一种能力,且不能面向两种——因此在 OCI registry 中组织它们最清晰的方式,是将能力放在仓库名的首段。
OCI 分类体系涵盖所有实体类型。仓库名由 kind 段(即实体的 kind,转为小写)加上实体的标识组成,全部小写:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component,发布者core,类别datastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component,发布者core,类别computehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature,发布者core(扁平,无类别)hub.aggrega.ai/aggregate/core/db-module:1.0.0— 可复用的 Aggregate 模块hub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe,能力helmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe,能力helm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe,能力composehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe,能力helmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary,共享的 schema 定义;PascalCase 的metadata.nameAIDatastores转为小写后成为仓库名hub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary,共享的 Go 模板映射片段hub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin,插槽类型provider(即metadata.pluginType段)
可发布的 kind 包括各种目录编写 kind,以及 Aggregate(一种可复用模块,无论之后作为 Release 的顶层 spec.aggregate 被引用,还是嵌套在另一个 Aggregate 的 aggregates: 块中,都可发布)和 Plugin(指向 WebAssembly 制品的内容寻址引用,由编译器路由、由运行时执行)。Plugin 是一种结构性的可发布制品,而非目录编写 kind。Release 和 Manifest 是部署侧的输入,存放在源代码管理中,从不推送(aggrega push 会拒绝它们),因此没有发布用的 mediatype。aggrega push --list-kinds 会列出当前安装的二进制可发布的 kind 集合,每行一个。每个可发布 kind 在发布的两种形态中各有自己的 OCI mediatype:
| 实体 kind | 以其文档发布 | 连同其声明的文件一起发布 |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — 不声明任何文件 |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — 不声明任何文件 |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — 不声明任何文件 |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — 不声明任何文件 |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — 不声明任何文件 |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — 通过自身的 manifest 发布 |
一次发布携带什么、因而采用何种形态,取决于实体声明了什么,而不取决于其 kind,也不取决于其目录中有什么。 一次发布携带实体文档以及实体本身在其旁边指明的文件:Recipe 或 FeatureRecipe 的本地 source:(目录会连同其下所有被其 entity.lock 中记录的忽略规则保留的文件一起传输)、其 valuesMapping:、workload: 和 artifacts: 条目通过 $import: 导入的每个文件,以及其 pin 步骤写入的 entity.lock;还有 Component 或 Feature 导入的每个 schema 文件,包括导入链中的每个文件。目录中的其他内容都不会传输:实体旁边的说明、README 或构建输出都不属于其发布内容,无论名称如何,也不会改变其发布形态。不指明任何文件的实体按其编写的文档逐字节发布,使用其 kind 的 +yaml mediatype;指明了文件的实体则以文档及这些文件的 gzip 压缩 tar 包发布,使用其 kind 的 +tar+gz mediatype。Aggregate、Plugin 以及各库 kind 在文档旁不声明任何文件,因此总是以文档形式发布——位于工作区根目录的 Aggregate 也是如此,因为它声明的每个路径都指向另一个实体,而非它携带的文件;内容全部内联的 Recipe 同样如此。远程 source 是引用而非文件,因此不携带任何内容,但记录其 pin 的 entity.lock 会使这样的 Recipe 成为归档包。每个 mediatype 的版本段对所有可发布 kind 都相同,编码段则表明字节属于两种形态中的哪一种。下游工具依据完整的 mediatype 字符串(kind、版本和编码三者)进行分派。
有一种编写形态指明的目录是发布时无法知晓的:以模板形式写出的本地 source。 其目录要等 Release 填充模板后才确定,因此实体会携带其自身目录中所有被记录的忽略规则保留的文件,从而无论 Release 选择哪个目录,该目录都已随之传输;发生这种情况时 aggrega push 会给出提示。只携带被指明的内容是有代价的,代价由使用方承担:实体读取但未在任何地方指明的文件不会传输,遇到其缺失的是使用方的构建,而不是发布方的推送,届时会指出其缓存槽位中缺失的路径。
source 目录中哪些文件属于该实体,在实体被 pin 时一次性决定并记录下来。 在作者工作区中为该实体的能力提供服务的插件,会声明其生态从不发布的内容——例如 chart 插件的版本控制目录及其对 chart 的 .helmignore 的遵循、module 插件的 .terraform/——而实体旁边作者的 .aggregaignore 拥有最终决定权。pin 步骤将该插件及组合后的规则记录在 entity.lock 中;发布、对 source pin 的每次比较、实体的 lockfile 行以及渲染都应用所记录的规则,而不会再次询问插件,因此发布的内容就是作者自己的构建所渲染的内容,绑定变化或二进制更新都不会改变任何摘要,直到实体再次被 pin。编译器对任何生态都不持立场:规则来自插件和作者,编译器只负责匹配。实体文件中的符号链接会被拒绝而不是被跟随,因为其指向的内容会以它的名义传输。aggrega pin 完整讲解了这些规则。
Recipe 的名称既不带领域前缀,也不带能力:实体类型目录和能力段已经表明了这两者。
命名约定: Components(领域 2)使用 {publisher}/{category}/{name},Features(领域 2)和可复用的 Aggregates(领域 1)使用 {publisher}/{name},其中 publisher 段指明供应商/作者(core = 官方标准库,acme = 企业)。领域 3 实体(Recipe、FeatureRecipe)使用 {capability}/{name},其中 capability 是实体在 spec.capability 中声明的 provider;引用也可以只写叶子名称来指代该实体。Recipe 名称也不包含能力,因为它已是规范 URI 的首段。
Recipes 使用 implements 关键字绑定到其实现的接口。implements 字段支持精确、主版本兼容范围或无版本匹配(关于 implements 版本匹配,参见 vocabulary/inheritance-and-interface)。Manifest 映射条目中的 Recipe 必须实现它所映射的类型,或该类型 extends 的某个基类:即条目的键,以及该键在未指明版本时所覆盖的每个组件实例的类型(按构建编译该实例时所用的版本)——因此,一个键无法把实例发送给为其类型的另一个版本编写的 Recipe。
当 Ops 工程师运行 aggrega push 时,CLI 以该形态发布实体,在其版本上不可变。使用方通过三层解析模型获取它,在本地缓存到 .aggrega/cache/ 中,并将其携带的内容展开到该实体的缓存槽位(§4)——归档包中的文件,或仅文档本身。
**拉取的实体读取其携带的文件,方式与在目录(catalog)中读取其旁边的文件完全相同。**实体从展开后的目录树中它所在的位置读取,因此它声明的相对 source: 或 $import:——无论是直接写出的还是由模板生成的——都在已发布的内容内部解析,而离开实体自身目录的路径在此处会被拒绝,与在 catalog 目录中一样。不会读取目录树之外的任何内容来代替:既不读取构建运行时所在的目录,也不读取放入缓存槽中的文件。从文件导入 schema 的 Component 或 Feature 会携带该文件,因此拉取的副本会加载已发布的契约,并据此校验所编写的值,与从 catalog 目录读取的副本完全一样。
从包中读回实体是相反的步骤,它根据文档是什么而不是叫什么来识别实体:即包顶层中 kind: 为可发布实体种类的那个文档。实体文件的名称是 catalog 的约定而非契约,因此 recipe.yaml 是标准库 catalog 的写法,而不是格式的要求;携带在实体旁边的文件——图表模板、compose 片段——也不会被误认为实体。该规则不能反过来,以使用方所需的种类为键:种类是从实体中读取的,而实体在包内,所以在必须打开包的那一刻,并没有种类可作为键。当包顶层包含两个实体文档时,读取端会停止而不是从中选择——这种包由其他客户端将包含两个实体的整个目录打包而成,随后会作为同一个制品同时位于两者各自的发布坐标之下。本产品的发布无法产生这种包,因为每个实体只携带它所声明的内容,而且发布端也会拒绝这样的目录:除 Aggregate、Release 和 Manifest 之外,每个种类都有自己的目录,aggrega pin 和 aggrega push 会拒绝旁边还有另一个实体的其他任何种类的实体,而 catalog 加载、lint 和构建则不干预该目录。两端都不评判目录的名称:<name>/<version>/ 布局是标准库 catalog 的约定。
**已发布的实体通过同一步骤读取。**一个坐标恰好携带其实体的一份副本,其形态由实体的声明决定;查看它时使用 aggrega inspect oci://<registry>/<repository>:<tag>,而不是通过在其旁边发布的可读副本——因此不存在可能与构建所解析的副本不一致的第二份副本。该命令按上述规则解包归档,从 Plugin 的清单而不是随其发布的可执行文件中读取其实体,并按该种类文件的渲染方式渲染结果;参见读取已发布的实体。
**可搜索的清单注解。**每次发布都会在制品的 OCI 清单上添加一小组可搜索注解,使注册表索引或 catalog 浏览器无需获取并解析每个实体主体,即可按 catalog 元数据筛选制品。每个实体都携带其人类可读的描述(标准 OCI description 注解)以及其 catalog 类别和种类。Plugin 还额外携带其插槽类型和它所服务的能力。aggrega registry update 正是将这些注解读回本地可搜索索引(§8)。
**每个已发布的文件都有名称。**发布所携带的每个文件都在清单上以标准的 org.opencontainers.image.title 注解命名,通用 OCI 客户端将制品拉取到目录时,会以该名称写入文件。名称说明文件是什么,其扩展名取决于文件的媒体类型:
| 发布的内容 | 通用 OCI 客户端写入的文件 |
|---|---|
| 以其文档形式发布的实体 | entity.yaml |
| 连同其声明的文件一起发布的实体 | entity.tar.gz |
| Plugin | entity.yaml,即实体,旁边是其可执行文件 entity.wasm |
| 附加到制品的签名 | signature.json |
| 附加到制品的弃用标记 | deprecation.json |
使用 aggrega push-artifact 发布的数据制品 | 通过 --name 指定的名称 |
因此,oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server 会将已发布的实体放在 ./server/entity.yaml,与发布时逐字节一致。oras 会跳过没有名称的描述符,并且仍然报告成功,这就是发布打包的每个描述符都带有名称的原因。名称仅由媒体类型派生,绝不取自所发布文件的文件名,因此从不同名称的文件发布相同字节会产生相同的清单。连同文件一起发布的实体以其包的形式到达:entity.tar.gz 是包的名称,包内的实体按上述规则查找,而不是按任何文件名。Aggrega 自身的解析从不读取这些名称——它按媒体类型选择每个文件,并按摘要信任它——因此这些名称是为其他所有客户端准备的。
7. Recipe 架构:指针与映射器
完整的 Recipe 编写接口参见 entities/recipe——source:(指针)、valuesMapping:(映射器,有三种编写方式:内联块标量、文件 $import:、指向 MappingLibrary 条目的库 $import:)、Wasm 驱动的源 schema、原生 IaC 支持以及完整示例。
8. 默认注册表与上下文感知的简写 URI
为消除 YAML 冗余,编译器根据简写 URI 所在的 schema 位置,以上下文感知的方式解析它们。默认注册表在 .aggrega-config.yaml 中配置(默认为 hub.aggrega.ai)。
注册表主机只有一种解读。每个 registries[].host 都写成主机本身——包含点的小写主机名、localhost、后跟端口的单个名称、IPv4 地址,或放在方括号中的 IPv6 地址,每种都可带可选的 :port,且不含协议、路径、凭据或大写字母——因为这种写法是查找每个注册表信任策略所用的键,而官方 hub 内置的签名要求以 hub.aggrega.ai 为键。default_registry 以同样方式指定主机,并可在其后跟一个仓库路径,例如 ghcr.io/acme:此后通过默认注册表发布的所有内容都落在该路径下,所有短引用也在该路径下解析,而信任仍仅由主机决定。default_registry 也可以写成某个 registries 条目的 name:,此时代表该条目的主机。该名称在配置解析时读取一次,依据的是所有配置文件和环境变量生效之后的条目,因此默认注册表的每个读取者——发布、位置绑定、签名验证以及每次信任查找——读取的都是这一个条目的主机,任何一方都不会访问拼写与该名称相同的主机;名称后跟路径会被拒绝,因为名称代表的是条目而非位置。名称的匹配先于主机写法,两个条目共用的名称会因歧义而被拒绝。同一解读决定了拉取时对主机所做的三件事:不含主机的目录标识绑定到哪个注册表位置,获取的制品是否指向需要检查签名的注册表,以及该检查依据哪一条信任策略。可能访问到某个注册表却错过其策略的写法——大写字母、显式的默认 HTTPS 端口、协议、凭据、registries 条目主机上的路径——会在配置处被拒绝,并指明应写的写法;不带端口且不指向任何条目的单个名称同样会被拒绝,因为它是目录标识首段的形态,而非主机的形态。该拒绝适用于所有可以设置此值的层:配置文件(其 schema 在每个 registries[].host 上以模式声明同样的形态)、AGGREGA_DEFAULT_REGISTRY 环境变量以及命令行。因此,配置能指定的每个主机,其制品都会按为它编写的策略进行验证。主机仅凭写法判断;该名称能否解析、那里是否有注册表应答,属于编译器从不获取的运行时状态。configuration 通过示例详细列出了可接受的形式。
简写 URI 以上下文感知的方式依据 Manifest 解析;具体推断规则参见 ../language-reference/entities/manifest.md §Context-Aware Shorthand URIs。
管理注册表
aggrega registry 管理工作区已知的注册表及其签名信任策略。注册表的标识是其主机;各子命令共用一种寻址模型:
aggrega registry add <host>注册一个注册表并固定其信任策略;除非信任标志手动提供策略,否则会在首次连接时获取该注册表公布的策略。可选的--name <alias>为同一个以主机为键的条目附加一个易记的别名——主机仍是标识,凡是指定注册表的地方,别名都会解析为该主机。别名在所有注册表之间唯一。aggrega registry list按主机升序打印所有已配置的注册表——主机、别名、简短的信任状态摘要,以及默认注册表的标记。它读取解析后的配置,不访问网络。aggrega registry remove <name|host>删除某个注册表的信任策略条目,可通过主机或别名指定。它只删除信任策略:default_registry指针保持不变,向该主机推送的能力也不受影响,因此该主机会恢复为默认信任,而不会变得无法访问。写成被删除条目名称的default_registry此后不再指向任何内容,在重写之前会被拒绝。aggrega registry update刷新本地可搜索索引,详见下文。
凡是指定注册表的地方——registry 子命令的参数,或 aggrega push 与 aggrega push-artifact 上的 --registry 标志——都由同一个解析器解读该标记:已配置的别名解析为其主机,其他任何标记都被读作它所指的主机,并去掉引用中的协议、路径和凭据。当该主机成为签名决策的依据时——aggrega push 或 aggrega push-artifact 的目标,或 aggrega registry add 写入条目所用的键——它必须符合上述唯一解读,不符合时会被拒绝,并指明应写的写法。按该方式书写的未注册主机是合法的目标,会被接受。
本地可搜索索引
aggrega registry update [<name|host>] 为工作区已知的注册表构建本地可搜索索引。它遍历每个已配置注册表的仓库,选出每个仓库已发布的最高版本,读取该版本的可搜索 manifest 注解(§6),并将每个注册表的索引写入制品缓存。不带参数时,它为所有已配置的注册表建立索引;带单个注册表参数(主机或别名)时,只为该注册表建立索引。
该索引采用包管理器中常见的显式刷新模型:registry update 是访问注册表的命令,之后的 aggrega search 离线读取已写入的索引。注册表的记录文件是确定性的——针对同一注册表状态的两次更新产生逐字节相同的内容,新鲜度时间戳存放在同级文件中,因此不会扰动记录。没有已发布版本的仓库或无法读取的仓库会被跳过,因此单个无法读取的仓库绝不会导致整个索引被放弃。
已发布的目录快照
标准库目录的每次发布也会将目录作为一个整体发布:一个 OCI 制品,即该次发布所发布的提交中目录树所含全部文件的 gzip 压缩 tar 包,位于目录所发布到的 registry 下的 catalog/snapshot——对于官方 hub 即为 hub.aggrega.ai/catalog/snapshot。只有在该次发布的每个实体都已位于 registry 上之后,它才会被推送,因此它不会指向 registry 中不存在的任何实体。它以构建它的提交和 latest 作为标签,并像该次发布的每个实体一样由发布者以无密钥方式签名,因此可凭发布者的身份依据 registry 的信任策略对其进行验证;只有在快照签名之后,latest 才会移到该快照。归档按照一种固定布局写入——条目按名称升序排列,每个条目具有相同的模式、所有者和修改时间——因此同一个提交始终产生相同的 tar 包。
它唯一的读取者是工作区未指定任何目录文件夹的导入:没有 workspace.catalog_dirs,没有 AGGREGA_CATALOG_DIRS,工作区根目录下也没有 catalog/ 目录。aggrega import、编辑器会话的导入以及助手的导入工具执行的是同一操作,因此它们获取快照的方式相同。导入通过与 pull 相同的出站流量管控和登录,从工作区的默认 registry 获取快照,在保留任何内容之前依据该 registry 的信任策略验证其签名,将其保存在工作区的制品缓存中,并在那里将其作为目录文件夹读取,同时锁定到其摘要——因此导入器得到的是目录的 Components,--target 则根据其 Recipes 起草 Manifest,所走的路径与目录文件夹完全相同。导入在其草稿旁写入的记录通过清单摘要指明该快照,因此之后对相同草稿的导入无需发出请求即可读取同一目录,而 aggrega import --upgrade 会获取最新的快照,并从此以其为依据进行导入。在离线模式下,需要获取快照的导入会停止,并指明应运行的内容。指定了目录文件夹的工作区以该文件夹为依据进行导入,不获取任何快照。没有其他命令读取该快照:pull、构建和验证都通过 §5 的各层级解析每个实体并将其固定在锁文件中,而导入的草稿按名称引用目录实体,因此构建这些草稿时也以相同方式解析这些实体。
9. Lockfile 固定与制品不可变性
Lockfile 固定机制将每个依赖锚定到一个特定的内容寻址制品。在首次 lockfile 解析(aggrega pull)时,解析器查询注册表,按照 URI 的三种约束形式(精确 / 范围 / 无版本)选出一个版本,并将固定的版本 + 摘要写入该 Release 的 <release-stem>.lock。之后的 aggrega build 调用使用固定的值,不受注册表可变性影响;发布新版本不会影响现有的 lockfile。
该固定模型依赖一条关键规则:一旦某个 name:version 发布到注册表并解析为摘要 D,该映射就是永久的。以不同内容重新发布同一个 name:version 会在推送时被拒绝。 aggrega push 本身在每次发布时都执行这一点:它在目标注册表中解析 name:version 处的现有制品;如果存在且摘要与即将推送的内容一致,推送不上传任何内容,只附加该发布仍缺少的部分——其发布日期,以及推送进行签名时的签名;如果存在但摘要不同,推送会以不可变性违规错误终止,并列出两个摘要。
不可变性之所以重要,在于两个后果:
- Lockfile 固定是可信的。 当 lockfile 记录摘要为
D的mariadb:1.0.0时,按摘要获取的构建收到的就是D的字节。若没有不可变性,注册表端的修改可能会在 lockfile 固定之下替换D的字节,破坏从锁定时到构建时的稳定性。可复现构建正依赖于这一保证。 - 发布后的元数据变更有明确的途径。 将已发布版本标记为弃用、轮换签名密钥或修订证明,都不能通过修改已发布的制品来完成(该规则禁止这样做)。必须通过发布新的补丁版本,或发布单独记录元数据变更的附属制品来完成。两种途径都可审计——新版本或附属制品会作为独立的注册表条目出现——且都不会改变原始制品的字节。
不可变性规则统一适用于每个通过 OCI 发布的 Aggrega 制品(实体、SchemaLibrary、MappingLibrary,以及由 Recipe pipeline[].plugin: / FeatureRecipe pipeline[].plugin: / 工作区配置 plugins.{governance,linter,importer}[]: 引用的 Wasm 插件)。凡是在 lockfile 中以 name:version 加内容摘要固定的内容,都受不可变性约束。
不可变性是无条件的,任何配置都不能放宽它。 没有任何标志或工作区配置项允许覆盖,因为注册表不提供可供操作者选择启用的覆盖途径。已更改的内容以新版本发布,aggrega lint --pre-publish 会验证版本升级是否与变更的分类相符。
重新解析到更新的版本需要用户显式操作:aggrega pull --upgrade --release <release> <uri> 重新解析单个依赖,同时保持其他所有固定不变;aggrega pull --upgrade --release <release> 则依据当前注册表状态重新解析所有依赖。范围形式和无版本形式的依赖会重新解析到最新的匹配版本;精确形式的固定不会变动,除非用户显式升级到另一个精确版本。Lockfile 是构建的事实来源;用户书写的形式表达的是编写时的版本约束。
10. 目录实体名称形状的强制检查
目录实体名称遵循按实体种类区分的模式——下文逐一列出,每种种类的详细说明见实体参考概览。它们与开发者在 Aggregate 或 Release 中编写的实例名称是不同的层面,实例名称无论种类都共用同一个模式;该模式见 ../language-reference/02-naming-conventions.md “Instance Names”。目录 YAML 声明的 metadata.name 字段并不总是与实体的规范引用 URI 相同:Component 和 Feature 直接在 metadata.name 中嵌入发布者和分组段;Recipe 和 FeatureRecipe 声明仅含叶名的 metadata.name,其规范的两段式 URI 将该叶名与实体声明的 spec.capability 配对;每种库种类都在 metadata.name 中声明一个 PascalCase 标记。
各实体种类的形状:
- Component —— 在
metadata.name中声明的三个 kebab-case 段{publisher}/{category}/{name}。示例:core/datastore/postgres。 - Feature —— 在
metadata.name中声明的两个 kebab-case 段{publisher}/{name}。示例:core/data-masking。 - Recipe ——
metadata.name中的单个 kebab-case 叶名(例如postgres)。规范引用 URI{capability}/{name}(见上文 §6)将实体声明的spec.capability与该叶名配对;首段与spec.capability匹配,而不是与实体在磁盘上的位置匹配,因此移动recipe.yaml不会改变它的引用方式。标准库目录将实体放在<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yaml,使目录树与坐标对应,但这种对应是目录的约定,而不是 URI 的来源。引用也可以裸写 recipe 的名称——只写叶名,不带 capability 段——这是实践中的主要形式,只要目录中只有一个 recipe 使用该名称即可解析。Recipe URI 中不出现发布者段,带有第三段的引用不会匹配任何 recipe。 - FeatureRecipe ——
metadata.name中的单个 kebab-case 叶名(例如k8s-secret-from-parameter),与 Recipe 对称:规范 URI{capability}/{name}由声明的spec.capability加叶名构成,同样接受裸叶名,<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yaml目录树按约定与坐标对应。 - 库种类 —— SchemaLibrary、MappingLibrary、WorkloadLibrary 和 ArtifactLibrary ——
metadata.name中的单个 PascalCase 标记,匹配^[A-Z][A-Za-z0-9]*$(例如BaseComponents、AIDatastores、BaseWorkloads)。所有库种类的形状相同,因此在库之间移动条目时,永远不需要按另一种约定重命名。除下文所述的检查外,每种库种类的 JSON Schema 外壳也声明了该模式。
对于 Component、Feature、Recipe 和 FeatureRecipe,metadata.name 的 JSON Schema 接受任何非空字符串,因此对这些种类而言,形状不属于结构性约束。每种文档所述的形状——包括外壳也声明了模式的库种类——都由发布规范插件检查,该插件以正则表达式作为唯一可信来源携带这些模式,并与编译器发行版共享。这里不会为任何种类规定插件随后忽略的形状。
该检查需主动启用:只有一个命令执行它,并且只在作者要求时运行。最常被认为会执行它的两个命令并不会执行:
- **
aggrega lint报告名称形状违规。**插件将每个实体的metadata.name与其种类的模式进行比较。该检查在作者调用aggrega lint时运行——针对单个实体、使用--release针对某个 Release 的依赖闭包,或不带参数调用时针对所有目录实体——同一规则集也可通过 CLI 暴露的面向编辑器的工具接口使用。检查结果仅为建议:以warn严重级别报告,不会中止。
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)检查结果以其严重级别和其规则注册的短代码开头,aggrega explain E0278 会展开该代码。出问题文件的路径打印在检查结果上方,对整个目录的运行最后会给出已检查实体的数量和产生的建议性结果数量。
- **
aggrega build不检查名称形状。**渲染输出不依赖 Aggrega 实体名称,因此对包含不合规名称的目录进行构建时,不会产生警告或诊断,并且与其他情况下完全一样地成功。 - **
aggrega push也不检查名称形状。**发布会因其他原因被拒绝——最主要的是上文的不可变性规则,即以不同内容重新发布已有的name:version会中止。当拒绝信息提到aggrega lint --pre-publish时,它是在告诉作者该运行哪个命令;push 本身不会运行它。
由于构建和发布都不检查形状,希望遵守该约定的目录需要有意地运行 aggrega lint——放在 pre-commit 钩子中,或作为流水线步骤。注意,名称形状检查结果仅为建议:aggrega lint 会报告它,但仍以成功状态退出,因此希望以该约定作为门控的流水线应读取报告的检查结果,而不是依赖退出状态。
按工作区设置的策略可以屏蔽该规则:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default false设置该策略后,名称形状规则不会报告任何内容。也可以使用 aggrega lint --allow-nonstandard-names 仅为单次调用设置,或使用 --no-allow-nonstandard-names 强制重新关闭。合理的用途包括永远不会发布的目录、多发布者实验以及特殊用途的实体。
11. 注解驱动的 Feature 展开
Manifest 的 mappings.features.annotations 块声明注解键与 Feature 类型之间的绑定,以及一张按支柱分组的路由表(maps.infra、maps.values),列出每个注解可以填充的 Feature schema 属性。解析中的注解展开子阶段由外向内遍历 Release 边界,并由外向内遍历 Aggregate 子系统,通过级联和覆盖(支持整值和按子键的 null 退出)计算每个组件的有效注解集合,并注入在其 IR 来源信息中带有 origin: annotation 的合成 Feature 附加。完整的绑定结构和编写说明见 language-reference/entities/manifest.md 和 language-reference/providers/well-known-annotations.md;本节记录展开路径所依赖的目录加载时和 inspect 时的机制。
Schema 编译缓存。 每个 Feature 的 spec.schema.{infra,values} 在每次构建中只编译一次,并在各次级联遍历中复用。针对同一 Feature schema 的重复按子键类型校验(每个组件一个级联作用域,组件可达数百个)读取已编译的 schema,而不是再次编译。构建之间不保留任何内容,因此发生变化的 Feature schema 会在下一次构建中重新编译。
绑定目标校验(目录加载)。 在目录加载时,编译器遍历每个 Manifest 的 features.annotations 绑定,并验证 maps.infra 和 maps.values 下声明的每个点分路径都对应于所引用 Feature 的 spec.schema.<pillar> 实际声明的属性。如果某个绑定路由到 Feature schema 未列出的路径,目录加载将以明确的 OPS_ERROR 中止,该错误会指出绑定键、缺失的路径、Feature URI 和源位置。
Schema 支柱重叠 lint(目录加载)。 当某个 Feature 的 spec.schema 在 infra 和 values 两个支柱中声明了相同的属性名时,会触发一条建议性警告。这种重叠很少是有意为之——跨支柱的同名属性会使编写意图含混(当注解指向该共享名称时,哪个支柱生效?),并使诊断消息复杂化。该警告不会阻断,也无法退出:有意重叠的作者保留重叠和警告,无意重叠的作者则在其中一个支柱中重命名该属性。
绑定映射重叠 lint(解析)。 当某个子键路径在 Manifest 的各绑定中同时出现在 maps.infra 和 maps.values 下时,会触发一条建议性警告。同时出现在两个支柱列表中的路径是不一致的——单个注解子键无法同时路由到两个支柱,而编译器采用的确定性决胜规则(同时出现在两个列表中的路径路由到 infra;在 Aggregate 中编写的注解只能经由 values 路由,因此在那里为该路径编写的注解会被拒绝)只是一张安全网,而不是预期的编写形式。该警告不会阻断;忽略该警告运行的作者仍会得到干净的构建,决胜结果可在 IR 来源信息中看到。
aggrega inspect 来源信息呈现。 inspect 命令为每个 Feature 附加呈现一个方括号,记录每个已填充叶子的来源:
[explicit]—— 该 Feature 是通过 Aggregate 或 Release 的features:块显式附加的。[annotation: <key> from <source>]—— 每个已填充的叶子都来自同一个注解键。方括号会指出该键以及声明该注解的位置:文件,以及文件中以点号分隔的键路径。- 按叶子的方括号 —— 跨侧组合,其中每个已填充的叶子都以各自的来源方括号呈现(部分为
[explicit],部分为[annotation: <key> from <source>])。这种形式体现了按字段显式优先的合并:当一个显式附加和一个注解贡献指向同一 Component 上的同一 Feature 实例、但写入不同的叶子时,两者的贡献各自保留在相应的叶子上,inspect 输出会逐一指出每个叶子的来源。
inspect 呈现读取 IR 中按支柱划分的 values_provenance 和 infra_provenance 映射——它们在注解展开期间与合成附加的注入一同填充——并输出最能概括这些叶子整体来源的方括号形式。inspect 机制是规范的内省途径,用于了解某个 Feature 附加为何落在某个 Component 上,以及其值来自何处。