@mearl/client 2.6.0 → 2.7.0

package/README.md

@@ -67,6 +67,7 @@ mearl browser_launch --payload '{"name":"account-a","accountId":12345}'
 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 --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
 mearl browser_list
 mearl browser_release
@@ -74,35 +75,35 @@ mearl browser_release
 
 **通用选项：**
 
-| 选项                    | 说明                     |
-| ----------------------- | ------------------------ |
-| `--payload <json>`      | 直接传入 JSON 参数       |
-| `--payload-file <path>` | 从文件读取 JSON 参数     |
-| `--timeout <seconds>`   | 请求超时时间             |
-| `--compact`             | 紧凑输出                 |
-| `--output <path>`       | 将结果写入文件（如截图） |
-| `--browser <id\|名称>`  | 指定目标浏览器           |
+| 选项                     | 说明                     |
+| ------------------------ | ------------------------ |
+| `--payload <json>`       | 直接传入 JSON 参数       |
+| `--payload-file <path>`  | 从文件读取 JSON 参数     |
+| `--timeout <seconds>`    | 请求超时时间             |
+| `--compact`              | 紧凑输出                 |
+| `--output <path>`        | 将结果写入文件（如截图） |
+| `--browser <id\|名称>`   | 指定目标浏览器           |
 | `--connector <id\|名称>` | 限制到一台远端机器       |
-| `--local`               | 只使用当前机器           |
-| `--server <url>`        | 覆盖 cloud-server 地址   |
+| `--local`                | 只使用当前机器           |
+| `--server <url>`         | 覆盖 cloud-server 地址   |
 
 ## 支持的操作
 
