@cs2dak/contract 0.2.0 → 1.0.0

package/src/leaderboard.ts

@@ -0,0 +1,102 @@
+import type { PrismResult } from "@rivalhub/rival-rating";
+import { z } from "zod";
+import { teamKeySchema } from "cs2-demo-format";
+import { seasonCohortBundleSchema } from "./cohort.js";
+
+/**
+ * 赛季排行榜展示模型。由 @cs2dak/presentation 从 SeasonCohortBundle 派生，
+ * 吸收 RivalHub 排行榜的产品信息架构（分栏、标签、默认排序），但：
+ * - 不含数据库/权限/路由语义（规则 8）；身份用中立的 playerKey/teamKeys。
+ * - 缺失指标保持 null，不伪造 0（规则 6）。
+ * - 不计算评分公式；rrV1/accountRR/prism 均来自 cohort 已接线的 rival-rating 结果（规则 5）。
+ */
+
+/** 排行榜可展示的指标 key。值统一存原始量纲，缩放与单位由 format 决定。 */
+export const leaderboardMetricKeySchema = z.enum([
+  "maps",
+  // 评分门面
+  "rivalhubRR", // accountRR（绝对刻度 RivalHub RR）
+  "hltvRating", // rrV1（HLTV Rating 2.0 量纲，已被逆向验证）
+  // core
+  "adr",
+  "kd",
+  "kpr",
+  "hsPercent",
+  // impact（产量家族：每 100 回合 X 次）
+  "firstKillPer100",
+  "multiKillPer100",
+  "clutchPer100",
+  "openingDuelWinRate",
+  // advanced
+  "kast",
+  "utilityDamagePerRound",
+  "awpKillsPerRound",
+  "awpKillRate",
+  "flashAssistPerRound",
+  "tradeKillRate"
+]);
+
+/**
+ * 渲染格式。所有百分比类指标在 builder 中已统一为 0–100 刻度，故只有一个 percent 格式：
+ * - integer: 整数
+ * - rating:  2 位小数（RR / HLTV）
+ * - adr:     1 位小数
+ * - ratio:   2 位小数（K/D、KPR、每 100 回合产量 FK/MK/C、每回合计数）
+ * - percent: 值已是 0–100，1 位小数 + %（HS% / KAST% / Entry% / AWP%）
+ */
+export const leaderboardFormatSchema = z.enum([
+  "integer",
+  "rating",
+  "adr",
+  "ratio",
+  "percent"
+]);
+
+export const leaderboardColumnSchema = z.object({
+  key: leaderboardMetricKeySchema,
+  label: z.string(),
+  format: leaderboardFormatSchema,
+  /** 列说明 / tooltip；无则 null。 */
+  description: z.string().nullable()
+});
+
+export const leaderboardViewKeySchema = z.enum(["core", "impact", "advanced"]);
+
+export const leaderboardViewSchema = z.object({
+  key: leaderboardViewKeySchema,
+  label: z.string(),
+  /** 默认排序列（始终降序）。 */
+  defaultSort: leaderboardMetricKeySchema,
+  columns: z.array(leaderboardColumnSchema)
+});
+
+export const seasonLeaderboardRowSchema = z.object({
+  playerKey: z.string(),
+  name: z.string(),
+  steamIds: z.array(z.string()),
+  externalUserId: z.string().nullable(),
+  teamKeys: z.array(teamKeySchema),
+  mapCount: z.number().int().positive(),
+  confidence: z.number().min(0).max(1),
+  /** 每个指标 key 都有值；不可得为 null（不伪造 0）。 */
+  metrics: z.record(leaderboardMetricKeySchema, z.number().nullable()),
+  /** PRISM 风格画像，仅表达风格，不进入排序；缺失为 null。 */
+  prism: z.custom<PrismResult>().nullable()
+});
+
+export const seasonLeaderboardModelSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/leaderboard-0.1"),
+  weightsVersion: z.string(),
+  matchCount: z.number().int().nonnegative(),
+  provenance: seasonCohortBundleSchema.shape.provenance,
+  views: z.array(leaderboardViewSchema),
+  rows: z.array(seasonLeaderboardRowSchema)
+});
+
+export type LeaderboardMetricKey = z.infer<typeof leaderboardMetricKeySchema>;
+export type LeaderboardFormat = z.infer<typeof leaderboardFormatSchema>;
+export type LeaderboardColumn = z.infer<typeof leaderboardColumnSchema>;
+export type LeaderboardViewKey = z.infer<typeof leaderboardViewKeySchema>;
+export type LeaderboardView = z.infer<typeof leaderboardViewSchema>;
+export type SeasonLeaderboardRow = z.infer<typeof seasonLeaderboardRowSchema>;
+export type SeasonLeaderboardModel = z.infer<typeof seasonLeaderboardModelSchema>;

