协议文档更新

diff --git a/code/sdk/zhihui/leiniao/设备API接口文档.md b/code/sdk/zhihui/leiniao/设备API接口文档.md
index e5b4ff1..268e598 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
@@ -1509,6 +1509,143 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 - 如果长时间未收到Pong响应，说明连接可能异常，建议重新连接\r
 - 心跳间隔建议设置为30秒，过于频繁会增加服务器负载\r
 \r
+#### 对话会话开始 (ChatSessionStart)\r
+**命令描述**：客户端发送对话会话开始请求，用于开始一个新的对话会话\r
+**协议说明**：\r
+- 用户长按对话按键开始对话时，客户端发送此命令\r
+- 服务端收到请求后会生成16位UUID作为sessionId并返回\r
+- 后续的语音对话请求需要携带此sessionId\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "ChatSessionStart",\r
+  "data": {\r
+    "chatId": "请求ID，用于标识本次请求"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995200,\r
+  "messageId": "session_start_001",\r
+  "command": "ChatSessionStart",\r
+  "data": {\r
+    "chatId": "chat_12345"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 必填 | 描述 |\r
+|--------|------|------|------|\r
+| chatId | String | 是 | 请求ID，用于标识本次请求，建议使用UUID |\r
+\r
+**服务端响应**：\r
+服务端收到会话开始请求后，会通过WebSocket推送ChatSessionStartAck响应：\r
+\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995201,\r
+  "messageId": "session_start_ack_001",\r
+  "command": "ChatSessionStartAck",\r
+  "data": {\r
+    "sessionId": "a1b2c3d4e5f67890",\r
+    "chatId": "chat_12345"\r
+  }\r
+}\r
+```\r
+\r
+**服务端响应data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| sessionId | String | 对话会话ID，16位UUID，由服务端生成 |\r
+| chatId | String | 请求ID，与请求中的chatId对应 |\r
+\r
+**协议说明**：\r
+- 客户端收到sessionId后，应在后续的VoiceChatRequest请求中携带此sessionId\r
+- sessionId用于标识一个完整的对话会话，一个会话可以包含多次对话请求\r
+- 会话结束后需要调用ChatSessionEnd命令结束会话\r
+\r
+\r
+#### 对话会话结束 (ChatSessionEnd)\r
+**命令描述**：客户端发送对话会话结束请求，用于结束当前的对话会话\r
+**协议说明**：\r
+- 用户长按对话按键结束对话时，客户端发送此命令\r
+- 会话结束后，该sessionId将不再有效\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995200,\r
+  "messageId": "消息ID",\r
+  "command": "ChatSessionEnd",\r
+  "data": {\r
+    "sessionId": "对话会话ID",\r
+    "chatId": "请求ID，用于标识本次请求"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995300,\r
+  "messageId": "session_end_001",\r
+  "command": "ChatSessionEnd",\r
+  "data": {\r
+    "sessionId": "a1b2c3d4e5f67890",\r
+    "chatId": "chat_67890"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 必填 | 描述 |\r
+|--------|------|------|------|\r
+| sessionId | String | 是 | 对话会话ID，与ChatSessionStartAck返回的sessionId一致 |\r
+| chatId | String | 是 | 请求ID，用于标识本次请求，建议使用UUID |\r
+\r
+**服务端响应**：\r
+服务端收到会话结束请求后，会通过WebSocket推送ChatSessionEndAck响应：\r
+\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995301,\r
+  "messageId": "session_end_ack_001",\r
+  "command": "ChatSessionEndAck",\r
+  "data": {\r
+    "sessionId": "a1b2c3d4e5f67890",\r
+    "chatId": "chat_67890"\r
+  }\r
+}\r
+```\r
+\r
+**服务端响应data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| sessionId | String | 对话会话ID，与请求中的sessionId对应 |\r
+| chatId | String | 请求ID，与请求中的chatId对应 |\r
+\r
+**协议说明**：\r
+- 会话结束后，该sessionId将不再有效，后续的VoiceChatRequest不应再使用此sessionId\r
+- 如果需要继续对话，需要重新调用ChatSessionStart获取新的sessionId\r
+- 会话结束会清理服务端的会话缓存，释放相关资源\r
+\r
 #### 语音对话分片传输 (VoiceChatRequest)\r
 **命令描述**：客户端发送语音对话请求，支持大音频文件的分片传输\r
 **协议说明**：\r
@@ -1526,6 +1663,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
   "data": {\r
     "audioBase64": "音频数据Base64编码（分片）",\r
     "chatId": "对话ID，用于标识本次对话",\r
+    "sessionId": "对话会话ID",\r
     "finished": false\r
   }\r
 }\r
@@ -1542,6 +1680,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
   "data": {\r
     "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",\r
     "chatId": "chat_12345",\r
+    "sessionId": "a1b2c3d4e5f67890",\r
     "finished": false\r
   }\r
 }\r
