mooncat-browser 0.1.0

package/browser-op/web/browser.js

@@ -0,0 +1,231 @@
+// web/browser — browserd client facade
+//
+// 对外 API 不变: open / newTab / operate / listTabs / close 等。
+// 但底层不再是进程内 BrowserOp, 而是自动管理一个 detached browserd 后端进程。
+// 业务脚本退出不影响 Chrome (browserd 持有它)。
+//
+// 生命周期:
+//   open()  → 自动 spawn browserd (如不存在) → IPC open → 返回 browserHandle (纯数据)
+//   newTab/operate/listTabs → IPC 调 browserd
+//   close() → IPC close → browserd 关 Chrome + 退出
+//   业务脚本退出 → 什么都不做 (browserd 常驻)
+
+'use strict'
+
+const { spawn } = require('node:child_process')
+const path = require('node:path')
+const os = require('node:os')
+
+const { rpc, health } = require('../backend/rpc-client.cjs')
+
+// skill 根目录 (browser.js 在 lib/web/, 往上两层)
+const SKILL_ROOT = path.resolve(__dirname, '..', '..')
+const BROWSERD_PATH = path.join(SKILL_ROOT, 'lib', 'backend', 'browserd.cjs')
+
+// browserd 是否已在本进程确认存活 (避免重复 spawn)
+let _browserdReady = false
+
+// ─── ensureBrowserd: 确保后端存活 ───
+
+async function ensureBrowserd (timeoutMs = 15000) {
+  // 先查 health
+  const h = await health(2000)
+  if (h && h.ok) {
+    _browserdReady = true
+    return
+  }
+
+  // 不存活 → detached spawn
+  const child = spawn(process.execPath, [BROWSERD_PATH], {
+    cwd: SKILL_ROOT,
+    stdio: 'ignore',
+    detached: true,
+    windowsHide: true,
+    env: process.env
+  })
+  child.unref()
+
+  // 轮询 health
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 300))
+    const h2 = await health(1000)
+    if (h2 && h2.ok) {
+      _browserdReady = true
+      return
+    }
+  }
+
+  throw new Error('browserd failed to start (no /health after ' + timeoutMs + 'ms)')
+}
+
+// ─── 对外 API (签名不变) ───
+
+/**
+ * 打开浏览器 (自动连接或启动 browserd 后端)。
+ * @param {Object} options
+ *   mode: 'humanize' → 开启拟人行为注入（高危平台必用）；调用方显式 humanAct
+ *   riskLevel: 'low'|'medium'|'high'；不传则按 url 自动 detect（高危域名→high）
+ * @returns {Promise<browserHandle>} 纯数据: { mode, notice, ownerId, humanize? }
+ */
+async function open (options = {}) {
+  await ensureBrowserd()
+  const bh = await rpc('open', {
+    routeMode: options.routeMode || 'auto',
+    headless: options.headless || false,
+    executablePath: options.executablePath,
+    profileRoot: options.profileRoot,
+    userDataDir: options.userDataDir
+  })
+
+  // 拟人模式：挂 humanizer 到 browserHandle，newTab 继承，operate 自动注入
+  if (options.mode === 'humanize') {
+    const humanize = require('./humanize')
+    const level = options.riskLevel || humanize.detectRiskLevel(undefined)
+    bh.humanize = humanize.createHumanizer({ riskLevel: level })
+    bh.notice = bh.notice || { level: 'info', message: '拟人模式已开启 (riskLevel=' + bh.humanize.riskLevel + ')' }
+  }
+  // 可视化在后端默认开启 (resolver 单源保证高亮=执行对象), 这里不挂任何标记。
+  return bh
+}
+
+/**
+ * 新建 tab。返回 pageHandle (纯数据: { mode, pageId, tabId?, url, ownerId, humanize? })。
+ * humanize 标记从 browserHandle 继承（open mode:'humanize' 才有）。
+ */
+async function newTab (browserHandle, params = {}) {
+  if (!browserHandle) throw new Error('newTab: browserHandle required')
+  const ph = await rpc('newTab', { url: params.url || '' })
+  // 继承 humanizer（同一个实例，共享鼠标位置等模块级状态）
+  if (browserHandle.humanize) ph.humanize = browserHandle.humanize
+  return ph
+}
+
+/**
+ * 列出所有 tab。返回 [{ pageHandle, url, title, active }]。
+ */
+async function listTabs (browserHandle) {
+  if (!browserHandle) throw new Error('listTabs: browserHandle required')
+  return rpc('listTabs', {})
+}
+
+/**
+ * 复用已有 tab: 按 url 匹配找, 找到复用 pageHandle; 找不到才 newTab。
+ *
+ * 解决「盲目 newTab 重复打开同一页面」的污染问题。
+ * 这是采集/工作流场景的推荐入口: 先复用, 没有再开。
+ *
+ * @param {browserHandle} browserHandle
+ * @param {object} params
+ * @param {string} params.url         匹配已开 tab 的 url (子串匹配, 不含协议/查询更稳)
+ * @param {string} [params.match='includes'] 匹配方式: 'includes'(默认,子串) | 'exact'
+ * @param {boolean} [params.newIfMissing=true] 没找到是否 newTab; false 时没找到返回 null
+ * @param {string} [params.openUrl]   newTab 时用的完整 url (缺省用 params.url)
+ * @returns {Promise<pageHandle|null>}
+ */
+async function findOrNewTab (browserHandle, params = {}) {
+  if (!browserHandle) throw new Error('findOrNewTab: browserHandle required')
+  const match = params.match || 'includes'
+  const target = params.url || ''
+  if (!target) throw new Error('findOrNewTab: url required')
+
+  const tabs = await rpc('listTabs', {})
+  let found = null
+  for (const t of tabs) {
+    const u = t.url || ''
+    const hit = match === 'exact' ? u === target : u.includes(target)
+    if (hit) { found = t; break }
+  }
+
+  if (found) {
+    // 复用: 继承 humanize 标记 (newTab 会做, 这里手动补)
+    const ph = found.pageHandle
+    if (browserHandle.humanize) ph.humanize = browserHandle.humanize
+    return ph
+  }
+
+  if (params.newIfMissing === false) return null
+  return newTab(browserHandle, { url: params.openUrl || target })
+}
+
+/**
+ * 在 pageHandle 上执行操作。统一入口。
+ *
+ * 纯透传: operate 把 action 发给后端 browserd 执行。
+ * 可视化 (高亮真实操作对象) 在后端默认开启, 由 resolver 单源保证
+ *   高亮对象 = 执行对象 (resolve → visualMark → execute 同一元素/handle)。
+ *   不需要调用方传任何开关。
+ * 拟人化是独立能力, 由调用方显式控制 (humanize.humanAct)。
+ * @param {pageHandle} pageHandle
+ * @param {Object} actionObj - { action: 'click', selector: '#x', ... }
+ */
+async function operate (pageHandle, actionObj) {
+  if (!pageHandle) throw new Error('operate: pageHandle required')
+  if (!actionObj || !actionObj.action) throw new Error('operate: action required')
+
+  // 剥离内部专用 flag (_skipHumanize/_skipVisualize), 不透传给后端动作参数
+  const { action, _skipHumanize, _skipVisualize, ...rest } = actionObj
+
+  return rpc('operate', { pageHandle, action, params: rest })
+
+  return result
+}
+
+/**
+ * 关闭浏览器 + browserd。只有用户说"完成"时才调。
+ */
+async function close (browserHandle) {
+  if (!browserHandle) return
+  try {
+    await rpc('close', {})
+  } catch (e) {
+    // browserd 可能已退出, 忽略
+  }
+  _browserdReady = false
+}
+
+// ─── cookie (browserHandle 作用域) ───
+
+async function getCookies (browserHandle, params = {}) {
+  return rpc('getCookies', params)
+}
+async function setCookies (browserHandle, params = {}) {
+  return rpc('setCookies', params)
+}
+async function clearCookies (browserHandle, params = {}) {
+  return rpc('clearCookies', params)
+}
+
+// ─── 模块加载 (辅助模块, 不走 browserd) ───
+
+const createHumanizer = (opts) => {
+  try { return require('./humanize').createHumanizer(opts) } catch { return null }
+}
+const detectRiskLevel = (url) => {
+  try { return require('./humanize').detectRiskLevel(url) } catch { return 'medium' }
+}
+
+module.exports = {
+  open,
+  newTab,
+  findOrNewTab,
+  listTabs,
+  operate,
+  close,
+  getCookies,
+  setCookies,
+  clearCookies,
+  createHumanizer,
+  detectRiskLevel,
+  ensureBrowserd,
+  // 重新导出辅助模块 (兼容现有 require 路径)
+  createBehavior: (opts) => { try { return require('./behavior')(opts) } catch { return null } },
+  detect: (opts) => { try { return require('./captcha').detect(opts) } catch { return null } },
+  createCrawler: (opts) => { try { return require('./crawler')(opts) } catch { return null } },
+  scan: (opts) => { try { return require('./honeypot').scan(opts) } catch { return null } },
+  captureImages: (opts) => { try { return require('./image').captureImages(opts) } catch { return null } },
+  highlight: (opts) => { try { return require('./interact').highlight(opts) } catch {} },
+  toast: (opts) => { try { return require('./interact').toast(opts) } catch {} },
+  htmlToMarkdown: (html) => { try { return require('./markdown').htmlToMarkdown(html) } catch { return html } },
+  uploadFiles: (opts) => { try { return require('./upload').uploadFiles(opts) } catch { return null } }
+}

