dp-cli 0.2.0__tar.gz → 0.3.1__tar.gz

{dp_cli-0.2.0 → dp_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -26,10 +26,15 @@ A powerful CLI for [DrissionPage](https://github.com/g1879/DrissionPage) — bro
 ## Features
 
 - **Anti-detection by default** — not based on webdriver, `navigator.webdriver` is `false`
-- **Reuse your own browser** — connect to a running Chrome via `--port`, keeping login state and cookies
-- **Powerful locator syntax** — descriptive strings stable across navigation (no ephemeral refs)
-- **Structured data extraction** — `extract` + `query` + `snapshot --mode content` for scraping list pages
+- **Reuse your own browser** — `--auto-connect` (Chrome 144+, no CLI flag needed) or `--port`
+- **Hybrid snapshot** — a11y tree + Vimium-style clickable detection, catches icon-only buttons
+  and custom menu items the a11y tree misses; every element gets an `[N]` ref with
+  confidence markers (`⚡` medium, `?` low)
+- **`dp scan`** — fast Vimium-style listing of interactive elements (viewport-only mode available)
+- **Powerful locator syntax** — descriptive strings stable across navigation
+- **Structured data extraction** — `extract` + `query` + `snapshot` for scraping list pages
 - **Network listening** — capture XHR/Fetch requests and response bodies
+- **Stealth patches** — `dp stealth` bypasses common automation detections
 - **Dual mode** — browser control + pure HTTP requests
 - **Shadow-root / iframe** — traverse directly without switching context
 - **JSON output** — all commands output JSON, AI-friendly
@@ -99,6 +104,52 @@ the bridge automatically and never quits your Chrome (it's your browser, not dp'
 - Works with whatever profile Chrome is actually using — same cookies, logins, history.
 - Classic `--remote-debugging-port=9222` mode still works unchanged via `dp open --port 9222`.
 
+## Hybrid Snapshot (a11y + Vimium-style)
+
+The default `dp snapshot` fuses two element-discovery paths:
+
+1. **Browser a11y tree** via CDP — the structural skeleton (headings, lists, form roles,
+   explicit `<a>`/`<button>`, any `role="..."` element).
+2. **Vimium-style clickable detection** — a JS probe that flags icon-only buttons,
+   `<div onclick>`, `[tabindex>=0]`, `aria-selected`, `cursor:pointer` elements, etc.
+   that the a11y tree misses.
+
+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>`, 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"`.
+
+```bash
+dp snapshot                     # a11y + clickable (default); high + medium markers
+dp snapshot --viewport-only     # clickable probe limited to viewport (faster)
+dp snapshot --include-low       # also surface `?` low-confidence heuristics
+dp snapshot --no-clickables     # a11y tree only (legacy behavior)
+```
+
+### `dp scan` — fast clickable-only listing
+
+When you only need "what can I click next?" without the full a11y tree:
+
+```bash
+dp scan                         # full page, high+medium
+dp scan --viewport              # only elements currently in viewport
+dp scan --confidence all        # include low-confidence heuristics
+dp scan --confidence high       # only the sure-thing clickables
+```
+
+Both `snapshot` and `scan` share the same `[N]` ref numbering per session, so
+`dp click "ref:N"` works regardless of which one produced the snapshot.
+
 ## Anti-Detection (stealth)
 
 Bypass `navigator.webdriver`, `HeadlessChrome` UA, empty `plugins`, SwiftShader WebGL,

{dp_cli-0.2.0 → dp_cli-0.3.1}/README.md

@@ -5,10 +5,15 @@ A powerful CLI for [DrissionPage](https://github.com/g1879/DrissionPage) — bro
 ## Features
 
 - **Anti-detection by default** — not based on webdriver, `navigator.webdriver` is `false`
-- **Reuse your own browser** — connect to a running Chrome via `--port`, keeping login state and cookies
-- **Powerful locator syntax** — descriptive strings stable across navigation (no ephemeral refs)
-- **Structured data extraction** — `extract` + `query` + `snapshot --mode content` for scraping list pages
+- **Reuse your own browser** — `--auto-connect` (Chrome 144+, no CLI flag needed) or `--port`
+- **Hybrid snapshot** — a11y tree + Vimium-style clickable detection, catches icon-only buttons
+  and custom menu items the a11y tree misses; every element gets an `[N]` ref with
+  confidence markers (`⚡` medium, `?` low)
+- **`dp scan`** — fast Vimium-style listing of interactive elements (viewport-only mode available)
+- **Powerful locator syntax** — descriptive strings stable across navigation
+- **Structured data extraction** — `extract` + `query` + `snapshot` for scraping list pages
 - **Network listening** — capture XHR/Fetch requests and response bodies
+- **Stealth patches** — `dp stealth` bypasses common automation detections
 - **Dual mode** — browser control + pure HTTP requests
 - **Shadow-root / iframe** — traverse directly without switching context
 - **JSON output** — all commands output JSON, AI-friendly
@@ -78,6 +83,52 @@ the bridge automatically and never quits your Chrome (it's your browser, not dp'
 - Works with whatever profile Chrome is actually using — same cookies, logins, history.
 - Classic `--remote-debugging-port=9222` mode still works unchanged via `dp open --port 9222`.
 
+## Hybrid Snapshot (a11y + Vimium-style)
+
+The default `dp snapshot` fuses two element-discovery paths:
+
+1. **Browser a11y tree** via CDP — the structural skeleton (headings, lists, form roles,
+   explicit `<a>`/`<button>`, any `role="..."` element).
+2. **Vimium-style clickable detection** — a JS probe that flags icon-only buttons,
+   `<div onclick>`, `[tabindex>=0]`, `aria-selected`, `cursor:pointer` elements, etc.
+   that the a11y tree misses.
+
+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>`, 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"`.
+
+```bash
+dp snapshot                     # a11y + clickable (default); high + medium markers
+dp snapshot --viewport-only     # clickable probe limited to viewport (faster)
+dp snapshot --include-low       # also surface `?` low-confidence heuristics
+dp snapshot --no-clickables     # a11y tree only (legacy behavior)
+```
+
+### `dp scan` — fast clickable-only listing
+
+When you only need "what can I click next?" without the full a11y tree:
+
+```bash
+dp scan                         # full page, high+medium
+dp scan --viewport              # only elements currently in viewport
+dp scan --confidence all        # include low-confidence heuristics
+dp scan --confidence high       # only the sure-thing clickables
+```
+
+Both `snapshot` and `scan` share the same `[N]` ref numbering per session, so
+`dp click "ref:N"` works regardless of which one produced the snapshot.
+
 ## Anti-Detection (stealth)
 
 Bypass `navigator.webdriver`, `HeadlessChrome` UA, empty `plugins`, SwiftShader WebGL,

{dp_cli-0.2.0 → dp_cli-0.3.1}/dp_cli/commands/snapshot_cmd.py

@@ -9,7 +9,7 @@ from dp_cli.output import ok, error
 from dp_cli.session import save_refs
 from dp_cli.snapshot import (extract_structured, query_elements,
                               take_a11y_snapshot, render_a11y_text,
-                              render_a11y_plain_text)
+                              render_a11y_plain_text, detect_clickables)
 from dp_cli.snapshot.utils import suggest_locator
 from dp_cli.commands._utils import session_option, _get_page, records_to_csv, resolve_locator
 
@@ -25,8 +25,15 @@ def register(cli):
     @click.option('--format', 'fmt', type=click.Choice(['json', 'text']),
                   default='text', show_default=True, help='输出格式')
     @click.option('--filename', default=None, help='保存到文件路径')
-    def snapshot(session, mode, selector, fmt, filename):
-        """获取页面快照（基于浏览器原生 a11y tree，通用性极强）。
+    @click.option('--no-clickables', is_flag=True, default=False,
+                  help='禁用 Vimium 风格可交互元素补充探测（默认开启）')
+    @click.option('--include-low', is_flag=True, default=False,
+                  help='包含 low 置信度元素（cursor:pointer / class 规则匹配，可能假阳性）')
+    @click.option('--viewport-only', is_flag=True, default=False,
+                  help='补充探测只看视口内元素（省 token、更快）')
+    def snapshot(session, mode, selector, fmt, filename,
+                 no_clickables, include_low, viewport_only):
+        """获取页面快照（a11y tree + Vimium 风格可交互元素补充）。
 
         \b
         模式说明（默认 full）:
@@ -34,18 +41,30 @@ def register(cli):
           brief  精简模式，保留结构+交互，截断长文本（省 token）
           text   纯文本模式，按阅读顺序输出可见文本
 
+        \b
+        可交互元素补充探测（默认开启）:
+          a11y tree 会漏掉纯图标按钮、弹窗菜单项等未标 ARIA role 的元素。
+          补充探测会扫描 DOM，按 Vimium 规则识别这类元素并给出 ref:N 引用。
+          输出中以 ⚡ 标记 medium 置信度，? 标记 low 置信度。
+
         \b
         示例:
-          dp snapshot                          # 完整快照（推荐首次调用）
+          dp snapshot                          # 完整快照（默认含 clickable 补充）
           dp snapshot --mode brief             # 精简模式（省 token，适合循环调用）
-          dp snapshot --mode text              # 纯文本（全量文字内容）
-          dp snapshot --selector ".main"        # 只获取指定区域
-          dp snapshot --format json            # JSON 格式输出
+          dp snapshot --viewport-only          # 只扫视口内，更快
+          dp snapshot --include-low            # 启用 low 置信度（可能假阳性）
+          dp snapshot --no-clickables          # 纯 a11y tree，旧版本行为
+          dp snapshot --selector ".main"       # 只获取指定区域
         """
         page = _get_page(session)
 
         try:
-            data = take_a11y_snapshot(page, selector=selector)
+            data = take_a11y_snapshot(
+                page, selector=selector,
+                with_clickables=not no_clickables,
+                include_low=include_low,
+                viewport_only=viewport_only,
+            )
         except Exception as e:
             error('获取页面快照失败', code='SNAPSHOT_FAILED', detail=str(e))
             return
@@ -74,6 +93,152 @@ def register(cli):
         else:
             click.echo(output)
 
+    @cli.command('scan')
+    @session_option
+    @click.option('--viewport', 'viewport_only', is_flag=True, default=False,
+                  help='只扫描视口内元素（更快、更少结果）')
+    @click.option('--confidence', default='high,medium', show_default=True,
+                  help='逗号分隔的置信度过滤，可选 high / medium / low；'
+                       '使用 "all" 等价于 high,medium,low')
+    @click.option('--max', 'max_elements', default=1000, show_default=True,
+                  help='最多返回多少个元素')
+    @click.option('--format', 'fmt', type=click.Choice(['text', 'json']),
+                  default='text', show_default=True, help='输出格式')
+    @click.option('--filename', default=None, help='保存到文件路径')
+    @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
+        与 dp snapshot 的区别:
+          snapshot  返回完整 a11y tree + clickable 补充（大、慢、全面）
+          scan      只返回可交互元素清单（小、快、适合执行脚本）
+
+        \b
+        置信度分级:
+          high    明确可点击（<a href>, <button>, role=button 等）
+          medium  很可能可点击（onclick / jsaction / tabindex / aria-selected）
+          low     启发式匹配（cursor:pointer / class 含 btn/click/… 关键词）
+          默认只返回 high + medium；用 --confidence all 看全部
+
+        \b
+        输出的每个元素都有 [N] 编号，可直接 dp click "ref:N" 引用。
+        输出中 ⚡ 标记 medium 置信度，? 标记 low 置信度。
+
+        \b
+        示例:
+          dp scan                                # 扫全页，high + medium
+          dp scan --viewport                     # 只扫视口内
+          dp scan --confidence high              # 只要高置信度
+          dp scan --confidence all               # 包含 low 置信度
+          dp scan --format json                  # JSON 输出
+        """
+        # 解析 confidence 过滤
+        conf_str = (confidence or '').strip().lower()
+        if conf_str == 'all':
+            wanted = {'high', 'medium', 'low'}
+        else:
+            wanted = {c.strip() for c in conf_str.split(',') if c.strip()}
+        unknown = wanted - {'high', 'medium', 'low'}
+        if unknown:
+            error('无效的置信度值', code='INVALID_CONFIDENCE',
+                  detail=f'unknown: {sorted(unknown)}; 可选: high, medium, low, all')
+            return
+        include_low = 'low' in wanted
+
+        page = _get_page(session)
+        try:
+            data = detect_clickables(
+                page,
+                viewport_only=viewport_only,
+                max_elements=max_elements,
+                include_low=include_low,
+            )
+        except Exception as e:
+            error('扫描失败', code='SCAN_FAILED', detail=str(e))
+            return
+
+        if data.get('method') == 'failed':
+            error('扫描失败', code='SCAN_FAILED',
+                  detail=data.get('error', '未知'))
+            return
+
+        # 置信度过滤（JS 的 include_low 控制是否 *生成* low；
+        # 这里再按 wanted 精确过滤——例如用户只要 high）
+        filtered = [e for e in data.get('elements', [])
+                    if e.get('confidence') in wanted]
+
+        # 分配 ref:N 并保存到 session
+        refs = {}
+        url = page.url
+        title = page.title
+        rendered_lines = []
+
+        # 头部
+        mode_parts = []
+        if viewport_only:
+            mode_parts.append('viewport')
+        mode_parts.append(f"confidence={','.join(sorted(wanted))}")
+        mode_tag = ', '.join(mode_parts)
+
+        rendered_lines.append(f'### Clickable Scan ({mode_tag})')
+        rendered_lines.append(f'- URL: {url}')
+        rendered_lines.append(f'- Title: {title}')
+        rendered_lines.append(
+            f'- Detected: {data.get("total", 0)} total, '
+            f'{len(filtered)} after filter'
+            + (' (truncated)' if data.get('truncated') else '')
+        )
+        rendered_lines.append(
+            '- ⚡ = medium, ? = low；@zone = 位置区域（top-left/top-right/… 9 宫格）；'
+            '(icon) = 仅图标按钮；用 ref:N 引用'
+        )
+        rendered_lines.append('')
+
+        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('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')),
+            }
+            rendered_lines.append('- ' + format_clickable_record(rec, i, verbose=verbose))
+
+        # 保存 refs 到 session
+        if refs:
+            save_refs(session, url, refs)
+
+        if fmt == 'json':
+            output = json.dumps({
+                'status': 'ok',
+                'data': {
+                    'page': {'url': url, 'title': title},
+                    'meta': {
+                        'total_detected': data.get('total'),
+                        'after_filter': len(filtered),
+                        'truncated': data.get('truncated'),
+                        'viewport_only': viewport_only,
+                        'confidence_filter': sorted(wanted),
+                    },
+                    'elements': filtered,
+                }
+            }, ensure_ascii=False, indent=2)
+        else:
+            output = '\n'.join(rendered_lines)
+
+        if filename:
+            Path(filename).write_text(output, encoding='utf-8')
+            ok(msg=f'扫描结果已保存到 {filename}')
+        else:
+            click.echo(output)
+
     @cli.command('extract')
     @session_option
     @click.argument('container')

dp_cli-0.3.1/dp_cli/snapshot/__init__.py

@@ -0,0 +1,28 @@
+# -*- coding:utf-8 -*-
+"""
+dp-cli snapshot 模块
+
+基于浏览器原生 a11y tree（无障碍树）的页面快照系统。
+通过 CDP Accessibility API 获取，通用性极强，适用于 95%+ 的网站。
+
+模块组成：
+  - a11y.py          核心：a11y tree 获取 + 多模式渲染（full/brief/text）
+  - clickable.py     Vimium 风格可交互元素探测（补充 a11y tree 覆盖盲区）
+  - clickable_js.py  注入浏览器的 JS 探测脚本
+  - extract.py       数据提取（extract_structured / query_elements）
+  - utils.py         共享工具（定位器生成等）
+  - js_scripts.py    JS 降级脚本（CDP 不可用时的 fallback）
+"""
+from .a11y import take_a11y_snapshot, render_a11y_text, render_a11y_plain_text
+from .clickable import detect_clickables, format_clickable_record
+from .extract import extract_structured, query_elements
+
+__all__ = [
+    'take_a11y_snapshot',
+    'render_a11y_text',
+    'render_a11y_plain_text',
+    'detect_clickables',
+    'format_clickable_record',
+    'extract_structured',
+    'query_elements',
+]

{dp_cli-0.2.0 → dp_cli-0.3.1}/dp_cli/snapshot/a11y.py

@@ -50,14 +50,24 @@ _REF_CONTENT_ROLES = frozenset({
 })
 
 
-def take_a11y_snapshot(page, selector=None, max_depth=None) -> dict:
+def take_a11y_snapshot(page, selector=None, max_depth=None,
+                       with_clickables: bool = True,
+                       include_low: bool = False,
+                       viewport_only: bool = False) -> dict:
     """
-    获取页面 a11y tree。
+    获取页面 a11y tree，并（可选）合并 Vimium 风格的可点击元素探测。
 
     :param page: DrissionPage 的 ChromiumPage 对象
     :param selector: CSS 选择器，限定子树范围（可选）
     :param max_depth: 最大深度限制（可选，传给 CDP）
-    :return: 标准化的 a11y tree 数据
+    :param with_clickables: True 时额外运行 clickable 探测并合并到快照；
+                            收集 a11y tree 漏掉的可交互元素（如纯图标按钮、
+                            弹窗菜单项等）
+    :param include_low: with_clickables=True 时，是否包含 low 置信度元素
+                        （cursor:pointer 或 class-pattern 启发式匹配）
+    :param viewport_only: with_clickables=True 时，是否只探测视口内可见元素
+    :return: 标准化的 a11y tree 数据；若 with_clickables=True，
+             额外带 'clickable_extras' 字段（补充 a11y tree 未覆盖的可交互元素）
     """
     page.wait.doc_loaded()
     page_info = {'url': page.url, 'title': page.title}
@@ -91,6 +101,42 @@ def take_a11y_snapshot(page, selector=None, max_depth=None) -> dict:
         }
         if selector_warning:
             result['warning'] = selector_warning
+
+        # ── 可选：合并 clickable 探测结果 ──
+        # 注意：clickable 必须自己建 bid_map —— 它的 JS 会给元素加
+        # data-dp-scan-id 临时属性，bid_map 必须在那之后再建才能包含 scan-id
+        if with_clickables:
+            try:
+                from .clickable import detect_clickables
+                clk = detect_clickables(
+                    page,
+                    viewport_only=viewport_only,
+                    include_low=include_low,
+                )
+                # 收集 a11y tree 已覆盖的 backendNodeId（有 locator 的交互节点）
+                covered = {n['backendNodeId'] for n in normalized
+                           if n.get('backendNodeId')
+                           and n.get('locator')
+                           and n['role'] in _INTERACTIVE_ROLES}
+                # 过滤出 a11y 未覆盖的元素
+                extras = [e for e in clk.get('elements', [])
+                          if not (e.get('backendNodeId')
+                                  and e['backendNodeId'] in covered)]
+                # 过滤策略：如果有 rect 且 w/h < 2，跳过（已在 JS 过滤过，双保险）
+                extras = [e for e in extras
+                          if e.get('rect') and e['rect'].get('w', 0) >= 2]
+                result['clickable_extras'] = extras
+                result['clickable_meta'] = {
+                    'total_detected': clk.get('total', 0),
+                    'covered_by_a11y': clk.get('total', 0) - len(extras),
+                    'extras': len(extras),
+                    'truncated': clk.get('truncated', False),
+                    'viewport_only': viewport_only,
+                    'include_low': include_low,
+                }
+            except Exception as ce:
+                result['clickable_warning'] = f'clickable 探测失败（非致命）：{ce}'
+
         return result
     except Exception as cdp_err:
         cdp_error_msg = str(cdp_err)
@@ -170,12 +216,54 @@ def render_a11y_text(snapshot: dict, verbose: bool = False,
     else:
         lines.append('（a11y tree 为空）')
 
+    # ── 追加 clickable_extras（a11y tree 漏掉的可交互元素）──
+    extras = snapshot.get('clickable_extras') or []
+    if extras:
+        from .clickable import format_clickable_record
+        lines.append('')
+        meta = snapshot.get('clickable_meta') or {}
+        header_suffix = []
+        if meta.get('viewport_only'):
+            header_suffix.append('viewport-only')
+        if meta.get('include_low'):
+            header_suffix.append('include-low')
+        suffix_str = (f' — {", ".join(header_suffix)}'
+                      if header_suffix else '')
+        lines.append(f'### Additional Interactive Elements'
+                     f' (Vimium-style, not in a11y tree){suffix_str}')
+        lines.append(f'- 共 {len(extras)} 个；⚡ = medium 置信, ? = low 置信；'
+                     f'@zone=位置区域（top-left/top-right/center/… 9 宫格）；'
+                     f'(icon)=仅图标；用 ref:N 引用')
+        lines.append('')
+        for rec in extras:
+            ctx['counter'] += 1
+            rid = ctx['counter']
+            lines.append('- ' + format_clickable_record(rec, rid))
+            # 记入 refs 以便 click/fill 引用
+            ctx['refs'][str(rid)] = {
+                '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': rec.get('reason'),
+                'zone': rec.get('zone'),
+                'iconOnly': bool(rec.get('iconOnly')),
+            }
+
+    if snapshot.get('clickable_warning'):
+        lines.append('')
+        lines.append(f"⚠ {snapshot['clickable_warning']}")
+
     # 回填头部：包含 ref 统计
     ref_count = ctx['counter']
     lines[header_idx] = f'### Page Snapshot ({mode_label})'
-    lines[stats_idx] = (f"- Nodes: {stats.get('total', 0)} total, "
-                        f"{stats.get('interactive', 0)} interactive, "
-                        f"{ref_count} refs")
+    stats_line = (f"- Nodes: {stats.get('total', 0)} total, "
+                  f"{stats.get('interactive', 0)} interactive, "
+                  f"{ref_count} refs")
+    if extras:
+        stats_line += f" (含 {len(extras)} 个 a11y 外可交互)"
+    lines[stats_idx] = stats_line
     if ref_count > 0:
         lines[stats_idx] += f" — 使用 ref:N 引用元素，如 dp click \"ref:1\""
 
@@ -195,15 +283,29 @@ def render_a11y_plain_text(snapshot: dict, refs: dict = None) -> str:
     :return: 纯文本字符串
     """
     tree = snapshot.get('tree', {})
-    if not tree:
-        return ''
 
     # 如果需要收集 refs，在纯文本渲染过程中顺便收集
     if refs is not None:
         ctx = {'counter': 0, 'refs': refs}
-        _collect_refs_only(tree, ctx)
+        if tree:
+            _collect_refs_only(tree, ctx)
+        # 合并 clickable_extras 的 refs（与 full/brief 保持编号一致）
+        for rec in snapshot.get('clickable_extras') or []:
+            ctx['counter'] += 1
+            rid = ctx['counter']
+            ctx['refs'][str(rid)] = {
+                'locator': rec.get('locator') or '',
+                'role': f"clickable/{rec.get('tag', '')}",
+                'name': (rec.get('text') or '')[:100],
+                'backendNodeId': rec.get('backendNodeId'),
+                'confidence': rec.get('confidence'),
+                'reason': rec.get('reason'),
+            }
         refs.update(ctx['refs'])
 
+    if not tree:
+        return ''
+
     parts = []
     _collect_plain_text(tree, parts)
     return '\n'.join(parts)