actionbook-scraper

Actionbook Scraper Skill

⚠️ 重大：2 段階の検証

生成するスクリプトはすべて、両方のチェックに合格する必要があります：

チェック	確認する内容	失敗例
パート 1：スクリプトの実行	エラーやタイムアウトがないこと	Selector not found
パート 2：データの正確性	内容が期待どおりであること	名前ではなく「クリックして展開」を抽出

┌─────────────────────────────────────────────────────┐
│   1. Generate Script                                │
│          ↓                                          │
│   2. Execute Script                                 │
│          ↓                                          │
│   3. Check Part 1: Script runs without errors?      │
│          ↓                                          │
│   4. Check Part 2: Data content is correct?         │
│      - Not empty                                    │
│      - Not placeholder text ("Loading...")          │
│      - Not UI text ("Click to expand")              │
│      - Fields mapped correctly                      │
│          ↓                                          │
│      ┌───┴───┐                                      │
│   BOTH Pass  Either Fails                           │
│      │           │                                  │
│      │           ↓                                  │
│      │       Is it Actionbook data issue?           │
│      │           │                                  │
│      │       ┌───┴───┐                              │
│      │      Yes      No                             │
│      │       │       │                              │
│      │       ↓       ↓                              │
│      │    Log to   Fix script                       │
│      │    .actionbook-issues.log                    │
│      │       │       │                              │
│      │       └───┬───┘                              │
│      │           ↓                                  │
│      │       Retry (max 3x)                         │
│      ↓                                              │
│   Output Script                                     │
└─────────────────────────────────────────────────────┘

デフォルトの出力形式

/actionbook-scraper:generate <url>

デフォルト＝agent-browser スクリプト（bash コマンド）

agent-browser open "https://example.com"
agent-browser scroll down 2000
agent-browser get text ".selector"
agent-browser close

--standalone フラグを指定した場合

/actionbook-scraper:generate <url> --standalone

出力＝Playwright JavaScript コード

---

検証要件

2 段階の検証

生成するスクリプトはすべて、両方のチェックに合格する必要があります：

チェック	確認する内容	失敗時の対応
1. スクリプトの実行	エラーやタイムアウトがないこと	構文やセレクターのエラーを修正
2. データの正確性	内容が期待されるフィールドと一致すること	抽出ロジックを修正

パート 1：スクリプトの実行チェック

• 実行時エラーがない
• タイムアウトエラーがない
• ブラウザーが適切に閉じられる

パート 2：データ内容のチェック（重大）

抽出されたデータが期待される構造と一致することを確認します：

Expected: Company name, description, website, year founded
Actual:   "Click to expand", "Loading...", empty strings

→ FAIL: Data content incorrect, need to fix extraction logic

データ検証ルール：

ルール	失敗例	修正方法
フィールドが空でない	name: ""	セレクターが正しい要素を対象にしているか確認
プレースホルダーテキストがない	name: "Loading..."	動的コンテンツの表示を待機する
UI テキストがない	name: "Click to expand"	ボタンのテキストではなく、展開後に抽出する
データ型が正しい	year: "View Details"	セレクターが誤っています。フィールドの対応付けを修正
件数が妥当	期待値：約100件、実際：3件	スクロールやページネーションへの対応を追加

agent-browser スクリプトの場合

1. 生成したコマンドを実行する
2. スクリプトがエラーなしで実行されることを確認する
3. データ内容が正しいことを確認する：
   • フィールドが期待される構造と一致する
   • 値が UI テキストではなく実際のデータである
   • 件数が妥当である
4. 失敗した場合：
   • 問題の種類を分析する（スクリプトエラーかデータエラーか）
   • セレクター、待機ロジック、または抽出方法を修正する
   • 再実行する
5. 成功した場合：
   • 検証済みのスクリプトを出力する
   • フィールドの検証結果を含むデータのプレビューを表示する

Playwright スクリプト（--standalone）の場合

1. 一時ファイルにスクリプトを書き込む
2. node script.js で実行する
3. スクリプトがエラーなしで実行されることを確認する
4. 出力データが正しいことを確認する：
   • JSON 構造が期待されるフィールドと一致する
   • 値に実際のデータが含まれている
   • 件数が期待される範囲に一致する
5. 失敗した場合：
   • エラーの種類を分析する
   • スクリプトを修正する
   • 再実行する
6. 成功した場合：
   • 検証済みのスクリプトを出力する

アーキテクチャの概要

/generate <url>              → OUTPUT: agent-browser bash commands
/generate <url> --standalone → OUTPUT: Playwright .js file

