nonebot-plugin-maimai-raking 0.1.3

一个基于 NoneBot2 的舞萌 DX 分群排行榜插件

nonebot-plugin-maimai-raking

一个基于 NoneBot2 的舞萌 DX 分群排行榜插件

✨ 功能特性

🎮 核心功能

• 分群管理：每个群组独立管理排行榜数据，互不干扰
• 权限控制：超级管理员、群管理员、群主可以开关功能和管理成员
• 排行榜系统：用户可自愿加入/退出群内排行榜，支持管理员为他人操作
• 智能昵称：优先显示群名片，自动更新，提升用户识别度

🔄 自动更新

• 每天凌晨 0:00 自动更新歌曲数据
• 每天凌晨 0:05 自动更新歌曲别名库
• 每天凌晨 0:10 自动更新所有启用群的用户昵称
• 每天凌晨 0:15 自动更新所有用户的成绩数据
• 用户加入排行榜时自动刷新该群所有成员的昵称
• 管理员可手动使用 刷新昵称 命令更新群昵称
• 超管可使用 更新歌曲数据 命令手动更新水鱼歌曲数据

🎵 歌曲查询

• 支持歌曲名、别名、ID 多种方式查询
• 支持模糊匹配和智能搜索
• 可指定难度查询（绿/黄/红/紫/白）
• 默认显示最高难度的排行榜

📦 安装

使用 pip 安装：

pip install nonebot-plugin-maimai-raking

或使用 nb-cli：

nb plugin install nonebot-plugin-maimai-raking

⚙️ 配置

在 .env 文件中添加以下配置：

# 水鱼查分器 Developer Token（必填）
MAIMAI_DEVELOPER_TOKEN=your_developer_token_here

# 数据存储路径（可选，默认使用 nonebot-plugin-localstore 管理的插件数据目录）
MAIMAI_DATA_PATH=data/maimai_raking

# 缓存存储路径（可选，默认使用 nonebot-plugin-localstore 管理的插件缓存目录）
MAIMAI_CACHE_PATH=data/maimai_cache

获取 Developer Token

1. 访问 水鱼查分器
2. 登录你的账号
3. 进入"编辑个人资料"页面
4. 在"需要查分器中的玩家数据用于其他应用程序开发？请点击这里~"中申请 Developer Token

📖 使用方法

超管命令

以下命令需要超级管理员权限：

命令	说明
刷新排行榜	手动刷新当前群所有成员的成绩数据
重置刷新次数 <QQ号/@用户>	重置指定用户的今日刷新次数
更新歌曲数据	手动更新水鱼歌曲数据（歌曲名称、ID、难度等信息）
清理数据库	清理Bot已退出群组的数据
加入排行榜 <QQ号/@用户> [群号]	跨群加入排行榜
退出排行榜 <QQ号/@用户> [群号]	跨群退出排行榜

管理员命令

以下命令需要群主、管理员或超管权限：

命令	说明
开启舞萌排行榜	在当前群开启排行榜功能
关闭舞萌排行榜	在当前群关闭排行榜功能
刷新群昵称	手动刷新当前群所有成员的群昵称
刷新昵称	手动刷新当前群所有成员的群昵称（简化命令）
开启/关闭wmrt	开启/关闭本群的 Rating 排行榜功能
wmbm+/wmbm- <歌曲名/别名/ID> <新别名>	为歌曲添加/删除别名
加入排行榜 [QQ号/@用户]	为他人加入排行榜
退出排行榜 [QQ号/@用户]	为他人退出排行榜

用户命令

命令	说明
加入排行榜	加入排行榜
退出排行榜	退出排行榜
刷新成绩	刷新自己的成绩数据（每日限2次）
wmrk <歌曲名/别名/ID>	查询该歌曲在本群的排行榜（默认最高难度）
wmrk <歌曲名/别名/ID> <难度>	查询指定难度的排行榜
wmbm <歌曲名/别名/ID>	查询歌曲的别名信息
wmrt	查看本群全部 Rating 排行榜（前 10 名）
wmrt<分段>	查看指定分段的 Rating 排行榜（前 10 名）

难度参数

