Metadata-Version: 2.4
Name: nonebot-plugin-mute-cat
Version: 1.3.0
Summary: The Betterest Mute Cat — 极致的禁言猫猫，功能强大的QQ群禁言插件
Author-email: binglang <lianbingyu_v2@163.com>
License-Expression: MIT
Project-URL: homepage, https://github.com/binglang001/nonebot-plugin-mute-cat
Project-URL: repository, https://github.com/binglang001/nonebot-plugin-mute-cat
Project-URL: documentation, https://github.com/binglang001/nonebot-plugin-mute-cat#readme
Keywords: nonebot,nonebot2,qq,mute,ban,禁言
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nonebot2>=2.2.0
Requires-Dist: nonebot-adapter-onebot>=2.4.0
Requires-Dist: nonebot-plugin-apscheduler>=0.4.0
Requires-Dist: nonebot-plugin-localstore>=0.6.0
Requires-Dist: pydantic<3.0,>=1.10
Dynamic: license-file

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

<div align="center">

<code>nonebot-plugin-mute-cat</code>

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

[![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>

## 简介

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

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

当前版本支持：

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

## 适用环境

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

## 安装

### 使用 `nb-cli`

```bash
nb plugin install nonebot-plugin-mute-cat
```

### 使用 `pip`

```bash
pip install nonebot-plugin-mute-cat
```

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

```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` | 是否仅允许超级用户执行管理命令 |

示例：

```dotenv
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
```

## 权限要求

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

补充说明：

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

## 快速开始

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

常见示例：

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

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

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

## 功能说明

### 1. 个人禁言

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

示例：

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

说明：

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

### 2. 全员禁言

示例：

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

说明：

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

### 3. 每日禁言

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

示例：

```text
每天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. 取消禁言

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

#### 只取消当前禁言

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

说明：

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

#### 只取消未来任务

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

说明：

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

#### 同时取消当前和未来

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

说明：

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

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

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

说明：

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

### 6. 状态查看

示例：

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

说明：

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

### 7. `@` 触发开关

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

示例：

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

说明：

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

### 8. 禁我

示例：

```text
禁我
把我禁言
给我禁言
```

说明：

- 触发后会从 `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` 保存运行状态。

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

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

其中：

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

恢复规则：

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

## 常见问题

### 机器人没有反应

请依次检查以下项目：

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

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

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

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

```text
取消定时禁言 @某人
```

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

```text
取消所有禁言 @某人
```

### 重启之后任务还在吗

在。

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

### 为什么不能禁言管理员

这是 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](LICENSE) 协议开源。
