@mearl/client 2.20.1 → 2.20.2

package/README.md

@@ -268,6 +268,14 @@ export default function register(app) {
 }
 ```
 
+`app.command(signature, handler, description?, examples?)` 注册 CLI、SDK 和 Agent 可调用的业务命令。
+`app.toolboxCommand(signature, handler, description?, examples?)` 注册仅供工具页面调用的命令，参数和 handler 契约相同；
+它不出现在 CLI 帮助中，CLI（包括 JSON payload）、SDK、MCP 及插件间的 `app.invoke` 都不能调用。
+工具页面通过 `window.mearl.invoke` 或 `window.mearl.start` 执行；两类命令都必须显式列在 `toolbox.page.commands` 中才能供页面调用。
+注册的 `toolboxCommand` 若没有列入该白名单，插件加载会失败。分块上传、分块读取和页面临时资源释放适合使用它；
+对 Agent 有独立业务价值的查询、导入、压缩、比较等完整操作使用 `app.command`。
+Python 入口也支持 `app.toolboxCommand(...)`，包括 `@app.toolboxCommand(..., description="...")` 装饰器。
+
 声明 `agent` 后工具页可以把任务交给对话 Agent；`layout` 默认为 `drawer`，宿主会提供顶部入口。
 页面也可在 `setAgentPanelVisible` 或 `runAgentTask` 中为单次交互指定 `drawer` / `workspace` / `inline`；
 Agent 对话会保存在 Codex 会话历史中。带固定

package/dist/actionTimeouts.js

@@ -21,7 +21,7 @@ export function resolveObservedActionTimeoutSec(data) {
 }
 export function resolveActionTimeoutSec(action, data, fallback = 15) {
     if (action === 'send_request') {
-        const transferTimeoutMs = Array.isArray(data.files) && data.files.length > 0
+        const transferTimeoutMs = data.bodyFile !== undefined || (Array.isArray(data.files) && data.files.length > 0)
             ? SEND_REQUEST_FILE_TRANSFER_TIMEOUT_MS
             : 0;
         return Math.max(fallback, Math.ceil(((data.timeout ?? 30000) + transferTimeoutMs + 5000) / 1000));

package/dist/commands.d.ts

@@ -305,7 +305,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["get_rules"];
 }, {
     readonly name: "send_request";
-    readonly description: "发送 HTTP 请求，自动携带浏览器 Cookie，支持 multipart 文件上传";
+    readonly description: "发送 HTTP 请求，自动携带浏览器 Cookie，支持 multipart 和原始二进制上传";
     readonly params: [{
         readonly name: "url";
         readonly type: "string";
@@ -327,6 +327,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "body";
         readonly type: "any";
         readonly description: "请求体（传对象时自动 JSON 序列化）";
+    }, {
+        readonly name: "bodyFile";
+        readonly type: "object";
+        readonly description: "原始二进制请求体：filePath 或 base64 二选一，可选 contentType（默认 application/octet-stream）；与 body/formData/files 互斥";
     }, {
         readonly name: "formData";
         readonly type: "object";
@@ -349,9 +353,9 @@ export declare const COMMANDS: readonly [{
         readonly type: "number";
         readonly description: "超时毫秒数，默认 30000";
     }];
-    readonly notes: readonly ["仅用于非 BUC 请求；BUC 接口使用 mearl buc，不手工传 Token、DPoP 或 Ticket。", "body 不能与 formData/files 组合；multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。", "filePath 属于 native-host 所在机器；无法引用远端路径时用 base64。BUC 上传的路径属于插件执行宿主。"];
+    readonly notes: readonly ["仅用于非 BUC 请求；BUC 接口使用 mearl buc，不手工传 Token、DPoP 或 Ticket。", "body 不能与 formData/files 组合；bodyFile 以原始字节发送，不包 multipart boundary，不能用于 GET/HEAD。", "bodyFile.filePath 属于 native-host，最大 40 MiB；base64 解码后最大 7 MiB。multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。", "filePath 属于 native-host 所在机器；无法引用远端路径时用 base64。BUC 上传的路径属于插件执行宿主。"];
     readonly result: readonly ["返回 status、statusText、headers、body、bodyType、attachedCookieCount；bodyType 为 json/text/base64，二进制 body 需解码后保存。"];
-    readonly examples: ["send_request --payload '{\"url\":\"https://api.example.com/data\",\"method\":\"GET\"}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"formData\":{\"folder\":\"assets\"},\"files\":[{\"fieldName\":\"file\",\"filePath\":\"/absolute/path/image.png\"}]}'"];
+    readonly examples: ["send_request --payload '{\"url\":\"https://api.example.com/data\",\"method\":\"GET\"}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"formData\":{\"folder\":\"assets\"},\"files\":[{\"fieldName\":\"file\",\"filePath\":\"/absolute/path/image.png\"}]}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"bodyFile\":{\"filePath\":\"/absolute/path/image.png\",\"contentType\":\"image/png\"}}'"];
 }, {
     readonly name: "send_mtop_request";
     readonly description: "使用目标浏览器 Cookie 发起 mtop 请求，自动处理签名和 token";

package/dist/commands.js

@@ -306,13 +306,18 @@ export const COMMANDS = [
     // ── 网络代理 ──────────────────────────────────────────────────────────────
     {
         name: 'send_request',
-        description: '发送 HTTP 请求，自动携带浏览器 Cookie，支持 multipart 文件上传',
+        description: '发送 HTTP 请求，自动携带浏览器 Cookie，支持 multipart 和原始二进制上传',
         params: [
             { name: 'url', type: 'string', required: true, description: '完整目标 URL' },
             { name: 'method', type: 'string', description: 'HTTP 方法，默认 GET' },
             { name: 'headers', type: 'object', description: '自定义请求头' },
             { name: 'params', type: 'object', description: 'URL 查询参数' },
             { name: 'body', type: 'any', description: '请求体（传对象时自动 JSON 序列化）' },
+            {
+                name: 'bodyFile',
+                type: 'object',
+                description: '原始二进制请求体：filePath 或 base64 二选一，可选 contentType（默认 application/octet-stream）；与 body/formData/files 互斥',
+            },
             {
                 name: 'formData',
                 type: 'object',
@@ -338,7 +343,8 @@ export const COMMANDS = [
         ],
         notes: [
             '仅用于非 BUC 请求；BUC 接口使用 mearl buc，不手工传 Token、DPoP 或 Ticket。',
-            'body 不能与 formData/files 组合；multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。',
+            'body 不能与 formData/files 组合；bodyFile 以原始字节发送，不包 multipart boundary，不能用于 GET/HEAD。',
+            'bodyFile.filePath 属于 native-host，最大 40 MiB；base64 解码后最大 7 MiB。multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。',
             'filePath 属于 native-host 所在机器；无法引用远端路径时用 base64。BUC 上传的路径属于插件执行宿主。',
         ],
         result: [
@@ -347,6 +353,7 @@ export const COMMANDS = [
         examples: [
             `send_request --payload '{"url":"https://api.example.com/data","method":"GET"}'`,
             `send_request --payload '{"url":"https://api.example.com/upload","method":"POST","formData":{"folder":"assets"},"files":[{"fieldName":"file","filePath":"/absolute/path/image.png"}]}'`,
+            `send_request --payload '{"url":"https://api.example.com/upload","method":"POST","bodyFile":{"filePath":"/absolute/path/image.png","contentType":"image/png"}}'`,
         ],
     },
     {

package/dist/generated-browser-action-protocol.d.ts

@@ -83,12 +83,23 @@ export type SendRequestFile = SendRequestFileMetadata & ({
     /** Multipart filename for the Base64 payload. */
     filename: string;
 });
+export type SendRequestBinaryBody = {
+    contentType?: string;
+} & ({
+    filePath: string;
+    base64?: never;
+} | {
+    filePath?: never;
+    base64: string;
+});
 export interface SendRequestParams {
     url: string;
     method?: string;
     headers?: Record<string, string>;
     params?: Record<string, string>;
     body?: unknown;
+    /** Raw bytes, mutually exclusive with body, formData and files. */
+    bodyFile?: SendRequestBinaryBody;
     formData?: Record<string, SendRequestFormValue>;
     files?: SendRequestFile[];
     withCookies?: boolean;

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invok
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
 export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugin.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
-export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated-browser-action-protocol.js';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestBinaryBody, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
 export declare function tabCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;

package/dist/plugin.d.ts

@@ -24,6 +24,8 @@ export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
     /** Examples omit the `mearl <plugin>` prefix, which help adds when displayed. */
     command(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
+    /** Registers a page-only command, also declared in toolbox.page.commands. */
+    toolboxCommand(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
     invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
     progress(progress: PluginProgress): void;
 }
@@ -39,6 +41,7 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invo
     commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;
     run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
+    runToolbox(invocation: PluginInvocation): Promise<unknown>;
 }>;
 export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
     name: string | undefined;
@@ -48,5 +51,8 @@ export declare function loadRegisteredPlugin(name: string, context: PluginExecut
     commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;
     run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
+    runToolbox(invocation: PluginInvocation): Promise<unknown>;
 }>;
 export declare function invokeRegisteredPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
+/** Entry point for the native toolbox service; nested plugin calls retain public-command access. */
+export declare function invokeRegisteredToolboxPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;

package/dist/plugin.js

@@ -133,31 +133,33 @@ export async function loadPlugin(entry, context, pluginName) {
     let name;
     let description;
     let toolbox;
+    const registerCommand = (signature, handler, description = '', examples = [], toolboxOnly = false) => {
+        if (!registering)
+            throw new Error('命令只能在入口注册阶段声明');
+        const [name, ...args] = signature.trim().split(/\s+/);
+        if (!/^[a-z][a-z0-9-]*$/.test(name) ||
+            commands.has(name) ||
+            typeof handler !== 'function' ||
+            !Array.isArray(examples) ||
+            examples.some((example) => typeof example !== 'string' || !example.trim())) {
+            throw new Error(`无效或重复的命令: ${signature}`);
+        }
+        const command = new Command(name).description(description);
+        for (const argument of args) {
+            if (!/^(?:<[a-zA-Z][\w-]*(?:\.\.\.)?>|\[[a-zA-Z][\w-]*(?:\.\.\.)?\])$/.test(argument)) {
+                throw new Error(`无效的位置参数: ${argument}`);
+            }
+            command.argument(argument);
+        }
+        const names = command.registeredArguments.map(argument => argument.name());
+        if (new Set(names).size !== names.length)
+            throw new Error(`参数名称重复: ${signature}`);
+        commands.set(name, { command, signature, handler, examples: [...examples], toolboxOnly });
+    };
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
-        command(signature, handler, description = '', examples = []) {
-            if (!registering)
-                throw new Error('命令只能在入口注册阶段声明');
-            const [name, ...args] = signature.trim().split(/\s+/);
-            if (!/^[a-z][a-z0-9-]*$/.test(name) ||
-                commands.has(name) ||
-                typeof handler !== 'function' ||
-                !Array.isArray(examples) ||
-                examples.some((example) => typeof example !== 'string' || !example.trim())) {
-                throw new Error(`无效或重复的命令: ${signature}`);
-            }
-            const command = new Command(name).description(description);
-            for (const argument of args) {
-                if (!/^(?:<[a-zA-Z][\w-]*(?:\.\.\.)?>|\[[a-zA-Z][\w-]*(?:\.\.\.)?\])$/.test(argument)) {
-                    throw new Error(`无效的位置参数: ${argument}`);
-                }
-                command.argument(argument);
-            }
-            const names = command.registeredArguments.map(argument => argument.name());
-            if (new Set(names).size !== names.length)
-                throw new Error(`参数名称重复: ${signature}`);
-            commands.set(name, { command, signature, handler, examples: [...examples] });
-        },
+        command: (signature, handler, description = '', examples = []) => registerCommand(signature, handler, description, examples),
+        toolboxCommand: (signature, handler, description = '', examples = []) => registerCommand(signature, handler, description, examples, true),
         invoke(action, payload = {}, options = {}) {
             if (!executing)
                 throw new Error('app.invoke 只能在命令执行期间调用');
@@ -177,7 +179,8 @@ export async function loadPlugin(entry, context, pluginName) {
             toolbox = normalizePluginToolboxContribution(descriptor.toolbox);
             for (const command of descriptor.commands) {
                 const commandName = command.signature.trim().split(/\s+/)[0];
-                app.command(command.signature, input => runPythonPluginCommand(entry, commandName, input, app), command.description);
+                const register = command.toolboxOnly ? app.toolboxCommand : app.command;
+                register(command.signature, input => runPythonPluginCommand(entry, commandName, input, app), command.description);
             }
         }
         else {
@@ -198,6 +201,11 @@ export async function loadPlugin(entry, context, pluginName) {
         if (commands.size === 0)
             throw new Error('入口未注册任何命令');
         const toolboxCommands = toolbox?.page.commands ?? [];
+        for (const [name, command] of commands) {
+            if (command.toolboxOnly && !toolboxCommands.includes(name)) {
+                throw new Error(`toolboxCommand 未声明在 toolbox.page.commands 中: ${name}`);
+            }
+        }
         for (const command of toolboxCommands) {
             if (!commands.has(command))
                 throw new Error(`toolbox 命令未注册: ${command}`);
@@ -209,24 +217,86 @@ export async function loadPlugin(entry, context, pluginName) {
     finally {
         registering = false;
     }
-    const find = (name) => {
+    const find = (name, toolboxPage = false) => {
         const command = commands.get(name);
         if (!command)
             throw new PluginError('PLUGIN_COMMAND_NOT_FOUND', `未知子命令: ${name}`);
+        if (toolboxPage) {
+            if (!toolbox?.page.commands.includes(name)) {
+                throw new PluginError('PLUGIN_COMMAND_NOT_ALLOWED', `工具页面不允许调用命令: ${name}`);
+            }
+        }
+        else if (command.toolboxOnly) {
+            throw new PluginError('PLUGIN_COMMAND_TOOLBOX_ONLY', `命令仅供工具页面调用: ${name}`);
+        }
         return command;
     };
+    const publicCommands = () => [...commands.values()].filter(command => !command.toolboxOnly);
+    const run = async (positionals, payload, namedInput = {}, toolboxPage = false) => {
+        if (payload !== undefined && positionals.length > 0) {
+            throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数调用与 --payload 调用不能混用');
+        }
+        if (payload !== undefined && Object.keys(namedInput).length > 0) {
+            throw new PluginError('PLUGIN_INVALID_INPUT', '插件业务选项与 --payload 调用不能混用');
+        }
+        if (payload !== undefined &&
+            (!isObject(payload) || typeof payload.command !== 'string' || !isObject(payload.input))) {
+            throw new PluginError('PLUGIN_INVALID_INPUT', '--payload 必须为 {"command":"...","input":{...}}');
+        }
+        const envelope = payload;
+        const { command, handler } = find(envelope?.command ?? positionals[0] ?? '', toolboxPage);
+        const positionalInput = envelope
+            ? { ...envelope.input }
+            : Object.fromEntries(command.registeredArguments
+                .map((argument, index) => [
+                argument.name(),
+                argument.variadic ? positionals.slice(index + 1) : positionals[index + 1],
+            ])
+                .filter(([, value]) => value !== undefined));
+        for (const name of Object.keys(namedInput)) {
+            if (Object.hasOwn(positionalInput, name)) {
+                throw new PluginError('PLUGIN_INVALID_INPUT', `参数不能重复传入: ${name}`);
+            }
+        }
+        const input = { ...positionalInput, ...namedInput };
+        if (!envelope &&
+            !command.registeredArguments.some(argument => argument.variadic) &&
+            positionals.length - 1 > command.registeredArguments.length) {
+            throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数过多');
+        }
+        for (const argument of command.registeredArguments) {
+            const value = Object.hasOwn(input, argument.name()) ? input[argument.name()] : undefined;
+            if (argument.required &&
+                (value === undefined ||
+                    value === null ||
+                    value === '' ||
+                    (Array.isArray(value) && value.length === 0))) {
+                throw new PluginError('PLUGIN_INVALID_INPUT', `缺少必填参数: ${argument.name()}`);
+            }
+            if (argument.variadic && value !== undefined && !Array.isArray(value)) {
+                throw new PluginError('PLUGIN_INVALID_INPUT', `${argument.name()} 必须为数组`);
+            }
+        }
+        executing = true;
+        try {
+            return await handler(input);
+        }
+        finally {
+            executing = false;
+        }
+    };
     return {
         name,
         description,
         toolbox,
         version: readPluginVersion(entry),
         commandHelp(namespace) {
-            return [...commands.values()]
+            return publicCommands()
                 .map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`)
                 .join('\n');
         },
         help(namespace, name) {
-            const selected = name ? [find(name)] : [...commands.values()];
+            const selected = name ? [find(name)] : publicCommands();
             const examples = selected.flatMap(({ examples }) => examples);
             return [
                 '用法：',
@@ -236,58 +306,11 @@ export async function loadPlugin(entry, context, pluginName) {
                     : []),
             ].join('\n');
         },
