dp-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{dp_cli-0.3.0 → dp_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: A powerful CLI for DrissionPage — browser automation, structured data extraction, network listening and more.
 License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/mofanx/dp-cli
@@ -119,8 +119,13 @@ Results are deduplicated by `backendNodeId` and rendered with confidence markers
 | Marker | Confidence | Triggers |
 |--------|-----------|----------|
 | none   | **high**   | `<a href>`, `<button>`, `<input>`, `role=button/link/...`, `contenteditable` |
-| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>` |
-| `?`    | **low**    | `cursor:pointer` / class keyword match (`btn` / `click` / `toggle` / …) |
+| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>`, or `cursor:pointer` + heuristic (aria-label / icon child / small square / class keyword) — **catches most React/Vue icon buttons** |
+| `?`    | **low**    | bare `cursor:pointer` / class keyword only (no other signals); hidden unless `--include-low` |
+
+Output includes helpful context:
+- `@top-left`, `@top-right`, `@center`, `@bottom` … — position in the 9-region viewport grid
+- `(icon)` — icon-only button (no visible label, has `<svg>` / `<img>` child)
+- Shadow DOM is traversed automatically (open shadow roots)
 
 Every element gets an `[N]` ref usable in any command: `dp click "ref:5"`.
 

{dp_cli-0.3.0 → dp_cli-0.3.2}/README.md

@@ -98,8 +98,13 @@ Results are deduplicated by `backendNodeId` and rendered with confidence markers
 | Marker | Confidence | Triggers |
 |--------|-----------|----------|
 | none   | **high**   | `<a href>`, `<button>`, `<input>`, `role=button/link/...`, `contenteditable` |
-| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>` |
-| `?`    | **low**    | `cursor:pointer` / class keyword match (`btn` / `click` / `toggle` / …) |
+| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>`, or `cursor:pointer` + heuristic (aria-label / icon child / small square / class keyword) — **catches most React/Vue icon buttons** |
+| `?`    | **low**    | bare `cursor:pointer` / class keyword only (no other signals); hidden unless `--include-low` |
+
+Output includes helpful context:
+- `@top-left`, `@top-right`, `@center`, `@bottom` … — position in the 9-region viewport grid
+- `(icon)` — icon-only button (no visible label, has `<svg>` / `<img>` child)
+- Shadow DOM is traversed automatically (open shadow roots)
 
 Every element gets an `[N]` ref usable in any command: `dp click "ref:5"`.
 

{dp_cli-0.3.0 → dp_cli-0.3.2}/dp_cli/commands/_utils.py

@@ -106,11 +106,55 @@ def normalize_locator(loc: str) -> str:
     return loc
 
 
-def resolve_locator(locator: str, session: str = 'default') -> str:
+def _mark_element_by_backend_id(page, backend_node_id: int) -> str:
+    """通过 CDP 给指定 backendNodeId 的元素打一个临时 data-dp-ref 属性，
+    返回 marker 字符串，调用方可用 @data-dp-ref=<marker> 精确定位。
+
+    这是 ref:N → Element 的最鲁棒通路：
+      - 绕开 CSS Modules / React 动态 class 命名
+      - 绕开 xpath 结构变化
+      - 只要 DOM 节点还在，backendNodeId 稳定
+
+    失败（节点已不存在、CDP 异常）返回 None。
+    """
+    import uuid
+    marker = 'dp' + uuid.uuid4().hex[:12]
+    try:
+        res = page.run_cdp('DOM.resolveNode', backendNodeId=int(backend_node_id))
+    except Exception:
+        return None
+    if not isinstance(res, dict):
+        return None
+    obj_id = (res.get('object') or {}).get('objectId')
+    if not obj_id:
+        return None
+    try:
+        page.run_cdp(
+            'Runtime.callFunctionOn',
+            objectId=obj_id,
+            functionDeclaration=(
+                'function(m){'
+                'try{this.setAttribute("data-dp-ref", m);}catch(e){}'
+                '}'
+            ),
+            arguments=[{'value': marker}],
+            returnByValue=True,
+        )
+    except Exception:
+        return None
+    return marker
+
+
+def resolve_locator(locator: str, session: str = 'default', page=None) -> str:
     """解析定位器：ref:N 展开 + 智能前缀补全。
 
-    如果 locator 以 'ref:' 开头，从 session 的 refs 映射中查找真实定位器。
-    否则尝试智能补全 css:/xpath: 前缀。
+    如果 locator 以 'ref:' 开头，从 session 的 refs 映射中查找。
+      - 有 backendNodeId 时：通过 CDP 现场打临时属性，返回 @data-dp-ref=<marker>
+        （最鲁棒，绕开 CSS Modules / 动态 class / xpath 变化）
+      - 无 backendNodeId 或打标失败时：回落到保存的 locator 字符串
+      - 再失败，用 name 作 text 定位器
+
+    :param page: 可选，传入避免内部再调用 _get_page；为 None 时按需懒加载。
     """
     if not locator.startswith('ref:'):
         return normalize_locator(locator)
@@ -130,11 +174,27 @@ def resolve_locator(locator: str, session: str = 'default') -> str:
               code='REF_NOT_FOUND')
         raise SystemExit(1)
 
