# 设备 API 兼容性约定

> 当前设备接口主版本：`/device/v2`  
> 当前接口契约：OpenAPI 0.64.0  
> 适用对象：云端 API、终端固件、模拟终端和设备联调工具

## 1. 兼容目标

设备通常无法与云端同步升级，因此同一主版本内必须保证已投产终端无需识别新增字段也能继续完成启动、通话、心跳、停止、遥测和录音补传。云端只依据请求正文中明确声明的能力协商可选行为，不根据固件版本字符串、HTTP `User-Agent`、设备型号或服务端推测结果改变协议语义。

## 2. `/device/v2`允许的兼容变更

- 响应对象增加非必填字段；旧终端必须忽略未知字段。
- 请求对象增加非必填字段；字段省略时必须保持原有行为。
- 增加新端点，但不得改变已有端点的请求、响应和状态转换。
- 在既有可选能力位明确为`true`时启用对应新动作；未声明、`false`或无法识别时均走旧行为。
- 修正实现缺陷，但不得改变已发布字段的类型、含义、必填性和错误处理约定。

## 3. 必须升级到`/device/v3`的变更

以下任一变化都属于破坏性变更：删除或重命名字段、改变字段类型或业务含义、给既有请求增加必填字段、缩小已发布枚举导致旧值失效、改变签名算法或规范化规则、让旧固件收到无法安全忽略的新控制动作、改变既有状态机或重试/幂等语义。此类变更必须新增`/device/v3`，并保留v2迁移期和独立契约。

CI在拉取请求中以目标分支OpenAPI为基线执行破坏性变更检查。若确实需要破坏性变更，应先建立新主版本路径和迁移方案，不得通过修改或删除旧版契约绕过门禁。

## 4. 能力协商

创建通话时，终端通过`capabilities`声明能力。`rtc_credential_renewal`是可选布尔字段：

- 明确为`true`：进入续签窗口后，心跳可能在`continue`之后返回`renew_rtc_credential`及新短期凭证。
- 省略或为`false`：云端不返回该新增动作，保持旧版v2终端心跳行为。
- 能力在通话创建时冻结到通话记录，后续心跳不允许临时切换，避免同一通话内协议行为漂移。

模拟终端显式声明该能力，用于验证新链路。旧固件无需修改请求即可继续工作。

## 5. `engine_mode`终端不变量

创建响应中的`session.engine_mode`只用于云端诊断、成本归集和通话记录。终端不得根据该字段切换麦克风采集、音频编码、近端/远端轨道发布、智能体轨道订阅或扬声器播放。终端媒体行为只由固定设备协议、RTC房间资料和显式设备能力控制。

模拟终端的创建响应结构故意不定义也不解析`engine_mode`；JSON解码会忽略该未知字段。契约测试会阻止生产模拟终端重新依赖该字段。

## 6. 变更记录

| OpenAPI版本 | 设备兼容变更 | 兼容结论 |
|---|---|---|
| 0.64.0 | 运营外部预检增加`content_safety_tls`枚举和候选快照第四类可选必需依赖；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
| 0.63.0 | 增加设备固件阶段事件查询及云端证据字段；设备已有命令回执仅记录同一结果的不可变事件，未增加旧终端必填字段 | v2兼容，旧终端行为不变 |
| 0.62.0 | 命令结果增加A/B写入、待重启、启动健康和回退可选字段，省略时保持原有单分区结果语义 | v2兼容，旧终端可继续省略 |
| 0.61.0 | 新增家庭侧固件版本影响只读接口，未修改设备协议 | v2完全兼容 |
| 0.60.0 | 新增家庭侧固件版本暂停、恢复和退役操作，设备仍通过既有命令与配置接口工作 | v2完全兼容 |
| 0.59.0 | 新增家庭侧固件信任根台账与吊销操作，未改变设备签名请求和回执格式 | v2完全兼容 |
| 0.58.0 | 新增家庭侧未完成固件上传恢复与退役接口，未修改设备端点 | v2完全兼容 |
| 0.57.0 | 设备期望配置更新改为服务端白名单合并，避免未提交字段丢失；请求字段和终端拉取语义不变 | v2兼容性修复 |
| 0.56.0 | 新增家庭创建和邀请预览等SaaS操作，未修改设备端点 | v2完全兼容 |
| 0.55.0 | 试点日/周报增加运营侧候选版本和构建摘要，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
| 0.54.0 | 新增运营侧试点运行周报生成接口，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
| 0.53.0 | 新增运营侧试点运行日报生成接口，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
| 0.51.0 | 发布候选快照增加脱敏阻断告警定位与资源存在性信息，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
| 0.52.0 | 新增运营告警接收器联通测试和状态查询，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
| 0.50.0 | 增加运营侧发布候选验收快照与归档下载，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
| 0.49.0 | 增强运营侧联调问题验收证据和高严重度发布阻断汇总，未修改设备端点、字段或终端行为 | v2完全兼容 |
| 0.48.0 | 增加运营侧外部依赖预检台账和只读页面，未修改设备端点、字段或终端行为 | v2完全兼容 |
| 0.47.0 | 增加运营侧配置投放暂停/恢复和并发版本控制；暂停只改变后续新通话的云端选择，未修改设备端点、字段或终端行为 | v2完全兼容 |
| 0.44.0 | 仅收紧运营侧Agent组合的组件版本引用校验，未修改设备端点或字段 | v2完全兼容 |
| 0.45.0 | 新通话优先冻结已投放Agent组合并把已发布人设、音色、模型和路由版本传入供应商启动；未修改设备端点、字段或终端行为 | v2完全兼容 |
| 0.46.0 | 运行时按配置类型识别运营自定义键名的Agent组合和旧路由投放，消除保留键名依赖；未修改设备端点、字段或终端行为 | v2完全兼容 |
| 0.43.0 | 仅增加运营侧Agent质量证据类型和发布门禁，未修改设备端点或字段 | v2完全兼容 |
| 0.42.0 | 新增只读设备通话状态端点，明确返回`wait`、`continue`或`leave_room`；旧端点语义不变 | v2兼容，新终端可识别供应商启动失败并及时退房 |
| 0.41.0 | 新增可选`rtc_credential_renewal`能力位；续签动作按通话冻结能力返回；明确`engine_mode`终端不变量 | v2兼容，旧终端省略能力后保持旧行为 |
| 0.40.0 | 活动授权撤回后，心跳从权威通话状态返回既有`stop`动作 | v2兼容 |
| 0.34.0 | 增加短期RTC凭证续签动作 | 由0.41.0补充能力协商，消除旧终端收到未知动作的风险 |

每次OpenAPI版本更新都必须同步本表；设备端破坏性变更还必须给出v2保留期限、v3升级方式、灰度范围和回滚条件。