---
docStatus: current
---

# 兼容性与迁移

Type14 兼容方向、Type13 退役、历史归档和后继版本迁移。

精确版本保证重复解析同一份契约，不保证任意两个实现兼容。平台按结构和方向检查签名，不通过同名、相似字段或版本范围猜测兼容。

## 输入与输出的方向

实现必须接受调用方允许的全部输入；实现的每一种返回结果和事件载荷必须能被调用方接受。即方法输入逆变、结果和事件协变。

| 变化                    | 影响                |
| --------------------- | ----------------- |
| 实现新增必填参数或收窄输入         | 不兼容               |
| 实现扩大可能返回的值、null 或错误范围 | 可能不兼容，必须按调用方约束证明  |
| 同步/异步改变，缺少所需方法或事件     | 不兼容               |
| 实现额外提供未要求的方法          | 本身不破坏原方法，其他检查仍须通过 |
| 封闭对象增加字段              | 原消费者可能拒绝，不能一概视为兼容 |

Schema 比较返回 `Compatible`、`Incompatible` 或 `NotProven`。后者表示现有算法无法证明包含关系，**不授权发布或绑定实现**；它不是自动回退到宽松校验。外部引用比较必须提供已授权的精确资源集合。

类型签名不能证明事务、幂等、超时与业务语义相容，见[方法行为与重试契约](/development/bundle-development/module-development/method-behavior/)。

## 统一版本与退役边界

当前唯一开发规范为 `baijimu-types 14.0.0` / Type Definition `5.0.0`。Module、Workflow、Agent 结构化结果和人工事项统一使用本规范：数据声明采用 `JsonSchema` 和标准 Schema；`RefType` 只描述接口。Type13 已从当前开发文档退役，不再提供旧格式作者示例。

旧环境拒绝 Type14 时，应升级相应生产者、消费者与 CLI，再迁移业务资源；不要退回旧数据格式或添加静默转换。文档规范不代替目标环境的部署和迁移验收。

`contracts/<contract>/<version>/` 中已发布的历史归档只用于追溯既有不可变产物，不属于当前开发入口。历史字节不能覆盖或伪装成 Type14，也不能据此创建新资源。存量资源须由对应 Owner 创建后继版本；在途执行和存量引用清点、迁移完成后，才移除对应历史读取代码。

## 迁移到 Type14

旧 `DataType` / 数据 `Map` / 数据 `RefType` 不是 Type14 的输入。迁移时需要理解原合同，再创建新草稿：

1. 将数据正文改为标准 Schema，完整 Type 位置使用 `JsonSchema` 包装，子 Schema 不携带平台标签。
2. 显式保留原对象开放性；封闭对象加 `additionalProperties: false`。`properties: {}` 在标准 Schema 中仍默认开放。
3. 用类型联合或组合表达 null；区分对象 `required`、参数 `required`、参数 `default_value` 和仅作为注释的 Schema `default`。
4. 将数据引用改为 `$ref`，把命名数据放入 `dataSchema.$defs`、接口放入 `interfaces`；按新作用域校验外部资源与递归。
5. 发布后继 Type Definition，更新消费 Module 的精确导入并创建后继 Module / Bundle；确认目标消费者支持后再安装和验证。

历史版本不可原地改写。业务资源的 SemVer 按实际兼容性选择，不能把文档协议版本号复制成所有资源版本号；新库不会自动升级存量资源。

## 常见错误

| 错误或现象                                    | 检查与处理                                                     |
| ---------------------------------------- | --------------------------------------------------------- |
| 旧数据标签无法解析                                | 确认接收方协议；Type14 使用 JsonSchema，不能只替换标签而保留旧字段                |
| `type: "unknown"` 不合法                    | 若实际允许任意 JSON，使用 `schema: true`；若只允许对象，用 `type: "object"`  |
| `invalid type: map, expected a sequence` | 定位具体路径；methods/events 是数组，interfaces/$defs/properties 是映射 |
| `properties: {}` 接受了额外键                  | 标准语义默认开放，封闭空对象需要 additionalProperties:false               |
| nullable、one\_of 等字段被拒绝                  | 数据正文使用标准 Schema 关键字与大小写；不要复制旧类型字段                         |
| `$ref` 找不到成员                             | 检查精确 URI、资源闭包、JSON Pointer / anchor 与内联 Schema 的独立根作用域    |
| 数据校验通过，模型严格输出失败                          | 消费者能力更窄；修改明确的业务合同，不静默补 required、null 或删除约束                |
| 兼容性返回 NotProven                          | 当前比较器没有证明，不能当作成功                                          |

先校验 [CModel envelope](/development/data-contracts/)，再按明确协议解析。生产者输出与声明协议不一致时修复生产者；消费者选错协议时修复消费者，不能用宽松解析掩盖责任边界。