Genarrative/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md

AGC 客户端更新检查与下载

交付范围

AGC 每次启动时由根窗口检查一次公开 OSS 更新清单。清单默认位于 https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/latest.json，构建时可用 VITE_AGC_UPDATE_MANIFEST_URL 覆盖为同一受信任 OSS 域名下的 HTTPS 地址。客户端版本取 apps/ai-game-creator-shell/package.json，通过 version 与清单版本比较；只有远端版本更高时显示更新提示。

清单格式：

{
  "version": "0.1.13",
  "downloadUrl": "https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/0.1.13/Genarrative-AI-Game-Creator.exe",
  "sha256": "<64位十六进制摘要>",
  "size": 123456789,
  "releaseNotes": "修复与改进"
}

downloadUrl 必须是 HTTPS；如提供 sha256 / size，Tauri 下载时会校验摘要和字节数。点击“下载更新”后，客户端将安装包流式写入系统临时目录并显示进度，校验成功后通过 Windows UAC 提权启动 NSIS 静默安装并退出旧客户端。

启动与失败策略

• 检查挂在 WindowChrome 根组件，覆盖首页、工作台和调试窗口；网络错误、格式错误或版本不高于当前版本均静默忽略，不阻塞客户端启动。
• 更新请求使用单例 Promise，React StrictMode 或同一窗口重复挂载不会重复请求。
• Tauri HTTP capability 与 CSP 仅放行默认 OSS 域名；若更换域名，需同步更新 capabilities/main.json、tauri.conf.json 和发布环境配置。

发布约定

当前发布目标固定为 Windows x64 NSIS。执行 npm run ai-game-creator-shell:build 会先读取 VITE_AGC_UPDATE_MANIFEST_URL（默认 https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/latest.json）的 latest.json，取本地与 OSS 的较高版本并递增一个 patch，然后同步更新 package、Tauri 和 Cargo 版本后再向 Tauri 传入 --target x86_64-pc-windows-msvc 构建。OSS 清单首次不存在时按本地版本递增； OSS 请求失败、清单格式错误或版本无效会终止发布，避免覆盖线上版本。构建完成后自动扫描 .exe 安装包，并在 apps/ai-game-creator-shell/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/latest.json 生成包含版本、下载地址、大小和 SHA-256 的清单。可通过 AGC_BUILD_TARGET 显式覆盖目标（发布仍应使用 Windows x64），通过 AGC_UPDATE_ARTIFACT 指定要发布的安装包，通过 AGC_UPDATE_OSS_BASE_URL 指定 OSS 前缀，通过 AGC_RELEASE_VERSION 指定三段版本号（仅在明确需要复现指定版本时使用），通过 AGC_UPDATE_RELEASE_NOTES 写入发布说明；--no-bundle smoke 构建不会读取 OSS、修改版本或生成清单。

每次发布安装包上传完成后，再上传同一目录生成的 latest.json，确保 downloadUrl 指向已存在的 OSS 对象；清单和安装包均使用公开可读对象，不在清单中保存凭据、签名或本地路径。构建脚本本身不负责上传 OSS，发布流水线通过 release:upload 完成上传。

如需一键构建并上传，可执行 npm run ai-game-creator-shell:release:upload。该命令要求本机已安装并配置 ossutil， 先按上述规则比较 OSS 版本、递增 patch、构建 Windows x64 NSIS，再上传安装包和 latest.json。默认上传到 agc-dev / oss-rg-china-mainland.aliyuncs.com，也可用 AGC_OSS_BUCKET、AGC_OSS_ENDPOINT 和 OSSUTIL_BIN 覆盖；本机执行时凭据由 ossutil 本机配置读取，不能写入仓库或命令行参数。

Jenkins Windows 构建节点

AGC 发布流水线使用 jenkins/Jenkinsfile.ai-game-creator-shell-build，当前节点标签为 windows && win2022。节点应为 Windows Server 2022 x64 虚拟机，预装 Node.js 22、npm 10.9.7、Rust 1.96.0、Visual Studio Build Tools（MSVC 与 Windows SDK）、Git 和 ossutil； Jenkins Agent 服务必须能在同一用户环境中找到这些命令。Tauri Windows bundler 使用 tauri.windows.conf.json 中的 bundle.useLocalToolsDir: true，把固定版本的 NSIS 工具缓存到 src-tauri/target/.tauri/NSIS，不依赖 Jenkins 服务账户的 %LOCALAPPDATA%\tauri 或 PATH 中的系统 NSIS。 Jenkins Checkout 的 git clean -fdx 会清理该构建目录，因此每次全新工作区可能重新下载 NSIS；这只影响构建耗时，不改变工具来源或执行权限要求。 流水线执行根 workspace 的 npm ci，然后调用 npm run ai-game-creator-shell:release:upload，并归档 Windows 安装包、latest.json 与源码 commit。 流水线会将未导出的空参数按空字符串处理：COMMIT_HASH 留空时沿用 Jenkins SCM 当前提交，OSSUTIL_BIN 留空时使用节点 PATH 中的 ossutil，不会因 PowerShell 对空环境变量调用 .Trim() 而提前失败。

Jenkins Job 在“Build and upload”阶段通过受保护凭据 ID AliyunAccessKeyId 和 AliyunaccessKeySecret 注入 AccessKey，仅在当前进程运行时传给 ossutil，不写入仓库、workspace 或构建日志； 本机运行仍使用 ossutil 配置。凭据必须具备 PutObject 权限；OSS 对客户端保持公共读即可，公共读本身不授予 Jenkins 上传权限。由于版本号取决于 OSS 当前清单，Job 已关闭并发构建；若 Jenkins 上存在多个 AGC 发布 Job，还应使用同一个 Lockable Resource 串行化发布。Job 参数 AGC_RELEASE_VERSION 留空时自动递增，填写后会使用指定版本并更新对应的 latest.json，因此回滚或测试旧版本前应确认不会覆盖线上更新入口。