QQ群智能守护者 (GroupGuardian)

AstrBot 综合群管理插件，集 28项群管功能、AI智能审核、违禁词热更新 与 WebUI 管理面板 于一体，让机器人成为真正的群聊守护者。

当前版本：v2.21.0 | 最低 AstrBot 版本：>=4.24.2

---

功能概览

WebUI 管理面板（v1.7.0+）

插件内置专业 WebUI Dashboard，在 AstrBot 管理面板中即可完成所有操作：

标签页	功能
总览	实时统计卡片、今日拦截排行、趋势/分布/时段/群排行图表
群管理	群卡片网格、成员列表、单人/批量禁言/解禁/踢人/设名片/头衔/管理、远程执行群管操作
违规记录	被撤回用户聚合视图、完整审核日志、批量删除、CSV 导出、消息详情查看
刷屏监控	实时展示每群每人的秒/分/小时消息速率，红/黄/绿预警状态
规则中心	违禁词规则和关键词增删改查、搜索、批量导入/删除/启停、即时重建匹配器
入群审核	按群配置加群申请通过词、拒绝词、词库过滤和默认动作
权限管理	插件管理员、群超管、群级权限黑名单、群管理员动态授权
申诉/解禁	刷屏申诉记录、定时解禁计划查看与取消
名片监控	名片变更记录、名片保护名单、违规名片审核开关、管理员任免记录（v2.7.0+，默认全关）
词库学习	AI 自适应上下文学习：候选违禁词审批、功能开关、立即学习（v2.8.0+，默认全关）
多群配置	群级配置覆盖，全局默认与单群策略分离
设置	核心/审核/OCR/词库/功能开关、高级参数、SQLite 迁移助手、名单管理

Web 后台远程操作权限模型（v2.15.0）

WebUI 面板的远程群管操作（禁言/踢人/设名片等）遵循以下权限模型：

1. Dashboard 用户与 QQ 身份绑定（web_operator_bindings）

• WebUI 远程操作时前端携带操作者用户名（AstrBot Dashboard 登录用户名，本地记忆）；服务端按 web_operator_bindings（格式 用户名:QQ号,用户名2:QQ2）服务端绑定映射到 QQ 身份，用于授权校验与审计；
• v2.21.0 安全加固：操作者身份只来自服务端绑定，请求体自报的 operator_qq 一律忽略——调用方不能伪造管理员 QQ 绕过身份绑定。

2. 操作者角色分级（远程写操作前校验）

角色	判定	可操作范围
全局插件管理员	插件 admin_list / AstrBot 全局 admin_id / web_operator_bindings 绑定用户	所有群（产品设计的全局管理模型）
群超管	该群在 WebUI「权限管理」单独设置的群超管	仅该群
群主 / 群管理员	按 QQ 号查询目标群角色（owner / admin）	仅该群
普通成员	其余	拒绝

3. 强制校验开关（web_remote_require_operator，默认关闭）

• 开启后：远程写操作必须校验操作者授权，未绑定身份或非授权用户一律拒绝；
• 关闭时：依赖 AstrBot Dashboard 的登录鉴权（能登录面板即可操作），仍会记录审计日志；
• 无论开关状态，远程操作始终记录审计日志（操作者、目标群、操作、目标、结果、时间）， 可在 GET /audit_logs（WebUI 接口）或 SQLite web_audit_logs 表查询。

4. 高风险操作二次确认（web_remote_confirm_required，默认开启）

• 踢人 / 批量踢人 / 全体禁言等高危远程操作执行前弹「高风险操作确认」对话框，默认勾选确认框，防止误点；
• 关闭后直接执行，不弹确认。

5. 高敏感操作双管理员审批（web_remote_dual_approval_enabled，默认关闭）

• 开启后，web_remote_approval_actions（默认 set_admin,unset_admin,whole_ban）指定的高敏感操作 由第一名管理员发起后不立即执行，进入待审批队列；
• 需由第二名管理员在 WebUI「权限管理 → 待审批操作」确认后才真正执行；发起人不能自我确认， 确认人需具备目标群授权，超时 10 分钟自动过期；
• 接口：GET /approvals/list、POST /approvals/approve、POST /approvals/reject。

6. 详细审计（v2.19.0）

• 每条审计日志记录操作人姓名 / QQ / IP、操作时间、目标群、操作、参数、修改前后值（before/after）与结果；
• 操作人 IP 优先取 X-Forwarded-For 头，其次 remote_addr；
• WebUI「权限管理」页提供「远程操作审计日志」区块可视化查看。

7. 安全提示

• 请勿将 AstrBot Dashboard 端口直接暴露公网或关闭其登录验证；
• 强烈建议开启 web_remote_require_operator 并为每个 Dashboard 用户配置 web_operator_bindings， 确保所有远程写操作均可追溯到具体操作者；
• 高风险环境（多人共用面板）建议同时开启 web_remote_dual_approval_enabled 双管理员审批。

群管工具集（28项）

所有管理命令仅限 插件管理员或群管理员 使用，危险写操作会在插件内进行权限校验；查询类指令可通过配置项控制是否开放。

管理操作指令（需管理员权限）

