版本与兼容性¶
API 版本可能体现在 Base URL、协议 Header、请求字段、资源版本或 SDK 包版本中。客户端应保留当前环境提供的版本信息，并在升级前验证实际任务；不要根据服务运行版本推断接口兼容范围。
识别版本位置¶
版本位置 |
示例形态 |
处理方式 |
|---|---|---|
Base URL 或路径 |
Genesis Base URL 中的 |
从当前环境复制完整 Base URL，不自行增加、删除或替换版本段。 |
协议 Header |
Messages 接口要求的协议版本 Header |
使用接口页给出的值；不同协议不能共用。 |
请求对象 |
工作流、模板或其他资源的版本字段 |
将其视为目标资源契约的一部分，不当作整个 Product API 版本。 |
并发控制字段 |
|
用于检测资源是否已被其他调用修改；冲突后重新读取资源。 |
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 版本。升级时：
阅读目标 SDK 版本的发布说明和迁移说明；
在独立环境安装目标版本；
验证身份认证、工作区选择和一个只读请求；
验证应用实际使用的创建、查询、分页、流式和异步任务；
验证错误对象、超时和重试逻辑；
小范围发布并保留回退到原版本的能力。
不要只根据安装成功或编译通过判断兼容。接口路径、默认超时、返回类型和错误封装的变化可能只在运行时出现。
处理资源版本冲突¶
部分更新操作要求调用方提供读取时获得的版本。它用于防止覆盖其他调用方已经提交的修改。
读取资源及当前版本
→ 基于该版本构造修改
→ 提交期望版本
→ 成功后保存新版本
→ 收到冲突时重新读取并决定怎样合并
收到 409 或明确的版本冲突后，不要自动把旧请求套到新版本上。先比较服务端当前状态和原修改意图，再由业务决定重新提交、合并或放弃。
兼容性信息不足时¶
当前文档没有承诺统一的接口弃用周期、兼容年限或旧版本保留数量。因此：
不根据组件运行信息推算支持期限；
不把测试环境仍可调用的旧路径写成稳定兼容入口；
不依赖接口没有明确公开的旧字段或响应形态；
发布前以当前环境的接口说明、SDK 发布材料和实际测试结果为准；
如果升级影响关键业务，保留旧客户端和配置的可回退版本。
具体接口确认弃用、迁移路径或替代字段后，应将说明放在该接口页，并链接到对应迁移任务。通用页不维护未经确认的时间表。