Merge remote-tracking branch 'origin/master' into codex/fix-design-panic-boundary

2026-09-17 09:53:18 +00:00
parent 958078def8 5db407c3dc
commit 1a88ae3ffa
92 changed files with 6110 additions and 203 deletions
@@ -0,0 +1,136 @@
+# 【技术方案】AGC 模板库与模板建项
+
+## 交付范围
+
+AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，正文是 zip），并让用户能浏览、搜索、筛选、下载模板，直接由模板创建项目。模板更新不再依赖客户端发版。
+
+- OSS 侧：bucket `agc-dev`（endpoint `oss-rg-china-mainland.aliyuncs.com`）下的 `templates/` 前缀，公共读。
+- 客户端侧：Rust `template_library` 模块（读清单、下载、安装、建项目）+ 模板库全屏页 + 首页模板推荐 + 左侧导航入口。
+- 不在本次范围：模板制作工具、模板审核、模板计费、增量更新、已建项目的模板回填。
+
+## OSS 契约
+
+```text
+templates/
+  index.json                       # 模板库清单，客户端唯一读取入口
+  v1/<templateId>/
+    template.json                  # 单模板元数据（含文件级摘要）
+    template.zip                   # 模板正文，zip 根 == AGC 项目根（如 game/index.html）
+    cover.(png|jpg|webp|svg)       # 封面图（卡片展示，客户端 <img> 直接取）
+```
+
+`index.json`（schema `agc-template-library.v1`）：
+
+| 字段 | 说明 |
+| --- | --- |
+| `schemaVersion` | 固定 `agc-template-library.v1`；破坏性变更换 schema，不原地改语义 |
+| `library` / `libraryVersion` / `updatedAt` | 库标识、库格式版本、本次更新时间 |
+| `templates[].id` | 稳定标识，`[a-z0-9][a-z0-9._-]{0,63}`，同时是目录名 |
+| `templates[].title/summary/tags[]` | 展示与搜索/筛选用文案；`tags` 参与标签筛选与关键词命中 |
+| `templates[].runtime` | `html` / `unity` / `godot` / `cocos` |
+| `templates[].engine` / `engineVersion` | 引擎标识与版本（如 `phaser` 4.2.1、`three.js` 0.180.0） |
+| `templates[].templateVersion` / `updatedAt` | 模板内容版本；客户端按它判断是否需要重新下载 |
+| `templates[].entry` | 解压后的项目入口相对路径，如 `game/index.html` |
+| `templates[].zipKey` / `zipSizeBytes` / `zipSha256` | 模板包对象键、字节数、SHA-256（下载后强校验） |
+| `templates[].coverKey` / `coverWidth` / `coverHeight` / `coverSha256` | 封面对象键与尺寸/摘要 |
+| `templates[].metadataKey` | 单模板元数据对象键（`template.json`） |
+
+约束：
+
+- 所有对象键必须落在 `templates/` 前缀内；客户端只用「受信任 OSS 主机 + 对象键」自行拼 URL，**不直接信任清单里的地址**。
+- 任何一项校验失败（schema、标识符、sha256、尺寸、键前缀）都让整次清单读取失败，前端拿到的是全有或全无的清单。
+- 模板源在仓库 `apps/ai-game-creator-shell/template-library/`：`v1/<id>/{meta.json, project/**, cover.(png|jpg|webp|svg)}`，`template.zip` **不落仓库**，由脚本按 `project/` 现场打包（条目排序、固定时间戳，同内容重复打包摘要一致）。
+- 上传与校验由 [`scripts/agc-template-library-publish.mjs`](../../scripts/agc-template-library-publish.mjs) 完成：`--source apps/ai-game-creator-shell/template-library [--dry-run] [--prune]`，脚本生成 `template.json` 与 `index.json`、上传后回读 zip 摘要；`--prune` 清理该模板前缀下本次没有产出的旧对象（例如换封面扩展名后的残留）。
+- 当前模板：`blank-web`（空白网页）、`blank-2d-canvas`（空白二维画布）、`blank-3d-scene`（空白三维场景）、`phaser-2d-starter`（Phaser 2D 起步工程）、`threejs-3d-starter`（Three.js 3D 起步工程）。
+- 客户端可用 `AGC_TEMPLATE_LIBRARY_BASE_URL` 覆盖库地址；只接受 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com`（拒绝其他主机、路径、http）。
+
+## 客户端实现
+
+### Rust：`apps/ai-game-creator-shell/src-tauri/src/template_library.rs`
+
+| 命令 | 行为 |
+| --- | --- |
+| `fetch_game_template_library` | 读 `templates/index.json`（≤4 MiB），校验后缓存到 `<app_data>/templates/index.json`；网络失败时回退本机缓存并在 `source` 标 `cache` |
+| `download_game_template` | 取清单里对应条目，流式下载 zip（≤512 MiB），校验字节数与 SHA-256，解压到 `<app_data>/templates/installed/<id>/<version>/`，最后写 `installed.json` 作为安装完成的唯一标记 |
+| `create_automatic_local_game_project_from_template` | 需要时先安装模板，然后在 `<app_data>/projects/` 下按既有自动工作区规则建目录：先复制模板文件，再走 `init_local_game_project_at` 补 `.agent` 清单与标准目录 |
+
+安全与健壮性：
+
+- 解压只接受普通文件与目录：拒绝绝对路径、`..`、盘符、反斜杠、符号链接，并有文件数（4096）与单文件大小（256 MiB）上限。
+- 安装目录名由标识符白名单拼出，不拼接远端字符串；重装时只清理该模板自己的安装目录。
+- 模板文件与安装记录统一走 `write_game_creator_private_file` / `ensure_game_creator_private_directory_tree`，保持项目目录的私有 DACL 口径。
+- 建项目失败时删除刚创建的项目目录，不留半成品。
+
+### 前端
+
+- `src/features/template-library/templateLibraryModel.ts`：清单类型、搜索（空白分隔多关键词「与」）、标签/运行时/已下载筛选、标签选项聚合、体积格式化等纯函数。
+- `src/features/template-library/useTemplateLibrary.ts`：一次拉清单，暴露筛选状态、下载与「用模板建项目」；下载成功后只就地更新该条目的已下载状态。
+- `src/view/template-library/index.tsx`：模板库全屏页（返回、刷新、搜索、运行时/标签筛选、仅看已下载、卡片显示封面与已下载徽标、下载/使用模板）。
+  - 卡片动作按安装状态收口：已下载且版本一致时**不再显示下载入口**，只留「使用模板」；版本落后才显示「更新」；缺包显示「下载」。
+  - 过程提示（下载完成、开始建项目）走浮层 toast（复用 `packages/shared` 的 `PlatformRuntimeStatusToast`，`document.body` 浮层 + 2.6 秒自动消失），不再占用页面内位置；页面内只保留可操作的错误与空态。
+- 首页「灵感推荐」替换为「模板库」推荐位（`src/view/home/TemplateRecommendations.tsx`）：只展示封面、标题、运行时与已下载徽标，点击进入模板库页面；首页不再直接触发建项目。
+- 左侧导航新增模板库入口（`LauncherView = 'template-library'`）。
+- `src-tauri/tauri.conf.json` 的 `csp` / `devCsp` 在 `img-src` 放行 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com`，用于封面图；`connect-src` 原本已放行同一域名。
+- 旧的本机灵感图目录 `src/view/home/assets/inspiration/` 与 `InspirationGallery.tsx` 一并删除，不再保留退役实现。
+
+## 验收与验证
+
+## 本地压测假数据注入（feature 控制）
+
+模板库的数据源在 Rust 侧（清单校验、安装状态、下载与建项目都在这里），TS 只消费快照做渲染，所以假数据注入也放在 Rust 侧，走与真实完全一致的链路。
+
+- 开关：Cargo feature `template-library-fixtures`（**默认关闭**）。关闭时 `apply_template_library_fixtures` 是恒等透传，正式产物里不存在注入分支，并有单测保证这一点。
+- 条数：环境变量 `AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT`（默认 1000；`0` 表示不注入；上限 20000）。
+- 假数据特征：真实条目保留在最前，其余按真实条目循环复制；`id`/标题唯一，封面地址追加 `?synthetic=N`（强制逐张请求，模拟“每个模板各自封面”）；标签追加 `批次-00..19`；安装态按 1/3 混合。
+- 运行方式：
+
+```bash
+# 本机 dev 客户端（保留 Windows 默认 feature）
+AGC_DEV_CARGO_FEATURES=cocos-editor-execute,template-library-fixtures npm run dev
+# 直接跑二进制
+cargo run --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --features template-library-fixtures
+# 覆盖条数
+AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT=300 AGC_DEV_CARGO_FEATURES=template-library-fixtures npm run dev
+```
+
+两种编译模式都要过模板库单测：默认构建跑「恒等透传」用例，`--features template-library-fixtures` 跑「补齐到配置条数」用例。
+
+### 1000 条实测结论
+
+### 卡片列表虚拟滚动（react-window）
+
+- 列表改用 workspace 里已有的 `react-window@1.8.11` 的 `FixedSizeGrid`（`react-arborist` 已在用同一版本，不引入新包；类型来自 devDependency `@types/react-window`）。
+- 布局契约收在纯函数 `templateLibraryGrid.ts`（单测覆盖）：列数 = `floor((容器宽 + gap) / (最小卡宽 + gap))`、列宽 = 容器宽 / 列数、行高 = `卡片宽 × 9/16 + 文字区 150 + gap`；`buildTemplateRows` 按行切分并在行尾补 `null` 占位。
+- 卡片抽成 `TemplateCard`（`memo`），网格只渲染可视行 + 2 行 overscan；筛选条件（关键词/标签/运行时/仅看已下载）变化时把滚动位置复位到顶部，避免"从筛选切回全量后停在空白处"。
+- **页面高度契约**：页面根节点的高度按**父级 `.launcher-main` 的实测高度**内联设置，既不用百分比也不用 `100vh`。原因：外壳样式 `.launcher-main > .platform-theme { height: 100% }` 特异性高于 Tailwind 工具类，而这条百分比在 `.launcher-shell { min-height: 100vh }` 链路上是不定高，页面会退化成内容高度（虚拟网格视口高度 0、卡片区整片空白）；`100vh` 又比真实舞台高一个标题栏高度（窗口 100vh=800 / 舞台 750），底部会被裁掉。
+- 筛选区（运行时/标签）改成可独立滚动的区块（`max-h-[24vh]`），标签数量随库量增长时不再把卡片区挤出窗口。
+- 回归：`templateLibraryGrid.test.ts` 覆盖列数/行高/行数/切行；页面测试用固定视口断言「1000 条只渲染 ≤ 40 张卡片，滚动高度仍按 250 行计算」。
+
+- 页面能正常渲染 1000 张卡片（头部显示「共 1000 个模板 · 已下载 335 个」），并且滚动容器生效（窗口高度压到 430px 时右侧出现滚动条，页面内容被裁切而不是溢出到窗口外）。
+- 需要后续收口的两点（本次未改）：① 标签筛选条随库量膨胀——1000 条时聚合出 35 个标签、占三行；② 一次性渲染 1000 个卡片节点并触发 1000 次封面请求。建议标签只展示 Top N + 「更多」，卡片列表加分页或虚拟滚动。
+- 前端回归：1000 条渲染 + 已安装过滤（334）/标签过滤（50）/关键词过滤数量自洽，见 `apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx`。
+
+```bash
+# 模板库单测（清单校验、键安全、解压路径逃逸、安装与建项目）
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell template_library
+# 模板库真连检查（可选，需要网络）：读线上清单、下载安装线上模板包并据此建项目
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell template_library -- --ignored
+# 前端模型与页面单测（AGC 测试统一在 apps/ai-game-creator-shell/tests/）
+npx vitest run apps/ai-game-creator-shell/tests/templateLibraryModel.test.ts apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx
+# 类型检查 / 编码 / 空白
+cd apps/ai-game-creator-shell && npm run typecheck
+npm run check:encoding
+git diff --check
+# OSS 侧匿名可读
+curl -s https://agc-dev.oss-rg-china-mainland.aliyuncs.com/templates/index.json
+```
+
+手工验收：打开模板库 → 搜索与筛选 → 下载（出现「已下载」徽标）→ 「使用模板」→ 进入项目工作台且项目里已有模板文件。
+
+运行态核验（客户端真的拉过清单时）：本机缓存 `<app_data>/templates/index.json` 与线上 `templates/index.json` 逐字节一致；`<app_data>/templates/installed/<id>/<version>/installed.json` 出现即表示该模板已下载完成。
+
+## 失败与回退
+
+- 清单读不到且没有本机缓存：模板库页显示错误与重试，首页推荐位显示「模板库暂时没有可用的模板」。
+- 版本落后：`installedVersion != templateVersion` 视为需要重新下载，点「使用模板」会先重下再建项目。
+- 需要回退整条链路时，删除 `templates/` 前缀即可让客户端回到"空模板库"；客户端代码路径不受影响。