Scraper Builder

PageObject パターンと Playwright、TypeScript を使用した完全に動作する Web スクレイパープロジェクトを生成します。このスキルは、型付きデータ抽出、Docker デプロイメント、サイト分析用オプション agent-browser 統合を備えたサイト固有のスクレイパーを生成します。

このスキルを使用する場合

以下の場合にこのスキルを使用してください：

• データ抽出のためのサイト固有の Web スクレイパーを構築する
• ターゲット Web サイト用の PageObject クラスを生成する
• Docker サポート付きの完全なスクレイパープロジェクトをスキャフォルディングする
• agent-browser を使用してサイトを分析し、セレクターを自動生成する
• 再利用可能なスクレイピングコンポーネント（ページネーション、データテーブル）を作成する

以下の場合はこのスキルを使用しないでください：

• API クライアントを構築する場合（HTTP クライアントライブラリを直接使用してください）
• QA/E2E テストスイートを記述する場合（テスト用パターンで Playwright test runner を使用してください）
• ドメイン全体をマスクロール、スパイダリングする場合（Crawlee または Scrapy を使用してください）
• 認証バイパスまたは CAPTCHA 解決が必要なサイトをスクレイプする場合

コアプリンシパル

1. PageObject カプセル化

ターゲットサイトの各ページは 1 つの PageObject クラスにマップされます。ロケーターはコンストラクタで定義され、スクレイピングロジックはメソッド内に存在します。ページオブジェクトにはアサーション或いはビジネスロジックが含まれることはありません — データを抽出して返すだけです。

2. セレクターの堅牢性

セレクターの優先順位：data-testid > id > セマンティック HTML （role、aria-label） > 構造化 CSS クラス > テキストコンテンツ。位置セレクター （nth-child） と レイアウト依存パスは避けてください。完全な階層については references/playwright-selectors.md を参照してください。

3. コンポジションよりも継承

再利用可能な UI パターン（ページネーション、データテーブル、検索バー）は、ページオブジェクトがプロパティを介して構成するコンポーネントクラスとしてモデル化されます。BasePage のみが継承を使用します — その他はすべて構成します。

4. 型付きデータ抽出

スクレイプされたすべてのデータは、検証のために Zod スキーマを通じてフローします。これは、サイトがマークアップを変更した場合（セレクターの漂流）を、ダウンストリームではなく抽出時にキャッチします。assets/templates/data-schema.ts.md を参照してください。

5. Docker 優先デプロイメント

生成されたプロジェクトには、Microsoft の公式 Playwright イメージを使用した Dockerfile と、出力データとデバッグスクリーンショット用のボリュームマウント付き docker-compose.yml が含まれています。これにより、マシン全体で一貫したブラウザー環境が保証されます。

生成モード

モード 1: Agent-Browser 分析

agent-browser を使用してターゲットサイトをナビゲートし、アクセシビリティツリースナップショットをキャプチャし、セレクターを自動的に検出します。agent に agent-browser CLI へのアクセスがある場合、これが推奨されるモードです。

前提条件： agent-browser がまだインストールされていない場合は、まずスキルとして追加してください：

npx skills add vercel-labs/agent-browser

ワークフロー：

# 1. ターゲットページを開く
agent-browser open https://example.com/products

# 2. 要素参照付きのインタラクティブスナップショットをキャプチャする
agent-browser snapshot -i --json > snapshot.json

# 3. フォーカスされた分析のためにスコープされたセクションをキャプチャする
agent-browser snapshot -i --json -s "main" > main-content.json
agent-browser snapshot -i --json -s "nav" > navigation.json

# 4. 動的動作をテストする（ページネーション、load-more）
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i --json > after-click.json

# 5. 完了時に閉じる
agent-browser close

エージェントがスナップショットで行うこと：

1. 要素参照 （@e1、@e2 など） とそのロールをパースする
2. セマンティック目的（ナビゲーション、データ表示、フォーム、アクション）別に要素をグループ化する
3. データ要素をフィールド（タイトル、価格、画像など）にマップする
4. 検出されたセレクターを使用して PageObject クラスを生成する
5. ページネーションと動的ロードパターンを識別する

完全なワークフローリファレンスについては、references/agent-browser-workflow.md を参照してください。

モード 2: 手動説明

