@mearl/client 2.8.1 → 2.9.0

package/README.md

@@ -55,6 +55,7 @@ mearl set_mock --payload-file ./mock-data.json
 
 # 环境自检
 mearl check
+mearl check --local --json
 
 # 更新本地环境
 npx @mearl/setup update --local
@@ -68,6 +69,7 @@ mearl browser_launch --payload '{"name":"account-b","query":"test_account"}'
 mearl browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
 mearl browser_launch --payload '{"name":"cloud-login","provider":"agentbay","persistent":true,"userAgentMode":"desktop","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'
 mearl browser_launch --browser '<控制浏览器 browserId>' --payload '{"name":"cloud-login","provider":"agentbay","reuse":"require","copyCookieDomains":["example.com"]}'
+mearl browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":"mearl-services"}'
 mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
 mearl browser_list
 mearl browser_release
@@ -110,13 +112,13 @@ mearl browser_release
 
 `page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
 
-重复文本点击可用 `page_click.scope` 限定 CSS / ref 子树；ref 指向滚动容器内的子节点时，可用 `page_scroll.containerPolicy: "nearest"` 自动解析最近可滚动祖先。点击结果的 `resolvedTarget` 和滚动结果的前后位置、边界字段可用于诊断实际目标与效果。
+重复文本点击可用 `page_click.scope` 限定 CSS / ref 子树；浏览器扩展后端中，容器或 iframe 内的点坐标使用 `coordinateSpace: "active-frame"`，CSS/text 查询可用 `frameId` 显式指定 frame。点击结果通过 `requestedTarget`、`resolvedTarget`、`dispatchTarget`、`hitTarget` 和 `coordinates` 区分请求语义、DOM 解析、派发节点与可信输入实际命中；ref 指向滚动容器内的子节点时，可用 `page_scroll.containerPolicy: "nearest"` 自动解析最近可滚动祖先。
 
 `browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
 
 `browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时使用，不作为普通任务收尾。它会释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。
 
-托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`persistent: true` 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。`deleteProfile: true` 会显式删除对应 Profile 或 Context。AgentBay 的 `reuse` 支持 `never`（默认）、`prefer` 和 `require`：`prefer` 存在运行实例时复用、否则创建，`require` 只复用且不会意外创建计费会话。`copyCookieDomains` 可在首次启动或复用运行实例时把控制浏览器指定域的 Cookie 写入目标，Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 仅通过 `agentbayImageId`、`agentbayContextId` 和 `agentbayContextName` 返回 AgentBay 实例的稳定配置。无影浏览器串流入口包含临时访问凭据且会过期，因此不会写入实例记录或列表结果；需要时运行 `mearl check --browser <id|名称>` 实时获取，并按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
+托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`persistent: true` 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。`deleteProfile: true` 会显式删除对应 Profile 或 Context。AgentBay 的 `reuse` 支持 `never`（默认）、`prefer` 和 `require`：`prefer` 存在运行实例时复用、否则创建，`require` 只复用且不会意外创建计费会话。`copyCookieDomains` 传数组时把控制浏览器指定域的 Cookie 写入目标，传 `"mearl-services"` 时同步 Mearl 依赖平台登录态。Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 仅通过 `agentbayImageId`、`agentbayContextId` 和 `agentbayContextName` 返回 AgentBay 实例的稳定配置。无影浏览器串流入口包含临时访问凭据且会过期，因此不会写入实例记录或列表结果；需要时运行 `mearl check --browser <id|名称>` 实时获取，并按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 
 ## 架构
 

package/dist/check.d.ts

@@ -1,4 +1,50 @@
+import type { CloudConnectorInfo } from '@mearl/cloud-types';
 import { type UnifiedClientOptions, type UnifiedInvokeOptions } from './unified.js';
+export interface UnifiedCheckVersions {
+    nativeHost?: string;
+    extension?: string | null;
+    browser?: string | null;
+}
+interface BrowserInfo {
+    browserId: string;
+    extensionVersion?: string;
+    name: string;
+    nativeHostVersion?: string;
+    originalBrowserId?: string;
+    originalName?: string;
+    status: string;
+    type?: string;
+    provider?: 'local' | 'agentbay';
+    transport?: 'extension' | 'cdp';
+}
+interface CheckItem {
+    status: 'ok' | 'warning' | 'error';
+    label: string;
+    details?: string[];
+}
+export interface ExtensionInstallationInfo {
+    extensionId: string;
+    setupManagedPath: string | null;
+}
+export interface UnifiedCheckBrowserResult extends BrowserInfo {
+    agentbayAccessUrl?: string;
+    check?: {
+        errors?: string[];
+        label: string;
+        status: CheckItem['status'];
+        warnings?: string[];
+    };
+    extensionInstallation?: ExtensionInstallationInfo;
+    selected: boolean;
+    versions?: UnifiedCheckVersions;
+}
+export interface UnifiedCheckResult {
+    browsers: UnifiedCheckBrowserResult[];
+    clientVersion: string;
+    connectors: CloudConnectorInfo[];
+    environment: CheckItem[];
+    ok: boolean;
+}
 interface CheckClient {
     invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
     disconnect(): void;
@@ -12,11 +58,16 @@ export interface UnifiedCheckOptions {
     connector?: string;
     local?: boolean;
     transport?: 'cdp';
+    json?: boolean;
 }
 export interface UnifiedCheckDependencies {
     createClient?: (options: UnifiedClientOptions) => CheckClient;
+    writeJson?: (json: string) => void;
     writeLine?: (line: string) => void;
 }
 export declare function parseCheckTimeout(value: string | undefined): number | null;
+export declare function runUnifiedCheck(options: UnifiedCheckOptions & {
+    json: true;
+}, dependencies?: UnifiedCheckDependencies): Promise<UnifiedCheckResult>;
 export declare function runUnifiedCheck(options: UnifiedCheckOptions, dependencies?: UnifiedCheckDependencies): Promise<boolean>;
 export {};

package/dist/check.js

@@ -73,6 +73,7 @@ export function parseCheckTimeout(value) {
 export async function runUnifiedCheck(options, dependencies = {}) {
     const timeoutSec = options.timeoutSec ?? 5;
     const writeLine = dependencies.writeLine ?? (line => console.error(line));
+    const writeJson = dependencies.writeJson ?? (json => process.stdout.write(`${json}\n`));
     const createClient = dependencies.createClient ??
         ((clientOptions) => new UnifiedClient(clientOptions));
     const client = createClient({
@@ -194,11 +195,28 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                     browser: browser.browserId,
                     ...(options.transport ? { transport: options.transport } : {}),
                 }));
+                const publicVersions = {
+                    ...(versions.nativeHost ? { nativeHost: versions.nativeHost } : {}),
+                    ...(versions.extension !== undefined ? { extension: versions.extension } : {}),
+                    ...(versions.browser !== undefined ? { browser: versions.browser } : {}),
+                };
                 const details = [
                     versions.nativeHost ? `native-host v${versions.nativeHost}` : null,
                     versions.extension ? `extension v${versions.extension}` : null,
                     versions.browser ? `Chrome ${versions.browser}` : null,
                 ].filter((value) => value !== null);
+                let extensionInstallation;
+                if (options.local &&
+                    browser.transport === 'extension' &&
+                    typeof versions.extensionId === 'string' &&
+                    typeof versions.extension === 'string' &&
+                    (typeof versions.setupManagedPath === 'string' || versions.setupManagedPath === null)) {
+                    extensionInstallation = {
+                        extensionId: versions.extensionId,
+                        setupManagedPath: versions.setupManagedPath,
+                    };
+                }
+                let agentbayAccessUrl;
                 let accessUrlWarning;
                 if (browser.provider === 'agentbay' && options.browser) {
                     try {
@@ -209,6 +227,7 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                         if (!access.agentbayAccessUrl) {
                             throw new Error('AgentBay did not return a browser access URL');
                         }
+                        agentbayAccessUrl = access.agentbayAccessUrl;
                         details.push(`AgentBay access URL (temporary, sensitive): ${access.agentbayAccessUrl}`);
                     }
                     catch (error) {
@@ -217,7 +236,9 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                     }
                 }
                 browserChecks.push({
+                    ...(agentbayAccessUrl ? { agentbayAccessUrl } : {}),
                     browser,
+                    ...(extensionInstallation ? { extensionInstallation } : {}),
                     item: {
                         status: accessUrlWarning ? 'warning' : 'ok',
                         label: accessUrlWarning
@@ -225,12 +246,17 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                             : 'Browser command path',
                         details,
                     },
+                    versions: publicVersions,
+                    ...(accessUrlWarning ? { warnings: [accessUrlWarning] } : {}),
                 });
             }
             catch (error) {
                 const message = formatError(error);
                 browserChecks.push({
                     browser,
+                    ...(message.includes('Unknown action')
+                        ? { warnings: ['Update @mearl/native-host for complete diagnostics.'] }
+                        : { errors: [message] }),
                     item: message.includes('Unknown action')
                         ? {
                             status: 'warning',
@@ -245,6 +271,44 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 });
             }
         }));
+        const hasError = environment.some(item => item.status === 'error') ||
+            browserChecks.some(check => check.item.status === 'error');
+        const listedBrowsers = browserList?.browsers ?? [];
+        if (options.json) {
+            const result = {
+                browsers: listedBrowsers.map(browser => {
+                    const check = browserChecks.find(item => item.browser.browserId === browser.browserId);
+                    const browserIdentity = { ...browser };
+                    delete browserIdentity.extensionVersion;
+                    delete browserIdentity.nativeHostVersion;
+                    return {
+                        ...browserIdentity,
+                        selected: targets.some(target => target.browserId === browser.browserId),
+                        ...(check?.agentbayAccessUrl ? { agentbayAccessUrl: check.agentbayAccessUrl } : {}),
+                        ...(check?.item
+                            ? {
+                                check: {
+                                    label: check.item.label,
+                                    status: check.item.status,
+                                    ...(check.errors ? { errors: check.errors } : {}),
+                                    ...(check.warnings ? { warnings: check.warnings } : {}),
+                                },
+                            }
+                            : {}),
+                        ...(check?.extensionInstallation
+                            ? { extensionInstallation: check.extensionInstallation }
+                            : {}),
+                        ...(check?.versions ? { versions: check.versions } : {}),
+                    };
+                }),
+                clientVersion: options.clientVersion,
+                connectors,
+                environment,
+                ok: !hasError,
+            };
+            writeJson(JSON.stringify(result, null, 2));
+            return result;
+        }
         writeLine('');
         printSection(writeLine, 'Environment', environment);
         if (connectors.length > 0) {
@@ -253,7 +317,6 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 writeLine(formatConnector(connector));
             writeLine('');
         }
-        const listedBrowsers = browserList?.browsers ?? [];
         if (listedBrowsers.length > 0) {
             writeLine('Browsers');
             for (const browser of listedBrowsers) {
@@ -271,8 +334,6 @@ export async function runUnifiedCheck(options, dependencies = {}) {
             }
             writeLine('');
         }
-        const hasError = environment.some(item => item.status === 'error') ||
-            browserChecks.some(check => check.item.status === 'error');
         if (hasError) {
             writeLine('⚠️  Mearl checks failed. See the browser or source details above.');
             return false;

package/dist/cli.d.ts

@@ -2,4 +2,20 @@ export interface MearlCliOptions {
     commandName?: string;
     clientVersion?: string;
 }
+export interface ParsedArgs {
+    action: string;
+    browser?: string;
+    compact: boolean;
+    connector?: string;
+    forceCdp: boolean;
+    json: boolean;
+    local: boolean;
+    outputPath?: string;
+    payload: Record<string, any>;
+    serverUrl?: string;
+    serverUrlSource?: string;
+    timeoutSec: number;
+    timeoutOption?: string;
+}
+export declare function parseClientArgs(args: string[]): ParsedArgs;
 export declare function runMearlCli(args: string[], options?: MearlCliOptions): Promise<number>;

package/dist/cli.js

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { Command, CommanderError } from 'commander';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
 import { runUnifiedCheck, parseCheckTimeout } from './check.js';
 import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from './commandSuggestions.js';
@@ -59,10 +60,6 @@ const BUILTIN_COMMANDS = [
 ];
 const SUGGESTABLE_COMMANDS = [...COMMANDS, ...BUILTIN_COMMANDS];
 const ADVANCED_BUILTIN_COMMANDS = new Set(['connector_list']);
-function optionValue(args, name) {
-    const index = args.indexOf(name);
-    return index >= 0 ? args[index + 1] : undefined;
-}
 function printUsage(commandName, version) {
     const lines = [
         `${commandName} v${version}`,
@@ -81,6 +78,7 @@ function printUsage(commandName, version) {
         '  --payload-file <path> 从文件读取整个 JSON 参数',
         '  --timeout <seconds>   超时时间（默认按 action 推导）',
         '  --compact             输出紧凑格式 JSON',
+        '  --json                check 输出机器可读 JSON',
         '  --output <path>       保存输出或截图',
         '  --browser <id|名称>   指定 browser_list 返回的浏览器',
         '  --connector <id|名称> 限制到一台远端 connector',
@@ -158,9 +156,7 @@ function parsePositiveTimeout(value, fallback) {
     }
     return parsed;
 }
-function parsePayload(args) {
-    const payloadRaw = optionValue(args, '--payload');
-    const payloadFile = optionValue(args, '--payload-file');
+function parsePayload(payloadRaw, payloadFile) {
     if (payloadRaw !== undefined && payloadFile !== undefined) {
         throw new Error('--payload 与 --payload-file 不能同时使用');
     }
@@ -182,33 +178,7 @@ function parsePayload(args) {
     }
     return {};
 }
-function validateOptions(args) {
-    const optionsWithValues = new Set([
-        '--payload',
-        '--payload-file',
-        '--timeout',
-        '--output',
-        '--browser',
-        '--connector',
-        '--server',
-    ]);
-    const flags = new Set(['--compact', '--local', '--cdp', '--help', '-h']);
-    for (let index = 1; index < args.length; index += 1) {
-        const arg = args[index];
-        if (optionsWithValues.has(arg)) {
-            if (!args[index + 1] || args[index + 1].startsWith('--')) {
-                throw new Error(`缺少 ${arg} 的参数值`);
-            }
-            index += 1;
-            continue;
-        }
-        if (flags.has(arg))
-            continue;
-        throw new Error(`未知参数: ${arg}`);
-    }
-}
-function resolveServer(args) {
-    const explicit = optionValue(args, '--server');
+function resolveServer(explicit) {
     if (explicit)
         return { serverUrl: explicit, serverUrlSource: '--server' };
     if (process.env.MEARL_SERVER_URL) {
@@ -219,27 +189,59 @@ function resolveServer(args) {
         ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
         : {};
 }
-function parseArgs(args) {
-    validateOptions(args);
-    const action = args[0];
-    const payload = parsePayload(args);
+export function parseClientArgs(args) {
+    const program = new Command()
+        .name('mearl')
+        .helpOption(false)
+        .allowExcessArguments(false)
+        .exitOverride()
+        .configureOutput({ writeErr: () => { }, writeOut: () => { } })
+        .argument('<action>')
+        .option('--payload <json>')
+        .option('--payload-file <path>')
+        .option('--timeout <seconds>')
+        .option('--compact')
+        .option('--json')
+        .option('--output <path>')
+        .option('--browser <id-or-name>')
+        .option('--connector <id-or-name>')
+        .option('--local')
+        .option('--cdp')
+        .option('--server <url>');
+    try {
+        program.parse(['node', 'mearl', ...args]);
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            throw new Error(error.message.replace(/^error:\s*/i, ''), { cause: error });
+        }
+        throw error;
+    }
+    const action = program.processedArgs[0];
+    const options = program.opts();
+    const json = options.json === true;
+    if (json && action !== 'check')
+        throw new Error('--json 仅适用于 check');
+    const payload = parsePayload(options.payload, options.payloadFile);
     const fallbackTimeout = resolveActionTimeoutSec(action, payload, 60);
-    const forceCdp = args.includes('--cdp');
-    const local = forceCdp || args.includes('--local');
-    const connector = optionValue(args, '--connector');
+    const forceCdp = options.cdp === true;
+    const local = forceCdp || options.local === true;
+    const connector = options.connector;
     if (local && connector)
         throw new Error('--local/--cdp 不能与 --connector 同时使用');
     return {
         action,
         payload,
-        timeoutSec: parsePositiveTimeout(optionValue(args, '--timeout'), fallbackTimeout),
-        compact: args.includes('--compact'),
+        timeoutSec: parsePositiveTimeout(options.timeout, fallbackTimeout),
+        ...(options.timeout !== undefined ? { timeoutOption: options.timeout } : {}),
+        compact: options.compact === true,
         forceCdp,
+        json,
         local,
-        ...(optionValue(args, '--output') ? { outputPath: optionValue(args, '--output') } : {}),
-        ...(optionValue(args, '--browser') ? { browser: optionValue(args, '--browser') } : {}),
+        ...(options.output ? { outputPath: options.output } : {}),
+        ...(options.browser ? { browser: options.browser } : {}),
         ...(connector ? { connector } : {}),
-        ...resolveServer(args),
+        ...resolveServer(options.server),
     };
 }
 function screenshotData(action, result) {
@@ -300,19 +302,19 @@ export async function runMearlCli(args, options = {}) {
     }
     let parsed;
     try {
-        parsed = parseArgs(args);
+        parsed = parseClientArgs(args);
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
         return 2;
     }
     if (parsed.action === 'check') {
-        const timeoutSec = parseCheckTimeout(optionValue(args, '--timeout'));
+        const timeoutSec = parseCheckTimeout(parsed.timeoutOption);
         if (timeoutSec === null) {
             console.error('--timeout 必须是正整数秒');
             return 2;
         }
-        const ok = await runUnifiedCheck({
+        const checkOptions = {
             clientVersion,
             timeoutSec,
             ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
@@ -321,8 +323,12 @@ export async function runMearlCli(args, options = {}) {
             ...(parsed.connector ? { connector: parsed.connector } : {}),
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
-        });
-        return ok ? 0 : 1;
+        };
+        if (parsed.json) {
+            const result = await runUnifiedCheck({ ...checkOptions, json: true });
+            return result.ok ? 0 : 1;
+        }
+        return (await runUnifiedCheck(checkOptions)) ? 0 : 1;
     }
     if (parsed.action === 'page_selected_element' && parsed.outputPath) {
         parsed.payload = { ...parsed.payload, includeScreenshot: true };

package/dist/commands.d.ts

@@ -439,10 +439,10 @@ export declare const COMMANDS: readonly [{
         readonly description: "CDP 控制浏览器中用于读取 TDBank Cookie 的标签页";
     }, {
         readonly name: "copyCookieDomains";
-        readonly type: "string[]";
-        readonly description: "从控制浏览器复制到本地新实例或 AgentBay 新建/复用实例的 Cookie 域名列表，可与本地 TDBank 登录组合";
+        readonly type: "string[] | \"mearl-services\"";
+        readonly description: "从控制浏览器复制 Cookie：传域名数组，或传 mearl-services 同步 Mearl 依赖平台登录态";
     }];
-    readonly examples: ["browser_launch --payload '{\"name\":\"cloud-a\",\"provider\":\"agentbay\",\"userAgentMode\":\"desktop\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-public\",\"provider\":\"agentbay\",\"imageId\":\"browser_latest\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"persistent\":true,\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"reuse\":\"require\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"account-a\",\"headless\":true,\"accountId\":12345}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"account-b\",\"query\":\"test_account\",\"url\":\"https://www.taobao.com\"}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
+    readonly examples: ["browser_launch --payload '{\"name\":\"cloud-a\",\"provider\":\"agentbay\",\"userAgentMode\":\"desktop\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-public\",\"provider\":\"agentbay\",\"imageId\":\"browser_latest\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"persistent\":true,\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"reuse\":\"require\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "browser_launch --payload '{\"name\":\"account-a\",\"headless\":true,\"accountId\":12345}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"account-b\",\"query\":\"test_account\",\"url\":\"https://www.taobao.com\"}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
 }, {
     readonly name: "browser_close";
     readonly description: "关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context";
@@ -502,8 +502,20 @@ export declare const COMMANDS: readonly [{
         readonly name: "appProfile";
         readonly type: "string";
         readonly description: "开 tab 即进入 App 容器模拟态（客户端 UA + JSBridge 托管 + iframe 容器栈 + 自适应系统标题栏，首屏即容器态）。系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；档案名同 set_app_profile，如 \"fliggy\"";
+    }, {
+        readonly name: "os";
+        readonly type: "\"ios\" | \"android\"";
+        readonly description: "与 appProfile 配合；容器系统，默认 ios";
+    }, {
+        readonly name: "simulateSystemBars";
+        readonly type: "boolean";
+        readonly description: "与 appProfile 配合；是否模拟顶部状态/导航栏与底部手势栏，默认 true";
+    }, {
+        readonly name: "bridgeConfig";
+        readonly type: "object";
+        readonly description: "与 appProfile 配合；声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}";
     }];
-    readonly examples: ["tab_open --payload '{\"url\":\"https://example.com\"}'", "tab_open --payload '{\"url\":\"https://example.com/page\",\"reuse\":\"prefer\",\"match\":{\"ignoreSearch\":true}}'", "tab_open --payload '{\"url\":\"https://m.example.com\",\"emulation\":{\"preset\":\"iphone-15-pro\"}}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"group\":\"验证任务\"}'"];
+    readonly examples: ["tab_open --payload '{\"url\":\"https://example.com\"}'", "tab_open --payload '{\"url\":\"https://example.com/page\",\"reuse\":\"prefer\",\"match\":{\"ignoreSearch\":true}}'", "tab_open --payload '{\"url\":\"https://m.example.com\",\"emulation\":{\"preset\":\"iphone-15-pro\"}}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"appProfile\":\"fliggy\",\"os\":\"android\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"group\":\"验证任务\"}'"];
 }, {
     readonly name: "tab_close";
     readonly description: "关闭指定标签页";
@@ -534,7 +546,15 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "point";
         readonly type: "{ x: number; y: number }";
-        readonly description: "按视口坐标点击（CSS 像素）。selector/text 都不适用的兜底场景";
+        readonly description: "按视口坐标点击（CSS 像素）。默认使用 outer-viewport；容器或 iframe 内坐标配合 coordinateSpace: \"active-frame\"";
+    }, {
+        readonly name: "frameId";
+        readonly type: "string";
+        readonly description: "浏览器扩展后端：显式指定 CSS/text 查询或 active-frame 坐标所属的 frame；省略时容器模式自动使用当前业务 frame";
+    }, {
+        readonly name: "coordinateSpace";
+        readonly type: "\"outer-viewport\" | \"active-frame\"";
+        readonly description: "仅配合 point 使用；默认 outer-viewport；浏览器扩展后端的 active-frame 会换算 iframe 偏移与缩放后派发可信输入";
     }, {
         readonly name: "role";
         readonly type: "string";
@@ -557,7 +577,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_click --payload '{\"text\":\"提交\"}'", "page_click --payload '{\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"selector\":\"@e3\"}'", "page_click --payload '{\"selector\":\".submit-btn\"}'", "page_click --payload '{\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"point\":{\"x\":336,\"y\":117}}'"];
+    readonly examples: ["page_click --payload '{\"text\":\"提交\"}'", "page_click --payload '{\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"selector\":\"@e3\"}'", "page_click --payload '{\"selector\":\".submit-btn\"}'", "page_click --payload '{\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"point\":{\"x\":336,\"y\":117}}'", "page_click --payload '{\"point\":{\"x\":196,\"y\":240},\"coordinateSpace\":\"active-frame\"}'"];
 }, {
     readonly name: "page_drag";
     readonly description: "拖动页面元素或视口坐标，适用于轮播图、滑块和拖放";
@@ -952,10 +972,18 @@ export declare const COMMANDS: readonly [{
         readonly name: "deviceModel";
         readonly type: "string";
         readonly description: "Android 机型名（拼入 UA 与 __DEVICE_MODEL__）";
+    }, {
+        readonly name: "simulateSystemBars";
+        readonly type: "boolean";
+        readonly description: "是否模拟顶部状态/导航栏与底部手势栏，默认 true";
     }, {
         readonly name: "emulation";
         readonly type: "object";
         readonly description: "覆盖档案推荐的设备模拟参数，字段同 set_device_emulation 去掉 enabled";
+    }, {
+        readonly name: "bridgeConfig";
+        readonly type: "object";
+        readonly description: "声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本";
     }, {
         readonly name: "reload";
         readonly type: "boolean";
@@ -966,7 +994,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\"}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"alipay\",\"os\":\"android\",\"deviceModel\":\"Pixel 8 Pro\"}'", "set_app_profile --payload '{\"enabled\":false}'"];
+    readonly examples: ["set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\"}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\",\"simulateSystemBars\":false}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"alipay\",\"os\":\"android\",\"deviceModel\":\"Pixel 8 Pro\"}'", "set_app_profile --payload '{\"enabled\":false}'"];
 }, {
     readonly name: "set_timezone";
     readonly description: "覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区";

package/dist/commands.js

@@ -325,8 +325,8 @@ export const COMMANDS = [
             },
             {
                 name: 'copyCookieDomains',
-                type: 'string[]',
-                description: '从控制浏览器复制到本地新实例或 AgentBay 新建/复用实例的 Cookie 域名列表，可与本地 TDBank 登录组合',
+                type: 'string[] | "mearl-services"',
+                description: '从控制浏览器复制 Cookie：传域名数组，或传 mearl-services 同步 Mearl 依赖平台登录态',
             },
         ],
         examples: [
@@ -334,6 +334,7 @@ export const COMMANDS = [
             `browser_launch --payload '{"name":"cloud-public","provider":"agentbay","imageId":"browser_latest","url":"https://example.com"}'`,
             `browser_launch --payload '{"name":"cloud-login","provider":"agentbay","persistent":true,"copyCookieDomains":["example.com"],"url":"https://example.com/account"}'`,
             `browser_launch --payload '{"name":"cloud-login","provider":"agentbay","reuse":"require","copyCookieDomains":["example.com"]}'`,
+            `browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":"mearl-services"}'`,
             `browser_launch --payload '{"name":"account-a","headless":true,"accountId":12345}'`,
             `browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'`,
             `browser_launch --payload '{"name":"account-b","query":"test_account","url":"https://www.taobao.com"}'`,
