Metadata-Version: 2.5
Name: nonebot-plugin-msg-rank-card
Version: 0.1.12
Summary: 每日水群排行榜图片生成插件，记录群聊消息并生成精美排行榜
Project-URL: Homepage, https://github.com/TonyLiangP2010405/nonebot-plugin-msg-rank-card
Project-URL: Repository, https://github.com/TonyLiangP2010405/nonebot-plugin-msg-rank-card
Author-email: TonyLiangP2010405 <plia0974@uni.sydney.edu.au>
License: MIT
License-File: LICENSE
Keywords: card,message,nonebot,nonebot2,plugin,rank
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: nonebot-adapter-onebot>=2.4.0
Requires-Dist: nonebot-plugin-apscheduler>=0.5.0
Requires-Dist: nonebot2>=2.2.0
Requires-Dist: pillow>=10.0.0
Provides-Extra: dev
Requires-Dist: nonebug>=0.3; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <a href="https://v2.nonebot.dev/store"><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/nbp_logo.png" width="180" height="180" alt="NoneBotPluginLogo"></a>
  <br>
  <p><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/NoneBotPlugin.svg" width="240" alt="NoneBotPluginText"></p>
</div>

<div align="center">

# nonebot-plugin-msg-rank-card

_✨ 每日水群排行榜图片生成插件 ✨_

<a href="./LICENSE">
    <img src="https://img.shields.io/github/license/TonyLiangP2010405/nonebot-plugin-msg-rank-card.svg" alt="license">
</a>
<a href="https://pypi.python.org/pypi/nonebot-plugin-msg-rank-card">
    <img src="https://img.shields.io/pypi/v/nonebot-plugin-msg-rank-card.svg" alt="pypi">
</a>
<img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="python">

</div>

## 📖 介绍

