新增后台 AGC 模板管理与模板库内容寻址落库

- 后台新增「模板管理」页：按权限查看并编辑模板名称/简介/标签/封面，支持上架与下架；路由、侧栏、tab 权限、API 客户端与 DTO 同步接入 - api-server 新增 /admin/api/agc-templates 读取与更新路由，复用现有后台鉴权与 tab 权限校验，权限不足按既有失败关闭口径拒绝 - module-assets 收敛模板库纯规则（active/inactive 投影、索引 schema 与重复项校验、ZIP 大小与摘要核对），platform-oss 承担对象存储读写、不可变对象复用与发布互斥锁 - shared-contracts 补后台模板 DTO；spacetime-module 账号存储适配保持既有 schema 不变 - AGC 壳内置模板索引与建项读取改为内容寻址对象，补模板安装、越界归档、索引不匹配等用例 - 模板库发布脚本支持定向发布与上架/下架合并、内容地址复用与锁语义，CLI 守卫用例同步；jenkins 两条客户端打包管线统一触发邮件通知 Job 并传递首装包链接 - 内置 5 个 Cocos 官方模板载荷与索引 fixture（内容地址对象，共 90 个文件） - 补「后台模板管理」里程碑与实施计划，更新模板库技术方案、开发运维文档与共享记忆 - 验证：admin-web 39 项用例与 typecheck、发布脚本 25 项用例、api-server 与 AGC 壳编译、模板库定向 Rust 用例（AGC 壳 18 项、module-assets/platform-oss 16 项、后台权限 1 项）、check:encoding / check:doc-index / check:production-ops / rustfmt 全部通过
2026-09-21 13:50:26 +08:00
parent 6845cdcbc5
commit 02a7abeb3f
129 changed files with 21480 additions and 198 deletions
@@ -0,0 +1,18 @@
+# 后台模板管理实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】后台模板管理-2026-09-19.md` |
+| Status | in-progress |
+| Owner | Codex |
+
+## 修改边界与顺序
+
+1. 评审主规范和 DTO，确认权限、单清单 inactive 投影、锁与凭据配置。
+2. 前端独立负责 admin-web 页面/路由/类型/API/tests；存储分支负责 platform-oss 模板 adapter；领域分支负责 module-assets 纯规则、shared-contracts/admin DTO；主线程负责 API/配置/状态装配、CLI状态兼容、文档和集成验证。
+3. 后端共用已定义锁语义，CLI同步inactive合并；并行完成定向测试，Cargo依赖编译串行协调。
+4. 复审、API与浏览器smoke，回填证据，删除本里程碑临时计划。
+
+## 时间盒与风险
+
+按规格评审、最小读写闭环、权限/冲突边界、界面验收四个检查点推进。旧客户端仅识别templates，不能把下架条目留在该数组；正文与index不能跨bucket；异步请求取消不能误释放结果不明的锁。只新增必要执行层，保留现有Cocos改动和个人工具数据，不扩大为新模板上传系统。
@@ -0,0 +1,23 @@
+# 后台模板管理
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | approved |
+| Date | 2026-09-19 |
+| Parent Spec | `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md` |
+
+## 目标与范围
+
+后台管理员按权限查看并编辑 AGC 模板名称/简介/标签/封面，支持上架/下架。用户已明确选择此范围，不新增模板、ZIP 上传、版本发布、删除、部署或提交。
+
+## 合同与依赖
+
+OSS index 单一真相，active/inactive 两组；CLI/Rust 共用不可变对象及互斥发布锁；客户端沿用 active 读取。后台现有鉴权/权限/组件复用；不改 SpacetimeDB schema。
+
+## 验收
+
+- 页面、导航、权限和请求/响应合同一致，未授权无读取/写入。
+- 编辑、封面、上下架真实通过存储适配器写回；ZIP与版本不变，其他模板及未知字段保留。
+- 并发、旧revision、失败/未知写入和页面迟到响应失败关闭；CLI不重新上架下架项。
+- 定向测试/类型/构建/编码/格式与文档检查通过；本地API健康检查与桌面/移动受控浏览器smoke，真实OSS不写。
@@ -51,6 +51,8 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐

 ## AGC DirectProject 与 UI workflow

