@zhin.js/command 1.0.6 → 1.0.9

package/README.md

@@ -3,28 +3,36 @@
 Zhin Plugin Runtime 的约定式 Command Feature。它发现 `commands/**/*.ts(x)`，将插件树
 路径与文件路径投影为命令，并用 `segment-matcher` 同时匹配纯文本和 canonical IM segments。
 
+静态命令文件名可为 ASCII kebab（`hello.ts`）或 Unicode 名（`赞我.ts`）；动态参数文件
+（`[name].ts` 等）仍限 ASCII。详见 [命令创作指南](../../../docs/authoring/commands.md)。
+
 ## Authoring
 
 ```ts
 // commands/gh/issue/list.ts -> gh issue list
+// commands/赞我.ts -> 赞我
 import { defineCommand } from '@zhin.js/command';
 
 export default defineCommand({
   description: 'List GitHub issues',
+  alias: ['issues'],                 // 可多词；子插件仍保留 owner 前缀
+  permit: ['adapter(icqq)', 'role(master)'], // 数组 AND；未过则静默未命中
+  // shortcut: { '列 issue': {} },   // 全局整句，可打破命名空间
   execute: ({ args }) => `issues:${args.join(',')}`,
 });
 ```
 
-最后一个文件名可以声明参数：
+最后一个文件名可以用 Next.js 风格方括号声明参数形态，类型与默认值在 `defineCommand({ params })` 中声明（`type` 必填，`default` 可选且有默认值时文件名必须用双方括号）：
 
 ```text
-commands/gh/pr/[title:string=defaultTitle].ts -> gh pr [title]
-commands/upload/[asset:image].ts             -> upload <asset>
+commands/gh/pr/[[title]].ts   -> gh pr [title]    （params: { title: { type: 'string', default: 'defaultTitle' } }）
+commands/upload/[asset].ts    -> upload <asset>   （params: { asset: { type: 'image' } }）
+commands/search/[...kw].ts    -> search <...kw>   （params: { kw: { type: 'text' } }，运行时 params.kw 为数组；元素粒度随类型：text 逐消息段，word/string 逐词，number/boolean 逐词转换）
 ```
 
 文本类型包括 `string`、`word`、`text`、`number`、`integer`、`float`、`boolean`；结构化
 类型包括 `mention`、`image`、`face`、`reply`、`forward`、`dice`、`rps`。结构化类型
-直接从对应 segment 取值，不能声明文件名默认值。
+直接从对应 segment 取值，不能声明默认值。
 
 `execute()` 收到冻结的 `CommandContext`：
 
@@ -37,6 +45,12 @@ commands/upload/[asset:image].ts             -> upload <asset>
 - `scene`：`{ id, type, name? }` 场景对象。
 - `sender`：`{ id, name?, role: string[] }` 发送者对象。
 
+可选声明字段：
+
+- `alias`：替换全部本地静态段并重挂 owner 前缀（不打破子插件命名空间）。
+- `permit`：内置 DSL（`adapter|group|private|channel|user|role`）；失败为静默未命中。
+- `shortcut`：全局整句精确匹配 → 预填 `params`（可打破命名空间）。
+
 单文件插件可在 `setup({ addCommand })` 中调用
 `addCommand('hello', defineCommand(...))`。它与目录发现共用 CommandIndex；拆成文件后
 可获得单命令 HMR。

package/lib/command-index.d.ts

@@ -8,6 +8,10 @@ export interface CommandDescriptor {
     readonly description?: string;
     readonly source: string;
     readonly parameters: readonly CommandParameterDescriptor[];
+    readonly alias?: readonly string[];
+    readonly permit?: readonly string[];
+    /** shortcut 触发键列表（不含预填 params）。 */
+    readonly shortcut?: readonly string[];
 }
 export interface CommandDispatchResult {
     readonly matched: boolean;

package/lib/command-index.js

@@ -1,5 +1,7 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
-import { createCommandContext, } from './definition.js';
+import { createCommandContext, resolveCommandSession, } from './definition.js';
+import { permissionHostToken } from '@zhin.js/permission';
+import { toPermissionSubject } from '@zhin.js/permission';
 const segmentFields = {
     text: 'text',
     mention: 'target',
@@ -15,44 +17,83 @@ export class CommandIndex {
     snapshot;
     $projection = 'zhin.command-index/1';
     #commands;
+    #routes;
+    #shortcuts;
     constructor(slots, snapshot) {
         this.snapshot = snapshot;
         const commands = [];
-        const staticCommands = new Map();
-        const dynamicCommands = new Map();
+        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})`);
+            }
+            occupancy.set(key, source);
+        };
         for (const slot of slots) {
-            const segments = runtimeSegments(slot.owner, slot.localName);
+            const primarySegments = runtimeSegments(slot.owner, slot.localName);
             const parameter = slot.definition.$parameter;
-            assertParameterSegment(segments, parameter, slot.source);
-            const name = displayName(segments, parameter);
+            assertParameterSegment(primarySegments, parameter, slot.source);
+            const name = displayName(primarySegments, parameter);
+            const alias = normalizeAliasList(slot.definition.alias);
+            const permit = slot.definition.permit
+                ? Object.freeze([...slot.definition.permit])
+                : undefined;
+            const shortcutKeys = slot.definition.shortcut
+                ? Object.freeze(Object.keys(slot.definition.shortcut).map((key) => key.trim()))
+                : undefined;
             const record = Object.freeze({
                 name,
                 description: slot.definition.description,
                 source: slot.source,
                 parameters: Object.freeze(parameter ? [{
                         ...parameter,
-                        required: parameter.defaultValue === undefined,
+                        required: isRequiredParameter(parameter),
                     }] : []),
+                ...(alias ? { alias } : {}),
+                ...(permit ? { permit } : {}),
+                ...(shortcutKeys && shortcutKeys.length > 0 ? { shortcut: shortcutKeys } : {}),
                 slot,
-                segments: Object.freeze(segments),
+                segments: Object.freeze(primarySegments),
                 parameter,
-                matcher: new SegmentMatcher(matcherPattern(segments, parameter), segmentFields),
             });
-            if (!parameter) {
-                const key = segments.join(' ');
-                if (staticCommands.has(key))
-                    throw duplicateCommand(key);
-                staticCommands.set(key, record);
+            claim(occupancyKey(primarySegments, parameter), slot.source);
+            routes.push({
+                record,
+                segments: primarySegments,
+                matcher: new SegmentMatcher(matcherPattern(primarySegments, parameter), segmentFields),
+                kind: 'primary',
+            });
+            if (alias) {
+                for (const entry of alias) {
+                    const aliasSegments = aliasRuntimeSegments(slot.owner, entry, primarySegments);
+                    assertParameterSegment(aliasSegments, parameter, `${slot.source} alias ${JSON.stringify(entry)}`);
+                    claim(occupancyKey(aliasSegments, parameter), `${slot.source} alias ${JSON.stringify(entry)}`);
+                    routes.push({
+                        record,
+                        segments: Object.freeze(aliasSegments),
+                        matcher: new SegmentMatcher(matcherPattern(aliasSegments, parameter), segmentFields),
+                        kind: 'alias',
+                    });
+                }
             }
-            else {
-                const shape = routeShape(segments);
-                if (dynamicCommands.has(shape))
-                    throw duplicateCommand(name);
-                dynamicCommands.set(shape, record);
+            if (slot.definition.shortcut) {
+                for (const [rawTrigger, prefill] of Object.entries(slot.definition.shortcut)) {
+                    const trigger = rawTrigger.trim();
+                    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)}`)),
+                    });
+                }
             }
             commands.push(record);
         }
