mooncat-browser 0.1.0

package/browser-op/webplater/entrypoints/background.ts

@@ -0,0 +1,938 @@
+/**
+ * Background service worker.
+ *
+ * MV3 service worker 会被 Chrome 回收，不再直接持有 WebSocket。WS 长连接改由
+ * offscreen document 持有（见 entrypoints/offscreen/）。background 职责：
+ *   1. onStartup/onInstalled 时 ensureOffscreen() 建好 offscreen document
+ *   2. 收到 offscreen 转发的命令（source:'offscreen-command'），执行 tab 级 /
+ *      content / scripting / cookies 等操作，结果回 offscreen，再由 offscreen 回 browserd
+ *   3. 兜底 ensureOffscreen，防止 SW 重启后 offscreen 未建
+ *
+ * 命令链路：browserd :17321 ⇿ offscreen (WS) ⇿ background (runtime message)
+ *
+ * 不依赖窗口焦点：目标 tab 由 switchTab 显式选定，AI 可静默操作任意 tab。
+ */
+
+const OFFSCREEN_URL = 'offscreen.html'
+const CONTENT_TIMEOUT_MS = 15000
+// 长耗时命令放宽：evaluate/waitForFunction 可能等待页面异步结果（interact 的人机输入最长 120s、
+// 无限滚动等）。对齐 playwright evaluate 超时可由调用方控制的语义。
+const CONTENT_LONG_TIMEOUT_MS = 300000
+const LONG_CONTENT_METHODS = new Set(['evaluate', 'waitForFunction'])
+
+export default defineBackground(() => {
+  console.log('[WebPlater] background service worker started')
+
+  // 当前操作的目标 tab。由 switchTab 设置；未设置时取第一个窗口里的活跃 tab 兜底。
+  let currentTabId: number | null = null
+
+  // ── 捕获模式状态 ──
+  // service worker 可能重启，状态不跨重启持久；重启后若需重新开启，bee 会重新调 enableCapture
+  let captureEnabled = false
+  let captureRegistered = false
+
+  // ── 命令分发 ──────────────────────────────────────────────
+
+  async function handleCommand(
+    method: string,
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
+    // 绝大多数命令需要一个目标 tab，先解析出来
+    const tabId = () => resolveTargetTab(params.tabId)
+
+    switch (method) {
+      // ── tab 级：background 直接用 chrome.tabs API ──
+      case 'listTabs':
+        return listTabs()
+      case 'newTab':
+        return createTab(String(params.url ?? ''))
+      case 'switchTab':
+        return switchTab(toTabId(params.tabId))
+      case 'reuseTab':
+        return reuseTab(String(params.url ?? ''), params.urlMatch != null ? new RegExp(String(params.urlMatch)) : undefined)
+      case 'closeTab':
+        return closeTab(toTabId(params.tabId))
+      case 'goto':
+        return gotoTab(await tabId(), String(params.url ?? ''))
+      case 'goBack':
+        return goBack(await tabId())
+      case 'goForward':
+        return goForward(await tabId())
+      case 'reload':
+        return reloadTab(await tabId())
+
+      // ── evaluate：MAIN world 执行 JS (支持指定 frame 进跨域 iframe) ──
+      case 'evaluate':
+        return evaluateInMainWorld(await tabId(), String(params.source ?? ''), params.args, params.frameId)
+
+      // ── listFrames：列出 tab 所有 frame (进 iframe 前先拿 frameId) ──
+      case 'listFrames': {
+        const tid = await tabId()
+        const frames = await chrome.webNavigation.getAllFrames({ tabId: tid })
+        return (frames || []).map(f => ({ frameId: f.frameId, url: f.url, parentFrameId: f.parentFrameId }))
+      }
+
+      // ── 下载：chrome.downloads API (原生下载监听, 不轮询目录) ──
+      case 'listDownloads':
+        return listRecentDownloads(Number(params.limit ?? 20))
+      case 'getDownload':
+        return getDownloadById(Number(params.id))
+      case 'waitForDownload':
+        return waitForDownload({
+          filenameRegex: params.filenameRegex != null ? String(params.filenameRegex) : undefined,
+          sinceMs: params.sinceMs != null ? Number(params.sinceMs) : undefined,
+          timeoutMs: params.timeoutMs != null ? Number(params.timeoutMs) : undefined,
+          intervalMs: params.intervalMs != null ? Number(params.intervalMs) : undefined,
+        })
+
+      // ── 页面状态：background 直接读 tab 信息 ──
+      case 'status':
+        return tabStatus(await tabId())
+      case 'waitForLoadState':
+        return waitForLoadState(await tabId())
+
+      // ── 坐标/文本点击 + 序列 (content script 合成事件, 不走 CDP/debugger) ──
+      // clickAt: 坐标点击, content script 的 pointer/mouse 合成事件序列 (route=extension-content)
+      case 'clickAt':
+        return sendToContent(await tabId(), 'clickAt', { x: Number(params.x), y: Number(params.y), button: params.button, clickCount: params.clickCount, frameId: params.frameId })
+      // clickByText: 定位可见文本 → 立即点击 (content script 原子完成, 防 DOM 重渲染时序漂移)
+      case 'clickByText':
+        return sendToContent(await tabId(), 'clickByText', { text: params.text, exact: params.exact, index: params.index, offsetX: params.offsetX, offsetY: params.offsetY, frameId: params.frameId })
+      // locateVisibleText: 找可见文本节点返回 bbox (content script 扫描, 不返回 DOM handle)
+      case 'locateVisibleText':
+        return sendToContent(await tabId(), 'locateVisibleText', {
+          text: params.text, exact: params.exact, index: params.index, frameId: params.frameId,
+        })
+      // operateSequence: 一组 locate/click/wait/downloadWait 在同一页面上下文串行执行
+      case 'operateSequence':
+        return runOperateSequence(await tabId(), Array.isArray(params.steps) ? params.steps : [])
+
+      // ── 页面动作：转发到 content script（DOM 操作）──
+      case 'click':
+        return sendToContent(await tabId(), 'click', { selector: params.selector, x: params.x, y: params.y })
+      case 'fill':
+        return sendToContent(await tabId(), 'fill', { selector: params.selector, value: params.value })
+      case 'type':
+        return sendToContent(await tabId(), 'type', { selector: params.selector, value: params.value, delay: params.delay })
+      case 'press':
+        return sendToContent(await tabId(), 'press', { selector: params.selector, key: params.key })
+      case 'hover':
+        return sendToContent(await tabId(), 'hover', { selector: params.selector, x: params.x, y: params.y })
+      case 'focus':
+        return sendToContent(await tabId(), 'focus', { selector: params.selector })
+      case 'mouseMove':
+        return sendToContent(await tabId(), 'mouseMove', { x: params.x, y: params.y })
+      case 'check':
+        return sendToContent(await tabId(), 'check', { selector: params.selector })
+      case 'uncheck':
+        return sendToContent(await tabId(), 'uncheck', { selector: params.selector })
+      case 'selectOption':
+        return sendToContent(await tabId(), 'selectOption', { selector: params.selector, value: params.value })
+      case 'waitForSelector':
+        return sendToContent(await tabId(), 'waitForSelector', { selector: params.selector, timeout: params.timeout })
+
+      // ── 读取类：转发 content ──
+      case 'innerHTML':
+        return sendToContent(await tabId(), 'innerHTML', { selector: params.selector })
+      case 'innerText':
+        return sendToContent(await tabId(), 'innerText', { selector: params.selector })
+      case 'textContent':
+        return sendToContent(await tabId(), 'textContent', { selector: params.selector })
+      case 'getAttribute':
+        return sendToContent(await tabId(), 'getAttribute', { selector: params.selector, name: params.name })
+      case 'inputValue':
+        return sendToContent(await tabId(), 'inputValue', { selector: params.selector })
+      case 'boundingBox':
+        return sendToContent(await tabId(), 'boundingBox', { selector: params.selector })
+      case 'count':
+        return sendToContent(await tabId(), 'count', { selector: params.selector })
+      case 'setInputFiles':
+        return sendToContent(await tabId(), 'setInputFiles', { selector: params.selector, files: params.files })
+      case 'getLocalStorage':
+        return sendToContent(await tabId(), 'getLocalStorage', { keys: params.keys })
+      case 'setLocalStorage':
+        return sendToContent(await tabId(), 'setLocalStorage', { items: params.items })
+      case 'removeLocalStorage':
+        return sendToContent(await tabId(), 'removeLocalStorage', { keys: params.keys })
+      case 'clearLocalStorage':
+        return sendToContent(await tabId(), 'clearLocalStorage', {})
+
+      // ── 交互进阶：转发 content ──
+      case 'dblclick':
+        return sendToContent(await tabId(), 'dblclick', { selector: params.selector })
+      case 'dragTo':
+        return sendToContent(await tabId(), 'dragTo', { source: params.source, target: params.target })
+
+      // ── 等待类：转发 content ──
+      case 'waitForFunction':
+        return sendToContent(await tabId(), 'waitForFunction', { source: params.source, timeout: params.timeout, args: params.args })
+      case 'waitForURL':
+        return sendToContent(await tabId(), 'waitForURL', { url: params.url, timeout: params.timeout })
+      case 'waitForTimeout':
+        return sendToContent(await tabId(), 'waitForTimeout', { ms: params.ms })
+
+      // ── dialog：转发 content（在页面设置处理函数）──
+      case 'setDialogHandler':
+        return sendToContent(await tabId(), 'setDialogHandler', { handler: params.handler })
+
+      // ── aria snapshot：转发 content ──
+      case 'snapshot':
+        return sendToContent(await tabId(), 'snapshot', {
+          rootSelector: params.rootSelector,
+          depth: params.depth,
+          interactiveOnly: params.interactiveOnly,
+          chunkId: params.chunkId,
+          chunkSize: params.chunkSize,
+          refresh: params.refresh,
+        })
+
+      // ── 截图：chrome.tabs.captureVisibleTab ──
+      case 'screenshot':
+        return screenshotTab(await tabId())
+
+      // ── cookie：chrome.cookies API ──
+      case 'getCookies':
+        return getCookies(params)
+      case 'setCookies':
+        return setCookies(params)
+      case 'clearCookies':
+        return clearCookies(params)
+
+      // ── 捕获模式：bee 下发 captureInjectJS 字符串，插件注入所有 tab + 监听新 tab/导航 ──
+      case 'enableCapture':
+        return enableCapture(String(params.script ?? ''))
+      case 'disableCapture':
+        return disableCapture()
+      default:
+        throw new Error(`Unknown method: ${method}`)
+    }
+  }
+
+  // ── tab 操作 ──────────────────────────────────────────────
+
+  async function listTabs() {
+    const tabs = await chrome.tabs.query({})
+    return {
+      tabs: tabs
+        .filter((t) => t.id != null)
+        .map((t) => ({
+          id: t.id as number,
+          url: t.url ?? '',
+          title: t.title ?? '',
+          active: !!t.active,
+          current: t.id === currentTabId,
+        })),
+    }
+  }
+
+  async function createTab(url: string) {
+    const tab = await chrome.tabs.create({ url: url || 'about:blank', active: false })
+    if (!tab.id) throw new Error('createTab: no tab id')
+    currentTabId = tab.id
+    // 等 tab 真正开始导航，避免返回时 url 还是 about:blank
+    if (url && url !== 'about:blank') {
+      await waitForNavigationStarted(tab.id, url)
+      const final = await chrome.tabs.get(tab.id)
+      return { ok: true, tabId: tab.id, url: final.url ?? url }
+    }
+    return { ok: true, tabId: tab.id, url: tab.url ?? url }
+  }
+
+  async function switchTab(tabId: number) {
+    // 校验 tab 存在
+    await chrome.tabs.get(tabId)
+    currentTabId = tabId
+    // 真正在 Chrome 层面激活 tab (不只是内部指针), 这样 captureVisibleTab 才能截到
+    await chrome.tabs.update(tabId, { active: true })
+    return { ok: true, tabId }
+  }
+
+  /**
+   * 复用 tab: 按 url 找已开的 tab, 有则切过去复用 (高危平台不重开页面), 无则 newTab。
+   * url 精确匹配优先; urlMatch (正则源串) 提供时用于模糊匹配。
+   * 返回复用 (reused:true) 或新建 (reused:false) 的 tabId。
+   */
+  async function reuseTab(url: string, urlMatch?: RegExp) {
+    const tabs = await chrome.tabs.query({})
+    const hit = urlMatch
+      ? tabs.find((t) => t.id != null && urlMatch.test(t.url ?? ''))
+      : tabs.find((t) => t.id != null && (t.url ?? '') === url)
+    if (hit && hit.id != null) {
+      await switchTab(hit.id)
+      return { ok: true, reused: true, tabId: hit.id, url: hit.url ?? url }
+    }
+    const created = await createTab(url)
+    return { ok: true, reused: false, tabId: created.tabId, url: created.url ?? url }
+  }
+
+  async function closeTab(tabId: number) {
+    await chrome.tabs.remove(tabId)
+    if (currentTabId === tabId) currentTabId = null
+    return { ok: true }
+  }
+
+  async function gotoTab(tabId: number, url: string) {
+    if (!url) throw new Error('goto requires url')
+    await chrome.tabs.update(tabId, { url })
+    currentTabId = tabId
+    // 等 tab 真正开始导航
+    await waitForNavigationStarted(tabId, url)
+    const final = await chrome.tabs.get(tabId)
+    return { ok: true, tabId, url: final.url ?? url }
+  }
+
+  async function goBack(tabId: number) {
+    await chrome.tabs.goBack(tabId)
+    currentTabId = tabId
+    return { ok: true, tabId }
+  }
+
+  async function goForward(tabId: number) {
+    await chrome.tabs.goForward(tabId)
+    currentTabId = tabId
+    return { ok: true, tabId }
+  }
+
+  async function reloadTab(tabId: number) {
+    await chrome.tabs.reload(tabId)
+    currentTabId = tabId
+    return { ok: true, tabId }
+  }
+
+  /** 读取 tab 页面状态（url/title 来自 chrome.tabs，readyState/textLength 来自 content） */
+  async function tabStatus(tabId: number) {
+    const tab = await chrome.tabs.get(tabId)
+    currentTabId = tabId
+    // readyState / body 文本长度需要 content script，容错读取
+    let readyState = 'unknown'
+    let textLength = 0
+    try {
+      const res = (await sendToContent(tabId, 'status', {})) as {
+        readyState?: string
+        textLength?: number
+      } | undefined
+      readyState = res?.readyState ?? 'unknown'
+      textLength = res?.textLength ?? 0
+    } catch {
+      // chrome:// 等无法注入 content 的页面，只返回 tab 基本信息丶
+    }
+    return {
+      ok: true,
+      url: tab.url ?? '',
+      title: tab.title ?? '',
+      readyState,
+      textLength,
+    }
+  }
+
+  /** 等待页面到达指定加载状态（默认 complete） */
+  async function waitForLoadState(tabId: number, state: string = 'complete') {
+    const valid = ['loading', 'interactive', 'complete']
+    const target = valid.includes(state) ? state : 'complete'
+    const deadline = Date.now() + CONTENT_TIMEOUT_MS
+    // 先等导航真正启动（status 进入过 loading），避免导航未开始就误判 complete
+    let sawLoading = false
+    const startDeadline = Date.now() + 5000
+    while (Date.now() < startDeadline && Date.now() < deadline) {
+      try {
+        const tab = await chrome.tabs.get(tabId)
+        if (tab.status === 'loading') { sawLoading = true; break }
+        // 已是 complete 且 url 非 about:blank：可能导航太快已完成，也认为启动过
+        if (tab.status === 'complete' && tab.url && tab.url !== 'about:blank') { sawLoading = true; break }
+      } catch {
+        throw new Error('waitForLoadState: tab lost')
+      }
+      await sleep(80)
+    }
+    void sawLoading
+    // 再等到目标状态
+    while (Date.now() < deadline) {
+      try {
+        const tab = await chrome.tabs.get(tabId)
+        const status = tab.status ?? 'complete'
+        if (target === 'loading') {
+          return { ok: true, tabId, status }
+        }
+        if (status === 'complete') {
+          return { ok: true, tabId, status: 'complete' }
+        }
+      } catch {
+        throw new Error('waitForLoadState: tab lost')
+      }
+      await sleep(150)
+    }
+    throw new Error(`waitForLoadState timeout: ${state}`)
+  }
+
+  /** 截图：截取指定 tab 可视区域，返回 dataURL（png base64） */
+  async function screenshotTab(tabId: number) {
+    currentTabId = tabId
+
+    const tab = await chrome.tabs.get(tabId)
+    if (tab.windowId == null) {
+      throw new Error(`screenshot failed: tab ${tabId} has no windowId`)
+    }
+
+    // captureVisibleTab 只能截当前窗口真实可见的 active tab。
+    // 非 active tab 不自动切(切了画面也不可靠), 直接报明确错误。
+    const activeTabs = await chrome.tabs.query({ windowId: tab.windowId, active: true })
+    const activeTabId = activeTabs[0]?.id ?? null
+    if (activeTabId !== tabId) {
+      throw new Error(
+        'screenshot in extension mode only supports the active visible tab; call operate(ph, { action: \'activate\' }) and make sure the tab is visible before screenshot'
+      )
+    }
+
+    try {
+      const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, { format: 'png' })
+      return { ok: true, tabId, format: 'png', dataUrl }
+    } catch (err) {
+      throw new Error(`screenshot failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  /** 读取 cookie（按 url 过滤，未传 url 则返回全部） */
+  async function getCookies(params: Record<string, unknown>) {
+    const url = params.url ? String(params.url) : undefined
+    const domain = params.domain ? String(params.domain) : undefined
+    const query: chrome.cookies.GetAllDetails = {}
+    if (url) query.url = url
+    if (domain) query.domain = domain
+    const cookies = await chrome.cookies.getAll(query)
+    return {
+      ok: true,
+      cookies: cookies.map((c) => ({
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        secure: c.secure,
+        httpOnly: c.httpOnly,
+        sameSite: c.sameSite,
+        expirationDate: c.expirationDate,
+      })),
+    }
+  }
+
+  /** 设置 cookie */
+  async function setCookies(params: Record<string, unknown>) {
+    const cookies = (params.cookies ?? []) as Array<Record<string, unknown>>
+    for (const c of cookies) {
+      const detail: chrome.cookies.SetDetails = {
+        url: String(c.url ?? ''),
+        name: String(c.name ?? ''),
+        value: String(c.value ?? ''),
+      }
+      if (c.domain) detail.domain = String(c.domain)
+      if (c.path) detail.path = String(c.path)
+      if (c.secure != null) detail.secure = !!c.secure
+      if (c.httpOnly != null) detail.httpOnly = !!c.httpOnly
+      await chrome.cookies.set(detail)
+    }
+    return { ok: true, count: cookies.length }
+  }
+
+  /** 清除 cookie（按 url 或 domain） */
+  async function clearCookies(params: Record<string, unknown>) {
+    const url = params.url ? String(params.url) : undefined
+    const name = params.name ? String(params.name) : undefined
+    if (url) {
+      const removed = await chrome.cookies.remove({ url, name: name ?? '' })
+      return { ok: true, removed: removed != null }
+    }
+    // 未传 url：按 domain 清除全部
+    const domain = params.domain ? String(params.domain) : undefined
+    if (domain) {
+      const all = await chrome.cookies.getAll({ domain })
+      let count = 0
+      for (const c of all) {
+        const scheme = c.secure ? 'https' : 'http'
+        const r = await chrome.cookies.remove({
+          url: `${scheme}://${c.domain.replace(/^\./, '')}${c.path}`,
+          name: c.name,
+        })
+        if (r) count++
+      }
+      return { ok: true, count }
+    }
+    return { ok: false, error: 'clearCookies requires url or domain' }
+  }
+
+  // ── evaluate：MAIN world 执行 (evaluateInMainWorld 在模块级, 供 IIFE + runOperateSequence 共用) ────────
+
+  // ── 转发到 content script ────────────────────────────────
+
+  // sendToContent / evaluateInMainWorld 在模块级 (IIFE 外), 供 IIFE 内 case 分发 +
+  // 模块级 runOperateSequence 共用同一套 (含 ping/inject/retry)。
+
+  // ── 工具 ─────────────────────────────────────────────────
+
+  function toTabId(raw: unknown): number {
+    const n = Number(raw)
+    if (!Number.isFinite(n)) throw new Error('tabId must be a number')
+    return n
+  }
+
+  function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+
+  /**
+   * 等 tab 真正开始加载指定 url（修复 chrome.tabs.create/update 返回时导航未启动的 race）。
+   * chrome.tabs.create/update 触发后，tab.url 更新、status 进入 loading 需要一点时间；
+   * 不等的话 waitForLoadState 可能在导航启动前就误判 complete。
+   * 等 tab.url 包含期望 url 且 status=loading/complete，最多 timeoutMs。
+   */
+  async function waitForNavigationStarted(tabId: number, expectedUrl: string, timeoutMs = 5000): Promise<void> {
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      try {
+        const tab = await chrome.tabs.get(tabId)
+        const urlOk = !expectedUrl || expectedUrl === 'about:blank' || (tab.url && tab.url !== 'about:blank' && tab.url !== '')
+        if (urlOk && (tab.status === 'loading' || tab.status === 'complete')) return
+      } catch {
+        throw new Error('waitForNavigationStarted: tab lost')
+      }
+      await sleep(80)
+    }
+    // 超时不报错：某些页面导航太快或 about:blank，留给 waitForLoadState 处理
+  }
+
+  /**
+   * 解析命令的目标 tab。
+   *
+   * tab 隔离原则：页面动作必须显式传 tabId，不做隐式兜底。
+   * 多个并行工作流共享同一个浏览器实例，靠各自持有的 tabId 隔离，
+   * 避免全局 currentTabId 在并发下串台。
+   *
+   * 仅当命令确实未传 tabId 时，才回退到 currentTabId（单工作流顺序操作的便利）。
+   */
+  async function resolveTargetTab(rawTabId?: unknown): Promise<number> {
+    if (rawTabId != null) return toTabId(rawTabId)
+
+    if (currentTabId != null) {
+      try {
+        await chrome.tabs.get(currentTabId)
+        return currentTabId
+      } catch {
+        currentTabId = null
+      }
+    }
+
+    throw new Error('no target tab: pass tabId explicitly (e.g. from newTab/switchTab)')
+  }
+
+  // ── 捕获模式（enableCapture/disableCapture）─────────────────────
+  //
+  // 脚本本体是插件自带的 public/capture.js（打包进 dist，等价 bee captureInjectJS）。
+  // 注入机制：chrome.scripting.registerContentScripts(world:'MAIN', runAt:'document_start',
+  //   allFrames:true, matches:<all_urls>) ——这是 CDP Page.addScriptToEvaluateOnNewDocument
+  //   的真正等价：注册后每个文档加载（导航/刷新/新 tab/SPA 跳转）都自动执行，
+  //   document_start 即注入，持久存在，不需要 tabs 事件补注入。
+  //
+  // 脚本 installed 标志位防重复安装；enabled 标志位由 enable/disable 控制。
+  // script 参数仍接收（bee 下发）为兼容，但插件用自带的 capture.js，不依赖它。
+
+  const CAPTURE_SCRIPT_ID = 'bee-capture'
+  const CAPTURE_SCRIPT_FILE = 'capture.js'
+
+  /** 注册持久 capture content script（等价 CDP addScriptToEvaluateOnNewDocument） */
+  async function registerCaptureScript(): Promise<void> {
+    if (captureRegistered) return
+    try {
+      await chrome.scripting.unregisterScript({ id: CAPTURE_SCRIPT_ID })
+    } catch {
+      // 未注册过，忽略
+    }
+    await chrome.scripting.registerContentScripts([
+      {
+        id: CAPTURE_SCRIPT_ID,
+        matches: ['<all_urls>'],
+        js: [CAPTURE_SCRIPT_FILE],
+        runAt: 'document_start',
+        allFrames: true,
+        // ISOLATED world（默认）：脚本可直接读 chrome.storage.local，
+        // 所有 tab（含新 tab）状态一致，不依赖 background 内存。
+      },
+    ])
+    captureRegistered = true
+    console.log('[WebPlater] capture script registered (ISOLATED, document_start)')
+  }
+
+  /**
+   * 写 enabled 到 chrome.storage.local。
+   * capture.js（ISOLATED world）监听 storage.onChanged，所有 tab（含新 tab）实时同步。
+   * 不再需要逐 tab executeScript 设标志位。
+   */
+  async function setCaptureEnabled(enabled: boolean): Promise<void> {
+    await chrome.storage.local.set({ bee_capture_enabled: enabled })
+  }
+
+  async function enableCapture(_script: string): Promise<{ ok: boolean }> {
+ await registerCaptureScript()
+    captureEnabled = true
+    await setCaptureEnabled(true)
+    console.log('[WebPlater] enableCapture: storage.bee_capture_enabled=true')
+    return { ok: true }
+  }
+
+  async function disableCapture(): Promise<{ ok: boolean }> {
+    captureEnabled = false
+    await setCaptureEnabled(false)
+    console.log('[WebPlater] disableCapture: storage.bee_capture_enabled=false')
+    return { ok: true }
+  }
+
+  // ── offscreen document 管理 ──────────────────────────────
+  //
+  // offscreen document 持有到 browserd 的 WebSocket 长连接，规避 MV3 service worker
+  // 被回收导致连接中断。background 通过 ensureOffscreen() 保证它存在。
+  let creatingOffscreen: Promise<void> | null = null
+
+  async function hasOffscreen(): Promise<boolean> {
+    // 优先用 getContexts（按类型精确判定）；旧 Chrome 回退 hasDocument
+    try {
+      const contexts = await chrome.runtime.getContexts({
+        contextTypes: [chrome.runtime.ContextType.OFFSCREEN_DOCUMENT],
+      })
+      return contexts.length > 0
+    } catch {
+      return await chrome.offscreen.hasDocument()
+    }
+  }
+
+  async function ensureOffscreen(): Promise<void> {
+    if (await hasOffscreen()) return
+    if (creatingOffscreen) {
+      await creatingOffscreen
+      return
+    }
+    creatingOffscreen = chrome.offscreen.createDocument({
+      url: OFFSCREEN_URL,
+      // Chrome offscreen 的 Reason 枚举无 WEB_SOCKETS；此处只需合法枚举值，
+      // 用途由 justification 说明。offscreen document 内可直接使用 WebSocket。
+      reasons: [chrome.offscreen.Reason.WORKERS],
+      justification: 'Hold a persistent WebSocket to the local host bridge (browserd :17321).',
+    })
+    await creatingOffscreen
+    creatingOffscreen = null
+    console.log('[WebPlater] offscreen document created')
+  }
+
+
+  // ── offscreen 桥接：收到 offscreen 转发的命令，执行后回包 ──
+  chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+    // offscreen 转发的 host 命令
+    if (message?.source === 'offscreen-command') {
+      handleCommand(message.method as string, message.params ?? {})
+        .then((result) => sendResponse({ ok: true, result }))
+        .catch((err) =>
+          sendResponse({ ok: false, error: err instanceof Error ? err.message : String(err) }),
+        )
+      return true // 异步响应
+    }
+
+    // popup 调试：复用同一套命令处理；reconnect 触发 ensureOffscreen
+    if (message?.source === 'bee-plugin-popup') {
+      if (message.method === 'reconnect') {
+        ensureOffscreen()
+          .then(() => sendResponse({ ok: true, result: { offscreen: true } }))
+          .catch((err) =>
+            sendResponse({ ok: false, error: err instanceof Error ? err.message : String(err) }),
+          )
+        return true
+      }
+      handleCommand(message.method as string, message.params ?? {})
+        .then((result) => sendResponse({ ok: true, result }))
+        .catch((err) =>
+          sendResponse({ ok: false, error: err instanceof Error ? err.message : String(err) }),
+        )
+      return true
+    }
+
+    return false
+  })
+
+  // ── 生命周期钩子：保证 offscreen document 存在 ──
+  // service worker 可能休眠/重启；offscreen document 不随 SW 回收销毁，
+  // 但扩展装载 / 浏览器启动时还没建，需在这些钩子里 ensureOffscreen。
+  chrome.runtime.onStartup.addListener(() => {
+    void ensureOffscreen()
+  })
+  chrome.runtime.onInstalled.addListener(() => {
+    void ensureOffscreen()
+  })
+
+  ensureOffscreen()
+})
+
+// ── 下载监听 (chrome.downloads API, 实时查询不依赖 SW 内存) ────────────────
+// 设计: SW 会被回收, 内存状态不可靠。下载查询直接用 chrome.downloads.search
+// 实时查, 不维护易失 Map。provide 三个能力:
+//   - listDownloads: 列出最近下载 (默认最近 20 条)
+//   - getDownload: 查单个下载状态 (by id)
+//   - waitForDownload: 轮询等某下载完成 (按 filenameRegex 或 id, 超时控制)
+// 这几个函数在 background handleCommand 里作 case 暴露给 browserd。
+
+/** 下载状态摘要 (从 chrome.downloads.DownloadItem 提取) */
+interface DownloadSummary {
+  id: number
+  filename: string
+  url: string
+  state: 'in_progress' | 'interrupted' | 'complete'
+  bytesReceived: number
+  totalBytes: number
+  exists: boolean
+}
+
+function summarizeDownload(item: chrome.downloads.DownloadItem): DownloadSummary {
+  return {
+    id: item.id,
+    filename: item.filename || '',
+    url: item.url || (item.finalUrl ?? ''),
+    state: item.state as DownloadSummary['state'],
+    bytesReceived: item.bytesReceived,
+    totalBytes: item.totalBytes,
+    exists: item.exists,
+  }
+}
+
+async function listRecentDownloads(limit = 20): Promise<{ downloads: DownloadSummary[] }> {
+  const items = await chrome.downloads.search({
+    orderBy: ['-startTime'],
+    limit,
+  } as any)
+  return { downloads: (items || []).map(summarizeDownload) }
+}
+
+async function getDownloadById(id: number): Promise<{ download: DownloadSummary | null }> {
+  const items = await chrome.downloads.search({ id })
+  return { download: items && items[0] ? summarizeDownload(items[0]) : null }
+}
+
+/**
+ * 轮询等下载完成。匹配条件:
+ *   - filenameRegex 提供时, 找最近 startTime 最早的、filename 匹配且 state=complete 的
+ *   - sinceMs 提供时, 只看 startTime > sinceMs 的 (下载前时间戳, 防 diff 到旧文件)
+ * 返回匹配的下载摘要; 超时抛错。
+ */
+async function waitForDownload(
+  opts: { filenameRegex?: string; sinceMs?: number; timeoutMs?: number; intervalMs?: number },
+): Promise<{ download: DownloadSummary | null; reason: string }> {
+  const timeoutMs = opts.timeoutMs ?? 60000
+  const intervalMs = opts.intervalMs ?? 2000
+  const regex = opts.filenameRegex ? new RegExp(opts.filenameRegex) : null
+  const since = opts.sinceMs ?? 0
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, intervalMs))
+    const items = (await chrome.downloads.search({ orderBy: ['-startTime'], limit: 20 } as any)) || []
+    // 过滤: 时间 (sinceMs) + 文件名 (regex)
+    const candidates = items.filter((it) => {
+      if (it.startTime == null) return false
+      const ts = Date.parse(it.startTime)
+      if (isNaN(ts) || ts < since) return false
+      if (regex && !regex.test(it.filename || '')) return false
+      return true
+    })
+    // 找一个 complete 的
+    const done = candidates.find((it) => it.state === 'complete' && it.exists)
+    if (done) return { download: summarizeDownload(done), reason: 'complete' }
+    // 有 in_progress/中断 的候选, 继续等
+    const pending = candidates.find((it) => it.state === 'in_progress')
+    if (pending) continue
+    // 候选都没有 = 下载还没触发, 继续等
+  }
+  return { download: null, reason: 'timeout' }
+}
+
+// ── operateSequence: 原子序列执行 ───────────────────────────────
+//
+// 一组 locate/click/wait/downloadWait 在同一页面上下文串行执行, 中间状态 (saveAs 的 bbox)
+// 存在内存, 不暴露给外层 SDK。防 DOM 重渲染导致的外层时序漂移。
+//
+// 支持的 step:
+//   { action: 'locateVisibleText', text, exact?, index?, saveAs?: 'name' }
+//   { action: 'clickAt', x?, y?, from?: 'name', dx?, dy? }   // from 引用之前 saveAs 的 bbox center + dx/dy
+//   { action: 'clickByText', text, exact?, index?, offsetX?, offsetY? }
+//   { action: 'waitForTimeout', ms }
+//   { action: 'waitForDownload', timeout?, filenameRegex?, sinceMs? }
+//   { action: 'evaluate', source }   // 轻量自定义
+
+async function runOperateSequence(
+  tabId: number,
+  steps: Record<string, unknown>[],
+): Promise<{ ok: true; results: unknown[] }> {
+  const saved: Record<string, any> = {}
+  const results: unknown[] = []
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i] || {}
+    const action = String(step.action || '')
+    try {
+      if (action === 'locateVisibleText') {
+        const box = await sendToContent(tabId, 'locateVisibleText', {
+          text: step.text, exact: step.exact, index: step.index, frameId: step.frameId,
+        }) as any
+        results.push({ step: i, action, ok: box?.ok, count: box?.matches?.length })
+        if (step.saveAs && box?.matches?.length) saved[String(step.saveAs)] = box.matches[0]
+        if (!box?.ok || !box?.matches?.length) {
+          return { ok: false, results, error: `step ${i} locateVisibleText: text not visible: ${step.text}` } as any
+        }
+      } else if (action === 'clickAt') {
+        let x = step.x != null ? Number(step.x) : undefined
+        let y = step.y != null ? Number(step.y) : undefined
+        if (step.from && saved[String(step.from)]) {
+          const m = saved[String(step.from)]
+          x = Math.round(m.centerX + Number(step.dx ?? 0))
+          y = Math.round(m.centerY + Number(step.dy ?? 0))
+        }
+        if (x == null || y == null) throw new Error(`step ${i} clickAt: need x,y or from`)
+        const r = await sendToContent(tabId, 'clickAt', { x, y, button: step.button, clickCount: step.clickCount, frameId: step.frameId })
+        results.push({ step: i, action, ok: true, x, y })
+      } else if (action === 'clickByText') {
+        const m0 = step.index != null ? Number(step.index) : 0
+        const r: any = await sendToContent(tabId, 'clickByText', {
+          text: step.text, exact: step.exact, index: m0, offsetX: step.offsetX, offsetY: step.offsetY, frameId: step.frameId,
+        })
+        if (!r?.ok) {
+          return { ok: false, results, error: `step ${i} clickByText: ${r?.error || 'text not visible: ' + step.text}` } as any
+        }
+        results.push({ step: i, action, ok: true, x: r.x, y: r.y })
+        if (step.saveAs && r?.match) saved[String(step.saveAs)] = r.match
+      } else if (action === 'waitForTimeout') {
+        await new Promise((r) => setTimeout(r, Number(step.ms ?? 0)))
+        results.push({ step: i, action, ok: true })
+      } else if (action === 'waitForDownload') {
+        const since = step.sinceMs != null ? Number(step.sinceMs) : Date.now()
+        const r = await waitForDownload({
+          filenameRegex: step.filenameRegex != null ? String(step.filenameRegex) : undefined,
+          sinceMs: since,
+          timeoutMs: Number(step.timeout ?? 60000),
+          intervalMs: Number(step.intervalMs ?? 2000),
+        })
+        results.push({ step: i, action, ok: !!r.download, download: r.download, reason: r.reason })
+        if (!r.download) {
+          return { ok: false, results, error: `step ${i} waitForDownload: timeout` } as any
+        }
+      } else if (action === 'evaluate') {
+        // evaluate 走 MAIN world 动态注入 (不进 content script, 修正之前发 content 的 bug)
+        const r = await evaluateInMainWorld(tabId, String(step.source ?? ''), step.args, typeof step.frameId === 'number' ? step.frameId : undefined)
+        results.push({ step: i, action, ok: true, result: r })
+      } else {
+        throw new Error(`step ${i} unknown action: ${action}`)
+      }
+    } catch (e: any) {
+      return { ok: false, results, error: `step ${i} (${action}) failed: ${e?.message || e}` } as any
+    }
+  }
+  return { ok: true, results }
+}
+
+// ── content script 通信 (模块级, IIFE 外 runOperateSequence 也用这套) ──
+//
+// 稳定性设计: content script 靠 manifest run_at:document_idle 注入, 在 SPA hash 路由切换、
+// document_idle 时机窗口等情况下, listener 可能未就绪 → 'Receiving end does not exist'。
+// 本套发送函数内置 ping/inject/retry: 先 ping 探活, 不就绪则动态注入 content.js 再重试,
+// 不再依赖常驻 content script 的注入时机。
+
+// manifest 里的 content script 产物路径 (动态注入用, 不是 capture 脚本)
+const CONTENT_SCRIPT_FILE = 'content-scripts/content.js'
+
+// 只把这类错误认作"接收端不存在"(需注入重试), 不吞业务错/timeout/unknown method
+function isNoReceiverError(msg: string): boolean {
+  return /Receiving end does not exist|Could not establish connection/i.test(msg)
+}
+
+// 动态注入 content.js 到指定 tab/frame (重复注入会被 Chrome 忽略, 安全)
+async function injectContentScript(tabId: number, frameId?: number): Promise<void> {
+  const target: chrome.scripting.ScriptTarget = { tabId }
+  if (typeof frameId === 'number') target.frameIds = [frameId]
+  await chrome.scripting.executeScript({ target, files: [CONTENT_SCRIPT_FILE] })
+}
+
+// 裸发送: 只做 sendMessage + timeout + lastError + {ok:false} 处理, 不注入不重试
+function sendToContentRaw(
+  tabId: number,
+  method: string,
+  params?: Record<string, unknown>,
+): Promise<unknown> {
+  const limit = LONG_CONTENT_METHODS.has(method) ? CONTENT_LONG_TIMEOUT_MS : CONTENT_TIMEOUT_MS
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error(`content script timeout: ${method}`))
+    }, limit)
+    const frameId = typeof params?.frameId === 'number' ? params.frameId : undefined
+    const sendOptions = frameId !== undefined ? { frameId } : undefined
+    chrome.tabs.sendMessage(
+      tabId,
+      { source: 'bee-plugin', method, params: params ?? {} },
+      sendOptions as any,
+      (response) => {
+        clearTimeout(timeout)
+        if (chrome.runtime.lastError) {
+          reject(new Error(chrome.runtime.lastError.message))
+          return
+        }
+        if (response && typeof response === 'object' && response.ok === false) {
+          reject(new Error((response as { error?: string }).error ?? 'content error'))
+          return
+        }
+        resolve(response)
+      },
+    )
+  })
+}
+
+// 统一 content 发送: 解析 frameId → ping 探活(不就绪则注入+重ping) → 发真实 method
+// (真实 method 再次无接收端则再注入+重发一次) → 其他错直接抛
+async function sendToContent(
+  tabId: number,
+  method: string,
+  params?: Record<string, unknown>,
+): Promise<unknown> {
+  const frameId = typeof params?.frameId === 'number' ? params.frameId : undefined
+
+  // 1. ping 探活 (不就绪则注入一次再 ping)
+  try {
+    await sendToContentRaw(tabId, 'ping', { frameId })
+  } catch (e: any) {
+    const msg = String(e?.message || e)
+    if (!isNoReceiverError(msg)) throw e // 非"无接收端"错, 直接抛 (timeout 等)
+    // content script 未就绪 → 注入后重 ping
+    await injectContentScript(tabId, frameId)
+    await sendToContentRaw(tabId, 'ping', { frameId })
+  }
+
+  // 2. 发真实 method (再次无接收端则注入+重发一次)
+  try {
+    return await sendToContentRaw(tabId, method, params)
+  } catch (e: any) {
+    const msg = String(e?.message || e)
+    if (!isNoReceiverError(msg)) throw e // 业务错/timeout 直接抛, 不重试
+    await injectContentScript(tabId, frameId)
+    return await sendToContentRaw(tabId, method, params)
+  }
+}
+
+// evaluate: MAIN world 动态注入执行 JS (不依赖常驻 content script, 随时可用)
+// frameId 指定进跨域 iframe (如淘宝统一登录 iframe)。供 IIFE 内 case 'evaluate' +
+// 模块级 runOperateSequence 的 evaluate 子步共用。
+async function evaluateInMainWorld(tabId: number, source: string, args?: unknown, frameId?: number) {
+  if (!source) throw new Error('evaluate requires source')
+  const target: chrome.scripting.ScriptTarget = { tabId }
+  if (typeof frameId === 'number') target.frameIds = [frameId]
+  const [injection] = await chrome.scripting.executeScript({
+    target,
+    world: 'MAIN',
+    func: async (src: string, evalArgs: unknown) => {
+      // eslint-disable-next-line no-eval
+      const value = (0, eval)(`(${src})`)
+      if (typeof value === 'function') {
+        return await value(evalArgs)
+      }
+      return value
+    },
+    args: [source, args ?? null],
+  })
+  return injection?.result
+}