@cs2dak/core 0.2.1 → 2.0.0

package/src/tactics/round-facts.ts

@@ -0,0 +1,406 @@
+import {
+  FLAG_ALIVE,
+  FLAG_HAS_BOMB,
+  type DemoPackage,
+  type EconomyType,
+  type Side,
+  type TeamKey,
+} from "@cs2dak/contract";
+import {
+  calloutNear,
+  getCalloutTendencies,
+  getPrimaryCalloutRegion,
+  resolveSiteEntry,
+  type CalloutGrid,
+  type TacticalRegion,
+  type Vec3,
+} from "@cs2dak/maps";
+import { buildPlayerTacticalSegments } from "./segments.js";
+import { deriveOpeningPattern, deriveOpeningPressure } from "./formations.js";
+import { createReplayRoundContext, replayCalloutAt, replayTickAt, type ReplayRoundContext } from "./replay-round-context.js";
+import type { OpeningPattern, OpeningPressureEvent, TacticalFrameSample } from "./types.js";
+
+export const TACTICAL_FACT_VERSION = 9;
+export type ExecuteBucket = "rush" | "fast" | "mid" | "late";
+
+export interface SiteEntryOccurrence {
+  playerIndex: number;
+  tick: number;
+  remainSec: number;
+  callout: string;
+  /** 原始最后一个非包点 callout，仅作为证据。 */
+  entryCallout: string | null;
+  entryChokeId: string | null;
+  routeFamilyId: string | null;
+  routeMarkerCallout: string | null;
+  /** freeze end 到首次进点的去重 callout 序列。 */
+  trajectory: string[];
+}
+
+export interface SiteEntryFact {
+  entrants: number;
+  firstEntryTick: number | null;
+  secondEntryTick: number | null;
+  firstEntryRemainSec: number | null;
+  executeRemainSec: number | null;
+  distinctEntryChokeIds?: string[];
+  entrySpanSec?: number | null;
+  order: SiteEntryOccurrence[];
+}
+
+export interface TacticalPlantFact {
+  site: "a" | "b";
+  tick: number;
+  remainSec: number;
+}
+
+export interface TacticalGrenadeOccurrence {
+  id: string;
+  type: string;
+  throwTick: number;
+  effectTick: number | null;
+  throwPosition: Vec3;
+  effectPosition: Vec3;
+  throwCallout: string | null;
+  effectCallout: string | null;
+  effectCalloutSource: "exact" | "nearby" | null;
+  effectCalloutDistance: number | null;
+  confidence: number;
+  samples: number;
+  targetRegion: TacticalRegion | "other" | "unknown";
+  tendencies?: readonly TacticalRegion[];
+}
+
+export interface C4RouteFact {
+  /** 原始相邻去重轨迹，仅作为证据，不直接等同于战术。 */
+  callouts: string[];
+  startRegion: TacticalRegion | "other" | null;
+  endRegion: TacticalRegion | "other" | null;
+  rotated: boolean;
+  plantCallout: string | null;
+}
+
+export interface TacticalRoundFact {
+  analysisVersion: number;
+  matchId: string;
+  mapName: string;
+  side: Side;
+  teamKey: TeamKey;
+  teamName: string;
+  opponentName: string;
+  /** ZIP rounds.json 的本方原生经济。 */
+  economy: EconomyType;
+  opponentEconomy: EconomyType;
+  won: boolean;
+  roundNumber: number;
+  openingPattern: OpeningPattern;
+  openingPressure: OpeningPressureEvent[];
+  targetSite: "a" | "b" | null;
+  siteEntries: { a: SiteEntryFact; b: SiteEntryFact };
+  plant: TacticalPlantFact | null;
+  grenades: TacticalGrenadeOccurrence[];
+  c4Route: C4RouteFact | null;
+  executeRemainSec: number | null;
+  executeBucket: ExecuteBucket | null;
+  firstKillForTeam: boolean | null;
+  grenadeOccurrenceIds: string[];
+}
+
+function locateGrid(grid: CalloutGrid | null, point: Vec3) {
+  if (!grid) return null;
+  return calloutNear(grid, point, { horizontalRadius: 20, verticalRadius: 40 });
+}
+
+const ROUND_SECONDS = 115;
+
+function remainSecAt(tick: number, freezeEndTick: number, tickrate: number): number {
+  return Math.max(0, Math.round(ROUND_SECONDS - (tick - freezeEndTick) / tickrate));
+}
+
+function bucketOf(remainSec: number | null): ExecuteBucket | null {
+  if (remainSec == null) return null;
+  if (remainSec > 95) return "rush";
+  if (remainSec > 70) return "fast";
+  if (remainSec > 40) return "mid";
+  return "late";
+}
+
+function economyFor(round: DemoPackage["rounds"][number], teamKey: TeamKey): EconomyType {
+  return teamKey === "teamA" ? round.teamAEconomy : round.teamBEconomy;
+}
+
+function emptySiteEntry(): SiteEntryFact {
+  return {
+    entrants: 0,
+    firstEntryTick: null,
+    secondEntryTick: null,
+    firstEntryRemainSec: null,
+    executeRemainSec: null,
+    distinctEntryChokeIds: [],
+    entrySpanSec: null,
+    order: [],
+  };
+}
+
+function openingAnalysisFor(
+  decoded: ReplayRoundContext | null,
+  round: DemoPackage["rounds"][number],
+  mapName: string,
+  side: Side,
+  tickrate: number,
+  grid: CalloutGrid | null,
+): { openingPattern: OpeningPattern; openingPressure: OpeningPressureEvent[] } {
+  const endTick = Math.min(round.endTick, round.freezeEndTick + 30 * tickrate);
+  const samples: TacticalFrameSample[] = [];
+  for (const track of decoded?.tracks ?? []) {
+    if (track.side !== side) continue;
+    for (let index = 0; index < (decoded?.frameCount ?? 0); index += 1) {
+      const tick = replayTickAt(decoded!, index);
+      if (tick < round.freezeEndTick) continue;
+      if (tick > endTick) break;
+      const alive = ((track.flags[index] ?? 0) & FLAG_ALIVE) !== 0;
+      samples.push({
+        tick,
+        playerIndex: track.playerIndex,
+        side,
+        alive,
+        callout: alive ? replayCalloutAt(decoded!, track, index, grid) : null,
+      });
+    }
+  }
+  const segments = buildPlayerTacticalSegments(samples, {
+    mapName,
+    tickrate,
+    maxGapTicks: decoded ? decoded.tickStep * 2 : undefined,
+  });
+  return {
+    openingPattern: deriveOpeningPattern(segments, { side, startTick: round.freezeEndTick, endTick }),
+    openingPressure: deriveOpeningPressure(segments, { mapName, side, startTick: round.freezeEndTick, endTick }),
+  };
+}
+
+function siteEntriesFor(
+  decoded: ReplayRoundContext | null,
+  round: DemoPackage["rounds"][number],
+  mapName: string,
+  side: Side,
+  tickrate: number,
+  grid: CalloutGrid | null,
+): { a: SiteEntryFact; b: SiteEntryFact } {
+  if (!decoded) return { a: emptySiteEntry(), b: emptySiteEntry() };
+  const bySite = {
+    a: new Map<number, SiteEntryOccurrence>(),
+    b: new Map<number, SiteEntryOccurrence>(),
+  };
+  for (const track of decoded.tracks) {
+    if (track.side !== side) continue;
+    const seen = new Set<"a" | "b">();
+    const trajectory: string[] = [];
+    for (let index = 0; index < decoded.frameCount; index += 1) {
+      const tick = replayTickAt(decoded, index);
+      if (tick < round.freezeEndTick || tick > round.endTick) continue;
+      if (((track.flags[index] ?? 0) & FLAG_ALIVE) === 0) break;
+      const callout = replayCalloutAt(decoded, track, index, grid);
+      if (!callout) continue;
+      if (callout !== trajectory.at(-1)) trajectory.push(callout);
+      const site = callout === "BombsiteA" ? "a" : callout === "BombsiteB" ? "b" : null;
+      if (!site || seen.has(site)) continue;
+      seen.add(site);
+      const resolved = resolveSiteEntry(mapName, site, trajectory);
+      bySite[site].set(track.playerIndex, {
+        playerIndex: track.playerIndex,
+        tick,
+        remainSec: remainSecAt(tick, round.freezeEndTick, tickrate),
+        callout,
+        entryCallout: trajectory.at(-2) ?? null,
+        entryChokeId: resolved.entryChokeId,
+        routeFamilyId: resolved.routeFamilyId,
+        routeMarkerCallout: resolved.routeMarkerCallout,
+        trajectory: [...trajectory],
+      });
+    }
+  }
+  const build = (site: "a" | "b"): SiteEntryFact => {
+    const order = [...bySite[site].values()].sort((a, b) => a.tick - b.tick || a.playerIndex - b.playerIndex);
+    const first = order[0];
+    const last = order.at(-1);
+    return {
+      entrants: order.length,
+      firstEntryTick: first?.tick ?? null,
+      secondEntryTick: order[1]?.tick ?? null,
+      firstEntryRemainSec: first?.remainSec ?? null,
+      executeRemainSec: order[1]?.remainSec ?? null,
+      distinctEntryChokeIds: [...new Set(order.flatMap((row) => row.entryChokeId ? [row.entryChokeId] : []))].sort(),
+      entrySpanSec: first && last ? Math.round(((last.tick - first.tick) / tickrate) * 10) / 10 : null,
+      order,
+    };
+  };
+  return { a: build("a"), b: build("b") };
+}
+
+function targetRegion(mapName: string, callout: string | null): TacticalGrenadeOccurrence["targetRegion"] {
+  if (!callout) return "unknown";
+  return getPrimaryCalloutRegion(mapName, callout) ?? "unknown";
+}
+
+function plantFor(pkg: DemoPackage, round: DemoPackage["rounds"][number], tickrate: number): TacticalPlantFact | null {
+  const plant = pkg.bombs.find((event) =>
+    event.roundNumber === round.roundNumber && event.type === "planted" && (event.site === "a" || event.site === "b"),
+  );
+  if (!plant || (plant.site !== "a" && plant.site !== "b")) return null;
+  return { site: plant.site, tick: plant.tick, remainSec: remainSecAt(plant.tick, round.freezeEndTick, tickrate) };
+}
+
+function targetSiteFor(plant: TacticalPlantFact | null, entries: { a: SiteEntryFact; b: SiteEntryFact }): "a" | "b" | null {
+  if (plant) return plant.site;
+  if (entries.a.entrants > entries.b.entrants) return "a";
+  if (entries.b.entrants > entries.a.entrants) return "b";
+  return null;
+}
+
+function throwerCallout(pkg: DemoPackage, roundNumber: number, playerIndex: number, tick: number): string | null {
+  const replayRound = pkg.replay?.rounds.find((row) => row.roundNumber === roundNumber);
+  const track = replayRound?.players.find((row) => row.playerIndex === playerIndex);
+  if (!pkg.replay || !replayRound || !track) return null;
+  const frame = Math.max(0, Math.min(replayRound.frameCount - 1, Math.round((tick - replayRound.startTick) / replayRound.tickStep)));
+  return pkg.replay.placeDict[track.place[frame] ?? -1] ?? null;
+}
+
+function sideOf(pkg: DemoPackage, playerIndex: number, round: DemoPackage["rounds"][number]): Side | null {
+  const player = pkg.players[playerIndex];
+  if (!player) return null;
+  return player.teamKey === "teamA" ? round.teamASide : round.teamBSide;
+}
+
+function grenadesFor(
+  pkg: DemoPackage,
+  matchId: string,
+  round: DemoPackage["rounds"][number],
+  side: Side,
+  grid: CalloutGrid | null,
+): TacticalGrenadeOccurrence[] {
+  return (pkg.grenades ?? [])
+    .map((grenade, index) => ({ grenade, index }))
+    .filter(({ grenade }) => grenade.roundNumber === round.roundNumber && sideOf(pkg, grenade.throwerIndex, round) === side)
+    .map(({ grenade, index }) => {
+      const located = locateGrid(grid, grenade.effectPosition);
+      const effectCallout = located?.callout ?? null;
+      return {
+        id: grenade.grenadeId ?? `${matchId}:r${grenade.roundNumber}:g${index}`,
+        type: grenade.grenade,
+        throwTick: grenade.throwTick,
+        effectTick: grenade.effectTick ?? null,
+        throwPosition: grenade.throwPosition,
+        effectPosition: grenade.effectPosition,
+        throwCallout: throwerCallout(pkg, grenade.roundNumber, grenade.throwerIndex, grenade.throwTick),
+        effectCallout,
+        effectCalloutSource: located?.source ?? null,
+        effectCalloutDistance: located?.distance ?? null,
+        confidence: located?.confidence ?? 0,
+        samples: located?.samples ?? 0,
+        targetRegion: targetRegion(pkg.match.mapName, effectCallout),
+        tendencies: effectCallout ? getCalloutTendencies(pkg.match.mapName, effectCallout) ?? [] : [],
+      };
+    });
+}
+
+function c4RouteFor(
+  decoded: ReplayRoundContext | null,
+  round: DemoPackage["rounds"][number],
+  mapName: string,
+  plant: TacticalPlantFact | null,
+  grid: CalloutGrid | null,
+): C4RouteFact | null {
+  if (!decoded) return null;
+  const callouts: string[] = [];
+  let carrierIndex = -1;
+  for (let index = 0; index < decoded.frameCount; index += 1) {
+    const tick = replayTickAt(decoded, index);
+    if (tick < round.freezeEndTick || tick > round.endTick) continue;
+    const cached = decoded.tracks[carrierIndex];
+    if (!cached || ((cached.flags[index] ?? 0) & FLAG_ALIVE) === 0 || ((cached.flags[index] ?? 0) & FLAG_HAS_BOMB) === 0) {
+      carrierIndex = decoded.tracks.findIndex((track) =>
+        ((track.flags[index] ?? 0) & FLAG_ALIVE) !== 0 && ((track.flags[index] ?? 0) & FLAG_HAS_BOMB) !== 0,
+      );
+    }
+    if (carrierIndex < 0) continue;
+    const callout = replayCalloutAt(decoded, decoded.tracks[carrierIndex]!, index, grid);
+    if (callout && callout !== callouts.at(-1)) callouts.push(callout);
+  }
+  if (callouts.length === 0) return null;
+  const regions = callouts.map((callout) => targetRegion(mapName, callout)).filter((region) => region !== "unknown");
+  const directional = regions.filter((region): region is "a" | "b" => region === "a" || region === "b");
+  return {
+    callouts,
+    startRegion: regions[0] ?? null,
+    endRegion: regions.at(-1) ?? null,
+    rotated: Boolean(directional[0] && directional.at(-1) && directional[0] !== directional.at(-1)),
+    plantCallout: plant ? callouts.at(-1) ?? null : null,
+  };
+}
+
+function firstKillForTeam(pkg: DemoPackage, roundNumber: number, teamKey: TeamKey): boolean | null {
+  const first = pkg.kills.filter((kill) => kill.roundNumber === roundNumber).sort((a, b) => a.tick - b.tick)[0];
+  if (first?.killerIndex == null) return null;
+  return pkg.players[first.killerIndex]?.teamKey === teamKey;
+}
+
+function teamName(pkg: DemoPackage, teamKey: TeamKey): string {
+  return pkg.match[teamKey].name ?? teamKey;
+}
+
+export function extractTacticalRoundFacts(
+  pkg: DemoPackage,
+  options: { matchId: string; calloutGrid?: CalloutGrid | null },
+): TacticalRoundFact[] {
+  return extractTacticalRoundFactsWithContexts(pkg, options, undefined);
+}
+
+/** Internal composition seam: contexts never cross the @cs2dak/core public boundary. */
+export function extractTacticalRoundFactsWithContexts(
+  pkg: DemoPackage,
+  options: { matchId: string; calloutGrid?: CalloutGrid | null },
+  replayContexts: ReadonlyMap<number, ReplayRoundContext> | undefined,
+): TacticalRoundFact[] {
+  const tickrate = pkg.match.tickrate || 64;
+  const out: TacticalRoundFact[] = [];
+  for (const round of pkg.rounds) {
+    const decoded = replayContexts?.get(round.roundNumber) ?? createReplayRoundContext(pkg, round);
+    const plant = plantFor(pkg, round, tickrate);
+    for (const side of ["t", "ct"] as const) {
+      if (!decoded?.tracks.some((track) => track.side === side)) continue;
+      const teamKey: TeamKey = round.teamASide === side ? "teamA" : "teamB";
+      const opponentKey: TeamKey = teamKey === "teamA" ? "teamB" : "teamA";
+      const entries = siteEntriesFor(decoded, round, pkg.match.mapName, side, tickrate, options.calloutGrid ?? null);
+      const opening = openingAnalysisFor(decoded, round, pkg.match.mapName, side, tickrate, options.calloutGrid ?? null);
+      const targetSite = targetSiteFor(plant, entries);
+      const executeRemainSec = targetSite ? entries[targetSite].executeRemainSec : null;
+      const grenades = grenadesFor(pkg, options.matchId, round, side, options.calloutGrid ?? null);
+      out.push({
+        analysisVersion: TACTICAL_FACT_VERSION,
+        matchId: options.matchId,
+        mapName: pkg.match.mapName,
+        side,
+        teamKey,
+        teamName: teamName(pkg, teamKey),
+        opponentName: teamName(pkg, opponentKey),
+        economy: economyFor(round, teamKey),
+        opponentEconomy: economyFor(round, opponentKey),
+        won: round.winnerSide === side,
+        roundNumber: round.roundNumber,
+        openingPattern: opening.openingPattern,
+        openingPressure: opening.openingPressure,
+        targetSite,
+        siteEntries: entries,
+        plant,
+        grenades,
+        c4Route: side === "t" ? c4RouteFor(decoded, round, pkg.match.mapName, plant, options.calloutGrid ?? null) : null,
+        executeRemainSec,
+        executeBucket: bucketOf(executeRemainSec),
+        firstKillForTeam: firstKillForTeam(pkg, round.roundNumber, teamKey),
+        grenadeOccurrenceIds: grenades.map((grenade) => grenade.id),
+      });
+    }
+  }
+  return out;
+}

