新增 External v1 去背景生成链路

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

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

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

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

.codex/skills/genarrative-external-editor-api/SKILL.md

@@ -27,7 +27,7 @@ Prefer `scripts/genarrative_external_api.py` for runnable REST calls. It uses on
 ## Essential Invariants
 
 - Authenticate MCP and business API calls with `Authorization: Bearer <tnr_sk_...>`. Never ask the user to paste a key into chat or place one in repository files.
-- All eight generation POST routes require `Idempotency-Key` and return HTTP `202`; `202` is durable acceptance, not a media result.
+- All nine generation POST routes require `Idempotency-Key` and return HTTP `202`; `202` is durable acceptance, not a media result.
 - Retry an uncertain submission only with the exact same body and the same idempotency key. A polling timeout is not permission to generate again.
 - Use stable references such as `objectKey`, project resource ID, or asset ID where each operation permits them. Image edit/redraw is stricter: `sourceReferenceId` accepts only a registered project resource ID or asset ID; upload confirmation alone is not enough. Use `/assets/read-url` only for temporary preview/download access.
 - Preserve both warning channels after completion. A general `warning` can coexist with `sliceWarning`; do not discard either.
@@ -106,6 +106,21 @@ client.generate_image(
 )
 ```
 
+For background removal, pass a stable owner-scoped object key, project resource ID, or asset ID; the helper keeps the same asynchronous submission and polling contract:
+
+```python
+session = client.prepare_canvas_session("去背景画布")
+client.remove_background(
+    "editor-upload/object.png",
+    source_width=720,
+    source_height=1280,
+    canvasSession=session,
+    assetLabel="去背景结果",
+)
+```
+
+Background removal preserves the source pixel size. When `canvasSession` is used, pass the real `source_width` and `source_height`, or provide both `canvasWidth` and `canvasHeight`; the helper rejects missing dimensions instead of guessing a square placeholder. `assetKind` may only describe a static image and must match the authoritative source record. Prefer a project resource ID or asset ID when the same object key has multiple semantic registrations; for a raw object key outside in-place replacement, pass `sourceResourceId` to disambiguate. Without `canvasCompletion`, `targetLayerId` may replace only the layer that points to the same authoritative object as the source, and the server durably binds a raw object key to that target resource for Worker revalidation.
+
 Helper convenience methods wait locally, but the server still uses short asynchronous submit/status requests. For durable caller-controlled orchestration, call `submit_generation`, persist its `operationId` and idempotency key, then call `get_generation` or `wait_for_generation`.
 
 For character animation, pass the canvas session and asset label to `animate_character`. The helper submits asynchronously and returns the completed compact result containing the authoritative formal `resource` and `asset`; do not synthesize a library asset from the first frame.

.codex/skills/genarrative-external-editor-api/references/api-operations.md

@@ -51,6 +51,7 @@ Every generation row requires a stable `Idempotency-Key` header and returns HTTP
 | --- | --- | --- | --- |
 | Image generation | `/api/external/v1/editor/images/generations` | `prompt` | `kind`, `style`, `model`, `aspectRatio`, `imageSize`, `size`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
 | Image edit/redraw | `/api/external/v1/editor/images/edits` | `prompt`, `sourceReferenceId` | `referenceImageSrcs`, `model`, `size`, `projectId`, `assetFolderId`, `assetLabel`, `targetLayerId`, `canvasCompletion` |
+| Background removal | `/api/external/v1/editor/images/background-removals` | `sourceImageSrc` | `projectId`, `sourceResourceId`, `targetLayerId`, static-image `assetKind`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
 | Icon spritesheet | `/api/external/v1/editor/icon-spritesheets/generations` | `referenceId`, `iconDescriptions` | `sliceLayout`, `style`, `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` |
 | UI asset extraction | `/api/external/v1/editor/ui-designs/assets/extractions` | `sourceImageSrc`, `aspectRatio`, `imageSize` | `screenColor`, `model`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `spritesheetLabel`, `canvasCompletion` |
 | Character animation | `/api/external/v1/editor/character-animations/generations` | `sourceLayerId`, `sourceImageSrc`, `sourceWidth`, `sourceHeight`, `promptText`, `resolution`, `ratio`, `frameCount`, `durationSeconds`, `model` | `projectId`, `sourceResourceId`, `assetFolderId`, `assetLabel`, `canvasCompletion` |
@@ -58,7 +59,7 @@ Every generation row requires a stable `Idempotency-Key` header and returns HTTP
 | Sound effect | `/api/external/v1/editor/audios/sound-effects/generations` | `prompt` | `model`, `duration`, `loop`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
 | Background music | `/api/external/v1/editor/audios/background-music/generations` | `gptDescriptionPrompt`, `makeInstrumental` | `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
 
