BrowserSkill截图指南：视口、元素、整页3种模式与参数速查表
【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI + extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill
BrowserSkill是一个让 AI 智能体直接操控你"已登录真实浏览器"的浏览器自动化工具，由命令行 CLI（bsk）+ 浏览器扩展组成。其中的BrowserSkill 截图能力（bsk screenshot命令）支持视口、元素、整页 3 种模式，一条命令即可导出 PNG。本文给出这 3 种模式的完整用法与参数速查表，帮助你 5 分钟上手。
一、开始之前：确认浏览器已连接
使用截图功能前，需要安装 CLI 并让浏览器扩展连上本地 daemon。连接成功后，扩展 popup 会显示"已连接 / READY"状态，如官方商店页面所示：
快速检查三步：
bsk doctor # 诊断环境，按提示修复 bsk status # 查看 daemon 状态 bsk session list # 查看可用会话（截图命令需要 --session）💡 所有截图命令都需要一个处于活跃状态的 session ID，这是最常用的参数。
二、3 种截图模式快速上手
| 模式 | 命令要点 | 适用场景 |
|---|---|---|
| 🖥️ 视口截图 | 不带额外参数 | 截取当前可见区域，最简单、速度最快 |
| 🎯 元素截图 | --ref @eN | 裁剪截取指定 DOM 元素或 Canvas 区域 |
| 📜 整页截图 | --full-page | 自动从顶部滚动到底部，拼接完整长图 |
三种模式的典型命令：
bsk screenshot --session <id> --out viewport.png bsk screenshot --session <id> --ref @e3 --out element.png --json bsk screenshot --session <id> --full-page --out page.png- 视口模式：省略
--out时，文件自动保存到临时目录（$TMPDIR/bsk-screenshot-<时间戳>.png）。 - 元素模式：
--ref的值（如@e3）来自最近一次bsk observe或bsk snapshot分配的引用号；--json会额外输出图片宽、高、字节数。 - 整页模式：命令会滚动页面并自动恢复原来的滚动位置和样式，不会打乱你正在看的页面。
三、参数速查表
以下对照 screenshot.rs 中的 CLI 定义整理：
| 参数 | 模式 | 默认值 | 说明 |
|---|---|---|---|
--session | 全部 | 必填 | 会话 ID，必须处于活跃状态 |
--tab-id | 全部 | Agent Window 当前活动标签页 | 指定目标标签页，不改变当前选中状态 |
--ref | 元素 | 无 | @eN引用，裁剪到对应 DOM 元素或 Canvas 区域 |
--full-page | 整页 | 关闭 | 滚动整页并拼接长图，与--ref互斥 |
--scope | 整页 | follow | follow跟随追加内容；current只截初始文档高度 |
--timeout | 整页 | 2m | 抓取与编码超时，支持30s、5m等写法 |
--out | 全部 | 临时目录 | 输出 PNG 路径，已存在则覆盖 |
全局参数同样适用：--json（输出机器可读 JSON）、--quiet、-v（详细日志）。
--scope怎么选？
follow（默认）：页面持续追加内容（如信息流、聊天窗口）时，会一直滚动到"没有新内容"为止。current：在初始文档高度处停下。即使底部还显示加载指示器也只截已加载部分——此时应如实说明"只截取了当前已加载范围"，而不是宣称截全了整个列表。
四、整页截图的注意事项
整页模式功能强大，但有几条限制值得提前知道（详见 SKILL.md 的 Screenshots 章节）：
- 需要活动标签页：整页截图要求目标标签页处于活动状态；普通视口截图则支持后台标签页（配合
--tab-id）。 - 不支持的页面类型：浏览器内部页面、应用商店页面、嵌套滚动面板、虚拟滚动列表。
- 失败不产生残缺文件：捕获采用分块传输 + 原子写入（write_full_page 实现），中断后不会留下半截 PNG。
loading_stalled报错：表示页面底部 30 秒没有新增高度但一直显示加载中，此时加大--timeout也没用。- 保持标签页可见：
page_hidden属于环境中断；user_cancelled表示用户手动停止了捕获。
五、进阶：用截图里的坐标点击 Canvas 图形
普通视口截图只出图；而元素截图（--ref指向 Canvas）还会返回一个一次性capture_id。AI 智能体可以基于截图中的原始 PNG 坐标回点图形上的任意位置：
bsk click @e3 --capture <capture-id> --image-x 42 --image-y 18 \ --session <id>注意：capture 仅限一次使用、2 分钟内有效；重新observe/snapshot或对同一元素再次截图都会使其失效。协议细节见 tool_screenshot_result.json。
六、常见问题排查
| 现象 | 处理方式 |
|---|---|
--full-page和--ref同时传了 | 两者互斥，二选一 |
--timeout/--scope单独使用报错 | 这两个参数只在整页模式生效，需搭配--full-page |
extension did not acknowledge --scope current | 扩展版本过旧，需同步更新 CLI 与扩展 |
| 图片拿到了但不能做 Canvas 点选 | capture_unavailable表示图片仅可查看，需重新 observe + 截图后再点击 |
总结
BrowserSkill 截图功能覆盖了三档常见需求：视口最快、元素最精准、整页最完整。记住核心速查——--session必填、--ref配元素、--full-page配--scope/--timeout、--out控制输出路径，基本就能覆盖日常所有场景。配合bsk observe/bsk snapshot获取的@eN引用号，还能进一步实现"看图点图"的 Canvas 交互，是 AI 浏览器自动化工作流里视觉取证的基础能力。
【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI + extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 完全指南：用法、源码实现与最佳实践)
