企业官网建设流程全解析

做 GUI Agent 的人都清楚，定位（element location）是所有自动化动作的地基。任务规划、步骤拆分做得再漂亮，最后一步落实为一次鼠标点击、一次键盘输入时，总得先把目标元素在屏幕上的坐标找出来。我做的这套系统跑起来之后，日志里有个数字一直很扎眼：单次元素定位平均耗时 12.9 秒。一个 5 步的流程，光定位就吃掉大半时间，任务一长基本必超时。这个速度别说"实时操控"，连给人演示都费劲。

后来我把定位链路从架构层面重做了一遍，没有继续堆大模型推理，也没换更强的视觉模型，只把"理解界面"和"找坐标"这两件事拆开，定位耗时从 12.9 秒降到 0.3 秒，算下来刚好 40 倍。整个过程踩了不少坑，也推翻过两个中间方案，这篇就把完整思路、实现细节和那些文档里不会写的经验整理出来，给同样在做 GUI Agent 定位模块的朋友一些参考。

1. 12.9 秒审计：GUI Agent 定位慢在哪几个环节

1.1 旧定位链路是怎么跑的

先说清楚旧的定位链路长什么样，否则你没法理解 12.9 秒到底花在哪。我当时的基础实现和大多数 GUI Agent 项目一样：每一步操作走"截图-推理-执行"的老路。

拿到一个操作指令，比如"点击左上角的登录按钮"，系统先调用底层接口截取当前屏幕画面，把整张高清截图（一般是 1920x1080 或更高）编码成 base64 图片，然后连同系统提示词、界面描述、用户指令一起丢给多模态大模型。模型需要"看着"整张截图，想象出目标元素大概在什么位置，然后返回一组坐标或者对元素的视觉描述。我再把这些坐标换算成真实屏幕坐标，驱动鼠标去执行点击。

这套流程听起来很直觉，但实际上每一步都在浪费钱和时间。截图编码一次要几百毫秒，图片传上去要看尺寸和网络，模型推理阶段要排队，推理完解析结果又要时间。更让人崩溃的是，模型一旦给出一个"看起来合理但实际点偏了"的坐标，你还得截图重试，于是又一个完整循环被搭进去。

1.2 耗时构成：原来一半时间花在"看不见的地方"

我最初以为是模型推理慢导致整体慢，后来在关键路径上做了埋点统计，才发现"看不见的地方"才是大头。拿一次典型的点击动作为例，耗时拆解大概是这样的：

这还没算系统内置的"安全确认"逻辑——模型返回坐标后，我还会再做一次视觉对比，验证那个区域确实是目标元素。每次验证又是一轮小图推理。一个动作做到最后，多轮等待全部累加起来，12.9 秒其实属于"常态偏下"的数据，遇到复杂页面冲到 20 秒我都不意外。

1.3 这 12.9 秒背后的设计问题

审计做完之后，问题就很明确了：我当时把"理解界面"和"找元素坐标"两件事焊死在同一个模型调用里了。大模型擅长的事情是做规划、理解用户意图，但你非要它在每一步操作前都盯着整张截图做像素级搜索，等于让一个资深建筑师每次到工地上先亲手搬砖——不是不能做，是这个用法又慢又贵且不稳定。

一句话总结当时的病根：定位不是推理问题，是索引问题。

页面上的按钮、输入框、链接，这些元素在老早之前就存在于 DOM 树里、存在于可访问性树里。它们的文本、角色、位置信息全是现成的结构数据。我没有理由让模型从一堆像素里重新认知一个"登录按钮"，更好的做法是从结构数据里把候选元素直接捞出来。

2. 方案选型：为什么我绕开了"理解全图"这条路

2.1 三条路线摆在一起看

想清楚要拆解链路之后，我列了三条候选路线，直接排除法的过程比较有参考价值。

