@zhin.js/command 1.1.8 → 1.1.9

package/lib/command-index.d.ts

@@ -56,6 +56,11 @@ export declare class CommandIndex {
     dispatch(input: CommandMatchInput, source?: unknown, interactionFactory?: UserInteractionFactory, commandPrefix?: string, operationSnapshot?: RuntimeSnapshot): Promise<CommandDispatchResult>;
 }
 export declare function isCommandIndex(value: unknown): value is CommandIndex;
+/**
+ * Route-shape rule for a convention command: at most one dynamic segment, and it is the final one.
+ * Shared by the runtime index and {@link bindCommandSource}.
+ */
+export declare function assertParameterSegment(segments: readonly string[], parameter: CommandParameterDefinition | undefined, source: string): void;
 export declare class CommandParameterValueError extends TypeError {
     constructor(name: string, type: CommandParameterType, value: string);
 }

package/lib/command-index.js

@@ -5,7 +5,7 @@ import { permissionHostToken, } from '@zhin.js/permission';
 import { commandAdapterMatches, toCommandPermissionSubject } from './permission-explanation.js';
 import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp } from './arguments.js';
 import { MENU_PAGE_SIZE, readMenuAppearance, renderCommandMenu } from './command-menu.js';
-import { admitCommandExecution } from './execution-runtime.js';
+import { admitCommandExecution, admitDirectCommandExecution } from './execution-runtime.js';
 import { CommandExecutionLimitedError, normalizeExecutionPolicy } from './execution-policy.js';
 export { CommandExecutionLimitedError } from './execution-policy.js';
 import { createCommandContext, resolveCommandSession, resolveDynamicParams, } from './definition.js';
@@ -45,7 +45,15 @@ export class CommandIndex {
             for (const key of keys)
                 occupancy.set(key, source);
         };
