项目目标与能力边界#

目前插件提供以下命令：

有两条边界在开发中被刻意写死：

1. 插件只处理 QQ/OneBot v11 的群聊命令与私聊二维码；非目标平台直接退出，避免把依赖平台报文结构的代码误用到其他适配器。
2. /unlock confirm 被明确禁用。当前实现最多读取数据并生成预览，绝不调用 Upsert* 存档写接口，避免不完整快照覆盖玩家已有数据。

整体结构：把易变的部分隔离开#

最初的移植版本很容易把命令、网络报文、二维码、缓存和展示全堆到入口文件中。后续将其拆分为几层，使每个模块的失败模式都更清楚。

1
main.py                 AstrBot 命令、事件路由与业务编排
2
pending_login.py        二维码等待状态与 120 秒超时管理
3
maimai/runtime.py       配置、数据目录与代理参数
4
maimai/qr_decode.py     图片尺寸检查与二维码解码
5
maimai/qr_auth.py       Aime 二维码认证
6
maimai/client.py        加密请求、会话、重试与日志脱敏
7
maimai/requests.py      协议请求体的固定字段与字段顺序
8
maimai/music_data.py    曲库定数与物量缓存
9
maimai/cover.py         封面、头像、名牌资源下载与本地缓存
10
maimai/b50_view.py      原始成绩 -> 可渲染 view-model
11
maimai/b50_image.py     HTML 模板注入与 Playwright 截图
12
maimai/b50_text.py      图片渲染不可用时的文本降级输出
13
tests/                  协议、安全、缓存与降级回归测试

main.py 只负责业务层的“何时做什么”：注册指令、记录群消息上下文、在私聊收图、将认证成功后的数据送到具体流程。协议细节放在 maimai/ 内部，因而后续排查某个接口或替换渲染方式时，不会牵动机器人事件逻辑。

二维码登录：群里发起，私聊完成#

交互看似简单，但机器人场景有一个天然约束：群里的提问与私聊里的二维码必须可靠地关联到同一个人、同一条原始消息和同一个业务动作。

因此实现了 PendingLoginManager。它以 QQ 号为键，保存一次性回调、原群 ID、原群消息 ID 与超时任务：

这里有几个容易被忽略的实现细节：

• 同一用户再次发起命令会先取消旧的超时任务，再覆盖为新上下文，避免旧流程在 120 秒后意外回调。
• 收到二维码时会立刻从待处理表中弹出该条记录，保证同一登录凭据只会被消费一次。
• 认证和完整数据拉取放入 asyncio.create_task() 后台运行。完整 B50 流程可能需要等待服务端会话就绪，不能阻塞私聊消息处理器。
• 所有命令与已接管的二维码事件都会调用 event.stop_event()，防止 AstrBot 默认 LLM 再把命令或图片交给模型处理，产生“模型不支持图片输入”之类无关的噪声。

二维码不是普通图片：先拒绝危险输入#

图片解码通常是被忽略的攻击面。二维码图片来自用户，直接交给 Pillow、OpenCV 等解码器之前，可能先触发巨幅图片解压带来的内存问题。

maimai/qr_decode.py 先只读取 PNG、JPEG、GIF 与 WebP 的文件头，得到宽高而不解压像素数据；总像素数超过 16,000,000 时立即拒绝。入口侧还限制单个图片不超过 8 MiB。通过这两道检查后，才按顺序尝试 OpenCV 的 QRCodeDetector 与 pyzbar。

这种做法的重点不是追求“任何图片都能识别”，而是把失败变成可控的 None：用户会收到“图片无法读取、过大或未识别”的提示，插件进程则不会因为一张异常图片失去响应。

协议移植：报文正确远不止 AES 正确#

称号服务的请求管线可以概括为：

1
JSON 字符串
2
  -> UTF-8
3
  -> zlib deflate
4
  -> AES-CBC + PKCS#7
5
  -> HTTP body
6

7
HTTP body
8
  -> AES 解密
9
  -> zlib inflate
10
  -> UTF-8 JSON

看起来是标准的“压缩加密 HTTP”，真正难的是协议兼容性。移植时确认了以下约束：

