进阶手册：Jev Ultrafast 浏览器 Agent 与避坑指南
💡 目标：约 92 分钟做完两件事——把 Jev Ultrafast 浏览器 Agent 在自己电脑上跑起来（官方实录：Google Flights 一次真实搜索 7.073 秒），再带走官方踩坑文档里 Jev 1.13 的 9 种失败模式与替代做法。
🎯 阶段目标
- 说出 Jev Ultrafast 怎么工作：动态索引动作空间、一次往返同时定操作和目标、默认循环不截图
- 从零跑通一遍：
uv sync+ 两个 API Key，在127.0.0.1:8766的 inspector 里看编号元素和概率，再用 Agent 库写自己的浏览器任务 - 会读官方性能数据也知道边界：7.073 秒怎么测、协议调用 1,092→101 意味着什么、哪些控件不支持、DONE 为什么要独立验证
- 认得 Jev 1.13 的 9 种失败模式，每种都说得出官方替代做法——算术放代码、日期提部件、大 state 先过滤
⏳ 预计耗时
- 7 课合计约 92 分钟，预留浮动后约 64–120 分钟
- 5.1–5.4 是一条主线（原理 → 安装 → 实跑 → 读数据），建议按顺序走；5.5 / 5.6 只依赖第 2 课的环境，可按需单读
- 5.7 踩坑手册完全独立，不碰浏览器也能读——纯 API 用户直接跳它也不亏
🚀 开始之前
- 完成了 日常使用：掌握 Jev 的五种提问方式：Ultrafast 每一步决策就是一次 TypeSafe 请求，state、类型化问题和概率分布得先弄明白
- 手里有 TypeSafe API Key（注册与 API Key）；Ultrafast 还要再配一个文本模型的
TEXT_MODEL_API_KEY（第 2 课教你配） - 电脑上有 Chrome 和 uv——Ultrafast 用
uv sync安装，Chrome 通过 Browser Harness 连接 - 一杯水 ☕——这一阶段终于要让 Jev 替你动手点浏览器了
📚 本阶段课程
前 6 课的主角是 Jev Ultrafast——Browser Use × TypeSafe 的浏览器 Agent，官方一句话定位：「一个动态、带索引动作空间的浏览器 agent」。用法还是你熟悉的 Jev 式判断：给它一个目标，Jev 选操作和元素，小 LLM 只在需要打字（TYPE_TEXT）时写字符串。
云端另有官方托管的 BU Ultrafast（Browser Use Cloud，所有计划可用，model: "bu-ultrafast"，入口 cloud.browser-use.com）；本阶段带你跑的是 GitHub 上的开源版，所有操作都在你自己的电脑上完成。
先看它和你现在的做法差在哪：
| 你现在的做法 | Jev Ultrafast 的做法 |
|---|---|
| ❌ 自动化脚本把选择器写死，页面一改版就成批挂掉 | ✅ 每次观察动态生成编号元素表（[1] button Change ticket type · Round trip …），Jev 只从当前页面真实存在的东西里挑 |
| ❌ 视觉 agent 靠截图猜坐标，一步一截，又慢又贵 | ✅ 默认循环不截图：Jev 吃结构化 state，一次往返同时定操作和目标 |
| ❌ 让大 LLM 吐一段「操作计划」JSON，再祈祷能解析执行 | ✅ 操作和目标都是类型化答案；模型输出永远不变成 selector、坐标或可执行 JS |
操作一共 8 种：CLICK、TYPE_TEXT、SELECT、SCROLL_UP、SCROLL_DOWN、WAIT、DONE、BLOCKED——没有「任意执行脚本」这种危险动作。第 1 课会把这个动作空间拆开讲。
课程安排：
| 课程 | 内容 | 时长 |
|---|---|---|
| 5.1 Jev Ultrafast 原理 | 动态索引动作空间与 8 种操作；一次 TypeSafe 请求同时问操作和目标（两次决策、一次往返）；为什么默认循环不截图 | 12 分钟 |
| 5.2 Ultrafast 安装运行 | git clone + uv sync + 两个 API Key；打开 127.0.0.1:8766 的 inspector，看编号元素、操作概率、目标概率 | 15 分钟 |
| 5.3 跑通 Google Flights | Zürich → London 一次真实搜索，官方实录 7.073 秒；examples/flights.py 自带独立验证，只搜不订 | 15 分钟 |
| 5.4 性能解读 | 7.073 秒怎么测出来的：17 次 Jev 请求、中位延迟 178 ms；对比实测 9.450→7.092 s、协议调用 1,092→101——官方明说是小样本，不是通用基准 | 10 分钟 |
| 5.5 写自己的浏览器任务 | Agent 库实战：Agent(url, goals) + run() 逐步拿到 state；换一个 URL 和目标就是新任务 | 15 分钟 |
| 5.6 Ultrafast 排错 | 连不上 Chrome（browser-harness --doctor）、TEXT_MODEL 报错、点不动跑偏怎么办；不支持清单：shadow DOM、canvas、上传、弹出新 tab | 10 分钟 |
| 5.7 Jev 1.13 踩坑手册 | 官方 jaggedness 文档的 9 种失败模式与替代做法：字面理解、算术计数、日期比较、间接引用、大 state、对抗内容、矛盾指令、选项顺序、需要生成 | 15 分钟 |
💡 文本模型可以用国产的
Ultrafast 的文本 helper 走 OpenAI 兼容接口，官方 README 明说 Gemini、GLM、DeepSeek 都能配；代码里不设环境变量时的默认端点就是 DeepSeek（https://api.deepseek.com/v1 + deepseek-chat）。它只在 TYPE_TEXT 时出场——不配 TEXT_MODEL_API_KEY 会直接报错，官方原话：no text is hardcoded or guessed。
⚠️ DONE 不等于成功
官方在 Evidence and limits 里写得很直白：选了 DONE 仍然要独立验证结果（Flights 例子的 verify() 就是干这个的）；DOM reader 只认常见 HTML/ARIA 控件，shadow roots、frames、canvas、上传、弹出新 tab、嵌套滚动、任意键盘组件都不在这个 MVP 里。有效操作也可能是错的——第 4 课和第 6 课会反复强调这条。
最后一课相对独立：官方把 Jev 1.13 的已知问题整理成 jaggedness 文档——9 种失败模式，每种附替代做法。文档标注适用 jev-1.13（最后审阅 2026-10-02），官方也说其中很多会在后续版本修复；但「算术放代码、日期提部件、大 state 先过滤」这些提问习惯，无论用什么版本都值得养成。
🎒 你将收获
- 一套能跑的浏览器 Agent：从 clone 到 inspector 再到 Agent 库写自定义任务，全部在本机完成
- 读官方性能数据的正确姿势：7.073 秒的计时边界、小样本对比该怎么引用，不吹不黑
- 安全边界意识：模型输出永远不变成可执行代码、DONE 必须独立验证、不支持的控件清单心里有数
- 9 种失败模式的「症状 → 替代做法」清单，写问题时主动绕开 Jev 1.13 的坑
浏览器之外，想看 Jev 在纯 API 场景的 15 个完整案例（弹幕过滤、RAG 把关、级联提取），回看 场景实战：选择你的路线；要查请求格式和状态码，去 API 速查，模型版本与价格见 模型与价格。
准备好了吗？开始第一课：Jev Ultrafast 原理 →