TuriX-CUA：开源AI桌面自动化工具，模拟人类操作完成复杂桌面任务

一、TuriX-CUA是什么

TuriX-CUA全称为TuriX Computer Use Agent，是一款开源的AI驱动型桌面自动化代理，其核心目标是让人工智能模型能够像人类一样，在桌面操作系统（覆盖macOS 15、Windows 11主流版本）中完成各类交互操作，无需依赖任何应用程序的专属API接口。区别于传统的桌面自动化工具（如按键精灵、AutoHotkey），TuriX-CUA以视觉语言模型（VLM）为核心驱动力，能够理解自然语言指令，并通过解析桌面UI元素、屏幕截图等视觉信息，自主决策并执行点击、输入、滚动、快捷键操作等行为，实现端到端的任务闭环。

该项目定位为“面向开发者与研究者的桌面自动化基础设施”，100%开源且个人/研究使用免费，旨在降低AI驱动桌面操作的开发门槛，同时提供生产级的代理能力——内部测试数据显示，其在macOS平台的任务成功率超过68%，相较UI-TARS等同类开源代理，在成功率和执行速度上均具备显著优势。

二、功能特色

TuriX-CUA的核心优势集中在“无依赖、高适配、易扩展、跨平台”四大维度，具体功能特色可通过下表清晰呈现：

三、技术细节

1. 整体架构设计

TuriX-CUA的代码结构遵循“高内聚、低耦合”原则，核心模块分工明确，便于开发者理解和二次开发，整体目录结构如下：

TuriX-CUA/
├── src/           # 核心源码目录
│  ├── agent/        # AI代理核心逻辑层
│  │  ├── service.py    # 代理任务编排、历史记录管理、任务状态控制
│  │  ├── prompts.py    # 系统提示词模板（定义代理行为规则、输出格式约束）
│  │  ├── structured_llm.py # LLM结构化输出解析（ActionItem等数据模型定义）
│  │  ├── views.py     # 代理历史记录的数据模型与序列化逻辑
│  ├── controller/     # 动作执行与注册中心
│  │  ├── service.py    # 动作执行调度、参数校验、权限检查
│  │  ├── registry/    # 动作注册器（装饰器注册、动作索引管理）
│  ├── mac/         # macOS专属交互层
│  │  ├── actions.py    # 底层操作实现（点击、输入、滚动、UI元素定位）
│  │  ├── tree.py     # UI树构建、可访问性元素解析
│  │  ├── element.py    # macOS UI元素建模（坐标、类型、文本内容）
│  ├── windows/       # Windows专属交互层（与mac模块逻辑对称）
│  │  ├── actions.py    # Windows底层操作实现
│  │  ├── tree.py     # Windows UI树解析
│  │  ├── element.py    # Windows UI元素建模
│  ├── utils.py       # 通用工具函数（截图、权限检测、配置解析）
├── examples/        # 示例与配置目录
│  ├── config.json     # 模型配置、代理参数（步数限制、任务指令等）
│  ├── main.py       # 项目运行入口（配置加载、权限检查、代理启动）
│  ├── demo_scripts/    # 场景化Demo脚本（商旅预订、办公自动化等）
├── tests/          # 单元测试与集成测试目录
│  ├── test_agent.py    # 代理逻辑测试
│  ├── test_controller.py  # 动作执行测试
│  ├── test_cross_platform.py # 跨平台兼容性测试
├── docs/          # 文档目录（使用说明、开发指南、FAQ）
├── LICENSE         # MIT许可证文件
├── requirements.txt     # 依赖包清单
└── README.md        # 项目核心说明

2. 核心工作流程

TuriX-CUA的任务执行遵循“指令解析→环境感知→动作决策→执行反馈→闭环判断”的逻辑，具体步骤如下：

步骤1：配置加载与权限校验

启动项目时，首先读取examples/config.json中的配置项，包括：

• LLM模型参数（模型地址、API密钥、温度值、最大生成长度）；

• 代理参数（任务指令、最大执行步数、是否记录操作日志、截图保存路径）；

• 系统参数（目标操作系统、权限检测开关）。

同时自动校验系统级权限：

• macOS：检查“辅助功能”“屏幕录制”权限是否开启（无权限则弹窗引导用户开启）；

