koishi-plugin-minecraft-adapter 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# koishi-plugin-minecraft-adapter
+
+Koishi 的 Minecraft 适配器：支持 RCON 与鹊桥(Queqiao) Webhook。
+
+- RCON：连接并发送命令/广播
+- Webhook：接收聊天、加入、离开等事件并在 Koishi 中触发
+
+参考实现：
+- https://github.com/17TheWord/nonebot-adapter-minecraft
+- https://github.com/KroMiose/nekro-agent/tree/main/nekro_agent/adapters/minecraft
+
+## 安装
+
+```bash
+npm i koishi-plugin-minecraft-adapter
+```
+
+## 配置
+
+- RCON：host/port/password/timeout/reconnectInterval/reconnectStrategy/maxReconnectInterval/broadcastMode
+- Webhook：enabled/path/secret/verifyMode/signatureHeader/secretHeader
+
+## 用法
+
+```ts
+await ctx.minecraft.execute('list')
+await ctx.minecraft.broadcast('服务器即将重启')
+await ctx.minecraft.sendTo('Steve', '你好')
+
+ctx.on('minecraft/chat', (p) => {
+  // p: { player, message, raw }
+})
+```
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,63 @@
+import { Context, Schema, Service } from 'koishi';
+export interface MinecraftServiceAPI {
+    /** 发送任意 RCON 指令，返回原始响应字符串 */
+    execute(command: string): Promise<string>;
+    /** 广播一条消息（基于配置选择 say 或 tellraw） */
+    broadcast(message: string): Promise<string>;
+    /** 向指定玩家发送消息（tellraw） */
+    sendTo(player: string, message: string): Promise<string>;
+}
+declare class MinecraftService extends Service implements MinecraftServiceAPI {
+    ctx: Context;
+    config: MinecraftService.Config;
+    static inject: {
+        required: any[];
+        optional: string[];
+    };
+    private rcon?;
+    private isConnecting;
+    private reconnectTimer?;
+    private currentReconnectInterval?;
+    private commandQueue;
+    private isProcessingQueue;
+    constructor(ctx: Context, config: MinecraftService.Config);
+    private registerWebhook;
+    start(): void;
+    stop(): void;
+    private connectRcon;
+    private scheduleReconnect;
+    private ensureConnected;
+    private disconnect;
+    execute(command: string): Promise<string>;
+    broadcast(message: string): Promise<string>;
+    sendTo(player: string, message: string): Promise<string>;
+    private enqueue;
+    private processQueue;
+}
+declare namespace MinecraftService {
+    interface RconConfig {
+        enabled: boolean;
+        host: string;
+        port: number;
+        password: string;
+        timeout: number;
+        reconnectInterval: number;
+        reconnectStrategy?: 'fixed' | 'exponential';
+        maxReconnectInterval?: number;
+        broadcastMode: 'say' | 'tellraw';
+    }
+    interface WebhookConfig {
+        enabled: boolean;
+        path: string;
+        secret?: string;
+        verifyMode?: 'none' | 'header-secret' | 'hmac-sha256';
+        signatureHeader?: string;
+        secretHeader?: string;
+    }
+    interface Config {
+        rcon?: RconConfig;
+        webhook?: WebhookConfig;
+    }
+    const Config: Schema<Config>;
+}
+export default MinecraftService;