+- AGC 模板库包含 Creator 3.8.8 的四个官方 Cocos 模板；Cocos 建项复用原生导入，重建项目 UUID 并保留场景与资源。发布使用内容地址保留历史对象，并在确认 Bucket 从未开启版本控制后获取排他锁；`--only` 在锁内合并最新清单，清单写入结果不明时留锁，同版本 ZIP 变化拒绝发布。详细合同见 [AGC 模板库与模板建项](../../technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)。
+
 - AGC 的本地 `llm.customEnabled` 默认关闭，只能手动修改配置文件；开启后设置支持自定义 Responses 端点、读取 `/models`、勾选和预览 `visibleModels`。对话下拉只显示勾选项，LLM 请求经客户端凭据代理直连自定义上游；不会回退官方中转，平台资源服务仍使用账号权限。详见 AGC 后台模型别名与对话选择规范。

 - DirectProject 对话先在完整历史中按回合/原始 item 身份关联，再分页渲染；每个回合只有一个呈现入口。有流按 item `seq` 交替文本和工具，无流采用历史正文；禁止位置猜配或同时展示累计回复与 item 正文。流写入单调归并，收尾等待落盘任务，不按磁盘“最后一段”猜最终回复位置。详见 AGC 实施计划的“DirectProject 回合展示唯一归属”。
@@ -19,51 +19,73 @@ AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，
 - 验证入口：后台灰度页面测试、`useTemplateLibrary.test.tsx`、AppSurface 实际挂载的 template 用例、原生 `template_library` 测试和后端 `frontend_runtime_config` 测试。退出开始使用既有平台会话代次立即撤销，建项返回、revision 读取和预览核验后的旧回调均不得导航或登记最近项目；同主体 token 轮换不误撤销原生身份。
 - 本地隔离数据库已验证 Gate 经后台 API 保存后可重新读回，匿名运行时配置为 false；后台受控浏览器 smoke 验证桌面和 320px 布局及保存确认交互。线上 OSS 下载和正式安装包登录后的端到端操作不由这些测试替代。

