agent-desktop完全指南：用OS辅助功能树让AI Agent告别像素猜测、可靠操作桌面

GUI 自动化AI 应用桌面应用AI 技能【免费下载链接】agent-desktopAgent Desktop gives any agent reliable computer use on the desktop. Built with Rust, it sees any apps real UI structure through OS accessibility trees and operates it — refs stay stable and actions stay safe to retry, instead of guessing from pixels.项目地址https://gitcode.com/gh_mirrors/ag/agent-desktop点击查看免费下载agent-desktop 是一款用 Rust 编写的开源「Computer Use」工具它让任意 AI Agent 通过操作系统的**辅助功能树Accessibility Tree**直接读取并可靠操作桌面应用——refs 标识稳定、操作可安全重试彻底告别从像素截图中猜UI 的时代。为什么 AI Agent 要看懂辅助功能树而不是猜像素当前主流的 AI 桌面自动化方案大多是看截图 → 估坐标 → 点一下痛点很明显 像素猜测误差大窗口稍动就点错位置 失败后不知道点击是否真的生效盲目重试可能造成重复提交 密集应用Slack、VS Code截屏信息量巨大token 消耗惊人。agent-desktop 换了一条路直接读取 OS 暴露的辅助功能树——每个按钮、输入框、菜单项都有明确的 role角色、state状态和位置。Agent 拿到的不是像素坐标而是带稳定标识的结构化元素。一句话概括 README.md 中的定义gives any agent reliable computer use on the desktop。工作原理观察 → 决策 → 行动 → 验证循环整个机制可以概括为一个循环完整讲解见 skills/agent-desktop/SKILL.mdsnapshot快照 → decide决策 → act行动 → snapshot再观察 → ...三个核心概念建议花 1 分钟理解概念说明出处Snapshot快照某一时刻辅助功能树的观察结果元素被分配 refCONCEPTS.mdRef元素引用形如s8f3k2p9:e7的紧凑标识内嵌快照 ID行动时精确锁定元素CONCEPTS.mdSession会话磁盘上的命名空间隔离多 Agent 的快照与 trace 记录CONCEPTS.md行动前还有一道可行动性预检Actionability可见性、稳定性、启用状态等全部通过才会真正派发CONCEPTS.md——这就是操作可安全重试的来源。一键安装步骤3 种方式 30 秒上手方式一npm 全局安装推荐自动下载预编译二进制npm install -g agent-desktop方式二免安装直接体验npx agent-desktop snapshot --app Finder -i方式三源码编译需 Rust 1.89、macOS 13.0git clone https://gitcode.com/gh_mirrors/ag/agent-desktop cd agent-desktop cargo build --releasemacOS 还需要在系统设置 → 隐私与安全性中授予终端辅助功能权限截图需要屏幕录制权限。用下面命令可一键检测并申请缺失权限不会静默弹窗agent-desktop permissions --request 平台支持现状macOS 功能完整Windows / Linux 正在按同一核心契约适配中README.md。核心工作流像 Agent 一样操作 Finder下面的演示动图assets/Tutorial.gif展示了一个真实 Agent 通过 agent-desktop 编写并执行任务的完整过程最典型的「观察-行动」循环长这样# 1. 快照获取可交互元素带 ref agent-desktop snapshot --app Finder -i # 2. 行动按 ref 点击、输入 agent-desktop click s8f3k2p9:e3 agent-desktop type s8f3k2p9:e5 quarterly report # 3. 键盘快捷键 agent-desktop press cmds # 4. 再观察验证 UI 变化 agent-desktop snapshot -i常用命令速查表完整 58 个命令见 README.md场景命令 观察snapshot/find --role button/screenshot️ 交互click/type/select/toggle/scroll⌨️ 键盘press cmds/press escape 窗口launch/close-app/focus-window/resize-window⏳ 等待wait --element ref --predicate actionable 剪贴板clipboard-get/clipboard-set/clipboard-clear 通知macOSlist-notifications/dismiss-notification默认是headless无头模式只走辅助功能语义 API不移动光标、不抢焦点、不动剪贴板需要真实物理输入时加--headed即可。省 Token 大招渐进式骨架遍历让 AI Agent 少读 98%密集应用的完整快照动辄几万 token。agent-desktop 提供「骨架概览 按需下钻」策略先用 3 层浅快照拿到 UI 地图再只展开目标区域。以 Slack 为例3 次采集中位值完整快照约30,743 tokens骨架概览仅383 tokens节省 98.8%再下钻到输入框区域约1,440 tokensbenchmarks/skeleton/ 还有更直观的对比图含 250K 上下文窗口的续航估算骨架下钻让 Agent 可工作时长延长约 10 倍# 1. 浅层骨架地图 agent-desktop snapshot --skeleton --app Slack -i --compact # 2. 下钻到感兴趣的区域e3 是骨架中的区域 ref agent-desktop snapshot --root e3 --snapshot s8f3k2p9 -i --compact # 3. 对下钻出的元素执行动作 agent-desktop click e12 --snapshot s8f3k2p9 何时跳过骨架元素很少的简单应用计算器、TextEdit或已知道目标名称时直接用find更快。可靠性契约ref 过期了为什么也不慌这是 agent-desktop 区别于坐标点击工具的核心设计完整描述在 README.md 的 Ref System 一节严格 ref 解析每次行动前用保存的身份证据窗口、路径、角色、bounds重新确认元素缺失/变化返回STALE_REF多候选返回AMBIGUOUS_TARGET从不瞎猜可行动性预检派发前检查可见、稳定、启用等状态不满足直接结构化报错送达语义Delivery Semantics失败时明确告诉你输入是否已送达——未送达可放心重试可能送达则提示先验证避免重复提交CONCEPTS.md交互租约全机器同一时刻只有一个进程派发输入多 Agent 并发不会互相穿插。标准恢复循环snapshot → act → 遇到 STALE_REF → 重新 snapshot → 用新 ref 重试想回放整个会话的每一步会话自带 trace 时间线agent-desktop trace show --limit 500 # 有界的 JSON 时间线 agent-desktop trace export --out run.html # 单文件 HTML 回放内嵌截图项目结构导读目录内容crates/core/src/核心逻辑快照、refs 分配、可行动性、tracecrates/macos/src/macOS 辅助功能适配器当前主力平台crates/ffi/C-ABI 动态库供 Python / Go / Ruby / Node 进程内调用src/CLI 入口、命令分发、批量执行skills/agent-desktop/给 AI 的 Skill 文档观察 / 交互 / 系统命令详解tests/e2e/端到端场景测试真实应用可靠性验证benchmarks/locator-resolution/元素解析性能基准其他延伸阅读概念词汇表CONCEPTS.md——Snapshot、Ref、Session、Actionability 的精确定义JSON 输出契约docs/json-output.md常见问题docs/faq.mdFFI 语言绑定指南skills/agent-desktop-ffi/SKILL.md常见问题FAQQagent-desktop 本身是 AI 吗不是。它只是 Agent 调用的工具输入命令输出结构化 JSON。观察-决策循环在你自己的 Agent 里。Q和 Playwright / Puppeteer 是什么关系互补。Chromium 应用可以用launch --cdp开启已验证的 CDP 端口交给 Playwright 等框架操作网页内容而原生菜单、对话框、窗口管理仍走辅助功能路径。Q操作失败会重复执行吗不会盲目重试。每个错误都带error_code和恢复提示并标注输入是否已送达由 Agent 据此决定安全策略。QLinux / Windows 能用吗核心逻辑平台无关macOS 适配器目前功能最全Windows / Linux 正在按同一核心契约适配中README.md。总结可靠桌面操作靠这三件套agent-desktop 用三样东西换来了桌面自动化的可靠二字辅助功能树代替像素猜测——看到的是结构化 UI不是截图快照 refs的稳定标识体系——ref 过期就重新快照永远不瞎点可行动性预检 送达语义——失败也能判断能否安全重试。如果你正在构建桌面 Agent、自动化测试或 RPA 流程一条npm install -g agent-desktop就能开始体验观察 → 决策 → 行动 → 验证的完整循环。赞分享GUI 自动化AI 应用桌面应用AI 技能【免费下载链接】agent-desktopAgent Desktop gives any agent reliable computer use on the desktop. Built with Rust, it sees any apps real UI structure through OS accessibility trees and operates it — refs stay stable and actions stay safe to retry, instead of guessing from pixels.项目地址https://gitcode.com/gh_mirrors/ag/agent-desktop点击查看免费下载相关推荐告别命令行Goose桌面应用让AI助手可视化操作告别命令行Goose桌面应用让AI助手可视化操作 你是否还在为AI助手复杂的命令行操作而头疼是否希望像使用普通软件一样通过鼠标点击就能完成AI任务Goos人工智能大模型AI AgentAI 应用本地部署MCP ClientsMCP 服务工具调用桌面应用CLI告别操作障碍Termux辅助功能全解析与实用指南告别操作障碍Termux辅助功能全解析与实用指南 在移动设备上实现完整的Linux终端体验Termux作为Android平台的强大终端模拟器为开发者和技术移动开发CLI操作系统Trae Agent轨迹记录功能详解任务执行过程可视化Trae Agent轨迹记录功能详解任务执行过程可视化 引言告别黑箱调试掌控LLM代理执行全流程 你是否曾遭遇LLM代理执行任务时卡壳却无从排查人工智能大模型AI AgentAgent 框架代码智能体CLI工具调用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考