Metadata-Version: 2.4
Name: fengchao-sdk
Version: 1.0.0
Summary: 蜂巢云控 Python SDK - 手机自动化控制
Home-page: https://github.com/fendoushaonian/phone-control
Author: 蜂巢云控
Author-email: support@qunkong.com
Project-URL: Documentation, https://qk.lhy.lat/docs/sdk
Project-URL: Bug Reports, https://github.com/fendoushaonian/phone-control/issues
Project-URL: Source, https://github.com/fendoushaonian/phone-control
Keywords: android automation control phone fengchao qunkong accessibility hid adb
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: websocket-client>=1.0.0
Requires-Dist: requests>=2.20.0
Provides-Extra: image
Requires-Dist: Pillow>=8.0.0; extra == "image"
Provides-Extra: all
Requires-Dist: Pillow>=8.0.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 蜂巢云控 Python SDK

简单、强大的手机自动化控制SDK，支持无障碍、ADB、HID/OTG三种控制方式。

## 特性

- 🚀 **简单易用** - 几行代码即可控制手机
- 🔄 **统一接口** - 一套API支持三种控制方式
- 📱 **批量控制** - 同时控制多台设备
- 🔌 **直连模式** - SDK直连手机，不经过服务器
- 🌐 **中继模式** - 通过中继服务器远程控制
- 🛡️ **防检测** - HID模式绕过应用检测

## 三种连接模式

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **调试模式** | 电脑直连手机（局域网） | 本地开发调试 |
| **中继模式** | 通过用户自建中继服务器 | 远程控制、生产环境 |
| **中央模式** | 通过中央服务器获取设备IP后直连 | 设备管理 |

## 安装

### 方式1：从GitHub安装（推荐）

```bash
pip install git+https://github.com/fendoushaonian/phone-control.git#subdirectory=sdk/python
```

### 方式2：从PyPI安装

```bash
pip install fengchao

# 或者安装完整版（包含图像处理）
pip install fengchao[all]
```

### 方式3：下载源码安装

```bash
git clone https://github.com/fendoushaonian/phone-control.git
cd phone-control/sdk/python
pip install .
```

## 快速开始

### 方式1：通过服务器获取设备

```python
from fengchao import Client

# 初始化客户端
client = Client(api_key="your-api-key")

# 获取设备
device = client.get_device("DEVICE_001")

# 操作设备
device.click(500, 800)
device.swipe(500, 1500, 500, 500)
device.input_text("Hello World")
```

### 方式2：中继模式（推荐生产环境）

```python
from fengchao import Client

# 连接到你的中继服务器
client = Client(
    api_key="your-api-key",
    relay_server="http://your-relay-server:9999"
)

# 获取设备（通过device_id）
device = client.get_device("DEVICE_001")

# 操作设备（命令通过中继服务器转发）
device.click(500, 800)
device.swipe_up()
```

### 方式3：调试模式（局域网直连）

```python
from fengchao import Client

# 调试模式：电脑直连手机
client = Client(
    api_key="your-api-key",
    debug=True,
    debug_ip="192.168.1.100"  # 手机IP
)

# 获取设备
device = client.get_device()

# 操作设备（直接发送到手机）
device.click(500, 800)
```

### 方式4：IP直连

```python
from fengchao import Client

client = Client(api_key="your-api-key")

# 直接连接设备IP
device = client.connect_direct("192.168.1.100")

# 操作设备
device.click(500, 800)
```

## 功能示例

### 触摸操作

```python
# 点击
device.click(500, 800)

# 双击
device.double_click(500, 800)

# 长按
device.long_press(500, 800, duration=2000)

# 滑动
device.swipe(500, 1500, 500, 500, duration=300)

# 快捷滑动
device.swipe_up()      # 上滑
device.swipe_down()    # 下滑
device.swipe_left()    # 左滑
device.swipe_right()   # 右滑
```

### 输入操作

```python
# 输入文字
device.input_text("Hello World")

# 清空输入框
device.clear_text()

# 按键
device.press_key("back")       # 返回
device.press_key("home")       # Home
device.press_key("menu")       # 菜单
device.press_key("volume_up")  # 音量+
```

### 元素操作（无障碍）

```python
# 查找元素
element = device.find_element(text="登录")
element = device.find_element(resource_id="com.xxx:id/btn")

# 等待元素出现
element = device.wait_element(text="成功", timeout=10)

# 判断元素是否存在
if device.element_exists(text="登录"):
    print("登录按钮存在")

# 直接点击元素
device.click_element(text="确定")

# 元素操作
element = device.find_element(text="登录")
element.click()          # 点击
element.long_click()     # 长按
element.input_text("xx") # 输入文字
print(element.text)      # 获取文字
print(element.bounds)    # 获取坐标
```

### 应用操作

```python
# 启动应用
device.start_app("com.tencent.mm")

# 停止应用
device.stop_app("com.tencent.mm")

# 获取当前应用
app = device.get_current_app()
print(app["package"])

# 安装/卸载应用
device.install_app("/path/to/app.apk")
device.uninstall_app("com.xxx")
```

