mooncat-browser 0.1.0

package/browser-op/py/browser.py

@@ -0,0 +1,340 @@
+"""
+browserd Python 客户端 — 复刻 lib/web/browser.js 的 facade 模式.
+
+连接 PM2 Runtime 管理的 browserd, 通过 HTTP JSON-RPC (127.0.0.1:17322/rpc) 通信.
+业务脚本退出不影响 Chrome (browserd 持有它, 常驻).
+
+用法:
+    from browser import Browser
+    b = Browser()
+    bh = b.open(route_mode='auto')          # 自动起 browserd + 开浏览器
+    ph = b.find_or_new_tab('example.com')   # 找/开 tab
+    b.operate(ph, action='click', selector='#btn')
+    data = b.operate(ph, action='evaluate', source='() => document.title')
+    b.close()
+
+设计原则 (对齐 browser.js):
+  - handle 是纯数据, 绝不判断路由 (browser.js 铁律 1)
+  - 会话长生命周期, open 一次跨多步复用 (铁律 2)
+  - 步进落盘, 不一次做完 (铁律 3)
+  - Python 侧零路由判断, 全透传给 browserd
+"""
+from __future__ import annotations
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+# ─── 常量 (对齐 rpc-client.cjs) ───
+IPC_HOST = "127.0.0.1"
+IPC_PORT = 17322
+RPC_URL = f"http://{IPC_HOST}:{IPC_PORT}/rpc"
+HEALTH_URL = f"http://{IPC_HOST}:{IPC_PORT}/health"
+
+# browserd.cjs 路径: 本文件在 lib/py/, browserd 在 lib/backend/
+def _resolve_browserd_path() -> Path:
+    here = Path(__file__).resolve()
+    candidates = [
+        # Source and production runtime layout:
+        # libs/browser/py/browser.py -> libs/browser/backend/browserd.cjs
+        here.parent.parent / "backend" / "browserd.cjs",
+        # Distributed skillpack layout:
+        # browser/lib/py/browser.py -> browser/lib/backend/browserd.cjs
+        here.parent.parent.parent / "lib" / "backend" / "browserd.cjs",
+    ]
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    return candidates[0]
+
+
+BROWSERD_PATH = _resolve_browserd_path()
+
+# JSON-RPC 请求 id (Python 客户端单线程顺序递增即可)
+_rpc_seq = 0
+
+
+class BrowserdError(RuntimeError):
+    """browserd RPC 失败."""
+
+
+def _next_id() -> int:
+    global _rpc_seq
+    _rpc_seq += 1
+    return _rpc_seq
+
+
+def _health(timeout_ms: int = 2000) -> dict | None:
+    """探测 browserd 是否存活. 存活返回 health dict, 否则 None."""
+    try:
+        r = httpx.get(HEALTH_URL, timeout=timeout_ms / 1000)
+        if r.status_code == 200:
+            return r.json()
+    except (httpx.HTTPError, OSError):
+        pass
+    return None
+
+
+def _rpc(method: str, params: dict | None = None, timeout_ms: int = 60000) -> Any:
+    """发一个 JSON-RPC 请求到 browserd, 返回 result 或抛 BrowserdError."""
+    payload = {"id": _next_id(), "method": method, "params": params or {}}
+    try:
+        r = httpx.post(RPC_URL, json=payload, timeout=timeout_ms / 1000)
+        data = r.json()
+    except (httpx.HTTPError, json.JSONDecodeError) as e:
+        raise BrowserdError(f"rpc 通信失败 ({method}): {e}") from e
+
+    if not data.get("ok"):
+        raise BrowserdError(f"{method}: {data.get('error', 'rpc failed')}")
+    return data.get("result")
+
+
+def _ensure_browserd(timeout_ms: int = 15000) -> None:
+    """
+    检查 browserd 是否在跑. 不自动启动 — 进程生命周期由 PM2 Runtime 管理.
+    不活就报错, 提示用 `mooncat services start` 起.
+    """
+    if _health(2000):
+        return  # browserd 在跑
+
+    raise BrowserdError(
+        "browserd 未运行. 它现在由 PM2 Runtime 管理, 不再自动启动.\n"
+        "请先运行: mooncat services start\n"
+        "或单独起: mooncat services restart browserd"
+    )
+
+
+def _find_node() -> str | None:
+    """找 node 可执行文件."""
+    for name in ("node", "node.exe"):
+        for p in os.environ.get("PATH", "").split(os.pathsep):
+            f = Path(p) / name
+            if f.exists():
+                return str(f)
+    return None
+
+
+class Browser:
+    """
+    browserd 客户端 facade (对齐 browser.js 的导出函数).
+
+    生命周期:
+        b = Browser()
+        bh = b.open()                       # 起 browserd + 开浏览器 → browserHandle
+        ph = b.find_or_new_tab('url')       # → pageHandle
+        b.operate(ph, action='click', ...)  # 操作
+        b.close()                           # 关浏览器 + browserd (仅"完成"时调)
+    """
+
+    def __init__(self) -> None:
+        self._browser_open = False
+
+    # ─── 顶层 RPC (对齐 browser.js) ───
+
+    def open(
+        self,
+        route_mode: str = "auto",
+        headless: bool = False,
+        executable_path: str | None = None,
+        profile_root: str | None = None,
+        user_data_dir: str | None = None,
+    ) -> dict:
+        """
+        打开浏览器 (自动起 browserd + 开浏览器). 返回 browserHandle (纯数据).
+        route_mode: 'auto' | 'cdp' | 'plugin' (高危站点用 plugin/extension)
+        """
+        _ensure_browserd()
+        params: dict[str, Any] = {"routeMode": route_mode, "headless": headless}
+        if executable_path:
+            params["executablePath"] = executable_path
+        if profile_root:
+            params["profileRoot"] = profile_root
+        if user_data_dir:
+            params["userDataDir"] = user_data_dir
+        bh = _rpc("open", params, timeout_ms=120000)  # 开浏览器慢, 给 2 分钟
+        self._browser_open = True
+        return bh
+
+    def new_tab(self, url: str = "") -> dict:
+        """新建 tab. 返回 pageHandle (纯数据)."""
+        if not self._browser_open:
+            raise BrowserdError("browser not open; call open() first")
+        return _rpc("newTab", {"url": url})
+
+    def list_tabs(self) -> list[dict]:
+        """列出所有 tab, 每个 dict 含 pageHandle/url/title/active."""
+        if not self._browser_open:
+            raise BrowserdError("browser not open; call open() first")
+        return _rpc("listTabs", {})
+
+    def find_or_new_tab(
+        self,
+        url: str,
+        match: str = "includes",
+        new_if_missing: bool = True,
+    ) -> dict:
+        """
+        按 url 找已有 tab (复刻 browser.js findOrNewTab, 在客户端实现).
+        match: 'includes' (子串, 默认) | 'exact'
+        new_if_missing: 没找到是否新开 (True=新开, False=返回 None)
+        返回 pageHandle.
+        """
+        tabs = self.list_tabs()
+        for t in tabs:
+            t_url = t.get("url", "")
+            hit = (t_url == url) if match == "exact" else (url in t_url)
+            if hit and t.get("pageHandle"):
+                return t["pageHandle"]
+        if not new_if_missing:
+            return None  # type: ignore[return-value]
+        return self.new_tab(url)
+
+    def operate(
+        self,
+        page_handle: dict,
+        action: str,
+        timeout_ms: int = 60000,
+        **params: Any,
+    ) -> Any:
+        """
+        在 page 上执行一个 action (对齐 browser.js operate).
+        action 全集见 browserd.cjs: goto/click/fill/type/press/snapshot/evaluate/...
+        额外参数通过 **params 传 (selector/value/source/x/y/...).
+        """
+        if not self._browser_open:
+            raise BrowserdError("browser not open")
+        if not page_handle or not page_handle.get("pageId"):
+            raise BrowserdError("invalid pageHandle: missing pageId")
+        return _rpc(
+            "operate",
+            {"pageHandle": page_handle, "action": action, "params": params},
+            timeout_ms=timeout_ms,
+        )
+
+    def close(self) -> dict:
+        """关闭浏览器 + browserd daemon. 仅"完成"时调用."""
+        if not self._browser_open:
+            return {"ok": True, "note": "already closed"}
+        result = _rpc("close", {})
+        self._browser_open = False
+        return result
+
+    # ─── cookie (挂 browserHandle) ───
+
+    def get_cookies(self, browser_handle: dict | None = None) -> list[dict]:
+        return _rpc("getCookies", {"browserHandle": browser_handle or {}})
+
+    def set_cookies(self, cookies: list[dict], browser_handle: dict | None = None) -> dict:
+        return _rpc("setCookies", {"cookies": cookies, "browserHandle": browser_handle or {}})
+
+    def clear_cookies(self, browser_handle: dict | None = None) -> dict:
+        return _rpc("clearCookies", {"browserHandle": browser_handle or {}})
+
+    # ─── 便捷封装 (常用 action 的语法糖, 减少样板) ───
+
+    def goto(self, page_handle: dict, url: str) -> Any:
+        return self.operate(page_handle, "goto", url=url)  # type: ignore[arg-type]
+
+    def click(self, page_handle: dict, selector: str, x: float | None = None, y: float | None = None) -> Any:
+        p: dict[str, Any] = {"selector": selector}
+        if x is not None:
+            p["x"] = x
+        if y is not None:
+            p["y"] = y
+        return self.operate(page_handle, "click", **p)
+
+    def fill(self, page_handle: dict, selector: str, value: str) -> Any:
+        return self.operate(page_handle, "fill", selector=selector, value=value)
+
+    def press(self, page_handle: dict, selector: str, key: str) -> Any:
+        return self.operate(page_handle, "press", selector=selector, key=key)
+
+    def status(self, page_handle: dict) -> dict:
+        return self.operate(page_handle, "status")  # type: ignore[return-value]
+
+    def snapshot(self, page_handle: dict, **opts: Any) -> Any:
+        """aria 树 (探查 DOM)."""
+        return self.operate(page_handle, "snapshot", **opts)
+
+    def evaluate(self, page_handle: dict, source: str, args: list | None = None) -> Any:
+        """跑页面 JS (source 必须是函数表达式如 '() => document.title')."""
+        p: dict[str, Any] = {"source": source}
+        if args is not None:
+            p["args"] = args
+        return self.operate(page_handle, "evaluate", **p)
+
+    def screenshot(self, page_handle: dict) -> Any:
+        return self.operate(page_handle, "screenshot")
+
+    def inner_text(self, page_handle: dict, selector: str) -> str:
+        return self.operate(page_handle, "innerText", selector=selector)  # type: ignore[return-value]
+
+    def wait_for_selector(self, page_handle: dict, selector: str, timeout: int | None = None) -> Any:
+        p: dict[str, Any] = {"selector": selector}
+        if timeout is not None:
+            p["timeout"] = timeout
+        return self.operate(page_handle, "waitForSelector", **p)
+
+
+# ─── 模块级接口 (对齐 JS 的 operate/listTabs 等, 供 find/scroll/ready/humanize 等子模块用) ───
+# 用法: from browser import operate, list_tabs, new_tab, open_browser, find_or_new_tab, close_browser
+
+_default_browser: Browser | None = None
+
+
+def _get_browser() -> Browser:
+    global _default_browser
+    if _default_browser is None:
+        _default_browser = Browser()
+    return _default_browser
+
+
+def open_browser(**kwargs) -> dict:
+    """模块级 open (对齐 JS open)."""
+    return _get_browser().open(**kwargs)
+
+
+def new_tab(url: str = "") -> dict:
+    """模块级 newTab (对齐 JS newTab)."""
+    return _get_browser().new_tab(url)
+
+
+def list_tabs(browser_handle: dict | None = None) -> list[dict]:
+    """模块级 listTabs (对齐 JS listTabs)."""
+    return _get_browser().list_tabs()
+
+
+def find_or_new_tab(url: str, match: str = "includes", new_if_missing: bool = True) -> dict | None:
+    """模块级 findOrNewTab (对齐 JS findOrNewTab)."""
+    return _get_browser().find_or_new_tab(url, match, new_if_missing)
+
+
+def operate(page_handle: dict, params: dict) -> Any:
+    """
+    模块级 operate (对齐 JS operate(pageHandle, actionObj)).
+
+    params 是 dict, 必须含 'action' key, 其余 key 是 action 参数:
+      operate(ph, {"action": "click", "selector": "#btn"})
+      operate(ph, {"action": "evaluate", "source": "() => 1", "_skipVisualize": True})
+
+    特殊 key (不传给 browserd, 本地控制):
+      _skipVisualize / _skipHumanize / label — 忽略 (仅 JS 端用)
+    """
+    b = _get_browser()
+    action = params.get("action")
+    if not action:
+        raise ValueError("operate: params 缺 action")
+    # 提取 action 参数 (排除本地控制 key)
+    kwargs = {k: v for k, v in params.items() if k not in ("action", "_skipVisualize", "_skipHumanize", "label")}
+    return b.operate(page_handle, action, **kwargs)
+
+
+def close_browser() -> dict:
+    """模块级 close (对齐 JS close)."""
+    return _get_browser().close()

