@zhin.js/command 1.0.9 → 1.0.11

package/lib/command-index.js

@@ -1,5 +1,5 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
-import { createCommandContext, resolveCommandSession, } from './definition.js';
+import { createCommandContext, resolveCommandSession, resolveDynamicParams, } from './definition.js';
 import { permissionHostToken } from '@zhin.js/permission';
 import { toPermissionSubject } from '@zhin.js/permission';
 const segmentFields = {
@@ -114,8 +114,8 @@ 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));
+        // Host / 无 session：跳过 permit；无 source 时函数默认值得到空 session。
+        return match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, resolveDynamicParams(match.params, undefined)));
     }
     async dispatch(input, source = undefined) {
         const shortcut = this.#matchShortcut(input);
@@ -123,7 +123,7 @@ export class CommandIndex {
             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([])));
+            const value = await shortcut.record.slot.definition.execute(createCommandContext(this.snapshot, shortcut.record.slot.owner, Object.freeze([]), resolveDynamicParams(shortcut.params, source), source, Object.freeze([])));
             return Object.freeze({
                 matched: true,
                 command: shortcut.record.name,
@@ -138,7 +138,7 @@ export class CommandIndex {
             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));
+        const value = await match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, resolveDynamicParams(match.params, source), source, match.remaining));
         return Object.freeze({
             matched: true,
             command: match.command.name,
@@ -370,7 +370,7 @@ function matcherPattern(segments, parameter) {
             return `<${parameter.name}:${type}>`;
         return parameter.defaultValue === undefined
             ? `[${parameter.name}:${type}]`
-            : `[${parameter.name}:${type}=${String(parameter.defaultValue)}]`;
+            : `[${parameter.name}:${type}=${typeof parameter.defaultValue === 'function' ? '<dynamic>' : String(parameter.defaultValue)}]`;
     }).join(' ');
 }
 function matcherType(type) {

package/lib/definition.d.ts

@@ -3,6 +3,26 @@ import { type CapabilityContext } from '@zhin.js/feature-kit';
 declare const commandBrand: "zhin.command/1";
 export type CommandParameterType = 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'word' | 'text' | 'mention' | 'image' | 'face' | 'reply' | 'forward' | 'dice' | 'rps';
 export type CommandParameterValue = string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null;
+/**
+ * 可从运行时会话上下文动态解析的参数值。
+ *
+ * 静态值直接使用；函数值在命令派发时接收 {@link CommandSession}，
+ * 返回最终的 {@link CommandParameterValue}。适用于 shortcut 预填
+ * 和 params.default。
+ *
+ * ```ts
+ * defineCommand({
+ *   params: {
+ *     user_id: { type: 'string', default: (s) => s.sender?.id ?? '' },
+ *   },
+ *   shortcut: {
+ *     '查看我的信息': { user_id: (s) => s.sender?.id ?? '' },
+ *   },
+ *   execute: ({ params }) => `profile:${params.user_id}`,
+ * })
+ * ```
+ */
+export type CommandDynamicValue = CommandParameterValue | ((session: CommandSession) => CommandParameterValue);
 export declare const commandParameterTypes: ReadonlySet<CommandParameterType>;
 /**
  * Next.js 风格参数声明（`defineCommand({ params: ... })`）。
@@ -11,7 +31,7 @@ export declare const commandParameterTypes: ReadonlySet<CommandParameterType>;
  */
 export interface CommandParamSchema {
     readonly type: CommandParameterType;
-    readonly default?: CommandParameterValue;
+    readonly default?: CommandDynamicValue;
     readonly description?: string;
 }
 /** Minimal structural contract shared with canonical IM segments. */
@@ -24,7 +44,7 @@ export interface CommandSegment {
 export interface CommandParameterDefinition {
     readonly name: string;
     readonly type: CommandParameterType;
-    readonly defaultValue?: CommandParameterValue;
+    readonly defaultValue?: CommandDynamicValue;
     /** `[[name]]` / `[[...name]]` 可选段；缺省按 `defaultValue === undefined` 推断。 */
     readonly optional?: boolean;
     /** `[...name]` / `[[...name]]` 捕获所有段，运行时值为 `string[]`。 */
@@ -157,7 +177,7 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
      * 全局整句快捷方式：触发串（trim 后全文相等）→ 预填 params。
      * 可打破 owner 命名空间。
      */
-    readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandParameterValue>>>>;
+    readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>>;
     execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
 declare module '@zhin.js/plugin-runtime' {
@@ -172,6 +192,11 @@ declare module '@zhin.js/plugin-runtime' {
 export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage>(definition: Omit<CommandDefinition<TConfig, TResult, TInput>, '$feature' | '$parameter'>): Readonly<CommandDefinition<TConfig, TResult, TInput>>;
 export declare function bindCommandParameter<TConfig, TResult, TInput extends CommandMessage>(definition: CommandDefinition<TConfig, TResult, TInput>, parameter: CommandParameterDefinition | undefined): Readonly<CommandDefinition<TConfig, TResult, TInput>>;
 export declare function parseCommandDefinition(value: unknown): CommandDefinition;
+/**
+ * 将动态参数值（可能包含函数）批量解析为静态值。
+ * 函数值接收从 `source`（通常是 IM Runtime `Message`）解析出的 {@link CommandSession}。
+ */
+export declare function resolveDynamicParams(params: Readonly<Record<string, CommandDynamicValue>>, source: unknown): Readonly<Record<string, CommandParameterValue>>;
 export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown, segments?: readonly Readonly<CommandSegment>[]): CommandContext;
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。

package/lib/definition.js

@@ -100,6 +100,18 @@ export function parseCommandDefinition(value) {
     }
     return definition;
 }
+/**
+ * 将动态参数值（可能包含函数）批量解析为静态值。
+ * 函数值接收从 `source`（通常是 IM Runtime `Message`）解析出的 {@link CommandSession}。
+ */
+export function resolveDynamicParams(params, source) {
+    const session = resolveCommandSession(source);
+    const resolved = {};
+    for (const [key, value] of Object.entries(params)) {
+        resolved[key] = typeof value === 'function' ? value(session) : value;
+    }
+    return Object.freeze(resolved);
+}
 export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([])) {
     const context = createCapabilityContext(snapshot, ownerId);
     const session = resolveCommandSession(input);
@@ -167,10 +179,15 @@ function resolveSender(input, metadata) {
     if (isCommandSender(structured)) {
         return freezeSender(structured);
     }
-    const id = input.sender?.id || firstString(metadata?.user_id, metadata?.userId);
+    const $sender = input.$sender;
+    const id = input.sender?.id
+        || (typeof $sender?.id === 'string' ? $sender.id : undefined)
+        || firstString(metadata?.user_id, metadata?.userId);
     if (!id)
         return undefined;
-    const name = input.sender?.name || firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
+    const name = input.sender?.name
+        || (typeof $sender?.name === 'string' ? $sender.name : undefined)
+        || firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
     const role = resolveRoles(input, metadata);
     return Object.freeze({
         id,
@@ -190,16 +207,19 @@ function resolveRoles(input, metadata) {
         if (trimmed && !roles.includes(trimmed))
             roles.push(trimmed);
     };
+    // IM Message 的 $sender 携带 enrich 快照（isMaster/isTrusted）和平台群角色（role）
+    const $sender = input.$sender;
+    if ($sender?.isMaster === true || metadata?.isMaster === true)
+        push('master');
+    else if ($sender?.isTrusted === true || metadata?.isTrusted === true)
+        push('trusted');
+    push($sender?.role);
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,8 +19,8 @@
   "dependencies": {
     "segment-matcher": "^1.0.5",
     "@zhin.js/feature-kit": "1.0.8",
-    "@zhin.js/plugin-runtime": "1.1.5",
-    "@zhin.js/permission": "1.0.1"
+    "@zhin.js/permission": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -16,6 +16,8 @@ import {
   type CommandParameterType,
   type CommandParameterValue,
   type CommandSegment,
+  type CommandDynamicValue,
+  resolveDynamicParams,
 } from './definition.js';
 import { permissionHostToken, type PermissionHost } from '@zhin.js/permission';
 import { toPermissionSubject } from '@zhin.js/permission';
@@ -57,12 +59,12 @@ interface CommandRoute {
 
 interface ShortcutEntry {
   readonly record: CommandRecord;
-  readonly params: Readonly<Record<string, CommandParameterValue>>;
+  readonly params: Readonly<Record<string, CommandDynamicValue>>;
 }
 
 interface CommandMatch {
   readonly command: CommandRecord;
-  readonly params: Readonly<Record<string, CommandParameterValue>>;
+  readonly params: Readonly<Record<string, CommandDynamicValue>>;
   readonly remaining: readonly Readonly<CommandSegment>[];
 }
 
@@ -197,13 +199,13 @@ export class CommandIndex {
       this.#diagnoseParameter(name);
       throw new Error(`Unknown Command: ${name}`);
     }
-    // Host / 无 session：跳过 permit。
+    // Host / 无 session：跳过 permit；无 source 时函数默认值得到空 session。
     return match.command.slot.definition.execute(
       createCommandContext(
         this.snapshot,
         match.command.slot.owner,
         args,
-        match.params,
+        resolveDynamicParams(match.params, undefined),
       ),
     );
   }
@@ -222,7 +224,7 @@ export class CommandIndex {
           this.snapshot,
           shortcut.record.slot.owner,
           Object.freeze([]),
-          shortcut.params,
+          resolveDynamicParams(shortcut.params, source),
           source,
           Object.freeze([]),
         ),
@@ -246,7 +248,7 @@ export class CommandIndex {
         this.snapshot,
         match.command.slot.owner,
         args,
-        match.params,
+        resolveDynamicParams(match.params, source),
         source,
         match.remaining,
       ),
@@ -302,7 +304,7 @@ export class CommandIndex {
       const result = route.matcher.match(asMatcherSegments(segments));
       if (!result || !hasCommandBoundary(result.remaining)) continue;
       const parameter = route.record.parameter;
-      const params: Record<string, CommandParameterValue> = { ...result.params };
+      const params: Record<string, CommandDynamicValue> = { ...result.params };
       if (parameter?.rest) {
         const raw = result.params[parameter.name];
         const coerced = coerceRestValues(parameter, Array.isArray(raw) ? raw : []);
@@ -390,9 +392,9 @@ function normalizeAliasList(
 
 function resolveShortcutParams(
   definition: CommandDefinition,
-  prefill: Readonly<Record<string, CommandParameterValue>>,
+  prefill: Readonly<Record<string, CommandDynamicValue>>,
   source: string,
-): Record<string, CommandParameterValue> {
+): Record<string, CommandDynamicValue> {
   const allowed = new Set<string>();
   const parameter = definition.$parameter;
   if (parameter) allowed.add(parameter.name);
@@ -408,7 +410,7 @@ function resolveShortcutParams(
     }
   }
 
-  const result: Record<string, CommandParameterValue> = { ...prefill };
+  const result: Record<string, CommandDynamicValue> = { ...prefill };
 
   if (parameter) {
     if (result[parameter.name] === undefined) {
@@ -508,7 +510,7 @@ function matcherPattern(
     if (isRequiredParameter(parameter)) return `<${parameter.name}:${type}>`;
     return parameter.defaultValue === undefined
       ? `[${parameter.name}:${type}]`
-      : `[${parameter.name}:${type}=${String(parameter.defaultValue)}]`;
+      : `[${parameter.name}:${type}=${typeof parameter.defaultValue === 'function' ? '<dynamic>' : String(parameter.defaultValue)}]`;
   }).join(' ');
 }
 

package/src/definition.ts

@@ -30,6 +30,29 @@ export type CommandParameterValue =
   | Readonly<Record<string, unknown>>
   | null;
 
+/**
+ * 可从运行时会话上下文动态解析的参数值。
+ *
+ * 静态值直接使用；函数值在命令派发时接收 {@link CommandSession}，
+ * 返回最终的 {@link CommandParameterValue}。适用于 shortcut 预填
+ * 和 params.default。
+ *
+ * ```ts
+ * defineCommand({
+ *   params: {
+ *     user_id: { type: 'string', default: (s) => s.sender?.id ?? '' },
+ *   },
+ *   shortcut: {
+ *     '查看我的信息': { user_id: (s) => s.sender?.id ?? '' },
+ *   },
+ *   execute: ({ params }) => `profile:${params.user_id}`,
+ * })
+ * ```
+ */
+export type CommandDynamicValue =
+  | CommandParameterValue
+  | ((session: CommandSession) => CommandParameterValue);
+
 export const commandParameterTypes: ReadonlySet<CommandParameterType> = new Set([
   'string',
   'number',
@@ -54,7 +77,7 @@ export const commandParameterTypes: ReadonlySet<CommandParameterType> = new Set(
  */
 export interface CommandParamSchema {
   readonly type: CommandParameterType;
-  readonly default?: CommandParameterValue;
+  readonly default?: CommandDynamicValue;
   readonly description?: string;
 }
 
@@ -67,7 +90,7 @@ export interface CommandSegment {
 export interface CommandParameterDefinition {
   readonly name: string;
   readonly type: CommandParameterType;
-  readonly defaultValue?: CommandParameterValue;
+  readonly defaultValue?: CommandDynamicValue;
   /** `[[name]]` / `[[...name]]` 可选段；缺省按 `defaultValue === undefined` 推断。 */
   readonly optional?: boolean;
   /** `[...name]` / `[[...name]]` 捕获所有段，运行时值为 `string[]`。 */
@@ -212,7 +235,7 @@ export interface CommandDefinition<
    * 全局整句快捷方式：触发串（trim 后全文相等）→ 预填 params。
    * 可打破 owner 命名空间。
    */
-  readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandParameterValue>>>>;
+  readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>>;
   execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
 
@@ -286,7 +309,7 @@ function validateCommandPermit(permit: readonly string[] | undefined): void {
 }
 
 function validateCommandShortcutShape(
-  shortcut: Readonly<Record<string, Readonly<Record<string, CommandParameterValue>>>> | undefined,
+  shortcut: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>> | undefined,
 ): void {
   if (shortcut === undefined) return;
   if (!shortcut || typeof shortcut !== 'object' || Array.isArray(shortcut)) {
@@ -325,6 +348,22 @@ export function parseCommandDefinition(value: unknown): CommandDefinition {
   return definition as CommandDefinition;
 }
 
+/**
+ * 将动态参数值（可能包含函数）批量解析为静态值。
+ * 函数值接收从 `source`（通常是 IM Runtime `Message`）解析出的 {@link CommandSession}。
+ */
+export function resolveDynamicParams(
+  params: Readonly<Record<string, CommandDynamicValue>>,
+  source: unknown,
+): Readonly<Record<string, CommandParameterValue>> {
+  const session = resolveCommandSession(source);
+  const resolved: Record<string, CommandParameterValue> = {};
+  for (const [key, value] of Object.entries(params)) {
+    resolved[key] = typeof value === 'function' ? value(session) : value;
+  }
+  return Object.freeze(resolved);
+}
+
 export function createCommandContext(
   snapshot: RuntimeSnapshot,
   ownerId: PluginId,
@@ -419,10 +458,15 @@ function resolveSender(
     return freezeSender(structured);
   }
 
-  const id = input.sender?.id || firstString(metadata?.user_id, metadata?.userId);
+  const $sender = (input as { readonly $sender?: Readonly<Record<string, unknown>> }).$sender;
+  const id = input.sender?.id
+    || (typeof $sender?.id === 'string' ? $sender.id : undefined)
+    || firstString(metadata?.user_id, metadata?.userId);
   if (!id) return undefined;
 
-  const name = input.sender?.name || firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
+  const name = input.sender?.name
+    || (typeof $sender?.name === 'string' ? $sender.name : undefined)
+    || firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
   const role = resolveRoles(input, metadata);
 
   return Object.freeze({
@@ -446,13 +490,18 @@ function resolveRoles(
     if (trimmed && !roles.includes(trimmed)) roles.push(trimmed);
   };
 
+  // IM Message 的 $sender 携带 enrich 快照（isMaster/isTrusted）和平台群角色（role）
+  const $sender = (input as { readonly $sender?: Readonly<Record<string, unknown>> }).$sender;
+
+  if ($sender?.isMaster === true || metadata?.isMaster === true) push('master');
+  else if ($sender?.isTrusted === true || metadata?.isTrusted === true) push('trusted');
+
+  push($sender?.role);
   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);
 }