melobot.context

会话

会话是 melobot 的重要机制之一。以下是涉及会话控制和会话信息获取的相关类和函数：

class melobot.context.SessionOption

会话配置类

__init__(rule: ~melobot.base.abc.SessionRule[~melobot.base.abc.Event_T] | ~typing.Callable[[~melobot.base.abc.Event_T, ~melobot.base.abc.Event_T], bool] = <melobot.context.session.LegacyRule object>, second_pass: bool = True, conflict_wait: bool = True, conflict_cb: ~typing.Callable[[], ~typing.Awaitable[None]] | None = None, hold: bool = False) → None

创建一个会话配置

参数:

• rule – 会话规则，为空则使用默认会话规则

• second_pass – 会话暂停后，是否不进行预处理就唤醒会话

• conflict_wait – 会话冲突时，同会话事件是否等待处理

• conflict_cb – 会话冲突时，同会话事件不等待处理，转而运行的回调（conflict_wait=False 时生效）

• hold – 事件处理方法结束后是否保留会话

melobot.context.any_event() → BotEvent

获取当前会话下的事件

返回:

具体的事件

melobot.context.msg_event() → MessageEvent

获取当前会话下的事件

确定此事件是消息事件时使用，例如在消息事件的处理函数中，使用该方法即可获得精准的类型提示

返回:

具体的事件

melobot.context.msg_args() → list[Any] | None

获取当前会话下的消息事件的所有解析参数值。

只能在确定当前会话下必为消息事件时使用

返回:

解析参数值列表或 None

melobot.context.msg_text() → str

获取当前会话下的，消息事件的纯文本内容的合并字符串。 等价于手动读取消息事件的 text 属性

只能在确定当前会话下必为消息事件时使用

返回:

纯文本内容的合并字符串

melobot.context.req_event() → RequestEvent

获取当前会话下的事件

确定此事件是请求事件时使用，例如在请求事件的处理函数中，使用该方法即可获得精准的类型提示

返回:

具体的事件

melobot.context.notice_event() → NoticeEvent

获取当前会话下的事件

确定此事件是通知事件时使用，例如在通知事件的处理函数中，使用该方法即可获得精准的类型提示

返回:

具体的事件

melobot.context.meta_event() → MetaEvent

获取当前会话下的事件

确定此事件是元事件时使用，例如在元事件的处理函数中，使用该方法即可获得精准的类型提示

返回:

具体的事件

melobot.context.session_store() → dict

返回当前会话的存储字典对象，可直接操作

会话存储字典对象用于在会话层面保存和共享数据。

返回:

会话的存储字典对象

async melobot.context.pause(overtime: float | None = None) → None

会话暂停直到被同一会话的事件唤醒

暂时停止本会话。当本会话的会话规则判断有属于本会话的另一事件发生， 本会话将自动被唤醒。

可指定超时时间。如果超时时间结束会话仍未被唤醒，此时将会被强制唤醒， 并抛出一个 BotSessionTimeout 异常。可以捕获此异常， 实现自定义的超时处理逻辑

参数:

overtime – 超时时间

melobot.context.dispose() → None

销毁当前会话

将会清理会话的存储空间，并将会话标记为过期态。 此时调用该方法的函数依然可以运行，但是此会话状态下无法再进行行为操作。

一般来说，会话将会自动销毁。 只有在绑定事件处理函数时使用 session_hold=True，才会需要使用此函数。

高级行为操作

所有行为操作分为两大类：高级行为操作与基本行为操作。高级行为操作是 melobot 在 onebot 标准的基础上，利用会话信息进一步封装的行为操作。

以下函数均为高级行为操作函数：

melobot.context.send(content: str | MsgSegment | list[MsgSegment], cq_str: bool = False, wait: bool = False, auto: bool = True) → ActionHandle

发送消息（在当前会话下自动定位发送目标）

小技巧

当启用了 cq_str 选项，且 content 参数为字符串时， content 字符串将不会被处理为消息段对象，此时字符串中的 cq 码将会直接生效，而不是被转义。

警告

