computer-use

Computer Use

使用此技能透過 orca computer 操作桌面 UI。當請求目標是網站或網頁應用程式時，請操作包含該頁面的桌面瀏覽器應用程式/視窗。

前置條件

• 優先使用 orca computer ...；在 Linux 上，如果 orca 不可用，請使用 orca-ide computer ...。在此 Orca 工作目錄中，僅在測試本機開發執行環境時使用 ./config/scripts/orca-dev computer ...。
• 優先使用 --json。螢幕截圖位元組會從 JSON 中省略，並寫入 screenshot.path。
• 除非使用者明確要求，否則不要推送、提交表單、發送訊息、購買物品、刪除資料、變更帳號設定或揭露機密。
• 如果應用程式包含敏感內容，僅讀取使用者要求的內容。

orca status --json
orca computer capabilities --json

核心循環

orca computer list-apps --json
orca computer get-app-state --app com.spotify.client --json
orca computer click --app com.spotify.client --element-index 42 --json

使用每個動作回傳的最新狀態來決定下一個元素索引。元素索引是樹狀圖中顯示的數字標籤；當雜訊部分被省略時，索引可能不連續，因此切勿從 elementCount 或「可見元素」推斷有效索引。元素索引壽命短，在延遲、導航、焦點變更、滾動、視窗變更或應用程式重新渲染後會失效。

應用程式選擇器

優先使用 list-apps 中的套件 ID；當名稱無歧義時也可接受。僅在套件 ID 或名稱匹配不明確時使用 pid:<number>。

orca computer get-app-state --app com.microsoft.edgemac --json
orca computer get-app-state --app Spotify --json
orca computer get-app-state --app pid:12345 --json

對於有多個視窗或標題不明確的應用程式，請先執行 list-windows。當列出的 ID 不是 none 時，優先使用 --window-id <id>；否則使用 --window-index <n>。一旦選擇了視窗，請將相同的選擇器傳遞給 get-app-state 和後續動作，直到目標視窗變更。

指令

orca computer permissions --json
orca computer capabilities --json
orca computer list-apps --json
orca computer list-windows --app <app> --json
orca computer get-app-state --app <app> --json
orca computer get-app-state --app <app> --restore-window --json
orca computer click --app <app> --element-index <index> --json
orca computer click --app <app> --x 100 --y 100 --json
orca computer perform-secondary-action --app <app> --element-index <index> --action <name> --json
orca computer set-value --app <app> --element-index <index> --value "text" --json
orca computer type-text --app <app> --text "text" --json
orca computer press-key --app <app> --key Return --json
orca computer hotkey --app <app> --key CmdOrCtrl+A --json
orca computer paste-text --app <app> --text "text" --json
orca computer scroll --app <app> (--element-index <index> | --x <x> --y <y>) --direction down --json
orca computer drag --app <app> --from-element-index <index> --to-element-index <index> --json
orca computer drag --app <app> --from-x 100 --from-y 100 --to-x 300 --to-y 300 --json

僅在不需要像素時使用 --no-screenshot。對敏感文字使用 --text-stdin 或 --value-stdin，以免負載進入 shell 歷史記錄。在 Linux 和 Windows 上，動作負載仍會通過短暫的本機操作檔案，因此除非使用者明確要求，否則避免發送機密：

printf '%s' "$TEXT" | orca computer set-value --app <app> --element-index <index> --value-stdin --json

動作規則

• 優先使用語意動作：可編輯欄位使用 set-value，控制項使用 click，僅對列出的動作名稱使用 perform-secondary-action。
• 在任何改變 UI 的動作之後，使用回傳的狀態或重新執行 get-app-state，然後再選擇下一個元素索引。
• 僅在聚焦欄位並確認應用程式有聚焦的文字接收器後使用 type-text；合成鍵盤傳送被報告為未驗證，因此在假設文字已輸入之前，請檢查回傳的狀態。
• 使用 press-key 處理單一/導航鍵，例如 Return、Escape、Tab 和方向鍵。僅對一個修飾鍵組合加一個按鍵使用 hotkey，例如 CmdOrCtrl+A 或 CmdOrCtrl+Shift+P；跨平台組合鍵優先使用 CmdOrCtrl+...。
• 某些動作可在背景應用程式中運作，但這取決於應用程式。如果成功未改變 UI，請重新整理狀態並選擇更語意的動作或還原/聚焦視窗。
• 對於暴露值的文字欄位，優先使用 set-value；當提供者可以讀取重新整理後的值時，它可以報告已驗證的值寫入。
• 座標是視窗本地座標；使用來自同一目標視窗最新螢幕截圖/狀態的座標。

螢幕截圖

get-app-state 回傳樹狀圖和螢幕截圖。使用樹狀圖取得索引/動作，使用螢幕截圖進行視覺確認；擷取失敗通常表示視窗隱藏、最小化、在螢幕外或權限被封鎖。