-        async run(positionals, payload, namedInput = {}) {
-            if (payload !== undefined && positionals.length > 0) {
-                throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数调用与 --payload 调用不能混用');
-            }
-            if (payload !== undefined && Object.keys(namedInput).length > 0) {
-                throw new PluginError('PLUGIN_INVALID_INPUT', '插件业务选项与 --payload 调用不能混用');
-            }
-            if (payload !== undefined &&
-                (!isObject(payload) || typeof payload.command !== 'string' || !isObject(payload.input))) {
-                throw new PluginError('PLUGIN_INVALID_INPUT', '--payload 必须为 {"command":"...","input":{...}}');
-            }
-            const envelope = payload;
-            const { command, handler } = find(envelope?.command ?? positionals[0] ?? '');
-            const positionalInput = envelope
-                ? { ...envelope.input }
-                : Object.fromEntries(command.registeredArguments
-                    .map((argument, index) => [
-                    argument.name(),
-                    argument.variadic ? positionals.slice(index + 1) : positionals[index + 1],
-                ])
-                    .filter(([, value]) => value !== undefined));
-            for (const name of Object.keys(namedInput)) {
-                if (Object.hasOwn(positionalInput, name)) {
-                    throw new PluginError('PLUGIN_INVALID_INPUT', `参数不能重复传入: ${name}`);
-                }
-            }
-            const input = { ...positionalInput, ...namedInput };
-            if (!envelope &&
-                !command.registeredArguments.some(argument => argument.variadic) &&
-                positionals.length - 1 > command.registeredArguments.length) {
-                throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数过多');
-            }
-            for (const argument of command.registeredArguments) {
-                const value = Object.hasOwn(input, argument.name()) ? input[argument.name()] : undefined;
-                if (argument.required &&
-                    (value === undefined ||
-                        value === null ||
-                        value === '' ||
-                        (Array.isArray(value) && value.length === 0))) {
-                    throw new PluginError('PLUGIN_INVALID_INPUT', `缺少必填参数: ${argument.name()}`);
-                }
-                if (argument.variadic && value !== undefined && !Array.isArray(value)) {
-                    throw new PluginError('PLUGIN_INVALID_INPUT', `${argument.name()} 必须为数组`);
-                }
-            }
-            executing = true;
-            try {
-                return await handler(input);
-            }
-            finally {
-                executing = false;
-            }
+        run(positionals, payload, namedInput = {}) {
+            return run(positionals, payload, namedInput);
+        },
+        runToolbox(invocation) {
+            return run([], invocation, {}, true);
         },
     };
 }
