Eyebrowse

---

为什么选择 EyeBrowse？

• 🥷 默认隐蔽 — 引擎级指纹伪装（开箱即启用 geoip + humanize，每次启动都会生成新指纹）；隐藏 navigator.webdriver；视口会根据伪装后的屏幕自动调整。没有 puppeteer-extra 这种权宜补丁——反检测功能直接编译进浏览器。
• 🤖 专为大模型打造 — 页面以带有 [ref=…] 句柄的 ARIA 树形式读取；模型通过 ref 操作（click/type/hover），而非依赖脆弱的 CSS 或原始像素。跨域 iframe、shadow DOM、弹窗均可处理。
• ⚡ Chrome DevTools Protocol — 通过节点 ref 实现可信的无光标点击（Input.dispatchMouseEvent），直接访问原始 Network/Performance/Emulation，并支持 MHTML 快照、PDF 导出和原生视频——均可通过工具调用。
• 🧰 同一套代码兼具库和 MCP 服务 — 简洁的 Python API（EyeBrowse + Session），并由轻量 MCP 服务（85 个 browser_* 工具）一对一提供，适用于 Claude Code 和任何 MCP 客户端。
• 🪟 不受封装限制 — 精选的高级 API 不会隐藏 Playwright：需要未封装的功能时，可直接使用 session.page / .context / .browser。
• 🔋 开箱即用 — 多会话、代理与身份轮换、API 模式验证码求解器、原生视频、完整 HAR 捕获，以及清爽 Markdown 提取。

范围。 EyeBrowse 是一个底层浏览器引擎——不包含任何工作流逻辑。 使用者决定做什么；引擎提供能做什么。

目录

快速入门 · 安装 · 功能 · 对比 · 用作库 · 通过 MCP 使用 · 代理与身份 · 内容提取 · 录制 · 工作原理 · 注意事项 · 工具 · 许可证

快速入门

pip install eyebrowse
# The stealth-Chromium binary downloads automatically on first launch — nothing else to run.

import asyncio
from eyebrowse import EyeBrowse

async def main():
    eb = EyeBrowse()                          # stealth defaults: geoip · humanize
    async with eb.session() as s:
        await s.navigate("https://example.com")
        print(await s.snapshot())             # ARIA tree with [ref=...] handles
        await s.click("e6")                   # act on a ref from the snapshot
    await eb.aclose()

asyncio.run(main())

……或者将它接入 Claude Code（或任何 MCP 客户端）——请参阅通过 MCP 使用。

安装

从 PyPI 安装

pip install eyebrowse                 # or: uv pip install eyebrowse
# CloakBrowser fetches its Chromium binary lazily on first launch — nothing to run.
pip install "eyebrowse[extract]"     # optional: + Crawl4AI markdown extraction (heavier)

从源代码安装（开发）

git clone https://github.com/Evil-Bane/eyebrowse && cd eyebrowse
uv sync                              # core engine  (add --extra extract for Crawl4AI)
cp .env.example .env                 # only if you use a proxy / captcha keys

Python 3.12（固定为 <3.13）。引擎：cloakbrowser>=0.3（隐身 Chromium，Chrome/146），基于 playwright 1.60 和 mcp 1.27。

功能

