Screenshot技能使用说明

何时使用

当任务需要获取桌面应用、浏览器页面、模拟器、区域、窗口或全屏的截图时，特别是用于调试、质量保证、文档编写、发布说明、错误报告、视觉审查或前后对比。

此技能旨在可靠地获取正确的截图，而非事后编辑图像。

工具选择

首先默认采用最原生的捕获路径。当确定性、遮罩、元素捕获或视觉回归比便利性更重要时，转向浏览器原生工具。

核心规则

1. 根据产物选择捕获路径，而非习惯

• 桌面UI截图通常需要操作系统原生工具。
• 网页和Web应用通常需要浏览器原生捕获，而非浏览器窗口的桌面截图。
• 模拟器截图应尽可能来自模拟器工具。
• 当重点是局部时，使用区域、窗口或元素捕获；仅当完整上下文重要时，才使用全屏或整页捕获。

2. 捕获前稳定目标

• 动态页面应在捕获前稳定：等待网络空闲或特定关键元素，然后给字体和过渡效果短暂时间完成。 不要在真实渲染状态存在前截图。
• 对于浏览器捕获，尽可能优先使用明确的就绪状态检测，而非盲目等待。
• 如果页面永远无法真正空闲，则等待所需的确切UI状态，而非追求完美的静止。
• 3. 冻结视口、缩放、缩放比例和主题以确保可复现性

如果视口、缩放级别、主题或设备缩放比例发生变化，截图比较将毫无意义。

• 对于浏览器捕获，在捕获基线或前后对比图像前固定视口。
• 视网膜和高DPI显示屏可能产生比预期更多的像素；决定您需要物理像素还是CSS缩放输出，并保持该选择一致。
• 如果深色/浅色模式重要，请有意识地捕获两者，而非意外混合。
• 4. 捕获最小有用范围

元素、区域或窗口截图通常优于嘈杂的全屏捕获。

• 整页截图对审计和存档有用，但长页面会变得难以阅读和比较。
• 对于浏览器工作，元素截图或裁剪区域通常比整页输出产生更清晰的差异。
• 如果截图作为证据，保留足够的周围上下文，使用户能够理解他们正在查看的内容。
• 5. 捕获前移除噪音

当不稳定UI不是主体时，隐藏或避免：光标、插入符号、通知、聊天小部件、通知、加载动画、时间戳和随机内容。

• 捕获前，遮罩或避免秘密、个人数据、令牌和内部URL。
• Mask or avoid secrets, personal data, tokens, and internal URLs before capture.
• 对于Playwright风格的浏览器截图，当视觉稳定性很重要时，禁用动画、隐藏光标和遮罩等功能值得使用。
• 如果噪声是bug的一部分，就保留它；否则就移除。

6. 使用正确的输出格式

• PNG是截图、UI、代码、终端和文本密集内容的默认格式。
• JPEG用于摄影内容，而非常规截图。
• 当兼容性可接受时，WebP适合用于分享或存储，但如果使用者期望的是纯PNG文件，则不要默认使用它。
• 避免通过JPEG流程重新压缩截图，除非用户明确需要更小的有损输出。

7. 使自动化和CI截图可调试

• 失败时，在重试或继续之前立即保存截图。
• 基准测试使用稳定的文件名，临时或批量截图使用时间戳命名。
• 在CI中，一致的视窗和确定性的状态比原始截图数量更重要。
• 无头运行应优先使用浏览器原生截图，而非尝试截取主机显示。

8. 验证截图确实有用

• 检查重要细节是否可见、清晰且未被裁剪掉。
• 验证标签页、侧边栏、URL、通知或测试数据中没有残留的敏感信息。
• 前后对比应使用相同的视窗、缩放比例、主题和状态。
• 如果一张截图在技术上正确，但对需要它的人来说毫无用处，那它就是失败的。

高价值模式

• macOS：screencapture -x out.png用于静默截图，-i用于交互式选择， -R x,y,w,h用于固定区域。iOS模拟器：
• xcrun simctl io booted screenshot out.pngLinux Wayland：
• grim -g "$(slurp)" out.pnggrim -g "$(slurp)" out.png
• Playwright页面截图：等待目标状态，然后有目的地使用页面、元素、裁剪或全页截图。
• 值得记住的Playwright稳定性功能：固定视口、禁用动画、隐藏光标、敏感区域遮盖，以及稳定的主题/媒体设置。

常见陷阱

• 需要元素或页面截图时，却截取了浏览器窗口截图。
• 在字体、数据或布局转换完成之前进行截图。
• 使用不同视口大小或缩放级别的截图进行比较，并将差异视为有意义。
• 使用JPEG格式截图，导致文本、边缘和代码模糊。
• 让时间戳、光标闪烁、通知或随机数据破坏了视觉对比。
• 忘记Wayland会破坏熟悉的X11截图工具。
• 分享截图时，标签页、侧边栏、URL或测试账户中的秘密信息仍然可见。
• 对超大页面进行全页截图，最终得到难以辨认的证据。

相关技能

安装命令：clawhub install <slug>如果用户确认：

• playwright— 浏览器自动化、DOM交互和网页截图
• image— 截图后的格式、裁剪、压缩和导出决策
• image-edit— 截图后的标注、清理、遮盖和针对性编辑
• documentation— 将截图转化为文档、指南和发布资源
• video— 当流程应被录制而非简化为静态图像时

反馈

• 如果觉得有用：clawhub star screenshot
• 保持更新：clawhub sync