@zhin.js/command 1.0.7 → 1.0.10

package/lib/definition.js

@@ -1,4 +1,5 @@
 import { createCapabilityContext, } from '@zhin.js/feature-kit';
+import { assertPermitSyntax } from '@zhin.js/permission';
 const commandBrand = 'zhin.command/1';
 export const commandParameterTypes = new Set([
     'string',
@@ -35,8 +36,55 @@ export function defineCommand(definition) {
             }
         }
     }
+    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;
@@ -52,6 +100,18 @@ export function parseCommandDefinition(value) {
     }
     return definition;
 }
+/**
+ * 将动态参数值（可能包含函数）批量解析为静态值。
+ * 函数值接收从 `source`（通常是 IM Runtime `Message`）解析出的 {@link CommandSession}。
+ */
+export function resolveDynamicParams(params, source) {
+    const session = resolveCommandSession(source);
+    const resolved = {};
+    for (const [key, value] of Object.entries(params)) {
+        resolved[key] = typeof value === 'function' ? value(session) : value;
+    }
+    return Object.freeze(resolved);
+}
 export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([])) {
     const context = createCapabilityContext(snapshot, ownerId);
     const session = resolveCommandSession(input);
@@ -75,9 +135,8 @@ export function resolveCommandSession(input) {
         ? input.metadata
         : undefined;
     const adapter = input.conversation.endpoint.adapter || undefined;
-    const endpoint = typeof metadata?.endpoint === 'string' && metadata.endpoint
-        ? metadata.endpoint
-        : 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({
@@ -104,11 +163,8 @@ function resolveScene(input, metadata) {
         });
     }
     const conversation = input.conversation;
-    const type = (typeof metadata?.channelType === 'string' && metadata.channelType)
-        || (typeof metadata?.type === 'string' && metadata.type)
-        || conversation.kind;
-    const id = (typeof metadata?.channelId === 'string' && metadata.channelId)
-        || conversation.id;
+    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);
@@ -123,24 +179,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')

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.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';
@@ -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,18 +56,20 @@ async function* discoverCommandDirectory(context, directory, ancestors) {
         };
     }
 }
-function isCommandSegment(value) {
-    return /^[a-z0-9][a-z0-9-]*$/.test(value);
-}
 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 };
+    // 静态段：ASCII kebab（hello.ts）或 Unicode 名（赞我.ts）；与 isCapabilityLocalSegment 对齐。
+    if (commandModuleExtension.test(value)) {
+        const localSegment = parse(value).name;
+        if (isCapabilityLocalSegment(localSegment)) {
+            return { localSegment };
+        }
     }
     for (const { pattern, optional, rest } of dynamicCommandFilePatterns) {
         const match = pattern.exec(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "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.6",
-    "@zhin.js/plugin-runtime": "1.1.3"
+    "@zhin.js/feature-kit": "1.0.8",
+    "@zhin.js/permission": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",