leapfrog

Leapfrog

面向 AI Agent 的多会话浏览器 MCP。
36 个工具。15 个并行会话。隐身。HUD。自我改进。最多减少 10 倍 Token 消耗。

npm i leapfrog-mcp  |  兼容 Claude Code、Cursor、Windsurf

---

问题

对于 Hacker News 这样内容密集的页面，Playwright MCP 会发送 约 14,000 个 Token。其中大部分都是噪声。你的上下文窗口很快就会被填满。你的 Agent 会变得困惑。这些都会让你付出代价。

Leapfrog 只发送 约 1,400 个 Token。同一个页面。同样的信息。噪声最多减少 10 倍。

┌─────────────────────────────────────────────────────┐
│  Playwright MCP                                     │
│  ████████████████████████████████████████  ~14,000   │
│                                                     │
│  Leapfrog                                           │
│  █████                                    ~1,400    │
└─────────────────────────────────────────────────────┘
          tokens per page (Hacker News, real test)

根据页面复杂度，节省幅度为 2 到 10 倍。内容密集的页面收益最大，密集表单的收益最小。实际网站的中位数为 约 4-5 倍。

快速开始

npx leapfrog-mcp --doctor          # verify everything works
npx leapfrog-mcp --stealth-audit   # test all 19 stealth patches
npx leapfrog-mcp --config          # print MCP config to paste

将其添加到 ~/.mcp.json（Claude Code）或编辑器的 MCP 配置中：

{
  "leapfrog": {
    "command": "npx",
    "args": ["-y", "leapfrog-mcp"],
    "env": {
      "LEAP_MAX_SESSIONS": "15",
      "LEAP_TILE": "true",
      "LEAP_HUD": "true",
      "LEAP_AUTO_CONSENT": "true"
    }
  }
}

Leapfrog 使用 playwright-core（15MB），而不是 playwright（1.6GB），并且不会捆绑浏览器。你可以：

• 设置 LEAP_CHANNEL=chrome，使用已安装的 Chrome/Chromium（推荐）
• 或运行 npx playwright-core install chromium，安装捆绑的 Chromium 二进制文件
• 或设置 LEAP_CDP_ENDPOINT，连接到已运行的 Chrome 实例

功能对比表

	Leapfrog	Playwright MCP	agent-browser
每页 Token 数	约 1,200-2,500	约 3,800-15,000	约 300
并行会话	15	1	1
会话隔离	是	否	否
多标签页 / 弹出窗口	是	否	否
网络拦截	是	否	否
控制台捕获	是	是	否
隐身 / 反机器人	是	否	否
智能等待（5 种类型）	是	基础	否
崩溃恢复	是	否	否
批量操作（每次调用 100 项）	是	否	否
初始化脚本注入	是	是	否
拖动 / 上传 / 调整大小	是	是	否
每个会话单独配置代理	是	否	否
人性化操作（可选）	是	否	否
复用身份验证配置文件	是	否	否
Cookie 持久化	是	否	否
页面分类（18 种）	是	否	否
会话记忆	是	否	否
API 智能分析	是	否	否
自适应等待 + 自动重试	是	否	否
自动解决 CAPTCHA	是	否	否
自我改进（9 个维度）	是	否	否
录制 / 回放	是	否	否
分页提取	是	否	否
增量快照（差异）	是	否	否
隐身自测 CLI	是	否	否
SSRF 防护	是	否	否

隐身

Leapfrog 默认启用 19 项反检测补丁（LEAP_STEALTH=true）。提供四种模式：

• true（默认）— 启用全部 19 项补丁
• passive — 仅移除自动化信号（webdriver、HeadlessChrome）。不会伪造身份（WebGL、字体、音频）。适用于信任比规避检测更重要的网站。
• auto — 按域名使用 EXP3 多臂老虎机，根据以往效果选择最佳隐身配置
• false — 不启用任何隐身补丁

这些补丁覆盖了 CreepJS 和 fingerprint-pro 等指纹识别服务会检查的项目：

• Client Hints 品牌（移除 HeadlessChrome）
• 将 navigator.webdriver 强制设为 undefined
• WebGL 厂商/渲染器（用真实 GPU 字符串替换 SwiftShader）
• 连接 RTT（设为非零值）
• 警告框关闭时序（延迟模拟人工操作速度）
• 窗口外部/内部高度偏移
• MIME 类型数组填充
• 根据用户代理推断平台
• 模拟 chrome.app
• 保护 iframe 的 contentWindow
• 媒体编解码器伪装（canPlayType）
• 覆盖 document.hasFocus()
• 移除源 URL 注释
• 自定义 UA 与隐身功能兼容（自定义用户代理不再禁用隐身上下文）
• CDP Runtime.enable 检测（Error.prepareStackTrace 过滤器）
• Permissions API 伪装（20 多种权限类型）
• AudioContext 指纹噪声（getChannelData/getFloatFrequencyData）
• 防止 WebRTC IP 泄漏（过滤 ICE 候选项）
• 字体枚举指纹伪装

按会话控制隐身：在 session_create 中传入 stealth: false，即可为特定会话禁用隐身。

拟人化（实验性）

设置 LEAP_HUMANIZE=true，即可启用模拟真人的浏览器交互。此功能需主动启用，会增加延迟，以换取更逼真的行为。包含六个模块：

• 鼠标 — 使用贝塞尔曲线路径，结合菲茨定律计时和微震颤抖动
• 打字 — 按对数正态分布设置按键间延迟（中位数为 200ms），并模拟按键停留时间、根据字母组合调整速度以及滚动式打字
• 滚动 — 通过加速和动量衰减进行惯性模拟（触控板/鼠标滚轮物理效果）
• 暂停 — 操作间加入“思考”延迟，模拟操作之间的认知间隔
• 指纹 — 生成一致的浏览器指纹（平台、设备内存、GPU、时区）
• 工具函数 — 共享数学原语（Box-Muller 高斯分布、概率分布）

页面分类

每次 navigate 和 snapshot 调用都会使用加权信号评分自动对页面类型进行分类（无需 LLM）。共 18 种类型：

login · search-results · product · product-list · checkout · article · dashboard · form · error · challenge · landing · documentation · profile · media · feed · qa · ecommerce · unknown

分类结果可用于更智能地提取快照内容 — 登录页会显示表单字段，文章页会显示内容，仪表盘会显示交互元素。

自动化框架智能功能

自动化框架会跟踪会话中的每项操作并对结果进行分类：

• 操作结果分类 — SUCCESS、SILENT_CLICK、NAVIGATION、WRONG_ELEMENT、BLOCKED、ERROR、PENDING
• 机器人重定向检测 — 检测网站是否在操作后重定向到验证页或拦截页
• 循环检测 — 当 Agent 陷入重复点击同一元素、在 URL 之间来回跳转或重复执行操作时发出警告
• 会话记忆 — session_memory 工具可在上下文窗口压缩后回忆操作

Cookie 持久化

现在，持久化浏览器配置文件使用 context.cookies() + addCookies()，而不再使用在持久化上下文中会返回空结果的 storageState()。身份验证状态可在不同会话之间保留。

自适应等待与隐身升级

当页面加载失败时，Navigate 会使用备用策略自动重试：

1. 尝试 load（最快）——如果内容为空，则使用 networkidle 重试（上限 10s）
2. 如果 networkidle 超时（如 Amazon、广告密集型网站），则回退到 domcontentloaded
3. 如果遇到拦截或验证，则升级隐身策略：随机延迟 → 等待 JS 验证 → 使用新的指纹轮换会话
4. 已登录的会话不会被销毁——最高限制为 Level 2

在 navigate 中设置 autoRetry: false 可关闭自动重试。使用 maxRetryLevel（0-5，默认 3）控制最高升级级别。

记录 / 回放

将会话的操作历史导出为可回放的录制文件，然后在新会话中回放：

• session_export — 根据会话历史创建参数化 JSON 或 Playwright 脚本。@eN 引用会解析为稳定的 CSS 选择器。自动将电子邮件、密码和 URL 识别为 {{placeholders}}。
• session_replay — 使用参数覆盖值回放录制文件。支持 onError: 'stop' 或 'skip'。

将一次性的 Agent 工作流转变为可复用的自动化流程。

分页提取

通过一次工具调用提取多个页面的数据：

