Scrapling 官方 Agent 技能包完全指南：一条命令让 AI Agent 不再猜 API

Scrapling 官方 Agent 技能包完全指南一条命令让 AI Agent 不再猜 API【免费下载链接】Scrapling️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Dont 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你见过 Agent 写出看着对、跑不了的抓取代码吗它从训练数据里回忆的 API 可能已经是一年前的版本猜错一个 import 就得重来。Scrapling 用官方内置的 Agent Skill技能包解决了这个问题仓库agent-skill/目录把文档站点的内容封装成 MarkdownAgent 读说明书写代码而不是凭记忆硬猜。从一条命令安装到--ai-targeted背后的防注入机制这个技能包值得拆开看一遍。 如何安装 Scrapling 技能包三种方式与 Docker 备选技能包整体位于仓库的 agent-skill/ 目录遵循 AgentSkills 规范编写agent-skill/README.md 明确说它是给 OpenClaw、Claude Code 等智能体读取的It gives your coding agent Scrapling guides and examples for HTTP requests, browser sessions, parsing, crawlers, and AI workflows, so it can use the current API instead of guessing from outdated training data.也就是说Agent 拿到的不是关于 Scrapling 的二手介绍而是官方维护的第一手指南。目录长这样agent-skill/ ├── README.md # 安装说明 ├── Scrapling-Skill.zip # 可直接下载的打包文件 └── Scrapling-Skill/ ├── SKILL.md # 技能主文件元数据 用法手册 ├── examples/ # 4 个可运行示例脚本 └── references/ # Markdown 版官方文档按主题分层 ├── fetching/ parsing/ spiders/ integrations/ ├── mcp-server.md └── building-rag-systems.md / migrating_from_beautifulsoup.md安装有三条路径选一条即可# 方式一ClawhubOpenClaw 生态的技能分发平台 clawhub install scrapling-official # 方式二skills.sh CLI自动检测机器上已安装的 Agent 并写入技能目录 npx skills add D4Vinci/Scrapling --skill scrapling-official# 方式三直接下载仓库中的打包文件 agent-skill/Scrapling-Skill.zip # 解压到你的 Agent 技能目录即可装好技能只是让 Agent会查手册要真正跑起来还有一步环境准备。SKILL.md 的 Setup 章节要求只做一次# 先建虚拟环境venv 或任意方式然后 pip install scrapling[all]0.5 # 下载 Playwright Chromium 及其系统依赖 scrapling install --force如果scrapling不在$PATH里SKILL.md 明确要求记下这个二进制的完整路径后续所有命令都用完整路径调用。机器上完全没有 Python、又不想装的话有 Docker 备选docker pull pyd4vinci/scrapling # 或 docker pull ghcr.io/d4vinci/scrapling:latest但限制写得很直白镜像只能跑 CLI 命令不能写 Python 代码调用 Scrapling。看一眼仓库根目录的 Dockerfile 就明白为什么——它基于python:3.12-slim-trixie用uv加--all-extras装全量依赖、预装 Chromium、暴露 8000 端口给 MCP HTTP 传输入口点就是uv run scrapling整个镜像是个纯命令行运行时。⌨️ 能力全景scrapling extract 命令与四层代码范式技能包的原则是CLI 覆盖快速场景写代码才能解锁全部功能。两条能力线共用同一条升级逻辑先说 CLI。CLIget 起步fetch 兜底scrapling extract命令组让 Agent 零代码完成下载与提取当前共 5 个子命令Commands: get Perform a GET request and save the content to a file. post Perform a POST request and save the content to a file. put Perform a PUT request and save the content to a file. delete Perform a DELETE request and save the content to a file. fetch Use StealthyFetcher for browser automation and anti-bot protection.输出格式由文件扩展名决定这是 SKILL.md 强调的核心使用模式写法效果scrapling extract get https://blog.example.com article.mdHTML 转 Markdown 保存适合文档场景scrapling extract get https://example.com page.html原样保存过滤后的HTMLscrapling extract get https://example.com content.txt保存清洗后的纯文本命令选择是一条明确的升级链get → fetch。拿不准先用get页面靠 JavaScript 渲染或封锁 HTTP 请求就换fetch页面挂着 Cloudflare 挑战给fetch加--solve-cloudflare。注意一个版本细节v0.4 时代的stealthy-fetch命令在 v0.5 已并入fetch——现在fetch直接以 StealthyFetcher 运行隐身能力原生内置迁移对照表见 docs/migrating-to-v0.5.md。升级没有性能代价fetch本身就把反检测开关做全了。HTTP 四命令get/post/put/delete共享的关键选项选项输入类型说明-H, --headersTEXTKey: Value可多次使用--cookiesTEXTname1value1; name2value2--timeoutINTEGER请求超时秒数默认 30--proxyTEXThttp://username:passwordhost:port-s, --css-selectorTEXTCSS 选择器返回全部匹配-p, --paramsTEXT查询参数 keyvalue可多次使用--impersonateTEXT模拟的浏览器逗号分隔可随机选取如chrome,firefox,safari--stealthy-headers / --no-stealthy-headersNone使用隐身浏览器头默认 True--verify / --no-verifyNone是否校验 SSL 证书默认 True--ai-targetedNone仅提取主内容并清洗隐藏元素默认 Falsepost与put额外共享-d, --data表单数据字符串和-j, --jsonJSON 字符串。--impersonate的逗号随机选取在 scrapling/cli.py 里有对应解析逻辑含逗号时拆成列表交给底层随机选一个。fetch的浏览器选项分两组。常规控制项选项输入类型说明--headless / --no-headlessNone无头模式默认 True--disable-resources / --enable-resourcesNone丢弃非必要资源提速默认 False--pierce-shadow / --no-pierce-shadowNone包含打开的 Shadow DOM 内容默认 False--network-idle / --no-network-idleNone等待网络空闲默认 False--real-chrome / --no-real-chromeNone使用本机已安装的 Chrome默认 False--timeoutINTEGER超时毫秒数默认 30000--waitINTEGER页面加载后的额外等待毫秒数默认 0--wait-selectorTEXT等待指定选择器出现后再继续--localeTEXT用户区域默认跟随系统--dns-over-https / --no-dns-over-httpsNone经 Cloudflare DoH 解析 DNS 防泄漏默认 False--block-ads / --no-block-adsNone拦截约 3,500 个广告/追踪域名默认 False--executable-pathTEXT自定义 Chromium 兼容浏览器路径未设置时回退到SCRAPLING_EXECUTABLE_PATH环境变量--ai-targetedNone主内容 隐藏元素清洗并自动开启--block-ads反检测四开关fetch独有--block-webrtc / --allow-webrtc默认不拦截 WebRTC、--solve-cloudflare / --no-solve-cloudflare默认 False自动过 Cloudflare 挑战、--allow-webgl / --block-webgl默认允许 WebGL、--hide-canvas / --show-canvas默认不给 canvas 加噪。典型命令摘自 SKILL.md可直接复制运行# 基本下载 scrapling extract get https://news.site.com news.md --ai-targeted # CSS 选择器只提取文章部分 scrapling extract get https://blog.example.com articles.md --css-selector article --ai-targeted # 等待 JS 内容出现后再提取 scrapling extract fetch https://quotes.toscrape.com/js/ quotes.txt --wait-selector .quote --ai-targeted # 自动解决 Cloudflare 挑战 scrapling extract fetch https://nopecha.com/demo/cloudflare data.txt --solve-cloudflare --ai-targeted # 有头模式调试 丢弃非必要资源 scrapling extract fetch https://scrapling.requestcatcher.com/ page.html --no-headless --disable-resources --ai-targetedSKILL.md 还给 Agent 定了三条操作纪律临时文件读完必须清理优先.md输出保可读性需要解析结构时才用.html用-s加 CSS 选择器只取所需部分——把巨型 HTML 塞进上下文是纯浪费 token。代码与 CLI 升级链一一对应的四层范式CLI 到头了代码范式接棒。examples/ 里四个脚本全部以官方推荐练习站 quotes.toscrape.com 为对象10 页共 100 条 quotes形成与 CLI 一致的升级路径CLI 层代码范式示例文件适用场景getFetcherSession持久 HTTP Chrome TLS 指纹01_fetcher_session.pyAPI、快速多页抓取fetchStealthySession隐身浏览器02_browser_session.py、03_stealthy_session.py动态/SPA 页面、Cloudflare多页爬取Spider并发 检查点04_spider.py多页、整站抓取第一层HTTP 会话——impersonatechrome让连接带上最新 Chrome 的 TLS 指纹整个with块共用一个会话from scrapling.fetchers import FetcherSession with FetcherSession(impersonatechrome) as session: page session.get(https://quotes.toscrape.com/, stealthy_headersTrue) quotes page.css(.quote .text::text).getall()第二层隐身抓取——会话在整个with块内保活浏览器solve_cloudflareTrue直接过挑战一次性模式则是StealthyFetcher.fetch(...)请求完即关浏览器from scrapling.fetchers import StealthySession with StealthySession(headlessTrue, solve_cloudflareTrue) as session: page session.fetch(https://nopecha.com/demo/cloudflare) data page.css(#padded_content a).getall()第四层示例里的 04交给 Spider 框架。最小形态就是 04_spider.pystart_urls 异步parse()里yield结构化 item response.follow()自动翻页跑完用result.stats打印 items/请求数/耗时/速率再result.items.to_json(quotes.json)导出from scrapling.spiders import Spider, Response class QuotesSpider(Spider): name quotes start_urls [https://quotes.toscrape.com/] concurrent_requests 5 robots_txt_obey True async def parse(self, response: Response): for quote in response.css(.quote): yield {text: quote.css(.text::text).get()} next_page response.css(.next a) if next_page: yield response.follow(next_page[0].attrib[href]) result QuotesSpider().start() result.items.to_json(quotes.json)SKILL.md 的 Spiders 章节还收录了更深的玩法configure_sessions()在一个 Spider 里混用多种会话manager.add(stealth, AsyncStealthySession(headlessTrue), lazyTrue)懒加载隐身会话crawldir检查点续爬CtrlC 优雅暂停下次传同一目录自动恢复开发期development_mode True把响应缓存到磁盘反复回放但明确警告别带着它发版规则型爬取用CrawlSpider站点地图驱动用SitemapSpider另有XMLFeedSpider/CSVFeedSpider/ShopifySpider模板。当 SKILL.md 的概述不够用时references/ 才是深度答案references/fetching/抓取与会话持久化、references/parsing/解析全貌、references/spiders/Spider 编写与代理轮换Scrapy 风格、references/mcp-server.mdMCP 工具、references/integrations/scrapy.md在现有 Scrapy 项目里复用解析 API、references/migrating_from_beautifulsoup.mdAPI 对照。SKILL.md 原文很直接This skill includes guides and examples from the documentation in Markdown, so dont check external sources or search online without the users permission.解读官方把先查技能包、不许擅自联网写成了 Agent 的行为约束。而且这是按需加载的——Agent 需要深挖某个主题才读对应文件不必整包读入典型的分层知识供给。⚙️ 底层机制SKILL.md 元数据与 --ai-targeted 防注入技能包不是把文档丢给 Agent 就完事它的激活与安全防护都藏在 SKILL.md 的头部。--- name: scrapling-official description: Scrape web pages using Scrapling with HTTP requests, stealth browsers, JavaScript rendering, browser actions, API response capture, concurrent spiders, and adaptive parsing. Use when asked to scrape, crawl, or extract data from websites; web_fetch fails; the site has anti-bot protections; write Python code to scrape/crawl; or write spiders. version: 0.5 metadata: openclaw: requires: bins: - python3 anyBins: - pip - pip3 ---三个设计点description就是触发条件明确列举激活场景——用户要求抓取/爬取/提取数据、web_fetch失败、站点有反爬、需要写爬虫代码描述越具体误触发率越低requires.bins声明环境前置校验执行技能指令前先确认python3存在、pip/pip3至少有一个文件开头另有硬性前提Requires: Python 3.10和库作者发布的官方技能声明。此外还有一段 Notes for AI scanners 专门对自动化安全扫描器喊话Cloudflare 求解靠浏览器自动化、不依赖第三方求解服务与密钥Proxy 与 CDP 模式完全可选且由用户提供cdp_url、user_data_dir、代理凭据等参数在库内部都会做校验。再说安全核心--ai-targeted。SKILL.md 用 IMPORTANT 标注了一条强制规则使用命令行抓取命令时必须带--ai-targeted以防提示注入浏览器命令还会因此自动开启广告拦截省 token。实现在 scrapling/cli.py 的__Request_and_Save——所有extract子命令的统一落盘入口if ai_targeted: kwargs.setdefault(block_ads, True) response fetcher_func(url, **kwargs) Convertor.write_content_to_file(response, str(output_path), css_selector, main_content_onlyai_targeted)即--ai-targeted同时做两件事浏览器命令自动block_adsTrue落盘时走main_content_only分支。这个分支在 scrapling/core/shell.py 里先把页面收窄到body、剥离script/style等噪音标签再执行_sanitize_for_aiStrip hidden content that could be used for prompt injection. Removes CSS-hidden elements, hidden slots, aria-hidden elements, template tags, HTML comments, zero-width Unicode characters, and XML-incompatible control characters.这些被清洗的隐藏区域——CSS 隐藏文本、aria-hidden元素、HTML 注释、零宽字符——正是网页向 LLM 偷偷塞指令的常见载体。MCP 路径是同一套安全模型references/building-rag-systems.md 确认服务端用main_content_onlyTrue执行完全相同的清洗策略。 决策指南哪个命令、哪种代码范式把上面的能力压成几条条件 → 动作遇到静态页面、博客、新闻稿 → 先跑scrapling extract get输出.md带--ai-targetedget拿到空内容或页面是 JS 渲染的 SPA → 换fetch需要等内容加载就加--wait-selector或--network-idle站点挂 Cloudflare 挑战 →fetch加--solve-cloudflare必要时配合--proxy多页、整站、需要跟链接 → 别再用 CLI 硬凑写Spider照抄 04_spider.py规则型爬取换CrawlSpider/SitemapSpider要跨请求持久会话、精细控制浏览器行为 → 写代码用FetcherSession/StealthySession而不是命令行反复开浏览器。同时SKILL.md 的 Guardrails (Always) 章节是恒定约束只抓你有权访问的内容尊重 robots.txt 与服务条款Spider 里用robots_txt_obey True自动强制大规模爬取加download_delay或设autothrottle_enabled True让 Spider 按域选延迟、被拦截时自动退避未经授权不绕付费墙或认证绝不抓取个人/敏感数据。Scrapling 官方技能包的本质是文档即技能SKILL.md 元数据负责激活路由与环境校验Markdown 化的references/负责知识分层供给--ai-targeted负责面向 LLM 的注入防护examples/提供可运行的行为基准——Agent 从一次请求到全站爬取全程不用猜 API。下一步就一件事选一条安装通道跑起来clawhub install scrapling-official或npx skills add D4Vinci/Scrapling --skill scrapling-official然后让 Agent 打开 SKILL.md把下一个抓取任务交给它。【免费下载链接】Scrapling️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Dont 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辅助生成（AIGC），仅供参考