[Plugin] astrbot_plugin_group_guardian

[zcj-ui]

插件信息

{
  "name": "astrbot_plugin_group_guardian",
  "display_name": "QQ群智能守护者",
  "desc": "集28项群管功能与AI智能审核于一体的综合群管理插件。支持禁言/踢人/全体禁言/群名片/公告/群文件/精华消息/群打卡等完整群管工具集；内置智能审核系统：正则初筛+30条上下文+LLM二次判断，精准识别骂人/广告/色情/暴恐/涉枪涉爆/政治敏感/违规网址等违规内容；支持合并转发消息审核、OCR识图审核（3种内置提示词模板+自定义提示词+WebUI下拉选择视觉模型）、QQ收藏/JSON卡片自动撤回；支持外置JSON词库扩展，每个功能独立开关，群白名单/黑名单，管理员免检测，可指定审核专用LLM，WebUI管理面板实时监控。",
  "author": "zhaisir",
  "repo": "https://github.com/zcj-ui/astrbot_plugin_group_guardian",
  "tags": [
    "群管",
    "QQ",
    "AI审核",
    "OCR识图",
    "自动撤回",
    "WebUI面板"
  ],
  "social_link": "https://github.com/zcj-ui/"
}

插件检查清单

• 我的插件经过完整的测试
• 我的插件不包含恶意代码
• 我已阅读并同意遵守该项目的 行为准则。

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_group_guardian

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

1. 框架适应性检查

• 数据持久化违规：
  在 _logs_path 方法中，日志数据被硬编码保存到了插件本地目录：

  def _logs_path(self) -> str:
      return os.path.join(self._get_plugin_dir(), "moderation_logs.json")

  要求：必须从 astrbot.api.star 导入 StarTools，并使用 StarTools.get_data_dir() 获取持久化目录，防止由于容器化部署或插件更新导致的数据丢失。
  修改建议：

  from astrbot.api.star import StarTools
  
  def _logs_path(self) -> str:
      data_dir = StarTools.get_data_dir()
      if not data_dir.exists():
          data_dir.mkdir(parents=True, exist_ok=True)
      return str(data_dir / "moderation_logs.json")

2. 代码质量与编码规范

• 类膨胀与单一职责原则 (SRP) 违背：
  Main 类长达数千行，包揽了 API 注册、群管逻辑拦截、LLM 工具执行和大量的内置指令，显得极其臃肿。建议将 Web 路由、llm_tool 以及基于正则/词库的内容审查核心逻辑拆分到不同的子模块（或使用多重继承/混入类方式组织代码）。
• 重复的局部导入：
  代码中大约有 20 多处 from quart import jsonify, request 的局部导入。频繁局部导入会影响代码整洁度，若确有必要隔离 Quart 依赖，可以将其提为文件顶层延迟导入或是集中管理到一个特定的模块。
• 常量的硬编码：
  AD_PATTERNS 与 SWEAR_PATTERNS 占据了源码开头巨大的篇幅（高达八九百行）。大量的正则表达式严重影响了代码的阅读。建议将这类巨大的规则列表提取至单独的 patterns.py 或者 config.json 等独立文件中。

3. 功能实现与逻辑正确性

• 错误的重复装饰器：
  在 recall_all 命令的声明中，出现了不必要的重复修饰，这表明代码在重构或复制粘贴时出现了疏漏：

  @filter.permission_type(filter.PermissionType.ADMIN)
  @filter.permission_type(filter.PermissionType.ADMIN)  # 重复
  @filter.command("批量撤回")
  async def recall_all(self, event: AstrMessageEvent):

• JSON 提取正则的隐患：
  在 _call_llm_for_moderation 提取 LLM 输出内容时使用了贪婪匹配：

  json_match = re.search(r'\{.*\}', llm_response, re.DOTALL)

  当 LLM 的回答不完全受控且附带大段前言后语时，贪婪匹配可能会截取到意料之外的错误结构（比如包含了外围文本的花括号）。建议改用非贪婪匹配：r'\{.*?\}'，以此来匹配第一个合法闭合的 JSON 块。

4. 可维护性与可读性

