@zhin.js/command 1.1.7 → 1.1.9

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "exports": {
+    "./internal/execution": {
+      "types": "./lib/execution-runtime.d.ts",
+      "import": "./lib/execution-runtime.js"
+    },
     ".": {
       "types": "./lib/index.d.ts",
       "import": "./lib/index.js"
@@ -17,10 +21,10 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.1.5",
-    "@zhin.js/plugin-runtime": "1.1.14",
     "@zhin.js/interaction": "1.1.2",
-    "@zhin.js/permission": "1.1.6"
+    "@zhin.js/feature-kit": "1.1.7",
+    "@zhin.js/permission": "1.1.7",
+    "@zhin.js/plugin-runtime": "1.1.15"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -3,19 +3,25 @@ import {
   TypeMatcherRegistry,
   type MessageSegment,
 } from 'segment-matcher';
-import type {
-  CapabilitySlot,
-  PluginId,
-  RuntimeSnapshot,
+import {
+  htmlRendererToken,
+  type CapabilityId,
+  type CapabilitySlot,
+  type PluginId,
+  type RuntimeSnapshot,
 } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
-import { bindOperationInput, operationClientAdapter } from '@zhin.js/feature-kit';
+import { bindOperationInput } from '@zhin.js/feature-kit';
 import {
   permissionHostToken,
-  toPermissionSubject,
   type PermissionHost,
 } from '@zhin.js/permission';
+import { commandAdapterMatches, toCommandPermissionSubject } from './permission-explanation.js';
 import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp, type CommandValidationIssue } from './arguments.js';
+import { MENU_PAGE_SIZE, readMenuAppearance, renderCommandMenu, type CommandMenuSegment } from './command-menu.js';
+import { admitCommandExecution, admitDirectCommandExecution } from './execution-runtime.js';
+import { CommandExecutionLimitedError, normalizeExecutionPolicy, type CommandExecutionLimit } from './execution-policy.js';
+export { CommandExecutionLimitedError } from './execution-policy.js';
 import {
   createCommandContext,
   resolveCommandSession,
@@ -32,6 +38,8 @@ export interface CommandParameterDescriptor extends CommandParameterDefinition {
 }
 
 export interface CommandDescriptor {
+  readonly id: CapabilityId;
+  readonly owner: PluginId;
   readonly name: string;
   readonly description?: string;
   readonly adapter?: string;
@@ -41,18 +49,34 @@ 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;
+}
+
+interface CommandMenuResult {
+  readonly value: string | CommandMenuSegment;
+  readonly menu?: CommandMenuNavigation;
 }
 
 interface CommandRecord extends CommandDescriptor {
@@ -129,7 +153,14 @@ export class CommandIndex {
       for (const key of keys) occupancy.set(key, source);
     };
 
+    const disabledByOwner = new Map<PluginId, readonly string[]>();
     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;
@@ -143,9 +174,13 @@ export class CommandIndex {
         ? Object.freeze(Object.keys(slot.definition.shortcut).map((key) => key.trim()))
         : undefined;
 
+      const execution = normalizeExecutionPolicy(slot.definition.execution);
       const record: CommandRecord = 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),
@@ -240,8 +275,15 @@ export class CommandIndex {
     const supplied = [...match.remaining, ...(args.length > 0 ? [{ type: 'text', data: { text: args.join(' ') } }] : [])];
     const parsed = parseCommandArguments(definition, supplied, resolveDynamicParams(match.params, undefined), {});
     if (parsed.issues.length > 0) throw new CommandArgumentValidationError(parsed.issues, commandHelp(match.command.name, definition));
-    return definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner,
-      textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
+    // 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(
@@ -252,14 +294,14 @@ export class CommandIndex {
     operationSnapshot: RuntimeSnapshot = this.snapshot,
   ): Promise<CommandDispatchResult> {
     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,
         });
       }
     }
@@ -289,6 +331,8 @@ export class CommandIndex {
     const parsed = parseCommandArguments(definition, match.remaining, resolveDynamicParams(match.params, authorSource), resolveCommandSession(authorSource));
     if (parsed.issues.length > 0) return Object.freeze({ matched: true, status: 'invalid', command: match.command.name,
       owner: match.command.slot.owner, issues: parsed.issues, help });
+    const 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 });
@@ -315,9 +359,7 @@ export class CommandIndex {
     if (!source || typeof source !== 'object') return false;
     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);
   }
