page-agent 元素索引机制揭秘LLM 是如何精准点击 [35]的【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentPage Agentpage-agent是一个运行在网页内部的 JavaScript GUI Agent它让大语言模型LLM通过自然语言直接控制网页界面——无需截图、无需多模态模型、无需 Python 或无头浏览器。但 LLM 并不能看见页面那它是怎么把点击提交按钮这句话变成对真实[35]button的精准点击的本文带你完整拆解 page-agent 的元素索引机制DOM 提取、元素编号、selectorMap 映射、W3C 点击事件模拟四步走完你就明白了。一、整体流程一句话任务如何变成一次点击page-agent 采用经典的 ReAct 循环每一步先观察抓取页面状态再思考调用 LLM最后行动执行工具。核心循环位于 PageAgentCore.ts每一轮都会做三件事observe调用pageController.getBrowserState()重新抓取整个页面的交互元素生成一份文本版 DOMthink把文本版 DOM 连同任务、历史一起发给 LLMLLM 输出一个动作比如click_element_by_index参数index: 35act用编号 35 反查出真实 DOM 元素模拟一次标准点击。关键洞察LLM 自始至终只和编号打交道从不接触选择器、XPath 或坐标。二、第一步DOM 树提取——找出所有可交互元素页面 DOM 动辄上万个节点直接喂给 LLM 既贵又乱。page-agent 的做法是对 DOM 做脱水dehydrate遍历整个页面只保留有信息量的节点。提取入口是 dom/index.ts 中的getFlatTree()底层由移植自 browser-use 的 dom_tree/index.js 完成。它用一套启发式判断一个元素是否可交互见 isInteractiveElement鼠标指针样式cursor为pointer、grab、text等交互光标的元素直接放行——这是命中率最高的一招标签名button、a、input、select、textarea、label等表单/交互标签但会排除disabled、readonly的ARIA 角色rolebutton、roletab、rolecombobox等 20 余种可交互角色事件监听绑定了click、change等监听器的元素也算可交互可滚动容器能滚动的区域也会被收录并附带各方向可滚动距离。不可见display:none、零尺寸、aria-hidden的元素则被过滤掉。最终得到一棵扁平化 DOM 树数据结构定义在 type.ts每个可交互节点都带有一个真实的 DOM 引用ref: HTMLElement。三、第二步从 0 开始编号——highlightIndex被判定为可交互的元素会在遍历过程中被依次分配一个从零递增的编号即highlightIndex。第 36 个交互元素0 起算编号就是 35——这正是[35]button中那个 35 的来历。与此同时page-agent 会在页面上给该元素画一圈彩色描边、贴上编号角标highlightElement。这层高亮默认透明度极低、几乎不可见但它让你在调试模式下能直观看到LLM 眼里的元素地图。还有一个细节新元素标记。dom/index.ts 用一个WeakMap缓存见过的元素上一步没有、这一步新出现的交互元素比如下拉菜单展开出的选项编号前会加一个星号*[提示 LLM这是刚冒出来的。四、第三步把 DOM 树翻译成 LLM 能读的文本编号只是内部 IDLLM 需要的是人类可读的描述。flatTreeToString 把扁平树转成如下一份文本缩进表示父子层级方括号内是编号[33]div用户表单/div *[35]button aria-labelSubmit form提交/button [36]input typetext placeholder请输入姓名 / 普通正文文字直接列出不带编号这份文本随后被嵌入browser_state区块连同 URL、视口大小、滚动位置下方还有 300 像素一起作为browser_state.header / content / footer发送给 LLM拼装逻辑见 PageAgentCore.ts。为了省 token只保留title、aria-label、placeholder、role等约 20 个关键属性默认属性白名单属性值超过 20 字符会被截断。系统提示词中甚至专门教 LLM 如何解读这份格式见 system_prompt.mdInteractive Elements: All interactive elements will be provided in format as [index] text Only elements with numeric indexes in [] are interactive五、selectorMap编号到真实元素的那座桥LLM 决定点 35 号之后怎么从编号找回真实元素答案是selectorMap——一个Map编号, 交互节点在每次刷新 DOM 时由 getSelectorMap 重建缓存在 PageController.ts 中。注意一个设计原则编号是易失的。每一轮 LLM 思考前updateTree 都会清掉旧高亮、重新提取 DOM、重新编号。所以 LLM 永远只能使用当前这一步给出的编号——系统提示词里明确写着 Only use indexes that are explicitly provided。这避免了页面变化后拿着过期选择器乱点的问题。六、最后一公里从 35 到一次像真人的点击LLM 输出{click_element_by_index: {index: 35}}工具定义在 tools/index.ts。执行路径很短getElementByIndex从 selectorMap 取出 35 号节点返回它持有的真实HTMLElement取不到就直接报错No interactive element found at index 35clickElement模拟一次符合 W3C 规范的完整点击序列——先滚入视口按规范顺序派发pointerover → mousedown → pointerup → click等事件并且用elementFromPoint命中检测找到最内层真实目标连hover触发的悬浮菜单都能正确响应。input_text、select_dropdown_option、scroll等其余工具同样以编号为入参走同一座桥。七、关键源码文件速查想动手深挖按这个顺序读效率最高想了解看哪里索引如何生成dom_tree/index.js文本化与编号格式dom/index.ts每步刷新状态PageController.ts点击/输入实现actions.ts工具与主循环tools/index.ts、PageAgentCore.ts八、总结page-agent 的元素索引机制可以浓缩成三句话用启发式规则把上万节点压缩成几十个可交互元素用从 0 递增的编号替换脆弱的选择器用 selectorMap 把编号双向绑定到真实 DOM 节点。LLM 负责选哪个编号代码负责编号怎么变成一次点击——各干各的擅长的事这正是它不用截图、纯文本就能精准操作网页的核心机密。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考