Cindy自动更新机制全解:cindy-updater与启动时二进制更新
Cindy自动更新机制全解:cindy-updater与启动时二进制更新
Cindy 是一款开源、开箱即用的 AI Agent,其桌面版内置了完整的自动更新机制:由独立更新器 cindy-updater 负责应用本体的文件替换,再由启动时二进制更新保障内置 Agent 引擎(Claude Code、Codex、Pi)始终可用。本文带你快速看懂这套两层更新架构的设计思路与完整流程,适合刚接触 Cindy 桌面端的新手读者。
🧩 两层更新架构:应用更新与 Agent 二进制更新
理解 Cindy 的自动更新,先要分清"两层东西":
| 层级 | 更新对象 | 负责模块 |
|---|---|---|
| 应用层 | Cindy 桌面客户端本身(Electron 应用) | updateService.ts + cindy-updater |
| 引擎层 | 内置的 Agent 运行时二进制(claude-code、codex、pi) | agent-binaries/ 模块 |
应用更新走的是经典状态机:idle → checking → downloading → ready → 重启生效,状态定义见 updateService.ts。下载过程有 SHA-256 校验、断点续传与进度归一化,用户端永远不会看到"进度条回跳 0"这类毛刺。
而引擎二进制是独立于应用的一套资产,它有自己的清单(manifest)、下载与安装流程——这正是下一节主角。
🪟 cindy-updater:Windows 端的专职替换工
在 Windows 上,应用更新不能"边运行边覆盖自己",因此 Cindy 提供了一个独立的可执行更新器:cindy-updater。
它的设计要点(详见 cindy-updater/README.md):
- 为什么是独立的 exe? 早期 Cindy 在 Windows 更新时靠内嵌的
.cmd脚本,只能弹一个黑色命令行窗口。现在更新器有了真实 UI(进度、错误、日志按钮)、结构化错误处理,还能通过"复制到%TEMP%再启动"的模式完成自我更新,避免文件被占用无法覆盖。 - 更新六步走:
waiting(等待旧进程退出)→extracting(解压新包到临时目录)→replacing(逐文件替换安装目录)→launching(拉起新进程)→done(验证通过、自清理);任何一步出错则进入failed,释放锁文件并保留现场。 - 失败可重试:更新失败后窗口提供 Retry 按钮。失败的更新包会被移入
retry.zip防止自动重复应用;重试会重建解压与备份目录,并跳过可能被复用的旧 PID,避免误杀进程。 - 日志可追溯:全过程追加写入
<userData>/logs/cindy-update.log,单文件滚动、上限 5 MiB,排查问题一目了然。
Electron 主进程负责构造命令行参数(zip 路径、应用目录、目标 exe、PID、日志与锁路径等)后启动它,入口在 updateService.ts 的 executeUpdateWindows。
⚠️ 正因为更新链路"一处改错会无差别影响所有已安装用户",仓库将
cindy-updater列为高风险模块:任何改动都必须先与维护者确认,规则见 docs/dev-rules/cindy-updater.md。
🍎 macOS 与 Linux:各走各的可靠路径
- macOS:更新时生成一段 bash 脚本(见 updateScriptMacOS.ts),先轮询等待旧进程退出,超时后逐级升级到
SIGKILL,再替换整个.app包,最后验证新进程是否真正拉起,失败会自动重试open。 - Linux:按受管/非受管安装区分处理,更新重启可能需要输入系统密码;非受管安装等不支持的环境会明确返回原因,而不是盲目执行。
🔄 启动时二进制更新:为什么不是每次启动都升级?
引擎二进制(Claude Code、Codex、Pi 内核)体积不小,如果每次普通启动都检查并升级,既拖慢启动又浪费流量。Cindy 的策略是:
- 普通启动不升级:向二进制准备流程传入
checkForUpdates: false,本地有可用运行时就直接复用真实路径,保留用户已有的自更新结果。 - 更新重启写一次性标记:用户点击重启、空闲自动重启或启动时自动应用更新,三者走同一个执行入口,确认更新可执行后写入目标版本的一次性标记
agent-binary-update-once.json(位于 userData 目录,逻辑见 startup-update.ts)。 - 新版本启动时检查一次:进入二进制公共入口时读取并立即删除标记,仅当目标版本与当前应用版本一致才开启版本检查,随后普通启动不再重复检查。版本不匹配或损坏的标记也会被自动清理。
- 失败可恢复:更新执行被拒绝时不写标记;执行失败会清理本次标记,但不会误删更新一代的标记。
完整设计说明见 docs/desktop-startup-binary-updates.md,代码入口为 agent-binaries/index.ts。
📦 后台预取:引擎在你需要之前就已下好
除了"重启后升级",Cindy 还有一条更顺滑的路径——后台静默预取。
background-update.ts 会订阅应用更新检查拉取的清单,在独立下载队列中缓存 claude-code、codex、pi 三个引擎归档:
- 主窗口打开 10 秒后才开始,不给启动增加任何等待;
- 不更改当前引擎路径,也不删除正在使用的版本;
- 下次启动时,原安装器优先消费已校验的下载缓存,直接完成安装切换。
这样既省去了"重启后卡进度条"的体验,又对离线、缓存未就绪等情况保留本地可用版本兜底(Linux 下还有 CDN 优先 + 系统/私有运行时的回退逻辑)。
🤖 让 Agent 替你更新 Cindy
最有趣的细节:你甚至可以直接对 Cindy 说"更新 Cindy"。
Agent 通过 install_app_update 工具走的是同一条 check → download → relaunch 状态机,且宿主会弹出确认卡,写明从哪个版本到哪个版本、哪些运行中的任务会被中断(重启后可点"继续"恢复)、远程连接会短暂断开等。确认卡由宿主发起、不经 Agent 自己的审批回调,完全访问权限也跳不过;安装绑定发起时的账号,拒绝、超时都不下载不重启。产品规则详见 docs/product-rules/agent-app-update.md。
📚 关键文件速查
| 文件 / 目录 | 作用 |
|---|---|
| apps/desktop/cindy-updater/ | 独立 Windows 更新器(Rust + Tauri 全开源) |
| apps/desktop/src/main/updateService.ts | 应用更新状态机与三平台重启执行器 |
| apps/desktop/src/main/agent-binaries/startup-update.ts | 启动时一次性标记的写入与消费 |
| apps/desktop/src/main/agent-binaries/background-update.ts | 引擎二进制后台预取 |
| docs/desktop-startup-binary-updates.md | 启动时二进制更新策略全文 |
| docs/dev-rules/cindy-updater.md | 更新链路开发门禁规则 |
小结
Cindy 的自动更新用"两层架构"解决了 AI Agent 桌面应用的核心痛点:应用层交给专职更新器 cindy-updater 做可靠的安装—替换—重启,引擎层用"普通启动不升级 + 更新重启一次性标记 + 后台静默预取"组合拳,兼顾了启动速度、流量消耗与更新时效。所有更新行为日志可查、失败可重试、标记可自愈——这正是"开箱即用"背后的工程细节。🎉

