UI-TARS Desktop Preset（预设）导入与管理指南：本地 YAML 与远程 URL 的配置分发机制

本文围绕 docs/preset.md 展开，讲解 UI-TARS Desktop 中 Preset（预设）的核心概念与使用方式：如何把一组完整的设置（VLM 模型、对话参数、报告上传地址等）打包成 YAML 文件，通过本地文件或远程 URL 一键导入，并借助"远程 + 自动更新"实现团队级、组织级的配置统一分发。读完本文，你将掌握 Preset 文件格式、导入操作步骤、内置校验规则与自动同步原理，并能在 UI-TARS Desktop 中独立落地一套可复用的配置模板。

一、什么是 Preset：一组可分发、可复用的设置集合

Preset（预设）本质上是一组 设置项 的集合，用于把 VLM Provider、Base URL、API Key、模型名称、语言、对话轮次上限、报告上传地址等配置打包成一份 YAML，导入后一次性应用到桌面客户端。这一能力由社区以 PR 形式引入到 UI-TARS Desktop，设计目标就是让"配置"能够像文件一样被复制、传递、托管与同步，从而替代繁琐的逐项手工填写。

一个关键前提需要先说明：目前 UI-TARS Desktop 自身并不提供服务端能力，因此官方没有为开源社区维护一套云端 Preset 库，而是欢迎社区开发者将自建模板贡献到 examples/presets 目录（仓库内已放置一份 default.yaml 作为参考模板）。这意味着你要么使用社区已有模板，要么按本文第四节的字段规范自己编写。

UI-TARS Desktop 支持 两种预设来源，其差异决定了后续的更新模式：

graph TD
    A[Import Preset] --> B{Preset Type}
    B -->|File| C[YAML File]
    B -->|URL| D[URL Endpoint]
    C --> E[Manual Updates 🔧]
    D --> F[Auto Sync ⚡]

• 文件（File）：选择本地 .yaml/.yml 文件导入，导入成功后设置即时生效，之后由你手动维护与再次导入；
• URL（远程端点）：填入远程 YAML 的地址，可开启"启动时自动更新"，此后每次应用启动都会重新拉取远程最新配置。

本地预设与远程预设能力对比

特性	本地预设（Local Presets）	远程预设（Remote Presets）
存储位置	设备本地	云端托管
更新机制	手动	自动
访问控制	可读 / 可写	只读
版本管理	手动	与 Git 集成

从上表可以清晰看出两条预设路线的定位差异：本地预设适合个人快速试验与微调；远程预设则因为"只读 + 自动同步 + Git 版本管理"，天然适合团队统一分发 vlmBaseUrl、reportStorageBaseUrl 这类需要全员对齐的公共配置。

二、导入入口：Settings 界面中的 Import Preset 弹窗

两种导入方式共用一个 UI 入口。在 Settings → Preset 区域点击导入按钮后，会弹出 Import Preset 对话框，内含 Local File 与 Remote URL 两个页签，这一交互在渲染层由 PresetImport.tsx 实现。

从源码结构看，该组件通过 Tabs 组织两种来源（defaultValue="local"），并将导入动作统一委托给 useSetting hook 暴露的两个方法：importPresetFromText(yamlText) 与 importPresetFromUrl(url, autoUpdate)。无论走哪条路径，底层都归结为"把一段 YAML 文本解析、校验后写回设置存储"。

三、从本地文件导入预设

3.1 操作步骤

1. 打开 Settings，进入 Preset 管理区域；
2. 点击 Import，在弹出的对话框选择 Local File 页签；
3. 点击 Choose File，选择本地 .yaml 或 .yml 文件；
4. 文件解析成功后，设置会被自动更新并弹出成功提示。

前端在选择文件后，会通过 FileReader 读取为纯文本，再调用 importPresetFromText。源码中还限定了文件选择器的 accept=".yaml,.yml"（见 PresetImport.tsx#L92-L98），说明预设文件目前仅支持 YAML 格式。

若文件内容不合法（例如必填字段缺失、URL 格式错误、YAML 语法损坏），导入会失败并弹出错误提示，而已有的设置不会被破坏：

3.2 源码链路：从文本到生效的完整调用链

本地文件导入在代码层面走的是"渲染进程 → IPC → 主进程 Store"的链路：

1. 渲染进程：PresetImport 读取文件文本后调用 importPresetFromText（PresetImport.tsx#L35-L56）；
2. IPC 通道：主进程注册了 setting:importPresetFromText 处理器（services/settings.ts#L42-L50），其中先调用 SettingStore.importPresetFromText 拿到校验后的新设置，再整体写回存储；
3. 解析与校验：setting.ts#L144-L148 中的 parsePresetYaml 先用 yaml.load 将 YAML 解析为对象，再交由 validatePreset 做类型约束；
4. 持久化与通知：SettingStore.setStore 写入基于 electron-store 的 ui_tars.setting 持久化文件，同时通过 onDidAnyChange 向所有窗口广播 setting-updated 事件，界面即时刷新（setting.ts#L45-L53）。

