@myclaw163/clawclaw-cli 0.6.54

package/src/sdk/index.ts

@@ -0,0 +1,110 @@
+/**
+ * @myclaw163/clawclaw-cli — Public SDK
+ * ─────────────────────────────────
+ * 此文件是 @myclaw163/clawclaw-cli 对外的**公开 API**入口,通过 `package.json` 的
+ * `exports` 字段同时暴露在 `@myclaw163/clawclaw-cli` 与 `@myclaw163/clawclaw-cli/sdk` 两个 sub-path。
+ *
+ * 下游项目(适配器、MCP server、其他 agent 集成等)应当只 import 本文件
+ * 重新 export 的符号;凡是从 `@myclaw163/clawclaw-cli/src/...` 深路径直接 import 的,
+ * 视为内部实现,**不在 SemVer 承诺范围内**,可能在任意 minor 版本变更。
+ *
+ * 公开符号:
+ *   · Action            — 不可变动作工厂(move/kill/speech/vote/...)
+ *   · GameClient        — HTTP + WebSocket 游戏客户端
+ *   · GameClientConfig  — 客户端配置类型
+ *   · GameState / PlayerSelf / PlayerInfo / CorpseInfo / TaskInfo /
+ *     EmergencyInfo / Position / GameEvent / MapRoom / GameResult
+ *   · WsConnectionState / ActionErrorCode (enums)
+ *   · Strategy / StrategyContext / StrategyEntry / CustomModule /
+ *     BehaviorDecision / CorpseTarget / RoomTarget
+ *   · game-utils: dist / firstAvailableTask / nearestKnownCorpse / nearestKnownCorpseNav /
+ *     hasKnownCorpse / corpseAtScene / nearestReportableCorpse / safePatrolStep /
+ *     nonTeammatesVisible / matchesTarget / isTargetAlive / nearestVisibleTarget /
+ *     pursueVisibleTarget / killCooldownSecs / hasKillUseRemaining / canUseKill /
+ *     isKnowledgeHostile / isKnowledgeThreat / isKnowledgeTrusted
+ *     (含 @deprecated 别名 isKnowledgeKillTarget / isKnowledgeAvoid / isKnowledgeProtected) /
+ *     PatrolState / SafeTaskOptions / SafePatrolOptions + 常量(TASK_SUBMIT_RADIUS / KILL_RANGE /
+ *     SHRIMP_VISION_RANGE / SHRIMP_VISION_EXIT_BUFFER / SHRIMP_VISION_RELEASE_RANGE /
+ *     FOLLOW_RANGE / PATROL_REACHED_DISTANCE / PROGRESS_INTERVAL_MS)
+ *   · Knowledge (ctx.knowledge): KnowledgeView / SubjectEntry / FactMeta /
+ *     TagMeta / KnowledgeFile / KnowledgeScope / KnowledgeSource /
+ *     PlayerRef / SubjectRef / KnowledgeRef
+ *   · Greeting: parseGreetingArgs / GreetingTracker / MAX_GREETING_PHRASES /
+ *     GREETING_COOLDOWN_MS
+ *
+ * 新增 / 删除本文件的 export 必须走 minor / major 版本号;字段语义变更同理。
+ */
+
+export { Action } from './action.js';
+export { GameClient } from '../lib/game-client.js';
+export type { GameClientConfig } from '../lib/game-client.js';
+export type {
+  GameState, PlayerInfo, PlayerSelf, CorpseInfo, TaskInfo, EmergencyInfo,
+  Position, GameEvent, MapRoom, GameResult,
+  WsConnectionState, ActionErrorCode,
+} from './types.js';
+
+// Strategy framework (for user strategies)
+export type {
+  Strategy, StrategyContext, StrategyEntry, CustomModule,
+  BehaviorDecision, CorpseTarget, RoomTarget,
+} from '../strategies/types.js';
+
+// Game utilities (for user strategies)
+export {
+  dist, firstAvailableTask, nearestKnownCorpse, nearestKnownCorpseNav, hasKnownCorpse, corpseAtScene, nearestReportableCorpse,
+  safePatrolStep,
+  nonTeammatesVisible, matchesTarget, isTargetAlive,
+  nearestVisibleTarget, pursueVisibleTarget,
+  killCooldownSecs, hasKillUseRemaining, canUseKill,
+  isKnowledgeHostile, isKnowledgeThreat, isKnowledgeTrusted,
+  isKnowledgeKillTarget, isKnowledgeAvoid, isKnowledgeProtected,
+  PatrolState,
+  TASK_SUBMIT_RADIUS, KILL_RANGE, SHRIMP_VISION_RANGE, SHRIMP_VISION_EXIT_BUFFER, SHRIMP_VISION_RELEASE_RANGE,
+  FOLLOW_RANGE, PATROL_REACHED_DISTANCE,
+  PROGRESS_INTERVAL_MS,
+} from '../strategies/game-utils.js';
+export type { SafeTaskOptions, SafePatrolOptions } from '../strategies/game-utils.js';
+
+export type {
+  KnowledgeView, SubjectEntry, FactMeta, TagMeta, KnowledgeFile,
+  KnowledgeScope, KnowledgeSource, PlayerMark, PlayerRef, SubjectRef, KnowledgeRef,
+} from '../lib/knowledge-store.js';
+
+// Speech module (for exported strategies that use speech synthesis)
+export { SpeechModule, getSpeechConfigForRole } from '../strategies/speech-module.js';
+export type { SpeechModuleConfig, SpeechEvalResult } from '../strategies/speech-module.js';
+
+// Greeting utilities (for exported strategies that use greeting phrases)
+export { parseGreetingArgs, GreetingTracker, MAX_GREETING_PHRASES, GREETING_COOLDOWN_MS } from '../strategies/greeting.js';
+
+// TTS configuration (for exported strategies that use TTS)
+export { TTS_TEXT_MAX_LENGTH } from '../lib/tts-keys.js';
+
+// Player targeting utilities (for exported strategies)
+export { parseTargetArgs, stripRoleIds } from '../strategies/player-targets.js';
+
+// Goal system (for exported strategies that use the goal framework)
+export { GoalRootStrategy } from '../strategies/goals/goal-root-strategy.js';
+export { TaskOnlyTop } from '../strategies/goals/task-only-top.js';
+export { TaskReportTop } from '../strategies/goals/task-report-top.js';
+export { TaskKillReportTop } from '../strategies/goals/task-kill-report-top.js';
+export { KillFrenzyTop } from '../strategies/goals/kill-frenzy-top.js';
+export { KillLoneTop } from '../strategies/goals/kill-lone-top.js';
+export { KillTargetTop } from '../strategies/goals/kill-target-top.js';
+export { LoneKillTaskTop } from '../strategies/goals/lone-kill-task-top.js';
+export { CrabSabotageTop } from '../strategies/goals/crab-sabotage-top.js';
+export { CorpsePatrolTop } from '../strategies/goals/corpse-patrol-top.js';
+export { ReportPatrolTop } from '../strategies/goals/report-patrol-top.js';
+export { PatrolTop } from '../strategies/goals/patrol-top.js';
+export { NormalShrimpTop } from '../strategies/goals/normal-shrimp-top.js';
+export { WarriorShrimpTop } from '../strategies/goals/warrior-shrimp-top.js';
+export { ParadiseFishTop } from '../strategies/goals/paradise-fish-top.js';
+export { FindPlayerTop } from '../strategies/goals/find-player-top.js';
+export { SocialTaskTop } from '../strategies/goals/social-task-top.js';
+export { AvoidLoneTop } from '../strategies/goals/avoid-lone-top.js';
+export { AvoidPlayersTop } from '../strategies/goals/avoid-players-top.js';
+export { MoveRoomGoal } from '../strategies/goals/move-room-goal.js';
+export { ConversationGoal } from '../strategies/goals/conversation-goal.js';
+
+export type { SocialTarget } from '../strategies/goals/social-task-top.js';

