nonebot-plugin-fanqie-verify

番茄读书群入群验证插件：新成员入群后要求发送自己发布的番茄小说书评详情页截图， 通过 PaddleOCR（PP-OCRv6）云端 API 识别书评信息，校验「我」徽章、书名、作者后 自动放行；验证失败则私信管理员决定通过或踢出。

功能

• FR1 入群触发：监听 OneBot V11 group_increase 事件，对新成员发送验证提示并开启超时计时
• FR2 图片识别：接收新成员发送的图片，调用 PaddleOCR 云端 API 多模型并行识别并按字段融合（PaddleOCR-VL-1.6 / PP-OCRv6 / PP-StructureV3，置信度阈值可配）；OCR 失败时回退视觉模型看图判定（支持群聊发送或私聊机器人发送两种方式验证）
• FR3 信息提取：检测「我」徽章（书评为本人发布）、「书评详情」标题与五角星评分组件，提取读者名、发布日期、评分、阅读时长、书评正文、书名与作者
• FR4 综合判断：本人书评 + 书名/作者合理性校验 + 可配置的放行策略（按群配置作者白名单）；区分书评 vs 短评/段评/章评/想法（后者一律判无效）；OCR 通过后视觉模型二次复核（持否决权，确保高准确率）
• FR5 通过放行：发送欢迎消息
• FR6 拒绝处理：不执行禁言，转入"待管理员决策"并私信通知管理员决定通过或踢出
• FR7/FR8 超时/重试：超时未响应或连续识别失败达到上限，转入"待管理员决策"并通知管理员；响应超时后还会在群内 @ 成员提示已超时、可发送「重审」重试
• 私聊验证：新成员可直接私聊机器人发送书评详情页截图完成验证；多群待验证时用「验证 群号」指定目标群
• 管理决策超时：通知管理员后超过 16 小时（可配置）未处理，自动在群内通报并移出成员；被移出前最后 1 小时、5 分钟（可配置）会再次 @ 提醒该成员及时重审
• FR9 管理员命令：/kick、/keep、/通过 决定踢出/保留/直接批准；待处理列表、处理中列表 查询本群待决策/待提交成员；查看白名单 查看本群作者与作品配置
• 状态持久化：验证会话（等待提交 / 待管理员决策）持久化到数据库，重启后自动恢复并重建超时，不会把验证中的成员误当作已通过
• 追踪 ID：每次验证流程携带全局唯一 trace ID，贯穿日志、落库（会话/事件/审计三表）与管理员通知，可回溯完整判定链路
• 运行时重载：重载番茄OCR配置 命令热更新放行策略
• 边界守卫：监听退群/管理员变动/禁言事件，操作前查询群成员状态，避免对已退出成员执行无效动作
• 漏验补验：机器人（LLBot）掉线期间入群的成员不会收到入群事件，补验 命令可按「入群时间在最近 N 小时内 + 无验证记录」扫描并补进验证流程，也支持直接指定成员；机器人重连时可配置为自动补验或仅提醒管理员
• 延期审核：管理员可用 延期 命令推迟「待管理员决策」成员的自动移出时间（默认 6 小时、单次上限 48 小时，均可配置），用于暂时无法处理时保住成员；可指定成员（延期 @成员 12）或对本群全部待审成员生效（延期），不限制累计次数
• 引用回复：群内各项回复（提交反馈、命令回复、验证通过欢迎、超时通报、移出前提醒）均引用原消息发送，便于成员对照上下文；超时类通报引用该成员最后提交的图片消息。私聊消息与入群引导（系统事件，无原消息）保持普通发送

如何开始

前置要求：Python 3.13、uv、一个 OneBot V11 实现（如 NapCat / go-cqhttp）。

1. 安装依赖：

   uv sync --all-groups
   

2. 配置环境变量：复制 .env.example 为 .env 并填写：

   cp .env.example .env
   

   至少需要配置：

   • FANQIE_OCR_API_TOKEN：PaddleOCR 云端 API 令牌
   • SUPERUSERS / FANQIE_ADMIN_IDS：管理员 QQ 号（/kick、/keep、 重载番茄OCR配置 命令权限，NoneBot 要求 SUPERUSER）
   • 群范围：放行策略 TOML 中配置群节点（配置了节点的群才验证）

