mobile-use-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mobile-Use SDK Setup Wizard

Minitap移动使用SDK设置向导

Interactive guide for setting up the Minitap mobile-use SDK with support for iOS and Android devices, Platform and Local modes.

适用于iOS和Android设备、平台模式与本地模式的Minitap移动使用SDK交互式搭建指南。

When to Apply

适用场景

This skill activates when users want to:

Set up mobile automation for an app
Configure the Minitap mobile-use SDK
Connect physical iOS or Android devices
Set up cloud virtual devices
Create a new mobile testing project

当用户有以下需求时，将激活此技能：

为应用搭建移动自动化环境
配置Minitap移动使用SDK
连接iOS或Android物理设备
搭建云虚拟设备
创建新的移动测试项目

Setup Flow

设置流程

Phase 1: Gather Requirements

第一阶段：收集需求

Ask the user these questions using the AskUserQuestion tool:

Target Platform
- Question: "Which platform(s) do you want to automate?"
- Options: iOS only, Android only, Both iOS and Android
LLM Configuration Mode
- Question: "How do you want to configure AI/LLM?"
- Options:
  - Platform (Recommended) - Minitap handles LLM config, just need API key
  - Local - Full control with local config files and your own API keys
Device Type (if iOS selected)
- Question: "What iOS device setup do you need?"
- Options:
  - Physical device (iPhone/iPad via USB)
  - Simulator (Xcode iOS Simulator)
Device Type (if Android selected)
- Question: "What Android device setup do you need?"
- Options:
  - Physical device (via USB/WiFi ADB)
  - Cloud device (Minitap virtual Android)

使用AskUserQuestion工具向用户询问以下问题：

目标平台
- 问题：“您想要为哪个平台实现自动化？”
- 选项：仅iOS、仅Android、iOS和Android都要
LLM配置模式
- 问题：“您希望如何配置AI/LLM？”
- 选项：
  - 平台模式（推荐）- 由Minitap处理LLM配置，仅需提供API密钥
  - 本地模式 - 通过本地配置文件和自有API密钥实现完全控制
设备类型（若选择iOS）
- 问题：“您需要哪种iOS设备配置？”
- 选项：
  - 物理设备（通过USB连接的iPhone/iPad）
  - 模拟器（Xcode iOS模拟器）
设备类型（若选择Android）
- 问题：“您需要哪种Android设备配置？”
- 选项：
  - 物理设备（通过USB/WiFi ADB连接）
  - 云设备（Minitap虚拟Android设备）

Phase 2: Check Prerequisites

第二阶段：检查前置依赖

Run these checks based on user selections:

bash

undefined

根据用户选择执行以下检查：

bash

undefined

Always check

必查项

python3 --version # Requires 3.12+ which uv # Package manager

python3 --version # 要求3.12及以上 which uv # 包管理器

For iOS physical device

针对iOS物理设备

which idevice_id # libimobiledevice which appium # Appium appium driver list # XCUITest driver

which idevice_id # libimobiledevice which appium # Appium appium driver list # XCUITest驱动

For iOS simulator

针对iOS模拟器

which idb_companion # Facebook idb

For Android

针对Android

which adb # Android platform tools adb devices # Device connection

undefined

which adb # Android平台工具 adb devices # 设备连接情况

undefined

Phase 3: Install Missing Dependencies

第三阶段：安装缺失的依赖

iOS Physical Device Setup:

bash

undefined

iOS物理设备配置：

bash

undefined

Install libimobiledevice

安装libimobiledevice

brew install libimobiledevice

Install Appium + XCUITest

安装Appium + XCUITest

npm install -g appium appium driver install xcuitest


**iOS Simulator Setup:**
```bash
brew tap facebook/fb
brew install idb-companion

Android Setup:

bash

undefined

npm install -g appium appium driver install xcuitest


**iOS模拟器配置：**
```bash
brew tap facebook/fb
brew install idb-companion

Android配置：

bash

undefined

macOS

macOS系统

brew install --cask android-platform-tools

Linux

Linux系统

sudo apt install android-tools-adb


**UV Package Manager:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

sudo apt install android-tools-adb


**UV包管理器：**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

Phase 4: Create Project

第四阶段：创建项目

bash

undefined

bash

undefined

Create new project

创建新项目

uv init <project-name> cd <project-name>

Add SDK

添加SDK

uv add minitap-mobile-use python-dotenv

undefined

uv add minitap-mobile-use python-dotenv

undefined

Phase 5: Configure Credentials

第五阶段：配置凭据

For Platform Mode:

