bsk 截图实战指南从安装到十万像素级全页长截图【免费下载链接】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 Agent 操作完你已登录的浏览器后你总需要一张截图作为证据或存档——视口内的画面容易拿到跨了十几个屏幕的长页面就成了难题。BrowserSkill 的命令行入口bsk 截图命令就是为此设计的同一套命令覆盖视口截图、--ref元素裁切和--full-page全页长截图。读完本文你可以三分钟装好 bsk CLI跑通三种截图模式并知道长截图在极端页面下的可靠性边界与排错顺序。一分钟看懂 bsk一个二进制四条链路bsk 是CLI 前端与后台守护进程daemon合体的单一二进制。你敲一条bsk screenshot命令实际走了四段路CLI → daemon走本地 IPC。Unix 下是 socket 文件路径为$BSK_HOME/run/daemon.sockBSK_HOME缺省即~/.bskWindows 下是命名管道。daemon → 扩展走回环 WebSocket默认端口 52800。扩展 → 页面扩展不碰你正在用的标签而是把操作丢进一个独立的 Agent Window 里执行。子命令覆盖面很全会话session、标签tab、窗口window、导航、交互、snapshot/observe观察、record录制以及本文主角screenshot。所有命令共享全局开关--json出结构化结果--quiet收敛噪音-v/-vv调日志级别。子命令定义在 crates/bsk-cli/src/cli/mod.rs架构总图见 docs/architecture.md。三分钟跑起来bsk CLI 安装与验证macOS / Linux 一条命令默认装进~/.local/bincurl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh export PATH${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH注意export只在当前 shell 生效如果你的 Agent 每次调 shell 都带着旧 PATH要么在它的环境里同样设置要么直接用二进制绝对路径。Windows 侧用irm管道执行 install.ps1安装位置相同。装完立刻验证两条bsk --version bsk doctorbsk doctor会检查 CLI 与扩展的连通性并列出告警这一步别跳过——后文版本匹配问题全靠它兜底。CLI 之外还有两件配套浏览器扩展可从浏览器商店安装装好后 popup 里应显示已连接 READY以及 Agent skill——跑一次bsk install-skill写进 Cursor、Claude Code、Codex 等 harness或手动把 skill/SKILL.md 复制为browser-skill/SKILL.md。三种截图各管一事先说清前置条件三种模式全都适用--session id必填且必须是活跃会话由bsk session start创建对应一个 Agent Window目标标签必须属于该会话——会话自己创建的或用bsk tab borrow从你个人窗口借来的捕获期间标签保持选中、视口尺寸稳定--tab-id id只选中目标不会激活它不传时默认 Agent Window 当前激活的标签。然后是三个模式一句命令一个场景bsk screenshot --session id --out viewport.png bsk screenshot --session id --ref e3 --out element.png bsk screenshot --session id --full-page --out page.png视口截图默认行为截当前视口范围内的 PNG适合此刻看到了什么这类即时证据。元素截图--ref eN取自最近一次bsk observe或bsk snapshot的引用把画面裁到那个元素或 Canvas 区域。针对 Canvas 的截图会附带一个capture_id单次有效供后续点击等操作定向引用。全页长截图--full-page把普通 HTTP(S) 页面从顶滚到底连滚动过程中懒加载出来的内容一起收进来最后拼成一张完整 PNG。全页模式专属参数四个就够参数行为--timeout 30s / 5m捕获编码的截止时间默认 2 分钟必须搭配--full-page使用--scope follow默认跟随滚动中追加出来的新内容--scope current只收捕获开始时测得的文档区域但该区域内的懒加载图片照样会滚动触发--full-page与--ref互斥不能同时给两个通用约定省略--out时文件落进系统临时目录名字形如bsk-screenshot-毫秒时间戳.png加--json时三种模式返回一致的字段集——tab_id、width、height、format、path、byte_size视口/元素模式在可用时还会带capture_id。参数定义与校验逻辑在 crates/bsk-cli/src/cli/screenshot.rs。长截图的可靠性来自哪里一次超长截图的旅程把一次--full-page从头到尾拆开看它像一趟分段验收的货运每一段都有硬性检查点。第一段逐视口滚动采集。扩展每次只截一个视口相邻视口保留约 15% 重叠以防拼缝错位。何时算到底了判定条件是高度至少 1.5 秒不再增长且底部附近内容 600ms 无变化才收尾。若页面底部出现加载指示器并且 30 秒内毫无进展Agent 模式会提前返回loading_stalled而不是傻等到总超时。第二段扩展侧瓦片存储与流式编码。采集数据不堆在整页画布里而是切成512 像素高的 PNG 瓦片加一份小体积 manifest 存进扩展的 OPFSOrigin Private File System。后续导出按瓦片逐块读出按行应用 PNG Up 滤波器再经原生CompressionStream(deflate)流式压缩——全程不构造整张像素缓冲也不产生整图 base64。这套实现见 apps/extension/src/long-screenshot/行为文档在 docs/long-screenshot.md。第三段CLI 侧分块拉取。大文件拆箱发货CLI 按字节 offset 分块向扩展要数据每块上限 256 KiB。每块都要过连续性校验——大小不超限、非空、offset len恰好等于下一块的 offset、不越过总字节数、eof 标志与真实文件末尾一致。任何一块不合格就整体中止宁可失败也不拼出一张坏图。第四段原子落盘。CLI 在输出文件旁边先写临时文件.part后缀边收边写并sync_all刷盘字节收齐后才原子替换目标——Unix 用renameWindows 用MoveFileExW。落盘语义相当于整盘端上来的菜要么完整要么没有目标路径要么是旧图要么是完整新图不存在半张图的中间态。实现见 crates/bsk-cli/src/cli/atomic_output.rs。收尾还有两件事Ctrl-C 可随时取消捕获或传输取消后不保存任何残缺文件无论成功失败CLI 都会调用tool.screenshot_release释放扩展侧导出扩展本身也有 10 分钟无读取自动过期、每分钟一次的后台清扫兜底。官方实测中一张 3170×100062 像素的导出全程只用了最高 512 像素高的画布。它做不了什么全页模式只针对普通可脚本化的 HTTP(S) 页面以下场景直接不支持Chrome 内部页面、Chrome 应用商店页——这些页面禁止注入内容脚本。例外仅有一个扩展的 Quick Actions 在可见区域模式下经activeTab权限可以截当前视口但自动全页模式不可用嵌套滚动面板、虚拟化列表典型如无限滚动信息流页面文档本身不断增长时滚动会一直进行最终撞上--timeout截止线捕获期间页面发生导航、或你切换了标签捕获直接中止目标标签被隐藏切到后台窗口可能导致捕获停滞——所以要求标签全程保持选中且视口稳定。一个容易误解的点要澄清全页导出的 PNG由 CLI 直接写进你指定的磁盘路径不经过扩展 popup 的结果页也不会往浏览器下载目录里丢文件。普通视口截图与--ref裁切不受上述限制行为保持不变。出问题先查这三件第一件版本匹配。全页截图依赖 CLI 与扩展构建版本一致。CLI 更新后已有守护进程要手动重启bsk daemon restart如果扩展还是旧版它会拒绝新的 RPC 请求而不是悄悄返回一张错误的视口图——报错方向明确不会给你留错觉。扩展本身靠浏览器商店更新商店上架可能略滞后于 CLI 发布。第二件检查链。按顺序跑bsk --version→bsk status→bsk doctor前者确认 CLI 版本后者确认会话与扩展连通状态。绝大多数截图不对劲在这条链上就能定位。第三件对照 skill 规范。skill/SKILL.md 里固化了截图使用约束--full-page同样需要--session--ref与--full-page互斥全页模式需要受控标签。给 Agent 下截图任务前先对照一遍这三条能避开大部分低级失败。顺带一提仓库自带覆盖整条 CLI → daemon → 扩展链路的端到端浏览器测试多块传输、超长页面、取消、超时与临时文件清理都有专门场景实现细节想深挖可以看apps/extension/src/long-screenshot下的capture.ts、tiles.ts、png.ts与配套测试。【免费下载链接】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），仅供参考