-        this.#commands = Object.freeze(commands.sort(compareCommands));
+        this.#commands = Object.freeze(commands.sort(compareRecords));
+        this.#routes = Object.freeze(routes.sort(compareRoutes));
+        this.#shortcuts = shortcuts;
     }
     list() {
         return this.#commands.map(toDescriptor);
@@ -73,12 +114,29 @@ export class CommandIndex {
             this.#diagnoseParameter(name);
             throw new Error(`Unknown Command: ${name}`);
         }
+        // Host / 无 session：跳过 permit。
         return match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params));
     }
     async dispatch(input, source = undefined) {
+        const shortcut = this.#matchShortcut(input);
+        if (shortcut) {
+            if (!(await this.#permitAllows(shortcut.record, source))) {
+                return Object.freeze({ matched: false });
+            }
+            const value = await shortcut.record.slot.definition.execute(createCommandContext(this.snapshot, shortcut.record.slot.owner, Object.freeze([]), shortcut.params, source, Object.freeze([])));
+            return Object.freeze({
+                matched: true,
+                command: shortcut.record.name,
+                owner: shortcut.record.slot.owner,
+                value,
+            });
+        }
         const match = this.#match(input, false);
         if (!match)
             return Object.freeze({ matched: false });
+        if (!(await this.#permitAllows(match.command, source))) {
+            return Object.freeze({ matched: false });
+        }
         const args = textArgs(match.remaining);
         const value = await match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params, source, match.remaining));
         return Object.freeze({
@@ -88,6 +146,38 @@ export class CommandIndex {
             value,
         });
     }
+    async #permitAllows(record, source) {
+        const permits = record.permit;
+        if (!permits || permits.length === 0)
+            return true;
+        if (!hasImSession(source))
+            return true;
+        const host = this.#resolveHost();
+        if (!host)
+            return false;
+        const subject = toPermissionSubject(resolveCommandSession(source));
+        return host.checkAll(permits, subject);
+    }
+    #resolveHost() {
+        try {
+            const resources = this.snapshot.resources.get(this.snapshot.root);
+            if (!resources)
+                return undefined;
+            const host = resources.get(permissionHostToken.id);
+            return host && typeof host.check === 'function'
+                ? host
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #matchShortcut(input) {
+        const text = exactMessageText(input);
+        if (text === undefined)
+            return undefined;
+        return this.#shortcuts.get(text);
+    }
     #match(input, exact) {
         const segments = normalizeSegments(typeof input === 'string'
             ? input.trim()
@@ -96,16 +186,30 @@ export class CommandIndex {
             : input);
         if (segments.length === 0)
             return undefined;
-        for (const command of this.#commands) {
-            const result = command.matcher.match(asMatcherSegments(segments));
+        for (const route of this.#routes) {
+            const result = route.matcher.match(asMatcherSegments(segments));
             if (!result || !hasCommandBoundary(result.remaining))
                 continue;
+            const parameter = route.record.parameter;
+            const params = { ...result.params };
+            if (parameter?.rest) {
+                const raw = result.params[parameter.name];
+                const coerced = coerceRestValues(parameter, Array.isArray(raw) ? raw : []);
+                if (!coerced || (isRequiredParameter(parameter) && coerced.length === 0))
+                    continue;
+                params[parameter.name] = coerced;
+            }
             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];
+            }
             return {
-                command,
-                params: Object.freeze({ ...result.params }),
+                command: route.record,
+                params: Object.freeze(params),
                 remaining,
             };
         }
@@ -113,14 +217,14 @@ export class CommandIndex {
     }
     #diagnoseParameter(name) {
         const words = splitCommand(name);
