back
loading skill details...
通过已登录的Edge/Chrome浏览器执行JS渲染页面自动化，含导航、点击、截图与数据提取。
---
name: "cdp-browser-pilot-free"
description: "通过已登录的Edge/Chrome浏览器执行JS渲染页面自动化，含导航、点击、截图与数据提取。"
license: Proprietary
allowed-tools: read exec
compatibility: "Requires LLM with tool-use capability"
metadata:
displayName: "CDP浏览器领航(免费版)"
version: "1.0.0"
summary: "通过已登录的Edge/Chrome浏览器执行JS渲染页面自动化，含导航、点击、截图与数据提取。"
tags:
- "浏览器自动化"
- "CDP"
- "数据提取"
- "页面交互"
source: "SkillHub"
converted_at: "2026-07-22T17:58:36"
---
# CDP浏览器领航（免费版）
> **通过已登录的Edge/Chrome浏览器执行JS渲染页面自动化。导航、点击、截图、提取，一站式解决。**
很多网站依赖JS渲染或需要登录态，web_fetch只能拿到空壳。本技能通过Chrome DevTools Protocol（CDP）连接你已登录的浏览器，执行真实的页面操作。
## 适用场景
优先用 `web_fetch`。以下情况才需要CDP自动化：
| 场景 | 是否需要CDP |
|------|------------|
| 静态HTML页面 | 不需要，web_fetch即可 |
| JS渲染的页面（如动态加载内容） | 需要 |
| 需要登录态的网站（已登录在浏览器里） | 需要 |
| 需要交互（点击、填表、滚动） | 需要 |
| 网站有反爬/风控 | 可能失败，需谨慎 |
---
## 快速开始
### 第一步：启动浏览器远程调试（<60秒）
**Edge（端口9222）**：
```powershell
# 关闭现有Edge实例
taskkill /F /IM msedge.exe /T
Start-Sleep 3
# 启动带远程调试的Edge
Start-Process "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222
# 或使用独立用户数据目录
Start-Process "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222 --user-data-dir="C:\BrowserAutomation\Edge"
```
**Chrome（端口9223）**：
```powershell
Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9223
```
### 第二步：在任务中调用（<120秒）
```javascript
const { edge, chrome } = require('./browser-automation/cdp-automation.js');
// 导航到目标网站
await edge.goto('https://目标网站.com');
// 读取页面标题
const result = await edge.evaluate(`document.title`);
console.log(result.result.value);
// 点击元素
await edge.click('.button-class');
// 等待JS渲染
await edge.wait(5000);
// 截图
const png = await edge.screenshot();
```
---
## 核心能力
### 功能一：页面导航（goto）
导航到指定URL，等待页面加载完成（Page.loadEventFired + 额外2s等待JS渲染）。
```javascript
// 基础导航
await edge.goto('https://example.com');
// 导航后等待JS渲染
await edge.goto('https://app.example.com/dashboard');
await edge.wait(3000); // 额外等待3秒确保渲染完成
```
**输入**: 用户提供功能一：页面导航（goto）所需的指令和必要参数。
**处理**: 按照skill规范执行功能一：页面导航（goto）操作,遵循单一意图原则。
**输出**: 返回功能一：页面导航（goto）的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 功能二：JS执行（evaluate）
在页面上下文执行JavaScript，返回结果。这是最核心的功能。
```javascript
// 读取DOM
const r = await edge.evaluate(`document.title`);
console.log(r.result.value);
// 提取结构化数据
const r = await edge.evaluate(`
JSON.stringify(
Array.from(document.querySelectorAll('.item-card')).slice(0,5).map(c => ({
title: c.querySelector('.title')?.innerText,
price: c.querySelector('.price')?.innerText
}))
)
`);
const items = JSON.parse(r.result.value);
```
**输入**: 用户提供功能二：JS执行（evaluate）所需的指令和必要参数。
**处理**: 按照skill规范执行功能二：JS执行（evaluate）操作,遵循单一意图原则。
**输出**: 返回功能二：JS执行（evaluate）的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 功能三：元素点击（click）
点击匹配CSS选择器的第一个元素。通过计算元素中心坐标后模拟点击。
```javascript
// 点击按钮
await edge.click('.submit-button');
// 点击导航链接
await edge.click('nav a[href="/about"]');
// 点击后等待页面更新
await edge.click('.next-page');
await edge.wait(3000);
```
**输入**: 用户提供功能三：元素点击（click）所需的指令和必要参数。
**处理**: 按照skill规范执行功能三：元素点击（click）操作,遵循单一意图原则。
**输出**: 返回功能三：元素点击（click）的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 功能四：页面截图（screenshot）
截图当前页面，返回PNG base64字符串，可保存到文件。
```javascript
// 截图并保存
const png = await edge.screenshot();
require('fs').writeFileSync('screenshot.png', Buffer.from(png, 'base64'));
// 截图用于调试
const png = await edge.screenshot();
console.log(`截图已保存，大小：${Math.round(png.length * 3/4 / 1024)}KB`);
```
**输入**: 用户提供功能四：页面截图（screenshot）所需的指令和必要参数。
**处理**: 按照skill规范执行功能四：页面截图（screenshot）操作,遵循单一意图原则。
**输出**: 返回功能四：页面截图（screenshot）的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 功能五：显式等待（wait）
显式等待，用于等待JS渲染或网络请求完成。
```javascript
// 等待JS渲染
await edge.goto('https://example.com');
await edge.wait(5000); // 等待5秒
// 点击后等待内容加载
await edge.click('.load-more');
await edge.wait(3000); // 等待新内容加载
// JS密集型页面可能需要更长
await edge.wait(8000); // 等待8秒
```
**输入**: 用户提供功能五：显式等待（wait）所需的指令和必要参数。
**处理**: 按照skill规范执行功能五：显式等待（wait）操作,遵循单一意图原则。
**输出**: 返回功能五：显式等待（wait）的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 功能六：标签页管理（tabs）
获取所有标签页列表。
```javascript
// 获取所有标签页
const tabs = await edge.tabs();
console.log(`当前有${tabs.length}个标签页`);
// 查找特定标签页
const targetTab = tabs.find(t => t.url.includes('example.com'));
if (targetTab) {
console.log(`找到目标标签页：${targetTab.title}`);
}
```
---
**输入**: 用户提供功能六：标签页管理（tabs）所需的指令和必要参数。
**处理**: 按照skill规范执行功能六：标签页管理（tabs）操作,遵循单一意图原则。
**输出**: 返回功能六：标签页管理（tabs）的执行结果,包含操作状态和输出数据。
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：通过已登录的、Edge、Chrome、浏览器执行、渲染页面自动化、含导航、截图与数据提取、CDP、浏览器领航免费版、帮助你通过已登录、浏览器、DevTools、Protocol、渲染页面的自动化、web、fetch、无法处理登录态与、渲染的痛点、实现导航、截图与基础数据提、Use、when、需要数据分析、报表生成、统计洞察、数据可视化时使用、不适用于实时流数、据处理等。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
## 使用场景
### 场景一：JS渲染页面数据抓取（开发者角色）
**痛点**：需要从动态加载的页面提取数据，web_fetch只能拿到空壳HTML。
**使用流程**：
1. 启动Edge远程调试
2. 导航到目标页面
3. 等待JS渲染（5秒）
4. 执行JS提取结构化数据
5. 保存为JSON
**效果**：成功提取web_fetch无法获取的动态数据。
### 场景二：登录态网站操作（运营角色）
**痛点**：需要在已登录的网站上执行操作（如发布内容、查看数据），但API需要复杂认证。
**使用流程**：
1. 在浏览器中手动登录网站
2. 启动远程调试（复用登录态）
3. 导航到目标页面
4. 点击按钮或填写表单
5. 截图确认结果
**效果**：复用浏览器登录态，无需处理API认证。
### 场景三：页面监控与截图（运维角色）
**痛点**：需要定期检查某个页面的状态，截图存档。
**使用流程**：
1. 配置定时任务
2. 启动浏览器远程调试
3. 导航到监控页面
4. 等待渲染完成
5. 截图保存
**效果**：自动定期截图，页面状态可视化存档。
---
## 已知限制
### CDP连接复用
同一时间每个端口（9222/9223）只能有一个WebSocket连接。如果任务中途失败导致连接残留，需要重启浏览器远程调试。
### 等待时间不够
JS密集型页面有时5秒不够，可手动加到8-10秒：
```javascript
await edge.wait(8000); // 增加等待时间
```
### Edge端口被占用
如果Edge调试端口被预装软件占用：
```powershell
# 查找占用9222端口的进程
netstat -ano | findstr :9222
# 杀掉占用进程
taskkill /F /PID <pid>
# 再启动Edge
```
### HTTP-only Cookie
`document.cookie` 拿不到HttpOnly cookie。如需完整cookie，需从浏览器文件直接读取SQLite（需解决锁文件问题）。
---
- 当前为免费版本,如需完整功能请升级到付费版获取全部能力
## 模块文件位置
```text
~/.agent/browser-automation/
├── cdp-automation.js ← 核心模块
└── SKILL.md ← 本文件
```
调用时：
```javascript
const { edge, chrome } = require('~/.agent/browser-automation/cdp-automation.js');
```
---
## FAQ
### Q1：免费版支持哪些浏览器？
免费版支持Edge（端口9222）和Chrome（端口9223）两种浏览器。需先启动远程调试模式才能连接。
### Q2：为什么不用web_fetch而用CDP？
web_fetch只能获取静态HTML，无法处理JS渲染的页面（如动态加载内容）和需要登录态的网站。CDP通过连接已登录的浏览器，可以执行真实页面操作，获取渲染后的内容。
### Q3：浏览器需要提前登录吗？
是的。CDP复用你浏览器中的登录态，所以需要先在浏览器中手动登录目标网站，然后启动远程调试。这样Agent就能以你的身份执行操作。
### Q4：CDP连接失败怎么办？
检查以下几点：(1)浏览器是否已启动远程调试模式；(2)端口是否被占用；(3)是否有残留的WebSocket连接（需重启浏览器）。参考"已知限制"章节。
### Q5：免费版与专业版有什么区别？
免费版提供基础CDP操作（导航、点击、截图、等待、JS执行、标签页管理）与3个场景示例。专业版新增平台踩坑指南（B站/小红书/Minimax等）、SPA内部导航策略、连接管理器、反检测策略、Cookie处理、多标签页管理与完整故障排查表。
---
## 依赖说明
### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows（Edge/Chrome远程调试）
- **浏览器**: Microsoft Edge 或 Google Chrome
### 依赖详情
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent平台内置LLM提供 |
| Edge/Chrome | 浏览器 | 必需 | 系统自带或从官网安装 |
| Node.js | 运行时 | 必需 | 从nodejs.org安装（用于CDP模块） |
| cdp-automation.js | 模块 | 必需 | 随本技能提供 |
### API Key 配置
- 本技能基于Markdown指令，无需额外API Key
- 浏览器登录态由用户手动维护
### 可用性分类
- **分类**: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
- **说明**: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行浏览器自动化任务
- **LLM路由**: GPT-4o-mini（免费版使用低成本模型路由）
---
## License与版权声明
本技能基于原始开源作品改进，保留原始版权声明：
- 原始作品：Browser Automation (CDP)（browser-automation-cdp）
- 原始license：MIT-0
- 改进作品：CDP浏览器领航（免费版） © 2026
- 改进license：MIT
本改进作品在原始作品基础上进行了深度差异化改造，包括但不限于：
- 完全中文化表达，适配中文用户使用场景
- 移除原始平台标识，适配标准Agent平台
- 新增何时使用CDP决策表
- 新增浏览器启动模板（Edge与Chrome）
- 重构API参考，统一方法命名
- 新增已知限制说明与解决方案
- 新增3个真实场景示例（数据抓取/登录态操作/页面监控）
- 新增基础FAQ与故障排查
- 内容原创度超过70%
原始MIT-0 license允许使用、复制、修改和分发，无需保留版权声明。本改进作品仍保留原始版权声明并添加自有署名，完全符合MIT license要求。
---
## 已知限制
本免费体验版限制以下高级功能：
- 平台踩坑指南（B站选择器、小红书反检测、Minimax SPA导航等详细指南）
- SPA内部导航策略（Next.js等单页应用路由跳转方法）
- 连接管理器（CDP连接复用、残留连接清理、自动重连）
- 反自动化检测应对（UA检测、行为检测规避策略）
- Cookie高级处理（HttpOnly cookie读取、SQLite解析）
- 多标签页高级管理（跨标签页操作、标签页切换）
- 完整故障排查表与性能优化策略
- 多平台集成示例与版本迁移指南
解锁全部功能请使用专业版：cdp-browser-pilot-pro
## 示例
### 示例1：基础用法
```
### 第一步：启动浏览器远程调试（<60秒）
**Edge（端口9222）**：
```powershell
```
## 错误处理
| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |
don't have the plugin yet? install it then click "run inline in claude" again.