安卓智能体：MobileAgent分析及体验

1
2
3
4
5
6
7

uv venv 
source .venv/bin/activate
uv pip install -r requirements.txt

export ADB_PATH="/usr/local/bin/adb"
export QWEN_API_KEY="sk-xxx"
bash scripts/run_task.sh

1
2
3
4
5
6
7
8

....
  File "/Users/yzddmr6/project/MobileAgent/Mobile-Agent-E/.venv/lib/python3.10/site-packages/modelscope/models/base/base_head.py", line 5, in <module>
    from modelscope.models.base.base_model import Model
  File "/Users/yzddmr6/project/MobileAgent/Mobile-Agent-E/.venv/lib/python3.10/site-packages/modelscope/models/base/base_model.py", line 16, in <module>
    from modelscope.utils.plugins import (register_modelhub_repo,
  File "/Users/yzddmr6/project/MobileAgent/Mobile-Agent-E/.venv/lib/python3.10/site-packages/modelscope/utils/plugins.py", line 18, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

1

uv pip install --upgrade pip setuptools

1
2

pip uninstall numpy
pip install numpy==1.26.4 # 或者 1.26.x 的最新稳定版本

1

ImportError cannot import name 'get_metadata_patterns' from 'datasets.data_files

1

pip install "datasets<3"

1
2
3
4

## Reasoning model configs
BACKBONE_TYPE = os.environ.get("BACKBONE_TYPE", default="OpenAI") # "OpenAI" or "Gemini" or "Claude"
assert BACKBONE_TYPE in ["OpenAI", "Gemini", "Claude"], "Unknown BACKBONE_TYPE"
print("### Using BACKBONE_TYPE:", BACKBONE_TYPE)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

该项目（Mobile-Agent-E）是一个自动化移动设备操作智能体系统，能够通过感知、推理、执行和反思等模块，自动完成手机上的复杂任务。下面将详细分析其执行逻辑，并给出详细的执行流程图和各主要函数的调用关系。

---

## 一、整体执行流程

### 1. 启动入口

- **入口文件**：`run.py`
- **主函数**：`main()`
  - 解析命令行参数（如任务、日志目录、推理模型等）
  - 根据参数决定是单任务还是多任务模式
  - 调用 `run_single_task()`（单任务）或循环调用（多任务）

---

### 2. 单任务执行主流程

#### 主要函数：`run_single_task()`（inference_agent_E.py）

#### 详细流程：

1. **日志与环境初始化**
   - 创建日志目录、截图目录、临时目录
   - 读取/初始化 tips 和 shortcuts
   - 初始化 InfoPool（信息池，贯穿任务始终，记录所有状态）

2. **感知模型与Agent初始化**
   - 初始化 Perceptor（感知器，负责屏幕内容感知）
   - 初始化 Manager、Operator、Notetaker、ActionReflector、ExperienceReflectorShortCut、ExperienceReflectorTips 等智能体

3. **主循环（每一步迭代）**
   - **感知（Perception）**
     - `perceptor.get_perception_infos()`：获取当前屏幕的文本、图标等信息
     - 记录到 InfoPool
   - **高层规划（Planning）**
     - `manager.get_prompt()`：生成高层计划提示词
     - `add_response()`：构造多模态对话历史
     - `get_reasoning_model_api_response()`：调用大模型推理，得到计划
     - `manager.parse_response()`：解析计划、当前子目标
     - 更新 InfoPool
   - **经验反思（Experience Reflection）**（仅在任务结束时）
     - `exp_reflector_shortcuts.get_prompt()`、`exp_reflector_tips.get_prompt()`：生成反思提示
     - `get_reasoning_model_api_response()`：推理生成新 shortcut 和 tips
     - `exp_reflector_shortcuts.add_new_shortcut()`：添加新 shortcut
     - 更新 InfoPool
   - **执行（Action Decision & Execution）**
     - `operator.get_prompt()`：生成操作提示
     - `add_response()`：构造多模态对话历史
     - `get_reasoning_model_api_response()`：推理生成 action
     - `operator.parse_response()`：解析 action
     - `operator.execute()`：执行 action（包括原子操作和快捷操作）
     - 更新 InfoPool
   - **再感知（Perception）**
     - 再次调用 `perceptor.get_perception_infos()`，获取执行后的屏幕状态
     - 更新 InfoPool
   - **反思（Action Reflection）**
     - `action_reflector.get_prompt()`：生成反思提示
     - `add_response_two_image()`：构造前后截图的多模态对话历史
     - `get_reasoning_model_api_response()`：推理判断 action 成功与否
     - `action_reflector.parse_response()`：解析结果
     - 更新 InfoPool
   - **重要内容记录（Notetaking）**
     - 如果 action 成功，调用 `notetaker.get_prompt()`、`add_response()`、`get_reasoning_model_api_response()`、`notetaker.parse_response()`，记录重要内容
     - 更新 InfoPool
   - **终止条件判断**
     - 达到最大步数、连续失败、重复操作、任务完成等条件时，调用 `finish()` 结束任务

---

## 二、主要函数调用关系

### 1. run.py
- `main()`  
  └── `run_single_task()`（或多次）

### 2. inference_agent_E.py
- `run_single_task()`
  - 初始化各 Agent
  - 主循环
    - `perceptor.get_perception_infos()`
      - `get_screenshot()`
      - `ocr()`
      - `det()`
      - `merge_text_blocks()`
      - `draw_coordinates_on_image()`
      - `crop()`
      - `generate_api()`/`generate_local()`
    - `manager.get_prompt()`
    - `add_response()`
    - `get_reasoning_model_api_response()`
      - `inference_chat()`
    - `manager.parse_response()`
    - `operator.get_prompt()`
    - `add_response()`
    - `get_reasoning_model_api_response()`
    - `operator.parse_response()`
    - `operator.execute()`
      - `execute_atomic_action()`（tap、swipe、type、back、home、switch_app、enter、wait等）
      - `save_screenshot_to_file()`
    - `action_reflector.get_prompt()`
    - `add_response_two_image()`
    - `get_reasoning_model_api_response()`
    - `action_reflector.parse_response()`
    - `notetaker.get_prompt()`
    - `add_response()`
    - `get_reasoning_model_api_response()`
    - `notetaker.parse_response()`
    - `finish()`

---

## 三、执行流程图

---mermaid
flowchart TD
    A[main() in run.py] --> B{单任务 or 多任务}
    B -- 单任务 --> C[run_single_task()]
    B -- 多任务 --> C[run_single_task() 循环]
    C --> D[初始化日志/目录/InfoPool]
    D --> E[初始化 Perceptor & Agents]
    E --> F{主循环: 每步迭代}
    F --> G[Perceptor 感知 get_perception_infos]
    G --> H[Manager 规划 get_prompt → 推理 → parse_response]
    H --> I{是否任务完成}
    I -- 否 --> J[Operator 执行 get_prompt → 推理 → parse_response → execute]
    J --> K[Perceptor 再感知 get_perception_infos]
    K --> L[ActionReflector 反思 get_prompt → 推理 → parse_response]
    L --> M{Action 成功?}
    M -- 是 --> N[Notetaker 记录 get_prompt → 推理 → parse_response]
    M -- 否 --> O[跳过 Notetaker]
    N --> P[更新 InfoPool & 日志]
    O --> P
    P --> F
    I -- 是 --> Q[ExperienceReflector 反思经验]
    Q --> R[finish() 结束]
---

---

## 四、各核心函数说明

### 1. 感知相关
- `get_perception_infos()`：调用截图、OCR、图标检测、图标描述，合并文本块，返回所有可交互元素信息。
- `ocr()`：OCR 检测与识别，返回文本及其坐标。
- `det()`：图标检测，返回图标坐标。
- `generate_api()/generate_local()`：对图标图片进行描述。

### 2. 规划与推理
- `get_prompt()`（Manager/Operator/ActionReflector/Notetaker）：根据 InfoPool 生成多模态提示词。
- `add_response()/add_response_two_image()`：构造多模态对话历史。
- `get_reasoning_model_api_response()`：调用大模型 API 进行推理。
- `parse_response()`：解析模型输出，提取计划、action、反思结果等。

### 3. 执行与操作
- `execute()`（Operator）：解析 action，调用原子操作或快捷操作。
- `execute_atomic_action()`：具体执行 tap、swipe、type、back、home、switch_app、enter、wait 等操作。
- `save_screenshot_to_file()`：保存执行后截图。

### 4. 反思与自我进化
- `ActionReflector`：判断 action 是否成功，分析失败原因。
- `Notetaker`：记录重要内容。
- `ExperienceReflectorShortCut/ExperienceReflectorTips`：反思生成新 shortcut 和 tips。

### 5. 终止与总结
- `finish()`：保存最终 tips、shortcuts，总结任务过程。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

Qwen-VL-Plus 等云端 API 模型和本地 OCR 识别模型在项目中的作用有明显区别：

---

### 1. Qwen-VL-Plus（云端多模态大模型）的作用
- 主要用于**图标描述**（icon captioning）和复杂多模态理解。
- 输入是裁剪下来的图标图片，输出是对图标的形状、颜色等自然语言描述。
- 适合需要理解图片内容、场景、复杂语义的任务。
- 在代码中，`generate_api`、`process_image` 等函数会调用 Qwen-VL-Plus API，对图标图片进行描述。

### 2. 本地 OCR 识别模型的作用
- 专门用于**屏幕文本的检测和识别**，即提取屏幕上的所有可见文字及其坐标。
- 由 ModelScope 的 OCR 检测和识别 pipeline 实现，速度快、资源消耗低、无需联网。
- 在代码中，`ocr()` 函数会调用本地 OCR pipeline，直接返回文本内容和位置。

---

## 为什么不直接用 Qwen-VL-Plus 做 OCR 识别？

1. **专业性与准确率**  
   - Qwen-VL-Plus 是通用多模态大模型，虽然能理解图片，但在纯 OCR 任务（尤其是小字体、复杂背景、中文等）上，准确率远低于专用 OCR 模型。
   - 专业 OCR 模型针对文本检测和识别优化，效果更好。

2. **效率与成本**  
   - 本地 OCR 推理速度快、无需网络、无 API 调用费用。
   - Qwen-VL-Plus 作为云端大模型，推理慢且每次调用都消耗 API 额度，成本高。

3. **工程分工明确**  
   - 项目采用“专用模型做专用事”：OCR 负责文本，Qwen-VL-Plus 负责图标/复杂图片理解，互补协作，提升整体性能和效率。

4. **API 限制与稳定性**  
   - 频繁调用云端大模型做 OCR，容易受限于 API 速率、网络波动，影响系统稳定性。

---

## 总结

- **本地 OCR**：高效、准确地提取屏幕文本。
- **Qwen-VL-Plus**：理解和描述图标、复杂图片内容。
- **分工协作**，各司其职，提升系统整体效果和效率。

这也是业界常见的多模态系统工程实践。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

def get_perception_infos(self, screenshot_file, temp_file=TEMP_DIR):
        # 通过ADB获取当前屏幕截图
        get_screenshot(self.adb_path)
        
        # 打开截图，获取图片宽高
        width, height = Image.open(screenshot_file).size
        
        # 对截图进行OCR，获取文本和对应坐标
        text, coordinates = ocr(screenshot_file, self.ocr_detection, self.ocr_recognition)
        # 合并相邻的文本块
        text, coordinates = merge_text_blocks(text, coordinates)
        
        # 计算每个文本块的中心点坐标
        center_list = [[(coordinate[0]+coordinate[2])/2, (coordinate[1]+coordinate[3])/2] for coordinate in coordinates]
        # 在图片上绘制中心点
        draw_coordinates_on_image(screenshot_file, center_list)
        
        # 构建感知信息列表，每个元素包含文本和坐标
        perception_infos = []
        for i in range(len(coordinates)):
            perception_info = {"text": "text: " + text[i], "coordinates": coordinates[i]}
            perception_infos.append(perception_info)
            
        # 检测图标（icon），获取其坐标
        coordinates = det(screenshot_file, "icon", self.groundingdino_model)
        
        # 将检测到的icon加入感知信息列表
        for i in range(len(coordinates)):
            perception_info = {"text": "icon", "coordinates": coordinates[i]}
            perception_infos.append(perception_info)
            
        # 筛选所有icon的坐标和对应的索引
        image_box = []
        image_id = []
        for i in range(len(perception_infos)):
            if perception_infos[i]['text'] == 'icon':
                image_box.append(perception_infos[i]['coordinates'])
                image_id.append(i)

        # 将每个icon区域裁剪出来，保存到临时文件夹
        for i in range(len(image_box)):
            crop(screenshot_file, image_box[i], image_id[i], temp_file=temp_file)

        # 获取临时文件夹下所有图片文件
        images = get_all_files_in_folder(temp_file)
        if len(images) > 0:
            # 按文件名中的数字排序
            images = sorted(images, key=lambda x: int(x.split('/')[-1].split('.')[0]))
            # 提取图片对应的id
            image_id = [int(image.split('/')[-1].split('.')[0]) for image in images]
            icon_map = {}
            # 设定描述icon的提示词
            prompt = 'This image is an icon from a phone screen. Please briefly describe the shape and color of this icon in one sentence.'
            if CAPTION_CALL_METHOD == "local":
                # 本地模型生成icon描述
                for i in range(len(images)):
                    image_path = os.path.join(temp_file, images[i])
                    icon_width, icon_height = Image.open(image_path).size
                    # 过滤掉过大的icon
                    if icon_height > 0.8 * height or icon_width * icon_height > 0.2 * width * height:
                        des = "None"
                    else:
                        des = generate_local(self.vlm_tokenizer, self.vlm_model, image_path, prompt)
                    icon_map[i+1] = des
            else:
                # API方式批量生成icon描述
                for i in range(len(images)):
                    images[i] = os.path.join(temp_file, images[i])
                icon_map = generate_api(images, prompt, caption_model=CAPTION_MODEL)
            # 将icon描述填充回感知信息
            for i, j in zip(image_id, range(1, len(image_id)+1)):
                if icon_map.get(j):
                    perception_infos[i]['text'] = "icon: " + icon_map[j]

        # 将所有感知信息的坐标转为中心点坐标（整数）
        for i in range(len(perception_infos)):
            perception_infos[i]['coordinates'] = [int((perception_infos[i]['coordinates'][0]+perception_infos[i]['coordinates'][2])/2), int((perception_infos[i]['coordinates'][1]+perception_infos[i]['coordinates'][3])/2)]
            
        # 返回感知信息、图片宽度和高度
        return perception_infos, width, height

1

The agent can be run in both `individual` (performing a standalone task) or `evolution` (performing a sequence of tasks with evolution) settings. We provide example shell scripts as follows:

1
2
3
4

python run.py \
    --run_name "testing" \
    --setting "individual" \
    --instruction "Find me at least two survery papers on Large Language Models. Check the detailed abstract of the most cited one. And then create a new note in Notes and add the titles the papers you found. Also include the abstract of the most cited paper."

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

### Manager ... ###

Thought: The current subgoal is to open the Chrome browser. I can see the Chrome icon on the home screen. I will tap on the Chrome icon to open the browser.
Overall Plan: 1. Open the Chrome browser. 2. Navigate to the blog `yzddmr6.com`. 3. Read the content of the first three articles on the blog. 4. Generate a summary of the content from the three articles. 5. Open the file manager (MT管理器). 6. Create a new text file named `blog.txt` and save the generated summary into it.
Current Subgoal: 1. Open the Chrome browser.

### Operator ... ###

Executing atomic action:  Tap {'x': 745, 'y': 1963}
        Atomic Operation Screenshot saved to logs/gemini-2.5-flash-preview-05-20/mobile_agent_E/testing/20250614-105247/screenshots/2__Tap.png
Action Thought: My previous attempt to open Chrome using `Open_App` failed, indicating that the app name "Chrome" might not be recognized or directly available for that action. Looking at the screenshot, I can see the Chrome browser icon at coordinates [745, 1963]. To open the browser, I will directly tap on this icon.
Action Description: Tap the Chrome browser icon to open the application. This is a direct way to launch the app when `Open_App` fails or the app name is not explicitly listed.
Action: {'name': 'Tap', 'arguments': {'x': 745, 'y': 1963}}

### Perceptor ... ###

SupervisionWarnings: annotate is deprecated: `BoxAnnotator` is deprecated and will be removed in `supervision-0.22.0`. Use `BoundingBoxAnnotator` and `LabelAnnotator` instead
Perception Infos: [{'text': 'text: 91%', 'coordinates': [956, 60]}, {'text': 'text: @', 'coordinates': [335, 62]}, {'text': 'text: 10:54', 'coordinates': [246, 61]}, {'text': 'text: 40', 'coordinates': [753, 62]}, {'text': 'text: e', 'coordinates': [801, 62]}, {'text': 'text: O', 'coordinates': [63, 167]}, {'text': 'text: i', 'coordinates': [1014, 166]}, {'text': 'text: 0', 'coordinates': [881, 167]}, {'text': 'text: Google', 'coordinates': [535, 336]}, {'text': 'text: 搜索或输入网址', 'coordinates': [283, 560]}, {'text': 'text: f', 'coordinates': [834, 851]}, {'text': 'text: 虎', 'coordinates': [613, 852]}, {'text': 'text: 虎扑', 'coordinates': [612, 965]}, {'text': 'text: 百度', 'coordinates': [187, 966]}, {'text': 'text: Gitl', 'coordinates': [1012, 965]}, {'text': 'text: YouTube', 'coordinates': [400, 966]}, {'text': 'text: Facebook', 'coordinates': [827, 966]}, {'text': 'text: 探索', 'coordinates': [125, 1186]}, {'text': 'text: 8', 'coordinates': [937, 1194]}, {'text': 'text: X', 'coordinates': [915, 1330]}, {'text': 'text: 获得更合平需求的内容', 'coordinates': [539, 1485]}, {'text': 'text: 登录即可获取系统根据您的兴趣推荐的内容', 'coordinates': [539, 1573]}, {'text': 'text: 以6的身份继续', 'coordinates': [540, 1694]}, {'text': 'text: 选择其他账号', 'coordinates': [536, 1825]}, {'text': 'text: 用了几十年才刚知道,\n塑料椅中间的小洞是这', 'coordinates': [361, 2074]}, {'text': 'text: 么用的,涨知识了', 'coordinates': [303, 2172]}, {'text': 'text: i', 'coordinates': [966, 2266]}, {'text': 'text: 阿波罗新闻网·1日', 'coordinates': [290, 2269]}, {'text': 'icon: The icon is a blue square with a white paw print in the center.', 'coordinates': [186, 847]}, {'text': 'icon: The icon is a square with rounded corners, featuring a red background and a white play button in the center.', 'coordinates': [399, 847]}, {'text': 'icon: The icon is a teal circle with the number 6 in white.', 'coordinates': [538, 1356]}, {'text': 'icon: The icon is a blue square with rounded corners, featuring the white lowercase letter "f" in the center.', 'coordinates': [824, 847]}, {'text': 'icon: The icon is a simple, black house shape with a triangular roof on a white background.', 'coordinates': [65, 166]}, {'text': 'icon: The icon is a dark purple circle with a white camera outline inside it.', 'coordinates': [935, 560]}, {'text': 'icon: The icon is a yellow sun with rays extending outward, set against a white background.', 'coordinates': [109, 2265]}, {'text': 'icon: The icon depicts four orange plastic stools arranged in a square formation.', 'coordinates': [848, 2101]}, {'text': 'icon: The icon is a simple, rounded square with a white microphone symbol in the center, set against a dark gray background.', 'coordinates': [803, 560]}, {'text': 'icon: The icon is a square with rounded corners, colored black and white, featuring the number "1" in the center.', 'coordinates': [880, 166]}, {'text': 'icon: The icon is a black circle with a smaller white circle in the center, resembling an eye or a simplified face.', 'coordinates': [743, 165]}, {'text': "icon: The icon features a stylized, simplified shape of a tiger's head in black against a white background.", 'coordinates': [613, 848]}, {'text': 'icon: The icon is a circular shape with a dark background and features the red Chinese character "虎" (tiger) in the center.', 'coordinates': [612, 847]}, {'text': 'icon: The icon is a white, stylized word "Google" on a black background.', 'coordinates': [535, 337]}, {'text': 'icon: The icon is a black, X-shaped symbol on a white background.', 'coordinates': [913, 1327]}, {'text': 'icon: The icon is a black, circular shape with two smaller circles connected by lines, resembling a share symbol.', 'coordinates': [833, 2265]}, {'text': 'icon: The icon is a square with rounded corners, featuring a red play button on a white background, set against a dark circular backdrop.', 'coordinates': [399, 847]}, {'text': 'icon: The icon is an oval shape with a light purple background.', 'coordinates': [539, 1693]}, {'text': 'icon: The icon is a circular shape with a white background and a black outline, featuring a small vertical line in the center.', 'coordinates': [335, 62]}, {'text': 'icon: The icon depicts two orange, square-shaped stools stacked on top of each other.', 'coordinates': [777, 2090]}, {'text': 'icon: The icon depicts a simple, orange stool with a square seat and four legs.', 'coordinates': [823, 2128]}, {'text': 'icon: The icon features a simple, orange stool with a circular seat and four square legs.', 'coordinates': [935, 2120]}, {'text': 'icon: The icon is a simple, black Chinese character "探索" (exploration) on a white background.', 'coordinates': [125, 1185]}, {'text': 'icon: The icon features a square shape with rounded edges, colored in a bright orange hue.', 'coordinates': [884, 2052]}, {'text': 'icon: The icon is a simple, bold numeral "6" in black against a white background.', 'coordinates': [539, 1355]}, {'text': 'icon: The icon is a black circle with a diagonal line crossing through it, indicating prohibition or cancellation.', 'coordinates': [751, 61]}, {'text': 'icon: The icon is a white semicircle on a black background.', 'coordinates': [853, 60]}, {'text': 'icon: The icon is a square with rounded corners, featuring the letter "f" in white on a blue background.', 'coordinates': [824, 846]}, {'text': 'icon: The icon is a square with rounded corners, featuring a light blue paw print design and the letters "du" in a darker shade of blue.', 'coordinates': [186, 846]}, {'text': 'icon: The icon is a black square with white Chinese text that reads, "用了几十年才刚知道，塑料椅中间的小洞是这么用的，涨知识了."', 'coordinates': [361, 2106]}, {'text': 'icon: The icon is a circular shape with a dark gray color.', 'coordinates': [1017, 847]}, {'text': 'icon: The icon is a simple black circle with a horizontal line through the center, indicating a cancel or stop function.', 'coordinates': [800, 61]}]

### Action Reflector ... ###

Outcome: A
Progress Status: 1. Open the Chrome browser. 2. Navigate to yzddmr6.com.
Error Description: None

### NoteKeeper ... ###

Important Notes: - The Chrome browser is open and displaying the Google search page. - There is a search/URL input field labeled "搜索或输入网址" (Search or enter URL) at coordinates [283, 560].

=========================================================
sleeping for 5 before next iteration ...