package/src/sdk/types.ts

@@ -0,0 +1,146 @@
+// ─── Spatial ───
+
+export interface Position {
+  x: number;
+  y: number;
+}
+
+export interface MapRoom {
+  id: string;
+  x: number;
+  y: number;
+}
+
+// ─── WebSocket Events ───
+
+export interface GameEvent {
+  type: string;
+  [key: string]: any;
+}
+
+// ─── Action Error Codes ───
+
+export enum ActionErrorCode {
+  TASK_ALREADY_COMPLETED = 'task_already_completed',
+  TASK_NOT_ASSIGNED = 'task_not_assigned_to_you',
+  TASK_ALREADY_IN_PROGRESS = 'task_already_in_progress',
+  NO_SABOTAGE_COMPLETED = 'no_sabotage_completed',
+  ROLE_CANNOT_KILL = 'role_cannot_kill',
+  EMERGENCY_ALREADY_ACTIVE = 'emergency_already_active',
+  TARGET_UNREACHABLE = 'target_unreachable_or_too_far',
+  PATH_NOT_FOUND = 'path_not_found',
+  INVALID_POSITION = 'invalid_position_blocked',
+}
+
+// ─── WebSocket Connection State ───
+
+export enum WsConnectionState {
+  Disconnected = 'disconnected',
+  Connecting = 'connecting',
+  Connected = 'connected',
+  Reconnecting = 'reconnecting',
+  Switching = 'switching',
+}
+
+// ─── Phase ───
+
+export type Phase = 'preparing' | 'wandering' | 'meeting' | 'game_over';
+export type MeetingSubPhase = 'entry' | 'speech' | 'vote';
+
+// ─── Game State ───
+
+export interface PlayerSelf {
+  name: string;
+  x: number;
+  y: number;
+  room: string;
+  seat?: number;
+  role: string;
+  faction: string;
+  is_alive: boolean;
+  kill_cooldown_secs?: number;
+  kills_remaining?: number | null;
+  currently_moving?: boolean;
+  remaining_secs?: number;
+  doing_task?: boolean;
+  task_name?: string;
+}
+
+export interface PlayerInfo {
+  name: string;
+  seat?: number;
+  x: number;
+  y: number;
+  room: string;
+  distance?: number;
+}
+
+export interface CorpseInfo {
+  name: string;
+  seat?: number;
+  room: string;
+  distance?: number;
+  x?: number;
+  y?: number;
+}
+
+export interface MeetingState {
+  caller: string | null;
+  sub_phase: MeetingSubPhase;
+  alive_players: string[];
+  current_speaker?: string | null;
+  speeches_so_far?: Record<string, string>;
+  speeches?: Record<string, string>;
+  votes_submitted?: string[];
+}
+
+export interface TaskInfo {
+  task_id: string;
+  task_name: string;
+  room: string;
+  status: string;
+  x?: number;
+  y?: number;
+  is_fake_shrimp?: boolean;
+  faction?: 'lobster' | 'crab';
+}
+
+export interface EmergencyInfo extends TaskInfo {
+  remaining_secs: number;
+}
+
+export interface GameState {
+  phase: Phase;
+  tick: number;
+  you: PlayerSelf;
+  your_tasks: TaskInfo[];
+  players: PlayerInfo[];
+  corpses: CorpseInfo[];
+  emergency?: EmergencyInfo;
+  task_progress?: { completed: number; goal: number };
+  new_events?: Array<Record<string, any>>;
+  stale: boolean;
+  meeting?: MeetingState;
+  winner?: string | null;
+  win_reason?: string;
+  all_players?: Array<{ name: string; role: string; is_alive: boolean; seat: number }>;
+  settlement?: Record<string, any>;
+  game_id?: string;
+  last_ejected?: string | null;
+  last_votes?: Record<string, string>;
+  [key: string]: any;
+}
+
+// ─── Review ───
+
+export interface GameResult {
+  gameId: string;
+  won: boolean;
+  role: string;
+  faction: string;
+  winner: string;
+  winReason: string;
+  survivedToEnd: boolean;
+  totalTicks: number;
+  allPlayers: Array<{ name: string; role: string; is_alive: boolean; seat: number }>;
+}

