scrapling

scrapling - ルーティング優先の適応型 Web スクレイピング

キーワード：scrapling · adaptive scraping · stealthy fetch · scrapling spider

対象サイトの利用規約、robots、レート制限、認可の境界、悪用防止ポリシーを遵守してください。

Scrapling は、目的に合った最小限のスクレイピング方式を選ぶときに最も役立ちます。

• ブラウザーを使う前に、既知の HTML を解析する
• JavaScript をレンダリングする前に、通常の HTTP から始める
• より簡単な方法でうまくいかない場合に限り、ステルス方式に切り替える
• クロール状態の管理や複数ページのオーケストレーションが本当の課題になったときに限り、スパイダーに切り替える

このスキルを使う場面

• 1 ページ、または数ページから情報を抽出する必要があり、パーサーのみ、HTTP フェッチ、ブラウザーレンダリング、ステルス方式のどれを使うか判断する必要がある場合
• Python を先に書くのではなく、scrapling extract、scrapling shell、ラッパースクリプトでプロトタイプを作成したい場合
• 対象の DOM が時間とともに変化するため、セレクターを適応的に復元したい場合
• MCP 経由でエージェントから Scrapling を利用したい場合
• 繰り返しのフェッチをサイトのクロールに移行しようとしており、Scrapling のスパイダーが適切か判断する必要がある場合
• Playwright/Crawlee 形式のオーケストレーション、API の直接インターセプト、マネージド型ブロック解除サービスに話がそれてしまい、適切な代替手段を率直に案内する必要がある場合

手順

ステップ 1：ツールを選ぶ前に、1 つのインテーク情報セットをまとめる

最低限、次の情報を集めます。

• 対象の種類：生の HTML、通常の Web ページ、JavaScript レンダリングされたアプリ、保護されたサイト、または多数のページのクロール
• 必要な出力：CSS/XPath による抽出、Markdown/テキストファイル、構造化レコード、または長時間実行されるクロールの出力
• 運用上の要件：簡易な調査、セッションの繰り返し利用、エージェント/MCP からのアクセス、または中断・再開可能なクロール
• 制約：インストールの予算、ブラウザーの利用可否、認証/プロキシの制限、DOM スクレイピングよりも API/JSON への直接アクセスが適しているかどうか

次のルールに従います。

1. HTML がすでにある場合は、Selector から始める
2. ライブページが必要な場合は、Fetcher から始める
3. コンテンツがクライアント側でレンダリングされる場合は、DynamicFetcher に移行する
4. レンダリングした方法でもブロックされるか、結果が空の場合は、StealthyFetcher に移行する
5. キュー管理、リンクのたどり、再試行、チェックポイントが必要になった場合は、スパイダーに移行する
6. 本当に必要なのがブラウザーの自動化、ページ移動前のリクエストインターセプト、またはマネージド型ブロック解除サービスである場合は、Scrapling で対応できると過大に約束せず、別の方法を案内する

詳細なインテーク情報の例と別の方法の案内については、references/intake-packets-and-route-outs.md を参照してください。

ステップ 2：スキル（プラグイン）と必要なパッケージプロファイルのみをインストールする

このルーティングスキルを jeo-skills プラグインとして登録し、続けて上流の Scrapling パッケージプロファイルをインストールします。

npx skills add https://github.com/akillness/jeo-skills --skill scrapling

ユーザーがシステムへのインストールを明示的に希望しない限り、Python パッケージには仮想環境を使用してください。

bash scripts/install.sh --profile parser
bash scripts/install.sh --profile fetchers
bash scripts/install.sh --profile shell
bash scripts/install.sh --profile ai
bash scripts/install.sh --profile all

scripts/install.sh は、デフォルトで両方の手順をまとめて実行します。Python パッケージのみをインストールするには SKIP_SKILL=1 を、プラグインのみを登録するには SKIP_PACKAGE=1 を使用してください（GLOBAL/AGENTS の設定についてはスクリプトのヘッダーを参照してください）。

インストールの案内：

• parser — ローカル HTML の解析のみ
• fetchers — HTTP とブラウザーを使用するフェッチャー
• shell — 対話型 CLI シェルのワークフロー
• ai — MCP サーバーのワークフロー
• all — ユーザーが全機能を本当に必要とする場合に限る

ブラウザーを使用するワークフローには scrapling install が必要です。パーサーのみのワークフローでは必要ありません。

ステップ 3：目的に合った最も軽量な抽出方法を選ぶ