+        const disabledByOwner = new Map();
         for (const slot of slots) {
+            let disabled = disabledByOwner.get(slot.owner);
+            if (!disabled) {
+                disabled = disabledCommands(this.snapshot, slot.owner);
+                disabledByOwner.set(slot.owner, disabled);
+            }
+            if (isDisabledCommand(slot.localName, disabled))
+                continue;
             const namespace = commandNamespace(this.snapshot, slot.owner);
             const primarySegments = [...namespace, ...runtimeSegments(slot.localName)];
             const parameter = slot.definition.$parameter;
@@ -148,10 +156,16 @@ export class CommandIndex {
         const parsed = parseCommandArguments(definition, supplied, resolveDynamicParams(match.params, undefined), {});
         if (parsed.issues.length > 0)
             throw new CommandArgumentValidationError(parsed.issues, commandHelp(match.command.name, definition));
-        const limit = admitCommandExecution(undefined, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
-        if (limit)
-            throw new CommandExecutionLimitedError(limit);
-        return definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
+        // No inbound source: execution policy applies per command, never as a blanket refusal.
+        const admission = admitDirectCommandExecution(match.command.slot.id, match.command.execution, operationSnapshot);
+        if (admission.limit)
+            throw new CommandExecutionLimitedError(admission.limit);
+        try {
+            return await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
+        }
+        finally {
+            admission.release();
+        }
     }
     async dispatch(input, source = undefined, interactionFactory, commandPrefix = '', operationSnapshot = this.snapshot) {
         if (this.#menu) {
@@ -440,6 +454,27 @@ function commandNamespace(snapshot, owner) {
     }
     return Object.freeze([...segments]);
 }
+/**
+ * 插件实例配置 disabledCommands 列出的指令不进入路由表。条目写插件本地的静态路径
+ * （不含 commandNamespace 与参数段，如 `fanyi`、`netease login`）；写上级路径会连同
+ * 其子命令一起禁用。未匹配任何指令的条目被忽略。
+ */
+function disabledCommands(snapshot, owner) {
+    const config = snapshot.config.get(owner);
+    const value = config?.disabledCommands;
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new TypeError(`Invalid disabledCommands for ${owner}: expected an array of command names`);
+    }
+    return Object.freeze(value.map((entry) => splitCommand(entry).join(' ')).filter(Boolean));
+}
+function isDisabledCommand(localName, disabled) {
+    if (disabled.length === 0)
+        return false;
+    const path = runtimeSegments(localName).filter((segment) => !segment.startsWith('$')).join(' ');
+    return disabled.some((entry) => path === entry || path.startsWith(`${entry} `));
+}
 function isCommandNamespaceSegment(value) {
     return /^[\p{L}\p{N}][\p{L}\p{N}_-]*$/u.test(value);
 }
@@ -566,7 +601,11 @@ function exactMessageText(input) {
     const trimmed = only.data.text.trim();
     return trimmed || undefined;
 }
-function assertParameterSegment(segments, parameter, source) {
+/**
+ * Route-shape rule for a convention command: at most one dynamic segment, and it is the final one.
+ * Shared by the runtime index and {@link bindCommandSource}.
+ */
+export function assertParameterSegment(segments, parameter, source) {
     const dynamicSegments = segments.filter((segment) => segment.startsWith('$'));
     if (!parameter && dynamicSegments.length === 0)
         return;

package/lib/definition.d.ts

@@ -282,7 +282,16 @@ type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extend
     readonly params: keyof P extends never ? Readonly<Record<string, CommandParameterValue>> : InferCommandParams<P>;
     readonly options: InferCommandOptions<O>;
 };
+/**
+ * `defineCommand.withConfig<Config>()` 返回的定义函数：config 类型已固定，params / options / 返回值
+ * 仍从定义推断。
+ * @public
+ */
+export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <TResult = unknown, const P extends CommandParams = {}, const O extends CommandOptions = {}>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>) => Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
 export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage, const P extends CommandParams = {}, const O extends CommandOptions = {}>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
+export declare namespace defineCommand {
+    var withConfig: <TConfig = unknown, TInput extends CommandMessage = CommandMessage>() => CommandDefiner<TConfig, TInput>;
+}
 /** @internal Convention-loader assembly helper. */
 export declare function bindCommandParameter<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined>(definition: CommandDefinition<TConfig, TResult, TInput, TAdapter>, parameter: CommandParameterDefinition | undefined): Readonly<CommandDefinition<TConfig, TResult, TInput, TAdapter>>;
 /** @internal Runtime validation for convention-discovered modules. */

package/lib/definition.js

@@ -43,6 +43,24 @@ export function defineCommand(definition) {
     const execution = normalizeExecutionPolicy(definition.execution);
     return Object.freeze({ $feature: commandBrand, ...definition, ...(execution ? { execution } : {}) });
 }
+/**
+ * 先固定插件 config 类型，再定义命令；params / options / 返回值仍从定义推断。
+ *
+ * ```ts
+ * export default defineCommand.withConfig<Config>()({
+ *   params: { count: { type: 'integer' } },
+ *   execute({ params, config }) { params.count; config.prefix },
+ * })
+ * ```
+ *
+ * `defineCommand<Config>({...})` 仍然可用，但 TypeScript 不支持部分推断，显式写了
+ * 类型参数后 params 会退化成 `Record<string, CommandParameterValue>`。
+ * 这里是独立的属性而不是 `defineCommand()` 重载：`defineCommand` 常被当作值传给
+ * `createEndpointCommands(spec, defineCommand)` 这类工厂，重载会让它推断错签名。
+ */
+defineCommand.withConfig = function withConfig() {
+    return (definition) => defineCommand(definition);
+};
 function validateAdapterName(adapter) {
     if (adapter !== undefined && (typeof adapter !== 'string' || adapter.trim() === '')) {
         throw new TypeError('Command adapter must be a non-empty string');

package/lib/execution-runtime.d.ts

@@ -16,7 +16,20 @@ interface ConversationIdentity {
 }
 interface AdmissionReader {
     admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined;
+    /**
+     * Programmatic call with no inbound source (e.g. `CommandIndex.execute`). The policy is keyed by command only:
+     * there is no sender or conversation to budget, and no reply channel for progress feedback.
+     * On success the caller must invoke `release` once the execution settles.
+     */
+    admitDirect(capability: string, policy: CommandExecutionPolicy): DirectAdmission;
 }
+type DirectAdmission = {
+    readonly limit: CommandExecutionLimit;
+    readonly release?: undefined;
+} | {
+    readonly limit?: undefined;
+    readonly release: () => void;
+};
 /** @internal Admission-only Root resource; no bind or finish authority is published. */
 export declare const commandExecutionAdmissionToken: import("@zhin.js/plugin-runtime").Token<AdmissionReader>;
 /** @internal Held only by Core's actual leased operation. */
@@ -47,4 +60,6 @@ export declare class CommandExecutionBudget {
 }
 /** @internal Projection reads the Root resource; ordinary authoring values cannot bind an operation. */
 export declare function admitCommandExecution(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy | undefined, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined;
+/** @internal Programmatic (source-less) admission: keyed by command only, never refused for lacking a source. */
+export declare function admitDirectCommandExecution(capability: string, policy: CommandExecutionPolicy | undefined, snapshot: RuntimeSnapshot): DirectAdmission;
 export {};

package/lib/execution-runtime.js

@@ -14,7 +14,8 @@ export class CommandExecutionBudget {
         this.#capacity = options.capacity ?? 10_000;
         if (!Number.isSafeInteger(this.#capacity) || this.#capacity < 1)
             throw new TypeError('Invalid command budget capacity');
-        this.admission = Object.freeze({ admit: (source, capability, owner, policy, snapshot) => this.#admit(source, capability, owner, policy, snapshot) });
+        this.admission = Object.freeze({ admit: (source, capability, owner, policy, snapshot) => this.#admit(source, capability, owner, policy, snapshot),
+            admitDirect: (capability, policy) => this.#admitDirect(capability, policy) });
     }
     openOperation(input) {
         const c = input.conversation;
@@ -67,41 +68,66 @@ export class CommandExecutionBudget {
             },
         });
     }
-    #admit(source, capability, owner, policy, snapshot) {
-        const binding = source !== null && typeof source === 'object' ? this.#views.get(source) : undefined;
-        const operation = binding?.operation;
-        if (!operation?.active || operation.snapshot !== snapshot || binding?.owner !== owner || operation.signal.aborted)
-            return limited('operation_unavailable');
-        if (!operation.key)
-            return limited('identity_unavailable');
-        const key = JSON.stringify([capability, ...operation.key]);
-        // Re-entering the same capability is a second attempt, rather than a second free execution.
+    #admitDirect(capability, policy) {
+        return this.#acquire(JSON.stringify([capability, 'direct']), policy);
+    }
+    /** Shared entry accounting: concurrency, cooldown and capacity. Returns a one-shot release on success. */
+    #acquire(key, policy) {
         const now = this.#clock();
         let entry = this.#entries.get(key);
         if (entry && policy.maxConcurrent !== undefined && entry.active >= policy.maxConcurrent)
-            return limited('busy');
+            return { limit: limited('busy') };
         if (entry && entry.cooldownUntil > now)
-            return Object.freeze({ reason: 'cooldown', retryAfterMs: Math.ceil(entry.cooldownUntil - now) });
+            return { limit: Object.freeze({ reason: 'cooldown', retryAfterMs: Math.ceil(entry.cooldownUntil - now) }) };
         if (!entry) {
             if (this.#entries.size >= this.#capacity) {
                 for (const [oldKey, old] of this.#entries)
                     if (old.active === 0 && old.cooldownUntil <= now)
                         this.#entries.delete(oldKey);
+                if (this.#entries.size >= this.#capacity) {
+                    // Still full of cooling identities: drop the oldest idle one. Forgetting a cooldown is acceptable;
+                    // refusing every new identity is not. Only entries with running operations are never evicted.
+                    for (const [oldKey, old] of this.#entries)
+                        if (old.active === 0) {
+                            this.#entries.delete(oldKey);
+                            break;
+                        }
+                }
                 if (this.#entries.size >= this.#capacity)
-                    return limited('capacity');
+                    return { limit: limited('capacity') };
             }
             entry = { active: 0, cooldownUntil: 0 };
             this.#entries.set(key, entry);
         }
         entry.active++;
-        operation.admitted = true;
         entry.cooldownUntil = now + (policy.cooldownMs ?? 0);
         const acceptedEntry = entry;
-        operation.releases.push(() => {
-            acceptedEntry.active--;
-            if (acceptedEntry.active === 0 && acceptedEntry.cooldownUntil <= this.#clock())
-                this.#entries.delete(key);
-        });
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                acceptedEntry.active--;
+                if (acceptedEntry.active === 0 && acceptedEntry.cooldownUntil <= this.#clock())
+                    this.#entries.delete(key);
+            },
+        };
+    }
+    #admit(source, capability, owner, policy, snapshot) {
+        const binding = source !== null && typeof source === 'object' ? this.#views.get(source) : undefined;
+        const operation = binding?.operation;
+        if (!operation?.active || operation.snapshot !== snapshot || binding?.owner !== owner || operation.signal.aborted)
+            return limited('operation_unavailable');
+        if (!operation.key)
+            return limited('identity_unavailable');
+        const key = JSON.stringify([capability, ...operation.key]);
+        // Re-entering the same capability is a second attempt, rather than a second free execution.
+        const acquired = this.#acquire(key, policy);
+        if (acquired.limit)
+            return acquired.limit;
+        operation.admitted = true;
+        operation.releases.push(acquired.release);
         if (policy.progressAfterMs !== undefined && !operation.progressStopped && !operation.accepted.has(capability)) {
             const timer = setTimeout(() => {
                 operation.timers.delete(timer);
@@ -132,3 +158,10 @@ export function admitCommandExecution(source, capability, owner, policy, snapsho
     const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id);
     return reader ? reader.admit(source, capability, owner, policy, snapshot) : limited('service_unavailable');
 }
+/** @internal Programmatic (source-less) admission: keyed by command only, never refused for lacking a source. */
+export function admitDirectCommandExecution(capability, policy, snapshot) {
+    if (!policy)
+        return { release: () => { } };
+    const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id);
+    return reader ? reader.admitDirect(capability, policy) : { limit: limited('service_unavailable') };
+}

package/lib/index.d.ts

@@ -7,7 +7,7 @@ export * from './command-index.js';
 /** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
 export * from './permission-explanation.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 { CONVERSATION_MANAGER_PERMIT, canManageConversation, assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, type ParsedPermit, type PermitKind, } from './permit.js';
+export { bindCommandSource, CommandPathSyntaxError, commandFeatureId, type BoundCommandSource, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';
 export type { CommandValidationIssue } from './arguments.js';

package/lib/index.js

@@ -7,6 +7,6 @@ export * from './command-index.js';
 /** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
 export * from './permission-explanation.js';
-export { assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, } from './permit.js';
-export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
+export { CONVERSATION_MANAGER_PERMIT, canManageConversation, assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, } from './permit.js';
+export { bindCommandSource, CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';

package/lib/permit.d.ts

@@ -2,4 +2,12 @@
  * Re-export permit 解析/校验 from @zhin.js/permission (SSOT)。
  * 保留 CommandSession 兼容签名供 command-index 过渡使用。
  */
+import { type PermissionSubject } from '@zhin.js/permission';
+/** 会话管理者：群主 / 群管理员 / 机器人主人（适配器投影的规范角色名）。 */
+export declare const CONVERSATION_MANAGER_PERMIT = "role(owner,admin,master)";
+/**
+ * 「私聊，或 owner / admin / master」。`permit` 列表只支持 AND，
+ * 订阅类命令需要这个 OR 规则时用它，并以命令会话的 `scene` / `sender.role` 为输入。
+ */
+export declare function canManageConversation(subject: PermissionSubject): boolean;
 export { type PermitKind, type ParsedPermit, parsePermitName, isBuiltinPermit, isPlatformPermit, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';

package/lib/permit.js

@@ -2,4 +2,15 @@
  * Re-export permit 解析/校验 from @zhin.js/permission (SSOT)。
  * 保留 CommandSession 兼容签名供 command-index 过渡使用。
  */
+import { checkBuiltinPermit } from '@zhin.js/permission';
+/** 会话管理者：群主 / 群管理员 / 机器人主人（适配器投影的规范角色名）。 */
+export const CONVERSATION_MANAGER_PERMIT = 'role(owner,admin,master)';
+/**
+ * 「私聊，或 owner / admin / master」。`permit` 列表只支持 AND，
+ * 订阅类命令需要这个 OR 规则时用它，并以命令会话的 `scene` / `sender.role` 为输入。
+ */
+export function canManageConversation(subject) {
+    return checkBuiltinPermit('private()', subject)
+        || checkBuiltinPermit(CONVERSATION_MANAGER_PERMIT, subject);
+}
 export { parsePermitName, isBuiltinPermit, isPlatformPermit, assertPermitSyntax as assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, } from '@zhin.js/permission';

package/lib/provider.d.ts

@@ -1,6 +1,21 @@
 import { CommandIndex } from './command-index.js';
 import { type CommandDefinition } from './definition.js';
 export declare const commandFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
+export interface BoundCommandSource<TDefinition> {
+    /** Plugin-local name the runtime registers, e.g. `term/$word`. */
+    readonly localName: string;
+    /** The definition with `$parameter` bound from the directory shape, as the runtime loads it. */
+    readonly definition: TDefinition;
+}
+/**
+ * Apply the runtime's convention-path rules to one command module: directory syntax
+ * (`[name]`, `[[name]]`, `[...name]`, `[[...name]]`), the `params` declaration the directory
+ * implies, and the route shape (one dynamic segment, last). `source` is the command's `index`
+ * file or its directory; everything after the last `commands` directory is the command path.
+ * Throws the same errors discovery, loading and the command index throw.
+ */
+export declare function bindCommandSource<TDefinition extends CommandDefinition>(value: TDefinition, source: string): BoundCommandSource<TDefinition>;
+export declare function bindCommandSource(value: unknown, source: string): BoundCommandSource<CommandDefinition>;
 export declare class CommandPathSyntaxError extends TypeError {
     constructor(file: string, detail?: string);
 }

package/lib/provider.js

@@ -1,7 +1,7 @@
-import { basename, dirname, join, sep } from 'node:path';
+import { basename, dirname, join, relative, 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';
+import { CommandIndex, assertParameterSegment } from './command-index.js';
 import { bindCommandParameter, parseCommandDefinition, } from './definition.js';
 export const commandFeatureId = featureId('zhin.command');
 const commandFiles = {
@@ -21,6 +21,8 @@ const commandFiles = {
     async load(source, context) {
         const module = await context.host.loadModule(source.source);
         const definition = parseCommandDefinition(module.default);
+        const commandDirectories = commandDirectoriesOf(context.packageRoot, source.source);
+        assertSingleTrailingParameterDirectory(commandDirectories, source.source);
         const file = parseCommandDirectory(basename(dirname(source.source)));
         return bindCommandParameter(definition, resolveParameter(definition, file, source.source));
     },
@@ -77,6 +79,63 @@ function parseCommandDirectory(value) {
     }
     return undefined;
 }
+/** Directory segments between `commands/` and the command's `index.*` file. */
+function commandDirectoriesOf(packageRoot, source) {
+    const commandsRoot = join(packageRoot, 'commands');
+    const commandDirectory = dirname(source);
+    return relative(commandsRoot, commandDirectory)
+        .split(sep)
+        .filter((segment) => segment !== '');
+}
+/**
+ * A command path may contain at most one parameter directory, and it must be the
+ * last directory before `index.*`. Further arguments belong in `defineCommand({ params })`.
+ */
+function assertSingleTrailingParameterDirectory(directories, source) {
+    const parameterDirectories = [];
+    directories.forEach((directory, position) => {
+        const hint = parseCommandDirectory(directory)?.parameter;
+        if (hint)
+            parameterDirectories.push({ position, directory, hint });
+    });
+    const [keptDirectory, ...movedDirectories] = parameterDirectories;
+    if (!keptDirectory)
+        return;
+    const lastPosition = directories.length - 1;
+    if (movedDirectories.length === 0 && keptDirectory.position === lastPosition)
+        return;
+    throw new CommandPathSyntaxError(source, describeParameterDirectoryRule(directories, keptDirectory, movedDirectories));
+}
+function describeParameterDirectoryRule(directories, keptDirectory, movedDirectories) {
+    const parameterDirectories = [keptDirectory, ...movedDirectories];
+    const currentPath = `commands/${directories.join('/')}/index.ts`;
+    const foundDirectories = parameterDirectories.map((entry) => entry.directory).join(', ');
+    const staticDirectories = directories.filter((_directory, position) => !parameterDirectories.some((entry) => entry.position === position));
+    const suggestedPath = `commands/${[...staticDirectories, keptDirectory.directory].join('/')}/index.ts`;
+    const suggestedParams = parameterDirectories
+        .map((entry) => describeParamDeclaration(entry.hint))
+        .join(', ');
+    const movedNote = movedDirectories.length > 0
+        ? `move ${movedDirectories.map((entry) => entry.directory).join(', ')} into defineCommand({ params })`
+        : 'move the parameter directory to the end of the path';
+    return `only the last directory of a command path may be a parameter directory `
+        + `([name], [[name]], [...name] or [[...name]]), and a command may have at most one; `
+        + `found ${foundDirectories} in ${currentPath}. `
+        + `Fix: ${movedNote}, e.g. ${suggestedPath} with `
+        + `defineCommand({ params: { ${suggestedParams} } }) `
+        + `(the directory parameter must be listed first). `
+        + 'See https://zhin.js.org/authoring/commands#目录参数规则';
+}
+function describeParamDeclaration(hint) {
+    const type = hint.rest ? 'text' : 'string';
+    const flags = [];
+    if (hint.optional)
+        flags.push('optional: true');
+    if (hint.rest)
+        flags.push('rest: true');
+    const flagText = flags.map((flag) => `, ${flag}`).join('');
+    return `${hint.name}: { type: '${type}'${flagText} }`;
+}
 /** 把文件名形态与 `definition.params` 合并成完整参数定义。 */
 function resolveParameter(definition, file, source) {
     const hint = file?.parameter;
@@ -86,8 +145,13 @@ function resolveParameter(definition, file, source) {
     if (!schema) {
         throw new CommandPathSyntaxError(source, `missing params.${hint.name} declaration in defineCommand({ params })`);
     }
-    if (Object.keys(definition.params ?? {})[0] !== hint.name) {
-        throw new CommandPathSyntaxError(source, `params.${hint.name} must be the first parameter declaration`);
+    const declaredNames = Object.keys(definition.params ?? {});
+    if (declaredNames[0] !== hint.name) {
+        const reorderedNames = [hint.name, ...declaredNames.filter((name) => name !== hint.name)];
+        throw new CommandPathSyntaxError(source, `params.${hint.name} must be the first parameter declaration: the parameter directory `
+            + `binds the first argument after the command name, so it has to come first in `
+            + `defineCommand({ params }). Current order: { ${declaredNames.join(', ')} }; `
+            + `reorder to { ${reorderedNames.join(', ')} }`);
     }
     if (schema.rest !== undefined && schema.rest !== hint.rest
         || schema.optional !== undefined && schema.optional !== hint.optional) {
@@ -119,6 +183,26 @@ function preferredCommandIndex(entries, preferJavaScript) {
         .sort((left, right) => commandFilePriority(left.name, preferJavaScript)
         - commandFilePriority(right.name, preferJavaScript))[0]?.name;
 }
+export function bindCommandSource(value, source) {
+    const directory = /^index\.(?:tsx?|[cm]?js)$/u.test(basename(source)) ? dirname(source) : source;
+    const parts = directory.split(/[\\/]/u).filter(Boolean);
+    const commandsAt = parts.lastIndexOf('commands');
+    if (commandsAt < 0 || commandsAt === parts.length - 1) {
+        throw new CommandPathSyntaxError(source, 'expected a path under commands/, e.g. commands/foo/index.ts');
+    }
+    const segments = parts.slice(commandsAt + 1).map((name) => {
+        const segment = parseCommandDirectory(name);
+        if (!segment) {
+            throw new CommandPathSyntaxError(source, `"${name}" is not a command directory name, so the runtime does not discover it`);
+        }
+        return segment;
+    });
+    const definition = parseCommandDefinition(value);
+    const bound = bindCommandParameter(definition, resolveParameter(definition, segments.at(-1), source));
+    const localName = segments.map((segment) => segment.localSegment).join('/');
+    assertParameterSegment(localName.split('/'), bound.$parameter, source);
+    return Object.freeze({ localName, definition: bound });
+}
 export class CommandPathSyntaxError extends TypeError {
     constructor(file, detail = 'expected commands/foo/index.ts or commands/foo/[name]/index.ts') {
         super(`Invalid Command path ${file}: ${detail}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -21,8 +21,8 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.1.6",
     "@zhin.js/interaction": "1.1.2",
+    "@zhin.js/feature-kit": "1.1.7",
     "@zhin.js/permission": "1.1.7",
     "@zhin.js/plugin-runtime": "1.1.15"
   },

package/src/command-index.ts

@@ -19,7 +19,7 @@ import {
 import { commandAdapterMatches, toCommandPermissionSubject } from './permission-explanation.js';
 import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp, type CommandValidationIssue } from './arguments.js';
 import { MENU_PAGE_SIZE, readMenuAppearance, renderCommandMenu, type CommandMenuSegment } from './command-menu.js';
-import { admitCommandExecution } from './execution-runtime.js';
+import { admitCommandExecution, admitDirectCommandExecution } from './execution-runtime.js';
 import { CommandExecutionLimitedError, normalizeExecutionPolicy, type CommandExecutionLimit } from './execution-policy.js';
 export { CommandExecutionLimitedError } from './execution-policy.js';
 import {
@@ -153,7 +153,14 @@ export class CommandIndex {
       for (const key of keys) occupancy.set(key, source);
     };
 
+    const disabledByOwner = new Map<PluginId, readonly string[]>();
     for (const slot of slots) {
+      let disabled = disabledByOwner.get(slot.owner);
+      if (!disabled) {
+        disabled = disabledCommands(this.snapshot, slot.owner);
+        disabledByOwner.set(slot.owner, disabled);
+      }
+      if (isDisabledCommand(slot.localName, disabled)) continue;
       const namespace = commandNamespace(this.snapshot, slot.owner);
       const primarySegments = [...namespace, ...runtimeSegments(slot.localName)];
       const parameter = slot.definition.$parameter;
@@ -268,10 +275,15 @@ export class CommandIndex {
     const supplied = [...match.remaining, ...(args.length > 0 ? [{ type: 'text', data: { text: args.join(' ') } }] : [])];
     const parsed = parseCommandArguments(definition, supplied, resolveDynamicParams(match.params, undefined), {});
     if (parsed.issues.length > 0) throw new CommandArgumentValidationError(parsed.issues, commandHelp(match.command.name, definition));
-    const limit = admitCommandExecution(undefined, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
-    if (limit) throw new CommandExecutionLimitedError(limit);
-    return definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner,
-      textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
+    // No inbound source: execution policy applies per command, never as a blanket refusal.
+    const admission = admitDirectCommandExecution(match.command.slot.id, match.command.execution, operationSnapshot);
+    if (admission.limit) throw new CommandExecutionLimitedError(admission.limit);
+    try {
+      return await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner,
+        textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
+    } finally {
+      admission.release();
+    }
   }
 
   async dispatch(
@@ -560,6 +572,27 @@ function commandNamespace(snapshot: RuntimeSnapshot, owner: PluginId): readonly
   return Object.freeze([...segments]);
 }
 
+/**
+ * 插件实例配置 disabledCommands 列出的指令不进入路由表。条目写插件本地的静态路径
+ * （不含 commandNamespace 与参数段，如 `fanyi`、`netease login`）；写上级路径会连同
+ * 其子命令一起禁用。未匹配任何指令的条目被忽略。
+ */
+function disabledCommands(snapshot: RuntimeSnapshot, owner: PluginId): readonly string[] {
+  const config = snapshot.config.get(owner) as Readonly<Record<string, unknown>> | undefined;
+  const value = config?.disabledCommands;
+  if (value === undefined) return Object.freeze([]);
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    throw new TypeError(`Invalid disabledCommands for ${owner}: expected an array of command names`);
+  }
+  return Object.freeze(value.map((entry: string) => splitCommand(entry).join(' ')).filter(Boolean));
+}
+
+function isDisabledCommand(localName: string, disabled: readonly string[]): boolean {
+  if (disabled.length === 0) return false;
+  const path = runtimeSegments(localName).filter((segment) => !segment.startsWith('$')).join(' ');
+  return disabled.some((entry) => path === entry || path.startsWith(`${entry} `));
+}
+
 function isCommandNamespaceSegment(value: string): boolean {
   return /^[\p{L}\p{N}][\p{L}\p{N}_-]*$/u.test(value);
 }
@@ -699,7 +732,11 @@ function exactMessageText(input: CommandMatchInput): string | undefined {
   return trimmed || undefined;
 }
 
-function assertParameterSegment(
+/**
+ * Route-shape rule for a convention command: at most one dynamic segment, and it is the final one.
+ * Shared by the runtime index and {@link bindCommandSource}.
+ */
+export function assertParameterSegment(
   segments: readonly string[],
   parameter: CommandParameterDefinition | undefined,
   source: string,

package/src/definition.ts

@@ -360,6 +360,19 @@ type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extend
     readonly options: InferCommandOptions<O>;
   };
 
+/**
+ * `defineCommand.withConfig<Config>()` 返回的定义函数：config 类型已固定，params / options / 返回值
+ * 仍从定义推断。
+ * @public
+ */
+export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <
+  TResult = unknown,
+  const P extends CommandParams = {},
+  const O extends CommandOptions = {},
+>(
+  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
+) => Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
+
 export function defineCommand<
   TConfig = unknown,
   TResult = unknown,
@@ -394,6 +407,28 @@ export function defineCommand<
   >;
 }
 
+/**
+ * 先固定插件 config 类型，再定义命令；params / options / 返回值仍从定义推断。
+ *
+ * ```ts
+ * export default defineCommand.withConfig<Config>()({
+ *   params: { count: { type: 'integer' } },
+ *   execute({ params, config }) { params.count; config.prefix },
+ * })
+ * ```
+ *
+ * `defineCommand<Config>({...})` 仍然可用，但 TypeScript 不支持部分推断，显式写了
+ * 类型参数后 params 会退化成 `Record<string, CommandParameterValue>`。
+ * 这里是独立的属性而不是 `defineCommand()` 重载：`defineCommand` 常被当作值传给
+ * `createEndpointCommands(spec, defineCommand)` 这类工厂，重载会让它推断错签名。
+ */
+defineCommand.withConfig = function withConfig<
+  TConfig = unknown,
+  TInput extends CommandMessage = CommandMessage,
+>(): CommandDefiner<TConfig, TInput> {
+  return (definition) => defineCommand(definition);
+};
+
 function validateAdapterName(adapter: string | undefined): void {
   if (adapter !== undefined && (typeof adapter !== 'string' || adapter.trim() === '')) {
     throw new TypeError('Command adapter must be a non-empty string');

package/src/execution-runtime.ts

@@ -12,8 +12,16 @@ interface ConversationIdentity {
 
 interface AdmissionReader {
   admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined;
+  /**
+   * Programmatic call with no inbound source (e.g. `CommandIndex.execute`). The policy is keyed by command only:
+   * there is no sender or conversation to budget, and no reply channel for progress feedback.
+   * On success the caller must invoke `release` once the execution settles.
+   */
+  admitDirect(capability: string, policy: CommandExecutionPolicy): DirectAdmission;
 }
 
+type DirectAdmission = { readonly limit: CommandExecutionLimit; readonly release?: undefined } | { readonly limit?: undefined; readonly release: () => void };
+
 /** @internal Admission-only Root resource; no bind or finish authority is published. */
 export const commandExecutionAdmissionToken = createToken<AdmissionReader>('zhin.command.execution-admission');
 
@@ -56,7 +64,8 @@ export class CommandExecutionBudget {
     this.#clock = options.clock ?? (() => performance.now());
     this.#capacity = options.capacity ?? 10_000;
     if (!Number.isSafeInteger(this.#capacity) || this.#capacity < 1) throw new TypeError('Invalid command budget capacity');
-    this.admission = Object.freeze<AdmissionReader>({ admit: (source, capability, owner, policy, snapshot) => this.#admit(source, capability, owner, policy, snapshot) });
+    this.admission = Object.freeze<AdmissionReader>({ admit: (source, capability, owner, policy, snapshot) => this.#admit(source, capability, owner, policy, snapshot),
+      admitDirect: (capability, policy) => this.#admitDirect(capability, policy) });
   }
 
   openOperation(input: {
@@ -110,33 +119,54 @@ export class CommandExecutionBudget {
     });
   }
 
-  #admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined {
-    const binding = source !== null && typeof source === 'object' ? this.#views.get(source) : undefined;
-    const operation = binding?.operation;
-    if (!operation?.active || operation.snapshot !== snapshot || binding?.owner !== owner || operation.signal.aborted) return limited('operation_unavailable');
-    if (!operation.key) return limited('identity_unavailable');
-    const key = JSON.stringify([capability, ...operation.key]);
-    // Re-entering the same capability is a second attempt, rather than a second free execution.
+  #admitDirect(capability: string, policy: CommandExecutionPolicy): DirectAdmission {
+    return this.#acquire(JSON.stringify([capability, 'direct']), policy);
+  }
+
+  /** Shared entry accounting: concurrency, cooldown and capacity. Returns a one-shot release on success. */
+  #acquire(key: string, policy: CommandExecutionPolicy): DirectAdmission {
     const now = this.#clock();
     let entry = this.#entries.get(key);
-    if (entry && policy.maxConcurrent !== undefined && entry.active >= policy.maxConcurrent) return limited('busy');
-    if (entry && entry.cooldownUntil > now) return Object.freeze({ reason: 'cooldown', retryAfterMs: Math.ceil(entry.cooldownUntil - now) });
+    if (entry && policy.maxConcurrent !== undefined && entry.active >= policy.maxConcurrent) return { limit: limited('busy') };
+    if (entry && entry.cooldownUntil > now) return { limit: Object.freeze({ reason: 'cooldown', retryAfterMs: Math.ceil(entry.cooldownUntil - now) }) };
     if (!entry) {
       if (this.#entries.size >= this.#capacity) {
         for (const [oldKey, old] of this.#entries) if (old.active === 0 && old.cooldownUntil <= now) this.#entries.delete(oldKey);
-        if (this.#entries.size >= this.#capacity) return limited('capacity');
+        if (this.#entries.size >= this.#capacity) {
+          // Still full of cooling identities: drop the oldest idle one. Forgetting a cooldown is acceptable;
+          // refusing every new identity is not. Only entries with running operations are never evicted.
+          for (const [oldKey, old] of this.#entries) if (old.active === 0) { this.#entries.delete(oldKey); break; }
+        }
+        if (this.#entries.size >= this.#capacity) return { limit: limited('capacity') };
       }
       entry = { active: 0, cooldownUntil: 0 };
       this.#entries.set(key, entry);
     }
     entry.active++;
-    operation.admitted = true;
     entry.cooldownUntil = now + (policy.cooldownMs ?? 0);
     const acceptedEntry = entry;
-    operation.releases.push(() => {
-      acceptedEntry.active--;
-      if (acceptedEntry.active === 0 && acceptedEntry.cooldownUntil <= this.#clock()) this.#entries.delete(key);
-    });
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        acceptedEntry.active--;
+        if (acceptedEntry.active === 0 && acceptedEntry.cooldownUntil <= this.#clock()) this.#entries.delete(key);
+      },
+    };
+  }
+
+  #admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined {
+    const binding = source !== null && typeof source === 'object' ? this.#views.get(source) : undefined;
+    const operation = binding?.operation;
+    if (!operation?.active || operation.snapshot !== snapshot || binding?.owner !== owner || operation.signal.aborted) return limited('operation_unavailable');
+    if (!operation.key) return limited('identity_unavailable');
+    const key = JSON.stringify([capability, ...operation.key]);
+    // Re-entering the same capability is a second attempt, rather than a second free execution.
+    const acquired = this.#acquire(key, policy);
+    if (acquired.limit) return acquired.limit;
+    operation.admitted = true;
+    operation.releases.push(acquired.release);
     if (policy.progressAfterMs !== undefined && !operation.progressStopped && !operation.accepted.has(capability)) {
       const timer = setTimeout(() => {
         operation.timers.delete(timer);
@@ -163,3 +193,10 @@ export function admitCommandExecution(source: unknown, capability: string, owner
   const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id) as AdmissionReader | undefined;
   return reader ? reader.admit(source, capability, owner, policy, snapshot) : limited('service_unavailable');
 }
+
+/** @internal Programmatic (source-less) admission: keyed by command only, never refused for lacking a source. */
+export function admitDirectCommandExecution(capability: string, policy: CommandExecutionPolicy | undefined, snapshot: RuntimeSnapshot): DirectAdmission {
+  if (!policy) return { release: () => {} };
+  const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id) as AdmissionReader | undefined;
+  return reader ? reader.admitDirect(capability, policy) : { limit: limited('service_unavailable') };
+}

package/src/index.ts

@@ -8,6 +8,8 @@ export * from './command-index.js';
 export * from './definition.js';
 export * from './permission-explanation.js';
 export {
+  CONVERSATION_MANAGER_PERMIT,
+  canManageConversation,
   assertBuiltinPermits,
   checkBuiltinPermit,
   checkBuiltinPermitList,
@@ -18,8 +20,10 @@ export {
   type PermitKind,
 } from './permit.js';
 export {
+  bindCommandSource,
   CommandPathSyntaxError,
   commandFeatureId,
+  type BoundCommandSource,
   default as commandFeature,
 } from './provider.js';
 export { default } from './provider.js';

package/src/permit.ts

@@ -2,6 +2,20 @@
  * Re-export permit 解析/校验 from @zhin.js/permission (SSOT)。
  * 保留 CommandSession 兼容签名供 command-index 过渡使用。
  */
+import { checkBuiltinPermit, type PermissionSubject } from '@zhin.js/permission';
+
+/** 会话管理者：群主 / 群管理员 / 机器人主人（适配器投影的规范角色名）。 */
+export const CONVERSATION_MANAGER_PERMIT = 'role(owner,admin,master)';
+
+/**
+ * 「私聊，或 owner / admin / master」。`permit` 列表只支持 AND，
+ * 订阅类命令需要这个 OR 规则时用它，并以命令会话的 `scene` / `sender.role` 为输入。
+ */
+export function canManageConversation(subject: PermissionSubject): boolean {
+  return checkBuiltinPermit('private()', subject)
+    || checkBuiltinPermit(CONVERSATION_MANAGER_PERMIT, subject);
+}
+
 export {
   type PermitKind,
   type ParsedPermit,

package/src/provider.ts

@@ -1,4 +1,4 @@
-import { basename, dirname, join, sep } from 'node:path';
+import { basename, dirname, join, relative, sep } from 'node:path';
 import { featureId, isCapabilityLocalSegment } from '@zhin.js/plugin-runtime';
 import {
   defineFeatureProvider,
@@ -6,7 +6,7 @@ import {
   type DiscoveredSource,
   type SourceConvention,
 } from '@zhin.js/feature-kit';
-import { CommandIndex } from './command-index.js';
+import { CommandIndex, assertParameterSegment } from './command-index.js';
 import {
   bindCommandParameter,
   parseCommandDefinition,
@@ -32,6 +32,8 @@ const commandFiles: SourceConvention = {
   async load(source, context) {
     const module = await context.host.loadModule<{ default?: unknown }>(source.source);
     const definition = parseCommandDefinition(module.default);
+    const commandDirectories = commandDirectoriesOf(context.packageRoot, source.source);
+    assertSingleTrailingParameterDirectory(commandDirectories, source.source);
     const file = parseCommandDirectory(basename(dirname(source.source)));
     return bindCommandParameter(definition, resolveParameter(definition, file, source.source));
   },
@@ -109,6 +111,76 @@ function parseCommandDirectory(value: string): ParsedCommandFile | undefined {
   return undefined;
 }
 
+/** Directory segments between `commands/` and the command's `index.*` file. */
+function commandDirectoriesOf(packageRoot: string, source: string): string[] {
+  const commandsRoot = join(packageRoot, 'commands');
+  const commandDirectory = dirname(source);
+  return relative(commandsRoot, commandDirectory)
+    .split(sep)
+    .filter((segment) => segment !== '');
+}
+
+interface ParameterDirectory {
+  readonly position: number;
+  readonly directory: string;
+  readonly hint: CommandParameterHint;
+}
+
+/**
+ * A command path may contain at most one parameter directory, and it must be the
+ * last directory before `index.*`. Further arguments belong in `defineCommand({ params })`.
+ */
+function assertSingleTrailingParameterDirectory(directories: readonly string[], source: string): void {
+  const parameterDirectories: ParameterDirectory[] = [];
+  directories.forEach((directory, position) => {
+    const hint = parseCommandDirectory(directory)?.parameter;
+    if (hint) parameterDirectories.push({ position, directory, hint });
+  });
+  const [keptDirectory, ...movedDirectories] = parameterDirectories;
+  if (!keptDirectory) return;
+  const lastPosition = directories.length - 1;
+  if (movedDirectories.length === 0 && keptDirectory.position === lastPosition) return;
+  throw new CommandPathSyntaxError(
+    source,
+    describeParameterDirectoryRule(directories, keptDirectory, movedDirectories),
+  );
+}
+
+function describeParameterDirectoryRule(
+  directories: readonly string[],
+  keptDirectory: ParameterDirectory,
+  movedDirectories: readonly ParameterDirectory[],
+): string {
+  const parameterDirectories = [keptDirectory, ...movedDirectories];
+  const currentPath = `commands/${directories.join('/')}/index.ts`;
+  const foundDirectories = parameterDirectories.map((entry) => entry.directory).join(', ');
+  const staticDirectories = directories.filter((_directory, position) =>
+    !parameterDirectories.some((entry) => entry.position === position));
+  const suggestedPath = `commands/${[...staticDirectories, keptDirectory.directory].join('/')}/index.ts`;
+  const suggestedParams = parameterDirectories
+    .map((entry) => describeParamDeclaration(entry.hint))
+    .join(', ');
+  const movedNote = movedDirectories.length > 0
+    ? `move ${movedDirectories.map((entry) => entry.directory).join(', ')} into defineCommand({ params })`
+    : 'move the parameter directory to the end of the path';
+  return `only the last directory of a command path may be a parameter directory `
+    + `([name], [[name]], [...name] or [[...name]]), and a command may have at most one; `
+    + `found ${foundDirectories} in ${currentPath}. `
+    + `Fix: ${movedNote}, e.g. ${suggestedPath} with `
+    + `defineCommand({ params: { ${suggestedParams} } }) `
+    + `(the directory parameter must be listed first). `
+    + 'See https://zhin.js.org/authoring/commands#目录参数规则';
+}
+
+function describeParamDeclaration(hint: CommandParameterHint): string {
+  const type = hint.rest ? 'text' : 'string';
+  const flags: string[] = [];
+  if (hint.optional) flags.push('optional: true');
+  if (hint.rest) flags.push('rest: true');
+  const flagText = flags.map((flag) => `, ${flag}`).join('');
+  return `${hint.name}: { type: '${type}'${flagText} }`;
+}
+
 /** 把文件名形态与 `definition.params` 合并成完整参数定义。 */
 function resolveParameter(
   definition: CommandDefinition,
@@ -124,8 +196,16 @@ function resolveParameter(
       `missing params.${hint.name} declaration in defineCommand({ params })`,
     );
   }
-  if (Object.keys(definition.params ?? {})[0] !== hint.name) {
-    throw new CommandPathSyntaxError(source, `params.${hint.name} must be the first parameter declaration`);
+  const declaredNames = Object.keys(definition.params ?? {});
+  if (declaredNames[0] !== hint.name) {
+    const reorderedNames = [hint.name, ...declaredNames.filter((name) => name !== hint.name)];
+    throw new CommandPathSyntaxError(
+      source,
+      `params.${hint.name} must be the first parameter declaration: the parameter directory `
+        + `binds the first argument after the command name, so it has to come first in `
+        + `defineCommand({ params }). Current order: { ${declaredNames.join(', ')} }; `
+        + `reorder to { ${reorderedNames.join(', ')} }`,
+    );
   }
   if (schema.rest !== undefined && schema.rest !== hint.rest
     || schema.optional !== undefined && schema.optional !== hint.optional) {
@@ -166,6 +246,46 @@ function preferredCommandIndex(
       - commandFilePriority(right.name, preferJavaScript))[0]?.name;
 }
 
+export interface BoundCommandSource<TDefinition> {
+  /** Plugin-local name the runtime registers, e.g. `term/$word`. */
+  readonly localName: string;
+  /** The definition with `$parameter` bound from the directory shape, as the runtime loads it. */
+  readonly definition: TDefinition;
+}
+
+/**
+ * Apply the runtime's convention-path rules to one command module: directory syntax
+ * (`[name]`, `[[name]]`, `[...name]`, `[[...name]]`), the `params` declaration the directory
+ * implies, and the route shape (one dynamic segment, last). `source` is the command's `index`
+ * file or its directory; everything after the last `commands` directory is the command path.
+ * Throws the same errors discovery, loading and the command index throw.
+ */
+export function bindCommandSource<TDefinition extends CommandDefinition>(
+  value: TDefinition,
+  source: string,
+): BoundCommandSource<TDefinition>;
+export function bindCommandSource(value: unknown, source: string): BoundCommandSource<CommandDefinition>;
+export function bindCommandSource(value: unknown, source: string): BoundCommandSource<CommandDefinition> {
+  const directory = /^index\.(?:tsx?|[cm]?js)$/u.test(basename(source)) ? dirname(source) : source;
+  const parts = directory.split(/[\\/]/u).filter(Boolean);
+  const commandsAt = parts.lastIndexOf('commands');
+  if (commandsAt < 0 || commandsAt === parts.length - 1) {
+    throw new CommandPathSyntaxError(source, 'expected a path under commands/, e.g. commands/foo/index.ts');
+  }
+  const segments = parts.slice(commandsAt + 1).map((name) => {
+    const segment = parseCommandDirectory(name);
+    if (!segment) {
+      throw new CommandPathSyntaxError(source, `"${name}" is not a command directory name, so the runtime does not discover it`);
+    }
+    return segment;
+  });
+  const definition = parseCommandDefinition(value);
+  const bound = bindCommandParameter(definition, resolveParameter(definition, segments.at(-1), source));
+  const localName = segments.map((segment) => segment.localSegment).join('/');
+  assertParameterSegment(localName.split('/'), bound.$parameter, source);
+  return Object.freeze({ localName, definition: bound });
+}
+
 export class CommandPathSyntaxError extends TypeError {
   constructor(
     file: string,