mooncat-browser 0.1.0

package/browser-op/web/ready.js

@@ -0,0 +1,295 @@
+// -*- coding: utf-8 -*-
+//
+// web/ready — 页面就绪等待 + 网页内弹窗清理（路由无关）
+//
+// 标准采集工作流的基础组件:
+//   waitForReady()  等待采集前提 (业务节点/文本出现), 没出现则刷新重试
+//   dismissPopups() 关闭网页内 DOM 弹窗 (modal/popup/dialog, 非浏览器 system dialog)
+//
+// 解决 SPA 场景:
+//   - 页面加载慢, snapshot/采集时主体还没渲染 → waitForReady 等到就绪
+//   - 弹窗挡住主体, snapshot 抓不到目标 → dismissPopups 先清障
+//
+// 依赖：./browser（operate）
+
+'use strict'
+
+const { operate } = require('./browser')
+const { findElement } = require('./find')
+
+// ─── waitForReady: 等业务就绪, 没出现则刷新重试 ───
+
+/**
+ * 等待页面就绪 (采集前提)。
+ *
+ * 判定: snapshot 的 aria 树 / innerText 出现任一 readyText, 或 evaluate fn 返回 truthy。
+ * 没出现则刷新页面, 重试 reloadMax 次。全部失败抛错 (采集不可进行)。
+ *
+ * @param {pageHandle} pageHandle
+ * @param {object} opts
+ * @param {string[]} [opts.readyText]  出现任一即就绪 (在 snapshot yaml 或 body 文本里找)
+ * @param {string} [opts.readySelector] 出现该 selector 即就绪 (DOM 存在)
+ * @param {number} [opts.timeoutMs=30000] 每轮等待总时长
+ * @param {number} [opts.pollMs=2000]     轮询间隔
+ * @param {number} [opts.reloadMax=1]     没就绪时的刷新重试次数 (0=不刷新, 超时就失败)
+ * @param {number} [opts.settleMs=2000]   检测到就绪后再等一会 (等子元素稳定)
+ * @returns {Promise<{ready:true, via:string, attempts:number}>}
+ */
+async function waitForReady (pageHandle, opts = {}) {
+  const readyText = opts.readyText || []
+  const readySelector = opts.readySelector
+  const timeoutMs = opts.timeoutMs || 30000
+  const pollMs = opts.pollMs || 2000
+  const reloadMax = opts.reloadMax == null ? 1 : opts.reloadMax
+  const settleMs = opts.settleMs || 2000
+
+  const check = async () => {
+    // 1. 文本判定: snapshot yaml + body innerText
+    if (readyText.length) {
+      const snap = await operate(pageHandle, { action: 'snapshot', _skipVisualize: true }).catch(() => ({ yaml: '' }))
+      const yaml = snap.yaml || ''
+      for (const t of readyText) {
+        if (yaml.includes(t)) return { ready: true, via: 'snapshot:' + t }
+      }
+      const body = await operate(pageHandle, {
+        action: 'evaluate',
+        source: '() => (document.body && document.body.innerText) || ""',
+        _skipVisualize: true
+      }).catch(() => '')
+      const bodyText = typeof body === 'string' ? body : (body && body.value) || ''
+      for (const t of readyText) {
+        if (bodyText.includes(t)) return { ready: true, via: 'text:' + t }
+      }
+    }
+    // 2. selector 判定
+    if (readySelector) {
+      const c = await operate(pageHandle, { action: 'count', selector: readySelector, _skipVisualize: true }).catch(() => ({ count: 0 }))
+      if (c.count > 0) return { ready: true, via: 'selector:' + readySelector }
+    }
+    return { ready: false }
+  }
+
+  let attempts = 0
+  for (let reload = 0; reload <= reloadMax; reload++) {
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      attempts++
+      const r = await check()
+      if (r.ready) {
+        if (settleMs > 0) await new Promise(res => setTimeout(res, settleMs))
+        return { ready: true, via: r.via, attempts }
+      }
+      await new Promise(res => setTimeout(res, pollMs))
+    }
+    // 这一轮没就绪: 还有重试次数就刷新
+    if (reload < reloadMax) {
+      await operate(pageHandle, { action: 'reload', _skipVisualize: true }).catch(() => {})
+      await new Promise(res => setTimeout(res, 3000)) // 刷新后等主体
+    }
+  }
+  throw new Error(`waitForReady 超时: 未等到就绪条件 text=${JSON.stringify(readyText)} sel=${readySelector || '无'} (尝试 ${attempts} 次, 刷新 ${reloadMax} 次)`)
+}
+
+// ─── dismissPopups: 关闭网页内 DOM 弹窗 ───
+
+// 常见弹窗关闭按钮 selector (语义类 + 通用关闭图标)
+const POPUP_CLOSE_SELECTORS = [
+  // 明确的关闭/取消/我知道了按钮 (按可见文本)
+  // 注: aria-ref 更稳, 但弹窗往往是动态的, 这里用通用 selector 兜底
+  '[class*="close"][aria-label]', '[class*="Close"]',
+  'button[class*="close"]', 'a[class*="close"]',
+  '.modal-close', '.dialog-close', '.popup-close',
+  '[class*="modal"] [class*="close"]', '[class*="dialog"] [class*="close"]',
+  // 通用关闭图标 (×)
+  '[class*="icon-close"]', '[class*="iconClose"]', '.icon-close',
+  // "我知道了/知道了/确定/关闭" 类文本按钮 (通用引导弹窗)
+  // 这类用 evaluate 按文本点更稳, 不放 selector
+]
+
+// 通用引导弹窗的确认文本 (国内站点常见)
+const CONFIRM_TEXTS = ['我知道了', '知道了', '确定', '关闭', '不再提示', '下次再说', '残忍拒绝', '暂不', '取消']
+
+/**
+ * 关闭网页内的 DOM 弹窗 (modal/popup/dialog)。
+ *
+ * 区别于 setDialogHandler (那是浏览器原生 alert/confirm/prompt 的 JS dialog)。
+ * 这个处理的是网页自己渲染的遮罩弹窗 —— 它们会挡住主体, 让 snapshot/点击失效。
+ *
+ * 策略 (逐层尝试, 命中即停):
+ *   1. 找可见的关闭按钮 selector 点击
+ *   2. 找"我知道了/确定/关闭"等文本按钮点击
+ *   3. 兜底: 隐藏所有 [class*=modal]/[class*=popup] 的遮罩元素
+ *
+ * @param {pageHandle} pageHandle
+ * @param {object} [opts]
+ * @param {string[]} [opts.extraCloseTexts]  额外的关闭按钮文本
+ * @param {string[]} [opts.extraSelectors]   额外的关闭按钮 selector
+ * @returns {Promise<{dismissed:number, methods:string[]}>}  关闭了几个, 用了什么方法
+ */
+async function dismissPopups (pageHandle, opts = {}) {
+  const texts = [...CONFIRM_TEXTS, ...(opts.extraCloseTexts || [])]
+  const sels = [...POPUP_CLOSE_SELECTORS, ...(opts.extraSelectors || [])]
+
+  // 一次 evaluate 完成探测+点击+兜底隐藏, 返回关闭了几个 + 方法
+  const result = await operate(pageHandle, {
+    action: 'evaluate',
+    source: `(() => {
+      const texts = ${JSON.stringify(texts)}
+      const sels = ${JSON.stringify(sels)}
+      const methods = []
+      let dismissed = 0
+      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'
+      }
+      const clickIfVis = (el, method) => {
+        if (isVisible(el)) {
+          try { el.click(); dismissed++; methods.push(method) } catch (e) {}
+          return true
+        }
+        return false
+      }
+      // 1. 关闭按钮 selector
+      for (const sel of sels) {
+        let els = []
+        try { els = Array.from(document.querySelectorAll(sel)) } catch (e) { continue }
+        for (const el of els) { if (clickIfVis(el, 'sel:' + sel)) return { dismissed, methods } }
+      }
+      // 2. 文本按钮 (我知道了/确定/关闭...)
+      const btns = Array.from(document.querySelectorAll('button, a, span, div'))
+      for (const el of btns) {
+        const t = (el.innerText || el.textContent || '').trim()
+        if (t.length > 0 && t.length <= 6 && texts.includes(t)) {
+          if (clickIfVis(el, 'text:' + t)) return { dismissed, methods }
+        }
+      }
+      // 3. 兜底: 隐藏可见的 modal/popup 遮罩 (不点, 直接 display:none)
+      const masks = Array.from(document.querySelectorAll('[class*="modal"], [class*="popup"], [class*="dialog"], [class*="Mask"], [class*="overlay"]'))
+      for (const el of masks) {
+        if (isVisible(el) && el.querySelector('button, a') === null) {
+          // 纯遮罩层 (没按钮的) 直接隐藏
+          try { el.style.display = 'none'; dismissed++; methods.push('hide:mask') } catch (e) {}
+        }
+      }
+      return { dismissed, methods }
+    })()`,
+    _skipVisualize: true
+  }).catch(() => ({ dismissed: 0, methods: [] }))
+
+  const r = (result && typeof result === 'object') ? result : { dismissed: 0, methods: [] }
+  return { dismissed: r.dismissed || 0, methods: r.methods || [] }
+}
+
+// ─── scroll: 滚动封装 (SPA 页面数据常需滚动才渲染) ───
+// 模拟人类: 分步 scrollBy + 随机停顿 (不是原生 smooth, 原生平滑无停顿不触发懒加载)
+
+// 分步滚动到目标 scrollY (人类化: 每步 30~60px, 30~60ms 停顿)
+async function humanScrollToY (pageHandle, targetY, maxSteps = 200) {
+  await operate(pageHandle, {
+    action: 'evaluate',
+    source: `(targetY) => new Promise((resolve) => {
+      const start = window.scrollY || window.pageYOffset || 0
+      const dir = targetY > start ? 1 : -1
+      let steps = 0
+      const tick = () => {
+        const cur = window.scrollY || window.pageYOffset || 0
+        steps++
+        if (steps > ${maxSteps} || (dir > 0 ? cur >= targetY - 5 : cur <= targetY + 5)) { resolve(); return }
+        const step = 30 + Math.floor(Math.random() * 30)  // 30~60px/步
+        window.scrollBy(0, dir * step)
+        setTimeout(tick, 30 + Math.random() * 30)  // 30~60ms 停顿
+      }
+      tick()
+    })`,
+    args: targetY,
+    _skipVisualize: true
+  }).catch(() => {})
+}
+
+/**
+ * 滚动到指定文本所在的元素 (SPA 最稳定位)。
+ * 先拿到目标元素 Y, 再人类化分步滚过去 (边滚边看, 触发懒加载)。
+ *
+ * @param {pageHandle} pageHandle
+ * @param {string} text         目标文本 (精确或包含)
+ * @param {object} [opts]
+ * @param {boolean} [opts.exact=false]   true=精确匹配
+ * @param {string} [opts.block='center'] 到位后对齐: 'center'|'start'|'end'
+ * @returns {Promise<{found:boolean, scrolled:boolean}>}
+ */
+async function scrollToText (pageHandle, text, opts = {}) {
+  const exact = !!opts.exact
+  const block = opts.block || 'center'
+  const findPos = async () => {
+    const el = await findElement(pageHandle, { text, exact })
+    if (!el.found) return { found: false }
+    const vh = await operate(pageHandle, { action: 'evaluate', source: '()=>window.innerHeight', _skipVisualize: true }).catch(() => 800)
+    let offset = vh / 2
+    if (block === 'start') offset = 50
+    else if (block === 'end') offset = vh - 50
+    return { found: true, targetY: Math.max(0, el.y + el.height/2 - offset) }
+  }
+  // 1. 先直接找 (元素可能在 DOM 里, 只是没滚到)
+  let pos = await findPos()
+  // 2. 没找到: 人类化逐步下滚, 边滚边找 (SPA 懒加载, 元素滚近才进 DOM)
+  if (!pos || !pos.found) {
+    for (let i = 0; i < 60; 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))
+      pos = await findPos()
+      if (pos && pos.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 (!pos || !pos.found) return { found: false, scrolled: false }
+  // 3. 找到了, 人类化分步滚到目标 Y
+  await humanScrollToY(pageHandle, pos.targetY)
+  await new Promise(r => setTimeout(r, 600))
+  return { found: true, scrolled: true }
+}
+
+/**
+ * 滚动到 selector 元素 (人类化分步)。
+ */
+async function scrollTo (pageHandle, selector, opts = {}) {
+  const block = opts.block || 'center'
+  const el = await findElement(pageHandle, { selector })
+  if (!el.found) return { found: false, scrolled: false }
+  const vh = await operate(pageHandle, { action: 'evaluate', source: '()=>window.innerHeight', _skipVisualize: true }).catch(() => 800)
+  let offset = vh / 2
+  if (block === 'start') offset = 50
+  else if (block === 'end') offset = vh - 50
+  const targetY = Math.max(0, el.y + el.height/2 - offset)
+  await humanScrollToY(pageHandle, targetY)
+  return { found: true, scrolled: true }
+}
+
+/**
+ * 滚动到页顶/页底 (人类化分步)。
+ * @param {'top'|'bottom'} to
+ */
+async function scrollToEnd (pageHandle, to = 'top') {
+  if (to === 'bottom') {
+    // 逐步下滚直到 scrollHeight 不再增长 (触底)
+    await operate(pageHandle, {
+      action: 'evaluate',
+      source: '() => new Promise((resolve) => { let last=-1; const t=setInterval(()=>{ window.scrollBy(0,80+Math.random()*60); const h=document.body.scrollHeight; if(h===last){clearInterval(t);resolve()} last=h }, 80+Math.random()*60) })',
+      _skipVisualize: true
+    }).catch(() => {})
+  } else {
+    const cur = await operate(pageHandle, { action: 'evaluate', source: '()=>window.scrollY||0', _skipVisualize: true }).catch(() => 0)
+    await humanScrollToY(pageHandle, 0)
+  }
+  return true
+}
+
+
+module.exports = { waitForReady, dismissPopups,  scrollToText, scrollTo, scrollToEnd, POPUP_CLOSE_SELECTORS, CONFIRM_TEXTS }

package/browser-op/web/scroll.js

@@ -0,0 +1,167 @@
+// -*- coding: utf-8 -*-
+//
+// web/scroll — 唯一滚动入口 ScrollController（路由无关）
+//
+// 原则: 所有改变 viewport 的动作必须经过这里。
+//   - scrollToY: 启动读一次 startY, clamp target, 单次定方向, 单调 easing, 不越过, 不反向
+//   - scrollBy: = scrollToY(currentY + delta)
+//   - scrollToElement: 算目标→scrollToY→重测→最多一次同向修正, 禁 scrollIntoView
+//   - scrollToEnd: 读 maxScrollY→scrollToY, 只单调
+//   - 返回 trace: {startY, targetY, positions, maxDelta, reversed} 供异常检测
+//
+// 库绝不制造跳变。若页面 JS/虚拟列表/focus/anchoring 导致 reversed/maxDelta 异常,
+// 返回失败 trace, 不静默通过。
+//
+// 依赖: ./browser (operate) — 底层, 不引 find/humanize/ready (避免循环)
+
+'use strict'
+
+const { operate } = require('./browser')
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)))
+
+// 单调缓动 (easeInOutCubic): t∈[0,1] → [0,1], 单调递增
+function ease (t) {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2
+}
+
+async function readScrollY (ph) {
+  const y = await operate(ph, { action: 'evaluate', source: '() => window.scrollY || window.pageYOffset || 0', _skipVisualize: true }).catch(() => 0)
+  return Number(y) || 0
+}
+
+async function readMaxScrollY (ph) {
+  const m = await operate(ph, { action: 'evaluate', source: '() => Math.max(0, (document.body.scrollHeight || 0) - (window.innerHeight || 0))', _skipVisualize: true }).catch(() => 0)
+  return Number(m) || 0
+}
+
+// 设置绝对 scrollY (用 scrollTo 设精确位置, 内部唯一允许; 外部禁止散落用)
+async function setScrollY (ph, y) {
+  await operate(ph, { action: 'evaluate', source: '(y) => { window.scrollTo(0, y); return window.scrollY || 0 }', args: y, _skipVisualize: true }).catch(() => {})
+}
+
+/**
+ * 滚动到指定 scrollY (绝对坐标)。
+ *
+ * 规则:
+ *   - 启动读一次 startY, 之后不靠实时 scrollY 反向修正
+ *   - clamp targetY 到 [0, maxScrollY]
+ *   - 方向一次确定, 单调 easing, 每步 clamp 到目标内, 不越过不反向
+ *
+ * @returns {Promise<{ok, startY, targetY, positions, maxDelta, reversed}>}
+ *   reversed=true 表示页面外部干扰导致实际滚动反向 (异常)
+ */
+async function scrollToY (pageHandle, targetY, opts = {}) {
+  const stepPx = opts.stepPx || 40        // 每步约 40px
+  const stepMs = opts.stepMs || 16        // 每步约 16ms (~60fps)
+  const startY = await readScrollY(pageHandle)
+  const maxY = await readMaxScrollY(pageHandle)
+  const target = Math.max(0, Math.min(targetY, maxY))
+  const distance = Math.abs(target - startY)
+  const dir = target >= startY ? 1 : -1   // 一次定方向
+
+  const steps = Math.max(1, Math.ceil(distance / stepPx))
+  const positions = [startY]
+  let maxDelta = 0
+  let reversed = false
+
+  for (let i = 1; i <= steps; i++) {
+    const t = i / steps
+    const eased = ease(t)
+    // 单调期望位置 (dir 固定, eased 单调)
+    let pos = startY + dir * distance * eased
+    // clamp 到目标内, 绝不越过
+    pos = dir > 0 ? Math.min(pos, target) : Math.max(pos, target)
+    await setScrollY(pageHandle, pos)
+
+    // 采样真实位置 (检测外部干扰, 但不用它决定方向)
+    const real = await readScrollY(pageHandle)
+    positions.push(real)
+    const delta = Math.abs(real - positions[positions.length - 2])
+    if (delta > maxDelta) maxDelta = delta
+    // 反向检测: 期望 dir 前进, 但 real 反向移动 (页面干扰)
+    if (positions.length >= 2) {
+      const prev = positions[positions.length - 2]
+      if (dir > 0 && real < prev - 1) reversed = true
+      if (dir < 0 && real > prev + 1) reversed = true
+    }
+    await sleep(stepMs)
+  }
+
+  // 最终确保落在 target (setScrollY 精确)
+  await setScrollY(pageHandle, target)
+  const final = await readScrollY(pageHandle)
+  positions.push(final)
+
+  return { ok: true, startY, targetY: target, positions, maxDelta, reversed }
+}
+
+/**
+ * 增量滚动 = 读当前 Y + scrollToY。
+ */
+async function scrollBy (pageHandle, deltaPx, opts = {}) {
+  const cur = await readScrollY(pageHandle)
+  return scrollToY(pageHandle, cur + deltaPx, opts)
+}
+
+/**
+ * 滚到元素 (禁 scrollIntoView)。
+ * 算目标 → scrollToY → 重测 → 容差内即停, 否则最多一次同向单调修正。
+ *
+ * @param {string} selector
+ * @param {object} [opts]  opts.block='center'|'start'|'end', opts.tolerance=20
+ * @returns {Promise<{ok, targetY, inViewport, ...trace}>}
+ */
+async function scrollToElement (pageHandle, selector, opts = {}) {
+  const block = opts.block || 'center'
+  const tolerance = opts.tolerance || 20
+
+  const computeTarget = async () => {
+    const r = await operate(pageHandle, {
+      action: 'evaluate',
+      source: `(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (!el) return null; const r = el.getBoundingClientRect(); const vh = window.innerHeight; let off = vh/2; if (${JSON.stringify(block)}==='start') off=50; else if (${JSON.stringify(block)}==='end') off=vh-50; return { targetY: Math.max(0, r.top + (window.scrollY||0) - off), top: Math.round(r.top), vh } })()`,
+      _skipVisualize: true
+    }).catch(() => null)
+    return r
+  }
+
+  const first = await computeTarget()
+  if (!first) return { ok: false, error: 'ELEMENT_NOT_FOUND', selector }
+  const trace = await scrollToY(pageHandle, first.targetY, opts)
+
+  // 重测: 元素是否在容差内
+  const remeasure = await computeTarget()
+  if (!remeasure) return { ok: false, error: 'ELEMENT_NOT_FOUND_AFTER_SCROLL', selector }
+  const inView = Math.abs(remeasure.top - (block === 'start' ? 0 : block === 'end' ? remeasure.vh : remeasure.vh / 2)) < tolerance + 50
+  if (inView) return { ok: true, targetY: first.targetY, inViewport: true, ...trace }
+
+  // 最多一次同向单调修正 (重新算 target 再滚一次)
+  const fix = await computeTarget()
+  if (!fix) return { ok: false, error: 'ELEMENT_NOT_FOUND', selector, inViewport: false, ...trace }
+  const trace2 = await scrollToY(pageHandle, fix.targetY, opts)
+  const remeasure2 = await computeTarget()
+  const inView2 = remeasure2 ? Math.abs(remeasure2.top - (block === 'start' ? 0 : block === 'end' ? remeasure2.vh : remeasure2.vh / 2)) < tolerance + 50 : false
+  return { ok: inView2, targetY: fix.targetY, inViewport: inView2, ...trace, fixTrace: trace2 }
+}
+
+/**
+ * 滚到页顶/页底 (只单调)。
+ * bottom: 读 maxScrollY → scrollToY → 若 scrollHeight 变化则重复 (只向下)。
+ */
+async function scrollToEnd (pageHandle, to = 'top', opts = {}) {
+  if (to === 'top') {
+    return scrollToY(pageHandle, 0, opts)
+  }
+  // bottom: 单调向下, 若页面增高则再来一轮 (最多 5 轮)
+  let lastMax = -1
+  let trace
+  for (let i = 0; i < 5; i++) {
+    const maxY = await readMaxScrollY(pageHandle)
+    if (maxY === lastMax) break
+    lastMax = maxY
+    trace = await scrollToY(pageHandle, maxY, opts)
+  }
+  return trace || { ok: true, startY: 0, targetY: 0, positions: [], maxDelta: 0, reversed: false }
+}
+
+module.exports = { scrollToY, scrollBy, scrollToElement, scrollToEnd, readScrollY, readMaxScrollY }

