@cs2dak/maps 0.2.1 → 1.0.0

package/src/callout-grid.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { calloutAt, calloutNear, type CalloutGrid } from "./callout-grid.js";
+
+function grid(cells: CalloutGrid["cells"], vocabulary = ["A", "B", "Mid"]): CalloutGrid {
+  return {
+    mapName: "de_test",
+    gridSize: 10,
+    origin: [-100, -100, -100],
+    maxCoord: [100, 100, 100],
+    dims: [20, 20, 20],
+    vocabulary,
+    confidence: 0.51,
+    minSamples: 3,
+    cells,
+  };
+}
+
+describe("callout-grid", () => {
+  it("floors negative world coordinates to the same grid convention as generation", () => {
+    const g = grid({ "-10,20,0": [0, 0.9, 12] });
+    expect(calloutAt(g, { x: -1, y: 29.9, z: 0 })?.callout).toBe("A");
+  });
+
+  it("returns null for empty cells", () => {
+    expect(calloutAt(grid({}), { x: 0, y: 0, z: 0 })).toBeNull();
+  });
+
+  it("guards vocabulary index overflow", () => {
+    expect(calloutAt(grid({ "0,0,0": [9, 0.9, 12] }), { x: 0, y: 0, z: 0 })).toBeNull();
+  });
+
+  it("returns exact hits before nearby candidates", () => {
+    const g = grid({
+      "0,0,0": [0, 0.6, 5],
+      "10,0,0": [1, 0.99, 50],
+    });
+    expect(calloutNear(g, { x: 1, y: 1, z: 1 })).toMatchObject({
+      callout: "A",
+      source: "exact",
+      distance: 0,
+      offset: [0, 0, 0],
+    });
+  });
+
+  it("finds nearby cells for sparse effect positions", () => {
+    const g = grid({
+      "10,0,0": [1, 0.7, 20],
+      "0,20,0": [2, 0.95, 100],
+    });
+    expect(calloutNear(g, { x: 1, y: 1, z: 1 }, { horizontalRadius: 25, verticalRadius: 10 })).toMatchObject({
+      callout: "B",
+      source: "nearby",
+      offset: [10, 0, 0],
+    });
+  });
+
+  it("prefers same z or lower z before upper z for equal-distance candidates", () => {
+    const g = grid({
+      "0,0,-10": [0, 0.7, 10],
+      "0,0,10": [1, 0.99, 100],
+    });
+    expect(calloutNear(g, { x: 0, y: 0, z: 0 }, { horizontalRadius: 0, verticalRadius: 10 })?.callout).toBe("A");
+  });
+
+  it("does not bridge Nuke-style stacked floors outside vertical radius", () => {
+    const g = grid({
+      "0,0,0": [0, 0.8, 20],
+      "0,0,120": [1, 0.9, 30],
+    });
+    expect(calloutNear(g, { x: 0, y: 0, z: 90 }, { horizontalRadius: 0, verticalRadius: 20 })).toBeNull();
+    expect(calloutNear(g, { x: 0, y: 0, z: 90 }, { horizontalRadius: 0, verticalRadius: 40 })?.callout).toBe("B");
+  });
+});

package/src/callout-grid.ts

