Browser CDP Skill

通过 CDP（Chrome DevTools Protocol）直接控制 Chrome 系浏览器，不依赖 Playwright/Selenium。
核心优势：可以连接用户正在使用的、已登录的真实浏览器窗口，与用户协同操作，而不是每次都起一个
干净的自动化浏览器丢失登录态。同时也支持在无 GUI 的服务器/沙盒环境里跑一个无头实例，专门做抓取。

Playwright 集成：作为 CDP 的补充，提供高层 API 封装，支持反检测、智能等待、复杂交互等高级功能。
适用于需要更强反检测能力或更简洁 API 的场景。

脚本目录：.claude/skills/browser-cdp/src/

脚本	用途
core/cdp_client.py	底层库，其他脚本导入用，一般不直接调用
core/utils.py	底层库，公共辅助函数
core/playwright_session.py	Playwright 高层封装：反检测、智能等待、复杂交互
core/browser_launch.py	确保/建立浏览器连接，管理 tab（列表/新建/关闭/激活）
core/browser_nav.py	打开网址、前进后退刷新、等待元素出现
core/browser_extract.py	抓取内容：html/text/elements/forms/links/meta
core/browser_screenshot.py	截图，支持整页/元素级/编号标注
core/browser_input.py	模拟点击、输入文字、按键、滚动、悬停
core/browser_console.py	执行任意 JS、抓取 console 日志、抓取网络请求
core/browser_watch.py	协作场景：轮询判断用户是否已完成某个操作（URL/标题变化）
core/stealth.py	反检测模式：webdriver 移除、指纹模拟、人类化行为
core/request_headers.py	请求头伪装：Sec-Fetch-*、站点自定义、动态 Referer
core/rate_limiter.py	请求速率控制：令牌桶/漏桶/固定窗口、熔断器
core/proxy_pool.py	代理池管理：HTTP/SOCKS5 轮换、健康检查、故障转移
core/browser_download.py	文件下载管理：下载事件监听、进度监控、断点续传、下载目录配置
core/browser_form.py	复杂表单自动化：多步骤表单、动态表单、文件上传、表单验证、状态保存/恢复
core/browser_tabs.py	多标签页管理：标签页列表、切换、批量操作、标签页组管理
core/browser_browse.py	浏览器浏览统一入口：整合导航/截图/交互/等待策略，提供组合操作能力
core/dom_observer.py	DOM 变化监听：MutationObserver 实现，检测动态内容加载完成
core/enhanced_dynamic_loader.py	增强版动态加载器：DOM 监听 + 虚拟列表 + 多策略等待
core/explicit_wait.py	显式等待模块：条件等待、组合条件、模块级便捷函数
core/network_idle_detector.py	网络空闲检测模块：精细化网络状态监控、MIME分类、稳定性检测
core/page_render_detector.py	页面渲染完成检测：DOM变化+内容哈希+字体加载+动画检测
searchers/baidu_search.py / searchers/bing_search.py	搜索引擎自动化，见下方对应子资源
searchers/zhihu_search.py / searchers/zhihu_hot.py	知乎内容/热榜抓取，见下方对应子资源
searchers/zhihu_column_search.py	知乎专栏文章批量搜索与抓取，见下方对应子资源
searchers/zhihu_publish_answer.py	知乎问题回答发布自动化脚本，通过已登录的浏览器实例在知乎问题下撰写并发布回答
searchers/arxiv_search.py / searchers/arxiv_multi_search.py	arXiv 论文搜索，见下方对应子资源
searchers/wechat_search.py	微信公众号文章搜索（搜狗微信），见下方对应子资源
searchers/jd_search.py	京东商品搜索，见下方对应子资源
searchers/pdd_search.py	拼多多商品搜索，见下方对应子资源
searchers/douban_search.py	豆瓣搜索，见下方对应子资源
searchers/sina_news.py	新浪财经新闻抓取，见下方对应子资源
searchers/eastmoney_guba.py	东方财富股吧帖子抓取，见下方对应子资源
searchers/scholar_search.py	Google Scholar 论文搜索，见下方对应子资源
searchers/bilibili_search.py	B站视频/UP主搜索，见下方对应子资源
searchers/boss_zhipin_search.py	BOSS直聘职位搜索，见下方对应子资源
searchers/thp_news.py	澎湃新闻新闻搜索，见下方对应子资源
searchers/weibo_search.py	微博热搜/关键词搜索，见下方对应子资源
searchers/lagou_search.py	拉勾网职位搜索，见下方对应子资源
searchers/youku_search.py	优酷视频/影视剧搜索，见下方对应子资源
searchers/weather_search.py	中国天气网天气预报，见下方对应子资源
searchers/mooc_search.py	中国大学MOOC课程搜索，见下方对应子资源
searchers/toutiao_search.py	今日头条搜索，见下方对应子资源
searchers/tencent_video_search.py	腾讯视频搜索，见下方对应子资源
searchers/iqiyi_search.py	爱奇艺搜索，见下方对应子资源
searchers/maimai_search.py	脉脉搜索，见下方对应子资源
searchers/amap_poi_search.py	高德地图 POI 搜索，见下方对应子资源
searchers/dianping_search.py	大众点评搜索，见下方对应子资源
searchers/facebook_search.py	Facebook 社交内容搜索，见下方对应子资源
searchers/instagram_search.py	Instagram 社交内容搜索，见下方对应子资源
searchers/linkedin_search.py	LinkedIn 职场社交搜索，见下方对应子资源
searchers/twitter_search.py	Twitter/X 社交内容搜索，见下方对应子资源
searchers/pinduoyun_search.py	拼多多云店商品搜索，见下方对应子资源
searchers/kuaishou_search.py	快手短视频搜索，见下方对应子资源
searchers/anjuke_search.py	安居客房产搜索，见下方对应子资源
searchers/ctrip_search.py	携程旅行搜索，见下方对应子资源
searchers/cnki_search.py	中国知网学术论文搜索，见下方对应子资源
searchers/xianyu_search.py	闲鱼二手商品搜索，见下方对应子资源

子资源（渐进式加载）

