补齐抠图参数透传与验收

修复flat自动识别门禁并严格校验模式和颜色

保持旧请求幂等指纹并区分客户端抠图意图

同步工具说明和Skill契约并补充定向测试

记录真实BgFilter验证及本地数据库阻塞的待验收项

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-client-projection/SKILL.md

@@ -14,7 +14,7 @@ Let the client derive projections from real disk changes and trusted tool result
 3. Keep read scopes separate: `asset.list` is the current project manifest, `asset.library.list` is the signed-in account library, and the web project's canvas resource read model is the authoritative canvas list. The account library is not the complete canvas list.
 4. Use `canvas.asset_import` for safe account/canvas asset IDs or project-relative local paths. The client rechecks ownership and validates bytes; host absolute paths require native UI file-picker authorization.
 5. When the user explicitly asks to create or derive video, character animation, sound effect, or background music, call `agc_create_or_derive_resource`. Use `create` only for video/audio without a source and `derive` with a registered `sourceLocalAssetId`; character animation is always derived from an image.
-6. When the user explicitly asks to remove an image background, call `agc_remove_background` with a registered image `sourceLocalAssetId` and an output name. The client requires the signed-in account, owns canvas/folder context and task identity, and returns only bounded queue state.
+6. When the user explicitly asks to remove an image background, call `agc_remove_background` with a registered image `sourceLocalAssetId` and `assetName`. Optional `backgroundMode` is `complex` (semantic foreground segmentation; default) or `flat` (solid-colour background removal). Prefer `flat` when the background is known to be solid. Only `flat` accepts optional `screenColor`: `auto`, `#RRGGBB`, or omitted for automatic detection by the service. Do not select a colour on behalf of `auto`. The client requires the signed-in account, owns canvas/folder context and task identity, and returns only bounded queue state.
 7. Preserve existing relative paths when a small edit is sufficient so client resource identities remain stable.
 8. Do not edit `.agent/manifest.json`, revision counters, version records, resource IDs, canvas identities, source provenance, generation ledgers, or browser receipts by hand.
 9. Do not create a version when no game file changed. The client compares content fingerprints and advances revision only after an actual source change.

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-client-projection/references/projection-contract.md

@@ -14,4 +14,4 @@ Read scopes remain separate: `asset.list` is the current project's local manifes
 
 `agc_create_or_derive_resource` accepts only semantic intent. The client resolves `sourceLocalAssetId`, creates stable request identities, recovers matching pending operations, serializes paid submissions, writes supported media into the current canvas and same-name asset folder, validates downloaded bytes, commits the local manifest transaction, and returns redacted warnings. A tool error or timeout is not permission to generate again with a new identity.
 
-`agc_remove_background` is the semantic image post-processing path. It accepts only a registered image `sourceLocalAssetId` and output name; the client resolves the formal source resource, canvas/folder context, stable operation identity, idempotency key, and authenticated External v1 `/api/external/v1/editor/images/background-removals` call. Its result is bounded queue state; Codex must not poll internal workers, construct source URLs, or retry with a new identity after an uncertain response.
+`agc_remove_background` accepts a registered image `sourceLocalAssetId`, `assetName`, and optional `backgroundMode` and `screenColor`. `complex` uses semantic segmentation to identify the foreground; `flat` removes a solid-colour background. Prefer `flat` when the background is known to be solid; omitting the mode selects `complex`. Only `flat` accepts a colour: `auto`, `#RRGGBB`, or omitted for automatic service detection. Never infer a concrete colour for `auto`. Empty or invalid values and colour without `flat` are rejected. The client resolves the formal source resource, canvas/folder context, stable operation identity, idempotency key, and authenticated External v1 `/api/external/v1/editor/images/background-removals` call. Mode and colour are part of request identity. Its result is bounded queue state; Codex must not poll internal workers, construct source URLs, or retry with a new identity after an uncertain response.

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "agc-skill-pack.v1",
-  "version": "2026-08-26.16",
+  "version": "2026-08-26.17",
   "skills": [
     {
       "name": "agc-game-production-workflow",
@@ -123,7 +123,7 @@
         "agents/openai.yaml",
         "references/projection-contract.md"
       ],
-      "sha256": "96b5bf9e2ed150bbe934a888867c1bb500b214a131f8b36c4830f51ca30267b6"
+      "sha256": "a929c27bc5b2b0bee0b7935e5c7b04ddbab1eb1804fe196f8c2537ad040ca5b1"
     }
   ]
 }

apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs

