@myclaw163/clawclaw-cli 0.6.54

package/src/strategies/pathfind/escape-planner.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import type { Position } from '../../sdk/types.js';
+import { FieldCalculator, PX_PER_UNIT, UNITS_PER_PX } from './distance-field.js';
+import { planEscape, type EscapeOptions } from './escape-planner.js';
+import { loadWalkableGrid } from './walkable-grid.js';
+
+const grid = loadWalkableGrid();
+const sampleCells = collectWalkableCells(3);
+
+const stressOpts = {
+  steps: 4,
+  stepDist: 144,
+  killRange: 80,
+  beamWidth: 6,
+  fieldRadius: 720,
+  directions: 12,
+} satisfies EscapeOptions;
+
+interface Scenario {
+  name: string;
+  shrimp: Position;
+  crabs: Position[];
+}
+
+function collectWalkableCells(stride: number): number[] {
+  const cells: number[] = [];
+  for (let ty = 0; ty < grid.height; ty += stride) {
+    for (let tx = 0; tx < grid.width; tx += stride) {
+      const cell = ty * grid.width + tx;
+      if (grid.isWalkableCell(cell)) cells.push(cell);
+    }
+  }
+  return cells;
+}
+
+function makeRng(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    return state / 0x100000000;
+  };
+}
+
+function randomCell(rng: () => number): number {
+  return sampleCells[Math.floor(rng() * sampleCells.length)];
+}
+
+function toCell(pos: Position): number {
+  return grid.snapToWalkable(grid.worldToCell(pos.x, pos.y));
+}
+
+function expectWalkablePosition(pos: Position): void {
+  const cell = toCell(pos);
+  expect(cell).toBeGreaterThanOrEqual(0);
+  expect(grid.isWalkableCell(cell)).toBe(true);
+}
+
+function nearbyCells(source: number, minPx: number, maxPx: number, rng: () => number, limit: number): number[] {
+  const calc = new FieldCalculator(grid);
+  const maxUnits = Math.round(maxPx * UNITS_PER_PX);
+  const minUnits = Math.round(minPx * UNITS_PER_PX);
+  const field = calc.compute(source, maxUnits, maxUnits, 8);
+  const start = Math.floor(rng() * sampleCells.length);
+  const cells: number[] = [];
+
+  for (let i = 0; i < sampleCells.length && cells.length < limit; i++) {
+    const cell = sampleCells[(start + i) % sampleCells.length];
+    const dist = field.distOf(cell);
+    if (cell !== source && dist >= minUnits && dist <= maxUnits) cells.push(cell);
+  }
+
+  return cells;
+}
+
+function buildScenarios(): Scenario[] {
+  const rng = makeRng(0xdecafbad);
+  const scenarios: Scenario[] = [];
+
+  for (let i = 0; i < 48; i++) {
+    const crabCount = 1 + Math.floor(rng() * 4);
+    scenarios.push({
+      name: `global-${i}`,
+      shrimp: grid.cellToWorld(randomCell(rng)),
+      crabs: Array.from({ length: crabCount }, () => grid.cellToWorld(randomCell(rng))),
+    });
+  }
+
+  let localCount = 0;
+  for (let attempts = 0; localCount < 48 && attempts < 300; attempts++) {
+    const source = randomCell(rng);
+    const near = nearbyCells(source, 88, 360, rng, 32);
+    if (near.length < 4) continue;
+
+    const crabCount = 1 + (localCount % 4);
+    const crabs: Position[] = [];
+    for (let i = 0; i < crabCount; i++) {
+      const index = Math.floor(((i + 0.5) * near.length) / crabCount);
+      crabs.push(grid.cellToWorld(near[index]));
+    }
+
+    scenarios.push({
+      name: `local-${localCount}`,
+      shrimp: grid.cellToWorld(source),
+      crabs,
+    });
+    localCount++;
+  }
+
+  expect(localCount).toBe(48);
+  return scenarios;
+}
+
+function replayPlan(
+  shrimp: Position,
+  crabs: Position[],
+  path: Position[],
+  opts: typeof stressOpts,
+): { minCrabDistance: number; finalCell: number } {
+  const calc = new FieldCalculator(grid);
+  const stepUnits = Math.round(opts.stepDist * UNITS_PER_PX);
+  const radiusUnits = Math.round(opts.fieldRadius * UNITS_PER_PX);
+  let shrimpCell = toCell(shrimp);
+  let crabCells = crabs.map(toCell).filter(cell => cell >= 0);
+
+  for (const waypoint of path) {
+    const nextCell = toCell(waypoint);
+    const field = calc.compute(shrimpCell, radiusUnits, stepUnits, opts.directions);
+    const moveUnits = field.distOf(nextCell);
+    expect(moveUnits).toBeLessThanOrEqual(stepUnits);
+    crabCells = crabCells.map(cell => calc.descend(cell, stepUnits).end);
+    shrimpCell = nextCell;
+  }
+
+  const finalField = calc.compute(shrimpCell, radiusUnits, stepUnits, opts.directions);
+  const minUnits =
+    crabCells.length > 0 ? Math.min(...crabCells.map(cell => Math.min(finalField.distOf(cell), radiusUnits))) : Infinity;
+  return { minCrabDistance: minUnits * PX_PER_UNIT, finalCell: shrimpCell };
+}
+
+function expectPlanShape(plan: ReturnType<typeof planEscape>, opts: typeof stressOpts): void {
+  expect(plan.survivedSteps).toBeGreaterThanOrEqual(0);
+  expect(plan.survivedSteps).toBeLessThanOrEqual(opts.steps);
+  expect(plan.path).toHaveLength(plan.survivedSteps);
+  expect(Number.isNaN(plan.minCrabDistance)).toBe(false);
+  expectWalkablePosition(plan.target);
+  for (const waypoint of plan.path) expectWalkablePosition(waypoint);
+
+  if (plan.survivedSteps > 0) {
+    expect(plan.target).toEqual(plan.path[plan.path.length - 1]);
+  }
+  if (plan.caught) {
+    expect(plan.survivedSteps).toBeLessThan(opts.steps);
+  } else {
+    expect(plan.survivedSteps).toBe(opts.steps);
+  }
+}
+
+describe('planEscape', () => {
+  it('plans a full horizon with infinite safety when there are no crabs', () => {
+    const start = grid.cellToWorld(sampleCells[Math.floor(sampleCells.length / 2)]);
+    const plan = planEscape(start, [], stressOpts);
+
+    expect(plan.caught).toBe(false);
+    expect(plan.survivedSteps).toBe(stressOpts.steps);
+    expect(plan.path).toHaveLength(stressOpts.steps);
+    expect(plan.minCrabDistance).toBe(Infinity);
+    expectPlanShape(plan, stressOpts);
+  });
+
+  it('reports no survived step when crabs already occupy the shrimp tile', () => {
+    const start = grid.cellToWorld(sampleCells[Math.floor(sampleCells.length / 3)]);
+    const plan = planEscape(start, [start, start, start, start], stressOpts);
+
+    expect(plan.caught).toBe(true);
+    expect(plan.survivedSteps).toBe(0);
+    expect(plan.path).toEqual([]);
+    expect(plan.minCrabDistance).toBe(0);
+    expectPlanShape(plan, stressOpts);
+  });
+
+  it('keeps movement and distance invariants across seeded global and local pressure cases', () => {
+    const scenarios = buildScenarios();
+    expect(scenarios).toHaveLength(96);
+
+    for (const scenario of scenarios) {
+      const plan = planEscape(scenario.shrimp, scenario.crabs, stressOpts);
+      const replay = replayPlan(scenario.shrimp, scenario.crabs, plan.path, stressOpts);
+
+      expectPlanShape(plan, stressOpts);
+      expect(toCell(plan.target), scenario.name).toBe(replay.finalCell);
+      expect(plan.minCrabDistance, scenario.name).toBeCloseTo(replay.minCrabDistance, 5);
+      if (!plan.caught) {
+        expect(plan.minCrabDistance, scenario.name).toBeGreaterThan(stressOpts.killRange);
+      }
+    }
+  }, 15_000);
+});

