agent-desktop 是做什麼的？
agent-desktop 是一個 CLI 工具，讓 AI 代理能透過作業系統的輔助功能樹來觀察與操作桌面應用程式。它是一個工具，而非代理。每一條命令都會輸出一個 JSON 信封（ok、data 或 error）。觀察、操作與驗證的循環由您自行掌控。
Shell 語法
範例使用 POSIX shell。在 PowerShell 中，請對每個引用使用引號（'@s8f3k2p9:e1'），因為裸 @token 是展開運算子。使用 $env:NAME = 'value' 取代 export，並使用 | ConvertFrom-Json 取代 $(...) 和 jq。Windows 技能具有 PowerShell 形式。
前置檢查
在任務的第一條命令之前執行此步驟。這是唯一安裝工具的地方。
-
執行
agent-desktop version。若回傳碼為 0 表示 CLI 已存在：跳到步驟 4。 -
若缺失，請使用 npm 安裝。npm 是唯一支援的方式：
npm install -g agent-desktop請勿嘗試 Homebrew、Scoop、下載的壓縮檔或舊版本。此技能是根據 npm 解析的任何版本撰寫的。如果
npm不在 PATH 中，請執行node -v和where npm（Windows）或which npm（macOS、Linux），並回報結果。請勿猜測其他套件管理器。 -
再次執行
agent-desktop version。如果仍然失敗，停止並告知使用者：安裝輸出的最後 20 行、agent-desktop --help是否能執行，以及您所在的作業系統。請勿自行改回使用螢幕截圖或滑鼠自動化。 -
執行
agent-desktop status。它會回報平台、權限和supported_surfaces。在 macOS 上，若缺少輔助功能授權，會在此顯示；請告知使用者執行agent-desktop permissions --guide，而不是自行嘗試授予權限。 -
執行
agent-desktop skills get platform。它會載入二進位檔執行之作業系統（macOS、Windows 或 Linux）的技能，且當其與此檔案不一致時，以此為準。 -
關於旗標與語法，請執行
agent-desktop <command> --help。此技能絕不重複旗標列表，因此--help總是與已安裝版本一致。
如果 agent-desktop skills get desktop 列出的規則與此檔案不同，以二進位檔為準：此檔案是副本，二進位檔才是您實際驅動的內容。
循環
當您知道角色或確切名稱時，使用 find。否則，先映射應用程式，再深入一個區域。
agent-desktop snapshot --skeleton --app "Notes" -i --compact # 淺層映射，在剪斷的分支上顯示 children_count
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact # 深入一個區域
agent-desktop click @s8f3k2p9:e12 # 對限域參考執行操作
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact # 驗證：重新讀取相同區域
- 小型應用程式不需要 skeleton。直接使用完整的
snapshot -i。 -i只保留互動節點，因此一行的靜態文字標籤會被捨棄。要判斷重複按鈕屬於哪一行，請使用--root深入該行的容器，並省略-i。在 Windows 和 Linux 上，這樣會讀取該行，但不會使其按鈕可操作：在其他行重複的按鈕在視窗中是雙胞胎，其參考將被拒絕（請參閱參考）。--root深入會將其參考加入相同的快照 ID。深入子樹外部的參考，以及深入的根節點本身，仍然有效；原本已在內部的參考會被取代，因此舊參考會回傳STALE_REF。- 絕不對表面（surface）使用 skeleton（
--surface menu、sheet、alert）。表面已經是焦點。 - 開啟選單、工作表或警示的操作會將其列在
data.surfaces中。接下來以該疊加層為目標。 - 在非同步步驟之後，使用
wait（請參閱references/commands-system.md）。固定時間的 sleep 是一場競賽。
參考
- 輸出的參考是限域的：
@<snapshot_id>:e<N>，例如@s8f3k2p9:e1。請直接將它們傳遞給後續命令。 - 參考僅對一個快照有效。在任何 UI 變更後，請重新深入受影響的區域或拍攝新的快照。
- 僅有可定址的元素會獲得參考。靜態文字和惰性容器不會。
- 命令在執行操作前會重新識別該元素。在 macOS 上，參考攜帶元素自身的位址，因此相同的雙胞胎各自保留其參考。在 Windows 和 Linux 上，參考僅當其是視窗中、在快照中以其角色、原生 ID、名稱和描述捕獲的唯一元素時才會解析，即使在 skeleton 或深度截斷下方計數，且確實有一個活動元素仍然匹配。在那裡，相同的雙胞胎沒有參考路徑：只有
--headed mouse-click --xy X,Y可以選擇一個，它會取得前景，而 Linux Wayland 工作階段會拒絕它。 STALE_REF：該元素已消失或不再匹配。details.kind為saved_ref_absent，或在 macOS 上為retained_object_stale。請拍攝新的快照並使用新的參考。AMBIGUOUS_TARGET：出現了相同的元素（saved_ref_ambiguous），或者該參考在捕獲時未被證明為唯一（identity_not_unique）。重複參考或重新快照相同的雙胞胎會得到相同的拒絕；請對視窗中唯一的控制項執行操作。identity_not_unique也可能在快照無法及時讀取整個視窗後發生：使用更大的--timeout-ms重新拍攝。TIMEOUT且details.kind: resolution_identity_unknown：即時讀取沒有回應，因此身份未被證明。沒有發送任何內容；請重試。SNAPSHOT_NOT_FOUND：快照 ID 已過期。請重新快照。
傳送與重試
操作結果攜帶 data.disposition，錯誤則攜帶 error.disposition，每個都包含 delivery 和 retry。觀察命令（如 snapshot）在成功時沒有 disposition；它們的錯誤，以及每個 INVALID_ARGS 拒絕，都攜帶 not_delivered 和 retry: safe。
- 僅當
disposition.retry為safe時，才重試或替換操作。只有not_delivered是安全的。 - 任何其他 delivery 值表示該操作可能已執行。重複操作可能會點擊、輸入或提交兩次，而
toggle可能會取消自身。 - 對於不安全的結果，請讀取即時狀態（
get、is或新的快照）並據此決定。details.post_state在存在時會有所幫助。 - 根據
error.code和error.disposition進行分支。訊息和建議文字可能會改變。 details.retryable: false表示等待無法改變結果。請嘗試不同的方法。
無頭模式與有頭模式
參考操作預設為無頭模式。它們使用語義化的輔助功能呼叫，不會取得焦點、移動游標、合成按鍵或使用剪貼簿。如果沒有語義路徑存在，操作會以失敗關閉。僅在使用者明確允許實體輸入（例如雙擊、懸停、拖曳或焦點）時，才使用全局 --headed 旗標。請勿為了從無頭模式失敗中恢復而切換到有頭模式。原始座標（--xy）從不暗示焦點。哪些操作需要 --headed 因作業系統而異：請閱讀平台技能。
參考資料
僅在需要時載入一個：agent-desktop skills get desktop <reference>。
| 參考資料 | 何時開啟 |
|---|---|
commands-observation | 當您需要 snapshot、find、get、is、screenshot、list-surfaces 語義、部分樹或 --root 規則時 |
commands-interaction | 當您在 click、type、set-value、select、toggle、scroll、press 和 mouse 命令之間做選擇，或除錯操作錯誤時 |
commands-system | 當您啟動或關閉應用程式、管理視窗、使用剪貼簿、wait、batch、工作階段、多代理游標、追蹤或載入技能時 |
workflows | 當您想要工作模式（表單、選單、對話框、等待新視窗、捲動查找、拖曳）和反模式列表時 |