在上一篇文章里，我们从宏观角度聊了 UI-TARS：它不是传统意义上的聊天机器人，也不是简单的 RPA 脚本，而是一个面向真实图形界面的 Native GUI Agent。

它的目标是让 AI 像人一样：

看屏幕 → 思考 → 输出动作 → 点击/输入/滚动 → 再看屏幕 → 继续执行

不过，当我们真正打开 UI-TARS 的 GitHub 仓库时，很多人可能会有一个疑问：

为什么代码这么少？
训练代码在哪里？
Agent 主循环在哪里？
桌面控制程序在哪里？

这篇文章就来专门解决这个问题：UI-TARS 开源仓库到底包含了什么？我们应该按什么顺序读？

---

一、先明确：UI-TARS 仓库不是完整训练框架

很多人看到“源码解析”这几个字，会自然以为 UI-TARS 仓库里应该包含：

模型结构代码
训练代码
数据处理代码
强化学习代码
评测环境
桌面 Agent 主程序

但实际上，当前 UI-TARS 主仓库公开的重点并不在训练框架，而是在 部署、Prompt、动作解析、坐标转换和 pyautogui 代码生成 这一条推理后处理链路上。

换句话说，这个仓库更像是：

UI-TARS 模型推理结果的官方后处理 SDK。

官方 README 中也把快速上手流程拆成两步：第一步是模型部署与推理，第二步是 Post Processing，也就是安装 ui-tars 包，把模型输出解析成结构化动作，再转成 pyautogui 代码执行。

这点非常重要。

因为如果我们误以为它是完整的训练仓库，阅读时一定会失望；但如果把它看成“模型输出到真实鼠标键盘动作之间的桥梁”，就会发现它非常值得研究。

---

二、仓库整体结构

从主仓库来看，最核心的内容大致可以分成四类：

UI-TARS
│
├── README.md
├── README_deploy.md
├── README_coordinates.md
│
└── codes
    │
    ├── README.md
    ├── pyproject.toml
    ├── ui_tars
    │   ├── __init__.py
    │   ├── prompt.py
    │   └── action_parser.py
    │
    └── tests
        ├── action_parser_test.py
        └── inference_test.py

其中，codes 目录下明确包含 tests、ui_tars、README.md、makefile、pyproject.toml 和 uv.lock 等文件；codes/README.md 也说明 ui-tars 是一个用于解析 VLM 生成的 GUI 动作指令、生成 pyautogui 脚本，并支持坐标转换和智能图片缩放的 Python 包。

我们可以把这个仓库理解成三层：

第一层：文档层
README.md / README_deploy.md / README_coordinates.md

第二层：核心源码层
prompt.py / action_parser.py

第三层：验证层
tests/action_parser_test.py / tests/inference_test.py

下面我们逐层来看。

---

三、README.md：项目入口与使用路线图

根目录下的 README.md 是整个仓库的入口。

它主要告诉我们三件事：

第一，UI-TARS 是什么。

它强调 UI-TARS 是一个面向自动化 GUI 交互的 Native Agent 项目，也就是通过截图理解界面，并输出鼠标键盘动作。

第二，如何部署和调用模型。

README 中给出的 Quick Start Guide 建议先看部署与推理文档，然后再进行后处理。后处理部分示例代码使用：

from ui_tars.action_parser import (
    parse_action_to_structure_output,
    parsing_response_to_pyautogui_code
)

也就是说，官方推荐的使用方式是：

模型输出文本
    ↓
parse_action_to_structure_output
    ↓
结构化动作
    ↓
parsing_response_to_pyautogui_code
    ↓
pyautogui 自动化代码

这条链路就是后面几篇文章要重点分析的主线。

第三，Prompt 应该如何选择。

README 里专门提到 codes/ui_tars/prompt.py 中提供了三类 Prompt 模板：

COMPUTER_USE
MOBILE_USE
GROUNDING

其中 COMPUTER_USE 适合 Windows、Linux、macOS 这类桌面 GUI 任务；MOBILE_USE 适合移动端或 Android 模拟器；GROUNDING 更偏轻量，只输出 Action，不输出 Thought，适合评估模型定位能力。

