agent-desktop

CLI工具，使AI代理能够通过原生操作系统无障碍树观察和控制桌面应用程序。

核心原则： agent-desktop 不是AI代理。它是AI代理调用的工具。它输出带有基于引用的元素标识符的结构化JSON。观察-行动循环存在于调用代理中。

安装

bash
npm install -g agent-desktop

或

需要macOS 12+，且终端已授予无障碍权限。

参考文件

详细文档分为多个重点参考文件。按需阅读：

观察-行动循环

每个自动化都遵循此模式：

1. 1. 观察 → agent-desktop snapshot --app App Name -i
2. 推理 → 解析JSON，通过引用（@e1、@e2...）查找目标元素
3. 行动 → agent-desktop click @e5（或type、select、toggle...）
4. 验证 → 再次运行agent-desktop snapshot确认状态变化
5. 重复 → 继续直到任务完成

始终在行动前进行快照。引用是快照作用域的，UI变化后失效。

引用系统

• - 引用按深度优先分配：@e1、@e2、@e3...
• 只有交互元素获得引用：按钮、文本字段、复选框、链接、菜单项、选项卡、滑块、组合框、树项、单元格
• 静态文本、组、容器保留在树中作为上下文，但没有引用
• 引用在快照内是确定性的，但如果UI发生变化，跨快照不稳定
• 任何改变UI的操作后，重新运行snapshot获取新引用

JSON输出契约

每个命令在标准输出上返回JSON信封：

成功： { version: 1.0, ok: true, command: snapshot, data: { ... } }
错误： { version: 1.0, ok: false, command: click, error: { code: STALE_REF, message: ..., suggestion: ... } }

退出码：0成功，1结构化错误，2参数错误。

错误码

命令快速参考（54个命令）

观察

agent-desktop snapshot --app App -i # 带引用的无障碍树
agent-desktop screenshot --app App out.png # PNG截图
agent-desktop find --app App --role button # 搜索元素
agent-desktop get @e1 --property text # 读取元素属性
agent-desktop is @e1 --property enabled # 检查元素状态
agent-desktop list-surfaces --app App # 可用表面

交互

agent-desktop click @e5 # 点击元素
agent-desktop double-click @e3 # 双击
agent-desktop triple-click @e2 # 三击（选择行）
agent-desktop right-click @e5 # 右键点击（上下文菜单）
agent-desktop type @e2 hello # 向元素输入文本
agent-desktop set-value @e2 new value # 直接设置值
agent-desktop clear @e2 # 清除元素值
agent-desktop focus @e2 # 设置键盘焦点
agent-desktop select @e4 Option B # 选择下拉选项
agent-desktop toggle @e6 # 切换复选框/开关
agent-desktop check @e6 # 幂等勾选
agent-desktop uncheck @e6 # 幂等取消勾选
agent-desktop expand @e7 # 展开披露控件
agent-desktop collapse @e7 # 折叠披露控件
agent-desktop scroll @e1 --direction down # 滚动元素
agent-desktop scroll-to @e8 # 滚动到视图中

键盘与鼠标

agent-desktop press cmd+c # 组合键
agent-desktop press return --app App # 定向按键
agent-desktop key-down shift # 按住键
agent-desktop key-up shift # 释放键
agent-desktop hover @e5 # 光标移到元素
agent-desktop hover --xy 500,300 # 光标移到坐标
agent-desktop drag --from @e1 --to @e5 # 元素间拖放
agent-desktop mouse-click --xy 500,300 # 在坐标处点击
agent-desktop mouse-move --xy 100,200 # 移动光标
agent-desktop mouse-down --xy 100,200 # 按下鼠标按钮
agent-desktop mouse-up --xy 300,400 # 释放鼠标按钮

应用与窗口

agent-desktop launch System Settings # 启动并等待
agent-desktop close-app TextEdit # 优雅退出
agent-desktop close-app TextEdit --force # 强制终止
agent-desktop list-windows --app Finder # 列出窗口
agent-desktop list-apps # 列出运行中的GUI应用
agent-desktop focus-window --app Finder # 置于前台
agent-desktop resize-window --app App --width 800 --height 600
agent-desktop move-window --app App --x 0 --y 0
agent-desktop minimize --app App
agent-desktop maximize --app App
agent-desktop restore --app App

通知

agent-desktop list-notifications # 列出所有通知
agent-desktop list-notifications --app Slack # 按应用筛选
agent-desktop list-notifications --text deploy --limit 5 # 按文本筛选
agent-desktop dismiss-notification 1 # 按索引关闭
agent-desktop dismiss-all-notifications # 关闭所有
agent-desktop dismiss-all-notifications --app Slack # 关闭应用的所有通知
agent-desktop notification-action 1 --action Reply # 点击操作按钮

剪贴板

agent-desktop clipboard-get # 读取剪贴板
agent-desktop clipboard-set text # 写入剪贴板
agent-desktop clipboard-clear # 清空剪贴板

等待

agent-desktop wait 1000 # 暂停1秒
agent-desktop wait --element @e5 --timeout 5000 # 等待元素
agent-desktop wait --window Title # 等待窗口
agent-desktop wait --text Done --app App # 等待文本
agent-desktop wait --menu --app App # 等待上下文菜单
agent-desktop wait --menu-closed --app App # 等待菜单关闭
agent-desktop wait --notification --app App # 等待新通知

系统

agent-desktop status # 健康检查
agent-desktop permissions # 检查权限
agent-desktop permissions --request # 触发权限对话框
agent-desktop version --json # 版本信息
agent-desktop batch [...] --stop-on