mioku-plugin-terraria 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,37 @@
+# mioku-plugin-terraria
+
+为 Mioku 提供 Terraria（TShock）服务器与 QQ 群消息互通能力，使用 [TianSuo](https://github.com/17TheWord/QueQiao) 协议（JSON over WebSocket）。
+
+## 功能特性
+
+- **消息双向同步**：QQ 群消息广播到 Terraria 服务器，Terraria 服务器内玩家聊天、加入、退出、死亡事件推送到群聊
+- **RCON 命令执行**：在群聊中以命令前缀（默认 `$`）开头的消息会被当作服务器命令执行，支持白名单
+- **多服务器支持**：可同时连接多台 Terraria 服务器，每台独立配置
+- **自动重连**：连接断开后按指数退避自动重连，可配置最大重试次数
+
+## 服务器端要求
+
+Terraria 服务器需安装 [TianSuo](https://github.com/17TheWord/QueQiao) TShock 插件
+
+```bash
+bun install
+```
+
+## 配置
+
+通过 WebUI 配置页面管理
+
+## 命令
+
+| 命令                       | 描述                       | 权限  |
+|--------------------------|--------------------------|-----|
+| `/ts 状态`                  | 查看所有服务器的 WebSocket 连接状态  | 主人  |
+| `/ts 开启同步 <服务器名称>`       | 开启指定服务器的群聊消息同步           | 主人  |
+| `/ts 关闭同步 <服务器名称>`       | 关闭指定服务器的群聊消息同步           | 主人  |
+| `/ts 重连`                  | 断开并重新建立所有服务器的 WebSocket 连接 | 主人  |
+
+## 鸣谢
+
+- [TianSuo](https://github.com/17TheWord/QueQiao)：Terraria WebSocket 桥
+- [TShock](https://github.com/TShock/TShock) 与 [Pryaxis](https://github.com/Pryaxis)：Terraria 服务端框架与插件 API
+- [Re-Logic](https://www.terraria.org/)：Terraria

package/config.md

@@ -0,0 +1,87 @@
+---
+title: Terraria 插件配置
+description: 配置 Terraria 服务器连接、消息同步与 RCON 命令白名单
+fields:
+  - key: base.say_way
+    label: 聊天前缀
+    type: text
+    description: QQ 消息转发到 Terraria 时显示的前缀，默认 "说："
+    placeholder: 说：
+
+  - key: base.display_server_name
+    label: 显示服务器名称
+    type: switch
+    description: 消息中是否显示服务器名称
+
+  - key: base.servers
+    label: 服务器列表
+    type: array
+    description: 配置多个 Terraria 服务器连接（TianSuo 协议）
+    itemFields:
+      - key: server_name
+        label: 服务器名称
+        type: text
+        description: 与 TianSuo 配置中 ServerName 一致（也是握手时 x-self-name 头的值）
+        placeholder: main
+
+      - key: host
+        label: 服务器地址
+        type: text
+        description: TianSuo 所在主机地址
+        placeholder: 127.0.0.1
+
+      - key: port
+        label: 服务器端口
+        type: number
+        description: TianSuo WebSocket 监听端口
+        placeholder: 8080
+
+      - key: access_token
+        label: 访问令牌
+        type: secret
+        description: 与 TianSuo 配置中 AccessToken 一致（若 TianSuo 启用则必填）
+
+      - key: reconnect_max_attempts
+        label: 最大重连次数
+        type: number
+        description: 断线后最大重连次数，0 表示无限
+        placeholder: 0
+
+      - 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: textarea
+        description: 允许执行 RCON 命令的 QQ 号列表，每行一个
+
+      - key: rcon_command_whitelist
+        label: RCON 命令白名单
+        type: textarea
+        description: 允许执行的 RCON 命令列表（首词匹配），每行一条
+
+      - key: sync_enabled
+        label: 启用同步
+        type: switch
+        description: 是否启用消息同步
+---
+
+```mioku-fields
+keys:
+  - base.say_way
+  - base.display_server_name
+  - base.servers
+```

package/core/command.ts

@@ -0,0 +1,63 @@
+import type { TerrariaServerConfig } from "../types";
+
+export function parseCommand(
+  text: string,
+  serverItem: TerrariaServerConfig,
+): 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: TerrariaServerConfig,
+  isMaster: boolean,
+  userId: number | string | undefined,
+): boolean {
+  if (isMaster) return true;
+
+  const cmdName = getCommandName(text);
+  const whitelist = serverItem.rcon_command_whitelist || [];
+  if (
+    whitelist.some((w) => String(w).replace(/^\/+/, "") === cmdName)
+  ) {
+    return true;
+  }
+
+  const userList = serverItem.command_user || [];
+  if (userId === undefined) return false;
+  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: TerrariaCommandResult): string {
+  if (raw === null || raw === undefined) return "命令执行成功";
+
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    return trimmed || "命令执行成功";
+  }
+
+  if (typeof raw !== "object") return String(raw);
+
+  const success = Boolean(raw.success);
+  const message = String(raw.message ?? "").trim();
+
+  if (!success) {
+    return message || "命令执行失败";
+  }
+  return message || "命令执行成功";
+}
+
+export type TerrariaCommandResult =
+  | { success: boolean; message?: string }
+  | string
+  | null
+  | undefined;

package/core/ws-client.ts

@@ -0,0 +1,210 @@
+import WebSocket from "ws";
+import { PROTOCOL, type TerrariaServerConfig } from "../types";
+
+export type ClientStatus = "connected" | "disconnected" | "connecting";
+
+export interface TerrariaApiResponse {
+  success: boolean;
+  message?: string;
+}
+
+export interface WsClient {
+  serverName: string;
+  getStatus(): ClientStatus;
+  request(
+    name: string,
+    data: Record<string, unknown>,
+  ): Promise<TerrariaApiResponse>;
+  close(): void;
+}
+
+type EventHandler = (raw: {
+  name: string;
+  data: Record<string, unknown>;
+}) => void;
+type StatusHandler = (serverName: string, status: ClientStatus) => void;
+type ErrorHandler = (serverName: string, error: Error) => void;
+
+interface PendingRequest {
+  name: string;
+  resolve: (value: TerrariaApiResponse) => void;
+  reject: (err: Error) => void;
+}
+
+export function createForwardClient(
+  serverItem: TerrariaServerConfig,
+  onEvent: EventHandler,
+  onStatusChange: StatusHandler,
+  onError?: ErrorHandler,
+): WsClient {
+  let socket: WebSocket | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let reconnectAttempt = 0;
+  let closed = false;
+  let currentStatus: ClientStatus = "disconnected";
+  const pendingQueue: PendingRequest[] = [];
+
+  const updateStatus = (status: ClientStatus) => {
+    currentStatus = status;
+    onStatusChange(serverItem.server_name, status);
+  };
+
+  const flushQueueWithError = (err: Error) => {
+    while (pendingQueue.length > 0) {
+      const pending = pendingQueue.shift()!;
+      pending.reject(err);
+    }
+  };
+
+  const connect = () => {
+    if (closed) return;
+    if (socket) {
+      try {
+        socket.close();
+      } catch {}
+      socket = null;
+    }
+    updateStatus("connecting");
+
+    const url = buildUrl(serverItem.host, serverItem.port);
+    const headers: Record<string, string> = {
+      "x-self-name": serverItem.server_name,
+    };
+    const token = (serverItem.access_token || "").trim();
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+
+    try {
+      socket = new WebSocket(url, { headers });
+    } catch (err) {
+      onError?.(serverItem.server_name, err as Error);
+      updateStatus("disconnected");
+      scheduleReconnect();
+      return;
+    }
+
+    socket.on("open", () => {
+      reconnectAttempt = 0;
+      updateStatus("connected");
+    });
+
+    socket.on("close", () => {
+      if (currentStatus !== "disconnected") {
+        updateStatus("disconnected");
+      }
+      flushQueueWithError(new Error(`服务器 ${serverItem.server_name} 连接已断开`));
+      scheduleReconnect();
+    });
+
+    socket.on("error", (err: Error) => {
+      onError?.(serverItem.server_name, err);
+    });
+
+    socket.on("message", (data: WebSocket.RawData) => {
+      const text = data.toString();
+      let parsed: { type?: string; name?: string; data?: unknown };
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        return;
+      }
+      handleEnvelope(parsed);
+    });
+  };
+
+  const handleEnvelope = (env: {
+    type?: string;
+    name?: string;
+    data?: unknown;
+  }) => {
+    if (!env.type || !env.name) return;
+
+    if (env.type === PROTOCOL.EVENT_TYPE) {
+      onEvent({
+        name: env.name,
+        data: (env.data ?? {}) as Record<string, unknown>,
+      });
+      return;
+    }
+
+    if (env.type === PROTOCOL.API_TYPE && env.name === PROTOCOL.API_RESPONSE) {
+      const pending = pendingQueue.shift();
+      if (!pending) return;
+      const result = (env.data ?? {}) as TerrariaApiResponse;
+      pending.resolve({
+        success: Boolean(result.success),
+        message: result.message,
+      });
+    }
+  };
+
+  const scheduleReconnect = () => {
+    if (closed) return;
+    if (reconnectTimer) return;
+    const maxAttempts = serverItem.reconnect_max_attempts ?? 0;
+    reconnectAttempt += 1;
+    if (maxAttempts > 0 && reconnectAttempt > maxAttempts) {
+      return;
+    }
+    const baseDelay = 10_000;
+    const delay = Math.min(baseDelay * reconnectAttempt, 60_000);
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, delay);
+  };
+
+  const request = (
+    name: string,
+    data: Record<string, unknown>,
+  ): Promise<TerrariaApiResponse> => {
+    return new Promise<TerrariaApiResponse>((resolve, reject) => {
+      if (!socket || socket.readyState !== WebSocket.OPEN) {
+        reject(new Error(`服务器 ${serverItem.server_name} 未连接`));
+        return;
+      }
+      const envelope = JSON.stringify({
+        type: PROTOCOL.API_TYPE,
+        name,
+        data,
+      });
+      try {
+        socket.send(envelope);
+      } catch (err) {
+        reject(err as Error);
+        return;
+      }
+      pendingQueue.push({ name, resolve, reject });
+    });
+  };
+
+  const close = () => {
+    closed = true;
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (socket) {
+      try {
+        socket.close();
+      } catch {}
+      socket = null;
+    }
+    flushQueueWithError(new Error(`服务器 ${serverItem.server_name} 已关闭`));
+    updateStatus("disconnected");
+  };
+
+  connect();
+
+  return {
+    serverName: serverItem.server_name,
+    getStatus: () => currentStatus,
+    request,
+    close,
+  };
+}
+
+function buildUrl(host: string, port: number): string {
+  return `ws://${host}:${port}/`;
+}

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>,
+): Promise<void> {
+  serverManager.reconnectAll();
+  return reply("已发起重新连接请求");
+}

