@zhin.js/command 1.1.5 → 1.1.7

package/lib/command-index.js

@@ -1,6 +1,7 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
 import { bindOperationInput, operationClientAdapter } from '@zhin.js/feature-kit';
 import { permissionHostToken, toPermissionSubject, } from '@zhin.js/permission';
+import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp } from './arguments.js';
 import { createCommandContext, resolveCommandSession, resolveDynamicParams, } from './definition.js';
 const segmentFields = {
     text: 'text',
@@ -27,12 +28,16 @@ export class CommandIndex {
         const routes = [];
         const occupancy = new Map();
         const shortcuts = new Map();
-        const claim = (key, source) => {
-            const existing = occupancy.get(key);
-            if (existing !== undefined) {
-                throw new Error(`Duplicate Command route "${key}" (${source} vs ${existing})`);
+        const claim = (keys, source) => {
+            for (const key of keys) {
+                for (const [occupied, existing] of occupancy) {
+                    if (routeShapesOverlap(key, occupied)) {
+                        throw new Error(`Duplicate Command route "${key}" (${source} vs ${existing})`);
+                    }
+                }
             }
-            occupancy.set(key, source);
+            for (const key of keys)
+                occupancy.set(key, source);
         };
         for (const slot of slots) {
             const namespace = commandNamespace(this.snapshot, slot.owner);
@@ -52,10 +57,16 @@ export class CommandIndex {
                 description: slot.definition.description,
                 ...(slot.definition.adapter ? { adapter: slot.definition.adapter } : {}),
                 source: slot.source,
-                parameters: Object.freeze(parameter ? [{
-                        ...parameter,
-                        required: isRequiredParameter(parameter),
-                    }] : []),
+                usage: commandUsage(name, slot.definition),
+                options: Object.freeze({ ...slot.definition.options }),
+                parameters: Object.freeze([
+                    ...Object.entries(slot.definition.params ?? {}).map(([key, schema]) => ({
+                        name: key, ...schema, ...(parameter?.name === key ? parameter : {}), defaultValue: schema.default,
+                        required: parameter?.name === key ? isRequiredParameter(parameter) : !schema.optional && schema.default === undefined,
+                    })),
+                    ...(parameter && !Object.hasOwn(slot.definition.params ?? {}, parameter.name)
+                        ? [{ ...parameter, required: isRequiredParameter(parameter) }] : []),
+                ]),
                 ...(alias ? { alias } : {}),
                 ...(permit ? { permit } : {}),
                 ...(shortcutKeys && shortcutKeys.length > 0 ? { shortcut: shortcutKeys } : {}),
@@ -63,22 +74,24 @@ export class CommandIndex {
                 segments: Object.freeze(primarySegments),
                 parameter,
             });
-            claim(occupancyKey(primarySegments, parameter), slot.source);
+            claim([...new Set([occupancyKey(primarySegments, parameter), ...declaredRouteShapes(primarySegments, slot.definition)])], slot.source);
             routes.push({
                 record,
                 segments: primarySegments,
                 matcher: new SegmentMatcher(matcherPattern(primarySegments, parameter), segmentFields),
+                literalMatcher: compileLiteralMatcher(primarySegments, parameter),
                 kind: 'primary',
             });
             if (alias) {
                 for (const entry of alias) {
                     const aliasSegments = [...namespace, ...aliasRuntimeSegments(entry, primarySegments.slice(namespace.length))];
                     assertParameterSegment(aliasSegments, parameter, `${slot.source} alias ${JSON.stringify(entry)}`);
-                    claim(occupancyKey(aliasSegments, parameter), `${slot.source} alias ${JSON.stringify(entry)}`);
+                    claim([...new Set([occupancyKey(aliasSegments, parameter), ...declaredRouteShapes(aliasSegments, slot.definition)])], `${slot.source} alias ${JSON.stringify(entry)}`);
                     routes.push({
                         record,
                         segments: Object.freeze(aliasSegments),
                         matcher: new SegmentMatcher(matcherPattern(aliasSegments, parameter), segmentFields),
+                        literalMatcher: compileLiteralMatcher(aliasSegments, parameter),
                         kind: 'alias',
                     });
                 }
@@ -86,7 +99,7 @@ export class CommandIndex {
             if (slot.definition.shortcut) {
                 for (const [rawTrigger, prefill] of Object.entries(slot.definition.shortcut)) {
                     const trigger = [...namespace, ...splitCommand(rawTrigger)].join(' ');
-                    claim(trigger, `${slot.source} shortcut ${JSON.stringify(trigger)}`);
+                    claim([trigger], `${slot.source} shortcut ${JSON.stringify(trigger)}`);
                     shortcuts.set(trigger, {
                         record,
                         params: Object.freeze(resolveShortcutParams(slot.definition, prefill, `${slot.source} shortcut ${JSON.stringify(trigger)}`)),
@@ -113,13 +126,19 @@ export class CommandIndex {
         }
     }
     async execute(name, args = [], operationSnapshot = this.snapshot) {
-        const match = this.#match(name, true);
+        const match = this.#match(name, false);
         if (!match) {
             this.#diagnoseParameter(name);
             throw new Error(`Unknown Command: ${name}`);
         }
-        // Host / 无 session：跳过 permit；无 source 时函数默认值得到空 session。
-        return match.command.slot.definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, args, resolveDynamicParams(match.params, undefined), undefined, Object.freeze([]), undefined, match.command.slot.definition.adapter));
+        if (!(await this.#permitAllows(match.command, undefined, operationSnapshot)))
+            throw new Error(`Permission denied for Command: ${match.command.name}`);
+        const definition = match.command.slot.definition;
+        const supplied = [...match.remaining, ...(args.length > 0 ? [{ type: 'text', data: { text: args.join(' ') } }] : [])];
+        const parsed = parseCommandArguments(definition, supplied, resolveDynamicParams(match.params, undefined), {});
+        if (parsed.issues.length > 0)
+            throw new CommandArgumentValidationError(parsed.issues, commandHelp(match.command.name, definition));
+        return definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
     }
     async dispatch(input, source = undefined, interactionFactory, commandPrefix = '', operationSnapshot = this.snapshot) {
         if (this.#menu) {
@@ -127,6 +146,7 @@ export class CommandIndex {
             if (menuValue !== undefined) {
                 return Object.freeze({
                     matched: true,
+                    status: 'executed',
                     command: this.#menu.keyword,
                     owner: operationSnapshot.root,
                     value: menuValue,
@@ -134,51 +154,70 @@ export class CommandIndex {
             }
         }
         const shortcut = this.#matchShortcut(input);
-        if (shortcut) {
-            if (!commandAdapterMatches(shortcut.record, source)) {
-                return Object.freeze({ matched: false });
-            }
-            if (!(await this.#permitAllows(shortcut.record, source, operationSnapshot))) {
-                return Object.freeze({ matched: false });
-            }
-            const authorSource = bindOperationInput(source, shortcut.record.slot.owner, operationSnapshot);
-            const value = await shortcut.record.slot.definition.execute(createCommandContext(operationSnapshot, shortcut.record.slot.owner, Object.freeze([]), resolveDynamicParams(shortcut.params, authorSource), authorSource, Object.freeze([]), interactionFactory?.(authorSource), shortcut.record.slot.definition.adapter));
-            return Object.freeze({
-                matched: true,
-                command: shortcut.record.name,
-                owner: shortcut.record.slot.owner,
-                value,
-            });
+        const match = shortcut
+            ? { command: shortcut.record, params: shortcut.params, remaining: Object.freeze([]), helpRequested: false }
+            : this.#match(input, false);
+        if (!match) {
+            const candidate = this.#invalidRoute(input);
+            if (!candidate)
+                return Object.freeze({ matched: false, status: 'unmatched' });
+            if (!commandAdapterMatches(candidate, source))
+                return Object.freeze({ matched: false, status: 'unmatched' });
+            if (!(await this.#permitAllows(candidate, source, operationSnapshot)))
+                return this.#denied(candidate);
+            const help = commandHelp(candidate.name, candidate.slot.definition, commandPrefix);
+            const segments = normalizeSegments(typeof input === 'string' ? [{ type: 'text', data: { text: input } }] : input);
+            if (requestsCommandHelp(segments))
+                return Object.freeze({ matched: true, status: 'executed', command: candidate.name, owner: candidate.slot.owner, value: help });
+            return Object.freeze({ matched: true, status: 'invalid', command: candidate.name, owner: candidate.slot.owner,
+                issues: Object.freeze([{ field: candidate.parameter?.name ?? 'arguments', message: 'Missing or invalid command parameter' }]), help });
         }
-        const match = this.#match(input, false);
-        if (!match)
-            return Object.freeze({ matched: false });
-        if (!commandAdapterMatches(match.command, source)) {
-            return Object.freeze({ matched: false });
+        if (!commandAdapterMatches(match.command, source))
+            return Object.freeze({ matched: false, status: 'unmatched' });
+        if (!(await this.#permitAllows(match.command, source, operationSnapshot)))
+            return this.#denied(match.command);
+        const definition = match.command.slot.definition;
+        const authorSource = bindOperationInput(source, match.command.slot.owner, operationSnapshot);
+        const help = commandHelp(match.command.name, definition, commandPrefix);
+        if (match.helpRequested) {
+            return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value: help });
         }
-        if (!(await this.#permitAllows(match.command, source, operationSnapshot))) {
-            return Object.freeze({ matched: false });
+        const parsed = parseCommandArguments(definition, match.remaining, resolveDynamicParams(match.params, authorSource), resolveCommandSession(authorSource));
+        if (parsed.issues.length > 0)
+            return Object.freeze({ matched: true, status: 'invalid', command: match.command.name,
+                owner: match.command.slot.owner, issues: parsed.issues, help });
+        const value = await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, textArgs(parsed.remaining), parsed.params, authorSource, parsed.remaining, interactionFactory?.(authorSource), definition.adapter, parsed.options));
+        return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+    }
+    #denied(record) {
+        return Object.freeze({ matched: true, status: 'denied', command: record.name, owner: record.slot.owner });
+    }
+    /** Diagnose only a reliable static route prefix; fully dynamic routes are ordinary chat candidates. */
+    #invalidRoute(input) {
+        const segments = normalizeSegments(typeof input === 'string' ? [{ type: 'text', data: { text: input } }] : input);
+        for (const route of this.#routes) {
+            if (!route.record.parameter)
+                continue;
+            const result = route.literalMatcher?.match(asMatcherSegments(segments));
+            if (result && hasCommandBoundary(result.remaining))
+                return route.record;
         }
-        const args = textArgs(match.remaining);
-        const authorSource = bindOperationInput(source, match.command.slot.owner, operationSnapshot);
-        const value = await match.command.slot.definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, args, resolveDynamicParams(match.params, authorSource), authorSource, match.remaining, interactionFactory?.(authorSource), match.command.slot.definition.adapter));
-        return Object.freeze({
-            matched: true,
-            command: match.command.name,
-            owner: match.command.slot.owner,
-            value,
-        });
+        return undefined;
     }
     async #permitAllows(record, source, operationSnapshot) {
         const permits = record.permit;
         if (!permits || permits.length === 0)
             return true;
-        if (!hasImSession(source))
-            return true;
+        if (!source || typeof source !== 'object')
+            return false;
         const host = this.#resolveHost(operationSnapshot);
         if (!host)
             return false;
-        const subject = toPermissionSubject(resolveCommandSession(source));
+        const projected = toPermissionSubject(source);
+        const session = resolveCommandSession(source);
+        const subject = { ...projected, ...session, ...(session.sender ? { sender: { ...projected.sender, ...session.sender } } : {}) };
+        if (!subject.sender?.id && !subject.scene?.id && !subject.adapter && !subject.endpoint)
+            return false;
         return host.checkAll(permits, subject);
     }
     #resolveHost(operationSnapshot) {
@@ -210,12 +249,18 @@ export class CommandIndex {
         if (segments.length === 0)
             return undefined;
         for (const route of this.#routes) {
-            const result = route.matcher.match(asMatcherSegments(segments));
+            // Options may appear between the literal route and a directory-bound parameter.
+            const literalResult = !exact ? route.literalMatcher?.match(asMatcherSegments(segments)) : undefined;
+            const helpRequested = literalResult && hasCommandBoundary(literalResult.remaining)
+                && requestsCommandHelp(normalizeSegments(literalResult.remaining));
+            const parseDeclaredArguments = !exact && route.record.parameter && route.literalMatcher !== undefined
+                && (Object.hasOwn(route.record.slot.definition.params ?? {}, route.record.parameter.name) || helpRequested);
+            const result = parseDeclaredArguments ? literalResult : route.matcher.match(asMatcherSegments(segments));
             if (!result || !hasCommandBoundary(result.remaining))
                 continue;
             const parameter = route.record.parameter;
             const params = { ...result.params };
-            if (parameter?.rest) {
+            if (parameter?.rest && !parseDeclaredArguments) {
                 const raw = result.params[parameter.name];
                 const coerced = coerceRestValues(parameter, Array.isArray(raw) ? raw : []);
                 if (!coerced || (isRequiredParameter(parameter) && coerced.length === 0))
@@ -225,15 +270,18 @@ export class CommandIndex {
             const remaining = normalizeSegments(result.remaining);
             if (exact && remaining.length > 0)
                 continue;
-            if (parameter && !parameter.rest && parameter.optional === true
-                && parameter.defaultValue === undefined
-                && (params[parameter.name] === '' || params[parameter.name] === null)) {
-                delete params[parameter.name];
+            if (parameter && !parseDeclaredArguments && !parameter.rest && !isRequiredParameter(parameter)
+                && (params[parameter.name] === '' || params[parameter.name] === null || params[parameter.name] === undefined)) {
+                if (parameter.defaultValue !== undefined)
+                    params[parameter.name] = parameter.defaultValue;
+                else
+                    delete params[parameter.name];
             }
             return {
                 command: route.record,
                 params: Object.freeze(params),
                 remaining,
+                helpRequested: literalResult ? !!helpRequested : requestsCommandHelp(remaining),
             };
         }
         return undefined;
@@ -262,18 +310,21 @@ export class CommandIndex {
         const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
         if (text === undefined)
             return undefined;
-        const keyword = this.#menu.keyword;
+        const menu = this.#menu;
+        if (!menu)
+            return undefined;
+        const keyword = menu.keyword;
         if (text === keyword)
-            return this.#buildMenu(undefined, commandPrefix);
+            return this.#buildMenu(undefined, commandPrefix, keyword);
         if (text.startsWith(keyword + ' ')) {
             const key = text.slice(keyword.length + 1).trim();
             if (key)
-                return this.#buildMenu(key, commandPrefix);
-            return this.#buildMenu(undefined, commandPrefix);
+                return this.#buildMenu(key, commandPrefix, keyword);
+            return this.#buildMenu(undefined, commandPrefix, keyword);
         }
         return undefined;
     }
-    #buildMenu(pluginKey, commandPrefix = '') {
+    #buildMenu(pluginKey, commandPrefix, keyword) {
         const root = this.snapshot.root;
         const targetId = pluginKey
             ? `${root}/${pluginKey.split('.').join('/')}`
@@ -285,7 +336,6 @@ export class CommandIndex {
         const children = node.children
             .map((childId) => this.snapshot.tree.get(childId))
             .filter((child) => !!child);
-        const keyword = this.#menu.keyword;
         const displayKey = pluginKey ?? node.instanceKey;
         const lines = [`=== ${displayKey} 指令菜单 ===`];
         if (directCommands.length > 0) {
@@ -354,12 +404,68 @@ function aliasRuntimeSegments(alias, primarySegments) {
 function occupancyKey(segments, parameter) {
     return parameter ? routeShape(segments) : segments.join(' ');
 }
+/** Accepted token arities, including optional tails and an unbounded rest tail. */
+function declaredRouteShapes(segments, definition) {
+    let variants = [[]];
+    const append = (token, optional = false) => {
+        const withToken = variants.map((variant) => [...variant, token]);
+        variants = [...new Map((optional ? [...variants, ...withToken] : withToken)
+                .map((variant) => [variant.join(' '), variant])).values()];
+    };
+    for (const segment of segments) {
+        if (!segment.startsWith('$')) {
+            append(segment);
+            continue;
+        }
+        const parameter = definition.$parameter;
+        if (!parameter)
+            continue;
+        if (parameter.rest)
+            append(isRequiredParameter(parameter) ? '$+' : '$*');
+        else
+            append('$', !isRequiredParameter(parameter));
+    }
+    for (const [name, schema] of Object.entries(definition.params ?? {})) {
+        if (name === definition.$parameter?.name)
+            continue;
+        const optional = schema.optional === true || schema.default !== undefined;
+        if (schema.rest)
+            append(optional ? '$*' : '$+');
+        else
+            append('$', optional);
+    }
+    return [...new Set(variants.map((variant) => variant.join(' ')))];
+}
+function routeShapesOverlap(left, right) {
+    const shape = (key) => {
+        const tokens = key.split(' ');
+        const repeat = tokens.at(-1);
+        const rest = repeat === '$*' || repeat === '$+';
+        const prefix = rest ? tokens.slice(0, -1) : tokens;
+        return { prefix, min: prefix.length + (repeat === '$+' ? 1 : 0), max: rest ? Infinity : prefix.length };
+    };
+    const a = shape(left);
+    const b = shape(right);
+    const length = Math.max(a.min, b.min);
+    if (length > Math.min(a.max, b.max))
+        return false;
+    for (let index = 0; index < length; index++) {
+        if ((a.prefix[index] ?? '$') !== (b.prefix[index] ?? '$'))
+            return false;
+    }
+    return true;
+}
 function normalizeAliasList(alias) {
     if (!alias || alias.length === 0)
         return undefined;
     return Object.freeze(alias.map((entry) => entry.trim().split(/\s+/u).filter(Boolean).join(' ')));
 }
 function resolveShortcutParams(definition, prefill, source) {
+    for (const [name, schema] of Object.entries(definition.options ?? {})) {
+        if (schema.optional === false && schema.default === undefined) {
+            throw new TypeError(`Invalid shortcut for ${source}: cannot supply required option --${name}`);
+        }
+    }
     const allowed = new Set();
     const parameter = definition.$parameter;
     if (parameter)
@@ -396,12 +502,6 @@ function resolveShortcutParams(definition, prefill, source) {
     }
     return result;
 }
-function hasImSession(source) {
-    if (!source || typeof source !== 'object')
-        return false;
-    const conversation = source.conversation;
-    return !!conversation && typeof conversation === 'object';
-}
 function exactMessageText(input) {
     if (typeof input === 'string') {
         const trimmed = input.trim();
@@ -445,6 +545,12 @@ function displayName(segments, parameter) {
         return required ? `<${label}>` : `[${label}]`;
     }).join(' ');
 }
+function compileLiteralMatcher(segments, parameter) {
+    if (!parameter)
+        return undefined;
+    const literals = segments.filter((segment) => !segment.startsWith('$'));
+    return literals.length > 0 ? new SegmentMatcher(literals.join(' '), segmentFields) : undefined;
+}
 function matcherPattern(segments, parameter) {
     return segments.map((segment) => {
         if (!segment.startsWith('$'))
@@ -457,9 +563,7 @@ function matcherPattern(segments, parameter) {
         }
         if (isRequiredParameter(parameter))
             return `<${parameter.name}:${type}>`;
-        return parameter.defaultValue === undefined
-            ? `[${parameter.name}:${type}]`
-            : `[${parameter.name}:${type}=${typeof parameter.defaultValue === 'function' ? '<dynamic>' : String(parameter.defaultValue)}]`;
+        return `[${parameter.name}:${type}]`;
     }).join(' ');
 }
 function matcherType(type) {
@@ -590,3 +694,13 @@ export class CommandParameterValueError extends TypeError {
         this.name = 'CommandParameterValueError';
     }
 }
+export class CommandArgumentValidationError extends TypeError {
+    issues;
+    help;
+    constructor(issues, help) {
+        super(issues.map((issue) => issue.message).join('\n') + '\n' + help);
+        this.issues = issues;
+        this.help = help;
+        this.name = 'CommandArgumentValidationError';
+    }
+}

package/lib/definition.d.ts

@@ -7,7 +7,7 @@ import { type AdapterClient, type RegisteredAdapterName, type CapabilityContext
 import type { UserInteraction } from '@zhin.js/interaction';
 declare const commandBrand: "zhin.command/1";
 export type CommandParameterType = 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'word' | 'text' | 'mention' | 'image' | 'face' | 'reply' | 'forward' | 'dice' | 'rps';
-export type CommandParameterValue = string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null;
+export type CommandParameterValue = string | number | boolean | ReadonlyArray<string | number | boolean | Readonly<Record<string, unknown>>> | Readonly<Record<string, unknown>> | null;
 /**
  * 可从运行时会话上下文动态解析的参数值。
  *
@@ -39,7 +39,44 @@ export interface CommandParamSchema {
     readonly type: CommandParameterType;
     readonly default?: CommandDynamicValue;
     readonly description?: string;
+    readonly optional?: boolean;
+    readonly rest?: boolean;
+    readonly min?: number;
+    readonly max?: number;
+    readonly choices?: readonly CommandParameterValue[];
+    readonly pattern?: RegExp;
+    readonly validate?: (value: CommandParameterValue, session: CommandSession) => boolean | string;
+}
+export interface CommandOptionSchema extends Omit<CommandParamSchema, 'rest'> {
+    readonly alias?: string;
 }
+export type CommandParams = Readonly<Record<string, CommandParamSchema>>;
+export type CommandOptions = Readonly<Record<string, CommandOptionSchema>>;
+type ParameterScalar<S extends CommandParamSchema> = S['type'] extends 'number' | 'integer' | 'float' | 'dice' | 'rps' ? number : S['type'] extends 'boolean' ? boolean : S['type'] extends 'image' ? Readonly<Record<string, unknown>> | string : S['type'] extends 'mention' | 'face' | 'reply' | 'forward' ? string | number : string;
+type ParameterResult<S extends CommandParamSchema> = S extends {
+    readonly rest: true;
+} ? readonly ParameterScalar<S>[] : ParameterScalar<S>;
+type HasDefault<S extends CommandParamSchema> = S extends {
+    readonly default: infer D;
+} ? undefined extends D ? false : true : false;
+type OptionalParam<S extends CommandParamSchema> = S extends {
+    readonly rest: true;
+} ? false : HasDefault<S> extends true ? false : S extends {
+    readonly optional: true;
+} ? true : false;
+type OptionalOption<S extends CommandOptionSchema> = HasDefault<S> extends true ? false : S extends {
+    readonly optional: false;
+} ? false : true;
+export type InferCommandParams<P extends CommandParams> = {
+    readonly [K in keyof P as OptionalParam<P[K]> extends true ? never : K]: ParameterResult<P[K]>;
+} & {
+    readonly [K in keyof P as OptionalParam<P[K]> extends true ? K : never]?: ParameterResult<P[K]>;
+};
+export type InferCommandOptions<O extends CommandOptions> = {
+    readonly [K in keyof O as OptionalOption<O[K]> extends true ? never : K]: ParameterResult<O[K]>;
+} & {
+    readonly [K in keyof O as OptionalOption<O[K]> extends true ? K : never]?: ParameterResult<O[K]>;
+};
 /** Minimal structural contract shared with canonical IM segments. */
 export interface CommandSegment {
     readonly type: string | {
@@ -169,6 +206,7 @@ export interface CommandSession {
 export interface CommandContext<TConfig = unknown, TInput extends CommandMessage = CommandMessage, TAdapter extends string | undefined = undefined> extends CapabilityContext<TConfig>, CommandSession {
     readonly args: readonly string[];
     readonly params: Readonly<Record<string, CommandParameterValue>>;
+    readonly options: Readonly<Record<string, CommandParameterValue>>;
     /** Structured arguments left after the command pattern was consumed. */
     readonly segments: readonly Readonly<CommandSegment>[];
     /**
@@ -196,7 +234,8 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
      * Next.js 风格参数声明：动态段文件名（`[name]` 等）的形态配合这里的
      * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
      */
-    readonly params?: Readonly<Record<string, CommandParamSchema>>;
+    readonly params?: CommandParams;
+    readonly options?: CommandOptions;
     /**
      * 本地静态段别名（可多词，如 `'gh issue'`）。Capability owner 不参与
      * 用户路由；alias 只替换文件路径提供的静态段。
@@ -223,12 +262,23 @@ declare module '@zhin.js/plugin-runtime' {
  * 定义一个命令模块（`commands/` 约定目录下默认导出）。
  * @public 用户侧创作面，承诺 semver（见 docs/contributing/public-api-surface.md）。
  */
-type CommandAuthoringDefinition<TConfig, TResult, TInput extends CommandMessage> = Omit<CommandDefinition<TConfig, TResult, TInput, undefined>, '$feature' | '$parameter'> | {
-    [TAdapter in RegisteredAdapterName]: Omit<CommandDefinition<TConfig, TResult, TInput, TAdapter>, '$feature' | '$parameter'> & {
+type CommandAuthoringDefinition<TConfig, TResult, TInput extends CommandMessage, P extends CommandParams, O extends CommandOptions> = (Omit<CommandDefinition<TConfig, TResult, TInput, undefined>, '$feature' | '$parameter' | 'params' | 'options' | 'execute'> & {
+    readonly params?: P;
+    readonly options?: O;
+    execute(context: TypedCommandContext<TConfig, TInput, undefined, P, O>): TResult | Promise<TResult>;
+}) | {
+    [TAdapter in RegisteredAdapterName]: Omit<CommandDefinition<TConfig, TResult, TInput, TAdapter>, '$feature' | '$parameter' | 'params' | 'options' | 'execute'> & {
         readonly adapter: TAdapter;
+        readonly params?: P;
+        readonly options?: O;
+        execute(context: TypedCommandContext<TConfig, TInput, TAdapter, P, O>): TResult | Promise<TResult>;
     };
 }[RegisteredAdapterName];
-export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput>): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
+type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extends string | undefined, P extends CommandParams, O extends CommandOptions> = Omit<CommandContext<TConfig, TInput, TAdapter>, 'params' | 'options'> & {
+    readonly params: keyof P extends never ? Readonly<Record<string, CommandParameterValue>> : InferCommandParams<P>;
+    readonly options: InferCommandOptions<O>;
+};
+export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage, const P extends CommandParams = {}, const O extends CommandOptions = {}>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
 /** @internal Convention-loader assembly helper. */
 export declare function bindCommandParameter<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined>(definition: CommandDefinition<TConfig, TResult, TInput, TAdapter>, parameter: CommandParameterDefinition | undefined): Readonly<CommandDefinition<TConfig, TResult, TInput, TAdapter>>;
 /** @internal Runtime validation for convention-discovered modules. */
@@ -240,7 +290,7 @@ export declare function parseCommandDefinition(value: unknown): CommandDefinitio
  */
 export declare function resolveDynamicParams(params: Readonly<Record<string, CommandDynamicValue>>, source: unknown): Readonly<Record<string, CommandParameterValue>>;
 /** @internal Command dispatcher assembly helper. */
-export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown, segments?: readonly Readonly<CommandSegment>[], interaction?: UserInteraction, adapter?: string): CommandContext;
+export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown, segments?: readonly Readonly<CommandSegment>[], interaction?: UserInteraction, adapter?: string, options?: Readonly<Record<string, CommandParameterValue>>): CommandContext;
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
  * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。

package/lib/definition.js

@@ -1,5 +1,6 @@
 import { createCapabilityContext, readOperationClient, } from '@zhin.js/feature-kit';
 import { assertPermitSyntax } from '@zhin.js/permission';
+import { validateArgumentSchemas } from './arguments.js';
 const commandBrand = 'zhin.command/1';
 /** @internal Runtime validator lookup. */
 export const commandParameterTypes = new Set([
@@ -34,6 +35,7 @@ export function defineCommand(definition) {
             }
         }
     }
+    validateArgumentSchemas(definition.params, definition.options);
     validateCommandAlias(definition.alias);
     validateCommandPermit(definition.permit);
     validateCommandShortcutShape(definition.shortcut);
@@ -120,14 +122,17 @@ export function resolveDynamicParams(params, source) {
     return Object.freeze(resolved);
 }
 /** @internal Command dispatcher assembly helper. */
-export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction, adapter) {
+export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction, adapter, options = Object.freeze({})) {
     const context = createCapabilityContext(snapshot, ownerId);
     const session = resolveCommandSession(input);
+    const parameterValues = { __proto__: null, ...params };
+    const optionValues = { __proto__: null, ...options };
     const result = {
         ...context,
         ...session,
         args: Object.freeze([...args]),
-        params: Object.freeze({ ...params }),
+        params: Object.freeze(parameterValues),
+        options: Object.freeze(optionValues),
         segments: freezeSegments(segments),
         ...(input !== undefined ? { input: input } : {}),
         ...(interaction !== undefined ? { interaction } : {}),

package/lib/index.d.ts

@@ -9,3 +9,4 @@ export * from './definition.js';
 export { assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, type ParsedPermit, type PermitKind, } from './permit.js';
 export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';
+export type { CommandValidationIssue } from './arguments.js';

package/lib/provider.js

@@ -86,6 +86,13 @@ function resolveParameter(definition, file, source) {
     if (!schema) {
         throw new CommandPathSyntaxError(source, `missing params.${hint.name} declaration in defineCommand({ params })`);
     }
+    if (Object.keys(definition.params ?? {})[0] !== hint.name) {
+        throw new CommandPathSyntaxError(source, `params.${hint.name} must be the first parameter declaration`);
+    }
+    if (schema.rest !== undefined && schema.rest !== hint.rest
+        || schema.optional !== undefined && schema.optional !== hint.optional) {
+        throw new CommandPathSyntaxError(source, `params.${hint.name} optional/rest declaration conflicts with the directory shape`);
+    }
     if (!hint.optional && schema.default !== undefined) {
         throw new CommandPathSyntaxError(source, `params.${hint.name} has a default but the directory is required: rename it to [[${hint.name}]]`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -8,7 +8,6 @@
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
-      "development": "./src/index.ts",
       "import": "./lib/index.js"
     }
   },
@@ -18,10 +17,10 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.1.3",
-    "@zhin.js/interaction": "1.1.0",
-    "@zhin.js/permission": "1.1.4",
-    "@zhin.js/plugin-runtime": "1.1.12"
+    "@zhin.js/feature-kit": "1.1.5",
+    "@zhin.js/plugin-runtime": "1.1.14",
+    "@zhin.js/interaction": "1.1.2",
+    "@zhin.js/permission": "1.1.6"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -35,7 +34,7 @@
     "featureApi": "1.0.0"
   },
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": ">=22.19.0"
   },
   "repository": {
     "type": "git",