• Windows：检查“辅助功能权限”“文件读写权限”是否充足。

步骤2：代理初始化

初始化核心组件：

• LLM实例：根据配置加载指定的视觉语言模型（如Qwen3-VL）；

• 控制器：加载动作注册中心，初始化所有可用的基础动作；

• Agent核心：整合LLM、控制器、系统交互层，建立任务执行上下文。

步骤3：环境感知与指令解析

Agent接收自然语言指令后，首先触发屏幕截图，将截图信息与指令一起传入LLM，LLM完成：

• 指令意图解析（如“预订明天从北京到上海的机票”）；

• 桌面UI环境感知（识别当前活跃窗口、关键UI元素位置与类型）；

• 第一步动作决策（如“打开浏览器，点击地址栏，输入携程网址”）。

步骤4：动作执行与反馈

控制器根据LLM输出的结构化动作指令（ActionItem），调用对应系统的底层动作函数（如macOS的click()、Windows的type_text()），执行后返回执行结果（成功/失败、当前界面截图），Agent将结果反馈给LLM，作为下一步决策的依据。

步骤5：闭环判断

重复“环境感知→动作决策→执行反馈”流程，直到满足以下任一条件：

• 任务完成（LLM判定指令目标达成）；

• 达到最大执行步数（避免无限循环）；

• 执行失败且无法恢复（如关键UI元素未找到）。

3. 关键技术亮点

（1）UI元素解析技术

针对macOS和Windows的不同UI架构，分别实现了UI树构建逻辑：

• macOS：基于系统的“可访问性API”解析UI元素，获取元素的坐标、类型、文本、父/子元素关系，构建结构化UI树；

• Windows：基于UIAutomation框架解析UI元素，兼容传统Win32窗口和现代UWP应用。

该技术让Agent能够精准定位目标元素，而非单纯依赖坐标点击，提升了操作的稳定性。

（2）模型热插拔实现

通过统一的LLM抽象接口，屏蔽不同模型的调用差异：

• 定义BaseVLM抽象类，规定generate()（生成动作指令）、parse_output()（解析输出）等核心方法；

• 不同模型（如Qwen3-VL、GPT-4V）只需实现该抽象类，在config.json中指定模型类名即可加载，无需修改Agent核心逻辑。

（3）MCP协议对接

兼容Model Context Protocol协议，可将部分复杂逻辑（如自然语言转结构化查询、多轮对话记忆）交由外部代理（如Claude）处理，本地Agent仅负责执行具体操作，实现“决策-执行”分离，提升复杂任务的处理能力。

四、应用场景

TuriX-CUA的无API依赖、跨平台特性使其覆盖多类桌面自动化场景，以下是典型应用场景及具体实现方式：

1. 商旅自动化

核心需求

自动完成机票、酒店、网约车预订，行程信息整理与同步。

执行流程

1. 接收指令：“预订明天（2026-01-06）从北京到上海的经济舱机票，优先国航，晚6点后起飞；预订上海外滩附近的三星级酒店，含早餐；预约明天10点从家到机场的网约车”；

2. 操作步骤：

• 打开浏览器→输入携程网址→登录账号→机票模块检索符合条件的航班→选择并下单；

• 切换至酒店模块→定位上海外滩→筛选三星级、含早餐→预订；

• 打开网约车APP→输入起点（家）、终点（机场）、时间（10点）→确认预约；

• 新建文档→记录航班、酒店、网约车信息→发送至指定邮箱。

价值

替代人工完成重复性高、流程固定的商旅预订工作，减少操作失误，节省1-2小时/次的人工耗时。

2. 办公自动化

场景1：跨应用数据整理与汇报

核心需求

查询iPhone 16最新官方价格→创建Pages/Word文档记录价格信息→生成价格对比图表→插入PPT→发送给指定联系人。

执行流程

• 打开浏览器→访问苹果官网→检索iPhone 16价格→提取数据；

• 打开Pages/Word→创建文档→录入价格信息并保存；

• 打开Numbers/Excel→制作历代iPhone价格对比表→生成柱状图；

• 打开Keynote/PowerPoint→插入图表→保存PPT；

