Winuse：面向 AI 智能体的跨平台桌面 GUI 自动化工具开源

一名开发者在 Hacker News 发布 Show HN 项目 Winuse，这是一个面向 AI 智能体的跨平台桌面 GUI 自动化库。它使用 Rust 编写核心，并通过统一的 Backend 抽象，分别对接 macOS 的 Accessibility（AX）接口与 Windows 10/11 的 UI Automation（UIA）接口，再以 Python API 与命令行界面（CLI）暴露给上层智能体调用，目标是为桌面端智能体提供结构化、稳定的元素选择器与 JSON 化的工具返回结果。

核心架构与平台要求

Winuse 的开发模型要求：

• macOS 15.2 或更高版本，终端或 Python 宿主进程需开启「辅助功能」权限；若使用截图功能，还需授予「屏幕录制」权限。
• Windows 10 或 11 上 UI Automation 与可见区域截图无需额外权限，但需注意 UIPI（用户界面特权隔离）会拦截向更高完整性级别应用的输入，应在与目标应用相同完整性级别下运行；安全桌面窗口不受支持。

构建方面，Python 绑定通过 maturin develop 完成开发安装，测试使用 pytest；CLI 可通过 cargo build --release -p winuse-cli 构建。

Python API 与异步等待

Python 接口以语义化选择器（role + name）定位元素，而非长期持有原生句柄——每次操作都会基于最新的无障碍快照重新解析目标，从而避免因 UI 重绘或窗口状态变化导致的句柄失效问题。典型能力包括：

• 窗口控制：activate、minimize、restore、maximize、close，以及 enumerate 所有真实窗口。
• 元素操作：fill（替换文本）、type_text（插入文本，不替换）、press（按键，支持 modifiers，如 cmd+s 等同于 Windows 上的 Ctrl+s）、click（含双击与悬停）。
• 拖拽与导航：通过 drag_to 在 list-item 之间拖拽，可基于 snapshot 提取子树文本以辅助智能体理解 UI 结构。
• 异步等待：find().wait_until("enabled"/"text", timeout=...) 替代轮询，可等待按钮变可用或文本变为指定值后再执行后续动作。
• 剪贴板与系统集成：clipboard_write/clipboard_read 支持文本、文件、图像多种类型，可将图像剪贴板导出为 PNG 文件。
• 监控变化：watch(interval=0.25) 可监听列表等容器的语义化新增与移除事件。
• 属性检查：inspect() 在 macOS 上暴露全部 AX 属性，在 Windows 上暴露 UIA 属性（name、automation id、class name、value、patterns 等）。
• 元素截图：screenshot(path, padding) 返回 PNG 字节并落盘，捕获范围为元素当前可见区域（包括覆盖在其上的窗口）。

CLI 与 Agent Skill 分发

Winuse CLI 同样面向智能体调用，统一返回 JSON 信封，便于模型解析。常用命令包括：

• winuse doctor：诊断平台无障碍后端是否可用。
• winuse windows：枚举所有窗口。
• winuse snapshot --window <id>：输出指定窗口的可访问性快照。
• winuse click/fill/press/scroll 等：以 --window、--role、--name 参数定位元素并执行动作。

项目附带可分发的「Agent Skill」（位于 skills/winuse），包含 SKILL.md、引用文档与宿主二进制；可通过 make install 安装到 ~/.agents/skills/winuse，或用 make package 打 zip 包（包含三个平台的二进制），便于集成到不同操作系统的智能体环境中。

设计理念与致谢

Winuse 的设计明显参考并致谢了 Vercel Labs 的 agent-browser：均采用「以稳定的语义选择器驱动 UI、对外输出 JSON 工具响应」的思路，但将目标从浏览器扩展到了 macOS 与 Windows 的原生桌面应用，使智能体能够跨桌面端进行结构化操作，而非依赖不可靠的像素坐标或图像识别。