功能	指令	说明
禁言	/禁言 <QQ号或@> <分钟>	禁言指定成员，如 /禁言 123456 30 或 /禁言 @张三 30
解禁	/解禁 <QQ号或@>	解除指定成员禁言，支持 @
踢出成员	/踢人 <QQ号或@>	将成员移出群聊，支持 @
全体禁言	/全体禁言 开启/关闭	开启/关闭全员禁言
设置群名片	/设置名片 <QQ号或@> <新名称>	修改成员显示名称，支持 @
发群公告	/发公告 <内容>	发布群公告
删群公告	/删公告 <公告ID>	删除群公告
删群文件	/删文件 <文件ID>	删除群文件
群名称	/群名 <新名称>	修改群聊名称
专属头衔	/头衔 <QQ号> <头衔名>	设置成员专属头衔
设精华	/设精华 <消息ID>	设置精华消息
取消精华	/取消精华 <消息ID>	取消精华消息
设置管理	/设置管理 <QQ号>	设置群管理员
加群方式	/加群方式 <方式>	修改入群验证（需要验证/允许/禁止）
自动审核	/自动审核 开启/关闭/状态	开关智能审核功能
设置管理插件	/设置管理插件 <QQ号> 添加/移除	管理插件管理员列表
批量撤回	/批量撤回 [条数]	批量撤回最近消息
撤回最新消息	/撤回最新消息 [条数]	撤回群内最新一条或多条消息
添加违禁词	/添加违禁词 <脏话|广告> <词>	添加自定义违禁词，即时生效（仅插件管理员）
删除违禁词	/删除违禁词 <脏话|广告> <词或ID>	删除自定义违禁词（仅插件管理员）
查看违禁词	/查看违禁词 [脏话|广告]	查看指令添加的自定义违禁词（仅插件管理员）

查询统计指令（按配置开放）

功能	指令	说明
字数统计	/字数统计	统计当前群的每日消息数和活跃成员数
群统计	/群统计	显示群内今日消息总数、活跃用户数及排行
搜索成员	/搜索成员 <关键词>	按昵称或QQ号搜索群成员
成员列表	/成员列表	查看群成员列表
禁言列表	/禁言列表	查看当前被禁言的成员
公告列表	/公告列表	查看群公告列表
文件列表	/文件列表	查看群文件列表

AI 可调用的 LLM 工具（20项）

AI 可通过以下工具自动执行群管操作，无需手动输入指令：

工具名	说明
ban_group_member	禁言群成员
unban_group_member	解除禁言
kick_group_member	踢出群成员
set_whole_group_ban	开启/关闭全体禁言
set_member_card	设置群名片
send_group_announcement	发布群公告
get_group_member_list	获取群成员列表
set_group_admin	设置/取消管理员
set_group_name	修改群名称
set_member_title	设置专属头衔
get_banned_members	查看禁言列表
set_group_join_verify	设置加群方式
recall_message	撤回消息
set_essence_message	设为精华消息
delete_essence_message	取消精华消息
delete_group_notice	删除群公告
list_group_files	查看群文件列表
delete_group_file	删除群文件
get_group_notice_list	获取群公告列表
upload_group_file	上传群文件

智能审核系统

核心流程：Aho-Corasick 自动机初筛 + 正则回退 → 获取30条上下文 → LLM二次判断 → 自动撤回 → 发送说明

检测类别：

类型	处理方式	说明
反动言论	直接拦截	命中即撤回
违规网址	直接拦截	命中即撤回
严重辱骂	直接拦截	涉及家人死亡诅咒、极端侮辱人格
政治敏感	LLM二次判断	结合上下文判断
广告推广	LLM二次判断	结合上下文判断是否为真实广告
色情淫秽	LLM二次判断	结合上下文判断
暴恐内容	LLM二次判断	结合上下文判断
涉枪涉爆	LLM二次判断	结合上下文判断
贪腐相关	LLM二次判断	结合上下文判断
隐私侵犯	LLM二次判断	人肉搜索、开盒、泄露个人信息

特色功能：

