@zhin.js/command 1.1.6 → 1.1.8

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 构建时拒绝。
@@ -383,7 +388,8 @@ 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>
   >;
 }
@@ -464,6 +470,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 +503,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 +541,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 +590,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 +617,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);
+}

package/src/execution-runtime.ts

@@ -0,0 +1,165 @@
+/** Internal composition contract. Not part of the command authoring facade. */
+import { createToken, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { CommandExecutionLimit, CommandExecutionPolicy } from './execution-policy.js';
+
+interface ConversationIdentity {
+  readonly endpoint: { readonly adapter: string; readonly id: string };
+  readonly kind: string;
+  readonly id: string;
+  readonly parent?: { readonly kind: string; readonly id: string };
+  readonly threadId?: string;
+}
+
+interface AdmissionReader {
+  admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined;
+}
+
+/** @internal Admission-only Root resource; no bind or finish authority is published. */
+export const commandExecutionAdmissionToken = createToken<AdmissionReader>('zhin.command.execution-admission');
+
+/** @internal Held only by Core's actual leased operation. */
+export interface CommandOperationController {
+  bind(view: object, owner: PluginId): void;
+  /** Core registers actual started delivery promises, never a caller-supplied completion callback. */
+  trackSend(send: Promise<unknown>): void;
+  /** Stop pending feedback and drain already-started feedback before the final reply. */
+  stopProgress(): Promise<void>;
+  /** Called only by the real outer operation's finally, after all final sends settle. */
+  finish(): Promise<void>;
+}
+
+interface Entry { active: number; cooldownUntil: number }
+interface Operation {
+  snapshot?: RuntimeSnapshot;
+  key?: readonly string[];
+  active: boolean;
+  progressStopped: boolean;
+  admitted: boolean;
+  signal: AbortSignal;
+  reply?: (owner: PluginId, text: string) => Promise<unknown>;
+  readonly releases: (() => void)[];
+  readonly timers: Set<ReturnType<typeof setTimeout>>;
+  readonly feedback: Promise<void>[];
+  readonly accepted: Set<string>;
+  readonly sends: Set<Promise<void>>;
+}
+
+/** @internal Root-instance-owned state shared by projections and draining retired generations. */
+export class CommandExecutionBudget {
+  readonly #entries = new Map<string, Entry>();
+  readonly #views = new WeakMap<object, { operation: Operation; owner: PluginId }>();
+  readonly #clock: () => number;
+  readonly #capacity: number;
+  readonly admission: AdmissionReader;
+
+  constructor(options: { readonly clock?: () => number; readonly capacity?: number } = {}) {
+    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<AdmissionReader>({ admit: (source, capability, owner, policy, snapshot) => this.#admit(source, capability, owner, policy, snapshot) });
+  }
+
+  openOperation(input: {
+    readonly snapshot: RuntimeSnapshot;
+    readonly conversation: ConversationIdentity;
+    readonly senderId?: string;
+    readonly retirementSignal: AbortSignal;
+    readonly reply: (owner: PluginId, text: string) => Promise<unknown>;
+  }): CommandOperationController {
+    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: 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: object, owner: PluginId) => { if (operation.active) this.#views.set(view, { operation, owner }); },
+      trackSend: (send: Promise<unknown>) => {
+        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: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined {
+    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: Promise<void>;
+        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: unknown): value is string { return typeof value === 'string' && value.length > 0; }
+function limited(reason: CommandExecutionLimit['reason']): CommandExecutionLimit { return Object.freeze({ reason }); }
+
+/** @internal Projection reads the Root resource; ordinary authoring values cannot bind an operation. */
+export function admitCommandExecution(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy | undefined, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined {
+  if (!policy) return undefined;
+  const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id) as AdmissionReader | undefined;
+  return reader ? reader.admit(source, capability, owner, policy, snapshot) : limited('service_unavailable');
+}

package/src/index.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,

package/src/permission-explanation.ts

@@ -0,0 +1,58 @@
+import { operationClientAdapter } from '@zhin.js/feature-kit';
+import { explainPermitRules, toPermissionSubject, type PermissionSubject, type PermissionConditionExplanation } from '@zhin.js/permission';
+import { resolveCommandSender, resolveCommandSession, type CommandMessage } from './definition.js';
+import type { CommandDescriptor } from './command-index.js';
+
+/** The exact subject projection used by the real command permit gate. No factories or checkers run. */
+export function toCommandPermissionSubject(source: unknown): PermissionSubject {
+  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: Readonly<{ adapter?: string }>, source: unknown): boolean {
+  return !command.adapter || operationClientAdapter(source) === command.adapter;
+}
+
+export type CommandPermissionHostStatus = 'present' | 'missing' | 'unverified';
+
+/** Read-only hypothetical conditions. A match is not permission to execute the command. */
+export function explainCommandPermissions(
+  command: Pick<CommandDescriptor, 'adapter' | 'permit'>,
+  options: Readonly<{ source?: unknown; rolesKnown?: boolean; permissionHost: CommandPermissionHostStatus }>,
+) {
+  const projected = toCommandPermissionSubject(options.source);
+  const inputSender = options.source && typeof options.source === 'object'
+    ? (options.source as Pick<CommandMessage, 'sender'>).sender : undefined;
+  const structuredRoles = inputSender && typeof inputSender === 'object'
+    && Array.isArray((inputSender as { readonly role?: unknown }).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 as Pick<CommandMessage, 'sender'>, 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: PermissionConditionExplanation = !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: PermissionConditionExplanation;
+  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 解释；这不是已核验的平台角色'] : [])]),
+  });
+}