@zhin.js/command 1.1.17 → 1.2.0

package/README.md

@@ -16,7 +16,7 @@ import { defineCommand } from 'zhin.js/command';
 export default defineCommand({
   description: 'List GitHub issues',
   alias: ['issues'],                 // 可多词；owner 不参与用户路由
-  permit: ['adapter(icqq)', 'role(master)'], // 数组 AND；失败返回 denied
+  permit: ['adapter(icqq)', 'owner'], // 数组 AND；失败返回 denied
   // shortcut: { '列 issue': {} },   // 全局整句
   execute: ({ args }) => `issues:${args.join(',')}`,
 });
@@ -154,7 +154,7 @@ parent 和 thread 独立计算。没有完整可信身份或真实 IM operation
 新策略的并发数用于新准入，原来已开始的冷却保留到原到期时间。移除策略即停止新请求的预算检查。
 状态只保留在当前进程，进程重启后重置；容量满时拒绝新身份，不驱逐活跃或仍在冷却的记录。
 
-进度默认关闭，只在业务等待阶段发送一次“正在处理中，请稍候。”，走当前平台统一发送链路。
+进度默认关闭，只在业务等待阶段发送一次“正在处理中，请稍候。”（按当前操作的语言本地化），走当前平台统一发送链路。
 开始自动最终回复前停止尚未开始的提示，并等待已开始的提示完成；已开始的 I/O 随原 lease 排空。
 执行内显式 `$reply()` 不会停止进度计时。提示失败不重试，也不表示任务取消或远端已经展示。
 `@zhin.js/command/internal/execution` 是 Core 装配使用的内部入口，不是插件创作 API。
