OpenProgram 正式版本更新设计

本文定义普通 Desktop、CLI/server 与源码开发安装如何发现和应用新版本。稳定安装只消费完整、已发布、已验证的 GitHub Release；GitHub 仓库出现新提交不等于可安装更新。

1. 已确定的设计约束

1. stable 只解析 GitHub 上最新的非 draft、非 prerelease 正式 Release。普通用户永远不跟踪 main、任意 commit 或未完成的 tag。
2. 更新单位是完整平台产物，不做 Python wheel、Web、Program、OCR、Browser 或模型的局部产品更新。新版本必须继续满足统一 capability manifest。
3. 默认自动检查，首次启动延迟执行；成功检查后每 24 小时检查一次，失败后最早 6 小时重试。网络错误不影响应用启动，也不循环弹窗。
4. Desktop 与 CLI/server 共用版本解析、Release 选择和 checksum 规则，但安装动作按产物不同实现。
5. 当前 macOS Desktop 使用 unsigned DMG。应用内负责检查、架构选择、完整下载和 SHA-256 校验，并在校验成功后打开 DMG；不实现自定义后台进程替换正在运行的 .app。
6. macOS/Linux CLI/server 复用现有 release installer：下载到新版本目录，验证完整 runtime 和 worker cold start，成功后原子切换 current，失败时保留原版本。
7. 源码开发安装继续使用显式 Git ref 的 openprogram upgrade 流程。设置页不能把源码 checkout 更新解释为普通稳定更新。
8. 当前只提供一个 stable 通道，不显示没有实际行为差异的通道选择器。
9. 删除 worker 启动时的“检查并自动应用”行为。OPENPROGRAM_IMMUTABLE_RUNTIME=1 的 managed runtime 和 Desktop 不允许进入旧的 Git/PyPI updater；openprogram update 只保留为 openprogram upgrade 的兼容入口。
10. 统一安装类型只有 managed_release、source_checkout 和 unknown。检测时 OPENPROGRAM_IMMUTABLE_RUNTIME=1 优先于 site-packages 等路径启发式规则；正式产品不得显示或使用 pip_wheel 更新语义。

2. 实施前基线与当前实现

3. 官方规范与方案比较

4. 统一版本与 Release 模型

• 版本比较只接受三段数字 SemVer，去掉 tag 前缀 v 后逐段数值比较；不使用字符串排序。
• 发现相同或更低版本时返回 up-to-date，不允许稳定通道降级。
• Release 必须同时包含 release-manifest.json 和当前安装类型要求的资产。manifest 以 basename(path) 建立索引，与 GitHub 的扁平 asset name 匹配；重复 basename、缺项或同名 metadata 不一致都使 Release 无效。缺失时不退回源码包或 wheel。
• metadata 固定从 https://api.github.com/repos/Fzkuji/OpenProgram/releases/latest 读取；manifest/DMG/runtime 固定从该响应中同仓库的 github.com/Fzkuji/OpenProgram/releases/download/vX.Y.Z/... 入口读取；版本化 CLI installer 固定从 raw.githubusercontent.com/Fzkuji/OpenProgram/vX.Y.Z/scripts/install-release.sh 读取。
• 所有请求只允许 HTTPS，最多跟随 5 次重定向，并逐跳校验 host。允许的 host 精确为 api.github.com、github.com、raw.githubusercontent.com 和 release-assets.githubusercontent.com；任意其他 host、协议降级或凭据型 URL 都拒绝。renderer 不接收或构造下载 URL。

5. macOS Desktop 更新

5.1 主进程职责

1. 启动后读取 userData/update-state.json；默认 automaticChecks=true。
2. 持久化 schema 1 包含 automaticChecks、lastAttemptAt、lastSuccessAt 和最近一次成功的、经过验证的 release metadata。使用同目录临时文件加 rename 写入；损坏文件、未知 schema 或无效字段回退默认值。
3. packaged app 启动 30 秒后计算检查计划。成功后下一次自动检查安排在 lastSuccessAt + 24h；失败后安排在 lastAttemptAt + 6h，避免密集重试。手动检查始终跳过成功缓存和失败退避。
4. 主进程只保留一个定时器和一个进行中的检查 Promise。每次完成、系统 sleep/resume 和 automaticChecks 设置变化后重新计算下一次时间；resume 不补发多个过期检查，最多立即启动一个，然后重新排程。开发模式不执行定时检查，但保留手动测试入口。
5. 使用 Electron 主进程网络 API 请求 GitHub latest，设置固定 User-Agent、超时和响应大小上限。
6. 按 process.arch 选择 OpenProgram-X.Y.Z-mac-arm64-unsigned.dmg 或 OpenProgram-X.Y.Z-mac-x64-unsigned.dmg，从 manifest 取得字节数和 SHA-256。
7. 用户点击下载后显示系统保存对话框；写入同目录临时文件，流式计算 SHA-256，校验字节数和 hash 后原子改名。
8. 校验成功后打开 DMG；失败时删除临时文件并显示可重试错误。不得打开未校验文件。

5.2 IPC 边界

updates.getState()                         // 只读当前状态
updates.check()                           // 手动检查；主进程强制刷新
updates.setAutomaticChecks(enabled)       // 保存布尔偏好
updates.download()                        // 只下载主进程已验证 metadata 对应的 DMG
updates.openRelease()                     // 打开固定 Release 页面
updates.onState(callback)                 // 状态推送

renderer 不能传入仓库、URL、文件名、hash 或目标命令。主进程持有全部远端和文件系统权限，并只接受布尔偏好和无参数动作。

