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

新增 OSS agc/global-version.json 发号模块与发号入口脚本\n构建侧优先采用发号 Job 下发的总号，未传入时本地兜底发号\n渠道高水位降级为回退断言，请求号低于渠道清单版本即失败关闭\n新增 Genarrative-Agc-Global-Version-Issue 发号 Job 与 job config\n调度管线与手动管线先发号再透传 AGC_RELEASE_VERSION\n补充单元测试、生产运维门禁、主规范与里程碑文档

docs/README.md

@@ -44,6 +44,7 @@
 - [AGC Godot 编辑器插件接入](<./technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md>)：GDExtension 聚焦加载、安装资源、受管描述文件、UID 归属、GDScript 回执与 Runner 边界。
 - [AGC Cocos Creator 编辑器桥接模块](<./technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md>)：独立 crate、feature 开关、目标校验与 Windows 注入边界。
 - [AGC 客户端更新检查与下载](./technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md)：启动版本检测、固定 dev 服务、OSS 清单与官网最新客户端下载。
+- [AGC 总版本号与发号](./technical/【技术方案】AGC总版本号与发号-2026-09-20.md)：客户端版本号收口到 OSS `agc/global-version.json`，统一构建一次发号供各渠道共用，渠道高水位降级为断言。
 - [AGC 模板库与模板建项](./technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)：`templates/` 前缀的模板库契约、下载安装与「用模板建项目」链路。
 - [DirectProject 本轮附件路径映射](./technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md)：Direct 首轮只映射附件原名与项目相对路径，不灌正文、不区别 GDD。
 - [Direct 回合行为审计账本](./technical/【技术方案】Direct回合行为审计账本-2026-08-31.md)：Direct GUI 回合把 native 读 / MCP / 写文件落成项目内有界时间线，用于判断有没有打开本轮附件。

docs/project-memory/plans/【里程碑】AGC总版本号落地-2026-09-20.md

@@ -0,0 +1,37 @@
+# 里程碑：AGC 总版本号落地
+
+状态：进行中（主规范已定稿，代码与 CI 已实现，等待首次真实统一构建验收）
+
+## 关联文档
+
+- 主规范：`docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md`
+
+## 交付物
+
+1. 发号模块与入口：`agc-global-version.mjs`、`issue-global-version.mjs`、`agc-global-version.test.mjs`。
+2. 构建侧改动：`build-release.mjs` 的 `prepareReleaseVersion()` 采用总号，高水位降级为断言。
+3. CI：发号 Job（`Jenkinsfile.agc-global-version-issue` + job config）、调度管线与手动管线接入发号 Job。
+4. 文档与项目记忆更新。
+
+## 实现顺序与门禁
+
+| 步骤 | 内容 | 门禁 |
+| --- | --- | --- |
+| 1 | 发号模块 + 单元测试 | `node --test apps/ai-game-creator-shell/scripts/agc-global-version.test.mjs` 全绿 |
+| 2 | 构建侧接入总号与断言 | `build-release.test.mjs` / `release-oss.test.mjs` / `cargo-features.test.mjs` 全绿 |
+| 3 | 发号 Job 与管线接入 | `npm run check:production-ops`、`npm run check:encoding` 通过 |
+| 4 | 一次性播种 | 发号 Job 勾选 `SEED_ONLY` 写入基线，回读一致 |
+| 5 | 首次统一构建 | dev-win 与 dev-mac 清单版本相同且等于总号 |
+| 6 | 单渠道热修回归 | 只有该渠道清单变化，总号 +1 |
+
+## 当前证据
+
+- `agc-global-version.test.mjs`：7/7 通过（播种基线、首发、递增、dry-run 不烧号、回退断言、并发写后回读失败关闭、patch 递增）。
+- AGC 相关脚本合跑：32/32 通过。
+- 真实 OSS 只读预览：`--dry-run --channel unified` 输出 `AGC_GLOBAL_VERSION=0.1.77`（基线 0.1.76，未写回）。
+- `npm run check:production-ops`、`npm run check:encoding` 通过。
+
+## 未完成项
+
+- 首次真实播种与统一构建尚未执行（避免在功能未合并前烧号）。
+- `feat/jenkins-mac-build` 分支上的 macOS 管线仍用旧的自增高水位逻辑；该分支合并 master 后才继承本方案的模块与断言，合并前 dev-mac 必须由发号 Job 显式传入 `AGC_RELEASE_VERSION`。

docs/project-memory/shared-memory/decision-log.md

@@ -9006,3 +9006,10 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 新增护栏：`scripts/project-ci-workflow.test.ts` 增加一条一致性用例——Dockerfile 的 `ARG RUST_IMAGE` 版本段必须等于 `rust-toolchain.toml` 的 channel 主次版本、其 digest 必须同时出现在两份运维文档里、镜像 tag 日期戳必须与 Dockerfile 的 `org.opencontainers.image.version` 一致，避免本次这种「改了 Dockerfile 忘了文档」的漂移。
 - 待办（不在本次仓库改动内）：在 station 上执行 `build / verify / export / load-runner`，备份 runner config 后把 `genarrative-ci` 映射切到新 Image ID 并 `docker restart --timeout 660 gitea-runner`；内层只有 1.96 时 PR 的 job 必然失败。macOS 与 Windows AGC 构建机（`jenkins/Jenkinsfile.ai-game-creator-shell-build`，preflight 只校验 rustc/cargo 是否存在）需确认已装 `1.98.1`，macOS 冷构建是本次问题的原始验证目标。`deploy/container/api-server.Dockerfile` 的 `FROM rust:1.93-bookworm` 是另一处未加 digest 的 Rust 版本 pin，本次未动。
 - 验证：分支 `chore/rust-toolchain-1-98` / PR #432；`npx vitest run scripts/project-ci-workflow.test.ts`、`npm run check:encoding`、`git diff --check` 通过。Windows：`1.98.1` 下 `npm run agc:build -- --debug` 的前端构建、Rust 编译与 NSIS 安装包生成成功（见 PR 描述记录）；macOS 与镜像重建后的 CI 结果仍待验证。
+
+## 2026-09-20 AGC 客户端版本号收敛为单一发号源
+
+- 客户端版本号唯一事实源改为 OSS `agc/global-version.json`；渠道清单只写本次拿到的号，仓库里 5 个版本文件只作构建输入参考。
+- 发号顺序固定「先写总号 → 再构建 → 再发渠道清单」，失败不回滚只烧号；统一构建发一次号供 `dev-win` / `dev-mac` 共用，单渠道热修只作用于该渠道。
+- 发号收口到 Jenkins Job `Genarrative-Agc-Global-Version-Issue`（`disableConcurrentBuilds()`；集群无 `lockable-resources`，以写后回读不一致即失败关闭兜底并发）。
+- 原渠道高水位逻辑降级为断言：请求号低于本渠道清单版本即失败关闭；`AGC_RELEASE_DRY_RUN` 只预览不烧号。

docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md

@@ -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. 传入低于本渠道当前版本的号时构建失败关闭。