From dccdc9fc9150c456162a6a70ef182fef0a763cd7 Mon Sep 17 00:00:00 2001
From: luozheng <1732036298@qq.com>
Date: Wed, 17 Dec 2025 17:59:23 +0800
Subject: [PATCH] =?utf8?q?ln=EF=BC=9A=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3?=
 =?utf8?q?=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" | 245 +++++++++++++++++-
 1 file changed, 238 insertions(+), 7 deletions(-)

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 ea3ef1520..ddce8a015 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"
@@ -1460,7 +1460,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 
 ### 客户端业务消息
 
-客户端可以通过WebSocket连接发送业务消息给服务端，目前支持心跳、对话会话开始、对话会话结束、语音对话分片传输、语音对话打断、语音选择故事、随机故事请求、蓝牙状态上报和设备升级状态上报。
+客户端可以通过WebSocket连接发送业务消息给服务端，目前支持心跳、对话会话开始、对话会话结束、语音对话分片传输、语音对话打断、语音选择故事、随机故事请求、蓝牙状态上报、设备升级状态上报和表情包下载状态上报。
 
 #### 心跳请求 (Ping)
 **命令描述**：客户端发送心跳请求，保持WebSocket连接活跃
@@ -1709,7 +1709,8 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
     "audioBase64": "BAAEAAQABAAEAAQABAAEAAQABAAEAAAA...",
     "chatId": "chat_12345",
     "sessionId": "a1b2c3d4e5f67890",
-    "finished": true
+    "finished": true,
+    "returnBytes": true
   }
 }
 ```
@@ -1722,6 +1723,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 | chatId | String | 是 | 对话ID，用于标识本次对话，建议使用UUID |
 | sessionId | String | 是 | 对话会话ID，由ChatSessionStartAck返回，用于标识对话会话 |
 | finished | Boolean | 是 | 是否为最后一个分片，true表示传输完成 |
+| returnBytes | Boolean | 否 | 是否返回字节流，true表示返回字节流，否则只返回音频URL地址，默认值为true |
 
 **分片传输规则**：
 1. 原始音频数据按8KB分片
@@ -1869,7 +1871,8 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
   "data": {
     "audioBase64": "BAAEAAQABAAEAAQABAAEAAQABAAEAAAA...",
     "chatId": "story_12345",
-    "finished": true
+    "finished": true,
+    "returnBytes": true
   }
 }
 ```
@@ -1881,6 +1884,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 | audioBase64 | String | 音频数据Base64编码，单个分片不超过8KB原始数据 |
 | chatId | String | 对话ID，用于标识本次故事请求，建议使用UUID |
 | finished | Boolean | 是否为最后一个分片，true表示传输完成 |
+| returnBytes | Boolean | 是否返回字节流，true表示返回字节流，否则只返回音频URL地址，默认值为true |
 
 **服务端响应**：
 服务端收到完整音频后，会通过WebSocket推送ChooseStoryResponse消息流式返回故事内容：
