Dev Browser Local Profile
このスキルは、ブラウザ自動化が毎回新しいブラウザ状態を起動する代わりに、長期間存続するローカルブラウザプロファイルに接続する必要がある場合に使用します。
このプロジェクトはdev-browserから適応されましたが、現在のスキルはスタンドアロンで動作し、dev-browserは必要ありません。
基本ルール
dev-browserの代わりに、バンドルされたPlaywright-over-CDPスクリプトを使用します。- 永続的なブラウザプロファイルがログイン状態の信頼できる情報源であると想定します。
- 固定のリモートデバッグポートを優先します。ユーザーが指定しない限り、デフォルトで
9222を使用します。 - プロファイルパスはユーザー相対パスにしてください。マシン固有のユーザー名をハードコードしないでください。
- デフォルトでは、ユーザーの現在のタブを置き換えるのではなく、新しいタブを開きます。明示的に要求された場合を除きます。
セットアップ手順
1. 依存関係のインストール
スキルディレクトリ内で一度だけ実行します：
npm install
これによりplaywright-coreのみがインストールされます。個別の管理対象ブラウザはダウンロードされません。
2. 永続的なプロファイルでChromeまたはChromiumを起動する
現在のユーザーのホームディレクトリ配下に固定のユーザーデータディレクトリを使用します：
- Windows:
Join-Path $env:USERPROFILE 'chrome-dev-browser-profile' - macOS/Linux:
~/chrome-dev-browser-profile
クロスプラットフォーム起動用のバンドルランチャースクリプトを使用します：
python scripts/start_chrome_debug.py
便利なオプション：
python scripts/start_chrome_debug.py --port 9222
python scripts/start_chrome_debug.py --profile-dir "C:\Users\name\chrome-dev-browser-profile"
python scripts/start_chrome_debug.py --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
3. スタンドアロンブラウザツールを使用する
新しいタブでURLを開く：
node scripts/browser_tools.mjs open --url "http://localhost:9800/h5-bzzx/"
現在のタブを一覧表示：
node scripts/browser_tools.mjs list
スクリーンショットを撮る：
node scripts/browser_tools.mjs screenshot --url "http://localhost:9800/h5-bzzx/" --output "./page.png"
4. カスタム自動化タスクを実行する
単純な open/list/screenshot フロー以上の処理には、汎用タスクランナーを使用します：
node scripts/run_task.mjs --task ./my-task.mjs --url "http://localhost:9800/h5-bzzx/" --task-arg mode=debug
タスクモジュールは、デフォルトの非同期関数またはrunという名前の関数をエクスポートする必要があります。
例：
export default async function ({ page, helpers, taskArgs }) {
await page.waitForLoadState("domcontentloaded");
return {
title: await page.title(),
url: page.url(),
taskArgs
};
}
ハッシュルートの処理
ハッシュルーティングされたURLに対して、json/new?... または類似の直接DevToolsオープンフローに依存しないでください。#... の部分が欠落する可能性があります。
ハッシュルートの場合、バンドルされたスクリプトは既に2段階のナビゲーション戦略を使用しています：
- 最初にベースURLを開きます。
- 次に、ページ内で
window.location.hrefを設定します。
例：
node scripts/browser_tools.mjs open --url "http://localhost:9527/#/inspection/log/list?book_id=352"
検証チェックリスト
ページを開いた後、明示的に成功を確認します：
- JSON出力の
urlが期待されるルートと一致することを確認します。 - ページに動的なタイトルがある場合は、
titleまたは既知のセレクタを確認します。 - アクションが無音のように見える場合は、再試行する前に
node scripts/browser_tools.mjs listを実行します。 - ログインが欠落している場合は、Chromeが永続的なプロファイルで起動されており、一時的なプロファイルではないことを確認します。
障害モード
ブラウザツールが接続できない
考えられる原因：Chromeが--remote-debugging-port=<port>で実行されていません。
修正方法：
python scripts/start_chrome_debug.pyでChromeを再起動します。- ポートがスクリプトに渡したものと一致することを確認します。
新しいタブが開いたがルートが間違っている
考えられる原因：外部ツールまたは手動で短縮されたURLによるハッシュルートの切り捨て。
修正方法：
- バンドルされたopenコマンドを使用します。
- 完全なハッシュルートURLを渡します。
ログイン状態がない
考えられる原因：Chromeが異なるプロファイルディレクトリで起動されました。
修正方法：
- 永続的な
--user-data-dirでChromeを再起動します。 - 同じプロファイルディレクトリを一貫して再利用します。
スコープ
このスキルは意図的にワークフローに焦点を当てています。Playwright over CDPを使用して、永続的なローカルログイン状態のためのスタンドアロンブラウザ自動化セットアップを標準化します。