package/src/strategies/avoid-lone.ts

@@ -0,0 +1,11 @@
+import type { StrategyEntry } from './types.js';
+import { GoalRootStrategy } from './goals/goal-root-strategy.js';
+import { AvoidLoneTop } from './goals/avoid-lone-top.js';
+
+export const strategy: StrategyEntry = {
+  id: 'avoid-lone',
+  description: '避免落单。视野里只有一个人时寻路躲避主动避开（推演逃点、持续远离）；视野里有两人以上时跟住次近的玩家、把可见人数维持在 ≥2（最近的人本就贴着不会丢，次近的人才是跌回一对一的临界）；持续无人或没有当前目标时巡逻。',
+  create() {
+    return new GoalRootStrategy('avoid-lone', () => new AvoidLoneTop(), { resetOnMeetingResume: false });
+  },
+};

package/src/strategies/avoid-players.knowledge.md

@@ -0,0 +1,20 @@
+# avoid-players 知识契约
+
+`avoid-players` 读取统一的玩家三档标记：
+
+| 标记 | 行为 |
+|------|------|
+| `suspect` | 加入回避名单，进入视野便逃离 |
+| `hostile` | 加入回避名单，进入视野便逃离 |
+| `trusted` | 不因知识标记而回避 |
+
+回避名单 = 启动参数（座位号/名字）∪ suspect/hostile 标记。威胁消失后恢复巡逻。
+
+```bash
+ccl knowledge mark 4 suspect --confidence 0.7 --note "贴脸尾随"
+ccl knowledge mark 4 hostile --confidence 0.9 --note "确认危险"
+ccl knowledge mark 4 trusted --note "已澄清"
+ccl knowledge del player 4
+```
+
+`role` 是纯身份事实，不直接控制策略。