package/src/player.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { teamKeySchema } from "cs2-demo-format";
+import { accountContextAvailabilitySchema } from "./analysis.js";
+import { leaderboardMetricKeySchema } from "./leaderboard.js";
+
+/**
+ * 选手赛季档案。由 @cs2dak/presentation 从 SeasonCohortBundle 中单个选手派生。
+ * 产品中立：身份用 playerKey/steamIds/externalUserId，不含数据库/路由/权限语义（规则 8）。
+ * 不算评分公式；rating/style 均来自 cohort 已接线的 rival-rating 结果（规则 5）。
+ * 缺失保持 null（规则 6）；style 在 PRISM 缺失时整体为 null。
+ */
+
+export const rrBreakdownEntrySchema = z.object({
+  key: z.enum(["combat", "trade", "clutch", "objective", "utility"]),
+  label: z.string(),
+  value: z.number()
+});
+
+/** PRISM 单根轴的展示项（八维风格雷达）。 */
+export const playerStyleAxisSchema = z.object({
+  key: z.string(), // PrismAxisKey
+  label: z.string(),
+  percentile: z.number().min(0).max(100)
+});
+
+export const playerStyleSchema = z.object({
+  weightsVersion: z.string(),
+  /** 整体着色依据：RR 百分位（0–100）。 */
+  rrPercentile: z.number().min(0).max(100),
+  /** 八根轴，按 PRISM_AXIS_ORDER 排序。 */
+  axes: z.array(playerStyleAxisSchema)
+});
+
+export const playerSeasonTrendPointSchema = z.object({
+  matchId: z.string(),
+  rivalhubRR: z.number().nonnegative(),
+  hltvRating: z.number().nonnegative()
+});
+
+export const playerWeaponProfileEntrySchema = z.object({
+  weapon: z.string(),
+  label: z.string(),
+  kills: z.number().int().nonnegative(),
+  killSharePercent: z.number().min(0).max(100),
+  headshotPercent: z.number().min(0).max(100).nullable(),
+  tradeKillPercent: z.number().min(0).max(100).nullable(),
+  noScopePercent: z.number().min(0).max(100).nullable(),
+  throughSmokePercent: z.number().min(0).max(100).nullable(),
+  wallbangPercent: z.number().min(0).max(100).nullable(),
+  averagePenetratedObjects: z.number().nonnegative().nullable()
+});
+
+export const playerSeasonProfileSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/player-profile-0.1"),
+  weightsVersion: z.string(),
+  playerKey: z.string(),
+  name: z.string(),
+  steamIds: z.array(z.string()),
+  externalUserId: z.string().nullable(),
+  teamKeys: z.array(teamKeySchema),
+  mapCount: z.number().int().positive(),
+  confidence: z.number().min(0).max(1),
+  accountContextStatus: z.object({
+    buyDelta: accountContextAvailabilitySchema,
+    manState: accountContextAvailabilitySchema
+  }),
+  rating: z.object({
+    rivalhubRR: z.number().nonnegative(),
+    rivalhubRRRaw: z.number(),
+    hltvRating: z.number().nonnegative(),
+    hltvPercentile: z.number().min(0).max(100),
+    breakdown: z.array(rrBreakdownEntrySchema)
+  }),
+  /** 与排行榜同口径的展示指标（共享 SEASON_STAT_VIEWS 渲染列）。 */
+  metrics: z.record(leaderboardMetricKeySchema, z.number().nullable()),
+  weapons: z.array(playerWeaponProfileEntrySchema),
+  highlights: z.object({
+    wallbangKills: z.number().int().nonnegative().nullable(),
+    noScopeKills: z.number().int().nonnegative().nullable(),
+    throughSmokeKills: z.number().int().nonnegative().nullable(),
+    collateralKills: z.number().int().nonnegative().nullable()
+  }),
+  style: playerStyleSchema.nullable(),
+  /** 每场 RR 趋势，按 matchId 升序。 */
+  perMatch: z.array(playerSeasonTrendPointSchema),
+  /** 相对赛季 cohort 的强项 / 弱项（按技能类指标的 cohort 百分位派生）。 */
+  strengths: z.array(z.string()),
+  weaknesses: z.array(z.string())
+});
+
+export type RRBreakdownEntry = z.infer<typeof rrBreakdownEntrySchema>;
+export type PlayerStyleAxis = z.infer<typeof playerStyleAxisSchema>;
+export type PlayerStyle = z.infer<typeof playerStyleSchema>;
+export type PlayerSeasonTrendPoint = z.infer<typeof playerSeasonTrendPointSchema>;
+export type PlayerWeaponProfileEntry = z.infer<typeof playerWeaponProfileEntrySchema>;
+export type PlayerSeasonProfile = z.infer<typeof playerSeasonProfileSchema>;

