@zhin.js/command 1.1.14 → 1.1.16

package/lib/arguments.d.ts

@@ -1,6 +1,6 @@
 import type { CommandDefinition, CommandParams, CommandOptions, CommandParameterValue, CommandSegment, CommandSession } from './definition.js';
 import type { Locale } from '@zhin.js/plugin-runtime';
-export type CommandValidationIssueCode = 'expectedType' | 'expectedArray' | 'minimum' | 'maximum' | 'choices' | 'invalidFormat' | 'invalidValue' | 'unknownOption' | 'duplicateOption' | 'defaultUndefined' | 'parameterUndefined' | 'missingOption' | 'unexpectedArguments' | 'invalidParameter' | 'custom';
+export type CommandValidationIssueCode = 'expectedType' | 'expectedArray' | 'minimum' | 'maximum' | 'choices' | 'invalidFormat' | 'invalidValue' | 'unknownOption' | 'duplicateOption' | 'defaultUndefined' | 'parameterUndefined' | 'missingOption' | 'missingRequiredParam' | 'unexpectedArguments' | 'invalidParameter' | 'custom';
 export interface CommandValidationIssue {
     readonly field: string;
     readonly message: string;

package/lib/arguments.js

@@ -105,7 +105,7 @@ export function requestsCommandHelp(segments) {
             continue;
         if (token.value === '--')
             return false;
-        if (token.value === '--help')
+        if (token.value === '--help' || token.value === '-h')
             return true;
     }
     return false;
@@ -300,7 +300,7 @@ export function parseCommandArguments(definition, remaining, initial, session, l
             else if (schema.default !== undefined)
                 params[name] = typeof schema.default === 'function' ? schema.default(session) : schema.default;
             else if (!schema.optional && !(definition.$parameter?.name === name && definition.$parameter.optional)) {
-                issues.push(commandValidationIssue('expectedType', name, locale, { type: schema.type }));
+                issues.push(commandValidationIssue('missingRequiredParam', name, locale, { type: schema.type }));
             }
         }
         if (Object.hasOwn(params, name) && params[name] === undefined)

package/lib/command-index.d.ts

@@ -1,5 +1,5 @@
 import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot, type Locale } from '@zhin.js/plugin-runtime';
-import type { UserInteractionFactory } from '@zhin.js/interaction';
+import type { UserInteractionFactory } from '@zhin.js/im-contract';
 import { type CapabilityOperationFactory } from '@zhin.js/feature-kit';
 import { type CommandValidationIssue } from './arguments.js';
 import { type CommandMenuEntry, type CommandMenuAppearance } from './command-menu.js';

package/lib/command-index.js

@@ -21,6 +21,7 @@ const segmentFields = {
     dice: 'result',
     rps: 'result',
 };
