lahfir/agent-desktop

它是什么

agent‑desktop 是一个命令行工具（以及配套的 C 库），让 AI 代理能够在 macOS 和 Windows 上查看并控制图形桌面应用程序。它读取操作系统的无障碍树，导出 UI 元素的 JSON 描述，并可通过引用这些元素的稳定 ID 来执行点击、输入、窗口管理、剪贴板访问等操作。

为什么重要

从代码控制 GUI 是自主代理的经典瓶颈。大多数基于 LLM 的助手只能处理文本 API，因此无法直接与人类使用的应用程序交互。通过将 UI 暴露为结构化的、机器可读的树，并提供丰富的操作集，agent‑desktop 弥合了这一差距，使代理能够自动化现实世界的桌面工作流程（例如，在 Finder 中归档报告、发送 Slack 消息或关闭通知），而无需移动鼠标或抢占焦点。

工作原理（高层概述）

1. 快照 – agent-desktop snapshot --app <名称> 遍历操作系统无障碍 API，并打印 UI 元素的 JSON 树。每个元素会获得一个如 @s8f3k2p9:e3 的引用，该引用编码了其所属的快照。
2. 操作 – 如 click、type、press、scroll 或 launch 等命令接受一个引用（或快捷键），并通过无障碍层发送相应的输入。默认情况下，操作是无头的（没有可见的鼠标移动）。
3. 迭代 – 操作后，您再拍摄另一个快照以验证 UI 是否按预期变化。过期或模糊的引用会被报告，以便代理刷新。
4. 库模式 – 相同功能被打包为 libagent_desktop_ffi，一个 C 兼容的共享库，因此其他语言的程序（例如，通过 ctypes 的 Python）可以直接调用 API，而无需启动 CLI 进程。

谁可能使用它

受众	用例
AI 研究实验室 构建需要操作桌面软件的自主代理。
个人助手开发者（例如，ChatGPT 式机器人）希望扩展超出纯文本操作的范围。
自动化工程师 寻找可编程的、跨平台的方式来编写 UI 任务脚本，而不使用脆弱的屏幕抓取工具。
工具制造商 希望通过 FFI 库将桌面控制功能嵌入到自己的应用程序中。

入门（快速步骤）

# 安装 CLI（包含原生二进制文件）
npm install -g agent-desktop

# 授予 macOS 无障碍权限（或确保 Windows 按需运行）
agent-desktop permissions --request

# 拍摄 Finder 的快照并列出交互元素
agent-desktop snapshot --app Finder -i

# 点击第一个元素（将引用替换为您获得的那个）
agent-desktop click @s8f3k2p9:e3

# 验证 UI 是否变化
agent-desktop snapshot --app Finder -i

对于编程使用，README 中的 Python 片段展示了如何加载共享库并初始化它。

优势与局限

