koishi-plugin-msg-router 1.3.0 → 1.4.0

package/lib/index.d.ts

@@ -1,10 +1,25 @@
 import { Context, Schema } from 'koishi';
 export declare const name = "msg-router";
+export type CommandScope = 'all' | 'group' | 'private';
+export interface CommandAccessConfig {
+    permissions: string[];
+    hidden: boolean;
+    maxUsage: number;
+    minInterval: number;
+    scope: CommandScope;
+    platforms: string[];
+}
 export interface CommandMappingConfig {
     enabled: boolean;
     source: string;
     target: string;
     description: string;
+    permissions: string[];
+    hidden: boolean;
+    maxUsage: number;
+    minInterval: number;
+    scope: CommandScope;
+    platforms: string[];
 }
 export interface ClientRouteConfig {
     name: string;
@@ -45,6 +60,8 @@ export interface Config {
     enableCommandTranslation: boolean;
     commandDeclarationAction: string;
     maxDeclaredCommands: number;
+    allowDynamicCommandPermissions: boolean;
+    minimumDynamicAuthority: number;
     clientRoutes: ClientRouteConfig[];
     serverRoutes: ServerRouteConfig[];
 }

package/lib/index.js

@@ -19,6 +19,16 @@ const CommonRouteConfig = {
         source: koishi_1.Schema.string().required().description('用户侧需要接管的指令名，例如：天气'),
         target: koishi_1.Schema.string().required().description('发送给后端的目标指令名，例如：weather'),
         description: koishi_1.Schema.string().default('').description('显示在 Koishi 指令系统中的说明，可留空'),
+        permissions: koishi_1.Schema.array(koishi_1.Schema.string()).role('perms').default(['authority:1']).description('Koishi 原生权限规则，例如 authority:3'),
+        hidden: koishi_1.Schema.boolean().default(false).description('是否在帮助菜单中隐藏，需要启用 help 插件'),
+        maxUsage: koishi_1.Schema.natural().default(0).description('每名用户每天最多调用次数，0 表示不限；需要 rate-limit 和数据库'),
+        minInterval: koishi_1.Schema.natural().default(0).description('同一用户连续调用的最小间隔，单位毫秒；0 表示不限'),
+        scope: koishi_1.Schema.union([
+            koishi_1.Schema.const('all').description('群聊和私聊'),
+            koishi_1.Schema.const('group').description('仅群聊'),
+            koishi_1.Schema.const('private').description('仅私聊'),
+        ]).default('all').description('指令可用的会话范围'),
+        platforms: koishi_1.Schema.array(koishi_1.Schema.string()).default([]).description('允许使用的平台列表，例如 qq；留空表示不限制'),
     })).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('单次请求超时时间，单位毫秒'),
