story/docs/device-api-reference.md

# 设备接口文档

> 适用范围：平台设备管理、EchoEar/ESP32-S3 设备接入、火山引擎硬件对话智能体。  
> 契约基线：当前工作区实际路由、处理器与 `openapi/openapi.yaml`，更新日期 2026-09-05。  
> 生产 API：`https://121.41.46.238`（正式域名启用后只替换 Base URL，不改变路径）。

## 1. 接入模型

设备同时使用两套彼此独立的身份：

| 身份/密钥 | 用途 | 生成与保存位置 | 是否下发设备 |
|---|---|---|---|
| 平台 `device_id` | 标识平台登记设备 | 平台生成；设备保存公开编号 | 是 |
| 平台 Device Secret | 调用 `/device/*` 时做 HMAC 鉴权 | 平台逐设备生成；平台加密保存，设备安全区保存 | 是，只在登记/轮换时显示一次 |
| 火山 `instance_id` / `product_key` | 标识火山实例和产品 | 平台配置 | 可随预配响应返回，非秘密 |
| 火山 Product Secret | 调用 DynamicRegister 的产品级秘密 | 只保存在平台 KMS/Secret | **否** |
| 火山 `device_name` / `device_secret` | 设备直连火山时使用的一机一密 | 平台代设备动态注册；平台加密保存，设备安全区保存 | 是，只返回给已认证的对应设备 |
| Bot ID | 选择硬件对话智能体 | 平台按设备绑定 | 会话响应返回，非秘密 |

核心原则：设备固件不内置 Product Secret。设备先用平台 Device Secret 认证，由平台代设备调用火山动态注册，再把该设备专属的火山 Device Secret 返回给设备。

### 1.1 火山 License 的准确含义

火山硬件对话智能体的 License 是产品侧可用额度。平台调用 DynamicRegister 时，火山自动消耗当前产品的一份有效额度并返回一机一密；设备不接收一段可安装的 License 明文，也不需要向平台提交 License 安装回执。

因此，当前有效契约中：

- 没有 `/device/v3/hardware-agent-license:ack` 路由；
- 没有设备端 `license` 字段；
- 没有 `AVAILABLE → ALLOCATED → ACTIVE` 的设备 License 安装状态机；
- 平台可以维护额度监控或影子账本，但不能用它替代火山的真实额度，也不能阻断已正确取得一机一密的设备。

火山返回额度耗尽、过期等错误时，平台统一转换为 `HARDWARE_AGENT_PROVISIONING_FAILED`，同时通过内部日志和请求编号保留供应商错误供运维定位。

## 2. 通用响应格式

成功响应：

```json
{
  "request_id": "req-...",
  "data": {}
}
```

失败响应：

```json
{
  "request_id": "req-...",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "请求参数不正确",
    "retryable": false,
    "field_errors": [],
    "details": {}
  }
}
```

排障时应记录 `request_id`、HTTP 状态码和稳定错误码，不记录任何 Secret、Token、完整人设或完整对话正文。

## 3. 设备 HMAC 鉴权

所有 `/device/v2/*` 和 `/device/v3/*` 请求必须携带：

| 请求头 | 说明 |
|---|---|
| `X-Device-Id` | 平台设备公开 UUID |
| `X-Device-Timestamp` | RFC3339 UTC 时间，默认允许前后 5 分钟 |
| `X-Device-Nonce` | 本次请求唯一的 16—128 字符随机值 |
| `X-Device-Content-SHA256` | 原始 HTTP 正文的 SHA-256 小写十六进制；空正文也要计算 |
| `X-Device-Signature` | HMAC-SHA256 结果的无填充 Base64URL |

签名原文必须逐字使用实际请求 URI（含查询字符串）：

```text
UPPERCASE_HTTP_METHOD
REQUEST_URI_WITH_EXACT_QUERY_STRING
X-Device-Timestamp原值
X-Device-Nonce原值
X-Device-Content-SHA256原值
```

伪代码：

```text
bodyHash = hexLower(SHA256(rawBody))
canonical = methodUpper + "\n" + requestURI + "\n" + timestamp + "\n" + nonce + "\n" + bodyHash
signature = base64UrlNoPadding(HMAC_SHA256(platformDeviceSecret, canonical))
```

注意事项：