package/src/qa.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const qaIssueSchema = z.object({
+  severity: z.enum(["info", "warning", "error"]),
+  code: z.string().min(1),
+  message: z.string().min(1),
+  path: z.string().optional()
+});
+
+export const qaReportSchema = z.object({
+  ok: z.boolean(),
+  summary: z.object({
+    issueCount: z.number().int().nonnegative(),
+    errorCount: z.number().int().nonnegative(),
+    warningCount: z.number().int().nonnegative()
+  }),
+  issues: z.array(qaIssueSchema)
+});
+
+export type QaIssue = z.infer<typeof qaIssueSchema>;
+export type QaReport = z.infer<typeof qaReportSchema>;

package/src/scoring.ts

@@ -0,0 +1,79 @@
+import type { RRIndicators } from "@rivalhub/rival-rating";
+import { z } from "zod";
+
+const clutchSplitSchema = z.object({
+  count: z.number().int().nonnegative(),
+  won: z.number().int().nonnegative()
+});
+
+export const rrIndicatorsSchema: z.ZodType<RRIndicators> = z.object({
+  steamId64: z.string(),
+  totalRounds: z.number().int().nonnegative(),
+  kills: z.number().int().nonnegative(),
+  deaths: z.number().int().nonnegative(),
+  assists: z.number().int().nonnegative(),
+  kpr: z.number().nonnegative(),
+  dpr: z.number().nonnegative(),
+  apr: z.number().nonnegative(),
+  adr: z.number().nonnegative(),
+  hsPercent: z.number().min(0).max(100),
+  kast: z.number().min(0).max(100),
+  survivalRate: z.number().min(0).max(1),
+  twoKillRounds: z.number().int().nonnegative(),
+  threeKillRounds: z.number().int().nonnegative(),
+  fourKillRounds: z.number().int().nonnegative(),
+  fiveKillRounds: z.number().int().nonnegative(),
+  multiKillRate: z.number().min(0).max(1),
+  firstKillCount: z.number().int().nonnegative(),
+  firstDeathCount: z.number().int().nonnegative(),
+  firstKillRate: z.number().nonnegative(),
+  firstDeathRate: z.number().nonnegative(),
+  openingDuelRate: z.number().nonnegative(),
+  openingDuelWinRate: z.number().min(0).max(1),
+  tradeKillCount: z.number().int().nonnegative(),
+  tradeDeathCount: z.number().int().nonnegative(),
+  tradeKillRate: z.number().nonnegative(),
+  tradeDeathRate: z.number().nonnegative(),
+  clutchAttempts: z.number().int().nonnegative(),
+  clutchWins: z.number().int().nonnegative(),
+  clutchWinRate: z.number().min(0).max(1),
+  clutchFrequency: z.number().nonnegative(),
+  clutchScore: z.number().nonnegative(),
+  clutchScoreRate: z.number().nonnegative(),
+  vsOne: clutchSplitSchema,
+  vsTwo: clutchSplitSchema,
+  vsThree: clutchSplitSchema,
+  vsFour: clutchSplitSchema,
+  vsFive: clutchSplitSchema,
+  awpKills: z.number().int().nonnegative(),
+  awpKillsPerRound: z.number().nonnegative(),
+  awpKillRate: z.number().min(0).max(1),
+  sniperKills: z.number().int().nonnegative(),
+  sniperKillRate: z.number().min(0).max(1),
+  awpMultiKillRate: z.number().min(0).max(1).nullable(),
+  awpDuelWinRate: z.number().min(0).max(1).nullable(),
+  utilityDamage: z.number().int().nonnegative(),
+  utilityDamagePerRound: z.number().nonnegative(),
+  flashAssistCount: z.number().int().nonnegative(),
+  flashAssistPerRound: z.number().nonnegative(),
+  blindDurationTotal: z.number().nonnegative(),
+  blindDurationPerRound: z.number().nonnegative(),
+  enemyFlashDurationSeconds: z.number().nonnegative().nullable(),
+  enemyFlashDurationPerRound: z.number().nonnegative().nullable(),
+  teamFlashDurationSeconds: z.number().nonnegative().nullable(),
+  teamFlashDurationPerRound: z.number().nonnegative().nullable(),
+  grenadeCount: z.number().int().nonnegative(),
+  grenadeCountPerRound: z.number().nonnegative(),
+  ecoRoundCount: z.number().int().nonnegative(),
+  forceRoundCount: z.number().int().nonnegative(),
+  fullBuyRoundCount: z.number().int().nonnegative(),
+  pistolRoundCount: z.number().int().nonnegative(),
+  avgEquipmentValue: z.number().nonnegative(),
+  combatDeathCount: z.number().int().nonnegative().nullable(),
+  bombDeathCount: z.number().int().nonnegative().nullable(),
+  wallbangKillCount: z.number().int().nonnegative().nullable(),
+  roundSwingTotal: z.number().nullable(),
+  roundSwingPerKill: z.number().nullable()
+});
+
+export type { AccountSignalsV2, RRIndicators, RRResult, RRResultV2, PrismResult, ValueAccountsWeights } from "@rivalhub/rival-rating";

