mioku-plugin-mc 2.0.0 → 3.0.0

package/play/session.ts

@@ -0,0 +1,486 @@
+import type { PlayPluginContext } from "./context";
+import { BotController } from "./bot/bot-controller";
+import { PlayBus } from "./bot/play-bus";
+import { buildGoodbyePrompt } from "./ai/prompt";
+import type { BehaviorEngine } from "./behavior/engine";
+import { withTimeoutMs } from "./util/async";
+import { MemoryBus } from "./state/memory-bus";
+import { CooldownRegistry } from "./state/cooldowns";
+import { EntityScanner } from "./state/sensors/entity-scanner";
+import { SnapshotCollector, type BehaviorSnapshot } from "./state/snapshot";
+import { PlayEventJournal } from "./state/event-journal";
+import { ActionRegistry, type ActionOutcome } from "./actions/registry";
+import { TaskRegistry } from "./missions/registry";
+import { MissionController, type SwitchResult, type MissionSpec } from "./missions/mission-controller";
+import { followPlayerBundle } from "./missions/bundles/follow-player";
+import { gatherResourceBundle } from "./missions/bundles/gather-resource";
+import { farmMobsBundle } from "./missions/bundles/farm-mobs";
+import { exploreBundle } from "./missions/bundles/explore";
+import { idleWanderBundle } from "./missions/bundles/idle-wander";
+import { approachPlayerBundle } from "./missions/bundles/approach-player";
+import { seekShelterBundle } from "./missions/bundles/seek-shelter";
+import type { MissionOutcome } from "./state/mode";
+import type {
+  GroupBinding,
+  PlayServerConfig,
+  PlaySessionStatus,
+  WorkStatus,
+} from "./types";
+
+export interface PlaySessionCompanion {
+  start?: () => void;
+  stop?: () => void;
+}
+
+export interface PlaySessionOptions {
+  pluginCtx: PlayPluginContext;
+  server: PlayServerConfig;
+  binding: GroupBinding;
+}
+
+export class PlaySession {
+  private readonly pluginCtx: PlayPluginContext;
+  readonly server: PlayServerConfig;
+  readonly binding: GroupBinding;
+  readonly bus = new PlayBus();
+  readonly memory = new MemoryBus();
+  readonly events = new PlayEventJournal();
+  readonly cooldowns = new CooldownRegistry();
+  readonly taskRegistry = new TaskRegistry();
+  readonly actionRegistry = new ActionRegistry();
+  readonly controller: BotController;
+  private readonly scanner: EntityScanner;
+  startedAt = Date.now();
+  connected = false;
+  debug = false;
+  engine?: BehaviorEngine;
+  private missionController?: MissionController;
+  private snapshotCollector?: SnapshotCollector;
+  private stopped = false;
+  private watchdog?: NodeJS.Timeout;
+  private companions: PlaySessionCompanion[] = [];
+  private qqWindow?: { start: number; count: number };
+  private workStatus: WorkStatus = {
+    running: false,
+    goal: null,
+    summary: "空闲",
+    updatedAt: Date.now(),
+  };
+
+  constructor(opts: PlaySessionOptions) {
+    this.pluginCtx = opts.pluginCtx;
+    const ctx = this.pluginCtx;
+    this.server = opts.server;
+    this.binding = opts.binding;
+    this.controller = new BotController({
+      server: opts.server,
+      bus: this.bus,
+      log: (msg) => ctx.ctx.logger.info(`[MC/play] ${msg}`),
+    });
+    this.scanner = new EntityScanner({
+      bus: this.memory,
+      bot: () => this.controller.bot,
+      onEvent: (type, data) => this.events.append(type, data),
+    });
+    this.registerDefaultBundles();
+  }
+
+  private registerDefaultBundles(): void {
+    this.taskRegistry.register(followPlayerBundle);
+    this.taskRegistry.register(gatherResourceBundle);
+    this.taskRegistry.register(farmMobsBundle);
+    this.taskRegistry.register(exploreBundle);
+    this.taskRegistry.register(idleWanderBundle);
+    this.taskRegistry.register(approachPlayerBundle);
+    this.taskRegistry.register(seekShelterBundle);
+  }
+
+  addCompanion(companion: PlaySessionCompanion): void {
+    this.companions.push(companion);
+  }
+
+  async start(): Promise<void> {
+    const ctx = this.pluginCtx;
+    ctx.ctx.logger.info(`[MC/play] 正在进入服务器 ${this.server.name} (${this.server.host})`);
+
+    this.bus.on("chat", (line) => {
+      this.events.append("game_chat", line);
+    });
+    this.bus.on("entityHurt", (entity) => {
+      const bot = this.controller.bot;
+      if (bot?.entity && entity?.id === bot.entity.id) {
+        this.events.append("damage", {
+          health: bot.health,
+          food: bot.food,
+          source: entity?.name ?? entity?.username ?? "unknown",
+        });
+      }
+    });
+    this.bus.on("death", () => this.events.append("death", { at: Date.now() }));
+    this.bus.on("respawn", () => this.events.append("respawn", { at: Date.now() }));
+    this.bus.on("inventoryChanged", () => this.scanner.refresh());
+    this.bus.on("end", (reason) => this.onUnexpectedEnd(`连接结束: ${reason}`));
+    this.bus.on("kicked", (reason) => this.onUnexpectedEnd(`被踢出: ${reason}`));
+    this.bus.on("error", () => this.onUnexpectedEnd("bot 错误"));
+
+    await this.controller.connect();
+    await this.controller.waitForChunksLoaded();
+    this.connected = true;
+    this.scanner.refresh();
+    this.scanner.start();
+    this.startWatchdog();
+
+    for (const companion of this.companions) companion.start?.();
+    ctx.ctx.logger.info(`[MC/play] 已进入 ${this.server.name}`);
+  }
+
+  onQqMessage(text: string, opts: { sender?: string; atBot?: boolean } = {}): void {
+    this.events.append("qq_chat", {
+      text,
+      sender: opts.sender,
+      atBot: Boolean(opts.atBot),
+    });
+  }
+
+  private startWatchdog(): void {
+    this.watchdog = setInterval(() => this.tick(), 1_000);
+  }
+
+  private stopWatchdog(): void {
+    if (this.watchdog) {
+      clearInterval(this.watchdog);
+      this.watchdog = undefined;
+    }
+  }
+
+  private tick(): void {
+    if (this.stopped) return;
+    const elapsed = Date.now() - this.startedAt;
+    this.missionController?.tick();
+    this.pluginCtx.notifyChatScan?.();
+    if (elapsed >= this.server.maxPlayMs) {
+      void this.stop("time_up");
+    }
+  }
+
+  async stop(reason: string, opts: { skipGoodbye?: boolean } = {}): Promise<void> {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.stopWatchdog();
+    this.scanner.stop();
+
+    for (const companion of this.companions) companion.stop?.();
+
+    if (this.connected && this.controller.isOnline()) {
+      if (!opts.skipGoodbye) await this.sayGoodbye();
+      await this.controller.disconnect("leaving");
+    }
+    this.connected = false;
+    this.bus.removeAll();
+    this.memory.clear();
+    this.events.clear();
+    this.workStatus = {
+      running: false,
+      goal: null,
+      summary: "已停止",
+      updatedAt: Date.now(),
+    };
+
+    const ctx = this.pluginCtx;
+    ctx.ctx.logger.info(`[MC/play] 已离开 ${this.server.name} (reason: ${reason})`);
+  }
+
+  private async onUnexpectedEnd(reason: string): Promise<void> {
+    if (this.stopped) return;
+    this.connected = false;
+    this.stopWatchdog();
+    this.scanner.stop();
+    for (const companion of this.companions) companion.stop?.();
+    this.stopped = true;
+    this.bus.removeAll();
+    this.memory.clear();
+    this.events.clear();
+
+    const ctx = this.pluginCtx;
+    ctx.ctx.logger.warn(`[MC/play] ${this.server.name} 异常断开: ${reason}`);
+    await this.notifyQq(`bot 已从 ${this.server.name} 断开: ${reason}`);
+  }
+
+  private async sayGoodbye(): Promise<void> {
+    const ctx = this.pluginCtx;
+    const main = ctx.mainInstance;
+    if (!main) {
+      this.controller.chat("我先走啦~");
+      return;
+    }
+    try {
+      const persona = main.getPrompt("persona") ?? "";
+      const prompt = buildGoodbyePrompt(persona, this.server);
+      const config = ctx.getPlayConfig();
+      const startedAt = Date.now();
+      const debugConfig = ctx.getPlayConfig();
+      void startedAt;
+      void debugConfig;
+      const text = await withTimeoutMs(
+        main.generateText({ prompt, messages: [] }),
+        ctx.config.goodbyeTimeoutMs,
+      );
+      const clean = text
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .slice(0, 2)
+        .join(" ");
+      this.controller.chat(clean || "我先走啦~");
+    } catch {
+      this.controller.chat("我先走啦~");
+    }
+  }
+
+  async notifyQq(message: string): Promise<void> {
+    const ctx = this.pluginCtx;
+    const bot = ctx.ctx.pickBot(this.binding.botSelfId);
+    if (!bot) return;
+    try {
+      await bot.sendGroupMsg(this.binding.groupId, message);
+    } catch (err) {
+      ctx.ctx.logger.error(`[MC/play] 发送 QQ 通知失败: ${err}`);
+    }
+  }
+
+  async sendQq(message: string): Promise<boolean> {
+    const ctx = this.pluginCtx;
+    const now = Date.now();
+    const windowMs = 60_000;
+    if (!this.qqWindow) this.qqWindow = { start: now, count: 0 };
+    if (now - this.qqWindow.start > windowMs) {
+      this.qqWindow = { start: now, count: 0 };
+    }
+    if (this.qqWindow.count >= ctx.config.qqSendPerMinute) {
+      ctx.ctx.logger.warn(`[MC/play] QQ 发送频率达上限，已丢弃: ${message}`);
+      return false;
+    }
+    this.qqWindow.count++;
+    const bot = ctx.ctx.pickBot(this.binding.botSelfId);
+    if (!bot) return false;
+    try {
+      await bot.sendGroupMsg(this.binding.groupId, message);
+      return true;
+    } catch (err) {
+      ctx.ctx.logger.error(`[MC/play] 发送 QQ 消息失败: ${err}`);
+      return false;
+    }
+  }
+
+  say(text: string): boolean {
+    if (!this.controller.isOnline()) return false;
+    this.controller.chat(text);
+    return true;
+  }
+
+  stopMovement(): void {
+    this.engine?.stopMission();
+  }
+
+  toggleOverlay(name: string, enabled: boolean, params?: Record<string, string>): boolean {
+    return this.engine?.toggleOverlay(name, enabled, params) ?? false;
+  }
+
+  isOverlayEnabled(name: string): boolean {
+    return this.engine?.isOverlayEnabled(name) ?? false;
+  }
+
+  clearBehaviors(): void {
+    this.engine?.clear();
+  }
+
+  getBehaviorStates(): import("./behavior/engine").BehaviorStateInfo[] {
+    const engine = this.engine;
+    const ctx = this.buildBehaviorContext();
+    if (!engine || !ctx) return [];
+    return engine.getStates(ctx);
+  }
+
+  getMemorySnapshot(): Record<string, { value: unknown; ageMs: number }> {
+    return this.memory.snapshot();
+  }
+
+  getBehaviorSnapshot(): BehaviorSnapshot | null {
+    if (!this.engine) return null;
+    if (!this.snapshotCollector) {
+      this.snapshotCollector = new SnapshotCollector({
+        bus: this.memory,
+        engine: this.engine,
+        cooldowns: this.cooldowns,
+        getContext: () => this.buildBehaviorContext(),
+        getMission: () => this.getCurrentMission(),
+        getLastOutcome: () => this.getLastMissionOutcome(),
+      });
+    }
+    return this.snapshotCollector.collect();
+  }
+
+  listBundles(): Array<{ id: string; description: string; mode: string | null }> {
+    return this.taskRegistry.list();
+  }
+
+  describeBundles(): ReturnType<TaskRegistry["describe"]> {
+    return this.taskRegistry.describe();
+  }
+
+  listActions(): Array<{ name: string; description: string }> {
+    return this.actionRegistry.list();
+  }
+
+  startMission(spec: MissionSpec): SwitchResult {
+    if (!this.engine) {
+      return {
+        kind: "rejected",
+        reason: "no_bot_session",
+        detail: "engine 尚未初始化",
+      };
+    }
+    if (!this.missionController) {
+      this.missionController = new MissionController({
+        registry: this.taskRegistry,
+        engine: this.engine,
+        bus: this.memory,
+        buildContext: () => this.buildBehaviorContext(),
+        log: (msg) => this.pluginCtx.ctx.logger.info(`[MC/play] ${msg}`),
+        onOutcome: (outcome) => this.handleMissionOutcome(outcome),
+      });
+    }
+    return this.missionController.startMission(spec);
+  }
+
+  stopMission(reason?: string): SwitchResult {
+    if (!this.missionController) {
+      return {
+        kind: "rejected",
+        reason: "rejected_by_engine",
+        detail: "没有进行中的任务",
+      };
+    }
+    return this.missionController.stopMission(reason);
+  }
+
+  getCurrentMission(): import("./state/mode").MissionState | null {
+    return this.missionController?.getCurrentMission() ?? null;
+  }
+
+  getLastMissionOutcome(): MissionOutcome | null {
+    return this.missionController?.getLastOutcome() ?? null;
+  }
+
+  updateWorkStatus(status: Partial<WorkStatus>): void {
+    this.workStatus = {
+      ...this.workStatus,
+      ...status,
+      updatedAt: Date.now(),
+    };
+  }
+
+  getWorkStatus(): WorkStatus {
+    return { ...this.workStatus };
+  }
+
+  getBot(): any {
+    return this.controller.bot;
+  }
+
+  getPluginCtx(): PlayPluginContext {
+    return this.pluginCtx;
+  }
+
+  requestMainAttention(reason: string): void {
+    this.events.append("work_completed", { reason, manual: true });
+  }
+
+  async performAction(
+    action: string,
+    params: Record<string, unknown>,
+    meta: {
+      directiveId?: string;
+      goalId?: string;
+      completesGoalOnSuccess?: boolean;
+    } = {},
+  ): Promise<ActionOutcome> {
+    const bot = this.controller.bot;
+    if (!bot) {
+      const outcome: ActionOutcome = {
+        action,
+        status: "failed",
+        code: "disconnected",
+        detail: "bot 尚未连接",
+        at: Date.now(),
+        directiveId: meta.directiveId,
+        completesDirectiveOnSuccess: meta.completesGoalOnSuccess ?? true,
+      };
+      this.recordActionOutcome(outcome);
+      return outcome;
+    }
+    const outcome = await this.actionRegistry.execute(
+      action,
+      params,
+      {
+        bot,
+        server: this.server,
+        stopCurrentTask: (reason) => {
+          this.stopMission(reason);
+        },
+      },
+      meta,
+    );
+    this.recordActionOutcome(outcome);
+    return outcome;
+  }
+
+  getLastActionOutcome(): ActionOutcome | null {
+    return null;
+  }
+
+  private lastSwitchResult: SwitchResult | null = null;
+
+  recordSwitchResult(result: SwitchResult): void {
+    this.lastSwitchResult = result;
+  }
+
+  consumeLastSwitchResult(): SwitchResult | null {
+    const r = this.lastSwitchResult;
+    this.lastSwitchResult = null;
+    return r;
+  }
+
+  private buildBehaviorContext(): import("./behavior/base-behavior").BehaviorContext | null {
+    const bot = this.controller.bot;
+    const movements = this.controller.getMovements();
+    if (!bot || !movements) return null;
+    return { bot, movements, log: (m: string) => this.pluginCtx.ctx.logger.info(`[MC/play] ${m}`) };
+  }
+
+  private handleMissionOutcome(outcome: MissionOutcome): void {
+    this.events.append("mission_outcome", outcome);
+  }
+
+  private recordActionOutcome(outcome: ActionOutcome): void {
+    this.events.append("action_outcome", outcome);
+  }
+
+  getStatus(): PlaySessionStatus {
+    return {
+      serverId: this.server.id,
+      serverName: this.server.name,
+      groupId: this.binding.groupId,
+      botSelfId: this.binding.botSelfId,
+      startedAt: this.startedAt,
+      connected: this.connected,
+      currentBehavior: this.engine?.currentLabel() ?? null,
+      lastAction: this.workStatus.goal ?? null,
+      workStatus: this.getWorkStatus(),
+    };
+  }
+
+  get isStopped(): boolean {
+    return this.stopped;
+  }
+}

