# macos-desktop-control

操作 macOS 桌面与应用界面：读无障碍元素树、点击按钮/菜单、填输入框、发文本与组合键、按窗口截图

以 Pi package（技能形态）发布。技能本体在 `skills/macos-desktop-control/`。

- 平台：macOS
- 许可：GPL-3.0-or-later（全文见 [LICENSE](LICENSE)）

## 安装

```sh
pi install git:gitea.vhkd.top/pi-hub/macos-desktop-control.git@v0.1.3
```

装完 `pi-skill list` 能看到 `macos-desktop-control`，`pi-skill macos-desktop-control check` 会告诉还缺什么。

## 先准备什么

- `swiftc`（命令），安装：xcode-select --install（Command Line Tools）；截图/窗口原语的小工具需要编译；已编译过就不再需要
- `shasum`（命令），安装：macOS 自带（perl）

## 常用命令

| 命令 | 说明 |
|---|---|
| `check` | 前置检查：权限与可达性（其它命令失败时先跑它） |
| `apps` | 正在运行的 GUI 应用 |
| `front` | 当前前台应用 |
| `windows` | 屏幕上所有窗口（含 CGWindowID） |
| `tree` | 无障碍元素树（= 原生 app 的 DOM） |
| `find` | 找元素，打印可直接使用的地址 |
| `get` | 读元素属性（省略属性时列出全部属性与可用动作） |
| `shot` | 截图（默认前台应用窗口，默认写临时文件；--clipboard 直接进剪贴板，--no-shadow 去阴影并等同窗口几何） |
| `ocr` | 识别屏幕文字并给出屏幕坐标（AX 树为空的界面用它定位） |
| `focus` | 把应用切到前台 |
| `press` | 按下元素 |
| `set` | 写元素属性，写完回读 |
| `menu` | 按标题路径点菜单 |
| `type` | 输入任意文本（含中文） |
| `key` | 发组合键 |
| `win-state` | 读窗口位置/尺寸/全屏/最小化/所在屏幕 |
| `win-place` | 把窗口摆到指定区域（半屏/四角/三分之一/自定义比例） |
| `win-screen` | 把窗口移到另一块屏幕 |
| `win-fullscreen` | 全屏开关 |
| `win-minimize` | 最小化窗口 |
| `win-unminimize` | 恢复被最小化的窗口 |
| `click` | 点击坐标或元素中心 |
| `drag` | 拖拽 |
| `scroll` | 滚动 |
| `space-list` | 列出各屏的桌面与当前所在 |
| `space-goto` | 切换桌面 |
| `space-move` | 把窗口移到别的桌面 |
| `volume` | 读/设系统音量与静音 |
| `media` | 发送系统媒体键（播放/暂停/上下曲）；status 读当前谁在播 |
| `brightness` | 读/设显示器亮度 |
| `clipboard` | 读/写剪贴板文本；--image <文件> 写图片、--out <文件> 存出剪贴板里的图、--info 只看类型 |
| `wifi` | 读/开关 Wi-Fi |
| `screen-list` | 列出显示器几何与可视区 |
| `input-source` | 读/列/切换输入法 |

用法与对外契约见技能内的 `SKILL.md` 与 `REFERENCE.md`。