• API 路径不是明文接口名，而是 md5(api + "MaimaiChn" + obfuscateParam) 的小写十六进制结果。
• User-Agent、Mai-Encoding、Accept-Encoding、Charset、Content-Encoding 与 Host 等请求头需要保持与参考实现一致。
• 请求体并非只要 JSON 语义相同即可。json.dumps 的默认空格、字段声明顺序都被固定在 requests.py 中，避免“逻辑正确、服务端仍拒绝”的隐性差异。
• AES key、IV、机台身份和服务地址都从 AstrBot 配置或环境变量读取；公开的 _conf_schema.json 只保留空默认值，不把真实凭据提交到仓库。

1
new_session()
2
  -> UserLoginApi
3
  -> 等待会话生效
4
  -> GetUserRatingApi
5
  -> GetUserMusicApi
6
  -> UserLogoutApi

重试不是越多越好#

网络波动时重试可以改善只读查询的体验，但如果把这个策略套用到写操作，就会把一次不确定的请求变成重复提交。

maimai/client.py 因此把接口分成两类：

• 普通读取接口最多尝试两次，失败间隔一秒。
• 以 Upsert、Upload、UserLogin、UserLogout 开头的操作不自动重试。

这既避免了写接口重复产生副作用，也避免在登录/登出阶段制造难以判断的状态。日志记录响应头时会对 Authorization、Cookie 与 Set-Cookie 做脱敏，保留足够的诊断信息而不把会话凭据写进日志。

B50：缓存、资源下载与多层降级#

B50 是项目里体验最重要、链路也最长的功能。它不能只把服务器 JSON 原样贴到聊天里：需要补曲名和定数、算单曲 RA、读取封面/头像/名牌，最后还要以易读的方式排版。

Less 与 Full：根据账号状态选择成本#

认证后，插件先取得用户预览信息，并依据 isLogin 选择不同路径：

• Less 路径：账号已经登录时，仅获取 Rating 数据；速度更快，也不会强行登录或登出。代价是不能可靠获取完整的 combo/sync 徽章。
• Full 路径：账号未登录时，使用共享 Cookie 的会话完成登录、等待、Rating 与 Music 查询，并在 finally 路径中尽力登出。音乐数据获取失败并不是致命错误，会降级为没有徽章的信息而不是丢失整份 B50。

这不是单纯的性能优化，而是把“尽量少改变账号状态”作为默认原则。

写入能力：宁可诚实地保留未解问题#

/ticket 需要调用真实写接口 UpsertUserChargelogApi，它与只读查询不同，不能拿到 HTTP 200 就当作成功。开发时已实现以下保护：登录、读取当前库存、确认未拥有目标票券、同会话提交写入、最后登出；写操作不重试。

不过截至本文更新，服务端对该写入请求仍可能返回 returnCode=0，真机验证尚未形成稳定的成功结论。尽管已经依据真实客户端样本调整过请求体字段顺序、playCount、playerRating 和 loginDateTime 等字段，仍不应把它描述为可靠功能。

这也是本项目一个刻意保留的开发原则：对会产生账户副作用的能力，未知状态必须写在文档和代码边界里，而不是用“看起来已经发出请求”掩盖结果。

回归测试覆盖了哪些风险#

当前测试通过 24 项，重点不在堆高覆盖率数字，而在固定容易回归的边界条件：

• AES 加解密往返与不合法 PKCS#7 Padding 拒绝；
• 请求格式的字段顺序与序列化结果；
• 只读接口可重试、登录/登出/写接口不可重试；
• 响应日志中的敏感请求头脱敏；
• 超大 PNG 在真正解码前被拒绝；
• 非法资源 ID 不会拼接远程 URL；
• 曲库刷新失败时保留可用旧缓存；
• /unlock 源码路径不包含 Upsert 写接口；
• 图片渲染与文本渲染双重失败时给出可控错误；
• 私聊图片无法读取时正确停止事件传播。

本地验证命令：

1
python -m unittest discover -v
2
python -m scripts.parity_check

后续工作#

接下来最值得继续投入的方向有三个：

1. 为 /ticket 建立更严格的真机验证记录，在确认服务端写入语义之前维持保守提示。
2. 将协议层的成功与失败报文样本进一步固化为离线 fixture，减少只能在线调试的情况。
3. 为 B50 模板提供独立的视觉回归截图，保证后续调整数据模型时不悄悄破坏排版。

这次开发最有价值的收获不是“把一个查分功能跑起来”，而是把不可见的约束变成代码结构：会话必须共享、用户图片要先验、写操作不能重试、渲染总要能退回文本、未知的写入结果不能被包装成成功。对一个常驻机器人的插件来说，这些细节才是真正决定可用性的部分。