extract

このスキルを使う場面

ユーザーがウェブサイトからデータを取得したいときに起動します:

• 「このページのすべての商品価格を抽出して」
• 「...の検索結果表をスクレイプして」
• "arXiv検索結果から著者と論文タイトルのリストを取得して"
• 「このページのすべての求人情報を集めて」
• 「このダッシュボードテーブルからデータを取って」
• 「...のレビュースコアを収集して」
• 「...のすべてのリンク/画像/カードをダウンロードして」

成果物は常に2つの成果物です:

1. 実行可能な Playwright スクリプト — Actionbook なしで実行時に抽出を再現できるスタンドアロン .cjs ファイル
2. 抽出されたデータ — JSON（デフォルト）、CSV、またはユーザー指定形式でディスクに書き込まれたもの

判定戦略

Actionbook を条件付きアクセラレータとして使用し、必須ではありません。目標は最短経路で信頼できるセレクターを得ることです。

ユーザーリクエスト
  │
  ├─► actionbook search "<site> <intent>"
  │     ├─ 結果のヘルススコア ≥ 70%  ──► actionbook get "<ID>" ──► セレクターを使用
  │     └─ 結果なし / スコアが低い  ──► フォールバック
  │
  └─► フォールバック: actionbook browser open <url>
        ├─ actionbook browser snapshot   (アクセシビリティツリー → セレクター検出)
        ├─ actionbook browser screenshot (ビジュアル確認)
        └─ DOM インスペクション経由のセレクター手動発見

セレクターソースの優先順位:

優先度	ソース	時期
1	actionbook get	サイトがインデックスされており、ヘルススコア ≥ 70%
2	actionbook browser snapshot	インデックスされていないか、セレクターが古い
3	スクリーンショット + スナップショット経由の DOM インスペクション	複雑な SPA / 動的コンテンツ

絶対ルール: search + get が必要なフィールドに対して既に使用可能なセレクターを提供している場合、get セレクターから開始し、デフォルトでは完全なフォールバック（snapshot/screenshot）にジャンプしないこと。例外: ハイドレーション/仮想化/ページネーションをプローブするための軽量メカニズムは、ランタイム動作がスクリプトの正確性に影響する可能性がある場合に許可されます。プローブ/サンプル検証がセレクターギャップまたは不安定性を示す場合のみ、snapshot/screenshot にエスカレートしてください。

メカニズム対応スクリプト戦略

ウェブサイトは素朴なスクレイピングを破壊するパターンを使用しています。生成された Playwright スクリプトはこれらを考慮に入れる必要があります:

ストリーミング / SSR / RSC ハイドレーション

ページはシェルを最初にレンダリングし、その後ストリーミングまたはハイドレーションでコンテンツを取得します。

// ハイドレーション完了を待つ — 単なる DOMContentLoaded ではなく
await page.waitForSelector('[data-item]', { state: 'attached' });
await page.waitForFunction(() => {
  const items = document.querySelectorAll('[data-item]');
  return items.length > 0 && !document.querySelector('[data-pending]');
});

検出のヒント: data-reactroot を持つ React ルート、Next.js の __NEXT_DATA__、JS 実行後に埋まる空のコンテナ。actionbook browser text "<selector>" が空を返すがスクリーンショットにコンテンツが表示されている場合、ハイドレーションが完了していません。

仮想化されたリスト / 仮想 DOM

DOM に存在するのは表示されている行のみです。スクロールすると新しい行がレンダリングされ、古い行が破壊されます。

// 仮想化リスト用スクロール＆収集ループ（スクロールコンテナ対応）
const allItems = [];
const maxScrolls = 50;
let scrolls = 0;

const container = await page.$('<scroll-container-selector>');
if (!container) throw new Error('Scroll container not found');

let previousTop = await container.evaluate(el => el.scrollTop);
while (scrolls < maxScrolls) {
  const items = await page.$$eval('[data-row]', rows =>
    rows.map(r => ({ text: r.textContent.trim() }))
  );
  for (const item of items) {
    if (!allItems.find(i => i.text === item.text)) allItems.push(item);
  }

  await container.evaluate(el => el.scrollBy(0, 600));
  await page.waitForTimeout(300);

  const currentTop = await container.evaluate(el => el.scrollTop);
  if (currentTop === previousTop) break;

  previousTop = currentTop;
  scrolls += 1;
}

検出のヒント: コンテナは overflow: auto/scroll で固定高さを持ち、DOM の行数が状態の総数より大幅に少なく、行は transform: translateY(...) または position: absolute; top: ...px を持ちます。

無限スクロール / 遅延読み込み

ユーザーが下部の近くをスクロールすると、新しいコンテンツが追加されます。

