新增 External v1 去背景生成链路

新增外部去背景 API、MCP 工具与异步队列契约

补齐来源归属、媒体类型、幂等重放和画布原子持久化校验

修复 provenance 重建、assetKindOverride 门禁与 revision retry 竞态

同步 Python helper、Skill、OpenAPI 及项目文档

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

@@ -1145,6 +1145,60 @@
         }
       }
     },
+    "/api/external/v1/editor/images/background-removals": {
+      "post": {
+        "tags": [
+          "Editor Images"
+        ],
+        "operationId": "removeExternalEditorImageBackground",
+        "summary": "去除编辑器图片背景",
+        "description": "提交已有静态图片素材的异步去背景任务。sourceImageSrc 只接受当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID；禁止 Data URL、Blob URL 和临时 signed URL。assetKind 只能表达静态图片，并且存在权威来源记录时必须与其类型一致；视频、音频、动画和图片序列在入队前返回 400。服务端固定使用 complex 去背景模式，不会在失败时切换到其它 provider。需要写入画布时提供 projectId 与 canvasCompletion；仅需原位替换既有图层时提供 projectId 与 targetLayerId，且来源与目标必须指向同一权威对象。",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/IdempotencyKey"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorBackgroundRemovalRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "去背景任务已持久化入队",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
+      }
+    },
     "/api/external/v1/editor/icon-spritesheets/generations": {
       "post": {
         "tags": [
@@ -2339,7 +2393,8 @@
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "可选的来源项目资源 ID，用于在同一 objectKey 被多个资源以不同权威元数据登记时消歧。sourceImageSrc 已是项目资源 ID 或素材 ID 时按该显式 ID 定点解析；纯 objectKey 无法唯一确定权威来源时必须提供本字段，否则返回 400。原位替换使用纯 objectKey 且省略本字段时，服务端自动绑定 targetLayerId 对应的当前项目资源，并把该绑定写入队列供 Worker 复验。"
           },
           "assetKind": {
             "type": [
@@ -3550,6 +3605,75 @@
         },
         "additionalProperties": false
       },
+      "EditorBackgroundRemovalRequest": {
+        "type": "object",
+        "required": [
+          "sourceImageSrc"
+        ],
+        "properties": {
+          "sourceImageSrc": {
+            "type": "string",
+            "minLength": 1,
+            "description": "当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID。禁止 Data URL、Blob URL 和临时 signed URL。"
+          },
+          "projectId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "可选项目上下文。提供 targetLayerId 时必须同时提供非空 projectId，否则在入队前返回 400。"
+          },
+          "targetLayerId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "提供时必须同时提供 projectId。仅在未提供 canvasCompletion 时用于原位替换既有画布图层，此时目标图层必须存在、关联当前项目静态图片资源；若图层提供 assetKindOverride，则以覆盖后的有效类型参与静态媒体门禁和来源类型比较。来源与目标必须指向同一权威对象：双方都有 assetObjectId 时按 ID 比较，任一缺失时回退 canonical bucket/objectKey；违反任一条件均在入队前返回 400。存在 canvasCompletion 时不参与原位替换。省略 targetLayerId 与 canvasCompletion 时只持久化请求指定的项目资源或素材库记录，不自动写入画布。"
+          },
+          "sourceResourceId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "可选的来源项目资源 ID，用于在同一 objectKey 被多个资源以不同权威元数据登记时消歧。sourceImageSrc 已是项目资源 ID 或素材 ID 时按该显式 ID 定点解析；纯 objectKey 无法唯一确定权威来源时必须提供本字段，否则返回 400。原位替换使用纯 objectKey 且省略本字段时，服务端自动绑定 targetLayerId 对应的当前项目资源，并把该绑定写入队列供 Worker 复验。"
+          },
+          "assetKind": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "可选静态图片语义类型。服务端优先采用来源项目资源或素材库记录的权威语义类型；资产对象存储类型只参与非静态媒体门禁，不覆盖语义类型。请求值与权威来源类型不一致，或任一记录表示 video、audio、animation、image-sequence、sound-effect、background-music 等非静态媒体时，在入队前返回 400。",
+            "x-genarrative-media-family": "static-image"
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "assetFolderId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetLabel": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "canvasCompletion": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "画布生成占位完成指令。提供时优先按生成完成链路写入结果，targetLayerId 不参与原位替换。"
+          }
+        },
+        "additionalProperties": false
+      },
       "EditorImageGenerationResponse": {
         "type": "object",
         "required": [

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

@@ -1,5 +1,12 @@
 # 决策记录
 
+## 2026-08-23 External 去背景绑定权威静态来源与真实画布尺寸
+
+- 背景：External v1 去背景曾把调用方 `assetKind` 原样带入持久化，并允许 `sourceImageSrc=A + targetLayerId=B` 覆盖不同资源；Python helper 又为所有画布完成请求固定生成 `1024×1024` 占位，导致非方形透明结果按占位尺寸拉伸。
+- 决策：入队前从当前 owner 的项目资源或素材库解析来源权威语义类型，资产对象存储类型只参与非静态媒体门禁；显式项目资源 ID / 素材 ID 优先于 objectKey 回退，同一纯 objectKey 对应的候选权威元数据不一致时返回 `400` 并要求用 `sourceResourceId` 或业务 ID 消歧，禁止按列表首条决定类型。请求类型冲突或任一记录属于视频、音频、动画、图片序列时返回 `400`，队列只保存服务端解析出的静态语义类型。无 `canvasCompletion` 的原位替换优先比较双方 `assetObjectId`，任一缺失时回退 canonical `(bucket, objectKey)`，并要求默认类型一致；纯 objectKey 省略 `sourceResourceId` 时自动绑定目标图层资源并写入队列，由 Worker 复验同一绑定。helper 使用画布会话时必须取得真实源宽高或显式 `canvasWidth + canvasHeight`，不再猜测方形尺寸。
+- 影响范围：External v1 去背景入队与 worker 复验、OpenAPI、Python helper、外部编辑器 skill 和相关契约测试；不修改 SpacetimeDB schema、BgFilter 协议或去背景输出尺寸语义。
+- 验证方式：覆盖非静态类型与权威类型冲突、来源/目标不同对象拒绝及同对象通过、非方形 helper completion；运行 api-server 定向测试、helper self-test、OpenAPI 解析、编码与 diff 门禁。
+
 ## 2026-08-20 UI Editor LLM 递归输出与参考图单文件限制
 
 - 背景：结构识别、界面语义建议和多图合并直接把 LLM 工具 arguments 反序列化为递归树；结构识别与语义建议还在 async command 中同步读取并 base64 编码参考图。模型异常输出或过大图片可能造成不受控内存、栈和 async worker 占用。
@@ -6492,6 +6499,7 @@
 - Agent 发现：新增公开 `agent-integration.json`、`skill/SKILL.md` 和 `skill.zip`。manifest 同时声明 MCP、OpenAPI、完整 Skill archive、SHA-256 和包内清单；archive 必须包含 `SKILL.md`、上述四篇 references、stdlib Python helper 和 `agents/openai.yaml` 七个声明文件，不能只提供 OpenAPI JSON，也不能包含 API Key、本机路径或个人配置。完整 `skill.zip` 只供不支持 MCP 或需要本地文件上传编排的 Agent 使用，不作为 MCP resource。
 - 兼容边界：这是基于「截至 2026-07-31 尚无外部第三方存量调用方」接受的 v1 原地 breaking change；一旦出现外部活跃 Key、公开契约或联调方，后续破坏性变更必须保留兼容、经过弃用期或升级 `/api/external/v2`。
 - 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`.codex/skills/genarrative-external-editor-api/SKILL.md`。
+- 2026-08-23 补充：新增 `POST /api/external/v1/editor/images/background-removals` 后，External v1 生成 POST 由八类增至九类；该入口继续使用 `editor:image-generate` scope、稳定 `Idempotency-Key`、`202 + operationId` 与统一查询合同。外部请求只允许 OpenAPI 声明的去背景字段，拒绝内部 `taskId` 和其它未声明字段；入队前按当前 owner 解析稳定来源并规范化为权威 objectKey，同时预检、规范化项目与素材目录目标。提供 `targetLayerId` 时始终必须同时提供 `projectId`；没有 `canvasCompletion` 时目标图层必须存在并关联当前项目资源，存在 `canvasCompletion` 时沿用生成完成链路且不执行原位替换；目标无效、引用未登记或越权时不创建任务。未提供任一画布完成字段时不自动写入画布；任务 ID 仅由服务端队列生成。
 
 ## 2026-08-04 图片画布 BGM Prompt 采用唯一可见规范化文本与面板级同步提交锁
 
@@ -13564,6 +13572,7 @@
 - Agent 发现：新增公开 `agent-integration.json`、`skill/SKILL.md` 和 `skill.zip`。manifest 同时声明 MCP、OpenAPI、完整 Skill archive、SHA-256 和包内清单；archive 必须包含 `SKILL.md`、上述四篇 references、stdlib Python helper 和 `agents/openai.yaml` 七个声明文件，不能只提供 OpenAPI JSON，也不能包含 API Key、本机路径或个人配置。完整 `skill.zip` 只供不支持 MCP 或需要本地文件上传编排的 Agent 使用，不作为 MCP resource。
 - 兼容边界：这是基于「截至 2026-07-31 尚无外部第三方存量调用方」接受的 v1 原地 breaking change；一旦出现外部活跃 Key、公开契约或联调方，后续破坏性变更必须保留兼容、经过弃用期或升级 `/api/external/v2`。
 - 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`.codex/skills/genarrative-external-editor-api/SKILL.md`。
+- 2026-08-23 补充：新增 `POST /api/external/v1/editor/images/background-removals` 后，External v1 生成 POST 由八类增至九类；该入口继续使用 `editor:image-generate` scope、稳定 `Idempotency-Key`、`202 + operationId` 与统一查询合同。外部请求只允许 OpenAPI 声明的去背景字段，拒绝内部 `taskId` 和其它未声明字段；入队前按当前 owner 解析稳定来源并规范化为权威 objectKey，同时预检、规范化项目与素材目录目标，未登记、越权引用和无效目标不创建任务；任务 ID 仅由服务端队列生成。托管 MCP 不再维护异步生成 operation 的幂等硬编码名单，而是从 OpenAPI operation/path 的 required `Idempotency-Key` header 自动生成 `idempotencyKey` 工具参数并转发同名 HTTP 头，避免新增 operation 只出现在 `tools/list` 却无法实际提交。
 
 ## 2026-08-04 图片画布 BGM Prompt 采用唯一可见规范化文本与面板级同步提交锁
 

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

@@ -8,7 +8,7 @@
 
 ## 背景
 
-VectorEngine `gpt-image-2`、音频、LLM 等外部生成不能由面向外部调用方的 HTTP 请求长期等待上游、OSS 持久化和 SpacetimeDB 回写。站内保留受控 `inline` 排障模式；External v1 的八类生成则固定使用持久队列和统一查询接口，避免调用方超时后重复提交、重复扣费或丢失已完成结果。
+VectorEngine `gpt-image-2`、音频、LLM 等外部生成不能由面向外部调用方的 HTTP 请求长期等待上游、OSS 持久化和 SpacetimeDB 回写。站内保留受控 `inline` 排障模式；External v1 的九类生成则固定使用持久队列和统一查询接口，避免调用方超时后重复提交、重复扣费或丢失已完成结果。
 
 ## 目标
 
@@ -117,7 +117,7 @@ pending/running -> cancelled    (预留)
 - `queue`：默认值，HTTP handler 入队 `external_generation_job`，由 `external-generation-worker` 角色 claim lease 后执行；生产、预发和压测默认使用该模式。
 - `inline`：HTTP handler 直接调用同一个 worker executor，同步等待 provider、OSS 和 SpacetimeDB 写回完成后返回 `operation.status = completed`；只用于本地或低并发排查，不提供队列持久化、lease 重领和 worker 横向扩容。
 
-External v1 八类生成不读取上述模式分支：即使进程配置为 `inline`，External handler 仍只做校验、幂等入队并返回 HTTP `202`。调用方按 `/api/external/v1/generations/{operationId}` 查询；这条外部契约不能因部署环境不同而从异步退化为同步响应。
+External v1 九类生成不读取上述模式分支：即使进程配置为 `inline`，External handler 仍只做校验、幂等入队并返回 HTTP `202`。调用方按 `/api/external/v1/generations/{operationId}` 查询；这条外部契约不能因部署环境不同而从异步退化为同步响应。
 
 同一个 Rust binary 通过 `GENARRATIVE_PROCESS_ROLE` 切换：
 
@@ -220,7 +220,7 @@ inline 完成结果与 External v1 completed compact result 继续使用结构
 
 ### External v1 异步提交与查询
 
-External v1 复用上述九类 editor job kind 中除手动去背景外的八类生成 kind。外部 POST handler 只负责 API Key scope、owner、请求校验和入队，不调用 `*_for_owner` 同步执行函数：
+External v1 复用上述全部九类 editor job kind，包括手动去背景。外部 POST handler 只负责 API Key scope、owner、请求校验和入队，不调用 `*_for_owner` 同步执行函数；去背景在入队前还会解析当前 owner 的稳定来源，并预检、规范化项目与素材目录目标。提供 `targetLayerId` 时必须同时提供 `projectId`；没有 `canvasCompletion` 时还要确认目标图层存在并关联当前项目资源，存在 `canvasCompletion` 时继续按生成完成链路写入而不执行原位替换：
 
 1. 每个生成 POST 必须携带 `Idempotency-Key`。服务端把 owner、job kind、稳定键和规范请求纳入 dedupe；未知结果重试必须复用原键。
 2. 成功入队返回 HTTP `202`、`operationId`、`statusUrl`、`pollAfterMs`，并设置 `Location` / `Retry-After`；不返回 project、asset 或媒体结果。