melobot.models

事件类型

melobot 主要包含四种事件类型：MessageEvent, RequestEvent, NoticeEvent, MetaEvent。

class melobot.models.MessageEvent

基类：BotEvent

消息事件类型

提示

一般无需手动实例化该类，多数情况会直接使用本类对象，或将本类用作类型注解。

bot_id: int

收到事件的机器人 qq 号

id: int

消息事件的消息 id

raw_content: str

使用 CQ 字符串表示的，本事件的所有消息内容

content: list[MsgSegment]

使用消息段对象列表表示的，本事件的所有消息内容

sender: Sender

消息事件的发送者数据结构

group_id: int | None

消息事件的来源群号，私聊时此属性也存在并为 None

text: str

本事件的所有消息内容中，纯文本消息的合并字符串

font: int

消息字体

temp_src: str | None

临时消息的来源标记，不是临时消息时为 None

property time: int

事件发生时刻的时间戳

property type: Literal['message']

事件的类型（返回指定字面量）

get_segments(type: str) → list[MsgSegment]

提取指定类型的，消息段对象组成的消息段对象列表

参数:

type – 消息段类型（对应 OneBot 标准中每种消息段对象的 type）

返回:

消息段对象列表

get_datas(type: str, data: str, convert: Callable[[Any], Any] | None = None) → list[Any]

提取指定类型的消息段对象中的指定数据

当没有任何对应类型的消息段时，为空列表。如果有对应类型的消息段，但是指定的数据键名不存在， 则在列表中产生 None 值.

可以指定 convert 来强制转换类型，不填则不使用类型转换

使用示例如下：

# 假设 event 是 MessageEvent 对象，即象征一个消息事件
datas = event.get_datas('at', 'qq')
# datas 将是此事件中，所有 at 消息段的 "qq" 数据值所组成的列表

参数:

• type – 消息段类型（对应 OneBot 标准中每种消息段对象的 type）

• data – 消息段对象 data 中的键名

• convert – 类型转换使用的函数

返回:

值列表

is_private() → bool

是否为私聊消息（注意群临时会话属于该类别）

is_friend() → bool

是否为好友消息

is_group() → bool

是否为群消息（正常群消息、群匿名消息、群自身消息、群系统消息属于该类型）

is_group_normal() → bool

是否为正常群消息

is_group_anonym() → bool

是否为匿名群消息

is_group_self() → bool

是否为群自身消息（即 bot 自己群中发的消息）

is_group_temp() → bool

是否为群临时会话（属于私聊的一种）

is_temp() → bool

是否为临时会话（属于私聊的一种）

is_group_notice() → bool

是否为群中的”系统消息”

class Sender

基类：object

消息事件发送者数据结构

提示

一般无需手动实例化该类，多数情况会直接使用本类对象，或将本类用作类型注解。

id: int

发送者的 qq 号

nickname: str | None

发送者昵称

sex: str | None

发送者性别

age: int | None

发送者年龄

group_card: str | None

发送者的群名片

group_role: Literal['owner', 'admin', 'member', 'anonymous'] | None

发送者的群中角色

group_title: str | None

发送者的群头衔

group_area: str | None

发送者的地区

group_level: str | None

发送者的群等级

anonym_id: int | None

匿名发送者的 id（此属性只在事件为群匿名消息事件时存在）

anonym_name: str | None

匿名发送者的名字（此属性只在事件为群匿名消息事件时存在）

anonym_flag: str | None

匿名发送者的匿名 flag（此属性只在事件为群匿名消息事件时存在）

is_group_owner() → bool

判断是否为群主，若不是或不是群类型消息，返回 False

is_group_admin() → bool

判断是否为群管理（包含群主），若不是或不是群类型消息，返回 False

only_group_member() → bool

判断是否只是群员（注意只是群员，不包括群主、管理和匿名），若不是或不是群类型消息，返回 False

is_bot() → bool

判断消息是否是bot自己发送的

class melobot.models.RequestEvent

基类：BotEvent

请求事件类型，对应两种可能：加好友请求和加群请求

