koishi-plugin-regex-guard

面向 Koishi 群聊场景的正则规则守卫插件，用于集中管理、测试与执行消息拦截策略。

koishi-plugin-regex-guard 提供一套以正则表达式为核心的群消息治理方案。你可以为不同群组配置规则，按优先级筛选命中项，并在命中后执行撤回、回复、禁言等动作。

[!NOTE] 这个仓库当前更偏向“规则管理与运营”体验：除了命令行管理外，还内置了 Koishi 控制台页面，方便可视化维护规则、测试匹配结果，以及查看调试记录。

适合用来做什么

• 管理敏感词、广告词、刷屏模式等正则规则
• 针对不同群组应用不同治理策略
• 给特定用户设置额外白名单
• 在命中后自动撤回消息、发送提醒、执行禁言
• 在正式启用前先测试消息是否会命中规则
• 通过导入/导出快速迁移规则集

核心能力

规则驱动的自动处理

每条规则都可以独立控制以下行为：

• 是否启用
• 优先级
• 触发概率
• 正则表达式与 flags
• 目标群组范围
• 额外白名单用户
• 是否豁免管理员
• 是否撤回消息
• 命中后的回复模板
• 禁言时长

当一条消息进入系统后，插件会先过滤作用范围与豁免条件，再执行正则匹配，最终从命中的规则中选出优先级最高的一条，并按该规则的触发概率决定这次是否真正执行动作。

可视化控制台

插件内置 Koishi 控制台页面，分为以下几个区域：

• 规则列表：查看当前规则、快速启停、进入编辑
• 规则编辑：创建或修改规则内容
• 测试匹配：输入消息内容，预览命中规则和动作计划
• 导入 / 导出：以 JSON 形式备份或恢复规则
• 调试日志：查看匹配、选择、执行结果等事件记录

这套界面更适合日常运营使用，尤其是在规则较多时，比手动维护文本命令更直观。

管理命令

插件提供 rguard 命名空间下的管理命令，用于常见维护工作：

rguard.add
rguard.list
rguard.get
rguard.update
rguard.delete
rguard.enable
rguard.disable
rguard.test
rguard.export
rguard.import

这些命令主要面向管理员，用来做快速调整、排查和备份。

规则如何生效

一条消息会按照下面的顺序被处理：

1. 检查规则是否启用
2. 检查群组范围是否匹配
3. 检查用户是否在白名单中
4. 检查是否需要豁免管理员
5. 使用正则表达式进行匹配
6. 在命中的规则中按优先级选择最终规则
7. 根据该规则的触发概率随机决定本次是否触发
8. 依次执行撤回、回复、禁言动作

这种处理方式适合把“是否命中”和“命中后做什么”拆开管理，避免同一条消息被多条规则重复执行。

回复模板变量

规则命中后，如果配置了回复内容，可以在模板里使用变量：

• {nickname}：用户昵称
• {match}：完整命中文本
• {group1} ~ {group9}：捕获组内容

在控制台的测试页面里，可以直接验证这些变量最终会如何展开，方便调整提示文案。

使用体验亮点

• 规则集中管理：规则保存在数据库中，不需要把策略散落在多个脚本里
• 命中前可测试：先验证，再启用，减少误伤
• 支持批量迁移：规则可导入、导出，便于备份和复用
• 带调试记录：能看到匹配与执行过程，更容易定位问题
• 兼顾命令与界面：适合轻量维护，也适合长期运营

适用场景

• 社群敏感词治理
• 广告与引流内容拦截
• 指定格式消息约束
• 群聊秩序维护
• 需要按群组定制治理规则的机器人场景

项目概览

这是一个围绕 Regex Guard / 正则守卫 构建的 Koishi 插件，核心目标不是只“拦截一条消息”，而是把规则管理、规则测试、规则迁移和调试观察整合到同一个插件里，方便长期维护一套可演进的群聊治理体系。