-Poll all eight through:
+Poll all nine through:
 
 ```text
 GET /api/external/v1/generations/{operationId}
@@ -72,6 +73,7 @@ Supply the `operationId` returned by submission. Poll no faster than `pollAfterM
 - Pass `assetFolderId` plus `assetLabel` for image, edit, icon spritesheet, video, sound effect, and BGM operations when supported.
 - UI extraction uses `assetFolderId` and `spritesheetLabel`.
 - Character animation accepts `assetFolderId` and `assetLabel`. Its completed compact result directly returns the final `assetKind="character-animation"` resource and asset with `imageSequenceFrames` and `imageSequenceDurationMs`; never create a duplicate first-frame resource or asset.
+- Background removal derives the final static-image `assetKind` from the authoritative source record. A conflicting request kind or any video, audio, animation, or image-sequence kind returns `400` before queueing. Without `canvasCompletion`, `targetLayerId` must point to the same authoritative object as `sourceImageSrc` (prefer `assetObjectId`, otherwise canonical bucket/object key).
 - If a caller must manually create a `character-animation` resource or asset, put the authoritative frames and total sequence duration in `imageSequenceFrames` and `imageSequenceDurationMs`. Keep `generationInputs` replayable: it must not contain legacy runtime fields such as `characterAnimation`, `frames`, `previewVideoPath`, `frameCount`, `fps`, or `durationSeconds`.
 - Reload project/library state after completion when full current state is required.
 

.codex/skills/genarrative-external-editor-api/references/capability-routing.md

@@ -47,6 +47,7 @@ Infer what is already clear and ask only for missing fields that block the selec
 | --- | --- |
 | Generate a background, character, spec, UI mockup, or publication image | Image generation |
 | Redraw, retouch, or replace an existing image | Image edit |
+| Remove the background from an existing image | Background removal |
 | Generate from a local reference | Upload and confirm the local file, then image generation or edit |
 | Build a reusable transparent icon/game atlas from a visual spec | Icon spritesheet generation |
 | Extract marked assets from an existing UI design | UI design asset extraction |

.codex/skills/genarrative-external-editor-api/references/requests-and-outputs.md

@@ -15,7 +15,7 @@ Use this reference to build generation payloads, carry canvas/library context, p
 
 ## Asynchronous Submission
 
-All eight generation POST routes require `Idempotency-Key` and return HTTP `202` with an `ExternalEditorGenerationSubmissionResponse` shaped like:
+All nine generation POST routes require `Idempotency-Key` and return HTTP `202` with an `ExternalEditorGenerationSubmissionResponse` shaped like:
 
 ```json
 {
@@ -71,6 +71,8 @@ status = client.get_generation(operation_id)
 completed = client.wait_for_generation(operation_id)
 ```
 
+Background removal uses the same submission and polling state machine. `sourceImageSrc` must be a stable owner-scoped object key, project resource ID, or asset ID; never pass a Data URL, Blob URL, or expiring signed URL. An explicit resource ID or asset ID is resolved before any object-key fallback. If a raw object key has multiple registrations with conflicting authoritative metadata, pass `sourceResourceId` to disambiguate or the server returns `400`. Use `projectId + canvasCompletion` for normal canvas placement. When `canvasCompletion` is absent, `projectId + targetLayerId` replaces an existing resource-backed layer and is rejected before queueing if the target is invalid; for a raw object key, the target resource becomes the durable source binding rechecked by the Worker. If both placement fields are absent, the server does not add the result to the canvas. The completed compact result contains the stable output object key, dimensions, and persisted resource/asset references when requested.
+
 ## Canvas and Asset-Library Completion
 
 For endpoints that support these fields, include:
@@ -98,6 +100,8 @@ A minimal `canvasCompletion` is:
 
 `dialogId` is optional. The placeholder supplies canvas placement and completion coordinates; it is not a final media pixel-size constraint. For successful pixel-art snapping, the result layer uses the final logical-grid PNG dimensions even when they differ from the placeholder. Do not reconstruct canvas state from completion results. Reload the project and asset library when complete authoritative snapshots are needed.
 
+Background removal preserves the source image dimensions. The Python helper therefore requires the real `source_width` and `source_height` whenever `canvasSession` is used without an explicit `canvasWidth` plus `canvasHeight`; it never substitutes a square default. The request `assetKind` is optional, static-image only, and must equal the authoritative source type when one exists. Without `canvasCompletion`, an in-place `targetLayerId` must resolve to the same authoritative source object; a raw object key is bound to that target resource instead of relying on project-list order.
+
 Character animation accepts `assetFolderId` and `assetLabel` and persists the final transparent sequence directly. Its completed compact result includes the authoritative `assetKind="character-animation"` resource and asset with `imageSequenceFrames` and `imageSequenceDurationMs`. Use those records directly and never synthesize a duplicate asset from the first frame.
 
 For the lower-level asset/resource creation endpoints, `generationInputs` is replayable request context rather than a media-runtime container. When `assetKind` is `character-animation`, the server rejects legacy runtime keys including `characterAnimation`, `frames`, `previewVideoPath`, `frameCount`, `fps`, and `durationSeconds`; send the formal sequence through `imageSequenceFrames` and `imageSequenceDurationMs`. Internal processing audit keys such as `screenColorHex`, `mattingProvider`, and `mattingModel` are removed before persistence.