// 新しいコンテンツが読み込まれなくなるまで下部にスクロール（無成長許容度あり）
let itemCount = 0;
let noGrowthStreak = 0;
const maxScrolls = 80;
let scrolls = 0;

while (scrolls < maxScrolls && noGrowthStreak < 3) {
  await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
  await page.waitForTimeout(1200);

  const newCount = await page.$$eval('.item', els => els.length);
  if (newCount > itemCount) {
    itemCount = newCount;
    noGrowthStreak = 0;
  } else {
    noGrowthStreak += 1;
  }

  scrolls += 1;
}

検出のヒント: ページ JS の Intersection Observer、「さらに読み込む」ボタン、下部のセンチネル要素、スクロール時に発火するネットワークリクエスト。

ページネーション

「次へ」ボタンまたは番号付きページの背後にある複数ページの結果。

// クリックスルーページネーション（ナビゲーション対応、SPA 対応）
const allData = [];
const maxPages = 50;
let pageIndex = 0;
while (pageIndex < maxPages) {
  const pageData = await page.$$eval('.result-item', items =>
    items.map(el => ({ title: el.querySelector('h3')?.textContent?.trim() }))
  );
  allData.push(...pageData);

  const nextBtn = await page.$('a.next-page:not([disabled])');
  if (!nextBtn) break;

  const previousUrl = page.url();
  const previousFirstItem = await page
    .$eval('.result-item', el => el.textContent?.trim() || '')
    .catch(() => '');

  await nextBtn.click();

  // クリック後検出のみ: 進展はこのクリックが原因である必要があります
  const advanced = await Promise.any([
    page
      .waitForURL(url => url.toString() !== previousUrl, { timeout: 5000 })
      .then(() => true),
    page
      .waitForFunction(
        prev => {
          const first = document.querySelector('.result-item');
          return !!first && (first.textContent || '').trim() !== prev;
        },
        previousFirstItem,
        { timeout: 5000 }
      )
      .then(() => true),
  ]).catch(() => false);

  if (!advanced) break;

  await page.waitForLoadState('networkidle').catch(() => {});
  pageIndex += 1;
}

実行チェーン

ステップ 1: ターゲットを理解する

ユーザーリクエストから以下を特定します:

• URL — 抽出元のページ
• データ形状 — 必要なフィールド / 列
• スコープ — 単一ページ、ページネーション、無限スクロール、または複数ページクロール
• 出力形式 — JSON（デフォルト）、CSV、またはその他

ステップ 2: セレクターを取得し、実行パスを選択する

# Actionbook インデックスを試す
actionbook search "<site> <data-description>" --domain <domain>

# 良好な結果がある場合（health ≥ 70%）、フルセレクターを取得
actionbook get "<ID>"

このルーティングを厳密に使用します:

• パス A（get が良好な場合のデフォルト）: 要求されたフィールドは get セレクターでカバーされており、品質は許容可能です。

  • get セレクターから開始し、スクリプトドラフトに素早く進みます。
  • スクリプト戦略を最終化する前に、軽量メカニズムプローブ（browser text、クイックスクロールチェック）を実行することができます。
  • プローブ/サンプル検証が不一致を示さない限り、最初のドラフト前に完全なフォールバック（snapshot / screenshot）を実行しないでください。
  • フィールドマッピングはデフォルトで get セレクターを使用し、ソースを actionbook_get としてマークします。

• パス B（部分的 / 不安定）: get は存在するが、必要なフィールドが不足している、セレクターが 0 要素を返す、または検証に失敗しています。

  • 失敗したフィールド/ステップのみを対象としたフォールバックを実行します。

• パス C（使用可能なカバレッジなし）: search/get に使用可能な結果がありません。

  • 完全なフォールバック検出を実行します。

ステップ 3: ページメカニズムをプローブし、必要なときだけフォールバック

パス A メカニズム検出のタイミング:

• 最小限のプローブを最後のスクリプトドラフト前またはサンプル検証中に実行します。
• プローブコマンド前に、正しいページコンテキストが開いていることを確認します:
  • actionbook browser open "<url>" （現在のタブコンテキストが不明/古い場合）
• プローブ/サンプル実行が不一致を示す場合（行がない、セレクターが不安定、ページネーション動作が間違っている）、パス B 対象フォールバックにエスカレートします。

パス別フォールバック検出:

パス B 対象フォールバック（失敗したフィールド/ステップのみ）:

actionbook browser open "<url>"     # まだ開いていない場合
actionbook browser snapshot          # 失敗したフィールド/コンテナマッピングに焦点
# actionbook browser screenshot      # オプション: 失敗エリアのビジュアル確認

パス C 完全フォールバック（使用可能なカバレッジなし）:

actionbook browser open "<url>"
actionbook browser snapshot
actionbook browser screenshot

メカニズムプローブ（スクリプト戦略の確認が必要な場合に実行）:

