mooncat-browser 0.1.0

package/browser-op/extension/state.cjs

@@ -0,0 +1,78 @@
+// -*- coding: utf-8 -*-
+//
+// lib/extension/state.cjs — 扩展路由专属运行时状态。
+//
+// 扩展路由不开远程调试端口, 跨进程复用靠两点:
+//   1. WS server 端口 (默认 17321) 是否被别的进程占用 (EADDRINUSE)
+//      → 被占 = 别的进程在管扩展路由, 本进程复用
+//   2. 本进程是否收到扩展心跳 (isPluginAlive)
+//      → 收到 = 本进程就是路由主人
+//
+// 文件位置: <userDataDir>/.extension-endpoint  (记录 WS 端口 + 最近心跳时间,
+//           便于诊断; 复用判据主要靠端口探测, 文件是辅助)
+
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const net = require('node:net')
+
+const STATE_FILENAME = '.extension-endpoint'
+const DEFAULT_WS_PORT = 17321
+
+function statePath (userDataDir) {
+  return path.join(userDataDir, STATE_FILENAME)
+}
+
+/** 读扩展状态。返回 { wsPort, lastHeartbeatAt, pid, updatedAt } 或 null。 */
+function read (userDataDir) {
+  try {
+    const p = statePath(userDataDir)
+    if (!fs.existsSync(p)) return null
+    return JSON.parse(fs.readFileSync(p, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** 写扩展状态 (WS server 起来后 / 收到心跳时调)。 */
+function write (userDataDir, info) {
+  try {
+    const p = statePath(userDataDir)
+    fs.mkdirSync(path.dirname(p), { recursive: true })
+    fs.writeFileSync(p, JSON.stringify({
+      wsPort: info.wsPort || DEFAULT_WS_PORT,
+      lastHeartbeatAt: info.lastHeartbeatAt || null,
+      pid: info.pid || process.pid,
+      updatedAt: Date.now()
+    }, null, 2))
+  } catch { /* ignore */ }
+}
+
+/** 清扩展状态 (close 后调)。 */
+function clear (userDataDir) {
+  try {
+    const p = statePath(userDataDir)
+    if (fs.existsSync(p)) fs.unlinkSync(p)
+  } catch { /* ignore */ }
+}
+
+/** 探测 WS 端口是否被占 (别的进程的 server 在听)。 */
+function isWsPortOccupied (port = DEFAULT_WS_PORT) {
+  return new Promise((resolve) => {
+    const tester = net.createServer()
+    tester.once('error', () => resolve(true))
+    tester.once('listening', () => tester.close(() => resolve(false)))
+    tester.listen(port, '127.0.0.1')
+  })
+}
+
+module.exports = {
+  STATE_FILENAME,
+  DEFAULT_WS_PORT,
+  statePath,
+  read,
+  write,
+  clear,
+  isWsPortOccupied
+}

package/browser-op/index.cjs

@@ -0,0 +1,389 @@
+// -*- coding: utf-8 -*-
+//
+// index.cjs — browser-op 双路由总入口。
+//
+// 复刻自 bee/packages/app/browser-op/main/browser-op-service.ts 的 open()/close() 决策逻辑，
+// 整合 launcher（CDP 启动）+ WebService（插件路）+ CaptureService（CDP 捕获）。
+//
+// 设计（与 bee 一致）：
+//   - open(routeMode) 统一入口：检测 profile 是否装了 webplater 插件
+//       装了且可用 → 插件模式（无 CDP 端口，WS 通信）mode=extension
+//       没装/禁用/不活  → CDP 模式（带调试端口）mode=cdp
+//   - 插件模式：所有 API 转发到扩展（callPlugin）
+//   - CDP 模式：本进程不实现页面操作 API（那需要 playwright），仅提供捕获能力（CaptureService）
+//               页面操作在 CDP 模式下请改用 playwright 直连 wsEndpoint
+//
+// 用法（node / bash）：
+//   const { BrowserOp } = require('./lib')
+//   const op = new BrowserOp({ executablePath, profileRoot, userDataDir })
+//   const { mode, port, wsEndpoint } = await op.open(undefined, { routeMode: 'auto' })
+//   if (mode === 'extension') {
+//     await op.fill('#q', 'hello', tabId)
+//   } else {
+//     // CDP 模式：用 playwright.connectOverCDP(wsEndpoint) 操作
+//   }
+//   await op.close()
+
+'use strict'
+
+const { CdpBrowserLauncher } = require('./cdp/chrome-launcher.cjs')
+const { ChromePathResolver } = require('./cdp/chrome-path.cjs')
+const { CaptureService } = require('./cdp/capture-service.cjs')
+const { WebService } = require('./extension/service.cjs')
+const { detectWebplaterExtension } = require('./extension/extension-detect.cjs')
+const { captureInjectJS } = require('./cdp/capture-inject.js')
+const globalState = require('./state.cjs')
+const cdpState = require('./cdp/state.cjs')
+const extState = require('./extension/state.cjs')
+
+function defaultInfo () {
+  if (process.env.BROWSER_OP_DEBUG) console.error.apply(console, ['[browser-op]'].concat(Array.from(arguments)))
+}
+function defaultError () {
+  console.error.apply(console, ['[browser-op][error]'].concat(Array.from(arguments)))
+}
+
+class BrowserOp {
+  /**
+   * @param {Object} deps
+   * @param {string} deps.executablePath  Chrome 路径（必填）
+   * @param {string} deps.profileRoot     profile 根目录（检测插件用，可选）
+   * @param {string=} deps.userDataDir    显式 userDataDir（不传则 launcher 用 profileRoot/default）
+   * @param {Function=} deps.info         日志函数
+   * @param {Function=} deps.errorLog     错误日志函数
+   */
+  constructor (deps) {
+    if (!deps || !deps.executablePath) {
+      throw new Error('BrowserOp: deps.executablePath is required (Chrome path)')
+    }
+    this.executablePath = deps.executablePath
+    this.profileRoot = deps.profileRoot || null
+    this.userDataDirOverride = deps.userDataDir || null
+    this.info = deps.info || defaultInfo
+    this.errorLog = deps.errorLog || defaultError
+
+    this.launcher = new CdpBrowserLauncher()
+    this.web = new WebService({
+      info: this.info,
+      errorLog: this.errorLog,
+      profileRoot: this.profileRoot
+    })
+    /** CDP 链路捕获服务。插件链路不用它，走 web.enableCapture/disableCapture */
+    this.captureService = new CaptureService()
+
+    this.currentMode = null // 'extension' | 'cdp'
+    this.currentPort = null
+    this.currentWsEndpoint = null
+    this._serverStarted = false
+  }
+
+  /**
+   * 统一启动入口（双路由唯一正确启动方式）。
+   *
+   * 检测 profile 是否装了 webplater 插件：
+   *   装了 → 启动 Chrome（无 CDP 端口，纯插件通信），ping 心跳
+   *           alive  → mode=extension
+   *           不alive → mode=extension + notice（心跳缺失）
+   *   没装 → 启动 Chrome（带 CDP 端口）→ mode=cdp + notice（建议装插件）
+   *
+   * @param {string=} url   打开后导航到的 URL（可选，导航在连接后做）
+   * @param {Object=} options
+   * @param {'auto'|'extension'|'cdp'} options.routeMode  默认 'auto'
+   * @param {number=} options.preferPort                CDP 模式优先端口
+   * @param {boolean=} options.headless                 CDP 模式 headless（插件模式忽略）
+   * @param {(connected:boolean, port?:number)=>void=} options.onStatus
+   * @returns {Promise<{ok:boolean, mode:'extension'|'cdp', port?:number, wsEndpoint?:string, pid?:number, notice?:Object|null, error?:string}>}
+   */
+  async open (url, options = {}) {
+    const routeMode = options.routeMode || 'auto'
+    const userDataDir = this.userDataDirOverride || this.launcher.getUserDataDir(this.profileRoot || '', 'default')
+
+    // routeMode=auto 才检测；extension/cdp 强制走对应通道
+    // 注意: 传 userDataDir (profiles/default), 不是 profileRoot (profiles/)。
+    // 扩展在 user-data-dir/Default/Secure Preferences 下。
+    const detect = routeMode === 'auto' && userDataDir
+      ? detectWebplaterExtension(userDataDir)
+      : null
+    const forceCdp = routeMode === 'cdp'
+    let tryPlugin = routeMode === 'extension' || (routeMode === 'auto' && detect && detect.installed && !detect.disabled)
+    let pluginFallbackNotice = null
+
+    // 启动前：开插件 WS server（插件链路需要；CDP 链路开起来也不碍事，便于 checkRoute）
+    // startServer 现在 EADDRINUSE 会 reject: 17321 被占 = 已有 browserd 在管插件
+    if (!this._serverStarted) {
+      try {
+        await this.web.startServer()
+        this._serverStarted = true
+      } catch (e) {
+        const portBusy = /EADDRINUSE|already in use/.test(e.message)
+        const message = portBusy
+          ? 'WebPlater WS 端口 17321 已被占用（另一个 browserd 正在管理插件，或残留进程）。'
+          : `WS server 启动失败: ${e.message}`
+        if (routeMode === 'extension') {
+          return { ok: false, mode: 'extension', notice: { level: 'error', message }, error: message }
+        }
+        // auto/CDP: 端口被占不影响 CDP 路, 继续 (不开 server, 后面走 CDP)
+        pluginFallbackNotice = { level: portBusy ? 'warn' : 'error', message }
+        tryPlugin = false
+      }
+    }
+
+    // 进程内已运行 → 复用，返回当前 mode
+    if (this.launcher.isRunning && this.launcher.currentResult) {
+      const mode = forceCdp
+        ? 'cdp'
+        : routeMode === 'extension'
+          ? 'extension'
+          : (this.web.isPluginAlive() ? 'extension' : 'cdp')
+      this.currentMode = mode
+      return { ok: true, mode, pid: this.launcher.processId, notice: null }
+    }
+
+    // CDP 路由跨进程复用检测: 读 .cdp-endpoint 拿 wsEndpoint, 端口活着就连。
+    // (扩展路由复用检测已在 startServer 前完成)
+    if (!tryPlugin) {
+      const probe = await cdpState.probe(userDataDir)
+      if (probe.active) {
+        this.info('cdp profile already in use via %s (port=%s) — reusing',
+          probe.via, probe.port || 'n/a')
+        this.currentMode = 'cdp'
+        this.currentPort = probe.port
+        this.currentWsEndpoint = probe.wsEndpoint
+        return {
+          ok: true, mode: 'cdp',
+          port: probe.port, wsEndpoint: probe.wsEndpoint,
+          notice: { level: 'info', message: `检测到该 profile 的 Chrome 已由其他进程启动，已复用，未重复启动。` }
+        }
+      }
+    }
+
+    // tryPlugin=true → 插件模式启动（无端口）
+    if (tryPlugin) {
+      // ★ 扩展路 handshake-first: startServer 后先等已有 Chrome 的 offscreen 回连 (2s)。
+      // 已有 Chrome 开着 (别的进程起的/上次没关干净) → offscreen 自动重连当前 17321 → 复用, 不 launch。
+      // 没回连 → Chrome 没开或坏了 → 才 launch。
+      const reused = await this.waitForPluginHeartbeat(2000)
+      if (reused) {
+        this.info('open mode=extension (reused: plugin already connected, skip launch)')
+        this.currentMode = 'extension'
+        extState.write(userDataDir, { wsPort: extState.DEFAULT_WS_PORT, lastHeartbeatAt: Date.now() })
+        globalState.writeGlobal(userDataDir, { profile: 'default' })
+        return { ok: true, mode: 'extension', notice: { level: 'info', message: '检测到该 profile 的 Chrome 已开且插件已连接，复用，未重复启动。' } }
+      }
+
+      // 没回连 → Chrome 没开, 正常 launch
+      const result = await this.launcher.launch({
+        executablePath: this.executablePath,
+        userDataDir,
+        url,
+        enableCdpPort: false
+      })
+      if (!result.ok) {
+        this.errorLog('plugin-mode launch failed: %s', result.error)
+        // launch 失败也要清理本次 server 占用的端口
+        await this.web.stopServer().catch(() => {})
+        this._serverStarted = false
+        return { ok: false, mode: 'extension', notice: null, error: result.error }
+      }
+      // 启动响应后等 offscreen hello (offscreen + extension cold start 不稳定, 用 15s)
+      const alive = await this.waitForPluginHeartbeat(15000)
+      if (options.onStatus) options.onStatus(alive, undefined)
+      if (alive) {
+        this.info('open mode=extension (plugin alive)')
+        this.currentMode = 'extension'
+        extState.write(userDataDir, { wsPort: extState.DEFAULT_WS_PORT, lastHeartbeatAt: Date.now() })
+        globalState.writeGlobal(userDataDir, { profile: 'default' })
+        return { ok: true, mode: 'extension', pid: this.launcher.processId, notice: null }
+      }
+      // 装了但 hello 没来: 必须清理本次启动 (Chrome + server)
+      const message =
+        `WebPlater 插件已安装但未响应（启动后 15s 内无 hello）。` +
+        `本进程不能使用 extension 通道。` +
+        (detect ? `当前 profile：${detect.profileDir || userDataDir}，扩展 id：${detect.extensionId || '未知'}。` : '')
+      this.errorLog('%s', message)
+      await this.launcher.stop().catch(() => {})
+      await this.web.stopServer().catch(() => {})
+      this._serverStarted = false
+      this.currentMode = null
+      if (routeMode === 'extension') {
+        return { ok: false, mode: 'extension', notice: { level: 'error', message }, error: message }
+      }
+      pluginFallbackNotice = { level: 'error', message }
+      tryPlugin = false
+    }
+
+    // 没装 / 被禁用 → CDP 模式启动（带端口）
+    const preferPort = options.preferPort && options.preferPort > 0 ? options.preferPort : undefined
+    const result = await this.launcher.launch({
+      executablePath: this.executablePath,
+      userDataDir,
+      url,
+      enableCdpPort: true,
+      preferPort,
+      headless: options.headless
+    })
+    if (!result.ok) {
+      this.errorLog('cdp-mode launch failed: %s', result.error)
+      return { ok: false, mode: 'cdp', notice: null, error: result.error }
+    }
+    if (options.onStatus) options.onStatus(true, result.port)
+
+    const notice = pluginFallbackNotice ||
+      (forceCdp
+        ? null
+        : detect && detect.disabled
+          ? { level: 'warn', message: 'WebPlater 插件已安装但被禁用，当前使用 CDP 模式。请在浏览器扩展页启用 WebPlater 以使用插件模式（对高危平台更安全）。' }
+          : { level: 'warn', message: '未检测到 WebPlater 插件，当前使用 CDP 模式。对于淘宝/京东等高危平台，CDP（--remote-debugging-port）可能触发风控，建议安装 WebPlater 插件以使用插件模式。' })
+    this.info('open mode=cdp (forceCdp=%s)', forceCdp)
+
+    this.currentMode = 'cdp'
+    this.currentPort = result.port
+    this.currentWsEndpoint = result.wsEndpoint
+    // 写状态: 供其他进程 connectOverCDP 复用
+    cdpState.write(userDataDir, { wsEndpoint: result.wsEndpoint, port: result.port, pid: this.launcher.processId })
+    globalState.writeGlobal(userDataDir, { profile: 'default' })
+    return { ok: true, mode: 'cdp', port: result.port, wsEndpoint: result.wsEndpoint, pid: this.launcher.processId, notice }
+  }
+
+  /**
+   * 关闭浏览器 + 停止 WS server。
+   * 先关 CDP 捕获服务（若开了），再关 Chrome 进程，最后停 server。
+   */
+  async close () {
+    try { await this.captureService.disable() } catch {}
+    // 清理状态文件 (本进程是路由主人时才清)
+    const ud = this.userDataDirOverride || this.launcher.getUserDataDir(this.profileRoot || '', 'default')
+    try { cdpState.clear(ud) } catch {}
+    try { extState.clear(ud) } catch {}
+    try { globalState.clearGlobal(ud) } catch {}
+    this.currentMode = null
+    this.currentPort = null
+    this.currentWsEndpoint = null
+    await this.launcher.stop()
+    if (this._serverStarted) {
+      await this.web.stopServer()
+      this._serverStarted = false
+    }
+  }
+
+  /**
+   * 等插件心跳到达（最多 timeoutMs）。插件模式启动后 WS 需时间连上。
+   */
+  async waitForPluginHeartbeat (timeoutMs = 8000) {
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      if (this.web.isPluginAlive()) return true
+      await new Promise((r) => setTimeout(r, 300))
+    }
+    return this.web.isPluginAlive()
+  }
+
+  // ── CDP 链路：捕获模式 ──
+
+  /** 开启 CDP 链路捕获（向所有 page 注入 captureInjectJS）。仅 mode=cdp 时有意义。 */
+  async enableCapture () {
+    if (this.currentMode !== 'cdp' || !this.currentPort) {
+      throw new Error('enableCapture (CDP) requires mode=cdp; current mode=' + this.currentMode)
+    }
+    return this.captureService.enable(this.currentPort)
+  }
+
+  /** 关闭 CDP 链路捕获。 */
+  async disableCapture () {
+    return this.captureService.disable()
+  }
+
+  // ── 插件链路 API 转发 ──
+  //
+  // 以下全部转发到 WebService（callPlugin）。
+  // 仅 mode=extension 时有意义；mode=cdp 下调用会因 "Plugin not connected" 抛错。
+
+  get isConnected () { return this.web.isConnected }
+  isPluginAlive (thresholdMs) { return this.web.isPluginAlive(thresholdMs) }
+  checkRoute () { return this.web.checkRoute() }
+
+  listTabs () { return this.web.listTabs() }
+  switchTab (tabId) { return this.web.switchTab(tabId) }
+  reuseTab (url, urlMatch) { return this.web.reuseTab(url, urlMatch) }
+  closeTab (tabId) { return this.web.closeTab(tabId) }
+  newTab (url) { return this.web.newTab(url) }
+
+  // ── 下载 (chrome.downloads API, 原生监听不轮询目录) ──
+  listDownloads (limit) { return this.web.listDownloads(limit) }
+  getDownload (id) { return this.web.getDownload(id) }
+  waitForDownload (opts) { return this.web.waitForDownload(opts) }
+
+  goto (url, tabId) { return this.web.goto(url, tabId) }
+  goBack (tabId) { return this.web.goBack(tabId) }
+  goForward (tabId) { return this.web.goForward(tabId) }
+  reload (tabId) { return this.web.reload(tabId) }
+  waitForLoadState (state, tabId) { return this.web.waitForLoadState(state, tabId) }
+  waitForURL (url, timeout, tabId) { return this.web.waitForURL(url, timeout, tabId) }
+  status (tabId) { return this.web.status(tabId) }
+
+  click (selector, x, y, tabId) { return this.web.click(selector, x, y, tabId) }
+  dblclick (selector, tabId) { return this.web.dblclick(selector, tabId) }
+  fill (selector, value, tabId) { return this.web.fill(selector, value, tabId) }
+  type (selector, value, delay, tabId) { return this.web.type(selector, value, delay, tabId) }
+  press (selector, key, tabId) { return this.web.press(selector, key, tabId) }
+  hover (selector, x, y, tabId) { return this.web.hover(selector, x, y, tabId) }
+  mouseMove (x, y, tabId) { return this.web.mouseMove(x, y, tabId) }
+  focus (selector, tabId) { return this.web.focus(selector, tabId) }
+  check (selector, tabId) { return this.web.check(selector, tabId) }
+  uncheck (selector, tabId) { return this.web.uncheck(selector, tabId) }
+  selectOption (selector, value, tabId) { return this.web.selectOption(selector, value, tabId) }
+  setInputFiles (selector, files, tabId) { return this.web.setInputFiles(selector, files, tabId) }
+  dragTo (source, target, tabId) { return this.web.dragTo(source, target, tabId) }
+
+  // 坐标/文本点击 + 用户视角定位 (扩展路=合成事件, 不走 CDP/debugger)
+  clickAt (x, y, opts, tabId) { return this.web.clickAt(x, y, opts || {}, tabId) }
+  locateVisibleText (text, exact, index, tabId) { return this.web.locateVisibleText(text, exact, index, tabId) }
+  clickByText (p, tabId) { return this.web.clickByText(p || {}, tabId) }
+  operateSequence (steps, tabId) { return this.web.operateSequence(steps || [], tabId) }
+
+  waitForSelector (selector, timeout, tabId) { return this.web.waitForSelector(selector, timeout, tabId) }
+  waitForFunction (source, timeout, args, tabId) { return this.web.waitForFunction(source, timeout, args, tabId) }
+  waitForTimeout (ms, tabId) { return this.web.waitForTimeout(ms, tabId) }
+
+  // evaluate: frameId 透传给扩展路 (WebService.evaluate 第 4 参), 用于 eval 进指定 iframe (如登录框)
+  evaluate (source, args, tabId, frameId) { return this.web.evaluate(source, args, tabId, frameId) }
+  // listFrames: 枚举当前 tab 的所有 frame (含 iframe), 返回 [{frameId, url, parentFrameId}]
+  listFrames (tabId) { return this.web.listFrames(tabId) }
+  innerHTML (selector, tabId) { return this.web.innerHTML(selector, tabId) }
+  innerText (selector, tabId) { return this.web.innerText(selector, tabId) }
+  textContent (selector, tabId) { return this.web.textContent(selector, tabId) }
+  getAttribute (selector, name, tabId) { return this.web.getAttribute(selector, name, tabId) }
+  inputValue (selector, tabId) { return this.web.inputValue(selector, tabId) }
+  boundingBox (selector, tabId) { return this.web.boundingBox(selector, tabId) }
+  count (selector, tabId) { return this.web.count(selector, tabId) }
+  snapshot (options, tabId) { return this.web.snapshot(options, tabId) }
+
+  getLocalStorage (keys, tabId) { return this.web.getLocalStorage(keys, tabId) }
+  setLocalStorage (items, tabId) { return this.web.setLocalStorage(items, tabId) }
+  removeLocalStorage (keys, tabId) { return this.web.removeLocalStorage(keys, tabId) }
+  clearLocalStorage (tabId) { return this.web.clearLocalStorage(tabId) }
+
+  screenshot (tabId) { return this.web.screenshot(tabId) }
+
+  getCookies (filter) { return this.web.getCookies(filter) }
+  setCookies (cookies) { return this.web.setCookies(cookies) }
+  clearCookies (filter) { return this.web.clearCookies(filter) }
+
+  setDialogHandler (handlerSource, tabId) { return this.web.setDialogHandler(handlerSource, tabId) }
+
+  /** 插件链路捕获：把 captureInjectJS 字符串下发给插件 */
+  enablePluginCapture (script) { return this.web.enableCapture(script || captureInjectJS) }
+  disablePluginCapture () { return this.web.disableCapture() }
+}
+
+module.exports = {
+  BrowserOp,
+  ChromePathResolver,
+  CdpBrowserLauncher,
+  WebService,
+  CaptureService,
+  detectWebplaterExtension,
+  WEBPLATER_EXTENSION_ID: 'npkapgkjeaaipldb',
+  WEBPLATER_EXTENSION_NAME: 'WebPlater',
+  captureInjectJS
+}

package/browser-op/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "browser-op",
+  "version": "0.1.0",
+  "description": "Dual-route (CDP + WebPlater extension) browser automation. Ports bee/packages/app/browser-op.",
+  "main": "index.cjs",
+  "type": "commonjs",
+  "bin": {
+    "browser-op": "index.cjs"
+  },
+  "dependencies": {
+    "cheerio": "^1.2.0",
+    "playwright-core": "^1.61.0",
+    "turndown": "^7.2.4",
+    "ws": "^8.21.0"
+  },
+  "_comment_runtime_deps": "这些依赖由上层 @mooncat/browser 的 package.json dependencies 安装到包根 node_modules；browserd.cjs 的 require 从此处向上解析。playwright-core 用于 connectOverCDP 连接宿主 Chrome，不下载自带浏览器。"
+}

package/browser-op/py/behavior.py

@@ -0,0 +1,138 @@
+"""web/behavior — 人类行为模拟 (路由无关, 全走 operate).
+
+忠实复刻 lib/web/behavior.js。
+贝塞尔鼠标轨迹 / 随机点击偏移 / 打字节奏 / 平滑滚动。
+所有页面动作统一走 operate(pageHandle, {action})，本模块只编排动作序列。
+
+依赖: browser (operate)
+"""
+from __future__ import annotations
+import math
+import random
+import time
+from typing import Any
+
+import sys
+sys.path.insert(0, __file__.rsplit("\\", 1)[0] if "\\" in __file__ else __file__.rsplit("/", 1)[0])
+from browser import operate  # noqa: E402
+
+
+def _bezier(p0: float, p1: float, p2: float, p3: float, t: float) -> float:
+    u = 1 - t
+    return u * u * u * p0 + 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t * p3
+
+
+def _trajectory(from_pt: dict, to_pt: dict, steps: int) -> list[dict]:
+    """生成贝塞尔轨迹点 (含随机抖动)."""
+    pts = []
+    mx = (from_pt["x"] + to_pt["x"]) / 2 + (random.random() - 0.5) * abs(to_pt["x"] - from_pt["x"]) * 0.6
+    my = (from_pt["y"] + to_pt["y"]) / 2 + (random.random() - 0.5) * abs(to_pt["y"] - from_pt["y"]) * 0.6
+    c1 = {"x": from_pt["x"] + (mx - from_pt["x"]) * 0.3, "y": from_pt["y"] + (my - from_pt["y"]) * 0.3}
+    c2 = {"x": to_pt["x"] + (mx - to_pt["x"]) * 0.3, "y": to_pt["y"] + (my - to_pt["y"]) * 0.3}
+    for i in range(steps + 1):
+        t = i / steps
+        pts.append({
+            "x": _bezier(from_pt["x"], c1["x"], c2["x"], to_pt["x"], t) + (random.random() - 0.5) * 2,
+            "y": _bezier(from_pt["y"], c1["y"], c2["y"], to_pt["y"], t) + (random.random() - 0.5) * 2,
+        })
+    return pts
+
+
+def _random_point_in_rect(rect: dict) -> dict:
+    return {
+        "x": rect["x"] + rect["width"] * (0.3 + random.random() * 0.4),
+        "y": rect["y"] + rect["height"] * (0.3 + random.random() * 0.4),
+    }
+
+
+def _move_trajectory(page_handle: dict, from_pt: dict, to_pt: dict) -> None:
+    """沿贝塞尔轨迹多点 mouseMove 注入."""
+    pts = _trajectory(from_pt, to_pt, 10 + random.randint(0, 5))
+    for pt in pts:
+        operate(page_handle, {"action": "mouseMove", "x": pt["x"], "y": pt["y"]})
+        time.sleep(0.008 + random.random() * 0.016)
+
+
+def create_behavior(page_handle: dict) -> dict:
+    """创建绑定到 pageHandle 的行为模拟器.
+
+    返回: move_to, click, click_element, type_text, type_in_element, scroll_down, scroll_to_bottom, scroll_to_element
+    """
+    if not page_handle:
+        raise ValueError("create_behavior: page_handle required")
+    last_pos = {"x": 100, "y": 100}
+
+    def move_to(x: float, y: float) -> None:
+        nonlocal last_pos
+        _move_trajectory(page_handle, last_pos, {"x": x, "y": y})
+        last_pos = {"x": x, "y": y}
+
+    def click(x: float, y: float, options: dict | None = None) -> None:
+        nonlocal last_pos
+        _move_trajectory(page_handle, last_pos, {"x": x, "y": y})
+        last_pos = {"x": x, "y": y}
+        time.sleep(0.05 + random.random() * 0.1)
+        operate(page_handle, {"action": "click", "x": x, "y": y})
+        delay = (options or {}).get("delay", 0.05 + random.random() * 0.1)
+        time.sleep(delay)
+
+    def click_element(selector: str, timeout: int = 10000) -> None:
+        nonlocal last_pos
+        operate(page_handle, {"action": "waitForSelector", "selector": selector, "timeout": timeout})
+        box_r = operate(page_handle, {"action": "boundingBox", "selector": selector})
+        box = None
+        if isinstance(box_r, dict) and box_r.get("width") is not None:
+            box = box_r
+        if not box:
+            operate(page_handle, {"action": "click", "selector": selector})
+            time.sleep(0.05 + random.random() * 0.1)
+            return
+        pt = _random_point_in_rect(box)
+        move_to(pt["x"], pt["y"])
+        time.sleep(0.05 + random.random() * 0.1)
+        operate(page_handle, {"action": "click", "x": pt["x"], "y": pt["y"]})
+        time.sleep(0.05 + random.random() * 0.1)
+
+    def type_text(text: str, delay: float = 0.1) -> None:
+        for ch in text:
+            operate(page_handle, {"action": "press", "selector": "body", "key": ch})
+            d = delay * (0.5 + random.random())
+            if random.random() < 0.1:
+                d += 0.2 + random.random() * 0.4
+            time.sleep(d)
+
+    def type_in_element(selector: str, text: str, options: dict | None = None) -> None:
+        opts = options or {}
+        delay = opts.get("delay", 0.1)
+        timeout = opts.get("timeout", 10000)
+        operate(page_handle, {"action": "waitForSelector", "selector": selector, "timeout": timeout})
+        operate(page_handle, {"action": "click", "selector": selector})
+        operate(page_handle, {"action": "type", "selector": selector, "value": text, "delay": delay})
+
+    def scroll_down(pixels: int = 400) -> None:
+        step = 30 + random.randint(0, 29)
+        operate(page_handle, {
+            "action": "evaluate",
+            "source": f"(p) => new Promise((r) => {{ let done = 0; const t = setInterval(() => {{ window.scrollBy(0, {step}); done += {step}; if (done >= p) {{ clearInterval(t); r() }} }}, 30 + Math.random() * 30) }})",
+            "args": pixels
+        })
+
+    def scroll_to_bottom() -> None:
+        operate(page_handle, {
+            "action": "evaluate",
+            "source": "() => new Promise((resolve) => { let last=-1; const t=setInterval(()=>{ window.scrollBy(0,100+Math.random()*100); const h=document.body.scrollHeight; if(h===last){clearInterval(t);resolve()} last=h }, 150) })"
+        })
+
+    def scroll_to_element(selector: str, timeout: int = 10000) -> None:
+        operate(page_handle, {
+            "action": "evaluate",
+            "source": f'(s) => {{ const el = document.querySelector(s); if (el) el.scrollIntoView({{ behavior: "smooth", block: "center" }}) }}',
+            "args": selector
+        })
+
+    return {
+        "move_to": move_to, "click": click, "click_element": click_element,
+        "type_text": type_text, "type_in_element": type_in_element,
+        "scroll_down": scroll_down, "scroll_to_bottom": scroll_to_bottom,
+        "scroll_to_element": scroll_to_element,
+    }