• 外置 SQLite 词库支持（lexicon.db），12类违规内容，66,993 个关键词 + 24,000+ 条辱骂规则
• 管理员消息免检测
• 群白名单/黑名单机制
• 用户黑名单（自动拒绝加群）
• SQLite 审核日志存储与 WebUI 迁移助手
• 每个功能独立开关
• 可指定审核专用LLM Provider
• 全量 AI 审核：可选将规则初筛未命中的普通消息也送 LLM，补充识别依赖语境或分段表达的内容（默认关闭，可按群覆盖）
• 普通 AI 模式也防拆分绕过：同一发送者近期多条消息呈现逐字、联系方式或引流形态时，即使本地关键词零命中，也会送 LLM 语义审核；已启用 OCR/二维码识别的截图结果同样不会在词库零命中时提前放行
• 多层嵌套消息审核：递归解析 Node / Nodes / Forward / JSON / App，并限制深度、节点、字符和远程请求数量
• 辱骂规避写法：内置 24,000 条安全分隔变体及 13 条短词边界规则；cs / cnm / nmsl 等不会命中正常英文子串
• OCR识图审核：使用LLM视觉模型识别图片内容，支持3种内置提示词模板（通用识别/严格审核/纯文字转录）和自定义提示词
• GIF动图审核：自动识别GIF格式图片，使用专用提示词引导视觉模型关注多帧内容
• 表情包/商城表情审核：识别 market_face 商城表情图片，通过OCR转录文字并判断是否违规
• 视频广告检测（v2.9.0+）：自动下载群内视频（受体积/超时上限保护），用 OpenCV 等间隔抽帧，逐帧走视觉模型识别 + 二维码解码，识别文本并入正文走统一「初筛 + LLM 二次判断 + 处罚」流程；识别失败静默降级不误杀（默认关闭，可按群覆盖）。配置与验证详见 视频广告识别-使用说明.md
• 广告图黑名单（v2.9.1+，感知哈希）：图片/视频帧识别前先与历史广告样本（pHash）比对，命中直接标记「已知广告」并跳过视觉 API 调用（省 GLM-4V 费用）；广告确认违规后自动学习新样本，可自定义相似度阈值（默认关闭）
• 广告分级处置（v2.9.1+）：按窗口内广告违规次数升级处罚：首次仅撤回+警告 → 二次禁言 → 三次踢出，降低误伤投诉（默认关闭，阈值与窗口可按群覆盖）
• 视频检测实时性优化（v2.9.2+）：场景切换抽帧（video_frame_mode=scene，仅保留画面明显变化的帧）+ 快速预检（本地特征打分，低分帧跳过视觉 API）+ 视频指纹缓存（广告确认过的整段视频直接命中零检测），三项均可按群开关，显著降低 GLM-4V 调用次数与延迟
• 独立 Web 管理后台（v2.10.0+）：插件内置独立 HTTP 后台（默认端口 8765，不依赖 AstrBot 面板），浏览器直接访问查看广告拦截统计、违规记录（含图片证据）、感知哈希黑名单、视频指纹缓存、分级处置记录与配置状态，支持删除黑名单/清空指纹/重置分级等管理操作；可设访问令牌（ad_backend_token）
• QQ收藏自动撤回：检测到QQ收藏转发的消息自动撤回
• 防刷屏检测（v2.2.1+）：追踪所有消息类型（转发/QQ收藏/图片/JSON等）的发送频率，按滑动窗口统计最近 1 秒 / 60 秒 / 3600 秒内的消息数，不按自然日累计；支持凌晨/夜间时段单独阈值，超限自动禁言+可选批量撤回，撤回阈值可自定义。WebUI 专属刷屏监控面板实时展示每群每人的消息速率，支持红/黄/绿预警状态
• 重复消息检测：默认统计最近 120 秒内同一内容重复次数，第 3 次触发处理；窗口最大 3600 秒，不做一天累计
• 入群自动审核：按群配置加群申请通过词、拒绝词、违禁词库过滤和默认动作，可自动通过/拒绝或转人工
• 刷屏申诉工作流：刷屏处罚后可群内 @ 当事人，引导其私聊申诉；LLM 结合申诉理由与群内上下文复核，支持 2 次文字申诉机会
• 定时自动解禁：插件发起的禁言可登记到期解禁，重启后从 SQLite 恢复计划
• 多群独立配置：通用功能开关、审核、防刷屏、词库、申诉、入群等配置可按群覆盖，全局默认与单群策略分离

名片监控（v2.7.0+，总开关默认关闭）

监听协议端上报的 group_card（名片变更）与 group_admin（管理员任免）通知事件， 并在 group_increase（成员入群）时立即查询一次名片。部分协议端不发送非标准 group_card 时，插件还会按低频间隔同步群成员名片，因此不要求成员先发言。 WebUI 有独立的「名片监控」页面。名片监控总开关默认关闭；周期同步兜底 默认开启，但只有总开关开启后才会发起查询。

能力	配置项	说明
总开关	card_monitor_enabled	关闭时完全不处理名片/管理员事件（默认关）
周期同步兜底	card_sync_enabled	通过 get_group_member_list 发现未上报的名片变化（默认开，受总开关控制）
同步间隔	card_sync_interval	全局调度周期，默认 120 秒（30-3600 秒）；普通成员首次同步只建立基线，保护名单成员发现偏离会立即还原
A 变更日志	card_log_enabled	记录所有名片变更（谁的名片、旧→新、时间）与管理员任免，WebUI 可分页/筛选/清空
B 名片保护	card_protect_enabled	保护名单内成员的名片被改后自动改回预设值，名单在 WebUI 维护
C 仅拦链接（宽松）	card_audit_link_only	只拦网址/店铺域名/扫码，放行「科技加我」「xxxrxxx」这类引流昵称
C 全量审核（严格）	card_audit_enabled	链接照拦，另外引流/违禁词经「正则初筛 + LLM 上下文判断」也拦
C 管理员豁免	card_audit_admin_exempt	群主、群管理员、插件管理员默认跳过违规名片审核；变更日志照常记录，名片保护仍执行
C 强制送 LLM	card_audit_llm_always	初筛没命中也送 LLM，用于识别 ldxp/catfk 这类无规律引流缩写黑话（成本高）
D 管理员任免通知	admin_change_notify_enabled	有人被设为/取消管理员时群内通知
还原时群内通知	card_monitor_notify	触发保护还原/违规还原时是否发通知

违规名片判定流程（与消息审核同款的「正则初筛 + LLM 二判」）：

名片保护名单会先独立执行；管理员豁免只跳过下方的违规审核，不跳过保护还原。

名片变更
  ├─ 含链接/店铺域名/扫码？ ── 是 ──> 直接还原（不走 LLM，两种模式都拦）
  └─ 否
      └─ 全量审核开启？
          ├─ 正则/词库初筛命中（引流词/违禁词）？ ──> 送 LLM 上下文判断
          ├─ 或开了「强制送 LLM」？ ──────────────> 送 LLM 上下文判断
          └─ 都没有 ──> 放行

还原目标默认为旧名片；旧名片本身也违规时清空名片。

两个审核开关同时开启时以严格模式为准（严格是宽松的超集）——开的开关越多拦得越严。

