# 版本与兼容性

API 版本可能体现在 Base URL、协议 Header、请求字段、资源版本或 SDK 包版本中。客户端应保留当前环境提供的版本信息，并在升级前验证实际任务；不要根据服务运行版本推断接口兼容范围。

## 识别版本位置

| 版本位置 | 示例形态 | 处理方式 |
| --- | --- | --- |
| Base URL 或路径 | Genesis Base URL 中的 `/v1` | 从当前环境复制完整 Base URL，不自行增加、删除或替换版本段。 |
| 协议 Header | Messages 接口要求的协议版本 Header | 使用接口页给出的值；不同协议不能共用。 |
| 请求对象 | 工作流、模板或其他资源的版本字段 | 将其视为目标资源契约的一部分，不当作整个 Product API 版本。 |
| 并发控制字段 | `expected_version`、策略版本或类似字段 | 用于检测资源是否已被其他调用修改；冲突后重新读取资源。 |
| SDK 包版本 | Go 模块或 Python 包版本 | 在应用依赖中固定，并在升级时运行接口和业务测试。 |
| 服务运行信息 | 组件构建版本、构建标识或运行状态 | 仅用于诊断，不等同于公开 API 的兼容性承诺。 |

同一个响应中出现 `version` 字段，不足以证明它是 API 版本。先根据接口页确认该字段描述协议、资源、工作流定义还是并发状态。

## 保持地址和协议一致

Genesis 接口页中的路径都相对于当前 Genesis Base URL。Base URL 已经包含 `/v1` 时，不要在 SDK `base_url` 或手写请求中再追加版本段。

Product API 页面中的请求假设 Product Base URL 已经包含 `/newmoi`。`/newmoi` 是当前产品路径前缀，不应被客户端替换成 Genesis 的 `/v1`。

调用 Messages、A2A、SSE 等协议接口时，还应保持以下内容一致：

- 请求和响应对象属于同一协议；
- 协议版本 Header 来自当前接口页；
- 流式事件按当前接口的结束条件处理；
- SDK 配置与原始 HTTP 示例使用同一 Base URL 和认证契约。

## 编写可演进的客户端

在接口公开契约允许的范围内：

- 只发送已记录的请求字段，不通过猜测添加新字段；
- 只对业务必须识别的枚举值建立自动动作；遇到未知值时停止自动推进并保留原始值；
- 不依赖 JSON 字段顺序、对象键顺序或未承诺的列表顺序；
- 区分缺少字段、字段为 `null`、空数组和空字符串；
- 按响应 `Content-Type` 选择 JSON、SSE 或文件流解析器；
- 保存服务端返回的资源和任务 ID，不根据显示名称重新推导；
- 将超时、分页上限、重试和未知状态处理放在业务层显式配置。

使用类型化 SDK 时，字段解码和未知字段行为由该 SDK 版本决定。不要在 SDK 外再次复制一套响应 Schema；升级 SDK 后通过测试确认新增字段、枚举和返回类型是否影响应用。

## 固定和升级 SDK 版本

生产应用应在依赖文件中固定经过验证的 SDK 版本。升级时：

1. 阅读目标 SDK 版本的发布说明和迁移说明；
2. 在独立环境安装目标版本；
3. 验证身份认证、工作区选择和一个只读请求；
4. 验证应用实际使用的创建、查询、分页、流式和异步任务；
5. 验证错误对象、超时和重试逻辑；
6. 小范围发布并保留回退到原版本的能力。

不要只根据安装成功或编译通过判断兼容。接口路径、默认超时、返回类型和错误封装的变化可能只在运行时出现。

## 处理资源版本冲突

部分更新操作要求调用方提供读取时获得的版本。它用于防止覆盖其他调用方已经提交的修改。

```text
读取资源及当前版本
→ 基于该版本构造修改
→ 提交期望版本
→ 成功后保存新版本
→ 收到冲突时重新读取并决定怎样合并
```

收到 `409` 或明确的版本冲突后，不要自动把旧请求套到新版本上。先比较服务端当前状态和原修改意图，再由业务决定重新提交、合并或放弃。

## 兼容性信息不足时

当前文档没有承诺统一的接口弃用周期、兼容年限或旧版本保留数量。因此：

- 不根据组件运行信息推算支持期限；
- 不把测试环境仍可调用的旧路径写成稳定兼容入口；
- 不依赖接口没有明确公开的旧字段或响应形态；
- 发布前以当前环境的接口说明、SDK 发布材料和实际测试结果为准；
- 如果升级影响关键业务，保留旧客户端和配置的可回退版本。

具体接口确认弃用、迁移路径或替代字段后，应将说明放在该接口页，并链接到对应迁移任务。通用页不维护未经确认的时间表。

## 下一步

- [确认服务地址与环境](service-endpoints-environments.md)
- [处理请求与响应格式差异](request-response-formats.md)
- [选择 Product API、SDK 或 CLI](../product-api/index.md)