第一条是经典的 SoM（Set-of-Marks）方案，也叫数字标记法。做法是先把当前页面上所有可交互元素找出来，给每个元素渲染一个数字角标，然后把打了数字标记的截图发给多模态模型，模型直接回答"点击编号 7"。这个方案的最大优点是定位准确率高，因为模型不用猜坐标，只需要识别数字标记；缺点是延迟并没有质变——你仍然要走一次完整的多模态推理，只是从"输出坐标"变成了"输出编号"。实测中单次延迟还是保持在 4 秒以上，对我这 0.3 秒的目标远远不够。

第二条是纯视觉坐标回归，让小模型直接输出目标元素的屏幕坐标。这条路线在游戏界面、远程桌面这类拿不到结构信息的场景里有意义，但精度和稳定性都很难保证，而且同样绕不开一次模型推理。

第三条是可访问性树 + 语义检索。先拿到当前界面的结构化元素列表，把元素转换成文本描述，再把用户指令变成向量去检索，用相似度直接命中目标元素，最后通过元素自带的 bounds 坐标回投出屏幕位置。整个过程没有一次大模型推理，纯计算和轻量检索，单次定位做到几百毫秒完全可行。

2.2 我为什么押注"结构化界面"

我当时犹豫过第一条和第三条，原因很简单：怕检索方案接不住那些"没有文本"的按钮。GUI 里大量图标按钮，比如一个只有齿轮图标的设置按钮，语义检索很难直接匹配"打开设置"和"齿轮图标"之间的含义。

但后来我想通了一件事：GUI 本来就是人为设计的结构化产物，不是自然场景。网站有 DOM，桌面应用有可访问性树，移动端有视图层级。这些结构里已经包含了每个元素的角色、名称、层级关系、位置信息。图标按钮即便没有文字，它的 tooltip、aria-label、父容器标题也通常写着它在干什么。我要做的事情不是从零理解界面，而是把这些结构信息最大限度地挖掘出来，变成检索可用的语义描述。

这也是为什么我没有选择"继续优化视觉定位"这条路。视觉定位在结构信息不可用时是对的兜底，但不应该成为默认路径。默认路径应该用最快的方案，兜底路径才留给最聪明但最慢的方案。

2.3 树拿不到的时候怎么办

有一类场景确实拿不到树：纯 canvas 游戏界面、远程桌面画面、只给截图的第三方接口。这种时候结构信息不存在，索引方案直接失效。

我的处理方式很直接：做一个运行时环境探测。如果脚本运行在浏览器里，通过 CDP（Chrome DevTools Protocol）拿 DOM 和可访问性树；如果运行在桌面端，通过系统辅助功能接口拿 UI 元素树；如果这些通道全部不可用，才降级回视觉定位旧链路。大多数 Web 和桌面自动化场景走的是前三者，所以降级路径实际上很少被触发，但它的存在让整套方案不至于在极端场景下完全没法用。

2.4 目标架构

最后确定的架构用一句话描述就是：快速检索拿候选，局部视觉做仲裁，完整视觉做兜底。

检索阶段用可访问性树 + 向量相似度，从几十个元素里直接筛出 top-k 候选；如果候选之间分数差距足够大，直接信任 top-1，立即执行点击；如果分数胶着，或者目标元素疑似是纯图标按钮，我会把目标区域的局部小图裁出来，只做一次轻量视觉确认，用几百毫秒的成本杜绝错误点击；万一这一步也拿不准，才会把完整截图推到完整视觉链路去做最终判定。

这套架构出来之后，定位延迟结构发生了根本变化：核心路径上不再有"整图大模型推理"这个环节。

3. 核心实现：把一棵界面树变成可检索的元素库

3.1 第一步：抽取可交互元素，别把整棵树都喂进去

可访问性树通常又大又深，一个复杂页面动辄几百上千个节点。如果全量塞进检索，既没必要也会把无关信息带进来。我做的第一件事就是过滤——只保留"可交互"元素：按钮、链接、输入框、下拉框、复选框、滑动条、选项项，以及那些绑定了点击事件的容器。