package/browser-op/web/upload.js

@@ -0,0 +1,116 @@
+// -*- coding: utf-8 -*-
+//
+// web/upload — 通用文件 / 文件夹上传（路由无关，全走 operate）
+//
+// 完整复刻自 bee/resources/sandbox/builtin-libs/web/upload.js。
+// 统一 operate(pageHandle, {action:'setInputFiles'})，operate 内部按路由分流：
+//   cdp 吃本地 paths（playwright 自动展开目录），extension 吃 base64 files。
+// upload 只负责把调用方意图整理成 operate 能懂的参数：
+//   总是同时提供 paths（给 cdp）+ files（给 extension，base64 展开后）。
+//
+// 依赖：./browser（operate）, node:fs + node:path（展开 paths 为 base64）
+
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { operate } = require('./browser')
+
+const MIME_MAP = {
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+  webp: 'image/webp', svg: 'image/svg+xml', ico: 'image/x-icon', bmp: 'image/bmp',
+  pdf: 'application/pdf', txt: 'text/plain', json: 'application/json', csv: 'text/csv',
+  html: 'text/html', htm: 'text/html', xml: 'application/xml', zip: 'application/zip',
+  gz: 'application/gzip', tar: 'application/x-tar',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  xls: 'application/vnd.ms-excel',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  doc: 'application/msword', mp4: 'video/mp4', mp3: 'audio/mpeg',
+  js: 'text/javascript', ts: 'text/plain', css: 'text/css', md: 'text/markdown'
+}
+
+function guessMime (name) {
+  const ext = name.toLowerCase().split('.').pop()
+  return MIME_MAP[ext] || 'application/octet-stream'
+}
+
+function readFileEntry (full, webkitRelativePath) {
+  const buf = fs.readFileSync(full)
+  const name = path.basename(full)
+  return {
+    name,
+    mime: guessMime(name),
+    data: buf.toString('base64'),
+    webkitRelativePath: webkitRelativePath || name
+  }
+}
+
+function walkDir (dir, relBase, out) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const e of entries) {
+    const full = path.join(dir, e.name)
+    const rel = relBase + '/' + e.name
+    if (e.isDirectory()) {
+      walkDir(full, rel, out)
+    } else if (e.isFile()) {
+      out.push(readFileEntry(full, rel))
+    }
+  }
+}
+
+/**
+ * 展开本地路径数组（文件/目录混合）→ base64 文件 entry 数组。
+ * 插件分支用（content 读不到本地文件，必须转 base64）。
+ * CDP 分支不需要（直传路径给 playwright）。
+ * @param {string[]} paths
+ * @returns {Array<{name, mime, data, webkitRelativePath}>}
+ */
+function expandPaths (paths) {
+  const out = []
+  for (const root of paths) {
+    let stat
+    try { stat = fs.statSync(root) } catch { throw new Error('upload: path not found: ' + root) }
+    if (stat.isFile()) {
+      out.push(readFileEntry(root, path.basename(root)))
+    } else if (stat.isDirectory()) {
+      walkDir(root, path.basename(root), out)
+    } else {
+      throw new Error('upload: not a file or directory: ' + root)
+    }
+  }
+  return out
+}
+
+/**
+ * 上传文件 / 文件夹到 <input type=file>。
+ *
+ * @param {object} pageHandle 单个 page 句柄
+ * @param {object} options
+ * @param {string} options.selector 文件输入框 selector（CSS 或 aria-ref=eN）
+ * @param {string[]} options.paths 本地路径数组（文件或目录，可混合）
+ * @returns {Promise<{ok, selector, requested, built, totalBytes}>}
+ *   built: 实际展开出的文件数（目录会展开为多文件，built 可能 > requested）
+ *   不要用 input.files.length 判断是否上传成功（框架接收后会清空），看页面 UI。
+ */
+async function uploadFiles (pageHandle, options = {}) {
+  if (!pageHandle) throw new Error('uploadFiles: pageHandle required')
+  const selector = options.selector
+  if (!selector) throw new Error('uploadFiles: selector required')
+  const paths = Array.isArray(options.paths) ? options.paths : []
+  if (paths.length === 0) throw new Error('uploadFiles: paths required')
+
+  // 同时准备两套：paths 给 cdp 路由（playwright 直吃路径），files 给 extension 路由（base64）。
+  // operate 内部按 pageHandle.mode 选用其一。先展开 base64 以便统一统计 built。
+  const files = expandPaths(paths)
+  const totalBytes = files.reduce((s, f) => s + Math.floor(f.data.length * 0.75), 0)
+  const r = await operate(pageHandle, { action: 'setInputFiles', selector, paths, files })
+  return {
+    ok: r && r.ok !== false,
+    selector,
+    requested: paths.length,
+    built: files.length,
+    totalBytes
+  }
+}
+
+module.exports = { uploadFiles, expandPaths }

