@cs2dak/contract 0.2.1 → 1.1.0

package/LICENSE

@@ -1,3 +1,10 @@
+Licensing note / 适用范围
+-------------------------
+The MIT License below applies to this repository EXCEPT apps/dak-studio/,
+which is licensed under the GNU AGPL-3.0-only (see apps/dak-studio/LICENSE).
+Ecosystem packages (@cs2dak/*, python exporter) are MIT; the DAK Studio
+product is AGPL. Third-party attributions: THIRD-PARTY-NOTICES.md.
+
 MIT License
 
 Copyright (c) 2026 Starfie1d

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@cs2dak/contract",
-  "version": "0.2.1",
+  "version": "1.1.0",
   "type": "module",
   "license": "MIT",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@rivalhub/rival-rating": "^0.1.0",
-    "cs2-demo-format": "^2.2.0",
+    "@rivalhub/rival-rating": "^0.3.0",
+    "cs2-demo-format": "^3.1.0",
     "zod": "^3.25.0"
   },
   "files": [

package/src/analysis.ts

@@ -0,0 +1,228 @@
+import type { RRResult, PrismResult } from "@rivalhub/rival-rating";
+import { z } from "zod";
+import { teamKeySchema, sideSchema, economyTypeSchema, teamEconomySchema, grenadeTypeSchema } from "cs2-demo-format";
+import { qaReportSchema } from "./qa.js";
+import { rrIndicatorsSchema } from "./scoring.js";
+
+export const playerRoundFactSchema = z.object({
+  roundNumber: z.number().int().positive(),
+  steamId64: z.string(),
+  name: z.string(),
+  teamKey: teamKeySchema,
+  side: sideSchema,
+  survived: z.boolean(),
+  kills: z.number().int().nonnegative(),
+  deaths: z.number().int().nonnegative(),
+  assists: z.number().int().nonnegative(),
+  damage: z.number().int().nonnegative(),
+  utilityDamage: z.number().int().nonnegative(),
+  flashAssists: z.number().int().nonnegative(),
+  tradeKills: z.number().int().nonnegative(),
+  tradedDeaths: z.number().int().nonnegative(),
+  openingDuel: z.enum(["none", "won", "lost"]),
+  kastTags: z.array(z.enum(["kill", "assist", "survive", "trade"])),
+  equipmentValue: z.number().int().nonnegative().nullable(),
+  economyType: economyTypeSchema.nullable()
+});
+
+export const playerIndicatorRowSchema = z.object({
+  steamId64: z.string(),
+  name: z.string(),
+  teamKey: teamKeySchema,
+  indicators: rrIndicatorsSchema,
+  rr: z.custom<RRResult>(),
+  rrPercentile: z.number().min(0).max(100),
+  prism: z.custom<PrismResult>().nullable()
+});
+
+export const playerScoreboardRowSchema = z.object({
+  steamId64: z.string(),
+  name: z.string(),
+  teamKey: teamKeySchema,
+  indicators: rrIndicatorsSchema,
+  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),
+  headshotPercent: z.number().min(0).max(100),
+  entryKills: z.number().int().nonnegative(),
+  tradeKills: z.number().int().nonnegative(),
+  awpKills: z.number().int().nonnegative(),
+  utilityDamage: z.number().int().nonnegative(),
+  combatDeathCount: z.number().int().nonnegative().nullable(),
+  bombDeathCount: z.number().int().nonnegative().nullable(),
+  wallbangKillCount: z.number().int().nonnegative().nullable(),
+  noScopeKillCount: z.number().int().nonnegative().nullable(),
+  throughSmokeKillCount: z.number().int().nonnegative().nullable(),
+  collateralKillCount: z.number().int().nonnegative().nullable(),
+  bombPlantCount: z.number().int().nonnegative().nullable(),
+  bombDefuseCount: z.number().int().nonnegative().nullable(),
+  confidence: z.number().min(0).max(1),
+  fieldAvailability: z.object({
+    playerStats: z.enum(["available", "missing"]),
+    economy: z.enum(["available", "missing"]),
+    rounds: z.enum(["available", "missing"]),
+    richKills: z.enum(["available", "partial", "missing"]),
+    damages: z.enum(["available", "missing"]),
+    bombs: z.enum(["available", "missing"])
+  }),
+  // rrBase（clamp 前的基础分）：被碾压方 KAST/KPR 低、死亡惩罚大时可为负，
+  // 不能强制非负，否则一边倒的真实比赛整场导入失败。最终 rr 才被 clamp 到非负。
+  ratingSeed: z.number(),
+  rr: z.number().nonnegative(),
+  rrPercentile: z.number().min(0).max(100),
+  /** RR v2 账户分。单场为 frozen pro baseline：1.00 = 职业基线。 */
+  accountRR: z.number().nonnegative(),
+  /** 锚定/clamp 前的原始账户分（调试用）。 */
+  accountRRRaw: z.number(),
+  /** Combat 击杀项的 context 乘子（1.0 = context 未生效 / 已降级）。 */
+  accountCombatContextFactor: z.number(),
+  /** 六账户对 RR 的加权贡献（解释面板用）。 */
+  accountBreakdown: z.object({
+    combat: z.number(),
+    trade: z.number(),
+    mapControl: z.number(),
+    clutch: z.number(),
+    objective: z.number(),
+    utility: z.number()
+  }),
+  /**
+   * Combat context 分桶的可用性。
+   * "available" = 采集到数据源（即使无相关样本，分桶为 0 也算 available）；
+   * "missing" = 数据源缺失（parser 未产出），乘子已降级为 1.0，前端应显示"未启用"。
+   */
+  accountContextStatus: z.object({
+    buyDelta: z.enum(["available", "missing"]),
+    manState: z.enum(["available", "missing"])
+  })
+});
+
+export const weaponKillRowSchema = z.object({
+  weapon: z.string(),
+  kills: z.number().int().nonnegative(),
+  headshotKills: z.number().int().nonnegative(),
+  tradeKills: z.number().int().nonnegative(),
+  noScopeKills: z.number().int().nonnegative(),
+  throughSmokeKills: z.number().int().nonnegative(),
+  wallbangKills: z.number().int().nonnegative(),
+  penetratedObjects: z.number().int().nonnegative()
+});
+
+export const playerWeaponHighlightFactsSchema = z.object({
+  steamId64: z.string(),
+  totalKills: z.number().int().nonnegative(),
+  weapons: z.array(weaponKillRowSchema),
+  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()
+  })
+});
+
+export const accountContextAvailabilitySchema = z.enum(["available", "partial", "missing"]);
+
+export const timelineEventSchema = z.object({
+  id: z.string(),
+  roundNumber: z.number().int().positive(),
+  tick: z.number().int().positive(),
+  timeSeconds: z.number().nonnegative(),
+  clockPhase: z.enum(["freeze", "round", "bomb", "round-end"]),
+  clockSeconds: z.number().nonnegative(),
+  clockLabel: z.string(),
+  type: z.enum(["kill", "bomb", "grenade", "round-end"]),
+  label: z.string(),
+  teamKey: teamKeySchema.nullable()
+});
+
+export const economyPointSchema = z.object({
+  roundNumber: z.number().int().positive(),
+  teamA: z.number().int().nonnegative(),
+  teamB: z.number().int().nonnegative(),
+  advantage: z.number().int(),
+  teamAEconomy: teamEconomySchema,
+  teamBEconomy: teamEconomySchema,
+  winnerTeamKey: teamKeySchema
+});
+
+export const heatmapPointSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  z: z.number(),
+  roundNumber: z.number().int().positive(),
+  teamKey: teamKeySchema.nullable(),
+  steamId64: z.string().nullable(),
+  side: sideSchema.nullable(),
+  kind: z.enum(["kill", "death", "grenade"]),
+  grenadeType: grenadeTypeSchema.nullable()
+});
+
+export const mapViewSchema = z.object({
+  name: z.string(),
+  radarImageUrl: z.string().nullable(),
+  /** 双层地图（de_nuke / de_vertigo）的下层底图；单层地图为 null。 */
+  lowerRadarImageUrl: z.string().nullable().optional().default(null),
+  calibrated: z.boolean()
+});
+
+export const analysisProvenanceSchema = z.object({
+  analysisVersion: z.string(),
+  sourceSchemaVersion: z.literal("cs2-demo-format/3.0"),
+  sourceDemoHash: z.string().nullable(),
+  exporter: z.object({ name: z.string(), version: z.string() }),
+  parser: z.object({ name: z.string(), version: z.string() }),
+  ratingVersions: z.object({
+    rr: z.string().nullable(),
+    valueAccounts: z.string().nullable()
+  })
+});
+
+export const analysisBundleSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/1.0"),
+  sourceSchemaVersion: z.literal("cs2-demo-format/3.0"),
+  provenance: analysisProvenanceSchema,
+  mapName: z.string(),
+  tickrate: z.number().int().positive(),
+  teams: z.object({
+    teamA: z.object({ name: z.string(), score: z.number().int().nonnegative() }),
+    teamB: z.object({ name: z.string(), score: z.number().int().nonnegative() })
+  }),
+  scoreboard: z.array(playerScoreboardRowSchema),
+  playerWeaponHighlights: z.array(playerWeaponHighlightFactsSchema),
+  playerIndicators: z.array(playerIndicatorRowSchema),
+  playerRoundFacts: z.array(playerRoundFactSchema),
+  timeline: z.array(timelineEventSchema),
+  economy: z.array(economyPointSchema),
+  heatmap: z.array(heatmapPointSchema),
+  qa: qaReportSchema
+});
+
+export const demoViewModelSchema = z.object({
+  title: z.string(),
+  subtitle: z.string(),
+  map: mapViewSchema,
+  scoreline: z.string(),
+  teams: analysisBundleSchema.shape.teams,
+  scoreboard: z.array(playerScoreboardRowSchema),
+  playerIndicators: z.array(playerIndicatorRowSchema),
+  playerRoundFacts: z.array(playerRoundFactSchema),
+  timeline: z.array(timelineEventSchema),
+  economy: z.array(economyPointSchema),
+  heatmap: z.array(heatmapPointSchema),
+  qa: qaReportSchema
+});
+
+export type PlayerRoundFact = z.infer<typeof playerRoundFactSchema>;
+export type PlayerIndicatorRow = z.infer<typeof playerIndicatorRowSchema>;
+export type PlayerScoreboardRow = z.infer<typeof playerScoreboardRowSchema>;
+export type WeaponKillRow = z.infer<typeof weaponKillRowSchema>;
+export type PlayerWeaponHighlightFacts = z.infer<typeof playerWeaponHighlightFactsSchema>;
+export type AccountContextAvailability = z.infer<typeof accountContextAvailabilitySchema>;
+export type TimelineEvent = z.infer<typeof timelineEventSchema>;
+export type EconomyPoint = z.infer<typeof economyPointSchema>;
+export type GrenadeType = z.infer<typeof grenadeTypeSchema>;
+export type HeatmapPoint = z.infer<typeof heatmapPointSchema>;
+export type AnalysisBundle = z.infer<typeof analysisBundleSchema>;
+export type AnalysisProvenance = z.infer<typeof analysisProvenanceSchema>;
+export type DemoViewModel = z.infer<typeof demoViewModelSchema>;