ユーザーはターゲットサイトのページ構造を説明し、エージェントはそれをページオブジェクトにマップします。エージェントは構造化された質問をします：

1. スクレイプするページは？ — URL またはページタイプのリスト
2. 抽出するデータは？ — ページごとのフィールド名と予期されるタイプ
3. データはどのようにページネーションされますか？ — ページ番号付け、load-more、無限スクロール、または単一ページ
4. 既知のセレクターは？ — ユーザーが既に知っている CSS セレクター、data-testid 値、または XPath

その後、エージェントは以下を行います：

• 説明を data/site-archetypes.json のサイトアーキタイプに一致させる
• クラス名と責任を持つページオブジェクトマップを提案する
• ユーザーが計画を確認した後にコードを生成する

モード 3: 完全なプロジェクトスキャフォルド

1 つの操作で scaffolder スクリプトを使用して完全な実行可能なプロジェクトを生成します：

deno run --allow-read --allow-write scripts/scaffold-scraper-project.ts \
  --name "my-scraper" \
  --url "https://example.com" \
  --pages "ProductListing,ProductDetail" \
  --fields "title,price,image_url,description"

これにより、すべてのソースファイル、構成、Docker セットアップ、および実行準備完了のエントリポイント付きプロジェクトが生成されます。完全なオプションについては、「スクリプトリファレンス」セクションを参照してください。

クイックリファレンス

カテゴリ	アプローチ	詳細
フレームワーク	Playwright	playwright パッケージ、@playwright/test ではない
言語	TypeScript	厳密モード、ES2022 ターゲット
パターン	PageObject	1 ページあたり 1 つのクラス、コンポーネントを構成
セレクター	堅牢	data-testid > id > role > CSS クラス > テキスト
Wait 戦略	オートウェイト	Playwright 組み込み、ナビゲーション用に networkidle を追加
検証	Zod	ページオブジェクトの出力タイプごとにスキーマ
出力	JSON + CSV	ストレージユーティリティを介して構成可能
Docker	公式イメージ	mcr.microsoft.com/playwright:v1.48.0-jammy
再試行	指数バックオフ	デフォルト 3 試行、構成可能
スクリーンショット	エラー時	デバッグ用に screenshots/ に保存

生成プロセス

スクレイパーを生成する場合は、以下のシーケンスに従ってください：

ステップ 1: 要件の収集

ユーザーに以下を求めてください：

• ターゲットサイト URL
• 抽出するデータフィールド
• 期待されるページ/アイテム数
• 出力形式の優先設定（JSON、CSV、両方）
• Docker デプロイメントが必要かどうか

ステップ 2: サイトを分析

モード 1 （agent-browser） またはモード 2 （手動説明） を使用して、以下を理解します：

• ページ構造とナビゲーションフロー
• データ要素の場所とセレクター戦略
• ページネーション無限スクロールパターン
• 動的コンテンツロード動作

ステップ 3: ページオブジェクトマップを設計

以下をリストする計画を作成します：

• 各 PageObject クラスと URL パターン
• 必要なコンポーネントクラス（Pagination、DataTable など）
• ページごとのデータスキーマフィールドとタイプ
• ページ間のスクレイパーのナビゲーションフロー

ステップ 4: 計画を提示

コードを生成する前に、ページオブジェクトマップをユーザーに表示してください。クラス名、フィールド名、実行フローを含めてください。確認を待ってください。

ステップ 5: コードを生成

assets/templates/ のテンプレートを基盤として使用してください：

• base-page.ts.md — BasePage 抽象クラス
• page-object.ts.md — サイト固有のページオブジェクト
• component.ts.md — 再利用可能なコンポーネント
• scraper-runner.ts.md — オーケストレーター
• data-schema.ts.md — Zod 検証スキーマ

ステップ 6: 配信

以下を含む完全なプロジェクトを提供してください：

• すべてのソースファイル
• assets/configs/ からの構成ファイル
• その実行方法を説明する README
• Docker セットアップ（明確に除外されていない限り）

コードパターン

BasePage

navigate()、waitForPageLoad()、screenshot()、getText() ヘルパーを提供する抽象クラス。すべてのページオブジェクトがこれを拡張します。

