校准资源替换的 PRD、验收文档、技术方案与项目记忆

- PRD §5.3 补实现口径：替换落盘 = 改绑定 + 追加新版本、子版本绑定 = 源绑定去掉源素材并保证替换素材在集合里、前后身份用推导记录、三项兼容性逐条判据与 sizeSpecEqual 的降级声明、失败即拒绝、入口与可见效果；同时标注 :364-373 的 ProjectResourceDescriptor 是历史四分类形状（其 width/height/durationMs 在 manifest 里并不存在）
- PRD §5.4 前的版本章节与 §6 P1、§7.4 第 4 条按当前状态校准：替换已实施，但版本聚焦态仍不提供创建/替换/切换/回滚按钮，资源替换入口在资源卡工具条
- PRD 新增 §7.8 P1 资源替换验收六条（入口放行判据、候选禁用与原因、只追加写入形状、两条绑定路径、拒绝零副作用、成功后切版本但不重载预览）
- 【测试用例】AGC资源工作台V3端到端验收：删掉「PRD L387 兼容性三项属 C6 取消范围」那句（改为明确不属于），更新 §7.3 工具条 opt-in 清单，补三条已知边界（运行画面不因改绑定而变、候选弹窗不加载缩略图、picker 在 AGC 首次使用），§8 覆盖与不覆盖范围补资源替换
- 【技术方案】AI游戏创作智能体App实施计划：:669 的「本阶段不提供版本创建、替换、切换」与 :641 的布局切片范围按当前状态校准，并在文末新增「2026-09-11 AGC 资源工作台 V3：版本级资源替换」一节，写全命令、写入语义、前后身份推导口径、三项兼容性判据与降级声明、入口、成功后行为与验证数字
- decision-log 新增一条（背景 / 决策 / 恒等绑定硬约束 / 判据 / 降级 / 边界 / 影响范围 / 验证方式 / 关联文档）：说明本次按 PRD §3.2 / §5.3 恢复「替换后创建下一迭代版本」，与 2026-09-10 那条「不创建新版本、替换功能整条取消」的口径关系，以及 C6 的候选/队列/审核仍不做
- Issue #309 的三处口径（C1 决策、贯穿性决策 6、验收总纲的「不创建新版本 / 不产生新版本」）按远程写确认规则**未擅自改动**，需要在用户确认后再改

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

@@ -8364,3 +8364,16 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 不做什么：不新增替代导航、不做栏目下拉/分段控件、不改 `resourceBookModel` 的 `main / child + category` 目标模型、不改每「排序模式 + 栏目」独立 viewport 的既有约定、不动 sidecar schema 与跨端契约。
 - 验证方式：新增反向守卫用例（`资源栏目大纲` 标签、`.game-resource-outline` 类名、对应 `<nav>` 都不再渲染）与切栏目链路用例（总览卡片进空栏目 → 下一页切下一个 → 标题栏「资源总览」返回 → 「所有资源」入口往返）；变异验证：把 `<nav aria-label="资源栏目大纲">` 加回去 → 守卫红灯，只加回类名 → 守卫同样红灯（均已实测）。既有断言未放宽：栏目顺序断言改钉在总览缩略卡片的 `aria-label` 序列上（第 0 张「所有资源」+ 固定七栏目），只服务导航的断言按「四不写」直接删除。
 - 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（:56 / :512）、`docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md`（:5 / :33 / :53 / :54 / :57 / :102 / :103）、`docs/project-memory/shared-memory/pitfalls.md`。
