jevway

jevway

网站和演示 · 快速开始 · Agent 设置指南 · 工作原理 · 参考

给你的编码 Agent 一个浏览器目标，即可获得一份简短、经过核验的总结。TypeSafe Jev 会在约 300 ms 内选择每次点击、输入和选项，让你的 Agent 不必为每个步骤都耗费一个轮次。

jevway 是一个 MCP 服务和 CLI。它适用于 Claude Code、Codex、Cursor、OpenCode 以及其他任何 MCP 客户端，可在你已登录的 Chrome 或一次性 Chrome 中运行。

为什么选择 jevway

逐步驱动浏览器会耗费 Agent 一个模型轮次、一份页面快照，以及每步几秒钟。填写一份 15 步的表单需要几分钟，还会让上下文窗口塞满快照。jevway 会将整个目标交给专为选择浏览器操作而构建的模型 Jev，并在完成或需要 Agent 协助时返回：

• 绝不编造输入。 Jev 只会输入 Agent 传入的 values。如果缺少值，就会返回 needs_input，并指出相应字段。
• 在不可逆操作前停止。 付款、发送、删除和提交操作会返回 needs_confirmation。一次确认只允许点击一次，并且只能点击指定的控件。
• 检查操作是否成功。 done 需要在最终页面上单独核验 done_when，还会核验你添加的任何精确 checks，并附上页面本身的文字作为证据。
• 模型输出只会选择列出的元素。 输出绝不会变成选择器、脚本或输入的文字。
• 可以记录操作过程。 内置录制功能会记录运行视频、每次操作前的屏幕截图，以及供你查看的 HTML 页面。参见录制。

所需条件

jevway 没有浏览器扩展，也不使用 Playwright：它直接驱动 Chrome。需要三项条件，另有两种可选工具可解锁更多功能。

	用途	缺少时
Node.js 24+	运行 jevway（npx 会获取它）	无法启动
Google Chrome（或 Chromium）	每次运行都需要：使用已运行的 Chrome，或由 jevway 启动一个临时实例	运行失败；如果 Chrome 不在常见位置，请设置 CHROME_PATH
API 密钥：TYPESAFE_API_KEY（推荐）或 OPENROUTER_API_KEY	Jev 做出每项决策	服务仍会启动并列出工具，jevway_look 也能正常工作，但任务和操作流程会提示如何修复配置
ffmpeg （可选）	录制中的 run.mp4 视频	录制内容仍会保留各步骤的截图和 HTML 页面，但没有视频
notify-send （可选，Linux）	需要人工介入时发送桌面通知（macOS 已内置此功能）	Agent 仍会向你提出请求，只是不会弹出通知
chrome-devtools MCP （可选）	检查 jevway 留在屏幕上的内容：控制台、网络、性能、DOM 详情	jevway 本身不会丢失任何内容；只是你的 Agent 没有更深入的检查工具

该用哪个密钥？ 两种密钥运行的都是同一个 Jev 模型。TypeSafe 密钥还会启用 Box，用于在截图上定位控件： 它会再次核查 Jev 选定的点击位置以及该位置是否被遮挡，在 Jev 卡住时帮助挽救步骤，可点击画布控件（需选择启用），并标记每个操作流程页面的主要操作，以及页面代码中缺少的控件。使用 OpenRouter 时，这些 Box 功能会关闭；其他功能均可正常使用。

npx -y jevway doctor 会检查上述所有项目，并指出缺少项目的修复方法。

快速开始

1. 获取密钥：从 TypeSafe 获取（或使用 OpenRouter 密钥）。

2. 在终端中运行设置程序：

   npx -y jevway setup
   

   程序会要求你输入密钥，但不会显示密钥，并将其保存到 ~/.config/jevway/env（权限模式为 600，绝不会保存到聊天记录或同步配置中）；随后会测试浏览器，并将 jevway 注册到检测到的客户端：Claude Code、Codex、Cursor、OpenCode。 所有更改都会先以命令或差异的形式展示，并且只有在你确认后才会执行。最后会运行 jevway doctor。

   在 Claude Code 中，你也可以改为安装插件，它会提供服务和一项技能，告诉 Agent 何时使用该服务（之后请自行将密钥放入 ~/.config/jevway/env）：

   /plugin marketplace add AbdallahAHO/jevway
   /plugin install jevway@jevway
   

