@zhin.js/command 1.2.0 → 1.2.1

package/lib/command-index.d.ts

@@ -25,6 +25,8 @@ export interface CommandDescriptor {
     readonly execution?: CommandDefinition['execution'];
     /** shortcut 触发键列表（不含预填 params）。 */
     readonly shortcut?: readonly string[];
+    /** `match` 正则的字面形式（如 `/^demo$/i`）。 */
+    readonly match?: string;
 }
 /** One dispatch reads the caller's exact operation generation and presentation. */
 export interface CommandDispatchRequest {

package/lib/command-index.js

@@ -90,6 +90,7 @@ export class CommandIndex {
                 ...(alias ? { alias } : {}),
                 ...(permit ? { permit } : {}),
                 ...(shortcutKeys && shortcutKeys.length > 0 ? { shortcut: shortcutKeys } : {}),
+                ...(slot.definition.match ? { match: String(slot.definition.match), pattern: slot.definition.match } : {}),
                 slot,
                 segments: Object.freeze(primarySegments),
                 preferredSegments: Object.freeze(Object.fromEntries(Object.entries(slot.definition.preferredAliasI18n ?? {}).map(([locale, entry]) => [locale, Object.freeze([...namespace, ...aliasRuntimeSegments(entry, primarySegments.slice(namespace.length))])]))),
@@ -213,9 +214,10 @@ export class CommandIndex {
             }
         }
         const shortcut = this.#matchShortcut(input);
-        const match = shortcut
+        const routed = shortcut
             ? { command: shortcut.record, params: shortcut.params, remaining: Object.freeze([]), helpRequested: false }
             : this.#match(input, false);
+        const match = routed ? withPattern(routed, input) : this.#matchPattern(input);
         if (!match) {
             const candidate = this.#invalidRoute(input);
             if (!candidate)
@@ -257,7 +259,8 @@ export class CommandIndex {
                 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 }));
+            }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options,
+                ...(match.regex ? { match: match.regex } : {}) }));
             return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
         }
         finally {
@@ -336,6 +339,18 @@ export class CommandIndex {
             return undefined;
         }
     }
+    /** `match` 正则：路由不中时，按指令列表顺序取第一条正文符合的指令（只看纯文本消息）。 */
+    #matchPattern(input) {
+        const text = exactMessageText(input);
+        if (text === undefined)
+            return undefined;
+        for (const command of this.#commands) {
+            const regex = command.pattern?.exec(text);
+            if (regex)
+                return { command, params: Object.freeze({}), remaining: Object.freeze([]), helpRequested: false, regex };
+        }
+        return undefined;
+    }
     #matchShortcut(input) {
         const text = exactMessageText(input);
         if (text === undefined)
@@ -881,7 +896,14 @@ function textArgs(segments) {
         return splitCommand(segment.data.text);
     }));
 }
