@mearl/client - npm Package Compare versions

Comparing version 2.4.0 to 2.5.0

dist/browserRegistry.js

@@ -71,5 +71,10 @@ /**
         return byId;
-    const byExactName = browsers.find(b => b.browserName.toLowerCase() === sel);
-    if (byExactName)
-        return byExactName;
+    const exactNameMatches = browsers.filter(b => b.browserName.toLowerCase() === sel);
+    if (exactNameMatches.length > 1) {
+        throw new Error(`Browser name "${selector.trim()}" is ambiguous. Use a full browserId: ${exactNameMatches
+            .map(browser => browser.browserId)
+            .join(', ')}`);
+    }
+    if (exactNameMatches[0])
+        return exactNameMatches[0];
     return (browsers.find(b => b.browserId.toLowerCase().includes(sel) || b.browserName.toLowerCase().includes(sel)) ?? null);
@@ -76,0 +81,0 @@ }

dist/commands.d.ts

@@ -297,3 +297,3 @@ import type { BrowserCommandAction } from './generated-browser-action-protocol.js';
     readonly name: "browser_list";
-    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息";
+    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含 agentbayImageId 和 agentbayAccessUrl";
     readonly examples: ["browser_list"];
@@ -306,3 +306,3 @@ }, {
     readonly name: "browser_launch";
-    readonly description: "启动独立 Chrome，可在新实例中通过 TDBank 登录指定账号";
+    readonly description: "启动本地 Chrome 或 AgentBay 云浏览器，并通过 CDP 接入 Mearl";
     readonly params: [{
@@ -314,9 +314,17 @@ readonly name: "name";
     }, {
+        readonly name: "provider";
+        readonly type: "\"local\" | \"agentbay\"";
+        readonly description: "运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器";
+    }, {
+        readonly name: "imageId";
+        readonly type: "string";
+        readonly description: "AgentBay 镜像别名或具体镜像 ID；默认使用已验证的 Linux Browser Use 内网镜像";
+    }, {
         readonly name: "headless";
         readonly type: "boolean";
-        readonly description: "是否无头运行，默认 true";
+        readonly description: "本地 provider 是否无头运行，默认 true；AgentBay 固定为 false，不支持 true";
     }, {
         readonly name: "userAgentMode";
         readonly type: "\"default\" | \"desktop\"";
-        readonly description: "UA 模式：default 使用 Chrome 默认 UA，desktop 使用匹配本机版本的桌面 UA";
+        readonly description: "UA 模式：default 使用 provider 默认 UA；desktop 本地使用匹配本机版本的 UA，AgentBay 复用控制浏览器的桌面 UA";
     }, {
@@ -357,5 +365,5 @@ readonly name: "persistent";
         readonly type: "string[]";
-        readonly description: "从控制浏览器复制到新实例的 Cookie 域名列表，可与 TDBank 登录组合";
+        readonly description: "从控制浏览器复制到本地或 AgentBay 新实例的 Cookie 域名列表，可与本地 TDBank 登录组合";
     }];
-    readonly examples: ["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\",\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "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\"]}'"];
 }, {
@@ -374,3 +382,3 @@ readonly name: "browser_close";
     }];
-    readonly examples: ["browser_close --payload '{\"browser\":\"managed:account-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
+    readonly examples: ["browser_close --payload '{\"browser\":\"managed:account-a\"}'", "browser_close --payload '{\"browser\":\"managed:agentbay:cloud-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
 }, {
@@ -377,0 +385,0 @@ readonly name: "tab_open";

dist/commands.js

@@ -213,3 +213,3 @@ const PAGE_DIAGNOSTICS_PARAM = {
         name: 'browser_list',
-        description: '列出所有浏览器及其连接状态、类型和托管实例信息',
+        description: '列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含 agentbayImageId 和 agentbayAccessUrl',
         examples: ['browser_list'],
@@ -224,10 +224,24 @@ },
         name: 'browser_launch',
-        description: '启动独立 Chrome，可在新实例中通过 TDBank 登录指定账号',
+        description: '启动本地 Chrome 或 AgentBay 云浏览器，并通过 CDP 接入 Mearl',
         params: [
             { name: 'name', type: 'string', required: true, description: '实例名称，最多 64 个字符' },
-            { name: 'headless', type: 'boolean', description: '是否无头运行，默认 true' },
             {
+                name: 'provider',
+                type: '"local" | "agentbay"',
+                description: '运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器',
+            },
+            {
+                name: 'imageId',
+                type: 'string',
+                description: 'AgentBay 镜像别名或具体镜像 ID；默认使用已验证的 Linux Browser Use 内网镜像',
+            },
+            {
+                name: 'headless',
+                type: 'boolean',
+                description: '本地 provider 是否无头运行，默认 true；AgentBay 固定为 false，不支持 true',
+            },
+            {
                 name: 'userAgentMode',
                 type: '"default" | "desktop"',
-                description: 'UA 模式：default 使用 Chrome 默认 UA，desktop 使用匹配本机版本的桌面 UA',
+                description: 'UA 模式：default 使用 provider 默认 UA；desktop 本地使用匹配本机版本的 UA，AgentBay 复用控制浏览器的桌面 UA',
             },
@@ -257,6 +271,9 @@ {
                 type: 'string[]',
-                description: '从控制浏览器复制到新实例的 Cookie 域名列表，可与 TDBank 登录组合',
+                description: '从控制浏览器复制到本地或 AgentBay 新实例的 Cookie 域名列表，可与本地 TDBank 登录组合',
             },
         ],
         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","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'`,
             `browser_launch --payload '{"name":"account-a","headless":true,"accountId":12345}'`,
@@ -282,2 +299,3 @@ `browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'`,
             `browser_close --payload '{"browser":"managed:account-a"}'`,
+            `browser_close --payload '{"browser":"managed:agentbay:cloud-a"}'`,
             `browser_close --payload '{"browser":"account-b","deleteProfile":true}'`,
@@ -284,0 +302,0 @@ ],

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

@@ -140,5 +140,11 @@ export interface GetRequestsParams {
     type: 'managed';
+    provider?: 'local' | 'agentbay';
     headless: boolean;
     persistent: boolean;
-    cdpPort: number;
+    cdpPort?: number;
+    agentbaySessionId?: string;
+    /** AgentBay image used to create the session. */
+    agentbayImageId?: string;
+    /** Browser-accessible AgentBay session URL when returned by the provider. */
+    agentbayAccessUrl?: string;
     createdAt: string;
