mioku-plugin-mc 2.0.0 → 3.0.0

package/play/ai/prompt.ts

@@ -0,0 +1,207 @@
+import type { ActionOutcome } from "../actions/registry";
+import type { PlayEvent } from "../state/event-journal";
+import type { BehaviorSnapshot } from "../state/snapshot";
+import type { PlayServerConfig, WorkStatus } from "../types";
+import { stableStringify } from "./context-builder";
+import type { WorkTerminator } from "./work-subroutine";
+
+export function buildGoodbyePrompt(
+  persona: string,
+  server: PlayServerConfig,
+): string {
+  const lines: string[] = [];
+  if (persona) lines.push("## Persona", persona, "");
+  lines.push(
+    "## Task",
+    `You are leaving the Minecraft server \"${server.name}\" right now.`,
+    "Say a short in-character goodbye to the players in the server chat.",
+    "1 or 2 short lines. No markers, no quotes, no preamble.",
+    "Output ONLY the goodbye text.",
+  );
+  return lines.join("\n");
+}
+
+export interface MainPromptContext {
+  persona: string;
+  bundles: unknown;
+  actions: unknown;
+  workStatus: WorkStatus | null;
+  focusedUntil: number;
+}
+
+export function buildMainSystemPrompt(input: MainPromptContext): string {
+  return [
+    "You are the only AI for a Minecraft bot that is currently in-game.",
+    "You see the bot's vitals, inventory, equipment, nearby entities, world state, recent chat, and (if running) the work subroutine's status.",
+    "",
+    "## Your output IS the chat reply",
+    "- Your plain-text response will be split by newlines and sent to the in-game chat, one line per newline.",
+    "- Keep total text short (max 3 short lines, each <=256 chars).",
+    "- Empty text is fine when silence is the right answer.",
+    "- DO NOT output JSON, tool-call syntax, or anything else. Just natural language chat lines.",
+    "",
+    "## How to act",
+    "- You have tools. Each tool call is one action. The bot executes tools synchronously — you wait for completion before your next move.",
+    "- For multi-step autonomous tasks (e.g. gather 16 oak logs, follow player X for 2 minutes), use `delegate_work` so the work agent runs the sub-task and returns a status.",
+    "- For short or immediate actions, call `start_motion`, `perform_action`, or `stop_motion` directly.",
+    "- Use `leave_server` only when the player asks to leave or the session must end.",
+    "",
+    "## Focus rules",
+    "- If a player asked you to do something, STAY ON THAT TASK. Do not switch to a different topic just because new chat arrived.",
+    "- You are NOT interrupted by in-game events (damage, hostile mobs, equipment loss). Your behavior engine handles survival automatically; you keep planning.",
+    "- If a new message explicitly @-mentions the bot while you are in the middle of a tool chain, your MainLoop will queue it; you will see and respond to it in your NEXT turn, after the current tool completes.",
+    "- Don't repeat yourself. Don't echo the player's message. Don't narrate actions in asterisks.",
+    "",
+    "## Chat scan context",
+    "- When you are triggered by `chat_scan_due` (every few minutes), review the recent chat lines. Reply ONLY if there's something that actually needs a response (someone asked you a question, or said something noteworthy). Otherwise output empty text and end your turn.",
+    "",
+    "## Reading the work status",
+    "- When a task is delegated to work, you can see its `summary` and `progress` passively. Use it to answer player questions like \"what are you doing?\" without re-running anything.",
+    "- Do NOT call `delegate_work` again while one is already running (`workStatus.running === true`). Either wait, or stop the current one first with `stop_motion`.",
+    "",
+    `Available motion bundles:\n${stableStringify(input.bundles)}`,
+    `Available atomic actions:\n${stableStringify(input.actions)}`,
+    "",
+    input.persona
+      ? `Persona:\n${input.persona}`
+      : "Persona: act friendly, concise, and human-like.",
+  ].join("\n");
+}
+
+export interface WorkPromptContext {
+  goal: string;
+  terminator: WorkTerminator;
+  bundles: unknown;
+  actions: unknown;
+}
+
+export function buildWorkSystemPrompt(input: WorkPromptContext): string {
+  const terminatorDescription = describeTerminator(input.terminator);
+  return [
+    "You are the work agent for a Minecraft bot, called as a synchronous subroutine by the main agent.",
+    "Your single job is to drive the bot until the goal is complete, then return.",
+    "",
+    "## Your single assignment",
+    `Goal: ${input.goal}`,
+    `Terminator: ${terminatorDescription}`,
+    "",
+    "## How to act",
+    "- You have tools to start/stop motion bundles, perform atomic actions, and update status.",
+    "- Pick ONE next action per turn. Don't try to do multiple things at once.",
+    "- Do NOT output chat lines — only tool calls and (optionally) text that updates the status report.",
+    "- Call `update_status` only when progress changed meaningfully (e.g. collected 4 logs out of 16). Don't spam status updates.",
+    "- When the terminator condition is met (inventory threshold reached, follow duration elapsed, etc.), just stop calling new actions and end your turn — the subroutine will detect completion and return.",
+    "",
+    "## Failure handling",
+    "- If a motion/action outcome is failed or blocked, do NOT silently retry the same thing. Read the structured error code and adapt:",
+    "  target_not_found → switch target or search elsewhere",
+    "  resource_not_found → wander or give up",
+    "  missing_tool → craft a prerequisite first",
+    "  inventory_full → drop or deposit",
+    "  path_unreachable → try another area",
+    "  path_timeout → break line of sight and try again",
+    "  permission_denied → stop the goal",
+    "  disconnected → wait briefly",
+    "",
+    "Stable mission error codes include target_not_found, target_lost, resource_not_found, missing_item, missing_tool, inventory_full, path_unreachable, path_timeout, permission_denied, command_rejected, disconnected, cancelled, and unknown.",
+    "",
+    `Available motion bundles:\n${stableStringify(input.bundles)}`,
+    `Available atomic actions:\n${stableStringify(input.actions)}`,
+  ].join("\n");
+}
+
+function describeTerminator(t: WorkTerminator): string {
+  switch (t.type) {
+    case "inventory_at_least":
+      return `inventory has at least ${t.count} × ${t.item}`;
+    case "follow_for":
+      return `follow ${t.target} for ${t.ms} ms`;
+    case "duration":
+      return `run for ${t.ms} ms total`;
+    case "manual":
+      return "main agent will stop you when done";
+  }
+}
+
+export function buildSessionFacts(input: {
+  serverName: string;
+  username: string;
+  groupId: number;
+  maxPlayMs: number;
+  allowedCommands: string[];
+}): string {
+  return `SESSION_FACTS\n${stableStringify(input)}`;
+}
+
+export interface MainUserContextInput {
+  trigger: string;
+  events: PlayEvent[];
+  snapshot: BehaviorSnapshot;
+  workStatus: WorkStatus | null;
+  elapsedMs: number;
+  maxMs: number;
+}
+
+export function buildMainUserContext(input: MainUserContextInput): string {
+  const snapshot = input.snapshot;
+  return `CURRENT_MAIN_CONTEXT\n${stableStringify({
+    trigger: input.trigger,
+    elapsedMs: input.elapsedMs,
+    maxMs: input.maxMs,
+    events: input.events,
+    workStatus: input.workStatus,
+    status: {
+      health: snapshot.vitals.health,
+      food: snapshot.vitals.food,
+      oxygen: snapshot.vitals.oxygen,
+      position: snapshot.position,
+      dimension: snapshot.dimension,
+      equipment: snapshot.equipment,
+      heldItem: snapshot.heldItem,
+      inventory: {
+        items: snapshot.inventory.items.slice(0, 24),
+        emptySlots: snapshot.inventory.emptySlots,
+        full: snapshot.inventory.full,
+      },
+      nearbyPlayers: snapshot.entities
+        .filter((entity) => entity.kind === "player")
+        .slice(0, 8),
+      nearbyHostiles: snapshot.entities
+        .filter((entity) => entity.kind === "hostile")
+        .slice(0, 8),
+      environment: {
+        timeOfDay: snapshot.environment.timeOfDay,
+        isDay: snapshot.environment.isDay,
+        weather: snapshot.environment.weather,
+        biome: snapshot.environment.biome,
+        terrain: {
+          below: snapshot.environment.terrain.below,
+          feet: snapshot.environment.terrain.feet,
+          head: snapshot.environment.terrain.head,
+          nearbyInteresting:
+            snapshot.environment.terrain.nearbyInteresting.slice(0, 12),
+        },
+      },
+      mission: snapshot.mission,
+      activeBehaviors: snapshot.activeBehaviors.filter((b) => b.active),
+    },
+  })}`;
+}
+
+export interface WorkUserContextInput {
+  goal: string;
+  terminator: WorkTerminator;
+  triggerEvents: PlayEvent[];
+  snapshot: BehaviorSnapshot;
+  lastActionOutcome: ActionOutcome | null;
+}
+
+export function buildWorkUserContext(input: WorkUserContextInput): string {
+  return `CURRENT_WORK_CONTEXT\n${stableStringify({
+    goal: input.goal,
+    terminator: input.terminator,
+    triggerEvents: input.triggerEvents,
+    lastActionOutcome: input.lastActionOutcome,
+    world: input.snapshot,
+  })}`;
+}

