@zhin.js/command 1.0.6 → 1.0.9

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;
 
@@ -25,9 +26,38 @@ export type CommandParameterValue =
   | string
   | number
   | boolean
+  | ReadonlyArray<string | number | boolean>
   | Readonly<Record<string, unknown>>
   | null;
 
+export const commandParameterTypes: ReadonlySet<CommandParameterType> = new Set([
+  'string',
+  'number',
+  'integer',
+  'float',
+  'boolean',
+  'word',
+  'text',
+  'mention',
+  'image',
+  'face',
+  'reply',
+  'forward',
+  'dice',
+  'rps',
+]);
+
+/**
+ * Next.js 风格参数声明（`defineCommand({ params: ... })`）。
+ * 文件名只声明参数形态（`[name]` / `[[name]]` / `[...name]` / `[[...name]]`），
+ * 类型与默认值统一在这里声明。
+ */
+export interface CommandParamSchema {
+  readonly type: CommandParameterType;
+  readonly default?: CommandParameterValue;
+  readonly description?: string;
+}
+
 /** Minimal structural contract shared with canonical IM segments. */
 export interface CommandSegment {
   readonly type: string | { readonly name: string };
@@ -38,6 +68,11 @@ export interface CommandParameterDefinition {
   readonly name: string;
   readonly type: CommandParameterType;
   readonly defaultValue?: CommandParameterValue;
+  /** `[[name]]` / `[[...name]]` 可选段；缺省按 `defaultValue === undefined` 推断。 */
+  readonly optional?: boolean;
+  /** `[...name]` / `[[...name]]` 捕获所有段，运行时值为 `string[]`。 */
+  readonly rest?: boolean;
+  readonly description?: string;
 }
 
 /** 场景：群 / 私聊 / 频道等。 */
@@ -57,6 +92,25 @@ export interface CommandSender {
   readonly role: readonly string[];
 }
 
+/**
+ * 命令侧入站会话契约（结构对齐 `@zhin.js/im-contract` 的 ConversationRef；
+ * command 为 Feature 层，不能 import core / IM 契约包，故独立声明）。
+ */
+export interface CommandConversation {
+  readonly endpoint: Readonly<{
+    readonly id: string;
+    /** 适配器插件 owner（PluginId），与 `snapshot.config.get(adapter)` 对齐。 */
+    readonly adapter: string;
+  }>;
+  readonly kind: 'private' | 'group' | 'channel';
+  readonly id: string;
+  readonly parent?: Readonly<{
+    readonly kind: 'private' | 'group' | 'channel';
+    readonly id: string;
+  }>;
+  readonly threadId?: string;
+}
+
 /**
  * 命令侧入站消息契约。
  *
@@ -64,17 +118,37 @@ export interface CommandSender {
  * 因架构分层（command 为 Feature 层，不能 import core），此处独立声明。
  */
 export interface CommandMessage {
-  readonly adapter: string;
-  readonly target: string;
+  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>;
 }
 
 /**
@@ -119,6 +193,26 @@ export interface CommandDefinition<
   readonly $feature: typeof commandBrand;
   readonly $parameter?: CommandParameterDefinition;
   readonly description?: string;
+  /**
+   * Next.js 风格参数声明：动态段文件名（`[name]` 等）的形态配合这里的
+   * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
+   */
+  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>;
 }
 
@@ -145,9 +239,69 @@ export function defineCommand<
   if (typeof definition.execute !== 'function') {
     throw new TypeError('Command execute must be a function');
   }
+  if (definition.params !== undefined) {
+    if (!definition.params || typeof definition.params !== 'object') {
+      throw new TypeError('Command params must be a Record<string, CommandParamSchema>');
+    }
+    for (const [name, schema] of Object.entries(definition.params)) {
+      if (!schema || typeof schema !== 'object'
+        || !commandParameterTypes.has((schema as CommandParamSchema).type)) {
+        throw new TypeError(`Command params.${name} requires a valid type`);
+      }
+    }
+  }
+  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, CommandParameterValue>>>> | 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,
@@ -202,10 +356,9 @@ export function resolveCommandSession(input: unknown): CommandSession {
     ? input.metadata as Readonly<Record<string, unknown>>
     : undefined;
 
-  const adapter = input.adapter.split('\0')[0] || undefined;
-  const endpoint = typeof metadata?.endpoint === 'string' && metadata.endpoint
-    ? metadata.endpoint
-    : undefined;
+  const adapter = input.conversation.endpoint.adapter || 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);
@@ -221,8 +374,8 @@ export function resolveCommandSession(input: unknown): CommandSession {
 function isCommandMessageLike(input: unknown): input is CommandMessage {
   if (!input || typeof input !== 'object') return false;
   const value = input as Partial<CommandMessage>;
-  return typeof value.adapter === 'string'
-    && typeof value.target === 'string'
+  return !!value.conversation
+    && typeof value.conversation === 'object'
     && typeof value.content === 'string';
 }
 
@@ -238,12 +391,9 @@ function resolveScene(
     });
   }
 