协议限制（重要）：group_card / group_admin 事件不含 operator_id， 因此无法区分「本人改的」还是「管理员改的」，只能记录变更这一事实本身。 该事件为 NapCat/LLOneBot 扩展（非 OneBot v11 标准），其他协议端可能不上报。 group_card 不上报时，周期同步最多在一个同步间隔内发现变化；成员入群则由标准 group_increase 事件立即查询，不需要等待发言。 card_sync_interval 是全局调度周期，不提供单群间隔；单群可独立覆盖 card_sync_enabled，决定该轮是否查询该群。

排查：改名片后若日志中没有 [GroupMgr] 收到名片变更事件 这行 INFO， 说明协议端根本没上报该事件（而非插件判定逻辑的问题）。

自适应上下文学习（v2.8.0+，总开关默认关闭）

让插件从群聊上下文自动学习本群特有的引流/广告黑话（如「AI中转」「plus日抛team」）， 沉淀进按群独立的自训练词库，逐步自我增强审核能力。WebUI 有独立「词库学习」页。

工作流：被动采集群消息进按群缓冲 → 周期（默认 300s）把样本交给学习模型 → LLM 找出反复出现、又不在现有词库里的引流词（带置信度/理由/样例）→ 跨轮累计出现次数 → 存为候选 → 审批生效 → 并入该群匹配器参与初筛与撤回判断。

⚠️ 安全设计（自动加违禁词是高危操作，误加常用词会误删满群消息）：

• 默认候选/审核模式：AI 只产出「建议词」，管理员在 WebUI 审批后才生效。
• 多维度自动审批门（lexicon_learn_auto_apply，默认关）：候选词要自动生效（进而自动参与撤回）， 必须同时通过五个维度——① 置信度 ② 跨轮出现频次 ③ 词形 ④ 非白名单常用词 ⑤ 对抗式 LLM 复核（专门反驳「会不会误伤正常消息」，从严）。任一不过即转人工。
• 按群独立：A 群学到的词只在 A 群匹配，不污染其它群。
• 最小词长、白名单保护、单轮上限、纯数字/纯标点丢弃等多重防误杀。

配置项	默认	说明
lexicon_learn_enabled	false	总开关，关闭则完全不采集不挖掘
lexicon_learn_auto_apply	false	候选词经多维度审批门自动生效（否则纯人工审批）
lexicon_learn_verify_llm	true	自动生效前的对抗式 LLM 复核（仅 auto_apply 开启时生效）
lexicon_learn_interval	300	挖掘间隔（秒，30-3600）
lexicon_learn_min_confidence	0.75	自动生效置信度阈值（0-1）
lexicon_learn_min_occurrences	3	自动生效所需跨轮出现次数
lexicon_learn_min_length	2	学习词最小长度（防单字误伤）
lexicon_learn_max_per_run	10	单轮单群最多接纳候选数
lexicon_learn_sample_size	60	每次挖掘的消息样本数
lexicon_learn_provider_id	空	学习模型（留空复用审核模型；可单独指定便宜模型省成本）
lexicon_learn_allowlist	[]	永不学习的词（保护本群常用词/商品名）

RAG 说明：当前学习核心用可配置的 LLM（lexicon_learn_provider_id）从上下文挖掘关键词， 自训练数据库即 learned_keywords 表（每群独立）。向量嵌入式 RAG 聚类为后续增强方向。

---

安装方法

方式一：通过AstrBot插件市场（推荐）

在 WebUI → 插件 → 插件市场 中搜索QQ群智能守护者安装

方式二：手动安装

1. 下载插件压缩包
2. 在 AstrBot WebUI → 插件 → 安装插件 → 上传插件文件
3. 重启或重载插件
4. 从 v1.x 升级到 v2.0.0 后，建议进入 WebUI 设置页查看 SQLite 迁移助手状态，并按提示迁移旧日志

---

配置说明

在 AstrBot WebUI → 插件配置 中设置：