┌─────────────────────────────────────────────────────────────┐
│                   /generate <url>                           │
│                                                             │
│   1. Search Actionbook → get selectors                      │
│   2. Generate OUTPUT:                                       │
│                                                             │
│      WITHOUT --standalone    │    WITH --standalone         │
│      ─────────────────────   │    ──────────────────        │
│      agent-browser commands  │    Playwright .js code       │
│                              │                              │
│      ```bash                 │    ```javascript             │
│      agent-browser open ...  │    const { chromium } = ...  │
│      agent-browser get ...   │    await page.goto(...)      │
│      agent-browser close     │    ```                       │
│      ```                     │                              │
└─────────────────────────────────────────────────────────────┘

ツールの優先順位

操作	主なツール	フォールバック	備考
URL のセレクターを検索	search_actions	なし	ドメインやキーワードで検索
セレクターの詳細を取得	get_action_by_id	なし	検索結果の action_id を使用
利用可能なソースを一覧表示	list_sources	search_sources	インデックス済みのサイトをすべて確認
agent-browser スクリプトを生成	エージェント（sonnet）	-	/generate のデフォルトモード
Playwright スクリプトを生成	エージェント（sonnet）	-	--standalone フラグを使用
構造を分析	エージェント（haiku）	-	Actionbook の応答を解析
新しいウェブサイトをリクエスト	agent-browser	手動	actionbook.app に送信（agent-browser を実行する唯一のコマンド）

ワークフロールール

重大：生成 → 検証 → 修正

生成したスクリプトはすべて、実行して検証する必要があります。

手順	アクション
1	Actionbook のセレクターを使ってスクリプトを生成する
2	スクリプトを実行して動作を検証する
3	失敗した場合：エラーを分析し、スクリプトを修正して、手順2に戻る
4	成功した場合：検証済みのスクリプトとデータのプレビューを出力する

検証プロセス

agent-browser スクリプトの場合：

# Execute each command
agent-browser open "https://example.com"
agent-browser wait --load networkidle
agent-browser get text ".selector"
# Check if data is returned
# If error → fix and retry
agent-browser close

Playwright スクリプト（--standalone）の場合：

# Write to temp file and execute
node /tmp/scraper.js
# Check if output file has data
# If error → fix and retry

重要なルール

1. 生成したスクリプトは必ず検証してください — 両方の項目を実行して確認します
2. 項目 1：スクリプトが実行できること — エラーやタイムアウトがないこと
3. 項目 2：データが正しいこと — 空ではなく、UI のテキストではなく、フィールドが正しくマッピングされていること
4. エラーは自動的に修正してください — 壊れたスクリプトや誤ったデータを出力しないでください
5. まず Actionbook MCP ツールを使用してください — セレクターを推測しないでください
6. 遅延読み込みされるページにはスクロール処理を含めてください
7. カードベースのレイアウトには展開／折りたたみ処理を含めてください
8. 必ずブラウザーを閉じてください — agent-browser close を含めます
9. 最大 3 回まで再試行してください — それでも失敗する場合は、具体的な問題を報告します

よくあるデータエラーへの対処

エラー	例	修正方法
ボタンのテキストを抽出	name: "Click to expand"	展開後にコンテンツを抽出します
プレースホルダーを抽出	desc: "Loading..."	動的コンテンツの待機処理を追加します
フィールドが空	name: ""	セレクターを修正します
フィールドのマッピングが誤り	year: "San Francisco"	各フィールドのセレクターを修正します
項目数が少なすぎる	100 件を想定、3 件を取得	スクロール／ページネーションを追加します

Actionbook のデータに関する問題を記録する

Actionbook のセレクターが誤っている、または古くなっている場合は、ローカルファイルに記録します。

.actionbook-issues.log

記録する状況：

• ページにセレクターが存在しない
• セレクターが誤った要素を返す
• ページ構造が変更されている
• 重要な要素のセレクターが不足している

ログ形式：

[YYYY-MM-DD HH:MM] URL: {url}
Action ID: {action_id}
Issue Type: {selector_error | outdated | missing}
Details: {description}
Selector: {selector}
Expected: {what it should select}
Actual: {what it actually selects or error}
---

セレクターの優先順位

Actionbook が複数のセレクターを提示する場合は、次の優先順位で選択します。

1. data-testid — 最も安定しており、自動化向けに設計されています
2. aria-label — アクセシビリティに基づくセマンティックなセレクターです
3. css — クラスベースのセレクターです
4. xpath — 最終手段であり、最も不安定です

