before-and-after

PR にビジュアルメディアを追加する

スクリーンショットや録画の作成には agent-browser を使用します。このスキルの対象は、GitHub PR への添付ワークフローのみです。

キャプチャ

1. agent-browser skills get core --full でバージョンに一致するコア手順を読み込み、セッション、ナビゲーション、ページの状態、スクリーンショット、録画について、その手順に従ってください。

2. Vercel URL が保護されている場合は、agent-browser skills get protected-vercel-deployments --full を読み込んでください。ここで認証ワークフローを再現しないでください。

3. メディアは、次の例のように、空白を含まないパスを使ってリポジトリ内に保存してください。

   captures/desktop-before.png
   captures/desktop-after.png
   captures/mobile-before.png
   captures/mobile-after.png
   

フォーマッターは、PNG、JPEG、GIF、WebP、MP4、MOV、WebM ファイルに対応しています。新規プレビューの場合は、対応する --before ファイルを指定せずに --after ファイルを使用してください。

画面録画

agent-browser record start は、新しいブラウザーコンテキストを作成します。Cookie とローカルストレージは保持されますが、保護された Vercel Preview を開くために使用したオリジンスコープのヘッダーは、新しいコンテキストに引き継がれない場合があります。保護された Preview を録画する前に、次の手順を実行してください。

1. agent-browser skills get protected-vercel-deployments --full を読み込みます。
2. 空白のページで録画コンテキストを開始します。
3. そのスキルに記載された認証方法を、録画コンテキスト内で適用します。
4. 認証が有効になってから Preview に移動し、必要に応じて冒頭のナビゲーション部分をトリミングします。

record start の前に動作していたページでも、認証状態が維持されるとは限りません。

Agent-browser 0.35.2 と 0.36.0 は、CLI や環境変数による上書きができない、固定の 10 fps でキャプチャします。今後のリリースでも同じ仕様とは限らないため、インストールされているバージョンと録画リファレンスを確認してください。トランスコード時は、ソースのフレームレートを維持してください。コンテナのフレームレートを 30 fps や 60 fps に変更しても、フレームが複製されるだけで、動きは滑らかになりません。より高い実フレームレートが必要なアニメーションの証拠には、agent-browser の出力をアップサンプリングするのではなく、実際に高いフレームレートでキャプチャできる方法を使用してください。

高さを揃えた画像ペア

GitHub は、Markdown テーブルのセル内で高さの低い画像を垂直方向に中央揃えします。ページ全体の変更前／変更後のスクリーンショットでは、上端を揃えるため、両方のファイルのピクセル単位の高さを同じにしてください。

1. 両方のページを同じビューポートと状態で開きます。
2. 両方のセッションで document.documentElement.scrollHeight を読み取ります。
3. 短い方のページの下部にのみ余白を追加し、両方のスクロール高さが一致したら、両方の --full スクリーンショットを撮影します。

余白は透明でも、キャプチャツールのデフォルトのキャンバス色でもかまいません。ページの上部に余白を追加しないでください。コンポーネントやセクションを比較する場合は、関係のないページコンテンツに余白を追加せず、同じ範囲を指定してキャプチャしてください。

この DOM のみの調整には、生の agent-browser eval を使用してください。このスキルに画像処理の依存関係を追加しないでください。公開前に、生成されたファイルのピクセル単位の寸法が一致していることを確認してください。

書式

比較ごとに --before と --after のペアを 1 組指定します。複数のペアを識別するには、--label を繰り返し指定してください。

node skill/scripts/format.mjs \
  --before captures/desktop-before.png \
  --after captures/desktop-after.png \
  --before captures/mobile-before.png \
  --after captures/mobile-after.png \
  --label Desktop \
  --label Mobile \
  > /tmp/before-and-after.md

変更後のみのプレビューの場合：

node skill/scripts/format.mjs \
  --after captures/new-page.png \
  > /tmp/before-and-after.md

PR で証拠の作成者を明記する場合は、--attribution "<name>" を追加すると、ブロックの先頭に > Before/after by <name> の行が付きます。

画像はテーブル内に表示されます。ローカル動画は、gh --attach でアップロードして最終的な添付 URL を取得できるよう、最初は単独の行に表示されます。gh --attach は <video src> 属性内のローカル参照を書き換えないため、変更前／変更後の動画テーブルでは、以下の 2 段階のワークフローを使用してください。

エビデンスの配置

新しいマーク付きブロックを挿入する前に、既存の PR の説明を読みます。視覚的なエビデンスは上部に配置します。冒頭の短い背景説明の後、既存のプレビューまたはデプロイリンクのセクションがあればその後、Details、Changes、Testing、Notes など、実装の詳細を扱うセクションの前に配置してください。

