NeoBot/src/neobot/docs/api/message.md

消息 API

发消息是机器人最基础的功能。这一页讲的是怎么发消息、撤回消息、转发消息，以及怎么用消息段（图片、@人、表情等等）。

快速开始

发一条简单的消息

from core.managers.command_manager import matcher
from models.events.message import MessageEvent

@matcher.command("hello")
async def handle_hello(event: MessageEvent):
    # 方法 1: 直接回复（最常用）
    await event.reply("你好呀！")
    
    # 方法 2: 通过 bot 实例发消息
    await event.bot.send_group_msg(event.group_id, "这是一条群消息")
    # 如果是私聊，可以用 send_private_msg
    # await event.bot.send_private_msg(event.user_id, "这是一条私聊消息")

event.reply() 是最简单的方式，它会自动判断是群聊还是私聊，然后调用正确的 API。

消息段 (MessageSegment)

除了纯文字，QQ 消息还能包含图片、@某人、表情、分享链接等等。在 OneBot 里，这些叫“消息段”。

NEO Bot 用 MessageSegment 类来表示消息段。

创建消息段

from models.message import MessageSegment

# 文本
text_seg = MessageSegment.text("这是一段文字")

# @某人
at_seg = MessageSegment.at(123456)  # @QQ号 123456
at_all = MessageSegment.at("all")    # @全体成员

# 图片
image_seg = MessageSegment.image("https://example.com/image.jpg")
# 本地图片
local_image = MessageSegment.image("file:///path/to/image.png")

# 表情 (QQ 表情，不是 emoji)
face_seg = MessageSegment(type="face", data={"id": "123"})

# 分享链接
share_seg = MessageSegment(type="share", data={
    "url": "https://example.com",
    "title": "示例网站",
    "content": "这是一个示例网站",
    "image": "https://example.com/thumb.jpg"
})

组合消息段

你可以把多个消息段组合成一条消息：

# 方法 1: 用列表
message = [
    MessageSegment.text("你好，"),
    MessageSegment.at(123456),
    MessageSegment.text("！"),
    MessageSegment.image("https://example.com/welcome.jpg")
]

# 方法 2: 用加法运算符（更直观）
message = (
    MessageSegment.text("你好，") +
    MessageSegment.at(123456) +
    MessageSegment.text("！")
)

# 发送组合消息
await event.reply(message)

从 CQ 码转换

如果你熟悉 CQ 码，也可以用 MessageSegment 来解析：

# CQ 码字符串转消息段列表（需要手动解析，这里只是示例）
# 实际使用中，框架会自动处理 CQ 码

API 方法详解

send_group_msg - 发送群消息

async def send_group_msg(
    self,
    group_id: int,
    message: Union[str, MessageSegment, List[MessageSegment]],
    auto_escape: bool = False
) -> Dict[str, Any]

参数：

• group_id: 群号
• message: 消息内容，可以是字符串、单个消息段，或消息段列表
• auto_escape: 是否对消息中的 CQ 码特殊字符进行转义（仅当 message 是字符串时有效）

示例：

# 发文字
await bot.send_group_msg(123456, "大家好！")

# 发图片
await bot.send_group_msg(123456, MessageSegment.image("https://example.com/cat.jpg"))

# 发组合消息
msg = MessageSegment.text("看这只猫：") + MessageSegment.image("https://example.com/cat.jpg")
await bot.send_group_msg(123456, msg)

send_private_msg - 发送私聊消息

async def send_private_msg(
    self,
    user_id: int,
    message: Union[str, MessageSegment, List[MessageSegment]],
    auto_escape: bool = False
) -> Dict[str, Any]

参数：

• user_id: 对方的 QQ 号
• message: 消息内容
• auto_escape: 是否转义 CQ 码

示例：

await bot.send_private_msg(123456, "你好，这是一条私聊消息")

send - 智能发送

async def send(
    self,
    event: OneBotEvent,
    message: Union[str, MessageSegment, List[MessageSegment]],
    auto_escape: bool = False
) -> Dict[str, Any]

