Merge branch 'fix/agc-rust-staging-idempotency' into feat/agc-bundled-resources-m3

2026-09-28 12:19:31 +08:00
parent acf021de2a 55b881de49
commit ceca4a7669
20 changed files with 947 additions and 112 deletions
@@ -0,0 +1,43 @@
+# 【实施计划】External v1 游戏场景生成路由
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】ExternalV1游戏场景生成路由-2026-09-24.md` |
+| Status | ready |
+| Owner | Agent |
+
+## 修改边界
+
+- 允许修改：
+  - `server-rs/crates/api-server/src/editor_project.rs`（抽取场景组装/入队共享逻辑）
+  - `server-rs/crates/api-server/src/external_editor_api.rs`（新 handler）
+  - `server-rs/crates/api-server/src/modules/external_api.rs`（路由表与契约矩阵）
+  - `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）；站内入口补齐现有 AGC 账号模式的幂等与结果协议。
+
+## 实现顺序
+
+1. 后端：把 `generate_editor_scene` 的「payload → `EditorImageGenerationRequest`」段抽成 `pub(crate)` 共享函数（含 options 标准化、Prompt 组装、generationInputs 重建、assetLabel 规范化），站内 handler 改为调用它。
+2. 后端：`external_editor_api.rs` 新增 `generate_external_editor_scene`：`require_scope(SCOPE_EDITOR_IMAGE_GENERATE)` + `require_idempotency_key` + 共享函数 + `enqueue_editor_image_generation_for_owner` + `external_generation_accepted_response`。
+3. 后端：`modules/external_api.rs` 路由表与 `PROTECTED_ROUTES` 各加 `/api/external/v1/editor/scenes/generations`（POST）。
+4. 后端：补单测/契约测试（鉴权、参数 400、幂等重放、与站内同 Prompt）；同步 OpenAPI JSON 与契约测试。
+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 元数据说明。
+
+## 验证命令
+
+1. `cargo test -p api-server`（重点：external_editor_api、editor_project 场景相关）
+2. `cargo test -p shared-contracts`
+3. AGC：`cargo test` 于 `apps/ai-game-creator-shell/src-tauri`（定向：canvas_generation、direct_runtime、recovery_scan、manifest）
+4. `npm run check:encoding`、`git diff --check`、`npm run check:doc-index`
+5. smoke：`npm run dev:api-server` 后 `curl /healthz`，再用测试 Key POST 新路由验证受理与重放。
+
+## 风险与回滚点
+
+- 共享逻辑抽取改变站内路由行为：以「相同输入 Prompt 逐字一致」单测为门禁；回滚点为抽取提交本身。
+- 旧路由登记的身份记录在新常量下读不到：保留旧路由 + `spec` 的读取分支，仅新增写入走新路由；回滚点为常量迁移提交。
+- 幂等重放依赖现有外部生成重放链路（issue #495 问题一不涉及图片生成入口，实测正常）；若 smoke 暴露重放异常，停止合并并记录。
@@ -0,0 +1,46 @@
+# 【里程碑】External v1 游戏场景生成路由
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | 2026-09-24 |
+| Parent Spec | `docs/technical/【技术方案】ExternalV1游戏场景生成路由-2026-09-24.md` |
+
+## 背景与触发
+
+平台自 `72f268e08`（游戏场景需求 v1.0）起在通用图片生成入口拒绝 `kind = scene` / `assetKind = scene`，要求场景必须走结构化专用路由；但 external v1 没有场景路由，AGC 客户端陶泥儿美术包的背景阶段仍向 `/api/external/v1/editor/images/generations` 提交 `assetKind = scene`，被平台参数校验拒绝（HTTP 400），新项目美术包无法生成（实测产物 `gameagent-f91a64dd`）。同时发现背景阶段保留账本匹配器期望 `assetKind = "game-background"`，与实际请求线上的 `"scene"` 不一致，中断恢复匹配失效。
+
+## 目标
+
+1. external v1 新增 `POST /api/external/v1/editor/scenes/generations`，与站内场景路由共享同一场景 Prompt 组装与入队实现，鉴权、幂等、计费、持久化语义与现役外部生成入口一致。
+2. AGC 美术包背景阶段迁移到新路由，以结构化场景意图提交，`reuse-or-create` 与 `regenerate` 均恢复可用，出图风格与尺寸不变。
+3. 背景阶段的路由、manifest 身份登记、保留账本匹配与恢复扫描常量整圈对齐到新路由与实际线上值；历史登记保持可读。
+
+## 不在本里程碑内
+
+- 保持站内场景生成规则，补齐账号模式幂等与结果协议；不改通用图片入口的 scene 拒绝校验。
+- 不改 SpacetimeDB schema、队列类型、计费档位。
+- 不迁移历史背景登记数据。
+- 不处理 issue #495 的两个既有问题。
+
+## 依赖与前置条件
+
+- `shared-contracts`：`EditorSceneGenerateRequest` 已存在，直接复用。
+- `api-server`：站内 `generate_editor_scene` 的组装与入队逻辑抽取为共享实现。
+- AGC `src-tauri`：背景阶段请求构造、保留账本与身份常量迁移。
+
+## 验收标准
+
+- [x] 账号场景入口透传可选幂等键、入队前拒绝非法键；场景配方保留 AGC 来源标记且队列完成结果包含可下载资源（路由校验及组装到结果序列化的定向测试）。
+- [ ] 新路由契约测试通过：路由矩阵与鉴权、参数 400、同键重放返回原任务、同键不同请求 409。
+- [ ] 外部场景路由与站内路由对相同输入产出相同的后端 Prompt 与入队 payload（共享实现单测对照）。
+- [ ] `docs/openapi/genarrative-external-v1.openapi.json` 与实现一致，相关契约检查通过。
+- [ ] 客户端定向测试：背景阶段请求命中新路由且为结构化字段；保留账本匹配器与实际请求口径一致；`reuse-or-create` 与 `regenerate` 路径回归通过。
+- [ ] 本地真实栈 smoke：`npm run dev:api-server` + 测试 Key 下美术包背景阶段受理成功（Provider 出图按环境可用性记录为已验证或未验证）。
+
+## 证据要求
+
+- 自动化：`cargo test -p api-server`（契约与场景相关单测）、AGC `src-tauri` 定向测试、`npm run check:encoding`、`git diff --check`。
+- 运行时：本地 api-server 受理 smoke。
+- 边界：鉴权 401/403、幂等重放、参数失败关闭。
@@ -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 提权弹窗；用户点「否」后仍会被再问一次。