新增 AGC 模板库与由模板创建项目链路 #396

Merged

kdletters merged 10 commits from codex/agc-template-library into master 2026-09-17 17:48:06 +08:00

Conversation 2 Commits 10 Files Changed 92

+6110 -203

kdletters commented 2026-09-17 11:21:50 +08:00

Member

Copy Link

Copy Source

交付范围

• OSS agc-dev bucket 的 templates/ 前缀作为 AGC 游戏模板库（去掉 agc/ 这一层；agc/ 继续只放客户端安装包与更新清单）。
• 模板正文改为 zip（zip 根 == AGC 项目根，如 game/index.html）；清单补齐 tags、封面字段与包大小/摘要，templateVersion 用于判断是否需要重下。
• 客户端：Rust 模板库模块、模板库全屏页、首页模板推荐位、左侧导航入口。

客户端行为

• fetch_game_template_library：读取并校验清单（≤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：先把模板文件铺进新项目目录，再走既有 init_local_game_project_at 补 .agent 清单与标准目录；失败删除半成品目录。
• 解压只接受普通文件与目录（拒绝绝对路径、..、盘符、符号链接），安装目录名由标识符白名单拼出；远端只信「受信任 OSS 主机 + 对象键」，清单里的地址字段不参与请求。
• UI：搜索（空白分隔多关键词「与」）、标签/运行时筛选、仅看已下载、封面卡片与已下载徽标；「使用模板」在版本落后时先重下再建项。

文档与脚本

• 主规范 docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md；里程碑与实施计划见 docs/project-memory/plans/；decision-log.md 记录库路径、清单 schema、安装缓存目录与 CSP 约定。
• 发布脚本 scripts/agc-template-library-publish.mjs（--dry-run 校验 → 上传 → 回读校验）。
• 首页「灵感推荐」替换为模板库推荐位，删除本机灵感图目录与 InspirationGallery.tsx；tauri.conf.json 的 img-src 放行受信任 OSS 主机用于加载封面。

验证

• cargo test --bin genarrative-ai-game-creator-shell template_library：9 passed；--ignored 真连检查 fetches_the_live_template_library_index 通过。
• npx vitest run src/features/template-library：9 passed。
• npm run typecheck、cargo fmt --check、npm run check:encoding、node scripts/check-doc-index.mjs、git diff --check 均通过。
• OSS 侧匿名复核：templates/index.json、各 cover.png 与 template.zip 均返回 200。

未做 / 待确认

• 本轮未做客户端点击级人工验收（下一步单独验证并把结果补进此 PR）。
• 模板封面目前是占位标题卡，正式封面由后续模板包提供。

## 交付范围 - OSS `agc-dev` bucket 的 `templates/` 前缀作为 AGC 游戏模板库（**去掉 `agc/` 这一层**；`agc/` 继续只放客户端安装包与更新清单）。 - 模板正文改为 zip（zip 根 == AGC 项目根，如 `game/index.html`）；清单补齐 `tags`、封面字段与包大小/摘要，`templateVersion` 用于判断是否需要重下。 - 客户端：Rust 模板库模块、模板库全屏页、首页模板推荐位、左侧导航入口。 ## 客户端行为 - `fetch_game_template_library`：读取并校验清单（≤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`：先把模板文件铺进新项目目录，再走既有 `init_local_game_project_at` 补 `.agent` 清单与标准目录；失败删除半成品目录。 - 解压只接受普通文件与目录（拒绝绝对路径、`..`、盘符、符号链接），安装目录名由标识符白名单拼出；远端只信「受信任 OSS 主机 + 对象键」，清单里的地址字段不参与请求。 - UI：搜索（空白分隔多关键词「与」）、标签/运行时筛选、仅看已下载、封面卡片与已下载徽标；「使用模板」在版本落后时先重下再建项。 ## 文档与脚本 - 主规范 `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`；里程碑与实施计划见 `docs/project-memory/plans/`；`decision-log.md` 记录库路径、清单 schema、安装缓存目录与 CSP 约定。 - 发布脚本 `scripts/agc-template-library-publish.mjs`（`--dry-run` 校验 → 上传 → 回读校验）。 - 首页「灵感推荐」替换为模板库推荐位，删除本机灵感图目录与 `InspirationGallery.tsx`；`tauri.conf.json` 的 `img-src` 放行受信任 OSS 主机用于加载封面。 ## 验证 - `cargo test --bin genarrative-ai-game-creator-shell template_library`：9 passed；`--ignored` 真连检查 `fetches_the_live_template_library_index` 通过。 - `npx vitest run src/features/template-library`：9 passed。 - `npm run typecheck`、`cargo fmt --check`、`npm run check:encoding`、`node scripts/check-doc-index.mjs`、`git diff --check` 均通过。 - OSS 侧匿名复核：`templates/index.json`、各 `cover.png` 与 `template.zip` 均返回 200。 ## 未做 / 待确认 - 本轮未做客户端点击级人工验收（下一步单独验证并把结果补进此 PR）。 - 模板封面目前是占位标题卡，正式封面由后续模板包提供。