package/browser-op/web/captcha.js

@@ -0,0 +1,85 @@
+// -*- coding: utf-8 -*-
+//
+// web/captcha — 验证码检测（多信号交叉验证，路由无关）
+//
+// 完整复刻自 bee/resources/sandbox/builtin-libs/web/captcha.js。
+// 信号：URL 关键词 / DOM selector / 页面标题关键词 / 预期内容缺失。
+// 基于 operate({action:'status'}) + operate({action:'evaluate'})。
+//
+// 依赖：./browser（operate）
+
+'use strict'
+
+const { operate } = require('./browser')
+
+const URL_KEYWORDS = ['captcha', 'verify', 'geetest', 'dingxiang', 'challenge', 'slider', 'recaptcha', 'hcaptcha']
+const TITLE_KEYWORDS = ['验证', 'captcha', 'security', 'verify', '人机', '安全验证']
+const DOM_SELECTORS = [
+  '.geetest_', '#geetest', '.yidun', '.dx_captcha', '#captcha',
+  'iframe[src*="captcha"]', 'iframe[src*="recaptcha"]', 'iframe[src*="hcaptcha"]',
+  '.g-recaptcha', '.h-captcha'
+]
+
+// 探测页面是否含特定 captcha DOM
+const DOM_PROBE_SOURCE = (selectors) => '() => {\n' +
+  '  const sels = ' + JSON.stringify(selectors) + '\n' +
+  '  const found = []\n' +
+  '  for (const s of sels) { if (document.querySelector(s)) found.push(s) }\n' +
+  '  return found\n' +
+  '}'
+
+/**
+ * 多信号验证码检测。
+ * @param {object} pageHandle - 单个 page 句柄
+ * @param {object} [options]
+ * @param {string} [options.expectedSelector] - 正常页面应存在的 selector（缺失视为信号）
+ * @returns {Promise<{isCaptcha, confidence, signals, evidence}>}
+ *   confidence: 0~1；>=0.7 判 isCaptcha=true。
+ *   2+ 信号 → 0.95；1 强信号 → 0.7；1 弱信号（仅缺失）→ 0.3。
+ */
+async function detect (pageHandle, options = {}) {
+  if (!pageHandle) throw new Error('detect: pageHandle required')
+
+  const signals = []
+  const evidence = []
+
+  // 信号 1：URL 关键词
+  const st = await operate(pageHandle, { action: 'status' })
+  const url = (st && (st.url || st.value)) || ''
+  const urlHit = URL_KEYWORDS.find((k) => url.toLowerCase().includes(k))
+  if (urlHit) { signals.push('url-keyword'); evidence.push('url contains "' + urlHit + '"') }
+
+  // 信号 2：标题关键词
+  const title = (st && st.title) || ''
+  const titleHit = TITLE_KEYWORDS.find((k) => title.toLowerCase().includes(k.toLowerCase()))
+  if (titleHit) { signals.push('title-keyword'); evidence.push('title contains "' + titleHit + '"') }
+
+  // 信号 3：captcha DOM
+  const found = await operate(pageHandle, { action: 'evaluate', source: DOM_PROBE_SOURCE(DOM_SELECTORS) })
+  const foundArr = Array.isArray(found) ? found : (found && Array.isArray(found.value) ? found.value : [])
+  if (foundArr.length > 0) { signals.push('dom-selector'); evidence.push('selectors: ' + foundArr.join(', ')) }
+
+  // 信号 4：预期内容缺失（弱信号）
+  if (options.expectedSelector) {
+    const exp = await operate(pageHandle, { action: 'evaluate', source: '(s) => !!document.querySelector(s)' })
+    const present = (() => {
+      if (typeof exp === 'boolean') return exp
+      if (exp && typeof exp.value === 'boolean') return exp.value
+      if (exp && typeof exp.result === 'boolean') return exp.result
+      return !!exp
+    })()
+    if (!present) { signals.push('expected-missing'); evidence.push('expected "' + options.expectedSelector + '" not found') }
+  }
+
+  // 置信度
+  let confidence = 0
+  const strong = signals.filter((s) => s !== 'expected-missing').length
+  const weak = signals.includes('expected-missing') ? 1 : 0
+  if (strong >= 2) confidence = 0.95
+  else if (strong === 1) confidence = 0.7
+  else if (weak === 1) confidence = 0.3
+
+  return { isCaptcha: confidence >= 0.7, confidence, signals, evidence }
+}
+
+module.exports = { detect }

