actionbook-scraper

Actionbook Scraper 技能

⚠️ 关键：两部分验证

生成的每个脚本都必须通过以下两项检查：

检查项	验证内容	失败示例
第一部分：脚本运行	没有错误、没有超时	Selector not found
第二部分：数据正确	内容符合预期	提取到的是“Click to expand”而不是名称

┌─────────────────────────────────────────────────────┐
│   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 代码

---

验证要求

两部分验证

生成的每个脚本都必须通过以下两项检查：

检查项	验证内容	失败后的操作
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 脚本	Agent（sonnet）	-	/generate 的默认模式
生成 Playwright 脚本	Agent（sonnet）	-	使用 --standalone 标志
结构分析	Agent（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 部分：数据必须正确——非空、不是界面文本、字段映射正确
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——最后手段，最不稳定

命令

命令	描述	Agent
/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