GitHub 今日推荐｜agent-desktop：通过无障碍树让 AI 代理直接操作桌面应用

一句话看懂

Agent Desktop 让 AI 代理通过操作系统的无障碍树读取并操作桌面应用，生成 JSON 快照并分配引用标识符，代理执行操作后再次快照验证结果。Rust 编写，Apache-2.0 许可，当前版本 1.0.2。仓库创建于 2026 年 2 月 19 日，已获 9497 星，当日新增 2902 星。

它解决什么问题

传统桌面自动化依赖像素匹配或硬编码坐标，屏幕分辨率变化或 UI 更新会导致失败。Agent Desktop 从操作系统层面读取应用 UI 结构，获取每个元素的角色、名称、位置、可操作性，生成结构化快照。代理使用引用标识符操作元素，系统检查元素可见性、稳定性、启用状态后执行操作。

官方 Homebrew 和 Scoop 包正在提交，当前可通过 npm 全局安装。快照、剪贴板、截图可能包含私密内容，需避免公开日志或上传。

核心概念速览

ref（引用标识符）

快照中每个可操作元素的唯一标识，格式为 @snapshotID:elementID。代理执行点击或输入时必须携带快照 ID，否则请求被拒绝。ref 与快照生命周期绑定，快照过期后 ref 失效，系统返回 STALE_REF 或 AMBIGUOUS_TARGET 错误。

accessibility tree（无障碍树）

操作系统提供的应用 UI 结构树，macOS 使用 Accessibility API，Windows 使用 UIA，Linux 使用 AT-SPI2。树节点包含元素角色、名称、边界、子元素列表。Agent Desktop 遍历这棵树生成快照，过滤不可操作节点。

actionability（可操作性检查）

元素是否可被操作的判断机制。系统检查元素可见性、稳定性、启用状态、编辑能力、策略、hit-test 结果。稠密应用中，一个元素可能被其他元素遮挡，hit-test 验证点击坐标是否命中目标元素。

headless（无头模式）

默认操作模式，不移动指针或获取焦点，通过无障碍 API 直接操作元素。禁止前台激活与合成输入，即使在无头模式下这些限制仍然生效。使用 --headed 标志允许物理输入，但会移动鼠标指针。

架构拆解

Agent Desktop 分为五个核心模块：

agent-desktop-core

核心逻辑模块，位于 crates/core。包含快照生成、ref 解析、actionability 检查、命令执行框架。定义 PlatformAdapter trait，抽象平台差异。命令通过 execute 函数调用核心逻辑，返回 JSON 信封。

platform adapters

平台适配器，分别位于 crates/macos、crates/windows、crates/linux。实现 PlatformAdapter trait，封装各平台无障碍 API、输入事件、系统调用。macOS 维护私有命令宿主保持无障碍对象生命周期，防止行号重用导致错误。

agent-desktop CLI

命令行入口，位于 src。使用 clap 解析参数，支持 60 个命令，包括 snapshot、click、type、clipboard、screenshot 等。调用 core 与平台适配器执行操作，输出 JSON 结果。

agent-desktop-ffi

C 库导出层，位于 crates/ffi。提供 ad_init、ad_adapter_create 等 C ABI 入口，供 Python、Node.js、Go 等语言调用。调用方需匹配 AD_ABI_VERSION_MAJOR，遵循 ownership-and-threading 规则。

docs site

文档站点，位于 apps/docs，使用 Next.js 构建。生成在线文档托管在 agent-browser.dev/desktop。

数据流向：CLI 解析命令，调用 core 的 execute 函数，core 通过 PlatformAdapter trait 调用平台操作，平台适配器读取无障碍树或执行输入，返回 JSON 信封。快照命令调用 actionability 评估生成 ref，操作命令执行前验证元素可操作性。

关键实现走读

可操作性检查逻辑

rust 复制代码

pub(super) fn check_with_stability(
    stability: StabilityExpectation,
    evidence: &ActionabilityEvidence,
    request: &ActionRequest,
    hit_test: Option<(&NativeHandle, &dyn PlatformAdapter)>,
    deadline: crate::Deadline,
) -> Result<ActionabilityReport, AdapterError> {
    let report = build_report(stability, evidence, request, hit_test, deadline)?;
    finish(evidence, request, report)
}

接收稳定性期望、元素证据、操作请求、可选的 hit-test 参数和截止时间，构建可操作性报告。build_report 检查可见性、稳定性、启用状态、策略、hit-test 结果，finish 根据报告决定操作是否可执行。将稳定性检查与 hit-test 分离，允许调用方根据场景选择是否验证点击坐标。稠密应用需要 hit-test 避免点击被遮挡的元素，简单应用可跳过 hit-test 提高性能。

操作步骤结构

rust 复制代码

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ActionStep {
    label: String,
    pub outcome: ActionStepOutcome,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub mechanism: Option<StepMechanism>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub verified: Option<bool>,
}

