Craft Agents自动更新系统解析：auto-update.ts工作原理

Craft Agents自动更新系统解析：auto-update.ts工作原理

【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss

Craft Agents 是一款面向 AI 智能体协作的开源桌面应用，它的自动更新系统让用户无需手动下载安装包即可保持版本最新。本文带你拆解核心文件 auto-update.ts 的工作原理：它基于 electron-updater 实现，启动即检查、后台静默下载、下载完成一键重启安装，并针对 macOS / Windows / Linux 三大平台分别采用 zip 包、NSIS 安装包、AppImage 三种安装策略，真正做到"无感更新"。

📦 更新组件全景：谁负责什么？

整个自动更新机制由三层协作完成，各文件职责清晰：

更新清单托管在agents.craft.do/electron/latest这个地址上，由 electron-builder.yml 中的publish段（第 76-79 行）声明。electron-updater 会定期拉取该地址的 YAML 清单，比对本地版本号，判断是否有新版本。

🔄 核心流程：从启动检查到重启安装

1️⃣ 启动即检查，自动下载

应用启动时，主进程入口 index.ts 会调用checkForUpdatesOnLaunch()。它内部委托给 electron-updater 的autoUpdater.checkForUpdates()，且默认开启autoDownload = true——发现新版本后自动开始后台下载，用户无需点击任何按钮（见 auto-update.ts 第 125-139 行）。

这里有个贴心细节：checkForUpdates()支持autoDownload参数，手动"检查更新"时可临时关闭自动下载，避免在计流量连接上浪费流量，检查结束后还会恢复原设置。

2️⃣ 一套状态机贯穿始终：UpdateInfo

所有更新状态都收敛为一个UpdateInfo对象（定义于 dto.ts）：

• downloadState：idle → downloading → ready → installing，出错则进入error
• downloadProgress：0-100 的实时进度
• currentVersion/latestVersion：当前与最新版本号

electron-updater 每触发一个事件（update-available、download-progress、update-downloaded、error），auto-update.ts 中的事件处理器就同步更新这个对象，并广播给所有渲染窗口——UI 永远是"最新真相"的镜像。

3️⃣ 断点续传的聪明做法：缓存目录检测

如果上次启动时更新已下载到一半甚至已完成，再次启动时不必重复下载。系统通过checkForExistingDownload()扫描各平台的更新缓存目录（Windows 为%LOCALAPPDATA%\{app}-updater\pending，macOS 为~/Library/Caches/...），优先读取 electron-updater 写入的update-info.json做二次确认，直接标记为ready状态（见 auto-update.ts 第 274-321 行）。

4️⃣ 一键安装，多窗口状态不丢失

用户点击"重启并安装"后，installUpdate()做三件事（auto-update.ts 第 384-429 行）：

1. 调用quitAndInstall()，让 electron-updater 按平台策略完成替换并自动拉起新版本；
2. 置位__isUpdating标志，防止主进程误判为普通退出而强制杀掉更新流程；
3. 执行beforeUpdateQuitHook——在窗口被销毁前快照多窗口布局，避免重启后窗口状态被清空。

🖥️ 三大平台差异化安装策略

不同操作系统使用不同的产物格式，但都由 electron-updater 原生接管，无需外部脚本：

各平台的打包规则、图标与命名规则统一由 electron-builder.yml 定义，例如 Windows 采用 per-user 安装到%LOCALAPPDATA%\Programs\，避免权限问题（第 190-195 行）。

💬 用户友好设计：进度可见 + 一键免打扰

渲染进程的 useUpdateChecker.ts Hook 是用户与更新系统的"界面"：

• 进度条：订阅onUpdateDownloadProgress事件，实时刷新百分比；
• 更新就绪 Toast：下载完成后弹出提示，带"重启"按钮，10 秒后自动收起；
• 不再提醒：用户关闭提示后，版本号会被持久化到用户配置（dismissedUpdateVersion，见 storage.ts），重启应用也不会再次打扰；一旦用户主动点击安装，该记录立即清除。

此外，菜单栏会动态追加"安装更新…"选项（menu.ts 第 60-69 行），即使弹窗被错过，入口也始终存在。

📁 关键源码索引

• 主进程更新核心：apps/electron/src/main/auto-update.ts
• 启动时触发与事件总线接入：apps/electron/src/main/index.ts
• IPC 通道定义（getUpdateInfo/installUpdate）：apps/electron/src/transport/channel-map.ts
• UI 状态 Hook：apps/electron/src/renderer/hooks/useUpdateChecker.ts
• 更新源与打包产物配置：apps/electron/electron-builder.yml
• 版本号唯一来源（读取 package.json）：packages/shared/src/version/index.ts

✅ 小结

Craft Agents 的自动更新系统是一个教科书级的 Electron 更新方案：electron-updater 负责"搬运"，auto-update.ts 负责"编排"。状态机 + 事件广播让 UI 始终同步，缓存检测避免重复下载，平台差异化策略保证三端一致体验，而"不再提醒"与多窗口状态快照等细节，则体现了对真实使用场景的细致打磨。理解了这套机制，你也可以快速为自己的 Electron 桌面应用搭建可靠的自动更新能力。

【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss