cdp-tunnel 3.6.2 → 3.6.4

package/CHANGELOG.md

@@ -0,0 +1,266 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [3.6.4] - 2026-07-08
+### Added
+- **SDK 入口**：新增 `index.js`，`require('cdp-tunnel')` 直接返回编程式 API（`startServer` / `createApiKey` / `listApiKeys` / `revokeApiKey` / `PortPoolManager` 等），无需深路径 require
+- **多浏览器实例服务示例**：新增 `examples/multi-browser-service.js`，演示"一服务管多浏览器"的完整流程（起 proxy → 创建 key → 启 Chrome → 发现 → 接管 → 操作 → 验证隔离）
+- **多浏览器并发测试**：新增 `tests/e2e/test-multi-browser.js`，覆盖 11 个检查点（服务端发现、key 路由、双向隔离、并发操作、断连容错），已纳入 `run-all.js` core tier
+- **示例文档**：新增 `examples/README.md`，含架构图、快速开始、7 步流程说明、验证点表格、发版前必跑命令
+
+### Changed
+- `package.json` 的 `main` 从 `server/proxy-server.js` 改为 `index.js`（SDK 入口）
+- `package.json` 的 `files` 加入 `index.js`
+
+## [3.6.3] - 2026-07-07
+### Fixed
+- **不再产生隐式 about:blank 页面**：删除端口池 warmup 逻辑（每个 session 第一个 client 连接时用 `Target.createTarget` 创建临时 about:blank tab 再关闭），时间窗口内 Playwright 的 `setAutoAttach` 会看到这个 tab，导致用户看到多余空白页或自动测试断言 `pages().length` 不稳定
+- **对齐原生 CDP**：移除 warmup 后，client 连接后 `pages()` 返回 0（与 `chrome --remote-debugging-port` 一致），不再有隐式页面
+
+### Changed
+- 更新 test-default-page.js 注释：描述改为"客户端连接后不产生任何隐式 about:blank"
+
+## [3.6.2] - 2026-07-07
+### Fixed
+- **内存泄漏**：`Target.targetDestroyed` / `Target.detachedFromTarget` 事件路径清理 `sessionToPort`、`targetToPort`、`sessionToClient`，避免长跑后无界增长
+- **客户端断开时清理**：port-pool 的 `ws.on('close')` 现在清掉对应 client 的 `pendingRequests` 和 `sessionToClient` 引用，避免 plugin 永不响应时 ws 对象常驻
+- **健壮性**：`handleHttpRequest` 加顶层 try/catch，plugin 通信异常不再 crash 整个 proxy
+- **WebSocket 安全发送**：proxy-server.js 中 8 处直接 `ws.send()` 全部改为 `safeSend()`，客户端/插件意外断开时不再触发二次 cleanup race
+- **message listener 泄漏**：`requestVersionFromPlugin` / `requestTargetsFromPlugin` 的超时分支现在会 `off` listener，避免长连接累积
+- **进程退出干净**：SIGINT/SIGTERM 现在清理全部 4 个 `setInterval`（之前只清了 heartbeat）
+
+### Changed
+- **依赖瘦身**：移除未使用的 devDependencies（`sharp`、`lz-string`、`pako`、`playwright-core`、`puppeteer-core`）
+- **scripts 清理**：删除指向不存在目录的 npm scripts（client / record / benchmark / demo 等 7 条）
+- **.gitignore 增强**：加入 `.vscode/`、`.idea/`、`*.cpuprofile`、`*.heapprofile`
+- **bin 字段规范化**：从 `"./cli/index.js"` 改为 `{ "cdp-tunnel": "./cli/index.js" }`（npm publish 会自动修正，现在显式正确）
+
+### Removed
+- 清理 13 个开发期临时脚本（`tests/e2e/_*.cjs`，含硬编码绝对路径）
+
+## [3.6.1] - 2026-07-07
+### Fixed
+- **issue #1**：cdp-tunnel 模式下 `Target.getTargetInfo` 返回空 title — 用 `tab.title` 覆盖过期 title
+- **issue #2**：带 clip 的 `Page.captureScreenshot` 缺 elementScreenshot — 自动 `ensureVisible` 前置
+
+### Changed
+- 大量死代码清理（autoCreateDefaultPageAndForward、forwardToPlugin、pageCreateIsolatedWorld 等）
+- pre-commit hook 加 `NO_PROXY=localhost,127.0.0.1,::1`，避免 Playwright HTTP 请求走系统代理导致测试假阳性
+
+## [3.6.0] - 2026-06-23
+### Added
+- **云管理控制台**：proxy 内置管理网页 `/admin`，查看在线浏览器、管理 key、CDP 快捷操作
+- **Tab 管理**：列表/关闭/切换标签页，关闭浏览器
+- **快捷操作 + 一键演示**：打开百度、截图、执行 JS、自动搜索演示
+- **创建浏览器入口**：直观创建新分组，生成完整地址一键复制
+- **按 key 隔离分组**：每个 key 独立端口池端口 session，listtabs 只看自己的 tab
+- test-key-isolation.js（5 项）、test-admin-console.js（10 项）自动化测试
+
+### Changed
+- 分组名按 API Key 名称命名（CDP-张三的浏览器），一眼看出是谁的
+- 扩展端 buildGroupName/_createGroupForClient/doGroup 支持 groupName
+- listtabs 走 /client 路径（按 key 过滤，不入侵用户 tab）
+
+### Fixed
+- closebrowser 正确关闭分组（clientId 按 key 反查 + client-disconnected）
+- keySessions constructor 补全（git checkout 遗漏）
+- doGroup 实际建分组时 groupName 没传（根因：state 没存 groupName）
+
+## [3.5.0] - 2026-06-22
+### Added
+- **API Key 鉴权**：proxy 支持 `REQUIRE_AUTH=true` 强制鉴权，一个 key 绑定一个浏览器。扩展连 `/plugin?key=xxx`，客户端连 `/client?key=xxx`，不同 key 互不可见。新增 `server/saas/key-manager.js` 手动管理 key（创建/列出/吊销）。
+- **版本校验加强**：`STRICT_VERSION=true` 时扩展版本与 proxy 不一致直接拒绝连接（close 4002），避免老扩展与新 proxy 不兼容。
+- **远程部署支持**：proxy 监听 0.0.0.0，可通过 nginx/Cloudflare 反代暴露到公网。新增 `docs/DEPLOY-CLOUDFLARE.md` 部署文档。
+- 新增自动化测试：`test-api-key-auth.js`（鉴权 7 项）、`test-version-check.js`（版本校验 3 项）、`test-prod-deploy.js`（生产环境验证 10 项）。
+- 扩展配置页优化：带 key 的 URL 自动隐藏明文（防截图泄露），显示 🔑 鉴权标识，CDP 地址自动带 key。
+
+### Changed
+- **9221 主端口纳入端口池**：9221 不再走老的 create 路径，改为端口池第 0 个 session（pool_9221），与 9231-9239 行为完全一致。takeover（9220）保持原逻辑。
+- 端口池 `/json/version` `/json/list` 支持尾斜杠（修复 Playwright connectOverCDP 404）。
+- pre-commit smoke test 从 3 个增加到 5 个（25 checks）。
+
+### Fixed
+- 修复 `attachedToTarget` 事件 sessionId 不注册导致 Playwright evaluate 卡死的根因（auto-attach 场景 targetId 可能未注册）。
+- 修复端口池 `closeTarget` 响应 `session.attachedTargets` 字段不存在的 TypeError。
+- 修复 SaaS `auth.js` 的 `datetime("now")` SQL 语法错误（双引号→单引号）。
+- 修复 `validateApiKey` 作用域 bug（定义在 try 块内导致 HAS_SAAS=true 时崩溃）。
+
+## [3.0.0] - 2026-06-19
+### Added
+- **端口池架构**：proxy 现在支持多端口隔离。每个 create 端口（默认 9222-9230）= 一个独立的隔离环境，不同端口的 client 互不可见对方的 tab。对齐原生 Chrome `--remote-debugging-port` 行为：多客户端可连同一端口、断开不清理 tab。
+- 新增 `server/modules/port-pool.js`：端口池管理器，按 portIndex 隔离 target/session 事件路由
+- 新增 `test-port-isolation.js`：验证不同端口的 client 互不可见（6 项检查）
+- `run-all.js` 测试时自动禁用端口池（`POOL_SIZE=0`）避免端口冲突
+
+### Changed
+- `config.js` 新增 `POOL_TAKEOVER_PORT`（9220）、`POOL_START`（9222）、`POOL_SIZE`（9）配置
+- 现有 9221/9222 行为完全不变（端口池是额外新增的端口）
+
+### 配置
+- `POOL_SIZE=0` 禁用端口池（默认 9 个 create 端口）
+- `POOL_START=9222` 端口池起始端口
+- `POOL_TAKEOVER_PORT=9220` 端口池的 takeover 端口
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.10.14] - 2026-06-19
+### Fixed
+- **长时间运行后并发 createTarget 偶发 page 停留 about:blank**：`sessionToClientId` 映射表泄漏——当 targetId 归属未定时，L900 将 `targetId` 误存为 session 的 value（应为 clientId），导致 `cleanupClient` 按 clientId 匹配时永远清不掉这些条目。proxy 长时间运行后 `sessionToClientId` 无限增长，新 client 的事件可能命中过期映射导致路由错误。修复：归属未定时暂存到 `pendingSessionToClientId`，归属绑定后补绑；`cleanupClient` 补清理 `pendingAttachedEvents`/`pendingTargetCreatedEvents`/`pendingSessionToClientId`。实测 200 次连/断后所有 Map 稳定为 0（修复前 sessionToClientId 线性增长至 300+）。
+
+## [2.10.13] - 2026-06-17
+### Fixed
+- **Input.dispatchKeyEvent / dispatchMouseEvent 在隔离 tab 上丢失**：隔离 tab 默认 `visibility=hidden`（`active:false` + 折叠分组），Chromium 在此状态下丢弃合成输入事件（keyboard/mouse），导致 Playwright/Puppeteer 的 `keyboard.type()`、`mouse.click()` 等操作静默失效。`forward.js` 现在在发送合成输入命令前自动执行 `Page.bringToFront` + 等待 `visibilitychange` + 恢复元素焦点，确保事件能投递到 DOM。`insertText` 和 `Runtime.evaluate` 不受影响（不走合成事件路由），无需此处理。
+
+### Added
+- E2E 测试 `test-input-delivery.js`：验证 keyboard/mouse/click/Enter 四类合成输入事件在隔离 tab 上能正确投递到 DOM
+
+## [2.5.8] - 2026-05-12
+### Fixed
+- 修复 `websocket.js` 中 `startGroupMonitor` 函数末尾代码重复导致的 JS 语法错误（该错误导致扩展完全无法加载）
+
+## [2.5.7] - 2026-05-12
+### Fixed
+- 恢复 `addTabToAutomationGroup` 的 `cdpClients[0]` fallback 机制：当 `clientId` 为空时，如果存在已连接 client 则 fallback 到第一个 client 强制分组，避免逃逸
+
+## [2.5.6] - 2026-05-12
+### Added
+- `doGroup` 分组失败自动重试 3 次（500ms 间隔），提高首次分组成功率
+- 分组逃逸监控日志增强：记录每个 tab 的 groupId、clientId、预期分组状态
+
+### Fixed
+- 分组逃逸监控跳过 `clientId` 为空或 pre-existing 的 tab
+
+## [2.5.5] - 2026-05-12
+### Changed
+- 分组逃逸监控间隔从 10 秒缩短为 5 秒，更快检测并修复逃逸 tab
+
+## [2.5.4] - 2026-05-12
+### Added
+- `startGroupMonitor()`: 每 10 秒扫描所有 attached tab，检测逃逸（有 clientId 但无 groupId）的 tab，自动强制归组
+
+### Fixed
+- Proxy 拦截跨客户端 `Target.closeTarget` 和 `Target.attachToTarget`，返回 `Target is owned by another client` 错误
+- `buildGroupName` 改用末尾 8 位随机后缀，确保各客户端组名唯一
+
+## [2.5.3] - 2026-05-12
+### Fixed
+- `buildGroupName` 改用 `clientId.substring(clientId.length - 8)` 取末尾随机后缀，修复所有 client 组名相同（都是 `CDP-client_1`）的问题
+
+### Added
+- 压力测试 `test-stress-isolation.js`：3 个并发 CDP 客户端各执行 10+ 次创建/关闭/切换操作，验证隔离性、分组独立性和断连清理
+- `Tab.getGroupInfo` handler：直接查询分组是否创建成功
+
+## [2.5.2] - 2026-05-12
+### Added
+- `addTabToAutomationGroup` 改用轮询方案：`chrome.tabs.get` 每 200ms 检查 tab 状态，加载完成后再分组（最多等 4 秒后强制分组），无需 setTimeout(500) 或 chrome.tabs.onUpdated
+
+### Fixed
+- `addTabToAutomationGroup` 的分组操作改为等 tab 状态 `complete` 后再执行，确保 `chrome.tabs.group` 调用成功
+
+## [2.5.1] - 2026-05-12
+### Fixed
+- CLI 更新命令改用 `npm install -g cdp-tunnel@latest`，修复 `npm update -g` 偶发的 `Cannot read properties of null` 错误
+
+## [2.5.0] - 2026-05-12
+### Added
+- 多客户端隔离：CDP 客户端只能看到自己创建的 tab（`Target.getTargets` 过滤）
+- 用户 tab 不可见：`emitAutoAttachForExistingTargets` 跳过非 CDP tab，不发事件不 attach
+- 目标事件缓存：`pendingTargetCreatedEvents` 修复事件先于 response 到达时的丢包问题
+
+### Fixed
+- `closeGroupById` 按 `clientId` 过滤 tab，避免断连时误杀其他 client 的 tab
+- `addTabToAutomationGroup` 去掉 `cdpClients[0]` fallback，无 clientId 不分组
+- `buildGroupName` 使用稳定 `CDP-<hash>` 而非 `CDP #<index>`（index 随 client 断连变化）
+
+## [2.1.0] - 2025-05-11
+
+### Added
+- `preExistingTabIds` tracking: tabs opened by user BEFORE CDP connect are preserved on disconnect
+- `CDPUtils.buildGroupName` / `getGroupBaseName` / `findGroupByName` / `getGroupColorForClient` — unified group helpers
+- E2E test: `test-tab-group-isolation.js` — single client group + user tab survival
+- E2E test: `test-multi-client-group-isolation.js` — multi-client group isolation + user tab survival
+
+### Fixed
+- **User tabs no longer closed on CDP disconnect**: `emitAutoAttachForExistingTargets` marks pre-existing tabs instead of grouping them; disconnect only closes grouped (CDP-created) tabs
+- **Unified tab group naming**: `CDP #1 (N)` instead of inconsistent `CDP-<hash>` / `CDP-Automation` / `CDP-<timestamp>`
+- **Unified group lookup**: all 3 files (`special.js`, `background.js`, `websocket.js`) now use `CDPUtils.findGroupByName` (prefix match)
+- **Removed dead `popup.html` / `popup.js`** (no `default_popup` in manifest)
+
+## [2.0.0] - 2025-05-11
+
+### Added
+- Landing page at `docs/index.html` with dark/light mode, feature showcase, CLI reference, and comparison table
+- `CHANGELOG.md` for version history tracking
+- `engines` field in package.json (Node.js >= 16)
+- `repository`, `homepage`, `bugs` fields in package.json
+- Expanded npm keywords for better discoverability
+
+### Changed
+- **Breaking**: package.json `description` now in English for npm discoverability
+- Moved 47 root-level test/debug scripts to `tests/scratch/` — cleaner repository
+- Extracted duplicate `String.prototype.hashCode` from `background.js` and `special.js` into shared `utils/helpers.js`
+- Removed dead `popup.html` and `popup.js` (unused since manifest has no `default_popup`)
+
+## [1.7.0] - 2025-05-10
+
+### Added
+- `/json/version` returns Chrome-compatible format (Browser, User-Agent, V8-Version, webSocketDebuggerUrl)
+- `/json/list` includes `devtoolsFrontendUrl` and `faviconUrl` fields
+- agent-browser `--cdp` compatibility via standard Chrome DevTools Protocol endpoints
+- `emitAutoAttachForExistingTargets` now attaches unattached pages — fixes `pages()` returning empty
+- CLI `--version` reads from package.json instead of hardcoded value
+
+### Fixed
+- Duplicate target events: `handleDebuggerEvent` in `debugger.js` now filters `Target.*` events
+- CLI `update` command: skips when already latest version, uses `fs.readFileSync` (not require cache), added timeouts
+
+## [1.6.1] - 2025-05-09
+
+### Fixed
+- Auto-mute: `muteTabIfNeeded()` called in ALL attach paths
+
+### Added
+- Custom CDP command `Tab.getMuteStatus` for verifying mute state from tests
+
+## [1.6.0] - 2025-05-09
+
+### Added
+- `--auto-restart` flag: proxy detects plugin disconnect + client connect → auto-launches Chrome
+- One-command `cdp-tunnel start`: auto-detects Chrome state, launches or guides user
+- Auto-mute tabs when attached by automation
+- Dynamic tab group names `CDP-{clientId:8} ({N})` with auto-collapse
+
+## [1.5.1] - 2025-05-08
+
+### Fixed
+- `Browser.close` forwarded to extension (not intercepted by proxy)
+
+## [1.5.0] - 2025-05-08
+
+### Added
+- Multi-client CDP isolation: Target.getTargets filtered by clientId
+- Target events routed to owning client only
+- `closeGroupById` closes tabs FIRST then detaches debugger
+
+## [1.3.1] - 2025-05-07
+
+### Added
+- CLI `diagnose` command: 6-step health check (proxy, HTTP, extension, targets, Chrome, Playwright)
+
+## [1.3.0] - 2025-05-07
+
+### Added
+- CLI help with usage examples
+- `--watchdog` crash recovery mode
+
+## [1.0.0] - 2025-05-05
+
+### Added
+- Initial release
+- Chrome Extension CDP Proxy via `chrome.debugger` API
+- WebSocket endpoint at `localhost:9221`
+- Playwright and Puppeteer compatibility
+- Configuration page with live dashboard
+- E2E test suite with CI/CD pipeline

