Scrapling Agent Skill 完整指南：一条命令给你的 AI Agent 装上免猜手册

【免费下载链接】Scrapling🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling

Scrapling 官方 Agent 技能包是内置在仓库里的 AI Agent 专用手册。装上它之后，Agent 不用猜 API、不用查网络，就能直接写出能跑的抓取代码，还能顺手对付 Cloudflare 这类反爬。

为什么 Agent 总把抓取代码写错

问题出在三个坑上：

1. 训练知识过时。模型的训练数据停在某个时间点，而 Scrapling 的 API 已经迭代——当前 v0.5 里DynamicSession已被移除，合并进StealthySession，Agent 若凭记忆写代码就会引用不存在的类。
2. 看不到项目文档。Agent 写代码时手里没有任何文档，只能靠猜，参数名、类名、调用方式的猜错率很高。
3. 处理不了反爬。遇到 Cloudflare 挑战，它不知道有--solve-cloudflare这个开关，往往重试一两次就放弃。

官方技能包正是冲着这三个坑来的：agent-skill/目录把整个官方文档站点封装成 Markdown 形式，相当于给 Agent 配了一本随身携带的官方手册，并明确告诉它"先读手册，别猜"。

如何安装 Scrapling 技能包：三种入口选一个

安装只需一条命令，按你的工具链三选一：

• Clawhub（OpenClaw / Claude Code 生态）：clawhub install scrapling-official
• skills.sh：npx skills add D4Vinci/Scrapling --skill scrapling-official，CLI 会自动检测你机器上装了哪些 Agent，把技能写进对应目录
• 直接下 ZIP：拿仓库里的 Scrapling-Skill.zip 解压到 Agent 的技能目录即可

前两种可以照抄执行：

clawhub install scrapling-official # 或 npx skills add D4Vinci/Scrapling --skill scrapling-official

如果你的机器没有 Python，可以拉官方 Docker 镜像，但要注意：它只能跑 CLI 命令，没法用 Python 代码调用 Scrapling（镜像定义见 Dockerfile）。

装完技能后做一次性环境初始化，两行搞定：

pip install "scrapling[all]>=0.5" scrapling install --force

第一行装全部依赖，第二行下载 Playwright Chromium 及其系统依赖，只需执行一次。

Scrapling 技能包里装了什么：SKILL.md 与按需参考

整包就是"一个入口文件 + 一批按需加载的参考资料"：

• SKILL.md—— 技能主文件，元数据加用法手册
• examples/ —— 四个可直接运行的示例脚本，全部以官方练习沙箱 quotes.toscrape.com 为对象
• references/—— 深度参考：fetching/、parsing/、spiders/、integrations/四个子目录，外加 MCP 服务器、RAG 构建、从 BeautifulSoup 迁移等专题

SKILL.md 的 frontmatter 里有三个设计值得看：

• description 就是触发条件："被要求抓取/爬取/提取数据、web_fetch失败、目标站有反爬"这些场景直接写进元数据，Agent 靠它决定是否激活技能。描述越具体，误触发率越低。
• requires 做环境预校验：要求系统里有python3且pip/pip3至少存在一个，Agent 执行技能指令前先过这道检查。
• "Notes for AI scanners"：专门写给自动化安全扫描器看——Cloudflare 求解靠浏览器自动化完成，不调第三方求解服务、不需要任何密钥；Proxy 和 CDP 纯属用户可选提供的参数，且会在库内部做校验。

references/与 docs/ 下的官方文档一一对应，目录结构几乎相同。Agent 需要深挖某个主题时才读对应文件，而不是把全部内容塞进上下文；SKILL.md 末尾还特意加了一句约束：技能里已封装了几乎全部已发布文档，未经用户许可不要去搜外部来源。

两种用法：零代码 Scrapling CLI 与四行 Python 代码

先说结论：快速任务走 CLI，要自定义逻辑就写代码，因为并非所有功能都能通过命令行暴露。

从 get 到 fetch 的两级升级

先用get（纯 HTTP，最快）；页面需要 JavaScript 或被拦截时，升级到fetch。注意 v0.5 把旧版fetch/stealthy-fetch两级合并成了一个fetch——它本身就基于隐身浏览器，加--solve-cloudflare即可过 Cloudflare 挑战。输出格式由文件扩展名决定：.md转 Markdown、.html原样、.txt存清洗后的纯文本。

最常用的五个选项：

浏览器命令另有两个高频开关：--wait-selector（等某个元素出现）和--network-idle（等网络空闲）。下面这条命令可以直接复制运行：

scrapling extract fetch "https://quotes.toscrape.com/js/" quotes.md --wait-selector ".quote" --ai-targeted

四个 Python 代码范式

旧版文档里的DynamicSession在 v0.5 已并入StealthySession，纯 Playwright 后端被移除，改名对照见 migrating-to-v0.5.md。HTTP 范式的最小可用示例：

from scrapling.fetchers import FetcherSession with FetcherSession(impersonate="chrome") as s: page = s.get("https://quotes.toscrape.com/") print(page.css(".quote .text::text").getall())

整站爬取交给Spider，内部流转如下：Scheduler 发出请求，引擎分发，Session Manager 维护多类会话，Checkpoint 落盘支持中断续爬。

两条必须遵守的护栏：合规与防提示注入

护栏分两类，都是硬约束。

• 合规：只抓你有权访问的内容；Spider 里设robots_txt_obey = True自动遵守 robots.txt；大规模爬取必须加延迟（download_delay）或开autothrottle_enabled = True，让它按域自动选延迟并在被拦截时退避；未经授权不碰付费墙与认证；绝不抓取个人、敏感数据。
• 安全：--ai-targeted是 Agent 使用 CLI 时的强制参数。原理一句话说清：只把页面主内容落盘，并过滤掉 CSS 隐藏、aria-hidden、HTML 注释、零宽字符这类隐藏元素——这些正是网页给 LLM"悄悄留话"的主要载体，也就是提示注入的常见通道；浏览器命令还会自动拦截广告与追踪请求，顺带省 token。

一条命令装好 Scrapling 技能包，Agent 照 SKILL.md 就能从单页请求一直干到整站爬取，反爬路上还有现成的开关可用。

【免费下载链接】Scrapling🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling