For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/desktop/run.md (or send Accept: text/markdown).

執行並配置外殼

啟動 Tauri 開發外殼，並讓它連線到你的 Web 應用。

詢問本指南

初學者演練

先決條件：閱讀下面的兩個初學者指南並完成桌面本地設定，包括 Rust 和作業系統先決條件。該程式碼塊啟動了 web 應用程式和 monorepo 中的 Tauri；在僅限桌面的結賬中，僅在單獨啟動可訪問的 Web 後端後才使用其過濾命令。 Tauri 載入該後端。

簡而言之：工作區是一個團隊的單獨使用者、資料和設定。伺服器是可信後端；讓提供商金鑰遠離瀏覽器和電話程式碼。遷移是建立或更新表的版本化資料庫更改。人工智慧模型是回答的引擎；型號目錄是伺服器上可用型號 ID 和價格的列表。提供商是一種外部服務，例如人工智慧、電子郵件或計費服務。權利是允許工作區使用某項功能的授權。 Webhook 是一個服務傳送到另一個服務的 URL 的訊息。

1、開啟apps/desktop/src-tauri/src/lib.rs；要求您的代理僅更改指定的視窗/托盤/熱鍵行為，並將產品 UI 保留在 Web 應用程式中。

2、執行shell並測試close-to-tray、Quit、CmdOrCtrl+Shift+Space；測試supastack:///settings/appearance?preview=1#main。

3. 它應該聚焦現有視窗並保留路徑/查詢/片段。如果開啟錯誤的頁面，請比較配置的起點和確切的路線。

對於自定義程式碼，請從提供的 prompts/README.md 開始，然後複製最接近的提示：對於應用程式螢幕為 prompts/new-app-screen.md，對於公共頁面為 prompts/new-landing-page.md。對於伺服器、資料庫或提供商工作，請為您的編碼代理提供本指南的任務，並要求其讀取 AGENTS.md、.ai/PROJECT_CONTEXT.md 和匹配的 .ai/ 映象；檢查此處指定的確切原始檔；列出檔案並在編輯前進行檢查；保留工作區所有權和僅限伺服器的機密；並向您展示差異。告訴它您想要的行為、輸入和輸出欄位、允許的角色、預期的成功和錯誤以及測試帳戶、提供程式或裝置。使用樣本值；永遠不要貼上真正的秘密。

# Monorepo: start the web app and desktop shell together
corepack pnpm dev:desktop

# Desktop-only checkout: start Tauri after a web backend is already reachable
corepack pnpm --filter @supastack/desktop dev

在 Rust 中保持 shell 行為

src-tauri/src/lib.rs 建立主 1200×800 webview 視窗。關閉時將其隱藏到托盤中；退出退出。本機選單提供主頁/後退/前進/重新載入、縮放/全屏和視窗操作。視窗狀態恢復保留大小/位置。

處理連結和召喚

外殼接受 supastack:// 路由，並按精確配置的 HTTP(S) 應用來源解析。supastack:///settings/appearance?preview=1#main 這類純路徑連結直接對映為 /settings/appearance?preview=1#main，supastack://workspace/settings 這類帶 authority 的連結對映為 /workspace/settings；supastack:///auth/callback?code=... 對映為 /auth/callback?code=...。查詢字串與片段原樣保留。

啟動連結在第一個視窗顯示之前生效。macOS 執行時連結走 Tauri 的 on_open_url；Windows 與 Linux 的第二例項引數走啟用了 deep-link 特性的單例項回撥。合法連結會聚焦並導航現有視窗。

只有具備精確配置的 scheme、主機與有效埠的無憑據 HTTP(S) 連結才留在外殼內。無憑據的 HTTP(S)、mailto:、tel: 連結可從外部開啟；畸形連結、憑據、不受支援的 scheme、自定義連結上的埠以及路徑穿越都會被拒絕。配置的後端 URL 同樣拒絕憑據，並回退到下一個有效/預設來源。

SUPASTACK_APP_URL=https://your-app.example
SUPASTACK_DESKTOP_HOTKEY=CmdOrCtrl+Shift+Space

supastack:///settings/appearance?preview=1#main
# Opens https://your-app.example/settings/appearance?preview=1#main

驗證特定於平臺的行為

注入的離線覆蓋提供重試、線上隱藏和重新載入 Web 應用程式。在每個目標作業系統上測試焦點、快捷鍵、選單縮放、托盤和深層連結呼叫；單元 URL 檢查本身並不能證明這些本機互動。

桌面驗收

安裝與配置

安裝工作區依賴項和 Rust 工具鏈以及 Tauri 的每個作業系統先決條件（WebView2 隨 Windows 一起提供；macOS 和 Linux 需要其記錄的軟體包）。 corepack pnpm --filter @supastack/desktop dev 執行 tauri dev：它構建 Rust 核心，顯示佔位符 UI，並載入已解析的應用程式 URL。

執行時 SUPASTACK_APP_URL 優先，其次採用構建時寫入的值。僅接受不帶憑據的 HTTP(S) 地址；無效時繼續嘗試下一候選值。SUPASTACK_DESKTOP_HOTKEY 覆蓋預設 CmdOrCtrl+Shift+Space；無效值會回退到預設快捷鍵，不會阻止啟動。

corepack pnpm --filter @supastack/desktop dev
corepack pnpm --filter @supastack/desktop typecheck

SUPASTACK_APP_URL=https://app.example.com \
SUPASTACK_DESKTOP_HOTKEY=CmdOrCtrl+Shift+Space \
corepack pnpm --filter @supastack/desktop dev

實現流程

主視窗只在配置的精確來源中導航，包括協議和埠。無憑據的 HTTP(S)、mailto 和 tel 連結可以交給系統瀏覽器開啟；其他協議會被取消。

已註冊的 supastack:// 連結會將路徑、查詢引數和片段對映到配置的應用來源。啟動時、平臺開啟 URL 事件和第二例項回撥都使用同一套驗證，深連結不能把外殼重定向到其他主機。

托盤圖示和全域性快捷鍵會顯示並聚焦唯一主視窗。快捷鍵無響應時，通常是另一個應用佔用了組合鍵；請改用其他 SUPASTACK_DESKTOP_HOTKEY。

驗證與排障

修改 src-tauri 後，通過包指令碼執行 cargo check 和 cargo test。然後端到端驗證精確來源導航、允許的外部 URL 開啟、supastack:// 路由留在配置來源、托盤和快捷鍵，以及重啟後登入狀態是否保留。