orca-per-workspace-env

獨立工作區環境 (Per-Workspace Environments)

本檔案僅為功能偵測用存根（Discovery Stub），並非完整的使用指南。與版本完全匹配的獨立工作區環境完整參考手冊，是由 orca 執行檔本身直接提供——特意不收錄於此檔案中，以確保說明內容永遠不會與實際執行命令的執行檔版本產生偏差。

每當你需要設定、檢視、偵錯或驗證獨立工作區環境 Recipe（亦即在每次建立工作區時，重新生成的隨需用即棄執行環境，包含雲端沙盒、虛擬機器或本機環境）時，請使用 Orca。內容涵蓋首次設定（服務提供者先決條件、可重複使用的基礎快照、Coding Agent 身份驗證快照、憑證與狀態），而不僅僅是獨立工作區的生命週期指令碼。可用於建置獨立工作區環境、修復 orca.yaml 中的 environmentRecipes 項目、腳手架（scaffold）生成提供者的生命週期指令碼，或排除 orca vm recipe doctor 執行失敗的問題。Orca 是一個輕量包裝器（Thin Wrapper）：由你負責引導、偵測與生成腳手架；你絕不能直接掌控使用者的雲端帳號、計費、映像檔或憑證，且在未取得使用者明確同意前，絕對不可產生任何費用。

確定此工作階段使用的 CLI

請先確定一次要採用的執行檔，後續所有命令皆重複使用該執行檔：

• 若已設定 ORCA_CLI_COMMAND 環境變數，請使用其設定值。Orca 會在受控的 WSL 工作階段中匯出此變數。
• 否則，在暴露 ORCA_DEV_REPO_ROOT 的開發原始碼目錄（Dev Checkout）中，請使用 orca-dev。
• 否則，在 Orca 受控終端機之外的 Linux 環境中，請使用 orca-ide。切勿在該環境下直接執行單純的 orca——在 Orca 終端機之外，它通常會指向 GNOME Orca 螢幕閱讀器（/usr/bin/orca），並開始在使用者的電腦上進行語音朗讀。
• 否則，請使用 orca。

在下文中，ORCA 為您所確定的執行檔預設占位符。在執行任何命令前請先將其替換；請勿建立 Shell 變數或直接執行字面上的 ORCA。此規則在 POSIX Shell、PowerShell 及 cmd.exe 中皆相同。

若選定的執行檔無法執行，請回報其確切的錯誤訊息並停止操作。請勿退回（fall through）使用其他執行檔，否則可能會在無意中指向不同的 Orca 建置版本。

執行 Orca 命令前請先載入完整指南

ORCA skills get orca-per-workspace-env

這會輸出與目前處理後續命令的執行檔版本完全匹配的完整指南——包含提供者設定、基礎與驗證快照、orca.yaml 中的 environmentRecipes、生命週期指令碼，以及 orca vm recipe doctor。請先閱讀指南，再執行您所需的具體命令。

切勿憑記憶或此存根的快取內容去猜測子命令或旗標（Flags）。這些選項在不同的 Orca 版本間可能會有變動，因此本檔案特意不再列出。請使用 ORCA status --json 確認應用程式正常運作（若有需要，可用 ORCA open --json 啟動），且在 Agent 自動化呼叫時，請優先使用 --json。

若舊版 Orca 無法識別 skills get

僅在選定的執行檔明確回報 skills get 為未知命令時，才使用此退回方案（Fallback）。其他失敗情況並不能證明執行檔版本過舊；請直接回報錯誤，而非隨意猜測或更換執行檔。對於已確認不支援新版指南的舊版執行檔，僅能使用以下有限的唯讀引導程序（Bootstrap）來熟悉現狀。請勿陷入死胡同，也切勿自行發明不存在的命令：

ORCA status --json
ORCA vm recipe doctor <recipe-id> --repo-path <repo> --json

上述 doctor 命令為免費的靜態檢查。未經使用者明確批准，切勿加上 --provision，因為這會建立提供者資源並可能產生費用。

接著請告知使用者，更新 Orca 即可透過 ORCA skills get orca-per-workspace-env 恢復完整的版本匹配指南。除了上述命令之外，請直接詢問使用者，而不是去猜測該舊版執行檔可能不支援的命令功能。