@pyrokine/mcp-chrome 1.7.0 → 2.0.1

package/dist/core/session.js

@@ -10,7 +10,8 @@
 import { BehaviorSimulator, getAntiDetectionScript } from '../anti-detection/index.js';
 import { BrowserLauncher, CDPClient, getBrowserWSEndpoint, getTargets } from '../cdp/index.js';
 import { AutoWait } from './auto-wait.js';
-import { NavigationTimeoutError, SessionNotFoundError, TargetNotFoundError } from './errors.js';
+import { DriverCapabilityError, } from './browser-driver.js';
+import { NavigationError, NavigationTimeoutError, SessionNotFoundError, TargetNotFoundError } from './errors.js';
 import { Locator } from './locator.js';
 import { DEFAULT_TIMEOUT, extractCdpValue, formatCdpException, MODIFIER_KEYS, } from './types.js';
 /**
@@ -37,8 +38,7 @@ class SessionManager {
     requestMap = new Map();
     // 监听器安装标志（防止重复安装）
     listenersInstalled = false;
-    constructor() {
-    }
+    constructor() { }
     /**
      * 获取当前调试端口
      */
@@ -54,8 +54,8 @@ class SessionManager {
     /**
      * 启动浏览器
      *
-     * 如果指定了端口，会先尝试连接该端口上已运行的浏览器。
-     * 只有连接失败时才启动新浏览器。
+     * 如果指定了端口，会先尝试连接该端口上已运行的浏览器，
+     * 只有连接失败时才启动新浏览器
      */
     async launch(options = {}) {
         return this.withLock(async () => {
@@ -172,10 +172,12 @@ class SessionManager {
         return targetInfos
             .filter((t) => t.type === 'page')
             .map((t) => ({
+            id: t.targetId,
             targetId: t.targetId,
-            type: t.type,
             url: t.url,
             title: t.title,
+            type: t.type,
+            active: t.targetId === this.currentTargetId,
         }));
     }
     /**
@@ -191,19 +193,20 @@ class SessionManager {
         return this.withLock(async () => {
             this.ensureSession();
             const { wait = 'load', timeout = DEFAULT_TIMEOUT } = options;
+            // networkidle：先注册监听器再 navigate，避免 navigate 返回和监听器注册之间的竞态窗口
+            // noinspection ES6MissingAwait — 故意不 await，Promise 在 navigate 完成后才消费
+            const networkIdlePromise = wait === 'networkidle' ? this.startNetworkIdleWatcher(timeout) : null;
             // 导航（传 timeout 防止 CDP 默认 30s 截断用户预算）
             const { errorText } = (await this.send('Page.navigate', { url }, timeout));
             if (errorText) {
-                throw new NavigationTimeoutError(url, timeout);
+                throw new NavigationError(url, errorText);
             }
             // 根据 wait 类型等待
-            if (wait === 'networkidle') {
-                await this.waitForNetworkIdle(timeout);
+            if (networkIdlePromise) {
+                await networkIdlePromise;
             }
             else {
-                const eventName = wait === 'domcontentloaded'
-                    ? 'Page.domContentEventFired'
-                    : 'Page.loadEventFired';
+                const eventName = wait === 'domcontentloaded' ? 'Page.domContentEventFired' : 'Page.loadEventFired';
                 await this.cdp.waitForEvent(eventName, undefined, timeout);
             }
             // 更新状态
@@ -213,72 +216,11 @@ class SessionManager {
     /**
      * 等待网络空闲（无进行中的请求且持续指定时间）
      *
-     * close() 时通过 'disconnected' 信号立即 reject，不必等 timer 超时。
+     * close() 时通过 'disconnected' 信号立即 reject，不必等 timer 超时
      */
     async waitForNetworkIdle(timeout, idleTime = 500) {
         this.ensureSession();
-        // 捕获当前 cdp 引用，防止 close() 并发置 null 导致回调崩溃
-        const cdp = this.cdp;
-        // 使用局部 Set 追踪本次等待的请求，避免污染成员变量
-        const localPendingRequests = new Set();
-        return new Promise((resolve, reject) => {
-            let idleTimer = null;
-            let timeoutTimer = null;
-            const checkIdle = () => {
-                if (localPendingRequests.size === 0) {
-                    if (idleTimer === null) {
-                        idleTimer = setTimeout(() => {
-                            cleanup();
-                            resolve();
-                        }, idleTime);
-                    }
-                }
-                else {
-                    if (idleTimer !== null) {
-                        clearTimeout(idleTimer);
-                        idleTimer = null;
-                    }
-                }
-            };
-            const onRequestStart = (params) => {
-                const { requestId } = params;
-                localPendingRequests.add(requestId);
-                checkIdle();
-            };
-            const onRequestEnd = (params) => {
-                const { requestId } = params;
-                localPendingRequests.delete(requestId);
-                checkIdle();
-            };
-            const cleanup = () => {
-                if (idleTimer !== null) {
-                    clearTimeout(idleTimer);
-                }
-                if (timeoutTimer !== null) {
-                    clearTimeout(timeoutTimer);
-                }
-                cdp.offEvent('Network.requestWillBeSent', onRequestStart);
-                cdp.offEvent('Network.loadingFinished', onRequestEnd);
-                cdp.offEvent('Network.loadingFailed', onRequestEnd);
-                cdp.removeListener('disconnected', onDisconnected);
-            };
-            // 超时处理
-            timeoutTimer = setTimeout(() => {
-                cleanup();
-                reject(new NavigationTimeoutError('networkidle', timeout));
-            }, timeout);
-            const onDisconnected = () => {
-                cleanup();
-                reject(new Error('CDP 连接已关闭'));
-            };
-            cdp.once('disconnected', onDisconnected);
-            // 监听网络事件
-            cdp.onEvent('Network.requestWillBeSent', onRequestStart);
-            cdp.onEvent('Network.loadingFinished', onRequestEnd);
-            cdp.onEvent('Network.loadingFailed', onRequestEnd);
-            // 初始检查
-            checkIdle();
-        });
+        return this.buildNetworkIdlePromise(this.cdp, timeout, idleTime);
     }
     /**
      * 等待导航完成（跨文档导航或同文档导航）
@@ -301,8 +243,7 @@ class SessionManager {
             const waitPromise = this.waitForAnyEvent(['Page.loadEventFired', 'Page.navigatedWithinDocument'], timeout);
             // 预注册 rejection handler：若 send() 抛错导致 waitPromise 永远不被 await，
             // 其 timer reject 不会成为 unhandled rejection（Node 20 默认会退出进程）
-            waitPromise.catch(() => {
-            });
+            waitPromise.catch(() => { });
             await this.send('Page.navigateToHistoryEntry', { entryId: entries[currentIndex - 1].id }, timeout);
             await waitPromise;
             await this.updateState();
@@ -321,8 +262,7 @@ class SessionManager {
             }
             // 跨文档导航触发 loadEventFired，同文档导航（hash/pushState）触发 navigatedWithinDocument
             const waitPromise = this.waitForAnyEvent(['Page.loadEventFired', 'Page.navigatedWithinDocument'], timeout);
-            waitPromise.catch(() => {
-            });
+            waitPromise.catch(() => { });
             await this.send('Page.navigateToHistoryEntry', { entryId: entries[currentIndex + 1].id }, timeout);
             await waitPromise;
             await this.updateState();
@@ -332,13 +272,11 @@ class SessionManager {
     /**
      * 刷新
      */
-    async reload(options = {}) {
+    async reload(ignoreCache = false, _waitUntil, timeout = DEFAULT_TIMEOUT) {
         return this.withLock(async () => {
             this.ensureSession();
-            const { ignoreCache = false, timeout = DEFAULT_TIMEOUT } = options;
             const waitPromise = this.cdp.waitForEvent('Page.loadEventFired', undefined, timeout);
-            waitPromise.catch(() => {
-            });
+            waitPromise.catch(() => { });
             await this.send('Page.reload', { ignoreCache }, timeout);
             await waitPromise;
             await this.updateState();
@@ -373,23 +311,26 @@ class SessionManager {
      */
     async mouseMove(x, y) {
         this.ensureSession();
+        // 整数点位：避免 sub-pixel 渲染时坐标命中元素边界外的情况（与 Playwright 一致）
+        const ix = Math.round(x);
+        const iy = Math.round(y);
         await this.send('Input.dispatchMouseEvent', {
             type: 'mouseMoved',
-            x,
-            y,
+            x: ix,
+            y: iy,
             modifiers: this.modifiers,
         });
-        this.behaviorSimulator.setCurrentPosition({ x, y });
+        this.behaviorSimulator.setCurrentPosition({ x: ix, y: iy });
     }
     /**
      * 鼠标按下
      */
-    async mouseDown(button = 'left') {
+    async mouseDown(button = 'left', clickCount = 1) {
         this.ensureSession();
         await this.send('Input.dispatchMouseEvent', {
             type: 'mousePressed',
             button,
-            clickCount: 1,
+            clickCount,
             x: this.behaviorSimulator.getCurrentPosition().x,
             y: this.behaviorSimulator.getCurrentPosition().y,
             modifiers: this.modifiers,
@@ -398,12 +339,12 @@ class SessionManager {
     /**
      * 鼠标释放
      */
-    async mouseUp(button = 'left') {
+    async mouseUp(button = 'left', clickCount = 1) {
         this.ensureSession();
         await this.send('Input.dispatchMouseEvent', {
             type: 'mouseReleased',
             button,
-            clickCount: 1,
+            clickCount,
             x: this.behaviorSimulator.getCurrentPosition().x,
             y: this.behaviorSimulator.getCurrentPosition().y,
             modifiers: this.modifiers,
@@ -426,18 +367,29 @@ class SessionManager {
     }
     /**
      * 键盘按下
+     *
+     * options.rawKeyDown=true 配合 options.autoRepeat=true 表示长按重复（与 Puppeteer 一致），
+     * 上层 unified-session 维护 pressedKeys Set 决定是否启用
      */
-    async keyDown(key) {
+    async keyDown(key, commands, options) {
         this.ensureSession();
         if (MODIFIER_KEYS[key]) {
             this.modifiers |= MODIFIER_KEYS[key];
         }
         const keyDefinition = getKeyDefinition(key);
-        await this.send('Input.dispatchKeyEvent', {
-            type: 'keyDown',
+        const params = {
+            type: options?.rawKeyDown ? 'rawKeyDown' : 'keyDown',
             modifiers: this.modifiers,
             ...keyDefinition,
-        });
+        };
+        if (commands && commands.length > 0) {
+            delete params.text;
+            params.commands = commands;
+        }
+        if (options?.autoRepeat) {
+            params.autoRepeat = true;
+        }
+        await this.send('Input.dispatchKeyEvent', params);
     }
     /**
      * 键盘释放
@@ -445,31 +397,57 @@ class SessionManager {
     async keyUp(key) {
         this.ensureSession();
         const keyDefinition = getKeyDefinition(key);
+        const nextModifiers = MODIFIER_KEYS[key] ? this.modifiers & ~MODIFIER_KEYS[key] : this.modifiers;
         await this.send('Input.dispatchKeyEvent', {
             type: 'keyUp',
-            modifiers: this.modifiers,
+            modifiers: nextModifiers,
             ...keyDefinition,
         });
-        if (MODIFIER_KEYS[key]) {
-            this.modifiers &= ~MODIFIER_KEYS[key];
-        }
+        this.modifiers = nextModifiers;
     }
     /**
      * 输入文本
      */
     async type(text, delay = 0) {
         this.ensureSession();
-        for (const char of text) {
-            await this.send('Input.dispatchKeyEvent', {
-                type: 'keyDown',
-                modifiers: this.modifiers,
-                text: char,
-            });
-            await this.send('Input.dispatchKeyEvent', {
-                type: 'keyUp',
-                modifiers: this.modifiers,
-                text: char,
-            });
+        // 归一化换行：\r\n 和 \r 都视作单个 \n
+        const normalized = text.replace(/\r\n?/g, '\n');
+        for (const char of normalized) {
+            if (char === '\n') {
+                // Enter 键：char 通道不接受 \n，必须分发 keyDown + char('\r') + keyUp
+                const enterParams = {
+                    key: 'Enter',
+                    code: 'Enter',
+                    windowsVirtualKeyCode: 13,
+                    nativeVirtualKeyCode: 13,
+                    modifiers: this.modifiers,
+                };
+                await this.send('Input.dispatchKeyEvent', {
+                    type: 'keyDown',
+                    ...enterParams,
+                });
+                await this.send('Input.dispatchKeyEvent', {
+                    type: 'char',
+                    text: '\r',
+                    ...enterParams,
+                });
+                await this.send('Input.dispatchKeyEvent', {
+                    type: 'keyUp',
+                    ...enterParams,
+                });
+            }
+            else {
+                await this.send('Input.dispatchKeyEvent', {
+                    type: 'keyDown',
+                    modifiers: this.modifiers,
+                    text: char,
+                });
+                await this.send('Input.dispatchKeyEvent', {
+                    type: 'keyUp',
+                    modifiers: this.modifiers,
+                    text: char,
+                });
+            }
             if (delay > 0) {
                 await new Promise((r) => setTimeout(r, delay));
             }
@@ -480,36 +458,28 @@ class SessionManager {
      */
     async touchStart(x, y) {
         this.ensureSession();
-        await this.send('Input.dispatchTouchEvent', {
-            type: 'touchStart',
-            touchPoints: [{ x, y }],
-        });
+        await this.dispatchTouch({ type: 'touchStart', touchPoints: [{ x, y }] });
     }
     /**
      * 触屏移动
      */
     async touchMove(x, y) {
         this.ensureSession();
-        await this.send('Input.dispatchTouchEvent', {
-            type: 'touchMove',
-            touchPoints: [{ x, y }],
-        });
+        await this.dispatchTouch({ type: 'touchMove', touchPoints: [{ x, y }] });
     }
     /**
      * 触屏结束
      */
     async touchEnd() {
         this.ensureSession();
-        await this.send('Input.dispatchTouchEvent', {
-            type: 'touchEnd',
-            touchPoints: [],
-        });
+        await this.dispatchTouch({ type: 'touchEnd', touchPoints: [] });
     }
     /**
      * 截图
      */
-    async screenshot(fullPage = false, scale, format, quality, clip) {
+    async screenshot(options = {}) {
         this.ensureSession();
+        const { fullPage = false, scale, format, quality, clip } = options;
         const effectiveFormat = format ?? 'png';
         const captureParams = { format: effectiveFormat };
         if (quality !== undefined && effectiveFormat !== 'png') {
@@ -520,11 +490,20 @@ class SessionManager {
         }
         if (fullPage) {
             // 获取页面完整高度
+            const sizeExpr = 'JSON.stringify({ width: document.documentElement.scrollWidth, ' +
+                'height: document.documentElement.scrollHeight })';
             const { result } = (await this.send('Runtime.evaluate', {
-                expression: 'JSON.stringify({ width: document.documentElement.scrollWidth, height: document.documentElement.scrollHeight })',
+                expression: sizeExpr,
                 returnByValue: true,
             }));
-            const { width, height } = JSON.parse(result.value);
+            let width, height;
+            try {
+                ;
+                ({ width, height } = JSON.parse(result.value));
+            }
+            catch {
+                throw new Error(`screenshot: 无法解析页面尺寸: ${result.value}`);
+            }
             // 设置视口
             await this.send('Emulation.setDeviceMetricsOverride', {
                 width,
@@ -534,14 +513,19 @@ class SessionManager {
             });
             try {
                 const { data } = (await this.send('Page.captureScreenshot', captureParams));
-                return data;
+                return { data, format: effectiveFormat };
             }
             finally {
-                await this.send('Emulation.clearDeviceMetricsOverride');
+                try {
+                    await this.send('Emulation.clearDeviceMetricsOverride');
+                }
+                catch {
+                    // cleanup failure, ignore to preserve original error
+                }
             }
         }
         const { data } = (await this.send('Page.captureScreenshot', captureParams));
-        return data;
+        return { data, format: effectiveFormat };
     }
     /**
      * 获取页面状态
@@ -594,62 +578,459 @@ class SessionManager {
         });
         return state;
     }
+    async getPageHtml(selector, outer = true) {
+        this.ensureSession();
+        if (selector) {
+            const prop = outer ? 'outerHTML' : 'innerHTML';
+            return this.evaluate(`((s, p) => { const el = document.querySelector(s); return el ? el[p] : '' })`, [selector, prop]);
+        }
+        return this.evaluate('document.documentElement.outerHTML');
+    }
+    /**
+     * 获取页面文本（IBrowserDriver 接口）
+     */
+    async getPageText(selector) {
+        this.ensureSession();
+        if (selector) {
+            return this.evaluate(`(s => document.querySelector(s)?.textContent || '')`, [selector]);
+        }
+        return this.evaluate('document.body.innerText');
+    }
+    // ==================== IBrowserDriver: 页面读取 ====================
+    /** Extension readPage 等价物：CDP 通过 getPageState 构造 pageContent 文本 */
+    async readPage(_options) {
+        const state = await this.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,
+        };
+    }
+    /** CDP 通过 evaluate 注入函数枚举 IMG */
+    async getHtmlWithImages(selector, outer = true) {
+        const selectorArg = JSON.stringify(selector ?? null);
+        return this.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};
+        })()`);
+    }
+    /** CDP 通过 evaluate 注入收集 meta 标签和 og/twitter/jsonLd */
+    async getMetadata() {
+        return this.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 = [];
+            var feedSel = 'link[type="application/rss+xml"],link[type="application/atom+xml"]';
+            document.querySelectorAll(feedSel).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
+            };
+        })()`);
+    }
+    // ==================== IBrowserDriver: 元素查找 ====================
+    /** CDP 通过 evaluate 注入 TreeWalker 查找元素 */
+    async find(selector, text, xpath, timeout) {
+        return this.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 if (text) {
+                // text-only：用 TreeWalker 仅遍历可能含目标文本的节点,避免 querySelectorAll('*') 的全树扫描和强制 layout
+                elements = [];
+                var lowerText = text;
+                var walker = document.createTreeWalker(
+                    document.body || document.documentElement,
+                    NodeFilter.SHOW_ELEMENT,
+                    {
+                    acceptNode: function (n) {
+                        var t = n.textContent || '';
+                        if (!t.includes(lowerText)) return NodeFilter.FILTER_SKIP;
+                        return NodeFilter.FILTER_ACCEPT;
+                    }
+                });
+                while (walker.nextNode()) {
+                    elements.push(walker.currentNode);
+                    if (elements.length >= 200) break;
+                }
+            } 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);
+    }
+    // ==================== IBrowserDriver: 元素操作（refId 类，CDP 不支持） ====================
+    click(_refId) {
+        return Promise.reject(new DriverCapabilityError('CDP 模式不支持 refId 点击,请使用 input 工具的坐标点击'));
+    }
+    actionableClick(_refId, _force) {
+        return Promise.reject(new DriverCapabilityError('actionableClick 仅支持 Extension 模式'));
+    }
+    dispatchInput(_refId, _text) {
+        return Promise.reject(new DriverCapabilityError('dispatchInput 仅支持 Extension 模式'));
+    }
+    dragAndDrop(_srcRefId, _dstRefId) {
+        return Promise.reject(new DriverCapabilityError('dragAndDrop 仅支持 Extension 模式'));
+    }
+    getComputedStyle(_refId, _prop) {
+        return Promise.reject(new DriverCapabilityError('getComputedStyle 仅支持 Extension 模式'));
+    }
+    typeRef(_refId, _text, _clear) {
+        return Promise.reject(new DriverCapabilityError('CDP 模式不支持 refId 输入,请使用 input 工具'));
+    }
+    /** scrollAt：CDP 模式没有 refId 概念,无视 refId 直接 mouseWheel（保持与原 unified-session 行为一致） */
+    async scrollAt(x, y, _refId) {
+        await this.mouseWheel(x, y);
+    }
+    async getAttribute(selector, refId, attribute) {
+        if (refId !== undefined) {
+            throw new DriverCapabilityError('CDP 模式不支持 refId 查询属性,请通过 selector');
+        }
+        if (!selector) {
+            throw new DriverCapabilityError('getAttribute 需要 selector');
+        }
+        return this.evaluate(`(s, a) => { const el = document.querySelector(s); return el ? el.getAttribute(a) : null }`, [selector, attribute]);
+    }
+    // ==================== IBrowserDriver: 输入（precise） ====================
+    /** CDP 通用 inputKey 接口实现：直接转发 Input.dispatchKeyEvent，不维护 modifiers（由调用方提供） */
+    async inputKey(type, options = {}) {
+        this.ensureSession();
+        const params = { type };
+        if (options.key !== undefined) {
+            params.key = options.key;
+        }
+        if (options.code !== undefined) {
+            params.code = options.code;
+        }
+        if (options.text !== undefined) {
+            params.text = options.text;
+        }
+        if (options.unmodifiedText !== undefined) {
+            params.unmodifiedText = options.unmodifiedText;
+        }
+        if (options.location !== undefined) {
+            params.location = options.location;
+        }
+        if (options.isKeypad !== undefined) {
+            params.isKeypad = options.isKeypad;
+        }
+        if (options.autoRepeat !== undefined) {
+            params.autoRepeat = options.autoRepeat;
+        }
+        if (options.windowsVirtualKeyCode !== undefined) {
+            params.windowsVirtualKeyCode = options.windowsVirtualKeyCode;
+        }
+        if (options.modifiers !== undefined) {
+            params.modifiers = options.modifiers;
+        }
+        if (options.commands && options.commands.length > 0) {
+            params.commands = options.commands;
+        }
+        await this.send('Input.dispatchKeyEvent', params);
+    }
+    /** CDP 通用 inputMouse 接口实现：直接转发 Input.dispatchMouseEvent */
+    async inputMouse(type, x, y, options = {}) {
+        this.ensureSession();
+        const params = {
+            type,
+            x: Math.round(x),
+            y: Math.round(y),
+        };
+        if (options.button !== undefined) {
+            params.button = options.button;
+        }
+        if (options.clickCount !== undefined) {
+            params.clickCount = options.clickCount;
+        }
+        if (options.deltaX !== undefined) {
+            params.deltaX = options.deltaX;
+        }
+        if (options.deltaY !== undefined) {
+            params.deltaY = options.deltaY;
+        }
+        if (options.modifiers !== undefined) {
+            params.modifiers = options.modifiers;
+        }
+        await this.send('Input.dispatchMouseEvent', params);
+        // mouseMoved 同步坐标到 BehaviorSimulator,与 mouseMove 方法保持一致
+        if (type === 'mouseMoved') {
+            this.behaviorSimulator.setCurrentPosition({ x: Math.round(x), y: Math.round(y) });
+        }
+    }
+    /** CDP 通用 inputTouch 接口实现：临时启用 touch 模拟避免命令挂起 */
+    async inputTouch(type, touchPoints) {
+        this.ensureSession();
+        await this.dispatchTouch({ type, touchPoints });
+    }
+    /** CDP inputType 接口实现：直接复用现有 type 方法 */
+    inputType(text, delay = 0) {
+        return this.type(text, delay);
+    }
+    // ==================== IBrowserDriver: Stealth（CDP 不支持） ====================
+    stealthKey(_key, _type, _modifiers) {
+        return Promise.reject(new DriverCapabilityError('Stealth 模式仅在 Extension 下可用,CDP 模式请使用 inputKey'));
+    }
+    stealthClick(_x, _y, _button, _clickCount, _refId) {
+        return Promise.reject(new DriverCapabilityError('Stealth 模式仅在 Extension 下可用,CDP 模式请使用 inputMouse'));
+    }
+    stealthMouse(_type, _x, _y, _button) {
+        return Promise.reject(new DriverCapabilityError('Stealth 模式仅在 Extension 下可用,CDP 模式请使用 inputMouse'));
+    }
+    stealthType(_text, _delay) {
+        return Promise.reject(new DriverCapabilityError('Stealth 模式仅在 Extension 下可用,CDP 模式请使用 inputType'));
+    }
+    stealthInject() {
+        return Promise.reject(new DriverCapabilityError('CDP 模式 stealth 脚本在 connect/launch 时通过 stealth 参数自动注入,不支持后续手动注入'));
+    }
+    // ==================== IBrowserDriver: 日志启用 ====================
+    /** CDP 模式：Network/Runtime 域已在 attach 时启用,no-op */
+    consoleEnable() {
+        return Promise.resolve();
+    }
+    /** CDP 模式：Network 域已在 attach 时启用,no-op */
+    networkEnable() {
+        return Promise.resolve();
+    }
+    // ==================== IBrowserDriver: Tab/状态 ====================
+    /** IBrowserDriver 接口：激活页面（attach + 切到前台） */
+    async activatePage(targetId) {
+        await this.attachToTarget(targetId);
+        await this.activateTarget(targetId);
+    }
+    /** IBrowserDriver 接口：选择操作目标（attach 即可） */
+    async selectPage(targetId) {
+        await this.attachToTarget(targetId);
+    }
+    /** IBrowserDriver 接口：获取当前操作目标 ID */
+    getCurrentTargetId() {
+        return this.currentTargetId;
+    }
+    /** IBrowserDriver 接口：设置当前操作目标 ID（attach 到指定 target） */
+    setCurrentTargetId(targetId) {
+        // CDP 路径不支持同步 setCurrentTargetId（attach 是异步的）;
+        // 调用方应使用 selectPage(targetId) 或 attachToTarget(targetId)
+        if (targetId === null) {
+            // 不允许同步清空 currentTargetId（会造成 sessionId 与 currentTargetId 状态漂移）
+            // 上层应通过 closePage 路径主动清理
+            return;
+        }
+        if (targetId !== this.currentTargetId) {
+            throw new DriverCapabilityError('CDP 模式不支持同步切换 target,请用 selectPage(targetId) 或 attachToTarget(targetId)');
+        }
+    }
+    // ==================== IBrowserDriver: iframe（CDP 不支持） ====================
+    resolveFrame(_frame) {
+        return Promise.reject(new DriverCapabilityError('iframe 穿透需要 Extension 模式'));
+    }
+    getCurrentFrameId() {
+        // CDP 模式没有 frameId 概念,统一返回 0（主框架）
+        return 0;
+    }
+    setCurrentFrameId(frameId) {
+        if (frameId !== 0) {
+            throw new DriverCapabilityError('iframe 穿透需要 Extension 模式');
+        }
+    }
+    evaluateInFrame(_frameId, _expression, _timeout) {
+        return Promise.reject(new DriverCapabilityError('iframe 穿透需要 Extension 模式'));
+    }
+    // ==================== IBrowserDriver: CDP 直通 ====================
+    /**
+     * 发送 CDP 命令（IBrowserDriver 接口）：
+     * tabId 在 CDP 模式下忽略（CDP 单 session 概念不区分 tab）；
+     * browser-level 域（Target/Browser/SystemInfo/DeviceAccess/IO）走 sendBrowserCommand
+     */
+    debuggerSend(method, params, _tabId, timeout) {
+        const domain = method.split('.')[0];
+        const browserLevelDomains = ['Target', 'Browser', 'SystemInfo', 'DeviceAccess', 'IO'];
+        if (browserLevelDomains.includes(domain)) {
+            return this.sendBrowserCommand(method, params);
+        }
+        return this.send(method, params, timeout);
+    }
     /**
      * 获取 Cookies
-     * @param urls 可选，限制返回指定 URL 的 cookies
      */
-    async getCookies(urls) {
+    async getCookies(filter) {
         this.ensureSession();
-        const params = urls?.length ? { urls } : {};
-        const { cookies } = (await this.send('Network.getCookies', params));
-        return cookies;
+        const urls = filter?.url ? [filter.url] : undefined;
+        const { cookies } = (await this.send('Network.getCookies', urls ? { urls } : {}));
+        if (!filter) {
+            return cookies;
+        }
+        return cookies.filter((c) => {
+            if (filter.name && c.name !== filter.name) {
+                return false;
+            }
+            if (filter.domain) {
+                const fd = filter.domain.replace(/^\./, '');
+                const cd = (c.domain ?? '').replace(/^\./, '');
+                if (cd !== fd && !cd.endsWith('.' + fd)) {
+                    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) {
+                const isSession = (c.expires ?? -1) <= 0;
+                if (filter.session !== isSession) {
+                    return false;
+                }
+            }
+            return true;
+        });
     }
     /**
      * 设置 Cookie
      */
-    async setCookie(name, value, options = {}) {
+    async setCookie(params) {
         this.ensureSession();
-        // 获取当前 URL
-        const url = this.state?.url ?? 'http://localhost';
+        const url = params.url ?? this.state?.url ?? 'http://localhost';
+        const { name, value, domain, path, httpOnly, secure, sameSite, expirationDate } = params;
         await this.send('Network.setCookie', {
             name,
             value,
             url,
-            ...options,
+            ...(domain !== undefined && { domain }),
+            ...(path !== undefined && { path }),
+            ...(httpOnly !== undefined && { httpOnly }),
+            ...(secure !== undefined && { secure }),
+            ...(sameSite !== undefined && { sameSite }),
+            ...(expirationDate !== undefined && { expires: expirationDate }),
         });
     }
-    /**
-     * 删除 Cookie
-     */
-    async deleteCookie(name, url) {
+    async deleteCookie(url, name) {
         this.ensureSession();
-        const effectiveUrl = url ?? this.state?.url ?? 'http://localhost';
+        const effectiveUrl = url || this.state?.url || 'http://localhost';
         await this.send('Network.deleteCookies', { name, url: effectiveUrl });
     }
-    /**
-     * 清除所有 Cookies
-     */
-    async clearCookies() {
+    async clearCookies(filter) {
         this.ensureSession();
-        await this.send('Network.clearBrowserCookies');
+        // Driver 级护栏：禁止无过滤的全站清除，必须带 url/domain/name 至少一项
+        if (!filter || (!filter.url && !filter.domain && !filter.name)) {
+            throw new Error('clearCookies 必须带 url/domain/name 至少一个过滤参数（防止误清全站 cookies）');
+        }
+        const urls = filter.url ? [filter.url] : undefined;
+        const { cookies } = (await this.send('Network.getCookies', urls ? { urls } : {}));
+        let count = 0;
+        for (const cookie of cookies) {
+            if (filter.domain) {
+                const fd = filter.domain.replace(/^\./, '');
+                const cd = cookie.domain.replace(/^\./, '');
+                if (cd !== fd && !cd.endsWith('.' + fd)) {
+                    continue;
+                }
+            }
+            if (filter.name && cookie.name !== filter.name) {
+                continue;
+            }
+            const protocol = cookie.secure ? 'https:' : 'http:';
+            const domain = cookie.domain.startsWith('.') ? cookie.domain.slice(1) : cookie.domain;
+            const deleteUrl = `${protocol}//${domain}${cookie.path}`;
+            await this.send('Network.deleteCookies', { name: cookie.name, url: deleteUrl });
+            count++;
+        }
+        return { count };
     }
-    /**
-     * 获取控制台日志
-     */
-    getConsoleLogs(level, limit = 100) {
+    async getConsoleLogs(options = {}) {
         let logs = this.consoleLogs;
+        const { level, pattern, clear } = options;
         if (level && level !== 'all') {
-            // warning/warn 统一匹配（CDP 用 warning，其他源可能用 warn）
-            logs = logs.filter((l) => l.level === level
-                || (level === 'warning' && l.level === 'warn')
-                || (level === 'warn' && l.level === 'warning'));
+            logs = logs.filter((l) => l.level === level ||
+                (level === 'warning' && l.level === 'warn') ||
+                (level === 'warn' && l.level === 'warning'));
+        }
+        if (pattern) {
+            const lp = pattern.toLowerCase();
+            logs = logs.filter((l) => l.text.toLowerCase().includes(lp));
         }
-        return logs.slice(-limit);
+        const result = logs.slice(-100);
+        if (clear) {
+            this.consoleLogs = [];
+        }
+        return result;
     }
-    /**
-     * 获取网络请求日志
-     */
-    getNetworkRequests(urlPattern, limit = 100) {
+    async getNetworkRequests(options = {}) {
+        const { urlPattern, clear } = options;
         let requests = this.networkRequests;
         if (urlPattern) {
             try {
@@ -665,7 +1046,12 @@ class SessionManager {
                 requests = requests.filter((r) => r.url.toLowerCase().includes(pat));
             }
         }
-        return requests.slice(-limit);
+        const result = requests.slice(-100);
+        if (clear) {
+            this.networkRequests = [];
+            this.requestMap.clear();
+        }
+        return result;
     }
     /**
      * 清除日志
@@ -693,7 +1079,7 @@ class SessionManager {
                 const callParams = {
                     functionDeclaration: script,
                     objectId: globalResult.objectId,
-                    arguments: args.map(a => ({ value: a })),
+                    arguments: args.map((a) => ({ value: a })),
                     returnByValue: true,
                     awaitPromise: true,
                 };
@@ -707,8 +1093,7 @@ class SessionManager {
                 return extractCdpValue(result);
             }
             finally {
-                this.send('Runtime.releaseObject', { objectId: globalResult.objectId }).catch(() => {
-                });
+                this.send('Runtime.releaseObject', { objectId: globalResult.objectId }).catch(() => { });
             }
         }
         const evalParams = {
@@ -746,12 +1131,11 @@ class SessionManager {
     }
     /**
      * 清除缓存
+     *
+     * 不再清 cookies：cookies 清除统一走 cookies action=clear（强制 name/domain/url 过滤）
      */
     async clearCache(type = 'all') {
         this.ensureSession();
-        if (type === 'all' || type === 'cookies') {
-            await this.send('Network.clearBrowserCookies');
-        }
         if (type === 'all' || type === 'cache') {
             await this.send('Network.clearBrowserCache');
         }
@@ -766,9 +1150,26 @@ class SessionManager {
     }
     /**
      * 新建页面（外部入口，加锁）
+     *
+     * IBrowserDriver 接口：可选 url 参数，url 提供时新建后立即导航
      */
-    async newPage() {
-        return this.withLock(async () => this.newPageInternal());
+    async newPage(url, _timeout) {
+        const target = await this.withLock(async () => this.newPageInternal());
+        if (url) {
+            await this.navigate(url);
+            return {
+                targetId: target.targetId,
+                url: this.state?.url ?? url,
+                title: this.state?.title ?? '',
+                type: 'page',
+            };
+        }
+        return {
+            targetId: target.targetId,
+            url: target.url,
+            title: target.title,
+            type: 'page',
+        };
     }
     /**
      * 激活页面（切到前台）
@@ -830,9 +1231,9 @@ class SessionManager {
     /**
      * 发送 CDP 命令（page-level，携带 sessionId）
      *
-     * 每次调用都检查连接状态，防止 close() 并发置空 this.cdp 后崩溃。
+     * 每次调用都检查连接状态，防止 close() 并发置空 this.cdp 后崩溃，
      * 多步操作（type 循环、fullPage 截图等）的 await 间隙可能被 close() 打断，
-     * ensureSession() 确保在当前 tick 内 this.cdp 非空。
+     * ensureSession() 确保在当前 tick 内 this.cdp 非空
      */
     send(method, params, timeout) {
         this.ensureSession();
@@ -846,6 +1247,95 @@ class SessionManager {
         this.ensureConnected();
         return this.cdp.send(method, params);
     }
+    /**
+     * 派发 CDP Input.dispatchTouchEvent，临时启用 touch 模拟避免命令挂起
+     */
+    async dispatchTouch(params) {
+        await this.send('Emulation.setTouchEmulationEnabled', { enabled: true });
+        try {
+            await this.send('Input.dispatchTouchEvent', params);
+        }
+        finally {
+            try {
+                await this.send('Emulation.setTouchEmulationEnabled', { enabled: false });
+            }
+            catch {
+                // cleanup 失败不覆盖原始错误
+            }
+        }
+    }
+    /**
+     * 在调用 navigate 之前注册网络空闲监听器，返回等待 idle 的 Promise
+     * 预先注册避免 Page.navigate 返回和监听器注册之间遗漏早期请求
+     */
+    startNetworkIdleWatcher(timeout, idleTime = 500) {
+        this.ensureSession();
+        return this.buildNetworkIdlePromise(this.cdp, timeout, idleTime);
+    }
+    /**
+     * 核心网络空闲等待逻辑
+     *
+     * 捕获 cdp 引用防止 close() 并发置 null，用局部 Set 追踪请求避免污染成员变量
+     * close() 时通过 'disconnected' 信号立即 reject
+     */
+    buildNetworkIdlePromise(cdp, timeout, idleTime) {
+        const localPendingRequests = new Set();
+        return new Promise((resolve, reject) => {
+            let idleTimer = null;
+            let timeoutTimer = null;
+            const checkIdle = () => {
+                if (localPendingRequests.size === 0) {
+                    if (idleTimer === null) {
+                        idleTimer = setTimeout(() => {
+                            cleanup();
+                            resolve();
+                        }, idleTime);
+                    }
+                }
+                else {
+                    if (idleTimer !== null) {
+                        clearTimeout(idleTimer);
+                        idleTimer = null;
+                    }
+                }
+            };
+            const onRequestStart = (params) => {
+                const { requestId } = params;
+                localPendingRequests.add(requestId);
+                checkIdle();
+            };
+            const onRequestEnd = (params) => {
+                const { requestId } = params;
+                localPendingRequests.delete(requestId);
+                checkIdle();
+            };
+            const cleanup = () => {
+                if (idleTimer !== null) {
+                    clearTimeout(idleTimer);
+                }
+                if (timeoutTimer !== null) {
+                    clearTimeout(timeoutTimer);
+                }
+                cdp.offEvent('Network.requestWillBeSent', onRequestStart);
+                cdp.offEvent('Network.loadingFinished', onRequestEnd);
+                cdp.offEvent('Network.loadingFailed', onRequestEnd);
+                cdp.removeListener('disconnected', onDisconnected);
+            };
+            timeoutTimer = setTimeout(() => {
+                cleanup();
+                reject(new NavigationTimeoutError('networkidle', timeout));
+            }, timeout);
+            const onDisconnected = () => {
+                cleanup();
+                reject(new Error('CDP 连接已关闭'));
+            };
+            cdp.once('disconnected', onDisconnected);
+            cdp.onEvent('Network.requestWillBeSent', onRequestStart);
+            cdp.onEvent('Network.loadingFinished', onRequestEnd);
+            cdp.onEvent('Network.loadingFailed', onRequestEnd);
+            checkIdle();
+        });
+    }
     /**
      * 附加到指定页面（内部版本，不加锁，供 launch/connect 等已持锁方法调用）
      */
@@ -895,8 +1385,8 @@ class SessionManager {
     /**
      * 重置所有状态（同步，不加锁）
      *
-     * 供已持有 withLock 的方法调用（launch/connect），避免 close() 的 withLock 重入死锁。
-     * 外部调用请使用 close()。
+     * 供已持有 withLock 的方法调用（launch/connect），避免 close() 的 withLock 重入死锁，
+     * 外部调用请使用 close()
      */
     resetState() {
         if (this.cdp) {
@@ -937,8 +1427,8 @@ class SessionManager {
      * 等待多个事件中的任一个触发
      *
      * 用于同时监听跨文档导航 (loadEventFired) 和同文档导航 (navigatedWithinDocument)，
-     * 任一事件触发后清理所有监听器和超时定时器。
-     * close() 时通过 'disconnected' 信号立即 reject，不必等 timer 超时。
+     * 任一事件触发后清理所有监听器和超时定时器
+     * close() 时通过 'disconnected' 信号立即 reject，不必等 timer 超时
      */
     waitForAnyEvent(events, timeout) {
         // 捕获当前 cdp 引用，防止 close() 并发置 null 导致回调崩溃
@@ -1020,9 +1510,9 @@ class SessionManager {
                 url: p.stackTrace?.callFrames[0]?.url,
                 lineNumber: p.stackTrace?.callFrames[0]?.lineNumber,
             });
-            // 环形缓冲区：超出上限时移除最旧的条目
+            // 环形缓冲区：批量裁剪到 800 条，均摊 O(n) 开销
             if (this.consoleLogs.length > SessionManager.MAX_LOG_ENTRIES) {
-                this.consoleLogs.shift();
+                this.consoleLogs.splice(0, this.consoleLogs.length - 800);
             }
         });
         // 网络请求
@@ -1046,9 +1536,9 @@ class SessionManager {
                     status: p.response.status,
                     duration: Math.round((p.timestamp - _monotonic) * 1000),
                 });
-                // 环形缓冲区：超出上限时移除最旧的条目
+                // 环形缓冲区：批量裁剪到 800 条，均摊 O(n) 开销
                 if (this.networkRequests.length > SessionManager.MAX_LOG_ENTRIES) {
-                    this.networkRequests.shift();
+                    this.networkRequests.splice(0, this.networkRequests.length - 800);
                 }
                 this.requestMap.delete(p.requestId);
             }
@@ -1095,7 +1585,7 @@ class SessionManager {
 /**
  * 获取按键定义
  */
-function getKeyDefinition(key) {
+export function getKeyDefinition(key) {
     const definitions = {
         // 修饰键
         Control: { key: 'Control', code: 'ControlLeft', keyCode: 17 },
@@ -1126,7 +1616,9 @@ function getKeyDefinition(key) {
     }
     // 如果是单个字符，生成定义
     if (key.length === 1) {
-        const charCode = key.charCodeAt(0);
+        // Windows VK code 对字母是大写 ASCII，对数字是数字 ASCII
+        // 用 charCodeAt 的话 'a'=97 会被识别为键码 97（不是字母 A 的 0x41=65），导致快捷键无法匹配
+        const vkCode = key >= 'a' && key <= 'z' ? key.toUpperCase().charCodeAt(0) : key.charCodeAt(0);
         const code = key >= 'a' && key <= 'z'
             ? `Key${key.toUpperCase()}`
             : key >= 'A' && key <= 'Z'
@@ -1137,7 +1629,7 @@ function getKeyDefinition(key) {
         return {
             key,
             code,
-            keyCode: charCode,
+            keyCode: vkCode,
             text: key,
         };
     }