koishi-plugin-msg-router 1.1.0 → 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;
@@ -227,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),
@@ -259,6 +283,7 @@ class RouteRuntime {
     ctx;
     config;
     route;
+    declareCommands;
     socket = null;
     server = null;
     connecting = null;
@@ -272,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')
@@ -289,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);
@@ -333,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) {
@@ -379,7 +405,7 @@ class RouteRuntime {
         push().catch(e => this.ctx.logger(exports.name).warn(e));
     }
     async sendRoutedMessage(bot, session, targetId, isPrivate, message) {
-        const qq = extractQQMarkdown(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';
@@ -585,12 +611,36 @@ 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 = resolveOutgoingMessage(data.params);
@@ -857,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;
@@ -877,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": "Koishi 指令中转路由：仅接管指定指令，通过 OneBot v11 WebSocket 双向通信，支持 QQ Markdown",
-  "version": "1.1.0",
+  "description": "Koishi OneBot 指令路由：支持手动/动态指令转译、双向 WebSocket 与 QQ Markdown",
+  "version": "1.3.0",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [
@@ -21,6 +21,7 @@
     "onebot11",
     "qq",
     "markdown",
+    "command-mapping",
     "websocket",
     "router"
   ],
@@ -33,8 +34,8 @@
   },
   "koishi": {
     "description": {
-      "zh": "仅接管指定指令，通过 OneBot v11 WebSocket 与外部后端双向通信，支持正反向连接和 QQ Markdown",
-      "en": "Routes selected commands to external backends over OneBot v11 WebSocket, with forward/reverse connections and QQ Markdown"
+      "zh": "通过 OneBot 手动或动态声明并转译指定指令，不影响其他指令，支持正反向 WebSocket 和 QQ Markdown",
+      "en": "Manually or dynamically maps selected commands over OneBot, with forward/reverse WebSocket and QQ Markdown"
     }
   }
 }

package/readme.md

@@ -9,6 +9,7 @@
 ## 主要用途
 
 - **按需接管指令**：每条路由独立配置指令列表，只转发明确指定的指令
+- **手动或动态转译**：可以在配置页维护指令映射，也可以由后端通过接口动态声明
 - **OneBot v11 兼容**：向后端推送标准消息事件，并处理常用 OneBot API 动作
 - **双向 WebSocket**：支持插件主动连接后端，也支持插件监听并等待后端连接
 - **多路由配置**：不同指令可以连接不同后端，分别设置地址、鉴权和连接参数
@@ -20,7 +21,12 @@
 
 ### 总开关
 
-- `debug`：是否输出调试信息
+- `enableQQMarkdown`：是否启用 QQ 原生 Markdown 文本；关闭后 Markdown 内容按普通文本降级发送
+- `enableCommandDeclaration`：是否允许后端通过 WebSocket 动态声明要接管的指令，默认关闭
+- `enableCommandTranslation`：是否允许把对外指令转译为不同的后端目标指令
+- `commandDeclarationAction`：动态声明接口的 action，默认 `msg_router.declare_commands`
+- `maxDeclaredCommands`：每条路由最多允许动态声明的指令数量，默认 `100`
+- `debug`：是否输出 WebSocket 收发、指令匹配和消息解析等调试信息
 
 ### 正向 WS 路由列表
 
@@ -33,6 +39,7 @@
 - `token`：后端鉴权令牌，可不填
 - `secret`：HMAC 签名密钥，可不填
 - `commands`：触发这条路由的 Koishi 指令
+- `commandMappings`：手动指令转译表，可设置对外指令、后端目标指令、说明和启用状态
 - `action`：发送给后端的 action 名称
 - `timeout`：单次请求等待时间，单位毫秒
 - `heartbeatInterval`：发送 ping 的间隔，单位毫秒
@@ -51,6 +58,7 @@
 - `token`：后端鉴权令牌，可不填
 - `secret`：HMAC 签名密钥，可不填
 - `commands`：触发这条路由的 Koishi 指令
+- `commandMappings`：手动指令转译表，可独立于 `commands` 使用
 - `action`：发送给后端的 action 名称
 - `timeout`：单次请求等待时间，单位毫秒
 - `heartbeatInterval`：发送 ping 的间隔，单位毫秒
@@ -159,10 +167,82 @@
 
 如果 `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",