go-playwright

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 設定）は依然として自動化を検出する可能性があります。
• CAPTCHA: 組み込みの CAPTCHA 解決機能は含まれていません。

戦略的な実装ガイドライン

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 を使用してページ、コンテキスト、ブラウザを閉じてください。
• パニックリカバリ: 重要な自動化ルーチンを、パニックを回復してスタックトレースをログに記録する安全なランナーでラップします。
• タイムアウト: デフォルトのタイムアウトに依存しないでください。明示的なタイムアウトを設定します（例: playwright.PageClickOptions{Timeout: playwright.Float(5000)}）。

4. ステルスと人間らしい動作

アンチボットシステム（Cloudflare、Akamai）を回避するには、生成されるコードが人間の生理機能を模倣する必要があります:

• 非線形のマウス移動: マウスをテレポートさせないでください。ランダムなジッターを伴うベジェ曲線に沿ってマウスを移動するヘルパーを実装します。
• 入力レイテンシ: 決して Fill() を使用しないでください。キーストローク間にランダムな遅延（50ms～200ms）を設けて Type() を使用します。
• ビューポートのランダム化: フィンガープリンティングを避けるため、ビューポートサイズをわずかにランダム化します（例: 1920x1080 ± 15px）。
• 行動ノイズ: 長い待機中に、ランダムにスクロールしたり、ウィンドウをフォーカス/アンフォーカスしたり、無関係な要素にホバーしたりします（「アイドリング」）。
• User-Agent: 新しいコンテキストごとに User-Agent をローテーションします。

5. ドキュメントの使用方法

• 主要な情報源: トークンを節約するため、まずは API に関する自身の内部知識に頼ってください。
• フォールバック: 公式ドキュメント playwright-go documentation を参照するのは、以下の場合に限ります:
  • 不明なエラーに遭遇した場合。
  • 複雑なネットワーク傍受や認証フローを実装する必要がある場合。
  • API が大幅に変更された場合。

リソース

• 詳細なコード例と実装パターンについては resources/implementation-playbook.md を参照してください。

エージェント向けサマリーチェックリスト

• デバッグモードはオンですか？ -> Headless=false、SlowMo=100+。
• 新しいユーザーアイデンティティですか？ -> NewContext を使用し、新しいプロキシを適用し、User-Agent をローテーションします。
• その操作は重要ですか？ -> Zap ロギングを伴う SafeAction でラップします。
• ターゲットは保護されていますか（Cloudflare/Akamai）？ -> HumanType、BezierMouse、ステルススクリプトを有効にします。