@pyrokine/mcp-chrome 1.7.0 → 2.0.0

package/dist/core/unified-session.js

@@ -6,7 +6,8 @@
  * 2. CDP 模式：通过 Chrome DevTools Protocol 操作（Fallback）
  */
 import { ExtensionBridge } from '../extension/index.js';
-import { getSession as getCdpSession } from './session.js';
+import { isExtensionDisconnected } from './extension-errors.js';
+import { getKeyDefinition, getSession as getCdpSession } from './session.js';
 import { extractCdpValue, formatCdpException, MODIFIER_KEYS } from './types.js';
 class UnifiedSessionManager {
     static instance;
@@ -16,12 +17,13 @@ class UnifiedSessionManager {
     currentMousePosition = { x: 0, y: 0 }; // 跟踪鼠标位置
     /** 当前按下的修饰键位掩码 */
     modifiers = 0;
+    /** 当前按下的所有键（用于 Puppeteer 风格的 rawKeyDown/autoRepeat 长按重复） */
+    pressedKeys = new Set();
     lastConnectionFailure = 0;
     tabSwitchLock = Promise.resolve(); // 串行化 tab 切换，防止并发竞态
     requireExtension = false; // 指定 tabId 或 frame 时为 true，禁止 CDP 回退
     currentFrameOffset = null; // iframe 在主页面的偏移量（withFrame 期间有效）
-    constructor() {
-    }
+    constructor() { }
     static getInstance() {
         if (!UnifiedSessionManager.instance) {
             UnifiedSessionManager.instance = new UnifiedSessionManager();
@@ -103,15 +105,15 @@ class UnifiedSessionManager {
     async launch(options = {}) {
         // 优先检查 Extension 是否已连接，如果断开则等待重连（受 timeout 约束）
         if (await this.ensureExtensionConnected(options.timeout)) {
-            // createTab 会设置 currentTabId，需要加锁
-            const tab = await this.withTabLock(async () => {
-                return this.extensionBridge.createTab(undefined, options.timeout);
+            // newPage 会设置 currentTabId，需要加锁
+            const result = await this.withTabLock(async () => {
+                return this.extensionBridge.newPage(undefined, options.timeout);
             });
             return {
-                targetId: String(tab.id),
-                type: 'page',
-                url: tab.url,
-                title: tab.title,
+                targetId: result.targetId,
+                type: result.type ?? 'page',
+                url: result.url,
+                title: result.title,
                 mode: 'extension',
             };
         }
@@ -126,131 +128,68 @@ class UnifiedSessionManager {
      * 列出所有页面
      */
     async listTargets() {
-        // 优先使用 Extension，如果断开则等待重连
-        if (await this.ensureExtensionConnected()) {
-            const tabs = await this.extensionBridge.listTabs();
-            const currentTabId = this.extensionBridge.getCurrentTabId();
-            return tabs.map(tab => ({
-                targetId: String(tab.id),
-                type: 'page',
-                url: tab.url,
-                title: tab.title,
-                mode: 'extension',
-                managed: tab.managed,
-                isActive: tab.id === currentTabId,
-                windowId: tab.windowId,
-                index: tab.index,
-                pinned: tab.pinned,
-                incognito: tab.incognito,
-                status: tab.status,
-            }));
-        }
-        if (getCdpSession().isConnected()) {
-            const targets = await getCdpSession().listTargets();
-            const currentTargetId = getCdpSession().getState()?.targetId;
-            return targets.map(t => ({
-                ...t,
-                mode: 'cdp',
-                isActive: t.targetId === currentTargetId,
-            }));
-        }
-        return [];
+        const mode = this.getMode();
+        if (mode === 'none') {
+            return [];
+        }
+        const driver = await this.getDriver();
+        const targets = await driver.listTargets();
+        return targets.map((t) => ({
+            targetId: t.targetId ?? String(t.id),
+            type: t.type ?? 'page',
+            url: t.url,
+            title: t.title,
+            mode,
+            isActive: t.active ?? false,
+            managed: t.managed,
+            windowId: t.windowId,
+            index: t.index,
+            pinned: t.pinned,
+            incognito: t.incognito,
+            status: t.status,
+        }));
     }
     /**
      * 导航到 URL
      */
     async navigate(url, options = {}) {
-        if (await this.ensureExtensionConnected(options.timeout)) {
-            // 加锁保护 currentTabId，防止并发 withTabId 将命令路由到临时切换的 tab
-            await this.withTabLock(async () => {
-                await this.extensionBridge.navigate(url, {
-                    waitUntil: options.wait,
-                    timeout: options.timeout,
-                });
-            });
-            return;
-        }
-        await getCdpSession().navigate(url, options);
+        const driver = await this.getDriver(options.timeout);
+        await this.withTabLock(() => driver.navigate(url, { wait: options.wait, timeout: options.timeout }));
     }
-    /**
-     * 后退
-     */
     async goBack(timeout) {
-        if (await this.ensureExtensionConnected(timeout)) {
-            return this.withTabLock(async () => {
-                const result = await this.extensionBridge.goBack(timeout);
-                return { navigated: result.navigated };
-            });
-        }
-        return getCdpSession().goBack(timeout);
+        const driver = await this.getDriver(timeout);
+        const result = await this.withTabLock(() => driver.goBack(timeout));
+        return { navigated: result.navigated };
     }
-    /**
-     * 前进
-     */
     async goForward(timeout) {
-        if (await this.ensureExtensionConnected(timeout)) {
-            return this.withTabLock(async () => {
-                const result = await this.extensionBridge.goForward(timeout);
-                return { navigated: result.navigated };
-            });
-        }
-        return getCdpSession().goForward(timeout);
+        const driver = await this.getDriver(timeout);
+        const result = await this.withTabLock(() => driver.goForward(timeout));
+        return { navigated: result.navigated };
     }
-    /**
-     * 刷新
-     */
     async reload(options = {}) {
-        if (await this.ensureExtensionConnected(options.timeout)) {
-            await this.withTabLock(async () => {
-                await this.extensionBridge.reload(options.ignoreCache, options.waitUntil, options.timeout);
-            });
-            return;
-        }
-        await getCdpSession().reload(options);
+        const driver = await this.getDriver(options.timeout);
+        await this.withTabLock(() => driver.reload(options.ignoreCache, options.waitUntil, options.timeout));
     }
     /**
      * 读取页面（Accessibility Tree）
      */
     async readPage(options) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.readPage(options);
-        }
-        // CDP 模式使用 getPageState
-        const state = await getCdpSession().getPageState();
-        const elements = state.elements || [];
-        // 构建简单的文本表示
-        const lines = elements.map(e => {
-            let line = e.role;
-            if (e.name) {
-                line += ` "${e.name}"`;
-            }
-            return line;
-        });
-        return {
-            pageContent: lines.join('\n'),
-            viewport: state.viewport,
-        };
+        const driver = await this.getDriver();
+        return driver.readPage(options);
     }
     /**
      * 截图
      */
     async screenshot(options) {
-        if (await this.ensureExtensionConnected()) {
-            const result = await this.extensionBridge.screenshot(options);
-            return result.data;
-        }
-        return getCdpSession().screenshot(options?.fullPage, options?.scale, options?.format, options?.quality, options?.clip);
+        const result = await (await this.getDriver()).screenshot(options);
+        return result.data;
     }
     /**
      * 点击元素
      */
     async click(refId) {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.click(refId);
-            return;
-        }
-        // CDP 模式需要通过 Locator
-        throw new Error('CDP 模式下请使用 input 工具的 click action');
+        const driver = await this.getDriver();
+        await driver.click(refId);
     }
     /**
      * 带 actionability 检查的点击（Extension 模式）
@@ -258,57 +197,43 @@ class UnifiedSessionManager {
      * 返回结构化结果，让调用方知道操作是否真正生效
      */
     async actionableClick(refId, force) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.actionableClick(refId, force);
-        }
-        throw new Error('actionableClick 仅支持 Extension 模式');
+        const driver = await this.getDriver();
+        return driver.actionableClick(refId, force);
     }
     /**
-     * 检查元素可操作性（Extension 模式）
+     * dispatch 模式输入（ISOLATED 世界，兼容 React/Vue 受控组件）
      */
-    async checkActionability(refId) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.checkActionability(refId);
-        }
-        throw new Error('checkActionability 仅支持 Extension 模式');
+    async dispatchInput(refId, text) {
+        const driver = await this.getDriver();
+        return driver.dispatchInput(refId, text);
     }
     /**
-     * dispatch 模式输入（ISOLATED 世界，兼容 React/Vue 受控组件）
+     * HTML5 drag/drop（ISOLATED 世界，通过 refId 访问 __mcpElementMap 中的元素引用）
      */
-    async dispatchInput(refId, text) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.dispatchInput(refId, text);
-        }
-        throw new Error('dispatchInput 仅支持 Extension 模式');
+    async dragAndDrop(srcRefId, dstRefId) {
+        const driver = await this.getDriver();
+        return driver.dragAndDrop(srcRefId, dstRefId);
     }
     /**
      * 获取元素 computed style（ISOLATED 世界）
      */
     async getComputedStyle(refId, prop) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.getComputedStyle(refId, prop);
-        }
-        throw new Error('getComputedStyle 仅支持 Extension 模式');
+        const driver = await this.getDriver();
+        return driver.getComputedStyle(refId, prop);
     }
     /**
      * 输入文本
      */
     async type(refId, text, clear = false) {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.type(refId, text, clear);
-            return;
-        }
-        throw new Error('CDP 模式下请使用 input 工具');
+        const driver = await this.getDriver();
+        await driver.typeRef(refId, text, clear);
     }
     /**
      * 滚动
      */
     async scroll(x, y, refId) {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.scroll(x, y, refId);
-            return;
-        }
-        await getCdpSession().mouseWheel(x, y);
+        const driver = await this.getDriver();
+        await driver.scrollAt(x, y, refId);
     }
     /**
      * 执行 JavaScript
@@ -320,8 +245,8 @@ class UnifiedSessionManager {
      * stealth 模式：使用 chrome.scripting.executeScript（受 CSP 限制）
      * precise 模式：使用 debugger API Runtime.evaluate（可绕过 CSP）
      *
-     * 使用 args 时 script 必须是函数表达式，如 "(x) => x + 1"。
-     * precise 模式通过 callFunctionOn 传递参数（支持大 payload），stealth 模式仍用字符串拼接。
+     * 使用 args 时 script 必须是函数表达式，如 "(x) => x + 1"，
+     * precise 模式通过 callFunctionOn 传递参数（支持大 payload），stealth 模式仍用字符串拼接
      * @param code JavaScript 代码
      * @param mode 执行模式（stealth/precise）
      * @param timeout 端到端预算（毫秒），同时作为脚本执行超时和 sendCommand 的端到端预算
@@ -329,12 +254,13 @@ class UnifiedSessionManager {
      * @param _retried 内部重试标记，外部不应传入
      */
     async evaluate(code, mode, timeout, args, _retried) {
+        const entryStart = Date.now();
         const effectiveMode = mode ?? this.inputMode;
         const hasArgs = args && args.length > 0;
         // stealth 模式：args 只能通过字符串拼接（chrome.scripting 不支持协议级参数传递）
         let expression = code;
         if (hasArgs && effectiveMode === 'stealth') {
-            const argsStr = args.map(a => JSON.stringify(a)).join(', ');
+            const argsStr = args.map((a) => JSON.stringify(a)).join(', ');
             expression = `(${code})(${argsStr})`;
         }
         const cdpScript = hasArgs ? code : expression;
@@ -343,61 +269,37 @@ class UnifiedSessionManager {
                 // 轮询上下文：快速失败，端到端预算受控
                 if (!this.isExtensionConnected()) {
                     this.assertCdpFallbackAllowed();
-                    return getCdpSession().evaluate(cdpScript, args, timeout);
+                    return this.evaluateViaCdp(cdpScript, args, timeout);
                 }
             }
             else {
                 // 非轮询上下文：允许等待重连；连接失败时回退 CDP
                 if (!(await this.ensureExtensionConnected())) {
-                    return getCdpSession().evaluate(cdpScript, args, timeout);
+                    return this.evaluateViaCdp(cdpScript, args, timeout);
                 }
             }
             // Extension 路径
-            const currentFrameId = this.extensionBridge.getCurrentFrameId();
             if (effectiveMode === 'precise') {
-                // precise + args + 主 frame：使用 callFunctionOn 避免大 payload 字符串拼接
-                if (hasArgs && currentFrameId === 0) {
-                    return this.callFunctionOn(code, args, timeout);
-                }
-                if (currentFrameId !== 0) {
-                    // iframe：args 仍用字符串拼接（evaluateInFrame 使用 expression 字符串）
-                    let iframeExpression = expression;
-                    if (hasArgs) {
-                        const argsStr = args.map(a => JSON.stringify(a)).join(', ');
-                        iframeExpression = `(${code})(${argsStr})`;
-                    }
-                    const result = await this.extensionBridge.evaluateInFrame(currentFrameId, iframeExpression, timeout);
-                    return this.checkCdpResult(result);
-                }
-                // 主 frame，无 args：直接 Runtime.evaluate
-                const params = {
-                    expression,
-                    returnByValue: true,
-                    awaitPromise: true,
-                };
-                if (timeout !== undefined) {
-                    params.timeout = timeout;
-                }
-                // timeout 即端到端预算，直接作为 RPC 超时（不额外加 margin）
-                const result = await this.extensionBridge.debuggerSend('Runtime.evaluate', params, undefined, timeout);
-                return this.checkCdpResult(result);
+                return this.evaluateViaExtensionPrecise(code, expression, args, timeout);
             }
-            return await this.extensionBridge.evaluate(expression, timeout, timeout);
+            return this.evaluateViaExtensionStealth(expression, timeout);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
+            // 计算重试时剩余预算（避免重试用满预算导致总耗时超额）
+            const remainingTimeout = timeout !== undefined ? Math.max(0, timeout - (Date.now() - entryStart)) : undefined;
             // Extension 断连时等待重连后重试一次
-            if (!_retried &&
-                (msg.includes('Extension disconnected') ||
-                    msg.includes('Connection replaced') ||
-                    msg.includes('not connected'))) {
-                await new Promise(r => setTimeout(r, 2000));
+            if (!_retried && (isExtensionDisconnected(err) || msg.includes('not connected'))) {
+                if (remainingTimeout !== undefined && remainingTimeout <= 0) {
+                    throw err;
+                }
+                await new Promise((r) => setTimeout(r, 2000));
                 if (this.isExtensionConnected()) {
-                    return this.evaluate(code, mode, timeout, args, true);
+                    return this.evaluate(code, mode, remainingTimeout, args, true);
                 }
                 // Extension 重连失败，尝试 CDP fallback
                 if (!this.requireExtension) {
-                    return getCdpSession().evaluate(cdpScript, args, timeout);
+                    return this.evaluateViaCdp(cdpScript, args, remainingTimeout);
                 }
             }
             // 裸 return 语句导致语法错误时，自动包裹 IIFE 重试（仅一次）
@@ -414,96 +316,30 @@ class UnifiedSessionManager {
      * 获取页面文本
      */
     async getText(selector) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.getText(selector);
-        }
-        if (selector) {
-            return getCdpSession().evaluate(`(s => document.querySelector(s)?.textContent || '')`, [selector]);
-        }
-        return getCdpSession().evaluate('document.body.innerText');
+        return (await this.getDriver()).getPageText(selector);
     }
-    /**
-     * 获取页面 HTML
-     */
     async getHtml(selector, outer = true) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.getHtml(selector, outer);
-        }
-        if (selector) {
-            const prop = outer ? 'outerHTML' : 'innerHTML';
-            return getCdpSession().evaluate(`((s, p) => { const el = document.querySelector(s); return el ? el[p] : ''; })`, [selector, prop]);
-        }
-        return getCdpSession().evaluate('document.documentElement.outerHTML');
+        return (await this.getDriver()).getPageHtml(selector, outer);
     }
     /**
      * 获取页面 HTML + 图片元信息
      */
     async getHtmlWithImages(selector, outer = true) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.getHtmlWithImages(selector, outer);
