Mofox-Core/消息发送API使用说明.md

消息发送API使用说明

概述

新的消息发送API允许插件直接向指定的平台和ID发送消息，无需依赖当前聊天上下文。API会自动从数据库中匹配chat_stream并构建相应的发送消息对象。

可用方法

1. send_message_to_target()

最通用的消息发送方法，支持各种类型的消息。

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:

示例用法：

# 发送文本消息到群聊
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()

便捷方法，专门用于向群聊发送文本消息。

async def send_text_to_group(
    self,
    text: str,                # 文本内容
    group_id: str,            # 群聊ID
    platform: str = "qq"      # 平台，默认为qq
) -> bool:

示例用法：

success = await self.send_text_to_group(
    text="群聊测试消息", 
    group_id="123456789"
)

3. send_text_to_user()

便捷方法，专门用于向用户发送私聊文本消息。

async def send_text_to_user(
    self,
    text: str,                # 文本内容  
    user_id: str,             # 用户ID
    platform: str = "qq"      # 平台，默认为qq
) -> bool:

示例用法：

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. 查看日志中的详细错误信息