Scrapling Agent Skill 完整指南：三步接入不猜 API 的官方技能包

【免费下载链接】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

让 AI Agent 写抓取代码，它看不到项目文档，只能靠训练数据里的旧记忆去猜 API。Scrapling Agent Skill（即 Scrapling 官方技能包）就是为这个问题准备的：装好后，Agent 直接读取打包进仓库的官方文档，从单次 HTTP 请求到整站爬取都不用猜、不用联网搜索。整个接入过程就是三步：装技能、装环境、跑第一条命令。

📦 三分钟装好 Scrapling 官方技能包

三条安装途径，看你手头用什么 Agent，选一条即可：

技能包本体只是 Markdown 文件，真正干活的是环境。先建好虚拟环境（venv 都行），再一次性执行：

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

第二条命令会下载 Playwright Chromium 浏览器及其系统依赖，只需做一次。如果scrapling不在$PATH里，记下二进制的实际路径，后面命令都用完整路径。机器上没 Python 也不怕，可以docker pull pyd4vinci/scrapling，但注意 Docker 方式只能跑 CLI 命令，没法写 Python 代码调用库。

装完直接验证一下：

scrapling extract get "https://quotes.toscrape.com/" test.md --ai-targeted

生成一个装着名言的test.md，说明环境就绪。--ai-targeted这个参数先照抄，为什么它重要，第四节专门讲。

🔑 技能如何被激活：SKILL.md 里的三把钥匙

技能包的核心入口是 SKILL.md，Agent 靠它顶部那段 YAML 元数据决定"现在该不该用这个技能"。

• description 是触发条件。官方把激活场景逐条列了：用户要求抓取、爬取或提取数据；内置的web_fetch失败；目标站有反爬保护；要写 Python 抓取代码；要写 spiders。用 Agent 视角看，技能路由就是拿当前任务去和 description 匹配，描述写得越具体，越不容易被无关任务误触发。
• requires 是环境前置校验。元数据声明系统里必须有python3，且pip/pip3至少存在一个，校验不过 Agent 就不该按技能指令执行。
• 版本与身份。当前版本 0.5，文件里明确写着"这是库作者本人发布的官方技能"，并要求 Python 3.10+。

另外还有一段专门写给自动安全扫描器看的说明：Cloudflare 挑战是通过浏览器自动化解决的，不依赖任何第三方求解服务，也就不需要密钥；代理和 CDP 模式完全可选，由用户自己提供；cdp_url、user_data_dir、代理凭据这类参数在库内部会做校验。一句话，这段声明就是告诉扫描器：技能里没有凭据外泄，也没有偷偷调用外部求解器。

🔀 命令实战：升级链和文件扩展名两个决策点

scrapling extract命令组下有get、post、put、delete四个 HTTP 命令和一个浏览器命令fetch。v0.5 把旧版的stealthy-fetch合并进了fetch，反检测开关（过 Cloudflare、拦截 WebRTC、canvas 加噪等）现在都挂在fetch上。

第一个决策：用哪个命令？官方给的策略是一条升级链：拿不准就先get；页面依赖 JavaScript 或拦住了普通 HTTP 请求，升级fetch；页面挂着 Cloudflare 挑战，再加--solve-cloudflare。升级没有性能代价，fetch和纯 HTTP 的差距只在遇到保护站点时才体现。

第二个决策：输出成什么格式？完全由你写的文件扩展名决定：.md是把 HTML 转成 Markdown，最适合阅读和交给 LLM；.html是过滤后的 HTML，需要解析结构时才用；.txt是清洗过的纯文本。

最短的三条命令长这样：

scrapling extract get "https://quotes.toscrape.com/" quotes.md --ai-targeted scrapling extract fetch "https://quotes.toscrape.com/js/" quotes.txt --network-idle --ai-targeted scrapling extract fetch "https://nopecha.com/demo/cloudflare" data.txt --solve-cloudflare --ai-targeted

高频选项只有这些需要记：

技能包还定了几条操作纪律：读临时文件后要清理；优先.md输出省 token；用-s选择器截小范围。

🛡️ --ai-targeted 如何防 Agent 提示注入，以及要守的规矩

先说结论：--ai-targeted是官方写给 Agent 的强制项，网页里最经典的提示注入载体就是人眼看不见的隐藏内容，这个参数负责把它们清掉。

源码层面，scrapling/cli.py 里所有extract命令的统一落盘函数__Request_and_Save在ai_targeted为真时做了两件事：给写入流程传main_content_only，清洗器会剥掉 CSS 隐藏元素、aria-hidden节点、<template>标签、HTML 注释和零宽字符；同时默认置block_ads为真，fetch会自动拦截约 3,500 个已知广告与追踪域名，少跑无关请求也省 token。MCP 路径的安全模型一致，服务端的main_content_only默认开启，执行同一套清洗策略，详见技能包里的references/mcp-server.md。

参数管住了"内容进 Agent 眼睛之前"，规矩管住行为底线，SKILL.md 把它列为恒定约束：

• 只抓你有权访问的内容；
• 遵守 robots.txt 与服务条款，Spider 里设robots_txt_obey = True自动强制；
• 大规模爬取加download_delay，或autothrottle_enabled = True让 Spider 按域自动选延迟、被拦截时自动退避；
• 未经授权不绕过付费墙和认证；
• 绝不抓个人与敏感数据。

🐍 从命令走向代码：三种范式跑完全站

命令覆盖一次性任务，但要并发、检查点续爬、多会话这些完整能力，得写代码。技能包 examples/ 里有四个可运行脚本，全部以官方练习站 quotes.toscrape.com（10 页 100 条名言）为目标：

Spider 框架是其中功能最多的部分：支持并发请求、crawldir检查点（Ctrl+C 优雅暂停、再次启动自动续爬）、development_mode = True的磁盘缓存回放，以及CrawlSpider、SitemapSpider、ShopifySpider等现成模板。

需要更深的细节时，按主题读 references/ 下的分层文档：fetching/讲抓取与会话持久化，parsing/讲解析类与选择器，spiders/八篇覆盖 Spider 编写、代理轮换等，另有mcp-server.md、integrations/scrapy.md（在现有 Scrapy 项目里复用解析 API）、migrating_from_beautifulsoup.md。技能包已封装了几乎全部已发布文档，官方也明确要求：未经用户许可，不要查外部来源或在线搜索。

从 Clawhub 一条命令安装，到--ai-targeted守住内容入口，再到 references 分层供给知识——Scrapling 这个技能包把"文档"做成了 Agent 可直接执行的知识源。使用中遇到问题，走项目 issue 渠道或官方 Discord 社区反馈即可。

【免费下载链接】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