-        }
-        // CDP 模式：evaluate 注入函数
-        const selectorArg = JSON.stringify(selector ?? null);
-        return getCdpSession().evaluate(`(function() {
-            var root = ${selectorArg} ? document.querySelector(${selectorArg}) : document.documentElement;
-            if (!root) return {html: '', images: []};
-            var html = ${selectorArg}
-                ? (${outer} ? root.outerHTML : root.innerHTML)
-                : document.documentElement.outerHTML;
-            var imgList = [];
-            if (root.tagName === 'IMG') imgList.push(root);
-            root.querySelectorAll('img').forEach(function(img) { imgList.push(img); });
-            var images = [];
-            for (var i = 0; i < imgList.length; i++) {
-                var img = imgList[i];
-                images.push({index: i, src: img.src, dataSrc: (function() { var raw = img.dataset.src || img.dataset.lazySrc || img.dataset.original || ''; if (!raw) return ''; try { return new URL(raw, location.href).href } catch(e) { return raw } })(), alt: img.alt, width: img.width, height: img.height, naturalWidth: img.naturalWidth, naturalHeight: img.naturalHeight});
-            }
-            return {html: html, images: images};
-        })()`);
+        const driver = await this.getDriver();
+        return driver.getHtmlWithImages(selector, outer);
     }
     /**
      * 获取页面元信息
      */
     async getMetadata() {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.getMetadata();
-        }
-        // CDP 模式：evaluate 注入函数
-        return getCdpSession().evaluate(`(function() {
-            function meta(name) {
-                var el = document.querySelector('meta[name="'+name+'"],meta[property="'+name+'"]');
-                return el ? el.content || undefined : undefined;
-            }
-            var og = {}, tw = {};
-            document.querySelectorAll('meta[property^="og:"]').forEach(function(m) { og[m.getAttribute('property')] = m.content || ''; });
-            document.querySelectorAll('meta[name^="twitter:"]').forEach(function(m) { tw[m.getAttribute('name')] = m.content || ''; });
-            var jsonLd = [];
-            document.querySelectorAll('script[type="application/ld+json"]').forEach(function(s) {
-                try { jsonLd.push(JSON.parse(s.textContent || '')); } catch(e) {}
-            });
-            var alternates = [];
-            document.querySelectorAll('link[rel="alternate"]').forEach(function(l) {
-                alternates.push({href: l.href, type: l.getAttribute('type') || undefined, hreflang: l.getAttribute('hreflang') || undefined});
-            });
-            var feeds = [];
-            document.querySelectorAll('link[type="application/rss+xml"],link[type="application/atom+xml"]').forEach(function(l) {
-                feeds.push({href: l.href, type: l.getAttribute('type'), title: l.getAttribute('title') || undefined});
-            });
-            return {
-                title: document.title,
-                description: meta('description'),
-                canonical: (document.querySelector('link[rel="canonical"]') || {}).href || undefined,
-                charset: document.characterSet,
-                viewport: meta('viewport'),
-                og: og, twitter: tw, jsonLd: jsonLd, alternates: alternates, feeds: feeds
-            };
-        })()`);
+        const driver = await this.getDriver();
+        return driver.getMetadata();
     }
     /**
      * 批量从浏览器缓存获取资源内容
      *
-     * 只调用一次 Page.enable + Page.getFrameTree，然后逐个获取资源。
-     * 并发限制避免 CDP 连接拥塞。
+     * 只调用一次 Page.enable + Page.getFrameTree，然后逐个获取资源，
+     * 并发限制避免 CDP 连接拥塞
      */
     async getResourceContentBatch(urls, concurrency = 6) {
         const results = new Map();
@@ -512,7 +348,7 @@ class UnifiedSessionManager {
         }
         try {
             await this.sendCdpCommand('Page.enable');
-            const frameTree = await this.sendCdpCommand('Page.getFrameTree');
+            const frameTree = (await this.sendCdpCommand('Page.getFrameTree'));
             const frameId = frameTree.frameTree.frame.id;
             // 并发控制
             let idx = 0;
@@ -520,18 +356,18 @@ class UnifiedSessionManager {
                 while (idx < urls.length) {
                     const url = urls[idx++];
                     try {
-                        const result = await this.sendCdpCommand('Page.getResourceContent', { frameId, url });
+                        const result = (await this.sendCdpCommand('Page.getResourceContent', { frameId, url }));
                         results.set(url, result);
                     }
-                    catch {
-                        // 单个资源获取失败不影响其他
+                    catch (err) {
+                        console.warn('[MCP] 资源获取失败:', url, err);
                     }
                 }
             };
             await Promise.all(Array.from({ length: Math.min(concurrency, urls.length) }, () => next()));
         }
-        catch {
-            // Page.enable 或 getFrameTree 失败，返回空结果
+        catch (err) {
+            console.warn('[MCP] Page 域不可用，返回空资源列表:', err);
         }
         return results;
     }
@@ -554,218 +390,103 @@ class UnifiedSessionManager {
                 return this.extensionBridge.find(selector, text, xpath, timeout);
             }
             this.assertCdpFallbackAllowed();
-            return this.findViaCdp(selector, text, xpath, timeout);
+            return getCdpSession().find(selector, text, xpath, timeout);
         }
-        // 非轮询上下文：允许等待重连
-        if (await this.ensureExtensionConnected()) {
-            return this.withExtensionRetry(() => this.extensionBridge.find(selector, text, xpath), () => this.findViaCdp(selector, text, xpath));
-        }
-        return this.findViaCdp(selector, text, xpath);
+        // 非轮询上下文：允许等待重连，断连时 fallback CDP
+        const driver = await this.getDriver();
+        return this.withExtensionRetry(() => driver.find(selector, text, xpath), () => getCdpSession().find(selector, text, xpath));
     }
     /**
      * 获取元素属性
      */
     async getAttribute(selector, refId, attribute) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.getAttribute(selector, refId, attribute);
