@mearl/client 2.10.0 → 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` 仅返回浏览器的稳定配置，不携带 AgentBay 串流入口或沙箱 noVNC 地址。需要时显式运行 `mearl check --browser <id|名称>`，由统一的浏览器访问入口能力实时返回 `browserAccess`；AgentBay、OpenSandbox 和 AONE Sandbox 地址都应按敏感信息处理。完整设计见 [托管浏览器与 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/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";

package/dist/commands.js

@@ -290,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',
@@ -346,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: [
@@ -355,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"}'`,

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;

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.10.0",
+  "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.10.0"
+    "@mearl/cloud-types": "2.11.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",