@mearl/client - npm Package Compare versions

Comparing version 2.6.1 to 2.7.0

dist/commands.d.ts

@@ -305,3 +305,3 @@ import type { BrowserCommandAction } from './generated-browser-action-protocol.js';
     readonly name: "browser_launch";
-    readonly description: "启动本地 Chrome 或 AgentBay 云浏览器，并通过 CDP 接入 Mearl";
+    readonly description: "启动本地 Chrome，或创建/显式复用 AgentBay 云浏览器，并通过 CDP 接入 Mearl";
     readonly params: [{
@@ -317,2 +317,6 @@ readonly name: "name";
     }, {
+        readonly name: "reuse";
+        readonly type: "\"never\" | \"prefer\" | \"require\"";
+        readonly description: "AgentBay 运行实例复用策略：never 默认不复用；prefer 同名运行实例存在则复用、无记录则创建；require 只复用、不创建";
+    }, {
         readonly name: "imageId";
@@ -364,5 +368,5 @@ readonly type: "string";
         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\"]}'"];
 }, {
@@ -481,2 +485,34 @@ readonly name: "browser_close";
 }, {
+    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";
@@ -483,0 +519,0 @@ readonly description: "向输入框填写文本，兼容 React 受控组件；默认观察校验提示等异步变化";

dist/commands.js

@@ -223,3 +223,3 @@ const PAGE_DIAGNOSTICS_PARAM = {
         name: 'browser_launch',
-        description: '启动本地 Chrome 或 AgentBay 云浏览器，并通过 CDP 接入 Mearl',
+        description: '启动本地 Chrome，或创建/显式复用 AgentBay 云浏览器，并通过 CDP 接入 Mearl',
         params: [
@@ -233,2 +233,7 @@ { name: 'name', type: 'string', required: true, description: '实例名称，最多 64 个字符' },
             {
+                name: 'reuse',
+                type: '"never" | "prefer" | "require"',
+                description: 'AgentBay 运行实例复用策略：never 默认不复用；prefer 同名运行实例存在则复用、无记录则创建；require 只复用、不创建',
+            },
+            {
                 name: 'imageId',
@@ -271,3 +276,3 @@ type: 'string',
                 type: 'string[]',
-                description: '从控制浏览器复制到本地或 AgentBay 新实例的 Cookie 域名列表，可与本地 TDBank 登录组合',
+                description: '从控制浏览器复制到本地新实例或 AgentBay 新建/复用实例的 Cookie 域名列表，可与本地 TDBank 登录组合',
             },
@@ -279,2 +284,3 @@ ],
             `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}'`,
@@ -428,2 +434,41 @@ `browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'`,
     {
+        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',
@@ -430,0 +475,0 @@ description: '向输入框填写文本，兼容 React 受控组件；默认观察校验提示等异步变化',

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

@@ -202,2 +202,4 @@ export interface GetRequestsParams {
     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. */
@@ -217,3 +219,3 @@ imageId?: 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[];
@@ -319,2 +321,16 @@ }
 }
+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 {
@@ -553,2 +569,6 @@ tabId?: number;
     };
+    page_drag: {
+        request: PageDragParams;
+        response: unknown;
+    };
     page_type: {
@@ -636,3 +656,3 @@ request: PageTypeParams;
 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];
@@ -663,2 +683,3 @@ export declare const BROWSER_ACTIONS: {
     readonly page_click: true;
+    readonly page_drag: true;
     readonly page_type: true;
@@ -707,2 +728,3 @@ readonly page_scroll: true;
     readonly page_click: true;
+    readonly page_drag: true;
     readonly page_type: true;
@@ -748,2 +770,3 @@ readonly page_scroll: true;
     readonly page_click: true;
+    readonly page_drag: true;
     readonly page_type: true;
@@ -750,0 +773,0 @@ readonly page_scroll: true;

dist/generated-browser-action-protocol.js

@@ -11,2 +11,3 @@ // Generated by scripts/generate-client-action-protocol.mjs.
     'page_click',
+    'page_drag',
     'page_type',
@@ -43,2 +44,3 @@ 'page_hover',
     page_click: true,
+    page_drag: true,
     page_type: true,
@@ -87,2 +89,3 @@ page_scroll: true,
     page_click: true,
+    page_drag: true,
     page_type: true,
@@ -128,2 +131,3 @@ page_scroll: true,
     page_click: true,
+    page_drag: true,
     page_type: true,
@@ -130,0 +134,0 @@ page_scroll: true,

dist/index.d.ts

@@ -10,3 +10,3 @@ /**
 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';
@@ -37,2 +37,3 @@ import type * as Protocol from './generated-browser-action-protocol.js';
 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'>>;
@@ -39,0 +40,0 @@ export declare function pageScroll(params: Protocol.PageScrollParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_scroll'>>;

dist/index.js

@@ -79,2 +79,5 @@ /**
 }
+export function pageDrag(params, options) {
+    return invoke('page_drag', params, options);
+}
 export function pageType(params, options) {
@@ -81,0 +84,0 @@ return invoke('page_type', params, options);

dist/socket.d.ts

@@ -16,2 +16,4 @@ /**
 export declare const SOCKET_PATH: string;
+export type ControlSource = 'local' | 'remote';
+type CompatibleControlSource = ControlSource | 'cloud';
 export interface InvokeOptions {
@@ -24,4 +26,4 @@ /** 超时时间（秒），默认 15 */
     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;
 }
@@ -40,1 +42,2 @@ /** Pin the default target browser for subsequent invokes (undefined clears it). */
 export declare function invoke(action: string, data?: Record<string, any>, options?: InvokeOptions): Promise<any>;
+export {};

dist/socket.js

@@ -28,2 +28,5 @@ /**
     : path.join(os.tmpdir(), 'mearl-agent.sock');
+function toControlSourceWireValue(source) {
+    return source === 'remote' || source === 'cloud' ? 'cloud' : 'local';
+}
 /**
@@ -270,3 +273,3 @@ * Process-wide default browser selector. Lets a long-lived host (e.g. the MCP
                 version: CLIENT_VERSION,
-                controlSource,
+                controlSource: toControlSourceWireValue(controlSource),
             };
@@ -273,0 +276,0 @@ if (transport)

package.json

 {
   "name": "@mearl/client",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
@@ -52,3 +52,3 @@ "type": "module",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.6.1"
+    "@mearl/cloud-types": "2.7.0"
   },
@@ -55,0 +55,0 @@ "devDependencies": {

README.md

@@ -70,2 +70,3 @@ # @mearl/client
 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"]}'
@@ -78,31 +79,31 @@ mearl browser_list
 
-| 选项                    | 说明                     |
-| ----------------------- | ------------------------ |
-| `--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`                                         |
+| 分类        | 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_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_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` 或对象可启用原子诊断。
 
@@ -117,3 +118,3 @@ `page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
 
-托管浏览器使用独立 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)。
 
@@ -120,0 +121,0 @@ ## 架构

No alert changes

Improved metrics

Total package byte prevSize

230023

2.83%

Lines of code

5015

2.43%

Number of lines in readme file

140

0.72%

Dependency changes

• + Added

  @mearl/cloud-types@2.7.0
  (transitive)

• - Removed

  @mearl/cloud-types@2.6.1
  (transitive)

• Updated

  @mearl/cloud-types@2.7.0