新抠图算法 (#85)

Co-authored-by: 段舒康 <kdletters@qq.com>
Reviewed-on: https://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/85
Co-authored-by: Linghong <ink29535@proton.me>
Co-committed-by: Linghong <ink29535@proton.me>

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

@@ -969,7 +969,7 @@
           "Editor Images"
         ],
         "operationId": "generateExternalEditorIconSpritesheet",
-        "summary": "按规范图生成并拆分图标素材",
+        "summary": "按规范图生成图标 spritesheet 并尝试拆分",
         "security": [
           {
             "ExternalApiKey": []
@@ -987,7 +987,7 @@
         },
         "responses": {
           "200": {
-            "description": "图标 spritesheet、切片结果与落库资源",
+            "description": "图标 spritesheet、实际切片结果、可选非阻断告警与落库资源",
             "content": {
               "application/json": {
                 "schema": {
@@ -1017,7 +1017,7 @@
           "Editor Images"
         ],
         "operationId": "extractExternalEditorUiDesignAssets",
-        "summary": "从 UI 设计图拆分素材",
+        "summary": "从 UI 设计图生成素材 spritesheet 并尝试拆分",
         "security": [
           {
             "ExternalApiKey": []
@@ -1035,7 +1035,7 @@
         },
         "responses": {
           "200": {
-            "description": "UI 设计图素材 spritesheet、切片结果与落库资源",
+            "description": "UI 设计图素材 spritesheet、实际切片结果、可选非阻断告警与落库资源",
             "content": {
               "application/json": {
                 "schema": {
@@ -2849,6 +2849,17 @@
               }
             ],
             "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
+          },
+          "warning": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorGenerationWarning"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "生成成功但后处理降级时返回的非阻断告警。"
           }
         }
       },
@@ -3090,6 +3101,25 @@
         },
         "additionalProperties": false
       },
+      "EditorGenerationWarning": {
+        "type": "object",
+        "required": [
+          "code",
+          "reason"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "const": "postprocess-failed-source-preserved",
+            "description": "透明背景处理最终失败并保留 provider 原图时的稳定原因码。"
+          },
+          "reason": {
+            "type": "string",
+            "description": "可直接展示给调用方的非阻断告警原因。"
+          }
+        },
+        "additionalProperties": false
+      },
       "EditorIconSpritesheetGenerationResponse": {
         "type": "object",
         "required": [
@@ -3130,7 +3160,7 @@
                 "type": "null"
               }
             ],
-            "description": "图集已成功持久化，但自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。"
+            "description": "图集已成功持久化，但自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。与通用 warning 互斥。"
           },
           "prompt": {
             "type": "string"
@@ -3184,7 +3214,24 @@
               }
             ],
             "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
+          },
+          "warning": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorGenerationWarning"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "透明背景处理最终失败、provider 原图作为主结果时返回的非阻断告警。与 sliceWarning 互斥。"
           }
+        },
+        "not": {
+          "required": [
+            "warning",
+            "sliceWarning"
+          ]
         }
       },
       "EditorCharacterAnimationGenerationRequest": {