コマンド

コマンド	説明	エージェント
/actionbook-scraper:analyze <url>	ページ構造を分析し、利用可能なセレクターを表示します	structure-analyzer
/actionbook-scraper:generate <url>	agent-browser スクレイパースクリプトを生成します	code-generator
/actionbook-scraper:generate <url> --standalone	Playwright/Puppeteer スクリプトを生成します	code-generator
/actionbook-scraper:list-sources	Actionbook のデータがあるウェブサイトを一覧表示します	-
/actionbook-scraper:request-website <url>	インデックス登録する新しいウェブサイトをリクエストします（agent-browser を使用）	website-requester

データフロー

Analyze コマンド

1. User: /actionbook-scraper:analyze https://example.com/page
2. Extract domain from URL → "example.com"
3. search_actions("example page") → [action_ids]
4. For best match: get_action_by_id(action_id) → full selector data
5. Structure-analyzer agent formats and presents findings

Generate コマンド（デフォルト：agent-browser スクリプト）

User: /actionbook-scraper:generate https://example.com/page

Step 1: Search Actionbook
  search_actions("example.com page") → action_ids

Step 2: Get selectors
  get_action_by_id(best_match) → selectors

Step 3: Generate agent-browser script
  ```bash
  agent-browser open "https://example.com/page"
  agent-browser wait --load networkidle
  agent-browser scroll down 2000
  agent-browser get text ".item-container"
  agent-browser close

ステップ 4：スクリプトを検証する（必須） コマンドを実行し、データが抽出されたか確認します 失敗した場合 → エラーを分析 → スクリプトを修正 → 再試行（最大 3 回）

ステップ 5：検証済みスクリプトとデータプレビューを返す

**Example Output:**
````markdown
## Verified Scraper (agent-browser)

**Status**: ✅ Verified (extracted 50 items)

Run these commands to scrape:

```bash
agent-browser open "https://example.com/page"
agent-browser wait --load networkidle
agent-browser scroll down 2000
agent-browser get text ".item-container"
agent-browser close

データプレビュー

[
  {"name": "Item 1", "description": "..."},
  {"name": "Item 2", "description": "..."},
  // ... showing first 3 items
]

### Generate Command (--standalone: Playwright script)

```
User: /actionbook-scraper:generate https://example.com/page --standalone

Step 1: Search Actionbook for selectors
Step 2: Get full selector data
Step 3: Generate Playwright/Puppeteer script
Step 4: VERIFY script (REQUIRED)
  Write to temp file → node /tmp/scraper.js → check output
  If failed → analyze error → fix script → retry (max 3x)
Step 5: Return verified script + data preview
```

**Example Output:**
````markdown
## Verified Scraper (Playwright)

**Status**: ✅ Verified (extracted 50 items)

```javascript
const { chromium } = require('playwright');
// ... generated code with Actionbook selectors
```

Usage:
```bash
npm install playwright
node scraper.js
```

### Data Preview
```json
[
  {"name": "Item 1", "description": "..."},
  // ... first 3 items
]
```

Request Website コマンド

1. User: /actionbook-scraper:request-website https://newsite.com/page
2. Launch website-requester agent (uses agent-browser)
3. Agent workflow:
   a. agent-browser open "https://actionbook.app/request-website"
   b. agent-browser snapshot -i (discover form selectors)
   c. agent-browser type <url-field> "https://newsite.com/page"
   d. agent-browser type <email-field> (optional)
   e. agent-browser type <usecase-field> (optional)
   f. agent-browser click <submit-button>
   g. agent-browser snapshot -i (verify submission)
   h. agent-browser close
4. Output: Confirmation of submission

セレクターデータ構造

Actionbook は次の形式でセレクターデータを返します。

{
  "url": "https://example.com/page",
  "title": "Page Title",
  "content": "## Selector Reference\n\n| Element | CSS | XPath | Type |\n..."
}

よくあるセレクターパターン

カードベースのレイアウト：

Container: .card-list, .grid-container
Card item: .card, .list-item
Card name: .card__title, .card-name
Card description: .card__description
Expand button: .card__expand, button.expand

詳細の抽出（dt/dd パターン）：

// Common pattern for key-value pairs
const items = container.querySelectorAll('.info-item');
items.forEach(item => {
  const label = item.querySelector('dt').textContent;
  const value = item.querySelector('dd').textContent;
});

テーブルレイアウト：

Table: table, .data-table
Header: thead th, .table-header
Row: tbody tr, .table-row
Cell: td, .table-cell

