SuperAPI AI 工具集

ui-pr-recording

编程与开发

查看项目

更新于 11-08 03:47

技能介绍

该技能用于在创建 UI 功能 PR 时生成功能运行证据,作为 PR 检查清单的一部分。需求记录在 ADR:2026-10-10-ui-prs-require-docker-screen-recordings 中。

一、适用范围与完成标准 需检查任务/关联 issue 与 PR 基线的差异。当 PR 实现或扩展 UI 功能,或属于该功能的 UI 相关任务/子任务时适用。独立缺陷修复、重构、样式、本地化、文档、测试及仅后端工作可使用“不适用 — <原因>”。分类依据任务及其行为,而非仅变更路径或标签;交付 UI 功能一部分的样式任务仍适用。此步骤在 PR 创建期间运行,不在实现或独立审查时自动运行;用户可显式请求对任意变更录制。合格 PR 应包含可播放的 GitHub 托管视频、录制的 commit、Docker 启动/健康证据、示例数据设置以及展示的步骤和结果。截图仅作补充,本地路径、测试跟踪、终端录制、仅 mock UI 或 TODO 不满足要求。必要的自动化测试仍为独立检查。 从 pr-checklist 第 5 步调用时,仅完成第 1–3 节并返回已验证的本地视频路径和证据;第 4 节在第 7 步运行,捕获不得创建或编辑 PR。

二、在 Docker 中运行 PR 构建 使用 test-locally 获取前置条件与既有构建流程。构建已提交的 PR 代码(含 UI),记录 git rev-parse HEAD。不得使用已发布镜像或跳过构建,除非验证现有产物包含该代码。 先检查 docker ps 与 Compose 配置。本地运行器即使 -r false 也会停止默认开发栈,默认 -r true 会删除数据库文件。若服务被其他任务占用,使用隔离的 Compose 栈,采用不同容器名、主机端口、网络和卷;仅改项目名不够,因为基础 Compose 文件固定了名称、端口、子网和数据库绑定挂载。不得停止其他任务栈或删除其数据。 默认开发栈可用时,从仓库根目录执行: source env/bin/activate make generate ./docker/run_local_docker.sh -m ui -d mysql -s false -i true -r false docker compose -f docker/development/docker-compose.yml ps curl --fail --silent --show-error http://localhost:8585/api/v1/system/version 验证服务器修订版与记录的构建一致,且服务器、数据库和搜索服务健康。隔离栈使用其配置的 URL/Compose 文件。录制和验证期间保持 Docker 运行,报告最终状态,不得隐式拆除。运行器通过摄取加载仓库示例数据;需等待演示所需数据并在 UI/API 中验证,仅启动成功不证明摄取成功。也可向隔离栈摄取仓库示例数据,并通过 API 为变更流程创建小型合成夹具;记录设置命令/夹具名称及示例加载失败。影响演示的失败须在录制前修复。

三、捕获变更流程 使用可用的浏览器录制工具或 UI 项目已安装的 Playwright,确认能生成实际视频,仅截图工具不满足。使用 Playwright 时,显式设置 viewport 与 recordVideo.size 为相同尺寸,桌面流程从 1920×1080 开始;未设显式视频尺寸时 Playwright 会缩放至 800×800。保留 page.video(),在读取/保存视频前等待 context 关闭。若复用登录状态且认证使用 IndexedDB,需在 storageState 中包含它;认证文件与令牌不得进入产物。 录制完整流程前先检查短样本。选择适合功能的视口,确保小标签在审阅尺寸下清晰;仅增加像素不能解决字太小。需要更清晰捕获或光标移动时,可考虑原生录制器:OBS Studio 适合以原生分辨率录制浏览器窗口,Indistinguishable 预设偏向质量;Screen Studio(macOS)可添加聚焦缩放和光标/点击强调,支持最高 4K 60fps 的 MP4 导出。这些为可选捕获选择,非必需依赖或购买。缩放时保持操作和结果可见。以目标分辨率/帧率捕获,不要上采样或插值已有片段;重新编码无法恢复捕获时丢失的细节。 展示导航到功能、操作及在 Docker 服务器上的可见结果。对于偏好设置,展示两种状态及切回。变更影响持久化、权限或错误行为时需包含。使用 UI/API 断言验证结果,而非将点击序列完成视为成功;使用真实服务器响应,而非路由 mock。保持片段聚焦、文本可读;状态变化不明显时字幕有用。使用合成示例数据录制,省略凭据、令牌及无关浏览器内容。产物保存在受跟踪源文件之外。后续 UI/运行时变更后重新构建并录制。文档或仅测试提交若演示的运行时代码未变,可复用证据,但须保留实际录制的 SHA 并在描述中说明。

四、验证视频 打开成品片段,检查可播放、覆盖所有声称状态、结果可读且对话框未被裁剪。检查时长/文件大小,查看开头、变更状态和结尾的帧。优先 H.264 MP4 以兼容浏览器;GitHub 附件也支持 MOV 和 WebM。上传被拒的超大文件可压缩或拆分,但不得隐藏相关行为。保留原始捕获;需转换 MP4 时从该源编码一次。FFmpeg libx264 的质量导向起点为 CRF 18 和 slow 预设,保留源尺寸与帧率: ffmpeg -n -i recording.webm -c:v libx264 -preset slow -crf 18
-pix_fmt yuv420p -c:a aac -movflags +faststart recording.mp4 选择更小导出前检查结果;在上传版本中也检查小字、移动/滚动区域和字幕;更高码率或更大文件不是可读性证明。

五、在 PR-checklist 第 7 步上传 仅在发布步骤、创建/更新已授权时运行本节。使用第 6 步的完整正文文件,包含证据和本地视频引用。第 7 步负责创建/编辑命令,不得从此技能创建第二个 PR。无上传授权的独立捕获请求以已验证的本地产物结束。 检查 gh pr create --help 或 gh pr edit --help 的 --attach。提供与正文引用相同的视频路径,CLI 会替换为上传的视频 URL。若 CLI 无此标志,使用已认证的 GitHub 浏览器编辑器的附件控件。检查保存的描述并确认上传视频可从 GitHub 加载。上传可能部分成功即使 CLI 非零退出;重试前读取当前 PR,避免重复附件或覆盖更新描述。后续更新从已保存的 GitHub 正文开始,保留其上传 URL,而非复用上传前的本地草稿。在标记新 PR 就绪前完成录制和其他创建检查。不得创建 release 或提交视频文件来托管。 若 Docker、录制或上传受阻,完成独立工作并保持 PR 草稿,报告确切失败、本地产物路径(若创建)和剩余步骤。若认证上传需用户帮助,提供成品视频和准备好的描述供附件;不得声称本地文件已上传。此技能不为只读审查增加单独门禁。