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

- 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 文档

docs/README.md

@@ -23,6 +23,7 @@
 - [外部 OpenAPI 与 API Key 接入方案](./【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)
 - [外部 MCP 语义工具说明与参数设计](./technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：15 个新增语义工具与全部原工具并存，复用现有 External API；包含工具说明、action、参数、幂等和兼容合同。
 - [External v1 OpenAPI](./openapi/genarrative-external-v1.openapi.json)：公开 HTTP 契约唯一机器可读来源。
+- [External v1 游戏场景生成路由](./technical/【技术方案】ExternalV1游戏场景生成路由-2026-09-24.md)：external v1 结构化场景生成专用路由与 AGC 美术包背景阶段迁移合同。
 
 ## AI 游戏创作与 Agent Runtime
 

docs/openapi/genarrative-external-v1.openapi.json

@@ -1052,7 +1052,60 @@
             "$ref": "#/components/responses/UpstreamError"
           }
         },
-        "description": "支持普通生图、规范图、角色图、快速编辑参考图、UI 设计图和宣发素材生成。kind 可取 spec、character、quick-edit、ui-design、publication-material。"
+        "description": "支持普通生图、规范图、角色图、快速编辑参考图、UI 设计图和宣发素材生成。kind 可取 spec、character、quick-edit、ui-design、publication-material。游戏场景不接受本接口的 kind/assetKind = scene，必须使用 /api/external/v1/editor/scenes/generations 提交结构化场景意图。"
+      }
+    },
+    "/api/external/v1/editor/scenes/generations": {
+      "post": {
+        "x-mcp-excluded": true,
+        "tags": ["Editor Images"],
+        "operationId": "generateExternalEditorScene",
+        "summary": "生成编辑器游戏场景（结构化场景意图）",
+        "description": "只接受结构化场景意图：sceneContent + stylePreset（custom 时必须提供 customStyle），完整 Provider Prompt 由服务端组装，不接受调用方提交的完整 prompt。入队后按 kind/assetKind = scene 持久化，产物保存 scene.generate V2 配方；队列、计费、资源入库与画布写回与站内场景路由一致。",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/IdempotencyKey"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorSceneGenerationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "生成任务已持久化入队",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
       }
     },
     "/api/external/v1/editor/images/edits": {
@@ -2965,6 +3018,68 @@
           }
         }
       },
