Agent Desktop
让 AI 通过无障碍树可靠地观察和操作 macOS 桌面应用。
最小权限处理充分：CI 默认清空权限并按作业授予只读或安全事件写入权限，普通权限检查不触发提示，请求权限由隔离辅助进程完成；默认引用动作采用无界面语义路径，物理输入及通知变更需要显式 --headed。用户确认仍扣分，因为启动、关闭应用、键盘、剪贴板和多数可变更动作一经调用不会逐次确认。数据流说明较清楚，包括会话文件位置、JSONL 跟踪、截图嵌入 HTML、输出覆盖路径以及仅绑定 127.0.0.1 的 CDP 端点和本地进程可访问风险。敏感数据处理只达到一般水平：文档提醒完整跟踪导出应按截图对待，但未展示统一的脱敏、加密、保留期限或安全清除策略。依赖安全证据较强，CI 使用 Cargo.lock、--locked、固定提交的 GitHub Actions、CodeQL 和私密漏洞报告流程；但没有展示依赖漏洞扫描结果。外部效果边界、headed 模式、强制退出语义、通知指纹及动作前检查均有明确说明。回滚能力薄弱：主要依赖重新观察、幂等操作或应用自身撤销，除测试报告可恢复移入废纸篓外，没有通用事务回滚。仓库、包名、许可证和报告渠道可归因，但发布者身份未验证且材料未明确个人或组织维护者，因此来源归属未满分。
README、Cargo 元数据和 CI 对 Rust 版本、产品版本、平台范围、FFI、权限和发布构件的描述高度一致，并设置发布元数据一致性检查、跨平台检查、单元测试及 FFI 边界守卫。依赖可获得性有 npm、源码构建和预编译构件说明，然而当前实际桌面自动化仅支持 macOS，Linux/Windows 是计划状态，且未提供锁文件内容或安装器源码供本次核查，因此扣分。失败消息设计充分，包含结构化 JSON、错误码、退出码、恢复提示、STALE_REF、AMBIGUOUS_TARGET、ACTION_NOT_SUPPORTED、ACTION_FAILED 和权限状态；未因未执行这些路径而扣分。
目标受众、AI 观察—行动循环、简单与密集应用、多代理会话、FFI 消费者及 Chromium 混合自动化场景均有具体指导。能力边界明确区分 macOS 已支持与其他平台计划项、语义与物理操作、无头与 headed 模式、保留但不支持的按键或鼠标状态命令，以及 CDP 必须全新启动等限制。触发精度较高：限定会话命名空间、限定快照引用、动作前可操作性检查、歧义时拒绝猜测，通知变更还要求同次列表所得指纹。环境适配因桌面能力目前集中于 macOS 13+ 且需要系统辅助功能权限而扣分；Linux 和 Windows 虽有 crate、CI 检查及 FFI 构件，但产品功能表仍标为计划中。
信息架构完整，README 将架构、安装、权限、工作流、命令族、JSON 契约、引用系统、平台支持、开发和 FAQ 分区，并链接更深层文档。安装说明覆盖 npm、npx、源码构建、Rust/macOS 前提和系统权限。命名及兼容策略明确，包括限定引用、旧裸引用的显式快照要求、稳定命令名和 ABI 主版本验证。示例覆盖主要命令和恢复流程，并提供 FAQ 入口。已知限制披露充分，包括平台缺口、保留命令、headed 副作用、CDP 暴露、会话并发注意事项和 FFI 测试覆盖缺口。Apache-2.0 元数据与完整许可证一致。版本号、发布入口和发布一致性检查存在，但所给材料没有独立变更日志或明确兼容周期，故版本变更项扣分。SECURITY.md 给出私密报告范围及维护者响应承诺，但未列明具体维护者、支持时限或治理与继任安排。
结构化 JSON、版本化信封、错误与恢复提示、确定范围的快照引用、渐进式遍历、批处理、等待条件和可读取跟踪记录，使输出非常适合代理消费。相对于截图和像素匹配，该工具提供可访问性树、稳定引用、原生窗口表面与可选 CDP 的组合，具有明确的额外价值。成本收益扣分是因为 78–96% 和 97% token 节省属于材料中的定量宣称，本次所给文件没有包含相应结果数据；此外部署受 macOS 权限、目标应用可访问性质量和 headed 操作副作用约束。
大量行为声明可追到具体命令契约、配置、CI 作业和测试工具，例如权限隔离、FFI panic 边界、版本一致性、输出限制及平台矩阵；但部分被引用的深层文档、源码实现、Cargo.lock 和测试结果未包含，定量 token 节省也缺少所给材料内的原始证据，因此声明可追溯性未满分。跨来源一致性很强：README、Cargo.toml、SECURITY.md、CI 和测试脚本相互支持版本、权限、边界、防护和测试范围。事实与推断大多通过“Planned”“Phase 1”、已知 FFI 覆盖缺口及风险提示分开陈述，但营销性的“works with any app”和节省比例没有在相邻位置充分限定证据基础，因此扣分。
- 桌面自动化当前实际仅支持 macOS；不要把 Linux/Windows crate、CI 检查或 FFI 构件误解为完整的平台功能支持。
- 辅助功能权限可读取和操纵其他应用界面；应使用专用低权限账户，并在执行关闭应用、键盘、剪贴板、通知或 headed 操作前由上层代理实施确认策略。
- 会话跟踪、截图和导出的单文件 HTML 可能包含敏感界面数据；材料未展示统一的脱敏、加密、保留期限或安全删除机制。
- CDP 虽仅绑定 127.0.0.1，但同一用户下的其他本地进程仍可访问；使用后应关闭目标应用以终止暴露。
- 定量 token 节省和“适用于任何应用”的表述未由所给文件中的原始测量或兼容性矩阵充分证明。
- 本评估仅审阅所给静态材料，未执行二进制、测试、安装器或自动化动作。
这个 Agent 能做什么，适合哪些场景？
Agent Desktop 是一个用 Rust 编写的原生桌面自动化 CLI，面向需要控制图形界面的 AI 智能体。它读取 macOS 无障碍树，以结构化 JSON 返回应用、窗口和元素状态，并为可交互元素生成与快照绑定的确定性引用。智能体可以通过这些引用执行点击、输入、选择、滚动、窗口管理、通知和剪贴板等操作，再重新拍摄快照验证结果。项目同时提供命令行程序和 C-ABI 动态库 libagent_desktop_ffi，后者可由 Python、Swift、Go、Ruby、Node 或 C 进程内调用。会话系统能够维护快照命名空间、记录 JSONL 轨迹并导出包含时间线和截图的单文件 HTML。实际桌面自动化目前只支持 macOS；Windows 和 Linux 的动态库随发行版提供，但对应的无障碍与交互能力仍标为规划中。
典型流程是运行 agent-desktop snapshot 读取目标应用的无障碍树，保存返回的 snapshot_id 和限定引用（如 @s8f3k2p9:e3），随后调用 click、type、set-value、select、toggle、scroll 等命令操作元素，并再次执行 snapshot 检查变化。--skeleton 先生成三层概览，再通过 --root 钻取目标区域，适合 Slack、VS Code 或 Notion 等密集界面。工具还可截图、查找和读取元素属性，发送快捷键，管理应用与窗口，处理剪贴板及 macOS 通知，并通过 wait 等待元素、窗口、文本或通知出现。session start 创建带自动 JSONL 轨迹的显式会话，trace show 汇总时间线，trace export 生成静态 HTML。对于 Chromium 应用，launch --cdp 可启动并验证仅监听 127.0.0.1 的 DevTools 端点，供 Playwright、Puppeteer、chrome-remote-interface 或 agent-browser 驱动网页内容；原生菜单、对话框和窗口仍走无障碍路径。
- 构建 macOS 操作智能体的开发者，需要让模型以 JSON 观察 Finder、Safari、系统设置或 Xcode，并通过稳定的元素引用执行动作。
- 自动化 Slack、VS Code、Notion 等大型界面的团队，希望用浅层骨架和定向钻取减少传给模型的界面树数据量。
- 测试或运维人员需要跨原生界面完成启动应用、等待窗口、填写字段、点击按钮并验证最终状态的可追踪工作流。
- 开发 Python、Swift、Go、Ruby、Node 或 C 宿主程序的工程师，希望通过 libagent_desktop_ffi 复用已加载的原生库，避免每个操作都派生 CLI 进程。
- 同时处理 Electron/Chromium 网页内容与原生菜单、文件对话框的自动化系统，可将 CDP 客户端与无障碍操作组合使用。
- 需要复盘多步骤桌面任务的团队，可用显式会话记录 JSONL 片段，并导出带截图的单文件 HTML 轨迹。
这个 Agent 有哪些优点和局限？
- 以无障碍树和结构化 JSON 为核心，不依赖截图识别、像素匹配或浏览器即可操作原生应用。
- 限定引用包含精确快照 ID，动作前还会重新识别目标并检查可操作性；过期或歧义目标会明确返回
STALE_REF或AMBIGUOUS_TARGET。 - 渐进式骨架遍历针对密集应用，README 给出的数据缩减范围为 78–96%，可降低界面上下文的令牌占用。
- 同时提供单一 Rust 二进制和 C-ABI 动态库，支持 CLI 子进程模式与多种语言的进程内集成。
- 显式会话可自动记录分段 JSONL 轨迹，并能将时间线和截图导出为单文件 HTML。
- Chromium 应用可通过经验证的本地 CDP 端点处理网页内容，同时保留对原生窗口、菜单和对话框的无障碍控制。
- 实际无障碍树、输入、截图、剪贴板、窗口管理和通知能力目前仅支持 macOS；Windows 与 Linux 均标为规划中。
- 部署至少需要 macOS 13.0 和无障碍权限；截图及通知中心功能还会增加屏幕录制和自动化权限配置成本。
- 默认无头引用操作强调语义和避免焦点副作用，但悬停、拖动、坐标点击、双击及三击等物理操作必须使用
--headed。 key-down、key-up、mouse-down和mouse-up只是保留命令名，在无状态 CLI 中会返回ACTION_NOT_SUPPORTED。- 引用属于特定会话命名空间，界面变化可能产生
STALE_REF或AMBIGUOUS_TARGET，调用方必须实现重新观察与重试逻辑。 launch --cdp要求目标应用全新启动；已经运行的应用会返回ACTION_FAILED，而且开放端点期间同一用户的其他本地进程也能访问它。
如何安装或部署这个 Agent？
推荐通过 npm 安装预编译二进制：
npm install -g agent-desktop也可直接运行：
npx agent-desktop snapshot --app Finder -i从源码构建需要 Rust 1.89+ 和 macOS 13.0+：
git clone https://github.com/lahfir/agent-desktop
cd agent-desktop
cargo build --release
cp target/release/agent-desktop /usr/local/bin/运行桌面自动化前需授予 macOS 无障碍权限；截图还需屏幕录制权限，打开通知中心还需针对 System Events 的自动化权限。可先检查 agent-desktop permissions，再用 agent-desktop permissions --request 在隔离辅助进程中请求缺失权限。日常运行不需要 README 所述的模型 API 凭据。
如何使用这个 Agent？
先检查环境：
agent-desktop status
agent-desktop permissions最小可用流程：
agent-desktop snapshot --app Finder -i从输出中保留 snapshot_id 和元素引用，然后执行类似：
agent-desktop click @s8f3k2p9:e3
agent-desktop type @s8f3k2p9:e5 "quarterly report"
agent-desktop snapshot --app Finder -i密集应用可先运行：
agent-desktop snapshot --skeleton --app Slack -i --compact
agent-desktop snapshot --root @e3 --snapshot s8f3k2p9 -i --compact如需轨迹，运行 agent-desktop session start --screenshots，把返回的会话 ID 设置为 AGENT_DESKTOP_SESSION，完成操作后用 agent-desktop trace show --limit 500 查看记录，或用 agent-desktop trace export --out run.html 导出。引用失效或目标不唯一时，应重新等待或拍摄快照，并用新引用重试。
这个 Agent 与同类方案有什么区别？
与基于截图和像素匹配的桌面自动化相比，Agent Desktop 主要读取无障碍树并输出可定位的 JSON 元素，因此更适合模型按语义观察和操作界面；截图仍是可选能力。对于 Chromium 应用，它不取代 Playwright、Puppeteer、chrome-remote-interface 或 agent-browser，而是通过 launch --cdp 让这些工具驱动网页内容，同时自己处理原生菜单、对话框和窗口。README 将 agent-browser列为偏好的 CDP 智能体工作流，但未提供性能或可靠性的直接对比测试。
常见问题
是否支持 Windows 或 Linux 桌面自动化？
运行时需要哪些 macOS 权限？
permissions --request 请求缺失权限。元素引用在界面变化后仍可靠吗？
STALE_REF，多个候选目标会返回 AMBIGUOUS_TARGET；此时应重新等待或拍摄快照。