-| 分类        | Actions                                                                                                   |
-| ----------- | --------------------------------------------------------------------------------------------------------- |
-| API 调试    | `capture_checkpoint` `get_requests` `get_logs` `get_events` `get_api_schema`                              |
-| Mock & 规则 | `set_mock` `get_mocks` `set_rule` `get_rules`                                                             |
-| 网络代理    | `send_request` `send_mtop_request`                                                                        |
-| 标签页      | `tab_open` `tab_close` `tab_list`                                                                         |
-| 页面操作    | `page_click` `page_type` `page_scroll` `page_eval` `page_press` `page_wait` `page_navigate` `page_upload` |
-| 页面感知    | `page_snapshot` `page_screenshot` `page_selected_element` `page_frames`                                   |
-| 环境与状态  | `set_device_emulation` `set_timezone` `get_cookie` `set_cookie`                                           |
-| 用户信息    | `get_user_info`                                                                                           |
-| 录制        | `record_start` `record_stop`                                                                              |
-| TDBank      | `tdbank_account`                                                                                          |
-| 浏览器      | `browser_list` `browser_release` `browser_launch` `browser_close`                                         |
-
-页面交互动作（`page_click` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认内置观察与原子诊断：同一次调用内执行动作、等待异步稳定，并返回 `{ action, observation, diagnostics }`；`diagnostics` 默认包含新增 error logs 和全部业务 requests。传 `observe: false` 只关闭 DOM/导航观察并保留诊断；同时传 `diagnostics: false` 才仅执行裸动作。观察结果不替代完整页面理解：`mode: "delta"` 只返回主文档中的 `effects.notifications`、`effects.interactives` 和 `effects.focus` 等高置信度信号，并明确携带 `scope: "main-document"`；可交互节点会尽量携带真实 backend `node.ref`，后续动作优先使用 ref，缺少 ref 时使用 `node.selector`。`mode: "navigation"` 且 `ready: true` 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。动作直接打开新标签页时，`observation.openedTabs` 返回新标签页的 `tabId`、URL、标题和加载状态，可直接把该 `tabId` 用于后续操作，不必调用 `tab_list`。通常仅在 `fullSnapshotRecommended` 为 true 时根据 `snapshotReasons` 回退；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`page_eval` 默认裸执行；显式传 `observe` 对象可启用观察，传 `diagnostics: true` 或对象可启用原子诊断。
+| 分类        | Actions                                                                                                               |
+| ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| API 调试    | `capture_checkpoint` `get_requests` `get_logs` `get_events` `get_api_schema`                                          |
+| Mock & 规则 | `set_mock` `get_mocks` `set_rule` `get_rules`                                                                         |
+| 网络代理    | `send_request` `send_mtop_request`                                                                                    |
+| 标签页      | `tab_open` `tab_close` `tab_list`                                                                                     |
+| 页面操作    | `page_click` `page_drag` `page_type` `page_scroll` `page_eval` `page_press` `page_wait` `page_navigate` `page_upload` |
+| 页面感知    | `page_snapshot` `page_screenshot` `page_selected_element` `page_frames`                                               |
+| 环境与状态  | `set_device_emulation` `set_timezone` `get_cookie` `set_cookie`                                                       |
+| 用户信息    | `get_user_info`                                                                                                       |
+| 录制        | `record_start` `record_stop`                                                                                          |
+| TDBank      | `tdbank_account`                                                                                                      |
+| 浏览器      | `browser_list` `browser_release` `browser_launch` `browser_close`                                                     |
+
+页面交互动作（`page_click` / `page_drag` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认内置观察与原子诊断：同一次调用内执行动作、等待异步稳定，并返回 `{ action, observation, diagnostics }`；`diagnostics` 默认包含新增 error logs 和全部业务 requests。传 `observe: false` 只关闭 DOM/导航观察并保留诊断；同时传 `diagnostics: false` 才仅执行裸动作。观察结果不替代完整页面理解：`mode: "delta"` 只返回主文档中的 `effects.notifications`、`effects.interactives` 和 `effects.focus` 等高置信度信号，并明确携带 `scope: "main-document"`；可交互节点会尽量携带真实 backend `node.ref`，后续动作优先使用 ref，缺少 ref 时使用 `node.selector`。`mode: "navigation"` 且 `ready: true` 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。动作直接打开新标签页时，`observation.openedTabs` 返回新标签页的 `tabId`、URL、标题和加载状态，可直接把该 `tabId` 用于后续操作，不必调用 `tab_list`。通常仅在 `fullSnapshotRecommended` 为 true 时根据 `snapshotReasons` 回退；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`page_eval` 默认裸执行；显式传 `observe` 对象可启用观察，传 `diagnostics: true` 或对象可启用原子诊断。
 
 `page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
 
@@ -112,7 +113,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。`copyCookieDomains` 可在首次启动或需要刷新登录态时把控制浏览器指定域的 Cookie 复制到新实例，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 写入目标，Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 仅通过 `agentbayImageId`、`agentbayContextId` 和 `agentbayContextName` 返回 AgentBay 实例的稳定配置。无影浏览器串流入口包含临时访问凭据且会过期，因此不会写入实例记录或列表结果；需要时运行 `mearl check --browser <id|名称>` 实时获取，并按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 
 ## 架构
 

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runMearlCli } from './cli.js';
+process.exitCode = await runMearlCli(process.argv.slice(2));

package/dist/cli.d.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 export interface MearlCliOptions {
     commandName?: string;
     clientVersion?: string;

package/dist/cli.js

@@ -1,7 +1,5 @@
-#!/usr/bin/env node
 import { readFileSync, writeFileSync } from 'node:fs';
-import path, { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
 import { runUnifiedCheck, parseCheckTimeout } from './check.js';
 import { COMMAND_MAP } from './commands.js';
@@ -310,7 +308,3 @@ export async function runMearlCli(args, options = {}) {
         client.disconnect();
     }
 }
-const currentFile = fileURLToPath(import.meta.url);
-if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) {
-    process.exitCode = await runMearlCli(process.argv.slice(2));
-}

package/dist/commands.d.ts

@@ -302,7 +302,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
-    readonly description: "启动本地 Chrome 或 AgentBay 云浏览器，并通过 CDP 接入 Mearl";
+    readonly description: "启动本地 Chrome，或创建/显式复用 AgentBay 云浏览器，并通过 CDP 接入 Mearl";
     readonly params: [{
         readonly name: "name";
         readonly type: "string";
@@ -312,6 +312,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "provider";
         readonly type: "\"local\" | \"agentbay\"";
         readonly description: "运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器";
+    }, {
+        readonly name: "reuse";
+        readonly type: "\"never\" | \"prefer\" | \"require\"";
+        readonly description: "AgentBay 运行实例复用策略：never 默认不复用；prefer 同名运行实例存在则复用、无记录则创建；require 只复用、不创建";
     }, {
         readonly name: "imageId";
         readonly type: "string";
@@ -359,9 +363,9 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "copyCookieDomains";
         readonly type: "string[]";
-        readonly description: "从控制浏览器复制到本地或 AgentBay 新实例的 Cookie 域名列表，可与本地 TDBank 登录组合";
+        readonly description: "从控制浏览器复制到本地新实例或 AgentBay 新建/复用实例的 Cookie 域名列表，可与本地 TDBank 登录组合";
     }];
-    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\":\"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 --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";
@@ -474,6 +478,38 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly examples: ["page_click --payload '{\"text\":\"提交\"}'", "page_click --payload '{\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"selector\":\"@e3\"}'", "page_click --payload '{\"selector\":\".submit-btn\"}'", "page_click --payload '{\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"point\":{\"x\":336,\"y\":117}}'"];
+}, {
+    readonly name: "page_drag";
+    readonly description: "在页面内执行可信拖动手势；from/to 均可使用视口坐标或 CSS/@ref，auto 按设备模拟状态选择 mouse/touch，并默认观察拖动后的页面变化";
+    readonly params: [{
+        readonly name: "from";
+        readonly type: "string | { x: number; y: number }";
+        readonly required: true;
+        readonly description: "起点：原生 CSS、@eN ref，或 { x, y } 视口坐标（CSS 像素）";
+    }, {
+        readonly name: "to";
+        readonly type: "string | { x: number; y: number }";
+        readonly required: true;
+        readonly description: "终点：原生 CSS、@eN ref，或 { x, y } 视口坐标（CSS 像素）";
+    }, {
+        readonly name: "dragMode";
+        readonly type: "\"auto\" | \"mouse\" | \"touch\"";
+        readonly description: "拖动输入类型；默认 auto，移动模拟页使用 touch，其余使用 mouse";
+    }, {
+        readonly name: "durationMs";
+        readonly type: "number";
+        readonly description: "拖动持续时间，0–5000ms，默认 400ms；内部自动分段移动";
+    }, {
+        readonly name: "observe";
+        readonly type: "object | false";
+        readonly description: "观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回";
+    }, ParamDef, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_drag --payload '{\"from\":{\"x\":350,\"y\":80},\"to\":{\"x\":80,\"y\":80}}'", "page_drag --payload '{\"from\":\"@e3\",\"to\":\"#drop-zone\",\"dragMode\":\"mouse\"}'"];
 }, {
     readonly name: "page_type";
     readonly description: "向输入框填写文本，兼容 React 受控组件；默认观察校验提示等异步变化";

package/dist/commands.js

@@ -220,7 +220,7 @@ export const COMMANDS = [
     },
     {
         name: 'browser_launch',
-        description: '启动本地 Chrome 或 AgentBay 云浏览器，并通过 CDP 接入 Mearl',
+        description: '启动本地 Chrome，或创建/显式复用 AgentBay 云浏览器，并通过 CDP 接入 Mearl',
         params: [
             { name: 'name', type: 'string', required: true, description: '实例名称，最多 64 个字符' },
             {
@@ -228,6 +228,11 @@ export const COMMANDS = [
                 type: '"local" | "agentbay"',
                 description: '运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器',
             },
+            {
+                name: 'reuse',
+                type: '"never" | "prefer" | "require"',
+                description: 'AgentBay 运行实例复用策略：never 默认不复用；prefer 同名运行实例存在则复用、无记录则创建；require 只复用、不创建',
+            },
             {
                 name: 'imageId',
                 type: 'string',
@@ -266,13 +271,14 @@ export const COMMANDS = [
             {
                 name: 'copyCookieDomains',
                 type: 'string[]',
-                description: '从控制浏览器复制到本地或 AgentBay 新实例的 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","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":"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"}'`,
@@ -420,6 +426,45 @@ export const COMMANDS = [
             `page_click --payload '{"point":{"x":336,"y":117}}'`,
         ],
     },
+    {
+        name: 'page_drag',
+        description: '在页面内执行可信拖动手势；from/to 均可使用视口坐标或 CSS/@ref，auto 按设备模拟状态选择 mouse/touch，并默认观察拖动后的页面变化',
+        params: [
+            {
+                name: 'from',
+                type: 'string | { x: number; y: number }',
+                required: true,
+                description: '起点：原生 CSS、@eN ref，或 { x, y } 视口坐标（CSS 像素）',
+            },
+            {
+                name: 'to',
+                type: 'string | { x: number; y: number }',
+                required: true,
+                description: '终点：原生 CSS、@eN ref，或 { x, y } 视口坐标（CSS 像素）',
+            },
+            {
+                name: 'dragMode',
+                type: '"auto" | "mouse" | "touch"',
+                description: '拖动输入类型；默认 auto，移动模拟页使用 touch，其余使用 mouse',
+            },
+            {
+                name: 'durationMs',
+                type: 'number',
+                description: '拖动持续时间，0–5000ms，默认 400ms；内部自动分段移动',
+            },
+            {
+                name: 'observe',
+                type: 'object | false',
+                description: '观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回',
+            },
+            PAGE_DIAGNOSTICS_PARAM,
+            { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
+        ],
+        examples: [
+            `page_drag --payload '{"from":{"x":350,"y":80},"to":{"x":80,"y":80}}'`,
+            `page_drag --payload '{"from":"@e3","to":"#drop-zone","dragMode":"mouse"}'`,
+        ],
+    },
     {
         name: 'page_type',
         description: '向输入框填写文本，兼容 React 受控组件；默认观察校验提示等异步变化',

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

@@ -199,6 +199,8 @@ export interface BrowserLaunchParams {
     name: string;
     /** Browser runtime provider. Defaults to local Chrome. */
     provider?: 'local' | 'agentbay';
+    /** 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. */
     imageId?: string;
     /** Local Chrome defaults to true. AgentBay is fixed to false and rejects true. */
@@ -213,7 +215,7 @@ export interface BrowserLaunchParams {
     site?: string | number;
     query?: string;
     tabId?: number;
-    /** Copy matching cookies from the selected control browser before opening url. */
+    /** Copy matching cookies from the selected control browser into a new or reused instance. */
     copyCookieDomains?: string[];
 }
 export interface BrowserCloseParams {
@@ -314,6 +316,20 @@ export interface PageClickParams {
     observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
 }
+export interface PageDragPoint {
+    x: number;
+    y: number;
+}
+export type PageDragEndpoint = string | PageDragPoint;
+export interface PageDragParams {
+    tabId?: number;
+    from: PageDragEndpoint;
+    to: PageDragEndpoint;
+    dragMode?: 'auto' | 'mouse' | 'touch';
+    durationMs?: number;
+    observe?: PageObservationWaitOptions | false;
+    diagnostics?: PageDiagnosticsSetting;
+}
 export interface PageTypeParams {
     tabId?: number;
     selector: string;
@@ -547,6 +563,10 @@ export interface BrowserActionMap {
         request: PageClickParams;
         response: unknown;
     };
+    page_drag: {
+        request: PageDragParams;
+        response: unknown;
+    };
     page_type: {
         request: PageTypeParams;
         response: unknown;
@@ -629,7 +649,7 @@ export type BrowserActionRequest<A extends BrowserAction> = BrowserActionMap[A][
 export type BrowserActionResponse<A extends BrowserAction> = BrowserActionMap[A]['response'];
 export type BrowserCommandAction = Exclude<BrowserAction, 'browser_select_browser'>;
 export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list' | 'browser_launch' | 'browser_close'>;
-export declare const PAGE_ACT_ACTIONS: readonly ["page_click", "page_type", "page_hover", "page_scroll", "page_press", "page_upload", "page_eval"];
+export declare const PAGE_ACT_ACTIONS: readonly ["page_click", "page_drag", "page_type", "page_hover", "page_scroll", "page_press", "page_upload", "page_eval"];
 export type PageActAction = (typeof PAGE_ACT_ACTIONS)[number];
 export declare const BROWSER_ACTIONS: {
     readonly capture_checkpoint: true;
@@ -655,6 +675,7 @@ export declare const BROWSER_ACTIONS: {
     readonly tab_close: true;
     readonly tab_list: true;
     readonly page_click: true;
+    readonly page_drag: true;
     readonly page_type: true;
     readonly page_scroll: true;
     readonly page_hover: true;
@@ -698,6 +719,7 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly tab_close: true;
     readonly tab_list: true;
     readonly page_click: true;
+    readonly page_drag: true;
     readonly page_type: true;
     readonly page_scroll: true;
     readonly page_hover: true;
@@ -738,6 +760,7 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
     readonly tab_close: true;
     readonly tab_list: true;
     readonly page_click: true;
+    readonly page_drag: true;
     readonly page_type: true;
     readonly page_scroll: true;
     readonly page_hover: true;

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

@@ -8,6 +8,7 @@ export const SEND_REQUEST_MAX_TOTAL_FILE_BYTES = 40 * 1024 * 1024;
 export const SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES = 7 * 1024 * 1024;
 export const PAGE_ACT_ACTIONS = [
     'page_click',
+    'page_drag',
     'page_type',
     'page_hover',
     'page_scroll',
@@ -39,6 +40,7 @@ export const BROWSER_ACTIONS = {
     tab_close: true,
     tab_list: true,
     page_click: true,
+    page_drag: true,
     page_type: true,
     page_scroll: true,
     page_hover: true,
@@ -82,6 +84,7 @@ export const BROWSER_COMMAND_ACTIONS = {
     tab_close: true,
     tab_list: true,
     page_click: true,
+    page_drag: true,
     page_type: true,
     page_scroll: true,
     page_hover: true,
@@ -122,6 +125,7 @@ export const EXTENSION_BROWSER_ACTIONS = {
     tab_close: true,
     tab_list: true,
     page_click: true,
+    page_drag: true,
     page_type: true,
     page_scroll: true,
     page_hover: true,

package/dist/index.d.ts

@@ -7,7 +7,7 @@
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
 export { 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, 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, 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, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
+export type { ActionStep, 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, 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';
 export declare function captureCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'capture_checkpoint'>>;
@@ -33,6 +33,7 @@ export declare function tabOpen(params: Protocol.TabOpenParams, options?: Unifie
 export declare function tabClose(params: Protocol.TabCloseParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_close'>>;
 export declare function tabList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_list'>>;
 export declare function pageClick(params: Protocol.PageClickParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_click'>>;
+export declare function pageDrag(params: Protocol.PageDragParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_drag'>>;
 export declare function pageType(params: Protocol.PageTypeParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_type'>>;
 export declare function pageScroll(params: Protocol.PageScrollParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_scroll'>>;
 export declare function pageHover(params: Protocol.PageHoverParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_hover'>>;

package/dist/index.js

@@ -76,6 +76,9 @@ export function tabList(options) {
 export function pageClick(params, options) {
     return invoke('page_click', params, options);
 }
+export function pageDrag(params, options) {
+    return invoke('page_drag', params, options);
+}
 export function pageType(params, options) {
     return invoke('page_type', params, options);
 }

package/dist/socket.d.ts

@@ -13,6 +13,8 @@ export declare const CLIENT_VERSION: string;
  * (or the pre-ping startup window) and is what auto-spawn targets.
  */
 export declare const SOCKET_PATH: string;
+export type ControlSource = 'local' | 'remote';
+type CompatibleControlSource = ControlSource | 'cloud';
 export interface InvokeOptions {
     /** 超时时间（秒），默认 15 */
     timeoutSec?: number;
@@ -20,8 +22,8 @@ export interface InvokeOptions {
     transport?: 'cdp';
     /** Target a specific browser by id / name (see the browser registry). */
     browser?: string;
-    /** Identifies whether browser control originated locally or through the cloud connector. */
-    controlSource?: 'local' | 'cloud';
+    /** Identifies whether browser control originated on this machine or through a remote connector. */
+    controlSource?: CompatibleControlSource;
 }
 /** Pin the default target browser for subsequent invokes (undefined clears it). */
 export declare function setDefaultBrowser(selector: string | undefined): void;
@@ -35,3 +37,4 @@ export declare function decorateBrowserListResult(result: Record<string, any>):
  * legacy well-known socket，并在 socket 不存在（ENOENT）时自动拉起 native host。
  */
 export declare function invoke(action: string, data?: Record<string, any>, options?: InvokeOptions): Promise<any>;
+export {};

package/dist/socket.js

@@ -25,6 +25,9 @@ const MAX_SOCKET_BUFFER_SIZE = 64 * 1024 * 1024;
 export const SOCKET_PATH = process.platform === 'win32'
     ? '\\\\.\\pipe\\mearl-agent'
     : path.join(os.tmpdir(), 'mearl-agent.sock');
+function toControlSourceWireValue(source) {
+    return source === 'remote' || source === 'cloud' ? 'cloud' : 'local';
+}
 /**
  * Process-wide default browser selector. Lets a long-lived host (e.g. the MCP
  * server) pin a target once via `select_browser` without threading it through
@@ -266,7 +269,7 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSour
                 action,
                 data,
                 version: CLIENT_VERSION,
-                controlSource,
+                controlSource: toControlSourceWireValue(controlSource),
             };
             if (transport)
                 message.transport = transport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
     }
   },
   "bin": {
-    "mearl": "./dist/cli.js"
+    "mearl": "./dist/bin.js"
   },
   "files": [
     "dist"
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.6.0"
+    "@mearl/cloud-types": "2.7.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
@@ -57,7 +57,7 @@
     "typescript": "^5.8.3"
   },
   "scripts": {
-    "build": "node ../../scripts/generate-client-action-protocol.mjs --check && rm -rf dist/ && tsc && chmod +x dist/cli.js",
+    "build": "node ../../scripts/generate-client-action-protocol.mjs --check && rm -rf dist/ && tsc && chmod +x dist/bin.js",
     "dev": "tsc --watch",
     "typecheck": "node ../../scripts/generate-client-action-protocol.mjs --check && tsc --noEmit",
     "test": "vitest run"