為 PR 提供瀏覽器影片證明
錄製一段簡短、可播放的瀏覽器影片來證明 UI 修復，將其附加到 PR 描述中，並驗證即時主體。除非使用者明確要求，否則不要為了錄製而修改應用程式程式碼。
參考執行：PR #723（/automations 擴展長時間運行滾動）。
先決條件
gh已通過驗證，並具有目標儲存庫的推送權限- 工作樹中已安裝 Bun 和儲存庫依賴項（
bun install） - 主機上安裝了 Google Chrome（或 Chromium）
ffmpeg已在 PATH 中（用於 webm → H.264 MP4）- Playwright 安裝在
/tmp下的隔離目錄中（不要將其添加到儲存庫）：
mkdir -p /tmp/<run>/playwright
cd /tmp/<run>/playwright
npm i playwright
npx playwright install ffmpeg
流程
1. 使用 git worktree 隔離
保持主要檢出的乾淨。
cd "$(git rev-parse --show-toplevel)"
git fetch origin main
git worktree add -b <branch> .worktrees/<slug> origin/main # 或附加到修復分支
cd .worktrees/<slug>
僅在該 worktree 內進行伺服器和錄製工作。
2. 先檢查 fixtures 和 UI
在發明資料之前：
- 閱讀被測試的頁面（標籤、展開控制、滾動容器）。
- 檢查相同功能的現有測試 fixtures / factories。
- 優先透過公開的 HTTP API 進行資料播種。僅當沒有任何 API 可以建立所需的資料行時，才在隔離的
NAKAMA_CONFIG_DIR中使用一次性 SQLite 插入作為備用方案（例如，具有巨大output的已完成自動化運行）。
3. 播種確定性的高內容
對於滾動/溢出證明，fixture 必須比窗格高。
- 在開始附近放置一個唯一的頂部標記：
SCROLL_PROOF_MARKER_TOP - 在結尾放置一個唯一的底部標記：
SCROLL_PROOF_MARKER_BOTTOM - 使用足夠的主體文字，使
scrollHeight - clientHeight變大（數千像素）
運行輸出的範例形狀：
# SCROLL_PROOF_MARKER_TOP — 長自動化運行輸出
## 第 1 節
...
## 第 80 節
...
# SCROLL_PROOF_MARKER_BOTTOM — 高內容結束
永遠不要 seed 到操作員真實的 ~/.nakama 資料中。始終在 /tmp/<run>/ 下使用全新的 NAKAMA_CONFIG_DIR。
4. 啟動隔離的本地伺服器
選擇空閒通訊埠。如果已有服務監聽 4310 / 3000 / 3003，不要佔用它們。
RUN=/tmp/<run>
API_PORT=4330
WEB_PORT=3014
mkdir -p "$RUN/nakama-data" "$RUN/logs"
# 在 shell 退出後保持進程存活（普通的 nohup ... & 在這裡會失效）
setsid nohup env NAKAMA_CONFIG_DIR="$RUN/nakama-data" NAKAMA_PORT=$API_PORT \
bun run apps/server/src/index.ts \
>"$RUN/logs/server.log" 2>&1 < /dev/null &
setsid nohup env VITE_API_URL="http://127.0.0.1:${API_PORT}" \
bun run --cwd apps/web dev -- --host 127.0.0.1 --port $WEB_PORT \
>"$RUN/logs/web.log" 2>&1 < /dev/null &
等待直到 curl -sf http://127.0.0.1:$API_PORT/health 成功且 web 來源有回應。全新設定：POST /v1/auth/setup，然後使用 Cookie + X-CSRF-Token + X-Org-Id 建立提供者 / 設定檔 / 自動化（或重複使用 fixtures）。
5. 使用 Playwright 錄製（H.264 MP4）
僅在 /tmp/<run>/ 下建立錄製器。永遠不要提交它。
const browser = await chromium.launch({
channel: "chrome", // 如果已安裝 Chrome
headless: false,
args: ["--disable-gpu"],
});
const context = await browser.newContext({
viewport: { width: 1440, height: 900 },
recordVideo: { dir: rawDir, size: { width: 1440, height: 900 } },
});
規則：
- 驅動被測試的真實 UI 路徑（角色/文字定位器）。
- 使動作可見 — 滑鼠滾輪或逐步滾動，而不是僅一次不可見的跳躍。
- 斷言滾動已移動（
scrollTop差值）且底部標記變得可到達。 - 在
context.close()之前擷取page.video()?.path()。 - 轉換：
ffmpeg -y -i in.webm -c:v libx264 -pix_fmt yuv420p out.mp4 - 在
artifacts/e2e-<id>/下寫入results.json以及前/後截圖。
僅 WebM 不足以在 GitHub 上播放。提供 H.264 + yuv420p。
6. 在聲稱任何內容之前驗證影片
ffprobe -v error -show_entries stream=codec_name,width,height \
-show_entries format=duration -of json out.mp4
# 提取早期/晚期影格並檢查它們
ffmpeg -y -ss 00:00:02 -i out.mp4 -vframes 1 frame-early.png
ffmpeg -y -ss 00:00:08 -i out.mp4 -vframes 1 frame-late.png
僅在以下條件下透過：
- codec 是
h264 - 持續時間足夠長以看到互動
- 早期影格顯示開始狀態（例如頂部標記 / 展開的窗格）
- 晚期影格顯示滾動進度（底部標記或進階的章節）
results.json報告真實的scrollTop差值（或等效的證明指標）
7. 上傳至 GitHub user-attachments
未公開記錄，但 token 驗證適用於圖片/影片，當您具有推送權限時：
TOKEN=$(gh auth token)
REPO_ID=$(gh api repos/<owner>/<repo> --jq .id)
MP4=artifacts/e2e-<id>/<name>.mp4
UPLOAD_JSON=$(curl -sS -X POST \
"https://uploads.github.com/user-attachments/assets?name=$(basename "$MP4")&repository_id=${REPO_ID}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: video/mp4" \
-H "Accept: application/vnd.github+json" \
--data-binary @"${MP4}")
VIDEO_URL=$(printf '%s' "$UPLOAD_JSON" | bun -e 'console.log(JSON.parse(await Bun.stdin.text()).url)')
echo "$VIDEO_URL" # https://github.com/user-attachments/assets/<uuid>
儲存網址。確認對該資產的 HEAD/GET 請求傳回影片內容類型。
8. 更新 PR 描述
添加一個簡短的 瀏覽器證明 區段，包含所顯示的步驟和單獨一行的裸 https://github.com/user-attachments/assets/... 網址（GitHub 會嵌入播放器）。建議透過檔案編寫主體：
gh api repos/<owner>/<repo>/pulls/<n> --method PATCH --input body.json
# 或：gh pr edit <n> --body-file /tmp/pr-body.md
對於主體的其餘部分，請遵循 .agents/skills/adhd-pr-description/SKILL.md。
9. 驗證即時 PR 主體
gh api repos/<owner>/<repo>/pulls/<n> --jq .body | rg 'user-attachments/assets/<uuid>|Browser proof'
在此檢查通過之前，不要報告成功。
範例：自動化擴展運行滾動
- 在修復分支上建立 worktree（或此技能的僅文件分支）。
- 隔離的 API
4330+ web3014，全新的NAKAMA_CONFIG_DIR。 POST /v1/auth/setup→ 提供者 → 建立自動化 Long output digester。- 插入/完成一次運行，其
output為帶有SCROLL_PROOF_MARKER_TOP/SCROLL_PROOF_MARKER_BOTTOM的長 markdown。 - Playwright：開啟
/automations→ 選擇該自動化 → 展開運行 → 用滑鼠滾輪滾動詳細資訊窗格，直到底部標記可見。 - 轉換為 H.264 MP4，檢查影格，上傳，更新 PR 主體，驗證。
清理
- 終止您選擇的通訊埠上的隔離 API/web 監聽器。
- 保留
/tmp/<run>/和設定檔artifacts/e2e-<id>/作為本地證據（不要提交影片或錄製器腳本）。 - 當分支被合併或放棄時刪除 worktree：
git worktree remove .worktrees/<slug>
誠實規則
- 沒有觀看影格或
ffprobe+ 截圖，就不要聲稱有瀏覽器證據。 - 不要貼上您沒有上傳並從即時 PR 主體重新擷取的
user-attachments網址。 - 當要求視覺證據時，不要將通過的單元測試視為影片的替代品。
- 如果滾動沒有移動、標記錯誤或 MP4 為空/損壞 — 請說它失敗了。不要軟化。
- 除非使用者要求產品修復，否則不要修改應用程式程式碼「以使影片更容易」。
- 不要觸碰操作員真實的 Nakama 設定目錄。