本 skill 遵循渐进式加载规范：正文只保留高频必读内容，长尾细节放在 references/*.md，
已在 frontmatter resources 中登记，激活本 skill 后可在资源清单里看到全部条目及加载状态。
命中对应 triggers 会自动加载；也可以不依赖关键词，主动调用
skill_resource_load(skill_name="browser-cdp", resource_id="<id>", reason=...) 按需加载：

id	内容
python-env-detection	python/python3 命令检测的完整原因与自动检测脚本
browser-launch-scenarios	三种建立浏览器连接场景的完整细节（专用实例/连接已登录窗口/headless）
workflows	抓取内容、看图填表单、协作模式、调试网页四类工作流的完整示例
troubleshooting	路径规则详解 + 截图/DPR/SPA/编号失效等常见坑
baidu-search / bing-search	对应搜索引擎自动化脚本完整文档
zhihu-search / zhihu-hot	知乎内容搜索 / 热榜抓取脚本完整文档
zhihu-column-search	知乎专栏文章批量搜索与抓取脚本完整文档
zhihu-publish-answer	知乎问题回答发布自动化脚本，通过已登录的浏览器实例在知乎问题下撰写并发布回答
arxiv-search / arxiv-multi-search	arXiv 单关键词 / 多关键词批量搜索脚本完整文档
wechat-search	微信公众号文章搜索自动化脚本完整文档
jd-search	京东商品搜索自动化脚本完整文档
pdd-search	拼多多商品搜索自动化脚本完整文档
douban-search	豆瓣搜索自动化脚本完整文档
sina-news	新浪财经新闻抓取脚本完整文档
eastmoney-guba	东方财富股吧帖子抓取脚本完整文档
scholar-search	Google Scholar 学术论文搜索脚本完整文档
bilibili-search	B站视频/UP主搜索自动化脚本完整文档
boss-zhipin-search	BOSS直聘职位搜索自动化脚本完整文档
thp-news	澎湃新闻新闻搜索自动化脚本完整文档
weibo-search	微博搜索自动化脚本完整文档
lagou-search	拉勾网招聘搜索自动化脚本完整文档
youku-search	优酷视频搜索自动化脚本完整文档
weather-search	中国天气网天气预报自动化脚本完整文档
mooc-search	中国大学MOOC课程搜索自动化脚本完整文档
toutiao-search	今日头条搜索自动化脚本完整文档
tencent-video-search	腾讯视频搜索自动化脚本完整文档
iqiyi-search	爱奇艺搜索自动化脚本完整文档
maimai-search	脉脉搜索自动化脚本完整文档
amap-poi-search	高德地图 POI 搜索自动化脚本完整文档
dianping-search	大众点评搜索自动化脚本完整文档
captcha-handling	验证码处理与反检测指南：滑块/点选/文字验证码处理、reCAPTCHA/hCaptcha 应对、反检测模式配置、常见反爬场景策略
request-headers	请求头伪装模块完整文档：按站点自定义请求头、Sec-Fetch-* 现代浏览器头、预定义站点配置、动态 Referer 生成
rate-limiter	请求速率控制模块完整文档：令牌桶/漏桶/固定窗口算法、指数退避重试、熔断器模式
proxy-pool	代理池管理模块完整文档：HTTP/SOCKS5 代理轮换、健康检查、自动故障转移、按健康度/轮询/随机策略选择
searchers-guide	搜索器使用指南：所有搜索器的快速开始、参数说明、输出格式、错误处理、最佳实践
browser-download	文件下载管理模块完整文档：下载事件监听、进度监控、断点续传、下载目录配置
browser-form	复杂表单自动化模块完整文档：多步骤表单、动态表单、文件上传、表单验证、状态保存/恢复
browser-tabs	多标签页管理模块完整文档：标签页列表、切换、批量操作、标签页组管理

新增子功能脚本时：在 .claude/skills/browser-cdp/references/ 下新建 <name>.md，并在本文件
frontmatter 的 resources 里登记 id/path/description/triggers——不登记就不会被加载机制发现。

运行前必做：Python 命令检测

本环境同时存在 python 和 python3，只有一个可用。本环境结论：用 python（Anaconda），
python3 不可用（会弹出应用商店安装提示）。

cd .claude/skills/browser-cdp
python src/core/browser_launch.py --dedicated --name work --start-url "https://example.com"

若换了新环境、命令报错，或需要检测脚本，加载 python-env-detection 子资源。

前置依赖

pip install websocket-client requests pillow

pillow 只有 browser_screenshot.py --annotate 需要，用于在截图上画编号框。

第一步：确保有可连接的浏览器

默认场景（推荐）：Agent 拉起一个独立的专用 Chrome 实例，独立 profile + 独立调试端口
（默认 9333），不碰用户真实登录态：

cd .claude/skills/browser-cdp
python src/core/browser_launch.py --dedicated --name work --start-url "https://example.com"
# 输出里会给出 port 和首个 tab id，例如 --port 9333 --tab <id>
python src/core/browser_nav.py --port 9333 --tab <id> --goto "https://example.com"

常用管理：python src/core/browser_launch.py --list-dedicated（查看已建实例）、
python src/core/browser_launch.py --stop-dedicated work（用完关闭）。

⚠️ 登录状态要跨多次调用保留，--name 必须每次固定不变：--dedicated 的登录态持久化
依赖同一个 --name 对应同一个 profile 目录。同一个任务/workflow 内所有涉及浏览器的步骤
都要用同一个固定的实例名（比如做知乎相关任务统一用 --name zhihu_session），不要每次
调用都用默认值或临时想一个名字——用不同名字等于每次都是全新登录态。第一次用某个 --name
跑的时候如果页面显示未登录，提示用户在这个专用窗口里手动登录一次即可，之后同名字复用会
保留登录态（profile 目录固定存放在 temp_cdp/cdp_brower_data/<name>/）。

如果同名字复用后登录态仍然看起来"丢了"，大概率不是目录/文件被删，而是上次浏览器非正常退出
（被强制杀进程/崩溃）后残留的 Chrome 单实例锁文件（SingletonLock 等）阻止了这次启动正确
加载该 profile；browser_launch.py 每次启动新进程前都会自动清理这些锁文件，遇到这种情况
不需要手动处理，直接重新 --dedicated --name <同一个名字> 即可。

需要连接用户已登录的真实浏览器窗口（共享登录态），或无 GUI 服务器环境用 headless，
加载 browser-launch-scenarios 子资源查看完整步骤。

先检测再启动：--ensure 模式在请求的端口不通时，不会直接判定"没有可用浏览器"，会先
扫一遍系统进程找有没有其它已经在跑的、带调试端口的 chrome/edge（不限于本技能自己启动的，
包括用户手动开的、或者之前会话遗留的），找到就直接复用并提示应该用哪个端口，而不是又启动
一个新的。想单独看一下当前系统里有哪些调试浏览器在跑，用：

python src/core/browser_launch.py --list-running

--dedicated 模式对"是否已有可用实例"的判断范围是"指定 --name 对应的那一个专用实例"
（先查 registry.json，查不到再查 profile 目录下的锁文件兜底），不会去匹配系统里任意其它
无关的调试浏览器——这是有意为之：--dedicated 的语义是"这个固定名字对应固定的 profile"，
如果为了"复用一个已有浏览器"而误连到一个 profile/登录态完全不相关的实例，反而会造成更隐蔽
的问题。

典型工作流速览

python src/core/browser_launch.py --new "https://example.com"        # 拿到新 tab 的 id
python src/core/browser_nav.py --tab <id> --goto "https://example.com"
python src/core/browser_extract.py --tab <id> --mode text             # 纯文本正文，适合直接喂给模型分析
python src/core/browser_screenshot.py --tab <id> --out shot.png --annotate   # 编号标注截图，用于看图点击/填表单

大页面注意 --max-chars（默认 20000）截断，需要完整内容时用 --save out.txt 写文件。

表单填写/点击的完整"看图操作"流程、与用户协作的三种介入程度（观察/建议/代劳）、
调试网页 console/网络请求，加载 workflows 子资源查看完整示例。

⚠️ 路径规则（极易踩坑）

所有脚本都必须先 cd 到 skill 目录再运行（导入路径已更新为 src.core.*），这意味着
所有相对路径（包括 ./temp_data/）都是相对于 skill 目录解析的，不是项目根目录。
优先使用绝对路径输出产出文件。完整规则和错误示例见 troubleshooting 子资源。

反爬机制处理

验证码处理

本 skill 支持检测和处理常见验证码类型：

验证码类型	支持程度	处理方式
滑块验证码	✅ 自动	自动计算滑动距离并执行滑动
点选验证码	⚠️ 部分	尝试识别指令并点击，失败时提示用户
文字验证码	⚠️ 需配置	需要配置 OCR API（百度/腾讯/阿里云）
reCAPTCHA	❌ 手动	提示用户手动完成
hCaptcha	❌ 手动	提示用户手动完成
短信/邮箱验证码	❌ 手动	提示用户提供验证码

使用示例：

# 自动检测并处理验证码
python src/core/browser_nav.py --tab <id> --goto "https://example.com" --handle-captcha

# 启用反检测模式 + 验证码处理
python src/core/browser_nav.py --tab <id> --goto "https://example.com" --stealth --handle-captcha

验证码处理流程：

1. 检测阶段：扫描页面元素、URL、文本，识别验证码类型
2. 处理阶段：
   • 滑块验证码：自动计算缺口位置并执行滑动
   • 点选验证码：识别指令文本，点击对应元素
   • 文字验证码：调用 OCR API 识别（需配置）
3. 提示阶段：无法自动处理时，输出明确提示供用户手动操作

反检测模式

启用 --stealth 参数可隐藏自动化特征：

python src/core/browser_nav.py --tab <id> --goto "https://example.com" --stealth

反检测功能包括：

• 移除 navigator.webdriver 属性
• 模拟真实 Chrome runtime 对象
• 模拟浏览器插件信息
• 模拟真实语言设置
• 模拟真实平台信息
• 随机 User-Agent 轮换
• 人类化鼠标轨迹和打字节奏
• 请求间隔随机化

常见反爬场景应对

场景	症状	应对策略
请求频率过高	429 错误、临时封禁	使用 --stealth + 速率控制
指纹检测	页面异常、验证码弹出	启用 stealth 模式
IP 封禁	无法访问、重定向	使用代理池
JavaScript 检测	页面无法加载	等待 JS 执行完成后再操作
行为分析	验证码、封号	模拟人类行为（点击、滚动、打字）
请求头异常	403/444 响应	使用请求头伪装模块

请求头伪装

启用 --stealth 时自动应用现代浏览器请求头（Sec-Fetch-*、Accept 等），也可通过 RequestHeaderManager 按站点自定义：

from src.core.request_headers import get_header_manager, HeaderConfig

# 获取管理器
mgr = get_header_manager()

# 为特定站点配置请求头
mgr.update_config("bilibili", HeaderConfig(
    custom_headers={"X-Requested-With": "XMLHttpRequest"}
))

# 获取带 Sec-Fetch-* 的请求头
headers = mgr.get_headers("https://www.bilibili.com")

预定义站点配置：B站、知乎、京东、淘宝、微博。加载 request-headers 子资源查看完整文档。

请求速率控制

使用 RateLimiter 控制请求频率，支持令牌桶/漏桶/固定窗口三种算法：

from src.core.rate_limiter import get_rate_limiter, RateLimitAlgorithm

limiter = get_rate_limiter()
limiter.set_algorithm(RateLimitAlgorithm.TOKEN_BUCKET, rate=2.0, burst=5)

# 执行请求前获取令牌
if limiter.acquire():
    await do_request()
else:
    await asyncio.sleep(limiter.get_retry_after())

支持指数退避重试和熔断器模式。加载 rate-limiter 子资源查看完整文档。

代理池管理

使用 ProxyPool 管理代理轮换，支持健康检查和自动故障转移：

from src.core.proxy_pool import get_proxy_pool, ProxyInfo, ProxyType

pool = get_proxy_pool()
pool.add_proxy(ProxyInfo(host="127.0.0.1", port=8080, proxy_type=ProxyType.HTTP))

# 按健康度选择代理
proxy = pool.get_proxy_by_health_score()

支持 HTTP/SOCKS5 代理，按健康度/轮询/随机策略选择。加载 proxy-pool 子资源查看完整文档。

文件下载管理

使用 browser_download.py 管理文件下载：

# 启动下载监听
python src/core/browser_download.py --port 9333 --tab <id> --start-listener

# 触发下载
python src/core/browser_input.py --port 9333 --tab <id> --click-selector "a.download"

# 等待下载完成
python src/core/browser_download.py --port 9333 --wait --timeout 60

# 查看下载状态
python src/core/browser_download.py --port 9333 --list

支持断点续传、下载进度监控、自定义下载目录。加载 browser-download 子资源查看完整文档。

复杂表单自动化

使用 browser_form.py 处理复杂表单：

# 填写单个字段
python src/core/browser_form.py --port 9333 --tab <id> --fill-selector "input[name='username']" --text "john"

# 文件上传
python src/core/browser_form.py --port 9333 --tab <id> --upload-file --fill-selector "input[type='file']" --file "/path/to/file.pdf"

# 批量填写表单
python src/core/browser_form.py --port 9333 --tab <id> --fill-form form_def.json

# 提交表单
python src/core/browser_form.py --port 9333 --tab <id> --submit-form --wait-for networkidle

# 保存/恢复表单状态
python src/core/browser_form.py --port 9333 --tab <id> --save-form --out saved.json
python src/core/browser_form.py --port 9333 --tab <id> --restore-form --in saved.json

支持多步骤表单、动态表单（AJAX 加载）、表单验证。加载 browser-form 子资源查看完整文档。

多标签页管理

使用 browser_tabs.py 管理多个标签页：

# 列出所有标签页
python src/core/browser_tabs.py --port 9333 --list

# 批量导航
python src/core/browser_tabs.py --port 9333 --batch-goto "url1,url2,url3"

# 批量截图
python src/core/browser_tabs.py --port 9333 --batch-screenshot --out-dir ./screenshots

# 批量提取内容
python src/core/browser_tabs.py --port 9333 --batch-extract --mode text --out-dir ./extracted

# 关闭所有标签页（保留 1 个）
python src/core/browser_tabs.py --port 9333 --close-all --keep 1

支持标签页组管理、批量操作。加载 browser-tabs 子资源查看完整文档。

浏览器浏览统一入口

使用 browser_browse.py 整合导航、截图、交互、等待策略，提供组合操作能力：

# 导航到页面并等待网络空闲
python src/core/browser_browse.py --tab <id> --goto "https://example.com" --wait-for networkidle

# 截图并标注可交互元素
python src/core/browser_browse.py --tab <id> --screenshot --out shot.png --annotate

# 整页截图
python src/core/browser_browse.py --tab <id> --screenshot --out shot.png --full-page

# 点击元素
python src/core/browser_browse.py --tab <id> --click-index 3

# 输入文本
python src/core/browser_browse.py --tab <id> --type-index 5 --text "hello world"

# 等待元素出现
python src/core/browser_browse.py --tab <id> --wait-selector "#result" --timeout 10

# 组合操作：导航 + 截图 + 标注
python src/core/browser_browse.py --tab <id> --goto "https://example.com" --screenshot --annotate --out shot.png

# 查询页面状态
python src/core/browser_browse.py --tab <id> --state

# 扫描可交互元素
python src/core/browser_browse.py --tab <id> --elements

支持的参数：

参数	说明
--goto URL	导航到指定 URL
--back	后退
--forward	前进
--reload	刷新页面
--screenshot --out PATH	截图保存到指定路径
--full-page	整页截图
--annotate	标注可交互元素编号
--element-index N	只截取指定编号元素
`--region NAV	MAIN
--click-index N	点击指定编号元素
--click-xy X Y	点击坐标
--click-selector CSS	点击选择器
--smart-click TEXT	根据文本智能点击
--type-index N --text TEXT	向元素输入文本
--type-selector CSS --text TEXT	向选择器输入文本
--scroll-to-index N	滚动到元素
--scroll-by DX DY	滚动偏移
--scroll-to-top	滚动到顶部
--scroll-to-bottom	滚动到底部
--wait-selector CSS	等待元素出现
--wait-for STRATEGY	智能等待策略
--state	查询页面状态
--elements	扫描可交互元素

错误处理与重试机制

browser_browse.py 内置了完整的错误处理和自动重试机制：

错误类型分类：

错误类型	说明	触发条件
timeout	超时错误	等待超时、导航超时
connection_lost	连接丢失	CDP 连接断开
element_not_found	元素未找到	选择器匹配失败
navigation_failed	导航失败	URL 加载失败
screenshot_failed	截图失败	截图操作异常
page_crashed	页面崩溃	Chrome 页面崩溃
unknown	未知错误	其他异常

重试配置：

# 默认重试 3 次，基础延迟 1 秒
python src/core/browser_browse.py --tab <id> --goto "https://example.com"

# 自定义重试次数和延迟
python src/core/browser_browse.py --tab <id> --goto "https://example.com" --max-retries 5 --retry-delay 2.0

重试策略：

• 指数退避：delay = base_delay * 2^(attempt-1)
• 最大延迟限制：防止等待时间过长
• 熔断器：连续失败后暂停，避免雪崩效应

输出格式：

成功时输出 JSON：

{
  "success": true,
  "operation": "screenshot",
  "elapsed": 1.23,
  "data": {
    "screenshot": "shot.png",
    "element_count": 15
  }
}

失败时输出错误信息：

{
  "success": false,
  "operation": "click",
  "elapsed": 0.5,
  "error": {
    "error_type": "element_not_found",
    "message": "未找到编号为 5 的元素",
    "operation": "click",
    "attempt": 3,
    "max_attempts": 3
  }
}

安全与边界

• 不用于绕过验证码、自动登录他人账号、批量注册等滥用场景；涉及登录态操作时，让用户自己完成
  账号密码/验证码相关的输入。
• 涉及"提交""支付""删除""发送"等不可逆操作时，先用截图向用户确认，再执行。
• headless spawn 模式默认使用独立 profile，不会读取用户真实 Chrome 的 cookie/密码，
  纯抓取公开页面场景优先用这个模式，减少对用户账号的接触面。
• 调试端口只在需要时开启，用完可以提示用户关闭该 Chrome 窗口恢复正常模式。

常见坑（速查，完整版见 troubleshooting 子资源）

• Page.captureScreenshot 的 clip 坐标是 CSS 像素，不需要额外乘 DPR。
• 页面是 SPA 时不要死等 load 事件，用 browser_watch.py --wait-url-contains 判断路由跳转。
• 元素编号依赖当次 DOM 扫描顺序，页面有明显变化后务必先重新截图/扫描再操作。

网站类型支持矩阵

支持类型概览

网站类型	核心能力	推荐配置	测试状态
电商网站	商品列表、详情、搜索、分页	--stealth + networkidle	✅ 已验证
新闻网站	文章列表、内容、评论、动态加载	--wait-for stable	✅ 已验证
社交网站	动态流、无限滚动、Shadow DOM	--wait-for networkidle + DynamicLoader	✅ 已验证
后台系统	表格、表单、AJAX、分页	--wait-for ajax	✅ 已验证

电商网站（E-commerce）

典型特征：商品列表分页、搜索筛选、详情页、购物车

推荐配置：

# 商品列表抓取
python src/core/browser_nav.py --tab <id> --goto "https://shop.example.com/products" \
    --wait-for networkidle --stealth

# 商品详情抓取
python src/core/browser_extract.py --tab <id> --mode text --max-chars 50000

# 搜索功能
python src/core/browser_input.py --tab <id> --type "关键词" --selector "input[name='q']"
python src/core/browser_input.py --tab <id> --click "button[type='submit']"

已知限制：

• 需要登录态的商品价格/库存可能无法抓取
• 动态加载的商品列表需配合 DynamicLoader 滚动

新闻网站（News）

典型特征：文章列表、分页、评论、RSS

推荐配置：

# 文章列表抓取
python src/core/browser_nav.py --tab <id> --goto "https://news.example.com" \
    --wait-for stable

# 文章内容抓取
python src/core/browser_extract.py --tab <id> --mode text --selector "article.content"

# 评论抓取
python src/core/browser_extract.py --tab <id> --mode elements --selector ".comment"

已知限制：

• 付费墙内容无法抓取
• 需要 JS 渲染的评论可能加载较慢

社交网站（Social）

典型特征：动态流、无限滚动、评论嵌套、Shadow DOM

推荐配置：

# 动态流抓取（含无限滚动）
python src/core/browser_nav.py --tab <id> --goto "https://social.example.com" \
    --wait-for networkidle --stealth

# 使用 DynamicLoader 滚动加载
python src/core/dynamic_loader.py --tab <id> --max-scrolls 10 --scroll-delay 0.8

# Shadow DOM 内容抓取
python src/core/browser_extract.py --tab <id> --mode elements --include-shadow

已知限制：

• 大量 Shadow DOM 嵌套可能影响抓取效率
• 需要登录态的内容无法访问
• 反爬机制较强，建议启用 --stealth

后台系统（Admin/Backend）

典型特征：数据表格、表单、权限控制、AJAX 加载

推荐配置：

# 等待 AJAX 完成
python src/core/browser_nav.py --tab <id> --goto "https://admin.example.com/dashboard" \
    --wait-for ajax --timeout 30

# 表格数据抓取
python src/core/browser_extract.py --tab <id> --mode elements --selector "table.data-grid"

# 表单填写
python src/core/browser_input.py --tab <id> --type "值" --selector "input[name='field']"
python src/core/browser_input.py --tab <id> --click "button[type='submit']"

已知限制：

• 需要登录认证，需使用 --dedicated --name 保留登录态
• 权限控制可能导致部分数据不可见
• CSRF Token 需要特殊处理

配置指南

快速开始

# 1. 启动浏览器
python src/core/browser_launch.py --dedicated --name my_task --start-url "https://example.com"

# 2. 导航（启用反检测）
python src/core/browser_nav.py --tab <id> --goto "https://example.com" --stealth --handle-captcha

# 3. 抓取内容
python src/core/browser_extract.py --tab <id> --mode text

# 4. 关闭浏览器
python src/core/browser_launch.py --stop-dedicated my_task

高级配置

自定义 User-Agent

python src/core/browser_nav.py --tab <id> --goto "https://example.com" \
    --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0"

配置 OCR API（文字验证码）

from src.core.captcha_handler import CaptchaHandler

def my_ocr(image_bytes: bytes) -> str:
    # 调用你的 OCR API
    return "识别结果"

handler = CaptchaHandler(session, ocr_api=my_ocr)
result = await handler.handle_captcha()

自定义等待策略

from src.core.smart_wait import SmartWait, WaitConfig

config = WaitConfig(
    timeout=30,
    poll_interval=0.5,
    strategies=["networkidle", "stable", "selector"]
)
wait = SmartWait(session, config)
await wait.wait_for("networkidle")

故障排查

问题	可能原因	解决方案
页面加载超时	网络慢/反爬检测	增加 --timeout，启用 --stealth
验证码无法处理	复杂验证码类型	使用 --handle-captcha 查看提示，手动处理
内容抓取为空	SPA 未渲染完成	使用 --wait-for networkidle 或 stable
元素找不到	动态加载/Shadow DOM	使用 ComplexDOMHandler 或增加等待时间
IP 被封禁	请求频率过高	降低频率，使用代理池

已知限制

技术限制

1. OCR 识别：文字验证码需要外部 OCR API，当前不提供内置 OCR
2. reCAPTCHA/hCaptcha：无法自动处理，需手动完成或使用专业服务
3. 图像对比：滑块验证码距离计算为简化算法，复杂场景可能不准确
4. Shadow DOM：深层嵌套可能影响抓取效率

法律与道德边界

1. 不得用于绕过安全验证的恶意用途
2. 不得用于批量注册、刷量等滥用场景
3. 遵守目标网站的 robots.txt 和服务条款
4. 控制请求频率，避免对目标服务器造成压力

性能限制

1. 单次抓取建议不超过 50000 字符（可通过 --max-chars 调整）
2. 无限滚动建议限制最大滚动次数（默认 10 次）
3. 并发请求需自行控制，避免触发反爬机制

搜索器模块

搜索器模块（src/searchers/）提供结构化的网站数据抓取能力，所有搜索器继承 BaseSearcher 抽象基类，统一配置接口和结果格式。

架构

from src.searchers.base import BaseSearcher, SearcherConfig
from src.searchers.jd_search import JDSearcher
from src.searchers.utils import SearchResults

# 配置
config = SearcherConfig(
    wait_timeout=30,
    max_results=20,
    retry_count=3,
)

# 搜索
searcher = JDSearcher(config=config)
results: SearchResults = searcher.search('iPhone 15')

# 批量搜索
results = searcher.search_batch(['iPhone 15', 'MacBook Pro'])

# 保存结果
results.save_json('output/jd_results.json')
results.save_csv('output/jd_results.csv')

# 健康检查
healthy = searcher.health_check()
searcher.close()

支持的搜索器

搜索器	用途	参考文档
JDSearcher	京东商品搜索	jd-search
PDDSearcher	拼多多商品搜索	pdd-search
DoubanSearcher	豆瓣书籍/电影/音乐搜索	douban-search
SinaNewsSearcher	新浪财经新闻抓取	sina-news
EastmoneyGubaSearcher	东方财富股吧帖子抓取	eastmoney-guba
ScholarSearcher	Google Scholar 论文搜索	scholar-search
BaiduSearcher	百度搜索	baidu-search
BingSearcher	Bing 搜索	bing-search
ZhihuSearcher	知乎内容搜索	zhihu-search
ZhihuHotSearcher	知乎热榜抓取	zhihu-hot
ArxivSearcher	arXiv 论文搜索	arxiv-search
WechatSearcher	微信公众号文章搜索	wechat-search
BilibiliSearcher	B站视频/UP主搜索	bilibili-search
BossZhipinSearcher	BOSS直聘职位搜索	boss-zhipin-search
GitHubSearcher	GitHub 代码仓库/Issue/PR/代码搜索	github-search
StackOverflowSearcher	Stack Overflow 技术问题搜索	stackoverflow-search
TaobaoSearcher	淘宝/天猫商品搜索	taobao-search
RESTAPISearcher	通用 REST API 搜索（GitHub/Twitter/Reddit 等）	api-search
GraphQLSearcher	GraphQL API 搜索	api-search
StockSearcher	股票行情搜索（东方财富）	realtime-search
CryptoSearcher	加密货币搜索（CoinMarketCap）	realtime-search
NewsSearcher	实时新闻搜索	realtime-search
CnkSearcher	中国知网论文搜索	cnki-search
FacebookSearcher	Facebook 社交内容搜索	facebook-search
InstagramSearcher	Instagram 社交内容搜索	instagram-search
LinkedInSearcher	LinkedIn 职场社交搜索	linkedin-search
TwitterSearcher	Twitter/X 社交内容搜索	twitter-search
PinduoyunSearcher	拼多多云店商品搜索	pinduoyun-search
KuaishouSearcher	快手短视频搜索	kuaishou-search
AnjukeSearcher	安居客房产搜索	anjuke-search
CtripSearcher	携程旅行搜索	ctrip-search
XianyuSearcher	闲鱼二手商品搜索	xianyu-search

详细使用指南见 searchers-guide 子资源。

新增模块（v0.9.5）

模块	用途	文件路径
CloudflareBypass	Cloudflare 反检测绕过	src/core/cloudflare_bypass.py
RESTAPISearcher	通用 REST API 搜索器	src/searchers/api_searcher.py
GraphQLSearcher	GraphQL API 搜索器	src/searchers/api_searcher.py
StockSearcher	股票行情实时搜索	src/searchers/realtime_searcher.py
CryptoSearcher	加密货币实时搜索	src/searchers/realtime_searcher.py
NewsSearcher	实时新闻搜索	src/searchers/realtime_searcher.py

Cloudflare 绕过特性：

• JS 挑战自动检测与绕过
• 指纹伪装（navigator、webdriver 等）
• 指数退避重试机制
• 可配置最大重试次数和超时

API 搜索器特性：

• 支持 REST API 和 GraphQL API
• 自动处理认证（Bearer Token、API Key）
• 请求缓存和去重
• 支持分页和批量请求

实时数据搜索器特性：

• 股票：东方财富实时行情、涨跌幅、成交量
• 加密货币：CoinMarketCap 数据、价格、市值
• 新闻：百度新闻搜索、实时热点
• 内置缓存机制，减少重复请求

测试与可靠性

测试套件

本 skill 包含完整的测试套件，位于 tests/ 目录：

测试文件	覆盖范围	状态
test_website_types.py	电商/新闻/社交/后台网站类型	✅ 32 通过
test_edge_cases.py	网络异常/页面跳转/动态内容/重试机制	✅ 17 通过
test_searchers.py	搜索器架构/配置/工具函数/集成测试	✅ 53 通过
test_captcha_handler.py	验证码处理逻辑	✅ 已验证
test_enhanced_modules.py	增强模块（智能等待/动态加载等）	✅ 已验证
templates/test_anti_crawl.py	反爬机制（stealth/请求头/速率控制/代理池）	✅ 32 通过
templates/test_bilibili_search.py	B站视频/UP主搜索	✅ 23 通过
templates/test_boss_zhipin_search.py	BOSS直聘职位搜索	✅ 31 通过
templates/test_browser_console_template.py	浏览器控制台调试	✅ 4 通过
templates/test_browser_watch_template.py	浏览器协作监控	✅ 5 通过
test_new_modules.py	新增模块（Cloudflare/API/实时数据）	✅ 全部通过

运行测试：

cd .claude/skills/browser-cdp
python -m pytest tests/ -v

注意：tests/templates/ 目录下部分测试文件（如 test_dynamic_content.py、test_ecommerce_flow_template.py 等）引用了不存在的函数，这些是占位符模板，尚未实现。核心测试（tests/unit/、tests/integration/、tests/e2e/ 和 tests/test_*.py）全部通过（194 passed, 10 skipped）。

边界场景处理

网络异常：

• CDPError 异常被 SmartWait._get_pending_requests() 捕获，返回 0 而非崩溃
• 超时后 wait_for() 返回 False 而非抛出异常

动态内容：

• DynamicLoader.scroll_to_load() 在高度不变时自动停止
• 虚拟列表自动去重（基于元素文本）

重试机制：

• 指数退避：base_delay * 2^attempt + jitter
• 熔断器：连续失败 N 次后暂停，超时后恢复
• 可配置 retry_on 只重试特定错误类型

已知测试行为

1. timeout 模式：MockSession(fail_mode="timeout") 的异常会被 _get_pending_requests 捕获，返回 0，网络被视为空闲
2. 熔断器计数：execute() 在所有重试耗尽后调用一次 record_failure()，failure_count 至少为 1
3. 快速导航：mock 每次返回不同 URL 时，change_count 会在 timeout 内达到，返回 True
4. 滚动停止：第一次滚动后高度不变时停止，loaded_pages=1 是正确行为

可靠性改进说明与最佳实践

可靠性改进要点

智能等待策略：

• 采用 networkidle、stable、selector 三重等待策略，根据页面类型自动选择最优策略
• networkidle 适用于动态加载页面，等待网络请求空闲后操作
• stable 适用于内容渲染页面，等待页面稳定后操作
• selector 适用于元素级操作，等待目标元素出现后操作

自动重试与熔断机制：

• 指数退避重试：base_delay * 2^attempt + jitter，最大重试次数可配置
• 熔断器保护：连续失败 N 次后暂停，超时后自动恢复
• 可配置 retry_on 只重试特定错误类型，避免无效重试

动态内容处理：

• DynamicLoader 支持无限滚动加载，自动检测页面高度变化
• 虚拟列表自动去重，基于元素文本相似度过滤重复内容
• Shadow DOM 和 iframe 内容自动穿透抓取

反检测模式：

• 移除 navigator.webdriver 属性，模拟真实浏览器指纹
• 随机 User-Agent 轮换，降低被识别风险
• 人类化鼠标轨迹和打字节奏，模拟真实用户行为
• 请求间隔随机化，避免固定频率触发反爬机制

使用最佳实践

搜索器使用最佳实践：

1. 配置优化：根据目标网站特性调整 wait_timeout、max_results、retry_count 参数
2. 批量搜索：使用 search_batch 方法批量搜索多个关键词，自动合并去重
3. 结果保存：使用 save_json、save_csv、save_markdown 方法保存结果
4. 健康检查：定期调用 health_check 方法检查搜索器状态
5. 资源释放：使用完毕后调用 close 方法释放浏览器资源

浏览器操作最佳实践：

1. 实例管理：固定使用 --name 参数保持登录态，避免每次新建实例
2. 等待策略：SPA 页面使用 --wait-for networkidle，传统页面使用 --wait-for stable
3. 反检测：敏感网站启用 --stealth 参数，降低被封禁风险
4. 验证码处理：启用 --handle-captcha 参数，自动检测并处理常见验证码
5. 内容抓取：大页面使用 --max-chars 控制输出长度，完整内容使用 --save 写文件

协作模式最佳实践：

1. 观察模式：轮询判断用户操作完成情况，不干预用户操作
2. 建议模式：分析页面状态，提供操作建议供用户决策
3. 代劳模式：在用户确认后自动执行操作，提高操作效率

常见问题与解决方案

问题	原因	解决方案
页面加载超时	网络慢/反爬检测	增加 --timeout，启用 --stealth
验证码无法处理	复杂验证码类型	使用 --handle-captcha 查看提示，手动处理
内容抓取为空	SPA 未渲染完成	使用 --wait-for networkidle 或 stable
元素找不到	动态加载/Shadow DOM	使用 ComplexDOMHandler 或增加等待时间
IP 被封禁	请求频率过高	降低频率，使用代理池
搜索结果重复	去重策略未启用	启用 dedup_by_title 或 dedup_by_url 去重
批量搜索失败	关键词过多	分批搜索，每批不超过 10 个关键词
结果保存失败	路径不存在	创建输出目录或使用绝对路径

新增搜索器（2026-08）

搜索器	目标网站	领域	优先级	反爬强度
GovServiceSearcher	https://www.gjzwfw.gov.cn	政府服务	P0	弱
StatsSearcher	https://www.stats.gov.cn	政府统计	P0	弱
LegalSearcher	https://www.12348.gov.cn	法律服务	P1	弱
MedicalSearcher	https://www.health.gov.cn	医疗健康	P1	中
SportsSearcher	https://www.sport.gov.cn	体育资讯	P2	弱
FoodSearcher	https://www.meishi.com	美食平台	P2	中

使用示例：

from src.searchers import StatsSearcher, LegalSearcher, MedicalSearcher

# 统计局数据搜索
stats = StatsSearcher()
results = stats.search("GDP 2024")

# 法律条文搜索
legal = LegalSearcher()
results = legal.search("民法典")

# 医疗健康搜索
medical = MedicalSearcher()
results = medical.search("感冒症状")

新领域覆盖：政府服务、法律、医疗健康、体育、美食

技术特点：

• 政府类网站反爬弱，无需 stealth 模式
• 法律/医疗网站结构规范，提取成功率高
• 体育/美食网站需处理动态加载内容

动态页面支持（v0.9.6）

本 skill 新增动态页面支持模块 src/core/dynamic_page_support.py，整合以下核心能力：

1. 元素加载等待

# 等待元素出现（自适应策略）
python src/core/browser_browse.py --tab <id> --wait-selector "#result" --timeout 10

# 等待页面完全就绪（网络空闲 + 元素 + 内容稳定）
python src/core/browser_browse.py --tab <id> --wait-page-ready --wait-page-selector ".content"

Python API：

from src.core.dynamic_page_support import DynamicPageSupport

support = DynamicPageSupport(session)

# 等待单个元素
await support.wait_for_element("#result", timeout=10)

# 等待多个元素
results = await support.wait_for_elements([".item1", ".item2"], all_required=False)

# 等待页面完全就绪
await support.wait_for_page_ready(selector=".main-content", timeout=30)

2. 滚动触发懒加载

# 滚动加载内容（无限滚动）
python src/core/browser_browse.py --tab <id> --scroll-load --scroll-item-selector ".item" --scroll-max-pages 10

# 等待懒加载图片完成
python src/core/browser_browse.py --tab <id> --wait-lazy --wait-lazy-selector "img[data-src]"

Python API：

from src.core.dynamic_page_support import DynamicPageSupport

support = DynamicPageSupport(session)

# 智能滚动加载
result = await support.scroll_to_load(
    item_selector=".product-item",
    max_pages=10,
    max_items=100,
)
print(f"加载了 {result.pages_loaded} 页，{result.items_found} 项")

# 加载虚拟列表
items = await support.load_virtual_list(
    item_selector=".list-item",
    max_items=200,
)

# 等待懒加载图片
loaded = await support.wait_for_lazy_images(
    selector="img[data-src]",
    timeout=10,
)
print(f"已加载 {loaded} 张图片")

# 滚动并收集内容
items = await support.scroll_and_collect(
    item_selector=".post",
    max_items=100,
    max_pages=10,
)

3. SPA 路由变化监听

# 等待 SPA 路由稳定
python src/core/browser_browse.py --tab <id> --wait-spa-route --wait-spa-url "/search"

Python API：

from src.core.dynamic_page_support import DynamicPageSupport

support = DynamicPageSupport(session)

# 检测 SPA 框架
spa_info = await support.detect_spa()
print(f"框架: {spa_info.framework.value}, 版本: {spa_info.version}")

# 等待路由稳定
await support.wait_for_spa_route(timeout=15, expected_url="/search")

4. DOM 变化监听

from src.core.dynamic_page_support import DynamicPageSupport

support = DynamicPageSupport(session)

# 等待 DOM 稳定
await support.wait_for_dom_stable(timeout=30)

# 等待内容变化
await support.wait_for_content_change(selector=".feed", min_changes=5)

5. 使用场景示例

场景 1：抓取社交媒体时间线

# 导航并等待页面就绪
python src/core/browser_browse.py --tab <id> --goto "https://social.example.com" --wait-page-ready

# 滚动加载内容
python src/core/browser_browse.py --tab <id> --scroll-load --scroll-item-selector ".post" --scroll-max-pages 20

# 等待懒加载图片
python src/core/browser_browse.py --tab <id> --wait-lazy

场景 2：抓取电商商品列表

# 导航到商品列表页
python src/core/browser_browse.py --tab <id> --goto "https://shop.example.com/products" --stealth

# 等待商品列表加载
python src/core/browser_browse.py --tab <id> --wait-selector ".product-list" --timeout 15

# 滚动加载所有商品
python src/core/browser_browse.py --tab <id> --scroll-load --scroll-item-selector ".product-item" --scroll-max-pages 10

场景 3：SPA 应用导航

# 导航并等待 SPA 路由稳定
python src/core/browser_browse.py --tab <id> --goto "https://app.example.com" --detect-spa --smart-wait

# 点击导航链接
python src/core/browser_browse.py --tab <id> --click-index 3

# 等待新路由稳定
python src/core/browser_browse.py --tab <id> --wait-spa-route --wait-spa-url "/search"

6. 配置参数

参数	默认值	说明
timeout	10.0s	等待超时时间
max_pages	10	最大滚动页数
max_items	100	最大收集项数
scroll_distance	800px	每次滚动距离
scroll_delay	0.8s	滚动间隔
stable_count	3	内容稳定检测次数
idle_timeout	0.5s	网络空闲阈值

7. 最佳实践

1. 先检测页面类型：使用 --detect-spa 检测是否为 SPA，再选择等待策略
2. 合理设置超时：动态页面建议 --timeout 15-30，避免过早超时
3. 限制滚动次数：使用 --scroll-max-pages 防止无限滚动导致内存溢出
4. 组合使用：--wait-page-ready 可一次性完成网络空闲 + 元素 + 内容稳定检测
5. 去重收集：scroll_and_collect 自动去重，避免重复收集相同内容

8. 高级动态场景等待（v0.9.7）

DynamicPageSupport 新增 19 个高级动态场景等待方法，覆盖 AJAX、动画、iframe、WebSocket、Shadow DOM、Cookie 弹窗、骨架屏、字体加载、弹窗关闭、视频加载、Canvas 渲染、WebGL、Intersection Observer、Resize 稳定、Service Worker、PWA 安装、JS 错误收敛、性能稳定等场景：

方法	说明
wait_for_ajax_complete()	等待所有 AJAX 请求完成
wait_for_animation_complete()	等待 CSS 动画结束
wait_for_iframe_loaded()	等待 iframe 内容加载
wait_for_websocket_ready()	等待 WebSocket 连接建立
wait_for_shadow_dom()	等待 Shadow DOM 渲染完成
wait_for_cookie_consent()	等待 Cookie 同意弹窗关闭
wait_for_loading_spinner()	等待加载转圈消失
wait_for_skeleton_screen()	等待骨架屏消失
wait_for_font_loaded()	等待自定义字体加载
wait_for_popup_closed()	等待弹窗关闭
wait_for_video_loaded()	等待视频加载完成
wait_for_canvas_rendered()	等待 Canvas 渲染完成
wait_for_webgl_ready()	等待 WebGL 上下文就绪
wait_for_intersection()	等待元素进入视口
wait_for_resize_stable()	等待元素尺寸稳定
wait_for_service_worker()	等待 Service Worker 注册完成
wait_for_pwa_install()	等待 PWA 安装提示出现
wait_for_js_error_settled()	等待 JS 错误收敛
wait_for_performance_stable()	等待页面性能稳定

from src.core.dynamic_page_support import DynamicPageSupport

support = DynamicPageSupport(session)

# 等待 AJAX 完成
await support.wait_for_ajax_complete(timeout=10)

# 等待 Cookie 弹窗关闭
await support.wait_for_cookie_consent(timeout=15)

# 等待 iframe 加载
await support.wait_for_iframe_loaded(selector="iframe.embed", timeout=10)

# 等待元素进入视口
await support.wait_for_intersection(selector=".main-content", timeout=10)

高级交互操作（v0.9.7）

本 skill 新增交互操作模块 src/core/browser_interaction.py，在基础点击/输入之上提供 10 个高级交互方法：

1. 拖拽操作

# 拖拽元素（通过索引）
python src/core/browser_interaction.py --tab <id> --drag-from-index 1 --drag-to-index 2

# 拖拽元素（通过选择器）
python src/core/browser_interaction.py --tab <id> --drag-from-selector ".draggable" --drag-to-selector ".drop-zone"

Python API：

from src.core.browser_interaction import BrowserInteraction

interaction = BrowserInteraction(session)

# 拖拽
result = await interaction.drag_and_drop(
    source_selector=".draggable",
    target_selector=".drop-zone",
)

# 拖拽到坐标
result = await interaction.drag_and_drop_to(
    source_selector=".draggable",
    x=500, y=300,
)

2. 悬停点击

# 悬停后点击
python src/core/browser_interaction.py --tab <id> --hover-and-click --hover-selector ".menu-item" --click-selector ".submenu a"

Python API：

# 悬停后点击
result = await interaction.hover_and_click(
    hover_selector=".menu-item",
    click_selector=".submenu a",
)

3. 右键点击

python src/core/browser_interaction.py --tab <id> --right-click-selector ".context-menu-target"

4. 双击

python src/core/browser_interaction.py --tab <id> --double-click-selector ".editable"

5. 下拉选择

python src/core/browser_interaction.py --tab <id> --select-dropdown --selector "select.country" --value "CN"

Python API：

# 通过值选择
result = await interaction.select_dropdown(
    selector="select.country",
    value="CN",
)

# 通过索引选择
result = await interaction.select_dropdown_by_index(
    selector="select.country",
    index=2,
)

6. 文件上传

python src/core/browser_interaction.py --tab <id> --upload-file --selector "input[type='file']" --file "/path/to/file.pdf"

7. 滚动到元素

python src/core/browser_interaction.py --tab <id> --scroll-to-selector ".bottom-content"

8. 填写并提交表单

python src/core/browser_interaction.py --tab <id> --fill-and-submit \
    --fields "name=John,email=john@example.com" \
    --submit-selector "button[type='submit']"

Python API：

result = await interaction.fill_and_submit(
    fields={"name": "John", "email": "john@example.com"},
    submit_selector="button[type='submit']",
)

9. 带标注截图

# 截图并标注指定元素
python src/core/browser_interaction.py --tab <id> --screenshot-annotated --selector ".highlight-me" --output ./annotated.png

10. 执行 JavaScript

# 执行 JS 并返回结果
python src/core/browser_interaction.py --tab <id> --exec-js "document.title"

# 执行带参数的 JS
python src/core/browser_interaction.py --tab <id> --exec-js "(x, y) => x + y" --args "1,2"

Python API：

# 执行 JS
result = await interaction.execute_javascript("document.title")

# 执行带参数的 JS
result = await interaction.execute_javascript(
    "(x, y) => x + y",
    args=[1, 2],
)

交互操作参数速查

参数	说明
--drag-from-index N	拖拽源元素索引
--drag-to-index N	拖拽目标元素索引
--drag-from-selector CSS	拖拽源选择器
--drag-to-selector CSS	拖拽目标选择器
--hover-and-click	悬停后点击
--hover-selector CSS	悬停目标选择器
--click-selector CSS	点击选择器
--right-click-selector CSS	右键点击
--double-click-selector CSS	双击
--select-dropdown	下拉选择
--selector CSS	下拉框选择器
--value TEXT	选择值
--upload-file	文件上传
--file PATH	上传文件路径
--scroll-to-selector CSS	滚动到元素
--fill-and-submit	填写并提交
--fields KEY=VAL,...	表单字段
--screenshot-annotated	带标注截图
--exec-js CODE	执行 JS
--args ARGS	JS 参数（逗号分隔）

数据质量评估机制（v0.9.8）

本 skill 新增数据质量评估机制，支持定期评估、趋势追踪、自动告警和优化建议生成。

核心组件

组件	文件路径	用途
DataQualityEvaluator	src/evaluators/data_quality_evaluator.py	多维度质量评估（6 维度加权评分）
DataQualityMonitor	src/evaluators/data_quality_evaluator.py	趋势追踪、告警管理、报告生成
DataQualityTracker	scripts/data_quality_tracker.py	记录质量数据、生成趋势报告、管理告警
OptimizationSuggester	scripts/optimization_suggester.py	根据质量数据自动生成优化建议
QualityDashboard	scripts/quality_dashboard.py	生成 markdown/html/json 格式质量报告
QualityScheduler	scripts/quality_scheduler.py	定时调度评估任务、管理调度配置
run_quality_assessment	scripts/run_quality_assessment.py	一键集成入口，整合所有模块

快速开始

# 一键运行完整评估（推荐）
python scripts/run_quality_assessment.py --site baidu

# 记录单个站点的质量数据
python scripts/data_quality_tracker.py --site baidu --record

# 记录所有站点的质量数据
python scripts/data_quality_tracker.py --all --record

# 查看趋势报告
python scripts/data_quality_tracker.py --site baidu --report

# 查看告警
python scripts/data_quality_tracker.py --alerts

# 生成优化建议
python scripts/optimization_suggester.py --site baidu

# 生成质量报告（markdown/html/json）
python scripts/quality_dashboard.py --site baidu --format markdown

# 定时调度评估
python scripts/quality_scheduler.py --run --site baidu
python scripts/quality_scheduler.py --status

评估维度

维度	权重	说明	告警阈值
抓取成功率	30%	页面访问成功率	< 70%
页面加载性能	20%	平均导航时间	< 60 分
元素定位准确率	20%	搜索结果数量	< 70%
反检测能力	15%	stealth 模式得分	< 60 分
稳定性	10%	场景成功率	< 70%
错误恢复能力	5%	错误处理得分	< 60 分

质量数据记录

from scripts.data_quality_tracker import DataQualityTracker

tracker = DataQualityTracker()

# 记录质量数据
quality_data = {
    "overall_score": 85.0,
    "scraping_success": {"score": 90.0},
    "performance": {"score": 80.0},
    "element_accuracy": {"score": 85.0},
    "anti_detection": {"score": 85.0},
    "stability": {"score": 85.0},
    "error_recovery": {"score": 80.0},
}
tracker.record_quality("baidu", quality_data)

# 获取趋势
trend = tracker.get_trend("baidu", "overall_score", days=7)

# 获取摘要
summary = tracker.get_summary("baidu", days=7)

# 查看告警
alerts = tracker.get_alerts(hours=24)

优化建议生成

from scripts.optimization_suggester import OptimizationSuggester
from scripts.data_quality_tracker import DataQualityTracker

tracker = DataQualityTracker()
suggester = OptimizationSuggester(tracker)

# 生成建议
suggestions = suggester.generate_suggestions("baidu", days=7)

# 生成报告
report = suggester.generate_report("baidu", days=7)
print(report)

调度器使用

from scripts.evaluation_scheduler import EvaluationScheduler

scheduler = EvaluationScheduler()

# 运行单个站点评估
result = scheduler.run_evaluation("baidu", stealth=True)

# 运行所有站点评估
results = scheduler.run_all(stealth=False)

# 查看状态
status = scheduler.get_status()
print(f"上次运行: {status['last_run']}")
print(f"平均得分: {status['avg_score']:.1f}")

# 设置调度
scheduler.set_schedule("0 2 * * *", ["baidu", "bing", "zhihu"])

数据持久化

质量数据存储在 .agent/ 目录下：

文件	内容
.agent/quality_history.json	历史质量记录
.agent/quality_alerts.json	告警记录
.agent/scheduler_config.json	调度配置

最佳实践

1. 定期评估：建议每天运行一次评估，记录质量数据
2. 趋势监控：关注 7 天趋势，及时发现性能下降
3. 告警响应：收到告警后立即检查，必要时调整策略
4. 优化迭代：根据建议调整配置，下次评估验证效果
5. 批量评估：使用 --all 参数批量评估所有站点

与评估框架集成

数据质量追踪器可与现有评估框架集成：

from scripts.run_evaluation import EvaluationRunner
from scripts.data_quality_tracker import DataQualityTracker

# 运行评估
runner = EvaluationRunner(output_dir="./output/evaluations")
result = runner.run_website(website_config)

# 记录质量数据
tracker = DataQualityTracker()
tracker.record_quality(
    result["name"],
    result.get("report", {}).get("dimensions", {})
)

新模块：DataQualityEvaluator（v0.9.8）

新增多维度质量评估器，支持 6 个维度加权评分：

from src.evaluators.data_quality_evaluator import DataQualityEvaluator, DataQualityMonitor

# 创建评估器
evaluator = DataQualityEvaluator()

# 评估单个站点
result = evaluator.evaluate(
    site_name="baidu",
    scraping_success=90.0,
    performance=80.0,
    element_accuracy=85.0,
    anti_detection=85.0,
    stability=85.0,
    error_recovery=80.0,
)
print(f"综合得分: {result['overall_score']:.1f}")

# 创建监控器
monitor = DataQualityMonitor()

# 记录质量数据
monitor.record_quality("baidu", result)

# 生成报告
report = monitor.generate_report("baidu", days=7)
print(report)

# 检查告警
alerts = monitor.check_alerts("baidu")
for alert in alerts:
    print(f"[{alert['level']}] {alert['message']}")

新模块：QualityDashboard（v0.9.8）

支持生成 markdown/html/json 三种格式的质量报告：

# 生成 markdown 报告
python scripts/quality_dashboard.py --site baidu --format markdown

# 生成 html 报告（含图表）
python scripts/quality_dashboard.py --site baidu --format html --output ./report.html

# 生成 json 报告
python scripts/quality_dashboard.py --site baidu --format json --output ./report.json

# 批量生成所有站点报告
python scripts/quality_dashboard.py --all --format markdown

新模块：QualityScheduler（v0.9.8）

定时调度评估任务：

# 立即运行评估
python scripts/quality_scheduler.py --run --site baidu

# 设置定时调度（每天凌晨 2 点）
python scripts/quality_scheduler.py --schedule "0 2 * * *" --sites baidu,bing,zhihu

# 查看调度状态
python scripts/quality_scheduler.py --status

# 停止调度
python scripts/quality_scheduler.py --stop

一键集成脚本（v0.9.8）

run_quality_assessment.py 整合所有模块，支持一键运行完整评估流程：

# 评估单个站点
python scripts/run_quality_assessment.py --site baidu

# 评估所有站点
python scripts/run_quality_assessment.py --all

# 指定输出目录
python scripts/run_quality_assessment.py --site baidu --output-dir ./reports

# 生成报告并保存
python scripts/run_quality_assessment.py --site baidu --generate-report --format html

新增模块说明（v0.9.9）

动态页面支持模块

src/core/dynamic_page_support.py 提供完整的动态页面处理能力，包括：

功能	方法	说明
元素等待	wait_for_element()	等待元素出现，支持自适应策略
多元素等待	wait_for_elements()	等待多个元素，支持必需/可选模式
滚动加载	scroll_to_load()	智能滚动加载内容
虚拟列表	load_virtual_list()	加载虚拟列表数据
SPA检测	detect_spa()	检测SPA框架（React/Vue/Angular/Next.js/Nuxt/Remix/SvelteKit）
SPA路由等待	wait_for_spa_route()	等待SPA路由稳定
懒加载图片	wait_for_lazy_images()	等待懒加载图片完成
DOM稳定	wait_for_dom_stable()	等待DOM变化稳定
页面就绪	wait_for_page_ready()	组合等待（网络+元素+内容）
滚动收集	scroll_and_collect()	滚动并收集去重内容

SPA框架支持：

• React、Vue、Angular、Svelte（基础框架）
• Next.js、Nuxt、Remix、SvelteKit（SSR框架）

交互操作模块

src/core/browser_interaction.py 提供高级交互操作：

功能	方法	说明
拖拽	drag_and_drop()	拖拽元素到目标
悬停点击	hover_and_click()	悬停后点击
右键点击	right_click()	右键点击元素
双击	double_click()	双击元素
下拉选择	select_dropdown()	选择下拉框选项
文件上传	upload_file()	触发文件上传
滚动到元素	scroll_to_element()	滚动到指定元素
填写提交	fill_and_submit()	填写表单并提交
截图标注	take_screenshot_with_annotation()	截图并标注元素
执行JS	execute_javascript()	执行JavaScript代码

显式等待模块（explicit_wait.py）

src/core/explicit_wait.py 提供结构化显式等待能力，替代隐式等待：

功能	方法	说明
条件等待	until(condition, timeout)	等待自定义条件满足
条件取反	until_not(condition, timeout)	等待条件不再满足
元素可见	until_visible(selector, timeout)	等待元素可见（含Shadow DOM支持）
元素存在	until_present(selector, timeout)	等待元素存在于 DOM
文本匹配	until_text(selector, text, exact)	等待元素包含指定文本
数量条件	until_count(selector, count, operator)	等待匹配元素数量满足条件
URL匹配	until_url_matches(pattern, timeout)	等待URL匹配正则模式
内容稳定	until_stable(selector, check_times)	等待元素内容连续多次不变

Condition 复合条件：

from src.core.explicit_wait import Condition, ExplicitWait

cond = Condition("has_text", lambda: el.text == "OK") & \n       Condition("is_visible", lambda: el.is_visible)
result = await wait.until(cond, timeout=10)

网络空闲检测模块（network_idle_detector.py）

src/core/network_idle_detector.py 提供精细化的网络空闲检测：

功能	方法	说明
等待空闲	wait_for_idle(idle_timeout, timeout, on_idle)	等待网络空闲并触发回调
获取状态	get_idle_status()	实时获取网络空闲状态
等待特定请求	wait_for_specific_request(url_pattern, timeout)	等待特定 URL 模式请求完成
重置状态	reset()	清空历史记录和请求计数

配置选项：

• idle_timeout: 空闲判定阈值（默认0.5s）
• max_pending_requests: 允许的最大 pending 数（0=严格）
• exclude_patterns: 排除的 URL 模式列表
• critical_mime_types: 关键 MIME 类型集合
• non_critical_extensions: 非关键文件扩展名集合

页面渲染完成检测模块（page_render_detector.py）

src/core/page_render_detector.py 提供多维度渲染状态检测：

功能	方法	说明
组合检测	wait_for_page_ready(timeout, require_all)	综合检测（DOM+字体+图片）
DOM稳定	wait_for_dom_stable(timeout, stable_samples)	连续N次快照无变化
字体加载	wait_for_fonts_loaded(timeout)	等待 WebFont 加载完成
图片加载	wait_for_images_loaded(timeout, include_lazy)	等待图片加载完成
内容检测	wait_for_content(selector, min_length, timeout)	等待指定内容达到最小长度
实时报告	get_render_report()	获取当前渲染状态报告

RenderStatus 字段：

• success: 是否成功
• dom_stable: DOM 是否稳定
• fonts_loaded: 字体是否加载
• images_loaded: 图片是否加载
• content_length: 有效内容长度

测试覆盖

测试文件	测试数	状态
test_dynamic_page_support.py	36	✅ 全部通过
test_browser_interaction_new.py	13	✅ 全部通过
test_browser_browse.py	46	✅ 全部通过
test_browser_interaction.py	9	✅ 全部通过

新增模块：

• explicit_wait.py: 478 行，Condition类 + ExplicitWait类 + 8个便捷方法
• network_idle_detector.py: 500 行，NetworkIdleDetector类 + CDP事件监听
• page_render_detector.py: 708 行，PageRenderDetector类 + 4维度检测

完整测试套件：922 passed, 7 failed（7个为预存问题）