@cs2dak/presentation 1.0.0 → 2.0.0

package/src/findings.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import type { DuelFinderRow } from "@cs2dak/contract";
+import type { TacticalCluster } from "@cs2dak/cohort";
+import {
+  buildMistakeFindings,
+  findingFromDuel,
+  findingFromTacticalCluster,
+  findingFromUtilityDamage,
+} from "./findings.js";
+
+const evidence = { matchId: "m1", roundNumber: 12, tick: 128, reason: "长枪局首死", role: "example" as const };
+
+describe("AnalysisFinding adapters", () => {
+  it("only turns evidence-backed mistake rules into system findings", () => {
+    const findings = buildMistakeFindings({
+      lowBuyFirstDeaths: { count: 0, attempts: 3, evidence: [] },
+      fullBuyFirstDeaths: { count: 3, attempts: 9, evidence: [{ ...evidence, detail: "长枪局首死" }] },
+      antiEcoFirstDeaths: { count: 1, attempts: 2, evidence: [] },
+      deathTiming: { early: 0, mid: 0, late: 0, total: 0 },
+      clutchLosses: { count: 0, evidence: [] },
+    }, { id: "self", label: "FalleN" });
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      key: "mistake:full-buy-first-death:self",
+      origin: "system",
+      sample: { numerator: 3, denominator: 9 },
+      evidence: [evidence],
+    });
+    expect(findings[0]?.limitations[0]).toContain("不");
+  });
+
+  it("preserves concrete duel and utility evidence with a reason", () => {
+    const duel = {
+      id: "m1:k1", matchId: "m1", mapName: "de_inferno", roundNumber: 12, tick: 128,
+      killerSteamId64: "a", victimSteamId64: "b", killerName: "FalleN", victimName: "ropz", weapon: "ak47",
+      classification: "contested_duel", hpBucket: "full_hp", thirdParty: false, fullHealth: true,
+      victimHealthBefore: 100, killerHealthBefore: 100, ttkMs: 320, oneShotKill: false,
+      evidenceTicks: { engagementStartTick: 64, engagementEndTick: 128, killerFirstShotTick: 100, victimResponseTick: 110, killTick: 128 },
+      killerPosition: null, victimPosition: null, roundTimeLabel: "1:20", evidence,
+    } satisfies DuelFinderRow;
+    const utility = { ...evidence, kind: "he" as const, playerName: "FalleN", victimCount: 2, damage: 86 };
+
+    expect(findingFromDuel(duel).evidence).toEqual([evidence]);
+    expect(findingFromUtilityDamage(utility).evidence).toEqual([utility]);
+  });
+
+  it("keeps tactical clusters within their observed opening-pattern boundary", () => {
+    const cluster = {
+      id: "cluster-1", mapName: "de_nuke", side: "t", economyEntry: "gun", teamIdentity: "furia", teamName: "FURIA",
+      opponentNames: ["Spirit"], opponentIdentities: ["spirit"], openingIntent: { regionCounts: { a: 2, mid: 1, b: 2, unknown: 0 }, spread: "split" },
+      positionGroupCounts: {}, primaryCategory: "均衡控图", openingSignature: "test",
+      entryEvidence: { coveredRounds: 3, totalRounds: 4, coveragePercent: 75, routes: [] }, roundCount: 4,
+      winRatePercent: 50, plantRatePercent: 50,
+      rounds: [{ matchId: "m1", roundNumber: 5, teamKey: "teamA", won: true, economy: "full", planted: true }],
+    } satisfies TacticalCluster;
+    const finding = findingFromTacticalCluster(cluster);
+
+    expect(finding?.evidence[0]).toMatchObject({ matchId: "m1", roundNumber: 5, role: "example" });
+    expect(finding?.limitations[0]).toContain("不识别完整中期战术");
+  });
+});

package/src/findings.ts