• 极高重复性的鉴权与前置检查代码：
  在多达数十个 llm_tool（如 ban_group_member_tool、unban_group_member_tool 等）以及 command 中，几乎复制粘贴了以下相同的样板代码：

  if not await self._is_admin(event):
      yield event.plain_result("仅管理员可以使用此功能")
      return
  ok, msg = self._cfg_check("xxx_enabled", "xxx")
  if not ok:
      ...
  allowed, reason = self._check_group_access(event)
  ...
  group_id = self._get_group_id(event)
  client = await self._get_client(event)

  这些样板代码让单个函数的行数翻倍，且极难维护。建议将这些通用的鉴权、状态检查及对象获取封装到一个自定义的装饰器中，或提取出一个返回特定数据结构的前置判断函数。

---

init.py

该文件为空，符合常规 Python 包的声明标准，无需修改。

---

代码评审团

Linus Torvalds：
看在上帝的份上，为什么要在文件的开头硬塞 800 多行的正则表达式？我滚动鼠标滚轮滚到手指发酸才看到类的声明。你的 Main 类像是变成了一个无底洞垃圾桶，它既负责 Web API 服务、又负责和 LLM 通信、还负责发送消息拦截和处理所有的指令。你听过“关注点分离”吗？还有那些像复读机一样复制粘贴了几十次的 if not await self._is_admin(event):，你为什么不写个装饰器（decorator）？这简直是对代码复用的侮辱。

John Carmack：
我对代码的性能感到担忧。你在提取 JSON 时写了 r'\{.*\}' 并加上了 re.DOTALL，在一个由不可靠的 LLM 生成的长文本里使用贪婪模式，如果你遇到大量文本，正则引擎会耗费大量的性能在回溯上。换成非贪婪匹配 .*? 仅仅是多敲一个问号的事。顺便一提，大量的 try...except Exception: pass 虽然防止了崩溃，但也让你在出错时完全处于盲人摸象的状态，这种吞异常的写法在复杂系统中可是“技术债务炸弹”。

GLaDOS：
哦，看看这个测试对象干的好事。连续两次 @filter.permission_type(filter.PermissionType.ADMIN)。你是不是认为如果加倍赋予管理员权限，程序运行起来就会表现得更加顺从？不，它只会凸显你在复制粘贴时的心不在焉。另外，你硬编码了一个指向本地的日志文件路径，难道你不在乎下一次插件更新时，你辛辛苦苦收集的违规日志就会像被送进焚化炉的同伴方块一样瞬间消失吗？请使用 StarTools.get_data_dir()，至少表现出你懂得如何持久地保存测试数据。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 2 个 Python 文件
• 已选择审核文件: 2 / 2
  已发送至 AI 审核的文件清单

main.py
__init__.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。评论 @astrpluginreviewer review 来重新触发 review，请不要重复提交插件发布 issue。

当前仓库：zcj-ui/astrbot_plugin_group_guardian
剩余触发次数：4

[zcj-ui]

@astrpluginreviewer review

[astrpluginreviewer]

❌ 插件审核失败

您好！在对您的插件进行审核时遇到了问题：

调用AI审核服务时发生内部错误。

---

请根据上述问题进行修改。修改完成后，请在 Issue 正文 中勾选"重新提交审核"复选框以再次触发审核。

此消息由系统自动生成

当前仓库：zcj-ui/astrbot_plugin_group_guardian
剩余触发次数：4

[zcj-ui]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_group_guardian

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

__init__.py

此文件为空，未发现任何代码质量、安全性或框架合规性相关问题。

---

main.py

1. 代码质量与编码规范

• 函数过于臃肿：_web_update_config 方法（约第 310-386 行）充斥着大量的硬编码字段列表（bool_keys, list_keys, int_keys 等）以及面条式的遍历赋值逻辑，圈复杂度极高。如果以后需要新增配置项，维护成本会成倍增加，建议引入类似 pydantic 的库进行请求数据模型的统一验证与序列化。
• 滥用全局异常捕获：在很多地方（如 _get_client，_sync_astrbot_admins，_try_get_sender_id 等）充斥着 except Exception: 并在内部静默处理（pass），这种粗放的捕获方式很容易掩盖真正导致功能失效的底层逻辑错误。

2. 功能实现与逻辑正确性

• 严重的未定义变量错误（NameError）：在 _web_stats 方法的第 263 行，存在代码 "total_logs": len(logs),，但在该方法的作用域中，logs 变量根本未被定义。这会导致在访问 /stats 接口时触发 NameError 异常，造成接口 500 报错。此处应修改为 len(self._moderation_logs)。
• 文档与实现严重割裂：在 recall_all（第 1812 行的 @filter.command("批量撤回")）中，注释写着 用法: /批量撤回 [条数]，但代码解析时（if len(args) >= 2: user_id = args[1]）实际是将第一个参数当成了 user_id（按用户撤回），不仅没有解析条数，反而将数量当作了用户的 QQ 号去比对，这是一个明显的逻辑缺陷。

