scrapling

scrapling——以路由优先的自适应网页抓取

关键词：scrapling · adaptive scraping · stealthy fetch · scrapling spider

请遵守每个目标网站的条款、robots 规则、速率限制、授权边界和反滥用政策。

Scrapling 最适合在选择满足任务需求的最轻量抓取模式时使用：

• 先解析已知 HTML，再考虑使用浏览器
• 先尝试普通 HTTP，再渲染 JavaScript
• 只有在更简单的路径行不通时，才升级到隐身模式
• 只有在爬取状态管理和多页面编排成为主要难题时，才改用 spider

何时使用此技能

• 用户需要提取一个或几个页面，你必须在仅解析、HTTP 抓取、浏览器渲染或隐身模式之间做出选择
• 用户想用 scrapling extract、scrapling shell 或包装脚本进行原型开发，而不是先编写 Python
• 用户需要自适应选择器恢复，以应对目标 DOM 随时间变化
• 用户想通过 MCP 向 Agent 提供 Scrapling
• 用户准备将重复抓取扩展为整站爬取，需要了解何时适合使用 Scrapling spiders
• 用户不断倾向于 Playwright/Crawlee 风格的编排、直接拦截 API 或托管式解封工具，需要你如实说明其他选择

说明

第 1 步：选择工具前，先收集一份基本信息

收集以下最少信息：

• 目标类别：原始 HTML、普通网页、JS 渲染的应用、受保护的网站或多页面爬取
• 所需输出：CSS/XPath 提取、Markdown/文本文件、结构化记录或长时间运行的爬取输出
• 操作需求：快速探测、重复复用会话、Agent/MCP 访问或可恢复的爬取
• 限制条件：安装预算、浏览器可用性、身份验证/代理限制，以及直接访问 API/JSON 是否比 DOM 抓取更合适

遵循以下规则：

1. 如果已有 HTML，从 Selector 开始
2. 如果需要访问实时页面，从 Fetcher 开始
3. 如果内容由客户端渲染，改用 DynamicFetcher
4. 如果渲染路径仍受阻或内容为空，改用 StealthyFetcher
5. 如果任务需要排队、跟踪链接、重试或检查点，改用 spiders
6. 如果实际需求是浏览器自动化、导航前请求拦截或托管式解封工具，应转向其他方案，而不是夸大 Scrapling 的能力

详细的信息收集示例和替代方案见 references/intake-packets-and-route-outs.md。

第 2 步：安装技能（插件），并且只安装所需的软件包配置

将此路由技能注册为 jeo-skills 插件，然后安装上游 Scrapling 软件包配置。

npx skills add https://github.com/akillness/jeo-skills --skill scrapling

除非用户明确要求系统级安装，否则请在虚拟环境中安装 Python 软件包。

bash scripts/install.sh --profile parser
bash scripts/install.sh --profile fetchers
bash scripts/install.sh --profile shell
bash scripts/install.sh --profile ai
bash scripts/install.sh --profile all

默认情况下，scripts/install.sh 会同时执行这两个步骤；使用 SKIP_SKILL=1 仅安装 Python 软件包，或使用 SKIP_PACKAGE=1 仅注册插件（GLOBAL/AGENTS 选项见脚本头部）。

安装指南：

• parser——仅本地 HTML 解析
• fetchers——HTTP + 浏览器支持的抓取器
• shell——交互式 CLI shell 工作流
• ai——MCP 服务工作流
• all——仅当用户确实需要全部功能时使用

浏览器支持的流程需要运行 scrapling install。仅解析器工作流不需要。

第 3 步：选择满足需求的最轻量提取路径

A. 仅解析器路径

当已有 HTML，或用户主要需要选择器逻辑时使用此路径。

from scrapling import Selector

page = Selector(html_doc, url="https://example.com")
items = page.css("article h2::text").getall()

以下情况使用此路径：

• 本地 HTML 样例
• 已保存的响应
• 快速编写选择器
• 无需考虑网络/浏览器问题的低成本提取

B. HTTP 抓取路径

普通 HTTP 可能足够时，使用 Fetcher 或 FetcherSession。

from scrapling.fetchers import Fetcher

page = Fetcher.get("https://example.com", impersonate="chrome")
title = page.css("title::text").get()

以下情况优先使用此路径：

• 文档、博客、许多营销页面、搜索结果、简单的产品页面
• 需要低成本的重复请求并复用会话
• 只有在证据表明 HTTP 不足时，用户才需要渲染后的 HTML

C. 动态浏览器路径

当目标由 JS 渲染时，使用 DynamicFetcher 或 DynamicSession。

from scrapling.fetchers import DynamicFetcher

page = DynamicFetcher.fetch(
    "https://example.com/app",
    network_idle=True,
    wait_selector=".content"
)

适用于以下情况：

• 页面是 SPA／仪表板
• 内容仅在客户端渲染后才会显示
• 少量交互或等待控制就足够

D. 隐匿路径

只有当较轻量的路径因防护机制而失效时，才使用 StealthyFetcher 或 StealthySession。

from scrapling.fetchers import StealthyFetcher

page = StealthyFetcher.fetch(
    "https://example.com/protected",
    headless=True,
    solve_cloudflare=True
)

重要提示：

• 将反机器人处理视为已记录的功能，而非保证
• 如果目标仍然无法访问或需要更强的基础设施，请如实转用代理或托管解封服务，而不要假装再加一个标志就总能解决问题

Fetcher／会话的详细信息见 references/fetchers-and-sessions.md。

第 4 步：仅在选择器漂移是问题时使用自适应抓取