• 点击下一页 — 自动检测“下一页”按钮、分页链接、“加载更多”按钮
• 无限滚动 — 滚动页面，并通过比较 DOM 哈希值等待新内容
• URL 模式 — 递增 ?page={page} 或使用自定义模式

每页可减少 3-4 次工具调用。上限：50 页，总计 100K 个字符。遇到以下情况时停止：没有下一页按钮、页面为空、内容重复或检测到机器人。

增量快照

diff 工具仅返回自上次快照以来的变化——新增、删除和更改。这能大幅节省监控和轮询工作流的令牌用量。

HUD 叠加层（LEAP_HUD=true）

在有头模式下运行时，Leapfrog 会在每个会话中叠加视觉反馈：

• 点击涟漪 — 在点击坐标处显示扩散的绿色圆圈（仅限 Agent 操作）
• 缩放至目标 — 浏览器会短暂放大至 1.15x，聚焦被点击的元素，让 Agent（和人类）在平铺窗口中直观地跟踪操作
• 滚动至目标 — 点击前调用 scrollIntoView，让你看到 Agent 即将点击的内容

设计简洁。没有边框、状态栏或光标叠加层——只显示重要反馈。

多终端平铺（LEAP_TILE=true）

多个 Leapfrog 实例通过基于文件的协调机制共享屏幕。每个实例跟踪自己的窗口，TilesCoordinator 则分配全局网格位置——不会重叠，无需手动排列。设置 LEAP_TILE=true（主实例可设置为 LEAP_TILE=master）。平铺窗口间距可通过 LEAP_TILE_PADDING 配置（默认 8px）。

人工介入

Leapfrog 会自动检测需要人工处理的情况——CAPTCHA、登录表单、OAuth 重定向、Cloudflare 验证——并在暂停前尝试自行解决。

• **优先自动解决：**点击 reCAPTCHA 复选框、Cloudflare 验证按钮、通用验证/继续按钮，然后进行第二轮重试——完成这些步骤后才会请求帮助
• **外部求解服务：**设置 LEAP_CAPTCHA_PROVIDER + LEAP_CAPTCHA_API_KEY，以集成 CapSolver、2Captcha 或 NopeCHA
• **记住有效方法：**记住每个域名上成功的解决方法，再次访问时优先尝试已知有效的方法
• 检测 reCAPTCHA、hCaptcha、Turnstile、登录表单、OAuth 重定向、Cloudflare 验证
• 需要介入时，标签页标题会变为“NEEDS HUMAN”
• wait_for_human 工具 — Agent 遇到阻塞时调用；该工具会一直等待，直到你解决问题或跳转离开

自动关闭 Cookie 同意提示（LEAP_AUTO_CONSENT=true）

自动关闭 10 种框架（OneTrust、CookieBot、TrustArc、Quantcast、Didomi、Cookielaw、Osano、Usercentrics 和通用框架）的 Cookie 同意横幅，并提供文本匹配回退方案。按域名缓存选择器，以便再次访问时即时重放。

跟踪（LEAP_TRACE=true）

按会话进行 Playwright 跟踪，包含截图和 DOM 快照。使用 session_export_trace 工具导出 ZIP 文件，并在 trace.playwright.dev 查看。会话销毁时自动保存。

自我改进

Leapfrog 会从每次访问中学习。每个域名的知识会保存在 ~/.leapfrog/domains/{domain}.json 中，涵盖 9 个维度，全部自动完成：

#	维度	功能
1	等待策略	学习每个域名的最佳等待方法（networkidle、domcontentloaded 或 load）及运行平均耗时
2	隐身等级	检测到拦截时自动从 0 提升至 3（1 小时内拦截 2 次或以上）。再次访问时从已学习的等级开始
3	同意选择器	记住用于关闭 Cookie 横幅的选择器，再次访问时自动点击
4	挑战解决	记录有效的 CAPTCHA 处理方法（reCAPTCHA 复选框、Cloudflare 验证等），优先尝试已验证有效的方法
5	稳定元素抑制	识别访问 3 次或以上出现的导航栏、页脚和侧边栏元素，并从快照中抑制它们（成熟域名可节省 30-40% 的令牌）
6	选择器修复	记住元素指纹与选择器的对应关系，跨访问修复失效的引用
7	API 端点缓存	在不同会话间保留已发现的 API 端点
8	交互热力图	跟踪 Agent 实际使用的元素，并抑制未触及的元素（即将推出）
9	策略选择	使用对抗性赌博机（EXP3）优化隐身配置。使用 LEAP_STEALTH=auto 启用。