以浏览器场景为例，CDP 拿可访问性树的关键调用是Accessibility.getPartialAXTree，配合 DOM 节点信息做角色过滤。核心逻辑类似这样：

# 伪代码：过滤可交互元素 def collect_interactive_nodes(ax_tree): interactive_roles = { "button", "link", "textbox", "combobox", "checkbox", "radio", "slider", "menuitem", "tab" } result = [] for node in ax_tree: if node.role in interactive_roles: result.append(node) elif node.is_clickable and node.has_action: # 某些 div 容器绑了点击事件，比纯粹的角色判断更准 result.append(node) return result

这里有个细节：很多库只按 role 过滤，会漏掉大量"div 套了点击事件"的可点击容器。这类元素在可访问性树里 role 可能还是generic，但会有可点击特征。所以我的过滤条件是"角色属于交互类型 或 节点本身带点击动作"，两者取并集。这一条过滤规则直接影响了后续检索的覆盖率。

3.2 第二步：构造元素描述文本，这是区分度的核心

过滤完可交互元素，下一步就是把每个元素转成一段适合做语义匹配的文本。这里是最能拉开工程距离的地方——千万不要只拿元素的文本内容去 embedding。

一个只写"确定"的按钮、一个只写"取消"的按钮，文本向量几乎一摸一样，语义检索根本分不开。我需要把元素的上下文全部压进描述文本里，让相似元素在向量空间里真正拉开距离。

我给每个元素构造描述的逻辑是这样：

• 主名称：优先取可访问名称（accessible name），退化链路是 aria-label → aria-labelledby 指向内容 → 元素文本 → 占位符。
• 角色信息：按钮、输入框、链接等，角色本身就是很强的语义信号。
• 容器上下文：向上找两层祖先节点，把表单标题、弹窗标题、导航栏名称拼进来，比如"位于登录表单"就很有辨识度。
• 可见文本片段：如果元素是容器型，抽取子节点的短文本做辅助描述。

最终一个"用户名输入框"的描述文本长这样：

textbox; 可见文本: 用户名; 占位符: 请输入邮箱或手机号; 表单: 登录; 区域: 登录表单

而一个"登录按钮"的描述则是：

button; 文本: 登录; 表单: 登录; 区域: 登录表单底部操作区

这样构造的文本，在向量空间里的相互距离会明显拉大，检索命中率才有保障。这一步是纯工程细节，没有太多理论和花活，但实际提升比换更好的 embedding 模型还大。

3.3 第三步：语义检索与 Top-K 打分

元素描述构造好之后，检索本身反而简单了。我的用户指令会先做一次轻量归一化，比如"点一下左上角的那个登录按钮"会去掉方位词，保留动作和对象，生成一个干净的检索向量，再对当前页面所有候选元素做余弦相似度计算。

这里有一个很多人的惯性误区：一听到"语义检索"就想着上向量数据库。我最初也差点去部署 Chroma、Milvus，后来算了一笔账：单页面可交互元素通常就 30 到 200 个，你对 200 个向量做一次暴力线性扫描，耗时在毫秒级，根本不需要索引结构。只要不是跨上千个页面的全局检索，同屏场景暴力扫永远是最简单最可靠的做法。

检索打分之后，我会做一个候选排序。排序结果不只是 top-1 一个元素，而是保留 top-3，因为后面仲裁环节要用。核心代码骨架大致这样：

import numpy as np from sklearn.preprocessing import normalize def locate_element(user_intent, element_descriptions, threshold=0.35): intent_vec = normalize([embed(user_intent)])[0] scores = [] for idx, desc in enumerate(element_descriptions): elem_vec = normalize([embed(desc)])[0] cos_sim = np.dot(intent_vec, elem_vec) scores.append((idx, cos_sim)) # 同分元素用文本精确匹配优先 return sorted(scores, key=lambda x: x[1], reverse=True)[:3]

特别说明一下粗筛阈值：0.35 是经验值。如果 top-1 的分数都低于这个值，说明检索结果基本不可信，我会直接跳过仲裁，触发完整视觉兜底，而不是硬着头皮去点一个低置信度的元素。

