feature-video

功能视频演示

录制展示某项功能的浏览器交互，将截图拼接成 MP4 视频，原生上传到 GitHub，并在 PR 描述中嵌入内嵌视频播放器。

前置条件

• 本地开发服务器正在运行（例如 bin/dev、npm run dev、rails server）
• 已安装 agent-browser CLI（详情请加载 agent-browser 技能）
• 已安装 ffmpeg（用于视频转换）
• gh CLI 已通过身份验证，并具有仓库的推送权限
• Git 仓库位于功能分支上（PR 可选——该技能可以创建草稿 PR，也可以仅录制）
• 一次性完成 GitHub 浏览器身份验证（请参阅步骤 6 的身份验证检查）

主要任务

1. 解析参数并确定 PR

参数： $ARGUMENTS

解析输入：

• 第一个参数：PR 编号、"current"（默认为当前分支的 PR），或现有 .mp4 文件的路径（仅上传的续传模式）
• 第二个参数：基础 URL（默认为 http://localhost:3000）

仅上传的续传模式： 如果第一个参数以 .mp4 结尾且文件存在，则跳过步骤 2-5，直接使用该文件继续步骤 6。从当前分支确定 PR 编号（gh pr view --json number -q '.number'）。

如果提供了明确的 PR 编号，请验证其存在并直接使用：

gh pr view [number] --json number -q '.number'

如果未提供明确的 PR 编号（或指定了 "current"），则检查当前分支是否存在 PR：

gh pr view --json number -q '.number'

如果当前分支不存在 PR，请询问用户如何继续。使用平台的阻塞式提问工具（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）：

No PR found for the current branch.

1. Create a draft PR now and continue (recommended)
2. Record video only -- save locally and upload later when a PR exists
3. Cancel

如果选择选项 1：根据分支名称生成占位标题，创建草稿 PR，然后使用新 PR 编号继续：

gh pr create --draft --title "[branch-name-humanized]" --body "Draft PR for video walkthrough"

如果选择选项 2：设置 RECORD_ONLY=true。继续执行步骤 2-5（录制并编码），跳过步骤 6-7（上传并更新 PR），最后报告本地视频路径和 [RUN_ID]。

仅上传的续传模式： 若要上传之前录制的视频，请将现有视频文件路径作为第一个参数传入（例如，/feature-video .context/compound-engineering/feature-video/1711234567/videos/feature-demo.mp4）。如果第一个参数是 .mp4 文件的路径，则跳过步骤 2-5，直接使用该文件继续步骤 6 并上传。

1b. 验证所需工具

继续之前，请检查所需的 CLI 工具是否已安装。尽早失败并给出清晰提示，避免截图录制完成后才在工作流中途失败：

command -v ffmpeg

command -v agent-browser

command -v gh

如果缺少任何工具，请停止并报告需要安装的工具：

• ffmpeg：macOS 上使用 brew install ffmpeg，或安装对应版本
• agent-browser：加载 agent-browser 技能以查看安装说明
• gh：macOS 上使用 brew install gh，或参阅 https://cli.github.com

所有工具都可用之前，不要继续执行步骤 2。

2. 收集功能上下文

如果有 PR，获取 PR 详情和更改的文件：

gh pr view [number] --json title,body,files,headRefName -q '.'

gh pr view [number] --json files -q '.files[].path'

如果处于仅录制模式（没有 PR），检测默认分支，并根据分支差异推导上下文。在同一个代码块中运行两条命令，以便变量保持有效：

DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name') && git diff --name-only "$DEFAULT_BRANCH"...HEAD && git log --oneline "$DEFAULT_BRANCH"...HEAD

将更改的文件映射到应演示的路由或页面。检查项目的路由配置（例如 routes.rb、next.config.js、app/ 目录结构），以确定哪些 URL 对应更改的文件。

3. 规划视频流程

录制前，先创建镜头列表：

1. 开场镜头：主页或起始位置（2-3 秒）
2. 导航：用户如何找到该功能
3. 功能演示：核心功能（重点）
4. 边缘情况：错误状态、验证等（如适用）
5. 成功状态：操作完成后的结果

录制前，将拟定的流程展示给用户确认。

如平台提供阻塞式提问工具，请使用（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）。否则，请列出带编号的选项，并等待用户回复后再继续：

Proposed Video Flow for PR #[number]: [title]

1. Start at: /[starting-route]
2. Navigate to: /[feature-route]
3. Demonstrate:
   - [Action 1]
   - [Action 2]
   - [Action 3]
4. Show result: [success state]

Estimated duration: ~[X] seconds

1. Start recording
2. Modify the flow (describe changes)
3. Add specific interactions to demonstrate

4. 录制操作演示

