---
title: "产品概览"
description: "agent-desktop 让 AI 智能体读取桌面应用的可访问性树、操控其中的元素，并自己核对结果。"
---

> Documentation Index
> Fetch the complete documentation index at: https://agent-desktop.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 产品概览

agent-desktop 是一个面向 macOS、Windows 和 Linux 的 CLI 与 C 库。它读取操作系统提供的可访问性树，把界面里智能体能够操作的每一个元素变成一个带 `ref` 的 JSON 节点。智能体对某个 `ref` 执行一次操作，然后再快照一次来确认结果，全程不做像素匹配，控制循环始终留在你自己的智能体里。

```bash
npm install -g agent-desktop
agent-desktop status          # 平台、权限、支持的界面
agent-desktop skills get desktop   # 智能体应该先读的指南
```

## 它是什么，不是什么

> **一条边界**
>
> agent-desktop 是一件工具，不是一个智能体。它内部没有模型，没有图形界面，也没有交互式提示。

- **智能体调用的工具** — 观察—操作—验证的循环由调用方（你的代码或 LLM 循环）持有。它只负责把界面变成可寻址的数据，再把一次动作落下去。
- **内部没有模型** — 不内嵌 LLM，不联网推理。每条命令打印一个 JSON 信封然后退出，输出完全可预测，也完全可脚本化。
- **只管桌面应用** — 网页自动化请用 [agent-browser](https://github.com/vercel-labs/agent-browser)：它走 Chrome DevTools 协议读网页，agent-desktop 只读操作系统的可访问性树。对于你自己启动的 Chromium 或 Electron 应用里的网页内容，agent-desktop 会开一个 DevTools 端口让 agent-browser 用 `--cdp` 连上去。
- **只看得见应用愿意暴露的** — 它读可访问性树，不做像素匹配，所以一个不发布可访问性树的界面，它同样读不到。

## 四步循环

智能体先把应用摸清，再钻进需要的那块区域，对一个 `ref` 执行动作，最后把结果读一遍。

```bash
agent-desktop snapshot --app gnome-calculator --skeleton -i --compact   # 1. 摸清整体骨架
agent-desktop snapshot --root @s2txcl95uv:e1 -i --compact               # 2. 展开其中一块区域
agent-desktop click @s2txcl95uv:e11                                     # 3. 按下按钮 7
agent-desktop wait --element @s2txcl95uv:e11 --predicate value --value 7 # 4. 核对显示的是 7
```

一次成功的操作并不能证明界面真的变了，所以循环的最后一步永远是一次读取。
`ref` 自带产生它的那次快照的 id，规则见[快照与 ref](/concepts/snapshots-and-refs/)，
前两条命令的解释见[骨架与下钻](/concepts/skeleton-and-drilldown/)。

## 怎么实现的

从调用方到被操作的应用，中间只有这一条链：

1. **调用方** —— 你的代码或 LLM 循环，运行一条命令并读取它打印的 JSON 信封。
2. **agent-desktop CLI**，或者在进程内直接调用时的 **C 库**。
3. **agent-desktop-core** —— 命令、`RefStore` 和快照构建。core 定义了 `PlatformAdapter` trait 和所有共享类型。
4. **`PlatformAdapter`** —— core 触达操作系统的唯一途径。
5. **一个平台 crate** —— `agent-desktop-macos`、`agent-desktop-windows` 或 `agent-desktop-linux`。
6. **操作系统的可访问性 API** —— macOS 的 AX API、Windows 的 UI Automation、Linux 的 AT-SPI。
7. **应用本身**，通过上面那个 API 暴露它的界面。

core 永远不 import 任何平台 crate，平台 crate 之间也互不 import。只有 CLI 和 C 库把一个平台 crate 接到 core 上，并且在编译期就选定，所以一个二进制只能驱动它构建时所属的那个操作系统。

## 平台支持

CLI 在每个平台上都是同一套 60 个命令名。运行在你这个平台上的完整能力表，由
`agent-desktop skills get platform` 直接输出。

## 下一步

- **安装与权限** — 用包管理器安装、校验下载、授予辅助功能权限。
- **快速开始** — 对着一个真实应用跑完一整轮观察—操作—验证。
- **面向 AI 智能体** — 把技能装进智能体运行环境，或者写进 `AGENTS.md`。
- **命令参考** — 全部 60 个命令名，按分组列出。

Source: https://agent-desktop.ndjp.net/start/index.mdx