From 955d099b6a05df01ee8799d472f7a4921ce05e82 Mon Sep 17 00:00:00 2001
From: luozheng <1732036298@qq.com>
Date: Tue, 18 Nov 2025 10:20:03 +0800
Subject: [PATCH] =?utf8?q?=E9=9B=B7=E9=B8=9F=E6=8E=A5=E5=8F=A3=E6=96=87?=
 =?utf8?q?=E6=A1=A3=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

---
 ...45\345\217\243\346\226\207\346\241\243.md" | 302 ++++++++++++++++++
 1 file changed, 302 insertions(+)

diff --git "a/code/sdk/zhihui/leiniao/\350\256\276\345\244\207API\346\216\245\345\217\243\346\226\207\346\241\243.md" "b/code/sdk/zhihui/leiniao/\350\256\276\345\244\207API\346\216\245\345\217\243\346\226\207\346\241\243.md"
index 10b949343..e5b4ff193 100644
--- "a/code/sdk/zhihui/leiniao/\350\256\276\345\244\207API\346\216\245\345\217\243\346\226\207\346\241\243.md"
+++ "b/code/sdk/zhihui/leiniao/\350\256\276\345\244\207API\346\216\245\345\217\243\346\226\207\346\241\243.md"
@@ -1905,6 +1905,104 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 - 发送间隔由服务端配置控制
 - 设备可以边接收边播放，实现流畅的播放体验
 
