cua-auto 跨平台 GUI 自动化库实战指南pyautogui 风格的鼠标、键盘、屏幕、窗口、剪贴板与 Shell/PTY 操作【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cuacua-auto是 cua 项目中一个轻量级、跨平台Windows / macOS / Linux的桌面自动化库提供同步、MIT 许可、pyautogui 风格的 Python API覆盖鼠标、键盘、屏幕、窗口、剪贴板与 Shell 命令六大类操作。本文以 README 为骨架结合仓库源码逐模块拆解其全部公开接口、参数语义与平台适配细节读完即可用它在本地桌面环境或 computer-use Agent 中快速搭建 GUI 自动化脚本。cua-auto 是什么从 pyproject.toml 可以看到cua-auto版本 0.1.2定位为 Cross-platform automation library — mouse, keyboard, screen, window, clipboard, shell关键字包含automation、computer-use、pyautogui要求 Python 3.11,3.14。它把四层底层能力封装成一组简洁的顶层函数底层依赖版本要求负责的能力pynput1.7.0鼠标与键盘输入控制pillow10.0.0截图与图像处理pyperclip1.9.0剪贴板读写pywinctl0.4窗口管理与 pyautogui 相比cua-auto 更强调轻量 可裁剪核心依赖只有四个且所有模块按需导入、可独立使用屏幕截图在跨平台与高分屏Retina / HiDPI场景下做了专门的坐标归一化处理详见下文屏幕捕获一节这使它特别适合作为 computer-use Agent 的底层动作原语。安装与依赖组cua-auto使用 hatchling 构建requires-python为3.11,3.14额外提供了三组可选依赖extras可在 pyproject.toml 中查看mssmss9.0.0更快的多显示器截图后端在 PIL.ImageGrab 不可用的 Linux / 多屏环境下作为回退方案windowspywin32306Windows 专属能力如通过 win32gui 获取光标位置DPI 下更可靠ptypywinpty2.0.0Windows 上的 PTY 伪终端支持all一次安装上述全部 extrasdevpytest / pytest-asyncio / ruff用于开发与测试。按需安装示例# 最小安装鼠标、键盘、屏幕、窗口、剪贴板、Shell pip install cua-auto # 完整安装含 mss 截图后端、Windows win32 扩展与 PTY 支持 pip install cua-auto[all]注意mss、windows、pty属于可选依赖。若跳过mss在 Linux 上截图、或跳过windows在 Windows 上使用screen.cursor_position()的 win32 加速路径代码会自动回退到通用实现详见后文但回退能力与可靠性会有所差异。快速上手以下完整示例直接继承自 README 并加上了返回值说明涵盖了库的全部六个顶层模块import cua_auto.mouse as mouse import cua_auto.keyboard as keyboard import cua_auto.screen as screen import cua_auto.window as window import cua_auto.clipboard as clipboard import cua_auto.shell as shell # ── Mouse ────────────────────────────────────────────── mouse.click(100, 200) # 左键单击 mouse.right_click(100, 200) # 右键单击 mouse.double_click(100, 200) # 左键双击 mouse.move_to(500, 300) # 移动到 (500, 300) mouse.mouse_down(100, 200) # 在 (100, 200) 按住左键 mouse.mouse_up(100, 200) # 在 (100, 200) 松开左键 mouse.drag(100, 200, 400, 500) # 从 (100,200) 拖到 (400,500) mouse.scroll_up(3) # 向上滚动 3 格 mouse.scroll_down(3) # 向下滚动 3 格 x, y mouse.position() # 当前光标位置 (x, y) # ── Keyboard ─────────────────────────────────────────── keyboard.press_key(enter) # 按下并立即松开一个键 keyboard.type_text(hello world) # 输入文本支持 Unicode keyboard.hotkey([ctrl, c]) # 组合键先按 ctrl再点 c再松开 ctrl keyboard.key_down(shift) # 按住 shift keyboard.key_up(shift) # 松开 shift # ── Screen ───────────────────────────────────────────── img screen.screenshot() # 返回 PIL.Image png screen.screenshot_bytes() # 返回原始 PNG 字节 b64 screen.screenshot_b64() # 返回 base64 字符串 w, h screen.screen_size() # 虚拟桌面总尺寸 x, y screen.cursor_position() # 当前光标位置 # ── Window ───────────────────────────────────────────── title window.get_active_window_title() # 当前活动窗口标题 handle window.get_active_window_handle() # 当前活动窗口句柄 handles window.get_windows_with_title(Chrome) # 标题包含 Chrome 的窗口句柄列表 name window.get_window_name(handle) # 句柄对应的窗口标题 x, y window.get_window_position(handle) # 窗口左上角坐标 w, h window.get_window_size(handle) # 窗口宽高 window.activate_window(handle) # 激活窗口置前并聚焦 window.minimize_window(handle) # 最小化 window.maximize_window(handle) # 最大化 window.close_window(handle) # 关闭窗口 window.set_window_size(handle, 1280, 800) # 调整为 1280x800 window.set_window_position(handle, 0, 0) # 移动到 (0, 0) window.open(https://example.com) # 用默认浏览器打开 URL 或默认程序打开文件 pid window.launch(notepad.exe) # 启动应用并返回 PID # ── Clipboard ────────────────────────────────────────── text clipboard.get() # 读取剪贴板文本 clipboard.set(hello) # 写入剪贴板文本 # ── Shell ────────────────────────────────────────────── result shell.run(echo hi) # 返回 CommandResult print(result.stdout, result.returncode) # hi\n 0鼠标操作详解鼠标模块cua_auto/mouse.py基于pynput.mouse.Controller实现全部为同步调用。按钮映射_map_button见 mouse.py#L11-L18把按钮名字符串映射为 pynput 的 Buttonleft默认、right、middle其余值一律归为左键。大小写不敏感内部.lower()。点击与移动click(x, y, buttonleft)先移动光标到 (x, y)再执行一次点击right_click(x, y)等价于click(x, y, right)double_click(x, y)在 (x, y) 处左键连击两次内部用_Button.left, 2由 pynput 保证连击语义move_to(x, y)仅移动光标不点击。按住 / 松开与拖拽mouse_down(xNone, yNone, buttonleft)/mouse_up(...)按下/松开指定按钮。x、y为可选项——传入时先移动光标再按下/松开适合按住的同时重新定位的场景drag(start_x, start_y, end_x, end_y, buttonleft)在起始点按下 → 移动到终点 → 松开完成一次拖拽drag_to(x, y, buttonleft)从当前光标位置拖到 (x, y)drag_path(path, buttonleft)按[(x1,y1), (x2,y2), ...]的轨迹逐点移动并最终松开用于绘制曲线、拖拽经过中间点的场景空列表直接返回不做任何操作。滚动scroll(dx, dy)直接透传 pynput 的scrolldy为正表示向上便捷封装scroll_up(clicks3)、scroll_down(clicks3)、scroll_left(clicks3)、scroll_right(clicks3)分别用abs(clicks)保证方向符号正确。光标位置position()返回(int(x), int(y))的整数坐标元组来自 pynput Controller。键盘操作详解键盘模块cua_auto/keyboard.py基于pynput.keyboard.Controller。其核心是一张统一键名映射表_SPECIAL见 keyboard.py#L11-L70源码注释说明该映射表来源于computer-server/handlers/windows.py即与 cua 的 computer-server 模块保持键名兼容。支持的键名常用特殊键覆盖如下大小写不敏感映射时统一.lower()类别键名编辑键enter/return、esc/escape、space、tab、backspace、delete、home、end翻页pageup/page_up、pagedown/page_down方向up、down、left、right修饰键shift/shift_l/shift_r、ctrl/ctrl_l/ctrl_r/control、alt/alt_l/alt_r、cmd/command/win/super/meta、option/option_l/option_r、capslock/caps_lock功能键f1~f20平台可选insert、print_screen、pause、num_lock、scroll_lock部分平台可能不存在代码用getattr(_Key, ...)探测后再加入见 keyboard.py#L72-L82除特殊键外_resolvekeyboard.py#L85-L94会把单字符len(key) 1直接当作字面字符透传给 pynput未知键名会抛出ValueError。基础操作press_key(key)按下并立即松开一次敲击key_down(key)/key_up(key)按住 / 松开配合实现按住 Shift 输入大写等场景type_text(text)输入整段字符串支持 Unicode透传 pynput 的type。组合键机制hotkey(keys)keyboard.py#L136-L160实现标准热键语义先按住除最后一个键以外的所有键修饰键敲击最后一个动作键再逆序松开所有修饰键。例如hotkey([ctrl, shift, s])会依次按下 ctrl、shift敲击 s再逆序松开 shift、ctrl。任何键无法解析时抛出ValueError并指明具体键名。屏幕捕获与显示信息屏幕模块cua_auto/screen.py是 cua-auto 中平台适配最精细的部分核心解决两个问题跨平台截图与高分屏坐标归一化。截图与三种输出格式screenshot()返回PIL.Image截取全部显示器screenshot_bytes(formatPNG)把截图编码为指定格式的原始字节默认 PNGscreenshot_b64(formatPNG)把截图字节做 base64 编码返回字符串方便通过 JSON / MCP 协议传输给 Agent 或 LLM。截图后端与回退链_get_display_scale与截图逻辑screen.py#L66-L108采用两级回退优先PIL.ImageGrab.grab(all_screensTrue)——在 Windows 与 macOS 上原生可用失败或 Linux 不支持时回退到mss抓取sct.monitors[0]合并的虚拟桌面并把 BGRA 原始数据转为 RGB 的 PIL Image。若两者都不可用例如未安装可选依赖mss的 Linux 无头环境screenshot()会抛出RuntimeError(screenshot failed: ...)。高分屏DPI / Retina归一化为了让截图坐标空间与 pynput 鼠标输入逻辑坐标一致_get_display_scalescreen.py#L12-L54按平台探测缩放系数并回退到 1.0macOS通过 AppKit 的NSScreen.mainScreen().backingScaleFactor()Retina 通常为 2.0Windows通过ctypes.windll.shcore.GetScaleFactorForDevice(0) / 100.0150% DPI 即为 1.5Linux读取GDK_SCALE或QT_SCALE_FACTOR环境变量Wayland/X11 合成器与工具包常设置未知平台或探测失败返回 1.0。当scale 1.0时截图像素会被Image.LANCZOS高质量重采样为逻辑尺寸从而保证screen.screenshot()返回图像的坐标与mouse.click()使用的坐标完全对齐。get_display_scale()是公开的便捷包装供外部代码如 MCP server查询当前 DPI 缩放。屏幕尺寸与光标位置screen_size()基于一张全屏截图返回(width, height)即虚拟桌面总尺寸cursor_position()优先使用 Windows 的win32gui.GetCursorPos()DPI 场景下更可靠需可选依赖pywin32异常时回退到 pynput Controller 获取返回(int, int)。窗口管理窗口模块cua_auto/window.py基于 pywinctl。模块级导入做了容错try: import pywinctl失败置为None使用前通过_require_pwc()校验并给出安装提示window.py#L15-L18。窗口句柄约定库内统一使用原生窗口句柄的字符串形式作为窗口标识。get_active_window_handle()返回当前活动窗口句柄get_windows_with_title(title)使用pwc.Re.CONTAINS包含匹配pwc.Re.IGNORECASE忽略大小写搜索标题返回句柄字符串列表——get_windows_with_title(Chrome)会命中所有标题含 Chrome 的窗口。_get_by_handle通过遍历getAllWindows()并按str(getHandle()) str(handle)比对来定位窗口对象。查询get_active_window()返回 pywinctl 窗口对象底层能力get_active_window_title()当前活动窗口标题无窗口时返回Desktopget_window_name(handle)句柄对应窗口标题get_window_position(handle)/get_window_size(handle)返回(x, y)/(w, h)找不到窗口返回None。动作activate_window、minimize_window、maximize_window、close_window、set_window_size(handle, w, h)、set_window_position(handle, x, y)均返回布尔值表示是否成功执行窗口不存在时返回False。打开 URL / 启动应用open(target)window.py#L155-L174以http://或https://开头时用webbrowser.open在默认浏览器打开否则视为文件路径调用系统默认打开方式——macOS 用open、Linux 用xdg-open、Windows 用os.startfile其他系统抛出RuntimeErrorlaunch(app, argsNone)window.py#L177-L188启动应用并返回 PID。传入args时用subprocess.Popen([app, *args])不传时以shellTrue运行因此可传libreoffice --writer这类带参数的完整命令字符串。剪贴板剪贴板模块cua_auto/clipboard.py是对 pyperclip 的两个薄封装get()读取当前剪贴板文本set(text)写入剪贴板文本。适合与键盘hotkey([ctrl, v])组合实现写入后粘贴或在 GUI 自动化中做数据搬运。Shell 命令执行Shell 模块cua_auto/shell.py提供run(command, timeout30)返回CommandResult数据类stdout、stderr、returncode以及便捷属性successreturncode 0。实现细节值得注意命令以shellTrue交给系统 shell 执行因此管道、重定向、shell 内建命令如echo、cd都按预期工作多编码回退解码shell.py#L25-L33stdout/stderr 依次尝试utf-8 → gbk → gb2312 → cp936 → latin1最后兜底utf-8errorsreplace兼容中文字符集环境Windows 控制台常见超时处理超过timeout秒时返回returncode-1的CommandResult保留已捕获的部分输出而非抛出异常便于调用方统一处理。PTY 伪终端会话除 README 展示的六个模块外cua-auto还提供terminal模块cua_auto/terminal.py——一个跨平台 PTY伪终端管理器用于需要交互式终端语义行编辑、ANSI 输出、程序内写 stdin的场景。这也解释了pyproject.toml中ptyextrapywinpty的用途。公开 API模块级单例terminal Terminal()可直接使用。核心方法方法说明create(commandNone, cols80, rows24, on_dataNone, cwdNone, envsNone)新建 PTY 会话返回PtySession(pid, cols, rows)。Unix 默认命令bashWindows 默认powershellon_data回调在后台 reader 线程中接收原始字节输出envs合并进os.environsend_stdin(pid, data)向会话写入字节数据如becho hi\nresize(pid, cols, rows)调整终端尺寸Unix 通过termios.TIOCSWINSZioctlWindows 通过setwinsizekill(pid)终止会话进程返回是否成功wait(pid, timeoutNone)阻塞至进程退出并返回退出码超时或未知 pid 返回Noneconnect(pid, on_data)为已存在会话替换数据回调适合 SSE / WebSocket 消费者重连场景平台实现Unixterminal.py#L194-L278用 stdlibpty.openpty()创建主从端命令经/bin/sh -c执行初始尺寸通过TIOCSWINSZ设置默认注入TERMxterm-256colorreader 线程从 master fd 读数据并分发回调进程退出后记录退出码并设置事件Windowsterminal.py#L280-L351依赖pywinptyPtyProcess.spawnreader 线程轮询isalive()并读取输出未安装时抛出带安装提示的ImportError。所有公开方法都是线程安全的内部用threading.Lock保护会话表多个会话按 PID 独立管理。无头环境与导入防护包入口 cua_auto/init.py 做了一个关键设计terminal与shell不依赖显示服务器总是安全导入而clipboard、keyboard、mouse、screen、window依赖 pynput / PIL / pywinctl / pyperclip因此被包裹在try/except ImportError中见init.py#L24-L32。这意味着在 CI无 X server或容器内的 computer-server 环境中import cua_auto不会因缺少显示后端而崩溃你仍然可以安全使用cua_auto.terminal与cua_auto.shell做无头自动化。平台判定常量IS_WINDOWS/IS_MACOS/IS_LINUX/PLATFORM集中在 cua_auto/_platform.py供各模块与外部代码复用。测试与质量保障仓库为 PTY 引擎提供了完整的单元测试tests/test_terminal.py覆盖基础回显含空格、首尾空格、多词、空串、数字、特殊字符的echoTestEchoBasic退出码exit 0 / 1 / 42、true/false的退出码断言TestExitCodes交互式 stdin通过send_stdin发送多条命令与exit并断言输出与退出码TestSendStdinkill / wait 行为可杀掉运行中的sleep 60会话、未知 PID 的kill返回False、wait返回NoneTestKillresize 不抛异常、未知 PID 为 no-opTestResizeconnect替换回调后新输出进入新回调TestConnect模块级单例terminal可直接使用TestSingletonTerminal。测试通过pytestmark skipif(sys.platform win32)在 Windows 上跳过 Unix PTY 用例Windows 路径由 tests/test_terminal_windows.py 单独覆盖体现了跨平台实现的测试分层策略。使用建议与限制坐标体系鼠标、截图、窗口接口统一使用逻辑坐标。在 Retina / HiDPI 屏幕下请优先使用screen.screenshot()已做 DPI 归一化得到的图像坐标来驱动mouse.click()避免物理像素与逻辑像素错位Linux 截图不安装mss时screenshot()会抛错多屏或 Linux 环境建议安装cua-auto[mss]无头环境terminal与shell可在无显示服务器环境使用其余模块需要真实桌面会话窗口操作部分窗口管理操作如activate可能受操作系统窗口策略限制返回值False时需自行降级处理。总体而言cua-auto以极小的依赖面提供了从模拟输入到读取屏幕、管理窗口、执行命令、交互式终端的完整桌面自动化原语集既可作为独立脚本库使用也可作为 cua 生态中 computer-use Agent 的本地动作层。相关源码与测试见 cua_auto 包 与 测试目录。【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考