@cs2dak/presentation 1.0.0 → 2.0.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,19 +1,20 @@
 {
   "name": "@cs2dak/presentation",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@rivalhub/rival-rating": "^0.1.0",
-    "@cs2dak/contract": "1.0.0",
-    "@cs2dak/core": "1.0.0"
-  },
-  "devDependencies": {
-    "@cs2dak/cohort": "1.0.0"
+    "@rivalhub/rival-rating": "^0.3.0",
+    "@cs2dak/contract": "1.1.0",
+    "@cs2dak/cohort": "2.0.0",
+    "@cs2dak/maps": "1.0.0",
+    "@cs2dak/core": "2.0.0",
+    "@cs2dak/tournament": "1.0.0"
   },
+  "devDependencies": {},
   "files": [
     "src"
   ],

package/src/double-awp.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import type { TeamAwpRoundFact } from "@cs2dak/contract";
+import { buildDoubleAwpAnalyses } from "./double-awp.js";
+
+function row(roundNumber: number, overrides: Partial<TeamAwpRoundFact> = {}): TeamAwpRoundFact {
+  return {
+    analysisVersion: 6, matchId: `m${Math.ceil(roundNumber / 3)}`, mapName: roundNumber % 2 ? "de_nuke" : "de_inferno", roundNumber,
+    teamKey: "teamA", side: "ct", economyType: "full", opponentEconomyType: "full", scorePhase: "first_half", won: roundNumber % 2 === 0,
+    roundStartAwpPlayerIndices: [0, 1], doubleAwpActiveSeconds: 12, awpActiveSeconds: 28, awpShots: 4, awpKills: 2, awpDamage: null,
+    openingKills: 1, openingDeaths: 0,
+    availability: { replay: "available", nav: "available", callouts: "available", shots: "available" }, ...overrides,
+  };
+}
+
+describe("double AWP analysis", () => {
+  it("keeps CT qualified conditions, combinations and observable contribution fields", () => {
+    const model = buildDoubleAwpAnalyses(Array.from({ length: 6 }, (_, index) => row(index + 1)), { teamKeyFor: () => "Team", playerKeyFor: (_match, index) => `p${index}` })[0]!;
+    expect(model).toMatchObject({ teamKey: "Team", side: "ct", status: "ready", doubleAwpRoundCount: 6, qualifiedRoundCount: 6, openingKills: 6, awpKills: 12, awpDamage: null });
+    expect(model.combinations[0]).toEqual({ playerKeys: ["p0", "p1"], rounds: 6 });
+    expect(model.mapDistribution).toHaveLength(2);
+  });
+
+  it("does not merge T-side double AWP into CT output and excludes force rounds from the denominator", () => {
+    const models = buildDoubleAwpAnalyses([row(1), row(2, { side: "t" }), row(3, { economyType: "force" })], { teamKeyFor: () => "Team" });
+    expect(models).toHaveLength(2);
+    expect(models.find((model) => model.side === "ct")?.qualifiedRoundCount).toBe(1);
+    expect(models.find((model) => model.side === "t")?.doubleAwpRoundCount).toBe(1);
+  });
+});

package/src/double-awp.ts