生成一个唯一的运行 ID（例如时间戳），并为每次运行创建单独的输出目录。这样可以防止将之前运行时遗留的截图拼接到新视频中。

**重要：**Shell 变量不会在不同代码块之间保留。生成运行 ID 后，请在此工作流的所有后续命令中替换为具体值。例如，如果时间戳是 1711234567，请在下面的所有路径中使用这个字面值——不要依赖 [RUN_ID] 在后续代码块中展开。

date +%s

将输出用作 RUN_ID。使用具体值创建目录：

mkdir -p .context/compound-engineering/feature-video/[RUN_ID]/screenshots
mkdir -p .context/compound-engineering/feature-video/[RUN_ID]/videos

执行规划好的流程，并使用 agent-browser 捕获每个步骤。按顺序为截图编号，以确保帧的顺序正确：

agent-browser open "[base-url]/[start-route]"
agent-browser wait 2000
agent-browser screenshot .context/compound-engineering/feature-video/[RUN_ID]/screenshots/01-start.png

agent-browser snapshot -i
agent-browser click @e1
agent-browser wait 1000
agent-browser screenshot .context/compound-engineering/feature-video/[RUN_ID]/screenshots/02-navigate.png

agent-browser snapshot -i
agent-browser click @e2
agent-browser wait 1000
agent-browser screenshot .context/compound-engineering/feature-video/[RUN_ID]/screenshots/03-feature.png

agent-browser wait 2000
agent-browser screenshot .context/compound-engineering/feature-video/[RUN_ID]/screenshots/04-result.png

5. 创建视频

使用与第 4 步相同的 [RUN_ID] 将截图合成为 MP4：

ffmpeg -y -framerate 0.5 -pattern_type glob -i ".context/compound-engineering/feature-video/[RUN_ID]/screenshots/*.png" \
  -c:v libx264 -pix_fmt yuv420p -vf "scale=1280:-2" \
  ".context/compound-engineering/feature-video/[RUN_ID]/videos/feature-demo.mp4"

注意：

• -framerate 0.5 = 每帧 2 秒。可调整以加快或减慢播放速度。
• -2 用于确保缩放后的高度可被 2 整除（H.264 的要求）。

6. 验证身份并上传到 GitHub

上传后会生成一个 user-attachments/assets/ URL，GitHub 会将其渲染为原生内嵌视频播放器——效果与手动将视频粘贴到 PR 编辑器中相同。

操作方法：关闭任何现有的 agent-browser 会话，启动一个已保存 GitHub 身份验证信息的 Chrome 引擎会话，导航到 PR 页面，将视频文件设为评论表单中的隐藏文件输入项，等待 GitHub 处理上传，提取生成的 URL，然后清空文本框但不提交。

检查现有会话

首先，检查是否已存在保存的 GitHub 会话：

agent-browser close
agent-browser --engine chrome --session-name github open https://github.com/settings/profile
agent-browser get title

如果页面标题包含用户的 GitHub 用户名或“Profile”，则会话仍然有效——跳到下面的“上传视频”。如果页面重定向到登录页面，则会话已过期或从未创建——继续进行“身份验证设置”。

身份验证设置（一次性）

建立经过身份验证的 GitHub 会话。只需设置一次——会话 Cookie 会通过 --session-name 标志在不同运行之间保留。

关闭当前会话，并在带界面的 Chrome 窗口中打开 GitHub 登录页面：

agent-browser close
agent-browser --engine chrome --headed --session-name github open https://github.com/login

用户必须在浏览器窗口中手动登录（支持 2FA、SSO、OAuth 等任意登录方式）。请使用平台的阻塞式提问工具（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）。否则，请显示消息并等待用户回复后再继续：

GitHub login required for video upload.

A Chrome window has opened to github.com/login. Please log in manually
(this handles 2FA/SSO/OAuth automatically). Reply when done.

登录后，验证会话是否正常：

agent-browser open https://github.com/settings/profile

如果个人资料页面成功加载，则表示身份验证已确认。github 会话现已保存，可重复使用。

上传视频

前往 PR 页面并滚动到评论表单：

agent-browser open "https://github.com/[owner]/[repo]/pull/[number]"
agent-browser scroll down 5000

上传前保存现有文本框内容（评论框中可能有尚未发送的草稿）：

agent-browser eval "document.getElementById('new_comment_field').value"

将此值保存为 SAVED_TEXTAREA。如果该值非空，提取上传 URL 后会恢复它。

通过隐藏的文件输入框上传视频。如果是仅上传恢复模式，则使用调用方提供的 .mp4 路径；否则使用当前运行中编码后的视频：

agent-browser upload '#fc-new_comment_field' [VIDEO_FILE_PATH]

