mooncat-browser 0.1.0

package/browser-op/extension/extension-detect.cjs

@@ -0,0 +1,228 @@
+// -*- coding: utf-8 -*-
+//
+// extension-detect.cjs — 启动前检测：扫浏览器 profile，判断 WebPlater 扩展是否装好且未禁用。
+// 完整复刻自 bee/packages/app/browser-op/main/web/extension-detect.ts。
+//
+// 用途：双路由 open() 决策走插件通道还是 CDP 通道。
+//   - 扩展装好且未禁用 → 走插件通道（无 CDP 端口，WS 通信）
+//   - 否则              → 走 CDP 通道（CdpBrowserLauncher，带调试端口）
+//
+// 判据（基于真实 Chrome profile 数据结构）：
+//   扩展设置存在 `Secure Preferences`（不是 `Preferences`）的
+//   `extensions.settings.<id>` 下，字段：
+//     - manifest.name : 扩展名（webplater 的 manifest 无 key，id 随 load 路径变，
+//                       故按 name=="WebPlater" 匹配，不按固定 id）
+//     - disable_reasons : 数组（非空 = 被禁用），如 [8192]
+//     - path : 相对 profile 的扩展目录，形如 "<id>\\<ver>_0"
+//     - state : 多数扩展无此字段，不可靠，不作为判据
+//
+//   扩展文件存在 `<profile>/Extensions/<id>/<ver>/manifest.json`。
+
+'use strict'
+
+const { existsSync, readFileSync, readdirSync, statSync } = require('node:fs')
+const { join } = require('node:path')
+
+/** webplater 扩展名（manifest.name），作为 fallback 匹配依据 */
+const WEBPLATER_EXTENSION_NAME = 'WebPlater'
+
+/**
+ * webplater 固定 extensionId（manifest.key 决定，不随 load 路径变）。
+ * 由 webplater 的 wxt.config.ts manifest.key 按 Chrome 算法稳定算出。
+ * 这是主判据——比 name 匹配稳（name 可能多语言/__MSG__/被改）。
+ * 与 webplater 仓库的 manifest.key 必须保持一致，任一方变动需同步。
+ */
+const WEBPLATER_EXTENSION_ID = 'npkapgkjeaaipldb'
+
+/**
+ * @typedef {Object} ExtensionDetectResult
+ * @property {boolean} installed      是否装了（无论禁用与否）
+ * @property {string|null} profileDir 找到扩展的 profile 子目录绝对路径，未装为 null
+ * @property {string|null} extensionId 扩展 id
+ * @property {string|null} name        Secure Preferences 里的 manifest.name
+ * @property {boolean} disabled        是否被禁用（disable_reasons 非空数组）
+ * @property {boolean} usable          是否既装了又未禁用 — open() 路由判据
+ * @property {boolean} hasFiles        Extensions 目录下是否有 manifest.json 文件
+ */
+
+/** Preferences 文件优先级：Secure Preferences 先（扩展真实落点），Preferences 兜底 */
+const PREF_FILES = ['Secure Preferences', 'Preferences']
+
+function readJson (path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 扫描 user-data-dir 下所有可能的 profile 子目录（Default/Profile 1/...）。
+ * 返回找到的扩展检测结果（第一个含 WebPlater 的 profile）。
+ *
+ * 参数是 Chrome 的 user-data-dir (如 .../profiles/default), 不是 profileRoot
+ * (.../profiles)。扩展在 user-data-dir/Default/Secure Preferences 下。
+ * 同时兼容传入目录本身就是 profile 的情况 (load unpacked 到默认 profile)。
+ * @param {string} userDataDir
+ * @returns {ExtensionDetectResult}
+ */
+function detectWebplaterExtension (userDataDir) {
+  if (!userDataDir || !existsSync(userDataDir)) {
+    return emptyResult()
+  }
+
+  // 候选 profile 子目录：Default / Profile 1 / Profile 2 / ...
+  const profileDirs = listProfileDirs(userDataDir)
+
+  for (const dir of profileDirs) {
+    const result = scanProfile(dir)
+    if (result.installed) return result
+  }
+
+  return emptyResult()
+}
+
+function listProfileDirs (userDataDir) {
+  const dirs = []
+  // 1. 传入目录本身可能就是一个 profile (直接有 Secure Preferences)。
+  //    某些 load unpacked 场景扩展落在默认 profile, 不在 Default 子目录。
+  if (hasAnyPrefFile(userDataDir)) dirs.push(userDataDir)
+
+  // 2. Chromium 标准: userDataDir/Default + userDataDir/Profile N
+  const defaultDir = join(userDataDir, 'Default')
+  if (existsSync(defaultDir) && statSync(defaultDir).isDirectory()) dirs.push(defaultDir)
+
+  try {
+    for (const name of readdirSync(userDataDir)) {
+      if (/^Profile \d+$/.test(name)) {
+        const full = join(userDataDir, name)
+        if (statSync(full).isDirectory()) dirs.push(full)
+      }
+    }
+  } catch { /* ignore */ }
+
+  return dirs
+}
+
+function hasAnyPrefFile (dir) {
+  return PREF_FILES.some((f) => existsSync(join(dir, f)))
+}
+
+function scanProfile (profileDir) {
+  for (const prefFile of PREF_FILES) {
+    const prefPath = join(profileDir, prefFile)
+    if (!existsSync(prefPath)) continue
+
+    const prefs = readJson(prefPath)
+    if (!prefs || typeof prefs !== 'object') continue
+
+    const settings = prefs.extensions && prefs.extensions.settings
+    if (!settings || typeof settings !== 'object') continue
+
+    // 遍历所有扩展设置, 用 resolveExtensionInfo 读真实 name (对齐 bee)
+    // load unpacked (location=4) 时 setting.manifest 常缺失, name 要从
+    // setting.path 指向的 manifest.json 读 — 这是 WebPlater 的实际情况
+    for (const [id, entry] of Object.entries(settings)) {
+      if (!entry) continue
+      const info = resolveExtensionInfo(entry, profileDir)
+      // 主判据: 固定 extensionId 命中, 或 name == WebPlater
+      const matched = id === WEBPLATER_EXTENSION_ID ||
+                      info?.name === WEBPLATER_EXTENSION_NAME ||
+                      (entry.manifest && entry.manifest.name === WEBPLATER_EXTENSION_NAME)
+      if (!matched) continue
+
+      const disabled = Array.isArray(entry.disable_reasons) && entry.disable_reasons.length > 0
+      const manifestDir = info?.manifestDir || profileDir
+      const hasFiles = existsSync(join(manifestDir, 'manifest.json')) ||
+                       checkExtensionFiles(profileDir, id, entry)
+
+      return {
+        installed: true,
+        profileDir,
+        extensionId: id,
+        name: info?.name || (entry.manifest && entry.manifest.name) || WEBPLATER_EXTENSION_NAME,
+        disabled,
+        usable: !disabled && hasFiles,
+        hasFiles
+      }
+    }
+  }
+
+  return emptyResult()
+}
+
+/**
+ * 从 setting 解析扩展的真实 name 与 manifest.json 所在目录 (对齐 bee)。
+ * Chrome 存储两种形态:
+ *   - 商店安装 (location=3): setting.manifest.name 有值, 文件在
+ *     <profile>/Extensions/<id>/<ver>/manifest.json
+ *   - load unpacked (location=4): setting.manifest 常缺失, path 是**绝对路径**
+ *     指向扩展根目录, manifest.json 在该根目录下
+ * 返回 { name, manifestDir } 或 null。
+ */
+function resolveExtensionInfo (setting, profileDir) {
+  if (setting.path) {
+    const root = existsSync(setting.path) ? setting.path : join(profileDir, setting.path)
+    const manifestPath = join(root, 'manifest.json')
+    if (existsSync(manifestPath)) {
+      const m = readJson(manifestPath)
+      if (m && m.name) return { name: m.name, manifestDir: root }
+    }
+    // path 可能是 <id>\<ver>_0 这种商店子目录形式: manifest 在下一层
+    if (existsSync(root)) {
+      try {
+        for (const v of readdirSync(root)) {
+          const mp = join(root, v, 'manifest.json')
+          if (existsSync(mp)) {
+            const m = readJson(mp)
+            if (m && m.name) return { name: m.name, manifestDir: join(root, v) }
+          }
+        }
+      } catch { /* ignore */ }
+    }
+  }
+  // fallback: setting.manifest.name (部分安装方式 Chrome 会内联 manifest)
+  if (setting.manifest && setting.manifest.name) {
+    return { name: setting.manifest.name, manifestDir: profileDir }
+  }
+  return null
+}
+
+function checkExtensionFiles (profileDir, extensionId, entry) {
+  const extBase = join(profileDir, 'Extensions', extensionId)
+  if (!existsSync(extBase)) return false
+
+  try {
+    for (const ver of readdirSync(extBase)) {
+      const manifest = join(extBase, ver, 'manifest.json')
+      if (existsSync(manifest)) return true
+    }
+  } catch { /* ignore */ }
+
+  // fallback: entry.path 给出的相对路径
+  if (entry.path) {
+    const byPath = join(profileDir, entry.path, 'manifest.json')
+    if (existsSync(byPath)) return true
+  }
+
+  return false
+}
+
+function emptyResult () {
+  return {
+    installed: false,
+    profileDir: null,
+    extensionId: null,
+    name: null,
+    disabled: false,
+    usable: false,
+    hasFiles: false
+  }
+}
+
+module.exports = {
+  detectWebplaterExtension,
+  WEBPLATER_EXTENSION_ID,
+  WEBPLATER_EXTENSION_NAME,
+  PREF_FILES
+}

package/browser-op/extension/server.cjs

@@ -0,0 +1,197 @@
+// -*- coding: utf-8 -*-
+//
+// server.cjs — 本地 WebSocket 主机，供 WebPlater 扩展连接。
+// 完整复刻自 bee/packages/app/browser-op/main/web/server.ts。
+//
+// 协议：
+//   - 监听 127.0.0.1:17321
+//   - 扩展 background service worker 连入
+//   - 主机通过 callPlugin() 下发命令，扩展通过 response 回包
+//   - 扩展断开时，所有挂起 callPlugin 立即 reject（不等超时）
+//   - 扩展周期发 hello/ping 保活，主机据此判 isPluginAlive
+
+'use strict'
+
+const { WebSocketServer, WebSocket } = require('ws')
+
+const DEFAULT_HOST = '127.0.0.1'
+const DEFAULT_PORT = 17321
+const COMMAND_TIMEOUT_MS = 15000
+// 长耗时命令放宽：evaluate/waitForFunction 可能长计算或等异步（interact 人机输入最长 120s）
+const COMMAND_LONG_TIMEOUT_MS = 300000
+const LONG_TIMEOUT_METHODS = new Set(['evaluate', 'waitForFunction'])
+
+function defaultLog () {
+  if (process.env.BROWSER_OP_DEBUG) {
+    console.error.apply(console, arguments)
+  }
+}
+
+class WebPluginServer {
+  constructor (info = defaultLog) {
+    this.info = info
+    this.wss = null
+    this.socket = null
+    this.seq = 1
+    this.pending = new Map()
+    /** 最近一次收到扩展 hello/ping 的时间戳。alive 判据 = Date.now() - lastSeenAt < 阈值 */
+    this.lastSeenAt = 0
+  }
+
+  get isConnected () {
+    return this.socket !== null && this.socket.readyState === WebSocket.OPEN
+  }
+
+  /**
+   * 插件心跳是否存活。
+   * 扩展每 20s 发一次 ping，阈值放宽到 45s 容忍抖动。
+   * 双路由 open() 决策：alive → 走插件通道；否则 → CDP。
+   */
+  isPluginAlive (thresholdMs = 45000) {
+    return this.lastSeenAt > 0 && Date.now() - this.lastSeenAt < thresholdMs
+  }
+
+  async start (host = DEFAULT_HOST, port = DEFAULT_PORT) {
+    if (this.wss) return true
+
+    return new Promise((resolve, reject) => {
+      this.wss = new WebSocketServer({ host, port })
+
+      this.wss.on('error', (err) => {
+        if (err.message.includes('EADDRINUSE')) {
+          // 必须失败: 17321 被占说明已有 browserd 在管插件, 不能两个同时管
+          this.info('[web] port %d already in use — EADDRINUSE', port)
+          this.wss = null
+          reject(new Error(`EADDRINUSE: port ${port} already in use (another browserd owns it)`))
+          return
+        }
+        this.info('[web] server error: %s', err.message)
+        this.wss = null
+        reject(err)
+      })
+
+      this.wss.on('listening', () => {
+        this.info('[web] server listening on ws://%s:%d', host, port)
+        resolve(true)
+      })
+
+      this.wss.on('connection', (socket) => {
+        if (this.socket && this.socket !== socket) {
+          this.info('[web] new connection replaced previous socket')
+          this.socket.terminate()
+        }
+        this.socket = socket
+        this.info('[web] extension connected')
+
+        socket.on('message', (raw) => this.handleMessage(raw))
+        socket.on('close', () => {
+          if (this.socket === socket) {
+            this.socket = null
+            this.info('[web] extension disconnected')
+            this.rejectAllPending('extension disconnected')
+          }
+        })
+        socket.on('error', (err) => {
+          this.info('[web] socket error: %s', err.message)
+        })
+      })
+    })
+  }
+
+  async stop () {
+    this.rejectAllPending('server stopping')
+    if (this.socket) {
+      this.socket.terminate()
+      this.socket = null
+    }
+    if (!this.wss) return
+
+    const wss = this.wss
+    this.wss = null
+    return new Promise((resolve) => {
+      wss.close(() => resolve())
+    })
+  }
+
+  /** 向扩展下发一条命令并等待回包 */
+  async callPlugin (method, params) {
+    if (!this.isConnected) {
+      throw new Error('Plugin not connected')
+    }
+
+    const id = this.seq++
+    const command = { id, type: 'command', method, params }
+    const limit = LONG_TIMEOUT_METHODS.has(method) ? COMMAND_LONG_TIMEOUT_MS : COMMAND_TIMEOUT_MS
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`Plugin command timeout: ${method}`))
+      }, limit)
+
+      this.pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timeout)
+          resolve(value)
+        },
+        reject: (err) => {
+          clearTimeout(timeout)
+          reject(err)
+        },
+        timeout
+      })
+
+      this.socket.send(JSON.stringify(command))
+    })
+  }
+
+  handleMessage (raw) {
+    let msg
+    try {
+      const text = Buffer.isBuffer(raw)
+        ? raw.toString()
+        : Array.isArray(raw)
+          ? Buffer.concat(raw).toString()
+          : Buffer.from(raw).toString()
+      msg = JSON.parse(text)
+    } catch {
+      this.info('[web] invalid JSON from extension')
+      return
+    }
+
+    if (!msg || typeof msg !== 'object') return
+
+    if (msg.type === 'hello' || msg.type === 'ping') {
+      // 记录心跳时间（hello 首连 + ping 周期保活）
+      this.lastSeenAt = Date.now()
+      return
+    }
+
+    if (msg.type === 'response') {
+      const item = this.pending.get(msg.id)
+      if (!item) return
+
+      this.pending.delete(msg.id)
+      if (msg.ok) {
+        item.resolve(msg.result)
+      } else {
+        item.reject(new Error(msg.error || 'Plugin error'))
+      }
+    }
+  }
+
+  /** 拒绝所有挂起命令（扩展断开 / server 关闭时调用） */
+  rejectAllPending (reason) {
+    for (const [, item] of this.pending) {
+      clearTimeout(item.timeout)
+      item.reject(new Error(reason))
+    }
+    this.pending.clear()
+  }
+}
+
+module.exports = {
+  WebPluginServer,
+  DEFAULT_HOST,
+  DEFAULT_PORT
+}

