补齐模板库页面单测与真连建项目检查

- 前端单测迁到 apps/ai-game-creator-shell/tests/，与根 vitest include 一致；新增模板库页面与首页推荐位 8 项渲染/交互测试（卡片封面、标签、已下载徽标、搜索、筛选、下载与使用模板、空态与错误态）
- 模板库的运行时与标签筛选补 aria-label，避免同名按钮歧义
- 真连检查扩展为「读线上清单 → 下载安装线上模板 → 据此建项目」的完整链路
- 同步技术方案、里程碑与实施计划的验证命令与验收口径

.gitea/workflows/project-ci.yml

@@ -7,10 +7,6 @@ on:
   pull_request:
   workflow_dispatch:
 
-concurrency:
-  group: project-ci-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
 permissions:
   contents: read
 

apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx

@@ -38,7 +38,6 @@ vi.mock('../api/adminApiClient', () => ({
 
 interface MockIntersectionObserverController {
   enter: (target: Element) => void;
-  enterAll: (targets: Element[]) => void;
   isObserved: (target: Element) => boolean;
 }
 
@@ -107,25 +106,6 @@ function installIntersectionObserverMock(): MockIntersectionObserverController {
         );
       });
     },
-    enterAll(targets) {
-      act(() => {
-        for (const target of targets) {
-          const record = observed.get(target);
-          if (!record) {
-            throw new Error('目标缩略图尚未进入 IntersectionObserver');
-          }
-          record.callback(
-            [
-              {
-                isIntersecting: true,
-                target,
-              } as IntersectionObserverEntry,
-            ],
-            record.observer,
-          );
-        }
-      });
-    },
     isObserved(target) {
       return observed.has(target);
     },
@@ -773,10 +753,10 @@ test('后台素材查询为大量同时可见的缩略图持续错峰换签', as
   const thumbnails = entries.map((entry) =>
     thumbnailElementForLabel(entry.label),
   );
-  for (const thumbnail of thumbnails) {
+  thumbnails.forEach((thumbnail) => {
     expect(observer.isObserved(thumbnail)).toBe(true);
-  }
-  observer.enterAll(thumbnails);
+    observer.enter(thumbnail);
+  });
   await act(async () => {
     await Promise.resolve();
   });
@@ -796,7 +776,7 @@ test('后台素材查询为大量同时可见的缩略图持续错峰换签', as
     await vi.advanceTimersByTimeAsync(200);
   });
   expect(getAdminAssetReadUrl).toHaveBeenCalledTimes(105);