package/browser-op/web/crawler.js

@@ -0,0 +1,109 @@
+// -*- coding: utf-8 -*-
+//
+// web/crawler — 轻量爬虫（URL 去重 + 深度控制 + 节流，路由无关）
+//
+// 完整复刻自 bee/resources/sandbox/builtin-libs/web/crawler.js。
+// 基于 operate（goto + evaluate 提取链接/内容）组合，复用同一个 pageHandle（顺序导航）。
+//
+// 依赖：./browser（operate）
+
+'use strict'
+
+const { operate } = require('./browser')
+
+// 页面内提取标题 + 正文 + 同域链接
+const EXTRACT_SOURCE = (baseDomain) => '() => {\n' +
+  '  const title = document.title || ""\n' +
+  '  const text = (document.body && document.body.innerText) ? document.body.innerText.slice(0, 8000) : ""\n' +
+  '  const links = []\n' +
+  '  const a = document.querySelectorAll("a[href]")\n' +
+  '  for (const el of a) {\n' +
+  '    try {\n' +
+  '      const u = new URL(el.href, location.href)\n' +
+  '      if (u.protocol !== "http:" && u.protocol !== "https:") continue\n' +
+  '      links.push(u.href)\n' +
+  '    } catch {}\n' +
+  '  }\n' +
+  '  const base = ' + JSON.stringify(baseDomain || '') + '\n' +
+  '  const filtered = base ? links.filter((l) => { try { return new URL(l).hostname === base } catch { return false } }) : links\n' +
+  '  return { title, text, links: [...new Set(filtered)].slice(0, 200) }\n' +
+  '}'
+
+/**
+ * 创建爬虫实例。
+ * @param {object} pageHandle - 单个 page 句柄
+ * @param {object} [options]
+ * @param {number} [options.maxPages=50] - 最多爬取页数
+ * @param {number} [options.maxDepth=3] - 最大链接深度
+ * @param {number} [options.delay=0.5] - 请求间隔秒
+ * @param {number} [options.retries=2] - 失败重试次数
+ * @param {boolean} [options.sameDomain=true] - 是否限制同域
+ * @returns {{ crawl(startUrl): Promise<Array<{url,title,html,depth}>>, results }}
+ */
+function createCrawler (pageHandle, options = {}) {
+  if (!pageHandle) throw new Error('createCrawler: pageHandle required')
+  const maxPages = options.maxPages != null ? options.maxPages : 50
+  const maxDepth = options.maxDepth != null ? options.maxDepth : 3
+  const delaySec = options.delay != null ? options.delay : 0.5
+  const retries = options.retries != null ? options.retries : 2
+  const sameDomain = options.sameDomain != null ? options.sameDomain : true
+
+  const results = []
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+  async function fetchPage (url, depth) {
+    let lastErr = null
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        await operate(pageHandle, { action: 'goto', url, timeout: 15000 })
+        await operate(pageHandle, { action: 'waitForLoadState', state: 'complete' }).catch(() => {})
+        let baseDomain = ''
+        try { baseDomain = sameDomain ? new URL(url).hostname : '' } catch {}
+        const data = await operate(pageHandle, { action: 'evaluate', source: EXTRACT_SOURCE(baseDomain) })
+        // evaluate 返回结构兼容
+        const d = (data && data.value && typeof data.value === 'object') ? data.value
+          : (data && typeof data === 'object' && !Array.isArray(data) && (data.title || data.links)) ? data
+          : (data && data.result) || {}
+        return { title: d.title || '', text: d.text || '', links: d.links || [] }
+      } catch (e) {
+        lastErr = e
+        await sleep(500)
+      }
+    }
+    throw lastErr || new Error('fetchPage failed')
+  }
+
+  async function crawl (startUrl) {
+    const queue = [{ url: startUrl, depth: 0 }]
+    const visited = new Set()
+    const startDomain = (() => { try { return new URL(startUrl).hostname } catch { return '' } })()
+
+    while (queue.length > 0 && results.length < maxPages) {
+      const { url, depth } = queue.shift()
+      if (visited.has(url)) continue
+      visited.add(url)
+      if (depth > maxDepth) continue
+
+      try {
+        const page = await fetchPage(url, depth)
+        results.push({ url, title: page.title, html: page.text, depth })
+        for (const link of page.links) {
+          if (visited.has(link)) continue
+          if (sameDomain && startDomain) {
+            try { if (new URL(link).hostname !== startDomain) continue } catch { continue }
+          }
+          queue.push({ url: link, depth: depth + 1 })
+        }
+      } catch {
+        results.push({ url, title: '', html: '', depth, error: 'fetch failed' })
+      }
+
+      if (delaySec > 0) await sleep(delaySec * 1000)
+    }
+    return results
+  }
+
+  return { crawl, results }
+}
+
+module.exports = { createCrawler }