@@ -1887,15 +1887,7 @@ async fn bridge_create_or_derive_resource(
 
 async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Value) -> Value {
     let result = async {
-        bridge_reject_unknown_fields(
-            arguments,
-            &[
-                "sourceLocalAssetId",
-                "assetName",
-                "backgroundMode",
-                "screenColor",
-            ],
-        )?;
+        super::direct_tools_mcp::validate_remove_background_arguments(arguments)?;
         enforce_project_permission_policy(&state.root, "canvas.asset_generate")?;
         enforce_project_permission_policy(&state.root, "asset.register")?;
         let source_asset_id = bridge_bounded_string(arguments, "sourceLocalAssetId", 80)?;
@@ -1904,26 +1896,8 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
             "assetName",
             DIRECT_TOOL_BRIDGE_MAX_RESOURCE_NAME_CHARS,
         )?;
-        let background_mode = bridge_optional_bounded_string(arguments, "backgroundMode", 16)?;
-        let screen_color = bridge_optional_bounded_string(arguments, "screenColor", 16)?;
-        if let Some(mode) = background_mode.as_deref() {
-            if mode != "complex" && mode != "flat" {
-                return Err("backgroundMode 必须是 complex 或 flat".to_string());
-            }
-        }
-        if let Some(color) = screen_color.as_deref() {
-            let valid_hex = color.len() == 7
-                && color.starts_with('#')
-                && color[1..]
-                    .chars()
-                    .all(|character| character.is_ascii_hexdigit());
-            if color != "auto" && !valid_hex {
-                return Err("screenColor 必须是 auto 或 #RRGGBB".to_string());
-            }
-            if background_mode.as_deref() == Some("complex") {
-                return Err("complex 模式不能传 screenColor".to_string());
-            }
-        }
+        let background_mode = arguments.get("backgroundMode").and_then(Value::as_str);
+        let screen_color = arguments.get("screenColor").and_then(Value::as_str);
         let manifest = read_existing_manifest_for_project(&state.root)?;
         let source_asset = manifest
             .assets
@@ -1948,24 +1922,34 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
             .map_err(|_| "创建抠图服务连接失败".to_string())?;
         let context =
             prepare_external_canvas_generation_context(&state.root, &client, &access).await?;
-        let fingerprint = format!("{}\0{}", source_asset_id, asset_name);
+        let fingerprint = background_removal_request_fingerprint(
+            &source_asset_id,
+            &asset_name,
+            background_mode,
+            screen_color,
+        );
         let (_operation_id, idempotency_key) = state.resource_request_ids(&fingerprint)?;
         let route = "/api/external/v1/editor/images/background-removals";
+        let mut request_body = json!({
+            "sourceImageSrc": source_resource_id,
+            "projectId": manifest.project_id,
+            "assetKind": source_asset.kind,
+            "assetFolderId": context.asset_folder_id,
+            "assetLabel": asset_name,
+            "sourceResourceId": source_resource_id,
+        });
+        if background_mode == Some("flat") {
+            request_body["backgroundMode"] = json!("flat");
+        }
+        if let Some(color) = screen_color {
+            request_body["screenColor"] = json!(color);
+        }
         let response = crate::http_client::with_agc_main_site_marker(
             client
                 .post(format!("{}{}", api_base_url, route))
                 .bearer_auth(api_key)
                 .header("Idempotency-Key", idempotency_key)
-                .json(&json!({
-                    "sourceImageSrc": source_resource_id,
-                    "projectId": manifest.project_id,
-                    "assetKind": source_asset.kind,
-                    "assetFolderId": context.asset_folder_id,
-                    "assetLabel": asset_name,
-                    "sourceResourceId": source_resource_id,
-                    "backgroundMode": background_mode,
-                    "screenColor": screen_color,
-                })),
+                .json(&request_body),
         )
         .send()
         .await
@@ -2002,6 +1986,20 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
     }
 }
 
