@zhin.js/command 1.1.0 → 1.1.2

package/README.md

@@ -1,23 +1,23 @@
 # @zhin.js/command
 
-Zhin Plugin Runtime 的约定式 Command Feature。它发现 `commands/**/*.ts(x)`，将插件树
-路径与文件路径投影为命令，并用 `segment-matcher` 同时匹配纯文本和 canonical IM segments。
+Zhin Plugin Runtime 的约定式 Command Feature。它发现 `commands/**/*/index.ts(x)`，只把文件
+相对路径投影为用户路由，并用 `segment-matcher` 同时匹配纯文本和 canonical IM segments。
 
-静态命令文件名可为 ASCII kebab（`hello.ts`）或 Unicode 名（`赞我.ts`）；动态参数文件
-（`[name].ts` 等）仍限 ASCII。详见 [命令创作指南](../../../docs/authoring/commands.md)。
+静态命令目录可为 ASCII kebab（`hello/`）或 Unicode 名（`赞我/`）；动态参数目录
+（`[name]/` 等）仍限 ASCII。每个路由目录只识别 `index.ts(x)`，同目录其他文件是 helper。详见[命令创作指南](../../../docs/authoring/commands.md)。
 
 ## Authoring
 
 ```ts
-// commands/gh/issue/list.ts -> gh issue list
-// commands/赞我.ts -> 赞我
+// commands/gh/issue/list/index.ts -> gh issue list
+// commands/赞我/index.ts -> 赞我
 import { defineCommand } from 'zhin.js/command';
 
 export default defineCommand({
   description: 'List GitHub issues',
-  alias: ['issues'],                 // 可多词；子插件仍保留 owner 前缀
+  alias: ['issues'],                 // 可多词；owner 不参与用户路由
   permit: ['adapter(icqq)', 'role(master)'], // 数组 AND；未过则静默未命中
-  // shortcut: { '列 issue': {} },   // 全局整句，可打破命名空间
+  // shortcut: { '列 issue': {} },   // 全局整句
   execute: ({ args }) => `issues:${args.join(',')}`,
 });
 ```
