Skip to content

README_CN.md

Latest commit

 

History

History
299 lines (231 loc) · 16.2 KB

README_CN.md

File metadata and controls

299 lines (231 loc) · 16.2 KB
Raw

ARTEMIS Banner

让 AI 助手与测试套件像人一样直接操作真机。

English • 中文文档 • 全流程演示 • 快速上手 • MCP 接入 IDE • 基准评测 • Discord 社区

Python 3.12+ License: Apache-2.0 MCP Native Multi-Model AndroidWorld SOTA

Artemis 演示效果
实机演示：在 Google Maps 中设置驾车路线并计算总耗时，随后打开 YouTube 播放 Coldplay 的歌曲。

核心亮点

  • 跨 App 复杂自动化与 AI 个人助理：不仅能执行严格的自动化测试用例，更具备接管真机的自主决策与长流程操作能力，一句话处理跨应用复杂业务与任务；
  • 零脚本维护自动化测试：基于“动态优先、坐标兜底”的多模态语义定位，彻底告别传统 XPath / 控件 ID 频繁失效的痛点，无惧 App 改版、分辨率差异与系统升级；
  • IDE 内一键 Bug 复现与 Logcat 诊断：原生支持 MCP 协议，可在 Antigravity、Claude Code、Windsurf 中直接用自然语言驱动真机复现缺陷，自动抓取关键帧截图与 Logcat 崩溃堆栈，完成研发测试闭环；
  • 极速执行吞吐（单步 3–5 秒）：首创全链路乐观异步流水线 (Optimistic Async Pipeline)，解耦重度推理与页面操作，在 Flash 模式下实现丝滑的高频交互与快速回归验证；
  • 干扰弹窗自愈与超长程巡检：独创 Safety Net 执行前校验机制，自动识别并清除系统权限弹窗、通知遮挡等异常；Pro 模式支持连续 10+ 小时 无人值守稳定性巡检与探索性测试 (Exploratory / Monkey-plus Testing)；
  • 业界顶尖 SOTA：在 Google Research AndroidWorld 基准评测（100+ 复杂长程系统与应用交互任务）中取得 99%+ 任务完成率。

Antigravity × ARTEMIS：全流程自主测试演示

通过原生 MCP 协议，Antigravity 与 ARTEMIS 深度协同——只需一句自然语言指令，即可自动完成从需求理解、测试规划、真机执行到深度报告输出的完整闭环：

1. 输入测试提示词 (Task Dispatch)
在 Antigravity 中用自然语言描述测试需求与目标指标

步骤一：输入测试提示词 		2. 生成测试方案 (Test Plan Generation)
自动拆解任务，生成详细测试步骤与架构图供确认

步骤二：生成测试方案
3. 自主执行测试 (Autonomous Test Execution)
驱动真机操作、界面导航并实时分析性能指标

步骤三：自主执行测试 		4. 交付最终报告 (Comprehensive Final Report)
生成结构化测试报告，交付性能图表、结论与原始数据

步骤四：交付最终报告

快速上手

确保电脑已连接 Android 实体机（已开启 USB 调试）或 Android 模拟器。一键启动脚本将会自动完成以下配置：

  • 安装系统环境依赖：自动检测并安装 ADB、scrcpy、FFmpeg 与 Python（uv）运行时及项目依赖。
  • 全局挂载 MCP 服务与测试准则 (Rules)：主动引导并自动将全局 MCP 服务与 Artemis 移动端测试思维准则 (rules.md) 挂载至你使用的 AI IDE（支持 Antigravity、Cursor、Claude Code、Codex、Windsurf、VS Code、Cline/Roo、OpenClaw）。

macOS 与 Linux

# 1. 克隆代码仓库并进入目录
git clone https://github.com/google/artemis.git && cd artemis

# 2. 一键启动
./start.sh

Windows PowerShell

# 1. 克隆代码仓库并进入目录
git clone https://github.com/google/artemis.git
cd artemis

# 2. 一键启动
.\start.bat

PowerShell 默认不会从当前目录查找可执行脚本，因此必须使用 .\start.bat，且命令末尾不要添加 \。如果使用传统命令提示符（CMD），则运行 start.bat。

提示：启动后将自动在默认浏览器中打开 Web 控制台（http://localhost:8000），提供设备连接向导、实时投屏、任务演练与状态回放面板。你也可以通过命令行直接运行：uv run artemis run "打开系统设置，找到电池选项并告诉我当前电量" --profile flash。

Codex / Antigravity / Claude Code / Windsurf MCP 配置（点击展开）