package/handlers/status.ts

@@ -0,0 +1,34 @@
+import type { ServerManager } from "../utils/server-manager";
+import type { TerrariaConfig } from "../types";
+
+export async function handleStatus(
+  serverManager: ServerManager,
+  config: TerrariaConfig,
+  reply: (text: string) => Promise<void>,
+): Promise<void> {
+  if (config.servers.length === 0) {
+    await reply("暂无已配置的服务器");
+    return;
+  }
+
+  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 =
+      statusObj?.status === "connected"
+        ? "已连接"
+        : statusObj?.status === "connecting"
+          ? "连接中"
+          : "未连接";
+
+    lines.push(`服务器：${server.server_name}`);
+    lines.push(`WebSocket 状态：${wsStatus}`);
+    lines.push(`地址：${server.host}:${server.port}`);
+  });
+
+  await reply(lines.join("\n"));
+}

package/handlers/sync.ts

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

package/index.ts

@@ -0,0 +1,221 @@
+import { definePlugin, getService, Services, type MiokiContext } from "mioku";
+import { handleStatus } from "./handlers/status";
+import { handleSync } from "./handlers/sync";
+import { handleReconnect } from "./handlers/reconnect";
+import { parseTsCommand } from "./utils/command-router";
+import { createConfigHandler } from "./utils/config-handler";
+import {
+  formatQqToTerraria,
+  formatTerrariaEvent,
+  type QqMessagePart,
+} from "./utils/message-formatter";
+import { createServerManager } from "./utils/server-manager";
+import {
+  formatCommandResult,
+  isCommandAllowed,
+  parseCommand,
+} from "./core/command";
+import { PROTOCOL, type TerrariaConfig, type TerrariaEvent } from "./types";
+
+export default definePlugin({
+  name: "terraria",
+  version: "1.0.0",
+  description: "Terraria 服务器与 QQ 群消息互通插件，基于 TianSuo 协议",
+
+  async setup(ctx: MiokiContext) {
+    const configService = getService(ctx, Services.Config);
+
+    const configHandler = createConfigHandler(configService);
+    await configHandler.register();
+    const config = configHandler.getConfig();
+
+    const serverManager = createServerManager({
+      onStatusChange: (serverName, status) => {
+        ctx.logger.info(`[Terraria] 服务器 ${serverName} 状态: ${status}`);
+      },
+      onEvent: (raw) => {
+        handleTerrariaEvent(ctx, raw, config, configHandler);
+      },
+      logger: { error: (msg) => ctx.logger.error(msg) },
+    });
+
+    serverManager.startServers(config);
+    ctx.logger.info("Terraria 插件已就绪");
+
+    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;
+
+      const parsed = parseTsCommand(text);
+      if (parsed) {
+        if (!groupId) return;
+
+        switch (parsed.action) {
+          case "状态": {
+            await handleStatus(serverManager, config, async (msg) => {
+              await event.reply(msg);
+            });
+            return;
+          }
+          case "开启同步": {
+            const serverName = parsed.args[0];
+            await handleSync(
+              serverName,
+              true,
+              configHandler,
+              config,
+              async (msg) => {
+                await event.reply(msg);
+              },
+            );
+            return;
+          }
+          case "关闭同步": {
+            const serverName = parsed.args[0];
+            await handleSync(
+              serverName,
+              false,
+              configHandler,
+              config,
+              async (msg) => {
+                await event.reply(msg);
+              },
+            );
+            return;
+          }
+          case "重连": {
+            if (ctx.isOwner?.(event)) {
+              await handleReconnect(serverManager, async (msg) => {
+                await event.reply(msg);
+              });
+            }
+            return;
+          }
+          case "":
+            return;
+        }
+        return;
+      }
+
+      if (!groupId) return;
+      await forwardToTerraria(ctx, event, config, configHandler, serverManager);
+    });
+
+    return async () => {
+      serverManager.stopServers();
+      ctx.logger.info("Terraria 插件已卸载");
+    };
+  },
+});
+
+async function handleTerrariaEvent(
+  ctx: MiokiContext,
+  raw: { serverName: string; name: string; data: Record<string, unknown> },
+  config: TerrariaConfig,
+  configHandler: ReturnType<typeof createConfigHandler>,
+): Promise<void> {
+  const eventName = raw.name as TerrariaEvent["name"];
+  if (
+    eventName !== PROTOCOL.PLAYER_JOIN &&
+    eventName !== PROTOCOL.PLAYER_QUIT &&
+    eventName !== PROTOCOL.PLAYER_CHAT &&
+    eventName !== PROTOCOL.PLAYER_DEATH
+  ) {
+    return;
+  }
+
+  const data = raw.data ?? {};
+  const event: TerrariaEvent = {
+    server_name: raw.serverName,
+    name: eventName,
+    player: (data.player as TerrariaEvent["player"]) || undefined,
+    message: typeof data.message === "string" ? data.message : undefined,
+    death_message:
+      typeof data.death_message === "string"
+        ? data.death_message
+        : typeof data.deathMessage === "string"
+          ? data.deathMessage
+          : undefined,
+  };
+
+  const messageText = formatTerrariaEvent(event, config);
+  if (!messageText) return;
+
+  const serverItem = configHandler.findServerByName(raw.serverName);
+  if (!serverItem) return;
+  if (serverItem.sync_enabled === false) return;
+
+  const bots = serverItem.bot_self_id ? [serverItem.bot_self_id] : [];
+  const groups = serverItem.group_list ? [serverItem.group_list] : [];
+
+  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(
+          `[Terraria] 发送消息到群 ${groupId} 失败: ${err}`,
+        );
+      }
+    }
+  }
+}
+
+async function forwardToTerraria(
+  ctx: MiokiContext,
+  event: any,
+  config: TerrariaConfig,
+  configHandler: ReturnType<typeof createConfigHandler>,
+  serverManager: ReturnType<typeof createServerManager>,
+): Promise<void> {
+  const text = ctx.text(event);
+  ctx.logger.debug(
+    `[Terraria] 收到群消息 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: QqMessagePart[] = Array.isArray(event.message)
+    ? event.message
+    : [{ type: "text", text }];
+
+  for (const server of servers) {
+    if (server.sync_enabled === false) continue;
+
+    const commandText = parseCommand(text, server);
+    if (commandText !== null) {
+      const isAllowed = isCommandAllowed(
+        commandText,
+        server,
+        ctx.isOwner?.(event) ?? false,
+        event.user_id,
+      );
+      if (!isAllowed) continue;
+
+      try {
+        const result = await serverManager.rcon(server.server_name, commandText);
+        await event.reply(formatCommandResult(result));
+      } catch (err) {
+        await event.reply(`执行命令失败: ${err}`);
+      }
+      continue;
+    }
+
+    try {
+      const message = formatQqToTerraria(event.sender || {}, msgList);
+      await serverManager.broadcast(server.server_name, message);
+    } catch (err) {
+      ctx.logger.error(
+        `[Terraria] 发送到服务器 ${server.server_name} 失败: ${err}`,
+      );
+    }
+  }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "mioku-plugin-terraria",
+  "version": "1.0.0",
+  "description": "Terraria 服务器与 QQ 群消息互通插件，基于 TianSuo 协议",
+  "main": "index.ts",
+  "type": "module",
+  "keywords": [
+    "mioku",
+    "terraria",
+    "tshock",
+    "tiansuo"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mioku-lab/mioku-plugin-terraria.git"
+  },
+  "mioku": {
+    "services": ["config"],
+    "accessHooks": [
+      {
+        "id": "/ts 状态",
+        "match": "/^\\/ts\\s*状态/"
+      },
+      {
+        "id": "/ts 开启同步",
+        "match": "/^\\/ts\\s*开启同步/"
+      },
+      {
+        "id": "/ts 关闭同步",
+        "match": "/^\\/ts\\s*关闭同步/"
+      },
+      {
+        "id": "/ts 重连",
+        "match": "/^\\/ts\\s*重连/"
+      }
+    ],
+    "help": {
+      "title": "Terraria",
+      "description": "Terraria 服务器与 QQ 群消息互通插件，基于 TianSuo 协议",
+      "commands": [
+        {
+          "cmd": "/ts 状态",
+          "desc": "查看所有已配置服务器的 WebSocket 连接状态",
+          "role": "master"
+        },
+        {
+          "cmd": "/ts 开启同步 <服务器名称>",
+          "desc": "开启指定服务器的群聊消息同步功能",
+          "usage": "/ts 开启同步 <服务器名称>",
+          "role": "master"
+        },
+        {
+          "cmd": "/ts 关闭同步 <服务器名称>",
+          "desc": "关闭指定服务器的群聊消息同步功能",
+          "usage": "/ts 关闭同步 <服务器名称>",
+          "role": "master"
+        },
+        {
+          "cmd": "/ts 重连",
+          "desc": "断开并重新建立所有服务器的 WebSocket 连接",
+          "role": "master"
+        }
+      ]
+    }
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "mioku": "^0.8.0",
+    "mioki": "^0.16.0"
+  },
+  "devDependencies": {
+    "mioku": "workspace:*",
+    "mioki": "^0.16.0",
+    "@types/ws": "^8.5.13"
+  }
+}

package/types.ts

@@ -0,0 +1,107 @@
+export const PROTOCOL = {
+  EVENT_TYPE: "event",
+  API_TYPE: "api",
+  API_RESPONSE: "api_response",
+
+  PLAYER_JOIN: "player_join",
+  PLAYER_QUIT: "player_quit",
+  PLAYER_CHAT: "player_chat",
+  PLAYER_DEATH: "player_death",
+
+  BROADCAST: "broadcast",
+  PRIVATE_MESSAGE: "private_message",
+  RCON_COMMAND: "rcon_command",
+} as const;
+
+export type ProtocolName = (typeof PROTOCOL)[keyof typeof PROTOCOL];
+
+export type TerrariaEventName =
+  | typeof PROTOCOL.PLAYER_JOIN
+  | typeof PROTOCOL.PLAYER_QUIT
+  | typeof PROTOCOL.PLAYER_CHAT
+  | typeof PROTOCOL.PLAYER_DEATH;
+
+export interface PlayerView {
+  name?: string;
+  index?: number;
+  group?: string;
+  account?: string;
+  uuid?: string;
+  ip?: string;
+}
+
+export interface TerrariaEvent {
+  server_name: string;
+  name: TerrariaEventName;
+  player?: PlayerView;
+  message?: string;
+  death_message?: string;
+}
+
+export interface TerrariaServerConfig {
+  server_name: string;
+  host: string;
+  port: number;
+  access_token?: string;
+  reconnect_max_attempts?: number;
+  group_list: string;
+  bot_self_id: string;
+  command_header?: string;
+  command_user?: string[];
+  rcon_command_whitelist?: string[];
+  sync_enabled?: boolean;
+}
+
+export interface TerrariaConfig {
+  servers: TerrariaServerConfig[];
+  say_way: string;
+  display_server_name: boolean;
+}
+
+export const DEFAULT_CONFIG: TerrariaConfig = {
+  servers: [],
+  say_way: "说：",
+  display_server_name: true,
+};
+
+export function normalizeConfig(raw: Partial<TerrariaConfig>): TerrariaConfig {
+  const servers = Array.isArray(raw.servers) ? raw.servers : [];
+  return {
+    servers: servers.map((s) => ({
+      ...s,
+      server_name: String(s.server_name ?? "").trim(),
+      host:
+        typeof s.host === "string" && s.host.trim()
+          ? s.host.trim()
+          : "127.0.0.1",
+      port: typeof s.port === "number" && s.port > 0 ? s.port : 8080,
+      access_token:
+        typeof s.access_token === "string" ? s.access_token.trim() : "",
+      reconnect_max_attempts:
+        typeof s.reconnect_max_attempts === "number"
+          ? s.reconnect_max_attempts
+          : 0,
+      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() : "",
+      command_header:
+        typeof s.command_header === "string" && s.command_header
+          ? s.command_header
+          : "$",
+      command_user: Array.isArray(s.command_user)
+        ? s.command_user.map((u) => String(u))
+        : [],
+      rcon_command_whitelist: Array.isArray(s.rcon_command_whitelist)
+        ? s.rcon_command_whitelist.map((c) => String(c))
+        : [],
+      sync_enabled:
+        typeof s.sync_enabled === "boolean" ? s.sync_enabled : true,
+    })),
+    say_way: raw.say_way || DEFAULT_CONFIG.say_way,
+    display_server_name:
+      typeof raw.display_server_name === "boolean"
+        ? raw.display_server_name
+        : DEFAULT_CONFIG.display_server_name,
+  };
+}

package/utils/command-router.ts

@@ -0,0 +1,21 @@
+export interface ParsedCommand {
+  action: string;
+  args: string[];
+  raw: string;
+}
+
+export function parseTsCommand(text: string): ParsedCommand | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/ts")) return null;
+
+  const remainder = trimmed.slice(3).trim();
+  if (!remainder) {
+    return { action: "", args: [], raw: "" };
+  }
+
+  const parts = remainder.split(/\s+/);
+  const action = parts[0] || "";
+  const args = parts.slice(1);
+
+  return { action, args, raw: remainder };
+}

package/utils/config-handler.ts

@@ -0,0 +1,64 @@
+import type { ConfigService } from "mioku";
+import {
+  DEFAULT_CONFIG,
+  normalizeConfig,
+  type TerrariaConfig,
+  type TerrariaServerConfig,
+} from "../types";
+
+export function createConfigHandler(configService: ConfigService | undefined) {
+  let currentConfig: TerrariaConfig = { ...DEFAULT_CONFIG };
+
+  const register = async () => {
+    if (!configService) return;
+    await configService.registerConfig("terraria", "base", DEFAULT_CONFIG);
+    const raw = await configService.getConfig("terraria", "base");
+    currentConfig = normalizeConfig(raw);
+    configService.onConfigChange("terraria", "base", (next) => {
+      currentConfig = normalizeConfig(next);
+    });
+  };
+
+  const getConfig = (): TerrariaConfig => currentConfig;
+
+  const updateServerSync = async (
+    serverName: string,
+    enabled: boolean,
+  ): Promise<boolean> => {
+    if (!configService) return false;
+    const exists = currentConfig.servers.some(
+      (s) => s.server_name === serverName,
+    );
+    if (!exists) return false;
+    const servers = currentConfig.servers.map((s) =>
+      s.server_name === serverName ? { ...s, sync_enabled: enabled } : s,
+    );
+    await configService.updateConfig("terraria", "base", { servers });
+    return true;
+  };
+
+  const findServerByName = (
+    serverName: string,
+  ): TerrariaServerConfig | null => {
+    return (
+      currentConfig.servers.find((s) => s.server_name === serverName) || null
+    );
+  };
+
+  const getServersForGroup = (
+    groupId: string | number,
+  ): TerrariaServerConfig[] => {
+    const gid = String(groupId);
+    return currentConfig.servers.filter((s) => s.group_list === gid);
+  };
+
+  return {
+    register,
+    getConfig,
+    updateServerSync,
+    findServerByName,
+    getServersForGroup,
+  };
+}
+
+export type ConfigHandler = ReturnType<typeof createConfigHandler>;

package/utils/message-formatter.ts

@@ -0,0 +1,75 @@
+import { PROTOCOL, type TerrariaConfig, type TerrariaEvent } from "../types";
+
+export function formatTerrariaEvent(
+  event: TerrariaEvent,
+  config: TerrariaConfig,
+): string | null {
+  const sayWord = config.say_way || "说：";
+  const playerName = event.player?.name || "未知玩家";
+  let body: string | null = null;
+
+  switch (event.name) {
+    case PROTOCOL.PLAYER_JOIN:
+      body = `${playerName} 加入了游戏`;
+      break;
+    case PROTOCOL.PLAYER_QUIT:
+      body = `${playerName} 退出了游戏`;
+      break;
+    case PROTOCOL.PLAYER_CHAT: {
+      const content = (event.message ?? "").trim();
+      if (content) body = `${playerName} ${sayWord} ${content}`;
+      break;
+    }
+    case PROTOCOL.PLAYER_DEATH: {
+      const text = (event.death_message ?? "").trim();
+      body = text ? `${playerName} ${text}` : `${playerName} 倒下了`;
+      break;
+    }
+  }
+
+  if (!body) return null;
+  if (!config.display_server_name) return body;
+  const name = event.server_name || "未知服务器";
+  return `[${name}] ${body}`;
+}
+
+export interface QqMessagePart {
+  type: string;
+  text?: string;
+  url?: string;
+}
+
+export interface QqSender {
+  nickname?: string;
+  card?: string;
+  user_id?: number | string;
+}
+
+export function formatQqToTerraria(
+  sender: QqSender,
+  messageArr: QqMessagePart[],
+): string {
+  const sayWord = "说：";
+  const nick =
+    sender.nickname || sender.card || String(sender.user_id ?? "未知用户");
+
+  const parts: string[] = [];
+  for (const msg of messageArr) {
+    if (msg.type === "text") {
+      parts.push(String(msg.text ?? ""));
+    } else if (msg.type === "image") {
+      parts.push("[图片]");
+    } else if (msg.type === "face") {
+      parts.push("[表情]");
+    } else if (msg.type === "at") {
+      parts.push(`@${String(msg.text ?? "").trim()}`);
+    } else if (msg.type === "reply") {
+      parts.push("");
+    } else {
+      parts.push(`[${msg.type}]`);
+    }
+  }
+
+  const content = parts.join("").trim();
+  return `${nick} ${sayWord} ${content}`.trim();
+}

package/utils/server-manager.ts

@@ -0,0 +1,124 @@
+import {
+  createForwardClient,
+  type ClientStatus,
+  type WsClient,
+} from "../core/ws-client";
+import { PROTOCOL, type TerrariaConfig } from "../types";
+
+export type StatusCallback = (serverName: string, status: ClientStatus) => void;
+export type EventCallback = (raw: {
+  serverName: string;
+  name: string;
+  data: Record<string, unknown>;
+}) => void;
+
+export interface ServerManagerOptions {
+  onStatusChange: StatusCallback;
+  onEvent: EventCallback;
+  logger?: { error: (msg: string) => void };
+}
+
+export function createServerManager(options: ServerManagerOptions) {
+  const clients = new Map<string, WsClient>();
+  let currentConfig: TerrariaConfig | null = null;
+
+  const handleEvent = (serverName: string) =>
+    (raw: { name: string; data: Record<string, unknown> }) => {
+      options.onEvent({
+        serverName,
+        name: raw.name,
+        data: raw.data,
+      });
+    };
+
+  const handleError = (serverName: string, error: Error) => {
+    options.logger?.error(
+      `[Terraria] 服务器 ${serverName} 连接错误: ${error.message}`,
+    );
+  };
+
+  const stopClients = () => {
+    clients.forEach((client) => client.close());
+    clients.clear();
+  };
+
+  const startServers = (config: TerrariaConfig) => {
+    stopClients();
+    currentConfig = config;
+
+    for (const server of config.servers) {
+      if (!server.server_name) continue;
+      if (server.sync_enabled === false) continue;
+
+      const client = createForwardClient(
+        server,
+        handleEvent(server.server_name),
+        options.onStatusChange,
+        handleError,
+      );
+      clients.set(server.server_name, client);
+    }
+  };
+
+  const stopServers = () => {
+    stopClients();
+    currentConfig = null;
+  };
+
+  const reconnectAll = () => {
+    if (!currentConfig) return;
+    const config = currentConfig;
+    startServers(config);
+  };
+
+  const isServerConnected = (serverName: string) => {
+    return clients.get(serverName)?.getStatus() === "connected";
+  };
+
+  const sendToServer = (
+    serverName: string,
+    apiName: string,
+    data: Record<string, unknown>,
+  ) => {
+    const client = clients.get(serverName);
+    if (!client) {
+      throw new Error(`服务器 ${serverName} 未配置`);
+    }
+    return client.request(apiName, data);
+  };
+
+  const broadcast = (serverName: string, message: string) =>
+    sendToServer(serverName, PROTOCOL.BROADCAST, { message });
+
+  const privateMessage = (
+    serverName: string,
+    target: string,
+    message: string,
+  ) =>
+    sendToServer(serverName, PROTOCOL.PRIVATE_MESSAGE, { target, message });
+
+  const rcon = (serverName: string, command: string) =>
+    sendToServer(serverName, PROTOCOL.RCON_COMMAND, { command });
+
+  const getStatusList = () => {
+    const list: Array<{ name: string; status: ClientStatus }> = [];
+    clients.forEach((client, name) => {
+      list.push({ name, status: client.getStatus() });
+    });
+    return list;
+  };
+
+  return {
+    startServers,
+    stopServers,
+    reconnectAll,
+    isServerConnected,
+    sendToServer,
+    broadcast,
+    privateMessage,
+    rcon,
+    getStatusList,
+  };
+}
+
+export type ServerManager = ReturnType<typeof createServerManager>;