專案結構

安裝與配置

開始任何步驟前，請閱讀開始之前和終端基礎。在根目錄開啟 supastack 資料夾——即包含 package.json 的資料夾。Desktop checkout 包含 apps/desktop 及其釋出指令碼；All Platforms monorepo 還附帶 Web 後端和移動應用。環境變數是儲存在本地 .env 檔案或託管平臺控制台中的命名設定；外殼把 SUPASTACK_APP_URL 作為終端設定讀取，而不是從檔案中讀取。

1. 開啟 apps/desktop/src-tauri/src/lib.rs——所有原生行為都在這一個檔案裡。

2. 瀏覽 apps/desktop/src-tauri/——配置、能力和圖示。

3. 在儲存庫根目錄執行 corepack pnpm --filter @supastack/desktop dev，並確保後端可訪問。

此 checkout 只包含 Tauri 外殼：Rust 原始碼、它的配置、啟動頁和釋出指令碼。產品介面位於視窗載入的 web 應用中——僅含 Desktop 的 checkout 自己沒有應用介面。修改行為前先閱讀 AGENTS.md 和 .ai/PROJECT_CONTEXT.md；.ai/ 映象檔案記錄了單從檔案看不出的決策。

apps/desktop/src-tauri/src/    Rust — window, tray, menus, deep links, updater
apps/desktop/src-tauri/        tauri.conf.json, capabilities/, Cargo.toml, icons
apps/desktop/ui/               Boot page (index.html + boot.js) shown while loading
apps/desktop/scripts/          Release preflight + update manifest
docs/                          Runbooks incl. desktop updates
.agents/skills/                Task guides for coding agents

改動應該放在哪

編輯前先確定改動屬於哪一側：使用者視為產品介面的東西屬於 web 應用；只有作業系統層面的行為才屬於 Rust。

• 構建您的第一個桌面端功能

• 視窗、托盤、選單、快捷鍵或單例項行為 → apps/desktop/src-tauri/src/lib.rs。
• 新的 webview 許可權 → apps/desktop/src-tauri/capabilities/default.json——只有在原生功能需要時才擴大。
• 包識別符號、版本、更新器端點或外掛選項 → apps/desktop/src-tauri/tauri.conf.json。
• 佔位產品圖示 → 替換 placeholder-icon.png 並執行圖示指令碼。
• 啟動、載入或離線遮罩行為 → apps/desktop/ui/。
• 任何產品介面、設定或資料 → web 應用儲存庫——外殼絕不另起產品介面。

實現流程

做原生改動時，編輯 lib.rs，執行 cargo check 和 Rust 測試，然後在每個目標作業系統上實際操作視窗——托盤、快捷鍵和 deep-link 行為因平臺而異。.agents/skills/ 中的 add-a-desktop-capability 技能按同樣的順序走一遍。

驗證與排障

cargo check 捕獲編譯錯誤，cargo test 覆蓋純邏輯。真正的驗證是在 Windows、macOS 和 Linux 上執行真實視窗——托盤、快捷鍵和 deep link 僅靠測試無法證明。

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