Maimai Random Helper - 舞萌随机查歌使用手册
0. 特别鸣谢
感谢水鱼提供的api数据支持！
1. 系统简介
Maimai Random Helper 是一个基于 Nonebot2 (OneBot V11) 的本地化舞萌 (Maimai DX) 查歌与推荐（鬼歌）插件。 该系统旨在为玩家群体提供一个高度自定义的“私有歌单”管理工具，解决玩家不知道玩什么歌、或者是不知道怎么阴人的困扰。该工具使用了基于水鱼查分器统计的功能。支持通过定数、离散度、拟合难度等硬核指标筛选谱面。
核心特性：
- 本地化运营：支持群友自行推荐并收录优质谱面，构建私有歌单。
- 神人筛选：基于 Diving Fish 查分器大数据。
- 可视化卡片：自动生成包含封面、难度、定数及详细统计数据的精美图片。
2. 用户指令指南 (User Guide)
所有指令统一前缀为 /d。（点歌的意思）
基础操作 (Basic)
| 指令格式 | 功能描述 | 示例 |
|---|---|---|
| /d | 随机选曲：从本群已收录的歌单中随机抽取一首。 | /d |
| /d -s [歌名/ID] [难度] | 收录歌曲：将指定谱面加入本群推荐歌单。 | /d -s 143 紫 /d -s Fragrance 白 |
注：难度支持中文（红/紫/白）或英文（Expert/Master/Re:Master）。
进阶筛选模式 (Advanced Filter)
系统提供三种基于玩家数据的特殊搜歌模式。支持叠加参数进行精确查找。
| 模式开关 | 名称 | 判定逻辑 | 适用场景 |
|---|---|---|---|
| -y | 越级 | 离散度 (StdDev) > 阈值 | 寻找手感诡异、上下限差距大的谱面 |
| -g | 鬼歌 | 拟合定数 > 官方定数 | 寻找实际难度高于标定等级的“地雷” |
| -t | 水分 | 拟合定数 < 官方定数 | 寻找实际难度低于标定等级的“爽局” |
筛选参数详解
以下参数可搭配上述模式开关使用，实现多维度过滤：
| 参数 | 描述 | 示例 | 说明 |
|---|---|---|---|
| -r [数值] | 阈值设定 | -r 0.5 | 设定离散度或定数差的临界值 |
| -d [难度] | 难度限制 | -d 紫白 | 仅筛选 Master 或 Re:Master 难度 |
| -f [版本] | 版本限制 | -f 熊镜 | 仅筛选 DX版(熊) 或 PRiSM版(镜) |
| -l [范围] | 等级范围 | -l 13+-14.5 | 筛选定数在指定区间内的谱面 |
| -i | 详细信息 | -i | 开启后额外显示曲师、BPM、流派等 |
组合指令示例：
- 找一首 DX版本(熊) 或 PRiSM版本(镜) 的紫谱或白谱，且实际难度比官方标定低 0.3 (适合推分)：
/d -t -r -0.3 -d 紫白 -f 熊镜 - 找一首 13+ 到 14.5 之间，离散度极高(>4.0) 的红谱：
/d -y -r 4.0 -l 13+-14.5 -d 红
3. 管理指令 (Admin)
该模式用于维护群歌单，仅 白名单管理员 (ADMIN_LIST) 或 该条目的原始推荐人 有权操作。
| 指令格式 | 功能描述 | 是否需确认 | 示例 |
|---|---|---|---|
| /d -c [歌名/ID] | 删除歌曲 | 是 (Confirm) | /d -c Fragrance |
| ... confirm | 确认删除 | - | /d -c Fragrance 白 confirm |
操作流程：
- 输入 /d -c [歌名]，系统会检索并列出匹配项。
- 若匹配唯一，系统提示确认；若匹配多个，系统提示补全信息（如难度）。
- 在指令后追加 confirm 完成删除（或按提示输入完整确认指令）。
4. 开发者文档 (Developer Reference)
4.1 文件结构
- maimai_helper.py: 插件核心逻辑。
- data/maimai_plugin/: 数据存储目录。
- maimai_lib.json: 官方基础数据 (music_data)。
- chart_stats.json: 玩家统计数据 (chart_stats)。
- group_playlist.json: 群友推荐歌单 (持久化存储)。
4.2 关键机制说明
定数范围解析 (Level Logic)
系统支持由 + 号构成的模糊定数写法，自动转换为闭区间：
- 14+ 作为下限时 -> 解析为 14.6
- 14+ 作为上限时 -> 解析为 14.9
- 13.5 -> 解析为 13.5
- 例：-l 13.5-14+ 等价于筛选定数范围 [13.5, 14.9]。
版本代号映射 (Version Mapping)
系统内置了完善的版本代号字典 (VERSION_MAP)，支持模糊匹配：
- **旧框：**真(maimai/maimai+)、超(Green)、檄(Green+)、橙(Orange)、晓(Orange+)、桃(Pink)、樱(pink+)、紫(Murasaki)、堇(Murasaki+)、白(Milk)、雪(Milk+)、辉(Finale)。
- DX：熊(DX)、华(DX+)、爽(Splash)、煌(Splash+)、宙(Universe)、星(Universe+)、祭(Festival)、祝(Festival+)、双(Buddies)、宴(Buddies+)、镜(PRiSM)。
- 特殊集合：输入“舞”可一次性涵盖从初代到Finale的所有旧框体版本。
- **注：**国服的歌曲分类太过于复杂和混乱，因此不考虑进去。
图片生成 (Rendering)
使用 Pillow 库动态绘制。
- 自适应排版：图片高度根据是否开启详细模式 (-i) 及元数据长度自动伸缩。
- 文字自适应：fit_text_width 算法确保超长歌名在卡片内完整显示不溢出。
4.3 配置参数
在 maimai_random_helper.py 头部可调整：
- WHITE_LIST: 开启机器人的群号白名单。
- ADMIN_LIST: 管理员 QQ 号列表。
- DIFF_MAP / DIFF_COLOR_MAP: 难度与颜色的映射配置。