mooncat-browser 0.1.0

package/browser-op/py/examples/03_interact.py

@@ -0,0 +1,66 @@
+"""
+样例 03: 交互操作 (click/fill/press + waitForSelector)
+
+演示 Python 客户端的自动化控制能力:
+  - wait_for_selector (等元素出现, 比 sleep 靠谱)
+  - fill / press / click (填表单 + 提交)
+  - inner_text (取结果)
+  - 截图存盘
+
+场景: 在 httpbin.org/forms/post 上填一个表单并提交。
+httpbin 无风控, 适合演练交互。
+
+跑: python lib/py/examples/03_interact.py
+"""
+import sys
+import os
+import base64
+from pathlib import Path
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from browser import Browser  # noqa: E402
+
+
+def main() -> None:
+    b = Browser()
+    print("[03] open...")
+    b.open(route_mode="auto", headless=False)
+
+    ph = b.new_tab("https://httpbin.org/forms/post")
+    print("[03] new tab → httpbin form")
+
+    # 1. 等表单出现 (比 sleep 靠谱)
+    b.wait_for_selector(ph, selector="input[type=submit]", timeout=15000)
+    print("[03] 表单已加载")
+
+    # 2. fill: 填字段 (httpbin 表单有 custname/custtel/custemail)
+    b.fill(ph, selector="input[name=custname]", value="Test User")
+    b.fill(ph, selector="input[name=custtel]", value="1234567890")
+    b.fill(ph, selector="input[name=custemail]", value="test@example.com")
+    print("[03] 已填表单")
+
+    # 3. screenshot 存盘 (看当前状态)
+    shot = b.screenshot(ph)
+    if isinstance(shot, dict) and shot.get("dataUrl"):
+        buf = base64.b64decode(shot["dataUrl"].split(",")[1])
+        out = Path(__file__).parent / "_artifacts" / "03_form_filled.png"
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_bytes(buf)
+        print(f"[03] 截图: {out} ({len(buf)} bytes)")
+
+    # 4. click 提交
+    b.click(ph, selector="input[type=submit]")
+    print("[03] 点击 submit")
+
+    # 5. 等结果页 (httpbin 会返回提交的 JSON)
+    b.wait_for_selector(ph, selector="pre", timeout=10000)
+    result_text = b.inner_text(ph, selector="pre")
+    print("[03] 提交结果 (httpbin 回显):")
+    print(result_text[:300] if result_text else "(空)")
+
+    print("[03] DONE (浏览器保持打开)")
+
+
+if __name__ == "__main__":
+    main()

package/browser-op/py/find.py