• 打开微信/飞书→找到指定联系人→发送文档和PPT。

场景2：社交/办公软件信息处理

核心需求

从Discord/企业微信接收Numbers/Excel文件→提取数据生成图表→插入PPT→回复发送方并抄送老板。

执行流程

• 监测指定聊天窗口→识别新接收的文件→下载并打开；

• 解析文件数据→生成可视化图表；

• 插入PPT并格式化→保存文件；

• 回复发送方“数据已处理，图表见附件”→抄送老板。

3. 跨平台通用操作

核心需求

Windows系统下自动完成YouTube视频搜索、点赞、评论；macOS系统下自动整理桌面文件、分类归档。

执行流程（以Windows YouTube操作为例）

• 打开Chrome浏览器→输入YouTube网址→登录账号；

• 搜索指定关键词（如“AI桌面自动化教程”）；

• 选择第一个视频→点击播放→点击点赞按钮；

• 输入指定评论内容→发布评论。

4. 定制化业务场景

开发者可通过注册自定义动作，适配小众/行业专属场景：

• 财务场景：自动打开财务软件→录入报销数据→生成报销单→提交审批；

• 客服场景：自动打开客服后台→检索用户问题→匹配标准答案→回复用户；

• 教育场景：自动打开学习平台→完成课程签到→播放指定课程→记录学习时长。

五、使用方法

1. 环境准备

（1）硬件要求

• CPU：Intel i5/AMD Ryzen 5及以上；

• 内存：8GB及以上（推荐16GB，模型推理更流畅）；

• 存储：10GB及以上可用空间（含依赖包、模型缓存、日志文件）；

• 系统：macOS 15（Ventura及以上）、Windows 11（22H2及以上）。

（2）软件要求

• Python版本：3.12+（推荐3.12.0，兼容所有依赖包）；

• 依赖包：通过requirements.txt安装，核心依赖包括pyautogui（桌面操作）、pillow（截图处理）、requests（模型调用）、pydantic（数据校验）、pyobjc（macOS API对接）、pywin32（Windows API对接）等。

2. 安装步骤

步骤1：克隆仓库

git clone https://github.com/TuriX-AI/TuriX-CUA.git
cd TuriX-CUA

步骤2：创建虚拟环境（推荐）

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate

步骤3：安装依赖

pip install -r requirements.txt

步骤4：配置系统权限

• macOS：

1. 打开“系统设置→隐私与安全性→辅助功能”；

2. 勾选终端/VS Code（运行项目的程序）；

3. 同样路径下打开“屏幕录制”，勾选上述程序。

• Windows：

1. 打开“设置→辅助功能→键盘”；

2. 开启“允许使用快捷键启动辅助功能”；

3. 以管理员身份运行终端/VS Code。

3. 配置修改

打开examples/config.json，根据需求修改核心配置项：

{
 "llm": {
  "model_name": "qwen3-vl", // 选择使用的模型（如gpt-4v、qwen3-vl）
  "api_base": "https://api.turix.ai/v1", // 模型API地址
  "api_key": "your-api-key", // 替换为自己的API密钥
  "temperature": 0.1, // 模型温度（越低越稳定）
  "max_tokens": 2048 // 最大生成令牌数
 },
 "agent": {
  "task_instruction": "预订明天从北京到上海的经济舱机票", // 任务指令
  "max_steps": 50, // 最大执行步数
  "save_history": true, // 是否保存操作历史
  "screenshot_path": "./screenshots" // 截图保存路径
 },
 "system": {
  "os_type": "macos", // 目标系统（macos/windows）
  "check_permission": true // 是否开启权限校验
 }
}

4. 运行项目

cd examples
python main.py

运行后，项目会自动完成权限校验→代理初始化→任务执行，所有操作日志和截图会保存在指定路径，执行完成后输出任务结果（成功/失败）及执行总结。

5. 自定义动作（进阶）

若需新增自定义动作（如“发送邮件”），步骤如下：

步骤1：在对应系统目录下编写动作函数

以macOS为例，编辑src/mac/actions.py：

from src.controller.registry import register_action

