@zhin.js/command 1.0.3 → 1.0.5

package/lib/command-index.js

@@ -133,11 +133,18 @@ export function isCommandIndex(value) {
     return !!value && typeof value === 'object'
         && value.$projection === 'zhin.command-index/1';
 }
+/**
+ * 命令运行时名 = 插件树路径段（instanceKey，去掉 root）以 `.` 连接后，再与命令
+ * 文件路径首段以 `.` 连接；命令内部嵌套段仍为空格分隔。Root 插件无前缀。
+ * 例：`root/qq` + `endpoint/list` → `qq.endpoint list`；
+ * `root/b/a` + `foo` → `b.a.foo`；root + `foo` → `foo`。
+ */
 function runtimeSegments(owner, localName) {
-    const ownerSegments = owner === 'root'
-        ? []
-        : owner.slice('root/'.length).split('/');
-    return [...ownerSegments, ...localName.split('/')];
+    const localSegments = localName.split('/');
+    if (owner === 'root')
+        return localSegments;
+    const prefix = owner.slice('root/'.length).split('/').join('.');
+    return [`${prefix}.${localSegments[0]}`, ...localSegments.slice(1)];
 }
 function assertParameterSegment(segments, parameter, source) {
     const dynamicSegments = segments.filter((segment) => segment.startsWith('$'));

package/lib/definition.js

@@ -140,14 +140,19 @@ function parseTarget(target) {
     const parts = target.split(':').filter(Boolean);
     if (parts.length < 2)
         return undefined;
-    const kind = parts[0];
+    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: parts[parts.length - 1] };
+        return { type: 'channel', id: lastPart };
     }
     if (kind === 'temp' && parts.length >= 3) {
-        return { type: 'private', id: parts[parts.length - 1] };
+        return { type: 'private', id: lastPart };
     }
