修复 AGC 前端资源 kind 判据与用例的 canonical 残留

- resource-canvas/resourceCanvasAssetGenerationReferenceModel.ts：「图集不接受用户参考」判据改用 canonical icon-spritesheet，删除残留平台词的字符串清单。 - view/project-development/index.tsx：美术摘要的图片产出判据显式排除 ui-design，候选 UI 原型图不再顶掉「仅完成计划」。 - tests/appSurface/project-development.suite.ts：generateCall 支持按素材名定位，规范 / 图集 / UI 设计图入口断言改用 canonical kind。 - tests/appSurface/project-assets.suite.ts：/asset-register 与开发面板用例改用 canonical kind，面板默认值按 unknown 断言。 - tests/resourceCanvasAssetGenerationReferences.test.tsx：夹具与提交断言改用 icon-spritesheet / ui-design。 - docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md：载荷表与规范通道说明改用 canonical kind，并写明平台请求词汇只留在 source.generationKind。 - docs/project-memory/shared-memory/pitfalls.md：记录前端 kind 判据与 fixture 必须一起按 canonical 成员重写。
修复 AGC 资源 kind 收敛后的 Rust 默认值与工具栏用例
2026-09-19 03:21:37 +08:00 · 2026-09-19 03:21:25 +08:00 · 2026-09-19 02:38:30 +08:00 · 2026-09-19 01:54:10 +08:00 · 2026-09-19 01:50:09 +08:00 · 2026-09-19 01:44:48 +08:00
204 changed files with 22234 additions and 3280 deletions
@@ -23,3 +23,6 @@
 *.meta text
 *.anim text
 *.controller text
+
+# Rust ts-rs 生成的共享契约：保留在仓库中供 TS 消费，但不作为手写源文件统计。
+packages/shared/src/contracts/generated/** linguist-generated=true
@@ -1,5 +1,14 @@
 {
  "singleQuote": true,
  "semi": true,
-  "trailingComma": "all"
+  "trailingComma": "all",
+  "overrides": [
+    {
+      "files": "packages/shared/src/contracts/generated/**/*.ts",
+      "options": {
+        "printWidth": 1000,
+        "singleQuote": false
+      }
+    }
+  ]
 }
@@ -676,11 +676,11 @@ async function runSelfTest() {
      designFoundationAssetCall?.arguments?.input?.outputPath ===
        'assets/ui-prototype.png' &&
      designFoundationAssetCall.arguments.input.aspectRatio === '16:9' &&
-      designFoundationAssetCall.arguments.input.assetKind === 'ui-prototype' &&
+      designFoundationAssetCall.arguments.input.assetKind === 'ui-design' &&
      artAssetPlanAssetCall?.arguments?.input?.outputPath ===
        'assets/art-spritesheet.png' &&
      artAssetPlanAssetCall.arguments.input.aspectRatio === '1:1' &&
-      artAssetPlanAssetCall.arguments.input.assetKind === 'art-spritesheet',
+      artAssetPlanAssetCall.arguments.input.assetKind === 'icon-spritesheet',
    'self-test-visual-assets-invalid',
  );

