AI

agent-desktop：Vercel Labs 開源的 Computer Use CLI，不靠截圖、改讀無障礙樹來操作桌面 App

Monday

本內容僅供參考，詳細使用規則與工具安全性與否，建議要進行相關安全性測試與評估

讓 AI Agent 操作桌面應用程式，主流做法是「截圖 → 讓模型看圖 → 計算座標 → 點下去」。這個流程慢、貴，而且脆弱——視窗位置一變、解析度一改、深色模式一開，座標就可能全錯。agent-desktop（vercel-labs/agent-desktop）換了一條路：不看截圖，直接讀作業系統的無障礙樹（accessibility tree），把每個按鈕、輸入框、選單都變成一個有編號的元素，讓 Agent 用「點 @e8」這樣的方式精準操作。根據 11 月 3 日的 AI 開源趨勢報告，它單日新增約 2,275 顆星，是當天成長最快的 Agent 工具，目前約 12.9k stars。

1. 專案背景與定位

agent-desktop 由 Vercel Labs 開源，Apache-2.0 授權，以 Rust 撰寫，官方描述是「給 AI Agent 的 Computer Use CLI」。它和 Vercel 的另一個專案 agent-browser 是同一系列（文件放在 agent-browser.dev/desktop）。

它的定位非常清楚：只負責「看」與「做」，不負責「想」。README 明確表示 agent-desktop 裡面沒有任何模型——推理完全交給你的 Agent 迴圈，它只提供可靠的觀察與操作介面。可以作為 CLI 使用，也提供 C 函式庫（libagent_desktop_ffi）讓其他程式整合。

2. 技術架構與核心設計

  • 無障礙樹而非像素：讀取應用程式的無障礙樹並以 JSON 回傳，每個可操作的元素都有一個 ref（參照編號）。
  • 各平台原生 API：
    • macOS：AX API（macOS 13 以上）
    • Windows：UI Automation（Windows 10 1809 以上）
    • Linux：AT-SPI（Ubuntu 24.04 以上，支援 X11 與 Wayland）
  • 平台抽象層：核心 agent-desktop-core 只透過 PlatformAdapter trait 接觸作業系統，編譯時選擇對應的平台實作。
  • 「快照 → 操作 → 再快照」迴圈：例如 snapshot --app Finder -i 取得元素樹，click 某個 ref，再快照確認結果。
  • 防呆設計：ref 會包含快照 ID，單獨寫 @e8 會回傳 INVALID_ARGS；UI 變動後使用舊 ref 會得到 STALE_REF，目標不明確時則是 AMBIGUOUS_TARGET——這些都提醒 Agent 重新快照，而不是盲目操作。
  • 預設無頭（headless）：操作預設不移動滑鼠、不改變視窗焦點；需要實體輸入時才加上 --headed。
  • 豐富的指令集：60 個指令名稱中有 56 個可用，涵蓋觀察（snapshot、find、get、screenshot）、元素操作（click、type、set-value、scroll）、鍵盤滑鼠、應用程式與視窗、通知、剪貼簿、等待、session 與 trace 等。
  • Agent 整合：提供可用 npx skills add 安裝的 Skill，以及 agent-desktop mcp——把每個指令變成 MCP 工具（如 desktop_snapshot、desktop_click）。
  • 安全重試：只有在錯誤回應的 error.disposition.retry 標示為 safe 時才建議重試。

3. 社群熱度與生態採用

約 12.9k stars、886 forks、328 commits，可透過 npm、Bun、Yarn、pnpm 或 Homebrew 安裝，預編譯二進位檔支援 x64 與 ARM64。agent-desktop status 可以檢查平台、權限與支援的介面，permissions --guide 則引導 macOS 使用者開啟輔助使用權限。

4. 局限性與潛在風險

  • 它能操作你電腦上的任何 App：在 macOS 授予輔助使用權限後，Agent 理論上可以讀取並操作你桌面上的所有應用程式——包括 Email、聊天軟體、銀行網站與密碼管理器。這是非常高的權限，應只在需要時授權，並考慮使用專用的使用者帳號或虛擬機。
  • 快照可能包含隱私資訊：README 特別警告，快照、剪貼簿讀取、截圖、指令輸出與除錯紀錄都可能含有桌面上的私人內容，不應出現在公開的 log 或上傳的檔案中。
  • Prompt injection 的新入口：Agent 讀到的無障礙樹包含網頁、Email、文件中的文字，惡意內容可能藉此影響 Agent 的下一步操作；有副作用的動作（送出、刪除、付款）應加上人工確認。
  • 無障礙支援程度因 App 而異：沒有好好實作無障礙 API 的應用程式（某些遊戲、自繪 UI 的 App）可能讀不到元素，仍需要退回截圖方式。
  • 部分指令尚未可用：key-down、key-up、mouse-down、mouse-up 四個指令要等常駐程式能釋放按住的按鍵後才會開放。
  • 平台差異：各平台在無頭模式下能做的事不同，有些操作需要 --headed，有些則會被拒絕。

5. 應用價值與適用場景

最適合需要讓 Agent 操作沒有 API 的桌面軟體的情境：例如自動化舊式的企業內部系統、在多個桌面 App 之間搬運資料、做桌面應用程式的自動化測試，或為行動不便的使用者打造語音操作助理。相較於截圖式的 Computer Use，它更快、更省 token，結果也更穩定可重現。

Monday 的觀點與架構建議

  • agent-desktop 證明了一件事：無障礙 API 是 AI Agent 最好的介面之一。當初為視障使用者設計的螢幕閱讀器介面，如今也成為 Agent 理解 UI 的最佳管道——這也讓「做好無障礙」從道德責任變成了產品競爭力。
  • 「沒有模型、只提供觀察與操作」的分工非常乾淨，搭配 STALE_REF 這類明確的錯誤碼，讓 Agent 迴圈可以可靠地自我修正。
  • 安全建議：在專用帳號或虛擬機中執行、把快照與 trace 視為敏感資料、對有副作用的操作加上確認步驟，並搭配本月介紹的 OpenShell 這類沙盒環境。
  • 回顧本月 Agent 與外部世界互動的方式：Agent-Reach 借用身分讀取網路、CLI-Anything 為軟體生成 CLI、agent-desktop 透過無障礙樹操作 GUI——結構化的介面正在全面取代「看圖點擊」，因為它更可靠，也更容易稽核。

參考來源