To3akaRin/mac-computer-use

Enable any LLM to control your computer with cross-platform support, featuring 3D modeling examples and live demos.

TL;DR

mac‑computer‑use 是一个开源的 Agent Skill，允许大型语言模型驱动的代理控制 macOS 桌面。它可以通过 macOS Accessibility (AX) 或 Chrome DevTools Protocol (CDP) 观察窗口和 UI 元素，发送点击/键盘输入，并验证结果，所有操作均通过遵循开放 Agent Skills 规范的本地命令行工具完成。

它能做什么（用通俗语言）

观察 – 列出打开的应用程序，获取窗口几何信息，读取 UI 控件（按钮、文本框等），对于基于 Chromium 的窗口，可通过 CDP 检查页面的 DOM。
操作 – 发送原生 macOS 输入事件（点击、悬停、滚动、输入）或 CDP 输入命令，与目标 UI 交互。
验证 – 读取 UI 状态，使用 ScreenCaptureKit 捕获截图，并返回结构化 JSON，使代理知道操作是否成功。

整个工作流程被封装为一个技能，任何支持 Agent Skills 规范的代理运行时（Claude Code、Codex、Cursor 等）均可加载并调用。

哪些人可能使用它

开发需要自动化 macOS 应用程序的 AI 助手的开发者（例如打开文件、填写表单、运行脚本），无需编写自定义 AppleScript 或 Selenium 代码。
研究具身智能（embodied AI）的科研人员，希望以可复现、沙盒化的方式让 LLM 操控真实桌面。
希望即插即用 CLI 来脚本化难以用纯 shell 命令表达的 UI 操作的高级用户。

如何快速上手（分步指南）

通过 Vercel Skills CLI 安装技能：
```
npx skills add To3akaRin/mac-computer-use
```
此命令将 mac-computer-use/ 目录复制到本地技能存储中。
确保你的 Mac 满足要求：
- macOS 14 或更高版本，Apple Silicon（Intel 可能可用但未经测试）。
- Xcode 命令行工具（Swift 6）– xcode-select --install。
- Node 22.4+（仅 CDP 部分需要）。
- 为终端或你将运行的代理应用授予 辅助功能 和 屏幕录制 权限。
运行一个简单的观察命令，查看可用窗口：
```
./.skills/mac-computer-use/scripts/run.sh native windows
```
输出为 JSON，列出每个窗口的 ID、标题、大小和进程。
选择一个窗口并探测其 UI（以 TextEdit 为例）：
```
./.skills/mac-computer-use/scripts/run.sh native ax \
    --window <WINDOW_ID> \
    --snapshot-out ./artifacts/window.json
```
此命令将该窗口中所有 Accessibility 元素的描述写入 JSON 文件。

执行一个操作 – 例如，在第一个文本字段中输入“Hello”：

./.skills/mac-computer-use/scripts/run.sh native type \
    --window <WINDOW_ID> \
    --element "AXTextField" \
    --text "Hello"

验证 – 读取字段内容或截取屏幕快照：

./.skills/mac-computer-use/scripts/run.sh native shot \
    --window <WINDOW_ID> \
    --output ./artifacts/after.png

JSON 结果会告诉代理文本是否正确设置。

所有命令均支持 --dry-run 标志，可在不实际发送输入的情况下检查参数，非常适用于安全测试。

核心技术细节（好奇者必看）

方面	实现方式
语言	原生 macOS 工具使用 Swift 6；CDP 交互使用 Node.js 脚本。
UI 观察	原生应用使用 macOS Accessibility (AX) API；基于 Chromium 的窗口使用 Chrome DevTools Protocol (CDP)。
输入生成	原生应用使用 `CGEvent` 基础的鼠标/键盘事件；网页使用 CDP `Input` 域（`click`、`insertText` 等）。
验证	读取 AX 值、CDP 只读断言，以及通过 ScreenCaptureKit 捕获截图。
打包方式	遵循开放的 Agent Skills 规范 – 包含 `SKILL.md` 元数据文件和运行时调用的 `scripts/` 启动脚本。
零运行时 npm 依赖	CDP 客户端是超小的自包含脚本；无需独立服务器或 API 密钥。
安全规则	• 仅在用户非活动 ≥2 秒后，且等待 ≤15 秒内执行操作。 • 支持 `--dry‑run` 预览模式。 • 拒绝过期的窗口快照。
输出格式	包含 `target`、`channel`（native 或 cdp）、`status`（`success`、`unknown`、`refused`）以及任何证据（截图、AX 读取结果）的 JSON 对象。

限制与待解决问题

应用覆盖范围 – 对于暴露清晰 AX 树或提供 CDP 端口的应用，开箱即用。部分第三方工具可能有自定义控件，难以定位。
Intel/macOS 14 – 未经官方验证；CI 在 Apple Silicon/macOS 15 上运行。
无远程执行 – 该技能必须在 Mac 上本地运行；Linux 沙箱无法控制桌面。
文档语言 – 多数指南（references/*.md）目前为中文，可能阻碍非中文贡献者。

快速参考速查表

命令	用途	示例
`native windows`	列出所有窗口	`run.sh native windows`
`native ax`	导出窗口的 Accessibility 树	`run.sh native ax --window 123 --snapshot-out out.json`
`native type`	向特定 AX 元素输入文本	`run.sh native type --window 123 --element AXTextField --text "Hi"`
`native click`	通过坐标或 AX 路径点击 UI 元素	`run.sh native click --window 123 --point 0.5,0.2`
`cdp snapshot`	捕获 Chromium 页面的 DOM 和截图	`node scripts/cdp.mjs snapshot --endpoint http://127.0.0.1:9222 --target PAGE_ID`
`native doctor`	运行自检（权限、Swift、Node）	`run.sh native doctor`

总结

mac‑computer‑use 将 macOS 桌面转变为一个可确定性、可观测-可操作-可验证的接口，任何 LLM 驱动的代理均可调用。它在无需云服务的情况下，弥合了高层语言推理与底层 UI 操作之间的鸿沟，是构建自主 macOS 代理的坚实基础。