feat: initial Python SDK implementation

- brosdk/ffi.py: ctypes C bindings for brosdk.dll/dylib
- brosdk/manager.py: high-level BrosdkManager with event callbacks
- brosdk/api.py: REST API client (getUserSig, create, page)
- brosdk/console.py: optional Windows DLL console output helper
- demo.py: interactive CLI demo
- README.md, pyproject.toml, requirements.txt, .gitignore

Author: dreamsxin

.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+
+# 虚拟环境
+.venv/
+venv/
+env/
+.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# 原生库二进制（用户自行放置）
+libs/*.dll
+libs/*.dylib
+libs/*.so
+
+# 工具目录
+.workbuddy/
+
+# 根目录散落的二进制 / 压缩包
+*.dll
+*.dylib
+*.so
+*.h
+*.zip
+

README.md

@@ -0,0 +1,207 @@
+# brosdk-sdk-python
+
+Python 语言绑定库 + 交互式命令行 Demo。
+
+通过 `ctypes` 动态加载平台 DLL/dylib，暴露安全、符合 Python 惯用法的 API。
+
+## 项目结构
+
+```
+brosdk-sdk-python/
+├── brosdk/
+│   ├── __init__.py      # 公共 API 导出
+│   ├── ffi.py           # 原始 C ctypes 绑定
+│   ├── manager.py       # 高级安全封装 + 事件回调
+│   └── api.py           # REST API 客户端
+├── libs/
+│   ├── brosdk.dll       # Windows x64 原生库
+│   └── brosdk.dylib     # macOS arm64 原生库
+├── demo.py              # 交互式命令行 Demo
+├── pyproject.toml       # 项目配置
+├── requirements.txt     # 可选依赖
+└── README.md
+```
+
+## 环境要求
+
+- Python 3.8+
+- 从 [github.com/browsersdk/brosdk-sdk/releases](https://github.com/browsersdk/brosdk-sdk/releases) 下载原生库并放置到 `libs/` 目录
+
+## 快速开始
+
+### 安装依赖（可选）
+
+```bash
+pip install -r requirements.txt
+```
+
+> 不安装也能运行，`requests` 会降级到内置 `urllib`，`colorama` 会降级为无色输出。
+
+### 运行 Demo
+
+```bash
+# 交互式菜单
+python demo.py
+
+# 预填 API Key 直接进入
+python demo.py --api-key YOUR_API_KEY
+
+# 快速演示（自动执行所有步骤）
+python demo.py --quick --api-key YOUR_API_KEY
+
+# 使用已有环境跳过创建步骤
+python demo.py --quick --api-key YOUR_API_KEY --env-id ENV_ID
+
+# 开启详细日志
+python demo.py --verbose
+```
+
+### Demo 使用流程
+
+1. **选择 `1`** → 输入 API Key → 自动获取 userSig → 初始化 SDK
+2. **选择 `2`** → 查看环境列表（SDK 接口或 REST API）
+3. **选择 `3`** → 选择内核版本（可选代理）→ 创建新环境
+4. **选择 `4`** → 启动浏览器环境（异步，等待 SDK 事件回调）
+5. **选择 `5`** → 关闭浏览器环境
+
+## 库使用方式
+
+### 基础用法
+
+```python
+from brosdk import BrosdkManager
+
+def on_event(event):
+    print(f"SDK 事件: code={event.code}, data={event.data}")
+
+sdk = BrosdkManager()
+sdk.on_event(on_event)
+
+# 加载原生库
+sdk.load("libs/brosdk.dll")      # Windows
+# sdk.load("libs/brosdk.dylib")  # macOS
+
+# 初始化（user_sig 通过 REST API 获取）
+sdk.init("your_user_sig", "/tmp/.brosdk", port=8080)
+
+# 启动环境
+import json
+sdk.browser_open(json.dumps({
+    "envs": [{"envId": "env-001", "args": ["--no-first-run"]}]
+}))
+
+# 关闭环境
+sdk.browser_close("env-001")
+
+sdk.shutdown()
+```
+
+### 使用上下文管理器
+
+```python
+from brosdk import BrosdkManager
+
+with BrosdkManager("libs/brosdk.dll") as sdk:
+    sdk.init("user_sig", "/tmp/.brosdk")
+    sdk.browser_open('{"envs": [{"envId": "env-001"}]}')
+    # SDK 会在 with 块结束时自动 shutdown
+```
+
+### REST API 客户端
+
+```python
+from brosdk.api import BrosdkApiClient
+
+client = BrosdkApiClient(api_key="your-api-key")
+
+# 获取 userSig
+user_sig = client.get_user_sig()
+
+# 创建环境
+env = client.create_env(kernel_version="127", proxy="http://127.0.0.1:8080")
+print(f"创建成功: {env.env_id}")
+
+# 查询环境列表
+result = client.page_env(page=1, page_size=20)
+for e in result.list:
+    print(f"{e.env_id}: {e.env_name} ({e.kernel_version})")
+
+# 获取所有环境（自动翻页）
+all_envs = client.list_all_envs()
+```
+
+### 监听 SDK 事件
+
+```python
+from brosdk import BrosdkManager, SdkEvent
+
+sdk = BrosdkManager()
+
+@sdk.on_event
+def handle_event(event: SdkEvent):
+    if event.is_ok():
+        print(f"成功: {event.data}")
+    else:
+        data = event.data_json()  # 自动解析 JSON
+        print(f"事件 code={event.code}: {data}")
+```
+
+> **注意**：`browser_open` 是异步操作，结果通过事件回调返回，不阻塞主线程。
+
+## API 参考
+
+### `BrosdkManager`
+
+| 方法 | 说明 |
+|------|------|
+| `load(lib_path)` | 加载原生库，注册回调 |
+| `init(user_sig, work_dir, port)` | 用凭据初始化 SDK |
+| `sdk_info()` | 查询 SDK 运行时信息 |
+| `browser_open(json_str)` | 启动浏览器环境（异步） |
+| `browser_close(env_id)` | 关闭浏览器环境 |
+| `token_update(token_json)` | 刷新访问令牌 |
+| `env_create(config)` | 创建新环境 |
+| `env_page(page, page_size)` | 分页查询环境列表 |
+| `env_update(config)` | 更新环境配置 |
+| `env_destroy(env_id)` | 销毁环境 |
+| `shutdown()` | 优雅关闭 |
+| `on_event(callback)` | 注册事件监听器 |
+| `off_event(callback)` | 移除事件监听器 |
+
+### `BrosdkApiClient`
+
+| 方法 | 说明 |
+|------|------|
+| `get_user_sig(duration)` | API Key → userSig |
+| `create_env(kernel_version, ...)` | 创建环境 |
+| `page_env(page, page_size)` | 分页查询环境 |
+| `list_all_envs(page_size)` | 获取所有环境（自动翻页） |
+
+### `SdkEvent`
+
+```python
+@dataclass
+class SdkEvent:
+    code: int    # SDK 状态码
+    data: str    # JSON 数据字符串
+
+    def is_ok(self) -> bool: ...       # 是否成功
+    def data_json(self) -> Any: ...    # 解析 data 为 Python 对象
+```
+
+## 构建
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 构建发布包
+python -m build
+```
+
+## 协议
+
+MIT

brosdk/__init__.py

@@ -0,0 +1,29 @@
+"""
+brosdk-sdk-python
+=================
+
+Python 语言绑定库，动态加载平台 DLL/dylib 并暴露安全、符合 Python 惯用法的 API。
+
+快速开始
+--------
+
+.. code-block:: python
+
+    from brosdk import BrosdkManager
+
+    sdk = BrosdkManager()
+    sdk.load("libs/windows-x64/brosdk.dll")
+    sdk.init("your_user_sig", "/path/to/work_dir", 8080)
+
+    sdk.browser_open('{"envs": [{"envId": "env-001"}]}')
+    sdk.browser_close("env-001")
+    sdk.shutdown()
+"""
+
+from .manager import BrosdkManager, SdkEvent
+from .ffi import BrosdkLib
+
+__version__ = "1.0.0"
+__all__ = [
+    "BrosdkManager", "SdkEvent", "BrosdkLib",
+]