Qmin简Q

文档 / 插件

写一个插件

插件就是 plugins/ 目录下的一个 .py 文件。文件名即插件名, 里面用装饰器注册处理器,收到匹配的消息就执行。

插件是什么

加载时框架会按路径导入文件,模块名固定为 qmin_plugin_<文件名>,并把装饰器注册的处理器挂到全局路由器上,打上来源标记(插件名)。导入失败只影响该插件:错误写进插件记录与日志,其他插件和机器人本体不受影响。

规则说明
小写字母、数字、下划线,字母开头例如 weather、group_admin、hello2
不能以下划线开头以 _ 开头的文件会被跳过,用来放模板(如 _template.py)
单文件 ≤ 256 KB面板安装时的限制
不能重名安装同名文件会被拒绝,除非选择覆盖
三种安装方式:面板「安装插件」粘贴代码/选文件(立即生效)、面板「重新加载」(改完点一下)、直接放进 plugins/(需要重启)。

最小插件

"""群里 @ 机器人并说“你好”时回复。"""

from core.handlers import on_group_at

__plugin_name__ = "打招呼"
__description__ = "收到包含“你好”的群消息时回复"
__version__ = "1.0.0"


@on_group_at("你好")
async def hello(event) -> None:
    await event.reply("你好呀")

__plugin_name__ 等元信息可选:面板会展示名字、描述、版本,不写也能正常加载。

装饰器

目前只有一个事件装饰器:

装饰器参数匹配规则
on_group_at(keyword=None)字符串或 NoneNone 匹配所有群 @ 消息;否则按子串匹配正文
  • 子串匹配、区分大小写:写「你好」会命中「你好啊」「我说你好」。想精确匹配就在处理器里自己判断 event.content.strip() == "你好"。
  • 按注册顺序执行,不会短路:一条消息命中多个处理器时依次全部执行。
  • 多个插件同时命中会各自回复:两个插件都监听「你好」,群里会收到两条。设计关键字时尽量错开。
  • 框架不对正文做 trim,正文可能带前导空格;子串匹配不受影响,精确比较请自己 strip()。

event 对象

处理器收到的是 GroupAtMessage(只读数据类):

字段 / 方法类型说明
event.group_openidstr群 openid(不是群号)
event.contentstr消息正文(平台原文,可能带前导空格)
event.sender_idstr发送者 openid
event.sender_namestr发送者昵称,可能为空字符串
event.msg_idstr本条消息 id
event.timestampstr | None平台给的时间字符串
event.rawMapping原始载荷副本,字段随平台变化,不建议依赖
await event.reply(text)Any发送被动回复(纯文本),失败会抛异常
@on_group_at("hi")
async def hi(event) -> None:
    who = event.sender_name or event.sender_id[:8]
    await event.reply(f"hi,{who}")

生命周期与热重载

场景行为
qmin start 启动扫描 plugins/*.py,逐个加载
面板「安装插件」写文件 → 立即加载(失败回滚文件)
面板「重新加载」先摘掉该插件的旧处理器,再重新导入
面板「禁用」摘掉处理器,文件保留
面板「启用」重新导入文件
面板「删除」摘处理器 + 删文件 + 从列表移除
手动放文件不生效,需要重启(没有文件监听)

边界

  • 模块级变量会重置:重新加载会重新执行整个模块,顶层的计数器、缓存归零。
  • 不会重启机器人连接:重载只影响后续消息分发,网关连接保持不变。
  • 正在执行的处理器不会被打断:重载对已经进入执行的那次调用没有影响。
  • 不能靠重载改框架:core/、api/ 的改动必须重启进程。
  • 处理器不会翻倍:重载前按来源摘除旧处理器;如果发现重复回复,多半是两个插件监听了同一个关键字。

错误处理

框架会给每个处理器兜底:抛出的异常会被捕获,写一条 ERROR 日志(来源 handler),然后继续执行后续处理器,不影响主进程。

对用户侧的失败,最好自己处理,给出可读的回复或日志:

import asyncio

from core.handlers import on_group_at


@on_group_at("查天气")
async def weather(event) -> None:
    try:
        data = await fetch_weather(event.content)
    except asyncio.TimeoutError:
        await event.reply("查询超时了,稍后再试")
        return
    except Exception:
        await event.reply("查询失败了,请联系管理员")
        raise

    await event.reply(data)
  • 不要在处理器里做同步阻塞操作(time.sleep、requests、大文件读写)——事件循环会被卡住,其他消息全部排队。用 asyncio.sleep 与异步 HTTP 客户端。
  • event.reply() 是网络调用,可能因限流或超时失败,建议包在 try/except 里。
  • 被动回复有时效(平台限制为收到消息后 5 分钟内),耗时任务请先回复再异步处理。

调试位置

现象看哪里
插件没加载qmin doctor 的插件数量;面板插件页状态是否「启用·加载失败」
加载报错面板日志筛选来源 plugins,错误带行号
运行时报错面板日志筛选来源 handler
想看 SDK 细节.env 设 LOG_SDK=all

插件之间,以及尚未支持

插件之间不能互相调用。每个插件是独立文件、独立模块,plugins/ 不在 sys.path 里。需要复用就做成独立 Python 包,或者保持单文件内聚;不要把共享状态放在模块级全局变量里——重载会丢。

以下能力需要直接调用 qq-botpy SDK,框架层暂未提供装饰器:

  • 按钮 / 卡片等交互组件(keyboard、ark)
  • 私聊(C2C)消息、频道消息
  • 主动推送(非被动回复)
  • 群成员变动、入群退群事件的业务处理(框架只记日志,不分发给插件)
有需要的场景,欢迎在 issues 里描述用途,会按需求排期。