+fn background_removal_request_fingerprint(
+    source: &str,
+    name: &str,
+    mode: Option<&str>,
+    color: Option<&str>,
+) -> String {
+    let mode = mode.unwrap_or("complex");
+    if mode == "complex" && color.is_none() {
+        format!("{source}\0{name}")
+    } else {
+        format!("{source}\0{name}\0{mode}\0{}", color.unwrap_or(""))
+    }
+}
+
 fn bridge_safe_queue_state(value: Value) -> Value {
     let object = value.as_object();
     json!({
@@ -2733,6 +2731,29 @@ pub(crate) async fn start_direct_tool_bridge(
 
 #[cfg(test)]
 mod tests {
+    #[test]
+    fn remove_background_identity_preserves_default_and_distinguishes_options() {
+        let legacy = "asset-1\0透明图";
+        assert_eq!(
+            background_removal_request_fingerprint("asset-1", "透明图", None, None),
+            legacy
+        );
+        assert_eq!(
+            background_removal_request_fingerprint("asset-1", "透明图", Some("complex"), None),
+            legacy
+        );
+        let mut identities = std::collections::HashSet::new();
+        identities.insert(legacy.to_string());
+        for color in [None, Some("auto"), Some("#CFEFFF"), Some("#112233")] {
+            let id =
+                background_removal_request_fingerprint("asset-1", "透明图", Some("flat"), color);
+            assert_eq!(
+                id,
+                background_removal_request_fingerprint("asset-1", "透明图", Some("flat"), color)
+            );
+            assert!(identities.insert(id));
+        }
+    }
     use super::*;
     use std::io::{Cursor, Read, Write};
 

apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs

@@ -435,7 +435,7 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab
         }),
         json!({
                 "name": "agc_remove_background",
-                "description": "为当前项目已登记的图片资源去除背景。客户端使用当前登录账号的抠图服务、项目画布和素材目录，模型只能提供已登记资源身份与结果名称；不会返回 Token、内部路由、宿主路径或临时签名 URL。",
+                "description": "为当前项目已登记的图片资源去除背景。complex 通过语义分割识别前景；flat 用于纯色背景抠图，确定背景为纯色时优先选择 flat。提供资源身份、结果名称及可选模式和背景色；客户端管理登录、项目画布和素材目录，不返回 Token、内部路由、宿主路径或临时签名 URL。",
                 "inputSchema": {
                     "type": "object",
                     "properties": {
@@ -891,7 +891,7 @@ fn validate_resource_generation_arguments(arguments: &Value) -> Result<(), Strin
     }
 }
 
-fn validate_remove_background_arguments(arguments: &Value) -> Result<(), String> {
+pub(super) fn validate_remove_background_arguments(arguments: &Value) -> Result<(), String> {
     validate_tool_object_fields(
         arguments,
         &[
@@ -927,7 +927,7 @@ fn validate_remove_background_arguments(arguments: &Value) -> Result<(), String>
         if color != "auto" && !valid_hex {
             return Err("screenColor 必须是 auto 或 #RRGGBB".to_string());
         }
-        if arguments.get("backgroundMode").and_then(Value::as_str) == Some("complex") {
+        if arguments.get("backgroundMode").and_then(Value::as_str) != Some("flat") {
             return Err("complex 模式不能传 screenColor".to_string());
         }
     }
@@ -1889,6 +1889,50 @@ pub(crate) fn stop_game_creator_external_mcp() -> Result<(), String> {
 
 #[cfg(test)]
 mod tests {
+    #[test]
+    fn remove_background_arguments_enforce_mode_color_contract() {
+        for fields in [
+            json!({}),
+            json!({"backgroundMode":"complex"}),
+            json!({"backgroundMode":"flat"}),
+            json!({"backgroundMode":"flat","screenColor":"auto"}),
+            json!({"backgroundMode":"flat","screenColor":"#Ab12EF"}),
+        ] {
+            let mut arguments = json!({"sourceLocalAssetId":"asset-1","assetName":"透明图"});
+            arguments
+                .as_object_mut()
+                .unwrap()
+                .extend(fields.as_object().unwrap().clone());
+            assert!(
+                validate_remove_background_arguments(&arguments).is_ok(),
+                "{fields}"
+            );
+        }
+        for fields in [
+            json!({"screenColor":"auto"}),
+            json!({"backgroundMode":"complex","screenColor":"auto"}),
+            json!({"backgroundMode":"flat","screenColor":""}),
+            json!({"backgroundMode":"flat","screenColor":" auto "}),
+            json!({"backgroundMode":"flat","screenColor":"AUTO"}),
+            json!({"backgroundMode":"flat","screenColor":"#GGGGGG"}),
+            json!({"backgroundMode":"flat","screenColor":null}),
+            json!({"backgroundMode":"flat","screenColor":12}),
+            json!({"backgroundMode":""}),
+            json!({"backgroundMode":"FLAT"}),
+            json!({"backgroundMode":" flat "}),
+            json!({"backgroundMode":null}),
+        ] {
+            let mut arguments = json!({"sourceLocalAssetId":"asset-1","assetName":"透明图"});
+            arguments
+                .as_object_mut()
+                .unwrap()
+                .extend(fields.as_object().unwrap().clone());
+            assert!(
+                validate_remove_background_arguments(&arguments).is_err(),
+                "{fields}"
+            );
+        }
+    }
     use super::*;
 
     #[cfg(all(windows, feature = "cocos-editor-execute"))]

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

@@ -3215,12 +3215,12 @@
             "type": ["string", "null"],
             "enum": ["complex", "flat", null],
             "default": "complex",
-            "description": "抠图模式。不填按 complex 处理；complex 使用语义分割识别前景，flat 用于纯色背景抠图。确定背景为纯色时优先使用 flat。"
+            "description": "抠图模式。省略或 null 按 complex 处理；complex 使用语义分割识别前景，flat 用于纯色背景抠图。确定背景为纯色时优先使用 flat。"
           },
           "screenColor": {
             "type": ["string", "null"],
             "pattern": "^(auto|#[0-9A-Fa-f]{6})$",
-            "description": "仅 flat 模式使用。可传 auto、#RRGGBB 或省略；auto 和省略由服务自动检测背景色。complex 搭配此字段返回 400。"
+            "description": "仅 flat 模式使用。可传 auto、#RRGGBB 或省略；null 等同省略。auto 和省略由服务自动检测背景色。模式省略或 complex 时提供非 null 颜色返回 400；空字符串或非法颜色返回 400。"
           },
           "projectId": {
             "type": ["string", "null"],
@@ -3260,6 +3260,14 @@
             "description": "画布生成占位完成指令。提供时优先按生成完成链路写入结果，targetLayerId 不参与原位替换。"
           }
         },
+        "if": {
+          "required": ["screenColor"],
+          "properties": { "screenColor": { "type": "string" } }
+        },
+        "then": {
+          "required": ["backgroundMode"],
+          "properties": { "backgroundMode": { "const": "flat" } }
+        },
         "additionalProperties": false
       },
       "EditorImageGenerationResponse": {

docs/project-memory/plans/【实施计划】抠图模式联调验收-2026-09-16.md

@@ -0,0 +1,14 @@
+# 抠图模式联调验收实施计划
+
+依据：[里程碑](./【里程碑】抠图模式联调验收-2026-09-16.md)。
+
+1. 主站修复 worker 对 auto/省略的门禁、空值契约和旧指纹；补接口、队列与 worker 定向测试。
+2. 客户端独立核对 schema、参数校验、幂等意图、Skill 与契约说明。
+3. 串行请求真实 BgFilter，凭据仅在进程内读取，不输出或落库。
+4. 运行 cargo test 的 background_removal、bgfilter、OpenAPI 定向过滤，客户端定向测试；运行 doc-index、encoding、diff 检查。
+5. 尝试 npm run dev:api-server 与 healthz smoke；记录真实登录/全链路未验证项。
+6. 收敛证据到主规范，删除临时计划。
+
+检查点：先通过契约测试，再开展运行时核验；不因环境缺失修改生产配置。回滚仅限本次局部补丁。
+
+当前收口：主站及客户端修复和定向检查已执行，真实 BgFilter 四组成功及自动检测失败分支已验证；本地 API 启动被现有数据库连接配置阻塞。仅完整登录/队列/资源回写运行时证据尚待补齐，测试凭据和临时日志不得提交。

docs/project-memory/plans/【里程碑】抠图模式联调验收-2026-09-16.md

@@ -0,0 +1,14 @@
+# 抠图模式联调验收
+
+Version: 1
+Status: 自动化与真实上游验收已执行；完整主站链路待本地数据库恢复
+Date: 2026-09-16
+Parent Spec: ../../technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md
+
+交付：证明客户端、External v1、队列和 BgFilter 的模式/颜色契约一致；修正范围内缺漏。
+不做：401 专题、部署、主站前端变化、生成角色与图集自动选色行为变化、数据库 schema 修改。
+
+验收：旧请求 complex；flat 三种颜色输入贯通；非法组合入队前 400；幂等包含新意图并保留旧请求指纹；真实服务返回可解码透明 PNG；实际证据与未验证环境分开记录。
+依赖：既有方案及前五步代码。
+
+剩余门禁：当前本地 SpacetimeDB 连接拒绝，导致 api-server 启动恢复未就绪。环境恢复后，用 npm run dev:api-server 验证 healthz，再以真实登录客户端提交三种 flat 请求及旧 complex 请求，确认队列完成和资源回写。不得用直连 BgFilter 测试替代此门禁；完成后将结论回写主规范并删除本计划和实施计划。

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

@@ -2,6 +2,13 @@
 
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+## 2026-09-16 抠图模式与背景色契约
+
+- External v1 抠图和 AGC `agc_remove_background` 支持 `complex`（语义分割识别前景）与 `flat`（纯色背景抠图）；明确纯色背景优先 flat，模式缺省仍为 complex，主站前端保持现有行为。
+- flat 的颜色允许 `auto`、`#RRGGBB` 或省略，自动识别完全由 BgFilter 负责。主站只校验、透传，不调用视觉模型选色；complex 携带颜色、非法值和空字符串在入队前拒绝。
+- 来源、名称、模式与颜色共同区分客户端请求意图；旧参数调用及旧 External 请求的幂等指纹须保持稳定。
+- 权威合同：[AGC 抠图模式与背景色透传](../../technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)。
+
 ## 2026-09-16 策划 Agent 工具执行退出项目级写锁并自动接续中断批次
 
 - 背景：策划 Agent 每个 `read_file` / `write_file` / `patch_file` 工具都在执行前竞争全局项目写锁，但同一会话已由 `.agent/design-agent/active.lock` 串行化，工具目标又限定在 `design_artifacts`；项目锁既不覆盖「工具 + 会话 checkpoint」事务，还把进程中断时的 `executing=true` 不确定窗口扩大到等锁与工具执行全程。真机项目出现 `pendingBatch.executing=true`、`function_call` 无配对 output、UI 只显示工作中且无错误的状态。

docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md

@@ -151,7 +151,7 @@ Authorization: Bearer <internal-token>
 - 当前部署只有一个配置内私有 OSS bucket，因此请求只传 `sourceObjectKey`，子 worker 从自身 OSS 配置取 bucket 并生成短期签名 URL。
 - 如果未来确实支持多个 bucket，新增字段也必须由服务端 allowlist 校验；不能接受调用方提供任意下载 URL。
 - `backgroundMode` 只允许 `flat / complex`；`segModel` 继续沿用当前 `birefnet / anime-seg` allowlist；complex 固定使用当前参数组合。
-- `screenColor` 只对 flat 必填；complex 不得误接 flat 参数，两种模式的熔断状态必须隔离。
+- `screenColor` 在 flat 下可省略，也可传 `auto` 或 `#RRGGBB`；省略或 `auto` 由 BgFilter 自动识别。complex 不得携带背景色，两种模式的熔断状态必须隔离。生成角色、图集等既有链路继续传已确定的背景色。
 - `maxQueueWaitMs` 与 `callBudgetMs` 都是相对预算，不是跨机器绝对时间。前者从 admission 起约束排队阶段（worker 还会用 §5.2 的动态估计对其取 min）；后者从取得 provider permit 起计时，覆盖签名、两次 attempt、结果校验和响应构造。`callBudgetMs` 是父侧按 `N / est` 公式算出的“配置指纹”，仅作核对：worker 始终以自己按同一公式派生的值执行，不一致时不拒绝请求，而是记录 warn 日志并递增漂移指标。发布调优 N / est 时新旧进程共存的瞬态漂移因此不会误伤在途任务；持久性漂移的硬拦截由部署脚本的共享 env 对齐校验承担。
 - JSON body 设置很小的固定上限；源图字节不进入该 JSON。
 

docs/technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md

@@ -38,8 +38,11 @@ POST /api/external/v1/editor/images/background-removals
 1. 不传新增字段：按 `complex` 执行。
 2. `complex` 不允许传 `screenColor`，返回 400。
 3. `flat` 可以传具体 `#RRGGBB`、`auto`，也可以省略颜色。
-4. 非法模式、非法颜色、空字符串颜色返回 400。
+4. 模式和颜色严格按原值校验；非法值、空字符串、前后空格和大写 `AUTO` / `FLAT` 返回 400。十六进制颜色的字母允许大小写。
 5. 主站只做格式和组合校验；`auto` 不在主站解析，直接转发给 BgFilter。
+6. HTTP 请求中的 `null` 视同省略；模式省略时提供非 null 颜色同样违反 complex 约束。客户端 MCP 可选参数应省略，不传 null。
+
+格式或组合错误在入队前返回 400；BgFilter 自动检测失败发生在异步执行阶段，任务通过既有失败状态收口，不把已接受的 202 改成同步 400，不启动其他抠图方式兜底。
 
 主站前端继续不传新增字段，因此用户行为不变。
 
@@ -58,7 +61,7 @@ POST /api/external/v1/editor/images/background-removals
 
 客户端保留旧参数调用；新字段不填时不改变旧调用语义。客户端不读取图片、不自动选色、不把 `auto` 改写为具体颜色，使用原有 Bearer 认证、幂等键和队列返回模型。
 
-需要同步 `direct_tool_bridge.rs`、工具 manifest/schema、`agc-client-projection` 的 Skill/契约说明及客户端测试。
+工具 schema、桥接参数校验和随包 `agc-client-projection` Skill/契约说明必须保持一致。模式与颜色属于请求意图，必须参与客户端幂等指纹；同一图片与名称的不同模式不能复用同一次请求。缺省 complex 且没有颜色时保留既有指纹。主站在默认值归一化之前计算 External 请求指纹，缺失的新字段不序列化，避免旧请求重放发生冲突。
 
 ## 实施任务
 
@@ -88,8 +91,12 @@ POST /api/external/v1/editor/images/background-removals
 
 ## 验收证据
 
-- OpenAPI、Rust DTO、队列任务和客户端请求字段一致；
-- 旧客户端不传新增字段仍成功入队并使用 `complex`；
-- `auto` 未被主站改写，BgFilter 收到 `auto` 或未收到 `screen_color`；
-- 主站前端继续使用 `complex`；
-- 定向测试、`npm run check:doc-index`、`npm run check:encoding` 和 `git diff --check` 通过。
+2026-09-16 实测：
+
+- 主站 `cargo test -p api-server background_removal`：36 项通过，覆盖非法请求入队前拒绝、缺省 complex、队列参数保留、旧请求指纹、父侧内部 RPC 和 provider multipart。
+- `cargo test -p api-server bgfilter`：52 项通过，包括 flat 的 auto/省略/具体颜色以及既有生成链路。
+- `exported_openapi_json_contains_external_editor_routes_and_security` 契约测试通过。
+- 客户端 `agent::direct_tools_mcp::tests` 18 项、`agent::skill_pack::tests` 4 项与抠图幂等指纹测试通过；Skill manifest 内容指纹已同步。主站与客户端 rustfmt、文档索引、编码及 diff 检查通过。
+- 真实 BgFilter（版本 `f1a0833`）：使用进程内凭据串行请求 `flat + auto`、flat 省略颜色、`flat + #CFEFFF`、complex；四组均返回 200、512×512 RGBA PNG，alpha 范围均为 0–255。
+- 无纯色背景的随机噪声图片使用 flat + auto 返回 400，确认自动识别失败要求调用方提供颜色。测试没有修改服务器代码或配置。
+- 本地 `npm run dev:api-server` 已尝试，但当前配置指向的 SpacetimeDB 不可连接，服务停留在启动恢复重试，`/healthz` 未通过；已结束本次启动。完整登录客户端 → 主站持久化队列 → 结果回写的运行时验收尚未完成，不能用真实 BgFilter 的独立测试代替。没有部署本次主站或客户端代码。

server-rs/crates/api-server/src/bgfilter_worker.rs

@@ -849,13 +849,13 @@ fn validate_internal_request(
     }
     match request.background_mode {
         BgfilterBackgroundMode::Flat => {
-            let screen_color = request.screen_color.as_deref().ok_or_else(|| {
-                WorkerFailure::new("invalid_request", "flat 请求缺少 screenColor", false)
-            })?;
-            if !valid_screen_color(screen_color) {
+            if let Some(screen_color) = request.screen_color.as_deref()
+                && screen_color != "auto"
+                && !valid_screen_color(screen_color)
+            {
                 return Err(WorkerFailure::new(
                     "invalid_request",
-                    "screenColor 必须是 #RRGGBB",
+                    "screenColor 必须是 auto 或 #RRGGBB",
                     false,
                 ));
             }
@@ -2811,7 +2811,13 @@ mod tests {
             call_budget_ms: 321_000,
             audit_context: None,
         };
-        assert!(validate_internal_request(&request, &admission).is_err());
+        assert!(validate_internal_request(&request, &admission).is_ok());
+        request.screen_color = Some("auto".to_string());
+        assert!(validate_internal_request(&request, &admission).is_ok());
+        for invalid in ["", "AUTO", "#12", "#GGGGGG"] {
+            request.screen_color = Some(invalid.to_string());
+            assert!(validate_internal_request(&request, &admission).is_err());
+        }
         request.screen_color = Some("#CFEFFF".to_string());
         assert!(validate_internal_request(&request, &admission).is_ok());
         // callBudget 只是父侧配置指纹：与 worker 公式值不一致不得拒绝（发布重启窗口
@@ -2854,6 +2860,85 @@ mod tests {
         assert!(validate_internal_request(&request, &admission).is_err());
     }
 
+    #[tokio::test]
+    async fn background_removal_provider_multipart_preserves_mode_and_color() {
+        for (mode, color) in [
+            (BgfilterBackgroundMode::Complex, None),
+            (BgfilterBackgroundMode::Flat, None),
+            (BgfilterBackgroundMode::Flat, Some("auto")),
+            (BgfilterBackgroundMode::Flat, Some("#Ab12EF")),
+        ] {
+            let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+            let address = listener.local_addr().unwrap();
+            let (sender, mut receiver) = tokio::sync::mpsc::channel(1);
+            let router = Router::new().route(
+                "/remove-background",
+                post(move |headers: HeaderMap, body: axum::body::Bytes| {
+                    let sender = sender.clone();
+                    async move {
+                        sender.send((headers, body)).await.unwrap();
+                        (
+                            [(axum::http::header::CONTENT_TYPE, "image/png")],
+                            encoded_png(2, 3),
+                        )
+                    }
+                }),
+            );
+            let server = tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });
+            let state = AppState::new(AppConfig {
+                editor_bgfilter_base_url: format!("http://{address}"),
+                editor_bgfilter_token: Some("provider-test-token".to_string()),
+                ..AppConfig::default()
+            })
+            .unwrap();
+            let request = BgfilterInternalRequest {
+                request_id: "multipart-test".to_string(),
+                source_object_key: "editor-upload/source.png".to_string(),
+                background_mode: mode,
+                screen_color: color.map(str::to_string),
+                seg_model: "birefnet".to_string(),
+                cross_check: false,
+                max_queue_wait_ms: 1000,
+                call_budget_ms: 321000,
+                audit_context: None,
+            };
+            let result = request_provider_once(
+                &state,
+                &request,
+                "https://example.invalid/source.png",
+                ProviderAttemptBudget {
+                    timeout: Duration::from_secs(5),
+                    budget_limited: false,
+                },
+                1,
+                Instant::now() + Duration::from_secs(5),
+                &BgfilterTaskTracker::new(),
+            )
+            .await;
+            server.abort();
+            let result = result.unwrap();
+            assert_eq!((result.width, result.height), (2, 3));
+            let (headers, body) = receiver.recv().await.unwrap();
+            assert_eq!(
+                headers[BGFILTER_PROVIDER_TOKEN_HEADER],
+                "provider-test-token"
+            );
+            let body = String::from_utf8(body.to_vec()).unwrap();
+            assert!(body.contains(&format!(
+                "name=\"background_mode\"\r\n\r\n{}\r\n",
+                mode.as_str()
+            )));
+            assert!(body.contains("name=\"image_url\""));
+            assert!(!body.contains("name=\"file\""));
+            match color {
+                Some(color) => {
+                    assert!(body.contains(&format!("name=\"screen_color\"\r\n\r\n{color}\r\n")))
+                }
+                None => assert!(!body.contains("name=\"screen_color\"")),
+            }
+        }
+    }
+
     #[test]
     fn provider_timeout_distinguishes_full_attempt_from_budget_truncation() {
         let now = Instant::now();

server-rs/crates/api-server/src/editor_generation_queue.rs

@@ -1019,6 +1019,52 @@ mod tests {
         );
     }
 
+    #[test]
+    fn background_removal_identity_preserves_old_dto_and_distinguishes_options() {
+        let legacy = json!({
+            "sourceImageSrc": "resource-source", "projectId": null,
+            "targetLayerId": null, "assetKind": null, "generationInputs": null,
+            "assetFolderId": null, "assetLabel": null, "sourceResourceId": null,
+            "taskId": null, "canvasCompletion": null,
+        });
+        let old = external_api_editor_generation_request_identity(
+            "user-1",
+            EDITOR_BACKGROUND_REMOVAL_JOB_KIND,
+            &legacy,
+            "stable-key",
+        )
+        .unwrap();
+        let restored: crate::editor_project::EditorBackgroundRemovalRequest =
+            serde_json::from_value(legacy.clone()).unwrap();
+        let current = external_api_editor_generation_request_identity(
+            "user-1",
+            EDITOR_BACKGROUND_REMOVAL_JOB_KIND,
+            &restored,
+            "stable-key",
+        )
+        .unwrap();
+        assert_eq!(old.request_fingerprint, current.request_fingerprint);
+        assert_eq!(old.job_id, current.job_id);
+        let mut fingerprints = std::collections::HashSet::new();
+        fingerprints.insert(current.request_fingerprint);
+        for color in [None, Some("auto"), Some("#CFEFFF"), Some("#112233")] {
+            let mut body = legacy.clone();
+            body["backgroundMode"] = json!("flat");
+            if let Some(color) = color {
+                body["screenColor"] = json!(color);
+            }
+            let changed = external_api_editor_generation_request_identity(
+                "user-1",
+                EDITOR_BACKGROUND_REMOVAL_JOB_KIND,
+                &body,
+                "stable-key",
+            )
+            .unwrap();
+            assert_eq!(old.job_id, changed.job_id);
+            assert!(fingerprints.insert(changed.request_fingerprint));
+        }
+    }
+
     #[test]
     fn external_api_dedupe_key_preserves_legacy_hash_bytes() {
         let dedupe_key = build_editor_generation_dedupe_key(

server-rs/crates/api-server/src/editor_project.rs

@@ -452,7 +452,9 @@ pub struct EditorImageEditRequest {
 #[serde(rename_all = "camelCase")]
 pub struct EditorBackgroundRemovalRequest {
     pub(crate) source_image_src: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub(crate) background_mode: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub(crate) screen_color: Option<String>,
     pub(crate) project_id: Option<String>,
     pub(crate) target_layer_id: Option<String>,
@@ -6292,7 +6294,6 @@ pub(crate) async fn enqueue_editor_background_removal_for_owner(
     mut payload: EditorBackgroundRemovalRequest,
     external_idempotency_key: Option<&str>,
 ) -> Result<ExternalGenerationJobRecord, AppError> {
-    normalize_editor_background_removal_options(&mut payload)?;
     let external_request_identity = external_idempotency_key
         .map(|idempotency_key| {
             external_api_editor_generation_request_identity(
@@ -6303,6 +6304,7 @@ pub(crate) async fn enqueue_editor_background_removal_for_owner(
             )
         })
         .transpose()?;
+    normalize_editor_background_removal_options(&mut payload)?;
     ensure_editor_reference_image_source_is_stable(
         payload.source_image_src.as_str(),
         "editor-background-removal",
@@ -6409,34 +6411,28 @@ fn normalize_editor_background_removal_options(
 ) -> Result<(), AppError> {
     let mode = payload
         .background_mode
-        .take()
-        .map(|value| value.trim().to_ascii_lowercase())
-        .filter(|value| !value.is_empty())
+        .clone()
         .unwrap_or_else(|| "complex".to_string());
     if mode != "complex" && mode != "flat" {
         return Err(
             AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                 "provider": "editor-background-removal",
                 "field": "backgroundMode",
-                "message": "backgroundMode must be complex or flat",
+                "message": "backgroundMode 必须是 complex 或 flat",
             })),
         );
     }
-    let color = payload
-        .screen_color
-        .take()
-        .map(|value| value.trim().to_string())
-        .filter(|value| !value.is_empty());
+    let color = payload.screen_color.as_deref();
     if mode == "complex" && color.is_some() {
         return Err(
             AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                 "provider": "editor-background-removal",
                 "field": "screenColor",
-                "message": "screenColor is only supported when backgroundMode is flat",
+                "message": "只有 flat 模式可以提供 screenColor",
             })),
         );
     }
-    if let Some(color) = color.as_deref()
+    if let Some(color) = color
         && color != "auto"
         && !(color.len() == 7
             && color.starts_with('#')
@@ -6448,12 +6444,11 @@ fn normalize_editor_background_removal_options(
             AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                 "provider": "editor-background-removal",
                 "field": "screenColor",
-                "message": "screenColor must be auto or #RRGGBB",
+                "message": "screenColor 必须是 auto 或 #RRGGBB",
             })),
         );
     }
     payload.background_mode = Some(mode);
-    payload.screen_color = color;
     Ok(())
 }
 
@@ -6706,6 +6701,7 @@ pub(crate) async fn remove_editor_image_background_for_owner(
     caller: EditorGenerationCaller,
     mut payload: EditorBackgroundRemovalRequest,
 ) -> Result<Json<Value>, AppError> {
+    normalize_editor_background_removal_options(&mut payload)?;
     payload.generation_inputs =
         sanitize_editor_client_generation_inputs(payload.generation_inputs.take());
     let started_at = Instant::now();
@@ -8010,7 +8006,7 @@ async fn request_editor_background_removal_image_with_bgfilter_worker(
     screen_color: Option<&str>,
     audit: &crate::external_api_audit::ExternalApiAuditContext,
 ) -> Result<EditorBackgroundRemovalImage, AppError> {
-    // complex 没有 flat fallback，排队上限只预留 2s 传输窗；worker 重启窗口内的
+    // 独立抠图两种模式都不进入生成链路的 fallback，排队上限只预留 2s 传输窗；worker 重启窗口内的
     // 连接失败由 client 内部按预算有界重试，避免 max_attempts=1 的队列任务终态失败。
     let mode = match background_mode {
         "flat" => crate::bgfilter_worker::BgfilterBackgroundMode::Flat,
@@ -13717,6 +13713,110 @@ pub(crate) fn current_utc_micros() -> i64 {
 
 #[cfg(test)]
 mod tests {
+    #[test]
+    fn background_removal_options_preserve_queue_parameters_and_legacy_identity() {
+        for (fields, mode, color) in [
+            (json!({}), "complex", None),
+            (json!({"backgroundMode": "complex"}), "complex", None),
+            (json!({"backgroundMode": "flat"}), "flat", None),
+            (
+                json!({"backgroundMode": "flat", "screenColor": "auto"}),
+                "flat",
+                Some("auto"),
+            ),
+            (
+                json!({"backgroundMode": "flat", "screenColor": "#Ab12EF"}),
+                "flat",
+                Some("#Ab12EF"),
+            ),
+        ] {
+            let mut input = json!({"sourceImageSrc": "resource-source"});
+            input
+                .as_object_mut()
+                .unwrap()
+                .extend(fields.as_object().unwrap().clone());
+            let mut payload: EditorBackgroundRemovalRequest =
+                serde_json::from_value(input).unwrap();
+            if payload.background_mode.is_none() {
+                let raw = serde_json::to_value(&payload).unwrap();
+                assert!(raw.get("backgroundMode").is_none());
+                assert!(raw.get("screenColor").is_none());
+            }
+            normalize_editor_background_removal_options(&mut payload).unwrap();
+            let restored: EditorBackgroundRemovalRequest =
+                serde_json::from_str(&serde_json::to_string(&payload).unwrap()).unwrap();
+            assert_eq!(restored.background_mode.as_deref(), Some(mode));
+            assert_eq!(restored.screen_color.as_deref(), color);
+        }
+    }
+
+    #[test]
+    fn background_removal_options_reject_invalid_values_and_color_without_flat() {
+        for fields in [
+            json!({"backgroundMode": ""}),
+            json!({"backgroundMode": "FLAT"}),
+            json!({"backgroundMode": " flat "}),
+            json!({"backgroundMode": "other"}),
+            json!({"screenColor": "auto"}),
+            json!({"backgroundMode": "complex", "screenColor": "auto"}),
+            json!({"backgroundMode": "complex", "screenColor": ""}),
+            json!({"backgroundMode": "flat", "screenColor": ""}),
+            json!({"backgroundMode": "flat", "screenColor": "AUTO"}),
+            json!({"backgroundMode": "flat", "screenColor": " auto "}),
+            json!({"backgroundMode": "flat", "screenColor": "#GGGGGG"}),
+            json!({"backgroundMode": "flat", "screenColor": "CFEFFF"}),
+        ] {
+            let mut input = json!({"sourceImageSrc": "resource-source"});
+            input
+                .as_object_mut()
+                .unwrap()
+                .extend(fields.as_object().unwrap().clone());
+            let mut payload: EditorBackgroundRemovalRequest =
+                serde_json::from_value(input).unwrap();
+            assert_eq!(
+                normalize_editor_background_removal_options(&mut payload)
+                    .unwrap_err()
+                    .status_code(),
+                StatusCode::BAD_REQUEST,
+                "{fields}"
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn background_removal_flat_options_reach_internal_worker_unchanged() {
+        for color in [None, Some("auto"), Some("#Ab12EF")] {
+            let response_png = encode_test_png(3, 2);
+            let (base_url, receiver, server) = spawn_bgfilter_worker_png_mock(response_png.clone());
+            let state = AppState::new(AppConfig {
+                bgfilter_worker_base_url: base_url,
+                bgfilter_internal_token: Some("flat-test-token".to_string()),
+                ..AppConfig::default()
+            })
+            .unwrap();
+            let audit = crate::external_api_audit::ExternalApiAuditContext {
+                user_id: None,
+                profile_id: None,
+                request_id: None,
+                external_call_deadline: None,
+            };
+            let output = request_editor_background_removal_image_with_bgfilter_worker(
+                &state,
+                "generated-character-drafts/editor/source.png",
+                "flat",
+                color,
+                &audit,
+            )
+            .await
+            .unwrap();
+            let request = receiver.recv_timeout(Duration::from_secs(1)).unwrap();
+            server.join().unwrap();
+            let payload = parse_mock_http_json_body(&request);
+            assert_eq!(payload["backgroundMode"], json!("flat"));
+            assert_eq!(payload["screenColor"], json!(color));
+            assert_eq!(output.image.bytes, response_png);
+        }
+    }
     use super::*;
     use crate::{
         config::AppConfig,

server-rs/crates/api-server/src/external_editor_api.rs

@@ -1868,7 +1868,7 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn external_background_removal_rejects_undocumented_fields_before_queueing() {
+    async fn external_background_removal_rejects_invalid_parameters_before_queueing() {
         let state = AppState::new(crate::config::AppConfig::default())
             .expect("external background removal test state should build");
         state.fail_test_editor_generation_enqueue();
@@ -1890,6 +1890,26 @@ mod tests {
                 json!({"taskId": "caller-controlled-task"}),
             ),
             ("unknown field", json!({"unexpected": true})),
+            ("invalid mode", json!({"backgroundMode": "unknown"})),
+            ("empty mode", json!({"backgroundMode": ""})),
+            ("uppercase mode", json!({"backgroundMode": "FLAT"})),
+            ("color without flat", json!({"screenColor": "auto"})),
+            (
+                "complex with color",
+                json!({"backgroundMode": "complex", "screenColor": "#123456"}),
+            ),
+            (
+                "empty color",
+                json!({"backgroundMode": "flat", "screenColor": ""}),
+            ),
+            (
+                "invalid color",
+                json!({"backgroundMode": "flat", "screenColor": "red"}),
+            ),
+            (
+                "non-string color",
+                json!({"backgroundMode": "flat", "screenColor": 123}),
+            ),
         ] {
             let mut request_body = json!({"sourceImageSrc": "editor-upload/source.png"});
             request_body
@@ -2848,6 +2868,25 @@ mod tests {
             ["EditorBackgroundRemovalRequest"]["properties"]["targetLayerId"]["description"]
             .as_str()
             .expect("background removal targetLayerId should document placement semantics");
+        let background_properties =
+            &parsed["components"]["schemas"]["EditorBackgroundRemovalRequest"]["properties"];
+        assert_eq!(
+            background_properties["backgroundMode"]["enum"],
+            json!(["complex", "flat", null])
+        );
+        assert_eq!(
+            background_properties["backgroundMode"]["default"],
+            "complex"
+        );
+        assert_eq!(
+            background_properties["screenColor"]["pattern"],
+            "^(auto|#[0-9A-Fa-f]{6})$"
+        );
+        assert_eq!(
+            parsed["components"]["schemas"]["EditorBackgroundRemovalRequest"]["then"]["properties"]
+                ["backgroundMode"]["const"],
+            "flat"
+        );
         assert!(background_target_description.contains("projectId"));
         assert!(background_target_description.contains("canvasCompletion"));
         assert!(background_target_description.contains("assetObjectId"));