mioku-plugin-mc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mioku Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# Mioku Minecraft Plugin
+
+Minecraft 服务器与 QQ 群消息互通插件，支持服务器状态监控与 RCON 命令执行，服务器需安装鹊桥模组或插件并配置。
+
+使用到的外部包：`@cikeyqi/queqiao-node-sdk`
+
+## 功能特性
+
+- **消息同步**：群聊消息同步到 MC 服务器，MC 服务器消息同步到群聊
+- **服务器状态推送**：玩家加入/退出/死亡/达成进度时自动推送到群聊
+- **RCON 命令执行**：在群聊中发送命令前缀开头的消息即可执行 RCON 命令
+- **多服务器支持**：可配置多个 MC 服务器，每个服务器独立设置连接方式
+- **正向/反向 WebSocket**：支持机器人主动连接或 MC 服务器反向连接
+
+## 安装
+
+将插件放置在 `plugins/mc/` 目录下，然后执行：
+
+```bash
+bun install
+```
+
+## 配置
+
+插件需要通过 WebUI 配置页面来管理配置项。
+
+### 全局配置
+
+| 配置项              | 类型     | 说明                         |
+|------------------|--------|----------------------------|
+| `聊天前缀`           | text   | QQ 消息转发到 MC 时显示的前缀，默认 "说：" |
+| `显示服务器名称`        | switch | 是否在推送消息中显示服务器名称            |
+| `启用反向 WebSocket` | switch | 启用反向连接（MC 服务器连接到此机器人）      |
+| `反向连接端口`         | number | 反向 WebSocket 监听端口          |
+| `反向连接路径`         | text   | 反向 WebSocket 路径            |
+| `反向连接密码`         | secret | 反向 WebSocket 连接密码          |
+
+### 服务器配置
+
+每个服务器可独立配置以下选项：
+
+| 配置项              | 类型     | 说明                          |
+|------------------|--------|-----------------------------|
+| `服务器名称`          | text   | 服务器唯一标识，不能与其他服务器重复          |
+| `WebSocket 地址`   | text   | 服务器 WebSocket 连接地址（正向连接时使用） |
+| `连接密码`           | text   | WebSocket 连接密码（可选）          |
+| `关联群聊`           | text   | 关联的 QQ 群号                   |
+| `机器人账号`          | text   | 使用哪个机器人 QQ 号发送消息            |
+| `命令前缀`           | text   | RCON 命令前缀，默认 "$"            |
+| `命令白名单`          | text   | 允许执行 RCON 命令的 QQ 号列表        |
+| `RCON 命令白名单`     | text   | 允许执行的 RCON 命令列表             |
+| `启用同步`           | switch | 是否启用消息同步                    |
+| `最大重连次数`         | number | WebSocket 最大重连次数            |
+| `启用正向 WebSocket` | switch | 启用正向连接（连接到 MC 服务器）          |
+| `启用反向连接`         | switch | 该服务器是否启用反向连接                |
+| `启用 RCON`        | switch | 启用 RCON 命令执行                |
+| `RCON 地址`        | text   | RCON 服务器地址                  |
+| `RCON 端口`        | number | RCON 端口                     |
+| `RCON 密码`        | secret | RCON 密码                     |
+
+## 命令
+
+| 命令                 | 描述                                     | 权限  |
+|--------------------|----------------------------------------|-----|
+| `/mc 状态`           | 查看所有已配置服务器的 WebSocket 连接状态，包括连接中、已断开等  | 主人  |
+| `/mc 开启同步 <服务器名称>` | 开启指定服务器的群聊消息同步功能，开启后该服务器可接收和发送群聊消息     | 主人 |
+| `/mc 关闭同步 <服务器名称>` | 关闭指定服务器的群聊消息同步功能，关闭后该服务器不再接收和发送群聊消息    | 主人 |
+| `/mc 重连`           | 断开并重新建立所有服务器的 WebSocket 连接，用于连接异常时手动恢复 | 主人  |

package/config.md