提示

一般无需手动实例化该类，多数情况会直接使用本类对象，或将本类用作类型注解。

bot_id: int

收到事件的机器人 qq 号

group_req_type: Literal['add', 'invite'] | None

加群请求类型：直接加入和邀请，请求来源于私聊时此属性为 None

operator_id: int

事件的来源 qq 号

group_id: int | None

事件的来源群号，请求来源于私聊时此属性为 None

req_comment: str

加群或加好友的验证消息

req_flag: str

加群或加好友请求的 flag，调用相关 API 时，需要使用

property time: int

事件发生时刻的时间戳

property type: Literal['request']

事件的类型（返回指定字面量）

is_friend_req() → bool

是否为加好友请求

is_group_req() → bool

是否为加群请求

class melobot.models.NoticeEvent

基类：BotEvent

通知事件类型

提示

一般无需手动实例化该类，多数情况会直接使用本类对象，或将本类用作类型注解。

注意

受 onebot 协议实现项目的影响，及对通知事件本身复杂性的考虑，通知事件大多数实例属性， 只会在特定类别的通知事件中存在。各个属性的含义与存在的时机，已在下方的注释说明。

如果你仍不确定某个属性在何时出现，建议直接调试查看存在的属性。例如通过 print(event.__dict__) 或调试器查看。

bot_id: int

收到事件的机器人 qq 号

user_id: int

通知作用者或主体方的 id，如被禁言的一方

group_id: int

通知若发生在群中的群 id

operator_id: int

通知发起者或操作方的 id，如禁言别人的管理员

msg_id: int

通知涉及消息时的消息 id

join_group_type: Literal['approve', 'invite']

入群通知事件的入群类型：管理员同意或管理员邀请

leave_group_type: Literal['leave', 'kick', 'kick_me']

退群通知事件的退群类型：自退群、踢出、bot 账号被踢

admin_change_type: Literal['set', 'unset']

群管理员变动通知事件类型：设置管理员或取消管理员

file: File

文件上传通知事件的文件信息数据结构

group_ban_type: Literal['ban', 'lift_ban']

群禁言通知事件的类型：禁言、解除禁言

ban_time: int

群禁言通知事件的禁言时长

honor_change_type: Literal['talkactive', 'performer', 'emotion']

群荣誉变更通知事件的荣誉类型：龙王、群聊之火、快乐源泉

new_title: str

群头衔变更通知事件的新头衔

old_card: str

群名片更新通知事件的旧名片，名片为空时对应属性为空字符串

new_card: str

群名片更新通知事件的新名片，名片为空时对应属性为空字符串

client: Client

客户端在线状态变更的通知事件的，客户端信息数据结构

essence_change_type: Literal['add', 'delete']

精华消息变更通知事件的类型：添加或删除

property time: int

事件发生的时间

property type: Literal['notice']

事件类型

is_group() → bool

是否是来自群的通知事件

is_group_upload() → bool

是否是群文件上传通知

is_group_admin() → bool

是否是群管理员变更通知

is_group_decrease() → bool

是否是群成员减少通知

is_group_increase() → bool

是否是群成员增加通知

is_group_ban() → bool

是否是群禁言通知

is_friend_add() → bool

是否是好友添加通知

is_group_recall() → bool

是否是群聊消息撤回通知

is_friend_recall() → bool

是否是私聊消息撤回通知

is_group_card() → bool

是否是群名片变更通知

is_offline_file() → bool

是否是离线文件上传通知（即私聊文件上传）

is_client_status() → bool

是否是客户端状态通知

is_essence() → bool

是否是精华消息变更通知

is_notify() → bool

是否为系统通知（包含群荣誉变更、戳一戳、群红包幸运王、群成员头衔变更）

is_honor() → bool

是否是群荣誉变更通知

is_poke() → bool

是否是戳一戳通知

is_lucky_king() → bool

是否是群红包幸运王通知

is_title() → bool

是否是群成员头衔变更通知

class File

基类：object

文件上传通知的文件信息数据结构

提示