A. パーサーのみの方法

HTML がすでにある場合、または主にセレクターのロジックが必要な場合に使用します。

from scrapling import Selector

page = Selector(html_doc, url="https://example.com")
items = page.css("article h2::text").getall()

次の用途に適しています。

• ローカルの HTML フィクスチャ
• 保存済みのレスポンス
• セレクターの素早い作成
• ネットワークやブラウザーの懸念がない、低コストの情報抽出

B. HTTP フェッチ方法

通常の HTTP で十分と考えられる場合は、Fetcher または FetcherSession を使用します。

from scrapling.fetchers import Fetcher

page = Fetcher.get("https://example.com", impersonate="chrome")
title = page.css("title::text").get()

次の用途に適しています。

• ドキュメント、ブログ、多くのマーケティングページ、検索結果、シンプルな製品ページ
• セッションを再利用する、低コストで繰り返し実行するリクエスト
• HTTP では不十分だと証拠で確認された場合に限り、レンダリング済み HTML が必要なケース

C. 動的ブラウザーパス

対象が JS でレンダリングされる場合は、DynamicFetcher または DynamicSession を使用します。

from scrapling.fetchers import DynamicFetcher

page = DynamicFetcher.fetch(
    "https://example.com/app",
    network_idle=True,
    wait_selector=".content"
)

次のような場合に使用します。

• ページが SPA／ダッシュボードである
• コンテンツがクライアント側のレンダリング後にのみ表示される
• 簡単な操作や待機の制御だけで十分である

D. ステルスパス

より軽量な方法が保護機能によって失敗した場合に限り、StealthyFetcher または StealthySession を使用します。

from scrapling.fetchers import StealthyFetcher

page = StealthyFetcher.fetch(
    "https://example.com/protected",
    headless=True,
    solve_cloudflare=True
)

重要：

• ボット対策への対応は、保証ではなく、文書化された機能として扱います
• 対象へのアクセスが依然として失敗する場合や、より強力なインフラが必要な場合は、フラグをもう一つ指定すれば必ず解決するかのように装わず、プロキシやマネージド型のブロック解除サービスを正直に案内します

Fetcher／session の詳細は、references/fetchers-and-sessions.md をご覧ください。

ステップ 4：セレクターのずれが問題の場合に限り、適応型スクレイピングを使用する

DOM が変化しても、意味上の対象が同じ場合に、適応型スクレイピングが役立ちます。

from scrapling.fetchers import Fetcher

Fetcher.configure(adaptive=True)
page = Fetcher.get("https://example.com")
saved = page.css(".product", auto_save=True)
relocated = page.css(".product", adaptive=True)

次の点に注意してください。

• adaptive=True はオプトインです
• auto_save=True は、後で再利用できるようにフィンガープリントを保存します
• 手動での save()、retrieve()、relocate() フローも利用できます
• これは壊れやすいセレクターには役立ちますが、認証の失敗やサイト全体の再設計への対処には役立ちません

パーサー／適応型スクレイピングの詳細は、references/parser-and-adaptive.md をご覧ください。

ステップ 5：適切な操作インターフェースを選択する

CLI／シェル

ユーザーが出力ファイルをすぐに取得したい場合や、ターミナルを中心に調査したい場合は CLI を使用します。

bash scripts/run-extract.sh get "https://example.com" article.md --css-selector "article"
bash scripts/run-extract.sh fetch "https://app.example.com" content.md --network-idle
bash scripts/run-extract.sh stealth "https://protected.example.com" content.md --solve-cloudflare

スタンドアロンスクリプトではなく、対話型 REPL をユーザーが求めている場合は、scrapling shell を使用します。

MCP

専用のスクレイパースクリプトではなく、エージェント向けのアクセスが目的の場合は MCP を使用します。

bash scripts/run-mcp.sh
bash scripts/run-mcp.sh --http --host 127.0.0.1 --port 8000

ローカルエージェントとの統合では stdio から始め、ストリーム可能な HTTP がすでに想定されている環境でのみ HTTP を使用します。

CLI／MCP の詳細は、references/cli-and-mcp.md をご覧ください。

ステップ 6：クロール状態の管理が必要な場合に限り、スパイダーに切り替える

次のような要件がある場合は、スパイダーを使用します。

• 複数ページの処理とリンクの追跡
• 再試行とブロックされた応答への対処
• 並行処理とセッションのルーティング
• crawldir による一時停止／再開チェックポイント

個別のページが 1、2 件だけの場合は、Fetcher のほうがシンプルです。

