---
name: GUI Agent 项目状态
description: 手机GUI Agent项目当前进度、技术决策和待确认事项
type: project
---

## 项目状态：端到端已跑通 + 手机端 OCR 已部署

### 设备信息
- **华为 P40 Pro**（ELS-AN00）
- 序列号：UQG5T20416000119
- 分辨率：1200x2640
- 系统：HarmonyOS 4.x（兼容安卓层，ADB 可用）
- ADB 路径：`/opt/homebrew/bin/adb`
- 连接注意：华为手机需在开发者选项中额外打开"仅充电模式下允许ADB调试"
- **已开启「通过USB安装应用」权限**（2026-03-29）

### 已完成
- 七层管线骨架代码（L1-L7）全部就位
- Web 控制台（FastAPI + 暗色主题 UI）已验证可运行
- 端口 4380，VLM 默认走 Poe API
- 支持 8 种动作类型（tap/swipe/type/long_press/back/home/scroll/wait）
- Agent 主循环含历史记忆（最近 5 步）和连续错误自动停止
- **ADB 截屏已验证通过**（2026-03-29）
- **Mac 端 OCR 元素定位已验证**（2026-03-29）— easyocr 中文识别，返回像素坐标
- **中文文本输入已验证**（2026-03-29）— uiautomator2 send_keys
- **端到端发微信消息已跑通 3 次**（2026-03-29）— "你是大聪明"、"祝你生日快乐"、"生日快乐"
- **手机端 OCR Service APK 已部署**（2026-03-29）— ML Kit Chinese bundled，端口 18900

### 手机端 OCR Service（android-ocr-service/）
- **引擎**：Google ML Kit text-recognition-chinese（bundled 版，不依赖 GMS，华为可用）
- **架构**：Kotlin APK = OcrEngine + NanoHTTPD(18900) + ForegroundService
- **接口**：
  - `GET /health` — 健康检查
  - `GET /ocr?path=/data/local/tmp/s.png` — 读文件 OCR
  - `GET /ocr?path=...&text=微信` — 按文本过滤
  - `POST /snap` — POST 图片字节直接 OCR（NanoHTTPD 二进制处理有 bug，待修）
- **使用流程**：
  ```bash
  adb shell am start -n com.guiagent.ocr/.MainActivity
  adb forward tcp:18900 tcp:18900
  adb shell "screencap -p /data/local/tmp/s.png"
  curl http://localhost:18900/ocr?path=/data/local/tmp/s.png
  ```
- **性能**：首次 ~2.4s（模型加载），后续 ~1.8s/次
- **构建**：`ANDROID_HOME=/opt/homebrew/share/android-commandlinetools JAVA_HOME=/opt/homebrew/Cellar/openjdk@21/21.0.10/libexec/openjdk.jdk/Contents/Home ./gradlew assembleDebug`

### 关键技术决策
| 能力 | 方案 | 备注 |
|------|------|------|
| 元素定位（Mac） | easyocr | pytesseract 中文分词差，uiautomator dump 在华为微信上返回空 |
| 元素定位（手机端） | ML Kit Chinese (bundled) | 不依赖 GMS/HMS，APK 自带模型 |
| 中文输入 | uiautomator2 send_keys | 需装辅助 APK，华为需开 USB 安装权限 |
| 截屏 | `adb shell screencap -p /data/local/tmp/s.png` | 不经 FUSE，比 /sdcard/ 快 |
| adb input text | 不支持中文 | NullPointerException，clipboard 也不可用 |
| 截屏显示 | 必须 sips -Z 1800 缩小 | 原始 1200x2640 超 Claude 2000px 限制 |

### 已知问题
1. OCR 偶尔误读（"康"→"東"）— ML Kit 和 easyocr 都有此问题
2. POST /snap 端点 NanoHTTPD 二进制 body 解析 bug — 文件方式 workaround
3. 微信双开弹选择框 — 每次 am start 会弹"使用以下方式打开"
4. 发送按钮白字绿底 OCR 不稳定 — 用坐标 (1008, 2425) 或 OCR "(田发送"

### 下一步（周一继续）
1. **速度优化**：发送按钮固定坐标不走 OCR（省2s），缩短 sleep（省2s），目标 5-6s/操作
2. **OCR 推理优化**：缩图再识别 / NNAPI 加速，目标 <1s
3. **集成到 Agent 主循环**：device OCR 引擎接入 ocr_grounding.py
4. 配置 .env（Poe API Key）
5. 接入 VLM（Poe API 调 Qwen2.5-VL）— 复杂场景屏幕理解
6. 端到端跑通复杂多步任务（滑动、长按、跨 App）
7. 完善验证纠错层

### 技术背景
项目灵感来自对字节 UI-TARS / 豆包手机的深度调研。结论：
- UI-TARS 开源的是权重+推理壳，训练代码和系统级操控完全闭源
- 核心壁垒不是模型，是"截屏→理解→定位→规划→执行→验证"的全链路
- 本项目目标：用开源 VLM + ADB 复现这个全链路