@mearl/client 2.0.1 → 2.0.2

package/README.md

@@ -72,23 +72,25 @@ mearl browser_list
 
 ## 支持的操作
 
-| 分类        | Actions                                                                                                              |
-| ----------- | -------------------------------------------------------------------------------------------------------------------- |
-| API 调试    | `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_user_info`                                                                                                      |
-| 录制        | `record_start` `record_stop`                                                                            |
-| TDBank      | `tdbank_account`                                                                                                     |
-| 浏览器      | `browser_list` `browser_launch` `browser_close`                                                                      |
-
-页面交互动作（`page_click` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认内置观察：同一次调用内执行动作并等待异步稳定，返回 `{ action, observation }`；传 `observe: false` 可关闭观察仅执行裸动作。观察结果不替代完整页面理解：`mode: "delta"` 只返回主文档中的 `effects.notifications`、`effects.interactives` 和 `effects.focus` 等高置信度信号，并明确携带 `scope: "main-document"`；`mode: "navigation"` 且 `ready: true` 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。仅在 `fullSnapshotRecommended` 为 true 时根据 `snapshotReasons` 回退到完整快照或截图。
-
-`page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要控件时传 `mode: "interactive"`，已知区域时传 `rootSelector`。页面缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
+| 分类        | Actions                                                                                                   |
+| ----------- | --------------------------------------------------------------------------------------------------------- |
+| API 调试    | `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_user_info`                                                                                           |
+| 录制        | `record_start` `record_stop`                                                                              |
+| TDBank      | `tdbank_account`                                                                                          |
+| 浏览器      | `browser_list` `browser_launch` `browser_close`                                                           |
+
+页面交互动作（`page_click` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认内置观察：同一次调用内执行动作并等待异步稳定，返回 `{ action, observation }`；传 `observe: false` 可关闭观察仅执行裸动作。观察结果不替代完整页面理解：`mode: "delta"` 只返回主文档中的 `effects.notifications`、`effects.interactives` 和 `effects.focus` 等高置信度信号，并明确携带 `scope: "main-document"`；可交互节点会尽量携带真实 backend `node.ref`，后续动作优先使用 ref，缺少 ref 时使用 `node.selector`。`mode: "navigation"` 且 `ready: true` 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。通常仅在 `fullSnapshotRecommended` 为 true 时根据 `snapshotReasons` 回退；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`page_eval` 默认裸执行，只有显式传入 `observe` 对象时才启用观察。
+
+`page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
+
+重复文本点击可用 `page_click.scope` 限定 CSS / ref 子树；ref 指向滚动容器内的子节点时，可用 `page_scroll.containerPolicy: "nearest"` 自动解析最近可滚动祖先。`page_click.clickMode` 默认 `auto`：可见桌面页派发可信 mouse，移动模拟页派发可信 touch；隐藏页使用 DOM fallback，返回 `dispatchMode: "dom"` 和 `fallbackReason: "page-hidden"`，且不切换标签或还原窗口。可用 `dom` / `mouse` / `touch` 覆盖自动策略；可信输入返回实际 `pointerType`。点击结果的 `resolvedTarget` 和滚动结果的前后位置、边界字段可用于诊断实际派发目标与滚动效果。
 
 `browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
 

package/dist/actionTimeouts.js

@@ -33,6 +33,8 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
         const waitMs = data.time ?? data.timeout ?? 10000;
         return Math.max(fallback, Math.ceil((Number(waitMs) + 5000) / 1000));
     }
+    if (action === 'tab_open')
+        return Math.max(fallback, 40);
     if (action === 'browser_launch')
         return Math.max(fallback, 90);
     if (action === 'browser_close' || action === 'tdbank_account')

package/dist/commands.js

@@ -43,9 +43,15 @@ export const COMMANDS = [
             { name: 'filter', type: 'string', description: '按 name 或 url 过滤，支持正则' },
             { name: 'since', type: 'number', description: '只返回最近 N 秒内的事件' },
             { name: 'limit', type: 'number', description: '返回条数，默认 20' },
+            {
+                name: 'includeRaw',
+                type: 'boolean',
+                description: '返回完整 URL、_raw 和 _context；默认 false',
+            },
         ],
         examples: [
             `get_events --payload '{"source":"aplus","event_type":"CLK","limit":10}'`,
+            `get_events --payload '{"filter":"order","includeRaw":true,"limit":1}'`,
             `get_events --payload '{"tabId":12345,"source":"all","limit":20}'`,
         ],
     },
@@ -285,12 +291,12 @@ export const COMMANDS = [
     // ── 页面操作 ──────────────────────────────────────────────────────────────
     {
         name: 'page_click',
-        description: '点击页面元素，支持 selector / text / point 三种定位方式；默认等待异步稳定并返回页面变化信号',
+        description: '点击页面元素，支持 selector / text / point 三种定位方式；auto 在可见页按设备模拟状态使用可信 mouse/touch，隐藏页使用 DOM fallback',
         params: [
             {
                 name: 'selector',
                 type: 'string',
-                description: '原生 CSS 选择器，或 @eN 形式的 snapshot ref（来自 page_snapshot，必须带 @ 前缀）。不支持 :has-text/:visible 等 Playwright 私有伪类',
+                description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）。不支持 :has-text/:visible 等 Playwright 私有伪类',
             },
             {
                 name: 'text',
@@ -313,9 +319,14 @@ export const COMMANDS = [
                 description: '配合 text 使用，默认 true 精确匹配；false 时按子串匹配',
             },
             {
-                name: 'clickType',
-                type: '"js" | "cdp"',
-                description: '点击方式，默认 js（对 selector/@ref 调用 el.click()）；cdp 走真实 mouse/touch 事件',
+                name: 'scope',
+                type: 'string',
+                description: '配合 text 使用，把文本匹配限制在指定 CSS 元素或 @eN ref 子树内，适合消除重复文案歧义',
+            },
+            {
+                name: 'clickMode',
+                type: '"auto" | "dom" | "mouse" | "touch"',
+                description: '点击模式；auto 在可见页按设备模拟状态选择可信 mouse/touch、隐藏页走 DOM，checkbox/radio 校验状态；其他值强制指定派发方式',
             },
             {
                 name: 'observe',
@@ -327,8 +338,10 @@ export const COMMANDS = [
         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}}'`,
         ],
     },
