合并最新 master 并解决画布共享冲突

同步 origin/master 的场景、音效、运行时与后端原子提交改动

保留共享画布包导出并补齐场景、生成配方和历史动作类型

融合清单刷新测试、幂等请求、生成合同校验与项目记忆文档

docs/README.md

@@ -22,7 +22,10 @@
 - [客户端素材创作无限画布阶段一合同](./technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md)
 - [图片画布编辑器 MVP 接入方案](./technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md)
 - [图片画布编辑器前端拆分计划](./technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md)
+- [图片画布游戏场景生成链路](./technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md)
 - [画板音乐生成入口设计](./【编辑器】画板音乐生成入口设计-2026-06-18.md)
+- [SFX 生成优化 V2.0 任务拆解](./project-memory/plans/【实施计划】SFX生成优化V2.0任务拆解-2026-08-06.md)
+- [SFX 生成优化 V2.0 T6 测试与发布门禁](./【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md)
 - [音频生成 Composer 恢复共享分流方案](./project-memory/plans/【前端重构】音频生成面板恢复共享分流方案-2026-08-06.md)
 - [BGM 提示词优化 T6 测试与发布门禁](./【实施记录】BGM生成提示词优化T6测试与发布门禁-2026-08-05.md)
 - [画布 Agent 对话面板](./【编辑器】画布Agent对话面板-2026-07-03.md)

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

@@ -365,13 +365,36 @@
             "ExternalApiKey": []
           }
         ],
+        "parameters": [
+          {
+            "name": "view",
+            "in": "query",
+            "required": false,
+            "description": "返回视图。full 返回完整项目、画布、图层与资源；summary 只返回项目选择所需元数据和封面稳定引用。MCP 的 list_editor_projects 工具固定使用 summary。",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "full",
+                "summary"
+              ],
+              "default": "full"
+            }
+          }
+        ],
         "responses": {
           "200": {
-            "description": "项目列表",
+            "description": "项目列表。view=full 返回完整项目列表；view=summary 返回紧凑项目摘要列表。",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ExternalEditorProjectListResponse"
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/ExternalEditorProjectListResponse"
+                    },
+                    {
+                      "$ref": "#/components/schemas/ExternalEditorProjectSummaryListResponse"
+                    }
+                  ]
                 }
               }
             }
@@ -2431,6 +2454,87 @@
           }
         }
       },
+      "ExternalEditorProjectSummaryListResponse": {
+        "type": "object",
+        "required": [
+          "projects"
+        ],
+        "properties": {
+          "projects": {
+            "type": "array",
+            "description": "用于展示、查找、同名确认和安全选择目标的紧凑项目摘要；不包含 canvas、viewport、layers 或 resources。",
+            "items": {
+              "$ref": "#/components/schemas/EditorProjectSummary"
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorProjectSummary": {
+        "type": "object",
+        "required": [
+          "projectId",
+          "title",
+          "updatedAt",
+          "cover"
+        ],
+        "properties": {
+          "projectId": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "cover": {
+            "description": "项目最新封面快照的稳定引用；项目没有封面时为 null。需要展示时使用 objectKey 调用 /assets/read-url 获取临时签名 URL。",
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorProjectSummaryCover"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorProjectSummaryCover": {
+        "type": "object",
+        "required": [
+          "resourceId",
+          "objectKey",
+          "width",
+          "height",
+          "updatedAt"
+        ],
+        "properties": {
+          "resourceId": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": "string",
+            "description": "封面对象的稳定引用，不是图片正文、Data URL 或临时签名 URL。"
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "additionalProperties": false
+      },
       "ExternalEditorProjectDeleteResponse": {
         "type": "object",
         "required": [
@@ -3195,7 +3299,7 @@
               "ui-design",
               "publication-material"
             ],
-            "description": "省略时生成普通图片；其它值选择对应的专用生成流程。"
+            "description": "省略时生成普通图片；其它值选择对应的专用生成流程。External v1 当前不开放结构化游戏场景生成，scene 不能通过该通用图片接口提交。"
           },
           "model": {
             "type": "string",
@@ -3236,10 +3340,18 @@
             ]
           },
           "assetKind": {
-            "type": [
-              "string",
-              "null"
-            ]
+            "anyOf": [
+              {
+                "type": "string",
+                "not": {
+                  "pattern": "^\\s*scene\\s*$"
+                }
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "生成产物分类。External v1 通用图片接口禁止使用 scene；结构化游戏场景必须使用主站场景专用契约。"
           },
           "generationInputs": {
             "$ref": "#/components/schemas/JsonValue"
@@ -3538,29 +3650,32 @@
       "EditorIconSpritesheetGenerationRequest": {
         "type": "object",
         "required": [
-          "referenceImageSrc",
+          "referenceId",
           "iconDescriptions"
         ],
         "properties": {
-          "referenceImageSrc": {
+          "referenceId": {
             "type": "string",
-            "description": "图标规范的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
+            "description": "当前账号中已登记为 icon-spec 的项目资源 ID 或素材 ID。只接受 ID，不接受 objectKey、图片 URL、Data URL 或 Blob URL。"
           },
           "referenceImageSrcs": {
             "type": "array",
             "items": {
               "type": "string",
-              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
+              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceId 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
             },
             "maxItems": 8
           },
           "iconDescriptions": {
             "type": "array",
-            "description": "图标生成需求文本数组，供 prompt 组装使用；数组长度不控制自动切片数量。画布前端把完整用户提示词作为唯一数组元素提交；其它调用方可继续提交 1 到 100 条非空文本。",
+            "description": "图标生成需求文本数组，供 prompt 组装使用；数组长度不控制自动切片数量。画布前端把完整用户提示词作为唯一数组元素提交；其它调用方可继续提交 1 到 100 条非空文本。服务端去空并以换行拼接后，单条最多 200 个 Unicode 字符，合计最多 2000 个 Unicode 字符且不超过 6144 个 UTF-8 字节；超限同步返回 400，不会入队或计费。",
             "minItems": 1,
             "maxItems": 100,
+            "x-genarrative-maxTotalCharacters": 2000,
+            "x-genarrative-maxTotalUtf8Bytes": 6144,
             "items": {
-              "type": "string"
+              "type": "string",
+              "maxLength": 200
             }
           },
           "screenColor": {
@@ -4449,25 +4564,41 @@
       "EditorSoundEffectGenerationRequest": {
         "type": "object",
         "required": [
-          "prompt",
-          "duration"
+          "prompt"
         ],
         "properties": {
           "prompt": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "maxLength": 2048,
+            "description": "用户原始语言音效描述。服务端按 ECMAScript String.trim() 语义删除首尾空白和行终止符（包括 U+FEFF，保留首尾 U+0085），再按 Unicode code point 校验 1-2048。"
           },
           "model": {
             "type": [
               "string",
               "null"
             ],
-            "default": "audio1.0"
+            "default": "eleven_text_to_sound_v2",
+            "description": "省略、null、空串、纯 Unicode White_Space 或首尾空白包围的 eleven_text_to_sound_v2 均 canonicalize 为 eleven_text_to_sound_v2；audio1.0 和其它非空值返回 400。"
           },
           "duration": {
-            "type": "integer",
-            "minimum": 2,
-            "maximum": 10
+            "anyOf": [
+              {
+                "type": "number",
+                "minimum": 0.5,
+                "maximum": 30
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "null 或省略表示自动时长；有限数值表示手动时长。服务端不按 UI 0.1 秒步进取整。"
+          },
+          "loop": {
+            "type": "boolean",
+            "default": false,
+            "description": "独立 Loop 参数；服务端不从 Prompt 推断、同步或校验。"
           },
           "projectId": {
             "type": [
@@ -4629,6 +4760,22 @@
               "background-music"
             ]
           },
+          "durationSeconds": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 600,
+            "description": "SFX V2 为 MP3 探测所得实际时长；不是请求时长。BGM 或历史结果可省略。"
+          },
+          "loop": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "SFX V2 返回冻结并发送给 provider 的 Loop；BGM 或历史结果可省略。"
+          },
           "project": {
             "anyOf": [
               {
@@ -4674,6 +4821,146 @@
           }
         }
       },
+      "ExternalEditorGenerationCompactResourceReference": {
+        "type": "object",
+        "required": [
+          "resourceId"
+        ],
+        "properties": {
+          "resourceId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "projectId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "objectKey": {
+            "type": "string",
+            "minLength": 1
+          },
+          "assetObjectId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sourceResourceId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true,
+        "description": "完成态 compact result 中的稳定画布资源引用；不是完整 resource 快照。"
+      },
+      "ExternalEditorGenerationCompactAssetReference": {
+        "type": "object",
+        "required": [
+          "assetId"
+        ],
+        "properties": {
+          "assetId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "folderId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "objectKey": {
+            "type": "string",
+            "minLength": 1
+          },
+          "assetObjectId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true,
+        "description": "完成态 compact result 中的稳定素材库引用；不是完整 asset 快照。"
+      },
+      "ExternalEditorSoundEffectCompactResult": {
+        "type": "object",
+        "required": [
+          "audioKind"
+        ],
+        "properties": {
+          "audioKind": {
+            "type": "string",
+            "const": "sound-effect"
+          },
+          "durationSeconds": {
+            "type": "number",
+            "exclusiveMinimum": 0,
+            "maximum": 600,
+            "description": "SFX V2 保存 MP3 后探测得到的实际时长；不是请求时长。历史完成结果可缺少此字段。"
+          },
+          "loop": {
+            "type": "boolean",
+            "description": "SFX V2 冻结并发送给 provider 的 Loop；历史完成结果可缺少此字段。"
+          },
+          "taskId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "objectKey": {
+            "type": "string",
+            "minLength": 1,
+            "description": "持久化音频对象的稳定引用；需要临时下载或预览 URL 时使用 assets/read-url。"
+          },
+          "assetObjectId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "resource": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/ExternalEditorGenerationCompactResourceReference"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "asset": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/ExternalEditorGenerationCompactAssetReference"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "additionalProperties": true,
+        "description": "External SFX 完成态的 compact result。仅包含稳定产物引用和可安全消费的 SFX 元数据；不包含完整 project/canvas/asset 快照或脱敏的 Prompt、模型与 provider 字段。"
+      },
+      "ExternalEditorGenerationGenericCompactResult": {
+        "type": "object",
+        "not": {
+          "type": "object",
+          "required": [
+            "audioKind"
+          ],
+          "properties": {
+            "audioKind": {
+              "const": "sound-effect"
+            }
+          }
+        },
+        "additionalProperties": true,
+        "description": "其它生成类型或历史结果的兼容 compact result。背景音乐（audioKind=background-music）与不带 audioKind 的图片、视频、图标序列帧、角色动作和 UI 拆解结果都落在这里。该 fallback 明确排除 audioKind=sound-effect，避免吞掉 SFX 专用分支。"
+      },
+      "ExternalEditorGenerationCompletedResult": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/ExternalEditorSoundEffectCompactResult"
+          },
+          {
+            "$ref": "#/components/schemas/ExternalEditorGenerationGenericCompactResult"
+          }
+        ],
+        "description": "External v1 轮询 completed 状态的命名 compact result 联合。两个分支已由 audioKind 的 const 与 not 精确互斥，不使用 discriminator：背景音乐返回 audioKind=background-music，图片、视频、图标序列帧、角色动作、UI 拆解与历史结果根本没有 audioKind，它们都无法映射到具名分支，且 fallback 分支不可能把 audioKind 声明为必填，因此任何 discriminator 映射都不可能覆盖全部合法结果。"
+      },
       "ExternalEditorGenerationSubmissionResponse": {
         "type": "object",
         "required": [
@@ -4758,9 +5045,8 @@
             "type": "string"
           },
           "result": {
-            "type": "object",
-            "description": "completed 时返回的 compact 稳定结果引用；不包含完整 project/canvas、Data URL、Blob URL 或临时签名 URL。",
-            "additionalProperties": true
+            "$ref": "#/components/schemas/ExternalEditorGenerationCompletedResult",
+            "description": "仅在 completed 时返回的 compact 稳定结果引用；queued、running 和 failed 不返回该字段。为兼容历史完成结果，此字段不作为无版本迁移的必填约束。"
           },
           "pollAfterMs": {
             "type": "integer",

docs/project-memory/plans/【实施计划】SFX生成优化V2.0任务拆解-2026-08-06.md

@@ -0,0 +1,259 @@
+# SFX 生成优化 V2.0 任务拆解
+
+日期：`2026-08-06`
+
+状态：`T1–T6 工程实施已完成；生产配置确认、旧 Vidu 队列 drain、灰度和实际发布仍须按门禁人工执行`
+
+开发分支：`feat/sound_opt`
+
+合并基线：`origin/master@281c84b7bf2d`
+
+权威设计：[`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`](../../【编辑器】画板音乐生成入口设计-2026-06-18.md)
+
+决策入口：[`docs/project-memory/shared-memory/decision-log.md`](../shared-memory/decision-log.md)
+
+> 本文是通过 Git 共享的脱敏实施计划。代码、OpenAPI、测试和运行配置只实现权威设计中冻结的最终口径，不依赖任何未进入仓库的本地资料。
+
+## 文档可见性边界
+
+- `local-docs/` 只供当前机器本地使用，由本机 Git exclude 排除，不进入仓库；其他开发者通过 Git 无法看到、读取或核验其中任何文件。
+- 除本节用于声明隔离边界外，仓库中的 tracked 文档不得链接、引用、摘录或把 `local-docs/` 中的文件作为来源、证据或前置阅读材料；代码、OpenAPI、测试、配置和提交信息也不得依赖其内容。
+- 所有参与实现、审查、测试和发布所需的规则与证据，必须自包含地写入 tracked 权威设计、决策日志或本共享计划。团队成员不需要、也不应被要求访问本地资料才能开工或验收。
+
+## T0 退出条件
+
+T0 只冻结设计、决策、任务归属、迁移 / 回滚门禁和安全记录；不要求当前 Vidu V1 代码、OpenAPI 或实际 API 在 T0 与 SFX V2 设计一致。实现差距在 T1–T5 收敛，T6 验收。
+
+| T0 条件 | 状态 | 证据 / 剩余动作 |
+| --- | --- | --- |
+| 权威 SFX V2 设计已进入 tracked `docs/` | 已完成 | 画板音乐生成入口设计的 SFX V2 章节 |
+| T1–T6 计划、基线、测试和迁移门禁已通过 Git 共享 | 已完成 | 本文 |
+| External v1 `model` 完整矩阵已冻结 | 已完成 | 本文“请求与幂等口径” |
+| 英文化具有 LLM 语义判断和程序 Script 门禁 | 已完成 | 本文“Prompt 与 LLM 口径” |
+| 一键优化与翻译的 completion tokens 总预算和 `length` 行为已冻结 | 已完成 | 两类请求均为 `2048 × 4 = 8192`，预算包含 reasoning 与可见输出，见本文“Prompt 与 LLM 口径” |
+| 旧 Vidu 队列 drain、发布顺序和回滚门禁已冻结 | 已完成 | 本文“发布与回滚” |
+| 凭据安全边界已明确 | 已完成 | 秘密值只允许由服务端私密配置注入，不进入 Git、文档、日志或 fixture；凭据轮换不作为本次 T0 仓库门禁 |
+| T0 放行状态已确认 | 已完成 | `2026-08-06` 项目负责人明确确认 T0 通过，可以进入 T1 |
+
+T0 已通过，T1–T5 可以按本文依赖顺序进入实现；T0 通过不表示功能已上线。
+
+## 安全边界与 T0 放行记录
+
+该记录只保存日期、责任人 / 工单标识和布尔结论，禁止写入账号、密码、Key、Token、Cookie 或任何可恢复凭据的值。
+
+| 记录 | 日期 | 责任人 / 工单 | 结论 |
+| --- | --- | --- | --- |
+| 凭据安全边界 | `2026-08-06` | 项目负责人确认 | 不在仓库记录秘密值；凭据轮换不作为本次 T0 仓库门禁 |
+| 本地资料隔离 | `2026-08-06` | 本机 Git exclude | 已确认仅本机可见、未被 Git 跟踪且不作为团队证据源 |
+| T0 放行 | `2026-08-06` | 项目负责人确认 | 已通过，可以进入 T1 |
+
+## 目标和非目标
+
+### 目标
+
+- 在 `/editor/canvas` 现有 `audio-sound-effect` 分支把新 SFX 任务从 Vidu `audio1.0` 切换为 ElevenLabs `eleven_text_to_sound_v2`。
+- 复用共享音频 composer、现有生成队列、计费、OSS、资源、素材库和画布完成态。
+- 增加 52 个预设、一键优化、单层交换撤销、Worker 内统一英文化、自动 / 手动时长和 Loop。
+- 稳定保存 `prompt = userPrompt`、`actual_prompt = actualPrompt`、实际时长、Loop、模型、provider 和平台 Task ID。
+- 同批演进站内 DTO、External v1 OpenAPI、幂等语义、定价配置、部署配置和测试。
+
+### 非目标
+
+- 不修改 BGM Suno、BGM Prompt 助手、BGM 预设、提交锁或定价行为。
+- 不新建 SFX 独立页面、平行 composer 或第二套音频业务真相。
+- 不新建平行编辑器音频 DTO、正式生成 handler、BFF 或 `/api/editor/audios/*/generations` 路由；原地演进 `server-rs/crates/shared-contracts/src/assets.rs` 与 `server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs` 的现有正式链路。
+- 不开放 Prompt Influence UI；服务端固定 `0.3`。
+- 不为新 SFX 任务提供 Vidu fallback，不删除其它未迁移调用方仍使用的 Vidu 通用能力。
+- 不新增 SpacetimeDB 表或列，不向 External v1 暴露 Prompt 优化或翻译助手。
+- 不执行未授权的真实付费生成。
+
+## 当前 V1 差距与任务归属
+
+| 领域 | 基线状态 | 收敛任务 |
+| --- | --- | --- |
+| SFX Prompt | `trim()`、空值回退“游戏音效”、1500 上限 | T1 实现 Unicode canonicalization、2048 上限和无默认回退 |
+| SFX UI | textarea、Vidu 胶囊、2–10 整数时长 | T4 增加 52 预设、优化 / 撤销、自动 / 手动时长和 Loop |
+| SFX DTO | `prompt + model + duration: u8` | T1 / T5 演进固定模型、nullable 小数时长、Loop 和响应字段 |
+| Prompt 语义 | `prompt == actual_prompt` | T2 / T5 分离 userPrompt 和 actualPrompt |
+| provider | Vidu submit + poll + URL download | T3 增加 ElevenLabs 同步二进制 adapter，T5 接线 |
+| 实际时长 | 请求时长同时作为结果时长 | T3 探测 MP3，T5 写回实际值 |
+| Loop | 不存在 | T1 契约、T4 UI、T5 持久化与详情 |
+| External v1 | nullable model 默认旧 `audio1.0`，duration 为 2–10 integer | T1 类型基础，T5 同批修改 Rust / OpenAPI / 幂等与结果 |
+| 定价 | 旧模型键 5 泥点 | T5 增加新模型键并保持 5 泥点 / 次 |
+| 详情 | 通用 Prompt / Model / 时长 / Task | T5 增加中英 Prompt、Loop 和历史 Vidu 分支 |
+
+## 冻结产品与技术口径
+
+### Prompt 与 LLM 口径
+
+- `userPrompt` 和 `actualPrompt` 上限均为 2048 Unicode code points。
+- 只按 ECMAScript `String.trim()` 删除首尾空白和行终止符，包含 `U+FEFF`、保留首尾 `U+0085`；不做 NFC、内部空白折叠、换行转换、标点替换或静默截断。
+- 一键优化固定 `gpt-5.6-luna`、`reasoning_effort = medium`；Worker 翻译固定同模型、`reasoning_effort = low`。两类请求分别按各自 2048 Unicode code point 候选上限的 4 倍，固定 completion tokens 总预算 `8192`；该预算由隐藏 reasoning tokens 与可见 JSON 输出 tokens 共享，不包含输入 Prompt tokens，不是可见正文保证，也不按实际输入长度缩小。当前 VectorEngine OpenAI Chat wire 固定发送 `max_completion_tokens = 8192`；内部历史字段名 `max_output_tokens` 不是业务语义。两者均不发送 temperature 或 function tools。
+- 翻译 envelope 固定 `prompt / isEnglish / isFaithfulTranslation / isDirectGenerationFormat / hasAddedOrRemovedRequirement`，只接受完整 `response.text` 中的唯一 JSON object。
+- `isEnglish = true` 作为 LLM 语义判断，程序侧另外要求：候选至少含一个 Script=Latin 的 alphabetic code point，且所有 alphabetic code point 的 Script 均为 Latin；Common / Inherited 数字、标点、空白和符号允许。
+- 日文假名、韩文、西里尔、希腊、阿拉伯等非 Latin alphabetic Script 候选失败。测试必须覆盖中文、英文、中英混合输入，以及 actualPrompt 2048 / 2049 边界。
+- 首轮成功响应但候选不合格或 `finish_reason = length` 时，使用同一 userPrompt 唯一重试；首轮 `content_filter` 和 transport 最终失败不开启第二业务语义轮。
+
+### 请求与幂等口径
+
+- 自动时长默认开启，并预置最近手动值 `5s`；手动范围 `0.5-30s`、UI 步进 `0.1s`。自动模式发送 null 并保留最近手动值。
+- Loop 默认 false，是独立 API 参数；系统不根据 Prompt 推断、同步或校验 Loop。
+- provider body 固定 `text / model_id / duration_seconds / loop / prompt_influence=0.3`，query 固定 `output_format=mp3_44100_128`。
+- provider POST 不 retry，浏览器正式 POST 不 unsafe retry，队列 `max_attempts = 1`，一个平台 job 最多一次 ElevenLabs POST。
+
+External v1 `model` 先删除首尾 Unicode `White_Space`，再按大小写敏感矩阵 canonicalize：
+
+| 输入 | 结果 | canonical queue payload |
+| --- | --- | --- |
+| omitted / `null` / 空串 / 纯空白 | 接受 | `eleven_text_to_sound_v2` |
+| 首尾空白包围的新模型 | 接受 | `eleven_text_to_sound_v2` |
+| `eleven_text_to_sound_v2` | 接受 | `eleven_text_to_sound_v2` |
+| `audio1.0` | `400 BAD_REQUEST` | 不入队 |
+| 其它未知非空值 | `400 BAD_REQUEST` | 不入队 |
+
+所有接受形态在定价、预扣和 enqueue 前收敛为同一个 model 字段，不得产生不同幂等 payload。拒绝形态必须证明零入队、零预扣、零 LLM 和零 provider。
+
+### 结果、计费与数据
+
+- 服务端重建 SFX V2 `generation_inputs_json`，不信任客户端的 actualPrompt、实际时长、model 或 Loop。
+- 成功响应的 MP3 必须按现有 `MAX_GENERATED_AUDIO_BYTES = 40 MiB` 有界读取并验证，探测实际时长且只以独立技术异常上限 `600s` 拒绝过长结果；不把请求最大 `30s` 当作响应上限。平台 taskId 使用 operation / queue job ID，不伪造 provider task ID。
+- 新模型按次保持 5 泥点，以后端入队时冻结价格为真相。
+- 不修改 SpacetimeDB schema，复用 `prompt / actual_prompt / generation_inputs_json` 和画布 layout。
+
+## 任务包
+
+### T0：权威设计、共享计划、安全记录与迁移口径
+
+- 仅修改 tracked 文档，不实现功能代码。
+- 完成权威设计、本共享计划、决策日志、对 V1 差距的 T1–T5 归属、drain / 发布 / 回滚门禁。
+- T0 放行记录必须真实且脱敏，不得为凭据轮换、责任人或工单虚构证据。
+
+### T1：Prompt 规则、52 预设、共享契约与 metadata 基础
+
+- 实现前后端 ECMAScript `String.trim()` 等值 canonicalization、code point 计数、2048 边界和无默认 Prompt 回退。
+- 增加 40 + 12 预设纯模型，锁定数量、ID、分类和可见文案。
+- 原地演进现有 TypeScript / Rust 音频 DTO：fixed model、nullable 小数 duration、Loop、实际时长和 V2 metadata；不得新增同义 DTO 或平行正式生成契约。
+- 实现 External `model` canonicalizer 的纯函数与矩阵测试；实际 OpenAPI / handler 接线属于 T5。
+
+实施记录（`2026-08-06`）：T1 已完成。前后端共享 canonicalization fixture 已锁定 Unicode 边界与 `2048 / 2049` 行为；52 个预设、最小优化 DTO、固定模型、nullable duration、Loop 默认值、响应结果字段和强类型 V2 metadata 已落地。duration 纯校验接受自动 `null` 与手动 `0.5–30s`，拒绝非有限值和越界值。External `model` 当前只落地纯 canonicalizer 与输入矩阵测试，正式定价、预扣、enqueue、OpenAPI 和副作用测试仍严格归属 T5；在 T5 完成前不得发布当前中间态。
+
+补充验收（`2026-08-06`）：音频 compact 结果保留完整 DTO 必填的 `provider`，SFX / BGM 均通过真实 compact → Agent reconcile 回归；正式 SFX 提交流程不再执行原生 `trim()` 或默认 Prompt 回退。Rust V2 metadata 只能经校验构造并拒绝错误版本、模型、时长组合与实际时长；共享 fixture 直接锁定 `1 / 2048 / 2049`，52 个预设 ID 和非 `0.1s` 步进小数时长均有固定断言。
+
+规则修订（`2026-08-07`）：SFX Prompt 边界 canonicalization 改为 ECMAScript `String.trim()`；本条覆盖上段“不得执行原生 `trim()`”的旧口径。TypeScript 直接调用 `String.trim()`，Rust 以等值边界字符集合实现；首尾 `U+FEFF` 删除、首尾 `U+0085` 保留，BGM Prompt 与 External `model` 的 Unicode `White_Space` 规则不变。
+
+### T2：一键优化 BFF 和 Worker 翻译 service
+
+- 增加登录态 SFX Prompt 优化 BFF，固定 Luna + Medium + completion tokens 总预算 `8192`，32 KiB body limit，严格唯一 JSON envelope，不调用音频 provider 或正式计费。
+- 增加仅 Worker 可调用的 Luna + Low 翻译 service，每次业务尝试固定 completion tokens 总预算 `8192`，严格 `isEnglish` + Unicode Script 门禁、保真判断和最多一次业务重试。
+- 测试覆盖中文 / 英文 / 中英混合输入，日文 / 韩文 / 西里尔等非 Latin 字母候选，actualPrompt 2048 / 2049，请求体精确 token 上限，以及优化直接拒绝 `length`、翻译首轮 `length` 重试一次 / 第二轮 `length` 最终失败和 `content_filter / transport` 行为。
+
+实施记录（`2026-08-06`，`2026-08-07` 同步 master token 契约）：T2 已完成。登录态 `POST /api/editor/audios/sound-effects/prompts/optimizations` 已按 `32 KiB` body limit、Luna + Medium + OpenAI Chat + completion tokens 总预算 `8192` 接入，并注册 User-scope tracking；当前 VectorEngine Chat wire 只发送 `max_completion_tokens=8192`，不发送 `max_tokens` 或 `max_output_tokens`。优化候选只接受完整唯一五字段 JSON object，拒绝 tool call、未完成响应、非 Han、生成参数内容、代码块、解释、额外 / 重复字段和超限结果，错误响应不暴露候选或内部 envelope。现有音频生成模块内已增加不注册 HTTP 路由的 Worker 翻译 service，固定 Luna + Low + completion tokens 总预算 `8192`，使用同一 Chat wire 字段，严格执行保真 / 直接生成格式 / Latin Script 门禁，首轮内容不合格或 `length` 只以原始 `userPrompt` 重试一次，`content_filter` 和 transport 最终失败不进入第二业务语义轮；typed failure 只暴露 `translation_invalid / translation_upstream_failed` 安全分类。T2 只交付可供 T5 调用的内部 service，尚未改变当前 Vidu 正式生成、队列、计费、持久化、External v1 或 OpenAPI，不是可发布切点。
+
+### T3：ElevenLabs adapter、配置、二进制与时长探测
+
+- 在 `platform-audio` 增加独立 ElevenLabs settings、endpoint normalizer、request builder 和 direct binary client，不伪装 Vidu / Suno poll task。
+- 固定 model、influence、format、header 与 query；按 `40 MiB` 做 Content-Length 预检和 `limit + 1` 流式读取，执行 MIME / MP3 验证和纯 Rust duration probe，并以 `600s` 作为独立技术异常时长上限。
+- 配置增加 `ELEVENLABS_BASE_URL / ELEVENLABS_API_KEY / ELEVENLABS_REQUEST_TIMEOUT_MS`，Key 只在服务端。
+- 测试断言 429 / 5xx / timeout / 读取失败都只有一次 provider POST，不执行真实付费请求。
+
+实施记录（`2026-08-07`）：T3 已完成。`platform-audio` 已增加独立 ElevenLabs 直接二进制 adapter，固定 endpoint、header、query、model、influence、nullable 小数时长和 Loop；专用 HTTP client 禁止重定向且没有 retry。成功响应先做 `40 MiB` Content-Length 预检，再以 `limit + 1` 有界读取，严格执行 MIME / 真实 MP3 门禁，并以纯 Rust MP3 probe 取得有限正实际时长和独立 `600s` 上限；请求格式 `mp3_44100_128` 不扩展为返回码率硬校验。配置、环境模板和 fail-closed settings guard 已落地，持久化准备已把 provider / file stem 从轮询任务枚举中最小解耦；正式 handler、Worker、计费、OSS 写回、External v1 和 OpenAPI 均未接线，继续归属 T5。
+
+### T4：SFX 前端 controller、预设与参数 UI
+
+- 新增 SFX Prompt 纯模型、预设纯模型和 dialog-scoped controller；抽取音频预设跑马灯内核，BGM / SFX 保留各自 wrapper。
+- 在共享 composer 的 SFX 分支增加计数、52 预设、一键优化、单层交换撤销、自动 / 手动时长、Loop 和 ElevenLabs 胶囊。
+- 在第一个 await 前取得 AI / 提交 operation，只锁当前 SFX dialog；迟到响应和 scope 切换不写新面板。
+- T4 不切换 provider，不是可发布切点；与 T5 同一发布列车。
+
+实施记录（`2026-08-07`）：T4 已完成。前端增加独立于 BGM 的 dialog-scoped SFX Prompt 状态模型与 controller，优化和提交都在第一个 `await` 前同步取得 operation；账号、项目、dialog、mode 和 `AbortController` 共同隔离迟到响应。优化成功形成一层 canonical Prompt 交换快照，失败清除本次临时快照且不恢复更早快照，预设写入清快照。现有 BGM 跑马灯已抽出无业务语义的音频内核，BGM / SFX 各保留 wrapper；SFX wrapper 展示 T1 冻结的 `40 + 12` 预设。
+
+共享音频 composer 的 SFX 分支现已展示 `0 / 2048` 计数、一键优化、单层撤销、自动 / 手动时长、`0.5-30s` 且 `0.1s` 步进的 slider、Loop、固定 `ElevenLabs` 胶囊和新模型前端 `5` 泥点兜底。dialog layout 保存并恢复 `soundDurationMode / soundDurationSeconds / soundLoop`；历史 Vidu dialog 和改造入口统一打开 SFX V2 模型面板。同步提交 claim 冻结 canonical Prompt、时长模式、最近手动值和 Loop，只锁当前 dialog，并在 scope 失效后拒绝旧 UI 写回。
+
+T4 没有修改 Worker、provider 调用、正式请求的 nullable duration / Loop 映射、服务端动态定价、计费、OSS、持久化详情、External v1、OpenAPI 或 SpacetimeDB schema；这些继续严格归属 T5。T4 单独合入仍不是可发布切点，也未执行真实 LLM、ElevenLabs 或付费生成。
+
+### T5：正式提交、Worker、计费、持久化、详情和 External v1
+
+- 前端提交冻结 canonical Prompt、duration 和 Loop，正式 POST 不 unsafe retry。
+- 原地演进 `server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs` 的现有 handler，在定价 / 预扣 / enqueue 前 canonicalize External model，入队 payload 不含提前翻译的 actualPrompt；保留现有路由注册、queue / inline 分流和计费边界。
+- Worker 执行翻译、单次 ElevenLabs、MP3 时长探测、OSS 和权威 metadata / 画布写回；任一阶段失败进入现有退款链路。
+- 实现新模型定价键、历史 Vidu 只读 / 重绘兼容、中英 Prompt + Loop 详情和真实时长。
+- 同批更新 External v1 Rust DTO / handler / OpenAPI / Idempotency-Key 重放 / compact result；任一字段不一致时 T5 不完成。
+
+实施记录（`2026-08-07`）：T5 已完成。站内与 External SFX 请求在定价、预扣和 enqueue 前统一 canonicalize 为固定模型、canonical userPrompt、nullable 小数时长与 Loop；正式浏览器 POST 不再配置 unsafe retry，queue payload 不包含提前翻译的 actualPrompt。Worker 在既有冻结计费上下文内执行 Luna 英文化、单次 ElevenLabs POST、MP3 校验与实际时长探测、OSS、项目资源 / 账号素材 / 画布完成态写回，并使用 queue job ID 或 inline 预生成的平台 ID 作为 Task ID。服务端重建 `generation_inputs_json`，客户端自报的实际英文 Prompt、实际时长、模型与 Loop 不进入权威 metadata。
+
+新定价键 `eleven_text_to_sound_v2` 已加入默认 JSON、api-server 与 SpacetimeDB 值校验，旧 `audio1.0` 键继续保留；历史 SpacetimeDB 定价快照仅缺新键时由受控本地定价补齐读取，下一次后台保存写回完整矩阵，不修改 schema。详情展示中英 Prompt、实际时长、Loop、生成模型与完整平台 Task ID；SFX V2 重绘恢复 userPrompt、duration mode / requested duration 和 Loop，自动时长不会把实际输出时长误作下一次手动值。
+
+External v1 Rust handler、共享 DTO、OpenAPI、compact result 与 Agent Skill 已同步 nullable `0.5-30` 时长、Loop、固定模型和实际 `durationSeconds`；接受的 model 形态生成同一 canonical queue payload，旧 / 未知模型在 enqueue 前返回 `400`。External compact 继续隐藏 provider 与 Prompt，只保留稳定资源引用、实际时长和 Loop。T5 定向 Rust、TypeScript、External/OpenAPI、Agent、定价与 SpacetimeDB WASM build 已通过，未执行真实 LLM、ElevenLabs 或其它付费请求；完整失败矩阵、端到端与发布 smoke 继续归属 T6。
+
+### T6：测试、文档、灰度和发布门禁
+
+- 汇总 T1–T5 分层测试，增加 mock LLM + mock ElevenLabs + mock OSS 失败矩阵、端到端等值、刷新 / 重绘、计费退款、无重试、External 幂等和 BGM 回归。
+- 更新后端架构、前端专题、开发运维和共享项目记忆。
+- 执行定向 TypeScript / Rust / OpenAPI、`npm run typecheck`、`npm run check:encoding`、`git diff --check`、`npm run check:spacetime-schema`、`npm run dev:api-server` + `/healthz`。
+- 不将 mock 测试写成真实 provider 验收，不执行未授权付费生成。
+
+实施记录（`2026-08-07`）：T6 已完成工程侧测试缝、组合失败矩阵、跨入口补齐、稳定失败分类和发布 runbook。正式 SFX Worker 现由同一编排函数串联计费、翻译、ElevenLabs、OSS、asset object / bind 候选和原子资源 / 素材 / 画布 / job 提交；生产 adapter 继续调用原实现，测试 adapter 覆盖自动 / 手动时长 × Loop、余额不足零外部副作用、翻译 / provider / MP3 / OSS / asset candidate / 原子项目资源 / 账号素材 / 画布写回失败、一次退款和单 job 最多一次 provider POST。ElevenLabs HTTP / 无效音频 / 时长探测分别稳定归类为 `elevenlabs_http_failed / invalid_audio / duration_probe_failed`，OSS 与后续写回归类为 `oss_failed / writeback_failed`；普通用户继续只看到稳定短文案。
+
+T6 盘点发现并修复画布 Agent 遗留的 Vidu 参数边界：`generate-sound-effect` 现与站内和 External v1 共用 canonical Prompt、固定模型、`duration = null | 0.5-30` 和 `loop`，显式 `duration: null` 不再被通用 null-default 兼容层错误恢复为手动 `5s`。完整验证和生产门禁记录见 [`docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md`](../../【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md)。本阶段没有调用真实 LLM / ElevenLabs、没有执行付费生成、没有连接生产 SpacetimeDB，也没有执行发布；因此“工程 T6 完成”不等于“生产门禁已放行”。
+
+## 依赖和发布列车
+
+```text
+T0 -> T1
+T1 -> T2 + T3 + T4
+T2 + T3 + T4 -> T5
+T5 -> T6
+```
+
+- T2 / T3 可在 T1 契约稳定后并行；T4 可与两者后半程并行。
+- T4 与 T5 之间不存在可发布切点。
+- 不修改 SpacetimeDB schema；如实际实现发现必须修改，立即停止并按 schema 迁移规则重新评审，不得带入本计划默认实施。
+
+## 测试门禁
+
+| 层级 | 必要覆盖 |
+| --- | --- |
+| canonical | 空 / 全 ECMAScript trim 字符（含 U+FEFF）、首尾 U+0085 保留、U+200B、内部 U+FEFF、换行、组合字符、ZWJ emoji、2048 / 2049 |
+| 预设 | 40 + 12、ID / label 唯一、文案等值、逗号追加、重复、清快照、超限保文 |
+| 优化 | Luna + Medium + completion tokens 总预算 `8192`，Chat wire 只含 `max_completion_tokens=8192`，唯一 JSON、布尔门禁、length 直接失败、content_filter、无 tool call、无候选泄漏、dialog / scope 迟到响应 |
+| 翻译 | 每轮 Luna + Low + completion tokens 总预算 `8192`，Chat wire 只含 `max_completion_tokens=8192`，中文 / 英文 / 中英混合输入，日文 / 韩文 / 西里尔候选，isEnglish + Script 门禁，2048 / 2049，首轮 length 唯一重试、第二轮 length 最终失败且 provider 0 次 |
+| 跨入口 / External model | 登录态、External v1、画布 Agent 共用 canonical SFX queue payload；omitted / null / 空串 / 纯空白 / 包围空白新模型 / 显式新模型共用幂等 payload；`audio1.0` / 未知值为 400 + 零副作用 |
+| ElevenLabs | auto / manual × Loop false / true，固定 model / influence / format，Key 不泄漏，网络 / HTTP / body 失败均只有一次 POST |
+| 二进制与时长 | `40 MiB` 接受 / `40 MiB + 1 byte` 拒绝，Content-Length / chunked 超限、空 / HTML / JSON / 损坏 MP3、允许与 fallback MIME；有限正时长、30.5 / 60 / 600s 接受，>600s / NaN / 无穷拒绝 |
+| 持久化 | prompt / actual_prompt / model / provider / task / actual duration / Loop 权威等值，客户端伪造值失效 |
+| 计费 | 余额不足零 LLM / provider；翻译 / provider / MP3 / OSS / DB 失败一次退款 |
+| 回归 | BGM Suno、助手、预设、锁和定价不变；其它 Vidu 调用方仍可编译和测试 |
+
+## 发布与回滚
+
+### 发布前
+
+- 不打印值地确认生产 `ELEVENLABS_BASE_URL / ELEVENLABS_API_KEY / ELEVENLABS_REQUEST_TIMEOUT_MS` 均已配置。
+- 确认定价 override 包含 `eleven_text_to_sound_v2` 且价格已批准。
+- 只读查询 `external_generation_job` 中 `job_kind = 'editor_sound_effect_generation'` 且 `status IN ('pending', 'running')` 的旧 Vidu payload。非零时先 drain，不得让新 Worker 按 V2 nullable duration / Loop payload 解析旧任务；命令必须显式指定 `--server` / `--server-url`。
+- 先部署 api-server / worker，再部署 web；两者之间使用维护窗或暂时关闭 SFX 提交入口。
+- External v1 变更提前通知调用方并完成 contract smoke。
+
+### 观测
+
+- 区分 `translation_invalid / translation_upstream_failed / elevenlabs_http_failed / invalid_audio / duration_probe_failed / oss_failed / writeback_failed`。
+- 只记录 operation ID、阶段、HTTP status、耗时、响应字节数和实际时长；不记录 Key 或完整 provider 错误正文。
+- 对账 job 完成数、退款数、ElevenLabs 调用数和完成资源数，识别重复调用和孤儿资源。
+
+### 回滚
+
+- 回滚时不自动切回 Vidu；先停止新 SFX 入队。
+- 等待或人工收口 V2 queued / running job，避免旧 Worker 无法解析 V2 payload。
+- 协同回滚 web、api-server、worker 和 External v1 文档，禁止只回滚一层。
+- 新生成的 ElevenLabs 素材继续按通用 audio / model / generation inputs 只读展示，不做数据迁移回滚。
+- 没有 SpacetimeDB schema 变更，回滚不执行表迁移或字段删除。
+
+## 完成定义
+
+- T0 已通过，T1–T5 按依赖顺序实现并分别完成测试门禁。
+- T1–T5 完成各自分层测试，T6 完成全部发布门禁。
+- 新编辑器 SFX 不调用 Vidu，历史 Vidu 数据仍可读和按新模型重绘。
+- 翻译最终失败时 ElevenLabs 调用为 0；成功 job 最多一次 provider POST。
+- MP3 经过有界读取、验证和实际时长探测，权威 metadata 跨队列、OSS、素材、画布、响应和刷新一致。
+- External v1 Rust、OpenAPI、幂等 payload、副作用和最终响应逐字段一致。
+- 配置、日志、fixture、差异和提交不包含真实账号、Key、Token、Cookie 或其它凭据值。

docs/project-memory/shared-memory/decision-log.md

@@ -42,6 +42,13 @@
 - 影响范围：下一阶段的共享画布包、网站 adapter、`apps/ai-game-creator-shell` 前端与 Tauri Rust 本地持久化；不修改 SpacetimeDB schema，不把草稿或资源布局 sidecar 变成 manifest 业务真相。
 - 验证方式：按权威专题的 28 项矩阵覆盖 Web/Tauri 共用源码、新增/精修、生成响应丢失、重复提交、两窗口并发、事务各崩溃点、草稿恢复、切项目/切状态/改选择/改筛选迟到结果和不刷新即时投影。
 - 关联文档：`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+## 2026-08-07 game-chat 使用单主路径按需补齐美术
+
+- 背景：原 game-chat 把 Supervisor 的意图判断之后又硬接为 `design-director / code-director / art-* / code-prototype / preview-*` 固定图。`code-director` 代替程序主 Agent 判断素材缺口，会让“把现有美术资源应用到游戏中”被错误翻译成先生成美术，且美术回执无法天然回到同一个代码 Run 完成接入。
+- 决策：Supervisor 只通过 `agent.route_manifest` 持久化用户 intent，统一使用 `audit-existing-first`；整体视觉重做也只是一项 intent，不审计、不固定委派、不生成，也不授权整套美术强制重生成。持久路由后只启动同一根 Run 的 `code-prototype`；它必须先 `asset.list` 审计权威资源和 Canvas 登记，完整覆盖则直接接入且零生成。只有真实缺失 `art-spec` 或核心 spritesheet 时，主 Agent 才能一次委派相应 `art-director / art-asset-plan`；child 只写 `assets/**`，不得写 `game/**`，回执由同一主 Run 认领。主 Agent 随后完成接入、`game.static_smoke` 和 desktop/mobile `preview.validate`。升级时，确定性 `code-prototype` Run 只兼容已知的旧版/当前 canonical task 文本；任意其它正文仍按身份冲突拒绝。升级前已经运行的固定 Graph 美术 child 立即失效，所有项目 mutation 和确定性生图计划失败关闭，不能绕过新主 Agent 继续生成。
+- 影响范围：仅 `project-supervisor-game-chat` 的单主 route、动态美术 delivery、完成门、恢复和进度投影；普通 GUI / CLI 的 16 节点 manifest DAG 保持原样。
+- 验证方式：覆盖路由后只启动 `code-prototype`、既有素材零美术委派、精确缺口才允许单个对应 child、child 的 `game/**`、memory 和 manifest 写入拒绝而 `assets/**` 写入允许、回执恢复同一主 Run，以及主 Agent 的接入、静态 smoke 与双视口试玩；追加真实 scheduler 对旧 canonical task 的同 Run 恢复、旧固定美术 child 及其历史 isolated 后代对 Canvas/memory/manifest/project scope 零 mutation、伪只读 `agent.run_status` 阻断、嵌套美术 child 硬截止对账回执；另跑完整 DAG 非回归。
+- 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
 
 ## 2026-08-03 资源管理阶段七以完整 CI 与可重复界面合同收口
 
@@ -112,12 +119,12 @@
 
 ## 2026-08-06 game-chat 固定规则只提供上下文，Supervisor 决定条件 Graph
 
+> 状态：本条已由上方 `2026-08-07 game-chat 使用单主路径按需补齐美术` 决策完全替代，仅保留问题背景；不得把本条的旧节点、旧路由或旧美术替换规则作为当前 game-chat 指令。
+
 - 背景：用户要求把已有美术接入当前俄罗斯方块时，Runtime 在 Supervisor 首次 Provider turn 之前按关键词重置 Graph、选择是否复用美术并自动调度 child；Supervisor 没有固定快车道计划时又直接 `fixed-task-graph-stalled`。结果是模型没有理解和决策机会，`art-asset-plan` 在已有资产与 baseline 门互相冲突时重复空规划直至耗尽预算。
-- 决策：关键词、否定/重做信号、占位状态和当前资产探测统一降级为 `advisoryOnly=true` 上下文。game-chat 根 Run 在持久 `GameChatWorkflowDecision` 前禁止启动任何 manifest child，并允许 Supervisor 正常请求 Provider；Supervisor 通过 auto-safe `agent.route_manifest` 选择 `audit-existing-first` 或 `regenerate-art`。审计路线首波只启动 `design-director + code-director`；已登记但无效的旧派生视觉不得在这两项审计启动前截断 scheduler。code-director 必须先成功 `asset.list`，并在 Provider 请求中读取 Supervisor 已持久化且经校验的 `authoritative=true` 决策，再提交绑定当前 root/completion contract/revision 的覆盖合同与 `use-existing-art / generate-missing-art / regenerate-art` 路由。Runtime 只校验身份、正式资产、Canvas、私有合同、切片、manifest、缺口和 fingerprint，并执行条件分支，不从关键词替 Supervisor 作决定。
-- 资产边界：首版缺口槽位固定为 `art-spec` 与原子 `core-spritesheet`。art spec 缺失若使图集的引用/Canvas 合同同时失效，则两个槽位都是真实缺口；仅图集缺失时复用 art spec，只运行 `art-asset-plan`。完整覆盖零生成；显式重做只授权当前 root 下两个正式 owner 原位替换。已登记但校验失败的固定资产按真实缺口交回其 canonical owner，并只在持久路由绑定当前 root 时授权原位替换。art manifest baseline 豁免只读取持久路由，不重新运行关键词分类。
-- 连续性边界：正式 failed continuation 继续继承原完成合同；普通美术措辞不再按关键词跨历史根 Run 借用具体试玩类型，避免新项目误继承旧 `tetris-v1`。code-prototype 仍须先读取并最小 patch 非占位入口、可见使用四类切片，再经过静态检查和试玩门禁。
-- 恢复与权限：`agent.route_manifest` 在共享 Rust/TypeScript 命令目录中为 `auto`，否则 autonomous profile 会因不能等待人工确认而拒绝唯一决策动作；仅根 Supervisor 和其 code-director 审计 child 可执行，隔离 Agent 与其它角色拒绝。执行中断只允许按 durable pending identity 幂等恢复，同 Run 已持久决策/路由禁止改写。
-- 验证方式：覆盖决策前零 child、用户原句只产生 hint、旧无效派生视觉不阻断首波、首波只有设计/程序审计、code-director 收到真实持久策略、完整复用、仅缺图集、无效已登记资产由 owner 原位替换、重做两个 owner、baseline 豁免只认持久 route、code-director 的 asset.list/coverage/route 完成门、自动权限，以及旧 root/错误 binding/fingerprint/缺口/重复 route 失败关闭。
+- 当前替代：关键词、否定/重做信号、占位状态和当前资产探测只形成 `advisoryOnly=true` 上下文。game-chat 根 Run 在持久 Supervisor intent 前禁止启动任何 child；持久动作只记录用户 intent，统一走 `audit-existing-first`，不审计、不生成、不固定委派，也不授权整套美术强制重生成。随后只启动 `code-prototype`，由它成功 `asset.list` 后判断完整复用或精确缺口；完整覆盖零生成/零委派，缺口才允许一个受限美术 child，回执回到同一主 Run。普通 GUI / CLI 的 16 节点 DAG 不受影响。
+- 连续性与恢复边界：正式 failed continuation 继续继承原完成合同；普通美术措辞不再按关键词跨历史根 Run 借用具体试玩类型，避免新项目误继承旧 `tetris-v1`。`code-prototype` 负责读取并最小 patch 非占位入口、可见使用四类切片、静态检查和试玩；美术 child 只能写 `assets/**`，不得写 `game/**`。`agent.route_manifest` 的自动权限、pending identity 幂等恢复以及 root / binding / fingerprint / 缺口校验均按上方现行决策执行。
+- 验证方式：覆盖决策前零 child、用户原句只产生 hint、持久 intent 后只启动主 Agent、主 Agent `asset.list` 前零美术委派、完整复用零生成、精确缺口单 child、回执恢复同一主 Run、child 写入范围与当前 revision 的接入/静态 smoke/双视口试玩完成门，以及旧 root/错误 binding/fingerprint/缺口/重复 route 失败关闭。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`、`docs/project-memory/shared-memory/pitfalls.md`。
 
 ---
@@ -170,6 +177,7 @@
 - 影响范围：AI 游戏创作 `runtime_driver/task_start.rs`、`task_queue.rs`、自主构建 continuation 合同、Supervisor 进度卡与相应 Rust/AppSurface 回归；不改变 manifest DAG、Agent catalog、Provider 路由或项目产物合同。
 - 验证方式：不预占 child locks，真实一次调度三项首波任务，并在有界时间内证明每个逻辑 Run 至少写入 running/`turn.started`；重复调度不得新增逻辑 Run。前端固定时钟覆盖正常运行、子 Agent 新活动、疑似停滞、各类合法等待与 terminal 冻结。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/pitfalls.md`。
+
 ## 2026-07-31 图集切片按需编码并批量确认持久化
 
 - 背景：`2026-07-29 图集切片必须受前置容量和有界 CPU 保护` 收口了连通域数量与 CPU 并发，但切片仍在一次循环里全部裁剪并编码，最多 64 份 PNG 字节连同整张 RGBA 同时驻留内存；持久化又按切片逐个调用 procedure，N 片至少 2N 次写入外加一次 cohort 完成，任一片失败都会留下已确认的部分记录。手动拆分入口另有一处重复鉴权：`get_editor_project` 已经取回并定位了来源资源，随后仍走 `parse_editor_reference_image` 按注册 ID 再解析一次，触发全账号项目与素材库扫描。
@@ -182,6 +190,7 @@
 - 验证方式：`platform-image` 覆盖 prepare 不编码且 `Send + Sync`、并发编码多个 index 结果不变、累计裁剪像素在编码前拒绝；`api-server` 覆盖切片记录 ID 稳定且按 owner / index 分区、自动路径保留处理超时告警码、上传超时释放内存许可；`spacetime-module` 覆盖批次校验的完整 cohort、重复 objectKey、来源资源同 owner 同 project、部分 cohort 拒绝与重放只在内容一致时复用。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、本文件 `2026-07-29 图集切片必须受前置容量和有界 CPU 保护`。
 - 补记说明：本条为事后补写，记录提交 `cf1a02312` 已落地的行为，不改变其任何决策。
+
 ## 2026-07-31 AI 游戏创作资源依赖图采用 Rust 只读拓扑与前端派生 SVG
 
 > 状态：其中资源卡 Pointer Move 拖动预览与局部更新验收已由 2026-08-03 mentor 最新决定暂缓；只读拓扑、SVG 派生展示、搜索与选择高亮合同继续生效。
@@ -197,6 +206,17 @@
 
 ---
 
+## 2026-08-04 画布生成输入 V2 原地收紧并统一回落当前默认值
+
+- 背景：画布 `generationInputs.version=2` 从持久化 JSON 恢复时只校验通用结构，未知、非法、已下线或与当前模型能力不兼容的模型、比例、尺寸、清晰度、声音、时长及角色动作档位仍可通过 TypeScript 断言进入 UI 和再次提交。前端已隐藏但后端仍兼容的历史 Veo 也不再属于当前可选模型。
+- 决策：不新增 V3，不迁移数据库，不保留旧值再次执行；V2 在读取时原地按 `action` 解码。所有已存在但未知、非法、已下线或与当前模型不兼容的参数统一回落到该 action 的当前默认值，历史 Veo 同样回落到当前默认视频模型。图片比例 / 尺寸按回落后的模型联动校验，视频参数按当前模型能力校验，角色动作 `frameCount / durationSeconds` 按完整档位成对校验。发生回落时必须向用户显示“部分原生成参数已使用当前默认值”告警；再次提交只使用规范结果并保存为仍是 `version: 2` 的新快照。缺失字段继续由当前 action 默认值补齐，不为此单独升级版本。
+- 实现边界：单一 action 级 runtime decoder 是持久化 V2 的读取真相，恢复 UI、改造入口和再次提交链不得各自解释原始 JSON；canonical 选项从当前编辑器模型 / 参数注册表派生，不新增平行旧模型清单。通用结构不合法时整份配方不支持改造；必需 `source` 缺失时仍按 action capability 保留改造按钮，点击后在恢复路径拒绝改造，不用默认值伪造引用；运行期来源变化时同样必须复检并拒绝。该策略只改变画布配方的运行时恢复和后续重存，不修改 SpacetimeDB schema、BFF DTO 或已有资产原始 JSON。
+- 影响范围：`ImageCanvasGenerationModel` 的 V2 decoder、`ImageCanvasGenerationDialogModel` 的恢复入口、`useImageCanvasGenerationWorkflow` 的回落告警、生成输入回归测试和编辑器 Lovart 统一方案。
+- 验证方式：fixture 覆盖当前合法 V2、历史 Veo、未知模型、模型不兼容尺寸、非法视频参数、非法音效参数、角色动作错配档位和缺失必需来源；断言 UI、价格与提交使用规范值，回落显示告警，再次生成仍保存 V2。运行图片画布定向 Vitest、`npm run typecheck`、定向 ESLint、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`review.txt`。
+
+---
+
 ## 2026-07-30 抠图实际后端作为 generationInputs 顶层内部元数据保存
 
 - 背景：角色、图标图集和 UI 图集抠图派生资产需要保留最终实际执行的处理后端，供后台诊断 BgFilter、阿里云通用抠图和本地键色的降级结果；把抠图模型写成 `generationInputs.fields` 的“处理模型”会进入图片信息，与用户可见输入快照语义冲突，而覆盖正式资产 `model` 又会丢失源生图模型。
@@ -210,10 +230,10 @@
 ## 2026-07-31 修正抠图内部元数据的普通用户读取边界
 
 - 背景：2026-07-30 的记录误把素材 owner 与后台审计并列为原始抠图执行信息的读取方。owner 是普通用户，前端不展示字段不能阻止其从项目资源、素材库、精选提交 / 点赞回包、画布布局或任务完成响应的网络 payload 读取 BgFilter、阿里云、本地键色、具体分割模型或背景色。
-- 决策：本条取代 2026-07-30 决策中“素材 owner、精选提交响应仍可读取原始值”的表述。普通用户（包括素材 owner）和匿名公开读取必须共同过滤素材顶层 `provider`、内部处理 `model`，以及 `generationInputs` 顶层 `screenColorHex`、`mattingProvider`、`mattingModel`；正常用户可见生成 `model` 和其他合法功能性顶层字段（例如 `characterAnimation`）保持不变。User/Owner mapper 先完成该清理，public mapper 在其基础上叠加公开字段规则；后台管理与服务端审计继续使用 raw mapper 和持久化原值。历史数据不迁移，统一在读取边界清理。
+- 决策：本条取代 2026-07-30 决策中“素材 owner、精选提交响应仍可读取原始值”的表述。普通用户（包括素材 owner）读取时必须过滤素材顶层 `provider`、内部处理 `model`，以及 `generationInputs` 顶层 `screenColorHex`、`mattingProvider`、`mattingModel`；正常用户可见生成 `model` 和其他合法功能性顶层字段（例如 `characterAnimation`）保持不变。匿名公开素材 payload 不包含整个 `generationInputs`。User/Owner mapper 完成普通用户清理，public mapper 在其基础上移除该 owner-only 配方字段；后台管理与服务端审计继续使用 raw mapper 和持久化原值。历史数据不迁移，统一在读取边界清理。
 - 入站与持久化：客户端提交的 `generationInputs` 不得伪造上述内部键，服务端在实际处理完成后才写入可信值。手动去背景的正式素材 `model` 必须继承经服务端验证的正常源生图模型；若来源或祖先链不存在正常模型则为 `null`，不得写入 `BgFilter complex` 等内部处理模型。内部抠图 provider / model 可继续持久化供后台审计，普通用户完成响应和用户可见错误文本均不得暴露它们；手动去背景与角色动作透明化失败在 Owner HTTP / 任务状态边界统一替换为稳定业务文案，原始错误只留在任务记录、tracing 和后台审计。
 - 影响范围：项目资源、素材库、精选提交 / 点赞、图片 / 图标 / 视频 / 音频 / 角色动画生成完成、Agent 紧凑结果和识别出的画布资源 / 图层快照的 User/Public mapper；手动去背景持久化和完成响应；External Editor API 创建素材 / 资源时的保留键入站清理；相应响应 / OpenAPI 契约、前端搜索 / 详情 / ZIP 过滤测试与后台 raw 审计测试。同源画布 BFF 的角色、图标和 UI 请求继续由前端自动提交默认 `segModel=birefnet`，后端继续校验并在缺失时回落默认值；该请求控制字段不进入 `generationInputs`、普通用户响应、搜索、详情、导出或错误详情。角色动作的 `seg_model` 继续由后端固定。不修改 SpacetimeDB schema、迁移或 bindings。
-- 验证方式：Owner 和匿名响应覆盖无 `provider`、无内部 `model`、无三个内部 `generationInputs` 键，且正常 `model` 与 `characterAnimation` 仍保留；Admin raw payload 保持完整。覆盖历史 `BgFilter complex`、三类入站伪造键、手动去背景源模型回溯和用户错误文本过滤；运行 api-server 定向测试、前端定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding` 与 `git diff --check`。
+- 验证方式：Owner 响应覆盖无 `provider`、无内部 `model`、无三个内部 `generationInputs` 键，同时保留正常 `model` 与 `characterAnimation`；匿名公开素材响应完全不含 `generationInputs`；Admin raw payload 保持完整。覆盖历史 `BgFilter complex`、三类入站伪造键、手动去背景源模型回溯和用户错误文本过滤；运行 api-server 定向测试、前端定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding` 与 `git diff --check`。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
 ---
@@ -1214,7 +1234,7 @@
 ## 2026-06-21 图片画布参考图元数据只保存项目内行引用
 
 - 背景：参考图如果把 Data URL、signed URL 或 `objectKey` 写入 `generationInputs` 或生成器布局快照，会撑大资源 / 素材 / 画布 JSON，也无法稳定索引到项目内用户可见行数据。
-- 决策：`generationInputs.references` 只保存 `{ title, label, refType, refId }`，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`。生成器 `itemType="generation-dialog"` 布局快照中的参考图也只保存 `resourceId/sourceAssetId` 和展示 label，不保存图片 Data URL、signed URL 或 `objectKey`；提交生成请求前的内存态可以临时持有 `src/objectKey`，刷新恢复时从 `editor_project_resource` / `editor_asset` 行补回请求所需图片源。不兼容旧 `src` 型参考图元数据。
+- 决策：`generationInputs.references` 只保存稳定行指针，不保存媒体本身。2026-08-03 起 V2 新写入结构为 `{ id, title, label?, refType, refId }`；`refType="project-resource"` 和 `refType="asset"` 只用于匹配当前画布中已 hydrate 图层的 `resourceId/sourceAssetId`，媒体类型取匹配图层的运行时数据，不新增 owner-only 工程资源 / 素材库 resolver。生成器 `itemType="generation-dialog"` 布局快照中的参考图也只保存 `resourceId/sourceAssetId` 和展示 label，不保存图片 Data URL、signed URL 或 `objectKey`；提交生成请求前的内存态可以临时持有 `src/objectKey`。面板直接上传引用不是画布图层，不承诺刷新或复用恢复；已移出画布的引用同样不恢复。不兼容旧 `src` 型参考图元数据。
 - 影响范围：图片画布生成输入快照、生成器布局保存 / 恢复、参考图上传工作流、元数据弹窗和图片画布技术文档。
 - 验证方式：运行图片画布生成模型、生成提交、上传工作流、项目持久化、元数据弹窗相关前端测试，执行 `npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
@@ -1271,7 +1291,7 @@
 ## 2026-06-18 图片画布 Seedance 2.0 参考媒体提交边界
 
 - 背景：`/editor/canvas` 生成视频需要严格对齐火山 Seedance 2.0 多模态参考输入；参考视频若继续走 Base64 / `data:video` 会超过请求体并被上游拒绝，参考音频单独输入和非 Seedance 模型携带参考字段也会违反文档契约。
-- 决策：仅 `seedance2.0-fast` / `seedance2.0` 可提交参考图片、参考视频、参考音频；图片 0~9、视频 0~3、音频 0~3，音频必须搭配图片或视频。参考视频只能提交公网 URL、`asset://` 或画板资源 `objectKey`，禁止 `data:video/*`；视频 / 音频上传先走 OSS 直传和 asset*object confirm，前端保存 signed URL 预览但提交优先 `objectKey`，后端统一重新签名给 Ark。Ark body 按 `image_url` / `video_url` / `audio_url` + `reference*\*`role 构造，并显式发送`generate_audio:false`。
+- 决策：仅 `seedance2.0-fast` / `seedance2.0` 可提交参考图片、参考视频、参考音频；图片 `0~9`、视频 `0~3`、音频 `0~3`，音频必须搭配图片或视频。参考视频只能提交公网 URL、`asset://` 或画板资源 `objectKey`，禁止 `data:video/*`；视频 / 音频上传先走 OSS 直传和 asset*object confirm，前端保存 signed URL 预览但提交优先 `objectKey`，后端统一重新签名给 Ark。Ark body 按 `image_url` / `video_url` / `audio_url` + `reference*\*`role 构造，并显式发送`generate_audio:false`。
 - 影响范围：图片画布生成视频面板、参考媒体上传工作流、`editorReferenceUploadClient`、`ImageCanvasGenerationSubmissionModel`、`shared-contracts`、`api-server` 编辑器视频 BFF、Lovart 生成类面板文档。
 - 验证方式：运行 `npx vitest run src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/services/image-editor/editorReferenceUploadClient.test.ts --reporter verbose`、`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`、`cargo test -p shared-contracts editor_video_request_supports_seedance_multimodal_references --manifest-path server-rs/Cargo.toml`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、火山 Seedance 2.0 任务创建文档。
@@ -1480,7 +1500,8 @@
 - 2026-06-20 桌面能力清单单测边界：Tauri `capabilities.rs` 必须用 Rust 单测同时覆盖桌面 runtime capability 清单顺序、无重复、真实桌面能力完整包含，并显式排除 `auth.requestLogin`、`payment.request`、`file.captureImage`、`scanner.scanQrCode` 和 `haptics.impact` 等未接入能力；桌面单端配置检查会反查该测试边界，避免只靠方案文档或共享 profile 发现桌面壳能力伪声明。
 - 2026-06-20 桌面本地通知契约镜像：Tauri `notification.showLocal` 的 title / body 归一化、长度上限和成功结果 action 必须镜像共享 HostBridge 契约；Rust 侧常量使用 `HOST_BRIDGE_LOCAL_NOTIFICATION_TITLE_MAX_LENGTH`、`HOST_BRIDGE_LOCAL_NOTIFICATION_BODY_MAX_LENGTH` 和 `HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_ACTION` 命名，桌面单端配置检查会与 `packages/shared/src/contracts/hostBridge.ts` 比对数值并反查成功结果由该 action 常量组装，避免通知 payload 边界变成桌面壳本地规则。
 - 2026-06-19 桌面壳外链打开 helper 共用：Tauri WebView 外域拦截和 HostBridge `app.openExternalUrl` 都必须复用 `open_normalized_desktop_external_url` 执行系统外链打开动作；HostBridge 分支仍先用 `normalize_external_url` 保留 payload 错误语义并把 opener 错误回传给 H5，WebView 拦截保持 best-effort 静默处理。桌面壳配置检查会拒绝 `dispatch.rs` 直接调用 `app.opener().open_url` 绕过该 helper，避免两条离壳路径漂移。
-  > 2026-07-18 覆盖说明：本段后续关于微信 `navigation.openNativePage`、生成结果订阅页、`[subscribe-message]` 日志和订阅页路由门禁的 2026-06 决策均已由旧创作模板退役决策废止，只作为历史记录。Expo / Tauri 的同源 H5 受控导航及微信登录、支付、分享能力继续有效。
+
+> 2026-07-18 覆盖说明：本段后续关于微信 `navigation.openNativePage`、生成结果订阅页、`[subscribe-message]` 日志和订阅页路由门禁的 2026-06 决策均已由旧创作模板退役决策废止，只作为历史记录。Expo / Tauri 的同源 H5 受控导航及微信登录、支付、分享能力继续有效。
 - 2026-06-20 H5 原生导航预校验：`navigateHostNativePage()` 在 `native_app` 下发送 `navigation.openNativePage` 前必须先拒绝空值、控制字符、协议相对 URL、外域绝对 URL 和非 `http:` / `https:` 协议目标；同源绝对 URL、`/path` 和保留给桌面壳兼容的相对 route 继续交给 Expo / Tauri 壳二次归一并补写宿主上下文。微信小程序分支仍按小程序页面 URL 语义走 `wx.miniProgram.navigateTo`，不套原生 App 同源 H5 预校验。根级 `npm run check:native-shells` 会反查 H5 facade 仍使用 `normalizeNativeAppPageUrl(...)` 且发送归一后的 URL，避免明显不安全目标触达原生壳。
 - 2026-06-20 微信受控原生页能力声明：微信小程序壳真实 capability profile 声明 `navigation.openNativePage`，用于承接已经登记并测试的小程序原生页 flow；当前订阅生成结果通知页通过 H5 `requestGenerationResultSubscribePermission()` 调用 `navigateHostNativePage()` 打开 `/pages/subscribe-message/index`，小程序页再调用真实 `wx.requestSubscribeMessage` 并按既有结果协议回灌。根级 `npm run check:native-shells` 必须把该能力反查到共享 profile、微信 `WECHAT_HOST_CAPABILITIES` 镜像、订阅页协议常量、H5 入口、小程序 host-bridge / shell / page 文件和相关测试；该能力不代表开放任意小程序页面跳转。
 - 2026-06-18 能力声明收紧：`packages/shared/src/contracts/hostBridge.ts` 提供 HostBridge method / capability 白名单，H5 的 `getHostRuntime()` 会解析并过滤 `hostCapabilities`；`openHostShare`、`writeHostClipboardText`、`requestHostHapticsImpact`、`setHostAppTitle`、`exportHostTextFile` 等 native 能力只在宿主声明对应 capability 后调用。发布分享弹窗只有声明 `share.open` 时才显示受控分享动作，并按 `hostShell` 区分 Expo 系统分享面板和 Tauri 剪贴板复制表达，避免旧壳或裁剪壳露出不可用入口。
@@ -5869,7 +5890,7 @@
 ## 2026-07-28 AI 游戏创作正式视觉规范与透明 spritesheet DAG
 
 - 16-task 边界：继续复用现有 seed manifest 的 `art-director / design-foundation / art-asset-plan` 三个任务，不新增平行任务、会话或素材系统。`art-director` 是正式视觉规范前置：先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`。`generationInputs.artSpec` 只是辅助结构化上下文，不能替代这张真实规范图。
-- 路由与依赖：`design-foundation` 以已登记 `assets/art-spec.png` 的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，通过 `/api/external/v1/editor/images/generations` 的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 art-spec 资源 ID 作为必填 `referenceImageSrc`，调用 `/api/external/v1/editor/icon-spritesheets/generations`，提交具体 `iconDescriptions` 与 `screenColor=auto` 生成透明 `assets/art-spritesheet.png`。严禁把 `assets/ui-prototype.png` 当作规范图引用；`art-spec.png` 缺失、不是当前画布的 `icon-spec` 或缺少稳定 `resourceId` 时，两个下游任务都必须等待 `art-director`，不得把本地路径、Data URL / Blob URL 当成稳定引用，也不得退回普通生图。单波最多 `3` 个静态职责的资源上限保持不变，调度只调整现有任务的依赖边和就绪顺序。
+- 路由与依赖：`design-foundation` 以已登记 `assets/art-spec.png` 的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，通过 `/api/external/v1/editor/images/generations` 的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 art-spec 资源 ID 作为必填 `referenceId`，调用 `/api/external/v1/editor/icon-spritesheets/generations`，提交具体 `iconDescriptions` 与 `screenColor=auto` 生成透明 `assets/art-spritesheet.png`。严禁把 `assets/ui-prototype.png` 当作规范图引用；`art-spec.png` 缺失、不是当前画布的 `icon-spec` 或缺少稳定 `resourceId` 时，两个下游任务都必须等待 `art-director`，不得把本地路径、Data URL / Blob URL 当成稳定引用，也不得退回普通生图。单波最多 `3` 个静态职责的资源上限保持不变，调度只调整现有任务的依赖边和就绪顺序。
 - UI extraction 边界：`/api/external/v1/editor/ui-designs/assets/extractions` 只适用于已有且带红框标注的 UI 设计图，不是 UI 设计图生成接口，也不进入本次 canonical DAG。后续若要生成独立 UI spritesheet，必须先补红框源图生成与正式产物合同，不得直接对无标注 `ui-prototype.png` 调用 extraction。
 - 完成门禁：External Editor 2xx 只表示生成请求完成。通用 `warning` 优先于 `sliceWarning`；`postprocess-failed-source-preserved` 表示 provider 源图是唯一权威结果，但不满足透明图集合同，客户端保留服务端事实并失败关闭，不登记本地正式 spritesheet、不伪造切片、不自动重跑。仅 `sliceWarning` 时完整透明图集有效，Runtime 把原始 reason 写入私有审计与 Agent observation，但不得声称独立切片存在。下载结果还必须解码并至少包含一个真实透明像素，纯 RGB 或全不透明 RGBA 一律拒绝落盘和 manifest 登记。
 - OpenAPI 同步事实：2026-07-28 从 `https://www.genarrative.world/api/external/v1/openapi.json` 获取的线上合同与 `docs/openapi/genarrative-external-v1.openapi.json` 原始 SHA-256 均为 `00fa39ea8781605b895b331a579fbf097eea7892962350cb2a82bed7e1024135`，逐字节一致，因此不制造无意义 JSON diff；实现按现有公开 `screenColor`、`assetLabel`、`warning` 与 `sliceWarning` 契约更新。
@@ -6053,6 +6074,12 @@
 - 当前口径：`server-rs/crates/platform-llm/tests/live_stream_tool_calls.rs` 是默认忽略的真实端点工具调用 smoke；`on_delta` 只接收文本，工具调用从最终 `LlmRunResponse.tool_calls` 读取。现有测试没有原始 SSE 录制、事件类型/slot/分片顺序保存或逐事件比较，因此两类测试都不能证明 raw SSE fidelity 或抓包转录无偏差。
 - 现有确定性流式工具覆盖应与普通 Anthropic 文本流测试分开统计：三协议真实来源 fixture、Responses 仅有 completed / incomplete 终态事件时的恢复、并行 slot 聚合、截断参数和无片段 `StreamUnavailable` 等用例共同覆盖 parser 边界；未来若需证明转录一致性，必须另行增加受控原始 SSE capture/compare 能力。
 
+## 2026-07-27 图片画布左侧素材库统一稳定多选与批量操作
+
+- 范围边界：本次只重写左侧素材库选择模式，不改变中央画布舞台和图层列表的选择、框选或下载语义。选择集合以全部上传完成且媒体地址有效的素材为有效性边界，不因搜索、折叠或展开变化而收缩；只有素材被删除、进入上传中 / 失败态或媒体地址失效时才清理对应选择和范围锚点。
+- 输入语义：鼠标、键盘、触摸和笔输入单击都只切换当前素材，不替换其它已选素材；`Shift + 点击` 按当前可见顺序把连续区间增量加入现有选择，锚点当前不可见时退化为切换目标素材并建立新锚点。当前搜索结果的全选 / 取消全选只增量增删已展开的可见素材并保留其它选择，同时清空上次单项选择的范围锚点。退出选择模式、关闭素材栏或切到图层栏统一清空选择、锚点和框选状态，非选择模式不显示历史选中高亮。触摸素材卡仍可单击切换，但触摸列表空白区域必须保留纵向滚动，不启动框选；鼠标 / 笔框选使用素材列表内容坐标承接滚动偏移，并以 `pointerup` 的最终坐标提交，`pointercancel` 只取消框选。
+- 工具栏与导出：批量工具栏作为素材滚动列表的固定非滚动底栏，展示跨搜索与折叠状态保留的全部已选数量，并提供当前可见范围全选 / 取消全选、下载、删除和取消。下载消费完整选中集合；删除完整选中集合时，如果其中存在当前未显示素材，必须先用危险确认弹窗明确展示全部删除数量和未显示数量，用户确认前不得执行删除。选择模式隐藏单行下载 / 重命名并禁用行拖拽和右键菜单；内置、上传未完成、上传失败或无可读来源的行显示为不可选择，不暴露虚假的可用按钮。移动端选择模式使用独立的侧栏高度状态，并让素材列表恢复纵向滚动，避免普通模式 `14rem` 高度上限被固定底栏、标题和搜索区吃完。一个选中素材直接下载，多个选中素材复用画布素材导出管线生成 `项目名-选中素材-YYYYMMDD-HHmmss.zip`，根目录为 `项目名-选中素材/`；单素材、序列帧和两类集合 ZIP 的下载名统一包含到秒的本地时间戳。素材卡整行是统一选择命中区，标题和空白区不得绕过单项切换或 Shift 范围处理。序列帧层的可导出性以至少一帧具有可读 `imageSrc / objectKey` 为准，不依赖层级 `src / objectKey`；单项、选中集合和整画布导出共用一个前端互斥锁，避免下载和状态提示互相覆盖。
+
 ## 2026-07-29 抽取通用多 Agent Runtime 公共内核第一阶段
 
 - 背景：AI 游戏创作 Runtime 已有独立 Runner、持久任务、Provider 恢复、Goal、计划、静态/隔离协作和 finalization，但实现仍属于 Tauri package；内建 capability、Agent 目录和 Run Profile 缺少第二个产品可直接依赖的公开契约。
@@ -6090,6 +6117,7 @@
 - 占位删除与重试：completion 必须读取当前权威 dialog；若删除已先持久化，只跳过画布 layer / dialog 写回，不得使用请求中的旧 placeholder 复活图层，已经成功持久化的 project resource / 账号素材允许保留。若回包时本地占位已删除，前端不得应用完成快照或写历史；现有布局 CAS 没有 deletion tombstone，因此 completion 先提交、删除保存后冲突的极端竞态仍按权威快照收口，绝对“删除意图胜出”留待 targeted delete / tombstone 方案。该路由是 unsafe POST，客户端不得配置 `EDITOR_REQUEST_RETRY_OPTIONS`；请求字节可能已发出后不因 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 自动重放，Bearer 中间件在 handler 前拒绝请求后的既有认证恢复继续保留。结果未知时先 GET 权威项目 / 素材快照，由用户显式决定是否再次执行。
 - 历史边界：成功加入画布时写一条 `perfect-pixel` 历史，中文标签为“完美像素”，并纳入新增结果保护；撤销不得让派生 PNG 消失。像素处理失败或 completion 因占位删除未落画布时不写该历史。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md`。
+
 ## 2026-07-31 game-chat 每条输出入聊天、试玩后收束与平台图集引用
 
 - 背景：game-chat 的 ready response 之前只作为 transient stream 展示，专业 Agent 的 `final-reply` 只进入各自私有 conversation，刷新或事件 / 轮询重放时项目聊天可能丢失这些输出；自主构建完成后仍可能继续进入发布任务；配置 External Editor API 时，原型 HTML 也可能不实际使用平台生成的 Canvas 美术资源。
@@ -6338,6 +6366,7 @@
 - 影响范围：`/editor/canvas` 的 `audio-background-music` 面板撤销按钮与其定向测试；不改变单层交换快照语义、canonicalization、提交锁、Suno 契约或后端 Prompt 助手，也不修改状态模型字段，`temporaryPromptSnapshot` 已在公开 dialog 状态中且只在 `completing` / `simplifying` 期间非空。本条不适用于 SFX，V1.0 不改动 SFX 的一键优化与撤销行为。
 - 验证方式：按矩阵逐行覆盖初始隐藏、首次与再次 AI 处理期间显示并禁用、成功启用、失败隐藏、手动编辑后仍启用、点击预设隐藏、`submitting` 有无快照的两种表现、解除锁定后恢复，以及连续撤销互换保持启用；并断言处理期间按钮仍在可访问树中且为真实禁用态。
 - 关联文档：`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。
+
 ## 2026-08-03 完美像素对账判据改看 dialog 收口状态，网关合成响应归入未知结果
 
 - 缺陷一（对账把真成功判成失败）：对账用「同 ID 的 generation-dialog 是否还在权威快照里」判定成败，而服务端成功回填时**保留**该 dialog 并就地改写——`apply_editor_canvas_generation_items` 置 `status: "idle"`、`composerOpen: false`、写入 `generatedLayerId`、清掉 `errorMessage`，该行为另有服务端测试断言 `dialog["generatedLayerId"]` 钉住。所以响应丢失但服务端其实已完成时，判据反向：用户被告知「画布未收到完美像素结果，请确认素材库」，而结果早已在画布上，重做一遍就造出第二份；这条分支还刻意不套用快照，本地也看不到那个新图层。
@@ -6511,6 +6540,22 @@
 - 权威性与剩余风险：preflight 不创建锁、reservation 或新表记录；最终 `persist_editor_pixel_art_result_and_return` 仍在同一事务内重复目录、布局、幂等 identity 和 revision 校验。preflight 通过后若目录或画布并发漂移，最终事务仍可能在 PUT 后拒绝并留下无引用 OSS object；彻底消除该 TOCTOU 需要 durable reservation / journal 或事务协调，不在本 PR 的最小修复边界内。
 - 契约影响：只新增 SpacetimeDB procedure ABI 与生成 bindings；没有表字段、index、migration、HTTP DTO、路由、状态码、OpenAPI 或 shared-contracts 变化。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-08-03 主站与 AI Game Creator 复用单一泥点钱包 Store
+
+- 背景：主站顶部优先读取 dashboard 总额，图片画板独立轮询 dashboard，充值 controller 和 AI Game Creator 又分别保存充值中心明细；不同请求返回时序不一致会让总额与分桶同时显示不同快照，快速生成或切换账号时旧响应还可能回滚余额。
+- 决策：在 `packages/shared` 提供依赖注入式 `createProfileWalletStore`，统一保存 `ownerUserId`、完整 `ProfileMudPointBalance`、读取状态与错误，并在每个实例的独立闭包内完成请求合并、尾随补读、generation 失效和 owner 校验。主站注入 `getPlatformProfileRechargeCenter`，AI Game Creator 注入 `getClientProfileRechargeCenter`；两端不共享 transport、认证或重试实现。主站顶部、图片画板顶部和“我的”统计只消费同一 Store 快照，总额固定取 `totalPoints`；dashboard 的 `walletBalance` 只保留后端兼容，不再作为钱包 UI 数据源。
+- 并发与账号边界：同一 owner generation 同时只执行一个余额读取；读取期间的新变化通知在当前请求结束后补读，直到覆盖最后一次通知。切换或退出账号立即清空快照、提升 generation、中止并脱离旧 generation 的 active 请求，新 owner 不得等待旧 transport 收束；不响应 abort 的旧 transport 可以在后台结束，但其结果必须忽略。消费端在 owner 绑定 effect 提交前也必须按当前用户 ID 同步屏蔽 owner 不匹配的快照，不能让旧余额与新账号身份同屏。充值中心读取或 mutation 响应必须携带请求开始时捕获的 owner，owner 不符时忽略。刷新失败保留已有快照；响应缺少 `mudPointBalance` 时进入错误状态，不用总额反推分桶。
+- UI 与 mutation：充值 controller 继续保存商品、订单和支付状态，但充值中心响应必须同步写入共享快照，余额 mutation 应在应用响应后再通知一次合并刷新。充值弹窗的余额和分桶由当前 Store 快照覆盖。生成完成、失败退款、兑换码和邀请奖励等事件只发送余额可能变化通知；账号变化同时清理旧充值中心、账单与支付临时状态。`limitedPoints` 只按既有后端快照原样保存，本决策不新增或调整会员限时泥点展示与结算。
+- 2026-08-05 审查补充：主站 transport adapter 必须通过既有请求 options 真实透传 `AbortSignal`；页面恢复时相邻的 `visibilitychange / focus` 合并为一次余额通知，并在卸载时清理待执行任务。Store 的 owner 输入统一在边界 trim，活动请求清理同时观察 Promise 成功与失败，不能用无人接收的 `finally` 派生 Promise。
+- 2026-08-05 账号隔离补充，2026-08-07 完善 legacy 总额入口：账单读取、奖励码和邀请码兑换使用各控制器自己的账号生命周期 / 请求 revision，不依赖共享 Store owner effect 的提交时序；旧账号回调不得更新新账号 UI、结束新请求或刷新新账号钱包。充值下单、邀请码兑换和奖励码兑换三条写请求还必须共享账号生命周期 `AbortController`，在切号 effect cleanup 与卸载时中止旧 signal，使 `fetchWithApiAuth` 的 refresh 等待和写请求退避立即结束，禁止旧 POST 重试重新读取新账号 Token。AI Game Creator 的账单与充值使用独立 lifecycle，账号切换 render 必须同步屏蔽旧账单、充值和支付状态。充值中心兼容响应暂缺共享明细时，弹窗保留响应自带的 `walletBalance / mudPointBalance`，不把有效总额改写为 `0`；owner 匹配的 legacy `walletBalance` 同时可供个人中心统计卡和图片画板顶部等纯总额入口兜底，但 `mudPointBalance`、钱包展开明细和账单分桶继续保持空，不从总额反推或伪造分桶。
+- 2026-08-07 审查收口补充：共享 Store 显式保存 owner 隔离的 `legacyWalletBalance`，确保首次生命周期读取旧响应时无需先打开充值弹窗即可展示纯总额；较新的 legacy-only 响应必须原子清除旧 `mudPointBalance`，该字段不能生成分桶。直接余额快照附带单调 operation sequence；充值中心、支付确认和 watch 等异步响应都在请求发起前捕获快照，后发操作先落地后拒绝更早快照回滚。刷新错误只向 UI 暴露稳定中文提示，不透传 transport / 后端实现文案。
+- 2026-08-07 lifecycle 所有权补充：主站钱包坚持全应用唯一 lifecycle，由 `AuthGate` 根认证边界绑定 ready user；现役平台壳、图片编辑器和 profile controller 只消费 Store，不重复声明 owner。根边界在账号失效、依赖切换、StrictMode effect replay 和最终卸载 cleanup 时统一 `resetWalletBalance`，中止活动请求并清除 owner、明细和 legacy 总额；禁止在子页面按相同 user ID 各自清理 module-level Store。
+- 2026-08-07 refresh 发布隔离补充：`apiClient` 把公开 token 设置与清理视为认证代际变更，共享 `/api/auth/refresh` 只在“代际 + 发起时 token”快照相同时复用。refresh 成功只能以同一快照 CAS 发布新 token，旧账号晚到成功必须拒绝；旧 refresh 的 401/403 也只能在原快照仍当前时清 token。新账号进入新代际后立即发起独立 refresh，不等待也不加入旧账号 Promise。
+- 2026-08-05 生成扣退费时序补充：external generation 入队时尚未扣费，worker 领取为 `running` 后的资产操作才预扣，业务失败则先退款再写任务失败态。主站钱包因此以账号下全局 active external task 为轮询生命周期，每轮成功状态读取都通知共享 Store 合并刷新，终态轮同时覆盖成功结算与失败退款；画布内容刷新仍只限当前项目的 `completed`，不因其它项目或 `failed` 刷新画布。
+- 验证：共享 Store 覆盖首次读取、尾随补读、旧响应、账号切换、错误保留和错误 owner；主站覆盖 dashboard 与充值中心不一致时三处 UI 仍一致、切换账号清空及 focus 刷新；AI Game Creator 覆盖 adapter、账号 owner 和 focus 刷新。运行定向 Vitest、两端类型检查、编码检查与 `git diff --check`。
+- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
+
 ## 2026-08-04 AI 游戏项目 manifest 存储与工作台实时投影
 
 - 存储决策：`.agent/manifest.json` 的版本追加不可变约束由同目录持久专用锁保护，读取旧状态、校验版本前缀、安装临时文件和安装后回读必须处于同一临界区；进程内 Mutex 不能替代跨进程文件锁。
@@ -6570,6 +6615,7 @@
 - classic script 分析单元把 inline 与无 `defer / async` 的本地 external 正文按 `game/index.html` 标签顺序交错组成 parser-blocking 段，再把 classic external `defer` 按文档顺序放到解析完成后的 deferred 段；不得把 defer-before-inline 误投影为外链先执行。classic external `async` 的下载完成顺序不可静态证明，当前静态门直接失败关闭。带 `src` 标签的 inline body 继续忽略；外部文件仍执行可信普通文件、`game/` 边界、文件数与累计体积门禁，重复标签按浏览器出现次数保留求值位置。
 - Canvas 尺寸、可见性、元素绑定和 stylesheet 选择器扫描只消费浏览器可渲染标记；`template / textarea / noscript / title / style / xmp / iframe / noembed / plaintext` 内的 Canvas、标签和样式诱饵全部跳过。活动顶层 stylesheet 与可见标记分开提取，既允许真实 CSS 参与隐藏/尺寸判断，也不把 CSS raw-text 中的伪标签当作 DOM。
 - ESM 组合单元按 dependency 初始化先于 importer 顶层求值排列。import reference 的 span replacement 仍基于原 importer 完成，随后把已闭包的 dependency projection 放在 importer 前并对最终单元重跑 parser、semantic、单元 `2 MiB` 与累计投影 `32 MiB` 门禁；循环模块继续按 `(origin module, original root binding)` canonical identity 去重并要求有界固定点收敛。
+
 ## 2026-08-04 JavaScript 延迟状态与复合调用边
 
 - 受控异步 callback 的 alias 读取按完整 enclosing invocation 链延迟到各层函数同步收尾，最外层再延迟到当前 job 末尾；callback 写入仍不在注册点同步提交。conditional / assignment expression callee 分别在 test / RHS 求值后建立调用边，`new` 同时执行普通 function constructor 及 alias。
@@ -6611,6 +6657,12 @@
 - 根 Supervisor 的 manifest completion gaps 只对 status 已为 Completed 的 seed task执行正式产物与 Canvas 深验；pending/running/failed 本身已经构成完成阻塞，禁止提前扫描后续波次。自动唤醒 200 次瞬态重试预算耗尽后必须写入 `needs-reconciliation`，不能静默返回并留下假运行状态。
 - parent wake 的 terminal reconciliation task 是 durable commit marker，state / queue / event / Agent DB audit 是可幂等重建投影；非瞬态 task journal 读取错误直接失败关闭。restart 只在 raw state 具有完整 Agent/task/Session/run/source/profile/binding/task 身份时修复其当前 run；state 缺失、损坏、空对象或关键身份为空时只取 journal 最后 logical run，完整有效的新 Run 阻止历史 marker 覆盖。event/audit 必须完整 payload 唯一匹配，同键冲突或重复失败关闭；旧 task 终态、Runtime 非 waiting 或新 Run 接管时，durable deferred signal 追加 resolved/superseded 后才返回 obsolete。
 
+## 2026-08-07 game-chat Supervisor 意图与单主美术顺序门
+
+- `game-chat-workflow-decision` 升级为 v2。Supervisor 必须把自己理解的用户目标写入非空 `intentSummary`；`strategy=audit-existing-first` 只提供固定安全执行上下文，不代表用户意图，也不授权生成图片。Runtime 只校验身份、字段和执行边界，不用关键词替 Supervisor 做语义决定。持久决策后只调度 `code-prototype`，普通 GUI / CLI 的 16 节点 DAG 保持不变。
+- `code-prototype` 成为 game-chat 唯一主 Agent：先 `asset.list`，资源完整时直接接入且零美术委派，只有真实缺口才临时委派对应的 `art-director` 或 `art-asset-plan`，child 只写 `assets/**`。两个槽位同时缺失时，`art-director` 的 delivery 必须先被同一主 Run 认领并达到 `EvidenceReady`，之后才允许委派依赖规范图的 `art-asset-plan`；同一槽位不同 actionId 仍不得重复消耗委派名额。生成型回执未认领、证据未就绪或身份不匹配时完成门失败关闭。
+- 升级恢复兼容 v1 决策，但不沿用旧责任链：读取时严格复核 v1 fingerprint，从根完成合同的有效任务恢复 `intentSummary`，并保留旧 fingerprint 只用于核对已有 route 身份。旧 `code-director` coverage/route 对当前单主完成门表现为 migration pending；当前 `code-prototype` 必须重新 `asset.list`，再原位写入自己的 coverage/route。这样同一根 Run 可以继续，又不会把旧 Director 审计冒充成主 Agent 本人的完成证据。
+
 ## 2026-08-04 静态视觉状态流与可见证据收口
 
 - Canvas、2D context 与图片变量统一按 semantic symbol 记录声明和整体赋值事件；重新指向离屏 Canvas、无效 context 或新图片时立即失效旧视觉身份，只有绘制点可证明的当前状态才作证。
@@ -6631,6 +6683,16 @@
 - 最终共享边界：Tauri 撤销/重做改为直接消费共享 `useCanvasHistory`；共享 history 统一恢复 viewport、selection、图层位置和缩放边界。Tauri Pointer 代码只负责把宿主事件接到共享 selection/viewport/transform/renderer 算法，不再维护第二套 history 栈。
 - 事务发布前恢复：首个快照、全部快照、journal 后但 ledger 前都是正式故障点。无 ledger 的 transaction 仅在受控目录内容、正式文件不存在且 manifest/revision 精确保持 before 时清理并返回 rolled-back；未知条目或权威状态变化必须失败关闭。清理后允许原 commit/idempotency 身份重放，最终仍只产生一个 manifest asset。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/project/asset_canvas/generation.rs`、`packages/image-canvas-core/src/ports.ts`、`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`。
+
+## 2026-08-03 图片画布生成产物统一“改造”契约
+
+- 背景：画布生成结果统一显示“改造”，但部分动画 / 音频结果无法恢复面板；另一些非生成型派生结果继承最近生成输入，产生错误可执行动作。中文标题和素材类别被同时当成显示文案、参数键和路由键，改名后容易漂移。
+- 决策：用户动作 `改造` 的语义是恢复原生成输入、编辑并生成新产物。沿用 `generation_inputs_json`，V2 以稳定 `action`、`fields[].id`、`references[].id/refType/refId` 作为唯一执行契约，`title` / `label` 只用于展示，字段值保留基础类型。引用只匹配当前已 hydrate 的画布图层，媒体类型取匹配图层的运行时数据，不重复写入快照，也不新增 owner-only 工程资源 / 素材库 resolver。面板直接上传引用和已移出画布的引用不恢复：可重新选择的槽位留空并提示，提交门禁继续校验必填槽位；必须依赖原 `source` 图层才能构造面板的 action 仍按 capability 保留改造按钮，source 缺失时点击后显示明确错误并拒绝改造，运行期来源变化时仍必须复检。有效 V2 不因引用缺失降级到 legacy adapter。提交前参数只归一一次，请求与持久快照共用同一归一值。
+- 兼容：恢复优先级为有效 V2 → 完整历史生成对话框 → legacy adapter。legacy 允许使用 `assetKind/mediaType`、历史标题别名、资源模型 / 尺寸 / 时长 / `sourceResourceId` 和当前默认值，但必须显示恢复告警；不回填存量数据，不做 SpacetimeDB schema 迁移。
+- 边界：独立裁扩、手动去背景和手动图集拆分结果不继承生成输入，不显示 `改造`；原生成任务内自动后处理产物可保留原输入。Owner 读取保留 V2 执行字段；匿名公开素材 payload 暂不返回 `generationInputs`，不沿用 owner 可执行配方 DTO。
+- 影响范围：图片、规范、角色、图标、UI、宣发、视频、音效、背景音乐、角色动作、生成型图片编辑和 UI 素材提取；不影响作品详情“作品改造”、`AI重绘` 或常规 `快速编辑`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。
+
 ## 2026-08-05 画布图层元数据以资源行为准，读边界补齐 sourceType
 
 - 背景：结构化画布保存要求图层布局项里的资源权威字段与 `editor_project_resource` 行逐字相等，否则整次 PATCH 报「与项目资源不一致」，而该 400 属于 non-retryable，会被前端保存队列静默吞掉。但读边界并不把这些值原样下发：`sanitize_editor_user_model` 会脱敏内部处理模型、`provider` 被无条件省略（见 2026-07-31 修正抠图内部元数据的普通用户读取边界），`sourceType` 则在结构化保存校验通过后被归还资源行、图层列置空，读回时整个键不存在。客户端拿不到权威值只能自己补——`resolveHydratedLayerModel` 沿来源链推导出展示用生图模型，`hydrateLayer` 把缺失的 `sourceType` 猜成 `uploaded`——再原样回写，判等于是必然失败。前者命中含 2026-07-30 之前抠图派生资源的画布，后者命中所有 generated 图层；两者都在项目重新加载后的首次保存触发，用户侧表现为「改动悄悄没保存」，完美像素因为提交前是严格保存才把服务端原文暴露出来。
@@ -6776,9 +6838,116 @@
 - 升级前 External 幂等任务可能仍在 payload 中保留客户端 references；重放比较只对白名单内已迁移的图片生成、图片修改、去背景、图标图集和 UI 提取任务，在旧侧有 references、当前侧已删除时移除旧字段，其他字段变化仍返回 `409`。音频 / 视频 / 角色动作等未迁移 job kind 始终完整比较，不能扩大兼容面。
 - 本次复用既有 `external_generation_job.dedupe_key` 唯一索引和 `spacetime-client` 查询，不改 SpacetimeDB schema、迁移或 bindings。
 
+## 2026-08-05 图标规范生成拆分请求预检与最终执行，图集规范引用改为窄事务查询
+
+- 图标规范 HTTP handler 在调用文本 LLM 前，先通过可复用图片请求预检完成参考图稳定性、owner 授权、Provider 配置与运行时定价校验；随后补齐 `ExtraParam` 与最终 prompt，并继续走既有 `editor_image_generation` inline / queue 分流，不新增图标规范专用 worker job。最终执行仍重新校验请求，以处理排队期间发生的权限或资源变化。
+- 图标图集主规范引用由通用 SpacetimeDB procedure `resolve_editor_reference_and_return` 在同一事务快照内解析和校验 owner。ID 使用资源 / 素材主键；objectKey 按规范化 `image_src="/<objectKey>"` 索引读取唯一行，并使用 `asset_object(bucket, object_key)` 复合索引校验对象 owner。procedure 不接收业务 / 存储类型 allowlist，复用既有 `EditorProjectResourceSnapshot` / `EditorAssetSnapshot` 返回完整单行，不新增图标专属 DTO，也不再拉取完整项目和素材库；`icon-spec` 业务类型与游戏类型由 API 业务代码校验和提取。缺失引用、跨 owner、asset object 不匹配、业务类型错误、元数据解析与数据库错误全部失败关闭；仅“合法记录没有 genre”允许返回 `None`。
+- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-08-06 图标规范与图标图集使用独立任务及 ID-only 主规范引用
+
+- 本条取代上一条“不新增图标规范专用 worker job”和“图标图集主规范允许 objectKey”的结论。图标规范生成使用独立 `editor_icon_spec_generation` job kind；队列保存原始强类型业务参数，worker 在统一计费操作预扣成功后执行 ExtraParam LLM、构建最终 prompt，再进入共享图片生成和既有后处理 / 持久化链。SpacetimeDB 编辑器生成结果 operation kind 白名单必须显式包含该独立 job kind，确保 Provider 成功后可以进入统一 durable receipt 原子提交；新增正式生成 job kind 时必须同步扩展白名单和模块回归。余额不足不调用文本 LLM，执行失败沿用统一退款；普通 `editor_image_generation` 的 DTO、payload 与执行行为保持不变。
+- `editor_project_icon.rs` 独立承接图标规范、图标 spritesheet、自动切片和手工拆分。普通图片模块只暴露可复用的 prompt builder 执行入口与强类型 provider 请求分流；nanobanana、无参考图 generation、有参考图 edit 的选择集中在同一个 helper，图标图集复用该 helper，不复制 provider 分支。
+- 图标规范生成的可选参考图与图标图集的必选主规范统一使用 `referenceId`，只接受当前 owner 的项目资源 ID 或账号素材 ID，不接受 objectKey、URL 或临时 key。SpacetimeDB `resolve_editor_reference_and_return` 因而只接收 `reference_id` 并按两张表主键查询，删除 `image_src` 二级索引。图标图集的普通附加参考图 `referenceImageSrcs` 仍允许 owned objectKey、项目资源 ID 或素材 ID，并继续走既有 owner 校验与真实图片下载链。
+- External v1 图标图集请求与 OpenAPI 同步改为必填 `referenceId`。前端和 Editor Agent 优先传正式 resource ID，其次传 asset ID；本地临时 ID、objectKey 和图片地址不得回退成主规范引用，未登记时明确失败并要求先上传或登记。
+- `resolve_editor_reference_and_return` 的歧义只在当前 owner 范围内判断：两张表先按 `owner_user_id` 过滤，同名但属于其它账号的行不阻断合法引用。记录存在 `asset_object_id` 时按该 ID 定位并同时核对 bucket、object key 与 owner，只有缺少 ID 的兼容旧行才按位置查询。图标规范入队 / inline 预检只验证这组行与对象元数据；inline 与 worker 共用的最终执行入口还必须在把 `referenceId` 转入通用图片请求前再次执行同一 ID / owner 校验。最终共享图片执行器再下载一次参考图正文，避免同一引用在入队、worker 预检和生成阶段重复下载。
+- 关联：`server-rs/crates/api-server/src/editor_project_icon.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`docs/openapi/genarrative-external-v1.openapi.json`。
+
 ## 2026-08-06 音效与背景音乐恢复共享音频 Composer
 
 - 决策：图片画布的 `audio-sound-effect` 与 `audio-background-music` 只保留一个 `ImageCanvasAudioGenerationComposerView`，组件内以 `isSoundEffect = dialog.mode === 'audio-sound-effect'` 分流。撤销的是完整 `ImageCanvasBackgroundMusicGenerationComposerView` 这一层视图拆分，不撤销 BGM Prompt 纯模型、助手 controller、预设模型或预设跑马灯的独立职责。
 - 业务隔离：共享组件不等于共享规则。SFX 继续使用 Vidu `audio1.0`、2–10 秒、默认 5 秒、现有 Prompt 回退、1500 字限制、价格和提交链路；BGM 继续使用 canonical Prompt、200 字生成限制、30 个预设、AI 补全 / 简化、单层撤销、提交锁和 Suno。BGM 按 dialog ID 写回，SFX 继续走现有 `setGenerateDialog`，两条路径不得互换。
 - 非目标：本次只规划视图归并，不实现 SFX V2 的 ElevenLabs、中译英、自动时长、30 秒、Loop、一键优化或预设，不修改任何后端、External v1、Schema、计费或需求原文，也不新建配置驱动的 composer 框架。
 - 实施状态：已恢复共享音频 composer，独立完整 BGM composer 及其测试文件已删除，原覆盖完整迁入总 composer。Prompt / 预设 / controller / 总 composer `121/121`、surface 与 submission workflow `72/72` 通过，typecheck、变更文件 ESLint、Prettier、编码检查和差异检查通过；没有修改后端、契约或需求原文，也没有实现 SFX V2 独有功能。
+
+## 2026-08-06 SFX 生成优化 V2.0 T0 设计与迁移口径
+
+- 权威入口：SFX V2 的可编码规则已完整融合到 `docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。实现、审查、测试和发布只以该 tracked 权威设计、本条决策和共享实施计划为依据，不依赖团队通过 Git 无法取得的本地资料。
+- 共享视图边界不变：`audio-sound-effect` 与 `audio-background-music` 继续共用 `ImageCanvasAudioGenerationComposerView`，通过 `isSoundEffect` 分流；SFX 和 BGM 的 Prompt 模型、controller、预设 wrapper、锁和提交契约分别维护，不新建独立页面或第二套音频系统。
+- 后端入口边界：正式生成原地演进 `server-rs/crates/shared-contracts/src/assets.rs` 的现有音频 DTO 与 `server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs` 的现有 handler，保留既有 `/api/editor/audios/*/generations` 路由、queue / inline 分流、计费和队列边界；不得新建平行 DTO、正式生成 BFF、handler 或第二套路由。只有 SFX Prompt 优化内部路由、Worker 翻译 service 和 ElevenLabs adapter 是新增能力。
+- provider 迁移：新编辑器 SFX 任务固定使用 ElevenLabs `eleven_text_to_sound_v2`，不提供模型选择、Vidu fallback 或 `audio1.0` alias。Vidu builder / 轮询仅保留给历史素材和其它未迁移调用方；历史素材可读，重绘新任务使用 ElevenLabs。
+- Prompt 真相：`prompt` 表示用户可见且确认的 canonical `userPrompt`，`actual_prompt` 表示 Worker 严格验收后实际提交给 ElevenLabs 的英文 `actualPrompt`。两者均以 2048 Unicode code points 为上限，只删除首尾 Unicode `White_Space`，不做其它规范化、默认 Prompt 回退或静默截断。
+- 可见交互：SFX 固定 40 个事件预设 + 12 个补充要求。空 Prompt 直接写入；非空 Prompt 末尾已是 Unicode 标点时直接追加，否则使用中文逗号 `，` 分隔。允许重复，不保留选中态，不去重或截断；点击预设清除旧快照。
+- Prompt 助手：一键优化使用 `gpt-5.6-luna`、`reasoning_effort = medium`；Worker 正式英文化使用同模型、`reasoning_effort = low`。两类候选上限均为 2048 Unicode code points，因此分别固定 completion tokens 总预算 `2048 × 4 = 8192`；该预算由隐藏 reasoning tokens 与可见输出 tokens 共享，不包含输入 Prompt tokens，也不是可见正文保证。当前 VectorEngine OpenAI Chat wire 固定发送 `max_completion_tokens = 8192`，内部历史字段名 `max_output_tokens` 不是业务语义。预算不按实际输入长度动态缩小；两者均不发送 temperature 或 function tools，只接受完整 `response.text` 中唯一 JSON object 的严格 envelope。翻译除要求 `isEnglish = true` 外，程序侧还要求候选至少含一个 Latin alphabetic code point，且所有 alphabetic code point 都属于 Latin Script；日文假名、韩文、西里尔、希腊和阿拉伯等非 Latin 字母均失败。优化只有一个业务语义轮，`finish_reason = length` 直接失败；翻译首轮成功响应但候选不合格或 `length` 时使用同一 `userPrompt`、同一 `8192` 上限唯一重试，第二轮 `length` 最终失败，`content_filter` 和 transport 最终失败不开启第二业务语义轮。翻译最终失败时 ElevenLabs 请求数必须为 0。
+- 撤销与锁：一键优化成功产生一层 canonical Prompt 交换快照；优化失败清除本次临时快照，不恢复更早快照。AI 操作和正式提交使用 dialog ID、账号 + 项目 scope、同步 operation ID 与 `AbortController`；只锁当前 SFX dialog。正式提交在第一个 `await` 前冻结 Prompt / duration / Loop；API 接受后结束 `submitting`、进入现有 `queued/generating` 占位，不把接受任务写成生成已完成。
+- 时长与 Loop：首次打开默认自动时长模式，预置最近手动值 `5s`、Loop false；手动范围 `0.5-30s`，UI 步进 `0.1s`。自动模式发送 `duration_seconds = null`，禁用 slider 但保留最近手动值。Loop 是独立 API 布尔参数；系统不根据 Prompt 推断、同步或校验 Loop，Prompt 文本与 Loop 开关不建立业务一致性门禁。
+- ElevenLabs 契约：`POST /v1/sound-generation`，body 固定 `text / model_id / duration_seconds / loop / prompt_influence=0.3`，query 固定 `output_format=mp3_44100_128`，`xi-api-key` 只在服务端 header 注入。provider POST 不自动重试，浏览器正式 POST 不 unsafe retry，队列 `max_attempts = 1`，一个平台 job 最多一次 ElevenLabs POST。成功响应复用现有 `MAX_GENERATED_AUDIO_BYTES = 40 MiB` 做 Content-Length 预检和 `limit + 1` 流式读取，验证 MIME 与真实 MP3，并探测有限正实际时长；实际时长仅受独立技术异常上限 `600s` 约束，不与请求最大 `30s` 比较，`30.5s-600s` 的合法结果可接受。平台使用 operation / queue job ID 作为 `taskId`，不伪造 provider task ID。
+- 结果真相：服务端重建 SFX V2 `generation_inputs_json`，写入 `userPrompt / actualPrompt / model / durationMode / requestedDurationSeconds / actualDurationSeconds / loop`；实际英文 Prompt、实际时长、model 和 Loop 不信任客户端自报。SFX V2 完成响应的 `durationSeconds` 使用同一 MP3 探测值；本条作为后出的 SFX 专项决策，仅在该完成响应上覆盖 2026-07-28“音频生成响应不得新增 `durationSeconds`”的通用口径，不新增资源 / 素材正式时长列，也不把该值写入 `EditorAsset`、`CanvasLayer`、layout 或图片序列字段。信息弹窗展示用户 Prompt、实际英文 Prompt、模型、实际时长、Loop 和平台 Task ID；历史 Vidu 数据不误标英文 Prompt。
+- 计费、External v1 与 schema：新模型键 `eleven_text_to_sound_v2` 保持 5 泥点 / 次，后端入队时冻结价格为真相。External v1 的 duration 演进为可选 / nullable `0.5-30 number`，Loop 缺省 false；`model` 的 omitted / null / 空串 / 纯空白 / 首尾空白包围的新模型 / 显式新模型统一 canonicalize 为 `eleven_text_to_sound_v2`，并产生相同幂等 payload。显式旧 `audio1.0` 和未知非空值返回 `400 BAD_REQUEST`，且必须为零入队、零预扣、零 LLM、零 provider；Rust、OpenAPI、幂等重放与最终响应必须在 T5 同批变更。本次不修改 SpacetimeDB schema，复用现有 `prompt`、`actual_prompt`、`generation_inputs_json` 和画布 layout。
+- 共享计划：脱敏 T1–T6 任务、当前基线、测试矩阵、旧 Vidu 队列 drain、发布与回滚门禁记录在 `docs/project-memory/plans/【实施计划】SFX生成优化V2.0任务拆解-2026-08-06.md`。T0 只验收设计、决策、共享计划、差距归属和安全记录，不要求当前 Vidu V1 代码、OpenAPI 或实际 API 已与 SFX V2 设计一致；实现差距归入 T1–T5，T6 统一验收。
+- 安全与状态：机器本地未跟踪资料不得进入提交，也不得被仓库文档链接、引用或作为团队证据源；ElevenLabs Key 只允许从服务端私密环境配置读取，不进入浏览器、日志、fixture、共享文档或 Git。T0 已通过，可以进入 T1–T5 实现；后续仍不得把秘密值、个人本地资料或不可审计记录写入仓库。
+
+## 2026-08-06 SFX 生成优化 V2.0 T2 助手与 Worker 翻译 service
+
+- 一键优化：新增登录态内部路由 `POST /api/editor/audios/sound-effects/prompts/optimizations`，复用 T1 的最小请求 / 响应 DTO、现有编辑器 `LlmClient`、标准成功 / 错误 envelope 和 route tracking。请求固定 Luna、OpenAI Chat、Medium、completion tokens 总预算 `8192`，当前 VectorEngine Chat wire 只发送 `max_completion_tokens=8192`，不发送 temperature 或 function tools；路由独立使用 `32 KiB` body limit，不增加功能级限流器，也不进入 External v1。
+- 优化验收：内部五字段 envelope 必须从完整 `response.text` 直接反序列化，允许外围 JSON whitespace，拒绝代码块、前后解释、多个 JSON、额外 / 重复字段、错误类型、tool call 和未完成 finish reason。候选只删除首尾 Unicode `White_Space`，要求 `1-2048` code points、至少一个 Han code point，并严格执行 `true / true / false / false`；失败 HTTP 响应不携带候选、内部 envelope 或上游回显正文。
+- 翻译 service：在现有 `vector_engine_audio_generation` 内新增仅 crate 内部生成流水线可见、没有同步 HTTP 路由的翻译 service。每个业务语义轮固定 Luna、OpenAI Chat、Low、completion tokens 总预算 `8192`，当前 VectorEngine Chat wire 只发送 `max_completion_tokens=8192`，不发送 temperature 或 tools；候选严格执行五字段结构、`true / true / true / false`、`1-2048` code points、至少一个 Latin alphabetic code point，且所有 alphabetic code point 都属于 Latin Script。Han、假名、韩文、西里尔、希腊和阿拉伯字母均失败，Common / Inherited 数字、标点、空白和符号允许。
+- 轮次与错误：首轮成功返回但结构、判断、Script、长度或 `finish_reason=length` 不合格时，只以同一 canonical `userPrompt` 开启唯一第二业务语义轮；不得读取或传递首轮候选。首轮 `content_filter` 和 transport / timeout / 上游最终失败直接结束；`LlmClient` 内部 transport retry 仍属于当前业务轮。第二轮任何失败均最终失败。service 错误展示只提供 `translation_invalid / translation_upstream_failed` 分类和安全中文消息，不保存或输出未通过候选。
+- 阶段边界：T2 没有调用 ElevenLabs、创建额外任务、扣费、修改队列 payload、持久化 `actual_prompt` 或变更 External v1 / OpenAPI / SpacetimeDB schema。T5 接入正式 Worker 时必须移除 T2 的 staged dead-code 豁免，并把翻译结果作为唯一 `actualPrompt` 进入 provider；T2 单独合入仍不是可发布切点。
+
+## 2026-08-07 SFX 生成优化 V2.0 T4 前端 controller 与参数 UI
+
+- 状态模型：SFX 使用独立于 BGM 的纯状态模型和 dialog-scoped controller。优化与提交均在第一个 `await` 前同步 claim operation；账号、项目、dialog、mode 与 `AbortController` 共同判定响应归属。关闭、删除、mode / scope 切换后的旧响应不能写回新面板；同一按钮双击只有第一个 operation 生效。
+- Prompt 与撤销：计数、优化、预设、撤销和提交统一复用 T1 的 Unicode `White_Space` canonicalizer 与 `1-2048` code point 规则。优化开始时以当前 canonical Prompt 替换旧快照，成功转为单层交换快照，失败清除本次临时快照且不恢复更早快照；预设写入清快照，手动编辑优化结果后仍可在两个 canonical 版本间反复交换。
+- 预设视图：BGM 预设跑马灯抽出无业务语义的音频内核，保留单一可访问控件队列、无缝滚动、hover、触摸、页面可见性和 reduced-motion 行为；BGM / SFX 各自保留 wrapper、预设模型和业务 class。SFX wrapper 展示固定 `40 + 12` 预设，不保存展开、滚动或 hover 状态。
+- 参数与布局：SFX 首次打开为自动时长、预置手动值 `5s`、Loop false；手动 slider 为 `0.5-30s`、步进 `0.1s`，自动模式禁用 slider 但保留最近手动值。layout 恢复 `soundDurationMode / soundDurationSeconds / soundLoop`，历史 Vidu dialog 与改造入口统一打开固定 `eleven_text_to_sound_v2` / `ElevenLabs` 面板。前端显示新模型 `5` 泥点兜底，正式价格仍以后端 T5 入队冻结值为真相。
+- 锁与阶段边界：优化、提交或既有生成态只锁当前 SFX dialog 的输入、预设、滚动、参数、撤销和生成。提交 claim 同步冻结 canonical Prompt、时长模式、最近手动值与 Loop；T4 不改变正式请求的 nullable duration / Loop 映射，不接 Worker 翻译或 ElevenLabs，不修改服务端动态定价、计费、OSS、持久化详情、External v1、OpenAPI 或 SpacetimeDB schema。T4 必须与 T5 同一发布列车，不能单独发布。
+
+## 2026-08-07 SFX 生成优化 V2.0 T5 正式生成与 External v1
+
+- 正式执行链：站内与 External 请求在定价、预扣和 enqueue 前统一收敛为 canonical userPrompt、`model = eleven_text_to_sound_v2`、nullable 小数 duration 与 Loop；队列载荷不包含 actualPrompt。Worker 在既有冻结计费上下文内顺序执行 Luna 英文化、单次 ElevenLabs POST、MP3 校验 / 实际时长探测、OSS 和项目资源 / 账号素材 / 画布完成态写回，任一失败进入既有退款边界。queue 使用 job ID，inline 在 provider 前生成平台 Task ID，不伪造 provider task ID。
+- 权威结果：服务端只保留 Agent 身份关联字段并重建 SFX V2 `generation_inputs_json`，统一写入 userPrompt、actualPrompt、固定模型、duration mode、请求 / 实际时长和 Loop；客户端自报的实际英文 Prompt、实际时长、模型和 Loop 均被覆盖。信息弹窗展示中英 Prompt、实际时长、Loop、模型和完整平台 Task ID；重绘优先恢复 V2 metadata，自动模式恢复默认最近手动值 `5s`，不把实际输出时长当作手动请求值。历史 Vidu 素材仍按旧字段只读，并以新模型重绘。
+- 定价兼容：默认配置、api-server 与 SpacetimeDB 值校验同时要求保留 `audio1.0` 和新增 `eleven_text_to_sound_v2`。已存在的 SpacetimeDB 定价快照仅缺新键时，api-server 从当前受控默认 / override 补入该键后读取；其它缺失模型仍失败。该兼容不修改 schema、不在读取时写库，下一次后台保存自然持久化完整矩阵；队列计费、响应和资产成本继续使用入队冻结价格。
+- External v1：Rust DTO / handler、OpenAPI、幂等 canonical payload、compact result 与仓库 Agent Skill 同批演进。model 的省略 / null / 空串 / 纯 Unicode White_Space / 包围空白新模型 / 显式新模型统一入队；旧模型和未知非空值在 enqueue 前返回 `400`。完成结果增加实际 `durationSeconds` 与 Loop，继续隐藏 provider、userPrompt 和 actualPrompt，只暴露稳定结果引用。
+- 阶段状态：T1–T5 已完成，可以进入 T6；T6 仍需汇总 mock LLM / ElevenLabs / OSS 失败矩阵、计费退款、端到端等值、BGM 回归、API smoke、旧 Vidu 队列 drain 和发布 / 回滚门禁。T5 未执行真实 LLM、ElevenLabs 或其它付费请求，且没有 SpacetimeDB schema、migration 或 bindings 变更。
+
+## 2026-08-07 SFX Prompt 边界 canonicalization 改为 ECMAScript trim
+
+- 决策：SFX 的 `userPrompt` 与 `actualPrompt` 从首尾 Unicode `White_Space` 规则改为 ECMAScript `String.trim()` 语义。TypeScript 直接使用 `String.trim()`；Rust 以等值边界字符集合实现，不能使用语义不同的 Rust `str::trim()`。因此首尾 `U+FEFF` 删除、首尾 `U+0085` 保留，内部空白、内部 `U+FEFF`、`U+200B`、组合字符和 ZWJ emoji 继续保持原样。
+- 范围：只影响 SFX Prompt 的输入、优化候选、Worker 翻译候选、正式请求、metadata 校验与 ElevenLabs body；BGM Prompt 以及 External v1 `model` 的 Unicode `White_Space` canonicalization 不变。
+- 验证：共享 fixture 锁定 ECMAScript 全部首尾删除字符、`U+FEFF` 边界删除与内部保留、`U+0085` 边界保留、内部空白和 `1 / 2048 / 2049` code point；前后端必须共同消费该 fixture。
+
+## 2026-08-07 SFX 生成优化 V2.0 T6 Worker 组合门禁
+
+- 正式编排：SFX Worker 以同一个内部编排函数串联现有计费、翻译、ElevenLabs、OSS、asset object / bind 候选准备和原子项目资源 / 账号素材 / 画布 / job 提交。生产 adapter 继续调用正式实现，测试 adapter 只替换外部边界；禁止另写与生产分叉的“测试专用业务流程”。
+- 失败与退款：余额不足时 Worker future 不得被 poll，LLM / ElevenLabs / OSS / 写回均为零；预扣后的翻译、provider、MP3、OSS 或写回失败全部一次退款。组合矩阵必须证明每个 job 的 ElevenLabs POST 最多一次、翻译最终失败 provider 为零、成功只扣费一次。
+- 分类：内部稳定 reason code 固定为 `translation_invalid / translation_upstream_failed / translation_budget_exhausted / elevenlabs_http_failed / invalid_audio / duration_probe_failed / oss_failed / writeback_failed`。MIME、空 body 和大小归 `invalid_audio`；MP3 识别、帧读取和时长门禁归 `duration_probe_failed`。普通用户继续只读稳定短文案，不暴露 endpoint、上游正文或凭据。
+- 跨入口：画布 Agent `generate-sound-effect` 与站内 / External v1 共用 canonical Prompt、固定模型、nullable `0.5-30` 小数时长和 Loop；省略 duration 为手动 `5s`，显式 null 为自动。SFX 参数解析必须保留该 null，不能被通用 null-default 兼容层改写。最终仍进入相同 `editor_sound_effect_generation` queue payload，不新增 Agent 专属链路。
+- 发布边界：T6 工程实施和 mock / loopback 门禁不等于真实 provider 或生产验收。发布前关闭 SFX 入队，使用显式 `--server` / `--server-url` 只读查询 `external_generation_job` 中 pending / running 的 `editor_sound_effect_generation`，清零后按 api-server / Worker → Web 顺序部署并灰度；禁止 `--root-dir`、删除任务伪造 drain 或自动回退 Vidu。本次没有 SpacetimeDB schema、migration 或 bindings 变更。
+## 2026-08-06 编辑器生成结果使用 durable receipt 与统一原子提交
+
+- 背景：图片、改图、去背景、图集 / UI 多产物、角色动作、视频、音效和背景音乐在 OSS 结果可用后，仍分段 confirm object、创建 project resource / account asset、保存 canvas 和 complete job。任一中间失败都会留下部分业务事实；只把 `external_generation_job` 当 operation journal 又无法覆盖无 job 的 inline，也无法独立证明某批 resource/asset/canvas 已作为一笔提交完成。
+- 决策：新增私有 `editor_generation_operation` durable commit receipt，queue 与 inline 共用。`persist_editor_generation_result_and_return` 在一次 `try_with_tx` 内提交可选 asset object、全部 resource / asset / binding、可选 canvas V2 CAS、queue job 终态和 receipt。job 仍是队列、lease、计费和通知真相，receipt 只是提交凭证，不复制大快照或形成平行 read model。worker 成功走统一 procedure 后不再单独 complete job。
+- 身份与重放：queue 以 job ID 为 operation ID，inline 以稳定 request ID 为 operation ID；Provider task ID 只做审计。operation fingerprint 绑定规范请求，commit SHA-256 对完整提交输入的稳定 BSATN 编码做 domain-separated 哈希，另外绑定逐 slot 候选、布局与 job completion，不使用 Rust `Debug` 文本充当持久协议。receipt 存在且所有权威事实一致时才返回 `AlreadyApplied`；不重复事件、不刷新时间、不推进 canvas revision。receipt 缺失但稳定 resource/asset/binding 已存在必须失败关闭；事务前已单独确认的 object 只在全部字段精确相等时允许复用。
+- 并发、时间与 OSS 边界：canvas 冲突只刷新 project 重算布局，不重跑 Provider / OSS；`completed_at_micros` 必须为正数，候选原时间字段与它一起绑定 commit SHA-256，重放不重新取时；job 终态与事件使用 SpacetimeDB `ctx.timestamp`。OSS `PUT / HEAD` 仍在数据库事务外，事务失败可以留下无引用 object，不声称跨 OSS exactly-once。
+- queue 结果与 CAS 重试补充：普通画布 queue 只持久化 source/warning 元数据，Editor Agent 和 External API 分别只写入各自裁剪后的结果，最终 JSON 不得超过 512 KiB。消费者身份必须在 worker 从完整 claimed job 构造调用上下文时固化，不能从已裁剪的 summary 兼容快照反推。CAS 冲突最多刷新布局一次，只允许 revision/layers 和 layout `updated_at_micros` 随最新 project 变化，避免回拨并发用户更新时间；items、job payload 与 `completed_at_micros` 保持不变。每个 prepared commit 的传输未知结果最多原样重放两次，不重跑 Provider / OSS。
+- receipt 只保存 queue result 的 SHA-256，不复制最多 512 KiB 的 payload；重放时从已完成 job 回读权威 payload 并核对摘要。事务边界即使没有 asset_object candidate，也必须统一核对 resource/asset/binding 的 object ID/key/owner，并要求 canvas layout 与全部 project resource 属于同一 project。
+- 事务内还要先查同 `operation_id` 的 `external_generation_job`：存在则首次/重放都强制完整 completion guard，不存在才允许 inline。resource/asset 的尺寸、媒体引用、task、kind 与生成元数据按 item 交叉验证，音频 binding 使用 operation 限定 tuple 和显式 kind 映射。省略 candidate 的已登记 object 在 receipt 重放时仍回读 owner/key/task/kind/媒体身份。
+- queue 跨记录绑定继续失败关闭：job `source_entity_id` 必须就是结果唯一 project，所有 `source_resource_id` 必须已存在且属于同 owner / project。Provider 已成功但原子持久化确定失败时，当前 worker/lease 验证、当前计费 attempt 退款和 job 失败终态由同一 SpacetimeDB 事务结算；不在 api-server 先独立退款。
+- compact result 裁剪不得丢失消费 DTO 必填字段或正式素材定位信息：角色动作/视频保留 `ok`，音效/BGM 保留 `prompt`，External 角色动作与视频还保留稳定 `assetId`，不复制大型生成 payload。account asset 的 `source_resource_id` 与 project resource 一样验证候选/已登记来源的 owner，并在有项目上下文时验证 project。
+- External v1 的二次 allowlist 裁剪同样保留 `prompt / actualPrompt`，契约验收以 `serialize_atomic_editor_generation_job_result` 最终 JSON 为准，不只测上游 builder。图标/UI 正常与 source-only fallback 同时保留 `ok / prompt / actualPrompt`，fallback 的尺寸/model/价格也从本次生成上下文显式携带，不依赖可选 project resource。Editor Agent 图片生成/修改 DTO 允许 compact payload 不携带 `provider`。inline 八类 provider 生成的已成功 billing guard 延迟到 owner handler 完成 durable receipt 提交才 disarm；procedure 发出前的明确失败/取消退款，发出后回包前的传输不确定或取消保留扣款。
+- 影响范围：所有现役编辑器生成类型、`spacetime-module` / `spacetime-client` 结果提交契约、queue worker 终态写回、schema / migration / generated bindings 与对应故障注入测试。完美像素保留现有专用原子 procedure；手动图集拆分保留现有批量事务，其 canvas completion 并入批量事务另行收口。
+- 关联：`docs/technical/【后端架构】编辑器生成结果原子提交与幂等重放方案-2026-08-06.md`、Issue #134。
+
+## 2026-08-07 确定性派生配方与改造 capability 分离
+
+- 决策：`generationInputs` 是持久化配方 / 来源账本，不直接代表“允许改造”。完美像素、裁扩、所有手动与自动图集切片、手动去背景分别写 `image.perfect-pixel`、`image.crop-expand`、`spritesheet.split`、`image.remove-background`，固定 `fields: []`；有正式来源行时只保存服务端权威 `references[id="source"]`，没有正式行时为空。这四个 action 不进入改造 allowlist，历史 `pixel-art-snap-*` 同样失败关闭；整张生成图集继续保留生成 action，自动抠图仍是生成流程内部后处理。
+- V2 水合统一按 `version/action/fields[].id/references[].id` 严格识别，保留有限数字、布尔值与无标签引用；出现 V2 标记但结构无效时不得降级 legacy。完美像素账本复用相同 V2 白名单，外层仍为 version 1，并继续原形接受旧 legacy 请求以维持 exact retry fingerprint。
+- 安全边界：站内已迁移队列只保留客户端 references 的安全槽位 `id`，真实 `title/label/refType/refId` 全部按 owner-scoped 记录重建；External API 和直接不可信写入仍删除整段 references。队列幂等比较忽略该冗余展示槽位，但继续严格比较实际媒体来源与其它参数。
+- 不改 SpacetimeDB schema、路由或 External OpenAPI；不回填历史记录。
+
+## 2026-08-08 游戏场景接入 V2 改造配方
+
+- 背景：`72f268e0` 新增 `assetKind = scene` 和场景专用生成入口，但场景生成输入仍是依赖中文标题的 legacy 快照，无法通过现役 V2 action allowlist 稳定恢复“改造”。
+- 决策：新增稳定 action `scene.generate`，字段 ID 固定为 `prompt/stylePreset/customStyle/model/aspectRatio/imageSize`，参考槽 ID 固定为 `reference`。新产物由服务端按结构化场景请求重建权威 V2 fields，并从真实 `referenceImageSrcs` 生成安全引用槽位，后续继续沿用 owner-scoped provenance 重建；前端 action decoder 恢复场景 composer，并让请求与持久快照共用规范化参数。
+- capability 边界：`assetKind` 只表示素材类别，不直接授予“改造”。`scene.generate` 显式进入已知与可改造 action allowlist；V2 上线前的场景仅在 `assetKind === scene` 且 legacy 字段包含“画面内容”时兼容恢复并告警，不把“画面内容”加入全局 legacy 标题路由，其他类别同名字段继续拒绝改造。
+- 影响范围：图片画布场景提交、生成输入解码、改造入口、场景 composer 恢复、api-server 场景配方重建与对应前后端测试；不修改 SpacetimeDB schema、migration、bindings、External v1 路由或 OpenAPI。
+- 关联文档：`docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
+
+## 2026-08-08 AGC Vite 纳入统一用户端口段
+
+- 背景：Linux 主开发栈已按用户分配 `100` 端口段，但后加入的 AGC Tauri 壳仍固定监听全机共享的 `3080`。同机任一用户的旧客户端都会阻塞其它用户，且 marker 中出现的动态 API 端口无法解决 Vite 本身的跨用户冲突。
+- 决策：端口段正式增加第六个槽位 `agc-vite = start + 5`，端口段最小长度同步改为 `6`。Linux AGC 首选该槽位并只在当前用户段内漂移；Windows / macOS 保留 `3080` 兼容首选并统一探测漂移，不读取 Linux 系统注册表。
+- 一致性：`start-tauri-dev.mjs` 是端口选择权威，最终端口通过 Tauri CLI `--config` 覆盖 `build.devUrl`，通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，并通过 Vite CLI `--port` 启动严格监听。父启动器选定端口后，子启动器只允许严格使用同一端口，配套后端漂移必须跳过该预留端口，竞态占用必须失败关闭。
+- 安全边界：动态端口不恢复旧 Vite 复用。无法证明 worktree 归属的监听器仍不复用、不主动终止；同用户多 worktree 通过段内漂移并行，不通过共享未知服务并行。
+- 验证：公共端口映射、Linux 默认槽位与段内漂移、非 Linux 兼容漂移、Tauri 动态配置、启动前预检、进程树收束、AGC typecheck / 配置门禁、编码检查和差异检查必须通过。

docs/project-memory/shared-memory/pitfalls.md

@@ -62,6 +62,14 @@
 - 验证：使用 deferred commit/layout Promise，依次在请求后切项目、切 run/overview、新开 session、改选择和改筛选；断言 manifest 只更新对应项目，新资源仍进入投影/布局，但所有失效守卫都不切中央状态、不改选择、不清查询。条件未变化且资源可见时才自动定位。
 - 关联：`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`。
 
+## 派生 Debug 会让完整配置经应用状态递归进入日志
+
+- 现象：配置和状态当前没有直接日志调用，但新增一行 `debug!(?state, ...)` 或 `format!("{config:?}")` 就能把 JWT、后台口令、支付私钥、OSS / provider key 与 SpacetimeDB token 一次性写入日志及 OTel 留存面。
+- 原因：`AppConfig`、`AppState` 与 `AppStateInner` 曾使用派生 `Debug`；状态继续递归格式化多个含配置的 client。即使顶层状态停止下钻，`SpacetimeClientConfig` 及 `SpacetimeClient` 的独立手写路径仍会绕过顶层防线。
+- 处理：配置和聚合状态只实现封闭的手写安全摘要，不格式化任一自由字符串或含凭据的嵌套 client；`SpacetimeClientConfig` 独立脱敏，`SpacetimeClient` 只复用该安全摘要。不要以默认 `info` 级别或当前零调用点代替代码约束。
+- 验证：同一唯一哨兵同时填入全部凭据字段、可能带凭据的 SpacetimeDB URL 和数据库名，逐一格式化 `AppConfig`、`AppStateInner`、`AppState`、`SpacetimeClientConfig`、`SpacetimeClient`，断言哨兵零出现且安全运行摘要仍存在。
+- 关联：`server-rs/crates/api-server/src/config.rs`、`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/spacetime-client/src/active.rs`、Issue #148。
+
 ## Chat 生成预算字段不能按模型名猜测或失败后自动重放
 
 - 现象：同一个 OpenAI-compatible Chat endpoint 调用 reasoning 模型时返回 `Unsupported parameter: max_tokens`；直接把全局请求字段改成 `max_completion_tokens` 后，旧兼容网关又可能拒绝新字段。
@@ -91,18 +99,26 @@
 
 - 现象：用户只说“现在没有用到任何美术资源”，Graph 就在 Supervisor 输出任何计划前自动打开美术节点；或者用户想复用现有素材，Runtime 直接按关键词预完成节点。Supervisor 无固定计划时随即 `fixed-task-graph-stalled`，看起来像模型不理解意图，实际上模型根本没有获得决策机会。
 - 原因：同一套关键词函数同时承担 prompt hint、Graph reset、baseline 豁免和历史试玩类型继承，启发式信号越过 Supervisor 成为了控制面真相；main loop 又在 Provider 请求前优先调度 ready task。
-- 处理：启发式结果只序列化成 `advisoryOnly=true` 的 Supervisor context。Scheduler 以持久 `GameChatWorkflowDecision` 为首轮前置门；Supervisor 先选审计或整体重做，code-director 再用成功 `asset.list` 和 Runtime 复核的覆盖合同选择复用或精确补缺。Runtime 可以拒绝过期、伪造、遗漏或重复 route，但不得替 Supervisor 补写决定。
-- 验证：直接使用用户原句，断言 hint 命中但 manifest 全部保持 pending、决策前零 child、Provider request 包含路由工具；决策后首波只有 design/code，code-director 未完成 asset.list/route 时不能完成；再分别覆盖完整复用、真实缺口和显式重做。
+- 处理：启发式结果只序列化成 `advisoryOnly=true` 的 Supervisor context。Scheduler 以持久 `GameChatWorkflowDecision` 为首轮前置门；Supervisor 只持久化用户 intent，随后由唯一 `code-prototype` 用成功 `asset.list` 和 Runtime 复核的覆盖合同选择复用或精确补缺。Runtime 可以拒绝过期、伪造、遗漏或重复 route/delivery，但不得替 Supervisor 补写决定或固定生成美术。
+- 验证：直接使用用户原句，断言 hint 命中但 manifest 全部保持 pending、决策前零 child、Provider request 包含路由工具；决策后只启动 code-prototype，它未完成 asset.list 时不得委派美术；再分别覆盖完整复用、真实缺口和显式重做。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`runtime_driver/main_loop.rs`、`runtime_driver/task_start.rs`、`runtime_protocol/autonomous_completion.rs`。
 
 ## 既有正式产物不能同时被快车道视为已完成、被本轮 baseline 门视为未变化
 
 - 现象：增量任务已有完整美术图集，`art-asset-plan` 每轮都返回零 action 和“已验证交付”，但 completion gate 每轮都报告 `assets/manifest.art.json(unchanged-from-run-baseline)`；最终 child `loop-budget-exhausted`，随后 Graph 和父 Run 失败。日志中没有本轮 Provider request、tool plan 或 action receipt。
 - 原因：Graph reset 无差别重新打开稳定的美术 owner 节点；快车道按“当前产物有效”判断完成，owner 完成合同则按“本轮必须修改 baseline 产物”判断完成，两套语义互相冲突。增加 loop 预算、伪造版本号或机械改写 manifest 都不能消除冲突，还会引入 verification loop、字段丢失或错误复用旧主题。
-- 处理：关键词和资产探测只作为 Supervisor 的 advisory context，不能直接修改 Graph。根 Run 先持久化 `audit-existing-first / regenerate-art` 决策；前者只启动 `design-director + code-director`，由 code-director 在成功 `asset.list` 后提交权威覆盖合同和精确缺口。Runtime 验证合同后才把已有 owner 投影为 completed，或只打开缺口 owner；根完成门只对持久路由明确复用的 art manifest 忽略 baseline 相同，所有结构、Canvas、私有回执、切片和可见使用验收继续失败关闭。
-- 验证：先断言 Supervisor 决策前零 child、固定关键词不会预完成节点，再覆盖完整复用、仅缺图集和明确重做。还要直接经过父完成门，证明合法持久路由不再出现 art baseline gap，并证明删除切片后覆盖合同拒绝复用；旧 root、错误 fingerprint、虚构或遗漏缺口和重复改写路由都应失败关闭。
+- 处理：关键词和资产探测只作为 Supervisor 的 advisory context，不能直接修改 Graph。根 Run 先以 `audit-existing-first` 持久化用户 intent；即使用户提出整体视觉重做，这也不授权强制重生成。决策后只启动 `code-prototype`，由它在成功 `asset.list` 后提交或建立权威覆盖/缺口 delivery。Runtime 验证合同后才允许已有资产复用，或只打开精确缺口 owner；根完成门继续要求主 Agent 认领回执并完成接入、Canvas、私有回执、切片、可见使用和试玩验收。
+- 验证：先断言 Supervisor 决策前零 child、固定关键词不会预完成节点，再覆盖完整复用、仅缺图集和明确重做。还要直接经过父完成门，证明合法持久 route/delivery 不再出现 art baseline gap，并证明删除切片后覆盖合同拒绝复用；旧 root、错误 fingerprint、虚构或遗漏缺口、重复委派以及 child 写入 `game/**` 都应失败关闭。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`。
 
+## 单主 Graph 升级不能只迁移 sidecar，必须同时处理活跃旧 Run
+
+- 现象：v1 decision/route 能迁移，但升级前正在运行的 `code-prototype` 因 prompt 文本变化被 scheduler 判为身份冲突；同时旧 fixed-graph 的 `art-director / art-asset-plan` 仍持有 scheduler binding，可以脱离新主 Agent 继续生图。
+- 原因：迁移测试只手工构造了非确定性主 Run，未经过真实 ready scheduler；资源 route 的迁移也没有自动让已启动的旧责任链失效。硬截止处理若仍只接受根的直接 child，还会把新的嵌套美术 child 留在 running，而丢失 reconciliation 投影。
+- 处理：确定性主 Run 只白名单兼容已知 canonical task 文本版本，所有其它身份字段继续精确校验；旧 fixed-graph 美术 child 及沿 isolated instance 父链可证的历史后代在计划和所有非只读工具入口失败关闭，只允许当前 `code-prototype` 经 `asset.list` 后重新委派。新美术 child 同样使用显式只读白名单，写工具只允许可证明落在 `assets/**` 的文件/patchset 与 `canvas.asset_generate`，不能借 `memory.write` 或 `task.create/update` 修改 memory 和 manifest；会认领 delivery 并写 observed 状态的 `agent.run_status` 也不是只读。绝对硬截止显式验证根、主 Agent、delegated art child 的完整 task/binding/delegation 链。
+- 验证：用真实 scheduler 恢复确定性 v1 主 Run；把旧 scheduler 美术 child 置为 running，断言 `canvas.asset_generate`、`memory.write`、`task.create`、`task.update` 和 `agent.run_status` 均被拒绝；再持久化其历史 `game/**` writeScope isolated 后代，断言恢复执行写操作仍失败且项目未变。对当前合法美术 child 同样验证 memory/manifest 零写入，再让它带在途外部生成命中硬截止，断言状态进入 `needs-reconciliation` 且 pending/batch/外部生成账本原样保留。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs`、`runtime_driver/game_chat_fast_path.rs`、`runtime_driver/main_loop.rs`、`runtime_tools/file_ops.rs`。
+
 ## 执行锁移交给未确认启动的异步 future 会制造永久 queued
 
 - 现象：父 Supervisor 与 Runner 一直显示运行中、heartbeat 正常，专业 Agent 已有 `background_task.queued` 和 `autonomous_ready_task.scheduled`，对应执行锁也被 Runner 持有，但该 child 永远没有 running journal、`turn.started` 或后续 Runtime event；其它同批 Agent 可能已经完成。
@@ -126,6 +142,7 @@
 - 处理：旧 action 继续禁止重放或伪造 observation；旧 child 与父 Run 先真实终态。新 Supervisor continuation 仅扫描同 Session、同 source、同有效任务合同的历史根 Run，并要求对应 ready-task 同时存在 `failed / needs-reconciliation` 记录、最终 `cancelled` 记录和 durable cancel tombstone，才把当前 manifest 的同一 failed 节点恢复为 pending，让 scheduler 创建新 child Run。manifest 的读取、筛选、child 证据重验和写回放在同一项目写锁内；每个 task journal 只读取一次并按 parent Run 建索引。较新的无 child Run 默认阻断旧凭证，只有其 root journal 精确证明为旧 failed Graph 在进入 scheduler 前即失败时才允许向前查找；scheduler 自身失败不得被当成该兼容场景。
 - 验证：构造 reconciliation child、人工 cancel tombstone、failed manifest 和终态父 Run，证明同源 continuation 只重排该节点；并列普通 failed 节点保持 failed，完成合同继续继承原任务 SHA 与项目 baseline，旧 pending action 不恢复。追加覆盖“旧 failed Graph 未调度”的中间 Run 可以跨过，而较新的 scheduler failure 即使没有 child journal 也会阻断更老 tombstone。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs`。
+
 ## `timeout_at` 不能替代显式的预算耗尽预检
 
 - 现象：给完美像素加端点级并发闸后，预算已经耗尽的请求仍然能拿到许可，白占一个名额继续去打几轮全账号 SpacetimeDB 扫描，直到下载那步才失败。
@@ -141,6 +158,7 @@
 - 处理：把递增封进一个 guard 结构体，递减放在它的 `Drop` 实现里；递增本身用 `fetch_update` 的 CAS，不能用「先读后加」——两个线程同时读到 `max - 1` 各自加一就会越界。拿到资源后立即 `drop(guard)` 让出队列名额，不要让它跟着许可一起活到请求结束。
 - 验证：单测覆盖 CAS 边界（满了返回失败且计数不越界、上限为 0 时任何进入都失败），并由独立用例覆盖 guard 离开作用域后的计数归还。预算耗尽路径只断言 `504`，不得通过另一个测试也会修改的进程级 static before/after 来推断“未入队”，也不得用串行锁或 `--test-threads=1` 掩盖隔离问题。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`（`try_enter_bounded_queue`、`EditorPixelArtSnapQueueGuard`）。
+
 ## Linux 生产脚本门禁不能假设本地也是 GNU userland
 
 - 现象：macOS 本地运行维护页、生产 API 部署和 Rust 产物门禁时，依次出现 `mv: illegal option -- T`、`mapfile: command not found`、`/usr/bin/cp` / `/usr/bin/chmod` 不存在，以及 `.rlib` 明明含有 `.o` 却报告“没有可扫描成员”；安全修复计划还会把 `/var/folders` 到 `/private/var/folders` 的系统别名误判为用户符号链接。
@@ -330,7 +348,7 @@
 
 - 现象：测试点击“添加素材”后，图层状态已经写入，但立即用 `getByAltText('画布图片：...')` 偶发或稳定找不到图片；前一张图可能通过，紧接着添加的第二张失败。
 - 原因：带 `objectKey` 的画布图片通过 `useResolvedAssetReadUrl` 异步获取签名 URL，`resolvedUrl` 就绪前不会渲染带 `alt` 的 `<img>`。`user.click` 只等待点击交互完成，不等待 effect 内的换签 Promise；前一张图在后续操作期间出现只是调度时机，不是同步契约。
-- 处理：每次点击添加后分别用 `await screen.findByAltText(...)` 等待对应图片可见，再执行依赖该图层的下一步操作；不要用固定 sleep，也不要只等待最后一张图而让前面的断言依赖偶然调度。
+- 处理：每次点击添加后分别用 `await screen.findByAltText(...)` 等待对应图片可见，再执行依赖该图层的下一步操作；不要用固定 sleep，也不要只等待最后一张图而让前面的断言依赖偶然调度。完整前端回归并行负载较高时，可只对明确跨越换签 Promise 的目标查询设置局部、有界的 `5_000ms` 超时，不要放宽 Testing Library 全局超时。
 - 验证：先精确运行目标用例并连续重复，再运行所在测试文件和完整前端测试；删除场景仍要保留 A/B 都消失、两个删除调用和撤销不恢复已删除素材的断言。
 - 关联：`src/hooks/useResolvedAssetReadUrl.ts`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx`。
 
@@ -342,6 +360,14 @@
 - 验证：`ImageCanvasEditorModel.test.ts` 覆盖素材库 source resource 保留，`useImageCanvasAssetCanvasBridge.test.tsx` 覆盖资源 ID 级联清理，`ImageCanvasEditorAssetsIntegration.test.tsx` 覆盖删除后保存的新 layout 不再包含被删图层。
 - 关联：`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/useImageCanvasAssetCanvasBridge.ts`、`src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx`。
 
+## 图片画布素材选择有效性不要绑定搜索与折叠可见性
+
+- 现象：批量选择多个素材后，搜索、折叠文件夹或展开文件夹会让已选数量下降、Shift 范围锚点丢失，后续批量下载或删除遗漏此前已选素材。
+- 原因：搜索结果和文件夹展开状态只描述当前 UI 可见范围，不描述素材是否仍然有效；用 `visibleAssetIds` reconcile 全局选择会把暂时隐藏误判为素材失效。
+- 处理：由唯一 `useImageCanvasAssetSelection` 持有选择集合、范围锚点、框选和全部选择 mutation；全局选择只按全部 `selectableAssetIds` 清理真正删除、上传未完成、上传失败或媒体地址无效的 ID。`visibleAssetIds` 只作为单项切换、Shift 可见区间和当前结果全选 / 取消全选的动作入参，批量下载与删除消费 hook 输出的完整 `selectedAssets`；删除中包含当前未显示选择时，必须明确展示全部数量和未显示数量并二次确认。
+- 验证：模型测试覆盖隐藏选择保留、可见范围增量和真正失效 ID 清理；图片画布素材集成测试覆盖搜索、折叠 / 展开后选中数量稳定及当前可见全选不影响隐藏选择。
+- 关联：`src/components/image-editor/useImageCanvasAssetSelection.ts`、`src/components/image-editor/useImageCanvasAssetLibrary.ts`、`src/components/image-editor/ImageCanvasSidebarView.tsx`、`src/components/image-editor/ImageCanvasEditorView.tsx`。
+
 ## 后台素材查询不要用 SQL 直查 editor_asset
 
 - 现象：后台“素材查询”报 `HTTP 400：no such table: editor_asset. If the table exists, it may be marked private.`。
@@ -399,6 +425,14 @@
 - 验证：画板生成 workflow 测试覆盖 queueState 持续 `running` 到前端等待窗口结束时，不进入 failed、不显示该排队文案、不添加本地临时结果层。
 - 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`。
 
+## 场景队列终态不保证首次项目快照已经收口生成占位
+
+- 现象：游戏场景任务已经显示完成，但画布仍保留 `generating` 占位；场景链路又禁止用本地结果补层，因此当前会话可能一直停在生成中。
+- 原因：外部生成任务终态与项目画布投影不是同一个原子观测点。队列轮询先看到 `completed` 后，紧接着的首次项目 GET 仍可能读到同一 `dialogId` 的未收口占位；若调用统一回读函数时没有传 completion dialog ID，函数无法识别该快照仍未完成，也不会执行已有的有界延迟重读。
+- 处理：游戏场景队列调用要把本次占位 `dialogId` 传给 `applyQueuedEditorGenerationProject`。首个快照中该 ID 仍为 unresolved 时，只按既有间隔补读一次项目；不追加本地图层，也不把任务终态直接等同于画布投影终态。其他生成类型若要补同类保护，必须分别复现其权威回填时序后再改，不能用本条场景结论替代验证。
+- 验证：场景 workflow 用两个连续快照复现时序：第一个保留 `scene / generating`，第二个包含场景结果并把同一占位置为 `idle`。修复前只读一次并超时，修复后依次应用两个权威快照。
+- 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`、`docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md`。
+
 ## 图片画布历史不能回退当前权威状态或复活后端已删素材
 
 - 现象：生成占位框移动后开始生成，撤销移动会把仍在运行的生成对象恢复成待生成状态；切换到 2K 或改变比例后撤销位置，旧占位框还可能把当前尺寸回退。上传图层落库后，普通移动撤销可能被提示“可能会使图片消失”并永久卡在栈顶；即使安全检查已放行，直接恢复旧图层快照也会丢失刚回填的资源关联。素材库后端删除关联素材后，更早的移动快照还可能把已删图层重新加入并自动保存；修改素材类型虽然界面提示撤销成功，刷新后却可能从仍指向新类型的 resource 回弹。无稳定 ID 的“修改图片”草稿也可能被 target-null 快照直接关闭。
@@ -411,7 +445,7 @@
 
 - 现象：画板生成、快速编辑、图标素材或 UI 素材提取如果允许直接提交 generated objectKey，用户只要知道其他账号的私有 objectKey，就可能让 api-server 签名读取并送给外部生成供应商。
 - 原因：Data URL/Blob URL 只允许停留在浏览器临时态，正式编辑器引用必须先上传并经统一 resolver 校验归属。
-- 处理：所有私有对象引用在读取字节或签发 URL 前统一走 `resolve_editor_reference_object_key_for_owner(state, owner_user_id, source)`，先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key。只有确实需要图片字节的入口（生成 / 重绘 / 图标 / UI 提取等交给 provider 的路径）再走 `parse_editor_reference_image`（内部仍先 resolve，再下载 OSS 字节）；手动去背景等只签发短期 URL 的入口不要 `parse` 整图。手动去背景还要恢复源模型时，object key 解析、所有权校验和源模型回溯必须复用同一轮账号项目 / 素材快照，项目与素材快照各最多读取一次；不得先走通用 resolver 全量读取，再为模型回溯重复拉取完整画布和素材库。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
+- 处理：普通图片、重绘、图标图集附加参考图和 UI 提取等允许 objectKey 的私有对象引用，在读取字节或签发 URL 前统一走 `resolve_editor_reference_object_key_for_owner(state, owner_user_id, source)`，先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key。只有确实需要图片字节的入口再走 `parse_editor_reference_image`（内部仍先 resolve，再下载 OSS 字节）；手动去背景等只签发短期 URL 的入口不要 `parse` 整图。图标规范生成的可选参考图与图标图集的主规范引用是更窄的业务契约：只接受正式 `referenceId`（项目资源 ID / 素材 ID），不得回退 objectKey、URL 或临时 key；图标图集的额外 `referenceImageSrcs` 才继续沿用通用 owned objectKey 规则。手动去背景还要恢复源模型时，object key 解析、所有权校验和源模型回溯必须复用同一轮账号项目 / 素材快照，项目与素材快照各最多读取一次；不得先走通用 resolver 全量读取，再为模型回溯重复拉取完整画布和素材库。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
 - 验证：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_reference`，并用前端 workflow 测试覆盖 `referenceImageSrcs` 进入图标生成请求；若快速编辑重开额外参考图，再补对应请求覆盖。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-client/src/assets.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`。
 
@@ -568,6 +602,14 @@
 - 验证：`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`；`cargo test -p api-server inline_data_url --manifest-path server-rs/Cargo.toml`。
 - 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/api-server/src/editor_generation_queue.rs`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
+## 专用生成契约不能被通用生成接口和任务摘要绕过
+
+- 现象：专用场景接口要求结构化 `sceneContent + stylePreset`，但调用方仍可向通用图片接口传 `kind = scene` 或 `assetKind = scene`，用任意完整 Prompt 生成并持久化正式场景；合法场景入队后，任务侧栏还可能显示后端完整规则文本和通用“生成图片”标题，空白素材名则可能回退成完整 Prompt。
+- 原因：专用 handler 内部复用了通用图片 payload、队列和 Worker，但公开通用 HTTP handler 没有限制专用身份；任务摘要又无条件优先提取 payload 顶层 `prompt`，素材名默认值只处理了字段省略，没有处理空白字符串。
+- 处理：公开通用 handler 拒绝专用 `kind / assetKind`，专用 handler 仍可直接调用内部共享执行函数；队列投影按 `kind = scene` 从权威 `generationInputs.fields[画面内容]` 派生标题和摘要，缺字段时失败关闭而不是回退内部 Prompt，并重新计算历史缓存；专用素材名统一把省略和空白收口为产品默认值。
+- 验证：路由测试先证明旁路会越过 HTTP 边界，再断言两种旁路均返回 `400` 且指向专用端点；摘要测试覆盖新任务、历史错误缓存和缺少画面内容三种情况；标签测试覆盖省略、空白、自定义和 80 字上限。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-module/src/external_generation.rs`、`docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md`。
+
 ## 图片编辑器角色动画必须提交稳定图片引用
 
 - 现象：图片编辑器里对尚未上传的角色图点击 `生成动画` 后，前端或后端返回 `sourceImageSrc 必须先上传 OSS`。
@@ -2306,6 +2348,14 @@
 - 验证：deploy 工作区应直接出现 `build/<version>/web.tar.gz` 与 `web.tar.gz.sha256`；后续仍由 `scripts/deploy/production-web-deploy.sh` 执行 checksum 校验和解压 smoke。
 - 关联：`jenkins/Jenkinsfile.production-web-deploy`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## Copy Artifact Production 模式下来源 Job 必须显式授权
+
+- 现象：Deploy / Publish / Import 在 `copyArtifacts` 立即报 `Unable to find project for artifact copy: <job>`，但 Jenkins 中的来源 Job、指定构建号和归档产物都存在。
+- 原因：Copy Artifact 已启用推荐的 `Production` 模式，但产物生产者的 Jenkinsfile 没有 `copyArtifactPermission`；插件会把权限不足伪装成“找不到项目”。
+- 处理：在产物生产者的 Declarative Pipeline `options` 内精确授权固定消费者：Stdb Build 授权 Stdb Publish，API Build 授权 API Deploy，Web Build 授权 Web Deploy，Database Export 授权 Database Import。不使用 `*`，不通过全局 `Job/Read` 扩权，不把插件退回 Migration 模式规避。
+- 验证：运行 `npm run check:production-ops`；上线后先运行一次四个产物生产者中本次需要的 Job，确认 live `config.xml` 出现 `CopyArtifactPermissionProperty`，再重跑消费者。
+- 关联：`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-web-build`、`jenkins/Jenkinsfile.production-database-export`、`scripts/check-production-ops-guardrails.mjs`。
+
 ## Jenkins 生产流水线拉 Git 统一走本机 SSH
 
 - 后续更新：2026-07-14 起所有生产 Job 的 `Pipeline script from SCM` 和 Jenkinsfile 内部 checkout 统一使用本机 SSH 地址 `ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git` 与凭据 `genarrative-local-gitea-ssh`，不再保留局域网 IP、HTTP 内网地址或公网 fallback。
@@ -4010,7 +4060,7 @@
 ## 画布 Agent 的规划请求不能关闭瞬时失败重试
 
 - 现象：美术 Agent 对话返回红色错误气泡 `completion error: LLM 请求超时，累计尝试 1 次`；HTTP 本身仍返回 200，前端 20 分钟 transport timeout 没有触发。
-- 原因：规划请求虽然有 Agent 专用单次 timeout，但 `editor_agent_llm_client` 把 `max_retries` 硬编码为 0；VectorEngine `gpt-5.4-mini` 的偶发长尾、连接超时或可重试上游状态会在第一次失败后直接持久化成 system error。framework 的英文 `completion error` 前缀也被原样暴露给用户。
+- 原因：规划请求虽然有 Agent 专用单次 timeout，但 `vector_engine_llm_client` 把 `max_retries` 硬编码为 0；VectorEngine `gpt-5.4-mini` 的偶发长尾、连接超时或可重试上游状态会在第一次失败后直接持久化成 system error。framework 的英文 `completion error` 前缀也被原样暴露给用户。
 - 处理：120 秒改为前端软提示阈值：POST 仍 pending 时显示不入库的“仍在处理中，请耐心等待”；provider 明确断开/失败才写正式错误。专用 provider 单 attempt 使用 8 分钟 hard timeout，请求发起阶段读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次且重试退避最多 60 秒。不要只计算单次 complete 的最坏时间：runner 还可因非法 JSON/工具校验失败进入后续轮次，必须从 handler 入口开始计算 18 分钟总 deadline，进入 `agent.prompt(...)` 时扣除会话锁/上下文准备已用时间，为持久化和前端 20 分钟 timeout 留出余量。响应头后的体读取/解析错误按明确失败收口，必须使用真实 attempt 计数；规划、配置和定价错误对用户统一为中文，原始诊断只记后端日志。重试发生在任何生成工具执行前，不会重复提交生成任务或扣费，不要通过提高前端 timeout 或 runner `max_turns` 掩盖 provider 重试缺失。
 - 验证：`platform-editor-agent` 测试锁定 8 分钟 hard timeout 与中文错误；前端 fake timer 用例锁定 120 秒前只显示思考动画、到点后显示耐心等待、成功/失败后移除；`platform-llm` 回归用例锁定第二次 attempt 成功响应头后的 body timeout 仍报累计 2 次；`api-server` 测试锁定专用 client retry、18 分钟整体 deadline 与中文直达错误。运行态排障按同一 request id 对齐 `platform_llm` failure stage 与 `/messages` 总耗时，并确认仍 pending 的请求不再在 120 秒形成错误气泡。
 - 关联：`server-rs/crates/platform-editor-agent/src/agent/agent.rs`、`server-rs/crates/platform-agent-harness/src/error.rs`、`server-rs/crates/api-server/src/state.rs`、`src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts`、`src/components/image-editor/EditorAgentConversation/MessageBubble.tsx`、`src/services/image-editor/editorAgentClient.ts`。
@@ -4056,11 +4106,18 @@
 
 - 现象：`Repository checks`、`Frontend tests`、`Backend tests` 和 `Native shell tests` 都从全新 job 容器开始，apt、setup-node、rustup 和原生系统库在不同 job 里重复安装；后端与原生壳的安装时间可达数分钟，并把软件源和代理瞬时失败放大为四份。
 - 原因：Gitea Actions job 彼此隔离，上一个 job 在容器内安装的包不会自动进入下一个 job；把同一套不随 PR 变化的工具链写在 workflow step 中，必然每次重做。
-- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、Rust 1.96、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热根 npm、server-rs 与桌面壳 Cargo 下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
+- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、Rust 1.96、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热根与 AI 游戏创作壳 npm、server-rs、桌面壳与 AI 游戏创作壳 Cargo 下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查五份缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
 - 依赖边界：每个 job 仍必须各自执行 `npm ci`，让当前 lockfile 和 PR 依赖在干净环境中验证；区别是命中镜像 cache 时只做本地解包，锁新增依赖时才走受控网络。不要把 `node_modules` 或 Cargo `target` 烘进镜像，也不要向不受信任 PR 挂载跨 job 可写 cache。
-- 锁漂移边界：runtime 校验输出 `server_rust_cache_lock=partial` 说明镜像内 Cargo lock 与当前 checkout 不同，不代表新增 crate 已经缓存。必须在新镜像中以 `--network none` 对当前 lock 执行真实 `cargo fetch/build --offline`；`cargo metadata --no-deps` 不会证明依赖 archive 可用，不能作为替代。
+- 锁漂移边界：runtime 校验输出任一 `*_cache_lock=partial` 说明镜像内 lock 与当前 checkout 不同，不代表新增依赖已经缓存；必须同时输出 Actions warning，提示可信分支落地后刷新镜像。必须在新镜像中对 server-rs、桌面壳和 AI 游戏创作壳当前 lock 执行真实 `cargo fetch --locked --offline`；`cargo metadata --no-deps` 不会证明依赖 archive 可用，不能作为替代。
 - 构建网络边界：`CARGO_NET_RETRY` 只覆盖部分 crate 下载，registry `config.json` / index TLS 握手仍可能直接终止整次 fetch。Dockerfile 对每个 `cargo fetch --locked` 再做最多 5 次整命令级有界重试，最终仍执行断网 fetch，不能降低为无锁重试或省略离线闭合验证。
-- 验证：workflow 不再出现 GitHub checkout action、apt、setup-node 或 rustup 安装 step；镜像在 `--network none` 下能按当前 npm / Cargo lock 完成依赖准备，四个 job 的环境校验、干净 `npm ci` 和原有测试门禁仍全部执行。
+- 验证：workflow 不再出现 GitHub checkout action、apt、setup-node 或 rustup 安装 step；镜像能按五份当前 lock 完成缓存闭合，四个 job 的环境校验、经 3 次整命令级有界重试保护的干净 `npm ci` 和原有测试门禁仍全部执行。
+
+## Gitea Actions HTTPS CONNECT 隧道必须双向收束 socket（2026-08-07）
+
+- 现象：CI 的 `npm ci` 高频出现 `ECONNRESET / network aborted`，Cargo 则出现 crates.io TLS EOF、连接超时或下载失败；同一出口 gateway 容器看似健康，却累计自动重启数百次，日志反复出现 `Socket.ondata -> Writable.write -> write EPIPE -> Unhandled 'error' event`。
+- 原因：HTTPS CONNECT 建立后使用 `upstreamSocket.pipe(clientSocket)` 与反向 pipe，但只监听 upstream `error`；客户端在 DNS 等待、下载或 job 清理期间关闭连接时，pipe 继续向已断开的 client socket 写入，未处理的 EPIPE 会让 Node 进程退出。`unless-stopped` 自动拉起和浅层 healthcheck 会掩盖崩溃，所有并发 npm / Cargo 隧道同时被 reset。
+- 处理：CONNECT 一开始就为 client socket 注册 `error / close`，解析完成后为 upstream socket注册同样的双向销毁处理；DNS 返回、写 200 和开始 pipe 前都检查 client 是否已销毁。任一端 error、close 或 timeout 都幂等 destroy 两端，不把普通客户端 reset 写成错误日志。不要用进程级 `uncaughtException` 吞掉问题，也不要只增加 npm/Cargo 重试掩盖 gateway 崩溃。
+- 验证：在独立 canary 和正式 gateway 上分别并发制造至少 500 次“CONNECT 后立即断开”，随后确认容器仍运行、restart count 不增加、日志无 EPIPE；再通过同一 proxy 对 npm registry 与 crates index 建立完整 TLS 隧道。切换前仍须确认 Gitea 无活跃 run 且 Runner 内层无 job 容器。
 
 ## Gitea CI 预构建镜像不能只靠 tag 判断内容
 
@@ -4114,7 +4171,6 @@
 
 - 现象：延迟重试携带比既有行更旧的调用方时间，回填图片序列字段时若无条件写入，会使 `updated_at` 倒退，导致基于时间戳的同步看不到更新或排序错误。
 - 处理：同源图片序列字段只允许 `None → Some`，非空冲突失败关闭；发生回填时 `updated_at = max(existing.updated_at, request_timestamp)`。legacy 音频 repair 不派生资源级图片序列或通用时长，重放继续精确匹配。
-
 ## 历史钱包消费不能从最近流水或通用订单快照推算
 
 - 现象：后台用户详情要展示累计花费时，直接复用只返回最近 50 条的 `list_profile_wallet_ledger`，或在充值订单每行使用的通用钱包快照里扫描该用户全部流水。
@@ -4221,13 +4277,21 @@
 - 验证：覆盖失败根任务“水晶俄罗斯方块”后输入“继续”、连续 successor、跨 Session、跨 source、正常完成后新输入、带具体新需求、既有非占位入口先 patch 后 smoke、初始化占位的俄罗斯方块真实语义、未知玩法失败关闭、纯继续目标缺失、规范图不在运行 DOM/Canvas、真实动作前后 `sequence` 与 RAF 空转。浏览器验收必须同时比较 baseline 玩法关键文本/控件/状态和当前 revision，不能只看 Canvas 非空与三个固定按钮。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_request_builders.rs`。
 
+## game-chat 的固定图不能替代主 Agent 对已有美术的理解（2026-08-07）
+
+- 现象：用户要求把已有美术资源接入游戏时，固定 `code-director -> art-director / art-asset-plan -> code-prototype` 图会在缺少主 Agent 审计的情况下启动美术生成，或把“整体重做”错误实现为无条件生图；美术完成后又换了 Run，代码接入、静态检查和试玩无法形成连续责任链。
+- 原因：固定节点把“是否需要美术”的语义判断编码为 Runtime 前置流程，`code-director` 成为另一个主控，而不是让真正接入游戏的 `code-prototype` 基于权威资产事实决策；如果再把固定审计策略塞进用户意图字段，Supervisor 的理解也会被 Runtime 规则覆盖。两个素材槽都缺失时若先消耗不可重试的 `art-asset-plan` 委派，其 child 又必然因缺规范图失败，整个 Run 会进入无法补救的死路。
+- 处理：Supervisor 用 `intentSummary` 持久化自己对用户意图的理解，固定 `audit-existing-first` 只作安全执行策略，随后只启动 `code-prototype`。主 Agent 先 `asset.list`，完整覆盖就直接使用；仅在事实证明缺少规范图或核心图集时，才建立一个写入范围受限为 `assets/**` 的美术 durable delivery。两槽都缺失时必须先完成并认领 `art-director` 的 `EvidenceReady` delivery，再委派 `art-asset-plan`；回执返回同一主 Run 后再接入素材、原玩法语义检查、静态检查和双视口试玩。读取旧 v1 决策时必须复核其旧 fingerprint，并从完成合同绑定的有效任务迁移 intent；旧 `code-director` coverage/route 只能触发当前主 Agent 重新审计和原位替换，不能直接成为新完成证据。整体视觉重做意图同样必须经过这次审计，不能成为绕过资产复用或强制重生成的固定规则。完整 GUI / CLI DAG 不使用该例外。
+- 验证：正反向测试同时证明 `intentSummary` 非空且不被固定策略代替、v1 决策与旧 route 同根恢复、完整资产零委派、真实缺口精确委派、两槽缺失时规范图优先、单个活跃 child、`game/**` 写拒绝、`assets/**` 写允许、回执恢复同一主 Run 和最终主 Agent 自验收；不能只凭 Prompt 出现关键词或 manifest 状态投影判通过。
+
 ## Tauri beforeDevCommand 失败不等于已启动客户端会自动退出（2026-08-03）
 
 - 现象：旧 worktree 的 AGC Vite 长期占用 `127.0.0.1:3080`，marker 仍指向旧 API；新 worktree 启动 game-chat 后，配套后端在新端口 ready，随后 `beforeDevCommand` 因代理 target 不匹配返回非零，终端已经回到提示符，但原生客户端和它启动的 Runner 仍存活。客户端 WebView 实际加载旧 Vite，因此当前 master 的界面优化看起来全部缺失。
 - 原因：Tauri 的字符串 `beforeDevCommand` 默认 `wait=false`。只要固定 `devUrl` 上已有可访问页面，Tauri CLI 可以在配套启动脚本完成前创建原生窗口；旧实现又直接从 npm 启动 Tauri CLI，没有在 CLI leader 退出后继续持有其 PGID / Windows 进程树。`start-dev-stack.mjs` 虽会在后端 ready 后识别 marker/API 错配，但检查时机已经晚于窗口创建，且只清理自己登记的后端和 Vite。
 - 处理：`dev` 与 `game-chat` 统一先进入 `start-tauri-dev.mjs`，在启动 Tauri CLI 前无副作用检查 3080。现有 marker 只有 API target，不能证明监听器属于当前 worktree，因此任何已存在的 3080 都失败关闭，不主动杀不能证明归属的旧服务，也不因 target 看似匹配而复用。Tauri CLI 使用独立 POSIX 进程组，任意退出后按负 PGID 先 TERM、有界等待、再 KILL；Windows 固定调用 `taskkill /PID <pid> /T /F`。`start-dev-stack.mjs` 自己的后端 / Vite 独立组也在返回前有界收束。
+- 2026-08-08 后续统一：上述 `3080` 是事故发生时的历史实现，不再是当前 Linux 启动口径。AGC Vite 已纳入系统级用户端口段，首选 `start + 5`，占用时只在本用户段内漂移；外层启动器把最终端口写入 Tauri CLI 动态 `build.devUrl` 和子进程 `GENARRATIVE_AGC_VITE_PORT`，并用 Vite CLI `--port` 启动严格监听。`beforeDevCommand`、配套后端预留、WebView 与 Vite `strictPort` 必须使用同一值。Windows / macOS 仅把 `3080` 保留为兼容首选并允许统一漂移。未知归属监听器仍不得复用或主动终止，但其它用户固定 `3080` 不再阻塞 Linux 当前用户启动。
 - Linux 容器边界：最小化 CI 容器的 PID 1 可能不回收孤儿后代，进程组在所有可执行成员退出后仍只剩 `Z` 僵尸；此时 `kill(-pgid, 0)` 仍成功，不能据此把已经完成的收束误报为失败。Linux 等待逻辑在 signal 探活后必须核对 `/proc/<pid>/stat`，只把同 PGID 的非 `Z / X` 成员视为存活；`/proc` 不可读时继续使用原保守判断，macOS 等其它 POSIX 平台仍只走 signal 探活。
-- 验证：定向测试必须覆盖旧 marker target 在 CLI spawn 前被拒绝、target 看似匹配仍拒绝无归属 Vite、非 HTTP 3080 失败、预检调用顺序、CLI leader 先退出后同 PGID 客户端仍收到 TERM、忽略 TERM 时升级 KILL，以及 Windows taskkill 的 `/PID /T /F` 参数。人工复验旧 worktree 占用 3080 时，新命令不得启动后端或弹出新窗口；正常启动后退出，确认 Tauri 客户端、Runner 和本轮自有后端 / Vite 均按生命周期收束。
+- 验证：定向测试必须覆盖用户段 `start + 5` 映射、同段占用漂移、父子启动器严格复用最终端口、动态 Tauri `--config`、marker 与预检地址一致、未知归属监听器拒绝复用、CLI leader 先退出后同 PGID 客户端仍收到 TERM、忽略 TERM 时升级 KILL，以及 Windows taskkill 的 `/PID /T /F` 参数。正常启动后退出，确认 Tauri 客户端、Runner 和本轮自有后端 / Vite 均按生命周期收束。
 - 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`、`apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts`、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts`。
 
 ## game-chat 快车道首波与已提交回复不能被后续 revision 破坏（2026-08-03）
@@ -4237,6 +4301,7 @@
 - 处理：从当前 root source 的 seed lane 动态解析全部零依赖首波任务，只对这些 child 容忍 hydration `Pending`，后续 code prototype / preview 仍严格要求 Running/Completed。`streaming / ready` 仍要求当前 revision，`committed` 回复改为依据 finalization 的稳定身份查询，不随后续项目 revision 失效。
 - 验证：覆盖 `design-director / art-director / code-director` 三个 Pending 首波 child 均可投影 Completed、`code-prototype` Pending 仍被拒绝；非流式专业 Agent 在 finalization 前无 stream，提交后形成 committed stream，再推进项目 revision 后仍可查询且正文不变。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/response_stream.rs`。
+
 ## 异步生成结果未知时不能换幂等键重提（2026-07-31）
 
 - 现象：生成提交发生客户端超时、连接中断或响应丢失后，调用方创建新的 `Idempotency-Key` 再提交一次；原任务其实已经入队，最终造成重复生成、重复扣费和重复画布 / 素材库写入。
@@ -4248,6 +4313,13 @@
 - 验证：覆盖“服务端已入队但提交响应丢失”后两次 POST 的 endpoint、正文 bytes 与 `Idempotency-Key` 完全相同，原键重试仍返回同一 operation，最终只出现一份 completed result 和一次计费 / 写回；恢复再次 transport 失败或临时鉴权失败仍保留同一账本；换 owner 不可见；MCP 与 REST 对同一 owner、同一请求和同一键必须命中同一 operation。
 - 关联：`server-rs/crates/api-server/src/external_generation.rs`、`server-rs/crates/api-server/src/external_mcp.rs`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
 
+## MCP 列表不能透传完整项目快照（2026-08-07）
+
+- 现象：账号项目数量增长后，`list_editor_projects` 把每个项目的 `canvas / layers / resources` 全量透传，REST 响应超过 MCP 4 MiB 上限，Agent 因整批失败而无法展示、查重或安全选择项目；缺少必填请求体时，内部 Axum JSON extractor 的文本 `415` 又会被泛化成“非 JSON 响应”。
+- 处理：项目列表 REST 保持默认 `view=full` 兼容，并提供 `view=summary`；MCP 固定使用 summary 且不向 Agent 暴露或接受 `view=full`。摘要只返回 `projectId / title / updatedAt / cover`，封面取最新且存在稳定 `objectKey` 的 `project-cover-snapshot`，展示时再调用 `/assets/read-url`，不在列表内嵌图片或签名 URL。MCP 在构造内部 REST 请求前按 OpenAPI schema 校验 required body；缺正文和缺字段分别返回结构化错误，不进入写入、上传票据或计费路径。
+- 验证：用 19 个完整序列化后超过 4 MiB 的项目 fixture 证明摘要仍低于上限且不含大型布局；覆盖四个历史 `415` 工具的缺正文、空对象和非对象输入，并断言项目列表工具固定 summary、调用方不能通过 query 覆盖。
+- 关联：`server-rs/crates/api-server/src/external_mcp.rs`、`server-rs/crates/api-server/src/external_editor_api.rs`、`docs/openapi/genarrative-external-v1.openapi.json`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
+
 ## api-server 嵌入仓库外资源时必须同步容器构建上下文（2026-07-31）
 
 - 现象：本地 `cargo test` 可以编译 MCP 与 Skill 下载模块，但 api-server 镜像在 Rust 编译阶段报 `include_str!` 找不到 OpenAPI 或 Skill 文件。
@@ -4281,12 +4353,26 @@
 - 处理：调用方在未认证时不得启动受保护的钱包刷新；可取消的读取要为每轮分配 `AbortController`，新读取先失效并中止旧读取，组件卸载时同时推进 revision、abort 当前请求并清空句柄。所有 `then / catch / finally` 在更新状态前都要检查 signal 与 revision。
 - 验证：定向测试覆盖卸载后请求 signal 已中止；同时复跑触发钱包刷新回调的画布生成集成测试和完整前端测试，不能以单文件偶然快速收束代替全量验证。
 
+## 账号级轮询和并发 bootstrap 必须中止整条旧生命周期（2026-08-06）
+
+- 现象：任务列表 `Promise.all` 一侧失败后，另一侧请求可能跨过重试和卸载继续悬挂；微信充值第一次确认返回 pending 后切换账号，旧订单的延迟重试可能使用新账号 Token 再次请求，401 路径还会影响新账号登录态。
+- 原因：只用 React state 或最终回调里的 owner 判断，无法阻止已安排的 timer、下一次 HTTP 请求和同轮未完成分支继续执行；每轮重试覆盖单个 controller ref，也会遗失更早的悬挂请求。
+- 处理：并发 bootstrap 每次 attempt 使用独立 `AbortController`，任一分支失败时先中止同轮 controller 再安排有界重试，卸载时中止当前 attempt。充值订单从创建成功起持有同一个 owner、账号 revision 和 `AbortController`；每次 delay、confirm 和 SSE watch 前后都校验生命周期，并把同一 signal 传到请求层；账号切换和卸载先 abort，再清理 ref、state 与旧支付回调 hash。
+- 验证：bootstrap 用例覆盖“一侧 reject、另一侧 pending、重试后卸载”，并断言每轮 signal 都已中止；充值用 fake timer 证明首次确认 pending 后切换账号会中止 signal，推进全部退避时间也不会产生第二个确认请求或清理新账号 Token。
+
+## 中止 refresh 等待不等于隔离 token 发布（2026-08-07）
+
+- 现象：A 账号的写请求 401 后开始共享 refresh，随后切换到 B。A 的 `AbortSignal` 虽然让业务请求立即结束且不再重放 POST，但底层 refresh 为了其它共享等待者不会被中止；A 的成功回包晚到时仍可能覆盖 B 的 token。
+- 原因：只对 `await` 叠加 abort 保护了调用链，没有给共享 Promise 的归属和最终 token 写入加账号栅栏；单一全局 Promise 还会让 B 加入 A 已在途的 refresh。
+- 处理：公开 token setter / clearer 每次都推进 auth generation；refresh 按 `generation + 发起时 access token` 共享、并以该快照 CAS 发布成功 token。快照已过期时成功回包转为失效结果，401/403 也不得清理新代际 token；新代际建立自己的 refresh Promise，旧 Promise 收尾时不得清掉新尝试。
+- 验证：`src/services/apiClient.test.ts` 要等旧 refresh 完整收束后断言 B token 不变，并用两个独立 deferred response 证明 B 会发起第二个 `/api/auth/refresh`；另覆盖旧 refresh 401 晚到不清 B token。
+
 ## 下游 manifest 回调测试不能冒充实时数据源（2026-08-05）
 
 - 现象：工作台的资源、任务与版本重投影单测保持绿色，但后台 Agent 已更新 `.agent/manifest.json` 后，打开中的工作台仍长期显示旧快照，只有重开项目才更新。
 - 原因：测试 Supervisor 直接调用 `onManifestChange`，只证明 `App manifest -> WorkspaceLauncher -> ProjectDevelopmentView` 的下游桥接；真实 Runtime event 没有失效字段，监听器也没有重读 manifest。External Runner 又与 GUI 分属不同进程，Runner 内无法使用 GUI `AppHandle`，只补普通 Tauri event 仍不能形成生产链路。
 - 处理：后台 manifest mutation 收敛到共用 Runtime emitter；GUI 内进程用带 `manifestInvalidated` 的 Runtime update，External Runner 通过 GUI owner attach 登记的受令牌保护 loopback sink 转发专用失效事件。App 对当前项目做 single-flight manifest 重读，并以 mounted、项目路径和 scope version 丢弃迟到结果；WorkspaceLauncher 继续只消费完整 manifest 快照，不新增平行状态或轮询。
-- 验证：集成测试必须渲染真实 `App + WorkspaceLauncher`、捕获真实 Tauri listener，让 `get_local_game_manifest` 从旧快照切换到新快照，并由非 Supervisor Agent 事件驱动资产、completed 任务、运行入口和版本卡出现；另测项目切换时旧请求迟到。旧的直接 `onManifestChange` 测试只能标记为下游桥接证据。
+- 验证：集成测试必须渲染真实 `App + WorkspaceLauncher`、捕获真实 Tauri listener，让 `get_local_game_manifest` 从旧快照切换到新快照，并由非 Supervisor Agent 事件驱动资产、completed 任务、运行入口和版本卡出现；另测项目切换时旧请求迟到。测试夹具必须先等待目标 Tauri listener 注册完成，并等待项目写入最近列表后触发的只读目录状态刷新完成，再清空调用记录和发送失效事件；对“事件 -> manifest 重读 -> 工作台重投影”使用局部、有界的 `5_000ms` 等待，避免并行全量回归把合法后台检查、监听注册或异步投影调度误判为功能失败。旧的直接 `onManifestChange` 测试只能标记为下游桥接证据。
 
 ## React 资源详情焦点不能依赖重建对象身份（2026-08-05）
 
@@ -4355,6 +4441,7 @@
 - 现象：parent wake 的 200 次瞬态预算耗尽后 Runtime 仍长期显示 running，或 lane 忙、取消、child 前进、manifest 损坏时 reconciliation 被静默丢弃或覆盖新状态。
 - 处理：预算耗尽错误必须向上传递；lane 忙先持久化 deferred signal，再在 lane + 项目锁内重检最新事实。结构损坏路径使用不依赖 manifest hydration 的专用 journal/state 写入，CAS 失败转为继续对账，绝不覆写并发取消或 DAG 进展。可解析的空对象/空 runId 仍是损坏身份，只有完整有效的新 Run 才能阻止旧 marker；event/audit 的同键记录必须完整比对并拒绝冲突或重复。旧 task 已终态、Runtime 非 waiting 或新 Run 接管时，deferred signal 必须写 resolved/superseded，不能留给后续 wake 永久重复 settle。
 - 测试注意：autonomous child fixture 先 linked Pending、后正式 Running；终态 runId 必须拒绝复用。判断 Completed-only 诊断时按每个 seed task 的实际状态分析，不能因为 `code-prototype` Pending 就忽略已经 Completed 的 `art-asset-plan` 深验。
+
 ## macOS 安全路径测试必须使用规范化临时目录（2026-08-05）
 
 - 现象：调用仓库上下文、Runtime context bundle 或 pending recovery 的 Rust 测试在 macOS 报“Repository root and its ancestors must not be symbolic links”，Linux CI 却可能通过；本地 HTTP 恢复夹具在完整串行测试中还可能偶发 `WouldBlock`。
@@ -4383,6 +4470,7 @@
 - 原因：把 dialog / canvas 的完整 UI 所有权同时用于账号级钱包和账号内项目级任务列表，或者任务列表只比较 project ID，没有校验账号。
 - 处理：按副作用分层校验。钱包只比较账号；任务列表比较账号加项目；dialog、canvas、asset 和 layer 写回继续比较账号、项目、scope version 与原 dialog。正式请求已接受后，删除 UI 状态不等于取消后端任务。
 - 验证：分别覆盖删除 dialog、同账号切项目、账号 A 切到账号 B 且 project ID 保持相同，以及原账号原项目原 dialog 仍有效的正常回写。
+
 ## GUI owner 锁不能替代逐 boot 的事件接收端登记（2026-08-05）
 
 - 现象：GUI 首次启动后 manifest 事件转发正常，但 Runner 被替换为新 boot 后只剩 owner 锁和 endpoint 可用，后台更新不再到达 GUI；或者 attach 响应只确认 owner，客户端却误记当前 boot 已完整登记，后续 ensure 不再重试。
@@ -4439,3 +4527,37 @@
 - 原因：冲突两侧代表不同组件架构，逐行保留看似有用的 JSX 会把一个架构中的局部条件拼进另一个架构。import 排序、格式检查和只覆盖单一 mode 的测试都不能证明这种组合成立。
 - 处理：先确定权威组件边界，再按完整调用链解决冲突。图片画布音频入口当前决策是恢复一个共享 `ImageCanvasAudioGenerationComposerView`，由组件内 `isSoundEffect` 分流；BGM/SFX 的 validator、写回、锁和提交契约仍分别保持。不要只补一个常量后继续维持已经废弃的双 composer 边界。
 - 验证：同时渲染 `audio-sound-effect` 与 `audio-background-music`，覆盖两个 mode 的正向控件和互斥负向断言、dialog / mode 切换、BGM 稳定 ID 与 controller 缺失的失败关闭，并运行 `ImageCanvasGenerationComposerView.test.tsx` 与 typecheck。
+
+## SFX Worker 不能只靠分层单测证明退款和零副作用（2026-08-07）
+
+- 现象：LLM、ElevenLabs adapter、OSS 和 metadata 各自测试都通过，但无法直接证明余额不足时外部调用为零、翻译失败不会调用 provider、OSS / DB 失败只退款一次，或项目资源 / 素材 / 画布使用同一份权威 metadata。
+- 原因：正式 SFX handler 把计费、翻译、provider、持久化和写回内联在一个 future 中；分层测试只能证明单个 helper，不能证明组合顺序和“失败后不继续”。同时若把 mock 流程另写一遍，它本身又可能与生产逻辑漂移。
+- 处理：抽出单一 Worker 编排函数和计费 / stage adapter。生产 adapter 代理现有正式实现：OSS 后只准备 asset object / binding 候选，项目资源、账号素材、画布和 job 终态通过同一原子提交落库；测试 adapter 逐段记录调用与注入失败。组合矩阵同时断言 charge / refund、LLM / provider / OSS / writeback 计数、稳定 reason code 和权威值等值。ElevenLabs 二进制、MIME、大小、timeout 和 MP3 仍由 loopback adapter 测试负责，组合 mock 不替代协议测试。
+- 验证：自动 / 手动时长 × Loop 四组合成功；余额不足；翻译、HTTP、无效音频、时长探测、OSS PUT / HEAD、asset confirm / bind、项目资源、账号素材和画布写回逐点失败；所有 job provider POST `<= 1`，预扣后失败 refund `= 1`。
+## 生成结果的稳定 ID 和 job 终态都不能代替 durable receipt（2026-08-06）
+
+- 现象：Provider / OSS 已成功，但项目资源、账号素材、binding、画布和 job 只完成一部分；不确定结果重放时，有时又复制一批素材或重复推进 canvas revision。inline 路径在进程重启后尤其无法判断前一次提交是否整笔完成。
+- 原因：把“请求已入队”、“某个稳定 ID 已存在”或“job 已 completed”误当成整批业务记录已原子提交的证据。request fingerprint 只证明用户请求，不绑定最终 slot、派生记录、画布候选和 compact result；仅比较资源 ID 也无法发现内容漂移。
+- 处理：用 `editor_generation_operation` 记录 durable receipt，分开 request fingerprint 与整笔 commit SHA-256。首次调用在同一 SpacetimeDB 事务中校验 lease 并写 object/resource/asset/binding/canvas/job/receipt；重放先查 receipt，再读回逐 slot 权威事实精确比较。receipt 缺失但 resource/asset/binding 已存在时失败关闭，不得补写 receipt；事务前已确认的 asset object 只能在 ID、bucket/key、owner、策略、媒体、来源和实体字段全部相等时复用。
+- 时间与并发：`completed_at_micros` 必须为正数，object/resource/asset/binding/canvas 候选原时间字段与它一起纳入 commit SHA-256，不能在每次重放时重新取时；job 终态和完成事件只用 SpacetimeDB `ctx.timestamp`。canvas CAS 冲突后只刷新 project 并重算布局，不重跑 Provider / OSS。OSS 尚未进入该事务，无引用 object 仍是需另行清理的边界，不要宣称跨 OSS exactly-once。
+- queue completion 不能把 inline 完整响应无条件同时复制到 `result` 和 `editor-agent-tool-call-result`。图集/UI 最多 64 个切片会重复携带 resource/asset/prompt/generationInputs，容易超过 job payload 512 KiB 上限并让整个原子提交回滚。必须先按普通 UI、Editor Agent、External API 的消费方契约裁剪，再把最终 JSON 交给统一 procedure。
+- 消费方身份不能在提交前重新读取 summary 兼容快照来判断：该快照按设计清空 dedupe key 并删除 generationInputs，Editor Agent / External API 会因此被误判成普通 UI。应在 worker 持有完整 claimed job 时把安全的 consumer kind 与 source identity 固化到调用上下文。
+- procedure future 超时或连接断开不能直接映射为业务失败，远端事务可能已经提交。必须有界重放同一 prepared commit；明确 CAS 后才刷新 layout，且刷新 layout 应使用新时间，不能把项目 `updated_at` 回拨。receipt 不复制 queue payload，只存摘要并从 job 权威行回读；跨记录 object/project 一致性必须在事务内验证，不能依赖当前 builder 通常会携带完整 candidate。
+- job 的 owner/kind/fingerprint/lease 都正确仍不够：`source_entity_id` 还必须绑定结果项目，来源资源必须另查存在性与 owner/project 归属；否则同 owner 的 job 可以误写别的项目，或伪造跨用户/跨项目血缘。
+- Provider 成功时计费 guard 已解除，后续原子持久化失败不会自动退款。但也不能在 api-server 先独立退款再尝试 fail job：过期 worker、fail 断线或原子提交已成功但回包丢失时，会变成「结果成功且已退款」。正确边界是在同一 SpacetimeDB 事务内先 fencing 当前 lease，再同步写退款账本和失败终态；不得期待 `max_attempts = 1` 的编辑器任务再走租约耗尽路径补退。
+- compact result 只能删除大 payload，不能删除消费方 DTO 必填字段或定位正式结果的稳定引用。角色动作/视频缺 `ok`、音效/BGM 缺 `prompt` 都会让 Editor Agent 把已完成 job 判成不可重试的回填失败；External 角色动作/视频如果创建了账号素材，completed 结果还必须保留 `assetId`。
+- `project_resource.source_resource_id` 校验不会自动覆盖 `editor_asset.source_resource_id`；asset-only 结果可以没有项目资源候选，必须另查来源是本事务候选或已登记资源且属于同 owner；若本次结果有 project，还必须同 project。
+- inline 模式不会走 queue `fail_job`，若计费 wrapper 在 Provider 成功时立即 disarm，后续的上传/原子持久化明确失败会扣费无结果。应在全部 inline owner handler 外统一延迟已成功 billing guard 到 durable commit；明确失败退款，但传输未知结果不退，否则远端已成功时又会变成「结果 + 退款」。
+- 消费契约不能只测上游 builder：External v1 在 durable job 入库前还有一层 allowlist compactor，必须对最终 JSON 断言 `ok / prompt / actualPrompt` 及稳定 resource/asset 引用。
+- 计费 guard 的取消补偿必须区分 procedure dispatch 边界：`Build / PoolAcquire / ConnectBuild / ConnectHandshake` 等未发出阶段可确定退款；dispatch 后回包前的 future 取消与断连必须视为结果未知并保留扣款，等 durable receipt 对账。只在 error 返回后再标记 unknown 会留下取消窗口；必须在真正调用 procedure 前同步设置 task-local 标记，并在 `Procedure` 结果或确定未发出的失败后清除。
+- compact DTO 的可选字段必须用最终 consumer payload 回归：Editor Agent 图片生成/修改的 `provider` 会被脱敏删除，必须是可选字段；图标/UI 正常与 source-only fallback 则必须保留 `ok / prompt / actualPrompt`。fallback 不得从可选 project resource 反推必填字段，否则无 `projectId` 任务会持久 `prompt/model=null`、尺寸为零且图标/UI 丢失 `priceMudPoints`。
+- receipt 存在不等于引用 object 仍然可信：省略 candidate 的已登记 object 在重放时也要回读 owner/key/task/kind/媒体身份。同时先查同 operation ID job，存在 job 却漏传 completion 必须整笔回滚，否则会得到 receipt 成功而 job 仍 running 的永久分裂。resource/asset/binding 也不得仅核对 object ID/key，必须按 operation 合法 tuple 交叉验证业务元数据。
+- 验证：故障注入覆盖 resource 后 asset/binding 失败、canvas CAS 冲突、过期 lease、同 operation 异 fingerprint / 异 commit、receipt 缺失的部分既有记录、精确既有 object 复用与 object 内容漂移；成功重放必须证明记录数、时间、binding/job 事件数和 canvas revision 全部不变。
+- 关联：`docs/technical/【后端架构】编辑器生成结果原子提交与幂等重放方案-2026-08-06.md`、Issue #134。
+
+## 付费生成不能把素材目录归属校验留到 provider 之后（2026-08-07）
+
+- 现象：登录用户给自己的合法 `projectId` 搭配不存在或属于其他账号的 `assetFolderId`，图片、改图、图集、UI 提取、视频、角色动作或音频生成会先扣泥点并调用付费 provider / OSS，直到创建 `editor_asset` 才拒绝目录；失败退款让用户成本归零，平台侧 provider 和存储成本不可逆。
+- 原因：`normalize_generated_asset_folder_id` 只处理 `project`、旧 `folder-*` 和默认目录 ID 的兼容映射，不读取 SpacetimeDB；真正的 `require_owned_asset_folder` 位于生成结果持久化末端。把“失败会退款”误当成副作用补偿，漏掉退款不能撤销 provider 请求与 OSS PUT。
+- 处理：所有付费编辑器生成在队列 enqueue 前和 worker / inline 执行前复用只读 `preflight_editor_generation_target_and_return`，按认证 owner 校验可选项目及归一化目录；读取失败和归属不匹配一律失败关闭。helper 返回 canonical 项目与目录并覆写后续入队 / worker / 原子准备使用的 payload，不能校验 trim 后的项目却持久化原始空白值。角色图片、角色动作、图标 spritesheet 与 UI 提取省略目录时按实际默认目录预检；默认目录允许尚未创建，自定义目录必须存在且 owned。预检不替代最终 procedure 复验，也不保证跨外部调用的目录锁定。
+- 验证：源码顺序回归必须覆盖图片生成、图片修改、图标 spritesheet、UI 设计图提取、视频、角色动作、SFX 与 BGM 的 enqueue / direct 两层，证明纯本地格式和 `data:` / `blob:` 稳定引用门禁先执行，canonical target 在预检后写回 payload，远端引用解析、generation input rebuild、扣费、入队、provider 与 OSS 均留在预检之后；模块侧扫描证明预检只调用 runtime identity、项目、目录只读校验且不含 insert / update / delete，并覆盖带空白项目、`project`、旧 `folder-*`、默认目录 ID、自定义目录与 `None` 归一化。

docs/project-memory/shared-memory/project-overview.md

@@ -21,7 +21,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 - 小程序 WebView 外壳：`miniprogram/`。
 - 法律文本：`media/files/user_agreement.md`、`media/files/privacy_policy.md`、`media/files/disclaimer.md`。
 
-桌面端侧边栏的一级入口为 `创作 / 项目 / 我的`；移动端底部 dock 只保留 `我的`。`/creation` 是桌面端独立创作工具主页，`/project` 是桌面端画布项目入口，`/profile` 是桌面端和移动端共用的“我的”稳定路由，继续承载账号、钱包、统计和通用设置等平台公共能力。移动端直达 `/creation`、`/project` 或 `/editor/canvas`，以及从首页触发项目 / 画布动作时，只显示桌面端创作提示，不挂载对应工具页面。
+桌面端侧边栏的一级入口为 `创作 / 项目 / 我的`；移动端底部 dock 只保留 `我的`，根入口默认展示“我的”并保持该 Tab 选中。移动端每次进入站点壳时先显示原有 IP 欢迎遮罩，明确“移动端仅支持作品展示”，遮罩只能通过“好”按钮关闭，关闭后本次页面生命周期内不再重复，刷新后重新显示。`/creation` 是桌面端独立创作工具主页，`/project` 是桌面端画布项目入口，`/profile` 是桌面端和移动端共用的“我的”稳定路由，继续承载账号、钱包、统计和通用设置等平台公共能力。移动端直达 `/creation`、`/project` 或 `/editor/canvas`，以及从首页触发项目 / 画布动作时，只显示与移除前一致的桌面端创作主页提示，不挂载对应工具页面；提示页底部继续保留唯一的“我的”Tab 作为返回入口。
 
 ## 当前后端路线
 

docs/project-memory/shared-memory/team-conventions.md

@@ -47,6 +47,7 @@
 - 新增 Markdown 文档时，文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`；只在任务需要时重命名历史文档，避免无关大 diff。
 - 涉及中文文本时注意 UTF-8 编码和乱码排查。
 - 涉及后端时遵循 DDD 分层，不把业务真相下沉到前端或临时兼容层。
+- 运行时日志禁止对完整配置、应用状态或 provider client 做递归 `Debug` 输出；当前 `AppConfig`、`AppState`、`AppStateInner`、`SpacetimeClientConfig` 与 `SpacetimeClient` 必须保持封闭的手写安全摘要，并用唯一哨兵测试锁定顶层与可独立格式化路径。其它仍使用派生 `Debug` 的历史 provider 类型不得新增整对象日志调用，后续按类型独立脱敏。新增字段默认不进入摘要，确需排障时只增加枚举、数值、布尔值或是否配置等非敏感字段。
 - `packages/shared` 用于前后端 DTO、公开契约及跨页面复用的无业务真相 UI 组件和纯工具；不得把领域规则、后端副作用或正式状态放入其中。
 - 修改 `/api/external/v1` 的路由、HTTP 方法、请求 / 响应 DTO、请求头、状态码、鉴权或异步语义时，必须同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 和对应契约测试；Rust 实现与 OpenAPI 未对齐时不得完成、提交或发布。
 - `maincloud` / `Maincloud` / `MAINCLOUD` 相关代码、脚本、测试、环境变量、命令和文档要求均视为历史残留，禁止新增、运行或引用；API smoke 统一使用 `npm run dev:api-server` 与 `/healthz`。

docs/project-memory/todos/【已知问题】AppConfig与AppState调试输出敏感配置泄漏-Master遗留-2026-08-07.md

@@ -0,0 +1,50 @@
+# AppConfig 与 AppState 调试输出敏感配置泄漏：Master 遗留问题
+
+状态：**主泄漏链已由 master 修复并合入本分支**；第二档的历史 provider 配置类型脱敏仍未完成。
+
+## 修复进展
+
+- master 提交 `497484409`「修复应用状态调试输出密钥泄漏」（PR #150，Closes #148）落地第一档主泄漏链。
+- 本分支 `feat/sound_opt` 已于合并提交 `38e195060` 合入该修复。
+
+已收口的部分（合并后逐条核对属实）：
+
+- `AppConfig`（`server-rs/crates/api-server/src/config.rs:32`）去掉 `derive(Debug)`，改为手写**允许清单** Debug：只输出枚举、数值、布尔等封闭字段，加一个 `credentials: "<redacted>"` 占位，并以 `finish_non_exhaustive()` 收尾。因此**新增的自由字符串字段默认缺席**，不需要逐个补脱敏标记。
+- `AppState` / `AppStateInner`（`server-rs/crates/api-server/src/state.rs:237`）同样改为手写摘要：内嵌 client 只输出 `*_enabled` 布尔，不递归下钻。
+- `SpacetimeClientConfig`（`server-rs/crates/spacetime-client/src/active.rs:110`）隐藏 `token` 与 `server_url` / `database` 自由字符串。这一条独立于 `AppConfig`——`SpacetimeClient` 的手写 Debug 一直在透传整个 `config`，只修 `AppConfig` 修不掉它。
+- 哨兵测试 `debug_summaries_redact_all_runtime_credentials`（`server-rs/crates/api-server/src/state.rs`）用唯一哨兵值覆盖 `AppConfig` / `SpacetimeClientConfig` / `SpacetimeClient` / `AppStateInner` / `AppState` 五条 Debug 路径，并以精确字符串比对锁定 `AppConfig` 的允许输出字段集合。
+- 本分支在该哨兵测试中补入 `elevenlabs_base_url` 与 `elevenlabs_api_key`，锁定 SFX V2 新增凭据同样默认缺席。
+
+## 仍未完成：第二档 provider 配置类型
+
+PR #150 明确把这一档排除在外（提交信息原文：「剩余边界：报告第二档中的历史 provider 配置类型独立 Debug 脱敏另行处理，本 PR 聚焦第一档主泄漏链」）。
+
+合并后仍为明文 `derive(Debug)` 的类型：
+
+| 类型 | 位置 | 明文敏感字段 |
+|---|---|---|
+| `VectorEngineAudioSettings` | `platform-audio/src/types.rs:84` | `api_key` |
+| `VectorEngineImageSettings` | `platform-image/src/vector_engine/types.rs:4` | `api_key` |
+| `LlmConfig` | `platform-llm/src/lib.rs:64` | `api_key` |
+| `OssConfig` | `platform-oss/src/lib.rs:72` | `access_key_id` / `access_key_secret` |
+| `WechatPayConfig` | `platform-wechat/src/pay.rs:98` | `private_key_pem` / `api_v3_key` |
+| `WechatConfig` | `platform-wechat/src/subscribe_message.rs:27` | `app_secret` |
+| `Hyper3dSettings` | `platform-hyper3d/src/types.rs:2` | `api_key` |
+| `VolcengineSpeechConfig` | `platform-speech/src/lib.rs:68` | `api_key` / `access_key` |
+| `MattingConfig` | `platform-matting/src/lib.rs:49` | `access_key_id` / `access_key_secret` |
+
+已完成脱敏、可作为施工模板的两个：`ElevenLabsAudioSettings`（`platform-audio/src/elevenlabs.rs:19`，`api_key` → `[redacted]`，配套哨兵测试 `settings_debug_redacts_the_api_key`）与 `OpenAiImageSettings`（`api-server/src/openai_image_generation.rs:38`，`api_key` → `<redacted>`，内嵌 `Option<AppState>` 只打 `.is_some()`）。
+
+风险评估：这些类型不再经由 `AppConfig` / `AppState` 的 Debug 递归暴露（第一档已阻断），只有在被**单独** Debug 格式化时才泄漏。当前未发现生产代码这样做，风险维持 P2。
+
+## 审查归属
+
+第一档已修复，后续审查若发现 `AppConfig` / `AppState` / `SpacetimeClientConfig` 的 Debug 再次泄漏，按**回归**处理，哨兵测试应当先红。
+
+第二档仍视为已知 master 遗留问题，不作为 `feat/sound_opt` 或 SFX V2 的新增缺陷重复报告。
+
+## 后续修复建议
+
+按上表逐个补手写脱敏 Debug，每个配一条哨兵测试。更彻底的做法是引入 secret wrapper 类型（仓库当前没有 `secrecy` / `zeroize` 等依赖），让「密钥字段不能被 Debug 打印」成为类型系统保证；代价是要动十几个 crate 的字段类型与取值点，需独立排期。
+
+规约现状：AGENTS.md 第 22 行只约束「禁止**提交**密钥到 git」，不覆盖运行时输出。PR #150 已在 `docs/project-memory/shared-memory/team-conventions.md` 补上运行时日志规约，其中对本档的要求是：仍使用派生 `Debug` 的历史 provider 类型**不得新增整对象日志调用**，后续按类型独立脱敏。也就是说第二档在完成前已有明确的止血约束，本文件只跟踪剩余施工项。

docs/technical/【前端架构】图片画布素材导出方案-2026-06-15.md

@@ -28,6 +28,10 @@
 - 锁定、分组、翻转等状态不影响图片文件导出，但写入元数据。
 - 空画布时按钮置灰，或点击后显示轻提示。
 
+左侧素材库选择模式同时支持导出当前可见范围内的选中素材：只选中一个普通素材时直接下载原文件；选中多个素材时沿用画布素材 ZIP 的读取、去重、媒体分目录、序列帧、元数据、部分失败和浏览器下载能力，生成 `项目名-选中素材-YYYYMMDD-HHmmss.zip`，包内根目录为 `项目名-选中素材/`。单素材、单序列帧、选中素材 ZIP 和画布素材 ZIP 的下载文件名都必须包含到秒的本地时间戳，避免同一天重复导出时重名。序列帧层只要至少一帧具有可读 `imageSrc / objectKey` 即可进入导出计划，不要求层级 `src / objectKey`；单层、选中素材和画布集合导出必须共用同一互斥状态，避免并发下载覆盖进度与结果提示。该入口不改变中央画布和图层列表的选择 / 下载语义。
+
+持久素材只要 `src` 或 `objectKey` 任一有效即可进入点击、Shift、框选和全选范围。`src` 为空但保留私有 `objectKey` 的素材，导出时复用统一资源读取链路换签；浏览器无法直读签名 URL 时继续回退同源 `/api/assets/read-bytes` 字节代理，不得因缺少临时展示地址而过滤。
+
 暂不实现：
 
 - 画布整体截图 PNG。
@@ -40,7 +44,7 @@
 导出文件名：
 
 ```text
-项目名-画布素材-YYYYMMDD.zip
+项目名-画布素材-YYYYMMDD-HHmmss.zip
 ```
 
 包内结构：
@@ -72,7 +76,7 @@
 普通序列帧 ZIP 结构：
 
 ```text
-角色动作-Sequence.zip
+角色动作-Sequence-YYYYMMDD-HHmmss.zip
 ├─ frames/
 │  ├─ frame-01.png
 │  └─ frame-02.png
@@ -84,7 +88,7 @@
 Spine JSON ZIP 结构：
 
 ```text
-角色动作-SpineJSON.zip
+角色动作-SpineJSON-YYYYMMDD-HHmmss.zip
 ├─ frames/
 │  ├─ frame-01.png
 │  └─ frame-02.png
@@ -164,6 +168,7 @@ assetObjectId > objectKey > sourceAssetId > src
 2. 过滤无效图层，保留隐藏图层。
 3. 按去重 key 合并图片源或序列帧源。
 4. 对每个素材源读取 Blob：
+   - 集合导出先按图层顺序完成去重和文件名规划，再用同一个四路并发读取器读取 / 转换普通素材与序列帧，最后按规划和原帧顺序写入 ZIP；不得让响应完成顺序改变导出目录或帧顺序。
    - `data:image/...` 直接转换为 Blob。
    - 同源或可访问 URL 使用 `fetch` 拉取 Blob。
    - 私有 generated / OSS 素材先走 `/api/assets/read-url` 换签并由浏览器直接 `fetch` OSS 签名 URL；必须在同一保护边界内完整消费响应体，换签、请求、状态码或响应体读取任一阶段失败时，才 fallback 到同源 `/api/assets/read-bytes`，不得在只拿到 `2xx/206` 响应头后提前视为读取成功。
@@ -198,6 +203,10 @@ assetObjectId > objectKey > sourceAssetId > src
 - 动作图层右键菜单把 `导出为` 作为一级入口，二级菜单提供 `序列帧导出（zip）` 和 `Spine 导出（zip）`。
 - 单图层普通序列帧 ZIP 包含 `frames/`、`preview.gif`、`metadata.json` 和 `manifest.txt`，且不包含 `skeleton.json`。
 - 序列帧导出的 `skeleton.json` 可被独立验证器解析并预览。
+- 左侧素材库只选一个素材时直接下载该素材，不创建集合 ZIP。
+- 左侧素材库选择多个素材时只把选中素材写入 `项目名-选中素材-YYYYMMDD-HHmmss.zip`，不混入未选素材，并继续覆盖部分失败和全部失败边界。
+- 同一事件循环内重复触发集合导出时只启动一次读取和下载；单个选中素材下载成功后显示 `选中素材已导出`。
+- 多素材与长序列帧集合导出同时读取不超过四项，外层素材无需等待前一个序列全部完成，异步读取逆序完成时 ZIP 文件与帧顺序仍保持稳定。
 
 ## Spine JSON 验证器
 
@@ -226,7 +235,6 @@ npm run spine-export-validator:build
 
 ## 后续扩展
 
-- 导出当前选中素材。
 - 导出画布快照 PNG。
 - 导出可恢复工程包。
 - 导入工程包恢复画布。

docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md

@@ -101,9 +101,12 @@
 ## 第十阶段模块
 
 - `useImageCanvasAssetLibrary.ts`
-  - 承载账号级素材库状态模型：素材文件夹、素材列表、文件夹折叠 / 新建 / 重命名 / 删除、素材重命名 / 删除、素材选择模式、框选、多选删除、素材拖到文件夹和鉴权失败登录弹窗。
+  - 承载账号级素材库状态模型：素材文件夹、素材列表、文件夹折叠 / 新建 / 重命名 / 删除、素材重命名 / 删除、批量删除资源副作用、素材拖到文件夹和鉴权失败登录弹窗；不再持有选择集合、范围锚点或框选交互状态。
   - 主视图继续保留上传文件读取、上传占位卡片进度、拖到画布坐标、创建画布图层、工程资源持久化和画布图层清理；素材删除通过 `onDeleteAssets` 回调通知主视图清理关联图层。
   - 该 hook 有独立单测覆盖素材库加载归一化、401 登录、新建文件夹临时 id 替换、素材移动、删除回调和多选删除，避免后续整理侧栏 JSX 时丢失素材库能力。
+- `useImageCanvasAssetSelection.ts`
+  - 作为素材选择的唯一状态边界，统一持有选择模式、完整选中集合、范围锚点、可选素材有效性 reconcile、单项 / Shift / 当前可见全选增量、框选几何与框选生命周期；框选除 `pointerup / pointercancel` 外必须在匹配的 `lostpointercapture` 到达时只清理框选状态，不得再次释放已经丢失的 capture。该 hook 向批量下载 / 删除只暴露已经按素材顺序解析的 `selectedAssets`；删除入口根据当前 `visibleAssetIds` 识别未显示选择并在执行完整集合删除前弹出危险确认。
+  - 搜索和文件夹折叠只在侧栏产生 `visibleAssetIds` 并传入增量动作，不得直接修改或 reconcile 选择集合；选择行为测试集中在该 hook，素材库 model 不再维护第二套选择状态机。
 
 ## 第十一阶段模块
 

docs/technical/【前端测试】React组件测试准则-2026-06-26.md

@@ -1,6 +1,6 @@
 # React 组件测试准则
 
-更新时间：`2026-06-26`
+更新时间：`2026-08-07`
 
 ## 背景
 
@@ -36,6 +36,10 @@
 - `data-testid` 名称必须描述用户或稳定渲染边界，例如 `image-canvas-editor-snap-guide-vertical`；不要描述 React 私有 state 名称。
 - 测试用 fixture 只包含本行为需要的字段。演化中的 payload 使用 `expect.objectContaining(...)` 或 helper 生成默认对象，避免一处契约加字段导致大量无关用例碎裂。
 - 当测试是为防止历史回归，应在测试名或邻近注释中说明防的是什么行为，而不是记录实现步骤。
+- 同一用例既要验证定时器调度参数，又要断言确定的中间帧或中间状态时，必须 mock 定时器回调或使用可控假时钟；不得让真实墙上时间在异步交互期间推进被断言的状态，否则本地通过的用例会在较慢 CI 中偶发失败。
+- 测试 React effect 中注册的事件监听时，触发事件前先用可观测的 listener 调用确认注册已完成；异步请求已开始应用有界 `waitFor` 断言确认，不要用无界手工 Promise 等待一次性信号。解除挂起请求时将 Promise 收尾纳入异步 `act`，确保后续 React 更新在断言前已冲刷。
+- 公共 `AutoGrowTextArea` 使用 Lexical `contenteditable`，业务测试通过 `setPlainTextEditorValue` 写入文本、通过 `getPlainTextEditorHost` 断言外层样式；占位文案是独立渲染节点，不读取原生 `placeholder` 属性，也不对编辑根触发 textarea 专属的 `change` 事件。
+- 异步请求失败时，错误状态与调用方的草稿 / 附件恢复可能分属连续两次 React 更新；用例必须对最终恢复结果使用有界 `waitFor`，不能把错误文案刚出现的中间帧当成恢复已经完成。
 
 ## 试点调整
 

docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md

@@ -29,7 +29,8 @@ VectorEngine `gpt-image-2`、音频、LLM 等外部生成不能由面向外部
 - `claim_external_generation_jobs_and_return`：worker 按 `worker_id`、`limit` 和 lease 时长抢占 `pending` 或 lease 过期的 `running` 任务，返回本次 claim 的 `lease_token`。
 - `renew_external_generation_job_lease_and_return`：worker 长任务执行期间按 `worker_id + lease_token` 续租，防止外部生成超过单次 lease 后被重复领取。
 - `update_external_generation_job_phase_and_return`：worker 按 `job_id + worker_id + lease_token` 把当前执行阶段更新为 `generating` 或 `processing`，并同步现有摘要投影；不新增阶段任务或阶段表。procedure 用结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`，调用方不解析错误文案；`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，只有 `Build` / `ConnectDropped` / `Timeout` 在同一个 job attempt 内重试 `1` 次。该重试只重新上报 phase，不把任务写回 `pending`，也不重新调用 provider；编辑器 job 入队固定 `max_attempts=1`，第二次传输失败后任务进入 `failed`，不会回到 `pending` 或从 provider 生成起点重跑。
-- `complete_external_generation_job_and_return`：worker 成功后按 `worker_id + lease_token` 写入 `result_payload_json`，任务进入 `completed`。
+- `complete_external_generation_job_and_return`：只保留给不携带编辑器正式 object/resource/asset/canvas 业务写回的兼容路径。现役编辑器生成成功时不得单独调用它。
+- `persist_editor_generation_result_and_return`：编辑器 queue / inline 共用的结果提交口。单一事务写入可选 asset object、全部 project resource / account asset / asset binding、可选 canvas V2 CAS、queue job 完成与 durable receipt；返回 `Applied / AlreadyApplied` 和权威快照。
 - `fail_external_generation_job_and_return`：worker 失败后按 `worker_id + lease_token` 回写错误，并按 `max_attempts` 决定回到 `pending` 重试或进入 `failed`。
 - `list_external_generation_job_summaries_and_return`：按当前账号从轻量摘要投影读取正式生成任务列表，返回 pending / running / 未确认终态数量、任务价格、执行阶段和完成提示确认状态。
 - `acknowledge_external_generation_job_summaries_and_return`：按当前账号确认已终态任务的完成 / 失败提示，写入摘要投影的 `notification_acknowledged_at` 并追加审计事件。
@@ -87,6 +88,8 @@ BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；worker 调度、
 
 新增私有审计表 `external_generation_job_event`，记录 `enqueued/claimed/lease_renewed/completed/failed/acknowledged` 等事件。事件表只追加状态转换事实，不作为当前状态源；排障时先看 `external_generation_job` 当前状态，再按 `job_id` 追 `external_generation_job_event` 时间线。
 
+另新增私有 `editor_generation_operation` durable commit receipt。它不与 `external_generation_job` 争抢任务状态：job 仍负责队列、lease、计费和通知，receipt 只固化某个 owner/kind/operation 的 request fingerprint、整笔 commit SHA-256、可选 project 以及 queue 的 job/worker/lease/result 绑定。inline 虽没有 job，也必须写 receipt；否则 API 进程重启后无法安全区分“完整提交”与“稳定 ID 巧合/历史部分记录”。
+
 索引：
 
 - `by_external_generation_job_status_available(status, available_at)`
@@ -205,9 +208,11 @@ controller 配置：
 - `editor_video_generation`：画布视频生成和视频素材快速编辑。
 - `editor_sound_effect_generation` / `editor_background_music_generation`：画布音效与背景音乐。
 
-画板结果的业务真相仍是 `editor_project_resource`、账号级 `editor_asset` 和 `editor_canvas.layers_json`。请求携带 `projectId + canvasCompletion` 时，worker 成功后读取当前项目 layout，用最新 generation dialog placeholder 或无 dialog 完成占位写入结果图层，并保存项目快照；前端轮询单 job 到 completed 后重新读取项目快照，不从队列 payload 或本地临时响应重建正式图层。生成器已被删除时，worker 只保留生成出的资源 / 素材记录，不把结果重新塞回画布。
+画板结果的业务真相仍是 `asset_object`、`editor_project_resource`、账号级 `editor_asset`、可选 `asset_entity_binding` 和对应的 legacy / structured canvas 表；`editor_generation_operation` 只是提交回执，不替代这些 read model。worker 在 Provider 与 OSS 完成后只做 prepare：使用 owner + operation kind + job ID + stable slot 派生 resource/asset ID，构造可选 object/binding、候选 layout 和 compact job result，然后一次调用 `persist_editor_generation_result_and_return`。该 procedure 必须在当前事务快照校验 owner、job kind、由 `request_payload_json` 重算的 fingerprint 与未过期 lease，最后与业务记录一起完成 job 和 receipt。任一验证、binding 或 canvas CAS 失败都回滚全部数据库事实；worker 不得随后再调用 `complete_external_generation_job_and_return`。前端轮询单 job 到 completed 后重新读取项目快照，不从队列 payload、receipt 或本地临时响应重建正式图层。
 
-角色形象、图标 spritesheet 和 UI 素材提取在 provider 原图已经持久化后，如果透明背景处理最终失败，只用原图完成 `canvasCompletion`，不创建或回填透明处理图，图标和 UI 也不继续拆分，任务保持 `completed`。这个 source-only 降级只包住透明背景处理的最终失败；phase 上报、provider 原图持久化、透明处理图持久化或画布写回失败仍按任务错误传播。
+结果重放必须保持同一 operation fingerprint 和同一 prepared commit：receipt 存在时核对 commit SHA-256、project/job/worker/lease/result 绑定与逐 slot 权威记录，完全一致才返回 `AlreadyApplied`，不重复 job/binding 事件或 canvas revision。receipt 缺失但任一稳定 resource/asset/binding 已存在、同 operation 异指纹/异内容、已过期 lease 都失败关闭；事务前已确认 object 只在候选全字段精确一致时复用。canvas CAS 冲突时只刷新 project 重算 layout，不再次调用 Provider 或上传 OSS。`completed_at_micros` 必须为正数，候选原时间字段与它一起绑定到 commit SHA-256，重放不得重新取时；job 终态与事件使用 SpacetimeDB `ctx.timestamp`。OSS `PUT / HEAD` 仍位于事务外，可留下无引用 object，不声称跨 OSS exactly-once。
+
+角色形象、图标 spritesheet 和 UI 素材提取在 provider 原图已可用且 OSS 上传已验证后，如果透明背景处理最终失败，最终 prepared commit 只保留原图并用它完成 `canvasCompletion`，不创建或回填透明处理图，图标和 UI 也不继续拆分，任务保持 `completed`。这个 source-only 降级只包住透明背景处理的最终失败；phase 上报、原图候选构造、透明处理图候选构造或统一原子提交失败仍按任务错误传播。
 
 透明背景处理正常成功时，角色形象、图标 spritesheet 和 UI 素材提取的画布都同时放透明主结果与 provider 原图：透明主结果保持生成器 `generatedLayerId` 主锚点，provider 原图作为第二个图层放在其右侧；图标和 UI 实际拆分出的业务素材从 provider 原图右侧继续排列。
 

docs/technical/【后端架构】编辑器生成结果原子提交与幂等重放方案-2026-08-06.md

@@ -0,0 +1,116 @@
+# 编辑器生成结果原子提交与幂等重放方案
+
+日期：`2026-08-06`
+
+## 目标
+
+修复 Issue #134：现役图片、图片修改、背景移除、图标图集、UI 素材提取、角色动作、视频、音效和背景音乐生成，在 OSS 结果已经可用后，必须把正式 `asset_object`、`editor_project_resource`、`editor_asset`、可选画布完成和队列终态作为同一个可重放提交处理，禁止继续按多个独立 SpacetimeDB procedure 分段写入。
+
+本方案只承诺数据库内原子性。OSS `PUT / HEAD` 仍位于 SpacetimeDB 事务外；事务失败可能留下尚未登记或尚未引用的对象，后续按 operation 前缀做异步清理，不把它描述成跨 OSS 的 exactly-once。
+
+## 权威操作身份
+
+- 默认 queue 模式：`external_generation_job.job_id` 是唯一 operation ID。External v1 的 `Idempotency-Key`、主站稳定 `x-request-id` 和 Editor Agent 确定性任务 ID 都先收敛为该 job ID。
+- inline 兼容模式：使用 `RequestContext.request_id` 作为 operation ID，并对规范请求计算 SHA-256 fingerprint；同 ID 异 fingerprint 必须返回幂等冲突。inline 也必须写 durable receipt，不能只靠进程内 prepared result 或稳定记录 ID 猜测是否已提交。
+- Provider `taskId` 只保留为生成审计字段，不参与正式记录唯一性。
+- 每个 operation 的产物以稳定 `slot` 区分，例如 `provider-source`、`primary`、`processed`、`slice-0000`、`animation-preview`、`animation-final`。记录 ID 按 `owner + operation kind + operation ID + slot + record kind` 做 domain-separated SHA-256 派生，产物顺序变化不能改变既有 slot 的 ID。
+
+## 统一 procedure
+
+在 `spacetime-module` 增加 `persist_editor_generation_result_and_return`。procedure 只允许 editor generation runtime service identity 调用，并在一个 `try_with_tx` 内完成全部动作。
+
+输入的编码级形状：
+
+```rust
+EditorGenerationResultPersistItemInput {
+    slot: String,
+    asset_object: Option<AssetObjectUpsertInput>,
+    project_resource: Option<EditorProjectResourceCreateInput>,
+    asset: Option<EditorAssetCreateInput>,
+    binding: Option<AssetEntityBindingInput>,
+}
+
+EditorGenerationResultPersistInput {
+    owner_user_id: String,
+    operation_kind: String,
+    operation_id: String,
+    operation_fingerprint: String,
+    items: Vec<EditorGenerationResultPersistItemInput>,
+    canvas_layout: Option<EditorProjectLayoutSaveV2Input>,
+    job_completion: Option<ExternalGenerationJobCompleteInput>,
+    completed_at_micros: i64,
+}
+```
+
+输出返回 `Applied / AlreadyApplied`、逐 slot 的 object/resource/asset/binding 快照、可选 project 快照和可选 job 快照。
+
+### Durable receipt
+
+新增私有表 `editor_generation_operation`，它是 queue 和 inline 共用的 durable commit receipt，不是第二套业务状态或任务队列。主键 `operation_key` 由 owner 和 operation ID 做 domain-separated SHA-256 派生，因此同 owner 不得跨 operation kind 复用同一 operation ID；表内固化 `owner_user_id / operation_kind / operation_id / operation_fingerprint / commit_sha256 / project_id / job_id / job_worker_id / job_lease_token / job_result_payload_sha256 / completed_at`。
+
+- `operation_fingerprint` 绑定用户请求；`commit_sha256` 对完整 `EditorGenerationResultPersistInput` 的稳定 BSATN 编码做 domain-separated SHA-256，另外绑定本次准备提交的 slot、object/resource/asset/binding、画布候选与 job completion。不得使用 Rust `Debug` 文本充当持久协议，两类指纹也不得混为一个。
+- queue 路径必须把 receipt 与原 `job_id + worker_id + lease_token + result_payload_json` 全量绑定；receipt 只保存 payload SHA-256，不复制正文。首次提交仍必须验证当前有效 lease，完成后重放以 receipt 为提交凭证，并回读已完成 job 核对业务身份、权威 compact result 及其 SHA-256。
+- receipt 只保存幂等校验所需的有界元数据与摘要，不复制 project/canvas 大快照，不代替 resource、asset、binding 和 job 的权威表。
+
+### 首次提交顺序
+
+1. 校验调用身份、operation 字段、fingerprint、item 数量上限和 slot 唯一性。统一提交最多接受 66 个 item，用于容纳最多 64 个图集切片以及 provider 原图和透明整图。
+2. queue 输入必须完整携带 `job_id + worker_id + lease_token + result_payload_json`；inline 输入必须全部省略，禁止半套 guard。
+3. queue 路径在同一事务快照内校验 job owner、kind、request fingerprint、running 状态和有效 lease；过期 worker 不得写业务结果。`source_entity_id` 必须精确等于本次唯一结果 `project_id`，不得用同 owner 的 job 向其他项目提交。
+4. 对每个 item 校验稳定 object/resource/asset ID、owner、project、folder、object key、source resource、task 审计字段和媒体字段的交叉一致性。project resource 和 account asset 的 `source_resource_id` 均必须单独验证：来源资源必须是本次同事务候选或已登记资源，属于同 owner，且在结果具有项目上下文时属于同 project；不接受 asset-only 分支绕过血缘校验。
+5. `asset_object` 存在于输入时在同一事务内做精确 upsert；省略时，resource/asset/binding 引用的 object 必须已登记且属于同 owner。事务前 OSS `HEAD` 成功不等于 object 已正式登记。
+6. 创建全部 project resource、account asset 和可选 `asset_entity_binding`。binding 必须指向同 slot 的 object 与对应 resource/asset 实体，且 owner、asset kind、entity kind/id 和稳定 binding ID 完全一致。不得接受普通 media reuse 返回另一个随机 resource ID；稳定 ID 已被占用且内容不一致时失败关闭。
+7. 有 `canvas_layout` 时调用既有 V2 layout 持久化函数，以 `expected_revision` 做 CAS，并继续执行 legacy / structured 大小、资源引用和媒体族门禁。
+8. queue 路径最后调用事务内 job complete，写入调用方预先按现有规则构造的 compact result payload；再写入 durable receipt。任一步失败时 object/resource/asset/binding/canvas/job/receipt 全部回滚。
+
+`completed_at_micros` 必须为正数，首次提交把它固化为 receipt `completed_at`。object/resource/asset/binding/canvas 候选各自现有的时间字段连同 `completed_at_micros` 一起进入 commit SHA-256；同一 prepared commit 的未知结果重放必须复用原时间，不得重新取时。明确的 canvas CAS 表示该事务已回滚，刷新 project 后形成新的 layout candidate，使用刷新时的 `updated_at_micros`，避免把并发用户刚写入的项目时间回拨。job `completed_at/updated_at` 与 job event 时间仍由 SpacetimeDB 事务时间 `ctx.timestamp` 产生，不信任调用方时钟。成功重放返回原快照，不刷新 receipt、业务记录、事件或 canvas revision。
+
+### 重放
+
+- receipt 存在时，只允许相同 owner/kind/ID、operation fingerprint、commit SHA-256 与原 project/job 绑定的完整重放；queue 额外核对原 worker/lease/result payload。逐 slot 权威 object/resource/asset/binding 和可选 project/job 仍必须可读且与候选一致，不得只看 receipt 就伪造快照。
+- receipt 存在且全部事实一致时返回 `AlreadyApplied`，不得新增记录、重复 binding changed / job completed 事件、刷新时间或推进 canvas revision。
+- receipt 缺失但任一稳定 asset object/resource/asset/binding、画布结果或已完成 job 已存在，属于可疑的部分写入，必须失败关闭；不得临时补 receipt 后声称幂等。现役生成 prepare 阶段只做 OSS PUT/HEAD，不得在统一 procedure 前单独登记稳定 asset object。
+- procedure 调用结果未知时，调用方最多自动重放同一 prepared commit 两次，不重新调用 Provider 或重新上传 OSS；明确的业务错误和 CAS 冲突不进入传输重放。
+- `operation_id` 在 `external_generation_job` 中已存在时，首次提交和 receipt 重放都必须携带与它一致的完整 job completion guard；只有事务内确认不存在同 ID job 时才允许 inline。
+- 同一 item 的 resource/asset 尺寸、媒体引用、task、asset kind 与生成元数据必须一致；binding 必须匹配 operation 明确允许的 entity/slot/kind/profile tuple。音频使用 `sound-effect -> editor_sound_effect`、`background-music -> editor_background_music` 显式映射，不使用粗暴的全字段硬等。
+- item 省略 `asset_object` candidate 而复用已登记对象时，首次提交与 `AlreadyApplied` 重放都要回读 canonical object，重新验证存在性、owner、object key、task、kind 和音频媒体类型。
+
+## api-server 接入
+
+- 通用持久化改为 `prepare -> build canvas candidate -> atomic commit`。prepare 阶段只生成稳定 ID、上传/验证对象和构造候选 DTO，不创建 resource/asset。
+- api-server 继续复用现有画布 completion / replacement 逻辑计算候选 `layers_json` 和 `expected_revision`；统一 procedure 在最终事务内重新执行既有 layout 校验和 CAS。
+- CAS 冲突只刷新当前 project、重新计算 layout 并重试 prepared commit；相同 operation、slot、对象和记录候选保持不变，禁止重跑 Provider。
+- 重新计算 layout 时只允许 revision、layers 与 layout `updated_at_micros` 随最新 project 变化；业务 items、job result payload 和 `completed_at_micros` 保持不变。首次 CAS 事务已明确回滚，因此刷新后的 layout 是新的 prepared commit；该 commit 若结果未知，只能原样重放自身。调用方最多自动刷新一次，第二次冲突直接返回。
+- queue completion 不持久化 inline handler 的完整响应：普通画布任务只保留 source/warning 元数据，Editor Agent 只写入裁剪后的 `editor-agent-tool-call-result`，External API 只写入裁剪后的 `result`。图集/UI 切片不得在 queue payload 中重复携带完整 resource/asset/prompt/generationInputs，最终 JSON 必须在 512 KiB 持久化上限内。
+- compact result 必须先满足原消费 DTO 的必填字段：角色动作/视频保留 `ok`，图标/UI 正常与 source-only fallback 保留 `ok / prompt / actualPrompt`，音效/BGM 保留 `prompt`；Editor Agent 与 External v1 的二次 allowlist 裁剪都不得再删除 `prompt / actualPrompt`，最终持久 payload 必须能反序列化为对应 response contract。Editor Agent 图片生成/修改 DTO 的 `provider` 为可选审计字段，compact payload 可删除它而不影响终态回填。External API 的角色动作与视频结果还必须保留本次已创建账号素材的稳定 `assetId`；裁剪可移除大 payload，但不得让 completed 结果无法定位正式素材。
+- queue 消费者身份在 worker 从完整 claimed job 构造调用上下文时固化；原子提交不得再从 summary 兼容快照反推，因为该快照会清空 dedupe key 并裁剪 request payload。
+- queue 的 compact result 当前不保存 `project`，因此可在事务前由稳定候选 resource/asset 和生成响应元数据构造；HTTP 成功响应中的 project 使用 procedure 返回的权威快照。
+- worker 在统一 procedure 已完成 job 后不得再次调用 `complete_external_generation_job`。只有 `Applied / AlreadyApplied` 才能作为成功终态。
+- Provider 已成功且计费 attempt 已扣款后，若原子提交确定失败并要把 job 置为终态 `failed`，必须由同一 SpacetimeDB 事务先验证当前 worker/lease，再结算当前 attempt 退款并写失败终态。不得在 api-server 先独立退款，否则过期 worker 或已成功但回包丢失的提交可能同时得到正式结果与退款。
+- inline 模式没有 job 失败事务补退，计费成功边界必须延迟到 durable result commit 完成。Provider/上传成功后的明确持久化失败退还已扣泥点；`Build / PoolAcquire / ConnectBuild / ConnectHandshake` 等 procedure 未发出阶段的失败或取消仍通过 deferred guard 退款。procedure dispatch 后到明确回包前必须标记结果未知；连续传输不确定或此窗口内 HTTP future 被取消时保留扣款，避免远端已成功时变成「正式结果 + 退款」。`Procedure` 回包是确定结果，成功或明确失败后必须清除未知标记。
+
+## 多产物与现有特例
+
+- 图片的 provider source、透明/规整结果和 source-only fallback 必须在最终选择明确后一次提交；fallback 只提交实际保留的结果集合。fallback compact result 的尺寸、`prompt / actualPrompt`、model 和图标/UI `priceMudPoints` 必须来自本次已冻结生成上下文，不得从可选 project resource 反推；不带 `projectId` 时仍必须产生完整消费契约。
+- 图标图集和 UI 提取使用稳定 slot 提交 provider source、透明整图和成功切片；切片失败时按既有 warning 语义只提交可信整图集合。
+- 角色动作一次提交预览视频与最终序列素材；逐帧 `asset_object` 可作为 item upsert 或已登记对象被最终序列引用，正式 project resource / account asset 与 canvas 不得分段提交。
+- 视频、音效和背景音乐使用单个 primary item。
+- 完美像素保留现有专用 operation/fingerprint/procedure；手动图集拆分不调用 Provider，不属于本次九类生成 job 的原子提交范围，继续使用现有批量 procedure 与画布完成链路。
+
+## Schema 与兼容性
+
+- 新增私有 `editor_generation_operation` durable receipt 表；它与 `external_generation_job` 分工，前者证明一笔业务结果原子提交，后者仍是 queue 执行、lease、计费和通知真相。新表必须纳入 `migration.rs` 导入/导出、schema 检查和本文档表目录。
+- 新增 Spacetime procedure/type ABI 后必须重新生成 `spacetime-client` bindings，并同步 facade mapper。
+- HTTP 路由、请求/响应 DTO、header、状态码和 External v1 异步语义保持不变，因此不修改 OpenAPI；必须复跑 External v1 契约测试证明没有漂移。
+- inline 兼容模式没有 durable job，但必须具有同样的 durable receipt、稳定 ID、fingerprint 和单事务重放；这仍不授权浏览器自动重试已可能发出的生成 POST，调用方应先走结果对账。
+
+## 验收
+
+- 资源创建后资产或 binding 校验失败：事务结束后 object/resource/asset/binding/canvas/job/receipt 均无部分写入。
+- 资源/资产创建后 canvas revision 冲突：全部业务记录回滚；使用同 operation 和 prepared result 刷新布局后可成功。
+- 成功后相同 operation 重放：返回原 object/resource/asset/binding/project/job，receipt 只有一行，记录数、时间、完成事件数和 canvas revision 不变。
+- 同 operation 异 request fingerprint、异 commit SHA-256、异 project/job 绑定、除精确可复用 object 外的部分既有记录、缺失 receipt 和过期 lease：失败关闭且零新增写入。
+- queue job 的 `source_entity_id` 与结果项目不同、或 `source_resource_id` 不属于同 owner / project：失败关闭且零新增写入。
+- Provider 成功后原子持久化确定失败：有效 lease、当前计费 attempt 退款与 job `failed` 在同一事务内成功或回滚；已 completed 或过期 lease 失败关闭且不退款。External 角色动作/视频成功结果保留稳定素材引用。
+- legacy 与 structured canvas、dialog 已删除、无 project/asset folder、单产物、多产物、64 切片和角色动作序列均覆盖。
+- 图片、修改、背景移除、图集、UI 提取、角色动作、视频、音效、背景音乐的生产路径不得再出现 `create resource -> create asset -> save canvas -> complete job` 分段组合。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -31,17 +31,17 @@
 - Windows AppData 安全迁移：首次创建客户端 AppData 时必须以进程 `TokenUser` SID 显式设置 owner，并写入当前用户私有 DACL，不能把可能为 Administrators 的 `TokenOwner` 当作用户身份。发现历史目录 owner 不属于当前 `TokenUser` 时，不在原目录上放宽权限，而是拒绝 reparse point / junction / symlink 后，将旧目录原子重命名到同级唯一 `.owner-mismatch-backup-*` 备份，再新建并验证当前用户 owner 与私有 DACL；迁移或备份失败必须失败关闭，不覆盖旧配置。
 - Windows Runner 私有文件初始化：父 AppData 已归当前 `TokenUser` 后，新建 `agent-runner.lock`、endpoint 临时文件、project-owner 诊断临时文件与 real-E2E 私有文件的 owner 仍可能采用 token 默认 owner `Administrators`。固定 stale lock 只有在父目录已验证为当前用户 protected 私有 DACL、Windows 不共享独占句柄已取得、且句柄确认普通文件、非 reparse point、链接数为一时才允许修复；其它三类文件只允许在本进程 `create_new` 成功且仍持有同一独占句柄时初始化 `TokenUser` owner / DACL，再写入、原子安装并严格复核，初始化失败必须清理刚创建的文件。既有 durable endpoint / diagnostic 读取不得自动接管；活锁不得截断，只有 sharing / lock violation `32/33` 表示占用，access denied 等其它错误立即返回。父进程观察到 Runner 子进程退出后立即返回错误，不等待完整 30 秒 deadline。
 - 启动诊断：独立 release 的 `startup.log` 和 `agent-runner.log` 只记录有界、脱敏的阶段与 stdout / stderr 摘要，凭据、AppData 路径和其它绝对路径不得原样落盘；单文件达到 256 KiB 后只轮转保留一份 `.previous.log`。`startup.log` 优先写独立 AppData，目录不可写时回退到系统 TEMP 下的 `Genarrative-Game-Chat-Diagnostics`；Tauri context、窗口 URL、AppData、Runner 或 `.setup()` / `.build()` 初始化失败时，Windows 必须显示可见错误对话框并给出诊断日志位置，不能只在无控制台 release 中静默退出。
-- 对话与事件：窗口固定使用 `project-supervisor + autonomous-game-build`，继续复用 active Session、External Runner、持久 conversation、流式回复、same-run steer、工具确认与用户追问。以 `/` 开头的输入必须继续走现有内置命令解析，例如 `/preview` 只能生成 `preview.start` 确认卡，不得作为自主构建任务投递给 Supervisor。界面聚合当前 Supervisor 父 run 及其直接委派专业 Agent 的最新原始事件，按时间倒序稳定去重并标注 Agent；默认显示 4 条，可展开至最新 20 条。原始 `summary / detail` 仍只作 Runtime 状态投影，不直接写入 conversation。需要进入聊天的事件必须由 Rust 同步生成唯一 `eventId` 与安全 `publicText`；前端只按这两个字段形成独立 assistant 消息，无 `eventId`、空 `publicText`、legacy 事件和内部 tool / Provider / Runner 协议一律忽略。
+- 对话与事件：窗口固定使用 `project-supervisor + autonomous-game-build`，继续复用 active Session、External Runner、持久 conversation、流式回复、same-run steer、工具确认与用户追问。以 `/` 开头的输入必须继续走现有内置命令解析，例如 `/preview` 只能生成 `preview.start` 确认卡，不得作为自主构建任务投递给 Supervisor。game-chat 的自主链路中，Supervisor 持久化意图后只有 `code-prototype` 是主 Agent；它可能临时委派一个受限美术 child，后者只写 `assets/**`，回执返回同一主 Run 后由主 Agent 接入与验收。界面聚合当前 Supervisor 父 run、单主 Agent 及其直接美术 child 的最新原始事件，按时间倒序稳定去重并标注 Agent；默认显示 4 条，可展开至最新 20 条。原始 `summary / detail` 仍只作 Runtime 状态投影，不直接写入 conversation。需要进入聊天的事件必须由 Rust 同步生成唯一 `eventId` 与安全 `publicText`；前端只按这两个字段形成独立 assistant 消息，无 `eventId`、空 `publicText`、legacy 事件和内部 tool / Provider / Runner 协议一律忽略。
 - 公开消息硬门：模型仍负责 Supervisor / 专业 Agent 回复的业务语义，Runtime 不根据 tool 或 Provider 事件自行补写业务结论；但用户直接投递的 Project Supervisor 根后台任务必须先落为不可执行的 `preparing / public-status-pending`，再以 `runtime-public-status-*` 稳定 message ID 把“任务已接收，正在启动处理”写入项目 conversation，成功后才转为 `pending / queued`；恢复预检只读，只能在验证到同 run accepted 消息后把该任务临时分类为可恢复，真实 resume 持有 Agent 锁后才可持久提升为 `pending / queued`；写入失败则落为 `failed / public-status-write-failed`，不得继续执行。这些 Runtime 公开状态只供 UI 展示，prompt 构建器必须按稳定前缀排除。根 Supervisor 通过正式失败 / 预算耗尽收束或 game-chat 绝对硬期限进入 reconciliation 时，必须在 task、event、state 等其它终态投影之前先幂等写入一条脱敏、用户可理解的失败消息；专业 Agent 命中该全局硬期限时，也必须通过权威 Run Profile 和根 task 将同一根终态写入项目 conversation，同时保留 child 私有 Session 状态；状态文件本身写坏也不能导致零公开结果。当前 Runtime 自称根 agent/run 时，其 session 和两个 parent 字段必须与权威根 task 一致；任一身份冲突必须失败关闭，不得以另一 session 派生第二条项目终态。前端把该前缀识别为 Runtime-owned，同秒时排在触发它的 Supervisor 用户消息之后，不二次持久化；仅根 Supervisor 的 `turn.started / turn.failed / turn.budget_exhausted` 只保留在 Runtime 详情和进度投影中，不能再生成第二条聊天消息，专业 Agent 的公开启动事件仍可见。该硬门不改变 final-reply 的唯一性；非 Supervisor 专业 Agent 的失败消息继续留在对应 Agent Session，不把私有诊断写进项目 conversation。
 - 启动恢复和续跑边界：本条取代上一条中“只有 accepted 才可恢复”的窄口径。若进程在 Supervisor 用户消息已持久、accepted 未持久之间崩溃，只读 preflight 可以把该 `preparing` 识别为可恢复，但不改写 task/conversation；真实 resume 持有 Agent 锁后必须先幂等补写 accepted，再提升为 `pending / queued`。用户消息或 accepted conversation 已落盘而辅助审计失败时，以 conversation 为公开真相继续入队，不留下“已接收但永不执行”的任务；根终态首次公开写入的瞬时失败必须在终态投影后用相同 message ID 重试。receipt / isolated-join 等带 parent 的 Supervisor continuation 不再另写 Session 终态，只保留单一后端公开事件；`runtime-task-*` 与 `runtime-public-status-*` 共享同 run 的不透明关联摘要，秒级时间戳下多个连续任务必须按实际 run 对应的 `user -> accepted -> terminal` 顺序交错展示。
-- Supervisor 进度播报：聊天消息流内保留且只保留一条当前 run 的 Runtime-owned 播报卡，由客户端从 manifest 任务图、Supervisor 结构化计划、`loopIteration`、当前动作、直接委派专业 Agent 及其持久事件确定性整理；显示当前轮次、任务 / 计划进度、活跃 Agent、最近试玩与静态检查、返工决定、代码修改和截图检查证据。同一 run 原位更新，切换 run 时替换，不调用额外模型、不追加持久 conversation，也不改变最终 assistant 回复的唯一性；任意详情必须有界且不展示绝对路径、Provider 元数据或内部指纹。
+- Supervisor 进度播报：聊天消息流内保留且只保留一条当前 run 的 Runtime-owned 播报卡，由客户端从 manifest 任务图、Supervisor 结构化计划、`loopIteration`、当前动作、直接委派专业 Agent 及其持久事件确定性整理；显示当前轮次、任务 / 计划进度、活跃 Agent、最近试玩与静态检查、返工决定、代码修改和截图检查证据。同一 run 原位更新，切换 run 时替换，不调用额外模型、不追加持久 conversation，也不改变最终 assistant 回复的唯一性；任意详情必须有界且不展示绝对路径、Provider 元数据或内部指纹。运行详情弹窗在项目或 run 身份切换的同次提交中同步关闭，不能由延迟 effect 关闭用户在新 run 状态可见后刚打开的弹窗。
 - ready-task 启动活性：`background_task.queued`、`autonomous_ready_task.scheduled`、Runner heartbeat 或执行锁已移交都不等于 child 已启动。实际持有执行权的 Runner 必须在释放项目写锁后同步写入 child 的 running task、`turn.started` 与 started journal，再把已启动 state 和 per-Agent 执行锁交给已确认开始轮询的独立 execution worker；同步启动或 worker 接管失败时，要在仍持有执行锁期间依次把 child 和 manifest Graph 节点明确落为 failed，再释放锁并让 parent 收到调度错误。`autonomous_ready_task.scheduled` 只作诊断审计，其写入失败不能阻断 durable child 启动；external client 只 wake Runner，不在客户端抢占执行。Supervisor 进度卡通过 durable `startedAt`（旧 Run 从完整 task journal 恢复，最新 task-record fallback 保持 0）显示真实持续时间，并以父 Run 与当前关联专业 Agent 的最大事件时间计算运行态活跃度：运行超过 5 分钟无新事件时显示“运行中 · 疑似停滞”和静默时长；等待用户、等待确认、Provider retry、视觉资产、进程会话、pausing 与 paused 不误报。父 Run terminal 后，持续时间冻结在父 Run 自身最后活动，不随 child 晚到收口事件增长。消息时间统一校验为 JavaScript 可表示的 Date；越界值显示“时间未知”且不写无效 `datetime`。实时回复只显示 response stream 自己的 `updatedAt`，缺失时同样显示“时间未知”，不能借用其它 Runtime 活动时间或随前端时钟漂移。该提示只提供可观测性，不改变 Runtime/manifest 正式状态。
 - ready-task manifest 漂移：父 Supervisor 必须分别判断“能否调度新节点”和“是否存在必须等待的工作”。派生视觉需要父规划修复时不再调度新 child，但当前最新且活跃的根 Run 下，只要存在确定性 runId、scheduler source、正确父绑定且 durable journal 为 queued/running 的 ready child，父 Run 就保持 `waiting-for-manifest-tasks`，不能因旧 hydration 快照把 manifest running 覆盖成 pending 而提前 fixed-graph-stalled。game-chat child 可在相同严格身份下容忍 pending 漂移；正式产物、Canvas、revision、`game.static_smoke` 与 `preview.validate` 门禁不放宽。GUI/CLI、旧父 Run、终态、确认/用户输入/reconciliation、伪造绑定或非确定性 runId 全部失败关闭；更新根 Run 后旧 child 不得继续维持新 DAG 或投影完成。
-- Supervisor 主导的条件美术路由：game-chat 的关键词、用户是否报告“美术未接入”、占位状态和当前资产探测只形成 `advisoryOnly=true` 的补充上下文，不得直接重置 Graph、预完成美术节点、选择复用/生成分支或继承历史试玩类型。当前根 Run 没有持久化 Supervisor 决策时，scheduler 不启动任何 manifest child，Supervisor Provider 必须先通过 auto-safe 的 `agent.route_manifest` 选择 `audit-existing-first` 或用户明确要求整体重做时的 `regenerate-art`。决策后首波只开放 `design-director + code-director`；`code-director` 必须先成功调用 `asset.list`，再以同一工具提交 `use-existing-art / generate-missing-art / regenerate-art` 与精确 `missingAssetSlots`。Runtime 只负责校验 root/child 身份、当前 revision、Canvas 登记、私有图集合同、四张语义切片、art manifest、覆盖 fingerprint 和路由 fingerprint，并据此把 `art-director / art-asset-plan` 投影为 completed 或 pending；缺少 art spec 若同时使图集引用合同失效，两个槽位都属于真实缺口，不能为了少调一个 Agent 伪称图集可复用。只有持久路由明确复用 `art-asset-plan` 时，根完成门才忽略 `assets/manifest.art.json(unchanged-from-run-baseline)`；其余产物、可见代码使用与试玩门禁不放宽。明确 `regenerate-art` 时两个正式图片 owner 使用严格绑定当前 root Run 的原位替换授权。纯“继续”仍走既有正式 continuation 合同；普通美术措辞不得借用更老项目的具体试玩场景。不得以增加 loop 预算、伪造 revision、机械改写 manifest 或重放历史图片 action 代替 Supervisor 决策和程序侧审计。
+- Supervisor 持久决策与单主条件美术：game-chat 的关键词、用户是否报告“美术未接入”、占位状态和当前资产探测只形成 `advisoryOnly=true` 的补充上下文，不得直接重置 Graph、预完成美术节点、选择复用/生成分支或继承历史试玩类型。当前根 Run 没有持久化 Supervisor 决策时，scheduler 不启动任何 child；Supervisor Provider 只通过 auto-safe 的 `agent.route_manifest` 提交 `game-chat-workflow-decision.v2`：`intentSummary` 是 Supervisor 自行理解并持久化的用户意图，`strategy=audit-existing-first` 只是固定安全执行策略，两者不得混用。此动作不能审计、生成、委派或替代后续判断，也不能把整体视觉重做解释成整套美术的强制重生成；成功后 Runtime 只启动唯一 `code-prototype` 主 Agent。升级恢复时严格校验 v1 sidecar 的旧 fingerprint，并从完成合同绑定的有效任务恢复 `intentSummary`；旧 `code-director` coverage/route 只作为迁移输入，不作为当前完成证据，必须由同一根 Run 的 `code-prototype` 重新 `asset.list` 后原位替换为单主合同。确定性 `code-prototype` Run 仅兼容已知 canonical task 文本版本，其余 task/binding/root 身份继续失败关闭；升级前已运行的 fixed-graph 美术 child 不再具备任何 mutation 或生图权限。主 Agent 必须以当前正式资产、Canvas 登记、私有图集合同、四张语义切片和 art manifest 判断真实缺口；完整覆盖时直接接入，不得生成或扣费。只有可证实缺失 `art-spec` 或核心 spritesheet 时，主 Agent 才可对相应 `art-director` 或 `art-asset-plan` 建立一条 durable 委派；每次最多一个活跃美术 child，child 仅可写 `assets/**`，不得修改 `game/**` 或接入/验收游戏。若两个槽位都缺失，必须先完成 `art-director`，由同一主 Run 认领其 `EvidenceReady` delivery 后，才能委派依赖规范图的 `art-asset-plan`；失败或未就绪 delivery 不得消耗不可重试的图集委派槽位。主 Agent 认领必要回执后继续同一 Run 完成素材接入、原玩法语义校验、`game.static_smoke` 与桌面/移动 `preview.validate`。绝对硬截止对嵌套美术 child 继续核验 `root -> code-prototype -> agent-delegate` 完整身份并保留未知外部生成的 reconciliation 证据。Runtime 只负责校验根/父子身份、当前 revision、路径、Canvas 登记、缺口/路由 fingerprint、写入范围及完成证据；纯“继续”仍走既有正式 continuation 合同，普通美术措辞不得借用更老项目的具体试玩场景。不得以增加 loop 预算、伪造 revision、机械改写 manifest 或重放历史图片 action 代替 Supervisor 决策和程序侧审计。
 - ready-task 对账取消续跑：未知工具结果仍停在 `needs-reconciliation` 且禁止自动重放；人工核对后显式取消原 child，保留 cancel tombstone，旧 child 和旧父 Run 按真实终态收口。若随后创建同 Session、同 Supervisor source、同有效任务语义的 continuation，新完成合同只对同时具有历史 `failed / needs-reconciliation`、最终 `cancelled` 和 durable tombstone 的 ready-task，把当前 manifest 对应 failed 节点恢复为 pending，并由 scheduler 创建全新 child Run。manifest 的读取、failed 筛选、每任务一次的 child journal 索引、证据重验和写回必须位于同一项目写锁域；较新的无 child 根 Run 只有在 durable journal 精确表明为旧 failed Graph 在进入调度前即失败时才能跨过，scheduler 自身失败必须阻断借用更老 tombstone。普通失败、无 tombstone、不同 source/Session/任务语义或证据冲突均保持失败关闭；不得复活旧 pending action、补造 observation 或把取消任务标成 completed。
 - 完成门静态分析预算：Canvas 视觉门必须先做只会提前拒绝的词法预检。经典或模块脚本同时不含大小写精确的 `import` 与 `export` 字节序列时，不运行模块依赖语义分析；纯 `export ... from` / `export * from` 仍须进入正式模块图分析。当前脚本不含目标文件名或任一已绑定 DOM 图片元素 ID 时，先低成本解码 `\\xNN`、`\\uNNNN`、`\\u{...}`、简单转义和续行；解码后仍无候选才不运行完整 Canvas alias / 函数可达性分析，解码不确定则保守进入 Oxc。存在任一候选时仍执行原 parser、semantic binding、解码后的 computed 属性/StringLiteral 路径、可达 `drawImage`、可见 Canvas、路径大小写和动态 namespace 写入门禁；HTML 中存在某个绑定元素不得使所有无关 JavaScript 单元进入重分析，禁止把词法命中当作通过条件。
 - Provider 故障展示：Provider retry 的“是否可重试”继续使用 `upstream-5xx` 等稳定类别判断，但 durable retry record 保留安全的精确 `upstream-<HTTP status>` 身份。等待态必须从真实 record 显示 HTTP 状态、`nextAttempt/maxRetries` 与当前持久退避剩余秒数，例如“Provider 上游返回 HTTP 503，准备自动重试 1/3；预计 8 秒后重试”；不得以动画或前端自增计时伪造 attempt。重试耗尽的 Runtime 私有错误只保存 `kind/httpStatus/fingerprint/chars/retryAttempt/maxRetries/retryState`，前端和持久 conversation 仅在字段顺序、范围、状态一致且无尾随正文时派生“上游服务返回 HTTP 503；自动重试已耗尽（3/3）”；其它错误使用固定安全摘要。Provider 响应正文、URL/query、凭据、本地绝对路径、fingerprint、字符数和 `[redacted ...]` 占位符均不得进入用户可见消息。
-- 跨轮阶段记录：game-chat 父 run 进入真实 completed / failed / cancelled 终态后，客户端等待 `design-director / art-director / art-asset-plan / code-director / code-prototype / preview-readiness / preview-playtest` 七项首版任务也全部投影到 completed / failed 终态，再把本轮、任务 / 计划完成度、最新试玩 / 静态检查、最近返工决定和已登记成果图片路径整理成一条 `【Supervisor 阶段记录】` 项目 assistant 消息。父 run 先终态而 manifest 仍在 hydration 时不得用陈旧 `0/7` 提前归档，要暂存终态 Runtime 并在 manifest 刷新后重试。页面初始 hydration 若直接读到缺少阶段记录的真实终态 run，也必须补写，但 `idle` 不是可归档终态。每个“项目 + 父 run”最多追加一次，进入现有 `conversation.write` 权限与项目 conversation 持久化链路，下一轮及重载后继续保留。阶段记录不是 Supervisor Runtime 正式回复，不写入 Agent Session、不增加 final assistant 数量，也不逐条复制原始事件或内部正文。
+- 跨轮阶段记录：game-chat 父 run 进入真实 completed / failed / cancelled 终态后，客户端等待唯一 `code-prototype` 主 Run 及其所有必要美术委派都已形成真实终态，再把本轮、主 Agent 进度、是否复用/补齐素材、最新试玩 / 静态检查、最近返工决定和已登记成果图片路径整理成一条 `【Supervisor 阶段记录】` 项目 assistant 消息。父 run 先终态而 child 或 manifest 仍在 hydration 时不得以陈旧快照提前归档，要暂存终态 Runtime 并在状态刷新后重试。页面初始 hydration 若直接读到缺少阶段记录的真实终态 run，也必须补写，但 `idle` 不是可归档终态。每个“项目 + 父 run”最多追加一次，进入现有 `conversation.write` 权限与项目 conversation 持久化链路，下一轮及重载后继续保留。阶段记录不是 Supervisor Runtime 正式回复，不写入 Agent Session、不增加 final assistant 数量，也不逐条复制原始事件或内部正文。
 - 图片成果：当前 manifest 新增或恢复已登记的 PNG / JPEG / WebP 资源时，聊天消息流同步显示 Runtime-owned “Supervisor 成果图片”卡，最多展示最新 4 张并随 manifest 原位更新。图片必须通过现有 `read_local_project_image_preview` 读取，只允许当前授权项目中 `assets/` 下的已登记资源，继续执行 `file.read` auto 权限、真实格式、大小、尺寸、普通文件、祖先目录和项目根边界校验；前端只接受返回路径、媒体类型和 `data:` 前缀与请求完全一致的结果。缩略图点击后使用独立模态查看器，支持按钮与滚轮缩放、指针拖拽、双击 / 按钮复位、Esc / 按钮 / 遮罩关闭，移动端占满视口；不得在聊天卡下方追加展开区。图片卡不写入 conversation，不解析 assistant 文本中的任意 Markdown / 绝对路径，也不开放 `.agent` 验收截图读取。
 - Run 接管：External Runner 模式下首次提交可能返回“旧 canonical state + 新 `acceptedRunId`”；页面必须以 `acceptedRunId` 作为本轮权威身份，在 state 尚未切换时显示“已投递，正在同步 Agent Runner”，并允许该 run 的 Tauri event 或轮询结果接管。不得把旧 idle state 当作本轮结果、过滤新 run 事件，自动预览授权也必须绑定 `acceptedRunId`。
 - 运行容器：当前项目没有由 Tauri 客户端 `PreviewRegistry` 返回的有效 `running` 预览时，页面只渲染聊天，不显示游戏区域或占位文案，顶部运行状态必须明确显示“预览未启动”，不得再使用含义不明的“未启动”；预览运行后自动显示 iframe，桌面端按“游戏 2 / 聊天 1”分栏，移动端改为上下布局。预览停止、失败或切换项目后立即移除 iframe。运行容器继续只接受当前授权项目的 `http://127.0.0.1:*`，复用现有 CSP、iframe sandbox、autoplay、fullscreen 和 gamepad 约束；远程 URL、`file://`、手填地址或陈旧 manifest 状态均不得显示。
@@ -59,27 +59,27 @@
 
 ## 2026-07-31 game-chat 输出、单轮预览与平台美术资源
 
-- 对话输出：game-chat 的 Supervisor `ready` response stream 继续以稳定身份显示；七任务目录中本轮实际启动的专业 Agent，其 `requestKind=final-reply` 且 `status=ready|committed` 的非空安全回复分别以 Agent、Session、run、request slot 和 response revision 形成 durable message ID，并带 Agent 标签逐条追加到项目聊天。条件路由跳过的美术节点只要求 manifest 正确投影为 completed，不伪造 Agent 回复。每条 Rust `eventId + publicText` 公开输出同样形成独立 durable 消息。所有这些消息通过 `append_local_conversation_message` 的顶层 `messageId` 幂等写入，事件、轮询、React StrictMode 和 hydration 重放不重复；tool-plan、半成品 stream、原始事件 detail、命令正文、绝对路径、Provider / Runner 元数据、哈希和凭据不得进入聊天。普通 `supervisor-chat` 保持原有 transient response 行为。
+- 对话输出：game-chat 的 Supervisor `ready` response stream 继续以稳定身份显示；本轮唯一主 `code-prototype` 与实际按缺口启动的美术 child，其 `requestKind=final-reply` 且 `status=ready|committed` 的非空安全回复分别以 Agent、Session、run、request slot 和 response revision 形成 durable message ID，并带 Agent 标签逐条追加到项目聊天。现有素材完整时不伪造美术 Agent 回复。每条 Rust `eventId + publicText` 公开输出同样形成独立 durable 消息。所有这些消息通过 `append_local_conversation_message` 的顶层 `messageId` 幂等写入，事件、轮询、React StrictMode 和 hydration 重放不重复；tool-plan、半成品 stream、原始事件 detail、命令正文、绝对路径、Provider / Runner 元数据、哈希和凭据不得进入聊天。普通 `supervisor-chat` 保持原有 transient response 行为。
 - 对话输出中的 `eventId + publicText` 只指需要独立进入聊天的进度事件；`turn.started` 和根 Run 终态失败事件由上一条 `runtime-public-status-*` 硬门覆盖，不得同时转成事件消息。专业 Agent child 的失败消息继续留在其 Agent Session，根项目聊天只接收 Supervisor 终态失败、明确公开进度和安全 final-reply，避免一项失败被 Runtime event 与 conversation 各播报一次。
-- 单轮收束：game-chat source 只生成至 `preview-playtest` 的 manifest seed task，试玩完成后父 Run 直接进入完成门，不再调度 `publish-strategy` / `publish-package`；`agent.schedule_ready` 必须按当前 Supervisor Run 的持久 source/profile 选择同一 source-aware scheduler，不能绕过该边界。`task.list` 对同一 root source 必须从任务行、readyTaskIds 和统计中排除两个发布节点，`agent.delegate` 也必须按 root binding 拒绝直接委派这两个节点，不能让 Provider 用“读取完整 DAG 后手工委派”恢复已裁掉的发布阶段。完成门满足且 collaboration、Provider batch、进程会话、视觉资源等非验证屏障全部清零后，Runtime 必须用确定性回复直接收束结构化计划并结束父 Run，不再请求下一次 Provider 工具计划。普通 GUI / CLI 仍执行完整发布 DAG。
-- 轮次展示：`loopIteration` 只是同一父 Run 内的 Provider / 工具规划循环，用于委派、回执、返工和验收，不是用户发起的游戏生成轮次。game-chat 的进度卡、当前工作和“最新状态”事件统一显示“本轮”，整个页面不向用户显示“第 N 轮”；完整 GUI / CLI pre-publish 任务图仍可显示 `x/14`，但首版只按七项任务显示 `x/7`（详见 2026-08-03 小节），不得把两个发布节点计入任一分母。父 Run 终态后移除运行中进度卡，只保留终态阶段记录与预览。
-- 平台美术资源：game-chat 保留正式视觉 DAG，但是否进入生成节点由 2026-08-06 的持久条件路由决定。现有正式资源覆盖完整时直接复用；存在真实缺口或 Supervisor 明确选择整体重做时，`art-director` 才通过平台 `images/generations(kind=spec)` 生成并登记 `assets/art-spec.png`，`art-asset-plan` 再以该规范图的稳定 resourceId 调用 `icon-spritesheets/generations` 生成真实透明 `assets/art-spritesheet.png`，并把响应中的 `iconImageSrcs` 下载为本地独立切片，写入 `assets/art-spritesheet-slices/manifest.json`。`code-prototype` 必须等待复用或补齐后的图集与切片清单，并在活动 Canvas 中分别绘制玩家、方块/目标、障碍/场景与反馈四类切片；规范图只作 reference，纯代码核心画面、猜测图集等分网格、整图 `<img>` / CSS 背景、完整图集直绘或只出现路径均不得完成。
+- 单轮收束：game-chat 只在 `code-prototype` 完成当前 revision 的接入、静态 smoke 与 desktop/mobile 试玩后进入完成门，不调度 `publish-strategy` / `publish-package` 或旧固定验证节点；`agent.schedule_ready` 必须按当前 Supervisor Run 的持久 source/profile 选择同一 source-aware scheduler，不能绕过该边界。`task.list` 对同一 root source 必须从任务行、readyTaskIds 和统计中排除发布节点以及不属于单主 route 的固定 DAG 节点，`agent.delegate` 也必须按 root binding 拒绝直接恢复这些节点。完成门满足且美术 delivery、Provider batch、进程会话等非验证屏障全部清零后，Runtime 必须用确定性回复直接收束结构化计划并结束父 Run，不再请求下一次 Provider 工具计划。普通 GUI / CLI 仍执行完整发布 DAG。
+- 轮次展示：`loopIteration` 只是同一父 Run 内的 Provider / 工具规划循环，用于委派、回执、返工和验收，不是用户发起的游戏生成轮次。game-chat 的进度卡、当前工作和“最新状态”事件统一显示“本轮”，整个页面不向用户显示“第 N 轮”；完整 GUI / CLI pre-publish 任务图仍可显示 `x/14`，game-chat 只显示单主及必要美术 child，不显示固定七项分母。父 Run 终态后移除运行中进度卡，只保留终态阶段记录与预览。
+- 平台美术资源：game-chat 不再执行固定视觉 DAG。现有正式资源覆盖完整时，单主 `code-prototype` 直接复用；只有它的 `asset.list` 审计证实真实缺口时，才临时委派相应美术 owner。`art-director` 通过平台 `images/generations(kind=spec)` 生成并登记 `assets/art-spec.png`，`art-asset-plan` 再以该规范图的稳定 resourceId 调用 `icon-spritesheets/generations` 生成真实透明 `assets/art-spritesheet.png`，并把响应中的 `iconImageSrcs` 下载为本地独立切片，写入 `assets/art-spritesheet-slices/manifest.json`；两者只可写 `assets/**`。`code-prototype` 必须认领复用或补齐后的结果，并在活动 Canvas 中分别绘制玩家、方块/目标、障碍/场景与反馈四类切片；规范图只作 reference，纯代码核心画面、猜测图集等分网格、整图 `<img>` / CSS 背景、完整图集直绘或只出现路径均不得完成。
 - 验证：前端运行时模型定向测试、Rust completion/source/asset 合同测试、`cargo fmt --check`、`npm run check:encoding` 与 `git diff --check` 必须全部执行；Windows 文件锁竞态只可作为既有测试失败单独记录，不得将其改写为本次改动的通过证据。
 
-## 2026-08-01 game-chat 首版七任务素材完整快车道与美术硬门
+## 2026-08-07 game-chat 单主素材审计、按需美术委派与自验收
 
-- 首版任务边界：game-chat 首版只展示 `design-director`、`art-director`、`art-asset-plan`、`code-director`、`code-prototype`、`preview-readiness`、`preview-playtest` 七项任务，进度统一显示为 `x/7`；当前根 Run 在 Supervisor 持久路由前零 child，`audit-existing-first` 决策后的首波只激活 `design-director + code-director`。code-director 审计后，完整资源把两个美术节点投影为 completed；真实缺口或整体重做才按依赖开放对应美术 owner，随后 `code-prototype` 与验证节点串行推进。不把完整 GUI / CLI 任务图的其它节点投影到该页面，也不显示内部 Provider / child loop 轮次。
+- 单主任务边界：game-chat 的根 Run 在 Supervisor 持久路由前零 child；决策后只启动 `code-prototype`。它先 `asset.list` 审计，再视真实缺口临时委派一个受限美术 child；现有资源完整时零美术委派，用户明确整体重做也不能绕过审计或把生成变成固定规则。美术 child 只写 `assets/**`，回执由主 Agent 认领并恢复同一 Run；主 Agent 随后接入素材、执行静态检查和 desktop/mobile 试玩。game-chat 不投影或调度 `design-director`、`code-director`、`preview-readiness`、`preview-playtest` 等固定节点，也不显示内部 Provider / child loop 轮次。完整 GUI / CLI 的 16 节点 DAG 不受影响。
 - 时间预算：从 game-chat 父 Run 接受用户请求开始，素材完整首版使用 `4200` 秒软预算；父 Run 与其全部 child Run、等待和回收阶段共享从 root `bound_at` 计算的 `4500` 秒绝对硬上限。该值来自现有两次串行生成各自最长 35 分钟的客户端等待合同，并为代码兜底、静态检查和双视口试玩保留 5 分钟。整个 Runtime pass 受同一 `timeout_at` 约束；硬上限内未通过完成门必须失败关闭，不得为了守时跳过图集、换普通生图或回退纯代码核心画面。即使完成证据恰好在上限后到齐，单轮确定性收束也必须再次检查累计预算并拒绝写入 `single_round_converged`。
-- Provider 次数：Supervisor 先用一个 Provider turn 理解目标并持久化条件路由；`audit-existing-first` 的首波仅请求 `design-director / code-director`，code-director 成功 `asset.list` 并提交覆盖合同后，Runtime 才确定性派发真实缺口对应的 `art-director / art-asset-plan`。完整复用不得调用图片生成接口；图集复用或登记完成后 `code-prototype` 最多执行一次 Provider 首版写入请求。软预算耗尽时只允许使用已登记图集和当前 resourceId 切片清单的确定性本地兜底，Provider 成功返回后由 Runtime 依次执行确定性的 `game.static_smoke` 与 `preview.validate`。
+- Provider 次数：Supervisor 先用一个 Provider turn 理解目标并持久化条件路由；随后唯一 `code-prototype` 主 Agent 先 `asset.list`，只有审计的精确缺口才建立相应的受限美术委派。完整复用不得调用图片生成接口；图集复用或主 Agent 认领生成回执后，仍由该主 Agent 接入、执行 `game.static_smoke` 和 desktop/mobile `preview.validate`。软预算耗尽时只允许使用已登记图集和当前 resourceId 切片清单的确定性本地兜底，不得由 Runtime 或关键词强制生成图片。
 - 可玩兜底：软预算或首版 Provider 无法及时完成时，只能为已显式实现真实语义的玩法生成完整、自包含、无远程运行依赖的中文 HTML 模板；未知玩法失败关闭，不能只替换标题后套用固定收集游戏。俄罗斯方块模板必须包含 10×20 棋盘、下落、移动、旋转、锁定、消行和触顶失败；收集模板只匹配明确收集类目标。模板必须从 `ready` 开始，包含真实 Canvas 绘制、`requestAnimationFrame`、键盘 / 触控主要操作、唯一可见且启用的 start / primary-action / restart 控件，状态 JSON 只随真实输入、状态迁移或模拟状态变化推进，并能在 primary-action 后保持 `playing`、在 restart 后稳定回到 `ready | playing`；不得在开始前固定进入 `lost`，不得通过固定失败冒充试玩通过，也不得由纯渲染帧空转 `sequence`。兜底只允许写入缺失或精确初始化占位的 `game/index.html`；存在非占位入口时，当前 `code-prototype` 必须读取并实际 patch，取得本人 `mutationRevision` 后再静态检查和试玩，不得反复用只读 smoke 冒充续作。
-- 平台图片：`art-spec.png` 只用于约束色板、材质、形状与后续派生，不是运行时背景、角色、目标或图集。`art-asset-plan` 必须以其稳定资源 ID 走专用 icon-spritesheet 路由，透明像素、generation route/kind、同画布归属和 reference resource ID 继续由 Runtime 验证。完整透明图集在编辑器合同中即使产生 `sliceWarning` 仍可登记，但 game-chat 不能据此猜测 atlas 坐标；图集 resourceId 缺失或空白时必须在任何本地写入前失败，四个切片均须保留与整图完全一致的 `sourceResourceId`，切片数量也必须在正式图集登记前严格等于四，多或少都失败关闭。四类唯一性按尺寸与解码后的规范 RGBA 像素摘要判断，不能用不同 PNG 压缩或 ancillary chunk 冒充不同素材。主图、四张 canonical 切片和切片清单必须共同提交，并把主图/切片摘要及 Canvas 身份冻结到 `.agent/runtime/art-spritesheet-contract.json` 私有回执；后续主图安装、回执或登记失败时恢复旧合同，避免出现旧图集绑定新切片。进程在固定主图落盘后崩溃时，保留的 generation 账本只允许按远端预期摘要幂等补齐同一组合同，路径内容冲突继续失败关闭。全部切片下载累计最多 `32 MiB`。完成门重新读取本地素材时仍执行相同文件大小、解码内存、内容摘要、规范像素摘要、可见 alpha 与四类唯一性校验，并要求公开切片清单、当前 Canvas 登记与私有回执完全一致，后续代码 Agent 不能通过同时改写素材和公开清单重定义合同。`postprocess-failed-source-preserved`、无真实 alpha、缺文件或缺登记同样失败关闭。首版只在 `preview-playtest` 后单轮收束，不进入发布节点。
-- 关联验收：快车道必须分别验证 Supervisor 决策前零 child、审计首波只有 design/code、完整覆盖零图片生成、精确缺口只启动对应 owner、显式重做两个正式 owner、`art-asset-plan` 在代码前完成、`x/7` 投影、实际启动的专业 Agent 安全 final-reply、跳过节点正确终态投影、4200 / 4500 秒累计预算、规范图到 icon-spritesheet 的真实引用、`iconImageSrcs` 本地持久化与资源 ID 绑定、失败续跑目标继承、非占位入口禁止整文件覆盖、纯代码核心画面、猜测单个 atlas 裁切与整图展示失败、四类独立切片可见使用通过、action-driven `sequence`，以及当前 revision 的静态 smoke 与浏览器试玩。
+- 平台图片：`art-spec.png` 只用于约束色板、材质、形状与后续派生，不是运行时背景、角色、目标或图集。`art-asset-plan` 必须以其稳定资源 ID 走专用 icon-spritesheet 路由，透明像素、generation route/kind、同画布归属和 reference resource ID 继续由 Runtime 验证。完整透明图集在编辑器合同中即使产生 `sliceWarning` 仍可登记，但 game-chat 不能据此猜测 atlas 坐标；图集 resourceId 缺失或空白时必须在任何本地写入前失败，四个切片均须保留与整图完全一致的 `sourceResourceId`，切片数量也必须在正式图集登记前严格等于四，多或少都失败关闭。四类唯一性按尺寸与解码后的规范 RGBA 像素摘要判断，不能用不同 PNG 压缩或 ancillary chunk 冒充不同素材。主图、四张 canonical 切片和切片清单必须共同提交，并把主图/切片摘要及 Canvas 身份冻结到 `.agent/runtime/art-spritesheet-contract.json` 私有回执；后续主图安装、回执或登记失败时恢复旧合同，避免出现旧图集绑定新切片。进程在固定主图落盘后崩溃时，保留的 generation 账本只允许按远端预期摘要幂等补齐同一组合同，路径内容冲突继续失败关闭。全部切片下载累计最多 `32 MiB`。完成门重新读取本地素材时仍执行相同文件大小、解码内存、内容摘要、规范像素摘要、可见 alpha 与四类唯一性校验，并要求公开切片清单、当前 Canvas 登记与私有回执完全一致，后续代码 Agent 不能通过同时改写素材和公开清单重定义合同。`postprocess-failed-source-preserved`、无真实 alpha、缺文件或缺登记同样失败关闭。game-chat 首版由 `code-prototype` 在同一主 Run 完成静态 smoke 和试玩后单轮收束，不进入发布节点。
+- 关联验收：快车道必须分别验证 Supervisor 决策前零 child、持久路由后只启动 `code-prototype`、主 Agent 成功 `asset.list` 后才可判断缺口、完整覆盖零图片生成/零委派、精确缺口只委派对应 owner、整体重做仍先审计且不产生无关委派、美术 child 对 `game/**` 写入拒绝而 `assets/**` 允许、回执恢复同一主 Run、主 Agent 自行完成接入/静态 smoke/desktop-mobile 试玩、4200 / 4500 秒累计预算、规范图到 icon-spritesheet 的真实引用、`iconImageSrcs` 本地持久化与资源 ID 绑定、失败续跑目标继承、非占位入口禁止整文件覆盖、纯代码核心画面、猜测单个 atlas 裁切与整图展示失败、四类独立切片可见使用通过与 action-driven `sequence`。完整 GUI / CLI 的固定 16 节点 DAG 另行保持原有回归。
 
 ## 2026-08-03 game-chat 开发态同源与持久输出修复
 
-- 开发态启动必须在 Tauri CLI 之前预检固定 `3080`。现有 marker 只包含 API target，不能证明监听器属于当前 worktree；因此只有端口空闲时才允许继续，任何已存在的 AGC Vite、非 HTTP 监听器或其它服务都必须在原生窗口创建前失败关闭。启动器不擅自终止无法证明归属的旧服务，也不得把当前 Rust 壳 / Runner 与其它 worktree 的旧 Vite 前端混用。Tauri CLI 任意退出后，外层启动器必须有界收束已启动的客户端进程树，避免 `beforeDevCommand` 失败后留下假在线窗口。
-- game-chat root binding 的 `source` 必须精确为 `project-supervisor-game-chat`。只有该持久 source 才能进入 Supervisor 决策前零 child 的条件 lane；`audit-existing-first` 路由后先运行 `design-director + code-director`，再按覆盖合同选择复用或补齐美术，最后推进 `code-prototype → preview-readiness → preview-playtest`、单轮确定性收束和自动预览。若绑定为 `project-supervisor-gui`，必须视为启动链路错误，不能用完整 16 节点 DAG 的运行状态伪装 game-chat 进度。
-- source-aware lane 的 ready child 可能在 UI hydration 写回时短暂恢复为 `Pending`。该例外必须从当前 root source、持久工作流决策和资产路由解析本轮已开放节点，不得硬编码旧三 Director 首波；当前审计首波是 `design-director / code-director`，后续美术、code prototype 与 preview child 仍严格拒绝未授权或不满足依赖的 `Pending` 收束。
+- 开发态启动必须在 Tauri CLI 之前解析并预检 AGC Vite 最终地址。Linux 使用系统级用户端口段的 `start + 5` 槽位并只在本段内漂移，Windows / macOS 以 `3080` 为兼容首选；启动器通过 `GENARRATIVE_AGC_VITE_PORT` 绑定 `beforeDevCommand` 和配套后端预留，通过 Tauri CLI `--config` 绑定 `build.devUrl`，并通过 Vite CLI `--port` 绑定 `strictPort` 监听。任何竞态中已存在的 AGC Vite、非 HTTP 监听器或其它服务都必须在原生窗口创建前失败关闭。启动器不擅自终止无法证明归属的旧服务，也不得把当前 Rust 壳 / Runner 与其它 worktree 的旧 Vite 前端混用。Tauri CLI 任意退出后，外层启动器必须有界收束已启动的客户端进程树，避免 `beforeDevCommand` 失败后留下假在线窗口。
+- game-chat root binding 的 `source` 必须精确为 `project-supervisor-game-chat`。只有该持久 source 才能进入 Supervisor 决策前零 child 的单主 lane；Supervisor 持久 intent 后先运行 `code-prototype`，由它按权威审计结果选择复用或暂时委派受限美术，再在同一主 Run 完成接入、静态 smoke、desktop/mobile 试玩、单轮确定性收束和自动预览。若绑定为 `project-supervisor-gui`，必须视为启动链路错误，不能用完整 16 节点 DAG 的运行状态伪装 game-chat 进度。
+- source-aware lane 的主 Run 或其经授权美术 child 可能在 UI hydration 写回时短暂恢复为 `Pending`。该例外必须从当前 root source、持久工作流决策、单主 route 与 child delegation 解析本轮已开放工作，不得从旧七节点图硬编码重启 Director、验证或试玩节点；未授权 child、第二个活跃美术 child，或缺少成功 `asset.list` 审计的美术委派仍严格失败关闭。
 - 专业 Agent 的非流式 final reply 继续由既有 finalization journal 重建并提交 `responseStream`。`streaming / ready` 投影仍必须匹配当前项目 revision；已经 finalization 提交的 `committed` 回复以 Agent / Session / run / request slot / response revision 稳定身份为准，不得因后续阶段推进项目 revision 而从 game-chat 查询中消失。
 
 ## Runtime 边界
@@ -601,7 +601,7 @@ game-project/
 ## 当前最小落地
 
 - `apps/ai-game-creator-shell` 是独立 Tauri App，不复用 `apps/desktop-shell`。
-- 独立客户端启动时先进入平台登录检查；未登录页默认展示手机号验证码登录，并保留密码登录切换。验证码登录调用平台后端 `/api/auth/phone/send-code` 与 `/api/auth/phone/login`，密码登录继续调用 `/api/auth/entry`；Tauri dev 下 `/api` 走固定 3080 Vite 代理，发布版静态窗口下登录请求默认直连本机配套 `http://127.0.0.1:8082` API，网络层失败时展示登录服务不可达提示，不裸露 WebView 的 `Load failed`。
+- 独立客户端启动时先进入平台登录检查；未登录页默认展示手机号验证码登录，并保留密码登录切换。验证码登录调用平台后端 `/api/auth/phone/send-code` 与 `/api/auth/phone/login`，密码登录继续调用 `/api/auth/entry`；Tauri dev 下 `/api` 走本轮动态 AGC Vite 代理，发布版静态窗口下登录请求默认直连本机配套 `http://127.0.0.1:8082` API，网络层失败时展示登录服务不可达提示，不裸露 WebView 的 `Load failed`。
 - `npm run agc` 的本地 SpacetimeDB owner identity 以独立 `spacetimeDataDir` 为作用域，不绑定可能漂移的监听端口；旧端口作用域记录仅在同一 data dir 下身份唯一时自动迁移，出现多个不同旧身份时失败关闭。`.app/dev-stack.json` 必须记录规范化 `spacetimeDataDir`，独立壳只复用数据库名和该目录同时匹配且健康的后端，旧 schema 状态或共享目录状态缺少此字段时不得复用。POSIX 子进程在 `spawn` 返回时立即登记 `error / exit` 生命周期、保存 detached leader 的 PGID 并把句柄交给外层；即使 direct leader 已先退出，也必须继续向负 PGID 发信号清理同组后代。后端 ready 前的 SIGINT、SIGTERM、超时或 ENOENT 都必须走同一进程组清理链路，不能遗留 npm、Cargo 或 SpacetimeDB。非 Linux Runtime 执行 `project.verify` 时，`npm run` 参数校验必须允许受控的 `--silent`、`--ignore-scripts` 位于脚本名前，并继续拒绝缺少真实脚本名的调用。
 - Tauri Rust 入口保持薄壳：`src-tauri/src/main.rs` 只保留共享类型 / 常量、模块声明、CLI preflight、`tauri::Builder`、运行时配置初始化和 `invoke_handler` 清单；命令行入口放在 `cli.rs`，Tauri command 包装放在 `commands.rs`，运行时配置与 LLM 配置检查放在 `config.rs`，Agent loop 与生成编排放在 `agent.rs`，上传 / 画板 / 平台美术生成接入放在 `assets.rs`，本地项目文件、记忆、对话、权限、checkpoint、manifest 和通用路径工具放在 `project.rs`，本地 HTTP 预览与 preview 命令放在 `preview.rs`，旧窗口兼容命令放在 `windows.rs`，Rust 单测放在 `tests.rs`。后续继续拆分时保持 Tauri command 名、JSON 字段、`.agent/*` 路径和错误语义不变。
 - 本地项目初始化会创建 `game/`、`assets/`、`memory/`、`memory/agents/`、`exports/`、`.agent/logs/`，写入 `.agent/manifest.json`，生成 append-only JSONL 本地项目索引 `.agent/agent.db`，并生成默认 `game/index.html`。
@@ -627,7 +627,7 @@ game-project/
 - 终端可用 `npm run ai-game-creator-shell:check` 跑 v1 开发验收：壳 typecheck、`platform-llm` 网关测试、共享契约测试、Tauri Rust 测试和无密钥本地 provider 端到端 smoke；已退役的 `platform-agent` 不再进入 workspace 或该门禁。
 - 终端可用 `npm run ai-game-creator-shell:agent-run -- /绝对项目路径 "游戏创作需求"` 跑一次真实 LLM 生成、落盘、`game.static_smoke` 和本地 HTTP 预览；发布 App 读取 Tauri 应用配置目录中的 `game-creator.config.json`，开发 CLI 无 AppHandle 时才读取仓库旁边的配置模板和 gitignored 本机覆盖文件，不把 API Key 写入仓库或项目文件。自动验证可加 `--no-wait`，例如 `npm run ai-game-creator-shell:agent-run -- --no-wait /tmp/genarrative-ai-game-test "像素风反弹弹幕厨房"`，生成预览 trace 后立即停止本地预览，避免终端卡在回车等待。默认 API kind 为 `openai_responses`；旧 Chat Completions 兼容网关设置 `llm.apiKind` 为 `openai_chat`，Anthropic Messages 网关设置 `llm.apiKind` 为 `anthropic`。真实 OpenAI-compatible 网关建议设置 `llm.stream` 为 `true` 跑 Planner 和 Generator，避免长请求非流式空闲断连。
 - 终端可用 `npm run ai-game-creator-shell:agent-run:smoke` 跑一次无密钥本地端到端 smoke：脚本启动本机 OpenAI-compatible SSE 流式测试 provider，预置一个本地上传图片和一个本地上传音频，复用真实 `--agent-run`、Planner / Orchestrator / 角色 agent / Generator / Evaluator loop、本地落盘、`game.static_smoke` 和本地 HTTP 预览，并断言每次 provider 请求都使用 `stream: true`、Planner 与 Generator 分别命中自己的 `agentLlm` provider 配置、provider prompt 收到图片与音频资产上下文以及最近对话上下文、生成 HTML 引用这些资产、预览服务能用 `GET` 读取 `/assets/...`、用 `HEAD` 返回真实资源长度和对应 MIME、headless Chrome 打开预览后至少执行一帧游戏 JS，且通过确定性亮色探针采样证明 canvas 不是空白画布、`.agent/run.latest.json` 的 step group 覆盖 design / balance / art / audio / code / publishing 六组、第二轮会重跑 Evaluator 命中任务及其下游影响任务，未受影响角色 carry-over；随后脚本自动给 CLI 发送回车停止预览。该脚本只用于开发验证，不进入产品生成路径。
-- `npm run ai-game-creator-shell:dev` 的 Tauri `devUrl` 固定为 `http://127.0.0.1:3080/`，Vite 必须 `strictPort` 对齐；`beforeDevCommand` 先复用已经跑在 3080 且页面标题为 `AI 游戏创作` 的本 app Vite server，否则才启动新的 Vite，若端口被其它服务占用则直接失败并提示释放端口。
+- `npm run ai-game-creator-shell:dev` 必须经受控启动器解析 AGC Vite 端口；Linux 默认使用用户端口段的 `start + 5`，非 Linux 保留 `3080` 兼容首选。启动器用动态 Tauri `build.devUrl`、`GENARRATIVE_AGC_VITE_PORT` 和 Vite CLI `--port` 保证 WebView、`beforeDevCommand`、配套后端预留和 Vite `strictPort` 对齐；不得复用无法证明 worktree 归属的现有 Vite，最终端口被竞态占用时直接失败。
 - AI 游戏创作 App 的本地后端使用 gitignored 的 `server-rs/.spacetimedb/ai-game-creator/data`，不复用主站旧 standalone 数据目录。启动器从本地 `/v1/identity` 获取并持久化 API identity，再通过数据目录内 `0600` 的独立 `dev-cli/cli.toml` 发布模块；不得读取或覆盖开发者全局 SpacetimeDB 登录，也不得回退到每次变化的 `--anonymous` 身份。发布失败时 API 和 Vite 不得继续启动旧 schema，避免 `external_generation_job` 等缺表订阅进入持续重试。
 - `start-dev-stack.mjs` 在 POSIX 下以独立进程组托管后端和 Vite，关闭 Tauri 或任一子进程失败时必须收束整组；macOS 不注册仅支持 Windows/Linux 的 api-server 进程指标 observable callback，避免每轮指标采集重复输出平台不支持告警。
 - Unix 下 Agent DB、External Runner owner 和 tool-plan handoff 的相对句柄复核必须同时比较设备号、inode 和文件类型；`libc::stat` 的 `st_dev / st_ino` 先按 Rust `MetadataExt` 的 Unix 口径规范为 `u64` 再比较，保持 Linux 和 macOS 的同一安全语义，不得为了通过 macOS 编译而删除路径替换检测。
@@ -867,7 +867,7 @@ game-project/
 - 自动验收现在严格要求 manifest 恰好包含固定 16 个不重复 task ID 且全部为 `completed`，并逐任务核对当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物存在并满足文件 / JSON / 非占位入口检查，配置画布 API Key 时再增加 `art-spec / ui-prototype / art-spritesheet` 三张图片。PNG 验收不止检查 magic / IHDR / 比例，还会校验 chunk CRC、zlib 解压、scanline 长度、索引色 PLTE 和未知 critical chunk。Runtime 根 Supervisor 的完成合同已升级为 `game-creator-autonomous-completion-contract.v2`，`baselineArtifacts` 必填并纳入指纹，旧 v1 或缺基线合同失败关闭；最终门禁要求最后一次验证工具是 `game.static_smoke`、状态通过且 `verifiedRevision == currentRevision`。`preview.validate` 回执必须绑定同一 Agent、run、current revision、当前 `game/index.html` 摘要、固定试玩场景、持久浏览器报告以及 desktop / mobile 两张截图的路径、摘要和 PNG 身份，任一证据缺失、变化、过期或来自其它 run / revision 都阻止最终回复。旧两图合同的确定性证据不替代新三图 DAG 验收；新合同实现后必须新起独立单轮。
 - `design-foundation` 已增加专属职责边界：项目文件只允许写 `memory/project.md` 与 `game/game_design.md`；配置 External Editor API Key 且合同要求界面原型时，只额外允许固定 `assets/ui-prototype.png`。它不得创建、修改、删除或补丁 `game/index.html`，不得改动其它程序实现、发布、音频或美术素材，也不得调用 `preview.start`、`preview.validate`、`game.static_smoke`，或借 `command.exec / command.start / command.run_limited` 启动预览服务、浏览器、Playwright 和桌面 / 移动试玩。程序和质量 Agent 的共享 Runtime 工具合同不因此缩减；有 / 无画布配置和其它 Agent 不受影响的聚焦回归为 `3/3` 通过。
 - `canvas.asset_generate.replaceExisting` 默认并必须保持 `false`；只有静态专业 Agent 的 `delegated-*` 唯一 repair run 才能申请 `true`。Runtime 要求当前 delivery 带 `repairOfDelegationId`，原 delivery 已被同一父 Agent / 父 run 认领，原始与返工合同的目标 Agent 和精确 `expectedArtifacts` 路径一致；普通 run、未声明路径、错误 Agent、未认领原交付或缺失原图都失败关闭。图片生成仍服从 `art-director` / `design-foundation` / `art-asset-plan` 的固定输出路径、比例、尺寸、kind 和 label，禁止先删除正式图片；请求前记录旧文件 SHA-256，外部生成返回后在项目写锁内复核，旧图在网络请求期间变化即拒绝覆盖。授权替换先写私有临时文件，再以备份 / rename 切换；落盘或 manifest 登记失败时恢复旧图，不把新旧文件并存状态当作成功。
-- 2026-07-28 起，在既有 16-task manifest 内固定正式视觉 DAG，不新增平行任务系统：`art-director` 先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`；`design-foundation` 使用该规范图的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，再通过同一 images 接口的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 `assets/art-spec.png` 资源 ID 作为必填 `referenceImageSrc` 调用 `/api/external/v1/editor/icon-spritesheets/generations`，传入具体 `iconDescriptions`、`screenColor=auto`、同名画布 / 素材库与 `canvasCompletion`，生成透明 `assets/art-spritesheet.png`。`generationInputs.artSpec` 只是辅助结构化上下文，不能代替真实 `art-spec.png`；严禁把 `assets/ui-prototype.png` 当作图集规范图。规范图缺失、未登记为当前画布的 `icon-spec` 或缺少稳定资源 ID 时，两个下游任务均等待 `art-director`，不得退回普通生图。UI extraction 只适用于已有且带红框标注的 UI 设计图，不用于生成完整 UI，也不进入本次 canonical DAG。单波最多 `3` 个静态职责的资源上限保持不变，只调整现有任务的依赖边与就绪顺序。图集返回 `warning` 时以 `postprocess-failed-source-preserved` 源图保留语义失败关闭，不把不透明源图登记为正式 spritesheet，也不自动重试；仅有 `sliceWarning` 时完整透明图集仍可登记，但必须原样保留切片失败原因。客户端下载后还要解码 PNG 并确认至少存在一个 alpha 小于 255 的像素，未形成真实透明像素时拒绝落盘和 manifest 登记。
+- 2026-07-28 起，在既有 16-task manifest 内固定正式视觉 DAG，不新增平行任务系统：`art-director` 先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`；`design-foundation` 使用该规范图的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，再通过同一 images 接口的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 `assets/art-spec.png` 资源 ID 作为必填 `referenceId` 调用 `/api/external/v1/editor/icon-spritesheets/generations`，传入具体 `iconDescriptions`、`screenColor=auto`、同名画布 / 素材库与 `canvasCompletion`，生成透明 `assets/art-spritesheet.png`。`generationInputs.artSpec` 只是辅助结构化上下文，不能代替真实 `art-spec.png`；严禁把 `assets/ui-prototype.png` 当作图集规范图。规范图缺失、未登记为当前画布的 `icon-spec` 或缺少稳定资源 ID 时，两个下游任务均等待 `art-director`，不得退回普通生图。UI extraction 只适用于已有且带红框标注的 UI 设计图，不用于生成完整 UI，也不进入本次 canonical DAG。单波最多 `3` 个静态职责的资源上限保持不变，只调整现有任务的依赖边与就绪顺序。图集返回 `warning` 时以 `postprocess-failed-source-preserved` 源图保留语义失败关闭，不把不透明源图登记为正式 spritesheet，也不自动重试；仅有 `sliceWarning` 时完整透明图集仍可登记，但必须原样保留切片失败原因。客户端下载后还要解码 PNG 并确认至少存在一个 alpha 小于 255 的像素，未形成真实透明像素时拒绝落盘和 manifest 登记。
 - 旧项目已有同路径派生图但缺少上述 provenance 时，一律标记为 legacy，不得只因文件、kind 或通用视觉检查存在就完成。原位替换仍走显式 repair：`design-foundation` 与 `art-asset-plan` 先在同一 Supervisor 批次分别建立 owner 精确原合同并交付 `needs-repair`，父 run 认领后再在同一批次分别发起各自唯一 repair；两个 repair 合称一个显式视觉返工阶段。`art-director` 不得跨 owner 声明或替换 UI / spritesheet，Runtime 在委派落盘前就拒绝这类合同，不再等到生图阶段才失败。
 - 2026-07-27 新起的“16 任务正式产物 + 两张真实画布图片 + current revision 静态 / 双视口浏览器 / PNG 证据 + 受限 repair 替换”独立外部 Provider 验收，使用 `npm run agc:test:chat -- --timeout-minutes 75`，约 `59m50s` 后以退出码 `0` 完整 **PASS**。同一轮真实生成并登记 `assets/ui-prototype.png`（`2829418` bytes）与 `assets/art-spritesheet.png`（`1361906` bytes），固定 `16` 个 manifest task 均为当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物、两张 PNG、当前 revision 的 `game.static_smoke`、desktop / mobile `lane-defense-v1` playtest、浏览器报告与截图全部通过。`turn.report=settled` 且唯一 assistant，busy / pending / running / confirmation / user-input / reconciliation 均为 `0`；隔离 Runner、一次性项目和隔离 AppData 已自动清理。此前失败轮继续独立保留，不与本轮拼接；未来合同变化仍须新起完整轮次复验。
 - 2026-07-27 补充 tool-plan 成功响应交接的内容边界：Provider 的自然语言计划叙述，以及结构化 arguments 中 `body / code / content / css / html / newText / oldText / patch / script / text` 等源码内容字段，只检查真实密钥 token 形状、凭据头标记和不安全控制字符；仅仅提及 `.env` 或 `game-creator.config` 不能阻断已经计费的安全响应。结构化输入中的敏感 JSON key、非内容字段中的配置痕迹或绝对路径、真实 token、容量、thinking、身份、顺序和账本完整性门禁仍失败关闭。成功 handoff 失败进入 reconciliation 时，Runtime 额外只持久化受控 `failureKind`、脱敏错误 SHA-256 和字符数，不保存 Provider 正文、function arguments、密钥或绝对路径。定向回归覆盖叙述/源码字段放行、`.env.local` 路径和真实 token 拒绝、全部 tool-plan handoff 回归及诊断零正文。
@@ -905,7 +905,7 @@ game-project/
 
 ## 2026-07-31 长耗时与恢复收口
 
-- `autonomous-game-build` 的固定 manifest DAG 是唯一缺省首轮专业执行链。缺省 collaboration policy 不再额外强制 `code-prototype / quality-review / art-*` 静态首波，Runtime 也不再按 Editor Key 或已有图片偷偷追加 Agent。2026-08-03 起，显式项目 policy 或旧 batch 恢复若进入首批 `agent.delegate` 兜底，同样只能激活 `design-director / art-director / code-director`，不得提前激活底层 Agent；这条兜底不能在默认 manifest 前复制同职责委派。
+- 除持久 `project-supervisor-game-chat` 单主 route 外，`autonomous-game-build` 的固定 manifest DAG 是唯一缺省首轮专业执行链。缺省 collaboration policy 不再额外强制 `code-prototype / quality-review / art-*` 静态首波，Runtime 也不再按 Editor Key 或已有图片偷偷追加 Agent。2026-08-03 起，显式项目 policy 或旧 batch 恢复若进入首批 `agent.delegate` 兜底，同样只能激活 `design-director / art-director / code-director`，不得提前激活底层 Agent；这条兜底不能在默认 manifest 前复制同职责委派。game-chat 例外只允许持久路由后的 `code-prototype`，以及该主 Run 经审计后临时建立的受限美术 delivery。
 - `preview-readiness` 只有在自己的 child run 持有当前 project revision 的 `game.static_smoke=passed` 凭证后才能完成；`preview-playtest` 作为根 Supervisor 的直接 manifest child，必须解析并写入根完成合同的当前 revision browser receipt，报告、desktop/mobile 截图及摘要复核通过后才能投影 manifest completed。
 - 浏览器未发现、临时环境不可建、启动超时或在 WebSocket URL 解析前退出统一分类为 `preview-infrastructure-unavailable`。首个持久 observation 后收束当前 action batch并失败结束 child/root run，禁止继续用 Provider 逐轮规划同一 revision 的重复启动；普通页面/玩法验收失败仍保留为业务失败，不混入基础设施分类。
 - game-chat release 在 `CloseRequested / ExitRequested` 前复用 Runner durable idle probe；只要存在 process session、pending/finalization/provider/tool-plan handoff 或非终态 Agent queue/phase，就阻止关闭并提示先完成、暂停或取消。不可撤销的最终 `Exit` 不再作为唯一保护点，Windows Job Object 的 child-owned 安全边界保持不变。
@@ -924,7 +924,7 @@ game-project/
 
 - `.agent/manifest.json` 的存储写边界使用同目录持久文件锁跨线程、跨进程串行化；锁必须覆盖旧 manifest 读取、不可变版本前缀校验、临时文件安装和安装后回读一致性校验。锁文件拒绝符号链接、非普通文件和异常所有权 / 硬链接；Windows 使用不共享写句柄，Unix 使用 `O_NOFOLLOW + flock`。旧快照在新版本安装后只能被拒绝，不能覆盖已追加版本。
 - 后台 Agent 的 manifest 变化以共用 Runtime 状态投影 / 终态 emitter 作为失效因果点：`game-creator-agent-runtime-update` 的 Rust / TypeScript DTO 固定携带 `manifestInvalidated`，且 App 必须在 Supervisor、selected agent、session 和 run 身份的任何 early return 之前处理失效。GUI 进程内 Runtime 直接发该事件；External Runner 是独立进程、没有 GUI `AppHandle`，因此 Runner 协议 v5 的 `runner.attach_gui_owner` 必须登记 GUI 创建的随机 loopback 端口和 64 位随机令牌，Runner 的同一 emitter 通过受令牌保护的短连接转发 `game-creator-manifest-invalidated`。两条路径都只传项目路径与 Agent 身份，不复制 manifest，也不靠轮询补偿。
-- App 收到当前项目的 Runtime / relay 失效后重新调用 `get_local_game_manifest`。重读按项目 single-flight 合并事件风暴；读取中再到达失效只追加一轮串行重读，不并发提交同项目响应。应用结果同时校验组件仍挂载、当前项目路径和项目 scope version；项目切换、组件卸载或旧 scope 的迟到响应不得覆盖新项目。Project Supervisor 对外发布前以“revision 前读 -> manifest -> revision 后读”取得一致快照，再通过 `onManifestChange(projectPath, manifest, metadata)` 携带 `projectId + revision + source`；启动器按 `projectPath + projectId` 只接受更高 revision，同 revision 只接受内容一致的重复，旧轮询和同 revision 分叉都不得覆盖。资源列表、依赖图输入、任务状态、运行入口和正式版本卡必须在当前页面实时重投影，不要求关闭或重开项目。
+- App 收到当前项目的 Runtime / relay 失效后重新调用 `get_local_game_manifest`。重读按项目 single-flight 合并事件风暴；读取中再到达失效只追加一轮串行重读，不并发提交同项目响应。应用结果同时校验组件仍挂载、当前项目路径和项目 scope version；项目切换、组件卸载或旧 scope 的迟到响应不得覆盖新项目。Project Supervisor 对外发布前以“revision 前读 -> manifest -> revision 后读”取得一致快照，再通过 `onManifestChange(projectPath, manifest, metadata)` 携带 `projectId + revision + source`；启动器按 `projectPath + projectId` 只接受更高 revision，同 revision 只接受内容一致的重复，旧轮询和同 revision 分叉都不得覆盖。资源列表、依赖图输入、任务状态、运行入口和正式版本卡必须在当前页面实时重投影，不要求关闭或重开项目。集成测试记录“事件未重新打开项目”的调用基线前，必须先等待项目写入最近列表后触发的只读目录状态刷新完成，不能把这项合法后台检查误算成失效事件副作用。
 - `.agent/agent.db` 有界尾部读取报告截断时，审计 producer 映射失败关闭，不生成基于不完整审计的 producer、task flow 或对应任务环。前端收到截断 DTO 时只剔除 `producerAssignments`、`taskFlows` 与对应 `cyclicTaskIds`；Rust 根据当前 manifest、精确资源引用和仍可信任务深度下限返回的 `dependencyDepths` 继续保留，前端只校验资源仍存在且深度为非负安全整数，不得自行重算或压平权威深度。精确引用边、reference connection index、`cyclicResourceIds` 与 unresolved references 同样继续保留。
 - 资源依赖 SVG 继续作为不可交互装饰层隐藏，但 dependency 画布通过 `aria-describedby` 提供当前可见精确引用和任务流的文本等价列表。中央资源聚焦按稳定 `resourceId` 驱动焦点状态：仅 `null -> id` 或 `idA -> idB` 聚焦详情 region，同一 ID 的 manifest 重投影不得抢走音频、视频、链接或关闭按钮焦点；显式收起和 Escape 恢复画布滚动并优先聚焦原触发卡片。聚焦资源被删除时清理 stale focused / selected ID，关闭详情并把焦点落到资源搜索框；项目切换或运行视图切换清除旧恢复意图，不得恢复旧项目卡片。橙色引用线及箭头使用对 `#fffdfa` 画布达到至少 `3:1` 的颜色。
 

docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md

@@ -0,0 +1,181 @@
+# 图片画布游戏场景生成链路
+
+更新时间：`2026-08-08`
+
+## 1. 目标
+
+在现役图片画布中补齐单张、静态、非分层游戏环境背景的专用生成链路：
+
+```text
+首页游戏场景 / 画布底部游戏场景
+-> 场景专用生成表单
+-> 后端确定性组装场景 Prompt
+-> 现有 editor_image_generation 队列与 Worker
+-> 现有计费、失败、资源持久化和 canvasCompletion
+```
+
+本期不是 Agent 工作流，不新增场景 Agent、场景 Worker、场景任务表或场景专属计费系统。
+
+## 2. 输入和默认值
+
+用户输入：
+
+- 必填画面内容。
+- 视觉风格：日系动画、清透水彩、平面几何、定格模型、自定义。
+- 自定义风格下必填自定义画风。
+- 可选用户参考图，沿用普通图片生成的参考图处理能力。
+- 图片比例、清晰度和图片模型。
+
+默认值：
+
+- 图片比例：`16:9`。
+- 清晰度：`1K`。
+- 模型：`gemini-3.1-flash-image-preview`，产品展示名沿用现有画布。
+- 视觉风格：日系动画。
+- 参考图：无。
+
+`model`、`aspectRatio`、`imageSize` 继续使用现有编辑器的字符串契约、模型选项、尺寸选项和后端标准化函数，不维护场景专属枚举列表。
+
+## 3. 前端边界
+
+前端只保存和提交结构化场景意图，不保存或拼接完整场景 Prompt。
+
+正式场景状态使用 `GenerateDialogState.mode = "scene"`，不沿用前端壳中的 `generatorVariant = "game-scene"` Demo 标识。
+
+交接壳复用范围：
+
+- 画风选择控件、交互和局部样式。
+- 自定义画风条件输入框。
+- 底部游戏场景按钮。
+- 四张固定画风预览图。
+
+不复用：
+
+- Demo `App.tsx`。
+- `setTimeout` 模拟生成。
+- FileReader Data URL 正式请求。
+- 复制出的整套画布和缩减版类型。
+
+四张固定图片只用于前端预览，不进入 `generationReferences`，不随生成请求提交。保留原分辨率，只做轻量无损压缩；画风菜单打开时不同时挂载全部预览图，只在用户悬停、键盘聚焦或点击对应预览入口时按需挂载当前图片。点击同一入口可关闭预览，保证无 hover 的触屏设备可用。
+
+## 4. API 契约
+
+主站新增：
+
+```text
+POST /api/editor/scenes/generations
+```
+
+请求字段：
+
+```text
+sceneContent
+stylePreset
+customStyle?
+model?
+aspectRatio?
+imageSize?
+referenceImageSrcs?
+projectId?
+generationInputs?
+assetFolderId?
+assetLabel?
+canvasCompletion?
+```
+
+请求不接受前端组装后的完整 `prompt`。通用 `/api/editor/images/generations` 与 `/api/external/v1/editor/images/generations` 共用同一边界校验，均拒绝 `kind = scene` 或 `assetKind = scene`，防止调用方绕过结构化字段校验和后端 Prompt 组装。External v1 当前没有场景专用路由，因此不能通过通用图片接口提交结构化场景；主站 `/api/editor/scenes/generations` 构造规范请求后直接复用队列，不经过通用入口校验。
+
+完整 Provider Prompt 仍只能由后端生成。
+
+场景参考图沿用普通图片生成的客户端前置门禁，最多 5 张；超限时不得发送 HTTP 请求。场景生成 POST 使用生成专用零重试策略，避免 inline 响应丢失后重复调用 Provider。
+
+后端对模型、比例和清晰度先沿用 `normalize_editor_generation_options` 标准化，再使用标准化比例决定画幅描述和入队价格。
+
+## 5. Prompt
+
+场景 Prompt 在 `server-rs/crates/api-server/src/prompt/editor_scene.rs` 中维护，经 `api-server::prompt` 现役模块出口编译，沿用现有后端 Prompt 常量和 builder 模式，不拆分为运行时文本模板文件，不调用 LLM 润色、扩写或改写。旧 `prompt/scene_background.rs` 属于已退役的自定义世界 / RPG 场景链路，不作为本功能复用入口。
+
+提示词来源为产品提供的 `scene_prompt.md`：
+
+- 删除文档章节编号和 `[图片]` 占位。
+- 保留场景结构约束和四套完整预设风格正文。
+- 自定义模式只使用用户自定义画风，不附加预设风格正文。
+- `视觉风格：` 标题只由场景结构模板输出，预设正文不重复携带标题。
+- 先替换受控的比例和画幅方向，再切分静态用户占位符并一次性拼入画面内容与画风正文；用户输入中的模板占位符按原文保留，不参与后续替换。
+
+画幅方向按标准化比例映射：
+
+- `16:9`、`4:3`、`3:2`：横幅。
+- `1:1`：方形。
+- `9:16`、`2:3`：竖幅。
+
+## 6. 队列和计费
+
+场景请求在后端组装完整 Prompt 后，转换成现有 `EditorImageGenerationRequest`：
+
+```text
+kind = scene
+assetKind = scene
+prompt = 后端完整 Prompt
+```
+
+随后复用 `enqueue_editor_image_generation_for_owner`，队列类型继续是 `editor_image_generation`，Worker 继续执行 `generate_editor_image_for_owner`。
+
+队列标题固定为“图片画布生成游戏场景”。任务摘要只展示 `generationInputs.fields` 中的“画面内容”，不得把队列 payload 里的后端完整 Prompt 暴露到任务侧栏；历史错误摘要在投影刷新时按同一规则重新派生。`assetLabel` 省略、空字符串或纯空白时统一使用“游戏场景”，不能退回完整 Prompt 作为素材名称。
+
+计费规则：
+
+- 前端展示价继续读取 `/api/editor/generation-pricing`。
+- 入队时按标准化后的模型和清晰度由后端计算并固化 `external_generation_job.price_mud_points`。
+- Worker 按入队价格扣费，不能在场景接口增加第二层扣费。
+- `scene` 明确按普通图片模型档位计价。
+- Provider 失败、执行取消和 lease 耗尽沿用现有扣退费语义。
+- Provider 成功后的持久化或画布写回失败语义不在本期调整。
+- inline 响应中的通用生成告警必须在队列终态处理前转发；有项目画布占位但响应缺少权威 `project` 快照时，不得追加本地图层或把占位标记为已完成。
+- 队列任务进入 `completed` 后，首次项目快照仍可能短暂保留同一 `dialogId` 的 `generating` 占位。场景提交必须把 completion 的 `dialogId` 传给统一项目回读逻辑；首个权威快照仍未收口时做一次有界延迟重读，不能把该快照当作最终状态永久套用。
+
+## 7. 数据落点
+
+不修改 SpacetimeDB schema，继续复用：
+
+- `external_generation_job`。
+- `editor_canvas_generation_dialog`。
+- `editor_project_resource`。
+- `editor_asset`。
+- `editor_canvas_layer`。
+- `asset_object` / `asset_entity_binding`。
+- 现有钱包流水和 `asset_operation_wallet_settlement`。
+
+字段语义：
+
+- `prompt`：后端最终提交给图片 Provider 的完整场景 Prompt。
+- `actual_prompt`：Provider 返回的 actual/revised Prompt。
+- `asset_kind`：`scene`。
+- `generation_inputs_json`：可恢复场景生成器的 V2 配方；`assetKind = scene` 只表示素材类别，不直接授予“改造”能力。
+
+场景新产物统一保存以下稳定执行契约：
+
+```text
+version = 2
+action = scene.generate
+fields[].id = prompt | stylePreset | customStyle | model | aspectRatio | imageSize
+references[].id = reference
+```
+
+`title` / `label` 仅用于中文展示，不参与路由或恢复。前端提交快照和再次提交使用同一组规范化后的模型、比例与清晰度。请求兼容字段 `generationInputs.fields[]` 保留中文展示 `title`，同时把规范值字符串化，例如 `{ title: "视觉风格", value: "anime" }`；它不携带 V2 的 `id / action / version`。后端忽略客户端提供的执行字段和引用 provenance，按请求顶层 `sceneContent / stylePreset / customStyle / model / aspectRatio / imageSize` 重建 V2 `fields`，并按本次真实 `referenceImageSrcs` 只保留安全的 `references[id="reference"]` 槽位，再由现有 owner-scoped 引用重建链补齐 `refType/refId`。
+
+`scene.generate` 必须同时进入已知 action 与可改造 action allowlist，并由 action 级 decoder 和场景 composer 恢复路径读取。`assetKind = scene` 不能替代上述 capability 判断。`72f268e0` 之后、V2 上线之前产生的场景数据只在 `assetKind === "scene"` 且 legacy `fields` 含展示标题“画面内容”时走既有 legacy 恢复和告警；“画面内容”不得加入全局 legacy 可复用标题列表，其他素材即使带同名字段也不能获得改造入口。
+
+## 8. 验收
+
+- 首页和底部按钮进入同一个场景生成器。
+- 默认值为 `16:9 / 1K / Banana / 日系动画 / 无参考图`。
+- 预设顺序和自定义条件输入正确。
+- 预览图不进入请求参考图。
+- 前端请求中不存在完整场景 Prompt。
+- 后端正确组装四种预设、一个自定义风格和三类画幅。
+- 展示价、入队价、实际扣费和资源成本一致。
+- 任务复用现有等待、失败、轮询、资源入库和画布添加逻辑。
+- 场景产物以 `assetKind = scene` 持久化，画布图层右上角显示“场景”标签，不降级为“未知”。
+- 新场景产物保存 `scene.generate` V2 配方，点击“改造”后恢复画面内容、风格、自定义风格、模型、比例、清晰度和当前画布中仍存在的参考图，再次提交仍保存规范 V2。
+- V2 场景、窄化匹配的历史场景显示“改造”；非场景素材即使 legacy 字段标题为“画面内容”也不得显示“改造”。

docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md

@@ -17,7 +17,7 @@ v1 只开放以下能力：
 - `POST /api/external/v1/assets/direct-upload-tickets`：创建素材直传 OSS 凭证。
 - `POST /api/external/v1/assets/objects/confirm`：确认已上传素材对象，`ownerUserId` 固定为 API Key 所属账号。
 - `GET /api/external/v1/assets/read-url`：获取私有素材读取签名 URL。
-- `GET /api/external/v1/editor/projects`：列出当前 API Key 所属账号的图片画布项目。
+- `GET /api/external/v1/editor/projects`：列出当前 API Key 所属账号的图片画布项目；`view=full|summary`，REST 默认 `full`，MCP 固定使用 `summary`。
 - `POST /api/external/v1/editor/projects`：创建图片画布项目。
 - `GET /api/external/v1/editor/projects/recent`：读取当前账号最近图片画布项目。
 - `GET /api/external/v1/editor/projects/{projectId}`：读取项目与默认画布。
@@ -32,7 +32,7 @@ v1 只开放以下能力：
 - `POST /api/external/v1/editor/assets`：创建素材记录。
 - `PATCH /api/external/v1/editor/assets/{assetId}`：更新素材名称或所在文件夹。
 - `DELETE /api/external/v1/editor/assets/{assetId}`：删除素材记录。
-- `POST /api/external/v1/editor/images/generations`：异步提交编辑器图片素材生成；通过 `kind` 支持普通图、规范图 `spec`、角色图 `character`、快速编辑参考图 `quick-edit`、UI 设计图 `ui-design` 和宣发素材 `publication-material`。
+- `POST /api/external/v1/editor/images/generations`：异步提交编辑器图片素材生成；通过 `kind` 支持普通图、规范图 `spec`、角色图 `character`、快速编辑参考图 `quick-edit`、UI 设计图 `ui-design` 和宣发素材 `publication-material`。External v1 当前不开放结构化游戏场景生成，`kind = scene` 与 `assetKind = scene` 均在入队前返回 `400`。
 - `POST /api/external/v1/editor/images/edits`：异步提交已有图片重绘 / 调整。
 - `POST /api/external/v1/editor/icon-spritesheets/generations`：异步提交规范图驱动的图标 spritesheet 生成和拆分。
 - `POST /api/external/v1/editor/ui-designs/assets/extractions`：异步提交 UI 设计图素材提取 / 拆分。
@@ -83,6 +83,8 @@ MCP transport 的 DNS rebinding 防护必须同时允许正式入口 `www.genarr
 
 MCP tools 从同一份 OpenAPI operation 自动形成 snake_case 名称，并在进程内复用 External REST router，因此鉴权、scope、owner、入参、幂等、计费和结果查询契约只有一份。生成 tools 把 `idempotencyKey` 显式放进参数，因为 MCP transport 的 Authorization 头不能代替逐次业务幂等键。工具结果使用 `structuredContent`；业务失败使用 `isError=true` 的结构化安全错误，协议不可路由时才返回 JSON-RPC error。
 
+`list_editor_projects` 是项目选择工具，服务端固定以 `view=summary` 调用项目列表，不允许因 OpenAPI 的 REST 默认值退回完整视图。摘要逐项目只返回 `projectId`、`title`、`updatedAt` 和可空 `cover`，不携带 `canvas`、`viewport`、`layers`、`resources` 或图片正文；选定目标后再用 `get_editor_project` 读取完整权威状态。`cover` 只包含最新项目封面快照的 `resourceId`、稳定 `objectKey`、尺寸与 `updatedAt`，没有封面时为 `null`。需要展示封面时，以 `objectKey` 调用 `/api/external/v1/assets/read-url` 获取短期签名 URL；列表不得内嵌 Data URL、图片二进制或临时签名 URL，也不得把签名 URL 当作持久引用。
+
 MCP 暴露下列稳定文本资源：
 
 - `genarrative://external-editor/usage`：关键工作流和异步轮询规则。
@@ -212,7 +214,7 @@ SpacetimeDB procedure：
 
 外部生成接口复用站内编辑器已有 DTO、入队器和 worker executor，不维护第二套生成语义：
 
-- 图片生成 / 重绘 / 规范图 / 宣发图 / UI 设计图复用 `/api/editor/images/generations` 与 `/api/editor/images/edits` 的校验、模型归一、计费和持久化规则，但 External handler 固定只入队。
+- 图片生成 / 重绘 / 规范图 / 宣发图 / UI 设计图复用 `/api/editor/images/generations` 与 `/api/editor/images/edits` 的校验、模型归一、计费和持久化规则，但 External handler 固定只入队。主站和 External 的通用图片入口共用场景专用合同边界校验，禁止用 `kind = scene` 或 `assetKind = scene` 绕过后端场景 Prompt 组装；场景专用 handler 自己构造规范请求，不受该通用入口校验影响。
 - 图标 spritesheet 和 UI 设计图素材提取复用站内拆分逻辑，生成图集后按连通域切片，并把图集与切片都按请求写入项目资源和素材库。
 - 角色动画、视频、音效和背景音乐复用站内编辑器生成链路；请求携带 `assetFolderId` 时按站内规则写入素材库，音频类外部调用使用 API Key 所属账号作为 asset owner。
 - API Key 管理接口仍只属于登录态个人中心，不进入外部 OpenAPI JSON。
@@ -252,11 +254,14 @@ docs/openapi/genarrative-external-v1.openapi.json
 - API Key 创建只返回一次明文，列表不返回明文。
 - 撤销后的 API Key 调用外部接口返回 `401`。
 - 八类外部生成 POST 缺少或携带非法 `Idempotency-Key` 时返回 `400`；同一 owner、请求和 key 重试只得到同一 operation。
+- External 通用图片生成携带 `kind = scene` 或 `assetKind = scene` 时均返回 `400`，且不得产生入队尝试。
 - 八类外部生成 POST 固定返回 `202`，查询能从 `queued/running` 收敛到 `completed/failed`；调用方超时后使用原 operationId 继续查询。
 - 外部图片生成、重绘、图标拆分、UI 素材拆分、角色动画、视频、音效和音乐 completed 后，生成结果按请求同时出现在画布资源和账号级素材库。
 - 角色图、图标 spritesheet 和 UI 素材提取的 completed result 允许携带 `EditorGenerationWarning`；provider 原图保留降级与自动拆分降级必须保持成功状态，并分别使用通用 `warning` 与兼容 `sliceWarning` 表达。
 - 外部视频、角色动画、音效和音乐接口使用站内编辑器相同的请求校验、模型限制和价格校验。
 - OpenAPI JSON 能被 `serde_json` 解析，且 security scheme 为 Bearer API Key。
+- 项目列表 REST 默认 `view=full` 并保持完整响应兼容；`view=summary` 只返回项目选择元数据和可空封面稳定引用，MCP `list_editor_projects` 固定使用该摘要视图，不因完整项目数据量增长触发返回体上限。
+- 摘要封面不内嵌图片或签名 URL；使用 `cover.objectKey` 调 `/assets/read-url` 后才能临时展示。
 - OpenAPI JSON 不包含 `/api/profile/api-keys`、`UserAccessToken` 或 API Key 管理 schema。
 - `agent-integration.json` 能发现 MCP、OpenAPI、Skill entry/archive；下载 archive 的 SHA-256 与 manifest 一致，ZIP 包含 `SKILL.md`、四篇 references、Python helper 和 `agents/openai.yaml` 七个声明文件且不含凭据。
 - MCP 在无 Bearer、Bearer 格式错误或 Key 无效时返回相同的 `401 + WWW-Authenticate + details.guide` 鉴权引导，且不暴露 tools/resources/owner；合法 Key 可完成 initialize、tools/list、resources/list/read 和生成提交/查询；resource catalog 必须包含 usage、OpenAPI、`skill` 主入口和当前全部 Skill references，当前精确为 `skill/references/capability-routing.md`、`skill/references/api-operations.md`、`skill/references/authentication-and-safety.md` 与 `skill/references/requests-and-outputs.md`，且不包含 CLI 脚本、测试或 workflow；多实例不依赖 sticky session，不暴露内部 SpacetimeDB MCP 或 worker 控制面。

docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md

@@ -0,0 +1,158 @@
+# SFX 生成优化 V2.0 T6 测试与发布门禁实施记录
+
+日期：`2026-08-07`
+
+状态：`工程实施完成；生产配置、队列 drain、灰度和实际发布待人工执行`
+
+## 文档定位
+
+本文记录 SFX V2 T6 的实际工程范围、组合测试证据和发布 / 回滚门禁。产品与技术规则以[画板音乐生成入口设计](./【编辑器】画板音乐生成入口设计-2026-06-18.md)为准，分阶段依赖以[SFX V2 任务拆解](./project-memory/plans/【实施计划】SFX生成优化V2.0任务拆解-2026-08-06.md)为准。
+
+本文不是生产部署授权。所有自动测试都使用内存 mock、loopback HTTP server 或仓库 fixture；没有调用真实 LLM、ElevenLabs、OSS 或其它付费 provider，不能表述为真实 provider 验收。
+
+## 实施基线与边界
+
+- 隔离分支：`codex/sfx-v2-t6`。
+- 基线：`feat/sound_opt@69f850ff827fe64ec1c7f7a325e34ecf9c338252`，已包含 master 合并、Chat completion tokens 契约修复、未知请求字段拒绝、稳定用户失败文案和 Worker provider budget。
+- 不修改 SpacetimeDB schema、migration、bindings 或表目录。
+- 不修改 BGM Suno、BGM Prompt 助手、BGM 预设、提交锁和定价语义。
+- 不执行生产配置写入、数据库查询、旧任务 drain、服务部署、流量切换或真实生成。
+
+## 正式 Worker 组合测试缝
+
+正式 SFX Worker 现在通过同一个内部编排函数按顺序执行：
+
+```text
+计费预扣
+  -> Luna 英文化
+  -> 单次 ElevenLabs POST
+  -> MP3 / 实际时长门禁
+  -> OSS PUT / HEAD
+  -> asset object / bind 候选准备
+  -> 原子提交项目资源 / 账号素材 / 画布完成态 / queue job
+```
+
+生产 adapter 仍调用原有统一计费、`LlmClient`、`platform-audio` ElevenLabs adapter、OSS 和编辑器原子持久化实现，没有复制第二套业务流程。测试 adapter 只替换外部边界，以相同编排函数覆盖：
+
+- 自动 / 手动时长 × Loop false / true 四种成功组合；
+- 余额不足时 LLM、ElevenLabs、OSS 和全部写回均为零；
+- `translation_invalid / translation_upstream_failed` 时 ElevenLabs 为零；
+- ElevenLabs HTTP、无效 body / MIME / 大小、损坏 MP3 / 时长探测失败；
+- OSS PUT、OSS HEAD、asset object / bind 候选准备、原子项目资源 / 账号素材 / 画布写回失败；
+- 所有预扣后的失败恰好退款一次，成功只扣费一次；
+- 每个 job 的 ElevenLabs POST 最多一次；
+- `prompt / actualPrompt / model / provider / taskId / actual duration / loop / generationInputs.soundEffect` 在响应、项目资源、账号素材和画布 layer 等值。
+
+`platform-audio` 的 loopback HTTP 测试继续负责真实 adapter 形态：固定 endpoint / query / header / body、自动 / 手动时长、Loop、MIME fallback、`40 MiB` 与 chunked 上限、timeout / 429 / 5xx / body 失败无 retry、MP3 probe 和独立 `600s` 上限。组合 mock 不替代这些 adapter 测试。
+
+## 稳定失败分类
+
+Worker 任务记录和内部观测使用以下稳定 reason code：
+
+| 阶段 | reason code |
+| --- | --- |
+| 翻译候选不合格 | `translation_invalid` |
+| 翻译 transport / upstream | `translation_upstream_failed` |
+| 翻译 / provider 预算耗尽 | `translation_budget_exhausted` / `elevenlabs_http_failed` |
+| ElevenLabs HTTP / timeout / body 读取 | `elevenlabs_http_failed` |
+| MIME、空 body、大小等音频门禁 | `invalid_audio` |
+| MP3 识别、帧读取、有限正时长或 600 秒门禁 | `duration_probe_failed` |
+| OSS PUT / HEAD | `oss_failed` |
+| asset object / bind 候选、原子项目资源 / 账号素材 / 画布写回 | `writeback_failed` |
+
+reason code 不包含 endpoint、provider 原始正文或凭据。普通用户读取失败任务时仍只看到“音效生成失败，请稍后重试。”；原始诊断继续留在受控 Worker / tracing / 后台边界。
+
+## 跨入口补齐
+
+T6 盘点发现画布 Agent 的 `generate-sound-effect` 虽已使用 ElevenLabs 模型，但仍保留旧 Vidu 的 `2–10` 整数时长且固定 `loop=false`。本阶段修复为：
+
+- Prompt 使用与站内请求相同的 ECMAScript `String.trim()` 等值 canonicalization 和 `1–2048` code point 门禁；
+- model 固定 `eleven_text_to_sound_v2`；
+- `duration` 接受 `null` 或有限 `0.5–30` 小数，缺省仍为手动 `5s`；
+- `loop` 为独立布尔值，缺省 false；
+- 显式 `duration: null` 在 Agent 参数解析中保留为自动时长，不经过通用“顶层 null 当缺省”兼容层；
+- Agent 最终生成与登录态、External v1 进入同一个 `editor_sound_effect_generation` canonical queue payload。
+
+External v1 仍要求 `Idempotency-Key`。接受的 model 形态在 enqueue 前收敛为同一 payload；`audio1.0` 和未知模型在计费、LLM 与 provider 前返回 `400`。compact result 继续只暴露稳定资源引用、实际时长和 Loop，不暴露 Prompt 或 provider。
+
+## 验证结果
+
+| 门禁 | 结果 |
+| --- | --- |
+| `platform-audio` 分层与 ElevenLabs loopback | `60/60` |
+| `platform-editor-agent` | `24/24` |
+| api-server SFX Prompt / 翻译 / Worker 组合矩阵 | `32/32` |
+| External v1 / OpenAPI / 幂等 | `13/13` |
+| external-generation Worker / compact / deadline | `31/31` |
+| api-server BGM 回归 | `35/35` |
+| SFX / BGM 前端提交、刷新、重绘、metadata | `14` 个文件、`451/451` |
+| `cargo check -p api-server --all-targets` | 通过；仅既有 dead-code warning |
+| `npm run typecheck` | 通过 |
+| `npm run check:spacetime-schema` | `137` 张表通过，确认无 schema diff |
+| `npm run check:encoding` | `5248` 个文件通过 |
+| `cargo fmt --all -- --check` | 通过 |
+| `git diff --check` | 通过 |
+
+本地运行态 smoke 使用独立临时数据库、临时 data dir 和 `18000–18004` 端口，未复用或修改原工作树正在运行的 `3000 / 3101 / 8082 / 8083` 服务。结果如下：
+
+| 服务 | 地址 | 门禁 | 结果 |
+| --- | --- | --- | --- |
+| SpacetimeDB | `http://127.0.0.1:18002` | `GET /v1/ping` | HTTP 200 |
+| BgFilter worker | `http://127.0.0.1:18004` | `GET /readyz` | HTTP 200，`ready=true` |
+| api-server | `http://127.0.0.1:18001` | `GET /healthz` | HTTP 200，`service=genarrative-api-server` |
+| Web | `http://127.0.0.1:18000` | `GET /` | HTTP 200 |
+| Admin Web | `http://127.0.0.1:18003/admin/` | `GET /admin/` | HTTP 200 |
+
+临时进程树停止后，`18000–18004` 五个端口均已释放。该 smoke 只证明本地进程、路由和临时 SpacetimeDB 模块可以启动，不包含真实 ElevenLabs / LLM / OSS 调用，也不代表生产配置或生产队列已验收。
+
+## 生产发布门禁
+
+以下步骤未在 T6 工程实施中执行。发布人员必须在维护窗内逐项记录时间、目标环境和结果，但不得把 Key、Token、Cookie、完整 provider 错误正文或宿主私密路径写入仓库。
+
+### 1. 配置与价格
+
+在目标 host 的受控 secret 环境中只检查“是否存在”，不输出值：
+
+```bash
+for name in ELEVENLABS_BASE_URL ELEVENLABS_API_KEY ELEVENLABS_REQUEST_TIMEOUT_MS; do
+  test -n "$(printenv "$name")" || { echo "missing required setting: $name" >&2; exit 1; }
+done
+```
+
+确认生产定价配置包含 `eleven_text_to_sound_v2`，单位 `perGeneration`，批准价格为 `5` 泥点；禁止只依赖前端兜底价格。
+
+### 2. 关闭入队并排空旧任务
+
+先进入维护窗或关闭 SFX 提交入口，再对显式目标 server 做只读查询。`<database>` 和 `<server-url>` 必须由发布环境明确提供；禁止依赖默认 server，禁止使用 `--root-dir`：
+
+```bash
+spacetime sql <database> \
+  --server <server-url> \
+  --format json \
+  "SELECT job_id, status, request_payload_json FROM external_generation_job WHERE job_kind = 'editor_sound_effect_generation' AND (status = 'pending' OR status = 'running')"
+```
+
+门禁要求结果为零行。非零时保持 SFX 入队关闭，让当前旧 Worker drain；不得用新 Worker 解析存量 Vidu payload，也不得删除或改写任务来伪造清零。该查询只读，不修改 schema 或数据。
+
+### 3. 部署顺序与灰度
+
+1. 保持 SFX 入队关闭。
+2. 部署共享 env 已对齐的 api-server / external-generation worker。
+3. 检查 `/healthz`，确认 Worker 可启动且没有配置失败。
+4. 部署 Web。
+5. 先放开小比例 SFX 入队，观察失败分类、退款、provider POST 和完成资源对账，再逐步放量。
+6. External v1 调用方完成 contract smoke 后再结束维护窗。
+
+灰度必须对账：job 完成数、退款数、ElevenLabs POST 数、完成资源数和孤儿资源数。单 job provider POST 大于 1、翻译失败仍出现 provider POST、成功 job 出现退款或失败 job 无退款时立即停止放量。
+
+## 回滚门禁
+
+- 不自动切回 Vidu，也不在失败时静默 fallback。
+- 先停止新 SFX 入队，再等待或人工收口 V2 pending / running job。
+- Web、api-server、Worker 和 External v1 契约协同回滚，禁止只回滚一层。
+- 已成功生成的 ElevenLabs 素材继续按通用音频资产和现有 metadata 只读展示，不做数据迁移回滚。
+- 本阶段没有 SpacetimeDB schema 变更，回滚不得执行表迁移、字段删除或数据重建。
+
+## 发布判定
+
+T6 工程代码与本地确定性门禁完成后，只能判定“具备进入生产维护窗验证的条件”。只有配置存在、价格批准、旧 SFX 队列为零、部署健康检查通过、灰度对账无异常且 External contract smoke 通过后，生产发布才可放行。

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -54,13 +54,13 @@ npm run dev:api-server
 npm run dev:bgfilter-worker
 ```
 
-Linux 本机多用户并发开发时，`npm run dev` 和 `npm run dev:*` 单模块命令会先在系统级端口段注册表里给当前用户分配一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`、`bgfilter-worker = start + 4`。默认注册表目录是 `/var/tmp/genarrative-dev-port-ranges/`，其中 `registry.json` 记录各用户的活跃段，`registry.lock` 负责串行化分配；可以用 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。系统自动分配时从 `10000-10099` 开始，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 只在 Linux 上生效，Windows 仍按原来的 3000 / 8082 / 3101 / 3102 / 8083 优先端口统一探测并漂移，不读这个系统级注册表。父 API 与 worker 始终使用解析后的实际 `GENARRATIVE_BGFILTER_WORKER_BASE_URL`，不能写死 `8083`。
+Linux 本机多用户并发开发时，`npm run dev`、`npm run dev:*` 单模块命令和 `npm run agc` / `npm run agc:game-chat` 会先在系统级端口段注册表里给当前用户分配一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`、`bgfilter-worker = start + 4`、`agc-vite = start + 5`。默认注册表目录是 `/var/tmp/genarrative-dev-port-ranges/`，其中 `registry.json` 记录各用户的活跃段，`registry.lock` 负责串行化分配；可以用 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。系统自动分配时从 `10000-10099` 开始，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；同用户已有 worktree 占用首选 AGC 槽位时，AGC 只在本用户段内继续漂移。`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 只在 Linux 上生效，Windows 仍按原来的 3000 / 8082 / 3101 / 3102 / 8083 与 AGC 兼容优先端口 3080 统一探测并漂移，不读这个系统级注册表。父 API 与 worker 始终使用解析后的实际 `GENARRATIVE_BGFILTER_WORKER_BASE_URL`，不能写死 `8083`。
 
 后端日志默认写入 `logs/api-server/`，独立 BgFilter worker 日志默认写入 `logs/bgfilter-worker/`。后端 API smoke 使用 `npm run dev:api-server`，先检查 BgFilter worker `/readyz`，再检查 API `/healthz`；需要确认 API 实例可接生产流量时检查 API `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
 
-AI 游戏创作客户端使用 `npm run agc`，开发态 game-chat 使用 `npm run agc:game-chat`。两个入口都先由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 在 Tauri CLI 启动前检查固定地址 `http://127.0.0.1:3080/`：只有端口空闲时才继续启动。现有 marker 只包含 API target，不能证明监听器属于当前 worktree；即使页面和 target 看似匹配，也不得复用已经存在的 3080。旧 worktree Vite、无响应监听器或非 AGC 服务一律在创建原生窗口前失败关闭，并提示先停止旧服务；启动器不擅自终止无法证明归属的进程。
+AI 游戏创作客户端使用 `npm run agc`，开发态 game-chat 使用 `npm run agc:game-chat`。两个入口都先由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。启动器在创建原生窗口前预检最终地址；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。
 
-Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：旧 3080 已就绪时，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对 3080 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
+Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：选定地址上若已有旧 Vite，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对控制台输出的 AGC Vite 实际地址及其 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
 
 Windows 本地 `npm run dev` / `npm run dev:api-server` / `npm run dev:bgfilter-worker` 会用空的 `RUSTC_WRAPPER` / `CARGO_BUILD_RUSTC_WRAPPER` 覆盖 `server-rs/.cargo/config.toml` 里的 `sccache`，从而直连真实 `rustc`。完整栈和 `dev:api-server` 把 API 与 BgFilter worker 作为一个 Rust 重启单元：源码变化时先停两个进程，再先启动并验活 worker、最后启动并验活 API，避免两个 `cargo run` 并发链接同一个 Windows 可执行文件。不要把 wrapper 绕过值写成 `rustc`；Cargo 会按 wrapper 协议调用 `rustc <真实rustc路径> - ...`，最终报 `multiple input filenames provided` 并导致 api-server 无法启动。排查本地启动失败时，先看 dev 日志是否出现该错误，再确认脚本注入的 wrapper 为空。
 
@@ -183,6 +183,10 @@ spacetime sql <database> "SELECT * FROM runtime_setting LIMIT 1" --server http:/
 
 本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查图片编辑器 VectorEngine 生成链路时，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000`；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。业务模型和 VectorEngine provider 首选请求都使用 `gpt-image-2`，符合条件时才回退到兜底模型 `gpt-image-2-c`；图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`，`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image-2 family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。
 
+编辑器 ElevenLabs 音效生成只从服务端读取 `ELEVENLABS_BASE_URL`、`ELEVENLABS_API_KEY` 和 `ELEVENLABS_REQUEST_TIMEOUT_MS`，timeout 默认 `180000ms`；base URL 或 Key 缺失时失败关闭，不回退 Vidu。生产 API 与 external-generation worker 通过共享 API env 取得同一配置，模板见 `deploy/env/api-server.env.example`；Key 不得进入 Web/Vite 环境、命令参数、日志、fixture 或仓库。普通测试只使用 loopback mock，禁止把真实付费请求作为 T3 自动验收。
+
+SFX V2 发布必须使用维护窗：先关闭 SFX 入队，再对显式目标执行只读 `spacetime sql <database> --server <server-url> --format json "SELECT job_id, status, request_payload_json FROM external_generation_job WHERE job_kind = 'editor_sound_effect_generation' AND (status = 'pending' OR status = 'running')"`；结果非零时保持旧 Worker drain，不得删除任务或让新 Worker 解析旧 Vidu payload。禁止依赖默认 server，禁止使用 `--root-dir`。清零后先部署共享 env 已对齐的 api-server / external-generation worker，检查 `/healthz` 和 Worker 启动，再部署 Web 并小流量开放 SFX。灰度对账 job 完成数、退款数、ElevenLabs POST 数、完成资源数和孤儿资源；翻译失败仍调用 provider、单 job provider POST 大于一次、成功退款或失败未退款均应立即停止放量。回滚先停止入队并收口 V2 pending / running job，不自动切回 Vidu，不执行 SpacetimeDB schema 或数据回滚。完整清单见 `docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md`。
+
 VectorEngine 图片生成 / 编辑在 `request_send` 阶段出现 `timeout`、`connect`、libcurl 35 SSL connect reset、libcurl 56 receive error / `unexpected eof while reading`、recv failure 等临时传输错误，或在 `upstream_status` 阶段收到 408 / 429 / 5xx（例如 Nginx HTML `502 Bad Gateway`）时，`platform-image` 会在一次业务请求总上限 5 次内处理；multipart 图片编辑每次重试都会重新构造 form，避免复用已消费的 body。首个 provider attempt 使用 `gpt-image-2`；明确模型不可用、408 / 非拒绝类 429 / 5xx、响应解析失败或非拒绝类缺图时，下一 attempt 直接切兜底模型 `gpt-image-2-c`，之后只在剩余次数内重试兜底模型。发送 / 连接错误无法确认上游是否已受理，只重试同一首选模型，不切模型；认证、普通参数、安全拒绝、图片下载和 budget 错误同样不切。worker 从 job 开始的同一时钟起点计算绝对 deadline，常规保留最后 `60` 秒给审计、OSS 和终态写回；job 预算小于 `120` 秒时保留一半。VectorEngine 单次 attempt timeout 取配置值和剩余 provider 预算的较小值；退避或模型切换后已没有下一次 attempt 的预算时立即停止。该 deadline 覆盖参考图、provider 请求 / 响应和响应图片下载的整次 provider future，但只在 worker 进程内通过 `RequestContext` 传递；普通 HTTP / `inline` 没有该 deadline，继续保持原有 timeout 和重试行为。日志中 `VectorEngine 首选图片模型失败，切换兼容模型` 会携带 `fallback_from_model` / `fallback_to_model`；即使回退成功，首选模型错误仍写入 `external_api_call_failure`，成功运行摘要的 `recoveredFailureCount` 同时递增。排查生产失败时应同时统计 fallback / retry 日志和最终 audit，避免把一次用户请求内的多次发送误判成多个用户请求。这项收口不修改 lease 续租 / fencing、迟到写回仲裁、attempt 耗尽与原子退款语义。
 
 图片编辑器生成属于持久队列长任务：提交接口返回 job 后，前端通过 `/api/runtime/external-generation/jobs/{jobId}` 与编辑器项目资源状态收敛。生产排查小程序或 WebView `Failed to fetch` 时，若 Nginx access log 为 `499`、`upstream_status=-`，先按提交请求的 `request_id`、job id、worker 日志和 `external_api_call_failure` 对齐真实任务，不把客户端断开直接判定为 provider 失败。
@@ -243,20 +247,20 @@ PR checkout 必须保留完整 Git 历史，并把 PR base SHA 传给 `SPACETIME
 
 当前 `genarrative-station` 使用 Gitea `1.26.4` 和基于 Gitea Runner `2.0.0-dind-rootless` 的固定 digest 修补镜像。Runner 2.0.0 会先把 `systempaths=unconfined` 解析为空 `MaskedPaths` / `ReadonlyPaths`，再被 `mergo.WithOverride` 当成 empty value 丢失；站点修补只在 merge 后保留这两个显式空 slice，不改其它 runner 行为。真实 job inspect 必须看到 `MaskedPaths=[]`、`ReadonlyPaths=[]`、`SecurityOpt=[seccomp=unconfined]`、`Privileged=false`、无 CapAdd 且 `Binds=[]`。外层 runner 以 `rootless` 用户运行，`privileged=false`、不增加 `CAP_SYS_ADMIN`，只映射 `/dev/net/tun`，内部 Docker 只监听私有 Unix socket；runner 配置保持 `docker_host: "-"`、`valid_volumes: []`、`bind_workdir: false` 和 `force_pull: false`，防止内部 Docker socket 或宿主 bind mount 进入 job。job 只连接 `gitea-actions` internal network：`genarrative-station` 由只转发 `/git` 到 Gitea 的内部 gateway 解析，公网依赖只经拒绝私网、保留地址和 metadata 的 80/443 egress proxy；绕过 proxy 的公网和 Postgres/Redis 数据网都必须不可达。完整 bwrap canary 需要 rootless DinD 外层的 rootlesskit AppArmor/userns 边界，以及内层 job 的 namespace/proc 挂载支持；相关 `seccomp/systempaths` 放宽只允许存在于这个无宿主 socket 的 rootless DinD 内层，禁止复制回控制宿主 rootful Docker 的 runner。
 
-CI job 镜像由 `deploy/container/gitea-ci-job.Dockerfile` 定义：Ubuntu job base 固定为 `sha256:58ea92624c7c09582e05594d95488331045053d3a3f34cf09649f2a32313a614`，Rust stage 固定为 `sha256:19817ead3289c8c631c73df281e18b59b172f6a31f4f563290f69cddd06c30e9`，Node `22.23.1` 发行包执行 SHA-256 校验，Google Linux 主签名指纹固定，Chrome 固定为 `150.0.7871.181-1`。构建脚本以 NUL 分隔白名单 tar 流只发送 Dockerfile、checkout 脚本和 npm / Cargo manifests/lock；当前 context 约 `1.638 MB`。镜像按根 npm 锁、server-rs 锁和桌面壳锁预热下载缓存，不包含 `node_modules` 或 Cargo `target`；两个 `cargo fetch --locked` 在 Cargo 自身重试之外再执行最多 5 次整命令级有界重试，处理 registry index 握手失败，最终仍以断网 `cargo fetch --locked` 关闭验证。当前验证镜像约 `1.788 GB`，默认 tag 为 `genarrative/gitea-project-ci:20260723.1`，完整 Image ID 为 `sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`；runner 标签保留 `ubuntu-latest`，并将 `genarrative-ci` 映射到 `docker://sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`。内层 Docker 数据必须持久化；`force_pull: false` 表示只使用这个已装载的精确内容，Image ID 缺失时 job 必须失败关闭，不得回退浮动 tag 或临时连 registry。
+CI job 镜像由 `deploy/container/gitea-ci-job.Dockerfile` 定义：Ubuntu job base 固定为 `sha256:58ea92624c7c09582e05594d95488331045053d3a3f34cf09649f2a32313a614`，Rust stage 固定为 `sha256:19817ead3289c8c631c73df281e18b59b172f6a31f4f563290f69cddd06c30e9`，Node `22.23.1` 发行包执行 SHA-256 校验，Google Linux 主签名指纹固定，Chrome 固定为 `150.0.7871.181-1`。构建脚本以 NUL 分隔白名单 tar 流只发送 Dockerfile、checkout 脚本，以及根、AI 游戏创作壳、server-rs 与桌面壳所需的 npm / Cargo manifests/lock；当前 context 约 `2.13 MB`。镜像按根 npm 锁、AI 游戏创作壳 npm 锁、server-rs 锁、桌面壳锁和 AI 游戏创作壳 Cargo 锁预热下载缓存，不包含 `node_modules` 或 Cargo `target`；三个 `cargo fetch --locked` 在 Cargo 自身重试之外再执行最多 5 次整命令级有界重试，处理 registry index 握手失败，最终仍分别以断网 `cargo fetch --locked` 关闭验证。当前验证镜像约 `1.85 GB`，默认 tag 为 `genarrative/gitea-project-ci:20260807.1`，完整 Image ID 为 `sha256:8b4b30f5a096522942947927b06cf47bdb1a1016dde9a3573f9780e79d8e40cf`；runner 标签保留 `ubuntu-latest`，并将 `genarrative-ci` 映射到 `docker://sha256:8b4b30f5a096522942947927b06cf47bdb1a1016dde9a3573f9780e79d8e40cf`。内层 Docker 数据必须持久化；`force_pull: false` 表示只使用这个已装载的精确内容，Image ID 缺失时 job 必须失败关闭，不得回退浮动 tag 或临时连 registry。
 
 镜像更新命令：
 
 ```bash
 bash scripts/gitea-ci-job-image.sh build
 bash scripts/gitea-ci-job-image.sh verify
-bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-gitea-project-ci-20260723.1.tar.zst
+bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-gitea-project-ci-20260807.1.tar.zst
 bash scripts/gitea-ci-job-image.sh load-runner
 ```
 
 执行账号只要有权访问宿主 Docker API 并管理 runner 容器即可，不强制使用 root；无该权限时由 runner 运维人员执行。更新顺序必须是 `build/verify -> export 仓库外镜像归档与 SHA-256 sidecar -> load-runner -> 确认无活跃 job -> 备份当前 config -> 增加或替换 label -> docker restart --timeout 660 gitea-runner`。`--timeout 660` 只是停止宽限，不是 drain API；rootless DinD supervisor 可能同时停止内层 dockerd，因此重启前必须确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空。config 和镜像归档只保存到仓库外受控位置，不在文档、仓库或日志中记录注册信息。重启后先重跑真实 PR 的四个 job，复核隔离边界并确认全部通过，再清理旧镜像。回滚时先把 workflow 的 `runs-on` 改回 `ubuntu-latest`，再恢复 config 备份并重启 runner。
 
-四个 job 先运行镜像内 `genarrative-gitea-checkout`，再以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，校验 Node 主版本、仓库 Rust toolchain、受信任 PATH、缓存锁命中状态、原生命令、pkg-config 依赖、完整 bwrap sandbox 和 Chrome headless。`RUSTUP_AUTO_INSTALL=0`，因此仓库 `rust-toolchain.toml` 变更必须先更新镜像，不能让 job 现场下载。每个 job 仍独立运行 `npm ci`，以当前 lockfile 为准验证 PR 依赖；`NPM_CONFIG_PREFER_OFFLINE=true` 且网络重试为 10 次，命中镜像 cache 时只做干净解包，lock 变化时允许补齐差量。不在镜像内烘入 `node_modules`，也不挂载跨 PR 可写缓存。任何 job 的 sandbox canary 失败都必须停止，不允许跳过。Cargo 通过受控 proxy 下载 lock 差量时继续关闭 HTTP multiplexing 并设置 `CARGO_NET_RETRY=10`。
+四个 job 先运行镜像内 `genarrative-gitea-checkout`，再以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，校验 Node 主版本、仓库 Rust toolchain、受信任 PATH、五份缓存锁命中状态、原生命令、pkg-config 依赖、完整 bwrap sandbox 和 Chrome headless。运行时发现锁不匹配时必须输出对应 `*_cache_lock=partial` 和 Actions warning，提示可信分支落地后刷新镜像，不能把陈旧缓存误报为闭合。`RUSTUP_AUTO_INSTALL=0`，因此仓库 `rust-toolchain.toml` 变更必须先更新镜像，不能让 job 现场下载。每个 job 仍独立运行 `npm ci`，以当前 lockfile 为准验证 PR 依赖；统一通过 `scripts/ci-npm-ci-with-retry.sh` 做最多 3 次整命令级有界重试，同时保留 `NPM_CONFIG_PREFER_OFFLINE=true` 和 npm 自身 10 次 fetch retry。命中镜像 cache 时只做干净解包，lock 变化时允许补齐差量。不在镜像内烘入 `node_modules`，也不挂载跨 PR 可写缓存。任何 job 的 sandbox canary 失败都必须停止，不允许跳过。Cargo 通过受控 proxy 下载 lock 差量时继续关闭 HTTP multiplexing，并设置 `CARGO_NET_RETRY=10`。
 
 站点 stack 仍由宿主受控目录管理，`.env`、runner 注册文件和数据库凭据不进入仓库。Compose 必须在 helper/container 内把该目录挂到与宿主相同的绝对路径再执行；挂载到不同路径会让相对 bind source 被 Docker daemon 解析到错误的宿主目录并启动空数据。升级或 runner 迁移前先停止 Gitea 写入，并把 Gitea 冷快照、数据库导出、compose/env 与 runner config/.runner 保存到仓库外受控备份位置。备份文件、绝对宿主配置和注册 token 不得提交 Git，也不在共享文档中记录具体路径或注册内容。
 
@@ -579,6 +583,8 @@ cat /var/lib/genarrative/health-patrol/status.json
 
 如需接外部告警，可在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_WEBHOOK_URL`；脚本只会在 `WARNING` 或 `CRITICAL` 时向该 webhook 发送 JSON。未配置 webhook 时，告警来源是 systemd 失败状态、journal 和状态文件。
 
+Jenkins Copy Artifact 必须保持 `Production` 权限模式；产物生产者要在 Jenkinsfile 中用 `copyArtifactPermission` 精确授权消费者，不能依赖 Migration 模式或全局 `Job/Read`。固定映射为 `Genarrative-Stdb-Module-Build` → `Genarrative-Stdb-Module-Publish`、`Genarrative-Api-Build` → `Genarrative-Api-Deploy`、`Genarrative-Web-Build` → `Genarrative-Web-Deploy`、`Genarrative-Database-Export` → `Genarrative-Database-Import`。如果 `copyArtifacts` 报 `Unable to find project for artifact copy`，但来源 Job、指定构建号和归档都实际存在，先检查来源 Job 的 `CopyArtifactPermissionProperty`；修复 Jenkinsfile 后必须先运行一次产物生产者，让 Declarative Pipeline 把 Job property 写回 Jenkins，再重跑 Deploy / Publish / Import。`npm run check:production-ops` 会防止四条白名单再次丢失。
+
 `Genarrative-Web-Build` 的主站构建失败若出现 Rollup 报错 `"xxx" is not exported by "src/services/publicWorkCode.ts"`，优先按前端公开作品号工具缺失处理，而不是排查 Jenkins 节点环境。修复时要让 `publicWorkCode.ts` 的 `build<Play>PublicWorkCode` 与 `isSame<Play>PublicWorkCode` 成对导出，并补 `src/services/publicWorkCode.test.ts` 覆盖对应玩法前缀；随后用 `npm run build:production-release -- --component web --name <临时名>` 复现 Jenkins web 构建路径。
 
 `Genarrative-Web-Build` 会把 `build/<version>/web.tar.gz`、`web.tar.gz.sha256`、`release-manifest.json` 和 `scripts/deploy/production-web-deploy.sh` 直接归档为 Jenkins 构建产物；`Genarrative-Web-Deploy` 只通过 `copyArtifacts` 从指定上游构建复制这些产物和部署脚本，不再在目标机器 checkout Git，再执行随构建归档的 `scripts/deploy/production-web-deploy.sh`。Web 发布不再读取构建机本地缓存目录，也不再通过 release agent `rsync` 回构建机拉取大包；如果 deploy 找不到 `web.tar.gz`，应先检查上游 Web Build 是否按同一 `BUILD_VERSION` 成功归档产物。
@@ -699,6 +705,7 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
 - `GENARRATIVE_DATABASE_BACKUP_*`
 - `GENARRATIVE_LLM_*`
 - `VECTOR_ENGINE_*`
+- `ELEVENLABS_*`
 - ~~`APIMART_*`~~（已弃用，LLM 文本调用统一迁移到 VectorEngine）
 - `APIMART_*`（历史残留，创意 Agent LLM 已迁移到 VectorEngine）
 - `HYPER3D_*`

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -12,7 +12,7 @@
 - `/project` 展示当前账号的图片编辑器项目，项目卡继续进入 `/editor/canvas`。
 - `/profile` 是“我的”稳定路由，保留头像与昵称编辑、陶泥号复制、泥点余额与账单、累计统计、泥点充值、兑换码、玩家社区、反馈与建议、通用设置、开发者 API Key 和法律信息等平台公共能力。
 - 桌面顶栏保留现役项目 / 素材搜索、泥点入口和账号胶囊。搜索只筛选当前编辑器项目与已读取的公开编辑器素材，不恢复旧公开作品号搜索、旧广场、旧作品详情或旧运行态。
-- 桌面端公共侧边栏固定显示“创作 / 项目 / 我的”；移动端底部 dock 只保留“我的”，不暴露“创作 / 项目”。移动端直达 `/creation`、`/project` 或 `/editor/canvas` 时显示桌面端创作提示，不挂载创作主页、项目列表或图片画布；从移动端首页触发项目或画布动作时也只显示同一提示。
+- 桌面端公共侧边栏固定显示“创作 / 项目 / 我的”；移动端底部 dock 只保留“我的”，不暴露“创作 / 项目”，根入口默认展示“我的”并保持该 Tab 选中。移动端每次进入站点壳时先显示移除前的 IP 欢迎遮罩，明确“移动端仅支持作品展示”；遮罩不允许通过背景或 Escape 关闭，只能点击“好”，关闭后本次页面生命周期内不再重复，刷新后重新显示。移动端直达 `/creation`、`/project` 或 `/editor/canvas` 时显示移除前的桌面端创作主页提示，不挂载创作主页、项目列表或图片画布；提示页底部继续保留唯一的“我的”Tab 作为返回入口。三类工具统一阻断沿用 2026-08-03 的现役产品边界，不回退为旧源码只拦截 `/creation` 的较弱行为。
 
 现役入口和公共资料能力只能依赖 `creation-home`、`project`、`image-editor`、公共组件及 `services/platform-entry` 等现役模块。Vite 模块门禁会拒绝 `components/rpg-entry`、`services/rpg-entry`、旧玩法目录和旧平台业务模块进入依赖图；Tailwind `@source`、TypeScript `include`、ESLint ignore 或 Vite watch ignore 都不能替代这条运行时依赖门禁。
 

docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md

@@ -59,15 +59,18 @@ layer 只表达“某个资源怎样放在画布上”。`src / prompt / actualP
 
 ### 3.5 worker 原子完成
 
-worker 完成生成任务时，本次先用读取时 revision 调用 CAS 保存；发生并发变更时拒绝覆盖并让任务保留可诊断失败，不再静默覆盖用户布局。最终收口仍是受 `job_id + worker_id + lease_token` 栅栏保护的后端 procedure 在同一事务内：
+worker 完成生成任务时，`api-server` 先把 Provider / OSS 结果准备为稳定 operation/slot 候选，再调用 `persist_editor_generation_result_and_return`。procedure 受 editor generation runtime service identity 保护，queue 路径还必须在同一快照校验 `job_id + worker_id + lease_token`、owner、job kind 和由 job 规范请求重算的 SHA-256 fingerprint；inline 三个 job guard 全空，不接受半套栅栏。同一 `try_with_tx` 内：
 
-1. 校验 job、owner、project、canvas、dialog 和租约；
-2. 幂等创建或确认 `editor_project_resource`；
-3. 创建 / 替换结果 layer，并删除或更新占位 layer；
-4. 把 dialog 更新为终态并关联 `generated_layer_id`；
-5. 递增 canvas revision，最后才允许完成 external job。
+1. 校验 operation 身份、request fingerprint、slot 唯一性、稳定 ID 和全部 owner/project/folder/source/task/媒体交叉关系；
+2. 精确 upsert 可选 `asset_object`，或验证省略的 object 已登记且归属同 owner；
+3. 创建全部 `editor_project_resource`、`editor_asset` 和可选 `asset_entity_binding`；
+4. 对候选布局重新执行 legacy / structured 验证，以 `expected_revision` CAS 写入 layer / dialog 完成态并且只递增一次 canvas revision；
+5. queue 路径写入 compact result 并完成 external job；
+6. 写入 `editor_generation_operation` durable receipt，固化 operation fingerprint、整笔 commit SHA-256、project/job/worker/lease/result 绑定和首次完成时间。
 
-重复 completion 必须返回同一资源、layer 和 dialog 终态，不得重复插入，也不能因 dialog 暂时缺失而返回 `changed=false` 后仍把任务标记完成。任一步失败时整笔业务写回回滚，任务保留可诊断的失败或可重试状态。
+任一步失败时 object/resource/asset/binding/canvas/job/receipt 全部回滚。CAS 冲突时调用方只刷新当前 project 并重算 layout 候选，原 operation、slot、对象和业务记录候选不变，不重跑 Provider 或 OSS。完整重放只在 receipt 存在，且 request fingerprint、commit SHA-256、project/job 绑定与全部权威记录一致时返回 `AlreadyApplied`；不重复事件、不刷新时间、不推进 revision。receipt 缺失但稳定业务记录已存在、同 operation 内容漂移或不完整重放都必须失败关闭。
+
+`completed_at_micros` 必须为正数并固化到 receipt；object/resource/asset/binding/canvas 候选的原时间字段也纳入 commit SHA-256，重放复用原 prepared commit，不重新取时。job 完成时间和完成事件使用事务 `ctx.timestamp`，不信任 worker 时钟。OSS `PUT / HEAD` 仍在 SpacetimeDB 事务外，因此事务失败可以留下未登记或未引用 object，不将本契约表述为跨 OSS exactly-once。
 
 ### 3.6 免费同步栅格派生完成
 
@@ -123,7 +126,7 @@ SpacetimeDB 必须先于依赖新 procedure / bindings 的 API 发布；前端
 - release 存量抽样中的缺资源 `local-*` 角色动作序列可无损 round-trip，并被识别为已持久化终态而非资源登记 pending；同形状但空帧、相对路径、HTTP / 签名 URL、`data:` / `blob:` 引用必须拒绝。已有资源的 `sourceResourceId == resourceId` 历史自引用应按资源表真相安全剥离，其他来源 ID 或资源字段冲突仍必须拒绝。
 - release 全量审计暴露的普通缺资源行必须先通过定向 repair dry-run；图片只能复用同工程唯一资源，音频只能从已登记 private asset_object 恢复。修复后同一 plan 全部命中 `already_repaired`，再重跑全量 backfill dry-run，要求所有 canvas 均通过。
 - structured 模式下 typed 列而非扩展 JSON 决定几何、层级、分组、显示 / 锁定、资源引用、`asset_kind_override` 和 dialog 状态；标签展示和类型能力判断统一按 `override ?? resource default`。修改当前图层标签与清除覆盖都保持 `resource_id` 和资源行数量不变；复制共享同一资源并复制 override，随后各副本可独立修改 override。两个客户端基于同一 revision 写入时只允许一个成功，冲突方重载后端最新快照，不换上新 revision 原样重放旧整包。细粒度 batch mutation 是取消 2 MiB 兼容入口的后续项，不冒充为本次已完成。
-- worker completion 当前以读取时 revision 做 CAS，冲突时拒绝覆盖；V2 保存和保存后快照在同一 procedure 结果内返回，避免“已提交但后续 GET 失败”的不确定结果。lease-fenced 资源 / layer / dialog / job 单事务 completion 仍是后续收口项。
+- worker completion 已使用 durable receipt 与统一原子提交；V2 布局 CAS、object/resource/asset/binding、job 终态和 receipt 在同一 procedure 结果内返回。故障注入必须证明资产校验失败与 canvas revision 冲突均为零部分写入，成功后重放不新增记录、事件或 revision。
 - structured 快照刷新后，上传参考图、生成结果、占位与 dialog 状态均可恢复；资源存在但布局写入失败时不会伪装为保存成功。
 - 完美像素处理失败 / 超时时 OSS、resource、asset 和 layer 均无新增；成功时只有一个最终 PNG、至多一个 project resource 和一个账号素材。处理中占位删除已先持久化时，完成请求不复活 dialog 或结果 layer；回包时本地占位已删除则不应用完成快照，已成功创建的资源 / 素材仍可读取；传输结果未知时客户端不自动重放 unsafe POST。
 - 回滚重组结果经 schema 校验、canonical hash / 资源引用核对且不超过 2 MiB；超限或不一致时明确拒绝且 structured 快照仍可读取。

docs/【编辑器】模型定价配置管理方案-2026-06-22.md

@@ -35,6 +35,7 @@
       "prices": { "480p": 10, "720p": 20, "1080p": 40 }
     },
     "audio1.0": { "unit": "perGeneration", "price": 5 },
+    "eleven_text_to_sound_v2": { "unit": "perGeneration", "price": 5 },
     "chirp-v5": { "unit": "perGeneration", "price": 12 }
   }
 }
@@ -46,6 +47,7 @@
 - `price`：单一价格，适合音效、背景音乐等单次生成模型。
 - `prices`：档位价格，图片模型按尺寸档位配置，视频模型按分辨率配置。
 - 生图模型必须补齐支持尺寸：`gemini-3.1-flash-image-preview` 配 `0.5K / 1K / 2K`，`gpt-image-2` 配 `1K / 2K`。
+- 新编辑器 SFX 只读取 `eleven_text_to_sound_v2`；`audio1.0` 继续保留为历史 Vidu 配置兼容键，两者均按次独立配置。
 
 后端保存前校验当前正式模型、必要尺寸和必要分辨率都存在且大于 0。
 
@@ -61,6 +63,8 @@ SpacetimeDB 模块会在事务内重复执行同等强度的校验，并拒绝
 
 所有会调用外部生成 provider 的编辑器生成请求都必须由后端计算价格，前端请求不提交价格字段；同步执行按当前运行时配置进入 `execute_billable_asset_operation_with_cost` 预扣泥点，预扣失败不得继续调用上游。外部生成队列在入队时把价格写入 `external_generation_job.price_mud_points`，worker 必须用该冻结价格完成扣费、退款、响应和资产成本持久化，配置更新不得改变已入队任务金额。普通图片、规范、角色、UI 设计、宣发素材、快速编辑 / 图片修改、图标 spritesheet、UI 设计图提取素材、视频、角色动作、音效和背景音乐均遵循该规则。背景色决策（gpt-5-mini）本身也是一次上游调用，同样必须在预扣泥点之后发起：预扣前只做颜色无关的算价 / 校验（动画用默认色占位算价），决策放进 billable 闭包，余额不足则决策不跑、决策失败走失败退款。需要向前端展示实际扣费时，由后端在响应中返回 `priceMudPoints`。
 
+SFX V2 上线前已经存在的 SpacetimeDB 定价快照可能只有 `audio1.0`。读取这类历史快照时，`api-server` 只允许从当前受控默认配置或本地 override 补入缺失的 `eleven_text_to_sound_v2` 条目，使旧快照可继续读取；其它必需模型缺失仍失败。该兼容不修改 schema，也不在读取时写数据库；下一次后台保存完整定价矩阵时自然持久化新键。发布前仍应确认运行时配置中的新键和价格已经批准。
+
 ## 运行时身份首次授权
 
 模型定价 writer、外部生成队列和钱包调用都以真实 SpacetimeDB `ctx.sender()` 校验运行时服务 identity。原始 bootstrap secret 固定为 64 位十六进制；首次授权使用与当前 `spacetime_module.wasm` 构建时注入 SHA-256 摘要对应的原始值，模块收到原始值后重新计算 SHA-256 并做常量时间比较，WASM 只嵌入摘要、不嵌入原文。bootstrap secret 只能在配置表为空时建立首个受信身份，表存在后不能重复使用。queue 和钱包 runtime guard 只接受精确 `writer_identity`，迁移操作员身份不自动获得在线生成或钱包权限；因此当前生产 API、worker 和 controller 必须继承同一份 runtime token。非 HTTP 角色只做 queue procedure 鉴权预检，不具备 seed 或轮换身份的职责。migration operator 与 runtime writer 必须互斥：任何已登记 operator 都不能成为 writer，当前 writer 也不能被授权为 operator；一旦已有 operator，bootstrap secret 不得再新增或接管 operator。

docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md

@@ -38,10 +38,12 @@
    - 生成角色：`你希望角色如何设计？`
    - 生成 UI：`你希望这个 UI 长什么样？`
    - 生成视频：`你希望生成什么视频？`
-8. 多输入框面板必须保留每个字段标题和输入框边界，例如生成规范。图标素材生成不再使用多描述列表，改为复用角色形象生成面板同款单文本输入框。
+8. 多输入框面板必须保留每个字段标题和输入框边界，例如生成规范。图标素材生成不再使用多描述列表，改为复用角色形象生成面板同款单文本输入框；该完整文本按 Unicode 字符限制为 `200`，输入时按 code point 截断，不能用 UTF-16 `maxLength` 误截 emoji。
 9. 生成规范下的角色规范、图标规范和自定义规范都使用同一生成类 shell：首行参考图区域、中央字段区、底部生成按钮区，不再出现缺首行参考区或单独 footer 样式。
-10. 图片快速编辑不展示额外参考图入口；原图或绘制了红框和序号的标注图始终作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。
-11. 快速编辑打开后，画布视口应调整到原图完整展示，且面板位于原图下方并不遮挡原图；原图右侧显示竖向框选工具，支持矩形、椭圆和画笔自由框选。快速编辑进入时不默认启用框选工具，点击工具后出现选中态并保持高亮，再点同一工具取消启用；红色圈选框使用细描边。每完成一次框选，红色圈选框按完成顺序标注 `1 / 2 / 3...`，并在快速编辑提示词中追加一行 `对N号红色圈选框里的内容做以下修改：`。
+10. 图标规范只使用 `specType="icon"`，历史 `specType="ui"` 快照在恢复边界迁移为 `icon`。表单字段使用 `playSetting / artStyle`，界面标题继续使用「玩法设定 / 美术风格」。两项初始为空且必填，客户端提交前统一 trim 并拒绝空白值；每项独立支持一键优化、处理中锁定自身、成功后单次撤销，操作行最右侧按 Unicode 字符实时显示 `当前数/200`。撤销必须恢复优化前的原始输入（包括首尾空白）；手工编辑后立即清除该字段已经失效的撤销快照，失败只保留当前文本与仍然有效的旧撤销快照。LLM 返回空文本、超长文本、Markdown / 结构化内容，或 finish reason 明确表示截断、过滤、失败时，后续有界重试必须携带上次无效输出和对应修正要求，不能把未完成前缀当作成功结果。优化请求必须绑定发起时的生成对象 ID 和请求代次；活动对象身份只在 React effect 提交后更新，并在 cleanup 中失效，丢弃的并发 render 不得改变请求归属；对象切换或新请求取代旧请求后，旧成功或失败结果都不得更新当前面板。任一项处理中或任一项为空时禁用生成。字段标题使用真实 label 关联 textarea，不得把优化 / 撤销按钮包进 label。控件继续使用平台默认样式，不新增图标规范专属 CSS。
+11. 图标规范最终生成改走 `POST /api/editor/icon-specs/generations`。前端只提交业务字段和统一参考图 / 项目完成包络，不拼最终 prompt，不提交 `kind / assetKind / ExtraParam`；可选参考图字段为 `referenceId`，只允许当前 owner 的项目资源 ID 或素材 ID。后端固定以 `kind=spec / assetKind=icon-spec / gpt-image-2 / 16:9·2K` 执行图片生成。inline 路径校验业务字段和 `referenceId` 后，补全 `ExtraParam` 与最终 prompt 并交给共享图片生成执行器；queue 路径在预校验后按 `gpt-image-2 / 2K` 运行时定价冻结价格，再以独立 `editor_icon_spec_generation` job kind 入队原始业务载荷。worker 使用入队价格和当前 claim attempt 的计费上下文，重新解析载荷、校验当前 owner 与引用事实，再补全 `ExtraParam` 并调用同一共享图片生成执行器，避免排队期间状态变化产生 TOCTOU。
+12. 图片快速编辑不展示额外参考图入口；原图或绘制了红框和序号的标注图始终作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。
+13. 快速编辑打开后，画布视口应调整到原图完整展示，且面板位于原图下方并不遮挡原图；原图右侧显示竖向框选工具，支持矩形、椭圆和画笔自由框选。快速编辑进入时不默认启用框选工具，点击工具后出现选中态并保持高亮，再点同一工具取消启用；红色圈选框使用细描边。每完成一次框选，红色圈选框按完成顺序标注 `1 / 2 / 3...`，并在快速编辑提示词中追加一行 `对N号红色圈选框里的内容做以下修改：`。
 
 ## 参数交互
 
@@ -70,6 +72,7 @@
 - 生成规范类图片固定使用 `16:9·2K · gpt-image-2`。这三个参数在面板底部沿用可编辑参数按钮的胶囊样式展示，但控件保持禁用不可点击，不提供比例、尺寸或模型修改入口。
 - 宣发素材的 `游戏首图`、`详情五图`、`运营海报` 固定使用 `gpt-image-2`。面板底部只显示禁用态 `gpt-image-2` 模型胶囊和生成按钮，不出现 `nanobanana2` 选项；后端收到 `publication-material` 旧请求时也必须强制归一为 `gpt-image-2`。
 - 图片快速编辑保留一个提示词输入框，并展示与常规图片生成一致的比例 / 尺寸和模型选择；提示词 placeholder 为 `你希望素材如何修改？`，提交按钮显示 `修改`，不展示额外参考图控件。打开面板时优先继承原图关联生成器记录的模型、比例和尺寸；没有关联生成器时使用图层模型，并按原图真实分辨率推导比例和尺寸；模型缺失或已不受支持时回落到当前默认图片模型。切换模型后只展示该模型支持的参数，不兼容的当前值回落到该模型默认值，按钮泥点按选定模型和尺寸同步刷新。提交时必须同时传递 `model / aspectRatio / imageSize`；后端按模型选择 provider 协议：`nanobanana2` 使用 `generateContent + inline_data`，`gpt-image-2` 使用 `/v1/images/edits` multipart，不能把 nanobanana 模型 ID 发往 GPT edits 端点。
+- 图片改造入口也要保持同样约束：恢复历史参数时优先使用 `generationInputs` 中保存的模型、比例和尺寸，失败回退到当前关联参数后再映射为实际 `size`，并一并回传到编辑请求；`canvasCompletion` 的落位尺寸也应与实际输出目标分辨率一致，避免使用源图尺寸伪造改造结果的参数。
 - 不再在底部常驻展开全部可选项。
 
 ## 泥点显示
@@ -77,7 +80,7 @@
 - 本次消耗泥点必须显示在生成按钮内部。
 - 生成按钮内明确显示 `N泥点`，例如 `生成12泥点`、`生成40泥点`；不使用泥点图标替代文字。
 - 画板内所有会提交外部生成任务的按钮，展示价格都必须从模型定价配置函数推导，不允许在按钮文案中散落固定泥点数字；生成请求不提交 `priceMudPoints`，修改后端模型定价配置后，后端实际扣费和前端下一次拉取到的按钮展示应同步变化。
-- 后端所有编辑器外部生成入口必须按运行时模型定价配置计算价格后进入 `execute_billable_asset_operation_with_cost`：`/api/editor/images/generations`、`/api/editor/images/edits`、`/api/editor/icon-spritesheets/generations`、`/api/editor/ui-designs/assets/extractions`、`/api/editor/videos/generations`、`/api/editor/character-animations/generations`、`/api/editor/audios/sound-effects/generations`、`/api/editor/audios/background-music/generations` 都不能只展示价格而不真实预扣钱包。
+- 后端所有编辑器外部生成入口必须按运行时模型定价配置计算价格后进入 `execute_billable_asset_operation_with_cost`：`/api/editor/icon-specs/generations`、`/api/editor/images/generations`、`/api/editor/images/edits`、`/api/editor/icon-spritesheets/generations`、`/api/editor/ui-designs/assets/extractions`、`/api/editor/videos/generations`、`/api/editor/character-animations/generations`、`/api/editor/audios/sound-effects/generations`、`/api/editor/audios/background-music/generations` 都不能只展示价格而不真实预扣钱包。
 - 当前前端展示价统一收口在 `ImageCanvasGenerationModel.ts`：生成图片、生成角色、快速编辑、重绘、宣发素材走 `calculateEditorImageModelPrice` / `calculateEditorImageGenerationPrice`；生成图标素材走 `calculateEditorIconSpritesheetPrice`；生成 UI 设计图走 `calculateEditorUiDesignPrice`；生成规范走 `calculateEditorSpecGenerationPrice`；生成视频走 `calculateEditorVideoPrice`；角色动作走 `calculateCharacterAnimationPrice`；音效 / 背景音乐分别走 `calculateEditorSoundEffectPrice` / `calculateEditorBackgroundMusicPrice`。这些函数启动时会被后端下发配置覆盖，接口失败时才使用内置兜底。定价配置只按模型区分，不按图片 / 规范、视频 / 动作用途拆分；图片类价格必须同时传入模型和 `imageSize`，规范固定读取 `gpt-image-2` 的 `2K` 定价。
 - 泥点配置默认值独立收口到 `server-rs/crates/api-server/config/editor-generation-pricing.default.json`，JSON 结构为 `models[model] = { unit, price | prices }`；后台“模型定价”页面通过 `POST /admin/api/editor-generation-pricing` 保存完整配置到 SpacetimeDB `editor_generation_pricing_config` 全局表，主站通过 `GET /api/editor/generation-pricing` 动态读取当前配置。后台必须展示定价单位：`perGeneration` 显示“按次”，`perSecond` 显示“按秒”。
 - 生成图标素材、生成视频、角色动画、音效和背景音乐请求只提交生成参数，不提交价格字段；后端按归一后的模型、清晰度、时长或音频模型重新计算并扣费。
@@ -112,8 +115,9 @@
 - 视频 / 角色 / 角色动作 / 音效 / 背景音乐待生成占位的角标同样按 viewport 反向缩放，不随画布缩放变小。
 - 已生成角色图、角色动作图或其它生成结果图被点击时只选中图层并收起已有生成输入框；重绘、快速编辑和生成动画面板必须由对应工具栏按钮或右键菜单显式打开。
 - 角色图层打开“生成动作”后再点击“改造”，必须重新打开角色形象生成器；动作生成对话框只把角色图层作为输入来源，不得被识别为该角色图层自身的来源生成器。
-- 角色动作结果图层点击“改造”时，必须通过 `sourceResourceId` 找回原角色图层并重新打开角色动作生成器；关联原角色已不存在时应显示明确提示，不得无响应或降级成图片生成器。
-- 恢复已生成图层的来源生成器时，角色、动作、规范、图标、UI、宣发、视频、音效和背景音乐必须按 `assetKind / mediaType` 恢复对应面板；去背景或快速编辑产生的派生 `quick-edit` 对话框不得遮住图层原有来源生成器。
+- 角色动作结果图层点击“改造”时，V2 必须通过 `references[id="source"]` 找回原角色图层，legacy 数据才允许以 `sourceResourceId` 回退；关联原角色已不存在时应显示明确提示，不得无响应或降级成图片生成器。
+- `改造` 覆盖图片、规范、角色、图标、UI、宣发、游戏场景、视频、音效、背景音乐、角色动作和生成型图片编辑。有效 V2 只按 `action + fields[].id + references[].id` 恢复，引用只匹配当前画布图层；面板直接上传引用和已移出画布的引用不恢复。V2 不新增后续版本，读取时统一经 action 级 runtime decoder 原地收紧：已存在但未知、非法、已下线或与当前模型能力不兼容的参数统一回落到该 action 当前默认值，历史 Veo 也回落到当前默认视频模型；图片比例 / 尺寸按回落后的模型联动校验，角色动作帧数 / 时长按完整档位成对校验。发生参数回落时显示明确告警，再次提交和新快照只使用规范值并继续保存为 `version: 2`。服务端以实际媒体时长覆盖 V2 配方时必须保留 `fields[id="durationSeconds"]`，并写入归一后的有限数值，不能改写为无 `id` 的 legacy 展示字符串。可重新选择的引用缺失时打开面板、留空槽位并提示，提交门禁继续校验必填槽位；必须依赖原 `source` 图层才能构造面板的 action 也始终按 capability 保留改造入口，source 缺失时点击后显示不可替换原因并拒绝改造，运行期间来源变化时仍必须复检并拒绝。有效 V2 不得因引用缺失降级到 legacy。生成型图片编辑 V2 中已持久化的附加 `reference` 应恢复到可见参考槽，并让再次提交的模型、比例、尺寸、像素尺寸、参考图和新快照保持一致；普通快速编辑仍不得提交未展示的隐藏参考图。视频快速编辑必须把实际送入请求的源视频同步保存为 `references[id="videoReference"]`，不能只依赖 `sourceResourceId`；视频 V2 同步保存并恢复 `webSearchEnabled`。历史对话框和 legacy 数据保留 `assetKind/mediaType`、标题别名、资源尺寸 / 模型 / 时长 / `sourceResourceId` 回退，并对默认值恢复显示告警。V2 结构水合必须完整保留 `version/action`、字段与引用 `id`、有限数字、布尔值和无标签引用；一旦出现 `version` 或 `action` 却不满足 V2 合同，必须失败关闭，禁止降级成 legacy。
+- 配方元数据不等于改造 capability。完美像素、手动去背景、裁扩、手动图集拆分以及图标 / UI 自动切片分别保存 `image.perfect-pixel`、`image.remove-background`、`image.crop-expand`、`spritesheet.split`，统一使用 `fields: []`；有正式来源行时只保留不可编辑的 `references[id="source"]` 权威来源，没有正式行时保留空引用。这四个确定性 action 永不显示或执行“改造”，历史 `pixel-art-snap-*` 结果也按 task identity 拒绝改造。整张生成图集仍保留原生成 action；生成任务内部自动抠图仍属于同源后处理，不提升为独立用户 action。
 - 任何会移除画布图层的入口，包括删除、右键剪切和素材库删除关联素材，都必须同步清理该图层关联的生成面板和派生状态，不得在保存或刷新后恢复成孤立占位。
 
 ## 画布保存
@@ -190,7 +194,7 @@
 - 图片快速编辑底部左侧展示比例 / 尺寸组合选择，右侧展示模型选择和 `修改` 按钮；原图或红框序号标注图作为 `sourceImageSrc` 直接编辑，不展示额外参考图条。图标与图集素材不展示快速编辑入口，图标规范仍可快速编辑。
 - 快速编辑打开后画布自动缩放平移到原图完整展示，并让面板位于原图下方且不遮挡原图；原图右侧出现竖向矩形 / 椭圆 / 画笔自由框选按钮。进入快速编辑不默认启用框选，点击工具启用并保持高亮，再点同一工具取消；完成框选后画布红色细框显示连续序号，输入框同步追加 `对N号红色圈选框里的内容做以下修改：`。
 - 快速编辑提交前保留提示词里对原图的 `原图`、`当前图片`、`当前图` 或 `图1` 引用，不再改写成 `图N`。
-- 快速编辑提交给后端时只把原图或已绘制红框和序号的标注图作为 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`。
+- 普通快速编辑提交给后端时只把原图或已绘制红框和序号的标注图作为 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`；从生成型图片编辑 V2 快照恢复且在面板中可见的附加参考图除外。
 - 生成中的占位图聚焦后可用 `Delete` / `Backspace` 删除；删除后异步结果不再落回画布，也不显示额外删除 UI。
 - 快速编辑不创建生成中占位图；提交后当前面板显示修改中，异步结果只允许回填到源图。
 - 生成视频 / 角色形象 / 角色动作 / 音效 / 背景音乐新建后，画布占位空白样式和右上角标签均与对应生成类型一致，不再统一使用图片占位 icon。