-function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, ...descriptor }) {
+/** A routed command whose `match` also fits the text exposes the match result too. */
+function withPattern(match, input) {
+    const pattern = match.command.pattern;
+    const text = pattern ? exactMessageText(input) : undefined;
+    const regex = pattern && text !== undefined ? pattern.exec(text) : null;
+    return regex ? { ...match, regex } : match;
+}
+function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, pattern: _pattern, ...descriptor }) {
     return descriptor;
 }
 export class CommandParameterValueError extends TypeError {

package/lib/definition.d.ts

@@ -254,6 +254,11 @@ export interface CommandContext<TConfig = unknown, TInput extends CommandMessage
      */
     /** Canonical user-facing input/confirmation/selection module. */
     readonly interaction?: UserInteraction;
+    /**
+     * 由 `match` 正则触发时的匹配结果（捕获组、具名组 `match.groups`）。
+     * 走指令名路由且正文同样符合 `match` 时也会填入；其余情况为 `undefined`。
+     */
+    readonly match?: Readonly<RegExpExecArray>;
 }
 export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage, TAdapter extends string | undefined = string | undefined> {
     /** @internal Runtime feature brand. */
@@ -289,6 +294,17 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
      * 与普通路由一样是全局用户输入，冲突会在 generation 构建时拒绝。
      */
     readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>>;
+    /**
+     * 正则触发：消息正文（去掉指令前缀并 trim 后、只含文本时）符合此正则即执行本指令，
+     * 匹配结果见 `context.match`。指令名路由照常可用，先按路由匹配，路由不中再试正则；
+     * 多条指令的正则都符合时取指令列表顺序中的第一条。不允许 `g` / `y` 标志（有状态）。
+     */
+    readonly match?: RegExp;
+    /**
+     * 固定回复：与 `execute` 二选一，等价于 `execute: () => reply`。
+     * 可以是文本、消息段或 JSX 等任何 `execute` 可返回的内容。
+     */
+    readonly reply?: TResult;
     execute(context: CommandContext<TConfig, TInput, TAdapter>): TResult | Promise<TResult>;
 }
 declare module '@zhin.js/plugin-runtime' {
@@ -300,18 +316,23 @@ declare module '@zhin.js/plugin-runtime' {
  * 定义一个命令模块（`commands/` 约定目录下默认导出）。
  * @public 用户侧创作面，承诺 semver（见 docs/contributing/public-api-surface.md）。
  */
-type CommandAuthoringDefinition<TConfig, TResult, TInput extends CommandMessage, P extends CommandParams, O extends CommandOptions> = (Omit<CommandDefinition<TConfig, TResult, TInput, undefined>, '$feature' | '$parameter' | 'params' | 'options' | 'execute'> & {
+type CommandAuthoringDefinition<TConfig, TResult, TInput extends CommandMessage, P extends CommandParams, O extends CommandOptions> = Omit<CommandDefinition<TConfig, TResult, TInput, undefined>, '$feature' | '$parameter' | 'params' | 'options' | 'execute' | 'reply'> & {
     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'> & {
+} & CommandBody<TConfig, TResult, TInput, undefined, P, O> | {
+    [TAdapter in RegisteredAdapterName]: Omit<CommandDefinition<TConfig, TResult, TInput, TAdapter>, '$feature' | '$parameter' | 'params' | 'options' | 'execute' | 'reply'> & {
         readonly adapter: TAdapter;
         readonly params?: P;
         readonly options?: O;
-        execute(context: TypedCommandContext<TConfig, TInput, TAdapter, P, O>): TResult | Promise<TResult>;
-    };
+    } & CommandBody<TConfig, TResult, TInput, TAdapter, P, O>;
 }[RegisteredAdapterName];
+/** `execute` 与固定回复 `reply` 二选一。 */
+type CommandBody<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined, P extends CommandParams, O extends CommandOptions> = {
+    execute(context: TypedCommandContext<TConfig, TInput, TAdapter, P, O>): TResult | Promise<TResult>;
+} | {
+    readonly reply: TResult;
+    readonly execute?: 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>;
@@ -339,6 +360,8 @@ export declare namespace defineCommand {
 }
 /** @internal Validate display-only translations without changing their fallback text. */
 export declare function validateDescriptionI18n(value: CommandDefinition['descriptionI18n']): void;
+/** @internal `match` is tested many times per generation, so stateful flags would skip matches. */
+export declare function validateCommandMatch(match: unknown): void;
 /** @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. */
@@ -355,6 +378,7 @@ export interface CommandInvocationArguments {
     readonly params?: Readonly<Record<string, CommandParameterValue>>;
     readonly options?: Readonly<Record<string, CommandParameterValue>>;
     readonly segments?: readonly Readonly<CommandSegment>[];
+    readonly match?: RegExpExecArray;
 }
 /** Author and lifetime authority captured by the dispatcher for this invocation. */
 export interface CommandInvocationOperation {

package/lib/definition.js

@@ -26,9 +26,7 @@ export const commandParameterTypes = new Set([
     'rps',
 ]);
 export function defineCommand(definition) {
-    if (typeof definition.execute !== 'function') {
-        throw new TypeError('Command execute must be a function');
-    }
+    const body = normalizeCommandBody(definition);
     validateAdapterName(definition.adapter);
     if (definition.params !== undefined) {
         if (!definition.params || typeof definition.params !== 'object') {
@@ -47,8 +45,9 @@ export function defineCommand(definition) {
     validatePreferredAliases(definition);
     validateCommandPermit(definition.permit);
     validateCommandShortcutShape(definition.shortcut);
+    validateCommandMatch(definition.match);
     const execution = normalizeExecutionPolicy(definition.execution);
-    return Object.freeze({ $feature: commandBrand, ...definition, ...(execution ? { execution } : {}) });
+    return Object.freeze({ $feature: commandBrand, ...definition, ...body, ...(execution ? { execution } : {}) });
 }
 /** @internal Validate display-only translations without changing their fallback text. */
 export function validateDescriptionI18n(value) {
@@ -77,6 +76,32 @@ export function validateDescriptionI18n(value) {
 defineCommand.withConfig = function withConfig() {
     return (definition) => defineCommand(definition);
 };
+function normalizeCommandBody(definition) {
+    const hasReply = Object.hasOwn(definition, 'reply') && definition.reply !== undefined;
+    if (typeof definition.execute === 'function') {
+        if (hasReply)
+            throw new TypeError('Command declares both execute and reply; use one of them');
+        return { execute: definition.execute };
+    }
+    if (definition.execute !== undefined)
+        throw new TypeError('Command execute must be a function');
+    if (!hasReply)
+        throw new TypeError('Command needs execute or reply');
+    if (typeof definition.reply === 'function') {
+        throw new TypeError('Command reply is a fixed value; pass a function as execute instead');
+    }
+    const reply = definition.reply;
+    return { execute: () => reply };
+}
+/** @internal `match` is tested many times per generation, so stateful flags would skip matches. */
+export function validateCommandMatch(match) {
+    if (match === undefined)
+        return;
+    if (!(match instanceof RegExp))
+        throw new TypeError('Command match must be a RegExp');
+    if (match.global || match.sticky)
+        throw new TypeError('Command match must not use the g or y flag');
+}
 function validateAdapterName(adapter) {
     if (adapter !== undefined && (typeof adapter !== 'string' || adapter.trim() === '')) {
         throw new TypeError('Command adapter must be a non-empty string');
@@ -176,7 +201,7 @@ export function resolveDynamicParams(params, source) {
 /** @internal Command dispatcher assembly helper; each value has one owner. */
 export function createCommandContext(operation, invocation) {
     const { snapshot, ownerId, input, interaction, adapter, presentation } = operation;
-    const { args, params = {}, options = {}, segments = [] } = invocation;
+    const { args, params = {}, options = {}, segments = [], match } = invocation;
     const context = createCapabilityContext({ snapshot, ownerId, signal: readOperationInputSignal(input), operation: operation.operation });
     const session = resolveCommandSession(input);
     const parameterValues = { __proto__: null, ...params };
@@ -192,6 +217,7 @@ export function createCommandContext(operation, invocation) {
         segments: freezeSegments(segments),
         ...(input !== undefined ? { input: input } : {}),
         ...(interaction !== undefined ? { interaction } : {}),
+        ...(match !== undefined ? { match: Object.freeze(match) } : {}),
     };
     Object.defineProperty(result, 'session', {
         enumerable: true,

package/package.json

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