droidrun/mobile-harness

Mobile Harness – 面向 Android 和 iOS 上 AI 代理的可移植控制指令

它是什么 – 一个轻量级、由 Markdown 驱动的工具，让基于语言模型的 AI 代理能够与真实的 Android 或 iOS 设备通信。它不是代理运行时；它提供了代理调用的 Python API（mobilerun_core），以执行 UI 操作、截图、启动应用等。该工具支持本地设备（通过 ADB 或 Portal HTTP 服务器）以及通过 Mobilerun 云服务托管的云设备。

主要功能

• 通过一次调用连接设备：

  from mobilerun_core import Mobilerun
  m = Mobilerun()
  dev = m.connect("<id>", backend="cloud")
  

• 适用于 Android 和 iOS 的统一 API：ui()、screenshot()、start_app()、tap_node()、type()、scroll() 等。
• 在可访问性树上工作的辅助方法（find_nodes、tap_text、scroll_until）。
• 自动能力检测（device.capabilities、device.supports(...)）。
• 可选的云后端（需要 MOBILERUN_CLOUD_API_KEY）。
• 本地后端：
  • 通过 ADB 的 Android（可选 Portal HTTP 以获取更丰富的功能）。
  • 仅 Android Portal HTTP。
  • 通过开源 ios-portal HTTP 服务器的 iOS。
• 代理创建的所有状态（内存、凭据、自定义应用卡片）都位于 git 忽略的 local/ 文件夹下，将用户数据与仓库分开。

基准测试 – 使用标准编码代理和 GPT-6 风格模型，在公开的 AndroidWorld（116 个任务）和 iOSWorld（133 个任务）套件上进行了评估。结果：Android 平均得分 100%，iOS 平均得分 98.24%，二进制通过率分别为 100% 和 93.23%。详细的任务回放和方法论链接在 README 中。

安装

1. 克隆仓库。
2. 创建 Python 虚拟环境（Python 3.11-3.13）并安装核心库：

   python -m venv .venv
   .venv/bin/pip install "mobilerun-core[local]"
   .venv/bin/python -c "from mobilerun_core import Mobilerun"
   

3. 按照 install.md 进行平台特定设置（ADB、Portal 服务器、云 API 密钥等）。

AI 代理如何使用它 – README 提供了一个即用即粘贴的 Agent Setup Prompt，告诉代理克隆仓库并运行安装步骤。环境准备好后，代理可以直接从其生成的代码中导入 Mobilerun、连接设备、查询能力并调用 UI 操作。

分发 – 该工具可以通过 skills.sh CLI（npx skills add droidrun/mobile-harness）作为技能添加到代理中，或作为 Claude Code 插件（/plugin marketplace add droidrun/mobile-harness）。两种方法都安装相同的 Python 包，并将 local/ 数据目录放在适当的运行时位置。

适用对象 – 构建 LLM 驱动的移动自动化代理的研究人员和开发人员，尤其是那些需要一致、对语言模型友好的 API 来同时支持 Android 和 iOS（无论设备在本地还是云端运行）的人。