@myclaw163/clawclaw-cli 0.6.54

package/src/strategies/game-utils.ts

@@ -0,0 +1,721 @@
+import type { GameState, PlayerInfo, Position, TaskInfo, EmergencyInfo, CorpseInfo } from '../sdk/types.js';
+import { Action } from '../sdk/action.js';
+import type { BehaviorDecision, CorpseTarget, RoomTarget, StrategyContext } from './types.js';
+import { emptyKnowledgeView } from '../lib/knowledge-store.js';
+import { assessRoutes } from './pathfind/escape-planner.js';
+
+export const TASK_SUBMIT_RADIUS = 12;
+export const KILL_RANGE = 50;
+export const REPORT_RANGE = 150;
+export const SHRIMP_VISION_RANGE = 270;
+export const SHRIMP_VISION_EXIT_BUFFER = 30;
+export const SHRIMP_VISION_RELEASE_RANGE = SHRIMP_VISION_RANGE + SHRIMP_VISION_EXIT_BUFFER;
+export const FOLLOW_RANGE = 300;
+export const PATROL_REACHED_DISTANCE = 150;
+export const PROGRESS_INTERVAL_MS = 30_000;
+export const LONE_IGNORE_MS = 10_000;
+export const LONE_FOLLOW_DISTANCE = 10;
+/** 任务点离任一可见尸体多近就算「在尸体旁」，会做任务伪装的坏人据此跳过该任务、避免站在命案现场做任务。 */
+export const CORPSE_TASK_AVOID_RANGE = 100;
+/** 判「同一具尸体」的极近半径：尸体不会移动，跨 tick 只有坐标取整抖动，远小于两具不同尸体的间距。 */
+export const CORPSE_SAME_BODY_RADIUS = 20;
+/** corpse_spotted 事件坐标离自己多近才算「人就在命案现场」——超出视为别处尸体的迟到/补发事件，不触发现场反射。 */
+export const CORPSE_SCENE_RANGE = REPORT_RANGE;
+
+export function killCooldownSecs(state: GameState): number {
+  return state.you.kill_cooldown_secs ?? 0;
+}
+
+export function hasKillUseRemaining(state: GameState): boolean {
+  return state.you.kills_remaining == null || state.you.kills_remaining > 0;
+}
+
+export function canUseKill(state: GameState): boolean {
+  return hasKillUseRemaining(state) && killCooldownSecs(state) <= 0;
+}
+
+export function dist(x1: number, y1: number, x2: number, y2: number): number {
+  return Math.sqrt((x1 - x2) ** 2 + (y1 - y2) ** 2);
+}
+
+export function firstAvailableTask(
+  tasks: TaskInfo[],
+  predicate: (task: TaskInfo) => boolean,
+  emergency?: EmergencyInfo | null,
+  blockedTarget?: { x: number; y: number } | null,
+  avoidCorpses?: CorpseInfo[] | null,
+): TaskInfo | null {
+  const nearCorpse = (x: number, y: number): boolean =>
+    !!avoidCorpses && avoidCorpses.some(c => c.x != null && c.y != null && dist(x, y, c.x, c.y) <= CORPSE_TASK_AVOID_RANGE);
+
+  // 紧急任务（维修点）始终自动优先，不做尸体回避：大家都会涌向维修点，在那儿做任务并不可疑，
+  // 且紧急维修有倒计时、时间敏感。尸体回避只针对下面的常规伪装任务。
+  if (emergency && emergency.status !== 'completed' && emergency.x != null && emergency.y != null && predicate(emergency)) {
+    if (!blockedTarget || dist(emergency.x, emergency.y, blockedTarget.x, blockedTarget.y) > 10) {
+      return emergency;
+    }
+  }
+  return tasks.find(t => {
+    if (t.status === 'completed' || t.status === 'in_progress') return false;
+    if (t.x == null || t.y == null) return false;
+    if (blockedTarget && dist(t.x, t.y, blockedTarget.x, blockedTarget.y) <= 10) return false;
+    if (nearCorpse(t.x, t.y)) return false;
+    return predicate(t);
+  }) ?? null;
+}
+
+/** 任务点离任一威胁点多近就算「在威胁旁」而被硬排除（欧氏即可——隔薄墙的威胁照样危险）。 */
+export const TASK_THREAT_EXCLUDE_RANGE = 500;
+/** 测地路径离任一威胁点多近就算「必经之路有危险」而被硬排除（治路上有人把守时的来回逡巡）。 */
+export const TASK_PATH_THREAT_RADIUS = 350;
+
+export interface SafeTaskOptions {
+  /** 硬排除：这些点 threatExcludeRadius 内的任务直接丢弃。 */
+  threatPoints?: Position[];
+  threatExcludeRadius?: number;
+  /** 路径硬排除半径：去任务点的测地路径经过威胁点这个距离内也丢弃，默认 TASK_PATH_THREAT_RADIUS。 */
+  pathThreatRadius?: number;
+  /** 粘性：该任务仍是合法候选就直接返回它，不重新比距离，杜绝等距摇摆。 */
+  stickyTaskName?: string | null;
+}
+
+export interface SafePatrolOptions {
+  threatPoints?: Position[];
+  threatExcludeRadius?: number;
+  pathThreatRadius?: number;
+}
+
+/**
+ * firstAvailableTask 的进阶版：同样的紧急任务优先与候选过滤，但常规任务改选
+ * 测地最近（distance-field 一次扫描），并支持威胁硬排除（任务点旁有威胁，或
+ * 必经之路经过威胁附近）与当前任务粘性。粘性任务同样要过路径检查——路被人
+ * 把守时直接换任务，而不是「后撤→粘回原任务→再走近→再后撤」地振荡。
+ * 测地不可达的候选按欧氏距离垫底（仍可选，避免全图无任务可做）。
+ */
+export function nearestSafeTask(
+  state: GameState,
+  tasks: TaskInfo[],
+  predicate: (task: TaskInfo) => boolean,
+  emergency?: EmergencyInfo | null,
+  blockedTarget?: { x: number; y: number } | null,
+  avoidCorpses?: CorpseInfo[] | null,
+  opts: SafeTaskOptions = {},
+): TaskInfo | null {
+  // 紧急任务语义与 firstAvailableTask 一致：时间敏感且人人都涌过去，不做尸体/威胁回避。
+  if (emergency && emergency.status !== 'completed' && emergency.x != null && emergency.y != null && predicate(emergency)) {
+    if (!blockedTarget || dist(emergency.x, emergency.y, blockedTarget.x, blockedTarget.y) > 10) {
+      return emergency;
+    }
+  }
+
+  const threatPoints = opts.threatPoints ?? [];
+  const threatRadius = opts.threatExcludeRadius ?? TASK_THREAT_EXCLUDE_RANGE;
+  const nearCorpse = (x: number, y: number): boolean =>
+    !!avoidCorpses && avoidCorpses.some(c => c.x != null && c.y != null && dist(x, y, c.x, c.y) <= CORPSE_TASK_AVOID_RANGE);
+
+  const candidates = tasks.filter(t => {
+    if (t.status === 'completed' || t.status === 'in_progress') return false;
+    if (t.x == null || t.y == null) return false;
+    if (blockedTarget && dist(t.x, t.y, blockedTarget.x, blockedTarget.y) <= 10) return false;
+    if (nearCorpse(t.x, t.y)) return false;
+    if (threatPoints.some(p => dist(t.x!, t.y!, p.x, p.y) <= threatRadius)) return false;
+    return predicate(t);
+  });
+  if (candidates.length === 0) return null;
+
+  // 无威胁时粘性可以零成本短路（不必为路径检查扫距离场）。
+  if (opts.stickyTaskName && threatPoints.length === 0) {
+    const sticky = candidates.find(t => t.task_name === opts.stickyTaskName);
+    if (sticky) return sticky;
+  }
+
+  const routes = assessRoutes(
+    { x: state.you.x, y: state.you.y },
+    candidates.map(t => ({ x: t.x!, y: t.y! })),
+    threatPoints,
+    opts.pathThreatRadius ?? TASK_PATH_THREAT_RADIUS,
+  );
+  // routes 为 null（自己不在可走格上，极少见）时退回欧氏排序，无路径排除。
+  const viable = routes == null
+    ? candidates.map((t, i) => ({ t, i }))
+    : candidates.map((t, i) => ({ t, i })).filter(({ i }) => !routes[i].nearThreat);
+  if (viable.length === 0) return null;
+
+  if (opts.stickyTaskName) {
+    const sticky = viable.find(({ t }) => t.task_name === opts.stickyTaskName);
+    if (sticky) return sticky.t;
+  }
+
+  let best = viable[0].t;
+  let bestScore = Infinity;
+  for (const { t, i } of viable) {
+    const euclid = dist(state.you.x, state.you.y, t.x!, t.y!);
+    const geoPx = routes?.[i].distancePx;
+    const score = geoPx == null ? euclid : geoPx !== Infinity ? geoPx : euclid + 1e6;
+    if (score < bestScore) {
+      bestScore = score;
+      best = t;
+    }
+  }
+  return best;
+}
+
+/**
+ * 巡逻一步：朝当前巡逻房间移动，已到达就推进到下一个房间再走。rooms 为空返回 []（无处可去）。
+ * stopOnPlayer 控制路上撞见玩家是否立刻停下（猎杀型策略=true，借此撞见落单猎物即停、下一 tick 出刀）。
+ * 抽自各 *-top 里重复的 patrolDecision。
+ */
+export function patrolStep(
+  state: GameState,
+  ctx: StrategyContext,
+  patrol: PatrolState,
+  stopOnPlayer = true,
+): BehaviorDecision[] {
+  let room = patrol.nextRoom(ctx);
+  if (!room) return [];
+  if (dist(state.you.x, state.you.y, room.x, room.y) <= PATROL_REACHED_DISTANCE) {
+    patrol.advance(ctx);
+    const next = patrol.nextRoom(ctx);
+    if (next) room = next;
+  }
+  return [{ action: Action.move({ x: room.x, y: room.y }, stopOnPlayer) }];
+}
+
+export function safePatrolStep(
+  state: GameState,
+  ctx: StrategyContext,
+  patrol: PatrolState,
+  stopOnPlayer = true,
+  opts: SafePatrolOptions = {},
+): BehaviorDecision[] {
+  const room = nextSafePatrolRoom(state, ctx, patrol, opts);
+  return room ? [{ action: Action.move({ x: room.x, y: room.y }, stopOnPlayer) }] : [];
+}
+
+function nextSafePatrolRoom(
+  state: GameState,
+  ctx: StrategyContext,
+  patrol: PatrolState,
+  opts: SafePatrolOptions,
+): RoomTarget | null {
+  let current = patrol.nextRoom(ctx);
+  if (!current) return null;
+  if (dist(state.you.x, state.you.y, current.x, current.y) <= PATROL_REACHED_DISTANCE) {
+    patrol.advance(ctx);
+    current = patrol.nextRoom(ctx);
+    if (!current) return null;
+  }
+
+  const ordered = orderedPatrolRooms(ctx, current);
+  if (ordered.length === 0) return null;
+  const threatPoints = opts.threatPoints ?? [];
+  const notBlocked = ordered.filter(room =>
+    !ctx.blockedMoveTarget || dist(room.x, room.y, ctx.blockedMoveTarget.x, ctx.blockedMoveTarget.y) > 10);
+  const candidates = notBlocked.length > 0 ? notBlocked : ordered;
+  if (threatPoints.length === 0) {
+    movePatrolToRoom(ctx, patrol, current, candidates[0]);
+    return candidates[0];
+  }
+
+  const threatRadius = opts.threatExcludeRadius ?? TASK_THREAT_EXCLUDE_RANGE;
+  const endpointSafe = candidates.filter(room =>
+    !threatPoints.some(p => dist(room.x, room.y, p.x, p.y) <= threatRadius));
+  if (endpointSafe.length === 0) return null;
+
+  const routes = assessRoutes(
+    { x: state.you.x, y: state.you.y },
+    endpointSafe.map(room => ({ x: room.x, y: room.y })),
+    threatPoints,
+    opts.pathThreatRadius ?? TASK_PATH_THREAT_RADIUS,
+  );
+  const viable = routes == null
+    ? endpointSafe
+    : endpointSafe.filter((_room, i) => !routes[i].nearThreat);
+  const selected = viable[0] ?? null;
+  if (!selected) return null;
+  movePatrolToRoom(ctx, patrol, current, selected);
+  return selected;
+}
+
+function orderedPatrolRooms(ctx: StrategyContext, current: RoomTarget): RoomTarget[] {
+  if (ctx.rooms.length === 0) return [];
+  const start = Math.max(0, ctx.rooms.findIndex(room => room.name === current.name));
+  return ctx.rooms.map((_room, offset) => ctx.rooms[(start + offset) % ctx.rooms.length]);
+}
+
+function movePatrolToRoom(ctx: StrategyContext, patrol: PatrolState, current: RoomTarget, selected: RoomTarget): void {
+  if (selected.name === current.name || ctx.rooms.length === 0) return;
+  for (let i = 0; i < ctx.rooms.length; i += 1) {
+    const room = patrol.nextRoom(ctx);
+    if (!room || room.name === selected.name) return;
+    patrol.advance(ctx);
+  }
+}
+
+/**
+ * 靠近 → 到点提交单个任务；到点但本地仍被冷却（not_at_task_location 等）返回 null，让上层兜底巡逻、
+ * 避免死盯一个刚到却提交失败的点。供「会做任务伪装」的坏人策略（crab-sabotage / lone-kill-task）复用。
+ */
+export function approachOrDoTaskStep(
+  state: GameState,
+  ctx: StrategyContext,
+  task: TaskInfo,
+  stopOnPlayer = false,
+): BehaviorDecision[] | null {
+  const d = dist(state.you.x, state.you.y, task.x!, task.y!);
+  if (d <= TASK_SUBMIT_RADIUS) {
+    if (Date.now() >= ctx.taskLocalBlockedUntil) return [{ action: Action.doTask(task.task_name) }];
+    return null;
+  }
+  return [{ action: Action.move({ x: task.x!, y: task.y! }, stopOnPlayer) }];
+}
+
+/** 单个任务的「靠近 → 到点提交」决策：在提交半径内且本地未被冷却就 doTask，否则移动过去。 */
+export function taskMoveDecision(state: GameState, ctx: StrategyContext, task: TaskInfo): BehaviorDecision {
+  const d = dist(state.you.x, state.you.y, task.x!, task.y!);
+  if (d <= TASK_SUBMIT_RADIUS && Date.now() >= ctx.taskLocalBlockedUntil) {
+    return { action: Action.doTask(task.task_name) };
+  }
+  return { action: Action.move({ x: task.x!, y: task.y! }) };
+}
+
+export function nearestReportableCorpse(state: GameState): GameState['corpses'][number] | null {
+  const nearby = state.corpses
+    .map(corpse => {
+      const distance = corpse.distance ?? (
+        corpse.x != null && corpse.y != null
+          ? dist(state.you.x, state.you.y, corpse.x, corpse.y)
+          : Infinity
+      );
+      return { corpse, distance };
+    })
+    .filter(({ distance }) => distance <= REPORT_RANGE)
+    .sort((a, b) => a.distance - b.distance);
+  return nearby[0]?.corpse ?? null;
+}
+
+/** 已知尸体中离自己最近、且有坐标可导航的一具（含已离开视野、之前记下的）。供接近/徘徊用。 */
+export function nearestKnownCorpse(state: GameState, ctx: StrategyContext): CorpseTarget | null {
+  const candidates = (ctx.knownCorpses ?? []).filter(c => c.x != null && c.y != null);
+  if (candidates.length === 0) return null;
+  const corpse = candidates.reduce((best, c) =>
+    dist(state.you.x, state.you.y, c.x!, c.y!) < dist(state.you.x, state.you.y, best.x!, best.y!) ? c : best,
+  );
+  return { x: corpse.x!, y: corpse.y!, name: corpse.name, room: corpse.room };
+}
+
+/**
+ * 可导航的尸体目标：优先返回带坐标的最近尸体；若已知尸体都还没拿到坐标（state.corpses 只给 distance，
+ * 坐标得等 corpse_spotted 事件补上），退化为「尸体所在房间」的锚点，先把 bot 带进房间——人进视野后坐标
+ * 自然补全，避免「明知有尸体却因暂时没坐标而巡逻走开」。两者皆无才 null。接近/徘徊类**导航**用，区别于
+ * 严格要坐标的 nearestKnownCorpse（报尸等必须站在尸体上的场景仍用后者）。
+ */
+export function nearestKnownCorpseNav(state: GameState, ctx: StrategyContext): CorpseTarget | null {
+  const withCoords = nearestKnownCorpse(state, ctx);
+  if (withCoords) return withCoords;
+  for (const c of ctx.knownCorpses ?? []) {
+    if (!c.room) continue;
+    const room = ctx.rooms.find(r => r.name === c.room);
+    if (room) return { x: room.x, y: room.y, name: c.name, room: c.room };
+  }
+  return null;
+}
+
+/** 是否已知任何尸体（含看见过、已离开视野的）。开会清场后由 strategy-loop 清空。供「该不该去报尸/回避」类**导航**判断用。 */
+export function hasKnownCorpse(ctx: StrategyContext): boolean {
+  return (ctx.knownCorpses?.length ?? 0) > 0;
+}
+
+/**
+ * 当前这一帧我就**站在命案现场**（≤CORPSE_SCENE_RANGE，150px）——视野里有尸体或本 tick 刚冒出
+ * `corpse_spotted`，且尸体确实落在现场半径内。贴脸灭口目击者 / 报尸自证 / 标注尸体旁目击者这类
+ * **现场反射**必须用它，**不能**用 `hasKnownCorpse`：后者只表示「记得地图某处有尸体」，会把「记得有
+ * 尸体」误当成「人就在尸体旁」，导致随便撞见一个人就灭口 / 误把后来遇见者当目击者 / 生成错误的栽赃简报。
+ */
+export function corpseAtScene(state: GameState): boolean {
+  // state.corpses 按「视野半径」(SHRIMP_VISION_RANGE)过滤，比命案现场半径(CORPSE_SCENE_RANGE=150)大得多——视野里有
+  // 尸体 ≠ 人就站在尸体旁。不加距离门控会让 300px 外的尸体也触发灭口/目击者标注/栽赃，故同样按现场半径筛。
+  const corpseInScene = state.corpses.some(c => {
+    const d = c.distance ?? (
+      c.x != null && c.y != null ? dist(state.you.x, state.you.y, c.x, c.y) : Infinity
+    );
+    return d <= CORPSE_SCENE_RANGE;
+  });
+  if (corpseInScene) return true;
+  // corpse_spotted 事件可能被 backfill 补入、或在本轮移动开始后才到达，单看「增量里有该事件」会把地图别处
+  // 的尸体误当成脚下的命案现场。尸体不会移动，故只认坐标确实落在现场半径内的事件。
+  return spottedCorpsesFromEvents(state).some(c =>
+    dist(state.you.x, state.you.y, c.x, c.y) <= CORPSE_SCENE_RANGE);
+}
+
+/** 本 tick 增量里**全部** corpse_spotted 事件（按到达顺序）。同批多具尸体不能只留最后一具——
+ *  server 的 state.corpses 没坐标，漏掉的尸体无法再补回。 */
+export function spottedCorpsesFromEvents(state: GameState): CorpseTarget[] {
+  return spottedCorpsesFromEventList(state.new_events);
+}
+
+/** corpse_spotted 坐标提取的底层版：可作用于任意事件数组（如 action 结果里的 new_events，绕开主循环游标竞态）。 */
+export function spottedCorpsesFromEventList(events: any[] | undefined): CorpseTarget[] {
+  const out: CorpseTarget[] = [];
+  for (const evt of events ?? []) {
+    if (evt?.type !== 'corpse_spotted') continue;
+    const x = Number(evt.corpse_x);
+    const y = Number(evt.corpse_y);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+    out.push({
+      x,
+      y,
+      name: typeof evt.corpse_name === 'string' ? evt.corpse_name : undefined,
+      room: typeof evt.corpse_room === 'string' ? evt.corpse_room : undefined,
+    });
+  }
+  return out;
+}
+
+/**
+ * 已知尸体的跨 tick 记忆，全局唯一一份由 strategy-loop 持有，每 tick `observe` 后写入 `ctx.knownCorpses`，
+ * 供所有策略统一读取（检测 hasKnownCorpse、接近 nearestKnownCorpse、任务回避 firstAvailableTask/nearestSafeTask、
+ * 死亡确认按名/座位匹配）。`state.corpses` 只含当前视野(nearby)尸体，`corpse_spotted` 事件又只在尸体出现的
+ * 那一 tick 进增量——两者都没有持久性，尸体一离开视野下一 tick 就会丢。CorpseMemory 把见过的尸体按身份累积
+ * 去重，使「看见过、已离开视野」的尸体仍持续可见。尸体在游戏里出现后一直存在到开会才被清场，故 strategy-loop
+ * 在 `onMeetingResume` 时 `reset` 并清空 `ctx.knownCorpses`。报尸本身仍按近距触发（nearestReportableCorpse
+ * 读 state.corpses），记忆负责把 bot 带回尸体旁。
+ */
+export class CorpseMemory {
+  private readonly seen: CorpseInfo[] = [];
+  private readonly lastSeenPlayers = new Map<string, PlayerInfo>();
+
+  /**
+   * 每 tick 调用：缓存可见玩家位置，并入已确认击杀、当前视野尸体与本 tick 全部 corpse_spotted 事件。
+   * 服务端可能直到杀手再次移动才生成 corpse_spotted，因此成功击杀先用目标最后目击位置兜底。
+   */
+  observe(state: GameState, recentlyKilledTargets?: Map<string, number>): void {
+    for (const player of state.players) this.rememberPlayer(player);
+    for (const evt of state.new_events ?? []) {
+      if (evt?.type !== 'player_spotted') continue;
+      const name = typeof evt.spotted_name === 'string' ? evt.spotted_name : '';
+      const x = Number(evt.spotted_x);
+      const y = Number(evt.spotted_y);
+      if (!name || !Number.isFinite(x) || !Number.isFinite(y)) continue;
+      this.rememberPlayer({
+        name,
+        room: typeof evt.spotted_room === 'string' ? evt.spotted_room : '',
+        x,
+        y,
+        seat: typeof evt.spotted_seat === 'number' ? evt.spotted_seat : undefined,
+      });
+    }
+
+    const now = Date.now();
+    for (const [target, until] of recentlyKilledTargets ?? []) {
+      if (until <= now) continue;
+      const player = this.lastSeenPlayers.get(target.trim().toLowerCase());
+      if (player) this.remember(player);
+    }
+
+    // state.corpses 只含当前视野尸体，且可能无坐标（server 仅给 distance）；仍记下来，使无坐标尸体
+    // 至少能被「存在性检测」(hasKnownCorpse) 与「按名/座位死亡确认」命中，坐标随后由 corpse_spotted /
+    // 击杀回填补全。这样 knownCorpses 成为 state.corpses 的严格超集，跨 tick 持久、开会才清空。
+    for (const c of state.corpses) this.remember(c);
+    for (const spotted of spottedCorpsesFromEvents(state)) this.remember(spotted);
+  }
+
+  /**
+   * 从任意事件数组补全 corpse_spotted 坐标——供 action 结果里的 new_events 用，绕开主循环 state.new_events
+   * 的共享游标竞态（daemon 可能先通过 WS 消费掉该事件，strategy 的 HTTP 轮询就再也看不到，尸体坐标永远进
+   * 不了记忆，导航类策略只能巡逻走开）。
+   */
+  ingestEvents(events: any[] | undefined): void {
+    for (const spotted of spottedCorpsesFromEventList(events)) this.remember(spotted);
+  }
+
+  /** 累积的已知尸体（含已离开视野的）。供 firstAvailableTask / nearestSafeTask 的尸体回避参数。 */
+  list(): CorpseInfo[] {
+    return this.seen;
+  }
+
+  /** 会议后尸体清场 → 清空记忆。 */
+  reset(): void {
+    this.seen.length = 0;
+    this.lastSeenPlayers.clear();
+  }
+
+  private rememberPlayer(player: PlayerInfo): void {
+    const key = player.name.trim().toLowerCase();
+    if (key) this.lastSeenPlayers.set(key, player);
+  }
+
+  private remember(corpse: { x?: number; y?: number; name?: string; room?: string; seat?: number }): void {
+    // 身份去重，不能用任务回避半径(100px)——那会把相距 90px 的两具不同尸体并成一具，
+    // 漏掉第二具另一侧的任务回避。优先按尸体名判同，无名时退化为极近坐标(CORPSE_SAME_BODY_RADIUS)。
+    const name = corpse.name ?? '';
+    const existing = this.seen.find(c => this.isSameBody(c, corpse, name));
+    if (!existing) {
+      this.seen.push({ name, room: corpse.room ?? '', x: corpse.x, y: corpse.y, seat: corpse.seat });
+      return;
+    }
+    // 同一具尸体的后续观测：补全先前缺失的坐标 / 座位（首见常是无坐标的 state.corpses 条目）。
+    if (existing.x == null && corpse.x != null) { existing.x = corpse.x; existing.y = corpse.y; }
+    if (existing.seat == null && corpse.seat != null) existing.seat = corpse.seat;
+  }
+
+  private isSameBody(c: CorpseInfo, other: { x?: number; y?: number }, name: string): boolean {
+    if (name && c.name) return c.name === name; // 两边都有名：同名才是同一具
+    if (c.x != null && c.y != null && other.x != null && other.y != null) {
+      return dist(c.x, c.y, other.x, other.y) <= CORPSE_SAME_BODY_RADIUS;
+    }
+    return false; // 无名且坐标不全：无法判同，按新尸体处理（极退化，几乎不出现）
+  }
+}
+
+export function reportCorpseDecision(
+  state: GameState,
+  ctx: StrategyContext,
+  opts: { respectBlock?: boolean } = {},
+): BehaviorDecision | null {
+  const reportBlocked = opts.respectBlock && Date.now() < ctx.reportBlockedUntil;
+
+  const reportable = nearestReportableCorpse(state);
+  if (reportable && !reportBlocked) {
+    ctx.reportCorpseTarget = null;
+    ctx.notifications.push(`发现尸体，正在报告！`);
+    return { action: Action.report(reportable.name, reportable.room) };
+  }
+
+  const corpse = nearestKnownCorpse(state, ctx);
+  if (corpse) {
+    if (!ctx.reportCorpseTarget) {
+      ctx.notifications.push(`发现尸体，正在靠近准备报告。`);
+    }
+    ctx.reportCorpseTarget = corpse;
+    return { action: Action.move({ x: corpse.x, y: corpse.y }) };
+  }
+
+  ctx.reportCorpseTarget = null;
+  return null;
+}
+
+export function nonTeammatesVisible(state: GameState, ctx: StrategyContext): PlayerInfo[] {
+  const players = visibleLivePlayers(state, ctx);
+  return ctx.teammates.size > 0
+    ? players.filter(p => !ctx.teammates.has(p.name))
+    : players;
+}
+
+export function matchesTarget(
+  target: string,
+  player: { name?: string; seat?: number },
+  ctx: StrategyContext,
+): boolean {
+  const normalized = target.trim().toLowerCase();
+  if (player.name && player.name.toLowerCase() === normalized) return true;
+  if (/^\d+$/.test(target.trim())) {
+    const nameFromSeat = ctx.playerNamesBySeat[target.trim()];
+    if (nameFromSeat && player.name && player.name.toLowerCase() === nameFromSeat.toLowerCase()) return true;
+    if (player.seat != null && String(player.seat) === target.trim()) return true;
+  }
+  return false;
+}
+
+export function matchesAnyTarget(
+  player: { name?: string; seat?: number },
+  targets: string[],
+  ctx: StrategyContext,
+): boolean {
+  return targets.some(target => matchesTarget(target, player, ctx));
+}
+
+export function isTargetAlive(
+  state: GameState,
+  target: string,
+  ctx: StrategyContext,
+): boolean {
+  if (isRecentlyKilledTarget(target, ctx)) return false;
+  const player = state.all_players?.find(p => matchesTarget(target, p, ctx));
+  return player ? player.is_alive !== false : true;
+}
+
+export function isRecentlyKilledTarget(target: string, ctx: StrategyContext): boolean {
+  const names = targetNames(target, ctx);
+  for (const name of names) {
+    const until = ctx.recentlyKilledTargets?.get(name);
+    if (!until) continue;
+    if (until > Date.now()) return true;
+    ctx.recentlyKilledTargets?.delete(name);
+  }
+  return false;
+}
+
+function targetNames(target: string, ctx: StrategyContext): string[] {
+  const normalized = target.trim().toLowerCase();
+  if (!normalized) return [];
+  const names = [normalized];
+  if (/^\d+$/.test(target.trim())) {
+    const nameFromSeat = ctx.playerNamesBySeat[target.trim()];
+    if (nameFromSeat) names.push(nameFromSeat.toLowerCase());
+  }
+  return names;
+}
+
+export function visibleLivePlayers(state: GameState, ctx: StrategyContext): PlayerInfo[] {
+  return state.players.filter(p => isTargetAlive(state, p.name, ctx));
+}
+
+export function nearestPlayerByDistance(state: GameState, players: PlayerInfo[]): PlayerInfo | null {
+  return players
+    .map(p => ({ p, d: p.distance ?? dist(state.you.x, state.you.y, p.x, p.y) }))
+    .sort((a, b) => a.d - b.d)[0]?.p ?? null;
+}
+
+export function nearestVisibleTarget(
+  state: GameState,
+  ctx: StrategyContext,
+  targets: string[],
+): PlayerInfo | null {
+  return nearestPlayerByDistance(
+    state,
+    visibleLivePlayers(state, ctx).filter(p => targets.some(t => matchesTarget(t, p, ctx))),
+  );
+}
+
+export function pursueVisibleTarget(
+  state: GameState,
+  target: PlayerInfo,
+  opts: { kill: boolean; followDistance: number },
+): BehaviorDecision | null {
+  const d = target.distance ?? dist(state.you.x, state.you.y, target.x, target.y);
+  if (opts.kill && !hasKillUseRemaining(state)) return null;
+  if (opts.kill && d <= KILL_RANGE && canUseKill(state)) {
+    return { action: Action.kill(target.name) };
+  }
+  if (d > opts.followDistance) {
+    return { action: Action.move({ x: target.x, y: target.y }) };
+  }
+  return null;
+}
+
+// ── 知识系统语义助手 ────────────────────────────────────────────────
+// 把 ctx.knowledge 的查询统一成「躲/杀/护」三种意图，供内置与用户策略复用。
+// 见 docs/策略知识系统-by-claude.md。
+
+type PlayerRef = { name?: string; seat?: number };
+const FALLBACK_KNOWLEDGE = emptyKnowledgeView();
+
+function knowledgeOf(ctx: StrategyContext) {
+  return ctx.knowledge ?? FALLBACK_KNOWLEDGE;
+}
+
+/** hostile：带刀策略可主动攻击；无刀策略应回避。 */
+export function isKnowledgeHostile(p: PlayerRef, ctx: StrategyContext, minConfidence?: number): boolean {
+  return knowledgeOf(ctx).isHostile(p, minConfidence);
+}
+
+/** suspect 或 hostile：任何生存型策略都应视为威胁并回避。 */
+export function isKnowledgeThreat(p: PlayerRef, ctx: StrategyContext, minConfidence?: number): boolean {
+  const mark = knowledgeOf(ctx).markOf(p, minConfidence);
+  return mark === 'suspect' || mark === 'hostile';
+}
+
+/** trusted：可信同伴，永远优先于回避与击杀。 */
+export function isKnowledgeTrusted(p: PlayerRef, ctx: StrategyContext, minConfidence?: number): boolean {
+  return knowledgeOf(ctx).isTrusted(p, minConfidence);
+}
+
+/** @deprecated Use isKnowledgeHostile. */
+export const isKnowledgeKillTarget = isKnowledgeHostile;
+/** @deprecated Use isKnowledgeThreat. */
+export const isKnowledgeAvoid = isKnowledgeThreat;
+/** @deprecated Use isKnowledgeTrusted. */
+export const isKnowledgeProtected = isKnowledgeTrusted;
+
+export function resolveRoom(name: string, ctx: StrategyContext): RoomTarget | null {
+  const folded = name.trim().toLowerCase();
+  if (!folded) return null;
+  return ctx.rooms.find(room => room.name.toLowerCase() === folded) ?? null;
+}
+
+export function isInRoom(name: string, state: GameState): boolean {
+  const room = state.you.room;
+  if (!room) return false;
+  return room.toLowerCase() === name.trim().toLowerCase();
+}
+
+export function hasReachedRoomTarget(state: GameState, target: RoomTarget): boolean {
+  return dist(state.you.x, state.you.y, target.x, target.y) <= PATROL_REACHED_DISTANCE;
+}
+
+export function roomAwayFromPlayers(
+  state: GameState,
+  ctx: StrategyContext,
+  players: PlayerInfo[],
+): RoomTarget | null {
+  if (ctx.rooms.length === 0 || players.length === 0) return null;
+  const playerRooms = new Set(players.map(player => player.room?.toLowerCase()).filter(Boolean));
+
+  const nearestPlayer = players
+    .map(player => ({
+      player,
+      distance: player.distance ?? dist(state.you.x, state.you.y, player.x, player.y),
+    }))
+    .sort((a, b) => a.distance - b.distance)[0]?.player;
+  if (!nearestPlayer) return null;
+
+  const awayX = state.you.x - nearestPlayer.x;
+  const awayY = state.you.y - nearestPlayer.y;
+  const awayLen = Math.hypot(awayX, awayY);
+
+  const scored = ctx.rooms.map(room => {
+    const toRoomX = room.x - state.you.x;
+    const toRoomY = room.y - state.you.y;
+    const toRoomLen = Math.hypot(toRoomX, toRoomY);
+    const direction = awayLen > 0 && toRoomLen > 0
+      ? (toRoomX * awayX + toRoomY * awayY) / (toRoomLen * awayLen)
+      : 0;
+    const nearestDistance = Math.min(...players.map(player => dist(room.x, room.y, player.x, player.y)));
+    return {
+      room,
+      direction,
+      nearestDistance,
+      selfDistance: dist(state.you.x, state.you.y, room.x, room.y),
+    };
+  });
+
+  const viable = scored.filter(item => {
+    if (playerRooms.has(item.room.name.toLowerCase())) return false;
+    if (ctx.blockedMoveTarget && dist(item.room.x, item.room.y, ctx.blockedMoveTarget.x, ctx.blockedMoveTarget.y) <= 10) return false;
+    return true;
+  });
+  const base = viable.length > 0 ? viable : scored;
+  const oppositeRooms = base.filter(item => item.direction > 0.15);
+  const candidates = oppositeRooms.length > 0 ? oppositeRooms : base;
+  candidates.sort((a, b) => {
+    const distanceDiff = b.nearestDistance - a.nearestDistance;
+    if (Math.abs(distanceDiff) > 1) return distanceDiff;
+    const directionDiff = b.direction - a.direction;
+    if (Math.abs(directionDiff) > 0.01) return directionDiff;
+    return a.selfDistance - b.selfDistance;
+  });
+  return candidates[0]?.room ?? null;
+}
+
+export class PatrolState {
+  private roomIndex = 0;
+
+  nextRoom(ctx: StrategyContext): RoomTarget | null {
+    if (ctx.rooms.length === 0) return null;
+    if (ctx.forcePatrolAdvance) {
+      ctx.forcePatrolAdvance = false;
+      this.roomIndex = (this.roomIndex + 1) % ctx.rooms.length;
+    }
+    return ctx.rooms[this.roomIndex % ctx.rooms.length];
+  }
+
+  advance(ctx: StrategyContext): void {
+    if (ctx.rooms.length === 0) return;
+    this.roomIndex = (this.roomIndex + 1) % ctx.rooms.length;
+  }
+
+  reset(): void {
+    this.roomIndex = 0;
+  }
+}