from scrapling.spiders import Spider, Response

class QuotesSpider(Spider):
    name = "quotes"
    start_urls = ["https://quotes.toscrape.com/"]

    async def parse(self, response: Response):
        for quote in response.css(".quote"):
            yield {"text": quote.css(".text::text").get()}

スパイダーの詳細は、references/spiders.md をご覧ください。

ステップ 7：文献／データセットを対象とする場合は、調査データ収集のゲートを実行する

対象が一般的なウェブコンテンツではなく、科学文献、引用メタデータ、 またはデータセットである場合は必ず、ai4s-research/open-science の決定論的でスクリプトに基づくスキルパターンに従って、このステップを実行します。

python3 scripts/research_harvest_gate.py "https://arxiv.org/abs/2401.00001"

このゲートは標準ライブラリのみを使用し、robots.txt のクロール拒否／クロール遅延と、既知の有料記事掲載出版社に関するヒューリスティックを示す、1 つの ```review 形式の JSON ブロックを出力します。スクレイピングの許可があるとは決して断定しません。収集を始める前に、すべての指摘を解決するか、明示的に受け入れてください。パターンの全容と引き継ぎに関するガイダンスは、references/research-harvesting.md をご覧ください。

例

例 1：HTML は手元にあり、セレクターだけが必要な場合

ブラウザーではなく、Selector を使用します。

例 2：通常の HTTP で読み込まれるマーケティングページ

Fetcher または scrapling extract get から始め、コンテンツが欠落していることを示す根拠がある場合に限り、より高度な方法に切り替えます。

例 3：JS が実行されるまで React ダッシュボードが空の場合

DynamicFetcher に切り替え、network_idle または wait_selector を使用します。

例 4：保護された対象からチャレンジページが返される場合

StealthyFetcher を試します。ただし、より強力なプロキシ／ブロック解除インフラが必要になる可能性も明示します。

例 5：エージェントに範囲を限定したウェブ抽出機能が必要な場合

最初から手書きのスクレイパーを強いるのではなく、MCP 経由で Scrapling を公開します。

例 6：タスクが本格的なクロールになった場合

繰り返しの fetch を、チェックポイントとセッション制御を備えたスパイダーに切り替えます。

例 7：対象が論文、データセット、または引用元の場合

まず scripts/research_harvest_gate.py を実行して、検出された内容を解決または承認します。その後、レンダリングされた概要ページをスクレイピングするより、メタデータ API（Crossref/OpenAlex/Semantic Scholar）を優先します。

ベストプラクティス

1. 実用可能な最小のモードから始め、証拠が得られた場合にのみ段階的に拡張します。
2. 真の情報源が直接 API/JSON である場合はそれを優先し、ブラウザー中心のアプリに DOM スクレイピングを無理に適用しないでください。
3. リクエストを繰り返す場合は、ページごとにブラウザーを再起動するのではなく、セッションを再利用します。
4. 適応型スクレイピングはセレクターの変動に対して使い、あらゆる障害への万能な対処策として使わないでください。
5. モデルコンテキストを小さく保つため、CSS セレクターと .md または .txt の出力を優先します。
6. CLI、MCP、スパイダーは、互いに無関係な 3 つの機能ではなく、同じルーティングロジック上に構築されたオペレーター向けのインターフェースとして扱います。
7. Scrapling が最適ではなくなった場合は、Playwright/Crawlee 形式の自動化、外部のブロック解除ツール、または別の抽出サービスを適切に利用します。
8. 科学文献、データセット、または引用元をスクレイピングする前に、研究データ収集ゲートを実行します。ゲートの結果に問題がないことを、許可の証明として決して扱わないでください。

参考資料

• references/intake-packets-and-route-outs.md

• references/fetchers-and-sessions.md

• references/parser-and-adaptive.md

• references/cli-and-mcp.md

• references/spiders.md

• references/research-harvesting.md — 科学文献／データセットの収集に向けた決定論的なゲートのパターン。ai4s-research/open-science をモデルにしています。

• scripts/install.sh — このスキルをプラグイン（npx skills add）としてインストールし、上流の Python パッケージプロファイルもインストールします。

• scripts/research_harvest_gate.py — 研究データ収集向けの、robots.txt とペイウォールのヒューリスティックを用いた標準ライブラリのみのゲートです。

• scripts/run-extract.sh

• scripts/run-mcp.sh

• Scrapling GitHub リポジトリ

• Scrapling ドキュメント