mioku-plugin-mc 2.1.0 → 3.0.0

package/play/ai/main-loop.ts

@@ -0,0 +1,306 @@
+import type { PlaySession } from "../session";
+import type { PlayPluginContext } from "../context";
+import type { GameChatLine } from "../bot/play-bus";
+import {
+  buildMainSystemPrompt,
+  buildMainUserContext,
+  buildSessionFacts,
+} from "./prompt";
+import {
+  MAIN_TOOLS,
+  bindMainToolContext,
+  clearMainToolContext,
+} from "./main-tools";
+import { logAiRequest, logAiResponse } from "./debug-log";
+import { withTimeoutMs } from "../util/async";
+
+export interface MainLoopOptions {
+  session: PlaySession;
+  pluginCtx: PlayPluginContext;
+}
+
+const MODEL_TIMEOUT_MS = 30_000;
+
+interface QqChatLine {
+  text: string;
+  sender?: string;
+  atBot?: boolean;
+}
+
+type QueueReason = "game_chat" | "qq_chat" | "chat_scan" | "work_completed";
+
+interface QueuedMessage {
+  trigger: string;
+  reason: QueueReason;
+}
+
+export class MainLoop {
+  private readonly session: PlaySession;
+  private readonly pluginCtx: PlayPluginContext;
+  private readonly systemPrompt: string;
+  private readonly sessionFacts: string;
+  private readonly toolSchemas: any[];
+  private cursor = 0;
+  private running = false;
+  private stopped = false;
+  private unsubscribeEvents?: () => void;
+  private focusedPlayer: string | null = null;
+  private focusedUntil = 0;
+  private pendingQueue: QueuedMessage[] = [];
+  private lastChatAt = 0;
+  private lastChatScanAt = 0;
+
+  constructor(opts: MainLoopOptions) {
+    this.session = opts.session;
+    this.pluginCtx = opts.pluginCtx;
+    const persona = opts.pluginCtx.mainInstance?.getPrompt("persona") ?? "";
+    this.systemPrompt = buildMainSystemPrompt({
+      persona,
+      bundles: opts.session.describeBundles(),
+      actions: opts.session.listActions(),
+      workStatus: opts.session.getWorkStatus(),
+      focusedUntil: 0,
+    });
+    this.sessionFacts = buildSessionFacts({
+      serverName: opts.session.server.name,
+      username: opts.session.server.username,
+      groupId: opts.session.binding.groupId,
+      maxPlayMs: opts.session.server.maxPlayMs,
+      allowedCommands: opts.session.server.allowedCommands,
+    });
+    this.toolSchemas = MAIN_TOOLS.map((tool) => ({
+      type: "function" as const,
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+      },
+    })) as any[];
+  }
+
+  start(): void {
+    this.cursor = this.session.events.latestCursor();
+    this.session.bus.on("chat", (line: GameChatLine) => this.onGameChat(line));
+    this.unsubscribeEvents = this.session.events.subscribe((event) => {
+      if (event.type === "qq_chat") {
+        const data = event.data as QqChatLine | undefined;
+        if (this.shouldRespondToQq(data)) {
+          this.enqueue({
+            trigger: "direct_qq_chat",
+            reason: "qq_chat",
+          });
+        }
+        return;
+      }
+      if (event.type === "chat_scan_due") {
+        this.enqueue({ trigger: "chat_scan_due", reason: "chat_scan" });
+        return;
+      }
+      if (event.type === "work_completed") {
+        this.enqueue({ trigger: "work_completed", reason: "work_completed" });
+        return;
+      }
+    });
+  }
+
+  stop(): void {
+    this.stopped = true;
+    this.unsubscribeEvents?.();
+    clearMainToolContext();
+  }
+
+  private onGameChat(line: GameChatLine): void {
+    if (!this.shouldRespondToGameChat(line)) return;
+    if (line.username) {
+      this.focusedPlayer = line.username;
+      this.focusedUntil =
+        Date.now() + this.pluginCtx.getPlayConfig().mainConversationFocusMs;
+    }
+    this.enqueue({ trigger: "direct_game_chat", reason: "game_chat" });
+  }
+
+  private shouldRespondToGameChat(line: GameChatLine): boolean {
+    if (line.kind === "whisper") return true;
+    if (line.kind !== "chat" || !line.username) return false;
+    if (this.mentionsBot(line.text)) return true;
+    return (
+      this.focusedPlayer === line.username && Date.now() <= this.focusedUntil
+    );
+  }
+
+  private shouldRespondToQq(data: QqChatLine | undefined): boolean {
+    if (!data?.text) return false;
+    if (data.atBot) return true;
+    if (this.mentionsBot(data.text)) return true;
+    return false;
+  }
+
+  private mentionsBot(text: string): boolean {
+    const botName = this.session.server.username.toLowerCase();
+    const lower = text.toLowerCase();
+    return lower.includes(botName) || lower.includes(`@${botName}`);
+  }
+
+  private enqueue(msg: QueuedMessage): void {
+    if (this.running) {
+      this.pendingQueue.push(msg);
+      return;
+    }
+    void this.runTurn(msg);
+  }
+
+  private async runTurn(queued: QueuedMessage): Promise<void> {
+    if (this.stopped) return;
+    this.running = true;
+    try {
+      await this.runTurnInternal(queued);
+
+      while (this.pendingQueue.length > 0 && !this.stopped) {
+        const next = this.pendingQueue.shift()!;
+        await this.runTurnInternal(next);
+      }
+    } finally {
+      this.running = false;
+    }
+  }
+
+  private async runTurnInternal(queued: QueuedMessage): Promise<void> {
+    const main = this.pluginCtx.mainInstance;
+    const snapshot = this.session.getBehaviorSnapshot();
+    if (!main || !snapshot) return;
+
+    const batch = this.session.events.readAfter(this.cursor, isMainEvent, 80);
+    this.cursor = batch.cursor;
+
+    let context: string;
+    try {
+      context = buildMainUserContext({
+        trigger: queued.trigger,
+        events: batch.events,
+        snapshot,
+        workStatus: this.session.getWorkStatus(),
+        elapsedMs: Date.now() - this.session.startedAt,
+        maxMs: this.session.server.maxPlayMs,
+      });
+    } catch (error) {
+      this.pluginCtx.ctx.logger.error(
+        `[MC/play] main context 构建失败: ${error}`,
+      );
+      return;
+    }
+
+    const config = this.pluginCtx.getPlayConfig();
+    const startedAt = Date.now();
+    const messages = [
+      { role: "system" as const, content: this.systemPrompt },
+      { role: "user" as const, content: this.sessionFacts },
+      { role: "user" as const, content: context },
+    ];
+    bindMainToolContext({
+      session: this.session,
+      workSubroutineFactory: ({ session, goal, terminator, maxMs, maxIterations }) =>
+        this.pluginCtx.createWorkSubroutine({
+          session,
+          goal,
+          terminator,
+          maxMs,
+          maxIterations,
+        }),
+    });
+    logAiRequest(this.pluginCtx.ctx.logger, config, "main", {
+      trigger: queued.trigger,
+      messages,
+      tools: MAIN_TOOLS as any[],
+      temperature: 0.8,
+      max_tokens: 700,
+      triggerEvents: batch.events,
+    });
+
+    let response;
+    try {
+      response = await withTimeoutMs(
+        main.complete({
+          messages,
+          tools: this.toolSchemas,
+          temperature: 0.8,
+          max_tokens: 700,
+        }),
+        MODEL_TIMEOUT_MS,
+      );
+    } catch (error) {
+      logAiResponse(this.pluginCtx.ctx.logger, config, "main", {
+        durationMs: Date.now() - startedAt,
+        error,
+      });
+      this.pluginCtx.ctx.logger.warn(`[MC/play] 主模型调用失败: ${error}`);
+      return;
+    }
+    if (!response) {
+      this.pluginCtx.ctx.logger.warn(
+        "[MC/play] 主模型返回为空，跳过本轮",
+      );
+      return;
+    }
+    logAiResponse(this.pluginCtx.ctx.logger, config, "main", {
+      durationMs: Date.now() - startedAt,
+      content: response.content ?? null,
+      reasoning: response.reasoning ?? null,
+      toolCalls: response.toolCalls ?? [],
+    });
+
+    const content = response.content?.trim() ?? "";
+    if (content.length > 0) {
+      await this.sendChatLines(splitChatLines(content));
+    }
+    if (queued.reason === "chat_scan") {
+      this.lastChatScanAt = Date.now();
+    }
+  }
+
+  private async sendChatLines(lines: string[]): Promise<void> {
+    const config = this.pluginCtx.getPlayConfig();
+    for (const line of lines) {
+      const minInterval = config.gameChatMinIntervalMs;
+      const wait = minInterval - (Date.now() - this.lastChatAt);
+      if (wait > 0) {
+        await new Promise<void>((resolve) => setTimeout(resolve, wait));
+      }
+      this.session.say(line);
+      this.lastChatAt = Date.now();
+    }
+  }
+
+  markChatScanDue(now = Date.now()): void {
+    if (now - this.lastChatScanAt < this.pluginCtx.getPlayConfig().chatScanIntervalMs) {
+      return;
+    }
+    this.session.events.append("chat_scan_due", { at: now });
+    this.lastChatScanAt = now;
+  }
+}
+
+function isMainEvent(event: { type: string }): boolean {
+  return [
+    "game_chat",
+    "qq_chat",
+    "damage",
+    "vitals_threshold",
+    "day_phase",
+    "death",
+    "respawn",
+    "inventory_change",
+    "equipment_change",
+    "mission_outcome",
+    "action_outcome",
+    "path_error",
+  ].includes(event.type);
+}
+
+function splitChatLines(content: string): string[] {
+  return content
+    .split(/\r?\n+/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .slice(0, 3)
+    .map((line) => line.slice(0, 256));
+}

package/play/ai/main-tools.ts

@@ -0,0 +1,230 @@
+import type { AITool, SessionToolDefinition } from "mioku";
+import type { PlaySession } from "../session";
+import type { WorkSubroutine } from "./work-subroutine";
+
+export interface MainToolContext {
+  session: PlaySession;
+  workSubroutineFactory: (opts: {
+    session: PlaySession;
+    goal: string;
+    terminator: WorkSubroutine["options"]["terminator"];
+    maxMs?: number;
+    maxIterations?: number;
+  }) => WorkSubroutine;
+}
+
+const START_MOTION_TOOL: AITool = {
+  name: "start_motion",
+  description:
+    "Start a behavior bundle (a high-level task). The bot's behavior engine will run it autonomously. " +
+    "Returns success/missionId if accepted, or rejection reason. Use this when you want the bot to do something multi-step.",
+  parameters: {
+    type: "object",
+    properties: {
+      bundle: {
+        type: "string",
+        description:
+          "Bundle id from the available bundles list, e.g. 'task.gather_resource' or 'task.follow_player'.",
+      },
+      params: {
+        type: "object",
+        description: "Bundle-specific parameters object.",
+      },
+    },
+    required: ["bundle"],
+  },
+  handler: async (args, _event) => {
+    const ctx: MainToolContext | undefined = (handlerArgs as any).toolCtx;
+    if (!ctx) return { error: "tool context missing" };
+    const bundle = String(args?.bundle ?? "").trim();
+    if (!bundle) return { error: "缺少 bundle" };
+    const params = (args?.params ?? {}) as Record<string, unknown>;
+    const result = ctx.session.startMission({ bundle, params });
+    if (result.kind === "applied") {
+      return {
+        success: true,
+        missionId: result.missionId,
+        bundleId: result.bundleId,
+        message: result.message,
+      };
+    }
+    return {
+      success: false,
+      rejected: true,
+      reason: result.reason,
+      detail: result.detail,
+    };
+  },
+};
+
+const STOP_MOTION_TOOL: AITool = {
+  name: "stop_motion",
+  description:
+    "Stop the currently running mission/bundle. No-op if nothing is running. Use when the current task should be cancelled.",
+  parameters: {
+    type: "object",
+    properties: {
+      reason: {
+        type: "string",
+        description: "Optional reason for stopping (recorded in logs).",
+      },
+    },
+  },
+  handler: async (args, _event) => {
+    const ctx: MainToolContext | undefined = (handlerArgs as any).toolCtx;
+    if (!ctx) return { error: "tool context missing" };
+    const result = ctx.session.stopMission(
+      typeof args?.reason === "string" ? args.reason : "main_stop",
+    );
+    if (result.kind === "applied") {
+      return { success: true, message: result.message };
+    }
+    return {
+      success: false,
+      reason: result.reason,
+      detail: result.detail,
+    };
+  },
+};
+
+const PERFORM_ACTION_TOOL: AITool = {
+  name: "perform_action",
+  description:
+    "Execute a one-shot atomic action (drop item, send allowed server command, stop current task). " +
+    "Use for immediate actions that don't need multi-step planning.",
+  parameters: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        description: "Action name: 'drop_item' | 'send_command' | 'stop_current_task'.",
+      },
+      params: {
+        type: "object",
+        description: "Action-specific parameters.",
+      },
+    },
+    required: ["action"],
+  },
+  handler: async (args, _event) => {
+    const ctx: MainToolContext | undefined = (handlerArgs as any).toolCtx;
+    if (!ctx) return { error: "tool context missing" };
+    const action = String(args?.action ?? "").trim();
+    if (!action) return { error: "缺少 action" };
+    const params = (args?.params ?? {}) as Record<string, unknown>;
+    const outcome = await ctx.session.performAction(action, params);
+    return {
+      status: outcome.status,
+      code: outcome.code,
+      detail: outcome.detail,
+      data: outcome.data,
+    };
+  },
+};
+
+const DELEGATE_WORK_TOOL: AITool = {
+  name: "delegate_work",
+  description:
+    "Delegate a focused sub-task to the work agent. The work agent runs a synchronous sub-loop " +
+    "internally (multiple iterations, possibly up to 5 minutes) until the goal is complete, times out, " +
+    "or is cancelled. You will receive a final status report. Use this for tasks that need autonomous " +
+    "execution over time (e.g. 'gather 16 oak logs', 'follow player X for 2 minutes'). " +
+    "Do NOT use this for short actions — call start_motion or perform_action directly instead.",
+  parameters: {
+    type: "object",
+    properties: {
+      goal: {
+        type: "string",
+        description:
+          "Short high-level goal, e.g. 'gather 16 oak logs', 'follow kunkun for 2 minutes'.",
+      },
+      terminator: {
+        type: "object",
+        description:
+          "When to consider the goal complete. One of: " +
+          "{type: 'inventory_at_least', item, count}, " +
+          "{type: 'follow_for', target, ms}, " +
+          "{type: 'duration', ms}, " +
+          "{type: 'manual'} (you'll stop it next time).",
+        properties: {
+          type: {
+            type: "string",
+            enum: [
+              "inventory_at_least",
+              "follow_for",
+              "duration",
+              "manual",
+            ],
+          },
+          item: { type: "string" },
+          count: { type: "number" },
+          target: { type: "string" },
+          ms: { type: "number" },
+        },
+        required: ["type"],
+      },
+      maxMs: {
+        type: "number",
+        description: "Hard timeout in ms. Default: 300000 (5 minutes).",
+      },
+    },
+    required: ["goal", "terminator"],
+  },
+  handler: async (args, _event) => {
+    const ctx: MainToolContext | undefined = (handlerArgs as any).toolCtx;
+    if (!ctx) return { error: "tool context missing" };
+    const goal = String(args?.goal ?? "").trim();
+    const terminator = args?.terminator;
+    const maxMs = typeof args?.maxMs === "number" ? args.maxMs : undefined;
+    if (!goal) return { error: "缺少 goal" };
+    if (!terminator || typeof terminator !== "object") {
+      return { error: "缺少 terminator" };
+    }
+    const sub = ctx.workSubroutineFactory({
+      session: ctx.session,
+      goal,
+      terminator: terminator as any,
+      maxMs,
+    });
+    return await sub.run();
+  },
+};
+
+const LEAVE_SERVER_TOOL: AITool = {
+  name: "leave_server",
+  description:
+    "Disconnect the bot from the current Minecraft server and end the play session. " +
+    "A short goodbye will be sent. Use when the player asks to leave or you decide the session should end.",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (_args, _event) => {
+    const ctx: MainToolContext | undefined = (handlerArgs as any).toolCtx;
+    if (!ctx) return { error: "tool context missing" };
+    await ctx.session.stop("main_leave_requested");
+    return { success: true, message: "已离开服务器" };
+  },
+};
+
+export const MAIN_TOOLS: AITool[] = [
+  START_MOTION_TOOL,
+  STOP_MOTION_TOOL,
+  PERFORM_ACTION_TOOL,
+  DELEGATE_WORK_TOOL,
+  LEAVE_SERVER_TOOL,
+];
+
+let handlerArgs: { toolCtx?: MainToolContext } = {};
+
+export function bindMainToolContext(toolCtx: MainToolContext): void {
+  handlerArgs.toolCtx = toolCtx;
+}
+
+export function clearMainToolContext(): void {
+  handlerArgs.toolCtx = undefined;
+}
+
+export function buildMainSessionTools(): SessionToolDefinition[] {
+  return MAIN_TOOLS.map((tool) => ({ name: tool.name, tool }));
+}