@@ -0,0 +1,168 @@
+/**
+ * callout-grid — 3D 多数表决查找表。
+ *
+ * 来源：110 场 demo（pro 51 + NJU 59）replay 8Hz 流的 (x,y,z) + place 字段，
+ *       按 10-unit 3D 格点多数表决归纳得到。
+ * 生成：scripts/build-callout-grid.py
+ *
+ * 核心是纯函数 calloutAt()/calloutNear()，无平台依赖。
+ */
+import type { Vec3 } from "./nav.js";
+
+// ── 类型 ──
+
+export interface CalloutGridMeta {
+  mapName: string;
+  gridSize: number;
+  origin: [number, number, number];
+  maxCoord: [number, number, number];
+  dims: [number, number, number];
+  vocabulary: string[];
+  confidence: number;
+  minSamples: number;
+}
+
+export type CalloutGridCell = [
+  vocabularyIndex: number,
+  confidence: number,
+  samples: number,
+];
+
+export interface CalloutGrid extends CalloutGridMeta {
+  /**
+   * "gx,gy,gz" → [vocabularyIndex, confidence, sampleCount]
+   * vocabularyIndex -> vocabulary[] 查 callout 名
+   * confidence -> [0, 1] 多数占比
+   * sampleCount -> 该格总采样帧数
+   */
+  cells: Record<string, CalloutGridCell>;
+}
+
+export interface CalloutAtResult {
+  callout: string;
+  confidence: number;
+  samples: number;
+  source: "exact";
+  distance: 0;
+  offset: [number, number, number];
+}
+
+export interface CalloutNearResult {
+  callout: string;
+  confidence: number;
+  samples: number;
+  source: "exact" | "nearby";
+  distance: number;
+  offset: [number, number, number];
+}
+
+export interface CalloutNearOptions {
+  horizontalRadius?: number;
+  verticalRadius?: number;
+}
+
+// ── 核心查询（纯函数，浏览器/Node 通用） ──
+
+function gridCoord(value: number, gridSize: number): number {
+  return Math.floor(value / gridSize) * gridSize;
+}
+
+function cellAt(grid: CalloutGrid, gx: number, gy: number, gz: number): CalloutNearResult | null {
+  const cell = grid.cells[`${gx},${gy},${gz}`];
+  if (!cell) return null;
+  const callout = grid.vocabulary[cell[0]];
+  if (!callout) return null;
+  return {
+    callout,
+    confidence: cell[1],
+    samples: cell[2],
+    source: "exact",
+    distance: 0,
+    offset: [0, 0, 0],
+  };
+}
+
+/**
+ * 查询一个世界坐标对应的 callout 名。
+ * 返回 null 表示该格无数据（不可达区域 / 置信度不足 / 稀疏不足）。
+ *
+ * @param grid   通过 loadCalloutGrid() 或 fetch() 获取的网格对象
+ * @param point  世界坐标（v3 replay position 同系）
+ */
+export function calloutAt(
+  grid: CalloutGrid,
+  point: Vec3,
+): CalloutAtResult | null {
+  const result = cellAt(
+    grid,
+    gridCoord(point.x, grid.gridSize),
+    gridCoord(point.y, grid.gridSize),
+    gridCoord(point.z, grid.gridSize),
+  );
+  return result && result.source === "exact"
+    ? { ...result, source: "exact", distance: 0, offset: [0, 0, 0] }
+    : null;
+}
+
+/**
+ * 查询世界坐标附近的 callout。
+ *
+ * 道具落点常在空中、墙边或不可站立格，精确格可能没有玩家采样。此函数先做精确
+ * 命中；失败后在半径内查邻近格，优先同层/下方近格，再按距离、置信度、样本数排序。
+ */
+export function calloutNear(
+  grid: CalloutGrid,
+  point: Vec3,
+  options: CalloutNearOptions = {},
+): CalloutNearResult | null {
+  const gx = gridCoord(point.x, grid.gridSize);
+  const gy = gridCoord(point.y, grid.gridSize);
+  const gz = gridCoord(point.z, grid.gridSize);
+  const exact = cellAt(grid, gx, gy, gz);
+  if (exact) return exact;
+
+  const horizontalRadius = options.horizontalRadius ?? 20;
+  const verticalRadius = options.verticalRadius ?? 40;
+  const hSteps = Math.max(0, Math.ceil(horizontalRadius / grid.gridSize));
+  const zSteps = Math.max(0, Math.ceil(verticalRadius / grid.gridSize));
+  const candidates: CalloutNearResult[] = [];
+
+  for (let dx = -hSteps; dx <= hSteps; dx += 1) {
+    for (let dy = -hSteps; dy <= hSteps; dy += 1) {
+      for (let dz = -zSteps; dz <= zSteps; dz += 1) {
+        if (dx === 0 && dy === 0 && dz === 0) continue;
+        const ox = dx * grid.gridSize;
+        const oy = dy * grid.gridSize;
+        const oz = dz * grid.gridSize;
+        const horizontalDistance = Math.hypot(ox, oy);
+        if (horizontalDistance > horizontalRadius) continue;
+        if (Math.abs(oz) > verticalRadius) continue;
+        const cell = cellAt(grid, gx + ox, gy + oy, gz + oz);
+        if (!cell) continue;
+        candidates.push({
+          ...cell,
+          source: "nearby",
+          distance: Math.hypot(ox, oy, oz),
+          offset: [ox, oy, oz],
+        });
+      }
+    }
+  }
+
+  candidates.sort((a, b) => {
+    const zPrefA = zPreference(a.offset[2]);
+    const zPrefB = zPreference(b.offset[2]);
+    return zPrefA - zPrefB ||
+      a.distance - b.distance ||
+      b.confidence - a.confidence ||
+      b.samples - a.samples ||
+      a.callout.localeCompare(b.callout);
+  });
+  return candidates[0] ?? null;
+}
+
+function zPreference(offsetZ: number): number {
+  if (offsetZ === 0) return 0;
+  if (offsetZ < 0) return 1;
+  return 2;
+}

