ln协议文档更新

diff --git a/code/sdk/zhihui/leiniao/设备API接口文档.md b/code/sdk/zhihui/leiniao/设备API接口文档.md
index 105ea09..8b6da84 100644 (file)
--- a/code/sdk/zhihui/leiniao/设备API接口文档.md
+++ b/code/sdk/zhihui/leiniao/设备API接口文档.md
@@ -1816,6 +1816,477 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 }\r
 ```\r
 \r
+### 客户端应答消息 (ACK Messages)\r
+\r
+客户端在收到服务端推送的某些命令后，需要发送应答消息（ACK）来确认命令的接收和执行状态。所有 ACK 消息遵循统一的消息格式。\r
+\r
+#### 角色切换应答 (CharacterChangeAck)\r
+**命令描述**：设备端对角色切换命令的应答，确认角色切换操作的执行状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "CharacterChangeAck",\r
+  "data": {\r
+    "characterId": "角色ID",\r
+    "success": true,\r
+    "message": "角色切换成功"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "ack_char_change_001",\r
+  "command": "CharacterChangeAck",\r
+  "data": {\r
+    "characterId": "char_001",\r
+    "success": true,\r
+    "message": "角色切换成功"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| characterId | String | 角色ID |\r
+| success | Boolean | 是否成功切换角色 |\r
+| message | String | 切换结果描述信息 |\r
+\r
+**协议说明**：\r
+- 设备收到CharacterChange命令后，应用新角色配置，并发送此应答\r
+- success为true表示切换成功，false表示切换失败（如资源加载失败）\r
+- 服务端收到失败应答时，可以重新推送切换命令或通知用户\r
+\r
+#### 角色配置更改应答 (CharacterConfigChangeAck)\r
+**命令描述**：设备端对角色配置更改命令的应答，确认配置更新的执行状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "CharacterConfigChangeAck",\r
+  "data": {\r
+    "characterId": "角色ID",\r
+    "success": true,\r
+    "message": "配置更新成功"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "ack_config_001",\r
+  "command": "CharacterConfigChangeAck",\r
+  "data": {\r
+    "characterId": "char_001",\r
+    "success": true,\r
+    "message": "配置更新成功"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| characterId | String | 角色ID |\r
+| success | Boolean | 是否成功更新配置 |\r
+| message | String | 更新结果描述信息 |\r
+\r
+**协议说明**：\r
+- 设备收到CharacterConfigChange命令后，更新当前角色配置，并发送此应答\r
+- 配置更新包括角色形象、名称等属性的变更\r
+- 失败时应在message中说明具体原因\r
+\r
+#### 哄睡模式开始应答 (SleepModeStartAck)\r
+**命令描述**：设备端对哄睡模式开始命令的应答，确认哄睡模式启动状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "SleepModeStartAck",\r
+  "data": {\r
+    "success": true,\r
+    "message": "哄睡模式已启动"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "ack_sleep_start_001",\r
+  "command": "SleepModeStartAck",\r
+  "data": {\r
+    "success": true,\r
+    "message": "哄睡模式已启动"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| success | Boolean | 是否成功启动哄睡模式 |\r
+| message | String | 启动结果描述信息 |\r
+\r
+**协议说明**：\r
+- 设备收到SleepModeStart命令后，进入哄睡模式，并发送此应答\r
+- 启动成功后设备应调用故事接口开始播放故事\r
+- 失败可能原因：设备忙碌、资源不足等\r
+\r
+#### 哄睡模式结束应答 (SleepModeEndAck)\r
+**命令描述**：设备端对哄睡模式结束命令的应答，确认哄睡模式退出状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "SleepModeEndAck",\r
+  "data": {\r
+    "success": true,\r
+    "message": "哄睡模式已结束"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "ack_sleep_end_001",\r
+  "command": "SleepModeEndAck",\r
+  "data": {\r
+    "success": true,\r
+    "message": "哄睡模式已结束"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| success | Boolean | 是否成功结束哄睡模式 |\r
+| message | String | 结束结果描述信息 |\r
+\r
+**协议说明**：\r
+- 设备收到SleepModeEnd命令后，停止故事播放，退出哄睡模式，并发送此应答\r
+- 设备应停止所有与哄睡相关的音频播放\r
+- 退出后设备恢复到正常待机状态\r
+\r
+#### 设备绑定应答 (DeviceBindAck)\r
+**命令描述**：设备端对设备绑定命令的应答，确认绑定操作的执行状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "DeviceBindAck",\r
+  "data": {\r
+    "userId": "用户ID",\r
+    "success": true,\r
+    "message": "绑定成功"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "ack_bind_001",\r
+  "command": "DeviceBindAck",\r
+  "data": {\r
+    "userId": "user_001",\r
+    "success": true,\r
+    "message": "绑定成功"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| userId | String | 用户ID |\r
+| success | Boolean | 是否成功绑定 |\r
+| message | String | 绑定结果描述信息 |\r
+\r
+**协议说明**：\r
+- 设备收到DeviceBind命令后，更新绑定状态，隐藏绑定二维码，并发送此应答\r
+- 绑定成功后设备应进入正常使用状态\r
+- 服务端收到应答后可以向用户发送绑定成功通知\r
+\r
+#### 设备解绑应答 (DeviceUnbindAck)\r
+**命令描述**：设备端对设备解绑命令的应答，确认解绑操作的执行状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "DeviceUnbindAck",\r
+  "data": {\r
+    "userId": "用户ID",\r
+    "success": true,\r
+    "message": "解绑成功"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "ack_unbind_001",\r
+  "command": "DeviceUnbindAck",\r
+  "data": {\r
+    "userId": "user_001",\r
+    "success": true,\r
+    "message": "解绑成功"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| userId | String | 用户ID |\r
+| success | Boolean | 是否成功解绑 |\r
+| message | String | 解绑结果描述信息 |\r
+\r
+**协议说明**：\r
+- 设备收到DeviceUnbind命令后，清除用户数据，恢复出厂设置（可选），并发送此应答\r
+- 解绑成功后设备应显示绑定二维码，等待新用户绑定\r
+- 设备可以选择保留或清除用户相关数据\r
+\r
+#### 日程提醒应答 (ScheduleReminderAck)\r
+**命令描述**：设备端对日程提醒命令的应答，确认提醒播放的执行状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "ScheduleReminderAck",\r
+  "data": {\r
+    "scheduleId": 123,\r
+    "success": true,\r
+    "message": "提醒已播放"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "ack_reminder_001",\r
+  "command": "ScheduleReminderAck",\r
+  "data": {\r
+    "scheduleId": 123,\r
+    "success": true,\r
+    "message": "提醒已播放"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| scheduleId | Integer | 日程ID |\r
+| success | Boolean | 是否成功播放提醒 |\r
+| message | String | 播放结果描述信息 |\r
+\r
+**协议说明**：\r
+- 设备收到ScheduleReminder命令后，播放提醒音频和内容，并发送此应答\r
+- 应答表示设备已收到并处理提醒，不表示用户是否看到\r
+- 服务端根据应答记录提醒推送状态\r
+\r
+#### 日程提醒配置应答 (ScheduleReminderConfigAck)\r
+**命令描述**：设备端对日程提醒配置命令的应答，确认配置更新的执行状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "ScheduleReminderConfigAck",\r
+  "data": {\r
+    "scheduleId": 123,\r
+    "success": true,\r
+    "message": "配置已更新"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "ack_reminder_config_001",\r
+  "command": "ScheduleReminderConfigAck",\r
+  "data": {\r
+    "scheduleId": 123,\r
+    "success": true,\r
+    "message": "配置已更新"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| scheduleId | Integer | 日程ID |\r
+| success | Boolean | 是否成功更新配置 |\r
+| message | String | 更新结果描述信息 |\r
+\r
+**协议说明**：\r
+- 设备收到ScheduleReminderConfig命令后，更新日程提醒配置，并发送此应答\r
+- 配置更新可能包括提醒时间、内容、方式等\r
+- 失败时应说明原因，如配置格式错误等\r
+\r
+#### 删除表情应答 (DeleteEmojiAck)\r
+**命令描述**：设备端对删除表情命令的应答，确认表情删除的执行状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "DeleteEmojiAck",\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_delete_emoji_001",\r
+  "command": "DeleteEmojiAck",\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
+- 设备收到DeleteEmoji命令后，删除对应的表情文件，并发送此应答\r
+- 删除成功后应调用reportEmoji接口上报删除状态\r
+- 失败可能原因：文件不存在、权限不足等\r
+\r
+#### 下载表情应答 (DownloadEmojiAck)\r
+**命令描述**：设备端对下载表情命令的应答，确认表情下载的执行状态\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "DownloadEmojiAck",\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_download_emoji_001",\r
+  "command": "DownloadEmojiAck",\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
+- 设备收到DownloadEmoji命令后发送此应答，并下载表情文件到本地\r
+- 下载成功后应调用reportEmoji接口上报下载状态\r
+- 失败可能原因：网络异常、存储空间不足、下载超时等\r
+- 建议设备实现断点续传机制\r
+\r
 ### 服务端业务消息\r
 \r
 服务端通过WebSocket连接推送业务消息给设备端，消息采用JSON格式，消息结构如下：\r
@@ -2284,6 +2755,8 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 |--------|------|------|\r
 | emotion | String | 心情类型，如"happy"、"sad"、"angry"等 |\r
 | emojiUrl | String | 表情动画文件URL，通常为mp4格式 |\r
+| size | Integer | 表情大小，单位：字节 |\r
+\r
 \r
 **设备处理说明**：\r
 - 设备收到此命令后，应下载所有emotionEmojis中的表情文件\r