nonebot-plugin-mute-cat 1.2.3

The Betterest Mute Cat — 极致的禁言猫猫，功能强大的QQ群禁言插件

nonebot-plugin-mute-cat

🐱 The Betterest Mute Cat

✨ 功能强大的 QQ 群禁言插件，带有可爱的猫娘语气 ✨

---

📖 介绍

The Betterest Mute Cat 是一个功能完善的 QQ 群禁言插件，支持多种禁言方式，带有可爱的猫娘语气回复，附有持久化存储和定时任务功能。

✨ 特性

• 🔇 禁言成员 — 支持同时禁言多人，可自定义时长（分钟 / 小时 / 秒）
• 🔊 取消禁言 — 解除单个或多个成员的禁言
• 🔕 全员禁言 — 支持永久模式和定时自动解除模式
• 📢 解禁全员 — 一键解除全员禁言 + 所有个人禁言 + 清除定时任务
• 🎲 禁我功能 — 随机禁言自己，给自己整点小刺激
• ⏰ 定时禁言 — 指定时间点开始禁言，支持多种时间格式
• 📌 @ 开关 — 每个群独立设置是否需要 @ 机器人才能触发命令
• 📊 状态查看 — 实时查看谁被禁言中、剩余时间、待执行的定时任务
• 💾 持久化存储 — 基于 nonebot-plugin-localstore，重启后保留禁言记录和设置

---

📦 安装

方式一：nb-cli（推荐）

nb plugin install nonebot-plugin-mute-cat

方式二：pip

pip 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 社区提供的优秀框架和生态~