兼容性:发布版本承诺什么
Aggrega 的升级可能改变你所依赖的多个接口:你的文档所依据的模式、你的脚本调用的命令和标志、AI 助手调用的工具、你记录的错误码,以及构建插件所用的插件开发包。本页针对其中每一项说明发布版本可以改变什么、不会改变什么。本页未提及的接口,除其自身参考页面所述内容之外不作任何承诺。最后一节说明发布版本在哪里告知你其中某一项发生了变化。本页的承诺自 0.9.0 起生效。0.9.0 之前的 Releases 不受支持:hub 注册表,即 hub.aggrega.ai,不提供为它们构建的任何 Plugin 版本,它们的编译器也无法读取该注册表的目录,该目录中的文档声明的是 aggrega.ai/v1beta1。
Aggrega 以 0.x.y 版本发布:补丁版本递增最后一个数字,次版本递增中间的数字。目录实体自身的 metadata.version 是另一回事——由其作者选择,遵循 aggrega lint --pre-publish 所检查的版本递增准则,而 版本解析 描述了引用如何选择其中一个版本。
模式
Aggrega 发布的每个模式都属于一个 API 版本,即 aggrega.ai/v1beta1——实体文档在其 apiVersion 中声明的值。下面的规则适用于其中每一个:实体类型、插件载荷,以及工作区和其他模式——IR、工作区配置、锁文件等——它们都列在 模式参考 中。API 版本与发布版本号相互独立:许多发布版本读取同一个 API 版本。
v1beta1 内可以变更的内容
在同一个 API 版本内,模式只会以增量方式变更,就像 Kubernetes 变更其自身的 API 版本一样。一个发布版本可以:
- 修改描述;
- 添加字段,前提是该字段为可选字段。
在此类变更之前有效的每个文档,在变更之后仍然有效,且含义不变。读取编译器所写文档(例如 IR 或锁文件)的程序需要接受其不认识的字段,因为在 v1beta1 内,新增的可选字段可能出现在该输出中。
需要 v1beta2 的变更
以下每一项变更都需要新的 API 版本 aggrega.ai/v1beta2:
- 删除或重命名字段;
- 将字段设为必填;
- 收窄类型,或收窄字段接受的值的集合;
- 改变某个值的含义。
新的 API 版本属于破坏性变更,会被排期,并在引入它的发布版本中作为破坏性变更予以公告。
新的可选字段随认识它的编译器一起进入目录
编译器会拒绝其模式未声明的字段。正是这种严格性能捕获拼写错误的键,而它带来一个读者想不到的后果:目录实体只能在随附了认识该字段的编译器的发布版本中,才开始使用新添加的可选字段。
例如,假设某个发布版本向 Component 模式添加了一个可选字段——称之为 spec.newField:
- 在该发布版本之前编写的每个 Component 仍然有效;它们都没有设置该字段。
- 一位目录作者发布了某个 Component 的新版本,其中设置了
spec.newField。 - 来自该发布版本或更新发布版本的编译器会验证并构建该 Component。
- 来自更早发布版本的编译器会拒绝它,因为其自身的模式未声明该字段:验证会报告
spec.newField: unexpected property并指出所在行。
因此,基于该目录版本进行构建的人需先升级到添加了该字段的发布版本,而目录只有在该发布版本推出之后才会发布使用该字段的实体。已锁定的 Release 如何保留其解析出的版本,参见 版本解析。
命令行与助手工具
脚本、CI 流水线和助手配置会按名称调用 aggrega 命令、标志和助手工具。在 0.x 发布版本中:
- 补丁版本绝不会删除或重命名命令、标志或助手工具。
- 次版本可以删除或重命名其中之一,其变更日志会在 Removed 或 Changed 下注明。
- 新增内容——新的命令、标志或工具——可以出现在任何发布版本中。
助手工具是 aggrega mcp 向已连接的助手提供的工具。服务器自身的应答就是它们的完整列表,你的助手可以用 Aggrega 做什么 说明了如何获取该列表。运行命令的工具以该命令的调用路径命名,因此重命名命令也会重命名其工具。CLI 概览 列出了所有命令。
错误码
每个中止条件都带有一个短代码——字母 E 加四位数字,例如 [DEVELOPER_ERROR E0007]——打印在其诊断信息的开头。短代码是一项公开契约:一个代码只分配一次,绝不重新编号,也绝不分配给其他条件。 已停用条件的代码保持停用,因此记录在运行手册、CI 规则或 issue 中的代码在每次升级后都指向同一个条件。
错误哨兵 讲解条件所带的标识符——人们引用的短代码、程序记录的描述性代码,以及程序用于匹配的 Go 访问器——每一种标识符承诺什么,以及如何防止已停用的编号被再次分配。其 所有条件一览表 可解析每个短代码,包括已停用的短代码,而 aggrega explain 可在终端中解析单个短代码。
Plugin 开发包
插件开发包——github.com/aggrega-ai/aggrega-pdk/go、aggrega-pdk-rust 和 @aggrega-ai/aggrega-pdk-typescript——以及它们重新导出的 aggrega-abi 编解码器,从 0.9.0 起遵循语义化版本。三种语言的开发包共享一个版本号,三种语言的编解码器共享另一个版本号。
- 基于某个版本构建的插件,在同一版本线的每个后续发布版本上仍可构建。 在
0.9.x内,发布版本可以添加导出的函数、类型和常量,但绝不会删除或更改其中任何一个。 - 对导出 API 的破坏性变更只会在新的次版本中发布(从
0.9.x到0.10.0),补丁版本绝不会破坏兼容性。开发包和编解码器将与 Aggrega 自身的1.0.0一同升至1.0.0,此后破坏性变更将提升主版本号。 - 编解码器中的破坏性变更即是开发包中的破坏性变更,开发包会随之提升自身的次版本,因为它们重新导出了编解码器类型。
- 向现有类型添加的字段或成员是否算作新增,取决于语言。每个开发包随包发布的 README 会在 “Compatibility” 下说明其语言的情况。
此承诺涵盖插件源代码所引用的 API。而在编译器与运行中的插件之间传递的内容,则由插件 ABI 版本来保证:在同一个 ABI 版本内,socket 只会增加描述和可选字段,因此基于它构建的插件仍可加载。插件契约 描述了各个 socket,插件开发者指南 则描述了围绕它们的工作流程。
发布版本的变更日志说明什么
每个发布版本的说明位于 发布页面,其中包含变更日志,按 Added、Changed、Removed 和 Fixed 等标题分组。对于本页所述的接口:
- 被删除或重命名的命令、标志或助手工具会在做出该变更的次版本中列于 Removed 或 Changed 下。
- 新的模式 API 版本会在引入它的发布版本中作为破坏性变更予以公告。
- 插件开发包或编解码器的破坏性变更体现在其版本号中:它是低于
1.0.0的新次版本。 - 错误码绝不改变含义,因此没有任何发布版本需要公告此类变更。