@@ -0,0 +1,50 @@
+import { doubleAwpAnalysisSchema, type DoubleAwpAnalysis, type TeamAwpRoundFact } from "@cs2dak/contract";
+
+export interface DoubleAwpAnalysisOptions {
+  teamKeyFor?: (matchId: string, rawTeamKey: "teamA" | "teamB") => string;
+  playerKeyFor?: (matchId: string, playerIndex: number) => string;
+}
+
+function breakdown(values: string[]) {
+  const counts = new Map<string, number>();
+  for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1);
+  return [...counts.entries()].map(([key, rounds]) => ({ key, rounds })).sort((a, b) => b.rounds - a.rounds || a.key.localeCompare(b.key));
+}
+
+export function buildDoubleAwpAnalyses(rows: TeamAwpRoundFact[], options: DoubleAwpAnalysisOptions = {}): DoubleAwpAnalysis[] {
+  const groups = new Map<string, TeamAwpRoundFact[]>();
+  for (const row of rows) {
+    const teamKey = options.teamKeyFor?.(row.matchId, row.teamKey) ?? `${row.matchId}:${row.teamKey}`;
+    const key = `${teamKey}\t${row.side}`;
+    groups.set(key, [...(groups.get(key) ?? []), row]);
+  }
+  return [...groups.entries()].map(([key, group]) => {
+    const [teamKey, side] = key.split("\t") as [string, "t" | "ct"];
+    const qualified = group.filter((row) => row.economyType === "full");
+    const double = qualified.filter((row) => row.roundStartAwpPlayerIndices.length >= 2);
+    const comboCounts = new Map<string, { playerKeys: string[]; rounds: number }>();
+    for (const row of double) {
+      const playerKeys = row.roundStartAwpPlayerIndices.map((index) => options.playerKeyFor?.(row.matchId, index) ?? `${row.matchId}:player:${index}`).sort();
+      const comboKey = playerKeys.join("|");
+      const existing = comboCounts.get(comboKey) ?? { playerKeys, rounds: 0 };
+      existing.rounds += 1;
+      comboCounts.set(comboKey, existing);
+    }
+    const sumNullable = (pick: (row: TeamAwpRoundFact) => number | null): number | null => double.some((row) => pick(row) != null) ? double.reduce((sum, row) => sum + (pick(row) ?? 0), 0) : null;
+    const status = group.every((row) => row.availability.replay === "missing") ? "unknown" : qualified.length < 6 ? "insufficient" : "ready";
+    return doubleAwpAnalysisSchema.parse({
+      version: "cs2-demo-analysis-kit/double-awp-analysis-2.0", teamKey, side, status,
+      qualifiedRoundCount: qualified.length, doubleAwpRoundCount: double.length, eligibleRoundShare: qualified.length ? double.length / qualified.length : null,
+      combinations: [...comboCounts.values()].sort((a, b) => b.rounds - a.rounds || a.playerKeys.join("|").localeCompare(b.playerKeys.join("|"))),
+      mapDistribution: breakdown(double.map((row) => row.mapName)), scorePhaseDistribution: breakdown(double.map((row) => row.scorePhase)),
+      economyDistribution: breakdown(double.map((row) => row.economyType)), opponentEconomyDistribution: breakdown(double.map((row) => row.opponentEconomyType)),
+      wins: double.filter((row) => row.won).length, winRate: double.length ? double.filter((row) => row.won).length / double.length : null,
+      openingKills: double.reduce((sum, row) => sum + row.openingKills, 0), openingDeaths: double.reduce((sum, row) => sum + row.openingDeaths, 0),
+      roundStartAwpOwnerships: double.reduce((sum, row) => sum + row.roundStartAwpPlayerIndices.length, 0),
+      activeAwpSeconds: sumNullable((row) => row.awpActiveSeconds), doubleAwpActiveSeconds: sumNullable((row) => row.doubleAwpActiveSeconds), awpKills: sumNullable((row) => row.awpKills), awpDamage: sumNullable((row) => row.awpDamage),
+      evidence: double.slice(0, 8).map((row) => ({ matchId: row.matchId, roundNumber: row.roundNumber, reason: `${row.mapName} ${row.side.toUpperCase()} 双 AWP 长枪局`, role: "example" as const })),
+      basis: ["仅按逐回合 round-start AWP ownership、存活 active time 和有效生命伤害描述双 AWP 使用；CT/T 分开。"],
+      limitations: ["胜率和开局数据是条件统计，不表示双 AWP 导致结果。", ...(double.some((row) => row.awpDamage == null) ? ["当前 ZIP 缺少可用 damages 数据，AWP damage 保持 null。"] : [])],
+    });
+  }).sort((a, b) => a.teamKey.localeCompare(b.teamKey) || a.side.localeCompare(b.side));
+}