配置项	说明	默认值
enabled	插件总开关	true
admin_list	管理员QQ号列表（必填）	[]
group_white_list	群白名单（空则全部）	[]
group_black_list	群黑名单	[]
user_black_list	用户黑名单（自动拒绝加群）	[]
auto_moderate_enabled	自动审核开关	true
auto_moderate_notice	撤回后发送说明	true
moderation_llm_provider_id	审核专用LLM Provider ID	默认
llm_moderation_always	所有消息全量 AI 审核，带群聊/分段上下文并自动尝试识图（可按群覆盖）	false
llm_max_concurrency	LLM 全局并发上限（OCR 最多占 4 路，修改后重载）	12
llm_moderation_custom_prompt	消息 LLM 自定义审核标准（留空使用内置）	空
scan_forward_msg	合并转发消息审核开关	true
ocr_enabled	OCR识图审核开关	false
ocr_provider_id	OCR视觉LLM Provider（可留空回退审核/默认 Provider）	空
ocr_prompt_template	OCR提示词模板	default
ocr_custom_system_prompt	OCR自定义系统提示词	空
ocr_custom_user_prompt	OCR自定义用户提示词	空
video_audit_enabled	视频广告检测开关	false
video_max_frames	每个视频最多抽帧数	3
video_frame_interval_sec	视频抽帧间隔（秒）	5.0
video_max_size_mb	单个视频最大体积（MB）	30
video_download_timeout	视频下载超时（秒）	25
video_audit_timeout	单条消息视频审核总超时（秒）	60
ad_hash_blacklist_enabled	广告图黑名单（感知哈希）开关	false
ad_hash_distance	广告图黑名单相似度阈值（0-64）	10
ad_hash_auto_learn	广告确认后自动学习黑名单	true
ad_escalation_enabled	广告分级处置（警告→禁言→踢出）	false
ad_escalation_warn_at	广告第几次仅警告	1
ad_escalation_ban_at	广告第几次禁言	2
ad_escalation_kick_at	广告第几次踢出	3
ad_escalation_window_seconds	广告分级统计窗口（秒，默认7天）	604800
video_frame_mode	视频抽帧模式（interval=等间隔 / scene=场景切换）	interval
video_scene_threshold	场景切换抽帧阈值（scene 模式生效）	30.0
video_quick_precheck	视频帧快速预检（低分帧跳过视觉API）	false
video_precheck_threshold	快速预检可疑度阈值（0-1）	0.5
video_fingerprint_cache	视频指纹缓存（广告确认视频直接命中）	false
ad_backend_enabled	独立Web管理后台开关	false
ad_backend_port	独立后台端口（默认8765）	8765
ad_backend_token	独立后台访问令牌（留空不鉴权）	空
recall_qq_favorite_enabled	QQ收藏自动撤回开关	true
scan_sticker_enabled	表情包/商城表情审核开关	true
anti_flood_enabled	防刷屏检测总开关	true
anti_flood_rate_per_second	每秒消息上限，0 表示关闭本档	5
anti_flood_rate_per_minute	每分钟消息上限，0 表示关闭本档	20
anti_flood_rate_per_hour	每小时消息上限，0 表示关闭本档	60
anti_flood_night_enabled	凌晨/夜间独立限速开关	false
anti_flood_night_start_hour	夜间限速开始小时（0-23）	0
anti_flood_night_end_hour	夜间限速结束小时（0-23）	6
anti_flood_night_rate_*	夜间每秒/每分钟/每小时消息上限	3/10/30
join_audit_enabled	入群自动审核开关	false
join_llm_moderation_enabled	入群 LLM 语义审核（可按群覆盖）	false
join_llm_custom_prompt	入群 LLM 自定义审核标准	空
join_accept_overrides_lexicon	通过词优先于通用词库（拒绝词仍最优先）	true
appeal_enabled	刷屏申诉模式开关	false
auto_unban_enabled	定时自动解禁开关	false
auto_moderate_notice	撤回提示开关（自动审核撤回后是否发群内说明）	true
recall_reply_notice	/回复撤回 成功后是否回复确认	true
card_monitor_enabled	名片监控总开关（见「名片监控」章节）	false
card_sync_enabled	名片周期同步兜底	true
card_sync_interval	名片同步间隔（30-3600 秒）	120
card_log_enabled	名片变更/管理员任免记日志	true
card_protect_enabled	名片保护/自动还原	false
card_audit_link_only	名片仅拦链接/店铺（宽松，放行引流昵称）	false
card_audit_enabled	违规名片全量审核（词库+LLM上下文）	false
card_audit_admin_exempt	群主/群管理员/插件管理员豁免违规名片审核；名片保护仍执行	true
card_audit_llm_always	名片强制全量送 LLM（识别引流缩写黑话）	false
admin_change_notify_enabled	管理员任免群内通知	false
lexicon_*_enabled	各类词库独立开关	true
*_enabled	各群管功能独立开关	true

名片监控相关配置项虽有 card_log_enabled 等默认 true 的子项，但受总开关 card_monitor_enabled（默认 false）管控——总开关不开则整个功能完全不动作。

---

SQLite 存储与迁移

v2.0.0 起，插件使用 SQLite 存储审核日志和外置词库：

• 审核日志存储在数据目录的 group_guardian.db
• 外置词库已从 lexicon.json 转为 lexicon.db，仓库不再保留 JSON 词库文件
• WebUI 设置页提供 SQLite 迁移助手，可查看旧日志 JSON 文件状态并手动执行迁移
• 迁移助手执行成功后会删除旧 moderation_logs.json，并保留 moderation_logs.json.bak 备份
• lexicon.db 表结构包含 meta、lexicon_categories、lexicon_keywords
• 当前词库已验证：12 个分类、66,993 条关键词，通过 AC 自动机或纯 Python Trie 参与审核

---

审核匹配引擎：Aho-Corasick 自动机 + 正则回退

v2.2.0 起，词库关键词匹配从正则引擎全面替换为 Aho-Corasick (AC) 自动机，同时保留少量复杂正则作为回退。

为什么需要 AC 自动机？

词库包含 66,993 条关键词，如果用正则逐条匹配，复杂度为 O(n·m)（n=文本长度, m=关键词数），每条消息要扫描近 7 万次。AC 自动机将关键词构建为 Trie 树 + fail 指针，单次扫描复杂度为 O(n + 命中数)，与关键词数量无关。

匹配策略（HybridMatcher）

匹配方式	覆盖范围	复杂度
AC 自动机（优先）	66,993 条词库关键词 + 可拆解为正则的规则	O(n)
正则回退（fallback）	含 \s*、\d{5,12}、.{0,N} 等无法拆解为纯文本的复杂规则	回溯受限

517 条广告规则 + 24,014 条辱骂规则经过 regex_to_literals() 拆解，能转纯文本的走 AC，不能的保留正则。三种匹配结果按类别合并后进入审核流程。

v2.7.3 起随包提供 24,014 条可追溯辱骂规则：24,000 条明确辱骂核心短语/安全分隔变体、13 条短 ASCII 边界正则和 1 条反馈字面量。生成器不做全字符同音替换；cs、cnm、sb、fuck、shit 等短词使用边界正则，降低中文正常词和英文子串误报。未安装 pyahocorasick 时会自动改用纯 Python Trie，而不是逐条扫描全部字面量正则。

为什么仍有一些正则？

广告变体极其丰富，部分变体依赖模糊匹配：

