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

package/README.md

@@ -224,8 +224,8 @@ stdout 在管道或重定向时默认输出紧凑 JSON，在交互终端默认
 未指定字段时默认返回正文。
 
 `send_request` 默认携带所选浏览器中匹配完整目标 URL 的普通 Cookie，以及目标 URL 第一方站点对应的 CHIPS Cookie。例如 `https://app.example.com/` 使用 `https://example.com` 分区，不依赖已打开页面。站点按协议和公共后缀列表（含私有后缀）确定；排除其他站点、其他协议、跨站祖先及不透明分区。保留不同路径下的同名 Cookie，不额外拼入父站点的 host-only Cookie。嵌入其他站点的第三方分区、页面签名或完整页面身份仍需使用目标页面中的 `page_eval` 请求。
-响应中的 `Set-Cookie` 会更新原浏览器，后续调用可以使用刷新后的登录态；`withCookies:false` 同时关闭自动携带与响应回写。扩展由 Chrome 处理响应 Cookie；CDP 的 Node 请求在返回前通过原页面的浏览器连接回写，支持 HttpOnly、默认路径、过期时间和删除。CDP 响应存在 `Set-Cookie` 时附带 `cookieSync: { updatedCount, rejectedCount, failedCount }`，不返回 Cookie 值；无法确定分区的 Partitioned 响应 Cookie 计入拒绝数。同步失败不撤销已完成的 HTTP 操作，应检查状态而非直接重发业务请求。MTop 普通请求及流式请求使用相同的响应刷新机制。
-扩展的临时凭据注入仅匹配原始完整请求 URL，重定向由 Chrome 按新 URL 选择 Cookie。CDP 的 Node 请求（含 MTop 流式请求）不自动跟随重定向，避免将原 URL 的 Cookie 或签名传到其他地址。
+响应中的 `Set-Cookie` 会更新原浏览器，后续调用可以使用刷新后的登录态；`withCookies:false` 同时关闭自动携带与响应回写。扩展由 Chrome 处理响应 Cookie；CDP 的 Node 请求在返回前通过原页面的浏览器连接回写，支持 HttpOnly、默认路径、过期时间和删除。CDP 响应存在 `Set-Cookie` 时附带 `cookieSync: { updatedCount, rejectedCount, failedCount }`，不返回 Cookie 值；无法确定分区的 Partitioned 响应 Cookie 计入拒绝数。同步失败不撤销已完成的 HTTP 操作，应检查状态而非直接重发业务请求。Protocol 普通请求及流式请求使用相同的响应刷新机制。
+扩展的临时凭据注入仅匹配原始完整请求 URL，重定向由 Chrome 按新 URL 选择 Cookie。CDP 的 Node 请求（含 Protocol 流式请求）不自动跟随重定向，避免将原 URL 的 Cookie 或签名传到其他地址。
 
 Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通过 `browser_list` 返回的全局
 `browserId` 自动路由。以下覆盖参数仅在限定宿主或连接、传输排障时使用，因此不出现在默认 help：