当 DOM 发生变化，但语义目标仍然相同时，自适应抓取很有价值。

from scrapling.fetchers import Fetcher

Fetcher.configure(adaptive=True)
page = Fetcher.get("https://example.com")
saved = page.css(".product", auto_save=True)
relocated = page.css(".product", adaptive=True)

请记住：

• adaptive=True 需显式启用
• auto_save=True 会保存指纹，供之后复用
• 也可以使用手动的 save()、retrieve() 和 relocate() 流程
• 这有助于应对脆弱的选择器，但无法解决身份验证失败或完整的网站改版策略问题

解析器／自适应功能的详细信息见 references/parser-and-adaptive.md。

第 5 步：选择合适的操作界面

CLI／Shell

当用户需要快速输出文件或优先使用终端探测时，使用 CLI。

bash scripts/run-extract.sh get "https://example.com" article.md --css-selector "article"
bash scripts/run-extract.sh fetch "https://app.example.com" content.md --network-idle
bash scripts/run-extract.sh stealth "https://protected.example.com" content.md --solve-cloudflare

当用户需要交互式 REPL，而不是独立脚本时，使用 scrapling shell。

MCP

当目标是为 Agent 提供访问能力，而不是编写专用抓取脚本时，使用 MCP。

bash scripts/run-mcp.sh
bash scripts/run-mcp.sh --http --host 127.0.0.1 --port 8000

本地 Agent 集成从 stdio 开始；只有在环境本身已要求可流式传输的 HTTP 时，才使用 HTTP。

CLI／MCP 的详细信息见 references/cli-and-mcp.md。

第 6 步：仅当爬取状态很重要时才改用 spiders

当任务需要以下功能时，使用 spiders：

• 多个页面和链接跟踪
• 重试和阻止响应处理
• 并发和会话路由
• 通过 crawldir 暂停／恢复检查点

对于一两个彼此独立的页面，fetcher 仍然更简单。

from scrapling.spiders import Spider, Response

class QuotesSpider(Spider):
    name = "quotes"
    start_urls = ["https://quotes.toscrape.com/"]

    async def parse(self, response: Response):
        for quote in response.css(".quote"):
            yield {"text": quote.css(".text::text").get()}

Spider 的详细信息见 references/spiders.md。

第 7 步：针对文献／数据集目标执行研究采集关卡

当目标是科学文献、引文元数据或数据集（而非一般网页内容）时，始终执行此步骤，并遵循 ai4s-research/open-science 中由脚本支持的确定性技能模式。

python3 scripts/research_harvest_gate.py "https://arxiv.org/abs/2401.00001"

该关卡仅使用标准库，并输出一个 ```review 围栏包围的 JSON 块，用于标记 robots.txt 中的禁止／抓取延迟规则，以及已知的付费墙出版商启发式判断。它绝不会声称抓取已获授权——在采集之前，必须解决或明确接受每项发现。完整模式和交接指南见 references/research-harvesting.md。

示例

示例 1：我已经有 HTML，只需要选择器

使用 Selector，而非浏览器。

示例 2：营销页面通过纯 HTTP 加载

从 Fetcher 或 scrapling extract get 开始；只有证据表明内容缺失时才升级方案。

示例 3：React 仪表板在 JS 运行前是空白的

改用 DynamicFetcher，并使用 network_idle 或 wait_selector。

示例 4：受保护的目标返回了挑战页面

尝试 StealthyFetcher，但要明确说明可能仍需要更强的代理／解封基础设施。

示例 5：Agent 需要有限范围的网页提取

通过 MCP 提供 Scrapling，而不是一开始就强制编写手写抓取器。

示例 6：任务已发展为真正的爬取

从重复抓取转为使用 spiders，并启用检查点和会话控制。

示例 7：目标是论文、数据集或引用来源

先运行 scripts/research_harvest_gate.py，处理或接受其检查结果，然后 优先使用元数据 API（Crossref/OpenAlex/Semantic Scholar），而不是抓取 渲染后的摘要页面。

最佳实践

1. 从最小可行模式开始，只有在有证据时才升级。
2. 如果直接 API/JSON 访问才是事实来源，优先使用这种方式；不要强行对以浏览器为主的应用进行 DOM 抓取。
3. 对重复请求重用会话，而不是每访问一个页面就重新启动浏览器。
4. 仅在选择器漂移时使用自适应抓取，不要把它当作应对所有故障模式的通用修复方案。
5. 优先使用 CSS 选择器，并输出 .md 或 .txt，以缩小模型上下文。
6. 将 CLI、MCP 和 spiders 视为构建在同一套路由逻辑之上的操作界面，而不是三个互不相关的功能。
7. 当 Scrapling 不再适合时，应如实改用 Playwright/Crawlee 风格的自动化、外部解封工具或其他提取服务。
8. 抓取科学文献、数据集或引用来源前，先运行研究采集关卡——切勿将关卡检查通过视为已获授权的证明。

参考资料

• references/intake-packets-and-route-outs.md

• references/fetchers-and-sessions.md

• references/parser-and-adaptive.md

• references/cli-and-mcp.md

• references/spiders.md

• references/research-harvesting.md — 用于科学文献/数据集采集的确定性关卡模式，以 ai4s-research/open-science 为范本

• scripts/install.sh — 将此技能安装为插件（npx skills add），并安装上游 Python 包配置

• scripts/research_harvest_gate.py — 仅使用标准库的 robots.txt + 付费墙启发式研究采集关卡

• scripts/run-extract.sh

• scripts/run-mcp.sh

• Scrapling GitHub 仓库

• Scrapling 文档