-        for (const command of this.#commands) {
-            const parameter = command.parameter;
-            if (!parameter)
+        for (const route of this.#routes) {
+            const parameter = route.record.parameter;
+            if (!parameter || parameter.rest)
                 continue;
-            const parameterIndex = command.segments.findIndex((segment) => segment.startsWith('$'));
-            if (words.length !== command.segments.length)
+            const parameterIndex = route.segments.findIndex((segment) => segment.startsWith('$'));
+            if (words.length !== route.segments.length)
                 continue;
-            if (!command.segments.every((segment, index) => index === parameterIndex || segment === words[index]))
+            if (!route.segments.every((segment, index) => index === parameterIndex || segment === words[index]))
                 continue;
             const value = words[parameterIndex];
             if (value === undefined || matchesParameter(parameter.type, value))
@@ -146,6 +250,82 @@ function runtimeSegments(owner, localName) {
     const prefix = owner.slice('root/'.length).split('/').join('.');
     return [`${prefix}.${localSegments[0]}`, ...localSegments.slice(1)];
 }
+/**
+ * 用 alias 词序列替换全部本地静态段，再按 owner 规则重挂前缀；动态段保留。
+ */
+function aliasRuntimeSegments(owner, alias, primarySegments) {
+    const aliasTokens = alias.trim().split(/\s+/u).filter(Boolean);
+    const dynamicTail = primarySegments.filter((segment) => segment.startsWith('$'));
+    if (owner === 'root')
+        return [...aliasTokens, ...dynamicTail];
+    const prefix = owner.slice('root/'.length).split('/').join('.');
+    return [`${prefix}.${aliasTokens[0]}`, ...aliasTokens.slice(1), ...dynamicTail];
+}
+function occupancyKey(segments, parameter) {
+    return parameter ? routeShape(segments) : segments.join(' ');
+}
+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) {
+    const allowed = new Set();
+    const parameter = definition.$parameter;
+    if (parameter)
+        allowed.add(parameter.name);
+    if (definition.params) {
+        for (const key of Object.keys(definition.params))
+            allowed.add(key);
+    }
+    for (const key of Object.keys(prefill)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`Invalid shortcut params for ${source}: unknown key ${JSON.stringify(key)}`);
+        }
+    }
+    const result = { ...prefill };
+    if (parameter) {
+        if (result[parameter.name] === undefined) {
+            if (parameter.defaultValue !== undefined) {
+                result[parameter.name] = parameter.defaultValue;
+            }
+            else if (isRequiredParameter(parameter)) {
+                throw new TypeError(`Invalid shortcut params for ${source}: missing required ${parameter.name}`);
+            }
+        }
+    }
+    else if (allowed.size === 0 && Object.keys(prefill).length > 0) {
+        throw new TypeError(`Invalid shortcut params for ${source}: command has no params declaration`);
+    }
+    if (definition.params) {
+        for (const [name, schema] of Object.entries(definition.params)) {
+            if (result[name] === undefined && schema.default !== undefined) {
+                result[name] = schema.default;
+            }
+        }
+    }
+    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();
+        return trimmed || undefined;
+    }
+    // 仅纯单 text 段可作整句 shortcut；含 mention/image 等则不走 shortcut。
+    if (input.length !== 1)
+        return undefined;
+    const only = input[0];
+    if (!only || only.type !== 'text' || typeof only.data.text !== 'string')
+        return undefined;
+    const trimmed = only.data.text.trim();
+    return trimmed || undefined;
+}
 function assertParameterSegment(segments, parameter, source) {
     const dynamicSegments = segments.filter((segment) => segment.startsWith('$'));
     if (!parameter && dynamicSegments.length === 0)
@@ -154,15 +334,26 @@ function assertParameterSegment(segments, parameter, source) {
         && dynamicSegments[0] === `$${parameter.name}`
         && segments.at(-1) === dynamicSegments[0])
         return;
-    throw new Error(`Broken dynamic Command identity for ${source}`);
+    const dynamic = dynamicSegments[0] ?? (parameter ? `$${parameter.name}` : '$?');
+    throw new Error(`Invalid Command path for ${source}: the dynamic segment "${dynamic}" must be the only dynamic `
+        + `segment and come after a static segment (child plugin commands are prefixed by the plugin `
+        + `path, so a dynamic first segment is never reachable). `
+        + (parameter
+            ? `Hint: move the file under a static directory, e.g. "commands/add/[${parameter.name}:${parameter.type}].ts".`
+            : 'Hint: put the file under a static directory, e.g. "commands/add/<file>.ts".'));
+}
+function isRequiredParameter(parameter) {
+    return parameter.optional === true ? false : parameter.defaultValue === undefined;
 }
 function displayName(segments, parameter) {
     return segments.map((segment) => {
         if (!segment.startsWith('$'))
             return segment;
-        return parameter?.defaultValue === undefined
-            ? `<${segment.slice(1)}>`
-            : `[${segment.slice(1)}]`;
+        const label = segment.slice(1);
+        const required = !parameter || isRequiredParameter(parameter);
+        if (parameter?.rest)
+            return required ? `<...${label}>` : `[...${label}]`;
+        return required ? `<${label}>` : `[${label}]`;
     }).join(' ');
 }
 function matcherPattern(segments, parameter) {
@@ -172,25 +363,72 @@ function matcherPattern(segments, parameter) {
         if (!parameter)
             throw new Error(`Missing Command parameter metadata: ${segment}`);
         const type = matcherType(parameter.type);
+        if (parameter.rest) {
+            return `[...${parameter.name}:${isStructuredRestType(parameter.type) ? type : 'text'}]`;
+        }
+        if (isRequiredParameter(parameter))
+            return `<${parameter.name}:${type}>`;
         return parameter.defaultValue === undefined
-            ? `<${parameter.name}:${type}>`
+            ? `[${parameter.name}:${type}]`
             : `[${parameter.name}:${type}=${String(parameter.defaultValue)}]`;
     }).join(' ');
 }
 function matcherType(type) {
     return type === 'string' ? 'word' : type;
 }
