@mearl/client - npm Package Compare versions

Comparing version 2.0.1 to 2.0.2

dist/actionTimeouts.js

@@ -36,2 +36,4 @@ function boundedNumber(value, fallback, minimum, maximum) {
     }
+    if (action === 'tab_open')
+        return Math.max(fallback, 40);
     if (action === 'browser_launch')
@@ -38,0 +40,0 @@ return Math.max(fallback, 90);

dist/commands.js

@@ -46,5 +46,11 @@ export const COMMANDS = [
             { 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}'`,
@@ -289,3 +295,3 @@ ],
         name: 'page_click',
-        description: '点击页面元素，支持 selector / text / point 三种定位方式；默认等待异步稳定并返回页面变化信号',
+        description: '点击页面元素，支持 selector / text / point 三种定位方式；auto 在可见页按设备模拟状态使用可信 mouse/touch，隐藏页使用 DOM fallback',
         params: [
@@ -295,3 +301,3 @@ {
                 type: 'string',
-                description: '原生 CSS 选择器，或 @eN 形式的 snapshot ref（来自 page_snapshot，必须带 @ 前缀）。不支持 :has-text/:visible 等 Playwright 私有伪类',
+                description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）。不支持 :has-text/:visible 等 Playwright 私有伪类',
             },
@@ -319,7 +325,12 @@ {
             {
-                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',
@@ -334,4 +345,6 @@ type: 'object | false',
             `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}}'`,
@@ -348,3 +361,3 @@ ],
                 required: true,
-                description: '原生 CSS 选择器或 @eN snapshot ref（必须带 @ 前缀）',
+                description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）',
             },
@@ -370,3 +383,3 @@ { name: 'text', type: 'string', required: true, description: '要填写的文本' },
                 required: true,
-                description: '原生 CSS 选择器或 @eN snapshot ref（必须带 @ 前缀）',
+                description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）',
             },
@@ -384,3 +397,3 @@ {
         name: 'page_scroll',
-        description: '滚动页面，默认观察懒加载等滚动后变化',
+        description: '滚动页面或指定容器，默认观察懒加载等滚动后变化',
         params: [
@@ -393,4 +406,14 @@ {
             },
-            { 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',
@@ -405,2 +428,4 @@ type: 'object | false',
             `page_scroll --payload '{"direction":"bottom"}'`,
+            `page_scroll --payload '{"selector":".virtual-list","direction":"down","distance":800}'`,
+            `page_scroll --payload '{"selector":"@e8","containerPolicy":"nearest","direction":"bottom"}'`,
         ],
@@ -418,2 +443,7 @@ },
             },
+            {
+                name: 'observe',
+                type: 'object',
+                description: '仅在表达式会修改页面且需要观察结果时显式传入；不传保持轻量裸执行',
+            },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
@@ -470,10 +500,19 @@ ],
         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' },
@@ -484,2 +523,3 @@ ],
             `page_navigate --payload '{"tabId":12345,"refresh":true}'`,
+            `page_navigate --payload '{"tabId":12345,"history":"back"}'`,
         ],
@@ -495,3 +535,3 @@ },
                 required: true,
-                description: '原生 CSS 选择器或 @eN snapshot ref（必须带 @ 前缀），必须指向 input[type=file]',
+                description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀），必须指向 input[type=file]',
             },
@@ -519,3 +559,3 @@ { name: 'filePaths', type: 'string[]', required: true, description: '本地文件路径数组' },
                 type: '"full" | "interactive" | "viewport"',
-                description: '输出范围，默认 full；长列表优先使用 viewport',
+                description: '输出范围，默认 full；interactive 只保留当前视口内的语义控件；长列表优先使用 viewport',
             },
@@ -525,4 +565,19 @@ {
                 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 表示不限制' },
@@ -540,2 +595,4 @@ {
             `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"}}'`,
         ],
@@ -542,0 +599,0 @@ },

dist/index.d.ts

@@ -47,2 +47,4 @@ /**
     limit?: number;
+    /** Include full tracking URL, raw payload, and parsed context. Defaults to false. */
+    includeRaw?: boolean;
 }
@@ -249,2 +251,3 @@ export declare function getEvents(params?: GetEventsParams): Promise<any>;
  * 传 `observe: false` 关闭观察，仅执行裸动作并直接返回其结果。
+ * page_eval 默认裸执行，显式传 observe 对象时才进入同一观察链路。
  */
@@ -262,3 +265,3 @@ export interface PageObserveOptions {
     tabId: number;
-    /** 原生 CSS 选择器或 @eN snapshot ref。selector/text/point 三选一。 */
+    /** 原生 CSS 选择器，或 snapshot / 页面动作 observation 返回的 @eN ref。 */
     selector?: string;
@@ -276,7 +279,10 @@ /** 按可见文本（AX name）定位；可配合 role/exact 消歧。 */
     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 关闭内置观察。 */
@@ -297,4 +303,8 @@ observe?: PageObserveOptions | false;
     tabId: number;
-    direction: string;
+    direction: 'up' | 'down' | 'top' | 'bottom';
     distance?: number;
+    /** 原生 CSS 选择器或 page_snapshot 返回的 @eN ref；不传时滚动页面。 */
+    selector?: string;
+    /** selector 指向子节点时，是否自动使用最近的可滚动祖先。默认 self。 */
+    containerPolicy?: 'self' | 'nearest';
     /** 观察选项；传 false 关闭内置观察。 */
@@ -316,4 +326,14 @@ observe?: PageObserveOptions | false;
     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 {
@@ -324,3 +344,11 @@ tabId: 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';
@@ -349,6 +377,8 @@ }
     tabId: number;
-    /** 要导航到的 URL；refresh 为 true 时可省略。 */
+    /** 要导航到的 URL；与 refresh/history 互斥。 */
     url?: string;
-    /** 为 true 时直接重新加载当前页面（忽略 url），用于刷新页面。 */
+    /** 为 true 时直接重新加载当前页面；与 url/history 互斥。 */
     refresh?: boolean;
+    /** 沿当前标签页的浏览历史后退或前进；与 url/refresh 互斥。 */
+    history?: 'back' | 'forward';
 }
@@ -355,0 +385,0 @@ export declare function pageNavigate(params: PageNavigateParams): Promise<any>;

package.json

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

README.md

@@ -75,20 +75,22 @@ # @mearl/client
 
-| 分类        | 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`                                                                      |
+| 分类        | 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_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"`，已知区域时传 `rootSelector`。页面缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
+`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` 的浏览器可作为操作目标。
@@ -95,0 +97,0 @@

New alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

Found 2 instances

Fixed alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

Improved metrics

Total package byte prevSize

107717

5.74%

Lines of code

2378

3.89%

Number of lines in readme file

122

1.67%

Worsened metrics

Number of low supply chain risk alerts

12

9.09%

No dependency changes