> ## 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

# 專案結構

找到 Rust 外殼、啟動頁、釋出指令碼以及與 web 應用的邊界。

## 安裝與配置

開始任何步驟前，請閱讀[開始之前](https://supastack.dev/zh-tw/docs/desktop/before-you-start.md)和[終端基礎](https://supastack.dev/zh-tw/docs/desktop/terminal-basics.md)。在根目錄開啟 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。

[構建您的第一個桌面端功能](https://supastack.dev/zh-tw/docs/desktop/first-feature.md)

- 視窗、托盤、選單、快捷鍵或單例項行為 → `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
```


## 下一篇

[構建你的第一個功能](https://supastack.dev/zh-tw/docs/desktop/first-feature.md)