151 lines
3.7 KiB
Markdown
151 lines
3.7 KiB
Markdown
# 聊天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`对象包含了聊天的完整信息，包括用户信息、群信息等 |