Metadata-Version: 2.5
Name: ysbrowser-sdk
Version: 0.11.5.post2
Summary: YSbrowser 同步与异步 Python SDK，支持上下文配置、代理、诊断和模型鼠标轨迹
Project-URL: Documentation, https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/README.html
Project-URL: Homepage, https://github.com/selfshore/YSbrowser
Project-URL: Issues, https://github.com/selfshore/YSbrowser/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy<3,>=1.26
Requires-Dist: onnxruntime<2,>=1.17
Requires-Dist: patchright==1.64.2
Requires-Dist: py7zr<2,>=1.1
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: psutil<8,>=6; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: twine<8,>=7; extra == 'dev'
Description-Content-Type: text/markdown

# YSbrowser SDK 0.11.5.post2

配套 YSbrowser 定制浏览器的 Python 自动化库，支持 Windows 和 Linux，提供同步与异步接口、浏览器上下文配置、代理、登录状态保存、模型鼠标轨迹和诊断功能。

- [完整使用手册（含代码高亮与全文搜索）](https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/README.html)
- [drag_element 的全部参数和返回结构](https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/drag-element.html)

## 安装

需要 Python 3.10 或更高版本。在运行脚本的同一个 Python 环境安装：

```shell
python -m pip install --upgrade ysbrowser-sdk
```

Windows / Linux 均可运行以下命令，自动选择配套的 [YSbrowser 6.4](https://github.com/selfshore/YSbrowser/releases/tag/6.4)：Windows 下载 `chrome.7z`，Linux 下载 Ubuntu 24.04 x86_64 AppImage。默认资产自动校验 SDK 内置的 SHA-256。

```shell
python -m ysbrowser_sdk install
```

浏览器默认安装到当前目录的 `./browsers`，下载压缩包在解压完成后删除。随后在同一工作目录运行自动化脚本。需要其他版本时，可通过 `--url` 指定压缩包直链。

Linux 默认下载 AppImage，无需配置下载地址。也可设置 `YSBROWSER_LINUX_BROWSER_URL` 或 `--url` 覆盖。安装器赋予执行权限并记录入口，不会在安装期间执行下载的文件。SDK 与 AppImage 必须在同一个 Linux/WSL 环境运行；当前默认 Linux 包面向 Ubuntu 24.04 x86_64，要求 AVX2、FMA、F16C。Ubuntu AppArmor 沙箱处理见 [6.4 发布说明](https://github.com/selfshore/YSbrowser/releases/tag/6.4)。

Python 包不包含浏览器，依赖 Patchright 1.64.2、NumPy 和 ONNX Runtime；鼠标模型推理不需要 PyTorch。请勿单独升级固定版本的 Patchright。

## 同步使用

```python
from ysbrowser_sdk.sync_api import YSBrowser

with YSBrowser(headless=False) as browser:
    context = browser.new_context()
    page = context.new_page()
    page.set_content('<button style="position:absolute;left:700px;top:300px">目标</button>')
    mouse = context.mouse(page)

    # 按模型轨迹从指定起点移动到终点
    result = mouse.move_between(100, 200, 500, 300)

    # 移动到指定元素并点击
    result = mouse.click_element(page.get_by_role("button", name="目标"))
    print(result.plan.model_id, result.plan.data_source)
```

异步代码从 `ysbrowser_sdk.async_api` 导入，使用 `async with`，并在异步操作前加 `await`。完整示例见[使用手册](https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/installation.html)。

## Windows 与 Linux 配置

两种系统使用同一个 Python 安装包和同一套同步、异步接口。所有文件路径均相对于运行 Python 的系统解析。

省略 `server_gpu_backend` 时，Windows 默认使用 `warp`，Linux 默认使用 `llvmpipe`。显式指定时会在启动前校验：

| 系统 | 支持的图形后端 |
| --- | --- |
| Windows | `warp`、`swiftshader` |
| Linux | `llvmpipe`、`native`、`software`、`swiftshader` |

已有浏览器时，可以直接传入可执行文件路径：

```python
from ysbrowser_sdk.sync_api import YSBrowser

# Windows 使用 ./browser/chrome.exe；Linux 使用 ./browser/chrome
with YSBrowser(executable_path="./browser/chrome.exe", headless=False) as browser:
    context = browser.new_context()
    page = context.new_page()
    page.set_content("<h1>浏览器已启动</h1>")
```

Linux 需要安装 Chromium 所需的共享库、字体和沙箱运行依赖。在 WSL 中显示窗口及播放系统语音，还需要可用的 WSLg 图形和音频环境。

## 鼠标操作

鼠标轨迹由随包模型生成。`move()`、`move_to()` 使用绝对坐标，`move_by()` 使用相对距离，`move_between()` 指定起点和终点。省略 `duration_s` 时，模型自动预测运动时长。

模型操作通过 `context.mouse(page)` 调用；`page.mouse` 和定位器仍按 Patchright 原生接口使用。

- [鼠标完整接口](https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/mouse.html)
- [上下文与代理](https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/proxy.html)
- [上下文参数及诊断](https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/context-options.html)
- [从 A 点到 B 点的可运行示例](https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/examples/mouse_between.py)
- [拖动示例](https://selfshore.github.io/YSbrowser/sdk/0.11.5.post2/examples/mouse_drag.py)

## 6.4 两端修订（2026-11-01）

SDK 0.11.5.post2 更新 Windows chrome.7z 和 Linux AppImage 的固定 SHA-256，浏览器 Release 仍为 6.4。两端修复预渲染期间语音初始化的同步等待；字体改为按配置语言的书写体系选择额外池，再由 seed 稳定选择家族。系统基础字体不计入额外池，网页字体和多语言文本回退保留。

额外池包含 22 个文字体系、181 个真实开源家族。常用体系各 10 个，部分语言少于 10 个，不重复计入系统字体或把字重当作不同家族。字体只能提供语言线索，不能证明 IP 所在国家，也不保证第三方检测器的评分。

升级后运行 `python -m ysbrowser_sdk install`，安装器会按新哈希下载并启用修订包；已有浏览器进程需要关闭重开。旧 SDK 的固定哈希不匹配时会拒绝新的包，请升级 SDK，不要关闭校验。直接指定可执行文件路径的 API 不变。
