koishi-plugin-minecraft-adapter 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,9 @@
 # koishi-plugin-minecraft-adapter
 
-Koishi 的 Minecraft 适配器：支持 RCON 与鹊桥(Queqiao) Webhook。
+Koishi 的 Minecraft 适配器：支持 RCON、鹊桥(Queqiao) Webhook 与 WebSocket。
 
 - RCON：连接并发送命令/广播
-- Webhook：接收聊天、加入、离开等事件并在 Koishi 中触发
+- Webhook/WS：接收聊天、加入、离开等事件并在 Koishi 中触发
 
 参考实现：
 - https://github.com/17TheWord/nonebot-adapter-minecraft
@@ -19,6 +19,25 @@ npm i koishi-plugin-minecraft-adapter
 
 - RCON：host/port/password/timeout/reconnectInterval/reconnectStrategy/maxReconnectInterval/broadcastMode
 - Webhook：enabled/path/secret/verifyMode/signatureHeader/secretHeader
+- WebSocket（对齐鹊桥官方）
+  - enabled: 是否启用
+  - url: WS 地址，例如 `ws://127.0.0.1:8080`
+  - serverName: 必填，需与鹊桥 `config.yml` 的 `server_name` 完全一致
+  - accessToken: 可选，对应鹊桥 `config.yml` 的 `access_token`
+  - extraHeaders: 可选，附加自定义请求头
+  - reconnectStrategy: `fixed | exponential`
+  - reconnectInterval / maxReconnectInterval: 断线重连间隔
+
+握手头部：
+
+```
+x-self-name: <serverName>
+Authorization: Bearer <accessToken>   // 若 accessToken 不为空
+```
+
+鹊桥项目参考：
+
+- QueQiao: https://github.com/17TheWord/QueQiao
 
 ## 用法
 

package/lib/index.d.ts