+function isStructuredRestType(type) {
+    return type === 'mention'
+        || type === 'image'
+        || type === 'face'
+        || type === 'reply'
+        || type === 'forward'
+        || type === 'dice'
+        || type === 'rps';
+}
+function coerceRestValues(parameter, values) {
+    const type = parameter.type;
+    if (type === 'text' || isStructuredRestType(type)) {
+        return values;
+    }
+    const words = values.flatMap((value) => typeof value === 'string' ? value.split(/\s+/u).filter(Boolean) : []);
+    if (type === 'string' || type === 'word')
+        return words;
+    if (type === 'number' || type === 'integer' || type === 'float') {
+        const numbers = [];
+        for (const [index, word] of words.entries()) {
+            const number = Number(word);
+            if (!Number.isFinite(number)
+                || (type === 'integer' && !Number.isInteger(number))
+                || (type === 'float' && !word.includes('.')))
+                return undefined;
+            numbers[index] = number;
+        }
+        return numbers;
+    }
+    if (type === 'boolean') {
+        if (!words.every((word) => word === 'true' || word === 'false'))
+            return undefined;
+        return words.map((word) => word === 'true');
+    }
+    return undefined;
+}
 function routeShape(segments) {
     return segments.map((segment) => segment.startsWith('$') ? '$' : segment).join(' ');
 }
-function compareCommands(left, right) {
-    const leftDynamic = left.parameter ? 1 : 0;
-    const rightDynamic = right.parameter ? 1 : 0;
-    return leftDynamic - rightDynamic
+function compareRecords(left, right) {
+    return left.name.localeCompare(right.name);
+}
+function compareRoutes(left, right) {
+    return dynamicWeight(left) - dynamicWeight(right)
         || staticSegmentCount(right.segments) - staticSegmentCount(left.segments)
         || right.segments.length - left.segments.length
-        || right.name.length - left.name.length
-        || left.name.localeCompare(right.name);
+        || right.record.name.length - left.record.name.length
+        || left.record.name.localeCompare(right.record.name);
+}
+function dynamicWeight(route) {
+    if (!route.record.parameter)
+        return 0;
+    return route.record.parameter.rest ? 2 : 1;
 }
 function staticSegmentCount(segments) {
     return segments.filter((segment) => !segment.startsWith('$')).length;
@@ -251,12 +489,9 @@ function textArgs(segments) {
         return splitCommand(segment.data.text);
     }));
 }
-function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, matcher: _matcher, ...descriptor }) {
+function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, ...descriptor }) {
     return descriptor;
 }