+#### 蓝牙状态上报 (BluetoothStatusReport)
+**命令描述**：客户端发送蓝牙状态上报，用于主动上报蓝牙连接状态变化
+**协议说明**：
+- 设备端蓝牙连接状态/耳机电量发生变化时，主动发送此命令上报状态
+- 支持的状态包括：连接中、连接成功、连接失败、已断开、解绑中、解绑失败、解绑成功
+- 服务端返回BluetoothStatusReportAck应答确认收到状态上报
+
+**消息格式**：
+```json
+{
+  "deviceId": "设备ID",
+  "timestamp": 1640995200,
+  "messageId": "消息ID",
+  "command": "BluetoothStatusReport",
+  "data": {
+    "bluetoothAddress": "蓝牙地址",
+    "bluetoothName": "蓝牙名称",
+    "batteryLevel": 80,
+    "bluetoothStatus": "CONNECTED",
+    "message": "蓝牙连接成功"
+  }
+}
+```
+
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "bt_status_001",
+  "command": "BluetoothStatusReport",
+  "data": {
+    "bluetoothAddress": "AA:BB:CC:DD:EE:FF",
+    "bluetoothName": "AirPods Pro",
+    "batteryLevel": 80,
+    "bluetoothStatus": "CONNECTED",
+    "message": "蓝牙连接成功"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| bluetoothAddress | String | 蓝牙设备MAC地址 |
+| bluetoothName | String | 蓝牙设备名称 |
+| batteryLevel | Integer | 电池电量百分比，范围0-100 |
+| bluetoothStatus | String | 蓝牙连接状态，枚举值见下方说明 |
+| message | String | 状态上报消息，用于描述状态上报的原因 |
+
+**bluetoothStatus字段枚举值**：
+
+| 枚举值 | 描述 |
+|--------|------|
+| CONNECTED | 蓝牙已连接 |
+| DISCONNECTED | 蓝牙已断开 |
+| CONNECTING | 蓝牙连接中 |
+| CONNECT_FAILED | 蓝牙连接失败 |
+| UNBINDING | 蓝牙解绑中 |
+| UNBIND_FAILED | 蓝牙解绑失败 |
+| UNBIND_SUCCESS | 蓝牙解绑成功 |
+
+**使用场景**：
+1. **连接成功**：设备完成蓝牙连接后，上报CONNECTED状态和消息
+2. **连接失败**：设备无法连接蓝牙设备时，上报CONNECT_FAILED状态和消息
+3. **断开连接**：蓝牙设备断开连接时，上报DISCONNECTED状态和消息
+4. **解绑成功**：设备完成蓝牙解绑后，上报UNBIND_SUCCESS状态和消息
+5. **解绑失败**：设备无法解绑蓝牙设备时，上报UNBIND_FAILED状态和消息
+6. **电量变化**：蓝牙耳机电量变化时，上报最新的batteryLevel，范围0-100和消息
+
+**服务端响应**：
+服务端收到蓝牙状态上报后，会通过WebSocket推送BluetoothStatusReportAck消息：
+
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995201,
+  "messageId": "bt_status_ack_001",
+  "command": "BluetoothStatusReportAck",
+  "data": {
+    "bluetoothAddress": "AA:BB:CC:DD:EE:FF",
+    "bluetoothName": "AirPods Pro",
+    "success": true,
+    "message": "蓝牙状态上报处理完成"
+  }
+}
+```
+
+**服务端响应data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| bluetoothAddress | String | 蓝牙设备MAC地址 |
+| bluetoothName | String | 蓝牙设备名称 |
+| success | Boolean | 是否成功处理状态上报 |
+| message | String | 处理结果描述信息 |
+
 ### 客户端应答消息 (ACK Messages)
 
 客户端在收到服务端推送的某些命令后，需要发送应答消息（ACK）来确认命令的接收和执行状态。所有 ACK 消息遵循统一的消息格式。
@@ -2427,6 +2525,102 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 - 失败可能原因：存储空间不足、网络异常、版本校验失败等
 - 升级成功后设备会自动重启，重启后以新版本运行
 
+#### 蓝牙连接应答 (BluetoothConnectAck)
+**命令描述**：设备端对蓝牙连接命令的应答，确认蓝牙连接操作的执行状态
+
+**消息格式**：
+```json
+{
+  "deviceId": "设备ID",
+  "timestamp": 1640995200,
+  "messageId": "消息ID",
+  "command": "BluetoothConnectAck",
+  "data": {
+    "success": true,
+    "message": "蓝牙连接中"
+  }
+}
+```
+
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "ack_bt_connect_001",
+  "command": "BluetoothConnectAck",
+  "data": {
+    "success": true,
+    "message": "蓝牙连接中"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| success | Boolean | 是否成功接收并开始处理蓝牙连接命令 |
+| message | String | 处理结果描述信息，如"蓝牙连接中" |
+
+**协议说明**：
+- 设备收到BluetoothConnect命令后，开始执行蓝牙连接操作，并发送此应答
+- success为true表示设备开始处理连接请求，false表示无法处理（如蓝牙模块异常）
+- 此应答仅表示设备接收到命令并开始处理，不代表蓝牙连接最终结果
+- 蓝牙连接的最终状态通过BluetoothStatusReport命令上报
+- 失败可能原因：蓝牙模块故障、蓝牙地址无效、设备忙碌等
+
+#### 蓝牙解绑应答 (BluetoothUnbindAck)
+**命令描述**：设备端对蓝牙解绑命令的应答，确认蓝牙解绑操作的执行状态
+
+**消息格式**：
+```json
+{
+  "deviceId": "设备ID",
+  "timestamp": 1640995200,
+  "messageId": "消息ID",
+  "command": "BluetoothUnbindAck",
+  "data": {
+    "bluetoothAddress": "蓝牙地址",
+    "bluetoothName": "蓝牙名称",
+    "success": true,
+    "message": "蓝牙解绑中"
+  }
+}
+```
+
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "ack_bt_unbind_001",
+  "command": "BluetoothUnbindAck",
+  "data": {
+    "bluetoothAddress": "AA:BB:CC:DD:EE:FF",
+    "bluetoothName": "AirPods Pro",
+    "success": true,
+    "message": "蓝牙解绑中"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| bluetoothAddress | String | 蓝牙设备MAC地址 |
+| bluetoothName | String | 蓝牙设备名称 |
+| success | Boolean | 是否成功接收并开始处理蓝牙解绑命令 |
+| message | String | 处理结果描述信息，如"蓝牙解绑中" |
+
+**协议说明**：
+- 设备收到BluetoothUnbind命令后，开始执行蓝牙解绑操作，并发送此应答
+- success为true表示设备开始处理解绑请求，false表示无法处理（如蓝牙设备未连接）
+- 此应答仅表示设备接收到命令并开始处理，不代表蓝牙解绑最终结果
+- 蓝牙解绑的最终状态通过BluetoothStatusReport命令上报
+- 失败可能原因：蓝牙设备未连接、蓝牙地址不匹配、设备忙碌等
+
 ### 服务端业务消息
 
 服务端通过WebSocket连接推送业务消息给设备端，消息采用JSON格式，消息结构如下：
@@ -3056,6 +3250,114 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 7. 校验通过后执行升级并重启
 8. 重启后以新版本重新获取设备Token
 
+#### 17. 蓝牙连接 (BluetoothConnect)
+**命令描述**：通知设备连接指定的蓝牙设备
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "msg_014",
+  "command": "BluetoothConnect",
+  "data": {
+    "userId": "user_001",
+    "bluetoothAddress": "AA:BB:CC:DD:EE:FF"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| userId | String | 用户ID，标识发起连接操作的用户 |
+| bluetoothAddress | String | 要连接的蓝牙设备MAC地址，保留字段，暂时无用 |
+
+**设备处理说明**：
+- 设备收到此命令后，开始搜索和连接蓝牙设备
+- 连接过程中发送BluetoothConnectAck应答确认收到命令
+- 连接结果通过BluetoothStatusReport命令上报
+- 如果连接成功，上报CONNECTED状态和蓝牙耳机电量
+- 如果连接失败，上报CONNECT_FAILED状态和错误信息
+
+**连接流程**：
+1. 用户在小程序端发起连接蓝牙耳机操作
+2. 服务器通过WebSocket推送BluetoothConnect命令到设备端
+3. 设备端收到命令，返回BluetoothConnectAck应答
+4. 设备端执行搜索和蓝牙连接操作
+5. 连接完成后，设备端发送BluetoothStatusReport上报最终状态
+6. 小程序端显示连接状态和蓝牙耳机电量
+
+#### 18. 蓝牙解绑 (BluetoothUnbind)
+**命令描述**：通知设备解绑指定的蓝牙设备
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "msg_015",
+  "command": "BluetoothUnbind",
+  "data": {
+    "userId": "user_001",
+    "bluetoothAddress": "AA:BB:CC:DD:EE:FF",
+    "bluetoothName": "AirPods Pro"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| userId | String | 用户ID，标识发起解绑操作的用户 |
+| bluetoothAddress | String | 要解绑的蓝牙设备MAC地址 |
+| bluetoothName | String | 蓝牙设备名称 |
+
+**设备处理说明**：
+- 设备收到此命令后，开始解绑指定的蓝牙设备
+- 解绑过程中发送BluetoothUnbindAck应答确认收到命令
+- 解绑结果通过BluetoothStatusReport命令上报
+- 如果解绑成功，上报UNBIND_SUCCESS状态
+- 如果解绑失败，上报UNBIND_FAILED状态
+
+**解绑流程**：
+1. 用户在小程序端发起解绑蓝牙耳机操作
+2. 服务器通过WebSocket推送BluetoothUnbind命令到设备端
+3. 设备端收到命令，返回BluetoothUnbindAck应答
+4. 设备端执行蓝牙解绑操作
+5. 解绑完成后，设备端发送BluetoothStatusReport上报最终状态
+6. 小程序端显示解绑状态
+
+#### 19. 蓝牙状态上报应答 (BluetoothStatusReportAck)
+**命令描述**：服务端对设备蓝牙状态上报的应答，确认收到状态上报
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "msg_016",
+  "command": "BluetoothStatusReportAck",
+  "data": {
+    "bluetoothAddress": "AA:BB:CC:DD:EE:FF",
+    "bluetoothName": "AirPods Pro",
+    "success": true,
+    "message": "蓝牙状态上报处理完成"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| bluetoothAddress | String | 蓝牙设备MAC地址 |
+| bluetoothName | String | 蓝牙设备名称 |
+| success | Boolean | 是否成功处理状态上报 |
+| message | String | 处理结果描述信息 |
+
+**服务端处理说明**：
+- 服务端收到BluetoothStatusReport命令后，更新设备缓存中的蓝牙连接信息，并返回BluetoothStatusReportAck应答给设备端
+
 
 ## 7. 表情管理接口
 
-- 
2.17.1