@register_action(name="send_email", desc="发送邮件，参数：recipient（收件人）、subject（主题）、content（内容）")
def send_email(recipient: str, subject: str, content: str) -> bool:
  """
  实现macOS下发送邮件的逻辑
  """
  # 打开邮件应用→新建邮件→填写收件人/主题/内容→发送
  try:
    # 具体实现代码
    return True
  except Exception as e:
    print(f"发送邮件失败：{e}")
    return False

步骤2：重启项目，在指令中调用该动作

修改config.json的task_instruction为：“发送邮件给contact@turix.ai，主题为‘测试邮件’，内容为‘TuriX-CUA测试’”，运行后Agent会自动调用新增的send_email动作。

六、常见问题解答（FAQ）

Q1：运行项目时提示“权限不足”怎么办？

A：不同系统的权限解决方式如下：

• macOS：

1. 确认“辅助功能”和“屏幕录制”权限已勾选运行项目的程序；

2. 若仍提示权限不足，关闭程序后重新开启权限，重启电脑；

3. 避免使用远程桌面运行项目（远程桌面会限制屏幕录制权限）。

• Windows：

1. 以管理员身份运行终端/VS Code；

2. 确认“UIAutomation”相关服务已开启（运行services.msc，检查“UI Automation Service”状态）；

3. 关闭杀毒软件（部分杀毒软件会拦截系统级操作）。

Q2：Agent执行动作时点击位置不准确怎么办？

A：该问题多因UI元素解析偏差导致，可通过以下方式优化：

1. 提高屏幕分辨率（推荐1920×1080及以上），降低缩放比例（macOS/Windows均设置为100%）；

2. 编辑src/[macos/windows]/tree.py，调整UI元素识别的阈值（如文本匹配相似度从0.8提升至0.9）；

3. 若为固定坐标点击需求，可在动作函数中直接指定坐标（不推荐，兼容性差）。

Q3：如何切换底层模型（如从Qwen3-VL换成GPT-4V）？

A：仅需修改config.json的llm配置：

{
 "llm": {
  "model_name": "gpt-4v",
  "api_base": "https://api.openai.com/v1",
  "api_key": "your-openai-api-key",
  "temperature": 0.1,
  "max_tokens": 2048
 }
}

无需修改任何代码，重启项目即可加载新模型。

Q4：任务执行步数达到上限但任务未完成怎么办？

A：可分两步处理：

1. 临时解决方案：修改config.json的max_steps为更大的值（如100），重新运行；

2. 长期优化：查看操作日志，分析步数消耗在哪些无效动作（如重复点击同一元素），优化提示词或调整模型温度（降低温度减少随机决策）。

Q5：Windows系统下部分应用（如UWP应用）无法识别UI元素怎么办？

A：Windows下UWP应用的UI解析需要额外配置：

1. 安装pywinauto扩展包：pip install pywinauto[UIA]；

2. 编辑src/windows/tree.py，将UI解析方式切换为UIA模式：

   from pywinauto import Application
   app = Application(backend="uia").connect(title="目标应用")

3. 重新运行项目，即可解析UWP应用的UI元素。

Q6：项目支持中文指令吗？

A：完全支持。TuriX-CUA的默认提示词和模型对接逻辑已适配中文，可直接输入中文任务指令（如“整理桌面文件，按类型分类到不同文件夹”），模型能精准解析意图并执行。

Q7：商业使用需要付费吗？

A：TuriX-CUA采用MIT许可证，商业使用无需向项目方付费，但需遵守以下条款：

1. 保留原始版权声明；

2. 不得将项目声称为本公司原创；

3. 商业使用产生的风险由使用者自行承担。

七、相关链接

1. 项目仓库地址：https://github.com/TuriX-AI/TuriX-CUA

八、总结

TuriX-CUA作为一款开源的AI驱动桌面自动化代理，以无应用API依赖、跨平台适配、模型热插拔为核心优势，依托视觉语言模型实现了模拟人类操作的桌面任务自动化，其清晰的代码架构降低了开发者二次开发的门槛，丰富的基础动作和自定义能力可覆盖商旅预订、办公自动化、跨平台通用操作等多类场景，同时遵循MIT许可证保障了使用的自由度，是一款兼顾易用性和扩展性的桌面自动化基础设施，能够有效替代人工完成重复性桌面操作，提升办公与开发效率。