以下为本文档的中文说明

该技能为agent-browser，是一套专业的工具和最佳实践集合。它提供了完整的功能实现指导，涵盖核心概念、配置方法和典型应用场景。该技能注重实用性和可操作性，适用于需要在相关领域实现自动化和高效工作的开发者和技术团队。通过系统化的学习，用户可以快速掌握关键技能，在项目中有效应用。该技能提供了详细的操作指南和最佳实践，帮助用户快速上手并深入掌握。通过系统的功能模块划分和丰富的应用场景说明，用户可以在实际项目中有效运用该技能提升工作效率。该技能注重实用性和可操作性，涵盖从基础配置到高级功能的完整知识体系，满足不同层次用户的学习需求。持续更新和优化的内容确保用户始终能够接触到最新的技术发展和行业实践。通过此技能的学习和应用，用户可以减少摸索时间，快速获得可用的解决方案，将精力集中在核心业务逻辑和创新工作上，从而在技术快速迭代的环境中保持竞争力。该技能的模块化设计使其易于扩展和定制，用户可以根据自身需求灵活调整应用方式，实现最大化的价值产出。该技能整合了常见的设计模式和最佳实践，提供了清晰的学习路径和参考资料，帮助用户在短时间内建立起完整的知识框架，并有能力在实际项目中灵活运用所学内容解决问题。

Agent Browser

Use a controlled browser to verify behavior, capture evidence, or extract information from web pages that a static fetch cannot reach (SPAs, login-gated pages, dynamic content). This skill is about supervised verification, not unattended scraping.

When to use

• You need a screenshot of a deployed page or a local dev server to confirm a UI change.
• You need to read JavaScript-rendered content thatcurl/wgetwill not see.
• A user reports a UI bug and you need to reproduce it interactively to capture console errors, network requests, or layout state.
• You need to walk through a short flow (load page, click, observe) to verify acceptance criteria.

When not to use

• The page is reachable as static HTML. Usecurl/HTTP fetch — it is cheaper, faster, and more reliable.
• The task is unattended large-scale scraping. That belongs to a dedicated scraper with rate limits, robots.txt handling, and a real user agent policy — not this skill.
• The site is behind authentication you do not own credentials for, or whose terms of service prohibit automation.
• The site involves sensitive accounts (banking, healthcare, government) where automation risks lockout or compliance issues.

Before launching the browser

• Confirm the URL and what state should be true after navigation.
• Decide what evidence is needed: full-page screenshot, viewport screenshot, console log, network trace, HTML snapshot, extracted text.
• Decide the viewport size that matters for the task (mobile vs desktop). Default to a desktop size unless the task is mobile-specific.
• For local dev servers, confirm the server is running and the port is what you expect.

Driving the browser

A typical verification session:

1. Launch with a real-looking user agentwhen the target is the public internet; an unrealistic UA flags automation traffic.
2. Set a sane viewport(e.g., 1366×768 desktop, 390×844 iPhone-ish).
3. Navigate and wait for the right signal.Prefer waiting for a specific selector or network-idle over arbitrary sleeps.
4. Capture evidence immediatelyafter the wait condition succeeds, before any interaction perturbs the state.
5. Interact deliberately.One click at a time, with a wait between actions; re-screenshot after each meaningful state change.
6. Read the console and network panelsfor unexpected errors, 4xx/5xx responses, or slow requests.
7. Close the browser cleanlywhen done. Long-running browser sessions leak memory and hold ports.

What evidence to record

For a verification task, deliver:

• A full-page or viewport screenshot of each meaningful state.
• The console log, filtered to warnings/errors.
• Any non-2xx network response with the URL, status, and a short response body excerpt.
• A short narration: “Navigated to X, observed Y, clicked Z, observed W.”

For a UI bug repro, also record:

• The exact reproduction steps the user can follow.
• Viewport size and (where relevant) device pixel ratio.
• Whether the bug reproduces on first load vs after interaction.

Login-gated pages

• Prefer programmatic auth (API token, magic link) over UI login.
• If UI login is the only path, the user must provide credentials explicitly for this run. Never reuse credentials outside the session.
• Do not store credentials in the session log, screenshot, or returned output.

Performance and politeness

• Throttle to one navigation per few seconds when touching shared infra.
• Respectrobots.txtfor public sites you are inspecting at any volume.
• Cancel navigations if a page exceeds a reasonable timeout (e.g., 30s); the page is broken or rate-limiting you.
• Do not retry forever on failure. Retry once with a longer timeout, then escalate.

Common failure modes

• Selector not found.Page changed, or you are waiting before render. Take a screenshot to see actual state; adjust the selector.
• Click does nothing.The element is offscreen, covered by a modal, or in a shadow DOM. Scroll into view or pierce the shadow root.
• Headless detection.Some sites detect headless C
  hrome and serve a different page. Use a non-headless mode or a fingerprint-realistic configuration only when authorized.
• Cross-origin iframe blocking.Iframes you do not own cannot be inspected; the page must offer the data outside the iframe or the task is infeasible.

Anti-patterns

• Long unsupervised browser sessions that drift from the original task.
• Scraping behind authentication you do not own.
• Captioning a screenshot with “looks good” without saying what state was loaded and what selectors confirmed it.
• Treating a passing screenshot as proof of correctness across viewports you did not actually test.
  3e:[“","","","L48”,null,{“content”:“$49”,“frontMatter”:{“name”:“agent-browser”,“description”:“Drive a real browser to inspect or interact with a web page or app — navigate, take screenshots, read console and network, fill simple forms — for verification tasks, not unattended automation.”,“key”:“paperclipai/optional/browser/agent-browser”,“recommendedForRoles”:[“qa”,“engineer”,“researcher”],“tags”:[“browser”,“puppeteer”,“playwright”,“verification”]}}]