@mearl/client 2.20.1 → 2.20.3

package/README.md

@@ -76,6 +76,8 @@ mearl browser_release
 
 多步骤任务首次 `tab_open` 或 `page_snapshot` 使用 `--session new`，响应在原结果旁附带 `session`，后续用其 `sessionId` 自动路由，无需额外创建/查询 action。Session 绑定一个浏览器与传输；页面首次使用自动关联，复用页面与新建页面分别记录。同一页面只允许一个会话控制，旧调用不能绕过占用；Session 不隔离 Cookie 或存储。
 
+`sessionId` 是形如 `s_aB3d_E-f` 的短 ID。会话及其浏览器、传输映射保存在常驻控制宿主的内存中；新的 CLI 进程会内部查询本机和远端宿主完成路由，无需调用方保存或传递路由信息，也不写入会话映射文件。控制宿主退出后会话失效。
+
 旧调用不必传 `--session`，现有动作、`run_actions` 批次和上传 `filePaths` 参数继续可用。活动会话存在时，旧调用不能操作其占用页面、执行浏览器级释放/关闭或修改共享设置；旧批次中的开页/关闭浏览器需改为独立调用。CDP Mock 按标签页生效，跨页使用同一 Mock 时需分别配置。
 
 ```bash
@@ -268,6 +270,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(command, input)` 或 `window.mearl.invoke('host.operation.start', { command, input })` 执行；两类命令都必须显式列在 `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";
@@ -718,7 +722,19 @@ export declare const COMMANDS: readonly [{
         readonly name: "expression";
         readonly type: "string";
         readonly required: true;
-        readonly description: "要执行的 JS 表达式";
+        readonly description: "要执行的 JS 表达式；传 args 时须求值为函数";
+    }, {
+        readonly name: "args";
+        readonly type: "unknown[]";
+        readonly description: "传给页面函数的 JSON 参数；SDK/CLI 自动处理大参数分块，保持指定执行环境";
+    }, {
+        readonly name: "executionWorld";
+        readonly type: "string";
+        readonly description: "main（默认）读取网页 JS；isolated 使用命名隔离环境，扩展连接无需 debugger";
+    }, {
+        readonly name: "worldId";
+        readonly type: "string";
+        readonly description: "isolated 必填，小写字母开头，允许数字和连字符，最长 64 字符";
     }, {
         readonly name: "awaitPromise";
         readonly type: "boolean";
@@ -949,6 +965,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "quality";
         readonly type: "number";
         readonly description: "JPEG 压缩质量（0-100），默认 80";
+    }, {
+        readonly name: "captureMode";
+        readonly type: "\"cdp\" | \"visible\"";
+        readonly description: "默认 cdp；visible 使用活动标签页截图，普通网页无需 debugger；设备模拟复用模拟会话并截取业务视口，不支持 selector";
     }, {
         readonly name: "tabId";
         readonly type: "number";
@@ -956,7 +976,7 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly notes: readonly ["使用 --output <path> 保存图片；省略时 stdout 返回含 base64 data 的 JSON，避免直接将其加载为文本。"];
-    readonly result: readonly ["meta 包含 format、width、height、size、url、title；宽高为物理像素（CSS 尺寸 × DPR）。"];
+    readonly result: readonly ["meta 包含 format、width、height、size、url、title；宽高为实际截图的物理像素。"];
     readonly examples: ["page_screenshot --payload '{\"tabId\":12345}' --output ./screenshot.png", "page_screenshot --payload '{\"tabId\":12345,\"selector\":\".product-card\"}' --output ./card.png"];
 }, {
     readonly name: "set_device_emulation";

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"}}'`,
         ],
     },
     {
@@ -780,7 +787,27 @@ export const COMMANDS = [
         name: 'page_eval',
         description: '在页面上下文中执行任意 JavaScript 表达式',
         params: [
-            { name: 'expression', type: 'string', required: true, description: '要执行的 JS 表达式' },
+            {
+                name: 'expression',
+                type: 'string',
+                required: true,
+                description: '要执行的 JS 表达式；传 args 时须求值为函数',
+            },
+            {
+                name: 'args',
+                type: 'unknown[]',
+                description: '传给页面函数的 JSON 参数；SDK/CLI 自动处理大参数分块，保持指定执行环境',
+            },
+            {
+                name: 'executionWorld',
+                type: 'string',
+                description: 'main（默认）读取网页 JS；isolated 使用命名隔离环境，扩展连接无需 debugger',
+            },
+            {
+                name: 'worldId',
+                type: 'string',
+                description: 'isolated 必填，小写字母开头，允许数字和连字符，最长 64 字符',
+            },
             {
                 name: 'awaitPromise',
                 type: 'boolean',
@@ -1042,14 +1069,17 @@ export const COMMANDS = [
             { name: 'selector', type: 'string', description: 'CSS 选择器，提供后只截取该元素区域' },
             { name: 'format', type: '"png" | "jpeg"', description: '图片格式，默认 png' },
             { name: 'quality', type: 'number', description: 'JPEG 压缩质量（0-100），默认 80' },
+            {
+                name: 'captureMode',
+                type: '"cdp" | "visible"',
+                description: '默认 cdp；visible 使用活动标签页截图，普通网页无需 debugger；设备模拟复用模拟会话并截取业务视口，不支持 selector',
+            },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         notes: [
             '使用 --output <path> 保存图片；省略时 stdout 返回含 base64 data 的 JSON，避免直接将其加载为文本。',
         ],
-        result: [
-            'meta 包含 format、width、height、size、url、title；宽高为物理像素（CSS 尺寸 × DPR）。',
-        ],
+        result: ['meta 包含 format、width、height、size、url、title；宽高为实际截图的物理像素。'],
         examples: [
             `page_screenshot --payload '{"tabId":12345}' --output ./screenshot.png`,
             `page_screenshot --payload '{"tabId":12345,"selector":".product-card"}' --output ./card.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;
@@ -426,6 +437,7 @@ export interface PageScreenshotParams {
     selector?: string;
     format?: 'png' | 'jpeg';
     quality?: number;
+    captureMode?: 'cdp' | 'visible';
 }
 export declare const BROWSER_DEVICE_PRESET_NAMES: readonly ["iphone-duo-folded", "iphone-duo-unfolded", "iphone-17-pro", "iphone-17e", "pixel-11", "ipad-mini-a17-pro", "galaxy-s26", "pura-x-max", "iphone-15-pro", "iphone-se", "pixel-8", "ipad-mini", "galaxy-s23"];
 export type BrowserDevicePresetName = (typeof BROWSER_DEVICE_PRESET_NAMES)[number];
@@ -604,11 +616,22 @@ export interface PageHoverParams {
 export interface PageEvalParams {
     tabId: number;
     expression: string;
+    /** When provided, expression must evaluate to a function called with these JSON arguments. */
+    args?: unknown[];
     frameId?: string;
     awaitPromise?: boolean;
-    observe?: PageObservationWaitOptions;
+    observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
+    executionWorld?: 'main' | 'isolated';
+    worldId?: string;
+}
+export declare function resolvePageEvalExpression(params: Pick<PageEvalParams, 'expression' | 'args'>): string;
+export interface PageUserScriptParams {
+    tabId: number;
+    worldId: string;
+    code: string;
 }
+export declare function validatePageUserScriptParams(params: PageUserScriptParams): void;
 export interface PageSnapshotQuery {
     text?: string;
     role?: string;

package/dist/generated-browser-action-protocol.js

@@ -50,6 +50,26 @@ export const APP_PROFILE_NAMES = [
     'didi',
     'easybike',
 ];
+export function resolvePageEvalExpression(params) {
+    if (typeof params.expression !== 'string' || !params.expression.trim())
+        throw new Error('Invalid expression');
+    if (params.args === undefined)
+        return params.expression;
+    if (!Array.isArray(params.args))
+        throw new Error('page_eval args must be an array');
+    return `(${params.expression})(...JSON.parse(${JSON.stringify(JSON.stringify(params.args))}))`;
+}
+export function validatePageUserScriptParams(params) {
+    if (!Number.isSafeInteger(params?.tabId) || params.tabId < 0) {
+        throw new Error('Invalid target tab');
+    }
+    if (typeof params.worldId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(params.worldId)) {
+        throw new Error('Invalid user script worldId');
+    }
+    if (typeof params.code !== 'string' || !params.code.trim() || params.code.length > 256 * 1024) {
+        throw new Error('User script code must be non-empty and within 256 KiB characters');
+    }
+}
 export const TAB_ID_REQUIRED_ACTIONS = [
     'tab_checkpoint',
     'capture_checkpoint',

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/pageEvalArguments.d.ts

@@ -0,0 +1,3 @@
+import { type PageEvalParams } from './generated-browser-action-protocol.js';
+/** Serialize page_eval arguments within transport limits while retaining the caller's execution world. */
+export declare function invokePageEvalWithArgs(invoke: (payload: Record<string, unknown>, transfer?: boolean) => Promise<any>, params: PageEvalParams): Promise<any>;

package/dist/pageEvalArguments.js

@@ -0,0 +1,47 @@
+import { randomUUID } from 'node:crypto';
+import { validatePageUserScriptParams, resolvePageEvalExpression, } from './generated-browser-action-protocol.js';
+const CHUNK_CHARACTERS = 48 * 1024;
+/** Serialize page_eval arguments within transport limits while retaining the caller's execution world. */
+export async function invokePageEvalWithArgs(invoke, params) {
+    if (!Number.isSafeInteger(params.tabId) || params.tabId < 0)
+        throw new Error('Invalid target tab');
+    resolvePageEvalExpression({ expression: params.expression, args: [] });
+    if (!Array.isArray(params.args))
+        throw new Error('page_eval args must be an array');
+    if (params.executionWorld !== undefined && !['main', 'isolated'].includes(params.executionWorld))
+        throw new Error('Invalid page executionWorld');
+    if (params.executionWorld === 'isolated')
+        validatePageUserScriptParams({
+            tabId: params.tabId,
+            worldId: params.worldId ?? '',
+            code: params.expression,
+        });
+    const args = JSON.stringify(params.args);
+    if (args.length > 64 * 1024 * 1024)
+        throw new Error('Page script arguments must fit within 64 MiB characters');
+    const { args: _args, ...request } = params;
+    const evaluate = async (expression, transfer = false) => {
+        const payload = {
+            ...request,
+            ...(transfer ? { observe: false, diagnostics: false } : {}),
+            expression,
+        };
+        const result = await (transfer ? invoke(payload, true) : invoke(payload));
+        if (transfer && result?.action?.success === false)
+            throw new Error(result.action.error || 'page_eval failed');
+        return result;
+    };
+    if (args.length + params.expression.length <= CHUNK_CHARACTERS) {
+        return evaluate(resolvePageEvalExpression(params));
+    }
+    const key = JSON.stringify('__mearlPageScriptTransfer_' + randomUUID());
+    try {
+        for (let offset = 0; offset < args.length; offset += CHUNK_CHARACTERS) {
+            await evaluate(`void (window[${key}] = (window[${key}] || '') + ${JSON.stringify(args.slice(offset, offset + CHUNK_CHARACTERS))})`, true);
+        }
+        return await evaluate(`(() => { const args = JSON.parse(window[${key}]); delete window[${key}]; return (${params.expression})(...args); })()`);
+    }
+    finally {
+        await evaluate(`delete window[${key}]`, true).catch(() => { });
+    }
+}

package/dist/plugin.d.ts

@@ -1,3 +1,4 @@
+export { invokePageEvalWithArgs } from './pageEvalArguments.js';
 import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
 import { type PluginToolboxContribution, type PluginRegistration } from './pluginRegistry.js';
 import type { UnifiedInvokeOptions } from './unified.js';
@@ -24,6 +25,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 +42,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 +52,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

@@ -1,3 +1,4 @@
+export { invokePageEvalWithArgs } from './pageEvalArguments.js';
 import { readFileSync } from 'node:fs';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -133,31 +134,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 +180,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 +202,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 +218,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 +307,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 +372,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;