package/browser-op/py/captcha.py

@@ -0,0 +1,115 @@
+"""web/captcha — 验证码检测（多信号交叉验证，路由无关）
+
+忠实复刻 lib/web/captcha.js。
+信号：URL 关键词 / DOM selector / 页面标题关键词 / 预期内容缺失。
+基于 operate({action:'status'}) + operate({action:'evaluate'})。
+
+依赖：browser（operate）
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+sys.path.insert(0, __file__.rsplit("\\", 1)[0] if "\\" in __file__ else __file__.rsplit("/", 1)[0])
+from browser import operate  # noqa: E402
+
+URL_KEYWORDS = ['captcha', 'verify', 'geetest', 'dingxiang', 'challenge', 'slider', 'recaptcha', 'hcaptcha']
+TITLE_KEYWORDS = ['验证', 'captcha', 'security', 'verify', '人机', '安全验证']
+DOM_SELECTORS = [
+    '.geetest_', '#geetest', '.yidun', '.dx_captcha', '#captcha',
+    'iframe[src*="captcha"]', 'iframe[src*="recaptcha"]', 'iframe[src*="hcaptcha"]',
+    '.g-recaptcha', '.h-captcha',
+]
+
+
+# 探测页面是否含特定 captcha DOM
+def _dom_probe_source(selectors: list) -> str:
+    return ('() => {\n'
+            '  const sels = ' + json.dumps(selectors, separators=(',', ':')) + '\n'
+            '  const found = []\n'
+            '  for (const s of sels) { if (document.querySelector(s)) found.push(s) }\n'
+            '  return found\n'
+            '}')
+
+
+def detect(page_handle: dict, options: dict | None = None) -> dict:
+    """多信号验证码检测。
+
+    options:
+      expectedSelector: 正常页面应存在的 selector（缺失视为信号）
+    返回: {isCaptcha, confidence, signals, evidence}
+      confidence: 0~1；>=0.7 判 isCaptcha=true。
+      2+ 信号 → 0.95；1 强信号 → 0.7；1 弱信号（仅缺失）→ 0.3。
+    """
+    if options is None:
+        options = {}
+    if not page_handle:
+        raise ValueError('detect: pageHandle required')
+
+    signals: list[str] = []
+    evidence: list[str] = []
+
+    # 信号 1：URL 关键词
+    st = operate(page_handle, {'action': 'status'})
+    url = (st and (st.get('url') or st.get('value'))) or ''
+    url_hit = None
+    for k in URL_KEYWORDS:
+        if k in url.lower():
+            url_hit = k
+            break
+    if url_hit:
+        signals.append('url-keyword')
+        evidence.append('url contains "' + url_hit + '"')
+
+    # 信号 2：标题关键词
+    title = (st and st.get('title')) or ''
+    title_hit = None
+    for k in TITLE_KEYWORDS:
+        if k.lower() in title.lower():
+            title_hit = k
+            break
+    if title_hit:
+        signals.append('title-keyword')
+        evidence.append('title contains "' + title_hit + '"')
+
+    # 信号 3：captcha DOM
+    found = operate(page_handle, {'action': 'evaluate', 'source': _dom_probe_source(DOM_SELECTORS)})
+    if isinstance(found, list):
+        found_arr = found
+    elif isinstance(found, dict) and isinstance(found.get('value'), list):
+        found_arr = found['value']
+    else:
+        found_arr = []
+    if len(found_arr) > 0:
+        signals.append('dom-selector')
+        evidence.append('selectors: ' + ', '.join(found_arr))
+
+    # 信号 4：预期内容缺失（弱信号）
+    if options.get('expectedSelector'):
+        exp = operate(page_handle, {'action': 'evaluate', 'source': '(s) => !!document.querySelector(s)'})
+        if isinstance(exp, bool):
+            present = exp
+        elif isinstance(exp, dict) and isinstance(exp.get('value'), bool):
+            present = exp['value']
+        elif isinstance(exp, dict) and isinstance(exp.get('result'), bool):
+            present = exp['result']
+        else:
+            present = bool(exp)
+        if not present:
+            signals.append('expected-missing')
+            evidence.append('expected "' + options.get('expectedSelector') + '" not found')
+
+    # 置信度
+    confidence = 0
+    strong = len([s for s in signals if s != 'expected-missing'])
+    weak = 1 if 'expected-missing' in signals else 0
+    if strong >= 2:
+        confidence = 0.95
+    elif strong == 1:
+        confidence = 0.7
+    elif weak == 1:
+        confidence = 0.3
+
+    return {'isCaptcha': confidence >= 0.7, 'confidence': confidence, 'signals': signals, 'evidence': evidence}

package/browser-op/py/crawler.py

@@ -0,0 +1,125 @@
+"""web/crawler — 轻量爬虫 (URL 去重 + 深度控制 + 节流, 路由无关).
+
+忠实复刻 lib/web/crawler.js。
+基于 operate (goto + evaluate 提取链接/内容) 组合, 复用同一个 pageHandle (顺序导航)。
+
+依赖: browser (operate)
+"""
+from __future__ import annotations
+import json
+import time
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+import sys
+sys.path.insert(0, __file__.rsplit("\\", 1)[0] if "\\" in __file__ else __file__.rsplit("/", 1)[0])
+from browser import operate  # noqa: E402
+
+
+def _extract_source(base_domain: str) -> str:
+    return f"""() => {{
+      const title = document.title || "";
+      const text = (document.body && document.body.innerText) ? document.body.innerText.slice(0, 8000) : "";
+      const links = [];
+      const a = document.querySelectorAll("a[href]");
+      for (const el of a) {{
+        try {{
+          const u = new URL(el.href, location.href);
+          if (u.protocol !== "http:" && u.protocol !== "https:") continue;
+          links.push(u.href);
+        }} catch {{}}
+      }}
+      const base = {json.dumps(base_domain or "")};
+      const filtered = base ? links.filter((l) => {{ try {{ return new URL(l).hostname === base }} catch {{ return false }} }}) : links;
+      return {{ title, text, links: [...new Set(filtered)].slice(0, 200) }};
+    }}()"""
+
+
+def create_crawler(page_handle: dict, options: dict | None = None) -> dict:
+    """创建爬虫实例.
+
+    options:
+      maxPages: 最多爬取页数 (默认 50)
+      maxDepth: 最大链接深度 (默认 3)
+      delay: 请求间隔秒 (默认 0.5)
+      retries: 失败重试次数 (默认 2)
+      sameDomain: 是否限制同域 (默认 True)
+    返回: {{ crawl, results }}
+    """
+    if not page_handle:
+        raise ValueError("create_crawler: page_handle required")
+    opts = options or {}
+    max_pages = opts.get("maxPages", 50)
+    max_depth = opts.get("maxDepth", 3)
+    delay_sec = opts.get("delay", 0.5)
+    retries = opts.get("retries", 2)
+    same_domain = opts.get("sameDomain", True)
+
+    results = []
+
+    def fetch_page(url: str, depth: int) -> dict:
+        last_err = None
+        for attempt in range(retries + 1):
+            try:
+                operate(page_handle, {"action": "goto", "url": url, "timeout": 15000})
+                operate(page_handle, {"action": "waitForLoadState", "state": "complete"})
+                base_domain = ""
+                if same_domain:
+                    try:
+                        base_domain = urlparse(url).hostname or ""
+                    except Exception:
+                        pass
+                data = operate(page_handle, {"action": "evaluate", "source": _extract_source(base_domain)})
+                d = {}
+                if isinstance(data, dict):
+                    if "title" in data or "links" in data:
+                        d = data
+                    elif "value" in data:
+                        d = data["value"]
+                return {"title": d.get("title", ""), "text": d.get("text", ""), "links": d.get("links", [])}
+            except Exception as e:
+                last_err = e
+                time.sleep(0.5)
+        raise last_err or RuntimeError("fetchPage failed")
+
+    def crawl(start_url: str) -> list[dict]:
+        queue = [{"url": start_url, "depth": 0}]
+        visited = set()
+        start_domain = ""
+        try:
+            start_domain = urlparse(start_url).hostname or ""
+        except Exception:
+            pass
+
+        while queue and len(results) < max_pages:
+            item = queue.pop(0)
+            url = item["url"]
+            depth = item["depth"]
+            if url in visited:
+                continue
+            visited.add(url)
+            if depth > max_depth:
+                continue
+
+            try:
+                page = fetch_page(url, depth)
+                results.append({"url": url, "title": page["title"], "html": page["text"], "depth": depth})
+                for link in page["links"]:
+                    if link in visited:
+                        continue
+                    if same_domain and start_domain:
+                        try:
+                            if urlparse(link).hostname != start_domain:
+                                continue
+                        except Exception:
+                            continue
+                    queue.append({"url": link, "depth": depth + 1})
+            except Exception:
+                results.append({"url": url, "title": "", "html": "", "depth": depth, "error": "fetch failed"})
+
+            if delay_sec > 0:
+                time.sleep(delay_sec)
+
+        return results
+
+    return {"crawl": crawl, "results": results}

package/browser-op/py/examples/01_open_and_probe.py

@@ -0,0 +1,48 @@
+"""
+样例 01: 最小打开 + 探查 (对齐 e2e_steps/01_cdp_open.js)
+
+演示 Python 客户端最基本的: open → new_tab → status → evaluate → close
+适合第一次接触 Python 客户端的人跑通。
+
+跑: python lib/py/examples/01_open_and_probe.py
+"""
+import sys
+import os
+import time
+
+# 让 examples 能 import 上级目录的 browser 模块
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from browser import Browser  # noqa: E402
+
+
+def main() -> None:
+    b = Browser()
+
+    # 1. 打开浏览器 (自动起 browserd daemon, 双路由 auto)
+    print("[01] open browser...")
+    bh = b.open(route_mode="auto", headless=False)
+    print("[01] mode:", bh.get("mode"))
+
+    # 2. 新开 tab 到 example.com
+    print("[01] new tab → example.com")
+    ph = b.new_tab("https://example.com")
+    time.sleep(3)  # 等加载 (演示用, 生产用 wait_for_selector)
+
+    # 3. 探查: status
+    st = b.status(ph)
+    print("[01] status:", st)
+
+    # 4. 探查: evaluate 取标题 + 正文
+    title = b.evaluate(ph, source="() => document.title")
+    h1 = b.evaluate(ph, source='() => (document.querySelector("h1")||{}).innerText || ""')
+    print(f"[01] title={title!r}  h1={h1!r}")
+
+    # 5. 用完关闭 (仅演示结束才关, 生产里 agent 长生命周期复用)
+    print("[01] close")
+    b.close()
+    print("[01] DONE")
+
+
+if __name__ == "__main__":
+    main()

package/browser-op/py/examples/02_reuse_and_probe.py

@@ -0,0 +1,66 @@
+"""
+样例 02: 复用已有 tab + DOM 探查 (对齐 findOrNewTab + snapshot/evaluate)
+
+演示 Python 客户端的核心探查能力:
+  - find_or_new_tab (只找不开, 不重复打开已有 tab)
+  - snapshot (aria 树, DOM 结构探查)
+  - evaluate (跑页面 JS 取数据)
+
+这是 agent/采集场景最常用的模式: 先看页面长什么样, 再决定怎么操作。
+
+跑: python lib/py/examples/02_reuse_and_probe.py
+"""
+import sys
+import os
+import time
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from browser import Browser  # noqa: E402
+
+
+def main() -> None:
+    b = Browser()
+    print("[02] open...")
+    b.open(route_mode="auto", headless=False)
+
+    # 1. find_or_new_tab: 已有真实 example.com tab 就复用, 没有就开
+    #    (对齐 browser.js 的"复用已有 tab, 不盲目 newTab"原则)
+    #    注意: 用 'https://example.com' 精确匹配, 避开 chrome-extension:// 代理 tab
+    #          (代理 tab 的 url 是 chrome-extension://xxx/example.com, 子串会误命中)
+    ph = b.find_or_new_tab("https://example.com", match="includes")
+    print("[02] pageHandle:", ph)
+
+    # 切到这个 tab 并等加载
+    b.operate(ph, action="activate")
+    b.operate(ph, action="waitForLoadState", state="complete")
+    time.sleep(2)
+
+    # 2. snapshot: aria 树 (探查 DOM 结构, 对齐 browser 的 snapshot action)
+    snap = b.snapshot(ph)
+    if snap and isinstance(snap, dict):
+        yaml = snap.get("yaml", "")
+        print(f"[02] snapshot aria 树长度: {len(yaml)} 字符")
+        print("[02] aria 树前 300 字:")
+        print(yaml[:300])
+    else:
+        print("[02] snapshot:", snap)
+
+    # 3. evaluate: 取结构化数据 (采集常用)
+    links = b.evaluate(
+        ph,
+        source="""() => {
+            return [...document.querySelectorAll('a')].map(a => ({
+                text: (a.innerText || '').trim(),
+                href: a.href
+            })).slice(0, 5)
+        }""",
+    )
+    print(f"[02] 页面链接 (前5): {links}")
+
+    # 不关浏览器 (长生命周期, 后续 agent 继续用)
+    print("[02] 浏览器保持打开 (长生命周期复用)")
+
+
+if __name__ == "__main__":
+    main()