@@ -267,7 +267,7 @@ client、native-host、cloud-server 和 MCP server 的已安装版本。发现
 安装 skill 并自动注册命令，或直接注册已有入口：
 
 ```bash
-npx @mearl/setup plugin install https://github.com/F-loat/mearl --skill browser-tab-manager --yes
+npx @mearl/setup plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
 npx @mearl/setup plugin /absolute/path/to/browser-tab-manager
 npx @mearl/setup plugin uninstall tabs
 mearl tabs summary
@@ -445,7 +445,7 @@ Node 插件在运行 CLI、SDK 或 MCP Server 的宿主上执行，不随浏览
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | API 调试      | `tab_checkpoint` `get_requests` `get_logs` `get_events`                                                                              |
 | Mock & 规则   | `set_mock` `get_mocks` `set_rule` `get_rules`                                                                                        |
-| 网络请求      | `send_request` `send_mtop_request` `request_domain_permission`                                                                       |
+| 网络请求      | `send_request` `send_protocol_request` `request_permission`                                                                       |
 | 标签页        | `tab_open` `tab_list` `tab_close`                                                                                                    |
 | 页面感知      | `page_snapshot` `page_inspect` `page_screenshot` `page_frames`                                                                       |
 | 页面操作      | `page_click` `page_drag` `page_type` `page_hover` `page_scroll` `page_press` `page_wait` `page_navigate` `page_upload` `page_eval`    |

package/dist/actionTimeouts.js

@@ -26,7 +26,7 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
             : 0;
         return Math.max(fallback, Math.ceil(((data.timeout ?? 30000) + transferTimeoutMs + 5000) / 1000));
     }
-    if (action === 'send_mtop_request') {
+    if (action === 'send_protocol_request') {
         return Math.max(fallback, Math.ceil(((data.timeout ?? 10000) + 5000) / 1000));
     }
     if (action === 'page_download')

package/dist/autoUpdate.js

@@ -4,6 +4,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync,
 import { homedir } from 'node:os';
 import { delimiter, dirname, join, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { npmExecEnvironment } from '@mearl/daemon-core';
 import { isNewerRelease, parseReleaseVersion } from './check.js';
 import { loadCliAutoUpdateIntervalDays } from './unifiedConfig.js';
 const CONFIG_DIR = join(homedir(), '.mearl');
@@ -207,7 +208,7 @@ export function setupUpdateCommand(version, packageRoot, profiles, updateClient)
     if (!parseReleaseVersion(version))
         throw new Error('A valid Mearl release is required');
     const [major, minor] = version.split('.');
-    const env = { ...process.env };
+    const env = npmExecEnvironment();
     delete env.MEARL_AUTO_UPDATE_CLIENT_ROOT;
     delete env.MEARL_AUTO_UPDATE_CLIENT_ONLY;
     delete env.MEARL_AUTO_UPDATE_PROFILES;

package/dist/capabilityHelp.d.ts

@@ -0,0 +1,4 @@
+import type { BrowserCapabilityCatalog } from '@mearl/browser-core';
+/** Help reads an existing target with a short budget; it never installs an environment. */
+export declare function readHelpCapabilities(args: string[]): Promise<BrowserCapabilityCatalog | undefined>;
+export declare function formatCapabilityHelp(catalog: BrowserCapabilityCatalog | undefined, detailed?: boolean): string;

package/dist/capabilityHelp.js

@@ -0,0 +1,69 @@
+import { resolveServer } from './unifiedConfig.js';
+import { listLiveBrowsers } from './browserRegistry.js';
+import { UnifiedClient } from './unified.js';
+/** Help reads an existing target with a short budget; it never installs an environment. */
+export async function readHelpCapabilities(args) {
+    const value = (flag) => {
+        const index = args.indexOf(flag);
+        return index < 0 ? args.find(arg => arg.startsWith(`${flag}=`))?.slice(flag.length + 1) : args[index + 1];
+    };
+    const browser = value('--browser');
+    const session = value('--session');
+    const connector = value('--connector');
+    const { serverUrl } = resolveServer(value('--server'));
+    const local = args.includes('--local') || args.includes('--cdp');
+    if (local && connector || session === 'new')
+        return;
+    if (!browser && !connector && (local || !serverUrl) && !session && !listLiveBrowsers().length)
+        return;
+    const client = new UnifiedClient({ connectTimeoutSec: 1, requestTimeoutSec: 1, ...(serverUrl ? { serverUrl } : {}) });
+    let timer;
+    try {
+        const result = await Promise.race([
+            client.invoke('get_capabilities', {}, {
+                ...(browser ? { browser } : {}), ...(session ? { session } : {}),
+                ...(connector ? { connector } : {}), ...(local ? { local: true } : {}),
+                ...(args.includes('--cdp') ? { transport: 'cdp' } : {}),
+            }),
+            new Promise(resolve => { timer = setTimeout(() => resolve(undefined), 1500); }),
+        ]);
+        if (result && Array.isArray(result.actions) && Array.isArray(result.apps?.entries))
+            return result;
+    }
+    catch {
+        // Static help remains usable when the target is offline or does not expose a catalog.
+    }
+    finally {
+        clearTimeout(timer);
+        client.disconnect();
+    }
+}
+export function formatCapabilityHelp(catalog, detailed = false) {
+    if (!catalog)
+        return '当前浏览器能力暂不可读；以下为静态帮助。连接后再次运行 --help 可查看已安装 App。';
+    const lines = [
+        ...(catalog.actions.includes('send_protocol_request') ? ['已安装的可选协议命令：send_protocol_request（沿用 --payload 参数；--help 查看用法）', ''] : []),
+        '当前浏览器已安装的 App：',
+    ];
+    if (!catalog.apps.entries.length)
+        lines.push(catalog.apps.status === 'available' ? '  暂无 App 档案；设备模拟可独立使用。' : '  App 目录暂不可读，不代表未安装。');
+    for (const app of catalog.apps.entries) {
+        lines.push(`  ${app.id} — ${app.label}${app.available ? '' : '（暂不可用）'}`);
+        if (!detailed)
+            continue;
+        lines.push(`    能力：${app.features.join(', ')}`);
+        if (app.usage?.skills?.length)
+            lines.push(`    Skill：${app.usage.skills.join(', ')}`);
+        if (app.usage?.description)
+            lines.push(`    ${app.usage.description}`);
+        if (app.usage?.limitations?.length)
+            lines.push(...app.usage.limitations.map(line => `    限制：${line}`));
+        if (app.usage?.documentation?.length)
+            lines.push(...app.usage.documentation.map(doc => `    说明：${doc.title} ${doc.url}`));
+    }
+    if (detailed)
+        lines.push(...catalog.limitations.map(line => `  ${line}`));
+    else
+        lines.push('  App 用法与限制：mearl set_app_profile --help');
+    return lines.join('\n');
+}

package/dist/check.js

@@ -4,7 +4,7 @@ const UPDATE_SOURCES = {
     client: 'https://registry.npmjs.org/@mearl%2Fclient/latest',
     'native-host': 'https://registry.npmjs.org/@mearl%2Fnative-host/latest',
     'cloud-connector': 'https://registry.npmjs.org/@mearl%2Fcloud-connector/latest',
-    extension: 'https://github.com/F-loat/mearl/releases/latest/download/config.json',
+    extension: 'https://github.com/mearlhq/mearl/releases/latest/download/config.json',
 };
 export function parseReleaseVersion(value) {
     if (typeof value !== 'string')

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { readHelpCapabilities, formatCapabilityHelp } from './capabilityHelp.js';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { Command, CommanderError } from 'commander';
@@ -10,7 +11,7 @@ import { formatCommandHelp } from './commandHelp.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
 import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugins/sdk/plugin.js';
-import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
+import { resolveServer } from './unifiedConfig.js';
 const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
     {
@@ -20,9 +21,9 @@ const CATEGORIES = [
     { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
     {
         title: '网络请求',
-        names: ['send_request', 'send_mtop_request', 'request_domain_permission'],
+        names: ['send_request', 'request_permission'],
     },
-    { title: '标签页', names: ['tab_open', 'tab_list', 'tab_group', 'tab_close', 'get_capabilities'] },
+    { title: '标签页', names: ['tab_open', 'tab_list', 'tab_group', 'tab_close'] },
     {
         title: '页面感知',
         names: ['page_snapshot', 'page_inspect', 'page_screenshot', 'page_frames'],
@@ -351,17 +352,6 @@ function parsePayload(payloadRaw, payloadFile) {
     }
     return {};
 }
-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() }
-        : {};
-}
 function normalizeScreenshotOutput(action, payload, explicitOutput) {
     if (action !== 'page_screenshot' || !Object.hasOwn(payload, 'output')) {
         return { payload, ...(explicitOutput ? { outputPath: explicitOutput } : {}) };
@@ -612,8 +602,11 @@ export async function runMearlCli(args, options = {}) {
     }
     if (args.includes('--help') || args.includes('-h')) {
         const command = COMMAND_MAP.get(args[0]);
-        if (command)
+        if (command) {
             console.error(formatCommandHelp(commandName, command));
+            if (command.name === 'set_app_profile' || command.name === 'tab_open')
+                console.error(formatCapabilityHelp(await readHelpCapabilities(args), true));
+        }
         else if (args[0] === 'check')
             printCheckHelp(commandName);
         else if (ADVANCED_BUILTIN_COMMANDS.has(args[0])) {
@@ -621,6 +614,7 @@ export async function runMearlCli(args, options = {}) {
         }
         else if (args[0]?.startsWith('-')) {
             printUsage(commandName, clientVersion);
+            console.error(formatCapabilityHelp(await readHelpCapabilities(args)));
         }
         else {
             printUnknownCommand(commandName, args);

package/dist/commandHelp.js

@@ -39,10 +39,10 @@ export function formatCommandHelp(commandName, command) {
     ];
     const method = [...SDK_METHOD_ACTIONS].find(([, action]) => action === command.name)?.[0];
     if (method)
-        lines.push('SDK：', ...(method === 'browserRelease'
+        lines.push('SDK：', ...(method === 'browserRelease' || method === 'browserList'
             ? [
-                '  await mearl.browserRelease(options?)',
-                '  await mearl.browserRelease(params, options)',
+                `  await mearl.${method}(options?)`,
+                `  await mearl.${method}(params, options)`,
             ]
             : [
                 `  await mearl.${method}(${SDK_OPTIONS_ONLY_METHODS.has(method) ? 'options?' : 'params, options?'})`,

package/dist/commandSuggestions.d.ts

@@ -1,5 +1,7 @@
 export interface SuggestableCommand {
     readonly aliases?: readonly string[];
+    /** Suggestion-only expressions whose canonical invocation needs a specific payload. */
+    readonly aliasExamples?: Readonly<Record<string, string>>;
     readonly description: string;
     readonly examples?: readonly string[];
     readonly name: string;
@@ -7,6 +9,7 @@ export interface SuggestableCommand {
 export interface CommandSuggestion {
     command: SuggestableCommand;
     score: number;
+    example?: string;
 }
 export declare function commandInput(args: readonly string[]): string;
 export declare function findCommandSuggestions(args: readonly string[], commands: readonly SuggestableCommand[], limit?: number): CommandSuggestion[];

package/dist/commandSuggestions.js

@@ -40,9 +40,20 @@ export function findCommandSuggestions(args, commands, limit = 3) {
         return [];
     const ranked = commands
         .map(command => {
-        const keys = [command.name, ...(command.aliases ?? [])].map(normalizeCommand);
-        const score = Math.max(...queries.flatMap(query => keys.map(key => similarity(query, key))));
-        return { command, score };
+        const keys = [command.name, ...(command.aliases ?? [])].map(name => ({ name }));
+        for (const [name, example] of Object.entries(command.aliasExamples ?? {})) {
+            keys.push({ name, example });
+        }
+        let score = -1;
+        let example;
+        for (const key of keys) {
+            const candidate = Math.max(...queries.map(query => similarity(query, normalizeCommand(key.name))));
+            if (candidate > score) {
+                score = candidate;
+                example = key.example;
+            }
+        }
+        return { command, score, ...(example ? { example } : {}) };
     })
         .filter(suggestion => suggestion.score >= MIN_SIMILARITY)
         .sort((left, right) => right.score - left.score || left.command.name.localeCompare(right.command.name));
@@ -52,8 +63,8 @@ export function findCommandSuggestions(args, commands, limit = 3) {
     return ranked.filter(suggestion => bestScore - suggestion.score <= MAX_SCORE_GAP).slice(0, limit);
 }
 export function formatCommandSuggestions(commandName, suggestions) {
-    return suggestions.map(({ command }) => {
-        const invocation = command.examples?.[0] ?? command.name;
+    return suggestions.map(({ command, example }) => {
+        const invocation = example ?? command.examples?.[0] ?? command.name;
         return `  ${commandName} ${invocation}\n    ${command.description}`;
     });
 }

package/dist/commands.d.ts

@@ -14,6 +14,8 @@ export interface CommandDef {
     summary?: string;
     /** CLI 中用于推荐 canonical action 的常见表达，不会作为可执行 action。 */
     aliases?: readonly string[];
+    /** 仅用于错误建议；按表达给出 canonical action 的适用示例，不增加可执行别名。 */
+    aliasExamples?: Readonly<Record<string, string>>;
     /** payload 字段说明 */
     params?: ParamDef[];
     /** 是否支持 --output */
@@ -86,7 +88,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["tab_checkpoint --payload '{\"tabId\":12345}'"];
 }, {
     readonly name: "get_requests";
-    readonly description: "获取最近的网络请求（mtop 或普通 xhr/fetch）";
+    readonly description: "获取最近的网络请求（协议请求或普通 xhr/fetch）";
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
@@ -98,8 +100,8 @@ export declare const COMMANDS: readonly [{
         readonly description: "返回条数，默认 10";
     }, {
         readonly name: "source";
-        readonly type: "\"mtop\" | \"requests\" | \"all\"";
-        readonly description: "数据来源，不填时默认 mtop；all 返回全部业务请求";
+        readonly type: "\"protocol\" | \"requests\" | \"all\"";
+        readonly description: "数据来源，不填时默认 all；all 返回全部业务请求";
     }, {
         readonly name: "filter";
         readonly type: "string";
@@ -133,9 +135,9 @@ export declare const COMMANDS: readonly [{
         readonly type: "boolean";
         readonly description: "只返回数据结构，不返回叶子值";
     }];
-    readonly notes: readonly ["流式请求开始后即进入缓冲区；页面及 App 桥代发的 MTop SSE 都归入 mtop。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。"];
+    readonly notes: readonly ["流式请求开始后即进入缓冲区；页面及 App 桥代发的 协议 SSE 都归入 protocol。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。"];
     readonly result: readonly ["nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。", "省略正文时不返回 postData / responseBody 字段；指定 fields 后需要同时读取全文时显式传 includeBody:true。", "isPending 标记未完成请求；SSE 的 responseBody 保存按序到达的 event/data/timestamp/duration 分片。敏感请求头返回脱敏值。"];
-    readonly examples: ["get_requests --payload '{\"tabId\":12345,\"count\":5}'", "get_requests --payload '{\"tabId\":12345,\"source\":\"mtop\",\"filter\":\"cart\"}'"];
+    readonly examples: ["get_requests --payload '{\"tabId\":12345,\"count\":5}'", "get_requests --payload '{\"tabId\":12345,\"source\":\"protocol\",\"filter\":\"cart\"}'"];
 }, {
     readonly name: "get_logs";
     readonly description: "获取浏览器控制台日志";
@@ -242,7 +244,7 @@ export declare const COMMANDS: readonly [{
         readonly description: "请求 query/body 字段子集匹配；$index 从 0 开始指定调用顺序";
     }];
     readonly notes: readonly ["启用时至少提供 mockData 或非空 fields；非空 fields 优先。fields 每项 { path: string, value: any }，path 支持点号和数组索引。", "相同 apiName 的多条无条件 Mock 会覆盖；conditions 子集匹配 query/body（含 data 内层），不同条件可共存；$index 从 0 起控制调用顺序，不参与字段匹配。", "大字段可用顶层 @<绝对路径> 文件引用或 --payload-file；文件展开后仍受 Native Messaging 单条消息大小限制。"];
-    readonly examples: ["set_mock --payload '{\"tabId\":12345,\"apiName\":\"mtop.cart.query\",\"mockData\":{\"ret\":[\"SUCCESS::调用成功\"]}}'", "set_mock --payload-file ./mock-data.json"];
+    readonly examples: ["set_mock --payload '{\"tabId\":12345,\"apiName\":\"cart.query\",\"mockData\":{\"ret\":[\"SUCCESS::调用成功\"]}}'", "set_mock --payload-file ./mock-data.json"];
 }, {
     readonly name: "get_mocks";
     readonly description: "查看当前生效的 mock 列表";
@@ -307,7 +309,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly description: "规则说明";
     }];
-    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。", "扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。"];
+    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。", "扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。"];
     readonly examples: ["set_rule --payload '{\"actionType\":\"block\",\"filter\":\"^https://example\\\\.com/ads/.*\"}'", "set_rule --payload '{\"ruleId\":42,\"enabled\":false}'"];
 }, {
     readonly name: "get_rules";
@@ -367,46 +369,30 @@ export declare const COMMANDS: readonly [{
     readonly result: readonly ["返回 status、statusText、headers、body、bodyType、attachedCookieCount；bodyType 为 json/text/base64，二进制 body 需解码后保存。"];
     readonly examples: ["send_request --payload '{\"url\":\"https://api.example.com/data\",\"method\":\"GET\"}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"formData\":{\"folder\":\"assets\"},\"files\":[{\"fieldName\":\"file\",\"filePath\":\"/absolute/path/image.png\"}]}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"bodyFile\":{\"filePath\":\"/absolute/path/image.png\",\"contentType\":\"image/png\"}}'"];
 }, {
-    readonly name: "send_mtop_request";
-    readonly description: "使用目标浏览器 Cookie 发起 mtop 请求，自动处理签名和 token";
+    readonly name: "send_protocol_request";
+    readonly description: "通过已安装的请求协议能力，使用目标浏览器 Cookie 发送请求";
     readonly params: [{
-        readonly name: "api";
-        readonly type: "string";
-        readonly required: true;
-        readonly description: "mtop API 名称";
-    }, {
-        readonly name: "data";
-        readonly type: "object";
-        readonly description: "请求数据";
-    }, {
-        readonly name: "version";
-        readonly type: "string";
-        readonly description: "API 版本，默认 1.0";
-    }, {
-        readonly name: "method";
-        readonly type: "string";
-        readonly description: "HTTP 方法，默认 GET";
-    }, {
-        readonly name: "appKey";
-        readonly type: "string";
-        readonly description: "签名使用的 appKey，默认 12574478";
-    }, {
-        readonly name: "env";
-        readonly type: "\"prod\" | \"pre\"";
-        readonly description: "请求环境，默认 prod";
-    }, {
         readonly name: "timeout";
         readonly type: "number";
-        readonly description: "超时毫秒数，默认 10000";
+        readonly description: "宿主超时毫秒数；协议能力负责校验具体参数";
     }];
-    readonly notes: readonly ["需要目标浏览器有对应登录态；Mearl 自动处理签名，不依赖页面脚本。api 以 mopen. 开头时使用 mopen 协议。", "env=prod/pre 的网关由已安装的请求协议能力提供。"];
-    readonly result: readonly ["返回 success、response、requestData；业务成功需检查 response.ret。"];
-    readonly examples: ["send_mtop_request --payload '{\"api\":\"mtop.trade.order.detail\",\"data\":{\"orderId\":\"123\"}}'"];
+    readonly notes: readonly ["需要安装提供 request.protocol 的能力包；参数、签名、网关与响应协议由能力包定义。", "使用 --payload 传递协议文档声明的参数；核心不设置业务参数默认值。"];
+    readonly result: readonly ["返回 success、response、requestData；业务结果由协议定义。"];
+    readonly examples: ["send_protocol_request --payload '{\"operation\":\"example\",\"data\":{}}'"];
 }, {
     readonly name: "browser_list";
     readonly description: "列出所有浏览器及其连接状态、类型和 Provider 托管实例信息";
     readonly summary: "列出本地及远端浏览器与连接状态";
-    readonly examples: ["browser_list"];
+    readonly params: [{
+        readonly name: "provider";
+        readonly type: "string";
+        readonly description: "配合 launchForm，仅查询一个本机已安装 Provider 的启动候选；需 --local";
+    }, {
+        readonly name: "launchForm";
+        readonly type: "object";
+        readonly description: "现有动态启动表单请求：{variant?,values:{}}，不创建或接入实例";
+    }];
+    readonly examples: ["browser_list", "browser_list --local"];
 }, {
     readonly name: "browser_release";
     readonly description: "释放当前浏览器的调试控制和会话级临时效果（含设备/时区模拟）；不用于普通任务收尾，Provider 实例的行为以 mearl <providerId> 为准";
@@ -489,6 +475,9 @@ export declare const COMMANDS: readonly [{
     readonly name: "tab_open";
     readonly description: "打开或按 URL 规则复用 Tab，并等待新页面加载完成";
     readonly aliases: readonly ["tab_new", "new_tab", "tab_create", "create_tab"];
+    readonly aliasExamples: {
+        readonly tab_activate: "tab_open --payload '{\"url\":\"https://example.com\",\"reuse\":\"require\",\"active\":true}'";
+    };
     readonly params: [{
         readonly name: "url";
         readonly type: "string";
@@ -529,7 +518,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "appProfile";
         readonly type: "string";
-        readonly description: "按已安装档案应用 App 环境，ID 与限制通过 get_capabilities 查询。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
+        readonly description: "按已安装档案应用 App 环境，ID 与限制见当前动态帮助。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
     }, {
         readonly name: "os";
         readonly type: "\"ios\" | \"android\"";
@@ -581,6 +570,9 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "page_click";
     readonly description: "点击页面元素，支持 CSS/@ref、可见文本或视口坐标定位";
+    readonly aliasExamples: {
+        readonly page_select: "page_click --payload '{\"tabId\":12345,\"text\":\"选项文案\",\"role\":\"option\"}'";
+    };
     readonly params: [{
         readonly name: "selector";
         readonly type: "string";
@@ -624,7 +616,7 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
-    readonly notes: readonly ["selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。", "原生 select 可按 option 文本点击；checkbox/radio 返回 controlState.checkedBefore/checkedAfter。"];
+    readonly notes: readonly ["selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。", "auto 对原生 option、checkbox/radio 使用状态感知的 DOM 路径；显式 mouse/touch 保留可信输入。", "原生 select 可按 option 文本点击；auto/dom 返回 selectionState.valueBefore/valueAfter/selectedAfter，检查选中状态是否保持。checkbox/radio 返回 controlState.checkedBefore/checkedAfter。"];
     readonly examples: ["page_click --payload '{\"tabId\":12345,\"text\":\"提交\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\"@e3\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".submit-btn\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":336,\"y\":117}}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":196,\"y\":240},\"coordinateSpace\":\"active-frame\"}'"];
 }, {
     readonly name: "page_drag";
@@ -659,6 +651,9 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "page_type";
     readonly description: "向输入框填写文本，兼容 React 受控组件";
+    readonly aliasExamples: {
+        readonly page_fill: "page_type --payload '{\"tabId\":12345,\"selector\":\"@e6\",\"text\":\"填写内容\",\"clearFirst\":true}'";
+    };
     readonly params: [{
         readonly name: "selector";
         readonly type: "string";
@@ -820,6 +815,14 @@ export declare const COMMANDS: readonly [{
         readonly name: "modifiers";
         readonly type: "string[]";
         readonly description: "修饰键数组：ctrl/alt/shift/meta/cmd";
+    }, {
+        readonly name: "dialogId";
+        readonly type: "string";
+        readonly description: "原生弹窗回执或 page_snapshot 中的 dialog.id；仅配合 Enter 接受或 Escape 取消";
+    }, {
+        readonly name: "promptText";
+        readonly type: "string";
+        readonly description: "仅用于 dialogId + Enter 接受原生 prompt 时填写文本";
     }, {
         readonly name: "pressMode";
         readonly type: "\"auto\" | \"dom\" | \"keyboard\"";
@@ -830,7 +833,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly notes: readonly ["隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。"];
+    readonly notes: readonly ["隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。", "原生 alert/confirm/prompt/beforeunload 弹窗需显式传 dialogId；普通 Enter 不处理弹窗。弹窗处理绕过 DOM 观察，不自动重放被中断的动作；处理后重新读取页面。"];
     readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
     readonly examples: ["page_press --payload '{\"tabId\":12345,\"key\":\"Enter\"}'"];
 }, {
@@ -874,11 +877,14 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly notes: readonly ["time / selector / text / condition 必须且只能提供一个；time 范围 0–60000ms。页面交互已有内置观察，仅在需要独立等待条件时使用。"];
+    readonly notes: readonly ["time / selector / text / condition 必须且只能提供一个；time 范围 0–60000ms。页面交互已有内置观察，仅在需要独立等待条件时使用。", "等待后须立即执行已知动作时，用 mearl run 在同一脚本中 await pageWait 后紧接 pageClick，避免模型往返。整体 --timeout 须覆盖等待及后续动作；等待失败不继续点击。"];
     readonly examples: ["page_wait --payload '{\"tabId\":12345,\"time\":1000}'", "page_wait --payload '{\"tabId\":12345,\"selector\":\".dialog\",\"state\":\"visible\"}'", "page_wait --payload '{\"tabId\":12345,\"selector\":\".loading\",\"state\":\"hidden\"}'", "page_wait --payload '{\"tabId\":12345,\"text\":\"提交成功\"}'", "page_wait --payload '{\"tabId\":12345,\"condition\":\"window.appReady === true\",\"timeout\":30000}'"];
 }, {
     readonly name: "page_navigate";
     readonly description: "在当前标签页内导航到 URL、刷新页面，或沿浏览历史后退/前进";
+    readonly aliasExamples: {
+        readonly page_reload: "page_navigate --payload '{\"tabId\":12345,\"refresh\":true}'";
+    };
     readonly params: [{
         readonly name: "url";
         readonly type: "string";
@@ -1065,7 +1071,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"iphone-17-pro\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"pixel-11\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":false}'"];
 }, {
     readonly name: "set_app_profile";
-    readonly description: "设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟";
+    readonly description: "设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置已安装的网络控件，传 emulation 时联动设备模拟";
     readonly summary: "设置或清除目标标签页的 App 容器模拟";
     readonly params: [{
         readonly name: "enabled";
@@ -1075,7 +1081,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "profile";
         readonly type: "string";
-        readonly description: "已安装的容器档案 ID（enabled=true 时必填）；通过 get_capabilities 查询当前浏览器目录";
+        readonly description: "已安装的容器档案 ID（enabled=true 时必填）；当前动态帮助直接展示目标浏览器目录";
     }, {
         readonly name: "os";
         readonly type: "\"ios\" | \"android\"";
@@ -1101,9 +1107,9 @@ export declare const COMMANDS: readonly [{
         readonly type: "object";
         readonly description: "声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本";
     }, {
-        readonly name: "mtopEnv";
-        readonly type: "\"default\" | \"prod\" | \"pre\"";
-        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab";
+        readonly name: "networkControl";
+        readonly type: "object | null";
+        readonly description: "可选已安装网络控件 {id,value}；null 清除，省略时保持当前设置。仅作用于目标 tab";
     }, {
         readonly name: "emulation";
         readonly type: "object";
@@ -1119,8 +1125,8 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly notes: readonly ["只有用户明确要求 App/客户端/容器/JSBridge 模拟时启用。移动视口或普通 H5 调试使用 set_device_emulation。", "emulation={} 使用档案推荐设备；enabled=false 时省略 emulation 只清除 App 注入，传 {} 同时清除设备模拟。", "bridgeConfig.methods 按方法声明 behavior / response / noop 三选一，可传 silent；只支持受控行为、固定 JSON 回包或成功空实现，不执行配置脚本。"];
-    readonly result: readonly ["返回 enabled、profile、label、userAgent、os、mtopEnv、reloaded；联动设备时额外返回实际 emulation。"];
-    readonly examples: ["set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\",\"mtopEnv\":\"pre\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false,\"mtopEnv\":\"prod\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\",\"emulation\":{}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"wallet\",\"emulation\":{\"preset\":\"pixel-11\",\"deviceShell\":true}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false,\"emulation\":{}}'"];
+    readonly result: readonly ["返回 enabled、profile、label、userAgent、os、networkControl、reloaded；联动设备时额外返回实际 emulation。"];
+    readonly examples: ["set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\",\"networkControl\":{\"id\":\"environment\",\"value\":\"pre\"}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false,\"networkControl\":null}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\",\"emulation\":{}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"wallet\",\"emulation\":{\"preset\":\"pixel-11\",\"deviceShell\":true}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false,\"emulation\":{}}'"];
 }, {
     readonly name: "set_timezone";
     readonly description: "覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区";
@@ -1213,7 +1219,7 @@ export declare const COMMANDS: readonly [{
     readonly result: readonly ["frames[] 包含 frameId、url、name 和 isMainFrame；frameId 可用于 page_eval 等支持 frame 定位的 action。"];
     readonly examples: ["page_frames --payload '{\"tabId\":12345}'"];
 }, {
-    readonly name: "request_domain_permission";
+    readonly name: "request_permission";
     readonly description: "申请访问指定域名的权限（必要时弹窗让用户授权）";
     readonly params: [{
         readonly name: "domain";
@@ -1223,7 +1229,7 @@ export declare const COMMANDS: readonly [{
     }];
     readonly notes: readonly ["domain 使用纯主机名，不传 URL。在 send_request 或 set_rule 提示缺少浏览器域名权限时申请。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
     readonly result: readonly ["返回 granted、domain，授权成功时包含 origin。"];
-    readonly examples: ["request_domain_permission --payload '{\"domain\":\"example.com\"}'"];
+    readonly examples: ["request_permission --payload '{\"domain\":\"example.com\"}'"];
 }, {
     readonly name: "run_actions";
     readonly description: "批量顺序执行多个 action，减少往返延迟。遇错即停，返回已完成步骤结果；步骤内的页面动作不带内置观察";

package/dist/commands.js

@@ -101,7 +101,7 @@ export const COMMANDS = [
     },
     {
         name: 'get_requests',
-        description: '获取最近的网络请求（mtop 或普通 xhr/fetch）',
+        description: '获取最近的网络请求（协议请求或普通 xhr/fetch）',
         params: [
             {
                 name: 'tabId',
@@ -112,8 +112,8 @@ export const COMMANDS = [
             { name: 'count', type: 'number', description: '返回条数，默认 10' },
             {
                 name: 'source',
-                type: '"mtop" | "requests" | "all"',
-                description: '数据来源，不填时默认 mtop；all 返回全部业务请求',
+                type: '"protocol" | "requests" | "all"',
+                description: '数据来源，不填时默认 all；all 返回全部业务请求',
             },
             { name: 'filter', type: 'string', description: '按 URL 或 API 名称过滤，支持正则' },
             { name: 'since', type: 'number', description: '只返回最近 N 秒内的请求' },
@@ -133,7 +133,7 @@ export const COMMANDS = [
             { name: 'keysOnly', type: 'boolean', description: '只返回数据结构，不返回叶子值' },
         ],
         notes: [
-            '流式请求开始后即进入缓冲区；页面及 App 桥代发的 MTop SSE 都归入 mtop。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。',
+            '流式请求开始后即进入缓冲区；页面及 App 桥代发的 协议 SSE 都归入 protocol。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。',
         ],
         result: [
             'nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。',
@@ -142,7 +142,7 @@ export const COMMANDS = [
         ],
         examples: [
             `get_requests --payload '{"tabId":12345,"count":5}'`,
-            `get_requests --payload '{"tabId":12345,"source":"mtop","filter":"cart"}'`,
+            `get_requests --payload '{"tabId":12345,"source":"protocol","filter":"cart"}'`,
         ],
     },
     {
@@ -249,7 +249,7 @@ export const COMMANDS = [
             '大字段可用顶层 @<绝对路径> 文件引用或 --payload-file；文件展开后仍受 Native Messaging 单条消息大小限制。',
         ],
         examples: [
-            `set_mock --payload '{"tabId":12345,"apiName":"mtop.cart.query","mockData":{"ret":["SUCCESS::调用成功"]}}'`,
+            `set_mock --payload '{"tabId":12345,"apiName":"cart.query","mockData":{"ret":["SUCCESS::调用成功"]}}'`,
             `set_mock --payload-file ./mock-data.json`,
         ],
     },
@@ -303,7 +303,7 @@ export const COMMANDS = [
         ],
         notes: [
             '扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。',
-            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
+            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
         ],
         examples: [
             `set_rule --payload '{"actionType":"block","filter":"^https://example\\\\.com/ads/.*"}'`,
@@ -369,32 +369,28 @@ export const COMMANDS = [
         ],
     },
     {
-        name: 'send_mtop_request',
-        description: '使用目标浏览器 Cookie 发起 mtop 请求，自动处理签名和 token',
+        name: 'send_protocol_request',
+        description: '通过已安装的请求协议能力，使用目标浏览器 Cookie 发送请求',
         params: [
-            { name: 'api', type: 'string', required: true, description: 'mtop API 名称' },
-            { name: 'data', type: 'object', description: '请求数据' },
-            { name: 'version', type: 'string', description: 'API 版本，默认 1.0' },
-            { name: 'method', type: 'string', description: 'HTTP 方法，默认 GET' },
-            { name: 'appKey', type: 'string', description: '签名使用的 appKey，默认 12574478' },
-            { name: 'env', type: '"prod" | "pre"', description: '请求环境，默认 prod' },
-            { name: 'timeout', type: 'number', description: '超时毫秒数，默认 10000' },
+            { name: 'timeout', type: 'number', description: '宿主超时毫秒数；协议能力负责校验具体参数' },
         ],
         notes: [
-            '需要目标浏览器有对应登录态；Mearl 自动处理签名，不依赖页面脚本。api 以 mopen. 开头时使用 mopen 协议。',
-            'env=prod/pre 的网关由已安装的请求协议能力提供。',
-        ],
-        result: ['返回 success、response、requestData；业务成功需检查 response.ret。'],
-        examples: [
-            `send_mtop_request --payload '{"api":"mtop.trade.order.detail","data":{"orderId":"123"}}'`,
+            '需要安装提供 request.protocol 的能力包；参数、签名、网关与响应协议由能力包定义。',
+            '使用 --payload 传递协议文档声明的参数；核心不设置业务参数默认值。',
         ],
+        result: ['返回 success、response、requestData；业务结果由协议定义。'],
+        examples: [`send_protocol_request --payload '{"operation":"example","data":{}}'`],
     },
     // ── 浏览器 ────────────────────────────────────────────────────────────────
     {
         name: 'browser_list',
         description: '列出所有浏览器及其连接状态、类型和 Provider 托管实例信息',
         summary: '列出本地及远端浏览器与连接状态',
-        examples: ['browser_list'],
+        params: [
+            { name: 'provider', type: 'string', description: '配合 launchForm，仅查询一个本机已安装 Provider 的启动候选；需 --local' },
+            { name: 'launchForm', type: 'object', description: '现有动态启动表单请求：{variant?,values:{}}，不创建或接入实例' },
+        ],
+        examples: ['browser_list', 'browser_list --local'],
     },
     {
         name: 'browser_release',
@@ -501,6 +497,9 @@ export const COMMANDS = [
         name: 'tab_open',
         description: '打开或按 URL 规则复用 Tab，并等待新页面加载完成',
         aliases: ['tab_new', 'new_tab', 'tab_create', 'create_tab'],
+        aliasExamples: {
+            tab_activate: `tab_open --payload '{"url":"https://example.com","reuse":"require","active":true}'`,
+        },
         params: [
             { name: 'url', type: 'string', required: true, description: '要打开的 URL' },
             {
@@ -546,7 +545,7 @@ export const COMMANDS = [
             {
                 name: 'appProfile',
                 type: 'string',
-                description: '按已安装档案应用 App 环境，ID 与限制通过 get_capabilities 查询。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
+                description: '按已安装档案应用 App 环境，ID 与限制见当前动态帮助。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
             },
             {
                 name: 'os',
@@ -618,6 +617,9 @@ export const COMMANDS = [
     {
         name: 'page_click',
         description: '点击页面元素，支持 CSS/@ref、可见文本或视口坐标定位',
+        aliasExamples: {
+            page_select: `page_click --payload '{"tabId":12345,"text":"选项文案","role":"option"}'`,
+        },
         params: [
             {
                 name: 'selector',
@@ -671,7 +673,8 @@ export const COMMANDS = [
         result: PAGE_ACTION_RESULT,
         notes: [
             'selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。',
-            '原生 select 可按 option 文本点击；checkbox/radio 返回 controlState.checkedBefore/checkedAfter。',
+            'auto 对原生 option、checkbox/radio 使用状态感知的 DOM 路径；显式 mouse/touch 保留可信输入。',
+            '原生 select 可按 option 文本点击；auto/dom 返回 selectionState.valueBefore/valueAfter/selectedAfter，检查选中状态是否保持。checkbox/radio 返回 controlState.checkedBefore/checkedAfter。',
         ],
         examples: [
             `page_click --payload '{"tabId":12345,"text":"提交"}'`,
@@ -726,6 +729,9 @@ export const COMMANDS = [
     {
         name: 'page_type',
         description: '向输入框填写文本，兼容 React 受控组件',
+        aliasExamples: {
+            page_fill: `page_type --payload '{"tabId":12345,"selector":"@e6","text":"填写内容","clearFirst":true}'`,
+        },
         params: [
             {
                 name: 'selector',
@@ -911,6 +917,8 @@ export const COMMANDS = [
                 description: '按键名称：Enter/Tab/Escape/Backspace 等',
             },
             { name: 'modifiers', type: 'string[]', description: '修饰键数组：ctrl/alt/shift/meta/cmd' },
+            { name: 'dialogId', type: 'string', description: '原生弹窗回执或 page_snapshot 中的 dialog.id；仅配合 Enter 接受或 Escape 取消' },
+            { name: 'promptText', type: 'string', description: '仅用于 dialogId + Enter 接受原生 prompt 时填写文本' },
             {
                 name: 'pressMode',
                 type: '"auto" | "dom" | "keyboard"',
@@ -922,6 +930,7 @@ export const COMMANDS = [
         ],
         notes: [
             '隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。',
+            '原生 alert/confirm/prompt/beforeunload 弹窗需显式传 dialogId；普通 Enter 不处理弹窗。弹窗处理绕过 DOM 观察，不自动重放被中断的动作；处理后重新读取页面。',
         ],
         result: [
             ...PAGE_ACTION_RESULT,
@@ -961,6 +970,7 @@ export const COMMANDS = [
         ],
         notes: [
             'time / selector / text / condition 必须且只能提供一个；time 范围 0–60000ms。页面交互已有内置观察，仅在需要独立等待条件时使用。',
+            '等待后须立即执行已知动作时，用 mearl run 在同一脚本中 await pageWait 后紧接 pageClick，避免模型往返。整体 --timeout 须覆盖等待及后续动作；等待失败不继续点击。',
         ],
         examples: [
             `page_wait --payload '{"tabId":12345,"time":1000}'`,
@@ -973,6 +983,9 @@ export const COMMANDS = [
     {
         name: 'page_navigate',
         description: '在当前标签页内导航到 URL、刷新页面，或沿浏览历史后退/前进',
+        aliasExamples: {
+            page_reload: `page_navigate --payload '{"tabId":12345,"refresh":true}'`,
+        },
         params: [
             {
                 name: 'url',
@@ -1172,14 +1185,14 @@ export const COMMANDS = [
     },
     {
         name: 'set_app_profile',
-        description: '设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟',
+        description: '设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置已安装的网络控件，传 emulation 时联动设备模拟',
         summary: '设置或清除目标标签页的 App 容器模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
             {
                 name: 'profile',
                 type: 'string',
-                description: '已安装的容器档案 ID（enabled=true 时必填）；通过 get_capabilities 查询当前浏览器目录',
+                description: '已安装的容器档案 ID（enabled=true 时必填）；当前动态帮助直接展示目标浏览器目录',
             },
             { name: 'os', type: '"ios" | "android"', description: '容器系统，默认 ios' },
             {
@@ -1204,9 +1217,9 @@ export const COMMANDS = [
                 description: '声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本',
             },
             {
-                name: 'mtopEnv',
-                type: '"default" | "prod" | "pre"',
-                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab',
+                name: 'networkControl',
+                type: 'object | null',
+                description: '可选已安装网络控件 {id,value}；null 清除，省略时保持当前设置。仅作用于目标 tab',
             },
             {
                 name: 'emulation',
@@ -1222,12 +1235,12 @@ export const COMMANDS = [
             'bridgeConfig.methods 按方法声明 behavior / response / noop 三选一，可传 silent；只支持受控行为、固定 JSON 回包或成功空实现，不执行配置脚本。',
         ],
         result: [
-            '返回 enabled、profile、label、userAgent、os、mtopEnv、reloaded；联动设备时额外返回实际 emulation。',
+            '返回 enabled、profile、label、userAgent、os、networkControl、reloaded；联动设备时额外返回实际 emulation。',
         ],
         examples: [
             `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader"}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","mtopEnv":"pre"}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":false,"mtopEnv":"prod"}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","networkControl":{"id":"environment","value":"pre"}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":false,"networkControl":null}'`,
             `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","emulation":{}}'`,
             `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"wallet","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
             `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