@@ -0,0 +1,139 @@
+---
+title: Minecraft 插件配置
+description: 配置 Minecraft 服务器连接、消息同步与 RCON 命令白名单
+fields:
+  - key: base.say_way
+    label: 聊天前缀
+    type: text
+    description: QQ 消息转发到 MC 时显示的前缀，默认 "说："
+    placeholder: 说：
+
+  - key: base.display_server_name
+    label: 显示服务器名称
+    type: switch
+    description: 消息中是否显示服务器名称
+
+  - key: base.reverse_ws_enabled
+    label: 启用反向 WebSocket
+    type: switch
+    description: 启用反向连接（MC 服务器连接到此机器人）
+
+  - key: base.reverse_ws_port
+    label: 反向连接端口
+    type: number
+    description: 反向 WebSocket 监听端口
+    placeholder: 8080
+
+  - key: base.reverse_ws_path
+    label: 反向连接路径
+    type: text
+    description: 反向 WebSocket 路径
+    placeholder: /minecraft/ws
+
+  - key: base.reverse_ws_password
+    label: 反向连接密码
+    type: secret
+    description: 反向 WebSocket 连接密码
+
+  - key: base.servers
+    label: 服务器列表
+    type: array
+    description: 配置多个 Minecraft 服务器连接
+    itemFields:
+      - key: server_name
+        label: 服务器名称
+        type: text
+        description: 服务器唯一标识，不能与其他服务器重复
+        placeholder: main
+
+      - key: ws_url
+        label: WebSocket 地址
+        type: text
+        description: 服务器 WebSocket 连接地址（正向连接时使用）
+        placeholder: ws://127.0.0.1:8081
+
+      - key: ws_password
+        label: 连接密码
+        type: text
+        description: WebSocket 连接密码（可选）
+
+      - key: group_list
+        label: 关联群聊
+        type: text
+        description: 关联的 QQ 群号
+
+      - key: bot_self_id
+        label: 机器人账号
+        type: text
+        description: 机器人 QQ 号
+
+      - key: command_header
+        label: 命令前缀
+        type: text
+        description: RCON 命令前缀，默认 "$"
+        placeholder: $
+
+      - key: command_user
+        label: 命令白名单
+        type: text
+        description: 允许执行 RCON 命令的 QQ 号列表，每行一个
+
+      - key: rcon_command_whitelist
+        label: RCON 命令白名单
+        type: text
+        description: 允许执行的 RCON 命令列表，每行一个
+
+      - key: sync_enabled
+        label: 启用同步
+        type: switch
+        description: 是否启用消息同步
+
+      - key: ws_max_attempts
+        label: 最大重连次数
+        type: number
+        description: WebSocket 最大重连次数
+        placeholder: 10
+
+      - key: forward_ws_enabled
+        label: 启用正向 WebSocket
+        type: switch
+        description: 启用正向连接（连接到 MC 服务器）
+
+      - key: reverse_ws_enabled
+        label: 启用反向连接
+        type: switch
+        description: 该服务器是否启用反向连接
+
+      - key: rcon_enabled
+        label: 启用 RCON
+        type: switch
+        description: 启用 RCON 命令执行
+
+      - key: rcon_host
+        label: RCON 地址
+        type: text
+        description: RCON 服务器地址
+        placeholder: 127.0.0.1
+
+      - key: rcon_port
+        label: RCON 端口
+        type: number
+        description: RCON 端口
+        placeholder: 25575
+
+      - key: rcon_password
+        label: RCON 密码
+        type: secret
+        description: RCON 密码
+---
+
+```mioku-fields
+keys:
+  - base.say_way
+  - base.display_server_name
+  - base.reverse_ws_enabled
+  - base.reverse_ws_port
+  - base.reverse_ws_path
+  - base.reverse_ws_password
+  - base.servers
+```

package/core/rcon.ts