ARTEMIS 内置原生 Model Context Protocol (MCP) 服务。只需将以下配置加入你的 IDE 配置文件中，即可在编写代码时直接驱动真机：

1. 一键自动安装到 IDE（推荐）

运行 ./start.sh（macOS/Linux）或 .\start.bat（Windows PowerShell）启动脚本时，会主动询问是否自动挂载全局 MCP 与测试行为准则（支持跳过并在之后随时手动执行以下命令挂载）：

# 一键安装全局 MCP 服务与 Rules 到 Antigravity / Jetski：
uv run artemis mcp --install antigravity

# 或一键安装到所有支持的 AI IDE（包括 Codex）：
uv run artemis mcp --install all

提示：你也可以在首次运行 uv run artemis init 配置向导时，交互式完成 IDE 的 MCP 自动挂载。 进阶提示：如果希望在任意目录下都不需要加 uv run 就能全局直接使用 artemis 命令，可在项目根目录下执行一次 uv tool install -e .。

2. 手动配置（可选）

如果你习惯手动复制配置，可运行 uv run artemis mcp --generate-config <client>（例如 codex 或 antigravity）获取对应的 TOML 或 JSON 配置。请将 command 填写为项目下 .venv 虚拟环境中的 Python 绝对路径，并将 /path/to/artemis 替换为项目实际路径：

  • 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"
  • Antigravity (~/.gemini/jetski/mcp_config.json)：
{
  "mcpServers": {
    "artemis": {
      "command": "/path/to/artemis/.venv/bin/python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/artemis",
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "tools": {
        "mobile_run_task": { "eager": true },
        "mobile_manage_task": { "eager": true },
        "mobile_get_device_state": { "eager": true },
        "mobile_inspect_trace": { "eager": true }
      }
    }
  }
}
  • Claude Desktop (claude_desktop_config.json)：
{
  "mcpServers": {
    "artemis": {
      "command": "/path/to/artemis/.venv/bin/python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/artemis"
    }
  }
}

3. 挂载智能体行为规范 Rules（强烈推荐）

为使 AI 编程助手具备资深移动端测试工程师的严谨思维，避免凭空臆测 UI 交互，我们提供了专属的测试思维行为规范文件 mcp_server/rules.md（涵盖可运行代码原则与真机探索、Flash 与 Pro 任务路由策略、延迟与时间补偿机制以及**“动态优先、坐标兜底”定位模式**）。

你可以将 mcp_server/rules.md 挂载或复制到你的 AI IDE 规则配置中：

  • Antigravity：将 rules.md 内容添加至工作区规则（Workspace Rules）或全局规则设置中。
  • Claude Code：将 rules.md 内容复制或引入至项目根目录的 CLAUDE.md 文件中。
  • Cursor：将内容复制到 .cursorrules 文件或在 .cursor/rules/artemis.mdc 中创建新规则。
  • Codex：将内容添加至 ~/.codex/AGENTS.md（或当前生效的 AGENTS.override.md）。
  • Windsurf / OpenClaw：将内容添加到工作区规则或全局 System Prompt 中。

更多规范设计细节与 MCP 架构说明，请参阅 MCP Server 文档。

4. 在 IDE 中体验真机协同

在 Codex / Antigravity / Claude Code 对话框中直接输入：

"请帮我把刚刚修改的代码编译成 APK 并安装到手机上，打开登录页面输入测试账号，验证登录后是否有异常弹窗，并把最终页面截图回传。"

Python SDK 集成（点击展开）

只需几行代码，将移动端自动化智能体无缝嵌入你的 Python 脚本与 CI/CD 流水线中：

import asyncio
from artemis import ArtemisClient, ConcurrencyMode


async def main():
    # 1. 初始化测试客户端（支持指定设备序列号与并发策略）：
    # - concurrency_mode="per_device"（默认）：单设备排队，跨设备支持多任务并发执行
    # - concurrency_mode="global"：全局单一并发，整个集群跨所有设备同一时刻只执行一个任务
    client = ArtemisClient(
        device_serial="emulator-5554",  # 可选：指定目标设备序列号（不传则自动选择空闲设备）
        default_profile="flash",        # "flash" 极速校验 或 "pro" 深度推理自愈
        concurrency_mode="per_device",  # 或 ConcurrencyMode.GLOBAL
    )

    # 2. 执行端到端任务（也可在调用时动态覆盖指定设备与并发模式）
    result = await client.run(
        "打开系统设置，进入『电池』页面，验证是否正常显示电量百分比，确认页面无异常报错弹窗。",
        device_serial="emulator-5554",  # 可选：覆盖当前调用的目标设备
    )

    # 3. 结构化断言与执行追溯
    assert result.status == "SUCCESS", f"测试执行失败: {result.error}"
    print(f"✅ 测试通过！设备: {result.device_id} | 步数: {result.turns} | Trace ID: {result.trace_id}")


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

