@zhin.js/command 1.1.7 → 1.1.9

package/README.md

@@ -40,6 +40,7 @@ commands/search/[...kw]/index.ts    -> search <...kw>   （params: { kw: { type:
 - `args`：匹配后剩余文本按空白切分的兼容视图。
 - `segments`：匹配后剩余的结构化段，媒体和 mention 不会丢失。
 - `config` / `use()` / `owner` / `generation`：owner-scoped Runtime 上下文。
+- `signal`：真实 IM 入站操作的运行代退休时同步取消。补问、确认及其他需要随代结束的等待应观察此信号；它不会强制取消已经开始的发送，也不禁止持有旧 lease 的普通命令继续排空。没有携带运行代生命周期的输入（如普通 Host 调用）不会凭空获得 IM 生命周期。
 - `input`：派发来源；IM 中为满足 `CommandMessage` 的 Runtime `Message`。
 - `adapter` / `endpoint`：适配器实例 id 与 endpoint 名。
 - `scene`：`{ id, type, name? }` 场景对象。
@@ -57,9 +58,32 @@ commands/search/[...kw]/index.ts    -> search <...kw>   （params: { kw: { type:
 `addCommand('hello', defineCommand(...))`。它与目录发现共用 CommandIndex；拆成文件后
 可获得单命令 HMR。
 
+## 只读权限解释
+
+`CommandIndex.list()` 的命令描述包含稳定的 capability `id` 与声明 `owner`。
+`toCommandPermissionSubject(source)` 与真实命令 permit gate 共用投影；
+`explainCommandPermissions(command, { source?, rolesKnown?, permissionHost })` 只做声明条件的假设检查，
+不执行命令、参数默认函数或平台与自定义 checker。`permissionHost` 表示读取端确认的
+`present` / `missing` / `unverified` 状态，不会通过调用它的方法来试探。
+
+Console 的权限解释入口使用完整会话目标及可选发送者、角色假设。角色未提供时为
+`unknown`；显式提供 canonical `sender.roles: []` 时，按实际命令投影默认 `user`，并说明
+该角色未经平台核验。命令 `adapter` 是原生适配器名称的精确约束，独立于
+permit 的 `adapter(...)` 匹配。保留 Endpoint、父容器和话题只保证模拟输入不丢身份，
+不会使 `group(...)` 等内置规则自动约束这些维度。
+
+返回的 `match` 仅表示已解释条件与假设输入匹配。空 permit、未执行 checker、缺少
+PermissionHost 或缺少身份依据均不能被展示为“已授权”或“可以执行”。
+
 
 ## 集中声明参数、选项与帮助
 
+**列出指令**：在 Bot 会话中发送 `菜单`，列出根插件的指令和直接子插件；`菜单 <插件实例键>` 查看子插件，嵌套实例用 `菜单 foo.bar`。菜单逐层浏览，不一次展开全树。账号设有命令前缀时同样要加前缀，如 `/菜单`。项目根配置的顶层 `menuKeyword` 可修改关键词，`false` 或空字符串关闭；默认关键词为 `菜单`，不是 `help`。详见[指令菜单](../../../docs/authoring/commands.md#查看已加载的指令菜单)。
+
+安装 `@zhin.js/html-renderer` 后，菜单发出带原始文本备用内容的 HTML 段，复用统一发送链的图片渲染和平台策略。渲染失败或平台无法消费图片时保留原文本；无渲染器时直接返回文本。Command Feature 不调用渲染器，也不新增 Core 或样式组件依赖。
+
+菜单每页最多 30 项（指令与子插件合计），`菜单 --page 2` 或 `菜单 rss --page 2` 翻页，图片与文本返回同一页。三列分区、内置背景与图标不需要外部素材；根配置 `menuStyle` 可设置 `title`、`subtitle`、六位 hex `accentColor` 以及 HTTP(S)／PNG/JPEG/WebP data URL 的 `backgroundImage`。同时支持原生 Markdown 与原生按钮时附加翻页控件：首页禁用上一页、末页禁用下一页，单页省略控件；不支持时保留文本导航。回调复用原会话、当前 generation 的 JSX 按钮机制。完整配置和边界见上述指令菜单文档。
+
 目录提供静态命令路径。静态 `commands/remind/index.ts` 可集中声明任意数量的位置参数；
 现有 `commands/foo/[id]/index.ts` 仍绑定同名 `params.id`，后面的参数无需额外动态目录。
 
@@ -90,7 +114,7 @@ export default defineCommand({
 Endpoint 前缀及显式插件命名空间，不执行命令；同一权限声明仍约束帮助读取。
 
 `dispatch()` 返回 `status`：`unmatched`（继续普通消息处理）、`invalid`（`issues` +
-`help`）、`denied`（权限拒绝）、`executed`。后三者 `matched: true`，只有 `executed`
+`help`）、`denied`（权限拒绝）、`limited`（执行预算拒绝）、`executed`。后四者 `matched: true`，只有 `executed`
 包含业务结果。可靠静态路径匹配后才提示错误；纯动态路由的模糊聊天保持未匹配。
 受限命令没有可鉴权主体时拒绝，Host 可通过 `dispatch` 提供真实 `PermissionSubject`；
 `execute(name)` 无主体不能绕过权限。审批与命令准入独立。
@@ -102,6 +126,35 @@ Endpoint 前缀及显式插件命名空间，不执行命令；同一权限声
 `params.id.optional: true`；使用 `[...items]` 时声明 `params.items.rest: true`，
 让执行参数的可选性、数组类型与运行时一致。目录绑定的参数应放在 `params` 第一项。
 
+## 可选执行预算
+
+```ts
+defineCommand({
+  execution: { cooldownMs: 5000, maxConcurrent: 1, progressAfterMs: 1500 },
+  execute: async () => buildReport(),
+});
+```
+
+未声明 `execution` 的命令保持原行为。三个字段均可省略，但配置至少一个：
+`cooldownMs` 为 1–86400000 毫秒，`maxConcurrent` 为 1–1000，
+`progressAfterMs` 为 1–3600000 毫秒，均只接受正整数，未知字段拒绝。
+
+同一能力的普通路由、别名、shortcut 共用预算；不同真实 sender、Endpoint 账号、会话、
+parent 和 thread 独立计算。没有完整可信身份或真实 IM operation 的请求明确拒绝；
+`execute(name)` 不能执行启用了预算的命令。参数错误、帮助、权限拒绝不占额度。
+`limited` 返回 `limit.reason`，冷却时附精确 `retryAfterMs`；正在执行没有预测等待时间。
+
+冷却从接纳时开始，失败或取消仍消耗本次冷却；并发占用直到业务、渲染、出站中间件、
+最终回复及该 operation 中已经启动的发送全部结束。不要依赖 operation 结束后才启动的
+异步发送。热更新只取消尚未开始的进度提示，旧执行仍排空并继续占用同一 Root 的预算；
+新策略的并发数用于新准入，原来已开始的冷却保留到原到期时间。移除策略即停止新请求的预算检查。
+状态只保留在当前进程，进程重启后重置；容量满时拒绝新身份，不驱逐活跃或仍在冷却的记录。
+
+进度默认关闭，只在业务等待阶段发送一次“正在处理中，请稍候。”，走当前平台统一发送链路。
+开始自动最终回复前停止尚未开始的提示，并等待已开始的提示完成；已开始的 I/O 随原 lease 排空。
+执行内显式 `$reply()` 不会停止进度计时。提示失败不重试，也不表示任务取消或远端已经展示。
+`@zhin.js/command/internal/execution` 是 Core 装配使用的内部入口，不是插件创作 API。
+
 ## Runtime
 
 definition 在 import 时不注册全局状态。Feature provider 在 generation prepare 阶段完成

package/lib/command-index.d.ts

@@ -1,11 +1,15 @@
-import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
 import { type CommandValidationIssue } from './arguments.js';
+import { type CommandExecutionLimit } from './execution-policy.js';
+export { CommandExecutionLimitedError } from './execution-policy.js';
 import { type CommandDefinition, type CommandParameterDefinition, type CommandParameterType, type CommandSegment } from './definition.js';
 export interface CommandParameterDescriptor extends CommandParameterDefinition {
     readonly required: boolean;
 }
 export interface CommandDescriptor {
+    readonly id: CapabilityId;
+    readonly owner: PluginId;
     readonly name: string;
     readonly description?: string;
     readonly adapter?: string;
@@ -15,17 +19,27 @@ export interface CommandDescriptor {
     readonly options: NonNullable<CommandDefinition['options']>;
     readonly alias?: readonly string[];
     readonly permit?: readonly string[];
+    readonly execution?: CommandDefinition['execution'];
     /** shortcut 触发键列表（不含预填 params）。 */
     readonly shortcut?: readonly string[];
 }
 export interface CommandDispatchResult {
     readonly matched: boolean;
-    readonly status: 'unmatched' | 'invalid' | 'denied' | 'executed';
+    readonly status: 'unmatched' | 'invalid' | 'denied' | 'limited' | 'executed';
+    readonly limit?: CommandExecutionLimit;
     readonly issues?: readonly CommandValidationIssue[];
     readonly help?: string;
     readonly command?: string;
     readonly owner?: PluginId;
     readonly value?: unknown;
+    readonly menu?: CommandMenuNavigation;
+}
+/** Semantic menu navigation; the IM composition layer supplies platform controls. */
+export interface CommandMenuNavigation {
+    readonly keyword: string;
+    readonly pluginKey?: string;
+    readonly page: number;
+    readonly pages: number;
 }
 export type CommandMatchInput = string | readonly Readonly<CommandSegment>[];
 export interface CommandMenuConfig {
@@ -42,6 +56,11 @@ export declare class CommandIndex {
     dispatch(input: CommandMatchInput, source?: unknown, interactionFactory?: UserInteractionFactory, commandPrefix?: string, operationSnapshot?: RuntimeSnapshot): Promise<CommandDispatchResult>;
 }
 export declare function isCommandIndex(value: unknown): value is CommandIndex;
+/**
+ * Route-shape rule for a convention command: at most one dynamic segment, and it is the final one.
+ * Shared by the runtime index and {@link bindCommandSource}.
+ */
+export declare function assertParameterSegment(segments: readonly string[], parameter: CommandParameterDefinition | undefined, source: string): void;
 export declare class CommandParameterValueError extends TypeError {
     constructor(name: string, type: CommandParameterType, value: string);
 }

package/lib/command-index.js

@@ -1,7 +1,13 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
-import { bindOperationInput, operationClientAdapter } from '@zhin.js/feature-kit';
-import { permissionHostToken, toPermissionSubject, } from '@zhin.js/permission';
+import { htmlRendererToken, } from '@zhin.js/plugin-runtime';
+import { bindOperationInput } from '@zhin.js/feature-kit';
+import { permissionHostToken, } from '@zhin.js/permission';
+import { commandAdapterMatches, toCommandPermissionSubject } from './permission-explanation.js';
 import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp } from './arguments.js';
+import { MENU_PAGE_SIZE, readMenuAppearance, renderCommandMenu } from './command-menu.js';
+import { admitCommandExecution, admitDirectCommandExecution } from './execution-runtime.js';
+import { CommandExecutionLimitedError, normalizeExecutionPolicy } from './execution-policy.js';
+export { CommandExecutionLimitedError } from './execution-policy.js';
 import { createCommandContext, resolveCommandSession, resolveDynamicParams, } from './definition.js';
 const segmentFields = {
     text: 'text',
@@ -39,7 +45,15 @@ export class CommandIndex {
             for (const key of keys)
                 occupancy.set(key, source);
         };
+        const disabledByOwner = new Map();
         for (const slot of slots) {
+            let disabled = disabledByOwner.get(slot.owner);
+            if (!disabled) {
+                disabled = disabledCommands(this.snapshot, slot.owner);
+                disabledByOwner.set(slot.owner, disabled);
+            }
+            if (isDisabledCommand(slot.localName, disabled))
+                continue;
             const namespace = commandNamespace(this.snapshot, slot.owner);
             const primarySegments = [...namespace, ...runtimeSegments(slot.localName)];
             const parameter = slot.definition.$parameter;
@@ -52,9 +66,13 @@ export class CommandIndex {
             const shortcutKeys = slot.definition.shortcut
                 ? Object.freeze(Object.keys(slot.definition.shortcut).map((key) => key.trim()))
                 : undefined;
+            const execution = normalizeExecutionPolicy(slot.definition.execution);
             const record = Object.freeze({
+                id: slot.id,
+                owner: slot.owner,
                 name,
                 description: slot.definition.description,
+                ...(execution ? { execution } : {}),
                 ...(slot.definition.adapter ? { adapter: slot.definition.adapter } : {}),
                 source: slot.source,
                 usage: commandUsage(name, slot.definition),
@@ -138,18 +156,27 @@ export class CommandIndex {
         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));
+        // No inbound source: execution policy applies per command, never as a blanket refusal.
+        const admission = admitDirectCommandExecution(match.command.slot.id, match.command.execution, operationSnapshot);
+        if (admission.limit)
+            throw new CommandExecutionLimitedError(admission.limit);
+        try {
+            return await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
+        }
+        finally {
+            admission.release();
+        }
     }
     async dispatch(input, source = undefined, interactionFactory, commandPrefix = '', operationSnapshot = this.snapshot) {
         if (this.#menu) {
-            const menuValue = this.#dispatchMenu(input, commandPrefix);
-            if (menuValue !== undefined) {
+            const menuResult = this.#dispatchMenu(input, commandPrefix, operationSnapshot);
+            if (menuResult !== undefined) {
                 return Object.freeze({
                     matched: true,
                     status: 'executed',
                     command: this.#menu.keyword,
                     owner: operationSnapshot.root,
-                    value: menuValue,
+                    ...menuResult,
                 });
             }
         }
@@ -186,6 +213,9 @@ export class CommandIndex {
         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 limit = admitCommandExecution(authorSource, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
+        if (limit)
+            return Object.freeze({ matched: true, status: 'limited', command: match.command.name, owner: match.command.slot.owner, limit });
         const value = await definition.execute(createCommandContext(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 });
     }
@@ -213,9 +243,7 @@ export class CommandIndex {
         const host = this.#resolveHost(operationSnapshot);
         if (!host)
             return false;
-        const projected = toPermissionSubject(source);
-        const session = resolveCommandSession(source);
-        const subject = { ...projected, ...session, ...(session.sender ? { sender: { ...projected.sender, ...session.sender } } : {}) };
+        const subject = toCommandPermissionSubject(source);
         if (!subject.sender?.id && !subject.scene?.id && !subject.adapter && !subject.endpoint)
             return false;
         return host.checkAll(permits, subject);
@@ -306,7 +334,7 @@ export class CommandIndex {
     // ==========================================================================
     // 内置菜单命令
     // ==========================================================================
-    #dispatchMenu(input, commandPrefix = '') {
+    #dispatchMenu(input, commandPrefix, snapshot) {
         const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
         if (text === undefined)
             return undefined;
@@ -315,40 +343,59 @@ export class CommandIndex {
             return undefined;
         const keyword = menu.keyword;
         if (text === keyword)
-            return this.#buildMenu(undefined, commandPrefix, keyword);
+            return this.#buildMenu(undefined, commandPrefix, keyword, snapshot);
         if (text.startsWith(keyword + ' ')) {
             const key = text.slice(keyword.length + 1).trim();
+            const args = key.split(/\s+/u);
+            const flag = args.indexOf('--page');
+            if (flag !== -1) {
+                const pageText = args[flag + 1] ?? '';
+                if (flag > 1 || args.length !== flag + 2 || !/^[1-9]\d*$/u.test(pageText)
+                    || !Number.isSafeInteger(Number(pageText))) {
+                    return { value: `页码必须是正整数。用法：${commandPrefix}${keyword} [插件名] --page <页码>` };
+                }
+                return this.#buildMenu(flag === 1 ? args[0] : undefined, commandPrefix, keyword, snapshot, Number(pageText));
+            }
             if (key)
-                return this.#buildMenu(key, commandPrefix, keyword);
-            return this.#buildMenu(undefined, commandPrefix, keyword);
+                return this.#buildMenu(key, commandPrefix, keyword, snapshot);
+            return this.#buildMenu(undefined, commandPrefix, keyword, snapshot);
         }
         return undefined;
     }
-    #buildMenu(pluginKey, commandPrefix, keyword) {
-        const root = this.snapshot.root;
+    #buildMenu(pluginKey, commandPrefix, keyword, snapshot, page = 1) {
+        const root = snapshot.root;
         const targetId = pluginKey
             ? `${root}/${pluginKey.split('.').join('/')}`
             : root;
-        const node = this.snapshot.tree.get(targetId);
+        const node = snapshot.tree.get(targetId);
         if (!node)
-            return `未找到插件: ${pluginKey}`;
+            return { value: `未找到插件: ${pluginKey}` };
         const directCommands = this.#commands.filter((cmd) => cmd.slot.owner === targetId);
         const children = node.children
-            .map((childId) => this.snapshot.tree.get(childId))
+            .map((childId) => snapshot.tree.get(childId))
             .filter((child) => !!child);
+        const pages = Math.max(1, Math.ceil((directCommands.length + children.length) / MENU_PAGE_SIZE));
+        const invocation = `${commandPrefix}${keyword}${pluginKey ? ` ${pluginKey}` : ''}`;
+        if (page > pages)
+            return { value: `页码超出范围：共 ${pages} 页。请使用「${invocation} --page <页码>」。` };
+        const offset = (page - 1) * MENU_PAGE_SIZE;
+        const pageCommands = directCommands.slice(offset, offset + MENU_PAGE_SIZE);
+        const pageChildren = children.slice(Math.max(0, offset - directCommands.length), Math.max(0, offset + MENU_PAGE_SIZE - directCommands.length));
         const displayKey = pluginKey ?? node.instanceKey;
         const lines = [`=== ${displayKey} 指令菜单 ===`];
-        if (directCommands.length > 0) {
+        if (pages > 1)
+            lines.push(`第 ${page}/${pages} 页 · ${directCommands.length} 条指令 · ${children.length} 个子插件`);
+        if (pageCommands.length > 0) {
             lines.push('');
-            for (const cmd of directCommands) {
+            for (const cmd of pageCommands) {
                 const desc = cmd.description ? `  - ${cmd.description}` : '';
                 lines.push(`  ${commandPrefix}${cmd.name}${desc}`);
             }
         }
-        if (children.length > 0) {
+        if (pageChildren.length > 0) {
             lines.push('');
             lines.push('子插件：');
-            for (const child of children) {
+            for (const child of pageChildren) {
                 const childKey = pluginKey ? `${pluginKey}.${child.instanceKey}` : child.instanceKey;
                 const label = child.metadata?.displayName ?? child.instanceKey;
                 lines.push(`  ${childKey}  (${label})`);
@@ -358,11 +405,28 @@ export class CommandIndex {
             lines.push('');
             lines.push('（暂无指令和子插件）');
         }
-        if (children.length > 0) {
+        const hints = [];
+        if (children.length > 0)
+            hints.push(`提示：使用「${commandPrefix}${keyword} <插件名>」查看子插件的指令`);
+        if (page > 1)
+            hints.push(`上一页：${invocation} --page ${page - 1}`);
+        if (page < pages)
+            hints.push(`下一页：${invocation} --page ${page + 1}`);
+        const hint = hints.length ? hints.join('\n') : undefined;
+        if (hint) {
             lines.push('');
-            lines.push(`提示：使用「${commandPrefix}${keyword} <插件名>」查看子插件的指令`);
+            lines.push(hint);
         }
-        return lines.join('\n');
+        const text = lines.join('\n');
+        const menu = Object.freeze({ keyword, ...(pluginKey ? { pluginKey } : {}), page, pages });
+        if (!snapshot.resources.get(root)?.has(htmlRendererToken.id))
+            return { value: text, menu };
+        const config = snapshot.config.get(root);
+        return { menu, value: renderCommandMenu(displayKey, pageCommands.map(cmd => ({ name: `${commandPrefix}${cmd.name}`, description: cmd.description })), pageChildren.map(child => ({
+                name: pluginKey ? `${pluginKey}.${child.instanceKey}` : child.instanceKey,
+                description: child.metadata?.displayName ?? child.instanceKey,
+            })), hint, text, { page, pages, commandTotal: directCommands.length, pluginTotal: children.length,
+                appearance: readMenuAppearance(config?.menuStyle) }) };
     }
 }
 export function isCommandIndex(value) {
@@ -390,6 +454,27 @@ function commandNamespace(snapshot, owner) {
     }
     return Object.freeze([...segments]);
 }
+/**
+ * 插件实例配置 disabledCommands 列出的指令不进入路由表。条目写插件本地的静态路径
+ * （不含 commandNamespace 与参数段，如 `fanyi`、`netease login`）；写上级路径会连同
+ * 其子命令一起禁用。未匹配任何指令的条目被忽略。
+ */
+function disabledCommands(snapshot, owner) {
+    const config = snapshot.config.get(owner);
+    const value = config?.disabledCommands;
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new TypeError(`Invalid disabledCommands for ${owner}: expected an array of command names`);
+    }
+    return Object.freeze(value.map((entry) => splitCommand(entry).join(' ')).filter(Boolean));
+}
+function isDisabledCommand(localName, disabled) {
+    if (disabled.length === 0)
+        return false;
+    const path = runtimeSegments(localName).filter((segment) => !segment.startsWith('$')).join(' ');
+    return disabled.some((entry) => path === entry || path.startsWith(`${entry} `));
+}
 function isCommandNamespaceSegment(value) {
     return /^[\p{L}\p{N}][\p{L}\p{N}_-]*$/u.test(value);
 }
@@ -516,7 +601,11 @@ function exactMessageText(input) {
     const trimmed = only.data.text.trim();
     return trimmed || undefined;
 }
-function assertParameterSegment(segments, parameter, source) {
+/**
+ * Route-shape rule for a convention command: at most one dynamic segment, and it is the final one.
+ * Shared by the runtime index and {@link bindCommandSource}.
+ */
+export function assertParameterSegment(segments, parameter, source) {
     const dynamicSegments = segments.filter((segment) => segment.startsWith('$'));
     if (!parameter && dynamicSegments.length === 0)
         return;
@@ -685,9 +774,6 @@ function textArgs(segments) {
 function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, ...descriptor }) {
     return descriptor;
 }
-function commandAdapterMatches(record, source) {
-    return !record.adapter || operationClientAdapter(source) === record.adapter;
-}
 export class CommandParameterValueError extends TypeError {
     constructor(name, type, value) {
         super(`Invalid value for Command parameter ${name}:${type}: ${value}`);

package/lib/command-menu.d.ts

@@ -0,0 +1,31 @@
+interface MenuEntry {
+    readonly name: string;
+    readonly description?: string;
+}
+interface MenuAppearance {
+    readonly title?: string;
+    readonly subtitle?: string;
+    readonly accentColor?: string;
+    readonly backgroundImage?: string;
+}
+export interface CommandMenuSegment {
+    readonly type: 'html';
+    readonly data: {
+        readonly html: string;
+        readonly text: string;
+        readonly width: number;
+        readonly fileName: string;
+    };
+}
+export declare const MENU_PAGE_SIZE = 30;
+/** Configuration is text/data, never an interpolated CSS or HTML fragment. */
+export declare function readMenuAppearance(value: unknown): MenuAppearance;
+/** Presentation only: the unified outbound pipeline owns image rendering and fallback. */
+export declare function renderCommandMenu(title: string, commands: readonly MenuEntry[], children: readonly MenuEntry[], hint: string | undefined, text: string, options?: {
+    readonly page?: number;
+    readonly pages?: number;
+    readonly commandTotal?: number;
+    readonly pluginTotal?: number;
+    readonly appearance?: MenuAppearance;
+}): CommandMenuSegment;
+export {};

package/lib/command-menu.js

@@ -0,0 +1,81 @@
+export const MENU_PAGE_SIZE = 30;
+const escape = (value) => value.replace(/[&<>"']/gu, char => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+})[char] ?? char);
+/** Configuration is text/data, never an interpolated CSS or HTML fragment. */
+export function readMenuAppearance(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const input = value;
+    const result = {};
+    if (typeof input.title === 'string')
+        result.title = input.title.slice(0, 100);
+    if (typeof input.subtitle === 'string')
+        result.subtitle = input.subtitle.slice(0, 160);
+    if (typeof input.accentColor === 'string' && /^#[\da-f]{6}$/iu.test(input.accentColor))
+        result.accentColor = input.accentColor;
+    if (typeof input.backgroundImage === 'string') {
+        try {
+            const url = new URL(input.backgroundImage);
+            if (url.protocol === 'https:' || url.protocol === 'http:'
+                || /^data:image\/(?:png|jpeg|webp);base64,[A-Za-z0-9+/=]+$/u.test(url.href))
+                result.backgroundImage = url.href;
+        }
+        catch { /* Invalid optional artwork falls back to the bundled illustration. */ }
+    }
+    return result;
+}
+// Self-contained artwork: no network requests or extra asset/package dependency.
+const landscape = `<svg xmlns="http://www.w3.org/2000/svg" width="1080" height="1400" viewBox="0 0 1080 1400">
+<defs><linearGradient id="sky" x2=".8" y2="1"><stop stop-color="#162635"/><stop offset=".48" stop-color="#344b57"/><stop offset="1" stop-color="#70837c"/></linearGradient><radialGradient id="glow"><stop stop-color="#eddbc0" stop-opacity=".3"/><stop offset="1" stop-color="#d6d7c3" stop-opacity="0"/></radialGradient><linearGradient id="hill" x2="0" y2="1"><stop stop-color="#b2c2b5" stop-opacity=".34"/><stop offset="1" stop-color="#213e45" stop-opacity=".1"/></linearGradient></defs>
+<path fill="url(#sky)" d="M0 0h1080v1400H0z"/><circle cx="820" cy="184" r="290" fill="url(#glow)"/><circle cx="823" cy="167" r="92" fill="#e3dfc9"/><circle cx="802" cy="146" r="10" fill="#cbcdbb" opacity=".3"/><circle cx="854" cy="194" r="19" fill="#cbcdbb" opacity=".3"/>
+<g fill="#e7d5ac" opacity=".7"><circle cx="113" cy="72" r="1.5"/><circle cx="360" cy="104" r="1"/><circle cx="624" cy="55" r="2"/><circle cx="713" cy="265" r="1.2"/><circle cx="982" cy="332" r="2"/><circle cx="463" cy="43" r="1.4"/><circle cx="540" cy="202" r="1.4"/><circle cx="96" cy="410" r="2"/></g>
+<g fill="none" stroke="#abac8a" stroke-width="2" opacity=".6"><path d="M1080 0Q959 77 902 267M1012 45Q916 92 866 106M984 78Q1016 164 1004 229M946 146Q866 156 838 204M917 217Q947 257 945 311"/></g>
+<g fill="#d1bc93" opacity=".7"><ellipse cx="916" cy="84" rx="8" ry="21" transform="rotate(60 916 84)"/><ellipse cx="975" cy="115" rx="8" ry="20" transform="rotate(-25 975 115)"/><ellipse cx="876" cy="172" rx="8" ry="20" transform="rotate(58 876 172)"/><ellipse cx="1006" cy="208" rx="8" ry="20"/><ellipse cx="932" cy="270" rx="8" ry="20" transform="rotate(-25 932 270)"/></g>
+<path d="M0 615 171 375 293 517 441 315 619 564 796 417 1080 651V1400H0Z" fill="url(#hill)"/><path d="m0 867 263-305 194 263 173-167 216 142 234-183v783H0Z" fill="#243e48" opacity=".46"/><path d="M0 1155q260-270 540-160t540-125v530H0Z" fill="#17343d" opacity=".65"/>
+<g fill="none" stroke="#b1c1b2" stroke-opacity=".14"><path d="M0 455q210-85 424-12t656-4M0 474q210-85 424-12t656-4M0 1095q310-83 600-9t480-30M0 1124q310-83 600-9t480-30"/></g></svg>`;
+const symbols = [
+    '<path d="m16 3 4 9 9 4-9 4-4 9-4-9-9-4 9-4Z"/><path d="m16 10 2 6-2 6-2-6Z"/>',
+    '<circle cx="16" cy="16" r="11"/><path d="m10 19 6-12 6 12-6-3Z"/>',
+    '<path d="m16 3 12 7v12l-12 7-12-7V10Z"/><path d="m4 10 12 7 12-7M16 17v12"/>',
+    '<circle cx="16" cy="16" r="5"/><path d="m16 2 3 7 8-3-3 8 7 2-7 3 3 8-8-3-3 7-3-7-8 3 3-8-7-3 7-2-3-8 8 3Z"/>',
+];
+function icon(name, plugin = false) {
+    const hash = [...name].reduce((value, char) => (value + (char.codePointAt(0) ?? 0)) % symbols.length, 0);
+    return `<svg viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="1.15">${plugin ? symbols[2] : symbols[hash]}</svg>`;
+}
+/** Presentation only: the unified outbound pipeline owns image rendering and fallback. */
+export function renderCommandMenu(title, commands, children, hint, text, options = {}) {
+    const appearance = options.appearance ?? {};
+    const background = appearance.backgroundImage ?? `data:image/svg+xml,${encodeURIComponent(landscape)}`;
+    // CSS string escaping additionally prevents an artwork URL from closing <style>.
+    const cssUrl = JSON.stringify(background).replace(/</gu, '\\3c ').replace(/>/gu, '\\3e ');
+    const entries = (items, plugin) => items.map(item => `<div class="entry"><div class="icon">${icon(item.name, plugin)}</div><div class="copy"><div class="name">${escape(item.name)}</div>${item.description
+        ? `<div class="description">${escape(item.description)}</div>` : ''}</div></div>`).join('');
+    const section = (label, items, total, plugin = false) => items.length === 0 ? ''
+        : `<section><div class="section-head"><h2>${label}</h2><span>${items.length} / ${total}</span></div><div class="grid">${entries(items, plugin)}</div></section>`;
+    const page = options.page ?? 1;
+    const pages = options.pages ?? 1;
+    return {
+        type: 'html',
+        data: {
+            width: 1080, fileName: 'command-menu.png', text,
+            html: `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><style>
+*{box-sizing:border-box}body{margin:0;background:#253b46;color:#f4f0e6;font-family:"PingFang SC","Microsoft YaHei",sans-serif;font-size:18px;line-height:1.5;--accent:${appearance.accentColor ?? '#e7c993'}}
+main{padding:42px 28px 24px;background-image:linear-gradient(180deg,#0c202a0a,#0c202a55),url(${cssUrl});background-size:cover;background-position:center top}
+header{min-height:210px;padding:10px 22px 30px;position:relative}.eyebrow{font-size:12px;letter-spacing:5px;color:#f4e4c4;margin:0 0 17px}
+h1{margin:0 0 10px;font-family:"Songti SC","Noto Serif CJK SC",serif;font-size:55px;font-weight:800;letter-spacing:3px;text-shadow:0 2px 16px #0c202a66;max-width:760px;line-height:1.2}
+.subtitle{font-size:17px;color:#e0e6e0;letter-spacing:2px;max-width:700px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.summary{margin:18px 0 0;display:flex;align-items:center;gap:16px;font-size:13px;letter-spacing:1px;color:#e0dfcf}.summary i{width:22px;height:1px;background:var(--accent)}
+section{margin:0 0 20px;padding:5px;background:#dbe9e516;border:1px solid #f0e2c722;border-radius:19px;box-shadow:0 8px 25px #08192312}.section-head{padding:14px 18px;display:flex;justify-content:space-between;align-items:center;background:#142a34db;border-radius:13px 13px 0 0}
+h2{margin:0;font-size:20px;font-weight:700;letter-spacing:1px;color:var(--accent)}.section-head span{font-size:12px;letter-spacing:2px;color:#b7c7c5}
+.grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));background:#20363fdb;border-radius:0 0 13px 13px;overflow:hidden}
+.entry{display:flex;align-items:center;gap:12px;padding:19px 17px;min-width:0;min-height:106px;border-top:1px solid #e7e6d614;border-right:1px solid #e7e6d614;background:linear-gradient(120deg,#ffffff08,#ffffff00)}.entry:nth-child(3n){border-right:0}
+.icon{width:35px;height:35px;flex:0 0 35px;color:var(--accent);filter:drop-shadow(0 1px 6px #d9ba7c22)}.icon svg{display:block;width:100%;height:100%}.copy{min-width:0}.name{font-size:18px;font-weight:700;color:var(--accent)}.description{margin:4px 0 0;color:#e1e8e5;font-size:15px;line-height:1.45}
+.name,.description,h1{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;overflow-wrap:anywhere;white-space:pre-wrap}
+footer{margin:6px 5px 0;padding:15px 18px;display:flex;align-items:center;justify-content:space-between;gap:22px;background:#142a34da;border:1px solid #f0e2c71c;border-radius:13px}.hint{font-size:14px;color:#cfdbd7;white-space:pre-wrap;overflow-wrap:anywhere}.page{font-size:20px;color:var(--accent);white-space:nowrap;font-family:Georgia,serif}.signature{margin:16px 0 0;text-align:center;font-size:10px;letter-spacing:4px;color:#c4d0c899}.empty{margin:0 0 20px;padding:28px;background:#142a34da;border-radius:16px;color:#dbe4de}
+</style></head><body><main><header><div class="eyebrow">ZHIN / COMMAND ATLAS</div><h1>${escape(appearance.title || `${title} · 指令指南`)}</h1><div class="subtitle">${escape(appearance.subtitle ?? '每一个灵感，都有回应。')}</div><div class="summary"><i></i>${options.commandTotal ?? commands.length} 条指令<span>·</span>${options.pluginTotal ?? children.length} 个子插件<span>·</span>${escape(title)}</div></header>
+${section('指令索引', commands, options.commandTotal ?? commands.length)}${section('插件导航', children, options.pluginTotal ?? children.length, true)}${commands.length || children.length ? '' : '<p class="empty">暂无指令和子插件</p>'}
+<footer><div class="hint">${escape(hint ?? '查看参数与用法：指令名 --help')}</div><div class="page">${String(page).padStart(2, '0')} / ${String(pages).padStart(2, '0')}</div></footer><div class="signature">ZHIN · MAKE EVERY MESSAGE MATTER</div></main></body></html>`,
+        },
+    };
+}

package/lib/definition.d.ts

@@ -5,6 +5,8 @@
 import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import { type AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
 import type { UserInteraction } from '@zhin.js/interaction';
+import { type CommandExecutionPolicy } from './execution-policy.js';
+export type { CommandExecutionPolicy, CommandExecutionLimit } from './execution-policy.js';
 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>>> | Readonly<Record<string, unknown>> | null;
@@ -246,6 +248,8 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
      * 例：`adapter(icqq)`、`role(master)`、`group(123,456)`。
      */
     readonly permit?: readonly string[];
+    /** Optional full-operation cooldown, concurrency and one-shot progress feedback. */
+    readonly execution?: Readonly<CommandExecutionPolicy>;
     /**
      * 全局整句快捷方式：触发串（trim 后全文相等）→ 预填 params。
      * 与普通路由一样是全局用户输入，冲突会在 generation 构建时拒绝。
@@ -278,7 +282,16 @@ type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extend
     readonly params: keyof P extends never ? Readonly<Record<string, CommandParameterValue>> : InferCommandParams<P>;
     readonly options: InferCommandOptions<O>;
 };
+/**
+ * `defineCommand.withConfig<Config>()` 返回的定义函数：config 类型已固定，params / options / 返回值
+ * 仍从定义推断。
+ * @public
+ */
+export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <TResult = unknown, const P extends CommandParams = {}, const O extends CommandOptions = {}>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>) => Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
 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>>;
+export declare namespace defineCommand {
+    var withConfig: <TConfig = unknown, TInput extends CommandMessage = CommandMessage>() => CommandDefiner<TConfig, TInput>;
+}
 /** @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. */
@@ -297,4 +310,8 @@ export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId:
  * @internal Command dispatcher projection helper.
  */
 export declare function resolveCommandSession(input: unknown): CommandSession;
-export {};
+/**
+ * Pure canonical sender projection shared with read-only command condition simulation.
+ * @internal Command dispatcher projection helper.
+ */
+export declare function resolveCommandSender(input: Pick<CommandMessage, 'sender'>, metadata: Readonly<Record<string, unknown>> | undefined): CommandSender | undefined;