update-guide.md

自动更新指南

应用内置自动更新, 覆盖检查, 下载校验, 安装和重启. 发布侧的产物命名与 SHA256SUMS 由 CI 保证, 详见构建与发布指南.

检查与提示

启动 5 秒后执行一次静默检查, 仅当 启动时自动检查更新 开启时进行. 发现新版本会发系统通知, 网络失败只写日志. 手动入口有两个:

• 托盘右键菜单的 检查更新, 会触发检查并打开更新窗口.
• 仪表盘和更新窗口里的 检查更新 / 重新检查.

版本比较忽略 tag 的 v 前缀和 -<commit> / ^<commit> 后缀, 只有严格大于当前版本才提示. 因此同版本重新构建不会误报, dev-build 等无法解析 semver 的开发构建始终安静.

更新窗口可以跳过某个版本, 该版本不会再被静默检查提示.

下载与校验

按平台精确匹配 release 资产, 文件名形如 codex-switch-<version>-<platform>-<arch>.<ext>, 并要求同 release 存在 SHA256SUMS. 归档下载到数据目录的 update/ 下, 支持断点续传, 下载完成后整文件计算 SHA-256 比对, 不匹配就删除重下. 下载过程中关闭更新窗口不会中断下载, 重新打开仍显示进度.

安装

Linux 和 Windows

解包归档后替换正在运行的二进制: 先把当前可执行文件改名为 <exe>.old 让位, 再把新二进制移到原路径, 中途失败会回滚. 完成后状态变为等待重启, 点 重启应用 由新二进制接管, 当前进程走正常退出路径.

macOS

macOS 的产物是 DMG, 而进程存活时 LaunchServices 会占用 Applications 中已安装的 .app, Finder 会拒绝覆盖, 直接拖拽替换会被挡住. 因此应用改为交出替换工作:

1. 下载校验通过后, 应用在 update/ 下写出 apply-update.sh 并立即启动它.
2. 应用走统一退出路径退出: 停止代理和节点服务, 释放单实例锁.
3. 脚本等待旧进程消失, 然后挂载 DMG, 用 ditto 把新的 .app 复制到目标 bundle 同目录的临时路径.
4. 旧 bundle 改名为 Codex Switch.app.old 让位, 新 bundle 就位后删除备份, 最后重新拉起应用.

脚本日志写入 update/apply-update.log. 由于替换发生在应用退出之后, 失败原因同时写入 update/apply-update-result.txt, 脚本会立刻把应用重新拉起, 新进程启动时读取该文件并在更新窗口显示失败信息. 失败分两类:

• 旧进程 60 秒内没有退出时放弃替换, 不打开 DMG. 此时应用还活着, 打开镜像同样拖不进去, 用户可以稍后重新发起更新.
• 目标目录不可写, DMG 挂载失败, 镜像中没有 .app 或复制失败时, 同样回滚并提示手动安装. 此时旧进程已经退出, 手动拖拽不会再被占用阻挡.

应用每次启动会清理上次遗留的 bundle 备份, 替换脚本和残留挂载点, 但保留日志便于排查.

便携运行 (不进 Applications, 直接跑二进制) 时没有可替换的 bundle, 仍然走打开 DMG 的手动引导.

验证

just fake-dist 以 v0.0.0 走与正式发布相同的打包流程, 产出的安装包比任何正式 release 都旧, 因此可以用它端到端验证检查, 下载, 校验, 替换和重启的完整链路. 安装该产物后, 建议配合隔离数据目录启动:

CODEX_SWITCH_DATA_DIR=target/codex-switch-fake "/Applications/Codex Switch.app/Contents/MacOS/codex-switch"

macOS 上的替换脚本也可以脱离应用单独验证: 准备一个假的已安装 bundle 和一个含 .app 的 DMG, 按脚本顶部的占位路径替换后直接执行, 检查 bundle 是否被替换, 备份是否清理, 以及 open 是否重新拉起应用.