# nonebot_plugin_message_counter

**Repository Path**: lexiaoyao9744/nonebot_plugin_message_counter

## Basic Information

- **Project Name**: nonebot_plugin_message_counter
- **Description**: nb2的发言统计插件，改编自koishi的koishi-plugin-message-counter
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: python-plugin
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-16
- **Last Updated**: 2025-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NoneBot2 消息计数器插件

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
[![NoneBot](https://img.shields.io/badge/nonebot-2.0.0+-red.svg)](https://nonebot.dev/)

一个功能丰富的 NoneBot2 消息计数器插件，用于统计群聊发言数据并生成排行榜。

## 功能特性

- 📊 **多维度统计**：支持今日、昨日、本周、本月、今年、总计等多个时间维度的消息统计
- 🏆 **排行榜系统**：自动生成各时间段的发言排行榜，支持群内排行和跨群排行
- ⏰ **定时任务**：支持自动推送排行榜、定时数据重置等功能
- 🐉 **龙王系统**：自动检测发言过多的用户并进行禁言处理
- 🎯 **灵活配置**：丰富的配置选项，支持白名单、黑名单、自定义阈值等
- 💾 **数据持久化**：使用 SQLAlchemy 进行数据存储，支持多种数据库
- 🔍 **查询功能**：支持查询个人发言统计和排名信息

## 安装

### 使用 pip 安装

```bash
pip install nonebot-plugin-message-counter
```

### 使用 Poetry 安装

```bash
poetry add nonebot-plugin-message-counter
```

### 使用 nb-cli 安装

```bash
nb plugin install nonebot-plugin-message-counter
```

## 快速开始

1. 在 NoneBot2 项目的 `pyproject.toml` 文件中添加插件：

```toml
[tool.nonebot]
plugins = ["nonebot_plugin_message_counter"]
```

2. 在 `.env` 文件中添加基本配置：

```env
# 启用消息计数器
MESSAGE_COUNTER_ENABLE=true

# 数据库配置（可选，默认使用 SQLite）
MESSAGE_COUNTER_DATABASE_URL="sqlite:///message_counter.db"

# 启用自动推送排行榜
MESSAGE_COUNTER_AUTO_PUSH_ENABLE=true
MESSAGE_COUNTER_AUTO_PUSH_TIME="20:00"
```

3. 重启 NoneBot2 机器人

## 使用方法

### 基本命令

| 命令 | 别名 | 说明 | 示例 |
|------|------|------|------|
| `查询` | `查看`, `统计` | 查询个人发言统计 | `查询` `查询 @某人` |
| `排行榜` | `排行`, `榜单` | 查看群内排行榜 | `排行榜` `排行榜 10` `排行榜 昨日` |
| `群排行榜` | `群排行`, `群榜单` | 查看跨群排行榜 | `群排行榜` `群排行榜 本周` |
| `消息计数初始化` | - | 清空所有数据（仅超级用户） | `消息计数初始化` |

### 命令参数

#### 时间参数
- `今日` / `today`：今日数据（默认）
- `昨日` / `yesterday`：昨日数据
- `本周` / `week`：本周数据
- `本月` / `month`：本月数据
- `今年` / `year`：今年数据
- `总` / `total`：总计数据

#### 数量参数
- 数字：指定显示的排行榜条数，如 `排行榜 10`（最多50条）

### 使用示例

```
# 查询自己的发言统计
查询

# 查询指定用户的发言统计
查询 @张三

# 查看今日排行榜前10名
排行榜 10

# 查看昨日排行榜
排行榜 昨日

# 查看本周群排行榜
群排行榜 本周
```

## 配置说明

### 基础配置

```env
# 是否启用插件
MESSAGE_COUNTER_ENABLE=true

# 数据库连接URL
MESSAGE_COUNTER_DATABASE_URL="sqlite:///message_counter.db"

# 默认排行榜显示条数
MESSAGE_COUNTER_DEFAULT_LIMIT=10

# 是否显示百分比
MESSAGE_COUNTER_SHOW_PERCENTAGE=true

# 是否显示生成时间
MESSAGE_COUNTER_SHOW_TIME=true
```

### 自动推送配置

```env
# 启用自动推送排行榜
MESSAGE_COUNTER_AUTO_PUSH_ENABLE=true

# 推送时间（24小时制）
MESSAGE_COUNTER_AUTO_PUSH_TIME="20:00"

# 推送排行榜条数
MESSAGE_COUNTER_AUTO_PUSH_LIMIT=10

# 指定推送的群组（留空则推送所有群）
MESSAGE_COUNTER_AUTO_PUSH_GROUPS=["123456789", "987654321"]
```

### 龙王系统配置

```env
# 启用龙王系统
MESSAGE_COUNTER_DRAGON_KING_ENABLE=true

# 龙王触发阈值（每日发言条数）
MESSAGE_COUNTER_DRAGON_KING_THRESHOLD=100

# 龙王禁言时长（秒）
MESSAGE_COUNTER_DRAGON_KING_DURATION=3600

# 龙王检查时间
MESSAGE_COUNTER_DRAGON_KING_CHECK_TIME="21:00"

# 启用龙王系统的群组
MESSAGE_COUNTER_DRAGON_KING_GROUPS=["123456789"]
```

### 过滤配置

```env
# 群组白名单（仅统计这些群）
MESSAGE_COUNTER_GROUP_WHITELIST=["123456789", "987654321"]

# 群组黑名单（不统计这些群）
MESSAGE_COUNTER_GROUP_BLACKLIST=["111111111"]

# 用户黑名单（不统计这些用户）
MESSAGE_COUNTER_USER_BLACKLIST=["222222222"]
```

### 数据清理配置

```env
# 启用数据清理
MESSAGE_COUNTER_CLEANUP_ENABLE=true

# 数据保留天数
MESSAGE_COUNTER_CLEANUP_DAYS=30
```

## 数据库支持

插件支持多种数据库，通过修改 `MESSAGE_COUNTER_DATABASE_URL` 配置：

```env
# SQLite（默认）
MESSAGE_COUNTER_DATABASE_URL="sqlite:///message_counter.db"

# MySQL
MESSAGE_COUNTER_DATABASE_URL="mysql+aiomysql://user:password@localhost/dbname"

# PostgreSQL
MESSAGE_COUNTER_DATABASE_URL="postgresql+asyncpg://user:password@localhost/dbname"
```

## 定时任务

插件内置了多个定时任务：

- **每日重置**：每天 00:00 重置今日数据，将今日数据转移到昨日
- **每周重置**：每周一 00:05 重置本周数据
- **每月重置**：每月1日 00:10 重置本月数据
- **每年重置**：每年1月1日 00:15 重置今年数据
- **自动推送**：根据配置时间自动推送排行榜
- **龙王检查**：根据配置时间检查并处理龙王
- **数据清理**：每天 02:00 清理过期数据

## 权限说明

- **普通用户**：可以使用查询、排行榜等命令
- **超级用户**：可以使用所有命令，包括初始化命令

## 注意事项

1. 首次使用时，插件会自动创建数据库表
2. 数据统计从插件启用后开始，不会统计历史消息
3. 龙王系统需要机器人具有群管理员权限
4. 自动推送功能需要机器人能够主动发送消息
5. 建议定期备份数据库文件

## 故障排除

### 常见问题

**Q: 插件无法正常统计消息？**
A: 检查配置文件中的 `MESSAGE_COUNTER_ENABLE` 是否为 `true`，以及群组是否在黑名单中。

**Q: 自动推送不工作？**
A: 确认 `MESSAGE_COUNTER_AUTO_PUSH_ENABLE` 已启用，时间格式正确，且机器人有发送消息的权限。

**Q: 龙王禁言失败？**
A: 确保机器人在群内具有管理员权限，且目标用户不是群主或其他管理员。

**Q: 数据库连接失败？**
A: 检查数据库URL格式是否正确，数据库服务是否正常运行。

## 许可证

本项目采用 MIT 许可证。

## 更新日志

### v1.0.0
- 初始版本发布
- 支持多维度消息统计
- 实现排行榜功能
- 添加定时任务支持
- 实现龙王系统
- 支持多种数据库

---

**⭐ 如果这个项目对你有帮助，请给它一个星标！**