@zhin.js/command 1.0.13 → 1.0.15

package/README.md

@@ -11,7 +11,7 @@ Zhin Plugin Runtime 的约定式 Command Feature。它发现 `commands/**/*.ts(x
 ```ts
 // commands/gh/issue/list.ts -> gh issue list
 // commands/赞我.ts -> 赞我
-import { defineCommand } from '@zhin.js/command';
+import { defineCommand } from 'zhin.js/command';
 
 export default defineCommand({
   description: 'List GitHub issues',
@@ -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,5 +1,6 @@
 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;
 }
@@ -31,7 +32,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,6 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
+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',
@@ -119,7 +118,7 @@ export class CommandIndex {
         // Host / 无 session：跳过 permit；无 source 时函数默认值得到空 session。
         return match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, resolveDynamicParams(match.params, undefined)));
     }
-    async dispatch(input, source = undefined, promptFactory, commandPrefix = '') {
+    async dispatch(input, source = undefined, interactionFactory, commandPrefix = '') {
         if (this.#menu) {
             const menuValue = this.#dispatchMenu(input, commandPrefix);
             if (menuValue !== undefined) {
@@ -131,13 +130,13 @@ export class CommandIndex {
                 });
             }
         }
-        const prompt = promptFactory?.(source);
+        const interaction = interactionFactory?.(source);
         const shortcut = this.#matchShortcut(input);
         if (shortcut) {
             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));
             return Object.freeze({
                 matched: true,
                 command: shortcut.record.name,
@@ -152,7 +151,7 @@ export class CommandIndex {
             return Object.freeze({ matched: false });
         }
         const args = textArgs(match.remaining);
-        const value = await match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, 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));
         return Object.freeze({
             matched: true,
             command: match.command.name,

package/lib/definition.d.ts

@@ -1,5 +1,6 @@
 import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import { 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;
@@ -143,56 +144,21 @@ 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 {
     readonly args: readonly string[];
     readonly params: Readonly<Record<string, CommandParameterValue>>;
@@ -206,7 +172,8 @@ export interface CommandContext<TConfig = unknown, TInput extends CommandMessage
     /**
      * 对话式交互输入。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> {
     readonly $feature: typeof commandBrand;
@@ -235,7 +202,7 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
     execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
 declare module '@zhin.js/plugin-runtime' {
-    interface PluginSetupContext<TConfig> {
+    interface PluginSetupContext<TConfig = unknown> {
         addCommand<TResult = unknown, TInput extends CommandMessage = CommandMessage>(localName: string, definition: CommandDefinition<TConfig, TResult, TInput>): void;
     }
 }
@@ -251,7 +218,7 @@ export declare function parseCommandDefinition(value: unknown): CommandDefinitio
  * 函数值接收从 `source`（通常是 IM Runtime `Message`）解析出的 {@link CommandSession}。
  */
 export declare function resolveDynamicParams(params: Readonly<Record<string, CommandDynamicValue>>, source: unknown): Readonly<Record<string, CommandParameterValue>>;
-export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown, segments?: readonly Readonly<CommandSegment>[], prompt?: CommandPrompt): CommandContext;
+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;
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
  * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。

package/lib/definition.js

@@ -112,7 +112,7 @@ export function resolveDynamicParams(params, source) {
     }
     return Object.freeze(resolved);
 }
-export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), prompt) {
+export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction) {
     const context = createCapabilityContext(snapshot, ownerId);
     const session = resolveCommandSession(input);
     return Object.freeze({
@@ -122,7 +122,7 @@ export function createCommandContext(snapshot, ownerId, args, params = Object.fr
         params: Object.freeze({ ...params }),
         segments: freezeSegments(segments),
         ...(input !== undefined ? { input: input } : {}),
-        ...(prompt !== undefined ? { prompt } : {}),
+        ...(interaction !== undefined ? { interaction } : {}),
     });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "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.10",
-    "@zhin.js/permission": "1.0.2",
-    "@zhin.js/plugin-runtime": "1.1.6"
+    "@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"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -8,20 +8,22 @@ import type {
   PluginId,
   RuntimeSnapshot,
 } from '@zhin.js/plugin-runtime';
+import type { UserInteractionFactory } from '@zhin.js/interaction';
+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;
@@ -221,7 +223,7 @@ export class CommandIndex {
   async dispatch(
     input: CommandMatchInput,
     source: unknown = undefined,
-    promptFactory?: CommandPromptFactory,
+    interactionFactory?: UserInteractionFactory,
     commandPrefix = '',
   ): Promise<CommandDispatchResult> {
     if (this.#menu) {
@@ -235,7 +237,7 @@ export class CommandIndex {
         });
       }
     }
-    const prompt = promptFactory?.(source);
+    const interaction = interactionFactory?.(source);
     const shortcut = this.#matchShortcut(input);
     if (shortcut) {
       if (!(await this.#permitAllows(shortcut.record, source))) {
@@ -249,7 +251,7 @@ export class CommandIndex {
           resolveDynamicParams(shortcut.params, source),
           source,
           Object.freeze([]),
-          prompt,
+          interaction,
         ),
       );
       return Object.freeze({
@@ -274,7 +276,7 @@ export class CommandIndex {
         resolveDynamicParams(match.params, source),
         source,
         match.remaining,
-        prompt,
+        interaction,
       ),
     );
     return Object.freeze({

package/src/definition.ts

@@ -4,6 +4,7 @@ import {
   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;
 
@@ -193,51 +194,21 @@ 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,
@@ -254,7 +225,8 @@ export interface CommandContext<
   /**
    * 对话式交互输入。IM 派发时自动注入；无消息来源时为 `undefined`。
    */
-  readonly prompt?: CommandPrompt;
+  /** Canonical user-facing input/confirmation/selection module. */
+  readonly interaction?: UserInteraction;
 }
 
 export interface CommandDefinition<
@@ -289,7 +261,7 @@ export interface CommandDefinition<
 }
 
 declare module '@zhin.js/plugin-runtime' {
-  interface PluginSetupContext<TConfig> {
+  interface PluginSetupContext<TConfig = unknown> {
     addCommand<TResult = unknown, TInput extends CommandMessage = CommandMessage>(
       localName: string,
       definition: CommandDefinition<TConfig, TResult, TInput>,
@@ -420,7 +392,7 @@ export function createCommandContext(
   params: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
   input: unknown = undefined,
   segments: readonly Readonly<CommandSegment>[] = Object.freeze([]),
-  prompt?: CommandPrompt,
+  interaction?: UserInteraction,
 ): CommandContext {
   const context = createCapabilityContext(snapshot, ownerId);
   const session = resolveCommandSession(input);
@@ -431,7 +403,7 @@ export function createCommandContext(
     params: Object.freeze({ ...params }),
     segments: freezeSegments(segments),
     ...(input !== undefined ? { input: input as CommandMessage } : {}),
-    ...(prompt !== undefined ? { prompt } : {}),
+    ...(interaction !== undefined ? { interaction } : {}),
   });
 }