🥷 隐身	CloakBrowser 的补丁版 Chromium 指纹伪装（每次启动都会生成新的 --fingerprint）；默认启用 geoip + humanize；隐藏 webdriver；视口与伪装后的屏幕匹配。
🤖 LLM 交互	aria_snapshot(mode="ai") → ARIA 树 + [ref] 句柄；点击 / 输入 / 悬停 / 选择 / 拖动 / 文件上传 / 对话框 / 键盘操作；也支持坐标鼠标操作。
⚡ CDP	按 ref 进行可信无光标点击，原始 CDP（Network / Performance / Emulation）、MHTML 捕获、PDF 导出。
🪟 框架与 DOM	按 ref 路由跨域 iframe，穿透 shadow DOM，切换弹出窗口 / 新标签页，在任意框架内执行 evaluate。
🗂 多会话	独立的隐身会话，每个会话都有自己的 context / 身份 / 代理。
🌐 网络	检查请求 / 响应（包括 XHR/fetch 请求体和 WebSocket 帧）、屏蔽 URL、模拟响应、离线，以及完整的 HAR 导出。
💾 状态	Cookie、localStorage 和 sessionStorage（CRUD），保存 / 重新加载 storage_state。
🪪 身份轮换	全新指纹 + 隔离配置文件 + 配对代理；可插拔的住宅代理 ProxyProvider。
🧩 验证码	可插拔的 API 模式 识别器（CapSolver / 2Captcha / CapMonster / NextCaptcha）+ TOTP，无需浏览器扩展。
📄 提取	Crawl4AI raw: feed → 整洁、节省 token 的 markdown（无需大模型或 API 密钥）。
🎥 捕获	截图、Playwright 跟踪，以及原生视频（.webm）。
✅ 验证与调试	断言、元素高亮、定位器生成、地理位置 / 标头模拟。

完整的工具参考文档：docs/TOOLS.md（18 个分组中的 85 个工具）。

EyeBrowse 对比

	EyeBrowse	Playwright MCP	browser-use	playwright-stealth
内置于浏览器的反检测功能	✅	❌	❌	⚠️ JS 补丁
面向大模型的原生 ARIA [ref] 交互模型	✅	✅	✅	❌
提供 MCP 服务	✅（85 个工具）	✅	⚠️ 部分支持	❌
单一代码库：Python 库和 MCP	✅	仅 MCP	仅库	仅库
完整 CDP（可信点击 · 网络 · MHTML · PDF · 视频）	✅	⚠️ 部分支持	❌	⚠️ 部分支持
验证码（API 模式）+ TOTP	✅	❌	❌	❌
内置代理 + 身份轮换	✅	❌	⚠️ 部分支持	❌
跨域 iframe · shadow DOM · 弹出窗口	✅	✅	⚠️ 部分支持	不适用

_{公平使用说明：每个项目针对的细分领域各不相同——此处仅从 EyeBrowse 着重优化的维度（隐身 + 可由大模型驱动 + 单一库 / MCP 代码库）进行比较，并非总体排名。}

作为库使用

import asyncio
from eyebrowse import EyeBrowse

async def main():
    eb = EyeBrowse()                           # stealth defaults
    try:
        async with eb.session() as s:          # a stealth session (auto-closed)
            await s.navigate("https://example.com")
            print(await s.snapshot())          # ARIA tree with [ref=...] handles
            await s.click("e6")                # act on a ref
            await s.type("e8", "hello", submit=True)
            png = await s.screenshot(full_page=True)
            title = await s.page.title()        # full Playwright power when you need it
    finally:
        await eb.aclose()

asyncio.run(main())

运行随附的示例：uv run python examples/direct_usage.py。

通过 MCP 使用

EyeBrowse 自带 MCP 服务（eyebrowse-mcp，通过 stdio 运行的 FastMCP）。将其添加到任意 MCP 客户端。

Claude Code（CLI）：

claude mcp add eyebrowse -- eyebrowse-mcp

任意 MCP 客户端（JSON 配置）：

{
  "mcpServers": {
    "eyebrowse": {
      "command": "eyebrowse-mcp"
    }
  }
}

然后按以下步骤操作：browser_navigate(url) → 读取快照 → 根据引用执行操作 （browser_click / browser_type / …）。系统会自动创建默认会话，因此大多数工具都能直接使用。完整列表请参阅：docs/TOOLS.md。

代理与身份（可选）

默认不使用代理（geoip 仍会根据你的真实 IP 调整区域设置和时区）。仅在需要时添加代理：

await eb.new_session(proxy="http://user:[email protected]:8080")
await eb.rotate_identity(proxy="socks5://host:1080")   # fresh fingerprint + paired IP
await eb.new_session(no_proxy=True)                     # force proxyless

通过 .env 中的 EYEBROWSE_PROXY_*、eb.set_static_proxy(...)，或用于轮换代理的自定义 ProxyProvider，设置一次默认代理。通过 MCP：browser_new_session(proxy_url=…) / browser_new_identity(proxy_url=…) / browser_set_proxy(…)。