@@ -0,0 +1,85 @@
+import type { ServerConfig } from "../types";
+
+export interface CommandResult {
+  status?: string;
+  message?: string;
+  data?: unknown;
+}
+
+export function parseCommand(
+  text: string,
+  serverItem: ServerConfig,
+): string | null {
+  const header = serverItem.command_header || "$";
+  const trimmed = text.trim();
+
+  if (!header || !trimmed.startsWith(header)) {
+    return null;
+  }
+
+  return trimmed.slice(header.length).trim();
+}
+
+export function isCommandAllowed(
+  text: string,
+  serverItem: ServerConfig,
+  isMaster: boolean,
+  userId: number | string,
+): boolean {
+  if (isMaster) return true;
+
+  // check whitelist
+  const cmdName = getCommandName(text);
+  const whitelist = serverItem.rcon_command_whitelist || [];
+  if (whitelist.some((w) => String(w).replace(/^\/+/, "") === cmdName)) {
+    return true;
+  }
+
+  // check user list
+  const userList = serverItem.command_user || [];
+  return userList.some((u) => String(u) === String(userId));
+}
+
+function getCommandName(text: string): string {
+  const trimmed = String(text).trim();
+  const parts = trimmed.split(/\s+/, 1);
+  return parts[0] || "";
+}
+
+export function formatCommandResult(raw: unknown): string {
+  if (raw === null || raw === undefined || raw === "") {
+    return "命令执行成功";
+  }
+
+  if (typeof raw === "string") {
+    try {
+      const parsed = JSON.parse(raw);
+      return formatCommandResult(parsed);
+    } catch {
+      return raw;
+    }
+  }
+
+  if (typeof raw !== "object") {
+    return String(raw);
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  if (obj.data !== null && obj.data !== undefined && obj.data !== "") {
+    return typeof obj.data === "string"
+      ? String(obj.data)
+      : JSON.stringify(obj.data);
+  }
+
+  const status = String(obj.status || "")
+    .trim()
+    .toUpperCase();
+  const message = String(obj.message || "").trim();
+
+  if (status && status !== "SUCCESS") {
+    return message || `命令执行失败 (${status})`;
+  }
+
+  return message || "命令执行成功";
+}

package/core/ws-factory.ts

@@ -0,0 +1,223 @@
+import {
+  createClient,
+  createReverseClient,
+  type QueQiaoClient,
+  type QueQiaoEvent,
+  type KnownApi,
+} from "@cikeyqi/queqiao-node-sdk";
+import type { McConfig, ServerConfig } from "../types";
+
+export interface WsClient {
+  serverName: string;
+  config: ServerConfig;
+  status: "connected" | "disconnected" | "connecting";
+  send(data: Record<string, unknown>): Promise<void>;
+  close(): void;
+}
+
+export interface WsServer {
+  status: "listening" | "stopped";
+  close(): void;
+}
+
+type EventHandler = (event: QueQiaoEvent) => void;
+type StatusHandler = (serverName: string, status: string) => void;
+type ErrorHandler = (serverName: string, error: Error) => void;
+
+// Safe string normalizer - empty string becomes undefined, otherwise trimmed
+function safeString(value: string | undefined | null): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+export function createForwardClient(
+  serverItem: ServerConfig,
+  onEvent: EventHandler,
+  onStatusChange: StatusHandler,
+  onError?: ErrorHandler,
+): WsClient {
+  let client: QueQiaoClient | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let reconnectAttempt = 0;
+  let currentStatus: "connected" | "disconnected" | "connecting" = "disconnected";
+
+  const updateStatus = (status: "connected" | "disconnected" | "connecting") => {
+    currentStatus = status;
+    onStatusChange(serverItem.server_name, status);
+  };
+
+  const connect = () => {
+    if (client) {
+      client.close().catch(() => {});
+      client = null;
+    }
+    updateStatus("connecting");
+
+    const accessToken = safeString(serverItem.ws_password);
+
+    client = createClient(
+      [
+        {
+          url: serverItem.ws_url,
+          selfName: serverItem.server_name,
+          accessToken: accessToken,
+        },
+      ],
+      {
+        reconnect: false,
+      },
+    );
+
+    client.on("connection_open", (_selfName: string) => {
+      reconnectAttempt = 0;
+      updateStatus("connected");
+    });
+
+    client.on("connection_close", (_selfName: string, _code: number, _reason: string) => {
+      updateStatus("disconnected");
+      scheduleReconnect();
+    });
+
+    client.on("connection_error", (_selfName: string, error: Error) => {
+      onError?.(serverItem.server_name, error);
+      updateStatus("disconnected");
+    });
+
+    client.on("event", (eventData: QueQiaoEvent) => {
+      onEvent(eventData);
+    });
+
+    client.on("error", () => {});
+
+    client.connect().catch((err: Error) => {
+      onError?.(serverItem.server_name, err);
+      updateStatus("disconnected");
+      scheduleReconnect();
+    });
+  };
+
+  const scheduleReconnect = () => {
+    if (reconnectTimer) return;
+    const maxAttempts = serverItem.ws_max_attempts || 0;
+
+    reconnectAttempt++;
+    if (maxAttempts > 0 && reconnectAttempt > maxAttempts) {
+      return;
+    }
+
+    // Exponential backoff: 10s, 20s, 30s, ... up to 60s
+    const baseDelay = 10000;
+    const delay = Math.min(baseDelay * reconnectAttempt, 60000);
+
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, delay);
+  };
+
+  const send = async (data: Record<string, unknown>): Promise<void> => {
+    const api = data.type as string;
+    const apiData = { ...data };
+    delete apiData.type;
+
+    if (!client || !client.isOpen({ selfName: serverItem.server_name })) {
+      throw new Error(`服务器 ${serverItem.server_name} 未连接`);
+    }
+    await client.request(
+      api as KnownApi,
+      apiData as Record<string, unknown>,
+      { selfName: serverItem.server_name },
+    );
+  };
+
+  const close = () => {
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    client?.close().catch(() => {});
+    client = null;
+    updateStatus("disconnected");
+  };
+
+  connect();
+
+  return {
+    serverName: serverItem.server_name,
+    config: serverItem,
+    get status() {
+      return currentStatus;
+    },
+    send,
+    close,
+  };
+}
+
+export function createReverseServer(
+  config: McConfig,
+  onEvent: EventHandler,
+  onStatusChange: StatusHandler,
+  onError?: ErrorHandler,
+): WsServer {
+  let client: QueQiaoClient | null = null;
+
+  const updateStatus = (status: "listening" | "stopped") => {
+    onStatusChange("reverse", status);
+  };
+
+  const start = () => {
+    if (!config.reverse_ws_port) {
+      return;
+    }
+
+    const accessToken = safeString(config.reverse_ws_password);
+
+    client = createReverseClient(
+      {
+        port: config.reverse_ws_port,
+        path: config.reverse_ws_path || "/minecraft/ws",
+        host: "0.0.0.0",
+      },
+      accessToken ? { accessToken } : {},
+    );
+
+    client.on("connection_open", (_selfName: string) => {
+      updateStatus("listening");
+    });
+
+    client.on("connection_close", (_selfName: string, _code: number, _reason: string) => {
+      updateStatus("stopped");
+    });
+
+    client.on("connection_error", (_selfName: string, error: Error) => {
+      onError?.("reverse", error);
+    });
+
+    client.on("event", (eventData: QueQiaoEvent) => {
+      onEvent(eventData);
+    });
+
+    client.on("error", () => {});
+
+    client.connect().catch((err: Error) => {
+      onError?.("reverse", err);
+      updateStatus("stopped");
+    });
+  };
+
+  const close = () => {
+    client?.close().catch(() => {});
+    client = null;
+    updateStatus("stopped");
+  };
+
+  start();
+
+  return {
+    get status() {
+      return client ? "listening" : "stopped";
+    },
+    close,
+  };
+}