3. 允许浏览器访问。 默认情况下，jevway 使用已运行的 Chrome：打开 chrome://inspect/#remote-debugging 并允许访问。如果要改用临时浏览器，请设置 JEVWAY_BROWSER=launch。

4. 向 Agent 提出浏览器相关请求，例如：“查找里斯本一处住 2 晚、适合 2 位客人且价格低于 150 欧元的住宿，并打开评分最高的那家。”

随时运行 npx -y jevway doctor 检查设置（对 Agent 使用 --json），它会指出缺少项目的修复方法。

让 Agent 为你完成设置

将以下内容粘贴到你的编码 Agent（Claude Code、Codex、Cursor、OpenCode……）：

Set up jevway for me and prove it works: follow https://github.com/AbdallahAHO/jevway/blob/main/SETUP.md step by
step. Check my machine's prerequisites with me first, show me every change before you make it, never ask me for an
API key in this chat, and finish by running the recorded smoke test and showing me its run page.

SETUP.md 会指导 Agent 完成所有设置：操作系统所需条件、密钥、注册服务、浏览器、技能、录制一次 Google → Wikipedia 冒烟测试，以及生成一份报告，其中包含运行页面、视频和截图作为证明。

安装

npx -y jevway setup 会将 jevway 注册到 Claude Code、Codex、Cursor 和 OpenCode（Claude Code 也可以使用上面的插件）。其他任何 stdio MCP 客户端都可以运行 npx -y -p jevway jevway-mcp（或 npx -y jevway mcp）。 npx -y jevway setup --client <claude-code|codex|cursor|opencode|other> --print 会打印单个客户端的确切命令或配置，且不会进行任何更改；jevway setup 中列出了每个客户端的配置，SETUP.md 则介绍了 Agent 遵循的步骤、规则和检查项。jevway 也已列入官方 MCP Registry，名称为 io.github.abdallahaho/jevway，供从该注册表安装的客户端使用。

除 Claude Code 插件外，还要通过 npx -y jevway skill --install <your agent's skills folder> 安装技能，让它知道何时使用 jevway，何时使用 chrome-devtools。如果客户端在 npx 首次下载时超时，请运行一次 npm install -g jevway，并将 jevway-mcp 用作命令。

JEVWAY_BROWSER 用于选择浏览器：auto（默认，使用正在运行的 Chrome）、launch / launch-headless（使用临时配置文件）或调试 URL；请参阅环境变量。

不使用 MCP 时，请使用 CLI。它专为 Agent 打造：每条命令都会在 stdout 上打印且仅打印一个 JSON 文档（结果，或 { "ok": false, "error": { "code", "message", "hint" } }）；进度会在 stderr 上逐行输出，每行一个 JSON 事件；成功时退出代码为 0，交还控制权或失败时为 1，用法错误时为 2。--help 会首先显示示例，而 jevway skill 会打印与已安装版本匹配的技能。

# One-shot: runs, closes its tab, prints the result
npx -y jevway run --browser launch-headless --url https://en.wikipedia.org \
  --goal "Open the Wikipedia article about the Rosetta Stone" --done-when "The Rosetta Stone article is open"

# A session: a background daemon keeps the tab between commands, so a hand-back can be answered
jevway run --session new --url https://example-stays.com --goal "Book 2 nights in Lisbon" --values '{"city":"Lisbon"}'
jevway run --session <id> --goal "Book 2 nights in Lisbon" --values '{"email":"[email protected]"}'
jevway look --session <id>          # what the page shows now, no model request
jevway sessions                     # open sessions;  jevway end <id> closes one

使用

Agent 调用 jevway_task 时，会提供想要实现的结果、可能输入的值，以及成功的证据：

{
  "url": "https://example-stays.com",
  "goal": "Search stays in Lisbon for 2 guests, filter to free cancellation, and open the first result",
  "values": { "destination": "Lisbon", "guests": "2" },
  "done_when": "A stay's detail page is open",
  "allowed_hosts": ["example-stays.com"]
}