-        }
-        throw new Error('CDP 模式下请使用 extract 工具');
+        const driver = await this.getDriver();
+        return driver.getAttribute(selector, refId, attribute);
     }
     /**
      * 获取 Cookies
      */
     async getCookies(filter) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.getCookies(filter);
-        }
-        // CDP 模式：支持按字段过滤
-        const urls = filter?.url ? [filter.url] : undefined;
-        const cookies = await getCdpSession().getCookies(urls);
-        if (!filter) {
-            return cookies;
-        }
-        return cookies.filter((c) => {
-            if (filter.name && c.name !== filter.name) {
-                return false;
-            }
-            if (filter.domain) {
-                // 域名匹配：精确匹配或子域匹配（.example.com 匹配 sub.example.com）
-                const filterDomain = filter.domain.replace(/^\./, '');
-                const cookieDomain = (c.domain ?? '').replace(/^\./, '');
-                if (cookieDomain !== filterDomain && !cookieDomain.endsWith('.' + filterDomain)) {
-                    return false;
-                }
-            }
-            if (filter.path && c.path !== filter.path) {
-                return false;
-            }
-            if (filter.secure !== undefined && c.secure !== filter.secure) {
-                return false;
-            }
-            if (filter.session !== undefined) {
-                // session cookie: expires 为 -1 或 0（CDP 返回 session cookie 的 expires 为 -1）
-                const isSession = (c.expires ?? -1) <= 0;
-                if (filter.session !== isSession) {
-                    return false;
-                }
-            }
-            return true;
-        });
+        return (await this.getDriver()).getCookies(filter);
     }
