DivingFish：查询过滤能力与站点辅助端点 #1

New issue

Open

opened 2026-08-20 09:31:27 +00:00 by KumaAgent · 0 comments

KumaAgent commented

2026-08-20 09:31:27 +00:00

Member

背景

来自一次 DivingFish（水鱼查分器）实现 vs 文档偏移审查，DivingFish 部分已用真实后端源码（df-backend）复核，结论可信度较高。以下都是"文档描述了、src/DivingFish 完全没有对应实现"的真实缺口，不是 bug 修复。

已排除所有仅 @login_required（网站 Cookie 会话登录）鉴权、跟 Prober 这种第三方客户端场景不符的端点：/login、/player/agreement、/player/profile、/player/import_token。

参考文档：https://maimai.diving-fish.com/manual/docs/developer/zh-api-document

df-backend 源码（database/ 子目录）：https://github.com/Diving-Fish/maimaidx-prober/tree/main/database

查询过滤能力

1. `/player/records` 服务端过滤参数

src/DivingFish/DfPersonalClient.cs 的 GetPlayerDataAsync 目前无参数拉取全部成绩，未支持后端提供的服务端过滤能力：

STR 类型（精确匹配）：title/artist/genre/charter/version/release_date/type/level/level_label/rate/fc/fs
NUM 类型（支持精确匹配/闭区间/单边区间/逗号并列）：song_id/level_index/ds/bpm/achievements/dxScore/ra
BOOL 类型：is_new
专属参数 plate（牌子名转版本集合做 OR，再与显式 version 条件取交集）
响应体 filters 字段仅在有生效条件时才出现

来源：https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/tools/record_filter.py + https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/routes/maimai.py（/player/records）

2. `/player/test_data`

公开无鉴权的测试数据端点，player_id 固定为 636、username 固定回显字符串 "DivingFish"，不打码。适合用来做集成测试/连通性自检，目前客户端完全没有对接。

来源：https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/routes/maimai.py

站点辅助/公共端点

均已用 df-backend 源码确认真实存在，无需鉴权（除非特别说明）：

GET /count_view —— 注意每次调用都会让计数器 +1 并持久化，不是纯读接口
GET /alive_check —— 固定返回 {"message":"ok"}
GET /message —— 返回"今天"（UTC+8）留言，裸 JSON 数组，无需鉴权（POST 写入需要 Cookie 登录，按约定排除在外）
GET /advertisements —— 返回进程启动时一次性加载的静态数据（具体字段结构因数据文件不在 df-backend 仓库里，无法进一步确认）
GET /token_available —— 校验某个 Import-Token 是否有效，无鉴权；持有 Import-Token 的第三方客户端可以在正式使用前先调用它做前置校验

来源：https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/routes/public.py

## 背景来自一次 DivingFish（水鱼查分器）实现 vs 文档偏移审查，DivingFish 部分已用真实后端源码（df-backend）复核，结论可信度较高。以下都是"文档描述了、`src/DivingFish` 完全没有对应实现"的真实缺口，不是 bug 修复。已排除所有仅 `@login_required`（网站 Cookie 会话登录）鉴权、跟 Prober 这种第三方客户端场景不符的端点：`/login`、`/player/agreement`、`/player/profile`、`/player/import_token`。参考文档：https://maimai.diving-fish.com/manual/docs/developer/zh-api-document df-backend 源码（`database/` 子目录）：https://github.com/Diving-Fish/maimaidx-prober/tree/main/database ## 查询过滤能力 ### 1. `/player/records` 服务端过滤参数 `src/DivingFish/DfPersonalClient.cs` 的 `GetPlayerDataAsync` 目前无参数拉取全部成绩，未支持后端提供的服务端过滤能力： - STR 类型（精确匹配）：`title`/`artist`/`genre`/`charter`/`version`/`release_date`/`type`/`level`/`level_label`/`rate`/`fc`/`fs` - NUM 类型（支持精确匹配/闭区间/单边区间/逗号并列）：`song_id`/`level_index`/`ds`/`bpm`/`achievements`/`dxScore`/`ra` - BOOL 类型：`is_new` - 专属参数 `plate`（牌子名转版本集合做 OR，再与显式 `version` 条件取交集） - 响应体 `filters` 字段仅在有生效条件时才出现来源：https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/tools/record_filter.py + https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/routes/maimai.py（`/player/records`） ### 2. `/player/test_data` 公开无鉴权的测试数据端点，`player_id` 固定为 636、`username` 固定回显字符串 `"DivingFish"`，不打码。适合用来做集成测试/连通性自检，目前客户端完全没有对接。来源：https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/routes/maimai.py ## 站点辅助/公共端点均已用 df-backend 源码确认真实存在，无需鉴权（除非特别说明）： - `GET /count_view` —— **注意每次调用都会让计数器 +1 并持久化，不是纯读接口** - `GET /alive_check` —— 固定返回 `{"message":"ok"}` - `GET /message` —— 返回"今天"（UTC+8）留言，裸 JSON 数组，无需鉴权（POST 写入需要 Cookie 登录，按约定排除在外） - `GET /advertisements` —— 返回进程启动时一次性加载的静态数据（具体字段结构因数据文件不在 df-backend 仓库里，无法进一步确认） - `GET /token_available` —— 校验某个 Import-Token 是否有效，无鉴权；持有 Import-Token 的第三方客户端可以在正式使用前先调用它做前置校验来源：https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/routes/public.py

KumaAgent added the

状态：待评估

label

2026-08-20 09:31:33 +00:00