story/docs/device-api-compatibility.md

设备 API 兼容性约定

2026-09-18 更新：小程序支持先添加设备到账号、后创建家庭和老人。设备端 BLE 与 ble-bind 的五个火山字段保持不变，具体变化见 账号优先流程。

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

1. 兼容目标

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

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

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

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

当前/device/v3/hardware-agent-credentials:provision和/device/v3/agent-sessions承载火山硬件对话智能体控制面：前者由平台代设备动态注册且不下发Product Secret，后者在设备直连供应商音频前预取冻结的人设、记忆和授权配置，并回报会话事件与终稿。现有RTC/VoiceChat设备继续使用完整的/device/v2接口，平台不得将v3字段或状态语义反向强加给v2固件。

v3硬件会话必须在创建时冻结SDK版本、音频格式、可靠字幕、动态配置、凭证轮换和双路PCM录制能力，并以session_updated作为平台存活检查。session_started只有在设备证明本次session.updated已应用且Bot、传输、配置摘要匹配后才会激活。事件响应中的action=stop_session是强制控制动作：设备先断开供应商，再以新的单调序号回报结束或失败；continue才允许保持连接。低负载传输不具备供应商服务端状态回调，因此不得把设备事件和终稿上报能力声明为可选。硬件v3仍处于目标板卡接入期，本次新增必填能力字段不改变已经量产的v2契约。

以下任一变化都属于破坏性变更：删除或重命名字段、改变字段类型或业务含义、给既有请求增加必填字段、缩小已发布枚举导致旧值失效、改变签名算法或规范化规则、让旧固件收到无法安全忽略的新控制动作、改变既有状态机或重试/幂等语义。此类变更必须新增/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.78.0	新增独立 /api/v1/device/* 首次接入协议；physical_confirm设备使用DEVREQ1签名和v3首通许可；旧设备的HMAC、v2路径和一键认领规则保留	新库存显式选择新协议；旧设备兼容
0.77.0	新增v3平台代注册端点；Windows硬件智能体客户端不再接收Product Secret，既有v2接口不变	v2完全兼容；硬件v3客户端升级
0.68.0	生产基础设施状态增加实际应用运行环境与身份服务模式证明；未修改设备端点、字段、状态机或终端行为	v2完全兼容
0.67.0	发布候选快照增加生产基础设施强制门禁及主机部署模式、异地备份、外部告警、模拟服务状态；未修改设备端点、字段、状态机或终端行为	v2完全兼容
0.66.0	发布候选技术验收快照增加主机健康当前性门禁；未修改设备端点、字段、状态机或终端行为	v2完全兼容
0.65.0	新增主机健康签名回调和运营只读查询；未修改设备端点、字段、状态机或终端行为	v2完全兼容
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升级方式、灰度范围和回滚条件。

首次接入协议隔离

ONBOARDING-1.2-SAAS 仅适用于生产登记为 physical_confirm 的新设备，不依靠固件版本猜测协议。工装写入该契约标识、物理编号、raw32字节认证密钥和版本。新设备调用 /device/v3/agent-sessions；同一路径新旧认证由已登记身份区分，认证失败不降级。旧 /device/v2/conversations 创建不向新设备开放。新设备恢复出厂前须授权解绑，重置响应不含旧claim码。

CALL-MEMORY-1.1 并行协议与迁移门禁

OpenAPI 0.79.0 新增 /api/v1/device/calls/*，复用 ONBOARDING-1.1 DEVREQ1 身份，使用 CALL-MEMORY-1.1 契约；可选 contract_version 声明不匹配时拒绝。旧 /device/v2、/device/v3 不会被静默解释为新协议。

关键记忆变更或授权撤回后，主体 privacy_epoch 提升，旧 v3 新会话返回 426 CALL_MEMORY_PROTOCOL_REQUIRED；旧活动会话进入清理。新会话必须通过独立清单和首次 heartbeat 授权，不能依靠 session_updated 续租。设备回报 SDK 停止只证明本地 SDK 状态；远端 UNKNOWN 仍需可核验证据。

当前板卡仍在旧 v3/WS 链路，只完成本地音频与快速重拨修复；完整 RTC 客户端和实机核验见 实施记录。新固件尚未完成前，禁止把该版本按老设备无感兼容升级发布。