scrape

このファイルは296行あります。すべて読んでください。

以下の SKILL_DIR は、このファイルを含むディレクトリの絶対パスを表します。SKILLS_DIR は、すべてのスキルディレクトリ（そのうちの1つが SKILL_DIR）を含むディレクトリを表します。

ユーザーのプロンプトから、web-poetのページオブジェクトを備えた、動作するScrapyスパイダーまで、ウェブスクレイピングのワークフロー全体をオーケストレーションします。

前提条件

uv が必要です。見つからない場合はインストールしてください。

入力

ユーザーのプロンプトは次のとおりです：$ARGUMENTS。そこから次の情報を抽出する必要があります。

• url：対象ウェブサイトのURL。ホームページの場合も、特定の詳細ページの場合もあります。
• what：抽出する対象（例：「product」「job listing」「recipe」）
• その他の有用な詳細情報：プランに影響するユーザーの指示 （例：抽出するフィールド、ブラウザーレンダリングを使用するかどうかなど）

プロジェクトのコンテキスト

このワークフローは、Scrapyプロジェクトがすでに含まれているリポジトリで実行される場合があります。 通常、繰り返し実行する際は、ドメイン名を付けた別のプロジェクトを作成するのではなく、既存のプロジェクトにスパイダーを追加してください。

候補となるプロジェクトは、カレントディレクトリまたはその直下のディレクトリにある scrapy.cfg を含むディレクトリです。items.py、spiders/、pages/、および単独の pyproject.toml はプロジェクトの判定基準ではありません。.venv、.scrape、__pycache__ などの生成されたディレクトリは無視してください。

同梱のスクリプトはこれらの基準を適用し、各候補を project_dir を含むJSONとして出力します。プロジェクトとスキーマのコンテキストを /scrape-plan に反映できるよう、スキーマの引き継ぎ前に実行してください。

uv run SKILL_DIR/scripts/detect_projects.py

候補がない場合は、ドメイン名に基づく命名で新しいプロジェクトを作成してください。候補が複数ある場合は、どれを使用するか、または新規作成するかを質問してください。推測で決めてはいけません。

候補が1つだけの場合は、ユーザーの表現に従って判断してください。

• 既存プロジェクトを再利用する、または既存プロジェクトに追加する場合 → そのプロジェクトを選択します。
• 既存のスキーマを使用する場合 → そのスキーマを保持するプロジェクトを選択し、次に示すスキーマ一致ルールをそのプロジェクトのアイテムクラスに適用します。
• 新しいプロジェクトの作成を求めずにスパイダーを追加する場合 → 再利用の意図と判断します。「https://example.com 用のスパイダーを追加する」は、すでにある1つのプロジェクトを拡張することを意味します。
• 新しいプロジェクトを明示的に求めている場合 → 新規作成し、再利用はスキップします。
• それ以外の幅広い依頼（「スクレイパーを作成して」「このサイトをスクレイピングして」など）→ 作成を進める前に、プロジェクトを再利用するか、別のプロジェクトを作成するか確認します。スキーマ定義にはこの決定が必要なためです。

プロジェクトを選択した場合、確認は不要です。簡潔な状況報告でプロジェクト名を伝えてください。

プロジェクトを再利用する場合は、次の情報を記録してください。

• project_dir：scrapy.cfg を含むプロジェクトのルートディレクトリ
• project_name：scrapy.cfg のデフォルト設定モジュールに記載されたPythonパッケージ（たとえば、catalog_crawlers.settings は catalog_crawlers パッケージを示します）

プロジェクトを選択したら、その scrapy.cfg を読み取ってパッケージを特定し、プロジェクト構成を調べてください。スキーマを定義する前に、{project_name}/items.py が存在する場合は読み取り、既存のアイテムクラスとフィールドを列挙してください。また、過去のスキーマのコンテキストとして既存の .scrape/*/*/spec.json ファイルも探してください。生成コードの信頼できる情報源として既存の items.py を扱い、.scrape の仕様は有用なコンテキストや例として扱ってください。このコンテキストを活用して、変更のないフィールドをユーザーに再定義させたり、既存のアイテム、ページオブジェクト、フィクスチャー、スパイダーを誤って破損させたりしないようにしてください。

