龙虾安卓助手 / Lobster Android Assistant
一个强大的 Android 设备控制技能，通过 ADB 和 scrcpy 集成实现全面的设备控制能力。
A powerful Android device control skill with comprehensive capabilities through ADB and scrcpy integration.
功能特性 / Features
🎯 触摸控制 / Touch Control
- 点击、双击、长按 / Tap, double-tap, long press
- 滑动、手势操作 / Swipe, gestures
- 多点触控、缩放手势 / Multi-touch, pinch-to-zoom
⌨️ 键盘输入 / Keyboard Input
- 文本输入（支持中文） / Text input (Chinese supported)
- 按键事件、组合键 / Key events, key combinations
- 特殊按键（Home、Back、音量等）/ Special keys (Home, Back, Volume, etc.)
📱 系统控制 / System Control
- 电源管理 / Power management
- 应用启动与切换 / App launch and switching
- 截图、录屏 / Screenshot, screen recording
- 剪贴板操作 / Clipboard operations
🤖 AI 辅助自动化 / AI-Assisted Automation
- 屏幕分析与 UI 元素识别 / Screen analysis and UI element detection
- 智能决策与操作建议 / Intelligent decision-making
- 自然语言指令执行 / Natural language command execution
📹 Scrcpy 集成 / Scrcpy Integration
- 实时屏幕镜像 / Real-time screen mirroring
- 低延迟控制 / Low-latency control
- 完整控制消息支持 / Full control message support
🔄 脚本录制回放 / Script Recording & Playback
- 操作录制 / Action recording
- 脚本保存与加载 / Script save and load
- 变速回放 / Variable speed playback
快速开始 / Quick Start
基础使用 / Basic Usage
from scripts.adb_controller import ADBController
# 初始化控制器 / Initialize controller
controller = ADBController()
# 触摸操作 / Touch operations
controller.tap(500, 800) # 点击 / Tap
controller.swipe(100, 500, 500, 500) # 滑动 / Swipe
controller.long_press(500, 800, 1000) # 长按 / Long press
# 键盘操作 / Keyboard operations
controller.press_home() # 返回主页 / Go home
controller.press_back() # 返回键 / Back
controller.input_text("Hello") # 输入文本 / Input text
# 系统操作 / System operations
controller.screenshot("screen.png") # 截图 / Screenshot
controller.start_app("com.android.settings") # 启动应用 / Launch app
AI 自动化 / AI Automation
from scripts.adb_controller import ADBController
from scripts.ai_controller import ScreenAnalyzer, AIDecisionEngine
controller = ADBController()
analyzer = ScreenAnalyzer()
engine = AIDecisionEngine(controller, analyzer)
# 执行自动化任务 / Execute automation
engine.run_automation("打开设置并启用深色模式")
# Open settings and enable dark mode
脚本录制 / Script Recording
from scripts.adb_controller import ADBController, ActionRecorder
controller = ADBController()
recorder = ActionRecorder(controller)
# 开始录制 / Start recording
recorder.start_recording()
recorder.record_action('tap', {'x': 500, 'y': 800})
recorder.stop_recording()
# 保存并回放 / Save and playback
recorder.save_to_file("script.json")
actions = recorder.load_from_file("script.json")
recorder.playback(actions, speed=2.0)
环境要求 / Requirements
- Python 3.7+
- Android SDK (adb 命令可用 / adb command available)
- 已开启 USB 调试的 Android 设备 / Android device with USB debugging enabled
安装说明 / Installation
- 确保已安装 ADB 并添加到系统 PATH Ensure ADB is installed and added to system PATH
adb version
- 连接 Android 设备并授权 USB 调试 Connect Android device and authorize USB debugging
adb devices
- 加载技能即可使用 Load the skill and start using
API 参考 / API Reference
ADBController
主要设备控制器 / Primary device controller.
| 方法 Method | 描述 Description |
|---|---|
tap(x, y, duration_ms) | 点击坐标 / Tap at coordinates |
swipe(x1, y1, x2, y2, duration_ms) | 滑动手势 / Swipe gesture |
long_press(x, y, duration_ms) | 长按操作 / Long press |
input_text(text) | 输入文本 / Input text |
keyevent(keycode) | 发送按键事件 / Send key event |
press_home() | 返回主页 / Press HOME |
press_back() | 返回键 / Press BACK |
screenshot(path) | 截图 / Take screenshot |
start_app(package) | 启动应用 / Launch app |
ScrcpyController
高级控制器（需 scrcpy 服务）/ Advanced controller (requires scrcpy server).
| 方法 Method | 描述 Description |
|---|---|
start_server() | 启动 scrcpy 服务 / Start scrcpy server |
connect() | 连接到设备 / Connect to device |
scroll(x, y, h, v) | 滚动操作 / Scroll operation |
rotate_device() | 旋转屏幕 / Rotate screen |
multi_touch(points) | 多点触控 / Multi-touch |
AIDecisionEngine
AI 决策引擎 / AI decision engine.
| 方法 Method | 描述 Description |
|---|---|
analyze_and_suggest(goal) | 分析并建议操作 / Analyze and suggest |
execute_suggestion(suggestion) | 执行建议 / Execute suggestion |
run_automation(goal) | 执行自动化任务 / Run automation |
使用场景 / Use Cases
自动化测试 / Automated Testing
# 运行测试序列 / Run test sequence
controller.start_app("com.example.app")
controller.tap(500, 800)
controller.input_text("test input")
controller.press_back()
远程控制 / Remote Control
# 镜像用户指令 / Mirror user commands
def handle_command(cmd):
if cmd.type == 'tap':
controller.tap(cmd.x, cmd.y)
elif cmd.type == 'type':
controller.input_text(cmd.text)
AI 辅助操作 / AI-Assisted Operations
# 让 AI 自动完成任务 / Let AI complete tasks
engine.run_automation("打开微信发送消息给张三")
# Open WeChat and send message to Zhang San
故障排除 / Troubleshooting
设备未找到 / Device Not Found
adb devices
adb kill-server && adb start-server
权限被拒绝 / Permission Denied
在设备上启用 USB 调试：设置 > 开发者选项 > USB 调试 Enable USB debugging on device: Settings > Developer Options > USB Debugging
中文输入问题 / Chinese Input Issues
建议安装 ADBKeyboard 以支持中文输入： Install ADBKeyboard for Chinese input support:
adb install ADBKeyboard.apk
adb shell ime set com.android.adbkeyboard/.AdbIME
技术架构 / Technical Architecture
┌─────────────────────────────────────────────────────────────┐
│ 龙虾安卓助手 │
│ Lobster Android Assistant │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ ADB 控制器 │ │ Scrcpy 控制器│ │ AI 决策引擎 │ │
│ │ADB Controller│ │Scrcpy Ctrl │ │AI Decision Engine │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
│ │ │ │ │
│ └────────────────┼─────────────────────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ Android 设备│ │
│ │Android Device│ │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
版本信息 / Version Info
- 版本 Version: 1.0.0
- 作者 Author: Lobster Team
- 许可证 License: MIT
更新日志 / Changelog
v1.0.0
- 初始版本发布 / Initial release
- ADB 完整控制支持 / Full ADB control support
- Scrcpy 集成 / Scrcpy integration
- AI 自动化功能 / AI automation features
- 脚本录制回放 / Script recording & playback