TuriX如何看见屏幕macOS Accessibility API构建UI树与截图编号标注详解附源码【免费下载链接】TuriX-CUAThis is the official website for TuriX Computer-use-Agent项目地址: https://gitcode.com/gh_mirrors/tu/TuriX-CUATuriX 是一个完全开源的 macOS 计算机使用AgentComputer-Use-AgentCUA它的眼睛由两条通道组成一条是屏幕截图另一条是通过 macOSAccessibility API辅助功能接口构建的UI元素树。本文带你拆解 TuriX 是如何抓取 UI 树、识别可点击元素、给截图元素打上编号标注并把这些信息一起喂给大模型看懂屏幕的源码路径全部附上方便边读边查。为什么只看截图不够TuriX的双通道视觉设计如果只把截图丢给视觉模型模型必须从像素里猜按钮在哪、叫什么名字——猜错一点就点偏了。TuriX 的做法是双通道输入截图视觉通道模型直接看画面理解图标、图表、排版等像素级信息UI 树结构化通道通过系统级 Accessibility API 拿到每个元素的角色role、标题title、位置、尺寸、可执行动作再给可交互元素分配高亮编号highlight_index并在截图对应位置画出同编号色框。这样模型既能看到画面长什么样又能拿到元素精确在哪。编号就是两者的对齐锚点——模型说出点击 12 号元素Agent 就能精确落到坐标上。第一步连接目标应用拿到UI树的根节点整条链路的入口在 src/mac/tree.py 的MacUITreeBuilder类。每个动作步骤开始时Agent 会调用它的build_tree(pid)方法src/mac/tree.py流程是按进程号连接应用调用 macOS 的AXUIElementCreateApplication(pid)拿到该应用根部的辅助功能元素权限自检读取根节点的AXRole属性做连通性测试。如果系统没有给当前程序授予辅助功能权限会返回kAXErrorAPIDisabled错误日志里会提示去系统设置 ▸ 隐私与安全性 ▸ 辅助功能中授权这也是安装文档 README.zh-CN.md 里授予 macOS 权限一节的原因定位主窗口优先取AXMainWindow属性拿不到时回退到AXWindows列表的第一个窗口记录窗口边界主窗口的位置和尺寸被存入self.app_window后面截图标注时会用它裁剪元素范围。这里有个细节PID 通过模糊匹配运行中的应用名称获得src/controller/service.py 的fuzzy_find_pid所以你可以直接说打开 Safari 搜索…Agent 会自动找到对应进程。第二步递归遍历元素构建 MacElementNode 树拿到窗口后_process_element方法src/mac/tree.py开始深度优先递归每个元素把系统返回的原始 AX 对象转成 src/mac/element.py 中定义的MacElementNode节点。每个节点会记录字段含义role元素角色如AXButton、AXTextField、AXStaticTextattributestitle / value / description / position / size 等属性字典on_screen是否落在屏幕和主窗口可视区域内is_interactive是否可交互下一步讲highlight_index截图上的编号非交互元素为None两个重要的保护性约束深度上限 30 层、子元素上限 250 个max_depth30、max_children250见 src/mac/tree.py防止某些应用的 DOM 深不可测导致遍历爆炸坐标归一化系统返回的绝对像素坐标会被除以屏幕宽高转成 0~1 的相对坐标src/mac/tree.py。这样无论用户用 4K 屏还是普通屏模型看到的坐标体系都一致。还有一个巧思存进节点的边界框会向内收缩 10%x0 0.1*w、w * 0.8见 src/mac/tree.py避免相邻元素的边框在截图上互相粘连、视觉干扰模型判断。第三步识别可点击元素分配高亮编号不是所有元素都值得编号——一段静态文本、一个装饰性分组框点了也没用。_is_interactive方法src/mac/tree.py用动作白名单来判断交互动作AXPress点击、AXShowMenu弹菜单、AXIncrement/AXDecrement步进器、AXConfirm/AXCancel对话框、AXRaise前置窗口、AXSetValue输入框赋值滚动动作AXScrollUpByPage等翻页类动作。元素只要命中白名单且对于按钮/输入框还要求处于已启用状态就标记为可交互同时它必须完整落在主窗口可视区域内才会被分配一个从 0 开始递增的highlight_index并注册进元素缓存_element_cache供后续按编号精确查找src/mac/tree.py。MacElementNode还提供了accessibility_path这类工具src/mac/element.py可以生成类似/AXApplication/AXWindow/AXButton2的唯一路径支持按路径回查元素。第四步截图捕获与智能降采样截图由capture_screenshot完成src/mac/tree.py用 PyAutoGUI 全屏截图按分辨率智能降采样——720p/1080p 不动2K/4K 缩小 2 倍8K 缩小 4 倍用 LANCZOS 重采样。这一步是省 token 的隐形功臣视觉模型的输入成本和延迟都与像素量正相关降采样后画面信息基本无损token 消耗却大幅下降。这也是 TuriX 在 OSWorld 基准上能以64.2% 成功率排到第 3 名src/agent/service.py 的每一步都会把截图和 UI 文本一起送入模型背后的效率优化之一。第五步截图编号标注——色框 数字模型的对齐锚点核心方法annotate_screenshotsrc/mac/tree.py的逻辑非常直白递归遍历 UI 树凡是on_screen且有highlight_index的元素把归一化坐标乘回像素用PIL.ImageDraw画一个彩色矩形边框在框的左上角写上编号数字颜色在 红/蓝/绿/黄/紫 5 色间按编号循环color_palette[number % 5]编号大时颜色也会重复但位置不同边框与数字都会被裁剪到主窗口边界内避免画到桌面其他应用上。标注完成后这张带编号的截图与 UI 文本一起组成模型状态输入。UI 文本的序列化由_get_visible_clickable_elements_stringsrc/mac/element.py生成每行一个元素形如0[:]AXButton title提交 Top left: (0.41, 0.63)(w,h): (0.12, 0.05) 1[:]AXTextField valuesearch... Top left: (0.30, 0.08)(w,h): (0.40, 0.04)编号、角色、标题、相对坐标一目了然。还有一个token 保险丝估算 UI 文本超过约 10000 token 时直接弃用返回空字符串让该步只靠截图工作防止长页面撑爆上下文src/mac/element.py。编号如何变成点击从看见到动手的闭环模型回答点击 12 号元素后编号通过_element_cache反查出归一化坐标交给 src/mac/actions.py 执行。这里的实现同样值得看隐形点击通过 Quartz 的CGEvent直接在目标坐标注入鼠标按下/抬起事件不移动用户当前光标红色光圈反馈点击瞬间用NSWindow在目标位置画一个短暂的红色圆环高亮src/mac/actions.py让用户看得见AI 点了哪文本输入逐字符通过 Unicode 键盘事件注入天然支持中英文混输src/mac/actions.py。整个感知—决策—执行的循环在 src/agent/service.py 的actor_step中编排每步先build_tree 取 UI 文本再连同带编号的截图一起发给 Actor 模型拿到动作后由 Controller 执行若动作是open_app还会立刻重建一次 UI 树src/agent/service.py。实战效果多应用跨窗口的复杂任务UI 树 编号截图的组合让 TuriX 能处理跨越多个应用的任务。下图是一个典型例子读取 Discord 里老板发来的 Numbers 表格生成柱状图插入 PowerPoint 的正确位置再回复消息——全程无需任何应用专属 API在公开基准 OSWorldLinux 桌面环境上这套为 macOS 优化的架构同样拿到了排行榜第 3 名的成绩源码导读按路径索引核心文件模块路径职责UI 树构建器src/mac/tree.py连接 AX API、递归建树、截图与编号标注元素节点src/mac/element.py元素属性、UI 文本序列化、token 预算控制鼠标键盘动作src/mac/actions.py隐形点击、Unicode 输入、滚动与拖拽Agent 主循环src/agent/service.pyBrain/Actor 双模型协作、每步感知编排动作控制器src/controller/service.py解析模型动作、模糊匹配应用 PID运行示例examples/main.py / examples/config.json启动入口与模型配置小结TuriX 的视觉本质是一套结构化感知管线——Accessibility API 提供精确的元素语义与坐标截图提供像素级画面highlight_index编号作为两者的对齐锚点再辅以降采样和 token 预算两道节流阀。这套设计让它在不需要任何应用专用 API 的前提下实现了高成功率的桌面自动化。想动手验证按 README.zh-CN.md 快速开始一节配置好辅助功能权限和模型 API 后运行python examples/main.py即可。【免费下载链接】TuriX-CUAThis is the official website for TuriX Computer-use-Agent项目地址: https://gitcode.com/gh_mirrors/tu/TuriX-CUA创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考