@@ -173,7 +173,7 @@ pnpm --filter @zhin.js/command test
 ```
 
 完整用户契约见[命令创作指南](../../../docs/authoring/commands.md)，架构迁移背景见
-[Plugin Runtime 原位迁移](../../../docs/architecture/target-implementation/in-place-migration.md)。
+[Legacy 概念迁移](../../../docs/contributing/legacy-concepts.md)。
 
 
 命令可声明 `descriptionI18n: { en: 'Create a reminder' }` 翻译描述。若静态目录名是中文，可沿用 `alias` 提供英文入口，并用 `preferredAliasI18n` 显式选择英文展示：

package/lib/command-index.d.ts

@@ -46,6 +46,14 @@ export interface CommandDispatchResult {
     readonly owner?: PluginId;
     readonly value?: unknown;
     readonly menu?: CommandMenuPage;
+    /**
+     * `denied` only: the first unmet permit and a one-sentence reason for the sender (e.g. 「机器人不是本群管理员」).
+     * Undefined when no Permission host / source answered.
+     */
+    readonly denial?: Readonly<{
+        permit: string;
+        reason: string;
+    }>;
 }
 /** Semantic menu navigation; the IM composition layer supplies platform controls. */
 export interface CommandMenuNavigation {

package/lib/command-index.js

@@ -1,7 +1,7 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
 import { htmlRendererToken, resolveLocale, } from '@zhin.js/plugin-runtime';
 import { bindOperationInput } from '@zhin.js/feature-kit';
-import { permissionHostToken, } from '@zhin.js/permission';
+import { describeDeniedPermit, permissionHostToken, } from '@zhin.js/permission';
 import { commandAdapterMatches, toCommandPermissionSubject } from './permission-explanation.js';
 import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp, commandValidationIssue } from './arguments.js';
 import { commandDescription, commandMessages } from './messages.js';
@@ -175,7 +175,7 @@ export class CommandIndex {
             this.#diagnoseParameter(name);
             throw new Error(`Unknown Command: ${name}`);
         }
-        if (!(await this.#permitAllows(match.command, undefined, operationSnapshot)))
+        if ((await this.#permitDenial(match.command, undefined, operationSnapshot)) !== undefined)
             throw new Error(`Permission denied for Command: ${match.command.name}`);
         const definition = match.command.slot.definition;
         const supplied = [...match.remaining, ...(args.length > 0 ? [{ type: 'text', data: { text: args.join(' ') } }] : [])];
@@ -201,7 +201,7 @@ export class CommandIndex {
         const prefix = commandPrefix ?? '';
         if (this.#menu) {
             const keyword = this.#menu.keyword ?? commandMessages(locale, 'menuKeyword');
-            const menuResult = this.#dispatchMenu(input, { commandPrefix: prefix, snapshot: operationSnapshot, locale, keyword });
+            const menuResult = await this.#dispatchMenu(input, { commandPrefix: prefix, snapshot: operationSnapshot, locale, keyword, source });
             if (menuResult !== undefined) {
                 return Object.freeze({
                     matched: true,
@@ -222,8 +222,9 @@ export class CommandIndex {
                 return Object.freeze({ matched: false, status: 'unmatched' });
             if (!commandAdapterMatches(candidate, source))
                 return Object.freeze({ matched: false, status: 'unmatched' });
-            if (!(await this.#permitAllows(candidate, source, operationSnapshot)))
-                return this.#denied(candidate);
+            const candidateDenial = await this.#permitDenial(candidate, source, operationSnapshot);
+            if (candidateDenial !== undefined)
+                return this.#denied(candidate, candidateDenial, locale);
             const help = commandHelp(commandDisplayName(candidate, locale), candidate.slot.definition, prefix, locale);
             const segments = normalizeSegments(typeof input === 'string' ? [{ type: 'text', data: { text: input } }] : input);
             if (requestsCommandHelp(segments))
@@ -233,8 +234,9 @@ export class CommandIndex {
         }
         if (!commandAdapterMatches(match.command, source))
             return Object.freeze({ matched: false, status: 'unmatched' });
-        if (!(await this.#permitAllows(match.command, source, operationSnapshot)))
-            return this.#denied(match.command);
+        const denial = await this.#permitDenial(match.command, source, operationSnapshot);
+        if (denial !== undefined)
+            return this.#denied(match.command, denial, locale);
         const definition = match.command.slot.definition;
         const authorSource = bindOperationInput(source, match.command.slot.owner, operationSnapshot);
         const help = commandHelp(commandDisplayName(match.command, locale), definition, prefix, locale);
@@ -265,34 +267,60 @@ export class CommandIndex {
             catch { /* Cleanup never replaces the command's actual outcome. */ }
         }
     }
-    #denied(record) {
-        return Object.freeze({ matched: true, status: 'denied', command: record.name, owner: record.slot.owner });
+    #denied(record, permit, locale) {
+        return Object.freeze({ matched: true, status: 'denied', command: record.name, owner: record.slot.owner,
+            ...(permit ? { denial: Object.freeze({ permit, reason: describeDeniedPermit(permit, locale) }) } : {}) });
     }
     /** Diagnose only a reliable static route prefix; fully dynamic routes are ordinary chat candidates. */
     #invalidRoute(input) {
         const segments = normalizeSegments(typeof input === 'string' ? [{ type: 'text', data: { text: input } }] : input);
+        // segment-matcher clones its input before matching, so one copy serves every route.
+        const matcherSegments = asMatcherSegments(segments);
         for (const route of this.#routes) {
             if (!route.record.parameter)
                 continue;
-            const result = route.literalMatcher?.match(asMatcherSegments(segments));
+            const result = route.literalMatcher?.match(matcherSegments);
             if (result && hasCommandBoundary(result.remaining))
                 return route.record;
         }
         return undefined;
     }
-    async #permitAllows(record, source, operationSnapshot) {
+    /**
+     * ADR 0056 §5: the shared evaluator (PermissionHost) over the three dimensions — sender zhin role,
+     * sender platform standing and the Bot's own standing (resolved from the Adapter index cache).
+     * `undefined` = allowed; a permit string = the first unmet one; `null` = denied without a reason
+     * (no source or no Permission host).
+     */
+    async #permitDenial(record, source, operationSnapshot, cachedOnly = false) {
         const permits = record.permit;
         if (!permits || permits.length === 0)
-            return true;
+            return undefined;
         if (!source || typeof source !== 'object')
-            return false;
+            return null;
         const host = this.#resolveHost(operationSnapshot);
         if (!host)
-            return false;
+            return null;
         const subject = toCommandPermissionSubject(source);
         if (!subject.sender?.id && !subject.scene?.id && !subject.adapter && !subject.endpoint)
+            return null;
+        const options = { source, ...(cachedOnly ? { cachedOnly } : {}) };
+        if (await host.checkAll(permits, subject, options))
+            return undefined;
+        // Denied: name the first unmet permit for the reply (same evaluator; Bot standing is cached now).
+        try {
+            return (await host.firstDenied?.(permits, subject, options)) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Whether the menu should list `record` for `source` (adapter restriction + permits). */
+    async #listable(record, source, operationSnapshot) {
+        if (source === undefined)
+            return true;
+        if (!commandAdapterMatches(record, source))
             return false;
-        return host.checkAll(permits, subject);
+        return (await this.#permitDenial(record, source, operationSnapshot)) === undefined;
     }
     #resolveHost(operationSnapshot) {
         try {
@@ -322,14 +350,16 @@ export class CommandIndex {
             : input);
         if (segments.length === 0)
             return undefined;
+        // segment-matcher clones its input before matching, so one copy serves every route.
+        const matcherSegments = asMatcherSegments(segments);
         for (const route of this.#routes) {
             // Options may appear between the literal route and a directory-bound parameter.
-            const literalResult = !exact ? route.literalMatcher?.match(asMatcherSegments(segments)) : undefined;
+            const literalResult = !exact ? route.literalMatcher?.match(matcherSegments) : undefined;
             const helpRequested = literalResult && hasCommandBoundary(literalResult.remaining)
                 && requestsCommandHelp(normalizeSegments(literalResult.remaining));
             const parseDeclaredArguments = !exact && route.record.parameter && route.literalMatcher !== undefined
                 && (Object.hasOwn(route.record.slot.definition.params ?? {}, route.record.parameter.name) || helpRequested);
-            const result = parseDeclaredArguments ? literalResult : route.matcher.match(asMatcherSegments(segments));
+            const result = parseDeclaredArguments ? literalResult : route.matcher.match(matcherSegments);
             if (!result || !hasCommandBoundary(result.remaining))
                 continue;
             const parameter = route.record.parameter;
@@ -380,7 +410,7 @@ export class CommandIndex {
     // ==========================================================================
     // 内置菜单命令
     // ==========================================================================
-    #dispatchMenu(input, context) {
+    async #dispatchMenu(input, context) {
         const { commandPrefix, keyword, locale } = context;
         const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
         if (text === undefined)
@@ -414,7 +444,7 @@ export class CommandIndex {
         }
         return undefined;
     }
-    #buildMenu({ pluginKey, page = 1 }, { commandPrefix, keyword, snapshot, locale }) {
+    async #buildMenu({ pluginKey, page = 1 }, { commandPrefix, keyword, snapshot, locale, source }) {
         const root = snapshot.root;
         const targetId = pluginKey
             ? `${root}/${pluginKey.split('.').join('/')}`
@@ -422,15 +452,17 @@ export class CommandIndex {
         const node = snapshot.tree.get(targetId);
         if (!node)
             return { value: commandMessages(locale, 'missingPlugin', { plugin: pluginKey ?? '' }) };
-        const directCommands = this.#commands.filter((cmd) => cmd.slot.owner === targetId);
+        const listable = await Promise.all(this.#commands.map(async (cmd) => (await this.#listable(cmd, source, snapshot)) ? cmd : undefined));
+        const available = listable.filter((cmd) => cmd !== undefined);
+        const directCommands = available.filter((cmd) => cmd.slot.owner === targetId);
         const children = node.children
             .map((childId) => snapshot.tree.get(childId))
             .filter((child) => !!child);
         const effectiveCommands = targetId === root
             && directCommands.length === 0
-            && this.#commands.length > 0
-            && this.#commands.length <= MENU_PAGE_SIZE
-            ? this.#commands
+            && available.length > 0
+            && available.length <= MENU_PAGE_SIZE
+            ? available
             : directCommands;
         const pages = Math.max(1, Math.ceil((effectiveCommands.length + children.length) / MENU_PAGE_SIZE));
         const invocation = `${commandPrefix}${keyword}${pluginKey ? ` ${pluginKey}` : ''}`;

package/lib/definition.d.ts

@@ -112,7 +112,19 @@ export interface CommandScene {
 export interface CommandSender {
     readonly id: string;
     readonly name?: string;
-    readonly role: readonly string[];
+    /** Highest zhin chat role effective in this conversation (ADR 0056), set by the Runtime. */
+    readonly chatRole?: 'owner' | 'admin' | 'trusted';
+    /** Per role, the topmost level it is held at on this conversation's chain, set by the Runtime. */
+    readonly chatRoleLevels?: Readonly<Partial<Record<'owner' | 'admin' | 'trusted', 'global' | 'adapter' | 'endpoint' | 'conversation'>>>;
+    /** Normalized platform standing; absent in private chats. */
+    readonly platform?: Readonly<{
+        standing: 'owner' | 'admin' | 'member' | 'guest';
+        roles?: readonly Readonly<{
+            id: string;
+            name?: string;
+        }>[];
+        permissions?: readonly string[];
+    }>;
 }
 /**
  * 命令侧入站会话契约（结构对齐 `@zhin.js/im-contract` 的 ConversationRef；
@@ -147,7 +159,9 @@ export interface CommandMessage {
     readonly sender?: {
         readonly id: string;
         readonly name?: string;
-        readonly roles?: readonly string[];
+        readonly chatRole?: CommandSender['chatRole'];
+        readonly chatRoleLevels?: CommandSender['chatRoleLevels'];
+        readonly platform?: CommandSender['platform'];
     };
     readonly id?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -265,7 +279,7 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
     readonly preferredAliasI18n?: Readonly<Partial<Record<Locale, string>>>;
     /**
      * 内置 permit DSL（AND）。单项内逗号为 OR。
-     * 例：`adapter(icqq)`、`role(master)`、`group(123,456)`。
+     * 例：`adapter(icqq)`、`owner`、`trusted`、`platform:admin`、`group(123,456)`。
      */
     readonly permit?: readonly string[];
     /** Optional full-operation cooldown, concurrency and one-shot progress feedback. */

package/lib/definition.js

@@ -213,14 +213,12 @@ export function resolveCommandSession(input) {
     if (operation) {
         const endpoint = input && typeof input === 'object' ? input.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']) }) } : {}),
+            ...(sender ? { sender: freezeSender(sender) } : {}),
         });
     }
     if (!isCommandMessageLike(input))
@@ -281,38 +279,8 @@ export function resolveCommandSender(input, metadata) {
     if (!id)
         return undefined;
     const name = input.sender?.name || firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
-    const role = resolveRoles(input, metadata);
-    return Object.freeze({
-        id,
-        ...(name !== undefined ? { name } : {}),
-        role,
-    });
-}
-function resolveRoles(input, metadata) {
-    if (input.sender?.roles?.length) {
-        return Object.freeze([...input.sender.roles]);
-    }
-    const roles = [];
-    const push = (value) => {
-        if (typeof value !== 'string')
-            return;
-        const trimmed = value.trim();
-        if (trimmed && !roles.includes(trimmed))
-            roles.push(trimmed);
-    };
-    if (Array.isArray(metadata?.roles)) {
-        for (const item of metadata.roles)
-            push(item);
-    }
-    push(metadata?.senderRole);
-    push(metadata?.role);
-    if (metadata?.isMaster === true)
-        push('master');
-    if (metadata?.isTrusted === true)
-        push('trusted');
-    if (roles.length === 0)
-        roles.push('user');
-    return Object.freeze(roles);
+    // Roles come only from the Runtime-set sender fields, never from metadata (ADR 0056).
+    return freezeSender({ ...(input.sender ?? {}), id, ...(name !== undefined ? { name } : {}) });
 }
 function isCommandScene(value) {
     if (!value || typeof value !== 'object')
@@ -329,14 +297,31 @@ function isCommandSender(value) {
     const sender = value;
     return typeof sender.id === 'string'
         && sender.id.length > 0
-        && Array.isArray(sender.role)
-        && sender.role.every((item) => typeof item === 'string');
+        && (sender.chatRole === undefined || isChatRoleName(sender.chatRole));
+}
+function isChatRoleName(value) {
+    return value === 'owner' || value === 'admin' || value === 'trusted';
+}
+const STANDINGS = new Set(['owner', 'admin', 'member', 'guest']);
+const LEVELS = new Set(['global', 'adapter', 'endpoint', 'conversation']);
+function chatRoleLevelsOf(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const levels = Object.fromEntries(['owner', 'admin', 'trusted']
+        .filter(role => LEVELS.has(String(value[role])))
+        .map(role => [role, value[role]]));
+    return Object.keys(levels).length ? Object.freeze(levels) : undefined;
 }
 function freezeSender(sender) {
+    const platform = sender.platform && typeof sender.platform === 'object'
+        && STANDINGS.has(String(sender.platform.standing))
+        ? sender.platform : undefined;
     return Object.freeze({
         id: sender.id,
         ...(sender.name !== undefined ? { name: sender.name } : {}),
-        role: Object.freeze([...sender.role]),
+        ...(isChatRoleName(sender.chatRole) ? { chatRole: sender.chatRole } : {}),
+        ...(isChatRoleName(sender.chatRole) && chatRoleLevelsOf(sender.chatRoleLevels) ? { chatRoleLevels: chatRoleLevelsOf(sender.chatRoleLevels) } : {}),
+        ...(platform ? { platform } : {}),
     });
 }
 function firstString(...values) {

package/lib/execution-runtime.d.ts

@@ -1,5 +1,5 @@
 /** Internal composition contract. Not part of the command authoring facade. */
-import { type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { CommandExecutionLimit, CommandExecutionPolicy } from './execution-policy.js';
 interface ConversationIdentity {
     readonly endpoint: {
@@ -55,6 +55,8 @@ export declare class CommandExecutionBudget {
         readonly conversation: ConversationIdentity;
         readonly senderId?: string;
         readonly retirementSignal: AbortSignal;
+        /** The operation's language for progress feedback; defaults to the catalog default. */
+        readonly locale?: Locale;
         readonly reply: (owner: PluginId, text: string) => Promise<unknown>;
     }): CommandOperationController;
 }

package/lib/execution-runtime.js

@@ -1,5 +1,6 @@
 /** Internal composition contract. Not part of the command authoring facade. */
 import { createToken } from '@zhin.js/plugin-runtime';
+import { commandMessages } from './messages.js';
 /** @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. */
@@ -26,7 +27,7 @@ export class CommandExecutionBudget {
         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(),
+            locale: input.locale, reply: input.reply, releases: [], timers: new Set(), feedback: [], accepted: new Set(), sends: new Set(),
         };
         const stop = () => {
             operation.progressStopped = true;
@@ -136,7 +137,7 @@ export class CommandExecutionBudget {
                 // Observe failure once. Never retry uncertain delivery and never expose the exception.
                 let send;
                 try {
-                    send = Promise.resolve(operation.reply(owner, '正在处理中，请稍候。')).then(() => { }, () => { });
+                    send = Promise.resolve(operation.reply(owner, commandMessages(operation.locale, 'progress'))).then(() => { }, () => { });
                 }
                 catch {
                     send = Promise.resolve();

package/lib/index.d.ts

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

package/lib/index.js

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

package/lib/messages.d.ts

@@ -5,4 +5,4 @@ export declare function commandDescription(value: Readonly<{
     descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
 }>, locale: Locale): string | undefined;
 /** Static dictionaries; the caller supplies the operation's language. */
-export declare const commandMessages: (locale: Locale | undefined, key: "choices" | "defaultValue" | "menuKeyword" | "invalidPage" | "missingPlugin" | "pageOutOfRange" | "menuTitle" | "menuSummary" | "childPlugins" | "emptyMenu" | "pluginHint" | "previousPage" | "nextPage" | "guideTitle" | "guideSubtitle" | "commandCount" | "pluginCount" | "commandIndex" | "pluginIndex" | "guideEmpty" | "helpHint" | "genericHelpHint" | "expectedType" | "expectedArray" | "minimum" | "maximum" | "invalidFormat" | "invalidValue" | "unknownOption" | "duplicateOption" | "defaultUndefined" | "parameterUndefined" | "missingOption" | "missingRequiredParam" | "unexpectedArguments" | "invalidParameter" | "dynamicValue" | "noAdapter" | "missingEndpoint" | "adapterComparison" | "conditionMismatch" | "missingPermissionHost" | "missingEvidence" | "noPermit" | "uncheckedConditions" | "conditionsMatch" | "unconstrained" | "simulatedIdentity" | "unevaluatedCode" | "defaultedRole", values?: import("@zhin.js/plugin-runtime").MessageValues) => string;
+export declare const commandMessages: (locale: Locale | undefined, key: "choices" | "defaultValue" | "menuKeyword" | "progress" | "invalidPage" | "missingPlugin" | "pageOutOfRange" | "menuTitle" | "menuSummary" | "childPlugins" | "emptyMenu" | "pluginHint" | "previousPage" | "nextPage" | "guideTitle" | "guideSubtitle" | "commandCount" | "pluginCount" | "commandIndex" | "pluginIndex" | "guideEmpty" | "helpHint" | "genericHelpHint" | "expectedType" | "expectedArray" | "minimum" | "maximum" | "invalidFormat" | "invalidValue" | "unknownOption" | "duplicateOption" | "defaultUndefined" | "parameterUndefined" | "missingOption" | "missingRequiredParam" | "unexpectedArguments" | "invalidParameter" | "dynamicValue" | "noAdapter" | "missingEndpoint" | "adapterComparison" | "conditionMismatch" | "missingPermissionHost" | "missingEvidence" | "noPermit" | "uncheckedConditions" | "conditionsMatch" | "unconstrained" | "simulatedIdentity" | "unevaluatedCode" | "defaultedRole", values?: import("@zhin.js/plugin-runtime").MessageValues) => string;

package/lib/messages.js

@@ -6,6 +6,7 @@ export function commandDescription(value, locale) {
 /** Static dictionaries; the caller supplies the operation's language. */
 export const commandMessages = createMessages({
     menuKeyword: { 'zh-CN': '菜单', en: 'menu' },
+    progress: { 'zh-CN': '正在处理中，请稍候。', en: 'Working on it, please wait.' },
     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>.' },
@@ -54,5 +55,5 @@ export const commandMessages = createMessages({
     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' },
+    defaultedRole: { 'zh-CN': '输入未附聊天角色时按普通用户（无 owner / admin / trusted）解释；这不是已核验的角色', en: 'Input without a chat role is treated as an ordinary user (no owner / admin / trusted); this is not a verified role' },
 });

package/lib/permission-explanation.js

@@ -20,14 +20,13 @@ export function explainCommandPermissions(command, options) {
     const inputSender = options.source && typeof options.source === 'object'
         ? options.source.sender : undefined;
     const structuredRoles = inputSender && typeof inputSender === 'object'
-        && Array.isArray(inputSender.role);
+        && 'chatRole' in inputSender;
     // 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 defaultedRoles = options.rolesKnown === true && !!subject.sender && subject.sender.chatRole === undefined;
     const actualAdapter = operationClientAdapter(options.source);
     const adapter = !command.adapter
         ? { outcome: 'not_evaluated', reason: commandMessages(locale, 'noAdapter') }

package/lib/permit.d.ts

@@ -3,11 +3,14 @@
  * 保留 CommandSession 兼容签名供 command-index 过渡使用。
  */
 import { type PermissionSubject } from '@zhin.js/permission';
-/** 会话管理者：群主 / 群管理员 / 机器人主人（适配器投影的规范角色名）。 */
-export declare const CONVERSATION_MANAGER_PERMIT = "role(owner,admin,master)";
 /**
- * 「私聊，或 owner / admin / master」。`permit` 列表只支持 AND，
- * 订阅类命令需要这个 OR 规则时用它，并以命令会话的 `scene` / `sender.role` 为输入。
+ * 会话管理者：本会话层级链上的 zhin 聊天角色 `admin`（含 `owner`）。平台群主 / 管理员不自动具备
+ * （ADR 0056 §4，2026-11-12 修订）：订阅等 zhin 功能需要被授予的角色。
+ */
+export declare const CONVERSATION_MANAGER_PERMIT = "admin";
+/**
+ * 「私聊，或本会话 admin」。`permit` 列表只支持 AND，
+ * 订阅类命令需要这个 OR 规则时用它，并以命令会话的 `scene` / `sender.chatRole` 为输入。
  */
 export declare function canManageConversation(subject: PermissionSubject): boolean;
-export { type PermitKind, type ParsedPermit, parsePermitName, isBuiltinPermit, isPlatformPermit, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';
+export { type PermitKind, type ParsedPermit, parsePermitName, isBuiltinPermit, removedPermitReplacement, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';

package/lib/permit.js

@@ -3,14 +3,17 @@
  * 保留 CommandSession 兼容签名供 command-index 过渡使用。
  */
 import { checkBuiltinPermit } from '@zhin.js/permission';
-/** 会话管理者：群主 / 群管理员 / 机器人主人（适配器投影的规范角色名）。 */
-export const CONVERSATION_MANAGER_PERMIT = 'role(owner,admin,master)';
 /**
- * 「私聊，或 owner / admin / master」。`permit` 列表只支持 AND，
- * 订阅类命令需要这个 OR 规则时用它，并以命令会话的 `scene` / `sender.role` 为输入。
+ * 会话管理者：本会话层级链上的 zhin 聊天角色 `admin`（含 `owner`）。平台群主 / 管理员不自动具备
+ * （ADR 0056 §4，2026-11-12 修订）：订阅等 zhin 功能需要被授予的角色。
+ */
+export const CONVERSATION_MANAGER_PERMIT = 'admin';
+/**
+ * 「私聊，或本会话 admin」。`permit` 列表只支持 AND，
+ * 订阅类命令需要这个 OR 规则时用它，并以命令会话的 `scene` / `sender.chatRole` 为输入。
  */
 export function canManageConversation(subject) {
     return checkBuiltinPermit('private()', subject)
         || checkBuiltinPermit(CONVERSATION_MANAGER_PERMIT, subject);
 }
-export { parsePermitName, isBuiltinPermit, isPlatformPermit, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';
+export { parsePermitName, isBuiltinPermit, removedPermitReplacement, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.17",
+  "version": "1.2.0",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -16,15 +16,14 @@
     }
   },
   "files": [
-    "lib",
-    "src"
+    "lib"
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.1.15",
-    "@zhin.js/im-contract": "1.1.13",
-    "@zhin.js/permission": "1.1.15",
-    "@zhin.js/plugin-runtime": "1.1.23"
+    "@zhin.js/feature-kit": "1.1.16",
+    "@zhin.js/plugin-runtime": "1.2.0",
+    "@zhin.js/permission": "1.2.0",
+    "@zhin.js/im-contract": "1.1.14"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",