@zhin.js/command 1.1.7 → 1.1.9

package/lib/definition.js

@@ -1,6 +1,7 @@
-import { createCapabilityContext, readOperationClient, } from '@zhin.js/feature-kit';
+import { createCapabilityContext, readOperationClient, readOperationInputSignal, } from '@zhin.js/feature-kit';
 import { assertPermitSyntax } from '@zhin.js/permission';
 import { validateArgumentSchemas } from './arguments.js';
+import { normalizeExecutionPolicy } from './execution-policy.js';
 const commandBrand = 'zhin.command/1';
 /** @internal Runtime validator lookup. */
 export const commandParameterTypes = new Set([
@@ -39,8 +40,27 @@ export function defineCommand(definition) {
     validateCommandAlias(definition.alias);
     validateCommandPermit(definition.permit);
     validateCommandShortcutShape(definition.shortcut);
-    return Object.freeze({ $feature: commandBrand, ...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');
@@ -106,6 +126,7 @@ export function parseCommandDefinition(value) {
         throw new TypeError('Command module must default-export defineCommand(...)');
     }
     validateAdapterName(definition.adapter);
+    normalizeExecutionPolicy(definition.execution);
     return definition;
 }
 /**
@@ -123,7 +144,7 @@ export function resolveDynamicParams(params, source) {
 }
 /** @internal Command dispatcher assembly helper. */
 export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction, adapter, options = Object.freeze({})) {
-    const context = createCapabilityContext(snapshot, ownerId);
+    const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
     const session = resolveCommandSession(input);
     const parameterValues = { __proto__: null, ...params };
     const optionValues = { __proto__: null, ...options };
@@ -158,7 +179,7 @@ export function resolveCommandSession(input) {
     const endpoint = input.endpointId
         || (typeof metadata?.endpoint === 'string' && metadata.endpoint ? metadata.endpoint : undefined);
     const scene = resolveScene(input, metadata);
-    const sender = resolveSender(input, metadata);
+    const sender = resolveCommandSender(input, metadata);
     return Object.freeze({
         ...(adapter ? { adapter } : {}),
         ...(endpoint !== undefined ? { endpoint } : {}),
@@ -194,7 +215,11 @@ function resolveScene(input, metadata) {
         ...(name !== undefined ? { name } : {}),
     });
 }
-function resolveSender(input, metadata) {
+/**
+ * Pure canonical sender projection shared with read-only command condition simulation.
+ * @internal Command dispatcher projection helper.
+ */
+export function resolveCommandSender(input, metadata) {
     const structured = input.from;
     if (isCommandSender(structured)) {
         return freezeSender(structured);

package/lib/execution-policy.d.ts

@@ -0,0 +1,18 @@
+/** Optional per-capability budget, isolated by sender and the complete conversation identity. */
+export interface CommandExecutionPolicy {
+    readonly cooldownMs?: number;
+    readonly maxConcurrent?: number;
+    /** One best-effort progress message while business logic is waiting; disabled by default. */
+    readonly progressAfterMs?: number;
+}
+export interface CommandExecutionLimit {
+    readonly reason: 'cooldown' | 'busy' | 'capacity' | 'operation_unavailable' | 'identity_unavailable' | 'service_unavailable';
+    /** Exact remaining cooldown; a busy operation has no predictable completion time. */
+    readonly retryAfterMs?: number;
+}
+export declare class CommandExecutionLimitedError extends Error {
+    readonly limit: CommandExecutionLimit;
+    constructor(limit: CommandExecutionLimit);
+}
+/** @internal Validate at declaration and projection, without coercion or silent clamping. */
+export declare function normalizeExecutionPolicy(value: unknown): Readonly<CommandExecutionPolicy> | undefined;

package/lib/execution-policy.js

@@ -0,0 +1,27 @@
+export class CommandExecutionLimitedError extends Error {
+    limit;
+    constructor(limit) {
+        super(`Command execution limited: ${limit.reason}`);
+        this.name = 'CommandExecutionLimitedError';
+        this.limit = limit;
+    }
+}
+/** @internal Validate at declaration and projection, without coercion or silent clamping. */
+export function normalizeExecutionPolicy(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Command execution must be an object');
+    const limits = { cooldownMs: 86_400_000, maxConcurrent: 1000, progressAfterMs: 3_600_000 };
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (!Object.hasOwn(limits, key) || !Number.isSafeInteger(item) || item <= 0
+            || item > limits[key]) {
+            throw new TypeError(`Command execution.${key} must be a positive bounded integer`);
+        }
+        result[key] = item;
+    }
+    if (Object.keys(result).length === 0)
+        throw new TypeError('Command execution requires at least one policy');
+    return Object.freeze(result);
+}

package/lib/execution-runtime.d.ts

@@ -0,0 +1,65 @@
+/** Internal composition contract. Not part of the command authoring facade. */
+import { type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { CommandExecutionLimit, CommandExecutionPolicy } from './execution-policy.js';
+interface ConversationIdentity {
+    readonly endpoint: {
+        readonly adapter: string;
+        readonly id: string;
+    };
+    readonly kind: string;
+    readonly id: string;
+    readonly parent?: {
+        readonly kind: string;
+        readonly id: string;
+    };
+    readonly threadId?: string;
+}
+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. */
+export interface CommandOperationController {
+    bind(view: object, owner: PluginId): void;
+    /** Core registers actual started delivery promises, never a caller-supplied completion callback. */
+    trackSend(send: Promise<unknown>): void;
+    /** Stop pending feedback and drain already-started feedback before the final reply. */
+    stopProgress(): Promise<void>;
+    /** Called only by the real outer operation's finally, after all final sends settle. */
+    finish(): Promise<void>;
+}
+/** @internal Root-instance-owned state shared by projections and draining retired generations. */
+export declare class CommandExecutionBudget {
+    #private;
+    readonly admission: AdmissionReader;
+    constructor(options?: {
+        readonly clock?: () => number;
+        readonly capacity?: number;
+    });
+    openOperation(input: {
+        readonly snapshot: RuntimeSnapshot;
+        readonly conversation: ConversationIdentity;
+        readonly senderId?: string;
+        readonly retirementSignal: AbortSignal;
+        readonly reply: (owner: PluginId, text: string) => Promise<unknown>;
+    }): CommandOperationController;
+}
+/** @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

@@ -0,0 +1,167 @@
+/** Internal composition contract. Not part of the command authoring facade. */
+import { createToken } from '@zhin.js/plugin-runtime';
+/** @internal Admission-only Root resource; no bind or finish authority is published. */
+export const commandExecutionAdmissionToken = createToken('zhin.command.execution-admission');
+/** @internal Root-instance-owned state shared by projections and draining retired generations. */
+export class CommandExecutionBudget {
+    #entries = new Map();
+    #views = new WeakMap();
+    #clock;
+    #capacity;
+    admission;
+    constructor(options = {}) {
+        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({ 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;
+        const values = [c.endpoint.adapter, c.endpoint.id, c.kind, c.id, c.parent?.kind ?? '', c.parent?.id ?? '', c.threadId ?? '', input.senderId ?? ''];
+        const valid = values.slice(0, 4).every(nonempty) && ['private', 'group', 'channel'].includes(c.kind) && nonempty(input.senderId)
+            && (c.parent === undefined || (nonempty(c.parent.kind) && nonempty(c.parent.id)))
+            && (c.threadId === undefined || nonempty(c.threadId)) && values.every(value => value.length <= 1024);
+        const operation = {
+            snapshot: input.snapshot, key: valid ? Object.freeze(values) : undefined,
+            active: true, progressStopped: false, admitted: false, signal: input.retirementSignal,
+            reply: input.reply, releases: [], timers: new Set(), feedback: [], accepted: new Set(), sends: new Set(),
+        };
+        const stop = () => {
+            operation.progressStopped = true;
+            for (const timer of operation.timers)
+                clearTimeout(timer);
+            operation.timers.clear();
+        };
+        input.retirementSignal.addEventListener('abort', stop, { once: true });
+        return Object.freeze({
+            bind: (view, owner) => { if (operation.active)
+                this.#views.set(view, { operation, owner }); },
+            trackSend: (send) => {
+                if (!operation.active)
+                    return;
+                const settled = send.then(() => { operation.sends.delete(settled); }, () => { operation.sends.delete(settled); });
+                operation.sends.add(settled);
+            },
+            stopProgress: async () => { stop(); await Promise.all(operation.feedback); },
+            finish: async () => {
+                stop();
+                await Promise.all(operation.feedback);
+                // New sends may start while an earlier send is draining. Do not release from an initial snapshot alone.
+                if (operation.admitted)
+                    while (operation.sends.size > 0)
+                        await Promise.all(operation.sends);
+                if (!operation.active)
+                    return;
+                operation.active = false;
+                operation.signal.removeEventListener('abort', stop);
+                for (const release of operation.releases)
+                    release();
+                operation.releases.length = 0;
+                operation.feedback.length = 0;
+                operation.accepted.clear();
+                operation.sends.clear();
+                operation.reply = undefined;
+                operation.snapshot = undefined;
+                operation.key = undefined;
+            },
+        });
+    }
+    #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 { 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) {
+                    // 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++;
+        entry.cooldownUntil = now + (policy.cooldownMs ?? 0);
+        const acceptedEntry = entry;
+        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);
+                if (!operation.active || operation.progressStopped || operation.signal.aborted || !operation.reply)
+                    return;
+                // Observe failure once. Never retry uncertain delivery and never expose the exception.
+                let send;
+                try {
+                    send = Promise.resolve(operation.reply(owner, '正在处理中，请稍候。')).then(() => { }, () => { });
+                }
+                catch {
+                    send = Promise.resolve();
+                }
+                operation.feedback.push(send);
+            }, policy.progressAfterMs);
+            operation.timers.add(timer);
+        }
+        operation.accepted.add(capability);
+        return undefined;
+    }
+}
+function nonempty(value) { return typeof value === 'string' && value.length > 0; }
+function limited(reason) { return Object.freeze({ reason }); }
+/** @internal Projection reads the Root resource; ordinary authoring values cannot bind an operation. */
+export function admitCommandExecution(source, capability, owner, policy, snapshot) {
+    if (!policy)
+        return undefined;
+    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

@@ -6,7 +6,8 @@
 export * from './command-index.js';
 /** @public Command authoring contract and `defineCommand`. */
 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 * from './permission-explanation.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

@@ -6,6 +6,7 @@
 export * from './command-index.js';
 /** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
-export { assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, } from './permit.js';
-export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
+export * from './permission-explanation.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/permission-explanation.d.ts

@@ -0,0 +1,22 @@
+import { type PermissionSubject, type PermissionConditionExplanation } from '@zhin.js/permission';
+import type { CommandDescriptor } from './command-index.js';
+/** The exact subject projection used by the real command permit gate. No factories or checkers run. */
+export declare function toCommandPermissionSubject(source: unknown): PermissionSubject;
+/** Exact authoring adapter restriction, distinct from builtin adapter(...) matching. */
+export declare function commandAdapterMatches(command: Readonly<{
+    adapter?: string;
+}>, source: unknown): boolean;
+export type CommandPermissionHostStatus = 'present' | 'missing' | 'unverified';
+/** Read-only hypothetical conditions. A match is not permission to execute the command. */
+export declare function explainCommandPermissions(command: Pick<CommandDescriptor, 'adapter' | 'permit'>, options: Readonly<{
+    source?: unknown;
+    rolesKnown?: boolean;
+    permissionHost: CommandPermissionHostStatus;
+}>): Readonly<{
+    permissionHost: CommandPermissionHostStatus;
+    adapter: Readonly<PermissionConditionExplanation>;
+    rules: readonly import("@zhin.js/permission").PermitRuleExplanation[];
+    summary: Readonly<PermissionConditionExplanation>;
+    unconstrained: readonly string[];
+    assumptions: readonly string[];
+}>;

package/lib/permission-explanation.js

@@ -0,0 +1,54 @@
+import { operationClientAdapter } from '@zhin.js/feature-kit';
+import { explainPermitRules, toPermissionSubject } from '@zhin.js/permission';
+import { resolveCommandSender, resolveCommandSession } from './definition.js';
+/** The exact subject projection used by the real command permit gate. No factories or checkers run. */
+export function toCommandPermissionSubject(source) {
+    const projected = toPermissionSubject(source);
+    const session = resolveCommandSession(source);
+    return { ...projected, ...session, ...(session.sender ? { sender: { ...projected.sender, ...session.sender } } : {}) };
+}
+/** Exact authoring adapter restriction, distinct from builtin adapter(...) matching. */
+export function commandAdapterMatches(command, source) {
+    return !command.adapter || operationClientAdapter(source) === command.adapter;
+}
+/** Read-only hypothetical conditions. A match is not permission to execute the command. */
+export function explainCommandPermissions(command, options) {
+    const projected = toCommandPermissionSubject(options.source);
+    const inputSender = options.source && typeof options.source === 'object'
+        ? options.source.sender : undefined;
+    const structuredRoles = inputSender && typeof inputSender === 'object'
+        && Array.isArray(inputSender.role);
+    // A sender-only assumption has no synthetic conversation. Apply the real canonical
+    // sender defaults without inventing an Endpoint or treating unknown roles as known.
+    const senderOnly = options.source && typeof options.source === 'object' && !('conversation' in options.source) && !structuredRoles
+        ? resolveCommandSender(options.source, undefined) : undefined;
+    const subject = senderOnly ? { ...projected, sender: senderOnly } : projected;
+    const defaultedRoles = options.rolesKnown && Array.isArray(inputSender?.roles) && inputSender.roles.length === 0
+        && subject.sender?.role.length === 1 && subject.sender.role[0] === 'user';
+    const actualAdapter = operationClientAdapter(options.source);
+    const adapter = !command.adapter
+        ? { outcome: 'not_evaluated', reason: '命令未声明 adapter 约束' }
+        : !actualAdapter ? { outcome: 'unknown', reason: '未选择当前 Endpoint，无法判断命令的精确 adapter 约束' }
+            : { outcome: commandAdapterMatches(command, options.source) ? 'match' : 'mismatch', reason: '命令 adapter 与当前 Endpoint 声明的原生适配器精确比较；未探测在线状态' };
+    const rules = explainPermitRules(command.permit ?? [], subject, { rolesKnown: options.rolesKnown });
+    const conditions = [...(command.adapter ? [adapter] : []), ...rules];
+    let summary;
+    if (conditions.some(item => item.outcome === 'mismatch'))
+        summary = { outcome: 'mismatch', reason: '至少一个声明条件与假设输入不符；这不是实际准入检查' };
+    else if ((rules.length > 0 && options.permissionHost !== 'present') || conditions.some(item => item.outcome === 'unknown')) {
+        summary = { outcome: 'unknown', reason: rules.length > 0 && options.permissionHost !== 'present'
+                ? 'PermissionHost 缺失或无法确认；不能推断命令可执行' : '存在缺少依据的条件，不能推断命令可执行' };
+    }
+    else if (rules.length === 0)
+        summary = { outcome: 'not_evaluated', reason: '命令未声明 permit 限制；这不表示已获得执行权限' };
+    else if (conditions.some(item => item.outcome === 'not_evaluated'))
+        summary = { outcome: 'not_evaluated', reason: '存在未执行的平台或自定义条件，不能推断命令可执行' };
+    else
+        summary = { outcome: 'match', reason: '已解释的 builtin 条件与假设输入匹配；不代表真实授权或命令可执行' };
+    return Object.freeze({ permissionHost: options.permissionHost, adapter: Object.freeze(adapter), rules, summary: Object.freeze(summary),
+        unconstrained: Object.freeze(['已解释的 builtin 规则不检查具体 Endpoint、parent 或 thread；保留完整目标不等于这些维度受规则限制']),
+        assumptions: Object.freeze(['身份与角色仅用于模拟，未向平台核实', '未执行命令、动态默认值、平台或自定义 checker',
+            ...(defaultedRoles
+                ? ['canonical 输入未附角色时按命令运行时默认 user 解释；这不是已核验的平台角色'] : [])]),
+    });
+}

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}`);