-  const parsed = parseTarget(input.target);
-  const type = (typeof metadata?.channelType === 'string' && metadata.channelType)
-    || (typeof metadata?.type === 'string' && metadata.type)
-    || parsed?.type;
-  const id = (typeof metadata?.channelId === 'string' && metadata.channelId)
-    || parsed?.id;
+  const conversation = input.conversation;
+  const type = conversation.kind;
+  const id = conversation.id;
   if (!type || !id) return undefined;
 
   const name = firstString(
@@ -268,18 +418,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,
@@ -289,8 +433,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;
@@ -309,22 +457,6 @@ function resolveRoles(
   return Object.freeze(roles);
 }
 
-function parseTarget(target: string): { readonly type: string; readonly id: string } | undefined {
-  const parts = target.split(':').filter(Boolean);
-  if (parts.length < 2) return undefined;
-  const [kind, ...rest] = parts;
-  if (!kind) return undefined;
-  const lastPart = parts.at(-1);
-  if (!lastPart) return undefined;
-  if (kind === 'channel' && parts.length >= 3) {
-    return { type: 'channel', id: lastPart };
-  }
-  if (kind === 'temp' && parts.length >= 3) {
-    return { type: 'private', id: lastPart };
-  }
-  return { type: kind, id: rest.join(':') };
-}
-
 function isCommandScene(value: unknown): value is CommandScene {
   if (!value || typeof value !== 'object') return false;
   const scene = value as Partial<CommandScene>;

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,
@@ -10,9 +10,8 @@ import { CommandIndex } from './command-index.js';
 import {
   bindCommandParameter,
   parseCommandDefinition,
+  type CommandDefinition,
   type CommandParameterDefinition,
-  type CommandParameterType,
-  type CommandParameterValue,
 } from './definition.js';
 
 export const commandFeatureId = featureId('zhin.command');
@@ -27,7 +26,7 @@ const commandFiles: SourceConvention = {
     const module = await context.host.loadModule<{ default?: unknown }>(source.source);
     const definition = parseCommandDefinition(module.default);
     const file = parseCommandFile(basename(source.source));
-    return bindCommandParameter(definition, file?.parameter);
+    return bindCommandParameter(definition, resolveParameter(definition, file, source.source));
   },
 };
 
@@ -55,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),
@@ -75,51 +74,48 @@ async function* discoverCommandDirectory(
   }
 }
 
-function isCommandSegment(value: string): boolean {
-  return /^[a-z0-9][a-z0-9-]*$/.test(value);
-}
-
 interface ParsedCommandFile {
   readonly localSegment: string;
-  readonly parameter?: CommandParameterDefinition;
+  readonly parameter?: CommandParameterHint;
+}
+
+/** 文件名声明的参数形态；类型与默认值来自 `defineCommand({ params })`。 */
+interface CommandParameterHint {
+  readonly name: string;
+  readonly optional: boolean;
+  readonly rest: boolean;
 }
 
-const dynamicCommandFilePattern =
-  /^\[([a-z][a-zA-Z0-9]*):([a-z][a-z0-9-]*)(?:=([^\]]*))?\]\.(?:tsx?|[cm]?js)$/;
+const dynamicCommandFilePatterns: ReadonlyArray<{
+  readonly pattern: RegExp;
+  readonly optional: boolean;
+  readonly rest: boolean;
+}> = [
+  { pattern: /^\[\[\.\.\.([a-zA-Z][a-zA-Z0-9]*)\]\]\.(?:tsx?|[cm]?js)$/, optional: true, rest: true },
+  { pattern: /^\[\.\.\.([a-zA-Z][a-zA-Z0-9]*)\]\.(?:tsx?|[cm]?js)$/, optional: false, rest: true },
+  { pattern: /^\[\[([a-zA-Z][a-zA-Z0-9]*)\]\]\.(?:tsx?|[cm]?js)$/, optional: true, rest: false },
+  { pattern: /^\[([a-zA-Z][a-zA-Z0-9]*)\]\.(?:tsx?|[cm]?js)$/, optional: false, rest: false },
+];
 
