Merge branch 'master' into opt/design-simplify

2026-09-27 18:06:09 +00:00
parent 81419a84bd 5c648ab9c7
commit 01ebc3a143
5 changed files with 236 additions and 44 deletions
@@ -1,5 +1,11 @@
 # 踩坑与排障记录

+## 美术包固定 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 路由不足以证明客户端链路可用。
@@ -1493,6 +1493,9 @@ game-project/

 ## 2026-08-23 Direct Codex 美术包显式重生成与切片投影

+- 标准美术包在客户端将规范图、背景图和主图集统一保存为 PNG：下载仍校验来源、声明类型与文件签名，随后按真实内容接受 PNG/JPEG/WebP，在已有 20 MiB、4096 像素单边和 64 MiB 解码内存限制内完整解码。有效 PNG 原样保留，JPEG/WebP 编码成 PNG，最终内容也不得超过 20 MiB；本地媒体类型固定为 `image/png`。转码不补造透明度，主图集与独立切片继续执行真实 alpha、可见像素、尺寸和唯一性合同；平台独立切片仍须为 PNG。此行为仅属于美术包，普通图片工具的指定扩展名合同不变。
+- 美术包的转码在项目提交锁和本地写入之前完成，文件摘要、已安装结果识别、替换恢复和 manifest 登记均使用最终 PNG。转码失败保留原生成账本与平台身份，同冻结意图重试重新读取已有结果，不提交新的付费生成；不改变请求快照、幂等身份、固定资源路径或旧 PNG 包的复用方式，无数据迁移。验收覆盖 JPEG/WebP 转码、PNG 字节不变、损坏/超限拒绝、真实透明度以及已有结果重复恢复零生成 POST；客户端真实 Provider 的整包验证单独记录。
+- 转码自动化验收由 `canvas_generation_tests` 的格式/边界用例和 `retained_runtime_generation_retries_a_completed_stage_without_posting_again` 本地 HTTP 夹具覆盖：PNG/JPEG/WebP 均先下载损坏内容，再从同一已完成账本恢复两次，核对最终 PNG、稳定本地 asset ID、Canvas 来源身份、账本保留/清理及零生成 POST；替换与补偿继续由现有图集事务和 Direct 重生成用例覆盖。真实 Provider 的客户端整包效果不由这些夹具替代。
 - `agc_tools.taonier_prepare_game_art` 的请求模式固定为 `reuse-or-create | regenerate`。缺省使用 `reuse-or-create`，完整且可信的本地包继续零付费复用；只有用户显式要求重做、替换或切换视觉风格时使用 `regenerate`，并绕过完整包短路，按规范图、背景图、透明图集顺序生成和原位替换。`regenerate` 的旧包前置门只要求规范图和背景图已经可下载、可解码、来源一致且存在可信 manifest 登记，使两项旧字节与登记可以完整 rollback；历史主图集、私有回执、公开清单或 canonical 切片可以缺失。客户端必须把八个严格路径的实际存在性和摘要，以及其中受管顶层 asset identity，逐项冻结为 `Present/Some` 或 `Missing/None`，不能把缺失状态伪造成空文件或虚假登记。规范图或背景图任一缺失或身份无效时才失败关闭并提示先用 `reuse-or-create` 修复基础素材。
 - 显式重生成不放宽 External Editor 幂等与未知态边界。固定阶段已有 `prepared / accepted` 账本时，本次生成 prompt 必须与账本冻结 prompt 一致才可恢复；不一致返回 `platform-generation-result-unknown` 并保留原 `Idempotency-Key / operationId` 对账，禁止把旧结果解释为新意图，也禁止另起付费 POST。
 - 整包重生成在首个付费阶段前建立客户端私有 v4 workflow，状态固定为 `resetting / in-progress / compensating / completed`，并同时绑定意图摘要和客户端稳定 `clientTurnId`。专用 `direct-codex-art` 跨进程执行锁覆盖整个付费重生成生命周期，但不持有通用项目写锁等待网络。规范图和背景图替换后立即持久化旧字节、旧 manifest entry 与本轮双 CAS 锚点；任一后续阶段失败时进入 `compensating`，可在进程重启后继续恢复旧文件及旧登记。已成功阶段的生成账本继续保留；`completed` 持久化经脱敏和数量 / 长度限制的完整工具结果，同一 `clientTurnId` 回包丢失时必须等值重放且零新 POST。新的显式用户回合先持久化目标回合所有的 `resetting` workflow，再清理上一轮三阶段账本并转回 `in-progress`，任一崩溃点都不得出现无 workflow 窗口。只有尚无任何阶段账本且无替换锚点的孤立 `in-progress` 空壳允许被新回合原子接管；其余身份冲突、未知版本以及缺少新恢复字段的旧 v2/v3 workflow 均失败关闭，不能用 serde 缺省值把旧状态升级成可执行状态。