@@ -0,0 +1,150 @@
+"""web/find — 元素定位 (路由无关).
+
+忠实复刻 lib/web/find.js。
+通用能力: 按文本/selector 找元素, 返回坐标 + CSS path。
+解决 SPA 两大定位问题:
+  ① 标题被拆成多 span → 叶子精确匹配失败 → 兜底取包含匹配最深层
+  ② aria snapshot 抓不到 (CSS Modules 非语义 DOM) → 不依赖 aria-ref
+clickByText: 基于此的点击封装 (sycm 这类页面文本是唯一稳定位)
+
+依赖: browser (operate)
+"""
+from __future__ import annotations
+import json
+import asyncio
+from typing import Any
+
+import sys
+sys.path.insert(0, __file__.rsplit("\\", 1)[0] if "\\" in __file__ else __file__.rsplit("/", 1)[0])
+from browser import operate  # noqa: E402
+
+
+async def find_element(page_handle: dict, criteria: dict | None = None) -> dict:
+    """查找页面上匹配的元素, 返回坐标 + CSS path。
+
+    文本匹配策略 (解决标题被拆 span):
+      1. 叶子节点精确匹配 (最稳)
+      2. 兜底: 任意层级 innerText 包含, 取后代最少的 (最接近文本本身的元素)
+
+    criteria:
+      text: 按文本找 (exact=False 时子串匹配)
+      exact: bool
+      selector: 按 CSS selector 找 (与 text 二选一)
+      visibleOnly: 只返回可见元素
+    返回: {found, x, y, width, height, path, text} 或 {found: False}
+    """
+    criteria = criteria or {}
+    text = criteria.get("text")
+    exact = bool(criteria.get("exact"))
+    selector = criteria.get("selector")
+    visible_only = bool(criteria.get("visibleOnly"))
+    if not text and not selector:
+        raise ValueError("findElement: text 或 selector 必须传一个")
+    source = """(() => {
+      const text = """ + json.dumps(text or "") + """
+      const exact = """ + json.dumps(exact) + """
+      const selector = """ + json.dumps(selector or "") + """
+      const visibleOnly = """ + json.dumps(visible_only) + """
+      const all = [...document.querySelectorAll('*')]
+      const isVisible = (el) => {
+        if (!el) return false
+        const r = el.getBoundingClientRect()
+        const s = getComputedStyle(el)
+        return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.display !== 'none' && s.opacity !== '0'
+      }
+      let hit = null
+      if (selector) {
+        hit = document.querySelector(selector)
+      } else if (text) {
+        hit = all.find(el => el.children.length === 0 && (exact ? (el.innerText||'').trim()===text : (el.innerText||'').trim()===text))
+        if (!hit) {
+          const cands = all.filter(el => (el.innerText||'').includes(text) && (exact ? (el.innerText||'').trim()===text : true))
+          cands.sort((a,b) => a.querySelectorAll('*').length - b.querySelectorAll('*').length)
+          hit = cands[0]
+        }
+      }
+      if (!hit) return { found: false }
+      if (visibleOnly && !isVisible(hit)) return { found: false }
+      const path = []
+      let cur = hit
+      let depth = 0
+      while (cur && cur !== document.body && depth < 4) {
+        let seg = cur.tagName.toLowerCase()
+        if (cur.id) seg += '#' + cur.id
+        else if (cur.className) {
+          const c = (cur.className||'').toString().trim().split(/\\s+/).filter(x=>x).slice(0,1).join('.')
+          if (c) seg += '.' + c
+        }
+        path.unshift(seg)
+        cur = cur.parentElement
+        depth++
+      }
+      const r = hit.getBoundingClientRect()
+      return {
+        found: true,
+        x: Math.round(r.x), y: Math.round(r.y),
+        width: Math.round(r.width), height: Math.round(r.height),
+        path: path.join(' > '),
+        text: (hit.innerText||'').trim().slice(0, 60)
+      }
+    })()"""
+    try:
+        r = await operate(page_handle, {"action": "evaluate", "source": source, "_skipVisualize": True})
+        return r or {"found": False}
+    except Exception:
+        return {"found": False}
+
+
+async def click_by_text(page_handle: dict, text: str, opts: dict | None = None) -> dict:
+    """按文本点击元素 (SPA 最稳定定位, sycm 这类页面文本是唯一不随部署变的锚点)。
+
+    容错 "访客分析 >" 这种 (文本带后缀): 默认 startsWith 匹配, exact=True 则精确。
+
+    opts:
+      exact: bool (False=允许后缀)
+      scrollIntoView: bool (点击前滚到元素, 找不到时下滚探测)
+    返回: {clicked, path, text} 或 {clicked: False, error}
+    """
+    opts = opts or {}
+    exact = bool(opts.get("exact"))
+    scroll_into_view = opts.get("scrollIntoView", True)
+
+    el = await find_element(page_handle, {"text": text, "exact": exact})
+    if not el.get("found") and scroll_into_view:
+        for _ in range(40):
+            await operate(page_handle, {
+                "action": "evaluate",
+                "source": '() => { window.scrollBy(0, 40 + Math.floor(Math.random()*30)); return null }',
+                "_skipVisualize": True,
+            })
+            await asyncio.sleep(0.06 + __import__("random").random() * 0.06)
+            el = await find_element(page_handle, {"text": text, "exact": exact})
+            if el.get("found"):
+                break
+            at_bottom = False
+            try:
+                at_bottom = await operate(page_handle, {
+                    "action": "evaluate",
+                    "source": '()=>(window.innerHeight + (window.scrollY||0) + 5) >= document.body.scrollHeight',
+                    "_skipVisualize": True,
+                })
+            except Exception:
+                pass
+            if at_bottom:
+                break
+    if not el.get("found"):
+        return {"clicked": False, "error": "not found: " + text}
+    clicked = await operate(page_handle, {
+        "action": "evaluate",
+        "source": """(() => {
+      const all = [...document.querySelectorAll('*')]
+      const hit = all.find(e => e.children.length === 0 && (e.innerText||'').trim() === """ + json.dumps(text) + """)
+                 || all.find(e => e.children.length === 0 && (e.innerText||'').trim().startsWith(""" + json.dumps(text) + """))
+      if (!hit) return false
+      const clickable = hit.closest('button, a, [role=button], [onclick]') || hit
+      clickable.click()
+      return true
+    })()""",
+        "_skipVisualize": True,
+    })
+    return {"clicked": clicked is not False, "path": el.get("path"), "text": el.get("text")}