一般无需手动实例化该类，多数情况会直接使用本类对象，或将本类用作类型注解。

name: str

文件名

size: int

文件大小

id: str | None

文件 id，私聊文件上传时为 None

busid: int | None

文件 busid，私聊文件上传时为 None

url: str | None

文件 url 地址，群聊文件上传时为 None

class Client

基类：object

客户端在线状态变更通知的客户端信息数据结构

提示

一般无需手动实例化该类，多数情况会直接使用本类对象，或将本类用作类型注解。

online: bool

当前客户端是否在线

id: int

当前客户端 id

name: str

客户端设备名称

kind: str

客户端设备类型

class melobot.models.MetaEvent

基类：BotEvent

元事件类型

提示

一般无需手动实例化该类，多数情况会直接使用本类对象，或将本类用作类型注解。

bot_id: int

收到事件的机器人 qq 号

property time: int

事件发生时刻的时间戳

property type: Literal['meta']

事件的类型（返回指定字面量）

is_lifecycle() → bool

是否是生命周期类型的元事件

is_heartbeat() → bool

是否是心跳类型的元事件

消息构造

在 melobot 中，使用以下函数构造符合 onebot 标准的消息段。不过部分标准中的方法没有被包含，同时部分方法有所改变。

melobot.models.text_msg(text: str) → MsgSegment

生成普通文本消息

参数详细说明参考 onebot 标准：纯文本

参数:

text – 文本内容

返回:

onebot 标准中的消息段对象

melobot.models.face_msg(id: int) → MsgSegment

生成 qq 表情消息

参数详细说明参考 onebot 标准：QQ 表情

参数:

id – qq 表情的 ID

返回:

onebot 标准中的消息段对象

melobot.models.record_msg(file: str, magic: Literal[0, 1] = 0, cache: Literal[0, 1] = 1, proxy: Literal[0, 1] = 1, timeout: int | None = None) → MsgSegment

生成语音消息

参数详细说明参考 onebot 标准：语音

参数:

• file – 语音文件名

• magic – 是否使用变声

• cache – 是否使用已缓存文件

• proxy – 是否通过代理下载文件

• timeout – 超时时间，默认不启用

返回:

onebot 标准中的消息段对象

melobot.models.at_msg(qq: int | Literal['all']) → MsgSegment

生成艾特消息

参数详细说明参考 onebot 标准：某人

参数:

qq – 艾特的 qq 号，”all” 表示艾特全体成员

返回:

onebot 标准中的消息段对象

melobot.models.share_msg(url: str, title: str, content: str | None = None, image: str | None = None) → MsgSegment

生成链接分享消息

参数详细说明参考 onebot 标准：链接分享

参数:

• url – 链接的 url

• title – 消息的标题

• content – 消息的内容描述（可选）

• image – 消息的封面图 url（可选）

返回:

onebot 标准中的消息段对象

melobot.models.music_msg(type: Literal['qq', '163', 'xm'], id: str) → MsgSegment

生成音乐分享消息

参数详细说明参考 onebot 标准：音乐分享

参数:

• type – 音乐平台的类型（q 音、网易云、虾米）

• id – 歌曲 id

返回:

onebot 标准中的消息段对象

melobot.models.custom_music_msg(url: str, audio: str, title: str, content: str | None = None, image: str | None = None) → MsgSegment

生成音乐自定义分享 url

参数详细说明参考 onebot 标准：音乐自定义分享

参数:

• url – 点击后跳转目标 url

• audio – 音乐 url

• title – 标题

• content – 内容描述（可选）

• image – 封面图 url（可选）

返回:

onebot 标准中的消息段对象

melobot.models.image_msg(file: str, type: Literal['flash'] | None = None, cache: Literal[0, 1] = 1, proxy: Literal[0, 1] = 1, timeout: int | None = None) → MsgSegment

生成图片消息

参数详细说明参考 onebot 标准：图片

参数:

• file – 图片文件名或图片 base64 内容

• type – 图片类型

• cache – 是否使用已缓存的文件

• proxy – 是否通过代理下载文件

• timeout – 超时时间，默认不超时

