browser-use/jev-ultrafast

是什么

Jev Ultrafast 是一个开源的 浏览器代理，允许小型语言模型（LLM）驱动网页以实现单一自然语言目标。其工作方式是反复获取页面快照，将每个可见控件（按钮、组合框、文本框等）转换为编号表格，然后让 LLM 从该表格中选择 一项操作（例如 CLICK、TYPE_TEXT、SELECT）和 一个目标元素。选定的操作在浏览器中执行，获取下一个快照，循环重复，直到模型返回 DONE 或任务被验证为完成。

其核心创新在于 动态、索引化的操作空间：不是使用固定的硬编码选择器，而是代理在每次循环迭代中构建新的可能操作列表，因此可以适应页面变化、加载延迟和 UI 动画，且 每次决策仅需一次网络往返。

如何工作（概览）

快照 – 通过 Browser Harness 协议，在 Chrome 中运行极小的 JavaScript（snapshot.js），原子性地读取 DOM，并返回包含控件类型、标签和当前值的 UI 元素列表。
提示构造 – Python 端（model.py）将快照和用户提供的目标格式化为短提示，发送给 纯文本 LLM（例如 OpenRouter 的 inception/mercury‑2.5）。
LLM 决策 – 模型返回一个包含以下内容的 JSON 对象：
- operation – CLICK、TYPE_TEXT、SELECT、SCROLL_UP、SCROLL_DOWN、WAIT、DONE、BLOCKED 之一。
- target – 可接受该操作的元素索引。
- （对于 TYPE_TEXT）要输入的文本。
执行 – 选定的操作通过 harness 发送到 Chrome。执行前，代理会验证目标元素仍存在、未被遮挡，并与预期控件类型匹配。
循环 – 步骤 1–4 重复执行，直到返回 DONE，并可选地通过验证步骤确认目标已达成。

由于快照仅包含 可见文本 和控件元数据，模型永远不会看到大型页面数据块，从而保持提示短小且延迟低。

为何重要

速度 – 演示可在约 7 秒内完成完整的 Google Flights 搜索，仅使用约 100 次浏览器协议调用（而朴素实现需 >1,000 次）。设计上刻意最小化往返次数。
通用性 – 策略中未嵌入任何站点特定脚本。同一模型可轻松用于完全不同的任务（航班、维基百科导航、酒店搜索），只需更改目标字符串即可。
安全性 – 代理从不生成原始选择器、JavaScript 或 shell 命令。所有模型输出必须为有效 JSON，并在执行前与当前 DOM 重新验证。
透明性 – 可选的 UI 检查器可显示编号元素表、操作概率和目标概率，使决策过程可观测且可调试。

快速开始（Linux/macOS，Python 3.11+）

# 1. 克隆仓库
git clone https://github.com/browser-use/jev-ultrafast.git
cd jev-ultrafast

# 2. 安装依赖（使用 uv，或 pip 也可）
uv sync          # 创建虚拟环境并安装 Python 依赖
# Browser‑harness（Chrome 远程调试）会自动拉取

# 3. 配置 API 密钥
cp .env.example .env
# 编辑 .env 并添加：
#   TYPESAFE_API_KEY=…   # TypeSafe 策略服务用
#   TEXT_MODEL_API_KEY=… # OpenRouter（或兼容）密钥

# 4. 运行演示 UI
uv run jev
# 在 Chrome 中打开 http://127.0.0.1:8766，提示时启用远程调试，
# 然后点击“Start demo → Run automatically”。

在代码中使用库

from jev_ultrafast import Agent

with Agent(
    "https://www.google.com/travel/flights?hl=en",
    "查找 2026 年 9 月 20 日从苏黎世到伦敦的单程航班，1 名成人经济舱。当匹配的航班选项可见时停止。",
) as agent:
    for state in agent.run():
        print(state["elapsed_ms"], state["status"])  # 进度信息

使用与演示相同的 uv run --env-file .env python your_script.py 命令运行。

仓库还包含小型示例脚本（examples/run.py、examples/flights.py），展示如何在不修改核心代理的情况下更改起始 URL 和目标。

限制（如文档所述）

仅支持标准 HTML/ARIA 控件；复杂的组件如自定义画布编辑器、文件上传对话框、弹出窗口或深层阴影 DOM 树在本 MVP 中不支持。
LLM 仅用于 文本生成（TYPE_TEXT）。其他决策（点击哪个按钮、选择哪个选项）由接收编号元素表的策略模型做出。
结果验证（DONE）仍是独立步骤——代理不会假设模型的声明正确，而需检查页面确认。
性能数据基于单个 Chrome 配置文件的几次运行；不能保证跨站点或浏览器的可靠性。

接下来查看

agent.py – 完整决策循环及向文本助手的移交。
snapshot.js – 原子 DOM 提取逻辑。
browser.py – 低级 Chrome DevTools Protocol 包装器。
model.py – 操作/目标头的构建及对文本模型的调用。
performance.md – 详细时间分解和可复现性说明。

TL;DR

Jev Ultrafast 是一个紧凑的开源系统，让小型 LLM 通过重复（1）将页面读取为编号 UI 元素列表，（2）让模型选择 一项操作 和 一个目标，（3）执行该操作，来控制真实浏览器。该设计使提示极小、网络流量低，整个循环快到能在 8 秒内完成现实的航班搜索任务，同时保持完全可检查和安全。