@mearl/client 2.9.6 → 2.11.0

package/README.md

@@ -69,7 +69,9 @@ 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 --browser '<本地来源 browserId>' --payload '{"sessionId":"<其他设备创建的 AgentBay sessionId>","copyCookieDomains":["example.com"]}'
 mearl browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":"mearl-services"}'
+mearl browser_launch --payload '{"name":"cloud-tools-plus","provider":"agentbay","copyCookieDomains":{"presets":["mearl-services"],"domains":["figma.com"]}}'
 mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
 mearl browser_list
 mearl browser_release
@@ -120,9 +122,9 @@ mearl browser_release
 
 `browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
 
-`browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时使用，不作为普通任务收尾。它会释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。
+按 `sessionId` 接入的 AgentBay 浏览器用 `browser_release` 收尾：它会移除本机 attachment 并退出对应宿主，但不会关闭云端 Session。其他浏览器仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放 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` 只复用且不会意外创建计费会话。另一台设备已知确切 Session 时，可传 `sessionId` 直接通过 AgentBay CDP 接入，不需要 cloud-server；当前设备需配置能访问该 Session 的 `AGENTBAY_KEY`。provider-local ID 为 `managed:agentbay:session:<sessionId>`，跨 CLI 调用使用启动响应中的全局 `browserId`，且本机只持有 attachment。`copyCookieDomains` 传数组时复制指定域，传 `"mearl-services"` 时同步 Mearl 依赖平台登录态；需要同时复制基础登录态和额外站点时传 `{ "presets": ["mearl-services"], "domains": [...] }`。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

@@ -386,21 +386,24 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["browser_list"];
 }, {
     readonly name: "browser_release";
-    readonly description: "按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），保留浏览器和全部标签页；不用于普通任务收尾";
-    readonly summary: "释放浏览器调试控制及会话级临时效果";
+    readonly description: "sessionId 接入的 AgentBay 浏览器用它解除本机 attachment且不关闭云端 Session；其他浏览器仅按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），不用于普通任务收尾";
+    readonly summary: "释放浏览器控制或解除 Session attachment";
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
-    readonly description: "启动本地 Chrome，或创建/显式复用 AgentBay 云浏览器，并通过 CDP 接入 Mearl";
+    readonly description: "启动本地 Chrome、创建/复用同名 AgentBay 云浏览器，或用 sessionId 接入现有云端 Session";
     readonly params: [{
         readonly name: "name";
         readonly type: "string";
-        readonly required: true;
-        readonly description: "实例名称，最多 64 个字符";
+        readonly description: "实例名称，创建浏览器时必填；按 sessionId 接入时可省略";
     }, {
         readonly name: "provider";
         readonly type: "\"local\" | \"agentbay\"";
-        readonly description: "运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器";
+        readonly description: "运行环境，默认 local；传 sessionId 时自动使用 agentbay，否则 agentbay 从 AGENTBAY_KEY 创建云浏览器";
+    }, {
+        readonly name: "sessionId";
+        readonly type: "string";
+        readonly description: "显式接入现有 AgentBay Session；不会创建、初始化或取得其生命周期所有权";
     }, {
         readonly name: "reuse";
         readonly type: "\"never\" | \"prefer\" | \"require\"";
@@ -451,10 +454,10 @@ export declare const COMMANDS: readonly [{
         readonly description: "CDP 控制浏览器中用于读取 TDBank Cookie 的标签页";
     }, {
         readonly name: "copyCookieDomains";
-        readonly type: "string[] | \"mearl-services\"";
-        readonly description: "从控制浏览器复制 Cookie：传域名数组，或传 mearl-services 同步 Mearl 依赖平台登录态";
+        readonly type: "string[] | \"mearl-services\" | { presets?: [\"mearl-services\"]; domains?: string[] }";
+        readonly description: "从控制浏览器复制 Cookie：可传域名数组、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\":\"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 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 --browser '<本地浏览器 browserId>' --payload '{\"sessionId\":\"<AgentBay sessionId>\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":{\"presets\":[\"mearl-services\"],\"domains\":[\"figma.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 name: "browser_close";
     readonly description: "关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context";
@@ -509,25 +512,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 +911,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 +920,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 +934,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 +953,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 +968,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 +994,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 +1012,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',
@@ -289,19 +290,28 @@ export const COMMANDS = [
     },
     {
         name: 'browser_release',
-        description: '按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），保留浏览器和全部标签页；不用于普通任务收尾',
-        summary: '释放浏览器调试控制及会话级临时效果',
+        description: 'sessionId 接入的 AgentBay 浏览器用它解除本机 attachment且不关闭云端 Session；其他浏览器仅按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），不用于普通任务收尾',
+        summary: '释放浏览器控制或解除 Session attachment',
         examples: ['browser_release', 'browser_release --browser chrome-a'],
     },
     {
         name: 'browser_launch',
-        description: '启动本地 Chrome，或创建/显式复用 AgentBay 云浏览器，并通过 CDP 接入 Mearl',
+        description: '启动本地 Chrome、创建/复用同名 AgentBay 云浏览器，或用 sessionId 接入现有云端 Session',
         params: [
-            { name: 'name', type: 'string', required: true, description: '实例名称，最多 64 个字符' },
+            {
+                name: 'name',
+                type: 'string',
+                description: '实例名称，创建浏览器时必填；按 sessionId 接入时可省略',
+            },
             {
                 name: 'provider',
                 type: '"local" | "agentbay"',
-                description: '运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器',
+                description: '运行环境，默认 local；传 sessionId 时自动使用 agentbay，否则 agentbay 从 AGENTBAY_KEY 创建云浏览器',
+            },
+            {
+                name: 'sessionId',
+                type: 'string',
+                description: '显式接入现有 AgentBay Session；不会创建、初始化或取得其生命周期所有权',
             },
             {
                 name: 'reuse',
@@ -345,8 +355,8 @@ export const COMMANDS = [
             },
             {
                 name: 'copyCookieDomains',
-                type: 'string[] | "mearl-services"',
-                description: '从控制浏览器复制 Cookie：传域名数组，或传 mearl-services 同步 Mearl 依赖平台登录态',
+                type: 'string[] | "mearl-services" | { presets?: ["mearl-services"]; domains?: string[] }',
+                description: '从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名',
             },
         ],
         examples: [
@@ -354,7 +364,9 @@ 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 --browser '<本地浏览器 browserId>' --payload '{"sessionId":"<AgentBay sessionId>","copyCookieDomains":["example.com"]}'`,
             `browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":"mearl-services"}'`,
