@mearl/client 2.19.2 → 2.20.0

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

@@ -173,7 +173,7 @@ export interface BrowserInfoBase {
 }
 export type BrowserScreenshotKind = 'native' | 'reconstructed' | 'none';
 /** Browser-targeted actions that an external provider may implement. */
-export type BrowserCapabilityAction = ExtensionBrowserAction;
+export type BrowserCapabilityAction = ExtensionBrowserAction | 'page_download';
 /** Capabilities advertised by an external browser-control provider. */
 export interface BrowserCapabilities {
     actions: BrowserCapabilityAction[];
@@ -222,6 +222,52 @@ export interface BrowserReleaseResult {
     affectedTabIds: number[];
     failures?: BrowserReleaseFailure[];
 }
+export interface ControlSessionInfo {
+    sessionId: string;
+    browserId: string;
+    transport: BrowserTransport;
+    status: 'active' | 'user' | 'releasing' | 'released';
+    generation: number;
+    tabs: Array<{
+        tabId: number;
+        source: 'created' | 'attached';
+        title?: string;
+        url?: string;
+    }>;
+    reason?: string;
+}
+export interface BrowserReleaseParams {
+    /** Close only session-created pages; attached user pages are protected. */
+    closeCreatedTabs?: boolean;
+    keepTabIds?: number[];
+    /** Preserve the browser environment by default for a scoped release. */
+    preserveEnvironment?: boolean;
+    keepArtifactIds?: string[];
+}
+export interface BrowserControlParams {
+    operation: 'handoff' | 'resume';
+    tabId?: number;
+    reason?: string;
+}
+export interface BrowserArtifact {
+    artifactId: string;
+    filename: string;
+    bytes: number;
+    location: 'browser';
+    /** Global browser route is attached by the unified client. */
+    browserId?: string;
+}
+export interface PageDownloadParams {
+    tabId: number;
+    trigger: Omit<PageClickParams, 'tabId'>;
+    /** Restrict the expected download URL; useful when the browser cannot identify its source. */
+    url?: string;
+    timeout?: number;
+}
+export interface PageDownloadResult {
+    download: BrowserArtifact;
+    action: unknown;
+}
 export interface CookieCopyScope {
     /** Maintained authentication-domain presets to include. */
     presets?: Array<'mearl-services'>;
@@ -595,7 +641,14 @@ export interface PageNavigateParams {
 export interface PageUploadParams {
     tabId: number;
     selector: string;
-    filePaths: string[];
+    /** Absolute paths available to the browser host. */
+    filePaths?: string[];
+    /** SDK/CLI stages caller-local files before dispatch. Mutually exclusive with filePaths. */
+    files?: Array<{
+        filePath: string;
+    } | {
+        artifactId: string;
+    }>;
     observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
 }
@@ -616,9 +669,10 @@ export interface SetTimezoneResult {
     timezone: string | null;
 }
 export interface GetCookieParams {
-    tabId: number;
+    /** Select the tab's cookie store; omitted for the browser's default store. */
+    tabId?: number;
     name: string;
-    /** Cookie lookup URL; defaults to the current tab URL. */
+    /** Cookie lookup URL; required without tabId, otherwise defaults to the tab URL. */
     url?: string;
     domain?: string;
     path?: string;
@@ -633,9 +687,12 @@ export interface GetCookieResult {
     path?: string;
 }
 export interface SetCookieParams {
-    tabId: number;
+    /** Select the tab's cookie store; required when reload is true. */
+    tabId?: number;
     name: string;
     value: string;
+    /** Cookie target URL; required when tabId is omitted. */
+    url?: string;
     domain?: string;
     path?: string;
     reload?: boolean;
@@ -715,9 +772,19 @@ export interface BrowserActionMap {
         response: SelectBrowserResult;
     };
     browser_release: {
-        request: undefined;
+        request: BrowserReleaseParams;
         response: BrowserReleaseResult;
     };
+    browser_control: {
+        request: BrowserControlParams;
+        response: {
+            session: ControlSessionInfo;
+        };
+    };
+    page_download: {
+        request: PageDownloadParams;
+        response: PageDownloadResult;
+    };
     browser_launch: {
         request: BrowserLaunchParams;
         response: ManagedBrowserInfo;
@@ -829,10 +896,12 @@ export interface BrowserActionMap {
 }
 export type BrowserAction = keyof BrowserActionMap;
 export type BrowserActionRequest<A extends BrowserAction> = BrowserActionMap[A]['request'];
-export type BrowserActionResponse<A extends BrowserAction> = BrowserActionMap[A]['response'];
+export type BrowserActionResponse<A extends BrowserAction> = BrowserActionMap[A]['response'] & {
+    session?: ControlSessionInfo;
+};
 export type BrowserCommandAction = Exclude<BrowserAction, 'browser_select_browser'>;
-export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list' | 'browser_launch' | 'browser_close'>;
-export declare const TAB_ID_REQUIRED_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "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"];
+export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list' | 'browser_launch' | 'browser_close' | 'browser_control' | 'page_download'>;
+export declare const TAB_ID_REQUIRED_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "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_download", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "run_actions"];
 export type TabIdRequiredAction = (typeof TAB_ID_REQUIRED_ACTIONS)[number];
 export declare function actionRequiresTabId(action: unknown): action is TabIdRequiredAction;
 export declare function validateRequiredActionTabId(action: string, data: unknown): void;
@@ -853,6 +922,8 @@ export declare const BROWSER_ACTIONS: {
     readonly browser_list: true;
     readonly browser_select_browser: true;
     readonly browser_release: true;
+    readonly browser_control: true;
+    readonly page_download: true;
     readonly browser_launch: true;
     readonly browser_close: true;
     readonly page_screenshot: true;
@@ -895,6 +966,8 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly send_mtop_request: true;
     readonly browser_list: true;
     readonly browser_release: true;
+    readonly browser_control: true;
+    readonly page_download: true;
     readonly browser_launch: true;
     readonly browser_close: true;
     readonly page_screenshot: true;
@@ -962,6 +1035,46 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
     readonly request_domain_permission: true;
     readonly run_actions: true;
 };
+export declare const BROWSER_CAPABILITY_ACTIONS: {
+    readonly page_download: true;
+    readonly tab_checkpoint: true;
+    readonly capture_checkpoint: true;
+    readonly get_requests: true;
+    readonly get_logs: true;
+    readonly get_events: true;
+    readonly set_mock: true;
+    readonly get_mocks: true;
+    readonly set_rule: true;
+    readonly get_rules: true;
+    readonly send_request: true;
+    readonly send_mtop_request: true;
+    readonly browser_release: true;
+    readonly page_screenshot: true;
+    readonly tab_open: true;
+    readonly tab_close: true;
+    readonly tab_list: true;
+    readonly tab_group: true;
+    readonly page_click: true;
+    readonly page_drag: true;
+    readonly page_type: true;
+    readonly page_scroll: true;
+    readonly page_hover: true;
+    readonly page_eval: true;
+    readonly page_inspect: true;
+    readonly page_snapshot: true;
+    readonly page_press: true;
+    readonly page_wait: true;
+    readonly page_navigate: true;
+    readonly page_upload: true;
+    readonly page_frames: true;
+    readonly set_device_emulation: true;
+    readonly set_app_profile: true;
+    readonly set_timezone: true;
+    readonly get_cookie: true;
+    readonly set_cookie: true;
+    readonly request_domain_permission: true;
+    readonly run_actions: true;
+};
 export declare function isBrowserAction(value: unknown): value is BrowserAction;
 export declare function isBrowserCommandAction(value: unknown): value is BrowserCommandAction;
 export declare function isBrowserCapabilityAction(value: unknown): value is BrowserCapabilityAction;

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

@@ -72,12 +72,11 @@ export const TAB_ID_REQUIRED_ACTIONS = [
     'page_wait',
     'page_navigate',
     'page_upload',
+    'page_download',
     '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);
@@ -85,11 +84,22 @@ export function actionRequiresTabId(action) {
     return typeof action === 'string' && TAB_ID_REQUIRED_ACTION_SET.has(action);
 }
 export function validateRequiredActionTabId(action, data) {
-    if (!actionRequiresTabId(action))
+    const cookieAction = action === 'get_cookie' || action === 'set_cookie';
+    if (!actionRequiresTabId(action) && !cookieAction)
         return;
-    const tabId = data && typeof data === 'object' && !Array.isArray(data)
-        ? data.tabId
+    const input = data && typeof data === 'object' && !Array.isArray(data)
+        ? data
         : undefined;
+    const tabId = input?.tabId;
+    if (cookieAction && tabId === undefined) {
+        if (action === 'set_cookie' && input?.reload === true) {
+            throw new Error('set_cookie: reload requires tabId');
+        }
+        if (typeof input?.url !== 'string' || !input.url.trim()) {
+            throw new Error(`${action}: specify url or tabId`);
+        }
+        return;
+    }
     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.`);
     }
@@ -119,6 +129,8 @@ export const BROWSER_ACTIONS = {
     browser_list: true,
     browser_select_browser: true,
     browser_release: true,
+    browser_control: true,
+    page_download: true,
     browser_launch: true,
     browser_close: true,
     page_screenshot: true,
@@ -161,6 +173,8 @@ export const BROWSER_COMMAND_ACTIONS = {
     send_mtop_request: true,
     browser_list: true,
     browser_release: true,
+    browser_control: true,
+    page_download: true,
     browser_launch: true,
     browser_close: true,
     page_screenshot: true,
@@ -228,6 +242,10 @@ export const EXTENSION_BROWSER_ACTIONS = {
     request_domain_permission: true,
     run_actions: true,
 };
+export const BROWSER_CAPABILITY_ACTIONS = {
+    ...EXTENSION_BROWSER_ACTIONS,
+    page_download: true,
+};
 export function isBrowserAction(value) {
     return typeof value === 'string' && Object.hasOwn(BROWSER_ACTIONS, value);
 }
@@ -235,7 +253,7 @@ export function isBrowserCommandAction(value) {
     return typeof value === 'string' && Object.hasOwn(BROWSER_COMMAND_ACTIONS, value);
 }
 export function isBrowserCapabilityAction(value) {
-    return isExtensionBrowserAction(value);
+    return typeof value === 'string' && Object.hasOwn(BROWSER_CAPABILITY_ACTIONS, value);
 }
 export function isExtensionBrowserAction(value) {
     return typeof value === 'string' && Object.hasOwn(EXTENSION_BROWSER_ACTIONS, value);

package/dist/index.d.ts

@@ -7,7 +7,7 @@
 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, 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 { 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';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
@@ -24,6 +24,7 @@ export declare function sendMtopRequest(params: Protocol.SendMtopRequestParams,
 export declare function browserList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_list'>>;
 export declare function selectBrowser(params?: Protocol.SelectBrowserParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_select_browser'>>;
 export declare function browserRelease(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_release'>>;
+export declare function browserRelease(params: Protocol.BrowserReleaseParams, options: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_release'>>;
 export declare function browserLaunch(params: Protocol.BrowserLaunchParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_launch'>>;
 export declare function browserClose(params: Protocol.BrowserCloseParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_close'>>;
 export declare function setRule(params: Protocol.SetRuleParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_rule'>>;
@@ -52,3 +53,11 @@ export declare function setTimezone(params: Protocol.SetTimezoneParams, options?
 export declare function getCookie(params: Protocol.GetCookieParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_cookie'>>;
 export declare function setCookie(params: Protocol.SetCookieParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_cookie'>>;
 export declare function runActions(params: Protocol.RunActionsParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'run_actions'>>;
+export declare function browserControl(params: Protocol.BrowserControlParams, options?: UnifiedInvokeOptions): Promise<any>;
+export declare function pageDownload(params: Protocol.PageDownloadParams, options?: UnifiedInvokeOptions): Promise<any>;
+export declare function saveArtifact(artifact: Protocol.BrowserArtifact & {
+    browserId?: string;
+}, outputPath: string, options?: UnifiedInvokeOptions): Promise<{
+    outputPath: string;
+    bytes: number;
+}>;

package/dist/index.js

@@ -5,7 +5,7 @@
  * then routes actions using the global browser ids returned by browser_list.
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.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 { 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';
 import { invoke } from './unified.js';
 export function tabCheckpoint(params, options) {
     return invoke('tab_checkpoint', params, options);
@@ -41,8 +41,10 @@ export function browserList(options) {
 export function selectBrowser(params = {}, options) {
     return invoke('browser_select_browser', params, options);
 }
-export function browserRelease(options) {
-    return invoke('browser_release', {}, options);
+export function browserRelease(paramsOrOptions = {}, options) {
+    return options
+        ? invoke('browser_release', paramsOrOptions, options)
+        : invoke('browser_release', {}, paramsOrOptions);
 }
 export function browserLaunch(params, options) {
     return invoke('browser_launch', params, options);
@@ -128,3 +130,13 @@ export function setCookie(params, options) {
 export function runActions(params, options) {
     return invoke('run_actions', params, options);
 }
+export function browserControl(params, options) {
+    return invoke('browser_control', params, options);
+}
+export function pageDownload(params, options) {
+    return invoke('page_download', params, options);
+}
+export async function saveArtifact(artifact, outputPath, options = {}) {
+    const { exportArtifact } = await import('./artifacts.js');
+    return exportArtifact({ invoke }, artifact, outputPath, options);
+}

package/dist/plugin.d.ts

@@ -1,5 +1,5 @@
 import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
-import { type PluginToolboxContribution } from './pluginRegistry.js';
+import { type PluginToolboxContribution, type PluginRegistration } from './pluginRegistry.js';
 import type { UnifiedInvokeOptions } from './unified.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';
@@ -22,11 +22,14 @@ export interface PluginExecutionContext {
 }
 export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
-    command(signature: string, handler: PluginHandler, description?: string): void;
+    /** Examples omit the `mearl <plugin>` prefix, which help adds when displayed. */
+    command(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
     invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
     progress(progress: PluginProgress): void;
 }
 export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
+/** 工具列表仅检查入口；页面资源只在打开对应工具时检查。 */
+export declare function refreshRegisteredPlugin(name: string, includePage?: boolean): Promise<PluginRegistration | undefined>;
 /** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
 export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
     name: string | undefined;

package/dist/plugin.js

@@ -1,11 +1,12 @@
-import { readFileSync, statSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
 import { COMMAND_MAP } from './commands.js';
 import { findOfficialPlugin } from './officialPluginCatalog.js';
 import { ensureOfficialPluginRegistered, } from './officialPluginInstaller.js';
-import { findPluginRegistration, normalizePluginToolboxContribution, PluginError, } from './pluginRegistry.js';
+import { findPluginRegistration, pluginRegistrationNeedsRefresh, registerPlugin, pluginDirectory, normalizePluginToolboxContribution, PluginError, } from './pluginRegistry.js';
+import { pluginFileVersion } from './pluginSource.js';
 import { describePythonPlugin, runPythonPluginCommand } from './pythonPlugin.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';
@@ -67,14 +68,61 @@ function missingPluginEntryMessage(entry, pluginName) {
         `卸载命令：npx @mearl/setup plugin uninstall ${name}`,
     ].join('\n');
 }
+const registrationRefreshes = new Map();
+/** 工具列表仅检查入口；页面资源只在打开对应工具时检查。 */
+export async function refreshRegisteredPlugin(name, includePage = false) {
+    const key = `${pluginDirectory()}/${name}`;
+    const pending = registrationRefreshes.get(key);
+    if (pending) {
+        await pending;
+        return refreshRegisteredPlugin(name, includePage);
+    }
+    const registration = findPluginRegistration(name);
+    if (!registration)
+        return undefined;
+    const entryChanged = pluginRegistrationNeedsRefresh(registration);
+    if (!entryChanged && (!includePage || !pluginRegistrationNeedsRefresh(registration, true))) {
+        return registration;
+    }
+    const refresh = (async () => {
+        const entryVersion = pluginFileVersion(registration.entry);
+        const loaded = entryChanged
+            ? await loadPlugin(registration.entry, {
+                options: {},
+                invoke: async () => {
+                    throw new Error('注册时不能执行浏览器操作');
+                },
+                progress: () => {
+                    throw new Error('注册时不能报告执行进度');
+                },
+            }, name)
+            : registration;
+        // 异步加载期间其他进程可能卸载或重新绑定同名插件。
+        const current = findPluginRegistration(name);
+        if (JSON.stringify(current) !== JSON.stringify(registration))
+            return current;
+        if (pluginFileVersion(registration.entry) !== entryVersion) {
+            throw new PluginError('PLUGIN_SOURCE_CHANGED', `插件更新进行中，请重新打开工具: ${name}`);
+        }
+        registerPlugin(name, registration.entry, loaded.description, {
+            toolbox: loaded.toolbox,
+            ...(registration.managedBy ? { managedBy: registration.managedBy } : {}),
+        });
+        return findPluginRegistration(name);
+    })();
+    registrationRefreshes.set(key, refresh);
+    try {
+        return await refresh;
+    }
+    finally {
+        registrationRefreshes.delete(key);
+    }
+}
 /** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
 export async function loadPlugin(entry, context, pluginName) {
     let entryVersion;
     try {
-        const stat = statSync(entry);
-        if (!stat.isFile())
-            throw new Error('not a file');
-        entryVersion = `${stat.mtimeMs}-${stat.size}`;
+        entryVersion = pluginFileVersion(entry);
     }
     catch {
         throw new PluginError('PLUGIN_ENTRY_MISSING', missingPluginEntryMessage(entry, pluginName));
@@ -87,11 +135,15 @@ export async function loadPlugin(entry, context, pluginName) {
     let toolbox;
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
-        command(signature, handler, description = '') {
+        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') {
+            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);
@@ -104,7 +156,7 @@ export async function loadPlugin(entry, context, pluginName) {
             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 });
+            commands.set(name, { command, signature, handler, examples: [...examples] });
         },
         invoke(action, payload = {}, options = {}) {
             if (!executing)
@@ -175,20 +227,13 @@ export async function loadPlugin(entry, context, pluginName) {
         },
         help(namespace, name) {
             const selected = name ? [find(name)] : [...commands.values()];
-            const example = selected[0].command;
-            const input = Object.fromEntries(example.registeredArguments.map(argument => [
-                argument.name(),
-                argument.variadic ? [`<${argument.name()}>`] : `<${argument.name()}>`,
-            ]));
+            const examples = selected.flatMap(({ examples }) => examples);
             return [
+                '用法：',
                 ...selected.map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`),
-                '',
-                `  ${namespace} --payload '${JSON.stringify({ command: example.name(), input })}'`,
-                '',
-                '常用选项: --browser --timeout --compact --output',
-                '连接或传输排障运行 mearl check --help。',
-                '插件选项: --name=value 传入字符串业务字段；--all 传入 all=true；--verbose; -h, --help; -v, --version',
-                '同名宿主选项及非字符串字段使用 --payload；业务字段与校验规则见对应 skill。',
+                ...(examples.length
+                    ? ['', '示例：', ...examples.map(example => `  ${namespace} ${example}`)]
+                    : []),
             ].join('\n');
         },
         async run(positionals, payload, namedInput = {}) {

package/dist/pluginPageBundle.d.ts

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

package/dist/pluginPageBundle.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { pluginFileVersion } from './pluginSource.js';
 export const PLUGIN_PAGE_CHUNK_BYTES = 384 * 1024;
 const MAX_PAGE_SOURCE_BYTES = 16 * 1024 * 1024;
 const MAX_PAGE_BUNDLE_BYTES = 24 * 1024 * 1024;
@@ -31,6 +32,40 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   let resolveReady;
   const ready = new Promise(resolve => { resolveReady = resolve; });
 
+  let pageModalOpen = null;
+  let modalRestoreFrame = null;
+  const syncPageModal = () => {
+    if (!port) return;
+    const open = Boolean(document.querySelector?.('dialog:modal'));
+    if (open && modalRestoreFrame !== null) {
+      cancelAnimationFrame(modalRestoreFrame);
+      modalRestoreFrame = null;
+    }
+    if (open === pageModalOpen) return;
+    if (!open && pageModalOpen === true) {
+      if (modalRestoreFrame !== null) return;
+      // Closing a dialog restores focus and can scroll the anchors before the next paint.
+      modalRestoreFrame = requestAnimationFrame(() => {
+        modalRestoreFrame = null;
+        if (document.querySelector?.('dialog:modal')) return;
+        const positions = [];
+        for (const { presentation } of inlineAgentPanels.values()) {
+          if (!presentation.element.isConnected) continue;
+          const rect = presentation.element.getBoundingClientRect();
+          if (![rect.top, rect.left, rect.width, rect.height].every(Number.isFinite)) continue;
+          const bounds = { top: rect.top, left: rect.left, width: rect.width, height: rect.height };
+          presentation.bounds = bounds;
+          positions.push({ key: presentation.key, bounds });
+        }
+        pageModalOpen = false;
+        port.postMessage({ type: 'page-modal', open: false, positions });
+      });
+      return;
+    }
+    pageModalOpen = open;
+    port.postMessage({ type: 'page-modal', open });
+  };
+
   const requestHost = async (type, payload = {}) => {
     await ready;
     const requestId = String(++requestSequence);
@@ -468,6 +503,19 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     port.start();
     resolveReady(context);
     port.postMessage({ type: 'ready' });
+    // Dialogs in the sandbox cannot cover Agent overlays in the parent document.
+    syncPageModal();
+    const modalObserver = typeof MutationObserver === 'function'
+      ? new MutationObserver(syncPageModal)
+      : null;
+    modalObserver?.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['open'],
+      childList: true,
+      subtree: true,
+    });
+    document.addEventListener('toggle', syncPageModal, true);
+    document.addEventListener('close', syncPageModal, true);
   };
   window.addEventListener('message', connect);
   window.parent.postMessage({ type: 'mearl-plugin-ready' }, '*');
@@ -578,6 +626,7 @@ export function buildPluginPageBundle(entry, pageEntry) {
     const root = realpathSync(pluginRoot(entry));
     let sourceBytes = 0;
     const countedFiles = new Set();
+    const sources = {};
     const resolveLocalFile = (reference, fromFile) => {
         const cleanReference = reference.trim().split(/[?#]/, 1)[0];
         if (!cleanReference || isEmbeddedReference(cleanReference))
@@ -585,14 +634,17 @@ export function buildPluginPageBundle(entry, pageEntry) {
         if (isRemoteReference(cleanReference) || isAbsolute(cleanReference)) {
             throw new Error(`toolbox.page 不允许远程或绝对资源: ${reference}`);
         }
-        const resolved = realpathSync(resolve(dirname(fromFile), cleanReference));
+        const sourcePath = resolve(dirname(fromFile), cleanReference);
+        const resolved = realpathSync(sourcePath);
         const relativePath = relative(root, resolved);
         if (relativePath === '..' || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
             throw new Error(`toolbox.page 资源超出插件目录: ${reference}`);
         }
+        sources[sourcePath] = pluginFileVersion(sourcePath);
         return resolved;
     };
     const readAsset = (path) => {
+        sources[path] ??= pluginFileVersion(path);
         const content = readFileSync(path);
         if (!countedFiles.has(path)) {
             countedFiles.add(path);
@@ -676,5 +728,6 @@ export function buildPluginPageBundle(entry, pageEntry) {
         hash: createHash('sha256').update(buffer).digest('hex'),
         size: buffer.byteLength,
         chunks: Math.ceil(buffer.byteLength / PLUGIN_PAGE_CHUNK_BYTES),
+        sources,
     };
 }

package/dist/pluginRegistry.d.ts

@@ -37,7 +37,12 @@ export interface PluginRegistration {
     managedBy?: string;
     toolbox?: PluginToolboxContribution;
     pageBundle?: PluginPageBundleRegistration;
+    source?: {
+        entry: string;
+        page?: Record<string, string>;
+    };
 }
+export declare function pluginRegistrationNeedsRefresh(registration: PluginRegistration, includePage?: boolean): boolean;
 export interface PluginRegistrationOptions {
     managedBy?: string;
     toolbox?: PluginToolboxContribution;