6. macOS/Linux CLI 与 server 更新

• openprogram upgrade --check 只报告当前/最新版本和是否可升级，不写文件、不重启。
• openprogram upgrade 默认需要用户显式执行，不在后台替换 server runtime。
• managed upgrade 启动版本化 installer 时显式固定 OPENPROGRAM_REPOSITORY=Fzkuji/OpenProgram 和已验证的目标版本，并从子进程环境删除 OPENPROGRAM_RUNTIME_ARCHIVE、OPENPROGRAM_RUNTIME_SHA256 以及其他会改变正式产物来源的测试覆盖变量。installer 的本地 archive 注入只保留给直接执行脚本的 CI，不由产品命令继承。
• 运行中的 worker 不直接从旧进程内覆盖文件。升级命令只在隔离 cold start 成功后切换 current，不自动停止或重启现有 worker；旧 worker 继续运行当前代码，命令明确提示用户显式执行 openprogram worker restart。因此事务成功边界是 current 原子切换，不宣称新 worker 已接管。
• Web 设置页第一阶段不请求远端版本，也不提供远程执行升级按钮；显示 host 当前版本、安装类型和 openprogram upgrade --check/openprogram upgrade 指令。

7. 设置页信息结构

入口固定在 Settings → General → Application。Desktop 和普通浏览器显示不同的可执行动作，但不按“desktop user/client user”重复分类。非 Desktop 页面通过 owner-auth 保护的只读 GET /api/system/version 取得 host 信息，响应 schema 为 {currentVersion, installType}；版本来自当前 Python distribution metadata，安装类型来自统一 detector。detector 先检查 immutable runtime，再区分源码 checkout，否则返回 unknown；该接口不访问 GitHub、不执行更新。

• 有更新时显示版本号、发布日期和 Release Notes 摘要；完整内容链接到该 Release。
• 下载进度显示已下载字节/总字节。保存完成前按钮不可重复触发。
• 普通 Web 页面没有 Desktop bridge 时，不显示 DMG 下载动作；加载 /api/system/version 后显示实际 host 版本、安装类型和 CLI 升级命令。请求失败时显示 unknown，不使用硬编码版本。
• 设置文字区分“Automatically check for updates”和“Download and open DMG”，不使用“Install and restart”。

8. 安全、隐私与失败处理

自动检查会向 GitHub 暴露普通 HTTPS 请求所含的 IP、User-Agent 与请求时间。不开启遥测，不上传 OpenProgram 配置、会话或设备标识。

9. 实现顺序与验收

1. 旧 updater 收敛：测试证明 worker 启动不再 apply 更新、immutable runtime 不进入 Git/PyPI 路径、update 兼容入口与 upgrade 使用同一正式语义。
2. 安装类型：测试证明 Desktop/CLI 的 immutable runtime 均为 managed_release，源码仓库为 source_checkout，不存在把正式产品显示为 pip_wheel 的路径。
3. Desktop 检查与 UI：纯函数测试覆盖版本解析、latest 验证、真实 workflow 嵌套 manifest path 的 basename 唯一匹配、架构资产选择和状态转换；IPC 测试证明 renderer 不能指定 URL；Web 测试覆盖所有状态和非 Desktop 回退。
4. Desktop 下载：自动化测试通过注入的 fetch/Response 覆盖正常下载、允许的 GitHub 资产重定向、拒绝第三方/HTTP 重定向、重定向上限、body stall、大小不符、hash 不符、取消保存和并发请求；没有把该测试描述为真实 HTTP server 验收。只有校验成功才调用打开 DMG。
5. 持久化与调度：自动化测试覆盖 24 小时成功缓存、失败后 6 小时内不重复、6 小时到期重试、损坏/未来/未知 schema、原子写入及写失败回滚；main 的 timer、manual IPC 重排和 resume wiring 由源码合同检查覆盖。应用连续运行与实际 sleep/resume 属于首个 updater release 的可见验收，不列为本地自动化已执行。
6. CLI/Linux：fake GitHub/installer 测试覆盖 --check、无更新、缺资产、安装失败保留旧 current、成功切换且不重启现有 worker、显式 restart 后使用新版本，以及注入 archive/checksum/repository 环境变量不能改变产品命令的正式更新来源。
7. 发布门禁：release workflow 校验每个 Desktop 资产都存在 manifest 条目，每个 runtime 都有独立 checksum；Release 创建后使用 workflow token 查询 GitHub latest endpoint，确认目标 tag、稳定状态和唯一 manifest 资产。
8. 可见验收：在 /Applications/OpenProgram.app 的 default profile/18100 实例中验证设置页、版本号、手动检查、下载进度和失败提示；不启动第二个可见 Desktop 实例。

10. 实现与验证记录

• 已实现：Desktop 主进程更新服务、最小 IPC、Settings Application 状态；managed CLI Release 检查/升级；旧后台与 PyPI product updater 删除；installer old→new 原子替换；release 后 GitHub latest endpoint gate。
• 已验证：版本/manifest/架构匹配、URL 和逐跳重定向约束、损坏/未来缓存、短写、metadata/download stall、checksum/size 失败清理、并发 Promise、dry-run 和 JSON 输出合同、已有 current 的真实替换。
• 待 release 验收：首个包含 updater 的正式版本发布后，在默认 /Applications/OpenProgram.app 与隔离 CLI state 中验证 v0.6.6 一次性过渡及后续版本发现。发布前不把本地候选描述为已交付客户端。