PR的浏览器视频证据
录制一个简短的可播放浏览器视频，证明UI修复有效，将其附加到PR描述中，并验证最终输出。除非用户明确要求，否则不要修改应用程序代码进行录制。
参考执行：PR #723（/automations展开后长滚动）。
前置条件
- 已认证
gh，并对目标仓库具有推送权限 - 在工作树中安装Bun及仓库依赖项（
bun install） - 主机上安装Google Chrome（或Chromium）
ffmpeg已加入PATH（用于webm转H.264 MP4）- 在
/tmp下的隔离目录中安装Playwright（不要将其添加到仓库）：
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>
仅在该工作树中进行服务器和录制操作。
2. 首先检查fixtures和UI
在创建数据之前：
- 阅读被测页面（标签、展开控件、滚动容器）。
- 检查同一功能的现有测试fixtures/工厂。
- 优先通过公共HTTP API进行数据填充。仅在无法通过API创建所需行的情况下（例如，已完成的大型输出自动化运行），才在隔离的
NAKAMA_CONFIG_DIR中执行一次性SQLite插入。
3. 填充确定性的高内容
对于滚动/溢出证明，fixture必须比面板更高。
- 在开头附近放置一个唯一的顶部标记：
SCROLL_PROOF_MARKER_TOP - 在末尾放置一个唯一的底部标记：
SCROLL_PROOF_MARKER_BOTTOM - 使用足够的正文文本，使
scrollHeight - clientHeight足够大（数千像素）
运行输出的示例格式：
# SCROLL_PROOF_MARKER_TOP — 长时间自动化运行输出
## 第1节
...
## 第80节
...
# SCROLL_PROOF_MARKER_BOTTOM — 高内容结束
切勿填充到操作员的真实~/.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
仅当满足以下条件时才算通过：
- 编码器为
h264 - 时长足够长以观察交互
- 早期帧显示开始状态（例如顶部标记/展开的面板）
- 晚期帧显示滚动进度（底部标记或更靠后的部分）
results.json报告真实的scrollTop增量（或等效的证明指标）
7. 上传至GitHub用户附件
虽未公开文档化，但拥有推送权限时，基于令牌认证可用于图片/视频：
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>
保存该URL。确认对该资源的HEAD/GET请求返回视频内容类型。
8. 更新PR描述
添加简短的Browser proof部分，包含所展示的步骤，并在单独一行放置裸的https://github.com/user-attachments/assets/... URL（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'
在检查通过之前，不要报告成功。
示例：自动化展开运行滚动
- 在修复分支（或仅用于此技能的文档分支）上创建工作树。
- 隔离的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>/作为本地证据（不要提交视频或录制脚本）。 - 当分支被合并或废弃时，移除工作树：
git worktree remove .worktrees/<slug>
诚实规则
- 未观看帧或未使用
ffprobe+截图之前，切勿声称拥有浏览器证据。 - 切勿粘贴未上传且未从实时PR正文中重新获取的
user-attachmentsURL。 - 当要求视觉证明时，切勿将绿色单元测试视为视频的替代品。
- 如果滚动未移动、标记错误、或MP4为空/损坏——则报告失败。不要软化措辞。
- 除非用户要求产品修复，否则不要“为了视频更容易”而修改应用程序代码。
- 不要触碰操作员的真实Nakama配置目录。