这个方法会根据事件的类型自动选择发群消息还是私聊消息。如果事件是消息事件，它其实会调用 event.reply()。

示例：

# 在事件处理函数中
await bot.send(event, "自动判断是群聊还是私聊")

delete_msg - 撤回消息

async def delete_msg(self, message_id: int) -> Dict[str, Any]

参数：

• message_id: 要撤回的消息 ID（从消息事件中获取）

示例：

@matcher.command("recall")
async def handle_recall(event: MessageEvent):
    # 撤回上一条消息（假设我们知道 message_id）
    message_id = event.message_id
    await event.bot.delete_msg(message_id)

get_msg - 获取消息详情

async def get_msg(self, message_id: int) -> Dict[str, Any]

获取一条消息的详细信息，包括发送者、发送时间、内容等。

get_forward_msg - 获取合并转发消息

async def get_forward_msg(self, id: str) -> List[Dict[str, Any]]

获取一条合并转发消息（聊天记录）的详细内容。

参数：

• id: 合并转发消息的 ID（从消息中获取）

返回值：

• 消息节点列表，每个节点包含发送者、时间、内容等信息

合并转发

合并转发就是那种“点击展开查看聊天记录”的消息。在 QQ 里很常见。

构建转发节点

先用 bot.build_forward_node() 创建节点：

# 创建一个转发节点
node = bot.build_forward_node(
    user_id=123456,              # 发送者的 QQ 号
 nickname   ="张三",             # 显示的名字
    message="这是一条测试消息"    # 消息内容
)

# 消息内容也可以用消息段
node2 = bot.build_forward_node(
    user_id=789012,
    nickname="李四",
    message=MessageSegment.text("看这个图片：") + MessageSegment.image("https://example.com/img.jpg")
)

发送合并转发

# 方法 1: 直接发到群聊
nodes = [node1, node2, node3]
await bot.send_group_forward_msg(group_id=123456, messages=nodes)

# 方法 2: 发到私聊
await bot.send_private_forward_msg(user_id=123456, messages=nodes)

# 方法 3: 智能发送（根据事件判断）
await bot.send_forwarded_messages(target=event, nodes=nodes)

完整示例

@matcher.command("forward")
async def handleforward_(event: MessageEvent):
    # 创建几个测试节点
    nodes = [
        event.bot.build_forward_node(
            user_id=10001,
            nickname="系统",
            message="欢迎使用 NEO Bot"
        ),
        event.bot.build_forward_node(
            user_id=event.user_id,
            nickname=event.sender.nickname,
            message="这个合并转发功能真好用！"
        ),
        event.bot.build_forward_node(
            user_id=10002,
            nickname="机器人",
            message=MessageSegment.text("谢谢夸奖！") + MessageSegment.face(id="123")
        )
    ]
    
    # 发送
    await event.bot.send_forwarded_messages(event, nodes)

消息事件中的快捷方法

在消息事件 (MessageEvent) 中，有一些快捷方法：

event.reply()

await event.reply("你好！")
await event.reply(message_segment_list)

自动回复到消息来源（群聊或私聊）。

event.message

获取事件中的消息内容（已经是 MessageSegment 列表格式）。

# 检查消息是否包含图片
for segment in event.message:
    if segment.type == "image":
        await event.reply("你发了一张图片！")
        break

注意事项

1. 消息长度限制: QQ 对单条消息有长度限制，太长的消息会被截断。
2. 频率限制: 不要疯狂发消息，可能会被腾讯限制。
3. 图片缓存: 默认情况下，图片会缓存到本地，下次发送同样的图片会更快。
4. 网络错误: 发消息可能因为网络问题失败，建议做好错误处理。

下一步

现在你已经知道怎么发消息了。接下来可以看看：

• 群组 API: 管理群聊，比如禁言、踢人
• 好友 API: 处理好友相关操作
• 账号 API: 管理机器人自己的状态