nonebot-plugin-mute-cat 1.3.0

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

极致的禁言猫猫（The Betterest Mute Cat）

nonebot-plugin-mute-cat

一个面向 QQ 群管理场景的 NoneBot2 禁言插件，支持自然语言识别、定时禁言、每日禁言、长期禁言续期、状态查看与群级 @ 触发控制。

简介

nonebot-plugin-mute-cat 是一个面向 OneBot V11 的群禁言插件。

它的设计目标不是堆砌固定命令，而是尽量以清晰、稳定的方式理解常见自然语言表达，同时避免误伤普通聊天。对于容易产生歧义的说法，插件会明确拒绝执行，而不是猜测用户意图。

当前版本支持：

• 个人禁言与全员禁言
• 按时长禁言、按结束时间禁言、定时开始禁言
• 每日重复禁言
• 超过 30 天的长期禁言自动续期
• 当前禁言、未来任务、全部状态三种取消语义
• 状态摘要、详细列表与分页查看
• 定时任务、每日任务、长期计划持久化，重启后自动恢复
• 每个群单独控制是否必须先 @ 机器人

适用环境

项目	要求
Python	3.9+
NoneBot2	2.2.0+
适配器	nonebot-adapter-onebot
协议	OneBot V11

安装

使用 nb-cli

nb plugin install nonebot-plugin-mute-cat

使用 pip

pip install nonebot-plugin-mute-cat

安装完成后，在 pyproject.toml 中加载插件。

[tool.nonebot]
plugins = ["nonebot_plugin_mute_cat"]

配置项

以下配置项均为可选项，可写入项目根目录的 .env、.env.prod 等环境配置文件。

配置项	类型	默认值	说明
MUTE_DEFAULT_MINUTES	int	5	未显式指定时长时使用的默认禁言时长，单位为分钟
MUTE_COMMAND_PRIORITY	int	5	插件事件响应器优先级，数值越小优先级越高
MUTE_SELF_OPTIONS	list[int]	[1, 3, 5, 0]	禁我 的随机时长候选，单位为分钟，0 表示本次不禁言
MUTE_AT_REQUIRED	bool	true	全局默认是否要求先 @ 机器人才能触发命令
MUTE_SUPERUSER_ONLY	bool	false	是否仅允许超级用户执行管理命令

示例：

MUTE_DEFAULT_MINUTES=10
MUTE_COMMAND_PRIORITY=5
MUTE_SELF_OPTIONS=[1, 2, 3, 5, 10, 0]
MUTE_AT_REQUIRED=true
MUTE_SUPERUSER_ONLY=false

权限要求

功能	权限要求
禁言、取消禁言、全员禁言、取消全员禁言、@ 开关	群管理员或超级用户
帮助、使用细则、查看状态、展开状态、禁我	所有人

补充说明：

• 机器人自身必须拥有群管理员权限，否则无法执行禁言和解除禁言。
• 群主与其他管理员无法被禁言，这是平台限制。
• @ 开关命令必须先 @ 机器人后再发送。

快速开始

推荐直接使用自然语言表达需求。插件已经内置较完整的命令识别规则，大多数常见写法都可以直接理解。

常见示例：

禁言 @某人 10分钟
今晚八点禁言 @某人 到明早八点半
5分钟后禁言 @某人 到9点
每天10点禁言 @某人 10分钟
全员禁言 30分钟
取消定时禁言 @某人
查看状态

插件内还提供两个使用说明入口：

• 帮助 返回简要说明与常见示例。
• 使用细则 返回完整使用规则、时间写法与状态查看方式。

功能说明

1. 个人禁言

支持即时禁言、定时禁言、按结束时间禁言。

示例：

禁言 @某人
禁言 @某人 10分钟
给 @某人 禁言 2小时
把 @某人 禁言到明早八点
今晚八点禁言 @某人 到明早八点半
下周一上午九点禁言 @某人 2天
5分钟后禁言 @某人
2小时后禁言 @某人 30分钟
5分钟后禁言 @某人 到9点

说明：

• 未写时长时，使用 MUTE_DEFAULT_MINUTES。
• 支持同时 @ 多个成员。
• 如果只写结束时间，则默认立即开始，持续到该结束时间。
• 如果只写开始时间，则在对应时间开始，持续默认时长。