package/src/strategies/pathfind/escape-planner.ts

@@ -0,0 +1,348 @@
+import type { Position } from '../../sdk/types.js';
+import { COST_DIAG, COST_STRAIGHT, FieldCalculator, PX_PER_UNIT, UNITS_PER_PX, type FieldResult } from './distance-field.js';
+import { loadWalkableGrid, type WalkableGrid } from './walkable-grid.js';
+
+// Escape planning against pure-pursuit crabs, in lockstep time steps where
+// every crab walks its shortest walkable path toward the shrimp's position at
+// the start of each step (same speed as the shrimp):
+// - planEscape: beam-search the shrimp move that stays uncaught and maximizes
+//   the final geodesic distance to the nearest crab.
+// - assessEscapeTarget: rate an already-committed target by rolling out the
+//   fixed walk toward it, so callers can keep a target until it turns bad
+//   instead of re-targeting every tick.
+//
+// Model approximations: octile 5/7 geodesics overestimate the server's
+// smoothed paths by up to ~8% (symmetrically for both sides), and the
+// pure-pursuit crab is more pessimistic than real crabs with vision limits.
+
+export interface EscapeOptions {
+  /** Planning horizon in time steps. Default 6. */
+  steps?: number;
+  /** Distance each side covers per step, px. Default 144 (120px/s x 1.2s tick). */
+  stepDist?: number;
+  /** Geodesic distance at or under which the shrimp counts as caught, px. Default 80 (server kill_range). */
+  killRange?: number;
+  /** Beam width. Default 8. */
+  beamWidth?: number;
+  /** Distance field radius, px; crabs beyond it are frozen and scored as this far. Default 900. */
+  fieldRadius?: number;
+  /** Number of angle buckets for shrimp move candidates. Default 16. */
+  directions?: number;
+}
+
+export interface EscapePlan {
+  /** Position after the final step (best struggle endpoint when caught). */
+  target: Position;
+  /** Geodesic distance from target to the nearest simulated crab, px; capped at fieldRadius; Infinity with no crabs. */
+  minCrabDistance: number;
+  /** One waypoint per survived step (tile centers in world coords). */
+  path: Position[];
+  /** True when every branch gets caught within the horizon. */
+  caught: boolean;
+  survivedSteps: number;
+}
+
+export interface TargetAssessment {
+  /** Geodesic distance from the shrimp's current position to the target, px; Infinity if unreachable. */
+  distanceToTarget: number;
+  /** Geodesic distance to the nearest crab when the rollout ends (arrival, horizon, or last safe step when caught), px; capped at fieldRadius; Infinity with no crabs. */
+  minCrabDistance: number;
+  /** True when walking the fixed path to the target gets caught within the horizon. */
+  caught: boolean;
+  survivedSteps: number;
+}
+
+interface Node {
+  cell: number;
+  crabCells: number[];
+  depth: number;
+  parent: Node | null;
+  /** Lower bound on the min crab distance, px (beam ranking only). */
+  proxy: number;
+}
+
+interface ResolvedOptions {
+  steps: number;
+  killRange: number;
+  beamWidth: number;
+  directions: number;
+  stepUnits: number;
+  killUnits: number;
+  radiusUnits: number;
+}
+
+function resolveOptions(opts: EscapeOptions): ResolvedOptions {
+  const steps = opts.steps ?? 6;
+  const stepDist = opts.stepDist ?? 144;
+  const killRange = opts.killRange ?? 80;
+  const beamWidth = opts.beamWidth ?? 8;
+  const fieldRadius = opts.fieldRadius ?? 900;
+  const directions = opts.directions ?? 16;
+  return {
+    steps,
+    killRange,
+    beamWidth,
+    directions,
+    stepUnits: Math.round(stepDist * UNITS_PER_PX),
+    killUnits: Math.round(killRange * UNITS_PER_PX),
+    radiusUnits: Math.round(fieldRadius * UNITS_PER_PX),
+  };
+}
+
+interface Planner {
+  grid: WalkableGrid;
+  calc: FieldCalculator;
+}
+
+let planner: Planner | null = null;
+
+function getPlanner(): Planner {
+  if (!planner) {
+    const grid = loadWalkableGrid();
+    planner = { grid, calc: new FieldCalculator(grid) };
+  }
+  return planner;
+}
+
+function snapCell(grid: WalkableGrid, pos: Position): number {
+  return grid.snapToWalkable(grid.worldToCell(pos.x, pos.y));
+}
+
+function snapCrabCells(grid: WalkableGrid, crabs: Position[]): number[] {
+  return crabs.map(crab => snapCell(grid, crab)).filter(cell => cell >= 0);
+}
+
+function euclidPx(grid: WalkableGrid, a: number, b: number): number {
+  const pa = grid.cellToWorld(a);
+  const pb = grid.cellToWorld(b);
+  return Math.hypot(pa.x - pb.x, pa.y - pb.y);
+}
+
+// Both sides traverse their step path in the same time window; sample
+// matching fractions and flag any moment within kill range (euclidean,
+// ignoring walls — slightly conservative). Catches head-on swaps that the
+// endpoint check misses. t=0 is skipped: step-start safety is already
+// established geodesically, and a thin wall can make it euclid-close.
+function pathsCross(grid: WalkableGrid, killRange: number, shrimpPath: number[], crabPath: number[]): boolean {
+  for (let k = 1; k <= 8; k++) {
+    const t = k / 8;
+    const a = shrimpPath[Math.round(t * (shrimpPath.length - 1))];
+    const b = crabPath[Math.round(t * (crabPath.length - 1))];
+    if (euclidPx(grid, a, b) <= killRange) return true;
+  }
+  return false;
+}
+
+/** One pursuit step: every crab descends the latest field (source = shrimp) by stepUnits. */
+function pursuitStep(calc: FieldCalculator, crabCells: number[], stepUnits: number): { end: number; cells: number[] }[] {
+  return crabCells.map(cell => calc.descend(cell, stepUnits));
+}
+
+export function planEscape(shrimp: Position, crabs: Position[], opts: EscapeOptions = {}): EscapePlan {
+  const { grid, calc } = getPlanner();
+  const o = resolveOptions(opts);
+
+  const start = snapCell(grid, shrimp);
+  if (start < 0) {
+    return { target: shrimp, minCrabDistance: Infinity, path: [], caught: false, survivedSteps: 0 };
+  }
+  const crabCells = snapCrabCells(grid, crabs);
+
+  let frontier: Node[] = [{ cell: start, crabCells, depth: 0, parent: null, proxy: 0 }];
+  let bestLeaf: { node: Node; minUnits: number } | null = null;
+  let struggle: { node: Node; minUnits: number } | null = null;
+
+  while (frontier.length > 0) {
+    const children: Node[] = [];
+    for (const node of frontier) {
+      const field: FieldResult = calc.compute(node.cell, o.radiusUnits, o.stepUnits, o.directions);
+      const crabDists = node.crabCells.map(cell => Math.min(field.distOf(cell), o.radiusUnits));
+      const minUnits = crabDists.length > 0 ? Math.min(...crabDists) : Infinity;
+
+      // End-of-step catch check, deferred to expansion: this field's source is
+      // the shrimp position and the crabs have already taken last step's move.
+      if (node.depth > 0 && minUnits <= o.killUnits) continue;
+      if (
+        !struggle ||
+        node.depth > struggle.node.depth ||
+        (node.depth === struggle.node.depth && minUnits > struggle.minUnits)
+      ) {
+        struggle = { node, minUnits };
+      }
+      if (node.depth === o.steps) {
+        if (!bestLeaf || minUnits > bestLeaf.minUnits) bestLeaf = { node, minUnits };
+        continue;
+      }
+
+      // Pure pursuit: each crab descends this field toward the shrimp's
+      // step-start position.
+      const crabMoves = pursuitStep(calc, node.crabCells, o.stepUnits);
+      const newCrabCells = crabMoves.map(move => move.end);
+      const dangerous: number[] = [];
+      crabDists.forEach((d, i) => {
+        if (d <= o.killUnits + 2 * o.stepUnits) dangerous.push(i);
+      });
+
+      const candidates: number[] = [node.cell];
+      for (const cell of field.ringCandidates) if (cell >= 0) candidates.push(cell);
+      for (const cand of candidates) {
+        const shrimpPath = cand === node.cell ? [node.cell] : calc.pathToSource(cand);
+        if (dangerous.some(i => pathsCross(grid, o.killRange, shrimpPath, crabMoves[i].cells))) continue;
+        const candUnits = field.distOf(cand);
+        let proxy = Infinity;
+        for (const crab of newCrabCells) {
+          const crabUnits = field.distOf(crab);
+          const triangle = crabUnits === Infinity ? o.radiusUnits : crabUnits - candUnits;
+          proxy = Math.min(proxy, Math.max(euclidPx(grid, cand, crab), triangle * PX_PER_UNIT));
+        }
+        children.push({ cell: cand, crabCells: newCrabCells, depth: node.depth + 1, parent: node, proxy });
+      }
+    }
+    if (children.length === 0) break;
+    const byCell = new Map<number, Node>();
+    for (const child of children) {
+      const seen = byCell.get(child.cell);
+      if (!seen || child.proxy > seen.proxy) byCell.set(child.cell, child);
+    }
+    frontier = [...byCell.values()].sort((a, b) => b.proxy - a.proxy).slice(0, o.beamWidth);
+  }
+
+  const result = bestLeaf ?? struggle!;
+  const path: Position[] = [];
+  for (let n: Node | null = result.node; n && n.depth > 0; n = n.parent) {
+    path.unshift(grid.cellToWorld(n.cell));
+  }
+  return {
+    target: result.node.depth > 0 ? grid.cellToWorld(result.node.cell) : grid.cellToWorld(start),
+    minCrabDistance: result.minUnits * PX_PER_UNIT,
+    path,
+    caught: !bestLeaf,
+    survivedSteps: result.node.depth,
+  };
+}
+
+/**
+ * Fixed-policy rollout: the shrimp walks its initial geodesic path toward the
+ * target (mirroring the server's single A* at move submission) while the crabs
+ * pure-pursue each step, with the same catch semantics as planEscape. The
+ * rollout ends on arrival, at the horizon, or when caught.
+ */
+export function assessEscapeTarget(shrimp: Position, crabs: Position[], target: Position, opts: EscapeOptions = {}): TargetAssessment {
+  const { grid, calc } = getPlanner();
+  const o = resolveOptions(opts);
+
+  const start = snapCell(grid, shrimp);
+  const targetCell = start >= 0 ? snapCell(grid, target) : -1;
+  if (start < 0 || targetCell < 0) {
+    return { distanceToTarget: Infinity, minCrabDistance: Infinity, caught: false, survivedSteps: 0 };
+  }
+  let crabCells = snapCrabCells(grid, crabs);
+
+  // The walk path is fixed up front; extract it (and the target distance)
+  // before the per-step fields invalidate this one.
+  const reach = calc.compute(start, o.radiusUnits + o.steps * o.stepUnits, 0);
+  const targetUnits = reach.distOf(targetCell);
+  if (targetUnits === Infinity) {
+    return { distanceToTarget: Infinity, minCrabDistance: Infinity, caught: false, survivedSteps: 0 };
+  }
+  const walkPath = calc.pathToSource(targetCell);
+  const W = grid.width;
+  const cumUnits = new Array<number>(walkPath.length);
+  cumUnits[0] = 0;
+  for (let i = 1; i < walkPath.length; i++) {
+    const a = walkPath[i - 1];
+    const b = walkPath[i];
+    const diagonal = a % W !== b % W && Math.floor(a / W) !== Math.floor(b / W);
+    cumUnits[i] = cumUnits[i - 1] + (diagonal ? COST_DIAG : COST_STRAIGHT);
+  }
+
+  let shrimpIdx = 0;
+  let caught = false;
+  let survivedSteps = 0;
+  let minUnitsAtEnd = Infinity;
+
+  for (let depth = 0; ; depth++) {
+    const cell = walkPath[shrimpIdx];
+    const field = calc.compute(cell, o.radiusUnits, 0);
+    const crabDists = crabCells.map(c => Math.min(field.distOf(c), o.radiusUnits));
+    const minUnits = crabDists.length > 0 ? Math.min(...crabDists) : Infinity;
+
+    // Same end-of-step semantics as planEscape: at depth > 0 the crabs have
+    // already taken last step's move toward the previous shrimp position.
+    if (depth > 0 && minUnits <= o.killUnits) {
+      caught = true;
+      break;
+    }
+    survivedSteps = depth;
+    minUnitsAtEnd = minUnits;
+    if (depth === o.steps || shrimpIdx >= walkPath.length - 1) break;
+
+    const crabMoves = pursuitStep(calc, crabCells, o.stepUnits);
+    let nextIdx = shrimpIdx;
+    while (nextIdx < walkPath.length - 1 && cumUnits[nextIdx + 1] - cumUnits[shrimpIdx] <= o.stepUnits) nextIdx++;
+
+    const dangerous: number[] = [];
+    crabDists.forEach((d, i) => {
+      if (d <= o.killUnits + 2 * o.stepUnits) dangerous.push(i);
+    });
+    const segment = walkPath.slice(shrimpIdx, nextIdx + 1);
+    if (dangerous.some(i => pathsCross(grid, o.killRange, segment, crabMoves[i].cells))) {
+      caught = true;
+      break;
+    }
+    crabCells = crabMoves.map(move => move.end);
+    shrimpIdx = nextIdx;
+  }
+
+  return {
+    distanceToTarget: targetUnits * PX_PER_UNIT,
+    minCrabDistance: minUnitsAtEnd * PX_PER_UNIT,
+    caught,
+    survivedSteps,
+  };
+}
+
+export interface RouteInfo {
+  /** 测地距离 px；maxRadiusPx 之外或不可达 = Infinity。 */
+  distancePx: number;
+  /** 测地路径是否经过任一威胁点 threatRadiusPx 内（不可达时恒为 false）。 */
+  nearThreat: boolean;
+}
+
+/** 沿路径每 4 格（16px）采样一次离威胁点的欧氏距离，含末端格；半径 ~200px 下足够密。 */
+function pathNearAny(grid: WalkableGrid, path: number[], threats: Position[], radiusPx: number): boolean {
+  for (let i = 0; i < path.length; i += 4) {
+    const idx = Math.min(i, path.length - 1);
+    const w = grid.cellToWorld(path[idx]);
+    if (threats.some(t => Math.hypot(w.x - t.x, w.y - t.y) <= radiusPx)) return true;
+  }
+  const end = grid.cellToWorld(path[path.length - 1]);
+  return threats.some(t => Math.hypot(end.x - t.x, end.y - t.y) <= radiusPx);
+}
+
+/**
+ * 从 from 到各点的测地距离与「必经之路是否有危险」，一次距离场扫描 + 逐点回溯
+ * 梯度路径查表。threats 为空时只算距离不查路径。from 无法吸附到可走网格时返回
+ * null，调用方退回欧氏距离（且无路径信息）。
+ */
+export function assessRoutes(
+  from: Position,
+  points: Position[],
+  threats: Position[],
+  threatRadiusPx: number,
+  maxRadiusPx = 3000,
+): RouteInfo[] | null {
+  const { grid, calc } = getPlanner();
+  const start = snapCell(grid, from);
+  if (start < 0) return null;
+  const field = calc.compute(start, Math.round(maxRadiusPx * UNITS_PER_PX), 0);
+  return points.map(p => {
+    const cell = snapCell(grid, p);
+    const units = cell >= 0 ? field.distOf(cell) : Infinity;
+    if (units === Infinity) return { distancePx: Infinity, nearThreat: false };
+    return {
+      distancePx: units * PX_PER_UNIT,
+      nearThreat: threats.length > 0 && pathNearAny(grid, calc.pathToSource(cell), threats, threatRadiusPx),
+    };
+  });
+}

