---

name: go-playwright description: "使用Playwright Go进行健壮、隐蔽和高效浏览器自动化的专家能力。" risk: safe source: "https://github.com/playwright-community/playwright-go" date_added: "2026-02-27"

Playwright Go 自动化专家

概述

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

何时使用此技能

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

安全与风险

风险级别：🔵 安全

• 沙箱执行： 浏览器上下文是隔离的；除非明确保存，否则不会将数据持久化到主机。
• 资源管理： 设计为通过 defer 关闭浏览器和上下文以防止内存泄漏。
• 无外部状态更改： 默认行为是只读（抓取/测试），除非脚本明确设计为提交表单或修改数据。

限制

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

战略实施指南

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

关键： 永远不要为每个任务启动新的 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 关闭Pages、Contexts和Browsers。
• 恐慌恢复： 将关键自动化例程包装在安全运行器中，恢复恐慌并记录堆栈跟踪。
• 超时： 永远不要依赖默认超时。设置明确的超时（例如 playwright.PageClickOptions{Timeout: playwright.Float(5000)}）。

4. 隐蔽与类人行为

要绕过反机器人系统（Cloudflare、Akamai），生成的代码必须模仿人类生理学：

• 非线性鼠标移动： 永远不要瞬移鼠标。实现一个辅助函数，沿贝塞尔曲线移动鼠标并添加随机抖动。
• 输入延迟： 永远不要使用 Fill()。使用 Type() 并在按键之间添加随机延迟（50ms-200ms）。
• 视口随机化： 轻微随机化视口大小（例如 1920x1080 ± 15px）以避免指纹识别。
• 行为噪声： 在长时间等待期间随机滚动、聚焦/取消聚焦窗口或悬停在无关元素上（"空闲"）。
• User-Agent： 为每个新Context轮换User-Agent。

5. 文档使用

• 主要来源： 首先依赖你对API的内部知识以节省token。
• 备选： 仅在以下情况参考官方文档 playwright-go documentation：
  • 遇到未知错误。
  • 需要实现复杂的网络拦截或认证流程。
  • API发生了重大变化。

资源

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

Agent总结检查清单

• 调试模式开启？-> Headless=false，SlowMo=100+。
• 是新用户身份？-> NewContext，应用新代理，轮换 User-Agent。
• 操作是否关键？-> 用 SafeAction 包装并使用Zap日志。
• 目标是否有防护（Cloudflare/Akamai）？-> 启用 HumanType、BezierMouse 和隐蔽脚本。