傳遞給 click、scroll 和 drag 的座標是視窗本地動作座標。如果螢幕截圖報告的 scale 不是 1，請在執行動作前轉換視覺螢幕截圖像素：

action_x = screenshot_pixel_x / screenshot.scale
action_y = screenshot_pixel_y / screenshot.scale

當可用時，優先使用樹狀圖中的元素索引或元素框架。僅在檢查最新螢幕截圖比例和視窗大小後，才使用從螢幕截圖推導的原始座標。

在 Linux 和 Windows 上，螢幕截圖可能來自目標視窗邊界內的可見桌面區域。如果視覺像素很重要，請使用 --restore-window，以免其他視窗遮蓋目標區域；如果無法取得焦點，請信任樹狀圖而非可能被遮擋的像素。

應用程式注意事項

瀏覽器：對於 Edge、Chrome、Safari 和類似瀏覽器視窗，直接設定網址/搜尋欄位，然後按 Return。不要假設原始輸入已進入網址列。當瀏覽器不在最前面時，使用 --restore-window。大型分頁列可能只顯示活動分頁加上「非活動瀏覽器分頁已省略」標記；將其視為有意的雜訊減少，並操作當前頁面/網址列，除非使用者要求管理分頁。

對於瀏覽器託管的表單（例如 Gmail 撰寫），在每個欄位動作後驗證聚焦的 UI 元素。頁面文字欄位可以暴露輔助使用動作而不移動 DOM 焦點；如果點擊或 set-value 未改變聚焦接收器，請從已知聚焦的欄位使用 Tab / Shift+Tab，或從新螢幕截圖使用視窗本地座標。對於草稿正文，優先將 paste-text 貼入已驗證的聚焦欄位，然後在繼續前檢查回傳的狀態。

orca computer get-app-state --app com.microsoft.edgemac --restore-window --json
orca computer set-value --app com.microsoft.edgemac --element-index <addressBarIndex> --value "test123" --json
orca computer press-key --app com.microsoft.edgemac --key Return --json

Spotify：在播放點擊後重新整理；UI 經常非同步變更。

Slack：輔助使用樹狀圖可能較淺，而螢幕截圖包含有用資訊。在要求時讀取可見的 Slack UI 是可以的；發送訊息或觸發工作流程仍需要明確權限。

錯誤

• app_not_found：執行 list-apps 並使用套件 ID 重試。如果目標是網頁應用程式（例如 Gmail），請選擇包含它的桌面瀏覽器應用程式/視窗；不要直接重試 orca computer ... --app Gmail，因為 orca computer 應用程式選擇器指的是桌面應用程式，而非網站名稱。
• app_blocked：停止；目標已被故意封鎖，無法使用 computer-use。
• window_not_found / window_stale：執行 list-windows，選擇當前選擇器，然後重新執行 get-app-state。
• window_not_focused：使用 --restore-window 重試一次；如果訊息表示已請求還原，請停止重試還原，並手動將應用程式帶到前景或檢查權限。對於可編輯欄位，優先使用 set-value，然後在假設鍵盤輸入有效之前進行檢查。
• element_not_found：索引已過期；再次執行 get-app-state。
• unsupported_capability：提供者或桌面環境無法執行該動作；使用語意替代方案，或如果訊息指定了缺少的依賴項，請安裝它。
• action_not_supported：檢查元素的列出動作，並使用其中一個名稱重試，或在適當時使用 click/set-value。
• value_not_settable：元素無法接受直接值寫入；聚焦它並僅在可以檢查回傳狀態時使用鍵盤輸入。
• element_not_clickable：元素沒有可操作的框架；使用具有框架的父/子元素，或從最新螢幕截圖選擇視窗本地座標。
• invalid_argument：修正指令標誌；不要原樣重試相同指令。
• action_timeout：在重試前檢查當前狀態，然後使用更簡單的語意動作，或如果觀察速度慢，使用 --no-screenshot。
• screenshot_failed：如果樹狀狀態足夠，使用 --no-screenshot；如果訊息指定了螢幕錄製或螢幕截圖權限，請執行 orca computer permissions --id screenshots --json。
• accessibility_error：執行 orca computer capabilities --json；如果訊息指定了輔助使用權限，請執行 orca computer permissions --id accessibility --json。
• 空樹狀圖或無螢幕截圖：應用程式可能沒有可見視窗、已最小化或需要權限。
• 權限錯誤：執行 orca computer permissions --json，或當訊息指定單一權限時執行 orca computer permissions --id accessibility --json / --id screenshots --json，使用設定 UI，然後重試。

下一步動作

確認 Orca 狀態（除非已檢查），然後執行 orca computer capabilities --json。對於網站或網頁應用程式目標（例如 Gmail），識別包含該頁面的桌面瀏覽器應用程式/視窗，然後使用 orca computer get-app-state --app <app> --json 取得該目標應用程式狀態。