package/src/strategies/pathfind/walkable-grid.ts

@@ -0,0 +1,117 @@
+import { readFileSync } from 'fs';
+import type { Position } from '../../sdk/types.js';
+
+// Walkability bitmap baked from the server's inflated_weights (walls already
+// inflated by the agent collision radius, so a walkable tile means the agent
+// center may stand there). Regenerate with scripts/export-walkable-grid.py.
+
+const HEADER_SIZE = 20;
+
+export interface WalkableGrid {
+  readonly width: number;
+  readonly height: number;
+  readonly tileSize: number;
+  isWalkable(tx: number, ty: number): boolean;
+  isWalkableCell(cell: number): boolean;
+  /** cell = ty * width + tx; world coords are clamped into the map. */
+  worldToCell(wx: number, wy: number): number;
+  /** Tile center in world coords. */
+  cellToWorld(cell: number): Position;
+  /** Nearest walkable cell within maxRadius tiles (Chebyshev rings); -1 if none. */
+  snapToWalkable(cell: number, maxRadius?: number): number;
+}
+
+class Grid implements WalkableGrid {
+  readonly width: number;
+  readonly height: number;
+  readonly tileSize: number;
+  private readonly bits: Buffer;
+  private readonly rowBytes: number;
+
+  constructor(buf: Buffer) {
+    if (buf.toString('ascii', 0, 4) !== 'CCWG') throw new Error('walkable grid: bad magic');
+    const version = buf.readUInt32LE(4);
+    if (version !== 1) throw new Error(`walkable grid: unsupported version ${version}`);
+    this.width = buf.readUInt32LE(8);
+    this.height = buf.readUInt32LE(12);
+    this.tileSize = buf.readUInt32LE(16);
+    this.rowBytes = Math.ceil(this.width / 8);
+    if (buf.length !== HEADER_SIZE + this.rowBytes * this.height) {
+      throw new Error('walkable grid: size mismatch');
+    }
+    this.bits = buf;
+  }
+
+  isWalkable(tx: number, ty: number): boolean {
+    if (tx < 0 || ty < 0 || tx >= this.width || ty >= this.height) return false;
+    const byte = this.bits[HEADER_SIZE + ty * this.rowBytes + (tx >> 3)];
+    return ((byte >> (tx & 7)) & 1) === 1;
+  }
+
+  isWalkableCell(cell: number): boolean {
+    return this.isWalkable(cell % this.width, Math.floor(cell / this.width));
+  }
+
+  worldToCell(wx: number, wy: number): number {
+    const tx = Math.min(this.width - 1, Math.max(0, Math.floor(wx / this.tileSize)));
+    const ty = Math.min(this.height - 1, Math.max(0, Math.floor(wy / this.tileSize)));
+    return ty * this.width + tx;
+  }
+
+  cellToWorld(cell: number): Position {
+    const tx = cell % this.width;
+    const ty = Math.floor(cell / this.width);
+    return { x: tx * this.tileSize + this.tileSize / 2, y: ty * this.tileSize + this.tileSize / 2 };
+  }
+
+  snapToWalkable(cell: number, maxRadius = 8): number {
+    const cx = cell % this.width;
+    const cy = Math.floor(cell / this.width);
+    for (let r = 0; r <= maxRadius; r++) {
+      let best = -1;
+      let bestSq = Infinity;
+      for (let dy = -r; dy <= r; dy++) {
+        for (let dx = -r; dx <= r; dx++) {
+          if (Math.max(Math.abs(dx), Math.abs(dy)) !== r) continue;
+          if (!this.isWalkable(cx + dx, cy + dy)) continue;
+          const sq = dx * dx + dy * dy;
+          if (sq < bestSq) {
+            bestSq = sq;
+            best = (cy + dy) * this.width + (cx + dx);
+          }
+        }
+      }
+      if (best >= 0) return best;
+    }
+    return -1;
+  }
+}
+
+let cached: WalkableGrid | null = null;
+
+export function loadWalkableGrid(): WalkableGrid {
+  if (!cached) {
+    cached = new Grid(readFileSync(new URL('./clawclaw-walkable.bin', import.meta.url)));
+  }
+  return cached;
+}
+
+const STOP_NEIGHBORS = [[1, 0], [-1, 0], [0, 1], [0, -1], [1, 1], [1, -1], [-1, 1], [-1, -1]];
+
+/**
+ * A walkable tile center >= 2px away from pos, used to stop in place: the
+ * server ignores moves shorter than 1px without interrupting the current
+ * movement, so stopping means moving somewhere nearby.
+ */
+export function nearbyStopPoint(pos: Position): Position {
+  const grid = loadWalkableGrid();
+  const cell = grid.worldToCell(pos.x, pos.y);
+  const tx = cell % grid.width;
+  const ty = Math.floor(cell / grid.width);
+  for (const [dx, dy] of STOP_NEIGHBORS) {
+    if (grid.isWalkable(tx + dx, ty + dy)) return grid.cellToWorld(cell + dy * grid.width + dx);
+  }
+  const center = grid.cellToWorld(cell);
+  if (Math.hypot(center.x - pos.x, center.y - pos.y) >= 1.5) return center;
+  return { x: pos.x + 2, y: pos.y };
+}