变体类型	示例	匹配方式
谐音替换	加V 加薇 加微 加扣 加q	AC 自动机
符号混淆	V:x1234 薇❤️1234 扣⓪①②③	AC 自动机
空格穿插	加 V 信 1234 微 信: 1234	正则回退
暗语引流	懂的都懂+群 上车滴滴 福利群	AC 自动机
二维码诱导	扫码领 扫一扫 识别二维码	AC 自动机
色情引流	同城约 上门服务 真人视频	AC 自动机

性能保障

1. AC 自动机 O(n)：66,993 条关键词一次扫描，与关键词数量无关
2. 正则回退受限：无法拆解的复杂规则用 .*? 非贪婪 + 文本长度限制（5000字截断），避免回溯爆炸
3. 零运行时编译：Trie 树在插件加载时一次性构建

如果误判怎么办？

• 自动机/正则命中后不会直接撤回，而是交给 LLM二次判断，结合上下文确认是否真的违规
• 每条匹配规则都有独立开关，可按需关闭
• 词库关键词和正则规则存储在 lexicon.db，后续将支持通过 WebUI 热更新

---

外置词库扩展

v2.0.0 起，外置词库使用 SQLite：

• 内置词库文件：lexicon.db
• 运行时数据库：数据目录中的 group_guardian.db
• 词库分类表：lexicon_categories(name, description)
• 关键词表：lexicon_keywords(id, category, keyword)，并对 category 和 keyword 建立索引
• 正则规则表：moderation_rules(id, type, pattern, description, enabled)，v2.1.0 新增
• v2.2.0 起关键词匹配改用 Aho-Corasick 自动机（KeywordAutomaton），词库关键词在插件加载时编译为 Trie 树，运行时零正则开销
• v2.2.0 起脏话/广告规则通过 HybridMatcher（AC 优先 + 正则回退）统一匹配
• lexicon.json 已移除，后续词库维护以 SQLite 为准
• 后续版本将提供 WebUI 词库增删改查能力

---

使用示例

AI 群管场景

管理员: 把123456禁言30分钟
AI: 已禁言 123456 30分钟

管理员: 开启全体禁言
AI: 已开启全体禁言

手动指令

管理员: /禁言 123456 30
[机器人]: 已禁言 123456，时长 30 分钟

管理员: /群名 新群名称
[机器人]: 群名已修改为: 新群名称

智能审核场景

用户A: 访问 www.xxx.com 看片
[机器人自动撤回消息]
⚠️ 已撤回 用户A(123456789) 的消息
原因：违规网址

---

故障排查

AI 无法调用群管工具

1. 确认 AstrBot 版本 >= 4.24.2
2. 确认已配置 LLM Provider 且可用
3. 确认对应功能的开关已启用（*_enabled 配置项）
4. 检查操作者是否为插件管理员或群管理员

管理命令无权限

1. 确认操作者在插件 admin_list 中，或在当前群拥有群主/管理员权限
2. 确认机器人能通过 OneBot 获取群成员角色信息
3. 确认对应功能开关未被关闭

自动审核不生效

1. 检查 auto_moderate_enabled 是否为 true
2. 确认群不在黑名单中
3. 检查管理员列表是否正确配置
4. 确认LLM Provider已配置且可用

撤回失败

1. 确认机器人为群管理员
2. 消息超过2分钟无法撤回
3. 检查NapCat/OneBot是否支持 delete_msg API

SQLite / 词库加载失败

1. 确认插件目录存在 lexicon.db
2. 确认数据目录中的 group_guardian.db 可读写
3. 如从旧版本升级，可在 WebUI 设置页使用 SQLite 迁移助手导入旧日志
4. 如果迁移助手提示确认失败，请输入完整确认文本：我确认迁移并删除旧日志文件[已下线]
5. 查看日志中的具体错误信息

OCR识图不生效

1. 确认 ocr_enabled 已开启
2. 确认已配置支持视觉/图片理解的LLM模型（如 GPT-4o、Gemini Pro Vision 等）
3. 在 ocr_provider_id 中选择对应的 Provider，或留空自动选择
4. 查看日志中是否有 [GroupMgr] OCR识别失败 或 [GroupMgr] OCR LLM调用失败 错误

合并转发消息审核不生效

1. 确认 scan_forward_msg 已开启（默认开启）
2. 确认协议端（NapCat/LLOneBot等）支持 get_forward_msg API
3. 查看日志中是否有 [GroupMgr] 获取转发消息内容失败 错误

QQ收藏撤回不生效

1. 确认 recall_qq_favorite_enabled 已开启（默认开启）
2. 确认机器人为群管理员
3. 插件通过检测消息内容中的QQ收藏特征（sharechain.qq.com、JSON/app数据中的收藏标识）识别，无需依赖发送者昵称

名片监控不生效

第一步：看日志区分故障类型。 改一次群名片，然后查 AstrBot 日志：

• 没有 [GroupMgr] 收到名片变更事件 这行 → 协议端没上报事件，与插件无关。 该事件是 NapCat/LLOneBot 扩展（非 OneBot v11 标准），请确认协议端版本支持 notice_type=group_card 且已开启事件上报。
• 有这行但没动作 → 是开关或判定问题，继续往下看。

第二步：按现象排查。

