企业官网建设流程全解析

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/bin：

curl -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只选中目标，不会激活标签，截图中请保持标签处于选中状态。

⚖️ 三种模式对比

三种模式的--json输出字段一致：tab_id、width、height、format、path、byte_size。全页模式额外返回被确认的scope；视口/元素模式在有 Canvas 时附带一次性的capture_id。

📋 全页截图参数速查

互斥与依赖关系一句话记住：--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-C）：agent.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