> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 執行並配置外殼

啟動 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/` 映象；檢查此處指定的確切原始檔；列出檔案並在編輯前進行檢查；保留工作區所有權和僅限伺服器的機密；並向您展示差異。告訴它您想要的行為、輸入和輸出欄位、允許的角色、預期的成功和錯誤以及測試帳戶、提供程式或裝置。使用樣本值；永遠不要貼上真正的秘密。

[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md)

[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)

[桌面本地設定](https://supastack.dev/zh-tw/docs/desktop/ship-in-5-minutes.md)

[座席提示和專案記憶體](https://supastack.dev/zh-tw/docs/web/agents.md)

```
# 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 檢查本身並不能證明這些本機互動。

[桌面驗收](https://supastack.dev/zh-tw/docs/desktop/release.md)


## 安裝與配置

安裝工作區依賴項和 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:// 路由留在配置來源、托盤和快捷鍵，以及重啟後登入狀態是否保留。


如果你想繼續完成設定，可以閱讀《[建立桌面端釋出賬戶](https://supastack.dev/zh-tw/docs/desktop/external-accounts.md)》。


## 下一篇

[建立桌面端釋出賬戶](https://supastack.dev/zh-tw/docs/desktop/external-accounts.md)