前言¶

在 macOS 上做重复性界面操作，常见路径是手写 AppleScript，或在 Python 里自己拼 osascript、pyautogui 和截图逻辑。脚本越复杂，权限说明、模块边界和错误重试就越难在一次对话里交代清楚。若你已经在 Cursor、Claude Code 等环境里用 Agent 写代码，更希望有一份结构化的技能说明，让模型按固定模块去开应用、点按、截图匹配和串联步骤，而不是每次从零摸索。

下面介绍 SkillHub 上的社区技能 macOS UI 自动化技能包 —— 用 Python 控制你的 Mac（坐标 @user_2e438cd6/macos-desktop-controller-v1）。它把桌面自动化拆成应用控制、键鼠交互、视觉与工作流四层，并附带 Python 实现与 SKILL.md 指引，便于 Agent 在受权环境下生成可运行的自动化脚本。

这是什么¶

一句话定位：面向 macOS 14+（Sonoma） 的 Python 桌面 UI 自动化技能包，通过 PyAutoGUI、AppleScript 与 OpenCV 模板匹配控制本机界面；作为 Agent Skill，主要解决「模型不知道项目里有哪些模块、默认配置和步骤格式」的问题。

出品与来源：SkillHub 社区技能，发布者 user_2e438cd6（页面展示作者名「戈壁老王」），分类 dev-programming，当前包版本 1.0.2，标签 requires_api_key=false（无需 API Key）。
与纯脚本的差异：安装后 Agent 会读取技能目录内的 SKILL.md 与 Python 模块（app_control、click_control、vision_control、workflow 等），按文档中的动作名和配置项组织代码，而不是临时拼凑零散命令。

SkillHub 页面简介强调：用代码控制 Mac，无需单独学习 AppleScript；实现上仍会调用 osascript 做部分窗口与应用操作，日常开发以 Python API 为主即可。

核心功能¶

技能包内代码按模块划分，下列能力与仓库内实现一致（节选）。

应用控制（`AppControl`）¶

通过 open -a 启动应用，并可等待进程就绪（psutil）。
优雅或强制关闭应用，查询是否运行、激活前台窗口。
借助 AppleScript 进行窗口移动、缩放、最小化、最大化等操作。

键鼠交互（`ClickControl`）¶

基于 PyAutoGUI 的坐标点击、多击、拖拽、滚动与按键/组合键。
文本输入可配置间隔；坐标会校验是否在屏幕范围内。
文档中的「按元素名点击」在代码里尚未实现（会记录 warning 并返回失败），实际落地需配合模板匹配坐标再点击。

视觉（`VisionControl`）¶

全屏或区域截图（Pillow / PyAutoGUI），可选写入文件。
使用 OpenCV 做模板匹配（find_template、wait_for_template 等），支持截图缓存与阈值配置。

工作流（`WorkflowManager`）¶

execute_steps 接受步骤列表，内置动作包括：open_app、close_app、activate_window、click_at、click_template、write_text、press_key、drag_from_to、scroll、wait、wait_for_template、capture_screen、condition、loop 等。
单步可配置 continue_on_failure、delay_after；执行结果会写入工作流历史。

配置¶

默认从 config.json、用户目录 ~/.macos_controller_config.json 或环境变量 MACOS_CONTROLLER_CONFIG 加载。
常用项：default_timeout、retry_count、screenshot_dir、template_dir、vision_threshold、mouse_speed 等；环境变量如 MACOS_CONTROLLER_LOG_LEVEL、MACOS_CONTROLLER_SCREENSHOT_DIR 与文档一致。

安装与启用¶

系统与环境¶

SkillHub 列表页要求：

macOS 14+（Sonoma）
Python 3.9+
系统设置中开启 辅助功能 与 屏幕录制；技能文档还建议为 自动化（控制 Safari / Finder 等）授权。

技能包内 SKILL.md 另写 Python 3.8+，若以本机环境为准，建议满足 SkillHub 页面的 3.9+ 要求后再安装依赖。

安装 Skill（Agent）¶

官方页面给出的安装提示词为：

