# AI 操作電腦還在截圖猜座標？agent-desktop 改讀按鈕清單，實測 60 個動作 0 失敗

- 網址：https://blog.valenvan.uk/posts/vercel-labs-agent-desktop.html
- 發布日期：2026-11-04
- 測試設備：Mac mini M4 Pro（12 核、64GB）
- 專案：vercel-labs/agent-desktop（https://github.com/vercel-labs/agent-desktop），Apache-2.0 授權
- 測試版本：agent-desktop 1.1.0
- 實測影片：https://www.youtube.com/shorts/nMyCicLD780

## 重點摘要

- agent-desktop 1.1.0 讀 Mousepad 的無障礙資訊，列出 271 個能操作的元件，讀一次清單 56–84 毫秒。
- 用腳本模擬 AI 在 Mousepad 打三行字並另存新檔，打開存好的檔案核對，三行一字不差。
- 兩個分身同時在兩個視窗各加 15 筆待辦，60 個動作 4.31 秒、0 失敗，兩邊記到的滑鼠座標都停在螢幕正中央。
- README 寫的 agent-desktop mcp（掛進 AI 助手）在 1.1.0 發布版回 unrecognized subcommand。
- **結論：** 想讓 AI 穩定操作桌面程式又不搶滑鼠的人值得先試；要直接掛進 AI 助手（MCP）的等下一版。
- **適合：** 想讓 AI 自動操作桌面程式、會寫一點腳本把它接進自己 AI 流程的人。
- **不適合：** 想在 AI 助手裡一鍵掛上（MCP）的人，或完全不碰命令列的人。

| 實測項目 | 結果 |
|---|---|
| Mousepad 完整清單 | 271 個元件，約 46KB |
| 精簡清單（--skeleton） | 79 個元件，約 14.6KB |
| 讀一次清單 | 56–84 毫秒 |
| 單一動作（打字、點擊、填檔名） | 0.11–0.43 秒 |
| 打三行字＋另存新檔 | 三行一字不差 |
| 兩個分身各加 15 筆待辦 | 60 個動作 4.31 秒，0 失敗 |
| 選單沒打開就按裡面的項目 | ACTION_FAILED（項目不在畫面上） |
| 只寫 @e8 不帶快照代號 | INVALID_ARGS，標示 retry safe |
| agent-desktop mcp | 1.1.0 叫不出來 |

你請 AI 幫忙在記事本打幾行字、另存新檔。常見的做法是 AI 先截一張螢幕圖，看圖猜「存檔」在哪個位置，再移動滑鼠過去點。視窗一挪、按鈕換位置就容易點歪；而且這段時間滑鼠被它佔著，你自己不能用電腦。

[agent-desktop](https://github.com/vercel-labs/agent-desktop) 是 Vercel Labs 用 Rust 寫的命令列工具，換了一條路：讀作業系統給螢幕閱讀器（視障輔助）用的無障礙資訊，把視窗裡每個按鈕、輸入框列成清單、各給一個編號，AI 只要說「按第幾號」，不用看圖。它本身不含 AI 模型，是給 AI 呼叫的「手」。

## 測試方式與設備

測試設備：Mac mini M4 Pro（12 核、64GB）。受測版本：agent-desktop 1.1.0（2026-11-03 發布）。

官方支援 macOS、Windows、Linux，這次**只測了 Linux**（arm64、Debian 12）：開一個虛擬螢幕（Xvfb）加 openbox 視窗管理員，操作的程式是文字編輯器 Mousepad，和我自己寫的兩個小待辦視窗（Alpha、Beta）。

我沒有接真實的 AI，而是用 Python 腳本**模擬兩個 AI** 下指令。所以下面測的是「工具能不能把動作做準、做快」，不是「AI 會不會用它」。

## 安裝

Linux 需要圖形畫面、無障礙匯流排（AT-SPI）和視窗管理員。我用官方發布的執行檔，下載後先核對雜湊值：

```bash
sudo apt-get install -y xvfb openbox at-spi2-core dbus dbus-x11 mousepad

V=v1.1.0; A=$(uname -m); F=agent-desktop-$V-$A-unknown-linux-gnu.tar.gz
curl -fsSLO https://github.com/vercel-labs/agent-desktop/releases/download/$V/$F
curl -fsSLO https://github.com/vercel-labs/agent-desktop/releases/download/$V/checksums.txt
grep " $F" checksums.txt | sha256sum -c -    # 確認下載的檔案沒被動過
tar xzf $F
```

Linux arm64 版壓縮檔約 3.3MB。官方也提供 `npm install -g agent-desktop`，這次沒用。我的環境只有虛擬螢幕、沒有完整桌面，所以先手動把無障礙匯流排開起來：

```bash
/usr/libexec/at-spi-bus-launcher --launch-immediately &
```

## 怎麼用：先讀清單，再按編號

```bash
agent-desktop snapshot --app mousepad -i         # 列出 Mousepad 能操作的元件（JSON）
agent-desktop type  @s8f3k2p9:e5 "懶出來的發明"    # 往某個輸入框打字
agent-desktop click @s8f3k2p9:e2                  # 按某個按鈕
agent-desktop list-windows                        # 列出所有視窗
agent-desktop snapshot --window-id <id> -i --session agent-a   # 指定視窗、指定分身
```

編號長這樣：`@快照代號:e號碼`。每讀一次清單會產生新的快照代號，AI 按的時候要帶上它。成功的回覆會寫出它是怎麼做到的，例如打字是 `EditableText.InsertText`、點擊是 `Action.DoAction`，都標 `semantic_api`，走的是無障礙介面，不是移動滑鼠。

## 實測結果

| 項目 | 結果 |
|---|---|
| Mousepad 完整清單 | 271 個元件，JSON 約 46KB |
| 精簡清單（`--skeleton`） | 79 個元件，約 14.6KB |
| 另存新檔對話框 | 246 個元件 |
| 讀一次清單 | 56–84 毫秒 |
| 單一動作（打字、點擊、填檔名） | 0.11–0.43 秒，最慢是按 Save As |
| 打三行字＋另存新檔 | 打開存好的檔案核對，三行一字不差 |
| 兩個分身各加 15 筆待辦 | 60 個動作 4.31 秒，0 失敗，順序正確 |
| 滑鼠座標 | 兩個視窗記到的都是螢幕正中央（虛擬螢幕的起始位置） |

![存好的檔案在 Mousepad 打開，三行一字不差](https://blog.valenvan.uk/img/vercel-labs-agent-desktop-article_1.png)

兩個分身是這樣跑的：Alpha 用 `--session agent-a`、Beta 用 `--session agent-b`，各自讀自己視窗的清單，同時開跑，每輪「打字＋按新增」，中間不加等待。待辦視窗每按一次新增，就把當下的滑鼠座標寫進紀錄檔；兩邊最後記到的都是螢幕正中央。兩個視窗位置不同，如果真的是移動滑鼠去點，座標不可能都停在同一點。

![Alpha、Beta 兩個視窗各自排好 15 筆待辦](https://blog.valenvan.uk/img/vercel-labs-agent-desktop-article_2.png)

## 踩到的兩個地方

**選單沒打開，裡面的項目按不到。** 我一開始直接按清單裡的「Save As...」，回 `ACTION_FAILED`：「Target is not actionable: visible (live offscreen state is true)」，意思是那個項目現在不在畫面上。解法是先按 File 把選單打開，再用 `snapshot --surface menu -i` 讀一次選單（16 個元件），從新清單裡按。

**編號要帶快照代號。** 只寫 `@e8` 會回 `INVALID_ARGS`，訊息直接告訴你格式要 `@<snapshot_id>:e<N>`。我覺得最實用的是錯誤裡附的處置說明：`"delivery":"not_delivered","retry":"safe"`，表示動作沒送出、可以放心重試；用過期的編號會回 `STALE_REF`，同樣標可重試。成功的動作反而標 `retry: unsafe`，提醒別重複按。AI 不用猜「剛剛那下到底按了沒」。

## 說明有寫、這版還叫不出來：MCP

README 寫可以用 `agent-desktop mcp` 直接掛進支援 MCP 的 AI 助手。1.1.0 發布版執行結果是 `error: unrecognized subcommand 'mcp'`。想直接接到 AI 助手的，現在要自己寫一層包裝，或等下一版。

## 沒測到的

macOS（要開「輔助使用」權限）、Windows、Wayland 桌面都沒測；也沒接真實的 AI，沒測瀏覽器、Office 這類大型程式的清單有多大。官方 Linux 建議 Ubuntu 24.04 以上，並註明 Ubuntu 22.04 的 at-spi2-core 會出問題，這點我沒驗證。官方也提醒：清單、截圖會含畫面上的文字，可能有私人內容，不要貼到公開的地方。

## 我的看法

以下是看法，不是實測：讀清單比看截圖穩，按鈕換了位置照樣找得到，每個動作都回報成功沒、能不能重試，這對讓 AI 自己跑長流程很重要；又不搶滑鼠，人可以同時用電腦。缺點是它只是手，按哪一個還是要 AI 判斷；清單也不小（光 Mousepad 就 46KB），整份丟給 AI 會吃字數，我會先用 `--skeleton` 或只讀需要的那個視窗。

## 適合誰

- 適合：想讓 AI 自動操作桌面程式（填表、存檔、跑固定流程），又不想讓它佔用滑鼠的人；會寫一點腳本，把它接進自己 AI 流程的人。
- 不適合：想在 AI 助手裡一鍵掛上（MCP）的人，等下一版；完全不碰命令列的人。

專案：https://github.com/vercel-labs/agent-desktop ｜授權：Apache-2.0