@mearl/client 2.14.0 → 2.15.0

package/dist/plugin.d.ts

@@ -1,18 +1,42 @@
+import { type BucApi } from './buc.js';
 import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, } from './pluginRegistry.js';
+export { type BucApi, type BucIdentity, type BucProfile, type BucRequestAuth, type BucRequestFormValue, type BucRequestParams, type BucRequestResult, } from './buc.js';
+export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, type PluginRegistrationOptions, } from './pluginRegistry.js';
 export type PluginOptions = UnifiedInvokeOptions;
+export interface PluginInvocation {
+    command: string;
+    input: Record<string, any>;
+}
+export interface PluginInvokeOptions extends UnifiedInvokeOptions {
+    onProgress?: (message: string) => void;
+}
+export interface PluginExecutionContext {
+    buc?: BucApi;
+    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+}
 export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
+    readonly buc: BucApi;
     command(signature: string, handler: PluginHandler, description?: string): void;
     invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
     progress(message: string): void;
 }
 export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
 /** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
-export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
+export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'> & {
+    buc?: BucApi;
+}, pluginName?: string): Promise<{
+    name: string | undefined;
+    description: string | undefined;
+    version: string | undefined;
+    help(namespace: string, name?: string): string;
+    run(positionals: string[], payload?: unknown): Promise<unknown>;
+}>;
+export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
     name: string | undefined;
     description: string | undefined;
     version: string | undefined;
     help(namespace: string, name?: string): string;
     run(positionals: string[], payload?: unknown): Promise<unknown>;
 }>;
+export declare function invokeRegisteredPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;

package/dist/plugin.js

@@ -2,7 +2,8 @@ import { readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
-import { PluginError } from './pluginRegistry.js';
+import { buc } from './buc.js';
+import { findPluginRegistration, PluginError } from './pluginRegistry.js';
 export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
 function readPluginVersion(entry) {
     try {
@@ -31,9 +32,12 @@ function missingPluginEntryMessage(entry, pluginName) {
 }
 /** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
 export async function loadPlugin(entry, context, pluginName) {
+    let entryVersion;
     try {
-        if (!statSync(entry).isFile())
+        const stat = statSync(entry);
+        if (!stat.isFile())
             throw new Error('not a file');
+        entryVersion = `${stat.mtimeMs}-${stat.size}`;
     }
     catch {
         throw new PluginError('PLUGIN_ENTRY_MISSING', missingPluginEntryMessage(entry, pluginName));
@@ -45,6 +49,23 @@ export async function loadPlugin(entry, context, pluginName) {
     let description;
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
+        buc: Object.freeze({
+            request(params) {
+                if (!executing)
+                    throw new Error('app.buc.request 只能在命令执行期间调用');
+                return (context.buc ?? buc).request(params);
+            },
+            whoami() {
+                if (!executing)
+                    throw new Error('app.buc.whoami 只能在命令执行期间调用');
+                return (context.buc ?? buc).whoami();
+            },
+            profile() {
+                if (!executing)
+                    throw new Error('app.buc.profile 只能在命令执行期间调用');
+                return (context.buc ?? buc).profile();
+            },
+        }),
         command(signature, handler, description = '') {
             if (!registering)
                 throw new Error('命令只能在入口注册阶段声明');
@@ -78,7 +99,9 @@ export async function loadPlugin(entry, context, pluginName) {
         },
     });
     try {
-        const module = await import(pathToFileURL(entry).href);
+        const moduleUrl = pathToFileURL(entry);
+        moduleUrl.searchParams.set('mearl-version', entryVersion);
+        const module = await import(moduleUrl.href);
         if (module.name !== undefined && typeof module.name !== 'string')
             throw new Error('入口的 name 导出必须为字符串');
         name = module.name;
@@ -171,3 +194,29 @@ export async function loadPlugin(entry, context, pluginName) {
         },
     };
 }
+export async function loadRegisteredPlugin(name, context, options = {}) {
+    const registration = findPluginRegistration(name);
+    if (!registration) {
+        throw new PluginError('PLUGIN_NOT_REGISTERED', `插件未注册: ${name}`);
+    }
+    const { onProgress, ...invokeOptions } = options;
+    return loadPlugin(registration.entry, {
+        options: invokeOptions,
+        ...(context.buc ? { buc: context.buc } : {}),
+        progress: onProgress ?? (() => undefined),
+        async invoke(action, payload, overrides) {
+            const result = await context.invoke(action, payload, {
+                ...invokeOptions,
+                ...overrides,
+            });
+            if (result?.action?.success === false) {
+                throw new Error(result.action.error || `${action} failed`);
+            }
+            return result;
+        },
+    }, name);
+}
+export async function invokeRegisteredPlugin(name, invocation, context, options = {}) {
+    const plugin = await loadRegisteredPlugin(name, context, options);
+    return plugin.run([], invocation);
+}

package/dist/pluginRegistry.d.ts

@@ -5,11 +5,15 @@ export declare class PluginError extends Error {
 export interface PluginRegistration {
     entry: string;
     description?: string;
+    managedBy?: string;
+}
+export interface PluginRegistrationOptions {
+    managedBy?: string;
 }
 export declare function pluginDirectory(): string;
 export declare function assertPluginName(name: string): void;
 export declare function resolvePluginEntry(target: string): string;
-export declare function registerPlugin(name: string, target: string, description?: string): string;
+export declare function registerPlugin(name: string, target: string, description?: string, options?: PluginRegistrationOptions): string;
 export declare function unregisterPlugin(name: string): boolean;
 export declare function findPluginRegistration(name: string): PluginRegistration | undefined;
 export declare function findPluginEntry(name: string): string | undefined;

package/dist/pluginRegistry.js

@@ -40,7 +40,7 @@ export function resolvePluginEntry(target) {
         throw new PluginError('PLUGIN_ENTRY_MISSING', `入口不存在: ${absolute}（目录默认使用 scripts/main.mjs）`);
     }
 }
-export function registerPlugin(name, target, description) {
+export function registerPlugin(name, target, description, options = {}) {
     assertPluginName(name);
     const entry = resolvePluginEntry(target);
     const directory = pluginDirectory();
@@ -49,7 +49,12 @@ export function registerPlugin(name, target, description) {
     // 每个插件独立保存，多个名称并发注册不会覆盖彼此；同名注册原子替换绑定。
     const temporary = `${file}.${randomUUID()}.tmp`;
     const summary = description?.trim();
-    const record = { entry, ...(summary ? { description: summary } : {}) };
+    const managedBy = options.managedBy?.trim();
+    const record = {
+        entry,
+        ...(summary ? { description: summary } : {}),
+        ...(managedBy ? { managedBy } : {}),
+    };
     try {
         writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600, flag: 'wx' });
         renameSync(temporary, file);
@@ -92,7 +97,14 @@ export function findPluginRegistration(name) {
         const description = typeof record.description === 'string' && record.description.trim()
             ? record.description.trim()
             : undefined;
-        return { entry: record.entry, ...(description ? { description } : {}) };
+        const managedBy = typeof record.managedBy === 'string' && record.managedBy.trim()
+            ? record.managedBy.trim()
+            : undefined;
+        return {
+            entry: record.entry,
+            ...(description ? { description } : {}),
+            ...(managedBy ? { managedBy } : {}),
+        };
     }
     catch {
         throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);

package/dist/unified.d.ts

@@ -1,4 +1,5 @@
 import { type CloudConnectorListResult } from '@mearl/cloud-types';
+import type { PluginInvocation, PluginInvokeOptions } from './plugin.js';
 export interface UnifiedInvokeOptions {
     timeoutSec?: number;
     /** Global browser id, source-local browser id, or unique browser name. */
