mioku-plugin-mc 2.0.0 → 3.0.0

package/play/debug/commands.ts

@@ -0,0 +1,289 @@
+import type { PlayManager } from "../index";
+
+export interface DebugCommandContext {
+  text: string;
+  isOwner: boolean;
+  debugEnabled: boolean;
+  playManager: PlayManager;
+  groupId: number;
+}
+
+const OVERLAY_NAMES = ["defend", "auto_eat"];
+const KNOWN_COMMANDS = new Set([
+  "/join",
+  "/play",
+  "/exit",
+  "/say",
+  "/motion",
+  "/stop",
+  "/clear",
+  "/status",
+  "/behaviors",
+  "/off",
+  "/missions",
+  "/actions",
+  "/stopmission",
+]);
+
+export function isDebugCommand(text: string): boolean {
+  const head = text.trim().split(/\s+/)[0]?.toLowerCase();
+  return !!head && KNOWN_COMMANDS.has(head);
+}
+
+const OVERLAY_HELP: Record<string, string> = {
+  defend: "自动战斗。半径内有敌对生物时抢占移动去攻击。参数: [radius=<格, 默认8>]",
+  auto_eat: "自动进食。饥饿且有食物且不在战斗时进食。",
+};
+
+interface ParsedBundleArgs {
+  bundle: string;
+  params: Record<string, unknown>;
+}
+
+function parseBundleArgs(arg: string): ParsedBundleArgs | null {
+  const trimmed = arg.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith("{")) {
+    try {
+      const obj = JSON.parse(trimmed);
+      if (obj && typeof obj === "object" && typeof obj.bundle === "string") {
+        return {
+          bundle: obj.bundle,
+          params:
+            obj.params && typeof obj.params === "object"
+              ? (obj.params as Record<string, unknown>)
+              : {},
+        };
+      }
+    } catch {
+      return null;
+    }
+  }
+  const parts = trimmed.split(/\s+/);
+  const bundle = parts[0];
+  if (!bundle.startsWith("task.")) return null;
+  const params: Record<string, unknown> = {};
+  for (let i = 1; i < parts.length; i++) {
+    const eq = parts[i].indexOf("=");
+    if (eq > 0) {
+      const k = parts[i].slice(0, eq);
+      const raw = parts[i].slice(eq + 1);
+      const asNum = Number(raw);
+      params[k] = Number.isFinite(asNum) && raw !== "" ? asNum : raw;
+    }
+  }
+  return { bundle, params };
+}
+
+export async function handleDebugCommand(
+  ctx: DebugCommandContext,
+): Promise<string | null> {
+  if (!ctx.debugEnabled || !ctx.isOwner) return null;
+  const text = ctx.text.trim();
+  if (!text.startsWith("/")) return null;
+  const head = text.split(/\s+/)[0]?.toLowerCase();
+  if (!head || !KNOWN_COMMANDS.has(head)) return null;
+
+  const arg = text.slice(head.length).trim();
+  const pm = ctx.playManager;
+  const groupId = ctx.groupId;
+
+  switch (head) {
+    case "/join": {
+      if (!arg) return "用法: /join <服务器ID>";
+      const r = await pm.enter(groupId, arg, { debug: true });
+      return r.message;
+    }
+    case "/play": {
+      if (!arg) return "用法: /play <服务器ID>";
+      const r = await pm.enter(groupId, arg);
+      return r.message;
+    }
+    case "/exit": {
+      const r = await pm.exit(groupId);
+      return r.message;
+    }
+    case "/say": {
+      if (!arg) return "用法: /say <要说的话>";
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      if (!s.controller.isOnline()) return "bot 尚未连接到服务器";
+      s.say(arg);
+      return `已发送: ${arg}`;
+    }
+    case "/motion": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      if (!s.controller.isOnline()) return "bot 尚未连接到服务器";
+      if (!arg) return motionUsage();
+      if (OVERLAY_NAMES.includes(arg.toLowerCase().split(/\s+/)[0])) {
+        const head2 = arg.toLowerCase().split(/\s+/)[0];
+        const params: Record<string, string> = {};
+        for (const p of arg.split(/\s+/).slice(1)) {
+          const eq = p.indexOf("=");
+          if (eq > 0) params[p.slice(0, eq)] = p.slice(eq + 1);
+        }
+        const enable = !s.isOverlayEnabled(head2);
+        s.toggleOverlay(head2, enable, params);
+        return `${head2} ${enable ? "已开启" : "已关闭"}${
+          enable && Object.keys(params).length ? " " + formatParams(params) : ""
+        }`.trim();
+      }
+      const parsed = parseBundleArgs(arg);
+      if (!parsed) {
+        return `无法解析参数: ${arg}\n${motionUsage()}`;
+      }
+      const result = s.startMission(parsed);
+      if (result.kind === "applied") {
+        return `任务已启动: ${result.bundleId} (mission=${result.missionId.slice(0, 8)})`;
+      }
+      return `任务被拒绝 (${result.reason}): ${result.detail}`;
+    }
+    case "/missions": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      const bundles = s.listBundles();
+      const lines = [
+        "== Task Bundles (startMission API) ==",
+        ...bundles.map((b) => `- ${b.id} [${b.mode ?? "null"}]  ${b.description}`),
+      ];
+      const current = s.getCurrentMission();
+      if (current) {
+        lines.push(
+          "",
+          `当前任务: ${current.bundleId} (mission=${current.missionId.slice(0, 8)}, 启动于 ${new Date(current.startedAt).toLocaleTimeString()})`,
+        );
+      }
+      return lines.join("\n");
+    }
+    case "/actions": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      return [
+        "== Atomic Actions ==",
+        ...s.listActions().map((action) => `- ${action.name}  ${action.description}`),
+      ].join("\n");
+    }
+    case "/stopmission": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      const result = s.stopMission("debug_stop");
+      if (result.kind === "applied") {
+        return `任务已停止: ${result.bundleId}`;
+      }
+      return `停止失败 (${result.reason}): ${result.detail}`;
+    }
+    case "/stop": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      s.stopMovement();
+      return "移动已停止，回到 idle（叠加状态保留）";
+    }
+    case "/clear": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      s.clearBehaviors();
+      return "已清空所有状态，回到 idle";
+    }
+    case "/off": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      if (!arg) return "用法: /off <defend|auto_eat>";
+      if (!OVERLAY_NAMES.includes(arg.toLowerCase())) return `未知叠加状态: ${arg}`;
+      s.toggleOverlay(arg.toLowerCase(), false);
+      return `${arg} 已关闭`;
+    }
+    case "/status": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      const st = s.getStatus();
+      const elapsed = Math.floor((Date.now() - st.startedAt) / 1000);
+      const states = s.getBehaviorStates();
+      const on = states.filter((x) => x.enabled);
+      const activeNow = states.find((x) => x.active);
+      const mem = s.getMemorySnapshot();
+      const snap = s.getBehaviorSnapshot();
+      const lastMissionOutcome = s.getLastMissionOutcome();
+      const memLines = Object.entries(mem)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => {
+          const valueStr = formatMemoryValue(v.value);
+          return `  ${k}=${valueStr} (${v.ageMs}ms ago)`;
+        });
+      const snapLines = snap
+        ? [
+            `Mode: ${snap.mode.current} | Cooldowns: ${Object.keys(snap.cooldowns).length} pending`,
+            `Active (internal state):`,
+            ...snap.activeBehaviors
+              .filter((x) => x.active)
+              .map((x) => `  ▶ ${x.name}: ${formatMemoryValue(x.internalState)}`),
+          ]
+        : [`Snapshot: (engine not ready)`];
+      const ws = st.workStatus;
+      const workLine = ws
+        ? `Work 状态: ${ws.running ? "运行中" : "空闲"} - ${ws.summary}${ws.progress ? ` (${ws.progress.current}/${ws.progress.target} ${ws.progress.unit})` : ""}`
+        : "Work 状态: 未知";
+      return [
+        `服务器: ${st.serverName} | 状态: ${st.connected ? "已连接" : "未连接"}${s.debug ? " [debug]" : ""}`,
+        `已游玩: ${Math.floor(elapsed / 60)}m${elapsed % 60}s | 当前执行: ${activeNow?.name ?? "none"}`,
+        workLine,
+        `最近任务结果: ${lastMissionOutcome ? `${lastMissionOutcome.status} ${lastMissionOutcome.bundleId}${lastMissionOutcome.code ? ` (${lastMissionOutcome.code})` : ""}` : "none"}`,
+        `已启用状态:`,
+        ...on.map((x) => `  ${x.active ? "▶" : "○"} ${x.name} (${x.category}, P${x.priority})`),
+        ...snapLines,
+        `Snapshot revisions: ${snap ? formatMemoryValue(snap.revisions) : "none"}`,
+        `MemoryBus (${memLines.length} keys):`,
+        ...memLines,
+      ].join("\n");
+    }
+    case "/behaviors": {
+      const s = pm.getActiveSession(groupId);
+      if (!s) return "当前没有进行中的 mc 会话";
+      const bundles = s.listBundles();
+      return [
+        "== 任务 Bundle (startMission API) ==",
+        ...bundles.map((b) => `- ${b.id} [${b.mode ?? "null"}]  ${b.description}`),
+        "",
+        "== 叠加状态 (toggleOverlay) ==",
+        ...OVERLAY_NAMES.map((n) => `- /motion ${n}  ${OVERLAY_HELP[n]}`),
+        "",
+        "生存层（常驻）: escape_lava / mlg_fall / flee_creeper / escape_water",
+      ].join("\n");
+    }
+    default:
+      return null;
+  }
+}
+
+function formatParams(params: Record<string, string>): string {
+  return Object.entries(params).map(([k, v]) => `${k}=${v}`).join(" ");
+}
+
+function formatMemoryValue(v: unknown): string {
+  if (v === null) return "null";
+  if (v === undefined) return "undefined";
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+function motionUsage(): string {
+  return [
+    "用法:",
+    '  /motion {"bundle":"task.follow_player","params":{"target":"Steve","distance":3}}',
+    '  /motion task.follow_player target=Steve distance=3',
+    "  /motion <defend|auto_eat> [key=value ...]  切换叠加状态",
+    "  /stop              停止移动（回 idle，叠加状态保留）",
+    "  /stopmission       停止当前任务",
+    "  /clear             清空所有状态",
+    "  /off <名称>        关闭指定叠加状态",
+    "  /status            查看当前状态 + MemoryBus + Snapshot",
+    "  /behaviors         列出所有任务 bundle",
+    "  /missions          列出所有任务 bundle（含当前任务）",
+    "  /actions           列出 Working AI 可用的一次性动作",
+  ].join("\n");
+}

package/play/index.ts

@@ -0,0 +1,247 @@
+import type { MiokiContext } from "mioki";
+import type { AIService, AIInstance, ConfigService } from "mioku";
+import type { ConfigHandler } from "../utils/config-handler";
+import type { PlayPluginContext } from "./context";
+import type { PlayConfigHandler } from "./config";
+import { PlaySession } from "./session";
+import { MainLoop } from "./ai/main-loop";
+import { WorkSubroutine } from "./ai/work-subroutine";
+import { BehaviorEngine } from "./behavior/engine";
+import type { Behavior } from "./behavior/base-behavior";
+import { EscapeLavaBehavior } from "./behavior/survival/escape-lava";
+import { EscapeWaterBehavior } from "./behavior/survival/escape-water";
+import { MlgFallBehavior } from "./behavior/survival/mlg-fall";
+import { FleeCreeperBehavior } from "./behavior/survival/flee-creeper";
+import { AutoEatBehavior } from "./behavior/survival/auto-eat";
+import { SelfDefenseBehavior } from "./behavior/catalog/defend";
+import type { GroupBinding, PlayServerConfig } from "./types";
+
+export interface PlayManagerOptions {
+  ctx: MiokiContext;
+  aiService: AIService | undefined;
+  configService: ConfigService | undefined;
+  playConfigHandler: PlayConfigHandler;
+  syncConfigHandler: ConfigHandler;
+}
+
+export interface PlayEnterResult {
+  success: boolean;
+  serverId?: string;
+  message: string;
+}
+
+export interface PlayExitResult {
+  success: boolean;
+  message: string;
+}
+
+export class PlayManager {
+  private readonly ctx: MiokiContext;
+  private readonly aiService: AIService | undefined;
+  private readonly configService: ConfigService | undefined;
+  private readonly playConfigHandler: PlayConfigHandler;
+  private readonly syncConfigHandler: ConfigHandler;
+  private readonly sessions = new Map<number, PlaySession>();
+  private mainInstance?: AIInstance;
+  private workInstance?: AIInstance;
+
+  constructor(opts: PlayManagerOptions) {
+    this.ctx = opts.ctx;
+    this.aiService = opts.aiService;
+    this.configService = opts.configService;
+    this.playConfigHandler = opts.playConfigHandler;
+    this.syncConfigHandler = opts.syncConfigHandler;
+  }
+
+  private buildPluginCtx(config: ReturnType<PlayConfigHandler["getConfig"]>): PlayPluginContext {
+    return {
+      ctx: this.ctx,
+      config,
+      aiService: this.aiService,
+      configService: this.configService,
+      syncConfigHandler: this.syncConfigHandler,
+      mainInstance: this.mainInstance,
+      workInstance: this.workInstance,
+      getPlayConfig: () => this.playConfigHandler.getConfig(),
+      refreshInstances: () => {
+        this.mainInstance = this.aiService?.get("main");
+        this.workInstance = this.aiService?.get("work");
+      },
+      createWorkSubroutine: (opts) => new WorkSubroutine(opts),
+    };
+  }
+
+  private async ensureInstances(): Promise<void> {
+    if (!this.aiService) return;
+    this.mainInstance = this.aiService.get("main");
+    this.workInstance = this.aiService.get("work");
+    if (!this.mainInstance || !this.workInstance) {
+      this.ctx.logger.warn(
+        "[MC/play] chat 插件未注册 main/work AI 实例，AI 循环不可用（debug 命令仍可用）",
+      );
+    }
+  }
+
+  private buildSurvivalBehaviors(): Behavior[] {
+    return [
+      new EscapeLavaBehavior(),
+      new MlgFallBehavior(),
+      new FleeCreeperBehavior(),
+      new EscapeWaterBehavior(),
+    ];
+  }
+
+  private buildOverlays(): Behavior[] {
+    const defend = new SelfDefenseBehavior();
+    defend.enabled = true;
+    const autoEat = new AutoEatBehavior();
+    autoEat.enabled = true;
+    return [defend, autoEat];
+  }
+
+  async enter(
+    groupId: number,
+    serverId: string,
+    opts: { debug?: boolean } = {},
+  ): Promise<PlayEnterResult> {
+    await this.ensureInstances();
+
+    const debug = opts.debug ?? false;
+    const config = this.playConfigHandler.getConfig();
+    const binding = this.playConfigHandler.findBinding(groupId);
+    if (!binding) {
+      return { success: false, message: `未配置群 ${groupId} 的 mc 游玩绑定` };
+    }
+    const id = String(serverId ?? "").trim();
+    if (!binding.allowedServerIds.includes(id)) {
+      return {
+        success: false,
+        message: `服务器 ${id} 未对该群开放（允许: ${binding.allowedServerIds.join(", ") || "无"}）`,
+      };
+    }
+    const server = this.playConfigHandler.findServer(id);
+    if (!server) {
+      return { success: false, message: `未找到服务器配置 ${id}` };
+    }
+
+    const existing = this.sessions.get(groupId);
+    if (existing && !existing.isStopped) {
+      await existing.stop("reenter");
+      this.sessions.delete(groupId);
+    }
+
+    const pluginCtx = this.buildPluginCtx(config);
+    const session = new PlaySession({
+      pluginCtx,
+      server,
+      binding,
+    });
+    session.debug = debug;
+
+    const behaviorCtxBuilder = () => {
+      const bot = session.controller.bot;
+      const movements = session.controller.getMovements();
+      if (!bot || !movements) return null;
+      return {
+        bot,
+        movements,
+        log: (m: string) => this.ctx.logger.info(`[MC/play] ${m}`),
+      };
+    };
+    const engine = new BehaviorEngine({
+      ctxBuilder: behaviorCtxBuilder,
+      tickInterval: config.behaviorTickIntervalMs,
+      survival: this.buildSurvivalBehaviors(),
+      overlays: this.buildOverlays(),
+      initialMovement: { name: "idle", params: {} },
+    });
+    session.engine = engine;
+    session.addCompanion(engine);
+
+    let mainLoop: MainLoop | undefined;
+    if (!debug) {
+      pluginCtx.notifyChatScan = () => mainLoop?.markChatScanDue();
+      mainLoop = new MainLoop({ session, pluginCtx });
+      session.addCompanion(mainLoop);
+    } else {
+      pluginCtx.notifyChatScan = undefined;
+    }
+
+    this.sessions.set(groupId, session);
+
+    try {
+      await session.start();
+    } catch (err) {
+      this.sessions.delete(groupId);
+      await session.stop("enter_failed");
+      return { success: false, message: `进入服务器失败: ${err}` };
+    }
+    const mode = debug ? " (debug)" : "";
+    return { success: true, serverId: server.id, message: `已进入 ${server.name}${mode}` };
+  }
+
+  async exit(groupId: number): Promise<PlayExitResult> {
+    const session = this.sessions.get(groupId);
+    if (!session || session.isStopped) {
+      return { success: false, message: "当前没有进行中的 mc 会话" };
+    }
+    await session.stop("tool_exit");
+    this.sessions.delete(groupId);
+    return { success: true, message: "已离开服务器" };
+  }
+
+  onQqMessage(event: any): void {
+    const groupId = Number(event?.group_id);
+    if (!Number.isFinite(groupId) || groupId <= 0) return;
+    const session = this.sessions.get(groupId);
+    if (!session || session.isStopped) return;
+    const text = String(event?.raw_message ?? event?.message ?? "").trim();
+    if (!text) return;
+    const sender = event?.sender?.card || event?.sender?.nickname || event?.user_id || "群友";
+    const atBot = detectQqAtBot(event, session.server.username, session.binding.botSelfId);
+    session.onQqMessage(`[${sender}] ${text}`, { sender: String(sender), atBot });
+  }
+
+  getStatusList() {
+    return [...this.sessions.values()].map((s) => s.getStatus());
+  }
+
+  getActiveSession(groupId: number): PlaySession | undefined {
+    const s = this.sessions.get(groupId);
+    return s && !s.isStopped ? s : undefined;
+  }
+
+  async dispose(): Promise<void> {
+    await Promise.all(
+      [...this.sessions.values()].map((s) =>
+        s.stop("shutdown").catch(() => undefined),
+      ),
+    );
+    this.sessions.clear();
+  }
+}
+
+export interface PlayServer extends PlayServerConfig {}
+export interface PlayGroupBinding extends GroupBinding {}
+
+export function createPlayManager(opts: PlayManagerOptions): PlayManager {
+  return new PlayManager(opts);
+}
+
+function detectQqAtBot(
+  event: any,
+  botName: string,
+  botSelfId: number | undefined,
+): boolean {
+  const lower = String(event?.raw_message ?? event?.message ?? "").toLowerCase();
+  if (botName && lower.includes(botName.toLowerCase())) return true;
+  if (Array.isArray(event?.message)) {
+    for (const segment of event.message) {
+      if (!segment || typeof segment !== "object") continue;
+      if (segment.type !== "at") continue;
+      const qq = Number(segment.data?.qq ?? 0);
+      if (qq > 0 && qq === botSelfId) return true;
+    }
+  }
+  return false;
+}

package/play/mineflayer-shims.d.ts

@@ -0,0 +1,22 @@
+export {};
+
+declare module "minecraft-data" {
+  export interface IndexedData {
+    blocksByName: Record<string, any>;
+    itemsByName: Record<string, any>;
+    entitiesByName: Record<string, any>;
+    foodsByName?: Record<string, any>;
+    items?: any[];
+    [key: string]: any;
+  }
+  function minecraftData(version: string): IndexedData;
+  export default minecraftData;
+}
+
+declare module "mineflayer" {
+  interface Bot {
+    pathEngine?: any;
+    combat?: any;
+    pvp?: any;
+  }
+}

package/play/missions/bundles/approach-player.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { CATEGORY_PRIORITY, type Behavior } from "../../behavior/base-behavior";
+import { ApproachPlayerBehavior } from "../../behavior/catalog/approach-player";
+import type { BehaviorBundle, BehaviorEntry } from "../registry";
+
+const paramsSchema = z.object({
+  target: z.string().min(1).describe("玩家名"),
+  distance: z.number().int().min(1).max(10).default(3).describe("接近到多少格"),
+});
+
+export const approachPlayerBundle: BehaviorBundle<
+  z.infer<typeof paramsSchema>
+> = {
+  id: "task.approach_player",
+  description: "接近指定玩家，到达目标距离后完成。",
+  mode: "MISSION",
+  paramsSchema,
+  build(params): BehaviorEntry[] {
+    const behavior: Behavior = new ApproachPlayerBehavior();
+    behavior.configure({
+      target: params.target,
+      distance: String(params.distance),
+    });
+    return [{ priority: CATEGORY_PRIORITY.movement, behavior }];
+  },
+};

package/play/missions/bundles/explore.ts

@@ -0,0 +1,24 @@
+import {
+  CATEGORY_PRIORITY,
+  type Behavior,
+} from "../../behavior/base-behavior";
+import { ExploreBehavior } from "../../behavior/catalog/explore";
+import { z } from "zod";
+import type {
+  BehaviorBundle,
+  BehaviorEntry,
+} from "../registry";
+
+const paramsSchema = z.object({}).strict();
+
+export const exploreBundle: BehaviorBundle<Record<string, never>> = {
+  id: "task.explore",
+  description: "随机探索 12 格范围以加载新区块。",
+  mode: "MISSION",
+  paramsSchema,
+  build(): BehaviorEntry[] {
+    const b: Behavior = new ExploreBehavior();
+    b.configure({});
+    return [{ priority: CATEGORY_PRIORITY.movement, behavior: b }];
+  },
+};

package/play/missions/bundles/farm-mobs.ts

@@ -0,0 +1,24 @@
+import {
+  CATEGORY_PRIORITY,
+  type Behavior,
+} from "../../behavior/base-behavior";
+import { FarmMobsBehavior } from "../../behavior/catalog/farm-mobs";
+import { z } from "zod";
+import type {
+  BehaviorBundle,
+  BehaviorEntry,
+} from "../registry";
+
+const paramsSchema = z.object({}).strict();
+
+export const farmMobsBundle: BehaviorBundle<Record<string, never>> = {
+  id: "task.farm_mobs",
+  description: "猎杀附近被动生物获取掉落物（牛/羊/鸡等）。",
+  mode: "MISSION",
+  paramsSchema,
+  build(): BehaviorEntry[] {
+    const b: Behavior = new FarmMobsBehavior();
+    b.configure({});
+    return [{ priority: CATEGORY_PRIORITY.movement, behavior: b }];
+  },
+};

package/play/missions/bundles/follow-player.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import {
+  CATEGORY_PRIORITY,
+  type Behavior,
+} from "../../behavior/base-behavior";
+import { FollowPlayerBehavior } from "../../behavior/catalog/follow";
+import type { BehaviorBundle, BehaviorEntry, BundleBuildContext } from "../registry";
+
+const paramsSchema = z.object({
+  target: z.string().min(1).describe("玩家名"),
+  distance: z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .optional()
+    .default(3)
+    .describe("保持距离 (1-20)"),
+});
+
+export type FollowPlayerParams = z.infer<typeof paramsSchema>;
+
+export const followPlayerBundle: BehaviorBundle<FollowPlayerParams> = {
+  id: "task.follow_player",
+  description: "跟随指定玩家。玩家离线或跨维度时自动停止。",
+  mode: "MISSION",
+  paramsSchema,
+  build(params: FollowPlayerParams, ctx: BundleBuildContext): BehaviorEntry[] {
+    const b: Behavior = new FollowPlayerBehavior();
+    b.configure({
+      target: params.target,
+      distance: String(params.distance),
+    });
+    return [{ priority: CATEGORY_PRIORITY.movement, behavior: b }];
+  },
+  snapshot(internal: unknown): unknown {
+    const i = internal as { target: string; distance: number } | null;
+    return i ? { target: i.target, distance: i.distance } : null;
+  },
+};