用 Google ARTEMIS 让编码 Agent 直接操作 Android 真机：安装、Flash/Pro 双模式与 MCP 接入实操

前置条件只有三样：Python 3.12 或更高版本、一台开启了 USB 调试的 Android 真机或模拟器，以及能联网的环境。ADB、scrcpy、FFmpeg 与 Python 侧的 uv 依赖都不用你提前装——一键启动脚本会检测系统并自动补齐。启动之后它会打开浏览器控制台 http://localhost:8000，里面是设备连接向导、实时投屏、提示词沙盒与执行回放面板。如果你就是想在命令行干活，完全可以不碰那套界面。Windows 用户在 PowerShell 里要注意：默认不从当前目录查找可执行脚本，所以要写成带前导点的形式；在 CMD 里则不带。

# macOS / Linux
git clone https://github.com/google/artemis.git && cd artemis
./start.sh

# Windows PowerShell（注意前导点）
git clone https://github.com/google/artemis.git
cd artemis
.\start.bat

# 想在任意目录直接用 artemis 命令（可选，项目根目录执行一次）
uv tool install -e .

还有两个值得提前知道的服务端组件。其一，开始在一台设备上跑任务时，它会往手机安装一个无障碍辅助服务 Artemis Accessibility Helper，用来在不占用 UiAutomation 连接的前提下读取屏幕布局；如果它中途失效，框架会自动回退到 UIAutomator2，并且会把这次回退写进任务时间线、任务状态与最终报告里，便于你事后判断这批结果的可靠性。辅助服务只在手机本地监听，不向外部发送数据。其二，可以用下面的命令预装，避开任务开始那几秒的安装等待。

# 预装 / 查看 / 卸载手机端辅助服务
uv run artemis helper install
uv run artemis helper status
uv run artemis helper uninstall

# 服务生命周期与体检
uv run artemis status
uv run artemis restart
uv run artemis stop
uv run artemis doctor

命令行的最小用法就是把想做的事用自然语言写进引号里。真正要理解的是两种执行模式的分野：Flash 是反应式的「观察—行动」循环，配合异步历史摘要，典型单步三到五秒，适合界面确定、路径清晰的常规任务；代价是它没有任务计划与笔记、没有执行前的安全检查网、没有检查点验证或最终报告，也拿不到 ADB shell。Pro 则是一张多智能体图，有 Planner、Operator、Explorer、Checker 这些角色，每个动作执行前会校验目标，遇到被拦下的动作会交回上层恢复，典型单步十五到四十秒，换来的是长链路任务（一百步以上）与探索性、稳定性测试的可靠度。

# Flash：快，适合确定性 UI 任务
uv run artemis run "打开系统设置，找到电池，告诉我当前电量" --profile flash

# Pro：稳，适合长链路与探索性测试
uv run artemis run "检查设置里是否有崩溃弹窗，给出截图" --profile pro

# 交互配置（补装 MCP 用，与 start.sh 的安装提示互补）
uv run artemis init

选型上有一条很实用的经验：确定性回归、单条明确路径用 Flash；探索性测试、需要最终报告或一致性校验的场景才上 Pro。官方还给出了 Pro 侧的校验强度选项，可以在「关闭、仅最终、按检查点、严格」之间选，倾向自动驾驶的创作之外，把 verification-level 调高通常能换来更少的返工。另一处细节：Pro 模式里 Explorer 的定位精度档位是跟着 profile 由人来设定的，不会让 Agent 自己随意升级——这是刻意留给你控制的成本闸。

这一步才是整个方案的价值拐点。ARTEMIS 自带一个原生 MCP Server（入口是仓库里的 mcp_server 模块），官方支持的一键安装目标包括 Antigravity、Cursor、Claude Code、Codex、Windsurf、VS Code、Cline/Roo、OpenClaw。安装的同时还会挂载一份「移动端测试思维准则」的规则文件，里面写的是官方踩出来的几条硬经验：先主动探索再动手写代码、Flash 与 Pro 的路由策略、延迟与时序补偿，以及「动态元素优先、坐标兜底」的定位器写法。规则文件只装一处即可，重复挂载只会白白占用上下文。

# 装到所有支持的 IDE（含 Codex）
uv run artemis mcp --install all

# 只装某一个
uv run artemis mcp --install antigravity     # Antigravity / Jetski
uv run artemis mcp --install claude          # Claude Code

# 规则文件的落点（不同客户端不同）
# Claude Code  : ~/.claude/rules/artemis.md
# Codex        : ~/.codex/AGENTS.md（或生效的 AGENTS.override.md）
# Cursor       : .cursorrules 或 .cursor/rules/artemis.mdc
# Windsurf / OpenClaw : workspace rules 或全局 system prompt

