fengchao-sdk 1.0.0

蜂巢云控 Python SDK - 手机自动化控制

蜂巢云控 Python SDK

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

特性

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

三种连接模式

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

安装

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

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

方式2：从PyPI安装

pip install fengchao

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

方式3：下载源码安装

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

快速开始

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

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：中继模式（推荐生产环境）

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：调试模式（局域网直连）

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直连

from fengchao import Client

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

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

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

功能示例

触摸操作

# 点击
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()   # 右滑

输入操作

# 输入文字
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")  # 音量+

元素操作（无障碍）

# 查找元素
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)    # 获取坐标

应用操作

# 启动应用
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")

屏幕操作

# 截图
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()

批量控制

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会自动选择最优的控制方式。你也可以手动指定：

# 自动选择（推荐）
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 │ (调试模式)
                              │  (同局域网)  │
                              └─────────────┘

部署中继服务器

# 进入中继服务器目录
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连接中继

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)

完整示例

# 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