chat_api_doc

docs/plugins/api/chat-api.md

@@ -5,147 +5,126 @@
 ## 导入方式
 
 ```python
-from src.plugin_system.apis import chat_api
+from src.plugin_system import chat_api
 # 或者
-from src.plugin_system.apis.chat_api import ChatManager as chat
+from src.plugin_system.apis import chat_api
+```
+
+一种**Deprecated**方式：
+```python
+from src.plugin_system.apis.chat_api import ChatManager
 ```
 
 ## 主要功能
 
-### 1. 获取聊天流
+### 1. 获取所有的聊天流
 
-#### `get_all_streams(platform: str = "qq") -> List[ChatStream]`
+```python
-获取所有聊天流
+def get_all_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
+```
 
-**参数：**
+**Args**:
-- `platform`：平台筛选，默认为"qq"
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的聊天流。
 
-**返回：**
+**Returns**:
 - `List[ChatStream]`：聊天流列表
 
-**示例：**
+### 2. 获取群聊聊天流
+
 ```python
-streams = chat_api.get_all_streams()
+def get_group_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
-for stream in streams:
-    print(f"聊天流ID: {stream.stream_id}")
 ```
 
-#### `get_group_streams(platform: str = "qq") -> List[ChatStream]`
+**Args**:
-获取所有群聊聊天流
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的群聊流。
 
-**参数：**
+**Returns**:
-- `platform`：平台筛选，默认为"qq"
-
-**返回：**
 - `List[ChatStream]`：群聊聊天流列表
 
-#### `get_private_streams(platform: str = "qq") -> List[ChatStream]`
+### 3. 获取私聊聊天流
-获取所有私聊聊天流
 
-**参数：**
+```python
-- `platform`：平台筛选，默认为"qq"
+def get_private_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
+```
 
-**返回：**
+**Args**:
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的私聊流。
+
+**Returns**:
 - `List[ChatStream]`：私聊聊天流列表
 
-### 2. 查找特定聊天流
+### 4. 根据群ID获取聊天流
 
-#### `get_stream_by_group_id(group_id: str, platform: str = "qq") -> Optional[ChatStream]`
+```python
-根据群ID获取聊天流
+def get_stream_by_group_id(group_id: str, platform: Optional[str] | SpecialTypes = "qq") -> Optional[ChatStream]:
+```
 
-**参数：**
+**Args**:
 - `group_id`：群聊ID
-- `platform`：平台，默认为"qq"
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的群聊流。
 
-**返回：**
+**Returns**:
 - `Optional[ChatStream]`：聊天流对象，如果未找到返回None
 
-**示例：**
+### 5. 根据用户ID获取私聊流
+
 ```python
-chat_stream = chat_api.get_stream_by_group_id("123456789")
+def get_stream_by_user_id(user_id: str, platform: Optional[str] | SpecialTypes = "qq") -> Optional[ChatStream]:
-if chat_stream:
-    print(f"找到群聊: {chat_stream.group_info.group_name}")
 ```
 
-#### `get_stream_by_user_id(user_id: str, platform: str = "qq") -> Optional[ChatStream]`
+**Args**:
-根据用户ID获取私聊流
-
-**参数：**
 - `user_id`：用户ID
-- `platform`：平台，默认为"qq"
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的私聊流。
 
-**返回：**
+**Returns**:
 - `Optional[ChatStream]`：聊天流对象，如果未找到返回None
 
-### 3. 聊天流信息查询
+### 6. 获取聊天流类型
 
-#### `get_stream_type(chat_stream: ChatStream) -> str`
+```python
-获取聊天流类型
+def get_stream_type(chat_stream: ChatStream) -> str:
+```
 
-**参数：**
+**Args**:
 - `chat_stream`：聊天流对象
 
-**返回：**
+**Returns**:
-- `str`：聊天类型 ("group", "private", "unknown")
+- `str`：聊天流类型，可能的值包括`private`（私聊流），`group`（群聊流）以及`unknown`（未知类型）。
 
-#### `get_stream_info(chat_stream: ChatStream) -> Dict[str, Any]`
+### 7. 获取聊天流信息
-获取聊天流详细信息
 
-**参数：**
+```python
+def get_stream_info(chat_stream: ChatStream) -> Dict[str, Any]:
+```
+
+**Args**:
 - `chat_stream`：聊天流对象
 
-**返回：**
+**Returns**:
-- `Dict[str, Any]`：聊天流信息字典，包含stream_id、platform、type等信息
+- `Dict[str, Any]`：聊天流的详细信息，包括但不限于：
+    - `stream_id`：聊天流ID
+    - `platform`：平台名称
+    - `type`：聊天流类型
+    - `group_id`：群聊ID
+    - `group_name`：群聊名称
+    - `user_id`：用户ID
+    - `user_name`：用户名称
+
+### 8. 获取聊天流统计摘要
 
-**示例：**
 ```python
-info = chat_api.get_stream_info(chat_stream)
+def get_streams_summary() -> Dict[str, int]:
-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]`
+**Returns**:
-获取聊天流统计信息
+- `Dict[str, int]`：聊天流统计信息摘要，包含以下键：
+    - `total_streams`：总聊天流数量
+    - `group_streams`：群聊流数量
+    - `private_streams`：私聊流数量
+    - `qq_streams`：QQ平台流数量
 
-**返回：**
-- `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. 所有函数都有错误处理，失败时会记录日志
+1. 大部分函数在参数不合法时候会抛出异常，请确保你的程序进行了捕获。
-2. 查询函数返回None或空列表时表示未找到结果
+2. `ChatStream`对象包含了聊天的完整信息，包括用户信息、群信息等。
-3. `platform`参数通常为"qq"，也可能支持其他平台
-4. `ChatStream`对象包含了聊天的完整信息，包括用户信息、群信息等 

src/plugin_system/apis/chat_api.py

@@ -210,7 +210,7 @@ class ChatManager:
             chat_stream: 聊天流对象
 
         Returns:
-            Dict[str, Any]: 聊天流信息字典
+            Dict ({str: Any}): 聊天流信息字典
 
         Raises:
             TypeError: 如果 chat_stream 不是 ChatStream 类型
@@ -285,41 +285,41 @@ class ChatManager:
 # =============================================================================
 
 
-def get_all_streams(platform: Optional[str] | SpecialTypes = "qq"):
+def get_all_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
     """获取所有聊天流的便捷函数"""
     return ChatManager.get_all_streams(platform)
 
 
-def get_group_streams(platform: Optional[str] | SpecialTypes = "qq"):
+def get_group_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
     """获取群聊聊天流的便捷函数"""
     return ChatManager.get_group_streams(platform)
 
 
-def get_private_streams(platform: Optional[str] | SpecialTypes = "qq"):
+def get_private_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
     """获取私聊聊天流的便捷函数"""
     return ChatManager.get_private_streams(platform)
 
 
-def get_stream_by_group_id(group_id: str, platform: Optional[str] | SpecialTypes = "qq"):
+def get_stream_by_group_id(group_id: str, platform: Optional[str] | SpecialTypes = "qq") -> Optional[ChatStream]:
     """根据群ID获取聊天流的便捷函数"""
     return ChatManager.get_group_stream_by_group_id(group_id, platform)
 
 
-def get_stream_by_user_id(user_id: str, platform: Optional[str] | SpecialTypes = "qq"):
+def get_stream_by_user_id(user_id: str, platform: Optional[str] | SpecialTypes = "qq") -> Optional[ChatStream]:
     """根据用户ID获取私聊流的便捷函数"""
     return ChatManager.get_private_stream_by_user_id(user_id, platform)
 
 
-def get_stream_type(chat_stream: ChatStream):
+def get_stream_type(chat_stream: ChatStream) -> str:
     """获取聊天流类型的便捷函数"""
     return ChatManager.get_stream_type(chat_stream)
 
 
-def get_stream_info(chat_stream: ChatStream):
+def get_stream_info(chat_stream: ChatStream) -> Dict[str, Any]:
     """获取聊天流信息的便捷函数"""
     return ChatManager.get_stream_info(chat_stream)
 
 
-def get_streams_summary():
+def get_streams_summary() -> Dict[str, int]:
     """获取聊天流统计摘要的便捷函数"""
     return ChatManager.get_streams_summary()