AGC 客户端版本号收敛为单一发号源

新增 OSS agc/global-version.json 发号模块与发号入口脚本\n构建侧优先采用发号 Job 下发的总号，未传入时本地兜底发号\n渠道高水位降级为回退断言，请求号低于渠道清单版本即失败关闭\n新增 Genarrative-Agc-Global-Version-Issue 发号 Job 与 job config\n调度管线与手动管线先发号再透传 AGC_RELEASE_VERSION\n补充单元测试、生产运维门禁、主规范与里程碑文档
2026-09-20 18:12:49 +08:00
parent 4864e92e30
commit 9e0cbc7041
14 changed files with 1021 additions and 9 deletions
@@ -0,0 +1,62 @@
+# AGC 总版本号与发号
+
+更新时间：`2026-09-20`
+
+## 背景
+
+AGC 客户端此前按「渠道各自比高水位自增」发号：`dev-win` 与 `dev-mac` 各自读自己的渠道清单，`prepareReleaseVersion()` 取本地版本与远端高水位的较大值再 `patch + 1`。两个渠道因此天然拿到不同的号，统一构建无法保证 Windows 与 macOS 是同一个版本，手工填号或并发发号还会出现重号与回退。
+
+本方案把客户端版本号收敛成单一发号源，渠道只写自己本次拿到的号。
+
+## 版本源
+
+- 唯一事实源是 OSS 对象 `agc/global-version.json`，字段：`version`、`updatedAt`、`channel`、`commit`、`buildId`。
+- 渠道清单（`agc/<channel>/latest.json`）仍写各自本次的版本号，但不再承担发号职责。
+- 仓库里由构建改写的 5 个版本文件（`apps/ai-game-creator-shell/package.json`、根 `package-lock.json`、`src-tauri/tauri.conf.json`、`src-tauri/Cargo.toml`、`src-tauri/Cargo.lock`）继续按现状由构建改写，**只作构建输入参考、不作为事实源**，不提交、不参与发号。
+
+## 发号规则
+
+- `next = 总号 + 1`；总号不存在时先一次性播种，见下节。
+- 顺序固定为「先写总号 → 再构建 → 再发渠道清单」；任何一步失败都不回滚，只烧号。
+- 统一构建：发一次号，通过 `AGC_RELEASE_VERSION` 同时传给 `dev-win`、`dev-mac`（以及后续渠道），各渠道共用同一个号。
+- 单渠道热修：发一次号，只传给该渠道；其他渠道清单保持原值。
+- 显式传入 `AGC_RELEASE_VERSION` 的构建不再自行发号，只做高水位断言。
+
+## 并发控制
+
+- 发号收口到专用 Jenkins Job `Genarrative-Agc-Global-Version-Issue`（`disableConcurrentBuilds()` + 写后回读校验）。集群未安装 `lockable-resources` 插件，因此以 Job 级串行 + 写后回读兜底：写完总号后立刻回读，若远端值与本次写下不一致即失败关闭（号已烧，不重试、不回滚），由人工确认后再发。
+- 各渠道构建只接收号，不自己加；本地手工兜底路径（未传 `AGC_RELEASE_VERSION`）同样走「读总号 → +1 → 写回 → 回读校验」。
+- 不允许裸读改写：任何路径都必须经过发号模块，写后回读不一致即失败关闭。
+
+## 一次性播种
+
+- 基线 `seed = max(仓库当前版本, agc/dev-win/latest.json, agc/dev-mac/latest.json, agc/latest.json 旧指针)`。
+- 播种只写基线本身，不递增、不烧号；首个发放号是基线 + 1。
+- 播种入口：`node apps/ai-game-creator-shell/scripts/issue-global-version.mjs --seed-only`，或发号 Job 勾选 `SEED_ONLY`。
+
+## 实现位置
+
+- 发号模块：`apps/ai-game-creator-shell/scripts/agc-global-version.mjs`（读总号 / 播种 / 发号 / 写后回读 / 渠道高水位断言 / dry-run 预览）。
+- 发号入口：`apps/ai-game-creator-shell/scripts/issue-global-version.mjs`（CI 与本地共用，输出固定为 `AGC_GLOBAL_VERSION=<version>`）。
+- 构建侧：`build-release.mjs` 的 `prepareReleaseVersion()` 优先采用传入总号，未传入时现场发号；`resolveRemoteHighWaterVersion()` 降级为断言来源，只用于「请求号低于本渠道清单版本即失败关闭」。
+- CI：`jenkins/Jenkinsfile.agc-global-version-issue` + `jenkins/agc-global-version-issue-job-config.xml`；调度管线 `jenkins/Jenkinsfile.scheduled-revision-trigger` 与手动管线先调发号 Job，再把号透传给 AGC Build。
+
+## 不改的东西
+
+- `appUpdate.ts` 与官方 updater 的比较逻辑、渠道清单端点。
+- `release-oss.mjs` 上传流程。
+- `agc/latest.json` 只由 `dev-win` 写入。
+- 主站下载检查的读取源，不接总号。
+
+## 边界约定
+
+- `dev-mac` 在 macOS 构建机本地发布时同样只接收号（发号 Job 或本地发号脚本），不允许手动填号。
+- `AGC_RELEASE_DRY_RUN` 只读总号并预览 +1，不写回、不烧号。
+
+## 验收标准
+
+1. 统一构建后，`dev-win` 与 `dev-mac` 清单版本相同且等于总号。
+2. 单渠道热修后，只有该渠道清单变化，总号 +1，其他渠道清单原值不动。
+3. 热修后再统一构建，总号继续 +1，其他渠道版本跳过中间号。
+4. 并发两次发号不出现重号。
+5. 传入低于本渠道当前版本的号时构建失败关闭。