.codex/skills/genarrative-external-editor-api/scripts/genarrative_external_api.py

@@ -561,6 +561,51 @@ class GenarrativeExternalClient:
             idempotency_key=idempotency_key,
         )
 
+    def remove_background(
+        self,
+        source_image_src: str,
+        source_width: int | None = None,
+        source_height: int | None = None,
+        **fields: Any,
+    ) -> Any:
+        source_image_src = normalize_optional_text(source_image_src)
+        if not source_image_src:
+            raise GenarrativeApiError(
+                "source_image_src must be an owner-scoped object key, resource ID, or asset ID"
+            )
+        if (source_width is None) != (source_height is None):
+            raise GenarrativeApiError("source_width and source_height must be provided together")
+        if source_width is not None and (
+            source_width <= 0 or source_height is None or source_height <= 0
+        ):
+            raise GenarrativeApiError("source_width and source_height must be positive integers")
+        session = fields.get("canvasSession")
+        if session is None:
+            session = fields.get("canvas_session")
+        canvas_width = fields.get("canvasWidth")
+        canvas_height = fields.get("canvasHeight")
+        if (canvas_width is None) != (canvas_height is None):
+            raise GenarrativeApiError("canvasWidth and canvasHeight must be provided together")
+        if session is not None and canvas_width is None:
+            if source_width is None or source_height is None:
+                raise GenarrativeApiError(
+                    "remove_background requires source_width and source_height when canvasSession is used without canvasWidth/canvasHeight"
+                )
+            fields["canvasWidth"] = source_width
+            fields["canvasHeight"] = source_height
+        self._apply_canvas_session_fields(
+            fields,
+            fields.get("assetLabel", "去背景结果"),
+            source_width or 1,
+            source_height or 1,
+        )
+        idempotency_key = fields.pop("idempotencyKey", None)
+        return self.submit_and_wait_generation(
+            "/api/external/v1/editor/images/background-removals",
+            {"sourceImageSrc": source_image_src, **fields},
+            idempotency_key=idempotency_key,
+        )
+
     def generate_icon_spritesheet(
         self,
         reference_id: str,
@@ -687,11 +732,14 @@ def _self_test() -> None:
         b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR"
         b"\x00\x00\x00\x02\x00\x00\x00\x03\x08\x06\x00\x00\x00"
     )
-    with tempfile.NamedTemporaryFile(suffix="Hero Image.png") as fh:
+    with tempfile.NamedTemporaryFile(suffix="Hero Image.png", delete=False) as fh:
         fh.write(png)
-        fh.flush()
-        assert image_dimensions(fh.name) == (2, 3)
-        assert source_layer_id_from_path(fh.name).startswith("external-reference-")
+        temp_path = fh.name
+    try:
+        assert image_dimensions(temp_path) == (2, 3)
+        assert source_layer_id_from_path(temp_path).startswith("external-reference-")
+    finally:
+        Path(temp_path).unlink(missing_ok=True)
     assert unwrap_envelope({"ok": True, "data": {"upload": 1}}) == {"upload": 1}
     client = GenarrativeExternalClient(api_key="test")
     session = {"projectId": "proj-demo", "assetFolderId": "editor-asset-folder-demo"}
@@ -773,6 +821,30 @@ def _self_test() -> None:
     assert len(result["asset"]["imageSequenceFrames"]) == 2
     assert result["asset"]["imageSequenceDurationMs"] == 4000
     calls.clear()
+    background_result = client.remove_background(
+        "uploads/source.png",
+        720,
+        1280,
+        canvasSession=session,
+        assetLabel="去背景结果",
+    )
+    assert background_result["taskId"] == "task-demo"
+    assert calls[0]["path"] == "/api/external/v1/editor/images/background-removals"
+    assert calls[0]["body"]["sourceImageSrc"] == "uploads/source.png"
+    assert calls[0]["body"]["projectId"] == "proj-demo"
+    assert calls[0]["body"]["assetFolderId"] == "editor-asset-folder-demo"
+    assert calls[0]["body"]["assetLabel"] == "去背景结果"
+    assert calls[0]["body"]["canvasCompletion"]["title"] == "去背景结果"
+    assert calls[0]["body"]["canvasCompletion"]["placeholder"]["width"] == 720
+    assert calls[0]["body"]["canvasCompletion"]["placeholder"]["height"] == 1280
+    calls.clear()
+    try:
+        client.remove_background("uploads/source.png", canvasSession=session)
+    except GenarrativeApiError as error:
+        assert "source_width and source_height" in str(error)
+    else:
+        raise AssertionError("canvas background removal must not guess source dimensions")
+    assert calls == []
     client.generate_icon_spritesheet(
         "editor-resource-spec",
         ["蛇头向上", "蛇身直线", "转角", "尾部", "四类食物"],