package/src/duel.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from "vitest";
+import type { DemoPackage, PackageDamage, PackageKill, PackageShots } from "@cs2dak/contract";
+import { duelInsightsModelSchema } from "@cs2dak/contract";
+import { buildDuelInsights, buildDuelInsightsFromFacts, extractDuelInsightsFacts } from "./duel.js";
+
+const A = "76561198000000001";
+const B = "76561198000000002";
+
+// Player indices matching pkg().players order
+const AI = 0;
+const BI = 1;
+
+/** Build columnar PackageShots from a flat shot list. Ticks are delta-encoded per track. */
+function buildShots(
+  shots: Array<{ tick: number; playerIndex: number; roundNumber?: number; weaponIndex?: number }>
+): PackageShots {
+  const groups = new Map<string, Array<{ tick: number; playerIndex: number; roundNumber: number; weaponIndex: number }>>();
+  for (const s of shots) {
+    const rn = s.roundNumber ?? 1;
+    const key = `${rn}:${s.playerIndex}`;
+    const arr = groups.get(key) ?? [];
+    arr.push({ tick: s.tick, playerIndex: s.playerIndex, roundNumber: rn, weaponIndex: s.weaponIndex ?? 0 });
+    groups.set(key, arr);
+  }
+  const tracks: PackageShots["tracks"] = [];
+  for (const items of groups.values()) {
+    const deltas: number[] = [];
+    let prev = 0;
+    for (const { tick } of items) { deltas.push(tick - prev); prev = tick; }
+    const n = items.length;
+    tracks.push({
+      roundNumber: items[0]!.roundNumber,
+      playerIndex: items[0]!.playerIndex,
+      tick: deltas,
+      weapon: items.map((s) => s.weaponIndex),
+      vx: Array<number>(n).fill(0),
+      vy: Array<number>(n).fill(0),
+      vz: Array<number>(n).fill(0),
+      yaw: Array<number>(n).fill(0),
+      pitch: Array<number>(n).fill(0),
+      x: Array<number>(n).fill(0),
+      y: Array<number>(n).fill(0),
+      z: Array<number>(n).fill(0),
+    });
+  }
+  return { meta: { coordScale: 1, angleScale: 10 }, weaponDict: ["ak47", "glock"], tracks };
+}
+
+function damage(row: { attackerIndex: number | null; victimIndex: number; tick: number } & Partial<PackageDamage>): PackageDamage {
+  return {
+    roundNumber: 1,
+    weapon: "ak47",
+    hitgroup: "head",
+    healthDamage: 100,
+    healthDamageRaw: 100,
+    armorDamage: 0,
+    victimHealthBefore: 100,
+    attackerPosition: { x: 0, y: 0, z: 0 },
+    victimPosition: { x: 100, y: 0, z: 0 },
+    ...row
+  } as PackageDamage;
+}
+
+function kill(row: { killerIndex: number | null; victimIndex: number; tick: number } & Partial<PackageKill>): PackageKill {
+  return {
+    roundNumber: 1,
+    assisterIndex: null,
+    flashAssisterIndex: null,
+    weapon: "ak47",
+    killerActiveWeapon: "ak47",
+    victimActiveWeapon: "ak47",
+    headshot: true,
+    flashAssist: false,
+    tradeKill: false,
+    tradeDeath: false,
+    throughSmoke: false,
+    noScope: false,
+    penetratedObjects: 0,
+    killerPosition: { x: 0, y: 0, z: 0 },
+    victimPosition: { x: 100, y: 0, z: 0 },
+    ...row
+  } as PackageKill;
+}
+
+function pkg(shots?: PackageShots): DemoPackage {
+  return {
+    manifest: {
+      schemaVersion: "cs2-demo-format/3.0",
+      exporter: { name: "test", version: "0" },
+      parser: { name: "test", version: "0" },
+      demo: { hash: null, sourceFileName: null },
+      mapName: "de_mirage",
+      tickrate: 64,
+      exportedAt: "2026-01-01T00:00:00Z",
+      files: {
+        match: "match.json",
+        players: "players.json",
+        rounds: "rounds.json",
+        playerStats: "player-stats.json",
+        playerEconomies: "player-economies.json",
+        kills: "kills.json",
+        damages: "damages.json",
+        blinds: "blinds.json",
+        bombs: "bombs.json",
+        grenades: "grenades.json",
+        clutches: "clutches.json"
+      }
+    },
+    match: {
+      mapName: "de_mirage",
+      tickrate: 64,
+      durationSeconds: 120,
+      serverName: null,
+      source: "test",
+      teamA: { teamKey: "teamA", name: "A Team", score: 1 },
+      teamB: { teamKey: "teamB", name: "B Team", score: 0 }
+    },
+    players: [
+      { steamId64: A, name: "Alpha", teamKey: "teamA" },
+      { steamId64: B, name: "Bravo", teamKey: "teamB" }
+    ],
+    rounds: [],
+    playerEconomies: [],
+    playerStats: [],
+    kills: [kill({ tick: 120, killerIndex: AI, victimIndex: BI })],
+    damages: [damage({ tick: 120, attackerIndex: AI, victimIndex: BI })],
+    blinds: [],
+    bombs: [],
+    grenades: [],
+    clutches: [],
+    shots
+  } as DemoPackage;
+}
+
+describe("buildDuelInsights", () => {
+  it("builds the same model from persisted duel facts", () => {
+    const inputs = [
+      { matchId: "m1", pkg: pkg(buildShots([{ tick: 100, playerIndex: AI }, { tick: 120, playerIndex: AI }])) },
+      { matchId: "m2", pkg: pkg(buildShots([{ tick: 100, playerIndex: AI }, { tick: 120, playerIndex: AI }])) }
+    ];
+
+    expect(buildDuelInsightsFromFacts(inputs.map((input) => extractDuelInsightsFacts(input)))).toEqual(
+      buildDuelInsights(inputs)
+    );
+  });
+
+  it("builds a schema-valid model with raw values and current-range percentile labels", () => {
+    const model = buildDuelInsights([{ matchId: "m1", pkg: pkg(buildShots([{ tick: 100, playerIndex: AI }, { tick: 120, playerIndex: AI }])) }]);
+    expect(() => duelInsightsModelSchema.parse(model)).not.toThrow();
+    expect(model.duelRows[0].killerName).toBe("Alpha");
+    expect(model.mechanicsRows[0].metrics.some((metric) => metric.percentileLabel?.includes("当前范围"))).toBe(true);
+    expect(JSON.stringify(model)).not.toContain("letterGrade");
+  });
+
+  it("hides unavailable mechanics metrics when shots are missing", () => {
+    const model = buildDuelInsights([{ matchId: "m1", pkg: pkg(undefined) }]);
+    expect(model.duelRows).toHaveLength(1);
+    expect(model.mechanicsRows).toHaveLength(0);
+  });
+
+  it("aggregates the same player+weapon across matches into a single tailored row", () => {
+    const withShots = () => pkg(buildShots([{ tick: 100, playerIndex: AI }, { tick: 120, playerIndex: AI }]));
+    const model = buildDuelInsights([
+      { matchId: "m1", pkg: withShots() },
+      { matchId: "m2", pkg: withShots() }
+    ]);
+    const akRows = model.mechanicsRows.filter((row) => row.steamId64 === A && row.weapon === "ak47");
+    expect(akRows).toHaveLength(1); // 两场的 AK 合并为一行，而非各出一行
+    expect(akRows[0]!.killCount).toBe(2);
+    // 场均击杀 = 2 杀 / 2 场
+    expect(akRows[0]!.metrics.find((metric) => metric.key === "killsPerMatch")?.value).toBe(2 / 2);
+    // 爆头率：两场都是爆头击杀
+    expect(akRows[0]!.metrics.find((metric) => metric.key === "headshot")?.value).toBe(100);
+    // 步枪类别展示扫射命中率，而狙击会隐藏击杀耗时/预瞄（此处验证步枪保留 sprayHit）
+    const keys = akRows[0]!.metrics.map((metric) => metric.key);
+    expect(keys).toContain("sprayHit");
+    expect(keys).toContain("headshot");
+  });
+
+  it("does not show one tap for weapons that cannot one-shot full-health targets", () => {
+    const demo = pkg(buildShots([{ tick: 100, playerIndex: AI, weaponIndex: 1 }, { tick: 120, playerIndex: AI, weaponIndex: 1 }]));
+    demo.kills = [kill({ tick: 120, killerIndex: AI, victimIndex: BI, weapon: "glock", killerActiveWeapon: "glock" })];
+    demo.damages = [damage({ tick: 120, attackerIndex: AI, victimIndex: BI, weapon: "glock" })];
+
+    const model = buildDuelInsights([{ matchId: "m1", pkg: demo }]);
+    const glock = model.mechanicsRows.find((row) => row.weapon === "glock")!;
+
+    expect(glock.metrics.map((metric) => metric.key)).not.toContain("oneTap");
+  });
+});