+## 后台模板管理
+
+- 后台新增 `#agc-templates`「模板管理」页签，复用现有后台布局、列表、公共表单/独立弹窗及写入确认。提供名称/ID/标签搜索、运行时和上下架筛选，展示封面、名称、简介、标签、引擎/版本、包大小与上架状态。
+- 本轮只允许编辑名称、简介、标签、封面和上架状态；不新增模板、不上传 ZIP、不修改 ID、运行时、引擎或模板版本，不删除包、历史对象或已建项目。
+- 唯一数据真相仍是 OSS `templates/index.json`：`templates` 保存上架条目，新增可选 `inactiveTemplates` 保存下架条目，两个数组之间 ID 唯一。后台合并展示两组；AGC 客户端仍只读取 `templates`，刷新后不展示下架项。下架不是资源访问撤销，旧清单缓存和已下载项目不受影响。下架条目元数据位于公开清单，不承载私密草稿。
+- 后台读取/写入分别为 `GET /admin/api/agc-templates`、`PUT /admin/api/agc-templates/{id}`，均经过现有后台认证及 `agc-templates` 页签权限。owner 默认可用，member 需显式分配该权限；不新增数据库表或 schema。部署时后台、API 与引用权限白名单的 SpacetimeDB 模块需同步更新，成员账号才可保存新页签权限。
+- GET 返回 `{ revision, writable, templates }`：revision 是完整原始清单字节的 SHA-256；每条包含 `id/title/summary/tags/runtime/engine/engineVersion/templateVersion/enabled/coverUrl/zipSizeBytes`。不可用或格式错误返回可诊断错误，不能当作空模板库。
+- PUT 请求 `{ expectedRevision, title, summary, tags, enabled, cover? }`，禁止未知字段。名称 trim 后 1–80 字符、简介最多 1000 字符、最多 16 个去重标签（每项 1–32 字符）。封面可选 `{ contentType, dataBase64 }`，仅接受真实 PNG/JPEG/WebP，解码前后校验，原始字节最多 5 MiB、单边最多 4096 像素且不超过 1600 万像素；原有 SVG 引用可继续展示。HTTP body 上限 8 MiB。返回与 GET 同形的最新快照。
+- 写入复用同一 OSS 发布锁、版本控制前置检查及不确定清单写入留锁协议；在锁内读取最新清单并比较 expectedRevision，过期或锁忙返回 409，不自动重试写入。封面及更新后的 template.json 以内容摘要键写入并回读校验，再一次提交清单；ZIP、版本和未知元数据字段保留。清单响应不明返回 503 并留锁，后续需核对；任何 API 错误不回显凭据或上游正文。
+- 页面保存/上下架前使用既有确认交互。编辑弹窗保持独立；保存中防重复提交，失败保留输入并展示错误，409 引导刷新后重新编辑；刷新、切页、换账号和晚到响应不能覆盖新页面状态。封面仅作为待保存草稿预览，成功后使用后端返回的正式地址。
+- 模板 OSS 目标固定为当前 AGC 公开 bucket/endpoint，不能误用通用素材 Bucket。凭据优先成套读取 `GENARRATIVE_AGC_TEMPLATE_LIBRARY_OSS_ACCESS_KEY_ID/SECRET`，两项均未配置时可成套复用已有 `ALIYUN_OSS_ACCESS_KEY_ID/SECRET`；半配置不拼接回退且禁止写入。无可用写凭据时后台可只读，写接口返回 503，页面明确不可保存。
+- CLI 与后台共享锁和清单合同。CLI 合并保留未选条目与 `inactiveTemplates`，更新下架模板仍保持下架；新增模板默认上架，CLI 不承担删除或上下架。显式发布选中 ID 时，展示字段按该模板源更新，后台编辑结果持续有效直到下一次显式发布该 ID。两端都必须保留另一组条目，不能因本地模板源较旧而抹掉后台记录。
+- 验收包含权限、入口挂载、过滤、编辑与图片校验、上下架往返、未知字段保留、过期 revision/锁争用、上传失败与未知提交、CLI 对下架项的更新/保留，以及桌面/窄屏真实浏览器验证。真实 OSS 写入和生产部署不在本轮验证范围，使用隔离存储替身。
+
 ## OSS 契约

 ```text
 templates/
  index.json                       # 模板库清单，客户端唯一读取入口
+  .publish-lock.json                # 发布互斥锁，不供客户端读取
  v1/<templateId>/
-    template.json                  # 单模板元数据（含文件级摘要）
-    template.zip                   # 模板正文，zip 根 == AGC 项目根（如 game/index.html）
-    cover.(png|jpg|webp|svg)       # 封面图（卡片展示，客户端 <img> 直接取）
+    sha256/<zipSha256>/template.zip       # 模板正文，zip 根 == AGC 项目根
+    sha256/<coverSha256>/cover.<ext>      # 封面图
+    sha256/<metadataSha256>/template.json # 单模板元数据（含文件级摘要）
 ```

 `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`） |