package/browser-op/extension/service.cjs

@@ -0,0 +1,228 @@
+// -*- coding: utf-8 -*-
+//
+// service.cjs — 插件路 WebService 业务门面。
+// 完整复刻自 bee/packages/app/browser-op/main/web/service.ts（去 DI、纯 JS）。
+//
+// 职责：转发所有命令到 WebPlater 扩展（callPlugin）+ 维护 WS server + 检测/心跳。
+// 浏览器启停由 index.cjs 的 BrowserOp 类负责（双路由统一）。
+//
+// API 全集（与扩展协议对齐，参数顺序与 TS 原版一致）：
+//   生命周期: startServer / stopServer
+//   检测:     isConnected / isPluginAlive / checkRoute
+//   tab:      listTabs / switchTab / closeTab / newTab
+//   导航:     goto / goBack / goForward / reload / waitForLoadState / waitForURL
+//   交互:     click / dblclick / fill / type / press / hover / mouseMove / focus /
+//             check / uncheck / selectOption / dragTo
+//   等待:     waitForSelector / waitForFunction / waitForTimeout
+//   读取:     innerHTML / innerText / textContent / getAttribute / inputValue /
+//             boundingBox / count / status / snapshot
+//   存储:     getLocalStorage / setLocalStorage / removeLocalStorage / clearLocalStorage
+//   截图:     screenshot
+//   cookie:   getCookies / setCookies / clearCookies
+//   dialog:   setDialogHandler
+//   捕获:     enableCapture / disableCapture
+//   评估:     evaluate
+
+'use strict'
+
+const { WebPluginServer } = require('./server.cjs')
+const { detectWebplaterExtension } = require('./extension-detect.cjs')
+
+const BROWSER_PROFILES_DEFAULT = 'browser/profiles'
+
+class WebService {
+  constructor (deps = {}) {
+    this.info = deps.info || (() => {})
+    this.errorLog = deps.errorLog || (() => {})
+    /** profileRoot：WebPlater 扩展安装位置。由调用方注入（index.cjs 注入 userDataDir 的父目录） */
+    this.profileRoot = deps.profileRoot || null
+    this.server = new WebPluginServer(this.info)
+  }
+
+  setProfileRoot (root) {
+    this.profileRoot = root
+  }
+
+  // ── 生命周期 ──────────────────────────────────────────────
+
+  async startServer () {
+    await this.server.start()
+  }
+
+  async stopServer () {
+    await this.server.stop()
+  }
+
+  // 注：浏览器启动/关闭由 index.cjs 的 BrowserOp 类负责。
+  //     本 service 只维护 WS server（插件通信）+ 转发命令 + 检测/心跳。
+
+  // ── 扩展能力 ───────────────────────────────────────────────
+
+  get isConnected () {
+    return this.server.isConnected
+  }
+
+  /** 插件心跳是否存活 */
+  isPluginAlive (thresholdMs) {
+    return this.server.isPluginAlive(thresholdMs)
+  }
+
+  /** 捕获模式：把 captureInjectJS 字符串下发给插件，插件注入所有 tab + 监听新 tab */
+  enableCapture (script) {
+    return this.server.callPlugin('enableCapture', { script })
+  }
+
+  /** 捕获模式关闭：插件移除注入 + 关标志位 */
+  disableCapture () {
+    return this.server.callPlugin('disableCapture', {})
+  }
+
+  /**
+   * 双路由可用性检测（open 前调用）。
+   * 两层判据：启动前扫 profile 看装没装；启动后看心跳。
+   * 返回 mode 决策 + 给用户的提示信息。
+   */
+  checkRoute () {
+    const profileRoot = this.profileRoot
+    const detect = profileRoot ? detectWebplaterExtension(profileRoot) : null
+    const alive = this.server.isPluginAlive()
+
+    if (!detect || !detect.installed) {
+      this.info('[web] route=cdp (webplater not installed in profile)')
+      return {
+        mode: 'cdp',
+        installed: false,
+        disabled: false,
+        alive: false,
+        notice: {
+          level: 'warn',
+          message: '未检测到 WebPlater 插件，将使用 CDP 模式。对于淘宝/京东等高危平台，CDP 可能触发风控，建议安装 WebPlater 插件。'
+        }
+      }
+    }
+
+    if (detect.disabled) {
+      this.info('[web] route=cdp (webplater disabled in profile)')
+      return {
+        mode: 'cdp',
+        installed: true,
+        disabled: true,
+        alive: false,
+        notice: {
+          level: 'warn',
+          message: 'WebPlater 插件已安装但被禁用，将使用 CDP 模式。请在浏览器扩展页启用 WebPlater。'
+        }
+      }
+    }
+
+    if (!alive) {
+      this.info('[web] route=cdp (webplater installed but no heartbeat)')
+      return {
+        mode: 'cdp',
+        installed: true,
+        disabled: false,
+        alive: false,
+        notice: {
+          level: 'error',
+          message: 'WebPlater 插件已安装但未响应（心跳缺失）。请重装插件或检查浏览器是否已启动该 profile。'
+        }
+      }
+    }
+
+    this.info('[web] route=extension (webplater alive)')
+    return { mode: 'extension', installed: true, disabled: false, alive: true, notice: null }
+  }
+
+  // ── tab ──
+
+  listTabs () { return this.server.callPlugin('listTabs') }
+  switchTab (tabId) { return this.server.callPlugin('switchTab', { tabId }) }
+  reuseTab (url, urlMatch) { return this.server.callPlugin('reuseTab', { url: url || '', ...(urlMatch ? { urlMatch: urlMatch.source } : {}) }) }
+  closeTab (tabId) { return this.server.callPlugin('closeTab', { tabId }) }
+  newTab (url) { return this.server.callPlugin('newTab', { url: url || '' }) }
+
+  // ── 下载 (chrome.downloads API, 原生监听不轮询目录) ──
+  listDownloads (limit) { return this.server.callPlugin('listDownloads', { limit: limit || 20 }) }
+  getDownload (id) { return this.server.callPlugin('getDownload', { id }) }
+  waitForDownload (opts) { return this.server.callPlugin('waitForDownload', opts || {}) }
+
+  // ── 导航 ──
+
+  goto (url, tabId) { return this.server.callPlugin('goto', { url, tabId }) }
+  goBack (tabId) { return this.server.callPlugin('goBack', { tabId }) }
+  goForward (tabId) { return this.server.callPlugin('goForward', { tabId }) }
+  reload (tabId) { return this.server.callPlugin('reload', { tabId }) }
+  waitForLoadState (state, tabId) { return this.server.callPlugin('waitForLoadState', { state, tabId }) }
+  waitForURL (url, timeout, tabId) { return this.server.callPlugin('waitForURL', { url, timeout, tabId }) }
+
+  status (tabId) { return this.server.callPlugin('status', { tabId }) }
+
+  // ── 交互 ──
+
+  click (selector, x, y, tabId) { return this.server.callPlugin('click', { selector, x, y, tabId }) }
+  dblclick (selector, tabId) { return this.server.callPlugin('dblclick', { selector, tabId }) }
+  fill (selector, value, tabId) { return this.server.callPlugin('fill', { selector, value, tabId }) }
+  type (selector, value, delay, tabId) { return this.server.callPlugin('type', { selector, value, delay, tabId }) }
+  press (selector, key, tabId) { return this.server.callPlugin('press', { selector, key, tabId }) }
+  hover (selector, x, y, tabId) { return this.server.callPlugin('hover', { selector, x, y, tabId }) }
+  mouseMove (x, y, tabId) { return this.server.callPlugin('mouseMove', { x, y, tabId }) }
+  focus (selector, tabId) { return this.server.callPlugin('focus', { selector, tabId }) }
+  check (selector, tabId) { return this.server.callPlugin('check', { selector, tabId }) }
+  uncheck (selector, tabId) { return this.server.callPlugin('uncheck', { selector, tabId }) }
+  selectOption (selector, value, tabId) { return this.server.callPlugin('selectOption', { selector, value, tabId }) }
+  setInputFiles (selector, files, tabId) { return this.server.callPlugin('setInputFiles', { selector, files, tabId }) }
+  dragTo (source, target, tabId) { return this.server.callPlugin('dragTo', { source, target, tabId }) }
+
+  // ── 坐标/文本点击 + 用户视角定位 (扩展路=合成事件, 不走 CDP/debugger) ──
+  // clickAt: 坐标点击 (extension 路 content script 合成事件; CDP 路 page.mouse)
+  clickAt (x, y, opts, tabId) { return this.server.callPlugin('clickAt', { x, y, ...opts, tabId }) }
+  // locateVisibleText: 定位可见文本返回 bbox
+  locateVisibleText (text, exact, index, tabId) { return this.server.callPlugin('locateVisibleText', { text, exact, index, tabId }) }
+  // clickByText: 定位文本后立即点击 (content script 原子)
+  clickByText (p, tabId) { return this.server.callPlugin('clickByText', { ...p, tabId }) }
+  // operateSequence: 原子序列执行
+  operateSequence (steps, tabId) { return this.server.callPlugin('operateSequence', { steps, tabId }) }
+
+  // ── 等待 ──
+
+  waitForSelector (selector, timeout, tabId) { return this.server.callPlugin('waitForSelector', { selector, timeout, tabId }) }
+  waitForFunction (source, timeout, args, tabId) { return this.server.callPlugin('waitForFunction', { source, timeout, args, tabId }) }
+  waitForTimeout (ms, tabId) { return this.server.callPlugin('waitForTimeout', { ms, tabId }) }
+
+  // ── 读取 ──
+
+  evaluate (source, args, tabId, frameId) { return this.server.callPlugin('evaluate', { source, args, tabId, frameId }) }
+  listFrames (tabId) { return this.server.callPlugin('listFrames', { tabId }) }
+  innerHTML (selector, tabId) { return this.server.callPlugin('innerHTML', { selector, tabId }) }
+  innerText (selector, tabId) { return this.server.callPlugin('innerText', { selector, tabId }) }
+  textContent (selector, tabId) { return this.server.callPlugin('textContent', { selector, tabId }) }
+  getAttribute (selector, name, tabId) { return this.server.callPlugin('getAttribute', { selector, name, tabId }) }
+  inputValue (selector, tabId) { return this.server.callPlugin('inputValue', { selector, tabId }) }
+  boundingBox (selector, tabId) { return this.server.callPlugin('boundingBox', { selector, tabId }) }
+  count (selector, tabId) { return this.server.callPlugin('count', { selector, tabId }) }
+
+  snapshot (options, tabId) { return this.server.callPlugin('snapshot', { ...options, tabId }) }
+
+  // ── 存储 ──
+
+  getLocalStorage (keys, tabId) { return this.server.callPlugin('getLocalStorage', { keys, tabId }) }
+  setLocalStorage (items, tabId) { return this.server.callPlugin('setLocalStorage', { items, tabId }) }
+  removeLocalStorage (keys, tabId) { return this.server.callPlugin('removeLocalStorage', { keys, tabId }) }
+  clearLocalStorage (tabId) { return this.server.callPlugin('clearLocalStorage', { tabId }) }
+
+  // ── 截图 ──
+
+  screenshot (tabId) { return this.server.callPlugin('screenshot', { tabId }) }
+
+  // ── cookie ──
+
+  getCookies (filter) { return this.server.callPlugin('getCookies', filter || {}) }
+  setCookies (params) { return this.server.callPlugin('setCookies', params || { cookies: [] }) }
+  clearCookies (filter) { return this.server.callPlugin('clearCookies', filter || {}) }
+
+  // ── dialog ──
+
+  setDialogHandler (handlerSource, tabId) { return this.server.callPlugin('setDialogHandler', { handler: handlerSource, tabId }) }
+}
+
+module.exports = { WebService, BROWSER_PROFILES_DEFAULT }