page-agent getPageInfo与视口扩展：浏览器状态快照是如何组装的
page-agent getPageInfo与视口扩展浏览器状态快照是如何组装的【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentpage-agent 是一个 JavaScript 页面内 GUI AgentAI 网页操作代理它让大模型用自然语言控制浏览器界面。要让 AI 看见网页核心在于组装一份浏览器状态快照BrowserStategetPageInfo()负责测量页面尺寸与滚动位置viewportExpansion视口扩展决定哪些元素进入快照。本文带你读懂这份快照的完整组装流程。一、为什么 AI 需要浏览器状态快照page-agent 的每一步都遵循观察 → 思考 → 行动循环。在核心循环中Agent 会先调用getBrowserState()拿到当前页面的结构化状态再把它拼进发给大模型的提示词里快照采集入口PageController.getBrowserState()拼入 LLM 提示词的browser_state段落PageAgentCore.ts一份完整的快照包含四个部分字段含义示例url/title当前地址与页面标题用于定位上下文header页面信息 滚动位置提示Page info: 1920x1080px viewport...content可交互元素的简化 HTML[0]a 文档 /footer页面底部提示[End of page] 或 ... 300 pixels below ...这份结构在 PageController.ts 中定义为BrowserState接口是专门为 LLM 消费而设计的。二、getPageInfo一次轻量的页面测量getPageInfo()位于 getPageInfo.ts只有 40 行代码却回答了 AI 最关心的四个问题视口多大读取window.innerWidth/innerHeight整页多大取documentElement与body的scrollWidth/scrollHeight最大值滚动到哪了多级兼容读取scrollX/scrollYpageXOffset、scrollLeft兜底上下还剩多少用pixels_below page_height - (viewport_height scroll_y)算出下方剩余像素返回值里还有几个换算后的友好字段方便大模型建立直觉pages_above/pages_below把像素换算成几屏total_pages整页共几屏current_page_position当前滚动进度0~1会显示成 at 20% of page这些数字最终会渲染成一行文本注入header例如Page info: 1920x1080px viewport, 1920x5400px total page size, 0.0 pages above, 4.0 pages below, 5.0 total pages, at 0% of pageAI 正是靠这行文字判断还有多少内容没看到、要不要滚动。三、viewportExpansion视口扩展的三档模式DOM 提取时并非无脑抓取整页——viewportExpansion视口扩展参数控制元素的纳入范围定义见 dom/index.ts取值行为适用场景-1默认全页提取不受视口限制桌面端、长表单0只提取视口内元素移动端省 token正数如400视口向外扩展 400 像素折中方案判断逻辑在 dom_tree/index.js 的isInExpandedViewport中元素矩形与视口 扩展边距有交集才可见当值为-1时直接放行全部元素。一个有趣的细节-1模式下连最顶层元素判断也被特殊处理视口外的元素无法用elementFromPoint检测因此代码注释坦言正数扩展的实际收益有限真正常用的是-1与0两档见 dom/index.ts 的注释。在浏览器扩展场景下官方直接采用了折中值 400 像素扩展的 PageController 初始化RemotePageController.content.tsviewportExpansion还会反向影响快照的措辞——全页模式时 header 写 full pagefooter 固定为[End of page]而限视口模式会提示 scroll to see more引导 AI 主动滚动。这段文案分叉就藏在 getBrowserState() 里。四、快照组装的完整流水线把前面所有环节串起来一次getBrowserState()的流水线是测量getPageInfo()得到视口、整页尺寸、滚动进度重建 DOM 树updateTree()清理旧高亮 → 提取扁平 DOM 树 → 给可交互元素编上[序号]→ 生成简化 HTML见 PageController.ts拼装header标题行 页面信息行 滚动提示content简化 HTMLfooter底部提示消费核心 Agent 将三段拼入browser_state标签交给大模型决策见 PageAgentCore.tscontent长这样——每个可交互元素带序号缩进表示层级AI 只需报序号即可操作[0]a aria-label首页 / [3]a 文档 / [5]a rolebutton快速开始 /这种序号化 简化的设计对应 flatTreeToString是省 token 的关键属性白名单过滤、重复值去重、长文本截断到 20 字符。五、总结page-agent 的浏览器状态快照是一次精心设计的压缩getPageInfo()用十几行代码把页面几何信息压缩成 AI 能理解的几屏、百分之多少viewportExpansion用三档模式平衡覆盖范围与 token 成本最终 header/content/footer 三段式结构让大模型既能看见可点什么、又知道还能滚到哪。理解了这条流水线你就理解了 GUI Agent 观察能力的底层实现。延伸阅读官方文档page-controller 高级用法含viewportExpansion配置示例page-controller/page.tsxDOM 树数据结构定义dom_tree/type.ts扩展侧状态获取入口RemotePageController.ts【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考