20. 检查更新与版本
本节说明打包版桌面应用如何取得新版本。开发模式（
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 版本号；前端、后端与 Electron shell 会一并更新。
| 状态（英文 UI） | 意义 |
|---|---|
| You're up to date | 目前已是最新版本 |
| Update available | 有较新版本；可查看更新说明后按 Download now |
| Downloading update... | 正在下载完整且已验证的 App 套件。关闭对话框不会中断，但若来自系统的 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 常见情况
- 网络中断：下载失败不会损坏目前已安装的版本；修复网络后重新 Check for Updates 即可。
- Restart later：可继续使用目前版本；真正退出 App 时会安装已下载更新。Windows 若设为关闭后留在背景，关闭窗口不等于退出。
- Restart and update（Windows）：更新重启只保留安装进度，完成后自动启动新版。全用户安装仍可能出现 UAC，未签名版本仍可能出现 SmartScreen；两者都是 Windows 系统提示。首次手动安装仍会走完整安装向导。
- Restart and update（macOS）：沿用系统更新流程，没有安装百分比窗口。若 App 直接从 DMG 执行或位于只读位置，需先移到 Applications，否则无法完成更新。
- 从 0.3.3 升级：安装模式由发起更新的旧版决定，0.3.3 仍以静默方式发起，因此升到 0.3.4 仍是静默安装；0.3.4 之后的版本才会看到安装进度。
- 想停止自动提示：对该版本选 Skip this version，或忽略提示让它 24 小时后再出现。状态保存在用户数据目录，覆盖重装通常保留，但不保证重装清除。
- Release notes：更新窗口显示有长度限制的英文纯文本条目；GitHub Release 页面保留英文与繁中全文。
- 更新后仍显示旧版：请确认已按 Restart and update 并等待应用完全重启。
- 更新不可用：请至产品发布页手动下载最新版完整安装包；不要略过 checksum 或签名警告。
20.5 发布基线
0.3.0 是采用 Electron 标准整包 updater 的第一个版本。旧的热更新概念验证版无法自动升级到这个基线，需手动安装一次当前安装包。
维运与发布流程见内部桌面发布 SOP。
各版本功能条目见 /changelog，包括当前 0.3.2。
打包版若已设置官网文件 URL，App 内 Help 部分文件链接会在浏览器打开对应的公开文件页（未设置时仍使用内建 Docs）。