diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_audit.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_audit.rs index 6f8557a32..b3d60bc64 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_audit.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_audit.rs @@ -550,6 +550,7 @@ fn extract_mcp_arguments(root: &Path, tool: &str, arguments: &Value) -> Value { "agc_generate_image" => { copy_string(object, "kind", &mut out); copy_string(object, "sliceMode", &mut out); + copy_string(object, "screenColor", &mut out); copy_string(object, "aspectRatio", &mut out); copy_string(object, "imageSize", &mut out); copy_string(object, "assetName", &mut out); diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs index 706015112..91bc4ad1c 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs @@ -3390,6 +3390,7 @@ async fn generate_direct_taonier_art_asset_at( slice_mode: (asset_kind == "art-spritesheet").then(|| "connected-components".to_string()), grid_x: None, grid_y: None, + screen_color: None, }; let runtime_context = direct_taonier_art_generation_runtime_context(root, output_path, asset_kind)?; diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs index 9984ff4d6..164bd1543 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs @@ -2230,6 +2230,42 @@ fn validate_generate_image_slice_declaration( Ok(()) } +/// 抠图纯色背景只服务 character 与 art-spritesheet 链路;格式校验收口为 +/// `auto` 或 `#RRGGBB`(服务端另有支持色板,客户端不复制),`auto`/空串归一为 +/// None(服务端自动决策),hex 统一大写后透传。其它 kind 携带该字段直接拒绝, +/// 避免服务端静默忽略造成“已生效”的误解。 +fn normalize_generate_image_screen_color( + arguments: &Value, + kind: &str, +) -> Result, String> { + let Some(value) = arguments.get("screenColor") else { + return Ok(None); + }; + if value.is_null() { + return Ok(None); + } + if !matches!(kind, "character" | "art-spritesheet") { + return Err(format!( + "工具参数 screenColor 仅对 kind=character 和 kind=art-spritesheet 生效,当前 kind={kind}" + )); + } + let raw = value + .as_str() + .ok_or_else(|| "工具参数 screenColor 必须是 auto 或 #RRGGBB".to_string())? + .trim(); + if raw.is_empty() || raw.eq_ignore_ascii_case("auto") { + return Ok(None); + } + let normalized = raw.to_ascii_uppercase(); + let valid = normalized.len() == 7 + && normalized.starts_with('#') + && normalized[1..].chars().all(|c| c.is_ascii_hexdigit()); + if !valid { + return Err("工具参数 screenColor 必须是 auto 或 #RRGGBB".to_string()); + } + Ok(Some(normalized)) +} + async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value) -> Value { let result = async { bridge_reject_unknown_fields( @@ -2244,6 +2280,8 @@ async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value) "sliceMode", "gridX", "gridY", + "sliceCount", + "screenColor", ], )?; enforce_project_permission_policy(&state.root, "canvas.asset_generate")?; @@ -2323,13 +2361,25 @@ async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value) { return Err("工具参数 gridX/gridY 必须在 1 到 32 之间".to_string()); } + let slice_count = arguments + .get("sliceCount") + .filter(|value| !value.is_null()) + .map(|value| { + value + .as_u64() + .filter(|count| (1..=256).contains(count)) + .map(|count| count as usize) + .ok_or_else(|| "工具参数 sliceCount 必须是 1 到 256 的整数".to_string()) + }) + .transpose()?; validate_generate_image_slice_declaration( kind.as_str(), slice_mode.as_deref(), grid_x, grid_y, - None, + slice_count, )?; + let screen_color = normalize_generate_image_screen_color(arguments, kind.as_str())?; let options = PlatformArtAssetGenerationOptions { output_path, aspect_ratio, @@ -2337,10 +2387,11 @@ async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value) asset_kind: kind.clone(), asset_label: asset_name.clone(), replace_existing: false, - slice_count: None, + slice_count, slice_mode, grid_x, grid_y, + screen_color, }; let _generation_guard = state.image_generation_gate.lock().await; let generated = with_direct_editor_api_credentials( @@ -2867,6 +2918,61 @@ mod tests { assert!(validate_generate_image_slice_declaration("image", None, None, None, None).is_ok()); } + #[test] + fn generate_image_screen_color_is_normalized_and_kind_gated() { + // 省略与显式 null 等价,且不触发 kind 门禁。 + assert_eq!( + normalize_generate_image_screen_color(&json!({}), "image").expect("omitted"), + None + ); + assert_eq!( + normalize_generate_image_screen_color(&json!({"screenColor": null}), "image") + .expect("null"), + None + ); + // auto 家族归一为 None(服务端自动决策),大小写与空白不敏感。 + for raw in ["auto", "AUTO", " auto ", ""] { + assert_eq!( + normalize_generate_image_screen_color(&json!({"screenColor": raw}), "character") + .expect("auto variants"), + None, + "{raw}" + ); + } + // hex 统一大写透传;色板白名单由服务端权威校验,客户端只守格式。 + assert_eq!( + normalize_generate_image_screen_color(&json!({"screenColor": "#cfefff"}), "character") + .expect("lowercase hex"), + Some("#CFEFFF".to_string()) + ); + assert_eq!( + normalize_generate_image_screen_color( + &json!({"screenColor": " #A0BBA0 "}), + "art-spritesheet" + ) + .expect("padded hex"), + Some("#A0BBA0".to_string()) + ); + // 非 auto/非 hex、非字符串一律拒绝。 + for bad in [json!("green"), json!("#GGGGGG"), json!("#FFF"), json!(12)] { + assert!( + normalize_generate_image_screen_color(&json!({"screenColor": bad}), "character") + .is_err(), + "{bad}" + ); + } + // 其它 kind 携带该字段直接拒绝,即使取值合法。 + let gated = + normalize_generate_image_screen_color(&json!({"screenColor": "#CFEFFF"}), "image") + .expect_err("screenColor must stay scoped to character/art-spritesheet"); + assert!(gated.contains("kind=character"), "{gated}"); + assert!(normalize_generate_image_screen_color( + &json!({"screenColor": "auto"}), + "ui-prototype" + ) + .is_err()); + } + #[test] fn remove_background_identity_preserves_default_and_distinguishes_options() { let legacy = "asset-1\0透明图"; diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs index e9d9415df..718a30ddd 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs @@ -233,7 +233,7 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab }), json!({ "name": "agc_generate_image", - "description": "按原网站图片画布能力生成一张新图片:普通插画、角色立绘、统一视觉规范图、游戏 UI 设计图或透明游戏素材图集都可使用。仅在用户明确要求生成新图时调用;游戏美术包是另一个专用工具,不是本工具的限制。客户端负责登录态授权、计费、幂等账本、下载校验、manifest/revision 登记和本地预览,不需要用户提供 API Key、Token、URL 或 .env。", + "description": "按原网站图片画布能力生成一张新图片:普通插画、角色立绘、统一视觉规范图、游戏 UI 设计图或透明游戏素材图集都可使用。仅在用户明确要求生成新图时调用。", "inputSchema": { "type": "object", "properties": { @@ -286,6 +286,16 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab "minimum": 1, "maximum": 32, "description": "grid 模式纵向网格数量,只能与 sliceMode=grid 同时提供" + }, + "sliceCount": { + "type": "integer", + "minimum": 1, + "maximum": 256, + "description": "只与 kind=art-spritesheet 且 sliceMode=connected-components 同时提供,用于约束目标素材张数;省略时按图像内容自动识别" + }, + "screenColor": { + "type": "string", + "description": "抠图纯色背景,仅 kind=character(角色形象)和 kind=art-spritesheet(图标素材)生效,其它 kind 携带会被拒绝。生成时把主体置于该纯色背景上,回图后据此抠除背景。取值只能是 auto 或下列色板 hex 之一,传值只填 hex 本身、不要附带色名:#CFEFFF(浅雾蓝)、#B0C2E0(浅钢蓝)、#FFD6C2(暖浅桃色)、#E6D8FF(淡薰衣草紫)、#F4D8E8(浅粉灰)、#7FB3FF(中度天蓝)、#FFF2A8(浅柠黄)、#CFFFE1(淡薄荷绿)、#D8DEE8(浅中性灰)、#D8D2E8(淡灰紫)、#A8F7F0(高对比浅青)、#A0BBA0(灰竹绿);auto 时由服务端自动选色。手动指定时不能与角色或素材本体的颜色接近" } }, "required": ["prompt"], @@ -1131,6 +1141,8 @@ async fn call_agc_generate_image(arguments: &Value) -> Value { "sliceMode", "gridX", "gridY", + "sliceCount", + "screenColor", ], ) { return mcp_tool_result(error, Vec::new(), true); @@ -1159,6 +1171,7 @@ async fn call_agc_generate_image(arguments: &Value) -> Value { ("assetName", DIRECT_TOOLS_MCP_MAX_RESOURCE_NAME_CHARS), ("outputPath", 512), ("sliceMode", 32), + ("screenColor", 16), ] { if arguments.get(field).is_some() { if let Err(error) = bounded_tool_string(arguments, field, max_chars) { @@ -2391,11 +2404,27 @@ mod tests { assert_eq!(image_tool["inputSchema"]["required"], json!(["prompt"])); assert!(image_tool["description"] .as_str() - .is_some_and(|description| description.contains("不是本工具的限制"))); + .is_some_and(|description| description.contains("仅在用户明确要求生成新图时调用"))); assert_eq!( image_tool["inputSchema"]["properties"]["sliceMode"]["enum"], json!(["connected-components", "grid"]) ); + assert_eq!( + image_tool["inputSchema"]["properties"]["sliceCount"]["minimum"], + json!(1) + ); + assert_eq!( + image_tool["inputSchema"]["properties"]["sliceCount"]["maximum"], + json!(256) + ); + assert!( + image_tool["inputSchema"]["properties"]["screenColor"]["description"] + .as_str() + .is_some_and(|description| description.contains("抠图纯色背景") + && description.contains("kind=character") + && description.contains("不要附带色名")), + "screenColor description must carry the matting-background semantics" + ); assert!( image_tool["inputSchema"]["properties"]["sliceMode"] .get("default") diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs index a3b5be2a0..39857aff7 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs @@ -420,6 +420,9 @@ pub(crate) struct PlatformArtAssetGenerationOptions { pub(crate) slice_mode: Option, pub(crate) grid_x: Option, pub(crate) grid_y: Option, + /// 抠图纯色背景(auto/省略已归一为 None;Some 时是规范化后的大写 #RRGGBB)。 + /// 仅 character 与 art-spritesheet 链路透传给服务端。 + pub(crate) screen_color: Option, } impl Default for PlatformArtAssetGenerationOptions { @@ -435,6 +438,7 @@ impl Default for PlatformArtAssetGenerationOptions { slice_mode: None, grid_x: None, grid_y: None, + screen_color: None, } } } @@ -2206,6 +2210,8 @@ pub(crate) async fn generate_platform_art_asset_with_required_slices_at( /// /// 升级前遗留账本仍由旧材料函数定位;新请求把显式切分模式纳入身份,避免同一图集 /// 请求在网格与连通域之间误复用。`slice_count` 继续保持历史兼容语义,不进身份。 +/// `screen_color` 是付费语义不同的输入,进入身份;None 时跳过序列化,未使用该字段的 +/// 请求身份与升级前逐字节一致。 #[derive(Serialize)] #[serde(rename_all = "camelCase")] struct StandalonePlatformArtGenerationFingerprintMaterial<'a> { @@ -2220,6 +2226,8 @@ struct StandalonePlatformArtGenerationFingerprintMaterial<'a> { slice_mode: Option<&'a str>, grid_x: Option, grid_y: Option, + #[serde(skip_serializing_if = "Option::is_none")] + screen_color: Option<&'a str>, } /// 把输出路径收口成稳定的旧槽材料:空路径与未指定路径都落到 `(automatic-output)`, @@ -2259,6 +2267,7 @@ fn standalone_platform_art_generation_runtime_context( slice_mode: options.slice_mode.as_deref(), grid_x: options.grid_x, grid_y: options.grid_y, + screen_color: options.screen_color.as_deref(), }) .map_err(|error| format!("序列化 standalone 图片生成动作身份失败:{error}"))?; let action_fingerprint = format!("{:x}", Sha256::digest(&identity_bytes)); @@ -2833,7 +2842,7 @@ pub(in crate::agent) async fn request_platform_art_asset_with_runtime_options_at "sliceMode": options.slice_mode, "gridX": options.grid_x, "gridY": options.grid_y, - "screenColor": "auto", + "screenColor": options.screen_color.as_deref().unwrap_or("auto"), "aspectRatio": options.aspect_ratio, "imageSize": options.image_size, "assetLabel": options.asset_label, @@ -2881,6 +2890,14 @@ pub(in crate::agent) async fn request_platform_art_asset_with_runtime_options_at if options.asset_kind == "image" { object.remove("kind"); } + if options.asset_kind == "character" { + if let Some(screen_color) = options.screen_color.as_deref() { + object.insert( + "screenColor".to_string(), + serde_json::Value::String(screen_color.to_string()), + ); + } + } } request_body } else { @@ -8429,6 +8446,7 @@ mod canvas_generation_tests { slice_mode: None, grid_x: None, grid_y: None, + screen_color: None, }; let ordinary = standalone_platform_art_generation_runtime_context("完整生成提示词", &options, false) @@ -8495,6 +8513,9 @@ mod canvas_generation_tests { let mut changed = options.clone(); changed.replace_existing = false; changed_options.push(changed); + let mut changed = options.clone(); + changed.screen_color = Some("#CFEFFF".to_string()); + changed_options.push(changed); for changed in changed_options { let context = standalone_platform_art_generation_runtime_context( "完整生成提示词", @@ -10473,6 +10494,7 @@ mod canvas_generation_tests { slice_mode: None, grid_x: None, grid_y: None, + screen_color: None, }; let prompt = "生成同一套整包美术"; let generation_prompt = build_platform_art_asset_prompt(prompt, &[], &options); @@ -11377,6 +11399,7 @@ mod canvas_generation_tests { slice_mode: None, grid_x: None, grid_y: None, + screen_color: None, }; let prompt = "保持同一个生成提示词"; let generation_prompt = build_platform_art_asset_prompt(prompt, &[], &options); @@ -11841,6 +11864,7 @@ mod canvas_generation_tests { slice_mode: None, grid_x: None, grid_y: None, + screen_color: None, }; let prompt = "恢复已受理视觉规范图"; let generation_prompt = build_platform_art_asset_prompt(prompt, &[], &options); @@ -12450,6 +12474,7 @@ mod canvas_generation_tests { slice_mode: Some("connected-components".to_string()), grid_x: None, grid_y: None, + screen_color: None, } } diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs index 5ba2980c2..5c1e7ffda 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs @@ -577,6 +577,7 @@ pub(in crate::agent) async fn observe_agent_runtime_platform_art_asset_generatio slice_mode: (!slice_mode.trim().is_empty()).then_some(slice_mode.clone()), grid_x, grid_y, + screen_color: None, }; if let Some(pending) = pending_action { match recover_persisted_visual_generation_options( @@ -628,6 +629,7 @@ pub(in crate::agent) async fn observe_agent_runtime_platform_art_asset_generatio .or_else(|| (!slice_mode.trim().is_empty()).then_some(slice_mode)), grid_x, grid_y, + screen_color: requested_options.screen_color, } }; options.replace_existing = replace_existing; diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs index a2e86d06e..426efa9b8 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs @@ -4914,6 +4914,7 @@ pub(crate) fn prepare_local_project_asset_generation( .then(|| "connected-components".to_string()), grid_x: None, grid_y: None, + screen_color: None, }, }) } diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs index 0552c041e..145aabd36 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs @@ -1094,6 +1094,7 @@ async fn canonical_art_spec_and_ui_requests_use_the_shared_reference_chain() { slice_mode: None, grid_x: None, grid_y: None, + screen_color: None, }, ) .await; @@ -5574,6 +5575,7 @@ fn ui_prototype_generation_uses_dedicated_prompt_and_art_spec() { slice_mode: None, grid_x: None, grid_y: None, + screen_color: None, }; let prompt = build_platform_art_asset_prompt( "原创网格贪吃蛇:分数与状态 HUD、四类不同分值食物、开始、方向键/WASD、触控方向键、失败与重开",