package/src/strategies/avoid-players.ts

@@ -0,0 +1,15 @@
+import type { StrategyEntry } from './types.js';
+import { GoalRootStrategy } from './goals/goal-root-strategy.js';
+import { AvoidPlayersTop } from './goals/avoid-players-top.js';
+import { parseTargetArgs } from './player-targets.js';
+
+export const strategy: StrategyEntry = {
+  id: 'avoid-players',
+  description: '回避玩家：按房间顺序巡逻，视野里出现回避目标就寻路躲避（推演逃点、持续远离），威胁消失后恢复巡逻。回避名单 = 启动参数（座位号或名字，可多人，可省略）∪ 知识库中标记为 suspect/hostile 的玩家；trusted 不回避。Agent 可用 `ccl knowledge mark` 动态改判，免重启。',
+  create(args?: string[]) {
+    const targets = args ? parseTargetArgs(args) : [];
+    return new GoalRootStrategy('avoid-players', () => new AvoidPlayersTop(targets), {
+      resetOnMeetingResume: false,
+    });
+  },
+};

package/src/strategies/corpse-patrol.ts

@@ -0,0 +1,22 @@
+import type { StrategyEntry } from './types.js';
+import { GoalRootStrategy } from './goals/goal-root-strategy.js';
+import { CorpsePatrolTop } from './goals/corpse-patrol-top.js';
+import { parseGreetingArgs } from './greeting.js';
+
+class CorpsePatrolStrategy extends GoalRootStrategy {
+  constructor(private readonly greetingPhrases: string[]) {
+    super('corpse-patrol', () => new CorpsePatrolTop(greetingPhrases), { resetOnMeetingResume: false });
+  }
+
+  speechWarmupTexts(): string[] {
+    return this.greetingPhrases;
+  }
+}
+
+export const strategy: StrategyEntry = {
+  id: 'corpse-patrol',
+  description: '发现尸体就在附近40至100距离内随机游荡，但不报告——故意在尸体旁出没制造嫌疑感。没有尸体时巡逻各房间。传入打招呼话术时，视野内出现人就随机发送一条，之后120秒内不再发言。不做任务，不杀人。（天堂鱼默认；进阶版见 paradise-fish）参数：可选：1~3 条打招呼话术。',
+  create(args?: string[]) {
+    return new CorpsePatrolStrategy(parseGreetingArgs(args, 'corpse-patrol'));
+  },
+};

package/src/strategies/crab-sabotage.ts

