@zhin.js/command 1.1.13 → 1.1.15

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,6 @@
 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 CapabilityOperationFactory } from '@zhin.js/feature-kit';
 import { type CommandValidationIssue } from './arguments.js';
 import { type CommandMenuEntry, type CommandMenuAppearance } from './command-menu.js';
 export type { CommandMenuEntry, CommandMenuAppearance } from './command-menu.js';
@@ -32,6 +33,7 @@ export interface CommandDispatchRequest {
     readonly interactionFactory?: UserInteractionFactory;
     readonly commandPrefix?: string;
     readonly snapshot?: RuntimeSnapshot;
+    readonly operation?: CapabilityOperationFactory;
     readonly locale?: Locale;
 }
 export interface CommandDispatchResult {
@@ -81,7 +83,7 @@ export declare class CommandIndex {
     formatMenu(prefix: string | undefined, locale: Locale): string | undefined;
     has(name: string): boolean;
     execute(name: string, args?: readonly string[], operationSnapshot?: RuntimeSnapshot): Promise<unknown>;
-    dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot, locale: localeOverride }: CommandDispatchRequest): Promise<CommandDispatchResult>;
+    dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot, locale: localeOverride, operation: operationFactory }: CommandDispatchRequest): Promise<CommandDispatchResult>;
 }
 export declare function isCommandIndex(value: unknown): value is CommandIndex;
 /**

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';
@@ -195,7 +196,7 @@ export class CommandIndex {
             admission.release();
         }
     }
-    async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot, locale: localeOverride }) {
+    async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot, locale: localeOverride, operation: operationFactory }) {
         const locale = localeOverride ?? commandLocale(source, operationSnapshot);
         const prefix = commandPrefix ?? '';
         if (this.#menu) {
@@ -247,12 +248,22 @@ export class CommandIndex {
         const limit = admitCommandExecution(authorSource, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
         if (limit)
             return Object.freeze({ matched: true, status: 'limited', command: match.command.name, owner: match.command.slot.owner, limit });
-        const value = await definition.execute(createCommandContext({
-            snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
-            interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
-            presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath, source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
-        }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
-        return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+        const operation = operationFactory?.create({ owner: match.command.slot.owner, signal: operationFactory.signal });
+        try {
+            const value = await definition.execute(createCommandContext({
+                snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
+                operation,
+                interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
+                presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath, source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
+            }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
+            return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+        }
+        finally {
+            try {
+                await operation?.resources?.close();
+            }
+            catch { /* Cleanup never replaces the command's actual outcome. */ }
+        }
     }
     #denied(record) {
         return Object.freeze({ matched: true, status: 'denied', command: record.name, owner: record.slot.owner });
@@ -374,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) {
@@ -406,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) {
@@ -434,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'));
         }
@@ -461,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