四、从 URL 导入远程预设与自动更新

4.1 操作步骤

1. 打开 Settings → Preset，点击 Import；
2. 切换到 Remote URL 页签；
3. 输入远程 YAML 地址（例如 https://example.com/preset.yaml）；
4. 按需开关 Auto update on startup（源码中该开关默认值为 true，见 PresetImport.tsx#L31）；
5. 点击 Import，远程内容会立即被拉取并应用。

4.2 自动更新机制的源码级原理

远程预设之所以能"启动即自动同步"，在于主进程同时记录了一份导入元数据 presetSource。查看 services/settings.ts#L55-L71 可以发现，URL 导入成功后会额外写入：

presetSource: {
  type: 'remote',
  url: <远程地址>,
  autoUpdate: <是否自动更新>,
  lastUpdated: <导入时间戳>
}

这份元数据是后续自动更新的"遥控器"：在应用启动阶段，main.ts#L151-L160 会检查 presetSource?.type === 'remote' && presetSource.autoUpdate，若满足条件则再次调用 importPresetFromUrl(url, true) 拉取最新内容覆盖本地设置。也就是说：

• autoUpdate 开启：每次启动自动拉取最新远程配置（适用于集中管理，本地不可改）；
• autoUpdate 关闭：仅首次导入生效，之后以本地状态为准。

如果你希望"回到手工配置"或清除远程预设来源，可通过 services/settings.ts#L28-L30 注册的 setting:resetPreset 通道删除 presetSource 实现重置。远程获取的 YAML 同样会经过 yaml.load + validatePreset 的完整校验（setting.ts#L132-L141），拉取到的内容不合法时导入会被整体拒绝。

五、Preset YAML 字段规范与内置校验

仓库中的参考模板位于 examples/presets/default.yaml，其完整内容如下：

name: UI TARS Desktop Example Preset
language: en
vlmProvider: Hugging Face for UI-TARS-1.5
vlmBaseUrl: https://your-endpoint.huggingface.cloud/v1
vlmApiKey: your_api_key
vlmModelName: your_model_name
reportStorageBaseUrl: https://your-report-storage-endpoint.com/upload
utioBaseUrl: https://your-utio-endpoint.com/collect

docs/preset.md 示例中仅展示了 vlmProvider、vlmBaseUrl、vlmApiKey、vlmModelName、reportStorageBaseUrl、utioBaseUrl 与可选的 language、name 字段；完整可用的字段范围请以 setting.md 的参数说明与下方校验 Schema 为准。

5.1 字段清单与取值范围

Preset 允许携带的字段由 validate.ts#L16-L36 的 PresetSchema 定义，它同时充当了"配置契约"：

字段	类型 / 取值范围	是否必填	说明
vlmProvider	见下方 Provider 枚举	否（导入后通常由设置补齐）	选择后端 VLM Provider，用于 GUI 动作执行的准确性
vlmBaseUrl	string，须为合法 URL	是	VLM 请求的 Base URL，需为 OpenAI 兼容接口
vlmApiKey	string，长度 ≥ 1	是	VLM 访问密钥
vlmModelName	string，长度 ≥ 1	是	实际请求的模型名
useResponsesApi	boolean	否	支持 Responses API 时开启，可降低 token 消耗、提升响应速度
operator	枚举，见下方 Operator 列表	是（Schema 中不可缺省）	指定使用的操作器类型
language	zh / en	否（默认 en）	仅影响 VLM 输出语言，不影响 App 界面语言
screenshotScale	number，范围 [0.1, 1]	否	截图缩放比例
maxLoopCount	number，范围 [25, 200]	否（默认 100）	每轮对话的最大循环步数
loopIntervalInMs	number，范围 [0, 3000]	否（默认 1000）	每轮循环的等待时间（截图前的延迟，保证终态被记录）
searchEngineForBrowser	google / bing / baidu	否（默认 google）	本地浏览器操作器的搜索引擎
reportStorageBaseUrl	string，须为合法 URL	否	报告上传服务地址，未设置时"Export as HTML"直接下载报告
utioBaseUrl	string，须为合法 URL	否	UTIO（UI-TARS Insights and Observation）事件采集服务地址
presetSource	{type: 'local'|'remote', url?, autoUpdate?, lastUpdated?}	否	内部维护的预设来源元数据，由应用写入，一般不手工出现在预设文件中

5.2 枚举值参考（来自 types.ts）

VLM Provider（types.ts#L44-L49）：

enum VLMProviderV2 {
  ui_tars_1_0 = 'Hugging Face for UI-TARS-1.0',
  ui_tars_1_5 = 'Hugging Face for UI-TARS-1.5',
  doubao_1_5 = 'VolcEngine Ark for Doubao-1.5-UI-TARS',
  doubao_1_5_vl = 'VolcEngine Ark for Doubao-1.5-thinking-vision-pro',
}

