@zhin.js/command 1.0.14 → 1.0.16

package/README.md

@@ -44,6 +44,8 @@ commands/search/[...kw].ts    -> search <...kw>   （params: { kw: { type: 'text
 - `adapter` / `endpoint`：适配器实例 id 与 endpoint 名。
 - `scene`：`{ id, type, name? }` 场景对象。
 - `sender`：`{ id, name?, role: string[] }` 发送者对象。
+- `interaction`：可选的 `UserInteraction`。用 `ask()` 获取单个类型化结论，或用
+  `sequence()` 连续收集多个结论；请求可声明 `title`、`description`、`tip` 与校验规则。
 
 可选声明字段：
 

package/lib/command-index.d.ts

@@ -1,11 +1,13 @@
 import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import { type CommandDefinition, type CommandParameterDefinition, type CommandParameterType, type CommandSegment, type CommandPromptFactory } from './definition.js';
+import type { UserInteractionFactory } from '@zhin.js/interaction';
+import { type CommandDefinition, type CommandParameterDefinition, type CommandParameterType, type CommandSegment } from './definition.js';
 export interface CommandParameterDescriptor extends CommandParameterDefinition {
     readonly required: boolean;
 }
 export interface CommandDescriptor {
     readonly name: string;
     readonly description?: string;
+    readonly adapter?: string;
     readonly source: string;
     readonly parameters: readonly CommandParameterDescriptor[];
     readonly alias?: readonly string[];
@@ -31,7 +33,7 @@ export declare class CommandIndex {
     list(): readonly CommandDescriptor[];
     has(name: string): boolean;
     execute(name: string, args?: readonly string[]): Promise<unknown>;
-    dispatch(input: CommandMatchInput, source?: unknown, promptFactory?: CommandPromptFactory, commandPrefix?: string): Promise<CommandDispatchResult>;
+    dispatch(input: CommandMatchInput, source?: unknown, interactionFactory?: UserInteractionFactory, commandPrefix?: string): Promise<CommandDispatchResult>;
 }
 export declare function isCommandIndex(value: unknown): value is CommandIndex;
 export declare class CommandParameterValueError extends TypeError {

package/lib/command-index.js

@@ -1,7 +1,7 @@
 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';
-import { permissionHostToken } from '@zhin.js/permission';
-import { toPermissionSubject } from '@zhin.js/permission';
 const segmentFields = {
     text: 'text',
     mention: 'target',
@@ -49,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,
@@ -117,9 +118,9 @@ 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, promptFactory, commandPrefix = '') {
+    async dispatch(input, source = undefined, interactionFactory, commandPrefix = '') {
         if (this.#menu) {
             const menuValue = this.#dispatchMenu(input, commandPrefix);
             if (menuValue !== undefined) {
@@ -131,13 +132,16 @@ export class CommandIndex {
                 });
             }
         }
-        const prompt = promptFactory?.(source);
+        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([]), prompt));
+            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,
@@ -148,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, prompt));
+        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,
@@ -565,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,10 @@
+/**
+ * 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';
 export type CommandParameterValue = string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null;
@@ -23,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: ... })`）。
@@ -101,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>;
@@ -127,7 +135,7 @@ export interface CommandMessage {
 }
 /**
  * IM 入站快捷字段。
- * 有 `CommandMessage` 来源时由 {@link resolveCommandSession} 填充；
+ * 有 `CommandMessage` 来源时由 Runtime 从消息结构填充；
  * `CommandIndex.execute(name)` 等无消息路径下为 `undefined`。
  */
 export interface CommandSession {
@@ -143,57 +151,22 @@ export interface CommandSession {
     /** 发送者对象（id / name / role[]）。 */
     readonly sender?: CommandSender;
 }
-export interface CommandPromptOptions {
-    readonly timeout?: number;
-    readonly timeoutText?: string;
-    /** Cancel the pending claim when the owning turn aborts. */
-    readonly signal?: AbortSignal;
-}
-export interface CommandPromptListOptions extends CommandPromptOptions {
-    readonly type?: 'text' | 'number' | 'boolean';
-    readonly separator?: string;
-    readonly default?: readonly (string | number | boolean)[];
-}
-export interface CommandPromptPickOptions<V = unknown> extends CommandPromptOptions {
-    readonly options: readonly {
-        readonly label: string;
-        readonly value: V;
-    }[];
-    readonly multiple?: boolean;
-    readonly separator?: string;
-    readonly default?: V | readonly V[];
-}
 /**
  * 命令内对话式交互输入。
  *
- * IM 派发时自动注入（`context.prompt`）；Host / CLI 无消息来源时为 `undefined`。
+ * IM 派发时自动注入（`context.interaction`）；Host / CLI 无消息来源时为 `undefined`。
  *
  * ```ts
  * defineCommand({
  *   execute: async (context) => {
- *     const name = await context.prompt!.text('请输入你的名字');
- *     const age = await context.prompt!.number('请输入你的年龄');
+ *     const name = await context.interaction!.ask({ type: 'text', title: '请输入你的名字' });
+ *     const age = await context.interaction!.ask({ type: 'number', title: '请输入你的年龄' });
  *     return `你好 ${name}，你 ${age} 岁了`;
  *   },
  * });
  * ```
  */
-export interface CommandPrompt {
-    text(tips: string, options?: CommandPromptOptions & {
-        readonly default?: string;
-    }): Promise<string>;
-    number(tips: string, options?: CommandPromptOptions & {
-        readonly default?: number;
-    }): Promise<number>;
-    confirm(tips: string, options?: CommandPromptOptions & {
-        readonly condition?: string;
-        readonly default?: boolean;
-    }): Promise<boolean>;
-    list(tips: string, options?: CommandPromptListOptions): Promise<readonly (string | number | boolean)[]>;
-    pick<V = unknown>(tips: string, options: CommandPromptPickOptions<V>): Promise<V | readonly V[]>;
-}
-export type CommandPromptFactory = (source: unknown) => CommandPrompt | undefined;
-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. */
@@ -203,15 +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`。
      */
-    readonly prompt?: CommandPrompt;
+    /** 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]` 等）的形态配合这里的
      * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
@@ -232,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> {
-        addCommand<TResult = unknown, TInput extends CommandMessage = CommandMessage>(localName: string, definition: CommandDefinition<TConfig, TResult, TInput>): void;
+    interface PluginSetupContext<TConfig = unknown> {
+        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>[], prompt?: CommandPrompt): 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,22 +119,29 @@ export function resolveDynamicParams(params, source) {
     }
     return Object.freeze(resolved);
 }
-export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), prompt) {
+/** @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]),
         params: Object.freeze({ ...params }),
         segments: freezeSegments(segments),
         ...(input !== undefined ? { input: input } : {}),
-        ...(prompt !== undefined ? { prompt } : {}),
+        ...(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.14",
+  "version": "1.0.16",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,9 +18,10 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.0.11",
-    "@zhin.js/permission": "1.0.2",
-    "@zhin.js/plugin-runtime": "1.1.6"
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/interaction": "1.0.1",
+    "@zhin.js/permission": "1.0.4",
+    "@zhin.js/plugin-runtime": "1.1.8"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -8,20 +8,23 @@ import type {
   PluginId,
   RuntimeSnapshot,
 } from '@zhin.js/plugin-runtime';
+import type { UserInteractionFactory } from '@zhin.js/interaction';
+import { operationClientAdapter } from '@zhin.js/feature-kit';
+import {
+  permissionHostToken,
+  toPermissionSubject,
+  type PermissionHost,
+} from '@zhin.js/permission';
 import {
   createCommandContext,
   resolveCommandSession,
   type CommandDefinition,
   type CommandParameterDefinition,
   type CommandParameterType,
-  type CommandParameterValue,
   type CommandSegment,
   type CommandDynamicValue,
-  type CommandPromptFactory,
   resolveDynamicParams,
 } from './definition.js';
-import { permissionHostToken, type PermissionHost } from '@zhin.js/permission';
-import { toPermissionSubject } from '@zhin.js/permission';
 
 export interface CommandParameterDescriptor extends CommandParameterDefinition {
   readonly required: boolean;
@@ -30,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[];
@@ -130,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,
@@ -214,6 +219,10 @@ export class CommandIndex {
         match.command.slot.owner,
         args,
         resolveDynamicParams(match.params, undefined),
+        undefined,
+        Object.freeze([]),
+        undefined,
+        match.command.slot.definition.adapter,
       ),
     );
   }
@@ -221,7 +230,7 @@ export class CommandIndex {
   async dispatch(
     input: CommandMatchInput,
     source: unknown = undefined,
-    promptFactory?: CommandPromptFactory,
+    interactionFactory?: UserInteractionFactory,
     commandPrefix = '',
   ): Promise<CommandDispatchResult> {
     if (this.#menu) {
@@ -235,9 +244,12 @@ export class CommandIndex {
         });
       }
     }
-    const prompt = promptFactory?.(source);
+    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 });
       }
@@ -249,7 +261,8 @@ export class CommandIndex {
           resolveDynamicParams(shortcut.params, source),
           source,
           Object.freeze([]),
-          prompt,
+          interaction,
+          shortcut.record.slot.definition.adapter,
         ),
       );
       return Object.freeze({
@@ -262,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 });
     }
@@ -274,7 +290,8 @@ export class CommandIndex {
         resolveDynamicParams(match.params, source),
         source,
         match.remaining,
-        prompt,
+        interaction,
+        match.command.slot.definition.adapter,
       ),
     );
     return Object.freeze({
@@ -748,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,9 +1,17 @@
+/**
+ * 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';
+import type { UserInteraction } from '@zhin.js/interaction';
 
 const commandBrand = 'zhin.command/1' as const;
 
@@ -53,6 +61,7 @@ export type CommandDynamicValue =
   | CommandParameterValue
   | ((session: CommandSession) => CommandParameterValue);
 
+/** @internal Runtime validator lookup. */
 export const commandParameterTypes: ReadonlySet<CommandParameterType> = new Set([
   'string',
   'number',
@@ -147,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` 的
@@ -176,7 +187,7 @@ export interface CommandMessage {
 
 /**
  * IM 入站快捷字段。
- * 有 `CommandMessage` 来源时由 {@link resolveCommandSession} 填充；
+ * 有 `CommandMessage` 来源时由 Runtime 从消息结构填充；
  * `CommandIndex.execute(name)` 等无消息路径下为 `undefined`。
  */
 export interface CommandSession {
@@ -193,54 +204,25 @@ export interface CommandSession {
   readonly sender?: CommandSender;
 }
 
-export interface CommandPromptOptions {
-  readonly timeout?: number;
-  readonly timeoutText?: string;
-  /** Cancel the pending claim when the owning turn aborts. */
-  readonly signal?: AbortSignal;
-}
-
-export interface CommandPromptListOptions extends CommandPromptOptions {
-  readonly type?: 'text' | 'number' | 'boolean';
-  readonly separator?: string;
-  readonly default?: readonly (string | number | boolean)[];
-}
-
-export interface CommandPromptPickOptions<V = unknown> extends CommandPromptOptions {
-  readonly options: readonly { readonly label: string; readonly value: V }[];
-  readonly multiple?: boolean;
-  readonly separator?: string;
-  readonly default?: V | readonly V[];
-}
-
 /**
  * 命令内对话式交互输入。
  *
- * IM 派发时自动注入（`context.prompt`）；Host / CLI 无消息来源时为 `undefined`。
+ * IM 派发时自动注入（`context.interaction`）；Host / CLI 无消息来源时为 `undefined`。
  *
  * ```ts
  * defineCommand({
  *   execute: async (context) => {
- *     const name = await context.prompt!.text('请输入你的名字');
- *     const age = await context.prompt!.number('请输入你的年龄');
+ *     const name = await context.interaction!.ask({ type: 'text', title: '请输入你的名字' });
+ *     const age = await context.interaction!.ask({ type: 'number', title: '请输入你的年龄' });
  *     return `你好 ${name}，你 ${age} 岁了`;
  *   },
  * });
  * ```
  */
-export interface CommandPrompt {
-  text(tips: string, options?: CommandPromptOptions & { readonly default?: string }): Promise<string>;
-  number(tips: string, options?: CommandPromptOptions & { readonly default?: number }): Promise<number>;
-  confirm(tips: string, options?: CommandPromptOptions & { readonly condition?: string; readonly default?: boolean }): Promise<boolean>;
-  list(tips: string, options?: CommandPromptListOptions): Promise<readonly (string | number | boolean)[]>;
-  pick<V = unknown>(tips: string, options: CommandPromptPickOptions<V>): Promise<V | readonly V[]>;
-}
-
-export type CommandPromptFactory = (source: unknown) => CommandPrompt | undefined;
-
 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>>;
@@ -251,20 +233,28 @@ 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`。
    */
-  readonly prompt?: CommandPrompt;
+  /** Canonical user-facing input/confirmation/selection module. */
+  readonly interaction?: UserInteraction;
 }
 
 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]` 等）的形态配合这里的
    * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
@@ -285,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> {
-    addCommand<TResult = unknown, TInput extends CommandMessage = CommandMessage>(
+  interface PluginSetupContext<TConfig = unknown> {
+    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;
   }
 }
@@ -301,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>');
@@ -325,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 {
@@ -374,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(...)');
@@ -394,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>>,
@@ -413,6 +434,7 @@ export function resolveDynamicParams(
   return Object.freeze(resolved);
 }
 
+/** @internal Command dispatcher assembly helper. */
 export function createCommandContext(
   snapshot: RuntimeSnapshot,
   ownerId: PluginId,
@@ -420,24 +442,31 @@ export function createCommandContext(
   params: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
   input: unknown = undefined,
   segments: readonly Readonly<CommandSegment>[] = Object.freeze([]),
-  prompt?: CommandPrompt,
+  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]),
     params: Object.freeze({ ...params }),
     segments: freezeSegments(segments),
     ...(input !== undefined ? { input: input as CommandMessage } : {}),
-    ...(prompt !== undefined ? { prompt } : {}),
+    ...(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,