• 绿 - Basic
• 黄 - Advanced
• 红 - Expert
• 紫 - Master
• 白 - Re:Master

Rating 分段参数

• wmrt - 查询全部玩家
• wmrt0 - 查询 10000-10999 分段
• wmrt1 - 查询 11000-11999 分段
• wmrt2 - 查询 12000-12999 分段
• wmrt3 - 查询 13000-13999 分段
• wmrt4 - 查询 14000-14999 分段
• wmrt5 - 查询 15000-15999 分段
• wmrt6 - 查询 16000-16999 分段
• wmrt7 - 查询 17000-17999 分段

使用示例

用户操作

# 加入排行榜
用户: 加入排行榜
Bot: ✅ 已成功加入排行榜！
     昵称: 玩家A
     Rating: 14500

# 查询歌曲排行榜（默认最高难度）
用户: wmrk きたさいたま2000
Bot: [返回きたさいたま2000最高难度(紫)的排行榜图片]

# 查询指定难度
用户: wmrk 北埼玉 红
Bot: [返回きたさいたま2000 Expert 难度的排行榜图片]

# 使用别名查询
用户: wmrk 北埼玉
Bot: [返回きたさいたま2000的排行榜图片]

# 使用 ID 查询
用户: wmrk 388
Bot: [返回对应歌曲的排行榜图片]

# 查询歌曲详细信息
用户: wmbm 北埼玉
Bot: 🎵 歌曲信息
     📝 名称: きたさいたま2000
     🆔 ID: 388
     📊 类型: 标准谱面
     🏷️ 别名 (16个):
      2000
      kita
      きたさいたま2000
      下北泽2000
      五兄弟
      光污染小人
      全网最帅五兄弟
      北埼玉
      北埼玉2000
      北琦玉
      北琦玉2000
      埼玉2000
      太鼓2000
      琦玉2000
      过北脱新
      😁😁😁😁😁

# 刷新自己的成绩
用户: 刷新成绩
Bot: 正在刷新你的成绩数据，请稍候...
Bot: ✅ 成绩刷新完成！
     昵称: 玩家A
     Rating: 15000
     今日剩余刷新次数: 1/2

# 使用@用户加入排行榜
用户: 加入排行榜 @玩家B
Bot: ✅ 已成功为用户 123456789 加入排行榜！
     昵称: 玩家B
     Rating: 13800

# 加入指定群的排行榜（仅超管可执行）
超管: 加入排行榜 123456789 987654321
Bot: ✅ 已成功为用户 123456789 加入群 987654321 的排行榜！
     昵称: 玩家B
     Rating: 13800

超管: 加入排行榜 @玩家A 987654321
Bot: ✅ 已成功为用户 123456789 加入群 987654321 的排行榜！
     昵称: 玩家A
     Rating: 15000

# 使用@用户退出排行榜
用户: 退出排行榜 @玩家C
Bot: ✅ 已成功为用户 987654321 退出排行榜！

# 退出指定群的排行榜
超管: 退出排行榜 123456789 987654321
Bot: ✅ 已成功为用户 123456789 退出群 987654321 的排行榜！

超管: 退出排行榜 @玩家A 987654321
Bot: ✅ 已成功为用户 123456789 退出群 987654321 的排行榜！

# 查询 Rating 排行榜（全部）
用户: wmrt
Bot: 🏆 本群 Rating 排行榜 TOP 10
     ==============================
     🥇 玩家A
        Rating: 15000
     🥈 玩家B
        Rating: 14800
     🥉 玩家C
        Rating: 14500
     4. 玩家D
        Rating: 14200
     ...
     ==============================

# 查询指定分段 Rating 排行榜
用户: wmrt5
Bot: 🏆 本群 Rating 排行榜 W5 TOP 5
     ==============================
     🥇 玩家A
        Rating: 15888
     🥈 玩家B
        Rating: 15666
     🥉 玩家C
        Rating: 15234
     4. 玩家D
        Rating: 15100
     5. 玩家E
        Rating: 15000
     ==============================
     该分段共 5 人

