内容
<div align="center">
# 安卓应用调试
**通过LLM驱动安卓模拟器。构建、安装、启动并测试一个功能端到端 - 获取统一的日志记录和操作时间线。**
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](https://www.python.org/downloads/)
</div>
---
`android-app-debug-mcp` 是一个模型上下文协议服务器，它将一个结构化的测试任务（例如“验证登录屏幕是否拒绝空密码”）转化为一个可审计的调试运行 - 构建APK，启动AVD，安装应用，通过adb驱动UI，捕获日志记录，保存截图，生成判决。
每个UI操作都会作为一个键入的MCP工具调用，因此整个决策轨迹都可以在LLM客户端的聊天历史记录中可见，并且可以从磁盘上的`trace.jsonl`和`logcat.log`中重现。
## 亮点
- **构建 → 启动 → 启动 → 驱动 → 判决，全部在一个会话中。** Gradle、AVD、安装、启动、日志记录和Marvis UI树解析器都通过单个`start_debug_session`调用进行协调。
- **统一时间线。** 每个操作都在实时日志记录流中写入一个内联`<<< MARVIS_DEV ... >>>`标记，以便原因和效果在`timeline.md`中彼此相邻。
- **默认可审计。** 每个捕获的帧、每个操作和每个UX观察结果都记录在`<project_root>/android-app-debug/<timestamp>/`下。
## 安装
### 作为Claude Code插件（推荐）
```bash
# 在Claude Code中：
/plugin marketplace add /path/to/android-app-debug-mcp
/plugin install android-app-debug-mcp@FCLab.SKKU
```
捆绑的插件清单通过`${CLAUDE_PLUGIN_ROOT}/scripts/server.py`自动注册MCP服务器。
### 作为独立的MCP服务器
```bash
claude mcp add marvis-dev -- uv run --project /absolute/path/to/android-app-debug-mcp python /absolute/path/to/android-app-debug-mcp/scripts/server.py
```
或者将`.mcp.json.example`复制到项目根目录下的`.mcp.json`并编辑路径。
### 先决条件
- [`uv`](https://docs.astral.sh/uv/) 在`PATH`上 - 自动管理Python和依赖项（`brew install uv`或`curl -LsSf https://astral.sh/uv/install.sh | sh`）。
- 带有`adb`和`emulator`的Android SDK（默认查找`~/Library/Android/sdk`）。
- 通过Android Studio的AVD管理器创建的至少一个AVD。
`uv`读取`pyproject.toml`并在第一次启动时将`mcp` + `pillow`安装到隔离环境中 - 无需手动`pip install`步骤，无需全局Python污染。
### 一次性设置（可选）
```bash
python3 scripts/onboard.py
```
写入`~/.config/android-app-debug/config.json`，包含非机密默认值（SDK路径，默认AVD）。
## 工具参考
| 工具 | 用途 |
| --- | --- |
| `precheck` | JSON就绪报告 - AVD，设备，SDK路径 |
| `start_debug_session` | 构建，启动，安装，启动; 返回第一个观察结果 |
| `observe_screen` | 重新捕获当前屏幕而不触发输入 |
| `tap`，`long_press`，`type_text` | 触摸和键盘输入 |
| `scroll_dir`，`scroll_to_text_tool` | 滚动 |
| `press_home`，`press_back` | 硬件按键导航 |
| `wait` | 睡眠，然后重新观察 |
| `finish_test` | 编写`report.md` + `timeline.md`，停止日志记录，返回报告markdown |
| `abort_session` | 停止日志记录而不编写判决报告 |
每个操作工具都返回一个文本块（任务元数据，步骤计数器，UI元素列表）和两个图像块（原始截图，注释截图）。坐标位于图像空间（设备分辨率的一半）; 服务器在调用`adb input`之前缩放它们。
参见[`SKILL.md`](./SKILL.md)以获取完整的工作流，信息信任层次，坐标约定，UX观察标准和`report` markdown模板。
## 运行产物
每次`start_debug_session`调用都在`<project_root>/android-app-debug/<YYYY-MM-DDTHH-MM-SS>/`下写入一个目录（使用`$ANDROID_APP_DEBUG_RUNS_DIR`覆盖）：
```
android-app-debug/2026-05-28T22-15-04/
├── logcat.log # 带内联 <<< MARVIS_DEV ... >>> 标记的注释日志记录
├── trace.jsonl # 每个步骤一行，包含操作JSON
├── screenshots/
│ ├── step01_raw.jpg
│ ├── step01_annotated.jpg
│ └── ...
├── report.md # 提供给 finish_test的判决
├── timeline.md # 报告 + 日志记录在一个文件中 - 运行后要读取的文件
└── build_error.log # 仅当Gradle失败时
```
将`android-app-debug/`添加到项目的`.gitignore`中。
## 致谢
由 SungKyunKwan 大学的 [Team Marvis](https://marvis-ai.com/) 构建。
## 许可
MIT - 参见 [LICENSE](./LICENSE)。
