用途
capture-pr-visuals 是一个自动化工具，用于为代码仓库中的 Pull Request（PR）生成视觉文档。它能够自动截取运行中应用的页面截图和交互 GIF 动图，帮助评审者直观了解界面变更。该技能主要面向包含前端界面的项目，尤其是使用现代 JavaScript 框架（如 Next.js、Vite、Nuxt、Angular、SvelteKit、Electron、Vue 等）的代码库。
主要能力
- 自动读取项目上下文：优先读取
.chalk/chalk.json获取开发服务器命令、端口、URL、路由列表以及项目框架（如 electron），以确定如何启动服务和抓取哪些页面。 - 回退自动发现：当 chalk.json 缺失或关键字段不全时，技能会读取
package.json，根据依赖推断框架及默认端口（如 next 对应 3000，vite 对应 5173，nuxt 对应 3000，@angular/core 对应 4200 等），并根据框架特性扫描路由（文件路由、React Router、Vue Router、查询参数路由等）。若仍失败，则询问用户提供开发 URL 和路由。 - 分析 PR 变更：通过
git diff main..HEAD --name-only和--stat获取变更文件，并映射到受影响的路由（依赖 chalk.json 的 routes[].src 或架构文档）。例如src/pages/dashboard/映射到/dashboard；src/components/Header.tsx映射到所有页面。若无法映射（如仅后端改动），会提示用户选择要抓取的页面。 - 确保开发服务器运行：使用 curl 检查端口状态，未运行则根据 chalk.json 的 dev.command 在后台启动，并轮询等待就绪。对于 Electron 应用，会检测渲染进程的独立端口。
- 管理 Playwright 与依赖：通过 npx 安装 Chromium；检测 ffmpeg 是否可用，若缺失则仅生成截图（无 GIF），并提示安装方式。
- 生成并执行捕获脚本：在
.chalk/local/capture-script.ts创建临时 TypeScript 脚本，使用 Playwright 打开每个路由，进行全页截图，并录制简短滚动交互的视频（用于生成 GIF）。脚本支持项目特定适配，如 Electron 使用查询参数路径。 - 视频转 GIF：若 ffmpeg 存在，将录制的 webm 视频转换为 10fps、宽度 1280 的循环 GIF，并清理视频目录。
- 提交产物：将截图和 GIF 提交到
.github/pr-screenshots/目录，附带提交信息chore: add PR visual artifacts。 - 输出 PR 引用：生成可直接粘贴到 PR 正文的 Markdown 片段，包含截图和 GIF 的引用，并建议运行
/create-pr创建带嵌入式视觉的 PR。 - 清理：删除临时捕获脚本，并询问是否停止由本技能启动的开发服务器。
使用方式
用户通常通过某种技能调用机制（如 /capture-pr-visuals）触发。技能会依次执行以下步骤：
- 读取项目上下文（chalk.json 或自动发现）；
- 分析 PR 变更并映射路由；
- 确保开发服务器运行；
- 安装 Playwright 和检查 ffmpeg；
- 清理旧截图，生成并运行采集脚本；
- 将视频转为 GIF 并清理；
- 提交产物；
- 输出 Markdown 引用；
- 清理临时文件和可选停止服务器。
使用期间，用户可能需要确认自动检测的 URL 和路由是否正确，或在自动发现失败时提供信息。
适用场景
- 前端项目（尤其是 Next.js、Vite、Nuxt、Angular、SvelteKit、Electron、Vue 等）的 PR 中需要展示界面变更。
- 需要为评审者提供直观的页面截图和交互动图，而无需手动截图或录制。
- 希望把视觉产物纳入版本控制，并在 PR 中直接引用。
限制
- 对于需要登录鉴权的页面，技能会警告用户可能需要手动截图，因为自动脚本无法处理认证。
- 若 ffmpeg 未安装，则无法生成 GIF，只能输出截图。
- 脚本是临时的，不会修改 package.json 或安装永久依赖，始终使用 npx 运行 Playwright 和 tsx。
- 若某个路由捕获失败，会记录警告但继续处理其他路由。
- 截图存放在
.github/pr-screenshots/并提交到当前分支。 - 对于 Electron 应用，需使用渲染进程的独立端口作为 BASE_URL，并使用查询参数路由（如
?home=true）。