一句話結論
大多數「computer use」是讓模型看截圖、猜座標；agent-desktop 走另一條路：直接讀作業系統的無障礙樹（accessibility tree），把畫面上每個可操作元素變成一張有身分證的 ref，然後叫 agent 點那個 ref。
它由 Vercel Labs 開源（★18,588、Apache-2.0、Rust 撰寫），同時提供 CLI、C library，還能把所有命令掛成 MCP server。npm 上線不到一年、近 30 天下載 53,251 次，最新版 1.2.0（2026-11-05）。
最重要的一句話寫在 README 裡：「The loop lives in your agent; agent-desktop has no model inside.」——它自己不帶模型，只負責「看見」與「操作」。
一表看懂
| 項目 | 內容 |
|---|---|
| GitHub | vercel-labs/agent-desktop |
| 星數／分支 | ★18,588／1,350 forks（2026-11-07 查詢） |
| 授權／語言 | Apache-2.0／Rust |
| 版本 | npm 1.2.0（2026-11-05 發布，13 個 release 資產） |
| 規模 | 3,746 個檔案，含 43 KB 的 CONCEPTS.md 與 22 KB 的 AGENTS.md |
| 安裝 | npm install -g agent-desktop（也有 Homebrew；Bun／pnpm／Yarn 皆可） |
| 平台 | macOS 13+／Windows 10 1809+／Ubuntu 24.04+ |
截圖派 vs 無障礙樹派
| 面向 | 截圖＋視覺定位 | agent-desktop（無障礙樹） |
|---|---|---|
| 判斷依據 | 像素、模型看圖猜位置 | OS 提供的語意樹（角色、名稱、可用動作） |
| 解析度敏感度 | 高（DPI、縮放、主題都會影響） | 無關（不碰畫素） |
| 定位精度 | 座標，可能點偏 | ref id，指到具體元素 |
| 驗證方式 | 再截一張圖比對（還是靠眼睛） | 再 snapshot 一次，比對結構 |
| 遮擋／離屏 | 可能誤判 | 有 visible、occlusion 等原生證據 |
| 成本 | 每步都要送圖給模型 | 一步送一次 JSON |
代價是：沒有無障礙實作的程式（例如全自繪的遊戲、部分 Electron／Flutter 應用）就看不見。這是路線取捨，不是 bug。
核心機制：ref 是快照的產物
操作循環只有三步，官方 quick start 直接示範：
agent-desktop snapshot --app Finder -i # 取快照，每個元素帶 ref
agent-desktop click @s8f3k2p9:e8 # 對 ref 動作
agent-desktop snapshot --app Finder -i # 再觀察，驗證結果
snapshot 回傳的是一個 JSON envelope（version、ok、command、data），data 裡有 snapshot_id、ref_count、complete 與整棵 tree。每個節點長這樣：
{ "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"] }
三條規則是硬性的：
- ref 屬於它的快照。 只寫
@e8會被拒（INVALID_ARGS）；UI 變了再動作，會回STALE_REF或AMBIGUOUS_TARGET，正確做法是重取快照。 - 多視窗會回
AMBIGUOUS_TARGET，錯誤細節會列出候選 window id，要用--window-id指定。 - 密集的程式先看骨架：
snapshot --skeleton抓大結構，再--root @ref鑽進某一區，避免一次吐幾千個節點。
五個值得抄的工程細節
這份 repo 的價值不只在功能，而在它把「讓 agent 安全操作 GUI」拆得非常細。官方 CONCEPTS.md 裡有五個設計可以直接借：
| 設計 | 做法 | 為什麼重要 |
|---|---|---|
| 視窗身分 | 不是只看 window handle，而是 handle＋process-generation token（由行程建立時間推導） | 作業系統會回收 handle 給別的視窗；只認 handle 就會操作到錯的視窗。世代不合時 fail closed，寧可失敗也不誤點 |
| Auto-wait | 預設等 5000 ms（type 每字元再加 30 ms），--timeout-ms 0 回到「立刻動手」 | 把「按鈕還沒出現」從競態變成可預期的等待；terminal 檢查（支援動作、政策、可否編輯）不等，直接失敗 |
| Actionability battery | 派送前逐項檢查：可見、穩定、啟用、支援該動作、政策允許、可編輯 | 讓「點不到」變成明確錯誤碼，而不是靜默失敗 |
| Headless 預設 | ref 動作走無障礙 API，不移動游標、不搶焦點；--headed 才做實體輸入 | 使用者可以繼續用電腦，agent 在背景操作 |
| 可重試語意 | 錯誤帶 error.disposition.retry，只有 safe 才重試 | 避免 agent 對「已經點成功但回應逾時」的動作重複點擊 |
60 個命令，分成 9 組
官方說法：60 個命令名、56 個可操作——另外四個（key-down、key-up、mouse-down、mouse-up）在守護行程能釋放按鍵前會拒絕執行，避免把鍵盤或滑鼠卡在按下的狀態。
| 群組 | 命令 |
|---|---|
| 觀察 | snapshot、find、get、is、screenshot、list-surfaces |
| 對 ref 動作 | click、double-click、triple-click、right-click、type、set-value、clear、focus、select、toggle、check、uncheck、expand、collapse、scroll、scroll-to |
| 鍵鼠 | press、hover、drag、mouse-move、mouse-click、mouse-wheel、key-down、key-up、mouse-down、mouse-up |
| 程式與視窗 | launch、close-app、list-apps、list-windows、list-displays、focus-window、resize-window、move-window、minimize、maximize、restore、open-system-surface |
| 通知 | list-notifications、dismiss-notification、dismiss-all-notifications、notification-action |
| 剪貼簿 | clipboard-get、clipboard-set、clipboard-clear |
| 等待 | wait |
| 工作階段 | session、trace、cursor-overlay |
| 系統 | status、permissions、version、batch、skills |
安裝與第一次執行
npm install -g agent-desktop
agent-desktop status # 平台、權限、可用介面
agent-desktop permissions --guide # macOS：帶你完成「輔助使用」授權
macOS 與 Linux 也能 brew install agent-desktop。想直接用原生執行檔（不經 JS 啟動器），可從 GitHub Releases 下載對應平台的 archive，並把 helper 放在執行檔旁邊。
三種接法：CLI、MCP、C library
① CLI：每次呼叫回一個 JSON envelope，適合 shell 腳本與 subagent 直接跑。
② MCP：agent-desktop mcp 會把所有命令掛成 stdio 的 MCP 工具，命名是 desktop_snapshot、desktop_click、desktop_session_start 這種格式：
{ "mcpServers": { "agent-desktop": { "command": "agent-desktop", "args": ["mcp"] } } }
③ C library：每個 release 都附 libagent_desktop_ffi，讓程式在同一個行程內呼叫，不必開子行程。這也是它用 Rust 寫的原因之一——同一份 core，三種出口。
④ 給 agent 的說明書：執行檔內建與版本相符的指南，agent-desktop skills get desktop 給操作循環與重試規則，skills get platform 給平台差異。也能裝進 agent harness：
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
平台支援與門檻
| 平台 | 最低版本 | 使用的 API |
|---|---|---|
| macOS | 13 以上（Intel／Apple Silicon） | AX API |
| Windows | 10 1809 以上（x64／ARM64） | UI Automation |
| Linux | Ubuntu 24.04 以上（x86_64／aarch64、X11 或 Wayland） | AT-SPI |
每個平台頁面另外寫清楚「哪些功能在 headless 下可用、哪些一定要 --headed、哪些直接拒絕」。這一點比多數同類工具誠實。
安全與隱私：官方自己劃的紅線
README 開頭沒在講功能，先講風險：
「Snapshots, clipboard reads, screenshots, command output, and debug artifacts can contain private desktop content. Keep them out of public logs and uploads.」
實務上要照做的三件事：
- 快照、剪貼簿、截圖、除錯產物都可能夾帶私人內容——不要直接丟進公開 log 或上傳。
- 敏感字串用
--stdin管線餵進去（type、set-value、clipboard-set都支援），避免密碼出現在 process arguments；批次 JSON 的文字仍會留在參數裡。 - PowerShell 要把 ref 加引號（
'@s8f3k2p9:e8'），因為裸的@token是 splatting 運算子。
該保留懷疑的地方
| 疑點 | 說明 |
|---|---|
| 無障礙樹不是萬用 | 自繪 UI、遊戲、部分跨平台框架沒有完整無障礙實作，這時它「看不見」；必要時得退回 screenshot 路線 |
| 仍是 Labs 產品 | 2026-02 建庫、Vercel Labs 出品，定位是實驗性專案；187 個 open issue 說明還在快速變動 |
| Linux 門檻偏高 | 要求 Ubuntu 24.04 以上與 AT-SPI，舊發行版直接出局 |
| 不自帶模型 | 判斷與重試策略要自己寫在 agent 裡；它只給「看見＋操作」的原語 |
| 本文未實測 | 這台機器沒有可互動的桌面環境（只有無顯示的 Xvfb），因此本文沒有任何自己跑出來的數字，所有規格與行為描述皆取自 repo 與官方文件（2026-11-07） |
誰適合、誰先別碰
適合
- 想讓 agent 操作桌面應用（Finder、Slack、Excel、內部 ERP）而不是網頁的人
- 需要不搶使用者焦點的背景下操作：headless 預設正是為此設計
- 想要結構化、可驗證的 computer use：snapshot 是 JSON，驗證就再 snapshot 一次，不必看圖
- 已在用 MCP 生態的人：
agent-desktop mcp幾乎零成本接入
先別碰
- 目標是網頁自動化：那是同家族的 Agent Browser 在處理的事，不用繞道桌面 API
- 主要操作對象是自繪 UI 或遊戲：無障礙樹看不到
- 需要長期穩定 API 的生產系統：Labs 專案、一個月多版，先當實驗品
站內延伸閱讀
- Agent Browser：Vercel 為 AI 代理打造的開源瀏覽器自動化工具 — 同一家族的網頁版，先搞懂瀏覽器那條線再看桌面這條會更清楚
- MCP 完整教學 2026 — 想把
agent-desktop mcp接進自家 agent，先看這篇的協定與工具註冊 - DeepSeek 開源 dsh-superagent：會自己開 PR 的代理 — 另一種「給 agent 動手能力」的思路：不是操作 GUI，而是治理與授權
本文為獨立整理，不含聯盟連結、未受 Vercel 或任何廠商贊助。規格、命令與行為描述取自 repo 內
README.md、CONCEPTS.md與官方文件（2026-11-07 查證），下載量取自 npm 公開統計。本文未實際執行 agent-desktop，故不提供任何效能或成功率數字。