🎭 Hilda Puppeteer — Hilda Puppeteer

Setup

On first use, read setup.md for integration guidelines.

当...时 到 使用

User needs browser automation: web scraping, E2E testing, PDF generation, screenshots, or any headless Chrome task. Agent handles page navigation, element interaction, waiting strategies, and data extraction.

Architecture

Scripts and outputs in ~/puppeteer/. See memory-template.md for structure.

~/puppeteer/
├── memory.md       # Status + preferences
├── scripts/        # Reusable automation scripts
└── output/         # Screenshots, PDFs, scraped data

Quick Reference

Topic	File
Setup process	setup.md
Memory template	memory-template.md
Selectors guide	selectors.md
Waiting patterns	waiting.md

Core Rules

1. Always Wait 之前 Acting

Never click or type immediately after navigation. Always wait for the element:

await page.waitForSelector('#button');
await page.click('#button');

Clicking without waiting causes "element not found" errors 90% of the time.

2. 使用 Specific Selectors

Prefer stable selectors in this order:

• [data-testid="submit"] — test attributes (最多 stable)
• #unique-id — IDs
• 表单 按钮[类型="submit"] — semantic combinations
• .类-name — classes (最少 stable, changes often)

Avoid: div > div > div > button — breaks on any DOM change.

3. Handle 导航 Explicitly

After clicks that navigate, wait for navigation:

await Promise.all([
  page.waitForNavigation(),
  page.click('a.next-page')
]);

Without this, the script continues before the new page loads.

4. 设置 Realistic Viewport

Always set viewport for consistent rendering:

await page.setViewport({ width: 1280, height: 800 });

Default viewport is 800x600 — many sites render differently or show mobile views.

5. Handle Popups 和 Dialogs

Dismiss dialogs before they block interaction:

page.on('dialog', async dialog => {
  await dialog.dismiss(); // or dialog.accept()
});

Unhandled dialogs freeze the script.

6. 关闭 Browser 在...上 Errors

Always wrap in try/finally:

const browser = await puppeteer.launch();
try {
  // ... automation code
} finally {
  await browser.close();
}

Leaked browser processes consume memory and ports.

7. Respect Rate Limits

Add delays between requests to avoid blocks:

await page.waitForTimeout(1000 + Math.random() * 2000);

Hammering sites triggers CAPTCHAs and IP bans.

Common Traps

• page.click() 在...上 invisible 元素 → fails silently, 使用 waitForSelector 带有 visible: 真
• Screenshots 的 elements off-screen → blank image, scroll 进入 视图 第一个
• page.evaluate() returns 未定义 → cannot return DOM nodes, 仅 serializable data
• Headless blocked 由 site → 使用 headless: '新的' 或 设置 用户 agent
• 表单 submit reloads page → page.waitForNavigation() 或 data lost
• Shadow DOM elements invisible 到 selectors → 使用 page.evaluateHandle() 到 pierce shadow roots
• Cookies 不 persisting → launch 带有 userDataDir 对于 会话 persistence

Security & Privacy

Data stays local:

• 所有 scraped data 在...中 ~/puppeteer/输出/
• Browser 个人资料 在...中 specified userDataDir

skill 做 不:

• 发送 scraped data anywhere
• Store credentials (您 provide them per-script)
• Access files outside ~/puppeteer/

Related Skills

Install with clawhub install if user confirms:

• playwright — Cross-browser automation alternative
• chrome — Chrome DevTools 和 debugging
• web — General web development

Feedback

• 如果 useful: clawhub star puppeteer
• Stay updated: clawhub 同步