camofox-browser /snapshot端点深度解析：includeScreenshot与offset分页-开发者社区

camofox-browser /snapshot端点深度解析：includeScreenshot与offset分页

【免费下载链接】camofox-browserStealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.项目地址: https://gitcode.com/GitHub_Trending/ca/camofox-browser

camofox-browser是一款面向 AI 智能体的隐身无头浏览器服务器（基于 Camoufox 反检测引擎），它的/snapshot端点是整个 API 的核心：一次请求即可拿到页面的无障碍快照 + 可点击元素引用，还支持includeScreenshot附带截图、offset对超大页面自动分页，是智能体"看懂网页"的关键入口。

一、/snapshot 端点是什么？

传统爬虫把整页 HTML 喂给模型，又长又贵；camofox-browser 的做法是返回无障碍树（Accessibility Tree）——只保留页面里"有意义的东西"（标题、链接、按钮、输入框……），体积比原始 HTML 小约 90%。

更妙的是，每个可交互元素都会被标注一个稳定引用（如e1、e2），后续点击、输入只需引用编号即可：

- heading "Product Search Results" - link "Next" [e42] - button "Submit" [e1]

端点路径为GET /tabs/:tabId/snapshot（实现见 server.js），另有一个旧版 OpenClaw 格式GET /snapshot（见 server.js），两者参数与行为一致。

二、请求参数一览

参数	类型	说明
`userId`	字符串	必填，用于定位会话与标签页
`format`	`text`/`json`	输出格式，默认`text`
`offset`	整数	分页读取大快照的字符偏移量（默认 0）
`includeScreenshot`	`true`/`false`	是否附带 base64 编码的 PNG 截图

三、includeScreenshot：让智能体"既读得到、又看得见"

加上includeScreenshot=true后，响应里会多出一个screenshot字段：

{ "data": "<base64 字符串>", "mimeType": "image/png" }

截图是实时拍摄的 PNG，可直接交给多模态模型或保存归档；
不加该参数时，响应中不会出现screenshot字段，请求更轻量（行为由 tests/e2e/snapshotScreenshot.test.js 完整覆盖）；
对纯文本任务（如提取链接、填表单）建议保持默认关闭，省流量也省 token 👍。

💡 小贴士：camofox_snapshot等 MCP 工具内部默认开启截图参数，源码可参考 mcp/lib/tool-contracts.mjs。

四、offset 分页：超大页面如何"分片读取"

网页内容可能非常庞大，一次性全返回会撑爆上下文窗口。camofox-browser 在 lib/snapshot.js 中实现了精巧的**快照窗口化（windowing）**机制：

总预算 80000 字符（约 20K token），每片尾部固定保留约 5000 字符——专门留给分页导航链接，保证智能体在任何一片里都能找到 "Next / Previous"；
offset=0：返回"头部片段 + 尾部导航"；
offset=N：返回第 N 到 N+预算之间的内容，且仍追加导航尾部；
被截断时会在快照中嵌入提示标记：[... truncated at char X of Y. Call snapshot with offset=X to see more. ...]。

读取循环非常简单，靠hasMore/nextOffset两个字段驱动：

首次请求不传offset，得到第一片 +nextOffset；
若hasMore为true，用offset=nextOffset取下一片；
直到hasMore为false，整页内容即被完整遍历（e2e 测试见 tests/e2e/snapshot-truncation.test.js）。

⚡性能细节：offset>0的请求直接命中上一次快照的缓存（tabState.lastSnapshot），不需要重新截图、重新解析 DOM，翻页几乎零成本。而页面发生导航或点击后缓存会自动失效，保证你读到的永远是最新页面。

五、响应字段速查

字段	含义
`url`	当前页面地址
`snapshot`	本片的无障碍快照文本（含元素引用）
`refsCount`	页面中可交互元素引用总数
`truncated`	本响应是否被截断
`totalChars`	完整快照的总字符数
`hasMore`	是否还有后续片段
`nextOffset`	下一片的 offset 值（没有则为`null`）
`screenshot`	仅当`includeScreenshot=true`时存在

完整接口契约可参考自动生成的 openapi.json。

六、快速上手：两条 curl 搞定

# 1) 基础快照（纯文本无障碍树） curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1" # 2) 附带截图 + 读取第二片 curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1&includeScreenshot=true&offset=74800"

七、最佳实践

🎯常规浏览：只调/snapshot，用返回的元素引用去click/type；
📄电商列表、长文聚合页：检查hasMore，用nextOffset循环翻页，别一次吞下整页；
🖼️需要视觉判断时（验证码、布局异常）：再加includeScreenshot=true；
🧭点击分页链接后：重新调用 snapshot 获取新页面的引用，旧引用会因导航而失效。

关键文件导航

窗口化算法：lib/snapshot.js
主端点实现：server.js
旧版 OpenClaw 格式端点：server.js
接口文档：docs/openapi.json
分页 e2e 测试：tests/e2e/snapshot-truncation.test.js
截图 e2e 测试：tests/e2e/snapshotScreenshot.test.js

总结

/snapshot端点用三个参数就解决了两件大事：includeScreenshot让智能体"看得见"，offset分页让它"读得完"。配合稳定的元素引用和无障碍树的高压缩率，camofox-browser 把"浏览网页"变成了一项 token 成本可控、行为可靠的标准化操作——这正是 AI 智能体真正落地浏览任务的基石。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考