新增 external v1 游戏场景生成路由并迁移 AGC 美术包背景阶段 (#516)

- api-server 新增 POST /api/external/v1/editor/scenes/generations，复用 editor:image-generate scope、幂等键和站内场景生图队列 - editor_project.rs 抽取站内与外部共用的场景生图 payload 构造函数，站内 handler 改为调用共享函数 - 同步更新 external v1 OpenAPI 契约与 MCP 派生排除标记，登记 docs/README.md 索引 - AGC 客户端美术包背景阶段改走新场景路由，stylePreset 固定 custom + customStyle 保留现有风格文案 - external_generation_state 快照与 recovery_scan 账本白名单支持新场景路由 - direct_runtime 背景资源识别同时兼容新场景路由与旧通用路由，新增旧路由回放测试 - 更新 genarrative-external-editor-api skill 参考文档 - 新增主规范、里程碑规范与实施计划三份 SDD 文档 Reviewed-on: #516
2026-09-27 18:39:01 +08:00
parent 6ed1fd26ed
commit 155f0d316a
17 changed files with 708 additions and 67 deletions
@@ -1,5 +1,11 @@
 # 踩坑与排障记录

+## 2026-09-24 AGC 生成路由迁移必须核对账号队列契约
+
+- AGC 普通账号会把 external editor 路由映射到站内入口；只验证 API Key 路由不足以证明客户端链路可用。
+- 站内入口必须读取客户端持久化的 `Idempotency-Key`，场景配方重建须保留精确的 `generationInputs.source = ai-game-creator-client` 标记。否则可能按请求 ID 重复入队，且普通队列 consumer 不保存客户端轮询所需的可下载 `result`。
+- 场景其余执行字段和引用身份仍由服务端重建，不整体信任调用方 `generationInputs`。验证应覆盖来源标记经过组装、队列清理和结果序列化的完整纯逻辑链路，以及账号路由的幂等键校验。
+
 ## 同一祖先下的多个项目会各自弹一次 UAC

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