package/src/bracket.ts

@@ -0,0 +1,68 @@
+/**
+ * 赛事 bracket 的中性数据模型 —— 观看侧（从比赛结果推算）与制作器（从框架槽位）共用同一套
+ * 渲染。瑞士轮按战绩组（Buchholz）成列 + 晋级/淘汰终列；淘汰赛按晋级轮次成列。
+ */
+
+export interface BracketCell {
+  key: string;
+  teamA: string | null;
+  teamB: string | null;
+  scoreA: number | null;
+  scoreB: number | null;
+  winner: "A" | "B" | null;
+  date: string | null;
+  /** 观看侧：点开该场的 demo entry。 */
+  entryIds?: string[];
+  /** 制作器：待填槽位（点击附加 demo）。 */
+  empty?: boolean;
+}
+
+export interface SwissGroup {
+  /** 战绩组标签，如 "1-0"。 */
+  record: string;
+  matches: BracketCell[];
+  /** 制作器：该战绩组可继续添加比赛（携带 slot id）。 */
+  addSlotId?: string;
+}
+
+export interface SwissColumn {
+  round: number;
+  groups: SwissGroup[];
+}
+
+export interface SwissModel {
+  columns: SwissColumn[];
+  advanced: { team: string; record: string }[];
+  eliminated: { team: string; record: string }[];
+  winsTarget: number;
+  lossTarget: number;
+}
+
+export interface ElimColumn {
+  round: number;
+  label: string;
+  matches: BracketCell[];
+}
+
+/** 淘汰赛 bracket 中单个节点的元数据（双败 / GSL lane-aware 布局用）。 */
+export interface ElimNode {
+  id: string;
+  round: number;
+  lane: "winner" | "loser" | "grand" | "single";
+  label: string;
+  nextWinNodeId?: string | null;
+  nextLossNodeId?: string | null;
+}
+
+export interface ElimModel {
+  columns: ElimColumn[];
+  /**
+   * Lane-aware 节点元数据（可选）。**存在性决定渲染模式**：
+   * - 非空 → SVG lane-aware 布局（双败 / GSL），含晋级连线与 lane 分隔
+   * - undefined / [] → DOM 列布局（单败 / 旧资产 / 制作器），以 MatchBox 列展示
+   *
+   * 未来考虑改为显式 `renderMode?: "dom" | "svg-lane"` 以消除隐式联合类型。
+   */
+  nodes?: ElimNode[];
+}
+

