feat:统一加载插件,区分内部插件和外部插件,提供示例命令发送插件

This commit is contained in:
SengokuCola
2025-06-09 23:51:12 +08:00
parent 450dad2355
commit c44811815a
22 changed files with 2029 additions and 182 deletions

View File

@@ -0,0 +1,129 @@
# 消息发送API使用说明
## 概述
新的消息发送API允许插件直接向指定的平台和ID发送消息无需依赖当前聊天上下文。API会自动从数据库中匹配chat_stream并构建相应的发送消息对象。
## 可用方法
### 1. `send_message_to_target()`
最通用的消息发送方法,支持各种类型的消息。
```python
async def send_message_to_target(
self,
message_type: str, # 消息类型text, image, emoji等
content: str, # 消息内容
platform: str, # 目标平台qq等
target_id: str, # 目标ID群ID或用户ID
is_group: bool = True, # 是否为群聊
display_message: str = "", # 显示消息(可选)
) -> bool:
```
**示例用法:**
```python
# 发送文本消息到群聊
success = await self.send_message_to_target(
message_type="text",
content="Hello, 这是一条测试消息!",
platform="qq",
target_id="123456789",
is_group=True
)
# 发送图片到私聊
success = await self.send_message_to_target(
message_type="image",
content="https://example.com/image.jpg",
platform="qq",
target_id="987654321",
is_group=False
)
# 发送表情包
success = await self.send_message_to_target(
message_type="emoji",
content="😄",
platform="qq",
target_id="123456789",
is_group=True
)
```
### 2. `send_text_to_group()`
便捷方法,专门用于向群聊发送文本消息。
```python
async def send_text_to_group(
self,
text: str, # 文本内容
group_id: str, # 群聊ID
platform: str = "qq" # 平台默认为qq
) -> bool:
```
**示例用法:**
```python
success = await self.send_text_to_group(
text="群聊测试消息",
group_id="123456789"
)
```
### 3. `send_text_to_user()`
便捷方法,专门用于向用户发送私聊文本消息。
```python
async def send_text_to_user(
self,
text: str, # 文本内容
user_id: str, # 用户ID
platform: str = "qq" # 平台默认为qq
) -> bool:
```
**示例用法:**
```python
success = await self.send_text_to_user(
text="私聊测试消息",
user_id="987654321"
)
```
## 支持的消息类型
- `"text"` - 文本消息
- `"image"` - 图片消息需要提供图片URL或路径
- `"emoji"` - 表情消息
- `"voice"` - 语音消息
- `"video"` - 视频消息
- 其他类型根据平台支持情况
## 注意事项
1. **前提条件**目标群聊或用户必须已经在数据库中存在对应的chat_stream记录
2. **权限要求**:机器人必须在目标群聊中有发言权限
3. **错误处理**所有方法都会返回bool值表示发送成功与否同时会在日志中记录详细错误信息
4. **异步调用**:所有方法都是异步的,需要使用`await`调用
## 完整示例插件
参考 `example_send_message_plugin.py` 文件该文件展示了如何在插件中使用新的消息发送API。
## 配置文件支持
可以通过TOML配置文件管理目标ID、默认平台等设置。参考 `example_config.toml` 文件。
## 错误排查
如果消息发送失败,请检查:
1. 目标ID是否正确
2. chat_stream是否已加载到ChatManager中
3. 机器人是否有相应权限
4. 网络连接是否正常
5. 查看日志中的详细错误信息