kdletters added 1 commit 2026-09-17 11:21:50 +08:00

新增 AGC 模板库与由模板创建项目链路 ... 8ee50e8b94

- 新增 Rust 模板库模块 template_library.rs：读取 OSS 清单、校验并安装模板包、由模板创建项目
- 注册 fetch_game_template_library、download_game_template、create_automatic_local_game_project_from_template 命令
- 新增前端模板库模型与状态链路：搜索、标签/运行时/已下载筛选、下载与建项
- 新增模板库全屏页，并在左侧导航增加模板库入口
- 首页「灵感推荐」替换为模板库推荐位，删除本机灵感图目录与 InspirationGallery 组件
- tauri.conf.json 的 img-src 放行受信任 OSS 主机，用于加载模板封面
- 新增模板库发布脚本 scripts/agc-template-library-publish.mjs
- 新增模板库技术方案、里程碑与实施计划文档，并更新 docs/README.md 索引
- decision-log 记录模板库 OSS 路径、清单 schema、安装缓存目录与 CSP 约定

kdletters added 1 commit 2026-09-17 11:25:24 +08:00

补齐模板库模板源、空白模板与确定性打包 ... 7eaaa1a499

- 新增仓库模板源 apps/ai-game-creator-shell/template-library/：空白网页、空白二维画布、空白三维场景三个空白模板，以及 Phaser 2D、Three.js 3D 两个起步工程模板
- 发布脚本改为按 project/ 现场打包确定性 zip（条目排序 + 固定时间戳），支持 svg 封面、--prune 清理旧对象与 --index-out
- 模板库新增真连检查：读取线上清单、下载并安装线上模板包后校验文件落盘
- 刷新线上清单 fixture，并同步技术方案与实施计划的封面格式、模板源与发布方式

kdletters added 1 commit 2026-09-17 11:37:49 +08:00

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

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

kdletters added 1 commit 2026-09-17 14:43:59 +08:00

模板库卡片按安装状态收口并改用浮层提示 ... ff542085e1

- 已下载且版本一致的模板不再显示下载入口，只保留「使用模板」；版本落后显示「更新」，缺包显示「下载」
- 下载完成、开始建项目等过程提示改为浮层 toast（复用 PlatformRuntimeStatusToast，2.6 秒自动消失），不再占用页面内位置；页面内只保留错误与空态
- 补充/更新页面单测：已下载无下载按钮、落后显示更新、toast 渲染在页面外并自动消失
- 同步技术方案与里程碑的交互口径

kdletters added 1 commit 2026-09-17 14:53:07 +08:00

修复模板库页无法上下滚动 ... a9d5ac0931

