record-web-journey

Web の操作履歴を記録する

steps.md、screenshots/NNN-<kind>-<label>.png、および videos/*.webm を含む <out>/<NAME>-<timestamp>/ を生成します。steps.md では入力された値とクエリ文字列は省略されます。

レコーダーとブラウザードライバーは同じホストで実行してください。成果物はそのホストに直接保存します。VM 内で実行されているブラウザーは VM に、ローカルで実行されているブラウザーはローカルマシンに書き込みます。後で確認できるよう、完了したフォルダーはそのまま残し、絶対パスを報告してください。

SKILL_DIR にこの SKILL.md を含むディレクトリの絶対パスを設定してから、バンドルされているレコーダーを絶対パスで使用します。

SKILL_DIR="/absolute/path/to/record-web-journey"
RECORDER="$SKILL_DIR/scripts/record-flow.mjs"
AB="$SKILL_DIR/scripts/node_modules/.bin/agent-browser"

シェル呼び出しがそれぞれ独立している場合があるため、別々のシェル呼び出しを開始するたびに、必要に応じて SKILL_DIR、RECORDER、AB、保持している CDP ポート、および DISPLAY を設定し直してください。

セットアップ（ブラウザーホストごとに 1 回）

"$SKILL_DIR/scripts/setup.sh"
"$AB" skills get core

レコーダーの隣に agent-browser と Playwright をインストールし、動画用に Playwright の ffmpeg ヘルパーを追加します。また、Google Chrome がない場合は Chromium を追加します。Google Chrome がある場合は、サインインページに通常のブラウザーとして認識される --chrome を優先してください。

エージェント主導の記録（あなたが操作）

リクエストを開始 URL、記録 NAME、実行する手順に分けてください。

1. ホストを確認します。pgrep -a Xvnc または echo $DISPLAY でデスクトップの有無を確認できます。デスクトップがある場合は、すべてのシェル呼び出しで export DISPLAY=<it> を実行すると、人が操作をリアルタイムで確認できます。ディスプレイがない場合は --headless を追加します。df -h /dev/shm を確認し、64M なら 2G に再マウントしてください。そうしないと Chrome のレンダラーがクラッシュします。共有ホストでは、実行中の agent-browser プロセスを調べ、一意のセッションを選択し、完了時にはその名前付きセッションだけを閉じてください。

2. 記録対象のワークスペースから、このホスト上の絶対パスで出力ディレクトリと、使用可能なローカル CDP ポートを選択します。専用の長時間実行ターミナルまたはハーネスプロセスのセッションでレコーダーを起動し、そのセッションを実行したままにしてください。

   OUT="$PWD/.context/flow-recordings"
   PORT="$(node -e 'const s=require("node:net").createServer();s.listen(0,"127.0.0.1",()=>{console.log(s.address().port);s.close()})')"
   BROWSER_ARGS=()
   if command -v google-chrome >/dev/null || { [[ "$(uname -s)" == Darwin ]] && [[ -x "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ]]; }; then
     BROWSER_ARGS=(--chrome)
   fi
   printf 'CDP port: %s\n' "$PORT"
   node "$RECORDER" "https://app.example.com/" --name "journey-name" "${BROWSER_ARGS[@]}" --cdp "$PORT" --out "$OUT"
   

   表示されたポートと記録ディレクトリの絶対パスを、シェル呼び出しをまたいで保持してください。サインイン済みの操作履歴を記録する場合は、--profile <dir> を渡します（references/auth-and-bot-checks.md を参照）。

3. 一意のセッション名を指定して agent-browser をその Chrome に接続し、通常どおり操作します。

   "$AB" --session "rec-journey-name" --cdp "$PORT" snapshot -i -u
   "$AB" --session "rec-journey-name" --cdp "$PORT" click @e5
   

   すべてのコマンドで --session と --cdp の両方を使用します。レコーダーが読み込んだ開始 URL から操作を続け、手順で直接移動が必要な場合は open を使用してください。

4. 人が操作するペースに合わせ、各操作の間を約 1 秒空け、ナビゲーション後には wait --load networkidle を実行します。スクリーンショットはクリックから 250 ms 後に撮影されるため、間を空けずにクリックすると、どの手順にどのスクリーンショットが対応するか分かりにくくなります。

5. 画面下部より下にある要素を操作する場合は、scrollintoview @ref、続けて wait 1000、その後 click @ref の順に実行します。scroll-behavior: smooth が設定されたサイトではスクロールがアニメーションするため、明示的に停止させることで、クリック座標をターゲットに合わせられます。また、claude.ai で確認されたアニメーション中の座標読み取りを避けられます。snapshot -i から取得した最新の表示中の参照を使ってクリックしてください。視覚的に隠された 1x1 の入力欄は「（表示されているターゲットなし）」として記録されるため、それに対応する表示中のラベルまたはコントロールを選択してください。

6. <recordingDir>/STOP を使って終了し、レコーダーのセッションで「Saved N visual steps」が表示されるまで待ってから、名前付きの agent-browser セッションを閉じてください。この順序で、引き渡し前に WebM が確定されます。

   touch "/absolute/recording/directory/STOP"
   

   レコーダーの長時間実行セッションに戻るか、そこで「Saved N visual steps」が表示されるまで待ってから、名前付きのドライバーセッションを閉じてください。

   "$AB" --session "rec-journey-name" close
   

7. ブラウザーホスト上で steps.md を完成させ、各手順の下に、画面に表示された文言、agent-browser network requests からの関連する応答、および想定したフローと異なる結果を簡潔に記載します。成果物フォルダーはそのまま残してください。絶対パス、手順数、確認できた結果、リクエストされた手順を妨げたものがあればその内容を報告してください。

人による記録（人が操作）

node "$RECORDER" https://app.example.com/ -name "F06" --chrome --profile .context/chrome-profile

人は通常どおりウィンドウを操作し、完了したらターミナルで Enter キーを押します。生成されたフォルダーは、後で確認できるよう、そのマシン上の選択した出力ディレクトリに残ります。

フラグ

フラグ	意味
-name "<NAME>"	フォルダーのプレフィックス。例：F06-custom-mcp-<timestamp>
--chrome	インストール済みの Google Chrome を使用します（利用可能な場合は推奨）
--profile <dir>	Chrome のユーザーデータディレクトリを再利用し、録画間でサインイン状態を維持します
--cdp <port>	CDP を公開し、エージェントが agent-browser --cdp <port> で接続できるようにします
--headless	ウィンドウを表示しません。動画とスクリーンショットは引き続き作成されます
--out <dir>	親ディレクトリ。既定値は .context/flow-recordings です
--viewport WxH	ビューポートと動画のサイズ。既定値は 1440x900 です
--sign-in	--profile と併用します。通常の Chrome を開いてボットチェックを通過するかサインインし、その後終了します

終了シグナル：Enter（TTY）、STOP ファイル、ブラウザーの終了、SIGTERM。Enter または STOP の場合、 Playwright は正常な最終処理を行います。