@@ -0,0 +1,21 @@
+import type { StrategyEntry } from './types.js';
+import { GoalRootStrategy } from './goals/goal-root-strategy.js';
+import { CrabSabotageTop } from './goals/crab-sabotage-top.js';
+import { ConversationGoal } from './goals/conversation-goal.js';
+import { SpeechModule, getSpeechConfigForRole } from './speech-module.js';
+
+export const strategy: StrategyEntry = {
+  id: 'crab-sabotage',
+  description: '优先完成蟹的真实破坏任务（破坏点紧挨已知尸体时会跳过）；做完立刻触发紧急警报；警报期照样会被举报、不乱杀，只清真正落单的目标。有紧急事件时跳过破坏流程。视野里只有一个非队友且冷却可用就靠近，进入50距离就立刻出刀，即使正在做破坏任务；刀在冷却时不追不等、改做低优先级任务伪装，冷却好且目标仍落单可见再出刀；正在做任务时不会撇下任务去追猎（贴脸且刀好仍会立刻出刀）。发现尸体且附近有非队友、但当前不能原地出刀时，会靠近并报告尸体。视野里出现两人以上时，暂停攻击10秒并做任务伪装，先做真实任务再做虾的伪装任务；选任务时会跳过紧挨已知尸体（含看见过、已离开视野的）的任务。没有可做任务时按房间巡逻，绝不停在原地。（普通蟹默认）',
+  create(args?: string[]) {
+    const role = args?.[0] ?? 'crab_generic';
+    let convo: ConversationGoal | null = null;
+    return new GoalRootStrategy('crab-sabotage', () => {
+      convo = new ConversationGoal(() => new CrabSabotageTop(), new SpeechModule(getSpeechConfigForRole(role)));
+      return convo;
+    }, {
+      resetOnMeetingResume: false,
+      onUpdateRole: role => convo?.updateConfig(role),
+    });
+  },
+};