- 模板库页面根节点补 platform-theme / platform-theme--light 与 h-full + overflow-y-auto：shell 只给 .launcher-main 下带 platform-theme 的直接子元素 height:100% + overflow:auto，缺这个类时整页没有滚动容器，模板一多就滚不动
- 补回归单测：页面根节点必须同时具备 platform-theme 与 overflow-y-auto

kdletters added 1 commit 2026-09-17 15:09:25 +08:00

模板库假数据注入改为 Cargo feature 控制 ... 19e9dea45c

- 新增 feature template-library-fixtures（默认关闭）：关闭时 apply_template_library_fixtures 为恒等透传，正式产物不含注入分支
- 注入实现下沉为 cfg 模块：按真实清单循环补齐假数据（唯一 id/标题/封面地址，标签追加批次分组，安装态 1/3 混合），条数由 AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT 控制（默认 1000）
- 两种编译模式各补一条用例：默认构建必须恒等透传，开启 feature 必须补齐到配置条数；另补假数据识别/计数解析单测
- 前端补 1000 条渲染回归：1000 张卡片渲染 + 已安装/标签/关键词过滤数量自洽
- 技术方案补「本地压测假数据注入」与 1000 条实测结论（标签条膨胀、一次性渲染 1000 卡片与封面请求需后续收口）

kdletters added 1 commit 2026-09-17 16:36:37 +08:00

模板库卡片列表接入虚拟滚动 ... 066d0fe6f9

- 用 workspace 已有的 react-window@1.8.11 的 FixedSizeGrid：只渲染可视行 + 2 行 overscan，1000 条不再一次性挂 1000 个卡片节点
- 新增 templateLibraryGrid.ts 纯函数布局契约（列数/列宽/行高/行数/按行切分），单测覆盖
- 卡片抽成 memo 化的 TemplateCard；筛选条件变化时把滚动位置复位到顶部
- 筛选区（运行时/标签）改为可独立滚动区块，标签膨胀不再挤压卡片区
- 页面回归改用固定视口：断言 1000 条只渲染 ≤40 张卡、滚动高度按 250 行计算
- 技术方案补虚拟滚动契约说明

kdletters commented 2026-09-17 16:36:49 +08:00

Author

Member

Copy Link

Copy Source

补充一条与本 PR 无关、但影响更大的现场发现（本地 dev 客户端实测）：

WebView2 渲染进程存在无限渲染循环，日志持续刷：

WEBVIEW error webview: Maximum update depth exceeded. This can happen when a component calls setState inside useEffect, but useEffect either doesn't have a dependency array, or one of its dependencies changes on every render.

对照实验（同一台机器、同一份 %APPDATA%\world.genarrative.ai-game-creator）：

场景	渲染进程工作集/私有	CPU 累计	3.5 分钟内 Maximum update depth 条数
开 template-library-fixtures（1000 条假数据，未打开模板库页，停在首页）	4.4 GB / 4.8 GB	219.8s	持续刷屏（日志 5 秒 +8.5 KB）
关 fixture（5 个真模板，从未打开模板库页）	4.2 GB / 4.6 GB	186.1s	468 条

结论：渲染进程 4 GB+ 内存与持续吃 CPU 不是模板库卡片数量造成的（对照场景连模板库页都没打开），而是应用层既有的 setState 循环。它也是"拖动进度条不流畅 / 筛选切回全量卡一下"的主要背景噪声——虚拟列表解决的是 1000 个卡片节点这条真实性能债，但要判定交互流畅度是否达标，需要先修掉这个循环再复测。

复现：AGC_DEV_CARGO_FEATURES=cocos-editor-execute npm run dev（无需假数据），启动后保持首页不动，观察 %APPDATA%\world.genarrative.ai-game-creator\diagnostics\application.log 与对应 WebView2 renderer 进程。

