---
docStatus: current
---

# 协议演进约定

平台对外协议如何加字段、如何标版本、什么算破坏性变更，以及旧版本保留多久。

本页是平台提供给 Bundle 开发者的协议的演进约定，覆盖作者定义文件、公开 API 与 CLI、回调、事件和公共 SDK。各协议正在逐步符合这些约定，[当前符合情况](#当前符合情况)列出了已经符合和尚未符合的部分；未列为已符合的协议，仍以它自己的协议页为准。

## 未知字段

| 数据方向                              | 谁来处理未知字段 | 规则                      |
| --------------------------------- | -------- | ----------------------- |
| 平台发给你：回调请求、API 响应、回执、事件、CLI 结构化输出 | 你的代码     | **必须忽略**不认识的字段，不能因此解析失败 |
| 你发给平台：API 请求、回调响应、登记信息            | 平台       | **拒绝**不认识的字段，错误里给出字段路径  |
| 你编写的定义文件：Bundle、Module、Workflow 等 | 平台       | 同上，拒绝并给出字段路径            |

平台会在同一个 MAJOR 版本内给发给你的数据增加字段。如果你自己写解析器，不要开启“拒绝未知字段”一类的选项。

平台拒绝你发来的未知字段，是为了让版本不匹配立即暴露：当你使用的 SDK 比所连接的平台新时，多出的字段会得到明确错误，不会被悄悄丢弃。

## 版本

每个协议的版本只在一处声明：

| 协议形态           | 版本位置                  |
| -------------- | --------------------- |
| 作者定义文件         | 文件内的 `schemaVersion`  |
| 你调用平台的 HTTP 接口 | URL 路径里的 MAJOR 版本段    |
| 平台回调你的接口       | 你在登记信息里声明的协议版本        |
| CModel 响应信封    | 信封的 `contractVersion` |

版本按 MAJOR 匹配。平台支持某个 MAJOR 时，该 MAJOR 下的任意 MINOR 和 PATCH 都能使用。请求体、响应体和回执不另带版本字段。

## 兼容变更与破坏性变更

以下变更在同一个 MAJOR 内进行，你的代码不需要修改：

- 平台发给你的数据增加可选字段。
- 你发给平台的请求和定义文件增加可选字段；不填时行为与之前相同。
- 新增接口、命令和可选参数。

以下变更只会随新的 MAJOR 版本出现：

- 删除或重命名字段。
- 改变字段的类型、是否必填或默认值。
- 收紧校验规则。
- 改变已有字段的含义、授权范围、错误码或重试语义。
- 给平台发给你的枚举增加取值。个别枚举在其协议页标注为“开放枚举”时除外，这类枚举需要你容忍不认识的取值。

## 版本保留

- 每个协议同时最多有两个受支持的 MAJOR 版本。
- 新 MAJOR 发布后，上一个 MAJOR 进入弃用期，至少继续可用 6 个月。
- 弃用期内的版本只修复缺陷，不再增加能力。

版本保留的承诺适用于平台对外开放之后发布的正式版本。

## 当前符合情况

| 约定           | 已经符合                                                                                                                                                           | 尚未符合                                                                           |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 忽略平台发来的未知字段  | Bundle 管理器收到的生命周期请求、资源交付、属性写入响应、资源凭据响应、登记与凭据会话响应（Rust SDK `baijimu-bundle-plugin` 28.1.0 起）；资源操作返回的视图、分页与回执（`baijimu-runtime-resource` 3.1.0 起）；CModel 信封的顶层字段 | 其他协议以各自协议页为准                                                                   |
| 版本按 MAJOR 匹配 | CModel 信封的 `contractVersion`（`@baijimu/cmodel` 与 Rust CModel 库 12.1.0 起）；管理器登记的 `protocols.lifecycle` 与 `protocols.credentials`（SDK 28.1.0 起，各环境的平台服务升级后生效）    | 管理器登记的 `protocols.propertyWrite` 仍需精确版本                                        |
| 版本只在一处声明     | 作者定义文件；生命周期请求                                                                                                                                                  | 资源操作的请求、结果与回执，以及凭据会话请求体，仍带 `contractVersion`；资源凭据接口的路径仍写完整版本。两者都会随下一个 MAJOR 调整 |