@mearl/client 2.8.0 → 2.8.2

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

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.js

@@ -81,6 +81,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',
@@ -192,7 +193,7 @@ function validateOptions(args) {
         '--connector',
         '--server',
     ]);
-    const flags = new Set(['--compact', '--local', '--cdp', '--help', '-h']);
+    const flags = new Set(['--compact', '--json', '--local', '--cdp', '--help', '-h']);
     for (let index = 1; index < args.length; index += 1) {
         const arg = args[index];
         if (optionsWithValues.has(arg)) {
@@ -222,6 +223,9 @@ function resolveServer(args) {
 function parseArgs(args) {
     validateOptions(args);
     const action = args[0];
+    const json = args.includes('--json');
+    if (json && action !== 'check')
+        throw new Error('--json 仅适用于 check');
     const payload = parsePayload(args);
     const fallbackTimeout = resolveActionTimeoutSec(action, payload, 60);
     const forceCdp = args.includes('--cdp');
@@ -235,6 +239,7 @@ function parseArgs(args) {
         timeoutSec: parsePositiveTimeout(optionValue(args, '--timeout'), fallbackTimeout),
         compact: args.includes('--compact'),
         forceCdp,
+        json,
         local,
         ...(optionValue(args, '--output') ? { outputPath: optionValue(args, '--output') } : {}),
         ...(optionValue(args, '--browser') ? { browser: optionValue(args, '--browser') } : {}),
@@ -312,7 +317,7 @@ export async function runMearlCli(args, options = {}) {
             console.error('--timeout 必须是正整数秒');
             return 2;
         }
-        const ok = await runUnifiedCheck({
+        const checkOptions = {
             clientVersion,
             timeoutSec,
             ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
@@ -321,8 +326,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

@@ -501,9 +501,17 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "appProfile";
         readonly type: "string";
-        readonly description: "开 tab 即进入 App 容器模拟态（客户端 UA + JSBridge 托管 + iframe 容器栈，首屏即容器态）。档案名同 set_app_profile，如 \"fliggy\"";
+        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 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: "关闭指定标签页";
@@ -930,7 +938,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["set_device_emulation --payload '{\"enabled\":true,\"preset\":\"iphone-15-pro\"}'", "set_device_emulation --payload '{\"enabled\":true,\"preset\":\"pixel-8\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"enabled\":false}'"];
 }, {
     readonly name: "set_app_profile";
-    readonly description: "把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射），用于桌面浏览器近似实机验证 App 内 H5；需保持调试控制才持续生效";
+    readonly description: "把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射 + 自适应系统标题栏），系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；用于桌面浏览器近似实机验证 App 内 H5，需保持调试控制才持续生效";
     readonly params: [{
         readonly name: "enabled";
         readonly type: "boolean";
@@ -952,6 +960,10 @@ 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";
@@ -966,7 +978,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

@@ -408,7 +408,17 @@ export const COMMANDS = [
             {
                 name: 'appProfile',
                 type: 'string',
-                description: '开 tab 即进入 App 容器模拟态（客户端 UA + JSBridge 托管 + iframe 容器栈，首屏即容器态）。档案名同 set_app_profile，如 "fliggy"',
+                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',
             },
         ],
         examples: [
@@ -416,6 +426,7 @@ export const COMMANDS = [
             `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":"验证任务"}'`,
         ],
     },
@@ -834,7 +845,7 @@ export const COMMANDS = [
     },
     {
         name: 'set_app_profile',
-        description: '把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射），用于桌面浏览器近似实机验证 App 内 H5；需保持调试控制才持续生效',
+        description: '把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射 + 自适应系统标题栏），系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；用于桌面浏览器近似实机验证 App 内 H5，需保持调试控制才持续生效',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
             {
@@ -849,6 +860,11 @@ export const COMMANDS = [
                 type: 'string',
                 description: 'Android 机型名（拼入 UA 与 __DEVICE_MODEL__）',
             },
+            {
+                name: 'simulateSystemBars',
+                type: 'boolean',
+                description: '是否模拟顶部状态/导航栏与底部手势栏，默认 true',
+            },
             {
                 name: 'emulation',
                 type: 'object',
@@ -859,6 +875,7 @@ export const COMMANDS = [
         ],
         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

@@ -289,9 +289,14 @@ export interface TabOpenParams {
     group?: string;
     /**
      * 客户端容器模拟档案名（如 'fliggy'）。打开后即按该 App 的 WebView 环境渲染：
-     * 移动视口 + 容器 UA + JSBridge 托管。可用档案见 APP_PROFILE_NAMES。
+     * 移动视口 + 容器 UA + JSBridge 托管 + 自适应系统标题栏。系统栏由 iframe 外层统一渲染，
+     * 并根据页面协议与桥调用切换普通、沉浸或隐藏状态。可用档案见 APP_PROFILE_NAMES。
      */
     appProfile?: AppProfileName;
+    /** 与 appProfile 配合使用；容器系统，默认 ios */
+    os?: 'ios' | 'android';
+    /** 与 appProfile 配合使用；是否模拟顶部状态/导航栏与底部手势栏，默认 true */
+    simulateSystemBars?: boolean;
 }
 /**
  * 客户端容器模拟可用档案名。
@@ -312,6 +317,8 @@ export interface SetAppProfileParams {
     os?: 'ios' | 'android';
     appVersion?: string;
     deviceModel?: string;
+    /** 是否模拟顶部状态/导航栏与底部手势栏，默认 true */
+    simulateSystemBars?: boolean;
     /** 覆盖档案推荐的设备模拟参数（视口/UA 默认取档案值） */
     emulation?: BrowserEmulationOptions;
     /** 默认 true：应用/清除后刷新页面使注入生效 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -51,7 +51,7 @@
   "dependencies": {
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.8.0"
+    "@mearl/cloud-types": "2.8.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",