这个小技巧可以让你直接发送 CQ 码字符串。但是存在潜在的安全问题： 如果将用户输入作为 CQ 码字符串的一部分发送出去，这将会造成“注入攻击”！ 用户可以构造包含恶意图片、语音的 CQ 码，让 bot 发送。

任何时候启用 cq_str 选项，如需用到用户输入，务必校验。

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-2

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• content – 发送内容（可以是文本、消息段对象、消息段对象列表）

• cq_str – 是否以 cq 字符串发送（默认格式是消息段对象)

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.send_forward(msgNodes: list[MsgNode], cq_str: bool = False, wait: bool = False, auto: bool = True) → ActionHandle

发送转发消息（在当前会话下自动定位发送目标）

小技巧

当启用了 cq_str 选项，且 content 参数为字符串时， content 字符串将不会被处理为消息段对象，此时字符串中的 cq 码将会直接生效，而不是被转义。

警告

这个小技巧可以让你直接发送 CQ 码字符串。但是存在潜在的安全问题： 如果将用户输入作为 CQ 码字符串的一部分发送出去，这将会造成“注入攻击”！ 用户可以构造包含恶意图片、语音的 CQ 码，让 bot 发送。

任何时候启用 cq_str 选项，如需用到用户输入，务必校验。

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考：

{
    "message_id": xxx,  # int
    "forward_id": xxx   # str
}

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• msgNodes – 消息结点列表

• cq_str – 是否以 cq 字符串发送（默认格式是消息段对象)

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

async melobot.context.send_wait(content: str | MsgSegment | list[MsgSegment], cq_str: bool = False, overtime: int | None = None) → None

发送一条消息然后暂停当前会话（在当前会话下自动定位发送目标）

会话应该是可暂停的，这意味着该会话应该拥有会话规则。

小技巧

当启用了 cq_str 选项，且 content 参数为字符串时， content 字符串将不会被处理为消息段对象，此时字符串中的 cq 码将会直接生效，而不是被转义。

警告

这个小技巧可以让你直接发送 CQ 码字符串。但是存在潜在的安全问题： 如果将用户输入作为 CQ 码字符串的一部分发送出去，这将会造成“注入攻击”！ 用户可以构造包含恶意图片、语音的 CQ 码，让 bot 发送。

任何时候启用 cq_str 选项，如需用到用户输入，务必校验。

参数:

• content – 发送内容

• cq_str – 是否以 cq 字符串发送（默认格式是消息段对象)

• overtime – 会话暂停的超时时间，超时将抛出 BotSessionTimeout 异常

async melobot.context.send_reply(content: str | MsgSegment | list[MsgSegment], cq_str: bool = False, auto: bool = True) → None

发送一条回复消息（在当前会话下自动定位发送目标）

小技巧

当启用了 cq_str 选项，且 content 参数为字符串时， content 字符串将不会被处理为消息段对象，此时字符串中的 cq 码将会直接生效，而不是被转义。

警告

这个小技巧可以让你直接发送 CQ 码字符串。但是存在潜在的安全问题： 如果将用户输入作为 CQ 码字符串的一部分发送出去，这将会造成“注入攻击”！ 用户可以构造包含恶意图片、语音的 CQ 码，让 bot 发送。

任何时候启用 cq_str 选项，如需用到用户输入，务必校验。

参数:

• content – 发送内容

• cq_str – 是否以 cq 字符串发送（默认格式是消息段对象)

• auto – 是否自动发送

async melobot.context.finish(content: str | MsgSegment | list[MsgSegment], cq_str: bool = False) → None

发送一条消息，然后直接结束当前事件处理方法（在当前会话下自动定位发送目标）

只可在事件处理方法中使用。

小技巧

当启用了 cq_str 选项，且 content 参数为字符串时， content 字符串将不会被处理为消息段对象，此时字符串中的 cq 码将会直接生效，而不是被转义。

警告

这个小技巧可以让你直接发送 CQ 码字符串。但是存在潜在的安全问题： 如果将用户输入作为 CQ 码字符串的一部分发送出去，这将会造成“注入攻击”！ 用户可以构造包含恶意图片、语音的 CQ 码，让 bot 发送。