package/src/strategies/custom-module.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, expect } from 'vitest';
+import type { BehaviorDecision, CustomModule, Strategy, StrategyContext, StrategyEntry } from './types.js';
+import type { GameState } from '../sdk/types.js';
+import { Action } from '../sdk/action.js';
+import { emptyKnowledgeView } from '../lib/knowledge-store.js';
+
+function makeMoveDecision(): BehaviorDecision {
+  return { action: Action.move({ x: 100, y: 100 }) };
+}
+
+function makeKillDecision(): BehaviorDecision {
+  return { action: Action.kill('target') };
+}
+
+class TestCustomModule implements CustomModule {
+  processEventsCalled = 0;
+  afterDecideCalled = 0;
+  onMeetingResumeCalled = 0;
+  onMapLoadedCalled = 0;
+  lastTick = -1;
+  lastEventCount = 0;
+  lastRooms: any[] = [];
+  lastState: GameState | null = null;
+  lastDecisions: BehaviorDecision[] = [];
+
+  processEvents(events: any[], tick: number, state: GameState): void {
+    this.processEventsCalled++;
+    this.lastTick = tick;
+    this.lastEventCount = events.length;
+    this.lastState = state;
+  }
+
+  afterDecide(decisions: BehaviorDecision[], _state: GameState, _ctx: StrategyContext): BehaviorDecision[] {
+    this.afterDecideCalled++;
+    this.lastDecisions = decisions;
+    return decisions;
+  }
+
+  onMeetingResume(): void {
+    this.onMeetingResumeCalled++;
+  }
+
+  onMapLoaded(rawRooms: any[]): void {
+    this.onMapLoadedCalled++;
+    this.lastRooms = rawRooms;
+  }
+}
+
+/** Module that filters out move decisions (simulates SpeechModule suppress behavior). */
+class SuppressMoveModule implements CustomModule {
+  processEvents(_events: any[], _tick: number, _state: GameState): void {}
+  afterDecide(decisions: BehaviorDecision[], _state: GameState, _ctx: StrategyContext): BehaviorDecision[] {
+    return decisions.filter(d => d.action.type !== 'move');
+  }
+}
+
+class TestCustomModuleStrategy implements Strategy {
+  readonly name = 'test-custom-module';
+  private module: TestCustomModule;
+
+  constructor() {
+    this.module = new TestCustomModule();
+  }
+
+  customModules(): CustomModule[] {
+    return [this.module];
+  }
+
+  decide() {
+    return [];
+  }
+}
+
+const testEntry: StrategyEntry = {
+  id: 'test-custom-module',
+  description: 'Internal test strategy for CustomModule verification.',
+  create() {
+    return new TestCustomModuleStrategy();
+  },
+};
+
+const FAKE_STATE = { phase: 'wandering', tick: 1 } as GameState;
+
+function makeCtx(overrides: Partial<StrategyContext> = {}): StrategyContext {
+  return {
+    taskData: [],
+    emergency: null,
+    taskLocalBlockedUntil: 0,
+    reportCorpseTarget: null,
+    reportBlockedUntil: 0,
+    notifications: [],
+    lastProgressNotifyAt: 0,
+    teammates: new Set(),
+    alarmDone: false,
+    rooms: [],
+    playerNamesBySeat: {},
+    forcePatrolAdvance: false,
+    blockedMoveTarget: null,
+    mySeat: 1,
+    speechNotifications: [],
+    agentAlerts: [],
+    knowledge: emptyKnowledgeView(),
+    ...overrides,
+  };
+}
+
+describe('CustomModule interface', () => {
+  describe('TestCustomModule lifecycle', () => {
+    it('processEvents receives events, tick, and state', () => {
+      const mod = new TestCustomModule();
+      const events = [{ type: 'player_moved', actor: 'p1' }, { type: 'kill', actor: 'p2' }];
+
+      mod.processEvents(events, 42, FAKE_STATE);
+
+      expect(mod.processEventsCalled).toBe(1);
+      expect(mod.lastTick).toBe(42);
+      expect(mod.lastEventCount).toBe(2);
+      expect(mod.lastState).toBe(FAKE_STATE);
+    });
+
+    it('afterDecide receives and can modify decisions', () => {
+      const mod = new TestCustomModule();
+      const decisions = [makeMoveDecision(), makeKillDecision()];
+
+      const result = mod.afterDecide(decisions, FAKE_STATE, makeCtx());
+
+      expect(mod.afterDecideCalled).toBe(1);
+      expect(result).toEqual(decisions);
+    });
+
+    it('onMeetingResume is callable', () => {
+      const mod = new TestCustomModule();
+      mod.onMeetingResume();
+      mod.onMeetingResume();
+      expect(mod.onMeetingResumeCalled).toBe(2);
+    });
+
+    it('onMapLoaded receives raw rooms', () => {
+      const mod = new TestCustomModule();
+      const rooms = [{ name: 'room1', polygon: [[0, 0], [10, 0], [10, 10], [0, 10]] }];
+
+      mod.onMapLoaded(rooms);
+
+      expect(mod.onMapLoadedCalled).toBe(1);
+      expect(mod.lastRooms).toEqual(rooms);
+    });
+  });
+
+  describe('Strategy.customModules()', () => {
+    it('test strategy returns modules via customModules()', () => {
+      const strat = testEntry.create();
+      expect(strat.customModules).toBeDefined();
+
+      const modules = strat.customModules!();
+      expect(modules).toHaveLength(1);
+      expect(modules[0]).toBeInstanceOf(TestCustomModule);
+    });
+
+    it('customModules() returns the same instance on repeated calls', () => {
+      const strat = testEntry.create();
+      const a = strat.customModules!();
+      const b = strat.customModules!();
+      expect(a[0]).toBe(b[0]);
+    });
+  });
+
+  describe('Strategy-loop lifecycle simulation', () => {
+    it('simulates processEvents → afterDecide → onMeetingResume → onMapLoaded sequence', () => {
+      const strat = testEntry.create();
+      const modules = strat.customModules!();
+      const mod = modules[0] as TestCustomModule;
+      const ctx = makeCtx();
+
+      // Simulate 3 ticks: processEvents then afterDecide
+      for (let tick = 1; tick <= 3; tick++) {
+        mod.processEvents([{ type: 'player_moved' }], tick, FAKE_STATE);
+        mod.afterDecide([makeMoveDecision()], FAKE_STATE, ctx);
+      }
+      expect(mod.processEventsCalled).toBe(3);
+      expect(mod.afterDecideCalled).toBe(3);
+      expect(mod.lastTick).toBe(3);
+
+      // Simulate map load
+      mod.onMapLoaded?.([{ name: 'kitchen' }, { name: 'medbay' }]);
+      expect(mod.onMapLoadedCalled).toBe(1);
+
+      // Simulate meeting end
+      mod.onMeetingResume?.();
+      expect(mod.onMeetingResumeCalled).toBe(1);
+
+      // Post-meeting tick
+      mod.processEvents([{ type: 'session_started' }], 4, FAKE_STATE);
+      mod.afterDecide([], FAKE_STATE, ctx);
+      expect(mod.processEventsCalled).toBe(4);
+      expect(mod.afterDecideCalled).toBe(4);
+    });
+  });
+
+  describe('afterDecide pipeline', () => {
+    it('module can filter decisions (chained)', () => {
+      const mod = new SuppressMoveModule();
+      const decisions = [makeKillDecision(), makeMoveDecision()];
+
+      const result = mod.afterDecide(decisions, FAKE_STATE, makeCtx());
+
+      expect(result).toHaveLength(1);
+      expect(result[0].action.type).toBe('kill');
+    });
+
+    it('multiple modules chain by registration order', () => {
+      const mod1 = new TestCustomModule();
+      const mod2 = new SuppressMoveModule();
+      const modules: CustomModule[] = [mod1, mod2];
+      const ctx = makeCtx();
+
+      let decisions: BehaviorDecision[] = [makeKillDecision(), makeMoveDecision()];
+      for (const mod of modules) {
+        if (mod.afterDecide) {
+          decisions = mod.afterDecide(decisions, FAKE_STATE, ctx);
+        }
+      }
+
+      // mod1 saw both decisions, mod2 filtered out move
+      expect(mod1.lastDecisions).toHaveLength(2);
+      expect(decisions).toHaveLength(1);
+      expect(decisions[0].action.type).toBe('kill');
+    });
+
+    it('module without afterDecide is skipped', () => {
+      const minimal: CustomModule = {
+        processEvents(_events, _tick) {},
+      };
+      const decisions = [makeMoveDecision()];
+      const ctx = makeCtx();
+
+      // afterDecide is optional — strategy-loop skips if undefined
+      const result = minimal.afterDecide
+        ? minimal.afterDecide(decisions, FAKE_STATE, ctx)
+        : decisions;
+
+      expect(result).toBe(decisions);
+    });
+  });
+
+  describe('CustomModule type conformance', () => {
+    it('module with only processEvents satisfies CustomModule', () => {
+      const minimal: CustomModule = {
+        processEvents(_events, _tick) {},
+      };
+      expect(minimal.processEvents).toBeDefined();
+      expect(minimal.afterDecide).toBeUndefined();
+      expect(minimal.onMeetingResume).toBeUndefined();
+      expect(minimal.onMapLoaded).toBeUndefined();
+    });
+
+    it('module with all hooks satisfies CustomModule', () => {
+      const full: CustomModule = {
+        processEvents(_events, _tick) {},
+        afterDecide(d, _state, _ctx) { return d; },
+        onMeetingResume() {},
+        onMapLoaded(_rooms) {},
+      };
+      expect(full.processEvents).toBeDefined();
+      expect(full.afterDecide).toBeDefined();
+      expect(full.onMeetingResume).toBeDefined();
+      expect(full.onMapLoaded).toBeDefined();
+    });
+  });
+});

package/src/strategies/find-player.ts

@@ -0,0 +1,16 @@
+import type { StrategyEntry } from './types.js';
+import { GoalRootStrategy } from './goals/goal-root-strategy.js';
+import { FindPlayerTop } from './goals/find-player-top.js';
+import { parseTargetArgs } from './player-targets.js';
+
+export const strategy: StrategyEntry = {
+  id: 'find-player',
+  description: '全力寻找并贴身跟踪一个指定目标（座位号或名字，单个）。看到就贴上去近距离尾随（约40距离）；跟丢就先奔向最后出现的位置，再按房间顺序不停巡逻直到目标重新出现，绝不放弃。只跟踪、不出刀、不做任务、不报告；目标死亡即停。',
+  create(args?: string[]) {
+    const targets = args ? parseTargetArgs(args) : [];
+    if (targets.length === 0) {
+      throw new Error('find-player strategy requires a target seat number or player name as argument.');
+    }
+    return new GoalRootStrategy('find-player', () => new FindPlayerTop(targets[0]), { resetOnMeetingResume: false });
+  },
+};