CDP浏览器大师

通过用户已登录的浏览器（Edge/Chrome）执行自动化任务。核心技术：CDP（Chrome DevTools Protocol），通过WebSocket与浏览器通信。核心信条：优先用web_fetch，CDP只用于JS渲染或需登录态的场景；先探测再定位，多备选降级。

四大痛点与对策

何时用CDP

优先用web_fetch。以下情况才用CDP：

架构概览

Agent
  ↓ require('./cdp-automation.js')
连接管理器（端口复用 + 残留清理）
  ↓ WebSocket (HTTP → CDP)
用户浏览器（Edge:9222 / Chrome:9223）
  ↓ 执行JS / 读DOM / 点击
目标网站

快速开始

1. 开启浏览器远程调试

Edge（端口9222）：

taskkill /F /IM msedge.exe /T
Start-Sleep 3
Start-Process "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222

Chrome（端口9223）：

Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9223

2. 调用

const { edge, chrome } = require('./cdp-automation.js');

await edge.goto('https://目标网站.com');
const data = await edge.eval(`document.title`);
await edge.click('[class*="radio-filter__item"]');
await edge.waitNetworkIdle();  // 智能等待
const result = await edge.eval(`提取数据的JS`);
const png = await edge.screenshot();

API参考

browser.goto(url)

导航到指定URL，等待页面加载完成（Page.loadEventFired + 额外2s等待JS渲染）。

await edge.goto('https://space.bilibili.com/151190274/video');

browser.eval(script)

在页面上下文执行JavaScript，返回结果。

// 读取DOM
const r = await edge.eval(`document.title`);
console.log(r.result.value);

// 提取结构化数据
const r = await edge.eval(`
    JSON.stringify(
        Array.from(document.querySelectorAll('.upload-video-card')).slice(0,5).map(c => ({
            title: c.querySelector('.bili-video-card__title')?.innerText,
            play: c.querySelector('.bili-cover-card__stat span')?.innerText
        }))
    )
`);
const videos = JSON.parse(r.result.value);

browser.click(selector)

点击匹配选择器的第一个元素。通过计算元素中心坐标后用document.elementFromPoint模拟点击。

await edge.click('[class*="radio-filter__item"]');

browser.screenshot()

截图当前页面，返回PNG base64字符串。

const png = await edge.screenshot();
require('fs').writeFileSync('/tmp/screenshot.png', Buffer.from(png, 'base64'));

browser.wait(ms)

显式等待，用于等待JS渲染或网络请求。

await edge.wait(3000);

browser.waitNetworkIdle(timeout)

智能等待：检测网络空闲（无请求持续500ms）后继续，替代固定sleep。既不会太快也不会太慢。

await edge.click('.next-page');
await edge.waitNetworkIdle(10000);  // 最多等10秒，网络空闲即继续

browser.tabs()

获取所有标签页列表（不含临时JS上下文）。

const tabs = await edge.tabs();
const bTab = tabs.find(t => t.url.includes('bilibili.com'));

反检测策略

> 反爬检测是CDP自动化第一大拦路虎。

检测维度与规避

启动参数推荐

# Edge反检测启动
Start-Process "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" `
  --remote-debugging-port=9222 `
  --disable-blink-features=AutomationControlled `
  --disable-features=IsolateOrigins,site-per-process

行为拟人化

// 不要瞬间连续操作
await edge.click('.btn');
await edge.wait(500 + Math.random() * 1000);  // 随机500-1500ms
await edge.click('.next');
await edge.waitNetworkIdle(10000);

Cloudflare绕过思路

1. 用真实已登录浏览器（非Headless）
2. 加--disable-blink-features=AutomationControlled
3. 操作间加随机延迟（拟人化）
4. 首次访问后等Cloudflare验证页通过（waitNetworkIdle）
5. 复用已通过验证的会话Cookie

> 注意：强反爬站点（如小红书）可能仍失败。建议先测试能否正常浏览，再尝试自动化。

选择器探测模式

> 网站改版选择器就失效。先探测再定位，多备选降级。

探测流程

// 第一步：先eval探索DOM结构
const structure = await edge.eval(`
    JSON.stringify({
        title: document.title,
        samples: Array.from(document.querySelectorAll('[class*="note"]')).slice(0,3).map(x => ({
            text: x.innerText?.substring(0,100),
            class: x.className?.substring(0,60),
            tag: x.tagName
        }))
    })