- JSON 签名后不得重新格式化或改变字段顺序；服务端校验的是收到的原始字节。
- 每次网络重试都生成新的 `timestamp`、`nonce` 和签名。
- 需要幂等的业务请求保留原 `Idempotency-Key` 和原正文。
- 时间未同步时先通过安全时间源校时；不能关闭时间窗或重放保护。

## 4. 设备激活状态机

主流程：

```text
FACTORY → CLAIMABLE → BOUND → PROVISIONING → ACTIVE
                                              │
                                              ├─→ LOST
                                              └─→ REVOKED
```

| 状态 | 含义 | 允许的设备操作 |
|---|---|---|
| `FACTORY` | 只有出厂身份，等待质检放行 | 不允许设备 API 鉴权 |
| `CLAIMABLE` | 可生成/消费绑定码 | 启动、配置、命令、遥测；不能通话 |
| `BOUND` | 已绑定家庭和使用人 | 可申请火山一机一密；不能创建会话 |
| `PROVISIONING` | 正在注册或恢复火山运行凭据 | 可重复预配；不能创建会话 |
| `ACTIVE` | 平台身份、绑定和运行凭据就绪 | 全部设备接口 |
| `LOST` | 设备挂失 | 设备鉴权和新会话被拒绝 |
| `REVOKED` | 永久吊销 | 终态，不可恢复 |

代码允许的恢复/解绑边包括：`BOUND → CLAIMABLE`、`PROVISIONING → BOUND`、`ACTIVE → CLAIMABLE/PROVISIONING/LOST`、`LOST → CLAIMABLE/ACTIVE`；任意非 `REVOKED` 状态均可受控转为 `REVOKED`。状态变更必须由平台业务或运维接口执行，设备不能自行声明已激活。

每次变更增加 `activation_revision` 并保存审计历史。进入 `ACTIVE` 时，硬件智能体设备必须已经绑定且存在有效火山一机一密。

## 5. 首次激活完整流程

1. 运维调用 `POST /api/v1/ops/devices` 登记设备，取得一次性平台 Device Secret。
2. 工厂烧录/安全注入 `device_id`、平台 Device Secret、API Base URL 和稳定 `hardware_id`；不得烧录 Product Secret。
3. 运维将设备从 `FACTORY` 放行到 `CLAIMABLE`，并生成绑定码。
4. 用户 App/Web 调用 `POST /api/v1/device-claims` 消费绑定码，平台把设备变为 `BOUND`。
5. 设备使用平台 HMAC 调用 `POST /device/v3/hardware-agent-credentials:provision`。
6. 平台把状态推进到 `PROVISIONING`，自动建立产品默认 Bot/传输/最低 SDK 绑定，再使用服务端 Product Secret 调用火山 DynamicRegister。
7. 火山消耗产品 License 额度并返回该 `device_name` 对应的 `device_secret`。
8. 平台加密保存火山 Device Secret，并通过 `no-store` 响应返回给同一设备，然后自动完成到 `ACTIVE` 的迁移。
9. 设备把火山一机一密写入 NVS 加密分区/安全芯片；以后重复预配会返回已保存的同一凭据，不重复注册。
10. 每次用户发起聊天时，设备先创建平台硬件智能体会话，注入本次人设和上下文后，再直连火山。

## 6. 设备端接口总览

### 6.1 启动、配置、命令和固件（v2 公共能力）

| 方法 | 路径 | 状态要求 | 幂等键 | 作用 |
|---|---|---|---|---|
| `GET` | `/device/v2/bootstrap` | `CLAIMABLE/BOUND/PROVISIONING/ACTIVE` | 否 | 上报启动版本并取得绑定和兼容性 |
| `GET` | `/device/v2/config` | 同上 | 否 | 拉取期望配置；支持 `If-None-Match` |
| `GET` | `/device/v2/commands` | 同上 | 否 | 拉取待执行命令 |
| `POST` | `/device/v2/commands/{id}/ack` | 同上 | 否 | 上报命令阶段或终态 |
| `POST` | `/device/v2/telemetry:batch` | 同上 | 是 | 批量上报设备遥测 |
| `GET` | `/device/v2/firmware-releases/{id}/download` | 同上 | 否 | 下载受控固件制品 |

`bootstrap` 示例：

```http
GET /device/v2/bootstrap?firmware_version=1.0.0&board_rev=echoear-v1&rtc_sdk_version=1.0.0&codec=pcm_s16le&sample_rate=16000&device_time=2026-09-03T08%3A00%3A00Z&network=wifi
```

配置拉取建议：首次不带 `If-None-Match`；保存响应 `ETag`，后续携带该值。HTTP `304` 表示继续使用本地有效配置。

### 6.2 旧 RTC 通话（v2，仅兼容旧设备）

| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/device/v2/conversations` | 创建旧 RTC 通话 |
| `POST` | `/device/v2/conversations/{id}/activate` | 入房成功后激活供应商任务 |
| `GET` | `/device/v2/conversations/{id}` | 查询通话权威状态 |
| `POST` | `/device/v2/conversations/{id}/heartbeat` | 通话心跳 |
| `POST` | `/device/v2/conversations/{id}/stop` | 停止通话 |
| `POST` | `/device/v2/conversations/{id}/turns:batch` | 补传最终字幕 |

新 EchoEar 固件的 `voice_runtime=volc_hardware_agent` 时不得调用这组 RTC 创建/激活接口。

### 6.3 录音上传（v2 公共媒体能力）

| 方法 | 路径 | 作用 |
|---|---|---|
| `POST` | `/device/v2/conversations/{id}/upload-batches` | 创建分片上传批次 |
| `GET` | `/device/v2/upload-batches/{id}` | 查询上传校验状态 |
| `POST` | `/device/v2/upload-batches/{id}/complete` | 通知平台分片已上传 |
| `POST` | `/device/v2/media-segments/{id}/local-delete-ack` | 回报本地密文已删除 |

只有 `ACTIVE` 设备且本次隐私策略允许时才能使用；没有录音授权不得采集、缓存或上传 PCM。

## 7. 火山硬件智能体接口（v3）

### 7.1 申请火山一机一密

```http
POST /device/v3/hardware-agent-credentials:provision
Idempotency-Key: 2ee3b675-59c0-4d93-a189-6db7f8db3750
Cache-Control: no-store
Content-Type: application/json
```

状态要求：`BOUND`、`PROVISIONING` 或 `ACTIVE`。

请求：

```json
{
  "hardware_id": "echoear-b43a451634a8"
}
```

`hardware_id` 必须来自稳定硬件身份（如 eFuse/Chip ID 的规范化值），设备重启、升级和恢复出厂后保持不变。

成功响应：

```json
{
  "request_id": "req-...",
  "data": {
    "instance_id": "<instance-id>",
    "product_key": "<product-key>",
    "device_name": "echoear-...",
    "hardware_id": "echoear-b43a451634a8",
    "device_secret": "<volc-device-secret>",
    "credential_ref": "<non-secret-ref>",
    "credential_version": 1,
    "credential_source": "platform_dynamic_registration",
    "issued_at": "2026-09-03T08:00:00Z"
  }
}
```

安全要求：

- 响应带 `Cache-Control: no-store` 和 `Pragma: no-cache`。
- `device_secret` 只写入设备安全存储，不进入普通配置文件、串口日志、崩溃转储或平台遥测。
- `credential_source=platform_stored` 表示幂等返回平台已保存的凭据，不代表重新消耗 License。
- `hardware_id` 与已注册记录不一致时返回冲突，不允许覆盖原凭据。

常见错误：

| HTTP | 错误码 | 处理 |
|---|---|---|
| `400` | `VALIDATION_FAILED` | 修正 `hardware_id` 或幂等键 |
| `409` | `HARDWARE_AGENT_BINDING_REQUIRED` | 先在平台绑定 Bot/产品配置 |
| `409` | `HARDWARE_AGENT_PRODUCT_MISMATCH` | 运维核对实例、产品和设备绑定 |
| `409` | `HARDWARE_AGENT_HARDWARE_MISMATCH` | 停止自动重试，核对硬件身份 |
| `409` | `DEVICE_ACTIVATION_REQUIRED` | 先完成用户绑定，进入 `BOUND` |
| `503` | `HARDWARE_AGENT_PROVISIONING_UNAVAILABLE` | 平台未配置动态注册；联系运维 |
| `503` | `HARDWARE_AGENT_PROVISIONING_FAILED` | 使用原幂等键、原正文和新签名退避重试；由 `request_id` 查火山原始错误 |

### 7.2 创建本次硬件智能体会话

```http
POST /device/v3/agent-sessions
Idempotency-Key: d7f08e7a-9e1d-455f-b8ec-a745a34d8790
Content-Type: application/json
```

状态要求：仅 `ACTIVE`。每次聊天创建一个新会话，不复用上一通响应。

请求示例：

```json
{
  "device_time": "2026-09-03T08:05:00Z",
  "monotonic_ms": 123456,
  "capabilities": {
    "hardware_agent": true,
    "sdk_version": "1.0.0-echoear-platform.1",
    "transports": ["low_load"],
    "input_audio_format": "pcm_s16le_16000_mono",
    "output_audio_format": "pcm_s16le_16000_mono",
    "server_event_callback": false,
    "transcript_upload": true,
    "dynamic_session_config": true,
    "credential_rotation": true,
    "near_pcm_recording": false,
    "far_pcm_recording": false
  },
  "network": {
    "type": "wifi",
    "rssi": -52
  },
  "requested_goal": "open_conversation",
  "config_revision": 1
}
```

约束：

- `transports` 只能包含 `low_load`、`high_quality`，至少一个。
- `transcript_upload`、`dynamic_session_config`、`credential_rotation` 必须为 `true`。
- EchoEar 当前使用 `low_load`；`server_event_callback=false` 时设备事件和最终字幕上传是权威回流。
- `config_revision` 必须使用最近一次 `/device/v2/config` 返回的版本。

成功响应核心字段：

```json
{
  "request_id": "req-...",
  "data": {
    "conversation_id": "<uuid>",
    "status": "SESSION_READY",
    "runtime_type": "volc_hardware_agent",
    "runtime": {
      "provider": "volcengine",
      "bot_id": "<bot-id>",
      "transport": "low_load",
      "provider_session_ref": "<provider-session-ref>",
      "session_nonce": "<memory-only-secret>",
      "config_digest": "<sha256-hex>",
      "wait_for_session_update": true
    },
    "session_config": {
      "dialog_id": "<uuid>",
      "system_prompt": "<本次冻结的人设提示>",
      "persona_tone": "<语气>",
      "authorized_context": "<已授权背景/近期摘要/长期记忆>",
      "prompt_bundle_version": "<version>"
    },
    "privacy": {
      "retention_mode": "transcript_only",
      "record_near": false,
      "record_far": false,
      "upload_allowed": false
    },
    "session": {
      "engine_mode": "volc_hardware_agent",
      "heartbeat_interval_sec": 10,
      "allocation_expires_at": "2026-09-03T08:10:00Z"
    }
  }
}
```

设备处理顺序：

1. 只在运行内存保存 `session_nonce`。
2. 使用预配取得的一机一密连接响应指定的 Bot 和传输模式。
3. 以 `dialog_id` 作为本次业务对话标识。
4. 在开启麦克风前通过 SDK 动态配置或 WebSocket `session.update` 注入 `system_prompt`、`persona_tone` 和 `authorized_context`。
5. 收到火山配置已应用确认后，再上报 `session_started`。

`tool_scope_token` 如存在也只能保存在运行内存，并且仅用于响应指定的 `tool_url` 和本次会话。

### 7.3 上报会话事件

```http
POST /device/v3/agent-sessions/{conversation_id}/events
Content-Type: application/json
```

开始事件：

```json
{
  "event_id": "evt-start-0001",
  "sequence_no": 1,
  "event_type": "session_started",
  "occurred_at": "2026-09-03T08:05:03Z",
  "provider_session_ref": "<response-runtime-provider-session-ref>",
  "session_nonce": "<response-runtime-session-nonce>",
  "provider_connection_ref": "<actual-volc-connection-ref>",
  "bot_id": "<response-runtime-bot-id>",
  "transport": "low_load",
  "config_digest": "<response-runtime-config-digest>",
  "dynamic_config_applied": true
}
```

后续事件类型：

- `session_updated`：按 `heartbeat_interval_sec` 上报存活；`sequence_no` 严格递增。
- `session_ended`：正常结束。
- `session_failed`：异常结束，可附加稳定、脱敏的 `error_code`。

响应：

```json
{
  "request_id": "req-...",
  "data": {
    "conversation_id": "<uuid>",
    "status": "ACTIVE",
    "action": "continue",
    "duplicate": false,
    "accepted_at": "2026-09-03T08:05:03Z"
  }
}
```

`action=stop_session` 时，设备必须立即关闭麦克风和火山连接，然后补报 `session_ended` 或 `session_failed`。相同 `event_id` 重放时必须保持原正文一致。

### 7.4 批量上传最终话轮

```http
POST /device/v3/agent-sessions/{conversation_id}/turns:batch
Idempotency-Key: 1710b8cc-9bf2-45e8-a16d-f32c3b80cbbe
Content-Type: application/json
```

请求：

```json
{
  "turns": [
    {
      "turn_key": "user-final-0001",
      "sequence_no": 1,
      "speaker": "subject",
      "start_at": "2026-09-03T08:05:10Z",
      "end_at": "2026-09-03T08:05:12Z",
      "final_text": "今天天气怎么样？",
      "interrupted": false
    },
    {
      "turn_key": "agent-final-0002",
      "sequence_no": 2,
      "speaker": "agent",
      "start_at": "2026-09-03T08:05:12Z",
      "end_at": "2026-09-03T08:05:15Z",
      "final_text": "我来帮您看看。",
      "interrupted": false
    }
  ]
}
```

只上传最终字幕；不得上传增量识别结果。单批 1—500 条，`speaker` 只能为 `subject` 或 `agent`。同一 `turn_key`/`sequence_no` 的重试必须保持正文完全一致。

成功响应：

```json
{
  "request_id": "req-...",
  "data": {
    "conversation_id": "<uuid>",
    "accepted_count": 2,
    "duplicate_count": 0
  }
}
```

## 8. App/Web 的设备接口

以下接口使用用户 OIDC Bearer Token，不使用设备 HMAC：

| 方法 | 路径 | 作用 |
|---|---|---|
| `POST` | `/api/v1/device-claims` | 消费绑定码并绑定设备 |
| `GET` | `/api/v1/devices` | 列出当前用户可管理设备 |
| `GET` | `/api/v1/devices/{id}` | 查看设备详情 |
| `GET` | `/api/v1/devices/{id}/binding-impact` | 变更绑定前评估影响 |
| `POST` | `/api/v1/devices/{id}/binding-change` | 解绑或改绑 |
| `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` | 下发设备命令 |

绑定码由平台/运维为 `CLAIMABLE` 设备生成，App 只消费，不自行生成。解绑会影响设备激活状态和火山运行凭据，必须先调用 `binding-impact` 展示影响并要求用户确认。

## 9. 平台运维设备接口

所有接口要求 OIDC Bearer Token 和有效的 `X-Tenant-Id: <tenant-uuid>`，且仅独立运维账号可调用。

| 方法 | 路径 | 作用 |
|---|---|---|
| `GET` | `/api/v1/ops/devices` | 设备列表 |
| `POST` | `/api/v1/ops/devices` | 登记设备并一次性返回平台 Device Secret |
| `GET` | `/api/v1/ops/device-assignment-options` | 可选家庭/长者列表 |
| `PATCH` | `/api/v1/ops/devices/{id}` | 修改设备；必须携带 `If-Match` |
| `DELETE` | `/api/v1/ops/devices/{id}` | 吊销设备；必须携带 `If-Match` |
| `POST` | `/api/v1/ops/devices/{id}/credentials/rotate` | 轮换平台 Device Secret，只返回一次明文 |
| `POST` | `/api/v1/ops/devices/{id}/claims` | 生成一次性绑定码 |
| `POST` | `/api/v1/ops/devices/{id}/activation-transitions` | 人工迁移激活状态 |
| `GET` | `/api/v1/ops/devices/{id}/activation-transitions` | 查询激活迁移历史 |

### 9.1 登记硬件智能体设备

```json
{
  "model": "echoear",
  "hardware_revision": "esp32-s3",
  "minimum_security_version": "1",
  "minimum_firmware_version": "1.0.0",
  "household_id": "",
  "subject_id": "",
  "voice_runtime": "volc_hardware_agent",
  "activation_state": "FACTORY"
}
```

Instance ID、Product Key、默认 Bot、传输模式和最低 SDK 由平台产品配置统一持有。设备第一次预配时自动生成绑定，运维创建设备或设备自身都不能覆盖这些字段。

响应中的 `data.credential.secret` 只显示一次。运维系统应立即通过受控注入工具写入设备安全区，不得复制到工单、聊天记录或普通数据库字段。

### 9.2 人工迁移激活状态

```json
{
  "target_state": "CLAIMABLE",
  "reason": "工厂质检通过",
  "expected_revision": 1
}
```

并发控制：列表/详情返回的设备版本对应 `ETag`；修改和删除使用 `If-Match`。激活迁移单独使用 `expected_revision`。版本不一致返回 `412 VERSION_CONFLICT` 或 `409 DEVICE_ACTIVATION_CONFLICT`，刷新后再决定，不能强制覆盖。

## 10. 幂等、重试和本地持久化

| 数据 | 本地策略 |
|---|---|
| 平台 Device Secret | 安全区长期保存；轮换时原子替换 |
| 火山 Device Secret | 安全区长期保存；不要每次启动都预配 |
| `session_nonce` | 仅本次通话运行内存 |
| `tool_scope_token` | 仅本次通话运行内存 |
| 最终字幕待上传队列 | 授权允许时加密持久化，成功确认后删除 |
| 增量字幕/原始音频 | 默认不长期保存 |

重试规则：

- `Idempotency-Key` 长度 16—128 字符。
- HTTP 超时或 `retryable=true`：原业务正文 + 原幂等键 + 新 HMAC nonce/signature，指数退避。
- `401`：先检查平台 Device Secret、时钟、请求 URI、正文摘要和 Base64URL 编码，不要盲目轮换密钥。
- `409 IDEMPOTENCY_KEY_REUSED`：同一幂等键配了不同正文；这是客户端错误。
- `HARDWARE_SESSION_PROOF_INVALID`：丢弃当前会话内存数据，重新创建新会话，不尝试其他设备的 nonce。
- `action=stop_session`：优先停止音频和供应商连接，再做结束确认及本地队列收尾。

## 11. EchoEar 固件接入清单

出厂只写入：

- 平台 `device_id`；
- 平台 Device Secret；
- `hardware_id`；
- API Base URL 和服务器信任锚；
- 固件签名信任锚。

首次绑定后设备取得并安全保存：

- 火山 `instance_id`；
- 火山 `product_key`；
- 火山 `device_name`；
- 火山 Device Secret；
- `credential_version`。

绝不写入设备：

- 火山 Product Secret；
- 平台数据库主密钥/KMS 密钥；
- 其他设备的 Device Secret；
- 固定的会话 nonce 或工具 Token；
- 人设、长期记忆和聊天记录的永久明文副本。

会话侧必须做到：

- 每通先请求平台会话配置，再连接火山；
- 人设、近期摘要和长期记忆以本次 `session_config` 为准；
- 动态配置确认前不打开麦克风；
- 设备事件和最终字幕可靠回流平台；
- 平台下发 `stop_session` 时可在一个心跳周期内停止。

## 12. 当前实现边界

- 当前 API 已实现平台 HMAC、激活状态机、火山动态注册、v3 会话控制面、事件回流和最终字幕上传。
- 设备音频是设备直连火山，平台不代理每一帧音频；平台通过设备事件和字幕回流维护会话权威状态。
- Windows/EchoEar 客户端仍需按目标 SDK 完成真实音频 HAL、火山协议、断线重连和安全存储验收。
- `/device/v3/hardware-agent-license:ack` 处理器代码虽曾存在，但没有路由、没有生产契约，也不应由设备调用。
- 完整字段定义以 [`openapi/openapi.yaml`](../openapi/openapi.yaml) 为机器可读基准；本文件是设备研发和联调的实施说明。

## 13. 联调最小验收用例

1. 错误平台签名返回 `401`，日志不泄露设备是否存在。
2. 同 nonce 重放被拒绝；相同业务幂等键配新 nonce 可安全重试。
3. `CLAIMABLE` 设备不能预配，`BOUND` 设备可以预配但不能创建会话。
4. 首次预配成功取得火山一机一密；重复预配不重复注册。
5. Product Secret 在设备固件、NVS、日志和网络响应中均不存在。
6. `ACTIVE` 设备创建 v3 会话并得到正确 Bot ID、人设和授权上下文。
7. 未确认动态配置的 `session_started` 被拒绝。
8. 正常开始、心跳、最终字幕、结束全部回流平台。
9. 平台返回 `stop_session` 后设备关闭连接并补报结束。
10. 火山 License 额度耗尽时预配失败，扩容后使用原幂等请求可恢复；设备无需安装 License 或 ACK。