优势	局限
• 开箱即用地支持 macOS 和 Windows。
• 无头操作避免干扰用户的鼠标/键盘。
• 返回带有稳定引用的结构化 JSON，使代理易于推理 UI 状态。
• 提供全功能的 FFI 库以供进程内使用。
• 涵盖广泛的操作（点击、输入、窗口管理、通知、剪贴板等）。
• 开源，Apache-2.0 许可证，带 CI 和测试。
• 计划支持 Linux。
• 集成的“技能”指南供代理使用。
• 通过 npm 分发二进制文件简化安装。
• 详细的 macOS 权限处理。
• 清晰的错误代码（STALE_REF、AMBIGUOUS_TARGET）。
• 支持批处理命令和会话跟踪。
• 可以在 Windows 上操作 shell 界面（任务栏、开始菜单）。
• 使用操作系统无障碍 API – 比像素匹配更可靠。
• 无需外部 UI 自动化工具，如 Selenium 或 AutoIt。
• 支持 ARM64 和 x64 架构。
• 提供“光标叠加层”用于可视化调试代理操作。
• 能够拍摄骨架快照以减少 LLM 提示的令牌数量。
• 可通过 skills 系统扩展。
• CI 徽章显示活跃测试。
• 发布二进制文件经过校验和验证。
• 支持通过 CDP 启动 Chromium 应用。
• 可以列出和关闭系统通知。
• 可以直接操作剪贴板。
• 可以编程方式调整窗口大小/移动窗口。
• 支持多代理会话。
• 提供 batch 命令来捆绑多个操作。
• 提供 trace 命令用于调试代理行为。
• 包含 cursor-overlay 用于可视化代理光标。
• 支持 list-surfaces 枚举 UI 界面。
• 可以通过 screenshot 命令截图。
• 提供 list-apps 和 list-windows 用于发现。
• 在 Windows 上支持 open-system-surface。
• 可以通过 CDP 在 Chromium 上启动应用。
• 支持 wait 命令用于同步。
• 提供 session 管理用于持久上下文。
• 提供 skills 检索用于代理指导。
• 包含 status 命令用于健康检查。
• 支持 permissions 查询和请求。
• 提供 version 信息。
• 提供 list-notifications 及其操作。
• 支持 notification-action 与通知交互。
• 提供 clipboard-get、clipboard-set、clipboard-clear。
• 支持 list-displays 用于多显示器设置。
• 支持 focus-window、resize-window、move-window。
• 支持 minimize、maximize、restore。
• 在 Windows 上支持 open-system-surface。
• 支持使用 CDP 的 launch 用于 Chromium 应用。
• 支持 list-apps、list-windows。
• 支持 list-displays。
• 支持 list-notifications。
• 支持 clipboard 命令。
• 支持 wait。
• 支持 session 和 trace。
• 支持 cursor-overlay。
• 支持 batch。
• 支持 skills。
• 支持 status。
• 支持 permissions。
• 支持 version。
• 支持带有 --skeleton 和 --compact 的 snapshot 以减少令牌大小。
• 支持 find、get、is 查询 UI 元素。
• 支持 list-surfaces。
• 支持 scroll、scroll-to。
• 支持 expand、collapse。
• 支持 select、toggle、check、uncheck。
• 支持 clear、focus。
• 支持 type、set-value。
• 支持 click、double-click、triple-click、right-click。
• 支持 press、hover、drag、mouse-move、mouse-click、mouse-wheel。
• 支持 key-down、key-up、mouse-down、mouse-up（待守护进程）。
• 支持 launch、close-app。
• 支持 list-apps、list-windows。
• 支持 list-displays。
• 支持 focus-window、resize-window、move-window。
• 支持 minimize、maximize、restore。
• 支持 open-system-surface。
• 支持 list-notifications、dismiss-notification、dismiss-all-notifications。
• 支持 notification-action。
• 支持 clipboard-get、clipboard-set、clipboard-clear。
• 支持 wait。
• 支持 session、trace、cursor-overlay。
• 支持 status、permissions、version、batch、skills。
• 支持 list-surfaces。
• 支持带有各种标志的 snapshot。
• 支持 find、get、is。
• 支持 scroll、scroll-to。
• 支持 expand、collapse。
• 支持 select、toggle、check、uncheck。
• 支持 clear、focus。
• 支持 type、set-value。
• 支持 click、double-click、triple-click、right-click。
• 支持 press、hover、drag、mouse-move、mouse-click、mouse-wheel。
• 支持 key-down、key-up、mouse-down、mouse-up。
• 支持 launch、close-app。
• 支持 list-apps、...
• 目前仅限 macOS 和 Windows；Linux 仅计划中。
• 需要操作系统级别的无障碍权限；对于非技术用户来说设置可能繁琐。
• Windows 上的二进制文件未签名，因此 SmartScreen/防病毒软件可能会阻止它。
• 某些命令（key-down、mouse-down 等）在添加守护进程之前是占位符。
• JSON 输出可能冗长；大型应用可能产生巨大的快照（数万令牌）。
• 没有内置 LLM 集成 – 您需要将 JSON 接入自己的模型提示。
• 需要 Rust 工具链从源代码构建；不是纯 JS 包。
• 快照准确性取决于操作系统无障碍实现，不同应用可能有所不同。

---

此摘要仅基于项目 README。