trueoriginlabs/vibatchium

# vibatchium **由 Agent 驱动的浏览器自动化工具，可轻松绕过 Cloudflare。** 包含补丁版的 Playwright + 多会话 daemon + 凭证保险库 + 视觉点击 + 提示词注入安全防护。一个 MCP server，N 个并行 Chrome，以及持久化的独立会话配置。 ``` pipx install vibatchium # core: browse / extract / screenshot / N parallel sessions # 需要 stealth HTTP fetch lane (vb fetch)、credential vault、VLM read 还是 REST shim？ pipx install 'vibatchium[all]' # everything; or pick extras: vibatchium[fetch], [secrets], [llm], [rest] patchright install chrome vb setup # register MCP + an auto-discoverable skill so agents reach for vb (idempotent) ``` 核心安装涵盖了所有浏览功能。`vb fetch`（curl_cffi TLS 指纹通道）属于 `[fetch]` 额外扩展；`vb install` 会报告哪些可选通道可用。在 **uv** venv （不含 pip）中，请使用 `uv pip install --python /bin/python curl_cffi` 添加额外扩展。 ``` vb explore https://example.com # one-call: text-first (screenshot only as a fallback) vb research --target https://example.com \ # parallel fan-out, N intents --intent "pricing model" --intent "customers" --intent "tech stack" ``` **状态：** 正在积极开发中，处于 Alpha 阶段。606 项测试通过。在 bot.sannysoft.com 上取得 31/31 的成绩。成功冷启动绕过 HackerOne 的 Cloudflare。采用 Apache-2.0 协议（仅在启用可选的 `nodriver` 扩展时受 AGPL 约束）。 ## 更新 ``` vb update # upgrade to the latest PyPI release + restart the daemon vb update --version 0.6.8 # or pin a specific version ``` `vb update` 会检测 vibatchium 的安装方式（pipx 或 pip，带有 PEP-668 `--break-system-packages` 回退机制），然后**停止正在运行的 daemon**，以便 下一条命令加载新代码。手动等效操作： ``` pipx upgrade vibatchium # or: pip install -U vibatchium vb shutdown # bounce the daemon — it serves old code until you do vb --version # confirm ``` ## 为什么选择 vibatchium | | Vibium | Patchwright | Browser-Use | vibatchium | |---|---|---|---|---| | 对 LLM 友好的 `@eN` 引用 + `map` / `diff map` | ✅ | ❌ | ❌ | ✅ | | Cloudflare CDP 泄漏补丁 | ❌ | ✅ | ❌ | ✅ | | **一个 daemon 支持多个并行浏览器** | ❌ | 手动 | ❌ | ✅ | | 每个会话的持久化配置（cookie、登录状态） | ✅ | 手动 | 手动 | ✅ | | 通过 CDP 附加到手动登录的 Chrome | ❌ | 手动 | ❌ | ✅ | | **加密的凭证保险库**（密码 + TOTP） | ❌ | ❌ | ❌ | ✅ | | **IMAP 邮件验证码轮询** (2FA) | ❌ | ❌ | ❌ | ✅ | | 每个会话独立代理 + WebRTC 泄漏防护 | ❌ | 手动 | ❌ | ✅ | | 优先使用视觉点击并带有支出上限 | ❌ | ❌ | ✅ | ✅ | | **针对抓取内容的提示词注入分类器** | ❌ | ❌ | ❌ | ✅ (0% FP / 204 样本) | | 带有接管功能的实时画面流 (WebSocket) | ❌ | ❌ | 部分 | ✅ | | Bearer token REST 垫片 + 权限限制 | ❌ | ❌ | 手动 | ✅ | | `research` 命令（并行扇出） | ❌ | ❌ | ❌ | ✅ | ## 10 行代码实现多会话 ``` vb session new work vb --session work start vb --session work go https://github.com # log in by hand once vb session new banking vb --session banking start vb --session banking go https://bank.example.com vb --session work click @e3 & # truly parallel — vb --session banking fill @e5 hi & # separate Chromes, no cookie bleed wait vb session list ``` 活动会话解析优先级：`--session FLAG` → `$VIBATCHIUM_SESSION` env → `~/.config/vibatchium/active-session` → `default`。通过 `VIBATCHIUM_MAX_SESSIONS=4` 限制（默认为 4）。 ### 多 Agent：共享会话与私有 daemon 的对比 在**一个**共享 daemon 上，会话提供了真正的指纹隔离（独立的 Chrome，没有 cookie 串扰），但共享主机资源：会话数量预算、 内存，以及发生 OOM 或 daemon 崩溃时的爆炸半径。两种模型，可根据 信任级别进行选择： - **协作型 Agent（你自己的集群）：** 共享 daemon 是正确的选择 —— 只需为 每个并发 Agent 提供一个**唯一的 `--session` 名称**，这样有状态的流程就不会 在 `default` 上发生冲突。`vb session lease` 用于协调共享名称。 - **私有的爆炸半径：** 在每个 Agent 自己的 socket + `HOME` 上运行 **独立的 daemon** —— 具有独立的配置/状态、自己的会话预算，与 共享 daemon 零接触。`vb daemon start --isolated` 会打印出供后续调用 export 的 `XDG_RUNTIME_DIR`/ `HOME`；`vb mcp --isolated` 直接在它自己的私有 daemon 上运行 MCP server。`vb daemon reap` 会清理被遗弃的 daemon。 （相同的 UID = 相同的信任域 —— 这限制的是*爆炸半径*，而不是 互不信任的租户之间的安全边界；为此，请使用独立的 UID/container。） **资源治理。** 会话上限限制的是进程*数量*，而不是字节数。在 共享机器上，设置 `VIBATCHIUM_SESSION_RAM_FLOOR_MB` 可在空闲 内存不足时拒绝新启动（一种可移植的准入带）。对于硬性上限，请在 cgroup 下运行 daemon —— `systemd-run --user --scope -p MemoryMax=4G vb daemon start` 会将 daemon **及其所有 Chrome** 置于一个共享限制的 cgroup 中：这是一个*聚合的* daemon 范围内的上限（非每个 renderer），并且一旦超限，作用域内部会发生 OOM-kill，这 可能包括 daemon 本身。这是唯一没有竞态条件的内存限制，因此请根据 整个扇出规模来设定其大小。 ## 文档 - [`AGENTS.md`](AGENTS.md) — 编码 Agent 契约（Codex / Cursor / Claude Code） ## Server 模式 | 模式 | 对外接口 | 认证 | |---|---|---| | `vb mcp` | stdio JSON-RPC；默认为**精简的**约 80 个动词配置（使用 `--caps=full`/`all` 获取完整接口；使用 `--caps=...` 获取自定义桶集） | 无 (stdio) | | `vb serve` | `127.0.0.1:8000` 上的 FastAPI；每个动词位于 `POST /v1/`；WebSocket 实时画面位于 `/v1/stream/` | bearer token (`~/.cache/vibatchium/rest-token`，模式 0600) | **REST 权限限制**：`vb serve --caps=core,nav,input,vision` 限制 HTTP 接口的方式与 `mcp --caps` 相同。如果没有此设置，REST 将授予等同于本地代码的访问权限（eval + secret_* + 文件写入动词全部暴露） —— 适用于 localhost 开发，但**不**适用于托管/多租户环境。 ## 隐身等级 —— 各自能绕过什么 隐身是一个阶梯，而不是一个布尔值。选择能绕过你目标站点的最低等级 （更高的等级需要更多的设置 / 可见的浏览器 / 手动登录）。vibatchium **不**声称能在冷启动下击败行为检测墙 —— 这些需要真实的 人工驱动的会话，而 attach 模式是最可靠的解决方案。 | 等级 | 方式 | 能绕过 | 无法绕过 | |---|---|---|---| | **标准**（默认） | 无头模式冷启动，真实的 `channel=chrome`，去 Headless 特征的 UA | Cloudflare IUAM / 托管质询，`bot.sannysoft` 31/31，JS 运行时指纹检测 | 激进的 Turnstile、DataDome/Kasada、登录墙后的任何内容 | | **加固** | 重试 `--headed`；`vb humanize on`；对于最难的 Cloudflare 门槛使用 `--backend nodriver`（`pip install vibatchium[nodriver]`，AGPL） | 激进的 Cloudflare/Turnstile、无头模式遗留的 GPU/屏幕特征 | 行为生物识别、DataDome/Kasada 传感器融合 | | **Attach** | `vb attach` 到一个**由你**启动并登录的 Chrome | DataDome / Kasada / HUMAN 行为检测墙，以及任何已认证的会话 —— 使用你真实的指纹 + cookie | 这里没有任何内容是自动化的冷启动；它需要先进行人工登录 | 遇到检测墙时的升级阶梯：**无头模式 → `--headed` → `humanize on` → `--backend nodriver` → 手动登录后的 attach 模式。** Patchright 的 CDP 层 补丁适用于*所有*等级，包括 attach（`connect_over_cdp`）。 ## Attach 模式 —— 实用的 Cloudflare 解决方案 对于阻挡冷启动自动化的 DataDome / Kasada / 强化版认证： ``` google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile & # 手动登录 walled site vb attach http://localhost:9222 vb go https://target.example.com # now reads as your real browser ``` Patchright 的 CDP 层隐身技术仍然适用于 `connect_over_cdp` —— attach 模式获得了与冷启动相同的协议级补丁，加上你真实的浏览器指纹以及来自手动登录的任何 cookie。 ## 安全模型 凭证永远不会出现在日志、HAR 捕获、观察缓存或 Agent 可见的响应字段中（已在 CI 中经过 grep 测试）。保险库使用 XSalsa20-Poly1305 加密，密钥来源于 OS 密钥环或 `VIBATCHIUM_SECRETS_KEY`。所有由 vibatchium 写入的文件权限为 0600；目录权限为 0700。 对于 REST 垫片：如果不使用 `--caps`，bearer token 将授予每个动词的权限，包括 `eval`、`secret_*` 和文件写入动词。这等同于本地代码权限 —— 在托管模式下务必传递 `--caps=...`。默认情况下，实时画面仅绑定到 127.0.0.1（使用 `--insecure-public` 可覆盖此设置）。 ## 客观的局限性 - **5 个以上的并发会话 = 1-2GB 内存。** 每个持久化上下文的 Chrome 大约需要 200-400MB。可通过 `VIBATCHIUM_MAX_SESSIONS=8` 提高上限。 - **视觉功能支出上限是进程范围的。** N 个扇出 Agent 共享一个每日/终身预算。 - **Init 脚本在 patchright backend 上不起作用。** `chrome.runtime` 保持 `undefined` —— 这是为了隐身效果而做出的妥协。 - **登录墙（X、LinkedIn）需要 attach 模式。** 冷启动扇出无法击败需要认证会话的网站。 - **合成输入具有 CDP 坐标特征。** 每个 `click`/`type`/`hover`/`scroll` 都通过 CDP 的 `Input.dispatchMouseEvent`/`dispatchKeyEvent` 依托 Playwright 运行（`pageX==screenX`，没有 `CoalescedEvents`）。Patchright 修补了 JS 上下文的泄漏，但没有修补 Input 域，并且 `humanize on` 提升了轨迹/时序的真实性，但**不**改变单个事件的签名。对其进行指纹识别的行为检测墙（DataDome/Kasada/HUMAN）需要**对你驱动的真实 headful Chrome 使用 attach 模式** —— 操作系统级别的合成输入（CDP-Patches）仅适用于 headful + 活动标签页，不适用于无头、N 并行的 daemon。 - **`fetch` 是一个静态指纹通道，而不是浏览器。** curl_cffi 的 `fetch` 动词与 Chrome 的 JA3/HTTP2 指纹相匹配，但不运行 JavaScript —— 它能绕过 TLS 指纹检测，但无法绕过 DataDome/Kasada/Turnstile 的 JS 质询。针对这些情况请退回到 `go`。 - **单一 daemon = 单点故障。** 没有内置的高可用性 (HA)。 ## 许可证 核心采用 Apache-2.0。每个默认安装的额外扩展也都是宽松的许可 —— `fetch` 通道的 curl_cffi 采用 **MIT** 协议。唯一的 copyleft 选项是可选择启用的 `nodriver` backend (AGPL-3.0) —— 在将其商业整合之前请咨询许可。基础安装或 `[all]` 中绝对不包含任何 GPL/AGPL 组件。

标签：MCP, Playwright, RPA, 人工智能, 反爬虫, 浏览器自动化, 特征检测, 用户模式Hook绕过, 逆向工具