用 Desktop 連接器操作 Windows 桌面

Core 讓 ChatGPT 碰得到檔案與終端機；Desktop 讓它碰得到畫面、滑鼠與鍵盤。這是能力躍升最大、也最需要監督的一步。這篇範例用一個安全的驗收任務走完 observe 與 computer。

情境

receipt-cli 有一個 Electron 桌面殼（npm run desktop）。你要驗證一個小功能：在 App 裡按下 Copy summary 按鈕後，收據摘要會進到剪貼簿。

你在 Windows 11 上，Settings 已啟用 Desktop 連接器（全新安裝在 Windows 預設就開 Desktop 權限），ChatGPT 裡也加好了獨立的 Desktop App。

Core 與 Desktop 是分開的連接器、分開的權限邊界，使用各自 token 化的本機路徑；Core 的 token 不會授權 Desktop，反之亦然。macOS 還必須在系統設定明確開啟螢幕錄製與輔助使用權限。

目標

讓 ChatGPT 自己啟動桌面 App、看清楚畫面、按下按鈕、把剪貼簿內容讀回來驗證——全程用它自己的工具，不靠你截圖轉述。

步驟：給 ChatGPT 的 prompt

Launch the desktop build of receipt-cli with npm run desktop.

Then use the Desktop tools:
1. Observe the screen and find the main window.
2. Find the "Copy summary" button and press it.
3. Verify the action: read the clipboard and tell me what was copied.

Don't type into other applications, and don't touch windows that don't
belong to receipt-cli. If you lose track of the window, observe again
before acting.

預期的工具呼叫序列

1. exec_command(cmd: "npm run desktop")
   → 長指令：session_id
2. write_stdin(session_id: "...", chars: "")
   → App 視窗就緒的輸出
3. observe()
   → 截圖 + 視窗清單 + 該快照範圍內的 UI 控制項資訊
4. computer(actions: [
     { type: "focus",    ... },
     { type: "click_ref", ref: "<Copy summary 按鈕的語意 ref>" },
     { type: "wait",     ... }
   ], verify: {...})
   → 批次回報完成到哪一步、路線證據
5. computer(actions: [{ type: "read_clipboard" }])
   → 剪貼簿內容
6. observe()
   → 需要留證時再取一張

參數名稱以連接器當下暴露的 schema 為準；完整動作集見工具速查。

認識 observe 與 computer

observe（只讀，不移動焦點）：

讀取桌面狀態：截圖、視窗，以及快照範圍的 UI 控制項資訊。
視窗擷取會先嘗試直接背景路徑；若像素可能被遮擋，結果會標示為可見畫面回退。
螢幕存取與滑鼠／鍵盤控制是分開的權限——可以只讓它看、不讓它動。

computer（有界批次）：

目前動作集：click_ref、set_value、click、double_click、move、drag、scroll、type、keypress、focus、wait、read_clipboard、write_clipboard。
批次會回報已完成步驟與路線證據；部分失敗時明確指出失敗的索引。
語意 ref（click_ref）指向某次有界快照快取的 UI Automation／AXUIElement 物件；物件過期就失敗，不會拿一個可重用的原生識別碼重新掃描——所以畫面變了要重新 observe。
座標動作會指名它依據的影格，並在實際輸入前重新驗證目標視窗幾何。
可選的緊湊 verify 後置條件能在同一次呼叫裡等前景視窗、視窗開／關或某個 UI 控制項出現／消失，並把結果狀態一起帶回。
每一步都對照當下的畫面／控制／剪貼簿權限。Read-only 模式可以保留 observe，同時停用會改變狀態的動作。

驗收方式

剪貼簿內容與 App 內顯示的摘要一致。
ChatGPT 能說出它按了哪個控制項、用什麼證據確認結果，而不是只說「應該成功了」。
過程中沒有其他視窗被你的鍵盤輸入波及。

注意事項

Desktop 只在 Windows 與 macOS 發布；Linux 不廣告也不執行這些 schema，且會在執行期把 Desktop 權限遮罩（你儲存的選擇會保留，之後換到 Windows／macOS 仍可用）。
桌面控制不受核准資料夾限制：它可以在你登入的使用者能作用的範圍內行動。跑這類流程時，請把螢幕讓給它。
你隨時可以反悔：Read-only、停用 Desktop 權限，或在對話中 Block —— Block 撤銷的是該對話的本機工具，不代表取消 provider 端的生成。
這是外掛生態、安全邊界與責任使用的核心案例：能力越強，監督越重要；被 provider 擋下的動作，不要換個工具或連接器重做。