scrapling-skill

Scrapling スキル

概要

デフォルトの方法として、CLI 経由で Scrapling を使用します。まずは動作する最小限のコマンドを実行し、保存された出力を検証してください。静的な取得で実際のページコンテンツを取得できない場合に限り、ブラウザーを使った取得に切り替えます。

ユーザーの 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 追加機能を指定して再インストールします。

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

ユーザーがより幅広い機能セットを明示的に必要としていない限り、デフォルトでscrapling[all]を指定しないでください。

ブラウザーを使った取得が必要な場合

Playwright のランタイムをインストールします。

scrapling install

インストールの進行が遅い、または状況が不明瞭な場合は、推測せずにreferences/troubleshooting.mdを参照してください。 すでにインストール済みというメッセージやキャッシュディレクトリの存在は、インストール状況の手がかりとして扱います。ブラウザーを使った取得の準備が整っているかは、必要な取得を実行し、保存されたコンテンツを確認して検証してください。どちらの手がかりも、互換性のあるバージョンやブラウザーの起動が正常に動作することの証明にはなりません。

ステップ 3：取得方法を選ぶ

次の判断基準を使用します。

• 通常のページ、記事ページ、ほとんどの WeChat 公開記事には、extract getから始めます。
• 静的 HTML に実際のコンテンツが含まれていない場合や、ページの表示に JavaScript のレンダリングが必要な場合は、extract fetchを使用します。
• fetchでもボット対策やチャレンジの動作が原因で失敗する場合に限り、extract stealthy-fetchを使用します。デフォルトでは使用しないでください。

ステップ 4：役立つ最小限のコマンドを実行する

シェルコマンドでは、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

WeChat 公開記事の本文

まず#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

この操作は、失敗がローカルの証明書検証エラーのパターンと一致することを確認してから行ってください。デフォルトで検証を無効にしないでください。

WeChat の記事ページ

mp.weixin.qq.comの場合：

• extract fetchより先にextract getを試します
• 記事本文には-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'

WeChat 記事本文の診断とスモークテスト

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