ユーザーが抽出したい内容に妥当に一致する場合に限り、既存のスキーマを選択してください。ナビゲーション専用クラスと、唯一のフィールドにアイテムのリストを持つリストラッパークラスを除外し、要求された単数のデータ型とアイテムクラス名を照合します。ユーザーが既存スキーマの再利用を明示的に求め、妥当な一致候補がクラス1つだけの場合は、そのクラスを使用してください。候補が複数ある場合は、どれを再利用するかユーザーに質問してください。一致するクラスがない場合は、プロジェクトを再利用しつつ、新しいデータ型を通常どおり定義してください。無関係なアイテムクラスのフィールドを新しいスキーマに引き継いではいけません。

ワークフロー

たとえば、計画の承認後など、ユーザーのリクエストが満たされた時点で、どの段階でも停止してください。

各段階の結果は次の段階に引き継がれます。検証済みの計画は、ビルド段階に引き継がれます。通常のエンドツーエンドのリクエストでは、両方の段階と限定的なテストクロールを実行し、最後にレポートを作成してください。承認済みのスキーマ、完成した仕様、準備済みのプロジェクトなどの中間成果物は、ユーザーが明示的に部分的なワークフローや停止地点を指定した場合、必要なプロジェクト／スキーマの決定が未解決の場合、または回復不能なエラーによって先に進めない場合に、有効なワークフローの成果物となります。

サイトが単純に見える場合や、フィールドがユーザーのリクエストに明記されている場合でも、このワークフローを省略しないでください。「スパイダーを追加する」「スクレイパーを作成する」「スクレイパーを作成してテストする」というリクエストは、エンドツーエンドのリクエストです。Stage 1 で /scrape-plan を実行してから、Stage 2 に進んでください。計画やサイト分析の代わりに、親ワークフローで対象サイトの HTML を直接調査しないでください。

Stage 1: 計画と検証

/scrape-plan スキルを使用して、スクレイプを計画し、検証済みの仕様を作成してください。ユーザーのプロンプトから抽出したすべての情報を渡して、このスキルを呼び出してください。既存のプロジェクトを再利用する場合は、プロジェクトのコンテキストを踏まえてスキーマの検出を開始できるよう、既存のアイテムクラス／フィールドと関連する既存の仕様を簡潔にまとめて、プロンプトに含めてください。

この段階では、実際に /scrape-plan へ引き継ぐ必要があります。scrape-plan スキルを明示的に呼び出し、.scrape/{site_name}/ が作成されるまで待ってください。/scrape-plan の実行前に親ワークフローで .scrape/{site_name}/spec.json やデータ型の仕様ファイルを手動で作成して、計画を済ませたことにしないでください。選択したプロジェクトのコンテキストと既存の承認済みスキーマがある場合は、それらをサイト固有の仕様ファイルが作成される前に /scrape-plan へ渡したことが、作業の流れから明確に分かるようにしてください。

既存のアイテムクラスをスキーマとして選択した場合：

• その正確なフィールド名と見た目上の型を、マッチする以前の仕様にある有用な説明や例とともに、リクエストされたフィールドとして /scrape-plan に渡してください。
• これらの既存フィールドが承認済みスキーマであることを伝えてください。Existing approved schema: ProductItem(title: string, price: string, rating: string) のような明示的な引き継ぎフレーズを使い、変更のないフィールドはそのまま再利用し、ユーザーの承認を省略するよう /scrape-plan に指示してください。変更のないフィールドについて、ユーザーに再度列挙や承認を求めないでください。
• /scrape-plan は引き続き新しいウェブサイトを分析して、代表値と抽出根拠を取得します。ただし、無関係なフィールドを黙って追加したり、既存のフィールドを削除したりしてはいけません。既存のフィールドが見つからない場合や、互換性のない型に見える場合は、その不一致を報告し、スキーマを変更する前に確認を求めてください。

一致する既存のアイテムクラスがない場合は、通常の検出と承認のフローを使用してください。

ユーザーがリクエストで指定したフィールドも承認済みスキーマです。承認済みフィールドとして /scrape-plan に渡し、検出されたフィールドのどれを残すか、値をどのように形式化するかを尋ねないでください。

/scrape-plan はスキーマを確認してから、さらにページをダウンロードして分析し、HTML のバリエーションを比較し、値を抽出します。また、任意でブラウザーによるレビューを提示し、最後に確定した計画の承認を求めます。次の段階に必要な詳細をすべて含む、確定済みの計画が返されます。例：

Plan approved. Spec validated and saved to .scrape/books-toscrape/.

Details:
- Data types: product, navigation
- Project dir: ./books_toscrape_com
- Project name: books_toscrape_com
- Create the spider: yes
- Start URLs: https://books.toscrape.com
- Using Zyte API: no

これらの値を解析してください。次の段階で必要になります。

Stage 2: 動作するプロジェクトの構築

これはコーディングの段階です。現在の Scrapy／web-poet の規約、プロジェクトテンプレート、テストループについては /scrapy-extra を参照してください。これはこの作業のナレッジベースであり、仕様を引き継ぐ相手ではありません。これに従い、{spec_path} にある仕様を、動作確認済みのクローラーにしてください。仕様固有の入力のうち、/scrapy-extra が網羅していないもの：

この段階の代わりに、セレクターのみを使う単純な Scrapy スパイダーを実装しないでください。このワークフローの成果物は、取得した仕様ページから生成された web-poet のフィクスチャと、web-poet のページオブジェクトを備えた Scrapy スパイダーです。

• 新規実行：/scrape-plan が報告する {project_dir} に、{project_name} パッケージの新しい Scrapy プロジェクトを作成します。既存プロジェクトの再利用：新しいプロジェクトディレクトリは作成せず、既存の {project_dir} と {project_name} パッケージ内で作業します。

• 仕様には、/scrape-plan が報告するデータ型ごとにフォルダーがあります（例：product、navigation）。各フォルダーには spec.json（スキーマ、html_variant、url）、pages/ 内の保存済みページ、values/ 内の期待値が含まれます。データ型ごとにアイテムクラスと web-poet ページオブジェクトを追加し、その @field メソッドで保存済みページ全体にわたって期待値を再現します。

• 主データ型は、navigation 以外で最初に現れるデータ型です。navigation は常に含まれます。主データ型の末尾が -list の場合（例：product-list）、リクエストされたすべてのフィールドが一覧ページで見つかったことを示します。この場合、そのページオブジェクトは一覧ページからアイテムのリストを抽出し、スパイダーは詳細ページ用のコールバックを使わず、parse() から直接アイテムを yield します。それ以外の場合は、サイトで詳細ページから抽出します（デフォルト）。

• 既存プロジェクトを再利用する場合、ユーザーが変更を承認しない限り、既存のアイテムクラス、ページオブジェクト、フィクスチャ、スパイダーはそのまま維持します。データ型に一致する既存のアイテムクラスがあれば、そのクラスを使います。重複を作成するのではなく、不足しているスキーマフィールドをオプショナルとして追加します（既存の ProductItem があれば、引き続き ProductItem を使います）。新しいターゲットドメインに基づいて名前を決めるのは、新しいスパイダーとモジュールのみです。インポートは既存の {project_name} パッケージ内にとどめます。既存のスパイダーと名前またはファイルが衝突する場合は、置き換えるのではなく、ドメインとデータ型に基づく別の名前を使います。既存プロジェクトのアイテム、ページオブジェクト、フィクスチャ、スパイダーの規約に沿う最小限の追加にとどめます。再利用は、無関係なプロジェクトコードを再構成する許可を意味するものではありません。

• web-poet のフィクスチャは、仕様にすでに保存されているページから構築します。savefixture で再取得しないでください（すべてのページが再ダウンロードされ、ページオブジェクトの作成時に基準とした HTML と異なる可能性がある新しい HTML が記録されるためです）。代わりに、各ページオブジェクトを作成したら、データ型ごとにバンドルされたヘルパーを実行し、ページオブジェクトのインポートパスを渡します（このスキルのディレクトリを基準に SCRIPT を解決します）。

  SCRIPT=SKILLS_DIR/scrape-plan/scripts/make_fixtures.py
  uv run --python 3.14 "$SCRIPT" {spec_path}/{data_type} {project_dir} {PageObjectImportPath}
  

  これにより、保存済み HTML が再利用され、各 output.json が仕様の values/ の値に設定されるため、ネットワークへの再アクセスなしでフィクスチャが通過します。

• navigation ページオブジェクトを使ってアイテムへのリンク、ページネーション、サブカテゴリをたどり、アイテムページオブジェクトを使って各アイテムを抽出するスパイダーを作成します。/scrape-plan が報告する開始 URL を使います。html_variant が rendered のデータ型では、ブラウザーによるレンダリングが必要です。

計画でスパイダーを作成しないよう指示されている場合は、スパイダーを作成せず、ページオブジェクトとそのフィクスチャが用意できた時点で完了します。

成功を報告する前に、上記のヘルパーでフィクスチャが生成され、テストに通ることを確認します（uv run --with pytest python -m pytest fixtures/）。スパイダーを作成しない場合を除き、上限を設定したテストクロールを実行し、取得したアイテムを確認したことも確かめます。既存プロジェクトを再利用する場合は、新しいスパイダーのクロールのみを対象とし、既存のスパイダーは再テストも変更もしません。CLOSESPIDER_ITEMCOUNT または CLOSESPIDER_PAGECOUNT でクロールに上限を設定してください。スパイダーの検証だけを目的に、サイト全体を無制限にクロールしてはいけません。サンドボックス化されたハーネスが許可確認なしで作成できるよう、一時クロールフィードはワークスペース内、たとえば .scrape/.work/{site_name}/ に書き込みます。/tmp、/private/tmp、その他の外部出力先は避けてください。最終報告には、少なくとも1件のスクレイピング済みアイテムをそのまま含め、件数だけでなく実際に抽出されたフィールド値をユーザーに示します。

フィードバックマーカー

以下の各 Stage 3 の最終結果では、報告に戻る前、コマンドを実行している間に、直ちに一度だけフィードバックマーカーを記録します。これは、任意のセッション終了時フィードバックプロンプトに使用するワークフローの最終結果シグナルであり、ユーザーに直接プロンプトを表示するものではありません。ユーザーがワークフローを中止した場合や、認証情報の不足など、クロール前のセットアップで問題が発生した場合は記録しないでください。クールダウンと表示はセッション停止フックが処理します。

修復を試みた後も、範囲を限定したクロールまたは必須のフィクスチャテストが失敗する場合は、停止して、確認した内容を報告し、マーカーを記録します。

SCRAPE_FEEDBACK_STATE_FILE=".scrape/.work/feedback/state.json" \
SCRAPE_FEEDBACK_MARKER_FILE=".scrape/.work/feedback/marker.json" \
SCRAPE_FEEDBACK_EVENT_LOG_FILE=".scrape/.work/feedback/events.jsonl" \
uv run --no-project "SKILL_DIR/scripts/feedback_state.py" mark --context scrape_failed

クロールは成功したものの、修復を試みた後も項目に誤りや不完全な点がある場合は、停止して、確認した内容を報告し、マーカーを記録します。

SCRAPE_FEEDBACK_STATE_FILE=".scrape/.work/feedback/state.json" \
SCRAPE_FEEDBACK_MARKER_FILE=".scrape/.work/feedback/marker.json" \
SCRAPE_FEEDBACK_EVENT_LOG_FILE=".scrape/.work/feedback/events.jsonl" \
uv run --no-project "SKILL_DIR/scripts/feedback_state.py" mark --context scrape_incomplete

フィクスチャテストに合格し、範囲を限定したクロールが実行され、確認した項目が正しい場合に限り、ワークフローが完了したと宣言してください。その場合は、マーカーを記録します。

SCRAPE_FEEDBACK_STATE_FILE=".scrape/.work/feedback/state.json" \
SCRAPE_FEEDBACK_MARKER_FILE=".scrape/.work/feedback/marker.json" \
SCRAPE_FEEDBACK_EVENT_LOG_FILE=".scrape/.work/feedback/events.jsonl" \
uv run --no-project "SKILL_DIR/scripts/feedback_state.py" mark --context scrape_success

報告

Created scraping solution for {domain}:
  Project: {project_dir}/
  Spider: uv run scrapy crawl {spider_name}
  Tests: uv run --with pytest python -m pytest fixtures/

スパイダーの作成をスキップした場合は、Spider の行を省略してください。

ユーザーが希望する場合は、Scrapy Cloud へのデプロイを手伝うことを申し出てください。スケジュール実行や長時間のクロール、結果やログを含むジョブ履歴の保存、ジョブのモニタリング（LLM が利用できる API 付き）などに便利です。無料プランもあります。

デプロイには /zyte を使用します。Scrapy Cloud 上でのスパイダーの実行、およびそのジョブの監視と検証には、Zyte MCP の Scrapy Cloud ツールを使用します。