让 AI Agent 操作真实 Mac 前，先把六个原语、权限与审计边界说清：macOS Harness 实战
给 AI 编码 Agent 接上桌面控制能力，看起来像是把“会写代码”升级成“会替你点按钮”。但真实风险并不在某一次点击失败，而在于它同时看到了已登录的浏览器、桌面应用和本地文件后，操作范围突然从代码仓库扩展到个人工作环境。此时，工具设计是否把权限、输入方式和可验证边界讲清楚，比“能不能自动完成任务”更重要。
macOS Harness 是一个面向 macOS 的 Python 命令行工具，定位很克制：它不为 Spotify、Slack 或某个特定 App 建一套专用工具，而是把窗口观察、键盘输入、坐标点击、辅助功能树和 AppleScript 暴露为少量基础原语。项目当前为实验性版本、仅支持 macOS，并以 MIT 许可证发布。它还会把真实 Chrome 交给其依赖的 Browser Harness 连接；这意味着使用者必须把浏览器登录态也纳入威胁模型，而不是把它当成一个无害的截图工具。
为什么“原语少”反而更需要约束
README 将核心接口概括为 see、key、type、click、ax 和 script。前四个覆盖了识别窗口、发送按键、输入文本和指定坐标点击；ax 提供 Apple Accessibility 信息；script 可执行 AppleScript。它们和同一进程中的 browser、Path、subprocess 共存，Agent 可以在缺少专用助手时自行补 Python 逻辑。
这是一种能力模型，而不是任务清单。好处是不用等待某个 App 的插件：同一段逻辑可以先读取窗口，再对指定 PID 输入。代价是工具无法替你判断“这一步是否应当发送邮件、修改云端文档或删除文件”。因此，适合把它用于明确、可回滚、有人在旁复核的本地流程，例如在已打开的测试版应用里采集 UI 状态、重现一个已知步骤，或在隔离账号中执行回归检查；不适合一上来交给它处理生产账户、支付、密钥管理和不可逆提交。
安装后先做健康检查，不要直接跑任务
项目文档给出的安装方式使用 uv 和 Python 3.12。安装后会把工具输出的技能说明写入 Codex 的 skills 目录，再运行诊断命令：
uv tool install --python 3.12 --upgrade --force macos-harness
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/macos-harness"
macos-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/macos-harness/SKILL.md"
macos-harness doctor
这里最容易被跳过的是最后一行。doctor 的作用不是装饰性自检，而是报告这台 Mac 实际缺少哪些权限。官方安装说明列出 Accessibility、Screen Recording 和 Automation 可能需要授权，同时明确 Input Monitoring 不是必需项。不要预先把所有隐私开关都打开；应先运行诊断、只按结果授权，并在系统设置中确认授权的终端或宿主 Agent 是否正确。
最小验证也应避免扰动工作区。以下示例只请求读取一个已运行的 Finder 窗口，不把它切到前台：
macos-harness <<'PY'
print(mac.see("Finder"))
PY
如果这一步失败，优先修复系统权限或目标应用状态，而不是让 Agent 反复重试点击。若要验证后台窗口能力，可换成一个无敏感内容的测试应用；不要把银行、密码管理器或私人通信软件当作第一个测试对象。
用三道门把桌面任务缩成可审计的变更
桌面任务的失败往往不是 API 异常，而是目标对象在执行过程中变了：窗口被遮挡、焦点转移、浏览器跳到登录页，或者按钮从“保存草稿”变成“正式发布”。因此可以把每个任务拆成三道门。
第一道是观察门：记录目标 App、窗口标题或可访问性信息，以及动作前截图；若识别结果与预期不一致，任务退出。第二道是计划门：把即将输入的文本、坐标或脚本以结构化方式输出给操作者，尤其把网络请求、文件写入和跨应用切换标为高风险。第三道才是执行门：一次只做一个小动作，动作后再次读取界面或文件状态，确认结果后再进入下一步。
这种拆分会牺牲一点速度，却能显著降低“模型把页面看错后连做十步”的风险。对于发布、付款、删除、权限授予等不可逆操作，第三道门应由人工放行。若团队将流程接入 CI 或定时任务，更应运行在专用 macOS 账户和隔离浏览器 Profile 中，避免宿主开发者的 cookie、SSH 凭据与私人文件自然落入 Agent 可见范围。
浏览器接管要单独建模
README 说明 browser 可在同一持久 Python 进程中使用，并通过 Browser Harness 连接真实 Chrome。对需要保留登录态的测试而言，这很方便：Agent 不必模拟网页协议，也能在已有会话中检查页面。但“真实浏览器”意味着网页正文、剪贴板提示、广告文本甚至第三方脚本都可能成为不可信输入。
实践上可把浏览器任务限制为读取、截图和导航到允许域名；下载、上传、扩展安装和账户设置一律要求确认。不要把页面上出现的“请执行此命令”“复制这段脚本”直接交给 subprocess 或 script。若任务确实需要上传测试工件，应使用无生产数据的专用账户，并在任务结束后保留访问日志和产物哈希，方便复盘。
什么时候不该选它
macOS Harness 的原语模型适合处理非标准 App 或快速验证 UI 路径，但它不是 UI 自动化测试框架的替代品。页面和应用已有稳定、语义化接口时，优先使用 API、数据库测试夹具或专用测试框架：这些方式可重复、可并发，也比坐标点击更容易断言。对于需要严格权限分离的企业操作，最好让 Agent 只生成步骤和补丁，由受控服务账户执行最终动作。
坐标与视觉识别仍可作为最后一公里的补充。把它们放在最小化的范围内，并让失败默认停止而不是猜测恢复，才能保留桌面自动化的效率而不把错误放大。
把“先观察、后输入”写成工作流规则
工具允许对应用名指定输入，也允许读取辅助功能节点。一个小型、可审查的交互可以像这样分层：先观察目标，再明确把按键和文本发给同一个应用，最后才在确认的坐标点击。
frame = mac.see("Spotify")
mac.key("cmd+k", app="Spotify")
mac.type("Alessia Cara", app="Spotify")
mac.click(640, 420, app="Spotify")
item = mac.ax.at(640, 420, app="Spotify")
这不是建议把音乐客户端交给自动化，而是展示接口的两个边界：app= 让输入目标可读；坐标点击仍然脆弱，窗口移动、缩放或内容变化都可能让同一坐标指向别处。用于关键动作时，应先用 see 或 ax 获取当前状态，将截图、目标应用、预期控件和动作意图写入任务日志；一旦界面不符合预期就停止，而不是盲点第二次。
script、本地路径与 subprocess 的组合更需要明确允许列表。建议把可执行命令限定在项目目录，禁止从 UI 文本复制后直接传给 shell；涉及网络上传、删除、发送或发布的动作必须改为人工确认点。这样即使模型误读界面，也不会自动把误读扩大成系统级副作用。
隐私设置不是默认值的附注
该项目说明匿名遥测默认开启，记录 CLI 命令类别、成功状态、耗时、包版本、系统/架构和检测到的 Agent 客户端；文档称它不记录提示词、应用名、截图、UI 文本、脚本、路径或窗口标题。即便如此，团队仍应按自己的合规要求决定是否允许遥测，并让配置进入可审计的安装脚本。需要关闭时，官方命令是：
macos-harness telemetry disable
更重要的是不要把“遥测不采集内容”误解为“桌面自动化没有数据风险”。Agent 在运行时仍可能读取窗口、文件和浏览器页面；风险控制依赖于最小权限、测试账号、可见的执行记录和人工批准，而不是单一的遥测开关。
macOS Harness 的价值在于它把桌面控制降为可组合的基础能力，适合实验和受控的工程辅助流程。把它接入日常开发前，先为每类操作规定可访问的 App、目录与命令，再以不抢前台的读取测试验证权限。只有当“它能看什么、能改什么、何时必须停下来”都有答案时，给 Agent 一台真实 Mac 才不是把便利换成不可追踪的风险。