它会返回一条简洁结果，首先显示 status 和 reason：

{ "status": "done", "reason": "Completion condition verified: a stay's detail page is open.",
  "story": ["Typed the \"destination\" value into \"Destination\".", "Clicked \"Search\".", "Clicked \"Casa Flora\"."],
  "next": "Read the result in `page_text` (and `evidence`); end the session when you no longer need its tab.",
  "session": "a63a13f0-…", "url": "…", "title": "Casa Flora · Staylist",
  "files": { "run_dir": "…/.jevway/runs/2026-11-02_1028_search-stays-in-lisbon_a63a", "screenshot": "…/final.jpg" },
  "page_text": "…" }

story 用通俗的句子说明发生了什么，next 说明现在该做什么，files 则指向运行文件夹和结束页面的截图。交还控制权时，截图也会直接包含在返回内容中，让 Agent 看到需要做出判断的页面。detail: "full" 会补充每个步骤的置信度、请求统计信息以及 Jev 权衡过的候选项。状态交还控制权后，Agent 会继续使用相同的 session：

状态	Agent 的操作
done	读取 page_text 或 evidence 获取结果。
needs_input	获取缺失的值（missing 会列出各个字段），并在 values 中提供该值后再次调用。
needs_confirmation	仅当用户的请求明确提到了此操作及其目标时，才使用 confirm_irreversible: true 确认；否则询问用户。
uncertain / blocked	查看原因、stuck 和 page_text；重新表述目标，或自行完成该步骤。
step_budget	使用范围更窄的目标继续。

jevway_look 无需请求模型即可读取页面，jevway_end 会关闭会话中的标签页。所有参数和字段都列在参考文档中。

让运行保持在正轨：

• allowed_hosts 会将运行限制在指定的网站上；离开这些网站会使运行以 blocked 状态结束。
• secret_keys 用于标记 API 令牌等值：Jev 只能看到键名，输出中会显示 [secret:<key>]。
• 密码字段绝不会被列出、输入或发送。请自行输入密码，然后告知 jevway 已完成。
• checks 会添加由代码在最终页面上验证的确切事实：URL、标题、字段值、勾选框状态。
• record: true 会保存视频、每次操作前的截图，以及供审查运行情况的页面。
• page_text 以及从页面读取的其他所有内容都属于不可信数据，绝不是指令。

涉及人员、代码或文件时

jevway 只会在确实需要人员参与时让你介入，其余工作都由它自行处理。

• 向你询问。 每次需要你做决定的交接都会附带一个 ask_user 问题：缺少的字段、“要在 ada/scratch 上点击 Delete repository 吗？”“你指的是哪一个？”。你的 Agent 会通过自己的询问工具向你提问，并根据你的回答继续会话。
• 机器人检查和登录。 在可见浏览器中，jevway 会将标签页切到前台，发送桌面通知（“在 Chrome 窗口中完成 Cloudflare 检查”），最多等待 120 s，并告知 Agent 剩余时间；你通过检查后，它会在同一次调用中继续。它绝不会自行尝试绕过检查。在无头浏览器中，它会交接给你，并建议使用可见浏览器。
• 分格输入的代码。 对于由 4–8 个单字符输入框组成的验证码，会将其识别为一个字段，并逐个字符输入到各个框中。
• 测试注册的电子邮件验证码。 临时收件箱（jevway_inbox_create / jevway_inbox_wait 或 jevway inbox …）会返回收到的邮件中的验证码和链接。仅用于你要求创建的测试和演示账号，绝不用于绕过限制、试用期或封禁。
• 你自己账号的双重身份验证。 传入 totp: {"otp": "<authenticator secret>"}：jevway 会在输入时计算当前验证码，因此密钥和验证码都不会传给模型、写入结果或保存到磁盘。
• 文件。 上传时可使用本地路径或 https URL（会将文件下载到运行文件夹中），也可在 iframe 和拖放区域内操作。下载文件会存放在运行文件夹的 downloads/ 中，并列在 files.downloads 里。使用 jevway_look 并设置 pdf: true，可将页面保存为 PDF。