package/src/callout-names.ts

@@ -0,0 +1,238 @@
+export type TacticalRegion = "a" | "b" | "mid";
+
+/** callout 条目：中文名 + 可选战术倾向。 */
+export interface CalloutNameEntry {
+  cn: string;
+  /** 战术倾向：首元素为该位置在阵容中的主要方向。取 tendency[0] 参与区域人数统计。 */
+  tendency?: TacticalRegion[];
+}
+
+/** 读取一个已知 callout 的静态定义；未知地图或 callout 返回 null。 */
+export function getCalloutDefinition(mapName: string, id: string): CalloutNameEntry | null {
+  return CALLOUT_DICT[mapName]?.[id] ?? null;
+}
+
+/** 读取有序战术方向；已知但未标注方向时返回空数组，未知 callout 返回 null。 */
+export function getCalloutTendencies(mapName: string, id: string): readonly TacticalRegion[] | null {
+  const entry = getCalloutDefinition(mapName, id);
+  return entry ? entry.tendency ?? [] : null;
+}
+
+/** 读取 callout 的主要方向。 */
+export function getPrimaryCalloutRegion(mapName: string, id: string): TacticalRegion | null {
+  return getCalloutTendencies(mapName, id)?.[0] ?? null;
+}
+
+/** 判断 callout 是否可连接到指定方向（包含次要方向）。 */
+export function calloutBelongsToRegion(mapName: string, id: string, region: TacticalRegion): boolean {
+  return getCalloutTendencies(mapName, id)?.includes(region) ?? false;
+}
+
+/** 取 callout 的中文名。 */
+export function calloutCn(mapName: string, id: string): string {
+  return CALLOUT_DICT[mapName]?.[id]?.cn ?? "";
+}
+
+/**
+ * CS2 官方 callout 名 → 中文名 + 战术倾向映射表。
+ *
+ * 来源：79 场 demo（pro 24 + NJU 55）的 `lastPlaceName` 词表 + 社区约定。
+ * 定位：供 Area v1 / 动线 / 展示层消费，不含坐标与路由逻辑。
+ * 待核验：部分 callout 可能有更精确的社区叫法，本表为初稿。
+ */
+export const CALLOUT_DICT: Record<string, Record<string, CalloutNameEntry>> = {
+  de_ancient: {
+    BombsiteA: { cn: "A包", tendency: ["a"] },
+    BombsiteB: { cn: "B包", tendency: ["b"] },
+    Middle: { cn: "中路", tendency: ["mid"] },
+    Outside: { cn: "匪口", tendency: ["a", "mid"] },
+    SideEntrance: { cn: "黑屋", tendency: ["b"] },
+    Alley: { cn: "底线", tendency: ["b"] },
+    TSideUpper: { cn: "跳台", tendency: ["mid", "b"] },
+    TSideLower: { cn: "B小", tendency: ["b"] },
+    CTSpawn: { cn: "警家", tendency: ["a"] },
+    SideHall: { cn: "甜甜圈", tendency: ["a"] },
+    MainHall: { cn: "A厅", tendency: ["a"] },
+    Ruins: { cn: "B外", tendency: ["b"] },
+    House: { cn: "VIP", tendency: ["mid"] },
+    Ramp: { cn: "B坡", tendency: ["b"] },
+    TSpawn: { cn: "匪家" },
+    Tunnel: { cn: "隧道", tendency: ["b"] },
+    Water: { cn: "水路", tendency: ["b"] },
+    TopofMid: { cn: "中远", tendency: ["mid"] },
+  },
+
+  de_anubis: {
+    BombsiteB: { cn: "B包", tendency: ["b"] },
+    Canal: { cn: "水下", tendency: ["a", "b"] },
+    Middle: { cn: "中路", tendency: ["mid"] },
+    Bridge: { cn: "中桥", tendency: ["mid"] },
+    OutsideLong: { cn: "B外", tendency: ["b"] },
+    BombsiteA: { cn: "A包", tendency: ["a"] },
+    Ruins: { cn: "B外", tendency: ["b"] },
+    Connector: { cn: "黑屋", tendency: ["b"] },
+    PalaceInterior: { cn: "B连", tendency: ["b"] },
+    Main: { cn: "A厅", tendency: ["a"] },
+    Walkway: { cn: "A连", tendency: ["a"] },
+    BackofB: { cn: "B包台上", tendency: ["b"] },
+    TSpawn: { cn: "匪家" },
+    Street: { cn: "街道", tendency: ["a"] },
+    Heaven: { cn: "天堂", tendency: ["a"] },
+    MidDoors: { cn: "中门", tendency: ["mid"] },
+    TSideUpper: { cn: "匪跳", tendency: ["a"] },
+    CTSideUpper: { cn: "警家" },
+    Alley: { cn: "警家", tendency: ["b"] },
+    Bricks: { cn: "B连阳光房", tendency: ["b"] },
+    Fountain: { cn: "喷泉", tendency: ["a"] },
+    TStairs: { cn: "匪梯", tendency: ["a", "b"] },
+    LowerTunnel: { cn: "警家隧道", tendency: ["b"] },
+    CTSpawn: { cn: "警家后" },
+    TunnelStairs: { cn: "隧道楼梯", tendency: ["a"] },
+    SnipersNest: { cn: "警家狙位", tendency: ["b"] },
+    Tunnel: { cn: "隧道", tendency: ["a"] },
+    Water: { cn: "警家水下", tendency: ["a", "b"] },
+  },
+
+  de_dust2: {
+    BombsiteB: { cn: "B包", tendency: ["b"] },
+    LongDoors: { cn: "A门", tendency: ["a"] },
+    LongA: { cn: "A大", tendency: ["a"] },
+    MidDoors: { cn: "中门", tendency: ["mid"] },
+    UpperTunnel: { cn: "B洞", tendency: ["b"] },
+    TopofMid: { cn: "中远匪口", tendency: ["mid"] },
+    OutsideLong: { cn: "A门外", tendency: ["a"] },
+    UnderA: { cn: "警家", tendency: ["a"] },
+    CTSpawn: { cn: "警家", tendency: ["mid", "a"] },
+    Catwalk: { cn: "A小", tendency: ["a", "mid"] },
+    ExtendedA: { cn: "A小过点", tendency: ["a"] },
+    ShortStairs: { cn: "A小楼梯", tendency: ["a"] },
+    Middle: { cn: "中路", tendency: ["mid"] },
+    BombsiteA: { cn: "A包", tendency: ["a"] },
+    TSpawn: { cn: "匪家" },
+    LowerTunnel: { cn: "B1", tendency: ["mid"] },
+    BDoors: { cn: "B门", tendency: ["b"] },
+    ARamp: { cn: "A斜坡", tendency: ["a"] },
+    OutsideTunnel: { cn: "B洞外", tendency: ["b"] },
+    Pit: { cn: "大坑", tendency: ["a"] },
+    TunnelStairs: { cn: "B洞楼梯", tendency: ["b"] },
+    Hole: { cn: "狗洞", tendency: ["b"] },
+    Side: { cn: "大坑平台", tendency: ["a"] },
+    TRamp: { cn: "后花", tendency: ["b"] },
+  },
+
+  de_inferno: {
+    Banana: { cn: "香蕉道", tendency: ["b"] },
+    BombsiteB: { cn: "B包", tendency: ["b"] },
+    BombsiteA: { cn: "A包", tendency: ["a"] },
+    Apartments: { cn: "二楼", tendency: ["a"] },
+    Middle: { cn: "中路", tendency: ["mid"] },
+    CTSpawn: { cn: "警家" },
+    TopofMid: { cn: "中路", tendency: ["mid"] },
+    Arch: { cn: "拱门", tendency: ["a"] },
+    Ruins: { cn: "警家教堂", tendency: ["b"] },
+    Pit: { cn: "大坑", tendency: ["a"] },
+    SecondMid: { cn: "侧道", tendency: ["mid", "a"] },
+    TRamp: { cn: "匪口", tendency: ["mid", "b"] },
+    TSpawn: { cn: "匪家" },
+    Balcony: { cn: "阳台", tendency: ["a"] },
+    LowerMid: { cn: "匪口", tendency: ["mid", "b"] },
+    Library: { cn: "书房", tendency: ["a"] },
+    BackAlley: { cn: "匪二楼", tendency: ["a"] },
+    Underpass: { cn: "下水道", tendency: ["mid"] },
+    Quad: { cn: "马棚", tendency: ["a"] },
+    Deck: { cn: "匪二阳台", },
+    Bridge: { cn: "匪桥", tendency: ["mid", "a"] },
+    Upstairs: { cn: "匪二楼", tendency: ["mid", "a"] },
+    Graveyard: { cn: "墓地", tendency: ["a"] },
+    Kitchen: { cn: "厨房", },
+  },
+
+  de_mirage: {
+    BombsiteA: { cn: "A包", tendency: ["a"] },
+    CTSpawn: { cn: "警家" },
+    BombsiteB: { cn: "B包", tendency: ["b"] },
+    PalaceInterior: { cn: "A二楼", tendency: ["a"] },
+    Middle: { cn: "中路", tendency: ["mid"] },
+    TopofMid: { cn: "中远/匪口", tendency: ["mid"] },
+    Catwalk: { cn: "B小", tendency: ["b"] },
+    Apartments: { cn: "B二楼", tendency: ["b"] },
+    Underpass: { cn: "下水道", tendency: ["mid", "b"] },
+    TSpawn: { cn: "匪家" },
+    PalaceAlley: { cn: "A1", tendency: ["a"] },
+    Connector: { cn: "拱门", tendency: ["a", "mid"] },
+    SideAlley: { cn: "匪口", tendency: ["mid"] },
+    BackAlley: { cn: "B二楼", tendency: ["b"] },
+    Jungle: { cn: "Jungle", tendency: ["a"] },
+    Shop: { cn: "超市", tendency: ["b"] },
+    TRamp: { cn: "A1", tendency: ["a"] },
+    SnipersNest: { cn: "VIP", tendency: ["mid"] },
+    Truck: { cn: "白车", tendency: ["b"] },
+    House: { cn: "匪二楼", tendency: ["b"] },
+    Stairs: { cn: "跳台", tendency: ["a"] },
+    Ladder: { cn: "黑屋", tendency: ["mid", "b"] },
+    Scaffolding: { cn: "A2上下", tendency: ["a"] },
+  },
+
+  de_nuke: {
+    Outside: { cn: "外场", tendency: ["mid"] },
+    BombsiteA: { cn: "A包", tendency: ["a"] },
+    Ramp: { cn: "铁板", tendency: ["b"] },
+    Lobby: { cn: "匪厅", tendency: ["a"] },
+    Tunnels: { cn: "K1地下", tendency: ["b"] },
+    BombsiteB: { cn: "B包", tendency: ["b"] },
+    TSpawn: { cn: "匪家" },
+    Mini: { cn: "正门", tendency: ["a", "mid"] },
+    Squeaky: { cn: "铁门房", tendency: ["a"] },
+    Control: { cn: "链接", tendency: ["b"] },
+    Garage: { cn: "大仓", tendency: ["mid"] },
+    Rafters: { cn: "三楼横梁", tendency: ["a"] },
+    Hut: { cn: "黄房", tendency: ["a"] },
+    Vending: { cn: "链接", tendency: ["b"] },
+    Heaven: { cn: "三楼", tendency: ["a"] },
+    Admin: { cn: "铁板三楼下", tendency: ["b"] },
+    CTSpawn: { cn: "警家" },
+    Secret: { cn: "K1", tendency: ["b", "mid"] },
+    Trophy: { cn: "奖杯房", tendency: ["b"] },
+    HutRoof: { cn: "黄房顶", tendency: ["a"] },
+    Hell: { cn: "三楼下", tendency: ["a", "b", "mid"] },
+    Roof: { cn: "屋顶", tendency: ["a"] },
+    Silo: { cn: "山上", tendency: ["mid"] },
+    Vents: { cn: "管道", tendency: ["b"] },
+    Catwalk: { cn: "外场三楼", tendency: ["mid"] },
+    Decon: { cn: "死门", tendency: ["b"] },
+    Crane: { cn: "A包柱上", tendency: ["a"] },
+    Observation: { cn: "控制室", tendency: ["b"] },
+    LockerRoom: { cn: "更衣室", tendency: ["mid"] },
+  },
+
+  de_overpass: {
+    LowerPark: { cn: "A小厕所", tendency: ["a"] },
+    Water: { cn: "工地", tendency: ["b"] },
+    BombsiteA: { cn: "A包", tendency: ["a"] },
+    BombsiteB: { cn: "B包", tendency: ["b"] },
+    UpperPark: { cn: "A大厕所", tendency: ["a"] },
+    Canal: { cn: "长管", tendency: ["b"] },
+    Fountain: { cn: "喷泉", tendency: ["a"] },
+    Tunnels: { cn: "下水道", tendency: ["mid"] },
+    Connector: { cn: "下水道", tendency: ["mid", "a"] },
+    Walkway: { cn: "ABC", tendency: ["b"] },
+    Construction: { cn: "B小", tendency: ["b"] },
+    TSpawn: { cn: "匪家" },
+    Alley: { cn: "匪家B外", tendency: ["b"] },
+    SnipersNest: { cn: "B二楼", tendency: ["b"] },
+    UnderA: { cn: "一层", tendency: ["b"] },
+    BackofA: { cn: "垃圾桶", tendency: ["a"] },
+    Pipe: { cn: "短管", tendency: ["b"] },
+    Lobby: { cn: "银行", tendency: ["a"] },
+    Playground: { cn: "游乐园", tendency: ["a"] },
+    Restroom: { cn: "厕所", tendency: ["a"] },
+    TStairs: { cn: "匪楼梯" },
+    Bridge: { cn: "桥", tendency: ["b"] },
+    Stairs: { cn: "楼梯", tendency: ["a"] },
+    StorageRoom: { cn: "银行", tendency: ["a"] },
+    SideAlley: { cn: "匪家保枪位" },
+  },
+};
+
+/** 所有已标定的地图名。 */
+export const CALLOUT_MAPS = Object.keys(CALLOUT_DICT) as ReadonlyArray<string>;