package/src/series.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { matchWorkspaceModelSchema } from "./workspace.js";
+
+export const mvpCandidateSchema = z.object({
+  playerKey: z.string(),
+  name: z.string(),
+  teamName: z.string(),
+  recommendationScore: z.number().nonnegative(),
+  rivalhubRR: z.number().nonnegative(),
+  hltvRating: z.number().nonnegative(),
+  confidence: z.number().min(0).max(1),
+  explanation: z.array(z.string())
+});
+
+export const mvpRecommendationSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/mvp-recommendation-0.1"),
+  recommended: mvpCandidateSchema,
+  candidates: z.array(mvpCandidateSchema).min(1)
+});
+
+export const seriesMatchInputSchema = z.object({
+  matchId: z.string(),
+  model: matchWorkspaceModelSchema
+});
+
+export const seriesPlayerMapTrendSchema = z.object({
+  matchId: z.string(),
+  mapName: z.string(),
+  rivalhubRR: z.number().nonnegative(),
+  hltvRating: z.number().nonnegative(),
+  adr: z.number().nonnegative(),
+  kast: z.number().min(0).max(100)
+});
+
+export const seriesPlayerRowSchema = z.object({
+  playerKey: z.string(),
+  name: z.string(),
+  teamName: z.string(),
+  mapCount: z.number().int().positive(),
+  totalRounds: z.number().int().positive(),
+  kills: z.number().int().nonnegative(),
+  deaths: z.number().int().nonnegative(),
+  assists: z.number().int().nonnegative(),
+  adr: z.number().nonnegative(),
+  kast: z.number().min(0).max(100),
+  rivalhubRR: z.number().nonnegative(),
+  hltvRating: z.number().nonnegative(),
+  confidence: z.number().min(0).max(1),
+  perMap: z.array(seriesPlayerMapTrendSchema)
+});
+
+export const seriesSummarySchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/series-summary-0.1"),
+  mapCount: z.number().int().positive(),
+  maps: z.array(z.object({
+    matchId: z.string(),
+    mapName: z.string(),
+    scoreline: z.string(),
+    teamAName: z.string(),
+    teamBName: z.string(),
+    winnerName: z.string().nullable()
+  })),
+  teams: z.array(z.object({
+    teamKey: z.string(),
+    name: z.string(),
+    mapsWon: z.number().int().nonnegative()
+  })),
+  scoreboard: z.array(seriesPlayerRowSchema),
+  mvpCandidates: z.array(mvpCandidateSchema)
+});
+
+export type MvpCandidate = z.infer<typeof mvpCandidateSchema>;
+export type MvpRecommendation = z.infer<typeof mvpRecommendationSchema>;
+export type SeriesMatchInput = z.infer<typeof seriesMatchInputSchema>;
+export type SeriesPlayerMapTrend = z.infer<typeof seriesPlayerMapTrendSchema>;
+export type SeriesPlayerRow = z.infer<typeof seriesPlayerRowSchema>;
+export type SeriesSummary = z.infer<typeof seriesSummarySchema>;