package/src/tactics/segments.ts

@@ -0,0 +1,68 @@
+import { classifyTacticalLocation } from "@cs2dak/maps";
+import type { PlayerTacticalSegment, TacticalFrameSample } from "./types.js";
+
+export interface BuildSegmentsOptions {
+  mapName: string;
+  tickrate: number;
+  maxGapTicks?: number;
+}
+
+export function buildPlayerTacticalSegments(
+  samples: readonly TacticalFrameSample[],
+  options: BuildSegmentsOptions,
+): PlayerTacticalSegment[] {
+  const byPlayer = new Map<number, TacticalFrameSample[]>();
+  for (const sample of samples) {
+    const rows = byPlayer.get(sample.playerIndex) ?? [];
+    rows.push(sample);
+    byPlayer.set(sample.playerIndex, rows);
+  }
+
+  const segments: PlayerTacticalSegment[] = [];
+  for (const rows of byPlayer.values()) {
+    rows.sort((a, b) => a.tick - b.tick);
+    let active: TacticalFrameSample | null = null;
+    let endTick = 0;
+    const close = (): void => {
+      if (!active?.callout) return;
+      const location = classifyTacticalLocation(options.mapName, active.side, active.callout);
+      segments.push({
+        playerIndex: active.playerIndex,
+        side: active.side,
+        startTick: active.tick,
+        endTick,
+        durationSec: Math.max(0, (endTick - active.tick) / options.tickrate),
+        callout: active.callout,
+        tendencies: location.tendencies,
+        primaryRegion: location.primaryRegion,
+        positionGroupId: location.positionGroupId,
+        evidence: {
+          type: "dwell",
+          tick: active.tick,
+          endTick,
+          playerIndices: [active.playerIndex],
+          callouts: [active.callout],
+        },
+      });
+      active = null;
+    };
+
+    for (const sample of rows) {
+      if (!sample.alive || !sample.callout) {
+        close();
+        continue;
+      }
+      const gapExceeded = active != null
+        && options.maxGapTicks != null
+        && sample.tick - endTick > options.maxGapTicks;
+      const changed = active != null
+        && (active.callout !== sample.callout || active.side !== sample.side);
+      if (gapExceeded || changed) close();
+      if (!active) active = sample;
+      endTick = sample.tick;
+    }
+    close();
+  }
+
+  return segments.sort((a, b) => a.startTick - b.startTick || a.playerIndex - b.playerIndex);
+}

