@zhin.js/command 1.1.10 → 1.1.12

package/src/command-menu.ts

@@ -1,9 +1,12 @@
-interface MenuEntry {
+import type { Locale } from '@zhin.js/plugin-runtime';
+import { commandMessages } from './messages.js';
+
+export interface CommandMenuEntry {
   readonly name: string;
   readonly description?: string;
 }
 
-interface MenuAppearance {
+export interface CommandMenuAppearance {
   readonly title?: string;
   readonly subtitle?: string;
   readonly accentColor?: string;
@@ -27,7 +30,7 @@ const escape = (value: string) => value.replace(/[&<>"']/gu, char => ({
 })[char] ?? char);
 
 /** Configuration is text/data, never an interpolated CSS or HTML fragment. */
-export function readMenuAppearance(value: unknown): MenuAppearance {
+export function readMenuAppearance(value: unknown): CommandMenuAppearance {
   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 } = {};
@@ -69,20 +72,21 @@ function icon(name: string, plugin = false): string {
 /** Presentation only: the unified outbound pipeline owns image rendering and fallback. */
 export function renderCommandMenu(
   title: string,
-  commands: readonly MenuEntry[],
-  children: readonly MenuEntry[],
+  commands: readonly CommandMenuEntry[],
+  children: readonly CommandMenuEntry[],
   hint: string | undefined,
   text: string,
-  options: { readonly page?: number; readonly pages?: number; readonly commandTotal?: number; readonly pluginTotal?: number; readonly appearance?: MenuAppearance } = {},
+  options: { readonly page?: number; readonly pages?: number; readonly locale?: Locale; readonly commandTotal?: number; readonly pluginTotal?: number; readonly appearance?: CommandMenuAppearance } = {},
 ): CommandMenuSegment {
+  const locale = options.locale ?? 'zh-CN';
   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 =>
+  const entries = (items: readonly CommandMenuEntry[], 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 ? ''
+  const section = (label: string, items: readonly CommandMenuEntry[], 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;
@@ -91,7 +95,7 @@ export function renderCommandMenu(
     type: 'html',
     data: {
       width: 1080, fileName: 'command-menu.png', text,
-      html: `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><style>
+      html: `<!doctype html><html lang="${locale}"><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}
@@ -102,11 +106,11 @@ h2{margin:0;font-size:20px;font-weight:700;letter-spacing:1px;color:var(--accent
 .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}
+.name{overflow-wrap:anywhere;white-space:pre-wrap}.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>`,
+</style></head><body><main><header><div class="eyebrow">ZHIN / COMMAND ATLAS</div><h1>${escape(appearance.title || commandMessages(locale, 'guideTitle', { title }))}</h1><div class="subtitle">${escape(appearance.subtitle ?? commandMessages(locale, 'guideSubtitle'))}</div><div class="summary"><i></i>${escape(commandMessages(locale, 'commandCount', { count: options.commandTotal ?? commands.length }))}<span>·</span>${escape(commandMessages(locale, 'pluginCount', { count: options.pluginTotal ?? children.length }))}<span>·</span>${escape(title)}</div></header>
+${section(commandMessages(locale, 'commandIndex'), commands, options.commandTotal ?? commands.length)}${section(commandMessages(locale, 'pluginIndex'), children, options.pluginTotal ?? children.length, true)}${commands.length || children.length ? '' : `<p class="empty">${commandMessages(locale, 'guideEmpty')}</p>`}
+<footer><div class="hint">${escape(hint ?? commandMessages(locale, 'genericHelpHint'))}</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

@@ -2,10 +2,12 @@
  * Command authoring API consumed from `zhin.js/command`.
  * @module zhin.js/command
  */
-import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { resolveLocale, type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import {
   createCapabilityContext,
   readOperationClient,
+  readOperationSession,
+  type OperationSession,
   readOperationInputSignal,
   type AdapterClient,
   type RegisteredAdapterName,
@@ -92,6 +94,8 @@ export interface CommandParamSchema {
   readonly type: CommandParameterType;
   readonly default?: CommandDynamicValue;
   readonly description?: string;
+  /** Optional translated display text; machine keys and values remain unchanged. */
+  readonly descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
   readonly optional?: boolean;
   readonly rest?: boolean;
   readonly min?: number;
@@ -145,6 +149,7 @@ export interface CommandParameterDefinition {
   /** `[...name]` / `[[...name]]` 捕获所有段，运行时值为 `string[]`。 */
   readonly rest?: boolean;
   readonly description?: string;
+  readonly descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
 }
 
 /** 场景：群 / 私聊 / 频道等。 */
@@ -192,6 +197,8 @@ export interface CommandConversation {
 export interface CommandMessage {
   readonly conversation: CommandConversation;
   readonly content: string;
+  /** Display preference resolved by the IM runtime, when this is an IM operation. */
+  readonly locale?: Locale;
   /** 发送者（结构化视图见 CommandContext.sender）。 */
   readonly sender?: { readonly id: string; readonly name?: string; readonly roles?: readonly string[] };
   readonly id?: string;
@@ -264,6 +271,16 @@ export interface CommandContext<
   TInput extends CommandMessage = CommandMessage,
   TAdapter extends string | undefined = undefined,
 > extends CapabilityContext<TConfig>, CommandSession {
+  /** Language resolved once for the current operation. */
+  readonly locale: Locale;
+  /**
+   * Resolve a static local command path to its current chat invocation. Defaults to this
+   * plugin; an explicit owner may reference another indexed plugin.
+   * Includes the actual Endpoint prefix and configured commandNamespace. Arguments
+   * are appended explicitly by the caller. Returns undefined for unknown/disabled
+   * paths or calls without a known chat command environment.
+   */
+  formatCommand(localPath: string, owner?: PluginId): string | undefined;
   readonly args: readonly string[];
   readonly params: Readonly<Record<string, CommandParameterValue>>;
   readonly options: Readonly<Record<string, CommandParameterValue>>;
@@ -276,6 +293,8 @@ export interface CommandContext<
   readonly input?: TInput;
   /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
   readonly $client: AdapterClient<TAdapter>;
+  /** Bound by the actual IM operation; direct CommandIndex.execute calls may have no Session. */
+  readonly session: OperationSession<TAdapter> | undefined;
   /**
    * 对话式交互输入。IM 派发时自动注入；无消息来源时为 `undefined`。
    */
@@ -294,6 +313,7 @@ export interface CommandDefinition<
   /** @internal Convention-derived parameter metadata. */
   readonly $parameter?: CommandParameterDefinition;
   readonly description?: string;
+  readonly descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
   /** Restrict this command to one adapter and infer `context.$client`. */
   readonly adapter?: TAdapter;
   /**
@@ -307,6 +327,8 @@ export interface CommandDefinition<
    * 用户路由；alias 只替换文件路径提供的静态段。
    */
   readonly alias?: readonly string[];
+  /** Display an explicitly declared alias for this locale; every value must also occur in alias. */
+  readonly preferredAliasI18n?: Readonly<Partial<Record<Locale, string>>>;
   /**
    * 内置 permit DSL（AND）。单项内逗号为 OR。
    * 例：`adapter(icqq)`、`role(master)`、`group(123,456)`。
@@ -360,28 +382,40 @@ type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extend
     readonly options: InferCommandOptions<O>;
   };
 
+/** The returned declaration retains its platform, parameter schemas and callback result. */
+type DeclaredCommandAdapter<D> = D extends { readonly adapter: infer A extends string } ? A
+  : D extends { readonly adapter?: infer A extends string | undefined } ? A : undefined;
+export type TypedCommandDefinition<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined, P extends CommandParams, O extends CommandOptions> =
+  Omit<CommandDefinition<TConfig, TResult, TInput, TAdapter>, 'params' | 'options' | 'execute'> & {
+    readonly params?: P;
+    readonly options?: O;
+    execute(context: TypedCommandContext<TConfig, TInput, TAdapter, P, O>): TResult | Promise<TResult>;
+  };
+
 /**
  * `defineCommand.withConfig<Config>()` 返回的定义函数：config 类型已固定，params / options / 返回值
  * 仍从定义推断。
  * @public
  */
 export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <
-  TResult = unknown,
+  const TResult = unknown,
   const P extends CommandParams = {},
   const O extends CommandOptions = {},
+  const D extends CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> = CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
 >(
-  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
-) => Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
+  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> & D,
+) => Readonly<TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>>;
 
 export function defineCommand<
   TConfig = unknown,
-  TResult = unknown,
+  const TResult = unknown,
   TInput extends CommandMessage = CommandMessage,
   const P extends CommandParams = {},
   const O extends CommandOptions = {},
+  const D extends CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> = CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
 >(
-  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
-): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>> {
+  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> & D,
+): Readonly<TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>> {
   if (typeof definition.execute !== 'function') {
     throw new TypeError('Command execute must be a function');
   }
@@ -398,15 +432,26 @@ export function defineCommand<
     }
   }
   validateArgumentSchemas(definition.params, definition.options);
+  validateDescriptionI18n(definition.descriptionI18n);
   validateCommandAlias(definition.alias);
+  validatePreferredAliases(definition);
   validateCommandPermit(definition.permit);
   validateCommandShortcutShape(definition.shortcut);
   const execution = normalizeExecutionPolicy(definition.execution);
   return Object.freeze({ $feature: commandBrand, ...definition, ...(execution ? { execution } : {}) }) as Readonly<
-    CommandDefinition<TConfig, TResult, TInput, string | undefined>
+    TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>
   >;
 }
 
+/** @internal Validate display-only translations without changing their fallback text. */
+export function validateDescriptionI18n(value: CommandDefinition['descriptionI18n']): void {
+  if (value === undefined) return;
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.entries(value).some(([locale, text]) => !['zh-CN', 'en'].includes(locale) || typeof text !== 'string')) {
+    throw new TypeError('Command descriptionI18n must map zh-CN/en to strings');
+  }
+}
+
 /**
  * 先固定插件 config 类型，再定义命令；params / options / 返回值仍从定义推断。
  *
@@ -435,6 +480,19 @@ function validateAdapterName(adapter: string | undefined): void {
   }
 }
 
+function validatePreferredAliases(definition: Pick<CommandDefinition, 'alias' | 'preferredAliasI18n'>): void {
+  const preferred = definition.preferredAliasI18n;
+  if (preferred === undefined) return;
+  validateDescriptionI18n(preferred);
+  const normalize = (value: string) => value.trim().split(/\s+/u).filter(Boolean).join(' ');
+  const aliases = new Set(definition.alias?.map(normalize));
+  for (const [locale, alias] of Object.entries(preferred)) {
+    if (!aliases.has(normalize(alias))) {
+      throw new TypeError(`Command preferredAliasI18n.${locale} must reference a declared alias`);
+    }
+  }
+}
+
 function validateCommandAlias(alias: readonly string[] | undefined): void {
   if (alias === undefined) return;
   if (!Array.isArray(alias)) {
@@ -506,6 +564,8 @@ export function parseCommandDefinition(value: unknown): CommandDefinition {
   }
   validateAdapterName(definition.adapter);
   normalizeExecutionPolicy(definition.execution);
+  validateCommandAlias(definition.alias);
+  validatePreferredAliases(definition);
   return definition as CommandDefinition;
 }
 
@@ -526,18 +586,31 @@ export function resolveDynamicParams(
   return Object.freeze(resolved);
 }
 
-/** @internal Command dispatcher assembly helper. */
-export function createCommandContext(
-  snapshot: RuntimeSnapshot,
-  ownerId: PluginId,
-  args: readonly string[],
-  params: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
-  input: unknown = undefined,
-  segments: readonly Readonly<CommandSegment>[] = Object.freeze([]),
-  interaction?: UserInteraction,
-  adapter?: string,
-  options: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
-): CommandContext {
+/** Parsed invocation values, independent of the caller's transport and lifetime. */
+export interface CommandInvocationArguments {
+  readonly args: readonly string[];
+  readonly params?: Readonly<Record<string, CommandParameterValue>>;
+  readonly options?: Readonly<Record<string, CommandParameterValue>>;
+  readonly segments?: readonly Readonly<CommandSegment>[];
+}
+
+/** Author and lifetime authority captured by the dispatcher for this invocation. */
+export interface CommandInvocationOperation {
+  readonly snapshot: RuntimeSnapshot;
+  readonly ownerId: PluginId;
+  readonly input?: unknown;
+  readonly interaction?: UserInteraction;
+  readonly adapter?: string;
+  readonly presentation?: Readonly<{
+    locale: Locale;
+    formatCommand?: (localPath: string, owner?: PluginId) => string | undefined;
+  }>;
+}
+
+/** @internal Command dispatcher assembly helper; each value has one owner. */
+export function createCommandContext(operation: CommandInvocationOperation, invocation: CommandInvocationArguments): CommandContext {
+  const { snapshot, ownerId, input, interaction, adapter, presentation } = operation;
+  const { args, params = {}, options = {}, segments = [] } = invocation;
   const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
   const session = resolveCommandSession(input);
   const parameterValues: Record<string, CommandParameterValue> = { __proto__: null, ...params };
@@ -545,6 +618,8 @@ export function createCommandContext(
   const result = {
     ...context,
     ...session,
+    locale: presentation?.locale ?? resolveLocale((snapshot.config.get(snapshot.root) as { locale?: unknown } | undefined)?.locale),
+    formatCommand: presentation?.formatCommand ?? (() => undefined),
     args: Object.freeze([...args]),
     params: Object.freeze(parameterValues),
     options: Object.freeze(optionValues),
@@ -552,6 +627,10 @@ export function createCommandContext(
     ...(input !== undefined ? { input: input as CommandMessage } : {}),
     ...(interaction !== undefined ? { interaction } : {}),
   } as CommandContext;
+  Object.defineProperty(result, 'session', {
+    enumerable: true,
+    get: () => readOperationSession(input, adapter),
+  });
   Object.defineProperty(result, '$client', {
     enumerable: true,
     get: () => readOperationClient(input, adapter),
@@ -565,6 +644,20 @@ export function createCommandContext(
  * @internal Command dispatcher projection helper.
  */
 export function resolveCommandSession(input: unknown): CommandSession {
+  const operation = readOperationSession(input);
+  if (operation) {
+    const endpoint = input && typeof input === 'object' ? (input as { readonly endpointId?: unknown }).endpointId : undefined;
+    const sender = operation.sender;
+    const roles = [...new Set([...sender?.authorizationRoles ?? [], ...sender?.platformRoles ?? []])];
+    return Object.freeze({
+      adapter: operation.scene.endpoint.adapter,
+      ...(typeof endpoint === 'string' && endpoint ? { endpoint } : {}),
+      scene: Object.freeze({ id: operation.scene.id, type: operation.scene.kind,
+        ...(operation.scene.name !== undefined ? { name: operation.scene.name } : {}) }),
+      ...(sender ? { sender: Object.freeze({ id: sender.id, ...(sender.name !== undefined ? { name: sender.name } : {}),
+        role: Object.freeze(roles.length ? roles : ['user']) }) } : {}),
+    });
+  }
   if (!isCommandMessageLike(input)) return Object.freeze({});
 
   const metadata = input.metadata && typeof input.metadata === 'object'

package/src/index.ts

@@ -28,4 +28,4 @@ export {
 } from './provider.js';
 export { default } from './provider.js';
 
-export type { CommandValidationIssue } from './arguments.js';
+export type { CommandValidationIssue, CommandValidationIssueCode } from './arguments.js';

package/src/messages.ts

@@ -0,0 +1,62 @@
+import { createMessages, type Locale } from '@zhin.js/plugin-runtime';
+
+/** Translates only display metadata explicitly supplied by its author. */
+export function commandDescription(
+  value: Readonly<{ description?: string; descriptionI18n?: Readonly<Partial<Record<Locale, string>>> }>,
+  locale: Locale,
+): string | undefined {
+  return value.descriptionI18n?.[locale] ?? value.description;
+}
+
+/** Static dictionaries; the caller supplies the operation's language. */
+export const commandMessages = createMessages({
+  menuKeyword: { 'zh-CN': '菜单', en: 'menu' },
+  invalidPage: { 'zh-CN': '页码必须是正整数。用法：{command} [插件名] --page <页码>', en: 'The page must be a positive integer. Usage: {command} [plugin] --page <page>' },
+  missingPlugin: { 'zh-CN': '未找到插件: {plugin}', en: 'Plugin not found: {plugin}' },
+  pageOutOfRange: { 'zh-CN': '页码超出范围：共 {pages} 页。请使用「{command} --page <页码>」。', en: 'Page out of range: {pages} pages available. Use {command} --page <page>.' },
+  menuTitle: { 'zh-CN': '=== {plugin} 指令菜单 ===', en: '=== {plugin} command menu ===' },
+  menuSummary: { 'zh-CN': '第 {page}/{pages} 页 · {commands} 条指令 · {plugins} 个子插件', en: 'Page {page}/{pages} · Commands: {commands} · Plugins: {plugins}' },
+  childPlugins: { 'zh-CN': '子插件：', en: 'Plugins:' },
+  emptyMenu: { 'zh-CN': '（暂无指令和子插件）', en: '(No commands or plugins)' },
+  pluginHint: { 'zh-CN': '提示：使用「{command} <插件名>」查看子插件的指令', en: 'Use {command} <plugin> to view a plugin’s commands.' },
+  previousPage: { 'zh-CN': '上一页：{command}', en: 'Previous page: {command}' },
+  nextPage: { 'zh-CN': '下一页：{command}', en: 'Next page: {command}' },
+  guideTitle: { 'zh-CN': '{title} · 指令指南', en: '{title} · Command guide' },
+  guideSubtitle: { 'zh-CN': '每一个灵感，都有回应。', en: 'An answer to every idea.' },
+  commandCount: { 'zh-CN': '{count} 条指令', en: 'Commands: {count}' },
+  pluginCount: { 'zh-CN': '{count} 个子插件', en: 'Plugins: {count}' },
+  commandIndex: { 'zh-CN': '指令索引', en: 'Commands' },
+  pluginIndex: { 'zh-CN': '插件导航', en: 'Plugins' },
+  guideEmpty: { 'zh-CN': '暂无指令和子插件', en: 'No commands or plugins' },
+  helpHint: { 'zh-CN': '查看参数与用法：{command} --help', en: 'View arguments and usage: {command} --help' },
+  genericHelpHint: { 'zh-CN': '在当前环境的指令后追加 --help 查看用法', en: 'Append --help to a command in this environment to view its usage' },
+  expectedType: { 'zh-CN': '{field}：应为 {type}', en: '{field}: expected {type}' },
+  expectedArray: { 'zh-CN': '{field}：应为 {type} 数组', en: '{field}: expected an array of {type}' },
+  minimum: { 'zh-CN': '{field}：最小值为 {minimum}', en: '{field}: minimum {minimum}' },
+  maximum: { 'zh-CN': '{field}：最大值为 {maximum}', en: '{field}: maximum {maximum}' },
+  choices: { 'zh-CN': '{field}：可选值为 {choices}', en: '{field}: expected one of {choices}' },
+  invalidFormat: { 'zh-CN': '{field}：格式不正确', en: '{field}: invalid format' },
+  invalidValue: { 'zh-CN': '{field}：值不正确', en: '{field}: invalid value' },
+  unknownOption: { 'zh-CN': '未知选项 {field}', en: 'Unknown option {field}' },
+  duplicateOption: { 'zh-CN': '重复选项 --{field}', en: 'Duplicate option --{field}' },
+  defaultUndefined: { 'zh-CN': '{field}：默认值返回了 undefined', en: '{field}: default returned undefined' },
+  parameterUndefined: { 'zh-CN': '{field}：默认值或快捷指令返回了 undefined', en: '{field}: default or shortcut returned undefined' },
+  missingOption: { 'zh-CN': '缺少选项 --{field}', en: 'Missing option --{field}' },
+  unexpectedArguments: { 'zh-CN': '存在多余参数', en: 'Unexpected arguments' },
+  invalidParameter: { 'zh-CN': '缺少指令参数或参数不正确', en: 'Missing or invalid command parameter' },
+  defaultValue: { 'zh-CN': '默认值：{value}', en: 'default: {value}' },
+  dynamicValue: { 'zh-CN': '动态计算', en: 'dynamic' },
+  noAdapter: { 'zh-CN': '命令未声明 adapter 约束', en: 'The command does not declare an adapter restriction' },
+  missingEndpoint: { 'zh-CN': '未选择当前 Endpoint，无法判断命令的精确 adapter 约束', en: 'Select an Endpoint to evaluate the command’s exact adapter restriction' },
+  adapterComparison: { 'zh-CN': '命令 adapter 与当前 Endpoint 声明的原生适配器精确比较；未探测在线状态', en: 'Exact comparison with the Endpoint’s declared native adapter; online status was not checked' },
+  conditionMismatch: { 'zh-CN': '至少一个声明条件与假设输入不符；这不是实际准入检查', en: 'At least one declared condition does not match the hypothetical input; this is not a live admission check' },
+  missingPermissionHost: { 'zh-CN': 'PermissionHost 缺失或无法确认；不能推断命令可执行', en: 'PermissionHost is missing or unverified; command execution cannot be inferred' },
+  missingEvidence: { 'zh-CN': '存在缺少依据的条件，不能推断命令可执行', en: 'Some conditions lack evidence; command execution cannot be inferred' },
+  noPermit: { 'zh-CN': '命令未声明 permit 限制；这不表示已获得执行权限', en: 'The command does not declare permit restrictions; this does not establish authorization' },
+  uncheckedConditions: { 'zh-CN': '存在未执行的平台或自定义条件，不能推断命令可执行', en: 'Platform or custom conditions have not been evaluated; command execution cannot be inferred' },
+  conditionsMatch: { 'zh-CN': '已解释的 builtin 条件与假设输入匹配；不代表真实授权或命令可执行', en: 'The explained builtin conditions match the hypothetical input; this does not establish authorization or executability' },
+  unconstrained: { 'zh-CN': '已解释的 builtin 规则不检查具体 Endpoint、parent 或 thread；保留完整目标不等于这些维度受规则限制', en: 'The explained builtin rules do not constrain a specific Endpoint, parent or thread; retaining the full target does not add such restrictions' },
+  simulatedIdentity: { 'zh-CN': '身份与角色仅用于模拟，未向平台核实', en: 'Identity and roles are hypothetical and have not been verified with the platform' },
+  unevaluatedCode: { 'zh-CN': '未执行命令、动态默认值、平台或自定义 checker', en: 'Commands, dynamic defaults, platform checks and custom checkers have not been executed' },
+  defaultedRole: { 'zh-CN': 'canonical 输入未附角色时按命令运行时默认 user 解释；这不是已核验的平台角色', en: 'Canonical input without roles uses the command runtime’s default user role; this is not a verified platform role' },
+});

package/src/permission-explanation.ts

@@ -2,6 +2,8 @@ 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';
+import { resolveLocale, type Locale } from '@zhin.js/plugin-runtime';
+import { commandMessages } from './messages.js';
 
 /** The exact subject projection used by the real command permit gate. No factories or checkers run. */
 export function toCommandPermissionSubject(source: unknown): PermissionSubject {
@@ -20,8 +22,9 @@ 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 }>,
+  options: Readonly<{ source?: unknown; rolesKnown?: boolean; permissionHost: CommandPermissionHostStatus; locale?: Locale }>,
 ) {
+  const locale = resolveLocale(options.locale);
   const projected = toCommandPermissionSubject(options.source);
   const inputSender = options.source && typeof options.source === 'object'
     ? (options.source as Pick<CommandMessage, 'sender'>).sender : undefined;
@@ -36,23 +39,23 @@ export function explainCommandPermissions(
     && 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 });
+    ? { outcome: 'not_evaluated', reason: commandMessages(locale, 'noAdapter') }
+    : !actualAdapter ? { outcome: 'unknown', reason: commandMessages(locale, 'missingEndpoint') }
+      : { outcome: commandAdapterMatches(command, options.source) ? 'match' : 'mismatch', reason: commandMessages(locale, 'adapterComparison') };
+  const rules = explainPermitRules(command.permit ?? [], subject, { rolesKnown: options.rolesKnown, locale });
   const conditions = [...(command.adapter ? [adapter] : []), ...rules];
   let summary: PermissionConditionExplanation;
-  if (conditions.some(item => item.outcome === 'mismatch')) summary = { outcome: 'mismatch', reason: '至少一个声明条件与假设输入不符；这不是实际准入检查' };
+  if (conditions.some(item => item.outcome === 'mismatch')) summary = { outcome: 'mismatch', reason: commandMessages(locale, 'conditionMismatch') };
   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 条件与假设输入匹配；不代表真实授权或命令可执行' };
+      ? commandMessages(locale, 'missingPermissionHost') : commandMessages(locale, 'missingEvidence') };
+  } else if (rules.length === 0) summary = { outcome: 'not_evaluated', reason: commandMessages(locale, 'noPermit') };
+  else if (conditions.some(item => item.outcome === 'not_evaluated')) summary = { outcome: 'not_evaluated', reason: commandMessages(locale, 'uncheckedConditions') };
+  else summary = { outcome: 'match', reason: commandMessages(locale, 'conditionsMatch') };
   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',
+    unconstrained: Object.freeze([commandMessages(locale, 'unconstrained')]),
+    assumptions: Object.freeze([commandMessages(locale, 'simulatedIdentity'), commandMessages(locale, 'unevaluatedCode'),
       ...(defaultedRoles
-        ? ['canonical 输入未附角色时按命令运行时默认 user 解释；这不是已核验的平台角色'] : [])]),
+        ? [commandMessages(locale, 'defaultedRole')] : [])]),
   });
 }

package/src/provider.ts

@@ -311,7 +311,7 @@ const commandFeature = defineFeatureProvider({
       const rawKeyword = rootConfig?.menuKeyword;
       const menu = rawKeyword === false || rawKeyword === ''
         ? undefined
-        : { keyword: typeof rawKeyword === 'string' ? rawKeyword : '菜单' };
+        : typeof rawKeyword === 'string' ? { keyword: rawKeyword } : {};
       return { value: new CommandIndex(slots, context.snapshot, menu) };
     },
   },