@zhin.js/command 1.0.7 → 1.0.10

package/src/definition.ts

@@ -3,6 +3,7 @@ import {
   createCapabilityContext,
   type CapabilityContext,
 } from '@zhin.js/feature-kit';
+import { assertPermitSyntax } from '@zhin.js/permission';
 
 const commandBrand = 'zhin.command/1' as const;
 
@@ -29,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',
@@ -53,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;
 }
 
@@ -66,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[]`。 */
@@ -104,7 +128,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;
@@ -119,14 +143,35 @@ 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>;
+  // 方法式声明（而非属性式函数类型）：方法参数双变，runtime `Message` 的
+  // `$reply(content: SendContent)` 等才能鸭式兼容本契约（属性式是抗变，会报错）。
+  $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>;
 }
 
 /**
@@ -176,6 +221,21 @@ export interface CommandDefinition<
    * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
    */
   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, CommandDynamicValue>>>>;
   execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
 
@@ -213,9 +273,58 @@ export function defineCommand<
       }
     }
   }
+  validateCommandAlias(definition.alias);
+  validateCommandPermit(definition.permit);
+  validateCommandShortcutShape(definition.shortcut);
   return Object.freeze({ $feature: commandBrand, ...definition });
 }
 
+function validateCommandAlias(alias: readonly string[] | undefined): void {
+  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: readonly string[] | undefined): void {
+  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: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>> | undefined,
+): void {
+  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<
   TConfig,
   TResult,
@@ -239,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,
@@ -271,9 +396,8 @@ export function resolveCommandSession(input: unknown): CommandSession {
     : undefined;
 
   const adapter = input.conversation.endpoint.adapter || undefined;
-  const endpoint = typeof metadata?.endpoint === 'string' && metadata.endpoint
-    ? metadata.endpoint
-    : undefined;
+  const endpoint = (input as { endpointId?: string }).endpointId
+    || (typeof metadata?.endpoint === 'string' && metadata.endpoint ? metadata.endpoint : undefined);
 
   const scene = resolveScene(input, metadata);
   const sender = resolveSender(input, metadata);
@@ -307,11 +431,8 @@ function resolveScene(
   }
 
   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(
@@ -336,18 +457,12 @@ function resolveSender(
   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,
@@ -357,8 +472,12 @@ function resolveSender(
 }
 
 function resolveRoles(
+  input: CommandMessage,
   metadata: Readonly<Record<string, unknown>> | undefined,
 ): readonly string[] {
+  if (input.sender?.roles?.length) {
+    return Object.freeze([...input.sender.roles]);
+  }
   const roles: string[] = [];
   const push = (value: unknown) => {
     if (typeof value !== 'string') return;

package/src/index.ts

@@ -1,5 +1,15 @@
 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,

package/src/permit.ts

@@ -0,0 +1,14 @@
+/**
+ * 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/src/provider.ts

@@ -1,5 +1,5 @@
 import { basename, join, parse, sep } from 'node:path';
-import { featureId } from '@zhin.js/plugin-runtime';
+import { featureId, isCapabilityLocalSegment } from '@zhin.js/plugin-runtime';
 import {
   defineFeatureProvider,
   type DiscoveryContext,
@@ -54,7 +54,7 @@ async function* discoverCommandDirectory(
     }
   }
   for (const entry of entries) {
-    if (entry.kind === 'directory' && isCommandSegment(entry.name)) {
+    if (entry.kind === 'directory' && isCapabilityLocalSegment(entry.name)) {
       yield* discoverCommandDirectory(
         context,
         join(directory, entry.name),
@@ -74,10 +74,6 @@ async function* discoverCommandDirectory(
   }
 }
 
-function isCommandSegment(value: string): boolean {
-  return /^[a-z0-9][a-z0-9-]*$/.test(value);
-}
-
 interface ParsedCommandFile {
   readonly localSegment: string;
   readonly parameter?: CommandParameterHint;
@@ -101,9 +97,15 @@ const dynamicCommandFilePatterns: ReadonlyArray<{
   { pattern: /^\[([a-zA-Z][a-zA-Z0-9]*)\]\.(?:tsx?|[cm]?js)$/, optional: false, rest: false },
 ];
 
+const commandModuleExtension = /\.(?:tsx?|[cm]?js)$/u;
+
 function parseCommandFile(value: string): ParsedCommandFile | undefined {
-  if (/^[a-z0-9][a-z0-9-]*\.(?:tsx?|[cm]?js)$/.test(value)) {
-    return { localSegment: parse(value).name };
+  // 静态段：ASCII kebab（hello.ts）或 Unicode 名（赞我.ts）；与 isCapabilityLocalSegment 对齐。
+  if (commandModuleExtension.test(value)) {
+    const localSegment = parse(value).name;
+    if (isCapabilityLocalSegment(localSegment)) {
+      return { localSegment };
+    }
   }
   for (const { pattern, optional, rest } of dynamicCommandFilePatterns) {
     const match = pattern.exec(value);