mioku-plugin-mc 2.1.0 → 3.0.1

package/config.md

@@ -75,12 +75,12 @@ fields:
 
       - key: command_user
         label: 命令白名单
-        type: text
+        type: textarea
         description: 允许执行 RCON 命令的 QQ 号列表，每行一个
 
       - key: rcon_command_whitelist
         label: RCON 命令白名单
-        type: text
+        type: textarea
         description: 允许执行的 RCON 命令列表，每行一个
 
       - key: sync_enabled
@@ -125,6 +125,145 @@ fields:
         label: RCON 密码
         type: secret
         description: RCON 密码
+
+  - key: play.servers
+    label: 游玩服务器列表
+    type: array
+    description: bot 可加入游玩的 Minecraft 服务器（原版/leaves）
+    itemFields:
+      - key: id
+        label: 服务器 ID
+        type: text
+        description: 唯一标识，AI 工具按此选择服务器
+        placeholder: survival
+      - key: name
+        label: 显示名称
+        type: text
+        description: 服务器显示名
+        placeholder: 生存服
+      - key: host
+        label: 地址
+        type: text
+        description: 服务器地址。可写 host[:port]（如 play.example.com:25565），省略端口时会自动尝试 _minecraft._tcp.<host> 的 SRV 解析，失败则默认 25565
+        placeholder: play.example.com
+      - key: version
+        label: 版本
+        type: text
+        description: Minecraft 版本，留空自动协商
+        placeholder: "1.20.4"
+      - key: username
+        label: 假人名称
+        type: text
+        description: bot 加入服务器使用的名字
+        placeholder: MikuBot
+      - key: auth
+        label: 认证方式
+        type: text
+        description: offline 或 microsoft，默认 offline
+        placeholder: offline
+      - key: password
+        label: 认证密码
+        type: secret
+        description: microsoft 认证时使用
+      - key: maxPlayMs
+        label: 最长游玩时长(ms)
+        type: number
+        description: 单次游玩最长时长，到点自动下线
+        placeholder: 1800000
+
+      - key: joinCommands
+        label: 加入后自动执行的命令
+        type: textarea
+        description: bot 第一次进入该服务器后自动发送的命令（每行一条，如 /login xxx），仅在首次 spawn 时执行，重生不重复
+
+      - key: allowedCommands
+        label: AI 命令白名单
+        type: textarea
+        description: Working AI 可发送的斜杠命令前缀，每行一条；未列出的命令会被拒绝
+
+  - key: play.groups
+    label: 群聊绑定
+    type: array
+    description: 配置哪些群允许触发 bot 游玩及可选服务器
+    itemFields:
+      - key: groupId
+        label: 群号
+        type: text
+        description: QQ 群号
+        placeholder: "518680610"
+      - key: botSelfId
+        label: 机器人账号
+        type: text
+        description: 该群使用的 bot QQ 号
+      - key: allowedServerIds
+        label: 允许的服务器
+        type: textarea
+        description: 允许该群触发的服务器 ID，每行一个
+
+  - key: play.toolPermission
+    label: 工具权限
+    type: text
+    description: 谁可触发 bot 进出服（owner/admin/member，需重启生效）
+    placeholder: admin
+  - key: play.mainChatDebounceMs
+    label: 主 AI 防抖(ms)
+    type: number
+    description: 同一玩家连续触发主 AI 的最小间隔（仅 @bot/名字时才生效）
+    placeholder: 1000
+  - key: play.mainConversationFocusMs
+    label: 游戏连续对话窗口(ms)
+    type: number
+    description: 玩家明确呼叫 bot 后，后续消息可继续触发主 AI 的时间窗口
+    placeholder: 120000
+  - key: play.workTerminationCheckMs
+    label: 工作终止检查间隔(ms)
+    type: number
+    description: session watchdog 检查工作目标终止条件的频率
+    placeholder: 1000
+  - key: play.workStaleMs
+    label: 工作停滞超时(ms)
+    type: number
+    description: 工作目标在该时长内无进展时，自动拉起 work agent 重新评估
+    placeholder: 600000
+  - key: play.workGoalTimeoutMs
+    label: 工作目标总超时(ms)
+    type: number
+    description: 单个工作目标最长允许存活的时间，到点自动标记失败
+    placeholder: 1800000
+  - key: play.maxMissionMs
+    label: Mission 最大时长(ms)
+    type: number
+    description: 单个 mission 最大运行时间，到点强制结束（防 isFinished 缺失或抛错导致永久占用）
+    placeholder: 1800000
+  - key: play.behaviorTickIntervalMs
+    label: 行为引擎 tick(ms)
+    type: number
+    description: 行为引擎 tick 间隔
+    placeholder: 200
+  - key: play.maxPlayBudgetWarnRatio
+    label: 预算提醒比例
+    type: number
+    description: 到该比例时提醒主模型收尾
+    placeholder: 0.85
+  - key: play.goodbyeTimeoutMs
+    label: 告别超时(ms)
+    type: number
+    description: 生成告别语的超时时间
+    placeholder: 8000
+  - key: play.qqSendPerMinute
+    label: QQ 每分钟上限
+    type: number
+    description: bot 向 QQ 群发送消息的每分钟上限
+    placeholder: 3
+  - key: play.gameChatMinIntervalMs
+    label: 游戏发言间隔(ms)
+    type: number
+    description: bot 游戏内连续发言最小间隔
+    placeholder: 1500
+  - key: play.debug.enabled
+    label: 调试模式
+    type: switch
+    description: 开启后主人可用 /join /say /motion 等命令手动测试行为（不启动 AI 循环），详见 play/debug/README.md
 ---
 
 ```mioku-fields
@@ -136,4 +275,19 @@ keys:
   - base.reverse_ws_path
   - base.reverse_ws_password
   - base.servers
-```
+  - play.servers
+  - play.groups
+  - play.toolPermission
+  - play.mainChatDebounceMs
+  - play.mainConversationFocusMs
+  - play.workTerminationCheckMs
+  - play.workStaleMs
+  - play.workGoalTimeoutMs
+  - play.maxMissionMs
+  - play.behaviorTickIntervalMs
+  - play.maxPlayBudgetWarnRatio
+  - play.goodbyeTimeoutMs
+  - play.qqSendPerMinute
+  - play.gameChatMinIntervalMs
+  - play.debug.enabled
+```

package/index.ts

@@ -1,6 +1,10 @@
 import { definePlugin, type MiokiContext } from "mioki";
-import type { ConfigService } from "mioku";
+import { getService, Services } from "mioku";
 import { createConfigHandler } from "./utils/config-handler";
+import { createPlayConfigHandler } from "./play/config";
+import { createPlayManager } from "./play";
+import { createMcSkill } from "./skills/mc";
+import { handleDebugCommand } from "./play/debug/commands";
 import { createServerManager } from "./utils/server-manager";
 import { parseMcCommand } from "./utils/command-router";
 import { handleStatus } from "./handlers/status";
@@ -21,13 +25,31 @@ export default definePlugin({
   description: "Minecraft服务器与QQ群消息互通插件",
 
   async setup(ctx: MiokiContext) {
-    const configService = ctx.services?.config as ConfigService | undefined;
+    const configService = getService(ctx, Services.Config);
 
     const configHandler = createConfigHandler(configService);
     await configHandler.register();
 
     const config = configHandler.getConfig();
 
+    const playConfigHandler = createPlayConfigHandler(configService);
+    await playConfigHandler.register();
+
+    const aiService = getService(ctx, Services.AI);
+
+    const playManager = createPlayManager({
+      ctx,
+      aiService,
+      configService,
+      playConfigHandler,
+      syncConfigHandler: configHandler,
+    });
+    ctx.logger.info("Minecraft 游玩子系统已就绪");
+
+    if (aiService) {
+      aiService.registerSkill(createMcSkill(playManager));
+    }
+
     const serverManager = createServerManager(
       (serverName, status) => {
         ctx.logger.info(`[MC] 服务器 ${serverName} 状态: ${status}`);
@@ -42,12 +64,32 @@ export default definePlugin({
 
     serverManager.startServers(config);
 
-    ctx.handle("message", async (event: any) => {
+    ctx.handle("message", async (event) => {
       const text = ctx.text(event).trim();
+      const groupId =
+        "group_id" in event && typeof event.group_id === "number"
+          ? event.group_id
+          : undefined;
+
+      if (groupId) {
+        const reply = await handleDebugCommand({
+          text,
+          isOwner: ctx.isOwner?.(event) ?? false,
+          debugEnabled: playConfigHandler.getConfig().debug.enabled,
+          playManager,
+          groupId: Number(groupId),
+        });
+        if (reply !== null) {
+          await event.reply(reply);
+          return;
+        }
+      }
+
       const parsed = parseMcCommand(text);
 
       if (!parsed || parsed.action === "") {
-        if (event.group_id) {
+        if (groupId) {
+          playManager.onQqMessage(event);
           await forwardToMc(ctx, event, config, configHandler, serverManager);
         }
         return;
@@ -55,7 +97,9 @@ export default definePlugin({
 
       switch (parsed.action) {
         case "状态": {
-          await handleStatus(serverManager, config, (msg) => event.reply(msg));
+          await handleStatus(serverManager, config, async (msg) => {
+            await event.reply(msg);
+          });
           break;
         }
         case "开启同步": {
@@ -66,7 +110,9 @@ export default definePlugin({
             serverManager,
             configHandler,
             config,
-            (msg) => event.reply(msg),
+            async (msg) => {
+              await event.reply(msg);
+            },
           );
           break;
         }
@@ -78,13 +124,17 @@ export default definePlugin({
             serverManager,
             configHandler,
             config,
-            (msg) => event.reply(msg),
+            async (msg) => {
+              await event.reply(msg);
+            },
           );
           break;
         }
         case "重连": {
           if (ctx.isOwner?.(event)) {
-            await handleReconnect(serverManager, (msg) => event.reply(msg));
+            await handleReconnect(serverManager, async (msg) => {
+              await event.reply(msg);
+            });
           }
           break;
         }
@@ -93,8 +143,10 @@ export default definePlugin({
 
     ctx.logger.info("Minecraft插件加载成功");
 
-    return () => {
+    return async () => {
       serverManager.stopServers();
+      await playManager.dispose();
+      if (aiService) aiService.removeSkill("mc");
       ctx.logger.info("Minecraft插件已卸载");
     };
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-mc",
-  "version": "2.1.0",
+  "version": "3.0.1",
   "description": "Minecraft与QQ群消息互通插件，支持服务器状态监控与RCON命令",
   "main": "index.ts",
   "type": "module",
@@ -13,7 +13,8 @@
   },
   "mioku": {
     "services": [
-      "config"
+      "config",
+      "ai"
     ],
     "accessHooks": [
       {
@@ -63,7 +64,11 @@
     }
   },
   "dependencies": {
-    "@cikeyqi/queqiao-node-sdk": "^0.1.3"
+    "@cikeyqi/queqiao-node-sdk": "^0.1.3",
+    "minecraft-data": "^3.111.0",
+    "mineflayer": "^4.37.1",
+    "vec3": "^0.2.0",
+    "zod": "^3.24.1"
   },
   "peerDependencies": {
     "mioku": "^0.8.0",

package/play/actions/registry.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+import type { MissionErrorCode } from "../state/mode";
+import type { PlayServerConfig } from "../types";
+
+export interface ActionOutcome {
+  action: string;
+  status: "succeeded" | "failed";
+  code?: MissionErrorCode;
+  detail: string;
+  data?: unknown;
+  at: number;
+  directiveId?: string;
+  completesDirectiveOnSuccess: boolean;
+}
+
+export interface ActionContext {
+  bot: any;
+  server: PlayServerConfig;
+  stopCurrentTask: (reason?: string) => void;
+}
+
+interface ActionDefinition {
+  name: string;
+  description: string;
+  paramsSchema: z.ZodTypeAny;
+  run(
+    ctx: ActionContext,
+    params: any,
+  ): Promise<{ detail: string; data?: unknown }>;
+}
+
+export class ActionRegistry {
+  private actions = new Map<string, ActionDefinition>();
+
+  constructor() {
+    this.register(defaultDropItemAction);
+    this.register(defaultSendCommandAction);
+    this.register(defaultStopTaskAction);
+  }
+
+  register(action: ActionDefinition): void {
+    this.actions.set(action.name, action);
+  }
+
+  list(): Array<{ name: string; description: string }> {
+    return [...this.actions.values()]
+      .map((action) => ({ name: action.name, description: action.description }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  async execute(
+    name: string,
+    params: unknown,
+    ctx: ActionContext,
+    meta: { directiveId?: string; completesDirectiveOnSuccess?: boolean } = {},
+  ): Promise<ActionOutcome> {
+    const action = this.actions.get(name);
+    if (!action) {
+      return failed(name, "unknown", `未知动作: ${name}`, meta);
+    }
+    const parsed = action.paramsSchema.safeParse(params ?? {});
+    if (!parsed.success) {
+      return failed(
+        name,
+        "unknown",
+        parsed.error.issues
+          .map(
+            (issue) => `${issue.path.join(".") || "params"}: ${issue.message}`,
+          )
+          .join("; "),
+        meta,
+      );
+    }
+    try {
+      const result = await action.run(ctx, parsed.data);
+      return {
+        action: name,
+        status: "succeeded",
+        detail: result.detail,
+        data: result.data,
+        at: Date.now(),
+        directiveId: meta.directiveId,
+        completesDirectiveOnSuccess: meta.completesDirectiveOnSuccess ?? true,
+      };
+    } catch (error) {
+      const typed = normalizeActionError(error);
+      return failed(name, typed.code, typed.detail, meta);
+    }
+  }
+}
+
+const defaultDropItemAction: ActionDefinition = {
+  name: "drop_item",
+  description: "丢出指定数量的背包物品，可选先面向附近玩家。",
+  paramsSchema: z.object({
+    item: z.string().trim().min(1),
+    count: z.number().int().min(1).max(64).default(1),
+    target: z.string().trim().min(1).optional(),
+  }),
+  async run(ctx, params) {
+    const candidates =
+      ctx.bot.inventory
+        ?.items?.()
+        .filter((item: any) => item.name === params.item) ?? [];
+    const available = candidates.reduce(
+      (sum: number, item: any) => sum + Number(item.count ?? 0),
+      0,
+    );
+    if (available < params.count) {
+      throw actionError(
+        "missing_item",
+        `物品 ${params.item} 不足，需要 ${params.count}，现有 ${available}`,
+      );
+    }
+    if (params.target) {
+      const player = ctx.bot.players?.[params.target]?.entity;
+      if (!player?.position)
+        throw actionError("target_not_found", `找不到玩家 ${params.target}`);
+      await ctx.bot.lookAt(player.position.offset(0, 1, 0), true);
+    }
+    let remaining = params.count;
+    for (const item of candidates) {
+      if (remaining <= 0) break;
+      const amount = Math.min(remaining, Number(item.count ?? 0));
+      await ctx.bot.toss(item.type, item.metadata ?? null, amount);
+      remaining -= amount;
+    }
+    return { detail: `已丢出 ${params.count} 个 ${params.item}`, data: params };
+  },
+};
+
+const defaultSendCommandAction: ActionDefinition = {
+  name: "send_command",
+  description: "发送服务器允许列表中的斜杠命令。",
+  paramsSchema: z.object({ command: z.string().trim().min(2).max(256) }),
+  async run(ctx, params) {
+    const command = params.command.startsWith("/")
+      ? params.command
+      : `/${params.command}`;
+    const allowed = ctx.server.allowedCommands.some(
+      (entry) => command === entry || command.startsWith(`${entry} `),
+    );
+    if (!allowed)
+      throw actionError("permission_denied", `命令不在允许列表中: ${command}`);
+    ctx.bot.chat(command);
+    return { detail: `已发送命令 ${command}` };
+  },
+};
+
+const defaultStopTaskAction: ActionDefinition = {
+  name: "stop_current_task",
+  description: "停止当前高层任务并回到 idle。",
+  paramsSchema: z.object({ reason: z.string().trim().max(256).optional() }),
+  async run(ctx, params) {
+    ctx.stopCurrentTask(params.reason ?? "work_action_stop");
+    return { detail: "已停止当前任务" };
+  },
+};
+
+function actionError(
+  code: MissionErrorCode,
+  detail: string,
+): Error & { code: MissionErrorCode } {
+  return Object.assign(new Error(detail), { code });
+}
+
+function normalizeActionError(error: unknown): {
+  code: MissionErrorCode;
+  detail: string;
+} {
+  if (error && typeof error === "object" && "code" in error) {
+    const typed = error as { code: MissionErrorCode; message?: string };
+    return {
+      code: typed.code,
+      detail: String(typed.message || error),
+    };
+  }
+  return { code: "unknown", detail: String(error) };
+}
+
+function failed(
+  action: string,
+  code: MissionErrorCode,
+  detail: string,
+  meta: { directiveId?: string; completesDirectiveOnSuccess?: boolean },
+): ActionOutcome {
+  return {
+    action,
+    status: "failed",
+    code,
+    detail,
+    at: Date.now(),
+    directiveId: meta.directiveId,
+    completesDirectiveOnSuccess: meta.completesDirectiveOnSuccess ?? true,
+  };
+}

package/play/ai/context-builder.ts

@@ -0,0 +1,29 @@
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (!value || typeof value !== "object") return value;
+  const source = value as Record<string, unknown>;
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(source).sort()) {
+    const next = source[key];
+    if (next !== undefined) sorted[key] = sortValue(next);
+  }
+  return sorted;
+}
+
+export class SectionRevisionTracker {
+  private values = new Map<string, string>();
+  private revisions = new Map<string, number>();
+
+  revision(key: string, value: unknown): number {
+    const serialized = stableStringify(value);
+    if (this.values.get(key) !== serialized) {
+      this.values.set(key, serialized);
+      this.revisions.set(key, (this.revisions.get(key) ?? 0) + 1);
+    }
+    return this.revisions.get(key) ?? 0;
+  }
+}

package/play/ai/debug-log.ts

@@ -0,0 +1,135 @@
+import type { PlayConfig } from "../types";
+
+type LoggerLike = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+};
+
+export interface AiLogRequest {
+  messages: Array<{ role: string; content: unknown }>;
+  tools?: Array<{ function?: { name?: string } } | undefined>;
+  temperature?: number;
+  max_tokens?: number;
+  trigger?: string;
+  triggerEvents?: unknown;
+}
+
+export interface AiLogResponse {
+  content?: string | null;
+  reasoning?: string | null;
+  toolCalls?: Array<{ name: string; arguments: string }>;
+  durationMs: number;
+  error?: unknown;
+}
+
+export function logAiRequest(
+  logger: LoggerLike,
+  config: PlayConfig,
+  tag: "main" | "work" | "goodbye",
+  payload: AiLogRequest,
+): void {
+  if (!config.debug.enabled) return;
+  const toolNames = (payload.tools ?? [])
+    .map((t) => t?.function?.name)
+    .filter((name): name is string => typeof name === "string")
+    .join(", ");
+  const lines: string[] = [];
+  lines.push(
+    `[MC/play] ▶ AI req (${tag})` +
+      ` T=${payload.temperature ?? "?"}` +
+      ` max=${payload.max_tokens ?? "?"}` +
+      (toolNames ? ` tools=[${toolNames}]` : "") +
+      (payload.trigger ? ` trigger=${payload.trigger}` : "") +
+      (Array.isArray(payload.triggerEvents)
+        ? ` events=${payload.triggerEvents.length}`
+        : ""),
+  );
+  for (const message of payload.messages) {
+    const role = String(message.role ?? "unknown");
+    const text = stringifyContent(message.content);
+    lines.push(`  ↳ ${role} (${text.length}c): ${truncate(text, 600)}`);
+  }
+  logger.info(lines.join("\n"));
+}
+
+export function logAiResponse(
+  logger: LoggerLike,
+  config: PlayConfig,
+  tag: "main" | "work" | "goodbye",
+  payload: AiLogResponse,
+): void {
+  if (!config.debug.enabled) return;
+  if (payload.error !== undefined) {
+    logger.warn(
+      `[MC/play] ◀ AI resp (${tag}) failed in ${payload.durationMs}ms: ${stringifyError(payload.error)}`,
+    );
+    return;
+  }
+  const parts: string[] = [];
+  parts.push(`[MC/play] ◀ AI resp (${tag}) ${payload.durationMs}ms`);
+  const contentText = safeText(payload.content);
+  if (contentText && contentText.length > 0) {
+    parts.push(`text=${truncate(contentText, 600)}`);
+  }
+  const reasoningText = safeText(payload.reasoning);
+  if (reasoningText && reasoningText.length > 0) {
+    parts.push(`reasoning=${truncate(reasoningText, 300)}`);
+  }
+  if (payload.toolCalls && payload.toolCalls.length > 0) {
+    for (const call of payload.toolCalls) {
+      const name = safeText(call.name) ?? "(unnamed)";
+      const args = safeText(call.arguments) ?? "{}";
+      parts.push(`tool=${name}(${truncate(args, 400)})`);
+    }
+  }
+  if (parts.length === 1) parts.push("(empty)");
+  logger.info(parts.join(" | "));
+}
+
+function stringifyContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (content == null) return "";
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (!part || typeof part !== "object") return String(part);
+        const obj = part as Record<string, unknown>;
+        if (obj.type === "text" && typeof obj.text === "string") return obj.text;
+        try {
+          return JSON.stringify(part);
+        } catch {
+          return String(part);
+        }
+      })
+      .join(" ");
+  }
+  if (typeof content === "object") {
+    try {
+      return JSON.stringify(content);
+    } catch {
+      return "[unserializable]";
+    }
+  }
+  return String(content);
+}
+
+function safeText(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  return value;
+}
+
+function truncate(text: unknown, max: number): string {
+  const raw = typeof text === "string" ? text : safeText(text) ?? "";
+  const collapsed = raw.replace(/\s+/g, " ").trim();
+  return collapsed.length > max ? collapsed.slice(0, max) + "…" : collapsed;
+}
+
+function stringifyError(error: unknown): string {
+  if (error instanceof Error) return `${error.name}: ${error.message}`;
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}