nonebot_plugin_admin 是一个基于 NoneBot2 的群管理插件集合，当前包含基础群管、入群审批、内容审核、统计分析、广播、事件提醒、成员清理等功能。
当前 main-check 分支正在做结构整理与重构优化，目标是先稳定现有能力，再逐步清理历史耦合与文档遗留问题。现阶段目录结构和部分实现已经完成分域拆分，根目录说明文档也已按当前代码状态更新。
- 基础群管：禁言、解禁、改名片、踢人、拉黑、管理员增减、头衔、撤回、精华消息
- 入群审批：审批词条、拒绝词条、分群管理员、手动处理请求、AI 广告拦截
- 内容审核：违禁词检查、图片审核
- 统计分析：消息记录、发言排行、群词云、停用词、早晚安群消息
- 广播：广播预览、二次确认、排除群维护
- 事件提醒：防撤回、事件通知
- 成员清理：规则筛选、清理锁
- Dashboard：Web 管理面板、API 接口、操作日志
pip install nonebot-plugin-admin或使用 nb（推荐）：
nb plugin install nonebot-plugin-adminnb 命令下载的不用手动导入
pip下载的话，在 bot.py 中加载插件：
nonebot.load_plugin("nonebot_plugin_admin")或者在pyproject.toml中的plugins = 追加：
plugins = [ xxx, xxx, "nonebot_plugin_admin"]推荐 Python 3.9 及以上版本。
依赖会在安装插件时自动安装，如果你是从仓库下载的插件，则需要：
pip install -r requirements.txt以下配置写入 .env 或 .env.prod 等 NoneBot 配置文件。
配置示例如下或： ./.env.example
# nonebot_plugin_admin 配置示例
# 腾讯云图片安全配置：tenid、tenkeys （当初用这个是因为送额度，很久没研究了，目前不建议使用，可自行实现相关功能）
# 腾讯云图片安全api（当初用这个是因为送额度，很久没研究了，目前不建议使用，可自行实现相关功能）
tenid="xxxxxx"
tenkeys="xxxxxx"
# 是否开启禁言等操作的成功提示【历史遗留功能，应该是不开启的话踢人/禁言等成功没有QQ消息提示】
callback_notice=true # 如果不想开启设置成 false 或者不添加此配置项【默认关闭】
ban_rand_time_min=60 # 随机禁言最短时间，单位秒
ban_rand_time_max=2591999 # 随机禁言最长时间，单位秒
#↓↓↓↓↓↓推荐使用↓↓↓↓↓↓
ai_verify_api_key=sk-xxxxxxxxxxxxxxxx # AI 加群审核 API Key
ai_verify_base_url=https://api.deepseek.com # AI 加群审核接口地址
ai_verify_model=deepseek-chat # AI 加群审核模型名称
ai_verify_proxy= # AI 加群审核单独代理地址
ai_verify_use_proxy=true # 是否允许 AI 加群审核使用代理
#↓↓↓↓↓↓推荐使用↓↓↓↓↓↓
statistics_orm_enabled=true # 是否启用 ORM 存储
statistics_orm_capture_message_content=true # 是否保存消息原文
tortoise_orm_db_url=sqlite:///data/admin3-statistics.db # 数据库连接地址
#↓↓↓↓↓↓推荐使用↓↓↓↓↓↓
dashboard_enabled=true # 是否启用后台 API
dashboard_frontend_enabled=true # 是否启用后台前端页面
dashboard_base_path=/admin-dashboard # 后台挂载路径
dashboard_api_token=please-change-me # 后台 API Token
dashboard_title=群管后台 # 后台页面标题
dashboard_log_file_path=data/admin-dashboard.log # Bot日志文件路径，如果你想让群管后台也显示bot的日志（不配置则只显示本插件自己的日志）
#↓↓↓↓↓↓跨域配置，一般不用配置，除非你把插件中的网页提出来单独部署↓↓↓↓↓↓
dashboard_cors_allow_origins=http://xxx.xxx.xxx.xxx:xxx,http://localhost:xxxx # 允许跨域来源，逗号分隔
dashboard_cors_allow_credentials=false # CORS 是否允许携带凭证
#↑↑↑↑↑↑跨域配置，一般不用配置，除非你把插件中的网页提出来单独部署↑↑↑↑↑↑
#↓↓↓↓↓↓古早用户PR,本人未曾使用过，自行验证↓↓↓↓↓↓
send_group_id = ["xxx","xxx"] # 必填 群号
send_switch_morning = False # 选填 True/False 默认开启 早上消息推送是否开启
send_switch_night = False # 选填 True/False 默认开启 晚上消息推送是否开启
send_mode = 1 # 选填 默认模式2 模式1发送自定义句子，模式2随机调用一句
send_sentence_morning = ["句子1","句子2","..."] # 如果是模式1 此项必填，早上随机发送该字段中的一句
send_sentence_night = ["句子1","句子2","..."] # 如果是模式1 此项必填，晚上随机发送该字段中的一句
send_time_moring = "8 0" # 选填 早上发送时间默认为7:00
send_time_night = "23 0" # 选填 晚上发送时间默认为22:00
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
tenid |
否 | xxxxxx |
腾讯云 SecretId（图片安全审核） |
tenkeys |
否 | xxxxxx |
腾讯云 SecretKey（图片安全审核） |
callback_notice |
否 | true |
是否发送操作成功提示 |
ban_rand_time_min |
否 | 60 |
随机禁言最短时间（秒） |
ban_rand_time_max |
否 | 2591999 |
随机禁言最长时间（秒） |
⚠️ 腾讯云图片安全审核为古早版本加入的功能，目前不太推荐使用。如需图片审核能力，建议评估其他方案。
| 配置项 | 必填 | 默认值 | 推荐启用？ | 说明 |
|---|---|---|---|---|
ai_verify_api_key |
否 | （空） | 推荐 | OpenAI 兼容接口 API Key |
ai_verify_base_url |
否 | （空） | 推荐 | OpenAI 兼容接口 Base URL |
ai_verify_model |
否 | （空） | 推荐 | 使用的模型名称 |
ai_verify_proxy |
否 | （空） | AI 审核请求代理地址 | |
ai_verify_use_proxy |
否 | true |
是否启用代理 |
说明：
ai_verify_use_proxy=false时，AI 审核请求不会走代理ai_verify_proxy仅影响 AI 审核请求，不影响插件内其他网络请求- 未配置
ai_verify_api_key时，AI 审核功能会自动退化为不可用状态 - 会拒绝“请通过一下，谢谢！”这类及机器人加群
⚠️ 此功能由用户 PR 加入，完成度一般，无需求可不用。
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
send_group_id |
是 | （空） | 推送目标群号，JSON 数组或逗号分隔 |
send_switch_morning |
否 | true |
是否启用早安推送 |
send_switch_night |
否 | true |
是否启用晚安推送 |
send_mode |
否 | 2 |
推送模式：1=自定义句子，2=随机一言 |
send_sentence_morning |
否 | （空） | 早安自定义句子列表（mode=1 时生效） |
send_sentence_night |
否 | （空） | 晚安自定义句子列表（mode=1 时生效） |
send_time_morning |
否 | "7 0" |
早安推送时间，格式 "时 分" |
send_time_night |
否 | "22 0" |
晚安推送时间，格式 "时 分" |
说明：
send_mode=1时，使用自定义句子列表send_mode=2时，使用插件内置随机句子逻辑（调用一言 API）send_group_id支持 JSON 数组，也支持逗号分隔字符串
| 配置项 | 必填 | 默认值 | 推荐使用？ | 说明 |
|---|---|---|---|---|
statistics_orm_enabled |
否 | false |
推荐 | 是否启用统计 ORM 存储，填写 tortoise_orm_db_url 后自动开启 |
statistics_orm_capture_message_content |
否 | true |
推荐 | ORM 启用时是否记录消息原文 |
tortoise_orm_db_url |
否 | （空） | 数据库连接 URL |
说明：
- 填写
tortoise_orm_db_url后statistics_orm_enabled会自动设为true，无需手动开启 - 消息记录会同时写入数据库
- 启用后插件会在初始化时自动检测历史文件数据并迁移至数据库，迁移记录通过数据库中的 MD5 去重，避免重复导入
使用 SQLite 时，URL 格式为 sqlite:/// 加数据库文件路径：
Linux 示例：
tortoise_orm_db_url=sqlite:////home/bot/data/admin3-statistics.db四个
/：sqlite://是协议前缀，/home/bot/data/admin3-statistics.db是绝对路径。
Windows 示例：
tortoise_orm_db_url=sqlite:///C:/bot/data/admin3-statistics.db三个
/：sqlite://是协议前缀，C:/bot/data/admin3-statistics.db是 Windows 绝对路径（盘符后用/代替\）。
相对路径示例（相对于 NoneBot 工作目录）：
tortoise_orm_db_url=sqlite:///data/admin3-statistics.db| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
dashboard_enabled |
否 | false |
是否启用 Dashboard API |
dashboard_frontend_enabled |
否 | false |
是否提供前端入口 |
dashboard_base_path |
否 | /admin-dashboard |
Dashboard 挂载路径 |
dashboard_api_token |
否 | （空） | API 鉴权 Token，非空时受保护接口需 X-Admin-Token |
dashboard_title |
否 | Admin Dashboard |
Dashboard 页面标题 |
dashboard_cors_allow_origins |
否 | （空） | CORS 允许的来源，JSON 数组或逗号分隔 |
dashboard_cors_allow_credentials |
否 | false |
CORS 是否允许携带凭证 |
dashboard_log_file_path |
否 | （空） | Dashboard 日志文件路径 |
说明：
dashboard_enabled=true后会挂载 dashboard APIdashboard_frontend_enabled=true后会同时提供前端入口- 若
admin-web/dist存在，插件会优先提供admin-web构建产物 - 若
dist不存在，插件会回退到仓库内保留的最小前端页面
以下为当前版本的高层命令分类，详细矩阵建议查看 docs/README.md。
群管初始化
禁/解/改/踢/黑管理员+/管理员-头衔/删头衔撤回加精/取消精华
查看词条/词条+/词条-/词条拒绝所有词条/指定词条+/指定词条-分管/分管+/分管-/所有分管/接收请求同意xxx/请求拒绝xxxai拒绝开/ai拒绝关/ai拒绝prompt
关于分管：分管（副管理员）是本插件定义的角色，通过 分管+ 命令由群管指定。分管不是 OneBot 官方管理员，但可以执行以下操作：禁言、解禁、全员禁言、改名、踢人、拉黑、加精、取消精华、撤回。分管不能设置管理员/取消管理员/设置头衔。
词条审核与 AI 审核的区别：
| 对比项 | 词条审核 | AI 审核 |
|---|---|---|
| 触发方式 | 用户验证消息包含词条时自动同意 | AI 判断验证消息是否为广告/人机 |
| 判断逻辑 | 精确字符串匹配（词条在消息中即通过） | AI 语义理解，可识别变体和通用话术 |
| 拒绝能力 | 支持（词条拒绝 设置黑名单，匹配则拒绝） |
支持（AI 判定为广告直接拒绝） |
| 自定义规则 | 每群可设置不同的词条 | 每群可设置不同的自定义 prompt |
| 优先级 | 先执行词条审核，再执行 AI 审核 | 词条审核通过后才进入 AI 审核 |
| 适用场景 | 固定格式验证（如"答案：xxx"） | 开放式验证、防广告机器人 |
两者可以同时启用，互不冲突。词条审核优先处理，未命中词条的请求才会进入 AI 审核。
AI 审核三级判断（设置自定义 prompt 后生效）：
| AI 返回 | 含义 | 处理方式 |
|---|---|---|
| True | 广告/人机 | 直接拒绝 |
| False | 看起来像真人但不符合条件 | 放行给管理员人工处理 |
| Agree | 确定是真人且符合条件 | 机器人直接同意入群，并在群内通知 |
未设置自定义 prompt 时，AI 仅返回 True/False（二级判断，行为不变）。
自定义 prompt 模板：
通过 ai拒绝prompt 设置自定义规则后，AI 可根据规则直接同意符合条件的用户入群。模板示例：
ai拒绝prompt 本群的验证问题为"从哪里知道的本群？"如果用户的回答是一些社交平台，比如b站、bilibili、抖音等，或者包含xxx、xxx关键字时，则判定为直接同意。
说明：你可以强调某些条件让 AI 直接同意入群。注意放行和直接同意是两种不同的处理——放行指放行给管理员处理，直接同意指由机器人直接同意入群。
记录本群/停止记录本群群词云/更新mask今日榜首/今日发言排行/昨日发言排行排行/发言数/今日发言数
广播广播排除群列表排除列表广播帮助
说明：广播现在会先生成预览，只有再次确认后才会真正发送。
事件通知防撤回
成员清理清理解锁
面板地址/获取面板/dashboard地址
说明：仅超级管理员可用，返回 Dashboard 访问地址及 Token 提示。
数据库地址
说明：仅超级管理员可用，返回 ORM 数据库连接地址。未配置 tortoise_orm_db_url 时会提示配置方法。
BalconyJH |
lakwsh |
幼稚园园长 |
A lucky guy |
NekoPunch! |
脑袋里进花生了 |
DeepSource Bot |