package/browser-op/web/visual-runtime.inject.cjs

@@ -0,0 +1,6 @@
+// AUTO-GENERATED from webplater/lib/visual-runtime.ts (single source).
+// 由 webplater scripts/build-visual-runtime.mjs 构建后同步到此。
+// MAIN world 注入串: CDP operate 解析/高亮 + eval 契约 (window.visualMark)。
+// 不要手改本文件, 改 webplater/lib/visual-runtime.ts 后重 build + 同步。
+'use strict'
+module.exports = "(() => {\n  var __defProp = Object.defineProperty;\n  var __export = (target, all) => {\n    for (var name in all)\n      __defProp(target, name, { get: all[name], enumerable: true });\n  };\n\n  // lib/visual-runtime.ts\n  var visual_runtime_exports = {};\n  __export(visual_runtime_exports, {\n    ensureVisualOverlay: () => ensureVisualOverlay,\n    highlightResolved: () => highlightResolved,\n    locateEl: () => locateEl,\n    rectOf: () => rectOf,\n    resolveCount: () => resolveCount,\n    resolveSelector: () => resolveSelector,\n    visualMark: () => visualMark\n  });\n  function refByDomAttribute(ref) {\n    return document.querySelector(`[data-bee-ref=\"${cssEscape(ref)}\"]`) ?? void 0;\n  }\n  function cssEscape(s) {\n    try {\n      return window.CSS?.escape ? window.CSS.escape(s) : s.replace(/[\"\\\\]/g, \"\\\\$&\");\n    } catch {\n      return s.replace(/[\"\\\\]/g, \"\\\\$&\");\n    }\n  }\n  function splitSelector(selector) {\n    const idx = selector.indexOf(\">>\");\n    if (idx < 0) return { base: selector, suffix: \"\" };\n    return { base: selector.slice(0, idx), suffix: selector.slice(idx + 2).trim().toLowerCase() };\n  }\n  function resolveSelector(selector, refLookup) {\n    const { base, suffix } = splitSelector(selector);\n    if (base.startsWith(\"aria-ref=\")) {\n      const ref = base.slice(\"aria-ref=\".length).trim();\n      const lookup = refLookup ?? refByDomAttribute;\n      const el = lookup(ref);\n      if (!el || !document.contains(el)) return null;\n      return el;\n    }\n    const list = Array.from(document.querySelectorAll(base));\n    if (list.length === 0) return null;\n    if (suffix === \"last\") return list[list.length - 1] ?? null;\n    if (suffix.startsWith(\"nth(\") && suffix.endsWith(\")\")) {\n      const n = Number(suffix.slice(4, -1));\n      if (!Number.isInteger(n)) return null;\n      return list[n] ?? null;\n    }\n    return list[0] ?? null;\n  }\n  function locateEl(selector, refLookup) {\n    const el = resolveSelector(selector, refLookup);\n    if (!el) throw new Error(`element not found: ${selector}`);\n    return el;\n  }\n  function resolveCount(selector, refLookup) {\n    const { base } = splitSelector(selector);\n    if (base.startsWith(\"aria-ref=\")) {\n      const ref = base.slice(\"aria-ref=\".length).trim();\n      const lookup = refLookup ?? refByDomAttribute;\n      const el = lookup(ref);\n      return el && document.contains(el) ? 1 : 0;\n    }\n    return document.querySelectorAll(base).length;\n  }\n  function rectOf(el) {\n    const r = el.getBoundingClientRect();\n    return { x: r.left, y: r.top, w: r.width, h: r.height };\n  }\n  var OVERLAY_STYLE_ID = \"bee-visual-style\";\n  var HL_BOX_CLASS = \"bee-hl-box\";\n  var OVERLAY_CSS = [\n    `.${HL_BOX_CLASS}{position:fixed;outline:4px solid #ff0000;outline-offset:3px;box-shadow:0 0 0 7px rgba(255,0,0,.45);z-index:2147483647;pointer-events:none;border-radius:2px}`\n  ].join(\"\\n\");\n  function ensureVisualOverlay() {\n    if (document.getElementById(OVERLAY_STYLE_ID)) return;\n    const s = document.createElement(\"style\");\n    s.id = OVERLAY_STYLE_ID;\n    s.textContent = OVERLAY_CSS;\n    document.head.appendChild(s);\n  }\n  function drawRect(x, y, w, h) {\n    if (w <= 0 || h <= 0) return;\n    ensureVisualOverlay();\n    const box = document.createElement(\"div\");\n    box.className = HL_BOX_CLASS;\n    box.style.cssText = `left:${x}px;top:${y}px;width:${w}px;height:${h}px`;\n    document.body.appendChild(box);\n    setTimeout(() => {\n      box.style.transition = \"opacity 0.3s\";\n      box.style.opacity = \"0\";\n      setTimeout(() => box.remove(), 300);\n    }, 3e3);\n  }\n  function markOne(t) {\n    if (!t) return;\n    if (t instanceof Element) {\n      const r = rectOf(t);\n      drawRect(r.x, r.y, r.w, r.h);\n      return;\n    }\n    if (typeof t === \"object\" && t.x != null) {\n      if (t.w != null && t.h != null) drawRect(t.x, t.y, t.w, t.h);\n      else drawRect(t.x - 15, t.y - 8, 30, 16);\n      return;\n    }\n  }\n  function visualMark(target) {\n    document.querySelectorAll(\".\" + HL_BOX_CLASS).forEach((e) => e.remove());\n    if (Array.isArray(target)) target.forEach(markOne);\n    else markOne(target);\n  }\n  function highlightResolved(selector, refLookup) {\n    const el = resolveSelector(selector, refLookup);\n    if (!el) return false;\n    visualMark(el);\n    return true;\n  }\n\n  // visual-runtime-inject.ts\n  if (typeof window !== \"undefined\") {\n    window.__beeVR = visual_runtime_exports;\n    if (typeof window.visualMark === \"undefined\") window.visualMark = visualMark;\n    if (typeof window.resolveSelector === \"undefined\") window.resolveSelector = resolveSelector;\n    if (typeof window.rectOf === \"undefined\") window.rectOf = rectOf;\n  }\n})();\n"

package/browser-op/webplater/.env.example

@@ -0,0 +1,7 @@
+# FlashBox 对象存储凭证（发布浏览器插件用）。
+# 复制为 .env.local 并填入真实值（与 mini-app / flashbox 主仓库同源 bucket）。
+# .env.local 已在 .gitignore 中，不会提交。
+FLASHBOX_OS_ENDPOINT=
+FLASHBOX_OS_AK=
+FLASHBOX_OS_SK=
+FLASHBOX_OS_BUCKET=