@zhin.js/command 1.1.17 → 1.2.1

package/README.md

@@ -16,7 +16,7 @@ import { defineCommand } from 'zhin.js/command';
 export default defineCommand({
   description: 'List GitHub issues',
   alias: ['issues'],                 // 可多词；owner 不参与用户路由
-  permit: ['adapter(icqq)', 'role(master)'], // 数组 AND；失败返回 denied
+  permit: ['adapter(icqq)', 'owner'], // 数组 AND；失败返回 denied
   // shortcut: { '列 issue': {} },   // 全局整句
   execute: ({ args }) => `issues:${args.join(',')}`,
 });
@@ -154,7 +154,7 @@ parent 和 thread 独立计算。没有完整可信身份或真实 IM operation
 新策略的并发数用于新准入，原来已开始的冷却保留到原到期时间。移除策略即停止新请求的预算检查。
 状态只保留在当前进程，进程重启后重置；容量满时拒绝新身份，不驱逐活跃或仍在冷却的记录。
 
-进度默认关闭，只在业务等待阶段发送一次“正在处理中，请稍候。”，走当前平台统一发送链路。
+进度默认关闭，只在业务等待阶段发送一次“正在处理中，请稍候。”（按当前操作的语言本地化），走当前平台统一发送链路。
 开始自动最终回复前停止尚未开始的提示，并等待已开始的提示完成；已开始的 I/O 随原 lease 排空。
 执行内显式 `$reply()` 不会停止进度计时。提示失败不重试，也不表示任务取消或远端已经展示。
 `@zhin.js/command/internal/execution` 是 Core 装配使用的内部入口，不是插件创作 API。