package/browser-op/py/honeypot.py

@@ -0,0 +1,73 @@
+"""web/honeypot — 蜜罐陷阱检测（路由无关）
+
+忠实复刻 lib/web/honeypot.js。
+扫描页面隐藏的陷阱元素（隐藏 link/input/button），避免触发反爬。
+基于 operate({action:'evaluate'}) 跑页面 JS。
+
+依赖：browser（operate）
+"""
+from __future__ import annotations
+
+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
+
+# 页面内扫描隐藏陷阱的探测脚本（在页面 MAIN world 执行）
+# 检测：display:none / opacity:0 / visibility:hidden / 零尺寸 / 离屏 / 父级隐藏（向上查 3 层）
+SCAN_SOURCE = '''() => {
+  const traps = []
+  const isHidden = (el) => {
+    const s = getComputedStyle(el)
+    if (s.display === "none") return "display:none"
+    if (parseFloat(s.opacity) === 0) return "opacity:0"
+    if (s.visibility === "hidden") return "visibility:hidden"
+    const r = el.getBoundingClientRect()
+    if (r.width === 0 || r.height === 0) return "zero-size"
+    if (r.top < 0 && r.bottom < 0) return "offscreen-top"
+    if (r.left < 0 && r.right < 0) return "offscreen-left"
+    return null
+  }
+  const walk = (el, depth) => {
+    if (!el || depth > 3) return null
+    const reason = isHidden(el)
+    if (reason) return reason + (depth > 0 ? "(parent)" : "")
+    return walk(el.parentElement, depth + 1)
+  }
+  const sel = "a[href], input, button, [role=button], [onclick]"
+  document.querySelectorAll(sel).forEach((el) => {
+    const reason = walk(el, 0)
+    if (reason) {
+      traps.push({
+        tag: el.tagName.toLowerCase(),
+        text: (el.innerText || el.value || "").slice(0, 80),
+        href: el.getAttribute("href") || null,
+        name: el.getAttribute("name") || null,
+        type: el.getAttribute("type") || null,
+        reason,
+        rect: (() => { const r = el.getBoundingClientRect(); return { x: r.x, y: r.y, w: r.width, h: r.height } })(),
+      })
+    }
+  })
+  return traps
+}'''
+
+
+def scan(page_handle: dict) -> list:
+    """扫描页面的隐藏陷阱元素。
+
+    page_handle: 单个 page 句柄（来自 newTab）
+    返回: list[{tag, text, href, name, type, reason, rect}]
+    """
+    if not page_handle:
+        raise ValueError('scan: pageHandle required')
+    r = operate(page_handle, {'action': 'evaluate', 'source': SCAN_SOURCE})
+    # evaluate 在 CDP 分支直接返回结果；插件分支返回 {ok,...} 或裸结果，兼容两种
+    if isinstance(r, list):
+        return r
+    if isinstance(r, dict) and isinstance(r.get('value'), list):
+        return r['value']
+    if isinstance(r, dict) and isinstance(r.get('result'), list):
+        return r['result']
+    return []

package/browser-op/py/humanize.py

