maimai-mcp: Instructions file for Codex

Maimai DX MCP Server (Rust Architecture Specification)

本文档定义了将 Python 原版 maimaiDX 项目重构为高性能、模块化、代码精简的 Rust MCP 工具集的设计规范与实现蓝图。

1. 系统目标与设计原则

1. 通俗易懂与极简代码：
   • 杜绝过度工程和过深的抽象层，以简单、直观的函数式和轻量结构体驱动。
   • 整体代码量严格控制在 10,000 行以内。
2. 高性能与多线程：
   • 使用异步 I/O (tokio) 高并发处理查分网（水鱼 DivingFish / 落雪 LXNS / 柚子别名 Yuzuchan）的 HTTP 请求与数据同步。
   • 图片渲染阶段使用 CPU 多线程并发流水线（rayon 并行拼图和加载素材），大幅降低 B50 / 进度表渲染延迟。
3. 像素级绝对坐标对齐：
   • 采用纯 Rust 图像引擎（image + imageproc + ab_glyph），严格按照原 PIL 脚本的绝对像素坐标 (x, y) 贴图与绘制文字。
   • 静态资源路径完全兼容原项目规范，支持 MAIMAI_STATIC_DIR 环境变量与配置文件路径覆盖。
4. LLM 与 AstrBot 友好：
   • 自动支持上下文提取 QQ 号，统一入参标准。
   • 接口支持输出纯文本、Base64 图片（MCP 标准 Image Content Block）及本地图片文件路径，无缝兼容 QQ 机器人消息发送。

2. 模块架构设计

src/
├── main.rs                 # 服务入口、MCP Server 启动与 stdio 传输监听
├── config.rs               # 环境变量与资源路径配置 (MAIMAI_STATIC_DIR 等)
├── error.rs                # 统一轻量错误处理
│
├── core/
│   ├── models/             # 领域模型定义
│   │   ├── music.rs        # 曲目、谱面、等级与别名结构
│   │   ├── score.rs        # 成绩、分段、Rating 与 DX 分计算
│   │   └── user.rs         # 用户配置、绑定信息与凭据
│   │
│   ├── database/           # 本地数据存储与缓存
│   │   ├── music_db.rs     # 曲目库与谱面缓存索引
│   │   ├── alias_db.rs     # 别名数据库与模糊匹配
│   │   └── user_store.rs   # 按 QQ 号隔离的用户配置存储 (JSON)
│   │
│   ├── clients/            # 外部查分服务客户端 (Reqwest 异步请求)
│   │   ├── divingfish.rs   # 水鱼查分网 API Client
│   │   ├── lxns.rs         # 落雪查分网 API Client
│   │   └── yuzuchan.rs     # 柚子查分/别名数据源 Client
│   │
│   └── calc/               # 游戏数值算法
│       ├── rating.rs       # 单曲 Rating、B50 算法 (35 旧 + 15 新)
│       └── progress.rs     # 牌子、完成度、段位进度统计
│
├── draw/                   # 纯 Rust 绝对坐标绘图引擎 (image + ab_glyph + rayon)
│   ├── assets.rs           # 字体与图片素材加载/缓存管理器
│   ├── canvas.rs           # 坐标贴图、文字度量与绘制辅助器
│   ├── b50.rs              # B50 成绩总览图生成
│   ├── play_score.rs       # 单曲成绩结算卡片生成
│   ├── chart_info.rs       # 谱面信息预览卡片生成
│   ├── level_progress.rs   # 定数/等级完成度表生成
│   ├── plate_table.rs      # 牌子（霸者/舞舞/将/极/神等）进度表生成
│   ├── rating_table.rs     # Rating 达成表生成
│   └── fortune.rs          # 每日舞萌运势图生成
│
└── tools/                  # 供 LLM 调用的 MCP Tool 路由定义
    ├── b50.rs              # b50 查询与出图
    ├── score.rs            # 单曲成绩、分数线、上分推荐 (play_score / rise_score)
    ├── music.rs            # 曲目搜索、谱面信息、别名检索 (search_song / chart_info / alias)
    ├── random.rs           # 随机选曲、今天吃什么 (random_song / mai_what)
    ├── progress.rs         # 完成度与牌子进度 (level_progress / plate_table / level_score_list)
    ├── user.rs             # 绑定用户、查分源切换 (bind_player / user_settings)
    ├── fortune.rs          # 今日运势 (fortune)
    └── group_rank.rs       # 群内综合排行 (group_rank)