@@ -0,0 +1,174 @@
+import type { DuelFinderRow, EvidenceRef } from "@cs2dak/contract";
+import type { TacticalCluster } from "@cs2dak/cohort";
+import { duelClassificationLabel } from "./duel.js";
+import type {
+  EnemyFlashIncident,
+  FirstDeathStat,
+  MistakeReview,
+  UtilityDamageEvidence,
+} from "./insights.js";
+
+export type FindingOrigin = "system" | "user";
+
+/** 产品中立的、可交给证据查看器或行动面的系统结论。 */
+export interface AnalysisFinding {
+  /** capability 内稳定的 key，不承担跨产品持久化 identity。 */
+  key: string;
+  capability: "mistake-review" | "duel" | "utility" | "tactical";
+  producerVersion: string;
+  origin: FindingOrigin;
+  title: string;
+  statement: string;
+  subject: { id?: string; label: string };
+  relationship?: string;
+  sample: {
+    label: string;
+    numerator?: number;
+    denominator?: number;
+    coverage?: string;
+  };
+  baseline: string | null;
+  evidence: EvidenceRef[];
+  basis: string[];
+  limitations: string[];
+}
+
+export interface FindingSubject {
+  id?: string;
+  label: string;
+}
+
+const PRODUCER_VERSION = "cs2-demo-analysis-kit/finding-0.1";
+
+function systemFinding(
+  finding: Omit<AnalysisFinding, "origin" | "producerVersion">
+): AnalysisFinding {
+  return { ...finding, origin: "system", producerVersion: PRODUCER_VERSION };
+}
+
+function mistakeFinding(
+  key: string,
+  title: string,
+  statementLabel: string,
+  stat: FirstDeathStat,
+  subject: FindingSubject,
+): AnalysisFinding | null {
+  if (stat.count === 0 || stat.evidence.length === 0) return null;
+  return systemFinding({
+    key: `mistake:${key}:${subject.id ?? subject.label}`,
+    capability: "mistake-review",
+    title,
+    statement: `${subject.label} 在 ${stat.attempts} 个${statementLabel}中有 ${stat.count} 次首死。`,
+    subject,
+    sample: { label: statementLabel, numerator: stat.count, denominator: stat.attempts },
+    baseline: null,
+    evidence: stat.evidence,
+    basis: ["按回合首个死亡事件统计。"],
+    limitations: ["该规则只定位首死，不能据此判断首死成因或自动给出训练处方。"],
+  });
+}
+
+/** 只转换已有稳定规则和证据的 Mistake Review；没有证据的统计不形成系统 Finding。 */
+export function buildMistakeFindings(
+  mistakes: MistakeReview,
+  subject: FindingSubject,
+): AnalysisFinding[] {
+  const firstDeath = [
+    mistakeFinding("full-buy-first-death", "优先复盘：长枪局首死", "长枪局", mistakes.fullBuyFirstDeaths, subject),
+    mistakeFinding("anti-eco-first-death", "优先复盘：反 ECO 首死", "对手 ECO/半起局", mistakes.antiEcoFirstDeaths, subject),
+    mistakeFinding("low-buy-first-death", "优先复盘：劣势经济首死", "劣势经济局", mistakes.lowBuyFirstDeaths, subject),
+  ].filter((finding): finding is AnalysisFinding => finding != null);
+
+  if (mistakes.clutchLosses.count > 0 && mistakes.clutchLosses.evidence.length > 0) {
+    firstDeath.push(systemFinding({
+      key: `mistake:clutch-loss:${subject.id ?? subject.label}`,
+      capability: "mistake-review",
+      title: "优先复盘：残局失利",
+      statement: `${subject.label} 有 ${mistakes.clutchLosses.count} 次已记录的残局失利。`,
+      subject,
+      sample: { label: "残局失利", numerator: mistakes.clutchLosses.count },
+      baseline: null,
+      evidence: mistakes.clutchLosses.evidence,
+      basis: ["按导出的残局事实统计。"],
+      limitations: ["该规则不判断残局决策、对手配置或失利成因。"],
+    }));
+  }
+  return firstDeath;
+}
+
+/** 单条对枪事实可作为有明确回合证据的 Finding，不把分类扩展为因果结论。 */
+export function findingFromDuel(row: DuelFinderRow): AnalysisFinding {
+  const label = duelClassificationLabel(row.classification);
+  return systemFinding({
+    key: `duel:${row.id}`,
+    capability: "duel",
+    title: label,
+    statement: `${row.killerName} 在 ${row.mapName} R${row.roundNumber} 使用 ${row.weapon} 击杀 ${row.victimName}。`,
+    subject: { id: row.killerSteamId64, label: row.killerName },
+    relationship: `${row.killerName} 对 ${row.victimName}`,
+    sample: { label: "单次对枪", numerator: 1, denominator: 1 },
+    baseline: null,
+    evidence: [row.evidence],
+    basis: ["使用已有对枪分类与击杀事实。"],
+    limitations: ["单条对枪仅用于复核具体交战，不代表长期机制画像或因果判断。"],
+  });
+}
+
+export function findingFromUtilityDamage(row: UtilityDamageEvidence): AnalysisFinding {
+  const label = row.kind === "he" ? "HE 手雷" : "火焰";
+  return systemFinding({
+    key: `utility:${row.kind}:${row.matchId}:${row.roundNumber}:${row.tick ?? 0}:${row.playerId ?? row.playerName}`,
+    capability: "utility",
+    title: `${label}伤害证据`,
+    statement: `${row.playerName} 在 R${row.roundNumber} 用${label}对 ${row.victimCount} 人造成 ${row.damage} 点伤害。`,
+    subject: { id: row.playerId, label: row.playerName },
+    sample: { label: "单次道具伤害事件", numerator: row.damage },
+    baseline: null,
+    evidence: [row],
+    basis: ["使用导出的伤害事件聚合。"],
+    limitations: ["伤害事件不证明该道具导致了回合胜负，也不构成最佳点位或战术建议。"],
+  });
+}
+
+export function findingFromUtilityFlash(row: EnemyFlashIncident & { playerId?: string; playerName: string }): AnalysisFinding {
+  return systemFinding({
+    key: `utility:flash:${row.matchId}:${row.roundNumber}:${row.tick ?? 0}:${row.playerId ?? row.playerName}`,
+    capability: "utility",
+    title: "闪光贡献证据",
+    statement: `${row.playerName} 在 R${row.roundNumber} 致盲 ${row.victimCount} 名敌方，共 ${row.enemySeconds.toFixed(1)} 秒。`,
+    subject: { id: row.playerId, label: row.playerName },
+    sample: { label: "单颗闪光事件", numerator: row.enemySeconds },
+    baseline: null,
+    evidence: [row],
+    basis: ["按同一闪光事件归并敌方致盲秒数。"],
+    limitations: ["致盲时长不证明这颗闪光导致了击杀或回合胜负。"],
+  });
+}
+
+/** Tactical Cluster 只陈述开局/进点模式与代表回合，不推断完整战术意图或最佳反制。 */
+export function findingFromTacticalCluster(cluster: TacticalCluster): AnalysisFinding | null {
+  const representative = cluster.rounds[0];
+  if (!representative) return null;
+  const sample = `${cluster.mapName} ${cluster.side.toUpperCase()} ${cluster.economyEntry}`;
+  return systemFinding({
+    key: `tactical:${cluster.id}`,
+    capability: "tactical",
+    title: "开局模式证据",
+    statement: `${cluster.teamName} 在 ${sample} 样本中出现 ${cluster.roundCount} 回合相同开局结构。`,
+    subject: { id: cluster.teamIdentity, label: cluster.teamName },
+    sample: {
+      label: sample,
+      numerator: cluster.roundCount,
+      coverage: `${cluster.entryEvidence.coveredRounds}/${cluster.entryEvidence.totalRounds} 回合有真实进点入口证据`,
+    },
+    baseline: null,
+    evidence: [{
+      matchId: representative.matchId,
+      roundNumber: representative.roundNumber,
+      reason: "该回合是此开局结构的代表样本",
+      role: "example",
+    }],
+    basis: ["按默认位开局结构与真实进点事实聚类。"],
+    limitations: ["该聚类不识别完整中期战术、佯攻、转点意图或最佳反制。"],
+  });
+}

