diff --git a/CONTEXT.md b/CONTEXT.md index fc2799e85..c22344ea0 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -48,6 +48,23 @@ _Avoid_: 无来源的静态素材、只显示在 UI 但不落工程资源记录 一组同类素材的统一批量生成方式，采用批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成的通用流水线。 _Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成任一玩法专属 DTO +**UI 设计文档**: +AGC 本地项目里 `kind=ui-design-doc`、`mediaType=application/json` 的界面编辑载体，保存设计图集合、UI 树、组件绑定和 State revision；一份文档可同时承载多张设计图与各自的结构树，不强制收敛成一棵树。 +_Avoid_: 把 UI 设计图当成设计文档、给设计文档再套一层「页面」概念 + +**设计图**: +UI 设计文档里的一张参考界面图，以它在 manifest 中的资产 ID 作为文档内身份，附带像素尺寸与像素比；文档内的每棵树都必须引用文档里已存在的设计图。 +_Avoid_: 用文件名当设计图身份、设计图与设计文档同一概念 + +**UI 工作流步骤**: +对一份 UI 设计文档执行的一次受控处理阶段，当前只有「结构识别」与「素材切分」两步；步骤产物只有在写入文档并保存后才算完成。 +_Avoid_: 把单次工具调用当成步骤、把中间产物当成步骤完成 + +**工作流检查点日志**: +一份 UI 设计文档旁按行追加的恢复用日志，每完成一个工作流步骤追加一行；某步是否有对应行即代表该步是否完成，恢复时从第一个缺失的行继续。 +_Avoid_: 每步一个 sidecar 状态机、把切分专用的 SeparationState 泛化成通用检查点 + + ## Language ### Puzzle Clear diff --git a/apps/ai-game-creator-shell/scripts/check-config.mjs b/apps/ai-game-creator-shell/scripts/check-config.mjs index 6b2c74b13..37271c331 100644 --- a/apps/ai-game-creator-shell/scripts/check-config.mjs +++ b/apps/ai-game-creator-shell/scripts/check-config.mjs @@ -157,11 +157,8 @@ const allowedUncalledTauriCommands = [ 'set_active_game_creator_agent_session', 'start_game_creator_agent_goal', 'start_game_creator_supervisor_runtime_task', - // TODO: Remove the retired binding command after the legacy runtime path is removed. - 'bind_components', 'chat_with_game_creator_agent', 'check_ui_editor_font_glyph_coverage', - 'create_ui_design_resource', // 图片类生成的同步变体：GUI 已改为 `start_local_project_asset_generation` + 项目内任务账本 // （提交即返回、后台生成）。这条命令**没有生产调用方**，只有 Rust 集成测试 // （`src/tests/project.rs`）与 `commands.rs` 单测在调；待后续批次删除，或改为转调 diff --git a/apps/ai-game-creator-shell/src-tauri/capabilities/main.json b/apps/ai-game-creator-shell/src-tauri/capabilities/main.json index 753d89477..91ebf61db 100644 --- a/apps/ai-game-creator-shell/src-tauri/capabilities/main.json +++ b/apps/ai-game-creator-shell/src-tauri/capabilities/main.json @@ -1,11 +1,12 @@ { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "main", - "description": "AI 游戏创作主窗口允许读取系统剪贴板图片，用于粘贴素材附件；允许弹出原生打开/保存对话框用于素材上传与导出。", + "description": "AI 游戏创作主窗口允许读写系统剪贴板，用于粘贴素材附件和复制生成文件路径；允许弹出原生打开/保存对话框用于素材上传与导出。", "windows": ["client"], "permissions": [ "clipboard-manager:allow-read-image", "clipboard-manager:allow-read-text", + "clipboard-manager:allow-write-text", "core:image:allow-rgba", "core:image:allow-size", "core:resources:allow-close", diff --git a/apps/ai-game-creator-shell/src-tauri/prompts/runtime/manifest.json b/apps/ai-game-creator-shell/src-tauri/prompts/runtime/manifest.json index 88d921118..982112915 100644 --- a/apps/ai-game-creator-shell/src-tauri/prompts/runtime/manifest.json +++ b/apps/ai-game-creator-shell/src-tauri/prompts/runtime/manifest.json @@ -7,6 +7,7 @@ "execution": "texts/execution.json", "media": "texts/media.json", "nativeTools": "texts/native-tools.json", + "uiDesignDoc": "texts/ui-design-doc.json", "recovery": "texts/recovery.json", "interaction": "texts/interaction.json", "goalContext": "texts/goal-context.json", diff --git a/apps/ai-game-creator-shell/src-tauri/prompts/runtime/texts/native-tools.json b/apps/ai-game-creator-shell/src-tauri/prompts/runtime/texts/native-tools.json index 1e70efd57..7942f4de3 100644 --- a/apps/ai-game-creator-shell/src-tauri/prompts/runtime/texts/native-tools.json +++ b/apps/ai-game-creator-shell/src-tauri/prompts/runtime/texts/native-tools.json @@ -37,7 +37,6 @@ "preview.validate.description": "用真实浏览器验证桌面和移动预览并保存证据。", "image.inspect.description": "让视觉模型检查一至两张项目内图片。", "canvas.asset_generate.description": "通过已配置的 External Editor API 按项目需求生成图片或图集并登记到画布、素材库和项目 assets；可使用已登记资源作为参考。assetKind=icon-spritesheet 的 prompt 去除首尾空白后须为 1 到 200 个 Unicode 字符，保留内部换行并作为单条 iconDescriptions 原样提交，超限拒绝，不截断、不拆条，客户端不追加生图指令。assetKind=icon-spritesheet 时 sliceMode 必填且没有默认值：需求要求等分网格、固定槽位或指定行列数时用 grid 并提供来自需求本身的 gridX/gridY；自由排布、数量不定或只要求一张图集时用 connected-components，可用 sliceCount 约束素材张数；其它 assetKind 不得携带 sliceMode/gridX/gridY。", - "ui.workflow.run.description": "先用 discover 从受控 game/ui-pages.json 或页面声明标记自动发现全部功能页面，再把已登记 ui-design 与每个页面的设计图桥接成独立 UI JSON State；可同时载入已登记图片、图标和项目字体，执行 Provider 结构识别、多树合并与分批组件绑定、回读阶段，并且只有所有页面已绑定且已应用到 game/ 后才允许 finalize。项目根目录由 Runtime 注入，模型不得传入宿主路径。", "cocos.editor.execute.description": "在当前项目对应的已打开 Cocos Creator 编辑器中执行一段有界代码；仅提交 code，客户端负责绑定项目与编辑器进程。", "unity.editor.execute.description": "在当前 Unity 项目已打开的编辑器中执行 C#。仅提交 code；结果待核对时禁止自动重发。", "godot.editor.execute.description": "在当前 Godot 项目已打开的编辑器中执行支持 return/await 的 GDScript 函数体。仅提交 code；结果待核对时禁止自动重发。", diff --git a/apps/ai-game-creator-shell/src-tauri/prompts/runtime/texts/ui-design-doc.json b/apps/ai-game-creator-shell/src-tauri/prompts/runtime/texts/ui-design-doc.json new file mode 100644 index 000000000..910a916fa --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/prompts/runtime/texts/ui-design-doc.json @@ -0,0 +1,8 @@ +{ + "from_images.description": "用一至四张设计图新建一份 UI 设计文档：输入给已登记资源的 assetId，或给项目内相对路径由本工具顺带登记；随后按 ui/UI 设计 N.json 取号创建文档、把设计图写进文档并登记为 ui-design-doc 资源，返回新文档的 assetId 与 relativePath。每次调用都新建文档，不复用既有文档。", + "from_images.parameters.images": "一至四张设计图。每张给 assets 里已登记图片资源的 assetId，或给项目内相对路径（相对路径会先登记成图片资源）；文档内的设计图身份就是该图片资源的 assetId。", + "run_workflow.description": "对一份 UI 设计文档在 Rust 内依次执行结构识别与自动切分素材：把切分素材回填到 Image 组件的 target_graphic、清掉已处理节点的组件状态、给达到返工上限的问题节点写 NeedReview，最后写回文档并推进 revision。每完成一步追加一行检查点，崩溃后从第一个缺失的步骤继续；不做页面发现，也不做多树合并与独立组件绑定。文档在轮次中途被改动时本轮作废并报错，必须重新调用本工具开新一轮。", + "run_workflow.parameters.designDocAssetId": "目标 UI 设计文档在 assets 里的 assetId；文档内必须已有设计图。", + "into_js.description": "把一份 UI 设计文档的当前 revision 渲染成 ui/generated--.js，返回相对路径与导出树。只读文档内容，不修改文档、不推进 revision。", + "into_js.parameters.designDocAssetId": "目标 UI 设计文档在 assets 里的 assetId。" +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_audit.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_audit.rs index 9c397e912..34d2fda40 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_audit.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_audit.rs @@ -677,160 +677,14 @@ fn agent_runtime_action_receipt_safe_detail_with_owner( "revisionAdvanceCount": value.get("revisionAdvanceCount").and_then(serde_json::Value::as_u64).unwrap_or(0), })).ok(); } - if observation.tool == "ui.workflow.run" { - let value = serde_json::from_str::( - observation.detail.as_deref().unwrap_or_default(), - ) - .ok()?; - let operation = value.get("operation")?.as_str()?; - let project_id = value.get("projectId")?.as_str()?; - let source_asset_id = value.get("sourceAssetId")?.as_str()?; - let completed = value.get("completed")?.as_bool()?; - let revision_advance_count = value.get("revisionAdvanceCount")?.as_u64()?; - if project_id.is_empty() - || source_asset_id.is_empty() - || !matches!( - operation, - "discover" | "prepare" | "recognize" | "status" | "finalize" - ) - || project_id.chars().any(char::is_control) - || source_asset_id.chars().any(char::is_control) - { - return None; - } - if operation == "discover" { - let discovered_pages = value.get("discoveredPages")?.as_array()?; - if discovered_pages.is_empty() || discovered_pages.len() > 32 { - return None; - } - let safe_pages = discovered_pages - .iter() - .map(|page| { - let page_id = page.get("pageId")?.as_str()?; - let title = page.get("title")?.as_str()?; - let description = page.get("description")?.as_str()?; - let application_path = page.get("applicationPath")?.as_str()?; - let required_design_asset_path = - page.get("requiredDesignAssetPath")?.as_str()?; - let discovered_from = page.get("discoveredFrom")?.as_str()?; - if page_id.is_empty() - || title.is_empty() - || description.chars().any(char::is_control) - || application_path.is_empty() - || !application_path.starts_with("game/") - || required_design_asset_path.is_empty() - || discovered_from.is_empty() - { - return None; - } - Some(serde_json::json!({ - "pageId": agent_runtime_action_receipt_safe_text(root, page_id, 80, None)?, - "title": agent_runtime_action_receipt_safe_text(root, title, 120, None)?, - "description": agent_runtime_action_receipt_safe_text(root, description, 400, None)?, - "applicationPath": agent_runtime_action_receipt_safe_text(root, application_path, 240, None)?, - "requiredDesignAssetPath": agent_runtime_action_receipt_safe_text(root, required_design_asset_path, 240, None)?, - "discoveredFrom": agent_runtime_action_receipt_safe_text(root, discovered_from, 240, None)?, - })) - }) - .collect::>>()?; - return serde_json::to_string(&serde_json::json!({ - "operation": operation, - "projectId": agent_runtime_action_receipt_safe_text(root, project_id, 160, None)?, - "sourceAssetId": agent_runtime_action_receipt_safe_text(root, source_asset_id, 160, None)?, - "completed": completed, - "revisionAdvanceCount": revision_advance_count, - "pages": [], - "discoveredPages": safe_pages, - "finalStageRoute": null, - })) - .ok(); - } - let pages = value.get("pages")?.as_array()?; - if pages.is_empty() || pages.len() > 32 { - return None; - } - let mut safe_pages = Vec::with_capacity(pages.len()); - for page in pages { - let page_id = page.get("pageId")?.as_str()?; - let title = page.get("title")?.as_str()?; - let design_asset_id = page.get("designAssetId")?.as_str()?; - let ui_asset_id = page.get("uiAssetId")?.as_str()?; - let revision = page.get("uiStateRevision")?.as_u64()?; - let stage = page.get("stage")?.as_str()?; - let marker = page.get("applicationMarker")?.as_str()?; - let blockers = page.get("blockers")?.as_array()?; - if page_id.is_empty() - || title.is_empty() - || design_asset_id.is_empty() - || ui_asset_id.is_empty() - || revision > 9_007_199_254_740_991 - || marker.is_empty() - || !matches!( - stage, - "reference-ready" - | "structure-ready" - | "binding-ready" - | "application-ready" - | "completed" - ) - || blockers.len() > 32 - { - return None; - } - let safe_blockers = blockers - .iter() - .map(|blocker| { - let blocker = blocker.as_str()?; - agent_runtime_action_receipt_safe_text(root, blocker, 240, None) - .map(serde_json::Value::String) - }) - .collect::>>()?; - safe_pages.push(serde_json::json!({ - "pageId": agent_runtime_action_receipt_safe_text(root, page_id, 80, None)?, - "title": agent_runtime_action_receipt_safe_text(root, title, 120, None)?, - "designAssetId": agent_runtime_action_receipt_safe_text(root, design_asset_id, 160, None)?, - "uiAssetId": agent_runtime_action_receipt_safe_text(root, ui_asset_id, 160, None)?, - "uiStateRevision": revision, - "stage": stage, - "blockers": safe_blockers, - "applicationMarker": agent_runtime_action_receipt_safe_text(root, marker, 240, None)?, - })); - } - let final_stage_route = if completed { - let route = value.get("finalStageRoute")?; - let resource_id = route.get("resourceId")?.as_str()?; - let initial_step = route.get("initialStep")?.as_str()?; - let render_mode = route.get("renderMode")?.as_str()?; - if resource_id.is_empty() - || initial_step != "asset-separation" - || render_mode != "final-preview" - { - return None; - } - Some(serde_json::json!({ - "resourceId": agent_runtime_action_receipt_safe_text(root, resource_id, 160, None)?, - "initialStep": initial_step, - "renderMode": render_mode, - })) - } else { - if !value - .get("finalStageRoute") - .is_some_and(serde_json::Value::is_null) - { - return None; - } - None - }; - return serde_json::to_string(&serde_json::json!({ - "operation": operation, - "projectId": agent_runtime_action_receipt_safe_text(root, project_id, 160, None)?, - "sourceAssetId": agent_runtime_action_receipt_safe_text(root, source_asset_id, 160, None)?, - "completed": completed, - "revisionAdvanceCount": revision_advance_count, - "pages": safe_pages, - "finalStageRoute": final_stage_route, - })) - .ok(); + if matches!( + observation.tool.as_str(), + "ui-design-doc.from-images" | "ui-design-doc.run-workflow" + ) { + return agent_runtime_ui_design_doc_safe_detail(root, observation.detail.as_deref()); + } + if observation.tool == "ui-design-doc.into-js" { + return agent_runtime_ui_design_code_safe_detail(root, observation.detail.as_deref()); } if observation.tool != "project.patchset" { return None; @@ -1175,6 +1029,184 @@ pub(in crate::agent) fn agent_runtime_action_receipt_safe_text( Some(sanitized) } +/// UI 设计文档回执里身份类字段的长度上限：素材 id / 文档 id / 生成文件名都远小于这个值。 +const AGENT_RUNTIME_UI_DESIGN_SAFE_ID_MAX_CHARS: usize = 96; +/// 文档相对路径的长度上限；同时要求必须落在 `ui/` 下，避免把项目别处的路径带进回执。 +const AGENT_RUNTIME_UI_DESIGN_SAFE_RELATIVE_PATH_MAX_CHARS: usize = 160; +/// 单条回填说明的长度上限与总量上限；超出总量的部分不逐条外传，改用总数表达。 +const AGENT_RUNTIME_UI_DESIGN_SAFE_ERROR_MAX_CHARS: usize = 96; +const AGENT_RUNTIME_UI_DESIGN_SAFE_ERROR_CHAR_BUDGET: usize = 240; +/// 一份文档最多四张设计图，逐张身份也按同一上限放行。 +const AGENT_RUNTIME_UI_DESIGN_SAFE_IMAGE_ID_LIMIT: usize = 4; + +/// UI 设计文档链路（新建文档 / 跑工作流）的回执明细：只放身份、相对路径、计数与回填说明。 +/// 计数与身份必须完全合格；体积较大的清单（设计图身份、回填说明）在回执长度上限内能放多少放多少， +/// 放不下的部分用总数补齐，绝不把原始明细整体外传。 +fn agent_runtime_ui_design_doc_safe_detail(root: &Path, detail: Option<&str>) -> Option { + let detail = serde_json::from_str::(detail.unwrap_or_default()).ok()?; + let mut safe = serde_json::Map::new(); + safe.insert( + "assetId".to_string(), + agent_runtime_action_receipt_identity_text( + root, + detail.get("assetId")?.as_str()?, + AGENT_RUNTIME_UI_DESIGN_SAFE_ID_MAX_CHARS, + "assetId", + ) + .ok()? + .into(), + ); + safe.insert( + "relativePath".to_string(), + agent_runtime_ui_design_safe_relative_path(root, detail.get("relativePath")?.as_str()?)? + .into(), + ); + for key in [ + "revision", + "revisionAdvanceCount", + "recognizedTreeCount", + "boundNodeCount", + "problematicNodeCount", + ] { + if let Some(value) = detail.get(key) { + safe.insert(key.to_string(), value.as_u64()?.into()); + } + } + if let Some(value) = detail.get("recoveredFromCheckpoint") { + safe.insert( + "recoveredFromCheckpoint".to_string(), + value.as_bool()?.into(), + ); + } + if !agent_runtime_action_receipt_detail_fits(&safe) { + return None; + } + + if let Some(image_ids) = detail.get("imageIds") { + let image_ids = image_ids.as_array()?; + if image_ids.is_empty() || image_ids.len() > AGENT_RUNTIME_UI_DESIGN_SAFE_IMAGE_ID_LIMIT { + return None; + } + let image_ids = image_ids + .iter() + .map(|value| { + agent_runtime_action_receipt_identity_text( + root, + value.as_str()?, + AGENT_RUNTIME_UI_DESIGN_SAFE_ID_MAX_CHARS, + "imageIds", + ) + .ok() + }) + .collect::>>()?; + agent_runtime_action_receipt_insert_while_fits( + &mut safe, + "imageIds", + serde_json::json!(image_ids), + ); + } + if let Some(errors) = detail.get("backfillErrors") { + let errors = errors.as_array()?; + let mut safe_errors = Vec::new(); + for value in errors { + // 回填说明是自由文本：绝对路径按既有口径脱敏成占位符，控制字符或超长则整条明细失败关闭。 + let raw = value.as_str()?.trim(); + let error = agent_runtime_action_receipt_safe_text( + root, + raw, + AGENT_RUNTIME_UI_DESIGN_SAFE_ERROR_MAX_CHARS, + None, + )?; + if sanitize_agent_runtime_text(&error, AGENT_RUNTIME_UI_DESIGN_SAFE_ERROR_MAX_CHARS) + != error + { + return None; + } + let mut candidate = safe_errors.clone(); + candidate.push(serde_json::Value::String(error)); + let mut probe = safe.clone(); + probe.insert("backfillErrors".to_string(), serde_json::json!(candidate)); + probe.insert( + "backfillErrorCount".to_string(), + serde_json::json!(errors.len()), + ); + if !agent_runtime_action_receipt_detail_fits(&probe) { + break; + } + safe_errors = candidate; + } + if !safe_errors.is_empty() + && serde_json::to_string(&serde_json::json!(safe_errors)) + .map(|text| text.chars().count()) + .unwrap_or(0) + <= AGENT_RUNTIME_UI_DESIGN_SAFE_ERROR_CHAR_BUDGET + { + safe.insert("backfillErrors".to_string(), serde_json::json!(safe_errors)); + } + safe.insert( + "backfillErrorCount".to_string(), + serde_json::json!(errors.len()), + ); + } + serde_json::to_string(&serde_json::Value::Object(safe)).ok() +} + +/// 代码生成回执：相对路径与计数；导出名清单只用来核对数量，不逐项外传。 +fn agent_runtime_ui_design_code_safe_detail(root: &Path, detail: Option<&str>) -> Option { + let detail = serde_json::from_str::(detail.unwrap_or_default()).ok()?; + let relative_path = + agent_runtime_ui_design_safe_relative_path(root, detail.get("relativePath")?.as_str()?)?; + let tree_count = detail.get("treeCount")?.as_u64()?; + let node_count = detail.get("nodeCount")?.as_u64()?; + if usize::try_from(tree_count).ok()? != detail.get("treeExports")?.as_array()?.len() { + return None; + } + let safe = serde_json::to_string(&serde_json::json!({ + "relativePath": relative_path, + "treeCount": tree_count, + "nodeCount": node_count, + })) + .ok()?; + (sanitize_agent_runtime_text(&safe, AGENT_RUNTIME_ACTION_RECEIPT_SAFE_DETAIL_MAX_CHARS) == safe) + .then_some(safe) +} + +/// `ui/` 下的项目相对路径：绝对路径、反斜杠、上跳与超长一律拒绝。 +fn agent_runtime_ui_design_safe_relative_path(root: &Path, value: &str) -> Option { + let path = normalize_relative_path(value).ok()?; + if !path.starts_with("ui/") { + return None; + } + agent_runtime_action_receipt_identity_text( + root, + &path, + AGENT_RUNTIME_UI_DESIGN_SAFE_RELATIVE_PATH_MAX_CHARS, + "relativePath", + ) + .ok() +} + +fn agent_runtime_action_receipt_detail_fits( + detail: &serde_json::Map, +) -> bool { + serde_json::to_string(&serde_json::Value::Object(detail.clone())).is_ok_and(|text| { + sanitize_agent_runtime_text(&text, AGENT_RUNTIME_ACTION_RECEIPT_SAFE_DETAIL_MAX_CHARS) + == text + }) +} + +fn agent_runtime_action_receipt_insert_while_fits( + detail: &mut serde_json::Map, + key: &str, + value: serde_json::Value, +) { + let mut candidate = detail.clone(); + candidate.insert(key.to_string(), value); + if agent_runtime_action_receipt_detail_fits(&candidate) { + *detail = candidate; + } +} + pub(in crate::agent) fn agent_runtime_public_action_input_summary( root: &Path, tool: &str, @@ -1210,12 +1242,14 @@ pub(in crate::agent) fn agent_runtime_public_action_input_summary( | "preview.validate" | "image.inspect" | "canvas.asset_generate" - | "ui.workflow.run" | "agent.message" | "agent.delegate" | "agent.schedule_ready" | "agent.action_history" | "agent.run_status" + | "ui-design-doc.from-images" + | "ui-design-doc.run-workflow" + | "ui-design-doc.into-js" ); if public_shape_only { return agent_runtime_action_receipt_safe_text(root, input_summary, 320, None); @@ -1749,8 +1783,82 @@ pub(crate) fn agent_runtime_tool_action_input_summary( text(&["agentId", "agent_id", "targetAgentId", "target_agent_id"]), text(&["delegationId", "delegation_id"]) ), + // UI 设计文档三兄弟：入参只有设计图引用或目标文档 id，直接给出可读摘要， + // 不再退化成"只报哈希"——否则模型看不到自己这次到底传了什么。 + "ui-design-doc.from-images" => ui_design_doc_images_input_summary(input), + "ui-design-doc.run-workflow" | "ui-design-doc.into-js" => format!( + "designDocAssetId={}", + text(&["designDocAssetId", "design_doc_asset_id", "assetId", "asset_id"]) + ), _ => String::new(), }; let summary = redact_agent_runtime_project_paths(root, &summary, 320); (!summary.trim().is_empty()).then_some(summary) } + +/// 新建文档工具的设计图入参摘要：逐张给出身份（素材 id 或相对路径），绝对路径按既有口径降级成拒绝标记。 +fn ui_design_doc_images_input_summary(input: &serde_json::Value) -> String { + let Some(images) = input.get("images").and_then(serde_json::Value::as_array) else { + return String::new(); + }; + let described = images + .iter() + .map(|image| { + if let Some(asset_id) = image.get("assetId").and_then(serde_json::Value::as_str) { + return format!("assetId={asset_id}"); + } + match image.get("path").and_then(serde_json::Value::as_str) { + Some(path) if Path::new(path).is_absolute() => { + "[absolute path rejected]".to_string() + } + Some(path) => format!("path={path}"), + None => "input".to_string(), + } + }) + .collect::>() + .join(", "); + format!("images={} · {described}", images.len()) +} + +#[cfg(test)] +mod ui_design_doc_public_input_summary_tests { + use super::*; + + #[test] + fn ui_design_doc_input_summaries_are_readable_not_hashed() { + let root = Path::new("/nonexistent-ui-design-doc-input-summary-project"); + for (tool, summary) in [ + ( + "ui-design-doc.from-images", + "images=2 · assetId=image-1, path=assets/two.png", + ), + ( + "ui-design-doc.run-workflow", + "designDocAssetId=generated-ui-design-1", + ), + ( + "ui-design-doc.into-js", + "designDocAssetId=generated-ui-design-1", + ), + ] { + let public = agent_runtime_public_action_input_summary(root, tool, Some(summary)) + .expect("input summary"); + assert_eq!(public, summary, "{tool} 的入参不能被压成摘要哈希"); + } + } + + #[test] + fn from_images_input_summary_lists_each_image_reference() { + let input = serde_json::json!({ + "images": [ + {"assetId": "image-1"}, + {"path": "assets/two.png"}, + {"path": "/tmp/host-only.png"}, + ] + }); + assert_eq!( + ui_design_doc_images_input_summary(&input), + "images=3 · assetId=image-1, path=assets/two.png, [absolute path rejected]" + ); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_execution.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_execution.rs index 72a0cc3fd..653595170 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_execution.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_execution.rs @@ -153,6 +153,16 @@ pub(crate) async fn execute_game_creator_agent_runtime_tool_action_with_pending_ observe_agent_runtime_account_asset_library(root, &action.input).await } "canvas.asset_import" => observe_agent_runtime_asset_import(root, &action.input).await, + "ui-design-doc.from-images" => { + observe_agent_runtime_ui_design_doc_from_images(root, &action.input).await + } + "ui-design-doc.run-workflow" => { + observe_agent_runtime_ui_design_doc_run_workflow(root, agent_id, run_id, &action.input) + .await + } + "ui-design-doc.into-js" => { + observe_agent_runtime_ui_design_doc_into_js(root, &action.input).await + } "project.index" => observe_agent_runtime_project_snapshot_with_lock( root, agent_id, @@ -436,9 +446,6 @@ pub(crate) async fn execute_game_creator_agent_runtime_tool_action_with_pending_ ) .await } - "ui.workflow.run" => { - observe_agent_runtime_ui_workflow(root, agent_id, run_id, task, &action.input).await - } "blackboard.write" => { observe_agent_runtime_blackboard_write(root, agent_id, run_id, &action.input) } diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/parallel_ledger.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/parallel_ledger.rs index a1a2684be..b4f364493 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/parallel_ledger.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/parallel_ledger.rs @@ -103,7 +103,9 @@ pub(in crate::agent) fn game_creator_agent_runtime_tool_command_id( "preview.validate" => Some("preview.validate"), "image.inspect" => Some("image.inspect"), "canvas.asset_generate" => Some("canvas.asset_generate"), - "ui.workflow.run" => Some("asset.register"), + "ui-design-doc.from-images" => Some("asset.register"), + "ui-design-doc.run-workflow" => Some("asset.register"), + "ui-design-doc.into-js" => Some("file.write"), "blackboard.write" => Some("memory.write"), "agent.message" => Some("conversation.write"), "agent.delegate" => Some("agent.delegate"), diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs index 4d4f72abe..75ef70891 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs @@ -649,15 +649,16 @@ pub(crate) fn is_agent_runtime_project_mutation_observation( if observation.tool == "project.patchset" { return agent_runtime_patchset_advanced_project_revision(observation); } - if observation.tool == "ui.workflow.run" { - return agent_runtime_ui_workflow_observation_advances_project_revision(observation); + if agent_runtime_ui_design_doc_tool(&observation.tool) { + // 三个 UI 设计文档工具都在返回时改项目：`from-images` 登记设计图与文档，`run-workflow` 登记 + // 切图并保存文档，`into-js` 重写 `ui/generated-*.js`。成功返回即算改过项目；失败路径只有明细 + // 报出真实推进量时才算，避免漏掉"调用失败但素材已经登记进去"。 + return observation.status == "ok" + || agent_runtime_observation_detail_revision_advance_count(observation) + .is_some_and(|count| count > 0); } if observation.tool == "canvas.asset_import" { - return observation - .detail - .as_deref() - .and_then(|detail| serde_json::from_str::(detail).ok()) - .and_then(|value| value.get("revisionAdvanceCount")?.as_u64()) + return agent_runtime_observation_detail_revision_advance_count(observation) .is_some_and(|count| count > 0); } observation.status == "ok" @@ -669,10 +670,28 @@ pub(crate) fn is_agent_runtime_project_mutation_observation( | "project.patchset" | "project.restore" | "canvas.asset_generate" - | "ui.workflow.run" ) } +/// UI 设计文档链路当前的三个 Agent 工具（`ui.workflow.run` 退役后由它们接管）。 +fn agent_runtime_ui_design_doc_tool(tool: &str) -> bool { + matches!( + tool, + "ui-design-doc.from-images" | "ui-design-doc.run-workflow" | "ui-design-doc.into-js" + ) +} + +/// 明细里的真实项目 revision 推进量：登记类工具（`canvas.asset_import` 与 UI 设计文档工具）会写这个字段。 +fn agent_runtime_observation_detail_revision_advance_count( + observation: &AgentRuntimeToolObservation, +) -> Option { + observation + .detail + .as_deref() + .and_then(|detail| serde_json::from_str::(detail).ok()) + .and_then(|value| value.get("revisionAdvanceCount")?.as_u64()) +} + pub(in crate::agent) fn agent_runtime_command_start_advanced_project_revision( observation: &AgentRuntimeToolObservation, ) -> bool { @@ -735,16 +754,17 @@ pub(crate) fn agent_runtime_observation_advances_project_revision( if agent_runtime_patchset_advanced_project_revision(observation) { return true; } + if agent_runtime_ui_design_doc_tool(&observation.tool) { + // `into-js` 只重写派生产物，不推进 revision；另外两个（登记设计图/文档、登记切图并写回）会推进。 + return matches!( + observation.tool.as_str(), + "ui-design-doc.from-images" | "ui-design-doc.run-workflow" + ) && (observation.status == "ok" + || agent_runtime_observation_detail_revision_advance_count(observation) + .is_some_and(|count| count > 0)); + } if observation.status != "ok" { - return observation - .detail - .as_deref() - .and_then(|detail| serde_json::from_str::(detail).ok()) - .and_then(|value| { - value - .get("revisionAdvanceCount") - .and_then(serde_json::Value::as_u64) - }) + return agent_runtime_observation_detail_revision_advance_count(observation) .is_some_and(|count| count > 0); } match observation.tool.as_str() { @@ -755,63 +775,19 @@ pub(crate) fn agent_runtime_observation_advances_project_revision( | "project.restore" | "blackboard.write" | "canvas.asset_generate" => true, - "canvas.asset_import" => observation - .detail - .as_deref() - .and_then(|detail| serde_json::from_str::(detail).ok()) - .and_then(|value| value.get("revisionAdvanceCount")?.as_u64()) - .is_some_and(|count| count > 0), - "ui.workflow.run" => { - agent_runtime_ui_workflow_observation_advances_project_revision(observation) + "canvas.asset_import" => { + agent_runtime_observation_detail_revision_advance_count(observation) + .is_some_and(|count| count > 0) } "memory.write" => true, _ => false, } } -fn agent_runtime_ui_workflow_observation_advances_project_revision( - observation: &AgentRuntimeToolObservation, -) -> bool { - observation.tool == "ui.workflow.run" - && observation.status == "ok" - && observation - .detail - .as_deref() - .and_then(|detail| serde_json::from_str::(detail).ok()) - .and_then(|value| { - value - .get("revisionAdvanceCount") - .and_then(serde_json::Value::as_u64) - .map(|count| count > 0) - }) - .unwrap_or(false) -} - fn agent_runtime_observation_project_revision_advance_count( observation: &AgentRuntimeToolObservation, ) -> u64 { - if observation.tool == "ui.workflow.run" && observation.status == "ok" { - return observation - .detail - .as_deref() - .and_then(|detail| serde_json::from_str::(detail).ok()) - .and_then(|value| { - value - .get("revisionAdvanceCount") - .and_then(serde_json::Value::as_u64) - }) - .unwrap_or(0); - } - if let Some(count) = observation - .detail - .as_deref() - .and_then(|detail| serde_json::from_str::(detail).ok()) - .and_then(|value| { - value - .get("revisionAdvanceCount") - .and_then(serde_json::Value::as_u64) - }) - { + if let Some(count) = agent_runtime_observation_detail_revision_advance_count(observation) { return count; } if agent_runtime_observation_advances_project_revision(observation) { @@ -821,19 +797,6 @@ fn agent_runtime_observation_project_revision_advance_count( } } -fn is_agent_runtime_ui_workflow_completed_observation( - observation: &AgentRuntimeToolObservation, -) -> bool { - observation.tool == "ui.workflow.run" - && observation.status == "ok" - && observation - .detail - .as_deref() - .and_then(|detail| serde_json::from_str::(detail).ok()) - .and_then(|value| value.get("completed").and_then(serde_json::Value::as_bool)) - .unwrap_or(false) -} - pub(in crate::agent) fn is_agent_runtime_static_smoke_observation( observation: &AgentRuntimeToolObservation, ) -> bool { @@ -855,7 +818,6 @@ pub(in crate::agent) fn is_agent_runtime_project_verification_observation( || (observation.tool == "command.exec" && agent_runtime_command_exec_is_verification_eligible(observation)) || (observation.tool == "canvas.asset_generate" && observation.status == "ok") - || is_agent_runtime_ui_workflow_completed_observation(observation) || is_agent_runtime_static_smoke_observation(observation) } @@ -868,8 +830,6 @@ pub(in crate::agent) fn agent_runtime_project_verification_label( "command.exec" } else if observation.tool == "canvas.asset_generate" { "canvas.asset_generate" - } else if observation.tool == "ui.workflow.run" { - "ui.workflow.run" } else { "project.verify" } @@ -1830,3 +1790,107 @@ mod static_delegate_barrier_detail_gate_tests { } } } + +#[cfg(test)] +mod ui_design_doc_project_mutation_gate_tests { + use super::*; + + fn observation(tool: &str, status: &str, detail: Option<&str>) -> AgentRuntimeToolObservation { + AgentRuntimeToolObservation { + tool: tool.to_string(), + status: status.to_string(), + summary: String::new(), + detail: detail.map(str::to_string), + } + } + + #[test] + fn ui_design_doc_tools_count_as_project_mutation_when_they_return() { + for tool in [ + "ui-design-doc.from-images", + "ui-design-doc.run-workflow", + "ui-design-doc.into-js", + ] { + let observation = observation(tool, "ok", None); + assert!( + is_agent_runtime_project_mutation_observation(&observation), + "{tool} 成功返回后必须算改过项目" + ); + } + } + + #[test] + fn into_js_does_not_advance_project_revision() { + let observation = observation("ui-design-doc.into-js", "ok", None); + assert!(!agent_runtime_observation_advances_project_revision( + &observation + )); + assert_eq!( + agent_runtime_observation_project_revision_advance_count(&observation), + 0, + "只重写派生产物时不能虚报 revision 推进，否则会误报项目被别处改动" + ); + } + + #[test] + fn registered_ui_design_doc_tools_advance_project_revision() { + for tool in ["ui-design-doc.from-images", "ui-design-doc.run-workflow"] { + let observation = observation(tool, "ok", None); + assert!(agent_runtime_observation_advances_project_revision( + &observation + )); + assert_eq!( + agent_runtime_observation_project_revision_advance_count(&observation), + 1 + ); + } + } + + #[test] + fn reported_revision_advance_count_is_used_verbatim() { + let observation = observation( + "ui-design-doc.run-workflow", + "ok", + Some(r#"{"revisionAdvanceCount":3}"#), + ); + assert_eq!( + agent_runtime_observation_project_revision_advance_count(&observation), + 3, + "登记类工具在明细里报出的真实推进量必须优先于兜底的 1" + ); + } + + #[test] + fn failed_ui_design_doc_tool_counts_only_when_it_already_advanced_revision() { + let rolled_back = observation("ui-design-doc.from-images", "error", None); + assert!(!is_agent_runtime_project_mutation_observation(&rolled_back)); + assert!(!agent_runtime_observation_advances_project_revision( + &rolled_back + )); + + let partially_advanced = observation( + "ui-design-doc.run-workflow", + "error", + Some(r#"{"revisionAdvanceCount":2}"#), + ); + assert!(is_agent_runtime_project_mutation_observation( + &partially_advanced + )); + assert!(agent_runtime_observation_advances_project_revision( + &partially_advanced + )); + assert_eq!( + agent_runtime_observation_project_revision_advance_count(&partially_advanced), + 2 + ); + } + + #[test] + fn non_project_tools_are_unaffected() { + let observation = observation("file.read", "ok", Some(r#"{"lineCount":12}"#)); + assert!(!is_agent_runtime_project_mutation_observation(&observation)); + assert!(!agent_runtime_observation_advances_project_revision( + &observation + )); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/tool_policy_snapshot.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/tool_policy_snapshot.rs index b90402f76..8028b7901 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/tool_policy_snapshot.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/tool_policy_snapshot.rs @@ -59,7 +59,9 @@ pub(crate) fn agent_runtime_executable_tools() -> Vec<&'static str> { "preview.validate", "image.inspect", "canvas.asset_generate", - "ui.workflow.run", + "ui-design-doc.from-images", + "ui-design-doc.run-workflow", + "ui-design-doc.into-js", "blackboard.write", "agent.message", "agent.delegate", @@ -110,7 +112,7 @@ pub(crate) fn agent_runtime_acceptance_evidence_tools() -> BTreeSet<&'static str "image.inspect", "canvas.asset_generate", "canvas.asset_import", - "ui.workflow.run", + "ui-design-doc.run-workflow", ] .into_iter() .collect() diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/acceptance_graph.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/acceptance_graph.rs index ac1814fcf..6038bcc84 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/acceptance_graph.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/acceptance_graph.rs @@ -137,7 +137,7 @@ fn acceptance_evidence_tool_may_advance_project_revision(tool: &str) -> bool { | "project.patchset" | "canvas.asset_import" | "canvas.asset_generate" - | "ui.workflow.run" + | "ui-design-doc.run-workflow" ) } @@ -850,6 +850,16 @@ mod tests { .expect("append evidence receipt"); } + #[test] + fn ui_design_doc_workflow_evidence_may_advance_project_revision() { + // run-workflow 会写回文档并推进项目 revision；它同时是验收证据工具， + // 两处识别必须一致，否则真实执行后的取证会因 before != after 被判不匹配。 + assert!(agent_runtime_acceptance_evidence_tools().contains("ui-design-doc.run-workflow")); + assert!(acceptance_evidence_tool_may_advance_project_revision( + "ui-design-doc.run-workflow" + )); + } + #[test] fn root_completion_requires_contract_and_every_required_node() { let (_temporary, root, binding) = root_fixture(); diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/verification.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/verification.rs index e1bd6ce89..1c7b06bb4 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/verification.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/verification.rs @@ -162,7 +162,6 @@ pub(in crate::agent) fn validate_agent_runtime_verification_gate( | "command.start" | "canvas.asset_generate" | "canvas.asset_import" - | "ui.workflow.run" ) }) { return Err("Agent Runtime verification gate 的修改工具无效".to_string()); @@ -176,7 +175,6 @@ pub(in crate::agent) fn validate_agent_runtime_verification_gate( | "command.exec" | "preview.validate" | "canvas.asset_generate" - | "ui.workflow.run" ) }) { return Err("Agent Runtime verification gate 的验证工具无效".to_string()); diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools.rs index a68658e4a..9d8648eb0 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools.rs @@ -19,7 +19,7 @@ mod process_ops; mod project_ops; mod run_status; mod task_ops; -mod ui_workflow; +mod ui_design_doc; pub(in crate::agent) use action_history::*; pub(in crate::agent) use cocos_editor::*; @@ -39,7 +39,7 @@ pub(in crate::agent) use process_ops::*; pub(in crate::agent) use project_ops::*; pub(in crate::agent) use run_status::*; pub(in crate::agent) use task_ops::*; -pub(in crate::agent) use ui_workflow::*; +pub(in crate::agent) use ui_design_doc::*; #[cfg(test)] pub(crate) use delegation::observe_agent_runtime_agent_delegate_at_locked; diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/ui_design_doc.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/ui_design_doc.rs new file mode 100644 index 000000000..1cd763194 --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/ui_design_doc.rs @@ -0,0 +1,314 @@ +//! UI 设计文档三个工具在 Runtime 侧的参数解析与调用。 +//! +//! 工具名形如 `ui-design-doc.<动作>`；项目根目录、项目 ID 与 provider 身份一律由 +//! Runtime 注入，模型只给设计图引用与目标文档 assetId。 + +use super::*; +use crate::ui_editor::agent_tools::{ + create_ui_design_doc_from_images, run_ui_design_doc_workflow, CreateUiDesignDocFromImagesInput, + RunUiDesignDocWorkflowInput, UiDesignImageReference, +}; +use crate::ui_editor::persistence::{generate_ui_design_code_at, GenerateUiDesignCodeInput}; +use serde::Deserialize; +use serde_json::Value; + +pub(in crate::agent) const UI_DESIGN_DOC_FROM_IMAGES_TOOL: &str = "ui-design-doc.from-images"; +pub(in crate::agent) const UI_DESIGN_DOC_RUN_WORKFLOW_TOOL: &str = "ui-design-doc.run-workflow"; +pub(in crate::agent) const UI_DESIGN_DOC_INTO_JS_TOOL: &str = "ui-design-doc.into-js"; + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +struct FromImagesArguments { + images: Vec, +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +struct DesignDocArguments { + design_doc_asset_id: String, +} + +pub(in crate::agent) async fn observe_agent_runtime_ui_design_doc_from_images( + root: &Path, + input: &Value, +) -> AgentRuntimeToolObservation { + let tool = UI_DESIGN_DOC_FROM_IMAGES_TOOL; + let arguments = match serde_json::from_value::(input.clone()) { + Ok(arguments) => arguments, + Err(error) => return rejected(root, tool, format!("{tool} 输入无效：{error}")), + }; + let expected_project_id = match game_creator_agent_runtime_context_project_id(root) { + Ok(project_id) => project_id, + Err(error) => return rejected(root, tool, error), + }; + let revision_before = read_game_creator_agent_runtime_project_revision(root) + .ok() + .map(|snapshot| snapshot.revision); + // 新建文档要逐张解码设计图并写 manifest：整段阻塞 IO 交给 blocking 线程池， + // 别把 async 执行器（同一个 runtime 还要继续跑其它动作）占住。 + let project_path = root.to_string_lossy().into_owned(); + let images = arguments.images; + let created = match tokio::task::spawn_blocking(move || { + create_ui_design_doc_from_images(CreateUiDesignDocFromImagesInput { + project_path, + expected_project_id, + images, + }) + }) + .await + { + Ok(created) => created, + Err(_) => { + return error_observation(root, tool, "后台创建 UI 设计文档任务未完成".to_string()) + } + }; + match created { + Ok(created) => { + let revision_advance = revision_before + .map(|before| created.committed_project_revision.saturating_sub(before)); + if revision_before.is_none_or(|before| created.committed_project_revision > before) { + emit_game_creator_manifest_invalidated(root, tool); + } + AgentRuntimeToolObservation { + tool: tool.to_string(), + status: "ok".to_string(), + summary: format!( + "已新建 UI 设计文档 {}：{} 张设计图，路径 {}", + created.asset.id, + created.image_ids.len(), + created.relative_path + ), + detail: serde_json::to_string(&serde_json::json!({ + "assetId": created.asset.id, + "relativePath": created.relative_path, + "imageIds": created.image_ids, + "revisionAdvanceCount": revision_advance, + })) + .ok(), + } + } + Err(error) => error_observation_with_revision_advance( + root, + tool, + error, + project_revision_advance_since(root, revision_before), + ), + } +} + +pub(in crate::agent) async fn observe_agent_runtime_ui_design_doc_run_workflow( + root: &Path, + agent_id: &str, + run_id: &str, + input: &Value, +) -> AgentRuntimeToolObservation { + let tool = UI_DESIGN_DOC_RUN_WORKFLOW_TOOL; + let arguments = match serde_json::from_value::(input.clone()) { + Ok(arguments) => arguments, + Err(error) => return rejected(root, tool, format!("{tool} 输入无效：{error}")), + }; + let expected_project_id = match game_creator_agent_runtime_context_project_id(root) { + Ok(project_id) => project_id, + Err(error) => return rejected(root, tool, error), + }; + let revision_before = read_game_creator_agent_runtime_project_revision(root) + .ok() + .map(|snapshot| snapshot.revision); + match run_ui_design_doc_workflow( + RunUiDesignDocWorkflowInput { + project_path: root.to_string_lossy().into_owned(), + expected_project_id, + asset_id: arguments.design_doc_asset_id, + }, + Some((agent_id, run_id)), + ) + .await + { + Ok(result) => { + // result.revision 是文档自己的 revision（随文档重置），和项目 revision 不是同一个计数器； + // 重新读一次项目 revision，才能判断本次工作流是否真的推进了清单。 + let revision_after = read_game_creator_agent_runtime_project_revision(root) + .ok() + .map(|snapshot| snapshot.revision); + let revision_advance = revision_before + .zip(revision_after) + .map(|(before, after)| after.saturating_sub(before)); + if revision_before + .is_none_or(|before| revision_after.is_none_or(|after| after > before)) + { + emit_game_creator_manifest_invalidated(root, tool); + } + let pending = result.backfill_errors.len(); + AgentRuntimeToolObservation { + tool: tool.to_string(), + status: "ok".to_string(), + summary: format!( + "UI 设计文档工作流完成：识别 {} 棵树，回填 {} 个节点，{} 个待人工处理{}", + result.recognized_tree_count, + result.bound_node_count, + result.problematic_node_count, + if pending > 0 { + format!("，{pending} 项未回填") + } else { + String::new() + } + ), + detail: workflow_detail_with_revision_advance(&result, revision_advance), + } + } + Err(error) => error_observation_with_revision_advance( + root, + tool, + error, + project_revision_advance_since(root, revision_before), + ), + } +} + +pub(in crate::agent) async fn observe_agent_runtime_ui_design_doc_into_js( + root: &Path, + input: &Value, +) -> AgentRuntimeToolObservation { + let tool = UI_DESIGN_DOC_INTO_JS_TOOL; + let arguments = match serde_json::from_value::(input.clone()) { + Ok(arguments) => arguments, + Err(error) => return rejected(root, tool, format!("{tool} 输入无效：{error}")), + }; + let expected_project_id = match game_creator_agent_runtime_context_project_id(root) { + Ok(project_id) => project_id, + Err(error) => return rejected(root, tool, error), + }; + // 生成代码要读整份文档、算 SHA-256 再落盘，同样是阻塞 IO，放到 blocking 线程池。 + let project_path = root.to_string_lossy().into_owned(); + let asset_id = arguments.design_doc_asset_id; + let generated = match tokio::task::spawn_blocking(move || { + generate_ui_design_code_at(GenerateUiDesignCodeInput { + project_path, + expected_project_id, + asset_id, + }) + }) + .await + { + Ok(generated) => generated, + Err(_) => { + return error_observation(root, tool, "后台生成 UI 设计代码任务未完成".to_string()) + } + }; + match generated { + Ok(result) => AgentRuntimeToolObservation { + tool: tool.to_string(), + status: "ok".to_string(), + summary: format!( + "已生成 UI 设计代码 {}：{} 棵树 / {} 个节点", + result.relative_path, result.tree_count, result.node_count + ), + detail: serde_json::to_string(&result).ok(), + }, + Err(error) => error_observation(root, tool, error), + } +} + +/// 输入解析失败或项目上下文缺失：统一脱敏，避免摘要把宿主路径带给 provider。 +fn rejected(root: &Path, tool: &str, summary: String) -> AgentRuntimeToolObservation { + AgentRuntimeToolObservation { + tool: tool.to_string(), + status: "rejected".to_string(), + summary: redact_agent_runtime_project_paths(root, &summary, 240), + detail: None, + } +} + +fn error_observation(root: &Path, tool: &str, error: String) -> AgentRuntimeToolObservation { + AgentRuntimeToolObservation { + tool: tool.to_string(), + status: "error".to_string(), + summary: redact_agent_runtime_project_paths(root, &error, 500), + detail: None, + } +} + +/// 失败路径也可能已经改过项目（切图素材先登记、后面的步骤才失败，且按约定不回滚），所以重读一次项目 +/// 版本号，把真实推进量写进明细交给门禁；推进量为 0 时不写字段，明细保持原样。 +fn project_revision_advance_since(root: &Path, revision_before: Option) -> u64 { + let Some(before) = revision_before else { + return 0; + }; + read_game_creator_agent_runtime_project_revision(root) + .map(|snapshot| snapshot.revision.saturating_sub(before)) + .unwrap_or(0) +} + +fn error_observation_with_revision_advance( + root: &Path, + tool: &str, + error: String, + revision_advance: u64, +) -> AgentRuntimeToolObservation { + let mut observation = error_observation(root, tool, error); + if revision_advance > 0 { + observation.detail = + Some(serde_json::json!({ "revisionAdvanceCount": revision_advance }).to_string()); + } + observation +} + +/// 工作流结果明细原样保留，只追加一项真实推进量，供项目变更门禁读取。 +fn workflow_detail_with_revision_advance( + result: &T, + revision_advance: Option, +) -> Option { + let mut value = serde_json::to_value(result).ok()?; + if let Some(revision_advance) = revision_advance { + value + .as_object_mut()? + .insert("revisionAdvanceCount".to_string(), revision_advance.into()); + } + serde_json::to_string(&value).ok() +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[tokio::test] + async fn from_images_rejects_unknown_fields_and_accepts_reference_pairs() { + let root = Path::new("."); + let rejected = observe_agent_runtime_ui_design_doc_from_images( + root, + &json!({ "images": [{ "assetId": "a", "path": null }], "extra": 1 }), + ) + .await; + assert_eq!(rejected.status, "rejected"); + assert!(rejected.summary.contains("extra"), "{}", rejected.summary); + + // 参数合法但项目不存在：说明参数已经过解析，失败发生在项目校验之后。 + let invalid_project = observe_agent_runtime_ui_design_doc_from_images( + root, + &json!({ "images": [{ "assetId": "a", "path": null }] }), + ) + .await; + assert_eq!(invalid_project.status, "rejected"); + assert!(!invalid_project.summary.contains("输入无效")); + } + + #[tokio::test] + async fn design_doc_asset_id_must_be_a_string() { + // run-workflow 与 into-js 共用同一份入参解析，这里解析一次、各调用一次。 + assert!( + serde_json::from_value::(json!({ "designDocAssetId": 1 })).is_err() + ); + let observation = observe_agent_runtime_ui_design_doc_into_js( + Path::new("."), + &json!({ "designDocAssetId": 1 }), + ) + .await; + assert_eq!(observation.status, "rejected"); + assert!( + observation.summary.contains("输入无效"), + "{}", + observation.summary + ); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/ui_workflow.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/ui_workflow.rs deleted file mode 100644 index a9824df2c..000000000 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/ui_workflow.rs +++ /dev/null @@ -1,79 +0,0 @@ -use super::*; -use crate::ui_editor::workflow::{run_ui_workflow_at_with_provider, UiWorkflowRunInput}; -use serde_json::Value; - -pub(in crate::agent) async fn observe_agent_runtime_ui_workflow( - root: &Path, - agent_id: &str, - run_id: &str, - _task: &str, - input: &Value, -) -> AgentRuntimeToolObservation { - let parsed = match serde_json::from_value::(input.clone()) { - Ok(parsed) => parsed, - Err(error) => { - return AgentRuntimeToolObservation { - tool: "ui.workflow.run".to_string(), - status: "rejected".to_string(), - summary: format!("ui.workflow.run 输入无效：{error}"), - detail: None, - }; - } - }; - let operation = parsed.operation; - let revision_before = read_game_creator_agent_runtime_project_revision(root) - .ok() - .map(|snapshot| snapshot.revision); - match run_ui_workflow_at_with_provider(root, parsed, Some((agent_id, run_id))).await { - Ok(result) => { - let completed = result.completed; - let page_count = result.pages.len().max(result.discovered_pages.len()); - if result.revision_advance_count > 0 { - // Runtime actions can update manifest/State several times inside a - // single provider turn; publish the invalidation immediately so - // the workbench refreshes intermediate artifacts before finalize. - emit_game_creator_manifest_invalidated(root, "ui-workflow"); - } - let detail = serde_json::to_string(&result).ok(); - AgentRuntimeToolObservation { - tool: "ui.workflow.run".to_string(), - status: "ok".to_string(), - summary: if operation == crate::ui_editor::workflow::UiWorkflowOperation::Discover { - format!("UI workflow 自动发现 {page_count} 个功能页面") - } else if completed { - format!("UI workflow 已完成 {page_count} 个页面并生成最终编辑阶段路由") - } else { - format!("UI workflow 已更新 {page_count} 个页面的持久阶段状态") - }, - detail, - } - } - Err(error) => { - // Recognition can durably install a real structure before a later - // provider-backed binding step fails. The client still needs that - // intermediate State/manifest update even though this operation - // truthfully reports an error. - let revision_advanced = revision_before.is_some_and(|before| { - read_game_creator_agent_runtime_project_revision(root) - .ok() - .is_some_and(|after| after.revision > before) - }); - if revision_advanced { - emit_game_creator_manifest_invalidated(root, "ui-workflow"); - } - AgentRuntimeToolObservation { - tool: "ui.workflow.run".to_string(), - status: if operation == crate::ui_editor::workflow::UiWorkflowOperation::Finalize - || error.contains("拒绝伪造完成") - { - "rejected" - } else { - "error" - } - .to_string(), - summary: redact_agent_runtime_project_paths(root, &error, 500), - detail: None, - } - } - } -} diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent_native_tools.rs b/apps/ai-game-creator-shell/src-tauri/src/agent_native_tools.rs index 799c26b83..8b24b0cfc 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent_native_tools.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent_native_tools.rs @@ -225,9 +225,11 @@ pub(crate) fn native_runtime_function_name(tool: &str) -> Option { } fn native_runtime_function_name_for_tool(tool: &str) -> String { + // 工具 ID 允许 '-'（如 `ui-design-doc.from-images`），函数名只能是 + // `[A-Za-z_][A-Za-z0-9_]*`，两种分隔符都要归一成下划线。 format!( "{AGENT_RUNTIME_NATIVE_TOOL_PREFIX}{}", - tool.replace('.', "_") + tool.replace(['.', '-'], "_") ) } @@ -1051,9 +1053,9 @@ fn runtime_tool_description(tool: &str) -> &'static str { "canvas.asset_generate" => { prompt_text!("nativeTools.canvas.asset_generate.description") } - "ui.workflow.run" => { - prompt_text!("nativeTools.ui.workflow.run.description") - } + "ui-design-doc.from-images" => prompt_text!("uiDesignDoc.from_images.description"), + "ui-design-doc.run-workflow" => prompt_text!("uiDesignDoc.run_workflow.description"), + "ui-design-doc.into-js" => prompt_text!("uiDesignDoc.into_js.description"), "cocos.editor.execute" => { prompt_text!("nativeTools.cocos.editor.execute.description") } @@ -1160,6 +1162,37 @@ fn runtime_tool_input_schema(tool: &str) -> Value { } } }), + "ui-design-doc.from-images" => json!({ + "type": "object", + // 每张设计图给 assetId 或 path 之一，另一个显式传 null。 + "required": ["images"], + "additionalProperties": false, + "properties": { + "images": { + "type": "array", + "minItems": 1, + "maxItems": 4, + "description": prompt_text!("uiDesignDoc.from_images.parameters.images"), + "items": { + "type": "object", + "required": ["assetId", "path"], + "additionalProperties": false, + "properties": { + "assetId": { "type": ["string", "null"], "minLength": 1, "maxLength": 512 }, + "path": { "type": ["string", "null"], "minLength": 1, "maxLength": 512 } + } + } + } + } + }), + "ui-design-doc.run-workflow" => one_string_input_schema_with_description( + "designDocAssetId", + prompt_text!("uiDesignDoc.run_workflow.parameters.designDocAssetId"), + ), + "ui-design-doc.into-js" => one_string_input_schema_with_description( + "designDocAssetId", + prompt_text!("uiDesignDoc.into_js.parameters.designDocAssetId"), + ), "project.search" => json!({ "type": "object", "required": ["query", "path", "maxResults", "caseSensitive"], "additionalProperties": false, "properties": { @@ -1343,33 +1376,6 @@ fn runtime_tool_input_schema(tool: &str) -> Value { } }) } - "ui.workflow.run" => json!({ - "type": "object", - "required": ["operation", "sourceAssetId", "pages"], - "additionalProperties": false, - "properties": { - "operation": { "type": "string", "enum": ["discover", "prepare", "recognize", "status", "finalize"] }, - "sourceAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, - "pages": { - "type": "array", - "maxItems": 32, - "items": { - "type": "object", - "required": ["pageId", "title", "description", "designAssetId", "spriteAssetIds", "fontAssetIds", "applicationPath"], - "additionalProperties": false, - "properties": { - "pageId": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z0-9._-]+$" }, - "title": { "type": "string", "minLength": 1, "maxLength": 120 }, - "description": { "type": "string", "maxLength": 400 }, - "designAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, - "spriteAssetIds": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, - "fontAssetIds": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, - "applicationPath": { "type": ["string", "null"], "maxLength": 240 } - } - } - } - } - }), "blackboard.write" => two_string_input_schema("title", "content"), "agent.message" => two_string_input_schema("agentId", "content"), "agent.delegate" => json!({ @@ -1506,6 +1512,16 @@ fn one_string_input_schema(field: &str) -> Value { }) } +/// 与 `one_string_input_schema` 同形，但把文案里的参数说明挂到字段上。 +fn one_string_input_schema_with_description(field: &str, description: &str) -> Value { + json!({ + "type": "object", + "required": [field], + "additionalProperties": false, + "properties": { (field): { "type": "string", "description": description } } + }) +} + fn two_string_input_schema(first: &str, second: &str) -> Value { json!({ "type": "object", @@ -2171,4 +2187,32 @@ mod tests { }) ); } + + #[test] + fn native_ui_design_doc_tools_expose_dash_free_function_names() { + // 工具 ID 允许 '-'，Function Calling 的函数名不允许；两者不能混用同一套归一。 + let fallback = runtime_tool_description("ui-design-doc.unknown"); + for tool in [ + "ui-design-doc.from-images", + "ui-design-doc.run-workflow", + "ui-design-doc.into-js", + ] { + let function_name = native_runtime_function_name_for_tool(tool); + assert!( + !function_name.contains(['.', '-']), + "{tool} 的函数名仍有非法字符：{function_name}" + ); + assert_ne!( + runtime_tool_description(tool), + fallback, + "{tool} 缺少工具描述" + ); + assert_eq!(runtime_tool_input_schema(tool)["type"], json!("object")); + } + assert_eq!( + runtime_tool_input_schema("ui-design-doc.from-images")["properties"]["images"] + ["maxItems"], + json!(4) + ); + } } 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 c2a53a4a4..68b5c610d 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs @@ -2066,122 +2066,6 @@ pub(crate) fn register_local_asset( ) } -#[tauri::command] -pub(crate) fn create_ui_design_resource( - project_path: String, - expected_project_id: String, -) -> Result { - let root = Path::new(project_path.trim()); - enforce_project_permission_policy(root, "asset.register")?; - let _lock = acquire_project_write_lock(root, "asset.register")?; - let manifest = read_existing_manifest_for_project(root)?; - if manifest.project_id != expected_project_id.trim() { - return Err("project-identity-conflict".to_string()); - } - let (resource_name, relative_path) = - crate::ui_editor::resource_bridge::next_ui_design_path(root, &manifest)?; - let absolute_path = resolve_local_project_path(root, &relative_path)?; - if let Some(parent) = absolute_path.parent() { - ensure_game_creator_private_directory_tree(parent, "UI 资源目录")?; - prepare_game_creator_private_path_for_read(parent, true, "UI 资源目录")?; - } - if prepare_game_creator_private_path_for_read(&absolute_path, false, "UI 资源")? { - return Err("UI 设计资源路径已存在，拒绝覆盖".to_string()); - } - let mut options = fs::OpenOptions::new(); - options.write(true).create_new(true); - #[cfg(windows)] - { - use std::os::windows::fs::OpenOptionsExt; - options.custom_flags(crate::PROJECT_FILE_FLAG_OPEN_REPARSE_POINT); - } - let file = options - .open(&absolute_path) - .map_err(|error| format!("创建 UI 资源失败：{}: {error}", absolute_path.display()))?; - if let Err(error) = harden_new_game_creator_private_path(&absolute_path, false, "UI 资源") { - drop(file); - let _ = fs::remove_file(&absolute_path); - return Err(error); - } - file.sync_all() - .map_err(|error| format!("同步 UI 资源失败：{}: {error}", absolute_path.display()))?; - drop(file); - let asset = match register_local_asset_at( - root, - &relative_path, - GameCreationAppAssetKind::UiDesignDoc, - crate::ui_editor::persistence::UI_DESIGN_DOC_MEDIA_TYPE, - "generated", - GameCreationAppAssetSource { - kind: GameCreationAppAssetSourceKind::Generated, - canvas_project_id: None, - resource_id: Some(format!( - "ui:{}", - resource_name.trim_start_matches("UI 设计 ") - )), - asset_object_id: None, - task_id: None, - prompt: None, - model: None, - generation_route: None, - generation_kind: None, - reference_resource_ids: Vec::new(), - }, - ) { - Ok(asset) => asset, - Err(error) => { - let rollback = (|| { - write_manifest(&root.join(".agent/manifest.json"), &manifest)?; - fs::remove_file(&absolute_path).map_err(|remove_error| { - format!( - "删除未完成 UI 设计资源失败：{}: {remove_error}", - absolute_path.display() - ) - }) - })(); - return match rollback { - Ok(()) => Err(error), - Err(rollback_error) => Err(format!( - "UI 设计资源登记失败：{error}；reconciliation-required: 回滚未完成：{rollback_error}" - )), - }; - } - }; - if let Err(error) = ui_editor::persistence::initialize_ui_design_state_at( - root, - expected_project_id.trim(), - &asset.id, - ) { - let rollback = (|| { - let mut current = read_existing_manifest_for_project(root)?; - current.assets.retain(|entry| entry.id != asset.id); - write_manifest(&root.join(".agent/manifest.json"), ¤t)?; - fs::remove_file(&absolute_path).map_err(|remove_error| { - format!( - "删除未完成 UI 设计资源失败：{}: {remove_error}", - absolute_path.display() - ) - }) - })(); - return match rollback { - Ok(()) => Err(error), - Err(rollback_error) => Err(format!( - "UI 设计资源初始化失败：{error}；reconciliation-required: 回滚未完成：{rollback_error}" - )), - }; - } - advance_agent_runtime_project_revision_locked(root).map_err(|error| { - format!("reconciliation-required: UI 设计资源已创建，但项目 revision 未能推进：{error}") - })?; - let manifest = read_existing_manifest_for_project(root)?; - let revision = read_game_creator_agent_runtime_project_revision(root)?.revision; - Ok(CreateUiDesignResourceResult { - asset, - manifest, - committed_project_revision: revision, - }) -} - #[tauri::command] pub(crate) fn update_local_project_resource_classification( input: UpdateLocalProjectResourceClassificationInput, diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs index 70a568bdf..e0ceeb6da 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/main.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs @@ -196,14 +196,6 @@ use runner::*; use template_library::*; use user_input::*; use windows::*; -#[tauri::command] -async fn suggest_ui_design_semantic( - project_path: String, - state: ui_editor::state::State, -) -> Result, String> { - ui_editor::commands::suggest_ui_design_semantic_impl(project_path, state).await -} - #[tauri::command] async fn recognize_ui( project_path: String, @@ -247,20 +239,6 @@ fn discard_separation_recovery(project_path: String, asset_id: String) -> Result ui_editor::commands::separation::discard_separation_recovery(root, &asset_id) } -#[tauri::command] -async fn merge_ui(state: ui_editor::state::State) -> Result { - ui_editor::commands::merge_ui_impl(state).await -} - -#[tauri::command] -async fn bind_components( - project_path: String, - state: ui_editor::state::State, - sprite_ids: Vec, -) -> Result { - ui_editor::commands::bind_components_impl(project_path, state, sprite_ids).await -} - #[tauri::command] fn load_ui_design_state( input: ui_editor::persistence::LoadUiDesignStateInput, @@ -318,10 +296,10 @@ fn generate_ui_design_code( } #[tauri::command] -fn ensure_ui_design_resource_for_prototype( - input: ui_editor::resource_bridge::EnsureUiDesignResourceForPrototypeInput, -) -> Result { - ui_editor::resource_bridge::ensure_ui_design_resource_for_prototype(input) +fn create_ui_design_doc_from_images( + input: ui_editor::agent_tools::CreateUiDesignDocFromImagesInput, +) -> Result { + ui_editor::agent_tools::create_ui_design_doc_from_images(input) } #[derive(Debug, Eq, PartialEq, Serialize)] @@ -1121,14 +1099,6 @@ struct UploadLocalAssetResult { manifest_path: String, } -#[derive(Debug, Eq, PartialEq, Serialize)] -#[serde(rename_all = "camelCase")] -struct CreateUiDesignResourceResult { - asset: UploadLocalAssetResult, - manifest: GameCreationAppManifest, - committed_project_revision: u64, -} - #[derive(Debug, Eq, PartialEq, Serialize)] #[serde(rename_all = "camelCase")] struct ImportCanvasExportResult { @@ -2694,7 +2664,7 @@ fn main() { discover_game_creator_llm_models, upload_local_asset, register_local_asset, - create_ui_design_resource, + create_ui_design_doc_from_images, update_local_project_resource_classification, add_local_project_resource_tags, derive_local_project_resource, @@ -2711,18 +2681,14 @@ fn main() { prepare_ui_editor_project_fonts, read_ui_editor_font_bytes, check_ui_editor_font_glyph_coverage, - suggest_ui_design_semantic, recognize_ui, separate_ui, inspect_separation_recovery, finalize_separation, discard_separation_recovery, - merge_ui, - bind_components, load_ui_design_state, save_ui_design_state, generate_ui_design_code, - ensure_ui_design_resource_for_prototype, generate_platform_art_asset, generate_local_project_asset, start_local_project_asset_generation, 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 12d3df16c..f1ed549ff 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 @@ -2771,7 +2771,7 @@ fn register_local_asset_keeps_explicit_category_when_kind_is_unchanged() { /// 写侧 → 分类的端到端口径：现役写入侧直接写出的 canonical kind 必须落进明确栏目。 /// /// 这里的字面量与写入侧逐字一致：UI 设计资产是 -/// `ui_editor/resource_bridge.rs` / `workflow.rs` / `persistence.rs` 的 +/// `ui_editor/agent_tools/creation.rs` / `persistence.rs` 的 /// `register_local_asset_at` 使用 UI 文档 kind/media 常量， /// 字体是 `commands.rs` 字体上传的 `register_local_asset_entry(root, path, "font", ...)`。 #[test] @@ -2842,37 +2842,115 @@ fn register_local_asset_derives_category_from_real_write_side_kinds() { fs::remove_dir_all(root).ok(); } -/// 已存在的 `ui/UI 设计 N.json` 不能让新建 UI 设计资源直接失败。 +/// 已存在的 `ui/UI 设计 N.json` 不能让新建 UI 设计文档直接失败。 /// /// 编号按已登记的 UI 文档数推导，旧项目里 kind 已被收口为 `unknown` 的文档不再计入， -/// 只按计数取名就会撞上仍然存在的同名文件并报「路径已存在」。两个写入侧必须共用 -/// `ui_editor::resource_bridge` 的「第一个空闲编号」规则，既不改名既有文件也不覆盖。 +/// 只按计数取名就会撞上仍然存在的同名文件并报「路径已存在」。文档创建入口必须用 +/// `ui_editor::agent_tools::next_ui_design_path` 的「第一个空闲编号」规则， +/// 既不改名既有文件也不覆盖。 #[test] -fn create_ui_design_resource_skips_a_taken_ui_design_path() { +fn create_ui_design_doc_from_images_skips_a_taken_ui_design_path() { let root = unique_project_path(); init_local_game_project_at(&root, "project-1", "UI 设计编号避让").expect("project init"); write_local_project_file_at(&root, "ui/UI 设计 1.json", "{}").expect("ui asset file"); - - let result = crate::commands::create_ui_design_resource( - root.to_string_lossy().to_string(), - "project-1".to_string(), + let mut bytes = Vec::new(); + image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel( + 64, + 48, + image::Rgba([10, 20, 30, 255]), + )) + .write_to( + &mut std::io::Cursor::new(&mut bytes), + image::ImageFormat::Png, ) - .expect("create UI design resource"); + .expect("encode design image"); + fs::create_dir_all(root.join("assets")).expect("assets dir"); + fs::write(root.join("assets/page.png"), bytes).expect("write design image"); - assert_eq!(result.asset.local_path, "ui/UI 设计 2.json"); - let registered = result + let created = crate::ui_editor::agent_tools::create_ui_design_doc_from_images( + crate::ui_editor::agent_tools::CreateUiDesignDocFromImagesInput { + project_path: root.to_string_lossy().to_string(), + expected_project_id: "project-1".to_string(), + images: vec![crate::ui_editor::agent_tools::UiDesignImageReference { + asset_id: None, + path: Some("assets/page.png".to_string()), + }], + }, + ) + .expect("create UI design document"); + + assert_eq!(created.relative_path, "ui/UI 设计 2.json"); + assert_eq!(created.image_ids.len(), 1); + assert_eq!(created.asset.local_path, "ui/UI 设计 2.json"); + assert_eq!(created.asset.source.resource_id.as_deref(), Some("ui:2")); + assert_eq!(created.asset.kind, GameCreationAppAssetKind::UiDesignDoc); + let registered_image = created .manifest .assets .iter() - .find(|asset| asset.id == result.asset.id) - .expect("registered UI design asset"); - assert_eq!(registered.source.resource_id.as_deref(), Some("ui:2")); - assert_eq!(registered.kind, GameCreationAppAssetKind::UiDesignDoc); + .find(|asset| asset.id == created.image_ids[0]) + .expect("registered design image asset"); + assert_eq!(registered_image.local_path, "assets/page.png"); + assert_eq!(registered_image.media_type, "image/png"); assert!(root.join("ui/UI 设计 1.json").is_file()); fs::remove_dir_all(root).ok(); } +/// 批次里后面某张设计图不合法时，前面已通过校验的图片不能留在 manifest 里。 +/// +/// 登记动作本身是 manifest 副作用：如果边校验边登记，一旦后续引用失败就没有回滚路径， +/// 会在 manifest 里留下没有任何文档引用的图片条目。整批先校验再登记才不会漏。 +#[test] +fn create_ui_design_doc_from_images_leaves_no_orphan_assets_when_a_later_image_fails() { + let root = unique_project_path(); + init_local_game_project_at(&root, "project-1", "UI 设计批次校验").expect("project init"); + let mut bytes = Vec::new(); + image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel( + 32, + 24, + image::Rgba([1, 2, 3, 255]), + )) + .write_to( + &mut std::io::Cursor::new(&mut bytes), + image::ImageFormat::Png, + ) + .expect("encode design image"); + fs::create_dir_all(root.join("assets")).expect("assets dir"); + fs::write(root.join("assets/page.png"), bytes).expect("write design image"); + + let error = crate::ui_editor::agent_tools::create_ui_design_doc_from_images( + crate::ui_editor::agent_tools::CreateUiDesignDocFromImagesInput { + project_path: root.to_string_lossy().to_string(), + expected_project_id: "project-1".to_string(), + images: vec![ + crate::ui_editor::agent_tools::UiDesignImageReference { + asset_id: None, + path: Some("assets/page.png".to_string()), + }, + crate::ui_editor::agent_tools::UiDesignImageReference { + asset_id: None, + path: Some("assets/missing.png".to_string()), + }, + ], + }, + ) + .expect_err("批次中存在缺失的设计图时必须整批失败"); + assert!(error.contains("missing.png"), "{error}"); + + let manifest = crate::read_existing_manifest_for_project(&root).expect("read manifest"); + assert!( + manifest + .assets + .iter() + .all(|asset| asset.local_path != "assets/page.png"), + "整批校验失败时不该把已校验通过的图片登记进 manifest" + ); + assert!(!root.join("ui/UI 设计 1.json").is_file()); + + fs::remove_dir_all(root).ok(); +} + #[test] fn register_local_asset_rejects_missing_or_unsafe_path() { let root = unique_project_path(); diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/runtime_actions/action_execution.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/runtime_actions/action_execution.rs index bbc5186fb..780f589d6 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tests/runtime_actions/action_execution.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/runtime_actions/action_execution.rs @@ -2230,3 +2230,145 @@ fn seed_refresh_preserves_completed_visual_tasks_when_registered_file_is_missing fs::remove_dir_all(root).ok(); } + +#[test] +fn ui_design_doc_receipts_keep_safe_detail_instead_of_dropping_it() { + let root = unique_project_path(); + init_local_game_project_at(&root, "project-1", "UI 设计文档回执脱敏测试") + .expect("project init"); + + let from_images = AgentRuntimeToolObservation { + tool: "ui-design-doc.from-images".to_string(), + status: "ok".to_string(), + summary: "已新建 UI 设计文档".to_string(), + detail: Some( + serde_json::json!({ + "assetId": "generated-ui-design-1", + "relativePath": "ui/UI 设计 1.json", + "imageIds": ["image-1", "image-2"], + "revisionAdvanceCount": 2, + }) + .to_string(), + ), + }; + let public = agent_runtime_action_receipt_public_safe_detail_for_test(&root, &from_images) + .expect("from-images 必须留下可用明细"); + assert!(public.chars().count() <= 500, "{public}"); + let public = serde_json::from_str::(&public).expect("parse from-images detail"); + assert_eq!(public["assetId"], "generated-ui-design-1"); + assert_eq!(public["relativePath"], "ui/UI 设计 1.json"); + assert_eq!(public["imageIds"].as_array().map(Vec::len), Some(2)); + assert_eq!(public["revisionAdvanceCount"], 2); + + let run_workflow = AgentRuntimeToolObservation { + tool: "ui-design-doc.run-workflow".to_string(), + status: "ok".to_string(), + summary: "UI 设计文档工作流完成".to_string(), + detail: Some( + serde_json::json!({ + "assetId": "generated-ui-design-1", + "relativePath": "ui/UI 设计 1.json", + "revision": 3, + "recoveredFromCheckpoint": true, + "recognizedTreeCount": 2, + "boundNodeCount": 9, + "problematicNodeCount": 1, + "backfillErrors": [ + "未能登记自动切分素材图片：assets/cut.png", + format!("读取资源失败：{}", root.join("assets/cut.png").display()), + ], + "revisionAdvanceCount": 3, + }) + .to_string(), + ), + }; + let public = agent_runtime_action_receipt_public_safe_detail_for_test(&root, &run_workflow) + .expect("run-workflow 必须留下可用明细"); + assert!(public.chars().count() <= 500, "{public}"); + assert!( + !public.contains(root.to_string_lossy().as_ref()), + "回填说明里的宿主路径必须脱敏：{public}" + ); + let public = serde_json::from_str::(&public).expect("parse run-workflow detail"); + assert_eq!(public["recoveredFromCheckpoint"], true); + assert_eq!(public["problematicNodeCount"], 1); + assert_eq!(public["backfillErrorCount"], 2); + assert_eq!( + public["backfillErrors"][0], + "未能登记自动切分素材图片：assets/cut.png" + ); + + let into_js = AgentRuntimeToolObservation { + tool: "ui-design-doc.into-js".to_string(), + status: "ok".to_string(), + summary: "已生成 UI 设计代码".to_string(), + detail: Some( + serde_json::json!({ + "relativePath": "ui/generated-ui-design-1-0123456789abcdef.js", + "treeExports": ["treeA", "treeB"], + "treeCount": 2, + "nodeCount": 12, + }) + .to_string(), + ), + }; + let public = agent_runtime_action_receipt_public_safe_detail_for_test(&root, &into_js) + .expect("into-js 必须留下可用明细"); + let public = serde_json::from_str::(&public).expect("parse into-js detail"); + assert_eq!(public["treeCount"], 2); + assert_eq!(public["nodeCount"], 12); + assert!( + public.get("treeExports").is_none(), + "导出名清单只用于核对数量，不逐项外传：{public}" + ); + + fs::remove_dir_all(root).ok(); +} + +#[test] +fn ui_design_doc_receipts_reject_out_of_scope_paths_and_malformed_detail() { + let root = unique_project_path(); + init_local_game_project_at(&root, "project-1", "UI 设计文档回执边界测试") + .expect("project init"); + + let outside_ui_directory = AgentRuntimeToolObservation { + tool: "ui-design-doc.from-images".to_string(), + status: "ok".to_string(), + summary: "已新建 UI 设计文档".to_string(), + detail: Some( + serde_json::json!({ + "assetId": "generated-ui-design-1", + "relativePath": "game/UI 设计 1.json", + "imageIds": ["image-1"], + "revisionAdvanceCount": 1, + }) + .to_string(), + ), + }; + assert!( + agent_runtime_action_receipt_public_safe_detail_for_test(&root, &outside_ui_directory) + .is_none(), + "不在 ui/ 下的相对路径必须失败关闭" + ); + + let absolute_document_id = AgentRuntimeToolObservation { + tool: "ui-design-doc.run-workflow".to_string(), + status: "ok".to_string(), + summary: "UI 设计文档工作流完成".to_string(), + detail: Some( + serde_json::json!({ + "assetId": root.join("ui/UI 设计 1.json").to_string_lossy(), + "relativePath": "ui/UI 设计 1.json", + "revisionAdvanceCount": 1, + }) + .to_string(), + ), + }; + assert!( + agent_runtime_action_receipt_public_safe_detail_for_test(&root, &absolute_document_id) + .is_none(), + "身份字段不能是宿主路径" + ); + + fs::remove_dir_all(root).ok(); +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/tool_plan_handoff/content_validation.rs b/apps/ai-game-creator-shell/src-tauri/src/tool_plan_handoff/content_validation.rs index e532e76b7..246a01bf6 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tool_plan_handoff/content_validation.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tool_plan_handoff/content_validation.rs @@ -423,11 +423,12 @@ fn collect_native_tool_absolute_path_findings( findings, ); } - "ui.workflow.run" => { - if let Some(pages) = input.get("pages").and_then(serde_json::Value::as_array) { - for (index, page) in pages.iter().enumerate() { - let pointer = format!("{input_pointer}/pages/{index}/applicationPath"); - collect_native_string_field(root, page, "applicationPath", &pointer, findings); + "ui-design-doc.from-images" => { + // 设计图可以给项目内相对路径，交接阶段先按同一套判据拒绝绝对路径逃逸。 + if let Some(images) = input.get("images").and_then(serde_json::Value::as_array) { + for (index, image) in images.iter().enumerate() { + let pointer = format!("{input_pointer}/images/{index}/path"); + collect_native_string_field(root, image, "path", &pointer, findings); } } } diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/checkpoint.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/checkpoint.rs new file mode 100644 index 000000000..97d8aa8ef --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/checkpoint.rs @@ -0,0 +1,480 @@ +//! 工作流检查点日志：`ui/.<文档名>-workflow.jsonl`。 +//! +//! 这个模块只管日志机制——行格式、原子追加、半行截断、轮次扫描——不认识任何 +//! 业务 DTO 与 State 类型，步骤载荷一律按 `serde_json::Value` 原样存回。 +//! 方案见 `docs/technical/【技术方案】UI编辑器Agent工具化重写-2026-09-23.md`。 + +use serde::{Deserialize, Serialize}; +use serde_json::Value; +use std::fs::OpenOptions; +use std::io::{Read, Seek, SeekFrom, Write}; +use std::path::{Path, PathBuf}; +use std::time::{SystemTime, UNIX_EPOCH}; + +const WORKFLOW_LOG_SUFFIX: &str = "-workflow.jsonl"; +const TORN_TAIL_SCAN_BYTES: u64 = 64 * 1024; + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +#[serde(tag = "type", rename_all = "kebab-case")] +pub(crate) enum CheckpointLine { + /// 一轮的起点：原始 State 快照与起始 revision。 + Run { + at: u64, + doc: CheckpointDocument, + revision: u64, + state: Value, + }, + Recognize { + at: u64, + dto: Value, + /// 这一步在内存里应用完之后的 State 快照。恢复时直接读回来， + /// 不再按 dto 重放这一步的 delta。旧版日志没有这一栏，缺失即视为该步不可恢复。 + state: Option, + }, + Separate { + at: u64, + dto: Value, + state: Option, + /// 这一步产出的回填说明：恢复不再重跑该步，所以和状态快照一起存。 + #[serde(default)] + backfill_errors: Vec, + }, + /// 一轮的结束：文档已写回这个 revision。 + WriteBack { at: u64, revision: u64 }, + /// 一轮的结束：本轮作废，不再尝试恢复。 + Outdated { at: u64, reason: String }, +} + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +#[serde(rename_all = "camelCase")] +pub(crate) struct CheckpointDocument { + pub(crate) asset_id: String, +} + +#[derive(Clone, Debug, Eq, PartialEq)] +pub(crate) enum RoundOutcome { + /// 还没有结束行：这一轮需要恢复。 + Open, + WrittenBack { + revision: u64, + }, + Outdated { + reason: String, + }, +} + +/// 最后一轮的可恢复内容。`base_state` 是 `run` 行的原始 State 快照， +/// 各步的 `*_state` 是那一步做完之后的 State 快照。 +#[derive(Clone, Debug)] +pub(crate) struct WorkflowRound { + pub(crate) at: u64, + pub(crate) document_asset_id: String, + pub(crate) base_revision: u64, + pub(crate) base_state: Value, + pub(crate) recognize_dto: Option, + pub(crate) recognize_state: Option, + pub(crate) separate_dto: Option, + pub(crate) separate_state: Option, + pub(crate) backfill_errors: Vec, + pub(crate) outcome: RoundOutcome, +} + +pub(crate) struct WorkflowLog { + path: PathBuf, +} + +impl WorkflowLog { + pub(crate) fn open(root: &Path, document_relative_path: &str) -> Result { + Ok(Self { + path: workflow_log_path(root, document_relative_path)?, + }) + } + + /// 读取最后一轮。文件不存在或没有完整 `run` 行时返回 `None`。 + pub(crate) fn last_round(&self) -> Result, String> { + let Some(content) = read_log_content(&self.path)? else { + return Ok(None); + }; + parse_last_round(&self.path, &content) + } + + /// 一次性追加一行。崩溃可能留下写了一半的最后一行，追加前先把日志截断到最后 + /// 一个换行，避免半行夹在日志中间让后续扫描失败。 + pub(crate) fn append(&self, line: &CheckpointLine) -> Result<(), String> { + let mut bytes = + serde_json::to_vec(line).map_err(|error| format!("序列化工作流检查点失败：{error}"))?; + bytes.push(b'\n'); + if let Some(parent) = self.path.parent() { + std::fs::create_dir_all(parent).map_err(|error| { + format!("创建工作流检查点目录失败：{}：{error}", parent.display()) + })?; + } + let mut file = OpenOptions::new() + .create(true) + .read(true) + .append(true) + .open(&self.path) + .map_err(|error| { + format!("打开工作流检查点日志失败：{}：{error}", self.path.display()) + })?; + truncate_torn_tail(&mut file, &self.path)?; + file.write_all(&bytes) + .map_err(|error| format!("追加工作流检查点失败：{}：{error}", self.path.display()))?; + file.sync_all() + .map_err(|error| format!("同步工作流检查点失败：{}：{error}", self.path.display()))?; + Ok(()) + } +} + +/// 检查点行的时间戳：秒级 Unix 时间。 +pub(crate) fn checkpoint_timestamp() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|elapsed| elapsed.as_secs()) + .unwrap_or(0) +} + +/// 文档旁的同级隐藏日志：`ui/UI 设计 1.json` → `ui/.UI 设计 1-workflow.jsonl`。 +pub(crate) fn workflow_log_path( + root: &Path, + document_relative_path: &str, +) -> Result { + let document_relative_path = crate::normalize_relative_path(document_relative_path.trim())?; + let document_path = Path::new(&document_relative_path); + let stem = document_path + .file_stem() + .and_then(|value| value.to_str()) + .filter(|value| !value.trim().is_empty()) + .ok_or_else(|| "UI 设计文档路径缺少文件名".to_string())?; + let directory = document_path.parent().unwrap_or_else(|| Path::new("")); + Ok(root + .join(directory) + .join(format!(".{stem}{WORKFLOW_LOG_SUFFIX}"))) +} + +fn read_log_content(path: &Path) -> Result, String> { + match std::fs::read(path) { + Ok(bytes) => String::from_utf8(bytes) + .map(Some) + .map_err(|error| format!("工作流检查点日志不是 UTF-8：{}：{error}", path.display())), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None), + Err(error) => Err(format!( + "读取工作流检查点日志失败：{}：{error}", + path.display() + )), + } +} + +fn truncate_torn_tail(file: &mut std::fs::File, path: &Path) -> Result<(), String> { + let length = file + .metadata() + .map_err(|error| format!("读取工作流检查点长度失败：{}：{error}", path.display()))? + .len(); + if length == 0 { + return Ok(()); + } + let start = length.saturating_sub(TORN_TAIL_SCAN_BYTES); + let mut tail = Vec::new(); + file.seek(SeekFrom::Start(start)) + .and_then(|_| file.take(length - start).read_to_end(&mut tail)) + .map_err(|error| format!("读取工作流检查点末尾失败：{}：{error}", path.display()))?; + if tail.last() == Some(&b'\n') { + return Ok(()); + } + if let Some(index) = tail.iter().rposition(|byte| *byte == b'\n') { + return file + .set_len(start + index as u64 + 1) + .map_err(|error| format!("截断工作流检查点半行失败：{}：{error}", path.display())); + } + // 末尾 64 KiB 一个换行都没有：退回到整文件扫描，避免把完整行截掉。 + let mut whole = Vec::new(); + file.seek(SeekFrom::Start(0)) + .and_then(|_| file.read_to_end(&mut whole)) + .map_err(|error| format!("读取工作流检查点失败：{}：{error}", path.display()))?; + let keep = whole + .iter() + .rposition(|byte| *byte == b'\n') + .map(|index| index as u64 + 1) + .unwrap_or(0); + file.set_len(keep) + .map_err(|error| format!("截断工作流检查点半行失败：{}：{error}", path.display())) +} + +fn parse_last_round(path: &Path, content: &str) -> Result, String> { + let chunks: Vec<&str> = content.split('\n').collect(); + let last_index = chunks.len().saturating_sub(1); + let mut round: Option = None; + for (index, raw) in chunks.iter().enumerate() { + if raw.is_empty() { + continue; + } + let line = match serde_json::from_str::(raw) { + Ok(line) => line, + // 没有换行收尾的最后一段是崩溃留下的半行，整段丢弃且不算完成。 + Err(_) if index == last_index && !content.ends_with('\n') => break, + Err(error) => { + return Err(format!( + "工作流检查点日志第 {} 行无法解析：{}：{error}", + index + 1, + path.display() + )) + } + }; + apply_line(&mut round, line); + } + Ok(round) +} + +fn apply_line(round: &mut Option, line: CheckpointLine) { + match line { + CheckpointLine::Run { + at, + doc, + revision, + state, + } => { + *round = Some(WorkflowRound { + at, + document_asset_id: doc.asset_id, + base_revision: revision, + base_state: state, + recognize_dto: None, + recognize_state: None, + separate_dto: None, + separate_state: None, + backfill_errors: Vec::new(), + outcome: RoundOutcome::Open, + }); + } + CheckpointLine::Recognize { dto, state, .. } => { + if let Some(round) = round.as_mut() { + round.recognize_dto = Some(dto); + round.recognize_state = state; + } + } + CheckpointLine::Separate { + dto, + state, + backfill_errors, + .. + } => { + if let Some(round) = round.as_mut() { + round.separate_dto = Some(dto); + round.separate_state = state; + round.backfill_errors = backfill_errors; + } + } + CheckpointLine::WriteBack { revision, .. } => { + if let Some(round) = round.as_mut() { + if round.outcome == RoundOutcome::Open { + round.outcome = RoundOutcome::WrittenBack { revision }; + } + } + } + CheckpointLine::Outdated { reason, .. } => { + if let Some(round) = round.as_mut() { + if round.outcome == RoundOutcome::Open { + round.outcome = RoundOutcome::Outdated { reason }; + } + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + fn log_path(directory: &tempfile::TempDir) -> PathBuf { + workflow_log_path(directory.path(), "ui/UI 设计 1.json").expect("workflow log path") + } + + fn log(directory: &tempfile::TempDir) -> WorkflowLog { + WorkflowLog::open(directory.path(), "ui/UI 设计 1.json").expect("open workflow log") + } + + fn run_line(at: u64, revision: u64) -> CheckpointLine { + CheckpointLine::Run { + at, + doc: CheckpointDocument { + asset_id: "generated-1-1".to_string(), + }, + revision, + state: json!({ "ui_trees": [] }), + } + } + + #[test] + fn log_path_sits_next_to_the_document() { + let directory = tempfile::tempdir().expect("temp dir"); + assert_eq!( + workflow_log_path(directory.path(), "ui/UI 设计 1.json").expect("path"), + directory + .path() + .join("ui") + .join(".UI 设计 1-workflow.jsonl") + ); + } + + #[test] + fn open_round_reports_recorded_steps() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log(&directory); + assert!(log.last_round().expect("empty log").is_none()); + log.append(&run_line(10, 3)).expect("append run"); + log.append(&CheckpointLine::Recognize { + at: 11, + dto: json!({ "ui_trees": [{ "src_ui_design": "page" }] }), + state: None, + }) + .expect("append recognize"); + let round = log.last_round().expect("scan").expect("round"); + assert_eq!(round.base_revision, 3); + assert_eq!(round.document_asset_id, "generated-1-1"); + assert!(round.recognize_dto.is_some()); + assert!(round.recognize_state.is_none()); + assert!(round.separate_dto.is_none()); + assert_eq!(round.outcome, RoundOutcome::Open); + } + + #[test] + fn step_snapshots_and_backfill_errors_round_trip() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log(&directory); + log.append(&run_line(10, 1)).expect("append run"); + log.append(&CheckpointLine::Recognize { + at: 11, + dto: json!({ "ui_trees": [] }), + state: Some(json!({ "ui_trees": [], "recognized": true })), + }) + .expect("append recognize"); + log.append(&CheckpointLine::Separate { + at: 12, + dto: json!({ "bound_nodes": [], "problematic_nodes": [] }), + state: Some(json!({ "ui_trees": [], "recognized": true, "separated": true })), + backfill_errors: vec!["素材缺失：assets/cut-1.png".to_string()], + }) + .expect("append separate"); + + let round = log.last_round().expect("scan").expect("round"); + assert_eq!( + round.recognize_state, + Some(json!({ "ui_trees": [], "recognized": true })) + ); + assert_eq!( + round.separate_state, + Some(json!({ "ui_trees": [], "recognized": true, "separated": true })) + ); + assert_eq!( + round.backfill_errors, + vec!["素材缺失：assets/cut-1.png".to_string()] + ); + } + + #[test] + fn legacy_lines_without_step_snapshots_still_parse() { + let directory = tempfile::tempdir().expect("temp dir"); + std::fs::create_dir_all(log_path(&directory).parent().expect("parent")) + .expect("create dir"); + // 旧版日志只有 dto、没有状态快照：必须仍然可读，缺失的步骤由调用方按未完成处理。 + std::fs::write( + log_path(&directory), + concat!( + "{\"type\":\"run\",\"at\":1,\"doc\":{\"assetId\":\"generated-1-1\"},\"revision\":3,", + "\"state\":{\"ui_trees\":[]}}\n", + "{\"type\":\"recognize\",\"at\":2,\"dto\":{\"ui_trees\":[]}}\n", + "{\"type\":\"separate\",\"at\":3,\"dto\":{\"bound_nodes\":[],\"problematic_nodes\":[]}}\n", + ), + ) + .expect("write legacy log"); + + let round = log(&directory) + .last_round() + .expect("legacy log parses") + .expect("round"); + assert!(round.recognize_dto.is_some()); + assert!(round.recognize_state.is_none()); + assert!(round.separate_dto.is_some()); + assert!(round.separate_state.is_none()); + assert!(round.backfill_errors.is_empty()); + } + + #[test] + fn later_rounds_shadow_earlier_ones() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log(&directory); + log.append(&run_line(10, 1)).expect("append run"); + log.append(&CheckpointLine::WriteBack { + at: 11, + revision: 2, + }) + .expect("append write back"); + log.append(&run_line(20, 2)).expect("append second run"); + log.append(&CheckpointLine::Outdated { + at: 21, + reason: "doc-revision-drift".to_string(), + }) + .expect("append outdated"); + let round = log.last_round().expect("scan").expect("round"); + assert_eq!(round.base_revision, 2); + assert_eq!( + round.outcome, + RoundOutcome::Outdated { + reason: "doc-revision-drift".to_string(), + } + ); + } + + #[test] + fn written_back_round_is_closed() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log(&directory); + log.append(&run_line(10, 1)).expect("append run"); + log.append(&CheckpointLine::WriteBack { + at: 11, + revision: 2, + }) + .expect("append write back"); + let round = log.last_round().expect("scan").expect("round"); + assert_eq!(round.outcome, RoundOutcome::WrittenBack { revision: 2 }); + } + + #[test] + fn half_written_line_is_dropped_on_append() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log(&directory); + log.append(&run_line(10, 1)).expect("append run"); + { + let mut file = OpenOptions::new() + .append(true) + .open(log_path(&directory)) + .expect("open raw log"); + file.write_all(b"{\"type\":\"separate\",\"at\":12,\"dt") + .expect("write torn tail"); + } + let round = log.last_round().expect("scan").expect("round"); + assert!(round.separate_dto.is_none()); + assert_eq!(round.outcome, RoundOutcome::Open); + log.append(&CheckpointLine::WriteBack { + at: 13, + revision: 2, + }) + .expect("append after torn tail"); + let round = log.last_round().expect("scan").expect("round"); + assert_eq!(round.outcome, RoundOutcome::WrittenBack { revision: 2 }); + let content = std::fs::read_to_string(log_path(&directory)).expect("read log"); + assert!(!content.contains("\"dt")); + assert!(content.ends_with('\n')); + } + + #[test] + fn malformed_complete_line_fails_closed() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log(&directory); + std::fs::create_dir_all(log_path(&directory).parent().expect("parent")) + .expect("create dir"); + std::fs::write(log_path(&directory), "{\"type\":\"nonsense\"}\n").expect("write bad line"); + assert!(log.last_round().is_err()); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/creation.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/creation.rs new file mode 100644 index 000000000..7ba5f227f --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/creation.rs @@ -0,0 +1,391 @@ +use crate::ui_editor::persistence::{ + initialize_ui_design_state_with_images_at, UiDesignDocumentImage, UI_DESIGN_DOC_MEDIA_TYPE, + UI_DESIGN_STATE_MAX_IMAGES, +}; +use crate::{ + acquire_project_write_lock, advance_agent_runtime_project_revision_locked, + enforce_project_permission_policy, ensure_game_creator_private_directory_tree, + harden_new_game_creator_private_path, normalize_relative_path, + prepare_game_creator_private_path_for_read, read_existing_manifest_for_project, + register_local_asset_at, resolve_local_project_path, write_manifest, GameCreationAppAssetKind, + GameCreationAppAssetManifestEntry, GameCreationAppAssetSource, GameCreationAppAssetSourceKind, + GameCreationAppManifest, +}; +use image::GenericImageView; +use serde::{Deserialize, Serialize}; +use std::collections::BTreeSet; +use std::fs; +use std::path::Path; + +/// 一张设计图的输入引用：给已登记资源的 `assetId`，或给项目内相对路径。 +#[derive(Clone, Debug, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +pub(crate) struct UiDesignImageReference { + pub(crate) asset_id: Option, + pub(crate) path: Option, +} + +#[derive(Clone, Debug, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +pub(crate) struct CreateUiDesignDocFromImagesInput { + pub(crate) project_path: String, + pub(crate) expected_project_id: String, + pub(crate) images: Vec, +} + +#[derive(Clone, Debug, PartialEq, Serialize)] +#[serde(rename_all = "camelCase")] +pub(crate) struct UiDesignDocCreated { + pub(crate) asset: GameCreationAppAssetManifestEntry, + pub(crate) manifest: GameCreationAppManifest, + pub(crate) relative_path: String, + pub(crate) image_ids: Vec, + pub(crate) committed_project_revision: u64, +} + +/// 每次调用都新建一份 UI 设计文档：不做「原型 → 已存在文档」的复用查找。 +pub(crate) fn create_ui_design_doc_from_images( + input: CreateUiDesignDocFromImagesInput, +) -> Result { + let root = Path::new(input.project_path.trim()); + let expected_project_id = input.expected_project_id.trim(); + enforce_project_permission_policy(root, "asset.register")?; + if input.images.is_empty() { + return Err("至少需要一张设计图".to_string()); + } + if input.images.len() > UI_DESIGN_STATE_MAX_IMAGES { + return Err(format!( + "一份 UI 设计文档最多 {UI_DESIGN_STATE_MAX_IMAGES} 张设计图" + )); + } + let _lock = acquire_project_write_lock(root, "asset.register")?; + let manifest = read_existing_manifest_for_project(root)?; + if manifest.project_id != expected_project_id { + return Err("project-identity-conflict".to_string()); + } + let (images, registered_image_ids) = prepare_design_images(root, &manifest, &input.images)?; + let (resource_name, relative_path) = next_ui_design_path(root, &manifest)?; + let absolute_path = create_ui_design_document_file(root, &relative_path)?; + let asset = match register_local_asset_at( + root, + &relative_path, + GameCreationAppAssetKind::UiDesignDoc, + UI_DESIGN_DOC_MEDIA_TYPE, + "generated", + GameCreationAppAssetSource { + kind: GameCreationAppAssetSourceKind::Generated, + canvas_project_id: None, + resource_id: Some(format!( + "ui:{}", + resource_name.trim_start_matches("UI 设计 ") + )), + asset_object_id: None, + task_id: None, + prompt: None, + model: None, + generation_route: None, + generation_kind: None, + reference_resource_ids: Vec::new(), + }, + ) { + Ok(asset) => asset, + Err(error) => { + let _ = fs::remove_file(&absolute_path); + // 文档没登记成功时，本次顺带登记的设计图也不该留在 manifest 里。 + return match drop_manifest_assets(root, &[], ®istered_image_ids) { + Ok(()) => Err(error), + Err(rollback_error) => Err(format!( + "UI 设计文档登记失败：{error}；reconciliation-required: 回滚未完成：{rollback_error}" + )), + }; + } + }; + if let Err(error) = + initialize_ui_design_state_with_images_at(root, expected_project_id, &asset.id, &images) + { + return match rollback_created_document(root, &asset.id, ®istered_image_ids, &absolute_path) + { + Ok(()) => Err(error), + Err(rollback_error) => Err(format!( + "UI 设计文档初始化失败：{error}；reconciliation-required: 回滚未完成：{rollback_error}" + )), + }; + } + let committed_project_revision = + advance_agent_runtime_project_revision_locked(root).map_err(|error| { + format!("reconciliation-required: UI 设计文档已创建，但项目 revision 未能推进：{error}") + })?; + let manifest = read_existing_manifest_for_project(root)?; + let asset = manifest + .assets + .iter() + .find(|entry| entry.id == asset.id) + .cloned() + .ok_or_else(|| "UI 设计文档创建后无法从 manifest 回读".to_string())?; + Ok(UiDesignDocCreated { + asset, + manifest, + relative_path, + image_ids: images.into_iter().map(|image| image.image_id).collect(), + committed_project_revision, + }) +} + +/// 只读校验出来的设计图引用：资源身份已确定，但还没写 manifest。 +enum ResolvedDesignImage { + /// manifest 里已有这张图片，本次直接复用它的资源身份。 + Registered { + asset_id: String, + relative_path: String, + pixel_size: (u32, u32), + }, + /// 本次调用需要新登记的设计图，登记后才有 assetId。 + Pending { + relative_path: String, + pixel_size: (u32, u32), + media_type: &'static str, + }, +} + +impl ResolvedDesignImage { + /// 同批次查重键：已登记图片按资源身份，待登记图片按归一化路径。 + fn identity(&self) -> String { + match self { + ResolvedDesignImage::Registered { asset_id, .. } => asset_id.clone(), + ResolvedDesignImage::Pending { relative_path, .. } => { + format!("path:{relative_path}") + } + } + } +} + +/// 先整批校验、再登记，任何一张不合法都不会在 manifest 里留下无人引用的图片条目。 +fn prepare_design_images( + root: &Path, + manifest: &GameCreationAppManifest, + references: &[UiDesignImageReference], +) -> Result<(Vec, Vec), String> { + let mut resolved = Vec::with_capacity(references.len()); + let mut seen = BTreeSet::new(); + for reference in references { + let image = resolve_design_image(root, manifest, reference)?; + if !seen.insert(image.identity()) { + return Err("同一次调用不能重复登记同一张设计图".to_string()); + } + resolved.push(image); + } + let mut images = Vec::with_capacity(resolved.len()); + let mut registered_ids = Vec::new(); + for image in resolved { + let (asset_id, relative_path, pixel_size) = match image { + ResolvedDesignImage::Registered { + asset_id, + relative_path, + pixel_size, + } => (asset_id, relative_path, pixel_size), + ResolvedDesignImage::Pending { + relative_path, + pixel_size, + media_type, + } => { + let registered = register_local_asset_at( + root, + &relative_path, + GameCreationAppAssetKind::UiDesign, + media_type, + "ui-design", + GameCreationAppAssetSource { + kind: GameCreationAppAssetSourceKind::Uploaded, + canvas_project_id: None, + resource_id: None, + asset_object_id: None, + task_id: None, + prompt: None, + model: None, + generation_route: None, + generation_kind: None, + reference_resource_ids: Vec::new(), + }, + )?; + registered_ids.push(registered.id.clone()); + (registered.id, relative_path, pixel_size) + } + }; + images.push(UiDesignDocumentImage { + image_id: asset_id, + path: relative_path, + pixel_size, + }); + } + Ok((images, registered_ids)) +} + +/// 解析一张设计图引用并读取它的真实尺寸：只读，不写 manifest。 +fn resolve_design_image( + root: &Path, + manifest: &GameCreationAppManifest, + reference: &UiDesignImageReference, +) -> Result { + let (asset_id, relative_path, media_type): (Option, String, Option<&'static str>) = + match (reference.asset_id.as_deref(), reference.path.as_deref()) { + (Some(asset_id), None) => { + let asset_id = asset_id.trim(); + let asset = manifest + .assets + .iter() + .find(|asset| asset.id == asset_id) + .ok_or_else(|| format!("设计图资源不存在：{asset_id}"))?; + require_image_media_type(&asset.media_type)?; + (Some(asset.id.clone()), asset.local_path.clone(), None) + } + (None, Some(path)) => { + let normalized_path = normalize_relative_path(path.trim())?; + match manifest + .assets + .iter() + .find(|asset| asset.local_path == normalized_path) + { + // 已登记图片复用原资源身份，不因为本次调用改写它的 kind 与分类。 + Some(existing) => { + require_image_media_type(&existing.media_type)?; + (Some(existing.id.clone()), existing.local_path.clone(), None) + } + None => { + let absolute_path = resolve_local_project_path(root, &normalized_path)?; + let media_type = design_image_media_type(&absolute_path)?; + (None, normalized_path, Some(media_type)) + } + } + } + _ => return Err("每张设计图必须且只能给 assetId 或 path".to_string()), + }; + let absolute_path = resolve_local_project_path(root, &relative_path)?; + let pixel_size = image::open(&absolute_path) + .map_err(|error| format!("读取设计图失败：{relative_path}：{error}"))? + .dimensions(); + if pixel_size.0 == 0 || pixel_size.1 == 0 { + return Err(format!("设计图尺寸无效：{relative_path}")); + } + match (asset_id, media_type) { + (Some(asset_id), _) => Ok(ResolvedDesignImage::Registered { + asset_id, + relative_path, + pixel_size, + }), + (None, Some(media_type)) => Ok(ResolvedDesignImage::Pending { + relative_path, + pixel_size, + media_type, + }), + // 上面两条已覆盖 (assetId) 与 (path 未登记) 两种解析结果。 + (None, None) => Err("每张设计图必须且只能给 assetId 或 path".to_string()), + } +} + +fn require_image_media_type(media_type: &str) -> Result<(), String> { + if media_type.to_ascii_lowercase().starts_with("image/") { + Ok(()) + } else { + Err("设计图必须是图片资源".to_string()) + } +} + +fn design_image_media_type(absolute_path: &Path) -> Result<&'static str, String> { + let format = image::ImageFormat::from_path(absolute_path) + .map_err(|error| format!("无法识别设计图格式：{}：{error}", absolute_path.display()))?; + match format { + image::ImageFormat::Png => Ok("image/png"), + image::ImageFormat::Jpeg => Ok("image/jpeg"), + image::ImageFormat::Gif => Ok("image/gif"), + image::ImageFormat::WebP => Ok("image/webp"), + image::ImageFormat::Bmp => Ok("image/bmp"), + _ => Err("设计图只支持 png/jpeg/gif/webp/bmp".to_string()), + } +} + +fn create_ui_design_document_file( + root: &Path, + relative_path: &str, +) -> Result { + let absolute_path = resolve_local_project_path(root, relative_path)?; + if let Some(parent) = absolute_path.parent() { + ensure_game_creator_private_directory_tree(parent, "UI 资源目录")?; + prepare_game_creator_private_path_for_read(parent, true, "UI 资源目录")?; + } + if prepare_game_creator_private_path_for_read(&absolute_path, false, "UI 资源")? { + return Err("UI 设计资源路径已存在，拒绝覆盖".to_string()); + } + let mut options = fs::OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(windows)] + { + use std::os::windows::fs::OpenOptionsExt; + options.custom_flags(crate::PROJECT_FILE_FLAG_OPEN_REPARSE_POINT); + } + let file = options + .open(&absolute_path) + .map_err(|error| format!("创建 UI 资源失败：{}：{error}", absolute_path.display()))?; + if let Err(error) = harden_new_game_creator_private_path(&absolute_path, false, "UI 资源") { + drop(file); + let _ = fs::remove_file(&absolute_path); + return Err(error); + } + drop(file); + Ok(absolute_path) +} + +fn rollback_created_document( + root: &Path, + asset_id: &str, + registered_image_ids: &[String], + absolute_path: &Path, +) -> Result<(), String> { + drop_manifest_assets(root, &[asset_id], registered_image_ids)?; + fs::remove_file(absolute_path).map_err(|error| format!("删除未完成 UI 设计资源失败：{error}")) +} + +/// 把本次新建或新登记、但已判定失败的资源条目从 manifest 里摘掉。 +fn drop_manifest_assets( + root: &Path, + asset_ids: &[&str], + registered_image_ids: &[String], +) -> Result<(), String> { + let mut manifest = read_existing_manifest_for_project(root)?; + manifest.assets.retain(|entry| { + !asset_ids.contains(&entry.id.as_str()) && !registered_image_ids.contains(&entry.id) + }); + write_manifest(&root.join(".agent/manifest.json"), &manifest) +} + +/// UI 设计文档的确定性命名：从已登记文档数 + 1 起找第一个既未被占用、 +/// 也未登记进 manifest 的 `ui/UI 设计 N.json`，不覆盖任何既有文件。 +pub(crate) fn next_ui_design_path( + root: &Path, + manifest: &GameCreationAppManifest, +) -> Result<(String, String), String> { + let mut index = manifest + .assets + .iter() + .filter(|asset| { + asset.kind == GameCreationAppAssetKind::UiDesignDoc + && asset.media_type == UI_DESIGN_DOC_MEDIA_TYPE + }) + .count() + + 1; + loop { + let resource_name = format!("UI 设计 {index}"); + let relative_path = format!("ui/{resource_name}.json"); + let path = resolve_local_project_path(root, &relative_path)?; + if !path.exists() + && !manifest + .assets + .iter() + .any(|asset| asset.local_path == relative_path) + { + return Ok((resource_name, relative_path)); + } + index = index + .checked_add(1) + .ok_or_else(|| "UI 设计资源编号已达到上限".to_string())?; + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/mod.rs new file mode 100644 index 000000000..bc1a69b82 --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/mod.rs @@ -0,0 +1,13 @@ +mod checkpoint; +mod creation; +mod run_workflow; +mod steps; + +#[cfg(test)] +mod test_support; + +pub(crate) use creation::{ + create_ui_design_doc_from_images, CreateUiDesignDocFromImagesInput, UiDesignDocCreated, + UiDesignImageReference, +}; +pub(crate) use run_workflow::{run_ui_design_doc_workflow, RunUiDesignDocWorkflowInput}; diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/run_workflow.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/run_workflow.rs new file mode 100644 index 000000000..a92e00b21 --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/run_workflow.rs @@ -0,0 +1,429 @@ +//! `ui-design-doc.run-workflow` 的编排：`recognize` → `separate` → `write-back`， +//! 以及基于 JSONL 检查点的崩溃恢复。 +//! +//! 每步只做自己的事：识别结果落 State、切分结果落 State、最后写回文档。恢复判据 +//! 只有一条——这一步有没有对应的检查点行；文档中途漂移时追加 `outdated` 并报错， +//! 不在同一次调用里自动重开新一轮。 + +use super::checkpoint::{ + checkpoint_timestamp, CheckpointDocument, CheckpointLine, RoundOutcome, WorkflowLog, + WorkflowRound, +}; +use super::steps::recognize::apply_recognition; +use super::steps::separate::{add_sprite_assets, apply_separation, register_cut_image_sprites}; +use super::steps::write_back::{ + checkpoint_drift_message, record_write_back, WriteBackTarget, DRIFT_REASON, +}; +use crate::enforce_project_permission_policy; +use crate::ui_editor::commands::separation::finalize_separation; +use crate::ui_editor::commands::{ + recognize_ui_impl_with_provider, separate_ui_impl, RecognitionDTO, SeparationDTO, +}; +use crate::ui_editor::persistence::{load_ui_design_document_snapshot_at, UiDesignStateSnapshot}; +use crate::ui_editor::state::State; +use serde::{Deserialize, Serialize}; +use serde_json::Value; +use std::path::Path; + +#[derive(Clone, Debug, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +pub(crate) struct RunUiDesignDocWorkflowInput { + pub(crate) project_path: String, + pub(crate) expected_project_id: String, + pub(crate) asset_id: String, +} + +#[derive(Clone, Debug, PartialEq, Serialize)] +#[serde(rename_all = "camelCase")] +pub(crate) struct RunUiDesignDocWorkflowOutput { + pub(crate) asset_id: String, + pub(crate) relative_path: String, + pub(crate) revision: u64, + pub(crate) recovered_from_checkpoint: bool, + pub(crate) recognized_tree_count: usize, + pub(crate) bound_node_count: usize, + pub(crate) problematic_node_count: usize, + pub(crate) backfill_errors: Vec, +} + +/// 一轮已经推进到哪一步：已记录的 DTO 直接复用，缺失的步骤才真正执行。 +struct WorkflowProgress { + state: State, + recorded_recognize: Option, + recorded_separate: Option, + backfill_errors: Vec, + /// 文档已经是重建出的目标 State，只差补 `write-back` 行。 + already_written_back: bool, +} + +pub(crate) async fn run_ui_design_doc_workflow( + input: RunUiDesignDocWorkflowInput, + provider_identity: Option<(&str, &str)>, +) -> Result { + let root = Path::new(input.project_path.trim()); + // 与 Runtime 工具策略的命令映射一致：本工具等价于登记资源 + 写回 State。 + enforce_project_permission_policy(root, "asset.register")?; + let (relative_path, snapshot) = + load_ui_design_document_snapshot_at(root, &input.expected_project_id, &input.asset_id)?; + let log = WorkflowLog::open(root, &relative_path)?; + let resume = log + .last_round()? + .filter(|round| round.outcome == RoundOutcome::Open); + let recovered_from_checkpoint = resume.is_some(); + let mut progress = match &resume { + Some(round) => resume_progress(&log, &snapshot, round, &input.asset_id)?, + None => { + let state = snapshot.state.clone(); + log.append(&CheckpointLine::Run { + at: checkpoint_timestamp(), + doc: CheckpointDocument { + asset_id: input.asset_id.clone(), + }, + revision: snapshot.revision, + state: to_checkpoint_value(&state)?, + })?; + WorkflowProgress { + state, + recorded_recognize: None, + recorded_separate: None, + backfill_errors: Vec::new(), + already_written_back: false, + } + } + }; + + let recognize_dto = match progress.recorded_recognize.take() { + // 这一步上一轮已经做完：State 随检查点一起恢复，整步跳过，不再重放它的 delta。 + Some(dto) => dto, + None => { + let dto = recognize_ui_impl_with_provider( + input.project_path.trim().to_string(), + progress.state.clone(), + provider_identity, + ) + .await?; + apply_recognition(&mut progress.state, &dto)?; + log.append(&CheckpointLine::Recognize { + at: checkpoint_timestamp(), + dto: to_checkpoint_value(&dto)?, + state: Some(to_checkpoint_value(&progress.state)?), + })?; + dto + } + }; + + let separate_dto = match progress.recorded_separate.take() { + Some(dto) => dto, + None => { + let dto = separate_ui_impl( + input.project_path.trim().to_string(), + input.asset_id.clone(), + progress.state.clone(), + ) + .await?; + // 切图登记按路径复用 manifest 条目；失败只回报说明，不回滚已登记资源。 + let cut_images = register_cut_image_sprites(root, &dto)?; + let mut backfill_errors = cut_images.errors; + progress.state = add_sprite_assets(&progress.state, &cut_images.sprites)?; + backfill_errors.extend(apply_separation( + &mut progress.state, + &dto, + &cut_images.by_path, + )); + progress.backfill_errors = backfill_errors; + log.append(&CheckpointLine::Separate { + at: checkpoint_timestamp(), + dto: to_checkpoint_value(&dto)?, + state: Some(to_checkpoint_value(&progress.state)?), + backfill_errors: progress.backfill_errors.clone(), + })?; + dto + } + }; + + let revision = if progress.already_written_back { + record_write_back(&log, snapshot.revision)?; + snapshot.revision + } else { + WriteBackTarget { + project_path: input.project_path.trim(), + expected_project_id: &input.expected_project_id, + asset_id: &input.asset_id, + } + .commit(&log, snapshot.revision, &progress.state)? + }; + // 与前端切分链路一致：干净跑完才清理 sidecar；有回填问题或问题节点时保留， + // 交给编辑器显示恢复入口。切分 op 内部的细粒度进度仍由 SeparationState 承担。 + if progress.backfill_errors.is_empty() && separate_dto.problematic_nodes.is_empty() { + finalize_separation(root, &input.asset_id)?; + } + Ok(RunUiDesignDocWorkflowOutput { + asset_id: input.asset_id, + relative_path, + revision, + recovered_from_checkpoint, + recognized_tree_count: recognize_dto.ui_trees.len(), + bound_node_count: separate_dto.bound_nodes.len(), + problematic_node_count: separate_dto.problematic_nodes.len(), + backfill_errors: progress.backfill_errors, + }) +} + +/// 恢复一轮未完成的工作流。 +/// +/// 已完成的步骤只从检查点取结果：State 直接读回那一步的快照，整步不再重放，所以 +/// 既不会重复登记切图，也不会把回填说明重复累加进本轮报告。文档等于切分后那份 +/// State 说明上一轮已经写回、只差 `write-back` 行；文档既不等于本轮起点、也不等于 +/// 切分后 State 时判漂移并追加 `outdated`。 +fn resume_progress( + log: &WorkflowLog, + snapshot: &UiDesignStateSnapshot, + round: &WorkflowRound, + asset_id: &str, +) -> Result { + if round.document_asset_id != asset_id { + return Err(format!( + "工作流检查点属于其它 UI 设计文档（{}），拒绝按本轮恢复", + round.document_asset_id + )); + } + let base_state: State = serde_json::from_value(round.base_state.clone()) + .map_err(|error| format!("工作流检查点的起始 State 无法还原：{error}"))?; + let mut progress = WorkflowProgress { + state: base_state.clone(), + recorded_recognize: None, + recorded_separate: None, + backfill_errors: Vec::new(), + already_written_back: false, + }; + // 只认「带状态快照」的步骤为已完成：旧日志没有快照，按没做过处理，让主流程重跑那一步。 + if let (Some(dto), Some(state)) = (&round.recognize_dto, &round.recognize_state) { + progress.state = serde_json::from_value(state.clone()) + .map_err(|error| format!("工作流检查点的识别后 State 无法还原：{error}"))?; + progress.recorded_recognize = Some( + serde_json::from_value::(dto.clone()) + .map_err(|error| format!("工作流检查点的识别结果无法还原：{error}"))?, + ); + } + // 切分后的 State 已经含识别结果，只有识别那步也认下来了才用它接着走。 + if progress.recorded_recognize.is_some() { + if let (Some(dto), Some(state)) = (&round.separate_dto, &round.separate_state) { + progress.state = serde_json::from_value(state.clone()) + .map_err(|error| format!("工作流检查点的切分后 State 无法还原：{error}"))?; + progress.recorded_separate = Some( + serde_json::from_value::(dto.clone()) + .map_err(|error| format!("工作流检查点的切分结果无法还原：{error}"))?, + ); + progress.backfill_errors = round.backfill_errors.clone(); + } + } + if progress.recorded_separate.is_some() && snapshot.state == progress.state { + progress.already_written_back = true; + return Ok(progress); + } + if snapshot.state != base_state { + log.append(&CheckpointLine::Outdated { + at: checkpoint_timestamp(), + reason: DRIFT_REASON.to_string(), + })?; + return Err(checkpoint_drift_message(snapshot.revision, round)); + } + Ok(progress) +} + +fn to_checkpoint_value(value: &T) -> Result { + serde_json::to_value(value).map_err(|error| format!("序列化工作流检查点行失败：{error}")) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::ui_editor::agent_tools::checkpoint::workflow_log_path; + use serde_json::json; + + const ASSET_ID: &str = "generated-1-1"; + + fn design_image(path: &str) -> Value { + json!({ "path": path, "pixel_size": [100.0, 80.0], "pixels_per_unit": 1.0 }) + } + + /// 用界面图条目当进度标记：出现 `marker` 那张图就说明对应步骤的 State 已经拿到。 + fn state_with_marker(marker: Option<&str>) -> Value { + let mut images = serde_json::Map::new(); + images.insert("page".to_string(), design_image("assets/page.png")); + if let Some(marker) = marker { + images.insert( + marker.to_string(), + design_image(&format!("assets/{marker}.png")), + ); + } + json!({ + "ui_trees": [], + "ui_design_images": images, + "sprite_assets": {}, + "font_assets": {}, + }) + } + + fn snapshot_with(state: Value) -> UiDesignStateSnapshot { + UiDesignStateSnapshot { + revision: 7, + state: serde_json::from_value(state).expect("deserialize snapshot state"), + } + } + + fn log_lines(directory: &tempfile::TempDir, lines: &[CheckpointLine]) -> WorkflowLog { + let log = WorkflowLog::open(directory.path(), "ui/UI 设计 1.json").expect("open log"); + for line in lines { + log.append(line).expect("append line"); + } + log + } + + fn run_line() -> CheckpointLine { + CheckpointLine::Run { + at: 1, + doc: CheckpointDocument { + asset_id: ASSET_ID.to_string(), + }, + revision: 7, + state: state_with_marker(None), + } + } + + fn raw_log(directory: &tempfile::TempDir) -> String { + std::fs::read_to_string( + workflow_log_path(directory.path(), "ui/UI 设计 1.json").expect("log path"), + ) + .expect("read log") + } + + #[test] + fn resume_takes_state_from_checkpoint_without_replaying_recorded_steps() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log_lines( + &directory, + &[ + run_line(), + CheckpointLine::Recognize { + at: 2, + dto: json!({ "ui_trees": [] }), + state: Some(state_with_marker(Some("recognized"))), + }, + CheckpointLine::Separate { + at: 3, + dto: json!({ "bound_nodes": [], "problematic_nodes": [] }), + state: Some(state_with_marker(Some("separated"))), + backfill_errors: vec!["素材缺失：assets/cut-1.png".to_string()], + }, + ], + ); + let round = log.last_round().expect("scan").expect("round"); + + let progress = resume_progress( + &log, + &snapshot_with(state_with_marker(None)), + &round, + ASSET_ID, + ) + .expect("resume open round"); + + // 状态直接来自检查点里切分那一步的快照，识别与切分都不会被重放。 + let state = serde_json::to_value(&progress.state).expect("state json"); + assert!(state["ui_design_images"].get("separated").is_some()); + assert!(progress.recorded_recognize.is_some()); + assert!(progress.recorded_separate.is_some()); + assert_eq!( + progress.backfill_errors, + vec!["素材缺失：assets/cut-1.png".to_string()] + ); + assert!(!progress.already_written_back); + assert!(!raw_log(&directory).contains("outdated")); + } + + #[test] + fn resume_reports_already_written_back_when_document_holds_the_separated_state() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log_lines( + &directory, + &[ + run_line(), + CheckpointLine::Recognize { + at: 2, + dto: json!({ "ui_trees": [] }), + state: Some(state_with_marker(Some("recognized"))), + }, + CheckpointLine::Separate { + at: 3, + dto: json!({ "bound_nodes": [], "problematic_nodes": [] }), + state: Some(state_with_marker(Some("separated"))), + backfill_errors: Vec::new(), + }, + ], + ); + let round = log.last_round().expect("scan").expect("round"); + + let progress = resume_progress( + &log, + &snapshot_with(state_with_marker(Some("separated"))), + &round, + ASSET_ID, + ) + .expect("resume written back round"); + + assert!(progress.already_written_back); + assert!(progress.recorded_separate.is_some()); + } + + #[test] + fn resume_treats_steps_without_state_snapshots_as_unfinished() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log_lines( + &directory, + &[ + run_line(), + CheckpointLine::Recognize { + at: 2, + dto: json!({ "ui_trees": [] }), + state: None, + }, + ], + ); + let round = log.last_round().expect("scan").expect("round"); + + let progress = resume_progress( + &log, + &snapshot_with(state_with_marker(None)), + &round, + ASSET_ID, + ) + .expect("resume legacy round"); + + // 旧日志只有识别结果、没有状态快照：整步按没做过处理，由主流程重跑。 + assert!(progress.recorded_recognize.is_none()); + assert!(progress.recorded_separate.is_none()); + let state = serde_json::to_value(&progress.state).expect("state json"); + assert!(state["ui_design_images"].get("recognized").is_none()); + assert!(!progress.already_written_back); + } + + #[test] + fn resume_marks_round_outdated_when_document_drifted() { + let directory = tempfile::tempdir().expect("temp dir"); + let log = log_lines(&directory, &[run_line()]); + let round = log.last_round().expect("scan").expect("round"); + + let error = match resume_progress( + &log, + &snapshot_with(state_with_marker(Some("edited"))), + &round, + ASSET_ID, + ) { + Ok(_) => panic!("漂移的文档必须拒绝恢复"), + Err(error) => error, + }; + + assert!(error.contains("中途被改动"), "{error}"); + assert!(raw_log(&directory).contains("outdated")); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/mod.rs new file mode 100644 index 000000000..ac33a38df --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/mod.rs @@ -0,0 +1,3 @@ +pub(crate) mod recognize; +pub(crate) mod separate; +pub(crate) mod write_back; diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/recognize.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/recognize.rs new file mode 100644 index 000000000..0b2925366 --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/recognize.rs @@ -0,0 +1,126 @@ +//! 结构识别结果落到 State。镜像前端 `features/ui-editor/recognition.ts` 的 +//! `applyRecognitionResult` 与 `features/ui-editor/useUiEditorState.ts` 的 +//! `createTree` / `deriveTreeOffset` / `treeSize`。 + +use crate::ui_editor::commands::RecognitionDTO; +use crate::ui_editor::layout::offset::NodeOffset; +use crate::ui_editor::state::{State, UITree}; +use crate::ui_editor::utils::UIDesignImageId; + +/// 树与树之间的横向间距，与前端 `UI_TREE_PADDING` 一致。 +pub(crate) const UI_TREE_PADDING: f32 = 48.0; + +/// 识别结果是整棵结构草稿树的替换结果，不与旧树逐节点合并；每棵树按 DTO 顺序 +/// 依次重新推导横向偏移，所以先落位的树会把后面的树推到右边。 +pub(crate) fn apply_recognition(state: &mut State, dto: &RecognitionDTO) -> Result<(), String> { + let recognized = dto.ui_trees.clone(); + state.ui_trees = Vec::with_capacity(recognized.len()); + for tree in recognized { + let UITree { + src_ui_design, + mut root, + } = tree; + root.offset = derive_tree_offset(state, &src_ui_design)?; + state.ui_trees.push(UITree { + src_ui_design, + root, + }); + } + Ok(()) +} + +fn derive_tree_offset(state: &State, tree_id: &UIDesignImageId) -> Result { + let [width, height] = tree_size(state, tree_id)?; + let existing = state + .ui_trees + .iter() + .filter(|tree| &tree.src_ui_design != tree_id) + .collect::>(); + if existing.is_empty() { + return Ok(NodeOffset { + min: [0.0, 0.0], + max: [width, height], + }); + } + let mut max_x = f32::MIN; + let mut min_y = f32::MAX; + for tree in existing { + let [existing_width, _] = tree_size(state, &tree.src_ui_design)?; + max_x = max_x.max(tree.root.offset.min[0] + existing_width); + min_y = min_y.min(tree.root.offset.min[1]); + } + let min_x = max_x + UI_TREE_PADDING; + Ok(NodeOffset { + min: [min_x, min_y], + max: [min_x + width, min_y + height], + }) +} + +fn tree_size(state: &State, tree_id: &UIDesignImageId) -> Result<[f32; 2], String> { + let image = state + .ui_design_images + .get(tree_id) + .ok_or_else(|| format!("界面图 {} 缺少合法尺寸", tree_id.as_str()))?; + let pixels_per_unit = image.pixels_per_unit.get(); + if !pixels_per_unit.is_finite() || pixels_per_unit <= 0.0 { + return Err(format!("界面图 {} 缺少合法尺寸", tree_id.as_str())); + } + Ok([ + image.pixel_size.x / pixels_per_unit, + image.pixel_size.y / pixels_per_unit, + ]) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::ui_editor::agent_tools::test_support::{node, state_with}; + use crate::ui_editor::state::UITree; + + fn dto(trees: &[(&str, &str)]) -> RecognitionDTO { + RecognitionDTO { + ui_trees: trees + .iter() + .map(|(tree_id, node_id)| UITree { + src_ui_design: UIDesignImageId::new(tree_id.to_string()).expect("tree id"), + root: node(node_id), + }) + .collect(), + } + } + + #[test] + fn trees_are_replaced_and_laid_out_left_to_right() { + let mut state = state_with(&[("page-a", 120.0, 80.0), ("page-b", 60.0, 40.0)]); + apply_recognition( + &mut state, + &dto(&[("page-a", "root-a"), ("page-b", "root-b")]), + ) + .expect("apply recognition"); + assert_eq!(state.ui_trees.len(), 2); + assert_eq!(state.ui_trees[0].root.offset.min, [0.0, 0.0]); + assert_eq!(state.ui_trees[0].root.offset.max, [120.0, 80.0]); + assert_eq!(state.ui_trees[1].root.offset.min, [168.0, 0.0]); + assert_eq!(state.ui_trees[1].root.offset.max, [228.0, 40.0]); + } + + #[test] + fn recognition_replaces_the_whole_tree_list() { + let mut state = state_with(&[("page-a", 100.0, 50.0)]); + apply_recognition(&mut state, &dto(&[("page-a", "root-a")])).expect("first apply"); + apply_recognition(&mut state, &dto(&[("page-a", "root-b")])).expect("second apply"); + assert_eq!(state.ui_trees.len(), 1); + assert_eq!(state.ui_trees[0].root.id.as_str(), "root-b"); + } + + #[test] + fn tree_without_design_image_fails() { + let mut state = state_with(&[("page-a", 100.0, 50.0)]); + let error = apply_recognition( + &mut state, + &dto(&[("page-a", "root-a"), ("page-x", "root-x")]), + ) + .expect_err("missing design image must fail"); + assert!(error.contains("page-x")); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/separate/cut_images.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/separate/cut_images.rs new file mode 100644 index 000000000..28997580e --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/separate/cut_images.rs @@ -0,0 +1,158 @@ +//! `separate` sub-step 的资源侧：登记自动切分产出的图片并构造切分素材。镜像前端 +//! `useUiEditorPage.ts` 的 `import_local_project_image_assets` → +//! `prepareSpriteAssetBatch` 两段。 +//! +//! 登记按路径复用已有 manifest 条目，所以重放不会重复登记；登记失败的路径只回报 +//! 说明，不回滚已经登记成功的资源。 + +use super::normalize_cut_image_path; +use crate::import_local_project_assets_for_agent; +use crate::ui_editor::commands::SeparationDTO; +use crate::ui_editor::resource::sprite::SpriteAsset; +use crate::ui_editor::utils::SpriteAssetId; +use crate::{resolve_local_project_path, ImportedAsset}; +use image::GenericImageView; +use nalgebra::Vector2; +use std::collections::HashMap; +use std::path::Path; +use typed_floats::tf32::StrictlyPositiveFinite; + +/// 单批登记上限，与前端 `SEPARATION_IMPORT_BATCH_SIZE` 一致。 +const CUT_IMAGE_IMPORT_BATCH_SIZE: usize = 100; + +pub(crate) struct CutImageSprites { + /// 本次切分产出的素材（按资源 id 去重）。 + pub(crate) sprites: Vec, + /// 切分路径（含导入后回填的路径）到素材的映射，供回填按路径查找。 + pub(crate) by_path: HashMap, + /// 未能登记的路径说明。 + pub(crate) errors: Vec, +} + +pub(crate) fn register_cut_image_sprites( + root: &Path, + dto: &SeparationDTO, +) -> Result { + let unique_paths = unique_cut_image_paths(dto); + if unique_paths.is_empty() { + return Ok(CutImageSprites { + sprites: Vec::new(), + by_path: HashMap::new(), + errors: Vec::new(), + }); + } + let mut imported_by_path: Vec<(String, ImportedAsset)> = Vec::new(); + for batch in unique_paths.chunks(CUT_IMAGE_IMPORT_BATCH_SIZE) { + let imported = import_local_project_assets_for_agent(root, batch)?; + if imported.assets.len() != batch.len() { + return Err(format!( + "本地资源登记结果数量不匹配：请求 {} 个，返回 {} 个", + batch.len(), + imported.assets.len() + )); + } + for (index, asset) in imported.assets.into_iter().enumerate() { + let normalized = normalize_cut_image_path(&asset.local_path); + if let Some(requested) = batch.get(index) { + // 导入可能把文件复制到 assets/uploads，切分路径与素材路径都要能查到。 + imported_by_path.push((requested.clone(), asset.clone())); + } + imported_by_path.push((normalized, asset)); + } + } + let mut errors = Vec::new(); + for path in &unique_paths { + if !imported_by_path + .iter() + .any(|(imported, _)| imported == path) + { + errors.push(format!("未能登记自动切分素材图片：{path}")); + } + } + let mut sprites = Vec::new(); + let mut sprite_by_id: HashMap = HashMap::new(); + for (_, asset) in &imported_by_path { + if sprite_by_id.contains_key(&asset.id) { + continue; + } + let sprite = sprite_from_registered_image(root, asset)?; + sprite_by_id.insert(asset.id.clone(), sprite.clone()); + sprites.push(sprite); + } + let by_path = imported_by_path + .iter() + .filter_map(|(path, asset)| { + sprite_by_id + .get(&asset.id) + .map(|sprite| (path.clone(), sprite.clone())) + }) + .collect(); + Ok(CutImageSprites { + sprites, + by_path, + errors, + }) +} + +/// 按 `bound_nodes` 顺序取去重后的切分路径，镜像前端的 `new Set(map(...))`。 +pub(crate) fn unique_cut_image_paths(dto: &SeparationDTO) -> Vec { + let mut paths = Vec::new(); + for bound in &dto.bound_nodes { + let path = normalize_cut_image_path(&bound.cut_image_path); + if !paths.contains(&path) { + paths.push(path); + } + } + paths +} + +fn sprite_from_registered_image(root: &Path, asset: &ImportedAsset) -> Result { + let absolute_path = resolve_local_project_path(root, &asset.local_path)?; + let dimensions = image::open(&absolute_path) + .map_err(|error| format!("读取自动切分素材失败：{}：{error}", asset.local_path))? + .dimensions(); + if dimensions.0 == 0 || dimensions.1 == 0 { + return Err(format!("自动切分素材尺寸无效：{}", asset.local_path)); + } + let asset_id = SpriteAssetId::new(asset.id.clone()) + .map_err(|error| format!("自动切分素材 ID 无效：{}：{error}", asset.id))?; + let pixels_per_unit = + StrictlyPositiveFinite::new(1.0).map_err(|_| "自动切分素材像素单位无效".to_string())?; + SpriteAsset::from_registered_image( + asset_id, + normalize_cut_image_path(&asset.local_path), + Vector2::new(dimensions.0 as f32, dimensions.1 as f32), + pixels_per_unit, + ) + .map_err(|error| format!("自动切分素材无效：{}：{error}", asset.local_path)) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::ui_editor::commands::separation::BoundNode; + use crate::ui_editor::utils::NodeId; + + fn bound(cut_path: &str) -> BoundNode { + BoundNode { + node_id: NodeId::new("node-a".to_string()).expect("node id"), + cut_image_path: cut_path.to_string(), + } + } + + #[test] + fn unique_paths_normalize_separators_and_drop_duplicates() { + let dto = SeparationDTO { + bound_nodes: vec![ + bound("/ui/cut 1.png"), + bound("ui\\cut 1.png"), + bound("ui/cut 2.png"), + ], + problematic_nodes: Vec::new(), + }; + assert_eq!( + unique_cut_image_paths(&dto), + vec!["ui/cut 1.png".to_string(), "ui/cut 2.png".to_string()] + ); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/separate/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/separate/mod.rs new file mode 100644 index 000000000..8fea30925 --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/separate/mod.rs @@ -0,0 +1,417 @@ +//! `separate` sub-step 的全部落地逻辑，按有无副作用分两个文件： +//! +//! - `cut_images`：按 `bound_nodes` 的路径登记图片并构造 `SpriteAsset`，带项目 +//! manifest 副作用。 +//! - 本文件：登记结果与 `SeparationDTO` 到 State 的纯变换，镜像前端 +//! `useUiEditorPage.ts` 的切分回填循环、`features/ui-editor/useUiEditorState.ts` +//! 的 `addSpriteAssetsToState` 与 `features/ui-editor/separationStatus.ts` 的问题 +//! 状态写回。 + +mod cut_images; + +pub(crate) use cut_images::register_cut_image_sprites; + +use crate::ui_editor::commands::separation::{BoundNode, ProblematicNode}; +use crate::ui_editor::commands::SeparationDTO; +use crate::ui_editor::component::Component; +use crate::ui_editor::layout::node::StageStatus; +use crate::ui_editor::resource::sprite::SpriteAsset; +use crate::ui_editor::state::State; +use crate::ui_editor::utils::SpriteAssetId; +use std::collections::HashMap; + +/// 镜像前端 `normalizeProjectRelativePath`：只做分隔符与根斜杠归一，不做路径校验。 +pub(crate) fn normalize_cut_image_path(path: &str) -> String { + path.replace('\\', "/").trim_start_matches('/').to_string() +} + +/// 把切分产出的素材合入 State。同一 id 已有不同内容时报错，镜像 +/// `addSpriteAssetsToState` 的 `duplicate` 与资源校验。 +pub(crate) fn add_sprite_assets(state: &State, sprites: &[SpriteAsset]) -> Result { + let mut unique: HashMap = HashMap::new(); + for sprite in sprites { + let asset_id = sprite.asset_id().clone(); + let existing = unique + .get(&asset_id) + .copied() + .or_else(|| state.sprite_assets.get(&asset_id)); + if let Some(existing) = existing { + if existing != sprite { + return Err(format!("素材 {} 已存在且内容不同", asset_id.as_str())); + } + } + unique.insert(asset_id, sprite); + } + for sprite in unique.values() { + if let Err(reason) = sprite_asset_error(sprite) { + return Err(format!("{}：{reason}", sprite.asset_id().as_str())); + } + } + let mut next = state.clone(); + for sprite in unique.values() { + next.sprite_assets + .insert(sprite.asset_id().clone(), (*sprite).clone()); + } + Ok(next) +} + +/// 回填切分结果：先按 `bound_nodes` 顺序写 `target_graphic` 并清 +/// `component_status`，再统一写 `problematic_nodes` 的 `NeedReview`。返回值是需要 +/// 人工处理的说明，镜像前端 `backfillErrors`。`state` 必须已经含本次素材。 +pub(crate) fn apply_separation( + state: &mut State, + dto: &SeparationDTO, + sprite_by_path: &HashMap, +) -> Vec { + let mut errors = Vec::new(); + for bound in &dto.bound_nodes { + backfill_bound_node(state, bound, sprite_by_path, &mut errors); + } + errors.extend(apply_problematic_statuses(state, &dto.problematic_nodes)); + errors +} + +/// `problematic_nodes` 的统一回写：节点存在且带 Image 组件时写 `NeedReview`， +/// 否则只保留问题记录并回报。 +pub(crate) fn apply_problematic_statuses( + state: &mut State, + problematic_nodes: &[ProblematicNode], +) -> Vec { + let mut errors = Vec::new(); + for problematic in problematic_nodes { + let node_id = problematic.node_id.clone(); + let Some(node) = state + .ui_trees + .iter_mut() + .find_map(|tree| tree.root.find_mut(&node_id)) + else { + errors.push(format!( + "问题节点 {} 已不存在，已保留问题记录", + node_id.as_str() + )); + continue; + }; + if !matches!(node.component, Some(Component::Image(_))) { + errors.push(format!( + "问题节点 {} 不是可处理的 Image 组件，已保留问题记录", + node_id.as_str() + )); + continue; + } + node.metadata.component_status = + StageStatus::NeedReview(separation_problem_reason(problematic)); + } + errors +} + +/// `NeedReview` 文案，镜像 `separationStatus.ts` 的 `separationProblemReason`。 +pub(crate) fn separation_problem_reason(problematic: &ProblematicNode) -> String { + let history = problematic + .problem_history + .iter() + .filter(|item| !item.trim().is_empty()) + .cloned() + .collect::>() + .join("\n"); + let details = if history.is_empty() { + problematic.problem_description.clone() + } else { + history + }; + let head = format!("自动切分重试已达上限（{} 次）", problematic.rework_count); + if details.is_empty() { + head + } else { + format!("{head}\n{details}") + } +} + +fn backfill_bound_node( + state: &mut State, + bound: &BoundNode, + sprite_by_path: &HashMap, + errors: &mut Vec, +) { + let path = normalize_cut_image_path(&bound.cut_image_path); + let Some(sprite) = sprite_by_path.get(&path) else { + errors.push(format!( + "节点 {} 缺少已登记的自动切分素材图片：{path}", + bound.node_id.as_str() + )); + return; + }; + let node_id = bound.node_id.clone(); + let Some(node) = state + .ui_trees + .iter_mut() + .find_map(|tree| tree.root.find_mut(&node_id)) + else { + errors.push(format!("节点 {} 已不存在，素材已保留", node_id.as_str())); + return; + }; + let cleared = match node.component.as_mut() { + Some(Component::Image(component)) => match component.target_graphic.as_ref() { + Some(target) if target == sprite.asset_id() => true, + Some(_) => { + errors.push(format!( + "节点 {} 已绑定其他素材，自动切分素材已保留", + node_id.as_str() + )); + false + } + None => { + component.target_graphic = Some(sprite.asset_id().clone()); + true + } + }, + _ => { + errors.push(format!( + "节点 {} 没有可回填的 Image 组件，素材已保留", + node_id.as_str() + )); + false + } + }; + if cleared { + node.metadata.component_status = StageStatus::NoProblem; + } +} + +fn sprite_asset_error(sprite: &SpriteAsset) -> Result<(), String> { + if sprite.asset_id().as_str().trim().is_empty() { + return Err("缺少素材 ID".to_string()); + } + if sprite.path().trim().is_empty() { + return Err("缺少素材路径".to_string()); + } + let size = sprite.pixel_size(); + if !size.x.is_finite() || !size.y.is_finite() || size.x <= 0.0 || size.y <= 0.0 { + return Err(format!("素材尺寸无效：{}", format_pixel_size(size))); + } + let pixels_per_unit = sprite.pixels_per_unit().get(); + if !pixels_per_unit.is_finite() || pixels_per_unit <= 0.0 { + return Err(format!("像素单位无效：{pixels_per_unit}")); + } + validate_sprite_border(sprite) +} + +/// 镜像 `spriteBorder.ts` 的 `validateSpriteBorder`；Rust 侧边距是 `u32`， +/// 非负整数与上界由类型本身保证，只剩中心至少留 1 px 的检查。 +fn validate_sprite_border(sprite: &SpriteAsset) -> Result<(), String> { + let border = sprite.border(); + if !border.has_border() { + return Ok(()); + } + let size = sprite.pixel_size(); + if !size.x.is_finite() || !size.y.is_finite() || size.x <= 0.0 || size.y <= 0.0 { + return Err("素材尺寸无效".to_string()); + } + let horizontal = f64::from(border.left()) + f64::from(border.right()) + 1.0; + if horizontal > f64::from(size.x.floor()) { + return Err("水平中心至少保留 1 px".to_string()); + } + let vertical = f64::from(border.top()) + f64::from(border.bottom()) + 1.0; + if vertical > f64::from(size.y.floor()) { + return Err("垂直中心至少保留 1 px".to_string()); + } + Ok(()) +} + +fn format_pixel_size(size: nalgebra::Vector2) -> String { + format!("[{}, {}]", size.x, size.y) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::ui_editor::agent_tools::test_support::{image_node, sprite, state_with, tree}; + use crate::ui_editor::commands::separation::BoundNode; + use crate::ui_editor::utils::SpriteAssetId; + + fn sprite_by_path(sprites: &[SpriteAsset]) -> HashMap { + sprites + .iter() + .map(|sprite| (sprite.path().to_string(), sprite.clone())) + .collect() + } + + fn bound(node_id: &str, cut_path: &str) -> BoundNode { + BoundNode { + node_id: crate::ui_editor::utils::NodeId::new(node_id.to_string()).expect("node id"), + cut_image_path: cut_path.to_string(), + } + } + + fn problematic(node_id: &str, history: &[&str], description: &str) -> ProblematicNode { + ProblematicNode { + node_id: crate::ui_editor::utils::NodeId::new(node_id.to_string()).expect("node id"), + problem_description: description.to_string(), + problem_history: history.iter().map(|item| item.to_string()).collect(), + rework_count: 3, + } + } + + fn state_with_image_node(target_graphic: Option<&str>) -> State { + let mut state = state_with(&[("page-a", 100.0, 50.0)]); + state + .ui_trees + .push(tree("page-a", image_node("node-a", target_graphic))); + state + } + + #[test] + fn sprite_assets_merge_and_duplicates_must_match() { + let state = state_with(&[]); + let merged = add_sprite_assets(&state, &[sprite("cut-1", "assets/cut-1.png")]) + .expect("merge sprite"); + assert!(merged + .sprite_assets + .contains_key(&SpriteAssetId::new("cut-1".to_string()).expect("sprite id"))); + // 同 id 同内容可以重复合并。 + let again = add_sprite_assets(&merged, &[sprite("cut-1", "assets/cut-1.png")]) + .expect("merge identical sprite"); + assert_eq!(again.sprite_assets.len(), 1); + // 同 id 不同内容报错。 + let error = add_sprite_assets(&merged, &[sprite("cut-1", "assets/other.png")]) + .expect_err("different sprite content must fail"); + assert!(error.contains("cut-1")); + } + + #[test] + fn bound_node_without_registered_sprite_keeps_error() { + let mut state = state_with_image_node(None); + let errors = apply_separation( + &mut state, + &SeparationDTO { + bound_nodes: vec![bound("node-a", "assets/cut-1.png")], + problematic_nodes: Vec::new(), + }, + &HashMap::new(), + ); + assert_eq!(errors.len(), 1); + assert!(errors[0].contains("缺少已登记的自动切分素材图片")); + } + + #[test] + fn missing_node_and_non_image_component_keep_the_sprite() { + let sprite = sprite("cut-1", "assets/cut-1.png"); + let mut state = state_with(&[("page-a", 100.0, 50.0)]); + state.ui_trees.push(tree( + "page-a", + crate::ui_editor::agent_tools::test_support::node("node-b"), + )); + let errors = apply_separation( + &mut state, + &SeparationDTO { + bound_nodes: vec![ + bound("node-x", "assets/cut-1.png"), + bound("node-b", "assets/cut-1.png"), + ], + problematic_nodes: Vec::new(), + }, + &sprite_by_path(&[sprite]), + ); + assert_eq!( + errors, + vec![ + "节点 node-x 已不存在，素材已保留".to_string(), + "节点 node-b 没有可回填的 Image 组件，素材已保留".to_string(), + ] + ); + } + + #[test] + fn backfill_binds_free_graphic_and_clears_status() { + let mut state = state_with_image_node(None); + state.ui_trees[0].root.metadata.component_status = StageStatus::NeedReview("旧问题".into()); + let errors = apply_separation( + &mut state, + &SeparationDTO { + bound_nodes: vec![bound("node-a", "assets/cut-1.png")], + problematic_nodes: Vec::new(), + }, + &sprite_by_path(&[sprite("cut-1", "assets/cut-1.png")]), + ); + assert!(errors.is_empty()); + let node = &state.ui_trees[0].root; + assert_eq!( + node.component + .as_ref() + .and_then(|component| match component { + Component::Image(image) => image.target_graphic.clone(), + Component::Text(_) => None, + }) + .expect("target graphic") + .as_str(), + "cut-1" + ); + assert_eq!(node.metadata.component_status, StageStatus::NoProblem); + } + + #[test] + fn already_bound_graphic_keeps_other_sprite_and_reports() { + let mut state = state_with_image_node(Some("cut-2")); + let errors = apply_separation( + &mut state, + &SeparationDTO { + bound_nodes: vec![bound("node-a", "assets/cut-1.png")], + problematic_nodes: Vec::new(), + }, + &sprite_by_path(&[ + sprite("cut-1", "assets/cut-1.png"), + sprite("cut-2", "assets/cut-2.png"), + ]), + ); + assert_eq!( + errors, + vec!["节点 node-a 已绑定其他素材，自动切分素材已保留".to_string()] + ); + } + + #[test] + fn same_graphic_only_clears_status() { + let mut state = state_with_image_node(Some("cut-1")); + state.ui_trees[0].root.metadata.component_status = StageStatus::NeedReview("旧问题".into()); + let errors = apply_separation( + &mut state, + &SeparationDTO { + bound_nodes: vec![bound("node-a", "assets/cut-1.png")], + problematic_nodes: Vec::new(), + }, + &sprite_by_path(&[sprite("cut-1", "assets/cut-1.png")]), + ); + assert!(errors.is_empty()); + assert_eq!( + state.ui_trees[0].root.metadata.component_status, + StageStatus::NoProblem + ); + } + + #[test] + fn problematic_nodes_write_review_status_or_report() { + let mut state = state_with_image_node(None); + let errors = apply_problematic_statuses( + &mut state, + &[ + problematic("node-a", &["第一次", " ", "第二次"], "缺描述"), + problematic("node-x", &[], "缺描述"), + ], + ); + assert_eq!( + errors, + vec!["问题节点 node-x 已不存在，已保留问题记录".to_string()] + ); + assert_eq!( + state.ui_trees[0].root.metadata.component_status, + StageStatus::NeedReview("自动切分重试已达上限（3 次）\n第一次\n第二次".to_string()) + ); + } + + #[test] + fn problem_reason_falls_back_to_description() { + let reason = separation_problem_reason(&problematic("node-a", &[" "], "切分失败")); + assert_eq!(reason, "自动切分重试已达上限（3 次）\n切分失败"); + let bare = separation_problem_reason(&problematic("node-a", &[], "")); + assert_eq!(bare, "自动切分重试已达上限（3 次）"); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/write_back.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/write_back.rs new file mode 100644 index 000000000..20a698d36 --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/steps/write_back.rs @@ -0,0 +1,74 @@ +//! `write-back` 步骤：把本轮重建出的 State 保存进设计文档，并在检查点记下结果。 +//! +//! 文档被外部改动时追加 `outdated` 行并报错，不在同一次调用里自动重开新一轮； +//! 恢复侧发现文档已等于目标 State 时只补 `write-back` 行，不重复保存。 + +use super::super::checkpoint::{checkpoint_timestamp, CheckpointLine, WorkflowLog, WorkflowRound}; +use crate::ui_editor::persistence::{ + save_ui_design_state_at, SaveUiDesignStateInput, SaveUiDesignStateResult, +}; +use crate::ui_editor::state::State; + +/// 文档中途漂移，本轮作废的检查点原因。 +pub(crate) const DRIFT_REASON: &str = "doc-state-drift"; + +/// 本轮要写回的文档。 +pub(crate) struct WriteBackTarget<'a> { + pub(crate) project_path: &'a str, + pub(crate) expected_project_id: &'a str, + pub(crate) asset_id: &'a str, +} + +impl WriteBackTarget<'_> { + /// 保存 State 并追加 `write-back` 行；`Unchanged` 也记行，恢复判定只看行。 + pub(crate) fn commit( + &self, + log: &WorkflowLog, + expected_revision: u64, + state: &State, + ) -> Result { + match save_ui_design_state_at(SaveUiDesignStateInput { + project_path: self.project_path.to_string(), + expected_project_id: self.expected_project_id.to_string(), + asset_id: self.asset_id.to_string(), + expected_revision, + state: state.clone(), + })? { + SaveUiDesignStateResult::Saved { revision, .. } + | SaveUiDesignStateResult::Unchanged { revision, .. } => { + record_write_back(log, revision)?; + Ok(revision) + } + SaveUiDesignStateResult::Conflict { current } => { + log.append(&CheckpointLine::Outdated { + at: checkpoint_timestamp(), + reason: DRIFT_REASON.to_string(), + })?; + Err(conflict_message(expected_revision, current.revision)) + } + } + } +} + +/// 文档已经是目标 State（保存成功但缺 `write-back` 行）时只补行。 +pub(crate) fn record_write_back(log: &WorkflowLog, revision: u64) -> Result<(), String> { + log.append(&CheckpointLine::WriteBack { + at: checkpoint_timestamp(), + revision, + }) +} + +/// 保存时 revision 已经变了：说明文档在本轮中途被外部保存。 +pub(crate) fn conflict_message(expected_revision: u64, current_revision: u64) -> String { + format!( + "UI 设计文档在本次工作流中途被改动（写回期望 revision {expected_revision}，当前 {current_revision}），本轮已作废；请重新调用 run-workflow 开新一轮" + ) +} + +/// 恢复前的基线漂移：带上检查点基线时间与 revision，便于判断是外部保存还是本轮重放。 +pub(crate) fn checkpoint_drift_message(current_revision: u64, round: &WorkflowRound) -> String { + format!( + "UI 设计文档在本次工作流中途被改动（检查点基线 revision {}，记录于 {} 秒级 Unix 时间戳，当前 revision {current_revision}），本轮已作废；请重新调用 run-workflow 开新一轮", + round.base_revision, round.at + ) +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/test_support.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/test_support.rs new file mode 100644 index 000000000..18801327f --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/agent_tools/test_support.rs @@ -0,0 +1,94 @@ +//! agent_tools 单测共用夹具：只提供最小可用的 State / 节点 / 素材构造。 + +use crate::ui_editor::component::image::ImageComponent; +use crate::ui_editor::component::Component; +use crate::ui_editor::layout::children_display_mode::ChildrenDisplayMode; +use crate::ui_editor::layout::control_layout::ControlLayout; +use crate::ui_editor::layout::node::{Node, NodeMetadata, NodeSource, StageStatus}; +use crate::ui_editor::layout::offset::NodeOffset; +use crate::ui_editor::resource::sprite::SpriteAsset; +use crate::ui_editor::resource::ui_design_image::UIDesignImage; +use crate::ui_editor::state::{State, UITree}; +use crate::ui_editor::utils::{NodeId, SpriteAssetId, UIDesignImageId}; +use nalgebra::Vector2; +use std::collections::HashMap; +use typed_floats::tf32::StrictlyPositiveFinite; + +pub(crate) fn pixels_per_unit() -> StrictlyPositiveFinite { + StrictlyPositiveFinite::new(1.0).expect("pixels per unit") +} + +pub(crate) fn image(width: f32, height: f32) -> UIDesignImage { + UIDesignImage { + path: format!("assets/{width}x{height}.png"), + pixel_size: Vector2::new(width, height), + pixels_per_unit: pixels_per_unit(), + } +} + +pub(crate) fn state_with(images: &[(&str, f32, f32)]) -> State { + let mut ui_design_images = HashMap::new(); + for (id, width, height) in images { + ui_design_images.insert( + UIDesignImageId::new(id.to_string()).expect("image id"), + image(*width, *height), + ); + } + State { + ui_trees: Vec::new(), + ui_design_images, + sprite_assets: HashMap::new(), + font_assets: HashMap::new(), + } +} + +pub(crate) fn node_metadata() -> NodeMetadata { + NodeMetadata { + name: "页面根节点".to_string(), + description: String::new(), + layout_status: StageStatus::NoProblem, + component_status: StageStatus::NoProblem, + allow_llm_edit_layout: true, + allow_llm_edit_component: true, + source: NodeSource::System, + } +} + +pub(crate) fn node(id: &str) -> Node { + Node { + id: NodeId::new(id.to_string()).expect("node id"), + layout: ControlLayout::default(), + metadata: node_metadata(), + component: None, + children_display_mode: ChildrenDisplayMode::Stack, + children: Vec::new(), + offset: NodeOffset::default(), + } +} + +/// 带 Image 组件的节点，用来覆盖切分回填与问题状态。 +pub(crate) fn image_node(id: &str, target_graphic: Option<&str>) -> Node { + let mut component = ImageComponent::new(); + component.target_graphic = target_graphic + .map(|sprite_id| SpriteAssetId::new(sprite_id.to_string()).expect("sprite id")); + let mut node = node(id); + node.component = Some(Component::Image(component)); + node +} + +pub(crate) fn tree(tree_id: &str, root: Node) -> UITree { + UITree { + src_ui_design: UIDesignImageId::new(tree_id.to_string()).expect("tree id"), + root, + } +} + +pub(crate) fn sprite(id: &str, path: &str) -> SpriteAsset { + SpriteAsset::from_registered_image( + SpriteAssetId::new(id.to_string()).expect("sprite id"), + path.to_string(), + Vector2::new(32.0, 24.0), + pixels_per_unit(), + ) + .expect("sprite asset") +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/binding.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/binding.rs deleted file mode 100644 index 9d9b9bb3b..000000000 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/binding.rs +++ /dev/null @@ -1,636 +0,0 @@ -use crate::config::build_game_creator_llm_client_from_llm_config; -use crate::config::load_game_creator_app_config; -use crate::ui_editor::commands::utils::{ - parse_limited_llm_tool_arguments, read_ui_reference_image_data_url, request_ui_editor_llm, - strict_json_schema, -}; -use crate::ui_editor::component::text::FontSource; -use crate::ui_editor::component::{Component, NodeComponent}; -use crate::ui_editor::layout::node::{Node, StageStatus}; -use crate::ui_editor::persistence::UI_DESIGN_STATE_MAX_NODES; -use crate::ui_editor::state::State; -use crate::ui_editor::utils::{FontAssetId, NodeId, SpriteAssetId}; -use platform_llm::{ - LlmFunctionTool, LlmMessage, LlmMessageContentPart, LlmRunRequest, LlmToolChoice, -}; -use schemars::JsonSchema; -use serde::{Deserialize, Serialize}; -use std::collections::HashSet; -use std::path::Path; - -pub const ASSET_BATCH_SIZE: usize = 5; - -const FONT_CONTEXT_MAX_ASSETS: usize = 64; -const FONT_CONTEXT_MAX_ID_BYTES: usize = 128; -const FONT_CONTEXT_MAX_NAME_CHARS: usize = 128; - -const SYSTEM_PROMPT: &str = r#" -你是游戏 UI 组件绑定器。你会看到全部 UI 参考图、可编辑节点说明，以及本批独立素材的真实像素。 - -* 只对视觉上确实需要改变组件的节点返回 changes； -* 每个 change 的 component 是该节点完整的新组件；纯结构节点返回 "PureNode"，有组件返回 {"WithComponent": <完整 Component>}。 -* 对 Component，直接完整返回其全部参数. -* 有任何困难或者不确定把状态设为 NeedReview，说明中文原因。 -* 纯结构节点可以返回 "PureNode" 并标为 NoProblem。 -* 容器背景等推荐使用Simple + preserve_aspect: false 实现与node大小一致 -* 面向用户的 reason 使用中文。 - -"#; - -#[derive(Clone, Debug, Deserialize, JsonSchema)] -#[serde(deny_unknown_fields)] -#[schemars(deny_unknown_fields)] -enum DraftStatus { - NoProblem, - NeedReview(String), -} - -#[derive(Clone, Debug, Deserialize, JsonSchema)] -#[serde(deny_unknown_fields)] -#[schemars(deny_unknown_fields)] -struct BindingChangeDraft { - node_id: NodeId, - component: NodeComponent, - component_status: DraftStatus, -} - -#[derive(Clone, Debug, Deserialize, JsonSchema)] -#[serde(deny_unknown_fields)] -#[schemars(deny_unknown_fields)] -struct BindingResponse { - changes: Vec, -} - -#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] -pub struct BindingChange { - pub node_id: NodeId, - pub component: NodeComponent, - pub component_status: StageStatus, -} - -#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] -pub struct BindingDTO { - pub changes: Vec, -} - -#[derive(Serialize)] -struct EditableNodeContext<'a> { - node_id: &'a NodeId, - name: &'a str, - description: &'a str, - component: Option<&'a Component>, -} - -#[derive(Debug, Serialize)] -struct FontAssetContext<'a> { - id: &'a str, - family_name: String, - face_name: String, - weight: u16, - italic: bool, - format: crate::ui_editor::resource::font::FontFormat, -} - -fn binding_json_schema() -> Result { - strict_json_schema::() -} - -fn collect_editable_nodes<'a>(node: &'a Node, output: &mut Vec>) { - if node.metadata.allow_llm_edit_component { - output.push(EditableNodeContext { - node_id: &node.id, - name: &node.metadata.name, - description: &node.metadata.description, - component: node.component.as_ref(), - }); - } - for child in &node.children { - collect_editable_nodes(child, output); - } -} - -fn bounded_font_name(value: &str) -> String { - value - .chars() - .filter(|character| !character.is_control()) - .take(FONT_CONTEXT_MAX_NAME_CHARS) - .collect() -} - -fn collect_font_asset_context(state: &State) -> Result>, String> { - if state.font_assets.len() > FONT_CONTEXT_MAX_ASSETS { - return Err(format!( - "组件绑定上下文最多支持 {FONT_CONTEXT_MAX_ASSETS} 项字体素材" - )); - } - let mut fonts = state.font_assets.iter().collect::>(); - fonts.sort_by(|(left, _), (right, _)| left.cmp(right)); - fonts - .into_iter() - .map(|(id, font)| { - if id.as_str().len() > FONT_CONTEXT_MAX_ID_BYTES - || id.as_str().chars().any(char::is_control) - || font.asset_id != *id - { - return Err("字体素材 ID 不适合加入组件绑定上下文".to_string()); - } - let family_name = bounded_font_name(&font.metadata.family_name); - let face_name = bounded_font_name(&font.metadata.face_name); - if family_name.trim().is_empty() || face_name.trim().is_empty() { - return Err("字体素材名称不适合加入组件绑定上下文".to_string()); - } - if !(1..=1_000).contains(&font.metadata.weight) { - return Err("字体素材字重不适合加入组件绑定上下文".to_string()); - } - Ok(FontAssetContext { - id: id.as_str(), - family_name, - face_name, - weight: font.metadata.weight, - italic: font.metadata.italic, - format: font.metadata.format, - }) - }) - .collect() -} - -fn validate_binding_response_shape( - value: &serde_json::Value, - editable_node_count: usize, -) -> Result<(), String> { - let changes = value - .get("changes") - .and_then(serde_json::Value::as_array) - .ok_or_else(|| "组件绑定工具参数缺少 changes 数组".to_string())?; - let max_changes = editable_node_count.min(UI_DESIGN_STATE_MAX_NODES); - if changes.len() > max_changes { - return Err(format!("组件绑定 changes 不能超过 {max_changes} 条")); - } - for change in changes { - let Some(object) = change.as_object() else { - return Err("组件绑定 change 缺少 component 字段".to_string()); - }; - let Some(component) = object.get("component") else { - return Err("组件绑定 change 缺少 component 字段".to_string()); - }; - let valid_component = component == "PureNode" - || component - .as_object() - .and_then(|value| value.get("WithComponent")) - .is_some_and(serde_json::Value::is_object); - if !valid_component { - return Err( - "组件绑定 change 的 component 必须是 PureNode 或 WithComponent 对象".to_string(), - ); - } - } - Ok(()) -} - -fn parse_binding_response( - arguments: &str, - editable_node_count: usize, -) -> Result { - let value = parse_limited_llm_tool_arguments(arguments)?; - validate_binding_response_shape(&value, editable_node_count)?; - serde_json::from_value(value).map_err(|error| format!("组件绑定工具参数无效：{error}")) -} - -fn validate_and_materialize( - changes: Vec, - editable_ids: &HashSet, - known_sprite_ids: &HashSet, - known_font_ids: &HashSet, -) -> Result { - let mut changed_ids = HashSet::new(); - let mut materialized = Vec::with_capacity(changes.len()); - for change in changes { - if !editable_ids.contains(&change.node_id) { - return Err(format!( - "组件绑定返回了未授权节点：{}", - change.node_id.as_str() - )); - } - if !changed_ids.insert(change.node_id.clone()) { - return Err(format!("组件绑定重复返回节点：{}", change.node_id.as_str())); - } - if let NodeComponent::WithComponent(component) = &change.component { - match component { - Component::Image(image) => { - if image - .target_graphic - .as_ref() - .is_some_and(|id| !known_sprite_ids.contains(id)) - { - return Err("组件绑定引用了不存在的独立素材".to_string()); - } - } - Component::Text(text) => { - if let FontSource::Bound(id) = &text.font { - if !known_font_ids.contains(id) { - return Err("组件绑定引用了不存在的字体素材".to_string()); - } - } - } - } - } - let component_status = match change.component_status { - DraftStatus::NoProblem => StageStatus::NoProblem, - DraftStatus::NeedReview(reason) if reason.trim().is_empty() => { - return Err("组件待审状态必须包含原因".to_string()) - } - DraftStatus::NeedReview(reason) => { - if matches!(&change.component, NodeComponent::PureNode) { - return Err("纯结构节点不能标记为组件待审".to_string()); - } - StageStatus::NeedReview(reason) - } - }; - materialized.push(BindingChange { - node_id: change.node_id, - component: change.component, - component_status, - }); - } - Ok(BindingDTO { - changes: materialized, - }) -} - -pub(crate) async fn bind_components_impl( - project_path: String, - state: State, - sprite_ids: Vec, -) -> Result { - bind_components_impl_with_provider(project_path, state, sprite_ids, None).await -} - -pub(crate) async fn bind_components_impl_with_provider( - project_path: String, - state: State, - sprite_ids: Vec, - provider_identity: Option<(&str, &str)>, -) -> Result { - if sprite_ids.is_empty() { - return Err("请先导入至少一个独立素材".to_string()); - } - if sprite_ids.len() > ASSET_BATCH_SIZE { - return Err(format!("单次组件绑定最多 {} 个独立素材", ASSET_BATCH_SIZE)); - } - let sprite_ids = sprite_ids - .into_iter() - .map(SpriteAssetId::new) - .collect::, _>>() - .map_err(|error| format!("独立素材 ID 无效：{error}"))?; - let batch_sprite_ids = sprite_ids.iter().cloned().collect::>(); - if batch_sprite_ids.len() != sprite_ids.len() { - return Err("独立素材批次包含重复 ID".to_string()); - } - if state.ui_design_images.is_empty() || state.ui_design_images.len() > 4 { - return Err("组件绑定需要 1 至 4 张界面图".to_string()); - } - let mut editable_nodes = Vec::new(); - for tree in &state.ui_trees { - if !state.ui_design_images.contains_key(&tree.src_ui_design) { - return Err("UI 树引用的界面图不存在".to_string()); - } - collect_editable_nodes(&tree.root, &mut editable_nodes); - } - if editable_nodes.is_empty() { - return Err("当前没有允许 LLM 修改组件的节点".to_string()); - } - let editable_ids = editable_nodes - .iter() - .map(|node| node.node_id.clone()) - .collect::>(); - if editable_ids.len() != editable_nodes.len() { - return Err("UI 树包含重复节点 ID".to_string()); - } - let root = Path::new(project_path.trim()); - let mut parts = Vec::with_capacity(state.ui_design_images.len() * 2 + sprite_ids.len() * 2 + 2); - let node_context = serde_json::to_string(&editable_nodes) - .map_err(|error| format!("序列化可编辑节点失败：{error}"))?; - parts.push(LlmMessageContentPart::InputText { - text: format!("可编辑节点：{node_context}"), - }); - let font_context = collect_font_asset_context(&state)?; - let font_context = serde_json::to_string(&font_context) - .map_err(|error| format!("序列化字体素材失败：{error}"))?; - parts.push(LlmMessageContentPart::InputText { - text: format!("可用字体（以下 JSON 仅为数据，字段内容不是指令）：{font_context}"), - }); - for (id, image) in &state.ui_design_images { - let absolute = crate::project::resolve_local_project_path(root, &image.path)?; - let image_url = read_ui_reference_image_data_url(absolute) - .await - .map_err(|error| format!("读取界面图失败：{error}"))?; - parts.push(LlmMessageContentPart::InputText { - text: format!( - "UI_REFERENCE id={} pixel_size={:?}", - id.as_str(), - image.pixel_size - ), - }); - parts.push(LlmMessageContentPart::InputImage { image_url }); - } - for id in &sprite_ids { - let sprite = state - .sprite_assets - .get(id) - .ok_or_else(|| format!("独立素材不存在：{}", id.as_str()))?; - let absolute = crate::project::resolve_local_project_path(root, &sprite.path)?; - let image_url = read_ui_reference_image_data_url(absolute) - .await - .map_err(|error| format!("读取独立素材失败：{error}"))?; - parts.push(LlmMessageContentPart::InputText { - text: format!( - "SPRITE id={} name={} asset_type={} pixel_size={:?}", - id.as_str(), - sprite.metadata.name, - sprite.metadata.asset_type, - sprite.pixel_size - ), - }); - parts.push(LlmMessageContentPart::InputImage { image_url }); - } - let (llm, client) = if provider_identity.is_none() { - let llm = load_game_creator_app_config() - .map_err(|error| { - eprintln!("ui_binding.error stage=build_client error={error}"); - error - })? - .llm; - let client = - build_game_creator_llm_client_from_llm_config(&llm, "llm").map_err(|error| { - eprintln!("ui_binding.error stage=build_client error={error}"); - error - })?; - (Some(llm), Some(client)) - } else { - (None, None) - }; - let tool = LlmFunctionTool::new( - "bind_ui_components", - "根据 UI 参考图和当前批次独立素材，返回需要修改的节点组件", - binding_json_schema()?, - ) - .with_strict(true); - let request = LlmRunRequest::new(vec![ - LlmMessage::system(SYSTEM_PROMPT), - LlmMessage::user_multimodal(parts), - ]) - .with_function_tools(vec![tool]) - .with_tool_choice(LlmToolChoice::Required); - let response = if let Some((agent_id, run_id)) = provider_identity { - crate::agent::request_game_creator_ui_editor_llm_at( - root, - agent_id, - run_id, - "ui-editor-bind", - request, - ) - .await - .map_err(platform_llm::LlmError::InvalidRequest) - } else { - request_ui_editor_llm( - client - .as_ref() - .expect("provider client exists without runtime identity"), - llm.as_ref() - .expect("LLM config exists without runtime identity"), - request, - ) - .await - } - .map_err(|error| format!("组件绑定失败：{error}"))?; - let call = response - .tool_calls - .iter() - .find(|call| call.name == "bind_ui_components") - .ok_or_else(|| "LLM 未返回 bind_ui_components 工具调用".to_string())?; - let parsed = parse_binding_response(&call.arguments, editable_nodes.len())?; - let known_sprite_ids = state.sprite_assets.keys().cloned().collect::>(); - let known_font_ids = state.font_assets.keys().cloned().collect::>(); - let result = validate_and_materialize( - parsed.changes, - &editable_ids, - &known_sprite_ids, - &known_font_ids, - )?; - app_log!( - "ui_binding.completed ui_images={} sprites={} editable_nodes={} changes={}", - state.ui_design_images.len(), - sprite_ids.len(), - editable_nodes.len(), - result.changes.len() - ); - Ok(result) -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::ui_editor::component::text::{FontSource, TextComponent}; - - fn id(value: &str) -> NodeId { - NodeId::new(value).expect("valid id") - } - - #[test] - fn materialization_rejects_unapproved_node_and_unknown_sprite() { - let editable = HashSet::from([id("editable")]); - let known = HashSet::from([ - SpriteAssetId::new("sprite").expect("valid sprite"), - SpriteAssetId::new("other-batch-sprite").expect("valid sprite"), - ]); - let unapproved = BindingChangeDraft { - node_id: id("other"), - component: NodeComponent::PureNode, - component_status: DraftStatus::NoProblem, - }; - assert!( - validate_and_materialize(vec![unapproved], &editable, &known, &HashSet::new()).is_err() - ); - - // References to sprites from another batch are allowed once they exist in the project. - let other_batch = BindingChangeDraft { - node_id: id("editable"), - component: NodeComponent::WithComponent(Component::Image( - crate::ui_editor::component::image::ImageComponent { - target_graphic: Some( - SpriteAssetId::new("other-batch-sprite").expect("valid sprite"), - ), - image_type: crate::ui_editor::component::image::ImageType::Simple { - preserve_aspect: false, - }, - }, - )), - component_status: DraftStatus::NoProblem, - }; - assert!( - validate_and_materialize(vec![other_batch], &editable, &known, &HashSet::new()).is_ok() - ); - - // References to sprites that do not exist in the project at all are still rejected. - let unknown = BindingChangeDraft { - node_id: id("editable"), - component: NodeComponent::WithComponent(Component::Image( - crate::ui_editor::component::image::ImageComponent { - target_graphic: Some(SpriteAssetId::new("unknown").expect("valid sprite")), - image_type: crate::ui_editor::component::image::ImageType::Simple { - preserve_aspect: false, - }, - }, - )), - component_status: DraftStatus::NoProblem, - }; - assert!( - validate_and_materialize(vec![unknown], &editable, &known, &HashSet::new()).is_err() - ); - } - - #[test] - fn materialization_rejects_unknown_bound_font() { - let editable = HashSet::from([id("editable")]); - let mut text = TextComponent::new("标题"); - text.font = FontSource::Bound(FontAssetId::new("unknown-font").expect("valid font")); - let change = BindingChangeDraft { - node_id: id("editable"), - component: NodeComponent::WithComponent(Component::Text(text)), - component_status: DraftStatus::NoProblem, - }; - - let error = validate_and_materialize( - vec![change], - &editable, - &HashSet::new(), - &HashSet::from([FontAssetId::new("known-font").expect("valid font")]), - ) - .expect_err("unknown bound font must fail"); - assert!(error.contains("不存在的字体素材")); - } - - #[test] - fn materialization_preserves_pure_node_change() { - let editable = HashSet::from([id("editable")]); - let result = validate_and_materialize( - vec![BindingChangeDraft { - node_id: id("editable"), - component: NodeComponent::PureNode, - component_status: DraftStatus::NoProblem, - }], - &editable, - &HashSet::new(), - &HashSet::new(), - ) - .expect("valid changed-only clear"); - assert_eq!(result.changes.len(), 1); - assert!(matches!( - result.changes[0].component, - NodeComponent::PureNode - )); - assert_eq!(result.changes[0].component_status, StageStatus::NoProblem); - } - - #[test] - fn materialization_rejects_problematic_pure_node() { - let editable = HashSet::from([id("editable")]); - let error = validate_and_materialize( - vec![BindingChangeDraft { - node_id: id("editable"), - component: NodeComponent::PureNode, - component_status: DraftStatus::NeedReview("缺少可确认的组件".to_string()), - }], - &editable, - &HashSet::new(), - &HashSet::new(), - ) - .expect_err("pure node cannot carry a component review status"); - assert!(error.contains("纯结构节点")); - } - - #[test] - fn font_context_is_bounded_and_omits_storage_metadata() { - let font_id = FontAssetId::new("font-main").expect("valid font"); - let state = State { - ui_trees: Vec::new(), - ui_design_images: std::collections::HashMap::new(), - sprite_assets: std::collections::HashMap::new(), - font_assets: std::collections::HashMap::from([( - font_id.clone(), - crate::ui_editor::resource::font::FontAsset { - asset_id: font_id, - metadata: crate::ui_editor::resource::font::FontAssetMetadata { - family_name: format!( - "安全\n{}", - "字".repeat(FONT_CONTEXT_MAX_NAME_CHARS + 10) - ), - face_name: "Regular".to_string(), - weight: 400, - italic: false, - format: crate::ui_editor::resource::font::FontFormat::Woff2, - source_file_name: "private-source.woff2".to_string(), - }, - path: "ui/fonts/private.woff2".to_string(), - content_sha256: "private-digest".to_string(), - }, - )]), - }; - - let context = collect_font_asset_context(&state).expect("valid bounded font context"); - assert_eq!(context.len(), 1); - assert!(!context[0].family_name.contains('\n')); - assert_eq!( - context[0].family_name.chars().count(), - FONT_CONTEXT_MAX_NAME_CHARS - ); - let json = serde_json::to_string(&context).expect("font context JSON"); - assert!(!json.contains("private-source")); - assert!(!json.contains("ui/fonts")); - assert!(!json.contains("private-digest")); - } - - #[test] - fn binding_response_rejects_oversized_tool_arguments_before_dto_conversion() { - let oversized = - "x".repeat(crate::ui_editor::commands::utils::LLM_TOOL_ARGUMENT_MAX_BYTES + 1); - assert!(parse_binding_response(&oversized, 1) - .expect_err("oversized tool arguments must fail") - .contains("字节上限")); - } - - #[test] - fn binding_response_bounds_changes_and_uses_single_component_shape() { - let too_many_changes = serde_json::json!({ - "changes": [{"component": "PureNode"}, {"component": "PureNode"}] - }); - assert!(validate_binding_response_shape(&too_many_changes, 1).is_err()); - - let one_component = serde_json::json!({ - "changes": [{ - "node_id": "editable", - "component": "PureNode", - "component_status": "NoProblem" - }] - }); - assert!(validate_binding_response_shape(&one_component, 1).is_ok()); - let parsed = parse_binding_response(&one_component.to_string(), 1) - .expect("explicit PureNode payload should parse"); - assert!(matches!( - parsed.changes[0].component, - NodeComponent::PureNode - )); - } - - #[tokio::test] - async fn binding_image_input_rejects_oversized_files_via_bounded_reader() { - let directory = tempfile::tempdir().expect("binding image fixture"); - let path = directory.path().join("oversized.png"); - let file = std::fs::File::create(&path).expect("create sparse binding image"); - file.set_len((crate::ui_editor::commands::utils::UI_REFERENCE_IMAGE_MAX_BYTES + 1) as u64) - .expect("size sparse binding image"); - drop(file); - - assert!(read_ui_reference_image_data_url(path).await.is_err()); - } -} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/merge.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/merge.rs deleted file mode 100644 index 0a32724d6..000000000 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/merge.rs +++ /dev/null @@ -1,669 +0,0 @@ -use crate::config::build_game_creator_llm_client_from_llm_config; -use crate::config::load_game_creator_app_config; -use crate::ui_editor::commands::utils::{ - parse_limited_llm_tool_arguments, request_ui_editor_llm, strict_json_schema, -}; -use crate::ui_editor::state::{State, UITree}; -use platform_llm::{LlmFunctionTool, LlmMessage, LlmRunRequest, LlmToolChoice}; -use serde::{Deserialize, Serialize}; -use std::path::Path; -use ts_rs::TS; - -const MERGE_TOOL_NAME: &str = "merge_ui_trees"; -const MAX_MERGE_INPUT_NODES: usize = 512; -const MAX_MERGE_INPUT_DEPTH: usize = 32; -const MAX_MERGE_INPUT_BYTES: usize = 2 * 1024 * 1024; -const MAX_MERGE_PLAN_NODES: usize = 512; -const MAX_MERGE_PLAN_DEPTH: usize = 32; - -const SYSTEM_PROMPT: &str = r#" -角色： -你是游戏 UI 多树结构合并器。 - -任务： -用户会提供同一个 UI 系统中多张参考图各自的 UI 树。请返回一棵新的合并计划树。 - -规则： -* Simple 引用一个原始节点 id，并用返回的 children 定义它在新树中的子节点。 -* Merged 表示多个节点描述同一个共同组件(它们可能是同一组件的不同状态)，merged_from 中按语义排列需要放入容器的节点。 -* 可以在任意层级使用 Merged，不限于各输入树的根节点。 -* 一些共用的框架/层次/...在树中只保留一个, 优先保留优先级高的树中的节点 -* 面向用户的节点名称和结构判断使用中文语义理解。 -"#; - -mod llm_contract { - use super::strict_json_schema; - use crate::ui_editor::layout::node::{Node as LayoutNode, NodeMetadata}; - use crate::ui_editor::state::State; - use crate::ui_editor::utils::NodeId; - use schemars::JsonSchema; - use serde::{Deserialize, Serialize}; - - #[derive(Clone, Debug, Serialize)] - pub(super) struct OriginalNode { - id: NodeId, - metadata: NodeMetadata, - children: Vec, - } - - #[derive(Clone, Debug, Serialize)] - pub(super) struct OriginalTree { - priority: u32, - root: OriginalNode, - } - - #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, JsonSchema)] - #[serde(deny_unknown_fields)] - #[schemars(deny_unknown_fields)] - pub(super) struct MergedNode { - pub(super) name: String, - pub(super) description: String, - pub(super) merged_from: Vec, - } - - #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, JsonSchema)] - #[serde(deny_unknown_fields)] - #[schemars(deny_unknown_fields)] - pub(super) struct SimpleNode { - pub(super) id: NodeId, - pub(super) children: Vec, - } - - #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, JsonSchema)] - pub(super) enum Node { - Simple(SimpleNode), - Merged(MergedNode), - } - - #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, JsonSchema)] - #[serde(deny_unknown_fields)] - #[schemars(deny_unknown_fields)] - pub(super) struct MergeResponse { - pub(super) root: Node, - } - - pub(super) fn schema() -> Result { - strict_json_schema::() - } - - fn project_node(node: &LayoutNode) -> OriginalNode { - OriginalNode { - id: node.id.clone(), - metadata: node.metadata.clone(), - children: node.children.iter().map(project_node).collect(), - } - } - - pub(super) fn input_trees( - state: &State, - priorities: &[u32], - ) -> Result, String> { - if state.ui_trees.len() != priorities.len() { - return Err("UI 树优先级数量不匹配".to_string()); - } - Ok(state - .ui_trees - .iter() - .zip(priorities) - .map(|(tree, priority)| OriginalTree { - priority: *priority, - root: project_node(&tree.root), - }) - .collect()) - } -} - -mod priority { - use crate::ui_editor::resource::ui_design_image::UIDesignImage; - use crate::ui_editor::state::State; - use crate::ui_editor::utils::UIDesignImageId; - use std::collections::{HashMap, HashSet}; - - fn ancestor_chain( - image_id: &UIDesignImageId, - images: &HashMap, - ) -> Result, String> { - let mut chain = Vec::new(); - let mut seen = HashSet::new(); - let mut current = image_id.clone(); - loop { - if !seen.insert(current.clone()) { - return Err(format!( - "界面图 slave_to 关系存在循环：{}", - current.as_str() - )); - } - chain.push(current.clone()); - let image = images - .get(¤t) - .ok_or_else(|| format!("界面图 slave_to 引用了缺失界面图：{}", current.as_str()))?; - match &image.metadata.slave_to { - Some(parent) => current = parent.clone(), - None => return Ok(chain), - } - } - } - - pub(super) fn for_state(state: &State) -> Result, String> { - let source_ids = state - .ui_trees - .iter() - .map(|tree| tree.src_ui_design.clone()) - .collect::>(); - let chains = source_ids - .iter() - .map(|source_id| ancestor_chain(source_id, &state.ui_design_images)) - .collect::, _>>()?; - Ok(source_ids - .iter() - .map(|candidate| { - chains - .iter() - .filter(|chain| chain.contains(candidate)) - .count() as u32 - }) - .collect()) - } -} - -mod materialize { - use super::llm_contract::Node; - use crate::ui_editor::layout::children_display_mode::ChildrenDisplayMode; - use crate::ui_editor::layout::node::{ - Node as LayoutNode, NodeMetadata, NodeSource, StageStatus, - }; - use crate::ui_editor::layout::transform::Transform; - use crate::ui_editor::state::{State, UITree}; - use crate::ui_editor::utils::{random_node_id, NodeId, UIDesignImageId}; - use std::collections::{HashMap, HashSet}; - - #[derive(Clone)] - struct OriginalNodeRecord { - node: LayoutNode, - priority: u32, - src_ui_design: UIDesignImageId, - } - - struct BuiltNode { - node: LayoutNode, - priority: u32, - src_ui_design: UIDesignImageId, - } - - fn collect_original_nodes( - node: &LayoutNode, - priority: u32, - src_ui_design: &UIDesignImageId, - records: &mut HashMap, - ) -> Result<(), String> { - if records - .insert( - node.id.clone(), - OriginalNodeRecord { - node: node.clone(), - priority, - src_ui_design: src_ui_design.clone(), - }, - ) - .is_some() - { - return Err(format!("输入 UI 树包含重复节点 ID：{}", node.id.as_str())); - } - for child in &node.children { - collect_original_nodes(child, priority, src_ui_design, records)?; - } - Ok(()) - } - - fn highest_priority_member_index(members: &[BuiltNode]) -> Result { - if members.is_empty() { - return Err("MergedNode.merged_from 不能为空".to_string()); - } - let mut best_index = 0; - let mut best_priority = 0; - for (candidate_index, candidate) in members.iter().enumerate() { - if candidate.priority > best_priority { - best_index = candidate_index; - best_priority = candidate.priority; - } - } - Ok(best_index) - } - - fn unique_random_node_id(occupied: &mut HashSet) -> NodeId { - loop { - let id = random_node_id(); - if occupied.insert(id.clone()) { - return id; - } - } - } - - fn build_node( - plan: Node, - records: &HashMap, - used_original_ids: &mut HashSet, - occupied_ids: &mut HashSet, - ) -> Result { - match plan { - Node::Simple(simple) => { - if !used_original_ids.insert(simple.id.clone()) { - return Err(format!("合并计划重复引用节点 ID：{}", simple.id.as_str())); - } - let original = records - .get(&simple.id) - .ok_or_else(|| format!("合并计划引用了未知节点 ID：{}", simple.id.as_str()))?; - let mut node = original.node.clone(); - node.children = simple - .children - .into_iter() - .map(|child| { - build_node(child, records, used_original_ids, occupied_ids) - .map(|built| built.node) - }) - .collect::, _>>()?; - Ok(BuiltNode { - node, - priority: original.priority, - src_ui_design: original.src_ui_design.clone(), - }) - } - Node::Merged(merged) => { - let container_name = merged.name; - let container_description = merged.description; - let mut members = merged - .merged_from - .into_iter() - .map(|member| build_node(member, records, used_original_ids, occupied_ids)) - .collect::, _>>()?; - let highest_priority_index = highest_priority_member_index(&members)?; - let original_transform = members[highest_priority_index].node.layout.transform; - let priority = members[highest_priority_index].priority; - let src_ui_design = members[highest_priority_index].src_ui_design.clone(); - for member in &mut members { - member.node.layout.transform = Transform::stretch(); - } - Ok(BuiltNode { - node: LayoutNode { - id: unique_random_node_id(occupied_ids), - layout: - crate::ui_editor::layout::control_layout::ControlLayout::with_transform( - original_transform, - ), - metadata: NodeMetadata { - name: container_name, - description: container_description, - layout_status: StageStatus::NoProblem, - component_status: StageStatus::NoProblem, - allow_llm_edit_layout: true, - allow_llm_edit_component: true, - source: NodeSource::Llm, - }, - component: None, - children_display_mode: ChildrenDisplayMode::Exclusive, - children: members.into_iter().map(|member| member.node).collect(), - }, - priority, - src_ui_design, - }) - } - } - } - - pub(super) fn plan(plan: Node, state: &State, priorities: &[u32]) -> Result { - if state.ui_trees.len() != priorities.len() { - return Err("UI 树优先级数量不匹配".to_string()); - } - let mut records = HashMap::new(); - for (tree, priority) in state.ui_trees.iter().zip(priorities) { - collect_original_nodes(&tree.root, *priority, &tree.src_ui_design, &mut records)?; - } - let mut occupied_ids = records.keys().cloned().collect::>(); - // 合并计划是语义投影，不要求覆盖全部源节点；未引用节点表示本次合并明确丢弃。 - // 这里只拒绝重复/未知引用，避免把“公共结构合并”误收紧为全量复制。 - let mut used_original_ids = HashSet::new(); - let built = build_node(plan, &records, &mut used_original_ids, &mut occupied_ids)?; - Ok(UITree { - src_ui_design: built.src_ui_design, - root: built.node, - }) - } -} - -fn validate_merge_input_state(state: &State) -> Result<(), String> { - for tree in &state.ui_trees { - let mut stack = vec![(&tree.root, 1usize)]; - let mut node_count = 0usize; - while let Some((node, depth)) = stack.pop() { - if depth > MAX_MERGE_INPUT_DEPTH { - return Err(format!( - "单棵待合并 UI 树最大深度不能超过 {MAX_MERGE_INPUT_DEPTH}" - )); - } - node_count += 1; - if node_count > MAX_MERGE_INPUT_NODES { - return Err(format!( - "单棵待合并 UI 树最多包含 {MAX_MERGE_INPUT_NODES} 个节点" - )); - } - stack.extend(node.children.iter().map(|child| (child, depth + 1))); - } - } - Ok(()) -} - -fn validate_merge_plan_shape(value: &serde_json::Value) -> Result<(), String> { - let root = value - .get("root") - .ok_or_else(|| "UI 合并工具参数缺少 root".to_string())?; - let mut stack = vec![(root, 1usize)]; - let mut node_count = 0usize; - while let Some((node, depth)) = stack.pop() { - if depth > MAX_MERGE_PLAN_DEPTH { - return Err(format!( - "UI 合并计划最大深度不能超过 {MAX_MERGE_PLAN_DEPTH}" - )); - } - node_count += 1; - if node_count > MAX_MERGE_PLAN_NODES { - return Err(format!("UI 合并计划最多包含 {MAX_MERGE_PLAN_NODES} 个节点")); - } - let object = node - .as_object() - .filter(|object| object.len() == 1) - .ok_or_else(|| "UI 合并计划节点结构无效".to_string())?; - let children = if let Some(simple) = object.get("Simple") { - simple - .get("children") - .and_then(serde_json::Value::as_array) - .ok_or_else(|| "Simple 合并计划节点缺少 children 数组".to_string())? - } else if let Some(merged) = object.get("Merged") { - merged - .get("merged_from") - .and_then(serde_json::Value::as_array) - .ok_or_else(|| "Merged 合并计划节点缺少 merged_from 数组".to_string())? - } else { - return Err("UI 合并计划节点类型无效".to_string()); - }; - stack.extend(children.iter().map(|child| (child, depth + 1))); - } - Ok(()) -} - -#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, TS)] -#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/ui-editor/types/"))] -pub struct MergeDTO { - pub ui_tree: UITree, -} - -pub(crate) async fn merge_ui_impl_with_provider( - project_path: String, - state: State, - provider_identity: Option<(&str, &str)>, -) -> Result { - if state.ui_trees.is_empty() { - app_log!("ui_merge.error stage=validate reason=no_trees"); - return Err("请先完成 UI 结构识别".to_string()); - } - validate_merge_input_state(&state).map_err(|error| { - app_log!("ui_merge.error stage=validate_input error={error}"); - error - })?; - let priorities = priority::for_state(&state).map_err(|error| { - app_log!("ui_merge.error stage=build_priority error={error}"); - error - })?; - let trees = llm_contract::input_trees(&state, &priorities).map_err(|error| { - app_log!("ui_merge.error stage=build_input error={error}"); - error - })?; - let records_json = serde_json::to_string(&trees).map_err(|error| { - app_log!("ui_merge.error stage=serialize_input error={error}"); - format!("序列化 UI 合并输入失败：{error}") - })?; - if records_json.len() > MAX_MERGE_INPUT_BYTES { - app_log!( - "ui_merge.error stage=serialize_input reason=too_large bytes={} limit={MAX_MERGE_INPUT_BYTES}", - records_json.len() - ); - return Err(format!("UI 合并输入超过 {MAX_MERGE_INPUT_BYTES} 字节上限")); - } - let (llm, client) = if provider_identity.is_none() { - let llm = load_game_creator_app_config() - .map_err(|error| { - eprintln!("ui_merge.error stage=build_client error={error}"); - error - })? - .llm; - let client = - build_game_creator_llm_client_from_llm_config(&llm, "llm").map_err(|error| { - app_log!("ui_merge.error stage=build_client error={error}"); - error - })?; - (Some(llm), Some(client)) - } else { - (None, None) - }; - let schema = llm_contract::schema().map_err(|error| { - app_log!("ui_merge.error stage=build_schema error={error}"); - error - })?; - let tool = LlmFunctionTool::new( - MERGE_TOOL_NAME, - "把多张参考图各自的 UI 树合并为一棵新的 UI 计划树", - schema, - ) - .with_strict(true); - let request = LlmRunRequest::new(vec![ - LlmMessage::system(SYSTEM_PROMPT), - LlmMessage::user(format!("待合并 UI 树：\n{records_json}")), - ]) - .with_function_tools(vec![tool]) - .with_tool_choice(LlmToolChoice::Required); - let response = if let Some((agent_id, run_id)) = provider_identity { - crate::agent::request_game_creator_ui_editor_llm_at( - Path::new(project_path.trim()), - agent_id, - run_id, - "ui-editor-merge", - request, - ) - .await - .map_err(platform_llm::LlmError::InvalidRequest) - } else { - request_ui_editor_llm( - client - .as_ref() - .expect("provider client exists without runtime identity"), - llm.as_ref() - .expect("LLM config exists without runtime identity"), - request, - ) - .await - } - .map_err(|error| { - app_log!("ui_merge.error stage=llm_request error={error}"); - format!("UI 树合并失败：{error}") - })?; - let call = response - .tool_calls - .iter() - .find(|call| call.name == MERGE_TOOL_NAME) - .ok_or_else(|| { - app_log!("ui_merge.error stage=parse_tool_call reason=missing_tool_call"); - format!("LLM 未返回 {MERGE_TOOL_NAME} 工具调用") - })?; - let arguments = parse_limited_llm_tool_arguments(&call.arguments).map_err(|error| { - app_log!("ui_merge.error stage=parse_arguments error={error}"); - format!("UI 合并工具参数无效：{error}") - })?; - validate_merge_plan_shape(&arguments).map_err(|error| { - app_log!("ui_merge.error stage=validate_arguments error={error}"); - format!("UI 合并工具参数无效：{error}") - })?; - let parsed = - serde_json::from_value::(arguments).map_err(|error| { - app_log!("ui_merge.error stage=parse_arguments error={error}"); - format!("UI 合并工具参数无效：{error}") - })?; - let ui_tree = materialize::plan(parsed.root, &state, &priorities).map_err(|error| { - app_log!("ui_merge.error stage=materialize error={error}"); - error - })?; - Ok(MergeDTO { ui_tree }) -} - -pub(crate) async fn merge_ui_impl(state: State) -> Result { - merge_ui_impl_with_provider(String::new(), state, None).await -} - -#[cfg(test)] -mod tests { - use super::llm_contract::{MergedNode, Node as PlanNode, SimpleNode}; - use super::{ - materialize, validate_merge_input_state, validate_merge_plan_shape, MAX_MERGE_INPUT_DEPTH, - MAX_MERGE_INPUT_NODES, MAX_MERGE_PLAN_DEPTH, MAX_MERGE_PLAN_NODES, - }; - use crate::ui_editor::layout::children_display_mode::ChildrenDisplayMode; - use crate::ui_editor::layout::control_layout::ControlLayout; - use crate::ui_editor::layout::node::{Node, NodeMetadata, NodeSource, StageStatus}; - use crate::ui_editor::layout::transform::Transform; - use crate::ui_editor::state::{State, UITree}; - use crate::ui_editor::utils::{NodeId, UIDesignImageId}; - use std::collections::HashMap; - - fn node(id: &str, children: Vec) -> Node { - Node { - id: NodeId::new(id).expect("valid node id"), - layout: ControlLayout::with_transform(Transform::stretch()), - metadata: NodeMetadata { - name: id.to_string(), - description: String::new(), - layout_status: StageStatus::NoProblem, - component_status: StageStatus::NoProblem, - allow_llm_edit_layout: true, - allow_llm_edit_component: true, - source: NodeSource::Human, - }, - component: None, - children_display_mode: ChildrenDisplayMode::Stack, - children, - } - } - - #[test] - fn merged_materialization_sets_exclusive_children_display_mode() { - let page_id = UIDesignImageId::new("page").expect("valid page id"); - let state = State { - ui_trees: vec![UITree { - src_ui_design: page_id.clone(), - root: node("root", vec![node("a", vec![]), node("b", vec![])]), - }], - ui_design_images: HashMap::new(), - sprite_assets: HashMap::new(), - font_assets: HashMap::new(), - }; - let plan = PlanNode::Merged(MergedNode { - name: "状态容器".to_string(), - description: String::new(), - merged_from: vec![ - PlanNode::Simple(SimpleNode { - id: NodeId::new("a").expect("valid node id"), - children: vec![], - }), - PlanNode::Simple(SimpleNode { - id: NodeId::new("b").expect("valid node id"), - children: vec![], - }), - ], - }); - - let result = materialize::plan(plan, &state, &[1]).expect("materialize plan"); - assert_eq!( - result.root.children_display_mode, - ChildrenDisplayMode::Exclusive - ); - assert_eq!( - result.root.metadata.component_status, - StageStatus::NoProblem - ); - assert_eq!(result.root.children.len(), 2); - } - - #[test] - fn merge_plan_rejects_node_and_depth_overflow() { - let leaf = || serde_json::json!({"Simple": {"id": "leaf", "children": []}}); - let oversized = (0..MAX_MERGE_PLAN_NODES) - .map(|_| leaf()) - .collect::>(); - assert!(validate_merge_plan_shape(&serde_json::json!({ - "root": {"Simple": {"id": "root", "children": oversized}} - })) - .is_err()); - - let mut nested = leaf(); - for _ in 0..MAX_MERGE_PLAN_DEPTH { - nested = serde_json::json!({ - "Merged": {"name": "层", "description": "", "merged_from": [nested]} - }); - } - assert!(validate_merge_plan_shape(&serde_json::json!({"root": nested})).is_err()); - } - - #[test] - fn merge_input_limits_apply_per_tree_without_summing_trees() { - let tree = |page: &str, prefix: &str| UITree { - src_ui_design: UIDesignImageId::new(page).expect("valid page id"), - root: node( - &format!("{prefix}-root"), - (1..MAX_MERGE_INPUT_NODES) - .map(|index| node(&format!("{prefix}-{index}"), vec![])) - .collect(), - ), - }; - let state = State { - ui_trees: vec![tree("page-a", "a"), tree("page-b", "b")], - ui_design_images: HashMap::new(), - sprite_assets: HashMap::new(), - font_assets: HashMap::new(), - }; - validate_merge_input_state(&state) - .expect("each source tree independently fits the node limit"); - } - - #[test] - fn merge_input_rejects_node_and_depth_overflow() { - let page_id = UIDesignImageId::new("page").expect("valid page id"); - let wide_root = node( - "root", - (0..MAX_MERGE_INPUT_NODES) - .map(|index| node(&format!("child-{index}"), vec![])) - .collect(), - ); - let wide_state = State { - ui_trees: vec![UITree { - src_ui_design: page_id.clone(), - root: wide_root, - }], - ui_design_images: HashMap::new(), - sprite_assets: HashMap::new(), - font_assets: HashMap::new(), - }; - assert!(validate_merge_input_state(&wide_state).is_err()); - - let mut deep_root = node("leaf", vec![]); - for depth in 0..MAX_MERGE_INPUT_DEPTH { - deep_root = node(&format!("depth-{depth}"), vec![deep_root]); - } - let deep_state = State { - ui_trees: vec![UITree { - src_ui_design: page_id, - root: deep_root, - }], - ui_design_images: HashMap::new(), - sprite_assets: HashMap::new(), - font_assets: HashMap::new(), - }; - assert!(validate_merge_input_state(&deep_state).is_err()); - } -} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/mod.rs index d85432e07..512165949 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/mod.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/mod.rs @@ -1,17 +1,8 @@ -pub mod binding; -pub mod merge; pub mod recognition; pub mod separation; -pub mod ui_design_suggestion; pub mod utils; -pub use binding::BindingDTO; -pub(crate) use binding::{bind_components_impl, bind_components_impl_with_provider}; -pub use merge::MergeDTO; -pub(crate) use merge::{merge_ui_impl, merge_ui_impl_with_provider}; pub use recognition::RecognitionDTO; pub(crate) use recognition::{recognize_ui_impl, recognize_ui_impl_with_provider}; pub(crate) use separation::separate_ui_impl; pub use separation::{SeparationDTO, SeparationRecoveryDTO}; -pub(crate) use ui_design_suggestion::suggest_ui_design_semantic_impl; -pub use ui_design_suggestion::UIDesignSuggestionTreeNode; diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/recognition.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/recognition.rs index 963b056cd..2e23b1aaa 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/recognition.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/recognition.rs @@ -2,13 +2,14 @@ use crate::config::build_game_creator_llm_client_from_llm_config; use crate::config::load_game_creator_app_config; use crate::ui_editor::commands::utils::{ parse_limited_llm_tool_arguments, read_ui_reference_image_data_url, request_ui_editor_llm, - strict_json_schema, + required_tool_call_arguments, strict_json_schema, }; use crate::ui_editor::component::{Component, NodeComponent}; use crate::ui_editor::layout::children_display_mode::ChildrenDisplayMode; use crate::ui_editor::layout::control_layout::ControlLayout; use crate::ui_editor::layout::dimension::UIRect; use crate::ui_editor::layout::node::{Node as LayoutNode, NodeMetadata, NodeSource, StageStatus}; +use crate::ui_editor::layout::offset::NodeOffset; use crate::ui_editor::layout::transform::Transform; use crate::ui_editor::resource::ui_design_image::UIDesignImage; use crate::ui_editor::state::{State, UITree}; @@ -31,7 +32,7 @@ const SYSTEM_PROMPT: &str = r#" 任务： 同时分析同一 UI 系统的全部参考图，建立UI树 -用户会给你一些UI截图(它们从属于同一个UI系统)和对应的元数据, 请用给定的工具描述UI结构 +用户会给你一些UI截图(它们从属于同一个UI系统), 请用给定的工具描述UI结构 识别规则： * 只识别 UI元素. 要区分动态内容, 不要白费力气识别应该由程序生成/绘制的内容.(此类内容应该用一个整体节点+自然语言描述) 除此之外必须完整包含所有元素,结构. @@ -322,6 +323,7 @@ fn convert_node( component: source.component.clone().into_option(), children_display_mode: ChildrenDisplayMode::Stack, children, + offset: NodeOffset::default(), }) } @@ -384,12 +386,6 @@ mod tests { fn test_image() -> UIDesignImage { UIDesignImage { - metadata: crate::ui_editor::resource::ui_design_image::UIDesignImageMetadata { - name: "测试图".to_string(), - description: String::new(), - role: None, - slave_to: None, - }, path: "test.png".to_string(), pixel_size: Vector2::new(1000.0, 500.0), pixels_per_unit: typed_floats::tf32::StrictlyPositiveFinite::new(2.0) @@ -546,7 +542,7 @@ mod tests { #[test] fn conversion_stays_in_the_tree_image_coordinate_system() { - let image_id = UIDesignImageId::new("slave").expect("valid image id"); + let image_id = UIDesignImageId::new("second").expect("valid image id"); let image = test_image(); let root_rect = UIRect::new(Point2::origin(), image_layout_size(&image).unwrap()); let converted = @@ -589,56 +585,29 @@ mod tests { #[test] fn tree_validation_requires_exactly_one_tree_per_context_image() { let page = UIDesignImageId::new("page").expect("valid image id"); - let slave = UIDesignImageId::new("slave").expect("valid image id"); + let second = UIDesignImageId::new("second").expect("valid image id"); let tree = |id: UIDesignImageId| RecognitionTree { src_ui_design_image_id: id, root: test_node(), }; assert!(validate_tree_image_ids( - &[tree(page.clone()), tree(slave.clone())], - &[page.clone(), slave.clone()], + &[tree(page.clone()), tree(second.clone())], + &[page.clone(), second.clone()], ) .is_ok()); assert!( - validate_tree_image_ids(&[tree(page.clone())], &[page.clone(), slave.clone()]).is_err() - ); - assert!( - validate_tree_image_ids(&[tree(page.clone()), tree(page.clone())], &[page, slave],) + validate_tree_image_ids(&[tree(page.clone())], &[page.clone(), second.clone()]) .is_err() ); + assert!(validate_tree_image_ids( + &[tree(page.clone()), tree(page.clone())], + &[page, second], + ) + .is_err()); } } -fn recognition_root_image_ids(state: &State) -> Vec { - state - .ui_design_images - .iter() - .filter_map(|(id, image)| { - let is_page = image.metadata.role - == Some(crate::ui_editor::resource::ui_design_image::UIDesignImageRole::Page); - let is_direct_slave_of_page = image.metadata.slave_to.as_ref().is_some_and(|parent| { - state - .ui_design_images - .get(parent) - .and_then(|parent_image| parent_image.metadata.role) - == Some(crate::ui_editor::resource::ui_design_image::UIDesignImageRole::Page) - }); - (is_page || !is_direct_slave_of_page).then(|| id.clone()) - }) - .collect() -} - -fn slave_image_ids(state: &State, root_id: &UIDesignImageId) -> Vec { - state - .ui_design_images - .iter() - .filter_map(|(id, image)| { - (image.metadata.slave_to.as_ref() == Some(root_id)).then(|| id.clone()) - }) - .collect() -} - pub(crate) async fn recognize_ui_impl_with_provider( project_path: String, state: State, @@ -655,11 +624,7 @@ pub(crate) async fn recognize_ui_impl_with_provider( ); return Err("界面图最多 4 张".to_string()); } - let root_ids = recognition_root_image_ids(&state); - if root_ids.is_empty() { - app_log!("ui_recognition.error stage=validate reason=no_root_image"); - return Err("至少需要一张可作为识别上下文根的界面图".to_string()); - } + let root_ids = state.ui_design_images.keys().cloned().collect::>(); let (llm, client) = if provider_identity.is_none() { let llm = load_game_creator_app_config() .map_err(|error| { @@ -683,12 +648,9 @@ pub(crate) async fn recognize_ui_impl_with_provider( let root = Path::new(project_path.trim()); let mut ui_trees = Vec::with_capacity(root_ids.len()); for root_id in root_ids { - let mut context_ids = vec![root_id.clone()]; - context_ids.extend(slave_image_ids(&state, &root_id)); - // Page 仍可把直接 slave 参考图放在同一识别上下文；没有 Page - // 归属关系的其它界面图各自作为独立上下文根。 + let context_ids = vec![root_id.clone()]; let mut parts = Vec::with_capacity(context_ids.len() * 2); - for (index, context_id) in context_ids.iter().enumerate() { + for context_id in context_ids.iter() { let image = state .ui_design_images .get(context_id) @@ -714,8 +676,7 @@ pub(crate) async fn recognize_ui_impl_with_provider( })?; parts.push(LlmMessageContentPart::InputText { text: format!( - "{} id={} pixel_size={:?}", - if index == 0 { "ROOT" } else { "SLAVE" }, + "ROOT id={} pixel_size={:?}", context_id.as_str(), image.pixel_size ), @@ -768,21 +729,18 @@ pub(crate) async fn recognize_ui_impl_with_provider( !response.text.trim().is_empty(), response.tool_calls.len() ); - let call = response - .tool_calls - .iter() - .find(|call| call.name == "recognize_ui_structure") - .ok_or_else(|| { + let arguments = required_tool_call_arguments(&response, "recognize_ui_structure") + .map_err(|error| { app_log!( - "ui_recognition.error stage=parse_tool_call root={} reason=missing_tool_call", + "ui_recognition.error stage=parse_tool_call reason=missing_tool_call root={} error={error}", root_id.as_str() ); format!( - "根界面图 {} 的 LLM 未返回 recognize_ui_structure 工具调用", + "LLM 未返回 recognize_ui_structure 工具调用（根界面图 {}）", root_id.as_str() ) })?; - let arguments = parse_limited_llm_tool_arguments(&call.arguments).map_err(|error| { + let arguments = parse_limited_llm_tool_arguments(arguments).map_err(|error| { app_log!( "ui_recognition.error stage=parse_arguments root={} error={error}", root_id.as_str() @@ -858,6 +816,7 @@ pub(crate) async fn recognize_ui_impl_with_provider( component: recognition_root.component.into_option(), children_display_mode: ChildrenDisplayMode::Stack, children, + offset: NodeOffset::default(), }; // Tree identity and root identity are assigned by Rust, never chosen by the model. ui_trees.push(UITree { diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/separation/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/separation/mod.rs index 5bdf90008..595dee76e 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/separation/mod.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/separation/mod.rs @@ -22,6 +22,7 @@ mod tests { use crate::ui_editor::layout::control_layout::ControlLayout; use crate::ui_editor::layout::node::Node; use crate::ui_editor::layout::node::{NodeMetadata, NodeSource, StageStatus}; + use crate::ui_editor::layout::offset::NodeOffset; use crate::ui_editor::resource::ui_design_image::UIDesignImage; use crate::ui_editor::state::{State, UITree}; use crate::ui_editor::utils::{NodeId, UIDesignImageId}; @@ -46,6 +47,7 @@ mod tests { component, children_display_mode: ChildrenDisplayMode::Stack, children, + offset: NodeOffset::default(), } } fn state(root: Node) -> State { @@ -58,12 +60,6 @@ mod tests { ui_design_images: HashMap::from([( image_id, UIDesignImage { - metadata: crate::ui_editor::resource::ui_design_image::UIDesignImageMetadata { - name: "page".to_string(), - description: String::new(), - role: None, - slave_to: None, - }, path: "page.png".to_string(), pixel_size: Vector2::new(100.0, 100.0), pixels_per_unit: StrictlyPositiveFinite::new(1.0).unwrap(), diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/ui_design_suggestion.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/ui_design_suggestion.rs deleted file mode 100644 index 613d44b7b..000000000 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/ui_design_suggestion.rs +++ /dev/null @@ -1,350 +0,0 @@ -use crate::config::build_game_creator_llm_client_from_llm_config; -use crate::config::load_game_creator_app_config; -use crate::ui_editor::commands::utils::{ - parse_limited_llm_tool_arguments, read_ui_reference_image_data_url, request_ui_editor_llm, - strict_json_schema, -}; -use crate::ui_editor::resource::ui_design_image::UIDesignImageRole; -use crate::ui_editor::state::State; -use crate::ui_editor::utils::UIDesignImageId; -use platform_llm::{ - LlmFunctionTool, LlmMessage, LlmMessageContentPart, LlmRunRequest, LlmToolChoice, -}; -use schemars::JsonSchema; -use serde::{Deserialize, Serialize}; -use std::collections::HashSet; -use std::path::Path; -use ts_rs::TS; - -const SYSTEM_PROMPT: &str = r#" -请识别这些 UI 参考图的界面语义，并调用 suggest_ui_design_semantics 工具返回结果。 -不要在工具调用外输出 JSON、Markdown、代码围栏、注释、额外字段或解释文字。 - -字段含义： -- id：必填，必须逐字匹配当前输入参考图的 id。它标识“这条建议属于哪张图”，不是新 ID，不能为 null。 -- name：要写入该图片 metadata 的简短、可读名称； -- description：要写入该图片 metadata 的简短语义描述，例如“带底部导航的主游戏页面”。 -- role：要写入该图片 metadata 的界面角色。 - Page 表示完整主页面， - Section 表示同一主页面中的子界面或页签， - Modal/Drawer/Popover 表示浮层或局部覆盖界面， - State 表示同一界面的状态变体， - Scrolled 表示滚动或分页后的内容， - Detail 表示局部详情或补充证据。 -- children：该节点直接包含的子界面图。 - -- 根节点必须是 Page，子节点不能是 Page - -所有字段都必须出现，禁止省略字段、使用 null 或返回空字符串。每张参考图最多出现一次；id 必须逐字匹配输入图片 id。 -以下 UI 设计图中的 metadata 部分信息已确定，请根据已有信息补全语义. -"#; -#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, TS, JsonSchema)] -#[schemars(deny_unknown_fields)] -#[serde(deny_unknown_fields)] -#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/ui-editor/types/"))] -pub struct UIDesignSuggestionTreeNode { - pub id: UIDesignImageId, - pub name: String, - pub description: String, - pub role: UIDesignImageRole, - pub children: Vec, -} - -#[derive(Clone, Debug, Deserialize, JsonSchema)] -#[schemars(deny_unknown_fields)] -#[serde(deny_unknown_fields)] -struct UIDesignSuggestion { - ui_designs: Vec, -} - -fn ui_design_suggestion_json_schema() -> Result { - strict_json_schema::() -} - -const MAX_REFERENCES: usize = 4; -const MAX_SUGGESTION_TREE_DEPTH: usize = 4; - -fn validate_suggestion_response_shape(value: &serde_json::Value) -> Result<(), String> { - let roots = value - .get("ui_designs") - .and_then(serde_json::Value::as_array) - .ok_or_else(|| "UI 语义建议工具参数缺少 ui_designs 数组".to_string())?; - let mut stack = roots.iter().map(|node| (node, 1usize)).collect::>(); - let mut node_count = 0usize; - while let Some((node, depth)) = stack.pop() { - if depth > MAX_SUGGESTION_TREE_DEPTH { - return Err(format!( - "UI 语义建议树最大深度不能超过 {MAX_SUGGESTION_TREE_DEPTH}" - )); - } - node_count += 1; - if node_count > MAX_REFERENCES { - return Err(format!("UI 语义建议最多包含 {MAX_REFERENCES} 个节点")); - } - let children = node - .get("children") - .and_then(serde_json::Value::as_array) - .ok_or_else(|| "UI 语义建议节点缺少 children 数组".to_string())?; - stack.extend(children.iter().map(|child| (child, depth + 1))); - } - Ok(()) -} - -fn validate_suggestions( - suggestions: &[UIDesignSuggestionTreeNode], - image_ids: &HashSet, -) -> Result<(), String> { - let mut seen = HashSet::new(); - - fn visit( - nodes: &[UIDesignSuggestionTreeNode], - is_root: bool, - image_ids: &HashSet, - seen: &mut HashSet, - ) -> Result<(), String> { - for node in nodes { - if !image_ids.contains(&node.id) { - return Err("LLM 返回了未知界面图 ID".to_string()); - } - if !seen.insert(node.id.clone()) { - return Err("LLM 返回了重复界面图建议".to_string()); - } - if node.name.trim().is_empty() || node.description.trim().is_empty() { - return Err("界面图语义字段不能是空字符串".to_string()); - } - if is_root { - if node.role != UIDesignImageRole::Page { - return Err("界面图树根节点必须是 Page".to_string()); - } - } else if node.role == UIDesignImageRole::Page { - return Err("Page 不能作为其它界面图的子节点".to_string()); - } - visit(&node.children, false, image_ids, seen)?; - } - Ok(()) - } - - visit(suggestions, true, image_ids, &mut seen)?; - if seen != *image_ids { - return Err("LLM 未为每张界面图返回语义建议".to_string()); - } - Ok(()) -} - -#[tauri::command] -pub(crate) async fn suggest_ui_design_semantic_impl( - project_path: String, - state: State, -) -> Result, String> { - if state.ui_design_images.is_empty() { - app_log!("ui_design_suggestion.error stage=validate reason=no_images"); - return Err("请先导入界面图".to_string()); - } - if state.ui_design_images.len() > MAX_REFERENCES { - app_log!( - "ui_design_suggestion.error stage=validate reason=too_many_images count={}", - state.ui_design_images.len() - ); - return Err("界面图最多 4 张".to_string()); - } - let root = Path::new(project_path.trim()); - let mut parts = Vec::new(); - let mut ids = HashSet::new(); - for (id, image) in &state.ui_design_images { - ids.insert(id.clone()); - let absolute = - crate::project::resolve_local_project_path(root, &image.path).map_err(|error| { - app_log!( - "ui_design_suggestion.error stage=resolve_image id={} error={error}", - id.as_str() - ); - error - })?; - let image_url = read_ui_reference_image_data_url(absolute) - .await - .map_err(|error| { - app_log!( - "ui_design_suggestion.error stage=read_image id={} error={error}", - id.as_str() - ); - error - })?; - parts.push(LlmMessageContentPart::InputText { - text: format!("REFERENCE id:{} metadata:{}", id.as_str(), image.metadata,), - }); - parts.push(LlmMessageContentPart::InputImage { image_url }); - } - let llm = load_game_creator_app_config() - .map_err(|error| { - eprintln!("ui_design_suggestion.error stage=build_client error={error}"); - error - })? - .llm; - let client = build_game_creator_llm_client_from_llm_config(&llm, "llm").map_err(|error| { - app_log!("ui_design_suggestion.error stage=build_client error={error}"); - error - })?; - let schema = ui_design_suggestion_json_schema().map_err(|error| { - app_log!("ui_design_suggestion.error stage=build_schema error={error}"); - error - })?; - let tool = LlmFunctionTool::new( - "suggest_ui_design_semantics", - "为所有 UI 参考图补全界面语义 metadata", - schema, - ) - .with_strict(true); - let response = request_ui_editor_llm( - &client, - &llm, - LlmRunRequest::new(vec![ - LlmMessage::system(SYSTEM_PROMPT), - LlmMessage::user_multimodal(parts), - ]) - .with_function_tools(vec![tool]) - .with_tool_choice(LlmToolChoice::Required), - ) - .await - .map_err(|error| { - app_log!("ui_design_suggestion.error stage=llm_request error={error}"); - format!("UI 参考图语义识别失败：{error}") - })?; - app_log!( - "ui_design_suggestion.llm_output text_present={} tool_call_count={}", - !response.text.trim().is_empty(), - response.tool_calls.len() - ); - let call = response - .tool_calls - .iter() - .find(|call| call.name == "suggest_ui_design_semantics") - .ok_or_else(|| { - app_log!("ui_design_suggestion.error stage=parse_tool_call reason=missing_tool_call"); - "LLM 响应无效（详情：未返回 suggest_ui_design_semantics 工具调用）".to_string() - })?; - let arguments = parse_limited_llm_tool_arguments(&call.arguments).map_err(|error| { - app_log!("ui_design_suggestion.error stage=parse_arguments error={error}"); - format!("LLM 响应无效（详情：UI 语义建议工具参数无效：{error}）") - })?; - validate_suggestion_response_shape(&arguments).map_err(|error| { - app_log!("ui_design_suggestion.error stage=validate_arguments error={error}"); - format!("LLM 响应无效（详情：{error}）") - })?; - let suggestions = serde_json::from_value::(arguments) - .map_err(|error| { - app_log!("ui_design_suggestion.error stage=parse_arguments error={error}"); - format!("LLM 响应无效（详情：UI 语义建议工具参数无效：{error}）") - })? - .ui_designs; - validate_suggestions(&suggestions, &ids).map_err(|error| { - app_log!("ui_design_suggestion.error stage=validate_result error={error}"); - format!("LLM 响应无效（详情：{error}）") - })?; - Ok(suggestions) -} - -#[cfg(test)] -mod tests { - use super::*; - - fn id(value: &str) -> UIDesignImageId { - UIDesignImageId::new(value).expect("valid image id") - } - - fn node( - value: &str, - role: UIDesignImageRole, - children: Vec, - ) -> UIDesignSuggestionTreeNode { - UIDesignSuggestionTreeNode { - id: id(value), - name: value.to_string(), - description: format!("{value} description"), - role, - children, - } - } - - fn image_ids(values: &[&str]) -> HashSet { - values.iter().map(|value| id(value)).collect() - } - - #[test] - fn validates_page_tree() { - let suggestions = vec![node( - "page", - UIDesignImageRole::Page, - vec![node("section", UIDesignImageRole::Section, Vec::new())], - )]; - assert!(validate_suggestions(&suggestions, &image_ids(&["page", "section"])).is_ok()); - } - - #[test] - fn suggestion_shape_rejects_more_than_four_nodes_or_four_levels() { - let oversized = (0..=MAX_REFERENCES) - .map(|_| serde_json::json!({"children": []})) - .collect::>(); - assert!(validate_suggestion_response_shape(&serde_json::json!({ - "ui_designs": oversized - })) - .is_err()); - - let mut nested = serde_json::json!({"children": []}); - for _ in 0..MAX_SUGGESTION_TREE_DEPTH { - nested = serde_json::json!({"children": [nested]}); - } - assert!(validate_suggestion_response_shape(&serde_json::json!({ - "ui_designs": [nested] - })) - .is_err()); - } - - #[test] - fn rejects_duplicate_and_unknown_ids() { - let duplicate = vec![ - node( - "page", - UIDesignImageRole::Page, - vec![node("section", UIDesignImageRole::Section, Vec::new())], - ), - node("page", UIDesignImageRole::Page, Vec::new()), - ]; - assert!(validate_suggestions(&duplicate, &image_ids(&["page", "section"])).is_err()); - - let unknown = vec![node("missing", UIDesignImageRole::Page, Vec::new())]; - assert!(validate_suggestions(&unknown, &image_ids(&["page"])).is_err()); - } - - #[test] - fn rejects_invalid_root_roles_and_nested_pages() { - let non_page_root = vec![node("section", UIDesignImageRole::Section, Vec::new())]; - assert!(validate_suggestions(&non_page_root, &image_ids(&["section"])).is_err()); - - let nested_page = vec![node( - "page", - UIDesignImageRole::Page, - vec![node("nested", UIDesignImageRole::Page, Vec::new())], - )]; - assert!(validate_suggestions(&nested_page, &image_ids(&["page", "nested"])).is_err()); - } - - #[test] - fn strict_schema_requires_tree_fields() { - let schema = ui_design_suggestion_json_schema().expect("schema"); - assert_eq!(schema["required"], serde_json::json!(["ui_designs"])); - let node_schema = &schema["properties"]["ui_designs"]["items"]; - let required = node_schema["required"] - .as_array() - .expect("node required") - .iter() - .filter_map(serde_json::Value::as_str) - .collect::>(); - assert_eq!( - required, - ["id", "name", "description", "role", "children"] - .into_iter() - .collect() - ); - assert_eq!(node_schema["additionalProperties"], false); - } -} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/utils.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/utils.rs index 852a23c9d..990458054 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/utils.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/utils.rs @@ -95,6 +95,18 @@ pub(crate) fn parse_limited_llm_tool_arguments( serde_json::from_str(arguments).map_err(|error| format!("LLM 工具参数不是有效 JSON：{error}")) } +pub(crate) fn required_tool_call_arguments<'a>( + response: &'a LlmRunResponse, + tool_name: &str, +) -> Result<&'a str, String> { + response + .tool_calls + .iter() + .find(|call| call.name == tool_name) + .map(|call| call.arguments.as_str()) + .ok_or_else(|| format!("LLM 未返回 {tool_name} 工具调用")) +} + pub(crate) async fn read_ui_reference_image_data_url(path: PathBuf) -> Result { tokio::task::spawn_blocking(move || read_ui_reference_image_data_url_blocking(&path)) .await diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/html_renderer/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/html_renderer/mod.rs index 72753a218..ed90c9366 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/html_renderer/mod.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/html_renderer/mod.rs @@ -45,8 +45,6 @@ pub(crate) fn render_ui_design_state_js( "genarrative-ui-tree", json!({ "srcUiDesign": tree.src_ui_design.as_str(), - "name": image.metadata.name, - "description": image.metadata.description, }), ) .into_string(); diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/mod.rs index b0932dc49..661e31743 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/mod.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/mod.rs @@ -2,4 +2,5 @@ pub mod children_display_mode; pub mod control_layout; pub mod dimension; pub mod node; +pub mod offset; pub mod transform; diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/node.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/node.rs index be70cdca6..17ecbd346 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/node.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/node.rs @@ -1,6 +1,7 @@ use crate::ui_editor::component::Component; use crate::ui_editor::layout::children_display_mode::ChildrenDisplayMode; use crate::ui_editor::layout::control_layout::ControlLayout; +use crate::ui_editor::layout::offset::NodeOffset; use crate::ui_editor::utils::NodeId; use serde::{Deserialize, Serialize}; use ts_rs::TS; @@ -14,6 +15,21 @@ pub struct Node { pub component: Option, pub children_display_mode: ChildrenDisplayMode, pub children: Vec, + // 偏移量是后加的字段：历史设计文档没有它，默认回落到零偏移，保证旧文档仍可读。 + #[serde(default)] + pub offset: NodeOffset, +} + +impl Node { + /// 深度优先查找节点，用可变引用定位，镜像前端 `findUiNodeLocation` 的定位部分。 + pub fn find_mut(&mut self, node_id: &NodeId) -> Option<&mut Node> { + if &self.id == node_id { + return Some(self); + } + self.children + .iter_mut() + .find_map(|child| child.find_mut(node_id)) + } } #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, TS)] diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/offset.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/offset.rs new file mode 100644 index 000000000..069dadbac --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/layout/offset.rs @@ -0,0 +1,20 @@ +use serde::{Deserialize, Serialize}; +use ts_rs::TS; + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, TS)] +#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/ui-editor/types/"))] +pub struct NodeOffset { + #[ts(as = "[f32; 2]")] + pub min: [f32; 2], + #[ts(as = "[f32; 2]")] + pub max: [f32; 2], +} + +impl Default for NodeOffset { + fn default() -> Self { + Self { + min: [0.0, 0.0], + max: [0.0, 0.0], + } + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/mod.rs index 51fb28ec3..fa2ccf15a 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/mod.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/mod.rs @@ -1,10 +1,9 @@ +pub(crate) mod agent_tools; pub mod commands; pub mod component; pub(crate) mod html_renderer; pub mod layout; pub mod persistence; pub mod resource; -pub mod resource_bridge; pub mod state; mod utils; -pub(crate) mod workflow; diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/persistence.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/persistence.rs index e089532df..c03c63e70 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/persistence.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/persistence.rs @@ -2,9 +2,7 @@ use crate::ui_editor::component::text::FontSource; use crate::ui_editor::component::Component; use crate::ui_editor::html_renderer::render_ui_design_state_js; use crate::ui_editor::layout::node::Node; -use crate::ui_editor::resource::ui_design_image::{ - UIDesignImage, UIDesignImageMetadata, UIDesignImageRole, -}; +use crate::ui_editor::resource::ui_design_image::UIDesignImage; use crate::ui_editor::state::State; use crate::ui_editor::utils::UIDesignImageId; use crate::*; @@ -27,7 +25,7 @@ pub(crate) use shared_contracts::game_creation_app::{ }; const UI_DESIGN_STATE_MAX_BYTES: usize = 2 * 1024 * 1024; const UI_DESIGN_CODE_MAX_BYTES: usize = UI_DESIGN_STATE_MAX_BYTES * 8; -const UI_DESIGN_STATE_MAX_IMAGES: usize = 4; +pub(crate) const UI_DESIGN_STATE_MAX_IMAGES: usize = 4; const UI_DESIGN_STATE_MAX_SPRITES: usize = 1_024; pub(crate) const UI_DESIGN_STATE_MAX_NODES: usize = 10_000; const UI_DESIGN_STATE_MAX_DEPTH: usize = 128; @@ -116,42 +114,53 @@ pub(crate) fn initialize_ui_design_state_at( Ok(()) } -/// Initializes a newly bridged UI design with the source prototype as its first -/// design image. The bridge holds the project write lock, so this helper only -/// installs revision zero and never advances the project revision itself. -pub(crate) fn initialize_ui_design_state_with_source_image_at( +/// 新建文档时要装进文档的设计图：文档内身份取图片在 manifest 里的 assetId。 +pub(crate) struct UiDesignDocumentImage { + pub(crate) image_id: String, + pub(crate) path: String, + pub(crate) pixel_size: (u32, u32), +} + +/// Installs the given design images into a brand new UI design document at +/// revision zero. Callers hold the project write lock, so this helper never +/// advances the project revision itself. +pub(crate) fn initialize_ui_design_state_with_images_at( root: &Path, project_id: &str, asset_id: &str, - source_image_id: &str, - source_image_path: &str, - pixel_size: (u32, u32), + images: &[UiDesignDocumentImage], ) -> Result<(), String> { let asset = ui_design_asset(root, project_id, asset_id)?; - let source_image_id = required_identifier(source_image_id, "sourceImageId")?; - let source_image_path = normalize_relative_path(source_image_path.trim())?; - if pixel_size.0 == 0 || pixel_size.1 == 0 { - return Err("源 UI 原型图片尺寸无效".to_string()); + if images.is_empty() { + return Err("UI 设计文档至少需要一张设计图".to_string()); } let pixels_per_unit = - StrictlyPositiveFinite::new(1.0).map_err(|_| "UI 原型图片像素比例无效".to_string())?; + StrictlyPositiveFinite::new(1.0).map_err(|_| "UI 设计图像素比例无效".to_string())?; let mut document = empty_document(project_id, asset_id); - let source_image_id = UIDesignImageId::new(source_image_id) - .map_err(|error| format!("sourceImageId 无效：{error}"))?; - document.state.ui_design_images.insert( - source_image_id, - UIDesignImage { - metadata: UIDesignImageMetadata { - name: "游戏界面原型".to_string(), - description: "由画布 UI 原型桥接载入".to_string(), - role: Some(UIDesignImageRole::Page), - slave_to: None, - }, - path: source_image_path, - pixel_size: Vector2::new(pixel_size.0 as f32, pixel_size.1 as f32), - pixels_per_unit, - }, - ); + for image in images { + let image_id = required_identifier(&image.image_id, "designImageId")?; + let path = normalize_relative_path(image.path.trim())?; + if image.pixel_size.0 == 0 || image.pixel_size.1 == 0 { + return Err("UI 设计图尺寸无效".to_string()); + } + let image_id = UIDesignImageId::new(image_id) + .map_err(|error| format!("designImageId 无效：{error}"))?; + if document + .state + .ui_design_images + .insert( + image_id, + UIDesignImage { + path, + pixel_size: Vector2::new(image.pixel_size.0 as f32, image.pixel_size.1 as f32), + pixels_per_unit, + }, + ) + .is_some() + { + return Err("UI 设计文档的设计图不能重复".to_string()); + } + } write_ui_design_document(root, &asset.local_path, &document)?; let installed = read_ui_design_document(root, &asset.local_path, project_id, asset_id)?; validate_document(&installed, project_id, asset_id)?; @@ -162,16 +171,28 @@ pub(crate) fn load_ui_design_state_at( input: LoadUiDesignStateInput, ) -> Result { let root = Path::new(input.project_path.trim()); - let expected_project_id = required_identifier(&input.expected_project_id, "expectedProjectId")?; - let asset_id = required_identifier(&input.asset_id, "assetId")?; + Ok(load_ui_design_document_snapshot_at(root, &input.expected_project_id, &input.asset_id)?.1) +} + +/// 读取文档的登记路径与当前快照。工作流编排要据此定位检查点日志与起始 revision。 +pub(crate) fn load_ui_design_document_snapshot_at( + root: &Path, + expected_project_id: &str, + asset_id: &str, +) -> Result<(String, UiDesignStateSnapshot), String> { + let expected_project_id = required_identifier(expected_project_id, "expectedProjectId")?; + let asset_id = required_identifier(asset_id, "assetId")?; let asset = ui_design_asset(root, &expected_project_id, &asset_id)?; let document = read_ui_design_document(root, &asset.local_path, &expected_project_id, &asset_id)?; validate_document(&document, &expected_project_id, &asset_id)?; - Ok(UiDesignStateSnapshot { - revision: document.revision, - state: document.state, - }) + Ok(( + asset.local_path, + UiDesignStateSnapshot { + revision: document.revision, + state: document.state, + }, + )) } pub(crate) fn generate_ui_design_code_at( @@ -616,16 +637,7 @@ fn validate_state(state: &State) -> Result<(), String> { { return Err("界面图像素尺寸必须为正有限数值".to_string()); } - if image - .metadata - .slave_to - .as_ref() - .is_some_and(|owner| !state.ui_design_images.contains_key(owner)) - { - return Err("界面图 slaveTo 引用了不存在的界面图".to_string()); - } } - validate_slave_to_acyclic(state)?; for (id, sprite) in &state.sprite_assets { validate_id(id.as_str(), "独立素材 ID")?; if sprite.asset_id != *id { @@ -651,23 +663,6 @@ fn validate_state(state: &State) -> Result<(), String> { Ok(()) } -fn validate_slave_to_acyclic(state: &State) -> Result<(), String> { - for start in state.ui_design_images.keys() { - let mut current = Some(start); - let mut visited = HashSet::new(); - while let Some(id) = current { - if !visited.insert(id) { - return Err("界面图 slaveTo 不能形成循环".to_string()); - } - current = state - .ui_design_images - .get(id) - .and_then(|image| image.metadata.slave_to.as_ref()); - } - } - Ok(()) -} - fn validate_node( node: &Node, state: &State, @@ -715,6 +710,11 @@ fn validate_node( { return Err("UI 节点 Transform 必须是有限数值".to_string()); } + if !node.offset.min.iter().all(|value| value.is_finite()) + || !node.offset.max.iter().all(|value| value.is_finite()) + { + return Err("UI 节点 offset 必须是有限数值".to_string()); + } if node .layout .transform @@ -837,6 +837,7 @@ fn validate_id(value: &str, label: &str) -> Result<(), String> { #[cfg(test)] mod tests { use super::*; + use crate::ui_editor::layout::offset::NodeOffset; const PROJECT_ID: &str = "ui-design-persistence-project"; @@ -1052,12 +1053,6 @@ mod tests { "ui_trees": [], "ui_design_images": { "page": { - "metadata": { - "name": "主界面", - "description": "", - "role": "Page", - "slave_to": null - }, "path": path, "pixel_size": [1280.0, 720.0], "pixels_per_unit": 1.0 @@ -1130,18 +1125,14 @@ mod tests { } }, "children_display_mode": "Stack", - "children": [] - }] + "children": [], + "offset": { "min": [0.0, 0.0], "max": [0.0, 0.0] } + }], + "offset": { "min": [0.0, 0.0], "max": [0.0, 0.0] } } }], "ui_design_images": { "page": { - "metadata": { - "name": "主界面", - "description": "", - "role": "Page", - "slave_to": null - }, "path": "assets/page.png", "pixel_size": [1280.0, 720.0], "pixels_per_unit": 1.0 @@ -1313,17 +1304,12 @@ mod tests { }, "component": null, "children_display_mode": "Stack", - "children": [] + "children": [], + "offset": { "min": [0.0, 0.0], "max": [0.0, 0.0] } } }], "ui_design_images": { "page": { - "metadata": { - "name": "主界面", - "description": "", - "role": "Page", - "slave_to": null - }, "path": "missing.png", "pixel_size": [1280.0, 720.0], "pixels_per_unit": 1.0 @@ -1341,29 +1327,43 @@ mod tests { } #[test] - fn rejects_cyclic_slave_to_relationships() { + fn rejects_non_finite_node_offset() { let state: State = serde_json::from_value(serde_json::json!({ - "ui_trees": [], + "ui_trees": [{ + "src_ui_design": "page", + "root": { + "id": "root", + "layout": { + "transform": { + "anchor_min": [0.0, 0.0], + "anchor_max": [1.0, 1.0], + "offset_min": [0.0, 0.0], + "offset_max": [0.0, 0.0] + }, + "custom_minimum_size": [0.0, 0.0], + "size_flags_horizontal": 1, + "size_flags_vertical": 1, + "size_flags_stretch_ratio": 1.0, + "container": "None" + }, + "metadata": { + "name": "根节点", + "description": "", + "layout_status": "NoProblem", + "component_status": "NoProblem", + "allow_llm_edit_layout": true, + "allow_llm_edit_component": true, + "source": "System" + }, + "component": null, + "children_display_mode": "Stack", + "children": [], + "offset": { "min": [0.0, 0.0], "max": [1280.0, 720.0] } + } + }], "ui_design_images": { "page": { - "metadata": { - "name": "主界面", - "description": "", - "role": "Page", - "slave_to": "section" - }, - "path": "page.png", - "pixel_size": [1280.0, 720.0], - "pixels_per_unit": 1.0 - }, - "section": { - "metadata": { - "name": "子页面", - "description": "", - "role": "Section", - "slave_to": "page" - }, - "path": "section.png", + "path": "missing.png", "pixel_size": [1280.0, 720.0], "pixels_per_unit": 1.0 } @@ -1371,11 +1371,14 @@ mod tests { "sprite_assets": {}, "font_assets": {} })) - .expect("deserialize cyclic state"); + .expect("deserialize state with ordered offset"); + assert_eq!(validate_state(&state), Ok(())); + let mut invalid = state; + invalid.ui_trees[0].root.offset.min[1] = f32::INFINITY; assert_eq!( - validate_state(&state), - Err("界面图 slaveTo 不能形成循环".to_string()) + validate_state(&invalid), + Err("UI 节点 offset 必须是有限数值".to_string()) ); } @@ -1503,6 +1506,43 @@ mod tests { .is_err()); } + /// 历史设计文档没有节点 `offset` 字段：缺字段必须按零偏移解析，不能判成缺字段损坏。 + #[test] + fn legacy_nodes_without_offset_field_fall_back_to_zero_offset() { + let mut value = serde_json::to_value(state_with_sprite_and_dragged_transform()) + .expect("serialize dragged UI design state"); + strip_offset_fields(&mut value); + let state: State = serde_json::from_value(value).expect("节点缺 offset 时仍可解析"); + assert_eq!( + state.ui_trees[0].root.offset, + NodeOffset::default(), + "根节点缺 offset 时回落零偏移" + ); + assert_eq!( + state.ui_trees[0].root.children[0].offset, + NodeOffset::default(), + "子节点缺 offset 时回落零偏移" + ); + } + + /// 递归删除夹具里所有节点级 `offset` 字段，模拟该字段引入前落盘的文档。 + fn strip_offset_fields(value: &mut serde_json::Value) { + match value { + serde_json::Value::Object(fields) => { + fields.remove("offset"); + for field in fields.values_mut() { + strip_offset_fields(field); + } + } + serde_json::Value::Array(items) => { + for item in items { + strip_offset_fields(item); + } + } + _ => {} + } + } + #[test] fn rejects_text_component_with_missing_font_asset() { let (directory, asset_id) = fixture(); @@ -1547,17 +1587,12 @@ mod tests { } }, "children_display_mode": "Stack", - "children": [] + "children": [], + "offset": { "min": [0.0, 0.0], "max": [0.0, 0.0] } } }], "ui_design_images": { "page": { - "metadata": { - "name": "主界面", - "description": "", - "role": "Page", - "slave_to": null - }, "path": "assets/page.png", "pixel_size": [1280.0, 720.0], "pixels_per_unit": 1.0 diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource/sprite.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource/sprite.rs index 498fb0437..408a47379 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource/sprite.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource/sprite.rs @@ -119,6 +119,23 @@ impl SpriteAsset { &self.asset_id } + pub fn path(&self) -> &str { + &self.path + } + + /// 用一张已登记图片建自动切分素材：名称与类型留给人工填写，路径取资源路径， + /// 像素比固定为 1，九宫格为无边框。镜像前端 `prepareSpriteAssetBatch`。 + pub(crate) fn from_registered_image( + asset_id: SpriteAssetId, + path: String, + pixel_size: Vector2, + pixels_per_unit: StrictlyPositiveFinite, + ) -> Result { + let mut sprite = Self::new(asset_id, pixel_size, pixels_per_unit, SpriteBorder::NONE)?; + sprite.path = path; + Ok(sprite) + } + pub fn pixel_size(&self) -> Vector2 { self.pixel_size } diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource/ui_design_image.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource/ui_design_image.rs index d1f3b7714..7c18fa7c2 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource/ui_design_image.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource/ui_design_image.rs @@ -1,48 +1,14 @@ -use crate::ui_editor::utils::UIDesignImageId; use nalgebra::Vector2; -use schemars::JsonSchema; use serde::{Deserialize, Serialize}; -use std::fmt::{Display, Formatter}; use ts_rs::TS; use typed_floats::tf32::StrictlyPositiveFinite; -#[derive(Clone, Copy, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize, TS)] -#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/ui-editor/types/"))] -pub enum UIDesignImageRole { - Page, - Section, - Modal, - Drawer, - Popover, - State, - Scrolled, - Detail, -} - #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, TS)] #[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/ui-editor/types/"))] pub struct UIDesignImage { - pub(crate) metadata: UIDesignImageMetadata, pub(crate) path: String, #[ts(as = "[f32; 2]")] pub(crate) pixel_size: Vector2, #[ts(as = "f32")] pub(crate) pixels_per_unit: StrictlyPositiveFinite, } -#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, TS)] -#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/ui-editor/types/"))] -pub struct UIDesignImageMetadata { - pub(crate) name: String, - pub(crate) description: String, - pub(crate) role: Option, - pub(crate) slave_to: Option, -} -impl Display for UIDesignImageMetadata { - fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { - write!( - f, - "name: {}, description: {}, role: {:?}, slave_to: {:?}", - self.name, self.description, self.role, self.slave_to - ) - } -} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource_bridge.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource_bridge.rs deleted file mode 100644 index dc76ce37c..000000000 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource_bridge.rs +++ /dev/null @@ -1,339 +0,0 @@ -use crate::ui_editor::persistence::{ - initialize_ui_design_state_with_source_image_at, UI_DESIGN_DOC_ASSET_KIND, - UI_DESIGN_DOC_MEDIA_TYPE, -}; -use crate::{ - acquire_project_write_lock, advance_agent_runtime_project_revision_locked, - enforce_project_permission_policy, read_existing_manifest_for_project, - read_game_creator_agent_runtime_project_revision, register_local_asset_at, - resolve_local_project_path, write_manifest, GameCreationAppAssetManifestEntry, - GameCreationAppAssetSource, GameCreationAppAssetSourceKind, GameCreationAppManifest, -}; -use image::GenericImageView; -use serde::{Deserialize, Serialize}; -use shared_contracts::game_creation_app::GameCreationAppAssetKind; -use std::fs; -use std::path::Path; - -#[derive(Clone, Debug, Deserialize)] -#[serde(deny_unknown_fields, rename_all = "camelCase")] -pub(crate) struct EnsureUiDesignResourceForPrototypeInput { - pub(crate) project_path: String, - pub(crate) expected_project_id: String, - pub(crate) prototype_asset_id: String, -} - -#[derive(Clone, Debug, PartialEq, Serialize)] -#[serde(rename_all = "camelCase")] -pub(crate) struct EnsureUiDesignResourceForPrototypeResult { - pub(crate) asset: GameCreationAppAssetManifestEntry, - pub(crate) manifest: GameCreationAppManifest, - pub(crate) committed_project_revision: u64, - pub(crate) created: bool, -} - -pub(crate) fn ensure_ui_design_resource_for_prototype( - input: EnsureUiDesignResourceForPrototypeInput, -) -> Result { - let root = Path::new(input.project_path.trim()); - let expected_project_id = input.expected_project_id.trim(); - let prototype_asset_id = input.prototype_asset_id.trim(); - if expected_project_id.is_empty() || prototype_asset_id.is_empty() { - return Err("UI 原型桥接参数不能为空".to_string()); - } - enforce_project_permission_policy(root, "asset.register")?; - let _lock = acquire_project_write_lock(root, "asset.register")?; - let manifest = read_existing_manifest_for_project(root)?; - if manifest.project_id != expected_project_id { - return Err("project-identity-conflict".to_string()); - } - let prototype = manifest - .assets - .iter() - .find(|asset| asset.id == prototype_asset_id) - .ok_or_else(|| "UI 原型资产不存在".to_string())?; - if prototype.kind != GameCreationAppAssetKind::UiDesign - || !prototype - .media_type - .to_ascii_lowercase() - .starts_with("image/") - { - return Err("目标资产不是可桥接的 UI 原型图片".to_string()); - } - let source_path = prototype.local_path.clone(); - let source_reference_ids = [ - Some(prototype_asset_id), - prototype.source.resource_id.as_deref(), - prototype.source.asset_object_id.as_deref(), - ] - .into_iter() - .flatten() - .filter(|reference| !reference.trim().is_empty()) - .collect::>(); - let association_reference_id = prototype - .source - .resource_id - .as_deref() - .filter(|reference| !reference.trim().is_empty()) - .or_else(|| { - prototype - .source - .asset_object_id - .as_deref() - .filter(|reference| !reference.trim().is_empty()) - }) - .unwrap_or(prototype_asset_id) - .to_string(); - let source_absolute_path = resolve_local_project_path(root, &source_path)?; - let dimensions = image::open(&source_absolute_path) - .map_err(|error| format!("读取 UI 原型图片失败：{error}"))? - .dimensions(); - if dimensions.0 == 0 || dimensions.1 == 0 { - return Err("UI 原型图片尺寸无效".to_string()); - } - - if let Some(asset) = manifest.assets.iter().find(|asset| { - asset.kind == UI_DESIGN_DOC_ASSET_KIND - && asset.media_type == UI_DESIGN_DOC_MEDIA_TYPE - && asset.source.reference_resource_ids.iter().any(|reference| { - source_reference_ids - .iter() - .any(|expected| reference == expected) - }) - }) { - let revision = read_game_creator_agent_runtime_project_revision(root)?.revision; - return Ok(EnsureUiDesignResourceForPrototypeResult { - asset: asset.clone(), - manifest, - committed_project_revision: revision, - created: false, - }); - } - - let (resource_name, relative_path) = next_ui_design_path(root, &manifest)?; - let absolute_path = resolve_local_project_path(root, &relative_path)?; - if let Some(parent) = absolute_path.parent() { - fs::create_dir_all(parent) - .map_err(|error| format!("创建 UI 资源目录失败：{}: {error}", parent.display()))?; - } - fs::write(&absolute_path, "") - .map_err(|error| format!("创建 UI 资源失败：{}: {error}", absolute_path.display()))?; - - let asset = match register_local_asset_at( - root, - &relative_path, - GameCreationAppAssetKind::UiDesignDoc, - UI_DESIGN_DOC_MEDIA_TYPE, - "generated", - GameCreationAppAssetSource { - kind: GameCreationAppAssetSourceKind::Generated, - canvas_project_id: None, - resource_id: Some(format!( - "ui:{}", - resource_name.trim_start_matches("UI 设计 ") - )), - asset_object_id: None, - task_id: None, - prompt: None, - model: None, - generation_route: None, - generation_kind: None, - reference_resource_ids: vec![association_reference_id], - }, - ) { - Ok(result) => result, - Err(error) => { - let _ = fs::remove_file(&absolute_path); - return Err(error); - } - }; - - if let Err(error) = initialize_ui_design_state_with_source_image_at( - root, - expected_project_id, - &asset.id, - prototype_asset_id, - &source_path, - dimensions, - ) { - let rollback = (|| { - let mut current = read_existing_manifest_for_project(root)?; - current.assets.retain(|entry| entry.id != asset.id); - write_manifest(&root.join(".agent/manifest.json"), ¤t)?; - fs::remove_file(&absolute_path) - .map_err(|remove_error| format!("删除未完成 UI 设计资源失败：{remove_error}")) - })(); - return match rollback { - Ok(()) => Err(error), - Err(rollback_error) => Err(format!( - "UI 设计资源初始化失败：{error}；reconciliation-required: 回滚未完成：{rollback_error}" - )), - }; - } - - let committed_project_revision = - advance_agent_runtime_project_revision_locked(root).map_err(|error| { - format!("reconciliation-required: UI 设计资源已创建，但项目 revision 未能推进：{error}") - })?; - let manifest = read_existing_manifest_for_project(root)?; - let asset = manifest - .assets - .iter() - .find(|entry| entry.id == asset.id) - .cloned() - .ok_or_else(|| "UI 设计资源创建后无法从 manifest 回读".to_string())?; - Ok(EnsureUiDesignResourceForPrototypeResult { - asset, - manifest, - committed_project_revision, - created: true, - }) -} - -/// UI 设计文档的确定性命名：从已登记文档数 + 1 起找第一个既未被占用、 -/// 也未登记进 manifest 的 `ui/UI 设计 N.json`，不覆盖任何既有文件。 -pub(crate) fn next_ui_design_path( - root: &Path, - manifest: &GameCreationAppManifest, -) -> Result<(String, String), String> { - let mut index = manifest - .assets - .iter() - .filter(|asset| { - asset.kind == UI_DESIGN_DOC_ASSET_KIND && asset.media_type == UI_DESIGN_DOC_MEDIA_TYPE - }) - .count() - + 1; - loop { - let resource_name = format!("UI 设计 {index}"); - let relative_path = format!("ui/{resource_name}.json"); - let path = resolve_local_project_path(root, &relative_path)?; - if !path.exists() - && !manifest - .assets - .iter() - .any(|asset| asset.local_path == relative_path) - { - return Ok((resource_name, relative_path)); - } - index = index - .checked_add(1) - .ok_or_else(|| "UI 设计资源编号已达到上限".to_string())?; - } -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::ui_editor::persistence::{load_ui_design_state_at, LoadUiDesignStateInput}; - use crate::ui_editor::utils::UIDesignImageId; - use crate::{init_local_game_project_at, register_local_asset_entry}; - use shared_contracts::game_creation_app::GameCreationAppAssetCategory; - use std::io::Cursor; - - fn fixture() -> tempfile::TempDir { - let directory = tempfile::tempdir().expect("create UI bridge project"); - init_local_game_project_at(directory.path(), "ui-bridge-project", "UI bridge") - .expect("init project"); - let source_path = directory.path().join("assets/ui-prototype.png"); - fs::create_dir_all(source_path.parent().expect("source parent")) - .expect("create source parent"); - let mut bytes = Vec::new(); - image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel( - 320, - 180, - image::Rgba([255, 128, 64, 255]), - )) - .write_to(&mut Cursor::new(&mut bytes), image::ImageFormat::Png) - .expect("encode source image bytes"); - fs::write(&source_path, bytes).expect("write source image"); - register_local_asset_entry( - directory.path(), - "assets/ui-prototype.png", - GameCreationAppAssetKind::UiDesign, - "image/png", - "canvas", - GameCreationAppAssetSource { - kind: GameCreationAppAssetSourceKind::Canvas, - canvas_project_id: Some("canvas-project".to_string()), - resource_id: Some("prototype-resource".to_string()), - asset_object_id: None, - task_id: Some("design-foundation".to_string()), - prompt: None, - model: None, - generation_route: None, - generation_kind: Some("ui-design".to_string()), - reference_resource_ids: Vec::new(), - }, - ) - .expect("register source asset"); - directory - } - - #[test] - fn bridge_is_idempotent_and_installs_source_image() { - let directory = fixture(); - let root = directory.path(); - let manifest = read_existing_manifest_for_project(root).expect("manifest"); - let source_id = manifest - .assets - .iter() - .find(|asset| asset.kind == GameCreationAppAssetKind::UiDesign) - .expect("source asset") - .id - .clone(); - let input = EnsureUiDesignResourceForPrototypeInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: "ui-bridge-project".to_string(), - prototype_asset_id: source_id.clone(), - }; - let first = ensure_ui_design_resource_for_prototype(input.clone()).expect("bridge"); - assert!(first.created); - assert_eq!(first.asset.kind, UI_DESIGN_DOC_ASSET_KIND); - // 写侧 → 分类的端到端断言：这条路径走的是与 - // 写侧与 persistence/workflow 共用 UI 文档 kind/media 常量。 - assert_eq!( - first.asset.category, - GameCreationAppAssetCategory::UiInteraction - ); - assert_eq!( - first.asset.source.reference_resource_ids, - vec!["prototype-resource".to_string()] - ); - let snapshot = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: "ui-bridge-project".to_string(), - asset_id: first.asset.id.clone(), - }) - .expect("load bridged state"); - let source_image_id = UIDesignImageId::new(source_id.clone()).expect("source image id"); - let image = snapshot - .state - .ui_design_images - .get(&source_image_id) - .expect("source image"); - assert_eq!(image.path, "assets/ui-prototype.png"); - assert_eq!(image.pixel_size.x, 320.0); - assert_eq!(image.pixel_size.y, 180.0); - - let second = ensure_ui_design_resource_for_prototype(input).expect("idempotent bridge"); - assert!(!second.created); - assert_eq!(second.asset.id, first.asset.id); - assert_eq!( - second.committed_project_revision, - first.committed_project_revision - ); - assert_eq!( - second - .manifest - .assets - .iter() - .filter(|asset| { - asset.kind == UI_DESIGN_DOC_ASSET_KIND - && asset.media_type == UI_DESIGN_DOC_MEDIA_TYPE - }) - .count(), - 1 - ); - } -} diff --git a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/workflow.rs b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/workflow.rs index 12c5d58fb..e69de29bb 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/ui_editor/workflow.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/ui_editor/workflow.rs @@ -1,1767 +0,0 @@ -use crate::ui_editor::commands::binding::BindingChange; -use crate::ui_editor::commands::{ - bind_components_impl_with_provider, merge_ui_impl_with_provider, - recognize_ui_impl_with_provider, -}; -use crate::ui_editor::layout::node::{Node, StageStatus}; -use crate::ui_editor::persistence::{ - initialize_ui_design_state_at, load_ui_design_state_at, save_ui_design_state_at, - LoadUiDesignStateInput, SaveUiDesignStateInput, SaveUiDesignStateResult, - UI_DESIGN_DOC_ASSET_KIND, UI_DESIGN_DOC_MEDIA_TYPE, -}; -use crate::ui_editor::resource::font::FontAsset; -use crate::ui_editor::resource::sprite::{SpriteAsset, SpriteAssetMetadata, SpriteBorder}; -use crate::ui_editor::resource::ui_design_image::{ - UIDesignImage, UIDesignImageMetadata, UIDesignImageRole, -}; -use crate::ui_editor::utils::{SpriteAssetId, UIDesignImageId}; -use crate::*; -use image::GenericImageView as _; -use nalgebra::Vector2; -use serde::{Deserialize, Serialize}; -use sha2::Sha256; -use shared_contracts::game_creation_app::GameCreationAppAssetKind; -use std::collections::{HashMap, HashSet}; -use std::fs; -use std::path::Path; -use typed_floats::tf32::StrictlyPositiveFinite; - -const UI_WORKFLOW_RECEIPT_SCHEMA_VERSION: &str = "game-creator-ui-workflow-receipt.v1"; -const UI_WORKFLOW_MAX_PAGES: usize = 32; -const UI_WORKFLOW_MAX_IMAGE_BYTES: u64 = 16 * 1024 * 1024; -const UI_WORKFLOW_MAX_APPLICATION_BYTES: u64 = 4 * 1024 * 1024; -const UI_WORKFLOW_PAGE_REGISTRY_PATH: &str = "game/ui-pages.json"; -const UI_WORKFLOW_PAGE_MARKER: &str = "@genarrative-ui-page "; -const UI_WORKFLOW_PAGE_SCAN_FILES: &[&str] = &[ - "game/game_design.md", - "game/index.html", - "game/game.js", - "game/style.css", -]; -const UI_WORKFLOW_MAX_PAGE_REGISTRY_BYTES: u64 = 256 * 1024; -const UI_WORKFLOW_MAX_PAGE_SCAN_BYTES: u64 = 4 * 1024 * 1024; - -#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] -#[serde(rename_all = "kebab-case")] -pub(crate) enum UiWorkflowOperation { - Discover, - Prepare, - Recognize, - Status, - Finalize, -} - -#[derive(Clone, Debug, Deserialize)] -#[serde(deny_unknown_fields, rename_all = "camelCase")] -pub(crate) struct UiWorkflowPageInput { - pub(crate) page_id: String, - pub(crate) title: String, - pub(crate) description: String, - pub(crate) design_asset_id: String, - #[serde(default)] - pub(crate) sprite_asset_ids: Vec, - #[serde(default)] - pub(crate) font_asset_ids: Vec, - pub(crate) application_path: Option, -} - -#[derive(Clone, Debug, Deserialize)] -#[serde(deny_unknown_fields, rename_all = "camelCase")] -pub(crate) struct UiWorkflowRunInput { - pub(crate) operation: UiWorkflowOperation, - pub(crate) source_asset_id: String, - #[serde(default)] - pub(crate) pages: Vec, -} - -#[derive(Clone, Debug, Eq, PartialEq, Serialize)] -#[serde(rename_all = "camelCase")] -pub(crate) struct UiWorkflowDiscoveredPage { - pub(crate) page_id: String, - pub(crate) title: String, - pub(crate) description: String, - pub(crate) application_path: String, - pub(crate) required_design_asset_path: String, - pub(crate) discovered_from: String, -} - -#[derive(Clone, Debug, Deserialize)] -#[serde(deny_unknown_fields, rename_all = "camelCase")] -struct UiWorkflowPageDeclaration { - page_id: String, - title: String, - description: String, - application_path: String, -} - -#[derive(Clone, Debug, Eq, PartialEq, Serialize)] -#[serde(rename_all = "kebab-case")] -pub(crate) enum UiWorkflowPageStage { - ReferenceReady, - StructureReady, - BindingReady, - ApplicationReady, - Completed, -} - -#[derive(Clone, Debug, Eq, PartialEq, Serialize)] -#[serde(rename_all = "camelCase")] -pub(crate) struct UiWorkflowPageStatus { - pub(crate) page_id: String, - pub(crate) title: String, - pub(crate) design_asset_id: String, - pub(crate) ui_asset_id: String, - pub(crate) ui_state_revision: u64, - pub(crate) stage: UiWorkflowPageStage, - pub(crate) blockers: Vec, - pub(crate) application_marker: String, -} - -#[derive(Clone, Debug, Eq, PartialEq, Serialize)] -#[serde(rename_all = "camelCase")] -pub(crate) struct UiWorkflowRunResult { - pub(crate) operation: UiWorkflowOperation, - pub(crate) source_asset_id: String, - pub(crate) project_id: String, - pub(crate) completed: bool, - pub(crate) revision_advance_count: u64, - pub(crate) pages: Vec, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub(crate) discovered_pages: Vec, - pub(crate) final_stage_route: Option, -} - -#[derive(Clone, Debug, Eq, PartialEq, Serialize)] -#[serde(rename_all = "camelCase")] -pub(crate) struct UiWorkflowFinalStageRoute { - pub(crate) resource_id: String, - pub(crate) initial_step: String, - pub(crate) render_mode: String, -} - -#[derive(Clone, Debug, Eq, PartialEq, Serialize)] -#[serde(deny_unknown_fields, rename_all = "camelCase")] -struct UiWorkflowReceipt { - schema_version: String, - project_id: String, - source_asset_id: String, - pages: Vec, - final_stage_route: UiWorkflowFinalStageRoute, -} - -struct ResolvedWorkflowPage { - input: UiWorkflowPageInput, - design_asset: GameCreationAppAssetManifestEntry, - ui_asset: GameCreationAppAssetManifestEntry, -} - -#[cfg(test)] -pub(crate) async fn run_ui_workflow_at( - root: &Path, - input: UiWorkflowRunInput, -) -> Result { - run_ui_workflow_at_with_provider(root, input, None).await -} - -pub(crate) async fn run_ui_workflow_at_with_provider( - root: &Path, - input: UiWorkflowRunInput, - provider_identity: Option<(&str, &str)>, -) -> Result { - validate_project_root(root)?; - validate_workflow_input(&input)?; - if !matches!( - input.operation, - UiWorkflowOperation::Status | UiWorkflowOperation::Discover - ) { - enforce_project_permission_policy(root, "asset.register")?; - } - let revision_before = read_game_creator_agent_runtime_project_revision(root)?.revision; - let manifest = read_existing_manifest_for_project(root)?; - let source = manifest - .assets - .iter() - .find(|asset| asset.id == input.source_asset_id) - .cloned() - .ok_or_else(|| "ui.workflow.run sourceAssetId 未登记".to_string())?; - validate_source_asset(root, &source)?; - - if input.operation == UiWorkflowOperation::Discover { - return Ok(UiWorkflowRunResult { - operation: input.operation, - source_asset_id: source.id, - project_id: manifest.project_id, - completed: false, - revision_advance_count: 0, - pages: Vec::new(), - discovered_pages: discover_ui_pages(root)?, - final_stage_route: None, - }); - } - - let mut resolved = Vec::with_capacity(input.pages.len()); - for page in input.pages.clone() { - let current_manifest = read_existing_manifest_for_project(root)?; - let design_asset = current_manifest - .assets - .iter() - .find(|asset| asset.id == page.design_asset_id) - .cloned() - .ok_or_else(|| format!("页面 {} 的 designAssetId 未登记", page.page_id))?; - validate_design_asset(root, &design_asset)?; - let sprite_assets = resolve_page_assets( - root, - ¤t_manifest, - &page.page_id, - &page.sprite_asset_ids, - "spriteAssetIds", - validate_sprite_asset, - )?; - let font_assets = resolve_page_assets( - root, - ¤t_manifest, - &page.page_id, - &page.font_asset_ids, - "fontAssetIds", - validate_font_asset, - )?; - let ui_asset = match input.operation { - UiWorkflowOperation::Prepare | UiWorkflowOperation::Recognize => { - ensure_page_ui_resource( - root, - ¤t_manifest.project_id, - &source, - &page, - &design_asset, - &sprite_assets, - &font_assets, - )? - } - UiWorkflowOperation::Status | UiWorkflowOperation::Finalize => find_page_ui_resource( - ¤t_manifest, - &source, - &page, - &design_asset, - &sprite_assets, - &font_assets, - )? - .ok_or_else(|| format!("页面 {} 尚未准备 UI JSON 资源", page.page_id))?, - UiWorkflowOperation::Discover => unreachable!("discover 在页面解析前已返回"), - }; - resolved.push(ResolvedWorkflowPage { - input: page, - design_asset, - ui_asset, - }); - } - - if input.operation == UiWorkflowOperation::Recognize { - for page in &resolved { - // The workflow must use the same provider-backed recognition and - // binding commands as the editor. There is intentionally no - // deterministic fallback here: a missing provider or malformed - // response is returned to the caller and leaves the durable stage - // at reference-ready/structure-ready rather than claiming UI - // semantics were recognized. - recognize_page_semantics(root, &manifest.project_id, page, provider_identity).await?; - } - } - if input.operation == UiWorkflowOperation::Finalize { - for page in &resolved { - apply_application_marker( - root, - &manifest.project_id, - page.input.application_path.as_deref(), - &page.input.page_id, - &page.ui_asset.id, - )?; - update_page_manifest_stage(root, &page.ui_asset.id, "application-ready")?; - } - } - - let finalized = input.operation == UiWorkflowOperation::Finalize; - let statuses = resolved - .iter() - .map(|page| derive_page_status(root, &manifest.project_id, page, finalized)) - .collect::, _>>()?; - let completed = statuses - .iter() - .all(|status| status.stage == UiWorkflowPageStage::Completed); - if input.operation == UiWorkflowOperation::Prepare { - for page in &resolved { - update_page_manifest_stage(root, &page.ui_asset.id, "reference-ready")?; - } - } - let final_stage_route = if completed - && matches!( - input.operation, - UiWorkflowOperation::Finalize | UiWorkflowOperation::Status - ) { - let route = UiWorkflowFinalStageRoute { - resource_id: statuses[0].ui_asset_id.clone(), - initial_step: "asset-separation".to_string(), - render_mode: "final-preview".to_string(), - }; - if finalized { - for page in &resolved { - update_page_manifest_stage(root, &page.ui_asset.id, "completed")?; - } - write_final_receipt(root, &manifest.project_id, &source.id, &statuses, &route)?; - } - Some(route) - } else { - if finalized { - return Err(format!( - "ui.workflow.run 拒绝伪造完成：{}", - statuses - .iter() - .flat_map(|status| status - .blockers - .iter() - .map(move |blocker| { format!("{}: {blocker}", status.page_id) })) - .collect::>() - .join("；") - )); - } - None - }; - let revision_after = read_game_creator_agent_runtime_project_revision(root)?.revision; - Ok(UiWorkflowRunResult { - operation: input.operation, - source_asset_id: source.id, - project_id: manifest.project_id, - completed, - revision_advance_count: revision_after.saturating_sub(revision_before), - pages: statuses, - discovered_pages: Vec::new(), - final_stage_route, - }) -} - -fn validate_workflow_input(input: &UiWorkflowRunInput) -> Result<(), String> { - if input.source_asset_id.trim().is_empty() - || input.source_asset_id.len() > 160 - || input.source_asset_id.chars().any(char::is_control) - { - return Err("ui.workflow.run sourceAssetId 无效".to_string()); - } - if input.pages.len() > UI_WORKFLOW_MAX_PAGES - || (input.operation != UiWorkflowOperation::Discover && input.pages.is_empty()) - { - return Err(format!( - "ui.workflow.run pages 必须包含 1 至 {UI_WORKFLOW_MAX_PAGES} 页" - )); - } - let mut page_ids = HashSet::new(); - let mut design_ids = HashSet::new(); - for page in &input.pages { - let valid_page_id = !page.page_id.is_empty() - && page.page_id.len() <= 80 - && page - .page_id - .bytes() - .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.')); - if !valid_page_id || !page_ids.insert(page.page_id.clone()) { - return Err("ui.workflow.run pageId 无效或重复".to_string()); - } - if page.title.trim().is_empty() - || page.title.chars().count() > 120 - || page.description.chars().count() > 400 - || page.title.chars().any(char::is_control) - || page.description.chars().any(char::is_control) - { - return Err(format!("页面 {} 的标题或描述无效", page.page_id)); - } - if page.design_asset_id.trim().is_empty() - || page.design_asset_id.len() > 160 - || !design_ids.insert(page.design_asset_id.clone()) - { - return Err("ui.workflow.run 每页必须关联唯一 designAssetId".to_string()); - } - if page - .application_path - .as_deref() - .is_some_and(|path| path.len() > 240 || path.chars().any(char::is_control)) - { - return Err(format!("页面 {} 的 applicationPath 无效", page.page_id)); - } - if page.sprite_asset_ids.len() > 32 || page.font_asset_ids.len() > 16 { - return Err(format!( - "页面 {} 的 UI 图片/图标或字体资源数量超限", - page.page_id - )); - } - } - Ok(()) -} - -fn discover_ui_pages(root: &Path) -> Result, String> { - let mut declarations = Vec::<(UiWorkflowPageDeclaration, String)>::new(); - let registry_path = resolve_local_project_path(root, UI_WORKFLOW_PAGE_REGISTRY_PATH)?; - if registry_path.exists() { - let metadata = fs::symlink_metadata(®istry_path) - .map_err(|error| format!("读取 UI 页面注册表失败：{error}"))?; - if metadata.file_type().is_symlink() || !metadata.is_file() { - return Err(format!( - "UI 页面注册表必须是普通文件：{UI_WORKFLOW_PAGE_REGISTRY_PATH}" - )); - } - if metadata.len() > UI_WORKFLOW_MAX_PAGE_REGISTRY_BYTES { - return Err(format!( - "UI 页面注册表超过 {} KiB", - UI_WORKFLOW_MAX_PAGE_REGISTRY_BYTES / 1024 - )); - } - let bytes = - fs::read(®istry_path).map_err(|error| format!("读取 UI 页面注册表失败：{error}"))?; - let entries = serde_json::from_slice::>(&bytes) - .map_err(|error| format!("解析 UI 页面注册表失败：{error}"))?; - declarations.extend( - entries - .into_iter() - .map(|entry| (entry, UI_WORKFLOW_PAGE_REGISTRY_PATH.to_string())), - ); - } - - for relative in UI_WORKFLOW_PAGE_SCAN_FILES { - let path = resolve_local_project_path(root, relative)?; - if !path.exists() { - continue; - } - let metadata = fs::symlink_metadata(&path) - .map_err(|error| format!("读取 UI 页面声明文件失败：{relative}: {error}"))?; - if metadata.file_type().is_symlink() { - return Err(format!("UI 页面声明文件不得是符号链接：{relative}")); - } - if !metadata.is_file() { - continue; - } - if metadata.len() > UI_WORKFLOW_MAX_PAGE_SCAN_BYTES { - return Err(format!("UI 页面声明文件超过 4 MiB：{relative}")); - } - let content = fs::read_to_string(&path) - .map_err(|_| format!("UI 页面声明文件必须是 UTF-8 文本：{relative}"))?; - for (line_number, line) in content.lines().enumerate() { - let Some(marker_offset) = line.find(UI_WORKFLOW_PAGE_MARKER) else { - continue; - }; - let json = line[marker_offset + UI_WORKFLOW_PAGE_MARKER.len()..] - .trim() - .strip_suffix("-->") - .or_else(|| { - line[marker_offset + UI_WORKFLOW_PAGE_MARKER.len()..] - .trim() - .strip_suffix("*/") - }) - .map(str::trim) - .unwrap_or_else(|| line[marker_offset + UI_WORKFLOW_PAGE_MARKER.len()..].trim()); - if json.is_empty() { - return Err(format!( - "UI 页面声明缺少 JSON：{relative}:{}", - line_number + 1 - )); - } - let declaration = - serde_json::from_str::(json).map_err(|error| { - format!( - "解析 UI 页面声明失败：{relative}:{}: {error}", - line_number + 1 - ) - })?; - declarations.push((declaration, format!("{relative}:{}", line_number + 1))); - } - } - - if declarations.is_empty() { - return Err(format!( - "未发现 UI 页面声明：请创建 {UI_WORKFLOW_PAGE_REGISTRY_PATH}，或在 game/game_design.md、game/index.html、game/game.js、game/style.css 中添加 {UI_WORKFLOW_PAGE_MARKER}" - )); - } - if declarations.len() > UI_WORKFLOW_MAX_PAGES { - return Err(format!("UI 页面声明超过 {UI_WORKFLOW_MAX_PAGES} 页")); - } - - let mut page_ids = HashSet::new(); - let mut pages = declarations - .into_iter() - .map(|(declaration, discovered_from)| { - validate_discovered_page(&declaration)?; - if !page_ids.insert(declaration.page_id.clone()) { - return Err(format!("UI 页面声明 pageId 重复：{}", declaration.page_id)); - } - Ok(UiWorkflowDiscoveredPage { - required_design_asset_path: format!("assets/ui-pages/{}.png", declaration.page_id), - page_id: declaration.page_id, - title: declaration.title, - description: declaration.description, - application_path: declaration.application_path, - discovered_from, - }) - }) - .collect::, String>>()?; - pages.sort_by(|left, right| left.page_id.cmp(&right.page_id)); - Ok(pages) -} - -fn validate_discovered_page(page: &UiWorkflowPageDeclaration) -> Result<(), String> { - let valid_page_id = !page.page_id.is_empty() - && page.page_id.len() <= 80 - && page - .page_id - .bytes() - .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.')); - if !valid_page_id { - return Err(format!("UI 页面声明 pageId 无效：{}", page.page_id)); - } - if page.title.trim().is_empty() - || page.title.chars().count() > 120 - || page.description.chars().count() > 400 - || page.title.chars().any(char::is_control) - || page.description.chars().any(char::is_control) - { - return Err(format!("UI 页面 {} 的标题或描述无效", page.page_id)); - } - let normalized_path = normalize_relative_path(&page.application_path) - .map_err(|error| format!("UI 页面 {} 的 applicationPath 无效：{error}", page.page_id))?; - if !normalized_path.starts_with("game/") { - return Err(format!( - "UI 页面 {} 的 applicationPath 必须位于 game/", - page.page_id - )); - } - Ok(()) -} - -fn validate_source_asset( - root: &Path, - asset: &GameCreationAppAssetManifestEntry, -) -> Result<(), String> { - if asset.kind != GameCreationAppAssetKind::UiDesign || !asset.media_type.starts_with("image/") { - return Err("ui.workflow.run sourceAssetId 必须是已登记的 ui-design 图片".to_string()); - } - validate_image_asset_file(root, asset, "UI 原型图") -} - -fn validate_image_asset_file( - root: &Path, - asset: &GameCreationAppAssetManifestEntry, - label: &str, -) -> Result<(), String> { - let path = resolve_local_project_path(root, &asset.local_path)?; - let metadata = fs::symlink_metadata(&path) - .map_err(|error| format!("读取{label}失败：{}: {error}", asset.local_path))?; - if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() == 0 { - return Err(format!("{label}不是非空普通文件：{}", asset.local_path)); - } - if metadata.len() > UI_WORKFLOW_MAX_IMAGE_BYTES { - return Err(format!( - "{label}超过 {} MiB", - UI_WORKFLOW_MAX_IMAGE_BYTES / 1024 / 1024 - )); - } - image::open(&path).map_err(|_| format!("{label}无法解码：{}", asset.local_path))?; - Ok(()) -} - -fn validate_design_asset( - root: &Path, - asset: &GameCreationAppAssetManifestEntry, -) -> Result<(), String> { - if !asset.media_type.starts_with("image/") { - return Err(format!("页面设计资源 {} 不是图片", asset.id)); - } - validate_image_asset_file(root, asset, "页面设计图") -} - -fn resolve_page_assets( - root: &Path, - manifest: &GameCreationAppManifest, - page_id: &str, - asset_ids: &[String], - field: &str, - validate: fn(&Path, &GameCreationAppAssetManifestEntry) -> Result<(), String>, -) -> Result, String> { - let mut seen = HashSet::new(); - let mut resolved = Vec::with_capacity(asset_ids.len()); - for asset_id in asset_ids { - if asset_id.trim().is_empty() - || asset_id.len() > 160 - || asset_id.chars().any(char::is_control) - || !seen.insert(asset_id.as_str()) - { - return Err(format!("页面 {page_id} 的 {field} 包含无效或重复资源 ID")); - } - let asset = manifest - .assets - .iter() - .find(|asset| asset.id == *asset_id) - .cloned() - .ok_or_else(|| format!("页面 {page_id} 的 {field} 资源 {asset_id} 未登记"))?; - validate(root, &asset)?; - resolved.push(asset); - } - Ok(resolved) -} - -fn validate_sprite_asset( - root: &Path, - asset: &GameCreationAppAssetManifestEntry, -) -> Result<(), String> { - if !asset.media_type.starts_with("image/") { - return Err(format!("UI 独立图片/图标资源 {} 不是图片", asset.id)); - } - validate_image_asset_file(root, asset, "UI 独立图片/图标") -} - -fn validate_font_asset( - root: &Path, - asset: &GameCreationAppAssetManifestEntry, -) -> Result<(), String> { - if !asset.media_type.starts_with("font/") { - return Err(format!("UI 字体资源 {} 不是字体", asset.id)); - } - let path = resolve_local_project_path(root, &asset.local_path)?; - let metadata = fs::symlink_metadata(&path) - .map_err(|error| format!("读取 UI 字体失败：{}: {error}", asset.local_path))?; - if metadata.file_type().is_symlink() - || !metadata.is_file() - || metadata.len() == 0 - || metadata.len() > UI_WORKFLOW_MAX_IMAGE_BYTES - { - return Err(format!( - "UI 字体不是受控大小的非空普通文件：{}", - asset.local_path - )); - } - let bytes = fs::read(&path) - .map_err(|error| format!("读取 UI 字体失败：{}: {error}", asset.local_path))?; - FontAsset::from_verified_bytes( - asset.id.clone(), - asset.local_path.clone(), - Path::new(&asset.local_path) - .file_name() - .and_then(|name| name.to_str()) - .unwrap_or("font"), - &bytes, - ) - .map(|_| ()) -} - -fn canonical_resource_id(asset: &GameCreationAppAssetManifestEntry) -> String { - asset - .source - .resource_id - .clone() - .or_else(|| asset.source.asset_object_id.clone()) - .unwrap_or_else(|| asset.id.clone()) -} - -fn workflow_resource_id(source: &GameCreationAppAssetManifestEntry, page_id: &str) -> String { - let digest = Sha256::digest(format!("{}\0{page_id}", source.id).as_bytes()); - format!("ui-workflow-{}", &format!("{digest:x}")[..24]) -} - -fn workflow_relative_path(source: &GameCreationAppAssetManifestEntry, page_id: &str) -> String { - format!("ui/{}.json", workflow_resource_id(source, page_id)) -} - -fn find_page_ui_resource( - manifest: &GameCreationAppManifest, - source: &GameCreationAppAssetManifestEntry, - page: &UiWorkflowPageInput, - design_asset: &GameCreationAppAssetManifestEntry, - sprite_assets: &[GameCreationAppAssetManifestEntry], - font_assets: &[GameCreationAppAssetManifestEntry], -) -> Result, String> { - let resource_id = workflow_resource_id(source, &page.page_id); - let matches = manifest - .assets - .iter() - .filter(|asset| asset.source.resource_id.as_deref() == Some(resource_id.as_str())) - .cloned() - .collect::>(); - if matches.len() > 1 { - return Err(format!("页面 {} 存在重复 UI workflow 资源", page.page_id)); - } - let Some(asset) = matches.into_iter().next() else { - return Ok(None); - }; - if asset.kind != UI_DESIGN_DOC_ASSET_KIND - || asset.media_type != UI_DESIGN_DOC_MEDIA_TYPE - || asset.local_path != workflow_relative_path(source, &page.page_id) - { - return Err(format!("页面 {} 的 UI workflow 资源身份冲突", page.page_id)); - } - let mut expected_references = vec![ - canonical_resource_id(source), - canonical_resource_id(design_asset), - ]; - expected_references.extend(sprite_assets.iter().map(canonical_resource_id)); - expected_references.extend(font_assets.iter().map(canonical_resource_id)); - if !expected_references.iter().all(|expected| { - asset - .source - .reference_resource_ids - .iter() - .any(|reference| reference == expected) - }) { - return Err(format!( - "页面 {} 的 UI workflow manifest 关联不完整", - page.page_id - )); - } - Ok(Some(asset)) -} - -fn ensure_page_ui_resource( - root: &Path, - project_id: &str, - source: &GameCreationAppAssetManifestEntry, - page: &UiWorkflowPageInput, - design_asset: &GameCreationAppAssetManifestEntry, - sprite_assets: &[GameCreationAppAssetManifestEntry], - font_assets: &[GameCreationAppAssetManifestEntry], -) -> Result { - let manifest = read_existing_manifest_for_project(root)?; - let ui_asset = if let Some(existing) = find_page_ui_resource( - &manifest, - source, - page, - design_asset, - sprite_assets, - font_assets, - )? { - existing - } else { - let relative_path = workflow_relative_path(source, &page.page_id); - let absolute_path = resolve_local_project_path(root, &relative_path)?; - if absolute_path.exists() { - return Err(format!( - "UI workflow 资源路径已存在但未登记：{relative_path}" - )); - } - fs::create_dir_all( - absolute_path - .parent() - .ok_or_else(|| "UI workflow 路径缺少父目录".to_string())?, - ) - .map_err(|error| format!("创建 UI workflow 目录失败：{error}"))?; - fs::write(&absolute_path, b"") - .map_err(|error| format!("创建 UI workflow 资源失败：{error}"))?; - let registered = register_local_asset_at( - root, - &relative_path, - GameCreationAppAssetKind::UiDesignDoc, - UI_DESIGN_DOC_MEDIA_TYPE, - "ui-workflow", - GameCreationAppAssetSource { - kind: GameCreationAppAssetSourceKind::Generated, - canvas_project_id: source.source.canvas_project_id.clone(), - resource_id: Some(workflow_resource_id(source, &page.page_id)), - asset_object_id: None, - task_id: source.source.task_id.clone(), - prompt: None, - model: None, - generation_route: None, - generation_kind: Some("ui-workflow".to_string()), - reference_resource_ids: { - let mut references = vec![ - canonical_resource_id(source), - canonical_resource_id(design_asset), - ]; - references.extend(sprite_assets.iter().map(canonical_resource_id)); - references.extend(font_assets.iter().map(canonical_resource_id)); - references - }, - }, - ) - .map_err(|error| { - let _ = fs::remove_file(&absolute_path); - error - })?; - let current = read_existing_manifest_for_project(root)?; - current - .assets - .into_iter() - .find(|asset| asset.id == registered.id) - .ok_or_else(|| "UI workflow 资源登记后无法回读".to_string())? - }; - - let initialized = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: ui_asset.id.clone(), - }); - if initialized.is_err() { - initialize_ui_design_state_at(root, project_id, &ui_asset.id)?; - } - let snapshot = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: ui_asset.id.clone(), - })?; - let image_id = UIDesignImageId::new(page.page_id.clone()) - .map_err(|error| format!("页面 image ID 无效：{error}"))?; - let expected_image = workflow_design_image(root, page, design_asset)?; - let mut state = snapshot.state; - match state.ui_design_images.get(&image_id) { - Some(current) if current != &expected_image => { - return Err(format!( - "页面 {} 已有不同 UI 设计图，拒绝静默替换", - page.page_id - )); - } - Some(_) => {} - None if state.ui_design_images.is_empty() => { - state - .ui_design_images - .insert(image_id, expected_image.clone()); - } - None => return Err(format!("页面 {} UI State 已含其他设计图", page.page_id)), - } - let sprite_id = SpriteAssetId::new(format!("page-reference-{}", page.page_id)) - .map_err(|error| format!("页面 sprite ID 无效：{error}"))?; - if !state.sprite_assets.contains_key(&sprite_id) { - let mut sprite = SpriteAsset::new( - sprite_id.clone(), - expected_image.pixel_size, - StrictlyPositiveFinite::new(1.0).map_err(|_| "页面 sprite 像素比例无效".to_string())?, - SpriteBorder::NONE, - ) - .map_err(|error| format!("页面 sprite 初始化失败：{error}"))?; - sprite.metadata = SpriteAssetMetadata { - name: format!("{} 页面视觉素材", page.title.trim()), - asset_type: "ui-page-reference".to_string(), - }; - sprite.path = expected_image.path.clone(); - state.sprite_assets.insert(sprite_id, sprite); - } - install_page_component_assets(root, &mut state, sprite_assets, font_assets)?; - match save_ui_design_state_at(SaveUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: ui_asset.id.clone(), - expected_revision: snapshot.revision, - state, - })? { - SaveUiDesignStateResult::Saved { .. } | SaveUiDesignStateResult::Unchanged { .. } => {} - SaveUiDesignStateResult::Conflict { .. } => { - return Err(format!( - "页面 {} UI State revision 冲突，请重试", - page.page_id - )); - } - } - Ok(ui_asset) -} - -/// 比较 sprite 资源身份时忽略 `metadata.asset_type`。 -/// -/// `asset_type` 是随 canonical kind 派生的展示串，不构成资源身份；身份判定只看真正影响 -/// 渲染的字段，避免展示字段变化造成资源冲突。 -fn same_sprite_asset_identity(current: &SpriteAsset, next: &SpriteAsset) -> bool { - if current.metadata.asset_type == next.metadata.asset_type { - return current == next; - } - let mut current = current.clone(); - let mut next = next.clone(); - current.metadata.asset_type = String::new(); - next.metadata.asset_type = String::new(); - current == next -} - -fn install_page_component_assets( - root: &Path, - state: &mut crate::ui_editor::state::State, - sprite_assets: &[GameCreationAppAssetManifestEntry], - font_assets: &[GameCreationAppAssetManifestEntry], -) -> Result<(), String> { - for asset in sprite_assets { - let absolute = resolve_local_project_path(root, &asset.local_path)?; - let decoded = image::open(&absolute) - .map_err(|_| format!("UI 独立图片/图标无法解码：{}", asset.local_path))?; - let (width, height) = decoded.dimensions(); - let asset_id = SpriteAssetId::new(asset.id.clone()) - .map_err(|error| format!("UI 独立图片/图标 ID 无效：{error}"))?; - let mut sprite = SpriteAsset::new( - asset_id.clone(), - Vector2::new(width as f32, height as f32), - StrictlyPositiveFinite::new(1.0) - .map_err(|_| "UI 独立图片/图标像素比例无效".to_string())?, - SpriteBorder::NONE, - ) - .map_err(|error| format!("UI 独立图片/图标初始化失败：{error}"))?; - sprite.metadata = SpriteAssetMetadata { - name: Path::new(&asset.local_path) - .file_stem() - .and_then(|name| name.to_str()) - .unwrap_or("UI 素材") - .to_string(), - asset_type: asset.kind.to_string(), - }; - sprite.path = asset.local_path.clone(); - match state.sprite_assets.get(&asset_id) { - Some(current) if !same_sprite_asset_identity(current, &sprite) => { - return Err(format!( - "UI 独立图片/图标 {} 与已有 State 资源冲突", - asset.id - )); - } - Some(_) => {} - None => { - state.sprite_assets.insert(asset_id, sprite); - } - } - } - for asset in font_assets { - let absolute = resolve_local_project_path(root, &asset.local_path)?; - let bytes = fs::read(&absolute) - .map_err(|error| format!("读取 UI 字体失败：{}: {error}", asset.local_path))?; - let font = FontAsset::from_verified_bytes( - asset.id.clone(), - asset.local_path.clone(), - Path::new(&asset.local_path) - .file_name() - .and_then(|name| name.to_str()) - .unwrap_or("font"), - &bytes, - )?; - let asset_id = font.asset_id.clone(); - match state.font_assets.get(&asset_id) { - Some(current) if current != &font => { - return Err(format!("UI 字体 {} 与已有 State 资源冲突", asset.id)); - } - Some(_) => {} - None => { - state.font_assets.insert(asset_id, font); - } - } - } - Ok(()) -} - -/// Runs the provider-backed editor pipeline for one workflow page. -/// -/// `recognize_ui_impl` owns multimodal semantic recognition and strict tool -/// response validation. `bind_components_impl` owns visual component binding -/// and its allowlisted sprite validation. This wrapper only persists their -/// DTOs under the UI State revision gate; it never manufactures a tree when a -/// provider is unavailable or returns an invalid result. -async fn recognize_page_semantics( - root: &Path, - project_id: &str, - page: &ResolvedWorkflowPage, - provider_identity: Option<(&str, &str)>, -) -> Result<(), String> { - let image_id = UIDesignImageId::new(page.input.page_id.clone()) - .map_err(|error| format!("页面 image ID 无效：{error}"))?; - let snapshot = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: page.ui_asset.id.clone(), - })?; - - let mut stage = page - .ui_asset - .source - .generation_kind - .as_deref() - .unwrap_or("ui-workflow") - .to_string(); - let has_page_tree = snapshot - .state - .ui_trees - .iter() - .filter(|tree| tree.src_ui_design == image_id) - .count() - == 1; - - // Every provider-backed phase is persisted independently. A retry resumes - // from the latest truthful manifest stage instead of repeating completed - // calls or manufacturing fallback output. - if !matches!( - stage.as_str(), - "ui-workflow.structure-ready" | "ui-workflow.merge-ready" | "ui-workflow.binding-ready" - ) { - let project_path = root.to_string_lossy().into_owned(); - let recognition = recognize_ui_impl_with_provider( - project_path, - snapshot.state.clone(), - provider_identity, - ) - .await - .map_err(|error| format!("页面 {} UI 语义识别失败：{error}", page.input.page_id))?; - if recognition.ui_trees.len() != 1 || recognition.ui_trees[0].src_ui_design != image_id { - return Err(format!( - "页面 {} UI 语义识别返回的树与页面设计图不匹配", - page.input.page_id - )); - } - let mut state = snapshot.state; - state.ui_trees = recognition.ui_trees; - match save_ui_design_state_at(SaveUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: page.ui_asset.id.clone(), - expected_revision: snapshot.revision, - state, - })? { - SaveUiDesignStateResult::Saved { .. } | SaveUiDesignStateResult::Unchanged { .. } => {} - SaveUiDesignStateResult::Conflict { .. } => { - return Err(format!( - "页面 {} UI 语义识别保存 revision 冲突，请重试", - page.input.page_id - )); - } - } - update_page_manifest_stage(root, &page.ui_asset.id, "structure-ready")?; - stage = "ui-workflow.structure-ready".to_string(); - } else if !has_page_tree { - return Err(format!( - "页面 {} manifest 已记录语义识别阶段，但 UI State 缺少唯一结构树", - page.input.page_id - )); - } - - if stage == "ui-workflow.binding-ready" { - return Ok(()); - } - - if stage == "ui-workflow.structure-ready" { - let merge_snapshot = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: page.ui_asset.id.clone(), - })?; - let merged = merge_ui_impl_with_provider( - root.to_string_lossy().into_owned(), - merge_snapshot.state.clone(), - provider_identity, - ) - .await - .map_err(|error| format!("页面 {} UI 多树合并失败：{error}", page.input.page_id))?; - if merged.ui_tree.src_ui_design != image_id { - return Err(format!( - "页面 {} UI 多树合并结果未绑定主页面设计图", - page.input.page_id - )); - } - let mut state = merge_snapshot.state; - state.ui_trees = vec![merged.ui_tree]; - match save_ui_design_state_at(SaveUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: page.ui_asset.id.clone(), - expected_revision: merge_snapshot.revision, - state, - })? { - SaveUiDesignStateResult::Saved { .. } | SaveUiDesignStateResult::Unchanged { .. } => {} - SaveUiDesignStateResult::Conflict { .. } => { - return Err(format!( - "页面 {} UI 多树合并保存 revision 冲突，请重试", - page.input.page_id - )); - } - } - update_page_manifest_stage(root, &page.ui_asset.id, "merge-ready")?; - stage = "ui-workflow.merge-ready".to_string(); - } - - if stage != "ui-workflow.merge-ready" { - return Err(format!( - "页面 {} UI workflow 阶段无法进入组件绑定：{stage}", - page.input.page_id - )); - } - - let mut binding_snapshot = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: page.ui_asset.id.clone(), - })?; - let mut sprite_ids = binding_snapshot - .state - .sprite_assets - .keys() - .map(|id| id.as_str().to_string()) - .collect::>(); - sprite_ids.sort(); - if sprite_ids.is_empty() { - return Err(format!( - "页面 {} UI 语义识别已完成，但没有可用于组件绑定的页面素材", - page.input.page_id - )); - } - let mut changed_nodes = 0usize; - for batch in sprite_ids.chunks(crate::ui_editor::commands::binding::ASSET_BATCH_SIZE) { - let binding = bind_components_impl_with_provider( - root.to_string_lossy().into_owned(), - binding_snapshot.state.clone(), - batch.to_vec(), - provider_identity, - ) - .await - .map_err(|error| format!("页面 {} UI 组件语义绑定失败：{error}", page.input.page_id))?; - if binding.changes.is_empty() { - continue; - } - let mut state = binding_snapshot.state.clone(); - let changes = binding - .changes - .into_iter() - .map(|change| (change.node_id.clone(), change)) - .collect::>(); - changed_nodes += apply_binding_changes(&mut state.ui_trees, &changes); - binding_snapshot = match save_ui_design_state_at(SaveUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: page.ui_asset.id.clone(), - expected_revision: binding_snapshot.revision, - state, - })? { - SaveUiDesignStateResult::Saved { - state, revision, .. - } - | SaveUiDesignStateResult::Unchanged { - state, revision, .. - } => crate::ui_editor::persistence::UiDesignStateSnapshot { state, revision }, - SaveUiDesignStateResult::Conflict { .. } => { - return Err(format!( - "页面 {} UI 组件绑定保存 revision 冲突，请重试", - page.input.page_id - )); - } - }; - } - if changed_nodes == 0 || !state_has_renderable_component(&binding_snapshot.state) { - return Err(format!( - "页面 {} UI 组件语义绑定未形成可渲染组件，拒绝进入 binding-ready", - page.input.page_id - )); - } - let mut binding_blockers = Vec::new(); - let mut component_count = 0usize; - for tree in &binding_snapshot.state.ui_trees { - collect_binding_blockers(&tree.root, &mut component_count, &mut binding_blockers); - } - if !binding_blockers.is_empty() { - // Keep the provider result available for review, but do not claim the - // binding stage. A subsequent recognize operation can retry binding - // from the durable structure-ready state. - return Ok(()); - } - update_page_manifest_stage(root, &page.ui_asset.id, "binding-ready") -} - -fn apply_binding_changes( - trees: &mut [crate::ui_editor::state::UITree], - changes: &HashMap, -) -> usize { - fn apply_node( - node: &mut Node, - changes: &HashMap, - ) -> usize { - let mut changed = 0; - if let Some(change) = changes.get(&node.id) { - node.component = change.component.clone().into_option(); - node.metadata.component_status = change.component_status.clone(); - changed += 1; - } - for child in &mut node.children { - changed += apply_node(child, changes); - } - changed - } - - trees - .iter_mut() - .map(|tree| apply_node(&mut tree.root, changes)) - .sum() -} - -fn state_has_renderable_component(state: &crate::ui_editor::state::State) -> bool { - fn has_component(node: &Node) -> bool { - node.component.is_some() || node.children.iter().any(has_component) - } - state.ui_trees.iter().any(|tree| has_component(&tree.root)) -} - -/// Publishes the durable workflow stage alongside the UI JSON State. The -/// manifest is the workbench projection authority, so every stage transition -/// is revisioned and can invalidate the client projection immediately. -fn update_page_manifest_stage(root: &Path, asset_id: &str, stage: &str) -> Result<(), String> { - let _lock = acquire_project_write_lock(root, "ui.workflow.manifest_stage")?; - let changed = mutate_manifest_at(root, |manifest| { - let asset = manifest - .assets - .iter_mut() - .find(|asset| asset.id == asset_id) - .ok_or_else(|| format!("UI workflow 资源 {} 未登记", asset_id))?; - if asset.kind != UI_DESIGN_DOC_ASSET_KIND || asset.media_type != UI_DESIGN_DOC_MEDIA_TYPE { - return Err(format!("UI workflow 资源 {} 类型不匹配", asset_id)); - } - let next_kind = format!("ui-workflow.{stage}"); - let current_rank = asset - .source - .generation_kind - .as_deref() - .and_then(workflow_stage_rank) - .unwrap_or(0); - let next_rank = workflow_stage_rank(&next_kind).unwrap_or(0); - if current_rank >= next_rank { - return Ok(false); - } - asset.source.generation_route = Some("ui.workflow.run".to_string()); - asset.source.generation_kind = Some(next_kind); - Ok(true) - })?; - if changed { - advance_agent_runtime_project_revision_locked(root).map(|_| ()) - } else { - Ok(()) - } -} - -fn workflow_stage_rank(kind: &str) -> Option { - match kind { - "ui-workflow.reference-ready" => Some(1), - "ui-workflow.structure-ready" => Some(2), - "ui-workflow.merge-ready" => Some(3), - "ui-workflow.binding-ready" => Some(4), - "ui-workflow.application-ready" => Some(5), - "ui-workflow.completed" => Some(6), - _ => None, - } -} - -fn workflow_design_image( - root: &Path, - page: &UiWorkflowPageInput, - design_asset: &GameCreationAppAssetManifestEntry, -) -> Result { - let absolute = resolve_local_project_path(root, &design_asset.local_path)?; - let bytes = fs::read(&absolute) - .map_err(|error| format!("读取页面设计图失败：{}: {error}", design_asset.local_path))?; - let decoded = image::load_from_memory(&bytes) - .map_err(|_| format!("页面设计图无法解码：{}", design_asset.local_path))?; - let (width, height) = decoded.dimensions(); - if width == 0 || height == 0 { - return Err("页面设计图尺寸无效".to_string()); - } - Ok(UIDesignImage { - metadata: UIDesignImageMetadata { - name: page.title.trim().to_string(), - description: page.description.trim().to_string(), - role: Some(UIDesignImageRole::Page), - slave_to: None, - }, - path: design_asset.local_path.clone(), - pixel_size: Vector2::new(width as f32, height as f32), - pixels_per_unit: StrictlyPositiveFinite::new(1.0) - .expect("1.0 is a positive finite pixels-per-unit"), - }) -} - -fn derive_page_status( - root: &Path, - project_id: &str, - page: &ResolvedWorkflowPage, - check_application: bool, -) -> Result { - let snapshot = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: page.ui_asset.id.clone(), - })?; - let image_id = UIDesignImageId::new(page.input.page_id.clone()) - .map_err(|error| format!("页面 image ID 无效：{error}"))?; - let mut stage = UiWorkflowPageStage::ReferenceReady; - let mut blockers = Vec::new(); - let matching_trees = snapshot - .state - .ui_trees - .iter() - .filter(|tree| tree.src_ui_design == image_id) - .collect::>(); - if matching_trees.len() != 1 { - blockers.push("尚未形成唯一的页面 UI 结构树".to_string()); - } else { - stage = UiWorkflowPageStage::StructureReady; - let mut component_count = 0usize; - collect_binding_blockers(&matching_trees[0].root, &mut component_count, &mut blockers); - if component_count == 0 { - blockers.push("UI 结构树尚未绑定任何可渲染组件".to_string()); - } - if blockers.is_empty() { - stage = UiWorkflowPageStage::BindingReady; - } - } - let marker = application_marker(&page.input.page_id, &page.ui_asset.id, snapshot.revision); - let manifest_completed = - page.ui_asset.source.generation_kind.as_deref() == Some("ui-workflow.completed"); - if stage == UiWorkflowPageStage::BindingReady { - let marker_installed = page - .input - .application_path - .as_deref() - .map(|_| { - validate_application_marker(root, page.input.application_path.as_deref(), &marker) - .is_ok() - }) - .unwrap_or(false); - if marker_installed { - stage = if check_application || manifest_completed { - UiWorkflowPageStage::Completed - } else { - UiWorkflowPageStage::ApplicationReady - }; - } else if check_application { - validate_application_marker(root, page.input.application_path.as_deref(), &marker) - .map_err(|error| format!("页面 {} 应用门禁失败：{error}", page.input.page_id))?; - } - } - Ok(UiWorkflowPageStatus { - page_id: page.input.page_id.clone(), - title: page.input.title.trim().to_string(), - design_asset_id: page.design_asset.id.clone(), - ui_asset_id: page.ui_asset.id.clone(), - ui_state_revision: snapshot.revision, - stage, - blockers, - application_marker: marker, - }) -} - -fn collect_binding_blockers(node: &Node, component_count: &mut usize, blockers: &mut Vec) { - *component_count += node.component.is_some() as usize; - if let StageStatus::NeedReview(reason) | StageStatus::Blocked(reason) = - &node.metadata.layout_status - { - blockers.push(format!("{} 布局未通过：{reason}", node.metadata.name)); - } - if let StageStatus::NeedReview(reason) | StageStatus::Blocked(reason) = - &node.metadata.component_status - { - blockers.push(format!("{} 组件未通过：{reason}", node.metadata.name)); - } - for child in &node.children { - collect_binding_blockers(child, component_count, blockers); - } -} - -fn application_marker(page_id: &str, ui_asset_id: &str, revision: u64) -> String { - format!("GENARRATIVE_UI_PAGE:{page_id}:{ui_asset_id}:{revision}") -} - -fn validate_application_marker( - root: &Path, - application_path: Option<&str>, - marker: &str, -) -> Result<(), String> { - let relative = application_path - .map(str::trim) - .filter(|value| !value.is_empty()) - .ok_or_else(|| "finalize 必须提供 applicationPath".to_string())?; - let normalized = normalize_relative_path(relative)?; - if !normalized.starts_with("game/") { - return Err("applicationPath 必须位于 game/".to_string()); - } - let path = resolve_local_project_path(root, &normalized)?; - let metadata = fs::symlink_metadata(&path) - .map_err(|error| format!("读取 applicationPath 失败：{error}"))?; - if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() == 0 { - return Err("applicationPath 必须是非空普通文件".to_string()); - } - if metadata.len() > UI_WORKFLOW_MAX_APPLICATION_BYTES { - return Err("applicationPath 超出受控大小".to_string()); - } - let content = - fs::read_to_string(&path).map_err(|_| "applicationPath 必须是 UTF-8 文本".to_string())?; - if !content.contains(marker) { - return Err(format!( - "applicationPath 缺少当前 UI State revision 标记：{marker}" - )); - } - Ok(()) -} - -fn apply_application_marker( - root: &Path, - project_id: &str, - application_path: Option<&str>, - page_id: &str, - ui_asset_id: &str, -) -> Result<(), String> { - let relative = application_path - .map(str::trim) - .filter(|value| !value.is_empty()) - .ok_or_else(|| "finalize 必须提供 applicationPath".to_string())?; - let normalized = normalize_relative_path(relative)?; - if !normalized.starts_with("game/") { - return Err("applicationPath 必须位于 game/".to_string()); - } - let path = resolve_local_project_path(root, &normalized)?; - let metadata = fs::symlink_metadata(&path) - .map_err(|error| format!("读取 applicationPath 失败：{error}"))?; - if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() == 0 { - return Err("applicationPath 必须是非空普通文件".to_string()); - } - if metadata.len() > UI_WORKFLOW_MAX_APPLICATION_BYTES { - return Err("applicationPath 超出受控大小".to_string()); - } - let snapshot = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: project_id.to_string(), - asset_id: ui_asset_id.to_string(), - })?; - let marker = application_marker(page_id, ui_asset_id, snapshot.revision); - let _lock = acquire_project_write_lock(root, "ui.workflow.apply")?; - let content = - fs::read_to_string(&path).map_err(|_| "applicationPath 必须是 UTF-8 文本".to_string())?; - let marker_comment = format!(""); - if content.lines().any(|line| line.trim() == marker_comment) { - return Ok(()); - } - let next = format!("{content}\n{marker_comment}\n"); - fs::write(&path, next.as_bytes()) - .map_err(|error| format!("应用 UI 页面 {} 到游戏失败：{error}", page_id))?; - advance_agent_runtime_project_revision_locked(root) - .map(|_| ()) - .map_err(|error| format!("UI 页面 {} 已写入但项目 revision 未推进：{error}", page_id))?; - Ok(()) -} - -fn write_final_receipt( - root: &Path, - project_id: &str, - source_asset_id: &str, - pages: &[UiWorkflowPageStatus], - route: &UiWorkflowFinalStageRoute, -) -> Result<(), String> { - let digest = Sha256::digest(source_asset_id.as_bytes()); - let relative = format!(".agent/ui-workflows/{}.json", &format!("{digest:x}")[..24]); - let path = resolve_local_project_path(root, &relative)?; - fs::create_dir_all( - path.parent() - .ok_or_else(|| "UI workflow receipt 缺少父目录".to_string())?, - ) - .map_err(|error| format!("创建 UI workflow receipt 目录失败：{error}"))?; - let receipt = UiWorkflowReceipt { - schema_version: UI_WORKFLOW_RECEIPT_SCHEMA_VERSION.to_string(), - project_id: project_id.to_string(), - source_asset_id: source_asset_id.to_string(), - pages: pages.to_vec(), - final_stage_route: route.clone(), - }; - let bytes = serde_json::to_vec_pretty(&receipt) - .map_err(|error| format!("序列化 UI workflow receipt 失败：{error}"))?; - let temporary = path.with_extension("json.tmp"); - fs::write(&temporary, &bytes) - .map_err(|error| format!("写入 UI workflow receipt 临时文件失败：{error}"))?; - fs::rename(&temporary, &path) - .map_err(|error| format!("安装 UI workflow receipt 失败：{error}"))?; - let installed = - fs::read(&path).map_err(|error| format!("回读 UI workflow receipt 失败：{error}"))?; - if installed != bytes { - return Err("UI workflow receipt 安装后回读不一致".to_string()); - } - Ok(()) -} - -#[cfg(test)] -mod tests { - use super::*; - - fn fixture_png(path: &Path) { - let image = image::RgbaImage::from_pixel(8, 8, image::Rgba([32, 48, 64, 255])); - image.save(path).expect("write workflow fixture png"); - } - - fn fixture_asset( - root: &Path, - relative_path: &str, - kind: GameCreationAppAssetKind, - resource_id: &str, - ) -> GameCreationAppAssetManifestEntry { - register_local_asset_at( - root, - relative_path, - kind, - "image/png", - "workflow-test", - GameCreationAppAssetSource { - kind: GameCreationAppAssetSourceKind::Generated, - canvas_project_id: None, - resource_id: Some(resource_id.to_string()), - asset_object_id: None, - task_id: None, - prompt: None, - model: None, - generation_route: None, - generation_kind: None, - reference_resource_ids: Vec::new(), - }, - ) - .expect("register workflow fixture asset"); - read_existing_manifest_for_project(root) - .expect("read workflow fixture manifest") - .assets - .into_iter() - .find(|asset| asset.local_path == relative_path) - .expect("find workflow fixture asset") - } - - #[test] - fn workflow_input_rejects_duplicate_page_or_design_ids() { - let input = UiWorkflowRunInput { - operation: UiWorkflowOperation::Prepare, - source_asset_id: "prototype".to_string(), - pages: vec![ - UiWorkflowPageInput { - page_id: "home".to_string(), - title: "首页".to_string(), - description: String::new(), - design_asset_id: "design-home".to_string(), - sprite_asset_ids: Vec::new(), - font_asset_ids: Vec::new(), - application_path: None, - }, - UiWorkflowPageInput { - page_id: "home".to_string(), - title: "首页副本".to_string(), - description: String::new(), - design_asset_id: "design-home-2".to_string(), - sprite_asset_ids: Vec::new(), - font_asset_ids: Vec::new(), - application_path: None, - }, - ], - }; - assert!(validate_workflow_input(&input) - .expect_err("duplicate page ids must be rejected") - .contains("pageId")); - } - - #[test] - fn application_marker_is_revision_bound() { - assert_eq!( - application_marker("home", "ui-1", 2), - "GENARRATIVE_UI_PAGE:home:ui-1:2" - ); - } - - #[test] - fn discover_ui_pages_reads_registry_and_sorts_stable_ids() { - let directory = tempfile::tempdir().expect("create discovery fixture project"); - let root = directory.path(); - init_local_game_project_at(root, "ui-discovery", "UI discovery") - .expect("init discovery fixture project"); - fs::write( - root.join(UI_WORKFLOW_PAGE_REGISTRY_PATH), - r#"[ - {"pageId":"settings","title":"设置","description":"调整偏好","applicationPath":"game/index.html"}, - {"pageId":"home","title":"首页","description":"开始游戏","applicationPath":"game/index.html"} - ]"#, - ) - .expect("write page registry"); - - let pages = discover_ui_pages(root).expect("discover registered pages"); - assert_eq!( - pages - .iter() - .map(|page| page.page_id.as_str()) - .collect::>(), - ["home", "settings"] - ); - assert_eq!( - pages[0].required_design_asset_path, - "assets/ui-pages/home.png" - ); - assert_eq!(pages[0].discovered_from, UI_WORKFLOW_PAGE_REGISTRY_PATH); - } - - #[test] - fn discover_ui_pages_reads_controlled_marker() { - let directory = tempfile::tempdir().expect("create marker discovery fixture project"); - let root = directory.path(); - init_local_game_project_at(root, "ui-marker-discovery", "UI marker discovery") - .expect("init marker discovery fixture project"); - let index = root.join("game/index.html"); - let existing = fs::read_to_string(&index).expect("read game index"); - fs::write( - &index, - format!( - "{existing}\n\n" - ), - ) - .expect("write page marker"); - - let pages = discover_ui_pages(root).expect("discover marker page"); - assert_eq!(pages.len(), 1); - assert_eq!(pages[0].page_id, "inventory"); - assert!(pages[0].discovered_from.starts_with("game/index.html:")); - } - - #[test] - fn discover_ui_pages_rejects_missing_declarations() { - let directory = tempfile::tempdir().expect("create empty discovery fixture project"); - let root = directory.path(); - init_local_game_project_at(root, "ui-empty-discovery", "UI empty discovery") - .expect("init empty discovery fixture project"); - - let error = discover_ui_pages(root).expect_err("empty discovery must block"); - assert!(error.contains("未发现 UI 页面声明")); - } - - #[tokio::test] - async fn workflow_prepare_does_not_claim_semantics_before_provider() { - let directory = tempfile::tempdir().expect("create workflow fixture project"); - let root = directory.path(); - init_local_game_project_at(root, "ui-workflow-project", "UI workflow") - .expect("init workflow fixture project"); - let source_path = root.join("assets/ui-prototype.png"); - let design_path = root.join("assets/home.png"); - fixture_png(&source_path); - fixture_png(&design_path); - let source = fixture_asset( - root, - "assets/ui-prototype.png", - GameCreationAppAssetKind::UiDesign, - "source-ui", - ); - let design = fixture_asset( - root, - "assets/home.png", - GameCreationAppAssetKind::UiDesign, - "design-home", - ); - let page = |operation| UiWorkflowRunInput { - operation, - source_asset_id: source.id.clone(), - pages: vec![UiWorkflowPageInput { - page_id: "home".to_string(), - title: "首页".to_string(), - description: "主界面".to_string(), - design_asset_id: design.id.clone(), - sprite_asset_ids: Vec::new(), - font_asset_ids: Vec::new(), - application_path: Some("game/index.html".to_string()), - }], - }; - - let prepared = run_ui_workflow_at(root, page(UiWorkflowOperation::Prepare)) - .await - .expect("prepare workflow"); - assert!(!prepared.completed); - assert_eq!(prepared.pages[0].stage, UiWorkflowPageStage::ReferenceReady); - assert!(prepared.revision_advance_count > 0); - - let status = run_ui_workflow_at(root, page(UiWorkflowOperation::Status)) - .await - .expect("status workflow"); - assert_eq!(status.pages[0].stage, UiWorkflowPageStage::ReferenceReady); - assert!(status.pages[0] - .blockers - .iter() - .any(|blocker| blocker.contains("结构树"))); - assert_eq!(status.revision_advance_count, 0); - let persisted = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: "ui-workflow-project".to_string(), - asset_id: status.pages[0].ui_asset_id.clone(), - }) - .expect("read workflow UI state"); - assert!(persisted.state.ui_trees.is_empty()); - } - - #[tokio::test] - async fn workflow_prepare_installs_registered_sprite_and_font_assets() { - let directory = tempfile::tempdir().expect("create workflow component fixture"); - let root = directory.path(); - init_local_game_project_at(root, "ui-workflow-assets", "UI workflow assets") - .expect("init workflow component fixture"); - fs::create_dir_all(root.join("assets")).expect("create fixture assets"); - fixture_png(&root.join("assets/ui-prototype.png")); - fixture_png(&root.join("assets/home.png")); - fixture_png(&root.join("assets/start-button.png")); - let source = fixture_asset( - root, - "assets/ui-prototype.png", - GameCreationAppAssetKind::UiDesign, - "source-ui", - ); - let design = fixture_asset( - root, - "assets/home.png", - GameCreationAppAssetKind::UiDesign, - "design-home", - ); - let sprite = fixture_asset( - root, - "assets/start-button.png", - GameCreationAppAssetKind::Icon, - "start-button", - ); - let font_path = root.join("assets/ui-font.ttf"); - fs::copy( - Path::new(env!("CARGO_MANIFEST_DIR")).join("../../../public/fusion-pixel.ttf"), - &font_path, - ) - .expect("copy checked-in font fixture"); - let font = register_local_asset_at( - root, - "assets/ui-font.ttf", - GameCreationAppAssetKind::Font, - "font/ttf", - "workflow-test", - GameCreationAppAssetSource { - kind: GameCreationAppAssetSourceKind::Generated, - canvas_project_id: None, - resource_id: Some("ui-font".to_string()), - asset_object_id: None, - task_id: None, - prompt: None, - model: None, - generation_route: None, - generation_kind: None, - reference_resource_ids: Vec::new(), - }, - ) - .expect("register font fixture"); - let prepared = run_ui_workflow_at( - root, - UiWorkflowRunInput { - operation: UiWorkflowOperation::Prepare, - source_asset_id: source.id, - pages: vec![UiWorkflowPageInput { - page_id: "home".to_string(), - title: "首页".to_string(), - description: "主界面".to_string(), - design_asset_id: design.id, - sprite_asset_ids: vec![sprite.id.clone()], - font_asset_ids: vec![font.id.clone()], - application_path: Some("game/index.html".to_string()), - }], - }, - ) - .await - .expect("prepare workflow component assets"); - let persisted = load_ui_design_state_at(LoadUiDesignStateInput { - project_path: root.to_string_lossy().into_owned(), - expected_project_id: "ui-workflow-assets".to_string(), - asset_id: prepared.pages[0].ui_asset_id.clone(), - }) - .expect("read workflow component state"); - assert!(persisted - .state - .sprite_assets - .keys() - .any(|id| id.as_str() == sprite.id)); - assert!(persisted - .state - .font_assets - .keys() - .any(|id| id.as_str() == font.id)); - assert!(persisted.state.ui_trees.is_empty()); - } -} diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/importAdapter.ts b/apps/ai-game-creator-shell/src/features/ui-editor/importAdapter.ts index e2f238527..15c260aa9 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/importAdapter.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/importAdapter.ts @@ -66,12 +66,6 @@ export async function prepareDesignImageBatch( scopeId, ); const image: UIDesignImage = { - metadata: { - name: '', - description: '', - role: null, - slave_to: null, - }, path: asset.localPath, pixel_size: pixelSize, pixels_per_unit: 1, diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/merge.ts b/apps/ai-game-creator-shell/src/features/ui-editor/merge.ts deleted file mode 100644 index b90781bb4..000000000 --- a/apps/ai-game-creator-shell/src/features/ui-editor/merge.ts +++ /dev/null @@ -1,10 +0,0 @@ -import type { MergeDTO } from './types/MergeDTO'; -import type { State } from './types/State'; - -/** 合并阶段返回一棵新树，成功后替换当前全部逐图识别树。 */ -export function applyMergeResult(state: State, result: MergeDTO): State { - return { - ...structuredClone(state), - ui_trees: [structuredClone(result.ui_tree)], - }; -} diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/nodeTransformGeometry.ts b/apps/ai-game-creator-shell/src/features/ui-editor/nodeTransformGeometry.ts index 4a0b09382..1a167ba3c 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/nodeTransformGeometry.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/nodeTransformGeometry.ts @@ -1,6 +1,8 @@ import type { Node } from './types/Node'; import type { NodeId } from './types/NodeId'; +import type { State } from './types/State'; import type { Transform } from './types/Transform'; +import type { UIDesignImageId } from './types/UIDesignImageId'; export type ResizeAxis = 'horizontal' | 'vertical'; @@ -17,6 +19,32 @@ export type NodePageContext = { parentRect: PageRect; }; +/** State-level geometry seam shared by preview, inspector and transitions. */ +export function findStateNodePageContext( + state: State, + treeId: UIDesignImageId, + nodeId: NodeId, +): NodePageContext | null { + const tree = state.ui_trees.find( + (candidate) => candidate.src_ui_design === treeId, + ); + const image = state.ui_design_images[treeId]; + if ( + !tree || + !image || + !Number.isFinite(image.pixels_per_unit) || + image.pixels_per_unit <= 0 + ) { + return null; + } + const size: [number, number] = [ + image.pixel_size[0] / image.pixels_per_unit, + image.pixel_size[1] / image.pixels_per_unit, + ]; + if (!size.every((value) => Number.isFinite(value) && value > 0)) return null; + return findNodePageContext(tree.root, nodeId, pageRectFromSize(size)); +} + const MIN_NODE_SIZE = 1; export function pageRectFromSize(size: [number, number]): PageRect { diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/requisites.ts b/apps/ai-game-creator-shell/src/features/ui-editor/requisites.ts index 759792923..586c446b8 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/requisites.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/requisites.ts @@ -38,37 +38,6 @@ export function validateComponentRecognitionPrerequisites( if (ids.length > 4) { issues.push({ code: 'design-image-limit', message: '界面图最多 4 张' }); } - for (const id of ids) { - const image = state.ui_design_images[id]!; - const { role, slave_to: slaveTo } = image.metadata; - if (role === 'Page' && slaveTo !== null) { - issues.push({ - code: 'page-has-slave-to', - message: '主页面不能设置归属页面', - resourceId: id, - }); - } else if (role !== null && role !== 'Page') { - if (slaveTo === null) { - issues.push({ - code: 'missing-slave-to', - message: '该界面角色需要选择归属主页面', - resourceId: id, - }); - } else if (slaveTo === id) { - issues.push({ - code: 'self-slave-to', - message: '界面不能归属于自身', - resourceId: id, - }); - } else if (state.ui_design_images[slaveTo]?.metadata.role !== 'Page') { - issues.push({ - code: 'invalid-slave-to', - message: '归属页面必须是有效主页面', - resourceId: id, - }); - } - } - } return issues; } @@ -131,24 +100,6 @@ function visitNodes( } // 结果检查与进入步骤的前置条件保持分离；调用方只把结果作为非阻塞提示。 -export function validateReferenceAnalysisResult( - state: State, -): UiEditorPrerequisiteIssue[] { - const images = Object.values(state.ui_design_images); - if (images.length === 0) { - return [{ code: 'missing-analysis-input', message: '尚未导入参考图' }]; - } - if (images.every((image) => image.metadata.role === null)) { - return [ - { - code: 'missing-reference-analysis', - message: '参考图尚未设置界面用途', - }, - ]; - } - return []; -} - export function validateStructureRecognitionResult( state: State, ): UiEditorPrerequisiteIssue[] { diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/stageStatusOverview.ts b/apps/ai-game-creator-shell/src/features/ui-editor/stageStatusOverview.ts index 80dc27fac..cdfb2be40 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/stageStatusOverview.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/stageStatusOverview.ts @@ -1,4 +1,5 @@ import type { Node as UiNode } from './types/Node'; +import type { NodeId } from './types/NodeId'; import type { NodeMetadata } from './types/NodeMetadata'; import type { StageStatus } from './types/StageStatus'; import type { UIDesignImageId } from './types/UIDesignImageId'; @@ -14,6 +15,11 @@ export type UiTreeNodeTarget = { node: UiNode; }; +export type UiTreeNodeCursor = { + treeId: UIDesignImageId; + nodeId: NodeId; +}; + export type StageStatusOverview = { total: number; needsAttention: number; @@ -79,22 +85,28 @@ export function getStageStatusTargets( export function getNextUiTreeNodeTarget( targets: UiTreeNodeTarget[], - previousNodeId: string | null, + previous: string | UiTreeNodeCursor | null, ): UiTreeNodeTarget | null { if (targets.length === 0) return null; - const previousIndex = targets.findIndex( - ({ node }) => node.id === previousNodeId, - ); + let previousIndex = -1; + if (typeof previous === 'string') { + previousIndex = targets.findIndex(({ node }) => node.id === previous); + } else if (previous) { + previousIndex = targets.findIndex( + ({ treeId, node }) => + treeId === previous.treeId && node.id === previous.nodeId, + ); + } return targets[(previousIndex + 1) % targets.length] ?? null; } export function getNextMatchingUiTreeNodeTarget( uiTrees: UITree[], - previousNodeId: string | null, + previous: string | UiTreeNodeCursor | null, matches: (target: UiTreeNodeTarget) => boolean, ): UiTreeNodeTarget | null { return getNextUiTreeNodeTarget( collectUiTreeNodeTargets(uiTrees).filter(matches), - previousNodeId, + previous, ); } diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/stateInvariants.ts b/apps/ai-game-creator-shell/src/features/ui-editor/stateInvariants.ts new file mode 100644 index 000000000..cd792d2b1 --- /dev/null +++ b/apps/ai-game-creator-shell/src/features/ui-editor/stateInvariants.ts @@ -0,0 +1,57 @@ +import type { Node } from './types/Node'; +import type { State } from './types/State'; + +export type UiDesignInvariantIssue = { + code: 'duplicate-node' | 'invalid-image' | 'missing-tree-image'; + message: string; +}; + +/** Frontend display/save projection of persistable State invariants. + * Rust remains authoritative; this seam only prevents obviously invalid saves + * and gives the view a stable, user-visible failure message. + */ +export function validateUiDesignState(state: State): UiDesignInvariantIssue[] { + const issues: UiDesignInvariantIssue[] = []; + const nodeIds = new Set(); + for (const [id, image] of Object.entries(state.ui_design_images)) { + // 这个 seam 专门接住可能残缺的持久化 State，取字段前先判类型，别把 TypeError + // 漏给调用方，否则保存失败只会退化成通用文案。 + if ( + typeof image.path !== 'string' || + image.path.trim() === '' || + !Array.isArray(image.pixel_size) || + !image.pixel_size.every((value) => Number.isFinite(value) && value > 0) || + !Number.isFinite(image.pixels_per_unit) || + image.pixels_per_unit <= 0 + ) { + issues.push({ + code: 'invalid-image', + message: `界面图 ${id} 的尺寸或路径无效`, + }); + } + } + const visit = (node: Node) => { + if (nodeIds.has(node.id)) { + issues.push({ + code: 'duplicate-node', + message: `节点 ID 重复：${node.id}`, + }); + } + nodeIds.add(node.id); + for (const child of node.children) visit(child); + }; + for (const tree of state.ui_trees) { + if (!state.ui_design_images[tree.src_ui_design]) { + issues.push({ + code: 'missing-tree-image', + message: `UI 树引用了缺失界面图：${tree.src_ui_design}`, + }); + } + visit(tree.root); + } + return issues; +} + +export function firstUiDesignInvariantMessage(state: State): string | null { + return validateUiDesignState(state)[0]?.message ?? null; +} diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/stateTransition.ts b/apps/ai-game-creator-shell/src/features/ui-editor/stateTransition.ts new file mode 100644 index 000000000..a559e74ed --- /dev/null +++ b/apps/ai-game-creator-shell/src/features/ui-editor/stateTransition.ts @@ -0,0 +1,126 @@ +import type { Component } from './types/Component'; +import type { Node } from './types/Node'; +import type { NodeId } from './types/NodeId'; +import type { NodeMetadata } from './types/NodeMetadata'; +import type { State } from './types/State'; +import type { UIDesignImageId } from './types/UIDesignImageId'; + +export type StateTransitionFailure = + | 'missing' + | 'invalid' + | `invalid:${string}`; + +export type StateTransitionResult = + | { ok: true; state: State } + | { ok: false; reason: StateTransitionFailure }; + +export type UiEditorCommand = + | { + type: 'set-tree-offset'; + treeId: UIDesignImageId; + min: [number, number]; + } + | { + type: 'set-node-metadata'; + treeId: UIDesignImageId; + nodeId: NodeId; + patch: Partial< + Pick< + NodeMetadata, + | 'name' + | 'description' + | 'layout_status' + | 'component_status' + | 'allow_llm_edit_layout' + | 'allow_llm_edit_component' + > + >; + } + | { + type: 'set-node-component'; + treeId: UIDesignImageId; + nodeId: NodeId; + component: Component | null; + }; + +function cloneState(state: State): State { + return structuredClone(state); +} + +function findNode(node: Node, id: NodeId): Node | null { + if (node.id === id) return node; + for (const child of node.children) { + const found = findNode(child, id); + if (found) return found; + } + return null; +} + +function imageLogicalSize( + state: State, + treeId: UIDesignImageId, +): [number, number] | null { + const image = state.ui_design_images[treeId]; + if ( + !image || + !Number.isFinite(image.pixels_per_unit) || + image.pixels_per_unit <= 0 + ) { + return null; + } + const size: [number, number] = [ + image.pixel_size[0] / image.pixels_per_unit, + image.pixel_size[1] / image.pixels_per_unit, + ]; + return size.every((value) => Number.isFinite(value) && value > 0) + ? size + : null; +} + +/** + * React-free semantic State transition seam. The hook is an adapter that adds + * locking/history; callers provide a command and receive a complete next State + * or a typed failure, never a partially-mutated tree. + */ +export function applyUiEditorCommand( + current: State, + command: UiEditorCommand, +): StateTransitionResult { + const next = cloneState(current); + const tree = next.ui_trees.find( + (candidate) => candidate.src_ui_design === command.treeId, + ); + if (!tree) return { ok: false, reason: 'missing' }; + + if (command.type === 'set-tree-offset') { + // 只校验元素有限不够：`[]` 会让 every 空真通过，缺第二个坐标时 max 会算出 NaN。 + if (command.min.length !== 2 || !command.min.every(Number.isFinite)) + return { ok: false, reason: 'invalid' }; + const size = imageLogicalSize(next, command.treeId); + if (!size) return { ok: false, reason: 'invalid' }; + tree.root.offset = { + min: [...command.min], + max: [command.min[0] + size[0], command.min[1] + size[1]], + }; + return { ok: true, state: next }; + } + + const node = findNode(tree.root, command.nodeId); + if (!node) return { ok: false, reason: 'missing' }; + + if (command.type === 'set-node-component') { + node.component = structuredClone(command.component); + node.metadata.component_status = 'NoProblem'; + return { ok: true, state: next }; + } + + if (command.patch.component_status !== undefined && node.component === null) { + const status = command.patch.component_status; + if (status !== 'NoProblem') return { ok: false, reason: 'invalid' }; + } + const patch = Object.fromEntries( + Object.entries(command.patch).filter(([, value]) => value !== undefined), + ) as Partial; + node.metadata = { ...node.metadata, ...structuredClone(patch) }; + return { ok: true, state: next }; +} diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/types/BindingChange.ts b/apps/ai-game-creator-shell/src/features/ui-editor/types/BindingChange.ts deleted file mode 100644 index 3bb2c5c4d..000000000 --- a/apps/ai-game-creator-shell/src/features/ui-editor/types/BindingChange.ts +++ /dev/null @@ -1,6 +0,0 @@ -// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. -import type { NodeComponent } from "./NodeComponent"; -import type { NodeId } from "./NodeId"; -import type { StageStatus } from "./StageStatus"; - -export type BindingChange = { node_id: NodeId, component: NodeComponent, component_status: StageStatus, }; diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/types/BindingDTO.ts b/apps/ai-game-creator-shell/src/features/ui-editor/types/BindingDTO.ts deleted file mode 100644 index beb340894..000000000 --- a/apps/ai-game-creator-shell/src/features/ui-editor/types/BindingDTO.ts +++ /dev/null @@ -1,4 +0,0 @@ -// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. -import type { BindingChange } from "./BindingChange"; - -export type BindingDTO = { changes: Array, }; diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/types/Node.ts b/apps/ai-game-creator-shell/src/features/ui-editor/types/Node.ts index bac60a9ca..4b29eef76 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/types/Node.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/types/Node.ts @@ -4,5 +4,6 @@ import type { Component } from "./Component"; import type { ControlLayout } from "./ControlLayout"; import type { NodeId } from "./NodeId"; import type { NodeMetadata } from "./NodeMetadata"; +import type { NodeOffset } from "./NodeOffset"; -export type Node = { id: NodeId, layout: ControlLayout, metadata: NodeMetadata, component: Component | null, children_display_mode: ChildrenDisplayMode, children: Array, }; +export type Node = { id: NodeId, layout: ControlLayout, metadata: NodeMetadata, component: Component | null, children_display_mode: ChildrenDisplayMode, children: Array, offset: NodeOffset, }; diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/types/MergeDTO.ts b/apps/ai-game-creator-shell/src/features/ui-editor/types/NodeOffset.ts similarity index 56% rename from apps/ai-game-creator-shell/src/features/ui-editor/types/MergeDTO.ts rename to apps/ai-game-creator-shell/src/features/ui-editor/types/NodeOffset.ts index 366a191e3..13ad81ff0 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/types/MergeDTO.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/types/NodeOffset.ts @@ -1,4 +1,3 @@ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. -import type { UITree } from "./UITree"; -export type MergeDTO = { ui_tree: UITree, }; +export type NodeOffset = { min: [number, number], max: [number, number], }; diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImage.ts b/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImage.ts index b1f383426..c4cf6dbd5 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImage.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImage.ts @@ -1,4 +1,3 @@ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. -import type { UIDesignImageMetadata } from "./UIDesignImageMetadata"; -export type UIDesignImage = { metadata: UIDesignImageMetadata, path: string, pixel_size: [number, number], pixels_per_unit: number, }; +export type UIDesignImage = { path: string, pixel_size: [number, number], pixels_per_unit: number, }; diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImageMetadata.ts b/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImageMetadata.ts deleted file mode 100644 index 2e9df7fd3..000000000 --- a/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImageMetadata.ts +++ /dev/null @@ -1,5 +0,0 @@ -// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. -import type { UIDesignImageId } from "./UIDesignImageId"; -import type { UIDesignImageRole } from "./UIDesignImageRole"; - -export type UIDesignImageMetadata = { name: string, description: string, role: UIDesignImageRole | null, slave_to: UIDesignImageId | null, }; diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImageRole.ts b/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImageRole.ts deleted file mode 100644 index 131b0860b..000000000 --- a/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignImageRole.ts +++ /dev/null @@ -1,3 +0,0 @@ -// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. - -export type UIDesignImageRole = "Page" | "Section" | "Modal" | "Drawer" | "Popover" | "State" | "Scrolled" | "Detail"; diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignSuggestionTreeNode.ts b/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignSuggestionTreeNode.ts deleted file mode 100644 index fe0b35bc1..000000000 --- a/apps/ai-game-creator-shell/src/features/ui-editor/types/UIDesignSuggestionTreeNode.ts +++ /dev/null @@ -1,5 +0,0 @@ -// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. -import type { UIDesignImageId } from "./UIDesignImageId"; -import type { UIDesignImageRole } from "./UIDesignImageRole"; - -export type UIDesignSuggestionTreeNode = { id: UIDesignImageId, name: string, description: string, role: UIDesignImageRole, children: Array, }; diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/uiDesignResourceBridge.ts b/apps/ai-game-creator-shell/src/features/ui-editor/uiDesignResourceBridge.ts index 39168801f..459155ee0 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/uiDesignResourceBridge.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/uiDesignResourceBridge.ts @@ -2,120 +2,47 @@ import type { GameCreationAppAssetManifestEntry, GameCreationAppManifest, } from '../../../../../packages/shared/src/contracts/gameCreationApp'; -import { - GAME_CREATION_APP_UI_DESIGN_ASSET_KIND, - isGameCreationAppUiDesignDocAsset, - parseGameCreationAppAssetKind, -} from '../../../../../packages/shared/src/contracts/gameCreationApp'; -export type UiDesignResourceBridgeResult = { +/** + * 一张设计图的输入引用：给已登记资源的 assetId，或给项目内相对路径。 + * 两者只能二选一，与 Rust 侧 `每张设计图必须且只能给 assetId 或 path` 的判据一致。 + */ +export type UiDesignDocImageReference = + | { assetId: string; path?: never } + | { assetId?: never; path: string }; + +export type UiDesignDocCreated = { asset: GameCreationAppAssetManifestEntry; manifest: GameCreationAppManifest; + relativePath: string; + imageIds: Array; committedProjectRevision: number; - created: boolean; }; -export type UiDesignResourceBridgeInvoke = ( +export type UiDesignDocInvoke = ( command: string, args?: Record, ) => Promise; -function uiWorkflowStagePriority( - generationKind: string | null | undefined, -): number { - switch (generationKind) { - case 'ui-workflow.completed': - return 3; - case 'ui-workflow.binding-ready': - return 2; - case 'ui-workflow.reference-ready': - return 1; - default: - return 0; - } -} - -export function findLinkedUiDesignResource( - manifest: GameCreationAppManifest, - prototypeAssetId: string, -) { - const normalizedId = prototypeAssetId.trim(); - if (!normalizedId) return null; - const prototype = manifest.assets.find((asset) => asset.id === normalizedId); - const referenceIds = new Set( - [ - normalizedId, - prototype?.source.resourceId, - prototype?.source.assetObjectId, - ].filter((value): value is string => Boolean(value?.trim())), - ); - return ( - manifest.assets - .filter( - (asset) => - isGameCreationAppUiDesignDocAsset(asset) && - asset.source.referenceResourceIds?.some((reference) => - referenceIds.has(reference), - ), - ) - .sort( - (left, right) => - uiWorkflowStagePriority(right.source.generationKind) - - uiWorkflowStagePriority(left.source.generationKind), - )[0] ?? null - ); -} - -export async function ensureUiDesignResourceForPrototype({ +/** + * 新建一份 UI 设计文档。每次调用都新建，不做「原型 → 已存在文档」的复用查找； + * 未登记的相对路径由 Rust 侧顺带登记成图片资源。 + */ +export async function createUiDesignDocFromImages({ projectPath, - manifest, - prototypeAssetId, + expectedProjectId, + images, invoke, }: { projectPath: string; - manifest: GameCreationAppManifest; - prototypeAssetId: string; - invoke: UiDesignResourceBridgeInvoke; -}): Promise { - const normalizedPrototypeAssetId = prototypeAssetId.trim(); - if (!normalizedPrototypeAssetId) { - throw new Error('UI 原型资产身份不能为空'); + expectedProjectId: string; + images: Array; + invoke: UiDesignDocInvoke; +}): Promise { + if (images.length === 0) { + throw new Error('请至少选择一张界面图'); } - const prototype = manifest.assets.find( - (asset) => asset.id === normalizedPrototypeAssetId, - ); - if ( - !prototype || - parseGameCreationAppAssetKind( - prototype.kind, - 'ui-design-resource-bridge.prototype', - ) !== GAME_CREATION_APP_UI_DESIGN_ASSET_KIND - ) { - throw new Error('目标资源不是 UI 原型图片'); - } - if (!prototype.mediaType.toLowerCase().startsWith('image/')) { - throw new Error('UI 原型资源必须是图片'); - } - const linked = findLinkedUiDesignResource( - manifest, - normalizedPrototypeAssetId, - ); - if (linked) { - return { - asset: linked, - manifest, - committedProjectRevision: 0, - created: false, - }; - } - return invoke( - 'ensure_ui_design_resource_for_prototype', - { - input: { - projectPath, - expectedProjectId: manifest.projectId, - prototypeAssetId: normalizedPrototypeAssetId, - }, - }, - ); + return invoke('create_ui_design_doc_from_images', { + input: { projectPath, expectedProjectId, images }, + }); } diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/uiDesignSuggestions.ts b/apps/ai-game-creator-shell/src/features/ui-editor/uiDesignSuggestions.ts deleted file mode 100644 index 4727c7cdf..000000000 --- a/apps/ai-game-creator-shell/src/features/ui-editor/uiDesignSuggestions.ts +++ /dev/null @@ -1,52 +0,0 @@ -import type { State } from './types/State'; -import type { UIDesignImageId } from './types/UIDesignImageId'; -import type { UIDesignSuggestionTreeNode } from './types/UIDesignSuggestionTreeNode'; - -/** - * Applies semantic suggestions conservatively. The tree carries relationships; - * existing metadata remains authoritative whenever it is already populated. - * Persisted `slave_to` remains the owning Page ID, so nested descendants inherit - * their root Page rather than pointing at an intermediate Section. - */ -export function applyUiDesignSuggestions( - state: State, - suggestions: readonly UIDesignSuggestionTreeNode[], -): State { - const next = structuredClone(state); - - function applyNode( - node: UIDesignSuggestionTreeNode, - pageId: UIDesignImageId | null, - ): void { - const image = next.ui_design_images[node.id]; - if (!image) return; - - if (image.metadata.name.trim().length === 0 && node.name.trim()) { - image.metadata.name = node.name.trim(); - } - if (image.metadata.role === null) { - image.metadata.role = node.role; - } - if (image.metadata.slave_to === null && pageId !== null) { - image.metadata.slave_to = pageId; - } - if ( - image.metadata.description.trim().length === 0 && - node.description.trim() - ) { - image.metadata.description = node.description.trim(); - } - - const effectiveRole = image.metadata.role ?? node.role; - const childPageId = effectiveRole === 'Page' ? node.id : pageId; - for (const child of node.children) { - applyNode(child, childPageId); - } - } - - for (const root of suggestions) { - applyNode(root, null); - } - - return next; -} diff --git a/apps/ai-game-creator-shell/src/features/ui-editor/useUiEditorState.ts b/apps/ai-game-creator-shell/src/features/ui-editor/useUiEditorState.ts index a83ab93b4..0a0b1782a 100644 --- a/apps/ai-game-creator-shell/src/features/ui-editor/useUiEditorState.ts +++ b/apps/ai-game-creator-shell/src/features/ui-editor/useUiEditorState.ts @@ -10,6 +10,7 @@ import { resolveReparentTransform, } from './nodeTransformGeometry'; import { validateSpriteBorder } from './spriteBorder'; +import { applyUiEditorCommand } from './stateTransition'; import type { ChildrenDisplayMode } from './types/ChildrenDisplayMode'; import type { Component } from './types/Component'; import type { FontAsset } from './types/FontAsset'; @@ -17,13 +18,13 @@ import type { FontAssetId } from './types/FontAssetId'; import type { Node } from './types/Node'; import type { NodeId } from './types/NodeId'; import type { NodeMetadata } from './types/NodeMetadata'; +import type { NodeOffset } from './types/NodeOffset'; import type { SpriteAsset } from './types/SpriteAsset'; import type { SpriteAssetId } from './types/SpriteAssetId'; import type { SpriteBorder } from './types/SpriteBorder'; import type { State } from './types/State'; import type { UIDesignImage } from './types/UIDesignImage'; import type { UIDesignImageId } from './types/UIDesignImageId'; -import type { UIDesignImageRole } from './types/UIDesignImageRole'; import type { UiNodeMoveRequest } from './types/UiNodeMoveRequest'; export const EMPTY_UI_EDITOR_STATE: State = { @@ -34,6 +35,7 @@ export const EMPTY_UI_EDITOR_STATE: State = { }; const MAX_HISTORY_LENGTH = 100; +export const UI_TREE_PADDING = 48; export type UiEditorOperationFailureReason = | 'locked' @@ -82,34 +84,11 @@ type NodeLocation = { index: number; }; -function wouldCreateSlaveToCycle( - images: State['ui_design_images'], - id: UIDesignImageId, - slaveTo: UIDesignImageId, -): boolean { - let current: UIDesignImageId | null = slaveTo; - const visited = new Set(); - while (current !== null) { - if (current === id || visited.has(current)) return true; - visited.add(current); - const image: UIDesignImage | undefined = images[current]; - if (!image) return true; - current = image.metadata.slave_to; - } - return false; -} - function visitNodes(node: Node, visit: (node: Node) => void): void { visit(node); for (const child of node.children) visitNodes(child, visit); } -function isProblematicComponentStatus( - status: NodeMetadata['component_status'], -): boolean { - return typeof status !== 'string'; -} - function existingNodeIds(state: State): Set { const ids = new Set(); for (const tree of state.ui_trees) { @@ -156,6 +135,7 @@ function createPageRoot(state: State): Node { component: null, children_display_mode: 'Stack', children: [], + offset: { min: [0, 0], max: [0, 0] }, }; } @@ -187,9 +167,56 @@ function createHumanNode(state: State): Node { component: null, children_display_mode: 'Stack', children: [], + offset: { min: [0, 0], max: [0, 0] }, }; } +function treeSize(state: State, treeId: UIDesignImageId): [number, number] { + const image = state.ui_design_images[treeId]; + if ( + !image || + !Number.isFinite(image.pixels_per_unit) || + image.pixels_per_unit <= 0 + ) { + throw new Error(`界面图 ${treeId} 缺少合法尺寸`); + } + return [ + image.pixel_size[0] / image.pixels_per_unit, + image.pixel_size[1] / image.pixels_per_unit, + ]; +} + +function deriveTreeOffset(state: State, treeId: UIDesignImageId): NodeOffset { + const [width, height] = treeSize(state, treeId); + const existing = state.ui_trees.filter( + (tree) => tree.src_ui_design !== treeId, + ); + if (existing.length === 0) return { min: [0, 0], max: [width, height] }; + const maxX = Math.max( + ...existing.map( + (tree) => + (tree.root.offset?.min?.[0] ?? 0) + + treeSize(state, tree.src_ui_design)[0], + ), + ); + const minY = Math.min( + ...existing.map((tree) => tree.root.offset?.min?.[1] ?? 0), + ); + return { + min: [maxX + UI_TREE_PADDING, minY], + max: [maxX + UI_TREE_PADDING + width, minY + height], + }; +} + +export function createTree( + state: State, + treeId: UIDesignImageId, + root = createPageRoot(state), +) { + root.offset = deriveTreeOffset(state, treeId); + return { src_ui_design: treeId, root }; +} + function synchronizeDesignImageTrees(state: State): void { const imageIds = new Set(Object.keys(state.ui_design_images)); state.ui_trees = state.ui_trees.filter((tree) => @@ -197,7 +224,7 @@ function synchronizeDesignImageTrees(state: State): void { ); for (const [id] of Object.entries(state.ui_design_images)) { if (!state.ui_trees.some((tree) => tree.src_ui_design === id)) { - state.ui_trees.push({ src_ui_design: id, root: createPageRoot(state) }); + state.ui_trees.push(createTree(state, id)); } } } @@ -233,7 +260,6 @@ export type DesignImageInput = { export type RemovalImpact = { removedResourceCount: number; removedTreeCount: number; - clearedSlaveToCount: number; clearedTargetGraphicCount: number; clearedFontCount: number; }; @@ -450,9 +476,6 @@ export function designImageRemovalImpact( removedResourceCount: id in state.ui_design_images ? 1 : 0, removedTreeCount: state.ui_trees.filter((tree) => tree.src_ui_design === id) .length, - clearedSlaveToCount: Object.values(state.ui_design_images).filter( - (image) => image.metadata.slave_to === id, - ).length, clearedTargetGraphicCount: 0, clearedFontCount: 0, }; @@ -473,7 +496,6 @@ export function spriteAssetRemovalImpact( return { removedResourceCount: id in state.sprite_assets ? 1 : 0, removedTreeCount: 0, - clearedSlaveToCount: 0, clearedTargetGraphicCount, clearedFontCount: 0, }; @@ -494,7 +516,6 @@ export function fontAssetRemovalImpact( return { removedResourceCount: id in state.font_assets ? 1 : 0, removedTreeCount: 0, - clearedSlaveToCount: 0, clearedTargetGraphicCount: 0, clearedFontCount, }; @@ -695,86 +716,6 @@ export function useUiEditorState(initialState: State = EMPTY_UI_EDITOR_STATE) { [], ); - const setImageName = useCallback( - (id: UIDesignImageId, name: string): UiEditorOperationResult => { - const blocked = guard(); - if (blocked) return blocked; - const current = stateRef.current; - if (!(id in current.ui_design_images)) { - return { ok: false, reason: 'missing' }; - } - const next = cloneState(current); - next.ui_design_images[id]!.metadata.name = name; - commit(next); - return { ok: true, value: undefined }; - }, - [commit, guard], - ); - - const setImageDescription = useCallback( - (id: UIDesignImageId, description: string): UiEditorOperationResult => { - const blocked = guard(); - if (blocked) return blocked; - const current = stateRef.current; - if (!(id in current.ui_design_images)) { - return { ok: false, reason: 'missing' }; - } - const next = cloneState(current); - next.ui_design_images[id]!.metadata.description = description; - commit(next); - return { ok: true, value: undefined }; - }, - [commit, guard], - ); - - const setImageRole = useCallback( - ( - id: UIDesignImageId, - role: UIDesignImageRole | null, - ): UiEditorOperationResult => { - const blocked = guard(); - if (blocked) return blocked; - const current = stateRef.current; - if (!(id in current.ui_design_images)) { - return { ok: false, reason: 'missing' }; - } - const next = cloneState(current); - next.ui_design_images[id]!.metadata.role = role; - synchronizeDesignImageTrees(next); - commit(next); - return { ok: true, value: undefined }; - }, - [commit, guard], - ); - - const setImageSlaveTo = useCallback( - ( - id: UIDesignImageId, - slaveTo: UIDesignImageId | null, - ): UiEditorOperationResult => { - const blocked = guard(); - if (blocked) return blocked; - const current = stateRef.current; - if (!(id in current.ui_design_images)) { - return { ok: false, reason: 'missing' }; - } - if (slaveTo !== null && !(slaveTo in current.ui_design_images)) { - return { ok: false, reason: 'missing' }; - } - if ( - slaveTo !== null && - wouldCreateSlaveToCycle(current.ui_design_images, id, slaveTo) - ) { - return { ok: false, reason: 'invalid:slave_to 不能形成循环' }; - } - const next = cloneState(current); - next.ui_design_images[id]!.metadata.slave_to = slaveTo; - commit(next); - return { ok: true, value: undefined }; - }, - [commit, guard], - ); - const addDesignImages = useCallback( (entries: readonly DesignImageInput[]): UiEditorOperationResult => { const blocked = guard(); @@ -951,6 +892,26 @@ export function useUiEditorState(initialState: State = EMPTY_UI_EDITOR_STATE) { [commit, guard], ); + const setTreeOffset = useCallback( + ( + treeId: UIDesignImageId, + min: [number, number], + ): UiEditorOperationResult => { + const blocked = guard(); + if (blocked) return blocked; + if (!min.every(Number.isFinite)) return { ok: false, reason: 'invalid' }; + const result = applyUiEditorCommand(stateRef.current, { + type: 'set-tree-offset', + treeId, + min, + }); + if (!result.ok) return result; + commit(result.state); + return { ok: true, value: undefined }; + }, + [commit, guard], + ); + const insertNodeAfter = useCallback( ( treeId: UIDesignImageId, @@ -1134,21 +1095,14 @@ export function useUiEditorState(initialState: State = EMPTY_UI_EDITOR_STATE) { if (component && !isValidComponent(component)) { return { ok: false, reason: 'invalid' }; } - const current = stateRef.current; - const tree = current.ui_trees.find( - (candidate) => candidate.src_ui_design === treeId, - ); - if (!tree) return { ok: false, reason: 'missing' }; - const location = findNodeLocation(tree.root, nodeId); - if (!location) return { ok: false, reason: 'missing' }; - const next = cloneState(current); - const nextTree = next.ui_trees.find( - (candidate) => candidate.src_ui_design === treeId, - )!; - const nextNode = findNodeLocation(nextTree.root, nodeId)!.node; - nextNode.component = structuredClone(component); - nextNode.metadata.component_status = 'NoProblem'; - commit(next); + const result = applyUiEditorCommand(stateRef.current, { + type: 'set-node-component', + treeId, + nodeId, + component, + }); + if (!result.ok) return result; + commit(result.state); return { ok: true, value: undefined }; }, [commit, guard], @@ -1162,38 +1116,14 @@ export function useUiEditorState(initialState: State = EMPTY_UI_EDITOR_STATE) { ): UiEditorOperationResult => { const blocked = guard(); if (blocked) return blocked; - const current = stateRef.current; - const tree = current.ui_trees.find( - (candidate) => candidate.src_ui_design === treeId, - ); - if (!tree) return { ok: false, reason: 'missing' }; - if (!findNodeLocation(tree.root, nodeId)) - return { ok: false, reason: 'missing' }; - const next = cloneState(current); - const node = findNodeLocation( - next.ui_trees.find((candidate) => candidate.src_ui_design === treeId)! - .root, + const result = applyUiEditorCommand(stateRef.current, { + type: 'set-node-metadata', + treeId, nodeId, - )!.node; - if ( - patch.component_status !== undefined && - node.component === null && - isProblematicComponentStatus(patch.component_status) - ) { - return { ok: false, reason: 'invalid' }; - } - if (patch.name !== undefined) node.metadata.name = patch.name; - if (patch.description !== undefined) - node.metadata.description = patch.description; - if (patch.layout_status !== undefined) - node.metadata.layout_status = patch.layout_status; - if (patch.component_status !== undefined) - node.metadata.component_status = patch.component_status; - if (patch.allow_llm_edit_layout !== undefined) - node.metadata.allow_llm_edit_layout = patch.allow_llm_edit_layout; - if (patch.allow_llm_edit_component !== undefined) - node.metadata.allow_llm_edit_component = patch.allow_llm_edit_component; - commit(next); + patch, + }); + if (!result.ok) return result; + commit(result.state); return { ok: true, value: undefined }; }, [commit, guard], @@ -1350,9 +1280,6 @@ export function useUiEditorState(initialState: State = EMPTY_UI_EDITOR_STATE) { const next = cloneState(current); delete next.ui_design_images[id]; next.ui_trees = next.ui_trees.filter((tree) => tree.src_ui_design !== id); - for (const image of Object.values(next.ui_design_images)) { - if (image.metadata.slave_to === id) image.metadata.slave_to = null; - } commit(next); return { ok: true, value: impact }; }, @@ -1452,10 +1379,6 @@ export function useUiEditorState(initialState: State = EMPTY_UI_EDITOR_STATE) { isLocked, runWithStateLocked, - setImageName, - setImageDescription, - setImageRole, - setImageSlaveTo, addDesignImages, addSpriteAssets, addFontAssets, @@ -1464,6 +1387,7 @@ export function useUiEditorState(initialState: State = EMPTY_UI_EDITOR_STATE) { setSpriteBorder, insertNode, insertNodeAfter, + setTreeOffset, deleteNode, setNodeTransform, setNodeLayout, diff --git a/apps/ai-game-creator-shell/src/view/project-development/index.tsx b/apps/ai-game-creator-shell/src/view/project-development/index.tsx index 3b03ac6b0..0487d76b7 100644 --- a/apps/ai-game-creator-shell/src/view/project-development/index.tsx +++ b/apps/ai-game-creator-shell/src/view/project-development/index.tsx @@ -278,7 +278,7 @@ import { replaceVersionResource, } from '../../features/resource-canvas/resourceVersionReplacementTransport'; import { useResourceCanvasGenerationPlaceholders } from '../../features/resource-canvas/useResourceCanvasGenerationPlaceholders'; -import { ensureUiDesignResourceForPrototype } from '../../features/ui-editor/uiDesignResourceBridge'; +import { createUiDesignDocFromImages } from '../../features/ui-editor/uiDesignResourceBridge'; import { currentPlatformSessionGeneration, requestPlatformSessionRefresh, @@ -2223,7 +2223,6 @@ export default function ProjectDevelopmentView({ const [uiEditorRoute, setUiEditorRoute] = useState( null, ); - const autoOpenedUiWorkflowResourceRef = useRef(null); const [resourceWorkbenchNotice, setResourceWorkbenchNotice] = useState(''); /** * 打开项目时读盘归并旧分区 / 跳过无法对齐的坐标都是当场写回 sidecar 的副作用， @@ -6415,10 +6414,10 @@ export default function ProjectDevelopmentView({ setUiEditorRoute(null); setResourceWorkbenchNotice('正在准备 UI 编辑资源…'); try { - const result = await ensureUiDesignResourceForPrototype({ + const result = await createUiDesignDocFromImages({ projectPath, - manifest, - prototypeAssetId, + expectedProjectId: manifest.projectId, + images: [{ assetId: prototypeAssetId }], invoke, }); if (canvasOpenEpochRef.current !== openEpoch) return; @@ -6428,26 +6427,18 @@ export default function ProjectDevelopmentView({ ) { throw new Error('UI 编辑资源结果与当前项目不一致'); } - if (result.created) { - onManifestChange?.(projectPath, result.manifest, { - projectId: result.manifest.projectId, - revision: result.committedProjectRevision, - source: 'asset-command', - commitId: `ui-design-bridge:${result.asset.id}`, - }); - } + onManifestChange?.(projectPath, result.manifest, { + projectId: result.manifest.projectId, + revision: result.committedProjectRevision, + source: 'asset-command', + commitId: `ui-design-doc:${result.asset.id}`, + }); setResourceWorkbenchNotice(''); setUiEditorRoute({ resourceId: result.asset.id, resourceLabel: - result.asset.localPath.split(/[\\/]/u).filter(Boolean).pop() ?? + result.relativePath.split(/[\\/]/u).filter(Boolean).pop() ?? resource.label, - ...(result.asset.source.generationKind === 'ui-workflow.completed' - ? { - initialStep: 'asset-separation', - initialFurthestStepIndex: 2, - } - : {}), }); } catch (error) { if (canvasOpenEpochRef.current === openEpoch) { @@ -6491,19 +6482,10 @@ export default function ProjectDevelopmentView({ setUiEditorRoute({ resourceId: resource.manifestAssetId, resourceLabel: resource.label, - ...(manifest.assets.find( - (asset) => asset.id === resource.manifestAssetId, - )?.source.generationKind === 'ui-workflow.completed' - ? { - initialStep: 'asset-separation' as const, - initialFurthestStepIndex: 2, - } - : {}), }); }, [ advanceFocusGeneration, - manifest.assets, openUiDesignEditor, resourceCardPreviews.identityByResourceId, resourceCardPreviews.previews, @@ -6576,35 +6558,6 @@ export default function ProjectDevelopmentView({ resources, ]); - useEffect(() => { - if (uiEditorRoute) return; - const completed = manifest.assets.find( - (asset) => - isGameCreationAppUiDesignDocAsset(asset) && - asset.source.generationKind === 'ui-workflow.completed', - ); - if ( - !completed || - autoOpenedUiWorkflowResourceRef.current === completed.id - ) { - return; - } - autoOpenedUiWorkflowResourceRef.current = completed.id; - canvasOpenEpochRef.current += 1; - advanceFocusGeneration(); - activeFocusFlowIdRef.current = null; - pendingResourceFocusRef.current = null; - setResourceWorkbenchNotice(''); - setUiEditorRoute({ - resourceId: completed.id, - resourceLabel: - completed.localPath.split(/[\\/]/u).filter(Boolean).pop() ?? - 'UI 设计资源', - initialStep: 'asset-separation', - initialFurthestStepIndex: 2, - }); - }, [advanceFocusGeneration, manifest.assets, uiEditorRoute]); - const beginPendingResourceEditAction = useCallback((operationId: string) => { if (pendingResourceEditActionIdsRef.current.has(operationId)) return false; const next = new Set(pendingResourceEditActionIdsRef.current); diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/EditorDialogs.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/EditorDialogs.tsx index a4d637ecb..fad5685ef 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/EditorDialogs.tsx +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/EditorDialogs.tsx @@ -74,7 +74,6 @@ export function EditorDialogs({

  • 删除组件树：{impact?.removedTreeCount ?? 0}
    • -
  • 清空界面归属：{impact?.clearedSlaveToCount ?? 0}
  • 清空图片组件引用：{impact?.clearedTargetGraphicCount ?? 0}
  • 清空文本字体引用：{impact?.clearedFontCount ?? 0}
diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/ImportOverview.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/ImportOverview.tsx deleted file mode 100644 index 0823299bd..000000000 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/ImportOverview.tsx +++ /dev/null @@ -1,69 +0,0 @@ -import type { Node as UiNode } from '../../../features/ui-editor/types/Node'; -import type { SpriteAsset } from '../../../features/ui-editor/types/SpriteAsset'; -import type { UIDesignImage } from '../../../features/ui-editor/types/UIDesignImage'; -import type { UITree } from '../../../features/ui-editor/types/UITree'; - -function countUiComponents(nodes: UiNode[]): number { - return nodes.reduce( - (total, node) => - total + (node.component ? 1 : 0) + countUiComponents(node.children), - 0, - ); -} - -export function ImportOverview({ - images, - sprites, - uiTrees, -}: { - images: Record; - sprites: Record; - uiTrees: UITree[]; -}) { - const componentCount = uiTrees.reduce( - (total, tree) => total + countUiComponents([tree.root]), - 0, - ); - - return ( -
-
-
- - Overview - -

导入概览

-
-
-
-
- - {Object.keys(images).length} - - - 界面图数量 - -
-
- - {Object.keys(sprites).length} - - - 素材数量 - -
-
- - {componentCount} - - - 已有组件 - -
-
-
- ); -} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/InputSidebar.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/InputSidebar.tsx index b473accb2..065780691 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/InputSidebar.tsx +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/InputSidebar.tsx @@ -6,12 +6,17 @@ import { visitUiNodes } from '../../../features/ui-editor/treeUtils'; import type { Node as UiNode } from '../../../features/ui-editor/types/Node'; import type { NodeId } from '../../../features/ui-editor/types/NodeId'; import type { UIDesignImageId } from '../../../features/ui-editor/types/UIDesignImageId'; +import { resourceAssetDisplayName } from '../../project-development/resourceAssetDisplayName'; import type { UiEditorInputProjection } from '../useUiEditorPage'; import { CollapsibleSidebarPanel } from './CollapsibleSidebarPanel'; import { UiTreePanel } from './UiTreePanel'; const SUPER_ROOT_ID = '__ui-editor-super-root__'; +function designImageLabel(path: string, index: number) { + return resourceAssetDisplayName(path) || `界面图 ${index + 1}`; +} + export function InputSidebar({ input }: { input: UiEditorInputProjection }) { const { projectPath, @@ -70,6 +75,7 @@ export function InputSidebar({ input }: { input: UiEditorInputProjection }) { component: null, children_display_mode: 'Stack', children: uiTrees.map((tree) => tree.root), + offset: { min: [0, 0], max: [0, 0] }, }; }, [uiTrees]); @@ -82,9 +88,18 @@ export function InputSidebar({ input }: { input: UiEditorInputProjection }) { focusRequest={focusRequest} treeIdForNode={(nodeId) => treeIdByNodeId.get(nodeId) ?? null} isNodePreviewVisible={input.isNodePreviewVisible} - onSelectNode={(treeId, nodeId) => { - input.selectDesignImage(treeId); - input.selectNode(nodeId); + onSelectNode={(_treeId, nodeId) => { + // react-arborist emits `onSelect` when its controlled `selection` + // prop is updated. Overview navigation updates the selection and + // the status highlight in the same render, so treating that + // programmatic notification as a fresh user selection would clear + // the highlight before it can be painted. Only mutate selection + // state when the target actually differs from the current one. + const sameNode = input.selectedNodeId === nodeId; + if (!sameNode) { + input.selectDesignImage(_treeId); + input.selectNode(nodeId); + } }} onToggleNodeVisibility={(nodeId) => input.toggleNodePreviewVisibility(nodeId) @@ -120,7 +135,7 @@ export function InputSidebar({ input }: { input: UiEditorInputProjection }) { >
{imageOrder.length > 0 ? ( - imageOrder.map((id) => { + imageOrder.map((id, index) => { const image = images[id]; if (!image) return null; return ( @@ -147,10 +162,9 @@ export function InputSidebar({ input }: { input: UiEditorInputProjection }) {
- {image.metadata.name} + {designImageLabel(image.path, index)} - {image.metadata.role ?? '自动判断'} ·{' '} {image.pixel_size[0]} × {image.pixel_size[1]} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/InspectorSidebar.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/InspectorSidebar.tsx index 15e77c8e7..d7005f4fa 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/InspectorSidebar.tsx +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/InspectorSidebar.tsx @@ -12,10 +12,8 @@ import { FontSamplePreview } from '../../../../features/ui-editor/components/Fon import { SpriteImagePreview } from '../../../../features/ui-editor/components/SpriteImagePreview'; import type { StageStatusField } from '../../../../features/ui-editor/stageStatusOverview'; import type { NodeId } from '../../../../features/ui-editor/types/NodeId'; -import type { UIDesignImageId } from '../../../../features/ui-editor/types/UIDesignImageId'; -import type { UIDesignImageRole } from '../../../../features/ui-editor/types/UIDesignImageRole'; import { uiEditorPrivateFontFamily } from '../../../../features/ui-editor/useUiEditorFontFaces'; -import { UI_DESIGN_IMAGE_ROLES } from '../../model'; +import { resourceAssetDisplayName } from '../../../project-development/resourceAssetDisplayName'; import type { UiEditorInspectorProjection } from '../../useUiEditorPage'; import { ComponentPanel } from './Components/ComponentPanel'; import { @@ -64,7 +62,6 @@ type InspectorView = kind: 'image'; image: ActiveImage; imageId: ActiveImageId; - pageOptions: UiEditorInspectorProjection['pageOptions']; } | { kind: 'empty' }; @@ -155,11 +152,6 @@ export function InspectorSidebar({ inspector.requestDesignImageRemoval(view.imageId)} deleteDisabled={inspector.isLocked} /> @@ -226,7 +218,6 @@ function getInspectorView( spriteReferenceCounts, fontReferenceCounts, fontFaces, - pageOptions, } = inspector; if (selectedNode) { @@ -263,7 +254,6 @@ function getInspectorView( kind: 'image', image: activeImage, imageId: activeImageId, - pageOptions, }; } @@ -284,7 +274,7 @@ function NodeInspector({ onMetadataChange, highlightedStatusField, onTransformChange, - onLayoutChange, + // onLayoutChange, sprites, previewUrls, fonts, @@ -483,11 +473,11 @@ function NodeInspector({ readOnly={transformReadOnly || isReadOnly} onChange={onTransformChange} /> - + {/**/} { - if (!highlight) return; - statusRowRef.current?.scrollIntoView({ + const statusRow = statusRowRef.current; + if (!highlight || !statusRow) return; + statusRow.scrollIntoView({ block: 'nearest', behavior: 'smooth', }); + + // 强制制造一次样式边界，避免 A → B → A 时浏览器复用已完成的动画。 + statusRow.classList.remove('ui-editor-status-attention'); + void statusRow.offsetWidth; + statusRow.classList.add('ui-editor-status-attention'); + + // 多节点切换会复用 Inspector 树，显式重启动画，确保回到已查看节点时 + // 仍能再次播放提示，而不是依赖 class/key 的重协调行为。 + if (typeof statusRow.getAnimations === 'function') { + for (const animation of statusRow.getAnimations()) { + const animationName = (animation as CSSAnimation).animationName; + if (!animationName?.startsWith('ui-editor-status-attention')) continue; + animation.cancel(); + animation.play(); + } + } }, [highlight]); return ( @@ -1016,21 +1024,11 @@ function InspectorReadout({ label, value }: { label: string; value: string }) { function ImageInspector({ image, imageId, - pageOptions, - onNameChange, - onDescriptionChange, - onRoleChange, - onSlaveToChange, onDelete, deleteDisabled, }: { image: ActiveImage; imageId: ActiveImageId; - pageOptions: UiEditorInspectorProjection['pageOptions']; - onNameChange: UiEditorInspectorProjection['setImageName']; - onDescriptionChange: UiEditorInspectorProjection['setImageDescription']; - onRoleChange: UiEditorInspectorProjection['setImageRole']; - onSlaveToChange: UiEditorInspectorProjection['setImageSlaveTo']; onDelete: () => void; deleteDisabled: boolean; }) { @@ -1038,65 +1036,13 @@ function ImageInspector({ return (
- { - if (!readOnly) onNameChange(event.target.value); - }} - /> - { - if (!readOnly) onDescriptionChange(event.target.value); - }} - /> +
+ {resourceAssetDisplayName(image.path)} +
- { - if (!readOnly) { - onRoleChange( - (event.target.value || null) as UIDesignImageRole | null, - ); - } - }} - > - - {UI_DESIGN_IMAGE_ROLES.map((role) => ( - - ))} - - {image.metadata.role !== 'Page' || image.metadata.slave_to !== null ? ( - { - if (!readOnly) { - onSlaveToChange( - (event.target.value || null) as UIDesignImageId | null, - ); - } - }} - > - - {pageOptions - .filter(([id]) => id !== imageId) - .map(([id, page]) => ( - - ))} - - ) : null} {UI_EDITOR_STEPS.map((step, index) => { diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorCopyPathButton.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorCopyPathButton.tsx new file mode 100644 index 000000000..ea19e48bf --- /dev/null +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorCopyPathButton.tsx @@ -0,0 +1,43 @@ +import { writeText } from '@tauri-apps/plugin-clipboard-manager'; +import { Copy } from 'lucide-react'; +import { useEffect, useState } from 'react'; + +export function UiEditorCopyPathButton({ + relativePath, +}: { + relativePath: string; +}) { + const [copyState, setCopyState] = useState<'idle' | 'copied' | 'failed'>( + 'idle', + ); + + useEffect(() => setCopyState('idle'), [relativePath]); + + async function copyPath() { + setCopyState('idle'); + try { + await writeText(relativePath); + setCopyState('copied'); + } catch { + setCopyState('failed'); + } + } + + return ( + <> + {copyState === 'failed' ? ( +

+ 复制失败，请手动复制路径。 +

+ ) : null} + + + ); +} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorSaveResultModal.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorSaveResultModal.tsx new file mode 100644 index 000000000..053b97662 --- /dev/null +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorSaveResultModal.tsx @@ -0,0 +1,154 @@ +import { ThemedModal } from '../../../components/modal/ThemedModal'; +import { UiEditorCopyPathButton } from './UiEditorCopyPathButton'; + +export type UiEditorSaveResultNotice = + | { + kind: 'saved'; + } + | { + kind: 'generated'; + relativePath: string; + } + | { + kind: 'failure'; + message: string; + retryLabel?: string; + onRetry?: () => void; + }; + +export function UiEditorSaveResultModal({ + notice, + onClose, +}: { + notice: UiEditorSaveResultNotice | null; + onClose: () => void; +}) { + return ( + + {renderNoticeContent(notice, onClose)} + + ); +} + +function renderNoticeContent( + notice: UiEditorSaveResultNotice | null, + onClose: () => void, +) { + if (!notice) return null; + if (notice.kind === 'generated') { + return ( + + ); + } + if (notice.kind === 'saved') { + return ; + } + return ; +} + +function GeneratedNotice({ + relativePath, + onClose, +}: { + relativePath: string; + onClose: () => void; +}) { + return ( + <> +

代码已生成

+

生成文件路径

+ + {relativePath} + +
+ +
+ + + ); +} + +function SimpleNotice({ + title, + onClose, +}: { + title: string; + onClose: () => void; +}) { + return ( + <> +

{title}

+ + + ); +} + +function FailureNotice({ + notice, + onClose, +}: { + notice: Extract; + onClose: () => void; +}) { + return ( + <> +

操作失败

+

+ {notice.message} +

+ + + ); +} + +function NoticeFooter({ + onClose, + onRetry, + retryLabel = '重试', +}: { + onClose: () => void; + onRetry?: () => void; + retryLabel?: string; +}) { + return ( +
+ {onRetry ? ( + + ) : null} + +
+ ); +} + +function ariaLabelForNotice(notice: UiEditorSaveResultNotice | null) { + if (notice?.kind === 'generated') return '代码已生成'; + if (notice?.kind === 'saved') return '保存成功'; + if (notice?.kind === 'failure') return '操作失败'; + return '保存结果'; +} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/WorkflowActionCard.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/WorkflowActionCard.tsx index 7c392369b..24d61f8e6 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/WorkflowActionCard.tsx +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/WorkflowActionCard.tsx @@ -8,17 +8,14 @@ export function WorkflowActionCard({ }) { const action = getStepAction(workflow); const running = - (workflow.activeStep === 'reference-analysis' && workflow.isSuggesting) || (workflow.activeStep === 'structure-recognition' && workflow.isRecognizing) || (workflow.activeStep === 'asset-separation' && workflow.isSeparating); const status = { - 'reference-analysis': workflow.suggestionStatus, 'structure-recognition': workflow.recognitionStatus, 'asset-separation': workflow.separationStatus, }[workflow.activeStep]; const hasRun = { - 'reference-analysis': workflow.hasSuggested, 'structure-recognition': workflow.hasRecognized, 'asset-separation': workflow.hasSeparated, }[workflow.activeStep]; @@ -100,13 +97,6 @@ export function WorkflowActionCard({ } function getStepAction(workflow: UiEditorWorkflowProjection) { - if (workflow.activeStep === 'reference-analysis') { - return { - label: '分析参考图', - runningLabel: '分析中…', - action: workflow.suggestUiDesignSemantics, - }; - } if (workflow.activeStep === 'structure-recognition') { return { label: '识别界面结构', diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/WorkflowChecks.ts b/apps/ai-game-creator-shell/src/view/ui-editor/components/WorkflowChecks.ts index 5df5d0d9b..4a0431922 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/WorkflowChecks.ts +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/WorkflowChecks.ts @@ -3,7 +3,6 @@ import { validateAssetSeparationPrerequisites, validateAssetSeparationResult, validateComponentRecognitionPrerequisites, - validateReferenceAnalysisResult, validateStructureRecognitionResult, } from '../../../features/ui-editor/requisites'; import type { State } from '../../../features/ui-editor/types/State'; @@ -16,8 +15,6 @@ export function prerequisiteIssuesForStep( step: UiEditorStepId, ): UiEditorPrerequisiteIssue[] { switch (step) { - case 'reference-analysis': - return []; case 'structure-recognition': return validateComponentRecognitionPrerequisites(state); case 'asset-separation': @@ -30,8 +27,6 @@ export function postCheckIssuesForStep( step: UiEditorStepId, ): UiEditorPrerequisiteIssue[] { switch (step) { - case 'reference-analysis': - return validateReferenceAnalysisResult(state); case 'structure-recognition': return validateStructureRecognitionResult(state); case 'asset-separation': @@ -43,7 +38,6 @@ export function postCheckIssuesForSave( state: State, ): UiEditorPrerequisiteIssue[] { return [ - ...validateReferenceAnalysisResult(state), ...validateStructureRecognitionResult(state), ...validateAssetSeparationResult(state), ]; @@ -54,8 +48,6 @@ export function activeStepPrerequisiteIssues( step: UiEditorStepId, ): UiEditorPrerequisiteIssue[] { switch (step) { - case 'reference-analysis': - return validateComponentRecognitionPrerequisites(state); case 'structure-recognition': return validateAssetSeparationPrerequisites(state); case 'asset-separation': diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/PreviewWorkspace.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/PreviewWorkspace.tsx index 26203c35a..04150de7a 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/PreviewWorkspace.tsx +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/PreviewWorkspace.tsx @@ -1,4 +1,5 @@ import { + CANVAS_WORLD_SIZE, CANVAS_ZOOM_IN_FACTOR, CANVAS_ZOOM_OUT_FACTOR, canvasDisplayScaleToViewportScale, @@ -30,26 +31,107 @@ import { import { findNodePageContext } from '../../../../features/ui-editor/nodeTransformGeometry'; import type { Node } from '../../../../features/ui-editor/types/Node'; import type { NodeId } from '../../../../features/ui-editor/types/NodeId'; +import { resourceAssetDisplayName } from '../../../project-development/resourceAssetDisplayName'; import type { UiEditorCanvasProjection } from '../../useUiEditorPage'; import { UiNodeContextMenu } from '../UiNodeContextMenu'; +import { resolvePreviewGridStep } from './previewGrid'; +import { + createPreviewRightPanGesture, + movePreviewRightPanGesture, + type PreviewRightPanGesture, + resolvePreviewRightPanRelease, + shouldInterceptRightContextMenu, +} from './previewRightPanGesture'; import { handlePreviewZoomKeyDown, isPreviewZoomInteractiveTarget, previewZoomUsesMetaModifier, } from './previewZoomKeyboard'; -import { type UiEditorRenderMode, UiTreeRenderer } from './UiTreeRenderer'; +import { UiTreeRenderer } from './UiTreeRenderer'; import { useNodeTransformInteraction } from './useNodeTransformInteraction'; +/** 画布初始适配比例；调小可为浮动面板预留更多可视空间。 */ +export const UI_EDITOR_FIT_DEGREE = 0.7; + +function releasePointerCapture(element: Element, pointerId: number) { + if (element.hasPointerCapture(pointerId)) { + element.releasePointerCapture(pointerId); + } +} + +function isClientPointInsideElement( + element: Element | null, + clientX: number, + clientY: number, +) { + if (!element) return false; + const rect = element.getBoundingClientRect(); + return ( + clientX >= rect.left && + clientX <= rect.right && + clientY >= rect.top && + clientY <= rect.bottom + ); +} + +/** 右键抬起时命中的节点与它所属的树，用于打开节点菜单。 */ +function resolveRightClickMenuTarget(target: EventTarget | null) { + const element = target instanceof Element ? target : null; + const nodeId = element + ?.closest('[data-node-id]') + ?.getAttribute('data-node-id'); + const treeId = element + ?.closest('[data-tree-id]') + ?.getAttribute('data-tree-id'); + if (!nodeId || !treeId) return null; + return { nodeId, treeId }; +} + +function fitEditorViewport( + bounds: { x: number; y: number; width: number; height: number }, + canvasSize: { width: number; height: number }, +): CanvasViewport { + const fit = fitViewportToBounds({ bounds, canvasSize }); + const scale = fit.scale * UI_EDITOR_FIT_DEGREE; + return { + scale, + x: canvasSize.width / 2 - (bounds.x + bounds.width / 2) * scale, + y: canvasSize.height / 2 - (bounds.y + bounds.height / 2) * scale, + }; +} + export function PreviewWorkspace({ canvas, + showFrame, + showOriginImage, + showComponent, }: { canvas: UiEditorCanvasProjection; + showFrame: boolean; + showOriginImage: boolean; + showComponent: boolean; }) { - const { activeImage, activeImageId, previewUrls } = canvas; + const { previewUrls, uiTrees, images } = canvas; const viewportElementRef = useRef(null); const viewportRef = useRef({ x: 0, y: 0, scale: 0.5 }); const handledFocusRequestIdRef = useRef(null); + const didInitialFitRef = useRef(false); const panRef = useRef | null>(null); + const rightPanRef = useRef(null); + // 右键按下时的命中元素：指针被视口捕获后，pointerup 的 target 会变成捕获元素， + // 必须在按下时把真正的节点/树目标记下来。 + const rightPanTargetRef = useRef(null); + const rightPressSequenceRef = useRef(false); + const treeDragRef = useRef<{ + treeId: string; + pointerId: number; + startX: number; + startY: number; + origin: [number, number]; + } | null>(null); + const [previewTreeOffsets, setPreviewTreeOffsets] = useState< + ReadonlyMap + >(new Map()); const previewFocusedRef = useRef(false); const previewHoveredRef = useRef(false); const [viewport, setViewportState] = useState( @@ -58,19 +140,17 @@ export function PreviewWorkspace({ const [canvasSize, setCanvasSize] = useState({ width: 900, height: 640 }); const canvasSizeRef = useRef(canvasSize); const [spaceHeld, setSpaceHeld] = useState(false); - const [renderMode, setRenderMode] = - useState('editor-overlay'); - const [showFrame, setShowFrame] = useState(false); + const [isPanning, setIsPanning] = useState(false); const [previewTransforms, setPreviewTransforms] = useState< ReadonlyMap >(new Map()); const [contextMenu, setContextMenu] = useState<{ nodeId: NodeId; + treeId: string; x: number; y: number; isPageRoot: boolean; } | null>(null); - const tree = canvas.tree ?? null; const updatePreviewTransform = useCallback( (nodeId: NodeId, transform: Node['layout']['transform'] | null) => { setPreviewTransforms((current) => { @@ -84,41 +164,62 @@ export function PreviewWorkspace({ }, [], ); - useEffect(() => { - setPreviewTransforms(new Map()); - }, [activeImageId]); - const activeImagePixelWidth = activeImage?.pixel_size[0]; - const activeImagePixelHeight = activeImage?.pixel_size[1]; - const activeImagePixelsPerUnit = activeImage?.pixels_per_unit; - const logicalSize = useMemo(() => { - if ( - activeImagePixelWidth === undefined || - activeImagePixelHeight === undefined || - activeImagePixelsPerUnit === undefined - ) { - return null; - } - const ppu = activeImagePixelsPerUnit; - if (!Number.isFinite(ppu) || ppu <= 0) return null; - const width = activeImagePixelWidth / ppu; - const height = activeImagePixelHeight / ppu; - if ( - !Number.isFinite(width) || - !Number.isFinite(height) || - width <= 0 || - height <= 0 - ) { - return null; - } - return { width, height }; - }, [activeImagePixelHeight, activeImagePixelsPerUnit, activeImagePixelWidth]); + const treeLayouts = useMemo( + () => + uiTrees.map((item) => { + const image = images[item.src_ui_design]; + const ppu = image?.pixels_per_unit ?? 0; + const width = + image && Number.isFinite(ppu) && ppu > 0 + ? image.pixel_size[0] / ppu + : 0; + const height = + image && Number.isFinite(ppu) && ppu > 0 + ? image.pixel_size[1] / ppu + : 0; + return { + tree: item, + image, + width, + height, + validOffset: + item.root.offset?.min?.every((value) => Number.isFinite(value)) ?? + false, + }; + }), + [images, uiTrees], + ); + const allBounds = useMemo(() => { + const valid = treeLayouts.filter( + (item) => item.validOffset && item.width > 0 && item.height > 0, + ); + if (valid.length === 0) return null; + const minX = Math.min(...valid.map(({ tree }) => tree.root.offset.min[0])); + const minY = Math.min(...valid.map(({ tree }) => tree.root.offset.min[1])); + const maxX = Math.max( + ...valid.map(({ tree, width }) => tree.root.offset.min[0] + width), + ); + const maxY = Math.max( + ...valid.map(({ tree, height }) => tree.root.offset.min[1] + height), + ); + return { x: minX, y: minY, width: maxX - minX, height: maxY - minY }; + }, [treeLayouts]); + const logicalSizes = useMemo( + () => + new Map( + treeLayouts.map( + ({ tree: item, width, height }) => + [item.src_ui_design, { width, height }] as const, + ), + ), + [treeLayouts], + ); const nodeInteractions = useNodeTransformInteraction({ - activeImageId, canvas, - logicalSize, + trees: uiTrees, + logicalSizes, spaceHeld, - tree, keepChildrenUnchanged: canvas.keepChildrenUnchanged, viewportRef, onPreviewTransform: updatePreviewTransform, @@ -143,28 +244,27 @@ export function PreviewWorkspace({ }, []); const fitToCanvas = useCallback(() => { - if (!logicalSize) return; + if (!allBounds) return; const element = viewportElementRef.current; setViewport( - fitViewportToBounds({ - bounds: { - x: 0, - y: 0, - width: logicalSize.width, - height: logicalSize.height, - }, - canvasSize: { - width: element?.clientWidth || canvasSizeRef.current.width, - height: element?.clientHeight || canvasSizeRef.current.height, - }, + fitEditorViewport(allBounds, { + width: element?.clientWidth || canvasSizeRef.current.width, + height: element?.clientHeight || canvasSizeRef.current.height, }), ); - }, [logicalSize, setViewport]); + }, [allBounds, setViewport]); useEffect(() => { - if (!activeImageId || !logicalSize) return; - fitToCanvas(); - }, [activeImageId, fitToCanvas, logicalSize]); + if (!allBounds) return; + if (didInitialFitRef.current) return; + didInitialFitRef.current = true; + const element = viewportElementRef.current; + const canvasSize = { + width: element?.clientWidth || canvasSizeRef.current.width, + height: element?.clientHeight || canvasSizeRef.current.height, + }; + setViewport(fitEditorViewport(allBounds, canvasSize)); + }, [allBounds, setViewport]); const scaleViewportFromCenter = useCallback( (nextScale: number) => { @@ -195,6 +295,7 @@ export function PreviewWorkspace({ }, [scaleViewportFromCenter]); const displayPercent = formatCanvasDisplayScalePercent(viewport.scale); + const previewGridStep = resolvePreviewGridStep(viewport.scale); const zoomToDisplayScale = useCallback( (displayScale: number) => { @@ -222,15 +323,12 @@ export function PreviewWorkspace({ useEffect(() => { const request = canvas.focusRequest; - if ( - !request || - request.requestId === handledFocusRequestIdRef.current || - request.treeId !== activeImageId || - !tree || - !logicalSize - ) { + if (!request || request.requestId === handledFocusRequestIdRef.current) { return; } + const tree = uiTrees.find((item) => item.src_ui_design === request.treeId); + const logicalSize = logicalSizes.get(request.treeId); + if (!tree || !logicalSize) return; const context = findNodePageContext(tree.root, request.nodeId, { min: [0, 0], max: [logicalSize.width, logicalSize.height], @@ -243,24 +341,23 @@ export function PreviewWorkspace({ }; handledFocusRequestIdRef.current = request.requestId; setViewport( - fitViewportToBounds({ - bounds: { + fitEditorViewport( + { x: context.rect.min[0], y: context.rect.min[1], width: context.rect.max[0] - context.rect.min[0], height: context.rect.max[1] - context.rect.min[1], }, - canvasSize: size, - }), + size, + ), ); }, [ - activeImageId, canvasSize.height, canvasSize.width, canvas.focusRequest, - logicalSize, + logicalSizes, setViewport, - tree, + uiTrees, ]); useEffect(() => { @@ -287,7 +384,7 @@ export function PreviewWorkspace({ handlePreviewZoomKeyDown( event, { - hasZoomableViewport: logicalSize !== null, + hasZoomableViewport: allBounds !== null, isFocused: previewFocusedRef.current, isHovered: previewHoveredRef.current, usesMetaModifier, @@ -302,7 +399,23 @@ export function PreviewWorkspace({ const onKeyUp = (event: KeyboardEvent) => { if (event.code === 'Space') setSpaceHeld(false); }; - const onWindowBlur = () => setSpaceHeld(false); + const onWindowBlur = () => { + setSpaceHeld(false); + rightPressSequenceRef.current = false; + rightPanRef.current = null; + setIsPanning(false); + // 失焦时浏览器不一定补 pointercancel：丢掉未提交的树拖拽，避免后续指针事件 + // 复用陈旧手势把意外偏移写进文档。 + const drag = treeDragRef.current; + if (drag) { + treeDragRef.current = null; + setPreviewTreeOffsets((current) => { + const next = new Map(current); + next.delete(drag.treeId); + return next; + }); + } + }; window.addEventListener('keydown', onKeyDown); window.addEventListener('keyup', onKeyUp); window.addEventListener('blur', onWindowBlur); @@ -311,15 +424,33 @@ export function PreviewWorkspace({ window.removeEventListener('keyup', onKeyUp); window.removeEventListener('blur', onWindowBlur); }; - }, [logicalSize, resetToActualSize, zoomIn, zoomOut]); + }, [allBounds, resetToActualSize, zoomIn, zoomOut]); const handlePointerDown = (event: ReactPointerEvent) => { + // 右键 contextmenu 的拦截窗口要覆盖"按下到下一次按下"这段： + // Windows / Linux 在按下时触发，macOS 在抬起之后触发。 + rightPressSequenceRef.current = event.button === 2; + if (event.button === 2) { + // 只接"单按右键"的干净起手，避免和左键拖动/框选互相抢指针捕获。 + if (event.buttons !== 2 || rightPanRef.current !== null) return; + event.preventDefault(); + event.currentTarget.focus({ preventScroll: true }); + event.currentTarget.setPointerCapture(event.pointerId); + rightPanTargetRef.current = event.target; + rightPanRef.current = createPreviewRightPanGesture({ + pointerId: event.pointerId, + pointer: { x: event.clientX, y: event.clientY }, + viewport: viewportRef.current, + }); + return; + } if (event.button === 0 && !isPreviewZoomInteractiveTarget(event.target)) { event.currentTarget.focus({ preventScroll: true }); } if (event.button === 1 || (event.button === 0 && spaceHeld)) { event.preventDefault(); event.currentTarget.setPointerCapture(event.pointerId); + setIsPanning(true); panRef.current = createPanDragState({ pointerId: event.pointerId, pointer: { x: event.clientX, y: event.clientY }, @@ -333,6 +464,18 @@ export function PreviewWorkspace({ }; const handlePointerMove = (event: ReactPointerEvent) => { + const rightPan = rightPanRef.current; + if (rightPan && rightPan.pointerId === event.pointerId) { + const pointer = { x: event.clientX, y: event.clientY }; + const nextPan = movePreviewRightPanGesture(rightPan, pointer); + if (nextPan !== rightPan) { + rightPanRef.current = nextPan; + setIsPanning(true); + } + if (nextPan.panning) + setViewport(moveViewportFromPan(nextPan.pan, pointer)); + return; + } const drag = panRef.current; if (!drag || drag.pointerId !== event.pointerId) return; setViewport( @@ -340,12 +483,135 @@ export function PreviewWorkspace({ ); }; + const openNodeContextMenuAt = ( + event: ReactPointerEvent, + pressedTarget: EventTarget | null, + ) => { + const target = resolveRightClickMenuTarget(pressedTarget); + if (!target) return; + const layout = treeLayouts.find( + (item) => item.tree.src_ui_design === target.treeId, + ); + if (!layout) return; + canvas.selectNode(target.nodeId); + setContextMenu({ + nodeId: target.nodeId, + treeId: target.treeId, + x: event.clientX, + y: event.clientY, + isPageRoot: layout.tree.root.id === target.nodeId, + }); + }; + const handlePointerUp = (event: ReactPointerEvent) => { + const rightPan = rightPanRef.current; + if (rightPan && rightPan.pointerId === event.pointerId) { + rightPanRef.current = null; + setIsPanning(false); + releasePointerCapture(event.currentTarget, event.pointerId); + const release = resolvePreviewRightPanRelease({ + gesture: rightPan, + pointer: { x: event.clientX, y: event.clientY }, + isInsidePreview: isClientPointInsideElement( + viewportElementRef.current, + event.clientX, + event.clientY, + ), + }); + if (release.viewport) setViewport(release.viewport); + const pressedTarget = rightPanTargetRef.current; + rightPanTargetRef.current = null; + if (release.openNodeMenu) openNodeContextMenuAt(event, pressedTarget); + return; + } if (panRef.current?.pointerId !== event.pointerId) return; panRef.current = null; - if (event.currentTarget.hasPointerCapture(event.pointerId)) { - event.currentTarget.releasePointerCapture(event.pointerId); + setIsPanning(false); + releasePointerCapture(event.currentTarget, event.pointerId); + }; + + const handlePointerCancel = (event: ReactPointerEvent) => { + const rightPan = rightPanRef.current; + const pan = panRef.current; + const cancelsRightPan = + rightPan !== null && rightPan.pointerId === event.pointerId; + const cancelsPan = pan !== null && pan.pointerId === event.pointerId; + if (cancelsRightPan) { + rightPanRef.current = null; + rightPanTargetRef.current = null; } + if (cancelsPan) panRef.current = null; + if (cancelsRightPan || cancelsPan) { + setIsPanning(false); + releasePointerCapture(event.currentTarget, event.pointerId); + } + }; + + const handleTreePointerDown = ( + event: ReactPointerEvent, + treeId: string, + rootId: string, + origin: [number, number], + ) => { + if (event.button !== 0) return; + const hit = (event.target as Element).closest('[data-node-id]'); + if (!hit || hit.getAttribute('data-node-id') !== rootId) return; + event.stopPropagation(); + event.currentTarget.setPointerCapture(event.pointerId); + treeDragRef.current = { + treeId, + pointerId: event.pointerId, + startX: event.clientX, + startY: event.clientY, + origin, + }; + }; + const handleTreePointerMove = (event: ReactPointerEvent) => { + const drag = treeDragRef.current; + if (!drag || drag.pointerId !== event.pointerId) return; + const next: [number, number] = [ + drag.origin[0] + + (event.clientX - drag.startX) / viewportRef.current.scale, + drag.origin[1] + + (event.clientY - drag.startY) / viewportRef.current.scale, + ]; + setPreviewTreeOffsets((current) => new Map(current).set(drag.treeId, next)); + }; + const handleTreePointerUp = (event: ReactPointerEvent) => { + if (treeDragRef.current?.pointerId !== event.pointerId) return; + const drag = treeDragRef.current; + if (drag) { + const next: [number, number] = [ + drag.origin[0] + + (event.clientX - drag.startX) / viewportRef.current.scale, + drag.origin[1] + + (event.clientY - drag.startY) / viewportRef.current.scale, + ]; + canvas.setTreeOffset(drag.treeId, next); + setPreviewTreeOffsets((current) => { + const result = new Map(current); + result.delete(drag.treeId); + return result; + }); + } + treeDragRef.current = null; + if (event.currentTarget.hasPointerCapture(event.pointerId)) + event.currentTarget.releasePointerCapture(event.pointerId); + }; + + /** 浏览器发起的指针取消不是正常抬起：只清拖拽状态与捕获，不写回树偏移。 */ + const handleTreePointerCancel = ( + event: ReactPointerEvent, + ) => { + const drag = treeDragRef.current; + if (!drag || drag.pointerId !== event.pointerId) return; + treeDragRef.current = null; + setPreviewTreeOffsets((current) => { + const next = new Map(current); + next.delete(drag.treeId); + return next; + }); + releasePointerCapture(event.currentTarget, event.pointerId); }; const handleWheel = (event: React.WheelEvent) => { @@ -369,61 +635,32 @@ export function PreviewWorkspace({ const handleNodeContextMenu = ( event: ReactMouseEvent, - node: NonNullable['root'], + node: Node, isPageRoot: boolean, + treeId?: string, ) => { + if (!treeId) return; setContextMenu({ nodeId: node.id, + treeId, x: event.clientX, y: event.clientY, isPageRoot, }); }; - useEffect(() => { - if (renderMode !== 'editor-overlay') setContextMenu(null); - }, [renderMode]); - return ( -
- {activeImage && - logicalSize && - (renderMode === 'final-preview' || previewUrls[activeImageId ?? '']) ? ( +
+ {treeLayouts.length > 0 && allBounds ? (
-
- {renderMode === 'final-preview' ? ( - - ) : null} -
- - -
-
{ + if ( + !shouldInterceptRightContextMenu({ + button: event.button, + withinRightPressSequence: rightPressSequenceRef.current, + }) + ) { + return; + } + event.preventDefault(); + event.stopPropagation(); + }} onWheel={handleWheel} + onDragStart={(event) => event.preventDefault()} onClick={(event) => { if (!(event.target as Element).closest('[data-node-id]')) { canvas.clearNodeSelection(); } }} > - -
- {renderMode === 'editor-overlay' ? ( - {activeImage.metadata.name} - ) : ( -
- )} - -
+ + {treeLayouts + .filter((item) => item.validOffset) + .map(({ tree: item, image, width, height }) => { + const offset = + previewTreeOffsets.get(item.src_ui_design) ?? + item.root.offset.min; + return ( +
+ handleTreePointerDown( + event, + item.src_ui_design, + item.root.id, + offset, + ) + } + onPointerMove={handleTreePointerMove} + onPointerUp={handleTreePointerUp} + onPointerCancel={handleTreePointerCancel} + > + {showOriginImage && previewUrls[item.src_ui_design] ? ( + { + ) : null} + +
+ ); + })} {contextMenu ? ( @@ -512,13 +779,19 @@ export function PreviewWorkspace({ isPageRoot={contextMenu.isPageRoot} disabled={canvas.isLocked} onClose={() => setContextMenu(null)} - onInsertChild={(nodeId) => canvas.insertNode(nodeId)} - onInsertSibling={(nodeId) => canvas.insertNodeAfter(nodeId)} - onDelete={(nodeId) => canvas.deleteNode(nodeId)} + onInsertChild={(nodeId) => + canvas.insertNode(nodeId, contextMenu.treeId) + } + onInsertSibling={(nodeId) => + canvas.insertNodeAfter(nodeId, contextMenu.treeId) + } + onDelete={(nodeId) => + canvas.deleteNode(nodeId, contextMenu.treeId) + } /> ) : null}
{ if ( event.target instanceof Element && @@ -527,6 +800,7 @@ export function PreviewWorkspace({ event.preventDefault(); } }} + onDragStart={(event) => event.preventDefault()} >
)} -
- {canvas.status ? ( - - {canvas.status} - - ) : ( - - )} - -
); } diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/UiTreeRenderer.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/UiTreeRenderer.tsx index c4ca88a09..f92a19aad 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/UiTreeRenderer.tsx +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/UiTreeRenderer.tsx @@ -20,17 +20,17 @@ import { resolveExclusiveVisibleChildId } from './exclusiveVisibility'; export type { ResizeHandle } from '../../../../features/ui-editor/nodeTransformGeometry'; -export type UiEditorRenderMode = 'editor-overlay' | 'final-preview'; - type NodePointerDown = ( event: ReactPointerEvent, node: UiNode, + treeId?: string, ) => void; type UiTreeRendererProps = { tree: UITree | null; - renderMode: UiEditorRenderMode; + treeId?: string; showFrame: boolean; + showComponent: boolean; hiddenNodeIds: ReadonlySet; previewTransforms?: ReadonlyMap; selectedNodeId: NodeId | null; @@ -41,6 +41,7 @@ type UiTreeRendererProps = { event: ReactMouseEvent, node: UiNode, isPageRoot: boolean, + treeId?: string, ) => void; onNodePointerDown: NodePointerDown; onNodePointerMove: (event: ReactPointerEvent) => void; @@ -50,6 +51,7 @@ type UiTreeRendererProps = { event: ReactPointerEvent, node: UiNode, handle: ResizeHandle, + treeId?: string, ) => void; onNodeResizePointerMove: (event: ReactPointerEvent) => void; onNodeResizePointerUp: (event: ReactPointerEvent) => void; @@ -81,10 +83,11 @@ const EMPTY_PREVIEW_TRANSFORMS: ReadonlyMap< function RenderNode({ node, + treeId, isRoot, parentContainer, - renderMode, showFrame, + showComponent, hiddenNodeIds, previewTransforms, selectedNodeId, @@ -124,8 +127,8 @@ function RenderNode({ return null; } - const isEditorOverlay = renderMode === 'editor-overlay'; - const isFrameVisible = isEditorOverlay || showFrame; + const isSelected = selectedNodeId === node.id; + const isFrameVisible = showFrame || isSelected; const receivesPointerGesture = parentContainer === undefined; const hasDirectPointerGesture = receivesPointerGesture && !isRoot; const exclusiveVisibleChildId = @@ -170,15 +173,14 @@ function RenderNode({ } } onContextMenu={(event) => { - if (!isEditorOverlay) return; event.preventDefault(); event.stopPropagation(); onSelectNode(node.id); - onNodeContextMenu(event, node, Boolean(isRoot)); + onNodeContextMenu(event, node, Boolean(isRoot), treeId); }} onPointerDown={ receivesPointerGesture - ? (event) => onNodePointerDown(event, node) + ? (event) => onNodePointerDown(event, node, treeId) : undefined } onPointerMove={receivesPointerGesture ? onNodePointerMove : undefined} @@ -191,10 +193,10 @@ function RenderNode({ {node.metadata.name} ) : null} - {node.component ? ( + {showComponent && node.component ? ( ) : null} - {renderMode === 'final-preview' && selectedNodeId === node.id ? ( + {isSelected ? ( nodeId === exclusiveVisibleChildId} @@ -207,13 +209,14 @@ function RenderNode({ - onNodeResizePointerDown(event, node, handle.id) + onNodeResizePointerDown(event, node, handle.id, treeId) } onPointerMove={onNodeResizePointerMove} onPointerUp={onNodeResizePointerUp} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewDragThreshold.ts b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewDragThreshold.ts new file mode 100644 index 000000000..a38a6f469 --- /dev/null +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewDragThreshold.ts @@ -0,0 +1,21 @@ +/** 屏幕像素坐标点。 */ +export type ScreenPoint = { + x: number; + y: number; +}; + +/** + * 指针拖动阈值（屏幕像素）。左键拖动/缩放与右键拖拽平移共用同一判据， + * 保证同一张画布上"多小的移动算点击"只有一个答案。 + */ +export const DRAG_THRESHOLD_SCREEN_PX = 2; + +export function passedDragThresholdScreen( + start: ScreenPoint, + current: ScreenPoint, +): boolean { + return ( + Math.hypot(current.x - start.x, current.y - start.y) >= + DRAG_THRESHOLD_SCREEN_PX + ); +} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewGrid.ts b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewGrid.ts new file mode 100644 index 000000000..db64a13e3 --- /dev/null +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewGrid.ts @@ -0,0 +1,31 @@ +/** 背景网格的基础世界步长；缩放时按 2 倍档位调整屏幕密度。 */ +export const PREVIEW_GRID_BASE_STEP = 28; +const PREVIEW_GRID_MIN_SCREEN_SPACING = 20; +const PREVIEW_GRID_MAX_SCREEN_SPACING = 40; + +/** + * 选择一个离散的世界步长，让网格圆点在屏幕上保持可读密度。 + * 背景位置仍使用 viewport 的屏幕平移量，因此切档不会破坏世界原点对齐。 + */ +export function resolvePreviewGridStep(viewportScale: number): number { + if (!Number.isFinite(viewportScale) || viewportScale <= 0) { + return PREVIEW_GRID_BASE_STEP; + } + + let step = PREVIEW_GRID_BASE_STEP; + let screenSpacing = step * viewportScale; + // 极大缩放下 step * scale 会溢出成 Infinity，而 Infinity / 2 仍是 Infinity： + // 下面两个 while 会因此永不收敛，这里先退回基础步长。 + if (!Number.isFinite(screenSpacing)) { + return PREVIEW_GRID_BASE_STEP; + } + while (screenSpacing < PREVIEW_GRID_MIN_SCREEN_SPACING) { + step *= 2; + screenSpacing *= 2; + } + while (screenSpacing >= PREVIEW_GRID_MAX_SCREEN_SPACING) { + step /= 2; + screenSpacing /= 2; + } + return step; +} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewRightPanGesture.ts b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewRightPanGesture.ts new file mode 100644 index 000000000..839a0ce78 --- /dev/null +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/previewRightPanGesture.ts @@ -0,0 +1,92 @@ +import { + type CanvasViewport, + createPanDragState, + type DragState, + moveViewportFromPan, +} from '@genarrative/image-canvas-core'; + +import { + passedDragThresholdScreen, + type ScreenPoint, +} from './previewDragThreshold'; + +/** + * 右键按下到抬起之间的手势状态。右键同时承载节点菜单与视图平移： + * 只有越过拖动阈值的移动才判定为平移，且一旦越阈值就不再回到"点击开菜单"。 + */ +export type PreviewRightPanGesture = { + pointerId: number; + /** 按下点（屏幕坐标），平移按"按下点全量 delta"计算。 */ + start: ScreenPoint; + panning: boolean; + pan: Extract; +}; + +export function createPreviewRightPanGesture({ + pointerId, + pointer, + viewport, +}: { + pointerId: number; + pointer: ScreenPoint; + viewport: CanvasViewport; +}): PreviewRightPanGesture { + return { + pointerId, + start: pointer, + panning: false, + pan: createPanDragState({ pointerId, pointer, viewport }), + }; +} + +/** 未越阈值时原样返回同一个手势，避免无意义的重复状态写入。 */ +export function movePreviewRightPanGesture( + gesture: PreviewRightPanGesture, + pointer: ScreenPoint, +): PreviewRightPanGesture { + if (gesture.panning || !passedDragThresholdScreen(gesture.start, pointer)) { + return gesture; + } + return { ...gesture, panning: true }; +} + +export type PreviewRightPanRelease = { + /** 平移后的视口；未判定为平移时为 null，调用方不要改视口。 */ + viewport: CanvasViewport | null; + /** 是否按"节点右键菜单"处理。 */ + openNodeMenu: boolean; +}; + +export function resolvePreviewRightPanRelease({ + gesture, + pointer, + isInsidePreview, +}: { + gesture: PreviewRightPanGesture; + pointer: ScreenPoint; + isInsidePreview: boolean; +}): PreviewRightPanRelease { + return { + viewport: gesture.panning + ? moveViewportFromPan(gesture.pan, pointer) + : null, + openNodeMenu: !gesture.panning && isInsidePreview, + }; +} + +/** + * 预览是否接管这一次 contextmenu。 + * 平台差异：Windows / Linux 的 Chromium 与 Firefox 在**按下**时触发 contextmenu， + * macOS 在指针抬起之后触发；而原生菜单一旦弹出，页面之后收不到 pointermove / pointerup， + * 所以必须按下时就拦截，并把拦截窗口保留到下一次指针按下之前。 + * 键盘菜单键不在此列：Chromium 实测上报 `button: -1`，只认 2 正好把它留给原有菜单路径。 + */ +export function shouldInterceptRightContextMenu({ + button, + withinRightPressSequence, +}: { + button: number; + withinRightPressSequence: boolean; +}): boolean { + return button === 2 && withinRightPressSequence; +} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/useNodeTransformInteraction.ts b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/useNodeTransformInteraction.ts index 9b79de2d7..f3b75413c 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/useNodeTransformInteraction.ts +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/useNodeTransformInteraction.ts @@ -21,6 +21,7 @@ import { import type { Node as UiNode } from '../../../../features/ui-editor/types/Node'; import type { UITree } from '../../../../features/ui-editor/types/UITree'; import type { UiEditorCanvasProjection } from '../../useUiEditorPage'; +import { passedDragThresholdScreen } from './previewDragThreshold'; type ViewportScale = { scale: number }; type GestureBase = { @@ -47,17 +48,13 @@ type ActiveGesture = ratioAxis: ResizeAxis | null; }); -const DRAG_THRESHOLD_SCREEN_PX = 2; - function passedDragThreshold( gesture: GestureBase, event: ReactPointerEvent, ) { - return ( - Math.hypot( - event.clientX - gesture.startClientX, - event.clientY - gesture.startClientY, - ) >= DRAG_THRESHOLD_SCREEN_PX + return passedDragThresholdScreen( + { x: gesture.startClientX, y: gesture.startClientY }, + { x: event.clientX, y: event.clientY }, ); } @@ -176,22 +173,20 @@ function emitPreviewTransforms( } export function useNodeTransformInteraction({ - activeImageId, canvas, - logicalSize, + trees, + logicalSizes, spaceHeld, - tree, keepChildrenUnchanged, viewportRef, onPreviewTransform, previewRef, selectedNodeId, }: { - activeImageId: UiEditorCanvasProjection['activeImageId']; canvas: Pick; - logicalSize: { width: number; height: number } | null; + trees: readonly UITree[]; + logicalSizes: ReadonlyMap; spaceHeld: boolean; - tree: UITree | null; keepChildrenUnchanged: boolean; viewportRef: RefObject; onPreviewTransform?: ( @@ -229,36 +224,32 @@ export function useNodeTransformInteraction({ return () => window.removeEventListener('blur', cancelGesture); }, [cancelGesture]); - useEffect(() => { - const gesture = activeGestureRef.current; - if ( - gesture && - (gesture.treeId !== activeImageId || - tree?.src_ui_design !== gesture.treeId) - ) { - cancelGesture(); - } - }, [activeImageId, cancelGesture, tree]); - const acceptsGestureEvent = useCallback( (event: ReactPointerEvent) => { const gesture = activeGestureRef.current; - return ( - gesture !== null && - gesture.pointerId === event.pointerId && - gesture.treeId === activeImageId - ); + return gesture !== null && gesture.pointerId === event.pointerId; }, - [activeImageId], + [], ); const onNodePointerDown = useCallback( - (event: ReactPointerEvent, node: UiNode) => { + ( + event: ReactPointerEvent, + node: UiNode, + treeId?: string, + ) => { + const tree = treeId + ? (trees.find((candidate) => candidate.src_ui_design === treeId) ?? + null) + : null; + const logicalSize = treeId ? (logicalSizes.get(treeId) ?? null) : null; if ( activeGestureRef.current !== null || event.button !== 0 || spaceHeld || - !activeImageId || + !treeId || + !tree || + !logicalSize || node.id === tree?.root.id || !isFiniteTransform(node.layout.transform) ) { @@ -275,7 +266,7 @@ export function useNodeTransformInteraction({ event.preventDefault(); activeGestureRef.current = { kind: 'drag', - treeId: activeImageId, + treeId, nodeId: dragNode.id, pointerId: event.pointerId, target: event.currentTarget, @@ -292,14 +283,7 @@ export function useNodeTransformInteraction({ ), }; }, - [ - activeImageId, - keepChildrenUnchanged, - logicalSize, - spaceHeld, - selectedNodeId, - tree, - ], + [keepChildrenUnchanged, logicalSizes, spaceHeld, selectedNodeId, trees], ); const onNodePointerMove = useCallback( @@ -309,6 +293,11 @@ export function useNodeTransformInteraction({ return; } event.stopPropagation(); + const tree = + trees.find((candidate) => candidate.src_ui_design === gesture.treeId) ?? + null; + const logicalSize = logicalSizes.get(gesture.treeId) ?? null; + if (!tree || !logicalSize) return; if (!gesture.hasMoved && !passedDragThreshold(gesture, event)) return; const scale = viewportRef.current?.scale; if (!Number.isFinite(scale) || scale <= 0) { @@ -346,8 +335,8 @@ export function useNodeTransformInteraction({ acceptsGestureEvent, cancelGesture, keepChildrenUnchanged, - logicalSize, - tree, + logicalSizes, + trees, viewportRef, ], ); @@ -389,12 +378,18 @@ export function useNodeTransformInteraction({ event: ReactPointerEvent, node: UiNode, handle: ResizeHandle, + treeId?: string, ) => { + const tree = treeId + ? (trees.find((candidate) => candidate.src_ui_design === treeId) ?? + null) + : null; + const logicalSize = treeId ? (logicalSizes.get(treeId) ?? null) : null; if ( activeGestureRef.current !== null || event.button !== 0 || spaceHeld || - !activeImageId || + !treeId || node.id === tree?.root.id || !tree || !logicalSize || @@ -424,7 +419,7 @@ export function useNodeTransformInteraction({ suppressNextNodeClickRef.current = false; activeGestureRef.current = { kind: 'resize', - treeId: activeImageId, + treeId, nodeId: node.id, pointerId: event.pointerId, target: event.currentTarget, @@ -445,7 +440,7 @@ export function useNodeTransformInteraction({ ), }; }, - [activeImageId, keepChildrenUnchanged, logicalSize, spaceHeld, tree], + [keepChildrenUnchanged, logicalSizes, spaceHeld, trees], ); const onNodeResizePointerMove = useCallback( @@ -459,6 +454,11 @@ export function useNodeTransformInteraction({ return; } event.stopPropagation(); + const tree = + trees.find((candidate) => candidate.src_ui_design === gesture.treeId) ?? + null; + const logicalSize = logicalSizes.get(gesture.treeId) ?? null; + if (!tree || !logicalSize) return; if (!gesture.hasMoved && !passedDragThreshold(gesture, event)) return; const scale = viewportRef.current?.scale; if (!Number.isFinite(scale) || scale <= 0) { @@ -517,8 +517,8 @@ export function useNodeTransformInteraction({ acceptsGestureEvent, cancelGesture, keepChildrenUnchanged, - logicalSize, - tree, + logicalSizes, + trees, viewportRef, ], ); diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/workflowCompletionNotice.ts b/apps/ai-game-creator-shell/src/view/ui-editor/components/workflowCompletionNotice.ts index 02c5b317a..2e370bdc7 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/components/workflowCompletionNotice.ts +++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/workflowCompletionNotice.ts @@ -14,8 +14,6 @@ export function appendWorkflowCheckPrompt(message: string): string { export function workflowStepLabel(step: UiEditorStepId): string { switch (step) { - case 'reference-analysis': - return '分析参考图'; case 'structure-recognition': return '识别界面结构'; case 'asset-separation': diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/index.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/index.tsx index 4696d76f9..fd5f9c776 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/index.tsx +++ b/apps/ai-game-creator-shell/src/view/ui-editor/index.tsx @@ -1,5 +1,6 @@ -import { ChevronLeft, Redo2, Undo2 } from 'lucide-react'; +import { Redo2, Undo2, X } from 'lucide-react'; import { type ReactNode, useEffect, useMemo, useState } from 'react'; +import { createPortal } from 'react-dom'; import { ThemedModal } from '../../components/modal/ThemedModal'; import { @@ -8,13 +9,16 @@ import { uiDesignStateStore, } from '../../features/ui-editor/uiDesignStateStore'; import { EditorDialogs } from './components/EditorDialogs'; -import { ImportOverview } from './components/ImportOverview'; import { InputSidebar } from './components/InputSidebar'; import { InspectorSidebar } from './components/Inspector/InspectorSidebar'; import { PreviewWorkspace } from './components/preview/PreviewWorkspace'; import { RecognitionOverview } from './components/RecognitionOverview'; import { SeparationOverview } from './components/SeparationOverview'; import { ToolNavigation } from './components/ToolNavigation'; +import { + UiEditorSaveResultModal, + type UiEditorSaveResultNotice, +} from './components/UiEditorSaveResultModal'; import { WorkflowActionCard } from './components/WorkflowActionCard'; import { WorkflowCompletionModal } from './components/WorkflowCompletionModal'; import { UI_EDITOR_STEPS, type UiEditorStepId } from './model'; @@ -69,8 +73,32 @@ export default function UiEditorPage({ const [saveWarningOpen, setSaveWarningOpen] = useState(false); const [saveAfterReturn, setSaveAfterReturn] = useState(false); const [generateAfterWarning, setGenerateAfterWarning] = useState(false); - const [generateSuccess, setGenerateSuccess] = useState(null); + const [saveResultNotice, setSaveResultNotice] = + useState(null); const [returnConfirmOpen, setReturnConfirmOpen] = useState(false); + const [showFrame, setShowFrame] = useState(true); + const [showOriginImage, setShowOriginImage] = useState(true); + const [showComponent, setShowComponent] = useState(false); + const overview: ReactNode = + session.input.activeStep === 'structure-recognition' ? ( + { + session.input.focusNode(treeId, nodeId); + session.input.highlightStatusField(nodeId, 'layout_status'); + }} + /> + ) : ( + { + session.input.focusNode(treeId, nodeId); + session.input.highlightStatusField(nodeId, 'component_status'); + }} + /> + ); const saveDisabled = session.save.isSaving || session.save.isGenerating || @@ -82,49 +110,67 @@ export default function UiEditorPage({ const historyUndo = session.history.undo; const historyRedo = session.history.redo; const selectedNodeId = session.input.selectedNodeId; - const activeImageId = session.input.activeImageId; const deleteNode = session.input.deleteNode; - useEffect(() => { - if (session.save.isDirty) setGenerateSuccess(null); - }, [session.save.isDirty]); - useEffect(() => { const onKeyDown = (event: KeyboardEvent) => handleUiEditorKeyDown(event, { selectedNodeId, - activeImageId, deleteNode, historyUndo, historyRedo, }); window.addEventListener('keydown', onKeyDown); return () => window.removeEventListener('keydown', onKeyDown); - }, [activeImageId, deleteNode, historyRedo, historyUndo, selectedNodeId]); + }, [deleteNode, historyRedo, historyUndo, selectedNodeId]); async function save(afterReturn = false) { - if (await session.save.save()) { + const result = await session.save.save(); + if (result.status === 'saved') { if (afterReturn) { setReturnConfirmOpen(false); onBack?.(); + } else { + setSaveResultNotice({ kind: 'saved' }); } + return; } + if (afterReturn) return; + setSaveResultNotice({ + kind: 'failure', + message: result.message, + retryLabel: '重试保存', + onRetry: () => void save(afterReturn), + }); } async function saveAndGenerate() { - setGenerateSuccess(null); + setSaveResultNotice(null); const result = await session.save.saveAndGenerateCode(); - if (result) { + if (result.status === 'generated') { setGenerateAfterWarning(false); - setGenerateSuccess(`代码已生成：${result.relativePath}`); + setSaveResultNotice({ + kind: 'generated', + relativePath: result.result.relativePath, + }); + return; } + setSaveResultNotice({ + kind: 'failure', + message: + result.phase === 'generate' + ? `项目已保存，但代码生成失败：${result.message}` + : result.message, + retryLabel: '重试保存并生成', + onRetry: () => void saveAndGenerate(), + }); } function requestSave(afterReturn = false) { if (!resourceId || session.save.isSaving || session.workflow.isAiRunning) { return; } - setGenerateSuccess(null); + setSaveResultNotice(null); setSaveAfterReturn(afterReturn); setGenerateAfterWarning(false); if (session.save.hasWarnings()) { @@ -144,7 +190,7 @@ export default function UiEditorPage({ return; } setSaveAfterReturn(false); - setGenerateSuccess(null); + setSaveResultNotice(null); setGenerateAfterWarning(true); if (session.save.hasWarnings()) { setSaveWarningOpen(true); @@ -161,20 +207,41 @@ export default function UiEditorPage({ onBack?.(); } - return ( -
+ const editorContent = ( +
{resourceId ? ( -
- +
{resourceLabel ?? 'UI 设计'}
+
+ + + +
) : null} +
) : null} - {session.save.saveError ? ( -
- {session.save.saveError} -
+
); + + if (!resourceId) return editorContent; + + if (typeof document === 'undefined') return editorContent; + + return createPortal( +
+
+ {editorContent} +
+
, + document.body, + ); } function stepLabel(step: UiEditorWorkflowProjection['activeStep'] | undefined) { diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/model.ts b/apps/ai-game-creator-shell/src/view/ui-editor/model.ts index f03f6ef47..4722faac6 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/model.ts +++ b/apps/ai-game-creator-shell/src/view/ui-editor/model.ts @@ -1,12 +1,8 @@ import type { NodeId } from '../../features/ui-editor/types/NodeId'; import type { UIDesignImageId } from '../../features/ui-editor/types/UIDesignImageId'; -import type { UIDesignImageRole } from '../../features/ui-editor/types/UIDesignImageRole'; import type { RemovalImpact } from '../../features/ui-editor/useUiEditorState'; -export type UiEditorStepId = - | 'reference-analysis' - | 'structure-recognition' - | 'asset-separation'; +export type UiEditorStepId = 'structure-recognition' | 'asset-separation'; export type UiEditorImportKind = 'design-image' | 'font' | 'sprite'; export type UiEditorNodeFocusRequest = { @@ -25,29 +21,13 @@ export const UI_EDITOR_STEPS: Array<{ id: UiEditorStepId; label: string; }> = [ - { id: 'reference-analysis', label: '分析参考图' }, { id: 'structure-recognition', label: '识别界面结构' }, { id: 'asset-separation', label: '自动切分素材' }, ]; -export const UI_DESIGN_IMAGE_ROLES: Array<{ - value: UIDesignImageRole; - label: string; -}> = [ - { value: 'Page', label: '主页面' }, - { value: 'Section', label: '子界面 / 页签' }, - { value: 'Modal', label: '模态弹窗' }, - { value: 'Drawer', label: '抽屉 / 侧栏' }, - { value: 'Popover', label: '局部浮层' }, - { value: 'State', label: '交互状态' }, - { value: 'Scrolled', label: '滚动后内容' }, - { value: 'Detail', label: '局部详情' }, -]; - export function removalHasDownstreamReferences(impact: RemovalImpact) { return ( impact.removedTreeCount + - impact.clearedSlaveToCount + impact.clearedTargetGraphicCount + impact.clearedFontCount > 0 diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/operationLifecycle.ts b/apps/ai-game-creator-shell/src/view/ui-editor/operationLifecycle.ts new file mode 100644 index 000000000..c9eeec810 --- /dev/null +++ b/apps/ai-game-creator-shell/src/view/ui-editor/operationLifecycle.ts @@ -0,0 +1,21 @@ +import { useCallback, useState } from 'react'; + +export type UiEditorOperationLifecycle = { + running: boolean; + status: string | null; + setStatus: (status: string | null) => void; + begin: () => void; + finish: () => void; +}; + +/** Shared async-operation adapter used by suggestion/recognition/merge/separation. */ +export function useUiEditorOperation(): UiEditorOperationLifecycle { + const [running, setRunning] = useState(false); + const [status, setStatus] = useState(null); + const begin = useCallback(() => { + setStatus(null); + setRunning(true); + }, []); + const finish = useCallback(() => setRunning(false), []); + return { running, status, setStatus, begin, finish }; +} diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/uiEditorKeyboardShortcuts.ts b/apps/ai-game-creator-shell/src/view/ui-editor/uiEditorKeyboardShortcuts.ts index 90657f5b4..38c194e2d 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/uiEditorKeyboardShortcuts.ts +++ b/apps/ai-game-creator-shell/src/view/ui-editor/uiEditorKeyboardShortcuts.ts @@ -5,8 +5,8 @@ type DeleteResult = { ok: boolean } | undefined; export type UiEditorKeyboardActions = { selectedNodeId: NodeId | null; - activeImageId: UIDesignImageId | null; - deleteNode: (nodeId: NodeId, treeId: UIDesignImageId) => DeleteResult; + /** 省略 treeId 时由调用方按选中节点定位所在 UI 树。 */ + deleteNode: (nodeId: NodeId, treeId?: UIDesignImageId | null) => DeleteResult; historyUndo: () => boolean; historyRedo: () => boolean; }; @@ -50,11 +50,8 @@ export function handleUiEditorKeyDown( !event.shiftKey && !isInteractiveTarget(event.target) ) { - if (actions.selectedNodeId && actions.activeImageId) { - const result = actions.deleteNode( - actions.selectedNodeId, - actions.activeImageId, - ); + if (actions.selectedNodeId) { + const result = actions.deleteNode(actions.selectedNodeId); if (result?.ok) { event.preventDefault(); event.stopPropagation(); diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/useUiEditorPage.ts b/apps/ai-game-creator-shell/src/view/ui-editor/useUiEditorPage.ts index 6a2d84664..c88d3e111 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/useUiEditorPage.ts +++ b/apps/ai-game-creator-shell/src/view/ui-editor/useUiEditorPage.ts @@ -8,7 +8,10 @@ import { prepareFontAssetBatch, prepareSpriteAssetBatch, } from '../../features/ui-editor/importAdapter'; -import { applyMergeResult } from '../../features/ui-editor/merge'; +import { + findStateNodePageContext, + pageRectSize, +} from '../../features/ui-editor/nodeTransformGeometry'; import { applyRecognitionResult } from '../../features/ui-editor/recognition'; import { applySeparationProblematicStatuses, @@ -18,11 +21,11 @@ import { getStageStatusOverview, type StageStatusField, } from '../../features/ui-editor/stageStatusOverview'; +import { firstUiDesignInvariantMessage } from '../../features/ui-editor/stateInvariants'; import { collectUiNodeIds } from '../../features/ui-editor/treeUtils'; import type { ChildrenDisplayMode } from '../../features/ui-editor/types/ChildrenDisplayMode'; import type { Component } from '../../features/ui-editor/types/Component'; import type { FontAssetId } from '../../features/ui-editor/types/FontAssetId'; -import type { MergeDTO } from '../../features/ui-editor/types/MergeDTO'; import type { Node as UiNode } from '../../features/ui-editor/types/Node'; import type { NodeId } from '../../features/ui-editor/types/NodeId'; import type { RecognitionDTO } from '../../features/ui-editor/types/RecognitionDTO'; @@ -30,20 +33,17 @@ import type { SeparationDTO } from '../../features/ui-editor/types/SeparationDTO import type { SeparationRecoveryDTO } from '../../features/ui-editor/types/SeparationRecoveryDTO'; import type { SpriteAssetId } from '../../features/ui-editor/types/SpriteAssetId'; import type { SpriteBorder } from '../../features/ui-editor/types/SpriteBorder'; -import type { State } from '../../features/ui-editor/types/State'; -import type { UIDesignImage } from '../../features/ui-editor/types/UIDesignImage'; import type { UIDesignImageId } from '../../features/ui-editor/types/UIDesignImageId'; -import type { UIDesignImageRole } from '../../features/ui-editor/types/UIDesignImageRole'; -import type { UIDesignSuggestionTreeNode } from '../../features/ui-editor/types/UIDesignSuggestionTreeNode'; import type { UiNodeMoveRequest } from '../../features/ui-editor/types/UiNodeMoveRequest'; import { type IUiDesignStateStore, + type UiDesignCodeGenerationResult, uiDesignStateStore, } from '../../features/ui-editor/uiDesignStateStore'; -import { applyUiDesignSuggestions } from '../../features/ui-editor/uiDesignSuggestions'; import { useUiEditorFontFaces } from '../../features/ui-editor/useUiEditorFontFaces'; import { addSpriteAssetsToState } from '../../features/ui-editor/useUiEditorState'; import { + createTree, EMPTY_UI_EDITOR_STATE, type NodeLayoutPatch, type NodeMetadataPatch, @@ -71,14 +71,24 @@ import { import { type PendingResourceRemoval, removalHasDownstreamReferences, + UI_EDITOR_STEPS, type UiEditorImportKind, uiEditorOperationError, type UiEditorStepId, } from './model'; +import { useUiEditorOperation } from './operationLifecycle'; import { useUiEditorNodeFocus } from './useUiEditorNodeFocus'; const SEPARATION_IMPORT_BATCH_SIZE = 100; +export type UiEditorSaveResult = + | { status: 'saved' } + | { status: 'failed'; message: string }; + +export type UiEditorSaveAndGenerateResult = + | { status: 'generated'; result: UiDesignCodeGenerationResult } + | { status: 'failed'; phase: 'save' | 'generate'; message: string }; + type LocalImageImportResponse = { assets: Array<{ id: string; @@ -136,50 +146,6 @@ function isUiNodeEffectivelyVisible( return null; } -function findNodeContext( - node: UiNode, - nodeId: NodeId, - parentSize: { width: number; height: number }, -): { node: UiNode; parentSize: { width: number; height: number } } | null { - if (node.id === nodeId) return { node, parentSize }; - const width = - parentSize.width * - (node.layout.transform.anchor_max[0] - - node.layout.transform.anchor_min[0]) + - node.layout.transform.offset_max[0] - - node.layout.transform.offset_min[0]; - const height = - parentSize.height * - (node.layout.transform.anchor_max[1] - - node.layout.transform.anchor_min[1]) + - node.layout.transform.offset_max[1] - - node.layout.transform.offset_min[1]; - for (const child of node.children) { - const found = findNodeContext(child, nodeId, { width, height }); - if (found) return found; - } - return null; -} - -function isSlaveToDescendant( - images: State['ui_design_images'], - candidateId: UIDesignImageId, - ancestorId: UIDesignImageId | null, -): boolean { - if (ancestorId === null || candidateId === ancestorId) return true; - let current: UIDesignImageId | null = candidateId; - const visited = new Set(); - while (current !== null) { - if (visited.has(current)) return true; - visited.add(current); - const image: UIDesignImage | undefined = images[current]; - if (!image) return true; - current = image.metadata.slave_to; - if (current === ancestorId) return true; - } - return false; -} - export type PendingWorkflowStepChange = { from: UiEditorStepId; to: UiEditorStepId; @@ -197,11 +163,12 @@ export function useUiEditorSession( projectPath: string, resourceId?: string, stateStore: IUiDesignStateStore = uiDesignStateStore, - initialStep: UiEditorStepId = 'reference-analysis', + initialStep: UiEditorStepId = 'structure-recognition', initialFurthestStepIndex = 0, ) { const editor = useUiEditorState(EMPTY_UI_EDITOR_STATE); const editorDeleteNode = editor.deleteNode; + const setTreeOffset = editor.setTreeOffset; const editorUiTrees = editor.state.ui_trees; const replaceEditorState = editor.replaceState; const [isLoading, setIsLoading] = useState(Boolean(resourceId)); @@ -214,17 +181,17 @@ export function useUiEditorSession( ); const [saveError, setSaveError] = useState(null); const [isSaving, setIsSaving] = useState(false); - const [generateError, setGenerateError] = useState(null); const [isGenerating, setIsGenerating] = useState(false); - const normalizedInitialStepIndex = - initialStep === 'reference-analysis' - ? 0 - : initialStep === 'structure-recognition' - ? 1 - : 2; + const normalizedInitialStepIndex = Math.max( + 0, + UI_EDITOR_STEPS.findIndex((step) => step.id === initialStep), + ); const normalizedInitialFurthestStepIndex = Math.max( normalizedInitialStepIndex, - Math.min(2, Math.max(0, Math.trunc(initialFurthestStepIndex))), + Math.min( + UI_EDITOR_STEPS.length - 1, + Math.max(0, Math.trunc(initialFurthestStepIndex)), + ), ); const [activeStep, setActiveStep] = useState(initialStep); const [furthestStepIndex, setFurthestStepIndex] = useState( @@ -261,19 +228,20 @@ export function useUiEditorSession( const [clearOpen, setClearOpen] = useState(false); const [pendingRemoval, setPendingRemoval] = useState(null); - const [isSuggesting, setIsSuggesting] = useState(false); - const [suggestionStatus, setSuggestionStatus] = useState(null); - const [isRecognizing, setIsRecognizing] = useState(false); - const [recognitionStatus, setRecognitionStatus] = useState( - null, - ); - const [isMerging, setIsMerging] = useState(false); - const [mergeStatus, setMergeStatus] = useState(null); - const [isSeparating, setIsSeparating] = useState(false); - const [separationStatus, setSeparationStatus] = useState(null); + const recognitionOperation = useUiEditorOperation(); + const separationOperation = useUiEditorOperation(); + const isRecognizing = recognitionOperation.running; + const recognitionStatus = recognitionOperation.status; + const beginRecognition = recognitionOperation.begin; + const finishRecognition = recognitionOperation.finish; + const setRecognitionStatus = recognitionOperation.setStatus; + const isSeparating = separationOperation.running; + const separationStatus = separationOperation.status; + const beginSeparation = separationOperation.begin; + const finishSeparation = separationOperation.finish; + const setSeparationStatus = separationOperation.setStatus; const [separationRecovery, setSeparationRecovery] = useState(null); - const [hasSuggested, setHasSuggested] = useState(false); const [hasRecognized, setHasRecognized] = useState(false); const [hasSeparated, setHasSeparated] = useState(false); const [completionNotice, setCompletionNotice] = @@ -300,7 +268,6 @@ export function useUiEditorSession( setPersistedRevision(0); setSavedStateSignature(JSON.stringify(EMPTY_UI_EDITOR_STATE)); setSaveError(null); - setGenerateError(null); setIsGenerating(false); setHiddenNodeIds(new Set()); return; @@ -311,7 +278,6 @@ export function useUiEditorSession( setLoadError(null); setPersistedRevision(null); setSaveError(null); - setGenerateError(null); setIsGenerating(false); void stateStore .load(resourceId) @@ -409,13 +375,7 @@ export function useUiEditorSession( const activeImage = activeImageId ? images[activeImageId] : null; const selectedSprite = selectedSpriteId ? sprites[selectedSpriteId] : null; const selectedFont = selectedFontId ? fonts[selectedFontId] : null; - const pageOptions = Object.entries(images).filter( - ([id, image]) => - image.metadata.role === 'Page' && - !isSlaveToDescendant(images, id as UIDesignImageId, activeImageId), - ); - const isAiRunning = - isSuggesting || isRecognizing || isMerging || isSeparating; + const isAiRunning = isRecognizing || isSeparating; const isWorkflowBusy = isAiRunning || isSaving || isGenerating || isLoading || editor.isLocked; const stateSignature = JSON.stringify(editor.state); @@ -424,7 +384,6 @@ export function useUiEditorSession( savedStateSignature !== null && savedStateSignature !== stateSignature; const nextStepByStep: Partial> = { - 'reference-analysis': 'structure-recognition', 'structure-recognition': 'asset-separation', }; const nextStep = nextStepByStep[activeStep] ?? null; @@ -469,6 +428,16 @@ export function useUiEditorSession( ? editor.state.ui_trees.find((tree) => tree.src_ui_design === activeImageId) : null; + const treeForSelectedNode = useMemo(() => { + if (!selectedNodeId) return null; + return ( + editor.state.ui_trees.find( + (candidate) => + findUiNodeLocation(candidate.root, selectedNodeId) !== null, + ) ?? null + ); + }, [editor.state.ui_trees, selectedNodeId]); + useEffect(() => { const validNodeIds = new Set(); for (const tree of editor.state.ui_trees) { @@ -570,16 +539,16 @@ export function useUiEditorSession( [setNodePreviewVisible], ); const selectedNodeContext = useMemo(() => { - if (!activeImage || !treeForActiveImage || !selectedNodeId) return null; - const ppu = activeImage.pixels_per_unit; - const width = activeImage.pixel_size[0] / ppu; - const height = activeImage.pixel_size[1] / ppu; - if (!Number.isFinite(width) || !Number.isFinite(height)) return null; - return findNodeContext(treeForActiveImage.root, selectedNodeId, { - width, - height, - }); - }, [activeImage, selectedNodeId, treeForActiveImage]); + if (!selectedNodeId || !treeForSelectedNode) return null; + const context = findStateNodePageContext( + editor.state, + treeForSelectedNode.src_ui_design, + selectedNodeId, + ); + if (!context) return null; + const [width, height] = pageRectSize(context.parentRect); + return { node: context.node, parentSize: { width, height } }; + }, [editor.state, selectedNodeId, treeForSelectedNode]); async function importAssets(imported: ImportedAsset[]) { if (!importKind || !projectPath) return; @@ -705,13 +674,10 @@ export function useUiEditorSession( function enterStep(step: UiEditorStepId) { setActiveStep(step); - const index = - step === 'reference-analysis' - ? 0 - : step === 'structure-recognition' - ? 1 - : 2; - setFurthestStepIndex((current) => Math.max(current, index)); + const index = UI_EDITOR_STEPS.findIndex( + (candidate) => candidate.id === step, + ); + setFurthestStepIndex((current) => Math.max(current, Math.max(0, index))); } function requestStepChange(step: UiEditorStepId) { @@ -785,8 +751,12 @@ export function useUiEditorSession( } function setNodeTransform(transform: UiNode['layout']['transform']) { - if (!activeImageId || !selectedNodeId) return; - return updateNodeTransform(activeImageId, selectedNodeId, transform); + if (!treeForSelectedNode?.src_ui_design || !selectedNodeId) return; + return updateNodeTransform( + treeForSelectedNode.src_ui_design, + selectedNodeId, + transform, + ); } function updateNodeTransform( @@ -805,8 +775,12 @@ export function useUiEditorSession( } function setNodeMetadata(patch: NodeMetadataPatch) { - if (!activeImageId || !selectedNodeId) return; - const result = editor.setNodeMetadata(activeImageId, selectedNodeId, patch); + if (!treeForSelectedNode?.src_ui_design || !selectedNodeId) return; + const result = editor.setNodeMetadata( + treeForSelectedNode.src_ui_design, + selectedNodeId, + patch, + ); if ( result.ok && (patch.layout_status !== undefined || @@ -819,19 +793,23 @@ export function useUiEditorSession( } function setNodeLayout(patch: NodeLayoutPatch) { - if (!activeImageId || !selectedNodeId) return; - const result = editor.setNodeLayout(activeImageId, selectedNodeId, patch); + if (!treeForSelectedNode?.src_ui_design || !selectedNodeId) return; + const result = editor.setNodeLayout( + treeForSelectedNode.src_ui_design, + selectedNodeId, + patch, + ); if (!result.ok) setStatus('节点布局更新失败。'); return result; } function setNodeChildrenDisplayMode(mode: ChildrenDisplayMode) { - if (!activeImageId || !selectedNodeId) return; - const selectedNode = treeForActiveImage - ? findUiNodeLocation(treeForActiveImage.root, selectedNodeId)?.node + if (!treeForSelectedNode?.src_ui_design || !selectedNodeId) return; + const selectedNode = treeForSelectedNode + ? findUiNodeLocation(treeForSelectedNode.root, selectedNodeId)?.node : null; const result = editor.setNodeChildrenDisplayMode( - activeImageId, + treeForSelectedNode.src_ui_design, selectedNodeId, mode, ); @@ -850,9 +828,9 @@ export function useUiEditorSession( } function setNodeComponent(component: Component | null) { - if (!activeImageId || !selectedNodeId) return; + if (!treeForSelectedNode?.src_ui_design || !selectedNodeId) return; const result = editor.setNodeComponent( - activeImageId, + treeForSelectedNode.src_ui_design, selectedNodeId, component, ); @@ -897,7 +875,12 @@ export function useUiEditorSession( } const deleteNode = useCallback( - (nodeId: NodeId, treeId = activeImageId) => { + ( + nodeId: NodeId, + // 不给 treeId 时落到选中节点真正所在的树：选中节点可以来自非激活界面图， + // 按 activeImageId 找会静默删不掉。 + treeId = treeForSelectedNode?.src_ui_design ?? activeImageId, + ) => { if (!treeId) return; const tree = editorUiTrees.find( (candidate) => candidate.src_ui_design === treeId, @@ -914,7 +897,13 @@ export function useUiEditorSession( } return result; }, - [activeImageId, editorDeleteNode, editorUiTrees, selectedNodeId], + [ + activeImageId, + editorDeleteNode, + editorUiTrees, + selectedNodeId, + treeForSelectedNode, + ], ); function selectSprite(id: SpriteAssetId) { @@ -929,26 +918,6 @@ export function useUiEditorSession( setSelectedFontId(id); } - function setImageName(name: string) { - if (!activeImageId) return; - editor.setImageName(activeImageId, name); - } - - function setImageDescription(description: string) { - if (!activeImageId) return; - editor.setImageDescription(activeImageId, description); - } - - function setImageRole(role: UIDesignImageRole | null) { - if (!activeImageId) return; - editor.setImageRole(activeImageId, role); - } - - function setImageSlaveTo(slaveTo: UIDesignImageId | null) { - if (!activeImageId) return; - editor.setImageSlaveTo(activeImageId, slaveTo); - } - function setSpriteName(name: string) { if (!selectedSpriteId) return; editor.setSpriteName(selectedSpriteId, name); @@ -964,43 +933,11 @@ export function useUiEditorSession( editor.setSpriteBorder(selectedSpriteId, border); } - async function suggestUiDesignSemantics() { - if (isSuggesting || isWorkflowBusy) return; - setCompletionNotice(null); - setSuggestionStatus(null); - setIsSuggesting(true); - try { - await editor.runWithStateLocked(async (snapshot) => { - const suggestions = await invoke( - 'suggest_ui_design_semantic', - { projectPath, state: snapshot }, - ); - editor.replaceState(applyUiDesignSuggestions(snapshot, suggestions)); - setHasSuggested(true); - reportWorkflowCompletion( - 'reference-analysis', - 'success', - `参考图分析完成：已应用 ${suggestions.length} 条参考图语义建议`, - setSuggestionStatus, - ); - }); - } catch (cause) { - reportWorkflowCompletion( - 'reference-analysis', - 'failure', - cause instanceof Error ? cause.message : String(cause), - setSuggestionStatus, - ); - } finally { - setIsSuggesting(false); - } - } - async function recognizeUi() { if (isRecognizing || isWorkflowBusy) return; setCompletionNotice(null); setRecognitionStatus(null); - setIsRecognizing(true); + beginRecognition(); try { await editor.runWithStateLocked(async (snapshot) => { const result = await invoke('recognize_ui', { @@ -1008,6 +945,13 @@ export function useUiEditorSession( state: snapshot, }); const nextState = applyRecognitionResult(snapshot, result); + const recognizedTrees = nextState.ui_trees; + nextState.ui_trees = []; + for (const tree of recognizedTrees) { + nextState.ui_trees.push( + createTree(nextState, tree.src_ui_design, tree.root), + ); + } editor.replaceState(nextState); setHasRecognized(true); setSelectedNodeId(null); @@ -1030,32 +974,13 @@ export function useUiEditorSession( setRecognitionStatus, ); } finally { - setIsRecognizing(false); - } - } - - async function mergeUi() { - // TODO: This experimental operation is intentionally outside the formal workflow. - if (isMerging || isWorkflowBusy) return; - setMergeStatus(null); - setIsMerging(true); - try { - await editor.runWithStateLocked(async (snapshot) => { - const result = await invoke('merge_ui', { state: snapshot }); - editor.replaceState(applyMergeResult(snapshot, result)); - setSelectedNodeId(null); - setMergeStatus('已生成合并后的单棵界面树。'); - }); - } catch (cause) { - setMergeStatus(cause instanceof Error ? cause.message : String(cause)); - } finally { - setIsMerging(false); + finishRecognition(); } } async function runSeparationWorkflow() { if (!resourceId || isWorkflowBusy) return; - setIsSeparating(true); + beginSeparation(); setSeparationStatus(null); setCompletionNotice(null); let preparedSprites: Awaited> = @@ -1217,7 +1142,10 @@ export function useUiEditorSession( if (separationResult === null) throw new Error('自动切分素材没有返回结果'); const completedResult = separationResult as SeparationDTO; - if (!(await save({ allowDuringSeparation: true, saveSource: 'auto' }))) { + if ( + (await save({ allowDuringSeparation: true, saveSource: 'auto' })) + .status !== 'saved' + ) { throw new Error( '自动切分素材结果已写入编辑器，但 State 保存失败；sidecar 已保留，可继续恢复。', ); @@ -1263,7 +1191,7 @@ export function useUiEditorSession( setSeparationStatus, ); } finally { - setIsSeparating(false); + finishSeparation(); } } @@ -1391,7 +1319,10 @@ export function useUiEditorSession( persistedRevision === null || editor.isLocked ) { - return false; + return { + status: 'failed' as const, + message: '当前状态不允许保存，请稍后重试。', + }; } const analytics = beginUiSaveAnalytics( invoke, @@ -1399,10 +1330,17 @@ export function useUiEditorSession( options?.saveSource ?? 'manual', ); setSaveError(null); - setGenerateError(null); setIsSaving(true); try { return await editor.runWithStateLocked(async (snapshot) => { + const invariantMessage = firstUiDesignInvariantMessage(snapshot); + if (invariantMessage) { + setSaveError(invariantMessage); + return { + status: 'failed' as const, + message: invariantMessage, + }; + } const snapshotSignature = JSON.stringify(snapshot); const result = await stateStore.save( resourceId, @@ -1411,49 +1349,24 @@ export function useUiEditorSession( ); if (result.status === 'conflict') { setSaveError('资源已在别处更新；请重新加载后再保存。'); - return false; + return { + status: 'failed' as const, + message: '资源已在别处更新；请重新加载后再保存。', + }; } setPersistedRevision(result.revision); setSavedStateSignature(snapshotSignature); analytics?.record(result.status === 'saved'); - return true; + return { status: 'saved' as const }; }); } catch { setSaveError('保存失败，请稍后重试。'); - return false; + return { status: 'failed' as const, message: '保存失败，请稍后重试。' }; } finally { setIsSaving(false); } } - async function generateCode() { - if ( - !resourceId || - isGenerating || - isSaving || - isLoading || - isAiRunning || - loadError || - persistedRevision === null || - editor.isLocked - ) { - setGenerateError('当前状态不允许生成代码，请稍后重试。'); - return null; - } - setGenerateError(null); - setIsGenerating(true); - try { - return await editor.runWithStateLocked(() => - stateStore.generateCode(resourceId), - ); - } catch (cause) { - setGenerateError(cause instanceof Error ? cause.message : String(cause)); - return null; - } finally { - setIsGenerating(false); - } - } - async function saveAndGenerateCode() { if ( !resourceId || @@ -1465,15 +1378,27 @@ export function useUiEditorSession( persistedRevision === null || editor.isLocked ) { - return null; + return { + status: 'failed' as const, + phase: 'save' as const, + message: '当前状态不允许保存并生成代码，请稍后重试。', + }; } const analytics = beginUiSaveAnalytics(invoke, projectPath, 'manual'); setSaveError(null); - setGenerateError(null); setIsSaving(true); setIsGenerating(true); try { return await editor.runWithStateLocked(async (snapshot) => { + const invariantMessage = firstUiDesignInvariantMessage(snapshot); + if (invariantMessage) { + setSaveError(invariantMessage); + return { + status: 'failed' as const, + phase: 'save' as const, + message: invariantMessage, + }; + } const snapshotSignature = JSON.stringify(snapshot); const saved = await stateStore.save( resourceId, @@ -1482,17 +1407,32 @@ export function useUiEditorSession( ); if (saved.status === 'conflict') { setSaveError('资源已在别处更新；请重新加载后再保存。'); - return null; + return { + status: 'failed' as const, + phase: 'save' as const, + message: '资源已在别处更新；请重新加载后再保存。', + }; } setPersistedRevision(saved.revision); setSavedStateSignature(snapshotSignature); - const generated = await stateStore.generateCode(resourceId); - analytics?.record(saved.status === 'saved'); - return generated; + try { + const generated = await stateStore.generateCode(resourceId); + analytics?.record(saved.status === 'saved'); + return { status: 'generated' as const, result: generated }; + } catch (cause) { + const message = + cause instanceof Error ? cause.message : String(cause); + return { + status: 'failed' as const, + phase: 'generate' as const, + message, + }; + } }); } catch (cause) { - setGenerateError(cause instanceof Error ? cause.message : String(cause)); - return null; + const message = cause instanceof Error ? cause.message : String(cause); + setSaveError(message); + return { status: 'failed' as const, phase: 'save' as const, message }; } finally { setIsGenerating(false); setIsSaving(false); @@ -1518,18 +1458,12 @@ export function useUiEditorSession( selectedNodeId, focusRequest, operations: { - isMerging, isRecognizing, - isSuggesting, - mergeStatus, recognitionStatus, - suggestionStatus, }, checkPrerequisites, separateUi, - mergeUi, recognizeUi, - suggestUiDesignSemantics, openImporter: setImportKind, selectDesignImage, selectSprite, @@ -1548,11 +1482,14 @@ export function useUiEditorSession( isLocked: editor.isLocked, activeImage, activeImageId, + uiTrees: editor.state.ui_trees, previewUrls, images, sprites, fontFaces, tree: treeForActiveImage ?? null, + selectedTreeId: treeForSelectedNode?.src_ui_design ?? null, + setTreeOffset, selectedNode: selectedNodeContext?.node ?? null, selectedNodeId, keepChildrenUnchanged, @@ -1587,16 +1524,15 @@ export function useUiEditorSession( selectedNode: selectedNodeContext?.node ?? null, selectedNodeParentSize: selectedNodeContext?.parentSize, selectedNodeParent: - selectedNodeId && treeForActiveImage - ? (findUiNodeLocation(treeForActiveImage.root, selectedNodeId) + selectedNodeId && treeForSelectedNode + ? (findUiNodeLocation(treeForSelectedNode.root, selectedNodeId) ?.parent ?? null) : null, - tree: treeForActiveImage ?? null, + tree: treeForSelectedNode ?? treeForActiveImage ?? null, previewUrls, sprites, fonts, fontFaces, - pageOptions, spriteReferenceCounts, fontReferenceCounts, keepChildrenUnchanged, @@ -1615,10 +1551,6 @@ export function useUiEditorSession( setSpriteBorder, requestSpriteRemoval, requestFontRemoval, - setImageName, - setImageDescription, - setImageRole, - setImageSlaveTo, requestDesignImageRemoval, }, workflow: { @@ -1628,10 +1560,6 @@ export function useUiEditorSession( isAiRunning, isBusy: isWorkflowBusy, pendingStepChange: pendingWorkflowStepChange, - isSuggesting, - hasSuggested, - suggestionStatus, - suggestUiDesignSemantics, isRecognizing, hasRecognized, recognitionStatus, @@ -1674,11 +1602,9 @@ export function useUiEditorSession( isDirty, saveError, isGenerating, - generateError, hasWarnings: () => postCheckIssuesForSave(editor.state).length > 0, warnings: () => postCheckIssuesForSave(editor.state), save, - generateCode, saveAndGenerateCode, }, }; diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/useUiTreeNodeCycle.ts b/apps/ai-game-creator-shell/src/view/ui-editor/useUiTreeNodeCycle.ts index 6d32b3983..cb0053562 100644 --- a/apps/ai-game-creator-shell/src/view/ui-editor/useUiTreeNodeCycle.ts +++ b/apps/ai-game-creator-shell/src/view/ui-editor/useUiTreeNodeCycle.ts @@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react'; import { getNextMatchingUiTreeNodeTarget, + type UiTreeNodeCursor, type UiTreeNodeTarget, } from '../../features/ui-editor/stageStatusOverview'; import type { NodeId } from '../../features/ui-editor/types/NodeId'; @@ -17,20 +18,20 @@ export function useUiTreeNodeCycle({ matches: (target: UiTreeNodeTarget) => boolean; onFocusNode: (treeId: UIDesignImageId, nodeId: NodeId) => void; }) { - const [lastNodeId, setLastNodeId] = useState(null); + const [lastCursor, setLastCursor] = useState(null); - useEffect(() => setLastNodeId(null), [uiTrees]); + useEffect(() => setLastCursor(null), [uiTrees]); const focusNext = useCallback(() => { const target = getNextMatchingUiTreeNodeTarget( uiTrees, - lastNodeId, + lastCursor, matches, ); if (!target) return; - setLastNodeId(target.node.id); + setLastCursor({ treeId: target.treeId, nodeId: target.node.id }); onFocusNode(target.treeId, target.node.id); - }, [lastNodeId, matches, onFocusNode, uiTrees]); + }, [lastCursor, matches, onFocusNode, uiTrees]); return { focusNext }; } diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts index c12e7f92b..362a73b85 100644 --- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts +++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts @@ -6111,10 +6111,12 @@ export function registerProjectWorkbenchFoundationTests() { }), ); fireEvent.click(await screen.findByRole('button', { name: 'UI 编辑器' })); - await screen.findByRole('button', { name: '返回资源' }); - fireEvent.click(screen.getByRole('button', { name: '返回资源' })); + await screen.findByRole('button', { name: '关闭 UI 编辑器' }); + fireEvent.click(screen.getByRole('button', { name: '关闭 UI 编辑器' })); await waitFor(() => - expect(screen.queryByRole('button', { name: '返回资源' })).toBeNull(), + expect( + screen.queryByRole('button', { name: '关闭 UI 编辑器' }), + ).toBeNull(), ); const restoredCanvas = await screen.findByRole('region', { @@ -6535,7 +6537,7 @@ export function registerProjectWorkbenchFoundationTests() { ).not.toBeNull(); }); - it('opens the UI editor bridge from a canonical ui-design prototype image', async () => { + it('opens the UI editor by creating a design doc from a canonical ui-design prototype image', async () => { installResizeObserverStub(); const manifest = createGameCreationAppManifest( 'workbench-ui-prototype-entry', @@ -6578,7 +6580,7 @@ export function registerProjectWorkbenchFoundationTests() { }, }; } - if (command === 'ensure_ui_design_resource_for_prototype') { + if (command === 'create_ui_design_doc_from_images') { // 必须返回真实形状的成功结果：返回 `null` 会让 `result.manifest.projectId` // 抛 TypeError 并被组件吞进错误分支，用例就永远测不到它名字里的成功路径。 return { @@ -6602,8 +6604,9 @@ export function registerProjectWorkbenchFoundationTests() { }, ], }, + relativePath: 'ui/UI 设计 1.json', + imageIds: ['ui-prototype-asset'], committedProjectRevision: 1, - created: true, }; } throw new Error(`unexpected invoke ${command}`); @@ -6630,10 +6633,10 @@ export function registerProjectWorkbenchFoundationTests() { ); fireEvent.click(await screen.findByRole('button', { name: 'UI 编辑器' })); expect(invoke).toHaveBeenCalledWith( - 'ensure_ui_design_resource_for_prototype', + 'create_ui_design_doc_from_images', expect.objectContaining({ input: expect.objectContaining({ - prototypeAssetId: 'ui-prototype-asset', + images: [{ assetId: 'ui-prototype-asset' }], }), }), ); diff --git a/apps/ai-game-creator-shell/tests/previewRightPanDrag.test.tsx b/apps/ai-game-creator-shell/tests/previewRightPanDrag.test.tsx new file mode 100644 index 000000000..aab60e92a --- /dev/null +++ b/apps/ai-game-creator-shell/tests/previewRightPanDrag.test.tsx @@ -0,0 +1,547 @@ +// @vitest-environment jsdom + +import { + act, + cleanup, + fireEvent, + render, + screen, +} from '@testing-library/react'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import type { Node as UiNode } from '../src/features/ui-editor/types/Node'; +import type { UIDesignImage } from '../src/features/ui-editor/types/UIDesignImage'; +import { PreviewWorkspace } from '../src/view/ui-editor/components/preview/PreviewWorkspace'; +import type { UiEditorCanvasProjection } from '../src/view/ui-editor/useUiEditorPage'; + +const PANNING_CLASS = 'genarrative-image-canvas__viewport--panning'; +const DEFAULT_BUTTONS: Record = { 0: 1, 1: 4, 2: 2 }; + +class TestResizeObserver { + observe() {} + disconnect() {} + unobserve() {} +} + +function node( + id: string, + offset: { min: [number, number]; max: [number, number] }, + children: UiNode[] = [], +): UiNode { + return { + id, + layout: { + transform: { + anchor_min: [0, 0], + anchor_max: [1, 1], + offset_min: [0, 0], + offset_max: [0, 0], + }, + custom_minimum_size: [0, 0], + size_flags_horizontal: 1, + size_flags_vertical: 1, + size_flags_stretch_ratio: 1, + container: 'None', + }, + metadata: { + name: id, + description: '', + layout_status: 'NoProblem', + component_status: 'NoProblem', + allow_llm_edit_layout: true, + allow_llm_edit_component: true, + source: 'System', + }, + component: null, + children_display_mode: 'Stack', + children, + offset, + }; +} + +const activeImage: UIDesignImage = { + metadata: { + name: '测试界面', + description: '', + role: null, + slave_to: null, + }, + path: 'assets/page.png', + pixel_size: [1200, 800], + pixels_per_unit: 1, +}; + +const root = node('root', { min: [0, 0], max: [1200, 800] }, [ + node('child', { min: [40, 40], max: [440, 240] }), +]); + +const PREVIEW_RECT = { + x: 0, + y: 0, + left: 0, + top: 0, + right: 800, + bottom: 600, + width: 800, + height: 600, + toJSON: () => PREVIEW_RECT, +} as DOMRect; + +let previewRect = PREVIEW_RECT; + +function createCanvas( + overrides: Partial = {}, +): UiEditorCanvasProjection { + return { + isLocked: false, + activeImage, + activeImageId: 'page-1', + uiTrees: [{ src_ui_design: 'page-1', root }], + previewUrls: { 'page-1': 'data:image/png;base64,' }, + images: { 'page-1': activeImage }, + sprites: {}, + fontFaces: {}, + tree: { src_ui_design: 'page-1', root }, + selectedNode: null, + selectedNodeId: null, + keepChildrenUnchanged: false, + hiddenNodeIds: new Set(), + focusRequest: null, + status: null, + isNodePreviewVisible: vi.fn(() => true), + toggleNodePreviewVisibility: vi.fn(), + selectExclusiveChild: vi.fn(), + selectNode: vi.fn(), + clearNodeSelection: vi.fn(), + updateNodeTransform: vi.fn(), + insertNode: vi.fn(), + insertNodeAfter: vi.fn(), + deleteNode: vi.fn(), + setTreeOffset: vi.fn(), + openClearDialog: vi.fn(), + ...overrides, + }; +} + +function renderPreview() { + const canvas = createCanvas(); + const rendered = render( + , + ); + const preview = screen.getByRole('region', { name: 'UI 预览画布' }); + const child = rendered.container.querySelector( + '[data-node-id="child"]', + ) as HTMLDivElement; + return { canvas, child, preview, ...rendered }; +} + +/** 世界图层的位移，用来断言一个手势到底有没有平移视口。 */ +function worldTranslate(container: HTMLElement) { + const world = container.querySelector( + '.genarrative-image-canvas__world', + ) as HTMLElement; + const match = /translate\(([-\d.]+)px, ([-\d.]+)px\)/.exec( + world.style.transform, + ); + if (!match) throw new Error('无法从 world 读取视口位移'); + return { x: Number(match[1]), y: Number(match[2]) }; +} + +/** + * jsdom 没有 PointerEvent，`fireEvent` 也不会带 pointerId； + * 这里手工派发带 pointerId 的指针事件，让"指针 id 不匹配"这类分支被真实覆盖。 + */ +function dispatchPointer( + target: Element, + type: 'pointerdown' | 'pointermove' | 'pointerup' | 'pointercancel', + { + button = 0, + buttons, + clientX, + clientY, + pointerId, + }: { + button?: number; + buttons?: number; + clientX: number; + clientY: number; + pointerId: number; + }, +) { + const event = new MouseEvent(type, { + bubbles: true, + cancelable: true, + button, + buttons: buttons ?? DEFAULT_BUTTONS[button] ?? 1, + clientX, + clientY, + }); + Object.defineProperty(event, 'pointerId', { value: pointerId }); + act(() => { + target.dispatchEvent(event); + }); + return event.defaultPrevented; +} + +beforeEach(() => { + previewRect = PREVIEW_RECT; + vi.stubGlobal('ResizeObserver', TestResizeObserver); + Object.assign(Element.prototype, { + setPointerCapture: vi.fn(), + hasPointerCapture: vi.fn(() => true), + releasePointerCapture: vi.fn(), + }); + vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation( + () => previewRect, + ); +}); + +afterEach(() => { + cleanup(); + vi.unstubAllGlobals(); + vi.restoreAllMocks(); +}); + +describe('PreviewWorkspace tree drag', () => { + function renderTreeDrag() { + const rendered = renderPreview(); + const treeLayer = rendered.container.querySelector( + '[data-tree-id]', + ) as HTMLDivElement; + const rootNode = treeLayer.querySelector( + '[data-node-id="root"]', + ) as HTMLDivElement; + return { ...rendered, rootNode, treeLayer }; + } + + it('commits the tree offset on pointerup but not on pointercancel', () => { + const committed = renderTreeDrag(); + dispatchPointer(committed.rootNode, 'pointerdown', { + button: 0, + clientX: 10, + clientY: 10, + pointerId: 11, + }); + // 指针捕获在树容器上，后续指针事件由浏览器派发给捕获元素。 + dispatchPointer(committed.treeLayer, 'pointermove', { + clientX: 40, + clientY: 50, + pointerId: 11, + }); + dispatchPointer(committed.treeLayer, 'pointerup', { + button: 0, + clientX: 40, + clientY: 50, + pointerId: 11, + }); + expect(committed.canvas.setTreeOffset).toHaveBeenCalledTimes(1); + expect(committed.canvas.setTreeOffset.mock.calls[0]?.[0]).toBe('page-1'); + cleanup(); + + const cancelled = renderTreeDrag(); + dispatchPointer(cancelled.rootNode, 'pointerdown', { + button: 0, + clientX: 10, + clientY: 10, + pointerId: 12, + }); + dispatchPointer(cancelled.treeLayer, 'pointermove', { + clientX: 40, + clientY: 50, + pointerId: 12, + }); + dispatchPointer(cancelled.treeLayer, 'pointercancel', { + button: 0, + clientX: 40, + clientY: 50, + pointerId: 12, + }); + expect(cancelled.canvas.setTreeOffset).not.toHaveBeenCalled(); + }); + + it('drops an in-flight tree drag when the window loses focus', () => { + const { canvas, rootNode, treeLayer } = renderTreeDrag(); + dispatchPointer(rootNode, 'pointerdown', { + button: 0, + clientX: 10, + clientY: 10, + pointerId: 13, + }); + dispatchPointer(treeLayer, 'pointermove', { + clientX: 40, + clientY: 50, + pointerId: 13, + }); + + act(() => { + window.dispatchEvent(new Event('blur')); + }); + dispatchPointer(treeLayer, 'pointerup', { + button: 0, + clientX: 40, + clientY: 50, + pointerId: 13, + }); + + expect(canvas.setTreeOffset).not.toHaveBeenCalled(); + }); + + describe('PreviewWorkspace right-button pan', () => { + it('pans the viewport on a right drag and never opens the node menu', () => { + const { canvas, child, container, preview } = renderPreview(); + const before = worldTranslate(container); + + dispatchPointer(child, 'pointerdown', { + button: 2, + clientX: 100, + clientY: 100, + pointerId: 5, + }); + expect(preview.classList.contains(PANNING_CLASS)).toBe(false); + expect( + fireEvent.contextMenu(child, { + button: 2, + buttons: 2, + clientX: 100, + clientY: 100, + }), + ).toBe(false); + + dispatchPointer(child, 'pointermove', { + clientX: 101, + clientY: 100, + pointerId: 5, + }); + expect(preview.classList.contains(PANNING_CLASS)).toBe(false); + expect(worldTranslate(container)).toEqual(before); + + dispatchPointer(child, 'pointermove', { + clientX: 500, + clientY: 500, + pointerId: 99, + }); + expect(worldTranslate(container)).toEqual(before); + + dispatchPointer(child, 'pointermove', { + clientX: 130, + clientY: 140, + pointerId: 5, + }); + expect(preview.classList.contains(PANNING_CLASS)).toBe(true); + expect(worldTranslate(container)).toEqual({ + x: before.x + 30, + y: before.y + 40, + }); + + dispatchPointer(child, 'pointerup', { + button: 2, + clientX: 130, + clientY: 140, + pointerId: 5, + }); + expect(screen.queryByRole('menu')).toBeNull(); + expect(canvas.selectNode).not.toHaveBeenCalled(); + expect(canvas.clearNodeSelection).not.toHaveBeenCalled(); + expect(preview.classList.contains(PANNING_CLASS)).toBe(false); + }); + + it('treats a right press under the drag threshold as a node menu click', () => { + const { canvas, child, preview } = renderPreview(); + + dispatchPointer(child, 'pointerdown', { + button: 2, + clientX: 100, + clientY: 100, + pointerId: 6, + }); + dispatchPointer(child, 'pointermove', { + clientX: 101, + clientY: 100, + pointerId: 6, + }); + expect(preview.classList.contains(PANNING_CLASS)).toBe(false); + dispatchPointer(child, 'pointerup', { + button: 2, + clientX: 101, + clientY: 100, + pointerId: 6, + }); + + expect(canvas.selectNode).toHaveBeenCalledWith('child'); + expect(screen.getByRole('menu').style.left).toBe('101px'); + expect( + screen.getByRole('menuitem', { name: '新增同级节点' }), + ).toBeTruthy(); + }); + + it('opens the node menu when pointerup is retargeted to the capture element', () => { + const { canvas, child, preview } = renderPreview(); + + dispatchPointer(child, 'pointerdown', { + button: 2, + clientX: 100, + clientY: 100, + pointerId: 7, + }); + // 指针被视口捕获后，浏览器把后续指针事件派发给捕获元素：抬起目标不再是节点， + // 菜单必须按按下时的命中目标裁决。 + dispatchPointer(preview, 'pointerup', { + button: 2, + clientX: 101, + clientY: 100, + pointerId: 7, + }); + + expect(canvas.selectNode).toHaveBeenCalledWith('child'); + expect(screen.getByRole('menu')).toBeTruthy(); + }); + + it('keeps an empty-grid right click silent, unlike the left button', () => { + const { canvas, preview } = renderPreview(); + + dispatchPointer(preview, 'pointerdown', { + button: 2, + clientX: 300, + clientY: 200, + pointerId: 7, + }); + dispatchPointer(preview, 'pointerup', { + button: 2, + clientX: 300, + clientY: 200, + pointerId: 7, + }); + + expect(screen.queryByRole('menu')).toBeNull(); + expect(canvas.selectNode).not.toHaveBeenCalled(); + expect(canvas.clearNodeSelection).not.toHaveBeenCalled(); + + dispatchPointer(preview, 'pointerdown', { + clientX: 300, + clientY: 200, + pointerId: 8, + }); + expect(canvas.clearNodeSelection).toHaveBeenCalledTimes(1); + }); + + it('does not open the node menu when a clean right press ends outside the preview', () => { + const { canvas, child } = renderPreview(); + previewRect = { ...PREVIEW_RECT, right: 200, bottom: 200 } as DOMRect; + + dispatchPointer(child, 'pointerdown', { + button: 2, + clientX: 300, + clientY: 200, + pointerId: 9, + }); + dispatchPointer(child, 'pointerup', { + button: 2, + clientX: 300, + clientY: 200, + pointerId: 9, + }); + + expect(screen.queryByRole('menu')).toBeNull(); + expect(canvas.selectNode).not.toHaveBeenCalled(); + }); + + it('keeps the non-right-button context menu path immediate', () => { + const { canvas, child } = renderPreview(); + + fireEvent.contextMenu(child, { button: 0, clientX: 40, clientY: 50 }); + + expect(canvas.selectNode).toHaveBeenCalledWith('child'); + expect(screen.getByRole('menu')).toBeTruthy(); + }); + + it('leaves the keyboard menu key to the existing node menu path', () => { + const { canvas, child } = renderPreview(); + + dispatchPointer(child, 'pointerdown', { + button: 2, + clientX: 100, + clientY: 100, + pointerId: 13, + }); + // 键盘菜单键在 Chromium 上报 button: -1，不能被右键手势的拦截窗口吃掉。 + expect(fireEvent.contextMenu(child, { button: -1 })).toBe(false); + expect(canvas.selectNode).toHaveBeenCalledWith('child'); + expect(screen.getByRole('menu')).toBeTruthy(); + }); + + it('keeps middle-button panning and its shared grabbing cursor', () => { + const { container, preview } = renderPreview(); + const before = worldTranslate(container); + + dispatchPointer(preview, 'pointerdown', { + button: 1, + clientX: 100, + clientY: 100, + pointerId: 10, + }); + expect(preview.classList.contains(PANNING_CLASS)).toBe(true); + dispatchPointer(preview, 'pointermove', { + clientX: 120, + clientY: 90, + pointerId: 10, + }); + expect(worldTranslate(container)).toEqual({ + x: before.x + 20, + y: before.y - 10, + }); + dispatchPointer(preview, 'pointerup', { + button: 1, + clientX: 120, + clientY: 90, + pointerId: 10, + }); + expect(preview.classList.contains(PANNING_CLASS)).toBe(false); + }); + + it('still drags nodes with the left button after a right-drag pan', () => { + const { canvas, child } = renderPreview(); + + dispatchPointer(child, 'pointerdown', { + button: 2, + clientX: 100, + clientY: 100, + pointerId: 11, + }); + dispatchPointer(child, 'pointermove', { + clientX: 140, + clientY: 100, + pointerId: 11, + }); + dispatchPointer(child, 'pointerup', { + button: 2, + clientX: 140, + clientY: 100, + pointerId: 11, + }); + expect(canvas.updateNodeTransform).not.toHaveBeenCalled(); + + dispatchPointer(child, 'pointerdown', { + clientX: 100, + clientY: 100, + pointerId: 12, + }); + dispatchPointer(child, 'pointermove', { + clientX: 110, + clientY: 100, + pointerId: 12, + }); + dispatchPointer(child, 'pointerup', { + clientX: 110, + clientY: 100, + pointerId: 12, + }); + + expect(canvas.updateNodeTransform).toHaveBeenCalledTimes(1); + }); + }); +}); diff --git a/apps/ai-game-creator-shell/tests/previewRightPanGesture.test.ts b/apps/ai-game-creator-shell/tests/previewRightPanGesture.test.ts new file mode 100644 index 000000000..866d706f1 --- /dev/null +++ b/apps/ai-game-creator-shell/tests/previewRightPanGesture.test.ts @@ -0,0 +1,106 @@ +import { describe, expect, it } from 'vitest'; + +import { + createPreviewRightPanGesture, + movePreviewRightPanGesture, + resolvePreviewRightPanRelease, + shouldInterceptRightContextMenu, +} from '../src/view/ui-editor/components/preview/previewRightPanGesture'; + +const startViewport = { x: 10, y: -20, scale: 0.75 }; + +function pressAt(x: number, y: number) { + return createPreviewRightPanGesture({ + pointerId: 7, + pointer: { x, y }, + viewport: startViewport, + }); +} + +describe('preview right-button pan gesture', () => { + it('starts as a click until the pointer passes the drag threshold', () => { + const gesture = pressAt(100, 100); + + expect(gesture.panning).toBe(false); + expect(movePreviewRightPanGesture(gesture, { x: 101, y: 100 })).toBe( + gesture, + ); + expect( + movePreviewRightPanGesture(gesture, { x: 102, y: 100 }).panning, + ).toBe(true); + }); + + it('keeps panning once engaged, even when the pointer returns to the start', () => { + const engaged = movePreviewRightPanGesture(pressAt(100, 100), { + x: 130, + y: 140, + }); + + expect(engaged.panning).toBe(true); + expect( + movePreviewRightPanGesture(engaged, { x: 100, y: 100 }).panning, + ).toBe(true); + }); + + it('pans by the full delta from the press point without touching the scale', () => { + const gesture = movePreviewRightPanGesture(pressAt(100, 100), { + x: 140, + y: 70, + }); + const release = resolvePreviewRightPanRelease({ + gesture, + pointer: { x: 140, y: 70 }, + isInsidePreview: true, + }); + + expect(release.viewport).toEqual({ x: 50, y: -50, scale: 0.75 }); + expect(release.openNodeMenu).toBe(false); + }); + + it('opens the node menu only for a clean release inside the preview', () => { + const gesture = pressAt(100, 100); + + expect( + resolvePreviewRightPanRelease({ + gesture, + pointer: { x: 101, y: 100 }, + isInsidePreview: true, + }), + ).toEqual({ viewport: null, openNodeMenu: true }); + + expect( + resolvePreviewRightPanRelease({ + gesture, + pointer: { x: 101, y: 100 }, + isInsidePreview: false, + }), + ).toEqual({ viewport: null, openNodeMenu: false }); + }); + + it('intercepts only the right button of the preview right-press sequence', () => { + expect( + shouldInterceptRightContextMenu({ + button: 2, + withinRightPressSequence: true, + }), + ).toBe(true); + expect( + shouldInterceptRightContextMenu({ + button: 2, + withinRightPressSequence: false, + }), + ).toBe(false); + expect( + shouldInterceptRightContextMenu({ + button: 0, + withinRightPressSequence: true, + }), + ).toBe(false); + expect( + shouldInterceptRightContextMenu({ + button: -1, + withinRightPressSequence: true, + }), + ).toBe(false); + }); +}); diff --git a/apps/ai-game-creator-shell/tests/previewWorkspaceZoom.test.tsx b/apps/ai-game-creator-shell/tests/previewWorkspaceZoom.test.tsx index 92abe5778..3fdd46a61 100644 --- a/apps/ai-game-creator-shell/tests/previewWorkspaceZoom.test.tsx +++ b/apps/ai-game-creator-shell/tests/previewWorkspaceZoom.test.tsx @@ -5,6 +5,10 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import type { Node as UiNode } from '../src/features/ui-editor/types/Node'; import type { UIDesignImage } from '../src/features/ui-editor/types/UIDesignImage'; +import { + PREVIEW_GRID_BASE_STEP, + resolvePreviewGridStep, +} from '../src/view/ui-editor/components/preview/previewGrid'; import { PreviewWorkspace } from '../src/view/ui-editor/components/preview/PreviewWorkspace'; import type { UiEditorCanvasProjection } from '../src/view/ui-editor/useUiEditorPage'; @@ -41,15 +45,13 @@ const root: UiNode = { component: null, children_display_mode: 'Stack', children: [], + offset: { + min: [0, 0], + max: [1200, 800], + }, }; const activeImage: UIDesignImage = { - metadata: { - name: '测试界面', - description: '', - role: null, - slave_to: null, - }, path: 'assets/page.png', pixel_size: [1200, 800], pixels_per_unit: 1, @@ -62,6 +64,7 @@ function createCanvas( isLocked: false, activeImage, activeImageId: 'page-1', + uiTrees: [{ src_ui_design: 'page-1', root }], previewUrls: { 'page-1': 'data:image/png;base64,' }, images: { 'page-1': activeImage }, sprites: {}, @@ -111,6 +114,38 @@ afterEach(() => { }); describe('PreviewWorkspace quick zoom', () => { + it('chooses doubled or halved world steps to keep the grid readable', () => { + expect(resolvePreviewGridStep(1)).toBe(PREVIEW_GRID_BASE_STEP); + expect(resolvePreviewGridStep(0.5)).toBe(56); + expect(resolvePreviewGridStep(0.125)).toBe(224); + expect(resolvePreviewGridStep(2)).toBe(14); + expect(resolvePreviewGridStep(4)).toBe(7); + + for (const scale of [0.125, 0.25, 0.5, 1, 2, 4, 8]) { + const spacing = resolvePreviewGridStep(scale) * scale; + expect(spacing).toBeGreaterThanOrEqual(20); + expect(spacing).toBeLessThan(40); + } + }); + + it('falls back to the base step when the screen spacing overflows', () => { + // 溢出成 Infinity 时步长无法收敛：必须直接回基础步长，不能死循环。 + expect(resolvePreviewGridStep(Number.MAX_VALUE)).toBe( + PREVIEW_GRID_BASE_STEP, + ); + }); + + it('applies the adaptive screen-space spacing to the preview background', () => { + const rendered = render(); + const preview = screen.getByRole('region', { name: 'UI 预览画布' }); + const scale = logicalViewportScale(rendered.container); + const [backgroundWidth] = preview.style.backgroundSize.split('px'); + + expect(Number(backgroundWidth)).toBeCloseTo( + resolvePreviewGridStep(scale) * scale, + ); + }); + it('uses the toolbar zoom step while the preview is hovered', () => { const rendered = render(); const preview = screen.getByRole('region', { name: 'UI 预览画布' }); diff --git a/apps/ai-game-creator-shell/tests/stageStatusOverview.test.ts b/apps/ai-game-creator-shell/tests/stageStatusOverview.test.ts index 8e7389b02..b7677ead3 100644 --- a/apps/ai-game-creator-shell/tests/stageStatusOverview.test.ts +++ b/apps/ai-game-creator-shell/tests/stageStatusOverview.test.ts @@ -95,4 +95,34 @@ describe('stageStatusOverview', () => { 'review-a', ); }); + + it('uses the tree and node ids together when node ids repeat across trees', () => { + const duplicateTargets = [ + { treeId: 'page-a', node: node('same', { NeedReview: 'A' }) }, + { treeId: 'page-b', node: node('same', { NeedReview: 'B' }) }, + { treeId: 'page-c', node: node('same', { NeedReview: 'C' }) }, + ]; + + expect(getNextUiTreeNodeTarget(duplicateTargets, null)?.treeId).toBe( + 'page-a', + ); + expect( + getNextUiTreeNodeTarget(duplicateTargets, { + treeId: 'page-a', + nodeId: 'same', + })?.treeId, + ).toBe('page-b'); + expect( + getNextUiTreeNodeTarget(duplicateTargets, { + treeId: 'page-b', + nodeId: 'same', + })?.treeId, + ).toBe('page-c'); + expect( + getNextUiTreeNodeTarget(duplicateTargets, { + treeId: 'page-c', + nodeId: 'same', + })?.treeId, + ).toBe('page-a'); + }); }); diff --git a/apps/ai-game-creator-shell/tests/uiDesignResourceBridge.test.ts b/apps/ai-game-creator-shell/tests/uiDesignResourceBridge.test.ts index 42d2f5003..e7b65929c 100644 --- a/apps/ai-game-creator-shell/tests/uiDesignResourceBridge.test.ts +++ b/apps/ai-game-creator-shell/tests/uiDesignResourceBridge.test.ts @@ -1,201 +1,43 @@ import { describe, expect, it, vi } from 'vitest'; -import type { - GameCreationAppAssetManifestEntry, - GameCreationAppManifest, -} from '../../../packages/shared/src/contracts/gameCreationApp'; -import { - GAME_CREATION_APP_UI_DESIGN_DOC_ASSET_KIND, - GAME_CREATION_APP_UI_DESIGN_DOC_MEDIA_TYPE, -} from '../../../packages/shared/src/contracts/gameCreationApp'; -import { - ensureUiDesignResourceForPrototype, - findLinkedUiDesignResource, -} from '../src/features/ui-editor/uiDesignResourceBridge'; - -function manifestWithPrototype(): GameCreationAppManifest { - const prototype: GameCreationAppAssetManifestEntry = { - id: 'prototype-asset', - kind: 'ui-design', - mediaType: 'image/png', - localPath: 'assets/ui-prototype.png', - source: { kind: 'canvas', referenceResourceIds: [] }, - imageSequenceFrames: null, - imageSequenceDurationMs: null, - }; - return { - schemaVersion: 'game-creator-app.v1', - projectId: 'project-1', - projectName: 'UI bridge', - tasks: [], - assets: [prototype], - versions: [], - godotProjectRoot: null, - preview: null, - resourceCanvasLayouts: [], - } as unknown as GameCreationAppManifest; -} +import { createUiDesignDocFromImages } from '../src/features/ui-editor/uiDesignResourceBridge'; describe('ui design resource bridge', () => { - it('finds only a JSON UI resource linked to the exact prototype asset', () => { - const manifest = manifestWithPrototype(); - manifest.assets.push({ - id: 'unrelated-ui', - kind: GAME_CREATION_APP_UI_DESIGN_DOC_ASSET_KIND, - mediaType: GAME_CREATION_APP_UI_DESIGN_DOC_MEDIA_TYPE, - localPath: 'ui/unrelated.json', - source: { kind: 'generated', referenceResourceIds: ['other'] }, - imageSequenceFrames: null, - imageSequenceDurationMs: null, - }); - expect(findLinkedUiDesignResource(manifest, 'prototype-asset')).toBeNull(); - manifest.assets.push({ - id: 'linked-ui', - kind: GAME_CREATION_APP_UI_DESIGN_DOC_ASSET_KIND, - mediaType: GAME_CREATION_APP_UI_DESIGN_DOC_MEDIA_TYPE, - localPath: 'ui/linked.json', - source: { kind: 'generated', referenceResourceIds: ['prototype-asset'] }, - imageSequenceFrames: null, - imageSequenceDurationMs: null, - }); - expect(findLinkedUiDesignResource(manifest, 'prototype-asset')?.id).toBe( - 'linked-ui', - ); - }); - - it('reuses workflow resources linked by the prototype canonical resource id', () => { - const manifest = manifestWithPrototype(); - manifest.assets[0]!.source.resourceId = 'canvas-resource-1'; - manifest.assets.push({ - id: 'workflow-ui', - kind: GAME_CREATION_APP_UI_DESIGN_DOC_ASSET_KIND, - mediaType: GAME_CREATION_APP_UI_DESIGN_DOC_MEDIA_TYPE, - localPath: 'ui/workflow.json', - source: { - kind: 'generated', - resourceId: 'ui-workflow-page-1', - referenceResourceIds: ['canvas-resource-1', 'design-resource-1'], - }, - imageSequenceFrames: null, - imageSequenceDurationMs: null, - }); - expect(findLinkedUiDesignResource(manifest, 'prototype-asset')?.id).toBe( - 'workflow-ui', - ); - }); - - it('prefers a completed workflow resource when an older bridge resource also matches', () => { - const manifest = manifestWithPrototype(); - manifest.assets.push( - { - id: 'bridge-ui', - kind: GAME_CREATION_APP_UI_DESIGN_DOC_ASSET_KIND, - mediaType: GAME_CREATION_APP_UI_DESIGN_DOC_MEDIA_TYPE, - localPath: 'ui/UI 设计 1.json', - source: { - kind: 'generated', - referenceResourceIds: ['prototype-asset'], - }, - imageSequenceFrames: null, - imageSequenceDurationMs: null, - }, - { - id: 'completed-ui', - kind: GAME_CREATION_APP_UI_DESIGN_DOC_ASSET_KIND, - mediaType: GAME_CREATION_APP_UI_DESIGN_DOC_MEDIA_TYPE, - localPath: 'ui/ui-workflow-page.json', - source: { - kind: 'generated', - generationKind: 'ui-workflow.completed', - referenceResourceIds: ['prototype-asset'], - }, - imageSequenceFrames: null, - imageSequenceDurationMs: null, - }, - ); - expect(findLinkedUiDesignResource(manifest, 'prototype-asset')?.id).toBe( - 'completed-ui', - ); - }); - - it('reuses an existing link without invoking a mutating command', async () => { - const manifest = manifestWithPrototype(); - const linked = { - id: 'linked-ui', - kind: GAME_CREATION_APP_UI_DESIGN_DOC_ASSET_KIND, - mediaType: GAME_CREATION_APP_UI_DESIGN_DOC_MEDIA_TYPE, - localPath: 'ui/linked.json', - source: { - kind: 'generated' as const, - referenceResourceIds: ['prototype-asset'], - }, - imageSequenceFrames: null, - imageSequenceDurationMs: null, - }; - manifest.assets.push(linked); + it('rejects an empty image list without invoking the command', async () => { const invoke = vi.fn(); - const result = await ensureUiDesignResourceForPrototype({ + await expect( + createUiDesignDocFromImages({ + projectPath: '/project', + expectedProjectId: 'project-1', + images: [], + invoke, + }), + ).rejects.toThrow('请至少选择一张界面图'); + expect(invoke).not.toHaveBeenCalled(); + }); + + it('creates a document through the command with the project identity injected', async () => { + const created = { + asset: { id: 'ui-1' }, + manifest: { projectId: 'project-1' }, + relativePath: 'ui/UI 设计 1.json', + imageIds: ['image-a'], + committedProjectRevision: 7, + }; + const invoke = vi.fn().mockResolvedValue(created); + const result = await createUiDesignDocFromImages({ projectPath: '/project', - manifest, - prototypeAssetId: 'prototype-asset', + expectedProjectId: 'project-1', + images: [{ assetId: 'image-a', path: null }], invoke, }); - expect(result.asset).toEqual(linked); - expect(result.created).toBe(false); - expect(invoke).not.toHaveBeenCalled(); - }); - - it('invokes the atomic Tauri bridge for a missing link', async () => { - const manifest = manifestWithPrototype(); - const result = { - asset: { - id: 'new-ui', - kind: GAME_CREATION_APP_UI_DESIGN_DOC_ASSET_KIND, - mediaType: GAME_CREATION_APP_UI_DESIGN_DOC_MEDIA_TYPE, - localPath: 'ui/UI 设计 1.json', - source: { - kind: 'generated' as const, - referenceResourceIds: ['prototype-asset'], - }, - imageSequenceFrames: null, - imageSequenceDurationMs: null, - }, - manifest: { ...manifest, assets: [...manifest.assets] }, - committedProjectRevision: 7, - created: true, - }; - const invoke = vi.fn().mockResolvedValue(result); - await expect( - ensureUiDesignResourceForPrototype({ + expect(invoke).toHaveBeenCalledWith('create_ui_design_doc_from_images', { + input: { projectPath: '/project', - manifest, - prototypeAssetId: ' prototype-asset ', - invoke, - }), - ).resolves.toEqual(result); - expect(invoke).toHaveBeenCalledWith( - 'ensure_ui_design_resource_for_prototype', - { - input: { - projectPath: '/project', - expectedProjectId: 'project-1', - prototypeAssetId: 'prototype-asset', - }, + expectedProjectId: 'project-1', + images: [{ assetId: 'image-a', path: null }], }, - ); - }); - - it('rejects non-prototype assets before invoking Tauri', async () => { - const manifest = manifestWithPrototype(); - const invoke = vi.fn(); - await expect( - ensureUiDesignResourceForPrototype({ - projectPath: '/project', - manifest, - prototypeAssetId: 'missing', - invoke, - }), - ).rejects.toThrow('目标资源不是 UI 原型图片'); - expect(invoke).not.toHaveBeenCalled(); + }); + expect(result).toBe(created); }); }); diff --git a/apps/ai-game-creator-shell/tests/uiDesignSuggestions.test.ts b/apps/ai-game-creator-shell/tests/uiDesignSuggestions.test.ts deleted file mode 100644 index 4f16f2ec4..000000000 --- a/apps/ai-game-creator-shell/tests/uiDesignSuggestions.test.ts +++ /dev/null @@ -1,93 +0,0 @@ -import { describe, expect, it } from 'vitest'; - -import type { State } from '../src/features/ui-editor/types/State'; -import { applyUiDesignSuggestions } from '../src/features/ui-editor/uiDesignSuggestions'; - -function state(): State { - return { - ui_trees: [], - sprite_assets: {}, - font_assets: {}, - ui_design_images: { - page: { - metadata: { name: '', description: '', role: null, slave_to: null }, - path: 'page.png', - pixel_size: [100, 100], - pixels_per_unit: 1, - }, - section: { - metadata: { - name: '已有名称', - description: '', - role: 'Section', - slave_to: null, - }, - path: 'section.png', - pixel_size: [100, 100], - pixels_per_unit: 1, - }, - detail: { - metadata: { - name: '', - description: '已有描述', - role: null, - slave_to: null, - }, - path: 'detail.png', - pixel_size: [100, 100], - pixels_per_unit: 1, - }, - }, - }; -} - -describe('applyUiDesignSuggestions', () => { - it('masks existing metadata and maps descendants to their owning Page', () => { - const before = state(); - const after = applyUiDesignSuggestions(before, [ - { - id: 'page', - name: '主页面', - description: '页面描述', - role: 'Page', - children: [ - { - id: 'section', - name: '模型名称不应覆盖', - description: '页签描述', - role: 'Section', - children: [ - { - id: 'detail', - name: '详情', - description: '模型描述不应覆盖', - role: 'Detail', - children: [], - }, - ], - }, - ], - }, - ]); - - expect(after.ui_design_images.page.metadata).toEqual({ - name: '主页面', - description: '页面描述', - role: 'Page', - slave_to: null, - }); - expect(after.ui_design_images.section.metadata).toEqual({ - name: '已有名称', - description: '页签描述', - role: 'Section', - slave_to: 'page', - }); - expect(after.ui_design_images.detail.metadata).toEqual({ - name: '详情', - description: '已有描述', - role: 'Detail', - slave_to: 'page', - }); - expect(before.ui_design_images.page.metadata.name).toBe(''); - }); -}); diff --git a/apps/ai-game-creator-shell/tests/uiEditorKeyboardShortcuts.test.ts b/apps/ai-game-creator-shell/tests/uiEditorKeyboardShortcuts.test.ts index f21c284db..4e7237c6c 100644 --- a/apps/ai-game-creator-shell/tests/uiEditorKeyboardShortcuts.test.ts +++ b/apps/ai-game-creator-shell/tests/uiEditorKeyboardShortcuts.test.ts @@ -25,7 +25,6 @@ describe('ui editor keyboard shortcuts', () => { const listener = (event: KeyboardEvent) => handleUiEditorKeyDown(event, { selectedNodeId: null, - activeImageId: null, deleteNode: vi.fn(), historyUndo, historyRedo, @@ -47,7 +46,6 @@ describe('ui editor keyboard shortcuts', () => { const listener = (event: KeyboardEvent) => handleUiEditorKeyDown(event, { selectedNodeId: null, - activeImageId: null, deleteNode: vi.fn(), historyUndo, historyRedo, @@ -70,7 +68,6 @@ describe('ui editor keyboard shortcuts', () => { const listener = (event: KeyboardEvent) => handleUiEditorKeyDown(event, { selectedNodeId: 'node-1', - activeImageId: 'page-1', deleteNode, historyUndo: vi.fn(() => true), historyRedo: vi.fn(() => true), @@ -93,7 +90,6 @@ describe('ui editor keyboard shortcuts', () => { const listener = (event: KeyboardEvent) => handleUiEditorKeyDown(event, { selectedNodeId: 'node-1', - activeImageId: 'page-1', deleteNode, historyUndo: vi.fn(() => true), historyRedo: vi.fn(() => true), @@ -103,7 +99,7 @@ describe('ui editor keyboard shortcuts', () => { fireEvent.click(zoomIn); fireEvent.keyDown(window, { key: 'Delete' }); - expect(deleteNode).toHaveBeenCalledWith('node-1', 'page-1'); + expect(deleteNode).toHaveBeenCalledWith('node-1'); window.removeEventListener('keydown', listener); }); }); diff --git a/apps/ai-game-creator-shell/tests/uiEditorPage.test.ts b/apps/ai-game-creator-shell/tests/uiEditorPage.test.ts index 503d02003..7f82030a4 100644 --- a/apps/ai-game-creator-shell/tests/uiEditorPage.test.ts +++ b/apps/ai-game-creator-shell/tests/uiEditorPage.test.ts @@ -14,6 +14,10 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; vi.mock('@tauri-apps/api/core', () => ({ invoke: vi.fn() })); +vi.mock('@tauri-apps/plugin-clipboard-manager', () => ({ + writeText: vi.fn(), +})); + vi.mock('../src/components/AssetImporter', () => ({ AssetImporter: ({ open }: { open: boolean }) => open ? createElement('div', { role: 'dialog' }, '素材导入器') : null, @@ -25,6 +29,7 @@ vi.mock('../src/components/modal/ThemedModal', () => ({ })); import { invoke } from '@tauri-apps/api/core'; +import { writeText } from '@tauri-apps/plugin-clipboard-manager'; import type { Node as UiNode } from '../src/features/ui-editor/types/Node'; import type { State } from '../src/features/ui-editor/types/State'; @@ -98,12 +103,6 @@ function stateWithPages(pageIds: string[]): State { pageIds.map((id) => [ id, { - metadata: { - name: id, - description: '', - role: 'Page', - slave_to: null, - }, path: `assets/${id}.png`, pixel_size: [320, 180], pixels_per_unit: 1, @@ -357,10 +356,6 @@ describe('UiEditorPage', () => { it('renders the overview that belongs to the active workflow stage', () => { render(createElement(UiEditorPage, { projectPath: '/tmp/ui-editor' })); - expect(screen.getByRole('heading', { name: '导入概览' })).toBeTruthy(); - - fireEvent.click(screen.getByRole('button', { name: /识别界面结构/ })); - fireEvent.click(screen.getByRole('button', { name: '仍然继续' })); expect(screen.getByRole('heading', { name: '识别概览' })).toBeTruthy(); fireEvent.click(screen.getByRole('button', { name: /自动切分素材/ })); @@ -386,7 +381,7 @@ describe('UiEditorPage', () => { resourceId: 'ui-resource', stateStore, initialStep: 'asset-separation', - initialFurthestStepIndex: 2, + initialFurthestStepIndex: 1, }), ); @@ -411,6 +406,116 @@ describe('UiEditorPage', () => { ).toBeNull(); }); + it('restarts inspector animation for every item in a multi-item cycle', async () => { + const state = stateWithPages(['page']); + state.ui_trees[0]!.root.children = [ + node('review-a'), + node('review-b'), + node('review-c'), + ]; + for (const [index, child] of state.ui_trees[0]!.root.children.entries()) { + child.metadata.layout_status = { NeedReview: `请检查 ${index}` }; + } + const stateStore: IUiDesignStateStore = { + load: vi.fn().mockResolvedValue({ revision: 0, state }), + save: vi.fn(), + generateCode: vi.fn().mockRejectedValue(new Error('测试未配置代码生成')), + }; + const scrollSpy = vi.fn(); + Object.defineProperty(Element.prototype, 'scrollIntoView', { + configurable: true, + value: scrollSpy, + }); + const cancel = vi.fn(); + const play = vi.fn(); + const getAnimationsSpy = vi.fn(() => [ + { + animationName: 'ui-editor-status-attention-arrive', + cancel, + play, + } as unknown as Animation, + ]); + Object.defineProperty(Element.prototype, 'getAnimations', { + configurable: true, + value: getAnimationsSpy, + }); + try { + render( + createElement(UiEditorPage, { + projectPath: '/tmp/ui-editor-cycle-animation', + resourceId: 'ui-resource', + stateStore, + initialStep: 'structure-recognition', + initialFurthestStepIndex: 0, + }), + ); + const button = await screen.findByRole('button', { + name: '待用户检查 3，定位下一项', + }); + for (const reason of ['请检查 0', '请检查 1', '请检查 2', '请检查 0']) { + fireEvent.click(button); + await screen.findByText(reason); + } + expect(getAnimationsSpy).toHaveBeenCalledTimes(4); + expect(cancel).toHaveBeenCalledTimes(4); + expect(play).toHaveBeenCalledTimes(4); + expect(scrollSpy).toHaveBeenCalledTimes(4); + } finally { + delete (Element.prototype as Element & { getAnimations?: unknown }) + .getAnimations; + delete (Element.prototype as Element & { scrollIntoView?: unknown }) + .scrollIntoView; + } + }); + + it('keeps the status highlight after the tree handles controlled selection', async () => { + const state = stateWithPages(['page']); + state.ui_trees[0]!.root.children = [ + node('review-a'), + node('review-b'), + node('review-c'), + ]; + for (const child of state.ui_trees[0]!.root.children) { + child.metadata.layout_status = { NeedReview: '请检查' }; + } + const stateStore: IUiDesignStateStore = { + load: vi.fn().mockResolvedValue({ revision: 0, state }), + save: vi.fn(), + generateCode: vi.fn().mockRejectedValue(new Error('测试未配置代码生成')), + }; + Object.defineProperty(Element.prototype, 'scrollIntoView', { + configurable: true, + value: vi.fn(), + }); + + render( + createElement(UiEditorPage, { + projectPath: '/tmp/ui-editor-cycle-highlight', + resourceId: 'ui-resource', + stateStore, + initialStep: 'structure-recognition', + initialFurthestStepIndex: 0, + }), + ); + + const button = await screen.findByRole('button', { + name: '待用户检查 3，定位下一项', + }); + try { + for (let index = 0; index < 4; index += 1) { + fireEvent.click(button); + await waitFor(() => { + expect( + document.querySelector('[data-status-attention]'), + ).not.toBeNull(); + }); + } + } finally { + delete (Element.prototype as Element & { scrollIntoView?: unknown }) + .scrollIntoView; + } + }); + it('switches tools freely without inventing completed workflow state', () => { render(createElement(UiEditorPage, { projectPath: '/tmp/ui-editor' })); @@ -491,6 +596,30 @@ describe('UiEditorPage', () => { expect(result.current.canvas.hiddenNodeIds.size).toBe(0); }); + it('deletes an inspector node from its own tree without an explicit tree id', async () => { + const { result } = await renderLoadedSession( + stateWithPages(['page-a', 'page-b']), + ); + let otherTreeNodeId: string | undefined; + act(() => { + const inserted = result.current.input.insertNode('page-b-root', 'page-b'); + if (inserted?.ok) otherTreeNodeId = inserted.value; + }); + expect(otherTreeNodeId).toBeTruthy(); + + // 选中非激活界面图里的节点：Inspector 删除按钮不给 treeId，必须落到它所在的树。 + act(() => result.current.input.selectDesignImage('page-a')); + act(() => result.current.input.selectNode(otherTreeNodeId!)); + act(() => result.current.inspector.deleteNode(otherTreeNodeId!)); + + const otherTree = result.current.canvas.uiTrees.find( + (tree) => tree.src_ui_design === 'page-b', + ); + expect(otherTree?.root.children.map((child) => child.id)).not.toContain( + otherTreeNodeId, + ); + }); + it('clears selection when deleting a node removes the selected descendant', async () => { const { result } = await renderLoadedSession(stateWithPages(['page'])); const rootId = 'page-root'; @@ -534,7 +663,9 @@ describe('UiEditorPage', () => { await screen.findByDisplayValue('page-child'); fireEvent.keyDown(window, { key: 'Delete' }); - await waitFor(() => expect(screen.queryByText('page-child')).toBeNull()); + await waitFor(() => + expect(screen.queryAllByText('page-child')).toHaveLength(0), + ); }); it('does not delete a selected node when Delete originates inside a dialog', async () => { @@ -709,17 +840,13 @@ describe('UiEditorPage', () => { fireEvent.click(await screen.findByRole('button', { name: '保存' })); fireEvent.click(await screen.findByRole('button', { name: '仍然保存' })); - expect((await screen.findByRole('alert')).textContent).toContain( + expect((await screen.findByRole('dialog')).textContent).toContain( '保存失败，请稍后重试。', ); - expect(screen.getByRole('alert').textContent).not.toContain( - '临时存储不可用', - ); - expect(screen.getByRole('button', { name: '保存' })).toBeTruthy(); + expect(screen.getByRole('button', { name: '重试保存' })).toBeTruthy(); expect(stateStore.save).toHaveBeenCalledTimes(1); - fireEvent.click(screen.getByRole('button', { name: '保存' })); - fireEvent.click(await screen.findByRole('button', { name: '仍然保存' })); + fireEvent.click(screen.getByRole('button', { name: '重试保存' })); expect(stateStore.save).toHaveBeenCalledTimes(2); }); @@ -743,10 +870,152 @@ describe('UiEditorPage', () => { fireEvent.click(await screen.findByRole('button', { name: '保存' })); fireEvent.click(await screen.findByRole('button', { name: '仍然保存' })); - expect((await screen.findByRole('alert')).textContent).toContain( + expect((await screen.findByRole('dialog')).textContent).toContain( '资源已在别处更新；请重新加载后再保存。', ); }); + + it('shows a generated path modal and copies the project-relative path', async () => { + const stateStore: IUiDesignStateStore = { + load: vi.fn().mockResolvedValue(structuredClone(EMPTY_SNAPSHOT)), + save: vi.fn().mockResolvedValue({ + status: 'saved', + state: structuredClone(EMPTY_SNAPSHOT.state), + revision: 1, + committedProjectRevision: 1, + }), + generateCode: vi.fn().mockResolvedValue({ + relativePath: 'ui/generated-example.js', + treeExports: ['Example'], + treeCount: 1, + nodeCount: 2, + }), + }; + vi.mocked(writeText).mockResolvedValue(undefined); + + render( + createElement(UiEditorPage, { + projectPath: '/tmp/ui-editor', + resourceId: 'ui-resource', + stateStore, + }), + ); + + fireEvent.click( + await screen.findByRole('button', { name: '保存并生成代码' }), + ); + fireEvent.click( + await screen.findByRole('button', { name: '仍然保存并生成' }), + ); + + const dialog = await screen.findByRole('dialog'); + expect(dialog.textContent).toContain('代码已生成'); + expect(dialog.textContent).toContain('ui/generated-example.js'); + + fireEvent.click(screen.getByRole('button', { name: '复制路径' })); + await waitFor(() => + expect(writeText).toHaveBeenCalledWith('ui/generated-example.js'), + ); + expect(screen.getByRole('button', { name: '已复制' })).toBeTruthy(); + }); + + it('shows a save-success modal without a generated path', async () => { + const stateStore: IUiDesignStateStore = { + load: vi.fn().mockResolvedValue(structuredClone(EMPTY_SNAPSHOT)), + save: vi.fn().mockResolvedValue({ + status: 'saved', + state: structuredClone(EMPTY_SNAPSHOT.state), + revision: 1, + committedProjectRevision: 1, + }), + generateCode: vi.fn().mockRejectedValue(new Error('not requested')), + }; + + render( + createElement(UiEditorPage, { + projectPath: '/tmp/ui-editor', + resourceId: 'ui-resource', + stateStore, + }), + ); + + fireEvent.click(await screen.findByRole('button', { name: '保存' })); + fireEvent.click(await screen.findByRole('button', { name: '仍然保存' })); + + const dialog = await screen.findByRole('dialog'); + expect(dialog.textContent).toContain('保存成功'); + expect(dialog.textContent).not.toContain('生成文件路径'); + }); + + it('reports partial success when saving succeeds but generation fails', async () => { + const stateStore: IUiDesignStateStore = { + load: vi.fn().mockResolvedValue(structuredClone(EMPTY_SNAPSHOT)), + save: vi.fn().mockResolvedValue({ + status: 'saved', + state: structuredClone(EMPTY_SNAPSHOT.state), + revision: 1, + committedProjectRevision: 1, + }), + generateCode: vi.fn().mockRejectedValue(new Error('生成服务不可用')), + }; + + render( + createElement(UiEditorPage, { + projectPath: '/tmp/ui-editor', + resourceId: 'ui-resource', + stateStore, + }), + ); + + fireEvent.click( + await screen.findByRole('button', { name: '保存并生成代码' }), + ); + fireEvent.click( + await screen.findByRole('button', { name: '仍然保存并生成' }), + ); + + const dialog = await screen.findByRole('dialog'); + expect(dialog.textContent).toContain('项目已保存，但代码生成失败'); + expect(dialog.textContent).toContain('生成服务不可用'); + expect(screen.getByRole('button', { name: '重试保存并生成' })).toBeTruthy(); + }); + + it('shows a manual-copy hint when the native clipboard rejects a path', async () => { + const stateStore: IUiDesignStateStore = { + load: vi.fn().mockResolvedValue(structuredClone(EMPTY_SNAPSHOT)), + save: vi.fn().mockResolvedValue({ + status: 'saved', + state: structuredClone(EMPTY_SNAPSHOT.state), + revision: 1, + committedProjectRevision: 1, + }), + generateCode: vi.fn().mockResolvedValue({ + relativePath: 'ui/generated-example.js', + treeExports: ['Example'], + treeCount: 1, + nodeCount: 2, + }), + }; + vi.mocked(writeText).mockRejectedValue(new Error('clipboard unavailable')); + + render( + createElement(UiEditorPage, { + projectPath: '/tmp/ui-editor', + resourceId: 'ui-resource', + stateStore, + }), + ); + + fireEvent.click( + await screen.findByRole('button', { name: '保存并生成代码' }), + ); + fireEvent.click( + await screen.findByRole('button', { name: '仍然保存并生成' }), + ); + fireEvent.click(await screen.findByRole('button', { name: '复制路径' })); + + expect(await screen.findByText('复制失败，请手动复制路径。')).toBeTruthy(); + }); it.each([ ['manual', 'saved', 1], ['manual', 'unchanged', 1], diff --git a/apps/ai-game-creator-shell/tests/uiEditorPreview.test.tsx b/apps/ai-game-creator-shell/tests/uiEditorPreview.test.tsx index 487ea4fa4..963283a51 100644 --- a/apps/ai-game-creator-shell/tests/uiEditorPreview.test.tsx +++ b/apps/ai-game-creator-shell/tests/uiEditorPreview.test.tsx @@ -152,6 +152,27 @@ describe('UI tree preview visibility', () => { expect(onClose).toHaveBeenCalledTimes(1); }); + it('runs an enabled context-menu action from its portal', () => { + const onClose = vi.fn(); + const onInsertChild = vi.fn(); + render( + , + ); + + fireEvent.click(screen.getByRole('menuitem', { name: '新增子节点' })); + + expect(onInsertChild).toHaveBeenCalledWith('node-1'); + expect(onClose).toHaveBeenCalledTimes(1); + }); + it('maps a Godot HBoxContainer to preview CSS and disables child free-transform handles', () => { const hboxTree: UITree = { src_ui_design: 'page', @@ -198,9 +219,7 @@ describe('UI tree preview visibility', () => { }); it('shows final-preview node frames and resize handles only when requested', () => { - const withoutFrames = renderTree('final-preview', new Set(), { - selectedNodeId: 'child', - }); + const withoutFrames = renderTree('final-preview', new Set()); const plainChild = withoutFrames.container.querySelector( '[data-node-id="child"]', ) as HTMLDivElement; @@ -347,7 +366,7 @@ describe('UI tree preview visibility', () => { expect(onSelectChild).toHaveBeenCalledWith('child-b'); }); - it('opens a context-menu target only from editor overlay nodes', () => { + it('passes context-menu targets with the optional tree id', () => { const onNodeContextMenu = vi.fn(); const onSelectNode = vi.fn(); const editorOverlay = render( @@ -380,6 +399,7 @@ describe('UI tree preview visibility', () => { expect.anything(), expect.objectContaining({ id: 'child' }), false, + undefined, ); editorOverlay.unmount(); @@ -389,6 +409,12 @@ describe('UI tree preview visibility', () => { fireEvent.contextMenu( finalPreview.container.querySelector('[data-node-id="child"]')!, ); - expect(onNodeContextMenu).toHaveBeenCalledTimes(1); + expect(onNodeContextMenu).toHaveBeenCalledTimes(2); + expect(onNodeContextMenu).toHaveBeenLastCalledWith( + expect.anything(), + expect.objectContaining({ id: 'child' }), + false, + undefined, + ); }); }); diff --git a/apps/ai-game-creator-shell/tests/uiEditorState.test.ts b/apps/ai-game-creator-shell/tests/uiEditorState.test.ts index 248ea7335..737ce9d09 100644 --- a/apps/ai-game-creator-shell/tests/uiEditorState.test.ts +++ b/apps/ai-game-creator-shell/tests/uiEditorState.test.ts @@ -4,6 +4,8 @@ import { act, renderHook } from '@testing-library/react'; import { describe, expect, it } from 'vitest'; import { validateComponentRecognitionPrerequisites } from '../src/features/ui-editor/requisites'; +import { validateUiDesignState } from '../src/features/ui-editor/stateInvariants'; +import { applyUiEditorCommand } from '../src/features/ui-editor/stateTransition'; import type { FontAsset } from '../src/features/ui-editor/types/FontAsset'; import type { Node } from '../src/features/ui-editor/types/Node'; import type { SpriteAsset } from '../src/features/ui-editor/types/SpriteAsset'; @@ -16,7 +18,6 @@ import { function image(name: string): UIDesignImage { return { - metadata: { name, role: null, slave_to: null }, path: `assets/${name}.png`, pixel_size: [100, 80], pixels_per_unit: 1, @@ -117,6 +118,67 @@ function pageRoot(id: string, children: Node[] = []): Node { } describe('useUiEditorState', () => { + it('applies semantic transitions without exposing tree traversal', () => { + const state: State = { + ...structuredClone(EMPTY_UI_EDITOR_STATE), + ui_design_images: { page: image('Page') }, + ui_trees: [{ src_ui_design: 'page', root: pageRoot('root') }], + }; + const result = applyUiEditorCommand(state, { + type: 'set-tree-offset', + treeId: 'page', + min: [12, 24], + }); + expect(result.ok).toBe(true); + if (result.ok) { + expect(result.state.ui_trees[0]?.root.offset).toEqual({ + min: [12, 24], + max: [112, 104], + }); + } + }); + + it('rejects a tree offset that is not a two-element tuple', () => { + const state: State = { + ...structuredClone(EMPTY_UI_EDITOR_STATE), + ui_design_images: { page: image('Page') }, + ui_trees: [{ src_ui_design: 'page', root: pageRoot('root') }], + }; + for (const min of [[12], []] as unknown as [number, number][]) { + expect( + applyUiEditorCommand(state, { + type: 'set-tree-offset', + treeId: 'page', + min, + }), + ).toEqual({ ok: false, reason: 'invalid' }); + } + }); + + it('reports persistable state invariant failures before save', () => { + const state = structuredClone(EMPTY_UI_EDITOR_STATE); + state.ui_trees = [{ src_ui_design: 'missing', root: pageRoot('root') }]; + expect(validateUiDesignState(state)).toEqual([ + expect.objectContaining({ code: 'missing-tree-image' }), + ]); + }); + + it('reports malformed images instead of throwing', () => { + const state = structuredClone(EMPTY_UI_EDITOR_STATE); + for (const malformed of [ + { pixel_size: [100, 80], pixels_per_unit: 1 }, + { path: 'assets/page.png', pixels_per_unit: 1 }, + { path: 'assets/page.png', pixel_size: [0, 80], pixels_per_unit: 1 }, + ]) { + state.ui_design_images = { + page: malformed as unknown as UIDesignImage, + }; + expect(validateUiDesignState(state)).toEqual([ + expect.objectContaining({ code: 'invalid-image' }), + ]); + } + }); + it('moves a subtree between UI trees without changing its transform', () => { const moved = nodeWithSprite('moved'); const initial: State = { @@ -234,15 +296,11 @@ describe('useUiEditorState', () => { { id: 'section-a', image: image('Section A') }, ]), ).toEqual({ ok: true, value: undefined }); - result.current.setImageRole('page-a', 'Page'); - result.current.setImageRole('section-a', 'Section'); - result.current.setImageSlaveTo('section-a', 'page-a'); - result.current.setImageName('section-a', '任务页'); }); - expect(result.current.state.ui_design_images['section-a']).toMatchObject({ - metadata: { name: '任务页', role: 'Section', slave_to: 'page-a' }, - }); + expect(result.current.state.ui_design_images['section-a']).toEqual( + image('Section A'), + ); expect(result.current.state.ui_trees).toEqual( expect.arrayContaining([ expect.objectContaining({ @@ -282,33 +340,6 @@ describe('useUiEditorState', () => { }); }); - it('rejects self-references and slave_to cycles', () => { - const { result } = renderHook(() => useUiEditorState()); - - act(() => { - result.current.addDesignImages([ - { id: 'page', image: image('Page') }, - { id: 'section', image: image('Section') }, - ]); - result.current.setImageRole('page', 'Page'); - result.current.setImageSlaveTo('section', 'page'); - }); - - act(() => { - expect(result.current.setImageSlaveTo('page', 'page')).toEqual({ - ok: false, - reason: 'invalid:slave_to 不能形成循环', - }); - expect(result.current.setImageSlaveTo('page', 'section')).toEqual({ - ok: false, - reason: 'invalid:slave_to 不能形成循环', - }); - }); - expect(result.current.state.ui_design_images.page?.metadata.slave_to).toBe( - null, - ); - }); - it('adds a batch atomically and rejects duplicates and limits', () => { const { result } = renderHook(() => useUiEditorState()); @@ -365,7 +396,11 @@ describe('useUiEditorState', () => { expect(result.current.isLocked).toBe(true); act(() => { - expect(result.current.setImageName('a', 'Locked')).toEqual({ + expect( + result.current.addDesignImages([ + { id: 'locked', image: image('Locked') }, + ]), + ).toEqual({ ok: false, reason: 'locked', }); @@ -394,14 +429,8 @@ describe('useUiEditorState', () => { const initial: State = { ...structuredClone(EMPTY_UI_EDITOR_STATE), ui_design_images: { - page: { - ...image('Page'), - metadata: { name: 'Page', role: 'Page', slave_to: null }, - }, - child: { - ...image('Child'), - metadata: { name: 'Child', role: 'Section', slave_to: 'page' }, - }, + page: image('Page'), + child: image('Child'), }, sprite_assets: { panel: sprite('panel') }, ui_trees: [ @@ -448,7 +477,6 @@ describe('useUiEditorState', () => { value: { removedResourceCount: 1, removedTreeCount: 0, - clearedSlaveToCount: 0, clearedTargetGraphicCount: 1, clearedFontCount: 0, }, @@ -463,9 +491,7 @@ describe('useUiEditorState', () => { expect(result.current.state.sprite_assets.panel).toBeUndefined(); expect(result.current.state.ui_trees).toHaveLength(1); expect(result.current.state.ui_design_images.page).toBeUndefined(); - expect( - result.current.state.ui_design_images.child?.metadata.slave_to, - ).toBeNull(); + expect(result.current.state.ui_design_images.child).toBeDefined(); }); it('merges identical sprite and font resources idempotently and rejects identity conflicts', () => { @@ -554,7 +580,6 @@ describe('useUiEditorState', () => { value: { removedResourceCount: 1, removedTreeCount: 0, - clearedSlaveToCount: 0, clearedTargetGraphicCount: 0, clearedFontCount: 1, }, @@ -567,48 +592,15 @@ describe('useUiEditorState', () => { }); }); - it('keeps setters local and defers workflow errors to prerequisites', () => { - const initial: State = { - ...structuredClone(EMPTY_UI_EDITOR_STATE), - ui_design_images: { - page: { - ...image('Page'), - metadata: { name: 'Page', role: 'Page', slave_to: null }, - }, - child: { - ...image('Child'), - metadata: { name: 'Child', role: 'Section', slave_to: 'page' }, - }, - }, - }; - const { result } = renderHook(() => useUiEditorState(initial)); - - act(() => { - result.current.setImageRole('page', null); - }); - - expect(result.current.state.ui_design_images.child?.metadata.slave_to).toBe( - 'page', - ); - expect( - validateComponentRecognitionPrerequisites(result.current.state), - ).toEqual([ - expect.objectContaining({ - code: 'invalid-slave-to', - resourceId: 'child', - }), - ]); - }); - it('records, undoes, redoes, and clears redo after a new edit', () => { const initial: State = { ...structuredClone(EMPTY_UI_EDITOR_STATE), - ui_design_images: { page: image('Page') }, + sprite_assets: { panel: sprite('panel') }, }; const { result } = renderHook(() => useUiEditorState(initial)); act(() => { - result.current.setImageName('page', '第一次'); + result.current.setSpriteName('panel', '第一次'); }); expect(result.current.historyState).toEqual({ canUndo: true, @@ -618,8 +610,8 @@ describe('useUiEditorState', () => { act(() => { expect(result.current.undo()).toBe(true); }); - expect(result.current.state.ui_design_images.page?.metadata.name).toBe( - 'Page', + expect(result.current.state.sprite_assets.panel?.metadata.name).toBe( + 'panel', ); expect(result.current.historyState).toEqual({ canUndo: false, @@ -629,15 +621,15 @@ describe('useUiEditorState', () => { act(() => { expect(result.current.redo()).toBe(true); }); - expect(result.current.state.ui_design_images.page?.metadata.name).toBe( + expect(result.current.state.sprite_assets.panel?.metadata.name).toBe( '第一次', ); act(() => { - result.current.setImageName('page', '第二次'); + result.current.setSpriteName('panel', '第二次'); expect(result.current.redo()).toBe(false); }); - expect(result.current.state.ui_design_images.page?.metadata.name).toBe( + expect(result.current.state.sprite_assets.panel?.metadata.name).toBe( '第二次', ); }); @@ -645,17 +637,17 @@ describe('useUiEditorState', () => { it('does not record no-op edits and resets history when replacing loaded state', () => { const initial: State = { ...structuredClone(EMPTY_UI_EDITOR_STATE), - ui_design_images: { page: image('Page') }, + sprite_assets: { panel: sprite('panel') }, }; const { result } = renderHook(() => useUiEditorState(initial)); act(() => { - result.current.setImageName('page', 'Page'); + result.current.setSpriteName('panel', 'panel'); }); expect(result.current.historyState.canUndo).toBe(false); act(() => { - result.current.setImageName('page', '编辑后'); + result.current.setSpriteName('panel', '编辑后'); result.current.replaceState(initial, { history: 'reset' }); }); expect(result.current.historyState).toEqual({ @@ -664,7 +656,7 @@ describe('useUiEditorState', () => { }); act(() => { - result.current.setImageName('page', '清空前'); + result.current.setSpriteName('panel', '清空前'); result.current.clearState(); }); expect(result.current.state).toEqual(EMPTY_UI_EDITOR_STATE); @@ -677,27 +669,27 @@ describe('useUiEditorState', () => { it('records each replacement as an independent history entry', () => { const initial: State = { ...structuredClone(EMPTY_UI_EDITOR_STATE), - ui_design_images: { page: image('Page') }, + sprite_assets: { panel: sprite('panel') }, }; const { result } = renderHook(() => useUiEditorState(initial)); act(() => { result.current.replaceState({ ...initial, - ui_design_images: { page: image('中间') }, + sprite_assets: { panel: sprite('中间') }, }); result.current.replaceState({ ...initial, - ui_design_images: { page: image('最终') }, + sprite_assets: { panel: sprite('最终') }, }); }); - expect(result.current.state.ui_design_images.page?.metadata.name).toBe( + expect(result.current.state.sprite_assets.panel?.metadata.name).toBe( '最终', ); act(() => { expect(result.current.undo()).toBe(true); }); - expect(result.current.state.ui_design_images.page?.metadata.name).toBe( + expect(result.current.state.sprite_assets.panel?.metadata.name).toBe( '中间', ); }); @@ -705,7 +697,7 @@ describe('useUiEditorState', () => { it('records one history entry after skipped replacement batches', () => { const initial: State = { ...structuredClone(EMPTY_UI_EDITOR_STATE), - ui_design_images: { page: image('Page') }, + sprite_assets: { panel: sprite('panel') }, }; const { result } = renderHook(() => useUiEditorState(initial)); @@ -713,20 +705,20 @@ describe('useUiEditorState', () => { result.current.replaceState( { ...initial, - ui_design_images: { page: image('第一批') }, + sprite_assets: { panel: sprite('第一批') }, }, { history: 'skip' }, ); result.current.replaceState( { ...initial, - ui_design_images: { page: image('最终') }, + sprite_assets: { panel: sprite('最终') }, }, { history: 'record' }, ); }); - expect(result.current.state.ui_design_images.page?.metadata.name).toBe( + expect(result.current.state.sprite_assets.panel?.metadata.name).toBe( '最终', ); expect(result.current.historyState).toEqual({ @@ -736,8 +728,8 @@ describe('useUiEditorState', () => { act(() => { expect(result.current.undo()).toBe(true); }); - expect(result.current.state.ui_design_images.page?.metadata.name).toBe( - 'Page', + expect(result.current.state.sprite_assets.panel?.metadata.name).toBe( + 'panel', ); expect(result.current.historyState).toEqual({ canUndo: false, diff --git a/apps/ai-game-creator-shell/tests/useNodeTransformInteraction.test.tsx b/apps/ai-game-creator-shell/tests/useNodeTransformInteraction.test.tsx index e2f8339f9..f135a1db6 100644 --- a/apps/ai-game-creator-shell/tests/useNodeTransformInteraction.test.tsx +++ b/apps/ai-game-creator-shell/tests/useNodeTransformInteraction.test.tsx @@ -93,14 +93,12 @@ function canvas() { } function renderInteraction({ - activeImageId = 'page', scale = 1, tree = pageTree, keepChildrenUnchanged = false, onPreviewTransform, selectedNodeId = null, }: { - activeImageId?: string | null; scale?: number; tree?: UITree | null; keepChildrenUnchanged?: boolean; @@ -112,20 +110,28 @@ function renderInteraction({ } = {}) { const canvasProjection = canvas(); const viewportRef = { current: { scale } }; + const trees = tree ? [tree] : []; + const logicalSizes = tree + ? new Map([[tree.src_ui_design, { width: 320, height: 180 }]]) + : new Map(); const hook = renderHook( - ({ imageId, currentTree }) => + ({ currentTrees, currentLogicalSizes }) => useNodeTransformInteraction({ - activeImageId: imageId, canvas: canvasProjection, - logicalSize: { width: 320, height: 180 }, + trees: currentTrees, + logicalSizes: currentLogicalSizes, spaceHeld: false, - tree: currentTree, viewportRef, keepChildrenUnchanged, onPreviewTransform, selectedNodeId, }), - { initialProps: { imageId: activeImageId, currentTree: tree } }, + { + initialProps: { + currentTrees: trees, + currentLogicalSizes: logicalSizes, + }, + }, ); return { ...hook, canvasProjection, viewportRef }; } @@ -149,7 +155,11 @@ describe('useNodeTransformInteraction', () => { const target = gestureTarget(); act(() => { - result.current.onNodePointerDown(pointerEvent(target, 1, 0, 0), child); + result.current.onNodePointerDown( + pointerEvent(target, 1, 0, 0), + child, + 'page', + ); result.current.onNodePointerMove(pointerEvent(target, 1, 4, 0)); result.current.onNodePointerUp(pointerEvent(target, 1, 4, 0)); }); @@ -171,7 +181,7 @@ describe('useNodeTransformInteraction', () => { const event = pointerEvent(target, 1, 0, 0); act(() => { - result.current.onNodePointerDown(event, child); + result.current.onNodePointerDown(event, child, 'page'); }); expect(event.preventDefault).toHaveBeenCalledTimes(1); @@ -211,6 +221,7 @@ describe('useNodeTransformInteraction', () => { result.current.onNodePointerDown( pointerEvent(target, 1, 0, 0), nestedChild, + 'page', ); result.current.onNodePointerMove(pointerEvent(target, 1, 10, 5)); result.current.onNodePointerCancel(pointerEvent(target, 1, 10, 5)); @@ -250,7 +261,11 @@ describe('useNodeTransformInteraction', () => { const target = gestureTarget(); act(() => { - result.current.onNodePointerDown(pointerEvent(target, 1, 0, 0), parent); + result.current.onNodePointerDown( + pointerEvent(target, 1, 0, 0), + parent, + 'page', + ); result.current.onNodePointerMove(pointerEvent(target, 1, 10, 5)); }); @@ -300,6 +315,7 @@ describe('useNodeTransformInteraction', () => { pointerEvent(target, 1, 0, 0), parent, 'nw', + 'page', ); result.current.onNodeResizePointerMove(pointerEvent(target, 1, 10, 5)); }); @@ -320,11 +336,13 @@ describe('useNodeTransformInteraction', () => { result.current.onNodePointerDown( pointerEvent(dragTarget, 1, 0, 0), child, + 'page', ); result.current.onNodeResizePointerDown( pointerEvent(resizeTarget, 2, 0, 0), child, 'se', + 'page', ); result.current.onNodePointerMove(pointerEvent(dragTarget, 1, 12, 8)); }); @@ -338,6 +356,7 @@ describe('useNodeTransformInteraction', () => { pointerEvent(resizeTarget, 2, 0, 0), child, 'se', + 'page', ); }); expect(canvasProjection.updateNodeTransform).toHaveBeenCalledTimes(1); @@ -348,7 +367,11 @@ describe('useNodeTransformInteraction', () => { const { result, canvasProjection } = renderInteraction(); const target = gestureTarget(); act(() => { - result.current.onNodePointerDown(pointerEvent(target, 1, 0, 0), child); + result.current.onNodePointerDown( + pointerEvent(target, 1, 0, 0), + child, + 'page', + ); }); expect(canvasProjection.selectNode).not.toHaveBeenCalled(); act(() => { @@ -363,7 +386,11 @@ describe('useNodeTransformInteraction', () => { const { result, canvasProjection } = renderInteraction(); const target = gestureTarget(); act(() => { - result.current.onNodePointerDown(pointerEvent(target, 1, 0, 0), child); + result.current.onNodePointerDown( + pointerEvent(target, 1, 0, 0), + child, + 'page', + ); result.current.onNodePointerMove(pointerEvent(target, 1, 4, 0)); result.current.onNodePointerUp(pointerEvent(target, 1, 4, 0)); }); @@ -371,31 +398,38 @@ describe('useNodeTransformInteraction', () => { expect(result.current.consumeNodeClick()).toBe(true); act(() => { - result.current.onNodePointerDown(pointerEvent(target, 2, 0, 0), child); + result.current.onNodePointerDown( + pointerEvent(target, 2, 0, 0), + child, + 'page', + ); result.current.onNodePointerCancel(pointerEvent(target, 2, 0, 0)); }); expect(canvasProjection.selectNode).not.toHaveBeenCalled(); expect(result.current.consumeNodeClick()).toBe(false); }); - it('cancels a gesture when its tree changes and ignores its later events', () => { + it('ignores gesture updates when its tree leaves the preview', () => { const { result, rerender, canvasProjection } = renderInteraction(); const target = gestureTarget(); act(() => { - result.current.onNodePointerDown(pointerEvent(target, 1, 0, 0), child); + result.current.onNodePointerDown( + pointerEvent(target, 1, 0, 0), + child, + 'page', + ); }); act(() => { rerender({ - imageId: 'other', - currentTree: { ...pageTree, src_ui_design: 'other' }, + currentTrees: [{ ...pageTree, src_ui_design: 'other' }], + currentLogicalSizes: new Map([['other', { width: 320, height: 180 }]]), }); }); act(() => { result.current.onNodePointerMove(pointerEvent(target, 1, 12, 8)); }); - expect(target.releasePointerCapture).toHaveBeenCalledWith(1); expect(canvasProjection.updateNodeTransform).not.toHaveBeenCalled(); }); @@ -404,7 +438,11 @@ describe('useNodeTransformInteraction', () => { const target = gestureTarget(); act(() => { - result.current.onNodePointerDown(pointerEvent(target, 1, 0, 0), child); + result.current.onNodePointerDown( + pointerEvent(target, 1, 0, 0), + child, + 'page', + ); viewportRef.current.scale = Number.NaN; result.current.onNodePointerMove(pointerEvent(target, 1, 12, 8)); }); @@ -418,7 +456,11 @@ describe('useNodeTransformInteraction', () => { const target = gestureTarget(); act(() => { - result.current.onNodePointerDown(pointerEvent(target, 1, 0, 0), child); + result.current.onNodePointerDown( + pointerEvent(target, 1, 0, 0), + child, + 'page', + ); unmount(); }); diff --git a/apps/ai-game-creator-shell/tests/workflowCompletionNotice.test.ts b/apps/ai-game-creator-shell/tests/workflowCompletionNotice.test.ts index af3f2d1cc..ca52a001f 100644 --- a/apps/ai-game-creator-shell/tests/workflowCompletionNotice.test.ts +++ b/apps/ai-game-creator-shell/tests/workflowCompletionNotice.test.ts @@ -4,6 +4,7 @@ import { appendWorkflowCheckPrompt, workflowStepLabel, } from '../src/view/ui-editor/components/workflowCompletionNotice'; +import { UI_EDITOR_STEPS } from '../src/view/ui-editor/model'; describe('workflow completion notice helpers', () => { it('appends the review prompt to a terminal status', () => { @@ -12,9 +13,10 @@ describe('workflow completion notice helpers', () => { ); }); - it('maps every workflow step to a user-facing label', () => { - expect(workflowStepLabel('reference-analysis')).toBe('分析参考图'); - expect(workflowStepLabel('structure-recognition')).toBe('识别界面结构'); - expect(workflowStepLabel('asset-separation')).toBe('自动切分素材'); + it('maps every catalog step to its user-facing label', () => { + // 按步骤目录取标签：步骤退役或新增时用例会跟着目录走，不再断言已删除的步骤。 + for (const step of UI_EDITOR_STEPS) { + expect(workflowStepLabel(step.id)).toBe(step.label); + } }); }); diff --git a/docs/README.md b/docs/README.md index 6ddf891c0..20a519f46 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,6 +43,7 @@ - [DirectProject Codex 原始历史与异常恢复](<./technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md>)：原始 Responses item 持久化、线程注入与异常回合收尾。 - [DirectProject 对话历史单一事实源](./adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md)：AGC 项目开发对话只以项目对话历史与运行态事件为真相源，聊天投影不落盘。 - [DirectProject 独立聊天容器与工作台钱包布局](./adr/【ADR】DirectProject独立聊天容器与工作台钱包布局-2026-09-18.md)：DirectProject 与 Supervisor 等路径分容器，钱包入口由项目工作台布局独立承载。 +- [UI 工作流检查点用追加式 JSONL 日志](./adr/【ADR】UI工作流检查点用追加式JSONL日志-2026-09-23.md)：UI 设计文档的 Agent 工作流用文档旁追加式 JSONL 记录步骤完成，替代每步一个 sidecar 状态机。 - [退役 AGC 项目对话斜杠命令](./adr/【ADR】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22.md)：AGC 项目对话与终端 swarm chat 均不再解析斜杠命令，终端聊天入口一并退役；实现、测试、门禁与文档承诺全部删除，命令 id 与权限位作为项目策略词汇表保留。 - [引用候选由宿主注入](./adr/【ADR】引用候选由宿主注入-2026-09-22.md)：引用输入区只接受宿主注入的引用 provider，素材选择面板独立成组件，附件芯片成为本轮附件唯一事实源。 - [DirectProject 命令接单化](./adr/【ADR】DirectProject命令接单化-2026-09-23.md)：命令只负责接单、事件流回答整轮结果；拒单前置、失败后置。 @@ -67,7 +68,8 @@ - [AGC 资源派生与非破坏性编辑合同](./technical/【技术方案】AGC资源派生与非破坏性编辑合同-2026-09-09.md)：AGC 全类型现有资源非破坏性编辑的权威合同，约束资源派生、替换与写回边界。 - [AGC 聊天素材引用](./【功能说明】AGC聊天素材引用-2026-09-08.md)：聊天输入框 @ 引用项目素材的入口、引用模型与「当前版本素材」口径。 - [AGC 聊天 AI 润色与发送前提醒](./【功能说明】AGC聊天AI润色与发送前提醒-2026-09-10.md)：提示词润色与发送前提醒的交互、失败与取消口径。 -- [UI 工作流资源桥接与 Runtime 执行](./【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md) +- [UI 编辑器代码地图与模块职责](./technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md)：Rust `ui_editor` 模块、`features/ui-editor` 语义层与 `view/ui-editor` 视图层的职责划分与扩展指引。 +- [UI 编辑器 Agent 工具化重写](./technical/【技术方案】UI编辑器Agent工具化重写-2026-09-23.md)：三个工具（建文档 / 跑工作流 / 出 JS）的契约、两步工作流、JSONL 检查点与模块布局。 - [UI 编辑器 Godot 容器布局](./technical/【技术方案】UI编辑器Godot容器布局模型-2026-08-18.md) - [UI 编辑器变换角点偏移编辑器](./technical/【设计】UI编辑器变换角点偏移编辑器-2026-09-03.md) - [UI 编辑器子节点显示规则](./technical/【技术方案】UI编辑器子节点显示规则-2026-08-18.md) diff --git a/docs/adr/【ADR】UI工作流检查点用追加式JSONL日志-2026-09-23.md b/docs/adr/【ADR】UI工作流检查点用追加式JSONL日志-2026-09-23.md new file mode 100644 index 000000000..07865dee0 --- /dev/null +++ b/docs/adr/【ADR】UI工作流检查点用追加式JSONL日志-2026-09-23.md @@ -0,0 +1,18 @@ +# UI 工作流检查点用追加式 JSONL 日志 + +UI 设计文档的工作流由 Agent 工具驱动、跨多次外部调用，崩溃后需要能续跑。检查点定为**文档旁一条按行追加的 JSONL 日志**：每一步做完就追加一行——起始一轮记原始 State 快照，识别与切分各记自己的 DTO **以及该步应用完之后的那份 State 快照**，最后一行是回写标记——"某步是否完成"只看日志里有没有对应的行，没有就是没完成。恢复只做两件事：读回已完成步骤留下的 State 快照，然后从第一个没有快照的步骤继续。 + +## 考虑过的方案 + +- 每步一个 sidecar 状态机（步骤状态 + sealedAtRevision + evidence 清单）：要额外维护状态迁移、封条判据和证据校验，等于给每一步发明一套小协议。 +- 把切分专用的 `SeparationState` 泛化成通用检查点：切分需要"每个批次、每个节点"的细粒度恢复语义，其它步骤不需要，泛化会把这份复杂度摊给所有步骤。 + +追加式日志只需要"存在即完成"这一条判据，新增步骤类型等于新增一种行，天然可扩展。每步应用完的 State 快照随该步行一同落下，恢复就只是"读回最新快照"，不必再维护一份"照 DTO 重算一遍"的镜像逻辑。 + +## 后果 + +- 日志是恢复用的派生信息，不是项目内容：不登记为 manifest 资产，不推进项目 revision。 +- 每行必须一次性原子追加；崩溃时可能留下写了一半的最后一行，未形成完整行的步骤一律视为未完成。 +- 同一份文档可以被多次运行，日志必须能区分轮次：每一轮以一行原始 State 快照开头，该轮的第一行回写标记即为这一轮结束；恢复只针对最后一个没有回写标记的轮次。 +- 恢复只看快照、不重放步骤：已完成步骤在日志里带着"那一步应用完"的 State，恢复直接采纳并整步跳过。若照 DTO 再跑一遍，会重复登记切图、把同一条回填出错原因重复累加。只有带 State 快照的行才算已完成，旧格式（只有 DTO）按未完成重跑。 +- 切分 op 内部的细粒度恢复仍由 `SeparationState` 承担，日志只记录工作流层面的步骤完成，不顺带复制它的进度。 diff --git a/docs/project-memory/plans/【实施计划】UI编辑器多树预览与独立显示开关-2026-09-14.md b/docs/project-memory/plans/【实施计划】UI编辑器多树预览与独立显示开关-2026-09-14.md new file mode 100644 index 000000000..82a49e1f7 --- /dev/null +++ b/docs/project-memory/plans/【实施计划】UI编辑器多树预览与独立显示开关-2026-09-14.md @@ -0,0 +1,35 @@ +# 【实施计划】UI编辑器多树预览与独立显示开关 + +| 字段 | 值 | +| --- | --- | +| Milestone | `docs/project-memory/plans/【里程碑】UI编辑器多树预览与独立显示开关-2026-09-14.md` | +| Status | ready | +| Owner | Codex | + +## 修改边界 + +- 允许修改：AGC UI editor Rust Node/UITree DTO、前端 UI editor state/session、preview 组件、相关测试与当前专题文档。 +- 明确不修改：SpacetimeDB、External v1、代码生成 runtime 语义、用户 `.env`。 + +## 实现顺序 + +1. 更新 Rust Node 与生成的 TS 类型；补齐所有 Node 构造器。 +2. 在状态层集中实现 createTree 与 root offset 更新。 +3. 将 session canvas projection 改为全树投影并提供按 treeId 的节点/根操作。 +4. 重构 preview 为联合画布、多树 wrapper、独立三个显示开关和树级拖动。 +5. 修正左侧选择与 Inspector 的 tree 反查，不让预览选择修改 activeImageId。 +6. 增加/更新定向测试与文档。 + +## 验证命令 + +1. `npm --prefix apps/ai-game-creator-shell test -- --run` +2. `npm --prefix apps/ai-game-creator-shell run typecheck` +3. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` +4. `npm run check:encoding` +5. `git diff --check` + +## 风险与回滚点 + +- Node DTO 是生成绑定，Rust 与 TS 不一致会阻断编译；每次结构变更后立即生成并检查 diff。 +- 预览选择与 activeImageId 解耦可能暴露 Inspector 当前依赖；通过 treeId 反查补齐。 +- root 拖动需与画布平移和子节点拖动区分；若命中冲突，优先保留现有子节点手势。 diff --git a/docs/project-memory/plans/【里程碑】UI编辑器多树预览与独立显示开关-2026-09-14.md b/docs/project-memory/plans/【里程碑】UI编辑器多树预览与独立显示开关-2026-09-14.md new file mode 100644 index 000000000..6222e284c --- /dev/null +++ b/docs/project-memory/plans/【里程碑】UI编辑器多树预览与独立显示开关-2026-09-14.md @@ -0,0 +1,47 @@ +# 【里程碑】UI编辑器多树预览与独立显示开关 + +| 字段 | 值 | +| --- | --- | +| Version | 1.0 | +| Status | approved | +| Date | 2026-09-14 | +| Parent Spec | `docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md` | + +## 目标 + +UI 编辑器预览同时展示全部界面树。每棵树使用 root.offset 的 min 作为树级画布位置，支持整树拖动持久化；显示原图、组件和普通框线拆成三个独立开关。 + +## 范围 + +- `Node` 增加包含 min/max 的 offset 数据，读取只使用 min，max 由 min 与源图 logical size 派生。 +- 所有新树统一由 createTree 入口创建，并按现有树最右边界加 padding 横向排列。 +- 首次进入预览和手动适配使用全部树联合边界。 +- 左侧图片选择继续维护 activeImageId；预览选择不改变它，不因选择或拖动自动 fit。 +- root 可拖动但不可 resize；子节点维持现有选择、拖动和 resize 行为。 + +## 不在范围内 + +- 旧数据 migration、offset fallback、自动 revision 修复。 +- 删除/排序后的自动重排。 +- 代码生成 runtime 的树级布局语义。 +- root/max 的独立编辑控件。 + +## 依赖与前置条件 + +- 当前资源均符合最新 Node/UITree schema。 +- 对应界面图提供合法 pixel_size 与 pixels_per_unit。 + +## 验收标准 + +- [ ] 新树默认位于所有现有树右侧并与最小 top 对齐。 +- [ ] 原图与组件随 root 一起移动，拖动结束进入 undo/redo 并可保存恢复。 +- [ ] root 不显示 resize handles，子节点 resize 不回归。 +- [ ] 三个开关默认 showFrame=true、showOriginImage=true、showComponent=false，且互相独立。 +- [ ] 预览选择不修改 activeImageId；左侧图片选择和 Inspector 既有切换保持。 +- [ ] 仅首次进入和手动适配触发联合 fit。 + +## 证据要求 + +- 自动化：UI editor preview、state、transform 相关 Vitest；Tauri Rust 单元测试；类型检查。 +- 运行时：必要时执行 AGC UI 编辑器页面 smoke。 +- 边界：非法缺失 offset 不兜底；树重叠命中顺序；root 禁止 resize。 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index cccecf081..53b75ec40 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -1,5 +1,13 @@ # 决策记录 +## 2026-09-22 UI 编辑器预览画布补上右键拖拽平移，节点菜单改为右键抬起弹出 + +- 背景：预览画布此前只有中键与空格+左键平移，右键整段留给节点操作菜单（`UiTreeRenderer.onContextMenu` 直接弹 `UiNodeContextMenu`）。这次要补右键拖拽平移，并要求"拖拽过就不许再触发右键菜单"。实测（Linux Chromium 151 / Firefox 151，真实 X11 输入）确认 `contextmenu` 在**按下**瞬间触发，且原生菜单一旦弹出，页面之后收不到任何 `pointermove` / `pointerup` / `mouseup` / `auxclick`，所以"先让菜单弹、拖拽时再关"在浏览器层面不可行；headless 没有原生菜单，Playwright 复现不出该行为。macOS 的 `contextmenu` 在 mouseup 触发（本容器无法实测），但同一条实现路径对两种时序都成立。同一次实测：键盘菜单键触发的是 `button: -1`，所以"只认按钮 2"的拦截天然把键盘菜单留给原有节点菜单路径。 +- 决策：预览视口在捕获阶段拦截按钮 2 的 `contextmenu`（`preventDefault` + `stopPropagation`），右键手势改由预览自己裁决：按下时记录起点、`setPointerCapture` 并交焦点；移动越过与左键拖拽共用的 `DRAG_THRESHOLD_SCREEN_PX`（2px）后本次手势定死为平移，按"按下点全量 delta"更新视口（光标复用共享 `CanvasViewport` 的 `isPanning` → `cursor: grabbing`，三个平移绑定一起生效）；未越阈值且在预览内抬起时，用 `[data-node-id]` 加树容器 `data-tree-id` 命中节点并打开 `UiNodeContextMenu`，保留"右键即选中该节点"的既有语义；空白处干净右键不做事（原生菜单已被抑制）。中键、空格+左键平移不变，macOS ctrl+左键与键盘菜单键继续走原有即时菜单路径；平移是纯视图操作，不写 State、不进历史、不受 `isLocked` 与空格按住态限制。 +- 原因：右键同时承载菜单与视图平移，只能等到手势结束再裁决；把判定放进预览，是因为树、节点命中、预览边界与拖动阈值都在预览手里，而 `useNodeTransformInteraction` 应保持左键变换的单一职责；`[data-node-id]` 命中也已是 `resolveHitNodeId` 的既有模式。 +- 代价与取舍：右键从"按下即弹菜单"变成"抬起才弹"（与 Windows 自身右键菜单一致）；预览内空白处的浏览器原生菜单被永久抑制；右键平移与节点菜单互斥（越过阈值后抬起不再弹菜单）；`grabbing` 光标在悬停到节点上时仍会被节点自身的 `cursor-move` 覆盖，与共享画布现状一致。本次只改 UI 编辑器预览：AGC 美术画布仍只有空格/中键平移，资源画布保留自己的右键平移实现，都不动，也不抽 `packages/shared`。 +- 验证方式：新增 `previewRightPanGesture` 纯状态机单测（阈值跨越、起点全量 delta、拖拽吞菜单 / 干净抬起开菜单、取消与失焦清理），并在 `previewRightPanDrag.test.tsx`、`previewRightPanGesture.test.ts` 补右键回归（含键盘菜单键 `button: -1` 不被拦截的用例）；运行 `npx vitest run`（定向文件）、`apps/ai-game-creator-shell` `npm run typecheck`、`npm run lint:eslint`、`npm run check:encoding`、`git diff --check`。 + ## 2026-09-24 接单化 review 收口（第二轮）：失败载荷分类、拒单身份与提示口径 - 决策（失败载荷的 `kind` 收成 typed 枚举）：新增 `DirectTurnFailureKind`（`Serialize + Deserialize + TS`， @@ -9368,6 +9376,51 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 影响面：`apps/ai-game-creator-shell/src/features/{project-workspace/resourceReferences.ts,project-workspace/ResourceReferenceInput.tsx,resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx,resource-canvas/resourceCanvasAssetGenerationTaskModel.ts,resource-canvas/resourceCanvasAssetGenerationReferenceModel.ts}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx` 与对应 6 个定向测试文件。 - 验证：定向 `resourceCanvasAssetGenerationReferences` / `resourceCanvasAssetGenerationBackgroundClose` / `resourceCanvasBottomToolbar` / `resourceCanvasGenerationFloatingPanel(Chrome)` / `resourceReferenceInput` / `resourceReferences` / `resourceCanvasAssetGenerationTasksPanel` 全绿；全量 `npm run test -- apps/ai-game-creator-shell/tests` 只剩 `clientHttp` / `clientApi` / `clientAuthStorage` / `projectCreationDirectory` / `recentProjectsHook` 五个 jsdom `localStorage` 环境用例红（与本次改动无调用关系）；TS typecheck、`check:encoding`、`git diff --check` 通过。未复核真实客户端观感。 +## 2026-09-18 UI 编辑器深模块 seam 收敛 + +- 决策：UI 编辑器的语义状态写入通过 React-free `stateTransition` seam；页面 hook 继续负责 React/history/lock adapter。保存前增加 `stateInvariants` projection，Rust 持久化规则仍是最终权威。 +- 决策：节点几何新增 State 级 `findStateNodePageContext`，页面选择、预览和状态迁移共享同一坐标递归入口；四类异步操作的 running/status 由 `operationLifecycle` adapter 承接。 +- 决策：结构化 LLM action 共用 `commands::utils::required_tool_arguments`，仅统一必需 tool-call 定位与有界 JSON 解析，不合并 prompt、schema 或 materializer。 +- 验证：AGC typecheck、UI State 定向 Vitest、编码检查、doc-index、diff 检查和 Tauri Rust fmt 通过；Tauri 全量 cargo check 仍受现有 platform-llm API 漂移错误阻断，与本次 UI editor 改动无关。 + +## 2026-09-23 UI 编辑器退役界面图参考语义建议 + +- 背景：UI 编辑器的“分析参考图”步骤只用一次 LLM 调用给界面图补 `name` / `description` / `role` / `slave_to`，四个字段又反过来决定结构识别的上下文分组、合并的树优先级和 Inspector 的可选项；这条链路的价值不足以支撑它引入的跨层耦合。 +- 决策：`commands/ui_design_suggestion.rs`、`suggest_ui_design_semantic` 命令与 `UIDesignImage.metadata`（含 `UIDesignImageRole`、`UIDesignImageMetadata`）整体退役，`UIDesignImage` 只剩 `path` / `pixel_size` / `pixels_per_unit`；前端从三步工作流收敛为“识别界面结构 / 自动切分素材”两步，`model.ts`、`WorkflowActionCard`、`WorkflowChecks`、完成通知、`InputSidebar`、`InspectorSidebar` 与 `ImportOverview` 同步删减。不保留兼容字段、回退路径、旧文档迁移或写回。 +- 决策：界面图之间不再有持久化关系，结构识别按“每张界面图各自一棵树、各自一个上下文”执行（删掉 `recognition_root_image_ids` / `slave_image_ids`）；界面图显示名统一取 `path` 的 basename（复用 `view/project-development/resourceAssetDisplayName.ts`）。 +- 决策：多树合并暂时没有优先级来源（原优先级由 `slave_to` 祖先链计数得出），`merge` 现在把所有输入树优先级恒置 0 并留 `TODO`，合并冲突取 `merged_from` 首位成员；`ui-workflow.*` 阶段与页面级工作流不在本次范围，后续整体重写。 +- 代价与取舍：删掉 `name` / `description` 后界面图在 UI 上只能用文件名标识；合并冲突的代表节点选择不再有“优先级”依据；`role` / `slave_to` 曾承担的“主页面 + 子界面”语义彻底消失。旧 `ui_design.json` 里的 `metadata` 由 serde 默认忽略、下次保存后自然消失（`State` / `UIDesignImage` 都没有 `deny_unknown_fields`），已生成的 `ui_trees` 不受影响。 +- 影响面：`apps/ai-game-creator-shell/src-tauri/src/{main.rs,ui_editor/**}`、`src/features/ui-editor/**`、`src/view/ui-editor/**`、`src/view/project-development/index.tsx`、`tests/{uiEditorPage,uiEditorState,previewWorkspaceZoom}.test.*`、`docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md`、`docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md`、`docs/technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md`、`docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md`。 +- 验证：`cargo check` 与 `cargo test --bin genarrative-ai-game-creator-shell ui_editor`（160 passed）通过，ts-rs 重新导出 `types/UIDesignImage.ts` 并删除三个已退役类型；`npx vitest run` 定向 `uiEditorPage` / `uiEditorState` / `uiDesignStateStore` / `previewWorkspaceZoom` / `appSurface` 全绿；AGC `tsc --noEmit`、改动文件 eslint、`cargo fmt --check`、`check:encoding`、`git diff --check` 通过。整套 Rust 测试在本容器仍有 60 条环境性失败（`/sbin -> usr/bin` 让 `command.exec` 沙箱 merged-usr 预检失败），与本次改动无关。 + +## 2026-09-24 UI 设计文档三个工具的持久回执明细与入参摘要改为可读白名单 + +- 背景：动作回执的"安全明细"是一份白名单——只有认识的工具才把明细整理成安全字段。`ui.workflow.run` 退役时删掉了它那段分支，接管的 `ui-design-doc.*` 三个工具没补，于是统一落到兜底：明细整块变成 `detailUnavailable`，模型与审计都看不到；入参那一栏也只剩哈希。原始明细既不落盘也不给模型，所以**没有宿主路径泄露**，丢的是可用性（例如切分没登记上的素材清单）。 +- 决策：按既有白名单口径给三个工具各补一条分支。`from-images` 放 `assetId` / `relativePath` / `imageIds` / `revisionAdvanceCount`；`run-workflow` 再放文档 `revision`、恢复标记、识别与绑定计数、`backfillErrors` 与总数；`into-js` 只放相对路径与计数（导出名清单只用来核对数量，不逐项外传）。 +- 决策（校验口径）：身份字段走 `agent_runtime_action_receipt_identity_text`（禁控制字符、限长、含 file URI 或绝对路径即失败关闭）；相对路径必须归一化后落在 `ui/` 下；回填说明是自由文本，按既有口径把绝对路径脱敏成占位符，含控制字符或超长则整条明细失败关闭。 +- 决策（体积）：回执明细总长仍受 `AGENT_RUNTIME_ACTION_RECEIPT_SAFE_DETAIL_MAX_CHARS`（500）约束。设计图身份与回填说明按长度上限能放多少放多少，放不下的部分用 `backfillErrorCount` 表达总数；必需字段本身就超限时整条明细不可用。 +- 决策（入参摘要）：`agent_runtime_tool_action_input_summary` 为三个工具产出可读摘要（设计图逐张身份或目标文档 id），并把工具名加进 `agent_runtime_public_action_input_summary` 的可读名单，不再退化成只报哈希。 +- 验证方式：`tests::runtime_actions::action_execution::ui_design_doc_receipts_*` 两条用例（三个工具都能留下可用明细且不超长；宿主路径被脱敏；`ui/` 之外与宿主路径身份失败关闭）与 `action_audit::ui_design_doc_public_input_summary_tests` 两条用例；`cargo test --bin genarrative-ai-game-creator-shell receipt` 55 条全绿。 + +## 2026-09-24 UI 设计文档三个工具纳入项目变更门禁（成功返回即算改过项目） + +- 背景：`ui.workflow.run` 退役时，项目变更门禁的两处工具名单（`agent/runtime_actions/project_gates.rs` 的 `is_agent_runtime_project_mutation_observation` 与 `agent_runtime_observation_advances_project_revision`）只删未补，新接管的 `ui-design-doc.from-images` / `ui-design-doc.run-workflow` / `ui-design-doc.into-js` 都没登记。后果：改完项目可能被判定"没改过"，于是不要求验证就判完成、自动模式的 liveness 判据看不到进展；`agent_runtime_pending_expected_project_revision` 少算推进量又会误报 `pending_project_revision_drift`（"并行项目变更使旧动作过期"）。 +- 口径（产品确认）：三个工具都在**成功返回时**改项目——`from-images` 登记设计图与文档、`run-workflow` 登记切图并保存文档、`into-js` 重写 `ui/generated-*.js`；调用中途不产生需要门禁额外追踪的中间态。 +- 决策：门禁按"工具名 + 成功返回"判定三者都算项目变更；其中 `into-js` 只重写派生产物、**不推进 revision**，所以不进 revision 推进名单——进去会虚报推进量，正好把要修的误报再造出来。 +- 决策（真实推进量）：`from-images` / `run-workflow` 的观察明细带上 `revisionAdvanceCount`（沿用 `canvas.asset_import` 的既有字段），失败路径也带——切图素材先登记、后面步骤才失败时按约定不回滚，仍要如实计数，避免门禁把真实推进当成"别处改动"。 +- 代价与取舍：失败路径要多读一次项目 revision；`into-js` 属于"改了东西但项目 revision 没动"的少数派，与写文件类工具口径一致。 +- 验证方式：新增 `project_gates::ui_design_doc_project_mutation_gate_tests` 六条用例（成功即算变更、`into-js` 不推进 revision、登记类兜底推进量为 1、明细里的真实推进量优先、失败但已推进才算、无关工具不受影响）。 + +## 2026-09-23 UI 编辑器 Agent 工具化重写 + +- 背景：UI 编辑器的 Agent 链路原本只有一个 `ui.workflow.run`，把发现页面、桥接设计图、结构识别、多树合并、组件绑定、finalize 全塞进一个工具，工具参数本身就是工作流状态；识别与切分的产物由前端 `useUiEditorPage.ts` 落 State 再保存，Agent 侧没有任何恢复点，任一步失败只能整轮重来。 +- 决策：拆成三个各自只做一件事的工具——`ui-design-doc.from-images`（一至四张设计图新建并登记文档，返回 `assetId` 与 `relativePath`）、`ui-design-doc.run-workflow`（`recognize → separate → write-back`）、`ui-design-doc.into-js`（渲染 `ui/generated--.js`，不推进 revision）。只有 `run-workflow` 带崩溃恢复，粒度到子步骤。 +- 决策（检查点）：恢复判据只有「这一步有没有对应、且带着 State 快照的检查点行」。检查点是文档旁追加式 JSONL `ui/.<文档名>-workflow.jsonl`（不进 manifest、不推进 revision），行类型 `run` / `recognize` / `separate` / `write-back` / `outdated`；`run` 行带这一轮开始时的 State 快照，`recognize` / `separate` 行带该步应用完之后的 State 快照。恢复只读快照：逐级取回已完成步骤留下的 State，只把新完成那一步的改动应用到文档，已完成步骤整步跳过、绝不照 DTO 重跑（重跑会重复登记切图、把同一条回填出错原因重复报一遍）。只有 DTO、没有 State 快照的旧行按未完成处理，由主流程重跑该步。一轮以 `run` 开头、以首个 `write-back` 或 `outdated` 结束，只有最后一轮没有结束行时才恢复。追加前截断崩溃留下的半行；文档中途漂移（当前 State 既不是 `run` 行快照、也不是切分后那份快照）时追加 `outdated` 并返回错误，由下一次调用显式开新一轮，不在同一次调用里自动重启；写回按「切分后那份 State 快照与文档当前 State 相等」判幂等并补 `write-back` 行。 +- 决策（边界）：文档内设计图身份直接采用该图在 manifest 里的 `assetId`，输入给相对路径时先登记再用它的 `assetId`；每次调用都新建文档，不做「原型 → 已存在文档」的幂等查找。切图资源失败不回滚，重放靠 by-path 复用接上；切分 op 内部更细粒度的恢复仍由 `SeparationState` sidecar 承担，日志不复制它的进度。前端 `useUiEditorPage.ts` 的人工链路保留同语义，Rust 只是第二份实现，不把编排搬进 Rust。 +- 退役：`ui.workflow.run`、`ui_editor/commands/{merge.rs,binding.rs}`、`ui_editor/workflow.rs`、`ensure_ui_design_resource_for_prototype`、`ui/ui-workflow-.json` 命名与 `ui-workflow.*` manifest 阶段全部删除，不保留迁移、兼容与 fallback。 +- 代价与取舍：不接受跨语言 fixture 比对（四个 seam 都是简单变换，靠同语义实现与各自单测覆盖）；`run-workflow` 每次调用都推进一轮，调用方重复调用会重新识别而不是被幂等短路（除「保存成功但缺 `write-back` 行」这一种重放）。工具名 `ui-design-doc.*` 含连字符，Function Calling 的函数名归一同时处理 `.` 与 `-`。 +- 验证方式：`cargo test --bin genarrative-ai-game-creator-shell agent_tools` 覆盖检查点、识别/切分镜像与切图登记；`ui_design_doc` 与 `native_ui_design_doc_tools` 用例覆盖工具入参和函数名；`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。整套 Rust 用例在本容器仍有 9 条既有环境性失败（本地 HTTP 资源编辑器与 LLM 超时，改动前同样失败）。 + ## 2026-09-22 运行页收口：过程提示退出对话区，顶栏统一承载运行入口 - 背景：点播放（以及历史上 `/preview`、`/open-preview`、生成后自动启动预览）都会往对话区写一条 assistant 提示（`运行通过，已载入客户端运行视图：http://127.0.0.1:63155/` 这类）。它常驻对话底部遮挡运行画面，也让对话区混进非对话内容；运行页本身还有三处遮挡与两套皮：预览地址是一行常驻小字（不可点）、版本入口是绝对定位压在画面右上角的浮层、右上角还叠着「生成任务」开关。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 268c964de..0a3a42c64 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -318,6 +318,12 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\` - 成功 JSON 与错误响应体均复用 `readClientHttpResponseText` 的 15 秒上限；超时后保留最后一次有效目录并释放在途请求，手动重试重新发起请求。迟到的响应不得覆盖重试获得的新目录。 - 排查时区分接口未挂载（404）、未授权（401）、网络或响应体超时以及刷新无变化但缺少反馈；不能仅凭客户端启动 IPC 回退警告判断刷新失败原因。 +## 2026-09-14 未知 JS 异常必须继续进入 error report + +- **原则**：任何 JS 边界只要无法确认异常属于已知、已解决且有契约的业务失败，就必须保留原始异常并继续抛出，由全局 error report 链路采集；范围不限于 UI 编辑器、生成路径、剪贴板，也包括文件系统、权限、网络、插件和其它宿主调用。用户界面的 fallback（例如显示“复制失败，请手动复制”）只是附加的可继续操作提示，不代表异常已经被处理。 +- **易错点**：不要在 `catch` 中只设置 UI 文案然后结束，也不要把未知异常替换成新的泛化错误。需要用户 fallback 时，先更新提示，再重新抛出原始对象；只有已知且契约化的业务失败才可以在边界处转换为稳定的用户文案。 +- **关联**：`apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorCopyPathButton.tsx`、`docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md`。 + ## 2026-09-14 AGC 壳 Rust 套件按「一片一 job」拆分，且分片必须自校验覆盖 - **现象**：`AI game creator shell Rust tests` 一直是客户端 CI 的关键路径。run 2097 实测 15 分 27 秒，其中 `apps/ai-game-creator-shell/src-tauri` 的 bin target 单测（2466 条）一条 `cargo test -- --test-threads=1` 串行占 507 秒。 diff --git a/docs/project-memory/shared-memory/project-overview.md b/docs/project-memory/shared-memory/project-overview.md index 33a70abbc..a519a9249 100644 --- a/docs/project-memory/shared-memory/project-overview.md +++ b/docs/project-memory/shared-memory/project-overview.md @@ -67,7 +67,7 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐 - 2026-09-09 起，AGC 已新增遵循 OpenAI Agent Plugins 组合模型的通用 Plugin Host/SDK：Plugin、Skill 和 MCP 进入统一扩展 catalog；插件生命周期、行分隔 JSON-RPC、UI 面板、Capability Registry、权限和审计由 `plugin_host` 统一承接，Skill/MCP 仍分别交给各自现有 loader/transport；目标编辑器只通过通用 `EditorAdapter` 扩展点接入。详见 `docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md`。 - Unity 编辑器能力以 `plugins/agc-unity-editor` 内置插件提供，固定复用 Apache-2.0 的 DotCraft Attach 核心；Windows x64 / Unity Mono 接入不安装项目包。GUI、Runtime 与 DirectProject 通过现有 Runner 统一执行归属，跨进程回执与持久不确定阻断统一处理。首次打开 Unity 工程只初始化 AGC `.agent` 元数据，保留原引擎工程；详见 `docs/technical/【技术方案】AGC Unity编辑器插件接入-2026-09-18.md`。 - DirectProject 的 Codex 原生文件、搜索、命令、图片查看和 Skill 仅在用户项目 cwd 与 `workspaceWrite(writableRoots=[project])` 内可用；原生命令允许联网以支持 npm 安装，npm 缓存位于项目内 `.npm-cache/`。多 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制保持关闭。app-server 使用隔离 `CODEX_HOME`，provider 凭据只由 AGC 客户端代理持有，不能进入模型上下文或 shell 环境。 -- `ui-prototype`（设计图片）与 UI 编辑器 `UI` JSON 是不同资源。白名单 `ui.workflow.run` 按页面执行 `prepare → recognize → status → finalize`，由 provider-backed 识别、合并和组件绑定持久化 State/revision，并把 `reference-ready → structure-ready → merge-ready → binding-ready → application-ready → completed` 投影到 manifest。Provider 缺失、请求失败、工具缺失、结果不匹配或仍有待审节点时保留真实阶段并返回 blocker，不得用 deterministic seed 伪造完成。 +- `ui-prototype`（设计图片）与 UI 编辑器 `ui-design-doc` JSON 是不同资源。Agent 只通过三个工具驱动：`ui-design-doc.from-images` 由一至四张已登记设计图新建并登记文档（文档内设计图身份即图片 assetId），`ui-design-doc.run-workflow` 在 Rust 内跑 `recognize → separate → write-back` 并写回 State/revision，`ui-design-doc.into-js` 产出 `ui/generated-*.js`（不推进 revision）；三个工具都算项目变更观察（成功返回即算改过项目），其中只有前两个推进项目 revision；工具名与入参文案在 `prompts/runtime/texts/ui-design-doc.json`。Provider 缺失、请求失败、工具缺失或结果不匹配时保留真实 State 并返回错误，不得用 deterministic seed 伪造完成；旧 `ui.workflow.run`、多树合并、组件绑定与原型幂等桥接已退役，不保留兼容入口。 - UI workflow 的资源桥接与 Runtime 边界以 `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` 和 AGC 实施计划的 2026-08-24 覆盖段为准；只生成图片、登记空 JSON 或进入普通图片画布都不构成 workflow 完成。 ## 当前产品边界 diff --git a/docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md b/docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md index 12460d0e0..1445ac89a 100644 --- a/docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md +++ b/docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md @@ -4,6 +4,8 @@ `apps/ai-game-creator-shell` 的 UI 编辑器以 `useUiEditorSession` 作为视图与 adapter 的唯一协调边界。会话持有资源加载、revision、预览请求、选择、节点可见性、步骤 gate、异步操作和保存意图；`UiDesignStateStore` 与 Tauri 调用仍由该模块注入，不进入视图组件。 +实现层的深模块 seam 固定为：`features/ui-editor/stateTransition.ts`（React-free 语义 State transition）、`stateInvariants.ts`（保存前不变量 projection）、`nodeTransformGeometry.ts`（State 级节点几何）以及 `view/ui-editor/operationLifecycle.ts`（异步操作 adapter）。`useUiEditorState` 和 `useUiEditorSession` 只负责 React/history/lock 与平台 adapter 编排，不在视图中复制树遍历或几何反演。 + 页面与子视图不得再传递完整 controller。它们按职责读取以下小 projection： - `input`：资源输入、节点树及调试操作。 @@ -19,6 +21,18 @@ 保存与代码生成共享同一份持久化 State/revision。会话层在保存或生成进行期间互斥拦截，且代码生成必须基于已加载的持久化 revision；视图层的保存按钮和“保存并返回”按钮同步遵守该互斥状态。 +Rust UI workflow 的结构化 LLM 动作共享 `commands::utils::required_tool_arguments` seam：它只负责必需 tool-call 定位与有界 JSON 解析；prompt、schema、领域校验和 materializer 继续留在 recognition/binding/merge 各自 command。 + +UI 编辑器的普通“保存”和“保存并生成代码”结果使用独立结果弹窗呈现，不在编辑器内容区追加状态条。普通保存成功仅提示保存成功；保存并生成成功展示生成器返回的项目相对路径（例如 `ui/generated-xxx.js`），复制按钮通过 Tauri clipboard manager 的 `writeText` 写入剪贴板。复制失败时保留可选中文本并提示手动复制；设置用户 fallback 后仍必须重新抛出原始错误，让 error report 链路收到未知 / 未处理的异常，不能把异常静默吞掉。此异常传播原则适用于所有 JS 边界，不限于生成路径或剪贴板。两类操作失败均在弹窗中展示；组合操作若保存成功但生成失败，明确提示项目已保存，重试动作仍复用原操作。保存并返回成功后直接返回，不打开结果弹窗；结果弹窗关闭后不保留路径状态。 + +## 2026-09-14 多树预览与树级偏移 + +UI 编辑器预览同时渲染 State 中全部 `ui_trees`。每棵树的 `root.offset` 包含 `min` / `max`；当前仅读取 `min` 作为树 wrapper 的左上角，`max` 由 `min + 对应界面图 pixel_size / pixels_per_unit` 派生。所有新树必须经 `createTree` 创建：首棵树位置为 `[0, 0]`，后续树按现有树实际右边界最大值加固定 padding 横向排列，并与现有树最小 top 对齐。删除或排序不重排已有树。 + +预览中原图与树 root 共享同一空间，root 空白区域可拖动整树，拖动结束一次性写回 root offset 并进入撤销/重做；root 不提供 resize，子节点沿用既有手势。预览选中节点不改变左侧图片面板的 `activeImageId`，Inspector 通过节点所属树反查编辑目标。只有首次进入预览和用户手动点击“适配画布”使用全部树联合边界进行 fit。 + +原有 render mode 已拆为三个会话级临时开关：`showFrame=true`、`showOriginImage=true`、`showComponent=false`。普通节点框线/名称受 `showFrame` 控制，选中节点强调始终保留；原图和组件显示互不耦合。 + `UiDesignStateStore` 的 `generateCode(assetId)` 是必需能力，返回成功结果时不得为 nullable；所有注入的 adapter 与测试替身都必须实现该方法。 资源切换时，会话必须清理上一资源的保存/生成错误和生成中状态；普通保存开始时也清理代码生成错误。生成请求若因加载、锁定或 revision 等前置条件被拦截，必须向视图提供可见错误，而不是静默返回。 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index c5634f793..4f81fb017 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -1,5 +1,19 @@ # AI 游戏创作智能体 App 实施计划 +## 2026-09-23 UI 编辑器退役界面图参考语义建议 + +本节覆盖下文“2026-08-18 UI Editor 从属页面、手势与保存失败边界”中的 `UIDesignImage.metadata.slave_to` 口径，以及“界面语义建议”相关描述。 + +UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_semantic` 与 `UIDesignImage` 的 `metadata`（`name` / `description` / `role` / `slave_to`）整体退役，不保留兼容字段、回退路径或旧文档迁移：界面图只剩 `path`、`pixel_size`、`pixels_per_unit`；界面图之间不再存在持久化归属关系，结构识别按“每张界面图各自一棵树”执行；界面图在 UI 上的显示名统一取 `path` basename（`view/project-development/resourceAssetDisplayName.ts`），没有可选主页面过滤器、角色选择器和归属选择器。 + +多树合并当前不产生有效优先级：`merge` 的所有输入树优先级恒为 0（代码内留 `TODO`，等待重新设计），因此合并冲突时的代表节点取 `merged_from` 首位成员。旧的 `ui_design.json` 里残留的 `metadata` 字段由 serde 默认忽略，读取后不再写回；不新增拒绝或迁移逻辑。 + +| 要求 | 必须成立的行为 | 完成证据 | +| --- | --- | --- | +| 权威层收敛 | `resource/ui_design_image.rs` 只保留 `path` / `pixel_size` / `pixels_per_unit`；`commands/ui_design_suggestion.rs` 与 `suggest_ui_design_semantic` 注册删除；持久化校验不再有 `slave_to` 引用与环校验 | `cargo check`、`cargo test --bin genarrative-ai-game-creator-shell ui_editor`（160 passed） | +| 前端两步工作流 | `model.ts` 只保留“识别界面结构”“自动切分素材”；`ToolNavigation` 渲染两格；suggestion 操作、结果通知分支、role/slave_to 编辑器与 `ImportOverview`（原“分析参考图”步骤概览）全部删除 | `npx vitest run uiEditorPage/uiEditorState/uiDesignStateStore/previewWorkspaceZoom/appSurface` | +| 无迁移 | 旧文档中的 `metadata` 被静默忽略并在下次保存时消失，`ui_trees` 不受影响；不做迁移脚本或写入回填 | `persistence.rs` 既有加载/保存用例 | + ## 当前策划入口与退役边界 策划 V1、策划会话 Runtime V2 均已删除，当前“做方案”只使用独立 Design Agent，现行合同见[策划 Agent 生产迁移与工作区浏览](./【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。旧 V1/V2 Runtime、命令、会话、审批卡、身份白名单和专属测试不作为兼容或恢复目标；历史方案中的 lifecycle v3、planning binding 等要求不能作为孤立代码的保留依据。共享能力按现役调用判断，不因名称相似删除当前 Design Agent 或通用 Runtime。 @@ -1739,3 +1753,10 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面 `AgentRuntimeErrorEvent` 把失败投影到用户消息、运行面板和项目内 `.agent/runtime/errors/.json` 时，同一份已脱敏诊断还要投影成 AppData `diagnostics/application.log` 的两行：`agent.runtime.error`（身份行：`eventId / source / stage / code / retryable / clientTurnId / elapsedMs / detailRef`）与 `agent.runtime.error.detail`（详情行：`hint / summary / detail / metadata`）。原因是项目内 sidecar 只在项目目录可见，而“报告问题”只上传应用级日志：没有这两行时，用户提交的失败消息里只剩一个 `详情：.agent/runtime/errors/...json` 路径，团队拿不到诊断正文。 口径：两行都由 `agent/runtime_error.rs` 从同一份 diagnosis 生成，字段不退化成第二份来源；`summary` 按 320 字符、`detail` 与 `metadata` 按（1200 / 200 字符）预算先脱敏再截断，落盘前还会被 `sanitize_diagnostic_message` 二次脱敏并按行截断，因此自由文本字段在行内先压平换行。拆两行是因为整行一旦出现凭据标记会被整体替换成脱敏占位：所以**自由文本（summary / hint / detail）只放详情行**，身份行只留程序生成与调用方常量字段，详情行被整体脱敏时事件仍能按 eventId / detailRef 定位。写日志先于写 sidecar：sidecar 失败不能连日志一起丢。 + +## 2026-09-23 AGC UI 设计文档 Agent 工具化重写 + +- `ui.workflow.run` 单工具（`discover → prepare → recognize → merge → binding → status → finalize`）整体退役：它的参数就是工作流状态，任一步失败只能整轮重来，步骤产物又由前端会话落盘，Agent 侧没有任何恢复点。同时退役 `merge.rs`、`binding.rs`、`workflow.rs`、`ensure_ui_design_resource_for_prototype`（原型 → 文档的幂等查找）、`ui/ui-workflow-.json` 命名与 `ui-workflow.*` manifest 阶段，均不保留兼容、迁移或 fallback。 +- 当前只保留三个工具：`ui-design-doc.from-images`（一至四张设计图 → 新建并登记文档，返回 `assetId` 与 `relativePath`，无状态）、`ui-design-doc.run-workflow`（`recognize → separate → write-back`，唯一带崩溃恢复的工具）、`ui-design-doc.into-js`（渲染 `ui/generated--.js`，无状态、不推进 revision）。项目根目录、项目 ID 与 provider 身份由 Runtime 注入，模型只给设计图引用或文档 `assetId`。 +- `run-workflow` 的恢复判据只有一条：这一步有没有对应、且带着 State 快照的检查点行。检查点是文档旁追加式 JSONL（`ui/.<文档名>-workflow.jsonl`），行类型为 `run` / `recognize` / `separate` / `write-back` / `outdated`，`run` 行带本轮起始 State，`recognize` / `separate` 行带该步应用完之后的 State。恢复只读快照、整步跳过已完成步骤，只把新完成那一步的改动应用到文档，绝不照 DTO 重放（重放会重复登记切图、重复累加回填出错说明）；只有 DTO 的旧行按未完成重跑。一轮以 `run` 开头、以首个 `write-back` 或 `outdated` 结束；只有最后一轮没有结束行时才恢复。追加前先截断崩溃留下的半行，文档中途漂移（当前 State 既不是 `run` 行快照、也不是切分后那份快照）时追加 `outdated` 并返回错误，由下一次调用显式开新一轮，不在同一次调用里自动重启。切图资源失败不回滚，靠 manifest 的 by-path 复用接上；切分 op 内部更细粒度的恢复仍由 `SeparationState` sidecar 承担，检查点日志不复制它的进度。 +- 三个工具的描述与参数文案都在 `prompts/runtime/texts/ui-design-doc.json`（目录 ID `uiDesignDoc`），Rust 侧不得硬编码面向模型的长文案。策划 `design-foundation` 的自主构建白名单同步登记这三个工具，命令映射复用 `asset.register` / `file.write`。 diff --git a/docs/technical/【技术方案】UI编辑器Agent工具化重写-2026-09-23.md b/docs/technical/【技术方案】UI编辑器Agent工具化重写-2026-09-23.md new file mode 100644 index 000000000..197f3220e --- /dev/null +++ b/docs/technical/【技术方案】UI编辑器Agent工具化重写-2026-09-23.md @@ -0,0 +1,111 @@ +# UI 编辑器 Agent 工具化重写 + +更新时间：`2026-09-23` + +一句话定位：把 UI 编辑器今天由前端会话编排、由单个 `ui.workflow.run` 驱动的 Agent 链路，重写成三个各自只做一件事的工具——建文档、跑工作流、出 JS——且只有工作流工具带逐步骤崩溃恢复。 + +## 现状与问题 + +- `ui.workflow.run`（已退役）把发现页面、桥接设计图、结构识别、多树合并、组件绑定、回读、finalize 全塞进一个工具，工具参数本身就是工作流状态：模型不能只做其中一步，任何一步失败都只能整轮重来。 +- 步骤产物由前端 `useUiEditorPage.ts` 落 State 再保存，Agent 侧没有任何恢复点。 +- `merge` / `binding` 两条实验链路无现役价值，已随工具一起退役（`ui_editor/commands/merge.rs`、`binding.rs`、`ui_editor/workflow.rs` 已删除）。 + +## 工具契约 + +| 工具 | 输入 | 输出 | 恢复 | +| --- | --- | --- | --- | +| `ui-design-doc.from-images` | 1–4 张设计图，每张给 manifest `assetId` 或项目内相对路径 | 新建文档的 `assetId` 与 `relativePath` | 无状态 | +| `ui-design-doc.run-workflow` | 文档 `assetId` | 各步骤摘要与文档新 `revision` | 逐步骤 JSONL 检查点 | +| `ui-design-doc.into-js` | 文档 `assetId` | `ui/generated--.js` 路径与导出树 | 无状态 | + +工具名用 `<域>.<动作>` 形式，域内动作保留连字符（`from-images`、`run-workflow`、`into-js`）；调用这些工具时项目根目录仍由 Runtime 注入，模型不得传入宿主路径。 + +### 建文档：`ui-design-doc.from-images` + +- 文档内设计图 id 直接采用该图在 manifest 里的 `assetId`；输入给相对路径时先登记成资源再用它的 `assetId`，不额外发明文档内身份。 +- 文档文件名沿用 `ui/UI 设计 N.json` 取号，不登记半成品命名（旧 `ui/ui-workflow-.json` 口径废弃）。 +- 每次调用都新建一份文档并登记：不做「原型 → 已存在文档」的幂等查找，原 `ensure_ui_design_resource_for_prototype` 的复用分支随之删除。 +- 建项与登记在项目写锁内完成；写盘失败要回滚已登记的 manifest 条目，不留半成品。 + +### 工作流：`ui-design-doc.run-workflow` + +只做三步，全部在 Rust 内完成，结果不回传前端编排： + +| 步骤 | 实现 | 产物 | +| --- | --- | --- | +| `recognize` | `recognize_ui_impl_with_provider` | `ui_trees`（每棵树的 `src_ui_design` 指向文档内设计图） | +| `separate` | `separate_ui_impl` | 切分图落盘 → 登记 asset → 转 `SpriteAsset` → 写入 State → 回填 `target_graphic`、清 `component_status`、写 `NeedReview` | +| `write-back` | `save_ui_design_state_at` | 文档新 `revision`；没有回填问题且没有问题节点时再 `finalize_separation` 清理 sidecar | + +不再有合并、组件绑定与页面级 profile/finalize 阶段；`recognize` 之前不做任何前置发现。 + +`NeedReview` 与 `component_status` 的清理是 `separation` DTO 的一部分：问题节点由 DTO 的 +`problematic_nodes` 给出，编排阶段统一回写，重放时不需要模型再判一次；文案与判据镜像 +前端 `features/ui-editor/separationStatus.ts`。 + +## 崩溃恢复 + +检查点是文档旁一条追加式 JSONL 日志，方案与被否方案见 [ADR：UI 工作流检查点用追加式 JSONL 日志](../adr/【ADR】UI工作流检查点用追加式JSONL日志-2026-09-23.md)。 + +- 位置：`ui/.<文档文件名去扩展名>-workflow.jsonl`，与文档同级，不进 manifest、不推进项目 revision。 +- 行格式：`run`（原始 State 快照 + 起始 revision）、`recognize`（DTO + 该步应用完的 State 快照）、`separate`（DTO + 该步应用完的 State 快照 + 回填说明）、`write-back`（新 revision）、`outdated`（本轮作废原因）；行内另带 `at` 时间戳。 +- 判据只有一条：「本步有没有对应的行」。每行必须一次性原子追加，崩溃留下的半行一律视为该步未完成。 +- 恢复只看快照、不重放步骤：已完成的步骤在检查点里带着那一步应用完之后的 State 快照，恢复时直接读回这份 State 并整步跳过，不按记录下来的 DTO 重放该步 delta——重放会重复登记切图、重复累加回填说明，把同一份错误报两遍。只有带状态快照的行才算已完成，旧格式（只有 DTO）的行按未完成重跑。 +- 轮次：一轮以 `run` 行开头，以该轮第一行 `write-back` 或 `outdated` 结束；只有最后一轮没有结束行时才需要恢复。`outdated` 只作废未完成的那一轮，不删除既有行。 +- 半行：追加前先把日志截断到最后一个换行，丢掉崩溃留下的半行，避免它夹在日志中间。 +- 漂移：文档在轮次中途被改动（当前 State 既不是 `run` 行快照、也不是切分后那份快照）时，追加一行 `outdated` 并**返回错误**，不在同一次调用里自动重开新一轮；下一次调用看到 `outdated` 才从头开新一轮，且以当前文档为基准。 +- 写回幂等：`save` 成功但 `write-back` 行没追加时，恢复读回的切分后 State 与文档当前 State 相等，即判为已写完，直接补 `write-back` 行并返回成功。这条判据成立的前提是工作流这条路不产生随机身份：识别树的根节点 id 来自 DTO，切图资源 id 走 manifest 的 by-path 复用。 +- 切图资源不回滚：切分产出的图片与已登记资源在失败后保留，重放靠 by-path 复用接上，不做回滚清理。 +- 写回成功后才清理 sidecar：与前端切分链路一致，`backfill_errors` 为空且 `problematic_nodes` 为空时调用 + `finalize_separation`；有回填问题或问题节点时保留 sidecar，交给编辑器显示恢复入口。 +- 切分 op 内部的细粒度恢复仍由 `SeparationState` 承担（`ui-editor-separation-state.v2` sidecar），日志只记录工作流层面的步骤完成，不复制它的进度。 +- 不引入跨语言 fixture 比对：镜像的四个 seam 都是简单变换，靠同语义实现与各自单测覆盖，不为它们额外维护一套 golden。 + +## 模块布局 + +### Rust + +```text +src/ui_editor/agent_tools/ +├─ mod.rs 模块声明与三个工具的对外导出 +├─ creation.rs from-images：登记图片、建文档、manifest 注册、命名取号 +├─ checkpoint.rs JSONL 追加、读取、轮次判定 +├─ run_workflow.rs recognize → separate → write-back 编排与恢复 +├─ steps/ +│ ├─ mod.rs 步骤子模块声明 +│ ├─ recognize.rs 识别 DTO 落 State +│ ├─ separate/ +│ │ ├─ mod.rs 切分 DTO 落 State（回填、清状态、写 NeedReview） +│ │ └─ cut_images.rs 切图图片登记与 SpriteAsset 构造 +│ └─ write_back.rs 保存 State、记 write-back / outdated 行、漂移文案 +└─ test_support.rs agent_tools 单测共用夹具 +src/agent/runtime_tools/ui_design_doc.rs 工具参数解析与 Runtime 侧调用 +``` + +`into-js` 不需要独立模块：它直接复用 `persistence.rs` 的 `generate_ui_design_code_at`， +该入口本来就只渲染 `ui/generated--.js` 且不推进项目 revision。 + +每个文件只承担一件事；`checkpoint.rs` 不感知切分，`creation.rs` 不感知识别。 + +### 提示词目录模块 + +工具描述与参数文案一律进 `src-tauri/prompts/runtime/`，不在 Rust 里硬编码面向模型的中文长文案： + +- 新增文本目录 `texts/ui-design-doc.json`，在 `manifest.json` 的 `textCatalogs` 登记为 `uiDesignDoc`。 +- 键名规则 `<工具名>.<字段>`，工具名用下划线形式：`from_images.description`、`run_workflow.parameters.designDocAssetId` 等；Rust 侧用 `prompt_text!("uiDesignDoc.from_images.description")` 引用。 +- 构建期 `build_support/runtime_prompt_bundle.rs` 会校验目录已登记、key 非空、bundle 内没有未登记的 `.md`/`.json`，因此新增文件必须同步 `manifest.json`。 + +## 落地顺序（全部已完成） + +1. 清理 legacy：`ui.workflow.run`、`merge`、`binding` 与前端合并调用。 +2. 术语与 ADR：`CONTEXT.md` 四个词条、检查点 ADR。 +3. 本文档。 +4. 提示词目录模块 + 两个无状态工具（`from-images`、`into-js`）。 +5. `run-workflow` 与 JSONL 检查点（`agent_tools/{checkpoint,run_workflow}.rs` + `steps/separate/`）。 +6. 前端收口：删 `uiDesignResourceBridge` 的 `ui-workflow.*` 优先级与 `project-development` 的自动打开分支。 +7. 三个工具注册进 Runtime（`agent_native_tools`、`runtime_tools/ui_design_doc.rs`、可执行工具目录、并行账本映射、design-foundation 白名单）。 + +## 关联文档 + +- [UI 编辑器代码地图与模块职责](./【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md) +- [UI 编辑器自动切分素材工作流](./【技术方案】UI编辑器自动切分素材工作流-2026-09-08.md) diff --git a/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md b/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md new file mode 100644 index 000000000..c1ef44d01 --- /dev/null +++ b/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md @@ -0,0 +1,74 @@ +# UI 编辑器代码地图与模块职责 + +更新时间：`2026-09-23` + +一句话定位：`apps/ai-game-creator-shell` 的 UI 编辑器由「Rust/Tauri 权威层 + React 会话层 + 视图层」三段组成；Rust 持有可持久化 State、校验、LLM 工具链、预览渲染与代码生成，前端只负责语义编辑、会话编排和表现。 + +## 分层与数据流 + +```text +view/ui-editor (页面/组件) + └─ useUiEditorSession ← features/ui-editor (语义 + adapter) + ├─ useUiEditorState / stateTransition / nodeTransformGeometry + ├─ uiDesignStateStore → Tauri command + └─ invoke: recognize_ui / separate_ui / ... + └─ src-tauri/src/ui_editor (权威 State、校验、持久化、切分) +``` + +- 唯一事实来源是项目内的 `ui_design` JSON 文档（含 `revision`），前端 State 只是它的编辑副本。 +- 所有跨进程类型由 Rust 经 `ts_rs` 生成到 `features/ui-editor/types/`（当前 53 个文件），前端不得手改。 + +## Rust 侧：`src-tauri/src/ui_editor` + +| 模块 | 职责 | +| --- | --- | +| `state/mod.rs` | 权威 State 根类型：`State`（`ui_trees` + 界面图/sprite/字体三张资源表）、`UITree`；ts-rs 导出源 | +| `layout/` | 节点模型：`Node`、`NodeMetadata`/`StageStatus`、`ControlLayout`、`Container`、`NodeOffset`、`transform`、`ChildrenDisplayMode`（`Stack`/`Exclusive`） | +| `component/` | 组件枚举 `Component::{Image, Text}`、`NodeComponent`（LLM 工具载荷的 `PureNode`/`WithComponent` 判别式） | +| `resource/` | 界面图（`path` / `pixel_size` / `pixels_per_unit`）、sprite（含 `SpriteBorder` 九宫格）、字体（格式/媒体类型/CSS format）资源描述 | +| `persistence.rs` | 文档读写、`revision` 乐观并发保存、领域校验（重复 ID、树/资源引用、组件状态）、代码生成写盘 | +| `agent_tools/` | Agent 工具链路：`creation.rs` 用一至四张设计图新建文档（登记未登记图片、按 `ui/UI 设计 N.json` 取号、持项目写锁装 revision 0、失败回滚）、`checkpoint.rs` JSONL 检查点日志、`run_workflow.rs` 三步编排与崩溃恢复（恢复只读检查点里的 State 快照、整步跳过已完成步骤，不按 DTO 重放）、`steps/` 逐步落 State（`mod.rs` 步骤子模块声明、`recognize.rs` 识别、`separate/` 切分：`cut_images.rs` 登记切图与 `SpriteAsset` 构造、`mod.rs` 回填与问题状态、`write_back.rs` 保存与漂移文案） | +| `html_renderer/` | 由 State 生成 HTML 片段与 JS（maud + 布局/组件 CSS 映射），供预览与 `ui/generated-*.js` | +| `commands/` | LLM 工具链：`recognition`（结构识别）、`separation/`（自动切分素材）、`utils.rs`（LLM 请求、重试、`required_tool_arguments`） | +| `commands/separation/` | 切分批处理、截图/预切、sidecar 恢复（inspect / finalize / discard）、patch 回写 | + +Agent 工具（`agent_native_tools.rs` + `agent/runtime_tools/ui_design_doc.rs`）：`ui-design-doc.from-images` 新建文档并登记；`ui-design-doc.run-workflow` 在 Rust 内跑 `recognize → separate → write-back`，按文档旁 JSONL 检查点恢复；`ui-design-doc.into-js` 复用 `generate_ui_design_code_at` 产出 `ui/generated-*.js`，不推进 revision。旧 `ui.workflow.run` 与 `ensure_ui_design_resource_for_prototype` 已退役。 + +关键命令（`main.rs` 注册）：`load_ui_design_state`、`save_ui_design_state`、`generate_ui_design_code`、`create_ui_design_doc_from_images`、`recognize_ui`、`separate_ui`、`inspect_separation_recovery`、`finalize_separation`、`discard_separation_recovery`。 + +保存语义（`save_ui_design_state_at`）：`Saved` / `Unchanged` / `Conflict`（返回当前快照）三态；先 `validate_state` 再持锁重读比对 `expected_revision`，成功后推进项目 revision。代码生成只接受已保存的 revision，产物路径为 `ui/generated--.js`。 + +## 前端：`src/features/ui-editor`（无视图依赖的语义层） + +- `useUiEditorState.ts`：State reducer + 撤销/重做（`undo/redo/resetHistory`）、`isLocked` 与 `runWithStateLocked`、节点/资源/树偏移的语义写操作、`createTree`（新树横向排布 + `UI_TREE_PADDING`）、删除影响 projection。 +- `stateTransition.ts`：React-free 的命令 → State 语义 transition（`set-tree-offset`、`set-node-metadata`、`set-node-component`）。 +- `nodeTransformGeometry.ts`：State 级节点几何（页面矩形、父矩形、resize 手柄反演），预览/Inspector 共用。 +- `stateInvariants.ts`：保存前不变量 projection，给视图稳定的中文失败信息；Rust 仍是权威校验。 +- `uiDesignStateStore.ts`：`IUiDesignStateStore`（`load`/`save`/`generateCode`）+ Tauri 实现 + 内存替身。 +- 结果应用 seam：`recognition.ts`、`separationStatus.ts`（问题节点 → `NeedReview`）。 +- 概览 projection：`stageStatusOverview.ts`、`separationOverview.ts`。 +- 前置校验：`requisites.ts` 在发起 LLM 操作前检查必需资源与结果完整性。 +- 适配器：`importAdapter.ts`（图片解码、批量导入、字体准备）、`uiDesignResourceBridge.ts`（调用 `create_ui_design_doc_from_images` 新建文档）、`useUiEditorFontFaces.ts`（私有字体族加载）、`spriteBorder.ts`。 +- `utils/`：State → CSS 映射（`componentToCss`、`controlLayoutToCss`、`textStyleToCss`、`transform/tf2css`）、`treeUtils`。 + +## 前端：`src/view/ui-editor`（表现与编排） + +- `useUiEditorPage.ts`：`useUiEditorSession` 是视图与 adapter 的唯一协调边界，产出 `input` / `canvas` / `inspector` / `workflow` / `dialogs` / `save` 六个小 projection；视图不接收完整 controller。 +- `index.tsx`：页面骨架（输入侧栏、预览、Inspector、工具栏、保存/生成结果弹窗、键盘快捷键绑定），由 `view/project-development` 挂载。 +- `model.ts`：两步工作流（识别界面结构 / 自动切分素材）、导入种类、操作失败文案。 +- `operationLifecycle.ts`：recognition/separation 共用的异步操作 adapter。 +- `components/`：`InputSidebar`、`UiTreePanel`、`Inspector/*`（Transform、Components Text/Image、SpriteBorder）、`preview/*`（`PreviewWorkspace`、`UiTreeRenderer`、组件视图、排他子节点 tab、缩放/平移/拖拽手势）、工作流与结果弹窗。界面图没有独立显示名字段，列表与 Inspector 的统一显示名取 `path` basename（`view/project-development/resourceAssetDisplayName.ts`）。 +- 已退役的 render mode 由会话级开关 `showFrame` / `showOriginImage` / `showComponent` 取代。 + +## 扩展指引 + +- 新增节点/组件字段：先改 `layout/`（或 `component/`）并让 ts-rs 重新导出，再补 `stateTransition`、`stateInvariants`、`persistence::validate_node`、Inspector 与预览映射。 +- 新增 LLM 步骤：在 `commands/` 内自成 command（prompt + schema + 领域校验 + materializer），共用 `commands::utils` 的请求、重试与 tool-call 解析 seam。 +- 新增界面图字段：改 `resource/ui_design_image.rs` 后让 ts-rs 重新导出，再补 `persistence::validate_state`、导入 adapter（`features/ui-editor/importAdapter.ts`）与 Inspector / 预览展示。 + +## 关联文档 + +- [UI 编辑会话模块边界](./【前端架构】UI编辑会话模块边界-2026-08-19.md) +- [UI 编辑器 Godot 容器布局模型](./【技术方案】UI编辑器Godot容器布局模型-2026-08-18.md) +- [UI 编辑器子节点显示规则](./【技术方案】UI编辑器子节点显示规则-2026-08-18.md) +- [UI 编辑器自动切分素材工作流](./【技术方案】UI编辑器自动切分素材工作流-2026-09-08.md) diff --git a/docs/technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md b/docs/technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md index 385dcea54..f2d93702d 100644 --- a/docs/technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md +++ b/docs/technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md @@ -2,11 +2,11 @@ ## 目标 -UI 编辑器的“分析参考图”“识别界面结构”“自动切分素材”三个工作流动作在每次运行结束后，用独立的阻塞通知弹窗明确反馈结果，避免仅依赖卡片内一行状态文本而被忽略。 +UI 编辑器的“识别界面结构”“自动切分素材”两个工作流动作在每次运行结束后，用独立的阻塞通知弹窗明确反馈结果，避免仅依赖卡片内一行状态文本而被忽略。 ## 交互约定 -- 三个动作的每次运行在终态（成功或失败）时自动弹出一次通知。 +- 两个动作的每次运行在终态（成功或失败）时自动弹出一次通知。 - 弹窗打开期间遮挡并阻塞工作台底层交互；关闭后恢复当前步骤，不自动切换步骤、不自动重跑。 - 使用现有 `ThemedModal` 的普通关闭行为（遮罩、Esc 和关闭按钮均可关闭）。 - 弹窗仅承载通知，不提供“继续”“重试”或其他业务操作。 @@ -19,7 +19,6 @@ UI 编辑器的“分析参考图”“识别界面结构”“自动切分素 成功状态的基线文案： -- 分析参考图：保留已应用的语义建议数量；若现有状态可可靠取得问题/待确认数量，则一并展示。 - 识别界面结构：保留替换的界面树数量，并展示识别结果中的待检查/必须修复数量（若可取得）。 - 自动切分素材：保留现有 `B/B` 批次计数，改为用户可读的切分结果。 @@ -28,12 +27,12 @@ UI 编辑器的“分析参考图”“识别界面结构”“自动切分素 ## 实现边界 - 新增独立的工作流通知弹窗组件文件，组件只负责展示和关闭，不包含工作流领域规则或后端副作用。 -- 在 UI 编辑器页面/会话投影中维护临时通知状态，并在三个异步动作的成功与失败终态写入。 +- 在 UI 编辑器页面/会话投影中维护临时通知状态，并在两个异步动作的成功与失败终态写入。 - 不新增后端字段或公开契约；数量只能使用当前前端已有且可靠的数据。 ## 验收 -1. 三个动作成功和失败终态各弹出一次通知；绑定批次只弹最终一次。 +1. 两个动作成功和失败终态各弹出一次通知；绑定批次只弹最终一次。 2. 弹窗打开时底层工作台不可操作，且无继续/重试等业务按钮。 3. 弹窗可通过标准关闭方式退出；关闭后卡片状态仍可见。 4. 每条成功文案保留原有数量信息并增加可用的检查数量，所有文案包含“请检查”。 diff --git a/docs/【UI编辑器】拖动变换提交边界-2026-09-03.md b/docs/【UI编辑器】拖动变换提交边界-2026-09-03.md index 6988d039d..0126fa762 100644 --- a/docs/【UI编辑器】拖动变换提交边界-2026-09-03.md +++ b/docs/【UI编辑器】拖动变换提交边界-2026-09-03.md @@ -6,9 +6,13 @@ UI 编辑器预览中的节点拖动和缩放在指针移动期间只更新预 指针取消、页面切换、树切换、组件卸载或没有超过拖动阈值时，不提交变换，并清理临时预览值。指针松开后的最终变换属于正常 State 修改，会参与脏状态、保存和后端持久化；仅拖动期间的临时变换不会进入这些流程。资产文件也不会因该交互被删除。 +画布视口平移（空格+左键、中键、右键拖拽）属于视图操作：只改前端视口，不写编辑器 State，也不进撤销重做历史。右键同时承载节点菜单，两者按同一个拖动阈值互斥——按下后越过阈值即判定为平移，抬起时不再弹菜单；未越阈值且在预览内抬起才弹节点菜单。预览内按钮 2 的 `contextmenu` 由预览拦截（按下即触发，不能等到手势结束），因此右键菜单在指针抬起时才出现。 + ## 实现边界 - `useNodeTransformInteraction` 保存手势起始变换和最后一次有效变换。 - `UiTreeRenderer` 通过 `previewTransforms` 渲染临时变换。 - `canvas.updateNodeTransform` 仅在 `pointerup` 提交，`pointercancel` 不提交。 - 拖动和缩放继续共用单指针捕获与有限数校验。 +- 拖动阈值抽到 `previewDragThreshold.ts`，左键拖动与右键平移共用同一个 `DRAG_THRESHOLD_SCREEN_PX`。 +- 右键平移与菜单裁决放在预览的 `previewRightPanGesture.ts` 纯状态机里，`useNodeTransformInteraction` 只负责左键拖动与缩放。 diff --git a/docs/【交互设计】预览画布缩放滑杆-2026-09-05.md b/docs/【交互设计】预览画布缩放滑杆-2026-09-05.md index 5d35bf013..7b21c9a35 100644 --- a/docs/【交互设计】预览画布缩放滑杆-2026-09-05.md +++ b/docs/【交互设计】预览画布缩放滑杆-2026-09-05.md @@ -20,6 +20,7 @@ - 仅在存在可缩放视口且确认命中快捷键时调用 `preventDefault()` 与 `stopPropagation()`，防止浏览器页面同时缩放。 - 保留现有 `Ctrl/Cmd+0` 适配画布与 `Ctrl/Cmd+1` 恢复 100% 行为，不增加其他重置快捷键。缩放仍是当前预览实例的临时 UI 状态。 - 快捷键和百分比使用逻辑 `viewport.scale` 作为缩放真相；共享 `CanvasWorld` 的渲染 transform 可能包含超采样换算，验证时不得直接把 CSS transform 值当作用户可见比例。 +- 预览画布背景继续使用圆点网格，并按 `14/28/56/112…` 世界步长的 2 倍档位自适应缩放；屏幕间距目标约为 20–40px，缩放过小时自动加倍步长、放大时自动减半步长。网格背景位置继续跟随 `viewport.x/y`，保持世界原点对齐，不改变圆点样式。 - 保留快捷键与缩放焦点边界的组件级回归测试，不扩展端到端测试。 ## 验收 diff --git a/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md b/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md index 7a99366ca..7cd878636 100644 --- a/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md +++ b/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md @@ -66,6 +66,7 @@ - `docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md` - `docs/technical/【技术说明】AGC接第三方Provider的兼容性缺陷-2026-08-19.md` - `docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md` +- `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` 这些文件保留用于追溯；若其中仍有有效结论，应先融合到当前专题，再删除重复表述。 diff --git a/docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md b/docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md index 847d62b75..1aa5fcaaf 100644 --- a/docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md +++ b/docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md @@ -1,4 +1,9 @@ # UI 工作流资源桥接与 Runtime 执行 +> 文档状态：`historical` +本方案描述的 `ui.workflow.run` 单工具、`discover → prepare → recognize → merge → binding → status → finalize` 阶段、 +`ensure_ui_design_resource_for_prototype` 幂等桥接与 `.agent/ui-workflows/.json` 回执均已退役， +仅用于追溯。当前 Agent 链路见 [`【技术方案】UI编辑器Agent工具化重写-2026-09-23.md`](./technical/【技术方案】UI编辑器Agent工具化重写-2026-09-23.md)： +三个工具分别为 `ui-design-doc.from-images`、`ui-design-doc.run-workflow`、`ui-design-doc.into-js`。 ## 目标 @@ -87,9 +92,9 @@ JSON 文档读取、State 校验或 renderer 失败时，在同一引用后追 - 按 manifest asset id、`source.resourceId`、`source.assetObjectId` 识别已有关联，避免重复创建。 - 没有关联时原子创建 `ui/UI 设计 N.json`，登记 `kind=ui-design-doc`、`application/json`，并把原型图作为首张页面设计图载入 State。 -- 成功后通过 `onManifestChange` 更新客户端资源投影，再打开 UI 编辑器；普通桥接从 `reference-analysis` 开始。 +- 成功后通过 `onManifestChange` 更新客户端资源投影，再打开 UI 编辑器；普通桥接从 `structure-recognition` 开始。 -点击已有 `ui-design-doc` 资源直接打开 UI 编辑器。若 manifest 阶段为 `ui-workflow.completed`，工作台自动打开该资源的 `asset-separation` 阶段（最远步骤为 2），交给用户做最终检查和手动调整。 +点击已有 `ui-design-doc` 资源直接打开 UI 编辑器。若 manifest 阶段为 `ui-workflow.completed`，工作台自动打开该资源的 `asset-separation` 阶段（最远步骤为 `asset-separation`），交给用户做最终检查和手动调整。 自动切分达到返工上限的 problematic 节点会随分离 DTO 返回每节点的 `problem_history`，并由编辑器回写为 `component_status = NeedReview(...)`。`SeparationOverview` 只读取 UI State 中的状态来计数和定位；该结果仍按“已尽力完成”报告成功并执行既有 finalize，剩余节点由用户在概览定位后手动处理或再次发起分离。