任何时候启用 cq_str 选项，如需用到用户输入，务必校验。

参数:

• content – 发送内容

• cq_str – 是否以 cq 字符串发送（默认格式是消息段对象)

async melobot.context.reply_finish(content: str | MsgSegment | list[MsgSegment], cq_str: bool = False) → None

发送一条回复消息，然后直接结束当前事件处理方法（在当前会话下自动定位发送目标）

只可在事件处理方法中使用。

小技巧

当启用了 cq_str 选项，且 content 参数为字符串时， content 字符串将不会被处理为消息段对象，此时字符串中的 cq 码将会直接生效，而不是被转义。

警告

这个小技巧可以让你直接发送 CQ 码字符串。但是存在潜在的安全问题： 如果将用户输入作为 CQ 码字符串的一部分发送出去，这将会造成“注入攻击”！ 用户可以构造包含恶意图片、语音的 CQ 码，让 bot 发送。

任何时候启用 cq_str 选项，如需用到用户输入，务必校验。

参数:

• content – 发送内容

• cq_str – 是否以 cq 字符串发送（默认格式是消息段对象)

基本行为操作

基本行为操作是与 onebot 标准中的“API 接口”相吻合的行为操作。

注意部分 onebot API 接口在 melobot 中未提供支持：

注意

在 onebot 标准 中，以下不常用或难以被 onebot 实现项目实现的行为操作暂时不支持：

• set_group_anonymous_ban 群组匿名用户禁言

• set_group_anonymous 群组匿名

• get_cookies 获取 Cookies

• get_csrf_token 获取 CSRF Token

• get_credentials 获取 QQ 相关接口凭证

• set_restart 重启 OneBot 实现

• clean_cache 清理缓存

另外为提升 API 接口可读性，部分接口名称与 onebot 标准不同，请注意辨别。还有部分接口被合并（如发送私聊消息与发送群聊消息）

melobot.context.send_custom(content: str | MsgSegment | list[MsgSegment], isPrivate: bool, userId: int | None = None, groupId: int | None = None, cq_str: bool = False, wait: bool = False, auto: bool = True) → ActionHandle

发送消息（自定义发送目标）

小技巧

当启用了 cq_str 选项，且 content 参数为字符串时， content 字符串将不会被处理为消息段对象，此时字符串中的 cq 码将会直接生效，而不是被转义。

警告

这个小技巧可以让你直接发送 CQ 码字符串。但是存在潜在的安全问题： 如果将用户输入作为 CQ 码字符串的一部分发送出去，这将会造成“注入攻击”！ 用户可以构造包含恶意图片、语音的 CQ 码，让 bot 发送。

任何时候启用 cq_str 选项，如需用到用户输入，务必校验。

此接口合并了 onebot 标准中的私聊消息发送、群聊消息发送接口。

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-2

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• content – 发送内容

• isPrivate – 是否是私聊

• userId – 如果是私聊，传入目标 qq 号；群聊置空即可

• groupId – 如果是群聊，传入群号；私聊置空即可

• cq_str – 是否以 cq 字符串发送（默认格式是消息段对象)

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.send_custom_forward(msgNodes: list[MsgNode], isPrivate: bool, userId: int | None = None, groupId: int | None = None, cq_str: bool = False, wait: bool = False, auto: bool = True) → ActionHandle

发送转发消息（自定义发送目标）

小技巧

当启用了 cq_str 选项，且 content 参数为字符串时， content 字符串将不会被处理为消息段对象，此时字符串中的 cq 码将会直接生效，而不是被转义。

警告

这个小技巧可以让你直接发送 CQ 码字符串。但是存在潜在的安全问题： 如果将用户输入作为 CQ 码字符串的一部分发送出去，这将会造成“注入攻击”！ 用户可以构造包含恶意图片、语音的 CQ 码，让 bot 发送。

任何时候启用 cq_str 选项，如需用到用户输入，务必校验。

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考：

{
    "message_id": xxx,  # int
    "forward_id": xxx   # str
}

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• msgNodes – 消息结点列表

• isPrivate – 是否是私聊