@@ -173,7 +173,7 @@ pnpm --filter @zhin.js/command test
 ```
 
 完整用户契约见[命令创作指南](../../../docs/authoring/commands.md)，架构迁移背景见
-[Plugin Runtime 原位迁移](../../../docs/architecture/target-implementation/in-place-migration.md)。
+[Legacy 概念迁移](../../../docs/contributing/legacy-concepts.md)。
 
 
 命令可声明 `descriptionI18n: { en: 'Create a reminder' }` 翻译描述。若静态目录名是中文，可沿用 `alias` 提供英文入口，并用 `preferredAliasI18n` 显式选择英文展示：

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 {
@@ -46,6 +48,14 @@ export interface CommandDispatchResult {
     readonly owner?: PluginId;
     readonly value?: unknown;
     readonly menu?: CommandMenuPage;
+    /**
+     * `denied` only: the first unmet permit and a one-sentence reason for the sender (e.g. 「机器人不是本群管理员」).
+     * Undefined when no Permission host / source answered.
+     */
+    readonly denial?: Readonly<{
+        permit: string;
+        reason: string;
+    }>;
 }
 /** Semantic menu navigation; the IM composition layer supplies platform controls. */
 export interface CommandMenuNavigation {

package/lib/command-index.js

@@ -1,7 +1,7 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
 import { htmlRendererToken, resolveLocale, } from '@zhin.js/plugin-runtime';
 import { bindOperationInput } from '@zhin.js/feature-kit';
-import { permissionHostToken, } from '@zhin.js/permission';
+import { describeDeniedPermit, permissionHostToken, } from '@zhin.js/permission';
 import { commandAdapterMatches, toCommandPermissionSubject } from './permission-explanation.js';
 import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp, commandValidationIssue } from './arguments.js';
 import { commandDescription, commandMessages } from './messages.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))])]))),
@@ -175,7 +176,7 @@ export class CommandIndex {
             this.#diagnoseParameter(name);
             throw new Error(`Unknown Command: ${name}`);
         }
-        if (!(await this.#permitAllows(match.command, undefined, operationSnapshot)))
+        if ((await this.#permitDenial(match.command, undefined, operationSnapshot)) !== undefined)
             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(' ') } }] : [])];
@@ -201,7 +202,7 @@ export class CommandIndex {
         const prefix = commandPrefix ?? '';
         if (this.#menu) {
             const keyword = this.#menu.keyword ?? commandMessages(locale, 'menuKeyword');
-            const menuResult = this.#dispatchMenu(input, { commandPrefix: prefix, snapshot: operationSnapshot, locale, keyword });
+            const menuResult = await this.#dispatchMenu(input, { commandPrefix: prefix, snapshot: operationSnapshot, locale, keyword, source });
             if (menuResult !== undefined) {
                 return Object.freeze({
                     matched: true,
@@ -213,17 +214,19 @@ 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)
                 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 candidateDenial = await this.#permitDenial(candidate, source, operationSnapshot);
+            if (candidateDenial !== undefined)
+                return this.#denied(candidate, candidateDenial, locale);
             const help = commandHelp(commandDisplayName(candidate, locale), candidate.slot.definition, prefix, locale);
             const segments = normalizeSegments(typeof input === 'string' ? [{ type: 'text', data: { text: input } }] : input);
             if (requestsCommandHelp(segments))
@@ -233,8 +236,9 @@ export class CommandIndex {
         }
         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 denial = await this.#permitDenial(match.command, source, operationSnapshot);
+        if (denial !== undefined)
+            return this.#denied(match.command, denial, locale);
         const definition = match.command.slot.definition;
         const authorSource = bindOperationInput(source, match.command.slot.owner, operationSnapshot);
         const help = commandHelp(commandDisplayName(match.command, locale), definition, prefix, locale);
@@ -255,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 {
@@ -265,34 +270,60 @@ export class CommandIndex {
             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 });
+    #denied(record, permit, locale) {
+        return Object.freeze({ matched: true, status: 'denied', command: record.name, owner: record.slot.owner,
+            ...(permit ? { denial: Object.freeze({ permit, reason: describeDeniedPermit(permit, locale) }) } : {}) });
     }
     /** 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);
+        // segment-matcher clones its input before matching, so one copy serves every route.
+        const matcherSegments = asMatcherSegments(segments);
         for (const route of this.#routes) {
             if (!route.record.parameter)
                 continue;
-            const result = route.literalMatcher?.match(asMatcherSegments(segments));
+            const result = route.literalMatcher?.match(matcherSegments);
             if (result && hasCommandBoundary(result.remaining))
                 return route.record;
         }
         return undefined;
     }
-    async #permitAllows(record, source, operationSnapshot) {
+    /**
+     * ADR 0056 §5: the shared evaluator (PermissionHost) over the three dimensions — sender zhin role,
+     * sender platform standing and the Bot's own standing (resolved from the Adapter index cache).
+     * `undefined` = allowed; a permit string = the first unmet one; `null` = denied without a reason
+     * (no source or no Permission host).
+     */
+    async #permitDenial(record, source, operationSnapshot, cachedOnly = false) {
         const permits = record.permit;
         if (!permits || permits.length === 0)
-            return true;
+            return undefined;
         if (!source || typeof source !== 'object')
-            return false;
+            return null;
         const host = this.#resolveHost(operationSnapshot);
         if (!host)
-            return false;
+            return null;
         const subject = toCommandPermissionSubject(source);
         if (!subject.sender?.id && !subject.scene?.id && !subject.adapter && !subject.endpoint)
+            return null;
+        const options = { source, ...(cachedOnly ? { cachedOnly } : {}) };
+        if (await host.checkAll(permits, subject, options))
+            return undefined;
+        // Denied: name the first unmet permit for the reply (same evaluator; Bot standing is cached now).
+        try {
+            return (await host.firstDenied?.(permits, subject, options)) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Whether the menu should list `record` for `source` (adapter restriction + permits). */
+    async #listable(record, source, operationSnapshot) {
+        if (source === undefined)
+            return true;
+        if (!commandAdapterMatches(record, source))
             return false;
-        return host.checkAll(permits, subject);
+        return (await this.#permitDenial(record, source, operationSnapshot)) === undefined;
     }
     #resolveHost(operationSnapshot) {
         try {
@@ -308,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)
@@ -322,14 +365,16 @@ export class CommandIndex {
             : input);
         if (segments.length === 0)
             return undefined;
+        // segment-matcher clones its input before matching, so one copy serves every route.
+        const matcherSegments = asMatcherSegments(segments);
         for (const route of this.#routes) {
             // Options may appear between the literal route and a directory-bound parameter.
-            const literalResult = !exact ? route.literalMatcher?.match(asMatcherSegments(segments)) : undefined;
+            const literalResult = !exact ? route.literalMatcher?.match(matcherSegments) : 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));
+            const result = parseDeclaredArguments ? literalResult : route.matcher.match(matcherSegments);
             if (!result || !hasCommandBoundary(result.remaining))
                 continue;
             const parameter = route.record.parameter;
@@ -380,7 +425,7 @@ export class CommandIndex {
     // ==========================================================================
     // 内置菜单命令
     // ==========================================================================
-    #dispatchMenu(input, context) {
+    async #dispatchMenu(input, context) {
         const { commandPrefix, keyword, locale } = context;
         const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
         if (text === undefined)
@@ -414,7 +459,7 @@ export class CommandIndex {
         }
         return undefined;
     }
-    #buildMenu({ pluginKey, page = 1 }, { commandPrefix, keyword, snapshot, locale }) {
+    async #buildMenu({ pluginKey, page = 1 }, { commandPrefix, keyword, snapshot, locale, source }) {
         const root = snapshot.root;
         const targetId = pluginKey
             ? `${root}/${pluginKey.split('.').join('/')}`
@@ -422,15 +467,17 @@ export class CommandIndex {
         const node = snapshot.tree.get(targetId);
         if (!node)
             return { value: commandMessages(locale, 'missingPlugin', { plugin: pluginKey ?? '' }) };
-        const directCommands = this.#commands.filter((cmd) => cmd.slot.owner === targetId);
+        const listable = await Promise.all(this.#commands.map(async (cmd) => (await this.#listable(cmd, source, snapshot)) ? cmd : undefined));
+        const available = listable.filter((cmd) => cmd !== undefined);
+        const directCommands = available.filter((cmd) => cmd.slot.owner === targetId);
         const children = node.children
             .map((childId) => snapshot.tree.get(childId))
             .filter((child) => !!child);
         const effectiveCommands = targetId === root
             && directCommands.length === 0
-            && this.#commands.length > 0
-            && this.#commands.length <= MENU_PAGE_SIZE
-            ? this.#commands
+            && available.length > 0
+            && available.length <= MENU_PAGE_SIZE
+            ? available
             : directCommands;
         const pages = Math.max(1, Math.ceil((effectiveCommands.length + children.length) / MENU_PAGE_SIZE));
         const invocation = `${commandPrefix}${keyword}${pluginKey ? ` ${pluginKey}` : ''}`;
@@ -849,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

@@ -112,7 +112,19 @@ export interface CommandScene {
 export interface CommandSender {
     readonly id: string;
     readonly name?: string;
-    readonly role: readonly string[];
+    /** Highest zhin chat role effective in this conversation (ADR 0056), set by the Runtime. */
+    readonly chatRole?: 'owner' | 'admin' | 'trusted';
+    /** Per role, the topmost level it is held at on this conversation's chain, set by the Runtime. */
+    readonly chatRoleLevels?: Readonly<Partial<Record<'owner' | 'admin' | 'trusted', 'global' | 'adapter' | 'endpoint' | 'conversation'>>>;
+    /** Normalized platform standing; absent in private chats. */
+    readonly platform?: Readonly<{
+        standing: 'owner' | 'admin' | 'member' | 'guest';
+        roles?: readonly Readonly<{
+            id: string;
+            name?: string;
+        }>[];
+        permissions?: readonly string[];
+    }>;
 }
 /**
  * 命令侧入站会话契约（结构对齐 `@zhin.js/im-contract` 的 ConversationRef；
@@ -147,7 +159,9 @@ export interface CommandMessage {
     readonly sender?: {
         readonly id: string;
         readonly name?: string;
-        readonly roles?: readonly string[];
+        readonly chatRole?: CommandSender['chatRole'];
+        readonly chatRoleLevels?: CommandSender['chatRoleLevels'];
+        readonly platform?: CommandSender['platform'];
     };
     readonly id?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -240,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. */
@@ -265,7 +284,7 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
     readonly preferredAliasI18n?: Readonly<Partial<Record<Locale, string>>>;
     /**
      * 内置 permit DSL（AND）。单项内逗号为 OR。
-     * 例：`adapter(icqq)`、`role(master)`、`group(123,456)`。
+     * 例：`adapter(icqq)`、`owner`、`trusted`、`platform:admin`、`group(123,456)`。
      */
     readonly permit?: readonly string[];
     /** Optional full-operation cooldown, concurrency and one-shot progress feedback. */
@@ -275,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' {
@@ -286,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>;
@@ -325,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. */
@@ -341,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,
@@ -213,14 +239,12 @@ export function resolveCommandSession(input) {
     if (operation) {
         const endpoint = input && typeof input === 'object' ? input.endpointId : undefined;
         const sender = operation.sender;
-        const roles = [...new Set([...sender?.authorizationRoles ?? [], ...sender?.platformRoles ?? []])];
         return Object.freeze({
             adapter: operation.scene.endpoint.adapter,
             ...(typeof endpoint === 'string' && endpoint ? { endpoint } : {}),
             scene: Object.freeze({ id: operation.scene.id, type: operation.scene.kind,
                 ...(operation.scene.name !== undefined ? { name: operation.scene.name } : {}) }),
-            ...(sender ? { sender: Object.freeze({ id: sender.id, ...(sender.name !== undefined ? { name: sender.name } : {}),
-                    role: Object.freeze(roles.length ? roles : ['user']) }) } : {}),
+            ...(sender ? { sender: freezeSender(sender) } : {}),
         });
     }
     if (!isCommandMessageLike(input))
@@ -281,38 +305,8 @@ export function resolveCommandSender(input, metadata) {
     if (!id)
         return undefined;
     const name = input.sender?.name || firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
-    const role = resolveRoles(input, metadata);
-    return Object.freeze({
-        id,
-        ...(name !== undefined ? { name } : {}),
-        role,
-    });
-}
-function resolveRoles(input, metadata) {
-    if (input.sender?.roles?.length) {
-        return Object.freeze([...input.sender.roles]);
-    }
-    const roles = [];
-    const push = (value) => {
-        if (typeof value !== 'string')
-            return;
-        const trimmed = value.trim();
-        if (trimmed && !roles.includes(trimmed))
-            roles.push(trimmed);
-    };
-    if (Array.isArray(metadata?.roles)) {
-        for (const item of metadata.roles)
-            push(item);
-    }
-    push(metadata?.senderRole);
-    push(metadata?.role);
-    if (metadata?.isMaster === true)
-        push('master');
-    if (metadata?.isTrusted === true)
-        push('trusted');
-    if (roles.length === 0)
-        roles.push('user');
-    return Object.freeze(roles);
+    // Roles come only from the Runtime-set sender fields, never from metadata (ADR 0056).
+    return freezeSender({ ...(input.sender ?? {}), id, ...(name !== undefined ? { name } : {}) });
 }
 function isCommandScene(value) {
     if (!value || typeof value !== 'object')
@@ -329,14 +323,31 @@ function isCommandSender(value) {
     const sender = value;
     return typeof sender.id === 'string'
         && sender.id.length > 0
-        && Array.isArray(sender.role)
-        && sender.role.every((item) => typeof item === 'string');
+        && (sender.chatRole === undefined || isChatRoleName(sender.chatRole));
+}
+function isChatRoleName(value) {
+    return value === 'owner' || value === 'admin' || value === 'trusted';
+}
+const STANDINGS = new Set(['owner', 'admin', 'member', 'guest']);
+const LEVELS = new Set(['global', 'adapter', 'endpoint', 'conversation']);
+function chatRoleLevelsOf(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const levels = Object.fromEntries(['owner', 'admin', 'trusted']
+        .filter(role => LEVELS.has(String(value[role])))
+        .map(role => [role, value[role]]));
+    return Object.keys(levels).length ? Object.freeze(levels) : undefined;
 }
 function freezeSender(sender) {
+    const platform = sender.platform && typeof sender.platform === 'object'
+        && STANDINGS.has(String(sender.platform.standing))
+        ? sender.platform : undefined;
     return Object.freeze({
         id: sender.id,
         ...(sender.name !== undefined ? { name: sender.name } : {}),
-        role: Object.freeze([...sender.role]),
+        ...(isChatRoleName(sender.chatRole) ? { chatRole: sender.chatRole } : {}),
+        ...(isChatRoleName(sender.chatRole) && chatRoleLevelsOf(sender.chatRoleLevels) ? { chatRoleLevels: chatRoleLevelsOf(sender.chatRoleLevels) } : {}),
+        ...(platform ? { platform } : {}),
     });
 }
 function firstString(...values) {

package/lib/execution-runtime.d.ts

@@ -1,5 +1,5 @@
 /** Internal composition contract. Not part of the command authoring facade. */
-import { type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { CommandExecutionLimit, CommandExecutionPolicy } from './execution-policy.js';
 interface ConversationIdentity {
     readonly endpoint: {
@@ -55,6 +55,8 @@ export declare class CommandExecutionBudget {
         readonly conversation: ConversationIdentity;
         readonly senderId?: string;
         readonly retirementSignal: AbortSignal;
+        /** The operation's language for progress feedback; defaults to the catalog default. */
+        readonly locale?: Locale;
         readonly reply: (owner: PluginId, text: string) => Promise<unknown>;
     }): CommandOperationController;
 }

package/lib/execution-runtime.js

@@ -1,5 +1,6 @@
 /** Internal composition contract. Not part of the command authoring facade. */
 import { createToken } from '@zhin.js/plugin-runtime';
+import { commandMessages } from './messages.js';
 /** @internal Admission-only Root resource; no bind or finish authority is published. */
 export const commandExecutionAdmissionToken = createToken('zhin.command.execution-admission');
 /** @internal Root-instance-owned state shared by projections and draining retired generations. */
@@ -26,7 +27,7 @@ export class CommandExecutionBudget {
         const operation = {
             snapshot: input.snapshot, key: valid ? Object.freeze(values) : undefined,
             active: true, progressStopped: false, admitted: false, signal: input.retirementSignal,
-            reply: input.reply, releases: [], timers: new Set(), feedback: [], accepted: new Set(), sends: new Set(),
+            locale: input.locale, reply: input.reply, releases: [], timers: new Set(), feedback: [], accepted: new Set(), sends: new Set(),
         };
         const stop = () => {
             operation.progressStopped = true;
@@ -136,7 +137,7 @@ export class CommandExecutionBudget {
                 // Observe failure once. Never retry uncertain delivery and never expose the exception.
                 let send;
                 try {
-                    send = Promise.resolve(operation.reply(owner, '正在处理中，请稍候。')).then(() => { }, () => { });
+                    send = Promise.resolve(operation.reply(owner, commandMessages(operation.locale, 'progress'))).then(() => { }, () => { });
                 }
                 catch {
                     send = Promise.resolve();

package/lib/index.d.ts

@@ -7,7 +7,7 @@ export * from './command-index.js';
 /** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
 export * from './permission-explanation.js';
-export { CONVERSATION_MANAGER_PERMIT, canManageConversation, assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, type ParsedPermit, type PermitKind, } from './permit.js';
+export { CONVERSATION_MANAGER_PERMIT, canManageConversation, assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, removedPermitReplacement, parsePermitName, type ParsedPermit, type PermitKind, } from './permit.js';
 export { bindCommandSource, CommandPathSyntaxError, commandFeatureId, type BoundCommandSource, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';
 export type { CommandValidationIssue, CommandValidationIssueCode } from './arguments.js';

package/lib/index.js

@@ -7,6 +7,6 @@ export * from './command-index.js';
 /** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
 export * from './permission-explanation.js';
-export { CONVERSATION_MANAGER_PERMIT, canManageConversation, assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, } from './permit.js';
+export { CONVERSATION_MANAGER_PERMIT, canManageConversation, assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, removedPermitReplacement, parsePermitName, } from './permit.js';
 export { bindCommandSource, CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';

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" | "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;
+export declare const commandMessages: (locale: Locale | undefined, key: "choices" | "defaultValue" | "menuKeyword" | "progress" | "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;