droidrun/mobile-harness：给 AI agent 的真机控制 Markdown harness（非 runtime）

droidrun/mobile-harness：给 AI agent 的真机控制 Markdown harness（非 runtime）

• ID: 6787d2e5
• 原文链接: https://github.com/droidrun/mobile-harness
• 作者: droidrun
• 日期: 2026-08-14
• 分类: agents
• 来源类型: github
• 标签: mobile-agent, android, ios, harness, mobilerun, adb
• 质量评分: 4/5
• 抓取时间: 2026-08-14T15:38:57Z
• Obsidian 证据: 调研/2026-08-14-调研-MobileHarness候选评估.md + DeepResearch/…/raw/droidrun-mobile-harness-README.md（README 全文归档）

中文导读

MIT 协议的 compact Markdown harness，README 明确「not an agent runtime」：主控制路径是 Python mobilerun_core，Android 走本地 ADB / Portal HTTP / 云，iOS 走 ios-portal HTTP / 云。可观测面有 ui nodes、screenshot、scroll_until 文本匹配、recovery GUIDE；execute_script 仅 cloud 后端可用。本地评估结论（repo_readme 级）：值得 hello 级联调进实验室，但不替代 adb/UIAutomator 的确定性回归，也不替代 logcat/Perfetto 证据层。

为什么值得关注

真机 agent 控制面分层的直接素材：探索层用 harness、回归层用脚本、证据层用 Perfetto——这是把「agent 开真机」从安利帖变成可执行选型的第一步。

正文存档

<p align="center"> <img src="assets/mobile-harness-logo.png" alt="Mobile Harness" width="900" /> </p>

Portable operating instructions for AI agents controlling Android and iOS devices—locally or in the cloud.

Mobile Harness is a compact Markdown harness, not an agent runtime. Its primary control path is Python's mobilerun_core, with optional client apps where needed.

Agent Setup Prompt

Copy paste it into your agent:

Set up https://github.com/droidrun/mobile-harness for me.

Read `install.md` and follow the steps to install `mobile-harness`.

Scope

• Android through mobilerun-core using local ADB with optional Portal, Portal HTTP-only, or cloud.
• iOS through mobilerun-core using ios-portal HTTP or cloud.

Manual Install

Install the full public control API:

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

Use Python 3.11, 3.12, or 3.13 to create the venv.

Tell agents which Python runtime to use:

Use /path/to/mobile-harness/.venv/bin/python for mobile-harness.

Base mobilerun-core includes cloud support through mobilerun-sdk. The local extra installs mobilerun-core-local, which mobilerun-core uses internally for local Android and iOS backends. Agents should still import only mobilerun_core.

Primary API

from mobilerun_core import Mobilerun

m = Mobilerun()
device = m.connect("<cloud-device-id>", backend="cloud")
device = m.connect("R5CT123456", backend="local-android-adb")
device = m.connect(backend="local-ios-http", url="http://127.0.0.1:6643")
device = m.connect(
    backend="local-android-http",
    url="http://127.0.0.1:18080",
    token="...",
)

device.ui()
device.screenshot()
device.start_app("com.android.settings")

After connecting, agents should inspect device.capabilities and use device.supports(...) before optional operations.

device.execute_script("<js>") runs JavaScript in the device's foreground Chrome tab and returns its JSON result. Cloud devices only; local backends raise UnsupportedOperation. Gate it with device.supports("execute_script"); the platform guides describe this key's network-probe behavior and its two server-side errors.

Common Device Helpers

Use these helpers through the device returned by Mobilerun.connect(...):

matches case-insensitive substrings across text, content description, resource id, and accessibility identifier. Nodes may carry offscreen: True (outside the viewport; scroll to reach it) and hidden: True (reported not visible; scrolling alone may not reveal it). A missing flag is not proof of visibility.

if the node has no usable bounds. Before any bounds check, it raises a distinct error for a node flagged hidden unless the node is also offscreen.

text, description, resource id, and accessibility identifier. It raises a distinct error when matches exist but none are tappable on-screen.

content-relative; verify=True returns whether the viewport actually moved.

scrolls until a match is on-screen, returning the node or None. It stops early with None when the viewport stops moving; do not re-call it blindly.

when the backend supports text input. device.clear_input() is available on local Android ADB and local iOS Portal HTTP.

include_system_apps=True when a full inventory is needed and supported.

• device.find_nodes(...) searches the accessibility tree. any_contains=
• device.tap_node(node) taps the center of an accessibility node and raises
• device.tap_text("label") taps the first on-screen, non-hidden match across
• device.scroll(direction, distance=0.5, ms=..., verify=False) scrolls
• device.scroll_until(text_contains=..., direction="down", max_swipes=10)
• device.type("text", clear=True) clears the focused field before typing
• device.list_apps() excludes system apps by default. Pass

Cloud Mode

Cloud devices use the same Mobilerun facade:

export MOBILERUN_CLOUD_API_KEY="..."
export MOBILERUN_API_BASE_URL="https://api.mobilerun.ai/v1"

from mobilerun_core import Mobilerun

m = Mobilerun()
device = m.connect("<cloud-device-id>", backend="cloud")
device.ui()
device.screenshot()
device.start_app("com.android.settings")

Loading Model

Skill-based runtimes can load SKILL.md; all runtimes should start with AGENTS.md. It routes agents to the smallest need

…（正文截断，全文见原文链接）

本地评估卡（摘自 Obsidian 调研笔记）

date: 2026-08-14 tags: [android-ai, llm-agent, mobile-agent, research] sources: [github, opencli-twitter, local-research] relevance: high slot: evening summary: droidrun/mobile-harness 作为真机 agent 控制面候选：MIT Markdown harness + mobilerun_core；进实验室 hello，不替代 adb/UIAutomator 回归与 Perfetto 证据层。

执行摘要

• 本次产出文件：/Users/chris/Library/Mobile Documents/iCloud~md~obsidian/Documents/Obsidian/调研/2026-08-14-调研-MobileHarness候选评估.md
• 材料包：[[DeepResearch/2026-08-14-evening-Agent限流状态机-MobileHarness-研究材料/master-research]]
• 关键发现：1）主候选是 droidrun/mobile-harness（MIT，316 star 快照），不是完整 runtime；2）同组织 mobilerun 约 9k star；3）MobAI-App/mobile-harness 是另一产品；4）本地 Android 主路径 ADB，未宣称必须 root
• 主要 takeaway：探索层用 agent 真机 harness，回归层仍用脚本，证据层仍用 logcat/Perfetto

Mobile Harness 候选评估

信号来源

8/13 @iluciddreaming 帖（约 85 likes）把「Mobile Harness」描述为真 iPhone/Android 上看屏、点击、滑动、输入，本地或云设备。证据层级是二级传播。本轮用 GitHub 搜索落到可核对仓库，再写评估卡。

候选识别

| 仓库 | Stars 快照 | 许可 | 判断 | |------|------------|------|------| | droidrun/mobile-harness | 316 | MIT | 主候选；README 明确是 agent 用 Markdown harness | | droidrun/mobilerun | 约 9056 | — | 同生态主 runtime，评估时一起看 | | MobAI-App/mobile-harness | 约 23 | MIT | 另一栈（MobAI DSL），勿合并叙事 |

10 行评估卡（droidrun/mobile-harness）

| 字段 | 内容 | |------|------| | 定位 | Portable operating instructions；compact Markdown harness，not an agent runtime | | 控制路径 | Python mobilerun_core；可选 client apps | | 平台 | Android：ADB / Portal HTTP / cloud；iOS：ios-portal HTTP / cloud | | 无控制通道时 | 无 ADB 且无 Portal HTTP → Blocked | | Root | README 主路径是 ADB；未宣称必须 root | | 与传统自动化 | 不替代 adb/UIAutomator/Appium 的确定性脚本回归 | | 可观测 | screenshot、ui nodes、device.supports(...)、recovery GUIDE | | 凭证 | cloud API key；本地 credentials/ ignored | | 风险 | 真机误操作、云数据出境、token、无人工门禁的 agent 手势 | | 实验室结论 | 值得 hello 级联调；不进发布门禁主路径 |

能力边界

适合：

• agent 探索未知 App 路径
• 点按、滑动、打字、开设置
• scroll_until 文本匹配
• 云设备批量试跑

不适合单独承担：

• 发布门禁的确定性回归
• 性能问题的主证据链（需要 Perfetto/logcat）
• 支付、通讯、账号注销等无人工确认动作
• 本地 backend 上的 execute_script（README：仅 cloud）

三层控制面（Android 工作流）

探索层  Mobile Harness / mobilerun     agent 驾驶，路径发现
回归层  adb + UIAutomator / Appium     可复现脚本
证据层  logcat / Perfetto / bugreport  性能与系统问题

稳定路径从探索层沉淀到回归层后，再谈是否让 agent 继续碰真机。

claim_level 升级

路由表 v2 真机 QA 行原为 brief_only。本轮升级为 repo_readme。仍不是 local_test：未本机安装、未接真机、未跑 hello。

最小验证（交互任务，非本 cron）

1. git clone + venv + pip install "mobilerun-core[local]" 2. 仅用 ADB 连一台可丢弃测试机 3. connect → screenshot → 打开 Settings → 返回 4. 记录：是否 root、Portal 是否必需、失败时 ui tree 是否够用 5. 通过后再评估是否写入实验室工具架；失败则保持候选注释

来源信号

• X Seeds: [[Hermes 定时任务/X-每日简报/2026-08-13-X-seeds_DeepSeekHarness-Ultrafast-ComputerHistory]]
• X 线索帖: https://x.com/i/status/2087837589906898983
• 材料包: [[DeepResearch/2026-08-14-evening-Agent限流状态机-MobileHarness-研究材料/master-research]]
• README 归档: [[DeepResearch/2026-08-14-eve

…（正文截断，全文见原文链接）