alemonjs 2.1.74 → 2.1.76

package/lib/app/router/dsl.d.ts

@@ -32,6 +32,7 @@ export declare class Router<P extends string = string, E extends string = string
         eventName: string;
         routes: {
             path: string;
+            description: string;
             importerCount: number;
         }[];
     }[];

package/lib/app/router/dsl.js

@@ -53,6 +53,7 @@ function normalizeRouteConfig(config) {
     }
     return {
         path: normalizeRoutePath(path),
+        description: config.description,
         events: config.events,
         platforms: config.platforms,
         schema: config.schema
@@ -68,6 +69,94 @@ function normalizeResConfig(config, defaults) {
 function getImporterLabel(importer, index) {
     return importer.name || `anonymous_${index + 1}`;
 }
+function formatRouteDescription(description) {
+    return typeof description === 'string' && description.trim() ? description.trim() : undefined;
+}
+function formatArgRuleHint(arg, displayIndex) {
+    const rules = arg.rules ?? [];
+    const parts = [];
+    const typeRule = rules.find(rule => rule.type);
+    const requiredRule = rules.find(rule => rule.required);
+    if (requiredRule) {
+        parts.push('必填');
+    }
+    else {
+        parts.push('可选');
+    }
+    if (typeRule?.type === 'number') {
+        parts.push('数字');
+    }
+    else if (typeRule?.type === 'enum') {
+        parts.push(`枚举: ${(typeRule.enum ?? []).join(' / ')}`);
+    }
+    else if (typeRule?.type === 'range') {
+        parts.push('区间');
+    }
+    else if (typeRule?.type === 'rest') {
+        parts.push('剩余文本');
+    }
+    else {
+        parts.push('文本');
+    }
+    if (typeof typeRule?.min === 'number') {
+        parts.push(`最小 ${typeRule.min}`);
+    }
+    if (typeof typeRule?.max === 'number') {
+        parts.push(`最大 ${typeRule.max}`);
+    }
+    const suffix = arg.description ? `，${arg.description}` : '';
+    return `参数${displayIndex} \`${arg.name}\`：${parts.join('，')}${suffix}`;
+}
+function buildSchemaHints(schema) {
+    const args = schema?.args ?? [];
+    if (args.length === 0) {
+        return [];
+    }
+    return args.map((arg, index) => formatArgRuleHint(arg, index + 1));
+}
+function quoteCommand(command) {
+    return command ? `\`${command}\`` : '';
+}
+function buildFallbackReply(params) {
+    const lines = [];
+    const commandText = quoteCommand(params.suggestedKey);
+    if (commandText) {
+        lines.push(`我猜你想用的是 ${commandText}。`);
+        lines.push(`可以直接输入：${commandText}`);
+    }
+    else {
+        lines.push('我还没完全认出你这条指令。');
+    }
+    if (params.description) {
+        lines.push(params.description);
+    }
+    if (params.usage && params.usage !== params.suggestedKey) {
+        lines.push(`如果你想继续，可以这样写：\`${params.usage}\``);
+    }
+    return lines;
+}
+function buildValidationReply(params) {
+    const lines = [];
+    const commandText = quoteCommand(params.commandKey);
+    if (commandText) {
+        lines.push(`我已经识别到你想用的是 ${commandText}。`);
+    }
+    lines.push(params.error || '这条指令的参数还不完整。');
+    if (params.description) {
+        lines.push(params.description);
+    }
+    if (params.usage) {
+        lines.push(`你可以这样输入：\`${params.usage}\``);
+    }
+    else if (commandText) {
+        lines.push(`请继续补全 ${commandText} 所需的参数。`);
+    }
+    if (params.schemaHints && params.schemaHints.length > 0) {
+        lines.push('参数说明：');
+        lines.push(...params.schemaHints);
+    }
+    return lines;
+}
 function normalizeInteractionKey(messageText) {
     return String(messageText ?? '')
         .trim()
@@ -345,6 +434,7 @@ class Router {
             eventName,
             routes: [...routes.two.values(), ...routes.one.values()].map(route => ({
                 path: route.config.path,
+                description: route?.config?.description,
                 importerCount: route.importers.length
             }))
         }));
@@ -542,14 +632,14 @@ class Router {
             return;
         }
         const eventName = String(event.name ?? '');
-        const routeKeys = this.inspect()
+        const routeMetas = this.inspect()
             .filter(item => item.eventName === eventName)
             .flatMap(item => item.routes)
             .filter(route => {
             const routeEntry = this.routes.get(eventName)?.one.get(route.path) ?? this.routes.get(eventName)?.two.get(route.path);
             return routeEntry ? applicableScopeIds.includes(routeEntry.scopeId) : false;
-        })
-            .map(route => route.path);
+        });
+        const routeKeys = routeMetas.map(route => route.path);
         const fallback = checkFallbackHint(typeof event.MessageText === 'string' ? event.MessageText : undefined, routeKeys, fallbackOptions);
         if (!fallback.matched) {
             await next();
@@ -558,7 +648,18 @@ class Router {
         const [message] = useMessage();
         const md = Format.createMarkdown();
         const format = Format.create();
-        md.addText(fallback.message ?? '未匹配到可用指令');
+        const suggestedRoute = fallback.suggestedKey ? routeMetas.find(route => route.path === fallback.suggestedKey) : undefined;
+        const replyLines = buildFallbackReply({
+            suggestedKey: fallback.suggestedKey,
+            description: formatRouteDescription(suggestedRoute?.description),
+            usage: suggestedRoute?.path
+        });
+        replyLines.forEach((line, index) => {
+            if (index > 0) {
+                md.addNewline();
+            }
+            md.addText(line);
+        });
         format.addMarkdown(md);
         void message.send({ format });
     }
@@ -570,15 +671,24 @@ class Router {
         const [message] = useMessage();
         const md = Format.createMarkdown();
         const format = Format.create();
-        md.addText(validation && !validation.valid ? validation.error : '参数校验失败');
-        if (validation && !validation.valid && validation.usage) {
-            md.addNewline();
-            md.addText(`应使用：${validation.usage}`);
-        }
-        else if (result.commandKey) {
-            md.addNewline();
-            md.addText(`请补全 \`${result.commandKey}\` 所需参数。`);
-        }
+        const routeEntry = (result.eventName && result.matchedPath
+            ? (this.routes.get(result.eventName)?.one.get(result.matchedPath) ?? this.routes.get(result.eventName)?.two.get(result.matchedPath))
+            : undefined) ?? undefined;
+        const description = formatRouteDescription(routeEntry?.config.description);
+        const schemaHints = buildSchemaHints(routeEntry?.config.schema);
+        const replyLines = buildValidationReply({
+            error: validation && !validation.valid ? validation.error : '参数校验失败',
+            commandKey: result.commandKey,
+            description,
+            usage: validation && !validation.valid ? validation.usage : undefined,
+            schemaHints
+        });
+        replyLines.forEach((line, index) => {
+            if (index > 0) {
+                md.addNewline();
+            }
+            md.addText(line);
+        });
         format.addMarkdown(md);
         void message.send({ format });
     }

package/lib/app/router/fallback.js

@@ -21,6 +21,12 @@ function levenshteinDistance(a, b) {
 function normalizeForCompare(text) {
     return text.replace(/^([!！/#＃])\s*/, '').trim();
 }
+function shouldCheckCandidate(messageText, candidate) {
+    if (!messageText || !candidate) {
+        return false;
+    }
+    return messageText.startsWith(candidate);
+}
 function getAdaptiveMaxDistance(input) {
     if (input.length <= 2) {
         return 1;
@@ -44,6 +50,10 @@ function checkFallbackHint(messageText, routeKeys, options = {}) {
     if (options.suggest === false) {
         return { matched: false };
     }
+    const normalizedMessage = normalizeForCompare(String(messageText ?? ''));
+    if (!normalizedMessage) {
+        return { matched: false };
+    }
     const parsed = parseMessageText(messageText);
     if (!parsed) {
         return { matched: false };
@@ -60,6 +70,9 @@ function checkFallbackHint(messageText, routeKeys, options = {}) {
     let bestMatch = null;
     for (const routeKey of routeKeys) {
         const normalizedKey = normalizeForCompare(routeKey);
+        if (!shouldCheckCandidate(normalizedMessage, normalizedKey)) {
+            continue;
+        }
         const distance = levenshteinDistance(attemptedKey, normalizedKey);
         if (!bestMatch || distance < bestMatch.distance) {
             bestMatch = {

package/lib/app/router/types.d.ts

@@ -20,6 +20,7 @@ export type RouteNext = () => Promise<void> | undefined;
 export type RouteExecutable = (event: Record<string, unknown>, next: RouteNext) => Promise<boolean | undefined> | boolean | undefined;
 export type RouteHandlerConfig<P extends string = string, E extends string = string> = {
     path?: string;
+    description?: string;
     events?: readonly E[];
     platforms?: readonly P[];
     schema?: RouteSchema;
@@ -52,6 +53,7 @@ export type RouteDefinition<P extends string = string, E extends string = string
 export type RouteDefinitions<P extends string = string, E extends string = string> = RouteDefinition<P, E> | RouteDefinition<P, E>[];
 export type NormalizedRouteConfig<P extends string = string, E extends string = string> = {
     path?: string;
+    description?: string;
     events?: readonly E[];
     platforms?: readonly P[];
     schema?: RouteSchema;

package/lib/app/router/validator.d.ts

@@ -27,6 +27,7 @@ export type RouteRule = {
 };
 export type RouteArgSchema = {
     name: string;
+    description?: string;
     defaultValue?: RouteSchemaValue;
     rules?: RouteRule[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alemonjs",
-  "version": "2.1.74",
+  "version": "2.1.76",
   "description": "bot script",
   "author": "lemonade",
   "license": "MIT",
@@ -72,4 +72,4 @@
     "url": "https://github.com/lemonade-lab/alemonjs.git"
   },
   "gitHead": "c6aa5616afe091a37610dad22fbb2d2618d943b8"
-}
+}