package/src/index.test.ts

@@ -4,16 +4,49 @@ import { fileURLToPath } from "node:url";
 import { analyzeDemoPackage, loadDemoPackageFromZip } from "@cs2dak/core";
 import { buildDemoViewModel, buildMatchWorkspaceModel } from "./index";
 
+const fixturePath = fileURLToPath(new URL("../../../fixtures/input/sample-2026-05-17_de_ancient_Team_Spirit_13-10_Team_Falcons.zip", import.meta.url));
+const workspaceFixture = (async () => {
+  const pkg = await loadDemoPackageFromZip(await readFile(fixturePath));
+  return {
+    pkg,
+    view: buildDemoViewModel(analyzeDemoPackage(pkg)),
+    workspace: buildMatchWorkspaceModel(pkg)
+  };
+})();
+
 describe("@cs2dak/presentation", () => {
   it("builds view and workspace models from canonical core analysis", async () => {
-    const zip = await readFile(fileURLToPath(new URL("../../../fixtures/input/cs2dak-sanitized-de_ancient.zip", import.meta.url)));
-    const pkg = await loadDemoPackageFromZip(zip);
-    const view = buildDemoViewModel(analyzeDemoPackage(pkg));
-    const workspace = buildMatchWorkspaceModel(pkg);
-
-    expect(view.scoreline).toBe("3:13");
-    expect(workspace.title).toBe("她还爱我对不 队 vs 車一进一宝贝队");
-    expect(workspace.rounds).toHaveLength(16);
+    const { view, workspace } = await workspaceFixture;
+
+    expect(view.scoreline).toBe("13:10");
+    expect(workspace.title).toBe("Team Spirit vs Team Falcons");
+    expect(workspace.rounds).toHaveLength(23);
     expect(workspace.replay.available).toBe(true);
   });
+
+  it("uses round-persistent loadout facts for replay weapons and utility", async () => {
+    const { pkg, workspace } = await workspaceFixture;
+    const economy = pkg.playerEconomies.find((row) => row.roundNumber === 2 && row.primaryWeapon && row.grenadeCount > 0);
+    expect(economy).toBeTruthy();
+
+    const sourcePlayer = pkg.players[economy!.playerIndex];
+    const replayRound = workspace.replay.rounds.find((row) => row.roundNumber === economy!.roundNumber);
+    const replayPlayer = replayRound?.players.find((player) => player.steamId64 === sourcePlayer?.steamId64);
+
+    expect(replayPlayer?.loadout.primaryWeapon).toBe(economy!.primaryWeapon);
+    expect(replayPlayer?.loadout.secondaryWeapon).toBe(economy!.secondaryWeapon);
+    expect(replayPlayer?.loadout.grenadeCount).toBe(economy!.grenadeCount);
+  });
+
+  it("uses next round start tick as replay target end when available", async () => {
+    const { pkg, workspace } = await workspaceFixture;
+    const firstReplayRound = workspace.replay.rounds[0]!;
+    const firstPackageRound = pkg.rounds.find((round) => round.roundNumber === firstReplayRound.roundNumber)!;
+    const nextPackageRound = pkg.rounds
+      .filter((round) => round.startTick > firstPackageRound.startTick)
+      .sort((a, b) => a.startTick - b.startTick)[0]!;
+
+    expect(firstReplayRound.targetEndTick).toBe(nextPackageRound.startTick);
+    expect(firstReplayRound.freezeEndTick).toBe(firstPackageRound.freezeEndTick);
+  });
 });

