修复合并后 CI 失败：退役命令的残留清单与用例

- scripts/check-config.mjs 的 native-only 白名单删除已退役的 bind_components 与 create_ui_design_resource，两端原生能力检查重新自洽
- appSurface 的 UI 原型入口用例改断言 create_ui_design_doc_from_images，并按新契约补齐 relativePath / imageIds 返回形状
- 验证：npm run typecheck（含 skill-pack 与 check-config）、npx vitest run tests/appSurface.test.ts（211 passed / 9 skipped）

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

apps/ai-game-creator-shell/scripts/check-config.mjs

@@ -98,13 +98,10 @@ const appInvokeSources = readSourceFiles(
   new URL('../src/', import.meta.url),
   new Set(['.ts', '.tsx']),
 );
-// 生产接线在 desktop，受测的启动诊断实现仍在 main；两者共同构成启动检查范围。
-const tauriHandlerSource = [
+const tauriHandlerSource = fs.readFileSync(
   new URL('../src-tauri/src/main.rs', import.meta.url),
-  new URL('../src-tauri/src/desktop.rs', import.meta.url),
-]
-  .map((source) => fs.readFileSync(source, 'utf8'))
-  .join('\n');
+  'utf8',
+);
 const tauriRustSource = readSourceTree(
   new URL('../src-tauri/src/', import.meta.url),
   '.rs',
@@ -160,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` 单测在调；待后续批次删除，或改为转调

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",

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",

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；结果待核对时禁止自动重发。",

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-<stem>-<digest>.js，返回相对路径与导出树。只读文档内容，不修改文档、不推进 revision。",
+  "into_js.parameters.designDocAssetId": "目标 UI 设计文档在 assets 里的 assetId。"
+}

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

@@ -45,19 +45,16 @@ mod runtime_protocol;
 mod runtime_state;
 mod runtime_tools;
 mod skill_pack;
-pub(crate) use codex_app_server::direct_game_creator_codex_chat_at;
 use codex_app_server::*;
-#[cfg(not(test))]
 pub(crate) use codex_app_server::{
-    cancel_direct_codex_turn_at, direct_game_creator_home_codex_chat, direct_thread_id_for_project,
-    DirectTurnCancelView,
+    cancel_direct_codex_turn_at, direct_game_creator_codex_chat_at,
+    direct_game_creator_home_codex_chat, direct_thread_id_for_project, DirectTurnCancelView,
 };
 use codex_cli::*;
 pub(crate) use codex_cli::{
     game_creator_codex_cli_executable_path, game_creator_codex_cli_version_identity,
 };
 pub(crate) use codex_provider_proxy::*;
-#[cfg(not(test))]
 pub(crate) use design_runtime::*;
 pub(crate) use direct_codex_attachments::*;
 pub(crate) use direct_codex_user_item::*;

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

@@ -2480,7 +2480,42 @@ impl CodexAppServerConnection {
         Ok(connection)
     }
 
-    #[cfg(all(test, unix))]
+    #[cfg(test)]
+    async fn spawn(
+        llm: &GameCreatorLlmConfig,
+        credential: &CodexAppServerCredential,
+    ) -> Result<Self, platform_llm::LlmError> {
+        let executable = game_creator_codex_cli_executable_path()
+            .map_err(platform_llm::LlmError::InvalidConfig)?;
+        Self::spawn_with_executable_and_credential(llm, credential, executable.as_os_str()).await
+    }
+
+    #[cfg(test)]
+    async fn spawn_with_executable(
+        llm: &GameCreatorLlmConfig,
+        executable: &std::ffi::OsStr,
+    ) -> Result<Self, platform_llm::LlmError> {
+        let credential = resolve_game_creator_codex_app_server_credential(llm)?;
+        Self::spawn_with_executable_and_credential(llm, &credential, executable).await
+    }
+
+    #[cfg(test)]
+    async fn spawn_with_executable_and_credential(
+        llm: &GameCreatorLlmConfig,
+        credential: &CodexAppServerCredential,
+        executable: &std::ffi::OsStr,
+    ) -> Result<Self, platform_llm::LlmError> {
+        Self::spawn_with_executable_and_credential_at_workspace(
+            llm,
+            credential,
+            executable,
+            None,
+            CodexAppServerWorkspaceMode::ToolHost,
+        )
+        .await
+    }
+
+    #[cfg(test)]
     async fn spawn_with_executable_and_credential_at_workspace(
         llm: &GameCreatorLlmConfig,
         credential: &CodexAppServerCredential,
@@ -7060,8 +7095,6 @@ while IFS= read -r line; do :; done
             .map(|argument| argument.to_string_lossy().into_owned())
             .collect::<Vec<_>>()
             .join("\n");
-        assert!(home_arguments.contains("--disable\nshell_tool"));
-        assert!(home_arguments.contains("--disable\nunified_exec"));
     }
 
     #[cfg(windows)]

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

@@ -1688,6 +1688,7 @@ pub(crate) fn read_design_workspace_file(
 
 #[cfg(test)]
 mod fake_provider {
+    use super::*;
     use std::cell::{Cell, RefCell};
     use std::collections::VecDeque;
 

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

@@ -8,7 +8,6 @@ use std::sync::{Mutex, OnceLock};
 use std::time::{SystemTime, UNIX_EPOCH};
 
 mod user_input;
-#[cfg(not(test))]
 pub(crate) use user_input::chat_with_game_creator_direct_codex;
 #[cfg(test)]
 pub(crate) use user_input::normalize_direct_client_turn_id;

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

@@ -49,6 +49,7 @@ pub(in crate::agent) use external_generation_state::{
 };
 #[cfg(test)]
 pub(crate) use external_generation_state::{
+    platform_art_generation_external_configuration_fingerprint,
     platform_art_generation_legacy_external_configuration_fingerprint,
     setup_platform_art_generation_runtime_accepted_for_recovery_test,
     write_platform_art_generation_runtime_accepted_for_test,

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

@@ -677,161 +677,6 @@ 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::<serde_json::Value>(
-            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::<Option<Vec<_>>>()?;
-            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::<Option<Vec<_>>>()?;
-            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 observation.tool != "project.patchset" {
         return None;
     }
@@ -1210,7 +1055,6 @@ 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"

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

@@ -153,6 +153,14 @@ 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)
+        }
+        "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),
         "project.index" => observe_agent_runtime_project_snapshot_with_lock(
             root,
             agent_id,
@@ -436,9 +444,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)
         }

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"),

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

@@ -649,9 +649,6 @@ 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 observation.tool == "canvas.asset_import" {
         return observation
             .detail
@@ -669,7 +666,6 @@ pub(crate) fn is_agent_runtime_project_mutation_observation(
                 | "project.patchset"
                 | "project.restore"
                 | "canvas.asset_generate"
-                | "ui.workflow.run"
         )
 }
 
@@ -761,47 +757,14 @@ pub(crate) fn agent_runtime_observation_advances_project_revision(
             .and_then(|detail| serde_json::from_str::<serde_json::Value>(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)
-        }
         "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::<serde_json::Value>(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::<serde_json::Value>(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()
@@ -821,19 +784,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::<serde_json::Value>(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 +805,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 +817,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"
     }

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

@@ -817,17 +817,24 @@ mod tests {
     use super::{
         acquire_game_creator_agent_provider_plan_project_write_lock_with_wait,
         agent_runtime_root_source_at, bind_game_creator_agent_runtime_run_profile_at,
+        build_game_creator_agent_background_final_reply_request,
         build_game_creator_agent_background_tool_plan_request_locked,
-        game_creator_agent_context_preload_notice, init_local_game_project_at,
-        new_game_creation_app_seed_tasks,
+        game_creator_agent_context_preload_notice,
+        game_creator_agent_runtime_run_profile_binding_path,
+        game_creator_project_supervisor_chat_system_prompt, init_local_game_project_at,
+        new_game_creation_app_seed_tasks, provider_command_exec_contract,
+        provider_command_start_contract,
         render_relaxed_autonomous_manifest_ready_task_background_prompt,
-        start_game_creator_agent_runtime_task_at, AgentRuntimeGoalContractAcceptanceNodeDraft,
-        AgentRuntimeGoalContractDraft, AgentRuntimeTaskLink, AgentRuntimeToolObservation,
+        required_runtime_prompt_section, start_game_creator_agent_runtime_task_at,
+        AgentRuntimeGoalContractAcceptanceNodeDraft, AgentRuntimeGoalContractDraft,
+        AgentRuntimeTaskLink, AgentRuntimeToolObservation, AgentRuntimeToolPlan,
         AgentRuntimeToolPlanRequestSnapshot, GameCreatorLlmConfig,
-        AGENT_RUNTIME_AUTONOMOUS_PRE_MUTATION_LOOP_LIMIT, AGENT_RUNTIME_RESPOND_FUNCTION_NAME,
-        AGENT_RUNTIME_RUN_PROFILE_AUTONOMOUS_GAME_BUILD, AGENT_RUNTIME_SUPERVISOR_CLI_SOURCE,
-        AGENT_RUNTIME_SUPERVISOR_GUI_SOURCE, AGENT_RUNTIME_UPDATE_PLAN_FUNCTION_NAME,
-        GAME_CREATOR_PROJECT_SUPERVISOR_AGENT_ID,
+        AGENT_RUNTIME_AUTONOMOUS_PRE_MUTATION_LOOP_LIMIT,
+        AGENT_RUNTIME_COMPLETION_BLOCKER_TOOL_PLAN_PROTOCOL, AGENT_RUNTIME_RESPOND_FUNCTION_NAME,
+        AGENT_RUNTIME_RUN_PROFILE_AUTONOMOUS_GAME_BUILD, AGENT_RUNTIME_RUN_PROFILE_STANDARD,
+        AGENT_RUNTIME_SUPERVISOR_CLI_SOURCE, AGENT_RUNTIME_SUPERVISOR_GUI_SOURCE,
+        AGENT_RUNTIME_UPDATE_PLAN_FUNCTION_NAME, GAME_CREATOR_PROJECT_SUPERVISOR_AGENT_ID,
+        RUNTIME_PROMPT_SUPERVISOR_CHAT_COMPOSITION,
     };
 
     fn build_game_creator_agent_background_tool_plan_request_for_test(
@@ -864,6 +871,24 @@ mod tests {
         )
     }
 
+    fn native_input_required_fields(
+        request: &platform_llm::LlmRunRequest,
+        tool: &str,
+    ) -> Vec<String> {
+        let function_name = crate::agent_native_tools::native_runtime_function_name(tool)
+            .expect("native runtime function name");
+        request
+            .function_tools
+            .iter()
+            .find(|function| function.name == function_name)
+            .and_then(|function| function.parameters.pointer("/properties/input/required"))
+            .and_then(serde_json::Value::as_array)
+            .expect("native input required fields")
+            .iter()
+            .map(|field| field.as_str().expect("required field string").to_string())
+            .collect()
+    }
+
     #[test]
     fn relaxed_request_keeps_general_catalog_after_plan_rejection() {
         let directory = crate::tests::canonical_test_tempdir("provider-plan-rejection-repair-");
@@ -1412,6 +1437,20 @@ mod tests {
         assert!(!prompt.contains("本轮唯一可用工具是 agent.goal_contract"));
     }
 
+    fn completion_blocker_protocol_requires_tool_repair_before_response() {
+        let protocol = AGENT_RUNTIME_COMPLETION_BLOCKER_TOOL_PLAN_PROTOCOL;
+
+        assert!(protocol.contains("最新 observation"));
+        assert!(protocol.contains("runtime.autonomous_completion"));
+        assert!(protocol.contains("status 为 blocked"));
+        assert!(protocol.contains("才能调用 respond_to_user"));
+        assert!(!protocol.contains("legacy response"));
+        assert!(protocol.contains("observation.detail 的 nextRequiredAction"));
+        assert!(protocol.contains("读取、修复和验证工具"));
+        assert!(protocol.contains("完成要求的动作、取得后续可信 observation"));
+        assert!(protocol.contains("通过完成门禁后"));
+    }
+
     #[test]
     fn supervisor_request_snapshot_preserves_prompt_visible_running_sibling_after_manifest_failure()
     {

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()

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

@@ -302,7 +302,10 @@ pub(crate) use entrypoints::{
 pub(crate) use finalization::resume_game_creator_agent_finalization_for_test_at;
 pub(crate) use finalization::AgentRuntimePendingActionResume;
 #[cfg(test)]
-pub(crate) use interaction::agent_runtime_tool_requires_repository_context_fingerprint_gate;
+pub(crate) use interaction::{
+    acquire_game_creator_agent_runtime_user_input_answer_locks_for_test,
+    agent_runtime_tool_requires_repository_context_fingerprint_gate,
+};
 pub(crate) use interaction::{
     answer_game_creator_agent_runtime_user_input_at, confirm_game_creator_agent_runtime_task_at,
     pending_repository_context_drift_observation, reject_game_creator_agent_runtime_task_at,

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

@@ -477,6 +477,20 @@ fn resolve_game_creator_agent_runtime_user_input_action_with_ordered_locks(
     Ok((None, runtime_lock, resolved))
 }
 
+#[cfg(test)]
+pub(crate) fn acquire_game_creator_agent_runtime_user_input_answer_locks_for_test(
+    root: &Path,
+    agent_id: &str,
+    run_id: &str,
+    action_id: &str,
+) -> Result<(Option<ProjectWriteLock>, AgentRuntimeTaskLock), String> {
+    let (project_lock, runtime_lock, _) =
+        resolve_game_creator_agent_runtime_user_input_action_with_ordered_locks(
+            root, agent_id, run_id, action_id,
+        )?;
+    Ok((project_lock, runtime_lock))
+}
+
 pub(crate) fn answer_game_creator_agent_runtime_user_input_at(
     root: &Path,
     agent_id: &str,

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

@@ -137,7 +137,6 @@ fn acceptance_evidence_tool_may_advance_project_revision(tool: &str) -> bool {
             | "project.patchset"
             | "canvas.asset_import"
             | "canvas.asset_generate"
-            | "ui.workflow.run"
     )
 }
 

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

@@ -11943,6 +11943,11 @@ impl ExternalGameplayJavascript {
                 .iter()
                 .any(|unit| unit.to_ascii_lowercase().contains(&marker))
     }
+
+    #[cfg(test)]
+    pub(in crate::agent) fn module_units(&self) -> &[String] {
+        &self.module_units
+    }
 }
 
 fn normalize_javascript_module_analysis_sources(

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());

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,12 +39,14 @@ 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;
 #[cfg(test)]
-pub(crate) use delivery::build_static_delegate_result_for_child_at;
+pub(crate) use delivery::{
+    build_static_delegate_result_for_child_at, wake_waiting_static_delegate_parent_run_for_test_at,
+};
 #[cfg(test)]
 pub(crate) use isolated_joins::render_isolated_join_status_batch_with_limit;
 #[cfg(test)]

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

@@ -408,6 +408,14 @@ pub(in crate::agent) fn wake_waiting_static_delegate_parent_run_at(
     Ok(true)
 }
 
+#[cfg(test)]
+pub(crate) fn wake_waiting_static_delegate_parent_run_for_test_at(
+    root: &Path,
+    parent_task: &AgentRuntimeTaskRecord,
+) -> Result<bool, String> {
+    wake_waiting_static_delegate_parent_run_at(root, parent_task)
+}
+
 pub(in crate::agent) fn wake_waiting_autonomous_manifest_parent_run_at(
     root: &Path,
     parent_task: &AgentRuntimeTaskRecord,

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

@@ -0,0 +1,222 @@
+//! 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<UiDesignImageReference>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+struct DesignDocArguments {
+    design_doc_asset_id: String,
+}
+
+pub(in crate::agent) 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::<FromImagesArguments>(input.clone()) {
+        Ok(arguments) => arguments,
+        Err(error) => return rejected(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(tool, error),
+    };
+    let revision_before = read_game_creator_agent_runtime_project_revision(root)
+        .ok()
+        .map(|snapshot| snapshot.revision);
+    match create_ui_design_doc_from_images(CreateUiDesignDocFromImagesInput {
+        project_path: root.to_string_lossy().into_owned(),
+        expected_project_id,
+        images: arguments.images,
+    }) {
+        Ok(created) => {
+            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,
+                }))
+                .ok(),
+            }
+        }
+        Err(error) => error_observation(root, tool, error),
+    }
+}
+
+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::<DesignDocArguments>(input.clone()) {
+        Ok(arguments) => arguments,
+        Err(error) => return rejected(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(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) => {
+            if revision_before.is_none_or(|before| result.revision > 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: serde_json::to_string(&result).ok(),
+            }
+        }
+        Err(error) => error_observation(root, tool, error),
+    }
+}
+
+pub(in crate::agent) 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::<DesignDocArguments>(input.clone()) {
+        Ok(arguments) => arguments,
+        Err(error) => return rejected(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(tool, error),
+    };
+    match generate_ui_design_code_at(GenerateUiDesignCodeInput {
+        project_path: root.to_string_lossy().into_owned(),
+        expected_project_id,
+        asset_id: arguments.design_doc_asset_id,
+    }) {
+        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),
+    }
+}
+
+/// 输入解析失败：模型只给了参数，摘要里不含宿主路径，无需再脱敏。
+fn rejected(tool: &str, summary: String) -> AgentRuntimeToolObservation {
+    AgentRuntimeToolObservation {
+        tool: tool.to_string(),
+        status: "rejected".to_string(),
+        summary,
+        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,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    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 }),
+        );
+        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 }] }),
+        );
+        assert_eq!(invalid_project.status, "rejected");
+        assert!(!invalid_project.summary.contains("输入无效"));
+    }
+
+    #[test]
+    fn design_doc_asset_id_must_be_a_string() {
+        // run-workflow 与 into-js 共用同一份入参解析，这里解析一次、同步调用一次。
+        assert!(
+            serde_json::from_value::<DesignDocArguments>(json!({ "designDocAssetId": 1 })).is_err()
+        );
+        let observation = observe_agent_runtime_ui_design_doc_into_js(
+            Path::new("."),
+            &json!({ "designDocAssetId": 1 }),
+        );
+        assert_eq!(observation.status, "rejected");
+        assert!(
+            observation.summary.contains("输入无效"),
+            "{}",
+            observation.summary
+        );
+    }
+}