• userId – 如果是私聊，传入目标 qq 号；群聊置空即可

• groupId – 如果是群聊，传入群号；私聊置空即可

• cq_str – 是否以 cq 字符串发送（默认格式是消息段对象)

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.msg_recall(msgId: int, wait: bool = False, auto: bool = True) → ActionHandle

撤回消息

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-3

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• msgId – 消息 id

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_msg(msgId: int, wait: bool = True, auto: bool = True) → ActionHandle

获取消息详细信息

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-4

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• msgId – 消息 id

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_forward_msg(forwardId: str, wait: bool = True, auto: bool = True) → ActionHandle

获取转发消息的详细信息

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-5

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• forwardId – 转发 id

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_image(fileName: str, wait: bool = True, auto: bool = True) → ActionHandle

获取图片信息

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-31

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• fileName – 图片文件名

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.send_like(userId: int, times: int = 1, wait: bool = False, auto: bool = True) → ActionHandle

发送好友赞

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-6

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• userId – qq 号

• times – 赞的数量，默认为 1，每天最多 10

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.group_kick(groupId: int, userId: int, laterReject: bool = False, wait: bool = False, auto: bool = True) → ActionHandle

群组踢人

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-7

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• userId – 被踢的 qq 号

• laterReject – 是否拒绝此人再次加群

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.group_ban(groupId: int, userId: int, duration: int, wait: bool = False, auto: bool = True) → ActionHandle

群组禁言

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-8

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• userId – 禁言的 qq 号

• duration – 禁言时长，为 0 则表示取消禁言

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.group_whole_ban(groupId: int, enable: bool, wait: bool = False, auto: bool = True) → ActionHandle

群组全员禁言

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-10

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• enable – 是则禁言，否则取消禁言

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.set_group_admin(groupId: int, userId: int, enable: bool, wait: bool = False, auto: bool = True) → ActionHandle

设置群管理员

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-11

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• userId – 设置的 qq 号

• enable – 是则设置，否则取消

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.set_group_card(groupId: int, userId: int, card: str, wait: bool = False, auto: bool = True) → ActionHandle

设置群名片

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-13

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• userId – 设置的 qq 号

• card – 新名片内容

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.set_group_name(groupId: int, name: str, wait: bool = False, auto: bool = True) → ActionHandle

设置群名

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-14

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• name – 新群名

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.group_leave(groupId: int, isDismiss: bool, wait: bool = False, auto: bool = True) → ActionHandle

退出群

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-15

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• isDismiss – 是否解散群（仅在 bot 为群主时可用）

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.set_group_title(groupId: int, userId: int, title: str, duration: int = -1, wait: bool = False, auto: bool = True) → ActionHandle

设置群特殊头衔

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-16

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• userId – 设置的 qq 号

• title – 头衔名

• duration – 生效时间，为 -1 则为无限期

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.set_friend_add(addFlag: str, approve: bool, remark: str, wait: bool = False, auto: bool = True) → ActionHandle

处理加好友请求

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-17

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• addFlag – 好友添加 flag，对应 req_flag 属性

• approve – 是否通过

• remark – 添加后的好友备注（仅用于通过请求后）

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.set_group_add(addFlag: str, addType: Literal['add', 'invite'], approve: bool, rejectReason: str | None = None, wait: bool = False, auto: bool = True) → ActionHandle

处理加群请求（只有 bot 是群管理时有用）

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-18

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• addFlag – 加群 flag，对应 req_flag 属性

• addType – 加群类型，对应 group_req_type 属性

• approve – 是否通过

• rejectReason – 如果不通过的原因回复

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_login_info(wait: bool = True, auto: bool = True) → ActionHandle

获得 bot 登录号信息

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-19

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_stranger_info(userId: int, noCache: bool, wait: bool = True, auto: bool = True) → ActionHandle

获取陌生人信息，也可以对好友使用

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-20

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• userId – qq 号

• noCache – 是否不使用缓存

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_friend_list(wait: bool = True, auto: bool = True) → ActionHandle