-    /**
-     * 设置 Cookie
-     */
-    async setCookie(name, value, options = {}) {
-        if (await this.ensureExtensionConnected()) {
-            const state = this.extensionBridge.getState();
-            const url = options.url || state?.url || 'http://localhost';
-            // 转换 sameSite 值到 Chrome cookies API 格式
-            let chromeSameSite;
-            if (options.sameSite) {
-                const sameSiteMap = {
-                    None: 'no_restriction',
-                    Lax: 'lax',
-                    Strict: 'strict',
-                };
-                chromeSameSite = sameSiteMap[options.sameSite];
-            }
-            await this.extensionBridge.setCookie({
-                url,
-                name,
-                value,
-                domain: options.domain,
-                path: options.path,
-                secure: options.secure,
-                httpOnly: options.httpOnly,
-                sameSite: chromeSameSite,
-                expirationDate: options.expirationDate,
-            });
-            return;
-        }
-        await getCdpSession().setCookie(name, value, options);
+    async setCookie(params) {
+        const driver = await this.getDriver();
+        await driver.setCookie(params);
     }
-    /**
-     * 删除 Cookie
-     */
     async deleteCookie(url, name) {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.deleteCookie(url, name);
-            return;
-        }
-        await getCdpSession().deleteCookie(name, url);
+        return (await this.getDriver()).deleteCookie(url, name);
     }
