vision-agent-app 1.0.0
Android automation with AI vision and natural language
License: MIT
Requires Python: >=3.11
Keywords: android, automation, ai, vision, adb, testing

# Vision Agent App - Android Automation with AI

独立的 Android 设备自动化项目，基于 AI 视觉识别和自然语言处理。

## 数据流

```mermaid
flowchart LR
    subgraph Input["输入"]
        U[用户命令]
        I[图片]
        D[设备]
    end

    subgraph Process["处理"]
        P1[参数解析]
        P2[模式路由]
        P3[AI 分析]
        P4[动作执行]
    end

    subgraph Output["输出"]
        J[JSON 结果]
        L[日志文件]
        A[标注图片]
    end

    U --> P1
    I --> P2
    D --> P2
    P1 --> P2
    P2 --> P3
    P3 --> P4
    P4 --> J
    P4 --> L
    P4 --> A
```

## 功能特性

- **视觉定位**: 使用 AI 视觉模型定位屏幕元素
- **自然语言交互**: 通过自然语言描述执行设备操作
- **多种模式**:
  - `locate`: 视觉元素定位
  - `ocr`: 从截图中识别并返回提问相关的文本
  - `locate-ocr`: 识别文本 + 估算位置框（并输出标注图）
  - `locate-xml`: 基于 UI 层级的元素定位
  - `action`: 单次设备操作
  - `automate`: 多步自动化任务
  - `diff`: 屏幕变化检测
  - `displays`: 列出物理显示器映射

## 安装

```bash
python -m venv .venv
pip install -r requirements.txt
```

## 配置

复制 `.env.example` 为 `.env`，并按需修改：

```env
# Model API Configuration
VISION_AGENT_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
VISION_AGENT_API_KEY=your_api_key
VISION_AGENT_MODEL=qwen3-vl-plus
VISION_AGENT_TEMPERATURE=0.1
VISION_AGENT_MAX_TOKENS=2048

# Application Settings
VISION_AGENT_LANG=cn
VISION_AGENT_MAX_STEPS=70
VISION_AGENT_OUTPUT_DIR=./outputs

# Device Connection (optional)
VISION_AGENT_DEVICE_ID=

# Timing Configuration
VISION_AGENT_KEYBOARD_SWITCH_DELAY=1.0
VISION_AGENT_TEXT_CLEAR_DELAY=1.0
VISION_AGENT_TEXT_INPUT_DELAY=1.0
VISION_AGENT_KEYBOARD_RESTORE_DELAY=1.0
VISION_AGENT_TAP_DELAY=1.0
VISION_AGENT_DOUBLE_TAP_DELAY=1.0
VISION_AGENT_DOUBLE_TAP_INTERVAL=0.1
VISION_AGENT_LONG_PRESS_DELAY=1.0
VISION_AGENT_SWIPE_DELAY=1.0
VISION_AGENT_BACK_DELAY=1.0
VISION_AGENT_HOME_DELAY=1.0
VISION_AGENT_LAUNCH_DELAY=1.0
VISION_AGENT_ADB_RESTART_DELAY=2.0
VISION_AGENT_SERVER_RESTART_DELAY=1.0
```

## 使用

### 命令行参数

| 参数 | 短参数 | 类型 | 必填 | 说明 |
|------|--------|------|------|------|
| `prompt` | - | string | 是* | 用户请求或任务描述 (*displays 模式除外) |
| `--mode` | - | string | 是 | 执行模式 |
| `--image` | `-i` | string | 否 | 输入图片路径（可重复使用） |
| `--device-id` | `-d` | string | 否 | ADB 设备 ID |
| `--display-id` | - | int | 否 | Android WindowManager display ID |
| `--output-dir` | - | string | 否 | 输出目录 |
| `--max-steps` | - | int | 否 | automate 模式最大步数 |
| `--lang` | - | string | 否 | 系统提示语言 |

### 参数取值

#### `--mode` 可选值
| 值 | 说明 |
|----|------|
| `locate` | 视觉元素定位 |
| `ocr` | 从截图识别文本 |
| `locate-ocr` | OCR + 定位（输出标注图） |
| `locate-xml` | 基于 UI 层级定位 |
| `action` | 单次设备操作 |
| `automate` | 多步自动化任务 |
| `diff` | 屏幕变化检测 |
| `displays` | 列出显示器映射 |

### 各模式参数与输出

#### `locate` - 视觉元素定位

| 参数 | 必需 | 说明 |
|------|------|------|
| `prompt` | ✓ | 元素描述 |
| `-i` | - | 图片路径，无则截屏 |
| `-d` | - | 设备 ID |
| `--display-id` | - | 显示器 ID |

```json
{
  "mode": "locate",
  "label": "元素标签",
  "bounding_box": [x1, y1, x2, y2],
  "confidence": 0.95,
  "page": 1,
  "annotated_image_path": "path/to/annotated.png"
}
```

#### `ocr` - 文字识别

| 参数 | 必需 | 说明 |
|------|------|------|
| `prompt` | ✓ | 查询描述 |
| `-i` | - | 图片路径，无则截屏 |
| `--lang` | - | 语言 (cn/en) |

```json
{
  "mode": "ocr",
  "text": "识别的文字",
  "items": [
    {"text": "文字1", "confidence": 0.95, "page": 1}
  ]
}
```

