Codex Local
@@ -1,7 +1,7 @@
|
||||
# 设备 API 兼容性约定
|
||||
|
||||
> 当前设备接口主版本：`/device/v2`
|
||||
> 当前接口契约：OpenAPI 0.73.0
|
||||
> 当前接口契约：OpenAPI 0.77.0
|
||||
> 适用对象：云端 API、终端固件、模拟终端和设备联调工具
|
||||
|
||||
## 1. 兼容目标
|
||||
@@ -18,6 +18,10 @@
|
||||
|
||||
## 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为基线执行破坏性变更检查。若确实需要破坏性变更，应先建立新主版本路径和迁移方案，不得通过修改或删除旧版契约绕过门禁。
|
||||
@@ -42,6 +46,7 @@ CI在拉取请求中以目标分支OpenAPI为基线执行破坏性变更检查
|
||||
|
||||
| OpenAPI版本 | 设备兼容变更 | 兼容结论 |
|
||||
|---|---|---|
|
||||
| 0.77.0 | 新增v3平台代注册端点；Windows硬件智能体客户端不再接收Product Secret，既有v2接口不变 | v2完全兼容；硬件v3客户端升级 |
|
||||
| 0.68.0 | 生产基础设施状态增加实际应用运行环境与身份服务模式证明；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
|
||||
| 0.67.0 | 发布候选快照增加生产基础设施强制门禁及主机部署模式、异地备份、外部告警、模拟服务状态；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
|
||||
| 0.66.0 | 发布候选技术验收快照增加主机健康当前性门禁；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
|
||||
|
||||
Reference in New Issue
Block a user