@@ -3,7 +3,7 @@
  * @module zhin.js/command
  */
 import { type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import { type OperationSession, type AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
+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 CommandExecutionPolicy } from './execution-policy.js';
 export type { CommandExecutionPolicy, CommandExecutionLimit } from './execution-policy.js';
@@ -346,6 +346,7 @@ export interface CommandInvocationArguments {
 export interface CommandInvocationOperation {
     readonly snapshot: RuntimeSnapshot;
     readonly ownerId: PluginId;
+    readonly operation?: CapabilityOperation;
     readonly input?: unknown;
     readonly interaction?: UserInteraction;
     readonly adapter?: string;

package/lib/definition.js

@@ -177,7 +177,7 @@ export function resolveDynamicParams(params, source) {
 export function createCommandContext(operation, invocation) {
     const { snapshot, ownerId, input, interaction, adapter, presentation } = operation;
     const { args, params = {}, options = {}, segments = [] } = invocation;
-    const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
+    const context = createCapabilityContext({ snapshot, ownerId, signal: readOperationInputSignal(input), operation: operation.operation });
     const session = resolveCommandSession(input);
     const parameterValues = { __proto__: null, ...params };
     const optionValues = { __proto__: null, ...options };

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.13",
+  "version": "1.1.15",
   "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.11",
     "@zhin.js/interaction": "1.1.2",
-    "@zhin.js/permission": "1.1.11",
-    "@zhin.js/plugin-runtime": "1.1.19"
+    "@zhin.js/permission": "1.1.13",
+    "@zhin.js/plugin-runtime": "1.1.21",
+    "@zhin.js/feature-kit": "1.1.13"
   },
   "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

@@ -13,7 +13,7 @@ import {
   type Locale,
 } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
-import { bindOperationInput } from '@zhin.js/feature-kit';
+import { bindOperationInput, type CapabilityOperationFactory } from '@zhin.js/feature-kit';
 import {
   permissionHostToken,
   type PermissionHost,
@@ -65,6 +65,7 @@ export interface CommandDispatchRequest {
   readonly interactionFactory?: UserInteractionFactory;
   readonly commandPrefix?: string;
   readonly snapshot?: RuntimeSnapshot;
+  readonly operation?: CapabilityOperationFactory;
   readonly locale?: Locale;
 }
 /** Presentation and generation shared across one menu lookup/render operation. */
@@ -161,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[];
@@ -351,7 +354,7 @@ export class CommandIndex {
   }
 
   async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot,
-    locale: localeOverride }: CommandDispatchRequest): Promise<CommandDispatchResult> {
+    locale: localeOverride, operation: operationFactory }: CommandDispatchRequest): Promise<CommandDispatchResult> {
     const locale = localeOverride ?? commandLocale(source, operationSnapshot);
     const prefix = commandPrefix ?? '';
     if (this.#menu) {
@@ -395,13 +398,19 @@ export class CommandIndex {
       owner: match.command.slot.owner, issues: parsed.issues, help });
     const limit = admitCommandExecution(authorSource, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
     if (limit) return Object.freeze({ matched: true, status: 'limited', command: match.command.name, owner: match.command.slot.owner, limit });
-    const value = await definition.execute(createCommandContext({
-      snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
-      interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
-      presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath,
-        source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
-    }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
-    return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+    const operation = operationFactory?.create({ owner: match.command.slot.owner, signal: operationFactory.signal });
+    try {
+      const value = await definition.execute(createCommandContext({
+        snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
+        operation,
+        interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
+        presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath,
+          source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
+      }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
+      return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+    } finally {
+      try { await operation?.resources?.close(); } catch { /* Cleanup never replaces the command's actual outcome. */ }
+    }
   }
 
   #denied(record: CommandRecord): CommandDispatchResult {
@@ -516,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) {
@@ -548,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('');
@@ -579,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'));
     }
@@ -605,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

@@ -5,6 +5,7 @@
 import { resolveLocale, type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import {
   createCapabilityContext,
+  type CapabilityOperation,
   readOperationClient,
   readOperationSession,
   type OperationSession,
@@ -598,6 +599,7 @@ export interface CommandInvocationArguments {
 export interface CommandInvocationOperation {
   readonly snapshot: RuntimeSnapshot;
   readonly ownerId: PluginId;
+  readonly operation?: CapabilityOperation;
   readonly input?: unknown;
   readonly interaction?: UserInteraction;
   readonly adapter?: string;
@@ -611,7 +613,7 @@ export interface CommandInvocationOperation {
 export function createCommandContext(operation: CommandInvocationOperation, invocation: CommandInvocationArguments): CommandContext {
   const { snapshot, ownerId, input, interaction, adapter, presentation } = operation;
   const { args, params = {}, options = {}, segments = [] } = invocation;
-  const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
+  const context = createCapabilityContext({ snapshot, ownerId, signal: readOperationInputSignal(input), operation: operation.operation });
   const session = resolveCommandSession(input);
   const parameterValues: Record<string, CommandParameterValue> = { __proto__: null, ...params };
   const optionValues: Record<string, CommandParameterValue> = { __proto__: null, ...options };

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}' },