ln：接口文档更新

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