nonebot-plugin-redbag-notice

QQ 红包私聊提醒插件（OneBot V11 / NapCat 场景）：超级用户在私聊里配置要监听的群， 群内出现红包时，私聊通知提醒名单中的用户。

不依赖任何外部服务，纯 OneBot V11 事件 + 本地 JSON 存储，装上就能用。

功能

• 私聊管理：监听哪些群、谁接收提醒、调试开关全部用私聊命令管理，改完立即生效，不用改 .env、不用重启
• 零配置可用：没有任何必填配置项；不填任何东西也不会报错，默认不监听任何群
• 红包识别：解析 QQ 红包卡片（json 消息段，自动还原 \uXXXX 转义与多重编码），并兜底识别 [QQ红包]、口令红包文本
• 消息去重：同一条群消息只提醒一次（最近 200 条 message_id 去重）
• 逐个发送：提醒名单里某个用户发送失败（未加好友、风控等）只记日志，不影响其他人
• 调试模式：命中红包时把原始 json 段写进日志，方便排查误报与漏报

安装

需要 NoneBot2（>=2.2.0）、nonebot-adapter-onebot（>=2.4.0）与 nonebot-plugin-localstore。 适配器连接的是实现了 OneBot V11 协议的后端（NapCat / Lagrange 等），需要能收到群消息事件。

使用 nb-cli 安装

nb plugin install nonebot-plugin-redbag-notice

使用 pip 安装

pip install nonebot-plugin-redbag-notice

使用 poetry 安装

poetry add nonebot-plugin-redbag-notice

配置

在 NoneBot 项目的 .env 文件中添加（可选，全部有默认值）：

# 监听配置的存储目录，留空使用 nonebot-plugin-localstore 的插件数据目录
# 默认位置：Linux/macOS 一般在 ~/.local/share/nonebot2/nonebot_plugin_redbag_notice/
#           Windows 一般在 %LOCALAPPDATA%\nonebot2\nonebot_plugin_redbag_notice\
REDBAG_NOTICE_DATA_DIR=

监听群、提醒名单、调试开关都存在数据目录的 settings.json 里，由私聊命令维护，不需要手工编辑：

{
  "groups": [123456, 789012],
  "users": [10001, 10002],
  "debug": false
}

• groups：监听的群号
• users：接收私聊提醒的用户 QQ
• debug：调试模式

默认安全：groups 为空（或 users 为空）时不会监听任何群。

使用方法

所有命令都在私聊中使用，命令前缀取决于 NoneBot 的 command_start 配置（下表按默认 / 书写）。

典型流程

超级用户：/监听 123456
机器人：已开始监听群 123456，群内出现红包时会私聊通知提醒名单中的用户。
超级用户：/红包提醒 开
机器人：已开启红包提醒，群内出现红包时会私聊通知你。
普通用户：/红包提醒 开
机器人：已开启红包提醒，群内出现红包时会私聊通知你。

—— 之后群 123456 里有人发红包 ——

机器人（私聊给超级用户）：          机器人（私聊给普通用户）：
【红包提醒】                        【红包提醒】
群号：123456                        群号：123456
发送者：群友甲（20001）             发送者：群友甲（20001）
提示：[QQ红包]恭喜发财               提示：[QQ红包]恭喜发财

超级用户：/红包监听
机器人：【红包提醒】当前配置
        监听群（1 个）：123456
        提醒用户（2 人）：10001、10002
        调试模式：关闭
        数据文件：/path/to/nonebot2/nonebot_plugin_redbag_notice/settings.json
        ...

红包检测规则

群消息进入 on_message（priority=90、block=False，不影响其它插件），只有满足 「群在监听列表中」且「提醒名单非空」两个条件才会继续检测：

1. 遍历消息段，取 json 段的内容。内容可能是字符串或对象，字符串形式的 JSON 会被解析 并重新序列化，因此 \u7ea2\u5305 这类转义也能命中。
2. json 段内容中包含 红包、恭喜发财、[QQ红包] 任一特征词即判为红包； 提示文本按 prompt → desc → summary → title → wishing → name 的顺序提取， 都没有时退回到「含红包字样的短字符串」，再没有就省略这一行。
3. 没有任何 json 段命中时，再按纯文本兜底：raw_message 含 [QQ红包] 或 口令红包。

由于 QQ 红包的 json 字段由客户端决定，检测是特征匹配而不是严格的协议解析： 如果某类红包没有被识别到，可以打开 /红包调试 开，群里再发一次红包，把日志里的 原始 json 段提 issue；反过来，如果在监听群里聊到「口令红包」被误报，直接 /取消监听 <群号> 即可。

常见问题

• 群里发红包了但没提醒：依次检查 1) /监听列表 里有没有这个群；2) /红包提醒 开 有没有执行过、 私聊是否被机器人成功发出（提醒需要对方已添加机器人为好友）；3) 机器人账号是否在该群里且能收到群消息； 4) 打开调试模式看有没有命中日志。
• 提示文本是空的：这类红包的 json 里没有 prompt/desc 等字段，属于正常情况，提醒里会省略「提示」一行。
• 同一条红包提醒了两次：去重只覆盖最近的 200 条消息，且去重基于 message_id， 上游适配器重复推送同一条消息时才会出现，正常场景不会触发。

开发

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

.venv/bin/python -m pytest        # 单元测试 + nonebug 事件流测试
.venv/bin/python -m ruff check .  # 代码检查

许可证

MIT