bsk 全页长截图实战指南从安装到一张完整页面 PNG【免费下载链接】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当你需要把一张超长网页从顶到底完整存成一张 PNG 时bsk screenshot --full-page会自动滚动、拼接并校验字节数。读完本指南你可以完成三件事装好bskCLI 并出第一张截图、看懂三种截图模式的差异与参数坑、理解全页长截图为什么不会写出半张坏图。 先想清楚你需要哪种截图三种模式对应三种真实需求选错模式只会白跑一趟。普通网页留档想留个当前画面的证据一条命令出图即可。视口模式截的是浏览器当前可见区域最快默认行为。单个元素取证页面里只有一个报错弹窗或一块 Canvas 图表需要留存。先用bsk observe或bsk snapshot拿到eN引用再用--ref把截图裁切到那个元素或 Canvas 区域。超长页面归档整个文档站、长文报告、无限信息流需要完整页面存下来。--full-page会把普通 HTTP(S) 页面从顶部滚到底部连滚动中加载出的新内容一起捕获结束后恢复原来的滚动位置。 三步装好环境出第一张图第一步安装 CLI。CLI 同时包含命令行前端和后台守护进程daemon默认装到~/.local/bincurl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh export PATH${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH第二步环境体检。装好浏览器扩展、打开它的 popup 并启用本地连接后跑一遍诊断处理所有失败项bsk doctor第三步首次出图。bsk screenshot的所有模式都要求一个活跃会话 ID先用bsk session start创建一个对应浏览器里的一个 Agent Window然后截图bsk session start --no-focus --json bsk screenshot --session id --out first.png注意截图目标标签必须属于该会话要么由会话创建要么用bsk tab borrow从你个人窗口借入。--tab-id只选中目标不会激活标签截图中请保持标签处于选中状态。⚖️ 三种模式对比模式一条命令示例适用场景限制视口截图bsk screenshot --session id --out viewport.png留档当前画面只截可见区域元素截图bsk screenshot --session id --ref e3 --out element.png单元素/Canvas 取证eN必须来自最近一次bsk observe或bsk snapshot全页长截图bsk screenshot --session id --full-page --out page.png超长页面完整归档仅普通 HTTP(S) 页面需 CLI 与扩展版本匹配三种模式的--json输出字段一致tab_id、width、height、format、path、byte_size。全页模式额外返回被确认的scope视口/元素模式在有 Canvas 时附带一次性的capture_id。 全页截图参数速查参数含义注意点--session id会话 ID必填必须活跃标签须属于该会话--tab-id id显式指定目标标签不激活它默认取 Agent Window 当前激活标签--ref eN裁切到指定元素/Canvas与--full-page互斥不能同用--full-page开启全页模式与--ref互斥--timeout 时长捕获/编码截止时间如30s、5m必须搭配--full-page默认 2 分钟--scope follow\|currentfollow默认跟随追加内容current只截开始时测得的文档区域必须搭配--full-pagecurrent仍会滚动该区域暴露懒加载图片--out 路径输出 PNG 路径省略时写入系统临时目录文件名bsk-screenshot-unix毫秒.png--json结构化输出全页模式额外含scope互斥与依赖关系一句话记住--timeout和--scope是--full-page的跟班单独出现直接报错--ref和--full-page是二选一。️ 长截图为什么不会损坏全页 PNG 可能非常大可靠性靠三层机制保证。分块传输PNG 数据不在 CLI 与扩展之间整包 base64 传输而是按字节offset分块拉取每块最多 256 KiB。每块都要过严格校验块非空、offset len与next_offset严格连续、eof与到达文件末尾一致任何一块非法立即中止绝不拼出坏图。原子落盘CLI 先在输出同目录创建临时文件.bsk-screenshot-uuid.part边收边写并sync_all落盘收满全部字节后才原子替换目标文件。这意味着目标路径要么是旧图、要么是完整新图绝无半张图。失败时临时文件会被清理无论成功、失败还是 Ctrl-C结束时都会调用tool.screenshot_release释放扩展侧的导出。实现见 screenshot.rs。瓦片存储扩展侧把整页存成 512 像素高的 PNG 瓦片集合存放在 Origin Private File System导出时逐瓦片读取经原生CompressionStream(deflate)流式压缩写出 PNG chunk全程不构造整张像素缓冲。追加内容只需替换相关瓦片官方验证中一张 3170×100062 像素的导出仅用最高 512 像素高的画布完成。核心定义在 tiles.ts 的TILE_HEIGHT 512。 截图翻车怎么办现象全页模式报扩展未确认 scope或新 RPC 被拒绝。原因CLI 与扩展构建版本不匹配旧扩展不认识新参数。处理更新扩展后运行bsk daemon restart重启已有守护进程再用bsk --version和bsk doctor复核。旧扩展宁可拒绝也不会返回错误的视口图。现象命令卡了 2 分钟后超时报错没有留下任何图片文件。原因默认捕获/编码截止线为 2 分钟页面持续加载可能触到截止线。处理用--timeout 5m放宽若是无限加载页面考虑改用--scope current只截初始区域。现象滚动中页面底部一直有加载指示器报loading_stalled。原因Agent 模式下底部 30 秒无进展且存在渲染的加载指示器提前报错而非等总超时。处理这是宁缺毋滥设计——不保存部分图片。可先手动把页面加载稳定后再重跑。现象Ctrl-C 取消后输出路径下没有文件。原因取消会中止捕获或传输残缺字节直接丢弃。处理无需清理重新执行即可原图若已存在则原样保留。现象标签切到后台后捕获停止报page_hidden或navigation。原因页面隐藏可能停止捕获页面导航或切走标签会中止捕获。处理捕获期间保持目标标签选中、视口尺寸稳定。 明确边界全页模式只支持普通可脚本化 HTTP(S) 页面以下场景不支持Chrome 内部页面、Chrome Web Store禁止注入内容脚本只能退回视口截图嵌套滚动面板、虚拟化列表如无限滚动列表文档自身不断增长到无底的页面会持续滚动直至超时捕获期间发生导航或切标签。如果目标页面命中上述限制最稳妥的替代是退回普通视口截图逐屏手动滚动留档。全页导出走 CLI 直写磁盘不经过扩展 popup 结果页也不触发浏览器下载目录。延伸阅读完整行为与实现文档docs/long-screenshot.md端到端浏览器测试多块传输、32K 像素以上捕获、超时与 Ctrl-Cagent.browser.test.ts滚动拼接与流式编码源码capture.ts、png.ts一句话收束装好 CLI、建好会话、一条--full-page长截图的可靠性就交给自己验证过的字节校验去守。【免费下载链接】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），仅供参考