@zhin.js/command 1.1.7 → 1.1.8

package/lib/execution-runtime.js

@@ -0,0 +1,134 @@
+/** Internal composition contract. Not part of the command authoring facade. */
+import { createToken } from '@zhin.js/plugin-runtime';
+/** @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. */
+export class CommandExecutionBudget {
+    #entries = new Map();
+    #views = new WeakMap();
+    #clock;
+    #capacity;
+    admission;
+    constructor(options = {}) {
+        this.#clock = options.clock ?? (() => performance.now());
+        this.#capacity = options.capacity ?? 10_000;
+        if (!Number.isSafeInteger(this.#capacity) || this.#capacity < 1)
+            throw new TypeError('Invalid command budget capacity');
+        this.admission = Object.freeze({ admit: (source, capability, owner, policy, snapshot) => this.#admit(source, capability, owner, policy, snapshot) });
+    }
+    openOperation(input) {
+        const c = input.conversation;
+        const values = [c.endpoint.adapter, c.endpoint.id, c.kind, c.id, c.parent?.kind ?? '', c.parent?.id ?? '', c.threadId ?? '', input.senderId ?? ''];
+        const valid = values.slice(0, 4).every(nonempty) && ['private', 'group', 'channel'].includes(c.kind) && nonempty(input.senderId)
+            && (c.parent === undefined || (nonempty(c.parent.kind) && nonempty(c.parent.id)))
+            && (c.threadId === undefined || nonempty(c.threadId)) && values.every(value => value.length <= 1024);
+        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(),
+        };
+        const stop = () => {
+            operation.progressStopped = true;
+            for (const timer of operation.timers)
+                clearTimeout(timer);
+            operation.timers.clear();
+        };
+        input.retirementSignal.addEventListener('abort', stop, { once: true });
+        return Object.freeze({
+            bind: (view, owner) => { if (operation.active)
+                this.#views.set(view, { operation, owner }); },
+            trackSend: (send) => {
+                if (!operation.active)
+                    return;
+                const settled = send.then(() => { operation.sends.delete(settled); }, () => { operation.sends.delete(settled); });
+                operation.sends.add(settled);
+            },
+            stopProgress: async () => { stop(); await Promise.all(operation.feedback); },
+            finish: async () => {
+                stop();
+                await Promise.all(operation.feedback);
+                // New sends may start while an earlier send is draining. Do not release from an initial snapshot alone.
+                if (operation.admitted)
+                    while (operation.sends.size > 0)
+                        await Promise.all(operation.sends);
+                if (!operation.active)
+                    return;
+                operation.active = false;
+                operation.signal.removeEventListener('abort', stop);
+                for (const release of operation.releases)
+                    release();
+                operation.releases.length = 0;
+                operation.feedback.length = 0;
+                operation.accepted.clear();
+                operation.sends.clear();
+                operation.reply = undefined;
+                operation.snapshot = undefined;
+                operation.key = undefined;
+            },
+        });
+    }
+    #admit(source, capability, owner, policy, snapshot) {
+        const binding = source !== null && typeof source === 'object' ? this.#views.get(source) : undefined;
+        const operation = binding?.operation;
+        if (!operation?.active || operation.snapshot !== snapshot || binding?.owner !== owner || operation.signal.aborted)
+            return limited('operation_unavailable');
+        if (!operation.key)
+            return limited('identity_unavailable');
+        const key = JSON.stringify([capability, ...operation.key]);
+        // Re-entering the same capability is a second attempt, rather than a second free execution.
+        const now = this.#clock();
+        let entry = this.#entries.get(key);
+        if (entry && policy.maxConcurrent !== undefined && entry.active >= policy.maxConcurrent)
+            return limited('busy');
+        if (entry && entry.cooldownUntil > now)
+            return Object.freeze({ reason: 'cooldown', retryAfterMs: Math.ceil(entry.cooldownUntil - now) });
+        if (!entry) {
+            if (this.#entries.size >= this.#capacity) {
+                for (const [oldKey, old] of this.#entries)
+                    if (old.active === 0 && old.cooldownUntil <= now)
+                        this.#entries.delete(oldKey);
+                if (this.#entries.size >= this.#capacity)
+                    return limited('capacity');
+            }
+            entry = { active: 0, cooldownUntil: 0 };
+            this.#entries.set(key, entry);
+        }
+        entry.active++;
+        operation.admitted = true;
+        entry.cooldownUntil = now + (policy.cooldownMs ?? 0);
+        const acceptedEntry = entry;
+        operation.releases.push(() => {
+            acceptedEntry.active--;
+            if (acceptedEntry.active === 0 && acceptedEntry.cooldownUntil <= this.#clock())
+                this.#entries.delete(key);
+        });
+        if (policy.progressAfterMs !== undefined && !operation.progressStopped && !operation.accepted.has(capability)) {
+            const timer = setTimeout(() => {
+                operation.timers.delete(timer);
+                if (!operation.active || operation.progressStopped || operation.signal.aborted || !operation.reply)
+                    return;
+                // Observe failure once. Never retry uncertain delivery and never expose the exception.
+                let send;
+                try {
+                    send = Promise.resolve(operation.reply(owner, '正在处理中，请稍候。')).then(() => { }, () => { });
+                }
+                catch {
+                    send = Promise.resolve();
+                }
+                operation.feedback.push(send);
+            }, policy.progressAfterMs);
+            operation.timers.add(timer);
+        }
+        operation.accepted.add(capability);
+        return undefined;
+    }
+}
+function nonempty(value) { return typeof value === 'string' && value.length > 0; }
+function limited(reason) { return Object.freeze({ reason }); }
+/** @internal Projection reads the Root resource; ordinary authoring values cannot bind an operation. */
+export function admitCommandExecution(source, capability, owner, policy, snapshot) {
+    if (!policy)
+        return undefined;
+    const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id);
+    return reader ? reader.admit(source, capability, owner, policy, snapshot) : limited('service_unavailable');
+}

package/lib/index.d.ts

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

package/lib/index.js

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

package/lib/permission-explanation.d.ts

@@ -0,0 +1,22 @@
+import { type PermissionSubject, type PermissionConditionExplanation } from '@zhin.js/permission';
+import type { CommandDescriptor } from './command-index.js';
+/** The exact subject projection used by the real command permit gate. No factories or checkers run. */
+export declare function toCommandPermissionSubject(source: unknown): PermissionSubject;
+/** Exact authoring adapter restriction, distinct from builtin adapter(...) matching. */
+export declare function commandAdapterMatches(command: Readonly<{
+    adapter?: string;
+}>, source: unknown): boolean;
+export type CommandPermissionHostStatus = 'present' | 'missing' | 'unverified';
+/** Read-only hypothetical conditions. A match is not permission to execute the command. */
+export declare function explainCommandPermissions(command: Pick<CommandDescriptor, 'adapter' | 'permit'>, options: Readonly<{
+    source?: unknown;
+    rolesKnown?: boolean;
+    permissionHost: CommandPermissionHostStatus;
+}>): Readonly<{
+    permissionHost: CommandPermissionHostStatus;
+    adapter: Readonly<PermissionConditionExplanation>;
+    rules: readonly import("@zhin.js/permission").PermitRuleExplanation[];
+    summary: Readonly<PermissionConditionExplanation>;
+    unconstrained: readonly string[];
+    assumptions: readonly string[];
+}>;

package/lib/permission-explanation.js

@@ -0,0 +1,54 @@
+import { operationClientAdapter } from '@zhin.js/feature-kit';
+import { explainPermitRules, toPermissionSubject } from '@zhin.js/permission';
+import { resolveCommandSender, resolveCommandSession } from './definition.js';
+/** The exact subject projection used by the real command permit gate. No factories or checkers run. */
+export function toCommandPermissionSubject(source) {
+    const projected = toPermissionSubject(source);
+    const session = resolveCommandSession(source);
+    return { ...projected, ...session, ...(session.sender ? { sender: { ...projected.sender, ...session.sender } } : {}) };
+}
+/** Exact authoring adapter restriction, distinct from builtin adapter(...) matching. */
+export function commandAdapterMatches(command, source) {
+    return !command.adapter || operationClientAdapter(source) === command.adapter;
+}
+/** Read-only hypothetical conditions. A match is not permission to execute the command. */
+export function explainCommandPermissions(command, options) {
+    const projected = toCommandPermissionSubject(options.source);
+    const inputSender = options.source && typeof options.source === 'object'
+        ? options.source.sender : undefined;
+    const structuredRoles = inputSender && typeof inputSender === 'object'
+        && Array.isArray(inputSender.role);
+    // A sender-only assumption has no synthetic conversation. Apply the real canonical
+    // sender defaults without inventing an Endpoint or treating unknown roles as known.
+    const senderOnly = options.source && typeof options.source === 'object' && !('conversation' in options.source) && !structuredRoles
+        ? resolveCommandSender(options.source, undefined) : undefined;
+    const subject = senderOnly ? { ...projected, sender: senderOnly } : projected;
+    const defaultedRoles = options.rolesKnown && Array.isArray(inputSender?.roles) && inputSender.roles.length === 0
+        && subject.sender?.role.length === 1 && subject.sender.role[0] === 'user';
+    const actualAdapter = operationClientAdapter(options.source);
+    const adapter = !command.adapter
+        ? { outcome: 'not_evaluated', reason: '命令未声明 adapter 约束' }
+        : !actualAdapter ? { outcome: 'unknown', reason: '未选择当前 Endpoint，无法判断命令的精确 adapter 约束' }
+            : { outcome: commandAdapterMatches(command, options.source) ? 'match' : 'mismatch', reason: '命令 adapter 与当前 Endpoint 声明的原生适配器精确比较；未探测在线状态' };
+    const rules = explainPermitRules(command.permit ?? [], subject, { rolesKnown: options.rolesKnown });
+    const conditions = [...(command.adapter ? [adapter] : []), ...rules];
+    let summary;
+    if (conditions.some(item => item.outcome === 'mismatch'))
+        summary = { outcome: 'mismatch', reason: '至少一个声明条件与假设输入不符；这不是实际准入检查' };
+    else if ((rules.length > 0 && options.permissionHost !== 'present') || conditions.some(item => item.outcome === 'unknown')) {
+        summary = { outcome: 'unknown', reason: rules.length > 0 && options.permissionHost !== 'present'
+                ? 'PermissionHost 缺失或无法确认；不能推断命令可执行' : '存在缺少依据的条件，不能推断命令可执行' };
+    }
+    else if (rules.length === 0)
+        summary = { outcome: 'not_evaluated', reason: '命令未声明 permit 限制；这不表示已获得执行权限' };
+    else if (conditions.some(item => item.outcome === 'not_evaluated'))
+        summary = { outcome: 'not_evaluated', reason: '存在未执行的平台或自定义条件，不能推断命令可执行' };
+    else
+        summary = { outcome: 'match', reason: '已解释的 builtin 条件与假设输入匹配；不代表真实授权或命令可执行' };
+    return Object.freeze({ permissionHost: options.permissionHost, adapter: Object.freeze(adapter), rules, summary: Object.freeze(summary),
+        unconstrained: Object.freeze(['已解释的 builtin 规则不检查具体 Endpoint、parent 或 thread；保留完整目标不等于这些维度受规则限制']),
+        assumptions: Object.freeze(['身份与角色仅用于模拟，未向平台核实', '未执行命令、动态默认值、平台或自定义 checker',
+            ...(defaultedRoles
+                ? ['canonical 输入未附角色时按命令运行时默认 user 解释；这不是已核验的平台角色'] : [])]),
+    });
+}

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "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/feature-kit": "1.1.6",
     "@zhin.js/interaction": "1.1.2",
-    "@zhin.js/permission": "1.1.6"
+    "@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 } 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 {
@@ -143,9 +167,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,6 +268,8 @@ 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));
+    const limit = admitCommandExecution(undefined, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
+    if (limit) throw new CommandExecutionLimitedError(limit);
     return definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner,
       textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
   }
@@ -252,14 +282,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 +319,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 +347,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 +434,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 +507,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) }) };
   }
 }
 
@@ -839,10 +902,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>`,
+    },
+  };
+}