现象	原因
完全无记录	card_monitor_enabled 总开关未开；或该群不在白名单/在黑名单内
有记录但违规名片不还原	未开 card_audit_link_only 或 card_audit_enabled（这两个默认关）
「科技加我」这类引流名片不拦	只开了「仅拦链接」宽松模式——该模式按设计放行引流昵称，只拦链接。需改开 card_audit_enabled 全量审核
引流缩写（ldxp/catfk）不拦	这类无规律黑话正则无法覆盖，需额外开 card_audit_llm_always 强制送 LLM 判断
还原失败	机器人需为群管理员，且不能对群主/同级管理员改名片
保护名单不生效	需同时开 card_protect_enabled，并在 WebUI「名片监控」页添加该成员

注意：协议不上报操作者（无 operator_id），插件无法区分本人改名片还是管理员改名片， 所以「谁改的」这一列不存在——这是协议限制，不是插件缺陷。

---

更新日志

详见 CHANGELOG.md

---

路线图

以下功能已实现，详见 CHANGELOG.md：

已交付功能	版本
SQLite 存储（审核日志 + 词库迁移）	v2.0.0
代码多文件架构拆分	v1.9.9
数据统计仪表盘（趋势/分布/排行）	v2.1.0
Aho-Corasick 自动机匹配（67k 词库）	v2.2.0
防刷屏检测（秒/分/时独立限流 + 禁言 + 撤回）	v2.2.1
违禁词热更新（规则 + 关键词 + WebUI 即时生效）	v2.2.5
重复消息检测 + 长文本刷屏检测	v2.2.5
规则中心体验升级（分类搜索 + 批量导入反馈 + 减少无效请求）	v2.2.6
单用户审核白名单（免审核/免防刷屏）	v2.2.7
多群独立配置（群级覆盖全局配置）	v2.3.0
入群自动审核（F1）	v2.3.0
刷屏申诉工作流（F2）	v2.3.0
定时自动解禁（F3）	v2.3.0
批量管理操作（F4）	v2.3.0
群管理员动态授权（F5）	v2.3.0
WebUI 稳定性、权限与数据请求修复	v2.3.3
凌晨/夜间独立限速	v2.3.4
二维码识别审核	v2.5.0
组合消息检测（防分段发送规避）	v2.5.0
踢人自动撤回近期消息	v2.5.0
名片监控（变更日志/名片保护/违规审核/管理员任免通知，独立 WebUI 页）	v2.7.0
/回复撤回 静默开关 + 撤回提示开关全路径统一	v2.7.2
多层嵌套审核 + 24,000+ 辱骂规则 + 名片即时/周期检测	v2.7.3
Gemini 批量群管工具 list[string] 参数修复	v2.7.4
全量 AI 审核（llm_moderation_always）+ 多图并发（llm_max_concurrency）+ 名片管理员豁免	v2.7.5
超长内容重叠分片送审 + 图片/LLM/群历史并发与超时边界	v2.7.6
自适应上下文学习（AI 自学本群引流黑话 + 多维度自动审批，独立 WebUI 页）	v2.8.0
视频广告检测（抽帧+视觉OCR+二维码解码） + 感知哈希广告黑名单 + 广告分级处置	v2.9.x
独立 Web 后台（ad_backend） + 本地 RapidOCR + 多识别引擎（local/umi/cloud/llm/auto）	v2.10.x
按角色分权限完善（role_*_require 三级分级，跨平台生效） + 多协议适配升级（Telegram/Discord 群管操作平台路由）	v2.12.0
外链邀请撤回 + 链接安全检测 + GIF 帧级拆分审核 + 语音消息审核 + 群活跃度统计（均默认关闭）	v2.13.0
违规积分累进制（首次警告→禁言→踢出，默认关闭）	v2.14.0

未来规划

审核增强

功能	说明	目标版本
违禁词热更新	WebUI 直接增删改审核规则和关键词，即时生效	已完成（v2.2.5）
入群自动审核	处理加群请求，自动通过/拒绝	已完成（v2.3.0）
群名片/昵称违规检测	改名含违规词自动拦截	v2.5.0
语音消息审核	接入语音转文字后送 LLM 审核	已完成（v2.13.0）
群文件审核	拦截含违规内容的文件名或文件内容	v2.5.0
链接安全检测	检查消息中的 URL 是否涉诈/钓鱼/赌博	已完成（v2.13.0）
GIF 帧级拆分审核	动图逐帧拆分，不漏中间帧违规	已完成（v2.13.0）

处罚机制

功能	说明	目标版本
违规积分累进制	首次警告 → 二次禁言 → 三次踢出	已完成（v2.14.0）
刷屏申诉	处罚后给当事人文字申诉机会并自动复核	已完成（v2.3.0）
定时自动解禁	到预设时间自动解封	已完成（v2.3.0）
批量管理操作	选中多人一键禁言/踢出	已完成（v2.3.0）

群运营

功能	说明	目标版本
新人入群欢迎	自定义欢迎语自动发送	v2.4.0
退群提醒	有人退群时通知群主/管理员	v2.4.0
定时消息/公告	定时自动发送通知或公告	v2.5.0
群活跃度统计	日活/周活/月活报表	已完成（v2.13.0）

防骚扰

功能	说明	目标版本
长文本刷屏	单条消息超 N 字判定违规	已完成（v2.2.5）
重复消息检测	同内容发多次自动处置	已完成（v2.2.5）
外链邀请撤回	检测外部群邀请链接并撤回	已完成（v2.13.0）
凌晨时段独立限速	夜间与白天可配置不同的速率上限	已完成（v2.3.4）

权限与配置

功能	说明	目标版本
单用户白名单	指定用户完全豁免所有审核	已完成（v2.2.7）
多群独立配置	每个群各自设置审核策略/词库/时长	已完成（v2.3.0）
按角色分权限	群主/管理员/普通成员不同规则（role_*_require 三级分级，含审核豁免）	已完成（v2.12.0）
多协议适配	支持 Telegram/Discord 等平台群管	受限模式已完成（v2.12.0，文本审核+撤回/禁言/踢人+角色分权）