Direct user to https://platform.minitap.ai to create account
Navigate to API Keys → Create API Key
Create .env file:

MINITAP_API_KEY=<their-key>

Add .env to .gitignore

For Local Mode:

Copy the config template:

bash

cp llm-config.override.template.jsonc llm-config.override.jsonc

Edit
```
llm-config.override.jsonc
```
with preferred models (refer to
```
llm-config.defaults.jsonc
```
for recommended settings)
Add provider API keys to .env (OPENAI_API_KEY, etc.) or set MINITAP_API_KEY for optimized config

平台模式：

引导用户访问https://platform.minitap.ai创建账号
进入API密钥页面 → 创建API密钥
创建.env文件：

MINITAP_API_KEY=<their-key>

将.env添加到.gitignore中

本地模式：

复制配置模板：

bash

cp llm-config.override.template.jsonc llm-config.override.jsonc

编辑
```
llm-config.override.jsonc
```
，填入偏好的模型（可参考
```
llm-config.defaults.jsonc
```
中的推荐设置）
将服务商API密钥（如OPENAI_API_KEY等）添加到.env文件中，或设置MINITAP_API_KEY以使用优化配置

Phase 6: Device-Specific Setup

第六阶段：设备专属配置

iOS Physical Device (requires manual Xcode steps):

Inform user they need to:

Open WebDriverAgent in Xcode:

bash

open ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj

Sign these targets with their Apple ID:
- WebDriverAgentRunner
- WebDriverAgentLib
- IntegrationApp
Change Bundle IDs to unique values
Build IntegrationApp once with device connected
Trust developer certificate on device: Settings → General → VPN & Device Management

Android Physical Device:

Inform user they need to:

Enable Developer Options (tap Build Number 7 times)
Enable USB Debugging
Connect device and tap "Allow" on USB debugging prompt

iOS物理设备（需手动完成Xcode步骤）：

告知用户需要执行以下操作：

在Xcode中打开WebDriverAgent：

bash

open ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj

使用个人Apple ID为以下目标签名：
- WebDriverAgentRunner
- WebDriverAgentLib
- IntegrationApp
将Bundle ID修改为唯一值
连接设备后，构建一次IntegrationApp
在设备上信任开发者证书：设置 → 通用 → VPN与设备管理

Android物理设备：

告知用户需要执行以下操作：

启用开发者选项（连续点击版本号7次）
启用USB调试
连接设备并在设备上点击“允许”USB调试提示

Phase 7: Create Starter Script

第七阶段：创建启动脚本

Generate main.py based on configuration:

Platform Mode:

python

import asyncio
from dotenv import load_dotenv
from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.types import PlatformTaskRequest

load_dotenv()

async def main() -> None:
    agent = Agent()
    await agent.init()

    result = await agent.run_task(
        request=PlatformTaskRequest(task="your-task-name")
    )
    print(result)
    await agent.clean()

if __name__ == "__main__":
    asyncio.run(main())

Local Mode:

python

import asyncio
from dotenv import load_dotenv
from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.types import AgentProfile
from minitap.mobile_use.sdk.builders import Builders

load_dotenv()

async def main() -> None:
    profile = AgentProfile(name="default", from_file="llm-config.override.jsonc")
    config = Builders.AgentConfig.with_default_profile(profile).build()

    agent = Agent(config=config)
    await agent.init()

    result = await agent.run_task(
        goal="Your automation goal here",
        name="task-name"
    )
    print(result)
    await agent.clean()

if __name__ == "__main__":
    asyncio.run(main())

根据配置生成main.py：

平台模式：

python

import asyncio
from dotenv import load_dotenv
from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.types import PlatformTaskRequest

load_dotenv()

async def main() -> None:
    agent = Agent()
    await agent.init()

    result = await agent.run_task(
        request=PlatformTaskRequest(task="your-task-name")
    )
    print(result)
    await agent.clean()

if __name__ == "__main__":
    asyncio.run(main())

本地模式：

python

import asyncio
from dotenv import load_dotenv
from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.types import AgentProfile
from minitap.mobile_use.sdk.builders import Builders

load_dotenv()

async def main() -> None:
    profile = AgentProfile(name="default", from_file="llm-config.override.jsonc")
    config = Builders.AgentConfig.with_default_profile(profile).build()

    agent = Agent(config=config)
    await agent.init()

    result = await agent.run_task(
        goal="Your automation goal here",
        name="task-name"
    )
    print(result)
    await agent.clean()

if __name__ == "__main__":
    asyncio.run(main())

Phase 8: Verify Setup

第八阶段：验证配置

