Scrapling Skill 用于通过 Scrapling 的命令行界面（CLI）从网页中提取 HTML、Markdown 或文本内容。其核心思路是：默认走 CLI 路径，从最小的可用命令开始，验证保存的输出，只有在静态抓取不包含真实页面内容时，才升级到基于浏览器的抓取。同时，不要假设用户的 Scrapling 安装是健康的，应先进行验证。
一、默认工作流程 该技能提供了一份可复制的检查清单，建议在工作过程中保持更新：
- 诊断本地 Scrapling 安装；
- 如有需要，修复 CLI 附加组件或浏览器运行时；
- 选择静态抓取或动态抓取；
- 将输出保存到文件；
- 验证文件大小和提取内容；
- 仅当前面的路径失败时才升级。
二、诊断安装 首先运行内置的诊断脚本： python3 scripts/diagnose_scrapling.py 并将结果作为下一步操作的依据。
三、修复安装 如果 CLI 安装时缺少附加组件，例如 scrapling --help 因缺少 click 而失败，或提示需要安装带附加组件的 Scrapling，则使用 CLI 附加组件重新安装： uv tool uninstall scrapling uv tool install 'scrapling[shell]' 除非用户明确需要更广泛的功能集，否则不要默认使用 scrapling[all]。 如果需要基于浏览器的抓取器，则安装 Playwright 运行时： scrapling install 如果安装过程看起来缓慢或不透明，应先阅读 references/troubleshooting.md，而不是猜测。只有在以下任一情况满足时才能声称成功：scrapling install 报告依赖已安装，或诊断脚本确认 Chromium 和 Chrome Headless Shell 均已存在。
四、选择抓取器 决策规则如下：
- 对于普通页面、文章页面以及大多数微信公众号文章，先使用 extract get；
- 当静态 HTML 不包含真实内容，或页面依赖 JavaScript 渲染时，使用 extract fetch；
- 只有在 fetch 仍因反机器人或挑战行为而失败后，才使用 extract stealthy-fetch，不要将其作为默认选项。
五、运行最小的可用命令 在 shell 命令中始终为 URL 加引号。当 URL 包含 ?、& 或其他特殊字符时，在 zsh 中这是强制要求。
- 整页转 HTML： scrapling extract get 'https://example.com' page.html
- 主要内容转 Markdown： scrapling extract get 'https://example.com' article.md -s 'main'
- 使用浏览器自动化处理 JS 渲染页面： 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'
六、验证输出 每次提取后，应验证文件而不是假设成功： wc -c article.md sed -n '1,40p' article.md 对于 HTML 输出，检查预期的标题、容器或选择器目标是否确实存在： rg -n '<title>|js_content|rich_media_title|main' page.html 如果文件很小、为空或缺少预期容器，则说明提取未成功。应返回第三步，切换抓取器或选择器。
七、处理已知失败模式
- 本地 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 失败，用 python3 scripts/diagnose_scrapling.py 重新检查安装，确认 Chromium 和 Chrome Headless Shell 存在，使用稍长的超时重试，只有在站点行为确实需要时才升级到 stealthy-fetch。
八、命令模式
- 诊断并对 URL 做冒烟测试： python3 scripts/diagnose_scrapling.py --url 'https://example.com'
- 诊断并对微信公众号文章正文做冒烟测试：
python3 scripts/diagnose_scrapling.py
--url 'https://mp.weixin.qq.com/s/ARTICLE_ID?scene=1'
--selector '#js_content'
--no-verify - 诊断并对基于浏览器的抓取做冒烟测试：
python3 scripts/diagnose_scrapling.py
--url 'https://example.com'
--dynamic
九、防护准则
- 不要盲目让用户重装，先验证；
- 当用户明确询问 CLI 时，不要默认使用 Python 库 API；
- 除非静态结果缺少真实内容，否则不要跳到基于浏览器的抓取；
- 不要仅凭退出代码就声称成功，应检查保存的文件；
- 不要将用户特定的绝对路径硬编码到输出或文档中。
十、资源
- 安装与冒烟测试辅助脚本：scripts/diagnose_scrapling.py
- 已验证的失败模式与恢复路径：references/troubleshooting.md