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

发布面

每个 Aggrega 目录 YAML 都带有一组统一的元数据字段,用于描述该实体以便在目录中分发:谁维护它、它采用什么许可证发布、它的源码位于何处、哪些关键词可让它被发现。这些字段共同构成了发布面——目录发布者和工具使用者所依赖的元数据词汇,有别于 labels-and-annotations.md 中记录的内容侧 metadata.labels / metadata.annotations 机制。

本页记录发布面字段、整个语料中的描述字段清单(信封级、实例级与字段级描述)、维护者字段的预期用途及经过验证的使用方,以及各实体在必填字段上的不对称(每个实体目前要求哪些字段,以及哪些不对称是有意为之)。

发布面字段

以下字段出现在每个 Domain 2(Component、Feature)和 Domain 3(Recipe、FeatureRecipe、Plugin)实体上,也出现在作为可复用模块的 Aggregate 上。它们同样出现在 Manifest 和 Release 上,但语义有所缩减(用于工作区归属,而非目录发布)。

字段类型用途使用方
descriptionstring实体的人类可读摘要编辑器悬停卡片(aggrega serve);助手调用的 describe 工具(aggrega mcp);已发布制品上的可搜索注解(aggrega push);aggrega inspect
maintainers对象数组实体的所有者(name、email、url)IR 中 Component 节点上的逐节点 catalog_metadata
licensestring法律合规(通常为 SPDX 标识符)IR 中 Component 节点上的逐节点 catalog_metadata
repositorystring(URL)源代码所在的 Git 仓库IR 中 Component 节点上的逐节点 catalog_metadata——没有其他地方读取它
homestring(URL)文档 / wiki URLIR 中 Component 节点上的逐节点 catalog_metadata——没有其他地方读取它
keywords字符串数组发现标签IR 中 Component 节点上的逐节点 catalog_metadata——没有搜索索引使用它们

在所有带有这六个字段的实体上,它们均为可选。省略整套字段的目录作者产生的仍是有效的 YAML——发布面面向的是打算进行目录分发的实体;内部使用的实体可以省略它,不会产生任何后果。

“使用方”一栏完整列出了当前已发布版本中的使用方,其中有两点后果值得直接说明,因为它们会改变哪些内容值得编写:

  • description 是唯一拥有多个读取方的字段。 aggrega serve 会将其渲染到 Aggregate、Component、Feature、Recipe、FeatureRecipe、Manifest 以及四种库类型(SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary)的悬停卡片中——Plugin 和 Release 除外。aggrega mcp 暴露的 describe 工具对任意类型的实体都会返回它。aggrega push 会将其作为可搜索注解写入已发布的制品。aggrega inspect 对每种类型都会在实体标题下方打印它,且不打印其他任何发布面字段。
  • repository、home 和 keywords 会被校验和携带,但除 IR 之外没有任何地方读取它们。 没有任何列表界面、目录站点或搜索索引使用它们。编写这些字段会记录随实体传递的来源信息,可从 IR 输出和治理策略中读取;但它不会让实体在任何地方变得可被发现。

弃用不是发布面字段。 实体的弃用方式是在发布之后于注册表中针对它记录一个标记——一个已签名的标记,携带严重级别(warning、error 或 retracted)、原因和替代项,并在拉取时校验。随后,每个读取 lockfile 的界面都会报告它;build.halt_on_deprecated_severity 只决定它是否同时中止构建。该标记从不写在实体自身的 YAML 中,原因在于结构:已发布的制品不可变,因此在发布时固化进去的标志永远无法表达之后做出的决定。aggrega inspect 为目录实体打印的弃用通知来自该标记,适用于它按名称解析的每种类型。

IR 使用——逐节点 catalog_metadata

编译器会将每个 Component 的发布面字段带入该节点的 catalog_metadata 块,可在运行返回的 IR 图中看到(aggrega inspect <release> --ir-graph)。该块包含 maintainers、license、repository、home 和 keywords——即 IR 携带的五个字段;description 不在其中。基于 IR 图契约构建的工具从这里读取元数据,而不是重新读取目录 YAML。

仅限 Component 节点。 该块的填充方式是在目录中将节点的组件类型作为 Component 查找,因此 Feature、Recipe、FeatureRecipe 或 Plugin 的发布面永远不会进入 IR——这些实体带有这些字段,字段也会通过校验,但不会由它们生成任何 IR 节点。

当源 Component 上的每个发布面字段都为空或零值时,catalog_metadata 会从 IR JSON 中完全消失:该块会被省略,而不是以空值输出。因此,相同的输入会产生相同的紧凑输出,从而使 IR diff 在多次运行之间保持稳定。

治理策略可以读取该块。以 ir-verdict 角色挂载在 plugins.governance 下的插件会逐节点接收完整的 IR 图,包括每个 Component 节点的 catalog_metadata——因此策略可以根据节点的 license、repository、home、keywords 或 maintainers 接受或拒绝构建。这种访问范围仅限于治理插槽:provider 的渲染插件接收的是不包含 catalog_metadata 的有界逐节点投影,因此渲染插件无法读取这些字段。

三种描述类型

description 字段统一出现在信封上,但语料中还在 schema 声明内部(逐字段描述)和支柱主体内部(逐实例描述)带有描述类字符串。三种不同的描述类型并存;下表对它们加以区分。

类型所在位置编写者用途
信封描述每个实体上的 metadata.description目录发布者实体整体的摘要,显示在编辑器悬停卡片上,并标记到已发布的制品上
实例描述逐实例声明旁的 description 字段(例如 featuresSchema.<slot>.description、usesSchema.<socket>.description)Schema 作者逐槽位 / 逐插座 / 逐端口的描述,供阅读该声明的消费方实体作者使用
字段描述schema: / featuresSchema: / usesSchema: 内容中的 JSON Schema 2020-12 description: 注解(紧凑形式或完整 JSON Schema YAML)Schema 作者随 schema 一起传递的逐字段文档

这三种类型共用“description”一词,但位于结构上不同的层级。信封描述适用于实体整体;实例描述适用于 schema 槽位内的一个声明;字段描述适用于类型化 schema 内的某个具体值。编写 Component 的作者应:

  • 为 Component 实体本身设置一次 metadata.description。
  • 为该 Component 声明的每个凭据槽位各设置一次 featuresSchema.admin_password.description。
  • 在 schema: 块内设置逐字段的 description: 注解——使用紧凑形式(port: { type: integer, description: "..." })或完整 JSON Schema YAML——为阅读该 Component 的 schema 的人记录每个字段。

这三种类型不会级联,也不会冲突,且各自到达不同的界面——或者不到达任何界面:

  • 信封描述——编辑器悬停卡片、已发布制品的可搜索注解,以及 aggrega inspect,见上文 Consumer 列。
  • 字段描述——原样出现在 Component 或 Feature 的悬停卡片所渲染的 schema 摘录中。该摘录仅涵盖 spec.schema,且截断为开头几行,因此块中较深处的描述——或 featuresSchema: 或 usesSchema: 内的描述——不会出现在那里。
  • 实例描述——随实体声明和携带;没有任何已发布的界面单独渲染它。aggrega inspect 列出 Component 的插座和特性槽位时不包含其描述。

维护者字段的意图

maintainers 字段承载一个对象数组,每个对象包含 name、email 和 url。其意图与经过验证的使用方如下:

意图(信息性 + IR 溯源)。 该字段在目录发布中是信息性的:其架构意图是“谁负责这个目录实体”——一个随实体一起传递的归属信号。没有任何界面将其呈现为联系人列表,也没有任何内置检查将其与任何内容进行比对。

经过验证的使用方(每节点 catalog_metadata)。 编译器将每个 Component 的 metadata.maintainers 带入 IR 中该节点的 catalog_metadata.maintainers;当源 Component 声明了该字段时,可在 aggrega inspect <release> --ir-graph 返回的图中看到它。这是该字段唯一的读取方。以 ir-verdict 角色挂载在 plugins.governance 下的治理策略可以在那里看到它,因此归属规则——每个实体至少指定一名维护者、维护者的域名属于某个批准集合——可以针对 IR 而不是针对目录 YAML 来表达。目前不附带任何此类规则;该插槽就是放置此类规则的位置。

