Cindy自动更新机制全解:cindy-updater与启动时二进制更新

原创2026-10-28 19:26:171,622 阅读
文章标签:人工智能AI Agent代码智能体大模型AI 技能Agent 记忆工具调用MCP Clients多智能体浏览器控制GUI 自动化本地部署插件系统桌面应用移动开发前端跨平台语音任务调度交互助手

Cindy自动更新机制全解:cindy-updater与启动时二进制更新

Cindy 是一款开源、开箱即用的 AI Agent,其桌面版内置了完整的自动更新机制:由独立更新器 cindy-updater 负责应用本体的文件替换,再由启动时二进制更新保障内置 Agent 引擎(Claude Code、Codex、Pi)始终可用。本文带你快速看懂这套两层更新架构的设计思路与完整流程,适合刚接触 Cindy 桌面端的新手读者。

Cindy开源AI Agent桌面端官方主视觉,支持开箱即用的自动更新体验

🧩 两层更新架构:应用更新与 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桌面客户端界面截图,插件页面展示了简洁的桌面端体验

它的设计要点(详见 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 的策略是:

  1. 普通启动不升级:向二进制准备流程传入 checkForUpdates: false,本地有可用运行时就直接复用真实路径,保留用户已有的自更新结果。
  2. 更新重启写一次性标记:用户点击重启、空闲自动重启或启动时自动应用更新,三者走同一个执行入口,确认更新可执行后写入目标版本的一次性标记 agent-binary-update-once.json(位于 userData 目录,逻辑见 startup-update.ts)。
  3. 新版本启动时检查一次:进入二进制公共入口时读取并立即删除标记,仅当目标版本与当前应用版本一致才开启版本检查,随后普通启动不再重复检查。版本不匹配或损坏的标记也会被自动清理。
  4. 失败可恢复:更新执行被拒绝时不写标记;执行失败会清理本次标记,但不会误删更新一代的标记。

完整设计说明见 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 做可靠的安装—替换—重启,引擎层用"普通启动不升级 + 更新重启一次性标记 + 后台静默预取"组合拳,兼顾了启动速度、流量消耗与更新时效。所有更新行为日志可查、失败可重试、标记可自愈——这正是"开箱即用"背后的工程细节。🎉

登录后查看全文
cindy