企业官网建设流程全解析

Scrapling 官方 Agent 技能包完全指南：一条命令让 AI Agent 不再猜 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

你见过 Agent 写出"看着对、跑不了"的抓取代码吗？它从训练数据里回忆的 API 可能已经是一年前的版本，猜错一个 import 就得重来。Scrapling 用官方内置的 Agent Skill（技能包）解决了这个问题：仓库agent-skill/目录把文档站点的内容封装成 Markdown，Agent 读"说明书"写代码，而不是凭记忆硬猜。从一条命令安装，到--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

安装有三条路径，选一条即可：

# 方式一：Clawhub（OpenClaw 生态的技能分发平台） 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。

CLI：get 起步，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 强调的核心使用模式：

命令选择是一条明确的升级链：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）共享的关键选项：

post与put额外共享-d, --data（表单数据字符串）和-j, --json（JSON 字符串）。--impersonate的逗号随机选取在 scrapling/cli.py 里有对应解析逻辑：含逗号时拆成列表交给底层随机选一个。

fetch的浏览器选项分两组。常规控制项：

反检测四开关（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-targeted

SKILL.md 还给 Agent 定了三条操作纪律：临时文件读完必须清理；优先.md输出保可读性，需要解析结构时才用.html；用-s加 CSS 选择器只取所需部分——把巨型 HTML 塞进上下文是纯浪费 token。

代码：与 CLI 升级链一一对应的四层范式

CLI 到头了，代码范式接棒。examples/ 里四个脚本全部以官方推荐练习站 quotes.toscrape.com 为对象（10 页共 100 条 quotes），形成与 CLI 一致的升级路径：

第一层，HTTP 会话——impersonate='chrome'让连接带上最新 Chrome 的 TLS 指纹，整个with块共用一个会话：

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

第二层，隐身抓取——会话在整个with块内保活浏览器，solve_cloudflare=True直接过挑战；一次性模式则是StealthyFetcher.fetch(...)，请求完即关浏览器：

from scrapling.fetchers import StealthySession with StealthySession(headless=True, solve_cloudflare=True) as session: page = session.fetch("https://nopecha.com/demo/cloudflare") data = page.css("#padded_content a").getall()

第四层（示例里的 04）交给 Spider 框架。最小形态就是 04_spider.py：start_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(headless=True), lazy=True)懒加载隐身会话）；crawldir检查点续爬（Ctrl+C 优雅暂停，下次传同一目录自动恢复）；开发期development_mode = True把响应缓存到磁盘反复回放，但明确警告"别带着它发版"；规则型爬取用CrawlSpider，站点地图驱动用SitemapSpider，另有XMLFeedSpider/CSVFeedSpider/ShopifySpider模板。

当 SKILL.md 的概述不够用时，references/ 才是深度答案：references/fetching/（抓取与会话持久化）、references/parsing/（解析全貌）、references/spiders/（Spider 编写与代理轮换，Scrapy 风格）、references/mcp-server.md（MCP 工具）、references/integrations/scrapy.md（在现有 Scrapy 项目里复用解析 API）、references/migrating_from_beautifulsoup.md（API 对照）。SKILL.md 原文很直接：

This skill includes guides and examples from the documentation in Markdown, so don't check external sources or search online without the user's 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_only=ai_targeted)

即--ai-targeted同时做两件事：浏览器命令自动block_ads=True；落盘时走main_content_only分支。这个分支在 scrapling/core/shell.py 里先把页面收窄到body、剥离script/style等噪音标签，再执行_sanitize_for_ai：

"""Strip 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_only=True执行完全相同的清洗策略。

🧭 决策指南：哪个命令、哪种代码范式

把上面的能力压成几条"条件 → 动作"：

• 遇到静态页面、博客、新闻稿 → 先跑scrapling extract get，输出.md，带--ai-targeted；
• get拿到空内容，或页面是 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! 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