← 返回部落格
Ai預計閱讀 9 分鐘

agent-desktop 讀的是無障礙樹,不是截圖

發布於 2026年11月14日
agent-desktop 讀的是無障礙樹,不是截圖

每一個靠截圖工作的電腦操作智慧體,都在跑同一套昂貴的迴圈。給螢幕拍張照。讓視覺模型回答按鈕在哪。把答案換算成像素座標。點擊。再拍一張照,看看有沒有發生什麼。

它確實能用,跟 OCR 能用是一個意思:效果驚人,卻從來沒有可靠到可以放著不管。各種失敗方式都指向同一件事,介面的照片是介面的有損表示。

Vercel Labs 推出的 agent-desktop 走的是另一條路,它目前約有 23,300 顆星,過去一週新增約 5,400 顆。它不看螢幕,而是讀取目標應用的無障礙樹並輸出 JSON,為每個可操作元素附一個引用。智慧體對引用執行點擊或輸入,再讀一次介面確認結果,然後重複。

深色機械鍵盤上方懸浮著幾層半透明玻璃矩形,一疊一疊錯開著。

這個迴圈活在你的智慧體裡。二進位檔案裡沒有模型。

安裝與第一次接觸

這個套件走 npm 全域安裝:

npm install -g agent-desktop
agent-desktop status

`status` 會報告平台、權限和可用的介面範圍。把它當第一條指令是合適的,因為電腦操作卡在權限這一步的次數,遠多於卡在邏輯上。在 macOS 上,下一條指令是 `agent-desktop permissions --guide`,它會帶你走完輔助使用授權。macOS 和 Linux 上也可以用 Homebrew。Bun、Yarn 和 pnpm 裝的是同一個套件;內建 x64 與 ARM64 的原生二進位。

三條指令的迴圈長這樣:

agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i

`-i` 參數把快照限制在可互動元素上。點擊用的是某一次特定快照裡的引用。第二次快照不是可有可無的例行公事,你靠它才知道這次點擊是否真的產生了你以為的效果。

幾個關鍵的設計決定

在拿它搭任何東西之前,有四個選擇值得先弄明白。

引用屬於它所在的那次快照。單獨寫一個 `@e8` 會被拒絕,回傳 `INVALID_ARGS`。如果介面在觀察與動作之間發生變化,動作會回傳 `STALE_REF` 或 `AMBIGUOUS_TARGET`,正確的應對是重新取一次快照,用新快照裡的引用。這比多數自動化工具都嚴格,也消掉了一整類無聲的誤點。

元素密集的應用有分兩步的查看路徑。以 Slack 這類應用為例,文件裡的做法是先用 `snapshot --skeleton --app Slack -i --compact` 把整體畫成地圖,再用 `snapshot --root @s8f3k2p9:e3 -i --compact` 鑽進某一塊。沒有這一步,一個複雜應用的完整樹對智慧體來說是太多 JSON。

預設是無頭的。基於引用的動作走無障礙 API,不移動指標,也不搶焦點,所以智慧體幹活時機器仍然可用。全域的 `--headed` 參數會切到實體輸入,應用會偵測真實事件時你需要它,其他情況不需要。

機密可以不進行程參數。`type`、`set-value` 和 `clipboard-set` 支援 `--stdin`,從管線讀文字。命令列參數在行程列表裡是可見的,這決定了一個密碼會不會出現在 `ps` 的輸出裡。README 的建議是把涉及機密的步驟拆成獨立指令,因為批次傳進去的 JSON 文字會再次出現在參數列表裡。

還有一條 PowerShell 註腳,能替某個人省下一小時:每個引用都要加引號,因為單獨的 `@token` 是展開運算子。

平台層到底是什麼

CLI 之下是一個 C 函式庫,兩者之下是同一個核心。每個二進位都為某一個作業系統編譯,與該系統的無障礙 API 對話:macOS 上是 AX API,Windows 上是 UI Automation,Linux 上是 AT-SPI。核心只透過一個 `PlatformAdapter` trait 接觸作業系統,所以同一份程式碼能在三套差異很大的無障礙模型之上給出同一種 JSON 信封。

這個架構也解釋了它的上限。它只能對無障礙樹暴露出來的東西動手。自己把介面畫在畫布上、什麼都不暴露的應用,它會看不見,或者幾乎看不見,適配器寫得再好也一樣。靠截圖的智慧體能處理這些應用,靠引用的不能。這筆交易是用做得好的應用的準確率,換對做得差的應用的覆蓋。

一個具體的對比

設想一個小任務,截圖智慧體處理得很糟:在桌面檔案管理器裡給十二個檔案改名。

截圖智慧體看一眼視窗,認出十二個檔名的位置,產出十二組座標。它點第一個,選取文字,輸入新名字,按 Enter,等列表重新排序。此後每一個座標都過期了,因為列表順序變了。它只能每改一次名就重新觀察一遍,也就是十二次視覺呼叫,十二次點錯列的機會。

基於引用的做法只觀察一次。快照回傳視窗的樹,每一列帶一個引用,另附一個快照 id。每次改名是對某個特定引用的動作,每次動作之後智慧體重讀這棵樹,確認新名字出現了。如果列表重新排序,原快照裡的引用會過期,工具會明確說出來,這正是你想要的行為:一個快速、明白的失敗,而不是對錯誤檔案的一次無聲操作。

可靠性的差別來自結構在哪裡被算出來。前一種情況裡,模型從像素重建一份檔案列表,偶爾會錯。後一種情況裡,作業系統報告它本來就維護著的檔案列表,基本不會錯。

那條安全提醒不是場面話

README 裡有一段警告,值得原樣引用而不是轉述:快照、剪貼簿讀取、截圖、指令輸出和除錯產物都可能包含私人桌面內容,應當避免進入公開日誌和上傳。

這是真實的危險,也是新的危險。靠截圖的智慧體洩漏的是像素。靠樹的智慧體洩漏的是結構化文字,這種文字更容易被索引、被搜尋、被誤提交。如果你為了除錯記錄智慧體的執行軌跡,你記錄的就是當時螢幕上的內容,格式還是 grep 能搜到的那種。

會越來越有用的部分

Vercel Labs 已經交付了兩個這樣的工具:面向網頁的 agent-browser,面向本地應用的 agent-desktop,都用 Rust 寫,都在同一週上了趨勢榜。它們共享的模式是拒絕讓模型去做作業系統已經做過的工作。

這裡真正有用的想法就在這一點上,比任何一條具體指令都重要。視覺模型讀截圖,是在推斷一個無障礙樹裡本來就存在的結構,並為這次推斷付出延遲、token 和錯誤率。讀樹不花什麼錢,回傳的東西智慧體還能驗證。

最終進入生產的智慧體,不會是最會看的那些。會是那些不再需要看的。

相關文章