补充一条与本 PR 无关、但影响更大的现场发现（本地 dev 客户端实测）： **WebView2 渲染进程存在无限渲染循环**，日志持续刷： ``` WEBVIEW error webview: Maximum update depth exceeded. This can happen when a component calls setState inside useEffect, but useEffect either doesn't have a dependency array, or one of its dependencies changes on every render. ``` 对照实验（同一台机器、同一份 `%APPDATA%\world.genarrative.ai-game-creator`）： | 场景 | 渲染进程工作集/私有 | CPU 累计 | 3.5 分钟内 `Maximum update depth` 条数 | | --- | --- | --- | --- | | 开 `template-library-fixtures`（1000 条假数据，未打开模板库页，停在首页） | 4.4 GB / 4.8 GB | 219.8s | 持续刷屏（日志 5 秒 +8.5 KB） | | **关 fixture（5 个真模板，从未打开模板库页）** | **4.2 GB / 4.6 GB** | **186.1s** | **468 条** | 结论：渲染进程 4 GB+ 内存与持续吃 CPU **不是**模板库卡片数量造成的（对照场景连模板库页都没打开），而是应用层既有的 setState 循环。它也是"拖动进度条不流畅 / 筛选切回全量卡一下"的主要背景噪声——虚拟列表解决的是 1000 个卡片节点这条真实性能债，但要判定交互流畅度是否达标，需要先修掉这个循环再复测。 复现：`AGC_DEV_CARGO_FEATURES=cocos-editor-execute npm run dev`（无需假数据），启动后保持首页不动，观察 `%APPDATA%\world.genarrative.ai-game-creator\diagnostics\application.log` 与对应 WebView2 renderer 进程。

kdletters added 1 commit 2026-09-17 16:54:07 +08:00

修复 AGC 壳首页无限 setState 循环 ... 13d272c2d4

- WorkspaceLauncher 发布活动项目面板的 effect 不再依赖每次渲染都换身份的 openActiveProject：回调改走 ref，依赖只留数据
- useDirectActiveTurns 轮询只在快照内容变化时更新状态，空态保持引用稳定，避免每 5 秒换数组身份带动下游 effect
- WindowChrome 的 context value 用 useMemo 收口，避免所有 useWindowChrome 消费方被无谓重渲染
- 新增回归测试 directActiveTurns.test.tsx：轮询返回值不变时快照引用必须不变
- pitfalls 记录现象/根因/定位手段（console.error 里抓调用栈）与验证数据：修复后 35 秒 0 条深度错误、renderer 工作集 4.2GB -> 254MB

kdletters added 1 commit 2026-09-17 17:28:05 +08:00

修复虚拟列表卡片区空白：页面高度按父级实测 ... 5a219e53a5

- 页面根节点高度改为内联写入父级 .launcher-main 的实测高度：外壳的 .launcher-main > .platform-theme { height:100% } 特异性高于 Tailwind，且该百分比在 min-height:100vh 链上是不定高，页面退化成内容高度后虚拟网格视口为 0（卡片区整片空白）；100vh 又比舞台高一个标题栏会裁掉底部
- 技术方案补页面高度契约说明
- 真机复测（1000 条假数据）：可视区 16 张卡、进入页面后 23ms 出现卡片、搜索到空态 22ms、清空搜索回全量 22ms；WebView2 组工作集 487MB（修复前 4.2-4.6GB）

kdletters commented 2026-09-17 17:28:21 +08:00

Author

Member

Copy Link

Copy Source

无限 setState 已定位并修复，虚拟列表也在真机复测过了，数据如下（本地 dev 客户端，同机同 %APPDATA%）。

1. 无限 setState 根因（13d272c2d）

