用途
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
分步流程
-
构建 Storybook:
make storybook-build,在仓库根目录生成storybook-static/。 -
启动静态服务器:捕获脚本期望 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。
- 运行捕获脚本:
bun run scripts/capture-readme-screenshots.ts --storybook-url http://localhost:6006
脚本行为:顺序遍历全部 7 个故事;为每个故事打开全新的 Playwright 页面;等待 networkidle 加 2 秒稳定;若定义了 playInteraction 则执行(对不稳定交互最多重试 3 次);捕获整页 PNG,再通过 Sharp 转换为 WebP;写入 docs/img/<outputFile>。
- 处理失败:含
playInteraction的故事(GitStatusPopover、ContextManagementDialog)在顺序负载下可能因 UI 时序而不稳定。脚本对每个最多重试 3 次。若持续失败:
# 重试单个失败的故事
bun run scripts/capture-readme-screenshots.ts --story GitStatusPopover
bun run scripts/capture-readme-screenshots.ts --story ContextManagementDialog
- 验证并提交:
# 检查全部 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"
适用场景
- 任一
Docs/README Screenshots故事被标记出视觉变化。 App.readmeScreenshots.stories.tsx或mockFactory.ts中的故事数据变更。- 影响截图故事视觉外观的 UI 组件变更。
- 用户明确要求刷新 README 图片。
- 在 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开始。