企业官网建设流程全解析

camofox-browser 大页面快照分页指南：offset 如何优雅避开 token 爆炸

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

在构建 AI Agent 时，浏览器快照（snapshot）动辄十几万字符，直接丢给大模型会瞬间引爆 token 成本。camofox-browser 是一款面向 AI Agent 的隐身无头浏览器服务，通过offset 分页快照机制自动截断超大页面、保留分页导航链接，让你按需取回每一块内容，从根源上解决 token 爆炸问题。本文带你快速理解它的原理与用法。

为什么大页面会"炸掉" token 上下文

AI Agent 浏览网页时，需要"看到"页面才能操作。如果把原始 HTML 全量喂给模型，一个普通电商搜索结果页就可能消耗数万字。camofox-browser 的做法是：

• 返回可访问性快照（accessibility snapshot）而非原始 HTML，体积约为 HTML 的1/10
• 快照只保留关键元素和稳定引用（e1、e2、e3），供 Agent 精准点击、输入
• 对超大页面再做窗口化截断：单次最多返回约 80000 字符（约 2 万 token），并附带offset参数继续取下一段

核心逻辑位于 lib/snapshot.js，它用MAX_SNAPSHOT_CHARS = 80000和SNAPSHOT_TAIL_CHARS = 5000两个常量定义了内容预算与"尾部保留区"。

offset 分页快照的工作原理

windowSnapshot(yaml, offset)是整个机制的核心，规则非常直白：

两个设计亮点值得注意：

1. 尾部永远在场：每块响应都会追加页面末尾的分页导航（"Previous / Next" 等链接），Agent 在任何一块里都能点击"下一页"，不会因为被截断而迷路。
2. 缓存复用：服务器把完整快照缓存在标签页状态中（tabState.lastSnapshot），后续offset请求直接切块返回，无需重新渲染 DOM，速度极快。页面一旦发生导航或点击，缓存自动失效，避免读到过期内容。

这个行为由单元测试 tests/unit/snapshot.test.js 和端到端测试 tests/e2e/snapshot-truncation.test.js 完整覆盖，包括"负数 offset 会被钳制为 0""迭代所有块可覆盖页面首尾全部内容"等边界场景。

一次真实的分页请求长什么样

整个过程只需看响应里的 3 个字段：truncated、hasMore、nextOffset。

# 1. 打开一个超大页面（如 500 个商品的列表页） curl -X POST http://localhost:9377/tabs \ -H 'Content-Type: application/json' \ -d '{"userId": "agent1", "url": "https://shop.example.com/large-list"}' # 2. 取第一块快照（自动截断） curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1"

响应关键字段：

{ "snapshot": "...前部内容...\n[... truncated at char 74800 of 152300. Call snapshot with offset=74800 to see more. Pagination links below. ...]\n...分页导航...", "truncated": true, "totalChars": 152300, "hasMore": true, "nextOffset": 74800 }

看到hasMore: true，就用nextOffset继续取下一块：

# 3. 取第二块，直到 hasMore 为 false curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1&offset=74800"

截断标记本身就把下一步操作写进了快照文本里——Agent 直接"读懂"提示，无需额外编程。MCP 工具侧同样如此：camofox_snapshot工具的描述明确写着"若响应包含hasMore=true和nextOffset，请带着该 offset 再次调用"，详见 mcp/lib/tool-contracts.mjs。

三个实用建议，让分页更省心

• 不要盲目取完所有块：先读第一块，确认目标元素是否已在"头部 + 尾部"里，很多操作（点击导航、翻页）根本不需要第二段。
• 利用稳定元素引用：refsCount字段告诉你快照中共注册了多少个可交互引用，点击用ref而非 CSS 选择器，翻页后引用自动重建。
• 配合includeScreenshot=true：在关键决策点（如判断弹窗、验证码）附带截图，让多模态模型辅助理解，其余块保持纯文本以省 token。

更多 API 细节可查阅自动生成的 OpenAPI 规范 openapi.json 与交互文档说明（GET /tabs/:id/snapshot支持offset与includeScreenshot两个查询参数）。

小结

camofox-browser 的 offset 分页快照用一个极简策略解决了 AI Agent 的大页面难题：80000 字符上限 + 5000 字符分页尾部保留 + 缓存切块。Agent 永远拿不到超过预算的响应，也永远不会丢失翻页能力——token 消耗从此可预期、可控。

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