3. 配置 OneBot V11 反向 WebSocket：

   在 NapCat / go-cqhttp 中添加反向 WebSocket 连接，地址指向本插件的 ws://<HOST>:<PORT>/onebot/v11/ws（默认 ws://127.0.0.1:8080/onebot/v11/ws）。 HOST / PORT 由 .env 中的 HOST / PORT 决定。

4. 首次运行生成放行策略配置，然后按需编辑（见下文）：

   uv run nb run
   

5. 运行机器人（开发热重载）：

   uv run nb run --reload
   

验证目标与判定

新成员需发送自己发布的番茄小说书评详情页截图。页面关键标识：

• 「我」徽章：书评为自己发布（他人书评无此徽章，将被拒绝）
• 读者名、发布日期、评分（★）、阅读时长、书评正文
• 书名（如 综漫：吉他雇佣兵无法找到归宿？）、作者

判定标准：必须检测到「我」徽章 + 提取到书名与作者。

配置

环境变量

以下变量通过 .env（或 .env.dev / .env.prod）配置，环境变量名大小写不敏感。

完整模板见 .env.example。

放行策略 TOML（FR4）

首次运行后生成在 config/nonebot_plugin_fanqie_verify/verification_policy.toml。 策略以群为节点组织：每个群下可配置多个作者，每个作者下可配置多个作品（书名）。

[verification]
require_all = false          # true 要求全部受支持元素匹配；false 按 required_elements
required_elements = ["book_name", "author"]  # require_all=false 时必配元素

# 群节点：群号 → 作者列表。配置了节点的群才执行验证。
[verification.groups]

[[verification.groups.868258211.authors]]
name = "阿百川大鬼"
books = ["综漫：吉他雇佣兵无法找到归宿？", "另一部作品"]

[[verification.groups.868258211.authors]]
name = "刘慈欣"
books = ["三体", "球状闪电"]

判定规则（按群）：

• 群未配置任何作者节点：放行（宽松模式，仅校验必配元素存在）。
• 群配置了作者节点：提取到的作者必须命中其中一个作者名（只校验作者， books 作品列表仅作配置参考与审计展示，不参与判定）。
• 群节点本身即监控范围：只有配置了节点的群才会执行入群验证。

受支持的元素名：reader_name、publish_time、rating、read_duration、 book_name、author、review_text。

管理员命令

<user_id> 也可用 @成员 代替。命令前缀由 COMMAND_START 决定（默认 /）。「重审」命令不受前缀限制（重审 与 /重审 均可用）。

成员命令（私聊验证）

验证流程

1. 新成员入群 → 机器人 @ 成员发送验证提示并开始超时计时
2. 成员发送自己发布的书评详情页截图 → OCR 识别 → 提取「我」徽章、书名、作者、读者名等
3. 综合判断：本人书评（「我」徽章）+ 信息足够 + 放行策略满足 + 合理性通过 → 放行（欢迎）
4. 否则（他人书评 / 缺少书名作者 / 白名单不命中 / 超时未发图 / 识别失败达上限）→ 转入待管理员决策并私信通知管理员，同时响应超时会在群内 @ 成员提示已超时、可发「重审」；管理员用 /kick 或 /keep 决策
5. 管理员超过 FANQIE_ADMIN_DECISION_TIMEOUT（默认 16 小时）未处理 → 被移出前最后 1 小时、5 分钟各在群内 @ 提醒该成员；仍未处理则群内通报并移出该成员
6. 所有进行中的会话（等待提交 / 待管理员决策）持久化到数据库，重启后自动恢复，不会把验证中的成员误当作已通过

开发

task check   # ruff + pyright
task test    # pytest
task fix     # 自动修复 lint/格式

插件源码位于 src/plugins/nonebot_plugin_fanqie_verify/。

更新日志

各版本的重要变更见 CHANGELOG.md。

文档

• NoneBot2 文档
• PaddleOCR / PP-OCRv6