其中 [VIDEO_FILE_PATH] 可以是：

• 作为第一个参数传入的 .mp4 路径（仅上传恢复模式）
• .context/compound-engineering/feature-video/[RUN_ID]/videos/feature-demo.mp4（常规录制流程）

等待 GitHub 处理上传（通常需要 3-5 秒），然后读取文本框的值：

agent-browser wait 5000
agent-browser eval "document.getElementById('new_comment_field').value"

验证提取出的 URL。 该值必须包含 user-attachments/assets/，以确认原生上传成功。如果文本框为空、仅包含占位文本，或者 URL 不匹配，请勿继续执行第 7 步。请改为：

1. 检查 agent-browser get url——如果显示 github.com/login，说明会话已过期。请重新进行身份验证设置。
2. 如果仍在 PR 页面，再等待 5 秒并重新读取文本框（GitHub 处理可能较慢）。
3. 如果重试后验证仍然失败，请报告失败情况以及本地视频路径，以便用户手动上传。

恢复原始文本框内容（如果原本为空，则清空文本框）。JSON 编码的字符串也是有效的 JavaScript 字符串字面量，因此可以直接赋值，无需使用 JSON.parse：

agent-browser eval "const ta = document.getElementById('new_comment_field'); ta.value = [SAVED_TEXTAREA_AS_JS_STRING]; ta.dispatchEvent(new Event('input', { bubbles: true }))"

准备该值的方法：取 SAVED_TEXTAREA 字符串，并将其转换为 JS 字符串字面量——转义反斜杠、双引号和换行符（例如，"text with \"quotes\" and\nnewlines"）。如果 SAVED_TEXTAREA 为空，则使用 ""。结果会直接嵌入赋值语句右侧——无需调用 JSON.parse。

7. 更新 PR 描述

获取当前 PR 正文：

gh pr view [number] --json body -q '.body'

附加一个 Demo 部分（或替换已有部分）。将视频 URL 单独放在一行时，会以内嵌播放器的形式显示：

## Demo

https://github.com/user-attachments/assets/[uuid]

*Automated video walkthrough*

更新 PR：

gh pr edit [number] --body "[updated body with demo section]"

8. 清理

删除临时文件前请先询问用户。如果用户确认，只清理当前运行的临时目录（其他运行可能仍在进行或等待上传）。

如果视频已成功上传，删除整个运行目录：

rm -r .context/compound-engineering/feature-video/[RUN_ID]

如果处于仅录制模式或上传失败，只删除截图，保留视频，以便用户稍后上传：

rm -r .context/compound-engineering/feature-video/[RUN_ID]/screenshots

提供完成情况摘要：

Feature Video Complete

PR: #[number] - [title]
Video: [VIDEO_URL]

Shots captured:
1. [description]
2. [description]
3. [description]
4. [description]

PR description updated with demo section.

使用示例

# Record video for current branch's PR
/feature-video

# Record video for specific PR
/feature-video 847

# Record with custom base URL
/feature-video 847 http://localhost:5000

# Record for staging environment
/feature-video current https://staging.example.com

提示

• 保持简短：PR 演示时长以 10-30 秒为宜。
• 聚焦改动：不要包含无关的 UI。
• 展示前后对比：如果是在修复 bug，请先展示故障状态（如果可能）。
• 当 GitHub 使 Cookie 失效时，--session-name github 会话就会过期（通常需要数周）。如果上传失败并跳转到登录页面，请重新进行身份验证设置。
• GitHub DOM 选择器（#fc-new_comment_field、#new_comment_field）可能会随 GitHub 更新 UI 而改变。如果上传悄然失败，请检查 PR 页面，确认选择器是否已更新。

故障排查

症状	原因	解决方法
ffmpeg: command not found	未安装 ffmpeg	通过 brew install ffmpeg（macOS）或其他等效方式安装
agent-browser: command not found	未安装 agent-browser	加载 agent-browser 技能，查看安装说明
上传后等待结束，文本区域仍为空	会话已过期，或 GitHub 处理缓慢	检查会话是否有效（第 6 步的身份验证检查）。如果有效，则延长等待时间并重试。
文本区域为空，URL 为 github.com/login	会话已过期	重新进行身份验证设置（第 6 步）
gh pr view 失败	当前分支没有 PR	第 1 步会处理此情况——选择创建草稿 PR，或使用仅记录模式
视频文件过大，无法上传	超出 GitHub 的 10MB（免费）或 100MB（付费）限制	重新编码：降低帧率（-framerate 0.33）、降低分辨率（scale=960:-2），或提高 CRF（-crf 28）
上传 URL 不包含 user-attachments/assets/	上传方式错误，或 GitHub 有所更改	检查 PR 页面，确认文件输入选择器仍然正确