采用 LRU 策略，最多缓存 500 个域名。使用 domain_knowledge 工具查看。

SSRF 加固

URL 验证会拦截十六进制编码的 IP（0x7f000001）、八进制表示法（0177.0.0.1）、CGNAT 网段（100.64.0.0/10），以及解析到内部地址的重定向链。默认情况下，允许 localhost 和 127.0.0.0/8，以支持本地开发工作流；设置 LEAP_BLOCK_LOCALHOST=true 可将其拦截。

生态系统

Leapfrog 使用池塘主题的比喻，让概念更容易记忆。你的 Agent 就是青蛙。

概念	Leapfrog 术语	含义
会话	池塘	相互隔离的浏览器上下文，包括 Cookie、存储和状态
标签页	睡莲叶	青蛙在池塘中落脚的地方
导航	跳跃	跳转到 URL，并获取紧凑的快照
快照	水面	水面上可见的内容，包括交互式 @eN 引用
网络流量	涟漪	水面下流动的 HTTP 请求
控制台错误	呱叫	浏览器中出现问题
隐身模式	伪装	反机器人规避补丁

全部 36 个工具

池塘管理（11 个）

工具	功能
session_create	开启新池塘，使用独立的 Cookie、状态、视口、区域设置、时区、隐身设置和代理
session_destroy	清空池塘并释放名额
session_list	查看所有活跃池塘及其 URL 和空闲时长
session_save_profile	将身份验证状态保存到磁盘，供未来的池塘使用
session_list_profiles	列出已保存的身份验证配置
pool_status	池塘统计信息、内存和运行时间
session_health	池塘运行是否正常？浏览器是否已连接，页面是否有响应？
profile_list	列出已保存的持久化浏览器配置
profile_delete	删除已保存的持久化浏览器配置及其数据
profile_import_from_chrome	从已安装的 Chrome 配置导入 Cookie 和状态
profile_warm	加载关键 URL，为配置预热并建立 Cookie 和状态

导航与快照（12）

工具	功能
navigate	跳转到 URL，返回精简的 @eN 快照。内置自适应等待和隐身升级机制。
snapshot	重新读取页面内容（使用 CSS 选择器限定范围）
diff	增量快照——仅返回自上次快照以来的变化
act	点击、填充、输入、勾选、选择、按键、滚动、悬停、移动鼠标、拖动、上传、调整大小、后退、前进
batch_actions	在一次 MCP 调用中按顺序执行最多 100 个操作，消除往返开销
paginate	在一次调用中提取多个页面的数据（点击下一页、滚动、URL 模式）
add_init_script	注入在每次页面加载前运行的 JS，并在导航过程中持续生效
wait_for	等待元素／文本／网络空闲／导航／JS 表达式
screenshot	截取 PNG（整页或元素）
extract	提取文本、HTML、标题、URL，或执行 JS
session_memory	回顾此会话中执行过的操作——在压缩后恢复上下文
session_export	将会话历史导出为可重放的 JSON 录制文件或 Playwright 脚本

标签页管理（3）

工具	功能
tabs_list	列出一个池中的所有标签页
tab_switch	切换到另一个标签页（-1 表示最近打开的弹出页）
tab_close	关闭一个标签页（无法关闭最后一个）

Agent 智能（3）

工具	功能
wait_for_human	暂停以等待人工干预——直到用户点击 @..@ 覆盖层上的 Done 按钮才会继续
domain_knowledge	检查 Leapfrog 已掌握的域名信息（等待策略、隐身级别、端点）
session_export_trace	导出 Playwright 跟踪 ZIP 文件——可在 trace.playwright.dev 上查看

网络与 API 智能（7）