package/handlers/reconnect.ts

@@ -0,0 +1,9 @@
+import type { ServerManager } from "../utils/server-manager";
+
+export function handleReconnect(
+  serverManager: ServerManager,
+  reply: (text: string) => Promise<void>,
+) {
+  serverManager.reconnectAll();
+  return reply("已发起重新连接请求");
+}

package/handlers/status.ts

@@ -0,0 +1,39 @@
+import type { ServerManager } from "../utils/server-manager";
+import type { McConfig } from "../types";
+
+export function handleStatus(
+  serverManager: ServerManager,
+  config: McConfig,
+  reply: (text: string) => Promise<void>,
+) {
+  if (config.servers.length === 0) {
+    return reply("暂无已配置的服务器");
+  }
+
+  const statusList = serverManager.getStatusList();
+
+  const lines: string[] = [];
+
+  config.servers.forEach((server, index) => {
+    if (index > 0) {
+      lines.push("");
+    }
+
+    const statusObj = statusList.find((s) => s.name === server.server_name);
+    const wsStatus = !server.forward_ws_enabled
+      ? "未启用"
+      : statusObj?.status === "connected"
+        ? "已连接"
+        : statusObj?.status === "connecting"
+          ? "连接中"
+          : "未连接";
+
+    const rconStatus = !server.rcon_enabled ? "未启用" : "已连接";
+
+    lines.push(`服务器：${server.server_name}`);
+    lines.push(`WebSocket 连接状态：${wsStatus}`);
+    lines.push(`RCON 连接状态：${rconStatus}`);
+  });
+
+  return reply(lines.join("\n"));
+}

package/handlers/sync.ts

@@ -0,0 +1,38 @@
+import type { ServerManager } from "../utils/server-manager";
+import type { ConfigHandler } from "../utils/config-handler";
+import type { McConfig } from "../types";
+
+export async function handleSync(
+  serverName: string | undefined,
+  enabled: boolean,
+  serverManager: ServerManager,
+  configHandler: ConfigHandler,
+  config: McConfig,
+  reply: (text: string) => Promise<void>,
+): Promise<boolean> {
+  if (!serverName) {
+    // show all servers and their sync status
+    if (config.servers.length === 0) {
+      await reply("暂无已配置的服务器");
+      return true;
+    }
+
+    const lines = config.servers.map((s) => {
+      const syncStatus = s.sync_enabled ? "已开启" : "已关闭";
+      return `${s.server_name}: ${syncStatus}`;
+    });
+    await reply(lines.join("\n"));
+    return true;
+  }
+
+  const serverItem = configHandler.findServerByName(serverName);
+  if (!serverItem) {
+    await reply(`未找到服务器「${serverName}」`);
+    return true;
+  }
+
+  await configHandler.updateServerSync(serverName, enabled);
+  const action = enabled ? "开启" : "关闭";
+  await reply(`${action}了服务器 ${serverName} 的同步`);
+  return true;
+}

package/index.ts