package/examples/README.md

@@ -0,0 +1,235 @@
+# 多浏览器实例服务
+
+把 cdp-tunnel 包装成一个"中转站"服务：一台服务器同时管理多个远程浏览器，每个浏览器用独立的 API Key 标识，互不可见。
+
+## 简介
+
+典型场景：
+
+```
+服务方（你）                              用户A / 用户B / ...
+─────────────                            ──────────────
+┌─────────────────────────┐              ┌──────────────┐
+│  cdp-tunnel proxy       │◀──wss───扩展 │  用户A 浏览器  │
+│  (公网 wss://...)       │◀──wss───扩展 │  用户B 浏览器  │
+│  + key 鉴权             │              └──────────────┘
+│  + 按 key 隔离           │
+└─────────┬───────────────┘
+          │
+          ▼ Playwright/CDP connectOverCDP
+     服务方用 clientUrl 接管浏览器
+```
+
+- 一 key = 一浏览器实例（不同 key 的浏览器互不可见）
+- 标准协议：客户端用 Playwright `connectOverCDP` 即可，无需学新 API
+- 服务端发现：`/json/browsers` 列出所有在线浏览器
+- 容错：某个浏览器断开，只影响对应 key，其他 key 不受影响
+
+## 前置条件
+
+```bash
+# 1. 安装 cdp-tunnel
+npm install -g cdp-tunnel
+
+# 2. 准备 Chromium（macOS 默认路径 /Applications/Chromium.app）
+#    或通过 CHROME_PATH 环境变量指定
+
+# 3. 进入项目目录（开发模式下）
+cd cdp-tunnel2
+```
+
+## 快速开始
+
+直接运行示例脚本，会自动完成全部流程：
+
+```bash
+NO_PROXY=localhost,127.0.0.1,::1 node examples/multi-browser-service.js
+```
+
+预期输出：
+
+```
+=== 多浏览器实例服务示例 ===
+
+[SERVICE] 启动 cdp-tunnel proxy on port 29xxx...
+[SERVICE] Proxy 就绪
+[SERVICE] 用户A 的 Key: cdp_xxxx...
+[SERVICE] 用户B 的 Key: cdp_xxxx...
+[BROWSER] 启动用户A 的 Chrome...
+[BROWSER] 启动用户B 的 Chrome...
+[SERVICE] 发现 2 个在线浏览器
+[CDP] 用户A 的浏览器打开百度...
+[CDP] 用户A 百度 title: "百度一下，你就知道"
+[CDP] 用户B 的浏览器打开 example.com...
+[CDP] 用户B example.com title: "Example Domain"
+[VERIFY] 用户A 看到的页面: ["https://www.baidu.com/"]
+[VERIFY] 用户B 看到的页面: ["https://example.com/"]
+
+=== 结果 ===
+  用户A 打开百度:    ✅ (百度一下，你就知道)
+  用户B 打开 example: ✅ (Example Domain)
+  A 看不到 B 的页面:  ✅
+  B 看不到 A 的页面:  ✅
+```
+
+## 流程说明
+
+示例脚本 [examples/multi-browser-service.js](multi-browser-service.js) 完整演示了以下 7 步：
+
+### Step 1 — 启动 proxy（强制鉴权）
+
+```javascript
+const { spawn } = require('child_process');
+const PROXY_PATH = require.resolve('cdp-tunnel/server/proxy-server.js');
+
+const proxyProc = spawn('node', [PROXY_PATH], {
+  env: {
+    ...process.env,
+    PORT: String(PORT),
+    REQUIRE_AUTH: 'true',        // 强制 key 鉴权
+    POOL_SIZE: '3',              // 端口池隔离
+    LOG_LEVEL: 'warn'
+  }
+});
+```
+
+### Step 2 — 为每个用户创建 API Key
+
+```bash
+node server/saas/key-manager.js create 用户A
+# 输出：
+#   Key: cdp_aaaa1111...
+#   扩展连接地址: ws://your-server:PORT/plugin?key=cdp_aaaa1111...
+#   CDP 客户端地址: ws://your-server:PORT/client?key=cdp_aaaa1111...
+```
+
+**一 key = 一浏览器实例槽位**。创建后把 pluginUrl 给用户填进扩展。
+
+### Step 3 — 用户装扩展 + 配置 key
+
+用户在自己电脑上：
+1. `chrome://extensions/` → 开发者模式 → 加载 `extension-new/` 目录
+2. 点扩展图标 → 配置页 → 添加连接 → 填入服务方给的 pluginUrl
+3. 点"连接"——扩展通过 wss 连上服务方的 proxy
+
+### Step 4 — 服务端发现浏览器
+
+```javascript
+const browsers = await httpGet(PORT, '/json/browsers');
+// 返回所有在线浏览器列表
+```
+
+### Step 5 — 用 CDP 接管浏览器
+
+```javascript
+// 标准 Playwright 接入
+const { chromium } = require('playwright');
+const browser = await chromium.connectOverCDP(
+  `ws://your-server:${PORT}/client?key=${KEY_A}`
+);
+```
+
+或用裸 CDP WebSocket（示例脚本采用的方式）：
+
+```javascript
+const WebSocket = require('ws');
+const ws = new WebSocket(`ws://127.0.0.1:${PORT}/client?key=${KEY_A}`);
+ws.on('open', () => {
+  ws.send(JSON.stringify({ id: 1, method: 'Target.createTarget', params: { url: 'about:blank' } }));
+});
+```
+
+### Step 6 — 分别操作各浏览器
+
+```javascript
+// 用户A 打开百度
+const { sessionId: sessA } = await createPageAndNavigate(clientA, 'https://www.baidu.com');
+const titleA = await clientA.send('Runtime.evaluate', { expression: 'document.title' }, sessA);
+
+// 用户B 打开 example.com
+const { sessionId: sessB } = await createPageAndNavigate(clientB, 'https://example.com');
+const titleB = await clientB.send('Runtime.evaluate', { expression: 'document.title' }, sessB);
+```
+
+### Step 7 — 验证隔离
+
+```javascript
+const tgA = await clientA.send('Target.getTargets');
+const tgB = await clientB.send('Target.getTargets');
+// keyA 只看到自己创建的百度，看不到 example.com
+// keyB 只看到自己创建的 example.com，看不到百度
+```
+
+## 验证点（测试覆盖）
+
+自动化测试 [tests/e2e/test-multi-browser.js](../tests/e2e/test-multi-browser.js) 覆盖以下 11 个检查点，每个都是可断言的硬性指标：
+
+| # | 检查点 | 说明 |
+|---|---|---|
+| 1 | 服务端发现 2 个浏览器 | `/json/browsers` 返回数组长度 ≥ 2 |
+| 2 | keyA 打开百度 | createTarget + navigate + get title 非空 |
+| 3 | keyB 打开 example.com | 同上 |
+| 4 | keyA 看到自己打开的百度 | `Target.getTargets` 包含 baidu URL |
+| 5 | keyA 看不到 keyB 的 example.com | `Target.getTargets` 不包含 example.com |
+| 6 | keyB 看到自己打开的 example.com | `Target.getTargets` 包含 example.com URL |
+| 7 | keyB 看不到 keyA 的百度 | `Target.getTargets` 不包含 baidu |
+| 8 | 并发操作：keyA 得到 MARK-A | Promise.all 并发注入，结果正确 |
+| 9 | 并发操作：keyB 得到 MARK-B | 同上 |
+| 10 | ChromeA 断开后 keyA 被拒 | 新 client 连 `/client?key=KEY_A` 被 close |
+| 11 | ChromeA 断开后 keyB 不受影响 | keyB 仍能 createTarget + evaluate |
+
+## 发版前必跑
+
+**每次发版前必须跑一遍，确保多浏览器场景未被破坏。**
+
+```bash
+# 单独跑多浏览器测试
+NO_PROXY=localhost,127.0.0.1,::1 node tests/e2e/test-multi-browser.js
+
+# 期望结果：11 passed, 0 failed
+```
+
+该测试已纳入 `run-all.js` 的 core tier：
+
+```bash
+# 跑 core 测试套件（包含本测试）
+SKIP_EXTENDED=1 npm run test:e2e
+```
+
+## 关键设计
+
+### 为什么用独立扩展副本
+
+两个 Chrome 不能共享同一个 `extension-new/` 目录，因为每个扩展的 `config.js` 要注入不同的 key。示例采用的方式是：
+
+```javascript
+// 复制扩展到临时目录
+fs.cpSync(EXTENSION_PATH, tmpExt, { recursive: true });
+// 改 config.js 注入 key
+fs.writeFileSync(configPath, configOriginal.replace(
+  /WS_URL:\s*'[^']*'/,
+  `WS_URL: 'ws://127.0.0.1:${port}/plugin?key=${key}'`
+));
+// 启动 Chrome 加载这个副本
+spawn(CHROME_PATH, [`--load-extension=${tmpExt}`, ...]);
+```
+
+### 为什么用 127.0.0.1 而不是 localhost
+
+Node.js 25+ 在 macOS 上 `localhost` 会优先解析到 IPv6（`::1`），而 proxy 监听的是 `0.0.0.0`。虽然 `0.0.0.0` 理论上同时覆盖 IPv4/IPv6，但 IPv6 的连接在某些环境下不稳定。统一用 `127.0.0.1` 避免歧义。
+
+### 为什么用 CDP WebSocket 而不是 Playwright
+
+示例脚本用裸 CDP WebSocket（`ws` 库）而不是 Playwright `connectOverCDP`，因为：
+- 更底层、更可控、不依赖 Playwright 版本
+- 测试更稳定（Playwright 的 `contexts()` 在 connectOverCDP 场景下行为不一致）
+
+实际生产中用 Playwright `connectOverCDP(clientUrl)` 完全可以，参考 [test-default-page.js](../tests/e2e/test-default-page.js) 的用法。
+
+## 相关文件
+
+- [examples/multi-browser-service.js](multi-browser-service.js) — 可直接运行的示例
+- [tests/e2e/test-multi-browser.js](../tests/e2e/test-multi-browser.js) — 自动化测试（11 checks）
+- [server/saas/key-manager.js](../server/saas/key-manager.js) — Key 管理 CLI
+- [docs/DEPLOY-CLOUDFLARE.md](../docs/DEPLOY-CLOUDFLARE.md) — 公网部署指南
+- [index.js](../index.js) — SDK 入口（`require('cdp-tunnel')`）

package/examples/multi-browser-service.js

@@ -0,0 +1,238 @@
+'use strict';
+
+/**
+ * 多浏览器实例服务示例
+ *
+ * 场景：一台服务器同时管理多个远程浏览器
+ * - 服务方启动 cdp-tunnel proxy（REQUIRE_AUTH=true）
+ * - 为每个用户创建一个 API Key（一 key = 一浏览器实例）
+ * - 用户在自己电脑装扩展 + 填 pluginUrl
+ * - 服务方用 clientUrl 通过 Playwright/CDP 接管浏览器
+ *
+ * 运行：node examples/multi-browser-service.js
+ */
+
+const { spawn, execSync } = require('child_process');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const WebSocket = require('ws');
+
+// === 配置 ===
+const CHROME_PATH = process.env.CHROME_PATH || '/Applications/Chromium.app/Contents/MacOS/Chromium';
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const EXTENSION_PATH = path.join(PROJECT_ROOT, 'extension-new');
+const PROXY_PATH = path.join(PROJECT_ROOT, 'server/proxy-server.js');
+const KEY_MGR = path.join(PROJECT_ROOT, 'server/saas/key-manager.js');
+
+function log(tag, msg) {
+  console.log(`[${new Date().toISOString().slice(11, 19)}] [${tag}] ${msg}`);
+}
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+function httpGet(port, urlPath) {
+  return new Promise((resolve, reject) => {
+    http.get(`http://127.0.0.1:${port}${urlPath}`, res => {
+      let d = '';
+      res.on('data', c => d += c);
+      res.on('end', () => { try { resolve(JSON.parse(d)); } catch { resolve(d); } });
+    }).on('error', reject);
+  });
+}
+
+async function waitForPort(port, maxWait = 15000) {
+  const start = Date.now();
+  while (Date.now() - start < maxWait) {
+    try { await httpGet(port, '/json/version'); return true; } catch { /* keep waiting */ }
+    await sleep(500);
+  }
+  return false;
+}
+
+// === Key 管理 ===
+function createKey(name) {
+  const out = execSync(`node ${KEY_MGR} create ${name}`, { encoding: 'utf8' });
+  const m = out.match(/Key:\s*(cdp_\w+)/);
+  return m ? m[1] : null;
+}
+
+// === CDP 客户端（轻量封装） ===
+class CdpClient {
+  constructor(url) {
+    this.url = url;
+    this.ws = null;
+    this.idCounter = 1;
+    this.pending = new Map();
+  }
+  async connect() {
+    this.ws = new WebSocket(this.url);
+    await new Promise((r, e) => { this.ws.on('open', r); this.ws.on('error', e); });
+    this.ws.on('message', (data) => {
+      const msg = JSON.parse(data.toString());
+      if (msg.id && this.pending.has(msg.id)) {
+        const { resolve, reject } = this.pending.get(msg.id);
+        this.pending.delete(msg.id);
+        msg.error ? reject(new Error(JSON.stringify(msg.error))) : resolve(msg.result);
+      }
+    });
+    return this;
+  }
+  send(method, params = {}, sessionId) {
+    return new Promise((resolve, reject) => {
+      const id = this.idCounter++;
+      this.pending.set(id, { resolve, reject });
+      setTimeout(() => { if (this.pending.has(id)) { this.pending.delete(id); reject(new Error(`Timeout: ${method}`)); } }, 30000);
+      const msg = { id, method, params };
+      if (sessionId) msg.sessionId = sessionId;
+      this.ws.send(JSON.stringify(msg));
+    });
+  }
+  close() { try { this.ws.close(); } catch {} }
+}
+
+// === 浏览器操作辅助 ===
+async function createPageAndNavigate(client, url) {
+  const { targetId } = await client.send('Target.createTarget', { url: 'about:blank' });
+  const { sessionId } = await client.send('Target.attachToTarget', { targetId, flatten: true });
+  await client.send('Page.enable', {}, sessionId);
+  await client.send('Page.navigate', { url }, sessionId);
+  for (let i = 0; i < 30; i++) {
+    try {
+      const result = await client.send('Runtime.evaluate', { expression: 'document.readyState' }, sessionId);
+      if (result?.result?.value === 'complete') break;
+    } catch {}
+    await sleep(500);
+  }
+  return { targetId, sessionId };
+}
+
+// === Chrome 启动（带扩展 + key 预设） ===
+function launchChrome({ key, port, tag }) {
+  // 复制扩展到临时目录，注入 key
+  const tmpExt = `/tmp/cdp-ext-${tag}-${Date.now()}`;
+  fs.cpSync(EXTENSION_PATH, tmpExt, { recursive: true });
+  const configPath = path.join(tmpExt, 'utils', 'config.js');
+  const configOriginal = fs.readFileSync(configPath, 'utf8');
+  fs.writeFileSync(configPath, configOriginal.replace(
+    /WS_URL:\s*'[^']*'/, `WS_URL: 'ws://127.0.0.1:${port}/plugin?key=${key}'`
+  ));
+
+  const profile = `/tmp/cdp-profile-${tag}-${Date.now()}`;
+  const proc = spawn(CHROME_PATH, [
+    '--headless=new',
+    `--user-data-dir=${profile}`,
+    `--load-extension=${tmpExt}`,
+    '--no-first-run', '--no-default-browser-check',
+    '--disable-features=DialMediaRouteProvider', '--no-sandbox',
+    'about:blank'
+  ], { detached: true, stdio: 'ignore' });
+  proc._profile = profile;
+  proc._tmpExt = tmpExt;
+  return proc;
+}
+
+function killChrome(proc) {
+  if (!proc) return;
+  try { process.kill(-proc.pid); } catch {}
+  if (proc._profile) { try { fs.rmSync(proc._profile, { recursive: true, force: true }); } catch {} }
+  if (proc._tmpExt) { try { fs.rmSync(proc._tmpExt, { recursive: true, force: true }); } catch {} }
+}
+
+// ============================================================
+// 主流程：模拟多浏览器实例服务
+// ============================================================
+(async () => {
+  const PORT = 29700 + Math.floor(Math.random() * 500);
+  let proxyProc, chromeA, chromeB, clientA, clientB;
+
+  try {
+    console.log('\n=== 多浏览器实例服务示例 ===\n');
+
+    // Step 1: 启动 proxy（强制鉴权）
+    log('SERVICE', `启动 cdp-tunnel proxy on port ${PORT}...`);
+    proxyProc = spawn('node', [PROXY_PATH], {
+      env: {
+        ...process.env,
+        PORT: String(PORT),
+        POOL_SIZE: '3',
+        POOL_START: String(PORT + 1),
+        TAKEOVER_PORT: String(PORT + 10),
+        POOL_TAKEOVER_PORT: String(PORT + 10),
+        REQUIRE_AUTH: 'true',
+        LOG_LEVEL: 'warn'
+      },
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    proxyProc.stdout.on('data', () => {});
+    proxyProc.stderr.on('data', () => {});
+    if (!await waitForPort(PORT)) throw new Error('Proxy 启动失败');
+    log('SERVICE', 'Proxy 就绪');
+
+    // Step 2: 为两个用户创建 Key
+    const KEY_A = createKey('用户A');
+    const KEY_B = createKey('用户B');
+    log('SERVICE', `用户A 的 Key: ${KEY_A?.slice(0, 20)}...`);
+    log('SERVICE', `用户B 的 Key: ${KEY_B?.slice(0, 20)}...`);
+    log('SERVICE', `用户A 的扩展连接地址: ws://your-server:${PORT}/plugin?key=${KEY_A}`);
+    log('SERVICE', `用户B 的扩展连接地址: ws://your-server:${PORT}/plugin?key=${KEY_B}`);
+
+    // Step 3: 启动两个 Chrome（模拟用户装扩展 + 配置 key）
+    log('BROWSER', '启动用户A 的 Chrome...');
+    chromeA = launchChrome({ key: KEY_A, port: PORT, tag: 'A' });
+    log('BROWSER', '启动用户B 的 Chrome...');
+    chromeB = launchChrome({ key: KEY_B, port: PORT, tag: 'B' });
+
+    // Step 4: 等待两个浏览器上线（服务端发现）
+    log('SERVICE', '等待浏览器连接...');
+    for (let i = 0; i < 60; i++) {
+      try {
+        const browsers = await httpGet(PORT, '/json/browsers');
+        if (Array.isArray(browsers) && browsers.length >= 2) {
+          log('SERVICE', `发现 ${browsers.length} 个在线浏览器`);
+          break;
+        }
+      } catch {}
+      await sleep(2000);
+    }
+
+    // Step 5: 用 CDP 接管两个浏览器
+    log('CDP', '连接用户A 的浏览器...');
+    clientA = await new CdpClient(`ws://127.0.0.1:${PORT}/client?key=${KEY_A}`).connect();
+    log('CDP', '连接用户B 的浏览器...');
+    clientB = await new CdpClient(`ws://127.0.0.1:${PORT}/client?key=${KEY_B}`).connect();
+
+    // Step 6: 分别操作两个浏览器
+    log('CDP', '用户A 的浏览器打开百度...');
+    const { sessionId: sessA } = await createPageAndNavigate(clientA, 'https://www.baidu.com');
+    const titleA = (await clientA.send('Runtime.evaluate', { expression: 'document.title' }, sessA))?.result?.value;
+    log('CDP', `用户A 百度 title: "${titleA}"`);
+
+    log('CDP', '用户B 的浏览器打开 example.com...');
+    const { sessionId: sessB } = await createPageAndNavigate(clientB, 'https://example.com');
+    const titleB = (await clientB.send('Runtime.evaluate', { expression: 'document.title' }, sessB))?.result?.value;
+    log('CDP', `用户B example.com title: "${titleB}"`);
+
+    // Step 7: 验证隔离
+    const tgA = await clientA.send('Target.getTargets');
+    const tgB = await clientB.send('Target.getTargets');
+    const urlsA = (tgA.targetInfos || []).filter(t => t.type === 'page').map(t => t.url);
+    const urlsB = (tgB.targetInfos || []).filter(t => t.type === 'page').map(t => t.url);
+    log('VERIFY', `用户A 看到的页面: ${JSON.stringify(urlsA)}`);
+    log('VERIFY', `用户B 看到的页面: ${JSON.stringify(urlsB)}`);
+
+    console.log('\n=== 结果 ===');
+    console.log(`  用户A 打开百度:    ${titleA === '百度一下，你就知道' ? '✅' : '❌'} (${titleA})`);
+    console.log(`  用户B 打开 example: ${titleB === 'Example Domain' ? '✅' : '❌'} (${titleB})`);
+    console.log(`  A 看不到 B 的页面:  ${!urlsA.some(u => u.includes('example.com')) ? '✅' : '❌'}`);
+    console.log(`  B 看不到 A 的页面:  ${!urlsB.some(u => u.includes('baidu')) ? '✅' : '❌'}`);
+    console.log('');
+
+  } finally {
+    // 清理
+    try { if (clientA) clientA.close(); } catch {}
+    try { if (clientB) clientB.close(); } catch {}
+    try { if (chromeA) killChrome(chromeA); } catch {}
+    try { if (chromeB) killChrome(chromeB); } catch {}
+    try { proxyProc && proxyProc.kill('SIGTERM'); } catch {}
+  }
+})();

package/extension-new/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "CDP Bridge",
-  "version": "3.6.2",
+  "version": "3.6.4",
   "description": "Chrome DevTools Protocol Bridge for Playwright/Puppeteer automation",
   "permissions": [
     "debugger",

package/extension-new/utils/config.js

@@ -1,5 +1,5 @@
 var Config = {
-  WS_URL: 'ws://localhost:51100/plugin',
+  WS_URL: 'ws://localhost:10108/plugin',
   RECONNECT_DELAY: 3000,
   DEBUGGER_VERSION: '1.3',
   HEARTBEAT_INTERVAL: 25000,

package/index.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * cdp-tunnel — 把 Chrome 扩展（chrome.debugger）桥接成标准 CDP WebSocket 服务
+ *
+ * 典型用法（本地一键启动）：
+ *   const cdp = require('cdp-tunnel');
+ *   const { port } = await cdp.startServer({ requireAuth: true });
+ *   const { pluginUrl, clientUrl } = cdp.createApiKey('张三');
+ *   // 把 pluginUrl 给用户填进扩展，用 clientUrl 让 Playwright connectOverCDP 接管
+ *
+ * 对外服务化部署：
+ *   const { port } = await cdp.startServer({
+ *     requireAuth: true,
+ *     strictVersion: true,
+ *     adminToken: 'your-secret',
+ *     externalHost: 'cdn.example.com:8443'  // 生成给用户的地址用这个 host
+ *   });
+ *   const key = cdp.createApiKey('用户A', { host: 'cdn.example.com:8443' });
+ *
+ * 客户端不需要本 SDK —— 标准 Playwright/Puppeteer 用 connectOverCDP(clientUrl) 即可。
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const http = require('http');
+const auth = require('./server/saas/auth');
+const { PortPoolManager } = require('./server/modules/port-pool');
+const { CONFIG } = require('./server/modules/config');
+
+const PROXY_SERVER_PATH = path.join(__dirname, 'server', 'proxy-server.js');
+const BUILTIN_USER = { id: 'builtin-admin', email: 'admin@local', displayName: 'Admin' };
+
+// ====== 内置用户（绕过注册系统，SDK 直接管理 key） ======
+
+function ensureBuiltinUser() {
+  const db = require('./server/saas/db');
+  const existing = db.prepare('SELECT id FROM users WHERE id = ?').get(BUILTIN_USER.id);
+  if (!existing) {
+    db.prepare('INSERT INTO users (id, email, password_hash, display_name) VALUES (?, ?, ?, ?)')
+      .run(BUILTIN_USER.id, BUILTIN_USER.email, 'builtin-no-login', BUILTIN_USER.displayName);
+  }
+  return BUILTIN_USER;
+}
+
+// ====== Key 管理（一 key = 一浏览器实例） ======
+
+/**
+ * 创建 API Key（= 一个浏览器实例槽位）
+ * @param {string} [name] 实例名称，用于辨识
+ * @param {object} [opts] { host } 自定义对外地址，如 'cdn.example.com:8443'。不传则用 EXTERNAL_HOST 环境变量或 localhost:PORT
+ * @returns {{ keyId, key, name, pluginUrl, clientUrl }}
+ */
+function createApiKey(name, opts = {}) {
+  ensureBuiltinUser();
+  const keyName = name || ('browser-' + Date.now().toString(36));
+  const keyInfo = auth.createApiKey(BUILTIN_USER.id, keyName);
+  const host = opts.host || process.env.EXTERNAL_HOST || `localhost:${CONFIG.PORT}`;
+  const proto = host.startsWith('localhost') || host.startsWith('127.') ? 'ws' : 'wss';
+  return {
+    keyId: keyInfo.id,
+    key: keyInfo.key,
+    name: keyName,
+    pluginUrl: `${proto}://${host}/plugin?key=${keyInfo.key}`,
+    clientUrl: `${proto}://${host}/client?key=${keyInfo.key}`
+  };
+}
+
+/**
+ * 列出所有 Key
+ * @returns {Array<{id, name, active, created_at, last_used_at}>}
+ */
+function listApiKeys() {
+  ensureBuiltinUser();
+  return auth.listApiKeys(BUILTIN_USER.id);
+}
+
+/**
+ * 吊销 Key
+ * @param {string} keyId
+ */
+function revokeApiKey(keyId) {
+  ensureBuiltinUser();
+  return auth.revokeApiKey(keyId, BUILTIN_USER.id);
+}
+
+/**
+ * 校验 Key（返回 userId/keyId/keyName 或 null）
+ * @param {string} key
+ */
+function validateApiKey(key) {
+  return auth.validateApiKey(key);
+}
+
+// ====== 服务启动 / 停止 ======
+
+/**
+ * 编程式启动 proxy server（子进程方式，不阻塞当前进程）
+ * @param {object} [opts]
+ * @param {number} [opts.port] 端口，默认 9221
+ * @param {boolean} [opts.requireAuth] 强制 key 鉴权
+ * @param {boolean} [opts.strictVersion] 扩展版本严格校验
+ * @param {string} [opts.adminToken] 管理后台 token
+ * @param {string} [opts.externalHost] 对外 host（生成给用户的地址用）
+ * @param {function} [opts.onLog] 日志回调 (msg) => void
+ * @param {object} [opts.env] 额外环境变量
+ * @returns {Promise<{ process, port, stop }>}
+ */
+function startServer(opts = {}) {
+  const port = opts.port || CONFIG.PORT;
+  const env = {
+    ...process.env,
+    PORT: String(port),
+    REQUIRE_AUTH: opts.requireAuth ? 'true' : (process.env.REQUIRE_AUTH || ''),
+    STRICT_VERSION: opts.strictVersion ? 'true' : (process.env.STRICT_VERSION || ''),
+    ADMIN_TOKEN: opts.adminToken || process.env.ADMIN_TOKEN || '',
+    EXTERNAL_HOST: opts.externalHost || process.env.EXTERNAL_HOST || '',
+    ...(opts.env || {})
+  };
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('node', [PROXY_SERVER_PATH], {
+      env,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let started = false;
+    const timeout = setTimeout(() => {
+      if (!started) {
+        child.kill('SIGTERM');
+        reject(new Error(`Server failed to start within 15s on port ${port}`));
+      }
+    }, 15000);
+
+    const onLine = (buf) => {
+      const msg = buf.toString();
+      if (opts.onLog) opts.onLog(msg);
+      if (!started && msg.includes(`Server started on port ${port}`)) {
+        started = true;
+        clearTimeout(timeout);
+        resolve({
+          process: child,
+          port,
+          stop: () => {
+            child.kill('SIGTERM');
+            return new Promise(r => child.on('exit', r));
+          }
+        });
+      }
+    };
+    child.stdout.on('data', onLine);
+    child.stderr.on('data', onLine);
+
+    child.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+    child.on('exit', (code) => {
+      clearTimeout(timeout);
+      if (!started) reject(new Error(`Server exited with code ${code} before starting`));
+    });
+  });
+}
+
+/**
+ * 健康检查：探测某端口的 proxy 是否就绪
+ * @param {number} [port] 默认 9221
+ * @param {number} [timeoutMs] 默认 5000
+ */
+function isServerReady(port = CONFIG.PORT, timeoutMs = 5000) {
+  const start = Date.now();
+  return new Promise(async (resolve) => {
+    while (Date.now() - start < timeoutMs) {
+      try {
+        await new Promise((res, rej) => {
+          const req = http.get(`http://localhost:${port}/json/version`, (r) => {
+            r.on('data', () => {});
+            r.on('end', res);
+          });
+          req.on('error', rej);
+          req.setTimeout(500, () => req.destroy(new Error('timeout')));
+        });
+        resolve(true);
+        return;
+      } catch {
+        await new Promise(r => setTimeout(r, 300));
+      }
+    }
+    resolve(false);
+  });
+}
+
+module.exports = {
+  // 服务启动 / 停止
+  startServer,
+  isServerReady,
+
+  // Key 管理（一 key = 一浏览器实例）
+  createApiKey,
+  listApiKeys,
+  revokeApiKey,
+  validateApiKey,
+
+  // 高级用法
+  PortPoolManager,
+  CONFIG,
+
+  // 完整 auth 模块（createUser / JWT / 密码等）
+  auth
+};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "cdp-tunnel",
-  "version": "3.6.2",
+  "version": "3.6.4",
   "description": "Bridge Chrome's debugger API to WebSocket — control your existing browser with Playwright/Puppeteer via CDP",
-  "main": "server/proxy-server.js",
+  "main": "index.js",
   "bin": {
     "cdp-tunnel": "./cli/index.js"
   },
@@ -43,10 +43,13 @@
     "node": ">=16.0.0"
   },
   "files": [
+    "index.js",
     "server/",
     "cli/",
     "extension-new/",
+    "examples/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {

package/server/modules/port-pool.js

@@ -261,22 +261,12 @@ class PortPoolManager {
       return;
     }
 
-    // SW 冷启动 warmup：第一个 client 连接时创建一个临时 tab 再关闭
-    if (!session.warmedUp) {
-      session.warmedUp = true;
-      const warmupId = `pool${session.portIndex}_internal_warmup`;
-      pluginWs.send(JSON.stringify({
-        id: warmupId,
-        method: 'Target.createTarget',
-        params: { url: 'about:blank' },
-        __portIndex: session.portIndex,
-        __clientId: `pool_${session.port}`
-      }));
-      // warmup 响应回来后在 handlePluginMessage 里关闭这个 tab
-      session.pendingWarmupClose = true;
-    }
-
     // 通知扩展有 client 连接（带端口号作为分组标识）
+    // 对齐原生 CDP：不创建任何隐式的 about:blank 页面。
+    // 原生 chrome --remote-debugging-port 在 client 连接后不创建任何 target，
+    // 只在 connectOverCDP 的 setAutoAttach 期间发现已有 target。
+    // （移除旧版 warmup 逻辑：它用 Target.createTarget 创建临时 about:blank 再关闭，
+    //   但时间窗口内 Playwright 的 setAutoAttach 会发现它，导致用户看到多余空白页。）
     // clientId 固定为 pool_{port}，让扩展为每个端口建一个独立分组
     // __groupName 带 key 名称，让扩展用 key 名称命名 Chrome 分组（一眼看出是谁的浏览器）
     const poolClientId = `pool_${session.port}`;
@@ -360,23 +350,8 @@ class PortPoolManager {
 
     // 1. 响应消息：id 以 pool 开头（排除事件——事件有 method 字段）
     if (msg.id && typeof msg.id === 'string' && msg.id.startsWith('pool') && !msg.method) {
-      // 内部命令响应
+      // 内部命令响应（_ensureVisible 的 bringToFront/waitVis 等）：丢弃，不路由给 client
       if (msg.id.includes('_internal')) {
-        // warmup createTarget 响应——关掉 warmup tab
-        const m = msg.id.match(/^pool(\d+)_/);
-        if (m && msg.id.includes('_warmup') && msg.result && msg.result.targetId) {
-          const pidx = parseInt(m[1]);
-          const sess = this.portSessions[pidx];
-          const warmupTid = msg.result.targetId;
-          const closeId = `pool${pidx}_internal_warmup_close_${Date.now()}`;
-          pluginWs.send(JSON.stringify({
-            id: closeId,
-            method: 'Target.closeTarget',
-            params: { targetId: warmupTid },
-            __portIndex: pidx,
-            __clientId: `pool_${sess.port}`
-          }));
-        }
         return true;
       }
       const match = msg.id.match(/^pool(\d+)_(.+)$/);