From 09a45c52e7d77f801a5ab8dd651696b0566d959a Mon Sep 17 00:00:00 2001
From: root <root@minecraft-server>
Date: Wed, 15 Apr 2026 12:09:48 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20API=20=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E5=93=8D=E5=BA=94=E7=BB=93=E6=9E=84=E6=8F=8F=E8=BF=B0?=
 =?UTF-8?q?=20+=20=E6=B7=BB=E5=8A=A0=E7=BC=BA=E5=A4=B1=E6=B5=8B=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 修正 PROCESS_MESSAGE 响应数据访问路径 (result['content'] -> result['data']['content'])
- 添加 CLEAR_HISTORY 文档说明 (基于 SAVE_HISTORY 空消息实现)
- 添加 test_clear_history 和 test_send_message_is_alias 测试用例
- 优化 BackendClient 历史相关方法的返回值处理
---
 core/client.py                 | 12 ++++++----
 docs/en/api.md                 |  7 ++++--
 docs/zh/api.md                 |  6 ++++-
 tests/test_core/test_packet.py | 40 ++++++++++++++++++++++++++++++++++
 4 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/core/client.py b/core/client.py
index 4226496..b7fb2f8 100644
--- a/core/client.py
+++ b/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()
diff --git a/docs/en/api.md b/docs/en/api.md
index 35b6102..ce21791 100644
--- a/docs/en/api.md
+++ b/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
 
 ---
 
diff --git a/docs/zh/api.md b/docs/zh/api.md
index e017dad..501746c 100644
--- a/docs/zh/api.md
+++ b/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()` 方法即基于此实现
 
 ---
 
diff --git a/tests/test_core/test_packet.py b/tests/test_core/test_packet.py
index c00cdac..7be1ecc 100644
--- a/tests/test_core/test_packet.py
+++ b/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:
     """测试工具限制器"""