zenstory-ai/oh-story-claudecode / skills/browser-cdp
browser-cdp
VerifiedUse this skill when you need to control a Chrome browser via CDP (Chrome DevTools Protocol) to reuse existing login sessions. Covers: launching Chrome in debug mode, opening URLs, waiting for page load, evaluating JavaScript, taking snapshots, and extracting auth tokens. Trigger phrases: browser automation, CDP, agent-browser, 浏览器操作, 操作浏览器, Chrome CDP, 复用登录态, extract token from browser.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.1 KB |
| scripts/setup-cdp-chrome.jsexecutable | script | 40.2 KB |
scripts/setup-cdp-chrome.js
View on GitHub#!/usr/bin/env node
// setup-cdp-chrome.js
// 准备带有 CDP(Chrome DevTools Protocol)调试功能的 Chrome 环境(跨平台)。
// 通过此脚本,agent-browser 可以复用用户的 Chrome 登录态。
//
// 用法:
// node setup-cdp-chrome.js [port] [options]
//
// Options:
// --detect-only 只探测当前状态(结构化输出),不做任何修改
// --yes 确认杀死现有 Chrome,跳过交互提示
// --reset 清空 ~/chrome-debug-profile 后重新复制
// --profile <name> 使用指定 Chrome profile(默认: Default)
// --dry-run 打印将执行的操作,不实际执行
//
// 说明:CDP 端口已在监听时默认直接复用现有 Chrome 并退出 0;但传了 --reset 或显式
// --profile 时不复用——这两个参数就是要重建 debug profile(登录态过期即走这条路),
// 会先关闭现有 Chrome(非 TTY 下需 --yes,否则 exit 3 报 NEEDS_CONSENT)。
// 重建路径上有两道硬闸门:关完进程后端口必须真的不再应答(否则在动 profile 之前就
// exit 1 中止,绝不删一个还在运行的 Chrome 的 profile);启动后必须证明「端口上应答的
// 就是本次启动的实例」——身份取得到且与重建前不同、spawn 出的进程还活着、端口的 LISTEN
// 持有者全在这棵进程树里、且树里确有一个持有者带着本次的 --remote-debugging-port。
// 任何一条证不出来(含查不到)都拒绝报成功,避免把别人的会话当新浏览器交出去。
//
// 退出码:
// 0 成功 / detect-only 完成
// 1 通用错误(环境缺失、超时等)
// 2 用户拒绝(TTY 模式下回答 N)
// 3 需要同意但当前为非 TTY 且未传 --yes
//
// detect-only 结构化输出(stdout,每行 KEY=value):
// CDP_STATUS=ready|needs-setup
// CDP_URL=... (仅当 ready)
// BROWSER=... (仅当 ready)
// CHROME_RUNNING=yes|no
// CHROME_PID_COUNT=N (仅当 CHROME_RUNNING=yes)
"use strict";
const { execSync, spawn } = require("child_process");
const fs = require("fs");
const http = require("http");
const net = require("net");
const os = require("os");
const path = require("path");
const readline = require("readline");
// ---------------------------------------------------------------------------
// 参数解析
// ---------------------------------------------------------------------------
function parseArgs(argv) {
const flags = { dryRun: false, yes: false, detectOnly: false, reset: false };
let profile = "Default";
// 是否显式传了 --profile:默认值 "Default" 无法区分「没传」和「传了 Default」,
// 而这两种情况在"CDP 已就绪"分支上的语义不同(复用 vs 按指定 profile 重建)
let profileExplicit = false;
let port = null;
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
switch (a) {
case "--dry-run": flags.dryRun = true; break;
case "--yes": case "-y": flags.yes = true; break;
case "--detect-only": flags.detectOnly = true; break;
case "--reset": flags.reset = true; break;
case "--profile":
profile = argv[++i];
if (!profile) {
console.error("❌ --profile 需要一个参数(例如: --profile \"Profile 1\")");
process.exit(1);
}
profileExplicit = true;
break;
default:
if (/^\d+$/.test(a)) {
port = parseInt(a, 10);
} else if (a.startsWith("--")) {
console.error(`⚠️ 未知参数: ${a}`);
} else {
console.error(`⚠️ 忽略参数: ${a}`);
}
}
}
if (port === null) port = 9222;
if (!Number.isInteger(port) || port < 1 || port > 65535) {
console.error(`❌ 端口非法: ${port}。必须是 1-65535 的整数。`);
process.exit(1);
}
return { flags, profile, profileExplicit, port };
}
const ARGS = parseArgs(process.argv.slice(2));
const CDP_PORT = ARGS.port;
const PLATFORM = os.platform();
// ---------------------------------------------------------------------------
// 平台配置映射
// ---------------------------------------------------------------------------
const PLATFORM_CONFIG = {
darwin: {
chromePaths: [
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
],
profileDir: path.join(
os.homedir(),
"Library",
"Application Support",
"Google",
"Chrome"
),
findChrome() {
for (const p of this.chromePaths) if (fs.existsSync(p)) return p;
return null;
},
listChromePids() {
try {
const out = execSync("pgrep -x 'Google Chrome'", { encoding: "utf-8" }).trim();
return out.split("\n").map(Number).filter((n) => n > 0);
} catch { return []; }
},
killChrome() {
try { execSync("pkill -9 -x 'Google Chrome'", { stdio: "ignore" }); } catch {}
},
},
win32: {
chromePaths: [
path.join(process.env["PROGRAMFILES(X86)"] || "", "Google", "Chrome", "Application", "chrome.exe"),
path.join(process.env.PROGRAMFILES || "", "Google", "Chrome", "Application", "chrome.exe"),
path.join(process.env.LOCALAPPDATA || "", "Google", "Chrome", "Application", "chrome.exe"),
],
profileDir: path.join(
process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"),
"Google", "Chrome", "User Data"
),
findChrome() {
for (const p of this.chromePaths) if (p && fs.existsSync(p)) return p;
return null;
},
listChromePids() {
try {
const out = execSync('tasklist /FI "IMAGENAME eq chrome.exe" /NH /FO CSV', { encoding: "utf-8" }).trim();
return out.split("\n").map((line) => {
const m = line.match(/"chrome.exe","(\d+)"/i);
return m ? parseInt(m[1], 10) : 0;
}).filter((n) => n > 0);
} catch { return []; }
},
killChrome() {
try { execSync("taskkill /F /IM chrome.exe", { stdio: "ignore" }); } catch {}
},
},
linux: {
chromePaths: [
"/usr/bin/google-chrome-stable",
"/usr/bin/google-chrome",
"/opt/google/chrome/google-chrome",
],
profileDir: path.join(os.homedir(), ".config", "google-chrome"),
findChrome() {
for (const p of this.chromePaths) if (fs.existsSync(p)) return p;
return null;
},
listChromePids() {
// 覆盖常见的 Chrome 进程命名
const patterns = ["google-chrome-stable", "google-chrome", "chrome"];
const pids = new Set();
for (const pat of patterns) {
try {
const out = execSync(`pgrep -x ${pat}`, { encoding: "utf-8" }).trim();
out.split("\n").map(Number).filter((n) => n > 0).forEach((n) => pids.add(n));
} catch {}
}
return [...pids];
},
killChrome() {
for (const pat of ["google-chrome-stable", "google-chrome", "chrome"]) {
try { execSync(`pkill -9 -x ${pat}`, { stdio: "ignore" }); } catch {}
}
},
},
};
// ---------------------------------------------------------------------------
// 工具函数
// ---------------------------------------------------------------------------
function log(msg) { console.log(msg); }
function warn(msg) { console.warn("⚠️ " + msg); }
function ok(msg) { console.log("✅ " + msg); }
function err(msg) { console.error("❌ " + msg); }
function getConfig() {
const config = PLATFORM_CONFIG[PLATFORM];
if (!config) {
err(`不支持的平台: ${PLATFORM}。支持 darwin/win32/linux。`);
process.exit(1);
}
return config;
}
/** 同步等待 ms 毫秒(不依赖 setTimeout / 系统 sleep) */
function sleepSync(ms) {
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
}
/**
* HTTP GET 检查 CDP 端点。拒绝 4xx/5xx;自动 drain 掉响应体。
* agent:false 是必须的——Node 19+ 的 http.globalAgent 默认 keepAlive,探测用过的 socket 会留在
* 连接池里;而本脚本用 sleepSync 死堵事件循环(等进程退出/等启动),期间服务端按 5s 空闲把这条
* 连接关掉,客户端来不及处理 FIN。下一次探测复用这条死 socket 就是 ECONNRESET,于是"端口还活着"
* 被误判成"没人应答"。这种假阴性会直接骗过下面的端口闸门,必须一次一条新连接。
*/
function httpGet(url) {
return new Promise((resolve, reject) => {
const req = http.get(url, { timeout: 3000, agent: false }, (res) => {
let body = "";
res.on("data", (chunk) => (body += chunk));
res.on("end", () => {
if (res.statusCode >= 400) {
reject(new Error(`HTTP ${res.statusCode}`));
} else {
resolve(body);
}
});
});
req.on("error", reject);
req.on("timeout", () => {
req.destroy();
reject(new Error("timeout"));
});
});
}
async function probeCDP(port) {
try {
const version = await httpGet(`http://127.0.0.1:${port}/json/version`);
return version;
} catch {
return null;
}
}
/** 原始 TCP 探测:HTTP 500/畸形 JSON 仍表示端口被占用,不能据此解锁 profile 破坏操作。 */
function probeTcp(port, timeoutMs = 1000) {
return new Promise((resolve) => {
const socket = net.createConnection({ host: "127.0.0.1", port });
let settled = false;
const done = (listening) => {
if (settled) return;
settled = true;
socket.destroy();
resolve(listening);
};
socket.setTimeout(timeoutMs);
socket.once("connect", () => done(true));
socket.once("error", () => done(false));
socket.once("timeout", () => done(false));
});
}
/**
* 从 /json/version 响应里取一个能区分「实例」的标识。
* Chrome 每次启动都会换一个新的 browser GUID(webSocketDebuggerUrl 尾段),最适合做这件事。
* 取不到就返回 null——调用方必须把 null 当作「无法比对」,绝不能当作「相同」或「不同」。
*/
function cdpIdentity(version) {
if (!version) return null;
try {
const obj = JSON.parse(version);
if (obj.webSocketDebuggerUrl) return String(obj.webSocketDebuggerUrl);
} catch {}
return null;
}
/**
* 等 TCP 端口真的不再监听;true = 端口已空出来,false = 超时后仍有人监听。
* 不能用 probeCDP:HTTP 500/畸形响应只说明“不是健康 CDP”,不说明“端口空闲”。
*/
async function waitForPortFree(port, maxMs = 8000, stepMs = 500, needQuiet = 2) {
const start = Date.now();
let quiet = 0;
for (;;) {
if (await probeTcp(port)) {
quiet = 0;
} else if (++quiet >= needQuiet) {
return true;
}
if (Date.now() - start >= maxMs) return false;
sleepSync(stepMs);
}
}
/** 尽力查出占用端口的进程,只用于诊断(查不到就返回 null,不影响判定) */
function describePortHolder(port) {
const cmd =
PLATFORM === "win32"
? `netstat -ano -p tcp | findstr LISTENING | findstr :${port}`
: `lsof -nP -iTCP:${port} -sTCP:LISTEN`;
try {
const out = execSync(cmd, {
encoding: "utf-8",
stdio: ["ignore", "pipe", "ignore"],
}).trim();
const line = out
.split("\n")
.map((l) => l.trim())
.filter((l) => l && !/^COMMAND\s/.test(l))[0];
return line ? line.slice(0, 200) : null;
} catch {
return null;
}
}
/** 跑一条只读的查询命令,拿 stdout;命令不存在/非零退出/超时一律返回 null */
function queryStdout(cmd) {
try {
const out = execSync(cmd, {
encoding: "utf-8",
stdio: ["ignore", "pipe", "ignore"],
timeout: 5000,
maxBuffer: 8 * 1024 * 1024,
});
return typeof out === "string" ? out : String(out);
} catch {
return null;
}
}
/**
* 列出正在 LISTEN 指定端口的进程 pid。
* 只在「已经探到 CDP 应答」之后调用——那一刻端口必然有人在监听,所以空结果只可能是
* 工具缺失或看不见,一律返回 null 表示「无从判断」,绝不能被当成「没人占用」而放行。
*/
function listPortListenerPids(port) {
const queries =
PLATFORM === "win32"
? [
{
kind: "pid",
cmd: `powershell -NoProfile -NonInteractive -Command "Get-NetTCPConnection -State Listen -LocalPort ${port} -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess"`,
},
{
kind: "pid",
cmd: `pwsh -NoProfile -NonInteractive -Command "Get-NetTCPConnection -State Listen -LocalPort ${port} -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess"`,
},
{ kind: "netstat", cmd: "netstat -ano -p tcp" },
]
: [
{ kind: "pid", cmd: `lsof -nP -iTCP:${port} -sTCP:LISTEN -t` },
// Linux 上 lsof 经常不预装,用 ss / fuser 兜底
{ kind: "ss", cmd: `ss -H -ltnp "sport = :${port}"` },
{ kind: "pid", cmd: `fuser -n tcp ${port}` },
];
for (const { kind, cmd } of queries) {
const out = queryStdout(cmd);
if (out === null) continue;
const pids = new Set();
if (kind === "netstat") {
// 不读取本地化的状态文字。监听行的稳定形状是 TCP + 本地目标端口 +
// foreign port 0 + 最后一列 Owning PID;已建立连接的 foreign port 非 0。
for (const line of out.split("\n")) {
const fields = line.trim().split(/\s+/);
if (fields.length < 5 || fields[0].toUpperCase() !== "TCP") continue;
const localPort = Number((fields[1].match(/:(\d+)$/) || [])[1]);
const foreignPort = Number((fields[2].match(/:(\d+)$/) || [])[1]);
const pid = Number(fields[fields.length - 1]);
if (localPort === port && foreignPort === 0 && Number.isInteger(pid) && pid > 0) {
pids.add(pid);
}
}
} else if (kind === "ss") {
for (const m of out.matchAll(/pid=(\d+)/g)) pids.add(Number(m[1]));
} else {
// PowerShell OwningProcess / lsof -t / fuser:一堆纯数字 pid
for (const tok of out.split(/\s+/)) {
const n = Number(tok);
if (Number.isInteger(n) && n > 0) pids.add(n);
}
}
const list = [...pids].filter((n) => n > 0);
if (list.length > 0) return list;
}
return null;
}
/** 全机 pid -> ppid 表;查不到返回 null(无从判断,不是「没有父进程」) */
function listProcessParents() {
const cmds =
PLATFORM === "win32"
? [
// wmic 在新版 Windows 上已被移除,退回 PowerShell CIM(5.1 / 7 都试)
"wmic process get ProcessId,ParentProcessId /format:csv",
'powershell -NoProfile -NonInteractive -Command "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId | ConvertTo-Csv -NoTypeInformation"',
'pwsh -NoProfile -NonInteractive -Command "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId | ConvertTo-Csv -NoTypeInformation"',
]
: ["ps -A -o pid=,ppid="]; // macOS(BSD) 与 Linux(procps) 都认这一条
for (const cmd of cmds) {
const out = queryStdout(cmd);
if (out === null) continue;
const map = new Map();
if (PLATFORM === "win32") {
// 两个来源的列序不一样(wmic 按字母序,PowerShell 按 Select 顺序),按表头定位
const lines = out.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
const head = lines.findIndex(
(l) => /processid/i.test(l) && /parentprocessid/i.test(l)
);
if (head < 0) continue;
const cols = lines[head]
.split(",")
.map((c) => c.replace(/"/g, "").trim().toLowerCase());
const pidCol = cols.indexOf("processid");
const ppidCol = cols.indexOf("parentprocessid");
if (pidCol < 0 || ppidCol < 0) continue;
for (const line of lines.slice(head + 1)) {
const cells = line.split(",").map((c) => c.replace(/"/g, "").trim());
const pid = Number(cells[pidCol]);
const ppid = Number(cells[ppidCol]);
if (pid > 0 && Number.isInteger(ppid)) map.set(pid, ppid);
}
} else {
for (const line of out.split("\n")) {
const m = line.trim().match(/^(\d+)\s+(\d+)$/);
if (m) map.set(Number(m[1]), Number(m[2]));
}
}
if (map.size > 0) return map;
}
return null;
}
/** 取某个 pid 的完整命令行;取不到返回 null */
function processCommandLine(pid) {
const cmds =
PLATFORM === "win32"
? [
`wmic process where "ProcessId=${pid}" get CommandLine /value`,
`powershell -NoProfile -NonInteractive -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CommandLine"`,
`pwsh -NoProfile -NonInteractive -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CommandLine"`,
]
: [`ps -ww -o command= -p ${pid}`]; // -ww:不许按终端宽度截断,Chrome 的命令行很长
for (const cmd of cmds) {
const out = queryStdout(cmd);
if (out === null) continue;
const text =
PLATFORM === "win32" ? out.replace(/^\s*CommandLine=/im, "") : out;
const trimmed = text.trim();
if (trimmed) return trimmed;
}
return null;
}
/** pid 是否在 rootPid 的进程树里(含 rootPid 本身);沿 ppid 往上走 */
function isInProcessTree(pid, rootPid, parents) {
let cur = pid;
for (let hops = 0; hops < 64; hops++) {
if (cur === rootPid) return true;
if (!Number.isInteger(cur) || cur <= 1) return false;
const next = parents.get(cur);
if (next === undefined || next === cur) return false;
cur = next;
}
return false;
}
function commandLineHasArgument(commandLine, argument) {
const escaped = argument.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
return new RegExp(`(?:^|[\\s"'])${escaped}(?=$|[\\s"'])`).test(commandLine);
}
/**
* 证明端口上应答的那个端点确实归本次 spawn 出来的进程所有。两件事都要成立:
* ① 端口上所有 LISTEN 持有者都在 rootPid 这棵进程树里——Chrome 会另起 browser 进程,
* macOS 上启动的二进制还可能 re-exec,所以比的是整棵树而不是直系 pid;反过来,
* 子进程继承了监听 fd 也会被 lsof 列出来,所以要求「全都在树里」而不是「有一个在」。
* ② 树里确实有一个持有者带着本次启动的 --remote-debugging-port=<port>——证明应答的是
* 我们配出来的那个实例,而不是树里某个别的进程顺手占了这个端口。
* 任何一步查不出来都返回 unverifiable:宁可硬失败,也不能把「证明不了」当成「证明了」。
*/
function verifyPortOwnedByLaunch(port, rootPid) {
const fail = (code, lines) => ({ ok: false, code, lines: [`${code}: ${lines[0]}`, ...lines.slice(1)] });
const unverifiable = (why) =>
fail("CDP_OWNER_UNVERIFIABLE", [
`无法确认端口 ${port} 的 LISTEN 持有者归属(${why})。`,
"拒绝报成功:证明不了这个端点属于本次启动,就不能把它交给后续采集。",
PLATFORM === "win32"
? "本机需要 netstat 加 wmic 或 PowerShell 才能查进程归属。"
: "本机需要 lsof(或 ss / fuser)加 ps 才能查进程归属。",
`处理办法:装上上述工具后重跑,或手动确认 ${port} 上跑的确实是刚启动的 Chrome。`,
]);
if (!rootPid) return unverifiable("spawn 没拿到 pid");
const listeners = listPortListenerPids(port);
if (!listeners) return unverifiable("查不到监听该端口的进程");
// 持有者就是 spawn 出来的那个 pid 时不必读进程表——最常见的形态(Chrome 的 browser
// 进程就是我们启动的那个)因此不依赖 wmic/ps 之外的任何东西
let outside = listeners.filter((pid) => pid !== rootPid);
if (outside.length > 0) {
const parents = listProcessParents();
if (!parents) return unverifiable("读不到进程表(pid/ppid)");
outside = outside.filter((pid) => !isInProcessTree(pid, rootPid, parents));
}
if (outside.length > 0) {
const holder = describePortHolder(port);
return fail("CDP_PORT_NOT_OURS", [
`端口 ${port} 的 LISTEN 持有者(pid ${outside.join(", ")})不在本次启动的进程树里(根 pid ${rootPid})。`,
"拒绝报成功:端口被别的进程握着,再往下用,每一次采集读到的都是别人的会话。",
...(holder ? [`占用者:${holder}`] : []),
`处理办法:结束占用 ${port} 的进程后重跑,或换一个端口。`,
]);
}
const marker = `--remote-debugging-port=${port}`;
let sawCommandLine = false;
for (const pid of listeners) {
const cmdline = processCommandLine(pid);
if (cmdline === null) continue;
sawCommandLine = true;
if (commandLineHasArgument(cmdline, marker)) return { ok: true, pids: listeners, pid };
}
if (!sawCommandLine) return unverifiable("读不到持有者的命令行");
return fail("CDP_OWNER_NOT_LAUNCHED_INSTANCE", [
`端口 ${port} 的 LISTEN 持有者(pid ${listeners.join(", ")})在本次启动的进程树里,但没有一个带着 ${marker}。`,
"拒绝报成功:应答的不是本次启动的那个 Chrome,只是同一棵树里另一个占了这个端口的进程。",
`处理办法:确认 ${port} 没被别的进程占用,或换一个端口重跑。`,
]);
}
/** spawn 出来的 Chrome 是否还活着(exitCode/signalCode 权威,兜底 kill(pid,0)) */
function isChildAlive(child) {
if (!child || !child.pid) return false;
if (child.exitCode !== null || child.signalCode !== null) return false;
try {
process.kill(child.pid, 0);
return true;
} catch {
return false;
}
}
function isPidAlive(pid) {
if (!Number.isInteger(pid) || pid <= 0) return false;
try {
process.kill(pid, 0);
return true;
} catch {
return false;
}
}
/** 只清理由本次 spawn 拉起的进程树;绝不调用全局 killChrome 连坐用户的其他窗口。 */
function terminateLaunchTree(rootPid) {
if (!Number.isInteger(rootPid) || rootPid <= 0) return;
if (PLATFORM === "win32") {
try {
execSync(`taskkill /F /T /PID ${rootPid}`, { stdio: "ignore" });
} catch {}
return;
}
const parents = listProcessParents();
const tree = [];
if (parents) {
for (const pid of parents.keys()) {
if (pid !== process.pid && isInProcessTree(pid, rootPid, parents)) tree.push(pid);
}
}
if (!tree.includes(rootPid)) tree.push(rootPid);
// 子孙先停、launcher 最后停,避免 detached listener 在父进程先死后被 reparent 而丢失归属。
const depth = (pid) => {
let current = pid;
for (let hops = 0; hops < 64; hops++) {
if (current === rootPid) return hops;
const next = parents?.get(current);
if (!next || next === current) return -1;
current = next;
}
return -1;
};
tree.sort((left, right) => depth(right) - depth(left));
for (const pid of tree) {
try { process.kill(pid, "SIGTERM"); } catch {}
}
sleepSync(200);
for (const pid of tree) {
if (!isPidAlive(pid)) continue;
try { process.kill(pid, "SIGKILL"); } catch {}
}
}
/** 复制文件(吞掉 ENOENT;其他错误打印一次警告供用户排查) */
function copyFileSafe(src, dest) {
try {
fs.copyFileSync(src, dest);
return true;
} catch (e) {
if (e.code !== "ENOENT") {
warn(`复制失败: ${src} -> ${dest} (${e.code || e.message})`);
}
return false;
}
}
/** 递归复制目录 */
function copyDirRecursive(src, dest) {
fs.cpSync(src, dest, { recursive: true, force: true });
}
/** 递归删除目录 */
function rmDirSafe(dir) {
fs.rmSync(dir, { recursive: true, force: true });
}
/**
* 刷新登录态相关文件(在 debugProfile 已存在的"增量"路径上使用)。
* 同时尝试 Chrome 当前可能存在的 Default/Cookies 与 Default/Network/Cookies,
* 包含各类 -journal / -wal / -shm 旁路文件,以及 Google 账号登录数据。
*/
function refreshAuthFiles(srcDefault, destDefault) {
const bases = [
"Cookies",
"Login Data",
"Login Data For Account",
"Web Data",
path.join("Network", "Cookies"),
];
const suffixes = ["", "-journal", "-wal", "-shm"];
let copied = 0;
for (const base of bases) {
for (const suffix of suffixes) {
const rel = `${base}${suffix}`;
const src = path.join(srcDefault, rel);
if (!fs.existsSync(src)) continue;
const dest = path.join(destDefault, rel);
fs.mkdirSync(path.dirname(dest), { recursive: true });
if (copyFileSafe(src, dest)) copied++;
}
}
return copied;
}
/** 清理 Chrome singleton 锁,避免上次崩溃后下次启动失败 */
function clearSingletonLocks(profileDir) {
const names = ["SingletonLock", "SingletonCookie", "SingletonSocket"];
for (const n of names) {
try { fs.unlinkSync(path.join(profileDir, n)); } catch {}
}
}
/** 等待 Chrome PID 列表为空 */
function waitForChromeExit(config, maxMs = 8000, stepMs = 500) {
const start = Date.now();
while (Date.now() - start < maxMs) {
if (config.listChromePids().length === 0) return true;
sleepSync(stepMs);
}
return false;
}
/** TTY 交互式问询 */
function promptYesNo(question) {
return new Promise((resolve) => {
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
rl.question(question, (answer) => {
rl.close();
resolve(/^y(es)?$/i.test((answer || "").trim()));
});
});
}
// ---------------------------------------------------------------------------
// detect-only 模式
// ---------------------------------------------------------------------------
async function runDetectOnly(config) {
const version = await probeCDP(CDP_PORT);
if (version) {
log("CDP_STATUS=ready");
log(`CDP_URL=http://127.0.0.1:${CDP_PORT}/json/version`);
// 尝试从 JSON 提取浏览器版本(容错)
try {
const obj = JSON.parse(version);
if (obj.Browser) log(`BROWSER=${obj.Browser}`);
} catch {}
process.exit(0);
}
log("CDP_STATUS=needs-setup");
const pids = config.listChromePids();
if (pids.length > 0) {
log("CHROME_RUNNING=yes");
log(`CHROME_PID_COUNT=${pids.length}`);
} else {
log("CHROME_RUNNING=no");
}
process.exit(0);
}
// ---------------------------------------------------------------------------
// 同意流程:返回 true 继续,false 用户拒绝
// ---------------------------------------------------------------------------
async function ensureConsentToKill(pids) {
if (pids.length === 0) return true;
if (ARGS.flags.yes) return true;
// 非 TTY:拒绝静默杀进程,给调用方(Claude / 上层脚本)一个明确信号
if (!process.stdin.isTTY) {
err(`NEEDS_CONSENT: ${pids.length} running Chrome process(es) will be killed.`);
err(`Pass --yes to confirm (after asking the user), or stop Chrome manually first.`);
process.exit(3);
}
// TTY:交互问询
warn(`检测到 ${pids.length} 个正在运行的 Chrome 进程。`);
warn("继续将杀死它们,你在常规 Chrome 中未保存的工作可能丢失。");
return promptYesNo("继续?[y/N] ");
}
// ---------------------------------------------------------------------------
// 主流程
// ---------------------------------------------------------------------------
async function main() {
const config = getConfig();
const debugProfile = path.join(os.homedir(), "chrome-debug-profile");
// 1) 检测 Chrome 可执行路径(detect-only 也需要 profileDir)
const chromePath = config.findChrome();
// detect-only:不修改任何状态
if (ARGS.flags.detectOnly) {
if (!chromePath) {
log("CDP_STATUS=needs-setup");
log("CHROME_INSTALLED=no");
process.exit(0);
}
return runDetectOnly(config);
}
log("=== CDP Chrome 环境准备 ===");
log(`平台: ${PLATFORM} | CDP 端口: ${CDP_PORT} | profile: ${ARGS.profile}`);
if (!chromePath) {
err("未找到 Google Chrome。请确保已安装。");
err(`搜索路径: ${JSON.stringify(config.chromePaths, null, 2)}`);
process.exit(1);
}
log(`Chrome 路径: ${chromePath}`);
// 2) dry-run:先于任何副作用(包括"复用现有 CDP")打印计划,让用户能看到真要执行时的步骤
const defaultProfile = path.join(config.profileDir, ARGS.profile);
const hasProfile = fs.existsSync(defaultProfile);
if (ARGS.flags.dryRun) {
const cdpAlive = !!(await probeCDP(CDP_PORT));
const tcpOccupied = await probeTcp(CDP_PORT);
// --reset / 显式 --profile 会跳过复用(见下方第 3 步),dry-run 必须照实说
const willReuse = cdpAlive && !ARGS.flags.reset && !ARGS.profileExplicit;
const cdpNote = !tcpOccupied
? "未监听"
: !cdpAlive
? "有 TCP 监听,但不是健康 CDP(实际运行会在动 profile 前硬失败)"
: willReuse
? "已就绪(实际运行时会直接复用)"
: "已就绪(但传了 --reset/--profile,实际运行会重建,不复用)";
log(`Chrome profile: ${defaultProfile} (${hasProfile ? "存在" : "不存在"})`);
log(`CDP 端口 ${CDP_PORT}: ${cdpNote}`);
const runningPids = config.listChromePids();
log(`检测到 ${runningPids.length} 个 Chrome 进程`);
log("\n--- dry-run 模式:只打印操作,不执行 ---");
if (willReuse) {
log("0. CDP 已就绪,实际运行会直接复用并退出 0(以下步骤仅供参考)");
} else if (cdpAlive) {
log("0. CDP 已就绪,但传了 --reset/--profile:实际运行不复用,按下列步骤重建");
}
// 步骤号按真实执行顺序动态编号:先杀进程、再确认端口空了,之后才碰 profile 目录
let stepNo = 0;
const step = (msg) => log(`${++stepNo}. ${msg}`);
if (runningPids.length > 0) {
step(`${ARGS.flags.yes ? "(已同意)" : "请求同意后 "}杀死 ${runningPids.length} 个 Chrome 进程`);
} else {
step("无 Chrome 进程,无需杀死");
}
step(`用 TCP 确认端口 ${CDP_PORT} 已释放(任何监听仍在都中止:不删 profile、不启动)`);
if (ARGS.flags.reset) step(`删除 ${debugProfile}`);
if (hasProfile) {
step(`复制 profile: ${defaultProfile} -> ${debugProfile}/Default`);
} else {
step("⚠️ 无用户 profile,将以空 profile 启动");
}
step("清理 SingletonLock / SingletonCookie / SingletonSocket");
step("启动 Chrome(含 --remote-allow-origins=*, --no-first-run 等)");
step(
`验证 http://127.0.0.1:${CDP_PORT}/json/version 来自本次启动的实例` +
"(身份取得到且已变 + 进程存活 + 端口的 LISTEN 持有者就在这棵进程树里)"
);
ok("dry-run 完成。");
process.exit(0);
}
// 3) 若 CDP 已就绪 → 复用,直接退出。
// 但 --reset / 显式 --profile 的语义就是"重建 debug profile":登录态过期时文档正是
// 让用户跑 --reset,而那时 CDP 恰恰是活着的(过期是从这个会话里发现的)。若照旧复用,
// 这两个参数会被静默丢掉,还以 exit 0 报"成功"。因此这两种情况不复用,继续往下重建。
const existing = await probeCDP(CDP_PORT);
const portWasListening = await probeTcp(CDP_PORT);
if (existing) {
if (!ARGS.flags.reset && !ARGS.profileExplicit) {
ok("CDP 已就绪,复用现有 Chrome。");
log(existing.split("\n").slice(0, 5).join("\n"));
process.exit(0);
}
const requested = ARGS.flags.reset ? "--reset" : `--profile ${ARGS.profile}`;
warn(`CDP 端口 ${CDP_PORT} 已在监听,但传了 ${requested}:不复用,将关闭现有 Chrome 后重建 debug profile。`);
}
// 重建前那个实例的身份:第 10 步要靠它证明「应答的是新起的实例」,而不只是「有人应答」
const staleIdentity = cdpIdentity(existing);
if (!hasProfile) {
err(`未找到 Chrome profile: ${defaultProfile}`);
err("请确保已安装 Google Chrome 并至少使用过一次,或用 --profile <name> 指定其他 profile。");
process.exit(1);
}
// 4) 同意流程:如有 Chrome 进程要杀,先征得同意
const runningPids = config.listChromePids();
const consented = await ensureConsentToKill(runningPids);
if (!consented) {
err("用户拒绝,已中止。");
process.exit(2);
}
// 5) 杀死现有 Chrome 进程,等待退出
if (runningPids.length > 0) {
log(`正在停止 ${runningPids.length} 个 Chrome 进程...`);
config.killChrome();
if (!waitForChromeExit(config, 6000)) {
warn("首轮 kill 后仍有 Chrome 进程,再试一次...");
config.killChrome();
waitForChromeExit(config, 4000);
}
const remain = config.listChromePids();
if (remain.length > 0) {
err(`仍有 ${remain.length} 个 Chrome 进程未退出,已中止。`);
err("未删除、未改动 debug profile,也未启动新 Chrome——状态保持原样。");
process.exit(1);
} else {
ok("Chrome 已退出。");
}
}
// 5.5) 硬闸门:端口必须真的空出来,才允许动 profile 目录、才允许启动新实例。
// 顺序是刻意的——闸门在删 profile 之前。旧实例还活着就往下走会撞上最坏的一种结果:
// 先删掉一个正在运行的 Chrome 的 profile(本身就是破坏性的),新进程又因端口被占起不来,
// 而第 10 步的 probeCDP 恰好被旧端点答上,于是 exit 0 报「重建成功」——调用方以为拿到了
// 新浏览器,之后每一次采集读的都是旧会话/别人的会话。这里只能硬失败。
// 无论 /json/version 是否健康都执行:HTTP 500 也可能正占着端口。
// 杀过进程才值得给宽限期;没有已识别 Chrome 时,占用者不会自己退出,快速确认后失败。
const graceMs = runningPids.length > 0 ? 8000 : 1000;
if (!(await waitForPortFree(CDP_PORT, graceMs))) {
const remain = config.listChromePids();
err(
existing
? `CDP 端口 ${CDP_PORT} 上的旧实例仍在应答,已中止。`
: `CDP 端口 ${CDP_PORT} 仍被占用、未释放,已中止。`
);
if (remain.length > 0) {
err(`原因:${remain.length} 个 Chrome 进程没能退出(kill 无效,可能权限不足或进程卡死)。`);
} else if (runningPids.length === 0) {
err("原因:端口被无法识别的进程占用——没找到任何 Chrome 进程,脚本无从关闭它。");
} else {
err("原因:Chrome 进程已退出,但另有进程仍守着这个端口。");
}
const holder = describePortHolder(CDP_PORT);
if (holder) err(`占用者:${holder}`);
err("未删除、未改动 debug profile,也未启动新 Chrome——状态保持原样。");
err(`处理办法:手动结束占用 ${CDP_PORT} 的进程后重跑,或换一个端口(node setup-cdp-chrome.js <其他端口> ...)。`);
process.exit(1);
}
if (portWasListening) {
ok(`CDP 端口 ${CDP_PORT} 已释放。`);
}
// 6) --reset:清空 debug profile
if (ARGS.flags.reset) {
log(`正在删除 debug profile: ${debugProfile}`);
rmDirSafe(debugProfile);
}
// 7) 复制 / 刷新 profile(此时 Chrome 已关闭,SQLite 一致;顺带同步上层 Local State 供解密 Cookie)
const debugDefault = path.join(debugProfile, "Default");
const srcLocalState = path.join(config.profileDir, "Local State");
if (!fs.existsSync(debugDefault)) {
log("正在复制 Chrome profile 到 debug 目录...");
fs.mkdirSync(debugProfile, { recursive: true });
try { fs.chmodSync(debugProfile, 0o700); } catch {}
if (fs.existsSync(srcLocalState)) {
copyFileSafe(srcLocalState, path.join(debugProfile, "Local State"));
}
copyDirRecursive(defaultProfile, debugDefault);
ok(`Profile 已复制到: ${debugProfile}`);
} else {
log("debug profile 已存在,刷新登录态相关文件...");
try { fs.chmodSync(debugProfile, 0o700); } catch {}
if (fs.existsSync(srcLocalState)) {
copyFileSafe(srcLocalState, path.join(debugProfile, "Local State"));
}
const n = refreshAuthFiles(defaultProfile, debugDefault);
ok(`已刷新 ${n} 个登录态文件`);
}
// 8) 清理 singleton 锁
clearSingletonLocks(debugProfile);
// 9) 以 CDP 模式启动 Chrome
log(`正在以 CDP 模式启动 Chrome(端口 ${CDP_PORT})...`);
const chromeArgs = [
`--remote-debugging-port=${CDP_PORT}`,
`--user-data-dir=${debugProfile}`,
"--remote-allow-origins=*",
"--no-first-run",
"--no-default-browser-check",
"--disable-features=ChromeWhatsNewUI",
];
const child = spawn(chromePath, chromeArgs, { detached: true, stdio: "ignore" });
const childPid = child.pid;
let spawnError = null;
child.on("error", (e) => { spawnError = e; });
child.unref();
/** 启动后验证没过:只清掉自己刚起的进程(端口上那个不是我们的,不该连坐杀别人的 Chrome) */
function abortAfterLaunch(reasons) {
for (const line of reasons) err(line);
err("正在清理刚启动的 Chrome 进程...");
terminateLaunchTree(childPid);
process.exit(1);
}
// 10) 等待启动并验证。光有人应答不算成功——那可能是没被关掉的旧实例,也可能是别的进程
// 顺手占了这个端口。四条全过才算:
// ① 新端点的 browser GUID 取得到(取不到=无法比对,按合约不能当作相同或不同);
// ② 这个 GUID 与重建前不同(配合第 5.5 步已确认旧端点消失过);
// ③ 刚 spawn 的进程还活着(它死了,端口上应答的就一定不是本次启动的实例);
// ④ 端口的 LISTEN 持有者确实在这棵 spawn 出来的进程树里,且带着本次的
// --remote-debugging-port。前三条都是间接证据——「旧端点消失过 + 身份变了 +
// launcher 还活着」推不出「端口归它」,只有第 ④ 条才真的把端口和进程绑上。
log("等待 Chrome 启动...");
let identityMisses = 0;
for (let i = 1; i <= 15; i++) {
sleepSync(2000);
if (spawnError) {
abortAfterLaunch([`启动 Chrome 失败: ${spawnError.message}`]);
}
const version = await probeCDP(CDP_PORT);
if (version) {
const identity = cdpIdentity(version);
if (identity === null) {
// 端点刚起来时理论上可能先答上 HTTP,给两轮宽限;之后仍取不到就硬失败。
if (++identityMisses < 3) {
log(` 端口有应答但取不到实例身份,重试 ${identityMisses}/3...`);
continue;
}
abortAfterLaunch([
`CDP_IDENTITY_UNVERIFIABLE: 端口 ${CDP_PORT} 有 HTTP 应答,但 /json/version 里取不到实例身份(webSocketDebuggerUrl)。`,
"拒绝报成功:身份取不到就无法证明这是新起的实例——按合约它既不算相同也不算不同,只能当作没证出来。",
`处理办法:确认 ${CDP_PORT} 上跑的是 Chrome 的 CDP 端点(而不是别的 HTTP 服务),或换一个端口重跑。`,
]);
}
if (staleIdentity && identity === staleIdentity) {
abortAfterLaunch([
`端口 ${CDP_PORT} 应答的仍是重建前那个实例(${identity}),不是新启动的 Chrome。`,
"拒绝报成功:再往下用,每一次采集读到的都会是旧会话。",
]);
}
if (!isChildAlive(child)) {
const holder = describePortHolder(CDP_PORT);
abortAfterLaunch([
`端口 ${CDP_PORT} 上有 CDP 应答,但刚启动的 Chrome(pid ${childPid})已经退出。`,
"拒绝报成功:这个端点不属于本次启动的实例。",
...(holder ? [`占用者:${holder}`] : []),
`处理办法:确认 ${CDP_PORT} 没被别的进程占用,或换一个端口重跑。`,
]);
}
const owner = verifyPortOwnedByLaunch(CDP_PORT, childPid);
if (!owner.ok) abortAfterLaunch(owner.lines);
ok(`Chrome 已成功以 CDP 模式启动(端口 ${CDP_PORT})`);
log(version.split("\n").slice(0, 5).join("\n"));
process.exit(0);
}
log(` 尝试 ${i}/15...`);
}
// 11) 失败清理:杀死刚才启动的孤儿 Chrome
err("30 秒内未能启动 Chrome CDP 环境。");
err("正在清理刚启动的 Chrome 进程...");
terminateLaunchTree(childPid);
err("可能原因:");
err(" - Chrome 不支持 --remote-debugging-port");
err(` - 端口 ${CDP_PORT} 已被其他进程占用`);
err(" - debug profile 目录已损坏(试试 --reset)");
process.exit(1);
}
main().catch((e) => {
err(`启动失败: ${e.message}`);
process.exit(1);
});
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |