platform/computer-use/src/api.zh-TW.md

Computer Use 是獨立且持久的 JavaScript REPL，直接呼叫 cua_repl；無需 Code Mode。變數與綁定物件在目前 Host 程序內跨呼叫和 Turn 保留。重新啟動後 REPL 沒有歷史變數；請遵循模型請求提供的目前 Computer Use 狀態。
`cua.computer.target` 識別選定的桌面平台（`mac`、`linux`、`windows`）。WSL 預設選擇 Windows 主機；Shell 命令仍可能在 Linux 中執行。

全新 REPL 沒有綁定目標。以下入口會輸出 API 文件及清單或目標初始狀態。瀏覽器 ID 只來自已設定的提供者；未設定時，透過 getApp 操作原生瀏覽器視窗。API 不提供 start_session 等驅動程式管理操作。

入口（選擇目標時自動輸出初始狀態）：
- `await cua.getState({emit?})`：應用程式和已設定瀏覽器清單，包括清單錯誤。
- `await cua.listApps({emit?})`、`await cua.listWindows({emit?})`。
- `const app = await cua.getApp("Name / bundle ID / app path")` 或 `getApp({windowId})`。
  macOS 會啟動缺少的應用程式。Windows getApp 選擇已開啟的視窗；先使用來自 cua.listApps() 的 ID 呼叫 `await cua.computer.launch_app({app: appId})`，再重新整理清單並選擇確切視窗。啟動前會重新核對原生清單中的 ID，不接受任意可執行檔路徑。名稱有歧義時選擇確切視窗。Linux 要求應用程式已開啟。
- `await cua.listBrowsers({emit?})`、`await cua.listTabs({browser?, emit?})`。
- `const browser = await cua.getBrowser({id? , url?})`：只選擇，不開啟分頁。
- `const tab = await cua.getTab("tab ID", {browser?})` 或 `getTab({url}, {browser?})`。
- `await cua.createBrowserTab(browserId, url?)`：在已設定的設定檔中開啟。無法使用的提供者、分頁提及和不支援的建立選項會擲出錯誤。

App 和 Tab 觀察：
- `getAXState({emit?, disableDiffing?})` 傳回文字。分頁和 macOS 應用程式預設傳回差異；Windows 和 Linux 應用程式傳回完整狀態。
- `getScreenshot({emit?})` 傳回 Uint8Array 並輸出影像。
- `getAXStateAndScreenshot(options?)` 傳回 `{state, screenshot}` 並輸出兩者。
探索、選擇和觀察會自動輸出結果，直接呼叫即可。用 `nodeRepl.emitImage()` 包裝 `getScreenshot()` 或用 `nodeRepl.write()` 包裝 `getAXState()` 會重複輸出。自行處理結果時使用 `{emit:false}`；清單錯誤仍會顯示。同一次呼叫內相同影像只交付一次；之後的呼叫可以再次輸出相同影像。
觀察包含短暫 UI 更新的有限穩定等待（分頁 200 ms，應用程式 400 ms），不會等待任意非同步工作，持續動畫不會延長視窗。之後的更新需重新觀察。僅擷取畫面的觀察會清除輔助使用索引。
若應用程式忙碌導致原生 AX 觀察失敗，待應用程式恢復後重新整理同一綁定物件。失敗的觀察會使舊索引和座標失效。

App 和 Tab 操作：
- `moveCursor(index | [x,y])` 用合成游標指示已觀察的位置。座標與 `click` 使用同一張目前擷取畫面，指示不會消耗畫面。傳回的可見性是顯示回饋，不證明輸入效果。
- `click(index | [x,y], {mouseButton?, clickCount?})`、`drag([x,y], [x,y])`。
- `scroll(index | [x,y], "up" | "down" | "left" | "right", pages?)`。
- `setValue(index, string)`。
- `selectText(index, text, {prefix?, suffix?, selectionType?})`，selectionType 為 `text`、`cursor_before` 或 `cursor_after`。原生選取僅支援 macOS。`text_not_found` 表示文字或指定上下文不存在，請重新讀取目前狀態。`ambiguous_text` 需要更具體的 prefix/suffix。
- `performSecondaryAction(index, action)`：使用原生 AX 觀察中列出的確切操作。CDP 不提供次要操作，會拒絕此方法。

App 輸入：`typeText(text)`、`paste(text, {format?})`、`pressKey(key)`。
Tab 輸入：`typeText(index|null, text)`、`paste(index|null, text, {format?})`、`pressKey(index|null, key)`。指定索引會先聚焦已觀察的欄位，`null` 表示目前焦點。按鍵範例：`Return`、`Tab`、`super+a`、`shift+Left`。
貼上格式：`text`（預設）、`md`（將 Markdown 原始碼作為純文字）和 `html`。原生 HTML 貼上僅支援 macOS，需要可讀的可編輯值和選取範圍；它會暫時啟用確切視窗、保留選取範圍，並還原原剪貼簿，除非使用者已複製更新的內容。值未改變會回報為不確定。瀏覽器 HTML 貼上需要已觀察的 contenteditable 元素。

Tab 導覽：`goto(url)`、`back()`、`forward()`、`reload()`、`close()`。導覽支援 HTTP(S) 和 about:blank，並等待可觀察的文件。涵蓋主要 CDP 目標；跨程序 iframe 輔助使用支援尚不完整。
原生捲動接受頁數。macOS 和 CDP 也接受 `{pixels:500}` 輸入增量；應用程式可能限制、動畫化或轉換增量。Windows/Linux 原生配接器目前拒絕像素單位輸入。macOS/Windows 索引捲動保留選定的輔助使用目標。原生索引點擊支援一次語義點擊；需要多次點擊時使用擷取畫面座標。

輸入派發成功不代表已經確定應用程式的結果狀態。
座標屬於最新擷取畫面。移動/縮放、導覽、捲動或任何操作都會消耗或使映射失效；再次按座標操作前重新擷取畫面。原生語義操作使用保留的輔助使用元素。應用程式選單僅限所屬程序和確切綁定視窗，關閉選單的內容不會顯示。選單互動可能啟用綁定視窗，並在選單開啟時保持啟用。
macOS/Windows 座標和鍵盤輸入透過確切視窗的前景路徑交付；macOS 在支援時還原先前應用程式。Linux 保持背景交付。座標輸入可能移動系統指標。未驗證的輸入效果會在呼叫輸出中回報。沒有公開的 `delivery_mode` 選項，也不會自動重播。

`nodeRepl.write(value)` 輸出文字/JSON。`await nodeRepl.emitImage(bytes | dataUrl | {bytes, mimeType})` 輸出影像。不提供檔案/HTTP 影像 URL、Node、任意檔案系統和網路 API。`cua.rewriteDocumentation()` 重新輸出此參考文件。

每次操作都使用目前 Host 權限；JS 物件不保留授權。Ask 模式下，Computer Use 核准在 REPL 執行逾時計時開始前完成。macOS 原生操作在螢幕鎖定時回報 `desktop_locked`；已連線 CDP 提供者和純 REPL 計算仍可獨立使用。
每個 Session 有獨立的 Maka 游標。輸入操作自動顯示游標；僅指示而不操作時才呼叫 `moveCursor`。`cua.cursor.configure({label?, color?, enabled?, reducedMotion?})` 修改此 Session 的顯示。顏色為 `blue`、`mint`、`violet`、`amber`、`rose`、`cyan`；標籤最多 48 個字元。`cua.cursor.getState()` 回報設定及原生/瀏覽器可見性。處於 `idle` 的原生繪製器在首次原生指示時啟動；`unavailable` 表示顯示主機缺少或失敗。重新設定可重試失敗的繪製器。閒置游標保留至停用或清理。游標不共享輸入權限，也不移動系統指標。多個游標不能隔離實體鍵盤、應用程式焦點或輸入法。
REPL 被取消、逾時或耗盡堆積記憶體後，需要 `cua_reset` 並重新綁定目標。已接納的原生工作會在傳回前結算；重設不會撤銷已派發的輸入。重設僅清除此 Session 的 REPL 和綁定，使用者應用程式和分頁保持開啟。