内容
<div align="center">
<img src="Assets/logobb.png" width="180" alt="Bladebro" />
# ⚡ Bladebro
**赋予您的 AI 代理一个浏览器。少数工具。全方位控制。真正的隐身。零运行时依赖。**
驱动 · 点击 · 输入 · 滚动 · 隐身 · 结算 · delta-first · 一个二进制文件
一个 MCP 服务器 · 一个持久页面模型 · 零 Node.js · 在您的机器上运行
[](LICENSE)
[](https://www.rust-lang.org)
[](#-install)
[](https://github.com/dondai44423/bladebro)
```bash
cargo build --release && ./target/release/bladebro mcp
```
[安装](#-install) · [5 种工具](#-the-5-tools) · [隐身系统](#-stealth-system) · [比较](#-comparison) · [注意事项](#-gotchas)
</div>
---
Bladebro 是一个从代理的角度构建的浏览器驱动程序。不同于 20 多种工具每种工具只做一件事，Bladebro 提供 **5 种工具**，它们共同提供完全的控制权。它驱动股票 Chromium 浏览器，通过 CDP 管理，并保持一个持久的 **实时页面模型**，在工具调用之间返回 **差异优先** 的结果：代理看到的是变化，而不是整个世界，每次都是如此。
使用 Rust 构建。单个静态二进制文件。无需运行时。无需 Node.js。无需 Playwright shim。只有浏览器引擎和您的代理。原生支持 Linux、macOS 和 Windows。
## 🔧 安装
**先决条件：** Chromium 或 Google Chrome（自动检测），Rust 1.80+。Linux：用于无头服务器的 Xvfb（macOS/Windows 原生运行）。
```bash
git clone https://github.com/dondai44423/bladebro.git
cd bladebro
cargo build --release
```
就这样。Bladebro 自己找到 Chrome，启动时带有隐身标志，并管理其生命周期。
**通过 stdio 上的 MCP 连接您的 AI 代理：**
```json
{ "mcpServers": { "bladebro": { "command": "/path/to/bladebro", "args": ["mcp"] } } }
```
| 环境变量 | 默认值 | 功能 |
|---|---|---|
| `CHROME_PATH` | 自动 | Chrome/Chromium 二进制文件路径 |
| `BLADE_PROFILE_DIR` | `~/.blade/profile` | 持久浏览器配置文件 |
| `BLADE_FRESH` | 未设置 | `1` = 短暂配置文件（无持久性） |
| `BLADE_LOCALE` | `en-US` | BCP-47 地区（例如 `en-GB`、`ne-NP`） |
| `BLADE_TZ` | 自动（IP 地理位置） | 时区（例如 `Europe/London`、`Asia/Kathmandu`） |
| `BLADE_NOISE` | 未设置 | `1` = 启用画布/音频指纹噪音 |
| `BLADE_WEBGL` | `auto` | `spoof` / `real` / `auto` |
| `BLADE_MEDIA` | `auto` | `patch` / `real` / `auto` |
| `BLADE_PROXY` | 无 | 代理 URL |
## 🎯 5 种工具
### `act` | 操作，然后观察
12 种操作。每种 `act` 操作都返回一个 **观察结果**（场景 + 增量 + 结果），而不是 `✓ Done`。
| 操作 | 示例 | 功能 |
|---|---|---|
| `click` | `act click e5` | 鼠标、JS、Enter 键升级；遇到 DOM 更改时中断 |
| `type` | `act type e2 "hello" press=Enter` | 有节奏的输入，带有可选的按键操作 |
| `fill` | `act fill fields=[...]` | 自动检测类型：文本框、下拉菜单、复选框 |
| `select` | `act select e4 "Nepal"` | 匹配可见文本和值，不区分大小写 |
| `navigate` | `act navigate "https://example.com"` | 幂等（如果已经存在，则不执行） |
| `scroll` | `act scroll down 3` | 平滑的多步滚动事件 |
| `hover` | `act hover e3` | 贝塞尔曲线鼠标路径，触发 CSS `:hover` |
| `read` | `act read e5` | 提取元素文本内容（最多 5000 个字符） |
| `wait` | `act wait condition=element text="Submit" timeout=5` | 轮询直到条件满足 |
| `back` | `act back` | 历史记录后退，总结已删除的元素 |
| `upload` | `act upload e7 path="/tmp/file.txt"` | `DOM.setFileInputFiles` |
| `press` | `act press Enter` | 真实的按键事件，带有键码查找 |
**文本寻址** | 不需要：`act click text="Sign in"` 通过可见文本查找元素。
**点击升级** | 鼠标、JS、Enter 键。遇到 DOM 突变（MutationObserver）、对话框或导航时提前中断。不会重复触发。
### `see` | 感知页面
| 调用 | 返回内容 |
|---|---|
| `see` | 完整页面视图（按令牌预算，大约 50 字节/元素） |
| `see filter="button,link"` | 过滤视图（逗号分隔的角色/名称） |
| `see content=true` | 页面文本内容 |
| `see find="Sign in"` | 查找元素/文本，返回引用 + 上下文片段 |
| `see extract="table"` | 结构化数据提取 |
8KB 预算上限 = 最大约 2100 个令牌，即使在 2000 个元素的页面上也是如此。当有 3 个或更少的 actionable 元素时，自动包含页面文本（节省一次往返）。
### `state` | cookie、存储、标签页、会话
| 调用 | 功能 |
|---|---|
| `state cookies` | 列出所有 cookie |
| `state storage get key=mykey` | 获取 localStorage 值 |
| `state tabs` | 列出打开的标签页 |
| `state save_session name=login` | 保存 localStorage + cookie（完整保真度） |
| `state load_session name=login` | 恢复会话 |
| `state proxy "http://host:port"` | 设置代理 |
### `run` | 批处理 + 分支
```json
{"action":"type","ref":"e1","text":"rust browser"}
{"action":"press","key":"Enter"}
{"action":"wait","condition":"element","text":"Results","timeout":5}
{"action":"click","ref":"e2"}
```
条件分支在一个调用中：
```json
{"action":"if","condition":"element","text":"Submit","timeout":5,
"then":[{"action":"click","ref":"e1"}],
"else":[{"action":"click","ref":"e2"}]}
```
### `vision` | 截图（罕见的备用方案）
返回 base64 PNG。对于画布内容、异国风情的布局或结构模型失败时的情况。
## 🛡️ 隐身系统
六层。默认全部启用。无需配置。
| 层级 | 功能 |
|---|---|
| **协议** | 无 `Runtime.enable`（解除 DataDome 控制台陷阱），CDP 通过管道（零监听端口，Unix） |
| **环境** | UA 覆盖（无 HeadlessChrome），WebGL 渲染器，outerWidth/innerWidth，屏幕几何，硬件并发，设备内存，权限，媒体设备 |
| **行为** | 贝塞尔曲线鼠标路径带有超调 + 校正，对数正态输入节奏，空闲嗡鸣（空闲时鼠标移动），平滑滚动 |
| **一致性** | 每个域的隐身内存（时区 + 地区），地理一致的身份，WebRTC 关闭，稳定的画布/音频（默认无噪音） |
| **残留物** | 删除 cdc_ 属性，原生 toString 完整性，MutationObserver 用于晚期工件 |
| **调味** | 持久浏览器配置文件（localStorage 在重启期间存活），存储配额，字体审计 |
**针对真实检测站进行验证：**
| 测试 | 分数 |
|---|---|
| 36 矢量本地套件 | 36/36 通过 |
| bot.sannysoft.com | 全部通过 |
| incolumitas.com | 无机器人检测 |
| 自我检查 | 4/4 确认 |
运行 `bladebro audit` 以验证您自己的设置。
## 📊 比较
| | Bladebro | Playwright MCP | Chrome DevTools MCP |
|---|---|---|---|
| 工具定义 | 约 940 个令牌 | 约 13700 个令牌 | 约 8000 个令牌 |
| 每次点击结果 | 60-570 个令牌（增量） | 2000+ 个令牌（完整页面） | 2000+ 个令牌 |
| 隐身 | 6 层，内置 | 无 | 无 |
| 运行时 | 无（静态二进制文件） | Node.js | Node.js |
| 进程模型 | 长寿命守护进程（有状态） | 无状态（每次调用重新连接） | 无状态 |
| 页面模型 | 持久，引用稳定，增量优先 | 无 | 无 |
| 二进制文件大小 | 5.1MB | 约 50MB（node + 依赖） | 约 50MB（node + 依赖） |
| 平台 | Linux，macOS，Windows | Linux，macOS，Windows | Linux，macOS，Windows |
**比所有竞争对手效率高 3-4 倍**。实时页面模型是核心创新：它在工具调用之间保持持久的、压缩的、引用稳定的页面模型。每次 `act` 操作都返回一个 **增量**（更改内容），而不是整个页面。引用（`e1`、`e2`，...）是稳定的语义锚点，在 DOM 突变中存活下来。不会再出现“过期元素”失败。
## ⚠️ 注意事项
| 惊喜 | 原因 |
|---|---|
| Cloudflare Turnstile 阻止 Bladebro | Turnstile 需要实际的挑战解决，而不仅仅是指纹伪造。你会得到一个 `blocked:` 结果，而不是卡住。 |
| 数据中心 IP 地址被标记 | 服务器/VPS IP 地址会被标记，无论浏览器指纹如何。使用 `BLADE_PROXY` 和住宅代理。 |
| 跨源 iframe 不可见 | `contentDocument` 上的 SecurityError。故意限制；需要 `Runtime.enable`（破坏隐身）。 |
| `BLADE_NOISE=1` 可能 *损害* 隐身 | FingerprintJS ML 检测到噪音注入为“浏览器篡改”。默认关闭。只有当你知道原因时才使用。 |
## 🤝 贡献
欢迎提交 PR。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。在提交前运行 `cargo clippy --release -- -D warnings` 和 `cargo test --release`。
## 📄 许可证
MIT | 参见 [LICENSE](LICENSE)。