@@ -404,50 +446,68 @@ export class CommandIndex {
   // 内置菜单命令
   // ==========================================================================
 
-  #dispatchMenu(input: CommandMatchInput, commandPrefix = ''): string | undefined {
+  #dispatchMenu(input: CommandMatchInput, commandPrefix: string, snapshot: RuntimeSnapshot): CommandMenuResult | undefined {
     const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
     if (text === undefined) return undefined;
     const menu = this.#menu;
     if (!menu) return undefined;
     const keyword = menu.keyword;
-    if (text === keyword) return this.#buildMenu(undefined, commandPrefix, keyword);
+    if (text === keyword) return this.#buildMenu(undefined, commandPrefix, keyword, snapshot);
     if (text.startsWith(keyword + ' ')) {
       const key = text.slice(keyword.length + 1).trim();
-      if (key) return this.#buildMenu(key, commandPrefix, keyword);
-      return this.#buildMenu(undefined, commandPrefix, keyword);
+      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, snapshot);
+      return this.#buildMenu(undefined, commandPrefix, keyword, snapshot);
     }
     return undefined;
   }
 
-  #buildMenu(pluginKey: string | undefined, commandPrefix: string, keyword: string): string {
-    const root = this.snapshot.root;
+  #buildMenu(pluginKey: string | undefined, commandPrefix: string, keyword: string, snapshot: RuntimeSnapshot, page = 1): CommandMenuResult {
+    const root = snapshot.root;
     const targetId = pluginKey
       ? `${root}/${pluginKey.split('.').join('/')}` as PluginId
       : root;
 
-    const node = this.snapshot.tree.get(targetId);
-    if (!node) return `未找到插件: ${pluginKey}`;
+    const node = snapshot.tree.get(targetId);
+    if (!node) 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 is NonNullable<typeof 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: string[] = [`=== ${displayKey} 指令菜单 ===`];
+    if (pages > 1) lines.push(`第 ${page}/${pages} 页 · ${directCommands.length} 条指令 · ${children.length} 个子插件`);
 
