W
AI-Wiki
← 开源项目

Ying-Kai-Liao/jev-browser

已整理
https://github.com/ying-kai-liao/jev-browser

jev-browser 用来把“想在网页上完成什么”的指令转成实际浏览器操作,并在不确定、受阻或涉及重要后果时把控制权交还给用户或上层模型。它适合需要用 Claude/MCP、命令行或代码自动操作网页,同时希望减少大模型直接读取大量页面内容的人使用。

项目简介

jev-browser 用来把“想在网页上完成什么”的指令转成实际浏览器操作,并在不确定、受阻或涉及重要后果时把控制权交还给用户或上层模型。它适合需要用 Claude/MCP、命令行或代码自动操作网页,同时希望减少大模型直接读取大量页面内容的人使用。

官方仓库资料

主要语言
JavaScript
许可证
MIT
默认分支
main
Stars
76
Forks
12
Open Issues
4
仓库状态
正常运行
派生仓库
非 Fork
数据采样
2026/9/23 19:04:51
资料抓取
2026/9/23 19:04:51
首次收录
2026/9/23 19:04:11

Topics:browser-automation · llm-agents · mcp · mcp-server · playwright

AI 整理 · 基于已抓取的官方资料

核心功能

  • 通过 MCP 工具进行浏览器自动化,包括打开页面、执行目标、检查页面、选择选项、获取快照、直接操作元素、截图和关闭会话
  • 支持作为 JavaScript 库使用,也支持 CLI 运行单步任务或 JSON 流程
  • 每轮会等待页面稳定、描述页面、调用 Jev 决策并执行浏览器动作
  • Jev 仅返回概率分布,不生成自由文本;需要输入的文本由调用方通过 values 提供
  • 在疑似订单、付款、发送、删除等不可逆操作前暂停,并返回 needs_confirmation
  • 支持 headed 模式观察浏览器操作过程
  • 支持持久化浏览器 profile,以便登录状态在重启后保留
  • 支持对页面进行 yes/no 检查、在选项中选择、获取紧凑元素列表和 PNG 截图
  • README 声称可处理表单、下拉框、复选框、单选框、动态加载、弹窗、JS 对话框、悬停、右键、拖放、按键、文件上传、iframe、Shadow DOM、新标签页、大量元素页面和非英文界面

适用场景

  • 让 MCP 客户端按步骤完成网页操作,例如登录、打开指定标签页或填写表单
  • 在网页自动化流程中执行一个可观察结果明确的目标
  • 对页面状态进行 yes/no 检查,例如确认购物车数量是否正确
  • 在多个给定选项中根据页面内容进行选择
  • 在自动化流程卡住、目标不明确或置信度低时获取页面快照并由调用方接管
  • 运行 JSON 定义的自动化流程
  • 对网页任务进行基准测试和上下文成本估算

使用方式

quick_start_mcp_from_npm: - npx playwright install chromium

  • claude mcp add jev-browser -e TYPESAFE_API_KEY=your-key -- npx -y -p jev-browser jev-browser-mcp mcp_client_command: npx mcp_client_args: - -y
  • -p
  • jev-browser
  • jev-browser-mcp required_env: - TYPESAFE_API_KEY optional_env: - JEV_BROWSER_HEADED=1:显示浏览器窗口
  • JEV_BROWSER_PROFILE=/dir:使用持久化 profile,保留登录状态
  • JEV_BROWSER_LOG=1:向 stderr 输出每轮决策日志 setup_from_source: - git clone https://github.com/Ying-Kai-Liao/jev-browser && cd jev-browser
  • npm install
  • npm run setup
  • cp .env.example .env
  • npm test
  • npm run test:e2e claude_code_from_source: claude mcp add jev-browser -- node /absolute/path/to/jev-browser/bin/jev-browser-mcp.mjs library_example: import { JevBrowser } from "jev-browser";

