20. 檢查更新與版本
本節說明打包版桌面應用的完整 App 更新。開發模式（
npm run dev）不連正式更新來源。
20.1 自動檢查與手動檢查
App 約每 24 小時自動檢查一次正式版。啟動後會先等 30 秒，再加最多 60 分鐘的隨機延遲，避免每次開 App 都立刻連網；睡眠喚醒後若已錯過多輪，只補一次。
有新版且主視窗在前景可互動時，會出現系統提示，三個選項的意義是：
| 選項 | 行為 |
|---|---|
| Update and restart | 直接開始下載，就緒且未儲存內容確認完畢後重啟 |
| Skip this version | 只抑制這個版本的自動提示；不下載、不安裝，更新版仍會提示 |
| Later | 24 小時後再提示同一個版本；不下載、不安裝 |
提示的 Later 不等於下載後的 Restart later：前者還沒下載，退出 App 不會安裝。
手動檢查永遠可用，也不受 Skip 影響：Help → Check for Updates...。手動檢查還能找到標示 Preview 的公開試用版本，該次檢查不會因此變成持續訂閱預覽通道。
20.2 對話框狀態
畫面只顯示一個 App 版本號；frontend、backend 與 Electron shell 會一起更新。
| 狀態（英文 UI） | 意義 |
|---|---|
| You're up to date | 目前已是最新版本 |
| Update available | 有較新完整版本；可查看說明並按 Download now |
| Downloading update... | 正在下載；關閉 Dialog 不會中斷，但若來自系統提示的 Update and restart，關閉即撤銷本次自動重啟 |
| Preparing update. | macOS 已下載、原生更新器尚在準備；App 仍可正常使用 |
| Update ready | 按 Restart and update 立即套用，或 Restart later |
| Update failed | 網路、metadata、checksum 或簽章驗證失敗；可 Retry |
Preview 版本會標示 Preview 與試用風險，按鈕為 Download preview。版本類型無法確認時顯示無法驗證並停用下載，不會當成正式版。
20.3 重啟前的未儲存保護
選擇重啟後，App 會先檢查主視窗與 compare 中所有可編輯視窗的未儲存內容：
- 沒有未儲存內容才自動繼續。
- 有未儲存內容時預設 Return to app（Esc 同），下載結果保留，存好後再按 Restart and update。
- 讀不到未儲存狀態時不自動繼續，回到可操作的已下載畫面並提示重試。
執行中的查詢不會阻擋提示，但重啟會中斷查詢與外部 Agent 連線。
20.4 常見情況
- 網路中斷：不會損壞目前版本；恢復網路後 Retry。
- Restart later：可繼續使用舊版；真正退出 App 時會安裝已下載更新，且不強制重新開啟。Windows 若設定關閉到背景，關閉視窗不等於退出；macOS 紅色關窗也不是退出。
- Restart and update（Windows）：更新重啟只保留安裝進度，完成後自動啟動新版。all-users 安裝仍可能出現 UAC；unsigned 版本仍可能出現 SmartScreen，兩者都是 Windows 系統提示。首次手動安裝仍會走完整安裝精靈。
- Restart and update（macOS）：沿用系統更新流程，沒有安裝百分比視窗。若 App 直接從 DMG 執行或位於唯讀位置，需先移到 Applications，否則無法完成更新。
- 從 0.3.3 升級：安裝模式由發起更新的舊版決定，0.3.3 仍以靜默方式發起，因此升到 0.3.4 時仍是靜默安裝；0.3.4 之後的版本才會看到安裝進度。
- Release notes：更新視窗顯示 English 純文字條列；GitHub Release 頁保留 English 與繁中全文。
- 更新後仍顯示舊版：請選 Restart and update，並等待 App 完全退出及重啟。
- 更新不可用：可至產品 Release 頁人工下載完整安裝包；不要略過 checksum 或簽章警告。
- 想停止自動提示：對該版本選 Skip this version，或忽略提示讓它 24 小時後再出現。狀態保存在使用者資料目錄，覆蓋重裝通常保留，但不保證重裝清除。
各版本功能列點見 /changelog。維運人員的桌面版發佈流程請依專案內 Docs/desktop-release.md 執行。