企业官网建设流程全解析

• GUI 自动化
• AI 应用
• 桌面应用
• AI 技能

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.md）：

snapshot（快照） → decide（决策） → act（行动） → snapshot（再观察） → ...

三个核心概念，建议花 1 分钟理解：

行动前还有一道可行动性预检（Actionability）：可见性、稳定性、启用状态等全部通过才会真正派发（CONCEPTS.md）——这就是"操作可安全重试"的来源。

一键安装步骤：3 种方式 30 秒上手

方式一：npm 全局安装（推荐，自动下载预编译二进制）

npm install -g agent-desktop

方式二：免安装直接体验

npx agent-desktop snapshot --app Finder -i

方式三：源码编译（需 Rust 1.89+、macOS 13.0+）

git clone https://gitcode.com/gh_mirrors/ag/agent-desktop cd agent-desktop && cargo build --release

macOS 还需要在系统设置 → 隐私与安全性中授予终端辅助功能权限；截图需要屏幕录制权限。用下面命令可一键检测并申请缺失权限（不会静默弹窗）：

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 cmd+s # 4. 再观察，验证 UI 变化 agent-desktop snapshot -i

常用命令速查表（完整 58 个命令见 README.md）：

默认是headless（无头）模式：只走辅助功能语义 API，不移动光标、不抢焦点、不动剪贴板；需要真实物理输入时加--headed即可。

省 Token 大招：渐进式骨架遍历让 AI Agent 少读 98%

密集应用的完整快照动辄几万 token。agent-desktop 提供「骨架概览 + 按需下钻」策略：先用 3 层浅快照拿到 UI 地图，再只展开目标区域。

以 Slack 为例（3 次采集中位值）：

• 完整快照：约30,743 tokens
• 骨架概览：仅383 tokens（节省 98.8%）
• 再下钻到输入框区域：约1,440 tokens

benchmarks/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 一节：

1. 严格 ref 解析：每次行动前用保存的身份证据（窗口、路径、角色、bounds）重新确认元素，缺失/变化返回STALE_REF，多候选返回AMBIGUOUS_TARGET，从不瞎猜；
2. 可行动性预检：派发前检查可见、稳定、启用等状态，不满足直接结构化报错；
3. 送达语义（Delivery Semantics）：失败时明确告诉你输入"是否已送达"——未送达可放心重试，可能送达则提示先验证，避免重复提交（CONCEPTS.md）；
4. 交互租约：全机器同一时刻只有一个进程派发输入，多 Agent 并发不会互相穿插。

标准恢复循环：

snapshot → act → 遇到 STALE_REF？ → 重新 snapshot → 用新 ref 重试

想回放整个会话的每一步？会话自带 trace 时间线：

agent-desktop trace show --limit 500 # 有界的 JSON 时间线 agent-desktop trace export --out run.html # 单文件 HTML 回放（内嵌截图）

项目结构导读

其他延伸阅读：

• 概念词汇表：CONCEPTS.md——Snapshot、Ref、Session、Actionability 的精确定义
• JSON 输出契约：docs/json-output.md
• 常见问题：docs/faq.md
• FFI 语言绑定指南：skills/agent-desktop-ffi/SKILL.md

常见问题（FAQ）

Q：agent-desktop 本身是 AI 吗？不是。它只是 Agent 调用的工具：输入命令，输出结构化 JSON。观察-决策循环在你自己的 Agent 里。

Q：和 Playwright / Puppeteer 是什么关系？互补。Chromium 应用可以用launch --cdp开启已验证的 CDP 端口交给 Playwright 等框架操作网页内容；而原生菜单、对话框、窗口管理仍走辅助功能路径。

Q：操作失败会重复执行吗？不会盲目重试。每个错误都带error_code和恢复提示，并标注输入是否已送达，由 Agent 据此决定安全策略。

Q：Linux / Windows 能用吗？核心逻辑平台无关，macOS 适配器目前功能最全，Windows / Linux 正在按同一核心契约适配中（README.md）。

总结：可靠桌面操作靠这三件套

agent-desktop 用三样东西换来了桌面自动化的"可靠"二字：

1. 辅助功能树代替像素猜测——看到的是结构化 UI，不是截图；
2. 快照 + refs的稳定标识体系——ref 过期就重新快照，永远不瞎点；
3. 可行动性预检 + 送达语义——失败也能判断能否安全重试。

如果你正在构建桌面 Agent、自动化测试或 RPA 流程，一条npm install -g agent-desktop就能开始体验"观察 → 决策 → 行动 → 验证"的完整循环。

• GUI 自动化
• AI 应用
• 桌面应用
• AI 技能