采集 / Capture

截图·录像·视口

这一页讲的是「把浏览器里发生的事变成文件」：抓一张截图、录一段工作流视频、把视口缩到手机宽度复现响应式 bug，以及处理挡在中间的 iframe 与弹窗。它们都是输出手段—— 不是用来「找元素、点元素」的。定位和交互请始终走 snapshot + @ref。

⚠️ 硬性规则：截图用于留档，不用于定位

永远不要靠「截图 + 坐标点击」去找或命中一个元素——那是 bug。表单字段、按钮、链接都用 snapshot -i 拿到 @ref，它连 跨源 iframe（内嵌的 Stripe / Google Payments / 结账框）都能穿透。截图只负责把渲染结果存成可复用的图片资产（地图、图表、og 图、视觉回归基线、报告插图）。

截图

screenshot 把当前页面渲染成 PNG。不带路径时存到临时文件并把路径打到 stdout；带路径就写到指定位置。

screenshot.sh

$ chrome-use screenshot                        # 临时路径，打印到 stdout
$ chrome-use screenshot page.png               # 指定路径
$ chrome-use screenshot --full full.png        # 整个滚动高度
$ chrome-use screenshot --annotate map.png     # 编号标注 + 图例，对应 snapshot 的 ref

--full 抓的是整页滚动高度而非只有可视区。 --annotate 是给多模态模型看的：每个标签 [N] 对应快照里的 @eN，方便把一张图和结构化快照对上号。

缩放与裁剪

真实 retina Chrome 的整页截图往往太大、塞不进图片阅读器，所以截图会 自动降采样到最长边 ≤2000px——这样既能被阅读器读取，像素坐标又能和 click x y 对齐。需要时用下面的开关覆盖，或只截某个选择器 / 某块区域：

bash

# 只截某个元素 / 某块区域，存成可复用图片资产
$ chrome-use screenshot "selector" --clip x,y,w,h region.png

# 覆盖默认降采样上限
$ chrome-use screenshot --max-width 1600 wide.png
$ chrome-use screenshot --scale 1 sharp.png

ℹ️ 关于滚动条

无头 Chromium 截图会隐藏原生滚动条，保证输出图一致。启动时传 --hide-scrollbars false 可以保留可见的原生滚动条。

✅ 想点一个 ref 点不到的东西？

不要靠截图找坐标。用 box @ref 拿到元素的 CSS 像素框和 centerX/centerY，直接喂给 click <centerX> <centerY>——全程不需要截图。

录制工作流视频

把一整段自动化录成视频，用于调试、写文档或留证据。 record start 开始录，中间正常跑你的命令， record stop 结束并落盘。

record.sh

$ chrome-use record start demo.webm
$ chrome-use open https://example.com
$ chrome-use snapshot -i
$ chrome-use click @e3
$ chrome-use record stop

还有一个 restart 子命令，等价于「停掉当前录制 + 用新文件开录」：

bash

$ chrome-use record start ./output.webm       # 开始录制到文件
$ chrome-use record stop                     # 停止当前录制
$ chrome-use record restart ./take2.webm    # 停当前 + 用新文件重开

录制的实用做法

目标	做法
让人看清每一步	在关键动作后插 `chrome-use wait 500`，给观看者反应时间
文件名带上下文	`login-flow-2024-01-15.webm`、`checkout-test-run-42.webm`
出错也要保住录像	用 `trap cleanup EXIT` 里调 `chrome-use record stop`
视频 + 关键帧一起留	录制的同时在每一步 `chrome-use screenshot ./stepN.png` 抓帧

ℹ️ 输出格式与限制

录制通过 ffmpeg 把 CDP 截帧编码成视频，所以机器上得装好 ffmpeg。输出格式由文件扩展名决定： .webm 走 VP8（libvpx），其它扩展名（比如 .mp4）走 H.264（libx264）——没有 GIF 导出。录制会给自动化带来轻微开销，长录像很占磁盘，个别无头环境可能缺编解码器。 skill 包里的 references/video-recording.md 有更多录制范例（仓库内文件，文档站不提供跳转）。

Iframe 作用域

iframe 的内容会自动内联进快照，refs 直接透明可用——通常你什么都不用做：

bash

$ chrome-use snapshot -i
# @e3 [Iframe] "payment-frame"
#   @e4 [input] "Card number"
#   @e5 [button] "Pay"

$ chrome-use fill @e4 "4111111111111111"
$ chrome-use click @e5

当你想把快照聚焦到某个 iframe（为了专注，或处理深层嵌套）时，用 frame 切换上下文，处理完再 frame main 切回主框架：

bash

$ chrome-use frame @e3      # 把上下文切进这个 iframe
$ chrome-use snapshot -i
$ chrome-use frame main     # 切回主框架

视口 / 窗口尺寸

要复现依赖宽度的 bug（响应式断点、横向溢出排查、移动端布局），先设视口。这是一个 CDP 虚拟视口（Emulation.setDeviceMetricsOverride）—— 它只改这个标签页的布局视口，不会真的去缩放操作系统窗口。所以无头能用，走扩展中继（extension relay）时也能用，而不会去拉扯用户真实的 Chrome 窗口。

viewport.sh

$ chrome-use viewport 1280 800        # 设宽 x 高（别名：resize）
$ chrome-use viewport 375x812         # WxH 简写
$ chrome-use viewport 375 812 --dpr 3 --mobile   # retina + 移动端模拟
$ chrome-use viewport reset           # 清除覆盖，恢复真实尺寸

典型用途——找出在窄宽度下是什么撑破了布局：

bash

$ chrome-use viewport 375 812
$ chrome-use eval 'document.documentElement.scrollWidth + " vs " + innerWidth'

✅ 等价别名

set viewport <w> <h> [scale] 与 viewport 等价，resize 也是别名—— 怎么顺手怎么写。

弹窗对话框

alert 和 beforeunload 会被自动接受，这样 agent 永远不会被弹窗卡住。需要手动处理 confirm 和 prompt 时：

dialog.sh

$ chrome-use dialog status          # 有没有待处理的弹窗？
$ chrome-use dialog accept           # 接受
$ chrome-use dialog accept "text"    # 接受并填入 prompt 内容
$ chrome-use dialog dismiss          # 取消

ℹ️ 什么时候需要它

大多数流程不用碰 dialog——原生 alert 已自动放行。只有当页面弹出 confirm（「确定要删除吗？」）或 prompt（要求输入一段文本）并阻塞后续操作时，才用 dialog accept / dialog dismiss 明确应答。

截图·录像·视口

截图

缩放与裁剪

录制工作流视频

录制的实用做法

Iframe 作用域

视口 / 窗口尺寸

弹窗对话框

相关页面