@@ -1347,7 +1360,7 @@ export const COMMANDS = [
         examples: [`page_frames --payload '{"tabId":12345}'`],
     },
     {
-        name: 'request_domain_permission',
+        name: 'request_permission',
         description: '申请访问指定域名的权限（必要时弹窗让用户授权）',
         params: [
             {
@@ -1362,7 +1375,7 @@ export const COMMANDS = [
             '弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。',
         ],
         result: ['返回 granted、domain，授权成功时包含 origin。'],
-        examples: [`request_domain_permission --payload '{"domain":"example.com"}'`],
+        examples: [`request_permission --payload '{"domain":"example.com"}'`],
     },
     // ── 组合调用 ────────────────────────────────────────────────────────────────
     {

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, SendProtocolRequestParams, 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,9 @@ 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 sendProtocolRequest(params: Protocol.SendProtocolRequestParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'send_protocol_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,13 @@ 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 sendProtocolRequest(params, options) {
+    return invoke('send_protocol_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/runtime/pluginTaskManager.js

@@ -884,7 +884,7 @@ export class PluginTaskManager {
                         });
                     }
                     if (restrictedTarget &&
-                        !['send_request', 'send_mtop_request', 'browser_list', 'connector_list'].includes(action))
+                        !['send_request', 'send_protocol_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/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() }
+        : {};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "3.0.0-beta.5",
+  "version": "3.0.0-beta.7",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -58,20 +58,20 @@
   ],
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "commander": "^15.0.0",
+    "commander": "^14.0.3",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/provider": "3.0.0-beta.5",
-    "@mearl/agent-runtime": "3.0.0-beta.5",
-    "@mearl/browser-core": "3.0.0-beta.5",
-    "@mearl/cloud-types": "3.0.0-beta.5",
-    "@mearl/daemon-core": "3.0.0-beta.5"
+    "@mearl/daemon-core": "3.0.0-beta.7",
+    "@mearl/cloud-types": "3.0.0-beta.7",
+    "@mearl/provider": "3.0.0-beta.7",
+    "@mearl/agent-runtime": "3.0.0-beta.7",
+    "@mearl/browser-core": "3.0.0-beta.7"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
@@ -80,7 +80,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/F-loat/mearl.git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
     "directory": "packages/client"
   },
   "scripts": {