@@ -0,0 +1,203 @@
+import { definePlugin, type MiokiContext } from "mioki";
+import type { ConfigService } from "../../src/services/config/tpyes";
+import { createConfigHandler } from "./utils/config-handler";
+import { createServerManager } from "./utils/server-manager";
+import { parseMcCommand } from "./utils/command-router";
+import { handleStatus } from "./handlers/status";
+import { handleSync } from "./handlers/sync";
+import { handleReconnect } from "./handlers/reconnect";
+import { formatMcEvent, formatQqToMc } from "./utils/message-formatter";
+import {
+  parseCommand,
+  isCommandAllowed,
+  formatCommandResult,
+} from "./core/rcon";
+import type { McEvent } from "./types";
+import type { McConfig } from "./types";
+
+export default definePlugin({
+  name: "mc",
+  version: "1.0.0",
+  description: "Minecraft服务器与QQ群消息互通插件",
+
+  async setup(ctx: MiokiContext) {
+    const configService = ctx.services?.config as ConfigService | undefined;
+
+    const configHandler = createConfigHandler(configService);
+    await configHandler.register();
+
+    const config = configHandler.getConfig();
+
+    const serverManager = createServerManager(
+      (serverName, status) => {
+        ctx.logger.info(`[MC] 服务器 ${serverName} 状态: ${status}`);
+      },
+      (event: McEvent) => {
+        handleMcEvent(ctx, event, config, configHandler);
+      },
+      {
+        error: (msg: string) => ctx.logger.error(msg),
+      },
+    );
+
+    serverManager.startServers(config);
+
+    ctx.handle("message", async (event: any) => {
+      const text = ctx.text(event).trim();
+      const parsed = parseMcCommand(text);
+
+      if (!parsed || parsed.action === "") {
+        if (event.group_id) {
+          await forwardToMc(ctx, event, config, configHandler, serverManager);
+        }
+        return;
+      }
+
+      switch (parsed.action) {
+        case "状态": {
+          await handleStatus(serverManager, config, (msg) => event.reply(msg));
+          break;
+        }
+        case "开启同步": {
+          const serverName = parsed.args[0];
+          await handleSync(
+            serverName,
+            true,
+            serverManager,
+            configHandler,
+            config,
+            (msg) => event.reply(msg),
+          );
+          break;
+        }
+        case "关闭同步": {
+          const serverName = parsed.args[0];
+          await handleSync(
+            serverName,
+            false,
+            serverManager,
+            configHandler,
+            config,
+            (msg) => event.reply(msg),
+          );
+          break;
+        }
+        case "重连": {
+          if (ctx.isOwner?.(event)) {
+            await handleReconnect(serverManager, (msg) => event.reply(msg));
+          }
+          break;
+        }
+      }
+    });
+
+    ctx.logger.info("Minecraft插件加载成功");
+
+    return () => {
+      serverManager.stopServers();
+      ctx.logger.info("Minecraft插件已卸载");
+    };
+  },
+});
+
+async function handleMcEvent(
+  ctx: MiokiContext,
+  event: McEvent,
+  config: McConfig,
+  configHandler: ReturnType<typeof createConfigHandler>,
+) {
+  const messageText = formatMcEvent(event, config);
+  if (!messageText) return;
+
+  const serverName = event.server_name || "";
+  const serverItem = configHandler.findServerByName(serverName);
+  if (!serverItem) return;
+
+  if (serverItem.sync_enabled === false) return;
+
+  const botList = serverItem.bot_self_id || "";
+  const groupList = serverItem.group_list || "";
+
+  const bots = botList ? [botList] : [];
+  const groups = groupList ? [groupList] : [];
+
+  for (const botId of bots) {
+    const bot = ctx.pickBot(Number(botId));
+    if (!bot) continue;
+
+    for (const groupId of groups) {
+      try {
+        await bot.sendGroupMsg(Number(groupId), messageText);
+      } catch (err) {
+        ctx.logger.error(`[MC] 发送消息到群 ${groupId} 失败: ${err}`);
+      }
+    }
+  }
+}
+
+async function forwardToMc(
+  ctx: MiokiContext,
+  event: any,
+  config: McConfig,
+  configHandler: ReturnType<typeof createConfigHandler>,
+  serverManager: ReturnType<typeof createServerManager>,
+) {
+  const text = ctx.text(event);
+  ctx.logger.debug(`[MC] 收到群消息 group=${event.group_id} text=${text}`);
+
+  // 检查是否为群消息
+  if (!event.group_id) {
+    return;
+  }
+
+  const servers = configHandler.getServersForGroup(event.group_id);
+  if (servers.length === 0) return;
+
+  const msgList = Array.isArray(event.message)
+    ? event.message
+    : [{ type: "text", text: text }];
+
+  for (const server of servers) {
+    if (server.sync_enabled === false) continue;
+
+    const commandText = parseCommand(text, server);
+    if (commandText !== null) {
+      if (server.rcon_enabled === false) continue;
+
+      const isAllowed = isCommandAllowed(
+        commandText,
+        server,
+        ctx.isOwner?.(event) ?? false,
+        event.user_id ?? "",
+      );
+
+      if (isAllowed) {
+        try {
+          const result = await serverManager.sendToServer(
+            server.server_name,
+            "send_rcon_command",
+            { command: commandText },
+          );
+          await event.reply(formatCommandResult(result));
+        } catch (err) {
+          await event.reply(`执行命令失败: ${err}`);
+        }
+      }
+      continue;
+    }
+
+    try {
+      const mcMessage = formatQqToMc(
+        event.sender || {},
+        msgList,
+        config,
+        server,
+      );
+      await serverManager.sendToServer(server.server_name, "broadcast", {
+        message: mcMessage,
+      });
+    } catch (err) {
+      ctx.logger.error(`[MC] 发送到服务器 ${server.server_name} 失败: ${err}`);
+    }
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mioku-plugin-mc",
+  "version": "1.0.0",
+  "description": "Minecraft与QQ群消息互通插件，支持服务器状态监控与RCON命令",
+  "main": "index.ts",
+  "keywords": [
+    "mioku"
+  ],
+  "mioku": {
+    "services": [
+      "config"
+    ],
+    "help": {
+      "title": "Minecraft",
+      "description": "Minecraft服务器与QQ群消息互通插件，支持服务器状态监控与RCON命令",
+      "commands": [
+        {
+          "cmd": "/mc 状态",
+          "desc": "查看所有已配置服务器的WebSocket连接状态，包括连接中、已断开等",
+          "role": "master"
+        },
+        {
+          "cmd": "/mc 开启同步",
+          "desc": "开启指定服务器的群聊消息同步功能，开启后该服务器可接收和发送群聊消息",
+          "usage": "/mc 开启同步 <服务器名称>",
+          "role": "master"
+        },
+        {
+          "cmd": "/mc 关闭同步",
+          "desc": "关闭指定服务器的群聊消息同步功能，关闭后该服务器不再接收和发送群聊消息",
+          "usage": "/mc 关闭同步 <服务器名称>",
+          "role": "master"
+        },
+        {
+          "cmd": "/mc 重连",
+          "desc": "断开并重新建立所有服务器的WebSocket连接，用于连接异常时手动恢复",
+          "role": "master"
+        }
+      ]
+    }
+  },
+  "dependencies": {
+    "@cikeyqi/queqiao-node-sdk": "^0.1.3"
+  }
+}

package/types.ts

@@ -0,0 +1,79 @@
+export interface McEvent {
+  post_type: string;
+  sub_type: string;
+  server_name?: string;
+  player?: { nickname?: string };
+  message?: string;
+  raw_message?: unknown;
+  death?: { text?: string; translate?: { text?: string } };
+  command?: string;
+  achievement?: {
+    text?: string;
+    translate?: { text?: string };
+    display?: {
+      title?: { text?: string; translate?: { text?: string } };
+    };
+  };
+}
+
+export interface ServerConfig {
+  server_name: string;
+  ws_url: string;
+  ws_password?: string;
+  ws_max_attempts?: number;
+  group_list: string;
+  bot_self_id: string;
+  command_header?: string;
+  command_user?: string[];
+  rcon_command_whitelist?: string[];
+  mc_qq_chat_image_enable?: boolean;
+  mask_word?: string;
+  sync_enabled?: boolean;
+  // RCON
+  rcon_enabled?: boolean;
+  rcon_host?: string;
+  rcon_port?: number;
+  rcon_password?: string;
+  // WebSocket direction control (per server)
+  forward_ws_enabled?: boolean;
+  reverse_ws_enabled?: boolean;
+}
+
+export interface McConfig {
+  servers: ServerConfig[];
+  say_way: string;
+  display_server_name: boolean;
+  // Reverse WS server (global, not per-server)
+  reverse_ws_enabled?: boolean;
+  reverse_ws_port?: number;
+  reverse_ws_path?: string;
+  reverse_ws_password?: string;
+}
+
+export const DEFAULT_CONFIG: McConfig = {
+  servers: [],
+  say_way: "说：",
+  display_server_name: true,
+  reverse_ws_enabled: false,
+  reverse_ws_port: 8080,
+  reverse_ws_path: "/minecraft/ws",
+  reverse_ws_password: "",
+};
+
+export function normalizeConfig(raw: Partial<McConfig>): McConfig {
+  const servers = Array.isArray(raw.servers) ? raw.servers : [];
+
+  return {
+    servers: servers.map((s) => ({
+      ...s,
+      group_list: typeof s.group_list === "string" ? s.group_list.trim() : "",
+      bot_self_id: typeof s.bot_self_id === "string" ? s.bot_self_id.trim() : "",
+    })),
+    say_way: raw.say_way || DEFAULT_CONFIG.say_way,
+    display_server_name: raw.display_server_name ?? DEFAULT_CONFIG.display_server_name,
+    reverse_ws_enabled: raw.reverse_ws_enabled ?? DEFAULT_CONFIG.reverse_ws_enabled,
+    reverse_ws_port: raw.reverse_ws_port ?? DEFAULT_CONFIG.reverse_ws_port,
+    reverse_ws_path: raw.reverse_ws_path ?? DEFAULT_CONFIG.reverse_ws_path,
+    reverse_ws_password: raw.reverse_ws_password ?? DEFAULT_CONFIG.reverse_ws_password,
+  };
+}

package/utils/command-router.ts

@@ -0,0 +1,51 @@
+export interface ParsedCommand {
+  action: string;
+  args: string[];
+  raw: string;
+}
+
+export function parseMcCommand(text: string): ParsedCommand | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/mc")) return null;
+
+  const remainder = trimmed.slice(3).trim();
+  if (!remainder) {
+    return { action: "", args: [], raw: "" };
+  }
+
+  // split into action and args
+  const parts = remainder.split(/\s+/);
+  const action = parts[0] || "";
+  const args = parts.slice(1);
+
+  return { action, args, raw: remainder };
+}
+
+export function matchMcCommand(
+  text: string,
+  pattern: RegExp
+): RegExpMatchArray | null {
+  const parsed = parseMcCommand(text);
+  if (!parsed) return null;
+  return parsed.raw.match(pattern);
+}
+
+export function buildStatusReply(
+  serverName: string,
+  status: string,
+  displayName?: string
+): string {
+  const name = displayName || serverName;
+  const icon = status === "connected" ? "在线" : status === "connecting" ? "连接中" : "离线";
+  return `[${name}] ${icon}`;
+}
+
+export function buildSyncReply(
+  serverName: string,
+  enabled: boolean,
+  displayName?: string
+): string {
+  const name = displayName || serverName;
+  const action = enabled ? "开启" : "关闭";
+  return `${action}了服务器 ${name} 的同步`;
+}