package/browser-op/web/find.js

@@ -0,0 +1,147 @@
+// -*- coding: utf-8 -*-
+//
+// web/find — 元素定位（路由无关）
+//
+// 通用能力: 按文本/selector 找元素, 返回坐标 + CSS path。
+// 解决 SPA 两大定位问题:
+//   ① 标题被拆成多 span → 叶子精确匹配失败 → 兜底取包含匹配最深层
+//   ② aria snapshot 抓不到 (CSS Modules 非语义 DOM) → 不依赖 aria-ref
+//
+// clickByText: 基于此的点击封装 (sycm 这类页面文本是唯一稳定位)
+//
+// 依赖：./browser（operate）
+
+'use strict'
+
+const { operate } = require('./browser')
+
+/**
+ * 查找页面上匹配的元素, 返回坐标 + CSS path。
+ *
+ * 文本匹配策略 (解决标题被拆 span):
+ *   1. 叶子节点精确匹配 (最稳)
+ *   2. 兜底: 任意层级 innerText 包含, 取后代最少的 (最接近文本本身的元素)
+ *
+ * @param {pageHandle} pageHandle
+ * @param {object} criteria
+ * @param {string} [criteria.text]       按文本找 (exact=false 时子串匹配)
+ * @param {boolean} [criteria.exact=false]
+ * @param {string} [criteria.selector]   按 CSS selector 找 (与 text 二选一)
+ * @param {boolean} [criteria.visibleOnly=false] 只返回可见元素
+ * @returns {Promise<{found:boolean, x:number, y:number, width:number, height:number, path:string, text:string}|{found:false}>}
+ */
+async function findElement (pageHandle, criteria = {}) {
+  const { text, exact, selector, visibleOnly } = criteria
+  if (!text && !selector) throw new Error('findElement: text 或 selector 必须传一个')
+  const r = await operate(pageHandle, {
+    action: 'evaluate',
+    source: `(() => {
+      const text = ${JSON.stringify(text || '')}
+      const exact = ${!!exact}
+      const selector = ${JSON.stringify(selector || '')}
+      const visibleOnly = ${!!visibleOnly}
+      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) {
+        // 1. 叶子精确
+        hit = all.find(el => el.children.length === 0 && (exact ? (el.innerText||'').trim()===text : (el.innerText||'').trim()===text))
+        // 2. 兜底: 包含匹配, 取后代最少的 (最接近文本本身)
+        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 }
+      // 生成简短 CSS path (供 click 复用)
+      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)
+      }
+    })()`,
+    _skipVisualize: true
+  }).catch(() => ({ found: false }))
+  return r || { found: false }
+}
+
+/**
+ * 按文本点击元素 (SPA 最稳定定位, sycm 这类页面文本是唯一不随部署变的锚点)。
+ *
+ * 容错 "访客分析 >" 这种 (文本带后缀): 默认 startsWith 匹配, exact=true 则精确。
+ *
+ * @param {pageHandle} pageHandle
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {boolean} [opts.exact=false]   true=精确匹配 "访客分析", false=允许 "访客分析 >"
+ * @param {boolean} [opts.scrollIntoView=true] 点击前滚到元素 (人类化, 找不到时下滚探测)
+ * @returns {Promise<{clicked:boolean, path:string, text:string}>}
+ */
+async function clickByText (pageHandle, text, opts = {}) {
+  const exact = !!opts.exact
+  // 找元素 (findElement 已处理多 span 拆分)
+  let el = await findElement(pageHandle, { text, exact })
+  // 找不到: 下滚探测 (元素在懒加载区, 用 scrollBy 连续)
+  if (!el.found && opts.scrollIntoView !== false) {
+    for (let i = 0; i < 40; i++) {
+      await operate(pageHandle, {
+        action: 'evaluate',
+        source: '() => { window.scrollBy(0, 40 + Math.floor(Math.random()*30)); return null }',
+        _skipVisualize: true
+      })
+      await new Promise(r => setTimeout(r, 60 + Math.random() * 60))
+      el = await findElement(pageHandle, { text, exact })
+      if (el.found) break
+      const atBottom = await operate(pageHandle, { action: 'evaluate', source: '()=>(window.innerHeight + (window.scrollY||0) + 5) >= document.body.scrollHeight', _skipVisualize: true }).catch(()=>false)
+      if (atBottom) break
+    }
+  }
+  if (!el.found) return { clicked: false, error: 'not found: ' + text }
+  // 点击: evaluate 内重新按文本找元素直接 click (不靠 path, path 末尾可能是 span 点不动)
+  // 滚动由 ScrollController 在调用前处理, 这里不 scrollIntoView
+  const clicked = await operate(pageHandle, {
+    action: 'evaluate',
+    source: `(() => {
+      const all = [...document.querySelectorAll('*')]
+      const hit = all.find(e => e.children.length === 0 && (e.innerText||'').trim() === ${JSON.stringify(text)})
+                 || all.find(e => e.children.length === 0 && (e.innerText||'').trim().startsWith(${JSON.stringify(text)}))
+      if (!hit) return false
+      // 点可点击的祖先 (button/a), 不只点 span
+      const clickable = hit.closest('button, a, [role=button], [onclick]') || hit
+      // 高亮同一真实元素 (resolve→mark→click 同一引用, 铁律: 高亮=执行对象)
+      if (window.visualMark) window.visualMark(clickable)
+      clickable.click()
+      return true
+    })()`,
+    _skipVisualize: true
+  })
+  return { clicked: !!(clicked !== false), path: el.path, text: el.text }
+}
+
+module.exports = { findElement, clickByText }

