一个功能强大的 AstrBot 插件，支持多群联动的违规管理系统，提供禁言、踢人、警告、黑名单等完整的群管理功能。
- 🔗 多群联动：支持多个 QQ 群组成联动网络，一次操作同步执行
- 🛡️ 双层权限：超管和群管分级权限控制
- 📊 完整记录：SQLite 数据库存储所有处罚记录，可查询和撤销
- 🚫 智能黑名单：自动拦截黑名单用户进群（支持 OneBot v11 协议）
- 📢 播报系统：所有处罚操作自动向播报群推送通知
- 克隆本插件到 AstrBot 的插件目录：
cd AstrBot/data/plugins/
git clone https://github.com/Watanabehato/astrbot_plugin_QManagementMaster.git- 重启 AstrBot 或通过 WebUI 重载插件
首次启动后，前往 AstrBot WebUI > 插件管理 > QManagementMaster > 配置：
在 WebUI 中添加超管 QQ 号到 super_admins 列表：
- 点击"添加项"按钮
- 输入超管的 QQ 号
- 点击"保存配置"
你可以在 WebUI 中直接配置群网络，或者通过指令动态配置：
WebUI 配置方式：
- 在
groupsJSON 编辑器中填写联动组对象 - 对象的键是联动组名称，值里设置
log_group播报群和exec_groups执行群列表 - 保存配置后重载插件生效
指令配置方式（推荐，实时生效）：
/g_join <组名>：将当前群加入联动组的执行群列表/g_log <组名>：将当前群设为该组的播报群/g_list [组名]：查看联动组配置
禁言用户，在所有执行群中生效。时长支持自定义格式。
/mute @张三 60 发广告 # 纯数字 = 分钟
/mute @张三 30m 刷屏 # 30分钟
/mute @张三 2h 恶意发言 # 2小时
/mute @张三 1d 严重违规 # 1天
/mute 123456789 30 刷屏
踢出用户，加上 -b 参数会同时加入黑名单
/kick @张三 违规 -b
/kick 123456789 恶意骚扰
警告用户，不执行实质处罚，仅记录并通知
/warn @张三 注意言行
查询用户的违规历史记录
/record @张三
/record 123456789
生成全局违规记录汇总报表，以图片形式返回。明细每页 100 条，可翻页
/gminfo # 第 1 页
/gminfo 2 # 第 2 页
撤销处罚记录
- 禁言：解除所有执行群的禁言
- 踢出：从黑名单移除
/undo 42 误操作
将当前群加入联动组
/g_join 主群网络
将当前群从联动组移除
/g_leave
将当前群设为播报群
/g_log 主群网络
查看联动组配置（可选指定组名筛选）
/g_list
/g_list 主群网络
- 读取插件配置文件中的
super_admins列表 - 可执行所有指令，包括网络管理
- 通过群角色判定 (
admin或owner) - 可执行处罚、查询、撤销指令
- 不可管理网络拓扑
本插件的联动处罚是全网生效的，请务必理解以下信任边界：
- 跨群越权：联动网络内任意一个执行群的群管理员（
admin/owner），即拥有对该网络内所有执行群的处罚权限（禁言 / 踢出 / 拉黑）。也就是说，某个分群的管理员可以对整个联动网络下的所有群成员执行处罚。 - 黑名单拦截范围：
/kick <目标> -b加入黑名单后，其自动踢出拦截对机器人所在的任意群生效（依赖group_increase通知事件），并不局限于本联动网络——只要黑名单用户加入了机器人在的群，就会被踢出并拒绝加群。 - 实践建议：只将可信群管所在的群加入同一联动组；不要把不信任的群或成员众多、管理权限分散的群纳入同一网络，以免管理员权限被滥用而波及全网。
当前版本刻意不在代码层面收紧跨群权限（维持联动即信任的设计），上述行为为预期行为，请依据本节说明谨慎规划联动组拓扑。
{
"super_admins": ["QQ号1", "QQ号2"],
"groups": {
"联动组名": {
"log_group": "播报群群号",
"exec_groups": ["群号1", "群号2"]
}
},
"blacklist": [
{
"qq": "QQ号",
"reason": "原因",
"time": "2026-06-17 10:00:00"
}
]
}id：记录ID（自增主键）action_type：操作类型 (mute/kick/warn)target_qq：目标QQ号operator_qq：操作者QQ号reason：原因duration：时长（仅禁言）timestamp：时间戳status：状态 (active/revoked)
某社区有3个QQ群（主群、分群1、分群2），希望违规处理在所有群同步执行：
- 超管在3个群分别执行
/g_join 社区网络 - 超管在主群执行
/g_log 社区网络（设为播报群） - 之后任何群管在任意群执行
/kick @违规用户 广告 -b - 该用户会在3个群同时被踢出，并加入黑名单
- 主群收到播报通知
某用户被踢出并加入黑名单后，尝试重新加入任意执行群：
- 插件自动监听 OneBot v11 的
group_increase事件 - 检测到该用户在黑名单中
- 立即踢出并拒绝加群请求
- 向播报群发送拦截通知
支持的协议端：
- ✅ Snowluma（OneBot v11）
- ✅ NapCat（OneBot v11）
- ✅ go-cqhttp（OneBot v11）
- ✅ 其他实现了 OneBot v11 标准的协议端
群管发现某次禁言操作有误：
- 执行
/record @用户查看历史记录 - 找到对应的记录ID（如 42）
- 执行
/undo 42 误操作撤销处罚 - 用户在所有执行群解除禁言
- 首次使用必须配置超管：在 AstrBot WebUI 的插件配置页面添加超管 QQ 号
- 权限要求：机器人必须拥有群管理员权限才能执行踢人和禁言操作
- 平台兼容性：
- ✅ 完全支持 OneBot v11 协议（Snowluma、NapCat、go-cqhttp 等）
- ✅ 黑名单自动拦截功能已适配 OneBot v11 的
group_increase通知事件 ⚠️ 其他平台需确认是否实现了 OneBot v11 标准
- 数据安全：建议定期备份数据库文件
data/plugin_data/QManagementMaster/records.db - 黑名单管理：
- 可以在 WebUI 中查看和手动编辑黑名单
- 使用
/kick -b自动添加到黑名单 - 黑名单用户尝试加群时会被自动踢出（需要机器人有管理员权限）
- 🐛
/mute不再固定取剩余参数第一个 token 作为时长，而是从清理后的参数中定位第一个合法时长；即使适配器残留@昵称(QQ)/[At:QQ]/[CQ:at,qq=QQ]等目标 token，也不会再误报“时长格式错误” - 🔧 目标解析只在首个 token 确实是命令名时才移除命令，兼容 AstrBot 已经剥离命令名的场景
- 🐛 进一步加固 @目标解析：识别到消息链 At 目标后会移除参数中的所有文本化 At 占位符，并兼容
[CQ:at,qq=...]，避免/mute @用户 1m 原因继续把 At 占位符误当成时长
- 🐛 修复部分适配器会在
event.message_str中保留[At:QQ]占位符，导致/mute @用户 1m 原因把 At 占位符误当作时长的问题；目标解析现在会清理文本化 At 占位符，并兼容消息链缺少 At 组件的情况
- 🐛 修复
/mute/kick/warn在 @提及目标 时因参数错位而报「参数不足」的问题（event.message_str不含 @提及，导致按位置取参整体错位）；@形式与纯 QQ 号形式现已统一解析，原因支持含空格 - 🐛
/kick的-b标志不再被误并入原因文本 - 🐛 目标解析跳过机器人自身的 @（@提及唤醒场景下不再误处罚机器人），并忽略 @全体成员（
At.qq="all"）等非数字目标，避免int()未捕获崩溃 - 🔒 修复
/gminfo报表的存储型 HTML 注入：所有来自数据库的字段（原因 / QQ / 时间 / 状态）渲染前统一html.escape转义 - ⚡
/gminfo明细行改为分页（每页 100 条，/gminfo [页码]）并按主键排序，避免记录增长后全表渲染导致图片过大 / 超时 / OOM - 🔧
/record、/gminfo最近记录排序改用主键id，同秒多条记录顺序稳定 - 🔒 群内处罚回执不再回显后端原始异常文本，仅显示失败群号（完整错误仍写入服务端日志）
- 🔧 超管判定与黑名单比较统一
str()强转，配置被手改成数字型时不再静默失效 - 📄 README 补充信任模型说明：联动网络内任一群管即拥有全网处罚权，黑名单拦截对机器人所在任意群生效
- 🔧
groups改为 JSON 对象文本编辑器，参照target_aliases的配置体验，方便在 AstrBot WebUI 中直接编辑复杂群组映射 - 🔄 兼容读取 v1.2.2 的 list 格式、旧 KV 字典格式和新的 JSON 对象格式
- 🐛 修复 AstrBot WebUI 无法编辑 QQ 群联动组配置的问题（
_conf_schema.json新增groups字段） - 🔧 对照 OneBot v11 / SnowLuma API 重构群管理调用，统一使用
send_group_msg、set_group_ban、set_group_kick - 🐛 修复
/mute、/kick、/warn、/undo只作用当前群的问题，改为按联动组执行群列表逐群执行并汇总失败
- ✨ 新增
/gminfo指令 — 全局违规记录汇总，HTML 渲染后通过 T2I 输出为图片 - ✨
/mute支持自定义时长后缀1m/2h/1d，兼容纯数字分钟 - 🐛 修复
/mute/kick/warn/undo操作失败时数据库已写入但返回假成功的问题
- ✨ 联动组配置支持在 WebUI 管理面板直接编辑（
_conf_schema.json新增groups字段） - 🔄 自动迁移旧的 KV 存储数据到插件配置（list 格式）
- 🐛 修复并发
/g_join导致群丢失的竞态条件（加 asyncio.Lock） - ✨ 新增
/g_list指令查看联动组配置 - 🔧 群号匹配统一使用纯群号比对，避免格式不一致问题
- 🐛 修复 Release CI 的 403 权限错误（补
contents: write） - 🐛 修复发布包缺失图标文件（
icon.png→logo.png）
- ✨ 黑名单添加去重：同一 QQ 已存在时更新原因/时间/操作者，不再产生重复条目
- 🧹 清理黑名单拦截流程的调试日志
- 🔧 修复黑名单拦截的群号匹配和踢人逻辑
- 🔧 参考 github_star_verify 插件重写事件处理逻辑
- ✅ 初始版本发布
- ✅ 支持禁言、踢人、警告功能
- ✅ 支持多群联动
- ✅ 支持黑名单自动拦截
- ✅ 支持处罚记录查询和撤销
本项目采用 MIT 许可证。
欢迎提交 Issue 和 Pull Request！
如有问题或建议，请通过 GitHub Issues 联系。
- AstrBot — 本插件基于其框架开发
- astrbot_plugin_github_star_verify — 事件处理逻辑参考了该插件的实现
基于 AstrBot 开发