# ハイドレーション / ストリーミングチェック
actionbook browser text "<container-selector>"

# 無限スクロール クイック信号（明確な前/後判定）
actionbook browser eval "document.querySelectorAll('<item-selector>').length"   # 前
actionbook browser click "<scroll-container-selector-or-body>"                    # スクロールコンテキストに焦点
actionbook browser eval "const c=document.querySelector('<scroll-container-selector>') || document.scrollingElement; c.scrollBy(0, c.clientHeight || window.innerHeight);"
actionbook browser eval "document.querySelectorAll('<item-selector>').length"   # 後
# カウントが増加する場合、ページは遅延読み込み/無限スクロールとして扱います。

フォールバックトリガー条件:

• actionbook get が必要なすべてのフィールドをマップできません。
• actionbook get セレクターがサンプル実行で空/不安定な値を返します。
• ランタイム動作が期待されるメカニズムと矛盾する（例：仮想化コンテナ、遅延ハイドレーション）。

ステップ 4: Playwright スクリプトを生成

ターゲット URL へのナビゲーション、適切な準備完了シグナルの待機、検出されたメカニズムの処理、データの構造化オブジェクトへの抽出、ディスクへの出力の書き込み、ブラウザーのクローズ、無限ループを避けるためのガードレール（maxPages、maxScrolls、タイムアウト予算）を適用するスタンドアロン Playwright スクリプト（extract_<domain>_<slug>.cjs）を作成します。

スクリプトテンプレート:

// extract_<domain>_<slug>.cjs
// Actionbook extract スキルで生成
// 使用法: node extract_<domain>_<slug>.cjs

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.goto('<URL>', { waitUntil: 'domcontentloaded' });

  // -- 準備完了を待つ --
  await page.waitForSelector('<container>', { state: 'visible' });

  // -- 抽出 --
  const data = await page.$$eval('<item-selector>', items =>
    items.map(el => ({
      // ユーザーリクエストからマップされたフィールド
    }))
  );

  // -- 出力 --
  const fs = require('fs');
  fs.writeFileSync('output.json', JSON.stringify(data, null, 2));
  console.log(`${data.length} 個のアイテムを抽出 → output.json`);

  await browser.close();
})();

ステップ 5: 実行と検証

スクリプトを実行して動作を確認します:

node extract_<domain>_<slug>.cjs

検証ルール:

チェック	合格条件
スクリプトが終了コード 0 で終了	ランタイムエラーなし
出力ファイルが存在	空でないファイルが書き込まれている
レコード数 > 0	少なくとも 1 つのアイテムが抽出されている
null/空フィールドなし	宣言されたすべてのフィールドにレコードの ≥ 90% で値がある
データがページと一致	actionbook browser text に対して最初と最後のレコードをスポットチェック

検証に失敗する場合、出力を検査し、セレクターまたは待機戦略を調整して、再実行します。

ステップ 6: 配信

ユーザーに以下を提示します:

1. スクリプトパス — いつでも再実行できる .cjs ファイル
2. データパス — 出力 JSON/CSV ファイル
3. レコード数 — 抽出されたアイテム数
4. 注釈 — メカニズム固有の注意点（例: 「このサイトは無限スクロールを使用しています; スクリプトはデフォルトで最大 50 ページをスクロールします」）

出力契約

すべての extract 呼び出しは以下を生成します:

成果物	パス	形式
Playwright スクリプト	./extract_<domain>_<slug>.cjs	playwright を使用するスタンドアロン Node.js スクリプト
抽出されたデータ	./output.json（デフォルト）またはユーザー指定パス	オブジェクトの JSON 配列（デフォルト）、CSV、またはユーザー指定

スクリプトは再実行可能でなければなりません — ユーザーは後でランタイム環境に Node.js + Playwright がある限り、Actionbook がインストールされていない状態で実行できるようにする必要があります。

セレクター優先度

actionbook get から複数のセレクタータイプが利用可能な場合:

優先度	タイプ	理由
1	data-testid	安定、テスト指向、ほとんど変わらない
2	aria-label	アクセシビリティ駆動、意味的に意味がある
3	CSS セレクター	構造的、リデザイン時に破壊される可能性がある
4	XPath	最終手段、最も脆い

エラーハンドリング

エラー	アクション
actionbook search が結果を返さない	snapshot + screenshot にフォールバック
セレクターが 0 要素を返す	再スナップショット、スクリーンショットと比較、セレクターを更新
スクリプトがタイムアウト	waitForTimeout を長くする、アンチボット対策を確認
部分的なデータ（一部フィールドが空）	コンテンツが遅延読み込みされているかを確認; スクロール/待機を追加
アンチボット / CAPTCHA	ユーザーに通知; headless: false で実行するか、actionbook setup 拡張モード経由で自分のブラウザーセッションを使用することを提案