Metadata-Version: 2.4
Name: nonebot-plugin-redbag-notice
Version: 0.1.0
Summary: QQ 红包私聊提醒插件：超级用户私聊配置监听群，群内出现红包时私聊通知提醒名单
Project-URL: Homepage, https://github.com/TonyLiangP2010405/nonebot-plugin-redbag-notice
Project-URL: Repository, https://github.com/TonyLiangP2010405/nonebot-plugin-redbag-notice
Author: TonyLiangP2010405
License: MIT
License-File: LICENSE
Keywords: napcat,nonebot,nonebot2,notice,plugin,qq,redbag,redpacket
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: nonebot-adapter-onebot>=2.4.0
Requires-Dist: nonebot-plugin-localstore>=0.7.0
Requires-Dist: nonebot2>=2.2.0
Provides-Extra: dev
Requires-Dist: nonebot2[fastapi]>=2.2.0; extra == 'dev'
Requires-Dist: nonebug>=0.3; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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 安装

```bash
nb plugin install nonebot-plugin-redbag-notice
```

### 使用 pip 安装

```bash
pip install nonebot-plugin-redbag-notice
```

### 使用 poetry 安装

```bash
poetry add nonebot-plugin-redbag-notice
```

## 配置

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

```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` 里，由私聊命令维护，不需要手工编辑：

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

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

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

## 使用方法

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

| 命令 | 权限 | 作用 |
|---|---|---|
| `/红包监听` | 超级用户 | 查看当前配置（监听群、提醒用户、调试开关）与帮助 |
| `/监听 <群号>` | 超级用户 | 添加监听群 |
| `/取消监听 <群号>` | 超级用户 | 移除监听群 |
| `/监听列表` | 超级用户 | 列出所有监听群 |
| `/红包提醒 开` | 任何人 | 把自己加入提醒名单，群里有红包时私聊通知我 |
| `/红包提醒 关` | 任何人 | 把自己移出提醒名单 |
| `/红包调试 开` | 超级用户 | 调试模式：命中红包时把原始 json 段写入日志 |
| `/红包调试 关` | 超级用户 | 关闭调试模式 |

### 典型流程

```
超级用户：/监听 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`，
  上游适配器重复推送同一条消息时才会出现，正常场景不会触发。

## 开发

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

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

## 许可证

[MIT](./LICENSE)