@@ -410,12 +411,28 @@ export const COMMANDS = [
                 type: 'string',
                 description: '开 tab 即进入 App 容器模拟态（客户端 UA + JSBridge 托管 + iframe 容器栈 + 自适应系统标题栏，首屏即容器态）。系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；档案名同 set_app_profile，如 "fliggy"',
             },
+            {
+                name: 'os',
+                type: '"ios" | "android"',
+                description: '与 appProfile 配合；容器系统，默认 ios',
+            },
+            {
+                name: 'simulateSystemBars',
+                type: 'boolean',
+                description: '与 appProfile 配合；是否模拟顶部状态/导航栏与底部手势栏，默认 true',
+            },
+            {
+                name: 'bridgeConfig',
+                type: 'object',
+                description: '与 appProfile 配合；声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}',
+            },
         ],
         examples: [
             `tab_open --payload '{"url":"https://example.com"}'`,
             `tab_open --payload '{"url":"https://example.com/page","reuse":"prefer","match":{"ignoreSearch":true}}'`,
             `tab_open --payload '{"url":"https://m.example.com","emulation":{"preset":"iphone-15-pro"}}'`,
             `tab_open --payload '{"url":"https://market.m.taobao.com/app/trip/rx-home/pages/home","appProfile":"fliggy"}'`,
+            `tab_open --payload '{"url":"https://example.com","appProfile":"fliggy","os":"android"}'`,
             `tab_open --payload '{"url":"https://example.com","group":"验证任务"}'`,
         ],
     },
