Skip to content

usage.md

Latest commit

 

History

History
199 lines (133 loc) · 6.76 KB

usage.md

File metadata and controls

199 lines (133 loc) · 6.76 KB
Raw

功能详解与使用

本文档讲清楚 bot 能做什么、告警长什么样、各检测机制的行为与边界。 命令用法见 commands.md，配置项见 config.md。

1. 总体行为

  • 监听 MONITOR_GROUP_IDS 里的学生群，默认静默：不在学生群回复、不私聊、不踢人/禁言/撤回、不下载或执行群文件。
  • 命中即告警，没有风险分数/阈值，路由分两类：
管理员群（确凿告警）：
    黑名单用户、消息命中黑名单、连续拆分消息命中黑名单、
    入群/改名资料命中黑名单、转发消息内文本/发送人昵称命中黑名单。
资源群（人工复核）：
    图片、文件信息、转发消息集合（含有限嵌套展开出的内嵌图片/文件）。
    未配置资源群时仅写入审计记录，不转发任何群。

同一"群+人+规则+内容"组合 10 分钟内去重，不会连环刷屏。

2. 关键词检测与模糊正则

黑名单/白名单关键词都按正则处理：

  • 普通写法自动变成"可穿插空白和不可见字符"的模糊正则：
高价收校园网

可以匹配：

高价收校园网
高 价 收 校 园 网
高​价​收校园网        （含零宽字符）
  • 高级正则用 re: 开头，原样编译（忽略大小写）：
re:高\s*价\s*收.*校\s*园\s*网
  • 黑名单优先。白名单用户完全跳过检测；白名单关键词命中时只抑制图片/转发的人工复核噪声，不压制黑名单命中。

添加关键词：

/guard blacklist keyword add 高价收校园网
/guard blacklist keyword add re:高\s*价\s*收.*v\s*p\s*n
/guard whitelist keyword add 校园网报修

3. 成员入群与改名监控

Bot 监控两类事件：新成员入群、群名片改动。

事件触发时会尽量读取群名片、昵称、特殊头衔、签名等字段，然后跑黑名单关键词正则。

示例：黑名单里有 高价收校园网，有人把群名片改成"高 价 收 校 园 网，带 vpn"→ 管理员群收到"入群/改名资料命中黑名单"告警。

4. 图片、文件、转发合集与资源群

资源群用于集中接收需要人工复核的资源，建议单独建群，只加管理员和监控 Bot。

RESOURCE_GROUP_IDS 留空      = 不配置资源群（不回退到管理员群），复核项仅落审计
RESOURCE_FORWARD_IMAGES=true   图片：把原图重发到资源群
RESOURCE_FORWARD_FILES=true    文件：只发文件名/大小/下载链接（若消息带 url）；
                               Bot 不下载、不转存群文件内容，天然免疫大文件 DoS
RESOURCE_FORWARD_FORWARDS=true 转发集合：有限嵌套展开，内嵌图片/文件转发资源群；
                               内嵌文本/发送人昵称命中黑名单则告警管理员群；
                               展开失败（API 不支持等）会明确告知"无法展开"

资源群图片转发示例

4.1 文件

默认不判断文件后缀。检测到群文件或文件消息 → 文件名/元数据发到资源群。开关：REVIEW_FILE_UPLOADS=true。

4.2 图片

检测到图片消息 → 图片转发到资源群。开关：REVIEW_IMAGE_MESSAGES=true。

不内置 OCR，不依赖图片识别判断风险。图片、花字、拼音、英文混写默认交给管理员人工判断。

4.3 图片和文件的判定边界

普通聊天里发送图片：OneBot 一般是 image 消息段，走图片复核规则。
把 png/jpg 当作群文件上传：OneBot 一般是 group_upload 或 file 消息段，走文件复核规则。

图片不会只因为后缀是 .png 就被当成文件，以 QQ/NapCat 上报的消息类型为准。

4.4 转发合集

检测到转发消息集合 → 有限嵌套展开（深度/条数上限见 config.md）， 内嵌文本/发送人昵称跑黑名单检测，内嵌图片/文件转发资源群；展开失败明确告知。 开关：REVIEW_FORWARD_MESSAGES=true。

5. 连续拆分消息检测

同一用户在同一群内短时间内（默认 300 秒窗口）连续发送的纯文本会被拼接后跑黑名单正则。

例如黑名单里有 高价收带vpn校园网，用户分开发：

高
价收
带vp
n校
园网

拼接后命中 → 告警里展示完整拼接序列（│ 分隔每条消息）。命中后自动清空拼接缓存、重新开始新一轮匹配，后续消息不会因为历史拼接而连环告警。

窗口参数：RECENT_TEXT_TTL_SECONDS=300、RECENT_TEXT_MAX_ITEMS=12（见 config.md）。

6. 管理员群命令与 @ 消歧

命令在管理员群直接发即可（默认免 @，带 @ 也有效），完整列表见 commands.md。

多实例 @ 消歧（默认 REQUIRE_AT_MENTION=false 时自动生效）：

不 @             → 管理员群内所有 bot 都响应
@某个 bot        → 只有被 @ 的 bot 响应，其余静默
@全体成员        → 所有 bot 都静默

REQUIRE_AT_MENTION=true 时额外要求"必须 @ 本 bot 才响应"（不 @ 连命令都不执行），一般保持默认 false。

提示：管理员群内直接发 /guard help 可看总览，/guard <命令> help 看子命令详情， 日常维护基本靠这两个命令就够了。

7. 告警长什么样

7.1 管理员群告警

管理员群告警示例

【群护网告警】消息命中黑名单
项目：monitor-qq-bot
事件ID：xxxx
来源群：xx学院拼车一群(10086)
发送人：小明(20001) Lv.12 入群:2023-07-20
规则：高价收校园网
内容：高价收校园网，懂的私聊

告警消息会附带发送人头像图（发送失败不影响文本）。

7.2 资源群通知

【群护网资源复核】图片 1/1
项目：monitor-qq-bot
事件ID：xxxx
来源群：xx学院拼车一群(10086)
用户QQ：20001
（随后是图片本体 / 文件信息 / 转发集合说明）

7.3 审计与统计

所有命中事件写入 Redis 审计（TTL 3 天，最多 1000 条）。在管理员群：

/guard audit                # 最近告警事件
/guard audit stats          # 哪个群哪个人触发几次（按次数排序）

8. 已知限制（请管理员心里有数）

  • 拼音、英文、谐音、花字、emoji 替字和图片文字都可能绕过自动检测——规则需要管理员持续维护。
  • 普通关键词只能防"空白/零宽穿插"，防不住"中间插入其他字"或"整字替换"；高频变形用 re: 规则补防。
  • 图片内容不识别（无 OCR），图片风险完全靠人工复核。
  • 本项目不实现自动处置（踢人、禁言、撤回），处置由管理员人工执行。