面向 AstrBot + NapCat 群聊场景的入群防广告管理插件,通过严格口令、动态数学题和验证前消息撤回,阻止广告账号趁验证期间发言。
本仓库由
mydanyi维护,Fork 自 huntuo146/astrbot_plugin_Group-Verification_PRO。 PROMAX 版本保留上游许可与作者信息,并针对 AstrBot + MaiBot 共用 NapCat 场景持续维护。**修改与许可声明:**本修改版于 2026-07-29 由
mydanyi基于上游项目修改, 整体继续按 AGPL-3.0 发布。当前部署版本的完整对应源代码可从本仓库及对应 Release 免费获取。
本插件为 AstrBot 提供了强大的新成员智能验证功能,能有效过滤广告机器人和可疑用户,全面提升群聊质量。
- 🧠 动态数学题验证:新成员需回答随机生成的 100 以内加减法问题,代替呆板的静态关键词,极大提升验证强度。
- 🔐 严格验证口令:只有“@机器人 验证 数字”格式才会进入答案校验,便于与其它机器人按关键词分流。
- 🧹 验证前发言管控:除正确且通过的验证码外,待验证成员发送的所有消息都会立即撤回,验证成功后解除限制。
- 🏢 分群启用 (White-list):支持指定特定群号开启验证,未在名单内的群组将不触发验证流程,更加灵活。
- 🔄 错误重试与上限:回答错误后自动生成新题,超过设定次数直接踢出,兼顾容错与防刷屏。
- 🔀 多群隔离:同一用户同时加入多个验证群时,各群验证状态互不干扰。
- ⏱️ 多段式时间控制:自定义验证总时长、超时前警告时机、失败后踢出延迟等,答错不重置计时。
- 🎨 完全可定制化消息:欢迎语、错误提示、超时警告、踢出公告等均可自定义,支持丰富变量。
- 🛡️ 安全生命周期:插件卸载/重载时自动取消所有后台任务,不会产生资源泄漏。
展开查看详细安装步骤
- 打开 AstrBot 插件管理界面。
- 选择“从 GitHub 仓库安装”,填写
https://github.com/mydanyi/astrbot_plugin_Group-Verification_PROMAX;也可以上传 Release 中的 ZIP。 - 安装完成后,进入插件配置页面进行参数设置。
- 保存配置并重启机器人,或在插件管理中手动重载本插件。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled_groups |
list | [] |
启用插件的群号列表。留空则全局生效,否则仅对名单内的群生效。 |
max_retries |
int | 3 |
最大答错重试次数。超过后直接踢出。设为 0 表示不限制。 |
verification_keyword |
string | 验证 |
验证口令关键词,例如 @机器人 验证 42。 |
revoke_pending_messages |
bool | true |
撤回待验证成员在验证成功前发送的普通消息、错误格式和错误答案;保留正确验证码。 |
source_code_url |
string | PROMAX 仓库地址 | 随入群题目展示的 AGPL-3.0 对应源码入口;请保持指向实际部署版本。 |
invalid_message_reminder_cooldown |
int | 15 |
错误格式提醒的冷却秒数,避免机器人被恶意触发刷屏。 |
verification_timeout |
int | 300 |
验证总超时时间(秒)。 |
kick_countdown_warning_time |
int | 60 |
超时前发送警告的秒数。设为 0 可禁用警告。 |
kick_delay |
int | 5 |
发送"验证超时"消息后延迟踢出的秒数。 |
new_member_prompt |
text | 见下方 | 新成员入群时发送的欢迎及验证提示语。 |
welcome_message |
text | 见下方 | 验证成功后的祝贺提示语。 |
wrong_answer_prompt |
text | 见下方 | 回答错误后的提示语(自动附带新题)。 |
invalid_message_prompt |
text | 见下方 | 撤回普通消息或错误格式验证消息后的提醒。 |
countdown_warning_prompt |
text | 见下方 | 验证即将超时时的警告消息。 |
failure_message |
text | 见下方 | 验证超时后、踢出前的"最后通牒"消息。 |
kick_message |
text | 见下方 | 成员被踢出后在群内的公开通知。 |
| 变量 | 说明 | 适用模板 |
|---|---|---|
{at_user} |
@目标用户的 CQ 码 | 所有模板 |
{member_name} |
用户的群名片或 QQ 昵称 | 所有模板 |
{question} |
随机生成的数学题(如 76 + 24 = ?) |
new_member_prompt、wrong_answer_prompt |
{timeout} |
验证超时时长(分钟) | new_member_prompt |
{countdown} |
踢出前的延迟秒数 | failure_message |
{keyword} |
当前验证关键词 | 验证相关模板 |
- 白名单设置:在
enabled_groups中填入需要开启验证的群号。若保持为空,则插件会对机器人加入的所有群组生效。 - 验证流程:新成员入群后,机器人会 @ 该成员并出题。成员需发送
@机器人 验证 数字答案,例如@机器人 验证 42。也兼容验证42、验证:42。 - 消息管控:验证成功前,该成员发送的广告、图片、链接、普通聊天、错误格式和错误答案都会被立即撤回;只有正确且通过的验证码消息会保留。错误格式只会按冷却时间提醒,不计入答错次数。
- 容错机制:格式正确但答案错误时,系统会更换题目,但不会重置超时计时。超过
max_retries次答错将直接踢出。 - 清理逻辑:如果成员在验证期间主动退群,系统会自动撤销验证任务,释放资源。
- 多群场景:同一用户同时加入多个启用验证的群时,各群验证独立进行,互不影响。
MaiBot 的 NapCat Adapter 建议使用黑名单正则过滤 AstrBot 命令和验证口令:
[filters]
ignore_self_message = true
regex_filter_enabled = true
regex_filter_mode = "blacklist"
regex_filter_patterns = [
'(^|\s)/\S+',
'^\s*验证\s*[::]?\s*\d+\s*$'
]注意:撤回操作发生在 NapCat 已经上报原消息之后。插件可以阻止消息继续进入 AstrBot 的其它插件并从 QQ 群中撤回,但无法保证另一个独立的 MaiBot 进程尚未收到这条消息。 如果要求 MaiBot 对待验证用户的广告也完全不可见,还需要让 MaiBot Adapter 读取共享的 待验证成员状态;这不是普通关键词正则能够完全解决的。
-
Q: 为什么输入正确答案没反应?
A: 请确认消息严格包含 @机器人 + 验证关键词 + 数字答案,例如@机器人 验证 42。 -
Q: 机器人没有踢人权限?
A: 请确保机器人帐号拥有 群管理员 或 群主 权限;撤回他人消息也需要该权限。 -
Q: 为什么待验证成员的消息没有被撤回?
A: 确认revoke_pending_messages已开启、事件中包含message_id,并确认机器人账号是群管理员或群主。 -
Q: 踢人失败后用户会恢复发言吗?
A: 不会。插件会保留该成员的受限状态并继续尝试撤回其消息,直到成员离群、插件重载或管理员修复权限。 -
Q: 如何彻底关闭某个群的验证?
A: 如果你设置了enabled_groups,只需将该群号移出列表;如果列表为空,则需要在 AstrBot 插件管理中禁用本插件。 -
Q: 答错后计时会重置吗?
A: 不会。答错只会换题,超时计时从入群那一刻开始,不会因答错而延长。 -
Q: 支持哪些消息平台?
A: 目前仅支持 aiocqhttp(OneBot v11 协议),如 NapCat、Lagrange 等。
- 🏷️ 更名:插件显示名称调整为“QQ群入群防片哥管理插件”,插件标识升级为
astrbot_plugin_Group_Verification_PROMAX。 - 🔗 维护仓库:迁移至 mydanyi/astrbot_plugin_Group-Verification_PROMAX,保留与上游仓库的 Fork 关系。
- 📝 文档:补充 PROMAX 维护说明、AstrBot + MaiBot 共用 NapCat 的过滤建议及消息流边界。
- ⚖️ 许可合规:保留上游作者与 AGPL-3.0,增加修改日期、对应源码声明及网络交互源码入口。
- ✅ 验证:保留 v2.3.0 的严格“@机器人 验证 数字”、待验证消息撤回、优先阻断和踢人失败锁定机制。
- 🆕 新增:严格验证口令,默认要求
@机器人 验证 数字。 - 🆕 新增:验证成功前撤回待验证成员发送的全部群消息,仅保留正确且通过的验证码。
- 🆕 新增:错误格式提醒及冷却时间,避免机器人被恶意触发刷屏。
- 🛡️ 修复:新成员状态在外部资料查询前立即登记,关闭入群瞬间的广告窗口。
- 🛡️ 修复:达到答错上限或超时后立即锁定;踢人失败时继续保持受限状态。
- 🔧 优化:修正警告时间大于总超时时间时的计时偏差。
- 🔧 优化:验证处理器提高优先级,在 AstrBot 内尽早停止待验证消息传播。
本版本为架构级重构,提升了稳定性、并发安全性和可维护性。
- 🆕 新增:
max_retries配置项,答错超过次数直接踢出,防止恶意刷屏。 - 🆕 新增:多群隔离,同一用户同时加入多个群时验证状态互不冲突。
- 🆕 新增:
terminate()生命周期方法,插件卸载/重载时自动取消所有后台任务。 - 🔧 优化:答错不再重置超时计时,防止恶意用户通过反复答错无限续命。
- 🔧 优化:使用
asyncio.Lock保护并发状态访问,消除竞态条件。 - 🔧 优化:存储 bot 引用到验证状态中,不再依赖非公开 API
get_platform().get_client()。 - 🔧 优化:使用
@filter.platform_adapter_type装饰器替代手动平台判断。 - 🔧 优化:消息模板配置类型改为
text,WebUI 编辑体验更好。 - 📝 变更:元数据迁移至
metadata.yaml,移除@register装饰器。
此版本重点解决了在复杂网络环境下或接收特殊事件时插件崩溃的问题。
- 🐛 修复:解决了在处理非标准事件时,由于
raw_message为空导致的'NoneType' object has no attribute 'get'严重报错。 - 🔧 优化:将事件过滤器调整为
EventMessageType.ALL,确保能更稳健地捕获入群通知(Notice)事件。 - 🛡️ 健壮性:增加了防御性编程检查,确保在数据异常或平台 API 调用失败时插件不会崩溃。
- 🆕 新增:分群启用功能,新增
enabled_groups配置项,支持白名单模式。 - 🔧 优化:完善数学题重试逻辑,确保每次回答错误后生成的题目具有随机性。
- 🐛 修复:解决了因
from astrbot.api.bot import Bot在部分版本中不兼容导致的ModuleNotFoundError。
- 🐛 修复:修复了
_timeout_kick函数中不完整代码行导致的语法错误。
- 🔧 优化:重构消息格式化逻辑,模板缺少占位符时不再崩溃。
- 🔧 优化:升级答案提取算法,智能识别用户回复中的数字。
- 🆕 核心验证方式从静态关键词升级为 100 以内动态数学题验证。
- 🆕 新增验证超时前警告、错误重试、自定义踢出延迟功能。
- PROMAX 维护者:mydanyi
- 原项目作者:huotuo146
- PROMAX 项目地址:astrbot_plugin_Group-Verification_PROMAX
- 上游项目地址:astrbot_plugin_Group-Verification_PRO
本项目采用 AGPLv3 许可证 开源。
详细修改与源码获取声明见 NOTICE.md。
如果您觉得这个插件有用,请考虑给项目一个 ⭐Star!
PROMAX maintained by mydanyi · Based on the original work by huotuo146