@zhin.js/core 1.1.34 → 1.1.35

package/lib/built/speech-loader.js

@@ -0,0 +1,32 @@
+import { createWarnOnce, resetWarnOnceForTests } from '@zhin.js/logger';
+import { importOptionalPeerPackage } from './optional-peer-import.js';
+/** 动态 import 时使用的包名（与 @zhin.js/speech package.json 一致） */
+export const SPEECH_PACKAGE = '@zhin.js/speech';
+let cached;
+const speechPeerWarnOnce = createWarnOnce('speech');
+/** zhin 启动时已创建 pipeline 时注入 */
+export function seedSpeechPipeline(pipeline) {
+    cached = pipeline;
+}
+/** 动态加载 @zhin.js/speech；未安装时 warn 一次并返回 undefined */
+export async function loadSpeechPipeline(opts) {
+    if (cached !== undefined) {
+        return cached ?? undefined;
+    }
+    try {
+        const mod = await importOptionalPeerPackage(SPEECH_PACKAGE);
+        const speechConfig = opts?.getConfig?.()?.speech;
+        cached = mod.createSpeechPipeline(speechConfig);
+        return cached;
+    }
+    catch {
+        speechPeerWarnOnce(opts?.warn, `未安装 ${SPEECH_PACKAGE}，STT/TTS 已降级。安装: pnpm add ${SPEECH_PACKAGE}`);
+        cached = null;
+        return undefined;
+    }
+}
+/** 测试用：重置加载缓存 */
+export function resetSpeechLoaderForTests() {
+    cached = undefined;
+    resetWarnOnceForTests('speech');
+}

package/lib/built/tool.d.ts

@@ -3,11 +3,14 @@
  * 工具仅面向 AI（通过 MCP 注册），不再与 Command 互转
  */
 import { Feature, FeatureJSON } from "@zhin.js/kernel";
-import type { Tool, ToolContext, ToolJsonSchema, ToolParametersSchema, PropertySchema, MaybePromise, ToolScope } from "../types.js";
+import type { Tool, ToolJsonSchema, ToolParametersSchema, PropertySchema, MaybePromise, ToolScope } from "../types.js";
+import type { Message } from "../message.js";
+import { type PermissionHost } from '@zhin.js/permission';
 /**
- * 检查工具是否可被当前上下文访问
+ * 检查工具是否可被当前 Message 通讯上下文访问。
+ * `host` 为 PermissionHost 实例；无 host 且有 permissions → deny。
  */
-export declare function canAccessTool(tool: Tool, context: ToolContext): boolean;
+export declare function canAccessTool(tool: Tool, message?: Message<any>, host?: PermissionHost | null): Promise<boolean>;
 /**
  * 从参数定义中提取参数信息
  */