3.4 第四步：坐标回投与缓存更新

检索命中元素后，最后一步是把元素坐标换算成屏幕坐标。这个环节看起来简单，但坑在细节。

可访问性树里每个元素自带 bounds，一般是相对当前浏览器的视口坐标。直接取 bounds 的中心点就能用：

x = bounds.left + bounds.width / 2 y = bounds.top + bounds.height / 2

但要注意两件事。第一，如果目标元素在 iframe 里，CDP 返回的 bounds 通常只是 iframe 内部的坐标系，你需要累加 iframe 本身的屏幕偏移，否则坐标会整体偏一截。第二，如果页面在滚动容器里，元素坐标要按当前滚动位置换算，不能直接用树的静态 bounds。

坐标算完之后，元素描述和它的向量会按页面 hash 做一层缓存。同一页面在流程中往往会被多次访问，比如"填写表单-点击保存-校验结果"这组动作会来回操作同一个页面。缓存命中时，连元素描述 embedding 都可以跳过，定位延迟能进一步压到 0.15 秒以内。

4. 准确率保底：仲裁、局部视觉确认和降级路径

4.1 纯检索的失败模式

无论描述文本构造得多好，纯文本检索总有失败的时候。我跑第一轮全量回归时，300 个真实任务里大概有 20 多个会点错，失败点集中在两类场景。

第一类是短文本按钮的同义纠缠。界面上同时存在"保存"和"保存并退出"，用户指令说"保存"，两个元素的描述向量可能非常接近，检索结果在二者之间摇摆。点错了用户立刻就会发现，因为动作语义完全不同。

第二类是纯图标按钮，无文本、tooltip 也不够明确。比如一个任务详情列表里每行有个"⋯"更多按钮，用户指令是"删除这条记录"，语义检索很难把"删除"和那个三点图标建立直接联系。

这两种失败如果只靠向量化手段硬解，收益很低。正确的做法是引入一层廉价的仲裁。

4.2 分数差仲裁规则

仲裁的第一层不涉及任何模型调用，纯粹用分数差。

我把 top-1 和 top-2 的余弦相似度相减，如果差值大于某个阈值，说明检索结果非常笃定，直接采用 top-1。如果差值很小，说明候选之间语义高度接近，此时不能盲目选，得做进一步确认。

阈值我调过很多轮，最终定在 0.15。大于 0.15 直接信任检索，小于等于 0.15 就进入轻量视觉确认。这个阈值的物理含义是：候选之间的语义距离要足够拉开，否则就默认"文本信息不足以区分目标"。

规则本身非常简单，但它把大量"可能点错"的场景在廉价层直接拦住了，避免在毫秒级检索之后硬着头皮乱点。

4.3 局部视觉确认：一张小图解决图标按钮

仲裁层的第二级才是视觉出场。做法是把 top-2 或 top-3 候选元素的 bounds 集合起来，取一个刚好覆盖它们的外接矩形，从屏幕截图上裁出一小块局部图，然后把这张小图和用户指令一起丢给多模态模型，让它在这两三个候选区域里选一个。

这一步和旧链路的最大区别是图片尺寸和推理范围都极小。旧链路让模型看整个 1920x1080 的界面，模型要把几百个候选元素全部扫一遍才能定位；现在模型只需要看一块可能只有 300x200 像素的小图，且只需要在 2 到 3 个候选里做选择，两者难度完全不同量级。实测单次局部确认的延迟在 150 到 300 毫秒之间，比全图推理快一个数量级。

这个设计同时也继承了 SoM 方案的优点，因为候选元素周围会渲染红框或数字标记，模型不需要输出精确到像素的坐标，只说"第二个候选"就行，极大降低了输出不确定性。

4.4 降级：老方案变成新方案的保险丝

如果局部视觉确认也失败，或检索结果整体置信度过低，我才允许流程跌回完整的视觉定位老链路。这个决定在架构上很关键：它让新方案承担 99% 的常规流量，同时让老方案作为安全网存在。