@@ -1555,6 +1694,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
   "data": {\r
     "audioBase64": "AAEAAQABAAEAAQABAAEAAQABAAEAAQAB...",\r
     "chatId": "chat_12345",\r
+    "sessionId": "a1b2c3d4e5f67890",\r
     "finished": false\r
   }\r
 }\r
@@ -1568,6 +1708,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
   "data": {\r
     "audioBase64": "BAAEAAQABAAEAAQABAAEAAQABAAEAAAA...",\r
     "chatId": "chat_12345",\r
+    "sessionId": "a1b2c3d4e5f67890",\r
     "finished": true\r
   }\r
 }\r
@@ -1575,18 +1716,24 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 \r
 **data字段说明**：\r
 \r
-| 字段名 | 类型 | 描述 |\r
-|--------|------|------|\r
-| audioBase64 | String | 音频数据Base64编码，单个分片不超过8KB原始数据 |\r
-| chatId | String | 对话ID，用于标识本次对话，建议使用UUID |\r
-| finished | Boolean | 是否为最后一个分片，true表示传输完成 |\r
+| 字段名 | 类型 | 必填 | 描述 |\r
+|--------|------|------|------|\r
+| audioBase64 | String | 否 | 音频数据Base64编码，单个分片不超过8KB原始数据 |\r
+| chatId | String | 是 | 对话ID，用于标识本次对话，建议使用UUID |\r
+| sessionId | String | 是 | 对话会话ID，由ChatSessionStartAck返回，用于标识对话会话 |\r
+| finished | Boolean | 是 | 是否为最后一个分片，true表示传输完成 |\r
 \r
 **分片传输规则**：\r
 1. 原始音频数据按8KB分片\r
 2. 每个分片转换为Base64编码后发送\r
-3. 所有分片使用相同的chatId\r
+3. 所有分片使用相同的chatId和sessionId\r
 4. 只有最后一个分片设置finished=true\r
 \r
+**sessionId使用说明**：\r
+- sessionId必须通过ChatSessionStart命令获取\r
+- 同一个会话中的所有对话请求应使用相同的sessionId\r
+- 会话结束后，该sessionId将不再有效，需要重新获取\r
+\r
 **服务端响应**：\r
 服务端收到完整音频后，会通过WebSocket推送VoiceChatResponse消息：\r
 \r
@@ -3358,6 +3505,92 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 **服务端处理说明**：\r
 - 服务端收到BluetoothStatusReport命令后，更新设备缓存中的蓝牙连接信息，并返回BluetoothStatusReportAck应答给设备端\r
 \r
+#### 20. 对话会话开始应答 (ChatSessionStartAck)\r
+**命令描述**：服务端对对话会话开始请求的应答，返回生成的sessionId\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995201,\r
+  "messageId": "消息ID",\r
+  "command": "ChatSessionStartAck",\r
+  "data": {\r
+    "sessionId": "对话会话ID",\r
+    "chatId": "请求ID"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995201,\r
+  "messageId": "session_start_ack_001",\r
+  "command": "ChatSessionStartAck",\r
+  "data": {\r
+    "sessionId": "a1b2c3d4e5f67890",\r
+    "chatId": "chat_12345"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| sessionId | String | 对话会话ID，16位UUID，由服务端生成 |\r
+| chatId | String | 请求ID，与请求中的chatId对应 |\r
+\r
+**协议说明**：\r
+- 客户端收到此应答后，应保存sessionId并在后续的VoiceChatRequest中使用\r
+- 会话结束后需要调用ChatSessionEnd命令结束会话\r
+\r
+\r
+#### 21.对话会话结束应答 (ChatSessionEndAck)\r
+**命令描述**：服务端对对话会话结束请求的应答，确认会话已结束\r
+\r
+**消息格式**：\r
+```json\r
+{\r
+  "deviceId": "设备ID",\r
+  "timestamp": 1640995301,\r
+  "messageId": "消息ID",\r
+  "command": "ChatSessionEndAck",\r
+  "data": {\r
+    "sessionId": "对话会话ID",\r
+    "chatId": "请求ID"\r
+  }\r
+}\r
+```\r
+\r
+**消息示例**：\r
+```json\r
+{\r
+  "deviceId": "DEVICE_001",\r
+  "timestamp": 1640995301,\r
+  "messageId": "session_end_ack_001",\r
+  "command": "ChatSessionEndAck",\r
+  "data": {\r
+    "sessionId": "a1b2c3d4e5f67890",\r
+    "chatId": "chat_67890"\r
+  }\r
+}\r
+```\r
+\r
+**data字段说明**：\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| sessionId | String | 对话会话ID，与请求中的sessionId对应 |\r
+| chatId | String | 请求ID，与请求中的chatId对应 |\r
+\r
+**协议说明**：\r
+- 客户端收到此应答后，应停止使用该sessionId\r
+- 会话结束后，该sessionId将不再有效\r
+- 如果需要继续对话，需要重新调用ChatSessionStart获取新的sessionId\r
+\r
 \r
 ## 7. 表情管理接口\r
 \r