+    # 1. 首选：backendNodeId 打标
+    bid = ref_data.get('backendNodeId')
+    if bid:
+        if page is None:
+            try:
+                page = _get_page(session)
+            except SystemExit:
+                page = None
+            except Exception:
+                page = None
+        if page is not None:
+            marker = _mark_element_by_backend_id(page, bid)
+            if marker:
+                return f'@data-dp-ref={marker}'
+
+    # 2. 回退：原保存的 locator 字符串
     real_loc = ref_data.get('locator')
     if real_loc and not real_loc.startswith('t:'):
         return real_loc
 
-    # locator 不可用时（如 t:p），尝试用 name 作为 text 定位器
+    # 3. 再回退：用 name 作文字定位
     name = ref_data.get('name', '')
     if name and len(name) <= 50:
         return f'text:{name}'

{dp_cli-0.3.0 → dp_cli-0.3.2}/dp_cli/commands/snapshot_cmd.py

@@ -105,7 +105,9 @@ def register(cli):
     @click.option('--format', 'fmt', type=click.Choice(['text', 'json']),
                   default='text', show_default=True, help='输出格式')
     @click.option('--filename', default=None, help='保存到文件路径')
-    def scan(session, viewport_only, confidence, max_elements, fmt, filename):
+    @click.option('--verbose', '-v', is_flag=True, default=False,
+                  help='显示 detection reason 和像素尺寸（调试用）')
+    def scan(session, viewport_only, confidence, max_elements, fmt, filename, verbose):
         """Vimium 风格扫描当前页面的可交互元素（纯 DOM 遍历，不依赖 a11y tree）。
 
         \b
@@ -188,40 +190,26 @@ def register(cli):
             f'{len(filtered)} after filter'
             + (' (truncated)' if data.get('truncated') else '')
         )
-        rendered_lines.append('- 用 ref:N 引用元素（⚡ = medium, ? = low）')
+        rendered_lines.append(
+            '- ⚡ = medium, ? = low；@zone = 位置区域（top-left/top-right/… 9 宫格）；'
+            '(icon) = 仅图标按钮；用 ref:N 引用'
+        )
         rendered_lines.append('')
 
-        # 置信度标记
-        marker_map = {'high': '', 'medium': '⚡ ', 'low': '? '}
+        from ..snapshot.clickable import format_clickable_record
 
         for i, rec in enumerate(filtered, start=1):
             refs[str(i)] = {
                 'locator': rec.get('locator') or '',
                 'role': f"clickable/{rec.get('tag', '')}",
-                'name': (rec.get('text') or '')[:100],
+                'name': (rec.get('label') or rec.get('text') or '')[:100],
                 'backendNodeId': rec.get('backendNodeId'),
                 'confidence': rec.get('confidence'),
                 'reason': rec.get('reason'),
+                'zone': rec.get('zone'),
+                'iconOnly': bool(rec.get('iconOnly')),
             }
-            marker = marker_map.get(rec.get('confidence'), '')
-            tag = rec.get('tag', '')
-            text = (rec.get('text') or '').strip()
-            reason = rec.get('reason') or ''
-            rect = rec.get('rect') or {}
-            loc = rec.get('locator') or ''
-
-            parts = [f'- [{i}] {marker}{tag}']
-            if text:
-                disp = text[:80] + '…' if len(text) > 80 else text
-                parts.append(f'"{disp}"')
-            meta_bits = [reason]
-            if rect.get('w'):
-                meta_bits.append(f'{rect["w"]}x{rect["h"]}')
-                meta_bits.append(f'@{rect.get("x", 0)},{rect.get("y", 0)}')
-            parts.append(f'({", ".join(meta_bits)})')
-            if loc:
-                parts.append(f'→ {loc}')
-            rendered_lines.append(' '.join(parts))
+            rendered_lines.append('- ' + format_clickable_record(rec, i, verbose=verbose))
 
         # 保存 refs 到 session
         if refs:

{dp_cli-0.3.0 → dp_cli-0.3.2}/dp_cli/snapshot/a11y.py

@@ -219,7 +219,7 @@ def render_a11y_text(snapshot: dict, verbose: bool = False,
     # ── 追加 clickable_extras（a11y tree 漏掉的可交互元素）──
     extras = snapshot.get('clickable_extras') or []
     if extras:
-        from .clickable import CONFIDENCE_MARKER
+        from .clickable import format_clickable_record
         lines.append('')
         meta = snapshot.get('clickable_meta') or {}
         header_suffix = []
@@ -232,38 +232,23 @@ def render_a11y_text(snapshot: dict, verbose: bool = False,
         lines.append(f'### Additional Interactive Elements'
                      f' (Vimium-style, not in a11y tree){suffix_str}')
         lines.append(f'- 共 {len(extras)} 个；⚡ = medium 置信, ? = low 置信；'
-                     f'用 ref:N 引用')
+                     f'@zone=位置区域（top-left/top-right/center/… 9 宫格）；'
+                     f'(icon)=仅图标；用 ref:N 引用')
         lines.append('')
         for rec in extras:
             ctx['counter'] += 1
             rid = ctx['counter']
-            marker = CONFIDENCE_MARKER.get(rec.get('confidence'), '')
-            tag = rec.get('tag', '')
-            text = (rec.get('text') or '').strip()
-            reason = rec.get('reason') or ''
-            loc = rec.get('locator') or ''
-            rect = rec.get('rect') or {}
-
-            parts = [f'- [{rid}] {marker}{tag}']
-            if text:
-                display_text = text[:80] + '…' if len(text) > 80 else text
-                parts.append(f'"{display_text}"')
-            meta_parts = [reason]
-            if rect.get('w'):
-                meta_parts.append(f'{rect["w"]}x{rect["h"]}')
-            parts.append(f'({", ".join(meta_parts)})')
-            if loc:
-                parts.append(f'→ {loc}')
-            lines.append(' '.join(parts))
-
+            lines.append('- ' + format_clickable_record(rec, rid))
             # 记入 refs 以便 click/fill 引用
             ctx['refs'][str(rid)] = {
-                'locator': loc,
-                'role': f'clickable/{tag}',
-                'name': text[:100],
+                'locator': rec.get('locator') or '',
+                'role': f"clickable/{rec.get('tag', '')}",
+                'name': (rec.get('label') or rec.get('text') or '')[:100],
                 'backendNodeId': rec.get('backendNodeId'),
                 'confidence': rec.get('confidence'),
-                'reason': reason,
+                'reason': rec.get('reason'),
+                'zone': rec.get('zone'),
+                'iconOnly': bool(rec.get('iconOnly')),
             }
 
     if snapshot.get('clickable_warning'):

{dp_cli-0.3.0 → dp_cli-0.3.2}/dp_cli/snapshot/clickable.py

@@ -106,6 +106,9 @@ def detect_clickables(page,
             'confidence': e.get('confidence'),
             'reason': e.get('reason'),
             'text': e.get('text'),
+            'label': e.get('label'),
+            'iconOnly': bool(e.get('iconOnly')),
+            'zone': e.get('zone'),
             'rect': e.get('rect'),
             'inViewport': e.get('inViewport'),
             'backendNodeId': backend_node_id,
@@ -167,31 +170,41 @@ CONFIDENCE_MARKER = {
 }
 
 
-def format_clickable_record(rec: dict, ref_id: int) -> str:
+def format_clickable_record(rec: dict, ref_id: int, verbose: bool = False) -> str:
     """把一条 ClickableRecord 渲染成一行文本。
 
