@aalis/plugin-commands 0.13.1 → 0.15.0

package/dist/commands.d.ts

@@ -1,6 +1,14 @@
-import type { ExecutionGuard } from '@aalis/api-authority';
+import type { AuthorityService, ExecutionGuard } from '@aalis/api-authority';
 import type { Command, CommandBuilder, CommandService, ExecutionInput, InternalCommandMeta } from '@aalis/api-commands';
-import type { Logger } from '@aalis/core';
+import { type I18nService } from '@aalis/api-i18n';
+import type { Logger, ServiceSelection } from '@aalis/core';
+import { type TextRef } from '@aalis/schema-i18n';
+/** 帮助按谁的等级过滤、按谁的语言渲染：执行时守卫裁决的同一个身份，与这条指令所在的会话 */
+interface Caller {
+    sessionId: string;
+    platform: string;
+    userId?: string;
+}
 export declare class CommandRegistry implements CommandService {
     /**
      * 名字 → 声明栈。空栈 = 自动创建的分组节点。
@@ -12,11 +20,17 @@ export declare class CommandRegistry implements CommandService {
     /** 别名映射：aliasName → realName */
     private readonly aliases;
     private readonly logger;
+    /** 权限服务：帮助按它的 authorize 判调用者能用哪些指令，与执行守卫的等级裁决同一份 */
+    private readonly authority;
+    /** 回复与帮助按读者的语言渲染；缺席时按原文 */
+    private readonly i18n;
+    /** i18n 渲染抛错时告警过了：之后再出错不再告警 */
+    private renderWarned;
     private _guard?;
     prefix: string;
-    constructor(logger: Logger);
-    setExecutionGuard(guard: ExecutionGuard): void;
-    command(rawName: string, description?: string, meta?: InternalCommandMeta): CommandBuilder;
+    constructor(logger: Logger, authority: Pick<ServiceSelection<AuthorityService>, 'present' | 'use'>, i18n: Pick<ServiceSelection<I18nService>, 'present' | 'use'>);
+    setExecutionGuard(guard: ExecutionGuard | undefined): void;
+    command(rawName: string, description?: string | TextRef, meta?: InternalCommandMeta): CommandBuilder;
     /** builder 写入**自己那一层声明**（闭包持有，无需每次查表）。 */
     private makeBuilder;
     /** 自动创建祖先分组节点（不替换已存在节点） */
@@ -42,12 +56,10 @@ export declare class CommandRegistry implements CommandService {
      * 分组节点由 `ensureGroups` 自动创建（空栈、无 pluginName），因此**任何按插件名的摘除都
      * 匹配不到它们**——空栈上 `dropped.length === 0` 直接返回。
      *
-     * 后果是用户可见的：卸载 `plugin-user-relation` 后 `relation` / `relation.cleanup` 留着，
-     * `hasMatch('relation')` 仍为真，于是指令相位**吞掉** `/relation` 不放行给普通消息管道，
-     * 回一段指向空节点的用法；`/help` 概览还会长出「`/relation` — 0 个子指令」。
-     * 而 `relation` 正是全仓唯一的占位分组，卸载该插件必然踩到。
+     * 后果是用户可见的：一个插件只登记了 `a.b.c`，卸载后自动建的 `a` / `a.b` 留着，
+     * `hasMatch('a')` 仍为真，于是指令相位**吞掉** `/a` 不放行给普通消息管道，回一段指向空节点的用法。
      *
-     * 反复扫直到不动点：删掉 `relation.cleanup` 会让 `relation` 也变成无子节点的空壳。
+     * 反复扫直到不动点：删掉 `a.b` 会让 `a` 也变成无子节点的空壳。
      */
     private pruneEmptyGroups;
     parseCommand(input: string): {
@@ -74,14 +86,39 @@ export declare class CommandRegistry implements CommandService {
      */
     hasMatch(head: string, tokens?: string[]): boolean;
     execute(name: string, input: ExecutionInput): Promise<string | undefined>;
+    /**
+     * 同 {@link execute}，回复不渲染：文字对象原样交出。聊天回复用它，把文字对象交给网关按会话的语言渲染；
+     * 帮助（裸敲分组、-h）照旧是按调用者所在会话的语言渲染好的字符串
+     */
+    run(name: string, input: ExecutionInput): Promise<string | TextRef | undefined>;
     private materialize;
+    /** `/help` 的概览：调用者看得见的顶层指令（help 自己不列） */
+    overview(caller: Caller): string;
+    /**
+     * `/help <指令>`、`<指令> -h` 与裸敲分组共用的回答。`/help` 问调用者看不见的指令，与问不存在的指令回同一句。
+     * 指令登记了 usage 时整段用它。
+     */
+    detail(path: string[], caller: Caller): string;
+    /** 用法（同帮助，按调用者所在会话的语言渲染好）；给了 error 时报错在前，同一次渲染 */
+    private usageOf;
+    /** 报错后附上用法；调用者看不见这条指令时只回报错 */
+    private withUsage;
+    /**
+     * 按调用者所在会话的语言渲染（i18n 缺席时按原文）。帮助一次要渲染几十段，整份交给这里一次，语言链只算一次；
+     * i18n 渲染抛错时按原文，告警一次
+     */
+    private localize;
+    private entries;
+    /** 帮助里看得见：调用者能用的指令，或底下有看得见的指令的分组 */
+    private visible;
     /**
-     * 单条指令的用法详情。与 `/help <指令>` 共用同一个渲染器（help.ts 的
-     * renderDetail）——裸调用分组、未知选项报错、help 详情三条路径一处修全部好。
+     * 调用者能不能用这条指令：有权限服务时按它的 authorize（执行守卫的等级裁决就是它，确认不算），
+     * 没有时按执行时同样的 fail-closed
      */
-    private formatUsage;
+    private permits;
     private directChildren;
     private parseArgs;
     private defaultOptions;
 }
+export {};
 //# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA2D,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEpH,OAAO,KAAK,EACV,OAAO,EAEP,cAAc,EAEd,cAAc,EACd,cAAc,EACd,mBAAmB,EAMpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAqG1C,qBAAa,eAAgB,YAAW,cAAc;IACpD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,gCAAgC;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,MAAM,CAAC,CAAiB;IAEhC,MAAM,SAAO;gBAED,MAAM,EAAE,MAAM;IAM1B,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAM9C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,cAAc;IA4D1F,0CAA0C;IAC1C,OAAO,CAAC,WAAW;IAiCnB,2BAA2B;IAC3B,OAAO,CAAC,YAAY;IAUpB;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAkBlD;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAUnB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gBAAgB;IAexB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAgBjF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,OAAO,CAAC,aAAa;IAIrB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAMtC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,GAAG,SAAS;IAKrD,MAAM,IAAI,OAAO,EAAE;IAMnB;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAkBf;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG,OAAO;IAIhD,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAkE/E,OAAO,CAAC,WAAW;IAyDnB;;;OAGG;IACH,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,SAAS;IA6FjB,OAAO,CAAC,cAAc;CAKvB"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}

package/dist/commands.js

@@ -1,5 +1,8 @@
 import { capabilityMinLevel, DEFAULT_AUTHORITY, riskDefaults } from '@aalis/api-authority';
-import { renderDetail } from './help.js';
+import { localizeFor } from '@aalis/api-i18n';
+import { isTextRef, TextError, textOf, toSource } from '@aalis/schema-i18n';
+import { renderDetail, renderOverview } from './help.js';
+import { t } from './texts.js';
 // ============================================================================
 // 命令注册表（v2 — 链式 builder）
 //
@@ -17,7 +20,7 @@ const NAME_SEGMENT_RE = /^[a-z][a-z0-9-]*$/;
  *
  * 栈顶决定「跑谁的实现」，但不该决定「谁能跑」——否则后注册者只要压一层就能放宽权限。
  *
- * ⚠️ **必须整份取，不能逐轴取严**。visibility / confirm / risk 三轴各自独立取最严实测不单调：
+ * 注意：**必须整份取，不能逐轴取严**。visibility / confirm / risk 三轴各自独立取最严实测不单调：
  * 真正的裁决函数里 **risk 一旦存在就完全遮蔽 visibility**
  * （见 `capabilityMinLevel`），于是「未声明 risk」在合并时被当成最弱、在裁决时却代表更强的
  * visibility 兜底。给 `{visibility:'restricted'}` 的 /shutdown 压一层 `{risk:'safe'}`，
@@ -77,10 +80,18 @@ export class CommandRegistry {
     /** 别名映射：aliasName → realName */
     aliases = new Map();
     logger;
+    /** 权限服务：帮助按它的 authorize 判调用者能用哪些指令，与执行守卫的等级裁决同一份 */
+    authority;
+    /** 回复与帮助按读者的语言渲染；缺席时按原文 */
+    i18n;
+    /** i18n 渲染抛错时告警过了：之后再出错不再告警 */
+    renderWarned = false;
     _guard;
     prefix = '/';
-    constructor(logger) {
+    constructor(logger, authority, i18n) {
         this.logger = logger.child('commands');
+        this.authority = authority;
+        this.i18n = i18n;
     }
     // ---- Guard ----
     setExecutionGuard(guard) {
@@ -160,6 +171,13 @@ export class CommandRegistry {
                 decl.options.push(parseOptionSyntax(optName, syntax, opts));
                 return self;
             },
+            argument: (argName, description) => {
+                const arg = decl.positionalArgs.find(a => a.name === argName);
+                if (!arg)
+                    throw new Error(`指令 ${name} 没有位置参数 ${argName}`);
+                arg.description = description;
+                return self;
+            },
             action: (handler) => {
                 decl.handler = handler;
                 return self;
@@ -234,12 +252,10 @@ export class CommandRegistry {
      * 分组节点由 `ensureGroups` 自动创建（空栈、无 pluginName），因此**任何按插件名的摘除都
      * 匹配不到它们**——空栈上 `dropped.length === 0` 直接返回。
      *
-     * 后果是用户可见的：卸载 `plugin-user-relation` 后 `relation` / `relation.cleanup` 留着，
-     * `hasMatch('relation')` 仍为真，于是指令相位**吞掉** `/relation` 不放行给普通消息管道，
-     * 回一段指向空节点的用法；`/help` 概览还会长出「`/relation` — 0 个子指令」。
-     * 而 `relation` 正是全仓唯一的占位分组，卸载该插件必然踩到。
+     * 后果是用户可见的：一个插件只登记了 `a.b.c`，卸载后自动建的 `a` / `a.b` 留着，
+     * `hasMatch('a')` 仍为真，于是指令相位**吞掉** `/a` 不放行给普通消息管道，回一段指向空节点的用法。
      *
-     * 反复扫直到不动点：删掉 `relation.cleanup` 会让 `relation` 也变成无子节点的空壳。
+     * 反复扫直到不动点：删掉 `a.b` 会让 `a` 也变成无子节点的空壳。
      */
     pruneEmptyGroups() {
         let removed = true;
@@ -326,31 +342,26 @@ export class CommandRegistry {
         return this.resolve(head, tokens) !== null;
     }
     async execute(name, input) {
+        return this.localize(await this.run(name, input), input);
+    }
+    /**
+     * 同 {@link execute}，回复不渲染：文字对象原样交出。聊天回复用它，把文字对象交给网关按会话的语言渲染；
+     * 帮助（裸敲分组、-h）照旧是按调用者所在会话的语言渲染好的字符串
+     */
+    async run(name, input) {
         const resolved = this.resolve(name, input.args);
         if (!resolved)
-            return `未知指令: ${this.prefix}${name}。输入 ${this.prefix}help 查看帮助。`;
+            return t('unknownCommand', { command: `${this.prefix}${name}`, prefix: this.prefix });
         const cmd = this.materialize(resolved.name);
-        // ⚠️ 这两步（分组用法、parseArgs 的报错）**先于守卫**返回，所以会把无权使用的指令列出来。
-        // 最直观的样本是 `/relation cleanup`：`relation.cleanup` 是 ensureGroups 自动建的无
-        // handler 分组节点，敲它会把 `relation.cleanup.*` 那 6 条 restricted 子指令一并列出。
-        // （裸敲 `/relation` 只列出下一层的分组名，实测要再敲一层才到那 5 条。）
-        //
-        // **决定不做过滤**。这是降噪而非防泄漏——开源项目里指令存在性本就
-        // 公开（源码、文档、npm 包都写着）。而且只堵这里等于只堵一半：低权限用户直敲受限指令时，
-        // authority 的拒绝文案照样暴露存在性，要真做得连那条通用文案一起改，而它同时服务 tools
-        // 与 commands 两个注入点，牵动所有能力的拒绝语义，改动面大于收益。
-        // 真要做的话两条一起：注入与执行侧同源的 authorize 判定，只取等级轴，明确排除 confirm
-        // 与临时授予（前者是 async 且会真弹确认框、后者随会话漂移，都不适合用于列表渲染）。
-        // /help 的概览与详情（plugin-commands 的 renderOverview/renderDetail）是同族第三条
-        // 列举路径，同属本裁定——2026-08 审计曾把它当漏项翻出，特此留痕勿再重开。
-        if (!cmd.handler) {
-            return this.formatUsage(cmd);
-        }
-        const parsed = this.parseArgs(cmd, resolved.remaining);
-        if (typeof parsed === 'string')
+        // 裸敲分组与 -h、--help 回的都是 `/help <指令>` 那一段：调用者用不了的指令在帮助里当作不存在。
+        // 直接执行用不了的指令由守卫拒绝，拒绝文案照旧点名指令
+        if (!cmd.handler || asksHelp(resolved.remaining))
+            return this.detail(resolved.name.split('.'), input);
+        const parsed = this.parseArgs(cmd, resolved.remaining, input);
+        if (typeof parsed === 'string' || isTextRef(parsed))
             return parsed;
         if (this._guard) {
-            const rejection = await this._guard({
+            const verdict = await this._guard({
                 name: cmd.name,
                 type: 'command',
                 visibility: cmd.visibility,
@@ -359,15 +370,16 @@ export class CommandRegistry {
                 sessionId: input.sessionId,
                 platform: input.platform,
                 userId: input.userId,
+                // 参与者只有发出者：聊天入站已把授权身份并进 platform 与 userId，没有账号的是无主体
+                participants: [{ platform: input.platform, userId: input.userId ?? '' }],
                 skipConfirm: input.skipConfirm,
+                confirmIntent: input.confirmIntent,
             });
-            if (rejection)
-                return rejection;
+            if (!verdict.ok)
+                return verdict.reason;
         }
-        else if (cmd.confirm || capabilityMinLevel({ risk: cmd.risk, visibility: cmd.visibility }) > DEFAULT_AUTHORITY) {
-            // 没有守卫（未装权限插件）时 fail-closed，口径与 plugin-tools 相同：等同人人都是默认等级、
-            // 没有确认通道。需要更高等级或需要确认的指令一律拒绝，默认等级可用且无需确认的照常执行。
-            return `指令 ${this.prefix}${cmd.name} 需要权限校验或确认，但未安装权限插件 @aalis/plugin-authority，已拒绝执行`;
+        else if (needsAuthority(cmd)) {
+            return t('needsAuthority', { command: `${this.prefix}${cmd.name}` });
         }
         try {
             const argv = {
@@ -384,9 +396,9 @@ export class CommandRegistry {
             return result ?? undefined;
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            this.logger.error(`指令 ${this.prefix}${cmd.name} 执行失败: ${message}`);
-            return `指令执行失败: ${message}`;
+            const error = textOf(err);
+            this.logger.error(`指令 ${this.prefix}${cmd.name} 执行失败: ${toSource(error)}`);
+            return t('failed', { error });
         }
     }
     // ---- 内部：把 patches 合成有效 Command（含父级可见性 + 权限继承） ----
@@ -425,7 +437,7 @@ export class CommandRegistry {
             name,
             pluginName: top?.pluginName ?? 'unknown',
             // 空栈 = 自动创建的分组节点，描述在此派生而非落字段（少存一份、不会陈旧）。
-            description: top?.description ?? `${name} 命令组`,
+            description: top?.description ?? t('group', { name }),
             visibility,
             confirm,
             risk,
@@ -444,15 +456,70 @@ export class CommandRegistry {
             isGroup: stack.length === 0,
         };
     }
-    // ---- usage 自动格式化 ----
+    // ---- 帮助 ----
+    /** `/help` 的概览：调用者看得见的顶层指令（help 自己不列） */
+    overview(caller) {
+        const tops = [...this.nodes.keys()].filter(n => !n.includes('.') && n !== 'help').sort();
+        return renderOverview(this.entries(tops, caller), this.prefix, value => this.localize(value, caller));
+    }
     /**
-     * 单条指令的用法详情。与 `/help <指令>` 共用同一个渲染器（help.ts 的
-     * renderDetail）——裸调用分组、未知选项报错、help 详情三条路径一处修全部好。
+     * `/help <指令>`、`<指令> -h` 与裸敲分组共用的回答。`/help` 问调用者看不见的指令，与问不存在的指令回同一句。
+     * 指令登记了 usage 时整段用它。
      */
-    formatUsage(cmd) {
-        if (cmd.usage)
-            return cmd.usage;
-        return renderDetail(cmd, this.directChildren(cmd.name).map(n => this.materialize(n)), this.prefix);
+    detail(path, caller) {
+        const cmd = this.getNode(path);
+        if (!cmd || !this.visible(cmd.name, caller)) {
+            return this.localize(t('noCommand', { path: path.join(' '), prefix: this.prefix }), caller);
+        }
+        return this.usageOf(cmd, caller);
+    }
+    /** 用法（同帮助，按调用者所在会话的语言渲染好）；给了 error 时报错在前，同一次渲染 */
+    usageOf(cmd, caller, error) {
+        const localize = value => this.localize(value, caller);
+        if (cmd.usage !== undefined)
+            return error ? `${localize(error)}\n\n${cmd.usage}` : cmd.usage;
+        return renderDetail(cmd, this.entries(this.directChildren(cmd.name), caller), this.prefix, localize, error);
+    }
+    /** 报错后附上用法；调用者看不见这条指令时只回报错 */
+    withUsage(error, cmd, caller) {
+        return this.visible(cmd.name, caller) ? this.usageOf(cmd, caller, error) : error;
+    }
+    /**
+     * 按调用者所在会话的语言渲染（i18n 缺席时按原文）。帮助一次要渲染几十段，整份交给这里一次，语言链只算一次；
+     * i18n 渲染抛错时按原文，告警一次
+     */
+    localize(value, caller) {
+        return localizeFor(this.i18n, value, { sessionId: caller.sessionId, platform: caller.platform }, {
+            onError: err => {
+                if (this.renderWarned)
+                    return;
+                this.renderWarned = true;
+                this.logger.warn('按会话的语言渲染指令的回复与帮助出错，按原文交出（之后再出错不再告警）:', err);
+            },
+        });
+    }
+    entries(names, caller) {
+        return names
+            .filter(n => this.visible(n, caller))
+            .map(n => ({
+            cmd: this.materialize(n),
+            children: this.directChildren(n).filter(c => this.visible(c, caller)).length,
+        }));
+    }
+    /** 帮助里看得见：调用者能用的指令，或底下有看得见的指令的分组 */
+    visible(name, caller) {
+        const cmd = this.materialize(name);
+        return cmd.handler ? this.permits(cmd, caller) : this.directChildren(name).some(c => this.visible(c, caller));
+    }
+    /**
+     * 调用者能不能用这条指令：有权限服务时按它的 authorize（执行守卫的等级裁决就是它，确认不算），
+     * 没有时按执行时同样的 fail-closed
+     */
+    permits(cmd, caller) {
+        if (!this.authority.present)
+            return !needsAuthority(cmd);
+        const request = { capability: `command:${cmd.name}`, visibility: cmd.visibility, risk: cmd.risk };
+        return this.authority.use.authorize(caller, request) === null;
     }
     directChildren(parent) {
         const prefix = `${parent}.`;
@@ -467,7 +534,7 @@ export class CommandRegistry {
         return out.sort();
     }
     // ---- 选项 + 位置参数 解析 ----
-    parseArgs(cmd, rawArgs) {
+    parseArgs(cmd, rawArgs, caller) {
         const options = this.defaultOptions(cmd.options);
         const positionalTokens = [];
         try {
@@ -480,11 +547,13 @@ export class CommandRegistry {
                 if (token.startsWith('--') && token.length > 2) {
                     const eq = token.indexOf('=');
                     const rawName = eq >= 0 ? token.slice(2, eq) : token.slice(2);
-                    const negated = rawName.startsWith('no-');
+                    // 先按全名找：选项名本身可以以 no- 开头（--no-llm）；找不到才当作反写（--no-cache 关掉 cache）
+                    const exact = findOption(cmd.options, rawName);
+                    const negated = !exact && rawName.startsWith('no-');
                     const optName = negated ? rawName.slice(3) : rawName;
-                    const def = findOption(cmd.options, optName);
+                    const def = exact ?? (negated ? findOption(cmd.options, optName) : undefined);
                     if (!def)
-                        return `未知选项: --${optName}\n\n${this.formatUsage(cmd)}`;
+                        return this.withUsage(t('unknownOption', { option: `--${rawName}` }), cmd, caller);
                     let rawValue = eq >= 0 ? token.slice(eq + 1) : undefined;
                     if (def.type === 'boolean') {
                         options[def.name] = negated ? false : rawValue === undefined ? true : parseBoolean(rawValue);
@@ -499,7 +568,7 @@ export class CommandRegistry {
                             rawValue = rawArgs[i];
                         }
                         if (rawValue === undefined)
-                            return `选项 --${optName} 缺少取值`;
+                            return t('missingValue', { option: `--${optName}` });
                         options[def.name] = parseOptionValue(def, rawValue, options[def.name]);
                     }
                     continue;
@@ -507,8 +576,13 @@ export class CommandRegistry {
                 if (token.startsWith('-') && token.length > 1) {
                     const alias = token.slice(1);
                     const def = findOption(cmd.options, alias);
+                    // 负数没有同名选项时是位置参数（/level <目标> -1 封禁）
+                    if (!def && /^\d/.test(alias)) {
+                        positionalTokens.push(token);
+                        continue;
+                    }
                     if (!def)
-                        return `未知选项: -${alias}\n\n${this.formatUsage(cmd)}`;
+                        return this.withUsage(t('unknownOption', { option: `-${alias}` }), cmd, caller);
                     if (def.type === 'boolean') {
                         options[def.name] = true;
                     }
@@ -520,7 +594,7 @@ export class CommandRegistry {
                                 options[def.name] = true;
                                 continue;
                             }
-                            return `选项 -${alias} 缺少取值`;
+                            return t('missingValue', { option: `-${alias}` });
                         }
                         options[def.name] = parseOptionValue(def, rawValue, options[def.name]);
                     }
@@ -530,13 +604,17 @@ export class CommandRegistry {
             }
             for (const o of cmd.options) {
                 if (o.required && options[o.name] === undefined)
-                    return `缺少必填选项: --${o.name}`;
+                    return t('missingOption', { option: `--${o.name}` });
             }
             // 有子指令、自身不收位置参数的指令，多出来的词是写错或不存在的子指令名，或是写多了的选项值
             // （`/clear -t context vector`）：报错并指向 /help，不忽略后执行本指令（否则 `/clear alll`
             // 会在确认后清掉当前会话）
             if (cmd.positionalArgs.length === 0 && positionalTokens.length > 0 && this.directChildren(cmd.name).length > 0) {
-                return `未知子指令或多余参数: ${positionalTokens[0]}。输入 ${this.prefix}help ${cmd.name.replace(/\./g, ' ')} 查看用法。`;
+                return t('extraArgument', {
+                    token: positionalTokens[0],
+                    prefix: this.prefix,
+                    command: cmd.name.replace(/\./g, ' '),
+                });
             }
             const positionals = [];
             let cursor = 0;
@@ -544,7 +622,7 @@ export class CommandRegistry {
                 const values = def.type === 'text' ? positionalTokens.slice(cursor) : positionalTokens.slice(cursor, cursor + 1);
                 if (values.length === 0) {
                     if (def.required)
-                        return `缺少必填参数: ${def.name}`;
+                        return t('missingArgument', { name: def.name });
                     positionals.push(undefined);
                     continue;
                 }
@@ -554,8 +632,8 @@ export class CommandRegistry {
             return { positionals, options };
         }
         catch (err) {
-            // 取值解析错误（数字非法 / choices 越界）→ 返回可读错误串，而非抛出冒泡到命令管道。
-            return err instanceof Error ? err.message : String(err);
+            // 取值解析错误（数字非法 / choices 越界）→ 返回给人看的报错，而非抛出冒泡到命令管道。
+            return textOf(err);
         }
     }
     defaultOptions(opts) {
@@ -569,9 +647,24 @@ export class CommandRegistry {
 // ============================================================================
 // 工具函数
 // ============================================================================
+/** 写了 -h 或 --help（`--` 之后的是位置参数，不算）：要看用法，别的参数一概不管 */
+function asksHelp(tokens) {
+    const end = tokens.indexOf('--');
+    return (end < 0 ? tokens : tokens.slice(0, end)).some(t => t === '-h' || t === '--help');
+}
+/**
+ * 没有权限插件时执行不了的指令：要比默认等级高，或要人确认。没有守卫时 fail-closed，口径与 plugin-tools 相同：
+ * 等同人人都是默认等级、没人能确认
+ */
+function needsAuthority(cmd) {
+    return (cmd.confirm !== undefined || capabilityMinLevel({ risk: cmd.risk, visibility: cmd.visibility }) > DEFAULT_AUTHORITY);
+}
+/** 按空白拆参数：引号里的整段是一个参数（空的引号是一个空参数），反斜杠转义下一个字符 */
 function tokenize(input) {
     const tokens = [];
     let current = '';
+    /** 这个参数写过引号：空的也算一个 */
+    let quoted = false;
     let quote;
     let escaped = false;
     for (const ch of input) {
@@ -593,18 +686,20 @@ function tokenize(input) {
         }
         if (ch === '"' || ch === "'") {
             quote = ch;
+            quoted = true;
             continue;
         }
         if (/\s/.test(ch)) {
-            if (current) {
+            if (current || quoted) {
                 tokens.push(current);
                 current = '';
+                quoted = false;
             }
             continue;
         }
         current += ch;
     }
-    if (current)
+    if (current || quoted)
         tokens.push(current);
     return tokens;
 }
@@ -691,6 +786,9 @@ function parseOptionSyntax(name, syntax, opts) {
             }
         }
     }
+    if (name === 'help' || name === 'h' || aliases.includes('h') || aliases.includes('help')) {
+        throw new Error(`-h 与 --help 是保留选项（回这条指令的用法），选项 ${name} 不能占用`);
+    }
     return {
         name,
         aliases,
@@ -700,9 +798,16 @@ function parseOptionSyntax(name, syntax, opts) {
         description: opts?.description,
         default: opts?.default,
         required: opts?.required === true,
-        choices: opts?.choices,
+        choices: choicesOf(opts?.choices),
     };
 }
+/** 登记写的取值收成每次现取的函数，只写值的一项补成 { value } */
+function choicesOf(choices) {
+    if (!choices)
+        return undefined;
+    const list = typeof choices === 'function' ? choices : () => choices;
+    return () => list().map(c => (typeof c === 'string' ? { value: c } : c));
+}
 function findOption(defs, nameOrAlias) {
     return defs.find(o => o.name === nameOrAlias || o.aliases.includes(nameOrAlias));
 }
@@ -714,7 +819,7 @@ function parseOptionValue(def, rawValue, previous) {
     if (def.type === 'number') {
         const n = Number(rawValue);
         if (Number.isNaN(n))
-            throw new Error(`选项 --${def.name} 需要数字，收到「${rawValue}」`);
+            throw new TextError(t('optionNumber', { option: `--${def.name}`, value: rawValue }));
         return n;
     }
     if (def.type === 'boolean')
@@ -730,8 +835,9 @@ function parseOptionValue(def, rawValue, previous) {
         ];
     }
     // string
-    if (def.choices && !def.choices.includes(rawValue)) {
-        throw new Error(`选项 --${def.name} 只能是: ${def.choices.join(', ')}`);
+    const choices = def.choices?.();
+    if (choices && !choices.some(c => c.value === rawValue)) {
+        throw new TextError(t('optionChoices', { option: `--${def.name}`, choices: choices.map(c => c.value).join(', ') }));
     }
     return rawValue;
 }
@@ -740,7 +846,7 @@ function parsePositionalValue(def, values) {
     if (def.type === 'number') {
         const n = Number(raw);
         if (Number.isNaN(n))
-            throw new Error(`参数 ${def.name} 需要数字，收到「${raw}」`);
+            throw new TextError(t('argumentNumber', { name: def.name, value: raw }));
         return n;
     }
     if (def.type === 'boolean')