-const commandParameterTypes = new Set<CommandParameterType>([
-  'string',
-  'number',
-  'integer',
-  'float',
-  'boolean',
-  'word',
-  'text',
-  'mention',
-  'image',
-  'face',
-  'reply',
-  'forward',
-  'dice',
-  'rps',
-]);
+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 };
-  }
-  const match = dynamicCommandFilePattern.exec(value);
-  if (match) {
-    const [, name, rawType, rawDefault] = match;
-    if (!name || !rawType || !commandParameterTypes.has(rawType as CommandParameterType)) {
-      throw new CommandPathSyntaxError(value, `unsupported parameter type: ${rawType ?? ''}`);
+  // 静态段：ASCII kebab（hello.ts）或 Unicode 名（赞我.ts）；与 isCapabilityLocalSegment 对齐。
+  if (commandModuleExtension.test(value)) {
+    const localSegment = parse(value).name;
+    if (isCapabilityLocalSegment(localSegment)) {
+      return { localSegment };
     }
-    const type = rawType as CommandParameterType;
+  }
+  for (const { pattern, optional, rest } of dynamicCommandFilePatterns) {
+    const match = pattern.exec(value);
+    if (!match || !match[1]) continue;
+    const name = match[1];
     // Metadata can change during HMR while $name keeps the Capability identity stable.
-    const parameter = rawDefault === undefined
-      ? { name, type }
-      : { name, type, defaultValue: parseParameterValue(name, type, rawDefault, value) };
-    return { localSegment: `$${name}`, parameter };
+    return {
+      localSegment: `$${name}`,
+      parameter: { name, optional, rest },
+    };
   }
   if (value.startsWith('[') || value.includes(']')) {
     throw new CommandPathSyntaxError(value);
@@ -127,66 +123,51 @@ function parseCommandFile(value: string): ParsedCommandFile | undefined {
   return undefined;
 }
 
-function commandFilePriority(value: string, preferJavaScript: boolean): number {
-  const extension = value.slice(value.lastIndexOf('.') + 1);
-  const order = preferJavaScript
-    ? ['js', 'mjs', 'cjs', 'ts', 'tsx']
-    : ['ts', 'tsx', 'js', 'mjs', 'cjs'];
-  const priority = order.indexOf(extension);
-  return priority < 0 ? Number.MAX_SAFE_INTEGER : priority;
-}
-
-function parseParameterValue(
-  name: string,
-  type: CommandParameterType,
-  value: string,
+/** 把文件名形态与 `definition.params` 合并成完整参数定义。 */
+function resolveParameter(
+  definition: CommandDefinition,
+  file: ParsedCommandFile | undefined,
   source: string,
-): CommandParameterValue {
-  if (type === 'string' || type === 'word' || type === 'text') return value;
-  if (type === 'number' || type === 'integer' || type === 'float') {
-    const number = Number(value);
-    if (
-      value.trim().length > 0
-      && Number.isFinite(number)
-      && (type !== 'integer' || Number.isInteger(number))
-      && (type !== 'float' || value.includes('.'))
-    ) return number;
+): CommandParameterDefinition | undefined {
+  const hint = file?.parameter;
+  if (!hint) return undefined;
+  const schema = definition.params?.[hint.name];
+  if (!schema) {
     throw new CommandPathSyntaxError(
       source,
-      `default for ${name}:${type} is invalid`,
+      `missing params.${hint.name} declaration in defineCommand({ params })`,
     );
   }
-  if (type === 'boolean') {
-    if (value === 'true' || value === 'false') return value === 'true';
+  if (!hint.optional && schema.default !== undefined) {
     throw new CommandPathSyntaxError(
       source,
-      `default for ${name}:${type} is invalid`,
+      `params.${hint.name} has a default but the file is required: rename to [[${hint.name}]]`,
     );
   }
-  if (isStructuredParameter(type)) {
-    throw new CommandPathSyntaxError(
-      source,
-      `default for structured parameter ${name}:${type} is not supported`,
-    );
-  }
-  throw new CommandPathSyntaxError(
-    source,
-    `default for ${name}:${type} is invalid`,
-  );
+  return {
+    name: hint.name,
+    type: schema.type,
+    ...(schema.default !== undefined ? { defaultValue: schema.default } : {}),
+    optional: hint.optional,
+    rest: hint.rest,
+    ...(schema.description !== undefined ? { description: schema.description } : {}),
+  };
 }
 
-function isStructuredParameter(type: CommandParameterType): boolean {
-  return type === 'mention'
-    || type === 'image'
-    || type === 'face'
-    || type === 'reply'
-    || type === 'forward'
-    || type === 'dice'
-    || type === 'rps';
+function commandFilePriority(value: string, preferJavaScript: boolean): number {
+  const extension = value.slice(value.lastIndexOf('.') + 1);
+  const order = preferJavaScript
+    ? ['js', 'mjs', 'cjs', 'ts', 'tsx']
+    : ['ts', 'tsx', 'js', 'mjs', 'cjs'];
+  const priority = order.indexOf(extension);
+  return priority < 0 ? Number.MAX_SAFE_INTEGER : priority;
 }
 
 export class CommandPathSyntaxError extends TypeError {
-  constructor(file: string, detail = 'expected [name:type=default].ts(x)') {
+  constructor(
+    file: string,
+    detail = 'expected [name].ts(x), [[name]].ts(x), [...name].ts(x) or [[...name]].ts(x)',
+  ) {
     super(`Invalid Command path ${file}: ${detail}`);
     this.name = 'CommandPathSyntaxError';
   }