#### `locate-ocr` - 文字定位

| 参数 | 必需 | 说明 |
|------|------|------|
| `prompt` | ✓ | 查询描述 |
| `-i` | - | 图片路径，无则截屏 |
| `--output-dir` | - | 输出目录 |

```json
{
  "mode": "locate-ocr",
  "text": "合并文字",
  "items": [
    {"text": "文字", "bounding_box": [x1,y1,x2,y2], "confidence": 0.95, "page": 1}
  ],
  "annotated_images": [{"page": 1, "annotated_image_path": "..."}]
}
```

#### `locate-xml` - 视觉 + XML 定位

| 参数 | 必需 | 说明 |
|------|------|------|
| `prompt` | ✓ | 元素描述 |
| `-d` | - | 设备 ID (需要设备) |
| `--display-id` | - | 显示器 ID |

```json
{
  "mode": "locate-xml",
  "class": "android.widget.Button",
  "text": "确定",
  "resource-id": "com.app:id/btn_ok",
  "bounds": "[100,200][300,250]",
  "xml_file_path": "path/to/ui.xml"
}
```

#### `action` - 单次操作

| 参数 | 必需 | 说明 |
|------|------|------|
| `prompt` | ✓ | 操作描述 |
| `-d` | - | 设备 ID (需要设备) |
| `--display-id` | - | 显示器 ID |

```json
{
  "mode": "action",
  "action": "Tap",
  "success": true,
  "message": "操作完成"
}
```

#### `automate` - 多步自动化

| 参数 | 必需 | 说明 |
|------|------|------|
| `prompt` | ✓ | 任务描述 |
| `-d` | - | 设备 ID (需要设备) |
| `--max-steps` | - | 最大步数 |
| `--lang` | - | 语言 (cn/en) |

```json
{
  "mode": "automate",
  "status": "finished",
  "message": "任务完成",
  "steps": 5
}
```

#### `diff` - 图片对比

| 参数 | 必需 | 说明 |
|------|------|------|
| `-i` | ✓ | 两张图片路径 |
| `--output-dir` | - | 输出目录 |

```json
{
  "mode": "diff",
  "diff_score": 0.05,
  "diff_boxes": [[x1,y1,x2,y2], ...],
  "diff_image_path": "path/to/diff.png"
}
```

#### `displays` - 显示器列表

| 参数 | 必需 | 说明 |
|------|------|------|
| `-d` | - | 设备 ID (需要设备) |

```json
{
  "mode": "displays",
  "device_id": "设备ID",
  "displays": [
    {"display_id": 0, "hwc_port": 0, "unique_id": "local:..."}
  ]
}
```

#### `--lang` 可选值
| 值 | 说明 |
|----|------|
| `cn` | 中文 |
| `en` | 英文 |

#### `--device-id` 示例
```
10.147.19.228:5554    # 网络连接
emulator-5554         # 模拟器
R3CN90XXXXX           # USB 连接的设备序列号
```

#### `--display-id` 说明
多屏车机系统中不同显示器的 ID：
- `0`: 通常是主屏/娱乐大屏
- `2`, `3`: 仪表盘/副屏等

### 使用示例

```bash
# 视觉定位
python -m vision_agent_app "找到应用列表图标" --mode locate

# OCR 识别
python -m vision_agent_app "屏幕上显示的时间是多少" --mode ocr

# OCR + 定位（输出标注图）
python -m vision_agent_app "找到设置两个字" --mode locate-ocr

# XML 定位（指定显示器）
python -m vision_agent_app "找到应用列表图标" --mode locate-xml --display-id 0

# 单次操作
python -m vision_agent_app "点击apps导航按钮" --mode action

# 多步自动化
python -m vision_agent_app "打开设置并进入蓝牙页面" --mode automate --max-steps 10

# 屏幕变化检测
python -m vision_agent_app "检测屏幕变化" --mode diff

# 列出显示器
python -m vision_agent_app --mode displays

# 指定设备
python -m vision_agent_app "滑动到底部" --mode action --device-id 10.147.19.228:5554

# 使用本地图片
python -m vision_agent_app "找到红色按钮" --mode locate -i screenshot.png

# 多张图片
python -m vision_agent_app "对比两张图片" --mode diff -i before.png -i after.png
```

## 项目结构

```
vision_agent_app/
├── vision_agent_app/
│   ├── device/           # 设备抽象与 ADB 控制
│   ├── modes/            # 各模式实现
│   │   ├── action.py
│   │   ├── automate.py
│   │   ├── diff.py
│   │   ├── displays.py
│   │   ├── llmclient.py
│   │   ├── locate.py
│   │   ├── locate_ocr.py
│   │   ├── locate_xml.py
│   │   └── ocr.py
│   ├── utils/            # 通用工具
│   ├── cli.py            # CLI 入口
│   ├── config.py         # 配置加载
│   └── router.py         # 模式路由
├── docs/
├── main.py
├── setup.py
└── requirements.txt
```

## 文档

- `docs/ARCHITECTURE.md`: 模块职责与运行流程说明

## 依赖

- Python 3.11+
- OpenAI 兼容的 LLM API
- ADB (Android Debug Bridge)
- PIL/Pillow
- uiautomator2 (可选，用于 XML 模式)