Run verification based on device type:

bash

undefined

根据设备类型执行验证：

bash

undefined

iOS physical

iOS物理设备

idevice_id -l

iOS simulator

iOS模拟器

xcrun simctl list devices

Android

Android设备

adb devices

Test SDK import

测试SDK导入

uv run python -c "from minitap.mobile_use.sdk import Agent; print('SDK OK')"

undefined

uv run python -c "from minitap.mobile_use.sdk import Agent; print('SDK OK')"

undefined

Quick Reference

快速参考

Setup Type	Key Dependencies	Verification
iOS Physical	Appium, XCUITest, libimobiledevice	`idevice_id -l`
iOS Simulator	idb-companion	`xcrun simctl list`
Android Physical	ADB	`adb devices`
Android Cloud	None (Platform only)	N/A

设置类型	关键依赖	验证方式
iOS物理设备	Appium、XCUITest、libimobiledevice	`idevice_id -l`
iOS模拟器	idb-companion	`xcrun simctl list`
Android物理设备	ADB	`adb devices`
Android云设备	无（仅平台模式支持）	不适用

Troubleshooting

故障排除

Issue	Solution
Python < 3.12	Install Python 3.12+ via pyenv or homebrew
UV not found	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
idevice_id not found	`brew install libimobiledevice`
ADB not found	`brew install --cask android-platform-tools`
WDA build fails	Check Xcode signing for all 3 targets
Device unauthorized	Enable USB debugging, tap Allow on device
CLT version error	`sudo xcode-select --install`

问题	解决方案
Python版本低于3.12	通过pyenv或Homebrew安装Python 3.12及以上版本
找不到UV	执行 `curl -LsSf https://astral.sh/uv/install.sh \| sh`
找不到idevice_id	执行 `brew install libimobiledevice`
找不到ADB	执行 `brew install --cask android-platform-tools`
WDA构建失败	检查Xcode中三个目标的签名设置
设备未授权	启用USB调试，并在设备上点击“允许”
CLT版本错误	执行 `sudo xcode-select --install`

Examples

示例

Example 1: New iOS automation project

User: "Help me set up mobile automation for my iOS app"
→ Ask: Platform preference (iOS), Mode (Platform), Device (Physical)
→ Check: python3, uv, libimobiledevice, appium
→ Install: Missing dependencies
→ Create: Project with uv init
→ Configure: .env with MINITAP_API_KEY
→ Guide: Xcode WebDriverAgent signing
→ Verify: idevice_id -l shows device

Example 2: Android cloud setup

User: "Set up mobile testing with cloud devices"
→ Ask: Platform (Android), Mode (Platform), Device (Cloud)
→ Check: python3, uv
→ Create: Project with uv init
→ Configure: .env with MINITAP_API_KEY
→ Guide: Create Virtual Mobile on platform.minitap.ai
→ Generate: main.py with for_cloud_mobile config

Example 3: Full local development setup

User: "I want full control over LLM config for mobile automation"
→ Ask: Platform (Both), Mode (Local), Devices (Physical)
→ Check: All dependencies
→ Create: Project, llm-config.override.jsonc
→ Configure: Provider API keys in .env
→ Guide: Device-specific setup for iOS and Android
→ Generate: main.py with local profile config

示例1：新iOS自动化项目

用户：“帮我为我的iOS应用搭建移动自动化环境”
→ 询问：平台偏好（iOS）、模式（平台模式）、设备类型（物理设备）
→ 检查：python3、uv、libimobiledevice、appium
→ 安装：缺失的依赖
→ 创建：通过uv init创建项目
→ 配置：创建包含MINITAP_API_KEY的.env文件
→ 引导：Xcode WebDriverAgent签名步骤
→ 验证：`idevice_id -l`显示设备

示例2：Android云设备配置

用户：“使用云设备搭建移动测试环境”
→ 询问：平台（Android）、模式（平台模式）、设备类型（云设备）
→ 检查：python3、uv
→ 创建：通过uv init创建项目
→ 配置：创建包含MINITAP_API_KEY的.env文件
→ 引导：在platform.minitap.ai上创建虚拟移动设备
→ 生成：适配云设备的main.py

示例3：完整本地开发配置

用户：“我想要完全控制移动自动化的LLM配置”
→ 询问：平台（两者都要）、模式（本地模式）、设备类型（物理设备）
→ 检查：所有依赖
→ 创建：项目与llm-config.override.jsonc文件
→ 配置：在.env中填入服务商API密钥
→ 引导：iOS和Android的设备专属配置步骤
→ 生成：包含本地配置文件的main.py