@pyrokine/mcp-chrome 1.1.0 → 1.4.0

package/dist/core/unified-session.js

@@ -7,16 +7,21 @@
  */
 import { ExtensionBridge } from '../extension/index.js';
 import { getSession as getCdpSession } from './session.js';
+import { extractCdpValue, formatCdpException, MODIFIER_KEYS } from './types.js';
 class UnifiedSessionManager {
     static instance;
     static CONNECTION_COOLDOWN = 30000; // 连接失败后 30 秒内不重试
     extensionBridge = null;
     inputMode = 'precise'; // 默认使用 precise 模式，可绕过 CSP 限制
     currentMousePosition = { x: 0, y: 0 }; // 跟踪鼠标位置
+    /** 当前按下的修饰键位掩码 */
+    modifiers = 0;
     lastConnectionFailure = 0;
     tabSwitchLock = Promise.resolve(); // 串行化 tab 切换，防止并发竞态
     requireExtension = false; // 指定 tabId 或 frame 时为 true，禁止 CDP 回退
-    constructor() { }
+    currentFrameOffset = null; // iframe 在主页面的偏移量（withFrame 期间有效）
+    constructor() {
+    }
     static getInstance() {
         if (!UnifiedSessionManager.instance) {
             UnifiedSessionManager.instance = new UnifiedSessionManager();
@@ -58,6 +63,12 @@ class UnifiedSessionManager {
     getInputMode() {
         return this.inputMode;
     }
+    /**
+     * 获取当前 iframe 在主页面的偏移量（仅 withFrame 期间有效）
+     */
+    getFrameOffset() {
+        return this.currentFrameOffset;
+    }
     /**
      * 获取当前鼠标位置
      */
@@ -73,30 +84,12 @@ class UnifiedSessionManager {
         this.inputMode = mode;
         console.error(`[MCP] Input mode set to: ${mode}`);
     }
-    /**
-     * 是否已连接（任一模式）
-     */
-    isConnected() {
-        return this.getMode() !== 'none';
-    }
     /**
      * 是否 Extension 已连接
      */
     isExtensionConnected() {
         return this.extensionBridge?.isConnected() ?? false;
     }
-    /**
-     * 检查 CDP 回退是否允许
-     *
-     * 当 requireExtension 为 true（tabId 或 frame 已指定）时，CDP 回退会操作错误目标，必须阻止。
-     * 允许时返回 false（供 ensureExtensionConnected 直接返回），不允许时抛出。
-     */
-    assertCdpFallbackAllowed() {
-        if (this.requireExtension) {
-            throw new Error('Extension 已断开，当前操作需要 Extension（指定 tabId 或 frame）时不可回退 CDP（操作目标不一致）');
-        }
-        return false;
-    }
     /**
      * 是否启用了 Extension 模式（不管当前是否连接）
      * 用于判断应该使用哪种模式
@@ -104,62 +97,6 @@ class UnifiedSessionManager {
     isExtensionModeEnabled() {
         return this.extensionBridge !== null;
     }
-    /**
-     * 等待 Extension 连接
-     * @param timeout 超时时间，0 表示无限等待
-     */
-    async waitForExtensionConnection(timeout = 0) {
-        if (!this.extensionBridge) {
-            return false;
-        }
-        return this.extensionBridge.waitForConnection(timeout);
-    }
-    /**
-     * 确保 Extension 已连接，如果断开则等待重连
-     * 返回 true 表示 Extension 可用，false 表示应 fallback 到 CDP
-     *
-     * 设计理念：Server 和 Extension 的启动时机完全独立，无任何要求。
-     * - 先装 Extension，一个月/一年后启动 Server → 能连上
-     * - 先启动 Server，再打开 Chrome → 能连上
-     * - 关闭再打开任何一方 → 能自动重连
-     *
-     * 超时设为 30 秒：足够等待 Extension 启动，但不会永远卡住。
-     *
-     * @param maxWait 调用方的端到端预算（毫秒）。传入时取 min(maxWait, 30000) 作为连接等待上限，
-     *               避免工具 timeout 被连接等待吞掉。不传则使用默认 30s。
-     */
-    async ensureExtensionConnected(maxWait) {
-        if (!this.extensionBridge) {
-            return this.assertCdpFallbackAllowed();
-        }
-        if (this.extensionBridge.isConnected()) {
-            return true;
-        }
-        // CDP 已连接时跳过 Extension 等待，直接使用 CDP 回退
-        if (getCdpSession().isConnected()) {
-            return this.assertCdpFallbackAllowed();
-        }
-        // 冷却期内不重复等待，避免每次操作都阻塞 30 秒
-        if (Date.now() - this.lastConnectionFailure < UnifiedSessionManager.CONNECTION_COOLDOWN) {
-            return this.assertCdpFallbackAllowed();
-        }
-        // Extension 服务器已启动但断开连接，等待重连
-        const waitTimeout = maxWait !== undefined ? Math.min(maxWait, 30000) : 30000;
-        if (waitTimeout <= 0) {
-            return this.assertCdpFallbackAllowed();
-        }
-        console.error(`[MCP] Waiting for Chrome Extension connection (${waitTimeout}ms timeout)...`);
-        console.error('[MCP] Please ensure Chrome is running with MCP Chrome extension installed.');
-        const connected = await this.extensionBridge.waitForConnection(waitTimeout);
-        if (connected) {
-            console.error('[MCP] Chrome Extension connected successfully');
-            this.lastConnectionFailure = 0;
-            return true;
-        }
-        console.error('[MCP] Chrome Extension connection timeout');
-        this.lastConnectionFailure = Date.now();
-        return this.assertCdpFallbackAllowed();
-    }
     /**
      * 启动浏览器（CDP 模式）或等待 Extension 连接
      */
@@ -185,16 +122,6 @@ class UnifiedSessionManager {
             mode: 'cdp',
         };
     }
-    /**
-     * 连接到已运行的浏览器（CDP 模式）
-     */
-    async connect(options) {
-        const target = await getCdpSession().connect(options);
-        return {
-            ...target,
-            mode: 'cdp',
-        };
-    }
     /**
      * 列出所有页面
      */
@@ -289,8 +216,9 @@ class UnifiedSessionManager {
         // 构建简单的文本表示
         const lines = elements.map(e => {
             let line = e.role;
-            if (e.name)
+            if (e.name) {
                 line += ` "${e.name}"`;
+            }
             return line;
         });
         return {
@@ -306,7 +234,7 @@ class UnifiedSessionManager {
             const result = await this.extensionBridge.screenshot(options);
             return result.data;
         }
-        return getCdpSession().screenshot(options?.fullPage);
+        return getCdpSession().screenshot(options?.fullPage, options?.scale, options?.format, options?.quality, options?.clip);
     }
     /**
      * 点击元素
@@ -349,46 +277,61 @@ class UnifiedSessionManager {
      * stealth 模式：使用 chrome.scripting.executeScript（受 CSP 限制）
      * precise 模式：使用 debugger API Runtime.evaluate（可绕过 CSP）
      *
-     * 使用 args 时 script 必须是函数表达式，会被包装为 IIFE：(script)(arg1, arg2, ...)
+     * 使用 args 时 script 必须是函数表达式，如 "(x) => x + 1"。
+     * precise 模式通过 callFunctionOn 传递参数（支持大 payload），stealth 模式仍用字符串拼接。
+     * @param code JavaScript 代码
+     * @param mode 执行模式（stealth/precise）
      * @param timeout 端到端预算（毫秒），同时作为脚本执行超时和 sendCommand 的端到端预算
+     * @param args 传递给函数的参数
      */
     async evaluate(code, mode, timeout, args) {
         const effectiveMode = mode ?? this.inputMode;
-        // 检测裸 return 语句，自动包裹 IIFE
-        // 排除已经是函数表达式或 IIFE 的情况
+        const hasArgs = args && args.length > 0;
+        // 检测裸 return 语句，自动包裹 IIFE（仅无 args 时）
         let expression = code;
-        if (/\breturn\b/.test(code) && !/^\s*([(\[]|function\b|async\b|class\b)/.test(code)) {
+        if (!hasArgs && /\breturn\b/.test(code) && !/^\s*([(\[]|function\b|async\b|class\b)/.test(code)) {
             expression = `(() => { ${code} })()`;
         }
-        if (args && args.length > 0) {
+        // stealth 模式：args 只能通过字符串拼接（chrome.scripting 不支持协议级参数传递）
+        if (hasArgs && effectiveMode === 'stealth') {
             const argsStr = args.map(a => JSON.stringify(a)).join(', ');
             expression = `(${code})(${argsStr})`;
         }
+        const cdpScript = hasArgs ? code : expression;
         if (timeout !== undefined) {
             // 轮询上下文：快速失败，端到端预算受控
             if (!this.isExtensionConnected()) {
                 this.assertCdpFallbackAllowed();
-                return getCdpSession().evaluate(code, args, timeout);
+                return getCdpSession().evaluate(cdpScript, args, timeout);
             }
         }
         else {
             // 非轮询上下文：允许等待重连；连接失败时回退 CDP
             if (!(await this.ensureExtensionConnected())) {
-                return getCdpSession().evaluate(code, args, timeout);
+                return getCdpSession().evaluate(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 上下文：通过 evaluateInFrame 使用 contextId 精确定位
-                const result = await this.extensionBridge.evaluateInFrame(currentFrameId, expression, timeout);
+                // 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);
                 if (result.exceptionDetails) {
-                    throw new Error(result.exceptionDetails.text);
+                    throw new Error(formatCdpException(result.exceptionDetails));
                 }
-                return result.result?.value;
+                return extractCdpValue(result.result);
             }
-            // 主 frame：直接 Runtime.evaluate
+            // 主 frame，无 args：直接 Runtime.evaluate
             const params = {
                 expression,
                 returnByValue: true,
@@ -400,9 +343,9 @@ class UnifiedSessionManager {
             // timeout 即端到端预算，直接作为 RPC 超时（不额外加 margin）
             const result = await this.extensionBridge.debuggerSend('Runtime.evaluate', params, undefined, timeout);
             if (result.exceptionDetails) {
-                throw new Error(result.exceptionDetails.text);
+                throw new Error(formatCdpException(result.exceptionDetails));
             }
-            return result.result?.value;
+            return extractCdpValue(result.result);
         }
         return await this.extensionBridge.evaluate(expression, timeout, timeout);
     }
@@ -431,6 +374,106 @@ class UnifiedSessionManager {
         }
         return getCdpSession().evaluate('document.documentElement.outerHTML');
     }
+    /**
+     * 获取页面 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};
+        })()`);
+    }
+    /**
+     * 获取页面元信息
+     */
+    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
+            };
+        })()`);
+    }
+    /**
+     * 批量从浏览器缓存获取资源内容
+     *
+     * 只调用一次 Page.enable + Page.getFrameTree，然后逐个获取资源。
+     * 并发限制避免 CDP 连接拥塞。
+     */
+    async getResourceContentBatch(urls, concurrency = 6) {
+        const results = new Map();
+        if (urls.length === 0) {
+            return results;
+        }
+        try {
+            await this.sendCdpCommand('Page.enable');
+            const frameTree = await this.sendCdpCommand('Page.getFrameTree');
+            const frameId = frameTree.frameTree.frame.id;
+            // 并发控制
+            let idx = 0;
+            const next = async () => {
+                while (idx < urls.length) {
+                    const url = urls[idx++];
+                    try {
+                        const result = await this.sendCdpCommand('Page.getResourceContent', { frameId, url });
+                        results.set(url, result);
+                    }
+                    catch {
+                        // 单个资源获取失败不影响其他
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(concurrency, urls.length) }, () => next()));
+        }
+        catch {
+            // Page.enable 或 getFrameTree 失败，返回空结果
+        }
+        return results;
+    }
     /**
      * 查找元素
      *
@@ -438,6 +481,9 @@ class UnifiedSessionManager {
      * - 传入 timeout（轮询上下文）：isExtensionConnected() 快速失败，不会主动等待重连；
      *   仅在"预检通过但竞态断连落入 sendCommand"时才发生预算内的连接等待
      * - 不传 timeout（一次性调用）：ensureExtensionConnected() 允许等待重连（最多 30s）
+     * @param selector CSS 选择器
+     * @param text 文本内容
+     * @param xpath XPath 表达式
      * @param timeout 端到端预算（毫秒），包含连接等待和请求超时，传给 bridge.find → sendCommand
      */
     async find(selector, text, xpath, timeout) {
@@ -473,11 +519,13 @@ class UnifiedSessionManager {
         // CDP 模式：支持按字段过滤
         const urls = filter?.url ? [filter.url] : undefined;
         const cookies = await getCdpSession().getCookies(urls);
-        if (!filter)
+        if (!filter) {
             return cookies;
+        }
         return cookies.filter((c) => {
-            if (filter.name && c.name !== filter.name)
+            if (filter.name && c.name !== filter.name) {
                 return false;
+            }
             if (filter.domain) {
                 // 域名匹配：精确匹配或子域匹配（.example.com 匹配 sub.example.com）
                 const filterDomain = filter.domain.replace(/^\./, '');
@@ -486,15 +534,18 @@ class UnifiedSessionManager {
                     return false;
                 }
             }
-            if (filter.path && c.path !== filter.path)
+            if (filter.path && c.path !== filter.path) {
                 return false;
-            if (filter.secure !== undefined && c.secure !== filter.secure)
+            }
+            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)
+                if (filter.session !== isSession) {
                     return false;
+                }
             }
             return true;
         });
@@ -645,25 +696,6 @@ class UnifiedSessionManager {
         // CDP 模式下需要 attach 到目标 target
         await getCdpSession().attachToTarget(targetId);
     }
-    /**
-     * 串行化所有 tab 切换操作，防止并发请求互相覆盖 currentTabId。
-     * 调用者：selectPage/activatePage/newPage/closePage/navigate/reload/launch/withTabId。
-     *
-     * 注意：此锁不可重入。fn() 内禁止调用任何使用 withTabLock 的方法，否则会死锁。
-     * 当前所有 fn() 只调用 bridge 的原子操作（createTab/navigate/evaluate 等），不存在此问题。
-     */
-    async withTabLock(fn) {
-        const previousLock = this.tabSwitchLock;
-        let releaseLock;
-        this.tabSwitchLock = new Promise(resolve => { releaseLock = resolve; });
-        try {
-            await previousLock;
-            return await fn();
-        }
-        finally {
-            releaseLock();
-        }
-    }
     /**
      * 临时切换操作目标 tab，执行完后恢复
      *
@@ -675,8 +707,9 @@ class UnifiedSessionManager {
      */
     async withTabId(tabId, fn) {
         // Extension 未连接时不需要锁和 tab 切换（CDP 模式无 currentTabId 竞态）
-        if (!this.extensionBridge?.isConnected())
+        if (!this.extensionBridge?.isConnected()) {
             return fn();
+        }
         if (!tabId) {
             // 不切换 tab，但需要加锁保护 currentTabId 不被并发修改
             return this.withTabLock(fn);
@@ -707,21 +740,25 @@ class UnifiedSessionManager {
      * withTabId(tabId, () => withFrame(frame, () => { ... }))
      */
     async withFrame(frame, fn) {
-        if (frame === undefined)
+        if (frame === undefined) {
             return fn();
+        }
         if (!this.extensionBridge?.isConnected()) {
             throw new Error('iframe 穿透需要 Extension 模式');
         }
-        const { frameId } = await this.extensionBridge.resolveFrame(frame);
+        const { frameId, offset } = await this.extensionBridge.resolveFrame(frame);
         const previousFrameId = this.extensionBridge.getCurrentFrameId();
+        const previousFrameOffset = this.currentFrameOffset;
         const previousRequireExtension = this.requireExtension;
         this.extensionBridge.setCurrentFrameId(frameId);
+        this.currentFrameOffset = offset;
         this.requireExtension = true;
         try {
             return await fn();
         }
         finally {
             this.requireExtension = previousRequireExtension;
+            this.currentFrameOffset = previousFrameOffset;
             this.extensionBridge.setCurrentFrameId(previousFrameId);
         }
     }
@@ -745,29 +782,19 @@ class UnifiedSessionManager {
         }
         await getCdpSession().close();
     }
-    /**
-     * 解析 tab ID 字符串为数字，校验 NaN
-     */
-    parseTabId(id) {
-        const tabId = parseInt(id, 10);
-        if (isNaN(tabId)) {
-            throw new Error(`无效的 Tab ID: ${id}`);
-        }
-        return tabId;
-    }
-    // ==================== 键鼠输入 ====================
-    // stealth 模式：使用 JS 事件模拟，不触发调试提示，推荐用于反检测场景
-    // precise 模式：使用 debugger API，精确但会显示"扩展程序正在调试此浏览器"
     /**
      * 按下键盘按键
      */
     async keyDown(key) {
+        if (MODIFIER_KEYS[key]) {
+            this.modifiers |= MODIFIER_KEYS[key];
+        }
         if (await this.ensureExtensionConnected()) {
             if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthKey(key, 'down');
+                await this.extensionBridge.stealthKey(key, 'down', this.getModifierNames());
             }
             else {
-                await this.extensionBridge.inputKey('keyDown', { key, code: key });
+                await this.extensionBridge.inputKey('keyDown', { key, code: key, modifiers: this.modifiers });
             }
             return;
         }
@@ -779,13 +806,19 @@ class UnifiedSessionManager {
     async keyUp(key) {
         if (await this.ensureExtensionConnected()) {
             if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthKey(key, 'up');
+                await this.extensionBridge.stealthKey(key, 'up', this.getModifierNames());
             }
             else {
-                await this.extensionBridge.inputKey('keyUp', { key, code: key });
+                await this.extensionBridge.inputKey('keyUp', { key, code: key, modifiers: this.modifiers });
+            }
+            if (MODIFIER_KEYS[key]) {
+                this.modifiers &= ~MODIFIER_KEYS[key];
             }
             return;
         }
+        if (MODIFIER_KEYS[key]) {
+            this.modifiers &= ~MODIFIER_KEYS[key];
+        }
         await getCdpSession().keyUp(key);
     }
     /**
@@ -813,7 +846,7 @@ class UnifiedSessionManager {
                 await this.extensionBridge.stealthMouse('mousemove', x, y);
             }
             else {
-                await this.extensionBridge.inputMouse('mouseMoved', x, y);
+                await this.extensionBridge.inputMouse('mouseMoved', x, y, { modifiers: this.modifiers });
             }
             return;
         }
@@ -830,7 +863,11 @@ class UnifiedSessionManager {
                 await this.extensionBridge.stealthMouse('mousedown', x, y, effectiveButton);
             }
             else {
-                await this.extensionBridge.inputMouse('mousePressed', x, y, { button: effectiveButton, clickCount: 1 });
+                await this.extensionBridge.inputMouse('mousePressed', x, y, {
+                    button: effectiveButton,
+                    clickCount: 1,
+                    modifiers: this.modifiers,
+                });
             }
             return;
         }
@@ -847,40 +884,41 @@ class UnifiedSessionManager {
                 await this.extensionBridge.stealthMouse('mouseup', x, y, effectiveButton);
             }
             else {
-                await this.extensionBridge.inputMouse('mouseReleased', x, y, { button: effectiveButton });
+                await this.extensionBridge.inputMouse('mouseReleased', x, y, { button: effectiveButton, clickCount: 1, modifiers: this.modifiers });
             }
             return;
         }
         await getCdpSession().mouseUp(effectiveButton);
     }
     /**
-     * 鼠标滚轮
+     * 鼠标点击（mousedown + mouseup + click 三合一）
+     *
+     * stealth 模式：原子操作（单次脚本注入完成 mouseover → mousedown → focus → mouseup → click）
+     * precise / CDP 模式：mouseDown + mouseUp，浏览器自动合成原生 click 事件
      */
-    async mouseWheel(deltaX, deltaY) {
-        if (await this.ensureExtensionConnected()) {
+    async mouseClick(button = 'left') {
+        if (this.inputMode === 'stealth' && await this.ensureExtensionConnected()) {
+            const effectiveButton = (button === 'back' || button === 'forward') ? 'left' : button;
             const { x, y } = this.currentMousePosition;
-            await this.extensionBridge.inputMouse('mouseWheel', x, y, { deltaX, deltaY });
+            await this.extensionBridge.stealthClick(x, y, effectiveButton);
             return;
         }
-        await getCdpSession().mouseWheel(deltaX, deltaY);
+        await this.mouseDown(button);
+        await this.mouseUp(button);
     }
+    // ==================== 键鼠输入 ====================
+    // stealth 模式：使用 JS 事件模拟，不触发调试提示，推荐用于反检测场景
+    // precise 模式：使用 debugger API，精确但会显示"扩展程序正在调试此浏览器"
     /**
-     * 点击（stealth 模式专用）
+     * 鼠标滚轮
      */
-    async clickAt(x, y, button = 'left') {
+    async mouseWheel(deltaX, deltaY) {
         if (await this.ensureExtensionConnected()) {
-            if (this.inputMode === 'stealth') {
-                await this.extensionBridge.stealthClick(x, y, button);
-            }
-            else {
-                await this.extensionBridge.inputMouse('mousePressed', x, y, { button: button, clickCount: 1 });
-                await this.extensionBridge.inputMouse('mouseReleased', x, y, { button: button });
-            }
+            const { x, y } = this.currentMousePosition;
+            await this.extensionBridge.inputMouse('mouseWheel', x, y, { deltaX, deltaY, modifiers: this.modifiers });
             return;
         }
-        await getCdpSession().mouseMove(x, y);
-        await getCdpSession().mouseDown(button);
-        await getCdpSession().mouseUp(button);
+        await getCdpSession().mouseWheel(deltaX, deltaY);
     }
     /**
      * 注入反检测脚本
@@ -922,7 +960,6 @@ class UnifiedSessionManager {
         }
         await getCdpSession().touchEnd();
     }
-    // ==================== 控制台日志 ====================
     /**
      * 启用控制台日志捕获
      */
@@ -943,16 +980,6 @@ class UnifiedSessionManager {
         // CDP 模式需要单独实现
         return [];
     }
-    /**
-     * 清除控制台日志
-     */
-    async clearConsoleLogs() {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.consoleClear();
-            return;
-        }
-    }
-    // ==================== 网络日志 ====================
     /**
      * 启用网络日志捕获
      */
@@ -972,16 +999,6 @@ class UnifiedSessionManager {
         }
         return [];
     }
-    /**
-     * 清除网络日志
-     */
-    async clearNetworkLogs() {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.networkClear();
-            return;
-        }
-    }
-    // ==================== Debugger 直接访问 ====================
     /**
      * 发送 CDP 命令（高级用法）
      *
@@ -1000,6 +1017,150 @@ class UnifiedSessionManager {
         }
         return getCdpSession().send(method, params);
     }
+    /** 获取当前修饰键名称数组（stealth 模式用） */
+    getModifierNames() {
+        const names = [];
+        if (this.modifiers & 1) {
+            names.push('alt');
+        }
+        if (this.modifiers & 2) {
+            names.push('ctrl');
+        }
+        if (this.modifiers & 4) {
+            names.push('meta');
+        }
+        if (this.modifiers & 8) {
+            names.push('shift');
+        }
+        return names;
+    }
+    // ==================== 控制台日志 ====================
+    /**
+     * 检查 CDP 回退是否允许
+     *
+     * 当 requireExtension 为 true（tabId 或 frame 已指定）时，CDP 回退会操作错误目标，必须阻止。
+     * 允许时返回 false（供 ensureExtensionConnected 直接返回），不允许时抛出。
+     */
+    assertCdpFallbackAllowed() {
+        if (this.requireExtension) {
+            throw new Error('Extension 已断开，当前操作需要 Extension（指定 tabId 或 frame）时不可回退 CDP（操作目标不一致）');
+        }
+        return false;
+    }
+    /**
+     * 确保 Extension 已连接，如果断开则等待重连
+     * 返回 true 表示 Extension 可用，false 表示应 fallback 到 CDP
+     *
+     * 设计理念：Server 和 Extension 的启动时机完全独立，无任何要求。
+     * - 先装 Extension，一个月/一年后启动 Server → 能连上
+     * - 先启动 Server，再打开 Chrome → 能连上
+     * - 关闭再打开任何一方 → 能自动重连
+     *
+     * 超时设为 30 秒：足够等待 Extension 启动，但不会永远卡住。
+     *
+     * @param maxWait 调用方的端到端预算（毫秒）。传入时取 min(maxWait, 30000) 作为连接等待上限，
+     *               避免工具 timeout 被连接等待吞掉。不传则使用默认 30s。
+     */
+    async ensureExtensionConnected(maxWait) {
+        if (!this.extensionBridge) {
+            return this.assertCdpFallbackAllowed();
+        }
+        if (this.extensionBridge.isConnected()) {
+            return true;
+        }
+        // CDP 已连接时跳过 Extension 等待，直接使用 CDP 回退
+        if (getCdpSession().isConnected()) {
+            return this.assertCdpFallbackAllowed();
+        }
+        // 冷却期内不重复等待，避免每次操作都阻塞 30 秒
+        if (Date.now() - this.lastConnectionFailure < UnifiedSessionManager.CONNECTION_COOLDOWN) {
+            return this.assertCdpFallbackAllowed();
+        }
+        // Extension 服务器已启动但断开连接，等待重连
+        const waitTimeout = maxWait !== undefined ? Math.min(maxWait, 30000) : 30000;
+        if (waitTimeout <= 0) {
+            return this.assertCdpFallbackAllowed();
+        }
+        console.error(`[MCP] Waiting for Chrome Extension connection (${waitTimeout}ms timeout)...`);
+        console.error('[MCP] Please ensure Chrome is running with MCP Chrome extension installed.');
+        const connected = await this.extensionBridge.waitForConnection(waitTimeout);
+        if (connected) {
+            console.error('[MCP] Chrome Extension connected successfully');
+            this.lastConnectionFailure = 0;
+            return true;
+        }
+        console.error('[MCP] Chrome Extension connection timeout');
+        this.lastConnectionFailure = Date.now();
+        return this.assertCdpFallbackAllowed();
+    }
+    // ==================== 网络日志 ====================
+    /**
+     * 通过 callFunctionOn 执行函数调用
+     *
+     * 参数通过 CDP 协议结构化传递，避免大 payload 字符串拼接导致的长度限制和转义问题。
+     * 要求 code 必须是函数表达式（如 "(x) => x + 1"）。
+     */
+    async callFunctionOn(code, args, timeout) {
+        const globalResult = await this.extensionBridge.debuggerSend('Runtime.evaluate', {
+            expression: 'globalThis',
+            returnByValue: false,
+        }, undefined, timeout);
+        try {
+            const params = {
+                functionDeclaration: code,
+                objectId: globalResult.result.objectId,
+                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);
+            if (result.exceptionDetails) {
+                throw new Error(formatCdpException(result.exceptionDetails));
+            }
+            return extractCdpValue(result.result);
+        }
+        finally {
+            this.extensionBridge.debuggerSend('Runtime.releaseObject', {
+                objectId: globalResult.result.objectId,
+            }).catch(() => {
+            });
+        }
+    }
+    /**
+     * 串行化所有 tab 切换操作，防止并发请求互相覆盖 currentTabId。
+     * 调用者：selectPage/activatePage/newPage/closePage/navigate/reload/launch/withTabId。
+     *
+     * 注意：此锁不可重入。fn() 内禁止调用任何使用 withTabLock 的方法，否则会死锁。
+     * 当前所有 fn() 只调用 bridge 的原子操作（createTab/navigate/evaluate 等），不存在此问题。
+     */
+    async withTabLock(fn) {
+        const previousLock = this.tabSwitchLock;
+        let releaseLock;
+        this.tabSwitchLock = new Promise(resolve => {
+            releaseLock = resolve;
+        });
+        try {
+            await previousLock;
+            return await fn();
+        }
+        finally {
+            releaseLock();
+        }
+    }
+    // ==================== Debugger 直接访问 ====================
+    /**
+     * 解析 tab ID 字符串为数字，校验 NaN
+     */
+    parseTabId(id) {
+        const tabId = parseInt(id, 10);
+        if (isNaN(tabId)) {
+            throw new Error(`无效的 Tab ID: ${id}`);
+        }
+        return tabId;
+    }
 }
 /**
  * 获取统一会话管理器实例