Metadata-Version: 2.4
Name: antbrowser
Version: 1.0.2
Summary: Python SDK for the Ant Browser daemon
Author: Ant Browser
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/lin293387-del/antbrowser-sdk
Project-URL: Repository, https://github.com/lin293387-del/antbrowser-sdk
Project-URL: Documentation, https://github.com/lin293387-del/antbrowser-sdk/tree/main/docs
Project-URL: Issues, https://github.com/lin293387-del/antbrowser-sdk/issues
Keywords: browser-automation,chromium,fingerprint-browser,headless-browser,ant-browser,android,termux
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# antbrowser

`antbrowser` 是 [Ant Browser](https://github.com/lin293387-del/Ant-Browser-master) 的 Python SDK，用于通过 Python 脚本操控 Ant Browser 反检测指纹浏览器守护进程（daemon）。

## 这个库能做什么？

antbrowser 是一个**反检测指纹浏览器自动化 SDK**，它让你可以用 Python 脚本完成以下工作：

- **自动管理浏览器守护进程** — SDK 会自动发现、启动或连接本地的 `ant-browser-daemon`，无需手动配置
- **创建和管理浏览器配置（Profile）** — 每个配置拥有独立的指纹、代理、Cookie 和浏览数据，互不干扰
- **生成随机浏览器指纹** — 通过 `FingerprintBuilder` 自由定制浏览器平台、分辨率、WebGL、Canvas、音频、字体等指纹参数
- **反检测与隐身模式** — 通过 `StealthBuilder` 启用 Canvas 投毒、WebGL 投毒、音频投毒、自动化痕迹抹除（WebDriver、Playwright、Selenium 标志）、权限伪装等反指纹检测能力
- **代理池管理** — 添加、验证、测速、批量替换代理，支持 Clash 订阅导入
- **浏览器内核管理** — 注册本机 Chrome / Chromium，Termux 环境下一键注册 Chromium
- **无头（headless）自动化** — 打开页面、点击元素、执行 JavaScript、截图、管理多标签页
- **Cookie 和存储管理** — 读写 Cookie、localStorage、sessionStorage
- **网络拦截与 TLS 检查** — 自定义请求拦截规则，查看 TLS 握手和流量记录
- **后台任务与下载管理** — 运行异步任务、跟踪和管理下载文件
- **实例租约管理** — 通过 acquire / renew / release 机制实现多进程间的浏览器实例协调

## 适用场景

| 场景 | 说明 |
|------|------|
| 电商多账号运营 | 每个账号独立指纹 + 独立代理，避免关联封号 |
| 数据采集 / 爬虫 | 反检测指纹 + 代理轮换，绕过指纹识别和 IP 封锁 |
| 自动化测试 | 无头启动多浏览器实例，执行页面交互和断言 |
| 社交媒体管理 | 多账号隔离环境，独立 Cookie 和存储 |
| 广告验证 | 不同地区代理 + 指纹组合查看广告投放效果 |

## 安装

```bash
pip install antbrowser
```

## 快速开始

```python
from antbrowser import AntBrowser

with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    # 查看守护进程状态
    print(browser.runtime.info())

    # 自动发现本机浏览器内核
    print(browser.discover_system_cores())
```

## 注册浏览器内核

```python
with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    # Windows: 注册 Chrome 目录
    core = browser.ensure_core(
        "C:/Program Files/Google/Chrome/Application",
        core_name="Local Chrome",
        is_default=True,
    )

    # Linux: 直接传可执行文件路径
    browser.ensure_core("/usr/bin/chromium", core_name="Chromium", is_default=True)
```

## 使用 Builder 创建带反检测的随机环境

```python
from antbrowser import AntBrowser

with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    result = (
        browser.new_profile("buyer-random")
        .random_environment(name_prefix="Buyer Random")
        .hardware(
            hardware_concurrency=8,
            device_memory=16,
            webgl_vendor="Intel",
            webgl_renderer="Intel Iris Xe",
        )
        .anti_detect("strict")
        .create(auto_launch=True, run_mode="headless")
    )
    print(result)
```

## 代理管理

```python
with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    proxy = browser.save_proxy({
        "proxyName": "Local Proxy",
        "proxyConfig": "http://127.0.0.1:7890",
        "groupName": "local",
    })

    # 验证代理
    browser.proxies.validate(proxy_config="http://127.0.0.1:7890")

    # 导入 Clash 订阅
    preview = browser.import_clash_subscription("https://example.com/subscription.yaml")
```

## 页面交互

```python
with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    result = browser.launch(profile_name="demo", run_mode="headless")
    agent_id = result["agentId"]

    # 打开页面
    browser.page.goto(agent_id, "https://example.com")

    # 点击元素
    browser.page.click(agent_id, "#login-button")

    # 执行 JavaScript
    title = browser.page.eval(agent_id, "document.title")

    # 截图
    browser.page.screenshot(agent_id)
```

## 指纹定制 (FingerprintBuilder)

```python
fingerprint = (
    browser.new_fingerprint()
    .platform("windows")
    .brand("chrome")
    .locale("en-US", "America/New_York")
    .resolution(1920, 1080)
    .color_depth(24)
    .hardware(
        hardware_concurrency=8,
        device_memory=16,
        webgl_vendor="Intel",
        webgl_renderer="Intel Iris Xe",
        media_devices="default",
        touch_points=0,
    )
    .noise(canvas_noise=True, audio_noise=True, do_not_track=True)
    .webrtc_policy("disable_non_relay")
    .fonts("Arial,Helvetica")
)

args = fingerprint.build_args()
```

## 反检测配置 (StealthBuilder)

```python
# balanced: 实用的默认反检测
stealth = browser.new_stealth().balanced()

# strict: 更强的反检测，抹除更多自动化痕迹
stealth = browser.new_stealth().strict()

# 自定义
stealth = (
    browser.new_stealth()
    .user_agent("Mozilla/5.0 ...")
    .mask_webdriver(True)
    .mask_permissions(True)
    .chrome_runtime_shim(True)
    .noise(canvas_noise=True, audio_noise=True)
    .poison(
        canvas_mode="session_stable",
        webgl_mode="session_stable",
        audio_mode="session_stable",
        seed_mode="instance_stable",
    )
)

config = stealth.build()
```

## Cookie 和存储操作

```python
with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    agent_id = "..."

    # 读取 Cookie
    cookies = browser.storage.cookies_get(agent_id)

    # 设置 Cookie
    browser.storage.cookies_set(agent_id, [
        {"name": "session", "value": "abc123", "domain": ".example.com"}
    ])

    # localStorage / sessionStorage
    browser.storage.local_storage_set(agent_id, {"key": "value"})
    browser.storage.session_storage_get(agent_id)
```

## 网络拦截

```python
with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    agent_id = "..."

    # 启用拦截
    browser.network.enable(agent_id)

    # 设置规则
    browser.network.set_rules(agent_id, [
        {"pattern": "*://ads.example.com/*", "action": "block"},
    ])

    # 查看网络记录
    browser.inspect.network_records(agent_id)
```

## Termux / Android 支持

```python
from antbrowser import AntBrowser

browser = AntBrowser(workspace="/data/data/com.termux/files/home/.ant-browser-workspace")
core = browser.ensure_termux_chromium_core()
```

## Raw API

SDK 同时提供与守护进程 HTTP 接口 1:1 对应的原始客户端：

```python
from antbrowser import RawClient

# 通过 AntBrowser 访问
browser.raw.profiles.create({...})
browser.raw.instances.list()
browser.raw.request_json("/api/any-endpoint", method="POST", body={...})
```

## 守护进程自动发现机制

SDK 按以下顺序查找 `ant-browser-daemon`：

1. 用户指定的 `daemon_path` 参数
2. `ANT_BROWSER_DAEMON_BIN` 环境变量
3. wheel 内嵌的 `ant-browser-daemon` 二进制文件
4. 系统 PATH 中的 `ant-browser-daemon`
5. 源码仓库中的 `go run ./cmd/ant-browser-daemon`

## 平台支持

| 平台 | 状态 |
|------|------|
| Windows x64 | 完整支持 |
| Linux x64 | 完整支持 |
| Linux ARM64 | 完整支持 |
| Android / Termux (arm64-v8a) | Chromium-only 工作流 |

## 文档

- [API 参考](docs/API.md)
- [教程](docs/TUTORIAL.md)
- [Termux 指南](docs/TERMUX.md)

## 许可证

AGPL-3.0-only — 详见 [LICENSE](LICENSE)

## 主项目

这是 Ant Browser 的独立 Python SDK 仓库。如需了解完整的 Ant Browser 项目（包含守护进程源码、前端界面等），请访问主仓库：

**https://github.com/lin293387-del/Ant-Browser-master**