package/browser-op/web/honeypot.js

@@ -0,0 +1,68 @@
+// -*- coding: utf-8 -*-
+//
+// web/honeypot — 蜜罐陷阱检测（路由无关）
+//
+// 完整复刻自 bee/resources/sandbox/builtin-libs/web/honeypot.js。
+// 扫描页面隐藏的陷阱元素（隐藏 link/input/button），避免触发反爬。
+// 基于 operate({action:'evaluate'}) 跑页面 JS。
+//
+// 依赖：./browser（operate）
+
+'use strict'
+
+const { operate } = require('./browser')
+
+// 页面内扫描隐藏陷阱的探测脚本（在页面 MAIN world 执行）
+// 检测：display:none / opacity:0 / visibility:hidden / 零尺寸 / 离屏 / 父级隐藏（向上查 3 层）
+const SCAN_SOURCE = '() => {\n' +
+  '  const traps = []\n' +
+  '  const isHidden = (el) => {\n' +
+  '    const s = getComputedStyle(el)\n' +
+  '    if (s.display === "none") return "display:none"\n' +
+  '    if (parseFloat(s.opacity) === 0) return "opacity:0"\n' +
+  '    if (s.visibility === "hidden") return "visibility:hidden"\n' +
+  '    const r = el.getBoundingClientRect()\n' +
+  '    if (r.width === 0 || r.height === 0) return "zero-size"\n' +
+  '    if (r.top < 0 && r.bottom < 0) return "offscreen-top"\n' +
+  '    if (r.left < 0 && r.right < 0) return "offscreen-left"\n' +
+  '    return null\n' +
+  '  }\n' +
+  '  const walk = (el, depth) => {\n' +
+  '    if (!el || depth > 3) return null\n' +
+  '    const reason = isHidden(el)\n' +
+  '    if (reason) return reason + (depth > 0 ? "(parent)" : "")\n' +
+  '    return walk(el.parentElement, depth + 1)\n' +
+  '  }\n' +
+  '  const sel = "a[href], input, button, [role=button], [onclick]"\n' +
+  '  document.querySelectorAll(sel).forEach((el) => {\n' +
+  '    const reason = walk(el, 0)\n' +
+  '    if (reason) {\n' +
+  '      traps.push({\n' +
+  '        tag: el.tagName.toLowerCase(),\n' +
+  '        text: (el.innerText || el.value || "").slice(0, 80),\n' +
+  '        href: el.getAttribute("href") || null,\n' +
+  '        name: el.getAttribute("name") || null,\n' +
+  '        type: el.getAttribute("type") || null,\n' +
+  '        reason,\n' +
+  '        rect: (() => { const r = el.getBoundingClientRect(); return { x: r.x, y: r.y, w: r.width, h: r.height } })(),\n' +
+  '      })\n' +
+  '    }\n' +
+  '  })\n' +
+  '  return traps\n' +
+  '}'
+
+/**
+ * 扫描页面的隐藏陷阱元素。
+ * @param {object} pageHandle - 单个 page 句柄（来自 newTab）
+ * @returns {Promise<Array<{tag,text,href,name,type,reason,rect}>>}
+ */
+async function scan (pageHandle) {
+  if (!pageHandle) throw new Error('scan: pageHandle required')
+  const r = await operate(pageHandle, { action: 'evaluate', source: SCAN_SOURCE })
+  // evaluate 在 CDP 分支直接返回结果；插件分支返回 {ok,...} 或裸结果，兼容两种
+  return Array.isArray(r) ? r
+    : (r && Array.isArray(r.value) ? r.value
+      : (r && Array.isArray(r.result) ? r.result : []))
+}
+
+module.exports = { scan }