The Betterest Mute Cat 是一个功能完善的 QQ 群禁言插件，支持多种禁言方式，带有可爱的猫娘语气回复，附有持久化存储和定时任务功能。
- 🔇 禁言成员 — 支持同时禁言多人，可自定义时长（分钟 / 小时 / 秒）
- 🔊 取消禁言 — 解除单个或多个成员的禁言
- 🔕 全员禁言 — 支持永久模式和定时自动解除模式
- 📢 解禁全员 — 一键解除全员禁言 + 所有个人禁言 + 清除定时任务
- 🎲 禁我功能 — 随机禁言自己，给自己整点小刺激
- ⏰ 定时禁言 — 指定时间点开始禁言，支持多种时间格式
- 📌 @ 开关 — 每个群独立设置是否需要 @ 机器人才能触发命令
- 📊 状态查看 — 实时查看谁被禁言中、剩余时间、待执行的定时任务
- 💾 持久化存储 — 基于 nonebot-plugin-localstore，重启后保留禁言记录和设置
nb plugin install nonebot-plugin-mute-catpip install nonebot-plugin-mute-cat安装完成后，在 pyproject.toml 或 bot.py 中加载插件：
# pyproject.toml
[tool.nonebot]
plugins = ["nonebot_plugin_mute_cat"]或
# bot.py
nonebot.load_plugin("nonebot_plugin_mute_cat")在项目根目录的 .env 或 .env.prod 文件中添加以下配置（全部可选，均有默认值）：
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
MUTE_DEFAULT_MINUTES |
int |
5 |
未指定时长时的默认禁言分钟数 |
MUTE_SELF_OPTIONS |
list[int] |
[1, 3, 5, 0] |
「禁我」功能的随机时长候选（分钟），0 表示本次不禁言 |
MUTE_AT_REQUIRED |
bool |
true |
全局默认：是否需要 @ 机器人才能触发命令（可被群级别 @ 开关覆盖） |
MUTE_SUPERUSER_ONLY |
bool |
false |
为 true 时只有超级管理员可用管理命令，群管理员无权限 |
# .env.prod
MUTE_DEFAULT_MINUTES=10
MUTE_SELF_OPTIONS=[1, 2, 3, 5, 10, 0]
MUTE_AT_REQUIRED=true
MUTE_SUPERUSER_ONLY=false| 命令 | 需要权限 |
|---|---|
| 禁言 / 取消禁言 / 全员禁言 / 解禁全员 | 群管理员 或 超级管理员 |
| @ 开关（开启 / 关闭 at 模式） | 群管理员 或 超级管理员，且必须 @ 机器人 |
| 禁我 | 任何人 |
| 帮助 / 查看状态 | 任何人 |
⚠️ 机器人自身必须是群管理员才能执行禁言和解禁操作。
⚠️ 无法禁言群主和其他管理员（QQ 协议限制）。
以下示例默认已开启
MUTE_AT_REQUIRED=true（默认值），命令前需要 @ 机器人。
如已关闭该配置或该群设置了「关闭 at」，则直接发送命令文字即可。
语法： 禁言 @目标 [时长]
时长支持以下所有格式，不填则使用 MUTE_DEFAULT_MINUTES 配置值：
| 输入示例 | 含义 |
|---|---|
禁言 @猫猫 |
禁言默认时长（默认 5 分钟） |
禁言 @猫猫 10 |
禁言 10 分钟 |
禁言 @猫猫 10分钟 |
禁言 10 分钟 |
禁言 @猫猫 1小时 |
禁言 1 小时 |
禁言 @猫猫 90s |
禁言 90 秒（自动换算取整为分钟） |
禁言 @猫猫 2h |
禁言 2 小时 |
禁言 @甲 @乙 @丙 5分钟 |
同时禁言多人 |
语法： 取消/解除/解禁 @目标 [@目标2 ...]
三个关键词效果完全相同：
取消 @猫猫
解除 @猫猫 @狗狗
解禁 @猫猫
语法： 全员禁言 [时长]
| 输入示例 | 含义 |
|---|---|
全员禁言 |
开启永久全员禁言（直到手动解除） |
全员禁言 30分钟 |
全员禁言 30 分钟后自动解除 |
全员禁言 2小时 |
全员禁言 2 小时后自动解除 |
全体禁言 1h |
同上，全体 和 全员 效果一致 |
以下命令任选其一，效果完全相同：
解禁全员 取消全员 解除全员
解禁全体 取消全体 解除全体
全员解禁 全体解禁
关闭全员禁言 解除全员禁言
💡 该命令会同时：关闭全员禁言、解除所有个人禁言、取消所有待执行的定时禁言任务。
语法： 禁我
随机从 MUTE_SELF_OPTIONS 配置的时长选项中抽取一个执行：
- 默认选项为
[1, 3, 5, 0]，四档各 25% 概率，抽到0本次不禁言 - 任何人均可使用，无需管理员权限
- 管理员因 QQ 协议限制无法被禁言，会收到提示
在禁言命令后加上时间参数即可创建定时任务，时间格式支持：
| 输入示例 | 含义 |
|---|---|
禁言 @猫猫 14:30 15:30 |
14:30 开始禁言，15:30 结束（持续 1 小时） |
禁言 @猫猫 14:30~15:30 |
同上，波浪线写法 |
禁言 @猫猫 14:30 1小时 |
14:30 开始，禁言 1 小时 |
禁言 @猫猫 14:30 30分钟 |
14:30 开始，禁言 30 分钟 |
禁言 @猫猫 14:30 |
14:30 开始，使用默认时长 |
⚠️ 所有定时任务使用北京时间（Asia/Shanghai）。
⚠️ 指定时间已过今天时，任务自动安排到明天同一时间。
⚠️ 机器人重启后定时任务会丢失，已存储的禁言状态记录不受影响。
语法： 查看状态
显示当前群的：
- @ 触发模式（需要 @ / 不需要 @）
- 全员禁言状态及剩余时间
- 正在被禁言的成员列表及各自剩余时间
- 待执行的定时任务列表
前提：必须 @ 机器人，且操作者为管理员。
@机器人 开启at → 该群开启「需要 @ 才能触发命令」模式
@机器人 关闭at → 该群关闭，直接发命令即可触发
💡 @ 开关是每个群独立设置的，优先级高于全局
MUTE_AT_REQUIRED配置。
语法： 帮助 或 help 或 菜单
机器人回复当前群触发模式说明和命令速查表。
插件使用 nonebot-plugin-localstore 管理持久化数据，文件位于 localstore 管理的插件专属目录：
<data_dir>/nonebot_plugin_mute_cat/
├── at_overrides.json # 各群的 @ 开关设置
└── group_states.json # 各群的禁言状态和任务记录
- 仅支持 OneBot V11 适配器（如 LLOneBot、Lagrange、NapCat 等）
- 机器人需要拥有群管理员权限才能执行禁言 / 解禁
- 无法禁言群主和其他管理员（QQ 协议限制，非 bug）
- 机器人重启后定时任务会丢失，重启后孤儿任务记录会在启动时自动清理
- QQ 单次禁言最长 30 天（43200 分钟）
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| nonebot2 | 2.2.0 | 核心框架，提供 nonebot.compat 兼容层 |
| nonebot-adapter-onebot | 2.4.0 | OneBot V11 适配器 |
| nonebot-plugin-apscheduler | 0.4.0 | 定时任务支持 |
| nonebot-plugin-localstore | 0.6.0 | 本地持久化存储 |
本插件同时兼容 pydantic v1 和 pydantic v2，通过 nonebot.compat.ConfigDict 实现
Q: 机器人没有反应？
A: 检查是否满足触发条件。默认需要 @ 机器人，发送 帮助 查看当前群的触发模式。
Q: 禁言失败提示权限不够？
A: 需要先在 QQ 群中给机器人赋予管理员权限。
Q: 能禁言群主 / 管理员吗？
A: 不能，这是 QQ 协议的限制。
Q: 重启后定时禁言任务消失了？
A: APScheduler 的任务不做持久化，重启后会丢失。这是已知限制，重启时孤儿任务记录会自动清理。如有强需求可考虑接入持久化 job store（如 SQLAlchemy）。
Q: 数据文件在哪里？
A: 由 nonebot-plugin-localstore 管理，路径因系统和项目配置而异，可通过 store.get_plugin_data_file(...) 确认实际路径。
本项目使用 MIT 协议开源，欢迎自由使用和二次开发。
感谢所有使用和支持本插件的小伙伴们，感谢 NoneBot2 社区提供的优秀框架和生态~