我把降级条件设置得很保守，宁可多走一次完整视觉定位，也不要为了追求 0.3 秒的指标去硬点一个低置信度的元素。GUI Agent 的错误点击代价通常比慢一点高得多——一步点错，后面的所有步骤全乱，还要额外花几倍时间去修复状态。

事实上完整回归跑下来，真实任务里触发完整视觉兜底的占比只有 2% 左右。这 2% 拖慢的是整体任务 p99 延迟，但保证了正确率不掉。

5. 实战踩坑：短文本、iframe、滚动容器与动态元素

5.1 中文短文本一致性遭遇战

中文界面的短文本语义匹配，比英文要麻烦不少。英文里"Save"和"Save and Exit"在向量空间里天然分得开，但中文的"保存"和"保 存"都可能被切词器搞出不同结果，更别说"确定""确认""好的"这种桌面弹窗三兄弟。

我踩过的坑是：一开始用标准的中文 embedding 模型处理元素描述，发现"删除"和"移除"的余弦相似度高达 0.94，反而"删除"和"删除记录"只有 0.87。后来排查发现，纯粹把短词丢给 embedding 模型，模型因为没有上下文，会把同义词笼统地投影到很近的位置。

解法不是在模型层面，是在数据层面。给元素描述加上了角色前缀和容器上下文之后，相似度区分度立刻拉开：

有没有上下文，向量空间里完全是两种局面。所以这一步我的建议是，遇到短文本区分度问题时先补上下文，再考虑换模型。换模型成本高，效果还不一定抵得上一条好的描述模板。

5.2 iframe 和阴影 DOM 的坐标陷阱

坐标偏移问题在我测试带第三方登录 iframe 的页面时爆发过。可访问性树返回的元素 bounds 只在 iframe 内部有意义，忽略 iframe 自身的屏幕偏移，点击位置会整体偏到 iframe 左上角那一块区域去。

后来我在坐标回投环节统一做了归一化处理：无论树是来自顶层文档还是 iframe 内部，都先定位它所属的 frame，然后把 frame 在整个页面里的累计偏移量加到 bounds 上。遇到嵌套 iframe 就递归累加，直到顶层文档。

阴影 DOM 是另一个容易翻车的点。标准 DOM 查询拿不到 shadow root 内部的元素，CDP 默认的可访问性树有时候也覆盖不全。我的处理是重写元素遍历逻辑，遇到 shadow root 就递归进去解析，而不是只做一层浅遍历。

这两个坑的共性原因是：调试工具拿到的坐标系统并不统一，做跨容器坐标换算时一定要明确当前坐标系是"相对谁的"。我最初统一按视口坐标处理，后续又调了页面滚动因素，才算把坐标漂移问题彻底按死。

5.3 树里有、视口里没有

可访问性树里的元素不一定在当前可视区域内。一个滚动列表中，树里可能同时存在"当前可见的行"和"下方还没滚出来的行"。语义检索只看文本相似度，不会判断元素是否真的在屏幕上。

于是出现了一种很隐蔽的失败：检索命中了目标元素，坐标也在合理范围，但那个元素根本没渲染到当前视口里。点击动作落在屏幕外区域，无效。

解决路径是两步走。第一步，点击前用元素 bounds 与视口矩形做一次相交检测，如果交集面积小于元素本身面积的 50%，判定为"需要先滚动"。第二步，如果检测到目标不在视口内，调用浏览器的滚动容器定位功能，把目标元素滚动到可视区域，然后再重新拿一次 bounds 并执行点击。

这里有个时间窗口问题：滚动后再点击之前，元素坐标可能因为懒加载重新渲染而变化。所以我把"滚动-重新取坐标-点击"封装成一个原子动作，中间不做任何其他查询，避免拿到旧坐标。

5.4 定位和点击之间的时间窗口