用户: wmrt4
Bot: 🏆 本群 Rating 排行榜 W4 TOP 3
     ==============================
     🥇 玩家F
        Rating: 14999
     🥈 玩家G
        Rating: 14800
     🥉 玩家H
        Rating: 14500
     ==============================
     该分段共 3 人

用户: wmrt0
Bot: 🏆 本群 Rating 排行榜 W0 TOP 2
     ==============================
     🥇 玩家A
        Rating: 10800
     🥈 玩家B
        Rating: 10200
     ==============================
     该分段共 2 人

管理员操作

# 开启排行榜功能
管理员: 开启舞萌排行榜
Bot: ✅ 已在本群开启舞萌排行榜功能！

# 刷新排行榜数据
超管: 刷新排行榜
Bot: 正在刷新排行榜数据，请稍候...
Bot: 刷新完成！
     成功: 10 人
     失败: 0 人

# 超管重置用户刷新次数
超管: 重置刷新次数 @玩家A
Bot: ✅ 已重置用户 123456789 的今日刷新次数！

超管: 重置刷新次数 987654321
Bot: ✅ 已重置用户 987654321 的今日刷新次数！

# 更新歌曲数据
超管: 更新歌曲数据
Bot: 正在更新歌曲数据，请稍候...
Bot: ✅ 歌曲数据更新完成！
     共加载 1500 首歌曲

# 刷新群昵称
管理员: 刷新群昵称
Bot: 正在刷新群昵称，共 10 位用户...
Bot: ✅ 群昵称刷新完成！

# 刷新昵称（简化命令）
管理员: 刷新昵称
Bot: 正在刷新群昵称，共 10 位用户...
Bot: ✅ 群昵称刷新完成！

# 为他人加入排行榜（当前群）
管理员: 加入排行榜 123456789
Bot: ✅ 已成功为用户 123456789 加入排行榜！
     昵称: 玩家B
     Rating: 13800

# 为他人加入指定群的排行榜（仅超管可执行）
超管: 加入排行榜 123456789 987654321
Bot: ✅ 已成功为用户 123456789 加入群 987654321 的排行榜！
     昵称: 玩家B
     Rating: 13800

💡 注意事项

使用前提

1. ✅ 用户必须先在 水鱼查分器 绑定 QQ 号
2. ✅ 用户需要在水鱼查分器中关闭隐私设置（允许第三方查询）
3. ✅ Developer Token 有请求频率限制，请合理使用

功能特点

• 📊 排行榜默认显示歌曲的最高难度，可通过参数指定其他难度
• 🎯 排行榜最多显示前 20 名，避免图片过长
• 👥 昵称优先显示群名片，如无群名片则显示 QQ 昵称
• 🔄 用户加入排行榜时会自动刷新该群所有成员的昵称

💾 数据存储

插件数据使用 nonebot-plugin-localstore 管理，默认存储在插件专属的数据与缓存目录中。也可通过配置项自定义路径。

主数据库

• 📄 maimai_raking.db - 主数据库文件
  • groups 表 - 群组配置信息
  • users 表 - 用户基本信息
  • user_groups 表 - 用户-群组关系
  • records 表 - 用户成绩记录
  • custom_aliases 表 - 自定义歌曲别名

缓存数据库

• 📄 cache.db - 缓存数据库文件
  • alias_cache 表 - 别名数据缓存
  • cover_cache 表 - 歌曲封面缓存（BLOB）

📄 开源协议

本项目采用 GPL3.0 开源协议

🤝 贡献

欢迎提交 Issue 和 Pull Request！

如果你有任何建议或发现了 Bug，请：

1. 在 GitHub 上提交 Issue
2. Fork 本项目并提交 Pull Request
3. 联系作者反馈问题

🔗 相关链接

• NoneBot2 文档
• 水鱼查分器
• 落雪咖啡屋查分器
• 舞萌 DX 别名库
• OneBot 协议

👨‍💻 致谢

• 感谢 水鱼查分器 提供的成绩 API 支持
• 感谢 落雪咖啡屋 提供的 舞萌美术资源
• 感谢 柚子舞萌别名库 提供的别名数据
• 感谢 NoneBot2 社区的支持

---

本项目完全使用vibe coding