package/utils/config-handler.ts

@@ -0,0 +1,49 @@
+import type { ConfigService } from "../../../src/services/config/tpyes";
+import { DEFAULT_CONFIG, normalizeConfig, type McConfig } from "../types";
+
+export function createConfigHandler(configService: ConfigService | undefined) {
+  let currentConfig: McConfig = { ...DEFAULT_CONFIG };
+
+  const register = async () => {
+    if (!configService) return;
+    await configService.registerConfig("mc", "base", DEFAULT_CONFIG);
+    const raw = await configService.getConfig("mc", "base");
+    currentConfig = normalizeConfig(raw);
+    configService.onConfigChange("mc", "base", (next) => {
+      currentConfig = normalizeConfig(next);
+    });
+  };
+
+  const getConfig = () => currentConfig;
+
+  const updateServerSync = async (serverName: string, enabled: boolean) => {
+    if (!configService) return;
+    const servers = currentConfig.servers.map((s) =>
+      s.server_name === serverName ? { ...s, sync_enabled: enabled } : s,
+    );
+    await configService.updateConfig("mc", "base", { servers });
+  };
+
+  const findServerByName = (serverName: string) => {
+    return (
+      currentConfig.servers.find((s) => s.server_name === serverName) || null
+    );
+  };
+
+  const getServersForGroup = (groupId: string | number): typeof currentConfig.servers => {
+    const gid = String(groupId);
+    return currentConfig.servers.filter((s) => {
+      return s.group_list == gid;
+    });
+  };
+
+  return {
+    register,
+    getConfig,
+    updateServerSync,
+    findServerByName,
+    getServersForGroup,
+  };
+}
+
+export type ConfigHandler = ReturnType<typeof createConfigHandler>;