-    if (directCommands.length > 0) {
+    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})`);
@@ -459,12 +519,27 @@ export class CommandIndex {
       lines.push('（暂无指令和子插件）');
     }
 
-    if (children.length > 0) {
+    const hints: string[] = [];
+    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) as Record<string, unknown> | undefined;
+    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) }) };
   }
 }
 
@@ -497,6 +572,27 @@ function commandNamespace(snapshot: RuntimeSnapshot, owner: PluginId): readonly
   return Object.freeze([...segments]);
 }
 
+/**
+ * 插件实例配置 disabledCommands 列出的指令不进入路由表。条目写插件本地的静态路径
+ * （不含 commandNamespace 与参数段，如 `fanyi`、`netease login`）；写上级路径会连同
+ * 其子命令一起禁用。未匹配任何指令的条目被忽略。
+ */
+function disabledCommands(snapshot: RuntimeSnapshot, owner: PluginId): readonly string[] {
+  const config = snapshot.config.get(owner) as Readonly<Record<string, unknown>> | undefined;
+  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: string) => splitCommand(entry).join(' ')).filter(Boolean));
+}
+
+function isDisabledCommand(localName: string, disabled: readonly string[]): boolean {
+  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: string): boolean {
   return /^[\p{L}\p{N}][\p{L}\p{N}_-]*$/u.test(value);
 }
@@ -636,7 +732,11 @@ function exactMessageText(input: CommandMatchInput): string | undefined {
   return trimmed || undefined;
 }
 
-function assertParameterSegment(
+/**
+ * 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: readonly string[],
   parameter: CommandParameterDefinition | undefined,
   source: string,
@@ -839,10 +939,6 @@ function toDescriptor({
   return descriptor;
 }
 
-function commandAdapterMatches(record: CommandRecord, source: unknown): boolean {
-  return !record.adapter || operationClientAdapter(source) === record.adapter;
-}
-
 export class CommandParameterValueError extends TypeError {
   constructor(name: string, type: CommandParameterType, value: string) {
     super(`Invalid value for Command parameter ${name}:${type}: ${value}`);

package/src/command-menu.ts

@@ -0,0 +1,112 @@
+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 const MENU_PAGE_SIZE = 30;
+
+const escape = (value: string) => 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: unknown): MenuAppearance {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const input = value as Record<string, unknown>;
+  const result: { title?: string; subtitle?: string; accentColor?: string; backgroundImage?: string } = {};
+  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: string, plugin = false): string {
+  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: 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 {
+  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: readonly MenuEntry[], plugin: boolean) => 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: string, items: readonly MenuEntry[], total: number, 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/src/definition.ts

@@ -6,6 +6,7 @@ import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import {
   createCapabilityContext,
   readOperationClient,
+  readOperationInputSignal,
   type AdapterClient,
   type RegisteredAdapterName,
   type CapabilityContext,
@@ -13,6 +14,8 @@ import {
 import { assertPermitSyntax } from '@zhin.js/permission';
 import { validateArgumentSchemas } from './arguments.js';
 import type { UserInteraction } from '@zhin.js/interaction';
+import { normalizeExecutionPolicy, type CommandExecutionPolicy } from './execution-policy.js';
+export type { CommandExecutionPolicy, CommandExecutionLimit } from './execution-policy.js';
 
 const commandBrand = 'zhin.command/1' as const;
 
@@ -309,6 +312,8 @@ export interface CommandDefinition<
    * 例：`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 构建时拒绝。
@@ -355,6 +360,19 @@ type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extend
     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 function defineCommand<
   TConfig = unknown,
   TResult = unknown,
@@ -383,11 +401,34 @@ export function defineCommand<
   validateCommandAlias(definition.alias);
   validateCommandPermit(definition.permit);
   validateCommandShortcutShape(definition.shortcut);
-  return Object.freeze({ $feature: commandBrand, ...definition }) as Readonly<
+  const execution = normalizeExecutionPolicy(definition.execution);
+  return Object.freeze({ $feature: commandBrand, ...definition, ...(execution ? { execution } : {}) }) as Readonly<
     CommandDefinition<TConfig, TResult, TInput, string | undefined>
   >;
 }
 
