@mai-kit/prober

@mai-kit/prober 提供舞萌 DX 玩家数据的只读查询。

ProberPlayer、PlayerProfile、Score 和 Bests 不依赖具体查分服务。 LXNS 与 Diving-Fish 适配把各自的 API 响应转换为这些类型，得到的 profile 和 bests 都可以传给 Draw.poster()。

查询玩家数据

// player 由适配创建，类型为 ProberPlayer
const [profile, bests] = await Promise.all([
  player.getProfile(),
  player.getBests(),
]);
// → Draw.poster(profile, bests)

内置适配

import { createLxnsClient, createDivingFishClient } from "@mai-kit/prober";

// LXNS
const me = createLxnsClient({ personalAccessToken: "..." }).me();

// Diving-Fish 公开 B50
const df = createDivingFishClient();
const player = await df.getPlayer({ username: "someone" });

错误处理

• ProberError：鉴权 / HTTP / 业务失败
• ProberNotImplementedError：适配无法实现某能力（包级，供实现复用）
• 适配子类：LxnsProberError / DivingFishProberError

import {
  isDivingFishProberError,
  isLxnsProberError,
  isProberError,
  isProberNotImplementedError,
} from "@mai-kit/prober";

try {
  await player.getBests();
} catch (error) {
  if (isProberNotImplementedError(error)) console.error("unsupported", error.method);
  else if (isLxnsProberError(error)) console.error("LXNS", error.status);
  else if (isDivingFishProberError(error)) console.error("Diving-Fish", error.status);
  else if (isProberError(error)) console.error("prober", error.message);
  else throw error;
}

包与职责 · 快速开始

接口与模型

名称	描述
Bests	Best50 结构。
BestScoreCapability	提供单谱面最佳成绩查询的玩家能力。
HeatmapCapability	提供出勤热力图查询的玩家能力。
PlayerCollection	玩家当前装备的收藏品信息。
PlayerCollectionListCapability	提供玩家已获得收藏品列表的能力。
PlayerCollectionProgressCapability	提供单个收藏品完成进度的能力。
PlayerProfile	玩家档案（与具体查分服务无关的通用模型）。 字段语义对齐常见查分器约定；可直接交给 @mai-kit/draw 的 Draw.poster。
ProberPlayer	已绑定身份的玩家只读查询接口（与具体查分服务无关）。
RatingTrend	某一日或版本节点的 Rating 走势记录。
RatingTrendCapability	提供 Rating 走势查询的玩家能力。
RecentScoresCapability	提供最近成绩查询的玩家能力。
Score	单条成绩。
ScoreHistoryCapability	提供单谱面成绩历史查询的玩家能力。
ScoreKey	唯一定位一张谱面的组合键。
ScoreListCapability	提供全量成绩查询的玩家能力。
ScoreRankingCapability	提供单谱面公开排行查询的玩家能力。
ScoreRankingEntry	单谱面公开排行中的一名玩家成绩。
SimpleScore	不含达成率与 DX 分的精简成绩，用于仅需谱面与通关标记的列表。
FullProberPlayer	具备档案、Best50、全量成绩、最近成绩、走势、热力图与单谱面历史的玩家查询对象。 由支持上述全部能力的适配在绑定身份后返回（与具体数据源无关）。
Heatmap	出勤热力图：键为数据源的日期标识，值为当日游玩次数。
ScoreHistory	单谱面的历史成绩；数据源明确表示无记录时为 null。
ScoreQuery	成绩列表的可选筛选条件。
ScoresProberPlayer	至少提供档案、Best50 与全量成绩的玩家对象。
SongScoreQuery	必须指定曲目 id 或曲名的成绩查询（用于单曲 Best 接口）。

LXNS 适配

名称	描述
LxnsProberError	LXNS 查分适配专用错误（继承 ProberError）。
LxnsClientOptions	LXNS 适配的客户端选项（至少提供一种 token）。
LxnsDevClient	LXNS 开发者令牌路径：先绑定玩家，再调用玩家能力。
LxnsDevPlayer	LXNS 开发者令牌绑定的玩家。
LxnsPersonalPlayer	LXNS 个人令牌绑定的玩家。
LxnsYearInReview	LXNS 年度总结；上游会按年份增加额外统计字段。
LxnsClient	LXNS 适配客户端类型：按构造时传入的 token 条件暴露方法。
createLxnsClient	创建 LXNS 查分适配客户端（将 LXNS API 映射为 ProberPlayer 等通用类型）。
isLxnsProberError	类型守卫：是否为 LxnsProberError。

Diving-Fish 适配

名称	描述
DivingFishProberError	Diving-Fish（水鱼）查分适配专用错误（继承 ProberError）。
DivingFishClientOptions	Diving-Fish 适配客户端选项。
DivingFishDeveloperPlayer	水鱼 Developer-Token 绑定的玩家。
DivingFishRatingRankEntry	水鱼公开 Rating 排行中的一名玩家。
DivingFishVersionScore	水鱼 /query/plate 返回的按版本成绩（字段少于完整 Score）。
DivingFishClient	Diving-Fish 适配客户端类型。
DivingFishPlayerQuery	查询目标：用户名或 QQ 二选一。
createDivingFishClient	创建 Diving-Fish（水鱼）查分适配客户端。
isDivingFishProberError	类型守卫：是否为 DivingFishProberError。

错误

名称	描述
ProberError	查分器通用错误（鉴权失败、HTTP / 业务错误等）。
ProberNotImplementedError	当前查分源无法实现某查询能力时抛出的包级错误。
ProberErrorInit	ProberError 构造参数
ProberNotImplementedErrorInit	ProberNotImplementedError 构造参数
isProberError	类型守卫：是否为 ProberError（含各适配子类）。
isProberNotImplementedError	类型守卫：是否为 ProberNotImplementedError。