返回:

onebot 标准中的消息段对象

melobot.models.reply_msg(id: int) → MsgSegment

生成回复消息

参数详细说明参考 onebot 标准：回复

参数:

id – 消息 id

返回:

onebot 标准中的消息段对象

melobot.models.poke_msg(qq: int) → MsgSegment

生成戳一戳消息

提示

鉴于目前大多数实现 cq 协议的项目都采用了此参数规范，因此在 melobot 中，也采用此规范。虽然这种规范实际上不符合 onebot 标准

参数:

qq – 戳的 qq 号

返回:

onebot 标准中的消息段对象

melobot.models.xml_msg(data: str) → MsgSegment

生成 xml 消息

参数详细说明参考 onebot 标准：xml 消息

参数:

data – xml 内容

返回:

onebot 标准中的消息段对象

melobot.models.json_msg(data: str) → MsgSegment

生成 json 消息

参数详细说明参考 onebot 标准：json 消息

参数:

data – json 内容

返回:

onebot 标准中的消息段对象

melobot.models.custom_msg_node(content: str | MsgSegment | list[MsgSegment], sendName: str, sendId: int, seq: list[MsgSegment] | None = None, useStd: bool = False) → MsgNode

生成一个自定义合并消息转发结点

提示

鉴于此方法涉及的消息构造，存在两种规范： onebot 规范、 go-cq 规范， 因此在 melobot 中，支持你使用 useStd 参数自定义选择哪种风格来构造

参数:

• content – 消息结点内容

• sendName – 消息结点标记的发送人名字

• sendId – 消息结点标记的发送人 qq 号

• seq – 消息 seq 号（一般来说你不需要使用这个）

• useStd – 消息段对象构造时是否遵循 onebot 标准，默认为否（使用 go-cq 风格）

返回:

onebot 标准中的消息段对象

melobot.models.refer_msg_node(id: int) → MsgNode

生成一个引用合并消息转发结点

参数:

id – 消息 id

返回:

onebot 标准中的消息段对象

melobot.models.forward_msg(forwardId: str) → MsgSegment

生成一条完整的转发消息，以消息段的形式

注意

这与通过结点来构造转发消息是不同的，这里直接构造一个消息段对象，就可以代表整条转发消息。 因为这里使用的是转发 id。

参数详细说明参考 onebot 标准：forward 消息段

参数:

forwardId – 转发 id

返回:

onebot 标准中的消息段对象

自定义消息内容

该方法可构造自定义的消息段对象，实现自定义的消息段。

melobot.models.custom_type_msg(type: str, params: dict[str, str]) → MsgSegment

生成一个自定义消息段对象

参数:

• type – 消息段对象的类型标识

• params – 消息段的参数

返回:

符合 onebot 格式，但不在 onebot 标准中的消息段对象

消息内容处理

使用以下函数可以处理消息内容，例如进行消息格式转换或实现特定的处理。

提示

这些函数过于底层，在 melobot 实际使用中并不常用。有所了解即可。

melobot.models.cq_filter_text(s: str) → str

cq 文本过滤函数

可从 cq 字符串中过滤出纯文本消息部分

参数:

s – cq 字符串

返回:

纯文本消息部分

melobot.models.cq_escape(text: str) → str

cq 字符串特殊符号转义

如：将 “&” 转义为 “&”

参数:

text – 需要转义的 cq 字符串

返回:

转义特殊符号后的 cq 字符串

melobot.models.cq_anti_escape(text: str) → str

cq 字符串特殊符号逆转义

如：将 “&” 逆转义为 “&”

参数:

text – 需要逆转义的 cq 字符串

返回:

逆转义特殊符号后的 cq 字符串

melobot.models.to_segments(s: str) → list[MsgSegment]

将 cq 字符串转换为消息段对象列表

参数:

s – cq 字符串

返回:

消息段对象列表

melobot.models.to_cq_str(content: list[MsgSegment]) → str

将消息段对象列表转换为 cq 字符串

参数:

content – 消息段对象列表

返回:

cq 字符串