package/src/tactics/tactics.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildFormationTimeline,
+  buildPlayerTacticalSegments,
+  deriveOpeningPattern,
+  deriveOpeningPressure,
+  type TacticalFrameSample,
+} from "./index.js";
+
+const base = (partial: Partial<TacticalFrameSample>): TacticalFrameSample => ({
+  tick: 0,
+  playerIndex: 1,
+  side: "t",
+  alive: true,
+  callout: "TRamp",
+  ...partial,
+});
+
+describe("tactical spatial kernel", () => {
+  it("将连续同 callout 样本合并，并在死亡、缺失、换区或采样断裂时截断", () => {
+    const segments = buildPlayerTacticalSegments([
+      base({ tick: 0 }),
+      base({ tick: 64 }),
+      base({ tick: 128, callout: "PalaceAlley" }),
+      base({ tick: 192, alive: false, callout: null }),
+      base({ tick: 256, callout: "TopofMid" }),
+      base({ tick: 640, callout: "TopofMid" }),
+    ], { mapName: "de_mirage", tickrate: 64, maxGapTicks: 128 });
+
+    expect(segments.map((row) => [row.callout, row.startTick, row.endTick])).toEqual([
+      ["TRamp", 0, 64],
+      ["PalaceAlley", 128, 128],
+      ["TopofMid", 256, 256],
+      ["TopofMid", 640, 640],
+    ]);
+    expect(segments[0]).toMatchObject({ primaryRegion: "a", positionGroupId: "a_ramp" });
+    expect(segments[2]).toMatchObject({ primaryRegion: "mid", positionGroupId: "top_mid" });
+  });
+
+  it("阵型快照对未知 callout 保持 unknown，不进行名称猜测", () => {
+    const timeline = buildFormationTimeline([
+      base({ tick: 64, playerIndex: 1, callout: "TRamp" }),
+      base({ tick: 64, playerIndex: 2, callout: "NoSuchPlace" }),
+      base({ tick: 64, playerIndex: 3, callout: null }),
+    ], { mapName: "de_mirage" });
+
+    expect(timeline).toHaveLength(1);
+    expect(timeline[0]?.regionCounts).toEqual({ a: 1, b: 0, mid: 0, unknown: 2 });
+    expect(timeline[0]?.positionGroupCounts).toEqual({ a_ramp: 1 });
+  });
+
+  it("开局粗签名只看区域结构，详细签名保留默认位", () => {
+    const first = buildPlayerTacticalSegments([
+      base({ tick: 0, playerIndex: 1, callout: "TRamp" }),
+      base({ tick: 64, playerIndex: 1, callout: "TRamp" }),
+      base({ tick: 0, playerIndex: 2, callout: "TopofMid" }),
+      base({ tick: 64, playerIndex: 2, callout: "TopofMid" }),
+      base({ tick: 0, playerIndex: 3, callout: "Apartments" }),
+      base({ tick: 64, playerIndex: 3, callout: "Apartments" }),
+    ], { mapName: "de_mirage", tickrate: 64 });
+    const shifted = buildPlayerTacticalSegments([
+      base({ tick: 0, playerIndex: 1, callout: "PalaceAlley" }),
+      base({ tick: 64, playerIndex: 1, callout: "PalaceAlley" }),
+      base({ tick: 0, playerIndex: 2, callout: "SideAlley" }),
+      base({ tick: 64, playerIndex: 2, callout: "SideAlley" }),
+      base({ tick: 0, playerIndex: 3, callout: "BackAlley" }),
+      base({ tick: 64, playerIndex: 3, callout: "BackAlley" }),
+    ], { mapName: "de_mirage", tickrate: 64 });
+
+    const a = deriveOpeningPattern(first, { side: "t", startTick: 0, endTick: 128 });
+    const b = deriveOpeningPattern(shifted, { side: "t", startTick: 0, endTick: 128 });
+    expect(a.coarseSignature).toBe("T:1A-1MID-1B:balanced");
+    expect(b.coarseSignature).toBe(a.coarseSignature);
+    expect(a.detailedSignature).toContain("a_ramp:1");
+    expect(a.evidence.every((row) => row.tick != null && row.playerIndices?.length === 1)).toBe(true);
+  });
+
+  it("开局代表位置优先采用已确认默认位，避免出生点长驻留淹没展开", () => {
+    const segments = buildPlayerTacticalSegments([
+      base({ tick: 0, callout: "TSpawn" }),
+      base({ tick: 64, callout: "TSpawn" }),
+      base({ tick: 128, callout: "TSpawn" }),
+      base({ tick: 192, callout: "TRamp" }),
+      base({ tick: 256, callout: "TRamp" }),
+    ], { mapName: "de_mirage", tickrate: 64 });
+
+    const opening = deriveOpeningPattern(segments, { side: "t", startTick: 0, endTick: 320 });
+    expect(opening.regionCounts).toEqual({ a: 1, b: 0, mid: 0, unknown: 0 });
+    expect(opening.positionGroupCounts).toEqual({ a_ramp: 1 });
+  });
+
+  it("CT 快速进入 T 默认位时标记深度前压，并保留中文 callout 证据", () => {
+    const segments = buildPlayerTacticalSegments([
+      base({ side: "ct", tick: 0, callout: "CTSpawn" }),
+      base({ side: "ct", tick: 64, callout: "Outside" }),
+      base({ side: "ct", tick: 128, callout: "Outside" }),
+    ], { mapName: "de_ancient", tickrate: 64 });
+
+    expect(deriveOpeningPressure(segments, {
+      mapName: "de_ancient",
+      side: "ct",
+      startTick: 0,
+      endTick: 192,
+    })).toEqual([expect.objectContaining({
+      playerIndex: 1,
+      callout: "Outside",
+      calloutLabel: "匪口",
+      kind: "deep",
+      opposingPositionGroupId: "t_outside",
+    })]);
+  });
+});