@@ -25,9 +25,9 @@ export default defineCommand({
 最后一个文件名可以用 Next.js 风格方括号声明参数形态，类型与默认值在 `defineCommand({ params })` 中声明（`type` 必填，`default` 可选且有默认值时文件名必须用双方括号）：
 
 ```text
-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 逐词转换）
+commands/gh/pr/[[title]]/index.ts   -> gh pr [title]    （params: { title: { type: 'string', default: 'defaultTitle' } }）
+commands/upload/[asset]/index.ts    -> upload <asset>   （params: { asset: { type: 'image' } }）
+commands/search/[...kw]/index.ts    -> search <...kw>   （params: { kw: { type: 'text' } }，运行时 params.kw 为数组；元素粒度随类型：text 逐消息段，word/string 逐词，number/boolean 逐词转换）
 ```
 
 文本类型包括 `string`、`word`、`text`、`number`、`integer`、`float`、`boolean`；结构化
@@ -49,9 +49,9 @@ commands/search/[...kw].ts    -> search <...kw>   （params: { kw: { type: 'text
 
 可选声明字段：
 
-- `alias`：替换全部本地静态段并重挂 owner 前缀（不打破子插件命名空间）。
+- `alias`：替换全部本地静态段；owner 不参与用户路由。
 - `permit`：内置 DSL（`adapter|group|private|channel|user|role`）；失败为静默未命中。
-- `shortcut`：全局整句精确匹配 → 预填 `params`（可打破命名空间）。
+- `shortcut`：全局整句精确匹配 → 预填 `params`。
 
 单文件插件可在 `setup({ addCommand })` 中调用
 `addCommand('hello', defineCommand(...))`。它与目录发现共用 CommandIndex；拆成文件后

package/lib/command-index.js

@@ -35,7 +35,8 @@ export class CommandIndex {
             occupancy.set(key, source);
         };
         for (const slot of slots) {
-            const primarySegments = runtimeSegments(slot.owner, slot.localName);
+            const namespace = commandNamespace(this.snapshot, slot.owner);
+            const primarySegments = [...namespace, ...runtimeSegments(slot.localName)];
             const parameter = slot.definition.$parameter;
             assertParameterSegment(primarySegments, parameter, slot.source);
             const name = displayName(primarySegments, parameter);
@@ -71,7 +72,7 @@ export class CommandIndex {
             });
             if (alias) {
                 for (const entry of alias) {
-                    const aliasSegments = aliasRuntimeSegments(slot.owner, entry, primarySegments);
+                    const aliasSegments = [...namespace, ...aliasRuntimeSegments(entry, primarySegments.slice(namespace.length))];
                     assertParameterSegment(aliasSegments, parameter, `${slot.source} alias ${JSON.stringify(entry)}`);
                     claim(occupancyKey(aliasSegments, parameter), `${slot.source} alias ${JSON.stringify(entry)}`);
                     routes.push({
@@ -84,7 +85,7 @@ export class CommandIndex {
             }
             if (slot.definition.shortcut) {
                 for (const [rawTrigger, prefill] of Object.entries(slot.definition.shortcut)) {
-                    const trigger = rawTrigger.trim();
+                    const trigger = [...namespace, ...splitCommand(rawTrigger)].join(' ');
                     claim(trigger, `${slot.source} shortcut ${JSON.stringify(trigger)}`);
                     shortcuts.set(trigger, {
                         record,
@@ -318,28 +319,36 @@ export function isCommandIndex(value) {
         && 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`。
+ * 用户路由来自命令的本地能力路径；只有插件配置显式声明 commandNamespace
+ * 时才在其前面增加命名空间。owner 始终只属于 CapabilityId。
  */
-function runtimeSegments(owner, localName) {
-    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 runtimeSegments(localName) {
+    return localName.split('/');
+}
+function commandNamespace(snapshot, owner) {
+    const config = snapshot.config.get(owner);
+    const value = config?.commandNamespace;
+    if (value === undefined || value === '')
+        return Object.freeze([]);
+    if (typeof value !== 'string') {
+        throw new TypeError(`Invalid commandNamespace for ${owner}: expected a string`);
+    }
+    const segments = splitCommand(value);
+    if (segments.length === 0 || segments.some((segment) => !isCommandNamespaceSegment(segment))) {
+        throw new TypeError(`Invalid commandNamespace for ${owner}: expected space-separated command segments`);
+    }
+    return Object.freeze([...segments]);
+}
+function isCommandNamespaceSegment(value) {
+    return /^[\p{L}\p{N}][\p{L}\p{N}_-]*$/u.test(value);
 }
 /**
- * 用 alias 词序列替换全部本地静态段，再按 owner 规则重挂前缀；动态段保留。
+ * 用 alias 词序列替换全部本地静态段；动态段保留。
  */
-function aliasRuntimeSegments(owner, alias, primarySegments) {
+function aliasRuntimeSegments(alias, primarySegments) {
     const aliasTokens = alias.trim().split(/\s+/u).filter(Boolean);
     const dynamicTail = primarySegments.filter((segment) => segment.startsWith('$'));
-    if (owner === 'root')
-        return [...aliasTokens, ...dynamicTail];
-    const prefix = owner.slice('root/'.length).split('/').join('.');
-    return [`${prefix}.${aliasTokens[0]}`, ...aliasTokens.slice(1), ...dynamicTail];
+    return [...aliasTokens, ...dynamicTail];
 }
 function occupancyKey(segments, parameter) {
     return parameter ? routeShape(segments) : segments.join(' ');
@@ -416,11 +425,10 @@ function assertParameterSegment(segments, parameter, source) {
         return;
     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). `
+        + `segment and be the final path segment. `
         + (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".'));
+            ? `Hint: keep only one dynamic entry, e.g. "commands/add/[${parameter.name}]/index.ts".`
+            : 'Hint: keep only one dynamic entry at the end of the command path.'));
 }
 function isRequiredParameter(parameter) {
     return parameter.optional === true ? false : parameter.defaultValue === undefined;

package/lib/definition.d.ts

@@ -198,8 +198,8 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
      */
     readonly params?: Readonly<Record<string, CommandParamSchema>>;
     /**
-     * 本地静态段别名（可多词，如 `'gh issue'`）。替换全部本地静态段后仍挂
-     * owner 前缀；不打破子插件命名空间。
+     * 本地静态段别名（可多词，如 `'gh issue'`）。Capability owner 不参与
+     * 用户路由；alias 只替换文件路径提供的静态段。
      */
     readonly alias?: readonly string[];
     /**
@@ -209,7 +209,7 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
     readonly permit?: readonly string[];
     /**
      * 全局整句快捷方式：触发串（trim 后全文相等）→ 预填 params。
-     * 可打破 owner 命名空间。
+     * 与普通路由一样是全局用户输入，冲突会在 generation 构建时拒绝。
      */
     readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>>;
     execute(context: CommandContext<TConfig, TInput, TAdapter>): TResult | Promise<TResult>;

package/lib/provider.js

@@ -1,4 +1,4 @@
-import { basename, join, parse, sep } from 'node:path';
+import { basename, dirname, join, sep } from 'node:path';
 import { featureId, isCapabilityLocalSegment } from '@zhin.js/plugin-runtime';
 import { defineFeatureProvider, } from '@zhin.js/feature-kit';
 import { CommandIndex } from './command-index.js';
@@ -8,52 +8,47 @@ const commandFiles = {
     id: 'commands-ts',
     async *discover(context) {
         const directory = join(context.packageRoot, 'commands');
-        yield* discoverCommandDirectory(context, directory, []);
+        const entries = [...await context.host.list(directory)]
+            .filter((entry) => entry.kind === 'directory')
+            .sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const segment = parseCommandDirectory(entry.name);
+            if (!segment)
+                continue;
+            yield* discoverCommandDirectory(context, join(directory, entry.name), [segment]);
+        }
     },
     async load(source, context) {
         const module = await context.host.loadModule(source.source);
         const definition = parseCommandDefinition(module.default);
-        const file = parseCommandFile(basename(source.source));
+        const file = parseCommandDirectory(basename(dirname(source.source)));
         return bindCommandParameter(definition, resolveParameter(definition, file, source.source));
     },
 };
 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);
-        }
+    const index = preferredCommandIndex(entries, preferJavaScript);
+    if (index) {
+        yield {
+            localName: ancestors.map((segment) => segment.localSegment).join('/'),
+            source: join(directory, index),
+            relatedSources: Object.freeze(entries
+                .filter((entry) => entry.kind === 'file' && entry.name !== index)
+                .map((entry) => join(directory, entry.name))),
+            target: 'server',
+        };
     }
     for (const entry of entries) {
-        if (entry.kind === 'directory' && isCapabilityLocalSegment(entry.name)) {
-            yield* discoverCommandDirectory(context, join(directory, entry.name), [...ancestors, entry.name]);
-            continue;
-        }
-        if (entry.kind !== 'file')
-            continue;
-        const file = parseCommandFile(entry.name);
-        if (!file)
+        if (entry.kind !== 'directory')
             continue;
-        if (preferredFiles.get(file.localSegment) !== entry.name)
+        const segment = parseCommandDirectory(entry.name);
+        if (!segment)
             continue;
-        yield {
-            localName: [...ancestors, file.localSegment].join('/'),
-            source: join(directory, entry.name),
-            target: 'server',
-        };
+        yield* discoverCommandDirectory(context, join(directory, entry.name), [...ancestors, segment]);
     }
 }
 const dynamicCommandFilePatterns = [
@@ -62,17 +57,9 @@ const dynamicCommandFilePatterns = [
     { 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) {
-    // 静态段：ASCII kebab（hello.ts）或 Unicode 名（赞我.ts）；与 isCapabilityLocalSegment 对齐。
-    if (commandModuleExtension.test(value)) {
-        const localSegment = parse(value).name;
-        if (isCapabilityLocalSegment(localSegment)) {
-            return { localSegment };
-        }
-    }
+function parseCommandDirectory(value) {
     for (const { pattern, optional, rest } of dynamicCommandFilePatterns) {
-        const match = pattern.exec(value);
+        const match = pattern.exec(`${value}.ts`);
         if (!match || !match[1])
             continue;
         const name = match[1];
@@ -82,6 +69,9 @@ function parseCommandFile(value) {
             parameter: { name, optional, rest },
         };
     }
+    if (isCapabilityLocalSegment(value)) {
+        return { localSegment: value };
+    }
     if (value.startsWith('[') || value.includes(']')) {
         throw new CommandPathSyntaxError(value);
     }
@@ -97,7 +87,7 @@ function resolveParameter(definition, file, source) {
         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}]]`);
+        throw new CommandPathSyntaxError(source, `params.${hint.name} has a default but the directory is required: rename it to [[${hint.name}]]`);
     }
     return {
         name: hint.name,
@@ -116,8 +106,14 @@ function commandFilePriority(value, preferJavaScript) {
     const priority = order.indexOf(extension);
     return priority < 0 ? Number.MAX_SAFE_INTEGER : priority;
 }
+function preferredCommandIndex(entries, preferJavaScript) {
+    return entries
+        .filter((entry) => entry.kind === 'file' && /^index\.(?:tsx?|[cm]?js)$/u.test(entry.name))
+        .sort((left, right) => commandFilePriority(left.name, preferJavaScript)
+        - commandFilePriority(right.name, preferJavaScript))[0]?.name;
+}
 export class CommandPathSyntaxError extends TypeError {
-    constructor(file, detail = 'expected [name].ts(x), [[name]].ts(x), [...name].ts(x) or [[...name]].ts(x)') {
+    constructor(file, detail = 'expected commands/foo/index.ts or commands/foo/[name]/index.ts') {
         super(`Invalid Command path ${file}: ${detail}`);
         this.name = 'CommandPathSyntaxError';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,10 +18,10 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.1.0",
+    "@zhin.js/feature-kit": "1.1.2",
     "@zhin.js/interaction": "1.1.0",
-    "@zhin.js/plugin-runtime": "1.1.9",
-    "@zhin.js/permission": "1.1.0"
+    "@zhin.js/permission": "1.1.2",
+    "@zhin.js/plugin-runtime": "1.1.11"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -119,7 +119,8 @@ export class CommandIndex {
     };
 
     for (const slot of slots) {
-      const primarySegments = runtimeSegments(slot.owner, slot.localName);
+      const namespace = commandNamespace(this.snapshot, slot.owner);
+      const primarySegments = [...namespace, ...runtimeSegments(slot.localName)];
       const parameter = slot.definition.$parameter;
       assertParameterSegment(primarySegments, parameter, slot.source);
       const name = displayName(primarySegments, parameter);
@@ -158,7 +159,10 @@ export class CommandIndex {
 
       if (alias) {
         for (const entry of alias) {
-          const aliasSegments = aliasRuntimeSegments(slot.owner, entry, primarySegments);
+          const aliasSegments = [...namespace, ...aliasRuntimeSegments(
+            entry,
+            primarySegments.slice(namespace.length),
+          )];
           assertParameterSegment(aliasSegments, parameter, `${slot.source} alias ${JSON.stringify(entry)}`);
           claim(occupancyKey(aliasSegments, parameter), `${slot.source} alias ${JSON.stringify(entry)}`);
           routes.push({
@@ -172,7 +176,7 @@ export class CommandIndex {
 
       if (slot.definition.shortcut) {
         for (const [rawTrigger, prefill] of Object.entries(slot.definition.shortcut)) {
-          const trigger = rawTrigger.trim();
+          const trigger = [...namespace, ...splitCommand(rawTrigger)].join(' ');
           claim(trigger, `${slot.source} shortcut ${JSON.stringify(trigger)}`);
           shortcuts.set(trigger, {
             record,
@@ -456,31 +460,43 @@ export function isCommandIndex(value: unknown): value is CommandIndex {
 }
 
 /**
- * 命令运行时名 = 插件树路径段（instanceKey，去掉 root）以 `.` 连接后，再与命令
- * 文件路径首段以 `.` 连接；命令内部嵌套段仍为空格分隔。Root 插件无前缀。
- * 例：`root/qq` + `endpoint/list` → `qq.endpoint list`；
- * `root/b/a` + `foo` → `b.a.foo`；root + `foo` → `foo`。
+ * 用户路由来自命令的本地能力路径；只有插件配置显式声明 commandNamespace
+ * 时才在其前面增加命名空间。owner 始终只属于 CapabilityId。
  */
-function runtimeSegments(owner: string, localName: string): string[] {
-  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 runtimeSegments(localName: string): string[] {
+  return localName.split('/');
+}
+
+function commandNamespace(snapshot: RuntimeSnapshot, owner: PluginId): readonly string[] {
+  const config = snapshot.config.get(owner) as Readonly<Record<string, unknown>> | undefined;
+  const value = config?.commandNamespace;
+  if (value === undefined || value === '') return Object.freeze([]);
+  if (typeof value !== 'string') {
+    throw new TypeError(`Invalid commandNamespace for ${owner}: expected a string`);
+  }
+  const segments = splitCommand(value);
+  if (segments.length === 0 || segments.some((segment) => !isCommandNamespaceSegment(segment))) {
+    throw new TypeError(
+      `Invalid commandNamespace for ${owner}: expected space-separated command segments`,
+    );
+  }
+  return Object.freeze([...segments]);
+}
+
+function isCommandNamespaceSegment(value: string): boolean {
+  return /^[\p{L}\p{N}][\p{L}\p{N}_-]*$/u.test(value);
 }
 
 /**
- * 用 alias 词序列替换全部本地静态段，再按 owner 规则重挂前缀；动态段保留。
+ * 用 alias 词序列替换全部本地静态段；动态段保留。
  */
 function aliasRuntimeSegments(
-  owner: string,
   alias: string,
   primarySegments: readonly string[],
 ): string[] {
   const aliasTokens = alias.trim().split(/\s+/u).filter(Boolean);
   const dynamicTail = primarySegments.filter((segment) => segment.startsWith('$'));
-  if (owner === 'root') return [...aliasTokens, ...dynamicTail];
-  const prefix = owner.slice('root/'.length).split('/').join('.');
-  return [`${prefix}.${aliasTokens[0]}`, ...aliasTokens.slice(1), ...dynamicTail];
+  return [...aliasTokens, ...dynamicTail];
 }
 
 function occupancyKey(
@@ -578,11 +594,10 @@ function assertParameterSegment(
   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). `
+    + `segment and be the final path segment. `
     + (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".'),
+      ? `Hint: keep only one dynamic entry, e.g. "commands/add/[${parameter.name}]/index.ts".`
+      : 'Hint: keep only one dynamic entry at the end of the command path.'),
   );
 }
 

package/src/definition.ts

@@ -261,8 +261,8 @@ export interface CommandDefinition<
    */
   readonly params?: Readonly<Record<string, CommandParamSchema>>;
   /**
-   * 本地静态段别名（可多词，如 `'gh issue'`）。替换全部本地静态段后仍挂
-   * owner 前缀；不打破子插件命名空间。
+   * 本地静态段别名（可多词，如 `'gh issue'`）。Capability owner 不参与
+   * 用户路由；alias 只替换文件路径提供的静态段。
    */
   readonly alias?: readonly string[];
   /**
@@ -272,7 +272,7 @@ export interface CommandDefinition<
   readonly permit?: readonly string[];
   /**
    * 全局整句快捷方式：触发串（trim 后全文相等）→ 预填 params。
-   * 可打破 owner 命名空间。
+   * 与普通路由一样是全局用户输入，冲突会在 generation 构建时拒绝。
    */
   readonly shortcut?: Readonly<Record<string, Readonly<Record<string, CommandDynamicValue>>>>;
   execute(context: CommandContext<TConfig, TInput, TAdapter>): TResult | Promise<TResult>;

package/src/provider.ts

@@ -1,4 +1,4 @@
-import { basename, join, parse, sep } from 'node:path';
+import { basename, dirname, join, sep } from 'node:path';
 import { featureId, isCapabilityLocalSegment } from '@zhin.js/plugin-runtime';
 import {
   defineFeatureProvider,
@@ -20,12 +20,19 @@ const commandFiles: SourceConvention = {
   id: 'commands-ts',
   async *discover(context) {
     const directory = join(context.packageRoot, 'commands');
-    yield* discoverCommandDirectory(context, directory, []);
+    const entries = [...await context.host.list(directory)]
+      .filter((entry) => entry.kind === 'directory')
+      .sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const segment = parseCommandDirectory(entry.name);
+      if (!segment) continue;
+      yield* discoverCommandDirectory(context, join(directory, entry.name), [segment]);
+    }
   },
   async load(source, context) {
     const module = await context.host.loadModule<{ default?: unknown }>(source.source);
     const definition = parseCommandDefinition(module.default);
-    const file = parseCommandFile(basename(source.source));
+    const file = parseCommandDirectory(basename(dirname(source.source)));
     return bindCommandParameter(definition, resolveParameter(definition, file, source.source));
   },
 };
@@ -33,45 +40,30 @@ const commandFiles: SourceConvention = {
 async function* discoverCommandDirectory(
   context: DiscoveryContext,
   directory: string,
-  ancestors: readonly string[],
+  ancestors: readonly ParsedCommandFile[],
 ): 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' && isCapabilityLocalSegment(entry.name)) {
-      yield* discoverCommandDirectory(
-        context,
-        join(directory, entry.name),
-        [...ancestors, entry.name],
-      );
-      continue;
-    }
-    if (entry.kind !== 'file') continue;
-    const file = parseCommandFile(entry.name);
-    if (!file) continue;
-    if (preferredFiles.get(file.localSegment) !== entry.name) continue;
+  const index = preferredCommandIndex(entries, preferJavaScript);
+  if (index) {
     yield {
-      localName: [...ancestors, file.localSegment].join('/'),
-      source: join(directory, entry.name),
+      localName: ancestors.map((segment) => segment.localSegment).join('/'),
+      source: join(directory, index),
+      relatedSources: Object.freeze(entries
+        .filter((entry) => entry.kind === 'file' && entry.name !== index)
+        .map((entry) => join(directory, entry.name))),
       target: 'server',
     };
   }
+  for (const entry of entries) {
+    if (entry.kind !== 'directory') continue;
+    const segment = parseCommandDirectory(entry.name);
+    if (!segment) continue;
+    yield* discoverCommandDirectory(context, join(directory, entry.name), [...ancestors, segment]);
+  }
 }
 
 interface ParsedCommandFile {
@@ -97,18 +89,9 @@ const dynamicCommandFilePatterns: ReadonlyArray<{
   { pattern: /^\[([a-zA-Z][a-zA-Z0-9]*)\]\.(?:tsx?|[cm]?js)$/, optional: false, rest: false },
 ];
 
-const commandModuleExtension = /\.(?:tsx?|[cm]?js)$/u;
-
-function parseCommandFile(value: string): ParsedCommandFile | undefined {
-  // 静态段：ASCII kebab（hello.ts）或 Unicode 名（赞我.ts）；与 isCapabilityLocalSegment 对齐。
-  if (commandModuleExtension.test(value)) {
-    const localSegment = parse(value).name;
-    if (isCapabilityLocalSegment(localSegment)) {
-      return { localSegment };
-    }
-  }
+function parseCommandDirectory(value: string): ParsedCommandFile | undefined {
   for (const { pattern, optional, rest } of dynamicCommandFilePatterns) {
-    const match = pattern.exec(value);
+    const match = pattern.exec(`${value}.ts`);
     if (!match || !match[1]) continue;
     const name = match[1];
     // Metadata can change during HMR while $name keeps the Capability identity stable.
@@ -117,6 +100,9 @@ function parseCommandFile(value: string): ParsedCommandFile | undefined {
       parameter: { name, optional, rest },
     };
   }
+  if (isCapabilityLocalSegment(value)) {
+    return { localSegment: value };
+  }
   if (value.startsWith('[') || value.includes(']')) {
     throw new CommandPathSyntaxError(value);
   }
@@ -141,7 +127,7 @@ function resolveParameter(
   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}]]`,
+      `params.${hint.name} has a default but the directory is required: rename it to [[${hint.name}]]`,
     );
   }
   return {
@@ -163,10 +149,20 @@ function commandFilePriority(value: string, preferJavaScript: boolean): number {
   return priority < 0 ? Number.MAX_SAFE_INTEGER : priority;
 }
 
+function preferredCommandIndex(
+  entries: readonly { readonly name: string; readonly kind: 'file' | 'directory' }[],
+  preferJavaScript: boolean,
+): string | undefined {
+  return entries
+    .filter((entry) => entry.kind === 'file' && /^index\.(?:tsx?|[cm]?js)$/u.test(entry.name))
+    .sort((left, right) => commandFilePriority(left.name, preferJavaScript)
+      - commandFilePriority(right.name, preferJavaScript))[0]?.name;
+}
+
 export class CommandPathSyntaxError extends TypeError {
   constructor(
     file: string,
-    detail = 'expected [name].ts(x), [[name]].ts(x), [...name].ts(x) or [[...name]].ts(x)',
+    detail = 'expected commands/foo/index.ts or commands/foo/[name]/index.ts',
   ) {
     super(`Invalid Command path ${file}: ${detail}`);
     this.name = 'CommandPathSyntaxError';