astrbot_plugin_qqadmin

✨ QQ群管插件 ✨

🤝 介绍

• 本插件利用Onebot协议接口，实现了QQ群的各种管理功能，旨在帮助用户更方便地管理群聊。
• 功能包括：禁言、全体禁言、踢人、拉黑、改群昵称、改头衔、设管理员、设精华、撤回消息、改群头像、改群名、发群公告等等。
• 插件提供前端配置面板，支持默认群模板、按群独立配置、群头像与群名展示等能力。
• 权限模型：仅超级管理员（在插件配置 super_admins 中指定的QQ号）可使用所有群管指令，非超级管理员的指令消息会被静默忽略。Bot 仍需具备群主/管理员角色才能执行相应操作。

📦 安装

在astrbot的插件市场搜索astrbot_plugin_qqadmin，点击安装即可

⌨️ 使用说明

权限说明

• 超级管理员：在插件配置项 super_admins 中填入QQ号，多个QQ号用换行或逗号分隔。只有超级管理员才能使用群管插件的所有指令。
• 超级管理员配置与 AstrBot 自身的管理员配置（admins_id）完全独立，互不影响。
• 非超级管理员发送的指令消息会被静默忽略（不回复、不执行）。
• Bot 本身仍需在群内具备相应角色（群主/管理员）才能执行禁言、踢人等操作。
• 超级管理员免受违禁词检测和刷屏检测的自动处罚。

指令格式

• 所有指令直接发送消息文本即可触发，无需添加任何前缀。
• 指令名称即为消息的第一个词，后续内容作为参数。

群管插件命令表

功能分类	指令格式	说明
NormalHandle 群管理	禁言 <秒数> @用户	对指定成员禁言，秒数可省略则随机
	禁我 <秒数>	对自己禁言
	解禁 @用户	解除指定成员的禁言
	开启全禁 / 关闭全禁	控制全群是否可发言（别名：全员禁言/开启全员禁言/关闭全员禁言）
	改名 <新昵称> @用户	修改指定成员的群名片
	改我 <新昵称>	修改自己的群名片
	头衔 <头衔> @用户	设置群头衔（需Bot为群主）
	申请头衔 <头衔>	设置自己的群头衔（需Bot为群主，别名：我要头衔）
	踢了 @用户	将指定成员移出群聊
	拉黑 @用户	踢出并拉黑指定成员
	上管 @用户	设置管理员（需Bot为群主，别名：设置管理员）
	下管 @用户	取消管理员（需Bot为群主，别名：取消管理员）
	设精 (引用消息)	将引用消息设为精华（别名：设为精华）
	移精 (引用消息)	将引用消息移出精华（别名：移除精华）
	查看群精华	查看精华消息列表（别名：群精华）
	设置群头像 (引用图片)	修改群头像
	设置群名 <新群名>	修改群名称
	撤回 (引用消息) / 撤回 @用户 数量	撤回消息，默认10条
NoticeHandle 公告管理	发布群公告 <内容> (可引用图片)	发布群公告
	查看群公告	查看群公告
BanproHandle 增强管控	禁词禁言 <秒数>	设置触发违禁词的禁言时长
	设置禁词 <词1 词2...>	设置/查看自定义违禁词（支持 +词/-词 增删，别名：禁词/违禁词）
	内置禁词 开/关	开启或关闭内置违禁词检测
	刷屏禁言 <秒数>	设置刷屏触发的禁言时长（0 关闭）
	投票禁言 <秒数> @用户	发起禁言投票
	赞同禁言 / 反对禁言	投票同意或反对禁言
	（自动）违禁词检测	检测违禁词并自动撤回并禁言
	（自动）刷屏检测	检测刷屏行为并自动处理
CurfewHandle 宵禁功能	开启宵禁 HH:MM HH:MM	设置宵禁时间段（开始时间 结束时间）
	关闭宵禁	关闭宵禁任务
JoinHandle 进群管理	进群审核 开/关	开启或关闭进群审核功能
	进群白词 <关键词...>	设置自动批准进群的关键词
	进群黑词 <关键词...>	设置自动拒绝进群的关键词
	未命中驳回 开/关	设置是否拒绝未命中白词的进群申请
	进群等级 <等级>	设置进群等级门槛
	进群次数 <次数>	设置最大进群尝试次数
	进群黑名单 +QQ号 / -QQ号	添加或移除进群黑名单
	进群禁言 <秒数>	设置新进成员的禁言时长（0 表示不启用）
	进群欢迎 <欢迎语>	设置进群欢迎消息（支持 {nickname} 变量）
	退群通知 开/关	开启或关闭退群通知
	退群拉黑 开/关	开启或关闭退群后自动拉黑
	批准 <理由> / 驳回 <理由>	审批进群申请（需引用进群申请消息，别名：同意进群/拒绝进群/不批准）
	（自动）监听进群/退群事件	自动处理进群审核与退群通知
