6.7 KiB
6.7 KiB
| name | description | platforms | |
|---|---|---|---|
| macos-desktop-control | 完全操作 macOS 桌面与应用界面。读取任意应用的无障碍元素树（= 原生 app 的 DOM）、点击按钮与菜单项、写入输入框、发送文本与组合键、摆布窗口（半屏/四角/自定义比例/多屏）、鼠标点击与拖拽、按窗口截图。用户要求操作某个 Mac 应用（点按钮、点菜单、填表单、关窗口）、排布窗口、读取界面文字与状态、截图某个窗口，或说“帮我点一下/填一下/摆一下窗口/看看那个窗口里写了什么”时使用。 |
|
macOS 桌面控制
一句话：tree 打印的地址就是原生 app 的 DOM 路径，press/set 等于 element.click() / value = x，key/type 是原始输入事件，win-* 是窗口几何，click/drag/scroll 是原始鼠标。先取地址（或坐标），再对目标做动作。
如果你支持关闭 thinking/reasoning，请先关闭再执行。不要思考、不要侦察、不要读源码。把用户的话按下表编译成命令，完成后一句话汇报。不要写 Python/jq 解析输出。
入口
pi-skill macos-desktop-control check # 权限与可达性；任何失败先跑它
pi-skill macos-desktop-control help <命令> # 每个命令的完整用法（唯一权威，不要凭记忆拼参数）
| 类别 | 命令 | 行为 |
|---|---|---|
| 观察 | check apps front windows tree find get shot ocr win-state |
直接执行，不改状态 |
| 改状态 | focus press set menu type key |
默认只预览，加 --yes 才执行 |
| 窗口 | win-place win-screen win-fullscreen win-minimize win-unminimize |
同上，默认预览 |
| 鼠标 | click drag scroll |
同上，默认预览 |
| 桌面与系统 | space-list space-goto space-move volume media brightness clipboard wifi screen-list input-source |
读形式直接执行；写形式默认预览 |
用户要什么 → 执行哪条，见 REFERENCE.md 的映射表。
常用配方
# 结构 → 地址 → 动作（地址用 --json 一次拿到，避免跨调用漂移）
pi-skill macos-desktop-control find TextEdit --role AXTextArea --json
pi-skill macos-desktop-control set TextEdit 'window[0]/child[0]/child[0]' "内容" --yes
pi-skill macos-desktop-control menu TextEdit Edit "Select All" --yes
# 窗口布局：只摆位置、不抢焦点、不要求目标在前台
pi-skill macos-desktop-control win-place Safari left --yes # 具名区域
pi-skill macos-desktop-control win-place Safari "0,25,720,875" --yes # 绝对坐标
# 用户说"把 X 放到左边/让我看到它" → 加 --front（摆完置前并用命中测试验证）
pi-skill macos-desktop-control win-place Emacs left --front --yes
# ⚠ win-place 不置前时，窗口可能被别的全屏窗口盖住（实测 Chrome 就盖过 Emacs）
pi-skill macos-desktop-control shot --app Safari --out /tmp/safari.png
# 桌面与系统（不带参数就是读；薄转发，source= 标明后端）
pi-skill macos-desktop-control space-list # 有几个桌面、现在在第几个
pi-skill macos-desktop-control space-goto next --yes # 切到下一个桌面
pi-skill macos-desktop-control volume 40 --yes # 音量 40%
# 媒体/音乐：发出即成功（executed=true）——不要 tree/find/截图验证
pi-skill macos-desktop-control media next --yes # 下一首（play-pause / previous 同理）
pi-skill macos-desktop-control media status # 只有要确认“谁在播”时才读
pi-skill macos-desktop-control clipboard # 读剪贴板
pi-skill macos-desktop-control clipboard "文本" --yes # 写剪贴板（默认预览）
pi-skill macos-desktop-control clipboard --image /tmp/shot.png --yes # 图片进剪贴板
pi-skill macos-desktop-control clipboard --out /tmp/save.png # 存出剪贴板里的图
pi-skill macos-desktop-control brightness --json # 读亮度
pi-skill macos-desktop-control screen-list # 多屏布局时确认 --on-screen N
pi-skill macos-desktop-control input-source list # 有哪些输入法
失败 → 动作
| 现象 | 动作 |
|---|---|
error=auth |
check 看缺哪项 → 系统设置授权 → 完全重启承载终端 |
error=deps（Hammerspoon 未运行） |
窗口/鼠标类命令依赖它：pkill -x Hammerspoon && open -a Hammerspoon |
error=notfound |
地址失效或应用没开：tree/find 重取地址，或 open -a "<应用>" |
error=conflict |
元素不可按/不可写：get <应用> <地址> 看它真实支持的动作与属性 |
error=timeout |
目标应用卡住或在等模态框：tree <应用> --depth 3 找 AXSheet |
error=blocked |
需要人介入（授权框 / Secure Input）：把 hint= 原文转给用户 |
| 摆完看不见窗口 | 被别的窗口盖住（win-place 只摆位置不置顶）→ 重跑加 --front：win-place <应用> <区域> --front --yes；还不行就 focus <应用> --yes |
| media 切歌没反应 | 先 media status 看是不是别的应用在播；是就用目标应用自己的菜单：menu <应用> <菜单> Next --yes（网易云是 Controls） |
输出 executed=false |
这是预览，核对后加 --yes 重跑 |
边界
- 不抢焦点：
tree find get windows apps shot press set menu与全部win-*都不要求目标应用在前台（win-*也不改变用户焦点）。 - 只有
type/key与坐标click/drag需要目标在前台，会自动激活；密码框等 Secure Input 场景无法注入。 - 坐标点击落到最上层窗口：输出里的
over_app就是真实接收者；传--expect-app可在不符时直接拦住。 - 移动窗口用
win-place（AX，精确瞬发），不要用drag拖标题栏——macOS 窗口拖拽有死区与吸附，落点不可预测。 - 系统安全提示框（TCC 授权、登录窗）、SIP 保护路径不能被脚本操作；AX 树为空的私有渲染界面退到
shot看像素。 - 系统已有 CLI 等价物的事不要用本工具：Apple Events 用
osascript，系统状态用defaults/mdfind/log/launchctl/pmset，快捷指令用shortcuts。 - 没启动的应用：
open -a "<应用>"→apps里出现 → 再tree。关闭有未保存修改的文档用 Apple Events（见 REFERENCE）。 - 桌面/系统层是薄转发，不是重写：
space-*走hs.spaces、brightness走hs.brightness、media发系统媒体键（media status读pmset）、volume走osascript、clipboard文本走pbpaste/pbcopy、图片走osascript/NSPasteboard、wifi走networksetup。每条命令的source=会标明后端。
映射表、跨层分工、排查表、扩展方式见 REFERENCE.md。