-    示例：
-      [42] ⚡ button "Sign in" (role=button, pos=120,340, 80x32) → #signin
-      [43] ? span "•••" (cursor:pointer, pos=200,150, 24x24) → .more-icon
+    默认紧凑格式（给 AI / 用户看，强调有用信息）：
+      [5] button "Sign in" @top-right → #signin
+      [8] ⚡ div "User profile" @top-left (icon) → .user-menu-btn
+      [9] ⚡ svg @top-right (icon) → xpath://header//svg[3]
+      [12] ? span "see more" @bottom → css:.footer > span:nth-child(3)
+
+    verbose=True 时追加 reason + 尺寸，用于调试：
+      [5] button "Sign in" @top-right (button, 80x32) → #signin
     """
     marker = CONFIDENCE_MARKER.get(rec.get('confidence'), '')
     tag = rec.get('tag', '')
-    text = rec.get('text') or ''
+    label = (rec.get('label') or rec.get('text') or '').strip()
+    zone = rec.get('zone') or ''
+    icon_only = bool(rec.get('iconOnly'))
     reason = rec.get('reason') or ''
     rect = rec.get('rect') or {}
     loc = rec.get('locator') or ''
 
     parts = [f'[{ref_id}]', f'{marker}{tag}']
-    if text:
-        parts.append(f'"{text[:80]}"')
-    rect_str = ''
-    if rect:
-        rect_str = f'{rect.get("w", 0)}x{rect.get("h", 0)}@{rect.get("x", 0)},{rect.get("y", 0)}'
-    meta = f'({reason}'
-    if rect_str:
-        meta += f', {rect_str}'
-    meta += ')'
-    parts.append(meta)
+    if label:
+        display = label[:80] + '…' if len(label) > 80 else label
+        parts.append(f'"{display}"')
+    elif icon_only:
+        # 无 label 但有 icon：标注 (icon) 提示这是图标按钮
+        parts.append('(icon)')
+    if zone:
+        parts.append(f'@{zone}')
+    if verbose:
+        meta_bits = [reason]
+        if rect.get('w'):
+            meta_bits.append(f'{rect["w"]}x{rect["h"]}')
+        parts.append(f'({", ".join(meta_bits)})')
     if loc:
         parts.append(f'→ {loc}')
     return ' '.join(parts)