@@ -70,7 +70,7 @@ const requiredFormalArtifactSpecs = [
  { path: 'game/balance.json', kind: 'json' },
  { path: 'assets/manifest.art.json', kind: 'json' },
  { path: 'assets/manifest.audio.json', kind: 'json' },
-  { path: 'game/index.html', kind: 'game-entry' },
+  { path: 'game/index.html', kind: 'file' },
  { path: 'exports/README.md', kind: 'file' },
 ];
 const editorImageArtifactSpecs = [
@@ -290,7 +290,7 @@ function deterministicArtManifest(
          {
            id: 'garden-guardians-spritesheet',
            path: 'assets/art-spritesheet.png',
-            kind: 'art-spritesheet',
+            kind: 'icon-spritesheet',
            usage: ['defenders', 'enemies', 'battlefield-ui'],
            source: 'canvas',
            status: 'ready',
@@ -710,7 +710,7 @@ function canvasAssetCall(agentId) {
      outputPath: 'assets/ui-prototype.png',
      aspectRatio: '16:9',
      imageSize: '2K',
-      assetKind: 'ui-prototype',
+      assetKind: 'ui-design',
      assetLabel: '游戏横屏界面原型图',
      replaceExisting: false,
    });
@@ -721,7 +721,7 @@ function canvasAssetCall(agentId) {
    outputPath: 'assets/art-spritesheet.png',
    aspectRatio: '1:1',
    imageSize: '1K',
-    assetKind: 'art-spritesheet',
+    assetKind: 'icon-spritesheet',
    assetLabel: '游戏首版核心美术素材',
    replaceExisting: false,
    sliceMode: 'connected-components',
@@ -830,12 +830,12 @@ function missingGeneratedVisualAssetObservation(context, agentId) {
    },
    'design-foundation': {
      path: 'assets/ui-prototype.png',
-      kind: 'ui-prototype',
+      kind: 'ui-design',
      summary: '策划界面原型图尚未按正式视觉流程生成并登记，不能完成任务',
    },
    'art-asset-plan': {
      path: 'assets/art-spritesheet.png',
-      kind: 'art-spritesheet',
+      kind: 'icon-spritesheet',
      summary: '首版美术素材图尚未按正式视觉流程生成并登记，不能完成任务',
    },
  }[agentId];
@@ -2667,7 +2667,7 @@ function createDeterministicCanvasFixture(apiKey) {
          asset: {
            assetId: `asset-${sliceImageId}`,
            assetObjectId: sliceAssetObjectId,
-            assetKind: 'art-spritesheet-slice',
+            assetKind: 'icon',
            projectId,
            taskId,
          },
@@ -2707,7 +2707,7 @@ function createDeterministicCanvasFixture(apiKey) {
        spritesheetAsset: {
          assetId: `asset-${imageId}`,
          assetObjectId,
-          assetKind: 'art-spritesheet',
+          assetKind: 'icon-spritesheet',
          projectId,
          taskId,
        },
@@ -2749,7 +2749,7 @@ function createDeterministicCanvasFixture(apiKey) {
      const assetObjectId = `asset-object-${imageId}`;
      const resourceId = `resource-${imageId}`;
      const assetKind =
-        typeof body?.assetKind === 'string' ? body.assetKind : 'game-art';
+        typeof body?.assetKind === 'string' ? body.assetKind : 'image';
      images.set(imageId, {
        ...image,
        objectKey,
@@ -5016,6 +5016,7 @@ dependencies = [
 "serde",
 "serde_json",
 "sha2",
+ "ts-rs",
 ]

 [[package]]
@@ -56,7 +56,7 @@ platform-agent = { path = "../../../server-rs/crates/platform-agent" }
 portable-pty = "0.9"
 reqwest = { version = "0.12", default-features = false, features = ["json", "multipart", "native-tls", "stream"] }
 regex = "1"
-shared-contracts = { path = "../../../server-rs/crates/shared-contracts", default-features = false }
+shared-contracts = { path = "../../../server-rs/crates/shared-contracts", default-features = false, features = ["ts-bindings"] }
 tauri = { version = "2.11.2", features = [] }
 tauri-plugin-dialog = "2.7.1"
 tauri-plugin-http = { version = "2.5.9", default-features = false, features = ["charset", "cookies", "http2", "rustls-tls"] }
@@ -14,6 +14,9 @@ Implement the user's actual game request in the current project as an npm-manage
 3. Build with the project's npm script before previewing. The playable entry is the package directory's `dist/index.html`; never report an unbuilt bare-module page as playable. Import assets or configure public assets so all runtime media is included in dist; preview and exports cannot read outside it.
 4. Build a complete playable loop: visible objective, responsive input, meaningful state changes, success or failure feedback, and a reliable restart path where the game needs one.
 5. Fit the active game scene to desktop and mobile viewports without accidental page scrollbars. Reserve deliberate safe space for HUD elements instead of covering interactive content.
+   - **画布居中只能由一处负责。** 使用 `Phaser.Scale.FIT` 与 `autoCenter: Phaser.Scale.CENTER_BOTH` 时，canvas 的直接父容器应使用尺寸明确的普通块布局，不再对同一 canvas 叠加 Grid/Flex 居中、`place-items: center`、自动外边距或居中 transform。Phaser 自动计算的 margin 与 CSS 居中叠加会使竖屏画面向右偏移。
+   - 若决定由 CSS 居中，则显式使用 `autoCenter: Phaser.Scale.NO_CENTER`，由 CSS 独立完成定位；外围页面可以继续使用 Grid/Flex，限制只针对同一 canvas 的重复定位。
+   - 出现偏移先检查游戏自身的 CSS 与 Phaser scale 配置，不添加 AGC 预览容器固定偏移补偿。修改布局后重新构建 dist，在桌面、移动及窗口 resize 后检查 canvas 相对游戏父容器居中（误差不超过 1 CSS px）、画面完整且无意外滚动条；不能仅凭 build 成功宣称布局通过。
 6. Invoke `taonier-art-assets` for every new game brief that needs visual assets. First reuse suitable registered Taonier art; when the brief's required visual elements are missing or unsuitable, call the reviewed `agc_tools` generation/edit workflow in the same task. After the tool returns, wire its relative paths into the game and verify the rendered result. A game with unused generated assets or placeholder emoji/CSS where requested art should appear is not complete. Load media defensively only for genuinely optional effects, and never relabel a local placeholder as platform art.
 7. Let Phaser own the render loop and input dispatch. Avoid duplicate scenes, stale event listeners, and state that survives restart unintentionally.
 8. After a meaningful game change, use the browser playtest Skill and fix issues shown by real evidence before reporting completion.
@@ -7,5 +7,7 @@
 - Score, steps, health, timer, or other core state updates consistently.
 - Restart restores all state and does not duplicate timers, animation loops, or event listeners.
 - Desktop and mobile layouts keep the core scene visible without accidental document scrolling.
+- 画布的缩放与居中由 Phaser 或 CSS 中的一方独立负责。`FIT + CENTER_BOTH` 不与同一 canvas 父容器的 Grid/Flex 居中、自动外边距或居中 transform 叠加；使用 CSS 居中时关闭 Phaser 自动居中（`NO_CENTER`）。
+- 在构建后的实际页面检查桌面、移动和 resize：比较 canvas 与游戏父容器的中心，预期居中时水平/垂直误差不超过 1 CSS px，并检查画面没有溢出或意外滚动条。偏移先修游戏 CSS/scale 配置，不用修改 AGC 预览位置掩盖。
 - HUD and overlays reserve space and do not cover essential interactive content.
 - Requested Taonier art is visibly integrated into the core experience when available.
@@ -1,6 +1,6 @@
 {
  "schemaVersion": "agc-skill-pack.v1",
-  "version": "2026-08-26.24",
+  "version": "2026-08-26.25",
  "skills": [
    {
      "name": "agc-game-production-workflow",
@@ -63,7 +63,7 @@
        "agents/openai.yaml",
        "references/platform-art-contract.md"
      ],
-      "sha256": "47ac742d9b88e5d6cd9833484ab212152578e58ae27f7add312fd1d78183385c"
+      "sha256": "6668bf1aa69601bcc65c97fdcd879c699c3139befcd70805d95614997f6e44e9"
    },
    {
      "name": "agc-web-game-development",
@@ -80,7 +80,7 @@
        "agents/openai.yaml",
        "references/game-quality-checklist.md"
      ],
-      "sha256": "05b5cfbf7a40fd303717491f5cea84ff339a73359c9678b283fd54d2b5c45efd"
+      "sha256": "e122d8f3a6d986b594b95c971754d68197bf7896912fa8267d44a7aa129a57ba"
    },
    {
      "name": "agc-browser-playtest",
@@ -19,13 +19,13 @@ image, UI design image, or publication material; use `agc_edit_image` for an
 edit of an existing registered image; use `taonier_prepare_game_art` only for
 the complete game-art package and its canonical slices.

-With `agc_generate_image`, `kind="character"` and `kind="art-spritesheet"`
+With `agc_generate_image`, `kind="character"` and `kind="icon-spritesheet"`
 generate the subject on a solid-colour background and automatically matte it
 away afterwards, producing transparent-background results; write the prompt
 for the subject only, never for a scene. `kind="image"` keeps the rendered
 frame without extra processing.

-When `agc_generate_image` is used with `kind="art-spritesheet"`, `sliceMode` is
+When `agc_generate_image` is used with `kind="icon-spritesheet"`, `sliceMode` is
 required and has no default, so decide it explicitly:

 - Use `sliceMode="grid"` with `gridX` and `gridY` (1-32 each) only when the user
@@ -797,6 +797,16 @@ fn direct_thread_visible_item(
    direct_thread_event_item(root, item)
 }

+/// AGC 预写的 canonical 用户条目 id：`direct-codex:{clientTurnId}:user`。
+///
+/// 与 `direct_project_history::is_direct_project_codex_user_item` 的判据同一份口径（前缀 +
+/// `:user` 后缀）。回合生命周期事件的 `userItemId` 只能来自这里或已落盘条目自身的 id；
+/// clientTurnId 缺失时不猜身份，返回 `None` 让前端按"未知归属"处理。
+fn direct_codex_user_item_id_for_client_turn_id(client_turn_id: &str) -> Option<String> {
+    let client_turn_id = client_turn_id.trim();
+    (!client_turn_id.is_empty()).then(|| format!("direct-codex:{client_turn_id}:user"))
+}
+
 fn direct_codex_command_is_game_verification(command: &str) -> bool {
    let command = command.to_ascii_lowercase();
    command.contains("game.static_smoke")
@@ -2927,7 +2937,7 @@ impl CodexAppServerConnection {
                    None => direct_project_local_message_item(
                        "user",
                        current_prompt,
-                        Some(&format!("direct-codex:{client_turn_id}:user")),
+                        direct_codex_user_item_id_for_client_turn_id(client_turn_id).as_deref(),
                    )
                    .map_err(platform_llm::LlmError::InvalidRequest)?,
                };
@@ -3046,13 +3056,30 @@ impl CodexAppServerConnection {
        };
        turn_start_guard.armed = false;
        let direct_thread_id = direct_thread_id_for_project(history_root);
+        // 回合边界的阶段时间：Turn 上游只有**秒**级 `startedAt` / `completedAt`，秒级截断
+        // 撑不起前端 0.1 秒粒度的展示，也可能让完成时刻落进该轮用户消息的同一秒、落在真实
+        // 发送时间之前，被判成无效边界后整轮新回合被吞掉。因此这里只在宿主处理对应阶段时取
+        // 毫秒钟（与条目侧"没有原生阶段时间就用宿主钟"同一口径），不再读上游秒字段。
+        let direct_turn_started_at_ms = direct_tool_call_now_ms();
+        // 本轮开口用户条目的 canonical id：只从已落盘的那条条目上读身份（`id`，工具条目才用
+        // `call_id`），不在事件侧重造一份。拿不到就留空，让前端按"归属不可证明"处理。
+        let direct_turn_user_item_id = direct_persisted_user_item
+            .as_ref()
+            .and_then(direct_thread_item_identity);
        if self.inner.workspace_mode == CodexAppServerWorkspaceMode::DirectProject {
-            append_direct_thread_event(&direct_thread_id, DirectThreadEvent::turn_started());
+            append_direct_thread_event(
+                &direct_thread_id,
+                DirectThreadEvent::turn_started(direct_turn_started_at_ms)
+                    .with_user_item_id(direct_turn_user_item_id.as_deref()),
+            );
            if let Some(user_item) = direct_persisted_user_item.as_ref() {
                if let Some(entry_item) = direct_thread_event_item(history_root, user_item) {
+                    // 这里的条目时间可能是启动应答后的观测时间；前端按同一用户条目身份
+                    // 保留更早的真实发送时间，不用此事件时间覆盖它。
+                    let user_item_at = entry_item.at();
                    append_direct_thread_event(
                        &direct_thread_id,
-                        DirectThreadEvent::item_completed(entry_item),
+                        DirectThreadEvent::item_completed(entry_item, user_item_at),
                    );
                }
            }
@@ -3191,9 +3218,14 @@ impl CodexAppServerConnection {
                            .map_err(platform_llm::LlmError::InvalidRequest)?;
                            direct_project_history.complete_item(&item);
                            if let Some(entry_item) = entry_item {
+                                // `rawResponseItem/completed` 不带阶段时间，宿主处理到这条
+                                // 通知的钟就是该阶段唯一可证明的时间。
                                append_direct_thread_event(
                                    &direct_thread_id,
-                                    DirectThreadEvent::item_completed(entry_item),
+                                    DirectThreadEvent::item_completed(
+                                        entry_item,
+                                        direct_tool_call_now_ms(),
+                                    ),
                                );
                            }
                        }
@@ -3322,9 +3354,19 @@ impl CodexAppServerConnection {
                                if let Some(entry_item) =
                                    direct_thread_visible_item(history_root, item)
                                {
+                                    // `item/started` 的通知层带 `startedAtMs`：这是工具真正
+                                    // 开始的阶段时间，优先于条目展示时间与宿主钟。
                                    append_direct_thread_event(
                                        &direct_thread_id,
-                                        DirectThreadEvent::item_started(entry_item),
+                                        DirectThreadEvent::item_started(
+                                            entry_item,
+                                            direct_thread_item_event_at_ms(
+                                                &params,
+                                                item,
+                                                false,
+                                                direct_tool_call_now_ms(),
+                                            ),
+                                        ),
                                    );
                                }
                            }
@@ -3367,9 +3409,19 @@ impl CodexAppServerConnection {
                            && matches!(status, "completed" | "interrupted" | "failed")
                        {
                            terminal_recorded = true;
+                            // 终态时间：`durationMs` 与宿主记下的毫秒起点都可靠时才派生，
+                            // 否则取宿主处理这条终态的钟；上游秒级 `completedAt` 一律不用。
                            append_direct_thread_event(
                                &direct_thread_id,
-                                DirectThreadEvent::turn_completed(status.to_string()),
+                                DirectThreadEvent::turn_completed(
+                                    status.to_string(),
+                                    direct_thread_turn_completed_at_ms(
+                                        turn,
+                                        Some(direct_turn_started_at_ms),
+                                        direct_tool_call_now_ms(),
+                                    ),
+                                )
+                                .with_user_item_id(direct_turn_user_item_id.as_deref()),
                            );
                        }
                        match status {
@@ -3426,7 +3478,11 @@ impl CodexAppServerConnection {
                        "failed"
                    }
                    .to_string(),
-                ),
+                    // 这条兜底终态没有对应的 app-server 终态载荷，只能取宿主处理它的钟，
+                    // 不能拿最后一次正文或工具更新时间当回合终点。
+                    direct_tool_call_now_ms(),
+                )
+                .with_user_item_id(direct_turn_user_item_id.as_deref()),
            );
        }
        let text = match collect_result {
@@ -3624,6 +3680,15 @@ enum DirectCodexTurnCancelTarget {
 /// 这时显式释放这条守卫并把可读原因返回给界面。释放条件见
 /// [`release_stale_direct_taonier_active_invocation`] 的注释；"正在跑的是另一轮"仍然
 /// 保持原拒绝语义，什么都不释放。
+///
+/// 兜底终态带 `userItemId`：身份取 `release_stale_direct_taonier_active_invocation` 返回的
+/// clientTurnId（客户端回合身份的唯一来源），与正常路径的开口条目 id 同一份 canonical 口径。
+/// 拿不到 clientTurnId 就留空——这一轮不会再有原生终态，猜一个身份会让前端把边界盖到别人身上。
+fn direct_stale_cancel_turn_completed_event(client_turn_id: &str) -> DirectThreadEvent {
+    DirectThreadEvent::turn_completed("aborted".to_string(), direct_tool_call_now_ms())
+        .with_user_item_id(direct_codex_user_item_id_for_client_turn_id(client_turn_id).as_deref())
+}
+
 pub(crate) fn cancel_direct_codex_turn_at(
    root: &Path,
    client_turn_id: Option<&str>,
@@ -3680,7 +3745,7 @@ pub(crate) fn cancel_direct_codex_turn_at(
            // 兜底补一条，否则前端的"最新回合是否在跑"会永远停在运行中。
            append_direct_thread_event(
                &direct_thread_id_for_project(root),
-                DirectThreadEvent::turn_completed("aborted".to_string()),
+                direct_stale_cancel_turn_completed_event(&released),
            );
            Ok(DirectTurnCancelView {
                outcome: DIRECT_TURN_CANCEL_OUTCOME_RELEASED.to_string(),
@@ -5006,6 +5071,109 @@ mod tests {
        ));
    }

+    /// 阶段时间取自**通知层**字段，形状照抄 codex-cli 0.147 / 0.155 的 v2 协议 schema：
+    /// `item/started` 带 `startedAtMs`、`item/completed` 带 `completedAtMs`（毫秒），
+    /// `turn/completed` 带 `turn.startedAt` / `turn.completedAt`（秒）与 `turn.durationMs`（毫秒）。
+    /// 分类函数把 params 原样交给事件级 `at` 的投影函数，所以字段位置必须在这里钉住；
+    /// 回合边界的秒字段按"不用"锁在这里，避免以后有人再把秒级截断当 0.1 秒精度。
+    #[test]
+    fn direct_lifecycle_stage_times_come_from_notification_params() {
+        let started = serde_json::json!({
+            "threadId": "thread-1",
+            "turnId": "turn-1",
+            "startedAtMs": 1_700_000_000_123u64,
+            "item": {"id": "call-1", "type": "commandExecution", "command": "ls"},
+        });
+        let completed = serde_json::json!({
+            "threadId": "thread-1",
+            "turnId": "turn-1",
+            "completedAtMs": 1_700_000_001_500u64,
+            "item": {"id": "call-1", "type": "commandExecution", "command": "ls"},
+        });
+        for (method, params, expected_at_ms) in [
+            ("item/started", &started, 1_700_000_000_123u64),
+            ("item/completed", &completed, 1_700_000_001_500u64),
+        ] {
+            let Some(CodexTurnEvent::Item {
+                completed,
+                params: event_params,
+            }) = direct_codex_notification_event(method, params, None, None, "turn-1")
+            else {
+                panic!("{method} 必须分类成条目生命周期事件");
+            };
+            let item = event_params.get("item").expect("item payload");
+            assert_eq!(
+                direct_thread_item_event_at_ms(&event_params, item, completed, 9_999),
+                expected_at_ms,
+                "{method} 必须用通知层的阶段时间，而不是宿主钟"
+            );
+        }
+
+        let terminal = serde_json::json!({
+            "threadId": "thread-1",
+            "turn": {
+                "id": "turn-1",
+                "items": [],
+                "status": "completed",
+                "startedAt": 1_700_000_000i64,
+                "completedAt": 1_700_000_042i64,
+            },
+        });
+        let Some(CodexTurnEvent::Terminal(params)) =
+            direct_codex_notification_event("turn/completed", &terminal, None, None, "turn-1")
+        else {
+            panic!("turn/completed 必须分类成终态事件");
+        };
+        let turn = params.get("turn").unwrap_or(&params);
+        assert_eq!(
+            direct_thread_turn_completed_at_ms(turn, Some(1_700_000_000_500), 9_999),
+            9_999,
+            "上游只有秒级 completedAt：不采用，取宿主处理终态的毫秒钟"
+        );
+        let with_duration = serde_json::json!({
+            "id": "turn-1",
+            "items": [],
+            "status": "completed",
+            "startedAt": 1_700_000_000i64,
+            "completedAt": 1_700_000_042i64,
+            "durationMs": 42_500u64,
+        });
+        assert_eq!(
+            direct_thread_turn_completed_at_ms(&with_duration, Some(1_700_000_000_500), 9_999),
+            1_700_000_043_000,
+            "durationMs + 宿主高精度起点才派生结束"
+        );
+    }
+
+    /// 取消兜底终态也要带开口用户条目身份，且身份只有一个来源：release 返回的 clientTurnId
+    /// 走与正常路径同一份 canonical 口径；拿不到（空 / 空白）就留空，不猜。
+    #[test]
+    fn stale_cancel_terminal_event_keeps_opener_user_item_id_from_client_turn_id() {
+        let event = direct_stale_cancel_turn_completed_event("turn-0001");
+        assert_eq!(event.user_item_id(), Some("direct-codex:turn-0001:user"));
+        assert!(event.at().is_some(), "兜底终态仍要带宿主观测时间");
+        assert!(matches!(
+            event,
+            DirectThreadEvent::TurnCompleted { ref status, .. } if status == "aborted"
+        ));
+
+        for missing in ["", "   "] {
+            let event = direct_stale_cancel_turn_completed_event(missing);
+            assert_eq!(
+                event.user_item_id(),
+                None,
+                "拿不到 clientTurnId 时不得编造开口条目身份"
+            );
+        }
+
+        // canonical 口径与落盘侧同一份：`direct-codex:{clientTurnId}:user`。
+        assert_eq!(
+            direct_codex_user_item_id_for_client_turn_id("  turn-0001  ").as_deref(),
+            Some("direct-codex:turn-0001:user")
+        );
+        assert_eq!(direct_codex_user_item_id_for_client_turn_id(""), None);
+    }
+
    fn test_llm() -> GameCreatorLlmConfig {
        GameCreatorLlmConfig {
            custom_enabled: false,
@@ -6740,12 +6908,33 @@ done

        let consumed = crate::agent::consume_direct_thread(&bootstrap.subscription_id)
            .expect("consume events");
+        // 回合起止必须与开口用户条目同源：前端在「只有锚点 + 历史、运行态为空」的回合里靠这个
+        // 身份把边界认领给同一条用户条目，缺了它就只能隐藏未知用时。
+        let lifecycle_user_item_ids = consumed
+            .events
+            .iter()
+            .filter(|event| {
+                matches!(
+                    event,
+                    DirectThreadEvent::TurnStarted { .. } | DirectThreadEvent::TurnCompleted { .. }
+                )
+            })
+            .map(DirectThreadEvent::user_item_id)
+            .collect::<Vec<_>>();
+        assert_eq!(
+            lifecycle_user_item_ids,
+            vec![
+                Some("direct-codex:turn-0001:user"),
+                Some("direct-codex:turn-0001:user"),
+            ],
+            "turn.started / turn.completed 都要带本轮开口用户条目的 canonical itemId"
+        );
        let mut user_items = Vec::new();
        let mut assistant_items = Vec::new();
        for event in &consumed.events {
            let item = match event {
-                DirectThreadEvent::ItemStarted { item }
-                | DirectThreadEvent::ItemCompleted { item } => item,
+                DirectThreadEvent::ItemStarted { item, .. }
+                | DirectThreadEvent::ItemCompleted { item, .. } => item,
                _ => continue,
            };
            match item {
@@ -1198,7 +1198,7 @@ mod tests {
                "tool": "agc_generate_image",
                "arguments": {
                    "prompt": prompt,
-                    "kind": "art-spritesheet",
+                    "kind": "icon-spritesheet",
                    "sliceMode": "connected-components",
                    "sliceCount": 8,
                    "screenColor": "#CFEFFF"
@@ -1,6 +1,10 @@
-use super::model::{DirectCodexUserContentPart, DirectCodexUserItem};
+use super::model::{DirectCodexUserContentPart, DirectCodexUserItem, DirectCodexUserMessageItem};
 use super::validation::validate_direct_codex_user_item;
 use crate::agent::{read_manifest_for_project, sanitize_attachment_local_path};
+use crate::ui_editor::persistence::{
+    generate_ui_design_code_at, GenerateUiDesignCodeInput, UI_DESIGN_DOC_ASSET_KIND,
+    UI_DESIGN_DOC_MEDIA_TYPE,
+};
 use serde_json::Value;
 use std::path::Path;

@@ -111,29 +115,165 @@ pub(crate) fn direct_codex_user_item_to_prompt(
    item: &DirectCodexUserItem,
 ) -> Result<String, String> {
    let wire = direct_codex_user_item_to_wire_input(root, item)?;
-    wire.as_array()
+    let DirectCodexUserItem::Message(message) = item;
+    let mut prompt = wire
+        .as_array()
        .ok_or_else(|| "DirectProject user item wire input 不是数组".to_string())
-        .map(|parts| {
+        .and_then(|parts| {
            parts
                .iter()
-                .filter_map(|part| part.get("text").and_then(Value::as_str))
-                .collect::<String>()
-        })
-        .and_then(|prompt| {
-            if prompt.trim().is_empty() {
-                Err("DirectProject user item 不能转换为空 prompt".to_string())
-            } else {
-                Ok(prompt)
+                .map(|part| {
+                    part.get("text")
+                        .and_then(Value::as_str)
+                        .ok_or_else(|| "DirectProject user item wire part 缺少 text".to_string())
+                })
+                .collect::<Result<String, String>>()
+        })?;
+    if let Some(code_context) = render_ui_design_code_context(root, message)? {
+        prompt.push('\n');
+        prompt.push_str(&code_context);
+    }
+    if prompt.trim().is_empty() {
+        return Err("DirectProject user item 不能转换为空 prompt".to_string());
+    }
+    Ok(prompt)
+}
+
+/// 本轮 prompt 的 UI 设计文档引用上下文：复用 UI Editor 代码导出，把带文档注释的
+/// JS 片段路径交给模型；生成失败只追加原始错误，不阻断本轮引用，其它引用继续处理。
+///
+/// 只在生成本轮 prompt 时展开：历史 item 回读走 `direct_codex_user_item_to_response_item`
+/// 的纯投影，不得在这里产生项目写副作用。
+fn render_ui_design_code_context(
+    root: &Path,
+    message: &DirectCodexUserMessageItem,
+) -> Result<Option<String>, String> {
+    let referenced_ids = message
+        .content
+        .iter()
+        .filter_map(|part| match part {
+            DirectCodexUserContentPart::AgcResourceReference { resource_id } => {
+                Some(resource_id.trim())
            }
+            _ => None,
        })
+        .collect::<Vec<_>>();
+    if referenced_ids.is_empty() {
+        return Ok(None);
+    }
+    let manifest = read_manifest_for_project(root)?;
+    let mut lines = Vec::new();
+    for resource_id in referenced_ids {
+        let is_ui_design_doc = manifest.assets.iter().any(|asset| {
+            asset.id == resource_id
+                && asset.kind == UI_DESIGN_DOC_ASSET_KIND
+                && asset.media_type == UI_DESIGN_DOC_MEDIA_TYPE
+        });
+        if !is_ui_design_doc {
+            continue;
+        }
+        lines.push(
+            match generate_ui_design_code_at(GenerateUiDesignCodeInput {
+                project_path: root.to_string_lossy().into_owned(),
+                expected_project_id: manifest.project_id.clone(),
+                asset_id: resource_id.to_string(),
+            }) {
+                Ok(result) => format!("请先阅读生成的带有文档的代码片段: {}", result.relative_path),
+                Err(error) => format!("生成代码遇到错误{error}"),
+            },
+        );
+    }
+    if lines.is_empty() {
+        return Ok(None);
+    }
+    Ok(Some(lines.join("\n")))
 }

 #[cfg(test)]
 mod tests {
-    use super::direct_codex_user_item_to_response_item;
+    use super::{direct_codex_user_item_to_prompt, direct_codex_user_item_to_response_item};
+    use crate::ui_editor::persistence::UI_DESIGN_DOC_MEDIA_TYPE;
    use serde_json::json;
+    use shared_contracts::game_creation_app::{
+        GameCreationAppAssetKind, GameCreationAppAssetSource, GameCreationAppAssetSourceKind,
+    };
    use std::path::Path;

+    const PROMPT_CONTEXT_PROJECT_ID: &str = "direct-prompt-context-project";
+
+    fn prompt_context_project() -> tempfile::TempDir {
+        let directory = tempfile::tempdir().expect("temp project");
+        crate::init_local_game_project_at(
+            directory.path(),
+            PROMPT_CONTEXT_PROJECT_ID,
+            "Direct prompt 上下文测试",
+        )
+        .expect("init project");
+        directory
+    }
+
+    fn register_fixture_asset(
+        root: &Path,
+        relative_path: &str,
+        kind: GameCreationAppAssetKind,
+        media_type: &str,
+    ) -> String {
+        let absolute_path = crate::resolve_local_project_path(root, relative_path)
+            .expect("resolve fixture asset path");
+        std::fs::create_dir_all(absolute_path.parent().expect("fixture asset parent"))
+            .expect("create fixture asset parent");
+        std::fs::write(&absolute_path, b"{}").expect("write fixture asset file");
+        crate::assets::register_local_asset_at(
+            root,
+            relative_path,
+            kind,
+            media_type,
+            "prompt-context-test",
+            GameCreationAppAssetSource {
+                kind: GameCreationAppAssetSourceKind::Generated,
+                canvas_project_id: None,
+                resource_id: Some("prompt-context".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 fixture asset")
+        .id
+    }
+
+    fn ui_design_doc_fixture(initialize_state: bool) -> (tempfile::TempDir, String) {
+        let directory = prompt_context_project();
+        let asset_id = register_fixture_asset(
+            directory.path(),
+            "ui/design.json",
+            GameCreationAppAssetKind::UiDesignDoc,
+            UI_DESIGN_DOC_MEDIA_TYPE,
+        );
+        if initialize_state {
+            crate::ui_editor::persistence::initialize_ui_design_state_at(
+                directory.path(),
+                PROMPT_CONTEXT_PROJECT_ID,
+                &asset_id,
+            )
+            .expect("initialize UI design state");
+        }
+        (directory, asset_id)
+    }
+
+    fn user_item_with_resource_reference(asset_id: &str) -> serde_json::Value {
+        json!({
+            "type": "message",
+            "role": "user",
+            "id": "turn-1:user",
+            "content": [{"type": "agc_resource_reference", "resourceId": asset_id}],
+        })
+    }
+
    #[test]
    fn standard_response_item_passes_through_without_agc_private_parts() {
        let item = json!({
@@ -174,4 +314,81 @@ mod tests {
        .expect_err("history item without type must fail");
        assert!(error.contains("缺少 type"), "{error}");
    }
+
+    #[test]
+    fn ui_design_doc_reference_appends_generated_code_context() {
+        let (project, asset_id) = ui_design_doc_fixture(true);
+        let item: super::DirectCodexUserItem =
+            serde_json::from_value(user_item_with_resource_reference(&asset_id))
+                .expect("canonical user item");
+        let prompt =
+            direct_codex_user_item_to_prompt(project.path(), &item).expect("prompt projection");
+        assert!(
+            prompt.contains(&format!(
+                "[素材引用 resourceId={asset_id}；项目路径=ui/design.json]"
+            )),
+            "{prompt}"
+        );
+        assert!(
+            prompt.contains("请先阅读生成的带有文档的代码片段: ui/generated-"),
+            "{prompt}"
+        );
+    }
+
+    #[test]
+    fn history_projection_never_writes_generated_ui_design_code() {
+        let (project, asset_id) = ui_design_doc_fixture(true);
+        let item = user_item_with_resource_reference(&asset_id);
+        direct_codex_user_item_to_response_item(project.path(), &item).expect("history projection");
+        let generated_root =
+            crate::resolve_local_project_path(project.path(), "ui").expect("resolve ui directory");
+        let generated_files = std::fs::read_dir(generated_root)
+            .expect("read ui directory")
+            .filter_map(|entry| entry.ok())
+            .filter(|entry| {
+                entry
+                    .file_name()
+                    .to_string_lossy()
+                    .starts_with("generated-")
+            })
+            .count();
+        assert_eq!(
+            generated_files, 0,
+            "历史回读只做纯投影，不得生成 UI 设计代码"
+        );
+    }
+
+    #[test]
+    fn ui_design_generation_failure_keeps_reference_and_reports_error() {
+        let (project, asset_id) = ui_design_doc_fixture(false);
+        let item: super::DirectCodexUserItem =
+            serde_json::from_value(user_item_with_resource_reference(&asset_id))
+                .expect("canonical user item");
+        let prompt =
+            direct_codex_user_item_to_prompt(project.path(), &item).expect("prompt projection");
+        assert!(prompt.contains("素材引用 resourceId="), "{prompt}");
+        assert!(prompt.contains("生成代码遇到错误"), "{prompt}");
+    }
+
+    #[test]
+    fn other_asset_kind_reference_does_not_generate_ui_design_code() {
+        let project = prompt_context_project();
+        let asset_id = register_fixture_asset(
+            project.path(),
+            "assets/hero.png",
+            GameCreationAppAssetKind::Character,
+            "image/png",
+        );
+        let item: super::DirectCodexUserItem =
+            serde_json::from_value(user_item_with_resource_reference(&asset_id))
+                .expect("canonical user item");
+        let prompt =
+            direct_codex_user_item_to_prompt(project.path(), &item).expect("prompt projection");
+        assert!(prompt.contains("素材引用 resourceId="), "{prompt}");
+        assert!(
+            !prompt.contains("请先阅读生成的带有文档的代码片段"),
+            "{prompt}"
+        );
+        assert!(!prompt.contains("生成代码遇到错误"), "{prompt}");
+    }
 }
@@ -427,12 +427,16 @@ mod tests {
        }
    }

+    /// 事件级阶段时间只在重放稳定性用例里逐个指定；其余用例用一个固定值即可，
+    /// 它们断言的是队列 / 游标语义，不是时间本身。
+    const FIXED_AT_MS: u64 = 1_000;
+
    fn item_started(item_id: &str) -> DirectThreadEvent {
-        DirectThreadEvent::item_started(message(item_id))
+        DirectThreadEvent::item_started(message(item_id), FIXED_AT_MS)
    }

    fn item_completed(item_id: &str) -> DirectThreadEvent {
-        DirectThreadEvent::item_completed(message(item_id))
+        DirectThreadEvent::item_completed(message(item_id), FIXED_AT_MS)
    }

    fn item_delta(item_id: &str) -> DirectThreadEvent {
@@ -450,7 +454,7 @@ mod tests {
    #[test]
    fn subscribers_have_independent_cursors_on_one_global_queue() {
        let mut manager = DirectThreadManager::with_limits(100, 100_000);
-        manager.append("thread-1", DirectThreadEvent::turn_started());
+        manager.append("thread-1", DirectThreadEvent::turn_started(FIXED_AT_MS));
        let first = manager.subscribe("thread-1");
        let second = manager.subscribe("thread-1");
        manager.append("thread-1", item_started("item-1"));
@@ -474,7 +478,7 @@ mod tests {
    #[test]
    fn bootstrap_contains_lifecycle_anchor_and_unfinished_events_only() {
        let mut manager = DirectThreadManager::with_limits(100, 100_000);
-        manager.append("thread-1", DirectThreadEvent::turn_started());
+        manager.append("thread-1", DirectThreadEvent::turn_started(FIXED_AT_MS));
        manager.append("thread-1", item_started("item-1"));
        manager.append("thread-1", item_delta("item-1"));
        manager.append("thread-1", item_completed("item-1"));
@@ -484,7 +488,7 @@ mod tests {
        assert!(matches!(
            bootstrap.events.as_slice(),
            [
-                DirectThreadEvent::TurnStarted {},
+                DirectThreadEvent::TurnStarted { .. },
                DirectThreadEvent::ItemStarted { item, .. },
            ] if item.item_id() == "item-2"
        ));
@@ -589,15 +593,118 @@ mod tests {
        let mut manager = DirectThreadManager::with_limits(100, 100_000);
        manager.append(
            "thread-1",
-            DirectThreadEvent::turn_completed("completed".to_string()),
+            DirectThreadEvent::turn_completed("completed".to_string(), FIXED_AT_MS),
        );
        let bootstrap = manager.subscribe("thread-1");
        assert!(matches!(
            bootstrap.events.as_slice(),
-            [DirectThreadEvent::TurnCompleted { status }] if status == "completed"
+            [DirectThreadEvent::TurnCompleted { status, at, .. }]
+                if status == "completed" && *at == Some(FIXED_AT_MS)
        ));
    }

+    /// 阶段时间必须随事件一起进队列：bootstrap 与重复订阅都拿到**原值**，
+    /// 重放不得重新取钟（否则每次重连都会把已固定的起止时间改掉）。
+    #[test]
+    fn replayed_events_keep_their_original_stage_time() {
+        let mut manager = DirectThreadManager::with_limits(100, 100_000);
+        manager.append("thread-1", DirectThreadEvent::turn_started(1_000));
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::item_started(message("item-1"), 2_000),
+        );
+
+        let first = manager.subscribe("thread-1");
+        assert_eq!(
+            first
+                .events
+                .iter()
+                .map(DirectThreadEvent::at)
+                .collect::<Vec<_>>(),
+            vec![Some(1_000), Some(2_000)]
+        );
+
+        // 第二个订阅看到的是同一份事件，时间不因"又取了一次当前时间"而漂移。
+        let second = manager.subscribe("thread-1");
+        assert_eq!(second.events, first.events);
+
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::item_completed(message("item-1"), 3_000),
+        );
+        let completion = manager
+            .consume(&first.subscription_id)
+            .expect("consume completion")
+            .events;
+        assert_eq!(
+            completion
+                .iter()
+                .map(DirectThreadEvent::at)
+                .collect::<Vec<_>>(),
+            vec![Some(3_000)]
+        );
+        // 重复消费不产生新事件，也不改写已下发过的时间。
+        assert!(manager
+            .consume(&first.subscription_id)
+            .expect("empty consume")
+            .events
+            .is_empty());
+        assert_eq!(
+            completion
+                .iter()
+                .map(DirectThreadEvent::at)
+                .collect::<Vec<_>>(),
+            vec![Some(3_000)]
+        );
+    }
+
+    /// 生命周期锚点重放时必须带上开口用户条目身份：前端在「只有锚点 + 历史切片、运行态一直空」
+    /// 的回合里也要能把边界认领给同一条用户条目，而不是按时间戳猜。
+    #[test]
+    fn bootstrap_replays_opener_user_item_id() {
+        let mut manager = DirectThreadManager::with_limits(100, 100_000);
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::turn_started(1_000)
+                .with_user_item_id(Some("direct-codex:turn-1:user")),
+        );
+        let bootstrap = manager.subscribe("thread-1");
+        assert_eq!(
+            bootstrap
+                .events
+                .iter()
+                .map(DirectThreadEvent::user_item_id)
+                .collect::<Vec<_>>(),
+            vec![Some("direct-codex:turn-1:user")]
+        );
+        assert_eq!(bootstrap.events[0].at(), Some(1_000));
+
+        // 锚点是独立保存的副本：队列里那条事件被回收之后，新订阅仍拿到同一个身份。
+        manager
+            .consume(&bootstrap.subscription_id)
+            .expect("consume anchor");
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::item_completed(message("item-1"), 2_000),
+        );
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::turn_completed("completed".to_string(), 3_000)
+                .with_user_item_id(Some("direct-codex:turn-1:user")),
+        );
+        let second = manager.subscribe("thread-1");
+        assert_eq!(
+            second
+                .events
+                .iter()
+                .map(DirectThreadEvent::user_item_id)
+                .collect::<Vec<_>>(),
+            vec![Some("direct-codex:turn-1:user")],
+            "起止同源：终态锚点也带同一个开口用户条目身份"
+        );
+        assert_eq!(second.events[0].at(), Some(3_000));
+    }
+
    #[test]
    fn queue_cleanup_only_removes_a_cleanable_prefix() {
        let mut manager = DirectThreadManager::with_limits(100, 100_000);
@@ -27,7 +27,6 @@ const DIRECT_TOOL_BRIDGE_SEARCH_URL: &str = "https://www.bing.com/search?format=
 const DIRECT_TOOL_BRIDGE_MAX_RESOURCE_NAME_CHARS: usize = 120;
 const DIRECT_TOOL_BRIDGE_MAX_RESOURCE_KIND_CHARS: usize = 80;
 const DIRECT_TOOL_BRIDGE_MAX_RESOURCE_PAGE_SIZE: usize = 100;
-const DIRECT_TOOL_BRIDGE_MAX_RESOURCE_CALLS_PER_TURN: usize = 4;
 const DIRECT_TOOL_BRIDGE_MAX_ACCOUNT_ASSET_ID_CHARS: usize = 512;
 const DIRECT_TOOL_BRIDGE_MAX_LOCAL_ASSET_PATH_CHARS: usize = 512;

@@ -68,7 +67,6 @@ struct DirectToolBridgeActiveTurnAuthorization {
    turn_id: String,
    brief_sha256: Option<String>,
    completed_result: Option<Value>,
-    resource_request_ids: BTreeMap<String, (String, String)>,
 }

 enum DirectToolBridgeRegenerationCall {
@@ -207,7 +205,6 @@ impl DirectToolBridgeState {
            turn_id: turn_id.clone(),
            brief_sha256: None,
            completed_result: None,
-            resource_request_ids: BTreeMap::new(),
        });
        Ok(DirectToolBridgeTurnGuard {
            state: Arc::clone(self),
@@ -637,30 +634,17 @@ impl DirectToolBridgeState {
        Ok(())
    }

-    fn resource_request_ids(&self, request_fingerprint: &str) -> Result<(String, String), String> {
-        let mut authorization = self
+    /// 取当前回合身份，媒体资源请求按回合身份与请求指纹确定性派生 operation/idempotency id。
+    fn active_resource_turn_id(&self) -> Result<String, String> {
+        let authorization = self
            .turn_authorization
            .lock()
            .map_err(|_| "AGC 工具桥回合授权状态不可用".to_string())?;
-        let active = authorization
+        authorization
            .active
-            .as_mut()
-            .ok_or_else(|| "当前没有客户端签发的资源生成回合身份".to_string())?;
-        if let Some(ids) = active.resource_request_ids.get(request_fingerprint) {
-            return Ok(ids.clone());
-        }
-        if active.resource_request_ids.len() >= DIRECT_TOOL_BRIDGE_MAX_RESOURCE_CALLS_PER_TURN {
-            return Err("单个用户回合最多只能创建四项媒体资源请求".to_string());
-        }
-        let operation_id =
-            direct_resource_request_uuid(&active.turn_id, "operation", request_fingerprint);
-        let idempotency_key =
-            direct_resource_request_uuid(&active.turn_id, "idempotency", request_fingerprint);
-        active.resource_request_ids.insert(
-            request_fingerprint.to_string(),
-            (operation_id.clone(), idempotency_key.clone()),
-        );
-        Ok((operation_id, idempotency_key))
+            .as_ref()
+            .map(|active| active.turn_id.clone())
+            .ok_or_else(|| "当前没有客户端签发的资源生成回合身份".to_string())
    }
 }

@@ -1213,9 +1197,9 @@ fn bridge_registered_resource(
        "mediaType": asset.media_type,
        // Agent 与 UI 必须看到同一个口径：UI 栏目走 TS 的 `gameCreationAppAssetCategory`
        // （落盘值 + 按 kind 派生 + 读时自愈），这里走 Rust 的同构实现。
-        // 直接透传落盘 `asset.category` 会让 `kind:"ui"` 的资产在 UI 显示「UI 交互」、
+        // 直接透传落盘 `asset.category` 会让 UI 设计资产在 UI 显示「UI 交互」、
        // 在 Agent 侧读到 `unclassified`（真机 55 条分歧）。
-        "category": game_creation_app_asset_effective_category(&asset.kind, asset.category),
+        "category": game_creation_app_asset_effective_category(asset.kind, asset.category),
        "tags": asset.tags,
        "canvasProjectId": asset.source.canvas_project_id,
        "resourceId": asset.source.resource_id,
@@ -1256,7 +1240,9 @@ fn bridge_list_registered_assets(root: &Path, arguments: &Value) -> Value {
            arguments,
            "kind",
            DIRECT_TOOL_BRIDGE_MAX_RESOURCE_KIND_CHARS,
-        )?;
+        )?
+        .map(|kind| bridge_asset_list_kind_filter(&kind))
+        .transpose()?;
        let asset_id = bridge_optional_bounded_string(
            arguments,
            "assetId",
@@ -1276,7 +1262,7 @@ fn bridge_list_registered_assets(root: &Path, arguments: &Value) -> Value {
        let mut assets = manifest
            .assets
            .iter()
-            .filter(|asset| kind.as_ref().is_none_or(|kind| asset.kind == *kind))
+            .filter(|asset| kind.is_none_or(|kind| asset.kind == kind))
            .filter(|asset| {
                asset_id
                    .as_ref()
@@ -1342,6 +1328,24 @@ fn bridge_list_registered_assets(root: &Path, arguments: &Value) -> Value {
    }
 }

+/// `asset.list` 的 `kind` 过滤：只接受 canonical 值，认不出的值直接报错。
+///
+/// 以前认不出的值会收口成 `unknown` 再参与等值过滤，结果是**静默返回空列表**：调用方（模型）
+/// 会以为项目里没有这类资产，而不是"你传的 kind 不合法"，于是继续按错误前提往下走。
+/// `unknown` 本身仍是合法输入（确有 kind 未知的资产），只拒绝"既不是 canonical、也不是字面
+/// `unknown`"的原值。
+fn bridge_asset_list_kind_filter(raw: &str) -> Result<GameCreationAppAssetKind, String> {
+    let kind = GameCreationAppAssetKind::parse_with_context(raw, "asset.list.kind");
+    if kind == GameCreationAppAssetKind::Unknown
+        && raw.trim() != GameCreationAppAssetKind::Unknown.as_str()
+    {
+        return Err(format!(
+            "kind 不是已知的 manifest 资源 kind：{raw}；请改用 canonical kind（如 image、scene、character、icon、icon-spritesheet、character-animation、audio、video、document）"
+        ));
+    }
+    Ok(kind)
+}
+
 fn bridge_project_file_class(path: &str) -> (&'static str, Option<&'static str>) {
    let extension = Path::new(path)
        .extension()
@@ -1890,8 +1894,11 @@ async fn bridge_create_or_derive_resource(
            ))
            .await?
        } else {
-            let (operation_id, idempotency_key) =
-                state.resource_request_ids(&request_fingerprint)?;
+            let turn_id = state.active_resource_turn_id()?;
+            let operation_id =
+                direct_resource_request_uuid(&turn_id, "operation", &request_fingerprint);
+            let idempotency_key =
+                direct_resource_request_uuid(&turn_id, "idempotency", &request_fingerprint);
            let revision = read_game_creator_agent_runtime_project_revision(&state.root)?.revision;
            let source_resource_id = source_asset
                .as_ref()
@@ -1909,7 +1916,7 @@ async fn bridge_create_or_derive_resource(
                source_asset_id: source_asset.as_ref().map(|asset| asset.id.clone()),
                source_path: source_asset.as_ref().map(|asset| asset.local_path.clone()),
                source_media_type: source_asset.as_ref().map(|asset| asset.media_type.clone()),
-                source_subtype: source_asset.as_ref().map(|asset| asset.kind.clone()),
+                source_subtype: source_asset.as_ref().map(|asset| asset.kind.to_string()),
                producer_task_id: source_asset
                    .as_ref()
                    .and_then(|asset| asset.source.task_id.clone()),
@@ -2001,7 +2008,11 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
            })
            .await?
        } else {
-            let (operation_id, idempotency_key) = state.resource_request_ids(&fingerprint)?;
+            // id 按回合身份与请求指纹确定性派生，同指纹重试与 pending 对账语义不变。
+            let turn_id = state.active_resource_turn_id()?;
+            let operation_id = direct_resource_request_uuid(&turn_id, "operation", &fingerprint);
+            let idempotency_key =
+                direct_resource_request_uuid(&turn_id, "idempotency", &fingerprint);
            let revision = read_game_creator_agent_runtime_project_revision(&state.root)?.revision;
            let request = DeriveLocalProjectResourceInput {
                project_path: state.root.to_string_lossy().into_owned(),
@@ -2015,7 +2026,7 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
                source_asset_id: Some(source_asset_id.clone()),
                source_path: Some(source_asset.local_path.clone()),
                source_media_type: Some(source_asset.media_type.clone()),
-                source_subtype: Some(source_asset.kind.clone()),
+                source_subtype: Some(source_asset.kind.to_string()),
                producer_task_id: source_asset.source.task_id.clone(),
                source_version_id: None,
                prompt: "去除背景".to_string(),
@@ -2183,35 +2194,37 @@ async fn bridge_prepare_game_art(state: &DirectToolBridgeState, arguments: &Valu
    result
 }

-fn bridge_image_generation_kind(arguments: &Value) -> Result<String, String> {
+fn bridge_image_generation_kind(arguments: &Value) -> Result<GameCreationAppAssetKind, String> {
    let kind = arguments
        .get("kind")
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .unwrap_or("image");
-    normalize_platform_art_asset_generation_kind(kind)
-        .map(str::to_string)
-        .ok_or_else(|| {
-            format!(
-                "工具参数 kind 只允许 {}",
-                PLATFORM_ART_ASSET_GENERATION_KINDS.join("、")
-            )
-        })
+    normalize_platform_art_asset_generation_kind(kind).ok_or_else(|| {
+        format!(
+            "工具参数 kind 只允许 {}",
+            PLATFORM_ART_ASSET_GENERATION_KINDS
+                .iter()
+                .map(|kind| kind.as_str())
+                .collect::<Vec<_>>()
+                .join("、")
+        )
+    })
 }

 /// 切分模式没有默认值：图集必须显式声明，且声明必须与 kind 和网格参数自洽。
 fn validate_generate_image_slice_declaration(
-    kind: &str,
+    kind: GameCreationAppAssetKind,
    slice_mode: Option<&str>,
    grid_x: Option<u32>,
    grid_y: Option<u32>,
    slice_count: Option<usize>,
 ) -> Result<(), String> {
-    if kind == "art-spritesheet" {
+    if kind == GameCreationAppAssetKind::IconSpritesheet {
        if slice_mode.is_none() {
            return Err(
-                "kind=art-spritesheet 必须显式声明 sliceMode，没有默认值：需求要求等分网格、固定槽位或指定行列数时传 sliceMode=grid 并提供 gridX/gridY；自由排布、数量不定或只要求一张图集时传 sliceMode=connected-components"
+                "kind=icon-spritesheet 必须显式声明 sliceMode，没有默认值：需求要求等分网格、固定槽位或指定行列数时传 sliceMode=grid 并提供 gridX/gridY；自由排布、数量不定或只要求一张图集时传 sliceMode=connected-components"
                    .to_string(),
            );
        }
@@ -2224,19 +2237,19 @@ fn validate_generate_image_slice_declaration(
    }
    if slice_mode.is_some() || grid_x.is_some() || grid_y.is_some() || slice_count.is_some() {
        return Err(format!(
-            "工具参数 sliceMode/gridX/gridY/sliceCount 仅对 kind=art-spritesheet 生效，当前 kind={kind}"
+            "工具参数 sliceMode/gridX/gridY/sliceCount 仅对 kind=icon-spritesheet 生效，当前 kind={kind}"
        ));
    }
    Ok(())
 }

-/// 抠图纯色背景只服务 character 与 art-spritesheet 链路；格式校验收口为
+/// 抠图纯色背景只服务 character 与 icon-spritesheet 链路；格式校验收口为
 /// `auto` 或 `#RRGGBB`（服务端另有支持色板，客户端不复制），`auto`/空串归一为
 /// None（服务端自动决策），hex 统一大写后透传。其它 kind 携带该字段直接拒绝，
 /// 避免服务端静默忽略造成“已生效”的误解。
 fn normalize_generate_image_screen_color(
    arguments: &Value,
-    kind: &str,
+    kind: GameCreationAppAssetKind,
 ) -> Result<Option<String>, String> {
    let Some(value) = arguments.get("screenColor") else {
        return Ok(None);
@@ -2244,9 +2257,12 @@ fn normalize_generate_image_screen_color(
    if value.is_null() {
        return Ok(None);
    }
-    if !matches!(kind, "character" | "art-spritesheet") {
+    if !matches!(
+        kind,
+        GameCreationAppAssetKind::Character | GameCreationAppAssetKind::IconSpritesheet
+    ) {
        return Err(format!(
-            "工具参数 screenColor 仅对 kind=character 和 kind=art-spritesheet 生效，当前 kind={kind}"
+            "工具参数 screenColor 仅对 kind=character 和 kind=icon-spritesheet 生效，当前 kind={kind}"
        ));
    }
    let raw = value
@@ -2373,24 +2389,26 @@ async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value)
            })
            .transpose()?;
        validate_generate_image_slice_declaration(
-            kind.as_str(),
+            kind,
            slice_mode.as_deref(),
            grid_x,
            grid_y,
            slice_count,
        )?;
-        let screen_color = normalize_generate_image_screen_color(arguments, kind.as_str())?;
+        let screen_color = normalize_generate_image_screen_color(arguments, kind)?;
        let options = PlatformArtAssetGenerationOptions {
            output_path,
            aspect_ratio,
            image_size,
-            asset_kind: kind.clone(),
+            asset_kind: kind,
            asset_label: asset_name.clone(),
            replace_existing: false,
            slice_count,
            slice_mode,
            grid_x,
            grid_y,
+            reference_asset_ids: Vec::new(),
+            target_category: None,
            screen_color,
        };
        let _generation_guard = state.image_generation_gate.lock().await;
@@ -2871,14 +2889,19 @@ pub(crate) async fn start_direct_tool_bridge(
 mod tests {
    #[test]
    fn generate_image_slice_declaration_is_explicit_and_self_consistent() {
-        let missing =
-            validate_generate_image_slice_declaration("art-spritesheet", None, None, None, None)
-                .expect_err("art-spritesheet without sliceMode must fail closed");
+        let missing = validate_generate_image_slice_declaration(
+            GameCreationAppAssetKind::IconSpritesheet,
+            None,
+            None,
+            None,
+            None,
+        )
+        .expect_err("icon-spritesheet without sliceMode must fail closed");
        assert!(missing.contains("没有默认值"), "{missing}");
        assert!(missing.contains("connected-components"), "{missing}");

        assert!(validate_generate_image_slice_declaration(
-            "art-spritesheet",
+            GameCreationAppAssetKind::IconSpritesheet,
            Some("connected-components"),
            None,
            None,
@@ -2886,7 +2909,7 @@ mod tests {
        )
        .is_ok());
        assert!(validate_generate_image_slice_declaration(
-            "art-spritesheet",
+            GameCreationAppAssetKind::IconSpritesheet,
            Some("grid"),
            Some(3),
            Some(2),
@@ -2894,7 +2917,7 @@ mod tests {
        )
        .is_ok());
        let grid_with_count = validate_generate_image_slice_declaration(
-            "art-spritesheet",
+            GameCreationAppAssetKind::IconSpritesheet,
            Some("grid"),
            Some(2),
            Some(2),
@@ -2904,58 +2927,80 @@ mod tests {
        assert!(grid_with_count.contains("gridX×gridY"), "{grid_with_count}");

        let wrong_kind = validate_generate_image_slice_declaration(
-            "image",
+            GameCreationAppAssetKind::Image,
            Some("connected-components"),
            None,
            None,
            None,
        )
-        .expect_err("slice declaration must stay scoped to art-spritesheet");
+        .expect_err("slice declaration must stay scoped to icon-spritesheet");
        assert!(
-            wrong_kind.contains("仅对 kind=art-spritesheet 生效"),
+            wrong_kind.contains("仅对 kind=icon-spritesheet 生效"),
            "{wrong_kind}"
        );
-        let wrong_kind_count =
-            validate_generate_image_slice_declaration("image", None, None, None, Some(8))
-                .expect_err("sliceCount-only violation must be rejected");
+        let wrong_kind_count = validate_generate_image_slice_declaration(
+            GameCreationAppAssetKind::Image,
+            None,
+            None,
+            None,
+            Some(8),
+        )
+        .expect_err("sliceCount-only violation must be rejected");
        assert!(
            wrong_kind_count.contains("sliceCount"),
            "sliceCount-only violation must name sliceCount: {wrong_kind_count}"
        );
-        assert!(validate_generate_image_slice_declaration("image", None, None, None, None).is_ok());
+        assert!(validate_generate_image_slice_declaration(
+            GameCreationAppAssetKind::Image,
+            None,
+            None,
+            None,
+            None
+        )
+        .is_ok());
    }

    #[test]
    fn generate_image_screen_color_is_normalized_and_kind_gated() {
        // 省略与显式 null 等价，且不触发 kind 门禁。
        assert_eq!(
-            normalize_generate_image_screen_color(&json!({}), "image").expect("omitted"),
+            normalize_generate_image_screen_color(&json!({}), GameCreationAppAssetKind::Image)
+                .expect("omitted"),
            None
        );
        assert_eq!(
-            normalize_generate_image_screen_color(&json!({"screenColor": null}), "image")
-                .expect("null"),
+            normalize_generate_image_screen_color(
+                &json!({"screenColor": null}),
+                GameCreationAppAssetKind::Image
+            )
+            .expect("null"),
            None
        );
        // auto 家族归一为 None（服务端自动决策），大小写与空白不敏感。
        for raw in ["auto", "AUTO", " auto ", ""] {
            assert_eq!(
-                normalize_generate_image_screen_color(&json!({"screenColor": raw}), "character")
-                    .expect("auto variants"),
+                normalize_generate_image_screen_color(
+                    &json!({"screenColor": raw}),
+                    GameCreationAppAssetKind::Character
+                )
+                .expect("auto variants"),
                None,
                "{raw}"
            );
        }
        // hex 统一大写透传；色板白名单由服务端权威校验，客户端只守格式。
        assert_eq!(
-            normalize_generate_image_screen_color(&json!({"screenColor": "#cfefff"}), "character")
-                .expect("lowercase hex"),
+            normalize_generate_image_screen_color(
+                &json!({"screenColor": "#cfefff"}),
+                GameCreationAppAssetKind::Character
+            )
+            .expect("lowercase hex"),
            Some("#CFEFFF".to_string())
        );
        assert_eq!(
            normalize_generate_image_screen_color(
                &json!({"screenColor": " #A0BBA0 "}),
-                "art-spritesheet"
+                GameCreationAppAssetKind::IconSpritesheet
            )
            .expect("padded hex"),
            Some("#A0BBA0".to_string())
@@ -2963,19 +3008,24 @@ mod tests {
        // 非 auto/非 hex、非字符串一律拒绝。
        for bad in [json!("green"), json!("#GGGGGG"), json!("#FFF"), json!(12)] {
            assert!(
-                normalize_generate_image_screen_color(&json!({"screenColor": bad}), "character")
-                    .is_err(),
+                normalize_generate_image_screen_color(
+                    &json!({"screenColor": bad}),
+                    GameCreationAppAssetKind::Character
+                )
+                .is_err(),
                "{bad}"
            );
        }
        // 其它 kind 携带该字段直接拒绝，即使取值合法。
-        let gated =
-            normalize_generate_image_screen_color(&json!({"screenColor": "#CFEFFF"}), "image")
-                .expect_err("screenColor must stay scoped to character/art-spritesheet");
+        let gated = normalize_generate_image_screen_color(
+            &json!({"screenColor": "#CFEFFF"}),
+            GameCreationAppAssetKind::Image,
+        )
+        .expect_err("screenColor must stay scoped to character/icon-spritesheet");
        assert!(gated.contains("kind=character"), "{gated}");
        assert!(normalize_generate_image_screen_color(
            &json!({"screenColor": "auto"}),
-            "ui-prototype"
+            GameCreationAppAssetKind::UiDesign
        )
        .is_err());
    }
@@ -3744,12 +3794,14 @@ mod tests {
    fn bridge_art_resource_exposes_only_the_safe_identity_projection() {
        let asset = GameCreationAppAssetManifestEntry {
            id: "local-art-1".to_string(),
-            kind: "art-spritesheet-slice".to_string(),
+            kind: GameCreationAppAssetKind::Icon,
            media_type: "image/png".to_string(),
            local_path: "assets/art-spritesheet-slices/player.png".to_string(),
            image_sequence_frames: None,
            image_sequence_duration_ms: None,
-            category: game_creation_app_asset_category_for_kind("art-spritesheet-slice"),
+            category: game_creation_app_asset_category_for_kind(
+                GameCreationAppAssetKind::IconSpritesheet,
+            ),
            tags: Vec::new(),
            source: GameCreationAppAssetSource {
                kind: GameCreationAppAssetSourceKind::Canvas,
@@ -3801,7 +3853,7 @@ mod tests {
    fn bridge_registered_resource_exposes_formal_sequence_without_private_generation_fields() {
        let asset = GameCreationAppAssetManifestEntry {
            id: "animation-1".to_string(),
-            kind: "character-animation".to_string(),
+            kind: GameCreationAppAssetKind::CharacterAnimation,
            media_type: "video/mp4".to_string(),
            local_path: "assets/edits/animation.mp4".to_string(),
            image_sequence_frames: Some(vec![
@@ -3814,7 +3866,9 @@ mod tests {
                },
            ]),
            image_sequence_duration_ms: Some(4_000),
-            category: game_creation_app_asset_category_for_kind("character-animation"),
+            category: game_creation_app_asset_category_for_kind(
+                GameCreationAppAssetKind::CharacterAnimation,
+            ),
            tags: Vec::new(),
            source: GameCreationAppAssetSource {
                kind: GameCreationAppAssetSourceKind::Canvas,
@@ -3852,7 +3906,7 @@ mod tests {
    fn bridge_registered_resource_keeps_explicit_manifest_classification() {
        let asset = GameCreationAppAssetManifestEntry {
            id: "spec-1".to_string(),
-            kind: "spec".to_string(),
+            kind: GameCreationAppAssetKind::Spec,
            media_type: "application/json".to_string(),
            local_path: "assets/specs/hero.json".to_string(),
            image_sequence_frames: None,
@@ -3888,13 +3942,13 @@ mod tests {
    ///
    /// UI 栏目走 TS 的 `gameCreationAppAssetCategory`（落盘值 + 按 kind 派生 + 读时自愈），
    /// Agent 走 Rust 的同构实现 `game_creation_app_asset_effective_category`。直接透传落盘
-    /// `category` 会让 `kind:"ui"` 的资产在 UI 显示「UI 交互」、在 Agent 侧读到
-    /// `unclassified`——真机 122 条资产里有 55 条这样分叉。
+    /// `category` 会让 `ui-design` 的资产在 UI 显示「UI 交互」、在 Agent 侧读到
+    /// `unclassified`，两侧分类口径必须一致。
    #[test]
    fn bridge_registered_resource_projects_effective_category_not_raw_persisted_value() {
        let asset = GameCreationAppAssetManifestEntry {
-            id: "ui-1".to_string(),
-            kind: "ui".to_string(),
+            id: "ui-design-1".to_string(),
+            kind: GameCreationAppAssetKind::UiDesign,
            media_type: "application/json".to_string(),
            local_path: "assets/UI 设计 1.json".to_string(),
            image_sequence_frames: None,
@@ -3917,7 +3971,7 @@ mod tests {
        };

        let projection = bridge_registered_resource(&asset, false);
-        assert_eq!(projection["kind"], "ui");
+        assert_eq!(projection["kind"], "ui-design");
        assert_eq!(projection["category"], "ui-interaction");
    }

@@ -247,7 +247,7 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab
                            "type": "string",
                            "enum": PLATFORM_ART_ASSET_GENERATION_KINDS,
                            "default": "image",
-                            "description": "image=普通新图（不做额外处理），character=角色图（纯色底生成后自动抠图，产出透明背景立绘，prompt 只描述角色主体），spec/icon-spec=统一视觉规范图（spec 是服务端同义词，客户端统一登记为 icon-spec），ui-prototype=完整 UI 设计图，art-spritesheet=透明游戏素材图集（纯色底生成后自动抠图并切片，项目须已有 icon-spec 规范图），publication-material=发布宣传图"
+                            "description": "image=普通新图（不做额外处理），character=角色图（纯色底生成后自动抠图，产出透明背景立绘，prompt 只描述角色主体），icon-spec=统一视觉规范图，ui-design=完整 UI 设计图，icon-spritesheet=透明游戏素材图集（纯色底生成后自动抠图并切片，项目须已有 icon-spec 规范图），publication-material=发布宣传图"
                        },
                        "aspectRatio": {
                            "type": "string",
@@ -273,7 +273,7 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab
                        "sliceMode": {
                            "type": "string",
                            "enum": ["connected-components", "grid"],
-                            "description": "仅 kind=art-spritesheet 生效，且必填、没有默认值：需求明确要求等分网格、固定槽位或指定行列数时传 grid，并用 gridX/gridY 传入来自需求本身的行列数；自由排布、数量不定或只要求一张图集时传 connected-components，需要约束素材张数时用 sliceCount。省略、与 kind 不匹配或与 gridX/gridY 互相矛盾时客户端直接拒绝，不会替你选择"
+                            "description": "仅 kind=icon-spritesheet 生效，且必填、没有默认值：需求明确要求等分网格、固定槽位或指定行列数时传 grid，并用 gridX/gridY 传入来自需求本身的行列数；自由排布、数量不定或只要求一张图集时传 connected-components，需要约束素材张数时用 sliceCount。省略、与 kind 不匹配或与 gridX/gridY 互相矛盾时客户端直接拒绝，不会替你选择"
                        },
                        "gridX": {
                            "type": "integer",
@@ -291,11 +291,11 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 256,
-                            "description": "只与 kind=art-spritesheet 且 sliceMode=connected-components 同时提供，用于约束目标素材张数；省略时按图像内容自动识别"
+                            "description": "只与 kind=icon-spritesheet 且 sliceMode=connected-components 同时提供，用于约束目标素材张数；省略时按图像内容自动识别"
                        },
                        "screenColor": {
                            "type": "string",
-                            "description": "抠图纯色背景，仅 kind=character（角色形象）和 kind=art-spritesheet（图标素材）生效，其它 kind 携带会被拒绝。生成时把主体置于该纯色背景上，回图后据此抠除背景。取值只能是 auto 或下列色板 hex 之一，传值只填 hex 本身、不要附带色名：#CFEFFF（浅雾蓝）、#B0C2E0（浅钢蓝）、#FFD6C2（暖浅桃色）、#E6D8FF（淡薰衣草紫）、#F4D8E8（浅粉灰）、#7FB3FF（中度天蓝）、#FFF2A8（浅柠黄）、#CFFFE1（淡薄荷绿）、#D8DEE8（浅中性灰）、#D8D2E8（淡灰紫）、#A8F7F0（高对比浅青）、#A0BBA0（灰竹绿）；auto 时由服务端自动选色。手动指定时不能与角色或素材本体的颜色接近"
+                            "description": "抠图纯色背景，仅 kind=character（角色形象）和 kind=icon-spritesheet（图标素材）生效，其它 kind 携带会被拒绝。生成时把主体置于该纯色背景上，回图后据此抠除背景。取值只能是 auto 或下列色板 hex 之一，传值只填 hex 本身、不要附带色名：#CFEFFF（浅雾蓝）、#B0C2E0（浅钢蓝）、#FFD6C2（暖浅桃色）、#E6D8FF（淡薰衣草紫）、#F4D8E8（浅粉灰）、#7FB3FF（中度天蓝）、#FFF2A8（浅柠黄）、#CFFFE1（淡薄荷绿）、#D8DEE8（浅中性灰）、#D8D2E8（淡灰紫）、#A8F7F0（高对比浅青）、#A0BBA0（灰竹绿）；auto 时由服务端自动选色。手动指定时不能与角色或素材本体的颜色接近"
                        }
                    },
                    "required": ["prompt"],
@@ -341,7 +341,7 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 80,
-                            "description": "可选的 manifest 资源 kind 精确过滤，例如 video、character-animation、sound-effect、background-music 或 art-spritesheet-slice"
+                            "description": "可选的 manifest 资源 kind 精确过滤，必须是 canonical kind（例如 video、character-animation、sound-effect、background-music、icon-spritesheet）；传非 canonical 值会被拒绝并报错，不会静默返回空列表"
                        },
                        "assetId": {
                            "type": "string",
@@ -2523,7 +2523,7 @@ mod tests {
        // 目录外的 kind 必须在本地拒绝：既不下发 bridge，也不产生任何计费副作用。
        let unsupported_kind = call_agc_generate_image(&json!({
            "prompt": "像素月光主角",
-            "kind": "game-art"
+            "kind": "future-kind"
        }))
        .await;
        assert_eq!(unsupported_kind["isError"], json!(true));
@@ -2533,7 +2533,7 @@ mod tests {

        let oversized_prompt = call_agc_generate_image(&json!({
            "prompt": "x".repeat(DIRECT_TOOLS_MCP_MAX_IMAGE_PROMPT_CHARS + 1),
-            "kind": "art-spritesheet"
+            "kind": "icon-spritesheet"
        }))
        .await;
        assert_eq!(oversized_prompt["isError"], json!(true));
@@ -2897,12 +2897,12 @@ mod tests {
    fn tool_chain_image_asset(id: &str, local_path: &str) -> GameCreationAppAssetManifestEntry {
        GameCreationAppAssetManifestEntry {
            id: id.to_string(),
-            kind: "image".to_string(),
+            kind: GameCreationAppAssetKind::Image,
            media_type: "image/png".to_string(),
            local_path: local_path.to_string(),
            image_sequence_frames: None,
            image_sequence_duration_ms: None,
-            category: game_creation_app_asset_category_for_kind("image"),
+            category: game_creation_app_asset_category_for_kind(GameCreationAppAssetKind::Image),
            tags: Vec::new(),
            source: GameCreationAppAssetSource {
                kind: GameCreationAppAssetSourceKind::Canvas,
@@ -67,10 +67,11 @@ pub(crate) use canvas_generation::{
    generate_platform_art_asset_with_options_at,
    generate_platform_art_asset_with_required_slices_at, maybe_generate_platform_art_asset_step,
    needs_platform_art_asset_generation, normalize_platform_art_asset_generation_kind,
+    normalize_platform_art_reference_asset_ids, normalize_platform_art_target_category,
    platform_art_asset_art_spec, platform_art_asset_output_extension_matches,
-    prepare_platform_art_asset_output_path, project_canvas_asset_media_types,
-    role_has_canvas_assets, suggested_canvas_tool_call, PlatformArtAssetGenerationOptions,
-    PLATFORM_ART_ASSET_GENERATION_KINDS,
+    platform_art_runtime_references_match_request_contract, prepare_platform_art_asset_output_path,
+    project_canvas_asset_media_types, role_has_canvas_assets, suggested_canvas_tool_call,
+    PlatformArtAssetGenerationOptions, PLATFORM_ART_ASSET_GENERATION_KINDS,
 };
 #[allow(unused_imports)]
 pub(crate) use draft_validation::{
@@ -31,9 +31,9 @@ fn is_direct_platform_art_generation_runtime_context(
    context: &PlatformArtGenerationRuntimeContext,
 ) -> bool {
    let asset_kind = match context.run_id.as_str() {
-        "art-spec" => "icon-spec",
-        "game-background" => "game-background",
-        "art-spritesheet" => "art-spritesheet",
+        "art-spec" => GameCreationAppAssetKind::IconSpec,
+        "game-background" => GameCreationAppAssetKind::Scene,
+        "art-spritesheet" => GameCreationAppAssetKind::IconSpritesheet,
        _ => return false,
    };
    context.agent_id == "direct-codex-art"
@@ -42,7 +42,11 @@ fn is_direct_platform_art_generation_runtime_context(
        && context.source == "direct-codex"
        && context.action_id == format!("direct-taonier-{}", context.run_id)
        && context.action_fingerprint
-            == format!("direct-taonier-art-v1:{asset_kind}:{}", context.run_id)
+            == format!(
+                "direct-taonier-art-v1:{}:{}",
+                asset_kind.as_str(),
+                context.run_id
+            )
 }

 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -98,7 +98,7 @@ pub(crate) fn render_local_asset_prompt_context(root: &Path) -> Result<String, S
            output.push_str("- ");
            output.push_str(&asset.id);
            output.push_str(": ");
-            output.push_str(&asset.kind);
+            output.push_str(asset.kind.as_str());
            output.push_str(" / ");
            output.push_str(&asset.media_type);
            output.push_str(" / ");
@@ -396,7 +396,7 @@ fn agent_runtime_action_receipt_safe_detail_with_owner(
        let inspection_kind = detail
            .get("inspectionKind")
            .and_then(serde_json::Value::as_str)
-            .filter(|value| *value == AGENT_RUNTIME_UI_PROTOTYPE_INSPECTION_KIND);
+            .filter(|value| *value == AGENT_RUNTIME_UI_DESIGN_INSPECTION_KIND);
        let validation_profile = detail
            .get("validationProfile")
            .and_then(serde_json::Value::as_str)
@@ -408,7 +408,7 @@ fn agent_runtime_action_receipt_safe_detail_with_owner(
                )
            });
        let (passed, checks, issues) = if validation_profile.is_some() {
-            if inspection_kind != Some(AGENT_RUNTIME_UI_PROTOTYPE_INSPECTION_KIND) {
+            if inspection_kind != Some(AGENT_RUNTIME_UI_DESIGN_INSPECTION_KIND) {
                return None;
            }
            let passed = detail.get("passed")?.as_bool()?;
@@ -2061,17 +2061,23 @@ mod tests {
        .expect("resume first manifest task fixture");

        for (local_path, kind) in [
-            ("assets/art-spec.png", "icon-spec"),
-            ("assets/ui-prototype.png", "ui-prototype"),
-            ("assets/art-spritesheet.png", "art-spritesheet"),
+            ("assets/art-spec.png", GameCreationAppAssetKind::IconSpec),
+            (
+                "assets/ui-prototype.png",
+                GameCreationAppAssetKind::UiDesign,
+            ),
+            (
+                "assets/art-spritesheet.png",
+                GameCreationAppAssetKind::IconSpritesheet,
+            ),
        ] {
            let (generation_route, generation_kind, reference_resource_ids) = match kind {
-                "icon-spec" => (
+                GameCreationAppAssetKind::IconSpec => (
                    "/api/external/v1/editor/images/generations",
                    "spec",
                    Vec::new(),
                ),
-                "ui-prototype" => (
+                GameCreationAppAssetKind::UiDesign => (
                    "/api/external/v1/editor/images/generations",
                    "ui-design",
                    vec!["resource-icon-spec".to_string()],
@@ -2082,7 +2088,7 @@ mod tests {
                    vec!["resource-icon-spec".to_string()],
                ),
            };
-            let bytes = if kind == "art-spritesheet" {
+            let bytes = if kind == GameCreationAppAssetKind::IconSpritesheet {
                use image::ImageEncoder;
                let mut bytes = Vec::new();
                image::codecs::png::PngEncoder::new(&mut bytes)
--- a/Show More
+++ b/Show More