工具	功能
network_log	查看 HTTP 流量——按 URL、方法、状态、内容类型筛选
console_log	读取浏览器控制台输出，并按级别筛选
network_intercept	按 URL 模式阻止、模拟或记录请求
api_discover	列出页面调用过的 JSON API，并按类别（数据、跟踪、身份验证、CDN、广告）分类
api_export	根据观察到的 API 流量生成 OpenAPI v3 规范
execute	在沙盒环境中运行 Playwright 脚本——替代 5-20 次连续的 MCP 往返调用
session_replay	在当前会话中重放录制内容，并覆盖参数

环境变量

变量	默认值	描述
LEAP_MAX_SESSIONS	15	最大并发会话数
LEAP_IDLE_TIMEOUT	1800000	会话空闲超时时间，单位为毫秒（30 分钟）。设为 0 可禁用。
LEAP_HEADLESS	true	设为 false 可查看浏览器
LEAP_HEADED	false	设为 true 可查看浏览器（LEAP_HEADLESS 的正向替代选项）
LEAP_CHANNEL	(bundled chromium)	设为 chrome 以使用已安装的 Chrome
LEAP_CDP_ENDPOINT	(none)	连接到正在运行的 Chrome 实例（例如 http://localhost:9222）
LEAP_EXTENSIONS	(none)	要加载的浏览器扩展路径，以逗号分隔
LEAP_ALLOW_JS	true	允许在 extract 和 wait_for 中执行 JS
LEAP_STEALTH	true	隐身模式：true | passive | auto | false。参见隐身部分。
LEAP_STEALTH_PROFILES	false	在配置文件（已认证）会话中启用隐身补丁
LEAP_CDP_STEALTH	true	规避 CDP 检测（过滤 Runtime.enable）
LEAP_HUMANIZE	false	实验性功能。模拟人类的鼠标移动、打字节奏和滚动行为。
LEAP_ALLOW_EXECUTE	true	允许使用 execute 工具（沙箱化的 Playwright 脚本）
LEAP_BLOCK_LOCALHOST	false	阻止 localhost/127.x.x.x（默认允许本地开发访问）
LEAP_PROFILES_DIR	~/.leapfrog/chrome-profiles	持久化浏览器配置文件目录
LEAP_TILE	false	将会话平铺为网格（true | master | false）
LEAP_TILE_PADDING	8	平铺窗口之间的间距（px）
LEAP_MULTI_TILE	false	在多个 Leapfrog 实例之间协调多终端平铺
LEAP_SCREEN_WIDTH	(auto)	用于平铺计算的显式屏幕宽度
LEAP_SCREEN_HEIGHT	(auto)	用于平铺计算的显式屏幕高度
LEAP_HUD	false	在 Agent 操作时显示点击涟漪、缩放至目标和滚动至目标效果
LEAP_AUTO_CONSENT	true	自动关闭 Cookie 同意横幅（支持 10 种框架及备用方案）
LEAP_TRACE	false	按会话进行 Playwright 跟踪（屏幕截图 + DOM 快照）
LEAP_RECORD	false	会话录制（导出操作历史记录）
LEAP_REBROWSER	false	启用 Rebrowser 集成
LEAP_AUTO_WARM	false	创建会话时加载关键 URL，自动预热配置文件
LEAP_CAPTCHA_PROVIDER	(none)	外部 CAPTCHA 求解服务：capsolver | 2captcha | nopecha
LEAP_CAPTCHA_API_KEY	(none)	已配置 CAPTCHA 求解服务的 API 密钥
LEAP_MAX_SESSIONS_PER_CLIENT	(none)	每个客户端的会话池上限
LEAP_LOG_LEVEL	info	debug / info / warn / error

测试

 769 passing across 31 suites

会话管理、快照引擎、快照差异比较器、网络智能、标签页管理、安全性、SSRF 防护、隐身补丁（19 项）、增强隐身、人性化操作（鼠标、打字、滚动）、页面分类、测试框架智能、API 智能、脚本执行器、扩展操作、HUD 覆盖层、人工干预、Cookie 同意、域名知识、选择器修复、稳定元素、平铺管理器、错误回归、集成冒烟测试、压力测试、基准测试。

npm test

要求

• Node.js >= 20
• Chromium — 使用系统 Chrome（LEAP_CHANNEL=chrome），或通过 npx playwright-core install chromium 安装

许可证

MIT