export abstract class BasePage {
  constructor(protected readonly page: Page) {}
  async navigate(url: string): Promise<void> { /* ... */ }
  async screenshot(name: string): Promise<void> { /* ... */ }
}

参照: assets/templates/base-page.ts.md

PageObject

ロケーターが readonly プロパティ、型付きデータを返すスクレイプメソッド、マルチページフロー用のナビゲーションメソッドを含むサイト固有のクラス。

export class ProductListingPage extends BasePage {
  readonly productCards: Locator;
  readonly nextButton: Locator;
  async scrapeProducts(): Promise<Product[]> { /* ... */ }
  async goToNextPage(): Promise<boolean> { /* ... */ }
}

参照: assets/templates/page-object.ts.md

Component

親ロケータスコープを受け取り、抽出メソッドを提供する再利用可能な UI パターン（Pagination、DataTable）。

export class Pagination {
  constructor(private page: Page, private scope: Locator) {}
  async hasNextPage(): Promise<boolean> { /* ... */ }
  async goToNext(): Promise<void> { /* ... */ }
}

参照: assets/templates/component.ts.md

ScraperRunner

ブラウザーを起動し、ページオブジェクトを作成し、ページを反復処理し、データを収集し、スキーマで検証し、出力を書き込むオーケストレーター。

export class SiteScraper {
  async run(): Promise<void> {
    const browser = await chromium.launch();
    const page = await browser.newPage();
    // navigate, scrape, validate, write
  }
}

参照: assets/templates/scraper-runner.ts.md

DataSchema

スクレイプされたレコードを検証する Zod スキーマ。セレクターの漂流と不正な形式のデータを抽出時にキャッチします。

export const ProductSchema = z.object({
  title: z.string().min(1),
  price: z.number().positive(),
});

参照: assets/templates/data-schema.ts.md

アンチパターン

アンチパターン	問題	ソリューション
モノリシックスクレイパー	すべてのスクレイピングロジックが 1 つのファイル内	ページごとに PageObject クラスに分割
Sleep Waiter	setTimeout/固定遅延を使用	Playwright オートウェイトと networkidle を使用
未検証パイプライン	出力に対するスキーマ検証なし	すべてのデータタイプに Zod スキーマを追加
セレクターロッタリー	脆い位置セレクター	堅牢なセレクター階層を使用
サイレント失敗	ログなしでエラーを飲み込む	失敗をログし、デバッグスクリーンショットを保存
スロットルなしのクローラー	リクエスト間に遅延なし	構成可能なリクエスト遅延を追加
ハードコード構成	コード内の URL とセレクター	環境変数と構成ファイルを使用
再試行ロジックなし	リクエストごとに 1 回の試行	指数バックオフを実装

拡張されたカタログの例と修正については、references/anti-patterns.md を参照してください。

スクリプトリファレンス

scaffold-scraper-project.ts

完全なスクレイパープロジェクトを生成します：

deno run --allow-read --allow-write scripts/scaffold-scraper-project.ts [options]

Options:
  --name <name>       プロジェクト名（必須）
  --path <path>       ターゲットディレクトリ（デフォルト: ./）
  --url <url>         ターゲットサイトベース URL
  --pages <pages>     カンマ区切りのページ名（例：ProductListing,ProductDetail）
  --fields <fields>   カンマ区切りのデータフィールド（例：title,price,rating）
  --no-docker         Docker セットアップをスキップ
  --no-validation     Zod 検証セットアップをスキップ
  --json              JSON として出力
  -h, --help          ヘルプを表示

Examples:
  # 製品スクレイパーをスキャフォルド
  deno run --allow-read --allow-write scripts/scaffold-scraper-project.ts \
    --name "shop-scraper" --url "https://shop.example.com" \
    --pages "ProductListing,ProductDetail" --fields "title,price,image_url"

  # Docker なしの最小限のスクレイパー
  deno run --allow-read --allow-write scripts/scaffold-scraper-project.ts \
    --name "blog-scraper" --no-docker

generate-page-object.ts

既存プロジェクト用に単一の PageObject クラスを生成します：

deno run --allow-read --allow-write scripts/generate-page-object.ts [options]