視覚的なエビデンスは、次の順序で並べます。

1. PR の内容を証明する実際の変更前／変更後のエビデンス、またはプレビューを最初に配置します。
2. 補足形式、別の状態、デモは、主要なエビデンスの後に配置します。
3. PR 自体ではなく、このスキルを実演するものにはデモと明記し、重要な制限事項をその横に記載します。たとえば、動きの滑らかさが重要な場合は、インストール済みの agent-browser レコーダーが現在 10 fps に制限されていることを記載します。

見出しは意味を示す手がかりであり、必須の名称ではありません。アンカーを作るためだけに文章を新たに作成したり書き換えたりしないでください。また、段落、リスト、表、コードブロック、その他の Markdown 構造を分割しないでください。安全な配置場所が明確でない場合は、既存の内容を損なう危険を冒さず、ブロックを末尾に追加します。マーク付きブロックがすでにある場合は、そのブロック全体だけを移動または置き換え、無関係な文章はすべて一字一句そのまま保持します。

公開後、レンダリングされた PR を開き、主要なエビデンスが補足デモより前、かつ実装の詳細より前に表示されていることを確認します。

公開

既存の PR の説明を保持し、このスキルのマーク付きブロックだけを置き換えます。

PR=123
gh pr view "$PR" --json body --jq .body > /tmp/pr-body.md

node skill/scripts/format.mjs \
  --body-file /tmp/pr-body.md \
  --before captures/desktop-before.png \
  --after captures/desktop-after.png \
  > /tmp/pr-body-next.md

ATTACH_ARGS=()
while IFS= read -r file; do
  ATTACH_ARGS+=(--attach "$file")
done < <(
  node skill/scripts/format.mjs \
    --attach-list \
    --before captures/desktop-before.png \
    --after captures/desktop-after.png
)

gh pr edit "$PR" --body-file /tmp/pr-body-next.md "${ATTACH_ARGS[@]}"

フォーマッターと gh は同じディレクトリから実行します。gh --attach はローカルファイルを GitHub にアップロードし、PR 本文内の対応するローカル参照を書き換えます。

公開後、PR の説明を取得または開いて、マーク付きブロック内に ./captures/... への参照が残っていないことと、エビデンスが意図した順序で表示されることを確認します。

動画比較の公開

動画比較は、次の 2 段階で公開します。

1. 通常の独立行形式を使って、ローカル動画を一時的な PR コメントにアップロードし、gh pr comment --attach を実行します。

2. gh api でそのコメントを取得し、変更前／変更後の順に、安定した https://github.com/user-attachments/assets/... の URL を収集します。

3. それらの URL から最終的な HTML テーブルを生成し、マーク付きの PR ブロックを置き換えます。

   node skill/scripts/format.mjs \
     --body-file /tmp/pr-body.md \
     --before-video-url https://github.com/user-attachments/assets/BEFORE_ID \
     --after-video-url https://github.com/user-attachments/assets/AFTER_ID \
     --label "Desktop hero" \
     > /tmp/pr-body-next.md
   
   gh pr edit "$PR" --body-file /tmp/pr-body-next.md
   

4. 一時コメントを削除する前に、編集後の PR 本文を取得します。最終的な URL が両方含まれていることと、ローカル動画へのパスが残っていないことを確認してから、コメントを削除します。

5. レンダリングされた PR を開き、両方の <video> 要素が比較テーブル内にあり、再生可能な準備完了状態になり、コントロールが表示されることを確認します。

URL の抽出、フォーマット、または PR の検証に失敗した場合は、一時コメントを残してアップロード済みの添付ファイルを復旧可能な状態に保ち、最後に成功した段階から再試行します。簡易的な代替手段として、動画を独立行に配置します。

Vercel OIDC トークン、バイパス用シークレット、認証済みのクエリパラメーター、またはブラウザー状態ファイルを含むキャプチャは公開しないでください。

スクリプトの仕様

scripts/format.mjs は、意図的に唯一の同梱スクリプトとして用意されています。このスクリプトは次の処理を行います。

• 既存のローカルメディアをフォーマットします。
• 最終的な GitHub 動画添付 URL を HTML 比較テーブルとしてフォーマットします。
• after のみのメディアに Preview とラベルを付けます。
• 添付ファイルの正確なパス一覧を出力します。
• 他の PR の文章を変更せずに、`` を挿入または置き換えます。

引数はこのスキルのバージョンに合わせて変更されます。公開ライブラリの API ではありません。