### 屏幕操作

```python
# 截图
img = device.screenshot()
img.save("screen.png")

# 获取屏幕尺寸
size = device.get_screen_size()
print(f"屏幕: {size['width']}x{size['height']}")

# 唤醒/锁屏
device.wake_up()
device.lock_screen()
```

### 批量控制

```python
from fengchao import Client

client = Client(api_key="your-api-key")

# 获取所有在线设备
devices = client.get_online_devices()
print(f"在线设备: {len(devices)} 台")

# 批量执行
for device in devices:
    device.swipe_up()  # 所有设备上滑
```

## 指定控制方式

默认情况下，SDK会自动选择最优的控制方式。你也可以手动指定：

```python
# 自动选择（推荐）
device.click(500, 800)

# 指定使用HID（最防检测）
device.click(500, 800, method="hid")

# 指定使用无障碍
device.click(500, 800, method="accessibility")

# 指定使用ADB
device.click(500, 800, method="adb")
```

## 控制方式对比

| 方式 | 防检测 | 稳定性 | 元素查找 | 需要 |
|------|--------|--------|----------|------|
| HID/OTG | ⭐⭐⭐ | ⭐⭐ | ❌ | OTG设备 |
| 无障碍 | ⭐⭐ | ⭐⭐⭐ | ✅ | 无障碍授权 |
| ADB | ⭐ | ⭐⭐⭐ | ❌ | USB调试 |

## API参考

### Client

| 方法 | 说明 |
|------|------|
| `get_device(device_id)` | 通过ID获取设备 |
| `get_device(ip="x.x.x.x")` | 通过IP直连设备 |
| `get_online_devices()` | 获取所有在线设备 |
| `scan_lan()` | 扫描局域网发现设备 |
| `connect_direct(ip)` | 直连设备 |

### Device

| 方法 | 说明 |
|------|------|
| `click(x, y)` | 点击 |
| `double_click(x, y)` | 双击 |
| `long_press(x, y, duration)` | 长按 |
| `swipe(x1, y1, x2, y2)` | 滑动 |
| `input_text(text)` | 输入文字 |
| `press_key(key)` | 按键 |
| `find_element(...)` | 查找元素 |
| `wait_element(...)` | 等待元素 |
| `click_element(...)` | 点击元素 |
| `screenshot()` | 截图 |
| `start_app(package)` | 启动应用 |
| `stop_app(package)` | 停止应用 |

### Element

| 属性/方法 | 说明 |
|----------|------|
| `text` | 元素文字 |
| `resource_id` | 元素ID |
| `bounds` | 边界坐标 |
| `center` | 中心坐标 |
| `click()` | 点击 |
| `long_click()` | 长按 |
| `input_text(text)` | 输入文字 |
| `exists()` | 是否存在 |

## 中继服务器

### 架构说明

```
┌─────────────┐     HTTP      ┌─────────────────┐    WebSocket    ┌──────────┐
│  Python SDK │ ────────────→ │  中继服务器      │ ←───────────── │  手机APP │
│  (电脑)      │               │  (云服务器)      │                 │          │
└─────────────┘               └─────────────────┘                 └──────────┘
                                     ↑
                                     │ 也可以直连
                                     ↓
                              ┌─────────────┐
                              │  Python SDK │ (调试模式)
                              │  (同局域网)  │
                              └─────────────┘
```

### 部署中继服务器

```bash
# 进入中继服务器目录
cd relay-server

# Docker部署（推荐）
docker-compose up -d

# 或手动运行
pip install -r requirements.txt
python main.py
```

### 配置APP连接中继

在网页端打包APP时，填写中继服务器地址：
- 格式：`ws://your-server:9999` 或 `wss://your-server:9999`

### 使用SDK连接中继

```python
from fengchao import Client

# 连接中继服务器
client = Client(
    api_key="your-api-key",
    relay_server="http://your-server:9999"
)

# 获取已连接到中继的设备
devices = client.get_online_devices()
print(f"在线设备: {len(devices)} 台")

# 控制设备
for device in devices:
    device.click(500, 800)
```

## 完整示例

```python
# demo.py - 中继模式完整示例
from fengchao import Client
import time

# 1. 连接中继服务器
client = Client(
    api_key="sk-xxxxx",
    relay_server="http://your-server:9999"
)

# 2. 获取在线设备
devices = client.get_online_devices()
print(f"发现 {len(devices)} 台在线设备")

# 3. 批量操作
for device in devices:
    print(f"正在操作设备: {device.device_id}")
    
    # 唤醒屏幕
    device.wake_up()
    time.sleep(1)
    
    # 上滑解锁
    device.swipe_up()
    time.sleep(1)
    
    # 打开抖音
    device.start_app("com.ss.android.ugc.aweme")
    time.sleep(3)
    
    # 刷视频
    for i in range(5):
        device.swipe_up()
        time.sleep(3)
    
    print(f"设备 {device.device_id} 操作完成")

print("全部完成！")
```

## 许可证

MIT License
