@zhin.js/command 1.0.7 → 1.0.9

package/README.md

@@ -3,14 +3,21 @@
 Zhin Plugin Runtime 的约定式 Command Feature。它发现 `commands/**/*.ts(x)`，将插件树
 路径与文件路径投影为命令，并用 `segment-matcher` 同时匹配纯文本和 canonical IM segments。
 
+静态命令文件名可为 ASCII kebab（`hello.ts`）或 Unicode 名（`赞我.ts`）；动态参数文件
+（`[name].ts` 等）仍限 ASCII。详见 [命令创作指南](../../../docs/authoring/commands.md)。
+
 ## Authoring
 
 ```ts
 // commands/gh/issue/list.ts -> gh issue list
+// commands/赞我.ts -> 赞我
 import { defineCommand } from '@zhin.js/command';
 
 export default defineCommand({
   description: 'List GitHub issues',
+  alias: ['issues'],                 // 可多词；子插件仍保留 owner 前缀
+  permit: ['adapter(icqq)', 'role(master)'], // 数组 AND；未过则静默未命中
+  // shortcut: { '列 issue': {} },   // 全局整句，可打破命名空间
   execute: ({ args }) => `issues:${args.join(',')}`,
 });
 ```
@@ -38,6 +45,12 @@ commands/search/[...kw].ts    -> search <...kw>   （params: { kw: { type: 'text
 - `scene`：`{ id, type, name? }` 场景对象。
 - `sender`：`{ id, name?, role: string[] }` 发送者对象。
 
+可选声明字段：
+
+- `alias`：替换全部本地静态段并重挂 owner 前缀（不打破子插件命名空间）。
+- `permit`：内置 DSL（`adapter|group|private|channel|user|role`）；失败为静默未命中。
+- `shortcut`：全局整句精确匹配 → 预填 `params`（可打破命名空间）。
+
 单文件插件可在 `setup({ addCommand })` 中调用
 `addCommand('hello', defineCommand(...))`。它与目录发现共用 CommandIndex；拆成文件后
 可获得单命令 HMR。

package/lib/command-index.d.ts

@@ -8,6 +8,10 @@ export interface CommandDescriptor {
     readonly description?: string;
     readonly source: string;
     readonly parameters: readonly CommandParameterDescriptor[];
+    readonly alias?: readonly string[];
+    readonly permit?: readonly string[];
+    /** shortcut 触发键列表（不含预填 params）。 */
+    readonly shortcut?: readonly string[];
 }
 export interface CommandDispatchResult {
     readonly matched: boolean;

package/lib/command-index.js

@@ -1,5 +1,7 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
-import { createCommandContext, } from './definition.js';
+import { createCommandContext, resolveCommandSession, } from './definition.js';
+import { permissionHostToken } from '@zhin.js/permission';
+import { toPermissionSubject } from '@zhin.js/permission';
 const segmentFields = {
     text: 'text',
     mention: 'target',
@@ -15,16 +17,33 @@ export class CommandIndex {
     snapshot;
     $projection = 'zhin.command-index/1';
     #commands;
+    #routes;
+    #shortcuts;
     constructor(slots, snapshot) {
         this.snapshot = snapshot;
         const commands = [];
-        const staticCommands = new Map();
-        const dynamicCommands = new Map();
+        const routes = [];
+        const occupancy = new Map();
+        const shortcuts = new Map();
+        const claim = (key, source) => {
+            const existing = occupancy.get(key);
+            if (existing !== undefined) {
+                throw new Error(`Duplicate Command route "${key}" (${source} vs ${existing})`);
+            }
+            occupancy.set(key, source);
+        };
         for (const slot of slots) {
-            const segments = runtimeSegments(slot.owner, slot.localName);
+            const primarySegments = runtimeSegments(slot.owner, slot.localName);
             const parameter = slot.definition.$parameter;
-            assertParameterSegment(segments, parameter, slot.source);
-            const name = displayName(segments, parameter);
+            assertParameterSegment(primarySegments, parameter, slot.source);
+            const name = displayName(primarySegments, parameter);
+            const alias = normalizeAliasList(slot.definition.alias);
+            const permit = slot.definition.permit
+                ? Object.freeze([...slot.definition.permit])
+                : undefined;
+            const shortcutKeys = slot.definition.shortcut
+                ? Object.freeze(Object.keys(slot.definition.shortcut).map((key) => key.trim()))
+                : undefined;
             const record = Object.freeze({
                 name,
                 description: slot.definition.description,
@@ -33,26 +52,48 @@ export class CommandIndex {
                         ...parameter,
                         required: isRequiredParameter(parameter),
                     }] : []),
+                ...(alias ? { alias } : {}),
+                ...(permit ? { permit } : {}),
+                ...(shortcutKeys && shortcutKeys.length > 0 ? { shortcut: shortcutKeys } : {}),
                 slot,
-                segments: Object.freeze(segments),
+                segments: Object.freeze(primarySegments),
                 parameter,
-                matcher: new SegmentMatcher(matcherPattern(segments, parameter), segmentFields),
             });
-            if (!parameter) {
-                const key = segments.join(' ');
-                if (staticCommands.has(key))
-                    throw duplicateCommand(key);
-                staticCommands.set(key, record);
+            claim(occupancyKey(primarySegments, parameter), slot.source);
+            routes.push({
+                record,
+                segments: primarySegments,
+                matcher: new SegmentMatcher(matcherPattern(primarySegments, parameter), segmentFields),
+                kind: 'primary',
+            });
+            if (alias) {
+                for (const entry of alias) {
+                    const aliasSegments = aliasRuntimeSegments(slot.owner, entry, primarySegments);
+                    assertParameterSegment(aliasSegments, parameter, `${slot.source} alias ${JSON.stringify(entry)}`);
+                    claim(occupancyKey(aliasSegments, parameter), `${slot.source} alias ${JSON.stringify(entry)}`);
+                    routes.push({
+                        record,
+                        segments: Object.freeze(aliasSegments),
+                        matcher: new SegmentMatcher(matcherPattern(aliasSegments, parameter), segmentFields),
+                        kind: 'alias',
+                    });
+                }
             }
-            else {
-                const shape = routeShape(segments);
-                if (dynamicCommands.has(shape))
-                    throw duplicateCommand(name);
-                dynamicCommands.set(shape, record);
+            if (slot.definition.shortcut) {
+                for (const [rawTrigger, prefill] of Object.entries(slot.definition.shortcut)) {
+                    const trigger = rawTrigger.trim();
+                    claim(trigger, `${slot.source} shortcut ${JSON.stringify(trigger)}`);
+                    shortcuts.set(trigger, {
+                        record,
+                        params: Object.freeze(resolveShortcutParams(slot.definition, prefill, `${slot.source} shortcut ${JSON.stringify(trigger)}`)),
+                    });
+                }
             }
             commands.push(record);
         }
-        this.#commands = Object.freeze(commands.sort(compareCommands));
+        this.#commands = Object.freeze(commands.sort(compareRecords));
+        this.#routes = Object.freeze(routes.sort(compareRoutes));
+        this.#shortcuts = shortcuts;
     }
     list() {
         return this.#commands.map(toDescriptor);
@@ -73,12 +114,29 @@ export class CommandIndex {
             this.#diagnoseParameter(name);
             throw new Error(`Unknown Command: ${name}`);
         }
+        // Host / 无 session：跳过 permit。
         return match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params));
     }
     async dispatch(input, source = undefined) {
+        const shortcut = this.#matchShortcut(input);
+        if (shortcut) {
+            if (!(await this.#permitAllows(shortcut.record, source))) {
+                return Object.freeze({ matched: false });
+            }
+            const value = await shortcut.record.slot.definition.execute(createCommandContext(this.snapshot, shortcut.record.slot.owner, Object.freeze([]), shortcut.params, source, Object.freeze([])));
+            return Object.freeze({
+                matched: true,
+                command: shortcut.record.name,
+                owner: shortcut.record.slot.owner,
+                value,
+            });
+        }
         const match = this.#match(input, false);
         if (!match)
             return Object.freeze({ matched: false });
+        if (!(await this.#permitAllows(match.command, source))) {
+            return Object.freeze({ matched: false });
+        }
         const args = textArgs(match.remaining);
         const value = await match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params, source, match.remaining));
         return Object.freeze({
@@ -88,6 +146,38 @@ export class CommandIndex {
             value,
         });
     }
+    async #permitAllows(record, source) {
+        const permits = record.permit;
+        if (!permits || permits.length === 0)
+            return true;
+        if (!hasImSession(source))
+            return true;
+        const host = this.#resolveHost();
+        if (!host)
+            return false;
+        const subject = toPermissionSubject(resolveCommandSession(source));
+        return host.checkAll(permits, subject);
+    }
+    #resolveHost() {
+        try {
+            const resources = this.snapshot.resources.get(this.snapshot.root);
+            if (!resources)
+                return undefined;
+            const host = resources.get(permissionHostToken.id);
+            return host && typeof host.check === 'function'
+                ? host
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #matchShortcut(input) {
+        const text = exactMessageText(input);
+        if (text === undefined)
+            return undefined;
+        return this.#shortcuts.get(text);
+    }
     #match(input, exact) {
         const segments = normalizeSegments(typeof input === 'string'
             ? input.trim()
@@ -96,16 +186,15 @@ export class CommandIndex {
             : input);
         if (segments.length === 0)
             return undefined;
-        for (const command of this.#commands) {
-            const result = command.matcher.match(asMatcherSegments(segments));
+        for (const route of this.#routes) {
+            const result = route.matcher.match(asMatcherSegments(segments));
             if (!result || !hasCommandBoundary(result.remaining))
                 continue;
-            const parameter = command.parameter;
+            const parameter = route.record.parameter;
             const params = { ...result.params };
             if (parameter?.rest) {
                 const raw = result.params[parameter.name];
                 const coerced = coerceRestValues(parameter, Array.isArray(raw) ? raw : []);
-                // 必需 `[...name]` 捕获所有：零元素视为不匹配；标量逐词转换失败同样不匹配。
                 if (!coerced || (isRequiredParameter(parameter) && coerced.length === 0))
                     continue;
                 params[parameter.name] = coerced;
@@ -113,15 +202,13 @@ export class CommandIndex {
             const remaining = normalizeSegments(result.remaining);
             if (exact && remaining.length > 0)
                 continue;
-            // `[[name]]` 无 default 且未命中时，matcher 对 text 回退 ''、其他类型回退 null；
-            // 按契约（省略 default 时未匹配为 undefined）删除该键。
             if (parameter && !parameter.rest && parameter.optional === true
                 && parameter.defaultValue === undefined
                 && (params[parameter.name] === '' || params[parameter.name] === null)) {
                 delete params[parameter.name];
             }
             return {
-                command,
+                command: route.record,
                 params: Object.freeze(params),
                 remaining,
             };
@@ -130,14 +217,14 @@ export class CommandIndex {
     }
     #diagnoseParameter(name) {
         const words = splitCommand(name);
-        for (const command of this.#commands) {
-            const parameter = command.parameter;
+        for (const route of this.#routes) {
+            const parameter = route.record.parameter;
             if (!parameter || parameter.rest)
                 continue;
-            const parameterIndex = command.segments.findIndex((segment) => segment.startsWith('$'));
-            if (words.length !== command.segments.length)
+            const parameterIndex = route.segments.findIndex((segment) => segment.startsWith('$'));
+            if (words.length !== route.segments.length)
                 continue;
-            if (!command.segments.every((segment, index) => index === parameterIndex || segment === words[index]))
+            if (!route.segments.every((segment, index) => index === parameterIndex || segment === words[index]))
                 continue;
             const value = words[parameterIndex];
             if (value === undefined || matchesParameter(parameter.type, value))
@@ -163,6 +250,82 @@ function runtimeSegments(owner, localName) {
     const prefix = owner.slice('root/'.length).split('/').join('.');
     return [`${prefix}.${localSegments[0]}`, ...localSegments.slice(1)];
 }
+/**
+ * 用 alias 词序列替换全部本地静态段，再按 owner 规则重挂前缀；动态段保留。
+ */
+function aliasRuntimeSegments(owner, alias, primarySegments) {
+    const aliasTokens = alias.trim().split(/\s+/u).filter(Boolean);
+    const dynamicTail = primarySegments.filter((segment) => segment.startsWith('$'));
+    if (owner === 'root')
+        return [...aliasTokens, ...dynamicTail];
+    const prefix = owner.slice('root/'.length).split('/').join('.');
+    return [`${prefix}.${aliasTokens[0]}`, ...aliasTokens.slice(1), ...dynamicTail];
+}
+function occupancyKey(segments, parameter) {
+    return parameter ? routeShape(segments) : segments.join(' ');
+}
+function normalizeAliasList(alias) {
+    if (!alias || alias.length === 0)
+        return undefined;
+    return Object.freeze(alias.map((entry) => entry.trim().split(/\s+/u).filter(Boolean).join(' ')));
+}
+function resolveShortcutParams(definition, prefill, source) {
+    const allowed = new Set();
+    const parameter = definition.$parameter;
+    if (parameter)
+        allowed.add(parameter.name);
+    if (definition.params) {
+        for (const key of Object.keys(definition.params))
+            allowed.add(key);
+    }
+    for (const key of Object.keys(prefill)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`Invalid shortcut params for ${source}: unknown key ${JSON.stringify(key)}`);
+        }
+    }
+    const result = { ...prefill };
+    if (parameter) {
+        if (result[parameter.name] === undefined) {
+            if (parameter.defaultValue !== undefined) {
+                result[parameter.name] = parameter.defaultValue;
+            }
+            else if (isRequiredParameter(parameter)) {
+                throw new TypeError(`Invalid shortcut params for ${source}: missing required ${parameter.name}`);
+            }
+        }
+    }
+    else if (allowed.size === 0 && Object.keys(prefill).length > 0) {
+        throw new TypeError(`Invalid shortcut params for ${source}: command has no params declaration`);
+    }
+    if (definition.params) {
+        for (const [name, schema] of Object.entries(definition.params)) {
+            if (result[name] === undefined && schema.default !== undefined) {
+                result[name] = schema.default;
+            }
+        }
+    }
+    return result;
+}
+function hasImSession(source) {
+    if (!source || typeof source !== 'object')
+        return false;
+    const conversation = source.conversation;
+    return !!conversation && typeof conversation === 'object';
+}
+function exactMessageText(input) {
+    if (typeof input === 'string') {
+        const trimmed = input.trim();
+        return trimmed || undefined;
+    }
+    // 仅纯单 text 段可作整句 shortcut；含 mention/image 等则不走 shortcut。
+    if (input.length !== 1)
+        return undefined;
+    const only = input[0];
+    if (!only || only.type !== 'text' || typeof only.data.text !== 'string')
+        return undefined;
+    const trimmed = only.data.text.trim();
+    return trimmed || undefined;
+}
 function assertParameterSegment(segments, parameter, source) {
     const dynamicSegments = segments.filter((segment) => segment.startsWith('$'));
     if (!parameter && dynamicSegments.length === 0)
@@ -200,7 +363,6 @@ function matcherPattern(segments, parameter) {
         if (!parameter)
             throw new Error(`Missing Command parameter metadata: ${segment}`);
         const type = matcherType(parameter.type);
-        // rest：结构化类型按消息段收集；标量类型先按 text 段收集，再在 #match 里逐词切分转换。
         if (parameter.rest) {
             return `[...${parameter.name}:${isStructuredRestType(parameter.type) ? type : 'text'}]`;
         }
@@ -214,7 +376,6 @@ function matcherPattern(segments, parameter) {
 function matcherType(type) {
     return type === 'string' ? 'word' : type;
 }
-/** rest 参数中按消息段收集（matcher 原生行为）的结构化类型。 */
 function isStructuredRestType(type) {
     return type === 'mention'
         || type === 'image'
@@ -224,16 +385,9 @@ function isStructuredRestType(type) {
         || type === 'dice'
         || type === 'rps';
 }
-/**
- * 捕获所有参数的取值粒度由类型决定：
- * - `text` / 结构化类型：逐消息段（matcher 原生结果）；
- * - `word` / `string`：逐词（空白切分）；
- * - `number` / `integer` / `float` / `boolean`：逐词切分后逐个转换，任一失败返回 undefined（不匹配）。
- */
 function coerceRestValues(parameter, values) {
     const type = parameter.type;
     if (type === 'text' || isStructuredRestType(type)) {
-        // 逐消息段，保持 matcher 原生提取值（text 为 string，结构化类型可能是 number 等）。
         return values;
     }
     const words = values.flatMap((value) => typeof value === 'string' ? value.split(/\s+/u).filter(Boolean) : []);
@@ -261,18 +415,20 @@ function coerceRestValues(parameter, values) {
 function routeShape(segments) {
     return segments.map((segment) => segment.startsWith('$') ? '$' : segment).join(' ');
 }
-function compareCommands(left, right) {
+function compareRecords(left, right) {
+    return left.name.localeCompare(right.name);
+}
+function compareRoutes(left, right) {
     return dynamicWeight(left) - dynamicWeight(right)
         || staticSegmentCount(right.segments) - staticSegmentCount(left.segments)
         || right.segments.length - left.segments.length
-        || right.name.length - left.name.length
-        || left.name.localeCompare(right.name);
+        || right.record.name.length - left.record.name.length
+        || left.record.name.localeCompare(right.record.name);
 }
-/** 静态 < 单参数 < 捕获所有：更具体的形状优先匹配。 */
-function dynamicWeight(command) {
-    if (!command.parameter)
+function dynamicWeight(route) {
+    if (!route.record.parameter)
         return 0;
-    return command.parameter.rest ? 2 : 1;
+    return route.record.parameter.rest ? 2 : 1;
 }
 function staticSegmentCount(segments) {
     return segments.filter((segment) => !segment.startsWith('$')).length;
@@ -333,12 +489,9 @@ function textArgs(segments) {
         return splitCommand(segment.data.text);
     }));
 }
-function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, matcher: _matcher, ...descriptor }) {
+function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, ...descriptor }) {
     return descriptor;
 }
-function duplicateCommand(name) {
-    return new Error(`Duplicate runtime Command: ${name}`);
-}
 export class CommandParameterValueError extends TypeError {
     constructor(name, type, value) {
         super(`Invalid value for Command parameter ${name}:${type}: ${value}`);

package/lib/definition.d.ts

@@ -59,7 +59,7 @@ export interface CommandConversation {
     readonly kind: 'private' | 'group' | 'channel';
     readonly id: string;
     readonly parent?: Readonly<{
-        readonly kind: 'group' | 'channel';
+        readonly kind: 'private' | 'group' | 'channel';
         readonly id: string;
     }>;
     readonly threadId?: string;
@@ -73,14 +73,37 @@ export interface CommandConversation {
 export interface CommandMessage {
     readonly conversation: CommandConversation;
     readonly content: string;
-    /** 发送者 id（扁平字段；结构化视图见 CommandContext.sender）。 */
-    readonly sender?: string;
+    /** 发送者（结构化视图见 CommandContext.sender）。 */
+    readonly sender?: {
+        readonly id: string;
+        readonly name?: string;
+        readonly roles?: readonly string[];
+    };
     readonly id?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
     /** 若上游已结构化，优先采用。 */
     readonly scene?: CommandScene;
-    readonly $reply?: (content: unknown) => Promise<unknown>;
-    readonly $replyFrom?: (requester: string, content: unknown) => Promise<unknown>;
+    $reply?(content: unknown): Promise<unknown>;
+    $replyFrom?(requester: string, content: unknown): Promise<unknown>;
+    /** 向同 Endpoint 的另一个通道发送消息（结构兼容 `Message.$sendTo`）。 */
+    $sendTo?(conversation: {
+        readonly kind: 'private' | 'group' | 'channel';
+        readonly id: string;
+        readonly parent?: Readonly<{
+            readonly kind: 'private' | 'group' | 'channel';
+            readonly id: string;
+        }>;
+        readonly threadId?: string;
+    }, content: unknown): Promise<unknown>;
+    /** 私信当前消息的发送者（结构兼容 `Message.$replyToPrivate`）。 */
+    $replyToPrivate?(content: unknown, from?: boolean | {
+        readonly kind: 'group' | 'channel';
+        readonly id: string;
+    }): Promise<unknown>;
+    /** 向指定群发送消息（结构兼容 `Message.$replyToGroup`）。 */
+    $replyToGroup?(groupId: string, content: unknown): Promise<unknown>;
+    /** 向指定频道发送消息（结构兼容 `Message.$replyToChannel`）。 */
+    $replyToChannel?(channelId: string, guildId: string, content: unknown, threadId?: string): Promise<unknown>;
 }
 /**
  * IM 入站快捷字段。
@@ -120,6 +143,21 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
      * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
      */
     readonly params?: Readonly<Record<string, CommandParamSchema>>;
+    /**
+     * 本地静态段别名（可多词，如 `'gh issue'`）。替换全部本地静态段后仍挂
+     * owner 前缀；不打破子插件命名空间。
+     */
+    readonly alias?: readonly string[];
+    /**
+     * 内置 permit DSL（AND）。单项内逗号为 OR。
+     * 例：`adapter(icqq)`、`role(master)`、`group(123,456)`。
+     */
+    readonly permit?: readonly string[];
+    /**
+     * 全局整句快捷方式：触发串（trim 后全文相等）→ 预填 params。
+     * 可打破 owner 命名空间。
+     */
+    readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandParameterValue>>>>;
     execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
 declare module '@zhin.js/plugin-runtime' {

package/lib/definition.js

@@ -1,4 +1,5 @@
 import { createCapabilityContext, } from '@zhin.js/feature-kit';
+import { assertPermitSyntax } from '@zhin.js/permission';
 const commandBrand = 'zhin.command/1';
 export const commandParameterTypes = new Set([
     'string',
@@ -35,8 +36,55 @@ export function defineCommand(definition) {
             }
         }
     }
+    validateCommandAlias(definition.alias);
+    validateCommandPermit(definition.permit);
+    validateCommandShortcutShape(definition.shortcut);
     return Object.freeze({ $feature: commandBrand, ...definition });
 }
+function validateCommandAlias(alias) {
+    if (alias === undefined)
+        return;
+    if (!Array.isArray(alias)) {
+        throw new TypeError('Command alias must be a readonly string[]');
+    }
+    for (const [index, entry] of alias.entries()) {
+        if (typeof entry !== 'string') {
+            throw new TypeError(`Command alias[${index}] must be a string`);
+        }
+        const tokens = entry.trim().split(/\s+/u).filter(Boolean);
+        if (tokens.length === 0) {
+            throw new TypeError(`Command alias[${index}] must contain at least one token`);
+        }
+    }
+}
+function validateCommandPermit(permit) {
+    if (permit === undefined)
+        return;
+    if (!Array.isArray(permit)) {
+        throw new TypeError('Command permit must be a readonly string[]');
+    }
+    for (const [index, entry] of permit.entries()) {
+        if (typeof entry !== 'string') {
+            throw new TypeError(`Command permit[${index}] must be a string`);
+        }
+    }
+    assertPermitSyntax(permit);
+}
+function validateCommandShortcutShape(shortcut) {
+    if (shortcut === undefined)
+        return;
+    if (!shortcut || typeof shortcut !== 'object' || Array.isArray(shortcut)) {
+        throw new TypeError('Command shortcut must be a Record<string, Record<string, value>>');
+    }
+    for (const [trigger, params] of Object.entries(shortcut)) {
+        if (!trigger.trim()) {
+            throw new TypeError('Command shortcut keys must be non-empty after trim');
+        }
+        if (!params || typeof params !== 'object' || Array.isArray(params)) {
+            throw new TypeError(`Command shortcut[${JSON.stringify(trigger)}] must be a params Record`);
+        }
+    }
+}
 export function bindCommandParameter(definition, parameter) {
     if (!parameter)
         return definition;
@@ -75,9 +123,8 @@ export function resolveCommandSession(input) {
         ? input.metadata
         : undefined;
     const adapter = input.conversation.endpoint.adapter || undefined;
-    const endpoint = typeof metadata?.endpoint === 'string' && metadata.endpoint
-        ? metadata.endpoint
-        : undefined;
+    const endpoint = input.endpointId
+        || (typeof metadata?.endpoint === 'string' && metadata.endpoint ? metadata.endpoint : undefined);
     const scene = resolveScene(input, metadata);
     const sender = resolveSender(input, metadata);
     return Object.freeze({
@@ -104,11 +151,8 @@ function resolveScene(input, metadata) {
         });
     }
     const conversation = input.conversation;
-    const type = (typeof metadata?.channelType === 'string' && metadata.channelType)
-        || (typeof metadata?.type === 'string' && metadata.type)
-        || conversation.kind;
-    const id = (typeof metadata?.channelId === 'string' && metadata.channelId)
-        || conversation.id;
+    const type = conversation.kind;
+    const id = conversation.id;
     if (!type || !id)
         return undefined;
     const name = firstString(metadata?.channelName, metadata?.group_name, metadata?.groupName, metadata?.sceneName);
@@ -123,24 +167,21 @@ function resolveSender(input, metadata) {
     if (isCommandSender(structured)) {
         return freezeSender(structured);
     }
-    // 允许上游把 sender 直接做成对象（未来 Runtime Message 演进）
-    if (isCommandSender(input.sender)) {
-        return freezeSender(input.sender);
-    }
-    const id = typeof input.sender === 'string' && input.sender
-        ? input.sender
-        : firstString(metadata?.user_id, metadata?.userId);
+    const id = input.sender?.id || firstString(metadata?.user_id, metadata?.userId);
     if (!id)
         return undefined;
-    const name = firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
-    const role = resolveRoles(metadata);
+    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(metadata) {
+function resolveRoles(input, metadata) {
+    if (input.sender?.roles?.length) {
+        return Object.freeze([...input.sender.roles]);
+    }
     const roles = [];
     const push = (value) => {
         if (typeof value !== 'string')

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from './command-index.js';
 export * from './definition.js';
+export { assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, type ParsedPermit, type PermitKind, } from './permit.js';
 export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export * from './command-index.js';
 export * from './definition.js';
+export { assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, } from './permit.js';
 export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';

package/lib/permit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export permit 解析/校验 from @zhin.js/permission (SSOT)。
+ * 保留 CommandSession 兼容签名供 command-index 过渡使用。
+ */
+export { type PermitKind, type ParsedPermit, parsePermitName, isBuiltinPermit, isPlatformPermit, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';

package/lib/permit.js

@@ -0,0 +1,5 @@
+/**
+ * Re-export permit 解析/校验 from @zhin.js/permission (SSOT)。
+ * 保留 CommandSession 兼容签名供 command-index 过渡使用。
+ */
+export { parsePermitName, isBuiltinPermit, isPlatformPermit, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';