@@ -36,6 +37,7 @@ export declare class UnifiedClient {
     private closing;
     constructor(options?: UnifiedClientOptions);
     disconnect(): void;
+    invokePlugin(name: string, invocation: PluginInvocation, options?: PluginInvokeOptions): Promise<unknown>;
     invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
     private invokeExplicitLocal;
     private invokeLaunchWithoutControlBrowser;
@@ -61,5 +63,6 @@ export declare class UnifiedClient {
     private rejectAllPending;
 }
 export declare function invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+export declare function invokePlugin(name: string, invocation: PluginInvocation, options?: PluginInvokeOptions): Promise<unknown>;
 export declare function listCloudConnectors(): Promise<CloudConnectorListResult>;
 export {};

package/dist/unified.js

@@ -13,8 +13,10 @@ function encodeBrowserTarget(target) {
 }
 function omitTransientBrowserSecrets(browser) {
     const safeBrowser = { ...browser };
-    delete safeBrowser.agentbayAccessUrl;
-    delete safeBrowser.accessUrl;
+    for (const key of Object.keys(safeBrowser)) {
+        if (/accessUrl$/i.test(key))
+            delete safeBrowser[key];
+    }
     return safeBrowser;
 }
 export function decodeBrowserTarget(selector) {
@@ -117,6 +119,12 @@ export class UnifiedClient {
         this.ws?.close();
         this.ws = null;
     }
+    async invokePlugin(name, invocation, options = {}) {
+        const { invokeRegisteredPlugin } = await import('./plugin.js');
+        return invokeRegisteredPlugin(name, invocation, {
+            invoke: (action, payload, invokeOptions) => this.invoke(action, payload, invokeOptions),
+        }, options);
+    }
     async invoke(action, data = {}, options = {}) {
         const timeoutSec = options.timeoutSec ?? resolveActionTimeoutSec(action, data, this.options.requestTimeoutSec);
         if (action === 'connector_list')
@@ -569,6 +577,20 @@ export async function invoke(action, data = {}, options = {}) {
         client.disconnect();
     }
 }
+export async function invokePlugin(name, invocation, options = {}) {
+    const serverUrl = process.env.MEARL_SERVER_URL ?? loadCloudServerConfig()?.server;
+    const client = new UnifiedClient({
+        ...(serverUrl ? { serverUrl } : {}),
+        defaultBrowser,
+        defaultConnector,
+    });
+    try {
+        return await client.invokePlugin(name, invocation, options);
+    }
+    finally {
+        client.disconnect();
+    }
+}
 export function listCloudConnectors() {
     return invoke('connector_list', {});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "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.14.0",
-    "@mearl/provider": "2.14.0"
+    "@mearl/cloud-types": "2.15.0",
+    "@mearl/provider": "2.15.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",