@@ -20,6 +20,9 @@ declare class MinecraftService extends Service implements MinecraftServiceAPI {
     private currentReconnectInterval?;
     private commandQueue;
     private isProcessingQueue;
+    private ws?;
+    private wsReconnectTimer?;
+    private wsCurrentInterval?;
     constructor(ctx: Context, config: MinecraftService.Config);
     private registerWebhook;
     start(): void;
@@ -28,6 +31,10 @@ declare class MinecraftService extends Service implements MinecraftServiceAPI {
     private scheduleReconnect;
     private ensureConnected;
     private disconnect;
+    private connectWs;
+    private disconnectWs;
+    private ensureWsConnected;
+    private scheduleWsReconnect;
     execute(command: string): Promise<string>;
     broadcast(message: string): Promise<string>;
     sendTo(player: string, message: string): Promise<string>;
@@ -54,9 +61,20 @@ declare namespace MinecraftService {
         signatureHeader?: string;
         secretHeader?: string;
     }
+    interface WebSocketConfig {
+        enabled: boolean;
+        url: string;
+        serverName: string;
+        accessToken?: string;
+        extraHeaders?: Record<string, string>;
+        reconnectInterval?: number;
+        reconnectStrategy?: 'fixed' | 'exponential';
+        maxReconnectInterval?: number;
+    }
     interface Config {
         rcon?: RconConfig;
         webhook?: WebhookConfig;
+        websocket?: WebSocketConfig;
     }
     const Config: Schema<Config>;
 }

package/lib/index.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const koishi_1 = require("koishi");
 const rcon_client_1 = require("rcon-client");
+const ws_1 = __importDefault(require("ws"));
 const logger = new koishi_1.Logger('minecraft');
 class MinecraftService extends koishi_1.Service {
     ctx;
@@ -16,6 +20,10 @@ class MinecraftService extends koishi_1.Service {
     currentReconnectInterval;
     commandQueue = [];
     isProcessingQueue = false;
+    // WebSocket
+    ws;
+    wsReconnectTimer;
+    wsCurrentInterval;
     constructor(ctx, config) {
         super(ctx, 'minecraft', true);
         this.ctx = ctx;
@@ -73,6 +81,9 @@ class MinecraftService extends koishi_1.Service {
         if (this.config.rcon?.enabled) {
             this.ensureConnected();
         }
+        if (this.config.websocket?.enabled) {
+            this.ensureWsConnected();
+        }
     }
     stop() {
         if (this.reconnectTimer) {
@@ -80,6 +91,11 @@ class MinecraftService extends koishi_1.Service {
             this.reconnectTimer = undefined;
         }
         this.disconnect();
+        if (this.wsReconnectTimer) {
+            clearTimeout(this.wsReconnectTimer);
+            this.wsReconnectTimer = undefined;
+        }
+        this.disconnectWs();
     }
     async connectRcon() {
         if (this.isConnecting || this.rcon)
@@ -138,6 +154,72 @@ class MinecraftService extends koishi_1.Service {
             this.rcon = undefined;
         }
     }
+    connectWs() {
+        if (this.ws)
+            return;
+        const { url, serverName, accessToken, extraHeaders } = this.config.websocket;
+        logger.info('WS 连接中: ' + url);
+        const headers = { 'x-self-name': serverName, ...(extraHeaders || {}) };
+        if (accessToken)
+            headers['Authorization'] = `Bearer ${accessToken}`;
+        const ws = new ws_1.default(url, { headers });
+        this.ws = ws;
+        ws.on('open', () => {
+            logger.info('WS 连接成功');
+        });
+        ws.on('message', (data) => {
+            try {
+                const text = data.toString('utf8');
+                const obj = JSON.parse(text);
+                const type = obj.type || obj.event || 'unknown';
+                const payload = obj.data ?? obj;
+                const mapped = mapQueqiaoEvent(type, payload);
+                this.ctx.emit(`minecraft/${mapped.type}`, mapped.payload);
+            }
+            catch (e) {
+                logger.warn('WS 消息解析失败: ' + e?.message);
+            }
+        });
+        ws.on('close', () => {
+            logger.warn('WS 连接断开');
+            this.ws = undefined;
+            this.scheduleWsReconnect();
+        });
+        ws.on('error', (err) => {
+            logger.warn('WS 错误: ' + err?.message);
+        });
+    }
+    disconnectWs() {
+        if (this.ws) {
+            try {
+                this.ws.terminate();
+            }
+            catch { }
+            this.ws = undefined;
+        }
+    }
+    ensureWsConnected() {
+        if (this.ws)
+            return;
+        this.connectWs();
+    }
+    scheduleWsReconnect() {
+        const base = this.config.websocket?.reconnectInterval ?? 5000;
+        const strategy = this.config.websocket?.reconnectStrategy ?? 'fixed';
+        const maxInterval = this.config.websocket?.maxReconnectInterval ?? 60000;
+        if (this.wsCurrentInterval == null)
+            this.wsCurrentInterval = base;
+        const interval = strategy === 'exponential' ? Math.min(this.wsCurrentInterval * 2, maxInterval) : base;
+        if (!this.config.websocket?.enabled)
+            return;
+        if (this.wsReconnectTimer)
+            return;
+        this.wsReconnectTimer = setTimeout(() => {
+            this.wsReconnectTimer = undefined;
+            this.wsCurrentInterval = interval;
+            this.ensureWsConnected();
+        }, interval);
+    }
     async execute(command) {
         if (!this.config.rcon?.enabled)
             throw new Error('RCON 未启用');
@@ -233,6 +315,25 @@ function escapeForMc(text) {
             signatureHeader: 'x-queqiao-signature',
             secretHeader: 'x-queqiao-secret',
         }),
+        websocket: koishi_1.Schema.object({
+            enabled: koishi_1.Schema.boolean().description('启用鹊桥 WebSocket').default(false),
+            url: koishi_1.Schema.string().description('WebSocket 地址，如 ws://host:port').required(),
+            serverName: koishi_1.Schema.string().description('服务器名称，需与鹊桥 config.yml 的 server_name 一致').required(),
+            accessToken: koishi_1.Schema.string().role('secret').description('访问令牌，对应鹊桥 config.yml 的 access_token，可为空'),
+            extraHeaders: koishi_1.Schema.dict(String).description('附加请求头，可选'),
+            reconnectInterval: koishi_1.Schema.number().description('断线重连基础间隔(ms)').default(5000),
+            reconnectStrategy: koishi_1.Schema.union(['fixed', 'exponential']).description('重连策略').default('fixed'),
+            maxReconnectInterval: koishi_1.Schema.number().description('最大重连间隔(ms)').default(60000),
+        }).description('WebSocket 设置').default({
+            enabled: false,
+            url: '',
+            serverName: 'Server-1',
+            accessToken: '',
+            extraHeaders: {},
+            reconnectInterval: 5000,
+            reconnectStrategy: 'fixed',
+            maxReconnectInterval: 60000,
+        }),
     });
 })(MinecraftService || (MinecraftService = {}));
 exports.default = MinecraftService;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-minecraft-adapter",
   "description": "Minecraft RCON & webhook integration for Koishi",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [
@@ -22,7 +22,8 @@
     "koishi": "^4.17.9"
   },
   "dependencies": {
-    "rcon-client": "^4.2.5"
+    "rcon-client": "^4.2.5",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0"