这说明 UI-TARS 的设计并不是只服务于桌面端，而是希望统一桌面端、移动端和 grounding 评测场景。

---

四、README_deploy.md：模型怎么跑起来

README_deploy.md 是部署文档，主要围绕 UI-TARS 1.5 在 HuggingFace Inference Endpoints 上的部署。

文档中给出的流程包括：

选择 UI-TARS 1.5 7B 模型
配置 GPU 实例
设置 TGI 容器参数
添加环境变量
创建 Endpoint
通过 OpenAI SDK 风格接口调用

例如，文档建议 7B 模型可选择 GPU L40S 1GPU 48G，并提到可以使用 ghcr.io/huggingface/text-generation-inference:3.2.1 作为容器镜像。

这部分代码对普通读者来说可能不是最核心，但它透露出一个很重要的信息：

UI-TARS 主仓库并没有提供一个完整的本地桌面 App，而是先让你把模型服务部署起来，然后通过 API 获得模型输出。

这也解释了为什么仓库源码重点放在后处理，而不是桌面程序本身。

实际做二次开发时，你需要自己补齐这几个环节：

截图采集
    ↓
调用 UI-TARS 模型服务
    ↓
解析模型输出
    ↓
执行 pyautogui 动作
    ↓
再次截图

官方仓库主要帮你解决的是中间两步：

解析模型输出
执行动作转换

---

五、README_coordinates.md：坐标为什么需要专门处理

GUI Agent 最容易被低估的一件事，就是坐标处理。

很多人会想：

模型输出了一个坐标，直接点不就行了吗？

实际并没有这么简单。

因为模型看到的图片尺寸，往往不是原始屏幕尺寸。截图可能会经过 resize，模型输出也可能是基于缩放后图像的坐标。

因此就会出现这样的问题：

原始屏幕：1920 × 1080
模型输入：可能被缩放成另一种尺寸
模型输出：click(start_box='(197,525)')
真实点击：需要还原到原图坐标

README_coordinates.md 就是专门解释这个问题的文档。文档示例中假设模型输出：

Thought: xxx
Action: click(start_box='(197,525)')

然后通过代码把模型输出坐标可视化到图片上，帮助开发者理解模型想点的位置。

这也是 UI-TARS 源码中 smart_resize、坐标缩放、start_box / end_box 转换存在的原因。

对 GUI Agent 来说，坐标不是一个简单的数字，而是连接“模型视觉世界”和“真实屏幕世界”的桥梁。

---

六、codes/README.md：Python 包的真正定位

codes/README.md 基本可以看作 ui-tars Python 包的说明书。

它对这个包的定位非常直接：

解析 VLM 生成的 GUI 动作指令，自动生成 pyautogui 脚本，并支持坐标转换和智能图像缩放。

它列出的核心能力包括：

支持多种 VLM 输出格式
自动处理坐标缩放
自动处理格式转换
一键生成 pyautogui 自动化脚本

从这里可以看出，UI-TARS 开源代码不是在做“大模型推理”本身，而是在做“大模型推理结果的工程落地”。

这类代码看起来不如模型结构复杂，但在实际产品里非常关键。

因为模型输出的是文本：

Action: click(point='<point>200 300</point>')

而操作系统需要的是确定的鼠标键盘动作：

pyautogui.click(384, 324, button='left')

中间这一步如果处理不好，整个 Agent 就会失控。

---

七、prompt.py：定义 Agent 能说什么、能做什么

prompt.py 是整个仓库最容易读懂、但也最重要的文件之一。

它本质上定义了 UI-TARS 的“动作语言”。

在 COMPUTER_USE_DOUBAO 模板中，模型被要求按照下面格式输出：

Thought: ...
Action: ...

同时，它被限定只能使用一组明确的动作：

click
left_double
right_single
drag
hotkey
type
scroll
wait
finished

这些动作覆盖了桌面 GUI 自动化中最常见的鼠标、键盘和等待操作。

移动端模板 MOBILE_USE_DOUBAO 又额外增加了：

