UI-TARS开发手册

#AI

一、什么是UI-TARS

UI-TARS是一个神奇的工具，它可以让你用自然语言（就像和朋友聊天一样）来控制你的电脑。它可以看懂屏幕上显示的内容，并根据你的指令来移动鼠标、点击按钮、输入文字等等。

想象一下，你可以对着电脑说："打开浏览器，搜索'小猫咪的图片'"，然后UI-TARS就会帮你完成这些操作！

二、核心概念

1. GUI代理（GUIAgent）

解释：GUI代理是整个系统的大脑，它协调视觉模型、操作执行和反馈处理。

实际用途：

它接收你的指令，比如"打开记事本"
它捕获屏幕截图，以"看见"屏幕内容
它决定应该点击哪里，输入什么内容
它执行操作并检查结果

示例：

// 创建一个GUI代理
const guiAgent = new GUIAgent({
  model: {
    baseURL: "https://你的模型服务地址",
    apiKey: "你的API密钥",
    model: "ui-tars-model"
  },
  operator: new NutJSOperator(),
  onData: (data) => {
    console.log("代理正在执行：", data)
  }
});
 
// 运行代理执行一项任务
await guiAgent.run("打开计算器应用");

2. 操作符（Operator）

解释：操作符是GUI代理的手和眼，负责实际执行鼠标点击、键盘输入等操作，以及获取屏幕截图。

实际用途：

截取电脑屏幕的图像
移动鼠标到特定位置
执行各种点击操作（单击、双击、右键点击）
输入文字、按键盘快捷键
滚动页面

示例：

// NutJS操作符（适用于桌面应用）
const desktopOperator = new NutJSOperator();
 
// 浏览器操作符（适用于网页）
const browserOperator = new BrowserOperator({
  browser: yourBrowserInstance
});

3. 模型（Model）

解释：模型是系统的"大脑"，它使用人工智能来理解屏幕上显示的内容，并决定如何完成用户的指令。

实际用途：

分析屏幕截图
理解用户指令
规划操作步骤
生成具体的操作指令（如点击哪里）

示例：

// 使用远程UI-TARS模型
const model = new UITarsModel({
  baseURL: "https://api.ui-tars.com",
  apiKey: "你的API密钥",
  model: "ui-tars-7b-dpo"
});
 
// 直接调用模型
const result = await model.invoke({
  conversations: [{ from: "human", value: "打开浏览器" }],
  images: [屏幕截图的Base64],
  screenContext: {
    width: 1920,
    height: 1080
  }
});

三、操作类型

UI-TARS可以执行多种操作类型，就像你自己操作电脑一样：

1. 鼠标操作

点击（Click）：模拟鼠标点击屏幕的某个位置。

点击指令：click(start_box='[100, 200, 150, 250]')

双击（Double Click）：模拟鼠标双击操作。

双击指令：left_double(start_box='[100, 200, 150, 250]')

右键点击（Right Click）：模拟鼠标右键点击。

右键点击指令：right_single(start_box='[100, 200, 150, 250]')

2. 拖拽操作（Drag）

解释：从一个位置拖拽到另一个位置。

拖拽指令：drag(start_box='[100, 200, 150, 250]', end_box='[300, 400, 350, 450]')

3. 键盘操作

输入文字（Type）：在当前位置输入文字。

输入指令：type(content='Hello World')

快捷键（Hotkey）：按下键盘快捷键。

快捷键指令：hotkey(key='ctrl+c')

4. 其他操作

滚动（Scroll）：上下或左右滚动页面。

滚动指令：scroll(start_box='[100, 200, 150, 250]', direction='down')

等待（Wait）：等待一段时间。

等待指令：wait()

四、使用流程图

用户 → 发出指令 → GUI代理
                   ↓
            捕获屏幕截图
                   ↓
            发送到AI模型
                   ↓
            接收操作建议
                   ↓
            执行具体操作
                   ↓
            检查操作结果
                   ↓
            重复上述步骤直到任务完成
                   ↓
            任务完成 → 返回结果给用户

五、如何开始使用

命令行快速体验

npx @ui-tars/cli start

输入你的UI-TARS模型服务配置（baseURL, apiKey, model）后，你就可以在命令行中使用自然语言控制你的电脑了！

在你自己的项目中使用

// 1. 安装SDK
// npm install @ui-tars/sdk @ui-tars/operator-nut-js
 
// 2. 导入需要的组件
import { GUIAgent } from '@ui-tars/sdk';
import { NutJSOperator } from '@ui-tars/operator-nut-js';
 
// 3. 创建一个GUI代理实例
const guiAgent = new GUIAgent({
  model: {
    baseURL: "你的模型地址",
    apiKey: "你的API密钥", 
    model: "ui-tars-model"
  },
  operator: new NutJSOperator(),
  onData: (data) => {
    console.log("执行状态：", data)
  }
});
 
// 4. 运行代理执行任务
await guiAgent.run("打开记事本并输入'你好，世界！'");

六、核心组件关系图

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   GUIAgent  │ ──→ │    Model    │ ──→ │  UI-TARS AI  │
└─────┬───────┘      └─────────────┘      └─────────────┘
      │                                           ↑
      ↓                                           │
┌─────────────┐                         ┌─────────────┐
│   Operator  │ ──────────────────────→ │  屏幕截图   │
└─────┬───────┘                         └─────────────┘
      │
      ↓
┌─────────────────────────────────────────────────────┐
│                    电脑操作                         │
│  (点击, 双击, 右键点击, 拖拽, 输入文字, 按快捷键)   │
└─────────────────────────────────────────────────────┘

通过这份简易开发手册，我们理解了UI-TARS如何让我们用自然语言控制电脑。就像有一个小助手在帮我们完成各种电脑操作，只需要用简单的语言告诉它我们想做什么！