diff --git a/skills/web/web-scraping-toolkit/SKILL.md b/skills/web/web-scraping-toolkit/SKILL.md new file mode 100644 index 0000000..80f933e --- /dev/null +++ b/skills/web/web-scraping-toolkit/SKILL.md @@ -0,0 +1,314 @@ +--- +name: web-scraping-toolkit +description: "五个网页抓取工具的使用手册 — Jina Reader(快)、Crawl4AI(深)、Scrapling(反爬)、CamouFox(隐身浏览器)、AutoCLI(Chrome登录态复用+AI生成)" +version: 1.1 +tools: + - jina-reader + - crawl4ai + - scrapling + - camoufox + - autocli +--- + +# Web Scraping Toolkit + +四个工具互补,覆盖从单页到批量、从简单到反爬的全场景。 + +## 1. Jina Reader — 单页极速抓取 + +**适用场景:** 快速抓取单个 URL 的正文内容,返回 Markdown 格式。最适合调研、阅读文章、提取信息。 + +**无需 API Key**,直接用 HTTP 请求: + +```python +# 终端/curl 方式(最快) +# curl -s -L "https://r.jina.ai/{URL}" -H "Accept: text/plain" + +# Python 方式 +import requests + +def jina_read(url: str) -> str: + """抓取单个页面,返回 Markdown 文本""" + resp = requests.get( + f"https://r.jina.ai/{url}", + headers={"Accept": "text/plain"} + ) + return resp.text + +# 高级用法 — 返回 JSON(含标题、链接等元数据) +def jina_read_json(url: str) -> dict: + resp = requests.get( + f"https://r.jina.ai/{url}", + headers={"Accept": "application/json"} + ) + return resp.json() +``` + +**高级 Header:** +- `X-With-Links-Summary: true` — 返回页面所有链接 +- `X-With-Images-Summary: true` — 返回页面所有图片 +- `X-Return-Format: html` — 返回原始 HTML 而非 Markdown +- `X-Set-Cookie: key=value` — 传递 Cookie + +**限制:** 免费额度有速率限制(约 20 req/min),大批量请用 Crawl4AI。 + +--- + +## 2. Crawl4AI — 批量深度抓取 + +**适用场景:** 批量抓取整个网站、多页爬取、JS 渲染页面、结构化数据提取。 + +```python +import asyncio +from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode + +async def crawl_single(url: str): + """抓取单页(带 JS 渲染)""" + browser_config = BrowserConfig(headless=True) + run_config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS) + + async with AsyncWebCrawler(config=browser_config) as crawler: + result = await crawler.arun(url=url, config=run_config) + return { + "url": result.url, + "markdown": result.markdown, + "html": result.html, + "links": result.links, + "media": result.media, + } + +async def crawl_batch(urls: list[str]): + """批量抓取多个 URL""" + browser_config = BrowserConfig(headless=True) + run_config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS) + + async with AsyncWebCrawler(config=browser_config) as crawler: + results = await crawler.arun_many(urls=urls, config=run_config) + return [{"url": r.url, "markdown": r.markdown} for r in results] + +async def crawl_site(base_url: str, max_pages: int = 20): + """深度爬取整个站点""" + browser_config = BrowserConfig(headless=True) + run_config = CrawlerRunConfig( + cache_mode=CacheMode.BYPASS, + max_pages=max_pages, + ) + + async with AsyncWebCrawler(config=browser_config) as crawler: + results = await crawler.arun(url=base_url, config=run_config) + return results +``` + +**关键配置:** +- `BrowserConfig(headless=True, browser_type="chromium")` — 默认 Chromium +- `CrawlerRunConfig(css_selector="article")` — 只提取特定 CSS 区域 +- `CrawlerRunConfig(extracted_content_type="json")` — 配合 schema 做结构化提取 +- `CrawlerRunConfig(cache_mode=CacheMode.ENABLED)` — 启用缓存加速重复抓取 + +**注意:**crawl4ai 使用的 lxml 版本可能与 scrapling 冲突,但实际影响可忽略(6.x 向下兼容 5.x API)。 + +--- + +## 3. Scrapling — 反爬绕过专用 + +**适用场景:** 被 Cloudflare/DataDok/PerimeterX 等反爬系统保护的网站。自动模拟真实浏览器指纹。 + +```python +from scrapling import Fetcher, StealthyFetcher, PlayWrightFetcher + +# 方式1:基础 Fetcher(轻量级,自动处理简单反爬) +page = Fetcher.get("https://example.com/protected") +print(page.status, page.text[:200]) + +# 方式2:StealthyFetcher(中等反爬,使用 curl_cffi 模拟浏览器指纹) +page = StealthyFetcher.fetch("https://example.com/protected") +# 可传参:headless=True, wait_selector="css:.content", network_idle=True + +# 方式3:PlayWrightFetcher(最强反爬,真实浏览器 + stealth 插件) +page = PlayWrightFetcher.fetch( + "https://example.com/protected", + headless=True, + wait_selector="css:.main-content", + network_idle=True, + timeout=30000 +) + +# 提取数据 — CSS 选择器 +items = page.css(".product-item") +for item in items: + title = item.css_first(".title").text() + price = item.css_first(".price").text() + +# 提取数据 — XPath +links = page.xpath("//a[@class='product-link']") + +# 自动适配网页结构(智能匹配) +page = Fetcher.get("https://example.com") +similar = page.find("product-card", score_threshold=0.5) +``` + +**三种引擎对比:** +| 引擎 | 速度 | 反爬能力 | JS渲染 | 适用 | +|------|------|---------|--------|------| +| Fetcher | ⚡最快 | 低 | ❌ | 静态页面 | +| StealthyFetcher | 🚀快 | 中高 | ❌ | Cloudflare等 | +| PlayWrightFetcher | 🐌较慢 | 最高 | ✅ | 重度反爬+JS | + +--- + +## 4. CamouFox — 隐身浏览器(专治登录墙) + +**适用场景:** 需要登录才能访问的内容、复杂的反爬检测、人机验证。基于 Firefox,指纹伪装极强。 + +```python +from camoufox.sync_api import Camoufox + +# 基础用法 +with Camoufox(headless=True) as browser: + page = browser.new_page() + page.goto("https://example.com/login") + page.fill("#username", "myuser") + page.fill("#password", "mypass") + page.click("button[type=submit]") + page.wait_for_load_state("networkidle") + + # 登录后抓取内容 + content = page.content() + print(content[:500]) + +# 异步用法 +from camoufox.async_api import AsyncCamoufox + +async def stealth_browse(url: str): + async with AsyncCamoufox(headless=True) as browser: + page = await browser.new_page() + await page.goto(url) + await page.wait_for_load_state("networkidle") + return await page.content() + +# 代理模式(防 IP 封锁) +with Camoufox( + headless=True, + proxy={"server": "http://proxy:port", "username": "u", "password": "p"} +) as browser: + page = browser.new_page() + page.goto("https://example.com") + +# 反指纹增强选项 +with Camoufox( + headless=True, + humanize=True, # 模拟人类操作节奏 + os=["windows"], # 伪装为 Windows 系统 + geoip=True, # 自动匹配地理IP +) as browser: + page = browser.new_page() + page.goto("https://example.com") +``` + +**CamouFox vs Playwright 对比:** +| 特性 | Playwright | CamouFox | +|------|-----------|----------| +| 浏览器引擎 | Chromium | Firefox | +| 反指纹 | 无内置 | 内置强伪装 | +| 登录墙 | 需要手动设置 | 自然绕过 | +| Cloudflare | 偶尔被检测 | 基本不检测 | +| 速度 | 快 | 略慢 | + +**浏览器二进制管理:** +- 安装/更新:`python -m camoufox fetch` +- 当前版本:v135.0.1-beta.24 + +--- + +## 5. AutoCLI — Chrome 登录态复用 + AI 生成适配器 + +**适用场景:** 已在 Chrome 浏览器登录的站点,直接复用 Cookie 抓取数据,无需管理 API Key。55+ 站点 333 个内置命令(Twitter/X、Reddit、Bilibili、知乎、小红书、YouTube 等)。AI 可自动生成新站点适配器。 + +**GitHub:** [nashsu/AutoCLI](https://github.com/nashsu/AutoCLI) ⭐2.6k | Rust 单二进制 4.7MB | Apache 2.0 + +**安装(一行命令):** +```bash +curl -fsSL https://raw.githubusercontent.com/nashsu/autocli/main/scripts/install.sh | sh +``` + +**Chrome 扩展设置(浏览器类命令必需):** +1. 从 [Releases](https://github.com/nashsu/autocli/releases/latest) 下载 `autocli-chrome-extension.zip` +2. Chrome → `chrome://extensions` → 开发者模式 → 加载已解压扩展 +3. 扩展自动连接 autocli daemon + +**常用命令:** +```bash +# 查看所有命令 +autocli --help +autocli hackernews --help + +# 公开 API(无需浏览器) +autocli hackernews top --limit 10 +autocli hackernews top --limit 5 --format json + +# 需要浏览器+登录态 +autocli bilibili hot --limit 20 +autocli twitter search "rust lang" --limit 10 +autocli xiaohongshu search "关键词" + +# AI 命令 — 自动生成适配器 +autocli auth # 首次认证 autocli.ai +autocli generate --ai # AI 分析当前页面生成适配器 +autocli search https://example.com # 搜索已有适配器 +autocli explore # 分析网站 API +autocli cascade # 探测认证策略 + +# 多格式输出 +autocli bilibili hot --format json|yaml|csv|markdown + +# 诊断 +autocli doctor +``` + +**v0.3.2 新功能:** Chrome 扩展可视化选数据 — 在页面上点选元素,AI 自动扩展相关字段并生成完整抓取规则。 + +**与其他工具的关键区别:** +- **无需 API Key** — 直接复用 Chrome 已有登录态,其他工具都需要自己管理登录/cookie +- **CLI 原生** — 命令行直接调用,天然适合 AI Agent 集成 +- **AI 生成** — 自动分析任意网站创建适配器,其他工具需手动编写选择器 +- **速度极快** — Rust 实现,比 Node.js 原版快 12x + +**⚠️ 限制:** +- 服务器环境无 Chrome 桌面 → 无法使用 Chrome 扩展和浏览器类命令(需有桌面浏览器) +- 适合用户本地电脑运行,或在 VNC/远程桌面环境中使用 +- 公开 API 命令(hackernews 等)可在服务器直接用 + +--- + +## 快速选型指南 + +| 需求 | 工具 | 一行代码 | +|------|------|---------| +| 读一篇文章 | Jina Reader | `curl -s https://r.jina.ai/URL` | +| 批量抓100页 | Crawl4AI | `AsyncWebCrawler().arun_many(urls)` | +| 反爬网站 | Scrapling | `StealthyFetcher.fetch(url)` | +| 需要登录 | CamouFox / AutoCLI | `Camoufox(headless=True)` / `autocli x search "key"` | +| JS重页面 | Crawl4AI / Scrapling PW | 都可处理JS | +| 速度优先 | Jina Reader | 无需渲染,最快 | +| 已登录Chrome直接抓 | AutoCLI | `autocli ` | +| AI自动生成抓取规则 | AutoCLI | `autocli generate --ai` | + +## 免费代理获取(补充) + +proxy-tools.com 等网站的端口被 reCAPTCHA/付费墙保护,免费用户拿不到。替代方案: +- **proxyscrape.com 免费 API**(无需 key): + - `https://api.proxyscrape.com/v2/?request=displayproxies&protocol=socks5&timeout=5000&country=ru` + - protocol 参数:http / socks5 / socks4 + - country 参数:ISO 两字母代码,留空=全球 + - 返回纯文本 `IP:PORT` 列表 +- 免费代理可用率约 5-6%,寿命短(小时~天级别),需定期刷新 + +## 已知问题 + +1. **lxml 版本冲突**:Crawl4AI 要求 lxml~=5.3,Scrapling 要求 lxml>=6.0。实际运行中 lxml 6.x API 向下兼容 5.x,不影响使用。 +2. **Jina Reader 限速**:免费版约 20 req/min,可加 `X-No-Cache: true` 绕过缓存(但消耗更快)。大批量用 Crawl4AI 替代。 +3. **CamouFox 启动慢**:Firefox 启动比 Chromium 慢约 2-3 秒,session 复用可缓解。 +4. **Scrapling DynamicFetcher 缺依赖**:需额外安装 `msgspec`(`pip install msgspec`),否则 import 报错。 +5. **curl socks5h/socks4a 不支持**:本系统 curl 版本不支持 `--proxy socks5h` 或 `--proxy socks4a`,改用 `--socks5` / `--socks4` 参数代替。 +6. **Scrapling PlayWrightFetcher 已更名**:0.4.7 版本中叫 `DynamicFetcher`,不是 `PlayWrightFetcher`。 +7. **AutoCLI 服务器限制**:服务器无 Chrome 桌面环境,浏览器类命令(bilibili、twitter 等需 Cookie 的)不可用;公开 API 命令(hackernews 等)正常。用户本地电脑或 VNC 环境可完整使用。