---

特别鸣谢

• 词库支持：Sensitive-lexicon

---

免责声明

使用本插件即表示您已阅读、理解并同意以下全部条款。如您不同意任何条款，请立即停止使用本插件。

一、一般性声明

1. 本插件（以下简称"本产品"）仅供学习、研究与交流目的，按"原样"（AS IS）提供，不做任何明示或暗示的保证，包括但不限于适销性、特定用途的适用性和非侵权性。
2. 本产品的开发者（以下简称"开发者"）不对本产品的稳定性、安全性、准确性、可靠性作出任何承诺或保证。本产品可能存在缺陷、错误或漏洞，使用者需自行承担全部风险。
3. 开发者保留随时修改、更新、中断或终止本产品的权利，无需事先通知使用者。

二、使用风险与责任限制

1. 使用者应自行评估本产品的适用性，并承担因使用本产品而产生的一切直接或间接风险与责任。
2. 因使用本产品导致的以下情形，开发者不承担任何责任：
   • 账号被限制、封禁、冻结或处罚；
   • 数据丢失、损坏或泄露；
   • 群聊管理操作（包括但不限于误撤回、误禁言、误踢人）造成的纠纷或损失；
   • 因本产品缺陷或故障导致的任何直接或间接损失（包括利润损失、业务中断等）；
   • 因第三方服务（如 LLM API 提供商、QQ 平台等）变更、中断或终止导致的功能异常。
3. 在适用法律允许的最大范围内，开发者对使用者的全部赔偿责任不超过使用者为本产品实际支付的金额（即零元）。

三、审核功能声明

1. 本产品内置的敏感词库、正则表达式及 LLM 智能审核功能仅用于群聊内容的自动化辅助审核，不构成对任何内容的法律认定、事实认定或官方评判。
2. 自动审核结果可能存在误判（将正常内容判定为违规）或漏判（未识别出违规内容），使用者不应将审核结果作为唯一依据，应结合人工复核与实际情况综合判断。
3. 本产品的审核规则和词库基于开发者经验编写，无法覆盖所有违规场景，也不保证对特定内容一定生效。
4. LLM（大语言模型）的审核判断受模型能力、提示词设计、上下文长度等因素影响，存在固有的不确定性，开发者不对 LLM 的任何输出内容承担责任。

四、群管操作声明

1. 本产品涉及的消息撤回、禁言、踢人、设置管理员等群管操作属于高风险操作，使用者应确保：
   • 已获得群主或管理员的明确授权；
   • 操作对象和操作内容已核实确认；
   • 遵守所在平台（如 QQ、Telegram 等）的相关服务条款与社区规范。
2. 因未获授权或违规使用群管操作而引发的任何纠纷、处罚或法律责任，由使用者自行承担，开发者不承担连带责任。
3. 本产品通过 AI 自动执行的群管操作（如 LLM 工具调用），使用者应知悉其自动化性质，并对 AI 的操作行为承担最终责任。

五、隐私与数据声明

1. 本产品不会收集、上传、传播任何用户聊天内容至开发者或第三方服务器。
2. LLM 审核过程中发送至 LLM API 的文本仅用于实时判断，传输过程受 LLM 服务商的隐私政策约束，开发者无法控制也不对此负责。
3. 本产品在本地存储的审核日志与运行时词库数据库（group_guardian.db）、内置词库数据库（lexicon.db）、旧日志备份（如 moderation_logs.json.bak）和配置文件由使用者自行管理，使用者应采取合理措施保护这些文件中的敏感信息不被未授权访问。
4. 本产品的 WebUI 管理接口目前未内置鉴权机制，使用者应确保 AstrBot 管理面板仅在内网或受信任的环境中访问，避免将服务直接暴露于公网。因未授权访问导致的配置篡改、数据泄露等后果，由使用者自行承担。

六、法律合规

1. 使用者在使用本产品时，应严格遵守所在国家或地区的法律法规，包括但不限于：
   • 《中华人民共和国网络安全法》《个人信息保护法》《数据安全法》等；
   • 所在平台的服务协议与社区规范；
   • 关于网络内容审核、信息安全的相关法规。
2. 使用者不得将本产品用于任何违法违规目的，包括但不限于：
   • 侵犯他人隐私权、名誉权、肖像权等合法权益；
   • 传播违法信息或进行网络攻击；
   • 对他人进行骚扰、威胁或歧视；
   • 其他违反法律法规或公序良俗的行为。
3. 因使用者违法违规使用本产品而产生的一切法律责任，由使用者自行承担，开发者不承担任何连带责任，并保留配合执法机关调查的权利。

七、知识产权

1. 本产品采用 MIT 开源许可证发布，使用者应遵守该许可证的条款。
2. 本产品内置的敏感词库部分内容来源于 Sensitive-lexicon 项目，相关内容的知识产权归原作者所有。
3. 本产品中引用的第三方库、框架和服务的知识产权归各自权利人所有。

八、其他

1. 本免责声明的最终解释权归开发者所有。开发者有权根据需要更新本声明，更新后的声明自发布之日起生效。
2. 本免责声明适用中华人民共和国法律。如发生争议，双方应友好协商解决；协商不成的，提交开发者所在地有管辖权的人民法院诉讼解决。
3. 本免责声明中任何条款被认定为无效或不可执行的，不影响其余条款的效力。

---

许可证

MIT License

---

Star History