koishi-plugin-msg-router 1.0.0

package/lib/index.d.ts

@@ -0,0 +1,39 @@
+import { Context, Schema } from 'koishi';
+export declare const name = "msg-router";
+export interface ClientRouteConfig {
+    name: string;
+    mode: 'client';
+    enabled: boolean;
+    endpoint: string;
+    token: string;
+    secret: string;
+    commands: string[];
+    action: string;
+    timeout: number;
+    heartbeatInterval: number;
+    reconnectInterval: number;
+    maxConcurrency: number;
+}
+export interface ServerRouteConfig {
+    name: string;
+    mode: 'server';
+    enabled: boolean;
+    listenHost: string;
+    listenPort: number;
+    token: string;
+    secret: string;
+    commands: string[];
+    action: string;
+    timeout: number;
+    heartbeatInterval: number;
+    reconnectInterval: number;
+    maxConcurrency: number;
+}
+export type RouteConfig = ClientRouteConfig | ServerRouteConfig;
+export interface Config {
+    debug: boolean;
+    clientRoutes: ClientRouteConfig[];
+    serverRoutes: ServerRouteConfig[];
+}
+export declare const Config: Schema<Config>;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,675 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.name = void 0;
+exports.apply = apply;
+const ws_1 = __importDefault(require("ws"));
+const koishi_1 = require("koishi");
+exports.name = 'msg-router';
+const CommonRouteConfig = {
+    name: koishi_1.Schema.string().default('后端路由').description('这条路由的显示名称'),
+    enabled: koishi_1.Schema.boolean().default(true).description('是否启用这条路由'),
+    token: koishi_1.Schema.string().role('secret').default('').description('后端鉴权令牌，可留空'),
+    secret: koishi_1.Schema.string().role('secret').default('').description('HMAC 签名密钥，可留空'),
+    commands: koishi_1.Schema.array(koishi_1.Schema.string()).default([]).description('触发这条路由的命令列表'),
+    action: koishi_1.Schema.string().default('msg_router.forward_command').description('发送给后端的 action 名称'),
+    timeout: koishi_1.Schema.number().default(10000).description('单次请求超时时间，单位毫秒'),
+    heartbeatInterval: koishi_1.Schema.number().default(30000).description('心跳间隔，单位毫秒'),
+    reconnectInterval: koishi_1.Schema.number().default(5000).description('断线后重连间隔，单位毫秒'),
+    maxConcurrency: koishi_1.Schema.number().min(1).default(16).description('这条路由同时处理的最大并发数'),
+};
+const ClientRouteConfig = koishi_1.Schema.object({
+    ...CommonRouteConfig,
+    mode: koishi_1.Schema.const('client').description('插件作为客户端连接后端'),
+    endpoint: koishi_1.Schema.string().default('ws://127.0.0.1:8080').description('OneBot v11 WebSocket 地址'),
+});
+const ServerRouteConfig = koishi_1.Schema.object({
+    ...CommonRouteConfig,
+    mode: koishi_1.Schema.const('server').description('插件作为服务端等待后端连接'),
+    listenHost: koishi_1.Schema.string().default('127.0.0.1').description('server 模式下的监听主机'),
+    listenPort: koishi_1.Schema.natural().default(8080).description('server 模式下的监听端口'),
+});
+const RouteConfig = koishi_1.Schema.union([
+    ClientRouteConfig,
+    ServerRouteConfig,
+]).role('table');
+exports.Config = koishi_1.Schema.object({
+    debug: koishi_1.Schema.boolean().default(false).description('是否输出调试日志'),
+    clientRoutes: koishi_1.Schema.array(ClientRouteConfig)
+        .role('table')
+        .default([])
+        .description('正向 WS 路由列表，插件主动连接后端'),
+    serverRoutes: koishi_1.Schema.array(ServerRouteConfig)
+        .role('table')
+        .default([])
+        .description('反向 WS 路由列表，插件监听等待后端连接'),
+});
+function toOneBotId(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+        return value; // Return original string if it's not a number (e.g. UUID)
+    }
+    return undefined;
+}
+function toElements(value) {
+    if (value == null)
+        return [];
+    if (typeof value === 'string')
+        return [koishi_1.h.text(value)];
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return [koishi_1.h.text(String(value))];
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => toElements(item));
+    }
+    if (typeof value === 'object') {
+        const segment = value;
+        if (segment.type === 'text') {
+            return [koishi_1.h.text(segment.data?.text || '')];
+        }
+        if (segment.type === 'image' || segment.type === 'img') {
+            let src = segment.data?.file || segment.data?.url || '';
+            if (typeof src === 'string' && src.startsWith('base64://')) {
+                src = 'data:image/png;base64,' + src.slice(9);
+            }
+            return [koishi_1.h.image(src)];
+        }
+        if (segment.type === 'at') {
+            if (segment.data?.qq === 'all')
+                return [(0, koishi_1.h)('at', { type: 'all' })];
+            return [(0, koishi_1.h)('at', { id: segment.data?.qq })];
+        }
+        if (segment.type === 'record' || segment.type === 'audio') {
+            let src = segment.data?.file || segment.data?.url || '';
+            if (typeof src === 'string' && src.startsWith('base64://')) {
+                src = 'data:audio/mp3;base64,' + src.slice(9);
+            }
+            return [koishi_1.h.audio(src)];
+        }
+        if (segment.type === 'video') {
+            let src = segment.data?.file || segment.data?.url || '';
+            if (typeof src === 'string' && src.startsWith('base64://')) {
+                src = 'data:video/mp4;base64,' + src.slice(9);
+            }
+            return [koishi_1.h.video(src)];
+        }
+        if (segment.type === 'face') {
+            return [(0, koishi_1.h)('face', { id: segment.data?.id || '' })];
+        }
+        if (segment.type === 'reply') {
+            return [(0, koishi_1.h)('quote', { id: segment.data?.id || '' })];
+        }
+        if (segment.reply !== undefined)
+            return toElements(segment.reply);
+        if (segment.message !== undefined)
+            return toElements(segment.message);
+        if (segment.text !== undefined)
+            return [koishi_1.h.text(String(segment.text))];
+    }
+    return [];
+}
+function transformElements(elements) {
+    const result = [];
+    const extractSrc = (el) => {
+        let src = el.attrs.src || el.attrs.url || '';
+        if (typeof src === 'string' && src.startsWith('data:')) {
+            const match = src.match(/^data:.*?;base64,(.*)$/);
+            if (match) {
+                src = 'base64://' + match[1];
+            }
+        }
+        return src;
+    };
+    for (const el of elements) {
+        if (el.type === 'text') {
+            result.push({ type: 'text', data: { text: el.attrs.content || '' } });
+        }
+        else if (el.type === 'at') {
+            if (el.attrs.type === 'all' || el.attrs.role === 'all') {
+                result.push({ type: 'at', data: { qq: 'all' } });
+            }
+            else {
+                result.push({ type: 'at', data: { qq: el.attrs.id } });
+            }
+        }
+        else if (el.type === 'image' || el.type === 'img') {
+            result.push({ type: 'image', data: { file: extractSrc(el) } });
+        }
+        else if (el.type === 'audio' || el.type === 'record') {
+            result.push({ type: 'record', data: { file: extractSrc(el) } });
+        }
+        else if (el.type === 'video') {
+            result.push({ type: 'video', data: { file: extractSrc(el) } });
+        }
+        else if (el.type === 'face') {
+            result.push({ type: 'face', data: { id: el.attrs.id } });
+        }
+        else if (el.type === 'quote') {
+            result.push({ type: 'reply', data: { id: el.attrs.id } });
+        }
+        else if (el.children && el.children.length > 0) {
+            result.push(...transformElements(el.children));
+        }
+    }
+    return result;
+}
+function buildOneBotMessageEvent(session, commandName, content) {
+    const text = session?.content || (commandName + ' ' + (content ?? '')).trim();
+    const isGroup = Boolean(session?.guildId != null
+        || (session?.channelId != null && String(session.channelId) !== String(session?.userId ?? '')));
+    const userId = toOneBotId(session?.userId);
+    const groupId = isGroup ? toOneBotId(session?.guildId ?? session?.channelId) : undefined;
+    const selfId = toOneBotId(session?.selfId ?? session?.bot?.selfId);
+    const messageId = toOneBotId(session?.messageId);
+    const elements = session?.elements || koishi_1.h.parse(text);
+    const messageSegments = transformElements(elements);
+    return {
+        time: Math.floor(Date.now() / 1000),
+        self_id: selfId ?? 0,
+        post_type: 'message',
+        message_type: isGroup ? 'group' : 'private',
+        sub_type: 'normal',
+        message_id: messageId ?? 0,
+        user_id: userId ?? 0,
+        group_id: isGroup ? (groupId ?? 0) : undefined,
+        message: messageSegments.length > 0 ? messageSegments : [{ type: 'text', data: { text } }],
+        raw_message: text,
+        font: 0,
+        sender: {
+            user_id: userId,
+            nickname: session?.username ?? session?.nickname,
+        },
+    };
+}
+class RouteRuntime {
+    ctx;
+    config;
+    route;
+    socket = null;
+    server = null;
+    connecting = null;
+    reconnectTimer = null;
+    heartbeatTimer = null;
+    serverReadyWaiter = null;
+    pending = new Map();
+    inflight = 0;
+    queue = [];
+    closed = false;
+    lastPong = 0;
+    constructor(ctx, config, route) {
+        this.ctx = ctx;
+        this.config = config;
+        this.route = route;
+    }
+    get kind() {
+        if (this.route.mode === 'client')
+            return 'client';
+        if ('endpoint' in this.route && this.route.endpoint)
+            return 'client';
+        return 'server';
+    }
+    get routeLabel() {
+        return `${this.route.name}(${this.kind})`;
+    }
+    get enabled() {
+        const commands = Array.isArray(this.route.commands) ? this.route.commands : [];
+        if (!this.route.enabled || !commands.length)
+            return false;
+        if (this.kind === 'client')
+            return !!('endpoint' in this.route && this.route.endpoint && this.route.endpoint.length > 0);
+        return !!('listenHost' in this.route && this.route.listenHost) && !!('listenPort' in this.route && this.route.listenPort && this.route.listenPort > 0);
+    }
+    start() {
+        if (!this.enabled)
+            return;
+        this.ctx.logger(exports.name).info(`route ${this.routeLabel} starting`);
+        if (this.kind === 'server') {
+            this.startServer();
+            return;
+        }
+        void this.connect().catch((error) => {
+            this.ctx.logger(exports.name).warn(`route ${this.route.name} initial connect failed: ${error.message}`);
+            this.scheduleReconnect();
+        });
+    }
+    stop() {
+        this.closed = true;
+        this.ctx.logger(exports.name).info(`route ${this.routeLabel} stopping`);
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.server) {
+            this.server.close();
+            this.server = null;
+        }
+        this.rejectServerReadyWaiter(new Error(`route ${this.route.name} closed`));
+        this.rejectAll(new Error(`route ${this.route.name} closed`));
+        if (this.socket && this.socket.readyState === ws_1.default.OPEN) {
+            this.socket.close(1000, 'plugin disposed');
+        }
+        else if (this.socket) {
+            this.socket.terminate();
+        }
+        this.socket = null;
+    }
+    async forward(session, commandName, content = '') {
+        if (!Array.isArray(this.route.commands)) {
+            throw new Error(`route ${this.route.name} has no commands configured`);
+        }
+        this.ctx.logger(exports.name).info(`route ${this.routeLabel} command trigger: command=${commandName} user=${session.userId ?? 'unknown'} channel=${session.channelId ?? 'unknown'}`);
+        if (this.config.debug) {
+            this.ctx.logger(exports.name).debug(`route ${this.routeLabel} command content: ${JSON.stringify(content)}`);
+        }
+        const event = buildOneBotMessageEvent(session, commandName, content);
+        this.sendEvent(event);
+        return undefined; // We do not return a reply here. Standard OB11 backends reply using send_msg API calls.
+    }
+    sendEvent(event) {
+        if (this.closed)
+            return;
+        const push = async () => {
+            if (this.kind === 'server') {
+                await this.waitForServerSocket();
+            }
+            else {
+                await this.connect();
+            }
+            const socket = this.socket;
+            if (!socket || socket.readyState !== ws_1.default.OPEN) {
+                throw new Error(`route ${this.route.name} is not connected`);
+            }
+            if (this.config.debug) {
+                this.ctx.logger(exports.name).debug(`route ${this.routeLabel} push event => ${JSON.stringify(event)}`);
+            }
+            socket.send(JSON.stringify(event), (error) => {
+                if (error) {
+                    this.ctx.logger(exports.name).warn(`route ${this.routeLabel} push event failed: ${error.message}`);
+                }
+            });
+        };
+        push().catch(e => this.ctx.logger(exports.name).warn(e));
+    }
+    acquireSlot() {
+        if (this.inflight < this.route.maxConcurrency) {
+            this.inflight += 1;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.queue.push(() => {
+                this.inflight += 1;
+                resolve();
+            });
+        });
+    }
+    releaseSlot() {
+        this.inflight = Math.max(0, this.inflight - 1);
+        const next = this.queue.shift();
+        if (next)
+            next();
+    }
+    async connect() {
+        if (this.closed) {
+            throw new Error(`route ${this.route.name} is disposed`);
+        }
+        if (this.socket?.readyState === ws_1.default.OPEN)
+            return;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
+            if (this.kind !== 'client') {
+                finish(() => reject(new Error(`route ${this.route.name} is not in client mode`)));
+                return;
+            }
+            const endpoint = 'endpoint' in this.route ? this.route.endpoint : '';
+            this.ctx.logger(exports.name).info(`route ${this.routeLabel} connecting to ${endpoint}`);
+            const socket = new ws_1.default(endpoint, {
+                handshakeTimeout: this.route.timeout,
+                headers: this.route.token
+                    ? {
+                        authorization: `Bearer ${this.route.token}`,
+                    }
+                    : undefined,
+            });
+            socket.once('open', () => {
+                this.socket = socket;
+                this.lastPong = Date.now();
+                this.bindSocket(socket);
+                this.startHeartbeat();
+                this.ctx.logger(exports.name).info(`route ${this.routeLabel} connected`);
+                // Push standard OB11 lifecycle meta_event
+                const selfId = toOneBotId(this.ctx.bots[0]?.selfId) || 0;
+                const connectEvent = {
+                    time: Math.floor(Date.now() / 1000),
+                    self_id: selfId,
+                    post_type: 'meta_event',
+                    meta_event_type: 'lifecycle',
+                    sub_type: 'connect'
+                };
+                if (socket.readyState === ws_1.default.OPEN) {
+                    socket.send(JSON.stringify(connectEvent));
+                }
+                finish(resolve);
+            });
+            socket.once('error', (error) => {
+                this.ctx.logger(exports.name).warn(`route ${this.routeLabel} connect error: ${error.message}`);
+                finish(() => reject(error));
+            });
+            socket.once('close', (code, reason) => {
+                const text = Buffer.isBuffer(reason) ? reason.toString() : String(reason ?? '');
+                this.ctx.logger(exports.name).warn(`route ${this.routeLabel} connect closed: code=${code} reason=${text || 'none'}`);
+                finish(() => reject(new Error(`route ${this.route.name} connection closed during handshake`)));
+            });
+        }).finally(() => {
+            this.connecting = null;
+        });
+        return this.connecting;
+    }
+    startServer() {
+        if (this.server || this.closed)
+            return;
+        if (this.kind !== 'server') {
+            return;
+        }
+        const listenHost = 'listenHost' in this.route ? this.route.listenHost : '127.0.0.1';
+        const listenPort = 'listenPort' in this.route ? this.route.listenPort : 0;
+        this.server = new ws_1.default.Server({
+            port: listenPort,
+            host: listenHost,
+        });
+        this.server.on('connection', (socket, request) => {
+            const remote = request.socket?.remoteAddress ?? 'unknown';
+            this.ctx.logger(exports.name).info(`route ${this.routeLabel} accepted connection from ${remote}`);
+            if (this.route.token) {
+                const auth = request.headers.authorization ?? '';
+                if (auth !== `Bearer ${this.route.token}`) {
+                    this.ctx.logger(exports.name).warn(`route ${this.routeLabel} rejected connection from ${remote}: unauthorized`);
+                    socket.close(1008, 'unauthorized');
+                    return;
+                }
+            }
+            if (this.socket && this.socket !== socket) {
+                this.socket.terminate();
+            }
+            this.socket = socket;
+            this.lastPong = Date.now();
+            this.bindSocket(socket);
+            this.startHeartbeat();
+            this.resolveServerReadyWaiter();
+            // Push standard OB11 lifecycle meta_event
+            const selfId = toOneBotId(this.ctx.bots[0]?.selfId) || 0;
+            const connectEvent = {
+                time: Math.floor(Date.now() / 1000),
+                self_id: selfId,
+                post_type: 'meta_event',
+                meta_event_type: 'lifecycle',
+                sub_type: 'connect'
+            };
+            if (socket.readyState === ws_1.default.OPEN) {
+                socket.send(JSON.stringify(connectEvent));
+            }
+            socket.on('close', () => {
+                if (this.socket === socket) {
+                    this.handleDisconnect();
+                }
+            });
+        });
+        this.server.on('listening', () => {
+            this.ctx.logger(exports.name).info(`route ${this.routeLabel} listening on ws://${listenHost}:${listenPort}`);
+        });
+        this.server.on('error', (error) => {
+            this.ctx.logger(exports.name).warn(`route ${this.routeLabel} server error: ${error.message}`);
+        });
+    }
+    async waitForServerSocket() {
+        if (this.socket?.readyState === ws_1.default.OPEN)
+            return;
+        const waiter = this.getServerReadyWaiter();
+        await waiter.promise;
+    }
+    bindSocket(socket) {
+        socket.on('message', async (raw) => {
+            const data = this.parseIncoming(raw);
+            if (!data)
+                return;
+            if (this.config.debug) {
+                this.ctx.logger(exports.name).debug(`route ${this.routeLabel} <= raw=${typeof raw === 'string' ? raw : raw.toString()}`);
+                this.ctx.logger(exports.name).debug(`route ${this.routeLabel} <= ${JSON.stringify(data)}`);
+            }
+            if (data.action) {
+                const sendResponse = (response) => {
+                    if (data.echo)
+                        response.echo = data.echo;
+                    if (socket.readyState === ws_1.default.OPEN) {
+                        socket.send(JSON.stringify(response));
+                    }
+                };
+                if (data.action === 'send_private_msg' || (data.action === 'send_msg' && data.params?.message_type === 'private')) {
+                    const userId = data.params?.user_id;
+                    const message = data.params?.message;
+                    if (userId == null || message == null) {
+                        return sendResponse({ status: 'failed', retcode: 100, msg: 'Missing user_id or message', data: null });
+                    }
+                    const bot = this.ctx.bots.find(b => b.selfId === String(data.params?.self_id)) || this.ctx.bots[0];
+                    if (bot) {
+                        try {
+                            const msgIds = await bot.sendPrivateMessage(String(userId), toElements(message));
+                            const msgId = msgIds && msgIds.length > 0 ? (Number(msgIds[0]) || Math.floor(Math.random() * 1000000)) : Math.floor(Math.random() * 1000000);
+                            sendResponse({ status: 'ok', retcode: 0, data: { message_id: msgId } });
+                        }
+                        catch (e) {
+                            this.ctx.logger(exports.name).error(`[send_private_msg] Failed to send to ${userId}:`, e);
+                            sendResponse({ status: 'failed', retcode: 100, msg: String(e), data: null });
+                        }
+                    }
+                    else {
+                        sendResponse({ status: 'failed', retcode: 100, msg: 'No Koishi bot available', data: null });
+                    }
+                    return;
+                }
+                if (data.action === 'send_group_msg' || (data.action === 'send_msg' && data.params?.message_type === 'group')) {
+                    const groupId = data.params?.group_id;
+                    const message = data.params?.message;
+                    if (groupId == null || message == null) {
+                        return sendResponse({ status: 'failed', retcode: 100, msg: 'Missing group_id or message', data: null });
+                    }
+                    const bot = this.ctx.bots.find(b => b.selfId === String(data.params?.self_id)) || this.ctx.bots[0];
+                    if (bot) {
+                        try {
+                            const msgIds = await bot.sendMessage(String(groupId), toElements(message));
+                            const msgId = msgIds && msgIds.length > 0 ? (Number(msgIds[0]) || Math.floor(Math.random() * 1000000)) : Math.floor(Math.random() * 1000000);
+                            sendResponse({ status: 'ok', retcode: 0, data: { message_id: msgId } });
+                        }
+                        catch (e) {
+                            this.ctx.logger(exports.name).error(`[send_group_msg] Failed to send to ${groupId}:`, e);
+                            sendResponse({ status: 'failed', retcode: 100, msg: String(e), data: null });
+                        }
+                    }
+                    else {
+                        sendResponse({ status: 'failed', retcode: 100, msg: 'No Koishi bot available', data: null });
+                    }
+                    return;
+                }
+                // Unsupported action fallback
+                sendResponse({ status: 'failed', retcode: 102, msg: 'Unsupported API action', data: null });
+                return;
+            }
+        });
+        socket.on('pong', () => {
+            this.lastPong = Date.now();
+        });
+        socket.on('close', (code, reason) => {
+            const text = Buffer.isBuffer(reason) ? reason.toString() : String(reason ?? '');
+            this.ctx.logger(exports.name).warn(`route ${this.routeLabel} socket closed: code=${code} reason=${text || 'none'}`);
+            this.handleDisconnect();
+        });
+        socket.on('error', (error) => {
+            this.ctx.logger(exports.name).warn(`route ${this.routeLabel} websocket error: ${error.message}`);
+        });
+    }
+    parseIncoming(raw) {
+        const text = typeof raw === 'string' ? raw : raw.toString();
+        try {
+            return JSON.parse(text);
+        }
+        catch (e) {
+            if (this.config.debug) {
+                this.ctx.logger(exports.name).debug(`route ${this.routeLabel} <= failed to parse JSON: ${text}`);
+            }
+            return null;
+        }
+    }
+    startHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = setInterval(() => {
+            const socket = this.socket;
+            if (!socket || socket.readyState !== ws_1.default.OPEN)
+                return;
+            const elapsed = Date.now() - this.lastPong;
+            if (elapsed > this.route.heartbeatInterval * 2) {
+                socket.terminate();
+                return;
+            }
+            socket.ping();
+        }, this.route.heartbeatInterval);
+    }
+    handleDisconnect() {
+        this.socket = null;
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.rejectServerReadyWaiter(new Error(`route ${this.route.name} disconnected`));
+        this.rejectAll(new Error(`route ${this.route.name} disconnected`));
+        if (!this.closed && this.kind === 'client') {
+            this.ctx.logger(exports.name).warn(`route ${this.routeLabel} scheduling reconnect in ${this.route.reconnectInterval}ms`);
+            this.scheduleReconnect();
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer || this.closed)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.ctx.logger(exports.name).info(`route ${this.routeLabel} reconnecting`);
+            void this.connect().catch((error) => {
+                this.ctx.logger(exports.name).warn(`route ${this.routeLabel} reconnect failed: ${error.message}`);
+                this.scheduleReconnect();
+            });
+        }, this.route.reconnectInterval);
+    }
+    rejectAll(error) {
+        for (const [echo, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+            this.pending.delete(echo);
+        }
+    }
+    getServerReadyWaiter() {
+        if (this.serverReadyWaiter)
+            return this.serverReadyWaiter;
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        const timer = setTimeout(() => {
+            if (this.serverReadyWaiter?.promise === promise) {
+                this.serverReadyWaiter = null;
+            }
+            reject(new Error(`route ${this.route.name} is waiting for backend connection`));
+        }, this.route.timeout);
+        this.serverReadyWaiter = { promise, resolve, reject, timer };
+        return this.serverReadyWaiter;
+    }
+    resolveServerReadyWaiter() {
+        if (!this.serverReadyWaiter)
+            return;
+        clearTimeout(this.serverReadyWaiter.timer);
+        this.serverReadyWaiter.resolve();
+        this.serverReadyWaiter = null;
+    }
+    rejectServerReadyWaiter(error) {
+        if (!this.serverReadyWaiter)
+            return;
+        clearTimeout(this.serverReadyWaiter.timer);
+        this.serverReadyWaiter.reject(error);
+        this.serverReadyWaiter = null;
+    }
+}
+function apply(ctx, config) {
+    const logger = ctx.logger(exports.name);
+    const runtimes = new Map();
+    const registered = new Set();
+    const routes = [...config.clientRoutes, ...config.serverRoutes];
+    for (const route of routes) {
+        const runtime = new RouteRuntime(ctx, config, route);
+        runtimes.set(route.name, runtime);
+        if (!route.enabled)
+            continue;
+        const kind = route.mode === 'client' || ('endpoint' in route && route.endpoint) ? 'client' : 'server';
+        if (kind === 'client') {
+            if (!('endpoint' in route) || !route.endpoint) {
+                logger.warn(`skip route ${route.name}: endpoint is empty`);
+                continue;
+            }
+        }
+        else {
+            if (!('listenHost' in route) || !route.listenHost || !('listenPort' in route) || !route.listenPort) {
+                logger.warn(`skip route ${route.name}: listenHost or listenPort is empty`);
+                continue;
+            }
+        }
+        if (!Array.isArray(route.commands) || !route.commands.length) {
+            logger.warn(`skip route ${route.name}: no commands configured`);
+            continue;
+        }
+        for (const commandName of route.commands) {
+            const normalized = commandName.trim();
+            if (!normalized)
+                continue;
+            if (registered.has(normalized)) {
+                logger.warn(`skip duplicated command ${normalized} from route ${route.name}`);
+                continue;
+            }
+            registered.add(normalized);
+            ctx.command(`${normalized} [content:text]`).action(async ({ session }, content) => {
+                if (config.debug) {
+                    logger.debug(`command trigger: ${normalized} route=${route.name} user=${session?.userId ?? 'unknown'} channel=${session?.channelId ?? 'unknown'} content=${JSON.stringify(content ?? '')}`);
+                }
+                await runtime.forward(session, normalized, content ?? '');
+                return undefined;
+            });
+        }
+    }
+    ctx.on('ready', () => {
+        for (const runtime of runtimes.values()) {
+            runtime.start();
+        }
+    });
+    ctx.on('dispose', () => {
+        for (const runtime of runtimes.values()) {
+            runtime.stop();
+        }
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "koishi-plugin-msg-router",
+  "description": "OneBot v11 WebSocket 消息转发插件",
+  "version": "1.0.0",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b -w"
+  },
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "onebot",
+    "onebot11",
+    "websocket",
+    "router"
+  ],
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {},
+  "peerDependencies": {
+    "koishi": "^4.18.0"
+  },
+  "koishi": {
+    "description": {
+      "zh": "标准 OneBot v11 WebSocket 消息路由与通信中间件",
+      "en": "Standard OneBot v11 WebSocket message routing and communication middleware"
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,165 @@
+# koishi-plugin-msg-router
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-msg-router?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-msg-router)
+
+这是一个用于 Koishi 的消息转发插件。它把你配置好的指令转发到外部 OneBot v11 WebSocket 后端，再把后端返回内容回传给用户。
+
+## 主要用途
+
+- 把某些 Koishi 指令交给外部后端程序处理
+- 支持正向 WS 和反向 WS 两种模式
+- 后端可通过 WebSocket 常驻连接接收请求
+- 支持令牌鉴权，`token` 可留空
+- 支持可选的 HMAC 签名
+- 支持断线重连、心跳保活、超时控制、并发控制
+
+## 控制台配置说明
+
+### 总开关
+
+- `debug`：是否输出调试信息
+
+### 正向 WS 路由列表
+
+这张表用于“插件主动连接后端”的场景。
+
+- `name`：路由名称
+- `enabled`：是否启用
+- `mode`：固定为 `client`
+- `endpoint`：OneBot v11 WebSocket 地址
+- `token`：后端鉴权令牌，可不填
+- `secret`：HMAC 签名密钥，可不填
+- `commands`：触发这条路由的 Koishi 指令
+- `action`：发送给后端的 action 名称
+- `timeout`：单次请求等待时间，单位毫秒
+- `heartbeatInterval`：发送 ping 的间隔，单位毫秒
+- `reconnectInterval`：断线后的重连间隔，单位毫秒
+- `maxConcurrency`：同时允许的请求数量
+
+### 反向 WS 路由列表
+
+这张表用于“插件监听，后端主动连进来”的场景。
+
+- `name`：路由名称
+- `enabled`：是否启用
+- `mode`：固定为 `server`
+- `listenHost`：监听主机
+- `listenPort`：监听端口
+- `token`：后端鉴权令牌，可不填
+- `secret`：HMAC 签名密钥，可不填
+- `commands`：触发这条路由的 Koishi 指令
+- `action`：发送给后端的 action 名称
+- `timeout`：单次请求等待时间，单位毫秒
+- `heartbeatInterval`：发送 ping 的间隔，单位毫秒
+- `reconnectInterval`：断线后的重连间隔，单位毫秒
+- `maxConcurrency`：同时允许的请求数量
+
+## 推荐配置示例
+
+```json
+{
+  "debug": false,
+  "clientRoutes": [
+    {
+      "name": "AI 后端",
+      "enabled": true,
+      "mode": "client",
+      "endpoint": "ws://127.0.0.1:8080",
+      "token": "",
+      "secret": "",
+      "commands": ["ask", "translate", "summarize"],
+      "action": "msg_router.forward_command",
+      "timeout": 10000,
+      "heartbeatInterval": 30000,
+      "reconnectInterval": 5000,
+      "maxConcurrency": 16
+    }
+  ],
+  "serverRoutes": [
+    {
+      "name": "反向后端",
+      "enabled": true,
+      "mode": "server",
+      "listenHost": "127.0.0.1",
+      "listenPort": 8080,
+      "token": "",
+      "secret": "",
+      "commands": ["reply", "summarize"],
+      "action": "msg_router.forward_command",
+      "timeout": 10000,
+      "heartbeatInterval": 30000,
+      "reconnectInterval": 5000,
+      "maxConcurrency": 16
+    }
+  ]
+}
+```
+
+## 模式说明
+
+- `client` 模式：插件主动连接后端
+- `server` 模式：插件自己监听，等待后端连接
+- `server` 模式下，如果后端还没连上来，命令会等待到超时为止
+
+## 协议约定
+
+插件向后端发送带 `action` / `echo` 外壳的请求，其中 `params` 使用 OneBot v11 的标准消息事件结构。当前只把文本内容封装为 `message` 段：
+
+```json
+{
+  "action": "msg_router.forward_command",
+  "params": {
+    "time": 1710000000,
+    "self_id": 123456789,
+    "post_type": "message",
+    "message_type": "group",
+    "sub_type": "normal",
+    "message_id": 10001,
+    "user_id": 123456,
+    "group_id": 654321,
+    "message": [
+      {
+        "type": "text",
+        "data": {
+          "text": "hello"
+        }
+      }
+    ],
+    "raw_message": "hello",
+    "font": 0,
+    "sender": {
+      "user_id": 123456,
+      "nickname": "Alice"
+    }
+  },
+  "auth": {
+    "algorithm": "hmac-sha256",
+    "signature": "hex-string",
+    "timestamp": 1710000000000
+  },
+  "echo": "uuid"
+}
+```
+
+后端响应示例：
+
+```json
+{
+  "status": "ok",
+  "retcode": 0,
+  "data": {
+    "text": "reply text"
+  },
+  "echo": "uuid"
+}
+```
+
+如果 `data.text`、`data.message` 或 `data.reply` 存在，插件会直接把它返回给用户。`data.message` 支持 OneBot 风格的文本段数组。
+
+## 兼容说明
+
+- `token` 是可选项，不填时不会附加 `Authorization` 头
+- `secret` 也是可选项，不填时不会生成 `auth`
+- 如果后端没有返回可显示内容，插件会保持静默
+- 请求超时只会记录警告，不会把命令直接抛成错误
+- 同名指令不建议在多个路由里重复配置