请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_2e438cd6/macos-desktop-controller-v1`。

若本机已安装 SkillHub CLI，也可在对应 Agent 的 skills 目录执行（路径需与当前客户端一致，见 SkillHub 安装说明）：

skillhub install @user_2e438cd6/macos-desktop-controller-v1 --dir <你的 Agent skills 目录>

常用目录示例（同一文档中的说明）：

Cursor：~/.cursor/skills/
Claude Code：~/.claude/skills/
Codex：~/.codex/skills/ 或项目下 .agents/skills/

安装后需让 Agent 重新加载 skills 目录（按各客户端惯例重启或刷新），才会读到新技能。

安装 Python 依赖¶

在 Mac 本机、技能包所在目录或你的项目环境中执行：

pip install -r requirements.txt

requirements.txt 中核心依赖包括 pyautogui、psutil、opencv-python、numpy、Pillow；可选 pyobjc-framework-Cocoa、pyobjc-framework-Quartz。

典型用法¶

下列示例与技能包内类 API 一致（需在技能目录加入 PYTHONPATH，或在你的项目中按相同模块名引用）。SKILL.md 里出现的 from macos_desktop_controller import app_control 与当前包结构不一致，以类实例方式为准。

1、应用开关与前台¶

from app_control import AppControl

ctrl = AppControl()
ctrl.open_app("Safari")
ctrl.activate_window("Safari")
ctrl.close_app("Safari")

2、点击与输入¶

from click_control import ClickControl

mouse = ClickControl()
mouse.click_at(500, 300)
mouse.write_text("Hello World", interval=0.05)
mouse.drag_from_to(100, 100, 500, 500, duration=1.0)

3、截图与模板定位¶

from click_control import ClickControl
from vision_control import VisionControl

vision = VisionControl()
mouse = ClickControl()

vision.capture_screen(save_path="/tmp/screen.png")
position = vision.find_template("target.png", threshold=0.8)
if position:
    mouse.click_at(position[0], position[1])

4、声明式工作流¶

from workflow import WorkflowManager

steps = [
    {"action": "open_app", "params": {"app_name": "Safari"}},
    {"action": "wait", "params": {"duration": 2}},
    {"action": "click_template", "params": {"template_path": "search_bar.png"}},
    {"action": "write_text", "params": {"text": "macOS automation"}},
    {"action": "press_key", "params": {"key": "enter"}},
]

WorkflowManager().execute_steps(steps)

工作流里 click_template 步骤使用参数名 template_path（与部分文档示例中的 template 字段不同，以 workflow.py 实现为准）。

适用场景与注意¶

适合谁

在 macOS 上需要重复操作 GUI（测试辅助、内部工具、批量点按）的开发者。
已使用 Cursor / Claude Code 等，希望 Agent 按固定模块生成自动化脚本，而不是每次重写 AppleScript 片段。

限制与坑

平台：仅适用于 macOS；Linux 或 Windows 上无法直接运行控制逻辑。
权限：未授予辅助功能 / 屏幕录制时，键鼠与截图会失败；首次运行建议在「隐私与安全性」中逐项确认。
版本表述：SkillHub 包版本为 1.0.2，包内 __init__.py 标注 __version__ = "2.0.0"，文档标题亦写「v2」；对接问题时以实际安装的目录与 _meta.json 为准。
文档与代码：SKILL.md 部分 import 示例与模块导出名不一致；元素 ID 点击未实现，应优先坐标或模板匹配。
安全：自动化会真实操作本机界面，交给 Agent 生成脚本前请确认步骤范围，避免误关应用或误点敏感操作。

结尾¶

macOS UI 自动化技能包把应用、键鼠、视觉和工作流收成一套 Python 模块，并写成 Agent 可读的 SKILL.md，适合在 Sonoma 及更高版本上，用对话驱动桌面脚本而不是单独啃 AppleScript。安装与详情见 SkillHub：

页面：https://www.skillhub.cn/skills/user_2e438cd6/macos-desktop-controller-v1
API 入口：https://api.skillhub.cn/user_2e438cd6/macos-desktop-controller-v1

（SkillHub 列表数据：评分 100000，下载 979，来源 community。）

macOS UI 自动化技能包：用 Python 驱动桌面，交给 Agent 执行

前言¶

这是什么¶

核心功能¶

应用控制（`AppControl`）¶

键鼠交互（`ClickControl`）¶

视觉（`VisionControl`）¶

工作流（`WorkflowManager`）¶

配置¶

安装与启用¶

系统与环境¶

安装 Skill（Agent）¶

安装 Python 依赖¶

典型用法¶

1、应用开关与前台¶

2、点击与输入¶

3、截图与模板定位¶

4、声明式工作流¶

适用场景与注意¶

结尾¶

精选优惠券

macOS UI 自动化技能包：用 Python 驱动桌面，交给 Agent 执行

前言¶

这是什么¶

核心功能¶

应用控制（AppControl）¶

键鼠交互（ClickControl）¶

视觉（VisionControl）¶

工作流（WorkflowManager）¶

配置¶

安装与启用¶

系统与环境¶

安装 Skill（Agent）¶

安装 Python 依赖¶

典型用法¶

1、应用开关与前台¶

2、点击与输入¶

3、截图与模板定位¶

4、声明式工作流¶

适用场景与注意¶

结尾¶

精选优惠券

相关文章

应用控制（`AppControl`）¶

键鼠交互（`ClickControl`）¶

视觉（`VisionControl`）¶

工作流（`WorkflowManager`）¶