mcpField
S
scrape-codegen-analyze

scrape-codegen-analyze

github.com/zytedataデータ・データベース11172 回インストール2 日前に更新
リポジトリ

scrape-codegen-analyze について

保存済み HTML からスキーマ項目の位置を特定し、別のコード生成エージェント向けに抽出手順を作るスクレイピング分析スキルです。ページメタデータと期待値を確認し、一覧ページの繰り返し要素と詳細ページの項目を区別します。

主な機能

  1. 01保存済みHTMLとメタデータの分析
  2. 02ページ内の各データソースから項目を特定
  3. 03一覧ページの繰り返し要素セレクターを特定
  4. 04抽出期待値の検証
  5. 05項目分析をJSONで保存

活用シーン

  1. 01詳細ページの抽出手順の準備
  2. 02一覧ページの繰り返し要素セレクターの特定
  3. 03期待値とページ内容の照合

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/zytedata/skills --skill scrape-codegen-analyze

インストール後、Claude Code で/scrape-codegen-analyzeを入力して読み込まれたか確認します。

詳細

コード生成システム向けの抽出手順を作成するため、詳細ページを分析します。HTML ページ、スキーマ、期待される値が与えられたら、各フィールドをページからどこで、どのように抽出できるかを特定します。

${CLAUDE_SKILL_DIR}/../scrape/references/python-environments.md を読みます。

分析結果は、HTML にアクセスできない別のコード生成エージェントによって参照されます。そのエージェントが正しい web-poet 抽出コードを作成できるよう、十分に詳しく記述してください。

入力

生の引数文字列は $ARGUMENTS です。空白で区切られた4つの位置引数に分割します。

  1. page_html_path：保存済み HTML ファイルのパス。例：.scrape/spec/pages/detail-1/raw.html
  2. work_path：分析結果を保存する作業ディレクトリ。例：.scrape/.work/spec
  3. spec_path：spec.json ファイルのパス。例：.scrape/spec/spec.json
  4. values_path：このページの values JSON ファイルのパス。例：.scrape/spec/values/detail-1.json

さらに、周囲のプロンプトテキストから取得する情報（引数文字列からは取得しません）：

  • fields：分析対象として指定されたフィールド（任意）。プロンプトに「Only analyze these fields: ...」として示されます。指定されている場合は、スキーマ内の該当フィールドだけを分析し、残りは対象外にします。指定されていない場合は、すべてのフィールドを分析します。

ページディレクトリ（HTML ファイルの親ディレクトリ）には、ソース URL を含む meta.json もあります。

手順

1. 入力の読み込みと HTML の準備

ディレクトリ名から page_id を取得します（例：.../detail-1/raw.html から detail-1）。

同じディレクトリから meta.json を読み込み、ソース URL と page_type を取得します。

meta.json の "page_type": "list" が指定されている場合、または page_id が list- で始まる場合は、is_list_page = true に設定します。これにより、フィールドの分析方法が変わります（手順2を参照）。

{spec_path} からスキーマを読み込みます。schema 内の properties オブジェクトを使用してください。 {values_path} から期待される値を読み込みます。values オブジェクトを使用してください（{} の場合があります）。

HTML をクリーニングし、構造化メタデータを抽出します。スクリプト（JSON-LD／埋め込みデータを含む可能性があります）を保持するため、レベル0のクリーニングを使用します。

mkdir -p {work_path}/codegen-analyze
uv run ${CLAUDE_SKILL_DIR}/../scrape-analyze-page/scripts/clean_html.py PAGE.html -l0 -o {work_path}/codegen-analyze/{page_id}.cleaned.html
uv run ${CLAUDE_SKILL_DIR}/../scrape-analyze-page/scripts/extract_metadata.py PAGE.html -u PAGE_URL -o {work_path}/codegen-analyze/{page_id}.metadata.json

クリーニング済み HTML（元の HTML ではありません）とメタデータ JSON のみを読み込みます。

2. 各フィールドを分析する

リストページの場合（is_list_page = true）： ページには、繰り返し表示される複数の項目要素が含まれています。単一のフィールド値を特定するのではなく、次の項目を特定する必要があります。

  1. コンテナーセレクター — 各項目を囲む繰り返し要素の CSS セレクターです（例：article.product_pod、li.col-xs-6 article、div.item）。 要求されたフィールドをすべて含む、最小の繰り返し要素を探します。 分析結果の container_selector として報告してください（ステップ 4 を参照）。

  2. コンテナー内の各フィールドのセレクター — 各フィールドについて、単一のコンテナー要素内で機能する CSS セレクターを記録します（例：コンテナーが article.product_pod の場合、タイトルはその要素内で h3 a::attr(title) と指定できます）。 ページ上の複数のコンテナー要素で、この相対セレクターが一貫して機能することを確認してください。

  3. 予想される項目数 — 見つかったコンテナー要素の数を記録します。この数は値配列の項目数と一致する必要があります。

リストページの分析では、scrape-codegen-generate が for container in self.css(...): ループを生成できるよう、コンテナーを基準とした抽出方法を説明してください。

詳細ページの場合： スキーマ内の各フィールドについて、詳細に分析します。HTML 内の考えられるすべてのデータソースを検討してください。

  • HTML 要素：タグ、クラス、ID、属性 — CSS セレクターまたは XPath を記録します
  • JSON-LD：<script type="application/ld+json"> ブロック — JSON パスを記録します
  • マイクロデータ：itemscope／itemprop 属性
  • OpenGraph：<meta property="og:..."> タグ
  • その他のスクリプトタグ：<script> タグ内の埋め込み JSON（例：window.__DATA__ = {...}）
  • URL の構成要素：ページの URL から導出できるデータ
  • メタタグ：<meta name="..."> タグ
  • 非表示の入力フィールドまたは data-* 属性

見つかった各ソースについて、次の内容を説明します。

  • データ要素に到達する CSS セレクターまたは XPath
  • 必要な 後処理（テキスト抽出、正規表現、JSON パス、型変換）
  • 信頼性：セレクターが一意で安定しているか、壊れやすいか
  • 関連要素を含む 短い HTML スニペット（長い内容は ... で省略します）

そのうえで、最適な抽出方法を推奨し、その理由を説明してください。

3. 目標値を決定する

各フィールドについて、正しい抽出目標値を決定します。

  • 予想値が指定されている場合は、HTML 内の値と照合します
  • 一致する場合は、その値を使用します
  • 誤りまたは不完全と思われる場合は、不一致を記録し、HTML に基づく修正値を提示します
  • ページにフィールドのデータがない場合は、null に設定します
4. 分析結果を保存する

{work_path}/codegen-analyze/{page_id}.json に保存します。

詳細ページの場合：

{
  "url": "https://example.com/product/widget-x",
  "page_id": "detail-1",
  "fields": {
    "name": {
      "target_value": "Widget X",
      "analysis": "The product name appears in two places:\n\n1. **HTML element** `<h1 class=\"product-title\">Widget X</h1>`\n   - Selector: `h1.product-title::text`\n   - Clean text, no post-processing needed\n   - Reliable: unique h1 on the page\n\n2. **JSON-LD** in `<script type=\"application/ld+json\">`:\n   ```json\n   {\"@type\": \"Product\", \"name\": \"Widget X\", ...}\n   ```\n   - Path: `name` on the Product object\n   - Also reliable\n\nRecommended: CSS selector `h1.product-title::text` — simplest, most direct."
    },
    "price": {
      "target_value": "$29.99",
      "analysis": "..."
    }
  }
}

リストページの場合は、container_selector と item_count を含め、フィールドごとの分析ではコンテナー内の相対セレクターを使用します。

{
  "url": "https://example.com/category/widgets/",
  "page_id": "list-1",
  "is_list_page": true,
  "container_selector": "article.product_pod",
  "item_count": 20,
  "fields": {
    "name": {
      "target_values": ["Widget X", "Widget Y", "..."],
      "analysis": "Container: article.product_pod\nRelative selector: h3 a::attr(title)\nFinds the full product title in the anchor's title attribute.\nVerified across 20 containers on the page."
    },
    "price": {
      "target_values": ["$29.99", "$14.99", "..."],
      "analysis": "Container: article.product_pod\nRelative selector: p.price_color::text\nFinds the price text directly. Verified across 20 containers."
    }
  }
}
5. 概要を返す

詳細ページの場合は、簡潔な概要を返します。

detail-1 (https://...):
  name: "Widget X" — h1.product-title, also in JSON-LD
  price: "$29.99" — span.price::text, JSON-LD offers.price
  description: "A premium widget..." (2340 chars) — div.description
  rating: null — not found in HTML

リストページの場合は、コンテナーセレクターと項目数を含めます。

list-1 (https://...): 20 items, container: article.product_pod
  name: h3 a::attr(title) — "Widget X", "Widget Y", ...
  price: p.price_color::text — "$29.99", "$14.99", ...

コメント

Markdown 対応