+| 字段                                                                  | 说明                                                              |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `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 起步工程）。
+- 上传与校验由 [`scripts/agc-template-library-publish.mjs`](../../scripts/agc-template-library-publish.mjs) 完成：`--source apps/ai-game-creator-shell/template-library [--dry-run] [--only <id,id,...>]`。ZIP、封面和元数据分别以自身字节的 SHA-256 定位，只创建新对象或复用逐字节校验一致的已有对象；全部对象回读一致后才更新 `index.json`。失败不回收已上传对象，旧清单及其引用始终可读。
+- 只更新指定模板时使用 `--only <id,id,...>`，在发布锁内读取最新清单，只替换指定 ID，其余条目和未知扩展字段保留。首次清单 404 可由本次选择初始化；读取异常或清单非法时停止。全量发布也遵守相同锁与版本门禁。
+- 正式发布先通过 `GetBucketVersioning` 确认 Bucket 从未开启版本控制，再用 `x-oss-forbid-overwrite: true` 原子创建 `.publish-lock.json`；版本控制 Enabled、Suspended、检查无权限或无法判定时均在写入前停止。所有写同一清单的发布进程必须使用此锁，发布期间不得改变 Bucket 版本控制配置。锁没有自动过期或抢占机制，已被占用时直接失败，重新执行须重新获取锁并读取最新清单。
+- 只释放本任务已明确获取且 owner 标识仍一致的锁。获取结果不明时不猜测删除。正文对象不可变，其写入失败可安全释放本任务的锁；清单 PUT 已发起后若遇到断连、超时或服务端 5xx 等不确定结果，必须保留锁并报错，防止旧在途请求晚于下一发布者写入。清单收到确定成功或确定拒绝响应后才进入正常解锁路径；不自动重发清单写入，也不凭一次 GET 猜测在途 PUT 已结束。遗留锁须在确认原请求及进程已终止或完成后由运维处理；释放失败必须报告，不伪装为发布成功。
+- `--dry-run` 仅构造和读取合并计划，不读取凭据、不获取锁、不 PUT/DELETE。发布不删除历史对象，也不提供随发布清理的选项；旧客户端缓存和未完成下载可能仍引用旧键。
+- 同一 ID、同一 `templateVersion` 的 ZIP 大小或摘要改变时，在上传正文前拒绝，要求更新模板版本；只把相同 ZIP 迁移到新键可保留版本。客户端现有 `<id>/<templateVersion>` 缓存行为不变。
+- 当前模板：`blank-web`（空白网页）、`blank-2d-canvas`（空白二维画布）、`blank-3d-scene`（空白三维场景）、`phaser-2d-starter`（Phaser 2D 起步工程）、`threejs-3d-starter`（Three.js 3D 起步工程），以及 Cocos Creator 3.8.8 的 `cocos-empty-2d`、`cocos-empty-3d`、`cocos-empty-3d-hq`、`cocos-hello-world`。
+- Cocos 内容来自 Creator 3.8.8 随附的 `resources/templates/{empty-2d,empty,empty-quality,hello-3d-world}`，保留官方资源、`.meta`、设置和模板预设；补齐 `package.json.creator.version`，空模板以 `assets/.gitkeep` 保证资源目录进入 Git 和 ZIP。`entry` 为 `package.json`，不打包编辑器生成的缓存或用户项目数据。
+- Cocos 建项在复制后按实际 `package.json.creator.version + assets/` 识别，复用既有 Cocos 导入流程，写入 `cocosProjectRoot: "."`；每个新项目重建 `package.json.uuid` 并写入所选项目名。只创建 `.agent` 管理目录，不生成 Web 占位入口；模板源与本机安装缓存不被改写。
 - 客户端可用 `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` 清单与标准目录。根目录可用 `projectsRoot` 覆盖（必须来自本机目录选择器并通过私有路径门禁），未指定时仍是 `<app_data>/projects/`；见 [`【实施计划】AGC项目创建目录可选-2026-09-17.md`](../project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md) |
+| 命令                                                | 行为                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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` | 需要时先安装模板，然后在自动工作区根目录下按既有自动工作区规则建目录：先复制模板文件；Cocos 项目更新自身身份后走既有 Cocos 导入，其余沿现有 `init_local_game_project_at` 初始化。根目录默认是 `<app_data>/projects/`，用户可选 `projectsRoot` 覆盖（必须来自本机目录选择器并通过私有路径门禁），见 [`【实施计划】AGC项目创建目录可选-2026-09-17.md`](../project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md) |

 安全与健壮性：

