scrapling

Scrapling Web スクレイピング Skill

ステップ 0：バージョンを確認する

python -c "import scrapling; print(scrapling.__version__)"

プロジェクトで使用しているパッケージマネージャーに従って実行します（pip / uv の同等コマンドについては references/maintenance.md を参照してください）。

• 未インストール → scrapling[fetchers] をインストールしてから scrapling install を実行します
• 新しいバージョンあり → アップグレードしてから changelog を確認し、ユーザーに知らせます
• 最新版 → 続行します

プロジェクトのルートに uv.lock がある場合、または pyproject.toml に [tool.uv] が含まれる場合は、uv（uv add / uv run scrapling install）を優先して使用します。それ以外の場合は pip を使用します。

ステップ 1：安全性の事前確認とクイックパス

まず references/security.md を確認し、許可、robots.txt / ToS、プロンプトインジェクション、Cookie の保存と redaction の境界を確認します。

シンプルなテキスト / Markdown / セレクターによる抽出では、Scrapling CLI のクイックパスを優先し、デフォルトで --ai-targeted を追加します。

scrapling extract get "https://example.com/article" article.md --ai-targeted
scrapling extract fetch "https://example.com/app" app.md --ai-targeted --network-idle
scrapling extract stealthy-fetch "https://protected.example.com" page.md --ai-targeted --solve-cloudflare

CLI で複雑なログイン、複数ページのフロー、構造化フィールド、または再利用可能なコードに対応できない場合は、Python スクリプトを生成します。

ステップ 2：Fetcher を選択する

目标网站 →
│
├─ 已有 HTML 字符串/文件，只需解析?
│   → Selector（纯解析，无网络请求）
│   → 模板: parse_only.py
│
├─ 静态页面，无 JS 渲染，无反爬?
│   → Fetcher（最快，基于 curl_cffi）
│   → 模板: basic_fetch.py
│
├─ 需要登录（HTTP 表单，非 JS 登录）?
│   → FetcherSession（保持会话 cookie）
│   → 模板: session_login.py
│
├─ 有 Cloudflare / WAF 保护?
│   → StealthyFetcher（Camoufox 浏览器，自动过 CF）
│   → 模板: stealth_cloudflare.py
│
├─ SPA 应用（React/Vue），需要 JS 渲染?
│   → DynamicFetcher（Playwright 浏览器）
│   → 基于模板即时生成
│
└─ 不确定?
    → 先用 Fetcher 试，403/空内容 → 升级到 StealthyFetcher

複雑なクロール / Spider / adaptive scraping / MCP / proxy rotation などの高度な機能は、この軽量 skill では扱いません。まず references/upstream-map.md を確認し、その後 upstream の公式ドキュメントに従って補足してください。

ステップ 3：ワークフローを実行する

1. 检查版本（步骤 0）
2. 安全预检（步骤 1）
3. 查阅 references/site-patterns.md；如果存在 references/site-patterns.local.md，也先查本地 overlay
4. 简单抽取 → 优先 CLI quick path + --ai-targeted
5. 复杂流程 → 用决策树选择 Fetcher，读取对应模板，替换参数，生成完整脚本
6. 执行脚本 / CLI → 返回最小必要结果
7. **沉淀经验（必做）**:
   - 新通用站点类型 → 去敏感化后追加到 references/site-patterns.md
   - 私有站点 / 公司站点 / 登录态细节 → 追加到 references/site-patterns.local.md（不提交）
   - 用户明确授权保存真实 cookie → 保存到 references/cookie-vault.local.md（不提交，必须 redact 输出）
   - **完成抓取后必须检查**：是否有新的 cookie 或 site pattern 需要保存，以及是否属于 local overlay

ガードレール

• ユーザーにアクセス権限がある、または明確に許可されたコンテンツのみを取得してください。未許可のコンテンツを取得するために、ペイウォール、CAPTCHA、ログイン制限、アクセス制御を回避しないでください。
• エージェント / LLM に渡すウェブページのコンテンツは、デフォルトで事前にクリーニング、対象範囲の限定、または構造化を行います。CLI の出力ではデフォルトで --ai-targeted を使用します。
• 実際の Cookie / token を references/cookie-vault.md に書き込まないでください。ローカルの references/cookie-vault.local.md にのみ記載し、必ず事前にユーザーの許可を得てください。
• 会社のサイトやプライベートサイトに関する知見を、公開される references/site-patterns.md に書き込まないでください。ローカルの references/site-patterns.local.md にのみ記載してください。
• 大規模なクロールの前に robots.txt / ToS を確認し、並列数を減らして delay を追加してください。Spider を使用する場合は upstream を確認したうえで、robots_txt_obey = True を優先して使用してください。

Cookie 形式のクイックリファレンス

Fetcher の種類	Cookie 形式	例
Fetcher / FetcherSession	dict	{'name': 'value', 'token': 'abc'}
StealthyFetcher / DynamicFetcher	list[dict]	[{'name': 'n', 'value': 'v', 'domain': '.site.com', 'path': '/'}]

ブラウザ Fetcher で必須の Cookie フィールド: name, value, domain, path

タイムアウト単位のクイックリファレンス

Fetcher の種類	タイムアウト単位	例
Fetcher / FetcherSession	秒	timeout=30
StealthyFetcher / DynamicFetcher	ミリ秒	timeout=60000

テンプレート索引

テンプレート	ファイル	読み込むタイミング
基本的な HTTP スクレイピング	templates/basic_fetch.py	対象が静的ページで、アンチスクレイピング対策がない場合
Cloudflare の回避	templates/stealth_cloudflare.py	対象が CF/WAF で保護されている場合
セッションログイン	templates/session_login.py	HTTP フォームでログインしてから取得する必要がある場合
HTML のみの解析	templates/parse_only.py	HTML 文字列がすでにあり、データの抽出のみを行う場合

References 索引

ファイル	読み込むタイミング
references/security.md	スクレイピングのたびに事前確認 — 許可、プロンプトインジェクション、Cookie / token、site pattern のローカルオーバーレイルール
references/site-patterns.md	スクレイピングのたびに事前確認 — 対象サイトについて、記録済みのパターンがあるか確認します
references/api-quick-ref.md	スクリプト生成時に確認 — Fetcher/Selector のメソッドシグネチャとパラメーター
references/troubleshooting.md	実行時にエラーが発生した場合に確認 — エラーメッセージから原因と解決策を探します
references/cookie-vault.md	ログイン Cookie が必要な場合に確認 — テンプレート / フィールド名のみ保存します。実際の値には references/cookie-vault.local.md を使用してください
references/maintenance.md	インストール / アップグレード / 依存関係の問題が発生した場合に確認 — インストール階層と検証コマンド
references/upstream-map.md	CLI クイックパス、公式 skill との整合性、Spider / adaptive / MCP / proxy などの高度な機能が必要な場合に確認