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 次瀏覽器協定呼叫（而 naïve 實作需 >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 秒內完成現實的航班搜尋任務，同時保持完全可檢查和安全。