3. 潜在缺陷或问题

• 异步生命周期中夹杂同步阻塞：在 terminate 这个异步钩子方法（第 52 行）中，直接调用了 self._write_logs_sync(p, data)。虽然插件卸载/关机时的少许磁盘 IO 不会导致严重问题，但作为最佳实践，应使用 await asyncio.to_thread(...) 将同步文件写入剥离出主事件循环，以避免关机卡顿。

4. 框架适应性检查

• 日志记录：✅ 合规。规范使用了 from astrbot.api import logger。
• 数据持久化：✅ 合规。规范使用了 StarTools.get_data_dir() 并且正确处理了 Path 对象进行文件读写。
• LLM 工具使用：✅ 合规。@filter.llm_tool 与 @filter.permission_type 未出现无效混用的情况。所有事件监听器的签名均正确包含了 event 参数。
• 主类规范：✅ 合规。拥有继承自 Star 的 Main 类，且完成了正确的初始化调用。

---

patterns.py

1. 可维护性与可读性

• 此文件几乎全由正则表达式构成。但正则的数量非常庞大（特别是在 AD_PATTERNS 中有上百条）。尽管逻辑集中放在单独的文件中利于阅读，但在没有充分注释的情况下，如果将来遇到特定的误杀或漏判，很难快速定位到是哪一条正则导致的问题。

2. 潜在缺陷或问题

• 正则表达式性能开销：大量使用了不捕获分组 (?:...) 和包含很多或逻辑 | 的正则。即使 main.py 中有 _build_combined_regex 进行正则合并，在遇到极长且存在恶意的文本输入时，某些正则可能会引发严重的性能开销（回溯问题）。
• 部分纯关键字完全可以用更高效的方式替代：正则中存在大量诸如 (?:洗\s*(?:钱|钱)|(?:钱)\s*洗) 这种高度机械化和同质化的拼接模式。如果是为了检测关键词，考虑将这部分提取出来，引入如 Aho-Corasick 自动机算法（例如 flashtext 库）进行多模式匹配，在长文本审核中性能会有百倍以上的飞跃。

---

代码评审团

Linus Torvalds：
"你是在写代码还是在闭着眼睛敲键盘？_web_stats 里面那个 len(logs) 的 NameError 就堂而皇之地放在那里，哪怕你跑过一次那个接口，你都会被弹出的异常扇一耳光！还有那个 /批量撤回，你的文档说是传入'条数'，代码里却把它当成了 'QQ 号'，这种注释和代码对着干的行为，比直接写出 bug 还让人火大！如果这是 Linux 内核的 patch，我会让你把它连同键盘一起扔进垃圾桶。"

乔布斯：
"伟大的产品应当由内而外散发着美感，包括每一行代码。看看 _web_update_config，它就像一个塞满了几十种杂乱电线的机箱。你为什么不在更新配置时使用模型验证？用更优雅的数据绑定来替代这些无尽的硬编码字符串列表。代码应该是艺术品，而不是一堆随时可能松脱的创可贴和胶带。"

雷军：
"朋友，你这 patterns.py 里的正则列表也太多了吧？这么多繁琐的正则拼接，如果有人发了一篇超长的群消息，这个正则匹配的性能我看了都有点虚，Are you ok？而且在 terminate 这个异步关机方法里，你居然直接在事件循环里同步写文件。虽然它可能只卡顿一瞬间，但作为有追求的工程师，顺手包装一个 asyncio.to_thread，让程序的关闭像顺滑的丝绸一样，不香吗？"

Disclaimer: 以上评审内容由 AI 自动生成，仅提供审核参考，并无他意，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 3 个 Python 文件
• 已选择审核文件: 3 / 3
  已发送至 AI 审核的文件清单

main.py
__init__.py
patterns.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。评论 @astrpluginreviewer review 来重新触发 review，请不要重复提交插件发布 issue。

当前仓库：zcj-ui/astrbot_plugin_group_guardian
剩余触发次数：3

[zcj-ui]

正则只是暂时的，我马上换DB了，别追着那个玩意看了，那个500错误忘了提交。。。

[zcj-ui]

为什么内置这么多正则？