`);
console.log(JSON.parse(structure.result.value));

// 第二步：根据探测结果写精确选择器
// 第三步：提供多备选，降级匹配

多备选选择器

async function robustFind(browser, candidates) {
    for (const selector of candidates) {
        const found = await browser.eval(`
            document.querySelector('${selector}') ? true : false
        `);
        if (found.result.value) {
            return selector;  // 第一个命中的就用
        }
    }
    throw new Error(`所有备选选择器都未命中: ${candidates.join(', ')}`);
}

// 使用：从最精确到最宽松
const selector = await robustFind(edge, [
    '.bili-video-card__title',           // 精确class
    '[class*="video-card"] [class*="title"]',  // 模糊class
    'h3.title',                           // 语义tag
    'a[href*="/video/"]'                  // 属性选择器
]);

选择器韧性原则

• 优先用[class*="xxx"]模糊匹配（网站加哈希后缀也能命中）
• 避免用nth-child等位置选择器（布局一变就错）
• 用data-*属性（业务标识比class稳定）
• 提供语义备选（如h3.title、a[href*="/video/"]）

SPA导航模式

> Next.js/React等SPA内部路由，直接Page.navigate到子路由会404。

正确做法

// 错误：直接导航到子路由（404）
await edge.goto('https://app.com/user-center/token-plan');  // 404

// 正确：先入可访问页，再JS触发内部跳转
await edge.goto('https://app.com/user-center/basic-information');  // 可访问
await edge.waitNetworkIdle();

// 用JS点击侧边栏菜单（注意：可能是div不是a）
await edge.eval(`
    (function() {
        var allDivs = document.querySelectorAll('div');
        for (var d of allDivs) {
            if (d.innerText && d.innerText.trim() === 'Token Plan'
                && d.className.includes('cursor-pointer')) {
                d.click();
                return 'clicked';
            }
        }
        return 'not found';
    })()
`);
await edge.waitNetworkIdle();  // 等待SPA路由跳转完成

SPA导航规律

• 侧边栏菜单多是<div cursor-pointer>而非<a>
• 不能用CDP Input.dispatchMouseEvent，必须用JS element.click()
• 跳转后URL会变但页面不刷新（纯前端路由）
• 跳转后用waitNetworkIdle等待数据加载

Cookie获取方案

普通Cookie

const cookies = await edge.eval(`document.cookie`);
// 只能拿到非HttpOnly的cookie

HttpOnly Cookie

document.cookie拿不到HttpOnly cookie。方案：

// 方案1：用CDP的Network.getCookies（推荐）
const cdpSession = await edge.getCDPSession();
const { cookies } = await cdpSession.send('Network.getCookies', {
    urls: ['https://目标网站.com']
});
// cookies包含HttpOnly的

// 方案2：从浏览器SQLite文件读（需解决锁文件问题）
// Edge: %LOCALAPPDATA%\Microsoft\Edge\User Data\Default\Cookies
// Chrome: %LOCALAPPDATA%\Google\Chrome\User Data\Default\Cookies

连接管理

端口复用

同一时间每个端口（9222/9223）只能有一个WebSocket连接。ConnectionManager管理复用：

// 模块内部自动复用，无需手动管理
const { edge } = require('./cdp-automation.js');
// 多次调用共享同一连接
await edge.goto(url1);
await edge.goto(url2);  // 复用连接

残留连接清理

任务中途失败可能导致连接残留：

// 清理残留连接
async function cleanupConnection(browser) {
    try {
        await browser.close();
    } catch (e) {
        // 连接已断，忽略
    }
}

// 重启浏览器远程调试（极端情况）
async function restartDebugging(port) {
    // 杀掉占用端口的进程
    const { exec } = require('child_process');
    exec(`taskkill /F /FI "PID eq ${getPidOnPort(port)}"`, () => {
        // 重新启动浏览器
    });
}

端口被占用排查

# 查看端口占用
netstat -ano | findstr :9222

# 杀掉占用进程（如联想Vantage的msedgewebview2.exe）
taskkill /F /PID <pid>

# 再启动你的Edge

平台踩坑库

B站

选择器（已验证）：
- 视频卡片：.upload-video-card
- 标题：.bili-video-card__title
- 播放量：.bili-cover-card__stat span（第一个span）
- "最多播放"tab：[class*="radio-filter__item"]

要点：
- B站页面完全JS渲染，web_fetch拿到的是空壳
- 播放量字段在DOM里是文本（如"1890"），需parseInt(play.replace(/\D/g,''))
- API有wbi签名保护，直接调API不可行，必须走DOM

小红书

注意：
- 有强反自动化检测（UA检测、行为检测）
- 建议先测试是否能正常浏览，再尝试自动化
- 选择器可能随时变，用探测模式先探索

// 先探索页面结构
const r = await edge.eval(`
    JSON.stringify({
        title: document.title,
        samples: Array.from(document.querySelectorAll('[class*="note"]')).slice(0,3).map(x => ({
            text: x.innerText?.substring(0,100),
            class: x.className?.substring(0,60)
        }))
    })
