# ARTEMIS-Eapil

基于 [ARTEMIS](https://github.com/google/artemis) 扩展的 Android AI 自动化测试平台。用自然语言描述任务，即可通过简体中文网页或 MCP 驱动真机、模拟器执行操作并收集结果。模型统一使用 **OpenAI Responses API**。

## 主要功能

- **自然语言任务**：Flash 适合明确的操作流程，Pro 适合需要计划、分支探索和验证的任务。
- **可保存的模型配置**：支持自定义接口、模型、思考强度和超时重试，以及视频分析与录屏开关。
- **批量测试**：下载 Excel 模板、校验导入、顺序执行，支持暂停、继续和复制失败项。
- **报告与历史**：导出 Word、Excel 和批次 ZIP；历史按日期分组，支持搜索和筛选。
- **AI 接入**：随源码提供 MCP 与 Skill，让 AI 完成设备诊断、任务执行、历史分析和报告交付。

## 安装与启动

准备一台开启 USB 调试并完成授权的 Android 手机，或已启动的 Android 模拟器。首次安装需要联网，建议使用 Git 克隆以支持后续更新。

### Windows

在 PowerShell 中执行：

```powershell
git clone https://git.playones.com/chenmingxuan/Artemis-Eapil.git
cd Artemis-Eapil
.\start.bat
```

国内网络使用 `.\start-cn.bat`。启动脚本会检测并安装缺少的 uv、Python 和所需工具，创建或复用 `.venv`，同步依赖并构建网页。启动后访问 **http://127.0.0.1:8000**。

常用选项：

```powershell
.\start-cn.bat -SetupOnly   # 仅准备 Python 环境并检查已有 MCP 配置
.\start.bat -Port 8001      # 指定端口
.\start.bat -SkipUpdate     # 跳过 Git 源码更新检查
```

镜像与下载超时在 [config/downloads.json](config/downloads.json) 中设置。scrcpy 默认从 GitHub 下载，无法访问时可配置可信的 scrcpy_url 或预先安装。

### macOS / Linux

克隆仓库后在项目目录执行 `./start.sh`。国内镜像入口和启动时自动更新目前由 Windows 脚本提供。

## 配置与使用

1. 在首页“系统设置与运行准备”中选择设备，打开“模型配置”。
2. 填写支持 Responses 的接口地址、API Key 和模型名称，测试连接后保存。接口地址通常是以 `/v1` 结尾的 API 根地址。
3. 输入任务目标，选择 Flash 或 Pro 后执行；在工作区查看步骤、截图和结果。
4. 通过“报告与批量”导出报告或导入 Excel 用例；任务队列支持历史搜索。

预设模型为 `gpt-5.6-luna`、`mimo-v2.6-flash`，也可填写自定义名称。默认模型是 `mimo-v2.6-flash`，思考强度默认 `high`（最高可选 `max`），单次请求超时 **300 秒**，失败后最多重试 **5 次**，间隔 **10 秒**；视频分析与录屏默认关闭。模型及思考参数是否可用取决于所配置网关；不支持时会明确报错。

也可在项目 `.env` 中设置 `OPENAI_API_KEY`、`OPENAI_BASE_URL` 和 `OPENAI_MODEL`，其他参数见 [.env.example](.env.example)。直接编辑环境文件后需重启相应服务。不要提交自己的密钥。

报告会区分“执行完成”和“验证通过”；没有验证证据的结果标为“未验证”。任务步骤与截图可查看，设备动作回放不提供。

## 让 AI 使用

环境与模型配置完成后，例如为 Codex 接入 MCP：

```sh
uv run artemis mcp --install codex
```

在客户端重新加载 MCP，并按 [AI 接入指南](docs/ai-automation.md) 安装仓库中的 [artemis-automation Skill](skills/artemis-automation/SKILL.md)。Skill 不会随启动脚本自动安装到用户全局目录。其他客户端可通过 `uv run artemis mcp --help` 查看接入方式。

示例指令：

> 使用 artemis-automation，在我指定的模拟器上验证系统设置首页可以打开，不修改设置，完成后输出 Word 和 Excel 报告。

## 更新与排错

Windows 用户再次运行一键脚本时，会检查 Git 上游、项目依赖、前端构建和已有 MCP 配置，仅对源码做快进更新。本地修改、分支分叉或网络认证失败时保留本地版本；有任务执行或排队时停止更新启动。更新后需在 AI 客户端重新加载 MCP。

ZIP 安装可继续运行；需要自动拉取源码时，请改用 Git 克隆安装。遇到启动或设备问题，在项目目录运行 `uv run artemis doctor`。

更多说明：[批量任务与报告](docs/automation-workspace.md) · [AI 接入](docs/ai-automation.md) · [开发协作指南](AGENTS.md)

基于上游 ARTEMIS 开发，遵循 [Apache-2.0 许可证](LICENSE)。