mooncat-browser 0.1.0

package/browser-op/backend/browserd.cjs

@@ -0,0 +1,1004 @@
+// browserd.cjs — browser 后端常驻进程 (detached)
+//
+// 这是唯一真正持有 BrowserOp / Chrome / WebPluginServer 的进程。
+// 业务脚本通过 HTTP IPC (:17322) 和它通信。
+//
+// 启动后:
+//   1. 初始化 IPC server
+//   2. 等待 client 发 open 指令
+//   3. 持有 browserHandle + pageHandle registry
+//   4. 收到 close 才关 Chrome + 退出
+//
+// 不自动退出 (除非 close 或 Chrome 被 kill)。
+
+'use strict'
+
+const http = require('node:http')
+const os = require('node:os')
+const path = require('node:path')
+
+// 找到 skill 根目录 (browserd 在 lib/backend/, 往上两层)
+const SKILL_ROOT = path.resolve(__dirname, '..', '..')
+
+// 复用现有双路由核心
+const { BrowserOp, ChromePathResolver } = require('../index.cjs')
+
+// visual-runtime 注入串 (single source: webplater/lib/visual-runtime.ts → build-visual-runtime.mjs)
+// MAIN world 注入后 window.__beeVR / window.visualMark 可用。CDP 路解析/高亮/eval 契约共用。
+const VISUAL_RUNTIME_SRC = require('../web/visual-runtime.inject.cjs')
+
+// IPC 端口
+const IPC_PORT = Number(process.env.BROWSERD_PORT) || 17322
+const IPC_HOST = '127.0.0.1'
+
+// ─── 状态 ───
+let _op = null            // BrowserOp 实例
+let _bh = null            // browserHandle
+let _browserOpen = false
+let _mode = null           // 'extension' | 'cdp'
+let _playwright = null     // CDP 模式下 require('playwright-core')
+let _cdpBrowser = null     // CDP 模式下的 playwright browser
+let _cdpContext = null     // CDP 模式下的 playwright context
+let _wsEndpoint = null
+
+// pageHandle registry: pageId → { mode, page?(cdp), tabId?(extension), url }
+const _pages = new Map()
+let _pageSeq = 0
+
+// ─── 默认 BrowserOp 工厂 (从 browser.js 搬来) ───
+function getDefaultProfileRoot () {
+  const home = process.env.APPDATA ||
+    (process.platform === 'darwin' ? path.join(os.homedir(), 'Library', 'Application Support') : path.join(os.homedir(), '.local', 'share'))
+  return path.join(home, 'browser-op', 'profiles')
+}
+
+function getDefaultOp (options = {}) {
+  if (_op) return _op
+  const executablePath = options.executablePath ||
+    process.env.BROWSER_OP_CHROME_PATH ||
+    new ChromePathResolver().detect()
+  if (!executablePath) {
+    throw new Error('Chrome 未找到。设 BROWSER_OP_CHROME_PATH 或在 open({executablePath}) 传入。')
+  }
+  const profileRoot = options.profileRoot || process.env.BROWSER_OP_PROFILE_ROOT || getDefaultProfileRoot()
+  const userDataDir = options.userDataDir || process.env.BROWSER_OP_USERDATA || null
+  _op = new BrowserOp({ executablePath, profileRoot, userDataDir })
+  return _op
+}
+
+// ─── getPlaywright (CDP 模式) ───
+async function getPlaywright () {
+  if (_playwright) return _playwright
+  // 用 playwright-core 而非 playwright：browserd 通过 connectOverCDP 连接宿主 Chrome，
+  // 从不启动 playwright 自带浏览器，因此用 playwright-core 避免 install 时下载浏览器。
+  // 两者 API（connectOverCDP / ariaSnapshot mode:'ai'）完全一致。
+  try {
+    _playwright = require('playwright-core')
+  } catch (e) {
+    throw new Error('CDP 路需要 playwright-core。npm i playwright-core (不下载 chromium)。')
+  }
+  return _playwright
+}
+
+// ─── RPC 方法实现 ───
+
+async function rpcOpen (params) {
+  // 已打开 → 返回当前 handle
+  if (_browserOpen && _bh) {
+    return _bh
+  }
+
+  _op = _op || getDefaultOp(params)
+
+  // 状态机在 BrowserOp.open() (lib/index.cjs):
+  //   先抢占唯一 17321 → 等已有 offscreen 回连 → 复用; 没回连才 launch Chrome
+  // browserd 这里只透传。
+  const launchRes = await _op.open(undefined, {
+    headless: params.headless || false,
+    routeMode: params.routeMode || 'auto'
+  })
+  if (!launchRes.ok) {
+    throw new Error('open failed: ' + (launchRes.error || 'browser.open failed'))
+  }
+
+  _mode = launchRes.mode
+  _wsEndpoint = launchRes.wsEndpoint || null
+
+  if (_mode === 'extension') {
+    _bh = { mode: 'extension', notice: launchRes.notice || null, ownerId: 'default' }
+  } else {
+    // CDP: connectOverCDP
+    let wsEndpoint = launchRes.wsEndpoint
+    if (!wsEndpoint && launchRes.port) {
+      const resp = await fetch('http://127.0.0.1:' + launchRes.port + '/json/version')
+      const data = await resp.json()
+      wsEndpoint = data.webSocketDebuggerUrl
+    }
+    if (!wsEndpoint) throw new Error('open failed: no wsEndpoint (port=' + launchRes.port + ')')
+    const pw = await getPlaywright()
+    _cdpBrowser = await pw.chromium.connectOverCDP(wsEndpoint)
+    _cdpContext = _cdpBrowser.contexts()[0] || (await _cdpBrowser.newContext())
+    _bh = { mode: 'cdp', notice: launchRes.notice || null, ownerId: 'default', wsEndpoint }
+  }
+
+  _browserOpen = true
+
+  // 写 state 文件
+  const state = require('./state.cjs')
+  const ud = _op.launcher.getUserDataDir(_op.profileRoot || '', 'default')
+  state.write(ud, { ipcPort: IPC_PORT, mode: _mode, sessionId: 's_' + Date.now() })
+
+  return _bh
+}
+
+async function rpcNewTab (params) {
+  if (!_browserOpen) throw new Error('browser not open; call open() first')
+
+  const url = params.url || ''
+  const force = params.force === true
+
+  // 默认: 同 host 复用已有 tab (导航过去 + 激活), 不开新 tab
+  // force:true 才强制开新 tab
+  if (!force && url) {
+    let urlHost = ''
+    try { urlHost = new URL(url).host } catch {}
+    if (_mode === 'extension') {
+      try {
+        const r = await _op.listTabs()
+        const tabs = (r && r.tabs) || []
+        // 同 host 即视为同一 tab (sycm 等 SPA 会跳转 login, 精确 url 匹配会失败)
+        const hit = tabs.find((t) => {
+          if (!t.url) return false
+          try { return new URL(t.url).host === urlHost } catch { return false }
+        })
+        if (hit) {
+          // 复用: 导航 + 激活
+          await _op.goto(url, hit.id).catch(() => {})
+          await _op.switchTab(hit.id).catch(() => {})
+          // 复用/创建 pageHandle
+          let pageId = null
+          for (const [pid, info] of _pages) {
+            if (info.mode === 'extension' && info.tabId === hit.id) { pageId = pid; break }
+          }
+          if (!pageId) {
+            pageId = 'p' + (++_pageSeq)
+            _pages.set(pageId, { mode: 'extension', tabId: hit.id, url })
+          }
+          return { pageHandle: { mode: 'extension', pageId, tabId: hit.id, url, ownerId: 'default' }, url, title: '', active: false, reused: true }
+        }
+      } catch { /* listTabs 失败兑底开新 */ }
+    } else {
+      // CDP: 在现有 pages 找同 host
+      for (const [pid, info] of _pages) {
+        if (info.mode === 'cdp' && info.page && info.url) {
+          try { if (new URL(String(info.url)).host === urlHost) {
+            await info.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 }).catch(() => {})
+            return { pageHandle: { mode: 'cdp', pageId: pid, url, ownerId: 'default' }, url, title: '', active: false, reused: true }
+          } } catch {}
+        }
+      }
+    }
+  }
+
+  // 开新 tab
+  const pageId = 'p' + (++_pageSeq)
+
+  if (_mode === 'extension') {
+    const r = await _op.newTab(url)
+    const pageHandle = { mode: 'extension', pageId, tabId: r.tabId, url: r.url || url, ownerId: 'default' }
+    _pages.set(pageId, { mode: 'extension', tabId: r.tabId, url: r.url || url })
+    return { pageHandle, url: r.url || url, title: '', active: true, reused: false }
+  }
+
+  // CDP
+  const page = await _cdpContext.newPage()
+  if (url) await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 }).catch(() => {})
+  const finalUrl = page.url() || url
+  const pageHandle = { mode: 'cdp', pageId, url: finalUrl, ownerId: 'default' }
+  _pages.set(pageId, { mode: 'cdp', page, url: finalUrl })
+  return { pageHandle, url: finalUrl, title: '', active: true, reused: false }
+}
+
+async function rpcListTabs (params) {
+  if (!_browserOpen) throw new Error('browser not open')
+
+  if (_mode === 'extension') {
+    const r = await _op.listTabs()
+    const tabs = (r && r.tabs) || []
+    return tabs.map((t) => {
+      // 复用已有 pageId 或新建
+      let pageId = null
+      for (const [pid, info] of _pages) {
+        if (info.mode === 'extension' && info.tabId === t.id) { pageId = pid; break }
+      }
+      if (!pageId) {
+        pageId = 'p' + (++_pageSeq)
+        _pages.set(pageId, { mode: 'extension', tabId: t.id, url: t.url })
+      }
+      return {
+        pageHandle: { mode: 'extension', pageId, tabId: t.id, url: t.url, ownerId: 'default' },
+        url: t.url,
+        title: t.title || '',
+        active: !!t.active
+      }
+    })
+  }
+
+  // CDP
+  const pages = _cdpContext.pages()
+  return pages.map((pg, i) => {
+    let pageId = null
+    for (const [pid, info] of _pages) {
+      if (info.mode === 'cdp' && info.page === pg) { pageId = pid; break }
+    }
+    if (!pageId) {
+      pageId = 'p' + (++_pageSeq)
+      _pages.set(pageId, { mode: 'cdp', page: pg, url: pg.url() })
+    }
+    return {
+      pageHandle: { mode: 'cdp', pageId, url: pg.url(), ownerId: 'default' },
+      url: pg.url(),
+      title: '',
+      active: i === 0
+    }
+  })
+}
+
+/** rpcReuseTab: 按 url 复用 tab (extension 路调插件 reuseTab; cdp 路 fallback 到 listTabs+goto/newTab)。 */
+async function rpcReuseTab (params) {
+  if (!_browserOpen) throw new Error('browser not open')
+  const url = params.url || ''
+  const urlMatchSrc = params.urlMatch
+  const urlMatch = urlMatchSrc ? new RegExp(urlMatchSrc) : null
+
+  if (_mode === 'extension') {
+    const r = await _op.reuseTab(url, urlMatch)
+    // 复用 listTabs 的 pageId 维护逻辑: 为返回的 tabId 找/建 pageId
+    const tabId = r && r.tabId
+    let pageId = null
+    for (const [pid, info] of _pages) {
+      if (info.mode === 'extension' && info.tabId === tabId) { pageId = pid; break }
+    }
+    if (!pageId) {
+      pageId = 'p' + (++_pageSeq)
+      _pages.set(pageId, { mode: 'extension', tabId, url: r.url })
+    }
+    return {
+      ok: true,
+      reused: !!r.reused,
+      tabId,
+      url: r.url,
+      pageHandle: { mode: 'extension', pageId, tabId, url: r.url, ownerId: 'default' }
+    }
+  }
+
+  // CDP: 找现有 page (url 匹配), 有则复用, 无则 newPage
+  const pages = _cdpContext.pages()
+  const hit = urlMatch
+    ? pages.find((pg) => urlMatch.test(pg.url() || ''))
+    : pages.find((pg) => (pg.url() || '') === url)
+  if (hit) {
+    let pageId = null
+    for (const [pid, info] of _pages) { if (info.mode === 'cdp' && info.page === hit) { pageId = pid; break } }
+    if (!pageId) {
+      pageId = 'p' + (++_pageSeq)
+      _pages.set(pageId, { mode: 'cdp', page: hit, url: hit.url() })
+    }
+    await hit.bringToFront().catch(() => {})
+    return { ok: true, reused: true, pageHandle: { mode: 'cdp', pageId, url: hit.url(), ownerId: 'default' }, url: hit.url() }
+  }
+  const pg = await _cdpContext.newPage()
+  if (url) await pg.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 }).catch(() => {})
+  const pageId = 'p' + (++_pageSeq)
+  _pages.set(pageId, { mode: 'cdp', page: pg, url: pg.url() })
+  return { ok: true, reused: false, pageHandle: { mode: 'cdp', pageId, url: pg.url(), ownerId: 'default' }, url: pg.url() }
+}
+
+/** rpcListDownloads / rpcGetDownload / rpcWaitForDownload: 仅 extension 路有 (chrome.downloads API)。 */
+async function rpcListDownloads (params) {
+  if (!_browserOpen) throw new Error('browser not open')
+  if (_mode !== 'extension') throw new Error('listDownloads only supported in extension mode (chrome.downloads API)')
+  return _op.listDownloads(params && params.limit)
+}
+async function rpcGetDownload (params) {
+  if (!_browserOpen) throw new Error('browser not open')
+  if (_mode !== 'extension') throw new Error('getDownload only supported in extension mode')
+  return _op.getDownload(params && params.id)
+}
+async function rpcWaitForDownload (params) {
+  if (!_browserOpen) throw new Error('browser not open')
+  if (_mode !== 'extension') throw new Error('waitForDownload only supported in extension mode')
+  return _op.waitForDownload(params || {})
+}
+
+function resolvePage (pageHandle) {
+  if (!pageHandle || !pageHandle.pageId) {
+    // 明确提示: 传了 TabInfo (有 url/pageHandle 字段) 而非 PageHandle
+    if (pageHandle && pageHandle.pageHandle && pageHandle.pageHandle.pageId) {
+      throw new Error('operate requires PageHandle; you passed a TabInfo — use tab.pageHandle (e.g. operate({ pageHandle: tab.pageHandle, ... }))')
+    }
+    throw new Error('invalid pageHandle: missing pageId (pass tab.pageHandle from newTab()/listTabs())')
+  }
+  const entry = _pages.get(pageHandle.pageId)
+  if (!entry) throw new Error(`unknown pageId: ${pageHandle.pageId}; call listTabs() or newTab() again`)
+  return entry
+}
+
+// ─── setInputFiles 归一化 (双路由统一传文件路径) ───
+const _fs = require('node:fs')
+const _path = require('node:path')
+
+// 判断是否为「路径」形式: 字符串、或对象含 buffer/name 且无 data
+function _isPath (f) { return typeof f === 'string' }
+
+// CDP 路: 返回纯字符串路径数组 (Playwright 原生接受)
+function normalizeFilePaths (files) {
+  if (!Array.isArray(files) || files.length === 0) throw new Error('setInputFiles: files must be a non-empty array of paths')
+  return files.map(f => {
+    if (_isPath(f)) return f
+    throw new Error('setInputFiles CDP: each file must be a path string, got ' + typeof f)
+  })
+}
+
+// Ext 路: 路径 → { name, mime, data(base64) }，content script 只接受此格式
+function normalizeInputFiles (files) {
+  if (!Array.isArray(files) || files.length === 0) throw new Error('setInputFiles: files must be a non-empty array of paths')
+  return files.map(f => {
+    if (!_isPath(f)) throw new Error('setInputFiles extension: each file must be a path string, got ' + typeof f)
+    const buf = _fs.readFileSync(f)
+    const ext = _path.extname(f).slice(1).toLowerCase()
+    return {
+      name: _path.basename(f),
+      mime: _MIME[ext] || 'application/octet-stream',
+      data: buf.toString('base64')
+    }
+  })
+}
+const _MIME = {
+  txt: 'text/plain', log: 'text/plain', csv: 'text/csv',
+  js: 'text/javascript', json: 'application/json', xml: 'text/xml', html: 'text/html',
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp',
+  pdf: 'application/pdf', zip: 'application/zip',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+}
+
+
+// ─── visual-runtime 注入 + CDP 元素级执行 (resolve → highlight → execute 同一 handle) ───
+// 铁律: 高亮对象 = 执行对象。这里用 playwright evaluateHandle 拿真实元素 ElementHandle,
+// 同一 handle 先 visualMark(el) 再 click/fill/... 不二次解析、不漂移。
+
+/** 幂等注入 visual-runtime 到页面 MAIN world。 */
+async function ensureVisualRuntime (page) {
+  const ok = await page.evaluate(() => typeof window.__beeVR === 'object' && window.__beeVR !== null).catch(() => false)
+  if (ok) return
+  // VISUAL_RUNTIME_SRC 是字符串 (IIFE 源码), 必须用 evaluate(fn, [src]) 把它作为参数传入页面后 eval,
+  // 不能直接 page.evaluate(字符串) — playwright 会把字符串当函数对象序列化, 闭包丢失, 实际不执行。
+  await page.evaluate((src) => { /* eslint-disable no-eval */ (0, eval)(src) }, VISUAL_RUNTIME_SRC)
+}
+
+/**
+ * 解析 selector 为真实 ElementHandle (CDP 路同源解析)。
+ * - aria-ref=eN → Playwright 原生 locator (snapshot 也是 Playwright, 同源于 Playwright)
+ * - CSS/>>nth/>>last → 注入的 visual-runtime resolver (单源)
+ * 两种都拿到真实 ElementHandle, 保证 resolve→高亮→执行同一对象。失败返回 null。
+ */
+async function resolveCdpHandle (page, selector) {
+  if (!selector) return null
+  const sel = String(selector)
+  if (sel.startsWith('aria-ref=')) {
+    // Playwright 原生 selector: aria-ref=eN 直接给 page.locator
+    return page.locator(sel).elementHandle({ timeout: 10000 }).catch(() => null)
+  }
+  await ensureVisualRuntime(page)
+  const handle = await page.evaluateHandle((s) => (window.__beeVR ? window.__beeVR.resolveSelector(s, undefined) : null), sel)
+  const exists = await handle.evaluate((el) => !!el).catch(() => false)
+  if (!exists) { await handle.dispose().catch(() => {}); return null }
+  return handle
+}
+
+/**
+ * CDP 交互动作: 解析 selector 出真实 ElementHandle → 高亮同一 handle → 用同一 handle 执行。
+ * 坐标动作 (click/hover 带 x,y) 不解析元素，直接 mouse + 画点。
+ * @returns 操作结果
+ */
+async function cdpPerformInteract (page, action, p) {
+  // 坐标动作: 直接 mouse, 不解析元素 (与 content.ts click 坐标分支对齐)
+  const hasXY = p.x != null && p.y != null
+  if (hasXY && (action === 'click' || action === 'hover')) {
+    if (action === 'click') await page.mouse.click(Number(p.x), Number(p.y))
+    else await page.mouse.move(Number(p.x), Number(p.y))
+    await page.evaluate((c) => window.__beeVR.visualMark({ x: c.x, y: c.y }), { x: Number(p.x), y: Number(p.y) }).catch(() => {})
+    return { ok: true, selector: p.selector, x: Number(p.x), y: Number(p.y) }
+  }
+
+  // 元素动作: resolve → highlight → execute 同一 handle
+  const handle = await resolveCdpHandle(page, p.selector || '')
+  if (!handle) throw new Error('element not found: ' + p.selector)
+  try {
+    await handle.evaluate((el) => window.__beeVR.visualMark(el)).catch(() => {})
+    switch (action) {
+      case 'click': await handle.click({ timeout: 10000 }); return { ok: true, selector: p.selector }
+      case 'fill': await handle.fill(String(p.value ?? ''), { timeout: 10000 }); return { ok: true, selector: p.selector, value: p.value }
+      case 'type': await handle.type(String(p.value ?? ''), { delay: p.delay || 0, timeout: 10000 }); return { ok: true, selector: p.selector }
+      case 'press': await handle.press(p.key, { timeout: 10000 }); return { ok: true, selector: p.selector, key: p.key }
+      case 'hover': await handle.hover({ timeout: 10000 }); return { ok: true, selector: p.selector }
+      case 'focus': await handle.focus(); return { ok: true, selector: p.selector }
+      case 'check': await handle.check({ timeout: 10000 }); return { ok: true, selector: p.selector }
+      case 'uncheck': await handle.uncheck({ timeout: 10000 }); return { ok: true, selector: p.selector }
+      case 'selectOption': await handle.selectOption(p.value, { timeout: 10000 }); return { ok: true, selector: p.selector, value: p.value }
+      case 'dblclick': await handle.dblclick({ timeout: 10000 }); return { ok: true, selector: p.selector }
+      default: throw new Error('cdpPerformInteract: unsupported action ' + action)
+    }
+  } finally {
+    await handle.dispose().catch(() => {})
+  }
+}
+
+/**
+ * CDP dragTo: 双 handle 解析 source/target → 高亮两个 → 同一 handle 执行拖拽。
+ * mouse 序列 (jQuery UI) + HTML5 drag events (原生) 双兼容。
+ */
+async function cdpDragTo (page, p) {
+  const srcHandle = await resolveCdpHandle(page, p.source || '')
+  const dstHandle = await resolveCdpHandle(page, p.target || '')
+  if (!srcHandle) throw new Error('dragTo source not found: ' + p.source)
+  if (!dstHandle) throw new Error('dragTo target not found: ' + p.target)
+  try {
+    await page.evaluate(([s, d]) => window.__beeVR.visualMark([s, d]), [srcHandle, dstHandle]).catch(() => {})
+    // 取两元素中心 (同一 handle)
+    const boxes = await page.evaluate(([s, d]) => {
+      const sr = s.getBoundingClientRect()
+      const dr = d.getBoundingClientRect()
+      return { sx: sr.x + sr.width / 2, sy: sr.y + sr.height / 2, dx: dr.x + dr.width / 2, dy: dr.y + dr.height / 2 }
+    }, [srcHandle, dstHandle])
+    // 1) mouse 序列
+    await page.mouse.move(boxes.sx, boxes.sy)
+    await page.mouse.down()
+    const steps = 10
+    for (let i = 1; i <= steps; i++) {
+      await page.mouse.move(boxes.sx + (boxes.dx - boxes.sx) * i / steps, boxes.sy + (boxes.dy - boxes.sy) * i / steps)
+    }
+    await page.mouse.up()
+    // 2) HTML5 drag events (同一 handle)
+    await page.evaluate(([s, d]) => {
+      const dt = new DataTransfer()
+      const mk = (type, el) => new DragEvent(type, { bubbles: true, cancelable: true, dataTransfer: dt, clientX: 0, clientY: 0 })
+      s.dispatchEvent(mk('dragstart', s))
+      d.dispatchEvent(mk('dragenter', d))
+      d.dispatchEvent(mk('dragover', d))
+      d.dispatchEvent(mk('drop', d))
+      s.dispatchEvent(mk('dragend', s))
+    }, [srcHandle, dstHandle])
+    return { ok: true, source: p.source, target: p.target }
+  } finally {
+    await srcHandle.dispose().catch(() => {})
+    await dstHandle.dispose().catch(() => {})
+  }
+}
+
+/**
+ * CDP locateVisibleText: 扫描可见文本节点返回 bbox (不返回 DOM handle)。
+ * 用 Range.getBoundingClientRect() 取文字精确 bbox。过滤 display/visibility/opacity/零面积/viewport外。
+ * 与 content.ts locateVisibleTextInContent 同源逻辑。
+ */
+async function cdpLocateVisibleText (page, p) {
+  const text = String(p.text ?? '')
+  const exact = p.exact === true
+  const matches = await page.evaluate((args) => {
+    const { text, exact } = args
+    const want = String(text)
+    const out = []
+    const isVisible = (el) => {
+      let cur = el
+      while (cur && cur !== document.body) {
+        const cs = getComputedStyle(cur)
+        if (cs.display === 'none' || cs.visibility === 'hidden' || Number(cs.opacity) === 0) return false
+        cur = cur.parentElement
+      }
+      return true
+    }
+    const vh = window.innerHeight || document.documentElement.clientHeight
+    const vw = window.innerWidth || document.documentElement.clientWidth
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, {
+      acceptNode: (node) => {
+        const t = (node.nodeValue || '').trim()
+        if (!t) return NodeFilter.FILTER_REJECT
+        const hit = exact ? t === want : t.includes(want)
+        if (!hit) return NodeFilter.FILTER_REJECT
+        const parent = node.parentElement
+        if (!parent || !isVisible(parent)) return NodeFilter.FILTER_REJECT
+        return NodeFilter.FILTER_ACCEPT
+      },
+    })
+    while (walker.nextNode()) {
+      const node = walker.currentNode
+      let rect = null
+      try {
+        const range = document.createRange()
+        range.selectNodeContents(node)
+        rect = range.getBoundingClientRect()
+      } catch (e) { rect = node.parentElement.getBoundingClientRect() }
+      if (!rect || rect.width <= 0 || rect.height <= 0) continue
+      const cx = rect.x + rect.width / 2
+      const cy = rect.y + rect.height / 2
+      if (cy < 0 || cy > vh || cx < 0 || cx > vw) continue
+      out.push({
+        text: (node.nodeValue || '').trim().slice(0, 80),
+        x: Math.round(rect.x), y: Math.round(rect.y),
+        width: Math.round(rect.width), height: Math.round(rect.height),
+        centerX: Math.round(cx), centerY: Math.round(cy),
+        visible: true,
+      })
+    }
+    return out
+  }, { text, exact })
+  return { ok: true, matches: matches || [] }
+}
+
+/**
+ * CDP operateSequence: 原子序列执行 (locate/click/wait/downloadWait 在同一 page 串行)。
+ * 中间状态 (saveAs 的 bbox) 存在内存, 不暴露给外层 SDK, 防 DOM 重渲染时序漂移。
+ */
+async function cdpOperateSequence (page, steps) {
+  const saved = {}
+  const results = []
+  const stepsArr = Array.isArray(steps) ? steps : []
+  for (let i = 0; i < stepsArr.length; i++) {
+    const step = stepsArr[i] || {}
+    const action = String(step.action || '')
+    try {
+      if (action === 'locateVisibleText') {
+        const r = await cdpLocateVisibleText(page, step)
+        results.push({ step: i, action, ok: r.ok, count: r.matches?.length })
+        if (step.saveAs && r.matches?.length) saved[String(step.saveAs)] = r.matches[0]
+        if (!r.matches?.length) return { ok: false, results, error: `step ${i} locateVisibleText: text not visible: ${step.text}` }
+      } 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`)
+        await page.mouse.click(x, y, { button: step.button || 'left', clickCount: step.clickCount || 1 })
+        results.push({ step: i, action, ok: true, x, y })
+      } else if (action === 'clickByText') {
+        const r = await cdpLocateVisibleText(page, step)
+        if (!r.matches?.length) return { ok: false, results, error: `step ${i} clickByText: text not visible: ${step.text}` }
+        const m = r.matches[0]
+        const x = Math.round(m.centerX + Number(step.offsetX ?? 0))
+        const y = Math.round(m.centerY + Number(step.offsetY ?? 0))
+        await page.mouse.click(x, y, { button: step.button || 'left', clickCount: step.clickCount || 1 })
+        results.push({ step: i, action, ok: true, x, y })
+        if (step.saveAs) saved[String(step.saveAs)] = m
+      } else if (action === 'waitForTimeout') {
+        await new Promise((r) => setTimeout(r, Number(step.ms ?? 0)))
+        results.push({ step: i, action, ok: true })
+      } else if (action === 'evaluate') {
+        const result = await page.evaluate(step.source)
+        results.push({ step: i, action, ok: true, result })
+      } else if (action === 'waitForSelector') {
+        const timeout = Number(step.timeout ?? 30000)
+        await page.waitForSelector(String(step.selector || ''), { timeout }).catch(() => {})
+        results.push({ step: i, action, ok: true })
+      } else {
+        throw new Error(`step ${i} unknown action: ${action}`)
+      }
+    } catch (e) {
+      return { ok: false, results, error: `step ${i} (${action}) failed: ${e?.message || e}` }
+    }
+  }
+  return { ok: true, results }
+}
+
+async function rpcOperate (params) {
+  if (!_browserOpen) throw new Error('browser not open')
+  const entry = resolvePage(params.pageHandle)
+  const action = params.action
+  const p = params.params || {}
+
+  if (entry.mode === 'extension') {
+    const tabId = entry.tabId
+    switch (action) {
+      case 'goto': return _op.goto(p.url || '', tabId)
+      case 'goBack': return _op.goBack(tabId)
+      case 'goForward': return _op.goForward(tabId)
+      case 'reload': return _op.reload(tabId)
+      case 'status': return _op.status(tabId)
+      case 'waitForLoadState': return _op.waitForLoadState(p.state || 'complete', tabId)
+      case 'closeTab': { const r = await _op.closeTab(tabId); _pages.delete(params.pageHandle.pageId); return r }
+      case 'activate': return _op.switchTab(tabId)
+      case 'click': return _op.click(p.selector, p.x, p.y, tabId)
+      case 'fill': return _op.fill(p.selector, p.value, tabId)
+      case 'type': return _op.type(p.selector, p.value, p.delay, tabId)
+      case 'press': return _op.press(p.selector, p.key, tabId)
+      case 'hover': return _op.hover(p.selector, p.x, p.y, tabId)
+      case 'focus': return _op.focus(p.selector, tabId)
+      case 'mouseMove': return _op.mouseMove(p.x, p.y, tabId)
+      case 'check': return _op.check(p.selector, tabId)
+      case 'uncheck': return _op.uncheck(p.selector, tabId)
+      case 'selectOption': return _op.selectOption(p.selector, p.value, tabId)
+      case 'dblclick': return _op.dblclick(p.selector, tabId)
+      case 'dragTo': return _op.dragTo(p.source, p.target, tabId)
+      /** @action clickAt | group:交互 | desc:坐标点击(绕过selector,CDP路真实鼠标/扩展路合成事件) | param:x:number:req — X坐标 | param:y:number:req — Y坐标 | param:button:string:opt=left — left/right/middle | param:clickCount:number:opt=1 — 点击次数 | returns:{ok,x,y,route} | ext:yes */
+      case 'clickAt': return _op.clickAt(p.x, p.y, { button: p.button, clickCount: p.clickCount }, tabId)
+      /** @action locateVisibleText | group:读取 | desc:定位可见文本节点返回bbox(不返回DOM handle) | param:text:string:req — 要查找的文本 | param:exact:boolean:opt=false — 精确匹配 | param:index:number:opt=0 — 选第几个match | returns:{ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | ext:yes */
+      case 'locateVisibleText': return _op.locateVisibleText(p.text, p.exact, p.index, tabId)
+      /** @action clickByText | group:交互 | desc:定位可见文本后立即点击(原子,防DOM重渲染) | param:text:string:req — 要点击的文本 | param:exact:boolean:opt=false — 精确匹配 | param:index:number:opt=0 — 选第几个match | param:offsetX:number:opt=0 — X偏移 | param:offsetY:number:opt=0 — Y偏移 | returns:{ok,text,x,y,match,route} | ext:yes */
+      case 'clickByText': return _op.clickByText(p, tabId)
+      /** @action operateSequence | group:进阶 | desc:原子序列执行(locate/click/wait在同一页面上下文串行) | param:steps:array:req — 步骤数组 | returns:{ok,results} | ext:yes */
+      case 'operateSequence': return _op.operateSequence(p.steps, tabId)
+      case 'waitForSelector': return _op.waitForSelector(p.selector, p.timeout, tabId)
+      case 'innerHTML': return _op.innerHTML(p.selector, tabId)
+      case 'innerText': return _op.innerText(p.selector, tabId)
+      case 'textContent': return _op.textContent(p.selector, tabId)
+      case 'getAttribute': return _op.getAttribute(p.selector, p.name, tabId)
+      case 'inputValue': return _op.inputValue(p.selector, tabId)
+      case 'boundingBox': return _op.boundingBox(p.selector, tabId)
+      case 'count': return _op.count(p.selector, tabId)
+      case 'screenshot': return _op.screenshot(tabId)
+      case 'snapshot': return _op.snapshot(p, tabId)
+      case 'evaluate': return _op.evaluate(p.source, p.args, tabId, p.frameId)
+      case 'listFrames': return _op.listFrames(tabId)
+      case 'waitForFunction':
+        throw new Error('waitForFunction is not supported in extension mode because page CSP can block string evaluation; use waitForSelector/waitForURL/status or CDP mode')
+      case 'waitForURL': return _op.waitForURL(p.url, p.timeout, tabId)
+      case 'waitForTimeout': return _op.waitForTimeout(p.ms, tabId)
+      case 'setInputFiles': return _op.setInputFiles(p.selector, normalizeInputFiles(p.files), tabId)
+      /** @action setDialogHandler | group:进阶 | desc:设置JS对话框处理 | param:handler:string:req — 处理器 | returns:{ok} | ext:only-extension */
+      case 'setDialogHandler': return _op.setDialogHandler(p.handler, tabId)
+      case 'getLocalStorage': return _op.getLocalStorage(p.keys, tabId)
+      case 'setLocalStorage': return _op.setLocalStorage(p.items, tabId)
+      case 'removeLocalStorage': return _op.removeLocalStorage(p.keys, tabId)
+      case 'clearLocalStorage': return _op.clearLocalStorage(tabId)
+      default: throw new Error(`unknown action: ${action}`)
+    }
+  }
+
+  // CDP: 直接在 page 对象上操作
+  const page = entry.page
+  switch (action) {
+    /** @action goto | group:导航 | desc:导航到URL,等待DOMContentLoaded | param:url:string:req — 目标地址 | returns:{ok,url} | ext:yes */
+    case 'goto': await page.goto(p.url, { waitUntil: 'domcontentloaded', timeout: 20000 }); return { ok: true, url: page.url() }
+    /** @action goBack | group:导航 | desc:后退一页 | param:timeout:number:opt=15000 — 超时毫秒 | returns:{ok,url} | ext:yes */
+    case 'goBack': await page.goBack({ waitUntil: 'domcontentloaded', timeout: p.timeout || 15000 }); return { ok: true, url: page.url() }
+    /** @action goForward | group:导航 | desc:前进一页 | param:timeout:number:opt=15000 — 超时毫秒 | returns:{ok,url} | ext:yes */
+    case 'goForward': await page.goForward({ waitUntil: 'domcontentloaded', timeout: p.timeout || 15000 }); return { ok: true, url: page.url() }
+    /** @action reload | group:导航 | desc:刷新当前页 | param:timeout:number:opt=15000 — 超时毫秒 | returns:{ok,url} | ext:yes */
+    case 'reload': await page.reload({ waitUntil: 'domcontentloaded', timeout: p.timeout || 15000 }); return { ok: true, url: page.url() }
+    /** @action status | group:导航 | desc:读当前页状态(url/title/readyState) | returns:{ok,url,title,readyState,textLength} | ext:yes */
+    case 'status': return { ok: true, url: page.url(), title: await page.title().catch(() => ''), readyState: 'complete', textLength: 0 }
+    /** @action waitForLoadState | group:等待 | desc:等待指定加载状态 | param:state:string:opt=load — load/domcontentloaded/networkidle | param:timeout:number:opt=30000 — 超时毫秒 | returns:{ok} | ext:yes */
+    case 'waitForLoadState': await page.waitForLoadState(p.state || 'load', { timeout: p.timeout || 30000 }).catch(() => {}); return { ok: true }
+    /** @action closeTab | group:标签页 | desc:关闭当前page | returns:{ok} | ext:yes */
+    case 'closeTab': await page.close(); _pages.delete(params.pageHandle.pageId); return { ok: true }
+    /** @action activate | group:标签页 | desc:切到最前(仅可视) | returns:{ok} | ext:yes */
+    case 'activate': await page.bringToFront(); return { ok: true }
+    /** @action click | group:交互 | desc:点击元素(或坐标x,y) | param:selector:string:req — CSS/aria-ref=xx/.cls>>nth(n)/>>last | param:x:number:opt — 坐标(与y同传,绕过selector) | param:y:number:opt — 坐标 | returns:{ok,selector} | ext:yes */
+    /** @action fill | group:交互 | desc:在selector元素填入文本(先清空) | param:selector:string:req — 目标元素 | param:value:string:req — 要填入的文本 | returns:{ok,selector,value} | ext:yes */
+    /** @action type | group:交互 | desc:逐字输入(带延迟,模拟键盘) | param:selector:string:req — 目标元素 | param:value:string:req — 要输入的文本 | param:delay:number:opt=0 — 每键延迟毫秒 | returns:{ok,selector} | ext:yes */
+    /** @action press | group:交互 | desc:在元素上按键 | param:selector:string:req — 目标元素 | param:key:string:req — 键名(如Enter/Tab/a) | returns:{ok,selector,key} | ext:yes */
+    /** @action hover | group:交互 | desc:悬停元素(或坐标) | param:selector:string:req — 目标元素 | param:x:number:opt — 坐标 | param:y:number:opt — 坐标 | returns:{ok,selector} | ext:yes */
+    /** @action focus | group:交互 | desc:聚焦元素 | param:selector:string:req — 目标元素 | returns:{ok,selector} | ext:yes */
+    /** @action check | group:交互 | desc:勾选checkbox/radio | param:selector:string:req — 目标元素 | returns:{ok,selector} | ext:yes */
+    /** @action uncheck | group:交互 | desc:取消勾选 | param:selector:string:req — 目标元素 | returns:{ok,selector} | ext:yes */
+    /** @action selectOption | group:交互 | desc:选择option | param:selector:string:req — 目标select | param:value:string:req — 选项值 | returns:{ok,selector,value} | ext:yes */
+    /** @action dblclick | group:交互 | desc:双击元素 | param:selector:string:req — 目标元素 | returns:{ok,selector} | ext:yes */
+    case 'click':
+    case 'fill':
+    case 'type':
+    case 'press':
+    case 'hover':
+    case 'focus':
+    case 'check':
+    case 'uncheck':
+    case 'selectOption':
+    case 'dblclick':
+      // resolver 单源 + ElementHandle: 解析→高亮→执行同一 handle (铁律: 高亮=执行对象)
+      return await cdpPerformInteract(page, action, p)
+    /** @action mouseMove | group:交互 | desc:移动鼠标到坐标 | param:x:number:req — X坐标 | param:y:number:req — Y坐标 | returns:{ok,x,y} | ext:yes */
+    case 'mouseMove': await page.mouse.move(p.x ?? 0, p.y ?? 0); return { ok: true, x: p.x, y: p.y }
+    /** @action clickAt | group:交互 | desc:坐标点击(CDP路page.mouse真实鼠标) | param:x:number:req — X坐标 | param:y:number:req — Y坐标 | param:button:string:opt=left | param:clickCount:number:opt=1 | returns:{ok,x,y,route} | ext:yes */
+    case 'clickAt': {
+      await page.mouse.click(Number(p.x), Number(p.y), { button: p.button || 'left', clickCount: p.clickCount || 1 })
+      await page.evaluate((c) => window.__beeVR.visualMark({ x: c.x, y: c.y }), { x: Number(p.x), y: Number(p.y) }).catch(() => {})
+      return { ok: true, x: Number(p.x), y: Number(p.y), route: 'cdp' }
+    }
+    /** @action locateVisibleText | group:读取 | desc:定位可见文本节点返回bbox | param:text:string:req | param:exact:boolean:opt=false | param:index:number:opt=0 | returns:{ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | ext:yes */
+    case 'locateVisibleText': {
+      const r = await cdpLocateVisibleText(page, p)
+      return r
+    }
+    /** @action clickByText | group:交互 | desc:定位可见文本后立即点击(CDP路原子) | param:text:string:req | param:exact:boolean:opt=false | param:index:number:opt=0 | param:offsetX:number:opt=0 | param:offsetY:number:opt=0 | returns:{ok,text,x,y,match,route} | ext:yes */
+    case 'clickByText': {
+      const r = await cdpLocateVisibleText(page, p)
+      if (!r.matches || r.matches.length === 0) throw new Error('clickByText: text not visible: ' + p.text)
+      const m = r.matches[Number(p.index ?? 0)] || r.matches[0]
+      const x = Math.round(m.centerX + Number(p.offsetX ?? 0))
+      const y = Math.round(m.centerY + Number(p.offsetY ?? 0))
+      await page.mouse.click(x, y, { button: p.button || 'left', clickCount: p.clickCount || 1 })
+      return { ok: true, text: p.text, x, y, match: m, route: 'cdp' }
+    }
+    /** @action operateSequence | group:进阶 | desc:原子序列执行 | param:steps:array:req | returns:{ok,results} | ext:yes */
+    case 'operateSequence': return await cdpOperateSequence(page, p.steps)
+    /** @action dragTo | group:交互 | desc:拖拽source到target(双兼容mouse+HTML5) | param:source:string:req — 源元素selector | param:target:string:req — 目标元素selector | returns:{ok,source,target} | ext:yes */
+    case 'dragTo': return await cdpDragTo(page, p)
+    /** @action waitForSelector | group:等待 | desc:等待selector元素可见 | param:selector:string:req — 目标元素 | param:timeout:number:opt=30000 — 超时毫秒 | returns:{ok,selector,visible,inViewport} | ext:yes */
+    case 'waitForSelector': {
+      const timeout = p.timeout || 30000
+      // aria-ref: 走 Playwright 原生 locator (snapshot 同源); 否则走 resolver 轮询
+      if (String(p.selector || '').startsWith('aria-ref=')) {
+        const loc = page.locator(p.selector)
+        await loc.waitFor({ state: 'visible', timeout }).catch(() => {})
+        const visible = await loc.isVisible().catch(() => false)
+        if (!visible) throw new Error('waitForSelector timeout (' + timeout + 'ms): ' + p.selector)
+        return { ok: true, selector: p.selector, visible: true }
+      }
+      await ensureVisualRuntime(page)
+      const deadline = Date.now() + timeout
+      let found = null
+      while (Date.now() < deadline) {
+        found = await page.evaluate((sel) => {
+          const el = window.__beeVR.resolveSelector(sel, undefined)
+          if (!el) return null
+          const r = el.getBoundingClientRect()
+          const vh = window.innerHeight || document.documentElement.clientHeight
+          const vw = window.innerWidth || document.documentElement.clientWidth
+          const cx = r.left + r.width / 2
+          const cy = r.top + r.height / 2
+          return { inViewport: cy >= 0 && cy <= vh && cx >= 0 && cx <= vw }
+        }, p.selector).catch(() => null)
+        if (found) return { ok: true, selector: p.selector, visible: true, inViewport: found.inViewport }
+        await new Promise((r) => setTimeout(r, 100))
+      }
+      throw new Error('waitForSelector timeout (' + timeout + 'ms): ' + p.selector)
+    }
+    /** @action innerHTML | group:读取 | desc:读元素innerHTML | param:selector:string:req — 目标元素 | returns:{ok,selector,value} | ext:yes */
+    case 'innerHTML': return { ok: true, selector: p.selector, value: await page.innerHTML(p.selector).catch(() => '') }
+    /** @action innerText | group:读取 | desc:读元素innerText | param:selector:string:req — 目标元素 | returns:{ok,selector,value} | ext:yes */
+    case 'innerText': return { ok: true, selector: p.selector, value: await page.innerText(p.selector).catch(() => '') }
+    /** @action textContent | group:读取 | desc:读元素textContent | param:selector:string:req — 目标元素 | returns:{ok,selector,value} | ext:yes */
+    case 'textContent': return { ok: true, selector: p.selector, value: await page.textContent(p.selector).catch(() => '') }
+    /** @action getAttribute | group:读取 | desc:读元素属性 | param:selector:string:req — 目标元素 | param:name:string:req — 属性名 | returns:{ok,selector,name,value} | ext:yes */
+    case 'getAttribute': return { ok: true, selector: p.selector, name: p.name, value: await page.getAttribute(p.selector, p.name).catch(() => null) }
+    /** @action inputValue | group:读取 | desc:读input/select当前值 | param:selector:string:req — 目标元素 | param:timeout:number:opt=10000 — 超时毫秒 | returns:{ok,selector,value} | ext:yes */
+    case 'inputValue': { const v = await page.locator(p.selector).inputValue({ timeout: p.timeout || 10000 }).catch(() => ''); return { ok: true, selector: p.selector, value: v } }
+    /** @action boundingBox | group:读取 | desc:读元素包围盒(坐标+尺寸) | param:selector:string:req — 目标元素 | returns:{ok,selector,x,y,width,height} | ext:yes */
+    case 'boundingBox': {
+      // 同源: aria-ref 走 Playwright, CSS 走 resolver (resolveCdpHandle 统一)
+      const handle = await resolveCdpHandle(page, p.selector || '')
+      if (!handle) return { ok: false, selector: p.selector, reason: 'not found' }
+      try {
+        const bb = await handle.boundingBox()
+        if (!bb) return { ok: false, selector: p.selector, reason: 'no box' }
+        return { ok: true, selector: p.selector, x: bb.x, y: bb.y, width: bb.width, height: bb.height }
+      } finally { await handle.dispose().catch(() => {}) }
+    }
+    /** @action count | group:读取 | desc:统计selector匹配数 | param:selector:string:req — 目标元素 | returns:{ok,selector,count} | ext:yes */
+    case 'count': {
+      // aria-ref 走 Playwright locator.count, CSS 走 resolver resolveCount
+      if (String(p.selector || '').startsWith('aria-ref=')) {
+        const cnt = await page.locator(p.selector).count().catch(() => 0)
+        return { ok: true, selector: p.selector, count: cnt }
+      }
+      await ensureVisualRuntime(page)
+      const c = await page.evaluate((sel) => window.__beeVR.resolveCount(sel, undefined), p.selector).catch(() => 0)
+      return { ok: true, selector: p.selector, count: c }
+    }
+    /** @action screenshot | group:截图 | desc:截整页PNG(返回dataUrl) | returns:{ok,format,dataUrl} | ext:yes */
+    case 'screenshot': { const buf = await page.screenshot({ type: 'png' }); return { ok: true, format: 'png', dataUrl: 'data:image/png;base64,' + buf.toString('base64') } }
+    /** @action snapshot | group:读取 | desc:aria无障碍快照(返回yaml) | param:depth:number:opt — 树深度 | param:timeout:number:opt=15000 — 超时毫秒 | returns:{ok,yaml,totalChars} | ext:yes */
+    case 'snapshot': {
+      // 对齐 bee snapshotCdp：page.ariaSnapshot({mode:'ai'}) 返回标准 aria yaml。
+      // 不缓存、不切块。depth/interactiveOnly 透传（interactiveOnly 在 ai mode 下不支持，
+      // 调用方需 interactiveOnly 时走 extension 路的 snapshotExt）。
+      try {
+        const full = await page.ariaSnapshot({ mode: 'ai', depth: p.depth, timeout: p.timeout || 15000 })
+        return { ok: true, yaml: full, totalChars: full.length }
+      } catch (e) {
+        // ariaSnapshot 失败（页面卸载/超时）返回空，不阻断调用
+        return { ok: true, yaml: '', totalChars: 0, error: String((e && e.message) || e) }
+      }
+    }
+    /** @action evaluate | group:进阶 | desc:执行页面JS函数(返回其结果) | param:source:string:req — 函数表达式字符串(如()=>document.title) | param:args:any:opt — 传给函数的参数 | returns:由函数返回值决定 | ext:yes */
+    case 'evaluate': {
+      // eval 契约: ensureVisualRuntime 注入后, eval 内可调 window.visualMark(真实元素)
+      await ensureVisualRuntime(page)
+      return await page.evaluate(
+        ({ source, args }) => {
+          // eslint-disable-next-line no-eval
+          const value = (0, eval)(`(${source})`)
+          return typeof value === 'function' ? value(args) : value
+        },
+        { source: p.source, args: p.args ?? null }
+      )
+    }
+    /** @action waitForFunction | group:等待 | desc:等待页面函数返回truthy | param:source:string:req — 函数表达式字符串 | param:timeout:number:opt=30000 — 超时毫秒 | returns:由函数返回值决定 | ext:no (extension路CSP拦截eval) */
+    case 'waitForFunction': return await page.waitForFunction(p.source, { timeout: p.timeout || 30000 })
+    /** @action waitForURL | group:等待 | desc:等待URL匹配 | param:url:string:req — 期望URL(支持glob) | param:timeout:number:opt=30000 — 超时毫秒 | returns:{ok,url} | ext:yes */
+    case 'waitForURL': await page.waitForURL(p.url, { timeout: p.timeout || 30000 }).catch(() => {}); return { ok: true, url: page.url() }
+    /** @action waitForTimeout | group:等待 | desc:固定等待 | param:ms:number:opt=1000 — 等待毫秒 | returns:{ok,ms} | ext:yes */
+    case 'waitForTimeout': await page.waitForTimeout(p.ms || 1000); return { ok: true, ms: p.ms }
+    // localStorage (CDP 路由: 通过 evaluate 操作)
+    /** @action getLocalStorage | group:存储 | desc:读localStorage(不传keys读全部) | param:keys:array:opt — 键名数组(不传读全部) | returns:{ok,storage} | ext:yes */
+    case 'getLocalStorage': {
+      const keys = Array.isArray(p.keys) ? p.keys : null
+      return await page.evaluate(({ keys }) => {
+        const out = {}
+        const ks = keys || Object.keys(localStorage)
+        for (const k of ks) out[k] = localStorage.getItem(k)
+        return { ok: true, storage: out }
+      }, { keys })
+    }
+    /** @action setLocalStorage | group:存储 | desc:写localStorage | param:items:object:req — 键值对{key:value} | returns:{ok,count} | ext:yes */
+    case 'setLocalStorage': {
+      const items = p.items || {}
+      await page.evaluate((items) => {
+        for (const [k, v] of Object.entries(items)) localStorage.setItem(k, v)
+      }, items)
+      return { ok: true, count: Object.keys(items).length }
+    }
+    /** @action removeLocalStorage | group:存储 | desc:删localStorage(不传keys删全部) | param:keys:array:opt — 键名数组(不传删全部) | returns:{ok,count} | ext:yes */
+    case 'removeLocalStorage': {
+      const keys = Array.isArray(p.keys) ? p.keys : Object.keys(localStorage)
+      await page.evaluate((keys) => {
+        for (const k of keys) localStorage.removeItem(k)
+      }, keys)
+      return { ok: true, count: keys.length }
+    }
+    /** @action clearLocalStorage | group:存储 | desc:清空localStorage | returns:{ok} | ext:yes */
+    case 'clearLocalStorage': {
+      await page.evaluate(() => localStorage.clear())
+      return { ok: true }
+    }
+    /** @action setInputFiles | group:进阶 | desc:上传文件到file input | param:selector:string:req — file input元素 | param:files:array:req — 文件绝对路径数组 | param:timeout:number:opt=10000 — 超时毫秒 | returns:{ok,selector,count} | ext:yes */
+    case 'setInputFiles': {
+      // 统一约定: 调用方传字符串文件路径数组。CDP 路 Playwright 原生接受路径。
+      const paths = normalizeFilePaths(p.files)
+      await page.locator(p.selector).setInputFiles(paths, { timeout: p.timeout || 10000 })
+      return { ok: true, selector: p.selector, count: paths.length }
+    }
+    default: throw new Error(`unknown action: ${action}`)
+  }
+}
+
+async function rpcGetCookies (params) {
+  if (!_op) return { ok: true, cookies: [] }
+  return _op.getCookies(params)
+}
+async function rpcSetCookies (params) {
+  // CDP 路由: 用 playwright context.addCookies
+  if (_cdpContext && params.cookies) {
+    const cookies = params.cookies.filter(c => c.name).map(c => ({
+      name: c.name, value: c.value,
+      url: c.url, domain: c.domain, path: c.path,
+      secure: c.secure, httpOnly: c.httpOnly
+    }))
+    await _cdpContext.addCookies(cookies).catch(() => {})
+    return { ok: true, count: cookies.length }
+  }
+  // 扩展路由
+  if (!_op) return { ok: true, count: 0 }
+  return _op.setCookies(params)
+}
+async function rpcClearCookies (params) {
+  if (!_op) return { ok: true }
+  return _op.clearCookies(params)
+}
+
+async function rpcClose () {
+  // 关 Chrome
+  if (_cdpBrowser) { try { await _cdpBrowser.close() } catch {} }
+  if (_op) { try { await _op.close() } catch {} }
+
+  // 清 state
+  const state = require('./state.cjs')
+  if (_op) {
+    const ud = _op.launcher.getUserDataDir(_op.profileRoot || '', 'default')
+    state.clear(ud)
+  }
+
+  // 清 registry
+  _pages.clear()
+  _browserOpen = false
+  _bh = null
+  _mode = null
+  _cdpBrowser = null
+  _cdpContext = null
+
+  // 标记要退出, IPC server 在响应发完后调 shutdownBrowserd
+  _pendingShutdown = true
+
+  return { ok: true, closed: true }
+}
+
+let _pendingShutdown = false
+// close 完成后, browserd 退出 (释放端口 + state)
+let _exiting = false
+function shutdownBrowserd () {
+  if (_exiting) return
+  _exiting = true
+  // 主动断开扩展 WS 长连接 (offscreen 连着的话, server.close() 会等它, 卡住)
+  try {
+    if (typeof _op !== 'undefined' && _op && _op.web && _op.web.server) {
+      _op.web.server.stop()
+    }
+  } catch {}
+  // 强制退出: server.close 最多等 500ms, 超时直接 exit, 不给陈旧进程留机会
+  try {
+    server.close(() => process.exit(0))
+  } catch {}
+  setTimeout(() => process.exit(0), 500)
+}
+
+// ─── IPC Server ───
+
+const server = http.createServer(async (req, res) => {
+  // CORS + JSON
+  res.setHeader('Content-Type', 'application/json')
+
+  if (req.method === 'GET' && req.url === '/health') {
+    res.end(JSON.stringify({
+      ok: true,
+      browserOpen: _browserOpen,
+      mode: _mode,
+      pageCount: _pages.size,
+      // 真实插件会话状态: offscreen 是否连接当前 browserd + 心跳是否活
+      extensionConnected: _op ? _op.web.isConnected : false,
+      extensionAlive: _op ? _op.web.isPluginAlive() : false,
+      pid: process.pid
+    }))
+    return
+  }
+
+  if (req.method === 'POST' && req.url === '/rpc') {
+    let body = ''
+    req.on('data', (c) => { body += c })
+    req.on('end', async () => {
+      try {
+        const msg = JSON.parse(body)
+        const { id, method, params = {} } = msg
+        let result, error
+        try {
+          switch (method) {
+            case 'open': result = await rpcOpen(params); break
+            case 'newTab': result = await rpcNewTab(params); break
+            case 'listTabs': result = await rpcListTabs(params); break
+            case 'operate': result = await rpcOperate(params); break
+            case 'getCookies': result = await rpcGetCookies(params); break
+            case 'setCookies': result = await rpcSetCookies(params); break
+            case 'clearCookies': result = await rpcClearCookies(params); break
+            case 'close': result = await rpcClose(); break
+            case 'reuseTab': result = await rpcReuseTab(params); break
+            case 'listDownloads': result = await rpcListDownloads(params); break
+            case 'getDownload': result = await rpcGetDownload(params); break
+            case 'waitForDownload': result = await rpcWaitForDownload(params); break
+            default: throw new Error(`unknown method: ${method}`)
+          }
+          res.end(JSON.stringify({ id, ok: true, result }))
+          if (_pendingShutdown) shutdownBrowserd()
+        } catch (e) {
+          res.end(JSON.stringify({ id, ok: false, error: e.message }))
+        }
+      } catch (e) {
+        res.end(JSON.stringify({ ok: false, error: 'bad request: ' + e.message }))
+      }
+    })
+    return
+  }
+
+  res.statusCode = 404
+  res.end(JSON.stringify({ ok: false, error: 'not found' }))
+})
+
+server.listen(IPC_PORT, IPC_HOST, () => {
+  // 打印到 stderr 供诊断 (stdout 保持干净给 client)
+  console.error(`[browserd] listening on ${IPC_HOST}:${IPC_PORT}`)
+})
+
+server.on('error', (e) => {
+  console.error(`[browserd] server error: ${e.message}`)
+  process.exit(1)
+})