package/play/ai/work-subroutine.ts

@@ -0,0 +1,487 @@
+import type { AIInstance, AITool, SessionToolDefinition } from "mioku";
+import type { PlaySession } from "../session";
+import type { PlayEvent } from "../state/event-journal";
+import {
+  buildWorkSystemPrompt,
+  buildWorkUserContext,
+} from "./prompt";
+import { withTimeoutMs } from "../util/async";
+import { logAiRequest, logAiResponse } from "./debug-log";
+
+export type WorkTerminator =
+  | { type: "inventory_at_least"; item: string; count: number }
+  | { type: "follow_for"; target: string; ms: number }
+  | { type: "duration"; ms: number }
+  | { type: "manual" };
+
+export interface WorkSubroutineOptions {
+  session: PlaySession;
+  goal: string;
+  terminator: WorkTerminator;
+  maxMs?: number;
+  maxIterations?: number;
+}
+
+export interface WorkSubroutineResult {
+  status: "completed" | "timeout" | "failed" | "cancelled";
+  summary: string;
+  iterations: number;
+  elapsedMs: number;
+  artifacts: Record<string, unknown>;
+}
+
+const WORK_MODEL_TIMEOUT_MS = 60_000;
+
+export class WorkSubroutine {
+  private readonly session: PlaySession;
+  private readonly goal: string;
+  private readonly terminator: WorkTerminator;
+  private readonly maxMs: number;
+  private readonly maxIterations: number;
+  private readonly startedAt: number;
+  private status: "running" | "completed" | "timeout" | "failed" | "cancelled" =
+    "running";
+  private lastSummary = "";
+  private lastProgress: { current: number; target: number; unit: string } | undefined;
+  private toolCtxBound = false;
+
+  constructor(opts: WorkSubroutineOptions) {
+    this.session = opts.session;
+    this.goal = opts.goal;
+    this.terminator = opts.terminator;
+    this.maxMs = opts.maxMs ?? 5 * 60_000;
+    this.maxIterations = opts.maxIterations ?? 25;
+    this.startedAt = Date.now();
+  }
+
+  get options(): { goal: string; terminator: WorkTerminator } {
+    return { goal: this.goal, terminator: this.terminator };
+  }
+
+  async run(): Promise<WorkSubroutineResult> {
+    const work = this.session.getPluginCtx().workInstance;
+    if (!work) {
+      return {
+        status: "failed",
+        summary: "work AI 实例不可用",
+        iterations: 0,
+        elapsedMs: Date.now() - this.startedAt,
+        artifacts: {},
+      };
+    }
+
+    bindWorkToolContext({
+      session: this.session,
+      onStatusUpdate: (summary, progress) => {
+        this.lastSummary = summary;
+        this.lastProgress = progress;
+        this.session.updateWorkStatus({
+          running: true,
+          goal: this.goal,
+          summary,
+          progress,
+          updatedAt: Date.now(),
+        });
+      },
+    });
+    this.toolCtxBound = true;
+    this.session.updateWorkStatus({
+      running: true,
+      goal: this.goal,
+      summary: `开始执行: ${this.goal}`,
+      updatedAt: Date.now(),
+    });
+
+    const cursor = this.session.events.latestCursor();
+    let iterations = 0;
+
+    try {
+      while (iterations < this.maxIterations) {
+        if (Date.now() - this.startedAt > this.maxMs) {
+          this.status = "timeout";
+          break;
+        }
+        if (this.isTerminatorMet()) {
+          this.status = "completed";
+          break;
+        }
+        if (this.session.isStopped) {
+          this.status = "cancelled";
+          break;
+        }
+
+        const decision = await this.runOneTurn(work, cursor);
+        iterations += 1;
+        if (!decision) continue;
+        if (decision.fatal) {
+          this.status = "failed";
+          break;
+        }
+      }
+      if (this.status === "running") {
+        this.status =
+          Date.now() - this.startedAt > this.maxMs ? "timeout" : "completed";
+      }
+    } finally {
+      if (this.toolCtxBound) {
+        clearWorkToolContext();
+        this.toolCtxBound = false;
+      }
+      this.session.updateWorkStatus({
+        running: false,
+        goal: this.goal,
+        summary: this.lastSummary || this.statusDefaultSummary(),
+        progress: this.lastProgress,
+        updatedAt: Date.now(),
+      });
+      this.session.events.append("work_completed", {
+        goal: this.goal,
+        status: this.status,
+        iterations,
+      });
+    }
+
+    return {
+      status: this.status,
+      summary: this.lastSummary || this.statusDefaultSummary(),
+      iterations,
+      elapsedMs: Date.now() - this.startedAt,
+      artifacts: {
+        progress: this.lastProgress,
+      },
+    };
+  }
+
+  private statusDefaultSummary(): string {
+    switch (this.status) {
+      case "completed":
+        return `目标已完成: ${this.goal}`;
+      case "timeout":
+        return `目标超时: ${this.goal}`;
+      case "failed":
+        return `目标失败: ${this.goal}`;
+      case "cancelled":
+        return `目标取消: ${this.goal}`;
+      default:
+        return `目标进行中: ${this.goal}`;
+    }
+  }
+
+  private isTerminatorMet(): boolean {
+    const bot = this.session.getBot();
+    if (!bot) return false;
+    switch (this.terminator.type) {
+      case "inventory_at_least": {
+        const total = countInventoryItem(bot, this.terminator.item);
+        return total >= this.terminator.count;
+      }
+      case "follow_for":
+      case "duration":
+      case "manual":
+        return false;
+      default:
+        return false;
+    }
+  }
+
+  private async runOneTurn(
+    work: AIInstance,
+    cursor: number,
+  ): Promise<{ fatal: boolean } | null> {
+    const snapshot = this.session.getBehaviorSnapshot();
+    if (!snapshot) return null;
+
+    const batch = this.session.events.readAfter(cursor, isWorkEvent, 50);
+    const triggerEvents = batch.events.length > 0 ? batch.events : [];
+
+    const context = buildWorkUserContext({
+      goal: this.goal,
+      terminator: this.terminator,
+      triggerEvents,
+      snapshot,
+      lastActionOutcome: this.session.getLastActionOutcome(),
+    });
+
+    const config = this.session.getPluginCtx().getPlayConfig();
+    const startedAt = Date.now();
+    const messages = [
+      { role: "system" as const, content: this.buildWorkSystemPrompt() },
+      { role: "user" as const, content: context },
+    ];
+    logAiRequest(this.session.getPluginCtx().ctx.logger, config, "work", {
+      trigger: `iteration:${this.iterationsLabel()}`,
+      messages,
+      tools: WORK_TOOLS as any[],
+      temperature: 0.2,
+      max_tokens: 600,
+      triggerEvents,
+    });
+
+    let response;
+    try {
+      response = await withTimeoutMs(
+        work.complete({
+          messages,
+          tools: WORK_TOOL_SCHEMAS,
+          temperature: 0.2,
+          max_tokens: 600,
+        }),
+        WORK_MODEL_TIMEOUT_MS,
+      );
+    } catch (error) {
+      logAiResponse(this.session.getPluginCtx().ctx.logger, config, "work", {
+        durationMs: Date.now() - startedAt,
+        error,
+      });
+      this.session
+        .getPluginCtx()
+        .ctx.logger.warn(`[MC/play] 工作模型调用失败: ${error}`);
+      return null;
+    }
+    if (!response) {
+      return null;
+    }
+    logAiResponse(this.session.getPluginCtx().ctx.logger, config, "work", {
+      durationMs: Date.now() - startedAt,
+      content: response.content ?? null,
+      reasoning: response.reasoning ?? null,
+      toolCalls: response.toolCalls ?? [],
+    });
+
+    let toolCalls = response.toolCalls ?? [];
+    let content = response.content;
+    let lastFatal = false;
+    while (toolCalls.length > 0 || (content && content.trim().length > 0)) {
+      if (content && content.trim().length > 0) {
+        const trimmed = content.trim();
+        if (trimmed.length > 0 && !this.lastSummary) {
+          this.lastSummary = trimmed;
+        }
+        content = null;
+      }
+      if (toolCalls.length === 0) break;
+      const call = toolCalls.shift()!;
+      const result = await runWorkToolCall(call);
+      if (result.fatal) lastFatal = true;
+      if (result.outputText) {
+        this.lastSummary = result.outputText;
+      }
+    }
+
+    return { fatal: lastFatal };
+  }
+
+  private iterationsLabel(): string {
+    return String(Math.floor((Date.now() - this.startedAt) / 1000));
+  }
+
+  private buildWorkSystemPrompt(): string {
+    const bundles = this.session.describeBundles();
+    const actions = this.session.listActions();
+    return buildWorkSystemPrompt({
+      goal: this.goal,
+      terminator: this.terminator,
+      bundles,
+      actions,
+    });
+  }
+}
+
+interface WorkToolContext {
+  session: PlaySession;
+  onStatusUpdate: (
+    summary: string,
+    progress?: { current: number; target: number; unit: string },
+  ) => void;
+}
+
+let workHandlerCtx: { ctx?: WorkToolContext } = {};
+
+export function bindWorkToolContext(ctx: WorkToolContext): void {
+  workHandlerCtx.ctx = ctx;
+}
+
+export function clearWorkToolContext(): void {
+  workHandlerCtx.ctx = undefined;
+}
+
+const WORK_START_MOTION: AITool = {
+  name: "start_motion",
+  description:
+    "Start a behavior bundle. Returns success or rejection reason. Use only ONE bundle at a time — " +
+    "starting a new bundle cancels the previous one.",
+  parameters: {
+    type: "object",
+    properties: {
+      bundle: { type: "string" },
+      params: { type: "object" },
+    },
+    required: ["bundle"],
+  },
+  handler: async (args) => {
+    const ctx = workHandlerCtx.ctx;
+    if (!ctx) return { fatal: true, detail: "work tool context missing" };
+    const bundle = String(args?.bundle ?? "").trim();
+    const params = (args?.params ?? {}) as Record<string, unknown>;
+    if (!bundle) return { fatal: false, detail: "缺少 bundle" };
+    const result = ctx.session.startMission({ bundle, params });
+    if (result.kind === "applied") {
+      return { success: true, missionId: result.missionId, bundleId: result.bundleId };
+    }
+    return { success: false, rejected: true, reason: result.reason, detail: result.detail };
+  },
+};
+
+const WORK_STOP_MOTION: AITool = {
+  name: "stop_motion",
+  description: "Stop the current bundle mission. No-op if nothing is running.",
+  parameters: {
+    type: "object",
+    properties: { reason: { type: "string" } },
+  },
+  handler: async (args) => {
+    const ctx = workHandlerCtx.ctx;
+    if (!ctx) return { fatal: true };
+    const result = ctx.session.stopMission(
+      typeof args?.reason === "string" ? args.reason : "work_stop",
+    );
+    if (result.kind === "applied") return { success: true, message: result.message };
+    return { success: false, reason: result.reason, detail: result.detail };
+  },
+};
+
+const WORK_PERFORM_ACTION: AITool = {
+  name: "perform_action",
+  description:
+    "Execute an atomic one-shot action (drop_item, send_command, stop_current_task).",
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string" },
+      params: { type: "object" },
+    },
+    required: ["action"],
+  },
+  handler: async (args) => {
+    const ctx = workHandlerCtx.ctx;
+    if (!ctx) return { fatal: true };
+    const action = String(args?.action ?? "").trim();
+    const params = (args?.params ?? {}) as Record<string, unknown>;
+    if (!action) return { fatal: false, detail: "缺少 action" };
+    const outcome = await ctx.session.performAction(action, params);
+    return {
+      status: outcome.status,
+      code: outcome.code,
+      detail: outcome.detail,
+    };
+  },
+};
+
+const WORK_UPDATE_STATUS: AITool = {
+  name: "update_status",
+  description:
+    "Update the passive status report that the main agent can read on demand. " +
+    "Use sparingly — only when the user-visible progress changed meaningfully.",
+  parameters: {
+    type: "object",
+    properties: {
+      summary: {
+        type: "string",
+        description: "Short status text, e.g. '正在砍第 4 棵树'.",
+      },
+      progress: {
+        type: "object",
+        description: "Optional numeric progress {current, target, unit}.",
+        properties: {
+          current: { type: "number" },
+          target: { type: "number" },
+          unit: { type: "string" },
+        },
+      },
+    },
+    required: ["summary"],
+  },
+  handler: async (args) => {
+    const ctx = workHandlerCtx.ctx;
+    if (!ctx) return { fatal: true };
+    const summary = String(args?.summary ?? "").trim();
+    if (!summary) return { fatal: false, detail: "缺少 summary" };
+    const progress = normalizeProgress(args?.progress);
+    ctx.onStatusUpdate(summary, progress);
+    return { success: true };
+  },
+};
+
+const WORK_TOOLS: AITool[] = [
+  WORK_START_MOTION,
+  WORK_STOP_MOTION,
+  WORK_PERFORM_ACTION,
+  WORK_UPDATE_STATUS,
+];
+
+const WORK_TOOL_SCHEMAS = WORK_TOOLS.map((tool) => ({
+  type: "function" as const,
+  function: {
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+  },
+}));
+
+export function buildWorkSessionTools(): SessionToolDefinition[] {
+  return WORK_TOOLS.map((tool) => ({ name: tool.name, tool }));
+}
+
+async function runWorkToolCall(call: {
+  name: string;
+  arguments: string;
+  id?: string;
+}): Promise<{ fatal: boolean; outputText?: string }> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(call.arguments || "{}");
+  } catch {
+    return { fatal: false };
+  }
+  const tool = WORK_TOOLS.find((t) => t.name === call.name);
+  if (!tool) return { fatal: false };
+  try {
+    const result = await tool.handler(parsed);
+    if (call.name === "update_status" && result && typeof result === "object") {
+      const r = result as { summary?: string };
+      if (typeof r.summary === "string") return { fatal: false, outputText: r.summary };
+    }
+    return { fatal: false };
+  } catch (error) {
+    return { fatal: false };
+  }
+}
+
+function normalizeProgress(input: unknown):
+  | { current: number; target: number; unit: string }
+  | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  const r = input as Record<string, unknown>;
+  const current = Number(r.current);
+  const target = Number(r.target);
+  const unit = typeof r.unit === "string" ? r.unit.trim() : "";
+  if (!Number.isFinite(current) || !Number.isFinite(target) || target <= 0 || !unit) {
+    return undefined;
+  }
+  return { current, target, unit };
+}
+
+function isWorkEvent(event: PlayEvent): boolean {
+  return !["game_chat", "qq_chat", "chat_scan_due"].includes(event.type);
+}
+
+function countInventoryItem(bot: any, itemName: string): number {
+  let total = 0;
+  for (const item of bot.inventory?.items?.() ?? []) {
+    const name = String(item.name ?? "").replace(/^minecraft:/, "");
+    if (name === itemName || name === `minecraft:${itemName}`) {
+      total += Number(item.count ?? 0);
+    }
+  }
+  return total;
+}