@zhin.js/command 1.0.5 → 1.0.7

package/README.md

@@ -15,16 +15,17 @@ export default defineCommand({
 });
 ```
 
-最后一个文件名可以声明参数：
+最后一个文件名可以用 Next.js 风格方括号声明参数形态，类型与默认值在 `defineCommand({ params })` 中声明（`type` 必填，`default` 可选且有默认值时文件名必须用双方括号）：
 
 ```text
-commands/gh/pr/[title:string=defaultTitle].ts -> gh pr [title]
-commands/upload/[asset:image].ts             -> upload <asset>
+commands/gh/pr/[[title]].ts   -> gh pr [title]    （params: { title: { type: 'string', default: 'defaultTitle' } }）
+commands/upload/[asset].ts    -> upload <asset>   （params: { asset: { type: 'image' } }）
+commands/search/[...kw].ts    -> search <...kw>   （params: { kw: { type: 'text' } }，运行时 params.kw 为数组；元素粒度随类型：text 逐消息段，word/string 逐词，number/boolean 逐词转换）
 ```
 
 文本类型包括 `string`、`word`、`text`、`number`、`integer`、`float`、`boolean`；结构化
 类型包括 `mention`、`image`、`face`、`reply`、`forward`、`dice`、`rps`。结构化类型
-直接从对应 segment 取值，不能声明文件名默认值。
+直接从对应 segment 取值，不能声明默认值。
 
 `execute()` 收到冻结的 `CommandContext`：
 

package/lib/command-index.js

@@ -31,7 +31,7 @@ export class CommandIndex {
                 source: slot.source,
                 parameters: Object.freeze(parameter ? [{
                         ...parameter,
-                        required: parameter.defaultValue === undefined,
+                        required: isRequiredParameter(parameter),
                     }] : []),
                 slot,
                 segments: Object.freeze(segments),
@@ -100,12 +100,29 @@ export class CommandIndex {
             const result = command.matcher.match(asMatcherSegments(segments));
             if (!result || !hasCommandBoundary(result.remaining))
                 continue;
+            const parameter = command.parameter;
+            const params = { ...result.params };
+            if (parameter?.rest) {
+                const raw = result.params[parameter.name];
+                const coerced = coerceRestValues(parameter, Array.isArray(raw) ? raw : []);
+                // 必需 `[...name]` 捕获所有：零元素视为不匹配；标量逐词转换失败同样不匹配。
+                if (!coerced || (isRequiredParameter(parameter) && coerced.length === 0))
+                    continue;
+                params[parameter.name] = coerced;
+            }
             const remaining = normalizeSegments(result.remaining);
             if (exact && remaining.length > 0)
                 continue;
+            // `[[name]]` 无 default 且未命中时，matcher 对 text 回退 ''、其他类型回退 null；
+            // 按契约（省略 default 时未匹配为 undefined）删除该键。
+            if (parameter && !parameter.rest && parameter.optional === true
+                && parameter.defaultValue === undefined
+                && (params[parameter.name] === '' || params[parameter.name] === null)) {
+                delete params[parameter.name];
+            }
             return {
                 command,
-                params: Object.freeze({ ...result.params }),
+                params: Object.freeze(params),
                 remaining,
             };
         }
@@ -115,7 +132,7 @@ export class CommandIndex {
         const words = splitCommand(name);
         for (const command of this.#commands) {
             const parameter = command.parameter;
-            if (!parameter)
+            if (!parameter || parameter.rest)
                 continue;
             const parameterIndex = command.segments.findIndex((segment) => segment.startsWith('$'));
             if (words.length !== command.segments.length)
@@ -154,15 +171,26 @@ function assertParameterSegment(segments, parameter, source) {
         && dynamicSegments[0] === `$${parameter.name}`
         && segments.at(-1) === dynamicSegments[0])
         return;
-    throw new Error(`Broken dynamic Command identity for ${source}`);
+    const dynamic = dynamicSegments[0] ?? (parameter ? `$${parameter.name}` : '$?');
+    throw new Error(`Invalid Command path for ${source}: the dynamic segment "${dynamic}" must be the only dynamic `
+        + `segment and come after a static segment (child plugin commands are prefixed by the plugin `
+        + `path, so a dynamic first segment is never reachable). `
+        + (parameter
+            ? `Hint: move the file under a static directory, e.g. "commands/add/[${parameter.name}:${parameter.type}].ts".`
+            : 'Hint: put the file under a static directory, e.g. "commands/add/<file>.ts".'));
+}
+function isRequiredParameter(parameter) {
+    return parameter.optional === true ? false : parameter.defaultValue === undefined;
 }
 function displayName(segments, parameter) {
     return segments.map((segment) => {
         if (!segment.startsWith('$'))
             return segment;
-        return parameter?.defaultValue === undefined
-            ? `<${segment.slice(1)}>`
-            : `[${segment.slice(1)}]`;
+        const label = segment.slice(1);
+        const required = !parameter || isRequiredParameter(parameter);
+        if (parameter?.rest)
+            return required ? `<...${label}>` : `[...${label}]`;
+        return required ? `<${label}>` : `[${label}]`;
     }).join(' ');
 }
 function matcherPattern(segments, parameter) {
@@ -172,26 +200,80 @@ function matcherPattern(segments, parameter) {
         if (!parameter)
             throw new Error(`Missing Command parameter metadata: ${segment}`);
         const type = matcherType(parameter.type);
+        // rest：结构化类型按消息段收集；标量类型先按 text 段收集，再在 #match 里逐词切分转换。
+        if (parameter.rest) {
+            return `[...${parameter.name}:${isStructuredRestType(parameter.type) ? type : 'text'}]`;
+        }
+        if (isRequiredParameter(parameter))
+            return `<${parameter.name}:${type}>`;
         return parameter.defaultValue === undefined
-            ? `<${parameter.name}:${type}>`
+            ? `[${parameter.name}:${type}]`
             : `[${parameter.name}:${type}=${String(parameter.defaultValue)}]`;
     }).join(' ');
 }
 function matcherType(type) {
     return type === 'string' ? 'word' : type;
 }
+/** rest 参数中按消息段收集（matcher 原生行为）的结构化类型。 */
+function isStructuredRestType(type) {
+    return type === 'mention'
+        || type === 'image'
+        || type === 'face'
+        || type === 'reply'
+        || type === 'forward'
+        || type === 'dice'
+        || type === 'rps';
+}
+/**
+ * 捕获所有参数的取值粒度由类型决定：
+ * - `text` / 结构化类型：逐消息段（matcher 原生结果）；
+ * - `word` / `string`：逐词（空白切分）；
+ * - `number` / `integer` / `float` / `boolean`：逐词切分后逐个转换，任一失败返回 undefined（不匹配）。
+ */
+function coerceRestValues(parameter, values) {
+    const type = parameter.type;
+    if (type === 'text' || isStructuredRestType(type)) {
+        // 逐消息段，保持 matcher 原生提取值（text 为 string，结构化类型可能是 number 等）。
+        return values;
+    }
+    const words = values.flatMap((value) => typeof value === 'string' ? value.split(/\s+/u).filter(Boolean) : []);
+    if (type === 'string' || type === 'word')
+        return words;
+    if (type === 'number' || type === 'integer' || type === 'float') {
+        const numbers = [];
+        for (const [index, word] of words.entries()) {
+            const number = Number(word);
+            if (!Number.isFinite(number)
+                || (type === 'integer' && !Number.isInteger(number))
+                || (type === 'float' && !word.includes('.')))
+                return undefined;
+            numbers[index] = number;
+        }
+        return numbers;
+    }
+    if (type === 'boolean') {
+        if (!words.every((word) => word === 'true' || word === 'false'))
+            return undefined;
+        return words.map((word) => word === 'true');
+    }
+    return undefined;
+}
 function routeShape(segments) {
     return segments.map((segment) => segment.startsWith('$') ? '$' : segment).join(' ');
 }
 function compareCommands(left, right) {
-    const leftDynamic = left.parameter ? 1 : 0;
-    const rightDynamic = right.parameter ? 1 : 0;
-    return leftDynamic - rightDynamic
+    return dynamicWeight(left) - dynamicWeight(right)
         || staticSegmentCount(right.segments) - staticSegmentCount(left.segments)
         || right.segments.length - left.segments.length
         || right.name.length - left.name.length
         || left.name.localeCompare(right.name);
 }
+/** 静态 < 单参数 < 捕获所有：更具体的形状优先匹配。 */
+function dynamicWeight(command) {
+    if (!command.parameter)
+        return 0;
+    return command.parameter.rest ? 2 : 1;
+}
 function staticSegmentCount(segments) {
     return segments.filter((segment) => !segment.startsWith('$')).length;
 }

package/lib/definition.d.ts

@@ -2,7 +2,18 @@ import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import { type CapabilityContext } from '@zhin.js/feature-kit';
 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 | Readonly<Record<string, unknown>> | null;
+export type CommandParameterValue = string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null;
+export declare const commandParameterTypes: ReadonlySet<CommandParameterType>;
+/**
+ * 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 | {
@@ -14,6 +25,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;
 }
 /** 场景：群 / 私聊 / 频道等。 */
 export interface CommandScene {
@@ -30,6 +46,24 @@ export interface CommandSender {
     readonly name?: string;
     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: 'group' | 'channel';
+        readonly id: string;
+    }>;
+    readonly threadId?: string;
+}
 /**
  * 命令侧入站消息契约。
  *
@@ -37,8 +71,7 @@ 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;
@@ -82,6 +115,11 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
     readonly $feature: typeof commandBrand;
     readonly $parameter?: CommandParameterDefinition;
     readonly description?: string;
+    /**
+     * Next.js 风格参数声明：动态段文件名（`[name]` 等）的形态配合这里的
+     * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
+     */
+    readonly params?: Readonly<Record<string, CommandParamSchema>>;
     execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
 declare module '@zhin.js/plugin-runtime' {

package/lib/definition.js

@@ -1,5 +1,21 @@
 import { createCapabilityContext, } from '@zhin.js/feature-kit';
 const commandBrand = 'zhin.command/1';
+export const commandParameterTypes = new Set([
+    'string',
+    'number',
+    'integer',
+    'float',
+    'boolean',
+    'word',
+    'text',
+    'mention',
+    'image',
+    'face',
+    'reply',
+    'forward',
+    'dice',
+    'rps',
+]);
 /**
  * 定义一个命令模块（`commands/` 约定目录下默认导出）。
  * @public 用户侧创作面，承诺 semver（见 docs/contributing/public-api-surface.md）。
@@ -8,6 +24,17 @@ export function defineCommand(definition) {
     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.type)) {
+                throw new TypeError(`Command params.${name} requires a valid type`);
+            }
+        }
+    }
     return Object.freeze({ $feature: commandBrand, ...definition });
 }
 export function bindCommandParameter(definition, parameter) {
@@ -47,7 +74,7 @@ export function resolveCommandSession(input) {
     const metadata = input.metadata && typeof input.metadata === 'object'
         ? input.metadata
         : undefined;
-    const adapter = input.adapter.split('\0')[0] || undefined;
+    const adapter = input.conversation.endpoint.adapter || undefined;
     const endpoint = typeof metadata?.endpoint === 'string' && metadata.endpoint
         ? metadata.endpoint
         : undefined;
@@ -64,8 +91,8 @@ function isCommandMessageLike(input) {
     if (!input || typeof input !== 'object')
         return false;
     const value = input;
-    return typeof value.adapter === 'string'
-        && typeof value.target === 'string'
+    return !!value.conversation
+        && typeof value.conversation === 'object'
         && typeof value.content === 'string';
 }
 function resolveScene(input, metadata) {
@@ -76,12 +103,12 @@ function resolveScene(input, metadata) {
             ...(input.scene.name !== undefined ? { name: input.scene.name } : {}),
         });
     }
-    const parsed = parseTarget(input.target);
+    const conversation = input.conversation;
     const type = (typeof metadata?.channelType === 'string' && metadata.channelType)
         || (typeof metadata?.type === 'string' && metadata.type)
-        || parsed?.type;
+        || conversation.kind;
     const id = (typeof metadata?.channelId === 'string' && metadata.channelId)
-        || parsed?.id;
+        || conversation.id;
     if (!type || !id)
         return undefined;
     const name = firstString(metadata?.channelName, metadata?.group_name, metadata?.groupName, metadata?.sceneName);
@@ -136,24 +163,6 @@ function resolveRoles(metadata) {
         roles.push('user');
     return Object.freeze(roles);
 }
-function parseTarget(target) {
-    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) {
     if (!value || typeof value !== 'object')
         return false;

package/lib/provider.d.ts

@@ -1,7 +1,8 @@
 import { CommandIndex } from './command-index.js';
+import { type CommandDefinition } from './definition.js';
 export declare const commandFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
 export declare class CommandPathSyntaxError extends TypeError {
     constructor(file: string, detail?: string);
 }
-declare const commandFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").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>, CommandIndex>>;
 export default commandFeature;

package/lib/provider.js

@@ -14,7 +14,7 @@ const commandFiles = {
         const module = await context.host.loadModule(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));
     },
 };
 async function* discoverCommandDirectory(context, directory, ancestors) {
@@ -59,45 +59,53 @@ async function* discoverCommandDirectory(context, directory, ancestors) {
 function isCommandSegment(value) {
     return /^[a-z0-9][a-z0-9-]*$/.test(value);
 }
-const dynamicCommandFilePattern = /^\[([a-z][a-zA-Z0-9]*):([a-z][a-z0-9-]*)(?:=([^\]]*))?\]\.(?:tsx?|[cm]?js)$/;
-const commandParameterTypes = new Set([
-    'string',
-    'number',
-    'integer',
-    'float',
-    'boolean',
-    'word',
-    'text',
-    'mention',
-    'image',
-    'face',
-    'reply',
-    'forward',
-    'dice',
-    'rps',
-]);
+const dynamicCommandFilePatterns = [
+    { 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 },
+];
 function parseCommandFile(value) {
     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)) {
-            throw new CommandPathSyntaxError(value, `unsupported parameter type: ${rawType ?? ''}`);
-        }
-        const type = rawType;
+    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);
     }
     return undefined;
 }
+/** 把文件名形态与 `definition.params` 合并成完整参数定义。 */
+function resolveParameter(definition, file, source) {
+    const hint = file?.parameter;
+    if (!hint)
+        return undefined;
+    const schema = definition.params?.[hint.name];
+    if (!schema) {
+        throw new CommandPathSyntaxError(source, `missing params.${hint.name} declaration in defineCommand({ params })`);
+    }
+    if (!hint.optional && schema.default !== undefined) {
+        throw new CommandPathSyntaxError(source, `params.${hint.name} has a default but the file is required: rename to [[${hint.name}]]`);
+    }
+    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 commandFilePriority(value, preferJavaScript) {
     const extension = value.slice(value.lastIndexOf('.') + 1);
     const order = preferJavaScript
@@ -106,39 +114,8 @@ function commandFilePriority(value, preferJavaScript) {
     const priority = order.indexOf(extension);
     return priority < 0 ? Number.MAX_SAFE_INTEGER : priority;
 }
-function parseParameterValue(name, type, value, source) {
-    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;
-        throw new CommandPathSyntaxError(source, `default for ${name}:${type} is invalid`);
-    }
-    if (type === 'boolean') {
-        if (value === 'true' || value === 'false')
-            return value === 'true';
-        throw new CommandPathSyntaxError(source, `default for ${name}:${type} is invalid`);
-    }
-    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`);
-}
-function isStructuredParameter(type) {
-    return type === 'mention'
-        || type === 'image'
-        || type === 'face'
-        || type === 'reply'
-        || type === 'forward'
-        || type === 'dice'
-        || type === 'rps';
-}
 export class CommandPathSyntaxError extends TypeError {
-    constructor(file, detail = 'expected [name:type=default].ts(x)') {
+    constructor(file, detail = 'expected [name].ts(x), [[name]].ts(x), [...name].ts(x) or [[...name]].ts(x)') {
         super(`Invalid Command path ${file}: ${detail}`);
         this.name = 'CommandPathSyntaxError';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,8 +18,8 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.0.4",
-    "@zhin.js/plugin-runtime": "1.1.1"
+    "@zhin.js/feature-kit": "1.0.6",
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -85,7 +85,7 @@ export class CommandIndex {
         source: slot.source,
         parameters: Object.freeze(parameter ? [{
           ...parameter,
-          required: parameter.defaultValue === undefined,
+          required: isRequiredParameter(parameter),
         }] : []),
         slot,
         segments: Object.freeze(segments),
@@ -173,13 +173,27 @@ export class CommandIndex {
     for (const command of this.#commands) {
       const result = command.matcher.match(asMatcherSegments(segments));
       if (!result || !hasCommandBoundary(result.remaining)) continue;
+      const parameter = command.parameter;
+      const params: Record<string, CommandParameterValue> = { ...result.params };
+      if (parameter?.rest) {
+        const raw = result.params[parameter.name];
+        const coerced = coerceRestValues(parameter, Array.isArray(raw) ? raw : []);
+        // 必需 `[...name]` 捕获所有：零元素视为不匹配；标量逐词转换失败同样不匹配。
+        if (!coerced || (isRequiredParameter(parameter) && coerced.length === 0)) continue;
+        params[parameter.name] = coerced;
+      }
       const remaining = normalizeSegments(result.remaining);
       if (exact && remaining.length > 0) continue;
+      // `[[name]]` 无 default 且未命中时，matcher 对 text 回退 ''、其他类型回退 null；
+      // 按契约（省略 default 时未匹配为 undefined）删除该键。
+      if (parameter && !parameter.rest && parameter.optional === true
+        && parameter.defaultValue === undefined
+        && (params[parameter.name] === '' || params[parameter.name] === null)) {
+        delete params[parameter.name];
+      }
       return {
         command,
-        params: Object.freeze({ ...result.params }) as Readonly<
-          Record<string, CommandParameterValue>
-        >,
+        params: Object.freeze(params),
         remaining,
       };
     }
@@ -190,7 +204,7 @@ export class CommandIndex {
     const words = splitCommand(name);
     for (const command of this.#commands) {
       const parameter = command.parameter;
-      if (!parameter) continue;
+      if (!parameter || parameter.rest) continue;
       const parameterIndex = command.segments.findIndex((segment) => segment.startsWith('$'));
       if (words.length !== command.segments.length) continue;
       if (!command.segments.every((segment, index) =>
@@ -230,7 +244,19 @@ function assertParameterSegment(
   if (parameter && dynamicSegments.length === 1
     && dynamicSegments[0] === `$${parameter.name}`
     && segments.at(-1) === dynamicSegments[0]) return;
-  throw new Error(`Broken dynamic Command identity for ${source}`);
+  const dynamic = dynamicSegments[0] ?? (parameter ? `$${parameter.name}` : '$?');
+  throw new Error(
+    `Invalid Command path for ${source}: the dynamic segment "${dynamic}" must be the only dynamic `
+    + `segment and come after a static segment (child plugin commands are prefixed by the plugin `
+    + `path, so a dynamic first segment is never reachable). `
+    + (parameter
+      ? `Hint: move the file under a static directory, e.g. "commands/add/[${parameter.name}:${parameter.type}].ts".`
+      : 'Hint: put the file under a static directory, e.g. "commands/add/<file>.ts".'),
+  );
+}
+
+function isRequiredParameter(parameter: CommandParameterDefinition): boolean {
+  return parameter.optional === true ? false : parameter.defaultValue === undefined;
 }
 
 function displayName(
@@ -239,9 +265,10 @@ function displayName(
 ): string {
   return segments.map((segment) => {
     if (!segment.startsWith('$')) return segment;
-    return parameter?.defaultValue === undefined
-      ? `<${segment.slice(1)}>`
-      : `[${segment.slice(1)}]`;
+    const label = segment.slice(1);
+    const required = !parameter || isRequiredParameter(parameter);
+    if (parameter?.rest) return required ? `<...${label}>` : `[...${label}]`;
+    return required ? `<${label}>` : `[${label}]`;
   }).join(' ');
 }
 
@@ -253,8 +280,13 @@ function matcherPattern(
     if (!segment.startsWith('$')) return segment;
     if (!parameter) throw new Error(`Missing Command parameter metadata: ${segment}`);
     const type = matcherType(parameter.type);
+    // rest：结构化类型按消息段收集；标量类型先按 text 段收集，再在 #match 里逐词切分转换。
+    if (parameter.rest) {
+      return `[...${parameter.name}:${isStructuredRestType(parameter.type) ? type : 'text'}]`;
+    }
+    if (isRequiredParameter(parameter)) return `<${parameter.name}:${type}>`;
     return parameter.defaultValue === undefined
-      ? `<${parameter.name}:${type}>`
+      ? `[${parameter.name}:${type}]`
       : `[${parameter.name}:${type}=${String(parameter.defaultValue)}]`;
   }).join(' ');
 }
@@ -263,20 +295,71 @@ function matcherType(type: CommandParameterType): string {
   return type === 'string' ? 'word' : type;
 }
 
+/** rest 参数中按消息段收集（matcher 原生行为）的结构化类型。 */
+function isStructuredRestType(type: CommandParameterType): boolean {
+  return type === 'mention'
+    || type === 'image'
+    || type === 'face'
+    || type === 'reply'
+    || type === 'forward'
+    || type === 'dice'
+    || type === 'rps';
+}
+
+/**
+ * 捕获所有参数的取值粒度由类型决定：
+ * - `text` / 结构化类型：逐消息段（matcher 原生结果）；
+ * - `word` / `string`：逐词（空白切分）；
+ * - `number` / `integer` / `float` / `boolean`：逐词切分后逐个转换，任一失败返回 undefined（不匹配）。
+ */
+function coerceRestValues(
+  parameter: CommandParameterDefinition,
+  values: readonly unknown[],
+): readonly (string | number | boolean)[] | undefined {
+  const type = parameter.type;
+  if (type === 'text' || isStructuredRestType(type)) {
+    // 逐消息段，保持 matcher 原生提取值（text 为 string，结构化类型可能是 number 等）。
+    return values as readonly (string | number | boolean)[];
+  }
+  const words = values.flatMap((value) =>
+    typeof value === 'string' ? value.split(/\s+/u).filter(Boolean) : []);
+  if (type === 'string' || type === 'word') return words;
+  if (type === 'number' || type === 'integer' || type === 'float') {
+    const numbers: number[] = [];
+    for (const [index, word] of words.entries()) {
+      const number = Number(word);
+      if (!Number.isFinite(number)
+        || (type === 'integer' && !Number.isInteger(number))
+        || (type === 'float' && !word.includes('.'))) return undefined;
+      numbers[index] = number;
+    }
+    return numbers;
+  }
+  if (type === 'boolean') {
+    if (!words.every((word) => word === 'true' || word === 'false')) return undefined;
+    return words.map((word) => word === 'true');
+  }
+  return undefined;
+}
+
 function routeShape(segments: readonly string[]): string {
   return segments.map((segment) => segment.startsWith('$') ? '$' : segment).join(' ');
 }
 
 function compareCommands(left: CommandRecord, right: CommandRecord): number {
-  const leftDynamic = left.parameter ? 1 : 0;
-  const rightDynamic = right.parameter ? 1 : 0;
-  return leftDynamic - rightDynamic
+  return dynamicWeight(left) - dynamicWeight(right)
     || staticSegmentCount(right.segments) - staticSegmentCount(left.segments)
     || right.segments.length - left.segments.length
     || right.name.length - left.name.length
     || left.name.localeCompare(right.name);
 }
 
+/** 静态 < 单参数 < 捕获所有：更具体的形状优先匹配。 */
+function dynamicWeight(command: CommandRecord): number {
+  if (!command.parameter) return 0;
+  return command.parameter.rest ? 2 : 1;
+}
+
 function staticSegmentCount(segments: readonly string[]): number {
   return segments.filter((segment) => !segment.startsWith('$')).length;
 }

package/src/definition.ts

@@ -25,9 +25,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 +67,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 +91,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: 'group' | 'channel';
+    readonly id: string;
+  }>;
+  readonly threadId?: string;
+}
+
 /**
  * 命令侧入站消息契约。
  *
@@ -64,8 +117,7 @@ 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;
@@ -119,6 +171,11 @@ export interface CommandDefinition<
   readonly $feature: typeof commandBrand;
   readonly $parameter?: CommandParameterDefinition;
   readonly description?: string;
+  /**
+   * Next.js 风格参数声明：动态段文件名（`[name]` 等）的形态配合这里的
+   * 类型 / 默认值 / 描述使用。静态命令可忽略本字段。
+   */
+  readonly params?: Readonly<Record<string, CommandParamSchema>>;
   execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
 
@@ -145,6 +202,17 @@ 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`);
+      }
+    }
+  }
   return Object.freeze({ $feature: commandBrand, ...definition });
 }
 
@@ -202,7 +270,7 @@ export function resolveCommandSession(input: unknown): CommandSession {
     ? input.metadata as Readonly<Record<string, unknown>>
     : undefined;
 
-  const adapter = input.adapter.split('\0')[0] || undefined;
+  const adapter = input.conversation.endpoint.adapter || undefined;
   const endpoint = typeof metadata?.endpoint === 'string' && metadata.endpoint
     ? metadata.endpoint
     : undefined;
@@ -221,8 +289,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 +306,12 @@ function resolveScene(
     });
   }
 
-  const parsed = parseTarget(input.target);
+  const conversation = input.conversation;
   const type = (typeof metadata?.channelType === 'string' && metadata.channelType)
     || (typeof metadata?.type === 'string' && metadata.type)
-    || parsed?.type;
+    || conversation.kind;
   const id = (typeof metadata?.channelId === 'string' && metadata.channelId)
-    || parsed?.id;
+    || conversation.id;
   if (!type || !id) return undefined;
 
   const name = firstString(
@@ -309,22 +377,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/provider.ts

@@ -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));
   },
 };
 
@@ -81,45 +80,40 @@ function isCommandSegment(value: string): boolean {
 
 interface ParsedCommandFile {
   readonly localSegment: string;
-  readonly parameter?: CommandParameterDefinition;
+  readonly parameter?: CommandParameterHint;
 }
 
-const dynamicCommandFilePattern =
-  /^\[([a-z][a-zA-Z0-9]*):([a-z][a-z0-9-]*)(?:=([^\]]*))?\]\.(?:tsx?|[cm]?js)$/;
+/** 文件名声明的参数形态；类型与默认值来自 `defineCommand({ params })`。 */
+interface CommandParameterHint {
+  readonly name: string;
+  readonly optional: boolean;
+  readonly rest: boolean;
+}
 
-const commandParameterTypes = new Set<CommandParameterType>([
-  'string',
-  'number',
-  'integer',
-  'float',
-  'boolean',
-  'word',
-  'text',
-  'mention',
-  'image',
-  'face',
-  'reply',
-  'forward',
-  'dice',
-  'rps',
-]);
+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 },
+];
 
 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 ?? ''}`);
-    }
-    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 +121,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';
   }