+            `browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":{"presets":["mearl-services"],"domains":["figma.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"}'`,
@@ -424,23 +436,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 +457,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 +860,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 +884,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 +922,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

@@ -157,6 +157,8 @@ export interface ManagedBrowserInfo extends BrowserInfoBase {
     persistent: boolean;
     cdpPort?: number;
     agentbaySessionId?: string;
+    /** Whether this host owns the AgentBay session lifecycle or only attaches to it. */
+    agentbaySessionMode?: 'owned' | 'attached';
     /** AgentBay image used to create the session. */
     agentbayImageId?: string;
     /** Persistent AgentBay browser context ID when enabled for this instance. */
@@ -199,12 +201,26 @@ export interface BrowserReleaseResult {
     hadActiveControl: boolean;
     transports: Array<'extension' | 'cdp'>;
     affectedTabIds: number[];
+    /** True when browser_release also removed a sessionId-based local AgentBay attachment. */
+    detached?: boolean;
+    /** Attached sessions remain alive in AgentBay after the local attachment is released. */
+    sessionClosed?: boolean;
+    agentbaySessionId?: string;
     failures?: BrowserReleaseFailure[];
 }
+export interface CookieCopyScope {
+    /** Maintained authentication-domain presets to include. */
+    presets?: Array<'mearl-services'>;
+    /** Additional domains or URLs to copy alongside the selected presets. */
+    domains?: string[];
+}
 export interface BrowserLaunchParams {
-    name: string;
-    /** Browser runtime provider. Defaults to local Chrome. */
+    /** Required when creating a browser; optional when attaching by AgentBay sessionId. */
+    name?: string;
+    /** Browser runtime provider. Defaults to local Chrome unless sessionId is present. */
     provider?: 'local' | 'agentbay';
+    /** Attach to an exact live AgentBay session without creating or owning it. */
+    sessionId?: string;
     /** AgentBay running-session reuse policy. Defaults to never. */
     reuse?: 'never' | 'prefer' | 'require';
     /** AgentBay image alias or concrete image ID. Only supported by the AgentBay provider. */
@@ -221,8 +237,8 @@ export interface BrowserLaunchParams {
     site?: string | number;
     query?: string;
     tabId?: number;
-    /** Copy explicit domains or the fixed Mearl-service preset from the control browser. */
-    copyCookieDomains?: string[] | 'mearl-services';
+    /** Copy explicit domains, the Mearl-service preset, or a combination of both. */
+    copyCookieDomains?: string[] | 'mearl-services' | CookieCopyScope;
 }
 export interface BrowserCloseParams {
     browser: string;
@@ -262,16 +278,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 +322,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 +350,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/dist/socket.js

@@ -11,6 +11,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { StringDecoder } from 'node:string_decoder';
 import { resolveFileRefs } from './fileRefs.js';
 import { listLiveBrowsers, findBrowser, describeBrowser } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
@@ -255,6 +256,7 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSour
         const socket = net.createConnection(socketPath);
         let settled = false;
         let buffer = '';
+        const decoder = new StringDecoder('utf8');
         const settle = (error, result) => {
             if (settled)
                 return;
@@ -283,7 +285,7 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSour
             socket.write(JSON.stringify(message) + '\n');
         });
         socket.on('data', chunk => {
-            buffer += chunk.toString('utf-8');
+            buffer += decoder.write(chunk);
             if (Buffer.byteLength(buffer, 'utf-8') > MAX_SOCKET_BUFFER_SIZE) {
                 settle(new Error(`Socket 响应超过 ${MAX_SOCKET_BUFFER_SIZE} 字节限制`));
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.9.6",
+  "version": "2.11.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.11.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",