docs: 修正 API 文档响应结构描述 + 添加缺失测试

- 修正 PROCESS_MESSAGE 响应数据访问路径 (result['content'] -> result['data']['content'])
- 添加 CLEAR_HISTORY 文档说明 (基于 SAVE_HISTORY 空消息实现)
- 添加 test_clear_history 和 test_send_message_is_alias 测试用例
- 优化 BackendClient 历史相关方法的返回值处理

core/client.py

@@ -58,13 +58,14 @@ class BackendClient:
         )
         return self._server.send(packet).body
 
-    def save_history(self, messages: list) -> None:
+    def save_history(self, messages: list) -> Dict:
         packet = Packet(
             id=self._next_id(),
             type=PacketType.SAVE_HISTORY,
             body={"messages": messages}
         )
-        self._server.send(packet)
+        response = self._server.send(packet)
+        return response.body.get("data", {})
 
     def get_history(self) -> list:
         packet = Packet(
@@ -72,7 +73,9 @@ class BackendClient:
             type=PacketType.GET_HISTORY,
             body={}
         )
-        return self._server.send(packet).body.get("history", [])
+        response = self._server.send(packet)
+        data = response.body.get("data", {})
+        return data.get("history", [])
     
     def clear_history(self) -> Dict:
         packet = Packet(
@@ -80,7 +83,8 @@ class BackendClient:
             type=PacketType.SAVE_HISTORY,
             body={"messages": []}
         )
-        return self._server.send(packet).body
+        response = self._server.send(packet)
+        return response.body.get("data", {})
     
     def shutdown(self) -> None:
         self._server.shutdown()

docs/en/api.md

@@ -103,7 +103,10 @@ client = BackendClient(server)
 result = client.process_message("Hello, please remember my name is Xiao Ming")
 
 if result.get("success"):
-    print(result["content"])
+    # Response data is in "data" field
+    print(result["data"]["content"])
+    # Tool calls: result["data"]["tool_calls"]
+    # Rejected tools: result["data"]["rejected_tools"]
 ```
 
 ---
@@ -288,7 +291,7 @@ body = {
 - Messages are automatically saved to database `chat_records` table
 - System automatically keeps only 500 most recent records, older records are deleted
 - Each call to `PROCESS_MESSAGE` will automatically save user message and AI response
-```
+- **Clear History**: Passing empty messages list `messages=[]` clears history, `client.clear_history()` method is implemented based on this
 
 ---
 

docs/zh/api.md

@@ -103,7 +103,10 @@ client = BackendClient(server)
 result = client.process_message("你好，请记住我的名字是小明")
 
 if result.get("success"):
-    print(result["content"])
+    # 响应数据在 data 字段中
+    print(result["data"]["content"])
+    # 工具调用: result["data"]["tool_calls"]
+    # 被拒绝的工具: result["data"]["rejected_tools"]
 ```
 
 ---
@@ -294,6 +297,7 @@ body = {
 - 消息自动保存到数据库 `chat_records` 表
 - 系统自动限制最多保留 500 条记录，超出后自动删除旧记录
 - 每次调用 `PROCESS_MESSAGE` 时，会自动保存用户消息和AI回复
+- **清空历史**：通过 `SAVE_HISTORY` 传递空消息列表 `messages=[]` 可清空历史，`client.clear_history()` 方法即基于此实现
 
 ---
 

tests/test_core/test_packet.py

@@ -235,6 +235,46 @@ class TestBackendClientAPI:
         
         server.shutdown()
 
+    def test_clear_history(self):
+        from core import BackendServer, BackendClient
+        server = BackendServer(db_path=":memory:", use_embedded_db=True)
+        server.start(api_key="")
+        client = BackendClient(server)
+        
+        # 先保存一些历史
+        client.save_history([
+            {"role": "user", "content": "test message 1"},
+            {"role": "assistant", "content": "test response 1"}
+        ])
+        
+        # 验证历史已保存
+        history = client.get_history()
+        assert len(history) >= 2
+        
+        # 清空历史
+        result = client.clear_history()
+        assert result.get("status") == "history_cleared"
+        
+        # 验证历史已清空
+        history = client.get_history()
+        assert len(history) == 0
+        
+        server.shutdown()
+
+    def test_send_message_is_alias(self):
+        """测试 send 方法是 process_message 的别名"""
+        from core import BackendServer, BackendClient
+        server = BackendServer(db_path=":memory:", use_embedded_db=True)
+        server.start(api_key="")
+        client = BackendClient(server)
+        
+        # send 方法应该等同于 process_message
+        # 由于没有真实 API key，应该返回失败
+        result = client.send("test")
+        assert result.get("success") is False
+        
+        server.shutdown()
+
 
 class TestToolLimiter:
     """测试工具限制器"""