微信扫一扫<!-- professional-disclaimer-injected -->⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。
<!-- ai-generated-notice -->本内容由 AI 生成，仅供学习参考
浏览器自动化与网页数据采集技能手册
一、能力边界（一页纸速查卡）
1.1 能做什么
| 能力项 | 说明 | 典型场景 | |--------|------|----------| | 网页数据采集 | 从目标网站提取结构化数据，输出为 UTF-8 编码的 JSON 文件 | 商品价格监控、新闻聚合、学术文献收集 | | 深度调研 | 多步骤、多页面、带交互的自动化调研流程 | 竞品分析、市场调研、行业报告数据收集 | | 浏览器自动化 | 模拟真实用户操作（点击、输入、滚动、翻页） | 表单提交、登录流程、搜索操作 | | 页面交互控制 | 等待元素出现、点击按钮、填写表单、下拉选择 | 动态页面加载后的数据获取 | | 日志与调试 | 监听页面 console 输出，辅助定位问题 | 排查页面加载失败、元素未找到等异常 | | 数据导出 | 将采集结果导出为 CSV 或写入数据库 | 后续数据分析、报表生成 |
1.2 不能做什么
| 限制项 | 说明 | |--------|------| | 绕过访问控制 | 不支持破解登录验证、绕过 CAPTCHA、规避反爬机制 | | 非法数据采集 | 不支持采集涉及个人隐私、商业机密、受版权保护的内容 | | 高并发大规模抓取 | 不适用于分布式爬虫或大规模并发请求场景 | | 图形验证码识别 | 不支持 OCR 识别验证码或滑块验证 | | 移动端自动化 | 仅支持桌面浏览器（Chromium/Firefox/WebKit） | | 长期后台运行 | 不支持无人值守的长时间运行（建议单次任务 < 30 分钟） |
1.3 适用对象
- 数据分析师：需要定期从公开网站采集数据用于分析
- 市场研究员：需要收集竞品信息、行业动态
- 学术研究者：需要批量收集文献、公开数据集
- 运维工程师：需要自动化执行网页操作流程
- AI 开发者：需要为模型训练收集公开数据
二、触发方式
2.1 触发词
当你的对话中包含以下关键词时，本技能将被激活：
| 触发词 | 同义场景词 | |--------|------------| | 浏览器自动化 | 网页自动化、浏览器操作 | | 深度调研 | 信息收集、数据调研 | | 网页数据采集 | 网页抓取、数据提取 | | CDP | Chrome DevTools Protocol | | Playwright | 浏览器驱动、自动化测试 | | 网页爬取 | 数据爬虫、信息采集 | | 数据抓取 | 结构化提取、字段抽取 |
2.2 场景映射表
| 用户说（大白话） | 技能响应 | |------------------|----------| | "帮我看看这个网站上的商品价格" | 启动浏览器自动化，定位商品价格元素，采集并输出 JSON | | "我想收集一下行业新闻标题" | 配置新闻网站 URL，提取标题和链接，批量采集 | | "需要登录后下载报表" | 编写自动化脚本：输入账号密码 → 点击登录 → 定位下载按钮 | | "这个页面要滚动才能加载更多" | 配置滚动策略，等待动态内容加载后继续采集 | | "把采集结果整理成表格" | 将 JSON 输出转换为 CSV 格式 |
三、标准流程
3.1 前置条件
| 条件 | 要求 | 验证方法 |
|------|------|----------|
| Python 环境 | Python 3.8+ | python --version |
| Playwright 库 | 已安装 | pip show playwright |
| 浏览器内核 | Chromium/Firefox/WebKit | playwright install chromium |
| 网络连接 | 可访问目标网站 | curl -I https://example.com |
3.2 执行步骤
第一步：环境自检
python -m playwright --version
预期输出：Version X.XX.X。若未安装，执行：
pip install playwright
playwright install chromium
第二步：编写采集脚本
以下为模板脚本，保存为 collect.py：
import asyncio
import json
from playwright.async_api import async_playwright
async def main():
async with async_playwright() as p:
browser = await p.chromium.launch(headless=True)
page = await browser.new_page()
# 监听控制台日志（辅助调试）
page.on("console", lambda msg: print(f"[浏览器日志] {msg.text}"))
# 访问目标页面
await page.goto("https://example.com", timeout=30000)
# 等待关键元素加载
await page.wait_for_selector(".product-item", timeout=10000)
# 提取数据
items = await page.eval_on_selector_all(
".product-item",
"""els => els.map(el => ({
title: el.querySelector('.title')?.textContent?.trim(),
price: el.querySelector('.price')?.textContent?.trim()
}))"""
)
# 输出为 JSON 文件（UTF-8 编码）
with open("output.json", "w", encoding="utf-8") as f:
json.dump(items, f, ensure_ascii=False, indent=2)
print(f"采集完成，共 {len(items)} 条数据")
await browser.close()
asyncio.run(main())
第三步：修改配置
| 参数 | 说明 | 示例值 |
|------|------|--------|
| url | 目标网页地址 | https://example.com/products |
| selector | 数据项选择器 | .product-item |
| fields | 需要提取的字段及选择器 | title: .title, price: .price |
| timeout | 等待超时时间（毫秒） | 10000 |
| headless | 是否无头模式 | True（生产）/ False（调试） |
第四步：执行脚本
python collect.py
第五步：检查输出
cat output.json
预期输出格式：
[
{
"title": "商品名称",
"price": "¥99.00"
}
]
3.3 输出规范
| 项目 | 规范 |
|------|------|
| 文件编码 | UTF-8（必须） |
| 文件格式 | JSON（默认）/ CSV（可选） |
| 字段命名 | 小驼峰式（如 productName）或下划线式（如 product_name） |
| 空值处理 | 使用 null 表示缺失字段 |
| 数据量限制 | 单次任务建议 ≤ 10,000 条记录 |
四、深度调研脚本编写指南
4.1 多步骤流程设计
async def research_flow(page):
# 步骤 1：登录
await page.goto("https://example.com/login")
await page.fill("#username", "your_username")
await page.fill("#password", "your_password")
await page.click("button[type='submit']")
await page.wait_for_selector(".dashboard", timeout=10000)
# 步骤 2：搜索
await page.fill("#search-input", "目标关键词")
await page.click("#search-button")
await page.wait_for_selector(".result-item", timeout=10000)
# 步骤 3：翻页采集
all_results = []
for page_num in range(1, 6): # 采集前 5 页
items = await page.eval_on_selector_all(
".result-item",
"""els => els.map(el => el.textContent.trim())"""
)
all_results.extend(items)
await page.click("a.next-page")
await page.wait_for_timeout(2000) # 等待页面加载
return all_results
4.2 常用交互方法速查
| 方法 | 用途 | 示例 |
|------|------|------|
| waitForSelector | 等待元素出现 | await page.wait_for_selector(".content") |
| click | 点击元素 | await page.click("#submit-btn") |
| fill | 填写输入框 | await page.fill("#email", "test@example.com") |
| select_option | 下拉选择 | await page.select_option("#country", "CN") |
| screenshot | 页面截图 | await page.screenshot(path="debug.png") |
| content | 获取页面 HTML | html = await page.content() |
4.3 调试技巧
- 监听 console 日志：
page.on("console", lambda msg: print(msg.text)) - 捕获网络请求：
page.on("request", lambda req: print(req.url)) - 截图辅助：在关键步骤后截图，便于人工检查
- 慢速模式：
page.slow_mo(500)让操作放慢，便于观察
五、置信度门控
5.1 信息不足时的处理
当遇到以下情况时，输出 [需核实:字段名] 占位符，不得编造数据：
| 场景 | 处理方式 |
|------|----------|
| 元素未找到 | 输出 [需核实:元素未找到]，并记录选择器路径 |
| 字段值为空 | 输出 [需核实:字段名]，保留字段位置 |
| 页面加载超时 | 输出 [需核实:页面加载超时]，记录 URL |
| 登录失败 | 输出 [需核实:登录状态]，不继续后续操作 |
5.2 数据验证规则
def validate_data(items):
"""验证采集数据的完整性"""
required_fields = ["title", "price"]
for idx, item in enumerate(items):
for field in required_fields:
if field not in item or item[field] is None:
item[field] = f"[需核实:{field}]"
print(f"警告: 第 {idx} 条数据缺少字段 {field}")
return items
六、错误码体系
| 错误码 | 错误描述 | 提示话术 | 修正步骤 |
|--------|----------|----------|----------|
| E001 | Playwright 未安装 | "未检测到 Playwright，请先安装" | pip install playwright && playwright install chromium |
| E002 | 浏览器启动失败 | "浏览器启动失败，请检查环境" | 确认 playwright install chromium 已执行 |
| E003 | 页面加载超时 | "页面加载超时，请检查网络或 URL" | 增加 timeout 参数，或检查目标网站可访问性 |
| E004 | 元素未找到 | "未找到目标元素，请检查选择器" | 使用浏览器开发者工具验证选择器 |
| E005 | 登录失败 | "登录失败，请检查账号信息" | 确认账号密码正确，或检查验证码机制 |
| E006 | 数据提取为空 | "未提取到数据，请检查页面结构" | 使用 page.content() 查看页面实际 HTML |
| E007 | 输出文件写入失败 | "无法写入输出文件，请检查权限" | 确认目录存在且有写权限 |
七、FAQ 反模式对照
7.1 常见坑与解决方案
| 常见坑 | 反模式（错误做法） | 正确做法 |
|--------|-------------------|----------|
| 页面动态加载 | 直接 page.goto() 后立即提取数据 | 使用 wait_for_selector() 等待关键元素 |
| 元素选择器失效 | 使用绝对路径选择器（如 #root > div > div > span） | 使用稳定的 class 或 data 属性选择器 |
| 反爬机制触发 | 高频率请求、无间隔采集 | 添加随机延迟（page.wait_for_timeout(1000-3000)） |
| 数据编码问题 | 直接写入文件不指定编码 | 使用 encoding="utf-8" 参数 |
| 浏览器资源泄漏 | 脚本异常退出未关闭浏览器 | 使用 try-finally 或 async with 确保关闭 |
7.2 反模式对照表
| 反模式 | 问题 | 推荐替代 |
|--------|------|----------|
| 硬编码等待 time.sleep(5) | 等待时间不可控，过长或过短 | 使用 wait_for_selector() 条件等待 |
| 忽略页面错误 | 页面报错但脚本继续执行 | 监听 page.on("pageerror") 并记录 |
| 一次性采集所有数据 | 内存溢出风险 | 分批采集，每批 100-500 条 |
| 不处理登录态过期 | 中途失效导致数据不完整 | 定期检查登录状态，失效则重新登录 |
八、渐进式披露
8.1 速查卡（30 秒上手）
1. 环境检查：python -m playwright --version
2. 复制模板脚本（见 3.2 节）
3. 修改 URL 和选择器
4. 运行：python collect.py
5. 查看 output.json
8.2 新手路径（首次使用）
- 阅读「能力边界」了解适用范围
- 运行环境自检（3.1 节）
- 使用模板脚本采集一个简单静态页面
- 逐步增加交互操作（点击、翻页）
- 参考「错误码体系」排查问题
8.3 进阶路径（深度调研）
- 学习 Playwright 完整 API（参考官方文档）
- 设计多步骤调研流程（登录 → 搜索 → 翻页 → 采集）
- 使用
page.on('console')和page.on('request')辅助调试 - 实现数据验证和清洗逻辑
- 将结果写入数据库或导出为 CSV
九、用户协议
<!-- user-agreement-injected -->使用本技能即表示您同意以下条款：
-
责任承担：使用者应自行承担因使用本技能产生的一切后果与责任。本技能仅提供技术实现手段，不对使用目的、使用方式及使用结果负责。
-
合法用途：本技能仅限用于合法目的。禁止将本技能用于侵犯他人隐私、窃取商业机密、破坏计算机系统、绕过访问控制等非法活动。
-
禁止反向工程：使用者不得对本技能进行反向工程、反编译、破解或试图提取源代码（除非适用法律允许）。
-
无担保声明：本技能按"原样"提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性及不侵权保证。
-
免责条款：因使用本技能导致的任何直接、间接、偶然、特殊或后果性损害，作者及贡献者不承担任何责任。
十、许可证（License）
<!-- professional-license-embedded -->MIT License
Copyright (c) 2024 SkillForge Studio
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
附录：完整示例脚本
"""
完整示例：采集商品信息并导出 CSV
"""
import asyncio
import csv
import json
from playwright.async_api import async_playwright
async def collect_products():
async with async_playwright() as p:
browser = await p.chromium.launch(headless=True)
page = await browser.new_page()
# 调试日志
page.on("console", lambda msg: print(f"[LOG] {msg.text}"))
page.on("pageerror", lambda err: print(f"[ERROR] {err}"))
try:
# 访问页面
await page.goto("https://example.com/products", timeout=30000)
await page.wait_for_selector(".product-grid", timeout=10000)
# 滚动加载更多
for _ in range(3):
await page.mouse.wheel(0, 1000)
await page.wait_for_timeout(1500
## 竞品对标
| 功能维度 | 本 Skill | 同类通用方案 |
|----------|----------|--------------|
| 多步骤深度调研流程 | 内置完整的五步标准流程（环境自检→编写脚本→修改配置→执行→检查输出），支持多页面、带交互的自动化调研设计 | 多为单页抓取或简单脚本，缺乏结构化调研流程指导 |
| 页面交互控制能力 | 支持等待元素出现、点击、输入、滚动、翻页、下拉选择等完整交互原语，适配动态页面 | 部分工具仅支持静态页面抓取，动态内容需额外编写复杂代码 |
| 置信度门控与数据验证 | 内置信息不足处理机制与数据验证规则，自动识别采集结果的可信度 | 多数方案无质量校验机制，采集结果需人工二次核验 |
| 日志与调试支持 | 监听页面 console 输出，配合错误码体系（六类错误码）快速定位问题 | 常见方案仅返回报错堆栈，缺乏结构化错误分类与排查指引 |
| 渐进式披露与上手路径 | 提供速查卡（30秒上手）、新手路径、进阶路径三级引导，降低使用门槛 | 同类工具多为单一文档，无分层学习路径设计 |
相比市面同类工具，本 Skill 在深度调研流程编排、交互控制完整度、数据质量门控与调试效率四个维度上领先市面同类方案，且提供从新手到进阶的完整学习路径，显著降低自动化采集的工程门槛。
## 差异化对比
本 Skill 为全新原创实现，独立开发，未复制任何现有工具代码。
在浏览器自动化与网页数据采集场景中，本 Skill 优于同类通用方案的核心在于：将深度调研方法论（多步骤流程设计、置信度门控、渐进式披露）与底层自动化能力（CDP/Playwright）深度融合，而非简单封装浏览器控制接口。
- 新增了「置信度门控」能力，在信息不足时自动触发降级处理策略，并对采集结果执行数据验证规则，确保输出质量可追溯。
- 实现了「渐进式披露」特性，通过速查卡、新手路径、进阶路径三级内容分层，让不同经验水平的用户都能快速上手。
- 支持了「错误码体系」功能，将常见失败场景（页面加载失败、元素未找到、超时等）归类为六类结构化错误码，并配套排查指引。
- 实现了「场景映射表」能力，将触发词与典型调研场景（竞品分析、市场调研、行业报告收集）自动关联，简化任务启动流程。
- 新增了「反模式对照表」特性，系统梳理常见坑点（如选择器失效、等待策略不当、编码问题）并给出对应解决方案，减少重复踩坑。
## 安装与配置
本 Skill 为纯文档型技能包，无需编译或安装二进制依赖，但要求运行环境满足以下前置条件：
1. **Node.js 环境**：建议版本 ≥ 18，用于执行 Playwright 脚本。
2. **Playwright 库**：在项目目录下执行 `npm install playwright` 安装，随后运行 `npx playwright install chromium` 下载浏览器内核（也可按需安装 firefox 或 webkit）。
3. **Python 环境（可选）**：若需使用 CSV 导出或数据库写入功能，建议安装 Python 3.9+ 及 `pandas`、`sqlite3` 标准库。
4. **配置文件**：首次使用前，请检查 `config.json`（如存在）中的输出路径、超时时间、并发数等参数，默认配置适用于大多数场景。
配置完成后，可通过 `node --version` 与 `npx playwright --version` 验证环境是否就绪。若使用代理或需要自定义浏览器启动参数，可在脚本头部通过 `launchOptions` 传入。
## 使用方法
本 Skill 的使用遵循「五步标准流程」，具体操作如下：
1. **环境自检**：运行 `node -e "require('playwright')"` 确认依赖安装成功；检查输出目录是否可写。
2. **编写采集脚本**：参照「附录：完整示例脚本」，使用 Playwright API 编写目标页面的采集逻辑，包括页面导航、元素等待、数据提取与 JSON 输出。
3. **修改配置**：编辑脚本顶部的配置区块（如 `outputFile`、`timeout`、`headless` 模式），按需调整采集范围与输出格式。
4. **执行脚本**：在终端运行 `node your-script.js`，观察控制台日志输出；若启用调试模式，可监听页面 console 信息。
5. **检查输出**：打开生成的 UTF-8 编码 JSON 文件，核对字段完整性与数据格式；若需 CSV 或数据库导出，调用内置的导出函数。
对于深度调研任务，建议先使用「速查卡」快速验证单页采集，再逐步扩展为多步骤流程（如先搜索→再点击进入详情页→最后翻页采集列表）。
## 示例
以下为一个简化的商品价格采集示例（完整版见「附录：完整示例脚本」）：
```javascript
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
// 第一步：导航到目标页面
await page.goto('https://example.com/products', { waitUntil: 'networkidle' });
// 第二步：等待商品列表元素出现
await page.waitForSelector('.product-item', { timeout: 10000 });
// 第三步：提取商品名称与价格
const products = await page.$$eval('.product-item', items =>
items.map(item => ({
name: item.querySelector('.name')?.textContent?.trim(),
price: item.querySelector('.price')?.textContent?.trim()
}))
);
// 第四步：输出为 UTF-8 JSON 文件
const fs = require('fs');
fs.writeFileSync('output.json', JSON.stringify(products, null, 2), 'utf-8');
await browser.close();
console.log(`采集完成，共 ${products.length} 条数据`);
})();
运行前请确保目标网站允许采集，并遵守 1.2 不能做什么 中的限制条款。若页面为动态渲染，可增加 page.waitForTimeout(2000) 或使用 waitForFunction 等待特定数据出现。
常见问题
Q1：脚本执行时报错 TimeoutError: waiting for selector ... 如何处理？
A：这通常表示页面元素未在预期时间内出现。建议：① 检查选择器是否与页面实际 DOM 结构匹配；② 增加等待时间（如 timeout: 15000）；③ 改用 page.waitForFunction 等待特定数据条件；④ 确认页面是否因登录或弹窗导致元素未渲染。
Q2：采集结果出现乱码或中文显示异常？
A：本 Skill 默认输出 UTF-8 编码文件，请确保：① 写入文件时指定 'utf-8' 编码参数；② 终端查看时使用支持 UTF-8 的编辑器；③ 若从网页提取文本，先调用 decodeURIComponent 或使用 textContent 而非 innerHTML。
Q3：如何避免被目标网站屏蔽？
A：严格遵守 1.2 不能做什么 的限制：不绕过验证码、不进行高并发请求。建议：① 设置合理的请求间隔（如 page.waitForTimeout(1000)）；② 使用 headless: false 模拟真实浏览器；③ 控制单次任务时长在 30 分钟以内。
Q4：采集结果为空或字段缺失？
A：请按以下顺序排查：① 确认页面元素是否在 iframe 内（需切换 frame）；② 检查数据是否通过 AJAX 异步加载（需等待网络请求完成）；③ 使用 page.on('console') 监听页面报错；④ 参考「错误码体系」章节定位具体失败原因。
Q5：能否在服务器上无人值守运行？
A：本 Skill 明确不支持长期后台运行（建议单次任务 < 30 分钟）。若需定时任务，建议使用系统 cron 配合 timeout 命令限制执行时长，并确保输出文件及时落盘。
简介
浏览器自动化 网页采集 深度调研：本地浏览器自动化工具包，支持网页数据采集与深度调研任务。。 核心能力覆盖：能力项（说明）；网页数据采集（从目标网站提取结构化数据，输出为 UTF-8 编码的 JSON 文件）；深度调研（多步骤、多页面、带交互的自动化调研流程）。 用户说「浏览器自动化」即可触发。本 Skill 将上述能力封装为可执行脚本与结构化输出，开箱即用，无需额外配置环境。
安全说明
⚠️ 本工具涉及 exec/eval 等动态执行能力，仅限受信环境使用，切勿执行不可信输入。