最后一个坑来自动态界面。元素定位完成和实际执行点击之间如果间隔过长，界面可能已经发生变化。我遇到过一个登录表单，输入账号密码后，页面会自动隐藏密码可见性切换按钮，如果我的流程里在点击密码框之前还去校验一个别的元素，再回来点击时，目标元素已经消失或移位。

这个问题的根源是定位结果的时效性。后来我加了两个约束：所有定位结果都有 300 毫秒的过期时间；超过过期时间必须重新定位。另外，定位和点击之间的所有中间检查项被砍掉，能并行的检查提前做，不能并行的直接放到点击完成后的异步阶段。

时效性约束对 GUI Agent 尤其重要，因为界面天然是动态的。树结构反映的是"取到树那一个瞬间"的状态，没有任何理由假设它下一秒还成立。

6. 实测结果：延迟分布、准确率变化与适用边界

6.1 一组可复现的对比数据

改造完成后，我对同一批真实任务做了前后对比。测试场景覆盖登录、填表、列表筛选、弹窗操作、后台管理页面，每组场景跑 50 次取中位数，结果如下：

延迟整体下降约 40 倍，和标题里说的吻合。准确率不仅没降，反而有小幅提升。原因也不难解释：旧方案里模型直接输出坐标，一旦点偏就要靠重试纠错，重试还未必保证成功；新方案里定位是基于结构数据命中的，候选元素本身就在正确的可交互集合里，再加上仲裁阶段二次确认，错误点击被拦掉了不少。

6.2 收益最大的场景和不太明显的场景

收益最大的是表单类和列表类操作。这类页面的元素通常有清晰的文本标识和稳定的结构上下文，语义检索命中率极高，且页面元素数量适中，几十个候选的暴力扫描几乎不耗时。

收益不明显的场景有两种。第一种是元素树严重缺失的自定义绘图界面，比如某些数据可视化大屏，大量内容画在 canvas 上，可访问性树里几乎没有可交互节点，检索直接拿不到候选。第二种是高度动态且元素信息极少的手势操作场景，比如地图拖拽、图片剪裁，这类操作本质上不是"定位某个元素"，而是"计算相对位移"，结构数据帮不上忙，该走视觉或坐标计算就走那条路。

我做这套优化时一开始预期所有场景都能提速，实际跑下来才明白：结构化结构越完整的界面，检索方案收益越大；结构越缺失的界面，越应该直接走视觉降级，不要在检索这条路上硬磨。

6.3 这套方案的边界

最后给个诚实的边界说明。这套方案的核心假设是"界面本身存在可访问的、结构化的元素描述"。浏览器页面满足这个假设，大多数基于原生控件的桌面应用满足，常见移动应用也满足。但以下情况不满足：纯 canvas 绘制的大屏可视化、游戏内界面、远程桌面传输画面、以及那些开发时没有接入无障碍支持的自绘控件。

这些场景我会直接断言"检索不可用"，而不是尝试硬套。万金油方案往往两头不到岸，明确每条技术路径的适用边界，反而能让你在真正出问题时更快切换。

另外，这套方案里 embedding 模型的选型也值得一提。中文界面优先选针对中文优化的轻量模型，比如 bge-small-zh 这一档，单次 embedding 延迟在几毫秒到几十毫秒之间，效果好且足够快。我也试过直接用通用的大型 embedding API，准确率没有显著提升，但延迟和成本增加明显，最后没有采用。

最后再分享一个我目前正在做的小优化：把每次成功定位的"指令 + 页面指纹 + 目标元素 id + 置信度"记录成一个反馈样本库，样本攒多了以后，对高频页面可以完全跳过检索和仲裁，直接按页面的历史最优结果命中。这样即使在最极端的情况下，也能让定位延迟进一步逼近 0.1 秒以内。当然，这只是锦上添花，核心的思路还是那一句话：GUI Agent 的定位不是让模型在你面前猜谜，而是把现成的界面结构变成一条可以快速检索的索引，模型只需要在关键决策点上做小范围确认就够了。