@zhin.js/command 1.0.15 → 1.0.16

package/lib/command-index.d.ts

@@ -7,6 +7,7 @@ export interface CommandParameterDescriptor extends CommandParameterDefinition {
 export interface CommandDescriptor {
     readonly name: string;
     readonly description?: string;
+    readonly adapter?: string;
     readonly source: string;
     readonly parameters: readonly CommandParameterDescriptor[];
     readonly alias?: readonly string[];

package/lib/command-index.js

@@ -1,4 +1,5 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
+import { operationClientAdapter } from '@zhin.js/feature-kit';
 import { permissionHostToken, toPermissionSubject, } from '@zhin.js/permission';
 import { createCommandContext, resolveCommandSession, resolveDynamicParams, } from './definition.js';
 const segmentFields = {
@@ -48,6 +49,7 @@ export class CommandIndex {
             const record = Object.freeze({
                 name,
                 description: slot.definition.description,
+                ...(slot.definition.adapter ? { adapter: slot.definition.adapter } : {}),
                 source: slot.source,
                 parameters: Object.freeze(parameter ? [{
                         ...parameter,
@@ -116,7 +118,7 @@ export class CommandIndex {
             throw new Error(`Unknown Command: ${name}`);
         }
         // Host / 无 session：跳过 permit；无 source 时函数默认值得到空 session。
-        return match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, resolveDynamicParams(match.params, undefined)));
+        return match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, resolveDynamicParams(match.params, undefined), undefined, Object.freeze([]), undefined, match.command.slot.definition.adapter));
     }
     async dispatch(input, source = undefined, interactionFactory, commandPrefix = '') {
         if (this.#menu) {
@@ -133,10 +135,13 @@ export class CommandIndex {
         const interaction = interactionFactory?.(source);
         const shortcut = this.#matchShortcut(input);
         if (shortcut) {
+            if (!commandAdapterMatches(shortcut.record, source)) {
+                return Object.freeze({ matched: false });
+            }
             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([]), resolveDynamicParams(shortcut.params, source), source, Object.freeze([]), interaction));
+            const value = await shortcut.record.slot.definition.execute(createCommandContext(this.snapshot, shortcut.record.slot.owner, Object.freeze([]), resolveDynamicParams(shortcut.params, source), source, Object.freeze([]), interaction, shortcut.record.slot.definition.adapter));
             return Object.freeze({
                 matched: true,
                 command: shortcut.record.name,
@@ -147,11 +152,14 @@ export class CommandIndex {
         const match = this.#match(input, false);
         if (!match)
             return Object.freeze({ matched: false });
+        if (!commandAdapterMatches(match.command, source)) {
+            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, resolveDynamicParams(match.params, source), source, match.remaining, interaction));
+        const value = await match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, resolveDynamicParams(match.params, source), source, match.remaining, interaction, match.command.slot.definition.adapter));
         return Object.freeze({
             matched: true,
             command: match.command.name,
@@ -564,6 +572,9 @@ function textArgs(segments) {
 function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, ...descriptor }) {
     return descriptor;
 }
+function commandAdapterMatches(record, source) {
+    return !record.adapter || operationClientAdapter(source) === record.adapter;
+}
 export class CommandParameterValueError extends TypeError {
     constructor(name, type, value) {
         super(`Invalid value for Command parameter ${name}:${type}: ${value}`);

package/lib/definition.d.ts

@@ -1,5 +1,9 @@
+/**
+ * Command authoring API consumed from `zhin.js/command`.
+ * @module zhin.js/command
+ */
 import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import { type CapabilityContext } from '@zhin.js/feature-kit';
+import { type AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
 import type { UserInteraction } from '@zhin.js/interaction';
 declare const commandBrand: "zhin.command/1";
 export type CommandParameterType = 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'word' | 'text' | 'mention' | 'image' | 'face' | 'reply' | 'forward' | 'dice' | 'rps';
@@ -24,6 +28,7 @@ export type CommandParameterValue = string | number | boolean | ReadonlyArray<st
  * ```
  */
 export type CommandDynamicValue = CommandParameterValue | ((session: CommandSession) => CommandParameterValue);
+/** @internal Runtime validator lookup. */
 export declare const commandParameterTypes: ReadonlySet<CommandParameterType>;
 /**
  * Next.js 风格参数声明（`defineCommand({ params: ... })`）。
@@ -102,6 +107,8 @@ export interface CommandMessage {
     };
     readonly id?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly clientAdapter?: string;
+    readonly $client?: unknown;
     /** 若上游已结构化，优先采用。 */
     readonly scene?: CommandScene;
     $reply?(content: unknown): Promise<unknown>;
@@ -128,7 +135,7 @@ export interface CommandMessage {
 }
 /**
  * IM 入站快捷字段。
- * 有 `CommandMessage` 来源时由 {@link resolveCommandSession} 填充；
+ * 有 `CommandMessage` 来源时由 Runtime 从消息结构填充；
  * `CommandIndex.execute(name)` 等无消息路径下为 `undefined`。
  */
 export interface CommandSession {
@@ -159,7 +166,7 @@ export interface CommandSession {
  * });
  * ```
  */
-export interface CommandContext<TConfig = unknown, TInput extends CommandMessage = CommandMessage> extends CapabilityContext<TConfig>, CommandSession {
+export interface CommandContext<TConfig = unknown, TInput extends CommandMessage = CommandMessage, TAdapter extends string | undefined = undefined> extends CapabilityContext<TConfig>, CommandSession {
     readonly args: readonly string[];
     readonly params: Readonly<Record<string, CommandParameterValue>>;
     /** Structured arguments left after the command pattern was consumed. */
@@ -169,16 +176,22 @@ export interface CommandContext<TConfig = unknown, TInput extends CommandMessage
      * Host / `CommandIndex.execute` 等无消息路径可能为 `undefined`。
      */
     readonly input?: TInput;
+    /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
+    readonly $client: AdapterClient<TAdapter>;
     /**
      * 对话式交互输入。IM 派发时自动注入；无消息来源时为 `undefined`。
      */
     /** Canonical user-facing input/confirmation/selection module. */
     readonly interaction?: UserInteraction;
 }
-export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage> {
+export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage, TAdapter extends string | undefined = string | undefined> {
+    /** @internal Runtime feature brand. */
     readonly $feature: typeof commandBrand;
+    /** @internal Convention-derived parameter metadata. */
     readonly $parameter?: CommandParameterDefinition;
     readonly description?: string;
+    /** Restrict this command to one adapter and infer `context.$client`. */
+    readonly adapter?: TAdapter;
     /**
      * Next.js 风格参数声明：动态段文件名（`[name]` 等）的形态配合这里的
      * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
@@ -199,29 +212,39 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
      * 可打破 owner 命名空间。
      */
     readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>>;
-    execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
+    execute(context: CommandContext<TConfig, TInput, TAdapter>): TResult | Promise<TResult>;
 }
 declare module '@zhin.js/plugin-runtime' {
     interface PluginSetupContext<TConfig = unknown> {
-        addCommand<TResult = unknown, TInput extends CommandMessage = CommandMessage>(localName: string, definition: CommandDefinition<TConfig, TResult, TInput>): void;
+        addCommand<TResult = unknown, TInput extends CommandMessage = CommandMessage, TAdapter extends string | undefined = undefined>(localName: string, definition: CommandDefinition<TConfig, TResult, TInput, TAdapter>): void;
     }
 }
 /**
  * 定义一个命令模块（`commands/` 约定目录下默认导出）。
  * @public 用户侧创作面，承诺 semver（见 docs/contributing/public-api-surface.md）。
  */
-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>>;
+type CommandAuthoringDefinition<TConfig, TResult, TInput extends CommandMessage> = Omit<CommandDefinition<TConfig, TResult, TInput, undefined>, '$feature' | '$parameter'> | {
+    [TAdapter in RegisteredAdapterName]: Omit<CommandDefinition<TConfig, TResult, TInput, TAdapter>, '$feature' | '$parameter'> & {
+        readonly adapter: TAdapter;
+    };
+}[RegisteredAdapterName];
+export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput>): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
+/** @internal Convention-loader assembly helper. */
+export declare function bindCommandParameter<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined>(definition: CommandDefinition<TConfig, TResult, TInput, TAdapter>, parameter: CommandParameterDefinition | undefined): Readonly<CommandDefinition<TConfig, TResult, TInput, TAdapter>>;
+/** @internal Runtime validation for convention-discovered modules. */
 export declare function parseCommandDefinition(value: unknown): CommandDefinition;
 /**
  * 将动态参数值（可能包含函数）批量解析为静态值。
  * 函数值接收从 `source`（通常是 IM Runtime `Message`）解析出的 {@link CommandSession}。
+ * @internal Command projection helper.
  */
 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>[], interaction?: UserInteraction): CommandContext;
+/** @internal Command dispatcher assembly helper. */
+export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown, segments?: readonly Readonly<CommandSegment>[], interaction?: UserInteraction, adapter?: string): CommandContext;
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
  * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。
+ * @internal Command dispatcher projection helper.
  */
 export declare function resolveCommandSession(input: unknown): CommandSession;
 export {};

package/lib/definition.js

@@ -1,6 +1,7 @@
-import { createCapabilityContext, } from '@zhin.js/feature-kit';
+import { createCapabilityContext, readOperationClient, } from '@zhin.js/feature-kit';
 import { assertPermitSyntax } from '@zhin.js/permission';
 const commandBrand = 'zhin.command/1';
+/** @internal Runtime validator lookup. */
 export const commandParameterTypes = new Set([
     'string',
     'number',
@@ -17,14 +18,11 @@ export const commandParameterTypes = new Set([
     'dice',
     'rps',
 ]);
-/**
- * 定义一个命令模块（`commands/` 约定目录下默认导出）。
- * @public 用户侧创作面，承诺 semver（见 docs/contributing/public-api-surface.md）。
- */
 export function defineCommand(definition) {
     if (typeof definition.execute !== 'function') {
         throw new TypeError('Command execute must be a function');
     }
+    validateAdapterName(definition.adapter);
     if (definition.params !== undefined) {
         if (!definition.params || typeof definition.params !== 'object') {
             throw new TypeError('Command params must be a Record<string, CommandParamSchema>');
@@ -41,6 +39,11 @@ export function defineCommand(definition) {
     validateCommandShortcutShape(definition.shortcut);
     return Object.freeze({ $feature: commandBrand, ...definition });
 }
+function validateAdapterName(adapter) {
+    if (adapter !== undefined && (typeof adapter !== 'string' || adapter.trim() === '')) {
+        throw new TypeError('Command adapter must be a non-empty string');
+    }
+}
 function validateCommandAlias(alias) {
     if (alias === undefined)
         return;
@@ -85,11 +88,13 @@ function validateCommandShortcutShape(shortcut) {
         }
     }
 }
+/** @internal Convention-loader assembly helper. */
 export function bindCommandParameter(definition, parameter) {
     if (!parameter)
         return definition;
     return Object.freeze({ ...definition, $parameter: Object.freeze({ ...parameter }) });
 }
+/** @internal Runtime validation for convention-discovered modules. */
 export function parseCommandDefinition(value) {
     if (!value || typeof value !== 'object') {
         throw new TypeError('Command module must default-export defineCommand(...)');
@@ -98,11 +103,13 @@ export function parseCommandDefinition(value) {
     if (definition.$feature !== commandBrand || typeof definition.execute !== 'function') {
         throw new TypeError('Command module must default-export defineCommand(...)');
     }
+    validateAdapterName(definition.adapter);
     return definition;
 }
 /**
  * 将动态参数值（可能包含函数）批量解析为静态值。
  * 函数值接收从 `source`（通常是 IM Runtime `Message`）解析出的 {@link CommandSession}。
+ * @internal Command projection helper.
  */
 export function resolveDynamicParams(params, source) {
     const session = resolveCommandSession(source);
@@ -112,10 +119,11 @@ export function resolveDynamicParams(params, source) {
     }
     return Object.freeze(resolved);
 }
-export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction) {
+/** @internal Command dispatcher assembly helper. */
+export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction, adapter) {
     const context = createCapabilityContext(snapshot, ownerId);
     const session = resolveCommandSession(input);
-    return Object.freeze({
+    const result = {
         ...context,
         ...session,
         args: Object.freeze([...args]),
@@ -123,11 +131,17 @@ export function createCommandContext(snapshot, ownerId, args, params = Object.fr
         segments: freezeSegments(segments),
         ...(input !== undefined ? { input: input } : {}),
         ...(interaction !== undefined ? { interaction } : {}),
+    };
+    Object.defineProperty(result, '$client', {
+        enumerable: true,
+        get: () => readOperationClient(input, adapter),
     });
+    return Object.freeze(result);
 }
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
  * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。
+ * @internal Command dispatcher projection helper.
  */
 export function resolveCommandSession(input) {
     if (!isCommandMessageLike(input))

package/lib/index.d.ts

@@ -1,4 +1,10 @@
+/**
+ * Command authoring contracts, parameter schemas, and permit helpers.
+ * @module @zhin.js/command
+ */
+/** @internal Runtime command projection. */
 export * from './command-index.js';
+/** @public Command authoring contract and `defineCommand`. */
 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';

package/lib/index.js

@@ -1,4 +1,10 @@
+/**
+ * Command authoring contracts, parameter schemas, and permit helpers.
+ * @module @zhin.js/command
+ */
+/** @internal Runtime command projection. */
 export * from './command-index.js';
+/** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
 export { assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, } from './permit.js';
 export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';

package/lib/provider.d.ts

@@ -4,5 +4,5 @@ export declare const commandFeatureId: import("@zhin.js/plugin-runtime").Feature
 export declare class CommandPathSyntaxError extends TypeError {
     constructor(file: string, detail?: string);
 }
-declare const commandFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<CommandDefinition<unknown, unknown, import("./definition.js").CommandMessage>, CommandIndex>>;
+declare const commandFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<CommandDefinition<unknown, unknown, import("./definition.js").CommandMessage, string | undefined>, CommandIndex>>;
 export default commandFeature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,10 +18,10 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
+    "@zhin.js/feature-kit": "1.0.13",
     "@zhin.js/interaction": "1.0.1",
-    "@zhin.js/permission": "1.0.3",
-    "@zhin.js/feature-kit": "1.0.12",
-    "@zhin.js/plugin-runtime": "1.1.7"
+    "@zhin.js/permission": "1.0.4",
+    "@zhin.js/plugin-runtime": "1.1.8"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -9,6 +9,7 @@ import type {
   RuntimeSnapshot,
 } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
+import { operationClientAdapter } from '@zhin.js/feature-kit';
 import {
   permissionHostToken,
   toPermissionSubject,
@@ -32,6 +33,7 @@ export interface CommandParameterDescriptor extends CommandParameterDefinition {
 export interface CommandDescriptor {
   readonly name: string;
   readonly description?: string;
+  readonly adapter?: string;
   readonly source: string;
   readonly parameters: readonly CommandParameterDescriptor[];
   readonly alias?: readonly string[];
@@ -132,6 +134,7 @@ export class CommandIndex {
       const record: CommandRecord = Object.freeze({
         name,
         description: slot.definition.description,
+        ...(slot.definition.adapter ? { adapter: slot.definition.adapter } : {}),
         source: slot.source,
         parameters: Object.freeze(parameter ? [{
           ...parameter,
@@ -216,6 +219,10 @@ export class CommandIndex {
         match.command.slot.owner,
         args,
         resolveDynamicParams(match.params, undefined),
+        undefined,
+        Object.freeze([]),
+        undefined,
+        match.command.slot.definition.adapter,
       ),
     );
   }
@@ -240,6 +247,9 @@ export class CommandIndex {
     const interaction = interactionFactory?.(source);
     const shortcut = this.#matchShortcut(input);
     if (shortcut) {
+      if (!commandAdapterMatches(shortcut.record, source)) {
+        return Object.freeze({ matched: false });
+      }
       if (!(await this.#permitAllows(shortcut.record, source))) {
         return Object.freeze({ matched: false });
       }
@@ -252,6 +262,7 @@ export class CommandIndex {
           source,
           Object.freeze([]),
           interaction,
+          shortcut.record.slot.definition.adapter,
         ),
       );
       return Object.freeze({
@@ -264,6 +275,9 @@ export class CommandIndex {
 
     const match = this.#match(input, false);
     if (!match) return Object.freeze({ matched: false });
+    if (!commandAdapterMatches(match.command, source)) {
+      return Object.freeze({ matched: false });
+    }
     if (!(await this.#permitAllows(match.command, source))) {
       return Object.freeze({ matched: false });
     }
@@ -277,6 +291,7 @@ export class CommandIndex {
         source,
         match.remaining,
         interaction,
+        match.command.slot.definition.adapter,
       ),
     );
     return Object.freeze({
@@ -750,6 +765,10 @@ function toDescriptor({
   return descriptor;
 }
 
+function commandAdapterMatches(record: CommandRecord, source: unknown): boolean {
+  return !record.adapter || operationClientAdapter(source) === record.adapter;
+}
+
 export class CommandParameterValueError extends TypeError {
   constructor(name: string, type: CommandParameterType, value: string) {
     super(`Invalid value for Command parameter ${name}:${type}: ${value}`);

package/src/definition.ts

@@ -1,6 +1,13 @@
+/**
+ * Command authoring API consumed from `zhin.js/command`.
+ * @module zhin.js/command
+ */
 import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import {
   createCapabilityContext,
+  readOperationClient,
+  type AdapterClient,
+  type RegisteredAdapterName,
   type CapabilityContext,
 } from '@zhin.js/feature-kit';
 import { assertPermitSyntax } from '@zhin.js/permission';
@@ -54,6 +61,7 @@ export type CommandDynamicValue =
   | CommandParameterValue
   | ((session: CommandSession) => CommandParameterValue);
 
+/** @internal Runtime validator lookup. */
 export const commandParameterTypes: ReadonlySet<CommandParameterType> = new Set([
   'string',
   'number',
@@ -148,6 +156,8 @@ export interface CommandMessage {
   readonly sender?: { readonly id: string; readonly name?: string; readonly roles?: readonly string[] };
   readonly id?: string;
   readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly clientAdapter?: string;
+  readonly $client?: unknown;
   /** 若上游已结构化，优先采用。 */
   readonly scene?: CommandScene;
   // 方法式声明（而非属性式函数类型）：方法参数双变，runtime `Message` 的
@@ -177,7 +187,7 @@ export interface CommandMessage {
 
 /**
  * IM 入站快捷字段。
- * 有 `CommandMessage` 来源时由 {@link resolveCommandSession} 填充；
+ * 有 `CommandMessage` 来源时由 Runtime 从消息结构填充；
  * `CommandIndex.execute(name)` 等无消息路径下为 `undefined`。
  */
 export interface CommandSession {
@@ -212,6 +222,7 @@ export interface CommandSession {
 export interface CommandContext<
   TConfig = unknown,
   TInput extends CommandMessage = CommandMessage,
+  TAdapter extends string | undefined = undefined,
 > extends CapabilityContext<TConfig>, CommandSession {
   readonly args: readonly string[];
   readonly params: Readonly<Record<string, CommandParameterValue>>;
@@ -222,6 +233,8 @@ export interface CommandContext<
    * Host / `CommandIndex.execute` 等无消息路径可能为 `undefined`。
    */
   readonly input?: TInput;
+  /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
+  readonly $client: AdapterClient<TAdapter>;
   /**
    * 对话式交互输入。IM 派发时自动注入；无消息来源时为 `undefined`。
    */
@@ -233,10 +246,15 @@ export interface CommandDefinition<
   TConfig = unknown,
   TResult = unknown,
   TInput extends CommandMessage = CommandMessage,
+  TAdapter extends string | undefined = string | undefined,
 > {
+  /** @internal Runtime feature brand. */
   readonly $feature: typeof commandBrand;
+  /** @internal Convention-derived parameter metadata. */
   readonly $parameter?: CommandParameterDefinition;
   readonly description?: string;
+  /** Restrict this command to one adapter and infer `context.$client`. */
+  readonly adapter?: TAdapter;
   /**
    * Next.js 风格参数声明：动态段文件名（`[name]` 等）的形态配合这里的
    * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
@@ -257,14 +275,18 @@ export interface CommandDefinition<
    * 可打破 owner 命名空间。
    */
   readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>>;
-  execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
+  execute(context: CommandContext<TConfig, TInput, TAdapter>): TResult | Promise<TResult>;
 }
 
 declare module '@zhin.js/plugin-runtime' {
   interface PluginSetupContext<TConfig = unknown> {
-    addCommand<TResult = unknown, TInput extends CommandMessage = CommandMessage>(
+    addCommand<
+      TResult = unknown,
+      TInput extends CommandMessage = CommandMessage,
+      TAdapter extends string | undefined = undefined,
+    >(
       localName: string,
-      definition: CommandDefinition<TConfig, TResult, TInput>,
+      definition: CommandDefinition<TConfig, TResult, TInput, TAdapter>,
     ): void;
   }
 }
@@ -273,16 +295,30 @@ declare module '@zhin.js/plugin-runtime' {
  * 定义一个命令模块（`commands/` 约定目录下默认导出）。
  * @public 用户侧创作面，承诺 semver（见 docs/contributing/public-api-surface.md）。
  */
+type CommandAuthoringDefinition<
+  TConfig,
+  TResult,
+  TInput extends CommandMessage,
+> =
+  | Omit<CommandDefinition<TConfig, TResult, TInput, undefined>, '$feature' | '$parameter'>
+  | {
+      [TAdapter in RegisteredAdapterName]: Omit<
+        CommandDefinition<TConfig, TResult, TInput, TAdapter>,
+        '$feature' | '$parameter'
+      > & { readonly adapter: TAdapter }
+    }[RegisteredAdapterName];
+
 export function defineCommand<
   TConfig = unknown,
   TResult = unknown,
   TInput extends CommandMessage = CommandMessage,
 >(
-  definition: Omit<CommandDefinition<TConfig, TResult, TInput>, '$feature' | '$parameter'>,
-): Readonly<CommandDefinition<TConfig, TResult, TInput>> {
+  definition: CommandAuthoringDefinition<TConfig, TResult, TInput>,
+): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>> {
   if (typeof definition.execute !== 'function') {
     throw new TypeError('Command execute must be a function');
   }
+  validateAdapterName(definition.adapter);
   if (definition.params !== undefined) {
     if (!definition.params || typeof definition.params !== 'object') {
       throw new TypeError('Command params must be a Record<string, CommandParamSchema>');
@@ -297,7 +333,15 @@ export function defineCommand<
   validateCommandAlias(definition.alias);
   validateCommandPermit(definition.permit);
   validateCommandShortcutShape(definition.shortcut);
-  return Object.freeze({ $feature: commandBrand, ...definition });
+  return Object.freeze({ $feature: commandBrand, ...definition }) as Readonly<
+    CommandDefinition<TConfig, TResult, TInput, string | undefined>
+  >;
+}
+
+function validateAdapterName(adapter: string | undefined): void {
+  if (adapter !== undefined && (typeof adapter !== 'string' || adapter.trim() === '')) {
+    throw new TypeError('Command adapter must be a non-empty string');
+  }
 }
 
 function validateCommandAlias(alias: readonly string[] | undefined): void {
@@ -346,18 +390,21 @@ function validateCommandShortcutShape(
   }
 }
 
+/** @internal Convention-loader assembly helper. */
 export function bindCommandParameter<
   TConfig,
   TResult,
   TInput extends CommandMessage,
+  TAdapter extends string | undefined,
 >(
-  definition: CommandDefinition<TConfig, TResult, TInput>,
+  definition: CommandDefinition<TConfig, TResult, TInput, TAdapter>,
   parameter: CommandParameterDefinition | undefined,
-): Readonly<CommandDefinition<TConfig, TResult, TInput>> {
+): Readonly<CommandDefinition<TConfig, TResult, TInput, TAdapter>> {
   if (!parameter) return definition;
   return Object.freeze({ ...definition, $parameter: Object.freeze({ ...parameter }) });
 }
 
+/** @internal Runtime validation for convention-discovered modules. */
 export function parseCommandDefinition(value: unknown): CommandDefinition {
   if (!value || typeof value !== 'object') {
     throw new TypeError('Command module must default-export defineCommand(...)');
@@ -366,12 +413,14 @@ export function parseCommandDefinition(value: unknown): CommandDefinition {
   if (definition.$feature !== commandBrand || typeof definition.execute !== 'function') {
     throw new TypeError('Command module must default-export defineCommand(...)');
   }
+  validateAdapterName(definition.adapter);
   return definition as CommandDefinition;
 }
 
 /**
  * 将动态参数值（可能包含函数）批量解析为静态值。
  * 函数值接收从 `source`（通常是 IM Runtime `Message`）解析出的 {@link CommandSession}。
+ * @internal Command projection helper.
  */
 export function resolveDynamicParams(
   params: Readonly<Record<string, CommandDynamicValue>>,
@@ -385,6 +434,7 @@ export function resolveDynamicParams(
   return Object.freeze(resolved);
 }
 
+/** @internal Command dispatcher assembly helper. */
 export function createCommandContext(
   snapshot: RuntimeSnapshot,
   ownerId: PluginId,
@@ -393,10 +443,11 @@ export function createCommandContext(
   input: unknown = undefined,
   segments: readonly Readonly<CommandSegment>[] = Object.freeze([]),
   interaction?: UserInteraction,
+  adapter?: string,
 ): CommandContext {
   const context = createCapabilityContext(snapshot, ownerId);
   const session = resolveCommandSession(input);
-  return Object.freeze({
+  const result = {
     ...context,
     ...session,
     args: Object.freeze([...args]),
@@ -404,12 +455,18 @@ export function createCommandContext(
     segments: freezeSegments(segments),
     ...(input !== undefined ? { input: input as CommandMessage } : {}),
     ...(interaction !== undefined ? { interaction } : {}),
+  } as CommandContext;
+  Object.defineProperty(result, '$client', {
+    enumerable: true,
+    get: () => readOperationClient(input, adapter),
   });
+  return Object.freeze(result);
 }
 
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
  * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。
+ * @internal Command dispatcher projection helper.
  */
 export function resolveCommandSession(input: unknown): CommandSession {
   if (!isCommandMessageLike(input)) return Object.freeze({});

package/src/index.ts

@@ -1,4 +1,10 @@
+/**
+ * Command authoring contracts, parameter schemas, and permit helpers.
+ * @module @zhin.js/command
+ */
+/** @internal Runtime command projection. */
 export * from './command-index.js';
+/** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
 export {
   assertBuiltinPermits,