@mearl/client 2.9.6 → 2.10.0

package/README.md

@@ -122,7 +122,7 @@ mearl browser_release
 
 `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 写入目标，传 `"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)。
+托管浏览器使用独立 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` 仅返回浏览器的稳定配置，不携带 AgentBay 串流入口或沙箱 noVNC 地址。需要时显式运行 `mearl check --browser <id|名称>`，由统一的浏览器访问入口能力实时返回 `browserAccess`；AgentBay、OpenSandbox 和 AONE Sandbox 地址都应按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 
 ## 架构
 

package/dist/check.d.ts

@@ -5,6 +5,16 @@ export interface UnifiedCheckVersions {
     extension?: string | null;
     browser?: string | null;
 }
+export type BrowserAccessCapability = {
+    kind: 'agentbay';
+} | {
+    kind: 'sandbox-novnc';
+    environment: 'opensandbox' | 'aone';
+    port: number;
+};
+export type BrowserAccess = BrowserAccessCapability & {
+    url: string;
+};
 interface BrowserInfo {
     browserId: string;
     extensionVersion?: string;
@@ -27,7 +37,7 @@ export interface ExtensionInstallationInfo {
     setupManagedPath: string | null;
 }
 export interface UnifiedCheckBrowserResult extends BrowserInfo {
-    agentbayAccessUrl?: string;
+    browserAccess?: BrowserAccess;
     check?: {
         errors?: string[];
         label: string;

package/dist/check.js

@@ -2,6 +2,20 @@ import { UnifiedClient, normalizeBrowserSelector, } from './unified.js';
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function browserAccessLabel(access) {
+    if (access.kind === 'agentbay')
+        return 'AgentBay, temporary';
+    return access.environment === 'opensandbox' ? 'OpenSandbox noVNC' : 'AONE Sandbox noVNC';
+}
+async function getBrowserAccess(client, browser, capability, timeoutSec) {
+    const result = (await client.invoke('get_browser_access_url', {}, { timeoutSec, browser: browser.browserId }));
+    if (!result.browserAccess?.url)
+        throw new Error('Browser host did not return an access URL');
+    if (result.browserAccess.kind !== capability.kind) {
+        throw new Error('Browser host returned an unexpected access URL type');
+    }
+    return result.browserAccess;
+}
 function redactServerUrl(serverUrl) {
     try {
         const parsed = new URL(serverUrl);
@@ -223,33 +237,27 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                         setupManagedPath: versions.setupManagedPath,
                     };
                 }
-                let agentbayAccessUrl;
+                let browserAccess;
                 let accessUrlWarning;
-                if (browser.provider === 'agentbay' && options.browser) {
+                const browserAccessCapability = versions.browserAccess;
+                if (browserAccessCapability && options.browser) {
                     try {
-                        const access = (await client.invoke('get_agentbay_access_url', {}, {
-                            timeoutSec,
-                            browser: browser.browserId,
-                        }));
-                        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}`);
+                        browserAccess = await getBrowserAccess(client, browser, browserAccessCapability, timeoutSec);
+                        details.push(`Browser access URL (${browserAccessLabel(browserAccess)}; sensitive): ${browserAccess.url}`);
                     }
                     catch (error) {
                         accessUrlWarning = formatError(error);
-                        details.push(`AgentBay access URL unavailable: ${accessUrlWarning}`);
+                        details.push(`Browser access URL unavailable: ${accessUrlWarning}`);
                     }
                 }
                 browserChecks.push({
-                    ...(agentbayAccessUrl ? { agentbayAccessUrl } : {}),
+                    ...(browserAccess ? { browserAccess } : {}),
                     browser,
                     ...(extensionInstallation ? { extensionInstallation } : {}),
                     item: {
                         status: accessUrlWarning ? 'warning' : 'ok',
                         label: accessUrlWarning
-                            ? 'Browser command path ready; AgentBay access URL unavailable'
+                            ? 'Browser command path ready; browser access URL unavailable'
                             : options.transport === 'cdp'
                                 ? 'CDP command path'
                                 : 'Browser command path',
@@ -293,7 +301,7 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                     return {
                         ...browserIdentity,
                         selected: targets.some(target => target.browserId === browser.browserId),
-                        ...(check?.agentbayAccessUrl ? { agentbayAccessUrl: check.agentbayAccessUrl } : {}),
+                        ...(check?.browserAccess ? { browserAccess: check.browserAccess } : {}),
                         ...(check?.item
                             ? {
                                 check: {

package/dist/commands.d.ts

@@ -509,25 +509,21 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "emulation";
         readonly type: "object";
-        readonly description: "开 tab 即进入移动端模拟态（首屏即移动态、无需 reload）。字段同 set_device_emulation 去掉 enabled，如 {\"preset\":\"iphone-15-pro\"}";
+        readonly description: "开 tab 即进入移动端模拟态（首屏即移动态、无需 reload）。字段同 set_device_emulation 去掉 enabled/reload；deviceShell=true 时页面从首屏起在 iframe WebView 中渲染设备系统外壳";
     }, {
         readonly name: "appProfile";
         readonly type: "string";
-        readonly description: "开 tab 即进入 App 容器模拟态（客户端 UA + JSBridge 托管 + iframe 容器栈 + 自适应系统标题栏，首屏即容器态）。系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；档案名同 set_app_profile，如 \"fliggy\"";
+        readonly description: "开 tab 即注入 App 客户端环境与 JSBridge；档案名同 set_app_profile，如 \"fliggy\"。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
     }, {
         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\",\"appProfile\":\"fliggy\",\"os\":\"android\"}'", "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-17-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: "关闭指定标签页";
@@ -912,7 +908,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["record_stop"];
 }, {
     readonly name: "set_device_emulation";
-    readonly description: "把目标 tab 切换为移动端模拟（视口/UA/触摸），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效";
+    readonly description: "把目标 tab 切换为移动端模拟（视口/DPR/UA/触摸/视觉比例），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效";
     readonly summary: "设置或清除目标标签页的设备模拟";
     readonly params: [{
         readonly name: "enabled";
@@ -921,8 +917,8 @@ export declare const COMMANDS: readonly [{
         readonly description: "true=启用，false=清除";
     }, {
         readonly name: "preset";
-        readonly type: "\"iphone-15-pro\" | \"iphone-se\" | \"pixel-8\" | \"ipad-mini\" | \"galaxy-s23\"";
-        readonly description: "内置设备预设，提供 width/height/DPR/UA 默认值";
+        readonly type: string;
+        readonly description: "内置设备预设，提供 width/height/DPR/UA 默认值；旧机型 ID 继续兼容";
     }, {
         readonly name: "width";
         readonly type: "number";
@@ -935,6 +931,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "deviceScaleFactor";
         readonly type: "number";
         readonly description: "DPR（覆盖 preset）";
+    }, {
+        readonly name: "scale";
+        readonly type: "number";
+        readonly description: "画面视觉比例，不改变视口尺寸或 DPR；必须为有限正数，默认 1";
     }, {
         readonly name: "mobile";
         readonly type: "boolean";
@@ -950,7 +950,11 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "touch";
         readonly type: "boolean";
-        readonly description: "是否启用触摸事件，默认 mobile 为真时启用";
+        readonly description: "是否启用触摸事件，默认从 preset 推断；无 preset 时跟随 mobile";
+    }, {
+        readonly name: "deviceShell";
+        readonly type: "boolean";
+        readonly description: "是否使用 iframe WebView 并渲染顶部状态栏与底部操作区，默认 false";
     }, {
         readonly name: "reload";
         readonly type: "boolean";
@@ -961,10 +965,10 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    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 examples: ["set_device_emulation --payload '{\"enabled\":true,\"preset\":\"iphone-17-pro\"}'", "set_device_emulation --payload '{\"enabled\":true,\"preset\":\"pixel-11\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"enabled\":false}'"];
 }, {
     readonly name: "set_app_profile";
-    readonly description: "把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射 + 自适应系统标题栏），系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；用于桌面浏览器近似实机验证 App 内 H5，需保持调试控制才持续生效";
+    readonly description: "设置 App 客户端环境与 JSBridge；传 emulation 时由同一个命令联动设备模拟，省略时不改变设备状态";
     readonly summary: "设置或清除目标标签页的 App 容器模拟";
     readonly params: [{
         readonly name: "enabled";
@@ -987,18 +991,14 @@ 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: "emulation";
+        readonly type: "object";
+        readonly description: "可选设备联动参数，字段同 set_device_emulation 去掉 enabled/reload；字段覆盖档案推荐设备，deviceShell 默认 true。省略时不设置或清除设备";
     }, {
         readonly name: "reload";
         readonly type: "boolean";
@@ -1009,7 +1009,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\":\"fliggy\",\"simulateSystemBars\":false}'", "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\",\"emulation\":{}}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"alipay\",\"emulation\":{\"preset\":\"pixel-11\",\"deviceShell\":true}}'", "set_app_profile --payload '{\"enabled\":false}'", "set_app_profile --payload '{\"enabled\":false,\"emulation\":{}}'"];
 }, {
     readonly name: "set_timezone";
     readonly description: "覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区";

package/dist/commands.js

@@ -1,6 +1,7 @@
-import { APP_PROFILE_NAMES, } from './generated-browser-action-protocol.js';
+import { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, } from './generated-browser-action-protocol.js';
 /** 容器档案名列表（拼进参数说明，新增档案无需改本文件） */
 const APP_PROFILE_NAME_LIST = APP_PROFILE_NAMES.join('/');
+const DEVICE_PRESET_TYPE = BROWSER_DEVICE_PRESET_NAMES.map(name => JSON.stringify(name)).join(' | ');
 const PAGE_DIAGNOSTICS_PARAM = {
     name: 'diagnostics',
     type: 'object | boolean',
@@ -424,23 +425,18 @@ export const COMMANDS = [
             {
                 name: 'emulation',
                 type: 'object',
-                description: '开 tab 即进入移动端模拟态（首屏即移动态、无需 reload）。字段同 set_device_emulation 去掉 enabled，如 {"preset":"iphone-15-pro"}',
+                description: '开 tab 即进入移动端模拟态（首屏即移动态、无需 reload）。字段同 set_device_emulation 去掉 enabled/reload；deviceShell=true 时页面从首屏起在 iframe WebView 中渲染设备系统外壳',
             },
             {
                 name: 'appProfile',
                 type: 'string',
-                description: '开 tab 即进入 App 容器模拟态（客户端 UA + JSBridge 托管 + iframe 容器栈 + 自适应系统标题栏，首屏即容器态）。系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；档案名同 set_app_profile，如 "fliggy"',
+                description: '开 tab 即注入 App 客户端环境与 JSBridge；档案名同 set_app_profile，如 "fliggy"。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
             },
             {
                 name: 'os',
                 type: '"ios" | "android"',
                 description: '与 appProfile 配合；容器系统，默认 ios',
             },
-            {
-                name: 'simulateSystemBars',
-                type: 'boolean',
-                description: '与 appProfile 配合；是否模拟顶部状态/导航栏与底部手势栏，默认 true',
-            },
             {
                 name: 'bridgeConfig',
                 type: 'object',
@@ -450,7 +446,7 @@ export const COMMANDS = [
         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://m.example.com","emulation":{"preset":"iphone-17-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":"验证任务"}'`,
@@ -853,18 +849,23 @@ export const COMMANDS = [
     // ── 移动端模拟 ────────────────────────────────────────────────────────────
     {
         name: 'set_device_emulation',
-        description: '把目标 tab 切换为移动端模拟（视口/UA/触摸），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效',
+        description: '把目标 tab 切换为移动端模拟（视口/DPR/UA/触摸/视觉比例），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效',
         summary: '设置或清除目标标签页的设备模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
             {
                 name: 'preset',
-                type: '"iphone-15-pro" | "iphone-se" | "pixel-8" | "ipad-mini" | "galaxy-s23"',
-                description: '内置设备预设，提供 width/height/DPR/UA 默认值',
+                type: DEVICE_PRESET_TYPE,
+                description: '内置设备预设，提供 width/height/DPR/UA 默认值；旧机型 ID 继续兼容',
             },
             { name: 'width', type: 'number', description: '视口宽度（覆盖 preset）' },
             { name: 'height', type: 'number', description: '视口高度（覆盖 preset）' },
             { name: 'deviceScaleFactor', type: 'number', description: 'DPR（覆盖 preset）' },
+            {
+                name: 'scale',
+                type: 'number',
+                description: '画面视觉比例，不改变视口尺寸或 DPR；必须为有限正数，默认 1',
+            },
             { name: 'mobile', type: 'boolean', description: '是否走移动渲染模式，默认从 preset 推断' },
             { name: 'userAgent', type: 'string', description: '自定义 UA（覆盖 preset）' },
             {
@@ -872,19 +873,28 @@ export const COMMANDS = [
                 type: '"portrait" | "landscape"',
                 description: '横竖屏，默认 portrait',
             },
-            { name: 'touch', type: 'boolean', description: '是否启用触摸事件，默认 mobile 为真时启用' },
+            {
+                name: 'touch',
+                type: 'boolean',
+                description: '是否启用触摸事件，默认从 preset 推断；无 preset 时跟随 mobile',
+            },
+            {
+                name: 'deviceShell',
+                type: 'boolean',
+                description: '是否使用 iframe WebView 并渲染顶部状态栏与底部操作区，默认 false',
+            },
             { name: 'reload', type: 'boolean', description: '启用后是否重载页面，默认 true' },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         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":true,"preset":"iphone-17-pro"}'`,
+            `set_device_emulation --payload '{"enabled":true,"preset":"pixel-11","orientation":"landscape"}'`,
             `set_device_emulation --payload '{"enabled":false}'`,
         ],
     },
     {
         name: 'set_app_profile',
-        description: '把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射 + 自适应系统标题栏），系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；用于桌面浏览器近似实机验证 App 内 H5，需保持调试控制才持续生效',
+        description: '设置 App 客户端环境与 JSBridge；传 emulation 时由同一个命令联动设备模拟，省略时不改变设备状态',
         summary: '设置或清除目标标签页的 App 容器模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
@@ -901,28 +911,24 @@ export const COMMANDS = [
                 description: 'Android 机型名（拼入 UA 与 __DEVICE_MODEL__）',
             },
             {
-                name: 'simulateSystemBars',
-                type: 'boolean',
-                description: '是否模拟顶部状态/导航栏与底部手势栏，默认 true',
-            },
-            {
-                name: 'emulation',
+                name: 'bridgeConfig',
                 type: 'object',
-                description: '覆盖档案推荐的设备模拟参数，字段同 set_device_emulation 去掉 enabled',
+                description: '声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本',
             },
             {
-                name: 'bridgeConfig',
+                name: 'emulation',
                 type: 'object',
-                description: '声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本',
+                description: '可选设备联动参数，字段同 set_device_emulation 去掉 enabled/reload；字段覆盖档案推荐设备，deviceShell 默认 true。省略时不设置或清除设备',
             },
             { 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":true,"profile":"fliggy","emulation":{}}'`,
+            `set_app_profile --payload '{"enabled":true,"profile":"alipay","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
             `set_app_profile --payload '{"enabled":false}'`,
+            `set_app_profile --payload '{"enabled":false,"emulation":{}}'`,
         ],
     },
     {

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

@@ -262,16 +262,20 @@ export interface PageSelectedElementParams {
     includeOuterHTML?: boolean;
     includeScreenshot?: boolean;
 }
-export type BrowserDevicePresetName = 'iphone-15-pro' | 'iphone-se' | 'pixel-8' | 'ipad-mini' | 'galaxy-s23';
+export declare const BROWSER_DEVICE_PRESET_NAMES: readonly ["iphone-17-pro", "iphone-17e", "pixel-11", "ipad-mini-a17-pro", "galaxy-s26", "pura-x-max", "iphone-15-pro", "iphone-se", "pixel-8", "ipad-mini", "galaxy-s23"];
+export type BrowserDevicePresetName = (typeof BROWSER_DEVICE_PRESET_NAMES)[number];
 export interface BrowserEmulationOptions {
     preset?: BrowserDevicePresetName;
     width?: number;
     height?: number;
     deviceScaleFactor?: number;
+    scale?: number;
     mobile?: boolean;
     userAgent?: string;
     orientation?: 'portrait' | 'landscape';
     touch?: boolean;
+    /** 在 iframe WebView 外渲染设备系统栏；默认 false，保持纯 CDP 设备模拟。 */
+    deviceShell?: boolean;
 }
 export type AppBridgeConfigBehavior = 'navigate' | 'closeAll' | 'closeBackData' | 'postMessage' | 'notifySubscribe' | 'notifyUnsubscribe' | 'notifyPost' | 'sharedFileRead' | 'sharedFileWrite' | 'sharedDataGet' | 'sharedDataSet' | 'legacyBroadcastCreate' | 'legacyBroadcastPost' | 'legacyBroadcastClose' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'networkInfo' | 'geolocation' | 'permission' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest';
 /** 单个桥方法的声明式覆盖；行为、固定回包、成功空实现三选一。 */
@@ -302,15 +306,12 @@ export interface TabOpenParams {
     emulation?: BrowserEmulationOptions;
     group?: string;
     /**
-     * 客户端容器模拟档案名（如 'fliggy'）。打开后即按该 App 的 WebView 环境渲染：
-     * 移动视口 + 容器 UA + JSBridge 托管 + 自适应系统标题栏。系统栏由 iframe 外层统一渲染，
-     * 并根据页面协议与桥调用切换普通、沉浸或隐藏状态。可用档案见 APP_PROFILE_NAMES。
+     * 客户端容器模拟档案名（如 'fliggy'）。只注入容器 UA、环境变量、JSBridge 与桥协议；
+     * 设备视口和 iframe 系统外壳由 emulation.deviceShell 独立控制。可用档案见 APP_PROFILE_NAMES。
      */
     appProfile?: AppProfileName;
     /** 与 appProfile 配合使用；容器系统，默认 ios */
     os?: 'ios' | 'android';
-    /** 与 appProfile 配合使用；是否模拟顶部状态/导航栏与底部手势栏，默认 true */
-    simulateSystemBars?: boolean;
     /** 与 appProfile 配合使用；按方法覆盖档案内置桥配置 */
     bridgeConfig?: AppBridgeConfig;
 }
@@ -333,11 +334,12 @@ export interface SetAppProfileParams {
     os?: 'ios' | 'android';
     appVersion?: string;
     deviceModel?: string;
-    /** 是否模拟顶部状态/导航栏与底部手势栏，默认 true */
-    simulateSystemBars?: boolean;
     /** 按方法覆盖档案内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现 */
     bridgeConfig?: AppBridgeConfig;
-    /** 覆盖档案推荐的设备模拟参数（视口/UA 默认取档案值） */
+    /**
+     * 可选设备联动参数。传入时显式字段覆盖档案推荐设备，空对象使用推荐设备且默认开启
+     * deviceShell；省略时不设置或清除该 tab 的设备状态。
+     */
     emulation?: BrowserEmulationOptions;
     /** 默认 true：应用/清除后刷新页面使注入生效 */
     reload?: boolean;

package/dist/generated-browser-action-protocol.js

@@ -6,6 +6,20 @@ export const SEND_REQUEST_MAX_TOTAL_FILE_BYTES = 40 * 1024 * 1024;
 // Base64 expands by 4/3; 7 MiB leaves roughly 680 KiB for JSON framing under
 // the 10 MiB cloud message limit.
 export const SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES = 7 * 1024 * 1024;
+export const BROWSER_DEVICE_PRESET_NAMES = [
+    'iphone-17-pro',
+    'iphone-17e',
+    'pixel-11',
+    'ipad-mini-a17-pro',
+    'galaxy-s26',
+    'pura-x-max',
+    // 旧名称保留具体机型语义，供已有调用与历史回归基线继续使用。
+    'iphone-15-pro',
+    'iphone-se',
+    'pixel-8',
+    'ipad-mini',
+    'galaxy-s23',
+];
 /**
  * 客户端容器模拟可用档案名。
  *

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
-export { APP_PROFILE_NAMES, BROWSER_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, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_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, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';

package/dist/index.js

@@ -5,7 +5,7 @@
  * then routes actions using the global browser ids returned by browser_list.
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
-export { APP_PROFILE_NAMES, BROWSER_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, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_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, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 import { invoke } from './unified.js';
 export function tabCheckpoint(params = {}, options) {
     return invoke('tab_checkpoint', params, options);

package/package.json

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