@@ -348,3 +371,8 @@ async function invokeRegisteredPluginWithState(name, invocation, context, option
 export function invokeRegisteredPlugin(name, invocation, context, options = {}) {
     return invokeRegisteredPluginWithState(name, invocation, context, options);
 }
+/** Entry point for the native toolbox service; nested plugin calls retain public-command access. */
+export async function invokeRegisteredToolboxPlugin(name, invocation, context, options = {}) {
+    const plugin = await loadRegisteredPluginWithState(name, context, options);
+    return plugin.runToolbox(invocation);
+}

package/dist/pluginPageBundle.d.ts

@@ -6,4 +6,5 @@ export interface BuiltPluginPageBundle {
     chunks: number;
     sources: Record<string, string>;
 }
+export declare const PLUGIN_PAGE_RUNTIME_HASH: string;
 export declare function buildPluginPageBundle(entry: string, pageEntry: string): BuiltPluginPageBundle;

package/dist/pluginPageBundle.js

@@ -103,6 +103,8 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   };
 
   const runningOperations = async () => requestHost('invoke-operations');
+  const readClipboard = async () => requestHost('clipboard-read');
+  const getActiveTab = async () => requestHost('active-tab');
 
   const selectDirectory = async () => {
     const path = await requestHost('select-directory');
@@ -119,6 +121,14 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     await requestHost('clipboard-write', { text });
   };
 
