跳转至

兼容与弃用策略

状态： v2 模块线的公开策略。本页定义 PRAXO-CORE 视为兼容的范围、加法变更 的审查方式，以及移除流程。

版本

PRAXO-CORE 使用干净的语义化版本：

  • v2.x.y 是当前模块线。
  • 补丁版本修复行为，不改变导出声明。
  • 次要版本新增向后兼容功能。
  • 破坏性变更需要 v3.0.0 和新模块路径。

可选适配器使用独立标签，例如 adapters/mcp/v0.3.0。适配器版本不代表核心版本， 反之亦然。

覆盖范围

兼容承诺覆盖导出的 pkg/... 声明：

  • 导出接口及其方法集
  • 导出结构体字段名、类型和 JSON 标签
  • 导出函数和方法签名
  • 导出常量和类型化字符串值
  • 错误哨兵和类型化错误码
  • 已文档化的线格式契约：
  • 插件 Manifest v1 和宿主信封
  • 事件名、负载字段和 stream kind
  • pkg/tool/jsonschema 文档化的 JSON Schema 子集语义
  • 可选模块导入路径及其声明的最低核心版本

不覆盖：

  • 声明适配器表面之外的具体适配器
  • 未导出 helper
  • 示例
  • 仅测试包
  • 明确标记为 experimental 的行为

加法变更

次要版本可以新增：

  • 新包
  • 新函数、类型、常量或变量
  • 具体类型的新方法，且不改变导出接口
  • 现有类型实现的新可选接口
  • 新的导出结构体字段，仅当该结构体文档化为 keyed literal 且字段可选
  • 新的可选 JSON 字段或事件 data 键

向导出接口添加方法是破坏性变更，除非接口明确文档化为可扩展。优先使用新的 可选接口。

向导出结构体添加字段可能破坏无键复合字面量。除非类型文档化为仅使用 keyed literal，否则视为破坏性变更。

破坏性变更

以下变更需要主版本：

  • 删除或重命名导出声明
  • 修改函数或方法签名
  • 修改导出接口方法集
  • 删除或重命名字段或 JSON 标签
  • 修改类型化常量字符串值或错误哨兵
  • 修改事件类型字符串、stream kind、插件 manifest 字段或宿主信封字段
  • 收紧校验，使之前有效的输入被拒绝
  • 修改文档化默认值并改变行为
  • 修改线格式且没有版本化兼容路径

行为与校验变更

当文档化有效输入或文档化默认值变化时，收紧校验和行为变更默认属于破坏性变更。 仅当以下条件全部成立时，补丁版本才可修正行为：

  • 规范或现有导出文档已经要求新行为，旧行为与其冲突；
  • 被拒绝的输入不属于文档化有效范围，或属于畸形/不安全输入；
  • 测试或消费者证据表明没有文档化有效用法依赖旧行为；
  • changelog、兼容说明和发布说明记录修正内容与迁移步骤；
  • 安全修复遵循相同证据规则，并说明为何此前输入在契约下无效。

如果必须破坏此前文档化的有效用法，应提供可选的兼容路径或使用主版本。无法保留 兼容路径的安全例外必须在发布审查中明确批准，并记录受影响行为和残余风险。

事件顺序、生命周期回调、重试/取消语义和 checkpoint 投影即使导出声明不变，也与 兼容性相关。它们需要行为测试、契约覆盖范围内的一致性向量更新、发布说明和受影响 范围的消费者验证。不能仅因 api/ 未变就把补丁归类为无行为变化。

弃用

  1. 在声明的 doc comment 和 CHANGELOG.md 中标记弃用。
  2. 旧声明至少保持一个次要版本的可用性。
  3. 记录替代方案和迁移路径。
  4. 仅在下一个主版本移除；安全原因需要更快移除时，必须在发布说明中记录。

弃用声明在移除前仍受兼容承诺保护。不得静默改变其行为。

可选模块规则

  • 可选模块标签为 adapters/<name>/vX.Y.Z。
  • 不得移动或复用已有模块标签。
  • 在模块 go.mod 中声明最低兼容核心版本。
  • 提供商 Core 不进入核心模块。
  • 提供商或协议变化时，模块可以独立发布。
  • 适配器兼容性针对声明的核心版本和已发布 consumer 模块测试。

多语言 Core

spec/ 树是 Python、TypeScript 和 Java Core 的规范契约。Go 仍是参考实现。

  • spec/SPEC_VERSION 独立于 Core 版本，对契约进行版本化。
  • 每个 Core 声明其实现的 SPEC_VERSION，并独立版本化。
  • wire 变更（JSON 字段名与大小写、事件类型、stream kind、插件 Manifest v1 与 信封、错误码）对所有 Core 都是破坏性变更。
  • 行为变更需要更新一致性向量，并以 Core 次要版本发布。
  • Core 处于 0.x 时，破坏性源码或行为变更需要次要版本和迁移说明；补丁版本不得 静默破坏文档化有效用法。无论 Core 版本如何，wire 变更仍需同步 spec/。
  • 源码 API 一对一映射，名称符合语言习惯；一致性记录在 spec/parity.md。
  • 任何 Core 不得实现 Go 参考实现尚不具备的契约能力。
  • 改变文档化 wire 行为的 pkg/... 变更必须在同一次变更中更新 spec/。

发布门禁

候选版本必须通过：

  • api/ 快照与差异审查
  • 根模块 test、vet、build、race、fuzz、staticcheck 和 govulncheck
  • 独立适配器 test、vet 和 build
  • 无本地 replace 的已发布 consumer 测试
  • 每个已发布 Core 的 spec/ 一致性向量和一致性 linter
  • 严格文档构建
  • CHANGELOG.md、VERSION、兼容说明和发布说明已更新
  • 发布工作流生成 SBOM 和校验和

如何审查变更

合并前回答：

  1. 哪些导出声明发生变化？
  2. 变更是加法、行为变化还是破坏性变更？
  3. 是否影响现有接口方法集？
  4. 无键结构体字面量是否失效？
  5. JSON 标签、事件类型、stream kind 或插件字段是否变化？
  6. 默认值或校验规则是否收紧？被拒绝的输入在此前文档化契约下是否有效？
  7. 是否有 API 快照差异和 consumer 测试覆盖？
  8. 是否需要弃用期？
  9. 可选模块是否需要新标签？
  10. 发布说明是否写明该变更没有证明什么？

相关文档