@pyrokine/mcp-chrome 1.0.0 → 1.1.0

package/dist/core/unified-session.js

@@ -0,0 +1,1010 @@
+/**
+ * 统一会话管理器
+ *
+ * 支持两种模式：
+ * 1. Extension 模式：通过 Chrome Extension 操作用户浏览器（推荐）
+ * 2. CDP 模式：通过 Chrome DevTools Protocol 操作（Fallback）
+ */
+import { ExtensionBridge } from '../extension/index.js';
+import { getSession as getCdpSession } from './session.js';
+class UnifiedSessionManager {
+    static instance;
+    static CONNECTION_COOLDOWN = 30000; // 连接失败后 30 秒内不重试
+    extensionBridge = null;
+    inputMode = 'precise'; // 默认使用 precise 模式，可绕过 CSP 限制
+    currentMousePosition = { x: 0, y: 0 }; // 跟踪鼠标位置
+    lastConnectionFailure = 0;
+    tabSwitchLock = Promise.resolve(); // 串行化 tab 切换，防止并发竞态
+    requireExtension = false; // 指定 tabId 或 frame 时为 true，禁止 CDP 回退
+    constructor() { }
+    static getInstance() {
+        if (!UnifiedSessionManager.instance) {
+            UnifiedSessionManager.instance = new UnifiedSessionManager();
+        }
+        return UnifiedSessionManager.instance;
+    }
+    /**
+     * 启动 Unix Socket 服务器，等待 Native Host 连接
+     */
+    async startExtensionServer() {
+        if (this.extensionBridge) {
+            return; // 已经启动
+        }
+        this.extensionBridge = new ExtensionBridge();
+        try {
+            await this.extensionBridge.start();
+            console.error(`[MCP] Extension HTTP server listening on port ${this.extensionBridge.getPort()}`);
+        }
+        catch (error) {
+            console.error('[MCP] Failed to start Extension server:', error);
+            this.extensionBridge = null;
+        }
+    }
+    /**
+     * 获取当前连接模式
+     */
+    getMode() {
+        if (this.extensionBridge?.isConnected()) {
+            return 'extension';
+        }
+        if (getCdpSession().isConnected()) {
+            return 'cdp';
+        }
+        return 'none';
+    }
+    /**
+     * 获取当前输入模式
+     */
+    getInputMode() {
+        return this.inputMode;
+    }
+    /**
+     * 获取当前鼠标位置
+     */
+    getMousePosition() {
+        return { ...this.currentMousePosition };
+    }
+    /**
+     * 设置输入模式
+     * @param mode 'stealth' - JS 事件模拟（推荐，不触发调试提示）
+     *             'precise' - debugger API（精确但会有调试提示）
+     */
+    setInputMode(mode) {
+        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 模式（不管当前是否连接）
+     * 用于判断应该使用哪种模式
+     */
+    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 连接
+     */
+    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);
+            });
+            return {
+                targetId: String(tab.id),
+                type: 'page',
+                url: tab.url,
+                title: tab.title,
+                mode: 'extension',
+            };
+        }
+        // Fallback 到 CDP 模式
+        const target = await getCdpSession().launch(options);
+        return {
+            ...target,
+            mode: 'cdp',
+        };
+    }
+    /**
+     * 连接到已运行的浏览器（CDP 模式）
+     */
+    async connect(options) {
+        const target = await getCdpSession().connect(options);
+        return {
+            ...target,
+            mode: 'cdp',
+        };
+    }
+    /**
+     * 列出所有页面
+     */
+    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,
+            }));
+        }
+        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 [];
+    }
+    /**
+     * 导航到 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);
+    }
+    /**
+     * 后退
+     */
+    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);
+    }
+    /**
+     * 前进
+     */
+    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);
+    }
+    /**
+     * 刷新
+     */
+    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);
+    }
+    /**
+     * 读取页面（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,
+        };
+    }
+    /**
+     * 截图
+     */
+    async screenshot(options) {
+        if (await this.ensureExtensionConnected()) {
+            const result = await this.extensionBridge.screenshot(options);
+            return result.data;
+        }
+        return getCdpSession().screenshot(options?.fullPage);
+    }
+    /**
+     * 点击元素
+     */
+    async click(refId) {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.click(refId);
+            return;
+        }
+        // CDP 模式需要通过 Locator
+        throw new Error('CDP 模式下请使用 input 工具的 click action');
+    }
+    /**
+     * 输入文本
+     */
+    async type(refId, text, clear = false) {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.type(refId, text, clear);
+            return;
+        }
+        throw new Error('CDP 模式下请使用 input 工具');
+    }
+    /**
+     * 滚动
+     */
+    async scroll(x, y, refId) {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.scroll(x, y, refId);
+            return;
+        }
+        await getCdpSession().mouseWheel(x, y);
+    }
+    /**
+     * 执行 JavaScript
+     *
+     * 双路径策略（同 find()）：
+     * - 传入 timeout（轮询上下文）：isExtensionConnected() 快速失败，端到端预算受控
+     * - 不传 timeout（一次性调用）：ensureExtensionConnected() 允许等待重连（最多 30s）
+     *
+     * stealth 模式：使用 chrome.scripting.executeScript（受 CSP 限制）
+     * precise 模式：使用 debugger API Runtime.evaluate（可绕过 CSP）
+     *
+     * 使用 args 时 script 必须是函数表达式，会被包装为 IIFE：(script)(arg1, arg2, ...)
+     * @param timeout 端到端预算（毫秒），同时作为脚本执行超时和 sendCommand 的端到端预算
+     */
+    async evaluate(code, mode, timeout, args) {
+        const effectiveMode = mode ?? this.inputMode;
+        // 检测裸 return 语句，自动包裹 IIFE
+        // 排除已经是函数表达式或 IIFE 的情况
+        let expression = code;
+        if (/\breturn\b/.test(code) && !/^\s*([(\[]|function\b|async\b|class\b)/.test(code)) {
+            expression = `(() => { ${code} })()`;
+        }
+        if (args && args.length > 0) {
+            const argsStr = args.map(a => JSON.stringify(a)).join(', ');
+            expression = `(${code})(${argsStr})`;
+        }
+        if (timeout !== undefined) {
+            // 轮询上下文：快速失败，端到端预算受控
+            if (!this.isExtensionConnected()) {
+                this.assertCdpFallbackAllowed();
+                return getCdpSession().evaluate(code, args, timeout);
+            }
+        }
+        else {
+            // 非轮询上下文：允许等待重连；连接失败时回退 CDP
+            if (!(await this.ensureExtensionConnected())) {
+                return getCdpSession().evaluate(code, args, timeout);
+            }
+        }
+        // Extension 路径
+        const currentFrameId = this.extensionBridge.getCurrentFrameId();
+        if (effectiveMode === 'precise') {
+            if (currentFrameId !== 0) {
+                // iframe 上下文：通过 evaluateInFrame 使用 contextId 精确定位
+                const result = await this.extensionBridge.evaluateInFrame(currentFrameId, expression, timeout);
+                if (result.exceptionDetails) {
+                    throw new Error(result.exceptionDetails.text);
+                }
+                return result.result?.value;
+            }
+            // 主 frame：直接 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);
+            if (result.exceptionDetails) {
+                throw new Error(result.exceptionDetails.text);
+            }
+            return result.result?.value;
+        }
+        return await this.extensionBridge.evaluate(expression, timeout, timeout);
+    }
+    /**
+     * 获取页面文本
+     */
+    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');
+    }
+    /**
+     * 获取页面 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');
+    }
+    /**
+     * 查找元素
+     *
+     * 双路径策略（约束：轮询/预算敏感调用必须传 timeout；一次性调用不传 timeout）：
+     * - 传入 timeout（轮询上下文）：isExtensionConnected() 快速失败，不会主动等待重连；
+     *   仅在"预检通过但竞态断连落入 sendCommand"时才发生预算内的连接等待
+     * - 不传 timeout（一次性调用）：ensureExtensionConnected() 允许等待重连（最多 30s）
+     * @param timeout 端到端预算（毫秒），包含连接等待和请求超时，传给 bridge.find → sendCommand
+     */
+    async find(selector, text, xpath, timeout) {
+        if (timeout !== undefined) {
+            // 轮询上下文：快速失败，端到端预算受控
+            if (this.isExtensionConnected()) {
+                return this.extensionBridge.find(selector, text, xpath, timeout);
+            }
+            throw new Error('Extension 未连接');
+        }
+        // 非轮询上下文：允许等待重连
+        if (await this.ensureExtensionConnected()) {
+            return this.extensionBridge.find(selector, text, xpath);
+        }
+        throw new Error('Extension 未连接');
+    }
+    /**
+     * 获取元素属性
+     */
+    async getAttribute(selector, refId, attribute) {
+        if (await this.ensureExtensionConnected()) {
+            return this.extensionBridge.getAttribute(selector, refId, attribute);
+        }
+        throw new Error('CDP 模式下请使用 extract 工具');
+    }
+    /**
+     * 获取 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;
+        });
+    }
+    /**
+     * 设置 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);
+    }
+    /**
+     * 删除 Cookie
+     */
+    async deleteCookie(url, name) {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.deleteCookie(url, name);
+            return;
+        }
+        await getCdpSession().deleteCookie(name, url);
+    }
+    /**
+     * 清空 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 };
+    }
+    /**
+     * 创建新页面
+     */
+    async newPage(url) {
+        if (await this.ensureExtensionConnected()) {
+            // createTab 会设置 currentTabId，需要加锁
+            const tab = await this.withTabLock(async () => {
+                return this.extensionBridge.createTab(url);
+            });
+            return {
+                targetId: String(tab.id),
+                type: 'page',
+                url: tab.url,
+                title: tab.title,
+            };
+        }
+        const target = await getCdpSession().newPage();
+        if (url) {
+            await getCdpSession().navigate(url);
+        }
+        return target;
+    }
+    /**
+     * 关闭页面
+     */
+    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;
+        }
+        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;
+        }
+        // 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;
+        }
+        // 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，执行完后恢复
+     *
+     * 用于多 tab 并行场景：指定 tabId 时临时切换到该 tab 执行操作，
+     * 不影响 browse attach 设置的默认 tab。
+     *
+     * 即使不传 tabId，也需要加锁：fn() 内调用 bridge 方法会读取 currentTabId，
+     * 不加锁则并发的 withTabId(someId, ...) 可能在 fn() 执行中途修改 currentTabId。
+     */
+    async withTabId(tabId, fn) {
+        // Extension 未连接时不需要锁和 tab 切换（CDP 模式无 currentTabId 竞态）
+        if (!this.extensionBridge?.isConnected())
+            return fn();
+        if (!tabId) {
+            // 不切换 tab，但需要加锁保护 currentTabId 不被并发修改
+            return this.withTabLock(fn);
+        }
+        const numericTabId = this.parseTabId(tabId);
+        return this.withTabLock(async () => {
+            const previousTabId = this.extensionBridge.getCurrentTabId();
+            this.extensionBridge.setCurrentTabId(numericTabId);
+            // tabId 明确指定时，禁止 CDP 回退（CDP 不感知 Extension tab）
+            const previousRequireExtension = this.requireExtension;
+            this.requireExtension = true;
+            try {
+                return await fn();
+            }
+            finally {
+                this.requireExtension = previousRequireExtension;
+                this.extensionBridge.setCurrentTabId(previousTabId);
+            }
+        });
+    }
+    /**
+     * 临时切换操作目标 iframe，执行完后恢复
+     *
+     * frame 支持 CSS 选择器（如 "iframe#main"）或索引（如 0）。
+     * 内部通过 Extension 的 resolveFrame 将选择器解析为 Chrome frameId。
+     *
+     * 与 withTabId 配合使用时，应嵌套在 withTabId 内部：
+     * withTabId(tabId, () => withFrame(frame, () => { ... }))
+     */
+    async withFrame(frame, fn) {
+        if (frame === undefined)
+            return fn();
+        if (!this.extensionBridge?.isConnected()) {
+            throw new Error('iframe 穿透需要 Extension 模式');
+        }
+        const { frameId } = await this.extensionBridge.resolveFrame(frame);
+        const previousFrameId = this.extensionBridge.getCurrentFrameId();
+        const previousRequireExtension = this.requireExtension;
+        this.extensionBridge.setCurrentFrameId(frameId);
+        this.requireExtension = true;
+        try {
+            return await fn();
+        }
+        finally {
+            this.requireExtension = previousRequireExtension;
+            this.extensionBridge.setCurrentFrameId(previousFrameId);
+        }
+    }
+    /**
+     * 获取当前状态
+     */
+    getState() {
+        if (this.extensionBridge?.isConnected()) {
+            return this.extensionBridge.getState();
+        }
+        const cdpState = getCdpSession().getState();
+        return cdpState ? { url: cdpState.url, title: cdpState.title } : null;
+    }
+    /**
+     * 关闭所有连接
+     */
+    async close() {
+        if (this.extensionBridge) {
+            await this.extensionBridge.stop();
+            this.extensionBridge = null;
+        }
+        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 (await this.ensureExtensionConnected()) {
+            if (this.inputMode === 'stealth') {
+                await this.extensionBridge.stealthKey(key, 'down');
+            }
+            else {
+                await this.extensionBridge.inputKey('keyDown', { key, code: key });
+            }
+            return;
+        }
+        await getCdpSession().keyDown(key);
+    }
+    /**
+     * 释放键盘按键
+     */
+    async keyUp(key) {
+        if (await this.ensureExtensionConnected()) {
+            if (this.inputMode === 'stealth') {
+                await this.extensionBridge.stealthKey(key, 'up');
+            }
+            else {
+                await this.extensionBridge.inputKey('keyUp', { key, code: key });
+            }
+            return;
+        }
+        await getCdpSession().keyUp(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;
+        }
+        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);
+            }
+            return;
+        }
+        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 });
+            }
+            return;
+        }
+        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 });
+            }
+            return;
+        }
+        await getCdpSession().mouseUp(effectiveButton);
+    }
+    /**
+     * 鼠标滚轮
+     */
+    async mouseWheel(deltaX, deltaY) {
+        if (await this.ensureExtensionConnected()) {
+            const { x, y } = this.currentMousePosition;
+            await this.extensionBridge.inputMouse('mouseWheel', x, y, { deltaX, deltaY });
+            return;
+        }
+        await getCdpSession().mouseWheel(deltaX, deltaY);
+    }
+    /**
+     * 点击（stealth 模式专用）
+     */
+    async clickAt(x, y, button = 'left') {
+        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 });
+            }
+            return;
+        }
+        await getCdpSession().mouseMove(x, y);
+        await getCdpSession().mouseDown(button);
+        await getCdpSession().mouseUp(button);
+    }
+    /**
+     * 注入反检测脚本
+     */
+    async injectStealth() {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.stealthInject();
+            return;
+        }
+        throw new Error('CDP 模式下 stealth 脚本在 connect/launch 时通过 stealth 参数自动注入，不支持后续手动注入');
+    }
+    /**
+     * 触摸开始
+     */
+    async touchStart(x, y) {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.inputTouch('touchStart', [{ x, y, id: 0 }]);
+            return;
+        }
+        await getCdpSession().touchStart(x, y);
+    }
+    /**
+     * 触摸移动
+     */
+    async touchMove(x, y) {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.inputTouch('touchMove', [{ x, y, id: 0 }]);
+            return;
+        }
+        await getCdpSession().touchMove(x, y);
+    }
+    /**
+     * 触摸结束
+     */
+    async touchEnd() {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.inputTouch('touchEnd', []);
+            return;
+        }
+        await getCdpSession().touchEnd();
+    }
+    // ==================== 控制台日志 ====================
+    /**
+     * 启用控制台日志捕获
+     */
+    async enableConsole() {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.consoleEnable();
+            return;
+        }
+        // CDP 模式已经在 logs 工具中实现
+    }
+    /**
+     * 获取控制台日志
+     */
+    async getConsoleLogs(options = {}) {
+        if (await this.ensureExtensionConnected()) {
+            return this.extensionBridge.consoleGet(options);
+        }
+        // CDP 模式需要单独实现
+        return [];
+    }
+    /**
+     * 清除控制台日志
+     */
+    async clearConsoleLogs() {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.consoleClear();
+            return;
+        }
+    }
+    // ==================== 网络日志 ====================
+    /**
+     * 启用网络日志捕获
+     */
+    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 [];
+    }
+    /**
+     * 清除网络日志
+     */
+    async clearNetworkLogs() {
+        if (await this.ensureExtensionConnected()) {
+            await this.extensionBridge.networkClear();
+            return;
+        }
+    }
+    // ==================== Debugger 直接访问 ====================
+    /**
+     * 发送 CDP 命令（高级用法）
+     *
+     * 自动识别 browser-level 域（Target、Browser、SystemInfo、DeviceAccess、IO）不携带 sessionId，
+     * 其他域默认携带 sessionId（page-level 命令）。
+     */
+    async sendCdpCommand(method, params) {
+        if (await this.ensureExtensionConnected()) {
+            return this.extensionBridge.debuggerSend(method, params);
+        }
+        // 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);
+        }
+        return getCdpSession().send(method, params);
+    }
+}
+/**
+ * 获取统一会话管理器实例
+ */
+export function getUnifiedSession() {
+    return UnifiedSessionManager.getInstance();
+}
+//# sourceMappingURL=unified-session.js.map