@@ -1935,7 +1939,8 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
   "command": "RandomStoryRequest",
   "data": {
     "chatId": "random_story_12345",
-    "storyTheme": "冒险"
+    "storyTheme": "冒险",
+    "returnBytes": true
   }
 }
 ```
@@ -1946,6 +1951,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 |--------|------|------|
 | chatId | String | 对话ID，用于标识本次故事请求，建议使用UUID |
 | storyTheme | String | 故事主题，可选参数。如"童话"、"冒险"、"科幻"等，不指定时系统随机选择 |
+| returnBytes | Boolean | 是否返回字节流，true表示返回字节流，否则只返回音频URL地址，默认值为true |
 
 **服务端响应**：
 服务端收到随机故事请求后，会通过WebSocket推送RandomStoryResponse消息流式返回故事内容：
@@ -2245,6 +2251,116 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 - 当收到升级状态时，服务端会将状态同步通知到小程序端
 - 设备端可根据应答确认状态上报是否成功，失败时可重试上报
 
+#### 表情包下载状态上报 (EmojiDownloadStatusReport)
+**命令描述**：客户端发送表情包下载状态上报，用于主动上报表情包下载进度和结果
+**协议说明**：
+- 设备在执行表情包下载任务过程中，定期上报下载状态和进度
+- 支持的状态包括：正在下载、下载成功、下载失败、取消成功、取消失败等
+- 服务端返回EmojiDownloadStatusReportAck应答确认收到状态上报
+
+**消息格式**：
+```json
+{
+  "deviceId": "设备ID",
+  "timestamp": 1640995200,
+  "messageId": "消息ID",
+  "command": "EmojiDownloadStatusReport",
+  "data": {
+    "characterId": "角色ID",
+    "eyesColor": "瞳色",
+    "eyesShape": "眼型",
+    "status": "downloading",
+    "progress": 50,
+    "message": "下载进度50%"
+  }
+}
+```
+
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "emoji_status_001",
+  "command": "EmojiDownloadStatusReport",
+  "data": {
+    "characterId": "char_001",
+    "eyesColor": "blue",
+    "eyesShape": "calm-eyes",
+    "status": "downloading",
+    "progress": 50,
+    "message": "下载进度50%"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| characterId | String | 角色ID，用于标识表情包所属角色 |
+| eyesColor | String | 瞳色，用于标识表情包组合 |
+| eyesShape | String | 眼型，用于标识表情包组合 |
+| status | String | 下载状态，枚举值见下方说明 |
+| progress | Integer | 下载进度，范围：0-100，仅在status为downloading时有效 |
+| message | String | 状态上报消息，用于描述状态上报的原因 |
+
+**status字段枚举值**：
+
+| 枚举值 | JSON值 | 描述 |
+|--------|--------|------|
+| DOWNLOADING | downloading | 正在下载 |
+| DOWNLOAD_SUCCESS | download_success | 下载成功 |
+| DOWNLOAD_FAILED | download_fail | 下载失败 |
+| CANCELLED | cancelled | 取消成功 |
+| CANCEL_FAILED | cancel_failed | 取消失败 |
+| DELETE_SUCCESS | delete_success | 删除成功 |
+| DELETE_FAILED | delete_fail | 删除失败 |
+| NOT_DOWNLOADED | not_downloaded | 未下载 |
+
+**使用场景**：
+1. **下载中**：设备下载表情包文件过程中，定期上报下载进度（progress: 0-100）
+2. **下载成功**：设备完成表情包下载后，上报DOWNLOAD_SUCCESS状态
+3. **下载失败**：设备下载过程中出现错误时，上报DOWNLOAD_FAILED状态和失败原因
+4. **取消成功**：用户主动取消下载或系统取消下载时，上报CANCELLED状态
+5. **取消失败**：设备无法取消下载时，上报CANCEL_FAILED状态
+
+**服务端响应**：
+服务端收到表情包下载状态上报后，会通过WebSocket推送EmojiDownloadStatusReportAck消息：
+
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995201,
+  "messageId": "emoji_status_ack_001",
+  "command": "EmojiDownloadStatusReportAck",
+  "data": {
+    "characterId": "char_001",
+    "eyesColor": "blue",
+    "eyesShape": "calm-eyes",
+    "success": true,
+    "message": "表情包下载状态上报处理完成"
+  }
+}
+```
+
+**服务端响应data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| characterId | String | 角色ID，与上报消息中的characterId对应 |
+| eyesColor | String | 瞳色，与上报消息中的eyesColor对应 |
+| eyesShape | String | 眼型，与上报消息中的eyesShape对应 |
+| success | Boolean | 是否成功处理状态上报 |
+| message | String | 处理结果描述信息 |
+
+**协议说明**：
+- 服务端收到EmojiDownloadStatusReport后，处理状态并返回此应答
+- success为true表示成功处理状态上报，false表示处理失败（如设备不存在等）
+- 当收到下载状态时，服务端会将状态同步通知到小程序端
+- 设备端可根据应答确认状态上报是否成功，失败时可重试上报
+- characterId、eyesColor、eyesShape三个字段组合标识一个唯一的表情包组合
+
 ### 客户端应答消息 (ACK Messages)
 
 客户端在收到服务端推送的某些命令后，需要发送应答消息（ACK）来确认命令的接收和执行状态。所有 ACK 消息遵循统一的消息格式。
@@ -2716,6 +2832,57 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 - 失败可能原因：网络异常、存储空间不足、下载超时等
 - 建议设备实现断点续传机制
 
