修复账号场景生成的幂等与结果返回协议

站内场景入口读取并透传可选幂等键，复用既有队列去重逻辑场景配方保留 AGC 来源标记，恢复可下载的队列完成结果补充非法幂等键、场景结果序列化和幂等命名空间回归测试同步 OpenAPI、技术方案、实施计划及排障记录
2026-09-24 16:18:40 +00:00
parent bb69e09b8d
commit 2370dc509b
8 changed files with 134 additions and 7 deletions
@@ -15,7 +15,7 @@
  - `docs/openapi/genarrative-external-v1.openapi.json` 与对应契约测试
  - AGC `src-tauri/src/agent/generation/canvas_generation.rs`、`src/agent/direct_runtime/mod.rs`、`src/agent/generation/external_generation_state.rs`、`src/agent/runtime_driver/recovery_scan.rs`、`src/project/manifest.rs`（背景阶段路由与身份口径）
  - `.codex/skills/genarrative-external-editor-api/references/`（外部 API 说明）
- 明确不修改：站内场景路由行为、通用图片入口校验、SpacetimeDB schema、计费、动画/抠图链路（issue #495）。
+- 明确不修改：站内场景生成规则、通用图片入口校验、SpacetimeDB schema、计费、动画/抠图链路（issue #495）；站内入口补齐现有 AGC 账号模式的幂等与结果协议。

 ## 实现顺序

@@ -26,6 +26,7 @@
 5. 客户端：`canvas_generation.rs` 请求构造为 Scene 拆专属分支——新路由 + `EditorSceneGenerateRequest` 形状 body（`sceneContent` = 现有场景 prompt 文本，`stylePreset = "custom"`，`customStyle` = 现有风格描述文案，其余字段沿用）；修 Scene 保留账本匹配器（新路由 + `sceneContent` 口径），统一 `game-background`/`scene` 不一致。
 6. 客户端：身份/对账常量迁移——`direct_runtime/mod.rs` 背景身份三元组路由与 kind、`manifest.rs` 期望路由、`recovery_scan.rs`、`external_generation_state.rs`；保持旧路由登记可读。
 7. 文档：外部 API Skill references 补新路由；运行编码与 diff 检查。
+8. 审查修复：站内场景 handler 读取并透传可选幂等键；共享组装只保留精确 AGC 来源标记。增加非法键路由测试与场景 payload 到队列可下载结果的回归测试，同步 OpenAPI 元数据说明。

 ## 验证命令

@@ -19,7 +19,7 @@

 ## 不在本里程碑内

- 不改站内场景路由行为与通用图片入口的 scene 拒绝校验。
+- 保持站内场景生成规则，补齐账号模式幂等与结果协议；不改通用图片入口的 scene 拒绝校验。
 - 不改 SpacetimeDB schema、队列类型、计费档位。
 - 不迁移历史背景登记数据。
 - 不处理 issue #495 的两个既有问题。
@@ -32,6 +32,7 @@

 ## 验收标准

+- [x] 账号场景入口透传可选幂等键、入队前拒绝非法键；场景配方保留 AGC 来源标记且队列完成结果包含可下载资源（路由校验及组装到结果序列化的定向测试）。
 - [ ] 新路由契约测试通过：路由矩阵与鉴权、参数 400、同键重放返回原任务、同键不同请求 409。
 - [ ] 外部场景路由与站内路由对相同输入产出相同的后端 Prompt 与入队 payload（共享实现单测对照）。
 - [ ] `docs/openapi/genarrative-external-v1.openapi.json` 与实现一致，相关契约检查通过。
@@ -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 提权弹窗；用户点「否」后仍会被再问一次。