package/lib/index.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const koishi_1 = require("koishi");
+const rcon_client_1 = require("rcon-client");
+const logger = new koishi_1.Logger('minecraft');
+class MinecraftService extends koishi_1.Service {
+    ctx;
+    config;
+    static inject = {
+        required: [],
+        optional: ['server'],
+    };
+    rcon;
+    isConnecting = false;
+    reconnectTimer;
+    currentReconnectInterval;
+    commandQueue = [];
+    isProcessingQueue = false;
+    constructor(ctx, config) {
+        super(ctx, 'minecraft', true);
+        this.ctx = ctx;
+        this.config = config;
+        if (config.webhook?.enabled) {
+            this.registerWebhook();
+        }
+    }
+    registerWebhook() {
+        const { path = '/minecraft/webhook', secret, verifyMode = 'header-secret', signatureHeader = 'x-queqiao-signature', secretHeader = 'x-queqiao-secret' } = this.config.webhook;
+        const router = this.ctx.router;
+        if (!router) {
+            logger.warn('未检测到 Koishi 服务器(router)，Webhook 将不会启用。请安装并启用 @koishijs/plugin-server。');
+            return;
+        }
+        router.post(path, async (koaCtx) => {
+            try {
+                const req = koaCtx.request;
+                const body = req.body || {};
+                // 验证
+                if (verifyMode === 'header-secret' && secret) {
+                    const provided = koaCtx.headers[secretHeader] || koaCtx.query['secret'] || '';
+                    if (provided !== secret) {
+                        koaCtx.status = 401;
+                        koaCtx.body = 'invalid secret';
+                        return;
+                    }
+                }
+                else if (verifyMode === 'hmac-sha256' && secret) {
+                    const sig = koaCtx.headers[signatureHeader] || '';
+                    const raw = req.rawBody ?? JSON.stringify(body);
+                    if (!verifyHmacSha256(raw, secret, sig)) {
+                        koaCtx.status = 401;
+                        koaCtx.body = 'invalid signature';
+                        return;
+                    }
+                }
+                // 兼容常见事件格式：{ type, data }
+                const type = body.type || body.event || 'unknown';
+                const data = body.data ?? body;
+                const mapped = mapQueqiaoEvent(type, data);
+                // 派发 Koishi 事件，名称按 "minecraft/<type>"
+                this.ctx.emit(`minecraft/${mapped.type}`, mapped.payload);
+                koaCtx.body = { ok: true };
+            }
+            catch (e) {
+                logger.warn(e);
+                koaCtx.status = 500;
+                koaCtx.body = 'internal error';
+            }
+        });
+        logger.info(`已注册鹊桥 Webhook 路由: ${path}`);
+    }
+    start() {
+        if (this.config.rcon?.enabled) {
+            this.ensureConnected();
+        }
+    }
+    stop() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        this.disconnect();
+    }
+    async connectRcon() {
+        if (this.isConnecting || this.rcon)
+            return;
+        this.isConnecting = true;
+        const { host, port, password, timeout } = this.config.rcon;
+        try {
+            logger.info(`RCON 连接中: ${host}:${port}`);
+            const conn = await rcon_client_1.Rcon.connect({ host, port, password, timeout });
+            this.rcon = conn;
+            this.isConnecting = false;
+            logger.info('RCON 连接成功');
+            conn.on('end', () => {
+                logger.warn('RCON 连接断开');
+                this.rcon = undefined;
+                this.scheduleReconnect();
+            });
+            conn.on('error', (err) => {
+                logger.warn('RCON 错误: ' + (err?.message || err));
+            });
+        }
+        catch (err) {
+            this.isConnecting = false;
+            logger.warn('RCON 连接失败: ' + (err?.message || err));
+            this.scheduleReconnect();
+        }
+    }
+    scheduleReconnect() {
+        const base = this.config.rcon?.reconnectInterval ?? 5000;
+        const strategy = this.config.rcon?.reconnectStrategy ?? 'fixed';
+        const maxInterval = this.config.rcon?.maxReconnectInterval ?? 60000;
+        if (this.currentReconnectInterval == null)
+            this.currentReconnectInterval = base;
+        const interval = strategy === 'exponential' ? Math.min(this.currentReconnectInterval * 2, maxInterval) : base;
+        if (!this.config.rcon?.enabled)
+            return;
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            this.currentReconnectInterval = interval;
+            this.ensureConnected();
+        }, interval);
+    }
+    ensureConnected() {
+        if (this.rcon)
+            return;
+        void this.connectRcon();
+    }
+    disconnect() {
+        if (this.rcon) {
+            try {
+                this.rcon.end();
+            }
+            catch { }
+            this.rcon = undefined;
+        }
+    }
+    async execute(command) {
+        if (!this.config.rcon?.enabled)
+            throw new Error('RCON 未启用');
+        this.ensureConnected();
+        if (!this.rcon)
+            throw new Error('RCON 未连接');
+        return await this.enqueue(command);
+    }
+    async broadcast(message) {
+        if (!this.config.rcon?.enabled)
+            throw new Error('RCON 未启用');
+        const mode = this.config.rcon.broadcastMode || 'say';
+        if (mode === 'say') {
+            return await this.execute(`say ${escapeForMc(message)}`);
+        }
+        // tellraw 使用简单 JSON 文本
+        const json = JSON.stringify([{ text: message }]);
+        return await this.execute(`tellraw @a ${json}`);
+    }
+    async sendTo(player, message) {
+        if (!this.config.rcon?.enabled)
+            throw new Error('RCON 未启用');
+        const json = JSON.stringify([{ text: message }]);
+        return await this.execute(`tellraw ${player} ${json}`);
+    }
+    async enqueue(command) {
+        return await new Promise((resolve, reject) => {
+            this.commandQueue.push({ command, resolve, reject });
+            this.processQueue();
+        });
+    }
+    async processQueue() {
+        if (this.isProcessingQueue)
+            return;
+        if (!this.rcon)
+            return;
+        this.isProcessingQueue = true;
+        try {
+            while (this.commandQueue.length && this.rcon) {
+                const task = this.commandQueue.shift();
+                try {
+                    const result = await this.rcon.send(task.command);
+                    task.resolve(result);
+                }
+                catch (err) {
+                    task.reject(err);
+                }
+            }
+        }
+        finally {
+            this.isProcessingQueue = false;
+        }
+    }
+}
+function escapeForMc(text) {
+    return text.replace(/[\n\r]/g, ' ').replace(/[§]/g, '');
+}
+(function (MinecraftService) {
+    MinecraftService.Config = koishi_1.Schema.object({
+        rcon: koishi_1.Schema.object({
+            enabled: koishi_1.Schema.boolean().description('启用 RCON').default(true),
+            host: koishi_1.Schema.string().description('RCON 主机地址').default('127.0.0.1'),
+            port: koishi_1.Schema.number().description('RCON 端口').default(25575),
+            password: koishi_1.Schema.string().description('RCON 密码').default(''),
+            timeout: koishi_1.Schema.number().description('RCON 超时(ms)').default(5000),
+            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),
+            broadcastMode: koishi_1.Schema.union(['say', 'tellraw']).description('广播模式').default('say'),
+        }).description('RCON 设置').default({
+            enabled: true,
+            host: '127.0.0.1',
+            port: 25575,
+            password: '',
+            timeout: 5000,
+            reconnectInterval: 5000,
+            reconnectStrategy: 'fixed',
+            maxReconnectInterval: 60000,
+            broadcastMode: 'say',
+        }),
+        webhook: koishi_1.Schema.object({
+            enabled: koishi_1.Schema.boolean().description('启用鹊桥 Webhook').default(false),
+            path: koishi_1.Schema.string().description('Webhook 路径').default('/minecraft/webhook'),
+            secret: koishi_1.Schema.string().role('secret').description('共享密钥（可选）'),
+            verifyMode: koishi_1.Schema.union(['none', 'header-secret', 'hmac-sha256']).description('校验方式').default('header-secret'),
+            signatureHeader: koishi_1.Schema.string().description('签名头(用于 HMAC)').default('x-queqiao-signature'),
+            secretHeader: koishi_1.Schema.string().description('密钥头(用于 header-secret)').default('x-queqiao-secret'),
+        }).description('Webhook 设置').default({
+            enabled: false,
+            path: '/minecraft/webhook',
+            secret: '',
+            verifyMode: 'header-secret',
+            signatureHeader: 'x-queqiao-signature',
+            secretHeader: 'x-queqiao-secret',
+        }),
+    });
+})(MinecraftService || (MinecraftService = {}));
+exports.default = MinecraftService;
+function verifyHmacSha256(rawBody, secret, signatureHeader) {
+    try {
+        const sig = signatureHeader.replace(/^sha256=/i, '');
+        // 延迟引入 crypto，避免浏览器侧打包
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const crypto = require('crypto');
+        const h = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+        return timingSafeEqual(h, sig);
+    }
+    catch {
+        return false;
+    }
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let r = 0;
+    for (let i = 0; i < a.length; i++)
+        r |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return r === 0;
+}
+function mapQueqiaoEvent(type, data) {
+    // 兼容常见事件名，向 Koishi 事件命名空间收敛
+    switch (type) {
+        case 'chat':
+        case 'player_chat':
+            return { type: 'chat', payload: { player: data.player || data.name, message: data.message || data.text, raw: data } };
+        case 'join':
+        case 'player_join':
+            return { type: 'join', payload: { player: data.player || data.name, raw: data } };
+        case 'leave':
+        case 'quit':
+        case 'player_quit':
+            return { type: 'leave', payload: { player: data.player || data.name, reason: data.reason, raw: data } };
+        case 'death':
+            return { type: 'death', payload: { player: data.player || data.name, message: data.message || data.reason, raw: data } };
+        case 'advancement':
+        case 'advancement_earned':
+            return { type: 'advancement', payload: { player: data.player || data.name, advancement: data.advancement || data.key, raw: data } };
+        default:
+            return { type, payload: data };
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "koishi-plugin-minecraft-adapter",
+  "description": "Minecraft RCON & webhook integration for Koishi",
+  "version": "0.1.0",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "license": "MIT",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "koishi": "^4.17.9"
+  },
+  "dependencies": {
+    "rcon-client": "^4.2.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "koishi",
+    "plugin",
+    "minecraft",
+    "rcon",
+    "webhook"
+  ],
+  "koishi": {
+    "service": {
+      "implements": [
+        "minecraft"
+      ]
+    },
+    "description": {
+      "en": "Minecraft RCON & webhook integration for Koishi",
+      "zh": "Minecraft RCON 与 Webhook 集成，提供 minecraft 服务"
+    }
+  }
+}
+
+