2. 全员禁言

示例：

全员禁言
全员禁言 30分钟
全体禁言 2小时
始终禁言 10分钟
禁言 @全体成员 3天
今晚八点全员禁言到明早八点半

说明：

• @全体成员 会按全员禁言处理。
• 有时长时，按时长自动解除。
• 未写时长时，保持到手动解除。
• 始终禁言 会被视为全员禁言关键词，不按普通自然语言歧义处理。

3. 每日禁言

每日禁言用于固定时间重复执行禁言任务。

示例：

每天10点禁言 @某人
每天10点禁言 @某人 10分钟
每天10点禁言 @某人到11点
每天禁言 @某人 1点
每天禁言 @某人 1点到3点
禁言 @某人 每天10点
每天10点全员禁言
每天下午8点全员禁言 30分钟

说明：

• 每天 与 每日 都会识别为每日任务。
• 每日任务支持写时长，也支持写结束时刻。
• 每天10点禁言 @某人 10分钟 会被识别为每天 10:00 开始，持续 10 分钟。
• 每天10点禁言 @某人到11点 会被识别为每天 10:00 开始，到 11:00 结束。
• 禁言 @某人 每天10点 与 每天10点禁言 @某人 语义相同。
• 每日个人禁言未写时长时，使用 MUTE_DEFAULT_MINUTES。
• 每日全员禁言未写时长时，也使用 MUTE_DEFAULT_MINUTES，避免形成无法自动收束的永久循环任务。

4. 超过 30 天的长期禁言

QQ 单次禁言最长为 30 天。

当用户设置的个人禁言超过 30 天时，插件会自动拆分为多段执行，并在续期时先解除已有禁言，再续上下一段，直到最终结束时间为止。用户不需要手动干预。

5. 取消禁言

插件明确区分三种取消语义。

只取消当前禁言

取消 @某人
解除 @某人
解禁 @某人
取消 @某人的禁言
解禁全员

说明：

• 只处理当前已经生效的禁言。
• 如果未来还有定时任务、每日任务或长期续期计划，回复中会明确说明这些任务仍然保留。

只取消未来任务

取消定时禁言 @某人
取消 @某人的定时任务
取消 @某人的未来禁言
取消全员的定时任务
解除所有人的定时禁言
解除全体的定时禁言

说明：

• 只清理未来计划，不影响当前已经生效的禁言。
• 一次性定时任务、每日任务、长期续期任务都属于未来计划的一部分。
• 解除所有人的定时禁言、解除全体的定时禁言 会按“所有成员的个人未来任务”处理，不会解除当前全员禁言。

同时取消当前和未来

取消所有禁言 @某人
取消 @某人的所有禁言状态
取消全员的所有禁言状态
解除所有人的所有禁言

说明：

• 会同时处理当前禁言和未来计划。
• 回复会分别说明当前部分与未来部分的处理结果。

批量处理所有成员的个人禁言

解除所有人的禁言
解除所有人的定时禁言
解除所有人的所有禁言
解除全体的定时禁言
解除全体定时禁言

说明：

• 这类写法处理的是“所有群成员的个人禁言状态”。
• 不会被当成“解除全员禁言”。
• 解除所有人 这类不带“的禁言/的定时禁言/的所有禁言”的说法，仍然按全员禁言相关命令处理。

6. 状态查看

示例：

查看状态
展开当前禁言
展开定时任务
展开每日任务
展开长期禁言
展开全部状态
展开当前禁言第2页
展开定时任务第3页
展开每日任务第2页

说明：

• 查看状态 返回摘要信息。
• 摘要中每个分类默认展示 5 条。
• 展开... 用于查看详细列表，并支持分页。
• 状态页会分别展示：
  • 当前禁言
  • 一次性定时任务
  • 每日任务
  • 长期禁言计划

7. @ 触发开关

可按群单独控制是否必须先 @ 机器人才能触发命令。

示例：

@机器人 开启at
@机器人 打开@
@机器人 关闭at
@机器人 停用@

说明：

• 开启后，未先 @ 机器人的命令会被静默忽略。
• 关闭后，即使消息中先 @ 机器人，也仍可正常执行。
• 群级设置优先于全局配置 MUTE_AT_REQUIRED。