package/src/index.ts

@@ -1,10 +1,94 @@
 export { buildDemoViewModel, buildMatchWorkspaceModel } from "./workspace.js";
+export { buildOpeningTrails, type OpeningTrailsOptions } from "./trails.js";
 export { buildSeasonLeaderboardModel } from "./leaderboard.js";
-export { buildPlayerSeasonProfile, buildAllPlayerSeasonProfiles } from "./player.js";
-export { buildTeamCohortSummary } from "./team.js";
-export { buildSeriesSummary, recommendMatchMvp } from "./series.js";
-export { SEASON_STAT_VIEWS } from "./season-metrics.js";
+export { buildAllPlayerSeasonProfiles } from "./player.js";
+export { buildPlayerMapRoleProfiles, buildTeamMapRoleMatrices } from "./map-roles.js";
+export { buildDoubleAwpAnalyses, type DoubleAwpAnalysisOptions } from "./double-awp.js";
+export { buildPlayerMapPool, type PlayerMapPerformanceInput } from "./player-map-pool.js";
+export {
+  buildTeamComparison,
+  buildTeamComparisonFromFacts,
+  buildTeamOverviewFromFacts,
+  extractTeamComparisonFacts,
+  type TeamComparisonFacts,
+  type TeamComparisonModel,
+  type TeamOverviewModel
+} from "./team.js";
+export { buildSeriesSummary } from "./series.js";
+export {
+  buildDuelInsights,
+  buildDuelInsightsFromFacts,
+  extractDuelInsightsFacts,
+  duelClassificationLabel,
+  weaponCategory,
+  CATEGORY_METRICS,
+  mechanicsMetricsForWeapon
+} from "./duel.js";
+export type { DuelInsightsFacts, MechanicsMetricKey, WeaponCategory } from "./duel.js";
+export { SEASON_STAT_VIEWS, formatPercent } from "./season-metrics.js";
+export {
+  buildPlayerSeasonInsights,
+  buildUtilityValueSummary,
+  mergeUtilityValueSummaries,
+  buildPlayerMechanicsProfile,
+  buildPlayerMechanicsProfileFromRows,
+  buildPlayerWeaponStats,
+  buildPlayerFlashSummaries,
+  buildMatchBuyQuality,
+  buildMatchReportMarkdown,
+  type SeasonInsightsDemo,
+  type PlayerSeasonInsights,
+  type PlayerMechanicsProfile,
+  type PlayerMechanicsWeaponProfile,
+  type PlayerWeaponStat,
+  type PlayerFlashSummary,
+  type UtilityValueSummary,
+  type UtilityValueRow,
+  type UtilityDamageEvidence,
+  type UtilityDamageKind,
+  type PlayerTrendPoint,
+  type FlashValueSummary,
+  type TeamFlashIncident,
+  type EnemyFlashIncident,
+  type MistakeReview,
+  type MistakeEvidence,
+  type MatchBuyQuality,
+} from "./insights.js";
+export {
+  buildTournamentInsights,
+  buildTournamentInsightsFromFacts,
+  extractTournamentFacts,
+  type TournamentEcoUpsetStat,
+  type TournamentEconomyMatrixCell,
+  type TournamentFacts,
+  type TournamentInsights,
+  type TournamentManAdvantageStat,
+  type TournamentMapStat,
+  type TournamentTeamEconomySummary,
+  type TournamentTeamManAdvantageStat,
+  type TournamentTeamManAdvantageState,
+  type TournamentTeamPistolStat,
+  type TournamentWeaponStat,
+} from "./tournament-compat.js";
 export { displayWeaponName } from "./weapons.js";
 export { economyLabelCn, ECONOMY_LABEL_SHORT } from "./economy.js";
-export { sideLabel } from "./labels.js";
-export type { EconomyConversion, EconomyTypeStats, MatchEconomyConversion } from "@cs2dak/core";
+export {
+  buildMistakeFindings,
+  findingFromDuel,
+  findingFromUtilityDamage,
+  findingFromUtilityFlash,
+  findingFromTacticalCluster,
+  type AnalysisFinding,
+  type FindingOrigin,
+  type FindingSubject,
+} from "./findings.js";
+export * from "./tactical-labels.js";
+export * from "./replay-clock.js";
+export {
+  RADAR_FIELD_MODES,
+  radarModeFrame,
+  radarFieldRoundCount,
+  type RadarFieldMode,
+  type RadarModeOption,
+  type RadarModeFrame
+} from "./radar-field.js";