UFO 源码实战 (1)：环境搭建与 ufo.py 入口函数保姆级解读

最新推荐文章于 2025-12-11 20:49:41 发布

原创最新推荐文章于 2025-12-11 20:49:41 发布 · 721 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#python

python 同时被 2 个专栏收录

83 篇文章

订阅专栏

源码分析

53 篇文章

订阅专栏

前言

微软开源的 UFO (UI-Focused Agent) 是目前 AI Agent 领域的一颗新星。它利用 GPT-4V 的视觉能力，能够像人类一样操作 Windows 应用程序。

很多同学都想研究它的源码，但面对复杂的项目结构往往无从下手。本系列专栏将带你“手把手”拆解 UFO 源码，从环境搭建到核心算法，彻底搞懂这个 AI 操控系统的黑科技。

今天第一篇，我们先攻克环境搭建，并深入解读整个程序的入口文件 ufo.py，看看它是如何启动并分发任务的。

🚀 第一步：硬核环境准备

UFO 依赖于 Windows 的底层 API 和 UI 自动化库，所以对环境有一定要求。

1. 基础环境

操作系统：必须是 Windows 10/11（因为底层用了 pywinauto 和 Windows UI Automation API）。
Python 版本：建议 Python 3.10+。
API Key：你需要一个 OpenAI GPT-4V (Vision) 的 Key。这是 UFO 的“眼睛”和“大脑”。

2. 获取源码

打开终端（CMD 或 PowerShell），执行以下命令：

Bash

git clone https://github.com/microsoft/UFO.git
cd UFO

3. 安装依赖

UFO 的依赖主要包括 pywinauto (控制窗口)、openai (调用大模型)、rich (美化终端输出) 等。

Bash

pip install -r requirements.txt

💡 避坑指南：如果你在国内，安装依赖慢，记得加上镜像源，例如：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

⚙️ 第二步：配置你的“驾驶员”

在运行代码前，必须配置 API Key。UFO 使用 TOML 格式进行配置。

找到 ufo/config/ 目录。
将 config_template.toml 复制一份，重命名为 config.toml。
打开 config.toml，重点修改以下几项：

Ini, TOML

# ufo/config/config.toml

[API_KEY]
# 填入你的 OpenAI Key
OPENAI_API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxx" 

[Visual_Model]
# 确保这里是支持视觉的模型，如 gpt-4-vision-preview 或 gpt-4o
VISUAL_MODEL = "gpt-4-vision-preview"

🔍 第三步：入口代码 `ufo.py` 深度解析

环境配好了，我们直奔主题。ufo.py (或者 ufo/__main__.py) 是整个项目的启动入口。它的核心职责只有三个：

接收参数：用户想干什么？
初始化系统：加载配置、加载 Agent。
启动循环：开始干活。

我们要分析的代码通常位于项目根目录下。让我们逐段拆解：

1. 引入模块与参数解析

Python

import argparse
from ufo.config.config import load_config
from ufo.ufo_system import UFO

# 定义参数解析器
parser = argparse.ArgumentParser(description="Microsoft UFO: UI-Focused Agent")

# --task: 用户输入的指令，例如 "帮我在记事本里写首诗"
parser.add_argument("--task", type=str, default="", help="The task you want UFO to perform.")
# --app: 指定要操作的 App，例如 "Notepad"
parser.add_argument("--app", type=str, default="", help="The application name.")

解析：

这里使用了 Python 标准库 argparse。这告诉我们，启动 UFO 最简单的方式是在命令行传参。

2. 核心入口函数 `main()`

这是逻辑的起点。

Python

def main():
    args = parser.parse_args()
    
    # 1. 加载全局配置
    # 这一步会读取我们刚才修改的 config.toml
    configs = load_config() 

    # 2. 实例化 UFO 系统核心类
    # 这里的 UFO 类是某种"总控"角色，它管理着 AppAgent 和 ActionAgent
    ufo_system = UFO(task=args.task, app_name=args.app)

    # 3. 启动任务
    # run() 方法是真正的执行流，我们将在后续文章详细分析
    ufo_system.run()

if __name__ == "__main__":
    main()

3. 深入 `UFO` 类 (简要预览)

为了看懂 main 函数里发生了什么，我们必须稍微看一眼 ufo/ufo_system.py 中的 UFO 类初始化做了什么。

(注：以下为简化逻辑，方便理解)

Python

class UFO:
    def __init__(self, task, app_name):
        self.task = task
        self.app_name = app_name
        
        # 核心：初始化两个 Agent
        # HostAgent通常负责宏观规划，AppAgent负责具体应用操作
        self.host_agent = HostAgent(...) 
        self.app_agent = AppAgent(...) 
        
    def run(self):
        # 打印欢迎语
        print_welcome_message()
        
        # 开启交互循环
        while True:
            # 1. 视觉感知当前屏幕
            # 2. 发送给 GPT-4V 决策
            # 3. 执行鼠标键盘操作
            # ...
            pass

博主解读：

看到这里，你脑子里应该有一个清晰的图谱了：

ufo.py 只是个“传话筒”，它把用户的 --task 传给 UFO 类，而 UFO 类内部通过 run() 方法开启了一个 "感知 -> 思考 -> 执行" 的死循环，直到任务完成。

💻 第四步：跑通 Hello World

现在，让我们来运行第一次测试。假设我们要让 UFO 打开记事本。

在终端输入：

Bash

python -m ufo --task "Open Notepad and type 'Hello World'" --app "Notepad"

预期效果：

终端会打印出 UFO 的 Logo 和初始化日志。
你的鼠标会自动移动（请不要惊慌，不要抢鼠标）。
记事本会被打开，并自动输入文字。

⚠️ 常见报错调试：

AttributeError: module 'PIL.Image' has no attribute 'ANTIALIAS': 这是因为 Pillow 版本过高（10.0+ 移除了此属性），请降级：pip install Pillow==9.5.0。

OpenAI API Connection Error: 检查你的梯子/代理设置，确保终端能访问 OpenAI。