本插件内置了 571 条广告正则 和 13 条脏话正则，看起来数量庞大，但这是经过反复权衡后的必要设计：

正则的作用：第一道防线

审核流程分为两层：正则初筛（毫秒级）→ LLM二次判断（秒级）。正则的作用是在毫秒内过滤掉明显违规的内容，避免每条消息都调用LLM，既节省API费用又降低延迟。

为什么需要571条广告正则？

广告变体极其丰富，举几个例子：

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

每一种变体都需要一条独立的正则来覆盖，571条并不是冗余，而是对抗广告变体的必要覆盖面。

性能如何保障？

不用担心性能问题，插件已做了多层优化：

1. 组合正则合并：571条正则被合并为约2个组合正则对象，匹配时只需执行2次而非571次
2. 文本长度限制：超过5000字的文本自动截断，防止超长文本导致正则回溯
3. 非贪婪匹配：所有正则使用 .*? 非贪婪模式，避免回溯爆炸
4. 预编译缓存：所有正则在插件启动时一次性编译，运行时零编译开销

如果误判怎么办？

• 正则命中后不会直接撤回，而是交给 LLM二次判断，结合上下文确认是否真的违规
• 每个词库类别都有独立开关（scan_swear、scan_ad等），可按需关闭
• 外置词库 lexicon.json 支持自定义关键词，修改后自动生效无需重启 @astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_group_guardian

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

• 代码质量与编码规范:

  • 导入顺序违规: import tempfile 出现在 _write_logs_sync 方法内部；且在文件头部 _PLUGIN_NAME 变量赋值插在了 import 语句中间 (from .patterns import ... 在其后)。建议将所有标准库和第三方库的导入移至文件最顶部，以符合 PEP 8 规范。
  • 上帝类 (God Class) / 违反单一职责原则 (SRP): Main 类长达 1600 多行，包揽了配置管理、Web API路由注册、日志本地持久化、正则校验、LLM 审查逻辑以及大量的群管指令。这极大地降低了代码的可读性和可维护性，建议将 Web 路由、权限校验、文本审核逻辑等拆分为独立的类或外部服务。
  • 代码嵌套过深（面条代码）: 如 _check_qq_favorite 和 _check_qq_favorite_non_forward 等方法中，存在高达 6-8 层的 if/elif/for/isinstance 嵌套，阅读极其困难。建议通过尽早 continue/return（卫语句）或提取辅助函数进行重构。

• 功能实现与逻辑正确性:

  • Web API 的隐式强依赖: 代码头部尝试 except ImportError 捕获 quart，但在没有 quart 的运行环境中（如较新框架使用 fastapi 时），quart_request 会被设为 None。虽然不会阻断插件加载，但在用户调用涉及 await quart_request.get_json() 或 quart_request.args 的接口时，会直接抛出 AttributeError: 'NoneType' object has no attribute 导致该功能完全不可用。
  • 同步写入退化风险: _save_logs 方法中，捕获到 RuntimeError 后直接退化执行同步方法 self._write_logs_sync(p, data)。若在事件循环之外等罕见边界情况触发此逻辑，这会导致整个线程（甚至事件循环，如果是由于某些误判触发）被文件 I/O 阻塞。
  • 非标准 LLM API 调用: _try_provider 函数中暴力尝试 chat, invoke, complete 等方法。这容易因为参数签名不匹配在内部产生混乱的异常堆栈，建议严格遵照 AstrBot 的标准 context.llm_generate 或提供明确且类型安全的 Provider 调用适配器。

• 安全漏洞与最佳实践:

  • 敏感信息暴露风险: WebAPI 接口 _web_get_config 方法中，仅过滤了包含 "token", "secret", "password", "key" 的字段。若用户配置文件中存有其他命名习惯（如 ak, sk, auth 等）的敏感凭证或隐私字段，存在被直接通过此 API 暴露的风险，建议改用显式的“白名单”机制来下发允许公开的配置项。
  • ReDoS（正则表达式拒绝服务）风险: 文本虽截断至 5000 字符，但结合巨量的正则表达式依次遍历（如 SWEAR_PATTERNS, AD_PATTERNS 以及外置词库），面对精心构造的长段重复无意义恶意文本时，部分正则仍有引发高频回溯、短暂拖慢并耗尽 CPU 资源的隐患。