使用方式

Artemis 可视化控制台
控制台功能概览：① 视图切换（主页与工作区） · ② 运行模式与回放（Flash/Pro 状态与视频回放） · ③ 实时感知推理流（动作感知、目标坐标与结构化总结） · ④ 提示词输入坞 (Prompt Dock)（自然语言下发） · ⑤ 任务队列看板（生命周期与历史回溯）

  • Web 可视化测试控制台 (uv run artemis ui)：集成设备实时投屏与交互面板，支持通过自然语言下发测试用例，实时观测推理步骤、操作轨迹、截图留存与异常状态回放；支持在任意终端使用 uv run artemis restart、uv run artemis stop、uv run artemis status 一键重启、关停或查看服务状态；
  • 原生 MCP 协议 (IDE 协同)：作为标准 MCP 服务器无缝接入 Antigravity、Claude Code、Windsurf 等开发环境，在 IDE 中直接驱动真机完成自动化测试与 Bug 复现验证；
  • 开发者命令行 CLI (uv run artemis run)：支持通过终端直接执行自动化测试用例、探索性稳定性巡检或 AndroidWorld 基准评测，提供高保真结构化终端输出；
  • Python SDK：作为标准 Python 库无缝集成至现有自动化测试框架（如 pytest）或 CI/CD 流水线，提供基于 Pydantic 的强类型结构化结果与断言支持。

基准评测：AndroidWorld (SOTA 99%+)

在 Google Research 发布的业界基准评测 AndroidWorld（涵盖 20+ 款常用应用与 100+ 项复杂多步长程任务）中：Artemis 在全套长程任务评测中展现了高鲁棒性，取得了超过 99% 的任务完成率。

AndroidWorld 评测基准对比

ARTEMIS 是如何建构的

  • Pre-Touch 触控前像素守门与预测性连点：彻底杜绝大模型推理延迟造成的「静默误触」。动作下发前毫秒级拦截意外弹窗（0 Token、0 云端等待），Micro-ROI 局部校验目标稳定性；针对视频全屏等瞬态控件，结合历史先验毫秒级连击唤醒，在淡出窗口期内瞬时闭环；
  • 三层递进式目标定位引擎 (Progressive Grounding)：首层通过本地 OCR 与无障碍树几何融合（~150ms、0 Token），以无偏移数字索引承载 85%+ 常见交互；二层对 Flutter/Compose/Canvas 等自绘组件自动回退至空间视觉模型，三层辅以沙箱 CV 探针核验细微像素状态；
  • 弹性双执行引擎与运行时上下文动态压缩：兼顾 3–5 秒秒级响应的 CI 高吞吐回归（Flash 模式）与深度长程认知状态图探索（Pro 模式），后台异步生成视觉增量并剪除冗余 DOM，长程任务 Token 消耗锐降 70%+，支持 10+ 小时无人值守稳定性压测。

ARTEMIS 架构系统示意图

运行模式：Flash vs. Pro

ARTEMIS 提供两种运行模式以适应不同的自动化需求：

  • Flash 模式 (--profile flash)：轻量极速且省 Token 的响应式循环（单步约 3–5 秒），适合 25–30 步以内的常规确定性 UI 操作。局限性：不支持长时间状态监控、视频流分析以及复杂的多步自愈恢复。
  • Pro 模式 (--profile pro)：最强大的模型架构（单步约 15–40 秒），基于多智能体图编排，具备自主规划、视觉校验与闭环自愈能力，支持 100+ 步的长程复杂业务流、设备持续状态监控与多媒体视频分析。

路线图

  • Android Studio 深度集成：推出官方 IDE 插件与协同工作流，支持在 Android Studio 内直接进行自动化测试、设备交互与断点调试。
  • iOS 跨平台支持：将视觉感知与自动化执行引擎拓展至 iOS 真机与模拟器。
  • 端侧轻量化模型：支持离线运行的轻量级 Edge VLM，实现低延迟与隐私安全的本地自动化。
  • 实时语音双工交互：支持自然语音下发任务与实时打断（Barge-in）控制。

社区与贡献

欢迎通过以下方式参与项目建设：

  • Star 本项目以关注最新进展与更新
  • 加入 Discord 社区 参与技术探讨与功能建议
  • 提交 Issue 反馈 Bug，欢迎发起 Pull Request 贡献代码

开源许可证

本项目基于 Apache License 2.0 协议开源。