ページタイプの検出

指標	ページタイプ	テンプレート
スクロールしてさらに読み込む	動的／無限スクロール	playwright-js（スクロールあり）
クリックして展開	カードベース	playwright-js（クリックあり）
ページネーションリンク	ページ分割	playwright-js（ページネーションあり）
静的コンテンツ	静的	puppeteer または playwright
SPA フレームワークを検出	SPA	playwright-js（ネットワークアイドル）

出力形式

分析結果

## Page Analysis: {url}

### Matched Action
- **Action ID**: {action_id}
- **Confidence**: HIGH | MEDIUM | LOW

### Available Selectors

| Element | Selector | Type | Methods |
|---------|----------|------|---------|
| {name} | {selector} | {type} | {methods} |

### Page Structure
- **Type**: {static|dynamic|spa}
- **Data Pattern**: {cards|table|list}
- **Lazy Loading**: {yes|no}
- **Expand/Collapse**: {yes|no}

### Recommendations
- Suggested template: {template}
- Special handling needed: {notes}

生成コードの出力

## Generated Scraper

**Target URL**: {url}
**Template**: {template}
**Expected Output**: {description}

### Dependencies
```bash
npm install playwright

コード

{generated_code}

使用方法

node scraper.js

出力

結果は {output_file} に保存されます

## Templates Reference

| Template | Flag | Output | Run With |
|----------|------|--------|----------|
| **agent-browser** | (default) | CLI commands | `agent-browser` CLI |
| playwright-js | --standalone | .js file | `node scraper.js` |
| playwright-python | --standalone --template playwright-python | .py file | `python scraper.py` |
| puppeteer | --standalone --template puppeteer | .js file | `node scraper.js` |

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| No actions found | URL not indexed | Use `/actionbook-scraper:request-website` to request indexing |
| Selectors not working | Page updated | Report to Actionbook, try alternative selectors |
| Timeout | Slow page load | Increase timeout, add retry logic |
| Empty data | Dynamic content | Add scroll/wait handling |
| Form submission failed | Network/page issue | Retry or submit manually at actionbook.app |

## agent-browser Usage

For the `request-website` command, the plugin uses **agent-browser CLI** to automate form submission.

### agent-browser Commands

```bash
# Open a URL
agent-browser open "https://actionbook.app/request-website"

# Get page snapshot (discover selectors)
agent-browser snapshot -i

# Type into form field
agent-browser type "input[name='url']" "https://example.com"

# Click button
agent-browser click "button[type='submit']"

# Close browser (ALWAYS do this)
agent-browser close

セレクターの特定

フォームのセレクターが不明な場合は、スナップショットを使用して特定します。

agent-browser open "https://actionbook.app/request-website"
agent-browser snapshot -i  # Returns page structure with selectors

必ずブラウザーを閉じる

重要： エラーが発生した場合も含め、agent-browser セッションの終了時には必ず agent-browser close を実行してください。

レート制限

• Actionbook MCP：ローカルでの使用にレート制限はありません
• 対象ウェブサイト：robots.txt を遵守し、リクエストの間に遅延を入れてください
• 推奨：ページリクエストの間に 1～2 秒の遅延を入れてください

例

例 1：agent-browser スクリプトの生成（デフォルト）

/actionbook-scraper:generate https://firstround.com/companies

Output: agent-browser commands
```bash
agent-browser open "https://firstround.com/companies"
agent-browser scroll down 2000
agent-browser get text ".company-list-card-small"
agent-browser close

ユーザーは次のコマンドを実行してスクレイピングします。

### Example 2: Generate Playwright Script

/actionbook-scraper:generate https://firstround.com/companies --standalone

出力：Playwright JavaScript コード

const { chromium } = require('playwright');
// ... full script

ユーザーが実行：node scraper.js

### Example 3: Analyze Page Structure

/actionbook-scraper:analyze https://example.com/products

出力：次の内容を示す分析：

• 利用可能なセレクター
• ページ構造
• 推奨されるアプローチ

### Example 4: Request New Website

/actionbook-scraper:request-website https://newsite.com/data

アクション：actionbook.app にフォームを送信します（このコマンドは agent-browser を実行します）

## Best Practices

1. **Always analyze before generating** - Understand the page structure first
2. **Check list-sources** - Verify the site is indexed before attempting
3. **Review generated code** - Verify selectors match expected elements
4. **Add appropriate delays** - Be respectful to target servers
5. **Handle edge cases** - Empty states, loading states, errors
6. **Test incrementally** - Run on small subset before full scrape