package/src/team.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { leaderboardMetricKeySchema } from "./leaderboard.js";
+import { playerStyleAxisSchema } from "./player.js";
+
+export const teamRosterInputSchema = z.object({
+  teamKey: z.string(),
+  name: z.string(),
+  playerKeys: z.array(z.string()).min(1)
+});
+
+export const teamMemberSummarySchema = z.object({
+  playerKey: z.string(),
+  name: z.string(),
+  mapCount: z.number().int().positive(),
+  confidence: z.number().min(0).max(1),
+  metrics: z.record(leaderboardMetricKeySchema, z.number().nullable())
+});
+
+export const teamMetricLeaderSchema = z.object({
+  metric: z.enum(["rivalhubRR", "adr", "kast", "firstKillPer100"]),
+  label: z.string(),
+  playerKey: z.string(),
+  name: z.string(),
+  value: z.number()
+});
+
+export const teamRoleSpecialistSchema = playerStyleAxisSchema.extend({
+  playerKey: z.string(),
+  name: z.string()
+});
+
+export const teamCohortSummarySchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/team-summary-0.1"),
+  weightsVersion: z.string(),
+  teamKey: z.string(),
+  name: z.string(),
+  members: z.array(teamMemberSummarySchema).min(1),
+  coreMembers: z.array(teamMemberSummarySchema).min(1),
+  averages: z.object({
+    rivalhubRR: z.number().nonnegative(),
+    hltvRating: z.number().nonnegative(),
+    adr: z.number().nonnegative(),
+    kd: z.number().nullable(),
+    kast: z.number().min(0).max(100),
+    confidence: z.number().min(0).max(1)
+  }),
+  performance: z.object({
+    firstKills: z.number().int().nonnegative(),
+    firstDeaths: z.number().int().nonnegative(),
+    openingDuelWinRate: z.number().min(0).max(1).nullable(),
+    clutchAttempts: z.number().int().nonnegative(),
+    clutchWins: z.number().int().nonnegative(),
+    clutchWinRate: z.number().min(0).max(1).nullable()
+  }),
+  /** 队伍 PRISM：成员各轴百分位的简单平均，不重算 PRISM。 */
+  style: z.object({
+    axes: z.array(playerStyleAxisSchema)
+  }).nullable(),
+  leaders: z.array(teamMetricLeaderSchema),
+  roleComplementarity: z.object({
+    /** 成员主轴覆盖率：不同主轴数 / min(成员数, 8)，0–100。 */
+    coverageScore: z.number().min(0).max(100),
+    specialists: z.array(teamRoleSpecialistSchema),
+    weakAxes: z.array(playerStyleAxisSchema)
+  })
+});
+
+export type TeamRosterInput = z.infer<typeof teamRosterInputSchema>;
+export type TeamMemberSummary = z.infer<typeof teamMemberSummarySchema>;
+export type TeamMetricLeader = z.infer<typeof teamMetricLeaderSchema>;
+export type TeamRoleSpecialist = z.infer<typeof teamRoleSpecialistSchema>;
+export type TeamCohortSummary = z.infer<typeof teamCohortSummarySchema>;