除 JSON Schema 的结构形状(name 必填;email 和 url 可选,均为字符串)之外,编译器不强制或校验维护者内容。所列维护者是否真正拥有该实体、其邮箱是否可达、仓库提交是否由其中某人签名——这些属于目录治理问题,没有任何附带的检查会评估其中任何一项。它们属于运维人员挂载的治理策略,而不属于编译器。

必填字段的不对称性

Aggrega 的各实体类型在其 JSON Schema 中的必填字段集合略有不同。大多数不对称是有意为之,反映了实体的角色。

各实体的必填字段(不含 apiVersion / kind / metadata.name / metadata.version,所有实体都统一要求这些字段):

实体额外的必填字段设计动机
Componentmetadata.labels.component.aggrega.ai/type该标签要求对选择器匹配起承重作用:usesSchema 的 x-aggrega-selector: 注解按此标签筛选目标 Components;缺少该标签时,Component 在加载时即被拒绝
Feature—没有保留标签要求;Features 通过名称 + 发布者来标识
Recipespec.capability, spec.implements能力决定 provider 分派;implements 决定 Component 绑定
FeatureRecipespec.capability, spec.implements同 Recipe
Pluginmetadata.pluginType, spec.abiVersion该插件实现的插槽类型(属于寻址块,提供派生坐标 plugin/<pluginType>/<name> 中的 <pluginType> 段)以及其目标 ABI 版本;.wasm 的位置由该标识派生而来,而非手动编写;provider 渲染插件(pluginType: provider)还会在 spec.provider 下携带其转换契约
Aggregate—一个 components、subsystems 和 aggregates 都未声明的 Aggregate 可以加载和构建,但不渲染任何内容
Manifestspec.mappings映射层级是 Manifest 的唯一用途
Releasespec.aggregate、spec.manifest(声明了 extends 的 Release 不写 aggregate,且可以省略 manifest);metadata.environment前两项将构建锚定到特定的 Aggregate + Manifest;environment 会作为 aggrega.ai/environment 标签标记到渲染输出上

Component 标签要求起承重作用

component.aggrega.ai/type 标签是 Aggrega 在任何实体上唯一要求的标签。之所以有此要求,是因为标准库的 usesSchema 机制通过携带选择器字符串(如 "component.aggrega.ai/type=database")的 x-aggrega-selector: 注解来筛选目标候选——选择器会查阅目标的标签,以判断其类型是否与插槽接受的类型匹配。Component schema 强制执行这一点:省略该标签的 Component 在加载时即被拒绝(E0215),并指出缺失的键。

因此,该要求并非发布面层面的问题(该标签不用于目录发现),而是拓扑层面的问题:每个 Component 都带有它,包括不面向目录分发、仅供内部使用的 Components。

Release 的 metadata.environment 是必填的

Release schema 要求 metadata.environment,这是一个字符串,构建会将其作为 aggrega.ai/environment 标签标记到渲染输出上。

其他不对称性

其余的不对称性(Recipe 与 Component 的必填字段差异、Manifest 对 mappings 的要求)反映了各实体的角色。希望所有实体类型都遵循统一必填字段契约的作者将找不到这样的契约;这些不对称性是基于角色驱动设计而有意为之的。

交叉引用

  • labels-and-annotations.md — 内容侧的元数据机制,与发布面互为补充。
  • entities/component.md — Component 的 metadata.labels.component.aggrega.ai/type 要求,以及 schema / usesSchema / featuresSchema 声明。
  • entities/release.md — Release 的 metadata.environment 字段及其必填要求。
  • 10-status.md — 元数据信封的状态。
  • architecture/02-ecosystem-philosophy.md — 严格 API 分区(Strict API Partitioning)与企业元数据套件(Enterprise Metadata Suite)的设计框架。
  • architecture/13-catalog-and-registry.md §“Lockfile pinning and artifact immutability”(锁文件固定与制品不可变性)+ §“Catalog entity name-shape enforcement”(目录实体名称形态检查)— 不可变性规则在发布时拒绝什么,以及按实体类型的名称形态在何处检查:作者运行 aggrega lint 时,publishing-discipline 插件以建议形式报告这些问题,构建和发布都不检查它们。
  • architecture/11-governance-and-compliance.md §“Inheritance and publishing discipline”(继承与发布规范)— 哪些治理规则属于 publishing-discipline 插件,哪些则由扩展型 Component 的继承在构造上直接确定。