package/utils/message-formatter.ts

@@ -0,0 +1,117 @@
+import type { McConfig, McEvent } from "../types";
+
+export function formatMcEvent(event: McEvent, config: McConfig): string | null {
+  const { sub_type, player, message, server_name } = event;
+
+  const sayWord = config.say_way || "说：";
+  const playerName = player?.nickname || "未知玩家";
+
+  let body: string | null = null;
+
+  switch (sub_type) {
+    case "player_join":
+      body = `${playerName} 加入了游戏`;
+      break;
+    case "player_quit":
+      body = `${playerName} 退出了游戏`;
+      break;
+    case "player_death":
+      body =
+        event.death?.text ||
+        event.death?.translate?.text ||
+        `${playerName} 死亡了`;
+      break;
+    case "player_command":
+      body = `${playerName} 使用命令 ${event.command || ""}`.trim();
+      break;
+    case "player_achievement": {
+      const titleRaw =
+        event.achievement?.translate?.text ||
+        event.achievement?.text ||
+        event.achievement?.display?.title?.text ||
+        event.achievement?.display?.title?.translate?.text ||
+        event.achievement?.display?.title;
+      const title = typeof titleRaw === "string" ? titleRaw : null;
+      if (title) {
+        body =
+          event.achievement?.translate?.text || event.achievement?.text
+            ? title
+            : `${playerName} 达成了进度 ${title}`;
+      }
+      break;
+    }
+    case "player_chat": {
+      const content = message || extractText(event.raw_message);
+      if (content) {
+        body = `${playerName} ${sayWord} ${content}`.trim();
+      }
+      break;
+    }
+    default:
+      return null;
+  }
+
+  if (!body) return null;
+
+  if (!config.display_server_name) return body;
+  const name = server_name || "未知服务器";
+  return `[${name}] ${body}`;
+}
+
+function extractText(raw: unknown): string {
+  if (!raw) return "";
+  if (typeof raw === "string") return raw.trim();
+  if (typeof raw !== "object") return String(raw);
+
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.text === "string") return obj.text;
+  if (typeof obj.translate === "string") return obj.translate;
+
+  const withArr = Array.isArray(obj.with) ? obj.with : [];
+  if (withArr.length > 0) {
+    return withArr.map((w) => (typeof w === "string" ? w : "")).join("");
+  }
+
+  return "";
+}
+
+export function formatQqToMc(
+  sender: { nickname?: string; card?: string; user_id?: number | string },
+  messageArr: Array<{ type: string; text?: string; url?: string }>,
+  config: McConfig,
+  serverItem: { mc_qq_chat_image_enable?: boolean },
+): Array<{ text: string; color?: string }> {
+  const result: Array<{ text: string; color?: string }> = [];
+  const sayWord = config.say_way || "说：";
+
+  const nick =
+    sender.nickname || sender.card || String(sender.user_id ?? "未知用户");
+
+  result.push({ text: nick, color: "green" });
+  result.push({ text: ` ${sayWord} `, color: "white" });
+
+  for (const msg of messageArr) {
+    if (msg.type === "text") {
+      result.push({
+        text: String(msg.text ?? "")
+          .replace(/\r/g, "")
+          .replace(/\n/g, "\n * "),
+        color: "white",
+      });
+    } else if (msg.type === "image") {
+      const imageUrl = String(msg.url || "");
+      if (serverItem.mc_qq_chat_image_enable) {
+        result.push({ text: `[[CICode,url=${imageUrl},name=图片]]` });
+      } else {
+        result.push({ text: "[图片]", color: "light_purple" });
+      }
+    } else {
+      result.push({
+        text: `[${msg.type}] ${msg.text || ""}`.trim(),
+        color: "white",
+      });
+    }
+  }
+
+  return result;
+}