• 潜在缺陷或问题:

  • 内存泄露风险: self._admin_role_cache 字典虽然在其存储的 Tuple 中记录了时间戳并设定了 ttl (300.0s)，但代码中只有惰性的“查询时校验”，而没有任何主动或定期的过期键清理机制。在长时间运行且交互频繁的机器人实例中，该字典体积将持续膨胀，造成内存泄漏。

init.py

• 代码质量与逻辑正确性:
  • 该文件为空，作为 Python 包声明文件，结构完全符合规范，未发现任何安全及逻辑问题。

patterns.py

• 代码质量与编码规范:
  • 正则表达式构建冗余: 大量正则表达式存在逻辑重合及机械生成导致的无意义冗余。例如 r'(?:成\s*(?:人|人)|(?:人)\s*成)' 中，(?:人|人) 毫无意义，可以直接化简为 (?:成\s*人|人\s*成)；此外，存在多组高度重合的模式（如 r'(?:18\+\s*(?:进|加|入|群|裙|q|Q|扣|微|v|V))' 与另一组纯数字版本），在长文本匹配时增加了不必要的开销，建议人工合并与优化。

---

代码评审团

Linus Torvalds：我真是不敢相信我的眼睛，你竟然把 1600 多行代码全部塞进了一个 Main 类里！你是打算把整个宇宙的质量都塞进这个类的构造函数里吗？这不仅是在嘲犯“单一职责原则”，这简直是在对软件工程竖中指。把你的 Web 路由、配置管理和业务逻辑给我拆开！现在！

Steve Jobs：这代码缺乏对美的基本认知。看看你的 _check_qq_favorite 方法，嵌套了大概七八层条件判断，里面全是各种繁杂的 if isinstance(seg, dict):。这种面条式的代码块是对阅读者体验的极度不尊重。你需要保持极简，使用尽早 return 的卫语句，把复杂性藏在优美的辅助函数后面，而不是把这种逻辑迷宫直接糊在工程师的脸上。

Rick Sanchez：Wubba Lubba Dub Dub！伙计，看看那个 patterns.py 里的正则！r'(?:成\s*(?:人|人)|(?:人)\s*成)' —— 你是喝了太多我的便携式烧瓶里的东西吗？连我那个傻外孙 Morty 都知道 (?:人|人) 这种写法完全没有意义且浪费算力。你是在指望靠这种机械生成的、冗长又低效的正则拯救多重宇宙的群聊环境吗？快整理一下你的正则树，别让 CPU 在无用的回溯里浪费时间打嗝！

Disclaimer: 以上评审内容由 AI 自动生成，仅提供审核参考，并无他意，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 3 个 Python 文件
• 已选择审核文件: 3 / 3
  已发送至 AI 审核的文件清单

main.py
__init__.py
patterns.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。评论 @astrpluginreviewer review 来重新触发 review，请不要重复提交插件发布 issue。

当前仓库：zcj-ui/astrbot_plugin_group_guardian
剩余触发次数：2

[zcj-ui]

一个不够吗这功能挺简单的

[zcj-ui]

安全修复

• _web_get_config 敏感信息泄露修复：从黑名单过滤改为白名单机制，仅返回 _conf_schema.json 中定义的配置项，防止未知命名的敏感字段（如 ak/sk/auth 等）被API暴露
• quart_request 为None时WebAPI防护：添加 _check_quart_available + _wrap_web_handler 包装器，所有Web API在Quart不可用时返回明确错误而非 AttributeError
• _save_logs 同步写入退化修复：RuntimeError 时不再退化执行同步文件写入，改为跳过并警告，避免阻塞事件循环

代码质量

• import顺序修正（PEP 8）：import tempfile 从方法内部移至文件顶部；_PLUGIN_NAME 移至所有import之后
• _check_qq_favorite 深层嵌套重构：提取 _is_qq_favorite_text、_check_dict_seg_qq_favorite、_check_forward_msg_qq_favorite 三个辅助方法，将6-8层嵌套降为2-3层
• _register_web_apis 循环注册：20个重复的 register_web_api 调用改为数据驱动的循环注册，代码量减少90行
• _admin_role_cache 内存泄漏修复：缓存超过1000条时自动清理过期条目，防止长时间运行后字典无限膨胀

正则优化

• patterns.py 冗余正则清理：修复335处 (?:X|X) 无意义重复模式（如 (?:人|人) → 人），AD_PATTERNS从571条精简为558条，减少正则引擎不必要的分支回溯 @astrpluginreviewer review