获取好友列表

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-21

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_group_info(groupId: int, noCache: bool, wait: bool = True, auto: bool = True) → ActionHandle

获取群信息，可以是未加入的群聊

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-22

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• noCache – 是否不使用缓存

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_group_list(wait: bool = True, auto: bool = True) → ActionHandle

获取群列表。

可能返回的建群时间都是 0，这是不准确的。准确的时间可以通过 get_group_info() 获得

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-23

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_group_member_info(groupId: int, userId: int, noCache: bool, wait: bool = True, auto: bool = True) → ActionHandle

获取群成员信息

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-24

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• userId – qq 号

• noCache – 是否不使用缓存

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_group_member_list(groupId: int, noCache: bool, wait: bool = True, auto: bool = True) → ActionHandle

获取群成员列表

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-25

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• noCache – 是否不使用缓存

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_group_honor(groupId: int, type: Literal['talkative', 'performer', 'legend', 'strong_newbie', 'emotion', 'all'], wait: bool = True, auto: bool = True) → ActionHandle

获取群荣誉信息

详细说明参考： 获取群荣誉信息

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-26

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• groupId – 群号

• type – 荣誉类型

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.check_send_image(wait: bool = True, auto: bool = True) → ActionHandle

检查是否可以发送图片

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-32

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.check_send_record(wait: bool = True, auto: bool = True) → ActionHandle

检查是否可以发送语音

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-33

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_onebot_version(wait: bool = True, auto: bool = True) → ActionHandle

获取 onebot 实现项目的版本

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-35

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

melobot.context.get_onebot_status(wait: bool = True, auto: bool = True) → ActionHandle

获取 onebot 实现项目的状态

响应数据在返回对象的 ActionHandle.resp.data 属性，数据结构参考： 响应数据-34

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• wait – 是否等待这个行为完成

• auto – 是否自动发送

返回:

ActionHandle 对象

手动行为操作

如果因为兼容性问题，你需要创建 melobot 预置行为操作函数无法创建的 onebot 标准行为，可以使用以下函数生成自定义的行为操作：

melobot.context.custom_action(type: str, params: dict, wait: bool = False, trigger: BotEvent | None = None) → ActionHandle

创建并自动提交一个自定义行为

提示

本函数虽然是同步函数，但返回的对象 ActionHandle 是可等待的（可使用 await）。 使用 await 会立即发生异步切换，这会使行为操作尽快执行。不使用时会创建异步任务，稍后执行

如果你不太明白这些概念，建议直接对返回的对象使用 await

参数:

• type – 行为的类型

• params – 行为的附加参数

• wait – 是否等待这个行为完成

• trigger – 行为的触发事件（可选，这一般是给钩子函数检查触发事件用的）

返回:

ActionHandle 对象

行为操作对象

行为操作函数被用来产生特定的行为操作。为了更精准的控制行为操作的全流程（行为生成、行为执行与行为响应等待），在 melobot 中，多数行为操作函数会返回“行为操作对象”，用于描述和控制整个流程：

class melobot.context.ActionHandle

行为操作类

本类的实例是可等待对象。使用 await 会使行为操作尽快执行。不使用 await 会先创建异步任务，稍后执行

提示

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

action: BotAction

本操作包含的行为对象

status: Literal['PENDING', 'EXECUTING', 'FINISHED']

本操作当前状态。分别对应：未执行、执行中、执行完成

property resp: ActionResponse

当前行为操作的响应数据，需要异步获取（行为操作函数 wait 参数为 True 时使用）

async wait() → None

等待当前行为操作完成（行为操作函数 wait 参数为 True 时使用）

execute() → ActionHandle

手动触发行为操作的执行（行为操作函数 auto 参数为 False 时使用）

返回:

本实例对象（因此支持链式调用）

行为响应对象

行为操作的响应通过行为响应对象描述：

class melobot.context.ActionResponse

行为响应类

提示

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

time: int

响应创建的时间

status: int

响应的状态码

data: dict[str, Any]

响应的数据

is_ok() → bool

是否为成功响应

is_processing() → bool

是否为被异步处理的响应，即未完成但在处理中

is_failed() → bool

是否为失败响应