-    /**
-     * 清空 Cookies
-     */
     async clearCookies(filter) {
-        if (await this.ensureExtensionConnected()) {
-            return await this.extensionBridge.clearCookies(filter);
-        }
-        // CDP 模式：有 filter 时先获取匹配的 cookies 再逐条删除，无 filter 时清除全部
-        if (filter && (filter.url || filter.domain)) {
-            // 优先使用 url 过滤缩小范围，减少不必要的遍历
-            const urls = filter.url ? [filter.url] : undefined;
-            const cookies = await getCdpSession().getCookies(urls);
-            let count = 0;
-            for (const cookie of cookies) {
-                // domain 进一步过滤（url 过滤后可能仍包含不匹配 domain 的 cookie）
-                if (filter.domain) {
-                    const filterDomain = filter.domain.replace(/^\./, '');
-                    const cookieDomain = cookie.domain.replace(/^\./, '');
-                    if (cookieDomain !== filterDomain && !cookieDomain.endsWith('.' + filterDomain)) {
-                        continue;
-                    }
-                }
-                // 构造删除 URL：必须匹配 cookie 自身的 domain/path/secure
-                const protocol = cookie.secure ? 'https:' : 'http:';
-                const domain = cookie.domain.startsWith('.') ? cookie.domain.slice(1) : cookie.domain;
-                const deleteUrl = `${protocol}//${domain}${cookie.path}`;
-                await getCdpSession().deleteCookie(cookie.name, deleteUrl);
-                count++;
-            }
-            return { count };
-        }
-        await getCdpSession().clearCookies();
-        return { count: -1 };
+        return (await this.getDriver()).clearCookies(filter);
     }
     /**
      * 创建新页面
      */
     async newPage(url) {
-        if (await this.ensureExtensionConnected()) {
-            // createTab 会设置 currentTabId，需要加锁
-            const tab = await this.withTabLock(async () => {
-                return this.extensionBridge.createTab(url);
-            });
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        const op = async () => {
+            const result = await driver.newPage(url);
             return {
-                targetId: String(tab.id),
-                type: 'page',
-                url: tab.url,
-                title: tab.title,
+                targetId: result.targetId,
+                type: result.type ?? 'page',
+                url: result.url,
+                title: result.title,
             };
-        }
-        const target = await getCdpSession().newPage();
-        if (url) {
-            await getCdpSession().navigate(url);
-        }
-        return target;
+        };
+        // Extension 模式 createTab 设置 currentTabId,需要加锁防止并发竞态
+        return isExt ? this.withTabLock(op) : op();
     }
     /**
      * 关闭页面
      */
     async closePage(targetId) {
-        if (await this.ensureExtensionConnected()) {
-            // closeTab 可能触发 currentTabId 重置，需要加锁
-            await this.withTabLock(async () => {
-                const tabId = targetId
-                    ? this.parseTabId(targetId)
-                    : this.extensionBridge.getCurrentTabId();
-                if (tabId === null) {
-                    throw new Error('没有可关闭的页面，请指定 targetId');
-                }
-                await this.extensionBridge.closeTab(tabId);
-            });
-            return;
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        const op = () => driver.closePage(targetId);
+        if (isExt) {
+            await this.withTabLock(op);
+        }
+        else {
+            await op();
         }
-        await getCdpSession().closePage(targetId);
     }
     /**
      * 激活页面（切到前台）
      */
     async activatePage(targetId) {
-        if (await this.ensureExtensionConnected()) {
-            const tabId = this.parseTabId(targetId);
-            await this.withTabLock(async () => {
-                await this.extensionBridge.activateTab(tabId);
-            });
-            return;
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        const op = () => driver.activatePage(targetId);
+        if (isExt) {
+            await this.withTabLock(op);
+        }
+        else {
+            await op();
         }
-        // CDP 模式：attach 到目标并切到前台
-        await getCdpSession().attachToTarget(targetId);
-        await getCdpSession().activateTarget(targetId);
     }
     /**
      * 选择要操作的页面（不切到前台，只设置当前操作目标）
      */
     async selectPage(targetId) {
-        if (this.isExtensionConnected()) {
-            const tabId = this.parseTabId(targetId);
-            await this.withTabLock(async () => {
-                this.extensionBridge.setCurrentTabId(tabId);
-            });
-            return;
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        const op = () => driver.selectPage(targetId);
+        if (isExt) {
+            await this.withTabLock(op);
+        }
+        else {
+            await op();
         }
-        // CDP 模式下需要 attach 到目标 target
-        await getCdpSession().attachToTarget(targetId);
     }
     /**
      * 临时切换操作目标 tab，执行完后恢复
      *
      * 用于多 tab 并行场景：指定 tabId 时临时切换到该 tab 执行操作，
-     * 不影响 browse attach 设置的默认 tab。
+     * 不影响 browse attach 设置的默认 tab
      *
      * 即使不传 tabId，也需要加锁：fn() 内调用 bridge 方法会读取 currentTabId，
-     * 不加锁则并发的 withTabId(someId, ...) 可能在 fn() 执行中途修改 currentTabId。
+     * 不加锁则并发的 withTabId(someId, ...) 可能在 fn() 执行中途修改 currentTabId
      */
     async withTabId(tabId, fn) {
         // Extension 未连接时不需要锁和 tab 切换（CDP 模式无 currentTabId 竞态）
@@ -786,10 +507,10 @@ class UnifiedSessionManager {
             // 不切换 tab，但需要加锁保护 currentTabId 不被并发修改
             return this.withTabLock(fn);
         }
-        const numericTabId = this.parseTabId(tabId);
+        const driver = this.extensionBridge;
         return this.withTabLock(async () => {
-            const previousTabId = this.extensionBridge.getCurrentTabId();
-            this.extensionBridge.setCurrentTabId(numericTabId);
+            const previousTargetId = driver.getCurrentTargetId();
+            driver.setCurrentTargetId(tabId);
             // tabId 明确指定时，禁止 CDP 回退（CDP 不感知 Extension tab）
             const previousRequireExtension = this.requireExtension;
             this.requireExtension = true;
@@ -798,15 +519,15 @@ class UnifiedSessionManager {
             }
             finally {
                 this.requireExtension = previousRequireExtension;
-                this.extensionBridge.setCurrentTabId(previousTabId);
+                driver.setCurrentTargetId(previousTargetId);
             }
         });
     }
     /**
      * 临时切换操作目标 iframe，执行完后恢复
      *
-     * frame 支持 CSS 选择器（如 "iframe#main"）或索引（如 0）。
-     * 内部通过 Extension 的 resolveFrame 将选择器解析为 Chrome frameId。
+     * frame 支持 CSS 选择器（如 "iframe#main"）或索引（如 0），
+     * 内部通过 Extension 的 resolveFrame 将选择器解析为 Chrome frameId
      *
      * 与 withTabId 配合使用时，应嵌套在 withTabId 内部：
      * withTabId(tabId, () => withFrame(frame, () => { ... }))
@@ -818,31 +539,33 @@ class UnifiedSessionManager {
         if (!this.extensionBridge?.isConnected()) {
             throw new Error('iframe 穿透需要 Extension 模式');
         }
-        const { frameId, offset } = await this.extensionBridge.resolveFrame(frame);
-        const previousFrameId = this.extensionBridge.getCurrentFrameId();
+        const driver = this.extensionBridge;
+        const { frameId, offset } = await driver.resolveFrame(frame);
+        const previousFrameId = driver.getCurrentFrameId();
         const previousFrameOffset = this.currentFrameOffset;
         const previousRequireExtension = this.requireExtension;
-        this.extensionBridge.setCurrentFrameId(frameId);
+        driver.setCurrentFrameId(frameId);
         this.currentFrameOffset = offset;
         this.requireExtension = true;
         try {
             return await fn();
         }
         finally {
+            // 字段赋值不会 throw,driver.setCurrentFrameId 是同步函数也不会 throw,无需嵌套 try
             this.requireExtension = previousRequireExtension;
             this.currentFrameOffset = previousFrameOffset;
-            this.extensionBridge.setCurrentFrameId(previousFrameId);
+            driver.setCurrentFrameId(previousFrameId);
         }
     }
     /**
      * 获取当前状态
      */
     getState() {
+        // driver.getState() 两侧都返回 DriverState | null（{url, title}），SessionState 含 targetId 是其超集，结构兼容
         if (this.extensionBridge?.isConnected()) {
             return this.extensionBridge.getState();
         }
-        const cdpState = getCdpSession().getState();
-        return cdpState ? { url: cdpState.url, title: cdpState.title } : null;
+        return getCdpSession().getState();
     }
     /**
      * 关闭所有连接
@@ -857,110 +580,119 @@ class UnifiedSessionManager {
     /**
      * 按下键盘按键
      */
-    async keyDown(key) {
+    async keyDown(key, commands) {
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        // 预检查：stealth + commands 必然抛错，要在任何状态变更前抛出，避免 modifiers 污染
+        if (isExt && this.inputMode === 'stealth' && commands && commands.length > 0) {
+            throw new Error('commands 参数不支持 stealth 输入模式（stealth 通过 JS 合成事件，无法触发 Chrome 原生编辑命令），请先调用 manage action=inputMode inputMode=precise 切换后重试');
+        }
+        // Puppeteer 风格：连续 keyDown 同 key → rawKeyDown + autoRepeat（长按重复）
+        const isRepeat = this.pressedKeys.has(key);
+        this.pressedKeys.add(key);
         if (MODIFIER_KEYS[key]) {
             this.modifiers |= MODIFIER_KEYS[key];
         }
-        if (await this.ensureExtensionConnected()) {
-            if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthKey(key, 'down', this.getModifierNames());
-            }
-            else {
-                await this.extensionBridge.inputKey('keyDown', { key, code: key, modifiers: this.modifiers });
-            }
+        if (isExt && this.inputMode === 'stealth') {
+            await driver.stealthKey(key, 'down', this.getModifierNames());
             return;
         }
-        await getCdpSession().keyDown(key);
+        const def = getKeyDefinition(key);
+        await driver.inputKey(isRepeat ? 'rawKeyDown' : 'keyDown', {
+            key: def.key,
+            code: def.code,
+            text: def.text,
+            windowsVirtualKeyCode: def.keyCode,
+            modifiers: this.modifiers,
+            commands,
+            autoRepeat: isRepeat || undefined,
+        });
     }
     /**
      * 释放键盘按键
      */
     async keyUp(key) {
-        if (await this.ensureExtensionConnected()) {
-            if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthKey(key, 'up', this.getModifierNames());
-            }
-            else {
-                await this.extensionBridge.inputKey('keyUp', { key, code: key, modifiers: this.modifiers });
-            }
-            if (MODIFIER_KEYS[key]) {
-                this.modifiers &= ~MODIFIER_KEYS[key];
-            }
-            return;
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        if (isExt && this.inputMode === 'stealth') {
+            await driver.stealthKey(key, 'up', this.getModifierNames());
+        }
+        else {
+            const def = getKeyDefinition(key);
+            await driver.inputKey('keyUp', {
+                key: def.key,
+                code: def.code,
+                windowsVirtualKeyCode: def.keyCode,
+                modifiers: this.modifiers,
+            });
         }
         if (MODIFIER_KEYS[key]) {
             this.modifiers &= ~MODIFIER_KEYS[key];
         }
-        await getCdpSession().keyUp(key);
+        this.pressedKeys.delete(key);
     }
     /**
      * 输入文本
      */
     async typeText(text, delay = 0) {
-        if (await this.ensureExtensionConnected()) {
-            if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthType(text, delay);
-            }
-            else {
-                await this.extensionBridge.inputType(text, delay);
-            }
-            return;
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        if (isExt && this.inputMode === 'stealth') {
+            await driver.stealthType(text, delay);
+        }
+        else {
+            await driver.inputType(text, delay);
         }
-        await getCdpSession().type(text, delay);
     }
     /**
      * 鼠标移动
      */
     async mouseMove(x, y) {
         this.currentMousePosition = { x, y }; // 更新位置
-        if (await this.ensureExtensionConnected()) {
-            if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthMouse('mousemove', x, y);
-            }
-            else {
-                await this.extensionBridge.inputMouse('mouseMoved', x, y, { modifiers: this.modifiers });
-            }
-            return;
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        if (isExt && this.inputMode === 'stealth') {
+            await driver.stealthMouse('mousemove', x, y);
+        }
+        else {
+            await driver.inputMouse('mouseMoved', x, y, { modifiers: this.modifiers });
         }
-        await getCdpSession().mouseMove(x, y);
     }
     /**
      * 鼠标按下
      */
-    async mouseDown(button = 'left') {
-        const effectiveButton = (button === 'back' || button === 'forward') ? 'left' : button;
-        const { x, y } = this.currentMousePosition; // 使用当前位置
-        if (await this.ensureExtensionConnected()) {
-            if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthMouse('mousedown', x, y, effectiveButton);
-            }
-            else {
-                await this.extensionBridge.inputMouse('mousePressed', x, y, {
-                    button: effectiveButton,
-                    clickCount: 1,
-                    modifiers: this.modifiers,
-                });
-            }
-            return;
+    async mouseDown(button = 'left', clickCount = 1) {
+        const { x, y } = this.currentMousePosition;
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        if (isExt && this.inputMode === 'stealth') {
+            await driver.stealthMouse('mousedown', x, y, button);
+        }
+        else {
+            await driver.inputMouse('mousePressed', x, y, {
+                button,
+                clickCount,
+                modifiers: this.modifiers,
+            });
         }
-        await getCdpSession().mouseDown(effectiveButton);
     }
     /**
      * 鼠标释放
      */
-    async mouseUp(button = 'left') {
-        const effectiveButton = (button === 'back' || button === 'forward') ? 'left' : button;
-        const { x, y } = this.currentMousePosition; // 使用当前位置
-        if (await this.ensureExtensionConnected()) {
-            if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthMouse('mouseup', x, y, effectiveButton);
-            }
-            else {
-                await this.extensionBridge.inputMouse('mouseReleased', x, y, { button: effectiveButton, clickCount: 1, modifiers: this.modifiers });
-            }
-            return;
+    async mouseUp(button = 'left', clickCount = 1) {
+        const { x, y } = this.currentMousePosition;
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        if (isExt && this.inputMode === 'stealth') {
+            await driver.stealthMouse('mouseup', x, y, button);
+        }
+        else {
+            await driver.inputMouse('mouseReleased', x, y, {
+                button,
+                clickCount,
+                modifiers: this.modifiers,
+            });
         }
-        await getCdpSession().mouseUp(effectiveButton);
     }
     /**
      * 鼠标点击（mousedown + mouseup + click 三合一）
@@ -968,132 +700,132 @@ class UnifiedSessionManager {
      * stealth 模式：原子操作（单次脚本注入完成 mouseover → mousedown → focus → mouseup → click）
      * precise / CDP 模式：mouseDown + mouseUp，浏览器自动合成原生 click 事件
      */
-    async mouseClick(button = 'left') {
-        if (this.inputMode === 'stealth' && await this.ensureExtensionConnected()) {
-            const effectiveButton = (button === 'back' || button === 'forward') ? 'left' : button;
+    async mouseClick(button = 'left', clickCount = 1, refId) {
+        const driver = await this.getDriver();
+        const isExt = this.isExtensionConnected();
+        if (this.inputMode === 'stealth' && isExt) {
             const { x, y } = this.currentMousePosition;
-            await this.extensionBridge.stealthClick(x, y, effectiveButton);
+            // stealth 通过单次脚本注入完成所有 mouse/click/dblclick/contextmenu 事件
+            // refId 透传：嵌套 iframe overlay 场景下绕过 elementFromPoint 命中外层 IFRAME 的问题
+            await driver.stealthClick(x, y, button, clickCount, refId);
             return;
         }
-        await this.mouseDown(button);
-        await this.mouseUp(button);
+        // CDP 每次 mousePressed/mouseReleased 递增 clickCount，让浏览器合成 dblclick/tripleclick
+        for (let i = 1; i <= clickCount; i++) {
+            await this.mouseDown(button, i);
+            await this.mouseUp(button, i);
+        }
     }
     /**
      * 鼠标滚轮
      */
     async mouseWheel(deltaX, deltaY) {
-        if (await this.ensureExtensionConnected()) {
-            const { x, y } = this.currentMousePosition;
-            await this.extensionBridge.inputMouse('mouseWheel', x, y, { deltaX, deltaY, modifiers: this.modifiers });
-            return;
-        }
-        await getCdpSession().mouseWheel(deltaX, deltaY);
+        const { x, y } = this.currentMousePosition;
+        const driver = await this.getDriver();
+        await driver.inputMouse('mouseWheel', x, y, { deltaX, deltaY, modifiers: this.modifiers });
     }
     /**
      * 注入反检测脚本
      */
     async injectStealth() {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.stealthInject();
-            return;
-        }
-        throw new Error('CDP 模式下 stealth 脚本在 connect/launch 时通过 stealth 参数自动注入，不支持后续手动注入');
+        const driver = await this.getDriver();
+        await driver.stealthInject();
     }
-    // ==================== 键鼠输入 ====================
-    // stealth 模式：使用 JS 事件模拟，不触发调试提示，推荐用于反检测场景
-    // precise 模式：使用 debugger API，精确但会显示"扩展程序正在调试此浏览器"
     /**
      * 触摸开始
      */
     async touchStart(x, y) {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.inputTouch('touchStart', [{ x, y, id: 0 }]);
-            return;
-        }
-        await getCdpSession().touchStart(x, y);
+        const driver = await this.getDriver();
+        await driver.inputTouch('touchStart', [{ x, y, id: 0 }]);
     }
     /**
      * 触摸移动
      */
     async touchMove(x, y) {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.inputTouch('touchMove', [{ x, y, id: 0 }]);
-            return;
-        }
-        await getCdpSession().touchMove(x, y);
+        const driver = await this.getDriver();
+        await driver.inputTouch('touchMove', [{ x, y, id: 0 }]);
     }
     /**
      * 触摸结束
      */
     async touchEnd() {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.inputTouch('touchEnd', []);
-            return;
-        }
-        await getCdpSession().touchEnd();
+        const driver = await this.getDriver();
+        await driver.inputTouch('touchEnd', []);
     }
+    // ==================== 键鼠输入 ====================
+    // stealth 模式：使用 JS 事件模拟，不触发调试提示，推荐用于反检测场景
+    // precise 模式：使用 debugger API，精确但会显示"扩展程序正在调试此浏览器"
     /**
      * 启用控制台日志捕获
      */
     async enableConsole() {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.consoleEnable();
-            return;
-        }
-        // CDP 模式已经在 logs 工具中实现
+        const driver = await this.getDriver();
+        await driver.consoleEnable();
     }
     /**
      * 获取控制台日志
      */
     async getConsoleLogs(options = {}) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.consoleGet(options);
-        }
-        // CDP 模式需要单独实现
-        return [];
+        return (await this.getDriver()).getConsoleLogs(options);
     }
-    /**
-     * 启用网络日志捕获
-     */
-    async enableNetwork() {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.networkEnable();
-            return;
-        }
-        // CDP 模式已在 session 中启用 Network.enable
-    }
-    /**
-     * 获取网络请求日志
-     */
     async getNetworkRequests(options = {}) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.networkGet(options);