@@ -38,7 +41,6 @@ export declare class ZhinTool {
     param(name: string, schema: PropertySchema, required?: boolean): this;
     platform(...platforms: string[]): this;
     scope(...scopes: ToolScope[]): this;
-    requireAnyRole(...roles: import('./roles.js').SenderRole[]): this;
     permit(...permissions: string[]): this;
     tag(...tags: string[]): this;
     keyword(...keywords: string[]): this;
@@ -51,7 +53,7 @@ export declare class ZhinTool {
     preExec(value?: boolean): this;
     /** 设置工具分类（如 file / shell / web），用于展示与 TOOLS.md 协同 */
     kind(value: string): this;
-    execute(callback: (args: Record<string, any>, context?: ToolContext) => MaybePromise<any>): this;
+    execute(callback: (args: Record<string, any>, message?: Message<any>) => MaybePromise<any>): this;
     toTool(): Tool;
     toJSON(): {
         name: string;
@@ -59,7 +61,7 @@ export declare class ZhinTool {
         parameters: ToolParametersSchema;
         platforms?: string[];
         scopes?: ToolScope[];
-        requiredAnyRole?: import('./roles.js').SenderRole[];
+        permissions?: string[];
         tags?: string[];
     };
     get help(): string;
@@ -71,15 +73,15 @@ export declare function isZhinTool(obj: any): obj is ZhinTool;
  */
 export type ToolInput = Tool | ZhinTool;
 /**
- * ToolContext 扩展方法类型
+ * Message 工具扩展方法类型
  */
-export interface ToolContextExtensions {
+export interface MessageToolExtensions {
     /** 添加工具 */
     addTool(tool: ToolInput): () => void;
 }
 declare module "../plugin.js" {
     namespace Plugin {
-        interface Extensions extends ToolContextExtensions {
+        interface Extensions extends MessageToolExtensions {
         }
         interface Contexts {
             tool: ToolFeature;
@@ -118,11 +120,11 @@ export declare class ToolFeature extends Feature<Tool> {
     /**
      * 执行工具
      */
-    execute(name: string, args: Record<string, any>, context?: ToolContext): Promise<any>;
+    execute(name: string, args: Record<string, any>, message?: Message<any>): Promise<any>;
     /**
-     * 根据上下文过滤工具
+     * 根据 Message 通讯上下文过滤工具
      */
-    filterByContext(tools: Tool[], context: ToolContext): Tool[];
+    filterByContext(tools: Tool[], message?: Message<any>, host?: PermissionHost | null): Promise<Tool[]>;
     /**
      * 按插件名获取工具
      */
@@ -147,4 +149,3 @@ export declare class ToolFeature extends Feature<Tool> {
     };
 }
 export {};
-//# sourceMappingURL=tool.d.ts.map

package/lib/built/tool.js

@@ -3,19 +3,28 @@
  * 工具仅面向 AI（通过 MCP 注册），不再与 Command 互转
  */
 import { Feature } from "@zhin.js/kernel";
-import { getPlugin } from "../plugin.js";
-import { roleSatisfies, resolveRolesFromContext } from './roles.js';
+import { toPermissionSubject } from '@zhin.js/permission';
 /**
- * 检查工具是否可被当前上下文访问
+ * 检查工具是否可被当前 Message 通讯上下文访问。
+ * `host` 为 PermissionHost 实例；无 host 且有 permissions → deny。
  */
-export function canAccessTool(tool, context) {
-    if (tool.platforms?.length && (!context.platform || !tool.platforms.includes(context.platform))) {
+export async function canAccessTool(tool, message, host) {
+    if (!message)
+        return !tool.platforms?.length && !tool.scopes?.length && !tool.permissions?.length;
+    const adapter = String(message.$adapter);
+    const scope = (message.$channel?.type || 'private');
+    if (tool.platforms?.length && !tool.platforms.includes(adapter)) {
         return false;
     }
-    if (tool.scopes?.length && (!context.scope || !tool.scopes.includes(context.scope))) {
+    if (tool.scopes?.length && !tool.scopes.includes(scope)) {
         return false;
     }
-    return roleSatisfies(resolveRolesFromContext(context), tool.requiredAnyRole);
+    if (!tool.permissions?.length)
+        return true;
+    if (!host)
+        return false;
+    const subject = toPermissionSubject(message);
+    return host.checkAll(tool.permissions, subject);
 }
 // ============================================================================
 // Tool 工具函数
@@ -54,7 +63,6 @@ export class ZhinTool {
     #execute;
     #platforms = [];
     #scopes = [];
-    #requiredAnyRole = [];
     #permissions = [];
     #tags = [];
     #keywords = [];
@@ -96,10 +104,6 @@ export class ZhinTool {
         this.#scopes.push(...scopes);
         return this;
     }
-    requireAnyRole(...roles) {
-        this.#requiredAnyRole = [...roles];
-        return this;
-    }
     permit(...permissions) {
         this.#permissions.push(...permissions);
         return this;
@@ -170,8 +174,6 @@ export class ZhinTool {
             tool.platforms = this.#platforms;
         if (this.#scopes.length > 0)
             tool.scopes = this.#scopes;
-        if (this.#requiredAnyRole.length > 0)
-            tool.requiredAnyRole = [...this.#requiredAnyRole];
         if (this.#permissions.length > 0)
             tool.permissions = this.#permissions;
         if (this.#tags.length > 0)
@@ -198,8 +200,8 @@ export class ZhinTool {
             json.platforms = this.#platforms;
         if (this.#scopes.length > 0)
             json.scopes = this.#scopes;
-        if (this.#requiredAnyRole.length > 0)
-            json.requiredAnyRole = [...this.#requiredAnyRole];
+        if (this.#permissions.length > 0)
+            json.permissions = [...this.#permissions];
         if (this.#tags.length > 0)
             json.tags = this.#tags;
         return json;
@@ -216,8 +218,8 @@ export class ZhinTool {
                 lines.push(`    ${param.name}: ${param.schema.type} ${required} ${desc}`);
             }
         }
-        if (this.#requiredAnyRole.length > 0) {
-            lines.push(`  角色: ${this.#requiredAnyRole.join(', ')}`);
+        if (this.#permissions.length > 0) {
+            lines.push(`  权限: ${this.#permissions.join(', ')}`);
         }
         if (this.#platforms.length > 0) {
             lines.push(`  平台: ${this.#platforms.join(', ')}`);
@@ -305,18 +307,22 @@ export class ToolFeature extends Feature {
     /**
      * 执行工具
      */
-    async execute(name, args, context) {
+    async execute(name, args, message) {
         const tool = this.byName.get(name);
         if (!tool) {
             throw new Error(`Tool "${name}" not found`);
         }
-        return tool.execute(args, context);
+        return tool.execute(args, message);
     }
     /**
-     * 根据上下文过滤工具
+     * 根据 Message 通讯上下文过滤工具
      */
-    filterByContext(tools, context) {
-        return tools.filter(tool => canAccessTool(tool, context));
+    async filterByContext(tools, message, host) {
+        const results = await Promise.all(tools.map(async (tool) => ({
+            tool,
+            allowed: await canAccessTool(tool, message, host),
+        })));
+        return results.filter((r) => r.allowed).map((r) => r.tool);
     }
     /**
      * 按插件名获取工具
@@ -370,7 +376,7 @@ export class ToolFeature extends Feature {
         const feature = this;
         return {
             addTool(tool) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const toolObj = isZhinTool(tool) ? tool.toTool() : tool;
                 const dispose = feature.addTool(tool, plugin.name);
                 plugin.recordFeatureContribution(feature.name, toolObj.name);
@@ -380,4 +386,3 @@ export class ToolFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=tool.js.map

package/lib/built/user-interaction.d.ts

@@ -0,0 +1,30 @@
+import type { UserInteractionContent, UserInteractionRequest } from '@zhin.js/interaction';
+import type { SendContent } from '../plugin-runtime/im/contracts.js';
+import type { ButtonStyle } from './interactive-segments/types.js';
+export interface UserInteractionAction {
+    readonly label: string;
+    readonly value: string;
+    readonly style?: ButtonStyle;
+}
+export interface UserInteractionView extends UserInteractionContent {
+    readonly actions?: readonly UserInteractionAction[];
+}
+export interface UserInteractionProgress extends UserInteractionContent {
+    readonly index: number;
+    readonly total: number;
+}
+export type UserInteractionParseResult = Readonly<{
+    ok: true;
+    value: unknown;
+}> | Readonly<{
+    ok: false;
+    message: string;
+}>;
+/** Fail early for interaction definitions that could never produce an unambiguous answer. */
+export declare function assertUserInteractionRequest(request: UserInteractionRequest): void;
+/** Project semantic content into canonical Markdown + keyboard segments. */
+export declare function renderUserInteraction(view: UserInteractionView): SendContent;
+/** Derive presentation and controls from one discriminated request. */
+export declare function projectUserInteraction(request: UserInteractionRequest, progress?: UserInteractionProgress): UserInteractionView;
+/** Parse and validate one user reply without transport knowledge. */
+export declare function parseUserInteractionAnswer(request: UserInteractionRequest, rawInput: string): UserInteractionParseResult;

package/lib/built/user-interaction.js

@@ -0,0 +1,248 @@
+/** Fail early for interaction definitions that could never produce an unambiguous answer. */
+export function assertUserInteractionRequest(request) {
+    if (!request.title.trim())
+        throw new TypeError('User interaction title must not be empty');
+    if (request.timeout !== undefined && (!Number.isFinite(request.timeout) || request.timeout <= 0)) {
+        throw new RangeError('User interaction timeout must be a positive finite number');
+    }
+    if (request.type === 'text' && !validRange(request.minLength, request.maxLength)) {
+        throw new RangeError('User interaction text length range is invalid');
+    }
+    if (request.type === 'number' && !validBounds(request.min, request.max)) {
+        throw new RangeError('User interaction number range is invalid');
+    }
+    if (request.type === 'select' || request.type === 'multiselect') {
+        if (request.options.length === 0)
+            throw new TypeError('User interaction options must not be empty');
+        const labels = new Set();
+        for (const option of request.options) {
+            const label = option.label.trim().toLocaleLowerCase();
+            if (!label)
+                throw new TypeError('User interaction option label must not be empty');
+            if (labels.has(label))
+                throw new TypeError(`Duplicate user interaction option label: ${option.label}`);
+            labels.add(label);
+        }
+    }
+    if (request.type === 'multiselect') {
+        if (request.separator === '')
+            throw new TypeError('User interaction separator must not be empty');
+        if (!validRange(request.minSelections, request.maxSelections)) {
+            throw new RangeError('User interaction selection range is invalid');
+        }
+    }
+    if (request.type === 'list') {
+        if (request.separator === '')
+            throw new TypeError('User interaction separator must not be empty');
+        if (!validRange(request.minItems, request.maxItems)) {
+            throw new RangeError('User interaction list length range is invalid');
+        }
+    }
+}
+/** Project semantic content into canonical Markdown + keyboard segments. */
+export function renderUserInteraction(view) {
+    const markdown = [
+        `### ${view.title}`,
+        view.description?.trim(),
+        view.tip?.trim() ? quoteTip(view.tip.trim()) : undefined,
+    ].filter((part) => !!part).join('\n\n');
+    const actions = view.actions ?? [];
+    if (actions.length === 0) {
+        return [{ type: 'markdown', data: { content: markdown } }];
+    }
+    const buttons = actions.map((action, index) => ({
+        id: `interaction-${index + 1}`,
+        label: action.label,
+        payload: action.value,
+        ...(action.style ? { style: action.style } : {}),
+        mode: 'command',
+        command: { enter: true, reply: false },
+    }));
+    return [
+        { type: 'markdown', data: { content: markdown } },
+        {
+            type: 'keyboard',
+            data: {
+                rows: chunk(buttons, 5),
+                fallback: {
+                    hint: '也可以直接回复对应内容。',
+                    map: Object.fromEntries(actions.map((action, index) => [String(index + 1), action.value])),
+                },
+            },
+        },
+    ];
+}
+/** Derive presentation and controls from one discriminated request. */
+export function projectUserInteraction(request, progress) {
+    const instruction = instructionFor(request);
+    const optionList = request.type === 'select' || request.type === 'multiselect'
+        ? renderOptions(request.options)
+        : undefined;
+    const optionsHaveDescriptions = request.type === 'select' || request.type === 'multiselect'
+        ? request.options.some((option) => !!option.description)
+        : false;
+    const actions = actionsFor(request);
+    const stepDescription = [
+        progress ? `**${progress.index}/${progress.total} · ${request.title}**` : undefined,
+        request.description,
+        optionList && (!actions || optionsHaveDescriptions) ? optionList : undefined,
+    ].filter((part) => !!part).join('\n\n');
+    return Object.freeze({
+        title: progress?.title ?? request.title,
+        description: progress
+            ? [progress.description, stepDescription].filter(Boolean).join('\n\n')
+            : stepDescription || undefined,
+        tip: [request.tip, instruction, progress?.tip].filter(Boolean).join('\n'),
+        ...(actions ? { actions: Object.freeze(actions) } : {}),
+    });
+}
+/** Parse and validate one user reply without transport knowledge. */
+export function parseUserInteractionAnswer(request, rawInput) {
+    const raw = rawInput.trim();
+    switch (request.type) {
+        case 'text': {
+            if (raw.length < (request.minLength ?? 0))
+                return invalid(`请至少输入 ${request.minLength} 个字符`);
+            if (request.maxLength !== undefined && raw.length > request.maxLength) {
+                return invalid(`请不要超过 ${request.maxLength} 个字符`);
+            }
+            if (request.pattern) {
+                request.pattern.lastIndex = 0;
+                if (!request.pattern.test(raw))
+                    return invalid('输入格式不正确');
+            }
+            return valid(raw);
+        }
+        case 'number': {
+            const value = Number(raw);
+            if (!raw || !Number.isFinite(value))
+                return invalid('请输入有效数字');
+            if (request.integer && !Number.isInteger(value))
+                return invalid('请输入整数');
+            if (request.min !== undefined && value < request.min)
+                return invalid(`请输入不小于 ${request.min} 的数字`);
+            if (request.max !== undefined && value > request.max)
+                return invalid(`请输入不大于 ${request.max} 的数字`);
+            return valid(value);
+        }
+        case 'confirm': {
+            const normalized = raw.toLocaleLowerCase();
+            const confirmLabel = request.confirmLabel?.trim().toLocaleLowerCase();
+            const cancelLabel = request.cancelLabel?.trim().toLocaleLowerCase();
+            if (CONFIRM_VALUES.has(normalized) || (confirmLabel && normalized === confirmLabel))
+                return valid(true);
+            if (CANCEL_VALUES.has(normalized) || (cancelLabel && normalized === cancelLabel))
+                return valid(false);
+            return invalid('请选择确认或取消');
+        }
+        case 'select': {
+            const option = resolveOption(request.options, raw);
+            return option ? valid(option.value) : invalid('请选择一个有效选项');
+        }
+        case 'multiselect': {
+            const separator = request.separator ?? ',';
+            const tokens = raw.split(separator).map((token) => token.trim()).filter(Boolean);
+            const selected = uniqueOptions(tokens.map((token) => resolveOption(request.options, token)));
+            if (selected.length !== tokens.length)
+                return invalid('多选中包含无效选项');
+            if (selected.length < (request.minSelections ?? 0))
+                return invalid(`请至少选择 ${request.minSelections} 项`);
+            if (request.maxSelections !== undefined && selected.length > request.maxSelections) {
+                return invalid(`请最多选择 ${request.maxSelections} 项`);
+            }
+            return valid(Object.freeze(selected.map((option) => option.value)));
+        }
+        case 'list': {
+            const separator = request.separator ?? ',';
+            const tokens = raw.split(separator).map((token) => token.trim()).filter(Boolean);
+            if (tokens.length < (request.minItems ?? 0))
+                return invalid(`请至少输入 ${request.minItems} 项`);
+            if (request.maxItems !== undefined && tokens.length > request.maxItems)
+                return invalid(`请最多输入 ${request.maxItems} 项`);
+            if (request.valueType === 'number') {
+                const values = tokens.map(Number);
+                return values.every(Number.isFinite) ? valid(Object.freeze(values)) : invalid('列表中包含无效数字');
+            }
+            if (request.valueType === 'boolean') {
+                const values = tokens.map(parseBoolean);
+                return values.every((value) => value !== undefined)
+                    ? valid(Object.freeze(values))
+                    : invalid('布尔列表只接受 true/false、yes/no 或 是/否');
+            }
+            return valid(Object.freeze(tokens));
+        }
+    }
+}
+function actionsFor(request) {
+    if (request.type === 'confirm') {
+        return [
+            { label: request.confirmLabel ?? '确认', value: 'yes', style: 'primary' },
+            { label: request.cancelLabel ?? '取消', value: 'no', style: 'danger' },
+        ];
+    }
+    if (request.type === 'select' && request.options.length <= 10) {
+        return request.options.map((option, index) => ({ label: option.label, value: String(index + 1), style: 'secondary' }));
+    }
+    return undefined;
+}
+function instructionFor(request) {
+    switch (request.type) {
+        case 'confirm': return '请选择确认或取消。';
+        case 'select': return '可以点击按钮，或回复序号/选项名称。';
+        case 'multiselect': return `回复序号或选项名称，多项用“${request.separator ?? ','}”分隔。`;
+        case 'list': return `多项用“${request.separator ?? ','}”分隔。`;
+        default: return undefined;
+    }
+}
+function renderOptions(options) {
+    return options.map((option, index) => `${index + 1}. ${option.label}${option.description ? ` — ${option.description}` : ''}`).join('\n');
+}
+function resolveOption(options, raw) {
+    const index = Number(raw);
+    if (Number.isInteger(index) && index >= 1 && index <= options.length)
+        return options[index - 1];
+    const normalized = raw.toLocaleLowerCase();
+    return options.find((option) => option.label.trim().toLocaleLowerCase() === normalized);
+}
+function uniqueOptions(options) {
+    const result = [];
+    for (const option of options)
+        if (option && !result.includes(option))
+            result.push(option);
+    return result;
+}
+function parseBoolean(raw) {
+    const normalized = raw.toLocaleLowerCase();
+    if (CONFIRM_VALUES.has(normalized))
+        return true;
+    if (CANCEL_VALUES.has(normalized))
+        return false;
+    return undefined;
+}
+function quoteTip(tip) {
+    return tip.split('\n').map((line) => `> 💡 ${line}`).join('\n');
+}
+function valid(value) {
+    return Object.freeze({ ok: true, value });
+}
+function invalid(message) {
+    return Object.freeze({ ok: false, message });
+}
+function validRange(minimum, maximum) {
+    return (minimum === undefined || (Number.isFinite(minimum) && minimum >= 0))
+        && (maximum === undefined || (Number.isFinite(maximum) && maximum >= 0))
+        && (minimum === undefined || maximum === undefined || minimum <= maximum);
+}
+function validBounds(minimum, maximum) {
+    return (minimum === undefined || Number.isFinite(minimum))
+        && (maximum === undefined || Number.isFinite(maximum))
+        && (minimum === undefined || maximum === undefined || minimum <= maximum);
+}
+const CONFIRM_VALUES = new Set(['1', 'y', 'yes', 'true', '是', '确认', '同意']);
+const CANCEL_VALUES = new Set(['2', 'n', 'no', 'false', '否', '取消', '拒绝']);
+function chunk(items, size) {
+    const rows = [];
+    for (let index = 0; index < items.length; index += size)
+        rows.push(items.slice(index, index + size));
+    return rows;
+}

package/lib/command.d.ts

@@ -1,16 +1,20 @@
-import { MatchResult, SegmentMatcher } from "segment-matcher";
-import { AdapterMessage, SendContent } from "./types.js";
-import { RegisteredAdapter } from "./types.js";
-import type { Message } from "./message.js";
-import { MaybePromise } from "./types.js";
-import { Plugin } from "./plugin.js";
+import { MatchResult, SegmentMatcher } from 'segment-matcher';
+import { AdapterMessage, SendContent, RegisteredAdapter, MaybePromise } from './types.js';
+import type { Message } from './message.js';
+import { type PermissionHost } from '@zhin.js/permission';
+type ConstructFirstParam<T extends new (...args: any[]) => any> = T extends new (...args: [infer U, ...any[]]) => any ? U : never;
+type ConstructSecondParam<T extends new (...args: any[]) => any> = T extends new (...args: [any, infer V, ...any[]]) => any ? V : never;
 /**
- * MessageCommand类：命令系统核心，基于segment-matcher实现。
- * 支持多平台命令注册、作用域限制、参数解析、异步处理等。
+ * MessageCommand类：经典命令系统（segment-matcher）。
+ *
+ * @deprecated 新插件请用 `defineCommand`（`zhin.js/command`）+ `commands/` 约定目录。
+ * 本类仍供 Agent init / game-kit hub / legacy `CommandFeature` 使用；计划随经典
+ * Plugin 路径一并退役。见 `docs/contributing/public-api-surface.md`。
  */
 export declare class MessageCommand<T extends RegisteredAdapter = RegisteredAdapter> extends SegmentMatcher {
     #private;
     get helpInfo(): MessageCommand.HelpInfo;
+    constructor(C: ConstructFirstParam<typeof SegmentMatcher>, P?: ConstructSecondParam<typeof SegmentMatcher>);
     get help(): string;
     desc(...desc: string[]): MessageCommand<T>;
     usage(...usage: string[]): MessageCommand<T>;
@@ -21,13 +25,17 @@ export declare class MessageCommand<T extends RegisteredAdapter = RegisteredAdap
      */
     action(callback: MessageCommand.Callback<T>): MessageCommand<T>;
     permit(...permissions: string[]): MessageCommand<T>;
+    /** 命令要求的 permit 列表（空表示所有人可用） */
+    get requiredPermits(): readonly string[];
+    /** 与 handle 一致的 permit 校验，供帮助菜单等场景过滤不可见命令 */
+    checkPermits(message: Message<AdapterMessage<T>>, host: PermissionHost | null): Promise<boolean>;
     /**
      * 处理消息，自动匹配命令并执行回调
      * @param message 消息对象
-     * @param plugin 插件实例
+     * @param host PermissionHost（null 时有 permit 的命令 fail-closed）
      * @returns 命令返回内容或undefined
      */
-    handle(message: Message<AdapterMessage<T>>, plugin: Plugin): Promise<SendContent | undefined>;
+    handle(message: Message<AdapterMessage<T>>, host: PermissionHost | null): Promise<SendContent | undefined>;
 }
 export declare namespace MessageCommand {
     type Callback<T extends RegisteredAdapter> = (message: Message<AdapterMessage<T>>, result: MatchResult) => SendContent | undefined | Promise<SendContent | undefined>;
@@ -39,4 +47,4 @@ export declare namespace MessageCommand {
         examples: string[];
     };
 }
-//# sourceMappingURL=command.d.ts.map
+export {};

package/lib/command.js

@@ -1,7 +1,11 @@
-import { SegmentMatcher } from "segment-matcher";
+import { SegmentMatcher } from 'segment-matcher';
+import { toPermissionSubject } from '@zhin.js/permission';
 /**
- * MessageCommand类：命令系统核心，基于segment-matcher实现。
- * 支持多平台命令注册、作用域限制、参数解析、异步处理等。
+ * MessageCommand类：经典命令系统（segment-matcher）。
+ *
+ * @deprecated 新插件请用 `defineCommand`（`zhin.js/command`）+ `commands/` 约定目录。
+ * 本类仍供 Agent init / game-kit hub / legacy `CommandFeature` 使用；计划随经典
+ * Plugin 路径一并退役。见 `docs/contributing/public-api-surface.md`。
  */
 export class MessageCommand extends SegmentMatcher {
     #callbacks = [];
@@ -17,6 +21,24 @@ export class MessageCommand extends SegmentMatcher {
             examples: this.#examples
         };
     }
+    constructor(C, P = {}) {
+        super(C, {
+            at: ['qq', 'user_id'],
+            face: ['id'],
+            mention: ['qq', 'user_id'],
+            html: ['content'],
+            markdown: ['content'],
+            image: ['file', 'src', 'url'],
+            video: ['file', 'src', 'url'],
+            audio: ['file', 'src', 'url'],
+            file: ['file', 'src', 'url'],
+            reply: ['id', 'reply_id', 'message_id'],
+            quote: ['id', 'reply_id', 'message_id'],
+            forward: ['id', 'res_id', 'message_id'],
+            location: ['latitude', 'longitude'],
+            ...P,
+        });
+    }
     get help() {
         return [
             this.pattern,
@@ -49,18 +71,28 @@ export class MessageCommand extends SegmentMatcher {
         this.#permissions.push(...permissions);
         return this;
     }
+    /** 命令要求的 permit 列表（空表示所有人可用） */
+    get requiredPermits() {
+        return this.#permissions;
+    }
+    /** 与 handle 一致的 permit 校验，供帮助菜单等场景过滤不可见命令 */
+    async checkPermits(message, host) {
+        if (!this.#permissions.length)
+            return true;
+        if (!host)
+            return false;
+        const subject = toPermissionSubject(message);
+        return host.checkAll(this.#permissions, subject);
+    }
     /**
      * 处理消息，自动匹配命令并执行回调
      * @param message 消息对象
-     * @param plugin 插件实例
+     * @param host PermissionHost（null 时有 permit 的命令 fail-closed）
      * @returns 命令返回内容或undefined
      */
-    async handle(message, plugin) {
-        const auth = plugin.contextIsReady('permission') ? plugin.inject('permission') : null;
-        for (const permit of this.#permissions) {
-            const passed = await auth?.check(permit, message);
-            if (!passed)
-                return;
+    async handle(message, host) {
+        if (!(await this.checkPermits(message, host))) {
+            return;
         }
         const matched = this.match(message.$content);
         if (!matched)
@@ -72,4 +104,3 @@ export class MessageCommand extends SegmentMatcher {
         }
     }
 }
-//# sourceMappingURL=command.js.map

package/lib/component.d.ts

@@ -24,4 +24,3 @@ export declare const Fragment: Component<{
     children?: SendContent;
 }>;
 export declare const Fetch: Component<any>;
-//# sourceMappingURL=component.d.ts.map