@@ -340,7 +353,7 @@ export const COMMANDS = [
                 name: 'selector',
                 type: 'string',
                 required: true,
-                description: '原生 CSS 选择器或 @eN snapshot ref（必须带 @ 前缀）',
+                description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）',
             },
             { name: 'text', type: 'string', required: true, description: '要填写的文本' },
             { name: 'clearFirst', type: 'boolean', description: '是否先清空原有内容，默认 true' },
@@ -361,7 +374,7 @@ export const COMMANDS = [
                 name: 'selector',
                 type: 'string',
                 required: true,
-                description: '原生 CSS 选择器或 @eN snapshot ref（必须带 @ 前缀）',
+                description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）',
             },
             {
                 name: 'observe',
@@ -374,7 +387,7 @@ export const COMMANDS = [
     },
     {
         name: 'page_scroll',
-        description: '滚动页面，默认观察懒加载等滚动后变化',
+        description: '滚动页面或指定容器，默认观察懒加载等滚动后变化',
         params: [
             {
                 name: 'direction',
@@ -382,7 +395,17 @@ export const COMMANDS = [
                 required: true,
                 description: '滚动方向',
             },
-            { name: 'distance', type: 'number', description: '滚动距离（px），默认 300' },
+            { name: 'distance', type: 'number', description: '滚动距离（px），默认 600' },
+            {
+                name: 'selector',
+                type: 'string',
+                description: '目标滚动容器的原生 CSS 选择器，或 page_snapshot 返回的 @eN ref；不传时滚动页面',
+            },
+            {
+                name: 'containerPolicy',
+                type: '"self" | "nearest"',
+                description: '默认 self，要求 selector 本身可滚动；nearest 会在其不可滚动时使用最近的可滚动祖先',
+            },
             {
                 name: 'observe',
                 type: 'object | false',
@@ -393,6 +416,8 @@ export const COMMANDS = [
         examples: [
             `page_scroll --payload '{"direction":"down"}'`,
             `page_scroll --payload '{"direction":"bottom"}'`,
+            `page_scroll --payload '{"selector":".virtual-list","direction":"down","distance":800}'`,
+            `page_scroll --payload '{"selector":"@e8","containerPolicy":"nearest","direction":"bottom"}'`,
         ],
     },
     {
@@ -405,6 +430,11 @@ export const COMMANDS = [
                 type: 'boolean',
                 description: '表达式返回 Promise 时等待完成，默认 true',
             },
+            {
+                name: 'observe',
+                type: 'object',
+                description: '仅在表达式会修改页面且需要观察结果时显式传入；不传保持轻量裸执行',
+            },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [`page_eval --payload '{"expression":"document.title"}'`],
@@ -456,19 +486,29 @@ export const COMMANDS = [
     },
     {
         name: 'page_navigate',
-        description: '在当前标签页内导航到新 URL，或用 refresh 直接刷新当前页面',
+        description: '在当前标签页内导航到 URL、刷新页面，或沿浏览历史后退/前进',
         params: [
-            { name: 'url', type: 'string', description: '要导航到的 URL（refresh 为 true 时可省略）' },
+            {
+                name: 'url',
+                type: 'string',
+                description: '要导航到的 URL；与 refresh/history 互斥',
+            },
             {
                 name: 'refresh',
                 type: 'boolean',
-                description: '为 true 时直接重新加载当前页面（忽略 url），默认 false',
+                description: '为 true 时直接重新加载当前页面；与 url/history 互斥',
+            },
+            {
+                name: 'history',
+                type: '"back" | "forward"',
+                description: '沿当前标签页浏览历史后退或前进；与 url/refresh 互斥',
             },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
             `page_navigate --payload '{"tabId":12345,"url":"https://example.com/page2"}'`,
             `page_navigate --payload '{"tabId":12345,"refresh":true}'`,
+            `page_navigate --payload '{"tabId":12345,"history":"back"}'`,
         ],
     },
     {
@@ -479,7 +519,7 @@ export const COMMANDS = [
                 name: 'selector',
                 type: 'string',
                 required: true,
-                description: '原生 CSS 选择器或 @eN snapshot ref（必须带 @ 前缀），必须指向 input[type=file]',
+                description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀），必须指向 input[type=file]',
             },
             { name: 'filePaths', type: 'string[]', required: true, description: '本地文件路径数组' },
             {
@@ -502,12 +542,27 @@ export const COMMANDS = [
             {
                 name: 'mode',
                 type: '"full" | "interactive" | "viewport"',
-                description: '输出范围，默认 full；长列表优先使用 viewport',
+                description: '输出范围，默认 full；interactive 只保留当前视口内的语义控件；长列表优先使用 viewport',
             },
             {
                 name: 'rootSelector',
                 type: 'string',
-                description: '只获取指定 CSS 元素的 AX 子树，可与 mode 组合',
+                description: '只获取指定 CSS 元素的 AX 子树，可与 mode 组合；与 rootRef 互斥',
+            },
+            {
+                name: 'rootRef',
+                type: 'string',
+                description: '以已有 @eN ref 为根获取局部 AX 子树；与 rootSelector 互斥',
+            },
+            {
+                name: 'ancestorDepth',
+                type: 'number',
+                description: 'rootRef 向上扩展的 DOM 祖先层数，默认 0，最大 20',
+            },
+            {
+                name: 'query',
+                type: '{ text?: string; role?: string; exact?: boolean }',
+                description: '服务端过滤 AX 树，只保留按 accessibility name / role 命中的节点及祖先路径',
             },
             { name: 'maxNodes', type: 'number', description: '最多输出节点数，0 表示不限制' },
             {
@@ -521,6 +576,8 @@ export const COMMANDS = [
             'page_snapshot',
             `page_snapshot --payload '{"tabId":1,"mode":"viewport"}'`,
             `page_snapshot --payload '{"tabId":1,"rootSelector":"[role=dialog]"}'`,
+            `page_snapshot --payload '{"tabId":1,"rootRef":"@e8","ancestorDepth":1}'`,
+            `page_snapshot --payload '{"tabId":1,"query":{"text":"保存","role":"button"}}'`,
         ],
     },
     {

package/dist/index.d.ts

@@ -44,6 +44,8 @@ export interface GetEventsParams {
     filter?: string;
     since?: number;
     limit?: number;
+    /** Include full tracking URL, raw payload, and parsed context. Defaults to false. */
+    includeRaw?: boolean;
 }
 export declare function getEvents(params?: GetEventsParams): Promise<any>;
 export interface SetMockParams {
@@ -245,6 +247,7 @@ export declare function tabList(): Promise<any>;
  * 页面交互动作（click/type/hover/scroll/press/upload）默认内置观察：
  * 同一次调用内执行动作并等待异步稳定，返回 `{ action, observation }`。
  * 传 `observe: false` 关闭观察，仅执行裸动作并直接返回其结果。
+ * page_eval 默认裸执行，显式传 observe 对象时才进入同一观察链路。
  */
 export interface PageObserveOptions {
     quietMs?: number;
@@ -257,7 +260,7 @@ export interface PageObserveOptions {
 }
 export interface PageClickParams {
     tabId: number;
-    /** 原生 CSS 选择器或 @eN snapshot ref。selector/text/point 三选一。 */
+    /** 原生 CSS 选择器，或 snapshot / 页面动作 observation 返回的 @eN ref。 */
     selector?: string;
     /** 按可见文本（AX name）定位；可配合 role/exact 消歧。 */
     text?: string;
@@ -270,11 +273,14 @@ export interface PageClickParams {
     role?: string;
     /** 配合 text，默认 true（精确匹配），false 时子串匹配。 */
     exact?: boolean;
+    /** 配合 text，把 AX 文本匹配限制在指定 CSS 元素或 @eN ref 子树内。 */
+    scope?: string;
     /**
-     * 点击方式。默认 'js'（对 selector / @ref 调用 el.click()）。
-     * 'cdp' 走真实 mouse/touch 事件；text 与 point 始终用 CDP。
+     * 点击模式。auto 会在可见页按设备模拟状态选择可信 mouse/touch，在隐藏页
+     * 使用 DOM fallback；checkbox/radio 使用带状态校验的 DOM 路径。
+     * dom/mouse/touch 可强制指定实际派发方式。
      */
-    clickType?: 'js' | 'cdp';
+    clickMode?: 'auto' | 'dom' | 'mouse' | 'touch';
     /** 观察选项；传 false 关闭内置观察。 */
     observe?: PageObserveOptions | false;
 }
@@ -290,8 +296,12 @@ export interface PageTypeParams {
 export declare function pageType(params: PageTypeParams): Promise<any>;
 export interface PageScrollParams {
     tabId: number;
-    direction: string;
+    direction: 'up' | 'down' | 'top' | 'bottom';
     distance?: number;
+    /** 原生 CSS 选择器或 page_snapshot 返回的 @eN ref；不传时滚动页面。 */
+    selector?: string;
+    /** selector 指向子节点时，是否自动使用最近的可滚动祖先。默认 self。 */
+    containerPolicy?: 'self' | 'nearest';
     /** 观察选项；传 false 关闭内置观察。 */
     observe?: PageObserveOptions | false;
 }
@@ -308,14 +318,32 @@ export interface PageEvalParams {
     expression: string;
     frameId?: string;
     awaitPromise?: boolean;
+    /** 显式传入时观察表达式引发的页面变化；不传保持轻量裸执行。 */
+    observe?: PageObserveOptions;
 }
 export declare function pageEval(params: PageEvalParams): Promise<any>;
+export interface PageSnapshotQuery {
+    /** 按 accessibility name 匹配。 */
+    text?: string;
+    /** 按 AX role 匹配。 */
+    role?: string;
+    /** 默认 true 精确匹配；false 时按子串匹配 text。 */
+    exact?: boolean;
+}
 export interface PageSnapshotParams {
     tabId: number;
     depth?: number;
     maxChars?: number;
     maxNodes?: number;
+    /** CSS 根元素；与 rootRef 互斥。 */
     rootSelector?: string;
+    /** 以已有 @eN ref 为根获取局部 AX 子树；与 rootSelector 互斥。 */
+    rootRef?: string;
+    /** rootRef 向上扩展的 DOM 祖先层数，默认 0，最大 20。 */
+    ancestorDepth?: number;
+    /** 服务端过滤 AX 树，只保留命中节点及其祖先路径。 */
+    query?: PageSnapshotQuery;
+    /** full 为完整树；interactive 为当前视口内的语义控件；viewport 为当前可视区域。 */
     mode?: 'full' | 'interactive' | 'viewport';
 }
 export declare function pageSnapshot(params: PageSnapshotParams): Promise<any>;
@@ -339,10 +367,12 @@ export interface PageWaitParams {
 export declare function pageWait(params: PageWaitParams): Promise<any>;
 export interface PageNavigateParams {
     tabId: number;
-    /** 要导航到的 URL；refresh 为 true 时可省略。 */
+    /** 要导航到的 URL；与 refresh/history 互斥。 */
     url?: string;
-    /** 为 true 时直接重新加载当前页面（忽略 url），用于刷新页面。 */
+    /** 为 true 时直接重新加载当前页面；与 url/history 互斥。 */
     refresh?: boolean;
+    /** 沿当前标签页的浏览历史后退或前进；与 url/refresh 互斥。 */
+    history?: 'back' | 'forward';
 }
 export declare function pageNavigate(params: PageNavigateParams): Promise<any>;
 export interface PageUploadParams {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Client SDK & CLI for Mearl — communicate with Chrome Extension via Unix Socket",
   "type": "module",
   "main": "dist/index.js",