企业官网建设流程全解析

macOS Harness CLI 是 macOS Harness 项目提供的唯一命令行入口：一条命令，把 Python、真实的 macOS 应用和你的浏览器连在同一个进程里，让 AI Agent（或你本人）能截图、打字、点击、执行 AppleScript。它是最薄的一层“控制 harness”，不封装任何具体 App 工具，只给出最原始的操作原语。本文带你逐条解析doctor、apps、repl、see、state等命令的用法、参数与典型场景，帮助新手快速上手这套 Mac 自动化 CLI 工具。

一分钟认识 macOS Harness

macOS Harness 的设计理念是“六动词”：see（看）、key（按键）、type（打字）、click（点击）、ax（无障碍树）、script（AppleScript）。没有 Spotify 工具、没有 Slack 工具——模型拿到的是原始能力，缺失的逻辑由它在任务中途用普通 Python 补上。

安装后你会得到一个可执行文件macos-harness，所有功能都通过子命令暴露：

# 安装（需要 Python 3.12） uv tool install --python 3.12 --upgrade --force macos-harness

完整安装说明见 install.md。

命令速查表

各命令的定义集中在 cli.py，建议对照源码阅读。

doctor：首次运行前的权限体检 🩺

macOS 对“读屏幕、发输入、自动化”有严格的隐私限制。doctor是安全的第一步——它只报告、不弹窗：

macos-harness doctor

输出是一个 JSON 报告，核心字段来自 macos.py：

• permissions.accessibility：辅助功能权限（截图、按键、点击都需要它）
• permissions.screen_recording：屏幕录制权限
• permissions.post_events：发送输入事件的权限
• permissions.automation：自动化（Apple Events）权限，按目标应用逐一授权

如果某项权限缺失，在获得用户确认后再加--request参数，macOS 会弹出系统授权窗口：

macos-harness doctor --request

💡 经验法则：装完先跑一次不带--request的doctor，按报告去「系统设置 → 隐私与安全性」手动授权，比一路点“允许”更可控。

apps：列出正在运行的应用

apps返回一个按名称排序的 JSON 数组，每项包含name、bundle_id、pid、path四个字段，实现在 macos.py：

macos-harness apps

它的价值在于帮你确认应用名到底怎么拼——后续所有命令的app参数都支持应用名、Bundle ID、路径或 PID 四种匹配方式（见 应用解析逻辑）。如果匹配到多个应用，CLI 会报ambiguous错误并列出候选项，此时改用 PID 即可精确命中。

see：后台截图，不打扰你的前台 👀

see是整套工具最核心的命令：它截取指定应用某个窗口的画面，但不会把该应用拉到前台，也不移动你的真实鼠标：

macos-harness see Finder macos-harness see Spotify --max-width 800 --max-height 600

参数说明（定义于 cli.py）：

返回 JSON 包含图片路径、实际尺寸、窗口 bounds、缩放系数scale_x/scale_y，以及焦点信息（见 see 实现）。特别注意focus.target_is_frontmost字段——它保证截图过程没有“偷偷抢焦点”。

为什么需要缩放？Retina 屏上窗口原始像素可能远超 1280，直接喂给模型太贵。see会自动用 Lanczos 算法压到上限尺寸，scale_x/scale_y则告诉你后续点击坐标该如何换算。

state：把无障碍树打印成 JSON

截图解决“看”，state解决“精确”：它遍历应用的 Accessibility 树，把每个控件的角色、标题、值、坐标、可用动作全部输出为 JSON（实现在 get_app_state）：

macos-harness state Finder --screenshot --max-depth 10

参数说明：

输出中每个节点都带element_index，在repl里可以直接用它读取属性或执行动作（例如AXPress模拟按钮点击）。对大应用，适当调小--max-nodes能显著加快输出。

repl：交互式 Python 探索会话

repl启动一个持久的交互式 Python 会话，mac、browser、Path、subprocess四个对象开箱即用：

macos-harness repl

进入后可以直接敲：

>>> mac.see("Finder") >>> mac.key("cmd+k", app="Finder")

它适合人工探索一个应用的控件结构；官方建议日常任务优先用 stdin 方式，把repl留给手动调试，用完记得退出（见 SKILL.md）。

隐藏高手用法：stdin 直接执行 Python

不给任何子命令、且输入不是终端时，macos-harness会把标准输入里的 Python 代码直接执行（逻辑见 cli.py）。这是 Agent 使用它的标准姿势——一次调用完成一个“动作包”，而不是每个原语调用一次：

macos-harness <<'PY' mac.see("Spotify") mac.key("cmd+k", app="Spotify") mac.type("Alessia Cara", app="Spotify") print(mac.see("Spotify")) PY

💡 官方技能文档建议：把确定性的、可逆的步骤打包成一个 Python 程序一次跑完，只在真正的决策点（身份不明、新坐标、不可逆操作）才停下来观察。

skill 与 telemetry：两个辅助命令

• macos-harness skill：打印内置的技能文档（即 SKILL.md），把它存进 Agent 的 skills 目录后，Agent 就能“自学会用”这套 CLI。
• macos-harness telemetry status | enable | disable：查看或开关匿名遥测。遥测只记录命令类别、成功与否、耗时等粗粒度信息，从不记录提示词、应用名、截图或窗口标题，实现见 telemetry.py。

macos-harness telemetry disable

常见问题速查

所有错误统一以macos-harness: <原因>输出到 stderr，退出码为 1（见 错误处理），方便脚本判断成败。

小结

macOS Harness 把整个 Mac 压缩成了一组极简 CLI 命令：用doctor确认权限，用apps找目标，用see和state观察，用 stdin Python 或repl行动。记住这五步流程，你就能让 AI Agent（或自己）在不干扰前台操作的前提下，安全地驱动任何正在运行的 macOS 应用。