gardel/Mofox-Core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chat_api_doc

Browse Source
This commit is contained in:
UnCLAS-Prommer
2025-07-27 10:23:06 +08:00
parent 47587a5e64
commit c3d9f53cb2
2 changed files with 83 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
docs/plugins/api/chat-api.md
View File

@@ -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]:
```
**参数：**
- `platform`：平台筛选，默认为"qq"
**Args**:
- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的聊天流。
**返回：**
**Returns**:
- `List[ChatStream]`：聊天流列表
**示例：**
### 2. 获取群聊聊天流
```python
streams = chat_api.get_all_streams()
for stream in streams:
print(f"聊天流ID: {stream.stream_id}")
def get_group_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
```
#### `get_group_streams(platform: str = "qq") -> List[ChatStream]`
获取所有群聊聊天流
**Args**:
- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的群聊流。
**参数：**
- `platform`：平台筛选，默认为"qq"
**返回：**
**Returns**:
- `List[ChatStream]`：群聊聊天流列表
#### `get_private_streams(platform: str = "qq") -> List[ChatStream]`
获取所有私聊聊天流
### 3. 获取私聊聊天流
**参数：**
- `platform`：平台筛选，默认为"qq"
```python
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]`
根据群ID获取聊天流
```python
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")
if chat_stream:
print(f"找到群聊: {chat_stream.group_info.group_name}")
def get_stream_by_user_id(user_id: str, platform: Optional[str] | SpecialTypes = "qq") -> Optional[ChatStream]:
```
#### `get_stream_by_user_id(user_id: str, platform: str = "qq") -> Optional[ChatStream]`
根据用户ID获取私聊流
**参数：**
**Args**:
- `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`：聊天流对象
**返回：**
- `str`：聊天类型 ("group", "private", "unknown")
**Returns**:
- `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`：聊天流对象
**返回：**
- `Dict[str, Any]`：聊天流信息字典，包含stream_id、platform、type等信息
**Returns**:
- `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)
print(f"聊天类型: {info['type']}")
print(f"平台: {info['platform']}")
if info['type'] == 'group':
print(f"群ID: {info['group_id']}")
print(f"群名: {info['group_name']}")
def get_streams_summary() -> Dict[str, int]:
```
#### `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. 所有函数都有错误处理，失败时会记录日志
2. 查询函数返回None或空列表时表示未找到结果
3. `platform`参数通常为"qq"，也可能支持其他平台
4. `ChatStream`对象包含了聊天的完整信息，包括用户信息、群信息等
1. 大部分函数在参数不合法时候会抛出异常，请确保你的程序进行了捕获。
2. `ChatStream`对象包含了聊天的完整信息，包括用户信息、群信息等。

18
src/plugin_system/apis/chat_api.py
View File

@@ -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()