package/src/default-positions.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import {
+  CALLOUT_MAPS,
+  CALLOUT_DICT,
+  calloutBelongsToRegion,
+  getCalloutDefinition,
+  getCalloutTendencies,
+  getPrimaryCalloutRegion,
+} from "./callout-names.js";
+import {
+  DEFAULT_POSITION_GROUPS,
+  positionGroupOf,
+  classifyTacticalLocation,
+  getDefaultPositionGroup,
+} from "./default-positions.js";
+
+describe("default-positions", () => {
+  it("mirage T 默认位含 5 个位置责任组", () => {
+    expect(Object.keys(DEFAULT_POSITION_GROUPS.de_mirage.t.groups)).toEqual([
+      "a_ramp",
+      "a_palace",
+      "top_mid",
+      "underpass",
+      "b_apps",
+    ]);
+  });
+
+  it("anchor 里引用的 callout 都是合法 callout（在 callout-names 中）", () => {
+    for (const [map, sides] of Object.entries(DEFAULT_POSITION_GROUPS)) {
+      const table = CALLOUT_DICT[map];
+      for (const side of ["t", "ct"] as const) {
+        for (const group of Object.values(sides[side].groups)) {
+          for (const callout of group.callouts) expect(table[callout]).toBeTruthy();
+        }
+      }
+    }
+  });
+
+  it("7 图都有 t/ct 默认位且每个 anchor 至少 1 callout", () => {
+    for (const map of CALLOUT_MAPS) {
+      const defaults = DEFAULT_POSITION_GROUPS[map];
+      expect(defaults, map).toBeTruthy();
+      for (const side of ["t", "ct"] as const) {
+        const groups = Object.values(defaults[side].groups);
+        expect(groups.length, `${map}.${side}`).toBeGreaterThan(0);
+        for (const group of groups) {
+          expect(group.callouts.length, `${map}.${side}.${group.name}`).toBeGreaterThan(0);
+        }
+      }
+    }
+  });
+
+  it("基础 callout API 保留多倾向顺序，未知 callout 不猜测", () => {
+    expect(getCalloutDefinition("de_mirage", "Connector")).toEqual({ cn: "拱门", tendency: ["a", "mid"] });
+    expect(getCalloutTendencies("de_mirage", "Connector")).toEqual(["a", "mid"]);
+    expect(getPrimaryCalloutRegion("de_mirage", "Connector")).toBe("a");
+    expect(calloutBelongsToRegion("de_mirage", "Connector", "mid")).toBe(true);
+    expect(getCalloutDefinition("de_mirage", "NoSuchPlace")).toBeNull();
+    expect(getCalloutTendencies("de_mirage", "NoSuchPlace")).toBeNull();
+    expect(getPrimaryCalloutRegion("de_mirage", "NoSuchPlace")).toBeNull();
+  });
+
+  it("默认位置组只保留人工确认的开局停挂点，不维护静态 contested/advanced 角色", () => {
+    expect(positionGroupOf("de_ancient", "t", "Outside")).toBe("t_outside");
+    expect(positionGroupOf("de_ancient", "t", "Tunnel")).toBeNull();
+    expect(positionGroupOf("de_ancient", "t", "Water")).toBeNull();
+
+    expect(positionGroupOf("de_anubis", "t", "Bridge")).toBe("mid_bridge");
+    expect(positionGroupOf("de_anubis", "t", "Middle")).toBeNull();
+
+    expect(positionGroupOf("de_dust2", "t", "LongA")).toBeNull();
+
+    expect(positionGroupOf("de_nuke", "t", "Ramp")).toBeNull();
+    expect(positionGroupOf("de_nuke", "t", "Trophy")).toBe("lobby");
+
+    expect(positionGroupOf("de_overpass", "t", "Water")).toBe("short_pipe");
+  });
+
+  it("统一位置分类只组合基础倾向与当前阵营默认位", () => {
+    expect(classifyTacticalLocation("de_mirage", "t", "PalaceAlley")).toEqual({
+      callout: "PalaceAlley",
+      tendencies: ["a"],
+      primaryRegion: "a",
+      positionGroupId: "a_ramp",
+      isDefaultPosition: true,
+    });
+    expect(classifyTacticalLocation("de_mirage", "ct", "PalaceAlley")).toEqual({
+      callout: "PalaceAlley",
+      tendencies: ["a"],
+      primaryRegion: "a",
+      positionGroupId: null,
+      isDefaultPosition: false,
+    });
+    expect(classifyTacticalLocation("de_mirage", "t", "NoSuchPlace")).toEqual({
+      callout: "NoSuchPlace",
+      tendencies: [],
+      primaryRegion: null,
+      positionGroupId: null,
+      isDefaultPosition: false,
+    });
+    expect(classifyTacticalLocation("de_mirage", "t", null).callout).toBeNull();
+  });
+
+  it("positionGroupOf：default 返回 positionGroupId，否则 null", () => {
+    expect(positionGroupOf("de_mirage", "t", "TRamp")).toBe("a_ramp");
+    expect(positionGroupOf("de_mirage", "t", "Catwalk")).toBeNull();
+    expect(getDefaultPositionGroup("de_mirage", "t", "TRamp")).toMatchObject({ id: "a_ramp", name: "A1" });
+  });
+});