doc：完善doc

docs/plugins/api/chat-api.md

@@ -0,0 +1,151 @@
+# 聊天API
+
+聊天API模块专门负责聊天信息的查询和管理，帮助插件获取和管理不同的聊天流。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import chat_api
+# 或者
+from src.plugin_system.apis.chat_api import ChatManager as chat
+```
+
+## 主要功能
+
+### 1. 获取聊天流
+
+#### `get_all_streams(platform: str = "qq") -> List[ChatStream]`
+获取所有聊天流
+
+**参数：**
+- `platform`：平台筛选，默认为"qq"
+
+**返回：**
+- `List[ChatStream]`：聊天流列表
+
+**示例：**
+```python
+streams = chat_api.get_all_streams()
+for stream in streams:
+    print(f"聊天流ID: {stream.stream_id}")
+```
+
+#### `get_group_streams(platform: str = "qq") -> List[ChatStream]`
+获取所有群聊聊天流
+
+**参数：**
+- `platform`：平台筛选，默认为"qq"
+
+**返回：**
+- `List[ChatStream]`：群聊聊天流列表
+
+#### `get_private_streams(platform: str = "qq") -> List[ChatStream]`
+获取所有私聊聊天流
+
+**参数：**
+- `platform`：平台筛选，默认为"qq"
+
+**返回：**
+- `List[ChatStream]`：私聊聊天流列表
+
+### 2. 查找特定聊天流
+
+#### `get_stream_by_group_id(group_id: str, platform: str = "qq") -> Optional[ChatStream]`
+根据群ID获取聊天流
+
+**参数：**
+- `group_id`：群聊ID
+- `platform`：平台，默认为"qq"
+
+**返回：**
+- `Optional[ChatStream]`：聊天流对象，如果未找到返回None
+
+**示例：**
+```python
+chat_stream = chat_api.get_stream_by_group_id("123456789")
+if chat_stream:
+    print(f"找到群聊: {chat_stream.group_info.group_name}")
+```
+
+#### `get_stream_by_user_id(user_id: str, platform: str = "qq") -> Optional[ChatStream]`
+根据用户ID获取私聊流
+
+**参数：**
+- `user_id`：用户ID
+- `platform`：平台，默认为"qq"
+
+**返回：**
+- `Optional[ChatStream]`：聊天流对象，如果未找到返回None
+
+### 3. 聊天流信息查询
+
+#### `get_stream_type(chat_stream: ChatStream) -> str`
+获取聊天流类型
+
+**参数：**
+- `chat_stream`：聊天流对象
+
+**返回：**
+- `str`：聊天类型 ("group", "private", "unknown")
+
+#### `get_stream_info(chat_stream: ChatStream) -> Dict[str, Any]`
+获取聊天流详细信息
+
+**参数：**
+- `chat_stream`：聊天流对象
+
+**返回：**
+- `Dict[str, Any]`：聊天流信息字典，包含stream_id、platform、type等信息
+
+**示例：**
+```python
+info = chat_api.get_stream_info(chat_stream)
+print(f"聊天类型: {info['type']}")
+print(f"平台: {info['platform']}")
+if info['type'] == 'group':
+    print(f"群ID: {info['group_id']}")
+    print(f"群名: {info['group_name']}")
+```
+
+#### `get_streams_summary() -> Dict[str, int]`
+获取聊天流统计信息
+
+**返回：**
+- `Dict[str, int]`：包含各平台群聊和私聊数量的统计字典
+
+## 使用示例
+
+### 基础用法
+```python
+from src.plugin_system.apis import chat_api
+
+# 获取所有群聊
+group_streams = chat_api.get_group_streams()
+print(f"共有 {len(group_streams)} 个群聊")
+
+# 查找特定群聊
+target_group = chat_api.get_stream_by_group_id("123456789")
+if target_group:
+    group_info = chat_api.get_stream_info(target_group)
+    print(f"群名: {group_info['group_name']}")
+```
+
+### 遍历所有聊天流
+```python
+# 获取所有聊天流并分类处理
+all_streams = chat_api.get_all_streams()
+
+for stream in all_streams:
+    stream_type = chat_api.get_stream_type(stream)
+    if stream_type == "group":
+        print(f"群聊: {stream.group_info.group_name}")
+    elif stream_type == "private":
+        print(f"私聊: {stream.user_info.user_nickname}")
+```
+
+## 注意事项
+
+1. 所有函数都有错误处理，失败时会记录日志
+2. 查询函数返回None或空列表时表示未找到结果
+3. `platform`参数通常为"qq"，也可能支持其他平台
+4. `ChatStream`对象包含了聊天的完整信息，包括用户信息、群信息等