@mearl/client 3.0.0-beta.5 → 3.0.0-beta.8

package/dist/guides/troubleshooting.md

@@ -0,0 +1,170 @@
+# Mearl 环境安装与连接排查
+
+## 目录
+
+- [环境安装、更新与卸载](#environment-management)
+- [本机控制](#local)
+  - [浏览器扩展安装](#local-extension)
+  - [命令不可用或连接失败](#local-check)
+  - [EACCES](#eacces)
+  - [ENOENT](#enoent)
+  - [ECONNREFUSED / 连接关闭](#econnrefused)
+- [远程控制](#cloud)
+  - [Agent（控制端）](#cloud-agent)
+  - [浏览器端](#cloud-browser)
+  - [远程控制常见问题](#cloud-issues)
+- [通用问题](#common)
+  - [请求超时](#timeout)
+
+按 Agent 与浏览器所在机器选择排障流程；命令参数读取对应 CLI 的 `--help`，失败时优先按错误或 `check` 输出的提示处理。
+
+- **本机控制**：Agent 与浏览器在同一台机器，`@mearl/client` 通过 native host socket 通信。
+- **远程控制**：Agent 与浏览器不在同一台机器，`@mearl/client` 通过 cloud-server + cloud-connector 中转。
+
+<a id="environment-management"></a>
+
+## 环境安装、更新与卸载
+
+CLI、Native Host、MCP 和云端核心运行包要求 Node.js >= 20.18.0。安装前用 `node --version` 确认版本；
+不满足时先升级 Node。3.0 beta 使用 `npx @mearl/setup@beta --yes`，保留显式的 `@beta` 标签。
+出现 `Unknown operation: plugin` 时，用 `npx @mearl/setup@beta --version` 核对安装器版本；
+未指定版本时，npm 可能因 Node 不兼容而选择历史版本。
+
+环境管理使用 `npx @mearl/setup@beta <install|update|uninstall>`，具体选项按子命令 `--help` 查询。Agent 执行 install/uninstall 时附加 `--yes` 或 `--non-interactive`，避免等待交互；人工终端可保留交互选择。
+
+主动安装或更新本机环境时，setup 优先使用显式 `--preset <清单 URL 或路径>`，否则保留本机已选 preset；本机未选择时，在运行时初始化后、安装任何 Skill 前检查已连接扩展的受信 preset 并补齐本机组件。首次连接最多等待约一分钟。多个浏览器选择不同、来源不受信或状态不可读时会停止并提示显式选择，不猜测。浏览器未连接时仅安装基础环境，连接后重跑 setup 即可；普通连接和后台自动更新不触发首次本机 preset 安装。
+
+卸载只在用户明确要求一并移除全部 CLI 插件和浏览器 Provider 时传 `--full`；该选项不删除 Chrome 扩展。正常浏览器任务不主动安装或重新初始化，下方排障只在连接失败后使用。
+
+---
+
+<a id="local"></a>
+
+## 本机控制
+
+<a id="local-extension"></a>
+
+### 浏览器扩展安装
+
+优先安装 [Chrome 商店版](https://chromewebstore.google.com/detail/mearl/aoehhjnofngknnjefamjbplchbolghkm)，由 Chrome 管理更新。商店不可用或用户明确要求 setup 托管时，执行：
+
+```bash
+npx @mearl/setup@beta extension --full --yes
+```
+
+该命令同时准备本地环境。人工在终端执行时可省略 `--yes`。
+
+<a id="local-check"></a>
+
+### 命令不可用或连接失败
+
+`mearl` 或 `mearl-native-host` 命令不存在时，在浏览器所在机器安装：
+
+```bash
+npx @mearl/setup@beta --local --yes
+```
+
+命令存在但连接失败时，先检查当前链路：
+
+```bash
+mearl check
+```
+
+只需隔离检查当前机器时使用 `mearl check --local`；路由参数与配置优先级见 `mearl check --help`。只有检查结果表明本地组件缺失、过期或初始化不完整时，才更新并重新初始化：
+
+```bash
+npx @mearl/setup@beta update --local --yes
+```
+
+<a id="eacces"></a>
+
+### EACCES（权限不足）
+
+仅当 native host 初始化写入系统目录时权限不足，才在浏览器所在机器执行：
+
+```bash
+sudo mearl-native-host --init
+```
+
+Socket 访问被 Agent 沙箱拒绝时，按错误提示配置访问权限，不通过 sudo 或改写 Socket 权限绕过。
+
+<a id="enoent"></a>
+
+### ENOENT（找不到 Socket）
+
+client 会自动拉起 native host 并重试。自动恢复失败时按错误提示检查本机链路；手工启动或开发版扩展初始化的参数见 `mearl-native-host --help`，不要用 `nohup` 手工保活 daemon。
+
+如果重试后仍然失败，可按以下步骤排查：
+
+**使用浏览器插件模式：**
+
+确认 Chrome 已打开并等待扩展建联；仍失败时打开 DevTools 的 Mearl 面板触发连接。开发版扩展使用其实际扩展 ID 初始化 native host，再重新执行命令。
+
+**使用 CDP 模式：**
+
+按 `mearl-native-host --help` 或连接错误提示在 Chrome 开启调试并允许授权，确认有普通网页已打开后重试。默认在 Extension 不可用时回退 CDP；需要单独验证 CDP 链路时使用 `mearl check --cdp`。
+
+<a id="econnrefused"></a>
+
+### ECONNREFUSED / 连接关闭
+
+client 会处理当前用户的 stale socket 并尝试恢复 native host；恢复失败时运行 `mearl check --local`，按诊断处理，避免盲目删除 Socket 或重复初始化。
+
+---
+
+<a id="cloud"></a>
+
+## 远程控制
+
+远程控制需要在 **Agent（控制端）** 和 **浏览器端** 两端分别准备。
+
+<a id="cloud-agent"></a>
+
+### Agent（控制端）
+
+1. 安装 cloud-server、统一 client 与当前 Agent 的全局 mearl skill：
+
+   ```bash
+   npx @mearl/setup@beta --cloud --yes
+   ```
+
+   setup 会启动 cloud-server 并输出连接命令。把输出的完整命令交给用户在浏览器所在机器执行，不自行拼接地址或 token。
+
+2. 再次获取连接命令使用 `mearl-cloud-server status`；管理与日志命令见 `mearl-cloud-server --help`。
+
+3. client 自动读取连接配置。用户完成本地连接后，在 Agent 侧验证：
+
+   ```bash
+   mearl check
+   ```
+
+   按诊断定位故障所在机器，再在对应机器修复。默认不逐次传 Server 地址；覆盖参数、配置优先级和检查范围见 `mearl check --help`。连接 URL 可能包含 token，不写入日志或转发给无关方。
+
+<a id="cloud-browser"></a>
+
+### 浏览器端
+
+1. 执行 Agent 侧输出的完整连接命令，把浏览器接入远程控制链路。
+
+2. 浏览器端仍需满足 [本机控制](#local) 的前置条件（native host 已初始化、浏览器插件或 CDP 已建联），否则 connector 无法连到本地 socket。相关报错（EACCES / ENOENT / ECONNREFUSED）参考上文本机排查步骤。
+
+<a id="cloud-issues"></a>
+
+### 远程控制常见问题
+
+- **Agent 侧无法连接 Server**：运行 `mearl check`，按失败项的提示处理。
+- **需要确认动作会落到哪台机器**：运行 `mearl browser_list`，首次操作传返回的全局 `--browser <browserId>`；控制会话建立后由 `--session <sessionId>` 固定目标，无会话时继续传选定的 `--browser`。需要限制到某台远端机器时，从 `source` 获取 ID 或名称并传 `--connector <id|name>`。
+- **connector 连不上或一直重连**：在浏览器端运行 `mearl-cloud-connector status`，按状态和错误提示处理。
+- **connector 已接入但浏览器不可用或请求无响应**：在浏览器端运行 `mearl check --local`；需要检查 connector 版本与心跳时，Agent 端使用 `mearl connector_list`，字段见该命令 `--help`。
+
+### 可选云连接协议
+
+Qoder Cloud Agent 需要在浏览器机器先安装 `@mearl/plugin-qoder` 能力，再按该包 README 和 `docs/cloud-pairing.md` 生成配对信息、配置自定义工具。普通远端 Agent 使用上述 WebSocket 模式。核心未安装对应协议时会报告能力缺失，不会自动安装或读取该协议的凭据。
+
+### 请求超时
+
+超时可能发生在连接、动作执行或结果回传阶段，不能据此判断动作未执行。
+
+- 连接超时：使用 `mearl check` 定位链路故障。
+- 点击、提交、上传或写入超时：先读取当前页面或业务状态确认结果，再决定是否重试，避免重复副作用。
+- 只读查询超时：按 CLI 提示缩小查询范围、裁剪结果或增加 `--timeout`；默认时间按 action 推导，不统一设为 30 秒。

package/dist/index.d.ts

@@ -13,7 +13,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 './plugins/sdk/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 '@mearl/browser-core';
-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 '@mearl/browser-core';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserListParams, 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, RequestPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestBinaryBody, SendRequestFormValue, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from '@mearl/browser-core';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from '@mearl/browser-core';
 export declare function tabCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
@@ -25,8 +25,8 @@ export declare function getEvents(params: Protocol.GetEventsParams, options?: Un
 export declare function setMock(params: Protocol.SetMockParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_mock'>>;
 export declare function getMocks(params: Protocol.GetMocksParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_mocks'>>;
 export declare function sendRequest(params: Protocol.SendRequestParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'send_request'>>;
-export declare function sendMtopRequest(params: Protocol.SendMtopRequestParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'send_mtop_request'>>;
 export declare function browserList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_list'>>;
+export declare function browserList(params: Protocol.BrowserListParams, 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'>>;

package/dist/index.js

@@ -36,11 +36,10 @@ export function getMocks(params, options) {
 export function sendRequest(params, options) {
     return invoke('send_request', params, options);
 }
-export function sendMtopRequest(params, options) {
-    return invoke('send_mtop_request', params, options);
-}
-export function browserList(options) {
-    return invoke('browser_list', {}, options);
+export function browserList(paramsOrOptions = {}, options) {
+    return 'provider' in paramsOrOptions || 'launchForm' in paramsOrOptions
+        ? invoke('browser_list', paramsOrOptions, options)
+        : invoke('browser_list', {}, paramsOrOptions);
 }
 export function selectBrowser(params = {}, options) {
     return invoke('browser_select_browser', params, options);

package/dist/plugins/officialPluginInstaller.js

@@ -2,6 +2,7 @@ import { closeSync, mkdirSync, openSync, rmSync, statSync, writeFileSync } from
 import { CLIENT_VERSION } from '../runtimePaths.js';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
+import { npmExecEnvironment } from '@mearl/daemon-core';
 import { findOfficialPlugin, readOfficialPluginCatalog } from './officialPluginCatalog.js';
 import { findPluginRegistration, pluginDirectory } from './pluginRegistry.js';
 const INSTALL_TIMEOUT_MS = 180_000;
@@ -60,7 +61,7 @@ function appendOutput(current, chunk) {
 function installWithSetup(name) {
     return new Promise((resolve, reject) => {
         const command = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-        const child = spawn(command, ['-y', '--@mearl:registry=https://registry.npmjs.org', `@mearl/setup@${CLIENT_VERSION}`, 'plugin', 'ensure', name], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        const child = spawn(command, ['-y', '--@mearl:registry=https://registry.npmjs.org', `@mearl/setup@${CLIENT_VERSION}`, 'plugin', 'ensure', name], { env: npmExecEnvironment(), stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
         let stdout = '';
         let stderr = '';
         let settled = false;

package/dist/plugins/pluginRegistry.js

@@ -8,6 +8,7 @@ import { COMMAND_MAP } from '../commands.js';
 import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, PLUGIN_PAGE_RUNTIME_HASH, } from './pluginPageBundle.js';
 import { pluginFileVersion } from './pluginSource.js';
 const RESERVED_NAMES = new Set([
+    'guide',
     'check',
     'run',
     'help',
@@ -15,6 +16,11 @@ const RESERVED_NAMES = new Set([
     'capture_checkpoint',
     'plugin',
     'plugins',
+    'plugin_state',
+    'plugin_model',
+    'plugin_page',
+    'plugin_invoke_child',
+    'plugin_task_checkpoint',
 ]);
 export class PluginError extends Error {
     code;
@@ -111,7 +117,7 @@ function persistPluginPageBundle(name, bundle) {
     }
 }
 export function assertPluginName(name) {
-    if (!/^[a-z][a-z0-9-]*$/.test(name) || RESERVED_NAMES.has(name) || COMMAND_MAP.has(name)) {
+    if (!/^[a-z][a-z0-9_-]*$/.test(name) || RESERVED_NAMES.has(name) || COMMAND_MAP.has(name)) {
         throw new PluginError('PLUGIN_INVALID_NAME', `不可用的插件名称: ${name}`);
     }
 }
@@ -346,7 +352,7 @@ export function unregisterPlugin(name) {
     }
 }
 export function findPluginRegistration(name) {
-    if (!/^[a-z][a-z0-9-]*$/.test(name))
+    if (!/^[a-z][a-z0-9_-]*$/.test(name))
         return undefined;
     const file = join(pluginDirectory(), `${name}.json`);
     let content;
@@ -470,7 +476,7 @@ export function findPluginEntry(name) {
 export function listPluginNames() {
     try {
         return readdirSync(pluginDirectory())
-            .filter(file => /^[a-z][a-z0-9-]*\.json$/.test(file))
+            .filter(file => /^[a-z][a-z0-9_-]*\.json$/.test(file))
             .map(file => file.slice(0, -5))
             .sort();
     }

package/dist/plugins/runtime/pluginDiagnostics.js

@@ -26,7 +26,7 @@ export function normalizeDiagnosticOptions(value) {
         throw new Error('Invalid diagnostic instance ID');
     if (input.plugin !== undefined &&
         (typeof input.plugin !== 'string' ||
-            !/^[a-z][a-z0-9-]*$/.test(input.plugin) ||
+            !/^[a-z][a-z0-9_-]*$/.test(input.plugin) ||
             input.plugin.length > 128))
         throw new Error('Invalid diagnostic plugin');
     for (const key of ['includeErrorMessages', 'includeLocalPaths'])

package/dist/plugins/runtime/pluginHostServer.js

@@ -91,7 +91,7 @@ export async function startPluginHostServer(configuration = {}) {
                     !['service', 'caller'].includes(String(input.bridge)) ||
                     !['cli', 'sdk', 'mcp', 'toolbox', 'runtime'].includes(String(input.source)) ||
                     (input.plugin !== undefined &&
-                        (typeof input.plugin !== 'string' || !/^[a-z][a-z0-9-]*$/.test(input.plugin))) ||
+                        (typeof input.plugin !== 'string' || !/^[a-z][a-z0-9_-]*$/.test(input.plugin))) ||
                     (input.scopeId !== undefined &&
                         (typeof input.scopeId !== 'string' || input.scopeId.length > 256)) ||
                     (input.access !== 'public' && (!input.plugin || input.bridge !== 'caller')))

package/dist/plugins/runtime/pluginPageManager.js

@@ -272,7 +272,7 @@ export class PluginPageManager {
         execution.signal?.throwIfAborted();
         if (!input || typeof input !== 'object' || Array.isArray(input))
             throw new Error('Invalid plugin page request');
-        if (!/^[a-z][a-z0-9-]*$/.test(plugin) ||
+        if (!/^[a-z][a-z0-9_-]*$/.test(plugin) ||
             (bridge.scope.plugin && bridge.scope.plugin !== plugin))
             throw new Error('Invalid plugin page scope');
         const operation = input.operation;
@@ -656,7 +656,7 @@ export class PluginPageManager {
     async receive(plugin, input, bridge, options = {}) {
         if (input.kind === 'sync') {
             if (this.closed ||
-                !/^[a-z][a-z0-9-]*$/.test(plugin) ||
+                !/^[a-z][a-z0-9_-]*$/.test(plugin) ||
                 (bridge.scope.plugin && bridge.scope.plugin !== plugin) ||
                 !Array.isArray(input.instances) ||
                 input.instances.length > 32)

package/dist/plugins/runtime/pluginStateManager.js

@@ -29,7 +29,7 @@ export class PluginStateManager {
     async call(plugin, input, bridge, options = {}, binding) {
         this.controller.signal.throwIfAborted();
         binding?.signal?.throwIfAborted();
-        if (!/^[a-z][a-z0-9-]*$/.test(plugin) ||
+        if (!/^[a-z][a-z0-9_-]*$/.test(plugin) ||
             (bridge.scope.plugin && bridge.scope.plugin !== plugin) ||
             !input ||
             typeof input !== 'object' ||

package/dist/plugins/runtime/pluginTaskManager.js

@@ -205,7 +205,7 @@ export class PluginTaskManager {
                 executionTimeoutMs: request.executionTimeoutMs ?? 120000,
             };
         }
-        if (!/^[a-z][a-z0-9-]*$/.test(request.plugin) || !/^[a-z][a-z0-9-]*$/.test(request.command))
+        if (!/^[a-z][a-z0-9_-]*$/.test(request.plugin) || !/^[a-z][a-z0-9-]*$/.test(request.command))
             throw new Error('Invalid plugin task command');
         if (bridge.scope.plugin && request.plugin !== bridge.scope.plugin)
             throw error('PLUGIN_COMMAND_NOT_ALLOWED', 'Plugin task is outside the caller scope');
@@ -884,7 +884,7 @@ export class PluginTaskManager {
                         });
                     }
                     if (restrictedTarget &&
-                        !['send_request', 'send_mtop_request', 'browser_list', 'connector_list'].includes(action))
+                        !['send_request', 'browser_list', 'connector_list'].includes(action))
                         throw error('PLUGIN_PAGE_TARGET_CHANGED', 'Runtime tasks must access the document through context.page');
                     this.assertRouting(options, request.options);
                     if (client) {

package/dist/plugins/sdk/plugin.d.ts

@@ -72,6 +72,7 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'opti
 }, pluginName?: string): Promise<{
     name: string | undefined;
     description: string | undefined;
+    defaultCommand: string | undefined;
     toolbox: PluginToolboxContribution | undefined;
     pageRuntime: PluginPageRuntime | undefined;
     stateStorage: PluginStateDeclaration | undefined;
@@ -90,6 +91,7 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'opti
 export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
     name: string | undefined;
     description: string | undefined;
+    defaultCommand: string | undefined;
     toolbox: PluginToolboxContribution | undefined;
     pageRuntime: PluginPageRuntime | undefined;
     stateStorage: PluginStateDeclaration | undefined;

package/dist/plugins/sdk/plugin.js

@@ -146,6 +146,7 @@ export async function loadPlugin(entry, context, pluginName) {
     let registering = true;
     let name;
     let description;
+    let defaultCommand;
     let toolbox;
     let pageRuntime;
     let stateStorage;
@@ -312,6 +313,9 @@ export async function loadPlugin(entry, context, pluginName) {
             if (module.description !== undefined && typeof module.description !== 'string')
                 throw new Error('入口的 description 导出必须为字符串');
             description = module.description;
+            if (module.defaultCommand !== undefined && typeof module.defaultCommand !== 'string')
+                throw new Error('入口的 defaultCommand 导出必须为字符串');
+            defaultCommand = module.defaultCommand;
             toolbox = normalizePluginToolboxContribution(module.toolbox);
             pageRuntime = normalizePluginPageRuntime(module.pageRuntime);
             stateStorage = normalizePluginState(module.stateStorage);
@@ -326,6 +330,8 @@ export async function loadPlugin(entry, context, pluginName) {
         }
         if (commands.size === 0 && !appProfiles)
             throw new Error('入口未注册任何命令');
+        if (defaultCommand !== undefined && (!commands.has(defaultCommand) || commands.get(defaultCommand)?.toolboxOnly || commands.get(defaultCommand)?.runtimeOnly))
+            throw new Error('defaultCommand 必须指向公开命令');
         for (const command of Object.keys(taskRecovery?.commands ?? {})) {
             if (!commands.has(command) ||
                 commands.get(command)?.runtimeOnly ||
@@ -401,12 +407,13 @@ export async function loadPlugin(entry, context, pluginName) {
         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))) {
+        const defaultPayload = defaultCommand && toolboxPage === false && isObject(payload) && !Object.hasOwn(payload, 'command');
+        if (payload !== undefined && !defaultPayload && !isPluginInvocation(payload)) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '--payload 必须为 {"command":"...","input":{...}}');
         }
-        const envelope = payload;
-        const commandName = envelope?.command ?? positionals[0] ?? '';
+        const envelope = (defaultPayload ? { command: defaultCommand, input: payload } : payload);
+        const positionalOffset = defaultCommand && !commands.has(positionals[0]) && toolboxPage === false ? 0 : 1;
+        const commandName = envelope?.command ?? (positionalOffset === 0 ? defaultCommand : positionals[0] ?? '');
         const hidden = toolboxPage === 'recovery' || toolboxPage === 'migration';
         const selected = find(commandName, hidden ? false : toolboxPage);
         const command = selected.command;
@@ -426,7 +433,7 @@ export async function loadPlugin(entry, context, pluginName) {
             : Object.fromEntries(command.registeredArguments
                 .map((argument, index) => [
                 argument.name(),
-                argument.variadic ? positionals.slice(index + 1) : positionals[index + 1],
+                argument.variadic ? positionals.slice(index + positionalOffset) : positionals[index + positionalOffset],
             ])
                 .filter(([, value]) => value !== undefined));
         for (const name of Object.keys(namedInput)) {
@@ -437,7 +444,7 @@ export async function loadPlugin(entry, context, pluginName) {
         const input = { ...positionalInput, ...namedInput };
         if (!envelope &&
             !command.registeredArguments.some(argument => argument.variadic) &&
-            positionals.length - 1 > command.registeredArguments.length) {
+            positionals.length - positionalOffset > command.registeredArguments.length) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数过多');
         }
         for (const argument of hidden ? [] : command.registeredArguments) {
@@ -529,6 +536,7 @@ export async function loadPlugin(entry, context, pluginName) {
     return {
         name,
         description,
+        defaultCommand,
         toolbox,
         pageRuntime,
         stateStorage,
@@ -538,11 +546,11 @@ export async function loadPlugin(entry, context, pluginName) {
         version: readPluginVersion(entry),
         commandHelp(namespace) {
             return publicCommands()
-                .map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`)
+                .map(({ command, signature }) => `  ${namespace} ${command.name() === defaultCommand ? signature.slice(defaultCommand.length).trim() : signature}  ${command.description()}`)
                 .join('\n');
         },
         help(namespace, name) {
-            const selected = name ? [find(name)] : publicCommands();
+            const selected = name ? [find(defaultCommand && !commands.has(name) ? defaultCommand : name)] : publicCommands();
             if (!selected.length) {
                 const location = toolbox
                     ? `请在 Mearl ${toolbox.displayMode === 'popup' ? 'Popup' : '工具箱'} 中打开「${toolbox.title}」使用。`
@@ -552,7 +560,7 @@ export async function loadPlugin(entry, context, pluginName) {
             const examples = selected.flatMap(({ examples }) => examples);
             return [
                 '用法：',
-                ...selected.map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`),
+                ...selected.map(({ command, signature }) => `  ${namespace} ${command.name() === defaultCommand ? signature.slice(defaultCommand.length).trim() : signature}  ${command.description()}`),
                 ...(examples.length
                     ? ['', '示例：', ...examples.map(example => `  ${namespace} ${example}`)]
                     : []),

package/dist/script.js

@@ -208,7 +208,8 @@ export async function executeScript(code, options = {}) {
                             session: sessionId,
                             ...args[2],
                         });
-                    const optionsOnly = OPTIONS_ONLY.has(method) || (method === 'browserRelease' && args.length < 2);
+                    const optionsOnly = (OPTIONS_ONLY.has(method) && !(method === 'browserList' && args[0] &&
+                        ('provider' in args[0] || 'launchForm' in args[0]))) || (method === 'browserRelease' && args.length < 2);
                     return invoke(METHOD_ACTIONS.get(method), optionsOnly ? {} : (args[0] ?? {}), optionsOnly ? args[0] : args[1]);
                 })
                     .then(result => send({ type: 'response', id, result, session }), error => send({ type: 'response', id, error: serializeError(error), session }))

package/dist/socket.js

@@ -13,13 +13,13 @@ import os from 'node:os';
 import path from 'node:path';
 import { CLIENT_VERSION } from './runtimePaths.js';
 import { StringDecoder } from 'node:string_decoder';
-import { ensureProviderControlHost, listInstalledProviders } from '@mearl/provider/host';
-import { MEARL_PROVIDER_PROTOCOL_VERSION } from '@mearl/provider';
-import { readLiveProvider } from '@mearl/provider/runtime';
+import { assertProviderControlSessionMode, ensureProviderControlHost, listInstalledProviders } from '@mearl/provider/host';
+import { MEARL_PROVIDER_PROTOCOL_VERSION, assertProviderProtocolVersion, validateProviderLaunchForm } from '@mearl/provider';
+import { readLiveProvider, ensureInstalledProvidersRunning } from '@mearl/provider/runtime';
 import { resolveFileRefs } from './fileRefs.js';
 import { listLiveBrowsers, findBrowser, describeBrowser, } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
-import { isBrowserCapabilityAction } from '@mearl/browser-core';
+import { isBrowserCapabilityAction, parseBrowserListParams } from '@mearl/browser-core';
 export { CLIENT_VERSION };
 const MAX_SOCKET_BUFFER_SIZE = 64 * 1024 * 1024;
 /**
@@ -376,6 +376,29 @@ export function invoke(action, data = {}, options = {}) {
     const resolvedData = resolveFileRefs(data);
     Object.defineProperty(resolvedData, SESSION_OPTION, { value: options.controlSessionId });
     if (action === 'browser_list') {
+        const discovery = parseBrowserListParams(resolvedData);
+        if (discovery) {
+            return (async () => {
+                if (transport || options.socketPath || controlSource !== 'local' || options.controlSessionId)
+                    throw new Error('Provider discovery requires the local source without a transport, socket or session override');
+                const provider = listInstalledProviders().find(provider => provider.providerId === discovery.provider);
+                if (!provider?.browserType.dynamicLaunchForm)
+                    throw new Error(`Provider does not support dynamic launch forms: ${discovery.provider}`);
+                const warnings = await ensureInstalledProvidersRunning([discovery.provider]);
+                if (warnings.length)
+                    throw new Error(warnings.join('; '));
+                const live = readLiveProvider(discovery.provider);
+                if (!live)
+                    throw new Error(`Provider did not start: ${discovery.provider}`);
+                assertProviderProtocolVersion(live.providerProtocolVersion, discovery.provider);
+                const form = await invokeOnce('browser_providers', { operation: 'launch_form', ...discovery.launchForm }, timeoutSec, undefined, live.socketPath, 'local');
+                validateProviderLaunchForm(form);
+                return decorateBrowserListResult({
+                    ...browserListFromProviderRecords(listLiveBrowsers().filter(browser => browser.provider?.id === discovery.provider)),
+                    discovery: { provider: discovery.provider, launchForm: form },
+                });
+            })();
+        }
         return dispatchInvoke(action, resolvedData, timeoutSec, transport, undefined, controlSource, options.socketPath).then(result => decorateBrowserListResult(transport === 'cdp' ? cdpOnlyBrowserList(result) : result));
     }
     const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
@@ -510,7 +533,7 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
             throw new Error(`Browser ${describeBrowser(match)} does not support ${action}`);
         }
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource, match.transport === 'provider' ? match.browserId : undefined);
+            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource, match.transport === 'provider' ? match.browserId : undefined, match.capabilities?.controlSessionMode);
         }
         catch (error) {
             if (isConnError(error) || isSocketSandboxError(error)) {
@@ -527,7 +550,7 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     if (candidates.length > 0) {
         const target = candidates[0];
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined);
+            return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined, target.capabilities?.controlSessionMode);
         }
         catch (error) {
             if (isSocketSandboxError(error)) {
@@ -575,7 +598,7 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
                     !(transport === 'cdp' && browser.transport === 'provider') &&
                     supportsAction(browser, action, data));
                 if (target) {
-                    return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined);
+                    return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined, target.capabilities?.controlSessionMode);
                 }
                 return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, 
                 /* isRetry */ true, localOnly);
@@ -586,9 +609,10 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
         throw new Error(formatConnectError(err, SOCKET_PATH), { cause: error });
     }
 }
-async function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource, providerTarget) {
+async function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource, providerTarget, controlSessionMode) {
     if (providerTarget) {
         const host = await ensureProviderControlHost(Math.min(timeoutSec * 1000, 10_000));
+        assertProviderControlSessionMode(host, controlSessionMode);
         socketPath = host.socketPath;
     }
     const id = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;

package/dist/unified.js

@@ -3,7 +3,7 @@ import { stageFile, exportArtifact } from './artifacts.js';
 import WebSocket from 'ws';
 import { DEFAULT_CONNECT_TIMEOUT, DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_REQUEST_TIMEOUT, MAX_BUFFER_SIZE, isHeartbeatMessage, resolveCloudConnectorSelector, } from '@mearl/cloud-types';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
-import { validateRequiredActionTabId, } from '@mearl/browser-core';
+import { validateRequiredActionTabId, parseBrowserListParams, } from '@mearl/browser-core';
 import { invoke as invokeLocalBrowser, resolveLocalActionTarget } from './socket.js';
 import { loadCloudServerConfig, loadLocalConnectorId } from './unifiedConfig.js';
 const RESPONSE_GRACE_MS = 1_000;
@@ -146,6 +146,9 @@ export class UnifiedClient {
         }, options);
     }
     async invoke(action, data = {}, options = {}) {
+        const discovery = action === 'browser_list' ? parseBrowserListParams(data) : undefined;
+        if (discovery && (!options.local || options.connector || options.transport || options.session || options.controlSessionId))
+            throw new Error('Provider discovery requires explicit --local without connector, transport, socket or session overrides');
         if (action === 'plugin_state') {
             const { PluginStateClient } = await import('./plugins/clients/pluginState.js');
             const state = new PluginStateClient();
@@ -350,6 +353,12 @@ export class UnifiedClient {
         if (action === 'connector_list')
             return this.listConnectors(timeoutSec);
         if (action === 'browser_list') {
+            if (parseBrowserListParams(data)) {
+                const result = await invokeLocalBrowser('browser_list', data, { timeoutSec, controlSource: 'local' });
+                if (!result?.discovery)
+                    throw new Error('Provider launch-form discovery is not supported by this host');
+                return this.applyConfiguredDefault(this.decorateListing(result, { kind: 'local' }));
+            }
             if (options.local || options.transport === 'cdp') {
                 return this.listLocalBrowsers(timeoutSec, options.transport);
             }
@@ -543,6 +552,7 @@ export class UnifiedClient {
                 })
                 : null,
             browsers,
+            ...(result?.discovery ? { discovery: result.discovery } : {}),
             ...(resultWarnings.length > 0 ? { warnings: resultWarnings } : {}),
         };
     }

package/dist/unifiedConfig.d.ts

@@ -6,3 +6,7 @@ export declare function loadCliAutoUpdateIntervalDays(configPath?: string): numb
 export declare function getCloudServerConfigPath(): string;
 export declare function loadCloudServerConfig(): CloudServerConfig | null;
 export declare function loadLocalConnectorId(): string | null;
+export declare function resolveServer(explicit?: string): {
+    serverUrl?: string;
+    serverUrlSource?: string;
+};

package/dist/unifiedConfig.js

@@ -56,3 +56,14 @@ export function loadLocalConnectorId() {
         return null;
     }
 }
+export function resolveServer(explicit) {
+    if (explicit)
+        return { serverUrl: explicit, serverUrlSource: '--server' };
+    if (process.env.MEARL_SERVER_URL) {
+        return { serverUrl: process.env.MEARL_SERVER_URL, serverUrlSource: 'MEARL_SERVER_URL' };
+    }
+    const config = loadCloudServerConfig();
+    return config?.server
+        ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
+        : {};
+}