• 根因：WorkspaceLauncher 发布"活动项目面板"的 effect 依赖 openActiveProject；它是 useCallback([openProject, setProjectPath]) 生成的，而 openProject 来自 useHomeProjectCreation 的普通函数声明（每次渲染都是新身份）→ effect 每渲染重跑 → cleanup/主体调 setActiveProjectRuns 改 WindowChrome state → 标题栏重渲染 → 再来一轮。WindowChrome 的 context value 当时还是内联对象，进一步放大连带重渲染。
• 定位手段：日志里没有组件栈；在 console.error 包装里抓 new Error().stack（这条日志与 setState 同栈），拿到 commitHookEffectListUnmount → dispatchSetState → WorkspaceLauncher.tsx:154。
• 修复：① 回调走 ref、effect 依赖只留数据；② useDirectActiveTurns 轮询只在快照内容变化时 setActiveTurns（空态保持引用稳定），不再每 5 秒换数组身份带动下游；③ WindowChrome context value 用 useMemo。

2. 虚拟列表（066d0fe6f + 5a219e53a）

• 用 workspace 里已有的 react-window@1.8.11 的 FixedSizeGrid（react-arborist 在用同一版本，未引入新包），布局契约收在纯函数 templateLibraryGrid.ts。
• 页面高度按父级 .launcher-main 实测内联设置：外壳 .launcher-main > .platform-theme { height:100% } 特异性高于 Tailwind 工具类，而这条百分比在 .launcher-shell { min-height:100vh } 链路上是不定高 → 页面退化成内容高度 → 虚拟网格视口 0，卡片区整片空白；改用 100vh 又会比舞台高一个标题栏（800 vs 750）裁掉底部。这一点已写进技术方案，避免后人踩回。

3. 真机复测（1000 条假数据，UIA 驱动）

指标	修复前	修复后
renderer 工作集 / 私有	4.2–4.4 GB / 4.6–4.8 GB	173–177 MB / 122–124 MB
WebView2 组总工作集（含 GPU/utility）	~4.6 GB	487–500 MB
renderer CPU 累计	186–220s（持续增长）	1.2–1.6s
Maximum update depth 日志	~1.5 条/秒	0
进入模板库页 → 卡片出现	页面几乎不可用	23ms
搜索 → 空态	—	22ms
清空搜索 → 回到全量（原"卡一会"）	—	22ms
标签筛选 / 取消	—	立即（可视区 16 张卡）

DOM 里同时只挂可视区的 16 张卡，滚动高度仍按 250 行 × 行高计算。

未测：真实帧时间/掉帧分布。本机 dev 脚本会给 Tauri CLI 子进程传裁剪过的 env，WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=… 传不进 WebView2，所以拿不到 CDP；需要的话我再补一条显式透传，就能采 long task 与帧率分布。