long_press
open_app
press_home
press_back

这说明移动端 Agent 需要处理一些桌面端没有的系统级行为，比如回到主页、返回上一页、打开 App 等。

GROUNDING_DOUBAO 则更简单，要求只输出：

Action: ...

这类 Prompt 通常更适合测试模型“看图定位”的能力，而不是完整任务规划能力。

所以，prompt.py 的核心价值在于：

它把一个开放式的自然语言模型，约束成了一个可执行的 GUI 动作生成器。

没有这个约束，模型可能会输出一大段解释，但自动化系统无法执行。

---

八、action_parser.py：整个仓库最核心的源码

如果说 prompt.py 负责“规定模型怎么说”，那么 action_parser.py 就负责“把模型说的话变成机器能执行的动作”。

这个文件是整个仓库最值得深入读的部分。

从源码看，它主要完成几件事：

1. 解析模型输出的 Action 字符串
2. 把 point / start_point / end_point 统一成 start_box / end_box
3. 根据模型类型处理坐标缩放
4. 把动作转换为结构化 dict
5. 把结构化动作转换成 pyautogui 代码

例如，模型可能输出：

Thought: Click the button
Action: click(point='<point>200 300</point>')

经过 parse_action_to_structure_output 后，会变成类似：

[
    {
        "thought": "Click the button",
        "action_type": "click",
        "action_inputs": {
            "start_box": "[0.1, 0.2, 0.1, 0.2]"
        }
    }
]

然后再经过 parsing_response_to_pyautogui_code，生成真正可以执行的 pyautogui 脚本。

源码中可以看到，parse_action 使用 Python AST 来解析 action 字符串，smart_resize 用于根据像素上下限和 28 的倍数要求调整图像尺寸，parse_action_to_structure_output 负责解析 Thought/Action 和坐标，parsing_response_to_pyautogui_code 则负责生成 click、hotkey、type、drag、scroll 等 pyautogui 操作。

这就是 UI-TARS 开源代码的技术核心。

一句话概括：

action_parser.py 是模型输出和真实 GUI 操作之间的翻译器。

---

九、pyproject.toml：这是一个轻量级 Python 包

codes/pyproject.toml 也值得看一下。

它说明项目包名是 ui-tars，版本为 0.1.4，描述是：

Parsing LLM-generated GUI action instructions,
automatically generating pyautogui scripts,
and supporting coordinate conversion and smart image resizing.

同时，项目要求 Python 版本为 >=3.10,<4.0，运行依赖为空，开发依赖中包含 matplotlib 和 pillow，主要用于测试和坐标可视化。

这说明官方有意把这个包做得很轻：

不绑定复杂框架
不强依赖深度学习库
不强依赖特定推理服务
只负责动作解析与脚本生成

这对于二次开发其实是好事。

你可以把它接到：

HuggingFace Endpoint
本地 VLM 服务
OpenAI-compatible API
自建模型网关
桌面自动化项目

只要模型输出格式符合要求，就可以复用这套解析链路。

---

十、tests：用最小测试验证核心链路

codes/tests 目录下目前主要有两个测试文件：

action_parser_test.py
inference_test.py

其中 action_parser_test.py 覆盖了三个核心函数：

parse_action
parse_action_to_structure_output
parsing_response_to_pyautogui_code

测试内容包括：

click(point='200 300') 是否能被解析
解析结果中是否包含 start_box
hotkey 动作是否能生成 pyautogui.hotkey 代码

这些测试看起来很简单，但它们刚好验证了整个 ui-tars 包最核心的三段链路：

Action 字符串
    ↓
结构化动作
    ↓
pyautogui 代码

测试目录中也能看到 action_parser_test.py 和 inference_test.py 两个文件。 action_parser_test.py 中直接导入并测试了 parse_action、parse_action_to_structure_output 和 parsing_response_to_pyautogui_code。

对源码学习来说，这些测试非常适合当作入口。

因为你不需要一上来就读完整个 action_parser.py，可以先从测试用例出发，理解输入是什么、输出是什么，再反向追源码实现。