+const DEFAULT_MENU_KEYWORDS = new Set(['菜单', '帮助', 'help', 'menu']);
 export class CommandIndex {
     snapshot;
     $projection = 'zhin.command-index/1';
@@ -384,10 +385,19 @@ export class CommandIndex {
         const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
         if (text === undefined)
             return undefined;
-        if (text === keyword)
+        const spaceIndex = text.search(/\s/u);
+        const firstToken = spaceIndex === -1 ? text : text.slice(0, spaceIndex);
+        const normalizedFirst = !commandPrefix && firstToken.startsWith('/')
+            ? firstToken.slice(1)
+            : firstToken;
+        const matchedDefaultAlias = this.#menu?.keyword === undefined
+            && DEFAULT_MENU_KEYWORDS.has(normalizedFirst.toLowerCase());
+        if (text === keyword || (matchedDefaultAlias && spaceIndex === -1))
             return this.#buildMenu({}, context);
-        if (text.startsWith(keyword + ' ')) {
-            const key = text.slice(keyword.length + 1).trim();
+        if (text.startsWith(keyword + ' ') || (matchedDefaultAlias && spaceIndex !== -1)) {
+            const key = (text.startsWith(keyword + ' ')
+                ? text.slice(keyword.length + 1)
+                : text.slice(spaceIndex + 1)).trim();
             const args = key.split(/\s+/u);
             const flag = args.indexOf('--page');
             if (flag !== -1) {
@@ -416,17 +426,23 @@ export class CommandIndex {
         const children = node.children
             .map((childId) => snapshot.tree.get(childId))
             .filter((child) => !!child);
-        const pages = Math.max(1, Math.ceil((directCommands.length + children.length) / MENU_PAGE_SIZE));
+        const effectiveCommands = targetId === root
+            && directCommands.length === 0
+            && this.#commands.length > 0
+            && this.#commands.length <= MENU_PAGE_SIZE
+            ? this.#commands
+            : directCommands;
+        const pages = Math.max(1, Math.ceil((effectiveCommands.length + children.length) / MENU_PAGE_SIZE));
         const invocation = `${commandPrefix}${keyword}${pluginKey ? ` ${pluginKey}` : ''}`;
         if (page > pages)
             return { value: commandMessages(locale, 'pageOutOfRange', { pages, command: invocation }) };
         const offset = (page - 1) * MENU_PAGE_SIZE;
-        const pageCommands = directCommands.slice(offset, offset + MENU_PAGE_SIZE);
-        const pageChildren = children.slice(Math.max(0, offset - directCommands.length), Math.max(0, offset + MENU_PAGE_SIZE - directCommands.length));
+        const pageCommands = effectiveCommands.slice(offset, offset + MENU_PAGE_SIZE);
+        const pageChildren = children.slice(Math.max(0, offset - effectiveCommands.length), Math.max(0, offset + MENU_PAGE_SIZE - effectiveCommands.length));
         const displayKey = pluginKey ?? node.instanceKey;
         const lines = [commandMessages(locale, 'menuTitle', { plugin: displayKey })];
         if (pages > 1)
-            lines.push(commandMessages(locale, 'menuSummary', { page, pages, commands: directCommands.length, plugins: children.length }));
+            lines.push(commandMessages(locale, 'menuSummary', { page, pages, commands: effectiveCommands.length, plugins: children.length }));
         if (pageCommands.length > 0) {
             lines.push('');
             for (const cmd of pageCommands) {
@@ -444,7 +460,7 @@ export class CommandIndex {
                 lines.push(`  ${childKey}  (${label})`);
             }
         }
-        if (directCommands.length === 0 && children.length === 0) {
+        if (effectiveCommands.length === 0 && children.length === 0) {
             lines.push('');
             lines.push(commandMessages(locale, 'emptyMenu'));
         }
@@ -471,7 +487,7 @@ export class CommandIndex {
                 name: pluginKey ? `${pluginKey}.${child.instanceKey}` : child.instanceKey,
                 description: child.metadata?.displayName ?? child.instanceKey,
             }))),
-            commandTotal: directCommands.length, pluginTotal: children.length, hint, text,
+            commandTotal: effectiveCommands.length, pluginTotal: children.length, hint, text,
             appearance: Object.freeze(readMenuAppearance(config?.menuStyle)),
         });
         if (!snapshot.resources.get(root)?.has(htmlRendererToken.id))

package/lib/definition.d.ts

@@ -4,7 +4,7 @@
  */
 import { type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import { type CapabilityOperation, type OperationSession, type AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
-import type { UserInteraction } from '@zhin.js/interaction';
+import type { UserInteraction } from '@zhin.js/im-contract';
 import { type CommandExecutionPolicy } from './execution-policy.js';
 export type { CommandExecutionPolicy, CommandExecutionLimit } from './execution-policy.js';
 declare const commandBrand: "zhin.command/1";

package/lib/messages.d.ts

@@ -5,4 +5,4 @@ export declare function commandDescription(value: Readonly<{
     descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
 }>, locale: Locale): string | undefined;
 /** Static dictionaries; the caller supplies the operation's language. */
-export declare const commandMessages: (locale: Locale | undefined, key: "choices" | "defaultValue" | "menuKeyword" | "invalidPage" | "missingPlugin" | "pageOutOfRange" | "menuTitle" | "menuSummary" | "childPlugins" | "emptyMenu" | "pluginHint" | "previousPage" | "nextPage" | "guideTitle" | "guideSubtitle" | "commandCount" | "pluginCount" | "commandIndex" | "pluginIndex" | "guideEmpty" | "helpHint" | "genericHelpHint" | "expectedType" | "expectedArray" | "minimum" | "maximum" | "invalidFormat" | "invalidValue" | "unknownOption" | "duplicateOption" | "defaultUndefined" | "parameterUndefined" | "missingOption" | "unexpectedArguments" | "invalidParameter" | "dynamicValue" | "noAdapter" | "missingEndpoint" | "adapterComparison" | "conditionMismatch" | "missingPermissionHost" | "missingEvidence" | "noPermit" | "uncheckedConditions" | "conditionsMatch" | "unconstrained" | "simulatedIdentity" | "unevaluatedCode" | "defaultedRole", values?: import("@zhin.js/plugin-runtime").MessageValues) => string;
+export declare const commandMessages: (locale: Locale | undefined, key: "choices" | "defaultValue" | "menuKeyword" | "invalidPage" | "missingPlugin" | "pageOutOfRange" | "menuTitle" | "menuSummary" | "childPlugins" | "emptyMenu" | "pluginHint" | "previousPage" | "nextPage" | "guideTitle" | "guideSubtitle" | "commandCount" | "pluginCount" | "commandIndex" | "pluginIndex" | "guideEmpty" | "helpHint" | "genericHelpHint" | "expectedType" | "expectedArray" | "minimum" | "maximum" | "invalidFormat" | "invalidValue" | "unknownOption" | "duplicateOption" | "defaultUndefined" | "parameterUndefined" | "missingOption" | "missingRequiredParam" | "unexpectedArguments" | "invalidParameter" | "dynamicValue" | "noAdapter" | "missingEndpoint" | "adapterComparison" | "conditionMismatch" | "missingPermissionHost" | "missingEvidence" | "noPermit" | "uncheckedConditions" | "conditionsMatch" | "unconstrained" | "simulatedIdentity" | "unevaluatedCode" | "defaultedRole", values?: import("@zhin.js/plugin-runtime").MessageValues) => string;

package/lib/messages.js

@@ -37,6 +37,7 @@ export const commandMessages = createMessages({
     defaultUndefined: { 'zh-CN': '{field}：默认值返回了 undefined', en: '{field}: default returned undefined' },
     parameterUndefined: { 'zh-CN': '{field}：默认值或快捷指令返回了 undefined', en: '{field}: default or shortcut returned undefined' },
     missingOption: { 'zh-CN': '缺少选项 --{field}', en: 'Missing option --{field}' },
+    missingRequiredParam: { 'zh-CN': '缺少必填参数 {field}（类型：{type}）', en: 'Missing required parameter {field} (expected {type})' },
     unexpectedArguments: { 'zh-CN': '存在多余参数', en: 'Unexpected arguments' },
     invalidParameter: { 'zh-CN': '缺少指令参数或参数不正确', en: 'Missing or invalid command parameter' },
     defaultValue: { 'zh-CN': '默认值：{value}', en: 'default: {value}' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -21,10 +21,10 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.1.12",
-    "@zhin.js/interaction": "1.1.2",
-    "@zhin.js/permission": "1.1.12",
-    "@zhin.js/plugin-runtime": "1.1.20"
+    "@zhin.js/feature-kit": "1.1.14",
+    "@zhin.js/im-contract": "1.1.13",
+    "@zhin.js/permission": "1.1.14",
+    "@zhin.js/plugin-runtime": "1.1.22"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/arguments.ts

@@ -7,7 +7,7 @@ import { commandDescription, commandMessages } from './messages.js';
 
 export type CommandValidationIssueCode = 'expectedType' | 'expectedArray' | 'minimum' | 'maximum'
   | 'choices' | 'invalidFormat' | 'invalidValue' | 'unknownOption' | 'duplicateOption'
-  | 'defaultUndefined' | 'parameterUndefined' | 'missingOption' | 'unexpectedArguments'
+  | 'defaultUndefined' | 'parameterUndefined' | 'missingOption' | 'missingRequiredParam' | 'unexpectedArguments'
   | 'invalidParameter' | 'custom';
 
 export interface CommandValidationIssue {
@@ -136,7 +136,7 @@ export function requestsCommandHelp(segments: readonly Readonly<CommandSegment>[
   for (const token of tokenize(segments)) {
     if (!isTextToken(token) || token.quoted) continue;
     if (token.value === '--') return false;
-    if (token.value === '--help') return true;
+    if (token.value === '--help' || token.value === '-h') return true;
   }
   return false;
 }
@@ -280,7 +280,7 @@ export function parseCommandArguments(
       if (value !== undefined) params[name] = value;
       else if (schema.default !== undefined) params[name] = typeof schema.default === 'function' ? schema.default(session) : schema.default;
       else if (!schema.optional && !(definition.$parameter?.name === name && definition.$parameter.optional)) {
-        issues.push(commandValidationIssue('expectedType', name, locale, { type: schema.type }));
+        issues.push(commandValidationIssue('missingRequiredParam', name, locale, { type: schema.type }));
       }
     }
     if (Object.hasOwn(params, name) && params[name] === undefined) issues.push(commandValidationIssue('parameterUndefined', name, locale));

package/src/command-index.ts

@@ -12,7 +12,7 @@ import {
   type RuntimeSnapshot,
   type Locale,
 } from '@zhin.js/plugin-runtime';
-import type { UserInteractionFactory } from '@zhin.js/interaction';
+import type { UserInteractionFactory } from '@zhin.js/im-contract';
 import { bindOperationInput, type CapabilityOperationFactory } from '@zhin.js/feature-kit';
 import {
   permissionHostToken,
@@ -162,6 +162,8 @@ export interface CommandMenuConfig {
   readonly keyword?: string;
 }
 
+const DEFAULT_MENU_KEYWORDS = new Set(['菜单', '帮助', 'help', 'menu']);
+
 export class CommandIndex {
   readonly $projection = 'zhin.command-index/1' as const;
   readonly #commands: readonly CommandRecord[];
@@ -523,9 +525,18 @@ export class CommandIndex {
     const { commandPrefix, keyword, locale } = context;
     const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
     if (text === undefined) return undefined;
-    if (text === keyword) return this.#buildMenu({}, context);
-    if (text.startsWith(keyword + ' ')) {
-      const key = text.slice(keyword.length + 1).trim();
+    const spaceIndex = text.search(/\s/u);
+    const firstToken = spaceIndex === -1 ? text : text.slice(0, spaceIndex);
+    const normalizedFirst = !commandPrefix && firstToken.startsWith('/')
+      ? firstToken.slice(1)
+      : firstToken;
+    const matchedDefaultAlias = this.#menu?.keyword === undefined
+      && DEFAULT_MENU_KEYWORDS.has(normalizedFirst.toLowerCase());
+    if (text === keyword || (matchedDefaultAlias && spaceIndex === -1)) return this.#buildMenu({}, context);
+    if (text.startsWith(keyword + ' ') || (matchedDefaultAlias && spaceIndex !== -1)) {
+      const key = (text.startsWith(keyword + ' ')
+        ? text.slice(keyword.length + 1)
+        : text.slice(spaceIndex + 1)).trim();
       const args = key.split(/\s+/u);
       const flag = args.indexOf('--page');
       if (flag !== -1) {
@@ -555,17 +566,23 @@ export class CommandIndex {
     const children = node.children
       .map((childId) => snapshot.tree.get(childId))
       .filter((child): child is NonNullable<typeof child> => !!child);
-
-    const pages = Math.max(1, Math.ceil((directCommands.length + children.length) / MENU_PAGE_SIZE));
+    const effectiveCommands = targetId === root
+      && directCommands.length === 0
+      && this.#commands.length > 0
+      && this.#commands.length <= MENU_PAGE_SIZE
+      ? this.#commands
+      : directCommands;
+
+    const pages = Math.max(1, Math.ceil((effectiveCommands.length + children.length) / MENU_PAGE_SIZE));
     const invocation = `${commandPrefix}${keyword}${pluginKey ? ` ${pluginKey}` : ''}`;
     if (page > pages) return { value: commandMessages(locale, 'pageOutOfRange', { pages, command: invocation }) };
     const offset = (page - 1) * MENU_PAGE_SIZE;
-    const pageCommands = directCommands.slice(offset, offset + MENU_PAGE_SIZE);
-    const pageChildren = children.slice(Math.max(0, offset - directCommands.length), Math.max(0, offset + MENU_PAGE_SIZE - directCommands.length));
+    const pageCommands = effectiveCommands.slice(offset, offset + MENU_PAGE_SIZE);
+    const pageChildren = children.slice(Math.max(0, offset - effectiveCommands.length), Math.max(0, offset + MENU_PAGE_SIZE - effectiveCommands.length));
 
     const displayKey = pluginKey ?? node.instanceKey;
     const lines: string[] = [commandMessages(locale, 'menuTitle', { plugin: displayKey })];
-    if (pages > 1) lines.push(commandMessages(locale, 'menuSummary', { page, pages, commands: directCommands.length, plugins: children.length }));
+    if (pages > 1) lines.push(commandMessages(locale, 'menuSummary', { page, pages, commands: effectiveCommands.length, plugins: children.length }));
 
     if (pageCommands.length > 0) {
       lines.push('');
@@ -586,7 +603,7 @@ export class CommandIndex {
       }
     }
 
-    if (directCommands.length === 0 && children.length === 0) {
+    if (effectiveCommands.length === 0 && children.length === 0) {
       lines.push('');
       lines.push(commandMessages(locale, 'emptyMenu'));
     }
@@ -612,7 +629,7 @@ export class CommandIndex {
         name: pluginKey ? `${pluginKey}.${child.instanceKey}` : child.instanceKey,
         description: child.metadata?.displayName ?? child.instanceKey,
       }))),
-      commandTotal: directCommands.length, pluginTotal: children.length, hint, text,
+      commandTotal: effectiveCommands.length, pluginTotal: children.length, hint, text,
       appearance: Object.freeze(readMenuAppearance(config?.menuStyle)),
     });
     if (!snapshot.resources.get(root)?.has(htmlRendererToken.id)) return { value: text, menu };

package/src/definition.ts

@@ -16,7 +16,7 @@ import {
 } from '@zhin.js/feature-kit';
 import { assertPermitSyntax } from '@zhin.js/permission';
 import { validateArgumentSchemas } from './arguments.js';
-import type { UserInteraction } from '@zhin.js/interaction';
+import type { UserInteraction } from '@zhin.js/im-contract';
 import { normalizeExecutionPolicy, type CommandExecutionPolicy } from './execution-policy.js';
 export type { CommandExecutionPolicy, CommandExecutionLimit } from './execution-policy.js';
 

package/src/messages.ts

@@ -42,6 +42,7 @@ export const commandMessages = createMessages({
   defaultUndefined: { 'zh-CN': '{field}：默认值返回了 undefined', en: '{field}: default returned undefined' },
   parameterUndefined: { 'zh-CN': '{field}：默认值或快捷指令返回了 undefined', en: '{field}: default or shortcut returned undefined' },
   missingOption: { 'zh-CN': '缺少选项 --{field}', en: 'Missing option --{field}' },
+  missingRequiredParam: { 'zh-CN': '缺少必填参数 {field}（类型：{type}）', en: 'Missing required parameter {field} (expected {type})' },
   unexpectedArguments: { 'zh-CN': '存在多余参数', en: 'Unexpected arguments' },
   invalidParameter: { 'zh-CN': '缺少指令参数或参数不正确', en: 'Missing or invalid command parameter' },
   defaultValue: { 'zh-CN': '默认值：{value}', en: 'default: {value}' },