package/utils/server-manager.ts

@@ -0,0 +1,126 @@
+import {
+  createForwardClient,
+  createReverseServer,
+  type WsClient,
+  type WsServer,
+} from "../core/ws-factory";
+import type { McConfig, McEvent } from "../types";
+import type { QueQiaoEvent } from "@cikeyqi/queqiao-node-sdk";
+
+export type StatusCallback = (serverName: string, status: string) => void;
+export type EventCallback = (event: McEvent) => void;
+
+export function createServerManager(
+  onStatusChange: StatusCallback,
+  onMcEvent: EventCallback,
+  logger?: { error: (msg: string) => void },
+) {
+  const forwardClients = new Map<string, WsClient>();
+  let reverseServer: WsServer | null = null;
+
+  const handleEvent = (event: QueQiaoEvent) => {
+    onMcEvent(event as McEvent);
+  };
+
+  const handleError = (serverName: string, error: Error) => {
+    logger?.error(`[MC] 服务器 ${serverName} 连接错误: ${error.message}`);
+  };
+
+  const handleClose = (serverName: string, code: number, reason: string) => {
+    logger?.error(`[MC] 服务器 ${serverName} 连接断开: code=${code} reason=${reason || '-'}`);
+  };
+
+  const startServers = (config: McConfig) => {
+    // close existing
+    stopServers();
+
+    // start reverse server if enabled (global, one instance)
+    if (config.reverse_ws_enabled && config.reverse_ws_port) {
+      reverseServer = createReverseServer(config, handleEvent, onStatusChange, handleError);
+    }
+
+    // start new forward connections
+    for (const server of config.servers) {
+      if (!server.server_name) continue;
+
+      // skip if sync is disabled
+      if (server.sync_enabled === false) continue;
+
+      // Forward WS: bot connects to MC server
+      if (server.forward_ws_enabled !== false && server.ws_url) {
+        const client = createForwardClient(server, handleEvent, onStatusChange, handleError);
+        forwardClients.set(server.server_name, client);
+      }
+    }
+  };
+
+  const stopServers = () => {
+    forwardClients.forEach((client) => client.close());
+    forwardClients.clear();
+    reverseServer?.close();
+    reverseServer = null;
+  };
+
+  const reconnectAll = () => {
+    forwardClients.forEach((client) => client.close());
+    forwardClients.clear();
+    reverseServer?.close();
+    reverseServer = null;
+  };
+
+  const getClient = (serverName: string) => forwardClients.get(serverName) || null;
+
+  const getConnectedNames = () => {
+    const names: string[] = [];
+    forwardClients.forEach((client, name) => {
+      if (client.status === "connected") {
+        names.push(name);
+      }
+    });
+    return names;
+  };
+
+  const isServerConnected = (serverName: string) => {
+    const client = forwardClients.get(serverName);
+    return client?.status === "connected";
+  };
+
+  const sendToServer = async (
+    serverName: string,
+    api: string,
+    data: Record<string, unknown>,
+  ) => {
+    const client = forwardClients.get(serverName);
+    if (!client) {
+      throw new Error(`服务器 ${serverName} 未配置`);
+    }
+    if (client.status !== "connected") {
+      throw new Error(`服务器 ${serverName} 未连接`);
+    }
+    return client.send({ type: api, ...data });
+  };
+
+  const getStatusList = () => {
+    const list: Array<{ name: string; status: string }> = [];
+    forwardClients.forEach((client, name) => {
+      list.push({ name, status: client.status });
+    });
+    if (reverseServer) {
+      list.push({ name: "reverse", status: reverseServer.status });
+    }
+    return list;
+  };
+
+  return {
+    startServers,
+    stopServers,
+    reconnectAll,
+    getClient,
+    getConnectedNames,
+    isServerConnected,
+    sendToServer,
+    getStatusList,
+  };
+}
+
+export type ServerManager = ReturnType<typeof createServerManager>;