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