导语:把一套"靠宿主机常驻 Node 内核跑 Playwright"的浏览器技能,重构成"一条命令一个进程"的 CLI,登录态零迁移、宿主换了照样能用。真正难的从来不是连 CDP,而是替掉那些"看起来理所当然"的宿主内置工具。
1. 背景与目标
日常要操作一批只能登录后才能访问的内部系统(工单、知识库、产品库)。这些页面没有对外 API,或者开放的成本远高于点几下页面。为避免"每次让 Agent 重新登录",做法是让自动化接管用户已经登录好的 Chrome:Chrome 用独立 profile 常驻一个调试端口,脚本通过 CDP 连上去,cookies、session、扩展、书签全都在。
第一版实现(下称 v0.1)是给某个 AI Agent 宿主写的技能:宿主内置一个常驻 Node 内核(mcp__node_repl__js 一类工具),每次调用可以 import("playwright-core")、connectOverCDP、操作页面,会话内变量还能跨调用保留。技能文档就是围绕这套工具写的操作手册。
后来换到另一个宿主(下称 DSH)------它有 Shell、有文件系统、有子进程,但没有常驻 Node 内核。那份技能在新宿主里逐条失效:文档第一条命令就是"给内核注入模块路径",而这个工具根本不存在。
目标因此明确了:
- 同一套 CDP 能力,在"有常驻内核"和"只有 Shell"两类宿主上都能跑;
- 复用用户已登录的 Chrome profile,不引入任何登录流程;
- 交互面收缩成命令行 + JSON 输出,Agent 能稳定解析,人能手工复跑;
- 绝不破坏用户已经开着的浏览器。
约束:Windows + PowerShell 宿主;内网出口有 TLS 中间人,npm install 这类下载不稳定;页面多是 Element UI 那类重组件框架。
2. 技术选型
浏览器自动化的路线不止一条,先按"要不要复用登录态"分叉:
| 维度 | A. connectOverCDP 接管已运行 Chrome | B. 自带 Chromium 启动 | C. 裸 CDP WebSocket 手写协议 | D. 独立实例 + 注入 storageState |
|---|---|---|---|---|
| 登录态复用 | 原生复用(同一个 profile) | 需先导出再注入 | 取决于连谁 | 需先导出再注入 |
| 额外下载 | 无(只用系统 Chrome) | 需下 Chromium(内网常失败) | 无 | 需下 Chromium |
| 多标签/iframe/事件 | Playwright 全量 API | 全量 | 全部手写 | 全量 |
| 实现成本 | 低 | 中 | 高 | 中 |
| 稳定性 | 高(只做客户端) | 中(受沙箱/证书影响) | 中(超时自实现) | 中(登录态会过期) |
| 适合场景 | 本机人工已登录的系统 | 干净隔离的抓取 | 极端轻量/无依赖 | CI、无桌面环境 |
结论:A 为主路线,C 降级为兜底 (连不上 Playwright 时,至少还能用 /json/version、/json 两个纯 HTTP 接口做探测和标签页枚举),D 留给未来无桌面场景。B 在内网基本被"下载 Chromium 撞 TLS 中间人"挡死,不作为默认。
3. 架构设计
3.1 架构演进:状态从"内核"搬到"Chrome 进程"
| 版本 | 执行模型 | 状态放哪 | 换宿主后 |
|---|---|---|---|
| v0.1 | 宿主常驻 Node 内核,多次调用共享 import 与 browser 绑定 | 宿主会话内存 | 整份失效 |
| v0.2 | 一次性 node 进程,每条命令进出一个 | Chrome 进程(cookies / 标签页 / 登录态) | 只需 Shell |
演进的本质不是"加了个 CLI",而是把会话级状态移交给一个进程外长期存在的服务。Chrome 才是那个"真状态持有者",脚本退化成无状态的客户端。这么一换,换来三个好处:
- 换宿主零成本(只要有 Shell 能
node); - 命令之间天然隔离,不会因为上一次调用残留的 browser 绑定而互相污染;
- 可以人工复跑同一条命令排障,问题定位不再依赖"Agent 当时那个会话的内核里有什么"。
代价也真实:每次调用都要付一次连接开销(本机约 1~2s),且必须在文档层面把"连接/选择页面"的语义写清楚。
3.2 总体架构
text
┌────────────────────────────── 宿主(AI Agent / 人) ──────────────────────────────┐
│ pwsh -Command "node <skill>\scripts\cdp.mjs <子命令> [参数]" │
└───────────────────────────────────┬──────────────────────────────────────────────┘
│ ① 启动一次性 node 进程
▼
┌────────────────────────────── CLI 层 cdp.mjs ────────────────────────────────────┐
│ 参数解析(--tab/--port/--timeout) → 子命令分发 → JSON 出口(同步写 + exit) │
└───────────┬───────────────────────────────────────────────────┬──────────────────┘
│ ② ensureChromeAndConnect │ ③ 纯 HTTP 探测
▼ ▼
┌──────────────────── 连接库 cdp-connect.mjs ─────────────────┐ ┌── HTTP /json/version ──┐
│ 探测端口 → 未就绪则拉起 Chrome → 轮询 → connectOverCDP │ │ status / tabs 兜底 │
│ → contexts()[0] → pages() │ └────────────────────────┘
└───────────┬─────────────────────────────────────────────────┘
│ ④ Playwright over CDP(ws)
▼
┌──────────────────── Chrome 调试实例(长期常驻) ─────────────────────────────────┐
│ --remote-debugging-port=9223 --user-data-dir=<专用 profile> │
│ 页面 / cookies / 登录态 / 扩展 │
└──────────────────────────────────────────────────────────────────────────────────┘
| 组件 | 载体 | 职责 | 关键约束 |
|---|---|---|---|
CLI 入口 cdp.mjs |
一次性 node 进程 | 参数解析、子命令分发、JSON 输出 | 不持有状态、不跨调用复用连接 |
连接库 cdp-connect.mjs |
ESM 模块 | 端口探测、拉起 Chrome、connectOverCDP、返回 context/pages | 绝不 close() 用户 Chrome |
定位器 lib/pw.mjs |
ESM 模块 | 多候选路径加载 playwright-core | 失败必须列出全部尝试位置 |
| Chrome 调试实例 | 用户本机 Chrome + 独立 profile | 承载页面与登录态 | 必须 --remote-debugging-port 配 --user-data-dir |
端到端走读(一次真实的 text --tab 0):CLI 解析到"读第 0 个页面的正文"→ 连接库探测 9223 已就绪(不重复启动)→ connectOverCDP 拿到 contexts()[0]→ pages() 有 1 个标签页,索引 0 命中 → 容错式 waitForLoadState("domcontentloaded")(8s 上限,超时不算失败,长白屏页面也要能读)→ evaluate(() => document.body.innerText) 返回 809 字符 正文 → 按 --max 600 截断并置 truncated: true → 同步写 stdout → exit(0)。整条链路约 1.5s,其中连接占大头,页面求值只占几十毫秒。
3.3 CLI 层:一个动作一条命令,全部 JSON
12 个子命令:status(自检)、start(拉起 Chrome)、tabs、open、text、html、eval、click、fill、shot、cookies、close。设计上刻意保持"薄":不做多步编排,编排交给调用方(Agent 或脚本),这样每一步都能单独复跑、单独看输出。
关键参数设计:
| 参数 | 取值 | 设计理由 |
|---|---|---|
--tab |
索引 / URL 片段 / 标题片段;不传取最后一个页面 | 人记不住 target id,但记得住 URL 关键词;索引给确定性,片段给可读性 |
--port |
默认 9223,可用环境变量覆盖 | 同一台机器常同时存在多个调试实例(后台/可视化),必须能选 |
--timeout |
默认 30s,大页面调 120s | 超时作为参数暴露,避免内置魔数卡住复杂页面 |
--wait |
操作后等待毫秒 | 内部系统异步渲染慢,点完立刻读会读到旧 DOM |
--max |
文本/HTML 截断长度 | 防止一屏刷出几万字把上下文塞爆 |
统一出口约定:永远输出一个 JSON 对象,ok 字段判成败 ;失败时 error 给出人话 + 现有页面清单("没有匹配 xyz 的页面。现有页面:0 https://... "),这一条在排障时比堆栈有用得多。
还有一个容易被忽略的点:出口写完必须同步落盘再退出进程(见坑 4)。
3.4 连接库:探测 → 拉起 → 轮询 → 连接
ensureChromeAndConnect({port, timeoutMs, autoLaunch}) 的流程是固定的四步,任何一步失败都给出可执行的下一步动作:
| 参数 | 默认 | 设计理由 |
|---|---|---|
port |
9223 | 避开常见被占用的端口(见坑 5) |
autoLaunch |
true |
首次使用自动拉起,省掉"先读文档再启动"的来回;脚本场景可设 false 让失败显式 |
timeoutMs |
20000 | connectOverCDP 在机器忙时会慢,20s 比默认更稳 |
第四步只取 contexts()[0]------因为接管的是一个真实用户 profile,它只有一个持久化 context,不存在"多 context 选哪个"的问题;这是 A 路线比 B 路线简单的地方。
3.5 playwright-core 定位器:为什么不做 npm install
首选方案本该是"技能目录里装一份依赖",但三个现实把它否了:目标机器上已经躺着好几个不同工具自带的 playwright-core 副本(实测 1.58.2 与 1.63.0 各一份),再装一份是几十 MB 的纯重复;内网 TLS 中间人让 npm/pnpm install 时好时坏;技能目录不属于任何工程,塞 node_modules 会和工程依赖语义混淆。
于是做成候选链 + 覆盖 + 兜底:
javascript
export const CANDIDATES = [
process.env.CDP_PLAYWRIGHT_CORE, // 1. 显式指定优先
path.join(skillDir, "node_modules", "playwright-core"),// 2. 技能自带
path.join(APPDATA, "<桌面工具A>", "node_modules", "playwright-core"),
path.join(APPDATA, "pnpm", "node_modules", "<某个技能>", "node_modules", "playwright-core"),
path.join(APPDATA, "pnpm", "node_modules", "playwright-core"),
// ... 其余全局目录
].filter(Boolean);
export async function loadPlaywright() {
const tried = [];
for (const dir of CANDIDATES) {
const entry = ["index.mjs", "index.js"].map((f) => path.join(dir, f)).find(existsSync);
if (!entry) { tried.push(`${dir} → 不存在`); continue; }
try {
const mod = await import(pathToFileURL(entry).href);
const pw = mod.default ?? mod; // 见坑 7
if (pw?.chromium) return { pw, from: dir };
} catch (e) { tried.push(`${dir} → 导入失败: ${e.message}`); }
}
throw new Error("找不到可用的 playwright-core。已尝试:\n - " + tried.join("\n - "));
}
设计要点:错误信息本身就是操作手册 。它列出每个尝试过的目录和失败原因,使用者(或 Agent)看一眼就知道该设 CDP_PLAYWRIGHT_CORE 还是该去装一份。
3.6 Chrome 进程、端口与 profile
这一层是整条链路里"最容易想当然"的地方,四个事实决定设计:
- 调试端口必须配
--user-data-dir(Chrome 130+ 的硬要求),否则端口不监听; - profile 是登录态的物理载体:复用同一 profile = 免登录,这是整套方案的价值来源;
- user-data-dir 是单实例锁:同 profile 已有普通模式 Chrome 在跑时,再启动带调试端口的实例只会把 URL 转给旧进程,端口依然不监听;
- 9222 常被别的 Electron 客户端占用,那个客户端本身也是 CDP 服务端,连上去会连到"别人"。
所以默认用 9223 ,profile 用专用目录(既保持登录态,又不和用户日常浏览器打架),并且判断"能不能用"的唯一依据是端口是否就绪,不是"进程是否存在"。
需要人工登录时用可见窗口启动(start 不带 --headless);纯自动化后台跑用 --headless=new。
3.7 可运维性:一条 status 说完所有前提
任何排障都从自检开始,它把"端口 / playwright / profile / 标签页数"一次摊平:
json
{
"ok": true,
"profileDir": "D:\\workspace\\chrome-profile",
"ports": {
"9223": { "ready": true, "browser": "Chrome/156.0.8078.79", "tabs": 1 },
"9333": { "ready": true, "browser": "Chrome/156.0.8078.79", "tabs": 1 }
},
"playwright": { "ok": true, "from": "C:\\Users\\<用户名>\\AppData\\Roaming\\...\\playwright-core" },
"ready": true
}
browser 字段写的是 /json/version 里的原文(Chrome/... vs Electron/...),用来一眼确认"连的是不是 Chrome",这是坑 5 的产物。ready 是综合结论,调用方只需要看它。
其余运维面刻意保持朴素:日志就是 stdout 的 JSON;截图落盘路径由 --out 指定(默认写当前目录,带时间戳);不写任何后台守护进程、不留 pid 文件。
4. 关键实现
4.1 按可见文字点击:可达性过滤 + 最短命中
页面里按钮文字常常嵌套(外层容器 innerText 也包含同样文字),直接 querySelector('button') 会点错层。策略是:只在可见元素里找、命中多个时取文字最短的那个。
javascript
const hits = [...document.querySelectorAll(
'button,a,li,span,div,input[type="submit"],[role="button"],.el-button,.el-radio__inner,.el-pager li'
)].filter((el) => el.offsetParent !== null) // 可见
.filter((el) => (el.innerText || el.value || "").trim().includes(needle));
hits.sort((a, b) => a.innerText.trim().length - b.innerText.trim().length);
if (!hits.length) return { clicked: false, reason: "text not found" };
const el = hits[0];
el.scrollIntoView({ block: "center" });
el.click();
return { clicked: true, tag: el.tagName, text: el.innerText.trim().slice(0, 80) };
返回里带 tag 与命中文字,让调用方能判断"点到的是不是我想点的那个"。
4.2 填表单:事件序列比赋值重要
受控组件(Vue/React)只认事件,不认 el.value = x。所以固定序列 focus → 赋值 → input → change → blur:
javascript
el.focus();
el.value = val;
el.dispatchEvent(new Event("input", { bubbles: true }));
el.dispatchEvent(new Event("change", { bubbles: true }));
el.blur();
反面情况:readonly 字段不要 fill,直接点它自己触发绑在上面的 onclick 联动计算(内部系统的 Domino 表单大量是这个套路)。
4.3 eval 是表达式语义,不是函数体
page.evaluate(string) 按表达式求值,const a = 1; return a; 这种函数体写法拿不到返回值。统一要求调用方包 IIFE:
powershell
node cdp.mjs eval --tab 0 --expr "(() => { const f = document.querySelector('iframe'); return f?.contentDocument?.body.innerText ?? 'cross-origin'; })()"
复杂逻辑走 --file a.js,避免命令里塞一长串 JS 被 shell 转义坑。
4.4 cookies → 复用给 HTTP 下载
有些资源(附件、报表)用浏览器点会弹下载框,直接用 cookie 调 HTTP 更干净:
powershell
node cdp.mjs cookies --tab 0 --url "https://<内部域名>" --names "SESSION_ID"
# 返回 cookieHeader: "SESSION_ID=xxx",可直接塞给 Invoke-WebRequest 的 -Headers @{Cookie=$h}
5. 踩坑记录(共 8 个)
坑 1:换了宿主,整份技能失效------状态押在"宿主 REPL"上
现象:文档第一条命令是"给内核注入 playwright 模块路径",新宿主的工具列表里根本没有这个工具;所有示例都是"每次调用重新 bootstrap"的形状,照抄全部报工具不存在。
原因 :v0.1 的设计假设是"宿主提供一个常驻 Node 内核"------import 缓存、browser 绑定、会话变量都活在那个内核里。这是宿主特性,不是可移植的浏览器能力,但文档把它当通用 API 写进了操作步骤,于是能力与宿主被焊死。
解决:把能力和宿主切开。能力下沉成 ESM 模块(连接库),交互层换成 CLI 子命令,状态外移到 Chrome 进程:
powershell
node <技能目录>\scripts\cdp.mjs status
node <技能目录>\scripts\cdp.mjs text --tab 0 --max 2000
预防 :写跨宿主技能时逐条自问"这句依赖的是浏览器能力,还是宿主给的便利"。凡是出现 import、常驻变量、模块路径注入这类内核语义,一律封装成可执行脚本,文档只做索引与参数说明。
坑 2:playwright-core 的硬编码路径在这台机器上不存在
现象 :Cannot find package 'playwright-core'。文档写死的目录(某个 pnpm 全局路径下)实测为空;真实副本在另外两个桌面工具自带的 node_modules 里,且版本还不一样(1.58.2 / 1.63.0)。
原因:依赖装在哪个目录,取决于"是谁装的";把某台机器上一次性的目录布局写成了永久路径,换机器/换版本即失效。
解决 :候选链探测(见 3.5)+ 环境变量 CDP_PLAYWRIGHT_CORE 覆盖 + 裸导入兜底,失败时打印全部尝试路径。
预防:技能里任何写死路径的地方都必须带 fallback 与覆盖开关;错误信息必须列出尝试过的位置------否则使用者只能猜。
坑 3:browser.close() 把用户开着的 Chrome 一起关了
现象 :第一次跑完命令,node 进程迟迟不退出(Playwright 的 WebSocket 维持着事件循环);加上 browser.close() 后进程秒退,但调试端口上的 Chrome 也一起消失了------用户桌面上开着的页面全没了。
原因 :connectOverCDP 拿到的 Browser.close() 语义不是"断开连接",它会像对待自己启动的浏览器那样把底层浏览器关掉。而我的心理模型是"我只是个客户端",两者不一致。
解决 :不调 close(),改为写完输出直接 process.exit(0);连接随进程销毁,Chrome 继续活着。
javascript
try {
await handler();
process.exit(0); // 连接自然断开,浏览器不受影响
} catch (e) {
die(e?.message || String(e));
}
预防:凡是"连外部已运行服务"的客户端,先确认断开语义;拿不准就用"进程退出即断开"这个最保守的模型。
坑 4:异步 stdout + process.exit → JSON 尾巴被截断
现象 :偶发 Unexpected end of JSON input,输出末尾少半个花括号,同一命令重跑有时又正常;输出越长越容易命中。
原因 :process.stdout.write 在 Windows 管道上是异步的,紧随其后的 process.exit() 直接杀掉进程,缓冲区没写完就没了。
解决:改成同步写入再退出:
javascript
import { writeSync } from "node:fs";
const out = (obj) => writeSync(1, JSON.stringify(obj, null, 2) + "\n");
预防:给 Agent 消费的 CLI,把"序列化 → 同步写 → 显式退出"三件套固定成模板,别用异步写 + exit 的组合。
坑 5:连上了 9222,但连的不是 Chrome
现象 :connectOverCDP 返回成功,pages() 里却全是某个聊天客户端的窗口;或者干脆连接超时。
原因 :9222 被一个 Electron 桌面客户端占用,它自身就是 CDP 服务端。端口能通不代表通到 Chrome。
解决 :改用 9223;status 里同时探测多个端口,并把 /json/version 的 Browser 原文打出来,用 Chrome/ 与 Electron/ 区分。
预防 :连接前先看 Browser 字段确认目标身份;客户端类和浏览器的端口规划要错开,别共用社区默认值。
坑 6:Chrome 130+ 不带 --user-data-dir,端口不监听;同 profile 再启动也一样
现象 A :只给 --remote-debugging-port 时端口不监听,进程看起来正常在跑。
现象 B:同一 profile 已有普通模式 Chrome 在跑,再启动一个带调试端口的实例,端口依然不监听。
原因 :Chrome 130 起调试端口强制要求配 --user-data-dir;而 user-data-dir 是单实例锁,第二次启动只会把命令行参数里的 URL 转给已有实例,调试开关被吞掉。
解决:永远带专用 profile 启动;启动前先探测端口,已在跑就复用;profile 被占用就先关掉那个 Chrome,或换一个 profile 目录。
powershell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9223 `
--user-data-dir="D:\workspace\chrome-profile"
预防 :把"端口是否就绪"当作唯一可用性判断(status),别用"进程存在"来判断------Chrome 有多进程模型,看进程只会误判。
坑 7:const { chromium } = await import("playwright-core") 拿到 undefined
现象 :解构出来的 chromium 是 undefined,随后 chromium.connectOverCDP is not a function。
原因 :CommonJS 包经 ESM 动态导入时,导出挂在 default 上,具名解构拿不到。
解决 :const { default: pw } = await import(...),再用 pw.chromium。这个坑直接在定位器里消化掉,业务代码不再重复踩。
预防 :ESM 里动态导入 CJS 包,先打印 Object.keys(mod) 看一眼结构;把这类兼容逻辑收敛到一个 loader。
坑 8:eval --expr 传多语句返回 undefined
现象 :--expr "const a = 1; return a;" 返回 null。
原因 :page.evaluate(string) 按表达式 求值,不是函数体,return 无处可去。
解决 :包成 IIFE (() => { ... })();长脚本用 --file。
预防:给 CLI 的求值入口在文档里写清"表达式语义",示例统一用 IIFE,避免使用者按函数体直觉写。
6. 总结
交付物是 4 个文件(1 份 SKILL.md + 3 个脚本)、12 个子命令。实测通过的动作:status(端口与依赖自检 ready: true)、tabs(复用已登录标签页)、text(一次读回 809 字符正文)、eval(返回结构化对象)、shot(99 KB png 落盘)、open / click / close(新开页面、点链接跳转、关页收尾,全程未触碰用户原有标签页)。
几条体会:
- 技能不是文档,是可执行能力。文档里每一句"先做 X 再做 Y",都该有对应的脚本入口;否则换个宿主就全废。
- 凡是宿主提供的便利,都是不可移植的。判据很简单:它是不是这个宿主独有的工具名。
- 状态放在最稳定的那个东西上。浏览器进程的寿命远长于任何一次 Agent 调用,把登录态押在浏览器上,脚本就可以随便启停。
- 错误信息要写成下一步动作。列尝试路径、列现有页面、给出可直接复制的启动命令------排障时间基本都花在这上面。
后续计划:跨源 iframe 的单独 target 连接、下载链路的统一封装(cookie 注入 + 落盘校验)、以及把"批量翻页采集"这类编排固化成脚本模板。
参考
- Playwright
browserType.connectOverCDP文档:https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp - Chrome DevTools Protocol 总览:https://chromedevtools.github.io/devtools-protocol/
- Chrome 远程调试端口与 user-data-dir 说明:https://developer.chrome.com/blog/remote-debugging-port