如果你的客户端不在自动覆盖范围内，或者你想把配置写进版本库统一管理，可以让它生成配置片段再手工粘贴。注意两点：路径要换成你本地仓库的真实路径，command 要指向虚拟环境里的 Python 可执行文件（Windows 上通常在 .venv/Scripts 而不是 .venv/bin）。Windows 用户在这里容易卡住，所以下面两种都列出来。

# 先生成片段
uv run artemis mcp --generate-config codex
uv run artemis mcp --generate-config antigravity

# Codex  ~/.codex/config.toml
[mcp_servers.artemis]
command = "/path/to/artemis/.venv/bin/python"
args = ["-m", "mcp_server"]
cwd = "/path/to/artemis"

[mcp_servers.artemis.env]
PYTHONUNBUFFERED = "1"
PYTHONPATH = "/path/to/artemis"

# Claude Desktop  claude_desktop_config.json
{
  "mcpServers": {
    "artemis": {
      "command": "/path/to/artemis/.venv/bin/python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/artemis"
    }
  }
}

接上 MCP 之后，编码 Agent 就多了一双手。官方演示的这句指令很能说明意图：把最新改动打成 APK、装到已连接的设备、用测试账号打开登录页、检查登录后有没有非预期弹窗、把最终页面的截图带回来。对日常开发来说，「改完就验收」这件事终于不用人肉盯了。但心里要有笔账：这条链路上的每一步都在调用多模态模型理解屏幕，步数与耗时、花费都成正比，它省的是你的时间，不是 token。

# 给编码 Agent 的自然语言指令（走 MCP 工具调用）
用 artemis 把刚才的改动构建成 APK，装到已连接的设备上，
用测试账号打开登录页，检查登录后有没有非预期弹窗，
把最终页面截图和 Logcat 片段带回来。

# 只想拉一次当前屏幕状态
看看当前屏幕上是什么界面？把可见元素列出来。

# 想排查某次失败
回放刚才那个任务的 trace，指出卡在第几步。

除了 MCP 与命令行，它还提供了一个 Python SDK：安装的是一个零运行时依赖的客户端（ADB、模型、图像处理这些重活仍然留在连接设备的那台宿主上，不会在你的开发机上重复安装一份），跑完之后返回强类型的结构化结果，可以直接断言。这样你就把它塞进了现有测试体系——pytest 里写用例，CI 里跑夜构建巡检，失败拿 trace_id 回去回放。下面是官方给出的异步用法。

# 安装客户端（注意 subdirectory 指向 packages/artemis-client）
uv add "artemis-client @ git+https://github.com/google/artemis.git#subdirectory=packages/artemis-client"

import asyncio
from artemis_client import ArtemisClient

async def main():
    client = ArtemisClient(
        "http://artemis-host:8000",
        device_serial="emulator-5554",   # 可选：指定目标设备
        default_profile="flash",         # "flash"（快速反应）或 "pro"（深度推理）
    )
    result = await client.run(
        "打开系统设置，进入电池，确认显示了电量百分比，并检查有没有崩溃弹窗。"
    )
    assert result.succeeded, f"测试失败: {result.error or result.status}"
    print(f"通过 | 设备: {result.device_serial} | Trace ID: {result.trace_id}")

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

放进 pytest 时有两种写法：装了 pytest-asyncio 就直接用异步测试函数；没有的话，在普通同步用例里用 asyncio.run 包一层同样成立。无论哪种，断言都落在 succeeded 上，失败信息从 error 或 status 里取，排查靠 trace_id。真实工程里建议把设备序列号与 profile 做成环境变量，同一份用例可以在本地模拟器与 CI 的真机池之间切换。

要给它定预算与预期，先看清三条账。其一是时间与钱：Flash 单步三到五秒、Pro 单步十五到四十秒，流程越长成本线性上升，长流程不要指望很快产出；进阶手段是把长任务拆短、让长链路在后台跑完再取结果，而不是让它一口气跑两百步。其二是平台范围：当前只有 Android，iOS 支持还在路线图上，跨平台团队别误以为能一套覆盖。其三是界面类型：标准控件能拿到元素索引，命中率最高；而 Canvas、Compose、Flutter 这类自绘界面拿不到索引，只能回退到坐标与视觉定位，稳定性会明显依赖多模态模型与 OCR 的水平。

# 你的三项日常运维动作
uv run artemis status       # 服务是否在跑
uv run artemis doctor       # 环境 / 辅助服务诊断
uv run artemis helper install   # 预装辅助服务，省掉任务开头的等待

# 强制改用 UIAutomator2（在 .env 里）
ARTEMIS_HIERARCHY_BACKEND=uiautomator
ARTEMIS_HELPER_AUTO_INSTALL=false      # 禁止自动安装辅助服务