本插件基于 [MsgRankCard](https://github.com/TonyLiangP2010405/MsgRankCard) 项目改写，是一个 NoneBot2 插件，用于记录群聊消息并生成精美的每日水群排行榜图片。

功能特点：
- 📝 自动记录群聊消息数量和在线时长
- 🎨 生成精美的排行榜图片，支持自定义背景、边框和字体
- 🥇 自动使用排行榜第一名的 QQ 头像作为背景
- 🕐 排行榜图片显示当前北京时间，发图前会播报日报/周报/月报类型；周报/月报还会显示统计起止日期
- ⏳ 在线时长超过 24 小时时按「X天X时X分」显示
- 🔔 发送周报/月报时会 @上榜成员（日报不 @）
- 🖼️ 自动获取用户 QQ 头像
- 🏆 支持查看今日、本周和本月水群排行榜
- 🔔 支持 Superuser 开启排名变动提醒，名次变化后自动重发榜单
- ⏰ 支持按小时定时发送日榜，以及每天定时发送周榜和月榜
- 🎲 已安装馒头好感度插件时，水群榜上的群友发言有 0.5% 概率触发「馒头博弈」
- 🧹 支持自动清理过期数据，默认保留35天

## 💿 安装

### 使用 nb-cli 安装

在 nonebot2 项目的根目录下打开命令行，输入以下指令即可安装

```bash
nb plugin install nonebot-plugin-msg-rank-card
```

### 使用包管理器安装

在 nonebot2 项目的插件目录下，打开命令行，根据你使用的包管理器，输入相应的安装命令

<details>
<summary>pip</summary>

```bash
pip install nonebot-plugin-msg-rank-card
```
</details>

<details>
<summary>poetry</summary>

```bash
poetry add nonebot-plugin-msg-rank-card
```
</details>

打开 nonebot2 项目根目录下的 `pyproject.toml` 文件，在 `[tool.nonebot]` 部分追加写入

```toml
plugins = ["nonebot_plugin_msg_rank_card"]
```

## ⚙️ 配置

在 nonebot2 项目的 `.env` 文件中添加下表中的配置

| 配置项 | 必填 | 默认值 | 说明 |
|:-----:|:----:|:----:|:----:|
| msg_rank_data_path | 否 | data/msg_rank | 数据存储路径 |
| msg_rank_resource_path | 否 | 插件目录/resources | 资源文件路径（背景图、边框、字体） |
| msg_rank_max_count | 否 | 10 | 排行榜最大显示人数 |
| msg_rank_auto_clean | 否 | true | 是否每天自动清理过期数据 |
| msg_rank_data_retention_days | 否 | 35 | 每日统计数据保留天数（最低31天） |
| msg_rank_bet_recent_minutes | 否 | 5 | 馒头博弈只从最近多少分钟内发过言的群友中选人（1~120） |
| msg_rank_title | 否 | 今日水群排行榜 | 排行榜标题 |

## 🎉 使用

### 指令表

| 指令 | 权限 | 需要@ | 范围 | 说明 |
|:-----:|:----:|:----:|:----:|:----:|
| 水群榜 / msgrank | 群员 | 否 | 群聊 | 查看今日水群排行榜 |
| 周水群榜 / 周榜 | 群员 | 否 | 群聊 | 查看本周一至今日的汇总排行榜 |
| 月水群榜 / 月榜 | 群员 | 否 | 群聊 | 查看本月1日至今日的汇总排行榜 |
| 排名变动提醒 开启\|关闭\|状态 | Superuser | 否 | 群聊 | 管理本群排名变动提醒 |
| 日榜定时 1-168\|关闭\|状态 | Superuser | 否 | 群聊 | 按指定小时间隔自动发送今日榜 |
| 周榜定时 HH:MM\|关闭\|状态 | Superuser | 否 | 群聊 | 每天指定时间自动发送本周榜 |
| 月榜定时 HH:MM\|关闭\|状态 | Superuser | 否 | 群聊 | 每天指定时间自动发送本月榜 |
| 清理水群数据 / clean_msgrank | 群主/管理员 | 否 | 群聊 | 清理过期数据 |

排名变动提醒默认关闭，开关按群保存。开启后，只有榜单成员或名次顺序发生变化时才会提醒；消息数增加但名次不变时不会重复发送。

定时任务默认关闭，按群保存，机器人重启后会自动恢复。`HH:MM` 使用 NoneBot APScheduler 配置的时区（默认 `Asia/Shanghai`）。

### 效果图

插件会自动记录群聊消息，发送 `/水群榜` 即可生成精美排行榜图片。

### 馒头好感度联动（可选）

同时加载 `nonebot-plugin-mantou-affection` 后，日榜、周榜、月榜和定时榜单都会在每位成员旁显示
“馒头好感 + 当前关系称号 + 一句随好感阶段变化的馒头短评”。好感数据按群读取；
未加载好感度插件、好感度读取失败或该阶段没有文案时卡片保持原样，只是不显示短评。
短评取自好感度插件的 `msg_rank_card.rank` 场景（按 neutral/warm/close/flirty/intimate 五个阶段），
文案过长时会自动截断，不会盖住排名图案。

**当日水群榜**上的群友发送普通群消息时，馒头插件还有 0.5% 的概率触发「馒头博弈」：馒头会从
**最近几分钟内发过言的群友**中随机抽取 2 位开局（排除触发者，候选人不要求在榜上；默认 5 分钟，
可用 `msg_rank_bet_recent_minutes` 调整，范围 1~120），好感度筛选由馒头插件负责。触发者本人必须
在当日水群榜上，概率判定和后续流程也都在馒头插件侧，本插件只负责在消息记录完成后转交触发者和
候选名单（候选昵称取自各自最近一次发言时的群名片/昵称）。发送 `/水群榜` 等命令、定时播报都不会
触发博弈；不在榜上的群友发言也不会触发。榜单名单按群做 30 秒缓存，刚上榜的群友可能需要等几十秒
才会参与触发判定。馒头插件未安装、未启用或调用失败时本插件不受影响，消息统计照常。

### 自定义资源

当第一名头像下载失败时，插件才会回退到 `resources` 文件夹中的背景图。你可以替换这些资源文件：
- `bg/` - 背景图片（随机选择）
- `frame/` - 排名边框装饰
- `ttf/` - 自定义字体（第一个 ttf 文件会被使用）

## 📄 许可证

本项目基于 [MsgRankCard](https://github.com/TonyLiangP2010405/MsgRankCard) 改写，采用 MIT 许可证。