MemberHandle 群成员工具	群友信息	查看群成员活跃情况
	清理群友 <未发言天数> <群等级>	移除不活跃或低等级成员（默认30天10级）
FileHandle 群文件管理	上传群文件 <文件夹名/文件名>	引用文件并上传到指定路径
	删除群文件 <文件夹名或序号> <文件名或序号>	删除群文件或文件夹
	查看群文件 <文件夹名或序号> <文件名或序号>	查看文件夹或文件详情
LLMHandle AI功能	取名 @用户 <抽取消息轮数>	根据聊天记录AI生成群昵称
	取头衔 @用户 <抽取消息轮数>	根据聊天记录AI生成群头衔
配置管理	群管配置 [群号] <配置串>	修改/查看本群或指定群的群管配置（别名：群管设置）
	群管重置 <群号/all>	重置本群或全部群的群管配置

🤝 配置

进入 AstrBot 插件设置页后，可直接使用本插件自带的前端配置面板进行管理。

必须配置项

配置项	类型	说明
super_admins	list	超级管理员QQ号列表。只有此处配置的QQ号才能使用群管插件的所有指令。多个QQ号用换行或逗号分隔。与AstrBot的管理员配置完全独立。必须配置，否则所有命令无法执行。

全局配置项

配置项	类型	默认值	说明
admin_audit	bool	false	开启后进群事件仅通知bot管理员，不再发送到群聊
random_ban_time	string	"30~300"	随机禁言时间范围（秒），用~分隔
vote_ban.ttl	int	120	投票禁言持续时长（秒）
vote_ban.threshold	int	3	投票通过所需票数
llm_get_msg_count	int	10	取名指令获取消息的默认轮数（每轮200条）
level_threshold	int	50	高等级成员阈值

默认群配置项（按群可覆盖）

配置项	类型	默认值	说明
join_switch	bool	true	进群审核总开关
join_min_level	int	8	进群等级门槛（0=不限制）
join_max_time	int	3	进群最大尝试次数
join_accept_words	list	[]	进群白词
join_reject_words	list	[]	进群黑词
join_no_match_reject	bool	false	未命中白词自动驳回
reject_word_block	bool	false	命中黑词自动拉黑
block_ids	list	[]	进群黑名单
join_welcome	string	""	进群欢迎词（支持 {nickname}）
join_ban_time	int	0	进群禁言时长（秒，0=不禁言）
leave_notify	bool	false	退群通知
leave_block	bool	false	退群自动拉黑
builtin_ban	bool	false	内置违禁词检测
custom_ban_words	list	[]	自定义违禁词
word_ban_time	int	360	违禁词禁言时长（秒，0=不禁言）
spamming_ban_time	int	0	刷屏禁言时长（秒，0=不启用）

前端面板说明

在Astrbot插件页面，点击插件logo图进入详情页面，在插件行为下点击"打开"，即可进入群管插件的前端配置面板。

• 左侧为群列表，支持按群名或群号搜索，也可以手动同步最新群列表。
• 右侧为当前选中群的配置表单，顶部显示当前群名称，下方直接展示可编辑配置项。
• "默认群"就是全局默认模板。新群或未单独配置的群，会优先继承默认群配置。
• 每个具体群的第一项配置为"跟随默认配置"。开启时继承默认群，关闭时保存独立配置。
• 切换群时，当前页面的修改会自动触发保存。
• 面板会显示群头像、群名称和群号；群名称会优先通过 QQ 接口获取并缓存。
• 如果某个群在实时列表中显示为 0 人，插件会视为该群已失效并自动清理。
• 面板右上角提供独立的浅色/深色/自动主题切换按钮。

配置思路

• 先把通用规则配置在"默认群"中，作为全局模板。
• 仅对少数特殊群关闭"跟随默认配置"，再按需覆盖个别设置。
• 大多数群如果保持跟随默认配置，后期维护会轻松很多。

📌 注意事项

• 本插件目前仅测试了napcat协议端，其他协议端可能会存在一些不兼容问题。
• 首次使用前，务必在配置中填写 super_admins（超级管理员QQ号），否则所有命令无法执行。
• 超级管理员免受违禁词检测和刷屏检测的自动处罚。
• 想第一时间得到反馈的可以来作者的插件反馈群（QQ群）：460973561（不点star不给进）

👥 贡献指南

• 🌟 Star 这个项目！（点右上角的星星，感谢支持！）
• 🐛 提交 Issue 报告问题
• 💡 提出新功能建议
• 🔧 提交 Pull Request 改进代码