koishi-plugin-msg-router 1.0.2 → 1.3.0

package/lib/index.d.ts

@@ -1,5 +1,11 @@
 import { Context, Schema } from 'koishi';
 export declare const name = "msg-router";
+export interface CommandMappingConfig {
+    enabled: boolean;
+    source: string;
+    target: string;
+    description: string;
+}
 export interface ClientRouteConfig {
     name: string;
     mode: 'client';
@@ -8,6 +14,7 @@ export interface ClientRouteConfig {
     token: string;
     secret: string;
     commands: string[];
+    commandMappings: CommandMappingConfig[];
     action: string;
     timeout: number;
     heartbeatInterval: number;
@@ -23,6 +30,7 @@ export interface ServerRouteConfig {
     token: string;
     secret: string;
     commands: string[];
+    commandMappings: CommandMappingConfig[];
     action: string;
     timeout: number;
     heartbeatInterval: number;
@@ -32,6 +40,11 @@ export interface ServerRouteConfig {
 export type RouteConfig = ClientRouteConfig | ServerRouteConfig;
 export interface Config {
     debug: boolean;
+    enableQQMarkdown: boolean;
+    enableCommandDeclaration: boolean;
+    enableCommandTranslation: boolean;
+    commandDeclarationAction: string;
+    maxDeclaredCommands: number;
     clientRoutes: ClientRouteConfig[];
     serverRoutes: ServerRouteConfig[];
 }

package/lib/index.js

@@ -10,11 +10,17 @@ 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('是否启用这条路由'),
+    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 名称'),
+    commands: koishi_1.Schema.array(koishi_1.Schema.string()).default([]).description('本路由需要接管的 Koishi 指令；未填写的其他指令不受插件影响'),
+    commandMappings: koishi_1.Schema.array(koishi_1.Schema.object({
+        enabled: koishi_1.Schema.boolean().default(true).description('是否启用这条手动映射'),
+        source: koishi_1.Schema.string().required().description('用户侧需要接管的指令名，例如：天气'),
+        target: koishi_1.Schema.string().required().description('发送给后端的目标指令名，例如：weather'),
+        description: koishi_1.Schema.string().default('').description('显示在 Koishi 指令系统中的说明，可留空'),
+    })).role('table').default([]).description('手动指令转译表。映射可以独立于 commands 使用；同名映射会覆盖本路由 commands 中的直通规则'),
+    action: koishi_1.Schema.string().default('msg_router.forward_command').description('兼容配置字段；消息事件当前按 OneBot v11 标准直接推送'),
     timeout: koishi_1.Schema.number().default(10000).description('单次请求超时时间，单位毫秒'),
     heartbeatInterval: koishi_1.Schema.number().default(30000).description('心跳间隔，单位毫秒'),
     reconnectInterval: koishi_1.Schema.number().default(5000).description('断线后重连间隔，单位毫秒'),
@@ -36,16 +42,33 @@ const RouteConfig = koishi_1.Schema.union([
     ServerRouteConfig,
 ]).role('table');
 exports.Config = koishi_1.Schema.object({
-    debug: koishi_1.Schema.boolean().default(false).description('是否输出调试日志'),
+    enableQQMarkdown: koishi_1.Schema.boolean()
+        .default(true)
+        .description('启用 QQ 原生 Markdown 文本。后端可使用 message 中的 markdown 段，或直接声明 params.markdown.content；关闭后按普通文本降级发送'),
+    enableCommandDeclaration: koishi_1.Schema.boolean()
+        .default(false)
+        .description('允许已连接的 OneBot 后端动态声明本路由要拦截的指令。为避免后端意外接管指令，默认关闭'),
+    enableCommandTranslation: koishi_1.Schema.boolean()
+        .default(true)
+        .description('允许声明接口把一个对外指令映射为另一个后端指令；关闭后仍可动态声明，但目标指令固定为原指令'),
+    commandDeclarationAction: koishi_1.Schema.string()
+        .default('msg_router.declare_commands')
+        .description('后端声明指令所调用的 WebSocket action。请求格式：{ action, params: { commands: [{ name: "对外指令", target: "后端指令" }], replace: true }, echo }'),
+    maxDeclaredCommands: koishi_1.Schema.natural()
+        .min(1)
+        .max(1000)
+        .default(100)
+        .description('每条路由最多允许后端动态声明的指令数量'),
+    debug: koishi_1.Schema.boolean().default(false).description('输出 WebSocket 收发内容、指令匹配和消息解析等调试日志'),
     clientRoutes: koishi_1.Schema.array(ClientRouteConfig)
         .role('table')
         .default([])
-        .description('正向 WS 路由列表，插件主动连接后端'),
+        .description('正向 WebSocket 接口：插件主动连接后端，将指定指令转换为 OneBot v11 消息事件；后端可调用 send_msg、send_group_msg、send_private_msg 等动作回发消息'),
     serverRoutes: koishi_1.Schema.array(ServerRouteConfig)
         .role('table')
         .default([])
-        .description('反向 WS 路由列表，插件监听等待后端连接'),
-});
+        .description('反向 WebSocket 接口：插件在指定地址监听，等待后端连接；事件和后端动作格式与 OneBot v11 一致'),
+}).description('仅接管路由中配置或由后端声明的指令，不覆盖其他 Koishi 指令。每条路由可通过 commandMappings 手动设置“对外指令 → 后端指令”，也可调用 msg_router.declare_commands 动态声明。后端回发接口：send_msg、send_group_msg、send_private_msg；管理接口：delete_msg、get_login_info、set_group_ban、set_group_kick、get_group_member_info、get_group_info。');
 function toOneBotId(value) {
     if (value == null)
         return undefined;
@@ -59,6 +82,61 @@ function toOneBotId(value) {
     }
     return undefined;
 }
+function firstMessageId(value) {
+    const first = Array.isArray(value) ? value[0] : value;
+    if (first == null || first === '')
+        return Math.floor(Math.random() * 1000000);
+    if (typeof first === 'number')
+        return first;
+    const numeric = Number(first);
+    return Number.isFinite(numeric) ? numeric : String(first);
+}
+/** Extracts QQ's native Markdown payload without letting generic Satori conversion discard it. */
+function extractQQMarkdown(value) {
+    const segments = Array.isArray(value) ? value : [value];
+    let markdownSource;
+    const remaining = [];
+    for (const item of segments) {
+        if (!item || typeof item !== 'object') {
+            remaining.push(item);
+            continue;
+        }
+        const segment = item;
+        if (segment.type === 'markdown') {
+            const source = segment.data?.markdown ?? segment.data ?? {};
+            markdownSource = typeof source === 'string' ? { content: source } : source;
+        }
+        else if (!Array.isArray(value) && segment.markdown) {
+            markdownSource = typeof segment.markdown === 'string'
+                ? { content: segment.markdown }
+                : segment.markdown;
+        }
+        else {
+            remaining.push(item);
+        }
+    }
+    if (!markdownSource)
+        return;
+    const content = markdownSource.content == null ? undefined : String(markdownSource.content);
+    if (!content)
+        return;
+    const fallback = String(markdownSource.fallback_text
+        ?? markdownSource.fallback
+        ?? markdownSource.prompt
+        ?? content
+        ?? '');
+    return {
+        markdown: { content },
+        fallback,
+        remaining,
+    };
+}
+function resolveOutgoingMessage(params) {
+    if (params?.markdown) {
+        return { markdown: params.markdown };
+    }
+    return params?.message;
+}
 function toElements(value) {
     if (value == null)
         return [];
@@ -106,6 +184,18 @@ function toElements(value) {
         if (segment.type === 'reply') {
             return [(0, koishi_1.h)('quote', { id: segment.data?.id || '' })];
         }
+        if (segment.type === 'markdown') {
+            const source = segment.data?.markdown ?? segment.data ?? {};
+            const fallback = source.fallback_text ?? source.fallback ?? source.prompt ?? source.content;
+            return fallback == null ? [] : [koishi_1.h.text(String(fallback))];
+        }
+        if (segment.type === 'keyboard')
+            return [];
+        if (segment.markdown !== undefined) {
+            const source = segment.markdown ?? {};
+            const fallback = source.fallback_text ?? source.fallback ?? source.prompt ?? source.content;
+            return fallback == null ? [] : [koishi_1.h.text(String(fallback))];
+        }
         if (segment.reply !== undefined)
             return toElements(segment.reply);
         if (segment.message !== undefined)
@@ -160,15 +250,16 @@ function transformElements(elements) {
     }
     return result;
 }
-function buildOneBotMessageEvent(session, commandName, content) {
-    const text = session?.content || (commandName + ' ' + (content ?? '')).trim();
+function buildOneBotMessageEvent(session, commandName, content, translated = false) {
+    const routedText = (commandName + ' ' + (content ?? '')).trim();
+    const text = translated ? routedText : (session?.content || routedText);
     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 elements = translated ? koishi_1.h.parse(text) : (session?.elements || koishi_1.h.parse(text));
     const messageSegments = transformElements(elements);
     return {
         time: Math.floor(Date.now() / 1000),
@@ -192,6 +283,7 @@ class RouteRuntime {
     ctx;
     config;
     route;
+    declareCommands;
     socket = null;
     server = null;
     connecting = null;
@@ -205,10 +297,11 @@ class RouteRuntime {
     lastPong = 0;
     recentGroupSessions = new Map();
     recentPrivateSessions = new Map();
-    constructor(ctx, config, route) {
+    constructor(ctx, config, route, declareCommands) {
         this.ctx = ctx;
         this.config = config;
         this.route = route;
+        this.declareCommands = declareCommands;
     }
     get kind() {
         if (this.route.mode === 'client')
@@ -222,7 +315,10 @@ class RouteRuntime {
     }
     get enabled() {
         const commands = Array.isArray(this.route.commands) ? this.route.commands : [];
-        if (!this.route.enabled || !commands.length)
+        const mappings = Array.isArray(this.route.commandMappings)
+            ? this.route.commandMappings.filter(item => item?.enabled !== false)
+            : [];
+        if (!this.route.enabled || (!commands.length && !mappings.length && !this.config.enableCommandDeclaration))
             return false;
         if (this.kind === 'client')
             return !!('endpoint' in this.route && this.route.endpoint && this.route.endpoint.length > 0);
@@ -266,15 +362,12 @@ class RouteRuntime {
         }
         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'}`);
+    async forward(session, commandName, content = '', sourceCommand = commandName) {
+        this.ctx.logger(exports.name).info(`route ${this.routeLabel} command trigger: source=${sourceCommand} target=${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);
+        const event = buildOneBotMessageEvent(session, commandName, content, sourceCommand !== commandName);
         const isGroup = Boolean(session?.guildId != null
             || (session?.channelId != null && String(session.channelId) !== String(session?.userId ?? '')));
         if (isGroup && session?.channelId) {
@@ -311,6 +404,58 @@ class RouteRuntime {
         };
         push().catch(e => this.ctx.logger(exports.name).warn(e));
     }
+    async sendRoutedMessage(bot, session, targetId, isPrivate, message) {
+        const qq = this.config.enableQQMarkdown !== false ? extractQQMarkdown(message) : undefined;
+        const isQQ = session?.platform === 'qq' || bot?.platform === 'qq';
+        const internal = bot?.internal;
+        const isQQPublicBot = typeof internal?.sendPrivateMessage === 'function';
+        const canSendNative = isQQ && typeof internal?.sendMessage === 'function'
+            && (!isPrivate || isQQPublicBot);
+        if (!qq || !canSendNative) {
+            const elements = qq
+                ? [...(qq.fallback ? [koishi_1.h.text(qq.fallback)] : []), ...toElements(qq.remaining)]
+                : toElements(message);
+            if (!elements.length)
+                return [];
+            return session
+                ? await session.send(elements)
+                : isPrivate
+                    ? await bot.sendPrivateMessage(targetId, elements)
+                    : await bot.sendMessage(targetId, elements);
+        }
+        const recentMessageId = session?.messageId
+            && (!session.timestamp || Date.now() - session.timestamp < 5 * 60 * 1000)
+            ? String(session.messageId)
+            : undefined;
+        const request = isQQPublicBot
+            ? {
+                msg_type: 2,
+                markdown: qq.markdown,
+                ...(recentMessageId ? { msg_id: recentMessageId } : {}),
+            }
+            : {
+                content: ' ',
+                markdown: qq.markdown,
+                ...(recentMessageId ? { msg_id: recentMessageId } : {}),
+            };
+        const response = isPrivate
+            ? await internal.sendPrivateMessage(targetId, request)
+            : await internal.sendMessage(targetId, request);
+        const ids = response?.id ? [response.id] : [];
+        // The Markdown segment forms one native QQ message. Preserve any other
+        // OneBot segments by sending them as a second, ordinary message.
+        const remaining = toElements(qq.remaining);
+        if (remaining.length) {
+            const extra = session
+                ? await session.send(remaining)
+                : isPrivate
+                    ? await bot.sendPrivateMessage(targetId, remaining)
+                    : await bot.sendMessage(targetId, remaining);
+            if (Array.isArray(extra))
+                ids.push(...extra);
+        }
+        return ids;
+    }
     acquireSlot() {
         if (this.inflight < this.route.maxConcurrency) {
             this.inflight += 1;
@@ -466,15 +611,39 @@ class RouteRuntime {
             }
             if (data.action) {
                 const sendResponse = (response) => {
-                    if (data.echo)
+                    if (data.echo !== undefined)
                         response.echo = data.echo;
                     if (socket.readyState === ws_1.default.OPEN) {
                         socket.send(JSON.stringify(response));
                     }
                 };
+                const declarationAction = this.config.commandDeclarationAction || 'msg_router.declare_commands';
+                if (data.action === declarationAction) {
+                    if (!this.config.enableCommandDeclaration) {
+                        return sendResponse({
+                            status: 'failed',
+                            retcode: 103,
+                            msg: 'Dynamic command declaration is disabled',
+                            data: null,
+                        });
+                    }
+                    try {
+                        const result = this.declareCommands(data.params);
+                        this.ctx.logger(exports.name).info(`route ${this.routeLabel} declared=${result.declared.length} removed=${result.removed.length} rejected=${result.rejected.length}`);
+                        return sendResponse({ status: 'ok', retcode: 0, data: result });
+                    }
+                    catch (error) {
+                        return sendResponse({
+                            status: 'failed',
+                            retcode: 100,
+                            msg: error instanceof Error ? error.message : String(error),
+                            data: null,
+                        });
+                    }
+                }
                 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;
+                    const message = resolveOutgoingMessage(data.params);
                     if (userId == null || message == null) {
                         return sendResponse({ status: 'failed', retcode: 100, msg: 'Missing user_id or message', data: null });
                     }
@@ -482,8 +651,8 @@ class RouteRuntime {
                     const session = this.recentPrivateSessions.get(String(userId));
                     if (session && (!data.params?.self_id || session.bot?.selfId === String(data.params?.self_id))) {
                         try {
-                            const msgIds = await session.send(toElements(message));
-                            const msgId = (Array.isArray(msgIds) && msgIds.length > 0) ? (Number(msgIds[0]) || Math.floor(Math.random() * 1000000)) : (typeof msgIds === 'string' ? msgIds : Math.floor(Math.random() * 1000000));
+                            const msgIds = await this.sendRoutedMessage(session.bot ?? bot, session, String(userId), true, message);
+                            const msgId = firstMessageId(msgIds);
                             sendResponse({ status: 'ok', retcode: 0, data: { message_id: msgId } });
                         }
                         catch (e) {
@@ -493,8 +662,8 @@ class RouteRuntime {
                     }
                     else if (bot) {
                         try {
-                            const msgIds = await bot.sendPrivateMessage(String(userId), toElements(message));
-                            const msgId = (Array.isArray(msgIds) && msgIds.length > 0) ? (Number(msgIds[0]) || Math.floor(Math.random() * 1000000)) : (typeof msgIds === 'string' ? msgIds : Math.floor(Math.random() * 1000000));
+                            const msgIds = await this.sendRoutedMessage(bot, null, String(userId), true, message);
+                            const msgId = firstMessageId(msgIds);
                             sendResponse({ status: 'ok', retcode: 0, data: { message_id: msgId } });
                         }
                         catch (e) {
@@ -509,7 +678,7 @@ class RouteRuntime {
                 }
                 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;
+                    const message = resolveOutgoingMessage(data.params);
                     if (groupId == null || message == null) {
                         return sendResponse({ status: 'failed', retcode: 100, msg: 'Missing group_id or message', data: null });
                     }
@@ -517,8 +686,8 @@ class RouteRuntime {
                     const session = this.recentGroupSessions.get(String(groupId));
                     if (session && (!data.params?.self_id || session.bot?.selfId === String(data.params?.self_id))) {
                         try {
-                            const msgIds = await session.send(toElements(message));
-                            const msgId = (Array.isArray(msgIds) && msgIds.length > 0) ? (Number(msgIds[0]) || Math.floor(Math.random() * 1000000)) : (typeof msgIds === 'string' ? msgIds : Math.floor(Math.random() * 1000000));
+                            const msgIds = await this.sendRoutedMessage(session.bot ?? bot, session, String(groupId), false, message);
+                            const msgId = firstMessageId(msgIds);
                             sendResponse({ status: 'ok', retcode: 0, data: { message_id: msgId } });
                         }
                         catch (e) {
@@ -528,8 +697,8 @@ class RouteRuntime {
                     }
                     else if (bot) {
                         try {
-                            const msgIds = await bot.sendMessage(String(groupId), toElements(message));
-                            const msgId = (Array.isArray(msgIds) && msgIds.length > 0) ? (Number(msgIds[0]) || Math.floor(Math.random() * 1000000)) : (typeof msgIds === 'string' ? msgIds : Math.floor(Math.random() * 1000000));
+                            const msgIds = await this.sendRoutedMessage(bot, null, String(groupId), false, message);
+                            const msgId = firstMessageId(msgIds);
                             sendResponse({ status: 'ok', retcode: 0, data: { message_id: msgId } });
                         }
                         catch (e) {
@@ -738,10 +907,128 @@ class RouteRuntime {
 function apply(ctx, config) {
     const logger = ctx.logger(exports.name);
     const runtimes = new Map();
-    const registered = new Set();
+    const registered = new Map();
+    const normalizeCommandName = (value) => String(value ?? '')
+        .trim()
+        .replace(/^\/+/, '')
+        .toLowerCase()
+        .replace(/_/g, '-');
+    const isValidCommandName = (value) => {
+        return !!value && value.length <= 100 && !/[\s[\]<>]/.test(value);
+    };
+    const parseDeclarations = (params) => {
+        const source = params?.commands;
+        if (Array.isArray(source))
+            return source;
+        if (source && typeof source === 'object') {
+            return Object.entries(source).map(([command, target]) => ({ command, target }));
+        }
+        throw new Error('params.commands must be an array or an object map');
+    };
+    const registerCommand = (runtime, sourceName, targetName, dynamic, description) => {
+        const existing = registered.get(sourceName);
+        if (existing) {
+            if (existing.runtime !== runtime)
+                return 'already owned by another msg-router route';
+            existing.target = targetName;
+            return;
+        }
+        if (ctx.$commander.get(sourceName))
+            return 'already registered by another Koishi plugin';
+        const entry = { runtime, target: targetName, dynamic, command: null };
+        const command = ctx.command(`${sourceName} [content:text]`, description || `由 msg-router 动态路由到 ${targetName}`).action(async ({ session }, content) => {
+            if (config.debug) {
+                logger.debug(`command trigger: source=${sourceName} target=${entry.target} content=${JSON.stringify(content ?? '')}`);
+            }
+            await runtime.forward(session, entry.target, content ?? '', sourceName);
+            return undefined;
+        });
+        entry.command = command;
+        registered.set(sourceName, entry);
+    };
+    const declareForRoute = (runtime, params) => {
+        const rejected = [];
+        const declarations = new Map();
+        for (const item of parseDeclarations(params)) {
+            const raw = typeof item === 'string' ? { name: item } : item;
+            if (!raw || typeof raw !== 'object') {
+                rejected.push({ name: String(item ?? ''), reason: 'declaration must be a string or object' });
+                continue;
+            }
+            const declaredName = raw.name ?? raw.command ?? raw.source;
+            const sourceName = normalizeCommandName(declaredName);
+            if (!isValidCommandName(sourceName)) {
+                rejected.push({ name: String(declaredName ?? ''), reason: 'invalid command name' });
+                continue;
+            }
+            const requestedTarget = raw.target ?? raw.target_command ?? raw.to ?? sourceName;
+            const targetName = config.enableCommandTranslation === false
+                ? sourceName
+                : String(requestedTarget ?? '').trim().replace(/^\/+/, '');
+            if (!isValidCommandName(targetName)) {
+                rejected.push({ name: sourceName, reason: 'invalid target command' });
+                continue;
+            }
+            declarations.set(sourceName, {
+                name: sourceName,
+                target: targetName,
+                description: raw.description == null ? undefined : String(raw.description).slice(0, 200),
+                enabled: raw.enabled !== false,
+            });
+        }
+        const limit = Math.max(1, config.maxDeclaredCommands || 100);
+        const resultingDynamic = new Set([...registered]
+            .filter(([, entry]) => entry.runtime === runtime && entry.dynamic)
+            .map(([sourceName]) => sourceName));
+        if (params?.replace !== false)
+            resultingDynamic.clear();
+        for (const item of declarations.values()) {
+            if (item.enabled)
+                resultingDynamic.add(item.name);
+            else
+                resultingDynamic.delete(item.name);
+        }
+        if (resultingDynamic.size > limit) {
+            throw new Error(`too many declared commands: ${resultingDynamic.size}, limit is ${limit}`);
+        }
+        const removed = [];
+        if (params?.replace !== false) {
+            for (const [sourceName, entry] of [...registered]) {
+                if (entry.runtime !== runtime || !entry.dynamic || declarations.has(sourceName))
+                    continue;
+                entry.command.dispose();
+                registered.delete(sourceName);
+                removed.push(sourceName);
+            }
+        }
+        const declared = [];
+        for (const item of declarations.values()) {
+            const existing = registered.get(item.name);
+            if (!item.enabled) {
+                if (existing?.runtime === runtime && existing.dynamic) {
+                    existing.command.dispose();
+                    registered.delete(item.name);
+                    removed.push(item.name);
+                }
+                else if (existing?.runtime === runtime) {
+                    existing.target = item.name;
+                }
+                continue;
+            }
+            const reason = registerCommand(runtime, item.name, item.target, true, item.description);
+            if (reason) {
+                rejected.push({ name: item.name, reason });
+            }
+            else {
+                declared.push({ name: item.name, target: item.target });
+            }
+        }
+        return { declared, removed: [...new Set(removed)], rejected };
+    };
     const routes = [...config.clientRoutes, ...config.serverRoutes];
     for (const route of routes) {
-        const runtime = new RouteRuntime(ctx, config, route);
+        let runtime;
+        runtime = new RouteRuntime(ctx, config, route, params => declareForRoute(runtime, params));
         runtimes.set(route.name, runtime);
         if (!route.enabled)
             continue;
@@ -758,26 +1045,41 @@ function apply(ctx, config) {
                 continue;
             }
         }
-        if (!Array.isArray(route.commands) || !route.commands.length) {
-            logger.warn(`skip route ${route.name}: no commands configured`);
+        const manualMappings = Array.isArray(route.commandMappings)
+            ? route.commandMappings.filter(item => item?.enabled !== false)
+            : [];
+        if ((!Array.isArray(route.commands) || !route.commands.length) && !manualMappings.length && !config.enableCommandDeclaration) {
+            logger.warn(`skip route ${route.name}: no commands or command mappings configured`);
             continue;
         }
-        for (const commandName of route.commands) {
-            const normalized = commandName.trim();
+        for (const commandName of route.commands || []) {
+            const normalized = normalizeCommandName(commandName);
             if (!normalized)
                 continue;
-            if (registered.has(normalized)) {
-                logger.warn(`skip duplicated command ${normalized} from route ${route.name}`);
+            if (!isValidCommandName(normalized)) {
+                logger.warn(`skip invalid command ${JSON.stringify(commandName)} 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;
-            });
+            const reason = registerCommand(runtime, normalized, normalized, false);
+            if (reason)
+                logger.warn(`skip command ${normalized} from route ${route.name}: ${reason}`);
+        }
+        for (const mapping of manualMappings) {
+            const sourceName = normalizeCommandName(mapping.source);
+            const requestedTarget = String(mapping.target ?? '').trim().replace(/^\/+/, '');
+            const targetName = config.enableCommandTranslation === false ? sourceName : requestedTarget;
+            if (!isValidCommandName(sourceName)) {
+                logger.warn(`skip invalid command mapping source ${JSON.stringify(mapping.source)} from route ${route.name}`);
+                continue;
+            }
+            if (!isValidCommandName(targetName)) {
+                logger.warn(`skip invalid command mapping target ${JSON.stringify(mapping.target)} from route ${route.name}`);
+                continue;
+            }
+            const reason = registerCommand(runtime, sourceName, targetName, false, mapping.description);
+            if (reason) {
+                logger.warn(`skip command mapping ${sourceName} -> ${targetName} from route ${route.name}: ${reason}`);
+            }
         }
     }
     ctx.on('ready', () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-msg-router",
-  "description": "OneBot v11 WebSocket 消息转发插件",
-  "version": "1.0.2",
+  "description": "Koishi OneBot 指令路由：支持手动/动态指令转译、双向 WebSocket 与 QQ Markdown",
+  "version": "1.3.0",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [
@@ -19,6 +19,9 @@
     "plugin",
     "onebot",
     "onebot11",
+    "qq",
+    "markdown",
+    "command-mapping",
     "websocket",
     "router"
   ],
@@ -31,8 +34,8 @@
   },
   "koishi": {
     "description": {
-      "zh": "标准 OneBot v11 WebSocket 消息路由与通信中间件",
-      "en": "Standard OneBot v11 WebSocket message routing and communication middleware"
+      "zh": "通过 OneBot 手动或动态声明并转译指定指令，不影响其他指令，支持正反向 WebSocket 和 QQ Markdown",
+      "en": "Manually or dynamically maps selected commands over OneBot, with forward/reverse WebSocket and QQ Markdown"
     }
   }
 }

package/readme.md

@@ -2,22 +2,31 @@
 
 [![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 的 OneBot v11 指令中转路由插件。插件仅接管配置中指定的指令，将会话转换为 OneBot v11 消息事件并通过 WebSocket 交给外部后端处理；未配置的指令保持 Koishi 原有处理流程，不受影响。
+
+后端可以通过标准 OneBot API 动作向群聊或私聊回发文本、图片、语音等消息。针对 QQ 官方适配器，插件还支持原生 Markdown 文本，并在不支持 Markdown 的平台上自动降级为普通文本。
 
 ## 主要用途
 
-- 把某些 Koishi 指令交给外部后端程序处理
-- 支持正向 WS 和反向 WS 两种模式
-- 后端可通过 WebSocket 常驻连接接收请求
-- 支持令牌鉴权，`token` 可留空
-- 支持可选的 HMAC 签名
-- 支持断线重连、心跳保活、超时控制、并发控制
+- **按需接管指令**：每条路由独立配置指令列表，只转发明确指定的指令
+- **手动或动态转译**：可以在配置页维护指令映射，也可以由后端通过接口动态声明
+- **OneBot v11 兼容**：向后端推送标准消息事件，并处理常用 OneBot API 动作
+- **双向 WebSocket**：支持插件主动连接后端，也支持插件监听并等待后端连接
+- **多路由配置**：不同指令可以连接不同后端，分别设置地址、鉴权和连接参数
+- **消息类型转换**：支持文本、图片、@、回复、语音、视频和表情等常用消息段
+- **QQ Markdown**：支持 QQ 原生 Markdown 文本，其他平台自动使用普通文本降级
+- **连接管理**：提供令牌鉴权、心跳检测、断线重连、请求超时和调试日志
 
 ## 控制台配置说明
 
 ### 总开关
 
-- `debug`：是否输出调试信息
+- `enableQQMarkdown`：是否启用 QQ 原生 Markdown 文本；关闭后 Markdown 内容按普通文本降级发送
+- `enableCommandDeclaration`：是否允许后端通过 WebSocket 动态声明要接管的指令，默认关闭
+- `enableCommandTranslation`：是否允许把对外指令转译为不同的后端目标指令
+- `commandDeclarationAction`：动态声明接口的 action，默认 `msg_router.declare_commands`
+- `maxDeclaredCommands`：每条路由最多允许动态声明的指令数量，默认 `100`
+- `debug`：是否输出 WebSocket 收发、指令匹配和消息解析等调试信息
 
 ### 正向 WS 路由列表
 
@@ -30,6 +39,7 @@
 - `token`：后端鉴权令牌，可不填
 - `secret`：HMAC 签名密钥，可不填
 - `commands`：触发这条路由的 Koishi 指令
+- `commandMappings`：手动指令转译表，可设置对外指令、后端目标指令、说明和启用状态
 - `action`：发送给后端的 action 名称
 - `timeout`：单次请求等待时间，单位毫秒
 - `heartbeatInterval`：发送 ping 的间隔，单位毫秒
@@ -48,6 +58,7 @@
 - `token`：后端鉴权令牌，可不填
 - `secret`：HMAC 签名密钥，可不填
 - `commands`：触发这条路由的 Koishi 指令
+- `commandMappings`：手动指令转译表，可独立于 `commands` 使用
 - `action`：发送给后端的 action 名称
 - `timeout`：单次请求等待时间，单位毫秒
 - `heartbeatInterval`：发送 ping 的间隔，单位毫秒
@@ -156,6 +167,103 @@
 
 如果 `data.text`、`data.message` 或 `data.reply` 存在，插件会直接把它返回给用户。`data.message` 支持 OneBot 风格的文本段数组。
 
+### 手动配置指令转译
+
+每条正向或反向路由都提供 `commandMappings` 表格，可以直接在 Koishi 配置页面添加映射：
+
+| 配置项 | 说明 | 示例 |
+| --- | --- | --- |
+| `enabled` | 是否启用这条映射 | `true` |
+| `source` | 用户实际执行、插件需要接管的指令 | `天气` |
+| `target` | 转发给后端的目标指令 | `weather` |
+| `description` | Koishi 指令系统中显示的说明 | `查询天气` |
+
+配置后，用户执行 `天气 上海`，后端会收到 `weather 上海`。映射可以独立使用，不需要再把 `天气` 重复填写到 `commands`；如果两处都填写，`commandMappings` 中的目标指令优先。单条映射可以使用 `enabled` 独立关闭。
+
+全局关闭 `enableCommandTranslation` 后，手动映射和动态声明仍会注册源指令，但不再替换指令名。
+
+### 动态声明与指令转译接口
+
+开启配置项 `enableCommandDeclaration` 后，已连接的后端可以通过 WebSocket 调用声明接口。接口 action 默认为 `msg_router.declare_commands`，也可以通过 `commandDeclarationAction` 修改。
+
+下面的声明会让插件接管用户侧的 `天气` 和 `菜单` 指令。其中，用户执行 `天气 上海` 时，后端收到的消息内容会转译为 `weather 上海`；插件只替换指令名，后续参数保持不变。
+
+```json
+{
+  "action": "msg_router.declare_commands",
+  "params": {
+    "replace": true,
+    "commands": [
+      {
+        "name": "天气",
+        "target": "weather",
+        "description": "查询天气"
+      },
+      {
+        "name": "菜单",
+        "target": "help"
+      }
+    ]
+  },
+  "echo": "declare-1"
+}
+```
+
+成功响应：
+
+```json
+{
+  "status": "ok",
+  "retcode": 0,
+  "data": {
+    "declared": [
+      { "name": "天气", "target": "weather" },
+      { "name": "菜单", "target": "help" }
+    ],
+    "removed": [],
+    "rejected": []
+  },
+  "echo": "declare-1"
+}
+```
+
+接口规则：
+
+- `commands` 可以是上述数组，也可以简写成 `{ "天气": "weather", "菜单": "help" }`
+- 字符串声明（例如 `"ping"`）表示不转译，源指令和目标指令相同
+- `replace` 默认为 `true`，会移除该路由之前动态声明、但本次未再次声明的指令
+- `replace: false` 表示增量更新；单项设置 `enabled: false` 可以移除动态指令
+- 关闭 `enableCommandTranslation` 后仍允许动态声明，但会忽略 `target`，按原指令转发
+- 插件不会覆盖其他 Koishi 插件已经注册的指令，冲突项会出现在 `rejected` 中
+- 只配置动态声明、不填写静态 `commands` 的路由也会启动并等待后端声明
+
+### QQ Markdown 文本
+
+后端通过 `send_group_msg`、`send_private_msg` 或 `send_msg` 回发消息时，可以使用 QQ 原生 Markdown 文本。插件在 QQ 官方适配器上会直接提交 `markdown.content`；在其他平台上会把同一内容作为普通文本降级发送。
+
+此功能可通过配置页面的 `enableQQMarkdown` 开关控制。关闭后不会调用 QQ 原生 Markdown 接口，而是把 `content` 或 `fallback_text` 作为普通消息发送。
+
+```json
+{
+  "action": "send_group_msg",
+  "params": {
+    "group_id": "群 openid",
+    "message": [
+      {
+        "type": "markdown",
+        "data": {
+          "content": "# 标题\n**加粗内容**\n[查看详情](https://example.com)",
+          "fallback_text": "标题\n加粗内容\nhttps://example.com"
+        }
+      }
+    ]
+  },
+  "echo": "request-id"
+}
+```
+
+如果后端本身直接使用 QQ 消息结构，也可以省略 `message`，直接在 `params.markdown.content` 中提供内容。`fallback_text` 可选；未提供时会直接使用 `content` 作为降级文本。
+
 ## 兼容说明
 
 - `token` 是可选项，不填时不会附加 `Authorization` 头