@@ -0,0 +1,392 @@
+"""web/humanize — 拟人化行为注入 (路由无关, 全走 operate).
+
+忠实复刻 lib/web/humanize.js。
+设计: 随机触发, 不是每次 action 都注入。每个 operate 有概率走 humanize 序列,
+概率按 riskLevel 调。避免"每次必注入"本身变成新的固定模式。
+
+嵌入方式: operate 顶部作为隐式中间件, 调用方无感。
+
+依赖: browser (operate), scroll, interact
+"""
+from __future__ import annotations
+import math
+import random
+import time
+from typing import Any
+
+import sys
+sys.path.insert(0, __file__.rsplit("\\", 1)[0] if "\\" in __file__ else __file__.rsplit("/", 1)[0])
+from browser import operate  # noqa: E402
+from scroll import scroll_by, scroll_to_y, scroll_to_element  # noqa: E402
+
+try:
+    from interact import highlight, toast
+except Exception:
+    highlight = None
+    toast = None
+
+
+# 风险等级配置
+RISK_LEVELS = {
+    "low": {"delayScale": 0.6, "sequenceLen": (1, 3), "triggerProb": 0.35, "scrollProb": 0.3, "wanderProb": 0.25},
+    "medium": {"delayScale": 1.0, "sequenceLen": (2, 4), "triggerProb": 0.55, "scrollProb": 0.5, "wanderProb": 0.4},
+    "high": {"delayScale": 1.8, "sequenceLen": (3, 6), "triggerProb": 0.75, "scrollProb": 0.7, "wanderProb": 0.6},
+}
+
+HIGH_RISK_DOMAINS = [
+    "taobao.com", "tmall.com", "jd.com", "1688.com", "pinduoduo.com",
+    "yangkeduo.com", "xiaohongshu.com", "xhslink.com", "weidian.com",
+    "douyin.com", "kuaishou.com", "bilibili.com", "weibo.com",
+    "alipay.com", "bank", "icbc", "cmbchina", "12306.cn",
+]
+
+_last_mouse_pos: dict = {"x": 300, "y": 300}
+
+
+def _gaussian(mean: float, std: float) -> float:
+    u1 = random.random()
+    while u1 == 0:
+        u1 = random.random()
+    u2 = random.random()
+    while u2 == 0:
+        u2 = random.random()
+    return mean + std * math.sqrt(-2.0 * math.log(u1)) * math.cos(2.0 * math.pi * u2)
+
+
+def _bezier(p0: float, p1: float, p2: float, p3: float, t: float) -> float:
+    u = 1 - t
+    return u * u * u * p0 + 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t * p3
+
+
+def _bezier_trajectory(from_pt: dict, to_pt: dict, steps: int) -> list[dict]:
+    pts = []
+    mx = (from_pt["x"] + to_pt["x"]) / 2 + (random.random() - 0.5) * abs(to_pt["x"] - from_pt["x"]) * 0.6
+    my = (from_pt["y"] + to_pt["y"]) / 2 + (random.random() - 0.5) * abs(to_pt["y"] - from_pt["y"]) * 0.6
+    c1 = {"x": from_pt["x"] + (mx - from_pt["x"]) * 0.3, "y": from_pt["y"] + (my - from_pt["y"]) * 0.3}
+    c2 = {"x": to_pt["x"] + (mx - to_pt["x"]) * 0.3, "y": to_pt["y"] + (my - to_pt["y"]) * 0.3}
+    for i in range(steps + 1):
+        t = i / steps
+        pts.append({
+            "x": _bezier(from_pt["x"], c1["x"], c2["x"], to_pt["x"], t) + (random.random() - 0.5) * 2,
+            "y": _bezier(from_pt["y"], c1["y"], c2["y"], to_pt["y"], t) + (random.random() - 0.5) * 2,
+        })
+    return pts
+
+
+# 原子行为
+
+def _read(page_handle: dict, scale: float) -> None:
+    time.sleep(max(0, _gaussian(2.5, 1.2) * scale))
+
+
+def _idle(page_handle: dict, scale: float) -> None:
+    time.sleep(max(0, _gaussian(1.2, 0.6) * scale))
+
+
+def _scroll_smooth(page_handle: dict, scale: float, direction: str | None = None) -> None:
+    dir_flag = direction or ("down" if random.random() < 0.8 else "up")
+    pixels = random.randint(120, 480)
+    dy = pixels if dir_flag == "down" else -pixels
+    try:
+        scroll_by(page_handle, dy)
+    except Exception:
+        pass
+    time.sleep(max(0, _gaussian(0.5, 0.2) * scale))
+
+
+def _scroll_to_ratio(page_handle: dict, scale: float) -> None:
+    ratio = random.choice([0.25, 0.4, 0.55, 0.7, 0.85])
+    target_y = operate(page_handle, {"_skipHumanize": True, "action": "evaluate", "source": f"(r) => Math.max(0, (document.body.scrollHeight - window.innerHeight) * r)", "args": ratio})
+    try:
+        if target_y:
+            y_val = int(target_y) if not isinstance(target_y, dict) else int(target_y.get("value", 0))
+            scroll_to_y(page_handle, y_val)
+    except Exception:
+        pass
+    time.sleep(max(0, _gaussian(0.8, 0.3) * scale))
+
+
+def _mouse_wander(page_handle: dict, scale: float) -> None:
+    global _last_mouse_pos
+    rand_x = random.uniform(100, 1100)
+    rand_y = random.uniform(100, 700)
+    el_info = operate(page_handle, {"_skipHumanize": True, "action": "evaluate", "source": "(x, y) => { const el = document.elementFromPoint(x, y); if (!el) return null; const r = el.getBoundingClientRect(); return { x: Math.round(r.x + r.width/2), y: Math.round(r.y + r.height/2), tag: el.tagName, text: (el.innerText||'').trim().slice(0,20) } }", "args": [rand_x, rand_y]})
+    target = el_info
+    if isinstance(target, dict) and "value" in target:
+        target = target["value"]
+    if target and target.get("x") is not None:
+        if highlight:
+            try:
+                highlight(page_handle, {"x": target["x"] - 30, "y": target["y"] - 10, "w": 60, "h": 20, "kind": "rect"})
+            except Exception:
+                pass
+    tx = target["x"] if target and target.get("x") is not None else rand_x
+    ty = target["y"] if target and target.get("y") is not None else rand_y
+    steps = random.randint(12, 22)
+    pts = _bezier_trajectory(_last_mouse_pos, {"x": tx, "y": ty}, steps)
+    for pt in pts:
+        operate(page_handle, {"_skipHumanize": True, "action": "mouseMove", "x": round(pt["x"]), "y": round(pt["y"])})
+        time.sleep(random.uniform(0.008, 0.022))
+    _last_mouse_pos = {"x": tx, "y": ty}
+    time.sleep(max(0, _gaussian(0.3, 0.15) * scale))
+
+
+def _hover_random(page_handle: dict, scale: float) -> None:
+    global _last_mouse_pos
+    pos = operate(page_handle, {"_skipHumanize": True, "action": "evaluate", "source": "() => { const els = document.querySelectorAll('a, button, input, [role=button]'); const arr = [...els].filter(e => { const r = e.getBoundingClientRect(); return r.width > 0 && r.height > 0 && r.top > 0 && r.top < window.innerHeight - 50 }); if (!arr.length) return null; const el = arr[Math.floor(Math.random()*arr.length)]; const r = el.getBoundingClientRect(); return { x: Math.round(r.x + r.width/2), y: Math.round(r.y + r.height/2) } }"})
+    target = pos
+    if isinstance(target, dict) and "value" in target:
+        target = target["value"]
+    if not target or target.get("x") is None:
+        return
+    if highlight:
+        try:
+            highlight(page_handle, {"x": target["x"] - 40, "y": target["y"] - 10, "w": 80, "h": 20, "kind": "rect"})
+        except Exception:
+            pass
+    steps = random.randint(10, 18)
+    pts = _bezier_trajectory(_last_mouse_pos, {"x": target["x"], "y": target["y"]}, steps)
+    for pt in pts:
+        operate(page_handle, {"_skipHumanize": True, "action": "mouseMove", "x": round(pt["x"]), "y": round(pt["y"])})
+        time.sleep(random.uniform(0.01, 0.025))
+    _last_mouse_pos = {"x": target["x"], "y": target["y"]}
+    time.sleep(max(0, _gaussian(0.4, 0.2) * scale))
+
+
+def _scroll_key(page_handle: dict, scale: float) -> None:
+    delta = random.randint(300, 600) * (1 if random.random() < 0.85 else -1)
+    try:
+        scroll_by(page_handle, delta)
+    except Exception:
+        pass
+    time.sleep(max(0, _gaussian(0.6, 0.25) * scale))
+
+
+def _mouse_jitter(page_handle: dict, scale: float) -> None:
+    global _last_mouse_pos
+    for _ in range(random.randint(2, 5)):
+        operate(page_handle, {"_skipHumanize": True, "action": "mouseMove", "x": round(_last_mouse_pos["x"] + (random.random() - 0.5) * 20), "y": round(_last_mouse_pos["y"] + (random.random() - 0.5) * 20)})
+        time.sleep(random.uniform(0.03, 0.08))
+    time.sleep(max(0, _gaussian(0.2, 0.1) * scale))
+
+
+def _tab_nav(page_handle: dict, scale: float) -> None:
+    count = random.randint(1, 3)
+    for _ in range(count):
+        operate(page_handle, {"_skipHumanize": True, "action": "press", "selector": "body", "key": "Tab"})
+        time.sleep(max(0, _gaussian(0.25, 0.1) * scale))
+
+
+def _noop(page_handle: dict, scale: float) -> None:
+    time.sleep(random.uniform(0.1, 0.4))
+
+
+def _weighted_pick(pool: list[dict]) -> Any:
+    total = sum(a.get("weight", 1) for a in pool)
+    r = random.random() * total
+    for item in pool:
+        r -= item.get("weight", 1)
+        if r <= 0:
+            return item["fn"]
+    return pool[0]["fn"]
+
+
+def _build_sequence(phase: str, risk_cfg: dict) -> list:
+    min_len, max_len = risk_cfg["sequenceLen"]
+    target_len = random.randint(min_len, max_len)
+    seq = []
+
+    attention_pool = [{"fn": _read, "weight": 3}, {"fn": _idle, "weight": 1}]
+    scroll_pool = [{"fn": _scroll_smooth, "weight": 4}, {"fn": _scroll_to_ratio, "weight": 2}, {"fn": _scroll_key, "weight": 1}]
+    mouse_pool = [{"fn": _mouse_wander, "weight": 3}, {"fn": _hover_random, "weight": 2}, {"fn": _mouse_jitter, "weight": 1}]
+    meta_pool = [{"fn": _noop, "weight": 2}]
+    all_pool = attention_pool + scroll_pool + mouse_pool + meta_pool
+
+    if phase == "navigate":
+        seq.append(_read)
+        for _ in range(random.randint(1, 3)):
+            seq.append(_weighted_pick(scroll_pool))
+        if random.random() < risk_cfg["wanderProb"]:
+            seq.append(_weighted_pick(mouse_pool))
+        while len(seq) < target_len and random.random() < 0.5:
+            seq.append(_weighted_pick(attention_pool + scroll_pool + mouse_pool + meta_pool))
+    elif phase == "interact":
+        aim_len = random.randint(0, min(2, target_len))
+        for _ in range(aim_len):
+            pool = mouse_pool if random.random() < 0.6 else attention_pool + meta_pool
+            seq.append(_weighted_pick(pool))
+    elif phase == "after-interact":
+        after_len = random.randint(0, min(2, target_len))
+        for _ in range(after_len):
+            seq.append(_weighted_pick(attention_pool + scroll_pool + meta_pool))
+    else:
+        for _ in range(target_len):
+            seq.append(_weighted_pick(all_pool))
+
+    if seq and random.random() < 0.1:
+        seq.insert(random.randint(0, len(seq)), _idle)
+    return seq
+
+
+def _should_trigger(risk_cfg: dict) -> bool:
+    return random.random() < risk_cfg["triggerProb"]
+
+
+def _reposition(page_handle: dict, selector: str, scale: float) -> None:
+    global _last_mouse_pos
+    if not selector:
+        return
+    try:
+        scroll_to_element(page_handle, selector, {"block": "center"})
+    except Exception:
+        pass
+    time.sleep(max(0, _gaussian(0.5, 0.2) * scale))
+    box_r = operate(page_handle, {"_skipHumanize": True, "action": "boundingBox", "selector": selector})
+    box = box_r
+    if isinstance(box, dict) and "value" in box:
+        box = box["value"]
+    if box and box.get("width") is not None:
+        cx = box["x"] + box["width"] * (0.4 + random.random() * 0.2)
+        cy = box["y"] + box["height"] * (0.4 + random.random() * 0.2)
+        steps = random.randint(8, 16)
+        pts = _bezier_trajectory(_last_mouse_pos, {"x": cx, "y": cy}, steps)
+        for pt in pts:
+            operate(page_handle, {"_skipHumanize": True, "action": "mouseMove", "x": round(pt["x"]), "y": round(pt["y"])})
+            time.sleep(random.uniform(0.01, 0.025))
+        _last_mouse_pos = {"x": cx, "y": cy}
+    try:
+        operate(page_handle, {"_skipHumanize": True, "action": "focus", "selector": selector})
+    except Exception:
+        pass
+
+
+def before_action(page_handle: dict, action: str, params: dict, risk_cfg: dict) -> None:
+    """在 operate 执行 action 之前调用 (随机触发)."""
+    scale = risk_cfg["delayScale"]
+    is_interact = action in ("click", "fill", "type", "press", "hover", "dblclick", "check", "uncheck", "selectOption", "dragTo", "setInputFiles")
+    is_navigate = action in ("goto", "goBack", "goForward", "reload")
+
+    if is_navigate:
+        return
+
+    if not _should_trigger(risk_cfg):
+        if is_interact and params.get("selector"):
+            _reposition(page_handle, params["selector"], scale)
+        return
+
+    seq = _build_sequence("interact" if is_interact else "default", risk_cfg)
+    for atom in seq:
+        try:
+            atom(page_handle, scale)
+        except Exception:
+            pass
+
+    if is_interact and params.get("selector"):
+        _reposition(page_handle, params["selector"], scale)
+
+
+def after_action(page_handle: dict, action: str, risk_cfg: dict) -> None:
+    """在 operate 执行 action 之后调用 (随机触发)."""
+    scale = risk_cfg["delayScale"]
+    is_navigate = action in ("goto", "goBack", "goForward", "reload")
+
+    if is_navigate:
+        seq = _build_sequence("navigate", risk_cfg)
+        for atom in seq:
+            try:
+                atom(page_handle, scale)
+            except Exception:
+                pass
+        return
+
+    if not _should_trigger(risk_cfg):
+        return
+    seq = _build_sequence("after-interact", risk_cfg)
+    for atom in seq:
+        try:
+            atom(page_handle, scale)
+        except Exception:
+            pass
+
+
+def create_humanizer(options: dict | None = None) -> dict:
+    """创建 humanizer 实例.
+
+    options:
+      riskLevel: 'low'|'medium'|'high' (默认 'medium')
+    返回: {beforeAction, afterAction, riskLevel, riskCfg}
+    """
+    opts = options or {}
+    level = opts.get("riskLevel", "medium")
+    risk_cfg = RISK_LEVELS.get(level, RISK_LEVELS["medium"])
+    safe_level = level if level in RISK_LEVELS else "medium"
+
+    return {
+        "riskLevel": safe_level,
+        "riskCfg": risk_cfg,
+        "beforeAction": lambda ph, a, p: before_action(ph, a, p, risk_cfg),
+        "afterAction": lambda ph, a: after_action(ph, a, risk_cfg),
+    }
+
+
+def human_act(page_handle: dict, opts: dict | None = None) -> None:
+    """自由调用的拟人接口 (采集/evaluate 场景).
+
+    一个调用搞定采集前的拟人 + 归位。
+
+    opts:
+      target: 归位目标 (CSS selector)
+      targetXY: 归位目标 (坐标), 与 target 二选一
+      phase: 'default'|'navigate'|'interact'|'after'
+      riskLevel: 'low'|'medium'|'high'
+      reposition: 拟人后归位到目标 (默认 True)
+    """
+    global _last_mouse_pos
+    opts = opts or {}
+    risk_cfg = RISK_LEVELS.get(opts.get("riskLevel", "medium"), RISK_LEVELS["medium"])
+    scale = risk_cfg["delayScale"]
+    phase = opts.get("phase", "default")
+    target = opts.get("target")
+    target_xy = opts.get("targetXY")
+
+    if target and highlight:
+        try:
+            highlight(page_handle, {"kind": "selector", "selector": target})
+        except Exception:
+            pass
+    elif target_xy and highlight:
+        try:
+            highlight(page_handle, {"kind": "point", "x": target_xy["x"], "y": target_xy["y"]})
+        except Exception:
+            pass
+
+    if _should_trigger(risk_cfg):
+        seq_phase = "navigate" if phase == "navigate" else ("after-interact" if phase == "after" else "default")
+        seq = _build_sequence(seq_phase, risk_cfg)
+        for atom in seq:
+            try:
+                atom(page_handle, scale)
+            except Exception:
+                pass
+
+    if opts.get("reposition", True) and phase != "after":
+        if target:
+            _reposition(page_handle, target, scale)
+        elif target_xy:
+            steps = random.randint(8, 16)
+            pts = _bezier_trajectory(_last_mouse_pos, {"x": target_xy["x"], "y": target_xy["y"]}, steps)
+            for pt in pts:
+                operate(page_handle, {"_skipHumanize": True, "action": "mouseMove", "x": round(pt["x"]), "y": round(pt["y"])})
+                time.sleep(random.uniform(0.01, 0.025))
+            _last_mouse_pos = {"x": target_xy["x"], "y": target_xy["y"]}
+
+
+def detect_risk_level(url: str | None = None) -> str:
+    """检测 url 是否命中高风控域名."""
+    if not url:
+        return "medium"
+    lower = url.lower()
+    for domain in HIGH_RISK_DOMAINS:
+        if domain in lower:
+            return "high"
+    return "medium"