AGC 发布版本标签改由工程内部版本派生，拆除 projectVersion 写链路

- shared contracts：resolveGameCreationAppProjectVersion 改为按 manifest.versions 条数派生，删除 isGameCreationAppProjectVersion，projectVersion 注释降级为遗留兼容位 - Rust shared-contracts：删除 resolve_game_creation_app_project_version / is_game_creation_app_project_version / GAME_CREATION_APP_FIRST_PROJECT_VERSION，project_version 注释改遗留位并重写往返测试 - AGC 发布面板：项目版本改为 useMemo 派生只读输入框，删除本地 state、失焦落盘与 onManifestUpdated 回调 - AGC 发布服务：删除 saveGameDistributionProjectVersion，提交版本号缺省改为按 versions 派生 - AGC 原生：发布成功回写与绑定回填不再写 project_version（置空），删除 update_game_distribution_project_version 命令 - AGC 命令注册与白名单：desktop.rs 注销命令、check-config.mjs 移除白名单条目 - AGC 前端装配：App.tsx 移除两处 onManifestUpdated 传递 - AGC 测试：publish/panel 两条测试改为覆盖派生口径，删除四条写回用例 - 注释对齐：game_publish_attempt.rs / project/manifest.rs / styles.css / shared-contracts 的 game_distribution.rs 把版本标签口径改为「由 versions[] 派生」，清掉 projectVersion 遗留位表述 - 文档：decision-log 追加本决策条目，两份 2026-10-02 计划加取代标注，新增 2026-10-03 里程碑与实施计划
2026-10-04 00:16:14 +08:00
parent 6edda2ae68
commit daae35a1a1
20 changed files with 308 additions and 405 deletions
@@ -0,0 +1,87 @@
+# 【实施计划】AGC 发布版本以工程内部版本为准
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC发布版本以工程内部版本为准-2026-10-03.md` |
+| Status | proposed |
+| Owner | Genarrative Agent |
+| 关联 | PR #565（`feat/game-works-management`）；取代 `【里程碑/实施计划】AGC已发布游戏版本更新-2026-10-02` 中「用户可编辑发行版本标签」的口径 |
+
+## 修改边界（不动的东西）
+
+- 不改 `server-rs/crates/{spacetime-module,module-game-distribution,api-server,spacetime-client}`：服务端 `versionNumber` 语义与 `publicationRevision` CAS 保持不变。
+- 不改 `apps/admin-web/**`、不改 `src-tauri/src/project/export.rs`（两者正被其它 worker 修改）。
+- 不删除本地字段 `projectVersion`（Rust DTO 带 `deny_unknown_fields`：`server-rs/crates/shared-contracts/src/game_creation_app.rs:1121`）。
+
+## 修改顺序
+
+1. 文档：主规范改写 → 本里程碑 → 本实现计划 → `decision-log` 条目 → 两份 2026-10-02 计划文档的取代标注。
+2. 契约：TS 解析器改为内部版本派生。
+3. Rust：拆掉两条 `project_version` 写链路 + 删除手改命令。
+4. 渲染层：面板改只读派生、删失焦写回与 `onManifestUpdated`。
+5. service：删保存函数、改默认值与注释。
+6. 测试改写 + 门禁全跑。
+
+## 逐条改动（文件 → 位置 → 改什么 → 验收）
+
+| # | 文件 | 位置 | 改什么 | 验收 |
+| --- | --- | --- | --- | --- |
+| 1 | `packages/shared/src/contracts/gameCreationApp.ts` | `:1001-1013` | `resolveGameCreationAppProjectVersion` 去掉 `binding` 形参，返回 `versions.length > 0 ? versions.length : GAME_CREATION_APP_FIRST_PROJECT_VERSION`；注释改为「唯一来源 = 工程内部版本」 | `npm run agc:typecheck`；面板/服务用例 |
+| 2 | 同上 | `:1034-1037` | `projectVersion?: number \| null` 保留，注释改「遗留位：旧清单兼容读，不再读写」 | 静态检查 |
+| 3 | `server-rs/crates/shared-contracts/src/game_creation_app.rs` | `:1107-1118`、`:1090-1096` | 删 `resolve_game_creation_app_project_version` 与 `GAME_CREATION_APP_FIRST_PROJECT_VERSION` / `is_game_creation_app_project_version`；对应单测改为「字段被忽略」 | `cargo test -p shared-contracts` |
+| 4 | 同上 | `:1146-1150` | `project_version` 字段保留，注释改「遗留：仅为旧清单可解析，不再读写」 | 同上 |
+| 5 | `apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs` | `:24-27` | 去掉解析器 import | `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml game_distribution_publish` |
+| 6 | 同上 | `:536-541`（`write_publication_binding`） | 删除 `manifest.project_version = Some(resolve(...))`，改为置 `None`；保留 `manifest.publication = Some(binding.clone())` | 同上 + `jq` 自检 |
+| 7 | 同上 | `:1531-1535`（发布成功回写） | 删除 `manifest.project_version = Some(version.version_number)`，改为置 `None`；保留 publication 回写 | 同上 |
+| 8 | 同上 | `:944-965` | 删除 `update_game_distribution_project_version` 命令 | 编译 + `rg` 零命中 |
+| 9 | `apps/ai-game-creator-shell/src-tauri/src/desktop.rs` | `:614` | 从 invoke handler 清单删除该命令 | 编译 |
+| 10 | `apps/ai-game-creator-shell/scripts/check-config.mjs` | `:138` | 从命令注册表删除 `'update_game_distribution_project_version'` | `npm run agc:typecheck` |
+| 11 | `apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts` | `:148-167` | 删除 `saveGameDistributionProjectVersion` | typecheck + 用例 |
+| 12 | 同上 | `:329-337`、`:362-363` | 注释改为「唯一来源 = 工程内部版本」；默认值 `args.versionNumber ?? resolveGameCreationAppProjectVersion(args.manifest)` | 同上 |
+| 13 | `apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx` | `:129-136`、`:283-288`、`:331-332`、`:397-403`、`:683-708`、`:731-734`、`:804` | 删 `parseProjectVersion`、`projectVersion`/`savedProjectVersion` state、`projectVersionSaveRequestRef`、`handleProjectVersionCommit` 与三处 setState；新增派生值 `useMemo(() => resolveGameCreationAppProjectVersion(manifest), [manifest.versions])`；提交改为 `versionNumber: projectVersion` | 面板用例 |
+| 14 | 同上 | `:947-1000` | 「项目版本」输入框改 `readOnly`（保留 `aria-label="项目版本"`），删 `onChange`/`onBlur`/`disabled`；提示语改为「来自 AGC 内部版本（版本 N）…」 | 面板用例 |
+| 15 | 同上 | `:242-243`、`:700` | 删除 `onManifestUpdated` prop 与唯一调用点 | typecheck |
+| 16 | `apps/ai-game-creator-shell/src/App.tsx` | `:1816`、`:1951` | 删除两处 `onManifestUpdated={setManifest}` | typecheck |
+| 17 | `apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx` | `:735-761`、`:778-823`、`:825-868` | 前两条改为「标签 = 内部版本数」；后两条（失焦写回 / 非法回退）整块删除；fixture `MANIFEST` 补非空 `versions` | vitest |
+| 18 | `apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts` | `:319-420` | 删 `saveGameDistributionProjectVersion` 用例块；默认值断言改为「无 `versions` → 1；N 条 → N」 | vitest |
+| 19 | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` | `:97`、`:99`、`:106` + 新增两条 | 见主规范新条款 | `npm run check:doc-index` |
+| 20 | `docs/project-memory/plans/【实施计划】AGC已发布游戏版本更新-2026-10-02.md` | `:11`、`:23` | 行内追加「被 2026-10-03 里程碑取代」标注 | 阅读 |
+| 21 | `docs/project-memory/plans/【里程碑】AGC已发布游戏版本更新-2026-10-02.md` | `:27-30` | 同上，逐条标注被取代/收窄 | 阅读 |
+| 22 | `docs/project-memory/shared-memory/decision-log.md` | 最新条目区 | 追加本决策条目 | `npm run check:doc-index` |
+
+## 验证命令
+
+```bash
+npx vitest run apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts \
+  apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx \
+  apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts
+npm run agc:typecheck
+cd server-rs && cargo test -p shared-contracts
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml game_distribution_publish
+npm run check:doc-index
+npm run check:encoding
+git diff --check
+# 静态断言：命令与字段来源都已拆干净
+rg -n "update_game_distribution_project_version" .            # 期望 0 命中
+rg -n "projectVersion" apps/ai-game-creator-shell/src packages/shared/src  # 期望仅剩遗留声明/注释
+```
+
+## 数据迁移
+
+- 无迁移脚本。读路径立即忽略 `projectVersion`；改动点 6/7 会在下一次「平台回读绑定 / 发布成功」时把它置空，`skip_serializing_if` 使该键随下次落盘消失。
+- 平台侧历史版本行不做任何改写（不可变留痕）。
+
+## 风险与回滚点
+
+- 回滚点：只动 AGC 客户端 + 本地契约 + 文档；回滚 = 还原提交，服务端数据无副作用。
+- 旧客户端降级：清单里 `projectVersion` 被置空后，旧版 AGC 会回落到绑定 `latestVersionNumber`（旧行为重现），仅影响本机，需写 release note。
+- 派生标签会因「截尾删除版本」而回退（删素材连带删版本），平台接受该回退，但会产生「同一标签先后指向不同包」——这属平台现行契约允许的形态（用户手动重复提交同版本同样会产生）。
+
+## 不做（本里程碑之外）
+
+1. 「线上最近提交 vN」加「（平台）」字样（纯文案）。
+2. 平台历史版本号对齐（**明确不做**：不可变历史行无改写入口，会破坏审核留痕）。
+3. 后台/作者侧的「同标签多实例」可辨识列（落在 `apps/admin-web/**`，正被其它 worker 修改）。
+4. 「截尾删除致标签回退」的产品兜底（引入单调计数器 = 新字段 = SpacetimeDB schema 变更，须单独评审）。
+5. `edit-<operationId>` 形状的资源编辑版本是否计入内部版本序数（当前计入，与资源卡口径一致）。
+6. 旧客户端降级提示写 release note。
@@ -8,7 +8,7 @@

 ## 修改边界

- `packages/shared/src/contracts/gameCreationApp.ts`：本地唯一 `projectVersion` 和 `publication` 绑定，不混入内部编辑迭代 `versions[]`。
+- `packages/shared/src/contracts/gameCreationApp.ts`：本地唯一 `projectVersion` 和 `publication` 绑定，不混入内部编辑迭代 `versions[]`。**（2026-10-03 取代：发布标签改为由工程内部 `versions[]` 派生、只读；`projectVersion` 降级为不再读写的遗留兼容位，见 `【里程碑】AGC发布版本以工程内部版本为准-2026-10-03.md`。）**
 - `packages/shared/src/contracts/gameDistribution.ts` 与 Rust shared-contracts：创建版本请求支持正整数 `versionNumber`，允许重复标签提交。
 - `apps/ai-game-creator-shell`：绑定回读、首次发布/更新 UI、项目版本输入、原 gameId 新提交、结果回写。
 - `api-server`、`spacetime-client`、`spacetime-module`：创建版本事务只校验正整数；同 gameId/同 versionNumber 生成新 versionId，publicationRevision 继续 CAS。
@@ -20,7 +20,7 @@
 2. 创建版本事务不再要求大于 max；未传时保留旧客户端自动递增，传入时校验正整数，并按同版本最新有效提交处理 pending 替代。
 3. AGC 发布绑定保存 gameId、最新 versionId、状态和 revision；按账号和 API origin 隔离绑定。
 4. AGC 打开项目回读已有作品；旧项目通过 localProjectId 恢复关联。
-5. 发布面板编辑 projectVersion，区分首次发布/更新，允许重复提交和回退，不再存在独立 targetVersion。
+5. 发布面板编辑 projectVersion，区分首次发布/更新，允许重复提交和回退，不再存在独立 targetVersion。**（2026-10-03 取代：面板不再编辑版本标签，标签由工程内部 `versions[]` 派生且只读；仍区分首次发布/更新。）**
 6. Rust 发布 facade 在更新模式跳过 create game，使用原 gameId 创建新 version；幂等账本把目标 projectVersion、资料和提交意图纳入发布意图。
 7. 验证重复提交同版本、回退版本、响应丢失、切换账号、publicationRevision 冲突和旧公开版本继续可玩。

@@ -0,0 +1,33 @@
+# 【里程碑】AGC 发布版本以工程内部版本为准
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | 2026-10-03 |
+| Parent Spec | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`（「身份、状态、审核与更新」章） |
+
+## 目标
+
+让 AGC 发布面板的「项目版本」只有一个权威来源：AGC 工程内部版本记录 `manifest.versions[]`（即资源总览「项目版本」栏目里的版本卡）。标签等于当前存活的内部版本条数（最新卡的「版本 N」），只读、不可手填、不被平台 `version_number` 回填或覆盖，与 `publicationRevision` 无关。
+
+## 边界
+
+- 不改服务端能力：`publicationRevision` 继续严格 CAS；平台 `versionNumber` 继续接受正整数、重复与回退（网页端与历史客户端依赖该兼容口径）。
+- 不新增或修改 SpacetimeDB 表、字段与 procedure；`game_distribution_version.version_number` 不动。
+- 不重写平台历史版本行；不改公开地址、审核状态机与发行网关。
+- 不做版本历史页、版本对比、一键回滚 UI。
+- 不删除本地清单字段 `projectVersion`（Rust DTO 带 `deny_unknown_fields`，删除会让存量清单解析失败），它降级为不再读写的兼容位。
+
+## 验收标准
+
+- [ ] 发布面板显示的「项目版本」等于当前 `manifest.versions` 的条数（`versions` 为空时为 1），与平台 `version_number`、`publicationRevision` 均无关。
+- [ ] 面板不提供任何修改该值的入口；提交时 `versionNumber` 逐字等于该派生值。
+- [ ] 打开已有线上作品（线上最近提交 v6、内部版本 4 条）时，面板显示 v4，且仍并列显示「线上最近提交 v6 · 审核中」。
+- [ ] AGC 任何路径都不再写入 `projectVersion`（含发布成功回写、绑定回读回填、面板失焦写回）。
+- [ ] 存量清单里已有的 `projectVersion` 值不影响展示与提交。
+- [ ] 内部版本被截尾删除（长度 4 → 3）后，面板显示 v3 且能正常提交，不需要任何本地冲突处理。
+
+## 依赖
+
+- 无外部依赖；与「AGC 已发布游戏版本更新（2026-10-02）」是**取代**关系（见该文档内的取代标注）。
@@ -23,9 +23,9 @@

 - [ ] 首次发布完成后项目清单保存 `gameId`、`versionId`、版本号、状态和 `publicationRevision`。
 - [ ] 重新打开同一项目显示“更新游戏”，不再显示“创建平台游戏”。
- [ ] 项目清单只有一个用户发行版本字段，发布面板编辑它，不存在独立 targetVersion。
+- [ ] 项目清单只有一个用户发行版本字段，发布面板编辑它，不存在独立 targetVersion。**（2026-10-03 取代：发布标签改由 AGC 工程内部 `versions[]` 派生且只读，面板不再编辑；见 `【里程碑】AGC发布版本以工程内部版本为准-2026-10-03.md`。）**
 - [ ] 同一 `gameId`、同一 `versionNumber` 可以重复提交，生成新的 `versionId`，不覆盖旧公开实例。
- [ ] 项目版本可以低于线上最新版本，服务端允许回退标签，但仍校验为正整数。
+- [ ] 项目版本可以低于线上最新版本，服务端允许回退标签，但仍校验为正整数。**（2026-10-03 收窄：平台侧继续成立；AGC 侧不再由用户手填回退，派生标签只在内部版本被截尾删除时变小。）**
 - [ ] 同版本旧 pending 提交被取消或被最新提交替代，审核队列不产生重复有效任务。
 - [ ] `publicationRevision` 仍用于并发 CAS，与用户版本号规则独立。
 - [ ] 更新使用同一 `gameId`，只增加一个新 `versionId`，公开地址保持不变。
@@ -1,5 +1,19 @@
 # 决策记录

+## 2026-10-03 AGC 发布版本标签改为由工程内部版本派生，取代「用户可编辑标签」口径
+
+- 背景：用户实机验收指出发布面板「项目版本」显示 v6，而 AGC 工程内部只有 4 条正式版本记录（资源总览「项目版本」栏目 4 张卡，顶栏「智能体修订」下拉同样只有这 4 条）。核实：面板值来自本地清单 `manifest.projectVersion` 这个可编辑标量，它被三条链路反复钉到**平台** `game_distribution_version.version_number` 上——发布成功回写（`apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs:1531-1535`）、打开面板回读绑定回填（`:536-541`）、用户手改（`:944-965`）；而 `manifest.versions` 从头到尾不参与该值。`publicationRevision` 只做 CAS，与任何版本号都无推导关系（`module-game-distribution/src/domain.rs:27-40` 的版本号解析只比 `max_existing` 与 `requested`）。
+- 决策：AGC 发布面板的「项目版本」改为**由 AGC 工程内部版本记录 `versions[]` 派生**（标签 = 当前存活内部版本条数，即最新版本卡的「版本 N」，空数组取 1），**只读**，且不得被平台 `version_number` 回填或覆盖、不得读取 `publicationRevision`。平台侧 `versionNumber` 语义不变（正整数、允许重复与回退；`None` 仍自动 `max+1` 以兼容网页端与历史客户端）。本地字段 `projectVersion` 降级为遗留兼容位：保留可解析、不再读写（Rust DTO 带 `deny_unknown_fields`，删字段会让存量清单解析失败）。
+- 取代（逐条）：
+  1. `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md:97,99`（原「项目清单保存唯一用户发行版本 `projectVersion`」「AGC 发布面板直接编辑项目清单的 `projectVersion`」）→ 已就地改写为「派生只读 + 遗留兼容位」。
+  2. 同文件原 `:105`（「允许用户修改项目版本标签、重复提交同版本和回退到旧版本标签」）→ 已就地改写为「用户不再编辑版本标签；回退与重复仍由平台侧接受」。
+  3. `docs/project-memory/plans/【实施计划】AGC已发布游戏版本更新-2026-10-02.md:11,23`（「本地唯一 `projectVersion`…不混入内部编辑迭代 `versions[]`」「发布面板编辑 `projectVersion`」）→ 行内追加取代标注。
+  4. `docs/project-memory/plans/【里程碑】AGC已发布游戏版本更新-2026-10-02.md:27-30` 的验收项「项目清单只有一个用户发行版本字段，发布面板编辑它」被取代；「项目版本可以低于线上最新版本」在平台侧继续成立，AGC 侧口径改为「派生标签可能因截尾删除而变小」。
+- 边界：不改 SpacetimeDB 表/字段/procedure，不改 `publicationRevision` CAS，不改公开地址与审核状态机，不重写平台历史版本行，不做版本历史/回滚 UI。AGC 工程内部版本 `versions` 只能追加或按显式放行删除一个后缀（删素材连带删版本），因此派生标签不保证单调；平台必须继续接受回退标签。
+- 影响范围：`packages/shared/src/contracts/gameCreationApp.ts`、`server-rs/crates/shared-contracts/src/game_creation_app.rs`、`apps/ai-game-creator-shell/src-tauri/src/{game_distribution_publish.rs,desktop.rs}`、`apps/ai-game-creator-shell/src/{services/gameDistributionPublish.ts,components/game-distribution/GameDistributionPublishPanel.tsx,App.tsx}`、`apps/ai-game-creator-shell/scripts/check-config.mjs`、`apps/ai-game-creator-shell/tests/**`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/project-memory/plans/`。
+- 验证方式：`npx vitest run …gameDistributionPublish*.test.*`、`npm run agc:typecheck`（含 `scripts/check-config.mjs`）、`cargo test -p shared-contracts`、`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml game_distribution_publish`、`npm run check:doc-index`、`npm run check:encoding`、`git diff --check`；真机：内部版本 4 条、线上最近提交 v6 的项目打开面板显示 v4 且只读，提交 `versionNumber: 4`。
+- 关联文档：[平台入口与玩法链路](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)、[里程碑](【里程碑】AGC发布版本以工程内部版本为准-2026-10-03.md)。
+
 ## 2026-10-03 AGC 栏目画布上传素材按入口栏目登记（Issue 359）

 - 背景：AGC 客户端在资源栏目子画布（「UI 交互 / 角色与对象 / 场景与环境 / 音频」）左下角工具栏点「上传」后，提示条给出「已上传 1 个素材」，但当前栏目计数不变（仍「0 项」）、素材出现在「待归类」，用户看到的是"上传成功了但它从这一页消失了"。原因是上传登记的 manifest `kind` 只由**内容证据**推导（`assets.rs::uploaded_asset_kind`：图片 / 视频 / 代码 → `unclassified`，音频 → `audio`，文档 / 字体 → `document`），kind 派生分类与栏目词汇（`ui-interaction` / `character` / `scene` / `audio`）不是同一套，而 `upload_local_asset` 原先不接受入口栏目。