+
+## 2026-09-11 AGC 资源替换按 PRD 恢复为「版本级替换」：改绑定落在追加的新版本上
+
+- 背景：PRD §3.2（`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md:36-41`）要求「替换版本引用资源时创建下一迭代版本，不原地修改既有版本」，并要求新版本记录 `parentVersionId`、替换前后资源身份与创建原因；§5.3（:356-387）给出 `ProjectVersionResourceReplacement` 与「三项兼容性必须同时为 true 才能创建下一版本」。本文件 2026-09-10 那条（`decision-log.md:8263`）与 Issue #309 的 C1 决策 / 贯穿性决策 6 / 验收总纲当时写的是相反口径：「改 manifest 绑定……**不创建新版本**」「替换功能（候选素材 / 替换关系 / 替换队列 / Agent 审核 / 单点替换）整条取消，不实现」。用户裁决：**按 PRD 来**，实际机制仍是「改 manifest 绑定」。
+- 决策：资源替换 = **改绑定 + 追加下一迭代版本**。新命令 `replace_local_project_version_resource`（写，`asset.register`）在持项目写锁与 `expectedProjectId + expectedProjectRevision` CAS 下，一次 `mutate_manifest_at` 写入里追加 `createdReason='resource-replacement'` 的子版本（`parentVersionId` 指向被替换的源版本），子版本绑定 = 源版本绑定**去掉源素材**并保证**替换素材在集合里**；只读命令 `read_local_project_version_replacement_candidates`（`asset.list`）返回候选与后端权威的三项兼容性。既有版本记录一个字节不改，**继续走默认空放行集合**，不新增/放宽 `mutate_manifest_at_allowing_version_removals`。
+- 恒等绑定口径的硬约束（实测得出）：每个版本的 `resourceBindings` 是「该版本使用的素材集合」而不是槽位表，替换素材若在源版本创建时就已登记，它本来就在集合里，因此**不能**把源素材那条槽位改写成替换素材（会撞「资源槽位重复」）；正确落盘是「源素材从集合里消失 + 替换素材在集合里」，替换素材是后来才登记时按源素材原位置插回。
+- 三项兼容性判据：`categoryEqual` 用 PRD §5.3 的**读时自愈**口径（为此在 `server-rs/crates/shared-contracts` 新增 `game_creation_app_asset_category_with_read_time_healing`，与 `packages/shared` 的 `gameCreationAppAssetCategory` 逐分支一致并配用例锁定——此前 Rust 反序列化只有「缺失/非法 → 按 kind 派生」，没有自愈，两侧口径并不一致）；`subtypeEqual` 比较 canonical `kind`；`sizeSpecEqual` 比较规范化媒体格式 + 已知帧宽高 + 已知时长，任一方有事实的维度必须相等。
+- 已知降级（刻意接受，不得当成完整实现）：manifest 资产表没有 `width / height / durationMs`，现役写入侧几乎全写 `imageSequenceFrames: None`，所以 `sizeSpecEqual` 在真实数据上退化为**媒体格式相等**（`png ↔ webp` 会被拒）。要支持跨图片格式替换，必须先给 manifest asset 增尺寸字段并在写入侧回填（跨端契约变更）。
+- 替换前后资源身份：按 PRD §5.4 的版本字段表口径**用推导记录**，不新增 manifest / 跨端契约字段（`父 − 子 = {源素材}`、`子 − 父 = {替换素材}`，配对由 `parentVersionId` + `createdReason` 确定）。已知限制：替换素材在源版本创建时就已登记时 `子 − 父` 为空集，版本记录无法单独反推配对；要无歧义持久化配对须先给 `GameIterationVersion` 增字段。
+- 边界：C6 的候选素材 / 替换关系图 / 替换队列 / Agent 审核 / 批量提交**仍然不做**（#309 该部分不变）；§3.2 末条「当前运行中的版本不消费尚未生成的新版本变更」保持——成功后只切记录层当前版本，不自动重载/重启预览，也不做运行时资源重映射。入口只在资源卡选中工具条、且只对「manifest 资产 + 被当前版本绑定」的素材渲染；候选弹窗复用美术画布的 `ImageCanvasProjectAssetPickerDialog`（AGC 首次使用），以可选 prop 扩展且默认值保持网页端行为逐字不变。
+- 影响范围：`server-rs/crates/shared-contracts/src/game_creation_app.rs`、`src-tauri/src/project/version_resource_replacement.rs`（新增）、`commands.rs`、`main.rs`、`tests/version_resource_replacement.rs`（新增）、`src/features/resource-canvas/resourceVersionReplacement{Model,Transport}.ts`（新增）、`view/project-development/index.tsx`、`src/components/image-editor/ImageCanvasProjectAssetPickerDialog.tsx`、`apps/ai-game-creator-shell/src/styles.css`。
+- 验证方式：Rust 定向 8 条 + `shared-contracts` 20 条；变异验证三条（去掉媒体格式维度 → 2 条转红；绕开读时自愈 → 自愈用例转红；改成原地改既有版本 → 4 条转红并被「项目版本记录写入后不可修改、删除或重排」拦下，证明只追加守卫真的在挡）。前端新增 12 条，变异验证两条（放宽入口判据 → 「不给假按钮」转红；失败路径静默关弹窗 → 「保留弹窗显示原因」转红）。AGC 全量 1231 passed / 4 skipped / 0 failed；共享美术画布组件 1385 passed；typecheck / `cargo check --locked --all-targets` / `check:encoding` / `git diff --check` 全绿。跨端契约、SpacetimeDB schema、manifest 结构与布局 sidecar schema 均未改动。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.2 保持，§5.3 补实现口径与降级声明，§7.8 新增替换验收）、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`（新增同章节）、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（§7.3 第 1 条已按本次口径改写）、Issue #309。