package/src/strategies/patrol.ts

@@ -0,0 +1,11 @@
+import type { StrategyEntry } from './types.js';
+import { GoalRootStrategy } from './goals/goal-root-strategy.js';
+import { PatrolTop } from './goals/patrol-top.js';
+
+export const strategy: StrategyEntry = {
+  id: 'patrol',
+  description: '按地图房间顺序依次游走，到达一个房间后自动前往下一个，循环往复。卡路时会跳过当前目标换下一个房间。纯游走，不做任务、不打人、不报告尸体。',
+  create() {
+    return new GoalRootStrategy('patrol', () => new PatrolTop(), { resetOnMeetingResume: false });
+  },
+};

package/src/strategies/player-targets.ts

@@ -0,0 +1,13 @@
+/** Split CLI args on commas and/or whitespace (Windows may pass `3,5` as one token). */
+export function parseTargetArgs(args: string[]): string[] {
+  return args
+    .flatMap((a) => a.split(/[,\s]+/))
+    .map((t) => t.trim())
+    .filter((t) => t.length > 0);
+}
+
+export const ROLE_ID_RE = /\b(?:shrimp_generic|shrimp_warrior|shrimp_pistol|crab_generic|neutral_paradise_fish|neutral_octopus)\b/g;
+
+export function stripRoleIds(text: string): string {
+  return text.replace(ROLE_ID_RE, '').replace(/\s+/g, ' ').trim();
+}