@pyrokine/mcp-chrome 1.1.0 → 1.3.0

package/dist/core/unified-session.js

@@ -7,16 +7,20 @@
  */
 import { ExtensionBridge } from '../extension/index.js';
 import { getSession as getCdpSession } from './session.js';
+import { 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() { }
+    constructor() {
+    }
     static getInstance() {
         if (!UnifiedSessionManager.instance) {
             UnifiedSessionManager.instance = new UnifiedSessionManager();
@@ -73,30 +77,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 +90,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 +115,6 @@ class UnifiedSessionManager {
             mode: 'cdp',
         };
     }
-    /**
-     * 连接到已运行的浏览器（CDP 模式）
-     */
-    async connect(options) {
-        const target = await getCdpSession().connect(options);
-        return {
-            ...target,
-            mode: 'cdp',
-        };
-    }
     /**
      * 列出所有页面
      */
@@ -289,8 +209,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 +227,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);
     }
     /**
      * 点击元素
@@ -349,18 +270,23 @@ 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})`;
         }
@@ -380,15 +306,24 @@ class UnifiedSessionManager {
         // 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);
                 }
                 return result.result?.value;
             }
-            // 主 frame：直接 Runtime.evaluate
+            // 主 frame，无 args：直接 Runtime.evaluate
             const params = {
                 expression,
                 returnByValue: true,
@@ -438,6 +373,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 +411,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 +426,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 +588,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 +599,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,8 +632,9 @@ 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 模式');
         }
@@ -745,29 +671,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 +695,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 +735,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 +752,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,41 +773,26 @@ 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, modifiers: this.modifiers });
             }
             return;
         }
         await getCdpSession().mouseUp(effectiveButton);
     }
+    // ==================== 键鼠输入 ====================
+    // stealth 模式：使用 JS 事件模拟，不触发调试提示，推荐用于反检测场景
+    // precise 模式：使用 debugger API，精确但会显示"扩展程序正在调试此浏览器"
     /**
      * 鼠标滚轮
      */
     async mouseWheel(deltaX, deltaY) {
         if (await this.ensureExtensionConnected()) {
             const { x, y } = this.currentMousePosition;
-            await this.extensionBridge.inputMouse('mouseWheel', x, y, { deltaX, deltaY });
+            await this.extensionBridge.inputMouse('mouseWheel', x, y, { deltaX, deltaY, modifiers: this.modifiers });
             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);
-    }
     /**
      * 注入反检测脚本
      */
@@ -922,7 +833,6 @@ class UnifiedSessionManager {
         }
         await getCdpSession().touchEnd();
     }
-    // ==================== 控制台日志 ====================
     /**
      * 启用控制台日志捕获
      */
@@ -943,16 +853,6 @@ class UnifiedSessionManager {
         // CDP 模式需要单独实现
         return [];
     }
-    /**
-     * 清除控制台日志
-     */
-    async clearConsoleLogs() {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.consoleClear();
-            return;
-        }
-    }
-    // ==================== 网络日志 ====================
     /**
      * 启用网络日志捕获
      */
@@ -972,16 +872,6 @@ class UnifiedSessionManager {
         }
         return [];
     }
-    /**
-     * 清除网络日志
-     */
-    async clearNetworkLogs() {
-        if (await this.ensureExtensionConnected()) {
-            await this.extensionBridge.networkClear();
-            return;
-        }
-    }
-    // ==================== Debugger 直接访问 ====================
     /**
      * 发送 CDP 命令（高级用法）
      *
@@ -1000,6 +890,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(result.exceptionDetails.text);
+            }
+            return result.result?.value;
+        }
+        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;
+    }
 }
 /**
  * 获取统一会话管理器实例