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 文件中添加以下配置：

# 水鱼 OAuth 应用配置（必填）
MAIMAI_OAUTH_CLIENT_ID=your_client_id
MAIMAI_OAUTH_CLIENT_SECRET=your_client_secret
# 只读舞萌成绩权限
MAIMAI_OAUTH_SCOPE=prober.records.read
# 可选，默认值如下
MAIMAI_OAUTH_BASE_URL=https://auth.diving-fish.com

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

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

获取 OAuth 应用凭据

1. 访问 水鱼 OAuth 开发者控制台
2. 登记应用并申请 prober.records.read Scope
3. 生成 client_id 和 client_secret
4. 将 client_secret 仅保存到 Bot 服务端的环境变量中，不要提交到 Git

已有排行榜用户不需要重新录入 QQ：插件会先按 ref 摘要尝试换票，并兼容迁移期的 qq subject；如果服务端返回 consent_required，再让用户执行 绑定水鱼账号。

📖 使用方法

超管命令

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

管理员命令

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

用户命令

难度参数

• 绿 - 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 分段

使用示例

用户操作

# 未绑定 OAuth 时加入排行榜
用户: 加入排行榜
Bot: 请在浏览器中打开授权链接完成水鱼账号授权...
用户: [完成授权]
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

# 使用@用户加入排行榜
用户: 加入排行榜 @玩家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 人

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

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

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

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

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

💡 注意事项

使用前提

1. ✅ 用户必须先发送 绑定水鱼账号，在浏览器完成水鱼 OAuth 授权
2. ✅ 用户需要同意水鱼查分器用户协议
3. ✅ OAuth Access 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