@@ -59,6 +69,14 @@ exports.Config = koishi_1.Schema.object({
         .max(1000)
         .default(100)
         .description('每条路由最多允许后端动态声明的指令数量'),
+    allowDynamicCommandPermissions: koishi_1.Schema.boolean()
+        .default(false)
+        .description('允许后端声明 permissions 权限规则。关闭时动态指令统一使用 minimumDynamicAuthority，避免后端意外开放敏感指令'),
+    minimumDynamicAuthority: koishi_1.Schema.natural()
+        .min(0)
+        .max(4)
+        .default(1)
+        .description('动态指令允许的最低权限等级；后端声明低于此等级的 authority 权限时会拒绝该指令'),
     debug: koishi_1.Schema.boolean().default(false).description('输出 WebSocket 收发内容、指令匹配和消息解析等调试日志'),
     clientRoutes: koishi_1.Schema.array(ClientRouteConfig)
         .role('table')
@@ -908,6 +926,14 @@ function apply(ctx, config) {
     const logger = ctx.logger(exports.name);
     const runtimes = new Map();
     const registered = new Map();
+    const defaultCommandOptions = () => ({
+        permissions: ['authority:1'],
+        hidden: false,
+        maxUsage: 0,
+        minInterval: 0,
+        scope: 'all',
+        platforms: [],
+    });
     const normalizeCommandName = (value) => String(value ?? '')
         .trim()
         .replace(/^\/+/, '')
@@ -916,6 +942,59 @@ function apply(ctx, config) {
     const isValidCommandName = (value) => {
         return !!value && value.length <= 100 && !/[\s[\]<>]/.test(value);
     };
+    const normalizeCommandOptions = (raw, dynamic) => {
+        const minimumAuthority = Math.min(4, Math.max(0, config.minimumDynamicAuthority ?? 1));
+        let permissions = Array.isArray(raw?.permissions)
+            ? raw.permissions.map(String).map(item => item.trim()).filter(Boolean).slice(0, 20)
+            : [];
+        if (dynamic && !config.allowDynamicCommandPermissions) {
+            permissions = [`authority:${minimumAuthority}`];
+        }
+        else if (!permissions.length) {
+            permissions = [dynamic ? `authority:${minimumAuthority}` : 'authority:1'];
+        }
+        if (dynamic) {
+            let hasAuthorityPermission = false;
+            for (const permission of permissions) {
+                const match = /^authority:(\d+)$/.exec(permission);
+                if (match) {
+                    hasAuthorityPermission = true;
+                    if (Number(match[1]) < minimumAuthority) {
+                        throw new Error(`permission ${permission} is below minimum authority:${minimumAuthority}`);
+                    }
+                }
+            }
+            if (!hasAuthorityPermission)
+                permissions.push(`authority:${minimumAuthority}`);
+        }
+        const requestedScope = String(raw?.scope ?? 'all');
+        const scope = requestedScope === 'group' || requestedScope === 'private'
+            ? requestedScope
+            : 'all';
+        const platforms = Array.isArray(raw?.platforms)
+            ? [...new Set(raw.platforms.map((item) => String(item).trim().toLowerCase()).filter(Boolean))].slice(0, 20)
+            : [];
+        return {
+            permissions,
+            hidden: raw?.hidden === true,
+            maxUsage: Math.min(1_000_000, Math.max(0, Math.floor(Number(raw?.maxUsage) || 0))),
+            minInterval: Math.min(86_400_000, Math.max(0, Math.floor(Number(raw?.minInterval) || 0))),
+            scope,
+            platforms,
+        };
+    };
+    const matchesCommandOptions = (session, options) => {
+        if (options.platforms.length && !options.platforms.includes(String(session?.platform ?? '').toLowerCase()))
+            return false;
+        const isPrivate = session?.isDirect === true || (session?.guildId == null
+            && session?.channelId != null
+            && String(session.channelId) === String(session?.userId ?? ''));
+        if (options.scope === 'private' && !isPrivate)
+            return false;
+        if (options.scope === 'group' && isPrivate)
+            return false;
+        return true;
+    };
     const parseDeclarations = (params) => {
         const source = params?.commands;
         if (Array.isArray(source))
@@ -925,18 +1004,45 @@ function apply(ctx, config) {
         }
         throw new Error('params.commands must be an array or an object map');
     };
-    const registerCommand = (runtime, sourceName, targetName, dynamic, description) => {
+    const registerCommand = (runtime, sourceName, targetName, dynamic, description, options = defaultCommandOptions()) => {
         const existing = registered.get(sourceName);
         if (existing) {
             if (existing.runtime !== runtime)
                 return 'already owned by another msg-router route';
+            if (!dynamic) {
+                existing.dynamic = false;
+                existing.baseTarget = targetName;
+                existing.baseOptions = options;
+            }
             existing.target = targetName;
+            existing.options = options;
+            Object.assign(existing.command.config, {
+                permissions: options.permissions,
+                hidden: options.hidden,
+                maxUsage: options.maxUsage,
+                minInterval: options.minInterval,
+            });
+            ctx.emit('command-updated', existing.command);
             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) => {
+        const entry = {
+            runtime,
+            target: targetName,
+            dynamic,
+            command: null,
+            options,
+            baseTarget: targetName,
+            baseOptions: options,
+        };
+        const commandCtx = ctx.intersect(session => matchesCommandOptions(session, entry.options));
+        const command = commandCtx.command(`${sourceName} [content:text]`, description || `由 msg-router 动态路由到 ${targetName}`, {
+            permissions: options.permissions,
+            hidden: options.hidden,
+            maxUsage: options.maxUsage,
+            minInterval: options.minInterval,
+        }).action(async ({ session }, content) => {
             if (config.debug) {
                 logger.debug(`command trigger: source=${sourceName} target=${entry.target} content=${JSON.stringify(content ?? '')}`);
             }
@@ -969,12 +1075,21 @@ function apply(ctx, config) {
                 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,
-            });
+            try {
+                declarations.set(sourceName, {
+                    name: sourceName,
+                    target: targetName,
+                    description: raw.description == null ? undefined : String(raw.description).slice(0, 200),
+                    enabled: raw.enabled !== false,
+                    options: normalizeCommandOptions(raw, true),
+                });
+            }
+            catch (error) {
+                rejected.push({
+                    name: sourceName,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
         }
         const limit = Math.max(1, config.maxDeclaredCommands || 100);
         const resultingDynamic = new Set([...registered]
@@ -994,11 +1109,24 @@ function apply(ctx, config) {
         const removed = [];
         if (params?.replace !== false) {
             for (const [sourceName, entry] of [...registered]) {
-                if (entry.runtime !== runtime || !entry.dynamic || declarations.has(sourceName))
+                if (entry.runtime !== runtime || declarations.has(sourceName))
                     continue;
-                entry.command.dispose();
-                registered.delete(sourceName);
-                removed.push(sourceName);
+                if (entry.dynamic) {
+                    entry.command.dispose();
+                    registered.delete(sourceName);
+                    removed.push(sourceName);
+                }
+                else {
+                    entry.target = entry.baseTarget;
+                    entry.options = entry.baseOptions;
+                    Object.assign(entry.command.config, {
+                        permissions: entry.options.permissions,
+                        hidden: entry.options.hidden,
+                        maxUsage: entry.options.maxUsage,
+                        minInterval: entry.options.minInterval,
+                    });
+                    ctx.emit('command-updated', entry.command);
+                }
             }
         }
         const declared = [];
@@ -1011,11 +1139,19 @@ function apply(ctx, config) {
                     removed.push(item.name);
                 }
                 else if (existing?.runtime === runtime) {
-                    existing.target = item.name;
+                    existing.target = existing.baseTarget;
+                    existing.options = existing.baseOptions;
+                    Object.assign(existing.command.config, {
+                        permissions: existing.options.permissions,
+                        hidden: existing.options.hidden,
+                        maxUsage: existing.options.maxUsage,
+                        minInterval: existing.options.minInterval,
+                    });
+                    ctx.emit('command-updated', existing.command);
                 }
                 continue;
             }
-            const reason = registerCommand(runtime, item.name, item.target, true, item.description);
+            const reason = registerCommand(runtime, item.name, item.target, true, item.description, item.options);
             if (reason) {
                 rejected.push({ name: item.name, reason });
             }
@@ -1076,7 +1212,7 @@ function apply(ctx, config) {
                 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);
+            const reason = registerCommand(runtime, sourceName, targetName, false, mapping.description, normalizeCommandOptions(mapping, false));
             if (reason) {
                 logger.warn(`skip command mapping ${sourceName} -> ${targetName} from route ${route.name}: ${reason}`);
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-msg-router",
-  "description": "Koishi OneBot 指令路由：支持手动/动态指令转译、双向 WebSocket 与 QQ Markdown",
-  "version": "1.3.0",
+  "description": "Koishi OneBot 指令路由：支持手动/动态转译、权限与频率控制、双向 WebSocket 和 QQ Markdown",
+  "version": "1.4.0",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [
@@ -34,8 +34,8 @@
   },
   "koishi": {
     "description": {
-      "zh": "通过 OneBot 手动或动态声明并转译指定指令，不影响其他指令，支持正反向 WebSocket 和 QQ Markdown",
-      "en": "Manually or dynamically maps selected commands over OneBot, with forward/reverse WebSocket and QQ Markdown"
+      "zh": "通过 OneBot 手动或动态声明并转译指定指令，可限制权限、频率、会话及平台，不影响其他指令，支持正反向 WebSocket 和 QQ Markdown",
+      "en": "Maps selected commands over OneBot with access controls, forward/reverse WebSocket, and QQ Markdown"
     }
   }
 }

package/readme.md

@@ -10,6 +10,7 @@
 
 - **按需接管指令**：每条路由独立配置指令列表，只转发明确指定的指令
 - **手动或动态转译**：可以在配置页维护指令映射，也可以由后端通过接口动态声明
+- **Koishi 指令控制**：映射可配置权限、帮助菜单隐藏、调用频率、群聊/私聊范围和平台限制
 - **OneBot v11 兼容**：向后端推送标准消息事件，并处理常用 OneBot API 动作
 - **双向 WebSocket**：支持插件主动连接后端，也支持插件监听并等待后端连接
 - **多路由配置**：不同指令可以连接不同后端，分别设置地址、鉴权和连接参数
@@ -26,6 +27,8 @@
 - `enableCommandTranslation`：是否允许把对外指令转译为不同的后端目标指令
 - `commandDeclarationAction`：动态声明接口的 action，默认 `msg_router.declare_commands`
 - `maxDeclaredCommands`：每条路由最多允许动态声明的指令数量，默认 `100`
+- `allowDynamicCommandPermissions`：是否允许后端自行声明权限规则，默认关闭
+- `minimumDynamicAuthority`：动态指令的最低权限等级，默认 `1`；后端不得声明更低的 `authority` 权限
 - `debug`：是否输出 WebSocket 收发、指令匹配和消息解析等调试信息
 
 ### 正向 WS 路由列表
@@ -177,10 +180,16 @@
 | `source` | 用户实际执行、插件需要接管的指令 | `天气` |
 | `target` | 转发给后端的目标指令 | `weather` |
 | `description` | Koishi 指令系统中显示的说明 | `查询天气` |
+| `permissions` | Koishi 权限规则 | `["authority:2"]` |
+| `hidden` | 是否从帮助菜单隐藏 | `false` |
+| `maxUsage` | 每名用户每天最多调用次数，`0` 不限制 | `20` |
+| `minInterval` | 同一用户连续调用的最小间隔（毫秒），`0` 不限制 | `3000` |
+| `scope` | `all`、`group` 或 `private` | `group` |
+| `platforms` | 允许的平台；空数组不限制 | `["qq"]` |
 
 配置后，用户执行 `天气 上海`，后端会收到 `weather 上海`。映射可以独立使用，不需要再把 `天气` 重复填写到 `commands`；如果两处都填写，`commandMappings` 中的目标指令优先。单条映射可以使用 `enabled` 独立关闭。
 
-全局关闭 `enableCommandTranslation` 后，手动映射和动态声明仍会注册源指令，但不再替换指令名。
+全局关闭 `enableCommandTranslation` 后，手动映射和动态声明仍会注册源指令，但不再替换指令名。`permissions` 使用 Koishi 原生权限服务；`hidden` 需要 help 插件，`maxUsage` 和 `minInterval` 需要 rate-limit 插件及数据库服务才能生效。
 
 ### 动态声明与指令转译接口
 
@@ -197,7 +206,13 @@
       {
         "name": "天气",
         "target": "weather",
-        "description": "查询天气"
+        "description": "查询天气",
+        "permissions": ["authority:2"],
+        "hidden": false,
+        "maxUsage": 20,
+        "minInterval": 3000,
+        "scope": "group",
+        "platforms": ["qq"]
       },
       {
         "name": "菜单",
@@ -233,6 +248,9 @@
 - 字符串声明（例如 `"ping"`）表示不转译，源指令和目标指令相同
 - `replace` 默认为 `true`，会移除该路由之前动态声明、但本次未再次声明的指令
 - `replace: false` 表示增量更新；单项设置 `enabled: false` 可以移除动态指令
+- 动态声明支持与手动映射相同的 `permissions`、`hidden`、`maxUsage`、`minInterval`、`scope` 和 `platforms`
+- 默认不允许后端决定权限，动态指令统一采用 `minimumDynamicAuthority`；只有显式开启 `allowDynamicCommandPermissions` 后才读取后端提交的 `permissions`
+- 即使允许动态权限，低于 `minimumDynamicAuthority` 的 `authority` 规则仍会被拒绝；只声明自定义权限时，插件也会自动附加最低 `authority` 规则
 - 关闭 `enableCommandTranslation` 后仍允许动态声明，但会忽略 `target`，按原指令转发
 - 插件不会覆盖其他 Koishi 插件已经注册的指令，冲突项会出现在 `rejected` 中
 - 只配置动态声明、不填写静态 `commands` 的路由也会启动并等待后端声明