SuperAPI AI 工具集

generate-readme-screenshots

编程与开发

查看项目

更新于 10-16 22:15

技能介绍

用途

README 中的截图(位于 docs/img/*.webp)并非手动截取,而是由 src/browser/stories/App.readmeScreenshots.stories.tsx 中定义的 Storybook 故事确定性地生成。当这些故事发生视觉变化(在评审或本地检查中发现)时,必须重新生成对应的 WebP 资源并提交。

主要能力

  • 从 Storybook 故事批量生成 README 截图,输出为 WebP 格式。
  • 支持一次性捕获全部 7 个故事,也支持通过 --story 参数捕获单个故事。
  • 对包含交互的故事(如打开对话框、切换模式)支持 playInteraction,并带有最多 3 次重试以应对不稳定的交互。
  • 使用 Playwright 进行无头浏览器截图,使用 Sharp 进行图像处理(缩放、WebP 转换)。

分辨率与输出

参数 值
CSS 视口 1900 × 1188
设备像素比(DPR) 2
原生捕获分辨率 3800 × 2376
输出格式 WebP(质量 90,lanczos3 重采样)
输出目录 docs/img/

故事 → 截图映射

故事导出名 输出文件 是否含交互
CodeReview code-review.webp 否
AgentStatusSidebar agent-status.webp 否
GitStatusPopover git-status.webp 是(打开对话框 + 切换模式)
PlanMermaidWithCosts plan-mermaid.webp 否
CostsTabRich costs-tab.webp 否
ContextManagementDialog context-management.webp 是(打开设置对话框)
MobileServerMode mobile-server-mode.webp 否

关键文件

文件 作用
src/browser/stories/App.readmeScreenshots.stories.tsx 故事定义与模拟数据
scripts/capture-readme-screenshots.ts Playwright + Sharp 捕获流水线
src/browser/stories/mockFactory.ts 确定性模拟数据工厂
src/browser/stories/mocks/orpc.ts 模拟 ORPC 后端(终端、git、密钥)
docs/img/*.webp 输出截图资源

使用方式

前置依赖

捕获流水线需要以下工具。若任一缺失,应立即停止并向用户报告完整问题,不要静默跳过或产出降级结果。

依赖 用途 检查命令
bun 脚本运行时 bun --version
playwright 无头浏览器自动化 bun -e "require('playwright')"
sharp 图像处理(缩放、WebP) bun -e "require('sharp')"
python3 Storybook 构建的静态文件服务器 which python3

依赖验证:

bun --version && \
bun -e "require('playwright'); require('sharp'); console.log('deps ok')" && \
which python3

若任一失败:不要继续生成截图;向用户报告确切的失败命令与错误;建议修复方式:缺少 playwright 时执行 bun add -d playwright && bunx playwright install chromium;缺少 sharp 时执行 bun add -d sharp;缺少 python3 时建议安装 Python 或使用替代静态服务器;缺少 bun 时属于硬性要求,整个仓库使用 bun。

快速参考

# 1. 构建 Storybook
make storybook-build

# 2. 将静态构建作为后台 bash 任务提供服务(见“启动静态服务器”)
python3 -m http.server 6006 -d storybook-static

# 3. 捕获全部截图(3800px,WebP 质量 90)
bun run scripts/capture-readme-screenshots.ts

# 4. 捕获单个故事
bun run scripts/capture-readme-screenshots.ts --story CodeReview

分步流程

  1. 构建 Storybook:make storybook-build,在仓库根目录生成 storybook-static/。

  2. 启动静态服务器:捕获脚本期望 Storybook 位于 http://localhost:6006。使用后台 bash 任务(而非 nohup 或前台 &)以保证服务器存活:

# 作为后台 bash 任务,约 10 分钟生命周期
python3 -m http.server 6006 -d storybook-static

验证服务器可达:

bun -e "const r = await fetch('http://localhost:6006'); console.log(r.status)"

注意:curl 可能成功而 bun fetch 失败(DNS 解析不同)。始终使用 bun -e "fetch(...)" 验证,因为捕获脚本使用 bun 的 fetch。

  1. 运行捕获脚本:
bun run scripts/capture-readme-screenshots.ts --storybook-url http://localhost:6006

脚本行为:顺序遍历全部 7 个故事;为每个故事打开全新的 Playwright 页面;等待 networkidle 加 2 秒稳定;若定义了 playInteraction 则执行(对不稳定交互最多重试 3 次);捕获整页 PNG,再通过 Sharp 转换为 WebP;写入 docs/img/<outputFile>。

  1. 处理失败:含 playInteraction 的故事(GitStatusPopover、ContextManagementDialog)在顺序负载下可能因 UI 时序而不稳定。脚本对每个最多重试 3 次。若持续失败:
# 重试单个失败的故事
bun run scripts/capture-readme-screenshots.ts --story GitStatusPopover
bun run scripts/capture-readme-screenshots.ts --story ContextManagementDialog
  1. 验证并提交:
# 检查全部 7 个生成文件是否存在
for f in code-review agent-status git-status plan-mermaid costs-tab context-management mobile-server-mode; do
  bun -e "const s = require('sharp'); const m = await s('docs/img/${f}.webp').metadata(); console.log('${f}:', m.width + 'x' + m.height)"
done

# 暂存并提交
git add docs/img/*.webp
git commit -m "regenerate README screenshots at 3800px"

适用场景

  1. 任一 Docs/README Screenshots 故事被标记出视觉变化。
  2. App.readmeScreenshots.stories.tsx 或 mockFactory.ts 中的故事数据变更。
  3. 影响截图故事视觉外观的 UI 组件变更。
  4. 用户明确要求刷新 README 图片。
  5. 在 main 上 rebase 后,上游变更影响了共享 UI 组件。

限制与故障排查

  • “Storybook is not running”:捕获脚本在开始前会验证 Storybook 可达。确保 make storybook-build 成功完成、静态服务器运行在 6006 端口,并用 bun -e "fetch('http://localhost:6006')"(而非仅 curl)验证。
  • 交互故事超时:Radix popover/tooltip 会 portal 到 document.body,需要精确的悬停时序。重试逻辑可处理大多数情况。若持续失败:单独运行失败的故事(--story <Name>);检查该故事的模拟数据或选择器是否与实际组件漂移。
  • 图像看起来不对(被裁剪、错位):检查 capture-readme-screenshots.ts 中的视口常量(1900×1188,DPR 2);截图使用仅视口捕获(非 fullPage),若内容溢出视口,应调整故事布局而非捕获脚本;StoryDef 接口支持 postProcess 钩子用于自定义 Sharp 流水线(如未来故事需要裁剪/合成),但当前没有故事使用它。
  • 为什么没有 ProductHero 截图故事:这是有意为之。README 现在使用 xum-demo.gif 作为主视觉媒体。README 截图流水线仅覆盖 README 中保留的 7 个生成的 WebP 资源,从 code-review.webp 开始。