impl ActionStep {
    pub fn attempted(label: &'static str) -> Self {
        Self {
            label: label.to_string(),
            outcome: ActionStepOutcome::Attempted,
            mechanism: None,
            verified: None,
        }
    }

定义操作步骤的数据结构，包含标签、结果、机制、验证状态。可序列化为 JSON 输出给代理。attempted 方法创建尝试状态的步骤，后续更新结果和验证状态。将操作分解为多个步骤，每个步骤记录执行细节和验证结果。代理解析步骤列表了解操作是否成功，哪个环节失败。skip_serializing_if 避免输出空字段，减少 JSON 体积。

动手上手

安装

bash 复制代码

npm install -g agent-desktop
agent-desktop version

第一条命令全局安装 npm 包，也可使用 yarn、pnpm、bun。第二条命令输出版本号和 Rust 版本要求，验证安装成功。

macOS 授权

macOS 需授予 Accessibility 权限。系统设置，隐私与安全性，辅助功能，添加终端或 IDE 到允许列表。Windows 无需额外授权，Linux 需安装 at-spi2-core。

生成快照

bash 复制代码

agent-desktop snapshot --app Finder -i

--app Finder 指定目标应用，-i 表示交互式快照，实时更新。输出 JSON 包含 snapshot_id、ref_count、tree 字段。树节点包含 role、name、ref_id、available_actions 字段。例如：

json 复制代码

{
  "version": "2.6",
  "ok": true,
  "command": "snapshot",
  "data": {
    "app": "Finder",
    "window": {"id": "w-204749", "title": "Downloads"},
    "snapshot_id": "s8f3k2p9",
    "ref_count": 59,
    "complete": true,
    "tree": {
      "role": "window",
      "name": "Downloads",
      "children": [
        {
          "role": "treeitem",
          "name": "Documents",
          "ref_id": "@s8f3k2p9:e8",
          "available_actions": ["Click"]
        }
      ]
    }
  }
}

ref_id 用于后续操作。

执行点击

bash 复制代码

agent-desktop click @s8f3k2p9:e8

点击 ref 对应的元素。系统检查 ref 有效性和元素可操作性，执行点击后返回 JSON。输出包含 steps 字段，记录每个操作步骤的结果和验证状态。

再次快照验证

bash 复制代码

agent-desktop snapshot --app Finder -i

代理执行操作后再次快照，对比窗口标题、元素位置变化，验证操作是否生效。

应用场景

AI 代理自动化桌面任务

代理读取快照 JSON，解析树结构选择目标元素，使用 ref 执行 click 或 type 命令，再次快照验证结果。ref 过期时返回 STALE_REF 或 AMBIGUOUS_TARGET 错误，代理重新生成快照。适合文件管理、文本编辑、浏览器操作等任务。

稠密应用逐层钻取

复杂应用包含数百个元素，完整快照体积过大。先用 --skeleton --compact 获取骨架结构，找到目标区域后用 --root @ref 钻入该区域生成详细快照。官方文档建议稠密应用先用骨架模式映射。

多语言集成

通过 libagent_desktop_ffi 的 ad_adapter_create 进程内调用，避免每次启动 CLI 进程的开销。Python、Node.js、Go 等语言加载 C 库，调用 ad_init 初始化，创建 adapter 执行快照和操作。需匹配 AD_ABI_VERSION_MAJOR，遵循 ownership-and-threading 规则。

独立分析

比像素匹配更可靠

无障碍树提供结构化元素信息，屏幕分辨率或主题变化不影响 ref 有效性。但这依赖应用正确实现无障碍 API，未适配无障碍的应用无法生成快照。像素匹配在某些场景下仍是备选方案。

Rust 性能与安全优势

主语言 Rust，release profile 开启 lto=true、strip=true、opt-level=z。link-time optimization 减少二进制体积，strip 移除调试符号，opt-level z 优化体积而非速度。适合作为 CLI 工具分发，但体积优化可能牺牲运行时性能。实际场景中快照和操作的瓶颈在平台 API 调用，Rust 编译优化的影响有限。

与像素匹配自动化对比

Agent Desktop 通过无障碍树获取结构化元素，像素匹配依赖图像识别。无障碍树不受分辨率、缩放、主题影响，但需应用支持。像素匹配通用性强，但对 UI 变化敏感。两者适用场景不同，Agent Desktop 适合现代应用和跨平台自动化，像素匹配适合遗留应用或游戏自动化。

与传统 UI 自动化框架对比

每次 CLI 调用运行在独立进程，无状态守护进程。传统框架通常启动长驻进程维护会话。Agent Desktop 避免状态泄漏，代理每次操作隔离，但启动进程有性能开销。FFI 接口提供进程内调用，平衡隔离与性能。

与浏览器自动化工具对比

Agent Desktop 覆盖所有桌面应用，topics 包含 computer-use-agent。浏览器自动化工具仅操作浏览器。Agent Desktop 适合需要跨应用交互的场景，例如从浏览器复制数据到文本编辑器。浏览器自动化工具提供更丰富的浏览器特定功能，例如网络拦截、Cookie 管理。

局限与风险

Homebrew 和 Scoop 包正在提交，当前尚未在默认目录可用。用户需通过 npm 或手动编译安装。

headless 模式仍禁止前台激活与合成输入。某些应用要求前台焦点才能响应操作，headless 模式下这些应用无法自动化。使用 --headed 标志允许物理输入，但会移动鼠标指针，干扰用户操作。

快照、剪贴板、截图可能包含私密内容。代理将快照发送给 LLM 推理时，需手动过滤敏感信息或使用本地模型。官方建议避免公开日志或上传。

多窗口应用需手动传 --window-id，否则返回 AMBIGUOUS_TARGET 错误。代理需先查询窗口列表，选择目标窗口。增加代理实现复杂度。

ref 生命周期与快照绑定，快照过期后 ref 失效。代理需在每次操作前验证 ref 有效性，失败时重新生成快照。频繁快照增加延迟。

结论卡片

适合： AI 研究者、自动化测试工程师、需跨平台桌面自动化的开发者。适合构建 AI 代理的桌面操作循环，需注意 ref 生命周期与权限配置。

不适合： 仅需浏览器自动化、需实时守护进程、需像素级视觉识别的场景。

关注要点： macOS 需授予 Accessibility 权限，快照可能含私密内容，ref 过期需重新快照，稠密应用使用骨架模式，FFI 调用需匹配 ABI 版本。

项目地址：github.com/vercel-labs...

原文地址：tools.wflynn.cn/aitools/git...

关注公众号「YourTools」，每天推送 GitHub 趋势与开源工具速报：