package/play/state/cooldowns.ts

@@ -0,0 +1,40 @@
+export class CooldownRegistry {
+  private until = new Map<string, number>();
+
+  set(key: string, durationMs: number, now = Date.now()): void {
+    this.until.set(key, now + durationMs);
+  }
+
+  setUntil(key: string, untilMs: number): void {
+    this.until.set(key, untilMs);
+  }
+
+  clear(key: string): void {
+    this.until.delete(key);
+  }
+
+  clearAll(): void {
+    this.until.clear();
+  }
+
+  /** 剩余毫秒，0 表示已就绪。 */
+  remaining(key: string, now = Date.now()): number {
+    const until = this.until.get(key);
+    if (until === undefined) return 0;
+    return until > now ? until - now : 0;
+  }
+
+  isReady(key: string, now = Date.now()): boolean {
+    return this.remaining(key, now) === 0;
+  }
+
+  /** 调试快照：key -> 剩余毫秒（已就绪的不输出）。 */
+  snapshot(now = Date.now()): Record<string, number> {
+    const out: Record<string, number> = {};
+    for (const [key, until] of this.until) {
+      const left = until - now;
+      if (left > 0) out[key] = left;
+    }
+    return out;
+  }
+}

package/play/state/event-journal.ts

@@ -0,0 +1,72 @@
+import type { PlayEventType } from "../types";
+
+export type { PlayEventType };
+
+export interface PlayEvent<T = unknown> {
+  seq: number;
+  at: number;
+  type: PlayEventType;
+  data: T;
+}
+
+export interface EventBatch {
+  events: PlayEvent[];
+  cursor: number;
+}
+
+export class PlayEventJournal {
+  private seq = 0;
+  private events: PlayEvent[] = [];
+  private listeners = new Set<(event: PlayEvent) => void>();
+
+  constructor(private readonly maxEntries = 300) {}
+
+  append<T>(type: PlayEventType, data: T): PlayEvent<T> {
+    const event: PlayEvent<T> = {
+      seq: ++this.seq,
+      at: Date.now(),
+      type,
+      data,
+    };
+    this.events.push(event);
+    if (this.events.length > this.maxEntries) {
+      this.events.splice(0, this.events.length - this.maxEntries);
+    }
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Journal consumers must not affect the game loop.
+      }
+    }
+    return event;
+  }
+
+  readAfter(
+    cursor: number,
+    filter?: (event: PlayEvent) => boolean,
+    limit?: number,
+  ): EventBatch {
+    const matched = this.events.filter(
+      (event) => event.seq > cursor && (!filter || filter(event)),
+    );
+    return {
+      events: limit && matched.length > limit ? matched.slice(-limit) : matched,
+      cursor: matched.at(-1)?.seq ?? cursor,
+    };
+  }
+
+  subscribe(listener: (event: PlayEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  latestCursor(): number {
+    return this.seq;
+  }
+
+  clear(): void {
+    this.events = [];
+    this.listeners.clear();
+  }
+}

package/play/state/memory-bus.ts

@@ -0,0 +1,115 @@
+export type MemoryKey =
+  | "self"
+  | "vitals"
+  | "position"
+  | "dimension"
+  | "inventory"
+  | "heldItem"
+  | "armor"
+  | "environment"
+  | "equipment"
+  | "nearestHostile"
+  | "nearestPlayer"
+  | "nearestCreeper"
+  | "nearestPassiveMob"
+  | "nearbyHostileNames"
+  | "nearbyPlayerNames"
+  | "combat"
+  | "movement"
+  | "mission";
+
+export interface MemoryEntry<T = unknown> {
+  value: T;
+  updatedAt: number;
+  ttlMs: number;
+}
+
+export interface MemoryChange<T = unknown> {
+  key: MemoryKey;
+  prev: T | undefined;
+  next: T | undefined;
+  at: number;
+}
+
+export class MemoryBus {
+  private store = new Map<MemoryKey, MemoryEntry>();
+  private watchers = new Map<MemoryKey, Set<(c: MemoryChange) => void>>();
+
+  set<T>(key: MemoryKey, value: T, opts?: { ttlMs?: number }): void {
+    const prev = this.store.get(key);
+    const ttlMs = opts?.ttlMs ?? 0;
+    const at = Date.now();
+    this.store.set(key, { value, updatedAt: at, ttlMs });
+    this.notify(key, prev?.value as T | undefined, value, at);
+  }
+
+  get<T = unknown>(key: MemoryKey): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (entry.ttlMs > 0 && Date.now() - entry.updatedAt > entry.ttlMs) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value as T;
+  }
+
+  has(key: MemoryKey): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  watch<T = unknown>(key: MemoryKey, handler: (c: MemoryChange<T>) => void): () => void {
+    let set = this.watchers.get(key);
+    if (!set) {
+      set = new Set();
+      this.watchers.set(key, set);
+    }
+    const wrapped = handler as (c: MemoryChange) => void;
+    set.add(wrapped);
+    return () => {
+      set!.delete(wrapped);
+    };
+  }
+
+  update(mut: (bus: MemoryBus) => void): void {
+    mut(this);
+  }
+
+  delete(key: MemoryKey): void {
+    const prev = this.store.get(key);
+    if (!prev) return;
+    this.store.delete(key);
+    this.notify(key, prev.value, undefined, Date.now());
+  }
+
+  clear(): void {
+    const keys = [...this.store.keys()];
+    const at = Date.now();
+    for (const key of keys) {
+      const prev = this.store.get(key);
+      this.store.delete(key);
+      this.notify(key, prev?.value, undefined, at);
+    }
+  }
+
+  snapshot(): Record<string, { value: unknown; ageMs: number }> {
+    const now = Date.now();
+    const out: Record<string, { value: unknown; ageMs: number }> = {};
+    for (const [key, entry] of this.store) {
+      if (entry.ttlMs > 0 && now - entry.updatedAt > entry.ttlMs) continue;
+      out[key] = { value: entry.value, ageMs: now - entry.updatedAt };
+    }
+    return out;
+  }
+
+  private notify(key: MemoryKey, prev: unknown, next: unknown, at: number): void {
+    const set = this.watchers.get(key);
+    if (!set) return;
+    for (const handler of set) {
+      try {
+        handler({ key, prev, next, at });
+      } catch {
+        // 观察者错误不影响主流程
+      }
+    }
+  }
+}