+/**
+ * 先固定插件 config 类型，再定义命令；params / options / 返回值仍从定义推断。
+ *
+ * ```ts
+ * export default defineCommand.withConfig<Config>()({
+ *   params: { count: { type: 'integer' } },
+ *   execute({ params, config }) { params.count; config.prefix },
+ * })
+ * ```
+ *
+ * `defineCommand<Config>({...})` 仍然可用，但 TypeScript 不支持部分推断，显式写了
+ * 类型参数后 params 会退化成 `Record<string, CommandParameterValue>`。
+ * 这里是独立的属性而不是 `defineCommand()` 重载：`defineCommand` 常被当作值传给
+ * `createEndpointCommands(spec, defineCommand)` 这类工厂，重载会让它推断错签名。
+ */
+defineCommand.withConfig = function withConfig<
+  TConfig = unknown,
+  TInput extends CommandMessage = CommandMessage,
+>(): CommandDefiner<TConfig, TInput> {
+  return (definition) => defineCommand(definition);
+};
+
 function validateAdapterName(adapter: string | undefined): void {
   if (adapter !== undefined && (typeof adapter !== 'string' || adapter.trim() === '')) {
     throw new TypeError('Command adapter must be a non-empty string');
@@ -464,6 +505,7 @@ export function parseCommandDefinition(value: unknown): CommandDefinition {
     throw new TypeError('Command module must default-export defineCommand(...)');
   }
   validateAdapterName(definition.adapter);
+  normalizeExecutionPolicy(definition.execution);
   return definition as CommandDefinition;
 }
 
@@ -496,7 +538,7 @@ export function createCommandContext(
   adapter?: string,
   options: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
 ): CommandContext {
-  const context = createCapabilityContext(snapshot, ownerId);
+  const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
   const session = resolveCommandSession(input);
   const parameterValues: Record<string, CommandParameterValue> = { __proto__: null, ...params };
   const optionValues: Record<string, CommandParameterValue> = { __proto__: null, ...options };
@@ -534,7 +576,7 @@ export function resolveCommandSession(input: unknown): CommandSession {
     || (typeof metadata?.endpoint === 'string' && metadata.endpoint ? metadata.endpoint : undefined);
 
   const scene = resolveScene(input, metadata);
-  const sender = resolveSender(input, metadata);
+  const sender = resolveCommandSender(input, metadata);
 
   return Object.freeze({
     ...(adapter ? { adapter } : {}),
@@ -583,8 +625,12 @@ function resolveScene(
   });
 }
 
-function resolveSender(
-  input: CommandMessage,
+/**
+ * Pure canonical sender projection shared with read-only command condition simulation.
+ * @internal Command dispatcher projection helper.
+ */
+export function resolveCommandSender(
+  input: Pick<CommandMessage, 'sender'>,
   metadata: Readonly<Record<string, unknown>> | undefined,
 ): CommandSender | undefined {
   const structured = (input as { readonly from?: unknown }).from;
@@ -606,7 +652,7 @@ function resolveSender(
 }
 
 function resolveRoles(
-  input: CommandMessage,
+  input: Pick<CommandMessage, 'sender'>,
   metadata: Readonly<Record<string, unknown>> | undefined,
 ): readonly string[] {
   if (input.sender?.roles?.length) {

package/src/execution-policy.ts

@@ -0,0 +1,39 @@
+/** Optional per-capability budget, isolated by sender and the complete conversation identity. */
+export interface CommandExecutionPolicy {
+  readonly cooldownMs?: number;
+  readonly maxConcurrent?: number;
+  /** One best-effort progress message while business logic is waiting; disabled by default. */
+  readonly progressAfterMs?: number;
+}
+
+export interface CommandExecutionLimit {
+  readonly reason: 'cooldown' | 'busy' | 'capacity' | 'operation_unavailable' | 'identity_unavailable' | 'service_unavailable';
+  /** Exact remaining cooldown; a busy operation has no predictable completion time. */
+  readonly retryAfterMs?: number;
+}
+
+export class CommandExecutionLimitedError extends Error {
+  readonly limit: CommandExecutionLimit;
+  constructor(limit: CommandExecutionLimit) {
+    super(`Command execution limited: ${limit.reason}`);
+    this.name = 'CommandExecutionLimitedError';
+    this.limit = limit;
+  }
+}
+
+/** @internal Validate at declaration and projection, without coercion or silent clamping. */
+export function normalizeExecutionPolicy(value: unknown): Readonly<CommandExecutionPolicy> | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Command execution must be an object');
+  const limits = { cooldownMs: 86_400_000, maxConcurrent: 1000, progressAfterMs: 3_600_000 };
+  const result: Record<string, number> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (!Object.hasOwn(limits, key) || !Number.isSafeInteger(item) || (item as number) <= 0
+      || (item as number) > limits[key as keyof typeof limits]) {
+      throw new TypeError(`Command execution.${key} must be a positive bounded integer`);
+    }
+    result[key] = item as number;
+  }
+  if (Object.keys(result).length === 0) throw new TypeError('Command execution requires at least one policy');
+  return Object.freeze(result);
+}