`);

Minimax（platform.minimaxi.com）

查询目标： Token Plan配额（每5小时重置）

已验证路径：
1. 先导航到任意minimaxi页面（需是type=page的标签页）
2. 再导航到/user-center/basic-information（可正常访问）
3. 用JS点击侧边栏的div（注意：不是<a>标签）触发SPA路由
4. 等待跳转后提取配额数据

实际路径规律（Next.js SPA）：
- 账户管理侧边栏是SPA内部路由，URL最终为/user-center/payment/token-plan
- 直接Page.navigate到/user-center/token-plan会404
- 正确做法：先进/user-center/basic-information，再JS点击触发路由跳转

配额数据位置：
- 套餐名：Token Plan / Starter年度套餐
- 剩余量：可用额度：XXX次模型调用 / 5小时
- 已用量：XXX/600

提取脚本：

const r = await edge.eval(`(function(){
  var t = document.body.innerText;
  var plan = t.match(/(Starter|Pro|Enterprise)[^\\n]*/)?.[0];
  var quota = t.match(/可用额度[：:][^\\n]*/)?.[0];
  var used = t.match(/(\\d+)\\/600/)?.[0];
  return JSON.stringify({plan, quota, used});
})()`);

边界情况与陷阱

• CDP连接复用：每端口同时只能一个WebSocket，模块内ConnectionManager管理，失败需重启浏览器
• 等待时间不够：JS密集页面5s可能不够，用waitNetworkIdle智能等待或手动加到8-10s
• Edge被联想Vantage占用端口：杀掉msedgewebview2.exe实例再启动你的Edge
• HttpOnly Cookie：document.cookie拿不到，用CDP Network.getCookies
• Next.js SPA内部导航：直接navigate到子路由404，需先入可访问页再JS点击
• div菜单点击：侧边栏菜单多是<div cursor-pointer>，不能用CDP鼠标事件，必须JS element.click()
• 反爬升级：网站可能随时加强检测，定期验证自动化是否仍有效

FAQ

Q：什么时候该用CDP而不是web_fetch？
A：JS渲染页面、需登录态、需交互（点击/填表）时用CDP。静态HTML用web_fetch即可。

Q：被Cloudflare拦了怎么办？
A：用真实已登录浏览器（非Headless），加--disable-blink-features=AutomationControlled，操作间加随机延迟，首次访问等验证页通过后复用Cookie。

Q：选择器经常失效怎么办？
A：用探测模式——先eval探索DOM结构再定位。提供多备选选择器（从精确class到模糊[class*="xxx"]到语义tag到属性选择器）降级匹配。

Q：Next.js SPA子路由404怎么解决？
A：直接navigate会404。先进入可访问的父页面（如/user-center/basic-information），再用JS点击侧边栏div触发内部路由跳转。

Q：固定sleep该等多久？
A：别用固定sleep。用waitNetworkIdle智能等待——检测无请求持续500ms即继续，既不快也不慢。

Q：怎么拿HttpOnly Cookie？
A：document.cookie拿不到。用CDP的Network.getCookies命令，或从浏览器SQLite文件读（需解决锁文件）。

Q：CDP连接断了怎么办？
A：模块内ConnectionManager会清理。极端情况重启浏览器远程调试——杀掉占用端口的进程再重新启动。

故障排查

模块文件位置

~/.skill-platform/browser-automation/
├── cdp-automation.js   ← 核心模块（不用动）
└── SKILL.md            ← 本文件

调用时：

const { edge, chrome } = require('~/.skill-platform/browser-automation/cdp-automation.js');

依赖说明

运行环境

• Agent平台：支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统：Windows（Edge/Chrome路径示例为Windows，macOS/Linux类似）
• 浏览器：Microsoft Edge 或 Google Chrome（已安装并可启动远程调试）

第三方依赖

API Key 配置

• 本skill基于本地浏览器自动化，无需额外API Key
• 涉及需登录的网站时，使用用户已登录的浏览器会话（无需配置凭证）

可用性分类

• 分类：MD+EXEC（Markdown指令 + Node.js脚本执行）
• 说明：通过自然语言指令驱动Agent调用cdp-automation.js控制浏览器执行自动化