Options:
  --name <name>           クラス名（必須）
  --url <url>             ページ URL（ドキュメントコメント用）
  --fields <fields>       カンマ区切りのデータフィールド
  --selectors <json>      フィールドからセレクターへの JSON マップ
  --with-pagination       ページネーションメソッドを含める
  --output <path>         出力ファイルパス（デフォルト: stdout）
  --json                  JSON として出力
  -h, --help              ヘルプを表示

Examples:
  # 既知のセレクター付きページオブジェクトを生成
  deno run --allow-read --allow-write scripts/generate-page-object.ts \
    --name "ProductListing" --url "https://shop.example.com/products" \
    --fields "title,price,rating" \
    --selectors '{"title":".product-title","price":".product-price","rating":".star-rating"}' \
    --with-pagination --output src/pages/ProductListingPage.ts

  # stdout へのクイック生成
  deno run --allow-read scripts/generate-page-object.ts \
    --name "SearchResults" --fields "title,url,snippet"

テンプレートおよびリファレンス

テンプレート（assets/templates/）

テンプレート	目的
base-page.ts.md	ナビゲーション、スクリーンショット、テキストヘルパー付き抽象 BasePage
page-object.ts.md	ロケーターとスクレイプメソッド付きサイト固有のページオブジェクト
component.ts.md	再利用可能なコンポーネント：Pagination、DataTable
scraper-runner.ts.md	オーケストレーター：ブラウザー起動、反復、収集、出力
data-schema.ts.md	スクレイプされたデータ検証用 Zod スキーマ

構成（assets/configs/）

構成	目的
dockerfile.md	公式 Playwright イメージを使用した多段階 Dockerfile
docker-compose.yml.md	データ/スクリーンショットボリュームマウント付きサービス
tsconfig.json.md	ES2022 ターゲット付きの厳密な TypeScript
package.json.md	playwright、zod、tsx の依存関係
playwright.config.ts.md	スクレイパー用の Playwright 構成

リファレンス（references/）

リファレンス	目的
pageobject-pattern.md	スクレイピング向けに適応した PageObject パターン
playwright-selectors.md	セレクター戦略と堅牢性階層
docker-setup.md	Docker 構成とデプロイメント
agent-browser-workflow.md	Agent-browser 分析ワークフロー
anti-patterns.md	拡張アンチパターンカタログ

例（assets/examples/）

例	目的
ecommerce-scraper.md	完全なマルチページ製品スクレイパーウォークスルー
multi-page-pagination.md	ページネーション処理戦略

データファイル（data/）

ファイル	目的
selector-patterns.json	UI 要素タイプ別に整理された一般的なセレクター
site-archetypes.json	一般的なページとフィールド付きの Web サイト構造アーキタイプ

インタラクション例

ユーザー： 「オンライン書店のスクレイパーが必要です。カタログページから本のタイトル、著者、価格、評価を取得したいです。」

エージェントワークフロー：

1. site-archetypes.json を確認 — ecommerce アーキタイプに一致
2. ページオブジェクトマップを提案：
   • BookListingPage — ページネーション付きカタログ
   • BookDetailPage — 個別の書籍ページ（詳細スクレイピングが必要な場合）
   • Pagination コンポーネント — 共有ページネーションハンドラー
3. フィールドマッピング付きの計画を提示：
   • title → [itemprop="name"] または .book-title
   • author → [itemprop="author"] または .book-author
   • price → [itemprop="price"] または .price
   • rating → .star-rating または [data-rating]
4. 確認後、scaffold スクリプトまたは手動コード生成を使用して生成
5. Docker セットアップと Book タイプの Zod スキーマ付きプロジェクトを配信

統合

このスキルは以下に接続されます：

• typescript-best-practices — 生成されたコードで使用される TypeScript コーディングパターン
• devcontainer — 生成されたプロジェクトの開発コンテナーセットアップ
• agent-browser — サイト分析とセレクター検出（外部ツール）

あなたが行わないこと

このスキルは以下を行いません：

• 認証またはログインウォールをバイパスする
• CAPTCHA またはボット検出を解決する
• JavaScript のみの出力を生成する（常に TypeScript）
• ドメイン全体をスパイダリングするクローラーを生成する
• robots.txt に違反するスクレイパーを作成する
• レート制限された API を処理する（API 作業に HTTP クライアントを使用してください）
• テストスイートを生成する（QA には Playwright テストパターンを使用してください）