-    return { type: kind, id: parts.slice(1).join(':') };
+    return { type: kind, id: rest.join(':') };
 }
 function isCommandScene(value) {
     if (!value || typeof value !== 'object')

package/lib/provider.js

@@ -1,4 +1,4 @@
-import { basename, join, parse } from 'node:path';
+import { basename, join, parse, sep } from 'node:path';
 import { featureId } from '@zhin.js/plugin-runtime';
 import { defineFeatureProvider, } from '@zhin.js/feature-kit';
 import { CommandIndex } from './command-index.js';
@@ -20,6 +20,23 @@ const commandFiles = {
 async function* discoverCommandDirectory(context, directory, ancestors) {
     const entries = [...await context.host.list(directory)]
         .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    const files = entries.flatMap((entry) => {
+        if (entry.kind !== 'file')
+            return [];
+        const parsed = parseCommandFile(entry.name);
+        return parsed ? [{ entry, parsed }] : [];
+    });
+    const preferJavaScript = context.packageRoot
+        .split(sep)
+        .includes('node_modules');
+    const preferredFiles = new Map();
+    for (const { entry, parsed } of files) {
+        const current = preferredFiles.get(parsed.localSegment);
+        if (!current || commandFilePriority(entry.name, preferJavaScript)
+            < commandFilePriority(current, preferJavaScript)) {
+            preferredFiles.set(parsed.localSegment, entry.name);
+        }
+    }
     for (const entry of entries) {
         if (entry.kind === 'directory' && isCommandSegment(entry.name)) {
             yield* discoverCommandDirectory(context, join(directory, entry.name), [...ancestors, entry.name]);
@@ -30,6 +47,8 @@ async function* discoverCommandDirectory(context, directory, ancestors) {
         const file = parseCommandFile(entry.name);
         if (!file)
             continue;
+        if (preferredFiles.get(file.localSegment) !== entry.name)
+            continue;
         yield {
             localName: [...ancestors, file.localSegment].join('/'),
             source: join(directory, entry.name),
@@ -40,7 +59,7 @@ 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?$/;
+const dynamicCommandFilePattern = /^\[([a-z][a-zA-Z0-9]*):([a-z][a-z0-9-]*)(?:=([^\]]*))?\]\.(?:tsx?|[cm]?js)$/;
 const commandParameterTypes = new Set([
     'string',
     'number',
@@ -58,7 +77,7 @@ const commandParameterTypes = new Set([
     'rps',
 ]);
 function parseCommandFile(value) {
-    if (/^[a-z0-9][a-z0-9-]*\.tsx?$/.test(value)) {
+    if (/^[a-z0-9][a-z0-9-]*\.(?:tsx?|[cm]?js)$/.test(value)) {
         return { localSegment: parse(value).name };
     }
     const match = dynamicCommandFilePattern.exec(value);
@@ -79,6 +98,14 @@ function parseCommandFile(value) {
     }
     return undefined;
 }
+function commandFilePriority(value, preferJavaScript) {
+    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, type, value, source) {
     if (type === 'string' || type === 'word' || type === 'text')
         return value;

package/package.json

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

package/src/command-index.ts

@@ -207,11 +207,17 @@ export function isCommandIndex(value: unknown): value is CommandIndex {
     && (value as { readonly $projection?: unknown }).$projection === 'zhin.command-index/1';
 }
 
+/**
+ * 命令运行时名 = 插件树路径段（instanceKey，去掉 root）以 `.` 连接后，再与命令
+ * 文件路径首段以 `.` 连接；命令内部嵌套段仍为空格分隔。Root 插件无前缀。
+ * 例：`root/qq` + `endpoint/list` → `qq.endpoint list`；
+ * `root/b/a` + `foo` → `b.a.foo`；root + `foo` → `foo`。
+ */
 function runtimeSegments(owner: string, localName: string): string[] {
-  const ownerSegments = owner === 'root'
-    ? []
-    : owner.slice('root/'.length).split('/');
-  return [...ownerSegments, ...localName.split('/')];
+  const localSegments = localName.split('/');
+  if (owner === 'root') return localSegments;
+  const prefix = owner.slice('root/'.length).split('/').join('.');
+  return [`${prefix}.${localSegments[0]}`, ...localSegments.slice(1)];
 }
 
 function assertParameterSegment(

package/src/definition.ts

@@ -312,14 +312,17 @@ function resolveRoles(
 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 = parts[0];
+  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: parts[parts.length - 1]! };
+    return { type: 'channel', id: lastPart };
   }
   if (kind === 'temp' && parts.length >= 3) {
-    return { type: 'private', id: parts[parts.length - 1]! };
+    return { type: 'private', id: lastPart };
   }
-  return { type: kind!, id: parts.slice(1).join(':') };
+  return { type: kind, id: rest.join(':') };
 }
 
 function isCommandScene(value: unknown): value is CommandScene {

package/src/provider.ts

@@ -1,4 +1,4 @@
-import { basename, join, parse } from 'node:path';
+import { basename, join, parse, sep } from 'node:path';
 import { featureId } from '@zhin.js/plugin-runtime';
 import {
   defineFeatureProvider,
@@ -38,6 +38,22 @@ async function* discoverCommandDirectory(
 ): AsyncIterable<DiscoveredSource> {
   const entries = [...await context.host.list(directory)]
     .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  const files = entries.flatMap((entry) => {
+    if (entry.kind !== 'file') return [];
+    const parsed = parseCommandFile(entry.name);
+    return parsed ? [{ entry, parsed }] : [];
+  });
+  const preferJavaScript = context.packageRoot
+    .split(sep)
+    .includes('node_modules');
+  const preferredFiles = new Map<string, string>();
+  for (const { entry, parsed } of files) {
+    const current = preferredFiles.get(parsed.localSegment);
+    if (!current || commandFilePriority(entry.name, preferJavaScript)
+      < commandFilePriority(current, preferJavaScript)) {
+      preferredFiles.set(parsed.localSegment, entry.name);
+    }
+  }
   for (const entry of entries) {
     if (entry.kind === 'directory' && isCommandSegment(entry.name)) {
       yield* discoverCommandDirectory(
@@ -50,6 +66,7 @@ async function* discoverCommandDirectory(
     if (entry.kind !== 'file') continue;
     const file = parseCommandFile(entry.name);
     if (!file) continue;
+    if (preferredFiles.get(file.localSegment) !== entry.name) continue;
     yield {
       localName: [...ancestors, file.localSegment].join('/'),
       source: join(directory, entry.name),
@@ -68,7 +85,7 @@ interface ParsedCommandFile {
 }
 
 const dynamicCommandFilePattern =
-  /^\[([a-z][a-zA-Z0-9]*):([a-z][a-z0-9-]*)(?:=([^\]]*))?\]\.tsx?$/;
+  /^\[([a-z][a-zA-Z0-9]*):([a-z][a-z0-9-]*)(?:=([^\]]*))?\]\.(?:tsx?|[cm]?js)$/;
 
 const commandParameterTypes = new Set<CommandParameterType>([
   'string',
@@ -88,7 +105,7 @@ const commandParameterTypes = new Set<CommandParameterType>([
 ]);
 
 function parseCommandFile(value: string): ParsedCommandFile | undefined {
-  if (/^[a-z0-9][a-z0-9-]*\.tsx?$/.test(value)) {
+  if (/^[a-z0-9][a-z0-9-]*\.(?:tsx?|[cm]?js)$/.test(value)) {
     return { localSegment: parse(value).name };
   }
   const match = dynamicCommandFilePattern.exec(value);
@@ -110,6 +127,15 @@ 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,