package/src/tactics/types.ts

@@ -0,0 +1,73 @@
+import type { DefaultPositionSide, TacticalRegion } from "@cs2dak/maps";
+
+export interface TacticalFrameSample {
+  tick: number;
+  playerIndex: number;
+  side: DefaultPositionSide;
+  alive: boolean;
+  callout: string | null;
+}
+
+export interface TacticalEvidenceRef {
+  type: "position" | "dwell" | "transition";
+  tick: number;
+  endTick?: number;
+  playerIndices?: number[];
+  callouts?: string[];
+}
+
+export interface PlayerTacticalSegment {
+  playerIndex: number;
+  side: DefaultPositionSide;
+  startTick: number;
+  endTick: number;
+  durationSec: number;
+  callout: string;
+  tendencies: readonly TacticalRegion[];
+  primaryRegion: TacticalRegion | null;
+  positionGroupId: string | null;
+  evidence: TacticalEvidenceRef;
+}
+
+export interface TacticalRegionCounts {
+  a: number;
+  b: number;
+  mid: number;
+  unknown: number;
+}
+
+export interface TacticalFormationSnapshot {
+  tick: number;
+  side: DefaultPositionSide;
+  regionCounts: TacticalRegionCounts;
+  positionGroupCounts: Record<string, number>;
+  playerLocations: Array<{
+    playerIndex: number;
+    callout: string | null;
+    primaryRegion: TacticalRegion | null;
+    positionGroupId: string | null;
+  }>;
+}
+
+export interface OpeningPattern {
+  side: DefaultPositionSide;
+  regionCounts: TacticalRegionCounts;
+  positionGroupCounts: Record<string, number>;
+  spread: "stacked" | "split" | "balanced" | "unknown";
+  coarseSignature: string;
+  detailedSignature: string;
+  evidence: TacticalEvidenceRef[];
+}
+
+export interface OpeningPressureEvent {
+  playerIndex: number;
+  side: DefaultPositionSide;
+  tick: number;
+  endTick: number;
+  callout: string;
+  calloutLabel: string;
+  primaryRegion: TacticalRegion | null;
+  kind: "forward" | "deep";
+  opposingPositionGroupId: string | null;
+  evidence: TacticalEvidenceRef;
+}