package/src/duel.ts

@@ -0,0 +1,359 @@
+import type { DemoPackage, DuelInsightsModel, DuelFinderRow, MechanicsMetric, OpeningDuelRow, PlayerMechanicsRow } from "@cs2dak/contract";
+import { duelInsightsModelSchema } from "@cs2dak/contract";
+import { deriveDuels, deriveOpeningDuels, derivePlayerMechanics, type PlayerMechanicsFact, type RateSample } from "@cs2dak/core";
+import type { TriangleBvh } from "@cs2dak/maps";
+
+export interface DuelInsightsInput {
+  matchId: string;
+  pkg: DemoPackage;
+}
+
+export interface DuelInsightsFacts {
+  matchId: string;
+  duelRows: DuelFinderRow[];
+  openingRows: OpeningDuelRow[];
+  mechanicsRows: PlayerMechanicsFact[];
+  teamNamesBySteamId: Record<string, string>;
+}
+
+export interface DuelInsightsOptions {
+  /** 按地图名提供 .tri BVH；提供后分类、反应时间、预瞄与首发可见性走静态 LOS 精确口径。 */
+  visibilityFor?: (mapName: string) => TriangleBvh | null;
+}
+
+const CLASSIFICATION_LABEL: Record<string, string> = {
+  contested_duel: "正面对枪击杀",
+  suppressed_kill: "先手压制击杀",
+  caught_off_guard: "无有效视野击杀"
+};
+
+function nameFor(pkg: DemoPackage, steamId64: string): string {
+  return pkg.players.find((player) => player.steamId64 === steamId64)?.name ?? steamId64;
+}
+
+/** CS2 标准回合时长（秒，freeze 结束后），用于回合剩余时间倒计时显示。 */
+const ROUND_DURATION = 115;
+
+/** 对枪发生时的回合剩余时间标签（"1:23"），无 freezeEnd 时为 null。 */
+function roundTimeLabelFor(input: DuelInsightsInput, fact: ReturnType<typeof deriveDuels>[number]): string | null {
+  const tickrate = input.pkg.match.tickrate || input.pkg.manifest.tickrate || 64;
+  const roundRow = input.pkg.rounds.find((r) => r.roundNumber === fact.roundNumber);
+  if (!roundRow || roundRow.freezeEndTick == null || tickrate <= 0) return null;
+  const elapsed = (fact.tick - roundRow.freezeEndTick) / tickrate;
+  const remaining = Math.max(0, ROUND_DURATION - elapsed);
+  const min = Math.floor(remaining / 60);
+  const sec = Math.round(remaining % 60);
+  return `${min}:${String(sec).padStart(2, "0")}`;
+}
+
+function duelRow(input: DuelInsightsInput, fact: ReturnType<typeof deriveDuels>[number]): DuelFinderRow {
+  return {
+    id: `${input.matchId}:${fact.id}`,
+    matchId: input.matchId,
+    mapName: input.pkg.match.mapName,
+    roundNumber: fact.roundNumber,
+    tick: fact.tick,
+    killerSteamId64: fact.killerSteamId64,
+    victimSteamId64: fact.victimSteamId64,
+    killerName: nameFor(input.pkg, fact.killerSteamId64),
+    victimName: nameFor(input.pkg, fact.victimSteamId64),
+    weapon: fact.weapon,
+    classification: fact.classification,
+    hpBucket: fact.hpBucket,
+    thirdParty: fact.thirdParty,
+    fullHealth: fact.fullHealth,
+    victimHealthBefore: fact.victimHealthBefore,
+    killerHealthBefore: fact.killerHealthBefore,
+    ttkMs: fact.ttkMs,
+    oneShotKill: fact.oneShotKill,
+    evidenceTicks: fact.evidenceTicks,
+    killerPosition: fact.killerPosition,
+    victimPosition: fact.victimPosition,
+    roundTimeLabel: roundTimeLabelFor(input, fact),
+    evidence: {
+      matchId: input.matchId,
+      roundNumber: fact.roundNumber,
+      tick: fact.tick,
+      reason: CLASSIFICATION_LABEL[fact.classification] ?? "对枪事件",
+      role: "example"
+    }
+  };
+}
+
+function openingRow(input: DuelInsightsInput, fact: ReturnType<typeof deriveDuels>[number]): OpeningDuelRow {
+  return {
+    ...duelRow(input, fact),
+    attackerCallout: null,
+    victimCallout: null
+  };
+}
+
+function round1(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+function median(values: number[]): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? round1((sorted[mid - 1]! + sorted[mid]!) / 2) : round1(sorted[mid]!);
+}
+
+function rate(successes: number, attempts: number): RateSample {
+  return { value: attempts > 0 ? round1((successes / attempts) * 100) : null, successes, attempts };
+}
+
+function sumRate(a: RateSample, b: RateSample): RateSample {
+  return rate(a.successes + b.successes, a.attempts + b.attempts);
+}
+
+function rankLabel(value: number | null, values: number[], higherIsBetter = true): string | null {
+  if (value == null || values.length < 1) return null;
+  const sorted = [...values].sort((a, b) => higherIsBetter ? b - a : a - b);
+  const rank = sorted.findIndex((candidate) => candidate === value) + 1;
+  return rank > 0 ? `当前范围前 ${Math.max(1, Math.round((rank / values.length) * 100))}%` : null;
+}
+
+// ── 武器分类 → 定制展示指标集（参考 5E「武器分析」：每类武器只展示有意义的特征）──
+export type MechanicsMetricKey = "firstShotHit" | "sprayHit" | "counterStrafe" | "oneTap" | "ttk" | "reaction" | "preaim" | "headshot" | "killsPerMatch";
+type MetricKey = MechanicsMetricKey;
+export type WeaponCategory = "rifle" | "sniper" | "pistol" | "submachine_gun" | "shotgun_lmg" | "other";
+
+const RIFLES = new Set(["ak47", "m4a1", "m4a4", "m4a1_silencer", "aug", "sg556", "sg553", "famas", "galilar", "galil"]);
+const SNIPERS = new Set(["awp", "ssg08", "scar20", "g3sg1"]);
+const PISTOLS = new Set(["deagle", "revolver", "glock", "usp_silencer", "usp", "hkp2000", "p2000", "p250", "fiveseven", "tec9", "cz75a", "cz75", "elite"]);
+const SUBMACHINE_GUNS = new Set(["mp9", "mp7", "mp5sd", "ump45", "p90", "bizon", "mac10"]);
+const SHOTGUNS_LMG = new Set(["nova", "xm1014", "mag7", "sawedoff", "m249", "negev"]);
+const ONE_TAP_CAPABLE = new Set(["ak47", "sg556", "sg553", "deagle", "revolver", "awp", "ssg08", "scar20", "g3sg1"]);
+
+export function weaponCategory(weapon: string): WeaponCategory {
+  const w = weapon.toLowerCase();
+  if (RIFLES.has(w)) return "rifle";
+  if (SNIPERS.has(w)) return "sniper";
+  if (PISTOLS.has(w)) return "pistol";
+  if (SUBMACHINE_GUNS.has(w)) return "submachine_gun";
+  if (SHOTGUNS_LMG.has(w)) return "shotgun_lmg";
+  return "other";
+}
+
+// 狙击：去击杀耗时(≈0)/扫射/one tap(恒满)/预瞄(多为架枪)；手枪：去扫射；冲锋枪：弱化预瞄。
+export const CATEGORY_METRICS: Record<WeaponCategory, MetricKey[]> = {
+  rifle: ["firstShotHit", "sprayHit", "counterStrafe", "ttk", "oneTap", "reaction", "preaim", "headshot", "killsPerMatch"],
+  sniper: ["firstShotHit", "counterStrafe", "reaction", "headshot", "killsPerMatch"],
+  pistol: ["firstShotHit", "counterStrafe", "ttk", "oneTap", "reaction", "headshot", "killsPerMatch"],
+  submachine_gun: ["firstShotHit", "sprayHit", "counterStrafe", "ttk", "reaction", "headshot", "killsPerMatch"],
+  shotgun_lmg: ["firstShotHit", "counterStrafe", "ttk", "reaction", "headshot", "killsPerMatch"],
+  other: ["firstShotHit", "counterStrafe", "reaction", "headshot", "killsPerMatch"]
+};
+
+export function mechanicsMetricsForWeapon(weapon: string): MetricKey[] {
+  const category = weaponCategory(weapon);
+  const keys = CATEGORY_METRICS[category];
+  if (ONE_TAP_CAPABLE.has(weapon.toLowerCase())) return keys;
+  return keys.filter((key) => key !== "oneTap");
+}
+
+const LOWER_IS_BETTER = new Set<MetricKey>(["ttk", "reaction", "preaim"]);
+
+/** 跨场按 (steamId64, weapon) 聚合后的枪法事实。 */
+interface AggMechanics {
+  steamId64: string;
+  playerName: string;
+  teamName: string;
+  weapon: string;
+  killCount: number;
+  cleanKillCount: number;
+  headshotKills: number;
+  cleanHeadshotKills: number;
+  shotCount: number;
+  burstCount: number;
+  firstShotHit: RateSample;
+  sprayHit: RateSample | null;
+  counterStrafe: RateSample;
+  oneTap: RateSample;
+  ttkSamples: number[];
+  reactionSamples: number[];
+  preaimSamples: number[];
+  burstLengthBuckets: PlayerMechanicsFact["burstLengthBuckets"];
+}
+
+/** 取某指标的标量值（用于该 agg 展示 + 跨 agg 百分位）。 */
+function metricValueOf(agg: AggMechanics, key: MetricKey, matchesPlayed: number): number | null {
+  switch (key) {
+    case "firstShotHit": return agg.firstShotHit.value;
+    case "sprayHit": return agg.sprayHit?.value ?? null;
+    case "counterStrafe": return agg.counterStrafe.value;
+    case "oneTap": return agg.oneTap.value;
+    case "ttk": return median(agg.ttkSamples);
+    case "reaction": return median(agg.reactionSamples);
+    case "preaim": return median(agg.preaimSamples);
+    case "headshot": return agg.cleanKillCount > 0 ? round1((agg.cleanHeadshotKills / agg.cleanKillCount) * 100) : null;
+    case "killsPerMatch": return matchesPlayed > 0 ? round1(agg.killCount / matchesPlayed) : null;
+  }
+}
+
+function buildMetric(key: MetricKey, agg: AggMechanics, allAggs: AggMechanics[], matchesByPlayer: Map<string, number>): MechanicsMetric {
+  const matchesPlayed = matchesByPlayer.get(agg.steamId64) ?? 1;
+  const value = metricValueOf(agg, key, matchesPlayed);
+  const peers = allAggs
+    .map((other) => metricValueOf(other, key, matchesByPlayer.get(other.steamId64) ?? 1))
+    .filter((candidate): candidate is number => candidate != null);
+  const percentileLabel = rankLabel(value, peers, !LOWER_IS_BETTER.has(key));
+  const base = { key, value, percentileLabel };
+  switch (key) {
+    case "firstShotHit": return { ...base, label: "首发命中率", unit: "%", successes: agg.firstShotHit.successes, attempts: agg.firstShotHit.attempts };
+    case "sprayHit": return { ...base, label: "扫射命中率", unit: "%", successes: agg.sprayHit?.successes, attempts: agg.sprayHit?.attempts };
+    case "counterStrafe": return { ...base, label: "急停成功率", unit: "%", successes: agg.counterStrafe.successes, attempts: agg.counterStrafe.attempts };
+    case "oneTap": return { ...base, label: "one tap 率", unit: "%", successes: agg.oneTap.successes, attempts: agg.oneTap.attempts };
+    case "ttk": return { ...base, label: "击杀耗时", unit: "ms", sampleSize: agg.ttkSamples.length };
+    case "reaction": return { ...base, label: "反应时间", unit: "ms", sampleSize: agg.reactionSamples.length };
+    case "preaim": {
+      const withinFive = agg.preaimSamples.filter((value) => value <= 5).length;
+      return {
+        ...base,
+        label: "预瞄误差",
+        unit: "°",
+        sampleSize: agg.preaimSamples.length,
+        detail: agg.preaimSamples.length > 0 ? `${withinFive}/${agg.preaimSamples.length} ≤5°` : undefined
+      };
+    }
+    case "headshot": return { ...base, label: "爆头率", unit: "%", successes: agg.cleanHeadshotKills, attempts: agg.cleanKillCount };
+    case "killsPerMatch": return { ...base, label: "场均击杀", unit: "", detail: `${agg.killCount} 杀 / ${matchesPlayed} 场` };
+  }
+}
+
+/**
+ * 单条武器画像：按武器类别只展示有意义的指标。命中率类带分子/分母，中位类带样本数；
+ * 击杀耗时 / 反应时间 / 预瞄误差 越低越好。
+ */
+function mechanicsRow(agg: AggMechanics, allAggs: AggMechanics[], matchesByPlayer: Map<string, number>): PlayerMechanicsRow {
+  const metrics: MechanicsMetric[] = mechanicsMetricsForWeapon(agg.weapon).map((key) => buildMetric(key, agg, allAggs, matchesByPlayer));
+  const buckets = agg.burstLengthBuckets;
+  const total = buckets.single + buckets.short + buckets.medium + buckets.long;
+  return {
+    steamId64: agg.steamId64,
+    playerName: agg.playerName,
+    teamName: agg.teamName,
+    weapon: agg.weapon,
+    killCount: agg.killCount,
+    shotCount: agg.shotCount,
+    burstCount: agg.burstCount,
+    metrics,
+    burstLengthBuckets: buckets,
+    firingPatternRatio: total > 0
+      ? { tap: round1((buckets.single / total) * 100), burst: round1(((buckets.short + buckets.medium) / total) * 100), spray: round1((buckets.long / total) * 100) }
+      : { tap: 0, burst: 0, spray: 0 }
+  };
+}
+
+export function duelClassificationLabel(classification: string): string {
+  return CLASSIFICATION_LABEL[classification] ?? classification;
+}
+
+export function extractDuelInsightsFacts(input: DuelInsightsInput, options: DuelInsightsOptions = {}): DuelInsightsFacts {
+  const visibility = options.visibilityFor?.(input.pkg.match.mapName) ?? null;
+  const teamNames = {
+    teamA: input.pkg.match.teamA.name ?? "Team A",
+    teamB: input.pkg.match.teamB.name ?? "Team B"
+  };
+  return {
+    matchId: input.matchId,
+    duelRows: deriveDuels(input.pkg, { visibility }).map((fact) => duelRow(input, fact)),
+    openingRows: deriveOpeningDuels(input.pkg, { visibility }).map((fact) => openingRow(input, fact)),
+    mechanicsRows: derivePlayerMechanics(input.pkg, { visibility }),
+    teamNamesBySteamId: Object.fromEntries(
+      input.pkg.players.map((player) => [player.steamId64, teamNames[player.teamKey]])
+    )
+  };
+}
+
+export function buildDuelInsightsFromFacts(facts: DuelInsightsFacts[]): DuelInsightsModel {
+  const duelRows: DuelFinderRow[] = [];
+  const openingRows: OpeningDuelRow[] = [];
+  // 跨场按 (steamId64, weapon) 聚合，避免同一选手同把武器在多场各出一行。
+  const aggByKey = new Map<string, AggMechanics>();
+  const matchesByPlayer = new Map<string, Set<string>>();
+
+  for (const input of facts) {
+    duelRows.push(...input.duelRows);
+    openingRows.push(...input.openingRows);
+    for (const fact of input.mechanicsRows) {
+      const playerMatches = matchesByPlayer.get(fact.steamId64) ?? new Set<string>();
+      playerMatches.add(input.matchId);
+      matchesByPlayer.set(fact.steamId64, playerMatches);
+      const key = `${fact.steamId64}:${fact.weapon}`;
+      const teamName = input.teamNamesBySteamId[fact.steamId64] ?? "";
+      const prev = aggByKey.get(key);
+      if (!prev) {
+        aggByKey.set(key, {
+          steamId64: fact.steamId64,
+          playerName: fact.playerName,
+          teamName,
+          weapon: fact.weapon,
+          killCount: fact.killCount,
+          cleanKillCount: fact.cleanKillCount,
+          headshotKills: fact.headshotKills,
+          cleanHeadshotKills: fact.cleanHeadshotKills,
+          shotCount: fact.shotCount,
+          burstCount: fact.burstCount,
+          firstShotHit: fact.firstShotHit,
+          sprayHit: fact.sprayHit,
+          counterStrafe: fact.counterStrafe,
+          oneTap: fact.oneTap,
+          ttkSamples: [...fact.ttkSamplesMs],
+          reactionSamples: [...fact.reactionSamplesMs],
+          preaimSamples: [...fact.preaimSamplesDeg],
+          burstLengthBuckets: { ...fact.burstLengthBuckets }
+        });
+      } else {
+        prev.teamName = teamName;
+        prev.killCount += fact.killCount;
+        prev.cleanKillCount += fact.cleanKillCount;
+        prev.headshotKills += fact.headshotKills;
+        prev.cleanHeadshotKills += fact.cleanHeadshotKills;
+        prev.shotCount += fact.shotCount;
+        prev.burstCount += fact.burstCount;
+        prev.firstShotHit = sumRate(prev.firstShotHit, fact.firstShotHit);
+        prev.sprayHit = fact.sprayHit == null ? prev.sprayHit : prev.sprayHit == null ? fact.sprayHit : sumRate(prev.sprayHit, fact.sprayHit);
+        prev.counterStrafe = sumRate(prev.counterStrafe, fact.counterStrafe);
+        prev.oneTap = sumRate(prev.oneTap, fact.oneTap);
+        prev.ttkSamples.push(...fact.ttkSamplesMs);
+        prev.reactionSamples.push(...fact.reactionSamplesMs);
+        prev.preaimSamples.push(...fact.preaimSamplesDeg);
+        prev.burstLengthBuckets.single += fact.burstLengthBuckets.single;
+        prev.burstLengthBuckets.short += fact.burstLengthBuckets.short;
+        prev.burstLengthBuckets.medium += fact.burstLengthBuckets.medium;
+        prev.burstLengthBuckets.long += fact.burstLengthBuckets.long;
+      }
+    }
+  }
+
+  const aggs = [...aggByKey.values()];
+  const matchCountByPlayer = new Map([...matchesByPlayer].map(([steamId64, set]) => [steamId64, set.size]));
+  const mechanicsRows = aggs
+    .map((agg) => mechanicsRow(agg, aggs, matchCountByPlayer))
+    .sort((a, b) => b.killCount - a.killCount || b.shotCount - a.shotCount || a.playerName.localeCompare(b.playerName));
+
+  return duelInsightsModelSchema.parse({
+    version: "cs2-demo-analysis-kit/duel-insights-0.1",
+    matchCount: facts.length,
+    duelRows,
+    openingRows,
+    mechanicsRows,
+    notes: [
+      "枪法质量指标只看干净交火：排除第三方伤害、穿烟击杀和穿墙击杀；标题击杀数仍保留真实武器产出。",
+      "首发命中率只统计干净交火开火段（造成敌方伤害，或首发开枪时视野锥+LOS 内有活敌）的第一发，排除打门/预开枪。",
+      "扫射命中率仅对干净全自动武器、长度≥5 的开火段从第 4 发起统计；手枪/狙击/霰弹显示 —。",
+      "急停成功率为干净「移动后停稳」口径：用 duels 连续轨迹判断开枪前 200ms 是否在移动，只把移动样本计入分母；开枪时速度低于该武器判定用最大移动速度约 34% 的停稳阈值记为成功。ZIP 无按键输入与开镜状态；AWP 按常见开镜开枪口径取 100u/s，其他开镜武器暂按基础移速口径展示。",
+      "one tap 率仅对可一枪满血终结的武器展示，分母为干净满血(100HP)击杀。",
+      "击杀耗时取干净满血击杀中，击杀开火段第一枪到击杀的中位耗时，AK 一枪头可接近 0ms。",
+      "反应时间从干净击杀者首发反向找当前连续可见段起点（需 hp>0、未被闪、视野锥内、静态LOS通透、无烟）；首发即击杀时用上一帧仍存活的可见状态；窗口首帧已可见、预开枪、可见>1s 的跟踪样本均剔除。",
+      "预瞄误差取干净可见段起点前 1~3 帧准星与目标的三维(yaw+pitch)夹角中位，并给出 ≤5° 比例。",
+      "百分位标签基于当前聚合范围；未接入固定联赛基线时不输出 A/B/C。"
+    ]
+  });
+}
+
+export function buildDuelInsights(inputs: DuelInsightsInput[], options: DuelInsightsOptions = {}): DuelInsightsModel {
+  return buildDuelInsightsFromFacts(inputs.map((input) => extractDuelInsightsFacts(input, options)));
+}