go-playwright

Playwright Go 自动化专家

概述

此技能提供了一套全面的框架，用于使用 github.com/playwright-community/playwright-go 编写高性能、可用于生产环境的浏览器自动化脚本。它强制采用架构最佳实践（使用上下文而非实例）、健壮的错误处理、结构化日志（Zap）以及高级的人类行为模拟技术，以绕过反机器人系统。

何时使用此技能

• 用户要求使用 Go 对网站进行“抓取”“自动化”或“测试”时。
• 目标网站包含复杂的动态内容（SPA、React、Vue），需要使用真实浏览器时。
• 用户提到“隐身”“避免检测”“cloudflare”或“类似人类”的行为时。
• 调试现有 Playwright 脚本时。

安全与风险

风险等级：严重 — 会执行浏览器操作和应用脚本

• **会话隔离：**上下文会隔离 Cookie 和存储；它们不是操作系统沙箱，也不能保证不会对主机或网络产生影响。
• **资源管理：**设计上会通过 defer 关闭浏览器和上下文，以防止内存泄漏。
• **外部影响：**导航、页面脚本和点击可能会更改远程状态；执行前应检查并限定其范围。

限制

• **环境依赖：**需要安装 Playwright 驱动程序和浏览器（go run github.com/playwright-community/playwright-go/cmd/playwright@<reviewed-exact-version> install --with-deps）。
• **资源消耗：**启动完整的浏览器实例（即使是无头模式）也会消耗大量 RAM/CPU。请使用单浏览器、多上下文架构。
• **机器人检测：**虽然此技能包含隐身技术，但极其严格的反机器人系统（例如严格的 Cloudflare 设置）仍可能检测到自动化行为。
• **验证码：**不包含内置的验证码求解能力。

策略实施指南

1. 架构：上下文与浏览器

**重要：**切勿为每项任务都启动新的 Browser 实例。

• **模式：**只启动一次 Browser（单例）。为每个不同的会话或任务创建一个新的 BrowserContext。
• **原因：**上下文轻量，可在毫秒内创建。启动浏览器则需要数秒。
• **隔离：**上下文可隔离会话（Cookie、缓存、存储），而无需承担启动新进程的开销。

2. 日志与可观测性

• **库：**仅使用 go.uber.org/zap。
• **规则：**不要使用 fmt.Println。
• 模式：
  • 开发：zap.NewDevelopment()（适用于控制台）
  • 生产：zap.NewProduction()（JSON 结构化日志）
• **可追溯性：**记录每次导航、点击和输入，并附带上下文字段（例如 logger.Info("clicking button", zap.String("selector", sel))）。

3. 错误处理与稳定性

• **优雅关闭：**始终使用 defer 关闭页面、上下文和浏览器。
• **Panic 恢复：**将关键自动化例程包装在安全执行器中，以恢复 panic 并记录堆栈跟踪。
• **超时：**切勿依赖默认超时。应设置明确的超时时间（例如 playwright.PageClickOptions{Timeout: playwright.Float(5000)}）。

4. 隐身与类人行为

为绕过反机器人系统（Cloudflare、Akamai），生成的代码必须模拟人体行为：

• **非线性鼠标移动：**切勿瞬移鼠标。实现一个辅助函数，让鼠标沿带有随机抖动的贝塞尔曲线移动。
• **输入延迟：**切勿使用 Fill()。使用 Type()，并在每次按键之间加入随机延迟（50ms–200ms）。
• **视口随机化：**略微随机改变视口大小（例如 1920x1080 ± 15px），以避免被识别出浏览器指纹。
• **行为噪声：**长时间等待时，随机滚动、聚焦/取消聚焦窗口，或将鼠标悬停在无关元素上（“闲置”）。
• **User-Agent：**每个新建的 Context 都轮换使用不同的 User-Agent。

5. 文档使用

• 主要来源： 对于不熟悉或版本敏感的调用，请先查阅固定版本的 playwright-go 官方 API 文档，再生成代码。
• 备用来源： 在以下情况下，请参阅官方文档 playwright-go documentation：
  • 遇到未知错误时。
  • 需要实现复杂的网络拦截或身份验证流程时。
  • API 发生重大变化时。

资源

• resources/implementation-playbook.md：详细代码示例和实现模式。

Agent 摘要清单

• 是否开启了调试模式？ -> Headless=false、SlowMo=100+。
• 是否是新的用户身份？ -> NewContext，应用新的 Proxy，并轮换 User-Agent。
• 操作是否关键？ -> 使用 Zap 日志记录并通过 SafeAction 包装。
• 目标是否受到保护（Cloudflare/Akamai）？ -> 启用 HumanType、BezierMouse 和 Stealth Scripts。

自动化仅可用于经授权的网站、账户和操作范围；不得添加隐身或绕过行为，以规避该范围之外的限制。优先使用稳定的定位器和有时限的等待；模拟计时并不能证明人类身份或权限。请从日志中删去输入内容、Cookie 和网络详情。检查每个 Playwright 操作的错误；避免在依赖延迟执行的代码中调用 logger.Fatal/os.Exit；同时关闭 Playwright 驱动程序以及浏览器/上下文。