关于 update-screenshots
update-screenshots 是用于处理组件截图 CI 哈希不匹配的技能，适用于维护 VS Code 组件测试的开发者。它指导从 CI 获取哈希、核对图像差异，并按生成文件格式更新基准。
主要功能
- 01从 CI 获取预期哈希
- 02比较新旧截图差异
- 03判断界面变化是否符合预期
- 04更新截图哈希基准文件
- 05区分截图差异报告与阻塞错误
适用场景
- 01组件截图哈希不匹配导致 CI 失败
- 02确认截图变化是预期布局调整还是回归
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/update-screenshots确认已加载。
详细介绍
从 CI 更新组件截图
截图图像不存储在代码库中，而是保存在外部服务（hediet-screenshots.azurewebsites.net）中，并以提交 SHA 为键。不过，部分测试夹具的哈希值固定记录在 test/componentFixtures/blocks-ci-screenshots.md 中，而且该文件会提交到代码库。哈希值发生变化时，CI 会失败，你必须更新该文件。
两种不同的结果，只有一种会阻塞
.github/workflows/component-fixtures.yml 中的 Screenshots & Tests 作业会产生两项独立结果：
| 结果 | 是否阻塞？ | 操作 |
|---|---|---|
| 截图差异报告（包含前后图像的 PR 评论） | 否 — 仅供参考 | 检查视觉效果。无需提交任何内容。 |
| blocks-ci 哈希不匹配 | 是 — 检查失败 | 更新 blocks-ci-screenshots.md 并提交。 |
测试夹具通过 labels: { kind: 'screenshot', blocksCi: true } 加入阻塞检查。只有这些测试夹具会出现在 blocks-ci-screenshots.md 中。
失败信息如下：
##[error]blocks-ci screenshot hashes do not match committed file. See PR comment or job summary for the updated content.
第 1 步：从 CI 获取预期哈希值
切勿在本地重新生成哈希值。 这些哈希值是对在
ubuntu-latest上生成的 PNG 字节进行计算得出的。在 macOS 或 Windows 上渲染会产生不同的字节，因此哈希值也会不同，本地生成的值会导致 CI 失败。请始终从 CI 作业中复制这些值。
三个位置包含相同内容 — 选择方便的一个：
- 标题为“blocks-ci screenshots changed”的 PR 评论（仅适用于非 fork PR）— 包含完整的更新后文件和补丁。
- 作业摘要，其中包含相同的正文，也是 fork PR 唯一能收到的内容。
- 作业日志，其最后一步会输出统一差异：
gh api repos/microsoft/vscode/actions/jobs/<JOB_ID>/logs > "$TMPDIR/ci-job-log.txt"
grep -n '##\[error\]' "$TMPDIR/ci-job-log.txt"
使用以下命令查找失败的作业 ID：
gh pr checks <PR> --json name,link,bucket --jq '.[] | select(.name == "Screenshots & Tests")'
第 2 步：接受更改前，确认更改是有意为之
此检查旨在捕获非预期的布局回归，因此，不查看图像就接受新哈希值会违背其目的。图像可通过哈希值公开获取，因此请下载旧版本（已提交）和新版本（来自 CI）并进行比较：
curl -sL -o old.png "https://hediet-screenshots.azurewebsites.net/images/<OLD_HASH>"
curl -sL -o new.png "https://hediet-screenshots.azurewebsites.net/images/<NEW_HASH>"
然后查看图像，并定位具体变化，不要只凭肉眼检查完整截图 — 差异往往只有一两个像素：
python3 -c "
from PIL import Image, ImageChops
a = Image.open('old.png').convert('RGB'); b = Image.open('new.png').convert('RGB')
print('diff bbox:', ImageChops.difference(a, b).getbbox())
"
确认差异符合 PR 的预期。如果测试夹具与此次更改无关，或者偏移超过预期，请将其视为回归问题，并修复代码，而不是修改哈希值。
第 3 步：应用更改并提交
仅编辑 test/componentFixtures/blocks-ci-screenshots.md 中发生变化的行，将图像 URL 中的旧哈希值替换为新哈希值：
#### editor/inlineChatZoneWidget/InlineChatZoneWidget/Dark
该文件由 build/lib/screenshotBlocksCi.ts 生成，并按逐字节比较，因此请保留 `` 标题、#### <fixtureId> / 图像链接配对、条目之间的空行，以及 fixtureId 的排序。确认你的编辑与 CI 报告的差异完全相反：
git diff test/componentFixtures/blocks-ci-screenshots.md
然后提交并推送。检查会重新运行，且应当通过；合并后，main 上的哈希值会成为新的基准。
深入调查
一次运行的原始截图和清单会作为构建产物上传：
gh run download <RUN_ID> --name screenshots --dir .tmp/screenshots
manifest.json 会将每个 fixtureId 映射到其 imageHash 和任何渲染错误。
同一作业中的相关失败
如果测试夹具渲染失败（Fail if fixtures had errors），或者 Playwright 测试夹具测试失败，检查也会失败。这些都是真正的错误 — 更新哈希值无济于事。请在日志中查找 ::error::<fixtureId>:，如果测试失败，则下载 playwright-test-results 构建产物。