8. 禁我

示例：

禁我
把我禁言
给我禁言

说明：

• 触发后会从 MUTE_SELF_OPTIONS 中随机抽取一个时长。
• 抽到 0 时，本次不会执行禁言。

时间与识别规则

目标指定

• 个人禁言必须通过 @成员 指定目标。
• 不支持直接使用纯 QQ 号。
• 同时 @全体成员 和普通成员时，会视为歧义并拒绝执行。

支持的时长单位

支持以下写法：

• 秒：秒、秒钟、s、sec、second、seconds
• 分钟：分、分钟、m、min、minute、minutes
• 小时：时、小时、h、hour、hours
• 天：天、d、day、days
• 月：月、个月、mon、month、months

额外规则：

• m 始终表示分钟，不表示月。
• 月按 30 天计算。
• 月份时长最多支持 12 个月。
• 支持常见中文数字，例如 十分钟、两小时。

支持的时间表达

支持以下常见写法：

• 14:30
• 8点
• 20点
• 晚上8点
• 今晚八点
• 明早八点半
• 下周一上午九点
• 今晚八点到明早八点半
• 到明早八点
• 5分钟后禁言 @某人
• 2小时后禁言 @某人 到明早八点

规则说明：

• 默认使用北京时间 Asia/Shanghai。
• 不带 上午、下午、晚上 这类前缀时，按 24 小时制理解。
• 8点 表示 08:00，20点 表示 20:00。
• 带时间段前缀时，按常见口语习惯理解。
• 晚上8点 表示 20:00，上午9点 表示 09:00。

识别边界

为了避免误判，插件会主动拒绝以下情况：

• 问句，例如 要不要禁言 @某人
• 容易误伤普通聊天的口语，例如 闭嘴、闭麦
• 目标不明确的命令
• 表达歧义较大的组合写法

任务合并与执行策略

一次性定时任务

同一成员允许存在多条不冲突的一次性定时任务。

如果多个任务时间区间发生重叠，插件会自动合并为一条更大的区间，避免互相覆盖或缩短禁言时间。

每日任务

同一目标允许存在多条不冲突的每日任务。

如果每日任务时间区间冲突，插件会自动合并，保留合并后的时间范围。

与当前禁言冲突

如果未来任务与当前已生效禁言发生冲突，插件会优先合并到当前禁言结果，而不是额外创建一条会导致时间缩短或状态混乱的新任务。

持久化与恢复

插件使用 nonebot-plugin-localstore 保存运行状态。

默认会在插件数据目录生成以下文件：

<data_dir>/nonebot_plugin_mute_cat/
├── at_overrides.json
└── group_states.json

其中：

• at_overrides.json 保存各群的 @ 开关覆盖配置
• group_states.json 保存当前禁言、一次性任务、每日任务与长期计划

恢复规则：

• 重启后会自动恢复未来任务、每日任务、长期计划和群级 @ 开关。
• 如果任务开始时间已过，但本轮结束时间还未过，插件会补执行到原本结束时间。
• 如果任务对应的结束时间已经过去，会在启动时静默清理。

常见问题

机器人没有反应

请依次检查以下项目：

• 当前群是否要求先 @ 机器人
• 消息是否是问句或普通聊天
• 是否正确使用了 @目标成员
• 机器人是否拥有群管理员权限

为什么 取消 @某人 之后，对方后面又被禁言了

因为 取消 @某人 只取消当前禁言，不会删除未来任务。

如果你要删除未来计划，请使用：

取消定时禁言 @某人

如果你要同时清掉当前和未来，请使用：

取消所有禁言 @某人

重启之后任务还在吗

在。

插件会持久化保存一次性定时任务、每日任务、长期禁言计划和群级 @ 设置，重启后自动恢复。

为什么不能禁言管理员

这是 QQ 平台权限限制。机器人无法禁言群主与其他管理员。

依赖

依赖	最低版本	说明
nonebot2	2.2.0	核心框架
nonebot-adapter-onebot	2.4.0	OneBot V11 适配器
nonebot-plugin-apscheduler	0.4.0	定时任务调度
nonebot-plugin-localstore	0.6.0	本地持久化存储
pydantic	1.10	配置模型与环境变量解析

开源协议

本项目基于 MIT 协议开源。