bsk 截图能力一次讲清：BrowserSkill 全页长截图从 0 到一张图-开发者社区

bsk 截图能力一次讲清：BrowserSkill 全页长截图从 0 到一张图

【免费下载链接】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

想象这个场景：Agent 刚读完一篇三万像素高的长文页面，想把它作为一张完整图片喂给下游多模态模型。逐屏截图再自己拼，麻烦且接缝难处理。BrowserSkill 的bsk screenshot就是干这个的：视口截图、元素截图、全页长截图都是一条命令，全页模式会把页面从顶滚到底、等懒加载内容出现，再拼出一张完整 PNG。这篇就按"一次全页截图的完整旅程"走一遍。

先把图拿到手

截图之前先备齐两样东西：连上 BrowserSkill 的浏览器，和一个会话。bsk session start会在浏览器里开一个专用 Agent Window，返回的会话 ID 是每条bsk screenshot都必需的--session <id>；目标标签必须属于这个会话——要么是会话创建的，要么用bsk tab borrow从你个人窗口借来的。扩展弹窗里看到"已连接 READY"就说明浏览器侧就绪了：

CLI 还没装的话，macOS/Linux 一条命令装完（默认落到~/.local/bin）：

curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh

最基础的用法就两条命令 📸：

bsk screenshot --session <id> --out viewport.png bsk screenshot --session <id> --ref @e3 --out element.png

前者是当前视口一张 PNG；后者拿上一次bsk observe或bsk snapshot返回的@eN引用，把图裁到那个元素（或 Canvas 区域）。--out不写就落到系统临时目录，文件名带时间戳；加--json会输出path、width、height、byte_size等统一字段，方便 Agent 直接解析。

把整页变成一张图

现在上正题。超长页面一句话搞定：

bsk screenshot --session <id> --full-page --out page.png bsk screenshot --session <id> --full-page --timeout 5m --scope current --out loaded.png

先说结果：成功时命令打印输出路径（--json时打印尺寸、字节数等字段），文件里就是从页面顶部到底部的完整 PNG；结束时会把原来的滚动位置和临时样式还原，你的阅读现场基本不动。

过程中的行为是：从顶往下逐视口抓取，滚动途中懒加载出来的新内容一并收进图里。默认follow范围会跟随底部追加的内容；--scope current则只截"开始时测得的文档区域"——仍会滚过整个区域触发懒加载图片，但范围不随页面变长。--timeout是捕获/编码的截止线，默认 2 分钟，慢页面给它 5m 也不心疼。

⚠️ 有一处防呆值得说：如果你指定了--scope current但扩展是旧版本、不认这个参数，CLI 会直接拒绝保存并提示更新扩展。宁可不给图，也不给一张尺寸悄悄错的图。

一页到底怎么拼出来的

为什么要分块传？因为图太大。长页 PNG 动辄几百 MB，整包 base64 走一趟，扩展、守护进程、CLI 三头的内存都悬。所以bsk把图片字节按块拉取，每块上限 256 KiB，边拉边校验；哪一块断了、错位了，直接中止——宁可整张重来，绝不拼出一张坏图。

为什么落盘要用"临时文件 + 原子替换"？为了不留半张图。CLI 先把收到的字节写进同目录的.part临时文件，全部收齐后才原子替换到目标路径。这意味着目标位置在任意时刻要么是旧图、要么是完整新图，下游读取方永远看不到撕裂的 PNG；失败时临时文件会自动清掉。

扩展侧同样做了内存友好设计，否则也撑不起这么高的图：捕获时只解码当前视口和 512 像素高的小瓦片，整页数据以"瓦片集合 + 小索引"存在扩展自己的 OPFS 磁盘存储里；导出时逐瓦片读、逐行做 PNG 滤波，再走浏览器原生的 deflate 压缩流写出，全程不构造整页像素缓冲。官方验证里一张 3170×100062 像素的导出，用的画布最高只有 512 像素高。

拼接也不是简单贴图：相邻视口留约 15% 重叠抵消滚动误差；文档高度增长时回卷重绘旧尾部；到底后至少等 1.5 秒高度稳定、600 毫秒附近内容无变化才收工；如果底部有加载指示器且 30 秒没进展，Agent 模式直接返回loading_stalled报错，而不是干等到总超时。CLI 读完后会通知扩展释放这次导出，扩展侧另有 10 分钟无人读取自动过期的兜底，不会永远占着地方。

截图没成功先看这里

常见的失败点，其实就三处：

标签页"动"了：目标标签必须全程保持选中，视口尺寸稳定。页面被隐藏可能直接停止捕获，页面发生导航或切换标签则整个捕获中止。
撞到截止线：--timeout就是捕获/编码的总期限。内容不断追加的页面（比如无限流）在 follow 模式会一直滚下去直到撞线，这时就该换--scope current把范围框死。
Ctrl-C 是安全退出：随时取消，捕获和传输都不留残缺图片，也不会动你之前的输出文件。