-function duplicateCommand(name) {
-    return new Error(`Duplicate runtime Command: ${name}`);
-}
 export class CommandParameterValueError extends TypeError {
     constructor(name, type, value) {
         super(`Invalid value for Command parameter ${name}:${type}: ${value}`);

package/lib/definition.d.ts

@@ -2,7 +2,18 @@ import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import { type CapabilityContext } from '@zhin.js/feature-kit';
 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 | Readonly<Record<string, unknown>> | null;
+export type CommandParameterValue = string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null;
+export declare const commandParameterTypes: ReadonlySet<CommandParameterType>;
+/**
+ * Next.js 风格参数声明（`defineCommand({ params: ... })`）。
+ * 文件名只声明参数形态（`[name]` / `[[name]]` / `[...name]` / `[[...name]]`），
+ * 类型与默认值统一在这里声明。
+ */
+export interface CommandParamSchema {
+    readonly type: CommandParameterType;
+    readonly default?: CommandParameterValue;
+    readonly description?: string;
+}
 /** Minimal structural contract shared with canonical IM segments. */
 export interface CommandSegment {
     readonly type: string | {
@@ -14,6 +25,11 @@ export interface CommandParameterDefinition {
     readonly name: string;
     readonly type: CommandParameterType;
     readonly defaultValue?: CommandParameterValue;
+    /** `[[name]]` / `[[...name]]` 可选段；缺省按 `defaultValue === undefined` 推断。 */
+    readonly optional?: boolean;
+    /** `[...name]` / `[[...name]]` 捕获所有段，运行时值为 `string[]`。 */
+    readonly rest?: boolean;
+    readonly description?: string;
 }
 /** 场景：群 / 私聊 / 频道等。 */
 export interface CommandScene {
@@ -30,6 +46,24 @@ export interface CommandSender {
     readonly name?: string;
     readonly role: readonly string[];
 }
+/**
+ * 命令侧入站会话契约（结构对齐 `@zhin.js/im-contract` 的 ConversationRef；
+ * command 为 Feature 层，不能 import core / IM 契约包，故独立声明）。
+ */
+export interface CommandConversation {
+    readonly endpoint: Readonly<{
+        readonly id: string;
+        /** 适配器插件 owner（PluginId），与 `snapshot.config.get(adapter)` 对齐。 */
+        readonly adapter: string;
+    }>;
+    readonly kind: 'private' | 'group' | 'channel';
+    readonly id: string;
+    readonly parent?: Readonly<{
+        readonly kind: 'private' | 'group' | 'channel';
+        readonly id: string;
+    }>;
+    readonly threadId?: string;
+}
 /**
  * 命令侧入站消息契约。
  *
@@ -37,17 +71,39 @@ export interface CommandSender {
  * 因架构分层（command 为 Feature 层，不能 import core），此处独立声明。
  */
 export interface CommandMessage {
-    readonly adapter: string;
-    readonly target: string;
+    readonly conversation: CommandConversation;
     readonly content: string;
-    /** 发送者 id（扁平字段；结构化视图见 CommandContext.sender）。 */
-    readonly sender?: string;
+    /** 发送者（结构化视图见 CommandContext.sender）。 */
+    readonly sender?: {
+        readonly id: string;
+        readonly name?: string;
+        readonly roles?: readonly string[];
+    };
     readonly id?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
     /** 若上游已结构化，优先采用。 */
     readonly scene?: CommandScene;
-    readonly $reply?: (content: unknown) => Promise<unknown>;
-    readonly $replyFrom?: (requester: string, content: unknown) => Promise<unknown>;
+    $reply?(content: unknown): Promise<unknown>;
+    $replyFrom?(requester: string, content: unknown): Promise<unknown>;
+    /** 向同 Endpoint 的另一个通道发送消息（结构兼容 `Message.$sendTo`）。 */
+    $sendTo?(conversation: {
+        readonly kind: 'private' | 'group' | 'channel';
+        readonly id: string;
+        readonly parent?: Readonly<{
+            readonly kind: 'private' | 'group' | 'channel';
+            readonly id: string;
+        }>;
+        readonly threadId?: string;
+    }, content: unknown): Promise<unknown>;
+    /** 私信当前消息的发送者（结构兼容 `Message.$replyToPrivate`）。 */
+    $replyToPrivate?(content: unknown, from?: boolean | {
+        readonly kind: 'group' | 'channel';
+        readonly id: string;
+    }): Promise<unknown>;
+    /** 向指定群发送消息（结构兼容 `Message.$replyToGroup`）。 */
+    $replyToGroup?(groupId: string, content: unknown): Promise<unknown>;
+    /** 向指定频道发送消息（结构兼容 `Message.$replyToChannel`）。 */
+    $replyToChannel?(channelId: string, guildId: string, content: unknown, threadId?: string): Promise<unknown>;
 }
 /**
  * IM 入站快捷字段。
@@ -82,6 +138,26 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
     readonly $feature: typeof commandBrand;
     readonly $parameter?: CommandParameterDefinition;
     readonly description?: string;
+    /**
+     * Next.js 风格参数声明：动态段文件名（`[name]` 等）的形态配合这里的
+     * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
+     */
+    readonly params?: Readonly<Record<string, CommandParamSchema>>;
+    /**
+     * 本地静态段别名（可多词，如 `'gh issue'`）。替换全部本地静态段后仍挂
+     * owner 前缀；不打破子插件命名空间。
+     */
+    readonly alias?: readonly string[];
+    /**
+     * 内置 permit DSL（AND）。单项内逗号为 OR。
+     * 例：`adapter(icqq)`、`role(master)`、`group(123,456)`。
+     */
+    readonly permit?: readonly string[];
+    /**
+     * 全局整句快捷方式：触发串（trim 后全文相等）→ 预填 params。
+     * 可打破 owner 命名空间。
+     */
+    readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandParameterValue>>>>;
     execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
 declare module '@zhin.js/plugin-runtime' {