koishi-plugin-minecraft-adapter 0.1.0 → 0.4.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
 
 ## 用法
 
@@ -32,4 +51,18 @@ ctx.on('minecraft/chat', (p) => {
 })
 ```
 
+### ChatLuna（AI）联动
+
+启用后可直接在 Koishi 中使用以下命令，便于 ChatLuna 的“指令模型/函数调用/意图解析”触发：
+
+- `mc.exec <command>`：通过 RCON 执行任意指令
+- `mc.say <message>`：向全服广播（优先走 WS，失败回退 RCON）
+- `mc.tell <player> <message>`：向指定玩家发送消息（优先 WS，失败回退 RCON）
+- `mc.title <player> <title> [subtitle]`：标题/子标题（WS 或 RCON 回退）
+- `mc.actionbar <player> <message>`：动作栏（WS 或 RCON 回退）
+
+可在插件配置中调整：
+- `commands.enabled`：是否注册上述命令（默认开启）
+- `commands.authority`：执行所需权限（默认 2），避免普通用户误触发
+
 MIT

package/lib/index.d.ts

@@ -6,6 +6,14 @@ export interface MinecraftServiceAPI {
     broadcast(message: string): Promise<string>;
     /** 向指定玩家发送消息（tellraw） */
     sendTo(player: string, message: string): Promise<string>;
+    /** 通过 WS 广播（可回退 RCON） */
+    wsBroadcast(message: string): Promise<string | void>;
+    /** 通过 WS 私聊（可回退 RCON） */
+    wsTell(player: string, message: string): Promise<string | void>;
+    /** 通过 WS 或 RCON 发送标题、子标题 */
+    wsTitle(player: string, title: string, subtitle?: string): Promise<string | void>;
+    /** 通过 WS 或 RCON 发送动作栏 */
+    wsActionbar(player: string, message: string): Promise<string | void>;
 }
 declare class MinecraftService extends Service implements MinecraftServiceAPI {
     ctx: Context;
@@ -20,6 +28,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,10 +39,18 @@ 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>;
     private enqueue;
+    wsBroadcast(message: string): Promise<string | void>;
+    wsTell(player: string, message: string): Promise<string | void>;
+    wsTitle(player: string, title: string, subtitle?: string): Promise<string | void>;
+    wsActionbar(player: string, message: string): Promise<string | void>;
     private processQueue;
 }
 declare namespace MinecraftService {
@@ -54,9 +73,24 @@ 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;
+        commands?: {
+            enabled?: boolean;
+            authority?: number;
+        };
     }
     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;
@@ -23,6 +31,85 @@ class MinecraftService extends koishi_1.Service {
         if (config.webhook?.enabled) {
             this.registerWebhook();
         }
+        // 注册 Koishi 指令，便于 ChatLuna 通过自然语言“触发命令”
+        if (config.commands?.enabled !== false) {
+            const authority = config.commands?.authority ?? 2;
+            ctx.command('mc.exec <command:text>', '执行 Minecraft 指令 (RCON)')
+                .action(async ({ session }, command) => {
+                const currentAuth = Number((session?.user?.authority) ?? 0);
+                if (currentAuth < authority)
+                    return '权限不足';
+                if (!command)
+                    return '用法: mc.exec <command>';
+                try {
+                    const res = await this.execute(command);
+                    return res || '已执行';
+                }
+                catch (e) {
+                    return '执行失败: ' + (e?.message || e);
+                }
+            });
+            ctx.command('mc.say <message:text>', '向服务器广播消息')
+                .action(async ({ session }, message) => {
+                const currentAuth = Number((session?.user?.authority) ?? 0);
+                if (currentAuth < authority)
+                    return '权限不足';
+                if (!message)
+                    return '用法: mc.say <message>';
+                try {
+                    const res = await this.broadcast(message);
+                    return res || '已广播';
+                }
+                catch (e) {
+                    return '广播失败: ' + (e?.message || e);
+                }
+            });
+            ctx.command('mc.tell <player:string> <message:text>', '向指定玩家发送消息')
+                .action(async ({ session }, player, message) => {
+                const currentAuth = Number((session?.user?.authority) ?? 0);
+                if (currentAuth < authority)
+                    return '权限不足';
+                if (!player || !message)
+                    return '用法: mc.tell <player> <message>';
+                try {
+                    const res = await this.sendTo(player, message);
+                    return res || '已发送';
+                }
+                catch (e) {
+                    return '发送失败: ' + (e?.message || e);
+                }
+            });
+            ctx.command('mc.title <player:string> <title:text> [subtitle:text]', '向玩家发送标题/子标题')
+                .action(async ({ session }, player, title, subtitle) => {
+                const currentAuth = Number((session?.user?.authority) ?? 0);
+                if (currentAuth < authority)
+                    return '权限不足';
+                if (!player || !title)
+                    return '用法: mc.title <player> <title> [subtitle]';
+                try {
+                    await this.wsTitle(player, title, subtitle);
+                    return '已发送';
+                }
+                catch (e) {
+                    return '发送失败: ' + (e?.message || e);
+                }
+            });
+            ctx.command('mc.actionbar <player:string> <message:text>', '向玩家发送动作栏')
+                .action(async ({ session }, player, message) => {
+                const currentAuth = Number((session?.user?.authority) ?? 0);
+                if (currentAuth < authority)
+                    return '权限不足';
+                if (!player || !message)
+                    return '用法: mc.actionbar <player> <message>';
+                try {
+                    await this.wsActionbar(player, message);
+                    return '已发送';
+                }
+                catch (e) {
+                    return '发送失败: ' + (e?.message || e);
+                }
+            });
+        }
     }
     registerWebhook() {
         const { path = '/minecraft/webhook', secret, verifyMode = 'header-secret', signatureHeader = 'x-queqiao-signature', secretHeader = 'x-queqiao-secret' } = this.config.webhook;
@@ -73,6 +160,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 +170,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 +233,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 未启用');
@@ -169,6 +330,42 @@ class MinecraftService extends koishi_1.Service {
             this.processQueue();
         });
     }
+    // ========== WS 发送：优先 WS，不可用则回退 RCON ==========
+    async wsBroadcast(message) {
+        if (this.ws && this.config.websocket?.enabled) {
+            this.ws.send(JSON.stringify(buildWsOutboundPayload(this.config, 'broadcast', { message })));
+            return;
+        }
+        return await this.broadcast(message);
+    }
+    async wsTell(player, message) {
+        if (this.ws && this.config.websocket?.enabled) {
+            this.ws.send(JSON.stringify(buildWsOutboundPayload(this.config, 'tell', { player, message })));
+            return;
+        }
+        return await this.sendTo(player, message);
+    }
+    async wsTitle(player, title, subtitle) {
+        if (this.ws && this.config.websocket?.enabled) {
+            this.ws.send(JSON.stringify(buildWsOutboundPayload(this.config, 'title', { player, title, subtitle })));
+            return;
+        }
+        // RCON 回退
+        await this.execute(`title ${player} title ${JSON.stringify({ text: title })}`);
+        if (subtitle) {
+            await this.execute(`title ${player} subtitle ${JSON.stringify({ text: subtitle })}`);
+        }
+        return 'OK';
+    }
+    async wsActionbar(player, message) {
+        if (this.ws && this.config.websocket?.enabled) {
+            this.ws.send(JSON.stringify(buildWsOutboundPayload(this.config, 'actionbar', { player, message })));
+            return;
+        }
+        // RCON 回退
+        await this.execute(`title ${player} actionbar ${JSON.stringify({ text: message })}`);
+        return 'OK';
+    }
     async processQueue() {
         if (this.isProcessingQueue)
             return;
@@ -233,6 +430,29 @@ 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,
+        }),
+        commands: koishi_1.Schema.object({
+            enabled: koishi_1.Schema.boolean().description('注册 Koishi 指令: mc.exec/mc.say/mc.tell').default(true),
+            authority: koishi_1.Schema.number().description('执行这些指令所需的权限等级').default(2),
+        }).description('命令设置').default({ enabled: true, authority: 2 }),
     });
 })(MinecraftService || (MinecraftService = {}));
 exports.default = MinecraftService;
@@ -279,3 +499,7 @@ function mapQueqiaoEvent(type, data) {
             return { type, payload: data };
     }
 }
+function buildWsOutboundPayload(config, api, data) {
+    // 参考 QueQiao 的 WS 入站接口语义，采用 { api, data } 基本结构
+    return { api, data };
+}

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.4.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"