package/src/upstream.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import {
+  sideSchema,
+  teamKeySchema,
+  economyTypeSchema,
+  teamEconomySchema,
+  vec3Schema,
+  playerRowSchema,
+  roundRowSchema,
+  killRowSchema,
+  damageRowSchema,
+  playerEconomyRowSchema,
+  playerStatsRowSchema,
+  blindRowSchema,
+  bombRowSchema,
+  grenadeRowSchema,
+  clutchRowSchema,
+  shotRowSchema,
+  positionRowSchema,
+  replaySchema,
+  replayRoundSchema,
+  replayPlayerTrackSchema,
+} from "cs2-demo-format";
+
+export {
+  SCHEMAS_BY_KEY,
+  blindRowSchema,
+  blindsSchema,
+  bombEventTypeSchema,
+  bombRowSchema,
+  bombsSchema,
+  clutchRowSchema,
+  clutchesSchema,
+  damageRowSchema,
+  damagesSchema,
+  economyTypeSchema,
+  endReasonSchema,
+  grenadeRowSchema,
+  grenadeTypeSchema,
+  grenadesSchema,
+  hitgroupSchema,
+  killRowSchema,
+  killsSchema,
+  manifestSchema,
+  matchSchema,
+  playerEconomiesSchema,
+  playerEconomyRowSchema,
+  playerRowSchema,
+  playersSchema,
+  playerStatsRowSchema,
+  playerStatsSchema,
+  positionRowSchema,
+  positionsSchema,
+  replaySchema,
+  replayPlayerTrackSchema,
+  replayRoundSchema,
+  roundRowSchema,
+  roundsSchema,
+  shotRowSchema,
+  shotsSchema,
+  sideSchema,
+  steamId64Schema,
+  teamEconomySchema,
+  teamEconomyTypeSchema,
+  teamKeySchema,
+  teamSummarySchema,
+  vec3Schema,
+} from "cs2-demo-format";
+
+export type Side = z.infer<typeof sideSchema>;
+export type TeamKey = z.infer<typeof teamKeySchema>;
+export type EconomyType = z.infer<typeof economyTypeSchema>;
+export type TeamEconomyType = z.infer<typeof teamEconomySchema>;
+export type Vec3 = z.infer<typeof vec3Schema>;
+
+export type PackagePlayer = z.infer<typeof playerRowSchema>;
+export type PackageRound = z.infer<typeof roundRowSchema>;
+export type PackageKill = z.infer<typeof killRowSchema>;
+export type PackageDamage = z.infer<typeof damageRowSchema>;
+export type PackagePlayerEconomy = z.infer<typeof playerEconomyRowSchema>;
+export type PackagePlayerStats = z.infer<typeof playerStatsRowSchema>;
+export type PackageBlind = z.infer<typeof blindRowSchema>;
+export type PackageBomb = z.infer<typeof bombRowSchema>;
+export type PackageGrenade = z.infer<typeof grenadeRowSchema>;
+export type PackageClutch = z.infer<typeof clutchRowSchema>;
+export type PackageShot = z.infer<typeof shotRowSchema>;
+export type PackagePosition = z.infer<typeof positionRowSchema>;
+export type Replay = z.infer<typeof replaySchema>;
+export type ReplayRound = z.infer<typeof replayRoundSchema>;
+export type ReplayPlayerTrack = z.infer<typeof replayPlayerTrackSchema>;