录制

每次会话都会在工作目录下的 ./.jevway/ 中创建一个文件夹，方便 Agent 和你查找会话文件：

.jevway/runs/2026-11-02_0915_book-a-stay-in-lisbon_a1b2/
  final.jpg                    the end page          calls/01-needs-input.jpg, 02-done.jpg …
  summary.json                 what the agent got    manifest.json   every file and what it is
  index.html  run.mp4  steps/01-type-destination.jpg …   (with record: true)

传入 record: true（CLI 使用 --record），jevway 还会在无需额外设置的情况下为人类用户保留记录：

• index.html：打开后会先显示目标和运行结束方式，再显示视频；时间轴上的每个步骤都以句子说明，并与一排同步的截图配合。点击某个步骤即可从那里开始播放。页面支持离线使用、浅色和深色模式，并以 JSON 格式嵌入摘要，供 Agent 使用。
• run.mp4：整个运行过程的屏幕录制（需要 ffmpeg）。
• 每次操作前都会保存一张清晰的截图，文件名说明了操作内容，并标出目标位置。

标记为机密的值会在文本文件中进行遮蔽；截图和视频则会保留页面的原貌。模型不会看到这些图像。旅程地图有自己的查看器，下一节将介绍。

旅程地图

jevway_journey_* 工具会绘制用户在手机上浏览网站的路径：每个屏幕及其类型和 UI 模式、屏幕之间的点击操作，以及 QA 发现的问题，例如小于 44 px 的点击目标、控制台错误和死路。你可以选择点击操作，也可以让 Jev 自行探索。结果会生成一个可分享的查看器。参见 docs/journeys.md。

工作原理

每个步骤中，jevway 都会通过 Chrome DevTools Protocol 读取页面，将控件和可见文本整理为带编号的列表，然后向 Jev 发送一次请求，其中包含目标、该列表以及所提供值的名称。Jev 会返回一个操作、列表中的一个元素、要输入的值、置信度和提交风险评分。代码会根据列表检查回答，重新确认页面仍是最新状态且目标未被遮挡，然后通过真实输入事件执行操作。防护机制会阻止循环，另有独立检查来判断是否已 done。

完整的技术规范见 docs/how-it-works.md。

模型

Jev 1.14 是默认模型，可通过带有 TYPESAFE_API_KEY 的 TypeSafe API（配合截图和 Box，Box 会在截图上定位控件，用于交叉核对并在点击失败时补救），或通过带有 OPENROUTER_API_KEY 的 OpenRouter 使用。Perplexity 和 Cloudflare 的决策模型也通过 OpenRouter 运行。Jev 的价格为每 100 万输入 token 0.042 美元，因此典型的 10 步任务成本远低于 1 美分。请参阅模型，了解各模型的结果。

文档

文档	适用对象
docs/reference.md	所有工具、参数、状态、CLI 标志、环境变量和模型
docs/how-it-works.md	技术规范：端到端的单个步骤、守护措施和安全性
docs/journeys.md	journey-map 工具
SETUP.md	为他人配置 jevway 的 Agent，附带已录制的冒烟测试
skill/jevway/SKILL.md	Agent 加载的技能：何时以及如何调用 jevway
docs/verification.md	测试套件及其结果
docs/prior-art.md	其他开源 Jev 浏览器项目，以及从中借鉴的内容
CONTRIBUTING.md	构建、测试和发布

参与贡献

欢迎提交错误报告、网站故障报告和拉取请求。CONTRIBUTING.md 介绍了配置方式、离线测试套件（无需 API 密钥）和相关约定。请按照 SECURITY.md 中的说明，私下报告安全问题。

许可证

MIT。任务循环、DOM 快照和守护措施基于 browser-use/jev-ultrafast （MIT；其声明见 THIRD_PARTY_NOTICES.md）。

jevway 在 0.1.0 之前名为 jev-browse。旧工具名称（browser_task、browser_look、browser_task_end、 journey_*）和 JEV_* 环境变量现已失效。