@zhin.js/command 1.0.6 → 1.0.9

package/lib/definition.js

@@ -1,5 +1,22 @@
 import { createCapabilityContext, } from '@zhin.js/feature-kit';
+import { assertPermitSyntax } from '@zhin.js/permission';
 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,8 +25,66 @@ 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`);
+            }
+        }
+    }
+    validateCommandAlias(definition.alias);
+    validateCommandPermit(definition.permit);
+    validateCommandShortcutShape(definition.shortcut);
     return Object.freeze({ $feature: commandBrand, ...definition });
 }
+function validateCommandAlias(alias) {
+    if (alias === undefined)
+        return;
+    if (!Array.isArray(alias)) {
+        throw new TypeError('Command alias must be a readonly string[]');
+    }
+    for (const [index, entry] of alias.entries()) {
+        if (typeof entry !== 'string') {
+            throw new TypeError(`Command alias[${index}] must be a string`);
+        }
+        const tokens = entry.trim().split(/\s+/u).filter(Boolean);
+        if (tokens.length === 0) {
+            throw new TypeError(`Command alias[${index}] must contain at least one token`);
+        }
+    }
+}
+function validateCommandPermit(permit) {
+    if (permit === undefined)
+        return;
+    if (!Array.isArray(permit)) {
+        throw new TypeError('Command permit must be a readonly string[]');
+    }
+    for (const [index, entry] of permit.entries()) {
+        if (typeof entry !== 'string') {
+            throw new TypeError(`Command permit[${index}] must be a string`);
+        }
+    }
+    assertPermitSyntax(permit);
+}
+function validateCommandShortcutShape(shortcut) {
+    if (shortcut === undefined)
+        return;
+    if (!shortcut || typeof shortcut !== 'object' || Array.isArray(shortcut)) {
+        throw new TypeError('Command shortcut must be a Record<string, Record<string, value>>');
+    }
+    for (const [trigger, params] of Object.entries(shortcut)) {
+        if (!trigger.trim()) {
+            throw new TypeError('Command shortcut keys must be non-empty after trim');
+        }
+        if (!params || typeof params !== 'object' || Array.isArray(params)) {
+            throw new TypeError(`Command shortcut[${JSON.stringify(trigger)}] must be a params Record`);
+        }
+    }
+}
 export function bindCommandParameter(definition, parameter) {
     if (!parameter)
         return definition;
@@ -47,10 +122,9 @@ export function resolveCommandSession(input) {
     const metadata = input.metadata && typeof input.metadata === 'object'
         ? input.metadata
         : undefined;
-    const adapter = input.adapter.split('\0')[0] || undefined;
-    const endpoint = typeof metadata?.endpoint === 'string' && metadata.endpoint
-        ? metadata.endpoint
-        : undefined;
+    const adapter = input.conversation.endpoint.adapter || undefined;
+    const endpoint = input.endpointId
+        || (typeof metadata?.endpoint === 'string' && metadata.endpoint ? metadata.endpoint : undefined);
     const scene = resolveScene(input, metadata);
     const sender = resolveSender(input, metadata);
     return Object.freeze({
@@ -64,8 +138,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 +150,9 @@ function resolveScene(input, metadata) {
             ...(input.scene.name !== undefined ? { name: input.scene.name } : {}),
         });
     }
-    const parsed = parseTarget(input.target);
-    const type = (typeof metadata?.channelType === 'string' && metadata.channelType)
-        || (typeof metadata?.type === 'string' && metadata.type)
-        || parsed?.type;
-    const id = (typeof metadata?.channelId === 'string' && metadata.channelId)
-        || parsed?.id;
+    const conversation = input.conversation;
+    const type = conversation.kind;
+    const id = conversation.id;
     if (!type || !id)
         return undefined;
     const name = firstString(metadata?.channelName, metadata?.group_name, metadata?.groupName, metadata?.sceneName);
@@ -96,24 +167,21 @@ function resolveSender(input, metadata) {
     if (isCommandSender(structured)) {
         return freezeSender(structured);
     }
-    // 允许上游把 sender 直接做成对象（未来 Runtime Message 演进）
-    if (isCommandSender(input.sender)) {
-        return freezeSender(input.sender);
-    }
-    const id = typeof input.sender === 'string' && input.sender
-        ? input.sender
-        : firstString(metadata?.user_id, metadata?.userId);
+    const id = input.sender?.id || firstString(metadata?.user_id, metadata?.userId);
     if (!id)
         return undefined;
-    const name = firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
-    const role = resolveRoles(metadata);
+    const name = input.sender?.name || firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
+    const role = resolveRoles(input, metadata);
     return Object.freeze({
         id,
         ...(name !== undefined ? { name } : {}),
         role,
     });
 }
-function resolveRoles(metadata) {
+function resolveRoles(input, metadata) {
+    if (input.sender?.roles?.length) {
+        return Object.freeze([...input.sender.roles]);
+    }
     const roles = [];
     const push = (value) => {
         if (typeof value !== 'string')
@@ -136,24 +204,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/index.d.ts

@@ -1,4 +1,5 @@
 export * from './command-index.js';
 export * from './definition.js';
+export { assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, type ParsedPermit, type PermitKind, } from './permit.js';
 export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export * from './command-index.js';
 export * from './definition.js';
+export { assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, } from './permit.js';
 export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';

package/lib/permit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export permit 解析/校验 from @zhin.js/permission (SSOT)。
+ * 保留 CommandSession 兼容签名供 command-index 过渡使用。
+ */
+export { type PermitKind, type ParsedPermit, parsePermitName, isBuiltinPermit, isPlatformPermit, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';

package/lib/permit.js

@@ -0,0 +1,5 @@
+/**
+ * Re-export permit 解析/校验 from @zhin.js/permission (SSOT)。
+ * 保留 CommandSession 兼容签名供 command-index 过渡使用。
+ */
+export { parsePermitName, isBuiltinPermit, isPlatformPermit, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';

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

@@ -1,5 +1,5 @@
 import { basename, join, parse, sep } from 'node:path';
-import { featureId } from '@zhin.js/plugin-runtime';
+import { featureId, isCapabilityLocalSegment } from '@zhin.js/plugin-runtime';
 import { defineFeatureProvider, } from '@zhin.js/feature-kit';
 import { CommandIndex } from './command-index.js';
 import { bindCommandParameter, parseCommandDefinition, } from './definition.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) {
@@ -38,7 +38,7 @@ async function* discoverCommandDirectory(context, directory, ancestors) {
         }
     }
     for (const entry of entries) {
-        if (entry.kind === 'directory' && isCommandSegment(entry.name)) {
+        if (entry.kind === 'directory' && isCapabilityLocalSegment(entry.name)) {
             yield* discoverCommandDirectory(context, join(directory, entry.name), [...ancestors, entry.name]);
             continue;
         }
@@ -56,48 +56,58 @@ 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 },
+];
+const commandModuleExtension = /\.(?:tsx?|[cm]?js)$/u;
 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 ?? ''}`);
+    // 静态段：ASCII kebab（hello.ts）或 Unicode 名（赞我.ts）；与 isCapabilityLocalSegment 对齐。
+    if (commandModuleExtension.test(value)) {
+        const localSegment = parse(value).name;
+        if (isCapabilityLocalSegment(localSegment)) {
+            return { localSegment };
         }
-        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 +116,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.6",
+  "version": "1.0.9",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,8 +18,9 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.0.5",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/feature-kit": "1.0.8",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "@zhin.js/permission": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",