@@ -450,7 +467,17 @@ export const COMMANDS = [
             {
                 name: 'point',
                 type: '{ x: number; y: number }',
-                description: '按视口坐标点击（CSS 像素）。selector/text 都不适用的兜底场景',
+                description: '按视口坐标点击（CSS 像素）。默认使用 outer-viewport；容器或 iframe 内坐标配合 coordinateSpace: "active-frame"',
+            },
+            {
+                name: 'frameId',
+                type: 'string',
+                description: '浏览器扩展后端：显式指定 CSS/text 查询或 active-frame 坐标所属的 frame；省略时容器模式自动使用当前业务 frame',
+            },
+            {
+                name: 'coordinateSpace',
+                type: '"outer-viewport" | "active-frame"',
+                description: '仅配合 point 使用；默认 outer-viewport；浏览器扩展后端的 active-frame 会换算 iframe 偏移与缩放后派发可信输入',
             },
             {
                 name: 'role',
@@ -484,6 +511,7 @@ export const COMMANDS = [
             `page_click --payload '{"selector":".submit-btn"}'`,
             `page_click --payload '{"selector":".gesture-btn","clickMode":"touch"}'`,
             `page_click --payload '{"point":{"x":336,"y":117}}'`,
+            `page_click --payload '{"point":{"x":196,"y":240},"coordinateSpace":"active-frame"}'`,
         ],
     },
     {
@@ -849,16 +877,27 @@ export const COMMANDS = [
                 type: 'string',
                 description: 'Android 机型名（拼入 UA 与 __DEVICE_MODEL__）',
             },
+            {
+                name: 'simulateSystemBars',
+                type: 'boolean',
+                description: '是否模拟顶部状态/导航栏与底部手势栏，默认 true',
+            },
             {
                 name: 'emulation',
                 type: 'object',
                 description: '覆盖档案推荐的设备模拟参数，字段同 set_device_emulation 去掉 enabled',
             },
+            {
+                name: 'bridgeConfig',
+                type: 'object',
+                description: '声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本',
+            },
             { name: 'reload', type: 'boolean', description: '应用/清除后是否重载页面，默认 true' },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
             `set_app_profile --payload '{"enabled":true,"profile":"fliggy"}'`,
+            `set_app_profile --payload '{"enabled":true,"profile":"fliggy","simulateSystemBars":false}'`,
             `set_app_profile --payload '{"enabled":true,"profile":"alipay","os":"android","deviceModel":"Pixel 8 Pro"}'`,
             `set_app_profile --payload '{"enabled":false}'`,
         ],

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

@@ -219,8 +219,8 @@ export interface BrowserLaunchParams {
     site?: string | number;
     query?: string;
     tabId?: number;
-    /** Copy matching cookies from the selected control browser into a new or reused instance. */
-    copyCookieDomains?: string[];
+    /** Copy explicit domains or the fixed Mearl-service preset from the control browser. */
+    copyCookieDomains?: string[] | 'mearl-services';
 }
 export interface BrowserCloseParams {
     browser: string;
@@ -271,6 +271,18 @@ export interface BrowserEmulationOptions {
     orientation?: 'portrait' | 'landscape';
     touch?: boolean;
 }
+export type AppBridgeConfigBehavior = 'navigate' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'networkInfo' | 'geolocation' | 'permission' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest';
+/** 单个桥方法的声明式覆盖；行为、固定回包、成功空实现三选一。 */
+export interface AppBridgeMethodConfig {
+    behavior?: AppBridgeConfigBehavior;
+    response?: unknown;
+    noop?: boolean;
+    silent?: boolean;
+}
+/** 追加或覆盖 App 档案中的桥方法。配置保持 JSON 可序列化，不执行配置提供的代码。 */
+export interface AppBridgeConfig {
+    methods: Record<string, AppBridgeMethodConfig>;
+}
 export interface TabOpenParams {
     url: string;
     active?: boolean;
@@ -293,6 +305,12 @@ export interface TabOpenParams {
      * 并根据页面协议与桥调用切换普通、沉浸或隐藏状态。可用档案见 APP_PROFILE_NAMES。
      */
     appProfile?: AppProfileName;
+    /** 与 appProfile 配合使用；容器系统，默认 ios */
+    os?: 'ios' | 'android';
+    /** 与 appProfile 配合使用；是否模拟顶部状态/导航栏与底部手势栏，默认 true */
+    simulateSystemBars?: boolean;
+    /** 与 appProfile 配合使用；按方法覆盖档案内置桥配置 */
+    bridgeConfig?: AppBridgeConfig;
 }
 /**
  * 客户端容器模拟可用档案名。
@@ -313,6 +331,10 @@ export interface SetAppProfileParams {
     os?: 'ios' | 'android';
     appVersion?: string;
     deviceModel?: string;
+    /** 是否模拟顶部状态/导航栏与底部手势栏，默认 true */
+    simulateSystemBars?: boolean;
+    /** 按方法覆盖档案内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现 */
+    bridgeConfig?: AppBridgeConfig;
     /** 覆盖档案推荐的设备模拟参数（视口/UA 默认取档案值） */
     emulation?: BrowserEmulationOptions;
     /** 默认 true：应用/清除后刷新页面使注入生效 */
@@ -344,6 +366,10 @@ export interface PageClickParams {
         x: number;
         y: number;
     };
+    /** CSS/text 查询的目标 frame；省略时容器模式自动使用当前业务 frame。 */
+    frameId?: string;
+    /** point 的坐标空间；默认 outer-viewport 以保持兼容。 */
+    coordinateSpace?: 'outer-viewport' | 'active-frame';
     role?: string;
     exact?: boolean;
     scope?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -45,13 +45,17 @@
     "socket-client"
   ],
   "license": "ISC",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.8.1"
+    "@mearl/cloud-types": "2.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",