内容
<div align="center">
# playwright-for-android
**从您的LLM驱动安卓模拟器。构建、安装、启动并测试一个功能端到端 — 获取统一的logcat和操作时间线。**
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](https://www.python.org/downloads/)
</div>
---
`playwright-for-android` 是一个模型上下文协议服务器，它将一个结构化的测试任务（例如“验证登录屏幕是否拒绝空密码”）转化为一个可审计的调试运行 — 构建APK，启动AVD，安装应用，通过adb驱动UI，捕获logcat，保存截图，生成判决。
每个UI操作都会作为一个输入的MCP工具调用，因此整个决策过程在LLM客户端的聊天记录中可见，并且可以从磁盘上的`trace.jsonl`和`logcat.log`中重现。
## 亮点
- **构建 → 启动 → 安装 → 驱动 → 判决，全部在一个会话中。** Gradle、AVD、安装、启动、logcat和Marvis UI树解析器都通过一个`start_debug_session`调用进行编排。
- **统一时间线。** 每个操作都会在实时logcat流中写入一个内联`<<< MARVIS_DEV ... >>>`标记，以便在`timeline.md`中，原因和效果可以彼此相邻。
- **默认可审计。** 每个捕获的帧、每个操作和每个UX观察结果都记录在`<project_root>/playwright-for-android/<timestamp>/`下。
## 安装
### 作为Claude Code插件（推荐）
```bash
# 在Claude Code中：
/plugin marketplace add /path/to/playwright-for-android
/plugin install playwright-for-android@FCLab.SKKU
```
捆绑的插件清单通过`${CLAUDE_PLUGIN_ROOT}/scripts/server.py`自动注册MCP服务器。
### 作为独立的MCP服务器
```bash
claude mcp add marvis-dev -- uv run --project /absolute/path/to/playwright-for-android python /absolute/path/to/playwright-for-android/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在`PATH`上（默认查找`~/Library/Android/sdk`）。
- 通过Android Studio的AVD管理器创建的AVD。
`uv`读取`pyproject.toml`并在首次启动时将`mcp` + `pillow`安装到隔离环境中 — 无需手动`pip install`步骤，无需全局Python污染。
### 一次性设置（可选）
```bash
python3 scripts/onboard.py
```
在`~/.config/playwright-for-android/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`，停止logcat，返回报告markdown |
| `abort_session` | 停止logcat而不编写判决报告 |
每个操作工具返回一个文本块（任务元数据、步骤计数器、UI元素列表）和一个图像块（原始截图）。坐标位于图像空间（设备分辨率的一半）；服务器在调用`adb input`之前缩放它们。
参见 [`SKILL.md`](./SKILL.md) 了解完整的代理接口：工作流、信息信任层次、坐标约定、UX观察标准和`report` markdown模板。
## 运行产物
每次`start_debug_session`调用都会在`<project_root>/playwright-for-android/<YYYY-MM-DDTHH-MM-SS>/`下写入一个目录（通过 `$PLAYWRIGHT_FOR_ANDROID_RUNS_DIR` 重写）：
```
playwright-for-android/2026-05-28T22-15-04/
├── logcat.log # 带内联 <<< MARVIS_DEV ... >>> 标记的注释logcat
├── trace.jsonl # 每个步骤一行，带有操作JSON
├── screenshots/
│ ├── step01_raw.jpg
│ └── ...
├── report.md # 提供给 finish_test的判决
├── timeline.md # 报告 + logcat在一个文件 — 运行后要读取的文件
└── build_error.log # 仅当Gradle失败时
```
将 `playwright-for-android/` 添加到项目的 `.gitignore` 中。
## 鸣谢
由 SungKyunKwan 大学的 [Team Marvis](https://marvis-ai.com/) 构建。
## 许可证
MIT — 参见 [LICENSE](./LICENSE)。