package/src/cohort.ts

@@ -0,0 +1,60 @@
+import type { PrismResult } from "@rivalhub/rival-rating";
+import { z } from "zod";
+import { teamKeySchema } from "cs2-demo-format";
+import { accountContextAvailabilitySchema } from "./analysis.js";
+import { rrIndicatorsSchema } from "./scoring.js";
+import { playerWeaponHighlightFactsSchema } from "./analysis.js";
+
+export const seasonPlayerRowSchema = z.object({
+  playerKey: z.string(),
+  steamIds: z.array(z.string()),
+  primarySteamId64: z.string(),
+  externalUserId: z.string().nullable(),
+  name: z.string(),
+  teamKeys: z.array(teamKeySchema),
+  mapCount: z.number().int().positive(),
+  rrV1: z.number().nonnegative(),
+  rrV1Percentile: z.number().min(0).max(100),
+  indicators: rrIndicatorsSchema,
+  weaponHighlights: playerWeaponHighlightFactsSchema,
+  accountRR: z.number().nonnegative(),
+  accountRRRaw: z.number(),
+  accountBreakdown: z.object({
+    combat: z.number(),
+    trade: z.number(),
+    mapControl: z.number(),
+    clutch: z.number(),
+    objective: z.number(),
+    utility: z.number()
+  }),
+  accountContextStatus: z.object({
+    buyDelta: accountContextAvailabilitySchema,
+    manState: accountContextAvailabilitySchema
+  }),
+  prism: z.custom<PrismResult>().nullable(),
+  confidence: z.number().min(0).max(1),
+  perMatch: z.array(z.object({
+    matchId: z.string(),
+    steamId64: z.string(),
+    accountRR: z.number().nonnegative(),
+    rrV1: z.number().nonnegative()
+  }))
+});
+
+export const seasonCohortBundleSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/cohort-1.0"),
+  matchCount: z.number().int().nonnegative(),
+  players: z.array(seasonPlayerRowSchema),
+  weightsVersion: z.string(),
+  provenance: z.object({
+    cohortVersion: z.literal("cs2-demo-analysis-kit/cohort-1.0"),
+    sourceSchemaVersion: z.literal("cs2-demo-format/3.0"),
+    matches: z.array(z.object({
+      matchId: z.string(),
+      sourceDemoHash: z.string().nullable()
+    }))
+  })
+});
+
+export type SeasonPlayerRow = z.infer<typeof seasonPlayerRowSchema>;
+export type SeasonCohortBundle = z.infer<typeof seasonCohortBundleSchema>;