+      "EditorSceneGenerationRequest": {
+        "type": "object",
+        "required": ["sceneContent", "stylePreset"],
+        "properties": {
+          "sceneContent": {
+            "type": "string",
+            "minLength": 1,
+            "description": "画面内容（结构化场景意图主体）。纯空白在入队前返回 400。"
+          },
+          "stylePreset": {
+            "type": "string",
+            "enum": ["anime", "watercolor", "flat", "stop-motion", "custom"],
+            "description": "视觉风格预设。custom 时必须同时提供非空 customStyle，否则返回 400。"
+          },
+          "customStyle": {
+            "type": ["string", "null"],
+            "description": "自定义画风描述，仅 stylePreset = custom 时使用。"
+          },
+          "model": {
+            "type": ["string", "null"],
+            "description": "图片模型，省略时使用服务端默认场景模型。"
+          },
+          "aspectRatio": {
+            "type": ["string", "null"],
+            "default": "16:9"
+          },
+          "imageSize": {
+            "type": ["string", "null"],
+            "default": "1K"
+          },
+          "referenceImageSrcs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "可选参考图，沿用普通图片生成的参考图口径。"
+          },
+          "projectId": {
+            "type": ["string", "null"]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "assetFolderId": {
+            "type": ["string", "null"]
+          },
+          "assetLabel": {
+            "type": ["string", "null"],
+            "description": "省略或纯空白时统一使用「游戏场景」。"
+          },
+          "canvasCompletion": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        }
+      },
       "EditorImageGenerationRequest": {
         "type": "object",
         "required": ["prompt"],

docs/project-memory/plans/【实施计划】ExternalV1游戏场景生成路由-2026-09-24.md

@@ -0,0 +1,42 @@
+# 【实施计划】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）。
+
+## 实现顺序
+
+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 检查。
+
+## 验证命令
+
+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 暴露重放异常，停止合并并记录。

docs/project-memory/plans/【里程碑】ExternalV1游戏场景生成路由-2026-09-24.md

@@ -0,0 +1,45 @@
+# 【里程碑】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`：背景阶段请求构造、保留账本与身份常量迁移。
+
+## 验收标准
+
+- [ ] 新路由契约测试通过：路由矩阵与鉴权、参数 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、幂等重放、参数失败关闭。

docs/technical/【技术方案】ExternalV1游戏场景生成路由-2026-09-24.md

@@ -0,0 +1,75 @@
+# 【技术方案】External v1 游戏场景生成路由
+
+更新时间：`2026-09-24`
+
+## 目标
+
+为 `/api/external/v1` 补齐游戏场景生成的结构化专用路由，使 AGC 客户端（陶泥儿美术包背景阶段）在平台收紧 `kind = scene` / `assetKind = scene` 边界校验后仍有合规的场景生成入口：
+
+```text
+AGC 美术包背景阶段（结构化场景意图）
+-> POST /api/external/v1/editor/scenes/generations
+-> 后端确定性组装场景 Prompt（与站内场景路由同一实现）
+-> 现有 editor_image_generation 队列与 Worker
+-> 现有计费、幂等、失败、资源持久化与 canvasCompletion
+```
+
+同时修复 AGC 客户端背景阶段保留账本匹配口径与实际请求不一致的既有隐患。
+
+## 非目标
+
+- 不改动站内 `/api/editor/scenes/generations` 的请求字段、Prompt 组装结果与计费语义。
+- 不放松通用 `/api/editor/images/generations` 与 `/api/external/v1/editor/images/generations` 对 `kind = scene` / `assetKind = scene` 的拒绝。
+- 不新增场景 Worker、任务表、计费档位或 SpacetimeDB schema。
+- 不改变美术包背景图的出图风格与尺寸（16:9 / 1K）。
+- 不处理 issue #495 的抠图重放 409 与动画 compact 字段问题（独立排期）。
+
+## 入口与边界
+
+- 系统入口：AGC 客户端 Direct 美术包流程的背景阶段（`reuse-or-create` 与 `regenerate` 均经过）。
+- 涉及模块：`api-server`（external v1 路由与场景 Prompt 组装）、`shared-contracts`（DTO 复用）、AGC `src-tauri`（请求构造、保留账本、身份对账与恢复扫描常量）。
+- 正式状态来源：`external_generation_job` 队列记录与项目 manifest 登记，与现役外部生成入口一致。
+
+## 必须成立的行为
+
+### 正常路径
+
+1. 新路由 `POST /api/external/v1/editor/scenes/generations` 接受与站内场景路由相同的 `EditorSceneGenerateRequest` 字段（`sceneContent`、`stylePreset`、`customStyle?`、`model?`、`aspectRatio?`、`imageSize?`、`referenceImageSrcs?`、`projectId?`、`generationInputs?`、`assetFolderId?`、`assetLabel?`、`canvasCompletion?`），不接受调用方组装后的完整 `prompt`。
+2. 场景 Prompt 由后端经与站内路由完全相同的组装实现生成；两路由只共享这一份组装逻辑。
+3. 鉴权复用现有 `editor:image-generate` scope；与现役外部生成入口一样强制 `Idempotency-Key` 请求头。
+4. 受理响应与现役外部生成入口同形（operationId 异步受理信封），轮询继续走 `/api/external/v1/generations/{operation_id}`。
+5. 入队后 `kind = scene`、`assetKind = scene`，队列类型、Worker、计费与持久化与站内场景路由一致；队列标题与任务摘要口径不变。
+6. AGC 美术包背景阶段以 `stylePreset = custom` + `customStyle` 承载现有风格描述，`sceneContent` 承载 brief 衍生的画面内容，出图风格与比例不因迁移改变。
+
+### 失败、重试与幂等
+
+1. 缺少 `sceneContent`、非法 `stylePreset`、自定义风格缺少 `customStyle` 等参数错误返回 400，与站内路由同语义。
+2. 缺少或非法幂等键、越权 scope 的拒绝语义与现役外部生成入口一致。
+3. 同一幂等键 + 同一请求重放返回原任务，不新建任务、不重复扣费；同键不同请求返回 409。
+4. Provider 失败、取消与 lease 耗尽沿用现有扣退费语义。
+
+### 权限、归属与数据边界
+
+1. 资源归属、项目绑定与素材文件夹解析沿用现役外部生成入口的 owner 口径。
+2. 任务摘要只展示 `generationInputs.fields` 的「画面内容」，不把后端完整 Prompt 暴露到任务侧栏。
+3. 场景产物以 `assetKind = scene` 持久化并保存 `scene.generate` V2 配方，与站内产物口径一致。
+
+## 契约与迁移
+
+- API / DTO / OpenAPI：新增 external v1 场景路由，DTO 复用 `shared-contracts` 的 `EditorSceneGenerateRequest`；同一次变更同步 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试（路由矩阵、鉴权、参数 400、幂等重放）。
+- SpacetimeDB schema / migration / bindings：不变。
+- 兼容与迁移策略：AGC 客户端背景阶段的路由、manifest 身份登记、保留账本匹配与恢复扫描常量整圈迁移到新路由；历史已登记的背景身份（旧通用路由 + `kind = spec`）保持可读，不做数据迁移。
+
+## 验收标准与证据
+
+| 条款 | 验收方式 | 证据 |
+| ---- | -------- | ---- |
+| 新路由受理/参数校验/鉴权/幂等重放 | api-server 契约测试与单测 | 待补 |
+| 与站内路由同一 Prompt 组装结果 | 共享实现的单测对照 | 待补 |
+| OpenAPI 与实现一致 | 契约测试 + `check:openapi` 类门禁 | 待补 |
+| 美术包背景端到端（reuse-or-create / regenerate） | 客户端定向测试 + 本地真实栈 smoke | 待补 |
+| 中断恢复：保留账本匹配与身份对账 | 客户端定向测试 | 待补 |
+
+## 未决问题与决策
+
+- `stylePreset` 取舍：已决策——AGC 美术包背景固定 `custom` + `customStyle` 承载现有风格文案，不绑定预设风格（2026-09-24，与用户确认）。