Search Engine（types.ts#L51-L55）：google、baidu、bing（与设置界面展示的 Google、Bing、Baidu 一一对应）。

Operator（types.ts#L57-L62）：Local Computer Operator、Local Browser Operator、Remote Computer Operator、Remote Browser Operator（对应枚举 LocalComputer / LocalBrowser / RemoteComputer / RemoteBrowser）。

5.3 校验如何生效：zod 严格校验

与"尽力解析"不同，Preset 导入采用 zod Schema 严格校验：validate.ts#L41-L43 的 validatePreset 直接对整份解析结果执行 PresetSchema.parse。这意味着：

• vlmBaseUrl、utioBaseUrl 等 URL 字段必须是合法 URL；
• vlmApiKey、vlmModelName 不允许为空字符串；
• 数值字段存在边界约束（如 maxLoopCount 只能落在 25~200）；
• 一旦校验不通过，parse 抛出异常，导入流程在写入前中断，避免半生效的脏配置。

值得注意的是 Schema 中 operator 被标记为不可缺省字段，而官方示例为了可读性只保留了最小字段集，因此建议在编写可导入的正式模板时，尽量包含上表全部字段，或参考 docs/setting.md 中每个参数的默认值，让预设在任何环境下都能行为一致。

5.4 从 Provider 看预设典型应用

综合 setting.md 给出的两套真实参数示例，可以拼出最常见的两种预设形态：

• Hugging Face 部署的 UI-TARS-1.5：vlmProvider: Hugging Face for UI-TARS-1.5，vlmModelName 使用 tgi，vlmApiKey 为 hf_xxx 形式；
• 火山引擎方舟上的 Doubao-1.5-UI-TARS：vlmProvider: VolcEngine Ark for Doubao-1.5-UI-TARS，vlmBaseUrl: https://ark.cn-beijing.volces.com/api/v3，vlmModelName: doubao-1.5-ui-tars-250328，language: cn。

团队若希望所有成员统一走某一套模型与上报通道，把上述参数固化成一份远程 YAML 并开启 autoUpdate，即可实现"一份模板、全员同步"。

六、与 Report / UTIO 设置的关系：预设只是"承载分发"

reportStorageBaseUrl 与 utioBaseUrl 之所以会出现在预设字段中，是因为它们的语义天然适合集中分发：

• Report Storage Base URL：设置后，点击 Export as HTML（Share） 时报告会上传至该服务并返回可公开访问的链接；未设置时则直接触发本地下载。
• UTIO Base URL：指定 UTIO（UI-TARS Insights and Observation）事件采集端点，应用会以 application/json POST 应用启动、发送指令、分享报告三类事件（appLaunched / sendInstruction / shareReport），服务端接口约定与示例代码可参见 docs/setting.md。

这两个字段写入预设文件的意义在于：使用者无需理解上报接口细节，只要导入预设，分享与统计通道即自动指向正确服务。这也从侧面说明，Preset 的价值并不止于"填好 VLM 参数"，而是把围绕 UI-TARS Desktop 的一整套环境约定（模型、上报、语言、算子）标准化。

七、编写与使用 Preset 的实践建议

综合文档与源码，给出几条可直接落地的建议：

1. 本地模板先行：在 Settings 中手工配置一遍并验证模型可用（可使用 Check Model Availability 按钮），再将关键参数整理成 YAML 模板，避免"参数错误被导入"带来的排查成本。
2. 团队场景走远程 + autoUpdate：将 vlmBaseUrl、reportStorageBaseUrl、utioBaseUrl 等公共参数托管到 Git 仓库（对应表格中"与 Git 集成"的版本管理优势），开启自动更新即可获得集中式配置下发的效果。
3. 留意字段完整性：导入内容会经过 zod 严格校验（validate.ts），URL 合法性与数值边界不满足会直接报错，模板应尽量完整、字段值应符合上表取值范围。
4. 社区共享：如果你打磨出一份通用性较强的模板，可参考 examples/presets/default.yaml 的写法，将你的预设贡献到 examples/presets 目录供社区使用。
5. 恢复手段：若想摆脱远程预设的接管，可在设置中重置 preset 来源（对应主进程 setting:resetPreset 通道删除 presetSource 元数据），回到手工编辑模式。

八、小结

Preset 是 UI-TARS Desktop 中"配置工程化"的载体：它把散落在设置页中的 VLM、对话、算子、报告与遥测参数收敛为一份 YAML，并借助文件导入（手动维护）与 URL 导入（启动自动同步）两条通道，覆盖从个人自定义到团队集中分发的全部场景。在实现层面，它由渲染层的 PresetImport.tsx、主进程 IPC 服务 services/settings.ts、持久化与解析逻辑 setting.ts 以及 zod 校验契约 validate.ts 共同支撑，任何一个环节都可以在仓库中对照研读。想要进一步了解每个配置项的行为差异，可继续阅读 docs/setting.md。