Merge branch 'master' into fix/agc-rust-staging-idempotency

2026-09-28 12:12:59 +08:00
parent 0b19df467e 8f59c034f5
commit 55b881de49
20 changed files with 947 additions and 112 deletions
@@ -1,5 +1,17 @@
 # 踩坑与排障记录

+## 美术包固定 PNG 路径与平台返回格式不一致
+
+- 平台生成成功仍可能返回 JPEG/WebP；直接按 `assets/art-spec.png` 等固定路径保存会在扩展名校验时失败，图片尚未落盘但已付费结果账本仍存在，不能据 manifest 为空认定没有生成结果。
+- 美术包专用入口在本地提交前有界解码并归一化为 PNG，原 PNG 字节不变；扩展名、MIME、内容摘要和恢复比较必须使用同一份最终字节。普通图片工具和独立切片的格式合同不随之放宽，转码也不能代替真实透明度校验。
+- 失败后保留原账本并按冻结意图恢复，不能删除账本后重新生成。详情见 [AGC 美术包合同](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#2026-08-23-direct-codex-美术包显式重生成与切片投影)。
+
+## 2026-09-24 AGC 生成路由迁移必须核对账号队列契约
+
+- AGC 普通账号会把 external editor 路由映射到站内入口；只验证 API Key 路由不足以证明客户端链路可用。
+- 站内入口必须读取客户端持久化的 `Idempotency-Key`，场景配方重建须保留精确的 `generationInputs.source = ai-game-creator-client` 标记。否则可能按请求 ID 重复入队，且普通队列 consumer 不保存客户端轮询所需的可下载 `result`。
+- 场景其余执行字段和引用身份仍由服务端重建，不整体信任调用方 `generationInputs`。验证应覆盖来源标记经过组装、队列清理和结果序列化的完整纯逻辑链路，以及账号路由的幂等键校验。
+
 ## 同一祖先下的多个项目会各自弹一次 UAC

 - **现象**：AGC 启动页一次挂载出现多个叠在一起的 UAC 提权弹窗；用户点「否」后仍会被再问一次。