better：优化文档
This commit is contained in:
SengokuCola
411
docs/plugins/api/message-api.md
Normal file
411
docs/plugins/api/message-api.md
Normal file
@@ -0,0 +1,411 @@
|
||||
# 📡 消息API
|
||||
|
||||
## 📖 概述
|
||||
|
||||
消息API提供了发送各种类型消息的接口，支持文本、表情、图片等多种消息类型，以及向不同目标发送消息的功能。
|
||||
|
||||
## 🔄 基础消息发送
|
||||
|
||||
### 发送文本消息
|
||||
|
||||
```python
|
||||
# 发送普通文本消息
|
||||
await self.send_text("这是一条文本消息")
|
||||
|
||||
# 发送多行文本
|
||||
message = """
|
||||
这是第一行
|
||||
这是第二行
|
||||
这是第三行
|
||||
"""
|
||||
await self.send_text(message.strip())
|
||||
```
|
||||
|
||||
### 发送特定类型消息
|
||||
|
||||
```python
|
||||
# 发送表情
|
||||
await self.send_type("emoji", "😊")
|
||||
|
||||
# 发送图片
|
||||
await self.send_type("image", "https://example.com/image.jpg")
|
||||
|
||||
# 发送音频
|
||||
await self.send_type("audio", "audio_file_path")
|
||||
```
|
||||
|
||||
### 发送命令消息
|
||||
|
||||
```python
|
||||
# 发送命令类型的消息
|
||||
await self.send_command("system_command", {"param": "value"})
|
||||
```
|
||||
|
||||
## 🎯 目标消息发送
|
||||
|
||||
### 向指定群聊发送消息
|
||||
|
||||
```python
|
||||
# 向指定群聊发送文本消息
|
||||
success = await self.api.send_text_to_group(
|
||||
text="这是发送到群聊的消息",
|
||||
group_id="123456789",
|
||||
platform="qq"
|
||||
)
|
||||
|
||||
if success:
|
||||
print("消息发送成功")
|
||||
else:
|
||||
print("消息发送失败")
|
||||
```
|
||||
|
||||
### 向指定用户发送私聊消息
|
||||
|
||||
```python
|
||||
# 向指定用户发送私聊消息
|
||||
success = await self.api.send_text_to_user(
|
||||
text="这是私聊消息",
|
||||
user_id="987654321",
|
||||
platform="qq"
|
||||
)
|
||||
```
|
||||
|
||||
### 通用目标消息发送
|
||||
|
||||
```python
|
||||
# 向任意目标发送任意类型消息
|
||||
success = await self.api.send_message_to_target(
|
||||
message_type="text", # 消息类型
|
||||
content="消息内容", # 消息内容
|
||||
platform="qq", # 平台
|
||||
target_id="123456789", # 目标ID
|
||||
is_group=True, # 是否为群聊
|
||||
display_message="显示消息" # 可选：显示消息
|
||||
)
|
||||
```
|
||||
|
||||
## 📨 消息类型支持
|
||||
|
||||
### 支持的消息类型
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|-----|------|------|
|
||||
| `text` | 普通文本消息 | "Hello World" |
|
||||
| `emoji` | 表情消息 | "😊" |
|
||||
| `image` | 图片消息 | 图片URL或路径 |
|
||||
| `audio` | 音频消息 | 音频文件路径 |
|
||||
| `video` | 视频消息 | 视频文件路径 |
|
||||
| `file` | 文件消息 | 文件路径 |
|
||||
|
||||
### 消息类型示例
|
||||
|
||||
```python
|
||||
# 文本消息
|
||||
await self.send_type("text", "普通文本")
|
||||
|
||||
# 表情消息
|
||||
await self.send_type("emoji", "🎉")
|
||||
|
||||
# 图片消息
|
||||
await self.send_type("image", "/path/to/image.jpg")
|
||||
|
||||
# 音频消息
|
||||
await self.send_type("audio", "/path/to/audio.mp3")
|
||||
|
||||
# 文件消息
|
||||
await self.send_type("file", "/path/to/document.pdf")
|
||||
```
|
||||
|
||||
## 🔍 消息查询
|
||||
|
||||
### 获取聊天类型
|
||||
|
||||
```python
|
||||
# 获取当前聊天类型
|
||||
chat_type = self.api.get_chat_type()
|
||||
|
||||
if chat_type == "group":
|
||||
print("当前是群聊")
|
||||
elif chat_type == "private":
|
||||
print("当前是私聊")
|
||||
```
|
||||
|
||||
### 获取最近消息
|
||||
|
||||
```python
|
||||
# 获取最近的5条消息
|
||||
recent_messages = self.api.get_recent_messages(count=5)
|
||||
|
||||
for message in recent_messages:
|
||||
print(f"用户: {message.user_nickname}")
|
||||
print(f"内容: {message.processed_plain_text}")
|
||||
print(f"时间: {message.timestamp}")
|
||||
```
|
||||
|
||||
### 获取当前消息信息
|
||||
|
||||
```python
|
||||
# 在Action或Command中获取当前处理的消息
|
||||
current_message = self.message
|
||||
|
||||
# 消息基本信息
|
||||
user_id = current_message.message_info.user_info.user_id
|
||||
user_nickname = current_message.message_info.user_info.user_nickname
|
||||
message_content = current_message.processed_plain_text
|
||||
timestamp = current_message.timestamp
|
||||
|
||||
# 群聊信息（如果是群聊）
|
||||
if current_message.message_info.group_info:
|
||||
group_id = current_message.message_info.group_info.group_id
|
||||
group_name = current_message.message_info.group_info.group_name
|
||||
```
|
||||
|
||||
## 🌐 平台支持
|
||||
|
||||
### 支持的平台
|
||||
|
||||
| 平台 | 标识 | 说明 |
|
||||
|-----|------|------|
|
||||
| QQ | `qq` | QQ聊天平台 |
|
||||
| 微信 | `wechat` | 微信聊天平台 |
|
||||
| Discord | `discord` | Discord聊天平台 |
|
||||
|
||||
### 平台特定功能
|
||||
|
||||
```python
|
||||
# 获取当前平台
|
||||
current_platform = self.api.get_current_platform()
|
||||
|
||||
# 根据平台调整消息格式
|
||||
if current_platform == "qq":
|
||||
# QQ平台特定处理
|
||||
await self.send_text("[QQ] 消息内容")
|
||||
elif current_platform == "wechat":
|
||||
# 微信平台特定处理
|
||||
await self.send_text("【微信】消息内容")
|
||||
```
|
||||
|
||||
## 🎨 消息格式化
|
||||
|
||||
### Markdown支持
|
||||
|
||||
```python
|
||||
# 发送Markdown格式的消息（如果平台支持）
|
||||
markdown_message = """
|
||||
**粗体文本**
|
||||
*斜体文本*
|
||||
`代码块`
|
||||
[链接](https://example.com)
|
||||
"""
|
||||
|
||||
await self.send_text(markdown_message)
|
||||
```
|
||||
|
||||
### 消息模板
|
||||
|
||||
```python
|
||||
# 使用模板生成消息
|
||||
def format_user_info(username: str, level: int, points: int) -> str:
|
||||
return f"""
|
||||
👤 用户信息
|
||||
━━━━━━━━━━━━━━━━━━
|
||||
📛 用户名: {username}
|
||||
⭐ 等级: Lv.{level}
|
||||
💰 积分: {points:,}
|
||||
━━━━━━━━━━━━━━━━━━
|
||||
""".strip()
|
||||
|
||||
# 使用模板
|
||||
user_info = format_user_info("张三", 15, 12580)
|
||||
await self.send_text(user_info)
|
||||
```
|
||||
|
||||
### 表情和Unicode
|
||||
|
||||
```python
|
||||
# 发送Unicode表情
|
||||
await self.send_text("消息发送成功 ✅")
|
||||
|
||||
# 发送表情包
|
||||
await self.send_type("emoji", "🎉")
|
||||
|
||||
# 组合文本和表情
|
||||
await self.send_text("恭喜你完成任务！🎊🎉")
|
||||
```
|
||||
|
||||
## 🔄 流式消息
|
||||
|
||||
### 获取聊天流信息
|
||||
|
||||
```python
|
||||
# 获取当前聊天流
|
||||
chat_stream = self.api.get_service("chat_stream")
|
||||
|
||||
if chat_stream:
|
||||
# 流基本信息
|
||||
stream_id = chat_stream.stream_id
|
||||
platform = chat_stream.platform
|
||||
|
||||
# 群聊信息
|
||||
if chat_stream.group_info:
|
||||
group_id = chat_stream.group_info.group_id
|
||||
group_name = chat_stream.group_info.group_name
|
||||
print(f"当前群聊: {group_name} ({group_id})")
|
||||
|
||||
# 用户信息
|
||||
user_id = chat_stream.user_info.user_id
|
||||
user_name = chat_stream.user_info.user_nickname
|
||||
print(f"当前用户: {user_name} ({user_id})")
|
||||
```
|
||||
|
||||
## 🚨 错误处理
|
||||
|
||||
### 消息发送错误处理
|
||||
|
||||
```python
|
||||
async def safe_send_message(self, content: str) -> bool:
|
||||
"""安全发送消息，包含错误处理"""
|
||||
try:
|
||||
await self.send_text(content)
|
||||
return True
|
||||
except Exception as e:
|
||||
logger.error(f"消息发送失败: {e}")
|
||||
# 发送错误提示
|
||||
try:
|
||||
await self.send_text("❌ 消息发送失败，请稍后重试")
|
||||
except:
|
||||
pass # 避免循环错误
|
||||
return False
|
||||
```
|
||||
|
||||
### 目标消息发送错误处理
|
||||
|
||||
```python
|
||||
async def send_to_group_safely(self, text: str, group_id: str) -> bool:
|
||||
"""安全向群聊发送消息"""
|
||||
try:
|
||||
success = await self.api.send_text_to_group(
|
||||
text=text,
|
||||
group_id=group_id,
|
||||
platform="qq"
|
||||
)
|
||||
|
||||
if not success:
|
||||
logger.warning(f"向群聊 {group_id} 发送消息失败")
|
||||
|
||||
return success
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"向群聊发送消息异常: {e}")
|
||||
return False
|
||||
```
|
||||
|
||||
## 📊 最佳实践
|
||||
|
||||
### 1. 消息长度控制
|
||||
|
||||
```python
|
||||
async def send_long_message(self, content: str, max_length: int = 500):
|
||||
"""发送长消息，自动分段"""
|
||||
if len(content) <= max_length:
|
||||
await self.send_text(content)
|
||||
else:
|
||||
# 分段发送
|
||||
parts = [content[i:i+max_length] for i in range(0, len(content), max_length)]
|
||||
for i, part in enumerate(parts):
|
||||
prefix = f"[{i+1}/{len(parts)}] " if len(parts) > 1 else ""
|
||||
await self.send_text(f"{prefix}{part}")
|
||||
|
||||
# 避免发送过快
|
||||
if i < len(parts) - 1:
|
||||
await asyncio.sleep(0.5)
|
||||
```
|
||||
|
||||
### 2. 消息格式规范
|
||||
|
||||
```python
|
||||
class MessageFormatter:
|
||||
"""消息格式化工具类"""
|
||||
|
||||
@staticmethod
|
||||
def success(message: str) -> str:
|
||||
return f"✅ {message}"
|
||||
|
||||
@staticmethod
|
||||
def error(message: str) -> str:
|
||||
return f"❌ {message}"
|
||||
|
||||
@staticmethod
|
||||
def warning(message: str) -> str:
|
||||
return f"⚠️ {message}"
|
||||
|
||||
@staticmethod
|
||||
def info(message: str) -> str:
|
||||
return f"ℹ️ {message}"
|
||||
|
||||
# 使用示例
|
||||
await self.send_text(MessageFormatter.success("操作成功完成"))
|
||||
await self.send_text(MessageFormatter.error("操作失败，请重试"))
|
||||
```
|
||||
|
||||
### 3. 异步消息处理
|
||||
|
||||
```python
|
||||
async def batch_send_messages(self, messages: List[str]):
|
||||
"""批量发送消息"""
|
||||
tasks = []
|
||||
|
||||
for message in messages:
|
||||
task = self.send_text(message)
|
||||
tasks.append(task)
|
||||
|
||||
# 并发发送，但控制并发数
|
||||
semaphore = asyncio.Semaphore(3) # 最多3个并发
|
||||
|
||||
async def send_with_limit(message):
|
||||
async with semaphore:
|
||||
await self.send_text(message)
|
||||
|
||||
await asyncio.gather(*[send_with_limit(msg) for msg in messages])
|
||||
```
|
||||
|
||||
### 4. 消息缓存
|
||||
|
||||
```python
|
||||
class MessageCache:
|
||||
"""消息缓存管理"""
|
||||
|
||||
def __init__(self):
|
||||
self._cache = {}
|
||||
self._max_size = 100
|
||||
|
||||
def get_cached_message(self, key: str) -> Optional[str]:
|
||||
return self._cache.get(key)
|
||||
|
||||
def cache_message(self, key: str, message: str):
|
||||
if len(self._cache) >= self._max_size:
|
||||
# 删除最旧的缓存
|
||||
oldest_key = next(iter(self._cache))
|
||||
del self._cache[oldest_key]
|
||||
|
||||
self._cache[key] = message
|
||||
|
||||
# 使用缓存避免重复生成消息
|
||||
cache = MessageCache()
|
||||
|
||||
async def send_user_info(self, user_id: str):
|
||||
cache_key = f"user_info_{user_id}"
|
||||
cached_message = cache.get_cached_message(cache_key)
|
||||
|
||||
if cached_message:
|
||||
await self.send_text(cached_message)
|
||||
else:
|
||||
# 生成新消息
|
||||
message = await self._generate_user_info(user_id)
|
||||
cache.cache_message(cache_key, message)
|
||||
await self.send_text(message)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
🎉 **现在你已经掌握了消息API的完整用法！继续学习其他API接口。**
|
||||
Reference in New Issue
Block a user