-}, 10_000);
+});
 
 test('后台素材查询读取更多后为新进入可视区域的素材换签', async () => {
   const observer = installIntersectionObserverMock();

apps/ai-game-creator-shell/src-tauri/design-agent/tools.json

@@ -2,7 +2,7 @@
   {"type":"function","function":{"name":"get_workflow_status","description":"读取当前策划工作流状态，只返回阶段列表、当前阶段、已批准阶段和待审批阶段；不推进阶段、不提交审批、不修改文件。","parameters":{"type":"object","properties":{},"additionalProperties":false}}},
   {"type":"function","function":{"name":"list_resources","description":"列出固定资源的逻辑目录、资源 ID、标题和简介。资源是只读的随包文档；不要猜测物理路径。","parameters":{"type":"object","properties":{},"additionalProperties":false}}},
   {"type":"function","function":{"name":"read_resource","description":"读取一份固定资源文档全文。每次读取一个 resource_id；资源只读。读到未实现占位文档时由你自行判断和处理。","parameters":{"type":"object","properties":{"resource_id":{"type":"string"}},"required":["resource_id"],"additionalProperties":false}}},
-  {"type":"function","function":{"name":"patch_file","description":"局部修改 UTF-8 文件。使用 old_text/new_text，或使用 edits 一次进行多个独立替换；每个 old_text 必须非空且在原文件中唯一。所有 edit 会一次性校验；任何失败都不修改文件，错误会列出各失败项及可唯一匹配的其余项。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"},"old_text":{"type":"string"},"new_text":{"type":"string"},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string"},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false}}},"required":["path"],"additionalProperties":false}}},
+  {"type":"function","function":{"name":"patch_file","description":"局部修改 UTF-8 文件。使用 old_text/new_text，或使用 edits 一次进行多个独立替换；每个 old_text 必须非空且在原文件中唯一，匹配失败、重复或范围重叠时不修改文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"},"old_text":{"type":"string"},"new_text":{"type":"string"},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string"},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false}}},"required":["path"],"additionalProperties":false}}},
   {"type":"function","function":{"name":"delete_path","description":"谨慎使用；永久删除工作区内的文件或目录；目录会连同全部内容递归删除，不备份。先确认目标及删除范围。path 使用相对路径，不能删除工作区根目录，也不能经过链接。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},
   {"type":"function","function":{"name":"list_dir","description":"列出工作目录内的文件和目录。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},
   {"type":"function","function":{"name":"read_file","description":"读取工作目录内的 UTF-8 文本文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},

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

@@ -527,6 +527,10 @@ fn process_design_batch(
         let result = if uncertain {
             Err("进程在工具执行期间中断，执行结果未保存。未重复执行；请读取实际工作区确认结果后再决定下一步。".to_string())
         } else {
+            let _write = acquire_game_creator_agent_runtime_project_write_lock_with_wait(
+                root,
+                "design.tool",
+            )?;
             execute_design_tool(root, resources, session, &call)
         };
         let error = result
@@ -1022,15 +1026,6 @@ pub(crate) async fn continue_design_agent_at(
     finish_design_command(root, resources, session, active, run, emit).await
 }
 
-async fn recover_uncertain_design_batch(
-    root: &Path,
-    resources: &DesignResources,
-    session: DesignSession,
-    active: File,
-) -> Result<DesignView, String> {
-    finish_design_command(root, resources, session, active, true, |_| {}).await
-}
-
 pub(crate) async fn decide_design_phase_at(
     root: &Path,
     resources: &DesignResources,
@@ -1063,8 +1058,7 @@ fn ensure_design_runtime_active(root: &Path) -> Result<(), String> {
 }
 
 #[tauri::command]
-pub(crate) async fn hydrate_design_agent_session(
-    app: tauri::AppHandle,
+pub(crate) fn hydrate_design_agent_session(
     project_path: String,
 ) -> Result<Option<DesignView>, String> {
     let root = Path::new(project_path.trim());
@@ -1090,33 +1084,8 @@ pub(crate) async fn hydrate_design_agent_session(
     if session.project_id != project_id {
         return Err("策划会话与当前项目不匹配".into());
     }
-    let Some(active) =
-        try_open_game_creator_agent_runtime_task_lock_file(root, DESIGN_ACTIVE_LOCK)?
-    else {
-        return Ok(Some(design_view(&session, true)));
-    };
-    if design_session_has_uncertain_batch(&session) {
-        let resources = DesignResources::new(resolve_design_resources_root(&app)?)?;
-        let view = recover_uncertain_design_batch(root, &resources, session, active).await?;
-        return Ok(Some(view));
-    }
-    drop(active);
-    Ok(Some(design_view(&session, false)))
-}
-
-fn design_session_has_uncertain_batch(session: &DesignSession) -> bool {
-    let Some(batch) = session.pending_batch.as_ref() else {
-        return false;
-    };
-    if !batch.executing || batch.cursor >= batch.calls.len() {
-        return false;
-    }
-    let call_id = batch.calls[batch.cursor].id.as_str();
-    session.turn.as_ref().is_some_and(|turn| turn.pending)
-        && !session.history.iter().any(|item| {
-            item.get("type").and_then(Value::as_str) == Some("function_call_output")
-                && item.get("call_id").and_then(Value::as_str) == Some(call_id)
-        })
+    let active = try_open_game_creator_agent_runtime_task_lock_file(root, DESIGN_ACTIVE_LOCK)?;
+    Ok(Some(design_view(&session, active.is_none())))
 }
 
 fn design_session_error_is_recoverable(error: &str) -> bool {
@@ -1989,94 +1958,4 @@ mod tests {
             .any(|message| message.text.contains("重试后继续")));
         assert!(next.session.last_error.is_none());
     }
-
-    #[tokio::test(flavor = "current_thread")]
-    async fn uncertain_batch_hydrate_continues_the_original_turn_without_replaying_file_tools() {
-        let (_temp, root, resources) = init_design_project();
-        execute_design_file_tool(
-            &root,
-            "write_file",
-            &json!({"path":"project/00_concept/design.md","content":"概念"}),
-        )
-        .expect("write concept");
-        let mut session = new_design_session("design-fake", "quality");
-        let call = platform_llm::LlmToolCall {
-            id: "interrupted-call".into(),
-            name: "patch_file".into(),
-            arguments: json!({
-                "path":"project/00_concept/design.md",
-                "old_text":"概念",
-                "new_text":"概念设计"
-            })
-            .to_string(),
-        };
-        session.history.push(json!({
-            "type":"function_call",
-            "call_id":call.id,
-            "name":call.name,
-            "arguments":call.arguments,
-        }));
-        session.messages = vec![DesignMessage {
-            id: "turn:user".into(),
-            role: "user".into(),
-            text: "继续".into(),
-        }];
-        session.turn = Some(DesignTurn {
-            id: "turn-recovery".into(),
-            pending: true,
-            request_index: 0,
-            attempt: 0,
-        });
-        session.pending_batch = Some(DesignToolBatch {
-            calls: vec![call],
-            cursor: 0,
-            executing: true,
-        });
-        assert!(design_session_has_uncertain_batch(&session));
-        write_design_session(&root, &session).expect("write interrupted session");
-
-        let _fake = fake_provider::install(
-            vec![Ok(fake_response(
-                "recovered-after-uncertain-tool",
-                "已读取文件并确认。",
-                Vec::new(),
-            ))],
-            0,
-        );
-        let view = recover_uncertain_design_batch(&root, &resources, session, {
-            try_open_game_creator_agent_runtime_task_lock_file(
-                &root,
-                ".agent/design-agent/active.lock",
-            )
-            .expect("open active lock")
-            .expect("active lock is free")
-        })
-        .await
-        .expect("recover uncertain batch");
-
-        assert!(!view.running);
-        assert!(view.session.last_error.is_none());
-        let restored = read_design_session(&root)
-            .expect("read restored")
-            .expect("session");
-        assert!(restored.pending_batch.is_none());
-        assert!(!restored.turn.expect("turn").pending);
-        assert!(restored.history.iter().any(|item| {
-            item.get("type").and_then(Value::as_str) == Some("function_call_output")
-                && item.get("call_id").and_then(Value::as_str) == Some("interrupted-call")
-                && item
-                    .get("output")
-                    .and_then(Value::as_str)
-                    .is_some_and(|output| output.contains("执行结果未保存"))
-        }));
-        assert!(restored.history.iter().any(|item| {
-            item.get("role").and_then(Value::as_str) == Some("assistant")
-                && item.get("content").is_some()
-        }));
-        assert!(
-            fs::read_to_string(root.join("design_artifacts/project/00_concept/design.md"))
-                .expect("read target")
-                == "概念"
-        );
-    }
 }

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

@@ -321,31 +321,15 @@ pub(crate) fn execute_design_file_tool(
                 })
                 .collect::<Vec<_>>();
             let mut matches = Vec::new();
-            let mut edit_errors = Vec::new();
-            let mut valid_edits = 0;
             for (index, (old, new)) in normalized.iter().enumerate() {
-                if old == new {
-                    edit_errors.push(format!(
-                        "edits[{index}] new_text 与 old_text 相同，不会产生修改"
-                    ));
-                    continue;
-                }
                 let count = content.matches(old).count();
                 if count == 0 {
-                    edit_errors.push(format!(
-                        "edits[{index}] 原文未找到：{}{}",
-                        display,
-                        design_patch_location_hint(&content, old)
-                    ));
-                    continue;
+                    return Err(format!("edits[{index}] 原文未找到：{display}"));
                 }
                 if count != 1 {
-                    let start = content.find(old).expect("count checked");
-                    let line = design_patch_line_number(&content, start);
-                    edit_errors.push(format!(
-                        "edits[{index}] 原文匹配 {count} 处，必须唯一；首次位于第 {line} 行"
+                    return Err(format!(
+                        "edits[{index}] 原文匹配 {count} 处，必须唯一：{display}"
                     ));
-                    continue;
                 }
                 let start = content.find(old).expect("count checked");
                 let end = start + old.len();
@@ -353,33 +337,13 @@ pub(crate) fn execute_design_file_tool(
                     .iter()
                     .find(|(_, other_start, other_end)| start < *other_end && *other_start < end)
                 {
-                    edit_errors.push(format!(
-                        "edits[{index}] 与 edits[{other_index}] 修改范围重叠；请合并为一个 edit 或缩短 old_text"
+                    return Err(format!(
+                        "edits[{index}] 与 edits[{other_index}] 修改范围重叠：{display}"
                     ));
-                    continue;
                 }
                 matches.push((index, start, end));
-                valid_edits += 1;
                 let _ = new;
             }
-            if !edit_errors.is_empty() {
-                let shown = edit_errors.len().min(4);
-                let mut details = edit_errors[..shown].to_vec();
-                if shown < edit_errors.len() {
-                    details.push(format!(
-                        "另有 {} 个 edit 校验失败（详情省略）",
-                        edit_errors.len() - shown
-                    ));
-                }
-                if valid_edits > 0 {
-                    details.push(format!(
-                        "其余 {valid_edits} 个 edit 当前可唯一匹配；本次未写入文件"
-                    ));
-                } else {
-                    details.push("本次未写入文件".to_string());
-                }
-                return Err(details.join("\n"));
-            }
             let mut updated = content.clone();
             for (index, start, end) in matches.into_iter().rev() {
                 let (_, new) = &normalized[index];
@@ -432,60 +396,6 @@ pub(crate) fn execute_design_file_tool(
     }
 }
 
-fn design_patch_line_number(content: &str, start: usize) -> usize {
-    1 + content[..start]
-        .bytes()
-        .filter(|byte| *byte == b'\n')
-        .count()
-}
-
-fn design_patch_visible_line(line: &str) -> String {
-    line.replace('\t', "\\t").chars().take(180).collect()
-}
-
-fn design_patch_location_hint(content: &str, old: &str) -> String {
-    let Some(anchor) = old.lines().map(str::trim).find(|line| !line.is_empty()) else {
-        return String::new();
-    };
-
-    let mut candidates = content
-        .lines()
-        .enumerate()
-        .filter(|(_, line)| line.trim() == anchor)
-        .map(|(index, line)| (index + 1, line))
-        .collect::<Vec<_>>();
-    if candidates.is_empty() {
-        let token = anchor.split_whitespace().find(|token| token.len() >= 3);
-        if let Some(token) = token {
-            candidates = content
-                .lines()
-                .enumerate()
-                .filter(|(_, line)| line.trim().contains(token))
-                .map(|(index, line)| (index + 1, line))
-                .collect();
-        }
-    }
-    if candidates.is_empty() {
-        return format!(
-            "；未找到与 old_text 首个非空行相似的行（当前文件约 {} 行）",
-            content.lines().count()
-        );
-    }
-
-    let details = candidates
-        .iter()
-        .take(2)
-        .map(|(line, text)| format!("第 {line} 行：{}", design_patch_visible_line(text)))
-        .collect::<Vec<_>>()
-        .join("；");
-    let suffix = if candidates.len() > 2 {
-        format!("等 {} 处", candidates.len())
-    } else {
-        String::new()
-    };
-    format!("；old_text 首个非空行可能对应 {details}{suffix}（tab 显示为 \\t）")
-}
-
 pub(crate) fn list_design_workspace_files(
     root: &Path,
 ) -> Result<Vec<DesignWorkspaceEntry>, String> {
@@ -783,22 +693,6 @@ mod tests {
         )
         .expect_err("escape");
         assert!(escaped.contains("路径"));
-        let mismatch = execute_design_file_tool(
-            root,
-            "patch_file",
-            &json!({
-                "path":"notes/design.md",
-                "edits":[
-                    {"old_text":"  游戏设计","new_text":"游戏概念"},
-                    {"old_text":"设计","new_text":"方案"}
-                ]
-            }),
-        )
-        .expect_err("report all patch failures");
-        assert!(mismatch.contains("edits[0] 原文未找到"));
-        assert!(mismatch.contains("第 1 行：游戏设计"));
-        assert!(mismatch.contains("其余 1 个 edit 当前可唯一匹配"));
-        assert!(mismatch.contains("本次未写入文件"));
         let patched = execute_design_file_tool(
             root,
             "patch_file",

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

@@ -284,6 +284,7 @@ mod resource_inspect;
 mod resource_preview_scheduler;
 mod runner;
 mod swarm_cli;
+mod template_library;
 mod tool_plan_handoff;
 mod user_input;
 mod windows;
@@ -323,6 +324,7 @@ use resource_inspect::*;
 use resource_preview_scheduler::*;
 use runner::*;
 use swarm_cli::*;
+use template_library::*;
 use user_input::*;
 use windows::*;
 #[tauri::command]
@@ -2660,7 +2662,10 @@ fn main() {
             start_game_creator_external_mcp,
             stop_game_creator_external_mcp,
             create_automatic_local_game_project,
+            create_automatic_local_game_project_from_template,
             init_local_game_project,
+            fetch_game_template_library,
+            download_game_template,
             import_local_godot_project,
             import_local_cocos_project,
             is_local_project_directory_non_empty,

apps/ai-game-creator-shell/src-tauri/tauri.conf.json

@@ -24,8 +24,8 @@
       }
     ],
     "security": {
-      "csp": "default-src 'self' customprotocol: asset:; img-src 'self' asset: data: blob:; media-src 'self' asset: data: blob:; connect-src 'self' https://agc-dev.oss-rg-china-mainland.aliyuncs.com http://127.0.0.1:* ws://127.0.0.1:*; script-src 'self'; style-src 'self' 'unsafe-inline'; frame-src 'self' http://127.0.0.1:*",
-      "devCsp": "default-src 'self' customprotocol: asset: http://127.0.0.1:*; img-src 'self' asset: http://127.0.0.1:* data: blob:; media-src 'self' asset: http://127.0.0.1:* data: blob:; connect-src 'self' https://agc-dev.oss-rg-china-mainland.aliyuncs.com http://127.0.0.1:* ws://127.0.0.1:*; script-src 'self'; style-src 'self' 'unsafe-inline'; frame-src 'self' http://127.0.0.1:*"
+    "csp": "default-src 'self' customprotocol: asset:; img-src 'self' asset: data: blob: https://agc-dev.oss-rg-china-mainland.aliyuncs.com; media-src 'self' asset: data: blob:; connect-src 'self' https://agc-dev.oss-rg-china-mainland.aliyuncs.com http://127.0.0.1:* ws://127.0.0.1:*; script-src 'self'; style-src 'self' 'unsafe-inline'; frame-src 'self' http://127.0.0.1:*",
+    "devCsp": "default-src 'self' customprotocol: asset: http://127.0.0.1:*; img-src 'self' asset: http://127.0.0.1:* data: blob: https://agc-dev.oss-rg-china-mainland.aliyuncs.com; media-src 'self' asset: http://127.0.0.1:* data: blob:; connect-src 'self' https://agc-dev.oss-rg-china-mainland.aliyuncs.com http://127.0.0.1:* ws://127.0.0.1:*; script-src 'self'; style-src 'self' 'unsafe-inline'; frame-src 'self' http://127.0.0.1:*"
     }
   },
   "bundle": {

apps/ai-game-creator-shell/src-tauri/tests/fixtures/agc-template-library-index.json

@@ -0,0 +1,133 @@
+{
+  "schemaVersion": "agc-template-library.v1",
+  "library": "agc-game-templates",
+  "libraryVersion": 1,
+  "updatedAt": "2026-09-17T03:22:43Z",
+  "templates": [
+    {
+      "id": "blank-2d-canvas",
+      "title": "空白二维画布工程",
+      "summary": "原生 Canvas 二维空白工程：自适应画布、按设备像素比缩放与 requestAnimationFrame 主循环已就绪。",
+      "tags": [
+        "空白",
+        "起步工程",
+        "2d",
+        "canvas"
+      ],
+      "runtime": "html",
+      "engine": "canvas",
+      "engineVersion": "",
+      "templateVersion": "0.1.0",
+      "updatedAt": "2026-09-17T03:22:43Z",
+      "entry": "game/index.html",
+      "zipKey": "templates/v1/blank-2d-canvas/template.zip",
+      "zipSizeBytes": 1534,
+      "zipSha256": "ff8f84e4793941acaf161738c2795f65c5d5390de8614f51aa9e3a5771767134",
+      "coverKey": "templates/v1/blank-2d-canvas/cover.svg",
+      "coverWidth": 960,
+      "coverHeight": 540,
+      "coverSha256": "afb753dc6d3de0f9fb6e03ec94f2be7221dd04c9d4ab3cf92311879f0af25192",
+      "metadataKey": "templates/v1/blank-2d-canvas/template.json"
+    },
+    {
+      "id": "blank-3d-scene",
+      "title": "空白三维场景工程",
+      "summary": "Three.js 空白场景：空场景、透视相机、网格地面与自适应视口已就绪，适合从零搭三维玩法。",
+      "tags": [
+        "空白",
+        "起步工程",
+        "3d",
+        "three.js"
+      ],
+      "runtime": "html",
+      "engine": "three.js",
+      "engineVersion": "0.180.0",
+      "templateVersion": "0.1.0",
+      "updatedAt": "2026-09-17T03:22:43Z",
+      "entry": "game/index.html",
+      "zipKey": "templates/v1/blank-3d-scene/template.zip",
+      "zipSizeBytes": 1644,
+      "zipSha256": "f3f295f4e5adcf1445d75229dc1b583376a9bc96d3f27a257d69ee3b7cace892",
+      "coverKey": "templates/v1/blank-3d-scene/cover.svg",
+      "coverWidth": 960,
+      "coverHeight": 540,
+      "coverSha256": "1429232adaf6df4457e45b4fc8d7ee9fab2e6bffce9f3f0016e91b81bb66c6a7",
+      "metadataKey": "templates/v1/blank-3d-scene/template.json"
+    },
+    {
+      "id": "blank-web",
+      "title": "空白网页工程",
+      "summary": "最小网页工程（HTML + CSS + 原生 JS + Vite），没有任何引擎依赖，适合从零写玩法。",
+      "tags": [
+        "空白",
+        "起步工程",
+        "网页",
+        "原生"
+      ],
+      "runtime": "html",
+      "engine": "none",
+      "engineVersion": "",
+      "templateVersion": "0.1.0",
+      "updatedAt": "2026-09-17T03:22:43Z",
+      "entry": "game/index.html",
+      "zipKey": "templates/v1/blank-web/template.zip",
+      "zipSizeBytes": 1212,
+      "zipSha256": "6fa4391f30342e8dcbdcf735f990d2534ea50405f119e4fa5879b83e8f00119e",
+      "coverKey": "templates/v1/blank-web/cover.svg",
+      "coverWidth": 960,
+      "coverHeight": 540,
+      "coverSha256": "326a2753386618971b1311043effa46c2e74bc1cfb116862c0ee4097dcd5086a",
+      "metadataKey": "templates/v1/blank-web/template.json"
+    },
+    {
+      "id": "phaser-2d-starter",
+      "title": "Phaser 2D 起步工程",
+      "summary": "AGC 新建项目使用的默认二维起步工程（Phaser 4 + Vite），解压后即为可运行项目根。",
+      "tags": [
+        "起步工程",
+        "2d",
+        "phaser",
+        "像素"
+      ],
+      "runtime": "html",
+      "engine": "phaser",
+      "engineVersion": "4.2.1",
+      "templateVersion": "0.1.0",
+      "updatedAt": "2026-09-17T03:22:43Z",
+      "entry": "game/index.html",
+      "zipKey": "templates/v1/phaser-2d-starter/template.zip",
+      "zipSizeBytes": 8770,
+      "zipSha256": "9026856c3c0b3a42401172e36ce8b450a65e9f11eb9096624d8990d51449d8ce",
+      "coverKey": "templates/v1/phaser-2d-starter/cover.svg",
+      "coverWidth": 960,
+      "coverHeight": 540,
+      "coverSha256": "fdb422027bf54bf755b2b91cd21fa10fdd7ce3f5c7e3ccd9ac3ffba602b12b96",
+      "metadataKey": "templates/v1/phaser-2d-starter/template.json"
+    },
+    {
+      "id": "threejs-3d-starter",
+      "title": "Three.js 3D 起步工程",
+      "summary": "网页三维起步工程（Three.js + Vite），自带可旋转立方体场景、方向光与自适应视口。",
+      "tags": [
+        "起步工程",
+        "3d",
+        "three.js",
+        "网页"
+      ],
+      "runtime": "html",
+      "engine": "three.js",
+      "engineVersion": "0.180.0",
+      "templateVersion": "0.1.0",
+      "updatedAt": "2026-09-17T03:22:43Z",
+      "entry": "game/index.html",
+      "zipKey": "templates/v1/threejs-3d-starter/template.zip",
+      "zipSizeBytes": 1697,
+      "zipSha256": "03096152b17cd6d55e7f6ccd518485136133cb54fd2a5a5d0ac8e0974149155c",
+      "coverKey": "templates/v1/threejs-3d-starter/cover.svg",
+      "coverWidth": 960,
+      "coverHeight": 540,
+      "coverSha256": "7ba013e8a8b515d7aff7146fe401afe5ba3416b9c69db181179705e1bce01beb",
+      "metadataKey": "templates/v1/threejs-3d-starter/template.json"
+    }
+  ]
+}

apps/ai-game-creator-shell/src/features/agent-runtime/directActiveTurns.ts

@@ -38,16 +38,11 @@ export function useDirectActiveTurns({
   const [snapshotReadFailed, setSnapshotReadFailed] = useState(false);
   const mountedRef = useRef(true);
   const inFlightRef = useRef<Promise<void> | null>(null);
-  const retryTimerRef = useRef<number | null>(null);
 
   useEffect(() => {
     mountedRef.current = true;
     return () => {
       mountedRef.current = false;
-      if (retryTimerRef.current !== null) {
-        window.clearTimeout(retryTimerRef.current);
-        retryTimerRef.current = null;
-      }
     };
   }, []);
 
@@ -78,12 +73,12 @@ export function useDirectActiveTurns({
           return;
         } catch {
           if (attempt < DIRECT_ACTIVE_TURNS_READ_ATTEMPTS) {
-            await new Promise<void>((resolve) => {
-              retryTimerRef.current = window.setTimeout(() => {
-                retryTimerRef.current = null;
-                resolve();
-              }, DIRECT_ACTIVE_TURNS_READ_RETRY_DELAY_MS * attempt);
-            });
+            await new Promise((resolve) =>
+              window.setTimeout(
+                resolve,
+                DIRECT_ACTIVE_TURNS_READ_RETRY_DELAY_MS * attempt,
+              ),
+            );
           }
         }
       }

apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx

@@ -25,8 +25,10 @@ import {
   type ProjectManifestSnapshotSource,
   rereadAuthoritativeProjectManifestSnapshot,
 } from '../../view/project-development/projectResourceLiveUpdateModel';
+import TemplateLibraryView from '../../view/template-library';
 import { useDirectActiveTurns } from '../agent-runtime/directActiveTurns';
 import { RuntimeConfigDialog } from '../runtime-config/RuntimeConfigDialog';
+import { useTemplateLibrary } from '../template-library/useTemplateLibrary';
 import { AccountWalletBar, AccountWalletDialogs } from './AccountWallet';
 import {
   DeveloperAgentDialogs,
@@ -83,6 +85,11 @@ export function WorkspaceLauncherShell({
     setAgentChatProjectPath: developerAgent.setAgentChatProjectPath,
     rememberRecentWorkspace,
   });
+  const templateLibrary = useTemplateLibrary({
+    onProjectCreated: async (result) => {
+      await homeProject.enterCreatedTemplateProject(result);
+    },
+  });
   const {
     projectPath,
     setProjectPath,
@@ -567,6 +574,13 @@ export function WorkspaceLauncherShell({
               void openProject(path, 'open');
             }}
             onProjectPick={() => void homeProject.pickAndOpenProject()}
+            templateRecommendations={templateLibrary.templates}
+            templateLibraryLoading={
+              templateLibrary.status === 'loading' ||
+              templateLibrary.status === 'idle'
+            }
+            templateLibraryError={templateLibrary.error}
+            onTemplateLibraryOpen={() => setLauncherView('template-library')}
           />
         ) : launcherView === 'projects' ? (
           <ProjectsPage
@@ -574,6 +588,11 @@ export function WorkspaceLauncherShell({
             homeProject={homeProject}
             recentProjects={recentProjects}
           />
+        ) : launcherView === 'template-library' ? (
+          <TemplateLibraryView
+            controller={templateLibrary}
+            onBack={() => setLauncherView('home')}
+          />
         ) : launcherView === 'agent-chat' ? (
           <DeveloperAgentPanel
             controller={developerAgent}

apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts

@@ -555,6 +555,35 @@ export function useHomeProjectCreation({
     }
   }
 
+  /**
+   * 模板库建出的项目：模板文件与项目脚手架已在 Rust 侧一次落盘，
+   * 这里只负责登记最近项目并走标准进项目通道（含会话预览核验与代次闸门）。
+   */
+  async function enterCreatedTemplateProject(result: InitLocalProjectResult) {
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      throw new Error('需要在陶泥儿客户端内运行');
+    }
+    await enterProjectDevelopment({
+      projectPath: result.projectPath,
+      projectName:
+        result.manifest.name || projectNameFromPath(result.projectPath),
+      projectKind: 'web',
+      manifest: result.manifest,
+      projectRevision: await readCurrentProjectRevision(
+        invoke,
+        result.projectPath,
+      ),
+      creationType: null,
+      startMode: null,
+      initialPrompt: '',
+      attachments: [],
+      recentRunStatus: null,
+      recentRunStopReason: null,
+      createdAt: Date.now(),
+    });
+  }
+
   async function openProject(nextProjectPath: string, mode: 'open' | 'create') {
     if (mode === 'create') {
       await createProjectFromProjectPage(nextProjectPath);
@@ -1005,6 +1034,7 @@ export function useHomeProjectCreation({
     renameProject,
     pickAndOpenProject,
     pickAndCreateProject,
+    enterCreatedTemplateProject,
     confirmCreateInNonEmptyFolder,
     cancelCreateInNonEmptyFolder,
   };

apps/ai-game-creator-shell/src/features/template-library/templateLibraryModel.ts

@@ -0,0 +1,208 @@
+/**
+ * AGC 模板库的前端模型：清单类型、搜索与筛选的纯函数。
+ *
+ * 真源在 OSS 清单与 Rust 侧（`fetch_game_template_library`）；这里只做展示层派生，
+ * 不缓存业务真相，也不拼远端地址（URL 由 Rust 侧按受信任 OSS 前缀给出）。
+ */
+
+export type GameTemplateLibrarySource = 'network' | 'cache';
+
+export type GameTemplateEntry = {
+  id: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  runtime: string;
+  engine: string;
+  engineVersion: string;
+  templateVersion: string;
+  updatedAt: string;
+  entry: string;
+  zipUrl: string;
+  zipSizeBytes: number;
+  zipSha256: string;
+  coverUrl: string;
+  coverWidth: number;
+  coverHeight: number;
+  installed: boolean;
+  installedVersion: string | null;
+  installedAtMillis: number | null;
+};
+
+export type GameTemplateLibrarySnapshot = {
+  schemaVersion: string;
+  library: string;
+  libraryVersion: number;
+  updatedAt: string;
+  fetchedAtMillis: number;
+  source: GameTemplateLibrarySource;
+  templates: GameTemplateEntry[];
+};
+
+export type InstalledGameTemplate = {
+  templateId: string;
+  templateVersion: string;
+  installedAtMillis: number;
+  zipSha256: string;
+  fileCount: number;
+  projectDir: string;
+};
+
+export type TemplateLibraryFilters = {
+  query: string;
+  tags: readonly string[];
+  runtime: string;
+  installedOnly: boolean;
+};
+
+export const EMPTY_TEMPLATE_LIBRARY_FILTERS: TemplateLibraryFilters = {
+  query: '',
+  tags: [],
+  runtime: '',
+  installedOnly: false,
+};
+
+const RUNTIME_LABELS: Record<string, string> = {
+  html: '网页',
+  unity: 'Unity',
+  godot: 'Godot',
+  cocos: 'Cocos',
+};
+
+export function templateRuntimeLabel(runtime: string): string {
+  const normalized = runtime.trim().toLowerCase();
+  if (!normalized) return '未标注运行时';
+  return RUNTIME_LABELS[normalized] ?? runtime.trim();
+}
+
+/**
+ * 空白分隔的多个关键词之间是「与」关系：每个词都必须命中标题、简介、标签或引擎，
+ * 这样「三消 像素」不会退化成命中任意一个就出现的宽泛搜索。
+ */
+export function templateMatchesQuery(
+  template: GameTemplateEntry,
+  query: string,
+): boolean {
+  const terms = query
+    .toLowerCase()
+    .split(/\s+/u)
+    .filter((term) => term.length > 0);
+  if (terms.length === 0) {
+    return true;
+  }
+  const haystack = [
+    template.title,
+    template.summary,
+    template.engine,
+    template.runtime,
+    template.tags.join(' '),
+  ]
+    .join(' ')
+    .toLowerCase();
+  return terms.every((term) => haystack.includes(term));
+}
+
+export function filterGameTemplates(
+  templates: readonly GameTemplateEntry[],
+  filters: TemplateLibraryFilters,
+): GameTemplateEntry[] {
+  const selectedTags = filters.tags
+    .map((tag) => tag.trim().toLowerCase())
+    .filter((tag) => tag.length > 0);
+  const runtime = filters.runtime.trim().toLowerCase();
+  return templates.filter((template) => {
+    if (filters.installedOnly && !template.installed) {
+      return false;
+    }
+    if (runtime && template.runtime.trim().toLowerCase() !== runtime) {
+      return false;
+    }
+    if (selectedTags.length > 0) {
+      const templateTags = template.tags.map((tag) => tag.toLowerCase());
+      if (!selectedTags.some((tag) => templateTags.includes(tag))) {
+        return false;
+      }
+    }
+    return templateMatchesQuery(template, filters.query);
+  });
+}
+
+/** 标签按出现次数降序，次数相同按名称排序，保证筛选条顺序稳定。 */
+export function collectGameTemplateTags(
+  templates: readonly GameTemplateEntry[],
+): string[] {
+  const counts = new Map<string, number>();
+  for (const template of templates) {
+    for (const tag of template.tags) {
+      const trimmed = tag.trim();
+      if (!trimmed) continue;
+      counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .sort(
+      ([leftTag, leftCount], [rightTag, rightCount]) =>
+        rightCount - leftCount || leftTag.localeCompare(rightTag, 'zh-CN'),
+    )
+    .map(([tag]) => tag);
+}
+
+export function collectGameTemplateRuntimes(
+  templates: readonly GameTemplateEntry[],
+): string[] {
+  const runtimes = new Set<string>();
+  for (const template of templates) {
+    const runtime = template.runtime.trim().toLowerCase();
+    if (runtime) runtimes.add(runtime);
+  }
+  return [...runtimes].sort((left, right) =>
+    left.localeCompare(right, 'zh-CN'),
+  );
+}
+
+export function formatGameTemplateSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) {
+    return '--';
+  }
+  if (bytes < 1024) {
+    return `${Math.round(bytes)} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function isTemplateLibraryFiltersEmpty(
+  filters: TemplateLibraryFilters,
+): boolean {
+  return (
+    !filters.query.trim() &&
+    filters.tags.length === 0 &&
+    !filters.runtime.trim() &&
+    !filters.installedOnly
+  );
+}
+
+export function toggleGameTemplateTag(
+  filters: TemplateLibraryFilters,
+  tag: string,
+): TemplateLibraryFilters {
+  const exists = filters.tags.includes(tag);
+  return {
+    ...filters,
+    tags: exists
+      ? filters.tags.filter((value) => value !== tag)
+      : [...filters.tags, tag],
+  };
+}
+
+/**
+ * 已安装版本低于清单版本时必须重新下载；已安装且版本一致才算可直接使用。
+ */
+export function needsTemplateDownload(template: GameTemplateEntry): boolean {
+  return (
+    !template.installed ||
+    template.installedVersion !== template.templateVersion
+  );
+}

apps/ai-game-creator-shell/src/features/template-library/useTemplateLibrary.ts

@@ -0,0 +1,243 @@
+/**
+ * 模板库状态链路：拉取清单、下载模板、用模板建项目。
+ *
+ * 远端真相全在 Rust 侧命令里（受信任 OSS 前缀 + 摘要校验 + 本机安装记录）；
+ * 这里只维护界面状态，并在下载成功后把对应条目的安装状态就地更新，
+ * 避免为了一个"已下载"徽标再打一次清单请求。
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { resolveTauriInvoke } from '../../app/tauri';
+import type { InitLocalProjectResult } from '../../app/types';
+import {
+  collectGameTemplateRuntimes,
+  collectGameTemplateTags,
+  EMPTY_TEMPLATE_LIBRARY_FILTERS,
+  filterGameTemplates,
+  type GameTemplateEntry,
+  type GameTemplateLibrarySnapshot,
+  type InstalledGameTemplate,
+  isTemplateLibraryFiltersEmpty,
+  needsTemplateDownload,
+  type TemplateLibraryFilters,
+  toggleGameTemplateTag,
+} from './templateLibraryModel';
+
+export type TemplateLibraryStatus = 'idle' | 'loading' | 'ready' | 'error';
+export type TemplateLibraryBusyKind = 'download' | 'create';
+
+type UseTemplateLibraryOptions = {
+  /** 项目已建好：由调用方负责进入项目工作区（模板库不碰工作区状态）。 */
+  onProjectCreated: (result: InitLocalProjectResult) => Promise<void> | void;
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function useTemplateLibrary({
+  onProjectCreated,
+}: UseTemplateLibraryOptions) {
+  const [snapshot, setSnapshot] = useState<GameTemplateLibrarySnapshot | null>(
+    null,
+  );
+  const [status, setStatus] = useState<TemplateLibraryStatus>('idle');
+  const [error, setError] = useState('');
+  const [notice, setNotice] = useState('');
+  const [filters, setFilters] = useState<TemplateLibraryFilters>(
+    EMPTY_TEMPLATE_LIBRARY_FILTERS,
+  );
+  const [busyTemplateId, setBusyTemplateId] = useState<string | null>(null);
+  const [busyKind, setBusyKind] = useState<TemplateLibraryBusyKind | null>(
+    null,
+  );
+  const loadingRef = useRef(false);
+
+  const refresh = useCallback(async () => {
+    if (loadingRef.current) {
+      return;
+    }
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      setStatus('error');
+      setError('需要在陶泥儿客户端内运行');
+      return;
+    }
+    loadingRef.current = true;
+    setStatus('loading');
+    setError('');
+    try {
+      const next = await invoke<GameTemplateLibrarySnapshot>(
+        'fetch_game_template_library',
+      );
+      setSnapshot(next);
+      setStatus('ready');
+      setNotice(
+        next.source === 'cache' ? '远端清单暂时读不到，当前展示本机缓存' : '',
+      );
+    } catch (nextError) {
+      setStatus('error');
+      setError(errorMessage(nextError));
+    } finally {
+      loadingRef.current = false;
+    }
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const downloadTemplate = useCallback(async (template: GameTemplateEntry) => {
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      throw new Error('需要在陶泥儿客户端内运行');
+    }
+    setBusyTemplateId(template.id);
+    setBusyKind('download');
+    setError('');
+    try {
+      const installed = await invoke<InstalledGameTemplate>(
+        'download_game_template',
+        {
+          templateId: template.id,
+          templateVersion: template.templateVersion,
+        },
+      );
+      setSnapshot((current) =>
+        current
+          ? {
+              ...current,
+              templates: current.templates.map((entry) =>
+                entry.id === template.id
+                  ? {
+                      ...entry,
+                      installed: true,
+                      installedVersion: installed.templateVersion,
+                      installedAtMillis: installed.installedAtMillis,
+                    }
+                  : entry,
+              ),
+            }
+          : current,
+      );
+      setNotice(`已下载模板「${template.title}」`);
+      return installed;
+    } catch (nextError) {
+      setError(errorMessage(nextError));
+      throw nextError;
+    } finally {
+      setBusyTemplateId(null);
+      setBusyKind(null);
+    }
+  }, []);
+
+  const createProjectFromTemplate = useCallback(
+    async (template: GameTemplateEntry) => {
+      const invoke = resolveTauriInvoke();
+      if (!invoke) {
+        throw new Error('需要在陶泥儿客户端内运行');
+      }
+      try {
+        if (needsTemplateDownload(template)) {
+          await downloadTemplate(template);
+        }
+        setBusyTemplateId(template.id);
+        setBusyKind('create');
+        setError('');
+        setNotice(`正在用模板「${template.title}」创建项目`);
+        const result = await invoke<InitLocalProjectResult>(
+          'create_automatic_local_game_project_from_template',
+          {
+            templateId: template.id,
+            templateVersion: template.templateVersion,
+            name: null,
+            planning: false,
+          },
+        );
+        await onProjectCreated(result);
+        setNotice(`已用模板「${template.title}」创建项目`);
+        return result;
+      } catch (nextError) {
+        setError(errorMessage(nextError));
+        throw nextError;
+      } finally {
+        setBusyTemplateId(null);
+        setBusyKind(null);
+      }
+    },
+    [downloadTemplate, onProjectCreated],
+  );
+
+  const templates = useMemo(
+    () => snapshot?.templates ?? [],
+    [snapshot?.templates],
+  );
+  const visibleTemplates = useMemo(
+    () => filterGameTemplates(templates, filters),
+    [templates, filters],
+  );
+  const tagOptions = useMemo(
+    () => collectGameTemplateTags(templates),
+    [templates],
+  );
+  const runtimeOptions = useMemo(
+    () => collectGameTemplateRuntimes(templates),
+    [templates],
+  );
+  const installedCount = useMemo(
+    () => templates.filter((template) => template.installed).length,
+    [templates],
+  );
+  const filtersActive = !isTemplateLibraryFiltersEmpty(filters);
+
+  const setQuery = useCallback((query: string) => {
+    setFilters((current) => ({ ...current, query }));
+  }, []);
+
+  const selectRuntime = useCallback((runtime: string) => {
+    setFilters((current) => ({
+      ...current,
+      runtime: current.runtime === runtime ? '' : runtime,
+    }));
+  }, []);
+
+  const toggleTag = useCallback((tag: string) => {
+    setFilters((current) => toggleGameTemplateTag(current, tag));
+  }, []);
+
+  const setInstalledOnly = useCallback((installedOnly: boolean) => {
+    setFilters((current) => ({ ...current, installedOnly }));
+  }, []);
+
+  const clearFilters = useCallback(() => {
+    setFilters(EMPTY_TEMPLATE_LIBRARY_FILTERS);
+  }, []);
+
+  return {
+    snapshot,
+    status,
+    error,
+    notice,
+    templates,
+    visibleTemplates,
+    tagOptions,
+    runtimeOptions,
+    installedCount,
+    filters,
+    filtersActive,
+    setQuery,
+    selectRuntime,
+    toggleTag,
+    setInstalledOnly,
+    clearFilters,
+    busyTemplateId,
+    busyKind,
+    refresh,
+    downloadTemplate,
+    createProjectFromTemplate,
+    clearNotice: useCallback(() => setNotice(''), []),
+  };
+}
+
+export type TemplateLibraryController = ReturnType<typeof useTemplateLibrary>;

apps/ai-game-creator-shell/src/view/home/InspirationGallery.tsx

@@ -1,81 +0,0 @@
-import { useEffect, useState } from 'react';
-import { createPortal } from 'react-dom';
-
-// TODO: 后续改为由服务器下发灵感资源；届时保留此组件的展示与预览交互，移除本地目录扫描。
-const INSPIRATION_IMAGES = Object.entries(
-  import.meta.glob('./assets/inspiration/*.{webp,png,jpg,jpeg}', {
-    eager: true,
-    import: 'default',
-    query: '?url',
-  }),
-)
-  .sort(([left], [right]) =>
-    left.localeCompare(right, undefined, { numeric: true }),
-  )
-  .map(([, image]) => image as string);
-
-export default function InspirationGallery() {
-  const [selectedImage, setSelectedImage] = useState<string | null>(null);
-
-  useEffect(() => {
-    if (!selectedImage) {
-      return;
-    }
-    const previousOverflow = document.body.style.overflow;
-    document.body.style.overflow = 'hidden';
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        setSelectedImage(null);
-      }
-    };
-    window.addEventListener('keydown', handleKeyDown);
-    return () => {
-      document.body.style.overflow = previousOverflow;
-      window.removeEventListener('keydown', handleKeyDown);
-    };
-  }, [selectedImage]);
-
-  return (
-    <>
-      <div className="columns-3 gap-3 max-[760px]:columns-2 max-[460px]:columns-1">
-        {INSPIRATION_IMAGES.map((image, index) => (
-          <button
-            className="mb-3 block w-full cursor-zoom-in break-inside-avoid overflow-hidden rounded-lg border-0 bg-transparent p-0 shadow-(--platform-panel-shadow) transition duration-200 hover:-translate-y-0.5 hover:shadow-(--platform-profile-action-shadow) focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--platform-warm-text)"
-            type="button"
-            key={image}
-            aria-label={`查看灵感图片 ${index + 1}`}
-            onClick={() => setSelectedImage(image)}
-          >
-            <img
-              className="block h-auto w-full"
-              src={image}
-              alt=""
-              loading="lazy"
-              decoding="async"
-            />
-          </button>
-        ))}
-      </div>
-
-      {selectedImage
-        ? createPortal(
-            <div
-              className="fixed inset-0 z-[1000] grid cursor-zoom-out place-items-center bg-black/80 p-6"
-              role="dialog"
-              aria-modal="true"
-              aria-label="查看灵感图片"
-              onClick={() => setSelectedImage(null)}
-            >
-              <img
-                className="block max-h-[92vh] max-w-[92vw] cursor-default object-contain shadow-2xl"
-                src={selectedImage}
-                alt="放大的灵感图片"
-                onClick={(event) => event.stopPropagation()}
-              />
-            </div>,
-            document.body,
-          )
-        : null}
-    </>
-  );
-}

apps/ai-game-creator-shell/src/view/home/TemplateRecommendations.tsx

@@ -0,0 +1,96 @@
+import { BadgeCheck, Loader2, Package } from 'lucide-react';
+
+import type { GameTemplateEntry } from '../../features/template-library/templateLibraryModel';
+import { templateRuntimeLabel } from '../../features/template-library/templateLibraryModel';
+
+type TemplateRecommendationsProps = {
+  templates: readonly GameTemplateEntry[];
+  loading: boolean;
+  error: string;
+  onOpenLibrary: () => void;
+};
+
+const RECOMMENDATION_LIMIT = 6;
+
+/**
+ * 首页模板推荐：只做展示与跳转，下载与建项目都在模板库页面里完成，
+ * 避免首页的卡片点击直接产生项目副作用。
+ */
+export default function TemplateRecommendations({
+  templates,
+  loading,
+  error,
+  onOpenLibrary,
+}: TemplateRecommendationsProps) {
+  if (loading && templates.length === 0) {
+    return (
+      <div className="flex items-center gap-2 py-6 text-[12px] text-(--platform-text-soft)">
+        <Loader2 className="animate-spin" size={14} aria-hidden="true" />
+        正在读取模板库…
+      </div>
+    );
+  }
+
+  if (templates.length === 0) {
+    return (
+      <div className="grid justify-items-center gap-2 py-6">
+        <Package
+          className="text-(--platform-icon-text)"
+          size={22}
+          aria-hidden="true"
+        />
+        <span className="text-[12px] text-(--platform-text-soft)">
+          {error || '模板库暂时没有可用的模板'}
+        </span>
+        <button
+          className="cursor-pointer border-0 bg-transparent p-0 text-[12px] text-(--platform-warm-text)"
+          type="button"
+          onClick={onOpenLibrary}
+        >
+          打开模板库
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="grid grid-cols-3 gap-3 max-[760px]:grid-cols-2 max-[460px]:grid-cols-1">
+      {templates.slice(0, RECOMMENDATION_LIMIT).map((template) => (
+        <button
+          className="grid cursor-pointer content-start overflow-hidden rounded-lg border border-(--platform-subpanel-border) bg-transparent p-0 text-left shadow-(--platform-panel-shadow) transition duration-200 hover:-translate-y-0.5 hover:shadow-(--platform-profile-action-shadow) focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--platform-warm-text)"
+          type="button"
+          key={template.id}
+          aria-label={`查看模板 ${template.title}`}
+          data-template-id={template.id}
+          onClick={onOpenLibrary}
+        >
+          <span className="relative block aspect-video w-full overflow-hidden bg-black/20">
+            <img
+              className="block h-full w-full object-cover"
+              src={template.coverUrl}
+              alt=""
+              loading="lazy"
+              decoding="async"
+            />
+            {template.installed ? (
+              <span className="absolute right-2 top-2 inline-flex items-center gap-1 rounded-full bg-black/60 px-2 py-0.5 text-[10px] text-white">
+                <BadgeCheck size={11} aria-hidden="true" />
+                已下载
+              </span>
+            ) : null}
+          </span>
+          <span className="grid gap-1 p-2.5">
+            <strong className="truncate text-[12px] text-(--platform-text-strong)">
+              {template.title}
+            </strong>
+            <span className="truncate text-[10px] text-(--platform-text-soft)">
+              {[templateRuntimeLabel(template.runtime), template.engine]
+                .filter((value) => value.trim())
+                .join(' · ')}
+            </span>
+          </span>
+        </button>
+      ))}
+    </div>
+  );
+}