const b = await JevBrowser.launch({ headed: true }); await b.open("https://www.saucedemo.com/"); await b.do("Log in", { values: { username: "standard_user", password: "secret_sauce" } }); await b.do("Add the Sauce Labs Backpack to the cart"); const p = await b.check("Does the cart badge show 1 item?"); await b.close(); cli_examples: - node bin/jev-browser.mjs do https://the-internet.herokuapp.com/login "Log in" username=tomsmith 'password=SuperSecretPassword!'

  • node bin/jev-browser.mjs run examples/flows/todomvc.json --headed mcp_tools: - name: browser_open(url) purpose: 导航并等待页面稳定
  • name: browser_do(goal, values?, max_actions?, allow_irreversible?, explain?) purpose: 朝一个目标执行操作并返回状态
  • name: browser_check(question) purpose: 针对页面提出 yes/no 问题并返回 p_yes
  • name: browser_choose(question, options) purpose: 在给定选项中选择并返回分布
  • name: browser_snapshot() purpose: 返回紧凑的编号元素列表,便于调用方接管
  • name: browser_act(action, element, value?, key?, destination?, accept_dialog?) purpose: 不调用模型,直接对元素执行动作;确认框或提示框默认会被关闭,除非设置 accept_dialog
  • name: browser_screenshot(full_page?) purpose: 返回 PNG 图片
  • name: browser_close() purpose: 结束会话

技术特点

  • 项目语言为 JavaScript。
  • 项目调用 TypeSafe System One API,需要用户提供自己的 TYPESAFE_API_KEY。
  • 每轮 browser_do 过程包括 settle、describe、Jev 决策和 Playwright 执行动作。
  • README 中描述 Jev 调用约约 300 ms,多数步骤需要 2–4 次调用。
  • README 中的测试结果为:42 个实时网站任务中最新运行 40/42 正确,0 次错误声明 done。
  • README 中称在约 200 轮操作中,仅 saucedemo 的 Finish 按钮被标记为不可逆操作。
  • README 中估算,相比 Playwright-MCP 风格循环,在相同任务中向 LLM 暴露的页面内容更少;小页面上没有节省。
  • browser_do 可能返回 done、likely_done、needs_login、needs_confirmation、error、stuck、max_actions、ambiguous、blocked 等状态。
  • README 建议每个步骤只包含一个可观察结果,所有字符串通过 values 传入,并对 likely_done、needs_confirmation、ambiguous、stuck 等状态进行检查、快照或询问用户。

限制与边界

  • README 明确建议不要把有顺序的多个子目标放在一个步骤中,例如“添加两个待办事项、完成一个、清除已完成”;应拆成每步一个目标。
  • 开放式目标不适合直接交给单步执行,例如“滚动加载更多”;应改成可衡量目标或由调用方自行检查。
  • 需要比较大量值的判断,例如表格是否已排序、是否恰好只有一个东西发生变化,建议使用 browser_check 或 browser_snapshot 验证。
  • 当返回 likely_done 时,页面看起来可能已完成但 Jev 不确定,调用方应先验证再继续。
  • 当返回 needs_confirmation 时,下一步动作或已触发的确认对话框可能涉及不可逆操作,只有在用户确认后才应使用 allow_irreversible: true 重新调用。
  • 当返回 ambiguous 时,目标置信度较低,调用方应从 candidates 中选择并用 browser_act 操作。
  • 部分网站可能向 headless Chromium 返回空白页面,README 举例提到 x.com;这种情况需要使用 headed 模式。
  • 该项目是非官方项目,不隶属于 TypeSafe。

README

README 介绍了 jev-browser 的目标、工作流程、测试结果、适用场景、已知限制和使用方式。项目通过 MCP、库和 CLI 提供浏览器自动化能力,让上层大语言模型提出单步目标和输入值,由 Jev 根据页面描述做概率式决策并由 Playwright 执行;文档还列出了安装命令、MCP 工具、状态含义、环境变量、示例代码、CLI 示例、编写步骤建议、基准测试命令和发布说明。

关联 Wiki 词条

暂无已建立的词条关联。