+#### 取消下载表情应答 (CancelDownloadEmojiAck)
+**命令描述**：设备端对取消下载表情命令的应答，确认取消下载的执行状态
+
+**消息格式**：
+```json
+{
+  "deviceId": "设备ID",
+  "timestamp": 1640995200,
+  "messageId": "消息ID",
+  "command": "CancelDownloadEmojiAck",
+  "data": {
+    "characterId": "角色ID",
+    "eyesColor": "瞳色",
+    "eyesShape": "眼型",
+    "success": true,
+    "message": "取消下载成功"
+  }
+}
+```
+
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "ack_cancel_download_emoji_001",
+  "command": "CancelDownloadEmojiAck",
+  "data": {
+    "characterId": "char_001",
+    "eyesColor": "blue",
+    "eyesShape": "calm-eyes",
+    "success": true,
+    "message": "取消下载成功"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| characterId | String | 角色ID |
+| eyesColor | String | 瞳色 |
+| eyesShape | String | 眼型 |
+| success | Boolean | 是否成功取消下载表情 |
+| message | String | 取消结果描述信息 |
+
+**协议说明**：
+- 设备收到CancelDownloadEmoji命令后，停止下载表情文件，并发送此应答
+- 失败可能原因：下载已完成、下载任务不存在、设备忙碌等
+
 #### 设备升级应答 (DeviceUpgradeAck)
 **命令描述**：设备端对设备升级命令的应答，确认升级任务触发状态
 
@@ -3425,7 +3592,38 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 - 删除完成后，调用`/v1/emoji/reportEmoji`接口上报删除状态
 - 删除操作应清理本地缓存的表情文件
 
-#### 16. 设备升级 (DeviceUpgrade)
+#### 16. 取消下载表情 (CancelDownloadEmoji)
+**命令描述**：通知设备取消正在下载的指定角色的表情包
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995200,
+  "messageId": "msg_013",
+  "command": "CancelDownloadEmoji",
+  "data": {
+    "characterId": "char_001",
+    "eyesColor": "blue",
+    "eyesShape": "calm-eyes"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| characterId | String | 角色ID |
+| eyesColor | String | 瞳色，用于标识要取消下载的表情包组合 |
+| eyesShape | String | 眼型，用于标识要取消下载的表情包组合 |
+
+**设备处理说明**：
+- 设备收到此命令后，应停止下载对应角色和瞳色、眼型组合的表情文件
+- 取消下载完成后，发送CancelDownloadEmojiAck应答确认取消结果
+- 如果取消成功，应清理已下载的部分文件（可选）
+- 如果取消失败，应在应答中说明失败原因
+
+#### 17. 设备升级 (DeviceUpgrade)
 **命令描述**：通知设备执行固件升级
 **消息示例**：
 ```json
@@ -3629,8 +3827,41 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 - 服务端收到DeviceUpgradeStatusReport命令后，处理升级状态并返回DeviceUpgradeStatusReportAck应答给设备端
 - success为true表示成功处理状态上报，false表示处理失败（如设备不存在等）
 
+#### 21. 表情包下载状态上报应答 (EmojiDownloadStatusReportAck)
+**命令描述**：服务端对表情包下载状态上报的应答，确认收到状态上报
+**消息示例**：
+```json
+{
+  "deviceId": "DEVICE_001",
+  "timestamp": 1640995201,
+  "messageId": "msg_018",
+  "command": "EmojiDownloadStatusReportAck",
+  "data": {
+    "characterId": "char_001",
+    "eyesColor": "blue",
+    "eyesShape": "calm-eyes",
+    "success": true,
+    "message": "表情包下载状态上报处理完成"
+  }
+}
+```
+
+**data字段说明**：
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| characterId | String | 角色ID，与上报消息中的characterId对应 |
+| eyesColor | String | 瞳色，与上报消息中的eyesColor对应 |
+| eyesShape | String | 眼型，与上报消息中的eyesShape对应 |
+| success | Boolean | 是否成功处理状态上报 |
+| message | String | 处理结果描述信息 |
+
+**服务端处理说明**：
+- 服务端收到EmojiDownloadStatusReport命令后，处理表情包下载状态并返回EmojiDownloadStatusReportAck应答给设备端
+- success为true表示成功处理状态上报，false表示处理失败（如设备不存在等）
+- 服务端会将表情包下载状态同步到小程序端，小程序端可以实时显示下载进度和结果
 
-#### 21. 对话会话开始应答 (ChatSessionStartAck)
+#### 22. 对话会话开始应答 (ChatSessionStartAck)
 **命令描述**：服务端对对话会话开始请求的应答，返回生成的sessionId
 
 **消息格式**：
@@ -3673,7 +3904,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 - 会话结束后需要调用ChatSessionEnd命令结束会话
 
 
-#### 21.对话会话结束应答 (ChatSessionEndAck)
+#### 23. 对话会话结束应答 (ChatSessionEndAck)
 **命令描述**：服务端对对话会话结束请求的应答，确认会话已结束
 
 **消息格式**：
-- 
2.17.1