nonebot-plugin-mute-cat 1.2.2
The Betterest Mute Cat — 极致的禁言猫猫，功能强大的QQ群禁言插件
License: MIT
Requires Python: <4.0,>=3.9
Keywords: nonebot, nonebot2, qq, mute, ban, 禁言

# nonebot-plugin-mute-cat

<div align="center">

# 🐱 The Betterest Mute Cat

✨ 功能强大的 QQ 群禁言插件，带有可爱的猫娘语气 ✨

[![license](https://img.shields.io/github/license/binglang001/nonebot-plugin-mute-cat.svg)](LICENSE)
[![pypi](https://img.shields.io/pypi/v/nonebot-plugin-mute-cat.svg)](https://pypi.python.org/pypi/nonebot-plugin-mute-cat)
[![python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org)
[![NoneBot](https://img.shields.io/badge/nonebot-2.2.0+-red.svg)](https://nonebot.dev)

</div>

---

## 📖 介绍

**The Betterest Mute Cat** 是一个功能完善的 QQ 群禁言插件，支持多种禁言方式，带有可爱的猫娘语气回复，附有持久化存储和定时任务功能。

### ✨ 特性

- 🔇 **禁言成员** — 支持同时禁言多人，可自定义时长（分钟 / 小时 / 秒）
- 🔊 **取消禁言** — 解除单个或多个成员的禁言
- 🔕 **全员禁言** — 支持永久模式和定时自动解除模式
- 📢 **解禁全员** — 一键解除全员禁言 + 所有个人禁言 + 清除定时任务
- 🎲 **禁我功能** — 随机禁言自己，给自己整点小刺激
- ⏰ **定时禁言** — 指定时间点开始禁言，支持多种时间格式
- 📌 **@ 开关** — 每个群独立设置是否需要 @ 机器人才能触发命令
- 📊 **状态查看** — 实时查看谁被禁言中、剩余时间、待执行的定时任务
- 💾 **持久化存储** — 基于 nonebot-plugin-localstore，重启后保留禁言记录和设置

---

## 📦 安装

### 方式一：nb-cli（推荐）

```bash
nb plugin install nonebot-plugin-mute-cat
```

### 方式二：pip

```bash
pip install nonebot-plugin-mute-cat
```

安装完成后，在 `pyproject.toml` 或 `bot.py` 中加载插件：

```toml
# pyproject.toml
[tool.nonebot]
plugins = ["nonebot_plugin_mute_cat"]
```

或

```python
# 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` 时只有超级管理员可用管理命令，群管理员无权限 |

### 配置示例

```dotenv
# .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](LICENSE) 协议开源，欢迎自由使用和二次开发。

---

## 💖 致谢

感谢所有使用和支持本插件的小伙伴们，感谢 NoneBot2 社区提供的优秀框架和生态~