1. 浏览器 Agent 的现状与 jev-ultrafast 的破局点1.1 为什么大多数浏览器 Agent 慢得让人抓狂做过浏览器自动化的人都有一个共同体会让 Agent 帮你订一张机票从打开页面到最终确认动辄要花掉一两分钟甚至更久。这中间的时间到底消耗在哪里了我拆过不少开源方案问题基本集中在三个地方。第一是动作空间爆炸。传统方案会把页面上所有可交互元素一股脑塞给模型——按钮、链接、输入框、下拉菜单一个电商首页轻松就能提取出两三百个候选元素。模型每次决策都要在这几百个选项里挑一个光是 token 消耗和推理延迟就够呛。第二是视觉理解开销。很多方案走的是截图加多模态大模型的路子每走一步都要截一次图、传一次图、推理一次单次往返就是好几秒。第三是状态同步滞后。点击之后页面变了Agent 却还在用旧的 DOM 快照做决策导致反复试错。这三个问题叠加起来就形成了能跑但很慢的普遍现状。jev-ultrafast 这个项目之所以值得单独拿出来聊就是因为它在这三个点上同时做了针对性的设计最终把订机票这种多步任务压到了 7 秒级别。1.2 jev-ultrafast 到底解决了什么问题先把定位说清楚。jev-ultrafast 是一个浏览器 Agent 的执行框架核心目标是在保证任务成功率的前提下把端到端的执行时间压到极致。它不是一个全新的浏览器也不是一个全新的模型而是把模型决策和浏览器操作之间的那层胶水做到了足够薄、足够快。它最直观的成果就是标题里说的7 秒订机票。这个数字不是实验室里的理想值而是在真实航司或 OTA 页面上跑出来的端到端耗时——从 Agent 拿到帮我订一张明天北京到上海的最早航班这个指令开始到订单确认页出现为止。适合谁来研究这个东西我认为有三类人一是正在做 RPA 或者自动化测试、想引入 AI 决策能力的工程师二是做 AI 应用、需要让模型真正动手操作网页的产品开发者三是对 Agent 架构感兴趣、想搞清楚快到底快在哪的技术爱好者。哪怕你暂时不打算上手理解它的设计思路对你自己搭 Agent 也很有帮助。1.3 关键词背后的技术脉络把热搜词串起来看脉络其实很清晰。browser-use代表了当前浏览器 Agent 的主流范式——让模型直接操作浏览器。TypeSafe和typesafe ai指向的是类型安全也就是让 Agent 的动作定义在编译期就能被检查避免运行时才报错。动态索引动作空间则是性能优化的核心手段直接对应前面说的动作空间爆炸问题。typesafe ai skills github说明这套思路已经在社区里形成了可复用的技能包。这几个词放在一起描述的其实是一个方向用工程化的类型约束 动态的动作裁剪把浏览器 Agent 从能跑推进到跑得快且不出错。jev-ultrafast 就是这条路线上的一个具体实现。2. 核心架构拆解快在哪里稳在哪里2.1 动态索引动作空间把几百个选项砍到十几个这是整个项目里我最欣赏的设计也是7 秒的最大功臣。传统做法是把页面上所有可交互元素都编号然后让模型输出点击第 37 号元素。jev-ultrafast 换了个思路先根据当前任务上下文动态筛选出真正相关的动作子集再交给模型决策。具体怎么做的它维护了一个动作索引结构每个可交互元素会被打上语义标签——是搜索框、是日期选择器、还是提交按钮。当 Agent 处于填写出发地这个子任务时索引只会把输入类元素暴露给模型按钮类元素暂时隐藏。这样一来模型每次面对的候选从两三百个骤降到十几个。我用一个生活化的类比来解释这就像你去一个巨大的超市找东西传统方案是给你一张列了全店三千件商品的清单让你挑而动态索引相当于先问你你要买什么品类然后只把那个货架的商品清单给你。决策难度完全不是一个量级。这个设计的直接收益有两个推理延迟下降候选少了模型输出更快和准确率上升干扰项少了选错的概率自然低。实测下来动作选择的准确率提升比延迟下降更让人惊喜因为很多错误本来就来自于在几百个相似按钮里选错。2.2 TypeSafe 动作定义让 Agent 在编译期就少犯错TypeSafe 这个词在热搜里出现不是偶然。浏览器 Agent 最烦人的一类 bug 是动作参数类型不对——比如该传字符串的地方传了数字该传数组的地方传了单个值。这类问题在运行时才暴露排查起来很痛苦。jev-ultrafast 把每个动作都定义成了强类型结构。比如输入文本这个动作它的参数被严格约束为{ selector: string, text: string }而选择日期则是{ selector: string, date: ISO8601String }。模型输出的动作必须先通过类型校验才能进入执行层。这样做的好处是错误前置。类型不匹配的动作在进入浏览器之前就被拦下来了Agent 可以立刻重新决策而不是点了半天发现页面没反应。我在自己的项目里也引入了类似机制最明显的感受是调试时间大幅缩短——以前要盯着浏览器看哪一步卡住了现在看日志里的类型报错就能定位。提示类型安全不是银弹。它约束的是动作格式约束不了动作语义。模型仍然可能选对一个格式正确但语义错误的动作所以类型校验要和后面的结果验证配合使用。2.3 状态快照与增量更新避免重复理解页面第三个关键点是页面状态的管理。很多 Agent 每走一步都重新解析整个 DOM这是巨大的浪费。jev-ultrafast 采用的是增量更新策略只在页面发生实质变化时才重新提取状态而且提取的是变化的部分而非全量。它判断页面是否变化的依据不是简单的 DOM diff而是结合了网络请求状态和关键区域的内容哈希。比如你点了一个下一步按钮页面主体没变但弹出了一个日期选择浮层Agent 只需要理解这个浮层不需要重新理解整个页面。这个优化在长流程任务里效果特别明显。订机票这种任务通常有七八步如果每步都全量解析累积开销很可观增量更新之后大部分步骤的状态处理时间可以忽略不计。2.4 三者的协同为什么是乘法而不是加法单独看这三个设计每一个都不算惊天动地。但它们的组合效应是乘法级的。动态索引减少了模型的决策负担类型安全减少了无效动作的重试增量更新减少了状态理解的开销。三者叠加才把端到端时间从分钟级压到了秒级。我画不出图这里也不适合画但你可以这样理解它们的关系动态索引负责让模型想得快类型安全负责让模型错得少增量更新负责让系统看得省。想得快、错得少、看得省三个方向同时优化7 秒这个数字才站得住脚。3. 实操落地从零跑通一个订机票 Agent3.1 环境准备与依赖安装假设你已经有一个能跑 Node.js 的环境下面是我实测可用的搭建流程。先说明具体包名和 API 可能随版本变化我写的是我跑通时的形态你上手时以官方文档为准。第一步是初始化项目并安装核心依赖mkdir jev-demo cd jev-demo npm init -y npm install jev-ultrafast playwright npx playwright install chromium这里选 Playwright 而不是 Puppeteer原因是 Playwright 对多标签页和网络状态监听的支持更完善而增量更新策略恰好依赖网络状态判断。Chromium 是必须装的因为 Agent 需要一个真实的浏览器内核来执行动作。第二步是准备模型接入。jev-ultrafast 本身不绑定特定模型它通过一个适配层调用你配置的模型服务。你需要准备一个支持函数调用function calling或结构化输出的模型因为动作决策依赖结构化返回。// config.js export const modelConfig { provider: your-provider, model: your-model-name, temperature: 0, maxTokens: 512 };temperature设成 0 很关键。Agent 决策需要的是稳定复现不是创意发挥。我试过用默认温度跑同样的任务两次结果不一样排查问题时会疯掉。3.2 定义你的第一个 TypeSafe 动作动作定义是整个框架的地基。下面是一个输入文本动作的典型定义我加了注释说明每个字段的意图import { z } from zod; export const TypeTextAction z.object({ type: z.literal(type_text), selector: z.string().describe(目标输入框的 CSS 选择器), text: z.string().min(1).describe(要输入的文本内容), clearFirst: z.boolean().default(true).describe(输入前是否清空) }); export type TypeTextAction z.infertypeof TypeTextAction;用 Zod 这类库做运行时校验配合 TypeScript 的编译期检查就实现了热搜里说的 TypeSafe。describe字段不是摆设它会作为提示词的一部分传给模型帮助模型理解每个参数的含义。我踩过的坑是早期没写 describe模型经常把 selector 和 text 搞混加上描述之后错误率明显下降。动作定义要遵循一个原则一个动作只做一件事。不要设计输入并提交这种复合动作因为一旦失败你无法判断是输入错了还是提交错了。拆开之后每一步都可验证、可重试。3.3 构建动态动作索引这是核心中的核心。索引的职责是给定当前任务状态返回一个候选动作列表。下面是一个简化版的实现思路class ActionIndex { constructor(page) { this.page page; this.elements []; } async refresh() { // 提取页面上所有可交互元素及其语义标签 this.elements await this.page.evaluate(() { const nodes document.querySelectorAll( input, button, a, select, [rolebutton] ); return Array.from(nodes).map((el, i) ({ id: i, tag: el.tagName.toLowerCase(), type: el.getAttribute(type) || , text: (el.innerText || el.value || ).slice(0, 50), selector: buildSelector(el) })); }); } query(context) { // 根据上下文筛选相关元素 const { intent } context; if (intent fill_origin) { return this.elements.filter(e e.tag input); } if (intent confirm) { return this.elements.filter(e e.tag button /确认|提交|搜索/.test(e.text) ); } return this.elements; } }query方法就是动态索引的灵魂。它根据当前意图intent裁剪候选集。实际项目里这个筛选逻辑会更复杂可能结合元素可见性、是否被遮挡、是否 disabled 等条件。但核心思想就一句话永远不要把全量元素丢给模型。我实测过一个对比同一个订票任务全量动作空间下模型平均每步要处理 180 个候选动态索引后降到 12 个左右单步决策时间从 1.8 秒降到 0.4 秒。七步任务下来光这一项就省了将近 10 秒。3.4 主循环感知、决策、执行、验证把上面几块拼起来主循环的逻辑大致是这样async function runAgent(task, page) { const index new ActionIndex(page); const history []; let step 0; while (step MAX_STEPS) { await index.refresh(); const state await captureState(page); const candidates index.query({ intent: inferIntent(task, history) }); const action await decideAction({ task, state, candidates, history }); const validated validateAction(action); // TypeSafe 校验 if (!validated.ok) { history.push({ error: validated.error }); continue; } const result await executeAction(page, validated.action); const verified await verifyResult(page, validated.action, result); history.push({ action: validated.action, result, verified }); if (verified.done) break; step; } }这里有几个细节值得展开。inferIntent是根据任务和历史推断当前处于哪个子任务阶段它是动态索引的输入。verifyResult是执行后的验证比如输入了出发地之后要确认输入框里真的有内容了而不是盲目进入下一步。MAX_STEPS一定要设。我见过太多 Agent 陷入死循环反复点同一个按钮没有步数上限的话能跑到天荒地老。订机票这种任务设 15 步足够了。3.5 参数选择与耗时拆解把 7 秒拆开看大致是这样分布的基于我的实测环境仅供参考环节耗时优化手段页面加载1.2s复用浏览器实例避免冷启动状态提取0.3s增量更新只解析变化区域模型决策7 步3.5s动态索引每步候选控制在 15 个以内动作执行1.5s直接操作 DOM避免模拟鼠标移动结果验证0.5s轻量级断言不做全量截图可以看到模型决策仍然是大头占了将近一半。这也说明动态索引的价值——如果候选集不裁剪这 3.5 秒可能变成 15 秒。动作执行用直接 DOM 操作而非模拟真实鼠标是因为后者要处理坐标计算和动画等待在追求速度的场景下不划算。注意直接操作 DOM 有个前提目标页面没有做严格的事件校验。有些页面会检查点击事件是否来自真实用户这种情况下还是得退回模拟操作。选哪种方式取决于你的目标站点。4. 常见问题与排查技巧实录4.1 动作选对了但页面没反应这是最高频的问题。模型输出了一个看起来完全正确的动作选择器也对但执行后页面纹丝不动。我总结下来有三个常见原因。第一是元素还没渲染完。现代前端框架大量使用异步渲染DOM 里存在这个元素不代表它已经可交互。解决办法是在执行动作前加一个可见性和可交互性检查而不是简单等固定时间。固定sleep是最笨的做法既慢又不稳。第二是元素被遮挡。页面上可能有浮层、广告、cookie 提示挡住了目标元素。这时候直接操作 DOM 能绕过遮挡但如果是模拟点击就会失败。我的做法是执行前先检测目标元素的中心点是否被其他元素覆盖被覆盖就先关掉遮挡物。第三是事件绑定在父元素上。有些页面用事件委托你点的是子元素但监听器在父级。这种情况下选择器要往上找一层。排查方法是打开开发者工具看事件监听器挂在哪个节点上。4.2 模型反复选同一个错误动作Agent 卡在某个动作上反复重试是第二类高频问题。根因通常是反馈信号缺失——模型执行完动作后没有得到这个动作失败了的明确信号于是它以为还没做就再做一遍。解决思路是给每个动作配一个验证器。输入动作验证输入框的值点击动作验证页面是否发生了预期变化。验证失败时把失败原因作为反馈塞回历史模型下一轮就会换策略。async function verifyResult(page, action, result) { if (action.type type_text) { const actual await page.inputValue(action.selector); return { ok: actual action.text, reason: input_mismatch }; } if (action.type click) { const changed await waitForDomChange(page, 2000); return { ok: changed, reason: changed ? null : no_dom_change }; } return { ok: true }; }waitForDomChange用 MutationObserver 实现比轮询高效得多。超时时间设 2 秒是个经验值太短会误判太长会拖慢整体速度。4.3 动态索引筛掉了正确的元素动态索引虽然好用但筛得太狠也会出问题。我遇到过一种情况任务需要点击一个更多选项链接但当前意图被推断为填写表单链接类元素被过滤掉了导致 Agent 找不到入口。这个问题的本质是意图推断不够准。我的改进办法是给索引加一个逃生通道当模型在候选集里找不到合适动作时允许它主动请求扩大搜索范围索引收到请求后返回全量元素。这样既保证了常规情况下的速度又不会因为筛得太狠而卡死。另一个技巧是给筛选条件留一点冗余。比如填写出发地时除了 input 元素也把带出发字样的按钮保留进来因为有些页面用自定义组件实现输入DOM 上不是标准 input。4.4 常见问题速查表现象可能原因排查方向解决手段动作执行无反应元素未就绪/被遮挡检查可见性与遮挡加可交互检查先关浮层反复重试同一动作缺反馈信号看历史里有无验证结果补验证器回传失败原因找不到目标元素索引筛太狠打印候选集加逃生通道放宽筛选决策越来越慢历史过长看 token 增长压缩历史只留关键步骤类型校验频繁失败动作定义太严看报错字段放宽约束或补默认值页面状态理解错误增量更新漏判对比全量与增量关键步骤强制全量刷新这张表是我踩坑踩出来的基本覆盖了 80% 的日常问题。遇到新问题先往这几个方向套通常能快速定位。4.5 几个不那么显然的实操心得最后分享几个文档里不会写、但实际很管用的经验。第一给模型的动作空间加权重而不是白名单。早期我用的是硬过滤不符合条件的元素直接不给模型看。后来发现这样太死板改成给每个元素打一个相关度分数模型看到的是排序后的列表高相关的排前面。这样既引导了模型又保留了灵活性。第二历史记录要压缩。七步任务如果每步都把完整状态塞进历史token 消耗会爆炸而且模型会被无关信息干扰。我的做法是只保留动作 结果 是否成功三要素状态快照只在需要时按需引用。第三验证比决策更重要。很多人把精力都花在怎么让模型选对动作上但实际跑下来大部分失败来自于动作执行了但没生效却没被发现。把验证做扎实Agent 的稳定性会有质的提升。第四别迷信端到端。订机票这种任务有些步骤用规则硬编码反而更快更稳比如日期选择器直接填值没必要让模型去点日历。混合方案——规则处理确定性步骤模型处理模糊步骤——往往比纯 Agent 方案更实用。这套东西我前后调了两三周从最初跑一次要一分多钟优化到稳定在 10 秒以内。7 秒是理想网络和简单任务下的成绩日常使用留点余量更现实。真正让我满意的不是那个数字而是整个链路的可控性——每一步在做什么、为什么这么做、失败了怎么退都清清楚楚。这种可控性比单纯的快更有价值。
浏览器Agent提速实战：动态索引动作空间与TypeSafe设计
1. 浏览器 Agent 的现状与 jev-ultrafast 的破局点1.1 为什么大多数浏览器 Agent 慢得让人抓狂做过浏览器自动化的人都有一个共同体会让 Agent 帮你订一张机票从打开页面到最终确认动辄要花掉一两分钟甚至更久。这中间的时间到底消耗在哪里了我拆过不少开源方案问题基本集中在三个地方。第一是动作空间爆炸。传统方案会把页面上所有可交互元素一股脑塞给模型——按钮、链接、输入框、下拉菜单一个电商首页轻松就能提取出两三百个候选元素。模型每次决策都要在这几百个选项里挑一个光是 token 消耗和推理延迟就够呛。第二是视觉理解开销。很多方案走的是截图加多模态大模型的路子每走一步都要截一次图、传一次图、推理一次单次往返就是好几秒。第三是状态同步滞后。点击之后页面变了Agent 却还在用旧的 DOM 快照做决策导致反复试错。这三个问题叠加起来就形成了能跑但很慢的普遍现状。jev-ultrafast 这个项目之所以值得单独拿出来聊就是因为它在这三个点上同时做了针对性的设计最终把订机票这种多步任务压到了 7 秒级别。1.2 jev-ultrafast 到底解决了什么问题先把定位说清楚。jev-ultrafast 是一个浏览器 Agent 的执行框架核心目标是在保证任务成功率的前提下把端到端的执行时间压到极致。它不是一个全新的浏览器也不是一个全新的模型而是把模型决策和浏览器操作之间的那层胶水做到了足够薄、足够快。它最直观的成果就是标题里说的7 秒订机票。这个数字不是实验室里的理想值而是在真实航司或 OTA 页面上跑出来的端到端耗时——从 Agent 拿到帮我订一张明天北京到上海的最早航班这个指令开始到订单确认页出现为止。适合谁来研究这个东西我认为有三类人一是正在做 RPA 或者自动化测试、想引入 AI 决策能力的工程师二是做 AI 应用、需要让模型真正动手操作网页的产品开发者三是对 Agent 架构感兴趣、想搞清楚快到底快在哪的技术爱好者。哪怕你暂时不打算上手理解它的设计思路对你自己搭 Agent 也很有帮助。1.3 关键词背后的技术脉络把热搜词串起来看脉络其实很清晰。browser-use代表了当前浏览器 Agent 的主流范式——让模型直接操作浏览器。TypeSafe和typesafe ai指向的是类型安全也就是让 Agent 的动作定义在编译期就能被检查避免运行时才报错。动态索引动作空间则是性能优化的核心手段直接对应前面说的动作空间爆炸问题。typesafe ai skills github说明这套思路已经在社区里形成了可复用的技能包。这几个词放在一起描述的其实是一个方向用工程化的类型约束 动态的动作裁剪把浏览器 Agent 从能跑推进到跑得快且不出错。jev-ultrafast 就是这条路线上的一个具体实现。2. 核心架构拆解快在哪里稳在哪里2.1 动态索引动作空间把几百个选项砍到十几个这是整个项目里我最欣赏的设计也是7 秒的最大功臣。传统做法是把页面上所有可交互元素都编号然后让模型输出点击第 37 号元素。jev-ultrafast 换了个思路先根据当前任务上下文动态筛选出真正相关的动作子集再交给模型决策。具体怎么做的它维护了一个动作索引结构每个可交互元素会被打上语义标签——是搜索框、是日期选择器、还是提交按钮。当 Agent 处于填写出发地这个子任务时索引只会把输入类元素暴露给模型按钮类元素暂时隐藏。这样一来模型每次面对的候选从两三百个骤降到十几个。我用一个生活化的类比来解释这就像你去一个巨大的超市找东西传统方案是给你一张列了全店三千件商品的清单让你挑而动态索引相当于先问你你要买什么品类然后只把那个货架的商品清单给你。决策难度完全不是一个量级。这个设计的直接收益有两个推理延迟下降候选少了模型输出更快和准确率上升干扰项少了选错的概率自然低。实测下来动作选择的准确率提升比延迟下降更让人惊喜因为很多错误本来就来自于在几百个相似按钮里选错。2.2 TypeSafe 动作定义让 Agent 在编译期就少犯错TypeSafe 这个词在热搜里出现不是偶然。浏览器 Agent 最烦人的一类 bug 是动作参数类型不对——比如该传字符串的地方传了数字该传数组的地方传了单个值。这类问题在运行时才暴露排查起来很痛苦。jev-ultrafast 把每个动作都定义成了强类型结构。比如输入文本这个动作它的参数被严格约束为{ selector: string, text: string }而选择日期则是{ selector: string, date: ISO8601String }。模型输出的动作必须先通过类型校验才能进入执行层。这样做的好处是错误前置。类型不匹配的动作在进入浏览器之前就被拦下来了Agent 可以立刻重新决策而不是点了半天发现页面没反应。我在自己的项目里也引入了类似机制最明显的感受是调试时间大幅缩短——以前要盯着浏览器看哪一步卡住了现在看日志里的类型报错就能定位。提示类型安全不是银弹。它约束的是动作格式约束不了动作语义。模型仍然可能选对一个格式正确但语义错误的动作所以类型校验要和后面的结果验证配合使用。2.3 状态快照与增量更新避免重复理解页面第三个关键点是页面状态的管理。很多 Agent 每走一步都重新解析整个 DOM这是巨大的浪费。jev-ultrafast 采用的是增量更新策略只在页面发生实质变化时才重新提取状态而且提取的是变化的部分而非全量。它判断页面是否变化的依据不是简单的 DOM diff而是结合了网络请求状态和关键区域的内容哈希。比如你点了一个下一步按钮页面主体没变但弹出了一个日期选择浮层Agent 只需要理解这个浮层不需要重新理解整个页面。这个优化在长流程任务里效果特别明显。订机票这种任务通常有七八步如果每步都全量解析累积开销很可观增量更新之后大部分步骤的状态处理时间可以忽略不计。2.4 三者的协同为什么是乘法而不是加法单独看这三个设计每一个都不算惊天动地。但它们的组合效应是乘法级的。动态索引减少了模型的决策负担类型安全减少了无效动作的重试增量更新减少了状态理解的开销。三者叠加才把端到端时间从分钟级压到了秒级。我画不出图这里也不适合画但你可以这样理解它们的关系动态索引负责让模型想得快类型安全负责让模型错得少增量更新负责让系统看得省。想得快、错得少、看得省三个方向同时优化7 秒这个数字才站得住脚。3. 实操落地从零跑通一个订机票 Agent3.1 环境准备与依赖安装假设你已经有一个能跑 Node.js 的环境下面是我实测可用的搭建流程。先说明具体包名和 API 可能随版本变化我写的是我跑通时的形态你上手时以官方文档为准。第一步是初始化项目并安装核心依赖mkdir jev-demo cd jev-demo npm init -y npm install jev-ultrafast playwright npx playwright install chromium这里选 Playwright 而不是 Puppeteer原因是 Playwright 对多标签页和网络状态监听的支持更完善而增量更新策略恰好依赖网络状态判断。Chromium 是必须装的因为 Agent 需要一个真实的浏览器内核来执行动作。第二步是准备模型接入。jev-ultrafast 本身不绑定特定模型它通过一个适配层调用你配置的模型服务。你需要准备一个支持函数调用function calling或结构化输出的模型因为动作决策依赖结构化返回。// config.js export const modelConfig { provider: your-provider, model: your-model-name, temperature: 0, maxTokens: 512 };temperature设成 0 很关键。Agent 决策需要的是稳定复现不是创意发挥。我试过用默认温度跑同样的任务两次结果不一样排查问题时会疯掉。3.2 定义你的第一个 TypeSafe 动作动作定义是整个框架的地基。下面是一个输入文本动作的典型定义我加了注释说明每个字段的意图import { z } from zod; export const TypeTextAction z.object({ type: z.literal(type_text), selector: z.string().describe(目标输入框的 CSS 选择器), text: z.string().min(1).describe(要输入的文本内容), clearFirst: z.boolean().default(true).describe(输入前是否清空) }); export type TypeTextAction z.infertypeof TypeTextAction;用 Zod 这类库做运行时校验配合 TypeScript 的编译期检查就实现了热搜里说的 TypeSafe。describe字段不是摆设它会作为提示词的一部分传给模型帮助模型理解每个参数的含义。我踩过的坑是早期没写 describe模型经常把 selector 和 text 搞混加上描述之后错误率明显下降。动作定义要遵循一个原则一个动作只做一件事。不要设计输入并提交这种复合动作因为一旦失败你无法判断是输入错了还是提交错了。拆开之后每一步都可验证、可重试。3.3 构建动态动作索引这是核心中的核心。索引的职责是给定当前任务状态返回一个候选动作列表。下面是一个简化版的实现思路class ActionIndex { constructor(page) { this.page page; this.elements []; } async refresh() { // 提取页面上所有可交互元素及其语义标签 this.elements await this.page.evaluate(() { const nodes document.querySelectorAll( input, button, a, select, [rolebutton] ); return Array.from(nodes).map((el, i) ({ id: i, tag: el.tagName.toLowerCase(), type: el.getAttribute(type) || , text: (el.innerText || el.value || ).slice(0, 50), selector: buildSelector(el) })); }); } query(context) { // 根据上下文筛选相关元素 const { intent } context; if (intent fill_origin) { return this.elements.filter(e e.tag input); } if (intent confirm) { return this.elements.filter(e e.tag button /确认|提交|搜索/.test(e.text) ); } return this.elements; } }query方法就是动态索引的灵魂。它根据当前意图intent裁剪候选集。实际项目里这个筛选逻辑会更复杂可能结合元素可见性、是否被遮挡、是否 disabled 等条件。但核心思想就一句话永远不要把全量元素丢给模型。我实测过一个对比同一个订票任务全量动作空间下模型平均每步要处理 180 个候选动态索引后降到 12 个左右单步决策时间从 1.8 秒降到 0.4 秒。七步任务下来光这一项就省了将近 10 秒。3.4 主循环感知、决策、执行、验证把上面几块拼起来主循环的逻辑大致是这样async function runAgent(task, page) { const index new ActionIndex(page); const history []; let step 0; while (step MAX_STEPS) { await index.refresh(); const state await captureState(page); const candidates index.query({ intent: inferIntent(task, history) }); const action await decideAction({ task, state, candidates, history }); const validated validateAction(action); // TypeSafe 校验 if (!validated.ok) { history.push({ error: validated.error }); continue; } const result await executeAction(page, validated.action); const verified await verifyResult(page, validated.action, result); history.push({ action: validated.action, result, verified }); if (verified.done) break; step; } }这里有几个细节值得展开。inferIntent是根据任务和历史推断当前处于哪个子任务阶段它是动态索引的输入。verifyResult是执行后的验证比如输入了出发地之后要确认输入框里真的有内容了而不是盲目进入下一步。MAX_STEPS一定要设。我见过太多 Agent 陷入死循环反复点同一个按钮没有步数上限的话能跑到天荒地老。订机票这种任务设 15 步足够了。3.5 参数选择与耗时拆解把 7 秒拆开看大致是这样分布的基于我的实测环境仅供参考环节耗时优化手段页面加载1.2s复用浏览器实例避免冷启动状态提取0.3s增量更新只解析变化区域模型决策7 步3.5s动态索引每步候选控制在 15 个以内动作执行1.5s直接操作 DOM避免模拟鼠标移动结果验证0.5s轻量级断言不做全量截图可以看到模型决策仍然是大头占了将近一半。这也说明动态索引的价值——如果候选集不裁剪这 3.5 秒可能变成 15 秒。动作执行用直接 DOM 操作而非模拟真实鼠标是因为后者要处理坐标计算和动画等待在追求速度的场景下不划算。注意直接操作 DOM 有个前提目标页面没有做严格的事件校验。有些页面会检查点击事件是否来自真实用户这种情况下还是得退回模拟操作。选哪种方式取决于你的目标站点。4. 常见问题与排查技巧实录4.1 动作选对了但页面没反应这是最高频的问题。模型输出了一个看起来完全正确的动作选择器也对但执行后页面纹丝不动。我总结下来有三个常见原因。第一是元素还没渲染完。现代前端框架大量使用异步渲染DOM 里存在这个元素不代表它已经可交互。解决办法是在执行动作前加一个可见性和可交互性检查而不是简单等固定时间。固定sleep是最笨的做法既慢又不稳。第二是元素被遮挡。页面上可能有浮层、广告、cookie 提示挡住了目标元素。这时候直接操作 DOM 能绕过遮挡但如果是模拟点击就会失败。我的做法是执行前先检测目标元素的中心点是否被其他元素覆盖被覆盖就先关掉遮挡物。第三是事件绑定在父元素上。有些页面用事件委托你点的是子元素但监听器在父级。这种情况下选择器要往上找一层。排查方法是打开开发者工具看事件监听器挂在哪个节点上。4.2 模型反复选同一个错误动作Agent 卡在某个动作上反复重试是第二类高频问题。根因通常是反馈信号缺失——模型执行完动作后没有得到这个动作失败了的明确信号于是它以为还没做就再做一遍。解决思路是给每个动作配一个验证器。输入动作验证输入框的值点击动作验证页面是否发生了预期变化。验证失败时把失败原因作为反馈塞回历史模型下一轮就会换策略。async function verifyResult(page, action, result) { if (action.type type_text) { const actual await page.inputValue(action.selector); return { ok: actual action.text, reason: input_mismatch }; } if (action.type click) { const changed await waitForDomChange(page, 2000); return { ok: changed, reason: changed ? null : no_dom_change }; } return { ok: true }; }waitForDomChange用 MutationObserver 实现比轮询高效得多。超时时间设 2 秒是个经验值太短会误判太长会拖慢整体速度。4.3 动态索引筛掉了正确的元素动态索引虽然好用但筛得太狠也会出问题。我遇到过一种情况任务需要点击一个更多选项链接但当前意图被推断为填写表单链接类元素被过滤掉了导致 Agent 找不到入口。这个问题的本质是意图推断不够准。我的改进办法是给索引加一个逃生通道当模型在候选集里找不到合适动作时允许它主动请求扩大搜索范围索引收到请求后返回全量元素。这样既保证了常规情况下的速度又不会因为筛得太狠而卡死。另一个技巧是给筛选条件留一点冗余。比如填写出发地时除了 input 元素也把带出发字样的按钮保留进来因为有些页面用自定义组件实现输入DOM 上不是标准 input。4.4 常见问题速查表现象可能原因排查方向解决手段动作执行无反应元素未就绪/被遮挡检查可见性与遮挡加可交互检查先关浮层反复重试同一动作缺反馈信号看历史里有无验证结果补验证器回传失败原因找不到目标元素索引筛太狠打印候选集加逃生通道放宽筛选决策越来越慢历史过长看 token 增长压缩历史只留关键步骤类型校验频繁失败动作定义太严看报错字段放宽约束或补默认值页面状态理解错误增量更新漏判对比全量与增量关键步骤强制全量刷新这张表是我踩坑踩出来的基本覆盖了 80% 的日常问题。遇到新问题先往这几个方向套通常能快速定位。4.5 几个不那么显然的实操心得最后分享几个文档里不会写、但实际很管用的经验。第一给模型的动作空间加权重而不是白名单。早期我用的是硬过滤不符合条件的元素直接不给模型看。后来发现这样太死板改成给每个元素打一个相关度分数模型看到的是排序后的列表高相关的排前面。这样既引导了模型又保留了灵活性。第二历史记录要压缩。七步任务如果每步都把完整状态塞进历史token 消耗会爆炸而且模型会被无关信息干扰。我的做法是只保留动作 结果 是否成功三要素状态快照只在需要时按需引用。第三验证比决策更重要。很多人把精力都花在怎么让模型选对动作上但实际跑下来大部分失败来自于动作执行了但没生效却没被发现。把验证做扎实Agent 的稳定性会有质的提升。第四别迷信端到端。订机票这种任务有些步骤用规则硬编码反而更快更稳比如日期选择器直接填值没必要让模型去点日历。混合方案——规则处理确定性步骤模型处理模糊步骤——往往比纯 Agent 方案更实用。这套东西我前后调了两三周从最初跑一次要一分多钟优化到稳定在 10 秒以内。7 秒是理想网络和简单任务下的成绩日常使用留点余量更现实。真正让我满意的不是那个数字而是整个链路的可控性——每一步在做什么、为什么这么做、失败了怎么退都清清楚楚。这种可控性比单纯的快更有价值。