@@ -182,3 +188,9 @@ account?: ManagedBrowserAccount;
     name: string;
+    /** Browser runtime provider. Defaults to local Chrome. */
+    provider?: 'local' | 'agentbay';
+    /** AgentBay image alias or concrete image ID. Only supported by the AgentBay provider. */
+    imageId?: string;
+    /** Local Chrome defaults to true. AgentBay is fixed to false and rejects true. */
     headless?: boolean;
+    /** Desktop mode uses the local Chrome UA or copies the selected control browser UA to AgentBay. */
     userAgentMode?: 'default' | 'desktop';
@@ -193,2 +205,3 @@ persistent?: boolean;
     tabId?: number;
+    /** Copy matching cookies from the selected control browser before opening url. */
     copyCookieDomains?: string[];
@@ -195,0 +208,0 @@ }

dist/socket.js

@@ -44,4 +44,12 @@ /**
     const connected = items.filter(item => item.status === 'connected');
-    return (connected.find(item => String(item.browserId).toLowerCase() === normalized) ??
-        connected.find(item => String(item.name).toLowerCase() === normalized) ??
+    const byId = connected.find(item => String(item.browserId).toLowerCase() === normalized);
+    if (byId)
+        return byId;
+    const exactNameMatches = connected.filter(item => String(item.name).toLowerCase() === normalized);
+    if (exactNameMatches.length > 1) {
+        throw new Error(`Browser name "${selector.trim()}" is ambiguous. Use a full browserId: ${exactNameMatches
+            .map(item => String(item.browserId))
+            .join(', ')}`);
+    }
+    return (exactNameMatches[0] ??
         connected.find(item => String(item.browserId).toLowerCase().includes(normalized) ||
@@ -48,0 +56,0 @@ String(item.name).toLowerCase().includes(normalized)) ??

package.json

 {
   "name": "@mearl/client",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Client SDK & CLI for Mearl — communicate with Chrome Extension via Unix Socket",
@@ -5,0 +5,0 @@ "type": "module",

README.md

@@ -65,2 +65,3 @@ # @mearl/client
 mearl browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
+mearl browser_launch --payload '{"name":"cloud-login","provider":"agentbay","userAgentMode":"desktop","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'
 mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
@@ -108,3 +109,3 @@ mearl browser_list
 
-托管浏览器使用独立 Profile 和动态 CDP 端口。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，新实例可以使用 `headless: true`（默认）完成测试账号登录。`copyCookieDomains` 可把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会出现在命令结果或日志中；`userAgentMode: "desktop"` 可让实例使用匹配本机 Chrome 版本的桌面 UA。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
+托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`copyCookieDomains` 可把控制浏览器指定域的 Cookie 复制到本地或 AgentBay 新实例，Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 通过 `agentbayImageId` 返回实例的实际镜像；当服务返回无影浏览器串流入口时，还会通过 `agentbayAccessUrl` 暴露，该地址可能包含临时访问凭据，应按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 
@@ -111,0 +112,0 @@ ## 架构

No alert changes

Improved metrics

Total package byte prevSize

181502

2.46%

Lines of code

4055

1.35%

Number of lines in readme file

133

0.76%

No dependency changes