开发指南数据契约规范
协议演进约定
平台对外协议如何加字段、如何标版本、什么算破坏性变更，以及旧版本保留多久。
本页是平台提供给 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 调整 |