---

十一、哪些内容没有开源？

这一点也要说清楚。

当前 UI-TARS 主仓库并没有完整提供以下内容：

完整模型训练代码
完整数据构造流水线
强化学习训练环境
本地桌面 App 主程序
完整 Agent Loop
跨平台桌面控制前端

这并不代表项目不完整，而是说明主仓库的开源边界比较明确：

它主要公开的是模型使用、Prompt、动作解析、坐标处理和 pyautogui 代码生成。

如果你想做一个完整的 UI-TARS 桌面自动化产品，还需要自己补齐：

截图模块
任务管理模块
模型调用模块
动作执行模块
状态回传模块
安全确认模块
失败重试模块

也就是说，UI-TARS 给了你“模型动作输出到执行代码”的关键中间层，但没有直接给你一个完整可商用的桌面 Agent 产品。

这也是后面做二次开发时需要重点考虑的地方。

---

十二、推荐源码阅读顺序

如果你是第一次读 UI-TARS，我建议按下面顺序：

第一步：读根目录 README.md
理解项目定位、使用流程和 Prompt 类型。

第二步：读 codes/README.md
理解 ui-tars Python 包到底解决什么问题。

第三步：读 prompt.py
理解模型被要求输出什么格式、可以使用哪些动作。

第四步：读 tests/action_parser_test.py
从最小测试用例理解输入输出。

第五步：读 action_parser.py
深入动作解析、坐标缩放和 pyautogui 代码生成。

第六步：读 README_coordinates.md
单独理解坐标还原逻辑。

第七步：读 README_deploy.md
了解模型部署和接口调用方式。

如果用一张图表示，就是：

README.md
   ↓
codes/README.md
   ↓
prompt.py
   ↓
tests/action_parser_test.py
   ↓
action_parser.py
   ↓
README_coordinates.md
   ↓
README_deploy.md

这样读，不会陷入“为什么没有训练代码”的误区，而是能快速抓住它真正开源的核心价值。

---

十三、从工程角度看 UI-TARS 仓库

从工程角度看，UI-TARS 仓库其实解决了 GUI Agent 落地中非常关键的一个问题：

大模型输出的是不稳定的文本，而操作系统需要的是稳定、明确、可执行的动作。

中间必须经过一层转换。

这层转换包括：

格式约束
动作解析
坐标归一化
坐标还原
动作类型映射
pyautogui 代码生成

这也是为什么 prompt.py 和 action_parser.py 虽然代码量不大，但非常重要。

GUI Agent 真正难的地方，不只是“让模型会看图”，而是让模型输出的内容能被工程系统稳定消费。

一个完整链路大概是这样：

用户任务
   ↓
截图
   ↓
VLM 推理
   ↓
Thought + Action
   ↓
Action Parser
   ↓
结构化动作
   ↓
pyautogui 代码
   ↓
鼠标键盘执行
   ↓
下一轮截图

UI-TARS 主仓库公开的，正是其中：

Thought + Action
   ↓
Action Parser
   ↓
结构化动作
   ↓
pyautogui 代码

这一段。

---

总结

这篇文章我们没有急着分析具体函数，而是先从仓库结构入手，搞清楚 UI-TARS 主仓库到底开源了什么。

简单总结一下：

README.md
负责介绍项目、快速上手和 Prompt 使用方式。

README_deploy.md
负责说明如何部署 UI-TARS 1.5 模型服务。

README_coordinates.md
负责解释模型坐标如何映射回真实图像。

codes/README.md
负责说明 ui-tars Python 包的能力。

prompt.py
负责定义模型输出格式和动作空间。

action_parser.py
负责把模型输出解析成结构化动作，并生成 pyautogui 代码。

tests
负责验证动作解析和代码生成链路。

所以，UI-TARS 主仓库的真正价值不是训练框架，而是：

把 VLM 生成的 GUI 动作，变成真实可执行的桌面自动化代码。

下一篇文章，我们将正式进入 prompt.py，分析 UI-TARS 是如何通过 Prompt 约束模型输出，并定义 GUI Agent 的动作空间的。