@@ -86,6 +108,12 @@ templates/

 ## 验收与验证

+并发发布验收必须覆盖真实发布编排的离线故障注入：正文写入或清单提交失败后旧清单引用保持一致；两个发布者互斥、后续重试从新清单合并；条件请求头正确签名；版本控制状态不安全时零写入；外部锁不被删除；同版本改 ZIP 被拒绝；已存在内容对象冲突及释放失败可诊断。普通打包和纯合并函数测试不能替代此门禁。OSS 协议依据：[PutObject](https://help.aliyun.com/zh/oss/developer-reference/putobject)、[GetBucketVersioning](https://help.aliyun.com/zh/oss/developer-reference/getbucketversioning) 与 [V1 签名](https://help.aliyun.com/zh/oss/developer-reference/include-signatures-in-the-authorization-header)。
+
+Cocos 回归分别覆盖仓库模板和线上真实 ZIP 的安装、连续建项、独立 UUID、`cocosProjectRoot`、原文件保留与安装缓存不变；Web 模板继续走原有回归。此处验证的是模板下载与建项，不替代 Creator 内场景运行验收。Cocos 原生建项分流需要包含此实现的客户端，旧二进制须重新构建或更新。
+
+`2026-09-19` 发布一致性验收：Node 发布回归 22 项通过，覆盖两个发布者竞争、正文/清单写入失败、迟到清单 PUT、锁归属、版本控制拒绝、V1 签名及真实 CLI 的无写入 dry-run。Rust 定向回归 15 项通过，新增内容地址的清单解析与 URL 保留校验；3 项线上用例本轮未重复执行，此前同日线上下载及原生建项已通过。只读 dry-run 保留线上九个模板并仅计划更新四个 Cocos 条目。格式、编码、文档索引、定向 ESLint 与 diff 检查通过。全部并发/故障写入证据来自离线替身，未执行真实 OSS 锁写入或发布，也未验证 Creator 内场景运行。
+
 ## 本地压测假数据注入（feature 控制）

 模板库的数据源在 Rust 侧（清单校验、安装状态、下载与建项目都在这里），TS 只消费快照做渲染，所以假数据注入也放在 Rust 侧，走与真实完全一致的链路。
@@ -122,6 +150,10 @@ AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT=300 AGC_DEV_CARGO_FEATURES=template-library
 - 前端回归：1000 条渲染 + 已安装过滤（334）/标签过滤（50）/关键词过滤数量自洽，见 `apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx`。

 ```bash
+# 模板内容、确定性打包与定向发布合并回归
+node --test scripts/agc-template-library-publish.test.mjs
+# 仅发布 Cocos 模板（先加 --dry-run 核对合并清单）
+node scripts/agc-template-library-publish.mjs --source apps/ai-game-creator-shell/template-library --only cocos-empty-2d,cocos-empty-3d,cocos-empty-3d-hq,cocos-hello-world
 # 模板库单测（清单校验、键安全、解压路径逃逸、安装与建项目）
 cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell template_library
 # 模板库真连检查（可选，需要网络）：读线上清单、下载安装线上模板包并据此建项目
@@ -144,4 +176,4 @@ curl -s https://agc-dev.oss-rg-china-mainland.aliyuncs.com/templates/index.json

 - 清单读不到且没有本机缓存：模板库页显示错误与重试，首页推荐位显示「模板库暂时没有可用的模板」。
 - 版本落后：`installedVersion != templateVersion` 视为需要重新下载，点「使用模板」会先重下再建项目。
- 需要回退整条链路时，删除 `templates/` 前缀即可让客户端回到"空模板库"；客户端代码路径不受影响。
+- 回退清单同样必须使用发布互斥协议并保留其引用的历史对象，不能删除整个 `templates/` 前缀来回退。