合并 origin/master

合并编辑器生成结果原子提交与外部 MCP 项目选择修复保留确定性派生配方与改造 capability 分离语义
2026-08-07 20:38:30 +08:00
parent e99f3209f1 1bc8ccd077
commit bd972662c7
55 changed files with 9139 additions and 1054 deletions
@@ -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": [
@@ -6748,6 +6748,21 @@
 - 非目标：本次只规划视图归并，不实现 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 编辑器生成结果使用 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，自动抠图仍是生成流程内部后处理。
@@ -4008,11 +4008,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 判断内容

@@ -4200,6 +4207,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 文件。
@@ -4348,3 +4362,24 @@
 - 原因：冲突两侧代表不同组件架构，逐行保留看似有用的 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。
+
+## 生成结果的稳定 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。
@@ -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 原图右侧继续排列。

@@ -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` 分段组合。
@@ -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}`：读取项目与默认画布。
@@ -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`：关键工作流和异步轮询规则。
@@ -257,6 +259,8 @@ docs/openapi/genarrative-external-v1.openapi.json
 - 角色图、图标 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 控制面。
@@ -243,20 +243,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，也不在共享文档中记录具体路径或注册内容。

@@ -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 快照仍可读取。