1224 lines
38 KiB
Markdown
1224 lines
38 KiB
Markdown
# 数据采集终端—云端系统设备接口文档
|
||
|
||
> 文档版本：1.0
|
||
> 设备接口版本：`/device/v2`
|
||
> OpenAPI 契约版本：`0.68.0`
|
||
> 本地联调地址：`http://localhost:58080`
|
||
> 契约来源：`openapi/openapi.yaml`、实际 HTTP 路由及设备处理代码
|
||
> 编制日期：2026-08-27
|
||
|
||
## 1. 文档范围
|
||
|
||
本文档面向终端固件、Windows 模拟设备和设备联调人员，说明终端直接调用云端的全部接口，包括：
|
||
|
||
- 设备启动、身份校验和配置同步；
|
||
- 双向语音通话创建、入房确认、智能体启动状态、心跳和停止；
|
||
- 设备遥测、错误和命令结果上报；
|
||
- 云端命令拉取与执行回执；
|
||
- 固件私有下载；
|
||
- 通话终稿补传；
|
||
- 双轨录音分片声明、对象存储直传、校验查询和本地删除回执。
|
||
|
||
本文档详细描述的是设备使用 HMAC 身份直接调用的 `/device/v2` 接口。家庭或运营人员使用的 `/api/v1/devices`、设备绑定、固件发布和灰度管理接口在第 15 章列出边界，但它们不由设备固件直接调用。火山 RTC/豆包回调也不属于设备接口。
|
||
|
||
## 2. 总体通信关系
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
D[终端设备] -->|HTTPS 控制请求 + HMAC| API[云端 API]
|
||
API --> PG[(PostgreSQL)]
|
||
API --> REDIS[(Redis)]
|
||
API -->|可靠任务| W[Worker]
|
||
W -->|StartVoiceChat / StopVoiceChat| V[火山语音服务]
|
||
D <-->|RTC 实时音频| RTC[火山 RTC 房间]
|
||
V -->|豆包智能体加入| RTC
|
||
D -->|录音文件 PUT| OSS[对象存储]
|
||
API -->|只签发短期地址| D
|
||
W -->|流式校验录音| OSS
|
||
```
|
||
|
||
重要边界：
|
||
|
||
1. 设备的控制请求经过本项目 API；实时麦克风音频不经过本项目 API 和数据库。
|
||
2. 设备和豆包智能体分别直接加入同一个火山 RTC 房间。
|
||
3. 录音文件使用短期单对象地址直接上传对象存储，不经过业务 API 传输文件字节。
|
||
4. RTC Token、上传地址和固件下载地址都是短期凭证，只允许保存在设备运行内存中。
|
||
|
||
## 3. 接口总览
|
||
|
||
| 序号 | 方法 | 路径 | 用途 | 幂等键 |
|
||
|---:|---|---|---|---|
|
||
| 1 | GET | `/device/v2/bootstrap` | 启动登记、版本与时钟检查 | 否 |
|
||
| 2 | GET | `/device/v2/config` | 拉取期望配置和绑定信息 | 否，支持 ETag |
|
||
| 3 | GET | `/device/v2/commands` | 拉取本设备待执行命令 | 否 |
|
||
| 4 | POST | `/device/v2/commands/{id}/ack` | 回报命令接收、成功或失败 | 否，业务状态幂等 |
|
||
| 5 | GET | `/device/v2/firmware-releases/{id}/download` | 获取固件私有短期下载地址 | 否 |
|
||
| 6 | POST | `/device/v2/conversations` | 创建通话并取得 RTC 房间资料 | 是 |
|
||
| 7 | POST | `/device/v2/conversations/{id}/activate` | 确认设备入房并启动豆包智能体 | 是 |
|
||
| 8 | GET | `/device/v2/conversations/{id}` | 查询权威通话和智能体状态 | 否 |
|
||
| 9 | POST | `/device/v2/conversations/{id}/heartbeat` | 通话心跳和租约续期 | 否，按序号去重 |
|
||
| 10 | POST | `/device/v2/conversations/{id}/stop` | 停止通话和豆包任务 | 是 |
|
||
| 11 | POST | `/device/v2/conversations/{id}/turns:batch` | 补传设备侧最终字幕 | 是 |
|
||
| 12 | POST | `/device/v2/telemetry:batch` | 批量上报状态、错误和命令结果 | 是 |
|
||
| 13 | POST | `/device/v2/conversations/{id}/upload-batches` | 声明录音分片并取得上传地址 | 是 |
|
||
| 14 | POST | `/device/v2/upload-batches/{id}/complete` | 声明上传完成并触发校验 | 否，业务状态幂等 |
|
||
| 15 | GET | `/device/v2/upload-batches/{id}` | 查询录音校验结果 | 否 |
|
||
| 16 | POST | `/device/v2/media-segments/{id}/local-delete-ack` | 回报本地录音密文删除结果 | 否，成功回执幂等 |
|
||
|
||
## 4. 通用协议约定
|
||
|
||
### 4.1 传输与数据格式
|
||
|
||
- 生产环境必须使用 HTTPS；本机开发环境可使用 HTTP。
|
||
- JSON 请求使用 `Content-Type: application/json; charset=utf-8`。
|
||
- 时间统一使用 RFC3339 UTC，例如 `2026-08-27T06:30:00Z`。
|
||
- UUID 使用带连字符的标准格式。
|
||
- 未声明可为空的字段不要发送 `null`，直接省略。
|
||
- 设备必须忽略响应中的未知非必填字段，以保持 `/device/v2` 向后兼容。
|
||
- 请求对象声明 `additionalProperties: false` 时，不得发送未定义字段。
|
||
|
||
### 4.2 统一成功响应
|
||
|
||
除 304、固件下载重定向等特殊响应外，成功响应统一为：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6...",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
`request_id` 是本次云端请求关联编号，设备日志应保存该值，但不得把密钥、签名、Token 或临时对象地址写入日志。
|
||
|
||
### 4.3 统一错误响应
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6...",
|
||
"error": {
|
||
"code": "VALIDATION_FAILED",
|
||
"message": "请求字段不符合契约",
|
||
"retryable": false,
|
||
"field_errors": [
|
||
{
|
||
"field": "body.device_time",
|
||
"message": "must be a valid RFC3339 timestamp"
|
||
}
|
||
],
|
||
"details": {}
|
||
}
|
||
}
|
||
```
|
||
|
||
设备应优先使用 `error.code` 和 `retryable` 决定动作，不解析或匹配 `message` 文本。
|
||
|
||
## 5. 设备 HMAC 身份认证
|
||
|
||
### 5.1 必填请求头
|
||
|
||
所有 `/device/v2` 请求都必须包含：
|
||
|
||
| 请求头 | 格式 | 说明 |
|
||
|---|---|---|
|
||
| `X-Device-Id` | UUID | 已登记的设备公开编号 |
|
||
| `X-Device-Timestamp` | RFC3339 | 本次请求 UTC 时间；默认允许前后 5 分钟误差 |
|
||
| `X-Device-Nonce` | 16～128 字符 | 每次 HTTP 尝试都必须重新生成的随机数 |
|
||
| `X-Device-Content-SHA256` | 64 位小写十六进制 | 原始 HTTP 正文字节的 SHA-256 |
|
||
| `X-Device-Signature` | Base64URL，无 `=` 填充 | HMAC-SHA256 签名结果 |
|
||
|
||
POST JSON 的摘要必须针对真正发送的原始 UTF-8 字节计算。GET 或空正文请求也必须计算空字节摘要：
|
||
|
||
```text
|
||
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
|
||
```
|
||
|
||
### 5.2 签名原文
|
||
|
||
使用单个换行符按以下顺序拼接，最后一行后不增加换行：
|
||
|
||
```text
|
||
UPPERCASE_HTTP_METHOD
|
||
REQUEST_URI_WITH_EXACT_QUERY_STRING
|
||
X-Device-Timestamp原值
|
||
X-Device-Nonce原值
|
||
X-Device-Content-SHA256原值
|
||
```
|
||
|
||
例如：
|
||
|
||
```text
|
||
GET
|
||
/device/v2/bootstrap?firmware_version=1.2.0&device_time=2026-08-27T06%3A30%3A00Z
|
||
2026-08-27T06:30:01Z
|
||
62d4b688f77b4baaa87a38d315c2f3b1
|
||
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
|
||
```
|
||
|
||
计算方法：
|
||
|
||
```text
|
||
signature = Base64URL_NoPadding(
|
||
HMAC_SHA256(device_secret, canonical_string)
|
||
)
|
||
```
|
||
|
||
注意事项：
|
||
|
||
- 查询参数的顺序、百分号编码和大小写必须与实际请求 URI 完全一致。
|
||
- `Nonce` 不是业务幂等键。业务请求重试时保留原 `Idempotency-Key` 和正文，但必须生成新 `Nonce`、时间戳和签名。
|
||
- 不允许在设备镜像、日志或前端页面中明文输出设备密钥。
|
||
- 云端 Redis 或设备身份数据库不可用时鉴权关闭失败并返回 503，不会绕过签名。
|
||
|
||
### 5.3 幂等键
|
||
|
||
需要幂等保护的接口必须包含：
|
||
|
||
```http
|
||
Idempotency-Key: 3ca4e514-cbde-41fc-aa32-6f1ed460cb01
|
||
```
|
||
|
||
长度为 16～128 字符。规则如下：
|
||
|
||
1. 同一设备、同一接口、同一幂等键和相同正文：返回第一次的业务结果。
|
||
2. 同一幂等键对应不同正文：返回 409 `IDEMPOTENCY_KEY_REUSED`。
|
||
3. 网络超时且无法确认结果时：使用原幂等键、原正文重试，但重新生成 HMAC 请求头。
|
||
4. 返回已有结果时，响应可能包含 `Idempotency-Replayed: true`。
|
||
|
||
## 6. 启动与配置接口
|
||
|
||
### 6.1 设备启动登记
|
||
|
||
`GET /device/v2/bootstrap`
|
||
|
||
用于设备开机、重连或固件升级后向云端上报运行版本，并取得服务器时间、设备状态、绑定、最低版本策略和期望配置版本。
|
||
|
||
查询参数：
|
||
|
||
| 参数 | 必填 | 类型/限制 | 说明 |
|
||
|---|---|---|---|
|
||
| `firmware_version` | 是 | string，1～80 | 当前固件版本 |
|
||
| `device_time` | 是 | RFC3339 | 设备当前时间 |
|
||
| `board_rev` | 否 | string，≤80 | 硬件板卡版本 |
|
||
| `rtc_sdk_version` | 否 | string，≤80 | RTC SDK 版本 |
|
||
| `codec` | 否 | string，≤40 | 当前首选音频编码 |
|
||
| `sample_rate` | 否 | integer，≥1 | 当前采样率 |
|
||
| `network` | 否 | string，≤80 | 网络类型或描述 |
|
||
|
||
成功响应示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6BOOTSTRAP",
|
||
"data": {
|
||
"server_time": "2026-08-27T06:30:01Z",
|
||
"clock_skew_ms": 850,
|
||
"device": {
|
||
"device_id": "10000000-0000-0000-0000-000000000511",
|
||
"status": "registered",
|
||
"model": "simulated-terminal",
|
||
"hardware_revision": "sim-rev-a",
|
||
"minimum_security_version": "security-v1",
|
||
"minimum_firmware_version": "0.1.0",
|
||
"firmware_compatible": true,
|
||
"config_revision": 3,
|
||
"binding": {
|
||
"bound": true,
|
||
"household_id": "20000000-0000-0000-0000-000000000001",
|
||
"subject_id": "30000000-0000-0000-0000-000000000001",
|
||
"subject_name": "演示长者"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
设备处理：
|
||
|
||
- `status=registered` 且 `binding.bound=true` 才能进入正常业务。
|
||
- `quarantined`：停止通话能力，只保留受控诊断或升级。
|
||
- `revoked`：立即停止业务并进入重新登记/售后流程。
|
||
- `firmware_compatible=false`：进入升级提示，不要创建新通话；云端仍会在创建通话时二次阻断。
|
||
- 使用 `server_time` 和 `clock_skew_ms` 校正后续签名时间。
|
||
|
||
主要状态码：200、400、401、503。
|
||
|
||
### 6.2 获取设备配置
|
||
|
||
`GET /device/v2/config`
|
||
|
||
请求可携带上次响应的强 ETag：
|
||
|
||
```http
|
||
If-None-Match: "v3"
|
||
```
|
||
|
||
成功响应头：
|
||
|
||
```http
|
||
ETag: "v4"
|
||
```
|
||
|
||
成功响应示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6CONFIG",
|
||
"data": {
|
||
"device_id": "10000000-0000-0000-0000-000000000511",
|
||
"revision": 4,
|
||
"desired_config": {
|
||
"volume": { "speaker": 60 },
|
||
"audio": { "sample_rate": 16000 },
|
||
"interaction": {},
|
||
"upload": {},
|
||
"rtc": {},
|
||
"policy_refs": {}
|
||
},
|
||
"reported_revision": 3,
|
||
"binding": {
|
||
"bound": true,
|
||
"household_id": "20000000-0000-0000-0000-000000000001",
|
||
"subject_id": "30000000-0000-0000-0000-000000000001",
|
||
"subject_name": "演示长者"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- 配置未变化返回 304，无响应正文。
|
||
- 设备只在完整校验新配置成功后切换本地生效版本。
|
||
- 应保留上一次有效配置；503 时不能清空本地配置。
|
||
- 应通过心跳或遥测上报实际应用的 `reported_config_revision`。
|
||
|
||
主要状态码：200、304、401、503。
|
||
|
||
## 7. 双向语音通话接口
|
||
|
||
### 7.1 创建通话并分配 RTC 房间
|
||
|
||
`POST /device/v2/conversations`
|
||
|
||
必须携带 `Idempotency-Key`。本接口只分配房间和短期凭证，不调用豆包 `StartVoiceChat`。
|
||
|
||
请求字段：
|
||
|
||
| 字段 | 必填 | 类型/限制 | 说明 |
|
||
|---|---|---|---|
|
||
| `device_time` | 是 | RFC3339 | 设备时间 |
|
||
| `monotonic_ms` | 否 | int64，≥0 | 开机后单调时钟毫秒数 |
|
||
| `capabilities.rtc` | 是 | `true` | 支持 RTC |
|
||
| `capabilities.audio_tracks` | 是 | `near`/`far` 数组 | 支持的音频轨道，至少一项且唯一 |
|
||
| `capabilities.upload_resume` | 是 | boolean | 是否支持断点/恢复上传 |
|
||
| `capabilities.rtc_credential_renewal` | 否 | boolean | 明确为 true 才允许心跳续签 RTC 凭证 |
|
||
| `network.type` | 是 | string，1～40 | 网络类型，如 wifi/ethernet/4g |
|
||
| `network.rssi` | 否 | integer | 信号强度 |
|
||
| `requested_goal` | 是 | 固定 `open_conversation` | 设备技术目标，不作为豆包提示词 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"device_time": "2026-08-27T06:31:00Z",
|
||
"monotonic_ms": 15820,
|
||
"capabilities": {
|
||
"rtc": true,
|
||
"audio_tracks": ["near", "far"],
|
||
"upload_resume": true,
|
||
"rtc_credential_renewal": true
|
||
},
|
||
"network": {
|
||
"type": "wifi",
|
||
"rssi": -48
|
||
},
|
||
"requested_goal": "open_conversation"
|
||
}
|
||
```
|
||
|
||
201 响应示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6CREATE",
|
||
"data": {
|
||
"conversation_id": "0829059e-4485-46b9-87ea-5a2fcefc6c35",
|
||
"status": "ROOM_ISSUED",
|
||
"rtc": {
|
||
"app_id": "<rtc-app-id>",
|
||
"room_id": "r_25a5f0e5825645d099540604e17ee15c",
|
||
"user_id": "d_10000000000000000000000000000511",
|
||
"agent_user_id": "a_0829059e448546b987ea5a2fcefc6c35",
|
||
"token": "<short-lived-rtc-token>",
|
||
"expires_at": "2026-08-27T06:41:00Z"
|
||
},
|
||
"privacy": {
|
||
"retention_mode": "transcript_only",
|
||
"record_near": false,
|
||
"record_far": false,
|
||
"upload_allowed": false
|
||
},
|
||
"session": {
|
||
"engine_mode": "s2s_hybrid",
|
||
"heartbeat_interval_sec": 10,
|
||
"allocation_expires_at": "2026-08-27T06:33:00Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
设备处理：
|
||
|
||
1. Token 只保存在内存中，不写日志和磁盘。
|
||
2. 在 `allocation_expires_at` 前使用 `rtc.room_id + rtc.user_id + rtc.token` 加入 RTC。
|
||
3. 发布麦克风近端音频，并订阅 `agent_user_id` 的智能体音频。
|
||
4. 成功入房后调用激活接口。
|
||
5. `session.engine_mode` 仅供云端诊断，终端不得据此切换采集、编码、发布或播放逻辑。
|
||
|
||
主要状态码：
|
||
|
||
| HTTP | 错误码/情况 | 设备动作 |
|
||
|---:|---|---|
|
||
| 201 | 创建成功 | 加入 RTC 后激活 |
|
||
| 403 | `CONSENT_REQUIRED` | 停止并等待授权 |
|
||
| 409 | `DEVICE_NOT_BOUND` | 提示先绑定设备 |
|
||
| 409 | `CONVERSATION_ALREADY_ACTIVE` | 查询或恢复已有通话 |
|
||
| 409 | `IDEMPOTENCY_KEY_REUSED` | 更正调用逻辑，不能换正文重用同键 |
|
||
| 422 | `AGENT_CONTEXT_PREPARATION_FAILED` | 不入房，提示背景资料准备失败 |
|
||
| 426 | `FIRMWARE_UPDATE_REQUIRED` | 进入固件升级流程 |
|
||
| 429 | `USAGE_QUOTA_EXCEEDED` | 停止自动重试并提示额度/并发限制 |
|
||
| 503 | `RUNTIME_CONFIG_UNAVAILABLE` 等 | 按 `retryable` 退避重试 |
|
||
|
||
### 7.2 确认入房并启动智能体
|
||
|
||
`POST /device/v2/conversations/{id}/activate`
|
||
|
||
必须携带 `Idempotency-Key`。只有 RTC 加入成功后调用。
|
||
|
||
请求字段：
|
||
|
||
| 字段 | 必填 | 限制 | 说明 |
|
||
|---|---|---|---|
|
||
| `joined_at` | 是 | RFC3339 | 实际入房时间 |
|
||
| `room_id` | 是 | 1～200 | 必须等于创建响应的房间号 |
|
||
| `rtc_user_id` | 是 | 1～200 | 必须等于创建响应的设备 RTC 用户号 |
|
||
| `rtc_join_result` | 是 | 固定 `success` | 只接受成功入房确认 |
|
||
| `config_revision` | 是 | int64，≥1 | 本通话使用的配置版本 |
|
||
| `connection_reference` | 否 | ≤255 | 设备侧连接关联号，不能包含凭证 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"joined_at": "2026-08-27T06:31:03Z",
|
||
"room_id": "r_25a5f0e5825645d099540604e17ee15c",
|
||
"rtc_user_id": "d_10000000000000000000000000000511",
|
||
"rtc_join_result": "success",
|
||
"config_revision": 4,
|
||
"connection_reference": "rtc-session-00001"
|
||
}
|
||
```
|
||
|
||
202 响应示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6ACTIVATE",
|
||
"data": {
|
||
"conversation_id": "0829059e-4485-46b9-87ea-5a2fcefc6c35",
|
||
"status": "STARTING_AGENT",
|
||
"accepted_at": "2026-08-27T06:31:04Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
响应表示云端已经受理，不表示豆包一定已经进房。随后必须调用通话状态查询接口，不能不断更换幂等键重复激活。
|
||
|
||
主要状态码：202、400、401、404、409、503。
|
||
|
||
### 7.3 查询权威通话状态
|
||
|
||
`GET /device/v2/conversations/{id}`
|
||
|
||
200 响应示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6STATE",
|
||
"data": {
|
||
"conversation_id": "0829059e-4485-46b9-87ea-5a2fcefc6c35",
|
||
"status": "ACTIVE",
|
||
"action": "continue"
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 取值 | 设备动作 |
|
||
|---|---|---|
|
||
| `status` | `PREPARING`、`ROOM_ISSUED`、`STARTING_AGENT`、`ACTIVE`、`STOPPING`、`COMPLETED`、`FAILED`、`EXPIRED` | 云端权威状态 |
|
||
| `action` | `wait` | 保持 RTC 房间并有限次数继续查询 |
|
||
| `action` | `continue` | 豆包已激活，进入正常双向语音和心跳 |
|
||
| `action` | `leave_room` | 立即退出 RTC 房间并结束本地通话流程 |
|
||
| `failure_code` | 可选稳定错误码 | 仅用于展示和诊断，不显示供应商原始错误 |
|
||
|
||
失败示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6STATEFAILED",
|
||
"data": {
|
||
"conversation_id": "0829059e-4485-46b9-87ea-5a2fcefc6c35",
|
||
"status": "FAILED",
|
||
"action": "leave_room",
|
||
"failure_code": "provider_start_rejected"
|
||
}
|
||
}
|
||
```
|
||
|
||
推荐轮询：首次等待 500 ms，之后每 1 秒查询，累计不超过房间预留有效期；达到上限仍未收敛时按本地超时处理并调用停止接口。
|
||
|
||
主要状态码：200、400、401、404、503。
|
||
|
||
### 7.4 通话心跳
|
||
|
||
`POST /device/v2/conversations/{id}/heartbeat`
|
||
|
||
进入 `STARTING_AGENT` 或 `ACTIVE` 后，按创建响应的 `heartbeat_interval_sec` 调用。
|
||
|
||
请求主要字段：
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `sequence_no` | 是 | 从 1 开始严格递增；进程重启后应从耐久状态恢复 |
|
||
| `device_time` | 是 | RFC3339 UTC |
|
||
| `monotonic_ms` | 是 | 单调时钟毫秒数 |
|
||
| `conversation_status` | 是 | 设备当前观察的通话状态 |
|
||
| `rtc.joined/uplink/downlink` | 是 | RTC 入房、上行和下行状态 |
|
||
| `network.type` | 是 | 当前网络类型 |
|
||
| `network.rssi` | 否 | 信号强度 |
|
||
| `firmware_version` | 是 | 当前固件版本 |
|
||
| `reported_config_revision` | 是 | 已实际应用的配置版本 |
|
||
| `recording_queue.pending_segments` | 是 | 待上传录音数 |
|
||
| `recording_queue.failed_segments` | 是 | 上传失败录音数 |
|
||
| `recording_queue.last_failure_code/at` | 否 | 最近稳定失败码和时间 |
|
||
| `rtc_credential_expires_at` | 否 | 当前 RTC Token 到期时间；声明续签能力时使用 |
|
||
| `last_error` | 否 | ≤80 的脱敏稳定错误码，不得传自由文本堆栈 |
|
||
| `command_results` | 是 | 最多 20 项；当前可为空数组 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"sequence_no": 1,
|
||
"device_time": "2026-08-27T06:31:15Z",
|
||
"monotonic_ms": 30820,
|
||
"conversation_status": "ACTIVE",
|
||
"rtc": {
|
||
"joined": true,
|
||
"uplink": true,
|
||
"downlink": true
|
||
},
|
||
"network": {
|
||
"type": "wifi",
|
||
"rssi": -50
|
||
},
|
||
"firmware_version": "1.2.0",
|
||
"reported_config_revision": 4,
|
||
"recording_queue": {
|
||
"pending_segments": 0,
|
||
"failed_segments": 0
|
||
},
|
||
"rtc_credential_expires_at": "2026-08-27T06:41:00Z",
|
||
"command_results": []
|
||
}
|
||
```
|
||
|
||
200 响应示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6HEARTBEAT",
|
||
"data": {
|
||
"lease_expires_at": "2026-08-27T06:32:05Z",
|
||
"actions": [
|
||
{ "type": "continue" }
|
||
],
|
||
"desired_config_revision": 4,
|
||
"commands": []
|
||
}
|
||
}
|
||
```
|
||
|
||
`actions[].type`：
|
||
|
||
- `continue`：继续通话；
|
||
- `stop`：尽快停止并离房；
|
||
- `stop_after_turn`：当前话轮完成后停止；
|
||
- `renew_rtc_credential`：响应同一动作的 `rtc` 字段包含新 RTCGrant，设备先替换内存凭证，再在下一次心跳报告新到期时间。
|
||
|
||
同序号或更小序号不会续租，也不会覆盖较新的设备状态。报告配置版本高于云端期望版本会返回 409。
|
||
|
||
主要状态码：200、400、401、404、409、503。
|
||
|
||
### 7.5 停止通话
|
||
|
||
`POST /device/v2/conversations/{id}/stop`
|
||
|
||
必须携带 `Idempotency-Key`。
|
||
|
||
请求字段：
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `reason` | 是 | 1～64 字符稳定原因码，字符集 `[A-Za-z0-9_.:-]` |
|
||
| `device_time` | 是 | RFC3339 |
|
||
| `last_heartbeat_sequence` | 是 | 最后成功心跳序号，可为 0 |
|
||
| `rtc_left` | 是 | 请求时是否已经退出 RTC |
|
||
| `recording.near_segments` | 是 | 本地近端录音分片数量 |
|
||
| `recording.far_segments` | 是 | 本地远端录音分片数量 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"reason": "user_hangup",
|
||
"device_time": "2026-08-27T06:35:00Z",
|
||
"last_heartbeat_sequence": 23,
|
||
"rtc_left": true,
|
||
"recording": {
|
||
"near_segments": 0,
|
||
"far_segments": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
202 响应示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6STOP",
|
||
"data": {
|
||
"conversation_id": "0829059e-4485-46b9-87ea-5a2fcefc6c35",
|
||
"status": "STOPPING",
|
||
"accepted_at": "2026-08-27T06:35:01Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
允许的响应状态为 `STOPPING`、`COMPLETED`、`FAILED` 或 `EXPIRED`。相同停止请求不会重复调用供应商 Stop。
|
||
|
||
主要状态码：202、400、401、404、409、503。
|
||
|
||
## 8. 设备遥测接口
|
||
|
||
### 8.1 批量上报遥测
|
||
|
||
`POST /device/v2/telemetry:batch`
|
||
|
||
必须携带 `Idempotency-Key`。每批 1～500 条，同一批内 `event_key` 和 `sequence_no` 分别唯一。
|
||
|
||
事件公共字段：
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `event_key` | 是 | 设备内稳定唯一键，1～255 字符 |
|
||
| `sequence_no` | 是 | 设备内严格正整数单调序号 |
|
||
| `occurred_at` | 是 | 事件发生时间 |
|
||
| `event_type` | 是 | `status`、`error`、`command_result` |
|
||
| `conversation_id` | 否 | 一旦填写，必须属于当前签名设备 |
|
||
| `status/error/command_result` | 条件必填 | 只允许携带与 `event_type` 同名的一个对象 |
|
||
|
||
状态事件：
|
||
|
||
```json
|
||
{
|
||
"event_key": "status.boot.000001",
|
||
"sequence_no": 1,
|
||
"occurred_at": "2026-08-27T06:30:00Z",
|
||
"event_type": "status",
|
||
"status": {
|
||
"firmware_version": "1.2.0",
|
||
"reported_config_revision": 4,
|
||
"network": { "type": "wifi", "rssi": -48 },
|
||
"rtc": { "joined": false, "uplink": false, "downlink": false },
|
||
"recording_queue": { "pending_segments": 0, "failed_segments": 0 }
|
||
}
|
||
}
|
||
```
|
||
|
||
错误事件：
|
||
|
||
```json
|
||
{
|
||
"event_key": "error.audio.000002",
|
||
"sequence_no": 2,
|
||
"occurred_at": "2026-08-27T06:30:10Z",
|
||
"event_type": "error",
|
||
"error": {
|
||
"code": "AUDIO_DEVICE_UNAVAILABLE",
|
||
"severity": "error"
|
||
}
|
||
}
|
||
```
|
||
|
||
命令结果事件：
|
||
|
||
```json
|
||
{
|
||
"event_key": "command.9e70.result",
|
||
"sequence_no": 3,
|
||
"occurred_at": "2026-08-27T06:30:20Z",
|
||
"event_type": "command_result",
|
||
"command_result": {
|
||
"command_id": "9e7006eb-6cd2-4e60-82ba-e24ba45158bd",
|
||
"status": "SUCCEEDED",
|
||
"result_summary": {
|
||
"result_code": "OK"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
完整请求：
|
||
|
||
```json
|
||
{
|
||
"events": [
|
||
{
|
||
"event_key": "status.boot.000001",
|
||
"sequence_no": 1,
|
||
"occurred_at": "2026-08-27T06:30:00Z",
|
||
"event_type": "status",
|
||
"status": {
|
||
"firmware_version": "1.2.0",
|
||
"reported_config_revision": 4,
|
||
"network": { "type": "wifi", "rssi": -48 },
|
||
"rtc": { "joined": false, "uplink": false, "downlink": false },
|
||
"recording_queue": { "pending_segments": 0, "failed_segments": 0 }
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
200 响应：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6TELEMETRY",
|
||
"data": {
|
||
"accepted_count": 1,
|
||
"duplicate_count": 0,
|
||
"desired_config_revision": 4,
|
||
"actions": [
|
||
{ "type": "pull_commands" }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
响应动作包括 `refresh_config`、`pull_commands` 和 `stop_conversation`。结果对象递归禁止出现 `secret`、`token`、`password`、`credential`、`private_key`、`api_key` 等敏感字段。
|
||
|
||
主要状态码：200、400、401、404、409、503。
|
||
|
||
## 9. 云端设备命令接口
|
||
|
||
### 9.1 拉取命令
|
||
|
||
`GET /device/v2/commands?limit=10`
|
||
|
||
`limit` 可选，范围 1～20，默认 10。只返回当前设备未过期、未终结的命令。
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6COMMANDS",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": "9e7006eb-6cd2-4e60-82ba-e24ba45158bd",
|
||
"type": "diagnostics",
|
||
"payload": {
|
||
"scope": ["audio", "network", "storage"]
|
||
},
|
||
"status": "DELIVERED",
|
||
"expires_at": "2026-08-27T06:40:00Z",
|
||
"delivery_attempts": 1,
|
||
"created_at": "2026-08-27T06:35:00Z"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
命令类型：
|
||
|
||
| 类型 | 用途 |
|
||
|---|---|
|
||
| `apply_config` | 拉取并应用指定配置 |
|
||
| `reboot` | 受控重启设备 |
|
||
| `diagnostics` | 执行音频、网络、存储等有限诊断 |
|
||
| `firmware_update` | 下载、验签、安装并确认固件 |
|
||
|
||
命令主状态机：
|
||
|
||
```text
|
||
QUEUED → DELIVERED → ACKNOWLEDGED → SUCCEEDED / FAILED
|
||
└────────→ EXPIRED / CANCELLED
|
||
```
|
||
|
||
设备进程重启后可以重新拉取 `ACKNOWLEDGED` 但未终结的命令，用于恢复执行。
|
||
|
||
主要状态码：200、401、503。
|
||
|
||
### 9.2 命令执行回执
|
||
|
||
`POST /device/v2/commands/{id}/ack`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"status": "ACKNOWLEDGED",
|
||
"result_summary": {
|
||
"phase": "running",
|
||
"progress_percent": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
`status` 只允许 `ACKNOWLEDGED`、`SUCCEEDED`、`FAILED`。同阶段或相同终态重复提交保持幂等，禁止状态回退。
|
||
|
||
固件命令可用的阶段包括：
|
||
|
||
- `downloading`
|
||
- `installing`
|
||
- `staging`
|
||
- `reboot_pending`
|
||
- `boot_verifying`
|
||
- `confirmed`
|
||
- `rolled_back`
|
||
|
||
成功结果应包含 `installed_version`；A/B 启动健康失败并自动回退时应提交：
|
||
|
||
```json
|
||
{
|
||
"status": "FAILED",
|
||
"result_summary": {
|
||
"phase": "rolled_back",
|
||
"progress_percent": 95,
|
||
"result_code": "BOOT_HEALTH_FAILED_ROLLED_BACK",
|
||
"rollback_applied": true,
|
||
"active_slot": "A",
|
||
"failed_slot": "B",
|
||
"rollback_version": "1.1.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
主要状态码：200、400、401、409。
|
||
|
||
## 10. 固件下载接口
|
||
|
||
### 10.1 获取私有固件地址
|
||
|
||
`GET /device/v2/firmware-releases/{id}/download`
|
||
|
||
只有属于当前灰度批次且版本仍可用的设备能够取得地址。响应签发约 5 分钟有效的私有下载地址，设备必须：
|
||
|
||
1. 只接受云端固定固件下载接口返回的地址；
|
||
2. 限制下载对象大小为 1 字节～256 MiB；
|
||
3. 下载后校验命令清单中的小写 SHA-256；
|
||
4. 使用安全区预置的 Ed25519 公钥验证 `firmware-manifest-v1`；
|
||
5. 校验型号、硬件版本、制品大小、版本和发布编号；
|
||
6. 全部校验通过后才允许写入非活动分区或执行安装。
|
||
|
||
不要信任命令 `payload` 临时携带的公钥，不要把下载地址写入持久日志。
|
||
|
||
主要状态码：200、401、403。
|
||
|
||
## 11. 通话终稿补传接口
|
||
|
||
### 11.1 批量补传最终话轮
|
||
|
||
`POST /device/v2/conversations/{id}/turns:batch`
|
||
|
||
必须携带 `Idempotency-Key`。用于供应商最终转写缺失或不完整时补交设备侧终稿，每批 1～500 条。
|
||
|
||
话轮字段：
|
||
|
||
| 字段 | 必填 | 限制 |
|
||
|---|---|---|
|
||
| `turn_key` | 是 | 1～255，通话内稳定唯一 |
|
||
| `sequence_no` | 是 | 正整数，批内唯一 |
|
||
| `speaker` | 是 | `subject` 或 `agent` |
|
||
| `start_at` | 是 | RFC3339 |
|
||
| `end_at` | 是 | RFC3339，不早于 `start_at` |
|
||
| `final_text` | 是 | 1～20000 字符 |
|
||
| `interrupted` | 是 | 是否被打断 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"turns": [
|
||
{
|
||
"turn_key": "device-turn-0001",
|
||
"sequence_no": 1,
|
||
"speaker": "subject",
|
||
"start_at": "2026-08-27T06:32:00Z",
|
||
"end_at": "2026-08-27T06:32:03Z",
|
||
"final_text": "今天天气怎么样？",
|
||
"interrupted": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"request_id": "01J6TURNS",
|
||
"data": {
|
||
"conversation_id": "0829059e-4485-46b9-87ea-5a2fcefc6c35",
|
||
"accepted_count": 1,
|
||
"duplicate_count": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
相同终稿计入重复数；相同 `turn_key` 或 `sequence_no` 对应不同内容时整批返回 409 `TRANSCRIPT_TURN_CONFLICT`，设备不得覆盖云端内容。
|
||
|
||
主要状态码：200、400、401、403、404、409、503。
|
||
|
||
## 12. 双轨录音上传接口
|
||
|
||
录音上传只在创建响应满足以下条件时允许：
|
||
|
||
```text
|
||
privacy.retention_mode = transcript_and_audio
|
||
privacy.upload_allowed = true
|
||
对应 track 的 record_near / record_far = true
|
||
```
|
||
|
||
当前编码基线只接受可解析的 WAV PCM 16 位：
|
||
|
||
- `codec=wav_pcm_s16le`
|
||
- `content_type=audio/wav`
|
||
- 单片时长 1～600000 ms
|
||
- 单片大小 1～67108864 字节
|
||
- 每批最多 1000 片
|
||
|
||
### 12.1 声明上传批次
|
||
|
||
`POST /device/v2/conversations/{id}/upload-batches`
|
||
|
||
必须携带 `Idempotency-Key`。
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"segments": [
|
||
{
|
||
"track": "near",
|
||
"sequence_no": 0,
|
||
"codec": "wav_pcm_s16le",
|
||
"content_type": "audio/wav",
|
||
"duration_ms": 10000,
|
||
"expected_size": 320044,
|
||
"expected_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
201 响应的 `data` 为上传批次：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `id` | 批次 UUID |
|
||
| `conversation_id` | 所属通话 |
|
||
| `status` | `PENDING/UPLOADING/VERIFYING/COMPLETED/FAILED/EXPIRED` |
|
||
| `segment_count` | 分片数 |
|
||
| `expected_total_size` | 声明总字节数 |
|
||
| `verified_count/rejected_count` | 校验成功/拒绝数量 |
|
||
| `verification_attempts` | 校验尝试次数 |
|
||
| `last_error_code` | 批次稳定失败码 |
|
||
| `expires_at` | 批次到期时间 |
|
||
| `segments` | 分片结果数组 |
|
||
|
||
新分片包含短期 `upload_url` 和 `upload_until`。设备使用 HTTP PUT 将该分片原始字节直接上传，不得把多个分片或其他内容写入同一 URL。
|
||
|
||
主要状态码：201、400、401、403、409。
|
||
|
||
### 12.2 声明批次上传完成
|
||
|
||
`POST /device/v2/upload-batches/{id}/complete`
|
||
|
||
请求无 JSON 正文，但仍需发送空正文 SHA-256。平台返回 202，并把批次置为 `VERIFYING` 或返回已经完成的结果。重复提交不会重复创建校验任务。
|
||
|
||
主要状态码：202、401、404、409、410。
|
||
|
||
### 12.3 查询批次校验结果
|
||
|
||
`GET /device/v2/upload-batches/{id}`
|
||
|
||
分片状态：
|
||
|
||
```text
|
||
DECLARED → AUTHORIZED → UPLOADED → VERIFYING → VERIFIED / REJECTED
|
||
```
|
||
|
||
关键字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `id` | 分片 UUID |
|
||
| `track` | `near` 或 `far` |
|
||
| `sequence_no` | 轨道内序号 |
|
||
| `expected_size/digest` | 声明大小和 SHA-256 |
|
||
| `status` | 当前分片状态 |
|
||
| `last_error_code` | 校验失败稳定码 |
|
||
| `verified_at` | 校验成功时间 |
|
||
| `local_delete_after` | 只有 VERIFIED 才返回；此时间之后才能删除本地密文 |
|
||
| `local_delete_status` | 最近一次本地删除回执 `DELETED/FAILED` |
|
||
|
||
建议每 1～2 秒轮询，达到批次 `expires_at` 或本地等待上限后停止。对象暂时不可见时平台可能保持 `VERIFYING` 并后台重试。
|
||
|
||
主要状态码：200、401、404。
|
||
|
||
### 12.4 回报本地密文删除结果
|
||
|
||
`POST /device/v2/media-segments/{id}/local-delete-ack`
|
||
|
||
只能在 `local_delete_after` 之后删除设备本地加密录音副本并回报。
|
||
|
||
成功：
|
||
|
||
```json
|
||
{
|
||
"status": "DELETED"
|
||
}
|
||
```
|
||
|
||
失败：
|
||
|
||
```json
|
||
{
|
||
"status": "FAILED",
|
||
"error_code": "LOCAL_STORAGE_DELETE_FAILED"
|
||
}
|
||
```
|
||
|
||
- `FAILED` 时 `error_code` 必填；`DELETED` 时禁止携带。
|
||
- 过早提交成功回执返回 409。
|
||
- `DELETED` 重复回报幂等。
|
||
- 此回执只代表设备副本已删除，不删除云端已验证对象。
|
||
|
||
主要状态码：200、400、401、404、409。
|
||
|
||
## 13. 业务流程
|
||
|
||
### 13.1 设备开机与配置同步
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant D as 设备
|
||
participant A as 云端API
|
||
D->>A: GET /bootstrap + HMAC
|
||
A-->>D: server_time、状态、绑定、版本门禁
|
||
alt 固件不兼容
|
||
D->>D: 进入升级流程，禁止新通话
|
||
else 固件兼容
|
||
D->>A: GET /config + If-None-Match
|
||
A-->>D: 200 新配置或 304 未变化
|
||
D->>D: 校验并原子应用配置
|
||
D->>A: POST /telemetry:batch 上报实际版本
|
||
end
|
||
```
|
||
|
||
### 13.2 双向语音通话
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant D as 设备
|
||
participant A as 云端API
|
||
participant R as 火山RTC
|
||
participant W as Worker
|
||
participant B as 豆包智能体
|
||
D->>A: POST /conversations
|
||
A-->>D: conversation_id + room/token
|
||
D->>R: 加入房间并发布麦克风
|
||
D->>A: POST /conversations/{id}/activate
|
||
A-->>D: 202 STARTING_AGENT
|
||
A->>W: agent_start_requested
|
||
W->>B: StartVoiceChat
|
||
B->>R: 智能体加入同一房间
|
||
loop 有限轮询
|
||
D->>A: GET /conversations/{id}
|
||
A-->>D: wait / continue / leave_room
|
||
end
|
||
loop 通话中
|
||
D->>A: POST /heartbeat
|
||
A-->>D: continue/stop/renew + config/commands
|
||
D->>R: 上行麦克风音频
|
||
R-->>D: 下行豆包语音
|
||
end
|
||
D->>A: POST /stop
|
||
A->>W: agent_stop_requested
|
||
W->>B: StopVoiceChat
|
||
D->>R: 退出房间
|
||
```
|
||
|
||
### 13.3 设备命令
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant D as 设备
|
||
participant A as 云端API
|
||
D->>A: GET /commands
|
||
A-->>D: 待执行命令
|
||
D->>A: POST /commands/{id}/ack ACKNOWLEDGED
|
||
D->>D: 执行命令并保存本地状态
|
||
D->>A: POST /commands/{id}/ack SUCCEEDED/FAILED
|
||
A-->>D: 最终命令状态
|
||
```
|
||
|
||
### 13.4 录音上传
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant D as 设备
|
||
participant A as 云端API
|
||
participant O as 对象存储
|
||
participant W as Worker
|
||
D->>A: POST /conversations/{id}/upload-batches
|
||
A-->>D: 分片ID + 短期PUT地址
|
||
D->>O: PUT 分片字节
|
||
D->>A: POST /upload-batches/{id}/complete
|
||
A->>W: media.verify_requested
|
||
W->>O: 校验大小、摘要、WAV与时长
|
||
loop 查询结果
|
||
D->>A: GET /upload-batches/{id}
|
||
A-->>D: VERIFYING/VERIFIED/REJECTED
|
||
end
|
||
D->>D: 到 local_delete_after 后删除本地密文
|
||
D->>A: POST /media-segments/{id}/local-delete-ack
|
||
```
|
||
|
||
## 14. 错误码与重试策略
|
||
|
||
| HTTP | 错误码 | 是否自动重试 | 处理建议 |
|
||
|---:|---|---|---|
|
||
| 400 | `VALIDATION_FAILED` | 否 | 修正字段，重新生成随机数和签名 |
|
||
| 401 | `DEVICE_AUTHENTICATION_FAILED` | 否 | 检查设备登记、时钟、摘要、签名或重放 |
|
||
| 403 | `CONSENT_REQUIRED` | 否 | 等待用户有效授权 |
|
||
| 403 | `TRANSCRIPT_STORAGE_NOT_ALLOWED` | 否 | 停止补传，不能绕过留存策略 |
|
||
| 404 | `TELEMETRY_CONVERSATION_NOT_FOUND` | 否 | 删除错误通话引用 |
|
||
| 409 | `DEVICE_NOT_BOUND` | 否 | 完成设备绑定 |
|
||
| 409 | `CONVERSATION_ALREADY_ACTIVE` | 否 | 恢复或查询已有通话 |
|
||
| 409 | `IDEMPOTENCY_KEY_REUSED` | 否 | 不同正文必须使用新业务键 |
|
||
| 409 | `ROOM_ALLOCATION_EXPIRED` | 否 | 重新创建通话和房间 |
|
||
| 409 | `RTC_ALLOCATION_MISMATCH` | 否 | 丢弃本地房间资料并重新创建 |
|
||
| 409 | `CONFIG_VERSION_CONFLICT` | 否 | 重新获取设备配置 |
|
||
| 409 | `CONVERSATION_STATE_CONFLICT` | 否 | 查询权威状态，禁止强制覆盖 |
|
||
| 409 | `TRANSCRIPT_TURN_CONFLICT` | 否 | 保存冲突明细，转人工对账 |
|
||
| 409 | `TELEMETRY_EVENT_CONFLICT` | 否 | 停止推进确认点，检查事件键和序号 |
|
||
| 409 | `DEVICE_COMMAND_STATE_CONFLICT` | 否 | 重新拉取命令，禁止状态回退 |
|
||
| 422 | `AGENT_CONTEXT_PREPARATION_FAILED` | 否 | 等待修正长者背景资料后新建通话 |
|
||
| 426 | `FIRMWARE_UPDATE_REQUIRED` | 否 | 执行固件升级 |
|
||
| 429 | `USAGE_QUOTA_EXCEEDED` | 延迟/人工 | 提示额度或并发限制 |
|
||
| 503 | `DEVICE_AUTHENTICATION_UNAVAILABLE` | 是 | 指数退避，使用新随机数重试 |
|
||
| 503 | `DEVICE_CONFIG_UNAVAILABLE` | 是 | 保留旧配置并退避重试 |
|
||
| 503 | `RUNTIME_CONFIG_UNAVAILABLE` | 有条件 | 停止创建通话，等待平台恢复路由 |
|
||
| 503 | `TRANSCRIPT_BATCH_UNAVAILABLE` | 是 | 原正文、原幂等键，新 HMAC 头重试 |
|
||
| 503 | `DEVICE_TELEMETRY_UNAVAILABLE` | 是 | 保留事件队列，原正文和幂等键重试 |
|
||
| 503 | `CONVERSATION_HEARTBEAT_UNAVAILABLE` | 是 | 同序号、新 HMAC 头退避重试 |
|
||
| 503 | `CONVERSATION_STOP_UNAVAILABLE` | 是 | 原正文和幂等键、新 HMAC 头重试 |
|
||
|
||
建议重试参数：
|
||
|
||
- 初始等待 500 ms；
|
||
- 指数退避 0.5、1、2、4、8、15、30 秒；
|
||
- 加入 0～20% 随机抖动；
|
||
- 单次业务的最大重试时间受 RTC 房间、上传批次或命令过期时间约束；
|
||
- `retryable=false` 时不得自动循环重试。
|
||
|
||
## 15. 与设备相关但不由终端直接调用的管理接口
|
||
|
||
下列接口由 SaaS 管理后台或运营后台调用，使用 OIDC 用户身份和权限控制，不使用设备 HMAC：
|
||
|
||
| 方法 | 路径 | 用途 |
|
||
|---|---|---|
|
||
| POST | `/api/v1/device-claims` | 家庭成员使用设备屏幕显示的绑定码绑定设备 |
|
||
| GET | `/api/v1/devices` | 查询当前家庭可管理设备 |
|
||
| GET | `/api/v1/devices/{id}` | 查询设备详情 |
|
||
| GET | `/api/v1/devices/{id}/presence` | 查询设备在线和当前通话状态 |
|
||
| GET | `/api/v1/devices/{id}/twin` | 查询设备期望/实际配置影子 |
|
||
| PATCH | `/api/v1/devices/{id}/twin` | 修改期望配置，需 `If-Match` |
|
||
| GET | `/api/v1/devices/{id}/commands` | 查询设备命令记录 |
|
||
| POST | `/api/v1/devices/{id}/commands` | 创建配置、重启、诊断或固件命令 |
|
||
| GET/POST | `/api/v1/households/{id}/firmware-signing-keys` | 管理固件 Ed25519 信任根 |
|
||
| POST | `/api/v1/households/{id}/firmware-signing-keys/revoke` | 吊销签名公钥 |
|
||
| GET/POST | `/api/v1/households/{id}/firmware-releases` | 查询或创建固件版本 |
|
||
| POST | `/api/v1/firmware-releases/{id}/upload-session` | 创建固件上传会话 |
|
||
| POST | `/api/v1/firmware-releases/{id}/finalize` | 完成固件制品校验与发布 |
|
||
| GET | `/api/v1/firmware-releases/{id}/impact` | 查询版本、设备和命令影响 |
|
||
| POST | `/api/v1/firmware-releases/{id}/pause` | 暂停版本 |
|
||
| POST | `/api/v1/firmware-releases/{id}/resume` | 恢复版本 |
|
||
| POST | `/api/v1/firmware-releases/{id}/retire` | 退役版本 |
|
||
| GET/POST | `/api/v1/households/{id}/firmware-rollouts` | 查询或创建灰度批次 |
|
||
| GET | `/api/v1/firmware-rollouts/{id}` | 查询灰度批次状态 |
|
||
| POST | `/api/v1/firmware-rollouts/{id}/pause` | 暂停灰度 |
|
||
| POST | `/api/v1/firmware-rollouts/{id}/rollback` | 回滚到已验证版本 |
|
||
|
||
## 16. 设备实现检查清单
|
||
|
||
### 16.1 身份与安全
|
||
|
||
- [ ] 每台设备使用独立密钥，密钥位于安全存储区。
|
||
- [ ] 每次请求生成新 Nonce，网络重试也不复用。
|
||
- [ ] 对实际发送的原始正文字节计算 SHA-256。
|
||
- [ ] 签名 URI 与实际请求路径、查询串完全一致。
|
||
- [ ] 不记录设备密钥、HMAC 签名、RTC Token、上传地址和下载地址。
|
||
- [ ] 生产环境强制 HTTPS 并校验证书。
|
||
|
||
### 16.2 离线与幂等
|
||
|
||
- [ ] 关键请求正文和幂等键在成功确认前持久化。
|
||
- [ ] 重试保留原正文与 Idempotency-Key，但更新 HMAC 请求头。
|
||
- [ ] 遥测事件键和序号跨进程重启保持单调或稳定唯一。
|
||
- [ ] 命令 `ACKNOWLEDGED` 后保存本地执行进度，重启可恢复。
|
||
- [ ] 保留最近一次有效配置，配置拉取失败不清空。
|
||
|
||
### 16.3 实时语音
|
||
|
||
- [ ] 创建通话后先加入 RTC，再调用 activate。
|
||
- [ ] 识别 `wait/continue/leave_room`，失败时及时离房。
|
||
- [ ] 按服务器心跳间隔发送递增序号。
|
||
- [ ] 支持续签时只在内存替换 RTC Token。
|
||
- [ ] 收到 `stop` 或终态后停止采集、退出 RTC 并调用停止接口。
|
||
- [ ] 不根据 `engine_mode` 改变设备媒体行为。
|
||
|
||
### 16.4 录音与隐私
|
||
|
||
- [ ] 只有云端明确允许时才录制和上传对应轨道。
|
||
- [ ] 上传前计算真实字节大小和 SHA-256。
|
||
- [ ] 每个短期 URL 只 PUT 对应单一对象。
|
||
- [ ] 只有校验为 VERIFIED 且到达 `local_delete_after` 后才删除本地密文。
|
||
- [ ] 删除失败上报稳定错误码，不上传包含个人信息的自由文本堆栈。
|
||
|
||
## 17. 契约与联调依据
|
||
|
||
- 权威机器可读契约：`openapi/openapi.yaml`
|
||
- 设备接入实现说明：`docs/device-integration.md`
|
||
- 设备命令可靠下发：`docs/device-commands.md`
|
||
- 录音上传和访问：`docs/media-upload-and-access.md`
|
||
- 设备 API 兼容策略：`docs/device-api-compatibility.md`
|
||
- A/B 固件协议：`docs/device-firmware-ab-protocol.md`
|
||
|
||
若本文档与当前 OpenAPI 发生字段差异，应以同一构建版本中的 `openapi/openapi.yaml` 为准，并同步修订本文档；不得根据固件版本、设备型号或 User-Agent 猜测接口字段。
|