UI-TARS-desktop入门指南：插件开发基础教程

1. UI-TARS-desktop简介

Agent TARS 是一个开源的多模态 AI Agent 框架，致力于通过融合视觉理解（Vision）、图形用户界面操作（GUI Agent）等能力，并与现实世界中的工具链深度集成，探索更接近人类行为模式的任务自动化方式。其设计目标是构建一个能够感知、推理并执行复杂任务的智能体系统。

该框架内置了多种常用工具模块，包括搜索引擎（Search）、浏览器控制（Browser）、文件系统操作（File）、命令行执行（Command）等，开箱即用。开发者可以通过 CLI 快速体验核心功能，也可以基于提供的 SDK 进行二次开发，定制专属的 AI Agent 应用逻辑。

UI-TARS-desktop 是 Agent TARS 的桌面可视化版本，集成了前端交互界面与本地后端服务，极大降低了使用门槛。特别地，该应用预置了Qwen3-4B-Instruct-2507模型，并通过轻量级的 vLLM 推理引擎提供高效稳定的语言生成能力，使得在普通硬件上也能流畅运行大模型驱动的智能代理。

本教程将带你从零开始掌握 UI-TARS-desktop 的基本使用流程，并为后续进行插件开发打下坚实基础。

2. 验证内置Qwen3-4B-Instruct-2507模型是否启动成功

在开始使用 UI-TARS-desktop 前，确保其依赖的大模型服务已正确加载并运行至关重要。以下是验证步骤：

2.1 进入工作目录

首先，打开终端并切换到项目的工作空间目录：

cd /root/workspace

此路径通常为默认部署环境下的项目根目录，包含日志文件、配置脚本及模型服务相关资源。

2.2 查看模型启动日志

执行以下命令查看 LLM 服务的日志输出：

cat llm.log

正常情况下，日志中应包含类似如下信息：

INFO:vLLM: Initializing model with config... INFO:vLLM: Using model: Qwen3-4B-Instruct-2507 INFO:vLLM: Tensor parallel size: 1 INFO:vLLM: Starting engine... INFO:vLLM: Model loaded successfully in 48.2s INFO:API Server: Running on http://0.0.0.0:8000

关键判断依据：

出现Model loaded successfully表示模型加载完成；
API Server: Running on http://0.0.0.0:8000表明 vLLM 提供的 REST API 已就绪，可供前端调用。

若日志中出现CUDA out of memory或Model not found等错误，请检查 GPU 显存是否充足或模型路径配置是否正确。

提示：如需实时监控日志变化，可使用tail -f llm.log命令动态查看输出。

3. 打开UI-TARS-desktop前端界面并验证功能

当模型服务确认运行正常后，即可访问 UI-TARS-desktop 的图形化界面进行功能测试。

3.1 启动前端服务（如未自动启动）

大多数部署环境下，前端服务会随容器或脚本自动启动。若未开启，可在工作目录下运行：

npm run dev

或根据实际部署方式执行对应启动命令（如python app.py或docker-compose up）。默认前端服务监听在http://localhost:3000。

3.2 浏览器访问界面

打开浏览器，输入地址：

http://localhost:3000

你将看到 UI-TARS-desktop 的主界面，包含对话窗口、工具选择区、历史记录面板等组件。

3.3 功能验证：发送一条测试请求

在输入框中输入以下问题：

你好，你能做什么？

点击“发送”按钮后，系统会通过 vLLM 调用 Qwen3-4B-Instruct-2507 模型生成回复。预期响应内容应体现对自身能力的理解，例如提及支持搜索、浏览网页、执行命令等功能。

同时观察页面右下角的状态指示灯：

绿色表示模型服务连接正常；
黄色或红色则提示连接异常，需返回第2节排查日志。

3.4 可视化效果展示

上图为 UI-TARS-desktop 的整体布局，左侧为工具栏，中间为主交互区，右侧可显示上下文信息或执行结果。

上图展示了 Agent 成功解析用户指令并调用内部工具执行任务的过程，如打开浏览器、检索信息等。

上图体现了 GUI Agent 对界面元素的识别与操作能力，可用于自动化表单填写、点击按钮等场景。

4. 插件开发准备：环境与结构概览

UI-TARS-desktop 支持通过插件机制扩展其功能边界。所有插件均位于plugins/目录下，遵循统一的接口规范。

4.1 插件目录结构示例

plugins/ └── my_tool_plugin/ ├── manifest.json # 插件元信息 ├── index.js # 主入口文件 ├── schema.json # 工具调用参数定义 └── utils/ # 辅助函数 └── helper.js

4.2 插件元信息定义（manifest.json）

每个插件必须包含manifest.json文件，用于声明基本信息：

{ "name": "my_tool_plugin", "version": "1.0.0", "description": "A custom plugin for UI-TARS-desktop", "author": "developer", "entrypoint": "index.js", "enabled": true, "permissions": ["file_system", "network"] }

字段说明：

name：插件唯一标识；
entrypoint：加载入口；
permissions：所需权限列表，影响安全策略。

4.3 工具接口定义（schema.json）

用于描述插件对外暴露的功能及其参数格式：

{ "name": "searchFile", "description": "在指定目录中搜索文件", "parameters": { "type": "object", "properties": { "directory": { "type": "string", "description": "搜索目录路径" }, "filename": { "type": "string", "description": "目标文件名" } }, "required": ["directory", "filename"] } }

该定义将被 Agent 用于生成符合规范的函数调用请求。

4.4 实现插件逻辑（index.js）

以下是一个简单的文件搜索插件实现示例：

const fs = require('fs'); const path = require('path'); async function searchFile(args) { const { directory, filename } = args; if (!fs.existsSync(directory)) { return { error: 'Directory does not exist' }; } const results = []; const walk = (currentPath) => { const files = fs.readdirSync(currentPath); for (const file of files) { const filePath = path.join(currentPath, file); const stat = fs.statSync(filePath); if (stat.isDirectory()) { walk(filePath); } else if (file === filename) { results.push(filePath); } } }; try { walk(directory); return { success: true, matches: results.length, paths: results }; } catch (err) { return { error: err.message }; } } module.exports = { searchFile };

保存后重启 UI-TARS-desktop，新插件将在工具列表中出现，并可通过自然语言触发。