+  const copyImage = async data => {
+    if (typeof data !== 'string' || data.length > 16 * 1024 * 1024 ||
+        !/^data:image\/(png|jpeg|webp);base64,/.test(data)) {
+      throw new Error('Clipboard image must be a PNG, JPEG or WebP data URL within 16 MiB');
+    }
+    await requestHost('clipboard-image-write', { data });
+  };
+
   const openExternalLink = async url => {
     if (typeof url !== 'string' || !url || url.length > 8192) {
       throw new Error('External link must be a non-empty URL no longer than 8192 characters');
@@ -441,7 +451,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     return query;
   };
 
-  const api = { copyText, invoke, operation, ready: () => ready, runAgentTask, runningOperations, selectDirectory, setAgentGuides, setAgentPanelVisible, setQueryParam, start, toast };
+  const api = { copyImage, copyText, getActiveTab, invoke, operation, readClipboard, ready: () => ready, runAgentTask, runningOperations, selectDirectory, setAgentGuides, setAgentPanelVisible, setQueryParam, start, toast };
   const ui = globalThis.__mearlToolboxUi;
   if (ui !== undefined) {
     if (!ui || typeof ui !== 'object' || ui.runtime !== 'preact') {
@@ -604,6 +614,11 @@ body {
 }
 button, input, select, textarea { font: inherit; }
 </style>`;
+export const PLUGIN_PAGE_RUNTIME_HASH = createHash('sha256')
+    .update(PAGE_BRIDGE_SCRIPT)
+    .update(PAGE_SECURITY_META)
+    .update(PAGE_THEME_STYLE)
+    .digest('hex');
 function pluginRoot(entry) {
     const entryDirectory = dirname(entry);
     return basename(entryDirectory) === 'scripts' ? dirname(entryDirectory) : entryDirectory;

package/dist/pluginRegistry.d.ts

@@ -18,6 +18,7 @@ export interface PluginToolboxAgentConfig {
 }
 export interface PluginToolboxContribution {
     version: 1;
+    displayMode?: 'popup' | 'tab' | 'both';
     title: string;
     description?: string;
     icon?: string;
@@ -40,6 +41,7 @@ export interface PluginRegistration {
     source?: {
         entry: string;
         page?: Record<string, string>;
+        pageRuntime?: string;
     };
 }
 export declare function pluginRegistrationNeedsRefresh(registration: PluginRegistration, includePage?: boolean): boolean;

package/dist/pluginRegistry.js

@@ -3,7 +3,7 @@ import { closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, re
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { COMMAND_MAP } from './commands.js';
-import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, } from './pluginPageBundle.js';
+import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, PLUGIN_PAGE_RUNTIME_HASH, } from './pluginPageBundle.js';
 import { pluginFileVersion } from './pluginSource.js';
 const RESERVED_NAMES = new Set([
     'check',
@@ -27,6 +27,8 @@ export function pluginRegistrationNeedsRefresh(registration, includePage = false
         return true;
     if (!includePage || !registration.toolbox)
         return false;
+    if (registration.source.pageRuntime !== PLUGIN_PAGE_RUNTIME_HASH)
+        return true;
     if (!registration.source.page)
         return true;
     return Object.entries(registration.source.page).some(([path, version]) => pluginFileVersion(path) !== version);
@@ -108,6 +110,10 @@ export function normalizePluginToolboxContribution(value) {
         throw new Error('toolbox 必须是对象');
     }
     const candidate = value;
+    if (candidate.displayMode !== undefined &&
+        !['popup', 'tab', 'both'].includes(candidate.displayMode)) {
+        throw new Error('toolbox.displayMode 必须是 popup、tab 或 both');
+    }
     const title = typeof candidate.title === 'string' ? candidate.title.trim() : '';
     const description = typeof candidate.description === 'string' ? candidate.description.trim() : undefined;
     const icon = typeof candidate.icon === 'string' ? candidate.icon.trim() : undefined;
@@ -216,6 +222,7 @@ export function normalizePluginToolboxContribution(value) {
     return {
         version: 1,
         title,
+        ...(candidate.displayMode !== undefined ? { displayMode: candidate.displayMode } : {}),
         ...(description ? { description } : {}),
         ...(icon ? { icon } : {}),
         ...(locales ? { locales } : {}),
@@ -281,7 +288,10 @@ export function registerPlugin(name, target, description, options = {}) {
     }
     const record = {
         entry,
-        source: { entry: entryVersion, ...(builtPage ? { page: builtPage.sources } : {}) },
+        source: {
+            entry: entryVersion,
+            ...(builtPage ? { page: builtPage.sources, pageRuntime: PLUGIN_PAGE_RUNTIME_HASH } : {}),
+        },
         ...(summary ? { description: summary } : {}),
         ...(managedBy ? { managedBy } : {}),
         ...(toolbox ? { toolbox } : {}),
@@ -344,6 +354,8 @@ export function findPluginRegistration(name) {
                 typeof source !== 'object' ||
                 Array.isArray(source) ||
                 typeof source.entry !== 'string' ||
+                (source.pageRuntime !== undefined &&
+                    (typeof source.pageRuntime !== 'string' || !/^[a-f0-9]{64}$/.test(source.pageRuntime))) ||
                 (source.page !== undefined &&
                     (!source.page ||
                         typeof source.page !== 'object' ||

package/dist/pythonPlugin.d.ts

@@ -2,6 +2,7 @@ import type { PluginOptions } from './plugin.js';
 export interface PythonPluginCommand {
     description: string;
     signature: string;
+    toolboxOnly: boolean;
 }
 export interface PythonPluginDescriptor {
     commands: PythonPluginCommand[];

package/dist/pythonPlugin.js

@@ -53,6 +53,12 @@ class _App:
         self.request_id = 0
 
     def command(self, signature, handler=None, description=""):
+        return self._register_command(signature, handler, description, False)
+
+    def toolboxCommand(self, signature, handler=None, description=""):
+        return self._register_command(signature, handler, description, True)
+
+    def _register_command(self, signature, handler, description, toolbox_only):
         if not self.registering:
             raise RuntimeError("命令只能在入口注册阶段声明")
         if not isinstance(signature, str):
@@ -67,6 +73,7 @@ class _App:
                 "signature": signature,
                 "description": description,
                 "handler": candidate,
+                "toolboxOnly": toolbox_only,
             })
             return candidate
 
@@ -163,7 +170,7 @@ try:
     descriptor = {
         "type": "ready",
         "commands": [
-            {"signature": item["signature"], "description": item["description"]}
+            {"signature": item["signature"], "description": item["description"], "toolboxOnly": item["toolboxOnly"]}
             for item in app.commands
         ],
     }
@@ -223,10 +230,15 @@ function parseDescriptor(message) {
     const commands = message.commands.map(value => {
         if (!isObject(value) ||
             typeof value.signature !== 'string' ||
-            typeof value.description !== 'string') {
+            typeof value.description !== 'string' ||
+            typeof value.toolboxOnly !== 'boolean') {
             throw new Error('Python 插件返回了无效的命令描述');
         }
-        return { signature: value.signature, description: value.description };
+        return {
+            signature: value.signature,
+            description: value.description,
+            toolboxOnly: value.toolboxOnly,
+        };
     });
     if (message.name !== undefined && typeof message.name !== 'string') {
         throw new Error('Python 插件返回了无效的 name');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.20.1",
+  "version": "2.20.2",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -59,8 +59,8 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.20.1",
-    "@mearl/provider": "2.20.1"
+    "@mearl/provider": "2.20.2",
+    "@mearl/cloud-types": "2.20.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",