story/docs/设备终端接口文档.md

# 数据采集终端—云端系统设备接口文档

> 文档版本：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 猜测接口字段。