@mearl/client 2.17.0 → 2.18.0

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

@@ -48,6 +48,43 @@ export const APP_PROFILE_NAMES = [
     'didi',
     'easybike',
 ];
+export const TAB_ID_REQUIRED_ACTIONS = [
+    'page_screenshot',
+    'tab_close',
+    'page_click',
+    'page_drag',
+    'page_type',
+    'page_scroll',
+    'page_hover',
+    'page_eval',
+    'page_inspect',
+    'page_snapshot',
+    'page_press',
+    'page_wait',
+    'page_navigate',
+    'page_upload',
+    'page_frames',
+    'set_device_emulation',
+    'set_app_profile',
+    'set_timezone',
+    'get_cookie',
+    'set_cookie',
+    'run_actions',
+];
+const TAB_ID_REQUIRED_ACTION_SET = new Set(TAB_ID_REQUIRED_ACTIONS);
+export function actionRequiresTabId(action) {
+    return typeof action === 'string' && TAB_ID_REQUIRED_ACTION_SET.has(action);
+}
+export function validateRequiredActionTabId(action, data) {
+    if (!actionRequiresTabId(action))
+        return;
+    const tabId = data && typeof data === 'object' && !Array.isArray(data)
+        ? data.tabId
+        : undefined;
+    if (typeof tabId !== 'number' || !Number.isSafeInteger(tabId) || tabId < 0) {
+        throw new Error(`${action} requires a numeric tabId. Call tab_open or tab_list to obtain a tabId.`);
+    }
+}
 export const PAGE_ACT_ACTIONS = [
     'page_click',
     'page_drag',
@@ -76,7 +113,6 @@ export const BROWSER_ACTIONS = {
     browser_launch: true,
     browser_close: true,
     page_screenshot: true,
-    page_selected_element: true,
     tab_open: true,
     tab_close: true,
     tab_list: true,
@@ -86,6 +122,7 @@ export const BROWSER_ACTIONS = {
     page_scroll: true,
     page_hover: true,
     page_eval: true,
+    page_inspect: true,
     page_snapshot: true,
     page_press: true,
     page_wait: true,
@@ -117,7 +154,6 @@ export const BROWSER_COMMAND_ACTIONS = {
     browser_launch: true,
     browser_close: true,
     page_screenshot: true,
-    page_selected_element: true,
     tab_open: true,
     tab_close: true,
     tab_list: true,
@@ -127,6 +163,7 @@ export const BROWSER_COMMAND_ACTIONS = {
     page_scroll: true,
     page_hover: true,
     page_eval: true,
+    page_inspect: true,
     page_snapshot: true,
     page_press: true,
     page_wait: true,
@@ -155,7 +192,6 @@ export const EXTENSION_BROWSER_ACTIONS = {
     send_mtop_request: true,
     browser_release: true,
     page_screenshot: true,
-    page_selected_element: true,
     tab_open: true,
     tab_close: true,
     tab_list: true,
@@ -165,6 +201,7 @@ export const EXTENSION_BROWSER_ACTIONS = {
     page_scroll: true,
     page_hover: true,
     page_eval: true,
+    page_inspect: true,
     page_snapshot: true,
     page_press: true,
     page_wait: true,

package/dist/index.d.ts

@@ -6,9 +6,9 @@
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
-export type { PluginInvocation, PluginInvokeOptions } from './plugin.js';
+export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugin.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_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, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, 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, 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'>>;
@@ -29,7 +29,6 @@ export declare function browserClose(params: Protocol.BrowserCloseParams, option
 export declare function setRule(params: Protocol.SetRuleParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_rule'>>;
 export declare function getRules(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_rules'>>;
 export declare function pageScreenshot(params: Protocol.PageScreenshotParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_screenshot'>>;
-export declare function pageSelectedElement(params: Protocol.PageSelectedElementParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_selected_element'>>;
 export declare function tabOpen(params: Protocol.TabOpenParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_open'>>;
 export declare function tabClose(params: Protocol.TabCloseParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_close'>>;
 export declare function tabList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_list'>>;
@@ -39,6 +38,7 @@ export declare function pageType(params: Protocol.PageTypeParams, options?: Unif
 export declare function pageScroll(params: Protocol.PageScrollParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_scroll'>>;
 export declare function pageHover(params: Protocol.PageHoverParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_hover'>>;
 export declare function pageEval(params: Protocol.PageEvalParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_eval'>>;
+export declare function pageInspect(params: Protocol.PageInspectParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_inspect'>>;
 export declare function pageSnapshot(params: Protocol.PageSnapshotParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_snapshot'>>;
 export declare function pagePress(params: Protocol.PagePressParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_press'>>;
 export declare function pageWait(params: Protocol.PageWaitParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_wait'>>;

package/dist/index.js

@@ -59,9 +59,6 @@ export function getRules(options) {
 export function pageScreenshot(params, options) {
     return invoke('page_screenshot', params, options);
 }
-export function pageSelectedElement(params, options) {
-    return invoke('page_selected_element', params, options);
-}
 export function tabOpen(params, options) {
     return invoke('tab_open', params, options);
 }
@@ -89,6 +86,9 @@ export function pageHover(params, options) {
 export function pageEval(params, options) {
     return invoke('page_eval', params, options);
 }
+export function pageInspect(params, options) {
+    return invoke('page_inspect', params, options);
+}
 export function pageSnapshot(params, options) {
     return invoke('page_snapshot', params, options);
 }

package/dist/plugin.d.ts

@@ -1,14 +1,20 @@
 import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
+import { type PluginToolboxContribution } from './pluginRegistry.js';
 import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, type PluginRegistrationOptions, } from './pluginRegistry.js';
+export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, type PluginRegistration, type PluginRegistrationOptions, type PluginToolboxAgentConfig, type PluginPageBundleRegistration, type PluginToolboxContribution, type PluginToolboxLocale, type PluginToolboxSandboxPage, } from './pluginRegistry.js';
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, type OfficialPluginDefinition, type OfficialPluginName, } from './officialPluginCatalog.js';
 export type PluginOptions = UnifiedInvokeOptions;
+export interface StructuredPluginProgress {
+    message: string;
+    data?: Record<string, unknown>;
+}
+export type PluginProgress = string | StructuredPluginProgress;
 export interface PluginInvocation {
     command: string;
     input: Record<string, any>;
 }
 export interface PluginInvokeOptions extends UnifiedInvokeOptions {
-    onProgress?: (message: string) => void;
+    onProgress?: (progress: PluginProgress) => void;
 }
 export interface PluginExecutionContext {
     ensurePlugin?: OfficialPluginInstaller;
@@ -18,13 +24,14 @@ export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
     command(signature: string, handler: PluginHandler, description?: string): void;
     invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
-    progress(message: string): void;
+    progress(progress: PluginProgress): void;
 }
 export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
 /** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
 export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
     name: string | undefined;
     description: string | undefined;
+    toolbox: PluginToolboxContribution | undefined;
     version: string | undefined;
     commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;
@@ -33,6 +40,7 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invo
 export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
     name: string | undefined;
     description: string | undefined;
+    toolbox: PluginToolboxContribution | undefined;
     version: string | undefined;
     commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;

package/dist/plugin.js

@@ -5,9 +5,9 @@ import { Command } from 'commander';
 import { COMMAND_MAP } from './commands.js';
 import { findOfficialPlugin } from './officialPluginCatalog.js';
 import { ensureOfficialPluginRegistered, } from './officialPluginInstaller.js';
-import { findPluginRegistration, PluginError } from './pluginRegistry.js';
+import { findPluginRegistration, normalizePluginToolboxContribution, PluginError, } from './pluginRegistry.js';
 import { describePythonPlugin, runPythonPluginCommand } from './pythonPlugin.js';
-export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
+export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, } from './pluginRegistry.js';
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, } from './officialPluginCatalog.js';
 function readPluginVersion(entry) {
     try {
@@ -26,6 +26,36 @@ function isObject(value) {
 function isPluginInvocation(value) {
     return isObject(value) && typeof value.command === 'string' && isObject(value.input);
 }
+function normalizePluginProgress(progress) {
+    if (typeof progress === 'string') {
+        if (!progress)
+            throw new Error('app.progress 需要非空消息');
+        return progress;
+    }
+    if (!isObject(progress) || typeof progress.message !== 'string' || !progress.message) {
+        throw new Error('app.progress 需要非空消息');
+    }
+    if (progress.data !== undefined && !isObject(progress.data)) {
+        throw new Error('app.progress data 必须是对象');
+    }
+    let data;
+    if (progress.data) {
+        try {
+            const serialized = JSON.stringify(progress.data);
+            const parsed = serialized === undefined ? undefined : JSON.parse(serialized);
+            if (!isObject(parsed))
+                throw new Error('invalid object');
+            data = Object.freeze(parsed);
+        }
+        catch {
+            throw new Error('app.progress data 必须是可 JSON 序列化的对象');
+        }
+    }
+    return Object.freeze({
+        message: progress.message,
+        ...(data ? { data } : {}),
+    });
+}
 function missingPluginEntryMessage(entry, pluginName) {
     const name = pluginName ?? '<name>';
     return [
@@ -54,6 +84,7 @@ export async function loadPlugin(entry, context, pluginName) {
     let registering = true;
     let name;
     let description;
+    let toolbox;
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
         command(signature, handler, description = '') {
@@ -80,12 +111,10 @@ export async function loadPlugin(entry, context, pluginName) {
                 throw new Error('app.invoke 只能在命令执行期间调用');
             return context.invoke(action, payload, options);
         },
-        progress(message) {
+        progress(progress) {
             if (!executing)
                 throw new Error('app.progress 只能在命令执行期间调用');
-            if (typeof message !== 'string' || !message)
-                throw new Error('app.progress 需要非空字符串');
-            context.progress(message);
+            context.progress(normalizePluginProgress(progress));
         },
     });
     try {
@@ -93,6 +122,7 @@ export async function loadPlugin(entry, context, pluginName) {
             const descriptor = await describePythonPlugin(entry, app.options);
             name = descriptor.name;
             description = descriptor.description;
+            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);
@@ -108,12 +138,18 @@ export async function loadPlugin(entry, context, pluginName) {
             if (module.description !== undefined && typeof module.description !== 'string')
                 throw new Error('入口的 description 导出必须为字符串');
             description = module.description;
+            toolbox = normalizePluginToolboxContribution(module.toolbox);
             if (typeof module.default !== 'function')
                 throw new Error('入口必须默认导出 register(app) 函数');
             await module.default(app);
         }
         if (commands.size === 0)
             throw new Error('入口未注册任何命令');
+        const toolboxCommands = toolbox?.page.commands ?? [];
+        for (const command of toolboxCommands) {
+            if (!commands.has(command))
+                throw new Error(`toolbox 命令未注册: ${command}`);
+        }
     }
     catch (error) {
         throw new PluginError('PLUGIN_LOAD_FAILED', `${entry}: ${error instanceof Error ? error.message : String(error)}`);
@@ -130,6 +166,7 @@ export async function loadPlugin(entry, context, pluginName) {
     return {
         name,
         description,
+        toolbox,
         version: readPluginVersion(entry),
         commandHelp(namespace) {
             return [...commands.values()]
@@ -215,7 +252,7 @@ async function loadRegisteredPluginWithState(name, context, options = {}, state
     }
     let registration = findPluginRegistration(name);
     if (!registration && findOfficialPlugin(name)) {
-        await (context.ensurePlugin ?? ensureOfficialPluginRegistered)(name, options.onProgress);
+        await (context.ensurePlugin ?? ensureOfficialPluginRegistered)(name, options.onProgress ? message => options.onProgress?.(message) : undefined);
         registration = findPluginRegistration(name);
     }
     if (!registration) {

package/dist/pluginPageBundle.d.ts

@@ -0,0 +1,8 @@
+export declare const PLUGIN_PAGE_CHUNK_BYTES: number;
+export interface BuiltPluginPageBundle {
+    content: string;
+    hash: string;
+    size: number;
+    chunks: number;
+}
+export declare function buildPluginPageBundle(entry: string, pageEntry: string): BuiltPluginPageBundle;