企业官网建设流程全解析

macOS Harness 是专门给 LLM 大语言模型使用的"最薄"Mac 控制框架（harness），它让 AI Agent 能够看到屏幕画面、按键、点击，从而获得操控整台 Mac 的完整自由度。本文将做一次完整实战：让 AI 自动在 Spotify 里搜索歌曲并播放。全程你的真实鼠标不会移动，目标应用甚至不需要切到前台。🎧

macOS Harness 是什么：给 AI 一台完整的 Mac

macOS Harness 的核心思路是"不给 AI 任何现成工具，只给原始积木"。它没有 Spotify 工具、Slack 工具或 Final Cut 工具，AI 拿到的只是 6 个底层原语（primitives），其余逻辑由模型用普通 Python 现场写出来。

它的 6 个核心原语是：

所有原语都工作在同一个常驻 Python 进程里，browser（真实 Chrome）、Path、subprocess也直接可用。完整原理见 README.md，其架构图说明了 CGWindow 截屏、CGEvent 输入、AX 无障碍和 CDP 浏览器控制是如何组合在一起的。

一键安装步骤：30 秒装好 macOS Harness

macOS Harness 只支持 macOS，依赖 Python 3.12。官方推荐用uv安装（完整说明见 install.md）：

# 1. 安装 CLI 工具 uv tool install --python 3.12 --upgrade --force macos-harness # 2. 把 Skill 说明注册给 AI Agent（以 Codex 为例） mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/macos-harness" macos-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/macos-harness/SKILL.md" # 3. 体检：检查缺失的 macOS 权限 macos-harness doctor

doctor会输出当前缺失的权限（Accessibility 辅助功能、Screen Recording 屏幕录制、Automation 自动化）。按提示在「系统设置 → 隐私与安全性」中授权即可，无需开启 Input Monitoring。

💡 更省事的方式：把 README 里那段英文指令直接粘贴给你的 Codex / Claude Code，Agent 会自己完成安装、注册 Skill、权限检查和验证。

验证连接是否成功——截一张已经在运行的 Finder 窗口，且不打断你的操作：

macos-harness <<'PY' print(mac.see("Finder")) PY

实战演示：AI 自动搜索 Spotify 并播放歌曲

下面这段程序就是完整流程：打开搜索框 → 输入歌手名 → 点击结果 → 用 AppleScript 播放。把app = "Spotify"换成任何应用名，套路完全一样。

macos-harness <<'PY' app = "Spotify" mac.see(app) # 1. 截屏窗口，让 AI 确认当前状态 mac.key("cmd+k", app=app) # 2. 快捷键打开搜索框 mac.type("Alessia Cara", app=app) # 3. 输入搜索词 print(mac.see(app)) # 4. 再截一次图，AI 根据画面定位结果 # 5. 用 AX 语义树精确点击（比纯坐标更稳） item = mac.ax.at(640, 420, app=app) mac.ax.perform(item["element_index"], "AXPress") # 6. 播放 mac.script('tell application "Spotify" to play') PY

为什么用虚拟指针而不是动你的鼠标

mac.click()发出的点击是直接投递到目标应用 PID 的原始事件，同时屏幕上的"动画指针"只是一个可点击穿透的视觉覆盖层，你的真实光标纹丝不动（实现见 pointer.py 与 overlay.py）。AI 截到的图里会画出这个虚拟指针的位置，方便它下一步决策。

每一步背后发生了什么

• mac.see：调用系统screencapture抓取指定窗口（支持 Retina 缩放），并在图上叠加虚拟指针，返回包含路径、尺寸、缩放系数的 JSON。实现位于 macos.py#L1033-L1126。
• mac.key/mac.type：通过 Core Graphics 事件（CGEvent）按键码逐字注入，支持cmd、ctrl、alt、shift等修饰键，任意 Unicode 文本都能输入。
• mac.click：把截图坐标系自动换算成屏幕坐标，再投递给应用 PID，因此即使 Spotify 在后台也能点中。
• mac.ax：读取 macOS Accessibility 语义树拿到按钮的element_index，再用AXPress执行"按下"动作——这是比像素坐标更可靠的语义级操作。
• mac.script：本质是调用osascript执行 AppleScript，适合应用本身支持精确指令的场景（如play、pause）。

六个原语速查清单

官方 Skill 文档对"如何减少往返、选择最低有效模式"有完整策略说明，推荐精读 SKILL.md。

权限与隐私：最小授权、不抢焦点

macOS Harness 在安全设计上非常克制：

• 从不激活目标应用：输入事件直接发给后台应用的 PID，窗口不会弹到最前。如果后台目标意外变成最前台，会抛出FocusChangedError并停止，而不是"修复"焦点。
• 匿名遥测默认开启：只记录命令类别、成功与否、耗时、版本、系统架构，绝不记录提示词、应用名、截图、UI 文本或窗口标题。介意的话一条命令关闭：

macos-harness telemetry disable

常见问题与快速排查

排查入口：cli.py 中doctor、apps、see、state四个子命令分别用于检查权限、列出运行中应用、截窗和导出 AX 状态 JSON。

进一步探索：核心文件清单

现在，你的 AI Agent 已经拥有了一台 Mac：下一次你可以让它自动整理下载文件夹、在 Notes 里建备忘，或者——像本文这样——自己搜歌、点歌、播放。🚀