-        }
-        return [];
+        return (await this.getDriver()).getNetworkRequests(options);
+    }
+    async enableNetwork() {
+        const driver = await this.getDriver();
+        await driver.networkEnable();
     }
     /**
      * 发送 CDP 命令（高级用法）
      *
-     * 自动识别 browser-level 域（Target、Browser、SystemInfo、DeviceAccess、IO）不携带 sessionId，
-     * 其他域默认携带 sessionId（page-level 命令）。
+     * Extension 模式：经 chrome.debugger.sendCommand 转发；
+     * CDP 模式：driver 自动识别 browser-level 域（Target/Browser/SystemInfo/DeviceAccess/IO）vs page-level
      */
     async sendCdpCommand(method, params) {
-        if (await this.ensureExtensionConnected()) {
-            return this.extensionBridge.debuggerSend(method, params);
+        const driver = await this.getDriver();
+        return driver.debuggerSend(method, params);
+    }
+    evaluateViaCdp(script, args, timeout) {
+        return getCdpSession().evaluate(script, args, timeout);
+    }
+    async evaluateViaExtensionPrecise(code, expression, args, timeout) {
+        const hasArgs = args !== undefined && args.length > 0;
+        const currentFrameId = this.extensionBridge.getCurrentFrameId();
+        // precise + args + 主 frame：使用 callFunctionOn 避免大 payload 字符串拼接
+        if (hasArgs && currentFrameId === 0) {
+            return this.callFunctionOn(code, args, timeout);
+        }
+        if (currentFrameId !== 0) {
+            // iframe：args 仍用字符串拼接（evaluateInFrame 使用 expression 字符串）
+            let iframeExpression = expression;
+            if (hasArgs) {
+                const argsStr = args.map((a) => JSON.stringify(a)).join(', ');
+                iframeExpression = `(${code})(${argsStr})`;
+            }
+            const result = (await this.extensionBridge.evaluateInFrame(currentFrameId, iframeExpression, timeout));
+            return this.checkCdpResult(result);
         }
-        // CDP 模式：browser-level 域不携带 sessionId
-        const domain = method.split('.')[0];
-        const browserLevelDomains = ['Target', 'Browser', 'SystemInfo', 'DeviceAccess', 'IO'];
-        if (browserLevelDomains.includes(domain)) {
-            return getCdpSession().sendBrowserCommand(method, params);
+        // 主 frame，无 args：直接 Runtime.evaluate
+        const params = {
+            expression,
+            returnByValue: true,
+            awaitPromise: true,
+        };
+        if (timeout !== undefined) {
+            params.timeout = timeout;
         }
-        return getCdpSession().send(method, params);
+        // timeout 即端到端预算，直接作为 RPC 超时（不额外加 margin）
+        const result = (await this.extensionBridge.debuggerSend('Runtime.evaluate', params, undefined, timeout));
+        return this.checkCdpResult(result);
+    }
+    async evaluateViaExtensionStealth(expression, timeout) {
+        return (await this.extensionBridge.evaluate(expression, undefined, timeout));
     }
     /**
      * Extension 操作断连自动重试
      *
-     * 操作失败且错误为断连类型时，等待 2 秒让 Extension 重连后重试一次。
-     * 若重连失败且提供了 cdpFallback，则降级到 CDP 模式。
+     * 操作失败且错误为断连类型时，等待 2 秒让 Extension 重连后重试一次，
+     * 若重连失败且提供了 cdpFallback，则降级到 CDP 模式
      */
     async withExtensionRetry(operation, cdpFallback) {
         try {
@@ -1101,11 +833,9 @@ class UnifiedSessionManager {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            if (msg.includes('Extension disconnected') ||
-                msg.includes('Connection replaced') ||
-                msg.includes('not connected')) {
+            if (isExtensionDisconnected(err) || msg.includes('not connected')) {
                 // 等待 Extension 重连
-                await new Promise(r => setTimeout(r, 2000));
+                await new Promise((r) => setTimeout(r, 2000));
                 if (this.isExtensionConnected()) {
                     return operation();
                 }
@@ -1117,51 +847,19 @@ class UnifiedSessionManager {
             throw err;
         }
     }
-    /** CDP fallback：通过 Runtime.evaluate 注入 DOM 查询逻辑 */
-    async findViaCdp(selector, text, xpath, timeout) {
-        return getCdpSession().evaluate(`function(selector, text, xpath) {
-            var elements;
-            if (xpath) {
-                elements = [];
-                var xr = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
-                for (var i = 0; i < xr.snapshotLength; i++) {
-                    var node = xr.snapshotItem(i);
-                    if (node instanceof Element) elements.push(node);
-                }
-            } else if (selector) {
-                elements = Array.from(document.querySelectorAll(selector));
-            } else {
-                elements = Array.from(document.querySelectorAll('*'));
-            }
-            var results = [];
-            for (var j = 0; j < elements.length; j++) {
-                var el = elements[j];
-                if (text && !(el.textContent || '').includes(text)) continue;
-                var rect = el.getBoundingClientRect();
-                results.push({
-                    refId: '',
-                    tag: el.tagName.toLowerCase(),
-                    text: (el.textContent || '').trim().substring(0, 100),
-                    rect: {x: rect.x, y: rect.y, width: rect.width, height: rect.height}
-                });
-                if (results.length >= 50) break;
-            }
-            return results;
-        }`, [selector ?? null, text ?? null, xpath ?? null], timeout);
-    }
     /** 获取当前修饰键名称数组（stealth 模式用） */
     getModifierNames() {
         const names = [];
-        if (this.modifiers & 1) {
+        if (this.modifiers & MODIFIER_KEYS.Alt) {
             names.push('alt');
         }
-        if (this.modifiers & 2) {
+        if (this.modifiers & MODIFIER_KEYS.Control) {
             names.push('ctrl');
         }
-        if (this.modifiers & 4) {
+        if (this.modifiers & MODIFIER_KEYS.Meta) {
             names.push('meta');
         }
-        if (this.modifiers & 8) {
+        if (this.modifiers & MODIFIER_KEYS.Shift) {
             names.push('shift');
         }
         return names;
@@ -1179,8 +877,8 @@ class UnifiedSessionManager {
     /**
      * 检查 CDP 回退是否允许
      *
-     * 当 requireExtension 为 true（tabId 或 frame 已指定）时，CDP 回退会操作错误目标，必须阻止。
-     * 允许时返回 false（供 ensureExtensionConnected 直接返回），不允许时抛出。
+     * 当 requireExtension 为 true（tabId 或 frame 已指定）时，CDP 回退会操作错误目标，必须阻止，
+     * 允许时返回 false（供 ensureExtensionConnected 直接返回），不允许时抛出
      */
     assertCdpFallbackAllowed() {
         if (this.requireExtension) {
@@ -1192,16 +890,22 @@ class UnifiedSessionManager {
      * 确保 Extension 已连接，如果断开则等待重连
      * 返回 true 表示 Extension 可用，false 表示应 fallback 到 CDP
      *
-     * 设计理念：Server 和 Extension 的启动时机完全独立，无任何要求。
+     * 设计理念：Server 和 Extension 的启动时机完全独立，无任何要求
      * - 先装 Extension，一个月/一年后启动 Server → 能连上
      * - 先启动 Server，再打开 Chrome → 能连上
      * - 关闭再打开任何一方 → 能自动重连
      *
-     * 超时设为 30 秒：足够等待 Extension 启动，但不会永远卡住。
+     * 超时设为 30 秒：足够等待 Extension 启动，但不会永远卡住
      *
-     * @param maxWait 调用方的端到端预算（毫秒）。传入时取 min(maxWait, 30000) 作为连接等待上限，
-     *               避免工具 timeout 被连接等待吞掉。不传则使用默认 30s。
+     * @param timeout 调用方的端到端预算（毫秒），传入时取 min(timeout, 30000) 作为连接等待上限，
+     *               避免工具 timeout 被连接等待吞掉，不传则使用默认 30s
      */
+    async getDriver(timeout) {
+        if (await this.ensureExtensionConnected(timeout)) {
+            return this.extensionBridge;
+        }
+        return getCdpSession();
+    }
     async ensureExtensionConnected(maxWait) {
         if (!this.extensionBridge) {
             return this.assertCdpFallbackAllowed();
@@ -1238,46 +942,45 @@ class UnifiedSessionManager {
     /**
      * 通过 callFunctionOn 执行函数调用
      *
-     * 参数通过 CDP 协议结构化传递，避免大 payload 字符串拼接导致的长度限制和转义问题。
-     * 要求 code 必须是函数表达式（如 "(x) => x + 1"）。
+     * 参数通过 CDP 协议结构化传递，避免大 payload 字符串拼接导致的长度限制和转义问题，
+     * 要求 code 必须是函数表达式（如 "(x) => x + 1"）
      */
     async callFunctionOn(code, args, timeout) {
-        const globalResult = await this.extensionBridge.debuggerSend('Runtime.evaluate', {
+        const globalResult = (await this.extensionBridge.debuggerSend('Runtime.evaluate', {
             expression: 'globalThis',
             returnByValue: false,
-        }, undefined, timeout);
+        }, undefined, timeout));
         try {
             const params = {
                 functionDeclaration: code,
                 objectId: globalResult.result.objectId,
-                arguments: args.map(a => ({ value: a })),
+                arguments: args.map((a) => ({ value: a })),
                 returnByValue: true,
                 awaitPromise: true,
             };
             if (timeout !== undefined) {
                 params.timeout = timeout;
             }
-            const result = await this.extensionBridge.debuggerSend('Runtime.callFunctionOn', params, undefined, timeout);
+            const result = (await this.extensionBridge.debuggerSend('Runtime.callFunctionOn', params, undefined, timeout));
             return this.checkCdpResult(result);
         }
         finally {
             this.extensionBridge.debuggerSend('Runtime.releaseObject', {
                 objectId: globalResult.result.objectId,
-            }).catch(() => {
-            });
+            }).catch(() => { });
         }
     }
     /**
-     * 串行化所有 tab 切换操作，防止并发请求互相覆盖 currentTabId。
-     * 调用者：selectPage/activatePage/newPage/closePage/navigate/reload/launch/withTabId。
+     * 串行化所有 tab 切换操作，防止并发请求互相覆盖 currentTabId，
+     * 调用者：selectPage/activatePage/newPage/closePage/navigate/reload/launch/withTabId
      *
-     * 注意：此锁不可重入。fn() 内禁止调用任何使用 withTabLock 的方法，否则会死锁。
-     * 当前所有 fn() 只调用 bridge 的原子操作（createTab/navigate/evaluate 等），不存在此问题。
+     * 注意：此锁不可重入，fn() 内禁止调用任何使用 withTabLock 的方法，否则会死锁，
+     * 当前所有 fn() 只调用 bridge 的原子操作（createTab/navigate/evaluate 等），不存在此问题
      */
     async withTabLock(fn) {
         const previousLock = this.tabSwitchLock;
         let releaseLock;
-        this.tabSwitchLock = new Promise(resolve => {
+        this.tabSwitchLock = new Promise((resolve) => {
             releaseLock = resolve;
         });
         try {