reCAPTCHA v3 / 声誉门槛基于评分，并依据 IP + 会话声誉判定 —— 即使使用隐蔽性功能，干净的新浏览器在被标记的 IP 上仍会失败。请将 EyeBrowse 与干净的住宅代理配合使用。

提取

eb.extract()（或 browser_extract）会将渲染后的 HTML 交给 Crawl4AI 的 raw: feed，并返回经过清理和精简的Markdown —— 不会调用 LLM，也不会读取任何 LLM 密钥；结构化工作由使用它的 Agent 完成。

md  = await eb.extract()                            # markdown string
res = await eb.extract(output_path="data/page.md")  # → {"path": ..., "chars": ...}

录制

原生视频 —— Playwright 会录制整个会话并保存为 .webm，在会话关闭时写入。文件路径会预先确定；会话关闭后，文件才会完成写入：

s = await eb.new_session(record_video=True)
# ... drive the browser ...
print(await s.video_path())          # path is known up-front; file finalizes on close
await eb.close_session(s.id)

通过 MCP：browser_new_session(record_video=True) → browser_video_path。想为 README 准备 GIF？ 使用 ffmpeg 将 .webm 转换为 GIF（ffmpeg -i demo.webm demo.gif）。顶部的演示就是这样录制的 —— 参见 examples/make_demo.py。

工作原理

CONSUMERS                         ENGINE (library: eyebrowse/)
 Claude Code  ──MCP──▶  mcp/  ──▶  EyeBrowse façade (public API)
 your code   ─ import ──────────▶   ├─ BrowserEngine (CloakBrowser / stealth Chromium)
 any MCP client                     ├─ proxy / identity rotation (pluggable)
                                    ├─ captcha solvers (pluggable, API-mode)
                                    └─ Crawl4AI (raw: feed) → clean markdown

门面层（EyeBrowse + Session）就是产品；MCP 适配器只是对它进行薄封装的一对一包装。高级 API 经过精心设计，便于 LLM 使用 —— 并非 对 Playwright 的完整重实现 —— 而且只需访问一个属性，就能随时获取原始的 page / context / browser 对象。启动器是唯一依赖具体引擎的层；其他一切都是普通的 Playwright。

注意事项

请留意：

• evaluate 在页面的主世界中运行（可访问页面全局变量）。若要覆盖页面组件的全局变量并触发站点回调（例如用于验证码），EyeBrowse 会注入 <script>，使代码在页面世界中运行 —— 参见 captcha/inject.py。
• 导出 HAR 会关闭会话 —— 只有在上下文关闭时，Playwright 才会刷新 HAR 缓冲区。请使用检查点模式：browser_storage_state → browser_har_export → browser_new_session(storage_state=...)。若要获取包含发起方信息的 Chrome HAR（JS 调用栈），请通过 browser_cdp_send 访问 Network.* 域。
• 原生视频格式为 .webm —— 若需要其他格式，可使用 ffmpeg 转换为 GIF/MP4。

项目结构

eyebrowse/
  api.py            EyeBrowse façade — the single public entry point
  config.py         settings / secrets (pydantic-settings)
  snapshot.py       aria_snapshot(mode="ai") + aria-ref= resolution
  proxy.py          ProxyConfig + pluggable ProxyProvider
  identity.py       Identity + random_identity() (isolated profile dir)
  extract.py        Crawl4AI raw: feed → markdown (lazy, optional dep)
  engine/           engine.py (CloakBrowser launch) + session.py (verbs + registry)
  captcha/          solver ABC + 4 providers + DOM detect/inject
  mcp/              FastMCP server + state + tools/ (18 groups · 85 tools)
examples/direct_usage.py   library proof (no MCP)
examples/make_demo.py      the native-video demo above
docs/TOOLS.md              full tool reference

构建说明、版本固定理由和已验证的引擎行为见 CLAUDE.md。

负责任地使用

EyeBrowse 会驱动具有反检测功能的真实浏览器。仅在你拥有的网站或明确授权自动化的网站上使用，并遵守其条款及适用法律。

许可证

MIT © Evil-Bane