Agent Desktop — 代理桌面

agent-desktop CLI 工具允许 AI 代理通过本机操作系统的无障碍树观察和控制桌面应用程序。核心原则：agent-desktop 不是 AI 代理，而是一个工具，AI 代理可以调用它。它输出带有基于引用元素标识符的结构化 JSON 数据。观察-操作循环存在于调用代理中。

安装：

npm install -g agent-desktop
# 或
bun install -g --trust agent-desktop

需要 macOS 12+ 并且授予终端无障碍权限。屏幕录制权限也需要用于截图。

参考文件： 详细文档分为专注的参考文件。按需阅读：

* 参考内容 + references/commands-observation.md：snapshot、find、get、is、screenshot、list-surfaces — 所有标志、输出示例 + references/commands-interaction.md：click、type、set-value、select、toggle、scroll、drag、keyboard、mouse — 选择正确的命令 + references/commands-system.md：launch、close、windows、clipboard、wait、batch、status、permissions、version + references/workflows.md：12 个常见模式：表单、菜单、对话框、滚动-查找、拖放、异步等待、反模式 + references/macos.md：macOS 权限/TCC、AX API 内部、智能激活链、表面、通知中心、故障排除

观察-操作循环（渐进骨架遍历）： 使用渐进骨架遍历作为默认方法。它通过两阶段探索 UI 来减少密集应用程序的令牌消耗：浅层骨架概述，然后针对感兴趣的区域进行有针对性的深入探索。

• 骨架 → agent-desktop snapshot --skeleton --app "App" -i --compact

解析概述。识别包含目标的区域。区域显示子元素数量（例如“Sidebar”具有 42 个子元素）。命名容器在截断边界具有用于深入探索的引用。保留返回的 snapshot_id。

• 深入探索 → agent-desktop snapshot --root @e3 --snapshot -i --compact

扩展目标区域。现在您可以看到其交互元素。

• 操作 → agent-desktop click @e12 --snapshot （或 type、select、toggle...）
• 验证 → agent-desktop snapshot --root @e3 --snapshot -i --compact

重新深入探索相同的区域以确认状态更改。范围无效：仅 @e3 的子树引用被替换。

• 重复 → 继续深入探索其他区域或根据需要进行操作。

何时跳过骨架并使用完整快照： 简单应用程序具有少量元素（Finder、Calculator、TextEdit） 您已经知道确切的元素名称 — 使用 find 代替 表面快照（菜单、表单、警报）— 这些已经聚焦 何时骨架发挥作用： 密集的 Electron 应用程序（Slack、VS Code、Discord、Notion） 任何应用程序的完整快照超过 ~50 个引用 多区域工作流（侧边栏 + 主内容 + 工具栏）

引用系统： 引用分配给深度优先：@e1、@e2、@e3... 仅交互元素获得引用：button、textfield、checkbox、link、menuitem、tab、slider、combobox、treeitem、cell 在骨架模式中，命名/描述容器在截断边界也获得引用（深入探索目标，具有空的 available_actions） 静态文本、组、容器保留在树中以提供上下文，但没有引用 引用在快照内是确定性的，但如果 UI 更改，则不稳定 每个快照返回快照 ID；引用消耗命令接受 --snapshot last_refmap.json 仅是一个最新快照的检查工件。命令路径使用快照范围存储。 在任何更改 UI 的操作之后，重新深入探索受影响的区域或重新快照 范围无效：重新深入探索 --root @e3 仅替换 @e3 的前一个深入探索的引用 — 其他区域和骨架本身的引用得到保留

JSON 输出合同： 每个命令在 stdout 上返回 JSON 信封： 成功：{ "version": "2.0", "ok": true, "command": "snapshot", "data": { ... } } 错误：{ "version": "2.0", "ok": false, "command": "click", "error": { "code": "STALE_REF", "message": "...", "suggestion": "..." } } 退出代码：0 成功，1 结构化错误，2 参数错误。 错误代码： 代码 含义 恢复 PERM_DENIED 无障碍或屏幕录制权限未授予 授予系统设置中的命名权限 ELEMENT_NOT_FOUND 引用无法解析为实时 UI 重新运行快照，使用新鲜的引用 APP_NOT_FOUND 应用程序未运行 首先启动它 ACTION_FAILED AX 操作被拒绝 尝试显式替代命令 ACTION_NOT_SUPPORTED 元素无法执行此操作 使用不同的命令 STALE_REF 来自旧快照的引用 重新运行快照 SNAPSHOT_NOT_FOUND 快照 ID 缺失或过期 再次运行快照并使用返回的 ID POLICY_DENIED 物理/头部路径被阻塞 如果物理交互是预期的，请使用显式鼠标/焦点/键盘命令 WINDOW_NOT_FOUND 没有匹配的窗口 检查应用程序名称，使用 list-windows PLATFORM_NOT_SUPPORTED 适配器方法未在此平台上实现 使用支持的平台适配器 TIMEOUT 等待条件未满足 增加 --timeout INVALID_ARG