无限 setState 已定位并修复，虚拟列表也在真机复测过了，数据如下（本地 dev 客户端，同机同 `%APPDATA%`）。 ## 1. 无限 setState 根因（`13d272c2d`） - **根因**：`WorkspaceLauncher` 发布"活动项目面板"的 effect 依赖 `openActiveProject`；它是 `useCallback([openProject, setProjectPath])` 生成的，而 `openProject` 来自 `useHomeProjectCreation` 的**普通函数声明**（每次渲染都是新身份）→ effect 每渲染重跑 → cleanup/主体调 `setActiveProjectRuns` 改 `WindowChrome` state → 标题栏重渲染 → 再来一轮。`WindowChrome` 的 context value 当时还是内联对象，进一步放大连带重渲染。 - **定位手段**：日志里没有组件栈；在 `console.error` 包装里抓 `new Error().stack`（这条日志与 setState 同栈），拿到 `commitHookEffectListUnmount → dispatchSetState → WorkspaceLauncher.tsx:154`。 - **修复**：① 回调走 ref、effect 依赖只留数据；② `useDirectActiveTurns` 轮询只在快照内容变化时 `setActiveTurns`（空态保持引用稳定），不再每 5 秒换数组身份带动下游；③ `WindowChrome` context value 用 `useMemo`。 ## 2. 虚拟列表（`066d0fe6f` + `5a219e53a`） - 用 workspace 里已有的 `react-window@1.8.11` 的 `FixedSizeGrid`（`react-arborist` 在用同一版本，未引入新包），布局契约收在纯函数 `templateLibraryGrid.ts`。 - **页面高度按父级 `.launcher-main` 实测内联设置**：外壳 `.launcher-main > .platform-theme { height:100% }` 特异性高于 Tailwind 工具类，而这条百分比在 `.launcher-shell { min-height:100vh }` 链路上是不定高 → 页面退化成内容高度 → 虚拟网格视口 0，卡片区整片空白；改用 `100vh` 又会比舞台高一个标题栏（800 vs 750）裁掉底部。这一点已写进技术方案，避免后人踩回。 ## 3. 真机复测（1000 条假数据，UIA 驱动） | 指标 | 修复前 | 修复后 | | --- | --- | --- | | renderer 工作集 / 私有 | 4.2–4.4 GB / 4.6–4.8 GB | **173–177 MB / 122–124 MB** | | WebView2 组总工作集（含 GPU/utility） | ~4.6 GB | **487–500 MB** | | renderer CPU 累计 | 186–220s（持续增长） | **1.2–1.6s** | | `Maximum update depth` 日志 | ~1.5 条/秒 | **0** | | 进入模板库页 → 卡片出现 | 页面几乎不可用 | **23ms** | | 搜索 → 空态 | — | **22ms** | | 清空搜索 → 回到全量（原"卡一会"） | — | **22ms** | | 标签筛选 / 取消 | — | 立即（可视区 16 张卡） | DOM 里同时只挂可视区的 16 张卡，滚动高度仍按 250 行 × 行高计算。 **未测**：真实帧时间/掉帧分布。本机 dev 脚本会给 Tauri CLI 子进程传裁剪过的 env，`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=…` 传不进 WebView2，所以拿不到 CDP；需要的话我再补一条显式透传，就能采 long task 与帧率分布。

kdletters added 1 commit 2026-09-17 17:45:17 +08:00

合入 master 并解决模板库分支冲突 ... b3d289f3aa

- directActiveTurns：保留 master 的重试定时器清理与本分支的快照签名去重（两侧在同一位置相邻插入）
- directActiveTurns 测试：合并两侧用例（master 的定时器清理与面板用例 + 本分支的快照引用稳定用例）
- decision-log：两侧新增条目都保留（AGC 模板库约定 + CI 宿主 CPU 上限）
- 冲突后复核：cargo check 0 错误、tsc 通过、33 项前端单测通过、编码 / 文档索引 / diff 检查通过

kdletters merged commit 5db407c3dc into master 2026-09-17 17:48:06 +08:00

kdletters deleted branch codex/agc-template-library 2026-09-17 17:48:07 +08:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

Compat/Breaking

Breaking change that won't be backward compatible

Kind/Bug

Something is not working

Kind/Documentation

Documentation changes

Kind/Enhancement

Improve existing functionality

Kind/Feature

New functionality

Kind/Security

This is security issue

Kind/Testing

Issue or pull request related to testing

Priority

Critical

1

The priority is critical

Priority

High

2

The priority is high

Priority

Low

4

The priority is low

Priority

Medium

3

The priority is medium

Reviewed

Confirmed

1

Issue has been confirmed

Reviewed

Duplicate

2

This issue or pull request already exists

Reviewed

Invalid

3

Invalid issue

Reviewed

Won't Fix

3

This issue won't be fixed

Status

Abandoned

3

Somebody has started to work on this but abandoned work

Status

Blocked

1

Something is blocking this issue or pull request

Status

Need More Info

2

Feedback is required to reproduce issue or to continue work

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

HuangJiaJia JenkenB k88936 (王德宇) kdletters (段舒康) laura2008 (王乐) lhk229 (孔令弘) Loer (农洛儿) loong suzmii (董羽秦) taobaisu (叶东旭) wuxiangwanzi (王子民) YixuanLiu ziyu

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GenarrativeAI/Genarrative#396