文档 / 插件
写一个插件
插件就是 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) | 字符串或 None | None 匹配所有群 @ 消息;否则按子串匹配正文 |
- 子串匹配、区分大小写:写「你好」会命中「你好啊」「我说你好」。想精确匹配就在处理器里自己判断
event.content.strip() == "你好"。 - 按注册顺序执行,不会短路:一条消息命中多个处理器时依次全部执行。
- 多个插件同时命中会各自回复:两个插件都监听「你好」,群里会收到两条。设计关键字时尽量错开。
- 框架不对正文做 trim,正文可能带前导空格;子串匹配不受影响,精确比较请自己
strip()。
event 对象
处理器收到的是 GroupAtMessage(只读数据类):
| 字段 / 方法 | 类型 | 说明 |
|---|---|---|
event.group_openid | str | 群 openid(不是群号) |
event.content | str | 消息正文(平台原文,可能带前导空格) |
event.sender_id | str | 发送者 openid |
event.sender_name | str | 发送者昵称,可能为空字符串 |
event.msg_id | str | 本条消息 id |
event.timestamp | str | None | 平台给的时间字符串 |
event.raw | Mapping | 原始载荷副本,字段随平台变化,不建议依赖 |
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 里描述用途,会按需求排期。