scrapling-skill

Scrapling 技能

概述

默认通过 Scrapling 的 CLI 使用。先运行最简可用命令，验证保存的输出，只有在静态抓取未包含页面实际内容时，才升级为使用浏览器的抓取方式。

不要假设用户的 Scrapling 安装正常。请先验证。

默认工作流

复制此检查清单，并在工作过程中持续更新：

Scrapling Progress:
- [ ] Step 1: Diagnose the local Scrapling install
- [ ] Step 2: Fix CLI extras or browser runtime if needed
- [ ] Step 3: Choose static or dynamic fetch
- [ ] Step 4: Save output to a file
- [ ] Step 5: Validate file size and extracted content
- [ ] Step 6: Escalate only if the previous path failed

第 1 步：诊断安装

在不更改用户工作目录的情况下，确定已加载的技能目录。 替换占位符一次，然后运行随附的诊断程序：

SCRAPLING_SKILL_DIR='<absolute path to the loaded scrapling-skill directory>'
python3 "$SCRAPLING_SKILL_DIR/scripts/diagnose_scrapling.py"

将结果作为下一步的准确依据。 有关平台默认设置、自定义或未知缓存位置以及冒烟测试输出的保留方式， 请阅读 references/troubleshooting.md。

第 2 步：修复安装

如果安装 CLI 时未包含额外依赖

如果 scrapling --help 因缺少 click 而失败，或提示需要通过额外依赖安装 Scrapling，请使用 CLI extra 重新安装：

uv tool uninstall scrapling
uv tool install 'scrapling[shell]'

除非用户明确需要更广泛的功能集，否则不要默认使用 scrapling[all]。

如果需要使用浏览器的抓取器

安装 Playwright 运行时：

scrapling install

如果安装过程看起来缓慢或不透明，请先阅读 references/troubleshooting.md，再进行推测。 将“已安装”提示或缓存目录存在视为安装线索。通过所需的抓取方式验证浏览器抓取是否就绪，并检查保存的内容；这两种线索都无法证明版本兼容或浏览器能正常启动。

第 3 步：选择抓取器

使用以下判断规则：

• 普通网页、文章页面和大多数微信公众号文章，从 extract get 开始。
• 如果静态 HTML 不包含实际内容，或页面依赖 JavaScript 渲染，则使用 extract fetch。
• 只有在 fetch 仍因反爬或验证挑战而失败后，才使用 extract stealthy-fetch。不要将其作为默认选项。

第 4 步：运行最简实用命令

在 shell 命令中始终给 URL 加引号。当 URL 包含 ?、& 或其他特殊字符时，在 zsh 中必须这样做。

将完整页面保存为 HTML

scrapling extract get 'https://example.com' page.html

将主要内容保存为 Markdown

scrapling extract get 'https://example.com' article.md -s 'main'

使用浏览器自动化抓取 JavaScript 渲染的页面

scrapling extract fetch 'https://example.com' page.html --timeout 20000

提取微信公众号文章正文

优先使用 #js_content。这是在 mp.weixin.qq.com 页面上提取文章正文的默认选择器。

scrapling extract get 'https://mp.weixin.qq.com/s/ARTICLE_ID?scene=1' article.md -s '#js_content'

第 5 步：验证输出

每次提取后，都要检查文件，不能想当然地认为操作成功：

wc -c article.md
sed -n '1,40p' article.md

对于 HTML 输出，请检查预期的标题、容器或选择器目标是否确实存在：

rg -n '<title>|js_content|rich_media_title|main' page.html

如果文件很小、为空，或缺少预期容器，则提取未成功。返回第 3 步，切换抓取器或选择器。

第 6 步：处理已知故障模式

本地 TLS 信任存储问题

如果 extract get 因 curl: (60) SSL certificate problem 失败，请首先将其视为本地信任存储问题，而非 Scrapling 内容抓取失败。

使用以下命令重试：

--no-verify

仅在确认故障符合本地证书验证错误特征后才这样做。默认情况下，不要静默禁用验证。

微信文章页面

对于 mp.weixin.qq.com：

• 先尝试 extract get，再尝试 extract fetch
• 使用 -s '#js_content' 提取文章正文
• 立即验证保存的 Markdown 或 HTML

浏览器抓取失败

如果 extract fetch 失败：

1. 使用 python3 "$SCRAPLING_SKILL_DIR/scripts/diagnose_scrapling.py" 重新检查安装
2. 检查所选浏览器缓存；如果位置为 unknown，请参阅 references/troubleshooting.md 并确定其位置
3. 使用稍长的超时时间重试
4. 只有在网站行为确有必要时，才升级为 stealthy-fetch

命令示例

诊断并对 URL 进行冒烟测试

python3 "$SCRAPLING_SKILL_DIR/scripts/diagnose_scrapling.py" --url 'https://example.com'

诊断并对微信公众号文章正文进行冒烟测试

python3 "$SCRAPLING_SKILL_DIR/scripts/diagnose_scrapling.py" \
  --url 'https://mp.weixin.qq.com/s/ARTICLE_ID?scene=1' \
  --selector '#js_content' \
  --no-verify

诊断并对浏览器抓取进行冒烟测试

python3 "$SCRAPLING_SKILL_DIR/scripts/diagnose_scrapling.py" \
  --url 'https://example.com' \
  --dynamic

防护规则

• 不要让用户不加验证地重新安装。先进行检查。
• 当用户明确询问 CLI 时，不要默认介绍 Python 库 API。
• 除非静态结果缺少实际内容，否则不要直接改用浏览器抓取。
• 不要仅凭退出代码就断言成功。检查保存的文件。
• 不要在输出或文档中硬编码用户专属的绝对路径。

资源

• 安装和冒烟测试辅助脚本：scripts/diagnose_scrapling.py
• 已验证的故障模式和恢复路径：references/troubleshooting.md