# https://github.com/D4Vinci/Scrapling 项目说明书

生成时间：2026-06-19 20:20:20 UTC

## 目录

- [Scrapling 框架概述与系统架构](#page-overview)
- [抓取器、隐身模式与会话管理](#page-fetching)
- [解析器、自适应元素追踪与相似度匹配](#page-parsing)
- [爬虫框架、CLI、MCP 与代理/Agent 扩展](#page-spiders)

<a id='page-overview'></a>

## Scrapling 框架概述与系统架构

### 相关页面

相关主题：[抓取器、隐身模式与会话管理](#page-fetching), [解析器、自适应元素追踪与相似度匹配](#page-parsing), [爬虫框架、CLI、MCP 与代理/Agent 扩展](#page-spiders)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)
- [agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md)
- [agent-skill/Scrapling-Skill/examples/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/Scrapling-Skill/examples/README.md)
- [scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py)
</details>

# Scrapling 框架概述与系统架构

## 1. 项目定位与设计目标

Scrapling 是一个自适应的 Web 抓取框架，主打"一次请求到全规模爬取"的全场景覆盖能力。根据 [README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md) 的官方描述，框架由三大核心支柱构成：

- **自适应解析器（Adaptive Parser）**：解析阶段会学习目标站点的结构变化，当页面改版后自动重新定位元素，避免硬编码选择器失效。
- **反爬取抓取器（Fetchers）**：内置 Cloudflare Turnstile 等反机器人机制的绕过能力，开箱即用。
- **Spider 爬虫框架**：支持并发、多会话、断点续爬、代理轮换以及流式输出。

项目口号"One library, zero compromises"体现了它在单一库内同时提供解析、HTTP 抓取、浏览器自动化与爬虫编排的定位。框架的最低运行要求为 Python 3.10，安装基础包只包含解析引擎；要使用抓取器或爬虫，需要额外安装 `[fetchers]` 可选依赖并执行 `scrapling install` 下载浏览器 资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md#L1-L120)。

## 2. 整体系统架构

框架在逻辑上被划分为五大子系统，它们通过统一的 `Response` 对象串联，构成分层的抓取流水线：

```mermaid
flowchart TB
    A[Parser<br/>scrapling.core] -->|Adaptor| B[Fetchers<br/>scrapling.fetchers]
    B --> C[Fetcher / FetcherSession<br/>HTTP]
    B --> D[DynamicFetcher<br/>浏览器自动化]
    B --> E[StealthyFetcher<br/>反检测]
    C --> F[Spider 框架<br/>scrapling.spiders]
    D --> F
    E --> F
    F --> G[CLI / MCP / Agent Skill]
    F --> H[日志与工具<br/>scrapling.core.utils]
    H -.上下文注入.-> F
```

各子系统的职责如下：

- **Parser（解析引擎）**：负责 HTML 解析、CSS/XPath 选择、文本处理与自适应元素查找。性能对比显示其文本提取速度与 Parsel/Scrapy 相当（2.02 ms vs 2.04 ms），但元素相似度匹配比 AutoScraper 快 5.2 倍 资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md#L100-L160)。
- **Fetchers（抓取层）**：提供三类抓取器——`Fetcher/FetcherSession`（HTTP，支持 TLS 指纹模拟）、`DynamicFetcher`（浏览器自动化）、`StealthyFetcher/StealthySession`（隐身模式，可绕过 Cloudflare）。
- **Spiders（爬虫编排）**：基于 `start_urls` 和异步 `parse` 回调实现并发抓取，支持多会话路由、暂停/恢复、流式统计和被拦截请求自动重试 资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md#L160-L240)。
- **CLI / MCP / Agent Skill（交互与扩展层）**：CLI 提供 `scrapling extract`、`scrapling install` 等命令；MCP 服务器使 AI Agent 能够调用抓取能力；Agent Skill 兼容 OpenClaw 与 Claude Code 资料来源：[agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md#L1-L40)。
- **工具与日志（Utils）**：使用 `ContextVar` 维护上下文感知的日志对象，调用方可通过 `set_logger` 注入自定义 logger 资料来源：[scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py#L1-L60)。

## 3. 典型升级路径与社区关注点

官方示例仓库为用户提供了清晰的"由轻到重"升级路径：

```
get / FetcherSession
  └─ 若需 JS 渲染 → fetch / DynamicSession
       └─ 若遭遇反爬 → stealthy-fetch / StealthySession
            └─ 若多页面抓取 → Spider
```

该流程鼓励开发者从最轻量的 HTTP 抓取开始，仅在必要时升级到浏览器自动化或爬虫框架 资料来源：[agent-skill/Scrapling-Skill/examples/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/Scrapling-Skill/examples/README.md#L1-L50)。

社区反馈揭示了几个值得关注的边界情况：

- **OpenClaw 集成**：issue #142 请求将 Scrapling 作为 OpenClaw 技能使用，最新版本已通过 [agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md) 提供 Clawhub 一键安装方式。
- **嵌入式 Turnstile 卡死**：issue #100 报告 `StealthyFetcher` 在嵌入版 Turnstile 上会无限等待；这暗示隐身抓取器对 iframe/嵌入场景的检测逻辑尚有改进空间。
- **浏览器请求监听**：issue #159 期望框架支持过滤浏览器网络请求并获取特定响应，这是当前 `DynamicFetcher`/`StealthyFetcher` 暂未覆盖的能力。
- **分页自动检测**：issue #82 提出自动识别分页 URL 的需求，目前需由用户自行在 `parse` 回调中编写 `response.follow` 逻辑 资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md#L240-L320)。

## 4. 故障模式与最佳实践

- **依赖安装遗漏**：仅执行 `pip install scrapling` 时导入 `scrapling.fetchers` 或 `scrapling.spiders` 会抛出 `ModuleNotFoundError`；必须额外安装 `pip install "scrapling[fetchers]"` 并运行 `scrapling install` 下载浏览器内核 资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md#L120-L180)。
- **浏览器指纹更新**：v0.4.9 发布说明要求升级后必须执行 `scrapling install --force` 刷新浏览器与指纹文件，否则可能与新版本不兼容。
- **日志上下文隔离**：在并发爬虫场景下，通过 `ContextVar` 维护的 logger 可避免不同请求间的日志串扰，开发者可利用 `set_logger` 注入请求级上下文 资料来源：[scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py#L40-L60)。
- **CLI 文件输出格式**：`scrapling extract` 的输出文件名后缀决定内容格式（`.md` 转为 Markdown、`.html` 保留原始 HTML），使用 `--css-selector` 可只导出匹配区域 资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md#L300-L340)。

## See Also

- [Scrapling 选择器与解析 API](选择器与解析.md)
- [Scrapling Fetchers 抓取器详解](抓取器.md)
- [Scrapling Spider 爬虫框架](爬虫框架.md)
- [Scrapling CLI 与 MCP 集成](CLI与MCP.md)

---

<a id='page-fetching'></a>

## 抓取器、隐身模式与会话管理

### 相关页面

相关主题：[Scrapling 框架概述与系统架构](#page-overview), [解析器、自适应元素追踪与相似度匹配](#page-parsing)

```markdown
<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)
- [agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md)
- [agent-skill/Scrapling-Skill/examples/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/Scrapling-Skill/examples/README.md)
- [scrapling/fetchers/__init__.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/fetchers/__init__.py)
- [scrapling/fetchers/requests.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/fetchers/requests.py)
- [scrapling/fetchers/chrome.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/fetchers/chrome.py)
- [scrapling/fetchers/stealth_chrome.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/fetchers/stealth_chrome.py)
- [scrapling/engines/static.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/engines/static.py)
- [scrapling/engines/_browsers/_stealth.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/engines/_browsers/_stealth.py)
- [scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py)
</details>

# 抓取器、隐身模式与会话管理

## 概述

Scrapling 是一个自适应 Web 抓取框架，其核心由三层组件构成：**抓取器（Fetchers）**、**隐身引擎（Stealthy）** 与 **会话管理（Session）**。这三者协同工作，覆盖了从单次 HTTP 请求到长时间多页爬取的全部场景。本页依据仓库源码梳理它们的分工、调用方式与常见陷阱，并结合社区反馈（Issue #100、#142、#159）说明其当前能力边界。

资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)

## 抓取器家族与升级路径

Scrapling 在 `scrapling/fetchers/` 子包下暴露了多组抓取器，按照"速度由快到慢、反爬能力由弱到强"排列，并通过同步/异步两套接口对外提供服务。

| 抓取器 | 后端 | 主要用途 | 典型参数 |
| --- | --- | --- | --- |
| `Fetcher` / `AsyncFetcher` | HTTP 客户端 | 单次 API 或静态页面请求 | `impersonate`、`stealthy_headers` |
| `FetcherSession` / `AsyncFetcherSession` | HTTP 会话（上下文） | 多页快速抓取，复用连接 | `http3`、`impersonate` |
| `DynamicFetcher` / `DynamicSession` | 浏览器自动化 | SPA、JS 渲染页面 | `headless`、`network_idle` |
| `StealthyFetcher` / `StealthySession` | 隐身浏览器 | Cloudflare Turnstile、指纹伪装 | `solve_cloudflare`、`google_search` |

基础用法与高级隐身在 README 中均有示例：

```python
from scrapling.fetchers import Fetcher, FetcherSession, StealthyFetcher, StealthySession

with FetcherSession(impersonate='chrome') as session:
    page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)

with StealthySession(headless=True, solve_cloudflare=True) as session:
    page = session.fetch('https://nopecha.com/demo/cloudflare', google_search=False)
```

仓库提供的"升级指南"（位于 `agent-skill/Scrapling-Skill/examples/README.md`）建议开发者按需逐级升级：先以 `Fetcher`/`FetcherSession` 试水，必要时切换到 `DynamicSession`，遇到反爬再切换到 `StealthySession`，最终才使用 `Spider` 接管多页面爬取。

资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)、[agent-skill/Scrapling-Skill/examples/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/Scrapling-Skill/examples/README.md)

## 隐身模式与会话管理

### 隐身引擎

`StealthyFetcher` 与 `StealthySession` 在 `scrapling/fetchers/stealth_chrome.py` 中实现，其底层修改自 Playwright/Chromium，行为由 `scrapling/engines/_browsers/_stealth.py` 控制。框架默认开启 `headless=True`，并提供 `solve_cloudflare=True` 以便自动通过 Cloudflare Turnstile 验证；同时支持 `adaptive=True` 与 `auto_save=True` 让选择器在网站改版后仍可定位元素。

### 会话管理

会话对象既是上下文管理器，也是异步上下文管理器，因此同一份代码既可作为同步阻塞调用，也可放入 `asyncio` 循环中：

```python
import asyncio
from scrapling.fetchers import FetcherSession, AsyncStealthySession

async with FetcherSession(http3=True) as session:
    page1 = session.get('https://quotes.toscrape.com/')
    page2 = session.get('https://quotes.toscrape.com/', impersonate='firefox135')
```

在 `Spider` 中，可通过 `configure_sessions(self, manager)` 把不同会话按 ID 注册，并由 `Request` 对象按需路由，从而让一个爬虫同时混合使用 HTTP 与隐身浏览器。

### 日志与会话隔离

日志系统通过 `ContextVar` 实现并发隔离：`scrapling/core/utils/_utils.py` 中的 `_current_logger` 与 `LoggerProxy` 让每次会话都能携带各自的日志记录器，配合 `set_logger()` 重置。Spider 框架正是借助这一机制实现"同一进程、多会话并行"的可观测性。

资料来源：[scrapling/fetchers/__init__.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/fetchers/__init__.py)、[scrapling/engines/_browsers/_stealth.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/engines/_browsers/_stealth.py)、[scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py)

## 已知问题与社区反馈

- **Issue #100**：在"嵌入式" Turnstile 场景下，`StealthyFetcher` 会无限等待。建议启用前先用 `solve_cloudflare=False` 手动观察页面结构，或在 `StealthySession` 中显式传入超时参数。
- **Issue #159**：社区希望框架暴露"监听浏览器请求并获取响应"的接口，目前隐身会话仍以整页响应为单位返回，复杂过滤需通过中间件自行实现。
- **Issue #142**：与 Agent Skill（OpenClaw）相关，`agent-skill/README.md` 中提供了 `clawhub install scrapling-official` 的安装入口，便于在 Agent 工具中复用本抓取能力。
- **v0.4.9 更新**：发布说明指出"所有浏览器与指纹已更新，升级后请运行 `scrapling install --force`"，否则隐身会话可能因旧指纹被目标站点拒绝。

资料来源：[agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md)、[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)

## See Also

- [解析与自适应选择器](README.md)（Parsing & Adaptive Selectors）
- [Spider 爬虫框架](scrapling/spiders/)（Spider Architecture）
- [CLI 与 MCP 服务器](scrapling/cli/)（CLI & MCP Server）
- [代理轮换](scrapling/spiders/proxy-blocking.md)（Proxy Rotation）

---

<a id='page-parsing'></a>

## 解析器、自适应元素追踪与相似度匹配

### 相关页面

相关主题：[抓取器、隐身模式与会话管理](#page-fetching), [爬虫框架、CLI、MCP 与代理/Agent 扩展](#page-spiders)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)
- [agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md)
- [agent-skill/Scrapling-Skill/examples/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/Scrapling-Skill/examples/README.md)
- [scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py)
- [scrapling/parser.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/parser.py)
</details>

# 解析器、自适应元素追踪与相似度匹配

## 概述

`scrapling.parser` 模块是整个框架的"语义中枢"，既承担 `Selector` 类的 HTML 解析职责，又在解析器层面提供自适应元素追踪与相似度匹配能力。开发者无需启动任何 fetcher，也能直接对 HTML 字符串使用全部 API：

```python
from scrapling.parser import Selector
page = Selector("<html>...</html>")
```

资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)

该模块在设计上刻意贴近 Scrapy/Parsel 与 BeautifulSoup 的语法，降低迁移成本；同时扩展出 `adaptive`、`auto_save`、`find_similar`、`find_by_text` 等原生 Scrapling 特性。模块底层的统一日志通过 `scrapling.core.utils._utils` 中的 `log` 代理输出，便于在爬虫与 Spider 中追踪解析过程。

## Selector 与选择 API

`Selector` 是所有 fetchers 与 Spider 返回 `Response` 的基础类型，提供与 Scrapy/Parsel 一致的 CSS/XPath 接口：

```python
page.css('.quote .text::text').getall()
page.xpath('//div[@class="quote"]/span[@class="text"]/text()').getall()
```

同时支持 BeautifulSoup 风格的 `find_all`、`find_by_text`，并提供链式调用：

```python
quote_text = page.css('.quote')[0].css('.text::text').get()
first_quote = page.css('.quote')[0]
author = first_quote.next_sibling.css('.author::text')
```

模块还提供 `below_elements()` 等结构导航方法，便于在嵌套结构中顺藤摸瓜。所有字符串操作底层使用 `_utils.py` 中的 `__CLEANING_TABLE__` 与 `__CONSECUTIVE_SPACES_REGEX__` 进行空白归一化。

资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)、[scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py)

## 自适应元素追踪

自适应追踪是 Scrapling 的标志性能力。开发者首次抓取时使用 `auto_save=True` 把当前选择器的"指纹"持久化下来；之后即使目标站改版，只要再以 `adaptive=True` 执行同一查询，解析器会依据指纹在 DOM 中重新定位元素：

```python
products = p.css('.product', auto_save=True)              # 首次抓取并保存指纹
products = p.css('.product', adaptive=True)               # 之后即使改版也能找回
```

该机制配合 `StealthyFetcher.adaptive = True` 可在浏览器层面持续复用同一逻辑。其工作流可用下图描述：

```mermaid
flowchart LR
    A[发起 css/xpath 查询] --> B{auto_save=True?}
    B -- 是 --> C[提取并持久化元素指纹]
    B -- 否 --> D[直接返回当前 DOM 匹配]
    C --> E[目标站结构变化]
    E --> F[再次执行 adaptive=True]
    F --> G[按指纹在 DOM 中重新定位]
    G --> H[返回更新后的元素]
```

指纹的存读依赖 `scrapling.core.storage`，使得同一份爬虫代码可在多次运行之间复用定位策略。这一能力正好回应社区中 #82「自动检测分页 URL」一类需求——开发者可以将"下一页"链接先用 `auto_save` 记录，再让 Spider 在后续运行中通过 `adaptive` 自动重新定位。

资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)

## 相似度匹配与文本搜索

除自适应追踪外，`Selector` 还内置基于结构特征的相似度匹配，用于在改版或部分缺失场景下兜底：

```python
similar_elements = first_quote.find_similar()
quotes = page.find_by_text('quote', tag='div')
```

`find_similar` 借助 `_utils.py` 中的归一化文本工具计算元素之间的相似度，在 README 给出的基准中较 AutoScraper 快约 5.2 倍：

| 库 | 耗时 (ms) | 对比 Scrapling |
|---|---:|---:|
| Scrapling | 2.39 | 1.0x |
| AutoScraper | 12.45 | 5.209x |

`find_by_text` 与 `parent` / `next_sibling` / `below_elements` 等关系 API 共同构成了"语义无关"的兜底选择策略。当页面 DOM 被部分重写、选择器失效时，组合使用相似度匹配与文本搜索可显著降低维护成本。

资料来源：[README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)、[scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py)

## 常见使用模式

- **直接解析本地 HTML**：无需任何 fetcher，直接 `Selector(html_str)`。
- **Fetcher 集成**：所有 fetcher（`Fetcher`/`StealthyFetcher`/`DynamicFetcher`）返回的对象均继承 `Selector`，可直接使用上述 API。
- **Spider 内使用**：Spider 的 `parse(response)` 中 `response.css(...)` 与上述示例一致，可结合 `auto_save`/`adaptive` 在多页爬取中复用指纹。
- **Agent 集成**：通过 [agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md) 安装的 Scrapling Skill 已封装该模块用法，可被 OpenClaw / Claude Code 等 Agent 直接调用（回应社区 #142）。

资料来源：[agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md)、[agent-skill/Scrapling-Skill/examples/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/Scrapling-Skill/examples/README.md)

## See Also

- [选择方法文档](https://scrapling.readthedocs.io/en/latest/parsing/selection.html)
- [Fetchers 选择指南](https://scrapling.readthedocs.io/en/latest/fetching/choosing.html)
- [Spider 架构](https://scrapling.readthedocs.io/en/latest/spiders/architecture.html)
- [Agent Skill 安装说明](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md)

---

<a id='page-spiders'></a>

## 爬虫框架、CLI、MCP 与代理/Agent 扩展

### 相关页面

相关主题：[Scrapling 框架概述与系统架构](#page-overview), [解析器、自适应元素追踪与相似度匹配](#page-parsing)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/D4Vinci/Scrapling/blob/main/README.md)
- [agent-skill/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/README.md)
- [agent-skill/Scrapling-Skill/examples/README.md](https://github.com/D4Vinci/Scrapling/blob/main/agent-skill/Scrapling-Skill/examples/README.md)
- [scrapling/core/utils/_utils.py](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/utils/_utils.py)
</details>

# 爬虫框架、CLI、MCP 与代理/Agent 扩展

Scrapling 是一个自适应 Web 抓取框架，除了底层解析器与多类型抓取器（HTTP / Dynamic / Stealthy）之外，还提供了完整的多页面爬虫框架、命令行工具（CLI）、MCP（Model Context Protocol）服务器以及面向 AI Agent 的扩展能力。本页围绕这四个外延子系统展开，重点说明它们在整体架构中的位置、典型用法以及与社区常见诉求的对应关系。

## 1. 爬虫框架（Spider 框架）

Scrapling 的 Spider 框架定位为"类 Scrapy"的并发爬虫 API，但其优势在于可以统一调度多种会话类型。开发者通过继承 `Spider` 子类并实现异步 `parse(response)` 回调即可构建完整抓取流程。资料来源：[README.md:1-50]()

### 1.1 核心组件

- `Spider`：定义 `start_urls`、并发度、下载延迟等参数，并提供 `start()` 启动入口；
- `Request` / `Response`：在爬虫内部流转的对象，后者包装 Scrapling 自有的 `Selector` 解析能力；
- `SessionManager`：通过 `configure_sessions(manager)` 将 `FetcherSession`、`AsyncStealthySession` 等不同抓取器注册到命名会话（例如 `fast` / `stealth`），随后在 `Request` 中按 ID 路由请求；
- 多会话协同：在同一 Spider 内混合使用纯 HTTP 会话与隐身浏览器会话，根据目标站点反爬强度动态切换。资料来源：[README.md:50-120]()

### 1.2 高级特性

- 并发与节流：可配置 `concurrent_requests`、按域节流、下载延迟；
- 暂停与恢复：基于检查点（checkpoint）的爬取持久化，Ctrl+C 优雅退出后重启可恢复断点；
- 流式输出：`async for item in spider.stream()` 实时产出抓取结果，配合 UI / Pipeline 友好；
- 自动反爬检测与重试、robots.txt 合规（`robots_txt_obey`）等开箱即用的工程化能力。资料来源：[README.md:120-180]()

社区反馈指出，许多站点（如招聘、电商列表）需要跨多页采集，期望 Spider 能自动识别分页 URL（参见 Issue #82），目前这一功能仍需开发者自行通过 `response.follow()` 显式 yield 后续请求。

## 2. CLI 命令行工具

Scrapling 提供 `scrapling` 命令，覆盖浏览器安装、一键抓取与提取。CLI 是框架的入口之一，特别适合临时性抓取与脚本集成。

### 2.1 常用子命令

| 子命令 | 用途 | 典型场景 |
| --- | --- | --- |
| `scrapling install [--force]` | 安装/更新浏览器与指纹库 | 升级 Scrapling 后刷新二进制 |
| `scrapling extract get <url> <file>` | 通过 Fetcher 抓取并保存为 `.md` / `.txt` | 快速抓取静态页面 |
| `scrapling extract fetch <url> <file>` | 通过 DynamicFetcher 抓取 | 需要 JS 渲染的页面 |
| `scrapling extract stealthy-fetch <url> <file>` | 通过 StealthyFetcher 抓取 | Cloudflare/Turnstile 站点 |

可通过 `--css-selector`、`--impersonate`、`--solve-cloudflare`、`--no-headless` 等参数调整行为。CLI 在最新版本中新增了 `--version` 标志（参见 v0.4.9 发布说明）。资料来源：[README.md:200-260]()

### 2.2 与 Shell / MCP 的衔接

CLI 同时充当交互式 Web Scraping Shell 的前端，并可被 MCP 服务器调用，使自然语言指令能够映射到具体子命令，降低对 LLM 的指令构造压力。

## 3. MCP 服务器集成

Scrapling 内置 MCP 服务器，允许 LLM、Agent 或 IDE（如 Claude Code）通过标准协议直接调用抓取、解析与提取能力，而无需自行实现 HTTP 调用细节。资料来源：[README.md:30-60]()

MCP 暴露的工具语义与 CLI 子命令基本一致，因此既可作为面向 Agent 的高层 API，也可作为脚本化的服务调用端点。其典型应用：

- 让 Agent 在一次会话中先 `extract get` 拉取主页 HTML，再调用 `css()` / `xpath()` 解析，最后通过 Spider 推进；
- 在受限环境下作为工具网关，结合 `scrapling parser` 的离线解析能力，对已抓取片段进行二次抽取；
- 与 Agent Skill（见下节）配合使用，Agent 在调用前即可获取完整的工具语义描述。

## 4. 代理与 Agent 扩展

Scrapling 在 Spider 中提供按域的代理轮换能力，并可通过 `--proxy` 参数在 CLI / Fetchers 层面临时启用。针对 AI Agent 场景，项目以独立 `agent-skill` 包的形式提供与 AgentSkill 规范兼容的技能包。

### 4.1 代理与反检测

- 多会话代理：在 `FetcherSession`、`StealthySession` 中可注入代理，Spider 的 `SessionManager` 自动按会话维度管理；
- 反指纹：StealthyFetcher 默认开启指纹伪装，并支持 `solve_cloudflare=True` 处理 Turnstile；社区报告（Issue #100）指出在嵌入式 Turnstile 场景下 `StealthyFetcher` 仍可能无限等待，建议结合超时参数使用。资料来源：[README.md:60-110]()

### 4.2 Agent Skill

`agent-skill/` 目录下的技能包遵循 [AgentSkill](https://agentskills.io/specification) 规范，可被 OpenClaw、Claude Code 等 Agent 工具识别。资料来源：[agent-skill/README.md:1-20]()

- 安装方式：通过 [Clawhub](https://clawhub.ai/D4Vinci/scrapling-official) 一键安装（`clawhub install scrapling-official`），或直接下载 ZIP 引入；
- 内容范围：封装了文档站点的几乎全部 Markdown 内容，使 Agent 在回答 Scrapling 相关问题时不必猜测 API；
- 测试覆盖：项目已在 OpenClaw 与 Claude Code 上进行兼容性验证，遇到问题可在 GitHub Issues 反馈（社区 Issue #142 正是关于 OpenClaw 支持的诉求）。资料来源：[agent-skill/README.md:20-40]()

### 4.3 示例集合

`agent-skill/Scrapling-Skill/examples/` 提供四份按抓取强度递进的示例脚本，配合下表的"升级路径"使用，可帮助 Agent 自主选择最合适的抓取策略：

```
get / FetcherSession
  └─ 若需 JS → fetch / DynamicSession
       └─ 若被反爬 → stealthy-fetch / StealthySession
            └─ 若多页 → Spider
```

资料来源：[agent-skill/Scrapling-Skill/examples/README.md:1-50]()

## 5. 内部工具与日志

爬虫框架与 CLI 在运行期间共用一套日志工具。`scrapling.core.utils._utils` 中通过 `setup_logger()` 配合 `lru_cache` 实现单例风格的日志配置，并由 `LoggerProxy` 通过 `ContextVar` 暴露为模块级 `log`，便于在并发爬取场景下被各子系统安全地复用。资料来源：[scrapling/core/utils/_utils.py:1-50]()

## See Also

- 解析与选择器：参见 `Selection methods` 文档
- 抓取器选型：参见 `Fetchers` 文档
- Spider 架构：参见 `Spider Architecture` 文档
- 代理与反爬：参见 `Proxy Rotation` 文档
- CLI 总览：参见 `CLI Overview` 文档
- MCP 服务器：参见 `MCP Server` 文档
- 社区 Issue #82（自动分页）、Issue #100（Turnstile 等待）、Issue #142（OpenClaw 支持）、Issue #159（监听浏览器请求响应）

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：D4Vinci/Scrapling

摘要：发现 12 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug Report : `init_script` + `user_data_dir` causes `ERR_NAME_NOT_RESOLVED` on all navigations。

## 1. 安装坑 · 来源证据：Bug Report : `init_script` + `user_data_dir` causes `ERR_NAME_NOT_RESOLVED` on all navigations

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug Report : `init_script` + `user_data_dir` causes `ERR_NAME_NOT_RESOLVED` on all navigations
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/D4Vinci/Scrapling/issues/294 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：No context persistence for code loaded using init_script

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：No context persistence for code loaded using init_script
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/D4Vinci/Scrapling/issues/350 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：[Feature Request] Add `--version` flag to CLI

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Add `--version` flag to CLI
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/D4Vinci/Scrapling/issues/299 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：linux chrome auto closed?

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：linux chrome auto closed?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/D4Vinci/Scrapling/issues/348 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/D4Vinci/Scrapling | README/documentation is current enough for a first validation pass.

## 6. 运行坑 · 来源证据：[BUG] [Good First Issue] LinkExtractor never filters .tar.gz links

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[BUG] [Good First Issue] LinkExtractor never filters .tar.gz links
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/D4Vinci/Scrapling/issues/349 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/D4Vinci/Scrapling | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/D4Vinci/Scrapling | no_demo; severity=medium

## 9. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/D4Vinci/Scrapling | no_demo; severity=medium

## 10. 安全/权限坑 · 来源证据：[Bug]Session-level proxy silently ignored, leaks real IP

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]Session-level proxy silently ignored, leaks real IP
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/D4Vinci/Scrapling/issues/295 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 11. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/D4Vinci/Scrapling | issue_or_pr_quality=unknown

## 12. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/D4Vinci/Scrapling | release_recency=unknown

<!-- canonical_name: D4Vinci/Scrapling; human_manual_source: deepwiki_human_wiki -->