mobile-agent-harness

mobile-agent-harness

面向 AI Agent 的 Android 设备自动化工具。 MCP 服务、命令行工具，以及运行在自愈 uiautomator2 桥接层之上的热重载插件运行时。无需在设备端安装应用。

中文文档：README.zh-CN.md

这里只包含基础运行时。插件收录在社区目录中：awesome-mobile-agent-harness-plugin。供 AI 使用的应用业务知识位于 app-lore，此仓库的 knowledge/ 加载器会直接读取该知识。

安装

git clone https://github.com/Aelindra/mobile-agent-harness
cd mobile-agent-harness
pip install -e .          # add ".[ocr]" for vision.ocr / ui2.*

需要 Python 3.9+，并确保 adb 位于 PATH 中且已启用 USB 调试。

快速开始

1. 将桥接层指向你的设备：

export AGENT_SERIAL_DEFAULT=192.168.1.23:5555   # or "emulator-5555"

2. 列出工具列表（无需设备即可运行），并运行离线测试：

python -m core.cli tools
python tests/test_runtime.py

3. 调用工具：

python -m core.cli call ui.snapshot
python -m core.cli call ui.click --args '{"selector":"text@^Network & internet$","pkg":"com.android.settings"}'

4. 接入任意 MCP 客户端：

{
  "mcpServers": {
    "phone": {
      "command": "python",
      "args": ["-m", "core.cli", "mcp"],
      "cwd": "/path/to/mobile-agent-harness",
      "env": { "AGENT_SERIAL_DEFAULT": "192.168.1.23:5555" }
    }
  }
}

所有工具都会返回 {"ok": bool, "error"?, ...} 格式的结果。ok=false 表示业务结果（例如 error_type=selector_not_found）——应据此调整，而不是重试。

工具

分组	工具
观察	ui.snapshot ui.dump ui.find ui2.state ui2.screen_evidence ui2.timeline ui2.find_templates vision.screenshot vision.ocr vision.diff
操作	ui.click ui.click_handle ui.text_handle ui.hold_read ui.set_text ui.scroll ui.back ui.home input.tap input.swipe input.key
应用	app.launch app.current app.probe app.list app.stop app.wait_idle
Shell 和数据	shell.run state.prefs state.db file.push file.pull net.http
事件	events.tail events.wait events.capture events.record_start events.record_stop
知识和任务	knowledge.list knowledge.guide ui2.check_states ui2.orient task.begin task.note task.end template.add sys.capabilities

ui.snapshot 会返回精简的无障碍树列表，其中包含元素句柄（e0、e1 等）；ui.click_handle 会在检测到界面变化的情况下操作指定句柄。ui2.state 会将无障碍树与 OCR 结果融合，用于处理通过画布绘制界面的 UI。ui2.screen_evidence 会收集可测量的屏幕特征（遮罩层级、动态、颜色、布局密度），但不会对其进行解释。app.probe 会返回确定性的辅助信息（包名、版本、屏幕方向）；ui2.timeline 会按时间顺序采集 N 帧轻量级证据；ui2.orient 会探查上下文，将请求路由至匹配的知识包，并评估其中的状态判别条件——返回匹配的状态，或按排名排列的假设，并列出缺失的证据。

选择器

选择器会根据实时无障碍树进行解析。不会使用坐标。

# ui.click selector examples
"id@d98 && [email protected]"       # resource-id, short form completed with pkg@
"text@^Settings$ && [email protected]"
"[email protected] && [clickable=true]"
"desc@^Search$"                        # content-desc regex

自动化框架和插件

自动化框架文件以选择器步骤和前置／后置条件声明各应用的流程；distill 会通过探索应用来起草流程，lint 会检查选择器质量，而后置条件检查失败会将工具标记为过时，以便重新提炼。内置示例请参见 harnesses/com.android.settings/harness.json5。

插件放入 plugins/ 后，会在加载时注册工具或能力提供程序；注册可以撤销，并会在文件变更时热重载。有关知识包格式，请参见 README.zh-CN.md 中的插件开发指南和 knowledge/README.md。

对于大模型先验知识不可靠的应用业务场景，可引导 Agent 使用 app-lore——这是一个以开放的 Agent Skills 格式编写应用结构调查报告的社区目录，复杂应用会按功能模块拆分报告。移动场景尤其具有私有领域属性，在训练数据中的占比也较低，因此 Agent 在操作不熟悉的应用前，加载相关调查报告会更有帮助。本地 knowledge/ 目录仍是此仓库的运行时层，包含知识包、图标模板和状态判别条件。

配置

变量	描述	示例
AGENT_SERIAL_DEFAULT	未提供 --serial/ANDROID_SERIAL 时使用的设备序列号	192.168.1.23:5555
AGENT_SERIAL_USB	USB 序列号备用值	0123456789abcdef
MAH_FRAME_STREAM	设为 1 可为观察工具启用 H.264 帧流	1
MAH_VISION_MODE	视觉增强：off / client / endpoint	client
MAH_VLM_URL / MAH_VLM_MODEL	外部视觉端点（兼容 OpenAI）	http://127.0.0.1:11434/v1/chat/completions

对比

• 与 mobile-mcp / agent-device 相比：它们是通用设备工具集；本项目在传输层之上增加了一个层：以文件形式提供的各应用知识（harness）、可热重载且具备能力接缝的插件运行时，以及明确的 adb/root 权限模型。
• 与 droidrun 相比：droidrun 需要在设备端安装无障碍应用；本项目通过 adb 即可使用，无需安装。
• Root 支持采用声明式方式：如果设备已有 su，则 shell 接缝会增加一个受命令允许列表约束的 root 提供程序。本项目不提供 root。

已知限制

消息、银行和电商应用会主动实施反自动化风险控制；adb 层在这些应用上不可靠。目标用途是开发、测试和你自己的设备工作流。

贡献

插件提交至 awesome-mobile-agent-harness-plugin；应用业务知识提交至 app-lore——请参阅它们的贡献指南。

许可证

MIT。