Merge branch 'master' into feat/gptimage2to2.5

docs/README.md

@@ -48,6 +48,7 @@
 - [AGC 客户端更新检查与下载](./technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md)：启动版本检测、固定 dev 服务、OSS 清单与官网最新客户端下载。
 - [AGC 总版本号与发号](./technical/【技术方案】AGC总版本号与发号-2026-09-20.md)：客户端版本号收口到 OSS `agc/global-version.json`，统一构建一次发号供各渠道共用，渠道高水位降级为断言。
 - [AGC 模板库与模板建项](./technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)：`templates/` 前缀的模板库契约、下载安装与「用模板建项目」链路。
+- [AGC 模板包组织指南](./【模板规范】AGC模板包组织指南-2026-09-21.md)：模板 ZIP 的根目录结构、Cocos 工程保留项、禁止放入的内容、封面与体积上限、版本不可变与发布前自检。
 - [DirectProject 本轮附件路径映射](./technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md)：Direct 首轮只映射附件原名与项目相对路径，不灌正文、不区别 GDD。
 - [Direct 回合行为审计账本](./technical/【技术方案】Direct回合行为审计账本-2026-08-31.md)：Direct GUI 回合把 native 读 / MCP / 写文件落成项目内有界时间线，用于判断有没有打开本轮附件。
 - [项目开发工作台 PRD](./prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)：当前工作台页面和验收边界。

docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md

@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-09-21`（2026-09-20 音频生成并入图片类那份后台任务账本、派生/修改类任务并入同一「生成任务」侧栏，2026-09-21 卡片浮层改为「提交即关」、**「生成任务」侧栏从画布左侧贴边改为画布右上角锚点（开关常驻）**、**资源卡可拖到对话栏批量 @ 引用**、**替换面板改为非模态浮层并支持在画布上点选目标**（验收现场两条修正：任务锚点改挂画布那一格、展开后开关让位），见 §3.10 / §5.3 / §7.8 / §7.9 与 [`【功能说明】AGC聊天素材引用`](../【功能说明】AGC聊天素材引用-2026-09-08.md)；2026-09-14 图片类生成后台化：入口 IPC 为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变）
+更新时间：`2026-09-21`（2026-09-20 音频生成并入图片类那份后台任务账本、派生/修改类任务并入同一「生成任务」侧栏，2026-09-21 卡片浮层改为「提交即关」、**「生成任务」侧栏从画布左侧贴边改为画布右上角锚点（开关常驻）**、**资源卡可拖到对话栏批量 @ 引用**、**替换面板改为非模态浮层并支持在画布上点选目标**（验收现场两条修正：任务锚点改挂画布那一格、展开后开关让位），见 §3.10 / §5.3 / §7.8 / §7.9 与 [`【功能说明】AGC聊天素材引用`](../【功能说明】AGC聊天素材引用-2026-09-08.md)；2026-09-14 图片类生成后台化：入口 IPC 为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变；2026-09-21 Godot 工作区发现放宽：一层多命中按目录名排序取第一个，`project.godot` 允许是链接/reparse point/硬链接，见 §3.8）
 
 ## 1. 产品定位
 
@@ -136,7 +136,7 @@
 
 ### 3.8 现有 Godot 项目
 
-- 首页和项目组统一使用“打开项目”，不提供独立 Godot 按钮。用户选择的目录作为工作区根；系统先检查根目录，再检查一层直接子目录中的普通文件 `project.godot`。根目录命中优先；一层发现多个 Godot 工程时必须提示歧义，不猜测目标。
+- 首页和项目组统一使用“打开项目”，不提供独立 Godot 按钮。用户选择的目录作为工作区根；系统先检查根目录，再检查一层直接子目录中的 `project.godot`。根目录命中优先；一层命中多个 Godot 工程时按目录名排序取第一个，不再因为存在第二个工程而失败或要求用户改选。`project.godot` 本身是符号链接、Windows reparse point 或硬链接时按链接目标判定，解析后是文件即命中；目录与悬空链接仍不算命中。
 - 工作区根始终绑定文件读取、修改、命令 cwd、对话、Runtime 和最近项目记录；`.agent/`、Agent DB 与日志也只写在这里。`project.godot` 所在目录额外以 `godotProjectRoot` 记录为相对工作区的 `.` 或单层目录名，不把项目作用域切到 Godot 子目录。
 - 首次打开只在工作区根创建 `.agent/` 元数据；已有 `.agent/manifest.json` 时读取并按当前唯一文件布局校准 `godotProjectRoot`。Godot 源码、场景、资源和项目配置继续使用原目录结构，不复制工程，也不建立 `game/`、`assets/`、`memory/`、`exports/` 平行目录。
 - Godot 项目使用 `standard` Run Profile，避免套用 Web 原型的 `game/index.html`、本地 HTTP 预览和自主 Web 游戏完成门；本期不提供 Godot 内嵌运行预览。

docs/project-memory/plans/【实施计划】AGC模板库客户端接入-2026-09-17.md

@@ -1,59 +0,0 @@
-# AGC 模板库客户端接入实施计划
-
-Version: 1.0
-Status: active
-Date: 2026-09-17
-Milestone Spec: `docs/project-memory/plans/【里程碑】AGC模板库客户端接入-2026-09-17.md`
-
-## 步骤
-
-1. **OSS 库布局与契约**
-   - 在 `agc-dev` 落地 `templates/` 前缀：`index.json`、`v1/<id>/{template.json,template.zip,cover.*}`。
-   - 清单补齐 `tags`、`coverKey/coverWidth/coverHeight/coverSha256`，正文改为 zip（zip 根 == 项目根）。
-   - 模板源落在 `apps/ai-game-creator-shell/template-library/v1/<id>/{meta.json,project/**,cover.*}`；zip 由 `scripts/agc-template-library-publish.mjs` 现场打包（不落仓库）。
-   - 交付：发布脚本（校验 + 打包 + 上传 + 回读校验，支持 `--dry-run` / `--prune`）、`templates/README.md`，以及 5 个模板（3 个空白 + 2 个起步工程）。
-   - 验收：匿名 `GET templates/index.json` 可读，每个 `zipKey` 回读 SHA-256 与清单一致。
-
-2. **Rust 模板库模块**
-   - 新增 `src-tauri/src/template_library.rs`：清单解析与校验、受信任 base、缓存/安装目录、zip 安全解压、安装记录、由模板建项目。
-   - 注册命令 `fetch_game_template_library`、`download_game_template`、`create_automatic_local_game_project_from_template`。
-   - 交付：模块内 8 项单测（schema/重复模板、键前缀、base 校验、解压逃逸、摘要与大小、安装记录、建项目与失败清理）。
-   - 验收：`cargo test --bin genarrative-ai-game-creator-shell template_library` 全绿。
-
-3. **前端状态链路**
-   - `src/features/template-library/templateLibraryModel.ts`（类型与搜索/筛选纯函数）与 `useTemplateLibrary.ts`（拉取、下载、建项目、就地更新已下载状态）。
-   - `useHomeProjectCreation` 增加 `enterCreatedTemplateProject`，复用既有进项目通道。
-   - 交付：9 项模型单测。
-   - 验收：`npx vitest run src/features/template-library` 全绿。
-
-4. **界面接入**
-   - 新增 `src/view/template-library/index.tsx` 全屏页；`LauncherView` 增加 `template-library`；左侧导航加模板库入口。
-   - 首页「灵感推荐」替换为 `TemplateRecommendations`；删除 `InspirationGallery.tsx` 与 `assets/inspiration/`。
-   - `tauri.conf.json` 的 `img-src` 放行受信任 OSS 主机以加载封面。
-   - 验收：模板库页可搜索、筛选、下载、显示已下载并成功建项目；首页推荐位可跳转。
-
-5. **文档与共享记忆**
-   - 主规范 `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`，并在 `docs/README.md` 建索引。
-   - 本里程碑与实施计划；`decision-log.md` 记录库路径、清单 schema、缓存目录与 CSP 约定。
-   - 验收：`node scripts/check-doc-index.mjs` 通过。
-
-## 验证命令
-
-```bash
-cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml
-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
-cd apps/ai-game-creator-shell && npx tsc -p tsconfig.json --noEmit
-npx vitest run apps/ai-game-creator-shell/tests/templateLibraryModel.test.ts apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx
-node scripts/agc-template-library-publish.mjs --source <dir> --dry-run
-npm run check:encoding
-node scripts/check-doc-index.mjs
-git diff --check
-```
-
-## 风险与回退
-
-- **封面走 WebView 直连**：仅放行受信任 OSS 主机；若日后改用后端签名，清单的 `coverKey` 不变。
-- **模板包体积**：下载上限 512 MiB、解压文件数 4096、单文件 256 MiB；超限直接拒绝，不落盘。
-- **清单漂移**：客户端只信「受信任主机 + 对象键」，清单中的地址字段不参与请求。
-- **回退**：清空 `templates/` 前缀即回到空模板库；客户端保留错误与空态展示，不阻断其它功能。

docs/project-memory/plans/【实施计划】AGC渠道安装身份隔离-2026-09-21.md

@@ -0,0 +1,49 @@
+# 【实施计划】AGC 渠道安装身份隔离
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC渠道安装身份隔离-2026-09-21.md` |
+| Status | ready |
+| Owner | 当前 Agent |
+
+## 修改边界
+
+- 允许修改：
+  - `apps/ai-game-creator-shell/scripts/channel-identity.mjs`（新增，渠道身份单点定义）
+  - `apps/ai-game-creator-shell/scripts/build-release.mjs`、`build-macos-ci.mjs`、`check-config.mjs`、`agent-swarm-test-chat.mjs`
+  - `apps/ai-game-creator-shell/src-tauri/src/main.rs`、`src-tauri/src/windows.rs`、`src-tauri/src/config.rs`
+  - 对应测试：`build-release.test.mjs`、`prepare-macos-codex.test.mjs`
+  - 文档：AGC 更新主规范、共享记忆与本计划对
+- 明确不修改：OSS 分区布局、官网下载接口与页面、Jenkins Job 参数、渠道版本发行逻辑、Apple 签名/公证、移动壳。
+
+## 实现顺序
+
+1. 抽出 `channel-identity.mjs`：渠道校验、渠道显示名、`resolveChannelInstallIdentity()`；`build-release.mjs` 复用并再导出渠道校验。
+2. 渠道 `--config` 同时注入 `productName` 与 `identifier`；macOS 发布入口按发布渠道解析产品名（`.app`、updater 归档、DMG 卷名与文件名）。
+3. Rust：主窗口/工作区/启动器窗口标题取构建期产品名；AGC 自有 AppData 目录的 ACL managed 识别覆盖 `<基线>` 与 `<基线>.<渠道>`。
+4. 门禁与测试：`check-config.mjs` 断言基线等于默认渠道身份、非默认渠道身份隔离；`build-release.test.mjs` 增补身份与首装包用例；`prepare-macos-codex.test.mjs` 改断言为消费渠道身份。
+5. 文档：更新 AGC 更新主规范与共享记忆，登记决策与踩坑。
+
+## 验证命令
+
+1. `node --check apps/ai-game-creator-shell/scripts/channel-identity.mjs apps/ai-game-creator-shell/scripts/build-release.mjs apps/ai-game-creator-shell/scripts/build-macos-ci.mjs apps/ai-game-creator-shell/scripts/check-config.mjs`
+2. `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs apps/ai-game-creator-shell/scripts/release-oss.test.mjs apps/ai-game-creator-shell/scripts/prepare-macos-codex.test.mjs apps/ai-game-creator-shell/scripts/cargo-features.test.mjs`
+3. `node apps/ai-game-creator-shell/scripts/check-config.mjs`
+4. `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell -- config::tests:: --test-threads=1`
+5. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+
+## 验证结果
+
+- `node --test build-release.test.mjs release-oss.test.mjs prepare-macos-codex.test.mjs cargo-features.test.mjs`：64/64 通过（新增渠道身份、身份注入与渠道 DMG 首装选择三条用例）。
+- `node apps/ai-game-creator-shell/scripts/check-config.mjs`、`npm --prefix apps/ai-game-creator-shell run typecheck`：通过。
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell -- config::private_path_elevation_policy_tests`：12/12 通过。
+- `AGC_UPDATE_CHANNEL=release npm --prefix apps/ai-game-creator-shell run build -- --no-bundle --debug`：Tauri 接受派生的 `productName` / `identifier` 并完成构建；产物字符串实测 `陶泥儿 Release` × 1、`agc/release-win/latest.json` × 1、`world.genarrative.ai-game-creator.release` × 1、`agc/dev-win/latest.json` × 0。
+- `cargo fmt --check`（AGC 壳）、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`：通过。
+- 未执行：真实渠道打包（需要签名私钥与发号/上传授权）、双渠道真机安装与并存、macOS 节点实跑。
+
+## 风险与回滚点
+
+- 风险：默认渠道身份若被改动，既有安装目录、卸载项与升级链会断。回滚点：基线 `tauri.conf.json` 与默认渠道映射不变，门禁用例钉住。
+- 风险：非默认渠道首次以新身份安装，老 `dev` 用户不会自动迁移本地数据。回滚点：渠道身份只影响非默认渠道构建，撤销该渠道的构建产物即可，仓库侧无数据迁移。
+- 风险：窗口标题改为构建期产品名后，标题不再等于配置里的字面量。回滚点：去掉 `main.rs` 的标题覆盖调用，行为回到配置标题。
+- 风险：ACL managed 识别放宽到前缀族。回滚点：`is_game_creator_packaged_app_data_leaf` 收紧回单一直线值，但非默认渠道的提权修复会重新失败关闭。

docs/project-memory/plans/【实施计划】后台模板上传-2026-09-21.md

@@ -0,0 +1,40 @@
+# 后台模板上传实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | in-progress |
+| Date | 2026-09-21 |
+| Milestone Spec | `docs/project-memory/plans/【里程碑】后台模板上传-2026-09-21.md` |
+
+## 修改边界与顺序
+
+1. **领域规则（`module-assets/template_library.rs`）**：新增「导入准备」函数——按 ID 合并清单条目（新增默认上架、已存在就地更新并保留 `enabled` 与未知字段），校验 ID / 版本 / entry / runtime / 显示字段上限，产出待提交的清单与 `template.json` 字节；不接触存储。
+2. **存储（复用 `platform-oss/template_library.rs`）**：只使用既有 `begin_publish` / `read_index` / `put_immutable` / `commit_index` / `finish`；如缺少「读单个对象作元数据基线」的能力，再补最小只读方法，不改锁与提交语义。
+3. **契约（`shared-contracts/admin.rs` + `apps/admin-web/src/api/adminApiTypes.ts`）**：新增导入请求（manifest）与导入结果 DTO；错误体沿用现有 `AppError` + 逐项原因结构。
+4. **接口（`api-server/admin_templates.rs` + `modules/admin.rs`）**：新增 multipart handler，按「解析 manifest → 校验每个 ZIP / 封面 → 取锁 → CAS → 写内容寻址对象并回读 → 提交清单 → 释放锁」顺序实现；路由套 `require_admin_auth` 与 256 MiB body 上限，并同步路由契约测试与页签权限矩阵测试。
+5. **后台页面（`AdminAgcTemplatesPage.tsx` + `adminApiClient.ts`）**：新增「上传模板」入口与弹窗（多选 ZIP、逐行元数据、批量提交、逐行错误、写入确认），沿用既有 `useAdminWriteConfirm` 与刷新语义。
+6. **文档**：主规范新增「后台模板上传」章节；决策记录补一条；主规范中「本轮只允许…不上传 ZIP」改为指向新章节。
+
+## 验证命令
+
+```bash
+cargo test --locked -p module-assets --manifest-path server-rs/Cargo.toml -- template_library
+cargo test --locked -p api-server --manifest-path server-rs/Cargo.toml -- agc_template
+cargo fmt --all --manifest-path server-rs/Cargo.toml -- --check
+npm run admin-web:typecheck
+npx vitest run apps/admin-web/src/pages/AdminAgcTemplatesPage.test.tsx apps/admin-web/src/api/adminApiClient.test.ts
+npm run check:encoding
+npm run check:doc-index
+git diff --check
+```
+
+接口 smoke：`npm run dev:api-server`（本地 8082）+ `npm run dev:admin-web`，先用未授权/无页签权限请求确认失败关闭，再以隔离存储替身或用户显式确认的 dev bucket 做一次真实导入。
+
+## 时间盒与风险
+
+- **风险：真实发布不可逆**。导入会写公共 bucket 且不提供删除，因此默认只在本地用替身验证；对 dev bucket 的写验证必须由用户显式确认，测试用模板需可在事后下架。
+- **风险：ZIP 原字节发布与 CLI 确定性打包不一致**。同一模板可能被两条路径写成不同字节；由「同 ID 同版本字节必须一致」的门禁兜住，导入失败时提示改用 CLI 或递增版本。
+- **风险：大文件内存**。ZIP（≤64 MiB）与封面在内存中校验，单批上限 20；需要更大模板时走 CLI。
+- **风险：批量部分写入**。所有对象在清单提交前写入且不删除；中途失败时清单不变、已写对象成为未被引用的历史对象，由后续同键复用。
+- **回退**：下线路由与页面入口即可停止使用；已发布内容按既有 CLI / 后台下架流程处理，历史对象保留。

docs/project-memory/plans/【里程碑】AGC模板库客户端接入-2026-09-17.md

@@ -1,7 +1,7 @@
 # AGC 模板库客户端接入
 
 Version: 1.0
-Status: active
+Status: accepted（2026-09-21 复核：7 条验收项均有定向、前端与线上真连证据）
 Date: 2026-09-17
 Parent Spec: `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`
 
@@ -38,3 +38,17 @@ AGC 客户端能读取公共 OSS 上的游戏模板库，并把「浏览 → 筛
 - 现有自动工作区建项链路（`create_automatic_local_game_project_at` / `init_local_game_project_at`）。
 - 现有 AGC 更新通道使用的受信任 OSS 主机与 CSP 白名单口径。
 - 仓库 OSS 凭据（本机 `.env.secrets.local` 的 `ALIYUN_OSS_*`）与 `scripts/agc-template-library-publish.mjs`。
+
+## 验收证据（2026-09-21）
+
+| 验收项 | 证据 |
+| --- | --- |
+| 1 读清单 + 合并已安装状态 + 远端不可用回退缓存并标 `source=cache` | `template_library::tests::template_index_*` 5 项（网络优先并标 `network`、远端失败回退缓存并标 `cache`、无缓存暴露远端错误、远端正文非法不用缓存掩盖、缓存损坏失败关闭）；`fetches_the_live_template_library_index` 真连通过 |
+| 2 下载拒绝字节数 / SHA-256 / 越界键 / 非 `templates/` 前缀，且不落半成品 | `rejects_archive_when_size_or_digest_do_not_match_the_index`（含新增断言：拒绝后无安装目录、无已下载判据）、`rejects_object_keys_outside_the_templates_prefix`、`rejects_template_base_url_outside_trusted_oss`；`downloads_and_installs_a_live_template` 真连通过 |
+| 3 解压拒绝绝对路径 / `..` / 盘符 / 符号链接；安装完成才写 `installed.json` | `rejects_archive_entries_that_escape_the_destination`（含新增断言：失败后不产生安装记录）、`installs_template_archive_and_reports_it_as_installed`、`parses_content_addressed_objects_without_changing_the_template_contract` |
+| 4 建项具备模板文件 + `.agent` + 标准目录，失败不留项目目录 | `creates_project_from_installed_template_without_leaking_install_marker`、`installs_official_cocos_templates_and_creates_native_projects`、新增 `failed_project_creation_removes_the_partial_project_directory`、`refuses_to_create_project_when_template_is_not_installed`；`downloads_and_creates_live_cocos_templates` 真连通过 |
+| 5 页面筛选 / 卡片 / 已下载徽标 / 更新入口 / 浮层提示 / 版本落后先重下 | `templateLibraryView.test.tsx` 12 项、`templateLibraryModel.test.ts` 9 项、`templateLibraryGrid.test.ts` 6 项、`useTemplateLibrary.test.tsx` 11 项 |
+| 6 首页推荐位与左侧导航入口 | `appSurface.test.ts` 首页模板用例 2 项：灰度外隐藏入口与推荐位、点击推荐位进入模板库且不建项目 |
+| 7 定向用例 + 类型 / 编码 / 文档检查 + 可选真连 | Rust 24 项 + 线上 3 项、前端 38 项 + `appSurface` 2 项、AGC `typecheck`、`check:encoding`、`check:doc-index`、`git diff --check` 全部通过；匿名 `GET templates/index.json` 返回 200（`schemaVersion=agc-template-library.v1`、9 个模板） |
+
+仍未验证：Creator 内场景运行；真机 iOS / Android 观感。持久结论已并入主规范 [`【技术方案】AGC模板库与模板建项-2026-09-17.md`](../../technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)，本里程碑的实施计划已按工作流删除。

docs/project-memory/plans/【里程碑】AGC渠道安装身份隔离-2026-09-21.md

@@ -0,0 +1,44 @@
+# 里程碑：AGC 渠道安装身份隔离
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | 代码与源码级验收已落地，等待真机双渠道安装验收 |
+| Date | 2026-09-21 |
+| Parent Spec | `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md` |
+
+## 目标
+
+不同渠道的 AGC 包体在同一台设备上并存：安装、运行、客户端数据与更新互不覆盖、互不顶掉。
+
+## 范围
+
+- 构建期按渠道产出安装身份（`productName` / `identifier`），默认渠道 `dev` 身份保持不变。
+- 渠道产物命名、首装包选择、macOS 发布入口与配置门禁都消费同一份渠道身份。
+- 同机并存的可见区分（窗口标题）与 AGC 自有 AppData 目录的提权 ACL 识别范围。
+
+## 不在范围内
+
+- 不迁移、不共享既有本地项目、工程快照、模板、登录态与诊断数据。
+- 不新增渠道，不改 OSS 分区布局、官网下载页与后端接口。
+- 不做 Apple 代码签名/公证，不恢复 Intel 架构。
+
+## 依赖与前置条件
+
+- 渠道与更新端点合同已落地（`<channel>-win` / `<channel>-mac` 分区与 Tauri updater 端点）。
+- 构建入口统一在 Tauri 构建前注入渠道 `--config`。
+
+## 验收标准
+
+- [x] 默认渠道的 `productName` / `identifier` 与基线配置逐字一致，既有安装与升级链不断（`check-config.mjs` + 渠道身份用例）。
+- [x] `release` 与自定义渠道派生独立 `productName` 与 `identifier`，与 `dev` 可在同一台设备并存（源码级；真机安装见下方未完成项）。
+- [x] 渠道产物（NSIS `.exe`、`.app.tar.gz`、DMG）与首装包选择跟随渠道身份且唯一匹配（发布脚本用例）。
+- [x] 非默认渠道的客户端数据目录、WebView2 目录与窗口标题跟随渠道身份（构建产物字符串实测 + 运行期标题取产品名）。
+- [x] AGC 自有 AppData 目录的 ACL managed 范围覆盖全部渠道身份，且不扩大到相似前缀目录（Rust 定向 12/12）。
+- [ ] 真机：同一台设备同时安装 `dev` 与 `release`，二者可并存、可各自原地更新。
+
+## 证据要求
+
+- 自动化：`build-release.test.mjs`、`release-oss.test.mjs`、`prepare-macos-codex.test.mjs`、`check-config.mjs` 与 Rust `config::tests::` 定向测试。
+- 运行时：单渠道 `--no-bundle` 构建烟测；真机双渠道安装、并存与各自更新。
+- 边界：非法渠道失败关闭；默认渠道身份不变；相似前缀目录不进入 managed 赋权范围。

docs/project-memory/plans/【里程碑】后台模板上传-2026-09-21.md

@@ -0,0 +1,73 @@
+# 后台模板上传
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | implemented-awaiting-runtime-acceptance（接口、页面与定向用例已交付；真实 dev bucket 写入 smoke 未执行） |
+| Date | 2026-09-21 |
+| Parent Spec | `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md` |
+
+## 目标与范围
+
+管理员在后台直接上传模板并发布到公共模板库，不必走本地 CLI；一批可以带多个模板（批量上传），一批只做一次发布锁和一次清单提交。
+
+- 新增 `POST /admin/api/agc-templates/import`（`multipart/form-data`）：`manifest` 文本字段 + `zip_<index>` / `cover_<index>` 文件字段，字段下标与 manifest 条目顺序一一对应。
+- manifest：`{ expectedRevision, templates: [{ id, title, summary, tags, runtime, engine, engineVersion, entry, templateVersion }] }`；`expectedRevision` 是当前清单字节 SHA-256，用于锁内 CAS。
+- 限制：单批最多 20 个模板；单个 ZIP ≤ 64 MiB；单张封面 ≤ 5 MiB；请求体 ≤ 200 MiB；`id` / `templateVersion` / `entry` 走既有标识符与相对路径白名单；`runtime` 仅接受 `html / unity / godot / cocos`。存储层为 `application/zip` 单独放宽单对象上限到 64 MiB（图片与元数据仍是 5 MiB）。
+- 语义：一批**全有或全无**——任一模板校验失败都在写入前整批拒绝并逐项给出原因；通过后在同一把发布锁内写入全部内容寻址对象、逐个回读校验，最后提交一次清单。
+- 新 ID 默认上架；已存在 ID 的导入就地更新该条目（保留 `enabled` 状态、所属分组与未知扩展字段，包含下架条目）；同一 ID 同一 `templateVersion` 但 ZIP 字节不同时拒绝，提示递增 `templateVersion`。
+- ZIP 由服务端校验后按原字节发布（不重新打包、不解压落盘）：合法 zip、无符号链接、无绝对路径 / `..` / 盘符条目、必须包含声明的 `entry`、至少一个文件，条目数与解压后体积受上限保护；正文含 `.agent` / `.git` / `.svn` / `node_modules` 段（任意层级）或根目录 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode` 的包直接拒绝，与 CLI 打包同一份段名单。
+- 封面**每个模板必填**（与 CLI 源布局 `v1/<id>/cover.*` 一致），仅接受真实 PNG / JPEG / WebP，上限与编辑路径相同（5 MiB、单边 4096、1600 万像素）；上传按字节嗅探格式，不信任 multipart 声明的 content-type。SVG 仍只可能来自 CLI 历史发布，编辑与上传都不产生新的 SVG 封面。
+- 后台「模板管理」页新增上传入口：可多选 ZIP、逐行编辑元数据（含可选封面）、批量提交、逐行显示校验错误；沿用现有写入确认、防重复提交与刷新语义。
+
+## 不做
+
+- 不做模板删除、版本回滚、下架条目清理、历史对象回收。
+- 不改 ZIP 内容、不做服务端重新打包（CLI 仍是确定性打包与 `--only` 定向发布的入口）。
+- 不做审核流、不做从 URL 拉取、不做 CLI 源布局目录（`v1/<id>/{meta.json,project/**,cover.*}`）的自动打包上传。
+- 不新增 SpacetimeDB 表或 schema。
+
+## 合同与依赖
+
+- 存储与锁：复用 `platform-oss` 的 `TemplateLibraryStore` / `TemplatePublishSession`（`begin_publish` / `read_index` / `put_immutable` / `commit_index` / `finish`）与既有版本控制前置检查；不新增第二套发布协议。
+- 领域规则：`module-assets/template_library.rs` 承担清单合并与字段校验（保留未知字段、下架状态、两组间 ID 唯一），沿用既有标识符 / 相对路径 / 摘要规则。
+- DTO：`shared-contracts/admin.rs` 新增导入结果类型；前端类型在 `apps/admin-web/src/api/adminApiTypes.ts`。
+- 鉴权：沿用后台认证与 `agc-templates` 页签权限；路由挂载在 `modules/admin.rs`。
+
+## 验收标准
+
+1. 权限与路由：未授权读取/写入均失败关闭；无 `agc-templates` 页签权限不可导入；路由契约测试覆盖新路径与方法。
+2. 校验失败关闭：manifest 非法、ID/版本/entry 越界、runtime 不在白名单、ZIP 非法或含越界/符号链接条目、缺少 entry、封面超限或非真实图片，全部在**任何写入之前**整批拒绝，响应逐项给出模板 ID 与原因。
+3. 批量原子性：一批 3 个模板（含 1 个新 ID、1 个新版本、1 个下架 ID）在锁内一次提交；中途任一环节失败时清单与历史对象不变，返回可诊断错误。
+4. 版本一致性：同 ID 同版本、ZIP 字节不同必须拒绝并要求递增版本；同 ID 同版本、字节完全一致视为幂等复用，不报错。
+5. CAS 与锁：`expectedRevision` 过期返回 409；锁被占用返回 409；清单写入结果不明时保留锁并返回 503，不自动重试。
+6. 保留语义：既有条目的展示字段按上传内容更新，`enabled` 分组、其它条目、未知扩展字段与历史对象不变；下架条目仍留在 `inactiveTemplates`。
+7. 内容寻址与回读：ZIP / 封面 / template.json 以自身字节摘要寻址，写入后逐项回读校验，清单最后提交且返回最新快照。
+8. 界面：桌面与窄屏都能完成多选 ZIP、逐行元数据编辑、批量提交与错误展示；保存中防重复提交，409 引导刷新后重试。
+9. 检查：`cargo test`（module-assets / platform-oss / api-server 定向）、`npm run admin-web:typecheck`、后台页面 vitest、`npm run check:encoding`、`npm run check:doc-index`、`cargo fmt --check`、`git diff --check` 全部通过。
+
+## 依赖
+
+- 已交付的后台模板管理链路（`GET/PUT /admin/api/agc-templates`、页面、锁与内容寻址发布协议）。
+- 模板库 OSS 写凭据（`GENARRATIVE_AGC_TEMPLATE_LIBRARY_OSS_ACCESS_KEY_ID/SECRET` 或成套 `ALIYUN_OSS_*`）；无凭据时导入返回 503 且页面明确不可用。
+- 真实 dev bucket 的写入验证需要用户显式确认（见实施计划「验证」）。
+
+## 实现与证据（2026-09-21）
+
+| 验收项 | 证据 |
+| --- | --- |
+| 1 权限与路由 | 路由契约测试覆盖 `POST /admin/api/agc-templates/import`；页签权限矩阵用例覆盖 GET / PUT / POST 三条路径（`admin::tests::agc_template_routes_require_the_template_tab_permission`） |
+| 2 校验失败关闭（写入前整批拒绝） | `template_import_archive_validation_fails_closed`（缺 entry / 越界路径 / 符号链接）、`template_import_plan_rejects_unknown_and_unreferenced_fields`（未引用字段、缺 ZIP 字段、字段前缀、未知 manifest 字段、非法 zip）、`template_import_archive_rejects_identity_and_build_directories`（13 条身份 / 版本库 / 依赖 / 构建目录逐条拒绝 + 正文内 `game/dist/**`、`game/.gitignore` 放行） |
+| 3 批量原子性 | `module-assets` 的 `template_import_appends_new_entries_with_metadata`（3 条口径：新 ID 入 `templates`、下架条目留在 `inactiveTemplates`、未知字段保留）；发布编排在锁内写完全部对象后才提交一次清单 |
+| 4 版本一致性 | `template_import_rejects_same_version_with_different_bytes`（同句文案）、`template_import_reuses_identical_bytes_for_the_same_version`（`reused`） |
+| 5 CAS 与锁 | `import_templates` 复用 `check_revision`（409）与 `TemplatePublishSession`（`commit_index` 不确定即留锁 → 503）；存储层既有用例覆盖锁与不确定写入 |
+| 6 保留语义 | 领域用例断言 `enabled` 分组、`extension` 未知字段与 `metadataKey` 保持不变 |
+| 7 内容寻址与回读 | `template_import_plan_uses_content_addressed_keys_and_sniffed_cover`；`put_immutable` 逐个回读校验 |
+| 8 界面 | 页面用例：多选 ZIP 生成行、封面匹配齐才可提交、确认后提交 manifest 与文件、成功后刷新列表、409 刷新引导、400 展示真实原因（共 40 项 vitest 通过） |
+| 9 检查 | `cargo test`（module-assets 11、platform-oss 12、api-server 定向 4）、`npm run admin-web:typecheck`、`check:encoding`、`check:doc-index`（193 份）、`cargo fmt --check`、`git diff --check` 全部通过 |
+
+仍未执行：真实 `agc-dev` bucket 的批量写入 smoke（需要用户显式确认；建议用两个 `smoke-import-<时间戳>` 模板验证一批多模板 + 一次清单提交，验证后下架保留历史对象）。
+
+## 追加：模板正文目录门禁（2026-09-21）
+
+验收标准 2 的补充落地——把「不要放进 ZIP」从文档约定升级为机器门禁，CLI 与后台上传同一份段名单（任意层级 `.agent` / `.git` / `.svn` / `node_modules`，根目录 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode`）。证据：Rust `admin_templates` 8 项通过（含新增 `template_import_archive_rejects_identity_and_build_directories`）；Node 发布回归 28 项通过（含新增 CLI 门禁用例）；仓库 9 个模板源无一条命中，本地重打包 ZIP 摘要与线上清单 `zipSha256` 逐条一致。规则说明见 `docs/【模板规范】AGC模板包组织指南-2026-09-21.md`。

docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md

@@ -23,7 +23,7 @@
 
 - [ ] 正式项目窗口可被同步调度识别；周期与关闭触发保持有界，失败有项目级诊断。
 - [ ] 未单独配置快照目标时仍使用 agc-dev，只复用资源存储凭据；显式快照目标保持有效，不迁移现存对象。
-- [ ] 后台列表显示项目名/ID、用户 ID、同步时间、文件数、体积和完整性，支持刷新与分页。
+- [ ] 后台列表按部署渠道查询，显示项目名/ID、用户（昵称 + 陶泥号）、同步时间、文件数、体积和完整性，支持刷新与游标分页（每页 20/50/100 + 上一页/下一页）。
 - [ ] ZIP 按清单还原相对路径；不含对象存储摘要目录；空文件可上传与导出。
 - [ ] 清单名称/完整性变化在无内容差异时也提交，partial 可恢复 ready，历史缺字段不冒充 ready。
 - [ ] 缺失、损坏、越界路径和非完整清单失败关闭；历史未声明完整性的清单明确标记，允许导出已有文件但不称为完整工程。

docs/project-memory/shared-memory/decision-log.md

@@ -1,5 +1,70 @@
 # 决策记录
 
+## 2026-09-21 渠道进安装身份：不同渠道的 AGC 包体在同一台设备并存
+
+- 背景：渠道此前只决定更新端点（`plugins.updater.endpoints`）与渲染层平台 origin，`productName` / `identifier` 与渠道无关，于是所有渠道共用 `%LOCALAPPDATA%\陶泥儿` 安装目录、同一个卸载项（`HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\陶泥儿`，另有 `HKCU\Software\genarrative\陶泥儿`）以及同一份 `%APPDATA%\world.genarrative.ai-game-creator` 数据目录。本机 0.1.48 安装实测：主程序二进制里只有 1 处 `agc/dev-win/latest.json`、0 处 release 端点，说明渠道在产物里只体现为端点。后果是后装的渠道静默顶掉先装的渠道，并接管更新端点、平台服务器与本地登录态/项目数据。
+- 决策：渠道同时决定**安装身份**。默认渠道 `dev` 保持基线 `productName = 陶泥儿`、`identifier = world.genarrative.ai-game-creator`（既有安装目录、卸载项与升级链不断）；其它渠道派生 `陶泥儿 <渠道显示名>`（`release` → `陶泥儿 Release`）与 `world.genarrative.ai-game-creator.<渠道>`。身份与更新端点必须在同一个构建期 `--config` 里注入，禁止分别回读默认值。窗口标题、macOS 产物名（`.app` / updater 归档 / DMG 卷名）、首装包选择与 Windows 提权 ACL 的 managed 识别范围同批跟随该身份。
+- 边界：不做本地数据迁移或共享——切渠道等于换一个客户端；`release` 与自定义渠道首次以新身份安装，不接管、不迁移既有 `dev` 安装与本地项目，由用户自行决定是否卸载其一。
+- 影响范围：新增 `apps/ai-game-creator-shell/scripts/channel-identity.mjs`；`build-release.mjs`、`build-macos-ci.mjs`、`check-config.mjs`、`agent-swarm-test-chat.mjs`、`src-tauri/src/{main.rs,windows.rs,config.rs}` 与对应测试；主规范 `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`。
+- 验证方式：`node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs release-oss.test.mjs prepare-macos-codex.test.mjs cargo-features.test.mjs`（64/64，新增渠道身份与渠道 DMG 首装选择用例）、`node apps/ai-game-creator-shell/scripts/check-config.mjs`（基线等于默认渠道身份、非默认渠道身份隔离）、`cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell -- config::private_path_elevation_policy_tests`（12/12，含基线/`<基线>.release`/`<基线>.beta-2` 与相似前缀反向断言）、`AGC_UPDATE_CHANNEL=release npm --prefix apps/ai-game-creator-shell run build -- --no-bundle --debug`（产物字符串实测 `陶泥儿 Release` × 1、`agc/release-win/latest.json` × 1、`world.genarrative.ai-game-creator.release` × 1、`agc/dev-win/latest.json` × 0）。真机双渠道安装、并存与各自更新尚未执行，按未验证项记录。
+
+## 2026-09-21 项目快照按部署渠道分区，后台按渠道查看并按素材查询口径展示用户
+
+- 背景：AGC 项目快照此前统一写在 `agc/project-snapshots/v1/{user}/{project}/`，而开发与正式两套部署共用同一个 bucket（都默认 `agc-dev`）。结果是渠道混在一层前缀里：正式后台会列出开发渠道上传的项目，列表上也看不出项目属于哪个渠道；同时“项目工程”列表只有裸用户 ID，且用“加载更多”逐段追加，翻页与定位都困难。
+- 决策（存储）：对象键升级为 `agc/project-snapshots/v2/{channel}/{user}/{project}/`。渠道是**部署渠道**，由服务端 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL` 决定（缺省沿用 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`，当前缺省 `dev`），客户端不上报渠道、也不需要发新版；渠道名必须是小写字母开头的 `[a-z0-9-]{1,32}`，非法值在上传与后台查询处失败关闭（`503`/`400`），不悄悄回落。正式部署必须在 api-server 环境里显式写 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL=release`。
+- 决策（后台）：新增 `GET /admin/api/project-snapshots/channels` 返回本部署渠道与远端已存在渠道的并集；列表与下载接口都接受 `channel`（缺省本部署渠道），游标里带上渠道并在解码时校验一致，跨渠道复用游标一律 400。页面顶部提供“渠道”选择框，切换渠道回到第 1 页。
+- 决策（列表形态）：“用户 ID”列改为与“素材查询”同口径的“用户”列——昵称 + 陶泥号 + 用户详情入口，昵称/陶泥号由 api-server 用 `resolve_work_author_by_user_id` 解析（账号不可读时回退占位作者），原始 `userId` 不再直接铺在列里；“加载更多”改为游标分页（每页 20/50/100 + 上一页/下一页 + 当前页），前端按页记录游标链，换令牌或换每页条数从第 1 页重来；翻页失败保留当前页。
+- 原因：渠道属于“这套部署服务哪个客户端渠道”，客户端正式包按构建渠道连接不同平台服务（release → 正式站，dev → 开发站），所以服务端是唯一可靠的渠道来源；把渠道放进对象键第一层，既不需要迁移历史对象就能让两套部署互不可见，也让后台的渠道维度天然对齐存储布局。
+- 影响范围：`server-rs/crates/platform-oss/src/{lib.rs,project_snapshots.rs,template_library.rs,examples/agc_project_snapshot_live_smoke.rs}`、`server-rs/crates/api-server/src/{config.rs,project_snapshots.rs,admin_project_snapshots.rs,modules/admin.rs}`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/{api/adminApiClient.ts,api/adminApiTypes.ts,pages/AdminProjectSnapshotsPage.tsx,pages/AdminProjectSnapshotsPage.test.tsx,styles/admin.css}`、`deploy/env/api-server.env.example` 与本仓运维/技术文档。
+- 未迁移的历史对象：`agc/project-snapshots/v1/` 下现存对象（只读核对过的两份历史清单）保留在 OSS，但不再写入、不再进入后台列表；需要取回时按旧前缀在 OSS 侧直接读取，确实要在后台看到时再单独开一个只读兼容视图。
+- 验证方式：`cargo test -p platform-oss snapshot` 7 passed（渠道校验、键布局、v2 根渠道枚举、v1 历史键仍必须私有）；`cargo test -p api-server project_snapshot` 18 passed/1 ignored（渠道失败关闭、游标跨渠道拒绝、用户昵称/陶泥号解析、归档与配额回归）；`cargo test -p api-server protected_route_matrix`、`route_contract` 通过（新路由纳入后台鉴权矩阵）；`npm run admin-web:typecheck` 与 `npx vitest run apps/admin-web/src` 202 passed。
+
+## 2026-09-21 Godot 模板入库与按模板建项的 Godot 分流
+
+- 背景：模板库此前只有网页（html）、Cocos 与 Unity 占位，`runtime` 白名单早就接受 `godot`，但既没有 Godot 模板，也没有按模板建项的 Godot 分流——Godot 模板即使上传，建项也会落到 Web 分支，写出 `game/index.html` 占位入口并让 `godotProjectRoot` 为空。
+- 决策（模板内容）：新增四个仓库内手写的 Godot 4.7 模板 `godot-empty-2d`、`godot-empty-3d`、`godot-hello-world`、`godot-platformer-2d`，`entry` 统一为 `project.godot`。模板只用内置 `ui_*` 输入动作、GL Compatibility 渲染，并用 `Polygon2D` / `BoxMesh` 搭可视骨架，不引入外部贴图或音频二进制；不打包 `.godot/` 缓存与导出产物。
+- 决策（建项分流）：`create_project_from_installed_template_at` 在复制模板后按工程文件分流——Cocos 更新自身身份后走 Cocos 导入，Godot 先改写 `project.godot` 里 `[application]` 段的 `config/name`（只改这一行，其余字节逐字保留）再走既有 Godot 导入，写入 `godotProjectRoot: "."`，其余继续走 `init_local_game_project_at`。分流靠工程文件识别，不新增只读 `entry` 或 `runtime` 字段的契约。
+- 原因：Godot 工程身份是 `project.godot` 所在目录，与 Cocos 的 `package.json` 身份同一类问题；复用既有导入流程能同时拿到相对根记录、`.agent` 初始化与「不生成 Web 占位入口」这三条既有保证，并且与 Cocos 分支保持对称。
+- 影响范围：`apps/ai-game-creator-shell/template-library/v1/godot-*`（新增模板源）、`apps/ai-game-creator-shell/src-tauri/src/template_library.rs`、`.../src/project/manifest.rs`（`apply_godot_project_display_name`）、`.../src/project/manifest/import_tests.rs`、`docs/【模板规范】AGC模板包组织指南-2026-09-21.md`、`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`。
+- 验证方式：本机 Godot `4.7.2.stable` 对四个模板逐一做「主场景实例化 + 3 帧 + GDScript `--check-only`」，平台跳跃模板另做真实物理试玩（落地 y=627.99、1 秒右移 320px、跳上平台 y=515.93、三枚金币全收集）；Rust 定向回归 `import_tests::rewrites_only_the_godot_display_name_line`、`import_tests::keeps_a_godot_project_without_a_display_name_line_untouched`、`template_library::tests::godot_template_creates_native_project_with_relative_root_and_display_name` 与既有 Cocos/Web 建项回归；发布走 `--only godot-*` 定向合并。
+
+## 2026-09-21 Godot 工作区发现放宽与内置插件行去掉手动启动
+
+- 背景：2026-08-10 “发现与歧义决策”把「一层多命中」和「`project.godot` 必须是普通文件」两条定为失败关闭。这两种布局都会让整个工作区被判成「没有 Godot 工程」，而 `PluginHost::list` 只按发现结果过滤，结果是 Godot 内置插件在设置→扩展 里直接消失，用户看不到任何可诊断入口。
+- 决策（发现）：根目录命中仍然优先；根未命中时一层直接子目录多命中改为按目录名排序取第一个，`godotProjectRoot` 记录该相对目录名，结果确定且可复现。`project.godot` 允许是符号链接 / Windows reparse point / 硬链接，判据改为「链接目标解析后是文件」，目录与悬空链接仍不算命中。工作区根本身是链接、候选子目录是链接、二层及更深不递归这三条边界不变。
+- 决策（界面）：设置→扩展 的内置插件行去掉手动「启动 / 停止」按钮。启动本来就由项目切换时的 `startAvailableAgcEditorPlugins` 自动完成，手动按钮只是第二个可绕过入口；停止改走该行的启用/禁用开关，`set_agc_plugin_enabled(false)` 会停止插件并断开编辑器连接。导入扩展行的启动按钮保留，因为导入扩展没有自动启动路径。
+- 原因：Godot 插件列表是按项目过滤的，发现失败等于功能静默消失；把不确定性收敛成一个确定的排序选择，比让用户面对空列表更好。链接放宽只作用于只读的工程标记文件，受管描述文件、运行缓存与项目目录的链接拒绝规则不动。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs`、`.../src/commands.rs`（错误文案）、`.../src/project/manifest/import_tests.rs`、`.../src/tests/project.rs`、`apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md` §3.8、`docs/technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+- 验证方式：`cargo test --locked -p genarrative-ai-game-creator-shell --bin genarrative-ai-game-creator-shell -- project::manifest::import_tests::` 与 `-- tests::project::`；前端 `agc:typecheck` 与 `runtime-settings` / `pluginHost` 套件。
+
+## 2026-09-21 模板正文目录门禁：CLI 打包与后台上传同一份段名单
+
+- 背景：模板包组织指南把 `.agent/`、`.git/`、`node_modules/`、根目录 `dist/` 等列为「不要放进 ZIP」，但两条发布路径此前只校验路径安全与 `entry` 是否存在，放进去的东西会跟着建到用户项目里（模板自带 `.agent/` 会让新项目继承一个陌生身份）。这条约定只靠作者自觉。
+- 决策：升级成机器门禁，CLI（`readProjectFiles`）与后台上传（`validate_import_archive`）用同一份段名单与同一句文案——任意层级拒绝 `.agent` / `.git` / `.svn` / `node_modules`，根目录拒绝 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode`。同名目录段只在根目录受限：正文内 `game/dist/**` 是模板自身内容；`.gitignore` 不等于 `.git`，Cocos 模板的 `.creator` / `.gitignore` 不受影响。
+- 原因：两类目录性质不同。`.agent/`、`.git/`、`.svn/`、`node_modules/` 放哪一层都是错的，进包即污染用户项目；而 `dist` / `library` / `temp` 这类只说明「作者把编辑器缓存或构建产物当成了模板内容」，出现在根目录才是信号，全面禁止会误伤工程内的正常同名目录。
+- 影响范围：`scripts/agc-template-library-publish.mjs` 及其测试、`server-rs/crates/api-server/src/admin_templates.rs`、`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`、`docs/【模板规范】AGC模板包组织指南-2026-09-21.md`、`docs/project-memory/plans/【里程碑】后台模板上传-2026-09-21.md`。
+- 验证方式：`node --test scripts/agc-template-library-publish.test.mjs`（28 项，新增 1 项：13 条拒绝用例 + `game/dist/**` 与 `game/.gitignore` 放行断言）；`cargo test --locked -p api-server admin_templates`（8 项，新增 `template_import_archive_rejects_identity_and_build_directories`）；仓库现有 9 个模板源无一条命中，本地重打包的 ZIP 摘要与线上清单 `zipSha256` 逐条一致；`cargo fmt --check`、`check:encoding`、`check:doc-index`、`git diff --check` 通过。
+
+## 2026-09-21 后台模板上传：成品 ZIP + 每模板封面，批量全有或全无
+
+- 背景：模板发布此前只有本地 CLI（源目录 + 确定性打包 + `--only`），后台上传需要一条不依赖本地仓库的通道，并支持一次提交多个模板。
+- 决策（输入形态）：后台上传**成品 ZIP**（库内字节原样发布，不重新打包），每个模板必须同时给一张 PNG/JPEG/WebP 封面（与 CLI 源布局 `v1/<id>/cover.*` 一致），`id/title/templateVersion/runtime/entry` 由页面逐行确认；简介、标签与引擎上传后用编辑接口补齐。服务端按字节嗅探封面格式，不信任 multipart 声明的 content-type。
+- 决策（批量语义）：一批 = 一把发布锁 + 一次清单提交，**全有或全无**；任一模板的 manifest/归档/封面不合法都在写入前整批拒绝并逐项给出原因。单批上限 20 个模板、单包 64 MiB、单封面 5 MiB、请求体 200 MiB。
+- 决策（校验与安全）：归档只校验不落盘——合法 zip、无符号链接、无绝对路径 / `..` / 盘符条目、必须包含声明的 `entry`、条目数 ≤ 4096 且解压后 ≤ 512 MiB。
+- 决策（版本与保留）：新 ID 默认上架；已存在 ID 就地更新并保留 `enabled` 分组、其它条目与未知扩展字段；同一 ID 同一 `templateVersion` 的 ZIP 字节不同时拒绝并要求递增版本，字节一致时按内容复用（`reusedObjects`）。
+- 决策（存储契约）：`platform-oss` 的 `put_immutable` 为 `application/zip` 单独放宽到 64 MiB（此前只有 json/图片的 5 MiB），图片与元数据上限不变。
+- 影响范围：`server-rs/crates/{shared-contracts/api-server/module-assets/platform-oss}`、`apps/admin-web/src/{api,pages,styles}`、模板库技术方案与 `docs/project-memory/plans/【里程碑】后台模板上传-2026-09-21.md`。
+- 验证方式：`cargo test`（module-assets 11、platform-oss 12、api-server 定向 4）、`npm run admin-web:typecheck`、后台页面与模型 40 项 vitest、`check:encoding`、`check:doc-index`、`git diff --check`；真实 dev bucket 写入验证需用户显式确认。
+
+## 2026-09-21 模板库线上产物对齐仓库源：递增版本重发 + 说明文档纳入发布
+
+- 背景：`agc-dev` 上的 `templates/` 产物停在 2026-09-17 发布的那一版，仓库源在那之后改过（`5e4ff54a9` 删掉模板内嵌 `package-lock.json`、`game.js` / `main.js` 等内容调整），9 个模板里 7 个的 ZIP 与线上不一致；dry-run 被「同一 `templateVersion` 的 ZIP 不得变」门禁拒绝，发布器因此无法把仓库状态发上去。
+- 决策：按门禁要求为内容已变的 7 个模板递增 `templateVersion` 到 `0.1.1`（`blank-2d-canvas`、`blank-web` 内容未变，保持 `0.1.0`），并完成一次真实发布；对象使用内容寻址键 `v1/<id>/sha256/<摘要>/…`，`index.json` 与说明文档在发布锁内最后提交，历史对象不删除。
+- 决策（说明文档）：`templates/README.md` 不再是手工副本——它由发布脚本从仓库源 `apps/ai-game-creator-shell/template-library/README.md`（≤64 KiB）覆盖写入并回读校验，写在清单之前；改契约只改仓库源。
+- 决策（CLI 行为）：发布器遇到门禁拒绝时用 `process.exitCode = 1` 正常退出，不再 `process.exit(1)` 让 Node 在 fetch 句柄未关闭时抛 libuv 断言（此前现场只剩 `Assertion failed`，看不到拒绝原因）。
+- 影响范围：`apps/ai-game-creator-shell/template-library/v1/*/meta.json`、`apps/ai-game-creator-shell/template-library/README.md`、`scripts/agc-template-library-publish.mjs` 与其测试、本文件与模板库技术方案。
+- 验证方式：`node --test scripts/agc-template-library-publish.test.mjs`（27 项，含新增「说明文档随发布覆盖写且写在清单之前」「源目录没有 README 时不写线上文档」）；真实发布 28 个对象回读通过；匿名读取线上清单（9 个模板、7 个 `0.1.1`、全部内容寻址键）与 `templates/README.md`（与仓库源逐字节一致）；AGC 壳 3 项线上用例（读清单、下载安装、下载并原生建项 Cocos）重跑通过。
+
 ## 2026-09-21 macOS 发布改为只出 arm64 单架构（Intel 暂不支持）
 
 - 背景：Mac 发布管线按 `universal-apple-darwin` 构建，但随包 Node 便携运行时只有**单架构官方发行版**（`stage-node-runtime.mjs` 从 `process.execPath` 取材），于是 macOS Job #7~#13 连续失败在「Node 运行时不支持发布目标：universal-apple-darwin」。期间出现过一版「按宿主架构放行」的过渡实现，它能骗过通用包自检（`check-macos-bundle.mjs` 按 `process.arch` 校验），但 Intel 上那份 arm64 侧车不可执行，并且已发布的 dev-mac 0.1.86 就带着这个缺陷。
@@ -8211,7 +8276,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 ## 2026-08-10 AGC 打开现有 Godot 项目
 
 - 项目双根决策（2026-08-14 更新）：项目组只保留通用“打开项目 / 新建项目”，不再提供独立 Godot 入口。用户选择目录始终是工作区根，也是 `.agent`、Session、Runner、沙箱、通用文件工具和外围资料的唯一授权根；实际 Godot 根由根目录或一层直接子目录中的普通文件 `project.godot` 唯一确定，并以工作区相对 `godotProjectRoot` 记录，根目录使用 `.`。不得把 Runtime 根切换成 Godot 子目录，也不得复制工程或建立第二套工作区。
-- 发现与歧义决策：根目录命中优先；根未命中时只检查一层直接子目录，唯一命中才通过，多个命中在任何 `.agent` 写入前失败关闭。候选目录与工程文件拒绝符号链接和 Windows reparse point，二层及更深不递归。未来只有 Godot 专属命令显式使用经过校验的相对 Godot cwd。
+- 发现与歧义决策：根目录命中优先；根未命中时只检查一层直接子目录，唯一命中才通过，多个命中在任何 `.agent` 写入前失败关闭。候选目录与工程文件拒绝符号链接和 Windows reparse point，二层及更深不递归。未来只有 Godot 专属命令显式使用经过校验的相对 Godot cwd。（2026-09-21 部分取代：多命中改为按目录名排序取第一个，`project.godot` 允许链接并按目标判定；候选子目录与更深层的边界不变，见本文件「2026-09-21 Godot 工作区发现放宽与内置插件行去掉手动启动」。）
 - 元数据决策：首次导入只在工作区根创建并保留 `.agent/manifest.json`、`.agent/agent.db`、`.agent/logs/` 与 `.agent/runtime/`；不得创建默认 Web 原型的 `game/`、`assets/`、`memory/`、`exports/`。已有有效 `.agent` 项目继续复用身份；缺失或错误的可推导 `godotProjectRoot` 只在 Godot 打开边界按唯一文件布局校准，歧义时不改写。
 - Windows 锁文件决策：提升权限进程新建 `.agent/.manifest.json.lock` 时，Windows 可能把 owner 设为 `Administrators`。仅在固定锁路径已取得不共享独占句柄并确认是普通、非 reparse、单链接文件后，才初始化为当前 `TokenUser`；随后再次复核句柄并执行原有 owner/DACL 校验，不放宽既有异常对象的安全规则。
 - 运行决策：Godot 项目提交给 Project Supervisor 时使用 `standard` Run Profile，避免触发 Web 专用 `game/index.html`、HTTP preview 与自主 Web 完成门。Godot 编辑器启动和内嵌运行预览不在本切片范围。
@@ -8988,7 +9053,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（矩阵）：`ui-interaction` = 生成图片 / 生成规范（图标规范、自定义规范）/ 生成图标素材 / 生成 UI 设计图 / 上传；`character` = 生成图片 / 生成规范（角色规范、自定义规范）/ 生成角色形象 / 上传；`scene` = 生成图片 / 生成规范（自定义规范）/ 上传；`audio` = 生成背景音乐 / 生成音效 / 上传。文档、待归类、项目版本、「所有资源」展开态与资源总览**不渲染**工具栏（`resolveResourceCanvasBottomTools` 返回空数组，渲染判据 `resourceBookState.view === 'child'` 且 category 命中四个栏目）。工具项与顺序是纯数据表，事实源落在 `resourceCanvasBottomToolbarModel.ts`。
 - 决策（落点与几何）：工具栏是 `.game-resource-book-manager` 的**直接子节点**（与画本场景、右下 Dock、通知条并列，不进带 `scale()` 的场景层），锚在**左下角**（`left/bottom: 14px; z-index: 40`）——右下角是既有缩放 / 撤销 Dock，左下角是画布上唯一两者都不占的稳定空位；外壳消费共享 `packages/image-canvas-react` 的 `CanvasToolbar / CanvasToolbarGroup / CanvasChromeButton`（AGC 侧第一次真正消费这组共享 chrome）。一处必要覆盖：共享 `.genarrative-image-canvas__toolbar` 是横向滚动容器，会裁掉它自己弹出的二级菜单，消费端改成 `overflow: visible` + `flex-wrap: wrap`。
 - 决策（接线与收敛）：图片类入口 `generate_local_project_asset`（kind 映射：图片 `image` / 角色形象 `character` / 图标规范 `icon-spec` / 角色规范与自定义规范 `spec` / 图标素材 `art-spritesheet` / UI 设计图 `ui-prototype`）；音频入口复用既有 `derive_local_project_resource` 无源生成链路（**不另写一份音频生成**）；上传复用 `upload_local_asset`。两者成功后的刷新形状统一为「**配对读 `(revision, manifest)`** → `onManifestChange` → `pendingResourceFocusRef` 定位新卡」，不重算依赖图、不另写布局。**音频入口收敛**：既有「生成素材」浮层入口改为只保留视频（`ResourceCanvasGenerationPanelView` 新增 `kinds` prop，单类型入口不再渲染类型选择器，面板标题与提交文案跟类型走），视频能力不删只是不进工具栏。
-- 决策（参数口径，避免假控件）：比例 / 尺寸选项与默认值复用网页端纯模型 `ImageCanvasGenerationModel.ts`，但按本地 IPC 白名单收窄（本地通道明确拒绝 `4:3`，照搬就是一个点了必失败的选项）；提示词上限复用 `resourceEditPromptMaxLength`（32000，与 Rust `LOCAL_PROJECT_ASSET_MAX_PROMPT_CHARS` 同口径）；**面板不渲染模型选择器**（本地 IPC 没有 `model` 入参）。规范入口是固定档：只读展示规格，不给点了不生效的比例控件。
+- 决策（参数口径，避免假控件）：比例 / 尺寸选项与默认值复用网页端纯模型 `ImageCanvasGenerationModel.ts`，但按本地 IPC 白名单收窄（本地通道明确拒绝 `4:3`，照搬就是一个点了必失败的选项）；图标素材描述去除首尾空白后最多 `200` 个 Unicode 字符，作为唯一 `iconDescriptions` 元素原样提交，不包装、截断或拆条；其余图片提示词上限为 `32000`，前端与 Rust 原生校验保持一致；**面板不渲染模型选择器**（本地 IPC 没有 `model` 入参）。规范入口是固定档：只读展示规格，不给点了不生效的比例控件。
 - 决策（前置规范图，本轮的关键设计）：`ui-prototype` 与 `art-spritesheet` 在 Rust 侧要求项目里已有登记并绑定当前账号的 `assets/art-spec.png`（`local_path` 精确匹配 + `kind == icon-spec` + 图片媒体类型 + 画布来源）。前端判据 `projectHasIconSpecReference` 与它逐字对齐；缺前置时入口**保持可点击**并给可执行原因（`aria-disabled` 而非原生 `disabled`，文案含 `assets/art-spec.png` 与「生成规范 → 图标规范」），且零生成请求。**同时**把「图标规范」入口在缺前置时按 `assets/art-spec.png` 落盘（`outputPath`），否则那两条入口会被前置条件永久锁死、工具栏自身无法满足自己的前置；已有权威规范图时不再传 `outputPath`（Rust `replace_existing` 固定 `false`，指向已存在文件会被硬拒），改为生成一张新的普通图标规范资产。这条是**前端策略**，不扩接口。
 - 已知能力缺口（用户口径是「缺参数就停下汇报，不自行扩接口」，记账备查）：本地 IPC 没有 ① `model` ② `specType` ③ `replaceExisting` 入参。后果：面板不给模型选择；**角色规范与自定义规范共用 `spec` 通道**（靠 `assetName` / 提示词区分），因此「角色规范」不是真正的角色设定板通道；权威规范图存在时无法重写它。另：网页端 composer 子视图（含 `ImageCanvasSpecGenerationPanelView` 直连 `/api/editor/llm/icon-specs/*`）**没有复用**，因为 AGC 无该 BFF 通道且本地 IPC 不接受模型 / 参考图入参，照搬会渲染改不了请求的控件——本轮只把**纯模型**接进来。
 - 影响范围：`apps/ai-game-creator-shell/src/features/resource-canvas/{resourceCanvasBottomToolbarModel.ts,ResourceCanvasBottomToolbarView.tsx,ResourceCanvasAssetGenerationPanelView.tsx,ResourceCanvasGenerationPanelView.tsx,resourceCanvasChrome.css}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、测试 `apps/ai-game-creator-shell/tests/{resourceCanvasBottomToolbar.test.tsx(新增),resourceCanvasGenerationEntry.test.tsx,projectResourceLiveIntegration.test.tsx,appSurface/project-development.suite.ts}`、PRD §3.10 / §7.9 / §8、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`（新增）、验收用例 S11 / S11a。**未动**：Rust、external v1 / OpenAPI、`packages/`（只消费共享 chrome）、SpacetimeDB。

docs/project-memory/shared-memory/pitfalls.md

@@ -1,5 +1,29 @@
 # 踩坑与排障记录
 
+## 客户端图标素材描述不能先包装再截断
+
+- 现象：资源画布填写了具体图标需求，平台实际收到的 `iconDescriptions` 却只包含泛化的小游戏美术指令，生成结果不遵循输入。
+- 原因：客户端先给用户描述套“Web 小游戏首版原型、核心美术素材”和默认 brief 模板，再把包装后的文本压入单项 `200` 字符；固定前缀已占满额度，用户描述在发给 API Server 之前就被丢弃。服务端校验只能看到被截短的文本，无法恢复原需求。
+- 处理：客户端画布图标生成只 trim 描述并以单项 `iconDescriptions` 原样提交，保留内部换行；面板与原生入口按 `200` 个 Unicode 码点校验并拒绝空白或超限输入，不静默截断、不机械拆条。服务端共用的提示词流程负责规范图、背景与排布要求；其它图片生成的 `32000` 字符上限保持不变。
+- 验证：检查实际请求体与 trim 后的原文一致，并覆盖 `200/201` 码点、补充平面字符、换行和空白输入；不能只断言“请求长度未超限”。完整合同见 [画板图标素材生成入口设计](../../【编辑器】画板图标素材生成入口设计-2026-06-15.md)。
+
+## 2026-09-21 不同渠道的包体在同一台设备安装会互相顶掉
+
+- **现象**：在一台已经装了某个渠道 AGC 客户端的设备上安装另一个渠道的安装包，装完后旧客户端直接消失（安装目录被覆盖、卸载项被接管），更新端点、平台服务器与本地登录态一起换成新渠道的；两个渠道的客户端无法共存。
+- **原因**：渠道此前只烘焙了 `plugins.updater.endpoints` 与 `VITE_AGC_PLATFORM_CHANNEL`（`apps/ai-game-creator-shell/scripts/build-release.mjs` 的 `createChannelConfig`），`productName` / `identifier` 用的是渠道无关的基线值。Tauri 的 Windows 安装目录与卸载项由 `productName` 决定，WebView2 数据目录与客户端数据目录由 `identifier` 决定，于是所有渠道落到 `%LOCALAPPDATA%\陶泥儿`、`HKCU\...\Uninstall\陶泥儿` 与 `%APPDATA%\world.genarrative.ai-game-creator`。
+- **处理（现行口径）**：渠道进入安装身份，默认渠道保持基线身份不变，其它渠道派生 `<产品名> <渠道显示名>` 与 `<基线>.<渠道>`；身份与端点在同一次构建期 `--config` 注入。见决策记录 2026-09-21 条目。
+- **核对方式**：装完任渠道的包后看 `HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\<产品名>` 的 `InstallLocation`、`%APPDATA%\<identifier>` 与主程序窗口标题是否按渠道分开；同名安装目录或同名数据目录说明身份没有生效。
+- **易错点**：只改安装包文件名或快捷方式名而不改 `identifier`，两个渠道仍会抢同一份 Agent Runner / 项目锁与登录态；反过来把渠道后缀加在默认渠道上，既有安装的升级链会断（客户端认不出旧安装）。相似前缀目录（如 `world.genarrative.ai-game-creator-backup`）不得进入提权 ACL 的 managed 范围。
+- **关联**：`apps/ai-game-creator-shell/scripts/channel-identity.mjs`、`build-release.mjs`、`build-macos-ci.mjs`、`src-tauri/src/config.rs`。
+
+## 发布器守卫拒绝时不要把 process.exit 用在 fetch 句柄未关闭处
+
+- 现象：`agc-template-library-publish.mjs --dry-run` 撞上「同一 `templateVersion` 的 ZIP 不得变」门禁时，终端只剩一句 `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c`，看不到任何拒绝原因，看起来像脚本崩溃而不是被拒绝。
+- 原因：`main().catch(...)` 里直接 `process.exit(1)`；此时 dry-run 刚用 fetch 读过公共清单，句柄仍在关闭流程中，Node/libuv 在 Windows 上先抛断言，把真实错误信息挤掉。
+- 处理：`catch` 里只设 `process.exitCode = 1`，让事件循环自然退出；同批把说明文档纳入受管发布（见决策记录 2026-09-21 条目）。
+- 验证：把模板源复制到临时目录、把某个模板的 `templateVersion` 改回与线上同版本并改动一个字节，`--dry-run` 应打印 `同版本 ZIP 内容或尺寸变化，请递增 templateVersion` 且退出码为 1，不再出现 `Assertion failed`。
+- 关联：`scripts/agc-template-library-publish.mjs`。
+
 ## macOS 只出 arm64 单架构，universal 必须失败关闭
 
 `stage-node-runtime.mjs` 只把**构建宿主的 Node**打成便携运行时（官方发行版是单架构，没有 universal 发行版），而 2026-09-21 之前 `build-macos-ci.mjs` 构建的是 `universal-apple-darwin`：macOS Job #7~#13 因此在 `stageNodeRuntime` 直接抛「Node 运行时不支持发布目标：universal-apple-darwin」。期间出现过一版「按宿主架构放行」的过渡实现（`targetRuntime` 对 universal 返回宿主架构），它能骗过通用包自检（`check-macos-bundle.mjs` 按 `process.arch` 校验），但**Intel Mac 上这份 arm64 侧车不可执行**，等于把坏包发出去。当前决策：macOS 固定只构建 `aarch64-apple-darwin`，清单只登记 `darwin-aarch64`，`targetRuntime('universal-apple-darwin')` 保持失败关闭。恢复 Intel 的正确路径是先在 staging 支持按架构各带一份**同版本**运行时（另下载另一架构官方发行版）并让通用包自检按架构分别校验，再切回 universal 目标、把 `darwin-x86_64` 键登记回去；不得用「只带宿主架构」充数，也不得把 arm64 产物登记成 x86_64 键。
@@ -4135,6 +4159,14 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 验证：活会话下 finalization 和 `runner.shutdown_if_idle` 必须失败关闭；分别验证 graceful handler 尾部输出、宽限超时后的 force、忽略 SIGHUP 的 npm 孙进程和 Windows Job 路径，只有 child 已终态、同组残留已处理且 PTY 尾部排空才出现唯一 terminal record。另用允许程序证明代理和固定 cwd 不是文件系统 / 网络沙箱，不得把该现象误写成测试失败或安全能力。
 - 关联：`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`、`apps/ai-game-creator-shell/src-tauri/src/runner.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent.rs`。
 
+## 一次性命令不能把孤儿僵尸误判为仍在执行的进程组
+
+- 现象：Linux CI 的命令已退出，但 `command.exec` 返回 `needs-reconciliation`，后续修复计划或输出读取请求一直等不到；普通 WSL 下相同命令可通过。
+- 原因：容器 PID 1 未回收孤儿 `bwrap` 僵尸，`kill(-pgid, 0)` 仍返回成功；主进程已被 wait 回收，后续 leader 启动身份核对必然失败，掩盖了真实退出结果与原本应触发的日志审计错误。
+- 处理：确认 target 终态且回收主进程后扫描 `/proc/<pid>/stat`，空组或仅含 `Z / X` 成员无需发送信号；有存活成员仍保留 leader 身份门禁，读取失败保守进入 reconciliation，不放宽未知进程组的信号权限。
+- 验证：隔离 subreaper 夹具覆盖 leader 已回收时的存活后代拒绝、孤儿僵尸接受和空组接受；原有诊断命令、审计失败、命令修复与长输出/历史读取测试在不回收孤儿的 PID namespace 下验证。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/command_exec.rs`、`apps/ai-game-creator-shell/src-tauri/src/tests/command_runtime.rs`。
+
 ## 命令环境变量、代理和进程组不能冒充 OS 沙箱
 
 - 现象：命令看似使用隔离 HOME / TMP、离线包管理器和不可达代理，仍能直接读取宿主用户文件、用原始 socket 联网，或由 `project.verify` 的平行 npm spawn 绕开 `command.exec` 限制。
@@ -5417,6 +5449,14 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 处理：Windows 专用 Tauri 配置设置 `bundle.useLocalToolsDir: true`，把工具缓存到 `src-tauri/target/.tauri/NSIS`；Jenkins 预检验证实际用户、项目工具目录可写，并在构建失败时打印实际缓存路径和绝对路径执行结果。
 - 验证：不要把 PATH 中 `makensis` 可发现当作 Tauri bundler 工具可执行的充分证据；需要在 Windows Agent 上检查 `target/.tauri/NSIS/makensis.exe`、ACL、EDR/Defender 和直接 `-VERSION` 结果。
 
+## Tauri NSIS 工具链必须在打包前预置并重试（2026-09-21）
+
+- 现象：AGC Windows 发布构建已完成 Rust release，Tauri 依次打印 `Downloading .../nsis-3.11.zip`、`Info extracting NSIS`、`Downloading .../nsis_tauri_utils.dll` 之后，直接以 ``failed to bundle project `io: unexpected end of file` `` 失败（退出码 1），安装包不会产出。
+- 原因：tauri-bundler 的 `download_and_verify` 现场从 GitHub 取 NSIS 工具链，只有一次机会、没有重试；响应体被截断即报 `io: unexpected end of file`，看起来像打包错误其实是网络问题。Checkout 阶段的 `git clean -fdx` 每次都会清掉 `target/.tauri`，所以每个构建都要重新下载，在受限网络下必然反复失败。
+- 处理：新增 `apps/ai-game-creator-shell/scripts/nsis-toolset.mjs` 与 `ensure-nsis-toolset.mjs`，在 `buildRelease`（Windows 目标且需要打包时）与 Jenkins `Tauri NSIS toolchain` 阶段按固定 SHA1 预置 `target/.tauri/NSIS`：原始归档带 4 次重试，缓存在工作区外的 `%ProgramData%\genarrative\tauri-nsis-cache`（可用 `AGC_TAURI_NSIS_CACHE_DIR` 覆盖），镜像开关沿用 bundler 的 `TAURI_BUNDLER_TOOLS_GITHUB_MIRROR_TEMPLATE` / `TAURI_BUNDLER_TOOLS_GITHUB_MIRROR`。该阶段同时执行 `makensis.exe -VERSION`，把 2026-09-02 记录的缓存目录不可执行问题也提前到编译之前暴露。Checkout 阶段改为 `git clean -fdx -e apps/ai-game-creator-shell/src-tauri/target/.tauri`：Tauri 的工具缓存位于工作区内，裸 `git clean -fdx` 会连它一起删，排除后同一节点的稳态构建不再需要联网，只有冷缓存（新节点、工作区重建）才下载。
+- 验证：`node --test apps/ai-game-creator-shell/scripts/nsis-toolset.test.mjs`（已就绪零下载复用、缓存离线还原、失败重试、哈希不符与归档越界失败关闭）与 `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs`；真实节点上该阶段必须早于 Rust 编译失败关闭。
+- 注意：不要改回 `bundle.useLocalToolsDir: false` 去用 `%LOCALAPPDATA%`，也不要依赖 PATH 里预装的 `makensis`；升级 `@tauri-apps/cli` 时同步核对归档 URL、SHA1 与必需文件清单。
+
 ## AGC 登录态续期必须同步本地运行时
 
 - 模型目录 HTTP 请求与 DirectProject 的 Rust/app-server 使用同一账号，但凭据分别保存在 WebView 与 Rust / Runner；续期应复用 `requestPlatformSessionRefresh` 完成用户核验及本地会话安装，不能只写 localStorage。
@@ -5851,3 +5891,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **处理（现行口径）**：① 依赖里只放数据，回调走 ref（`openActiveProjectRef`）——effect 不再因回调换身份而重跑；② `useDirectActiveTurns` 轮询只在快照内容变化时才 `setActiveTurns`（并给空态做引用稳定），避免每 5 秒换一次数组身份去带动下游 effect；③ `WindowChrome` 的 context value 用 `useMemo` 收口。判断类问题的通行判据：**凡是把"每次渲染新生成的函数/对象"写进 effect 依赖的，一律视为 bug**。
 - **验证**：修复后同一台机器、同一路径下 35 秒内新增 `Maximum update depth` **0 条**，renderer 工作集 **254 MB**（修复前 4.2–4.4 GB）；`apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx` 断言轮询返回值不变时快照引用不变。
 - **关联**：`apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx`、`apps/ai-game-creator-shell/src/features/agent-runtime/directActiveTurns.ts`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`。
+
+## 2026-09-21 DirectProject 结构化消息不能逐个拒绝空白文本片段
+
+- **现象**：多行正文、末尾空段落或合法引用前后的分隔空格会让有内容的消息报错；编辑器为了保持结构产生的空白文本片段被误判为“聊天内容为空”。
+- **原因**：校验器对每个 `input_text` 单独执行 `trim().is_empty()` 并立即拒绝，混淆了结构化片段合法性和整条消息是否有实际内容。
+- **处理（现行口径）**：`input_text` 允许空字符串、空格和换行，校验过程保持全部片段的原文、分段与顺序，不做合并或删除；遍历完整条消息后，只在既没有非空白文字、也没有合法 `agc_resource_reference` / `agc_runtime_region_reference` 时返回“聊天内容不能为空”。两类引用仍逐个执行原有校验，消息带正文也不能绕过非法引用。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/validation.rs`、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`。

docs/project-memory/shared-memory/project-overview.md

@@ -58,7 +58,7 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐
 - DirectProject 对话先在完整历史中按回合/原始 item 身份关联，再分页渲染；每个回合只有一个呈现入口。有流按 item `seq` 交替文本和工具，无流采用历史正文；禁止位置猜配或同时展示累计回复与 item 正文。流写入单调归并，收尾等待落盘任务，不按磁盘“最后一段”猜最终回复位置。详见 AGC 实施计划的“DirectProject 回合展示唯一归属”。
 - 回合生命周期只由活动 client 回合快照和 Direct 事件恢复；Provider 的历史终态通知不能创建活动 client 回合。消息发送时间保存在历史信封，原始 item 不混入宿主字段；完成后的中间文本和工具默认收进“执行过程”，最终回复及失败提示保持可见。
 
-- AGC 安装产品名统一为“陶泥儿”，由 Tauri `productName` 控制安装项、快捷方式与 EXE 产品描述；Windows 内置 Codex 安装到顶层 `coding-agent/win-x64/`，打包资源映射与运行时查找路径必须一致。内部可执行文件名与应用 identifier 保持稳定。
+- AGC 安装产品名基线为“陶泥儿”，由 Tauri `productName` 控制安装项、快捷方式与 EXE 产品描述；默认渠道 `dev` 保持基线产品名与 identifier `world.genarrative.ai-game-creator` 不变，其它渠道派生 `陶泥儿 <渠道显示名>` 与 `<基线>.<渠道>`，让不同渠道的包体在同一台设备上并存而不互相顶掉（详见《AGC客户端更新检查与下载》的渠道与安装身份合同）。Windows 内置 Codex 安装到顶层 `coding-agent/win-x64/`，打包资源映射与运行时查找路径必须一致。内部可执行文件名保持稳定。
 
 - 新 Web 游戏为 `game/` 下的 npm + Vite + Phaser 4.2.1 工程，使用包导入且允许其它依赖；npm 预览与导出只读取 dist，运行素材需纳入构建。单 HTML → Phaser 迁移固定走 DirectProject：文件落盘后先用受控 `project.bootstrap` 在 `game` 执行无参数 `npm install`，再用支持相对 cwd 的 `project.verify` 构建并确认 `game/dist/index.html`，已有单 HTML/Godot 不通过 JSON Generator 伪装成 npm 工程。
 

docs/project-memory/shared-memory/team-conventions.md

@@ -35,7 +35,7 @@
 
 - AGC 批量追加素材标签由原生在一次项目写锁与 revision CAS 下合并各项原标签，先校验全批再写 manifest；前端不能循环单素材分类命令，不回传展示层推导的分类或旧标签全集，以免部分写入或覆盖未编辑字段。
 
-- AGC 正式包的平台服务跟随构建渠道：`release` 连接 `https://www.genarrative.world`，`dev` 连接 `https://dev.genarrative.world`；本地 debug 态保留 release/dev/custom 服务器选择，会话凭据始终按 origin 隔离。发布渠道为 `dev/release/自定义名称`，Windows/Mac 是系统，OSS 的 `<channel>-win/mac` 仅是延续既有地址的分区。官网通过服务端 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`（默认 dev）选择渠道，公开同源 `/api/client-downloads` 汇总其各系统首装包与真实版本；未发布隐藏，单系统失败不影响其它下载，不跨渠道补齐。发布先上传 EXE/DMG 再写对应分区清单，不维护会互相覆盖的共享 OSS 索引。主站 Vite 代理复用实际 `runtimeServerTarget`。完整约定见 AGC 客户端更新检查与下载专题。
+- AGC 正式包的平台服务跟随构建渠道：`release` 连接 `https://www.genarrative.world`，`dev` 连接 `https://dev.genarrative.world`；本地 debug 态保留 release/dev/custom 服务器选择，会话凭据始终按 origin 隔离。发布渠道为 `dev/release/自定义名称`，Windows/Mac 是系统，OSS 的 `<channel>-win/mac` 仅是延续既有地址的分区。官网通过服务端 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`（默认 dev）选择渠道，公开同源 `/api/client-downloads` 汇总其各系统首装包与真实版本；未发布隐藏，单系统失败不影响其它下载，不跨渠道补齐。发布先上传 EXE/DMG 再写对应分区清单，不维护会互相覆盖的共享 OSS 索引。主站 Vite 代理复用实际 `runtimeServerTarget`。渠道同时决定安装身份：默认渠道 `dev` 必须保持基线 `productName` / `identifier` 不变，其它渠道派生独立身份，使不同渠道的包体可在同一台设备并存且本地数据不共享；身份与更新端点必须在同一次构建期注入里确定，禁止分别回读默认值。完整约定见 AGC 客户端更新检查与下载专题。
 - AGC 模板库灰度复用 `agc:template-library`：未配置关闭，已配置时遵循现有灰度启停、用户 ID/标签和比例规则；服务端返回权威结论，客户端入口和原生清单/下载/建项均执行门禁，主体切换丢弃旧异步结果。公开 OSS 不是保密边界，已创建项目不受影响。
 
 - 画布卡片类型与信息角标共用 `CanvasCardCornerActions`；菜单收纳共用 `OverflowActions`，宿主决定展示数量和资源命令。AGC 选中菜单前 5 项直显，Web 默认不折叠；浮层 portal 继续接入现有画布关闭与滚轮归属判据。

docs/technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md

@@ -3,7 +3,9 @@
 > 文档状态：`current`
 > 规范关系：承接 AGC 通用插件宿主与编辑器适配主规范
 
-更新时间：`2026-09-20`
+更新时间：`2026-09-21`
+
+2026-09-21 更新：解除工作区发现上的两条限制——一层子目录多命中时按目录名排序取第一个（不再整体失败关闭），`project.godot` 允许是符号链接 / Windows reparse point / 硬链接（按链接目标判定）；同时设置→扩展 的内置插件行去掉手动「启动 / 停止」，启动统一由前端自动完成、停止改走该行启用开关。
 
 ## 目标与边界
 
@@ -15,7 +17,7 @@
 
 将 Godot 编辑器操控接入现有 AGC PluginHost、EditorAdapter、Runner、内置插件开关、权限审计和 Agent 工具链。Windows x64 的 Godot 4.7 及以上标准编辑器是首个实现目标，实机验收使用 4.7.2；其他平台和 .NET 编辑器不得从该结果推断支持。
 
-初版工程路径支持 Windows 本地盘符目录；UNC/网络共享路径在准备描述文件前明确拒绝。链接/reparse point 继续按同一文件边界失败关闭。
+初版工程路径支持 Windows 本地盘符目录；UNC/网络共享路径在准备描述文件前明确拒绝。受管描述文件、缓存与运行缓存继续按同一文件边界对链接/reparse point 失败关闭；唯一例外是工作区发现读取的 `project.godot`，它允许是链接并按目标判定。
 
 DLL 原件随 AGC 安装包放在插件资源目录中；Godot Windows 加载器会在被加载文件旁生成 `~DLL`，因此宿主在 AGC 私有配置目录的运行缓存中按编辑器实例和构建身份准备临时加载副本。AGC 向项目新增一个可扫描的受管 `.gdextension` 描述文件，通过绝对路径引用该实例的加载副本；Godot 可自动生成其同名 `.uid` 伴生文件。DLL 不复制进工程。重新聚焦 Godot 后，由官方文件扫描完成首次加载；不需要用户打开或运行脚本，不创建 EditorPlugin addon，不修改 project.godot 或业务场景文件。编译工具链只属于开发与打包环境，不要求终端用户安装编译器。
 
@@ -24,9 +26,9 @@ DLL 原件随 AGC 安装包放在插件资源目录中；Godot Windows 加载器
 ## 入口与归属
 
 - 插件 id 为 `agc-godot-editor`，适配器为 `godot-editor`；命令 `godot.editor.execute`、连接能力 `godot.editor.connection`，DirectProject 工具为 `agc_godot_execute`。复用已有扩展列表和启用开关，不建立平行插件管理页面。
-- 项目发现沿用现有 Godot 工作区合同：工作区根保持用户选定目录；实际 Godot 根由普通 project.godot 在根或唯一一层子目录中确定。准备描述文件和读取 Godot 缓存只作用于实际 Godot 根，通用文件工具/Runtime 的工作区根不改变。
+- 项目发现沿用现有 Godot 工作区合同：工作区根保持用户选定目录；实际 Godot 根由根目录或一层直接子目录中的 project.godot 确定，一层命中多个时按目录名排序取第一个（确定性，不再报歧义），`project.godot` 本身是链接时按链接目标判定。准备描述文件和读取 Godot 缓存只作用于实际 Godot 根，通用文件工具/Runtime 的工作区根不改变。
 - 平台、内置开关、项目及目标身份必须在执行入口重新检查。插件只能处理宿主传入的当前受控项目，模型不能覆盖项目路径、DLL 路径、端口、令牌或目标实例。
-- Godot 的插件列表、启动和 Agent 工具目录继续按当前 Godot 项目过滤；Cocos/Unity 沿用各自不按工程类型过滤的合同。前端统一消费宿主列表自动启动三种编辑器插件，不在界面重复推断项目类型。Godot 的项目切换仍撤销旧插件上下文并停止旧实例。
+- Godot 的插件列表、启动和 Agent 工具目录继续按当前 Godot 项目过滤；Cocos/Unity 沿用各自不按工程类型过滤的合同。前端统一消费宿主列表自动启动三种编辑器插件，不在界面重复推断项目类型；设置→扩展 的内置插件行只保留启用/禁用与重载，不再提供手动启动/停止入口。Godot 的项目切换仍撤销旧插件上下文并停止旧实例。
 - 插件启动先完成项目事件订阅并接收当前受控项目快照，再注册命令和连接能力；命令可见时必须已经具备执行上下文。订阅期间收到的新项目事件优先于迟到的初始快照。
 - 只连接已打开且唯一匹配真实工程路径的 Godot Editor；校验 PID、进程启动身份、Godot 版本、握手中的工程路径与会话代次。多个候选、非编辑器、路径不符或已退出的进程均拒绝，不启动或关闭用户编辑器。
 - GUI、DirectProject 和 Agent Runtime 的原生操作统一由长寿命 Runner 持有。项目切换使连接失效，迟到回执不能改变新项目状态。

docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md

@@ -1,6 +1,6 @@
 # AGC 客户端更新检查与下载
 
-更新时间：`2026-09-20`
+更新时间：`2026-09-21`
 
 本文件是 AGC 客户端自动更新的主规范：更新能力由 Tauri 官方插件 `tauri-plugin-updater` 承担，并按下文渠道分发。
 
@@ -18,6 +18,17 @@
 - 验收必须覆盖 dev/release/自定义渠道各自端点和对象地址、独立版本、非法名称、旧 dev 地址延续、release 不写旧迁移桥、网站配置贯通、跨渠道链接拒绝和部分失败。
 - 更新链路的信任来源从「清单里的 sha256 + 受信域名」升级为「发布签名 + 受信域名」：清单里的 `signature` 由构建期私钥生成，客户端用内置公钥校验，校验不过就拒绝安装。
 
+### 渠道与安装身份合同
+
+- 渠道同时决定**更新端点**与**安装身份**，两者都由构建期写入产物。默认渠道 `dev` 保持基线身份 `productName = 陶泥儿`、`identifier = world.genarrative.ai-game-creator`；其它渠道（`release` 与自定义渠道）派生 `productName = 陶泥儿 <渠道显示名>`（`release` → `陶泥儿 Release`、`beta-2` → `陶泥儿 Beta-2`）与 `identifier = world.genarrative.ai-game-creator.<渠道>`。渠道显示名按连字符分段首字母大写，不改动渠道本身。
+- 默认渠道身份**不可变更**：既有安装目录、卸载项、快捷方式与已发布客户端的升级链都建立在基线身份上。渠道身份由 `apps/ai-game-creator-shell/scripts/channel-identity.mjs` 单点定义，构建入口、macOS 发布入口与配置门禁共同消费；基线 `tauri.conf.json` 必须逐字等于默认渠道身份。
+- 安装身份决定的持久与可见事实：Windows 安装目录 `%LOCALAPPDATA%\<产品名>`、卸载项与 `HKCU\Software\genarrative\<产品名>`、WebView2 数据目录 `%LOCALAPPDATA%\<identifier>`、客户端数据目录 `%APPDATA%\<identifier>`；macOS `.app` 名、bundle id、DMG 卷名与菜单栏应用名。
+- 同机并存：不同渠道的包体可以在同一台设备上同时安装并同时运行，互不覆盖、互不顶掉；同一渠道的新版本仍是原地升级，因为更新端点与安装身份同属一个渠道。
+- 数据不跨渠道共享：本地项目、工程快照、模板、登录态、诊断日志与 Runner/项目锁按渠道身份分目录。切渠道等于换一个客户端，不迁移、不合并本地数据；渠道内的 origin 隔离规则不变。
+- 主窗口与工作区/启动器窗口标题取构建期产品名，让同机并存的渠道客户端在任务栏与 Alt-Tab 中可区分；默认渠道标题仍是「陶泥儿」。
+- 首装包与更新包的对象名包含产品名（如 `陶泥儿 Release_0.1.96_x64-setup.exe`、`陶泥儿 Release_0.1.96_aarch64.dmg`）。清单 `downloads` 地址由发布脚本按本次真实产物派生，禁止写死产品名；首装包选择按 `<版本>_<架构>.dmg` 唯一匹配，不依赖产品名字面量。
+- Windows 提权 ACL 修复助手按目录名识别安装身份：`<基线>` 与 `<基线>.<渠道>` 都在 AGC 自有的 managed 范围内；相似前缀（例如 `world.genarrative.ai-game-creator-backup`）不在范围内，落回 user-selected 范围或直接拒绝。
+
 ## 非目标
 
 - 不做灰度放量、分批更新、强制更新和自动回滚；渠道只决定「取哪份清单」。
@@ -110,11 +121,21 @@
   - 迁移起点：已发布客户端（含当前线上版本）内置自研清单地址 `agc/latest.json`（sha256 格式），下载与安装由自研 Rust 命令完成。
   - 迁移策略见「未决问题与决策」。迁移完成后，自研清单解析、下载命令、下载进度事件以及为此放行的 CSP / HTTP 白名单条目按「四不写」整条删除，不留兼容分支与墓碑说明。
 
+- 渠道安装身份映射（`<channel>` 为 `dev`、`release` 或自定义名称；`<Channel>` 为渠道显示名）：
+
+| 渠道                 | productName        | identifier                                     | Windows 安装目录                    | 客户端数据目录                                  |
+| -------------------- | ------------------ | ---------------------------------------------- | ----------------------------------- | ----------------------------------------------- |
+| `dev`（默认）        | `陶泥儿`           | `world.genarrative.ai-game-creator`            | `%LOCALAPPDATA%\陶泥儿`             | `%APPDATA%\world.genarrative.ai-game-creator`     |
+| `release` / 自定义   | `陶泥儿 <Channel>` | `world.genarrative.ai-game-creator.<channel>`  | `%LOCALAPPDATA%\陶泥儿 <Channel>`   | `%APPDATA%\world.genarrative.ai-game-creator.<channel>` |
+
+- 安装身份迁移：`dev` 客户端保持原身份，升级链路连续；`release` 与自定义渠道首次以新身份安装，**不接管也不迁移**任何既有 `dev` 安装、本地项目或登录态，设备上因此可以同时存在两个渠道的客户端，由用户自行决定是否卸载其一。
+
 ## 构建与发布
 
 - 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
 - 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
 - 渠道由 `AGC_UPDATE_CHANNEL` 显式指定，默认 dev；Windows 与 macOS 目标均支持 dev、release 和自定义渠道，目标校验独立进行。
+- 渠道 `--config` 在 Tauri 构建前最后合并，同时注入 `productName`、`identifier` 与 updater 端点：安装身份与更新端点必须来自同一个渠道，不能各自回读默认值。macOS 发布入口构建 `*.app`、updater 归档与 DMG 前先按发布渠道解析产品名，产物名一律派生而不写死。
 - 定时调度只在本轮到达的提交包含 AGC 相关路径（客户端、共享包、`server-rs/crates`、AGC 插件、桌面壳图标、根依赖清单）时才触发渠道发布；纯文档或流水线自身的提交只跑 Full Build，不推高客户端版本号。判定失败或勾选强制触发时按"需要发布"处理。
 - 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题（短 SHA）`，最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
 - 清单里的 `commit` 是非标准字段：更新插件忽略未知字段，发布脚本用它定位下一次摘要的起点。
@@ -157,6 +178,25 @@
 | 真实更新闭环（含升级后重启） | 0.1.47 客户端按提示下载安装并重启                                       | 通过（2026-09-17 用户实测：提示 → 下载 → 安装 → 关于页显示新版本，再次检查为已是最新）                                               |
 | 更新摘要端到端展示           | 公网读取渠道清单 `notes` 与客户端更新提示                               | 通过（2026-09-17 用户实测：0.1.62 清单带 8 条自动摘要，客户端提示正常显示多行内容）                                                  |
 
+渠道安装身份隔离已于 `2026-09-21` 完成源码验收：
+
+| 条款 | 验收方式 | 结果 |
+| --- | --- | --- |
+| 渠道身份派生与默认渠道不变 | `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs` | 通过；`dev` 逐字等于基线 `陶泥儿` / `world.genarrative.ai-game-creator`，`release` / `beta-2` 派生独立产品名与 identifier，非法渠道失败关闭 |
+| 身份与端点同批注入 | 同上的渠道 `--config` 用例 | 通过；`productName` / `identifier` 与 `/<channel>-win|mac/latest.json` 来自同一次解析 |
+| 渠道产物首装包选择 | 同上的渠道 DMG 夹具用例 | 通过；`陶泥儿 Release_<版本>_aarch64.dmg` 仍按 `<版本>_<架构>.dmg` 唯一匹配 |
+| 基线配置等于默认渠道身份 | `node apps/ai-game-creator-shell/scripts/check-config.mjs` | 通过；基线漂移与非默认渠道身份不隔离都会失败关闭 |
+| 全量发布脚本回归 | `node --test build-release.test.mjs release-oss.test.mjs prepare-macos-codex.test.mjs cargo-features.test.mjs` | 通过（64/64，含 macOS 入口按渠道解析产品名的守卫） |
+| AGC 自有 AppData 提权 ACL 范围 | `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell -- config::private_path_elevation_policy_tests` | 通过（12/12；含基线、`<基线>.release`、`<基线>.beta-2` 与相似前缀 `-backup` 的反向断言） |
+| 渠道身份进入真实构建产物 | `AGC_UPDATE_CHANNEL=release npm --prefix apps/ai-game-creator-shell run build -- --no-bundle --debug` | 通过；Tauri 接受派生的 `productName` / `identifier` 并完成构建；产物字符串实测 `陶泥儿 Release` × 1、`agc/release-win/latest.json` × 1、`world.genarrative.ai-game-creator.release` × 1、`agc/dev-win/latest.json` × 0 |
+
+未验证项（不得按已通过处理）：
+
+- 真实 Windows 双渠道安装与并存：尚未在同一台设备安装 `dev` 与 `release` 两个渠道的安装包，安装目录/卸载项/数据目录的分离与两个客户端同时运行属于发布验收，本次只到源码与脚本层级。
+- 未生成安装包：本轮构建烟测止于 `--no-bundle`，NSIS 安装目录 / 卸载项 / 快捷方式按渠道分开、以及「装完 release 后 dev 仍在」的现场证据需要一次真实渠道打包与安装。
+- macOS 侧只验证到入口派生逻辑：`.app` 名、bundle id 与 DMG 卷名的渠道派生没有在 macOS 节点实跑。
+- 客户端数据隔离的运行期事实（`%APPDATA%\<identifier>` 分目录、登录态不跨渠道）未做真机对照。
+
 待执行证据（首次渠道发布后回填）：
 
 | 条款                 | 验收方式                                            | 证据   |
@@ -174,6 +214,7 @@
 - macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 arm64 单架构构建、arm64 隔离 smoke、arm64 DMG（`<产品名>_<版本>_aarch64.dmg`）、分区清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为关（与 Windows 渠道对称，即直接发布），只有勾选后才退化为「只打印上传计划、不写 OSS」的演练。
 - macOS 代码签名与公证暂缺：产物为未签名 + 未公证，构建入口剥离 `APPLE_*` 凭据跳过 Apple 签名，不传 `--no-sign`（它还会跳过 updater 的 minisign 签名，产物将没有 `.sig`）；构建清单实测记录 `appleSigned` 与签名类型，`latest.json` 侧固定记录 `notarized=false`，首装需用户在 Gatekeeper 中手动放行。该限制作为已知未验证项记录，不静默通过；「安装 → 重启接管新版本」的自动更新闭环仍需实机验收。
 - 更新包验签门禁：构建完成、上传 OSS 之前，用产物内烘焙的 `plugins.updater.pubkey` 复核 `<更新包>.sig`（Tauri 使用 minisign 的 `ED` 预哈希模式）。keyId 不一致或校验失败立即失败关闭，禁止上传——客户端校验失败会直接拒绝安装，且公钥发布后不可更换。
+- 渠道安装身份（2026-09-21）：渠道此前只决定更新端点，`productName` / `identifier` 与渠道无关，导致不同渠道的包体共用 `%LOCALAPPDATA%\陶泥儿`、同一个卸载项与同一份 `%APPDATA%\world.genarrative.ai-game-creator` 数据目录，后装的渠道静默顶掉先装的渠道并接管更新端点与本地登录态。现决策为「渠道进安装身份」：默认渠道保持基线身份不动，其它渠道派生 `<产品名> <渠道显示名>` 与 `<基线>.<渠道>`，渠道内仍原地升级，同机并存与数据隔离成立。窗口标题、macOS 产物名与 Windows 提权 ACL 的 managed 识别范围同批跟随该身份。
 
 待办：
 

docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md

@@ -22,7 +22,7 @@ AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，
 ## 后台模板管理
 
 - 后台新增 `#agc-templates`「模板管理」页签，复用现有后台布局、列表、公共表单/独立弹窗及写入确认。提供名称/ID/标签搜索、运行时和上下架筛选，展示封面、名称、简介、标签、引擎/版本、包大小与上架状态。
-- 本轮只允许编辑名称、简介、标签、封面和上架状态；不新增模板、不上传 ZIP、不修改 ID、运行时、引擎或模板版本，不删除包、历史对象或已建项目。
+- 编辑接口只允许改名称、简介、标签、封面和上架状态，不修改 ID、运行时、引擎或模板版本；**模板新增与 ZIP 上传见「后台模板上传」章节**。两条路径都不删除包、历史对象或已建项目。
 - 唯一数据真相仍是 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`。不可用或格式错误返回可诊断错误，不能当作空模板库。
@@ -33,6 +33,18 @@ AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，
 - CLI 与后台共享锁和清单合同。CLI 合并保留未选条目与 `inactiveTemplates`，更新下架模板仍保持下架；新增模板默认上架，CLI 不承担删除或上下架。显式发布选中 ID 时，展示字段按该模板源更新，后台编辑结果持续有效直到下一次显式发布该 ID。两端都必须保留另一组条目，不能因本地模板源较旧而抹掉后台记录。
 - 验收包含权限、入口挂载、过滤、编辑与图片校验、上下架往返、未知字段保留、过期 revision/锁争用、上传失败与未知提交、CLI 对下架项的更新/保留，以及桌面/窄屏真实浏览器验证。真实 OSS 写入和生产部署不在本轮验证范围，使用隔离存储替身。
 
+## 后台模板上传
+
+- 后台「模板管理」页提供「上传模板」入口：一次可多选 `.zip`，再按模板 ID 同名多选封面，逐行确认 ID / 名称 / 版本 / 运行时 / entry 后整批提交。简介、标签与引擎可在上传后用编辑接口补齐。
+- 接口 `POST /admin/api/agc-templates/import`（`multipart/form-data`）：`manifest` 文本字段 + `zip_<index>` / `cover_<index>` 文件字段，下标与 manifest 条目顺序一一对应。manifest 为 `{ expectedRevision, templates: [{ id, title, summary, tags, runtime, engine, engineVersion, entry, templateVersion, zipField, coverField }] }`，禁止未知字段。
+- 限制：单批最多 20 个模板；单个 ZIP ≤ 64 MiB；单张封面 ≤ 5 MiB；请求体 ≤ 200 MiB；`runtime` 仅接受 `html / unity / godot / cocos`，`id` / `templateVersion` / `entry` 走既有标识符与相对路径白名单。存储层为 `application/zip` 单独放宽单对象上限到 64 MiB，图片与元数据仍是 5 MiB。
+- 语义：一批**全有或全无**。任一模板的 manifest 字段、归档或封面不合法，都在任何写入之前整批拒绝，并逐项给出模板 ID 与原因。
+- 归档校验不落盘：合法 zip、无符号链接、无绝对路径 / `..` / 盘符 / 反斜杠条目、必须包含 manifest 声明的 `entry`、条目数 ≤ 4096 且解压后总大小 ≤ 512 MiB；并拒绝含 `.agent` / `.git` / `.svn` / `node_modules` 段（任意层级）与根目录 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode` 的包（与 CLI 打包同一门禁，见 [`【模板规范】AGC 模板包组织指南`](../【模板规范】AGC模板包组织指南-2026-09-21.md)）。
+- 封面每个模板必填，按字节嗅探格式（只接受真实 PNG / JPEG / WebP），不信任 multipart 声明的 content-type；上限与编辑路径相同（5 MiB、单边 4096、1600 万像素）。SVG 仍只可能来自 CLI 历史发布。
+- 发布复用既有协议：ZIP 按上传字节原样发布（不重新打包、不删除历史对象），对象键为 `templates/v1/<id>/sha256/<摘要>/{template.zip,cover.*,template.json}`；在发布锁内先 CAS 校验 `expectedRevision`（过期返回 409），写入后逐个回读校验，最后提交一次清单；清单写入结果不明时保留锁并返回 503。断连由独立任务持有，不会在清单 PUT 在途时提前解锁。
+- 版本与保留语义：新 ID 默认上架；已存在 ID 就地更新并保留 `enabled` 分组、其它条目与未知扩展字段（含下架条目）；同一 ID 同一 `templateVersion` 的 ZIP 字节不同时拒绝并要求递增版本（与 CLI 同一句文案），字节完全一致时按内容复用，响应里以 `reusedObjects` 标出。
+- 后台页面沿用既有写入确认、防重复提交与刷新语义：409 提示刷新后重试；上传失败只在弹窗内交代，401 仍交由会话处理。
+
 ## OSS 契约
 
 ```text
@@ -66,15 +78,19 @@ templates/
 - 所有对象键必须落在 `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] [--only <id,id,...>]`。ZIP、封面和元数据分别以自身字节的 SHA-256 定位，只创建新对象或复用逐字节校验一致的已有对象；全部对象回读一致后才更新 `index.json`。失败不回收已上传对象，旧清单及其引用始终可读。
+- 模板包内容怎么组织（根目录结构、Cocos 工程保留项、不要放的东西、封面与体积上限、发布前自检）见 [`docs/【模板规范】AGC模板包组织指南-2026-09-21.md`](../【模板规范】AGC模板包组织指南-2026-09-21.md)。
+- 上传与校验由 [`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`。失败不回收已上传对象，旧清单及其引用始终可读。打包阶段执行与后台上传相同的正文门禁（`readProjectFiles`）：正文含 `.agent` / `.git` / `.svn` / `node_modules` 段（任意层级）或根目录 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode` 的模板直接报错，不产生任何上传对象。
 - 只更新指定模板时使用 `--only <id,id,...>`，在发布锁内读取最新清单，只替换指定 ID，其余条目和未知扩展字段保留。首次清单 404 可由本次选择初始化；读取异常或清单非法时停止。全量发布也遵守相同锁与版本门禁。
+- `templates/README.md` 与上述正文不同：它不是内容寻址对象，而是**覆盖写的说明文档**，源在仓库 `apps/ai-game-creator-shell/template-library/README.md`（上限 64 KiB），由同一次发布在清单之前写入并回读校验。客户端从不读它，改契约只改仓库源即可，不要再手工维护线上副本。
 - 正式发布先通过 `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`。
+- 当前模板：`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`，以及 Godot 4.7 的 `godot-empty-2d`、`godot-empty-3d`、`godot-hello-world`、`godot-platformer-2d`。
 - 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 占位入口；模板源与本机安装缓存不被改写。
+- Godot 内容为仓库内手写的 Godot 4.7 工程（`project.godot` + `scenes/` + `scripts/`，GL Compatibility 渲染，只用内置 `ui_*` 输入动作，不依赖外部贴图），`entry` 为 `project.godot`，不打包 `.godot/` 编辑器缓存与导出产物。
+- Godot 建项在复制后按 `project.godot` 识别，复用既有 Godot 导入流程，写入 `godotProjectRoot: "."`，并把工程显示名改写成用户选择的项目名（只改 `[application]` 段的 `config/name` 一行，其余字节逐字保留）；不生成 `game/` 占位入口与 `assets/`、`memory/`、`exports/` 并行目录，也不改写模板源与本机安装缓存。
 - 客户端可用 `AGC_TEMPLATE_LIBRARY_BASE_URL` 覆盖库地址；只接受 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com`（拒绝其他主机、路径、http）。
 
 ## 客户端实现
@@ -83,9 +99,9 @@ templates/
 
 | 命令                                                | 行为                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fetch_game_template_library`                       | 读 `templates/index.json`（≤4 MiB），校验后缓存到 `<app_data>/templates/index.json`；网络失败时回退本机缓存并在 `source` 标 `cache`                                                                                                                                                                                                                                                                                         |
+| `fetch_game_template_library`                       | 读 `templates/index.json`（≤4 MiB），校验后缓存到 `<app_data>/templates/index.json`；网络失败时回退本机缓存并在 `source` 标 `cache`。远端已经答话但正文不是合法 UTF-8 或不符合 schema、以及缓存自己损坏时，一律失败关闭，不用缓存掩盖远端错误                                                                                                                                                                                  |
 | `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) |
+| `create_automatic_local_game_project_from_template` | 需要时先安装模板，然后在自动工作区根目录下按既有自动工作区规则建目录：先复制模板文件；Cocos 项目更新自身身份后走既有 Cocos 导入，Godot 项目改写工程显示名后走既有 Godot 导入，其余沿现有 `init_local_game_project_at` 初始化。根目录默认是 `<app_data>/projects/`，用户可选 `projectsRoot` 覆盖（必须来自本机目录选择器并通过私有路径门禁），见 [`【实施计划】AGC项目创建目录可选-2026-09-17.md`](../project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md) |
 
 安全与健壮性：
 
@@ -93,6 +109,7 @@ templates/
 - 安装目录名由标识符白名单拼出，不拼接远端字符串；重装时只清理该模板自己的安装目录。
 - 模板文件与安装记录统一走 `write_game_creator_private_file` / `ensure_game_creator_private_directory_tree`，保持项目目录的私有 DACL 口径。
 - 建项目失败时删除刚创建的项目目录，不留半成品。
+- 大小 / 摘要校验在落盘之前完成，被拒绝的模板包不产生任何安装目录；`installed.json` 是「已下载」的唯一判据，目录残留（例如解压中途失败）不构成已安装，下次安装会先清理该模板自己的安装目录。
 
 ### 前端
 
@@ -114,6 +131,14 @@ Cocos 回归分别覆盖仓库模板和线上真实 ZIP 的安装、连续建项
 
 `2026-09-19` 发布一致性验收：Node 发布回归 22 项通过，覆盖两个发布者竞争、正文/清单写入失败、迟到清单 PUT、锁归属、版本控制拒绝、V1 签名及真实 CLI 的无写入 dry-run。Rust 定向回归 15 项通过，新增内容地址的清单解析与 URL 保留校验；3 项线上用例本轮未重复执行，此前同日线上下载及原生建项已通过。只读 dry-run 保留线上九个模板并仅计划更新四个 Cocos 条目。格式、编码、文档索引、定向 ESLint 与 diff 检查通过。全部并发/故障写入证据来自离线替身，未执行真实 OSS 锁写入或发布，也未验证 Creator 内场景运行。
 
+`2026-09-21` 客户端接入复核：Rust 定向 24 项通过（新增清单来源判定 5 项：合法远端正文优先并标 `network`、远端失败回退缓存并标 `cache`、无缓存时暴露远端错误、远端正文非法时不用缓存掩盖、缓存损坏时失败关闭；新增建项目失败清理 1 项；并在大小/摘要不一致、越界归档两条用例上补「拒绝后不留安装目录、不产生已下载判据」断言）。3 项线上用例（读线上清单、下载安装线上模板、下载并原生建项 Cocos 模板）本轮全部真实执行通过；匿名 `GET https://agc-dev.oss-rg-china-mainland.aliyuncs.com/templates/index.json` 返回 200、`schemaVersion=agc-template-library.v1`、9 个模板。前端 38 项通过（模型 9、网格 6、页面 12、控制器 11），`appSurface` 首页模板用例 2 项通过（灰度外隐藏入口与推荐位、点击进入模板库不建项），AGC `typecheck` 通过。仍未验证：Creator 内场景运行，以及真机 iOS / Android 观感。
+
+`2026-09-21` 模板库重发布：把线上库从 09-17 的旧产物对齐到仓库当前源。线上 9 个模板里 7 个（`blank-3d-scene`、`cocos-empty-2d/3d/3d-hq/hello-world`、`phaser-2d-starter`、`threejs-3d-starter`）的 ZIP 与仓库不一致（旧产物来自 PR 定稿前的源，例如模板内嵌 `package-lock.json` 已由 `5e4ff54a9` 删除、`game.js` / `main.js` 后来改过），其中 2 个原本一致（`blank-2d-canvas`、`blank-web`）。按「同版本 ZIP 不得变」门禁，为这 7 个模板递增 `templateVersion` 到 `0.1.1` 后重发：28 个内容寻址对象逐个回读校验通过，`index.json` 与 `templates/README.md` 在锁内提交；线上清单现在全部指向 `v1/<id>/sha256/<摘要>/` 键，`libraryVersion=1`、9 个模板、无下架条目。发布脚本本次同时补齐说明文档受管写入（源文件即 `apps/ai-game-creator-shell/template-library/README.md`）并修掉「守卫拒绝后直接 `process.exit(1)` 触发 libuv 断言崩溃、看不到原因」的问题；线上 README 与仓库源已逐字节一致。
+
+`2026-09-21` 模板正文目录门禁：CLI 打包（`readProjectFiles`）与后台上传（`validate_import_archive`）统一拒绝正文含 `.agent` / `.git` / `.svn` / `node_modules` 段（任意层级）与根目录 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode` 的模板，两处用同一份段名单与同一句文案。同名目录段只在根目录受限：正文内 `game/dist/**` 与 `.gitignore` 仍合法（`.gitignore` 不等于 `.git`），Cocos 模板的 `.creator` / `.gitignore` 不受影响。证据：Node 发布回归 28 项通过（新增 1 项，13 条拒绝用例 + 2 条放行断言）；Rust `admin_templates` 8 项回归通过（新增 `template_import_archive_rejects_identity_and_build_directories`）；仓库现有 9 个模板源无一条命中门禁，本地重打包的 9 个 ZIP 摘要与线上 `index.json` 的 `zipSha256` 逐条一致（匿名读清单 200、9 个模板、0 个下架条目），即门禁未改变任何已发布字节。未执行真实 OSS 写入。
+
+`2026-09-21` Godot 模板入库：新增 `godot-empty-2d` / `godot-empty-3d` / `godot-hello-world` / `godot-platformer-2d` 四个仓库内手写模板，并给建项补 Godot 分流。模板内容用本机 Godot `4.7.2.stable` 逐项验证：四个模板的主场景都能实例化并跑满 3 帧、全部 GDScript 过 `--check-only`（同一条命令对故意写错的脚本报告 Parse Error，证明检查有效）；平台跳跃模板另做真机物理试玩——角色落地 y=627.99（地面顶 656 − 半高 28）、按住右 1 秒位移 320px、连按跳跃后落在平台上 y=515.93（平台顶 544 − 28）、三枚金币全部收集后 HUD 变为「已收集 3 / 3 —— 全部完成！Esc 重来」。Rust 侧 4 项定向回归通过：`template_library::tests::godot_template_creates_native_project_with_relative_root_and_display_name`（Godot 模板建项得到 `godotProjectRoot: "."`、无 `game/` 占位入口、`config/name` 改写成所选名称且其余行逐字保留）、`import_tests::rewrites_only_the_godot_display_name_line`、`import_tests::keeps_a_godot_project_without_a_display_name_line_untouched`，以及既有 Cocos/Web 建项回归未受影响。发布保持 `--only` 定向：只新增四个 Godot 模板对象并重写清单，其余 9 个模板的键与版本不变；未在客户端「模板库」里实际建一次项目。
+
 ## 本地压测假数据注入（feature 控制）
 
 模板库的数据源在 Rust 侧（清单校验、安装状态、下载与建项目都在这里），TS 只消费快照做渲染，所以假数据注入也放在 Rust 侧，走与真实完全一致的链路。

docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md

@@ -254,6 +254,7 @@ npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> -
 - `cwd` 必须是项目内规范相对目录，拒绝符号链接、绝对路径、`..`、Windows 盘符 / UNC / ADS 和整个 `.agent` 控制面；超时固定在 1-300 秒，stdin 关闭，stdout / stderr 采用有界头尾保留并先做凭据清洗。
 - 默认权限为 `confirm`。确认摘要包含程序、argv 摘要、cwd 和超时；精确动作继续绑定 actionId、repository fingerprint、project revision 和 execution owner。Runner 在 `executing` 阶段退出时保持 `needs-reconciliation`，不得自动重放命令。
 - 子进程继承环境清空；可执行文件必须从项目外安全绝对目录解析为绝对路径，子进程 PATH 只保留这些已规范化目录，并注入隔离 HOME / TMP / cache、离线包管理配置和不可达代理。超时或读流失败时 Runtime 请求终止受控进程组并检查终止调用结果，但这不等同于完整 detached-process / 容器隔离。首版安全等级与现有 `project.verify` 相同：固定程序和参数策略加用户确认，不宣称已经具备 Codex CLI 的完整 OS sandbox；在完成平台沙箱前不得把 `command.exec` 默认改为 `auto`。
+- Linux 一次性命令确认 target 终态并回收主进程后，按 `/proc/<pid>/stat` 核对同 PGID 成员；空组或只剩 `Z / X` 成员无需再发送信号，不因容器 PID 1 未回收孤儿僵尸而误报 reconciliation。存在存活成员时仍必须核对原 leader 启动身份，身份缺失或不匹配时拒绝发送信号；读取或解析进程状态失败同样进入 reconciliation。此判断不扩展为 detached-process 隔离证明，也不改变诊断命令与验证 gate 的区分。
 - Cargo / npm 缓存固定写入项目私有 `.agent/runtime/command-env/cache`，不复用或改写用户宿主缓存，也不允许联网补依赖。依赖未进入项目 vendor、现有 `node_modules` 或隔离缓存时，命令应以真实失败输出回到 Agent；首版不为“跑通命令”复制宿主的 Cargo registry、凭据或用户级配置。
 - `command.exec` 的执行前后源码指纹各自最多遍历 20,000 个目录项、10,000 个受保护文件和 512 MiB 正文；执行前超预算直接拒绝启动，执行后无法完成指纹则进入 `needs-reconciliation`，不得把截断扫描当成完整验证凭证。
 - 命令结束后重建安全项目文件指纹。若命令改写了受保护项目文件，则保持 verification gate 未通过并要求 Agent 重新检查；每次真正启动命令前已经保守推进一次 revision。可签发验证凭证的命令仅限 `cargo check/test/clippy/fmt/build`、`npm test`、命名为 `check/typecheck/test/lint/build/verify/validate` 的 npm 验证脚本及精确 `node --test`；`git`、`rg`、`cargo metadata` 和普通 `npm run` 即使退出码为 0 也只作为诊断结果。只有验证型命令退出码为 0、未超时、未改写受保护文件，且命令日志、manifest 投影和 Agent DB 审计全部成功后，才允许绑定当前 revision 的 passed gate；任一审计失败必须先保持 failed gate，再进入 `needs-reconciliation`。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -1,5 +1,16 @@
 # AI 游戏创作智能体 App 实施计划
 
+## 2026-09-21 Godot 工作区发现放宽与内置插件行去掉手动启动
+
+本节覆盖下文“打开项目自动识别 Godot”中的旧口径：判定从「唯一命中」放宽为「确定性命中」，`project.godot` 从「必须是普通文件」放宽为「按链接目标判定」。
+
+| 要求 | 必须成立的行为 | 完成证据 |
+| --- | --- | --- |
+| 确定性多命中 | 根目录未命中时，一层直接子目录中多个 `project.godot` 命中按目录名排序取第一个；不再报「多个 Godot 项目」，也不再要求用户改选具体工程 | `cargo test --locked -p genarrative-ai-game-creator-shell --bin genarrative-ai-game-creator-shell -- project::manifest::import_tests::` 与 `-- tests::project::` |
+| 链接标记 | `project.godot` 是符号链接 / Windows reparse point / 硬链接时按链接目标判定，目标解析为普通文件即命中；目录与悬空链接仍不算命中 | `import_tests::accepts_symbolic_link_project_marker`（unix）、`import_tests::accepts_windows_hard_link_project_marker`、`import_tests::accepts_windows_reparse_project_marker` |
+| 保持不变的边界 | 工作区根本身是链接、候选子目录是链接、二层及更深目录不递归，这三条既有边界不动 | `import_tests::ignores_symbolic_link_child_candidate_without_writing_agent_metadata`、`import_tests::ignores_windows_reparse_child_candidate_without_writing_agent_metadata`、`import_tests::ignores_godot_projects_below_the_first_child_level` |
+| 内置插件行 | 设置→扩展 的内置插件行不再渲染手动「启动 / 停止」按钮；启动由项目切换时的前端自动启动承担，停止走该行启用开关（禁用即停止并断开编辑器连接）；导入扩展行的启动按钮保留 | `apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx`、`tests/pluginHost.test.ts` |
+
 ## 2026-09-20 DirectProject 七项效率闭环（补齐合同）
 
 本节补齐并覆盖下节中仅靠 Skill 要求预检、收尾、批读和原生命令预算的部分。完整目标仍为：自动预检、宿主验收与收尾、分层验证、统一执行/返修预算、稳定测试基线、请求耗时与批量读取、所有工具并行。已有代码及测试不等于全部目标已完成；按下表逐项验收。
@@ -48,6 +59,8 @@
 ### 宿主验收与执行许可合同
 
 - 正式 GUI 和 CLI 的共同 Direct 回合入口建立宿主控制状态，绑定 canonical 项目路径、稳定 clientTurnId 和原始用户输入摘要；宿主私有目录保存权威账本并独占该回合，项目 `.agent` 仅允许保存展示副本。配置或项目侧文件被改写、工具切换、Provider 重试和进程重启不得刷新同一回合的预算。
+- Direct 回合集成测试也按生产入口计算原始用户输入的 SHA-256 十六进制摘要（64 字符），不能用请求名称替代。用户回显过滤回归继续覆盖实时消息去重、回合起止身份关联及历史落盘过滤。
+- 直接启动 Direct 工具桥的图片生成通知测试，须复用真实宿主执行会话与已登记交付合同夹具，再发起工具请求；继续验证资源提交后发出 manifest 失效通知，以及空提示词被参数校验拒绝且不发通知，不绕过执行许可门禁。
 - 普通聊天与读取不要求交付合同。首次修改、代码执行或付费扩项之前，模型通过结构化工具登记本轮必需范围与验收项；合同非空、有界且只冻结一次。模型只能声明要求，不能提交“通过”作为证据。后续扩项留到新的用户回合。
 - 明确新 Web 创建由宿主可信脚手架凭证及尚未交付的宿主记录判定，CLI 同样据此判定，不从提示文本猜测；这种回合即使模型没有调用工具或没有登记合同，也不得按普通聊天宣布交付。已有项目只有未激活合同且从未产生副作用时才允许直接聊天结束。
 - 验收项为明确类型的产物、构建/测试命令、双端视觉或指定固定场景的双端玩法。可信新 Web 游戏由宿主补充构建、双端视觉和玩法底线，不能由模型声明“已有项目”降低。已有项目按冻结的变更范围选择层级；平台美术只在用户目标要求时成为必需项。
@@ -199,6 +212,7 @@ Rust 侧在 `server-rs/crates/shared-contracts` 维护唯一权威 `GameCreation
 
 ## 资源画布生成、展示与布局合同
 
+- 客户端「生成图标素材」只将用户描述去除首尾空白后，保留内部换行并作为唯一 `iconDescriptions` 元素提交；不添加小游戏首版原型、核心美术或默认美术 brief，不截断、不按段落或字数拆条。面板与原生入口均要求描述非空且最多 `200` 个 Unicode 字符（按码点计数），超限在提交前明确拒绝；其余图片生成提示词维持 `32000` 字符上限。规范图、纯色背景、素材排布等生图约束由网站与客户端共用的 API Server 流程统一添加。完整请求合同见 [画板图标素材生成入口设计](../【编辑器】画板图标素材生成入口设计-2026-06-15.md)。
 - 生成工具点击后先在当前栏目创建临时占位卡，并以卡片为锚点展示独立生成浮层；占位不登记为正式素材、不进入 Agent 可引用资源集。上传仍沿用文件选择，不创建虚假生成任务。关闭编辑浮层不应丢失正在执行的任务；切换项目不得将旧项目结果或草稿写入新项目。
 - 图片生成支持从现有素材选择器添加真实参考；引用携带稳定资源身份并经既有原生权限、归属与类型校验传至生成链路，不能仅拼接名称。缺少规范图不阻止打开面板；确有规范前置的操作必须在提交前满足要求，不能绕过后端校验。用户可通过现有工具栏先生成规范图。
 - 占位可移动。提交复用正式生成任务、幂等与结果登记链路；成功结果使用占位最新位置，失败保留输入与引用供重试。已受理但响应不确定时先对账，不能无条件再次发起付费生成。关闭、删除占位和后台任务的行为需保持既有任务所有权，不把隐藏展示当作取消任务。
@@ -578,7 +592,8 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 模式合同：客户端 AppData 配置新增全局 `agentMode`，只接受 `codex_cli / provider`。缺省和新安装默认使用 `codex_cli`，原有 HTTP LLM Provider 路径完整保留并可显式切回 `provider`；切换只影响下一次节点请求，不新增 Runner、任务图、会话库、配置库或业务事实源。
 - 调度边界：正式 DAG、manifest、Agent task/session/run 身份、队列、锁、委派、all-join、完成门、Provider lifecycle、持久 retry/handoff 与 `needs-reconciliation` 继续由现有 AGC Runtime 掌控。每个被调度节点在 `codex_cli` 模式下直接启动一次非交互 `codex exec` 充当该节点的推理 Agent；Codex 返回当前 Runtime 广告函数的结构化调用，Runtime 仍是唯一 ToolHost，不允许 CLI 自己写项目、执行命令、调用 MCP 或形成第二套 revision / verification 真相。
 - 安装包侧车：Windows x64 release 固定随 Tauri resource 打包 `@openai/codex@0.155.1` 的原生 `codex.exe`；Rust build script 从 AGC 子包锁定依赖 stage 到 resource，并写入版本与 SHA-256 清单。固定版本只在 `build_support/codex_bundle.rs` 声明一次，构建脚本、宿主补丁执行器身份、逐次审批协议允许列表和模型目录捕获共同引用它，避免多处字面量漂移。Windows 侧车映射只写入 `tauri.windows.conf.json`，通用 `tauri.conf.json` 不得让 Linux / macOS 构建依赖未生成的 Windows 二进制。运行时只在文件摘要和 `codex-cli` 版本同时匹配清单时优先选内置侧车；缺失、损坏或版本漂移时跳过它，按既有 npm 安装、PATH 顺序回退。安装包同时携带 Apache-2.0 第三方声明；API Key、`auth.json`、Cookie、Token、用户 `CODEX_HOME`、用户配置和项目数据绝不打包。
-- Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。安装后的产品名、开始菜单 / 桌面快捷方式和 EXE 产品描述统一由 `tauri.conf.json` 的 `productName: "陶泥儿"` 生成；应用 identifier 与内部可执行文件名保持稳定。内置 Codex 资源安装到顶层 `coding-agent/win-x64/`，运行时从同一路径查找 `bin/codex.exe` 与 `manifest.json`；仓库 staging 仍使用 `resources/codex/win-x64/`，包内子目录、组件名、版本和完整性校验保持原合同。
+- Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。安装后的产品名、开始菜单 / 桌面快捷方式和 EXE 产品描述由 `tauri.conf.json` 的 `productName` 生成：基线是 `陶泥儿`，发布构建按渠道由 `--config` 覆盖为 `陶泥儿 <渠道显示名>`，identifier 同批派生 `<基线>.<渠道>`（默认渠道保持基线值），因此不同渠道的包体可在同一台设备并存；内部可执行文件名保持稳定。内置 Codex 资源安装到顶层 `coding-agent/win-x64/`，运行时从同一路径查找 `bin/codex.exe` 与 `manifest.json`；仓库 staging 仍使用 `resources/codex/win-x64/`，包内子目录、组件名、版本和完整性校验保持原合同。
+- Windows 渠道 AppData 目录归属判断及其调用分支统一保留 Windows 条件编译；通用项目路径策略测试仍可在 Linux 运行，实际 ACL 修复保持原平台门禁与授权范围。
 - macOS 安装包必须携带锁定版本的原生 Codex、`codex-code-mode-host`、`rg`、上游 zsh、`codex-package.json` 和第三方声明，保留上游相对布局；构建时按 Cargo 目标选择 npm 原生依赖，缺文件、版本或目标不匹配立即失败，不借用开发机 PATH 里的 Codex。资源只在 `tauri.macos.conf.json` 映射到 `Contents/Resources/coding-agent/mac-native/darwin-arm64/` 与 `darwin-x64/`。构建与运行共享平台文件白名单，运行时由当前 `.app/Contents/MacOS` 定位相邻 `Resources`，完整性与版本验证通过后优先使用内置组件；失败沿既有外部安装回退，不能运行未校验的内置文件。macOS 当前只构建 arm64 单架构，但资源映射仍并列携带两套锁定原生 Codex 依赖（运行切片按 Cargo 目标只选择对应目录），恢复 Intel 时无需改动资源布局；随包 Node 只有宿主架构那一份，所以不得构建 universal 包。不读取全局 Codex。
 - 内置插件的清单、运行入口与面板同时在 Windows/macOS 随包分发，继续由既有 PluginHost 的应用资源目录扫描入口发现；不携带开发依赖、缓存、测试或私有配置。插件文件随包不等于原生适配器跨平台：Cocos 进程桥接仍受现有 Windows 实现和 feature 门禁约束，macOS 原生桥接另行设计与验收，不复制 Windows DLL 冒充支持。系统 Node、用户 Cocos Creator、账号登录、网络和生成工程的 npm 工具链仍是现有外部前提，不在此次 Codex 侧车补齐中隐式变更。
 - macOS 安装包验收必须包括：脱离仓库位置的 `.app` 资源与架构检查、受限 PATH/隔离 HOME 下内置 Codex 启动和 app-server 握手、必需文件缺失/篡改/平台错误的拒绝测试，以及 DMG 完整性检查。真实登录、Provider 对话、GUI 和 Cocos 操作必须独立列出证据，不能用压缩包生成或 `--version` 成功替代。未配置正式签名、公证的本地测试包不得作为公开发行包。
@@ -1783,7 +1798,7 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 本地索引是增量对比的唯一依据：`<AppData>/project-snapshots/<projectId>/index.json` 保存上次成功同步的相对路径、校验和、字节数和修改时间。项目根使用现有 manifest 的稳定 `project_id` 作为远端身份，路径不再作为身份。
 - 可观测性按产品口径收敛到本机日志：同步结果、失败分类、延后与跳过计数只写入 AppData 诊断日志（`project_snapshot.sync.*` 前缀），客户端界面不暴露上传状态、时间线或入口按钮。`read_local_project_snapshot_state` 与 `sync_local_project_snapshot` 两条命令仅作为 native-only 的排障与联调入口登记，不在渲染层调用。
 - 远端写入经 `api-server`，客户端只持平台登录态 Access Token。两条登录态路由：`POST /api/agc/project-snapshots/files`（单文件，正文为原始字节，元数据走查询串）与 `POST /api/agc/project-snapshots/manifest`（本次同步后的完整清单）。
-- 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v1/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v1/{userId}/{projectId}/manifest.json`。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。
+- 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v2/{channel}/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v2/{channel}/{userId}/{projectId}/manifest.json`；`channel` 是本部署渠道（`GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL`，缺省沿用 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`），同一 bucket 因此天然按渠道分区，开发与正式部署互不可见对方项目。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀（含历史无渠道的 `agc/project-snapshots/v1/`）继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。后台“项目工程”按渠道查询与下载，渠道名非法时失败关闭，历史 v1 对象不再列出。
 - 目标 bucket 使用独立配置 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET` / `_ENDPOINT` / `_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`，默认 `agc-dev` + `oss-rg-china-mainland.aliyuncs.com`。只允许凭据回退 `ALIYUN_OSS_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`；bucket 与 endpoint 不跟随资源存储的 `ALIYUN_OSS_BUCKET` / `_ENDPOINT`，避免默认写入其它 bucket。显式快照目标配置继续优先；不自动搬迁其它 bucket 的现存数据。
 
 ### 正常、失败、重试与幂等行为

docs/【功能说明】AGC聊天素材引用-2026-09-08.md

@@ -15,6 +15,8 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材。
 
 提交时前端把 Lexical 草稿直接编码为受限 Response API user `message` item：`input_text` 与 AGC 引用 part 按编辑顺序内联在同一个 `content[]` 中。资源引用只携带稳定 `resourceId`；运行画面引用携带区域语义摘要及关联资源 ID。Rust 是唯一 schema source（通过 `ts-rs` 生成 TypeScript 绑定），在发起回合前完成 item 白名单、字段边界、manifest 归属和路径安全校验；校验失败时本轮不持久化、不发送。通过校验的 canonical item 以 `response_item` envelope 写入项目历史，随后由 Rust 将 AGC part 临时转换为 Codex 可接受的 `input_text`，保持原始 content 顺序。已有标准 `response_item` 原样读取与复用；旧 legacy conversation 行不再提供 fallback。
 
+输入校验按整条消息判断是否有内容：每个 `input_text` 片段都允许是空字符串、空格或换行，不逐片段拒绝，也不合并、删除或改写片段；原始文字、分段和 `content[]` 顺序保持不变。整条消息必须至少包含一段非空白文字，或至少一个通过既有校验的 `agc_resource_reference` / `agc_runtime_region_reference`，否则返回“聊天内容不能为空”。两种引用继续执行原有字段、数量、manifest 归属和路径安全校验；即使消息同时带有正文，非法引用也必须拒绝，不能由正文绕过。
+
 ## 拖拽引用（2026-09-21）
 
 除了 `@` 输入与「引用」按钮，资源卡还支持**拖到对话**：在资源画布上按住一张卡拖到右侧 Agent 对话栏，松手即把这次拖动真正参与位移的那批素材整批 `@` 进输入框（框选多选后拖任意一张 = 整批引用；拖未选中的卡 = 只引用它自己）。

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -147,6 +147,10 @@ revision 变化时，调度管线把同一个完整 commit 通过 `COMMIT_HASH`
 
 手工发布入口 `Genarrative-Manual-Build-And-Deploy` 的 `DEPLOY_TARGET` 与 AGC 更新渠道是两个独立维度。手工入口必须把 `release` 映射为 `AGC_UPDATE_CHANNEL=release`、把 `development` 映射为 `dev`，并把该参数同时透传给 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`；只传 `AGC_RELEASE_VERSION` 时下游会落回各自默认 `dev`。统一号 `0.1.95` 的 release 包应分别位于 `agc/release-win/0.1.95/` 与 `agc/release-mac/0.1.95/`，渠道清单为对应目录下的 `latest.json`，不存在 `agc/release/` 这一层。补发本轮已烧号的版本时，直接以相同 `AGC_RELEASE_VERSION` 重跑两条 AGC Job，不重新发号。
 
+渠道参数同时决定安装身份：默认渠道 `dev` 产出 `productName=陶泥儿` + `identifier=world.genarrative.ai-game-creator`（既有安装与升级链），其它渠道产出 `陶泥儿 <渠道显示名>` + `<基线>.<渠道>`，因此同一台设备可以同时装 `dev` 与 `release` 两个客户端，互不覆盖、数据不共享（渠道与安装身份合同见《AGC客户端更新检查与下载》）。发布后核对发布对象名（如 `agc/release-win/<版本>/陶泥儿 Release_<版本>_x64-setup.exe`）与装机后的卸载项、`%APPDATA%\<identifier>` 是否按渠道分开。
+
+`Genarrative-Agc-Windows-Build` 的 `Tauri NSIS toolchain` 阶段必须在 Rust 编译前预置 NSIS 工具链并失败关闭：tauri-bundler 打包时现场从 GitHub 下载 `nsis-3.11.zip` 与 `nsis_tauri_utils.dll` 且不重试，构建机每次检出都会重下，响应一旦被截断就只能抛 `io: unexpected end of file`，让发布在编译数分钟后才失败。该阶段先跑 `node apps/ai-game-creator-shell/scripts/ensure-nsis-toolset.mjs`（固定 SHA1 校验、4 次重试、解压到 `target/.tauri/NSIS`），再执行 `makensis.exe -VERSION` 验证可执行性；Checkout 的 `git clean -fdx` 必须带 `-e apps/ai-game-creator-shell/src-tauri/target/.tauri`，只保留这份工具缓存、其余 `target/` 内容照常清空，否则工作区内缓存会被每个构建删掉，退回到「每次从 GitHub 重下」（实测裸 `git clean -fdx` 会输出 `Would remove apps/ai-game-creator-shell/src-tauri/target/`）；原始归档缓存在工作区外的 `%ProgramData%\genarrative\tauri-nsis-cache`（可用 `AGC_TAURI_NSIS_CACHE_DIR` 覆盖），因此同一节点只有冷缓存才需要联网，离线补缓存时把这两个文件放进缓存目录即可；构建机确实无法访问 GitHub 时使用 bundler 自带的 `TAURI_BUNDLER_TOOLS_GITHUB_MIRROR_TEMPLATE` / `TAURI_BUNDLER_TOOLS_GITHUB_MIRROR` 指向可达镜像。升级 `@tauri-apps/cli` 时必须同步核对 `nsis-toolset.mjs` 里的归档地址、SHA1 与必需文件清单（与 tauri-bundler 的 `NSIS_REQUIRED_FILES` 逐条对齐），否则预置会被 bundler 判为不完整。
+
 调度状态是调度 Job 工作区里的 `.jenkins-last-triggered-revision`，构建描述同时回显本次 revision 与结果。工作区被清理（例如 `Wipe Out Workspace`）或状态文件缺失时，下一次运行按“版本变化”处理并触发一次，之后恢复稳定；需要重建同一版本时勾选 `FORCE_TRIGGER`。Job 按仓库内 `jenkins/scheduled-revision-trigger-job-config.xml` 创建：`scriptPath=jenkins/Jenkinsfile.scheduled-revision-trigger`、Git 入口 `ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git`、凭据 `genarrative-local-gitea-ssh`、`<triggers/>` 留空（定时器写在 Jenkinsfile 里）。推送后必须让三个 live Job 各自加载一次新 Jenkinsfile，并只读核对 `config.xml`：Full 与 AGC 不再有 cron，定时只来自新调度 Job；只改 Jenkinsfile 而不确认 live 配置时，旧 cron 仍会继续触发。
 
 Full Job 通过 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 明确选择完整发布成功后是否退出维护，默认勾选以保持历史行为。Full 对 Stdb Publish 和 API Deploy 两个下游阶段都固定传 `KEEP_MAINTENANCE_MODE=true`，让 maintenance marker 持续覆盖 Stdb → API → Web 整段发布；Web Deploy 成功后才进入独立 `Exit Maintenance` 阶段。该阶段只能通过 `agent none` 和显式 `node(...)` 分配目标机，直接执行 `/opt/genarrative/current/scripts/deploy/maintenance-off.sh`；目标机不得 checkout Git、挂载 Git SSH 凭据或依赖 Jenkins workspace 源码。取消勾选时跳过最终退出阶段，便于内网验收完成后人工恢复公网。`Genarrative-Api-Deploy` 也单独暴露 `KEEP_MAINTENANCE_MODE` 参数，并转换为随发布包脚本的 `--keep-maintenance-mode`；失败路径仍按既有 current 切换边界保留或退出维护，不受成功态选项覆盖。外部生成 queue 的 `warning` 由 API/worker 固化为可直接展示的完整文案，Web 不再补前缀，因此 API/worker 与 Web 必须在同一维护窗口按同一版本协调发布；分开运行 Job 时先保持维护态完成 API/worker，再发布 Web，二者完成后才能恢复公网，不得在公网可用期间只滚动其中一侧。
@@ -550,7 +554,7 @@ curl -fsS --max-time 5 http://127.0.0.1/api/editor/showcase/resources >/dev/null
 
 ### AGC 项目快照上传目标
 
-后台“项目工程”（`/admin/#project-snapshots`）按项目列出远端快照。完整快照提供“下载完整工程”，按原始目录返回 ZIP；未完成同步的项目暂不可下载，旧清单缺少完整性声明时显示“完整性未知”，只能“下载已存文件”。不要直接把 OSS 的 `files/{size}-{digest}/` 目录下载当成工程。
+后台“项目工程”（`/admin/#project-snapshots`）按项目列出远端快照，默认只看本部署渠道，顶部“渠道”选择框可切换远端已存在的其它渠道；列表按游标分页（每页 20/50/100，上一页复用已取得的游标，远端不给总数所以只显示当前页）。完整快照提供“下载完整工程”，按原始目录返回 ZIP；未完成同步的项目暂不可下载，旧清单缺少完整性声明时显示“完整性未知”，只能“下载已存文件”。“用户”列与“素材查询”同口径展示昵称与陶泥号，并可点开用户详情；不要直接把 OSS 的 `files/{size}-{digest}/` 目录下载当成工程。
 
 自动上传以原生登记的活动工程为准：打开即首传、每 300 秒周期同步、切换/关闭补传。排障同时核对 AppData `project-snapshots` 索引、`project_snapshot.sync.*` 日志和远端清单；只有测试项目的历史清单不能证明现役项目同步生效。前端在同一窗口内切项目时必须登记生命周期，不能只检查 URL 是否包含 `projectPath`。
 
@@ -559,15 +563,23 @@ curl -fsS --max-time 5 http://127.0.0.1/api/editor/showcase/resources >/dev/null
 AGC 客户端按周期与项目关闭时机把用户项目增量上传到 `agc-dev`。客户端只持有平台登录态 Access
 Token，经 `POST /api/agc/project-snapshots/files`（单文件原始字节）与
 `POST /api/agc/project-snapshots/manifest`（本次同步清单）交给 `api-server`，由服务端写入私有前缀
-`agc/project-snapshots/v1/{user}/{project}/`；客户端不直连 OSS，也不持有 OSS 凭据。
+`agc/project-snapshots/v2/{channel}/{user}/{project}/`；`channel` 是本部署渠道，客户端不上报渠道、也不直连 OSS，
+因此同一 bucket 可以由开发与正式两套部署分别落在 `dev/` 与 `release/` 下。
 
 ```env
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET=agc-dev
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ENDPOINT=oss-rg-china-mainland.aliyuncs.com
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_ID=
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_SECRET=
+GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL=dev
 ```
 
+`GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL` 未配置时沿用 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`（缺省 `dev`）；
+正式部署必须显式设成 `release`，否则正式上传会写进 `dev/` 渠道。渠道名必须是小写字母开头的
+小写字母 / 数字 / 连字符（≤32 字符），非法时上传与后台查询都返回 `503`/`400`，不会回落到别的渠道。
+历史无渠道前缀 `agc/project-snapshots/v1/` 只保留对象、不再写入也不再进入后台列表；需要取回历史对象时
+按旧前缀直接在 OSS 侧读取。
+
 专用凭据为空时回退 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，bucket 与 endpoint
 仍默认指向 AGC 发行 bucket，因此回退凭据必须具备目标 bucket 该前缀的 `PutObject` / `GetObject` /
 `DeleteObject` 权限；`api-server` 启动时会打印一行 `AGC 项目快照 OSS 客户端已启用`（含 bucket、
@@ -576,7 +588,7 @@ endpoint 与凭据来源，不含密钥），凭据缺失或只配一半则跳
 
 远端占用按当前清单收敛：每次清单写入成功后，服务端用上一版清单反推不再被引用的对象键并删除，单次最多
 回收 2000 个，上一版清单不可读时整轮跳过（不会误删）。因此不需要额外配置 bucket 生命周期来防止无界
-增长；`agc/project-snapshots/v1/` 下同一路径只保留当前内容，历史版本不保留。配额口径：单文件 64 MiB、
+增长；`agc/project-snapshots/v2/{channel}/` 下同一路径只保留当前内容，历史版本不保留。配额口径：单文件 64 MiB、
 单次同步上传预算 512 MiB、单项目常驻 2 GiB；超限分别表现为跳过/延后/413。服务端另有进程内小时配额
 （文件 3000 次、清单 120 次）与同一项目 5 秒最小清单间隔，超限返回 `429` 并带 `Retry-After`。
 
@@ -734,7 +746,7 @@ Mac 单架构（arm64）构建脚本位于 `jenkins/Jenkinsfile.ai-game-creator-
 
 Job 名为 `Genarrative-Agc-MacOS-Build`，SCM 直接读取仓库内上述 Jenkinsfile，参数为 `SOURCE_BRANCH`、`COMMIT_HASH`、`AGC_UPDATE_CHANNEL`、`AGC_RELEASE_VERSION`、`AGC_RELEASE_DRY_RUN`、`AGC_UPDATE_RELEASE_NOTES`、`OSSUTIL_BIN`、`CARGO_BUILD_JOBS`、`NOTIFICATION_EMAILS`。渠道参数是基础名（不含系统，默认 `dev`），脚本不接受 `dev-mac` 这类系统后缀，写入分区固定推导为 `<channel>-mac`：这与 Windows Job 的 `<channel>-win` 对称，也延续已发布客户端的端点。
 
-该 Job 的职责是构建并发布 `<channel>-mac` 分区更新：执行 `npm ci` 后使用锁文件校验并补齐两种 macOS Codex 原生依赖，再调用 `scripts/build-macos-ci.mjs`（AGC 应用目录下）生成 arm64 单架构 app、arm64 隔离 smoke、arm64 DMG（`<产品名>_<版本>_aarch64.dmg`）与分区清单 `latest.json`，用产物内烘焙的公钥复核更新包签名（`verify-updater-signature.mjs`），最后按 `AGC_RELEASE_DRY_RUN` 决定是否上传 OSS。签到会同时取 `master`，让渠道清单里上一次发布的 commit 可解析——缺了它更新摘要会退化成「最近客户端改动」（该步失败只降级摘要，不阻断发布）。产物名（`*.app`、updater 归档、DMG、卷名）一律从 Tauri `productName` 推导，校验脚本从包内 `Info.plist` 读取可执行名，改产品名不会让入口静默找错对象；隔离 smoke 用 `ditto --clone` 复制副本（实测整轮 6.8 秒，此前整包复制约 1 分钟），并在构建前删除本次将写出的 DMG/更新包/签名，保证归档产物一定来自本次构建。归档限 `artifacts/` 下的 DMG、SHA-256、`latest.json`、更新包签名、更新摘要、非敏感构建清单和源码 commit；不归档用户 HOME、Jenkins secret、原始工作目录或全量日志。
+该 Job 的职责是构建并发布 `<channel>-mac` 分区更新：执行 `npm ci` 后使用锁文件校验并补齐两种 macOS Codex 原生依赖，再调用 `scripts/build-macos-ci.mjs`（AGC 应用目录下）生成 arm64 单架构 app、arm64 隔离 smoke、arm64 DMG（`<产品名>_<版本>_aarch64.dmg`）与分区清单 `latest.json`，用产物内烘焙的公钥复核更新包签名（`verify-updater-signature.mjs`），最后按 `AGC_RELEASE_DRY_RUN` 决定是否上传 OSS。签到会同时取 `master`，让渠道清单里上一次发布的 commit 可解析——缺了它更新摘要会退化成「最近客户端改动」（该步失败只降级摘要，不阻断发布）。产物名（`*.app`、updater 归档、DMG、卷名）一律从渠道安装身份派生的产品名推导（默认渠道即基线 `productName`，`release` 等渠道带渠道后缀），校验脚本从包内 `Info.plist` 读取可执行名，改产品名或换渠道都不会让入口静默找错对象；隔离 smoke 用 `ditto --clone` 复制副本（实测整轮 6.8 秒，此前整包复制约 1 分钟），并在构建前删除本次将写出的 DMG/更新包/签名，保证归档产物一定来自本次构建。归档限 `artifacts/` 下的 DMG、SHA-256、`latest.json`、更新包签名、更新摘要、非敏感构建清单和源码 commit；不归档用户 HOME、Jenkins secret、原始工作目录或全量日志。
 
 发布凭据全部走 Jenkins 全局凭据，并在 `withCredentials` 内注入当前进程：`AgcUpdaterSigningKey`（与 `AgcUpdaterSigningKeyPassword`）映射为 `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，`AliyunAccessKeyId` / `AliyunaccessKeySecret` 映射为 `AGC_OSS_ACCESS_KEY_ID` / `AGC_OSS_ACCESS_KEY_SECRET`；私钥与凭据不写入 workspace、日志或归档产物。上传顺序为更新包、签名、首装包，三者全部成功后才覆盖 `agc/<channel>-mac/latest.json` 指针；`AGC_RELEASE_DRY_RUN` 与 Windows 渠道对称：默认关闭即真发布，勾选后才退化为演练（只打印将上传的对象、不写任何 OSS 对象）。本 Job 是正式发布入口，调度器在发号后与 Windows 一起触发它，并额外传 `SKIP_IF_SUPERSEDED=true`——Mac 节点是日常办公机，离线期间排队的旧构建在节点回来后若已被源码分支推进，直接跳过而不发布过期版本。Mac 节点需要 `ossutil`（实测 1.7.19 原生 arm64 可用，装在 `~/.local/bin`，已在 Job 的 PATH 内），可用 `OSSUTIL_BIN` 指定命令名或绝对路径。首次发布建议显式指定 `AGC_RELEASE_VERSION`，避免按渠道高水位递增时出现版本链回退。
 

docs/【模板规范】AGC模板包组织指南-2026-09-21.md

@@ -0,0 +1,124 @@
+# 【模板规范】AGC 模板包组织指南
+
+给准备 AGC（AI 游戏创作）游戏模板的人：说明模板源目录与成品 ZIP 该怎么组织、什么东西不能放、发布前怎么自检。
+
+权威合同仍是 [`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`](technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)（发布协议、锁、版本门禁、后台接口都在那里）；本文件只讲「内容怎么组织」。
+
+## 一句话契约
+
+**ZIP 的根目录 == 建项后用户项目的根目录**：解压出来看到什么，用户项目里就有什么（例如 `game/index.html`、`package.json`），不要再套一层 `my-template/` 目录。
+
+## 两条发布路径
+
+| 路径 | 输入 | 适用场景 |
+| --- | --- | --- |
+| CLI 发布 | 源目录 `v1/<id>/{meta.json, project/**, cover.(png\|jpg\|jpeg\|webp\|svg)}`，其中 `project/**` 就是 ZIP 根 | 仓库内长期维护、确定性打包、`--only` 定向发布 |
+| 后台「上传模板」 | 成品 ZIP + 同 ID 封面 + 表单元数据，一批最多 20 个 | 一次性上传，不依赖本地仓库 |
+
+CLI 打包规则：递归收集 `project/**` 下的普通文件（按条目名排序、固定时间戳，同一份内容重复打包摘要一致），只接受普通文件与目录，遇到符号链接等其它类型直接报错。
+
+## ZIP 内容规则
+
+### 必须满足
+
+- 根目录就是项目根；`entry` 是相对 ZIP 根、不以 `/` 开头、不含 `..`、不含空白或控制字符的路径。
+- ZIP 必须包含 `entry` 指向的文件，并且至少有一个文件（空 ZIP、只含目录的 ZIP 都会被拒绝）。
+- 条目不能用绝对路径、盘符、反斜杠或 `..`；不允许符号链接。
+
+### 建议结构（html / three.js / phaser 一类）
+
+```text
+game/index.html        # entry，推荐
+game/game.js
+game/style.css
+game/package.json      # 可选
+game/vite.config.js    # 可选
+assets/…              # 可选
+```
+
+- 建项时会在复制模板文件之后补齐 `game/`、`assets/`、`memory/`、`memory/agents/`、`exports/`，并创建 `.agent/` 清单；这些目录不用在模板里手工占位。
+- 模板没有 `game/index.html` 时，建项会写入一份默认入口占位页；所以 html 类模板应当自带 `game/index.html`，并把 `entry` 填成 `game/index.html`。根目录的 `index.html` 不会被当成游戏入口（建项仍会补默认 `game/index.html`），不要用这种结构。
+
+### Godot 项目（`runtime=godot`）
+
+- 根目录直接放 Godot 工程：`project.godot`（此时 `entry` 用 `project.godot`）、`scenes/`、`scripts/`、`icon.svg`、`.gitignore` 等，`.import` / `.uid` 之类由引擎生成的伴生文件不必手工准备。
+- `project.godot` 要能独立打开：`config_version=5`，且 `[application]` 段的 `run/main_scene` 指向工程内真实场景。建项会把 `config/name` 改写成用户选择的项目名（只改这一行），模板里的名字只是初始值。
+- 目标版本是 Godot 4.7：`config/features=PackedStringArray("4.7", "GL Compatibility")` 配套 `renderer/rendering_method="gl_compatibility"` 兼容面最大，2D 与轻量 3D 模板都用这一套。
+- 建项按 `project.godot` 识别 Godot 模板，写入 `godotProjectRoot: "."`，不生成 `game/` 占位入口与 `assets/`、`memory/`、`exports/` 并行目录。
+- 不要打包 `.godot/` 编辑器与导入缓存、导出产物（`export/`、`build/`）；模板正文保持「克隆下来直接就能打开」的源状态。
+- 输入优先只用 Godot 内置的 `ui_*` 动作；需要自定义动作时把 `[input]` 段写进 `project.godot`，不要让模板依赖开发者本机的输入映射。
+- 建议不引入外部贴图与音频，用 `Polygon2D`、`ColorRect`、`BoxMesh` 一类节点搭出可见骨架，避免模板源里出现难以复核的二进制素材。
+
+### Cocos Creator 项目（`runtime=cocos`）
+
+- 根目录直接放 Creator 工程：`package.json`（此时 `entry` 用 `package.json`）、`assets/`、`settings/`、`profiles/`、`.creator/`、`tsconfig.json`、`.gitignore` 等官方结构**原样保留**，`.meta` 与导入设置必须一起带上，否则导入后资源关系会丢。
+- `package.json` 必须带 `creator.version`（当前模板库口径是 3.8.8）；建项时会重写 `package.json` 的 `name` 与 `uuid`，模板里的这两个值不会出现在用户项目里。
+- 空工程用 `assets/.gitkeep` 之类的占位文件保证空资源目录能进 ZIP。
+- 不打包编辑器缓存与构建产物：`library/`、`temp/`、`local/`、`build/`，以及任何用户项目数据。
+
+### 不要放进 ZIP
+
+- `node_modules/`、`dist/`、构建产物、打包缓存。
+- `.git/`、`.svn/`、`.vscode/`、`.idea/` 等工程外元数据。
+- `.agent/`：项目身份、对话账本和 `.agent/manifest.json` 由建项流程生成；模板自带会让新项目继承一个陌生身份。
+- 密钥、Token、`.env*`、个人绝对路径、日志文件。
+- 嵌套的 `package-lock.json`：模板工程内嵌锁文件已在 2026-09-17 清理，需要锁文件请在用户项目里自行生成。
+- 符号链接与任何非普通文件。
+
+### 路径与体积上限
+
+| 项 | 上限 |
+| --- | --- |
+| ZIP 内路径 | 相对路径，无 `..`、盘符、反斜杠、空白与控制字符 |
+| 条目数 | ≤ 4096 |
+| 单个文件（解压后） | ≤ 256 MiB |
+| 解压后总量 | ≤ 512 MiB |
+| ZIP 体积 | 客户端下载 ≤ 512 MiB；后台「上传模板」≤ 64 MiB（更大请走 CLI） |
+| 清单体积 | ≤ 4 MiB（模板条目很多时注意） |
+
+## 封面
+
+- 必须每个模板一张。后台页面**按文件名匹配**模板 ID：`cocos-empty-2d.zip` ↔ `cocos-empty-2d.png`；CLI 源目录下则必须恰好一张 `cover.(png|jpg|jpeg|webp|svg)`。
+- 后台**上传**只接受真实 PNG / JPEG / WebP（按字节嗅探，不信任浏览器声明的 content-type）；SVG 只用于 CLI 发布的历史模板。
+- 上限：≤ 5 MiB、单边 ≤ 4096 像素、≤ 1600 万像素；建议 960×540，与现有模板一致。
+
+## 元数据字段
+
+| 字段 | 约束 |
+| --- | --- |
+| `id` | `^[a-z0-9][a-z0-9._-]{0,63}$`；CLI 下目录名必须等于 `meta.id` |
+| `title` | 非空；后台编辑上限 80 字符 |
+| `summary` | 可空；后台编辑上限 1000 字符 |
+| `tags` | CLI 要求非空字符串数组；去重后 ≤ 16 个、每个 ≤ 32 字符 |
+| `runtime` | 只能是 `html` / `unity` / `godot` / `cocos` |
+| `engine` / `engineVersion` | 可空；例如 `cocos-creator` / `3.8.8`、`three.js` / `0.180.0` |
+| `templateVersion` | `^[a-z0-9][a-z0-9._-]{0,31}$`；新模板从 `0.1.0` 起 |
+| `entry` | 见上，必须是 ZIP 内真实存在的文件 |
+| `coverWidth` / `coverHeight` | 可选；建议填真实尺寸，后台路径按上传图片实际尺寸记录 |
+
+## 版本与不可变
+
+- 同一 `id` 同一 `templateVersion` 的 ZIP 字节**不可变**：改了内容必须递增 `templateVersion`，否则 CLI 与后台上传都会拒绝并提示递增版本。
+- 发布不删除历史对象；下架只是把条目移进 `inactiveTemplates`，历史版本仍可按旧对象键下载。
+- 只改名称、简介、标签、封面或上下架 → 用后台「编辑」，不必动版本；改了包内容 → 递增版本。
+
+## 发布前自检
+
+1. 核对 ZIP 结构：`unzip -l your-template.zip`，确认没有外层目录、`entry` 存在、没有 `.agent/`、`.git/`、`node_modules/`、`dist/`（Godot 模板另需确认没有 `.godot/`）。
+2. 核对体积与条目数（见上表）。
+3. CLI 路径：`node scripts/agc-template-library-publish.mjs --source <dir> --dry-run` 查看合并计划与摘要，确认后再去掉 `--dry-run`。
+4. 后台路径：上传页逐行核对 ID / 名称 / 版本 / 运行时 / entry，确认封面已按 ID 匹配。
+5. 发布后匿名核验清单：`curl -s https://agc-dev.oss-rg-china-mainland.aliyuncs.com/templates/index.json`。
+6. 首次上架后，在客户端「模板库」里搜到该模板并实际建一次项目。
+
+## 已知边界
+
+- 上面「不要放进 ZIP」的目录里，**身份 / 版本库 / 依赖 / 构建产物已有机器门禁**：任意层级的 `.agent/`、`.git/`、`.svn/`、`node_modules/`，以及根目录的 `dist/`、`build/`、`library/`、`temp/`、`local/`、`.idea/`、`.vscode/`，都会在发布前被拒绝——CLI 在收集正文时就报错，后台「上传模板」在任何写入之前整批拒绝，不会出现「传上去了才发现」。同名目录段只在根目录受限，所以正文内的 `game/dist/**` 属于模板自身内容，不会被拦。
+- 门禁只覆盖上面列出的目录。其余内容（`.env*`、密钥、日志、个人绝对路径等）仍依赖模板作者遵守本指南：ZIP 里放了什么，建项后用户项目里就有什么（只有安装标记 `installed.json` 不会被复制）。
+- 客户端按 `installedVersion != templateVersion` 判断是否需要更新；同版本换内容不会触发更新，所以改了字节就必须递增版本。
+
+## 相关文档
+
+- 主规范：[【技术方案】AGC 模板库与模板建项](technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)（含「后台模板管理」「后台模板上传」章节）。
+- 模板库说明（发布到 OSS `templates/README.md` 的源）：[`apps/ai-game-creator-shell/template-library/README.md`](../apps/ai-game-creator-shell/template-library/README.md)。
+- 发布脚本：[`scripts/agc-template-library-publish.mjs`](../scripts/agc-template-library-publish.mjs)。

docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md

@@ -2,7 +2,7 @@
 
 日期：`2026-06-15`
 
-更新时间：`2026-09-17`
+更新时间：`2026-09-21`
 
 ## 背景
 
@@ -40,6 +40,8 @@
 ## 生成契约
 
 - 前端提交到 `POST /api/editor/icon-spritesheets/generations`。
+- AGC 客户端资源画布的「生成图标素材」与网站画布共用服务端图集生成与提示词流程。客户端只去除描述首尾空白，将保留内部换行的完整原文作为唯一 `iconDescriptions` 元素提交；不追加“Web 小游戏首版原型”“核心美术素材”或默认美术 brief，不静默截断，也不按换行或固定字数拆成多项绕过单项上限。
+- 客户端面板和原生提交均按去除首尾空白后的描述校验：不能为空，最多 `200` 个 Unicode 字符（按码点计数）。空白与 API Server 的 Rust `str::trim` 一致，使用 Unicode `White_Space`，不套用普通图片入口额外的控制字符限制。超限明确拒绝并保留输入全文，不能只截取前 `240` 字符或把包装后的提示词截进 `200` 字符；其它客户端图片生成仍保留 `32000` 字符上限。单项最多 `200` 码点自然满足现有数组、聚合字符与 UTF-8 字节上限。服务端的规范图、背景、排列和切图要求在描述校验后统一加入，不占请求描述的长度额度；现有 API 数组与聚合上限不变。
 - 图集拆分模式必须由调用方显式声明，任何入口都不得存在隐式默认值：`sliceMode` 是图标图集生成请求的必填字段，`connected-components` 按透明像素连通域切分，`grid` 按调用方提供的 `gridX × gridY` 网格切分。
 - 请求缺失 `sliceMode`、传 `null` 或空字符串时，`POST /api/editor/icon-spritesheets/generations` 与 `POST /api/external/v1/editor/icon-spritesheets/generations` 都必须在引用解析、定价、入队和任何 provider / OSS 副作用之前返回 `400`，错误体带 `field=sliceMode`，message 复述本节的决策要求；服务端不得用兜底模式继续执行，也不得为该字段保留默认值。
 - `grid` 必须同时提供 `gridX` 与 `gridY`（各 `1..32`，乘积不得超过当时生效的图集切片上限）；只提供其中一个、越界或乘积超限同样在副作用之前 `400`。
@@ -110,6 +112,7 @@
 - 点击 `生成图标素材` 后出现一叠空白图标占位和图标素材面板。
 - `图标规范 -> 从画布中选择` 只能选择图标规范图，点击普通图片或角色规范图不会绑定。
 - 默认提示文本会完整进入 prompt；用户输入不再被解析为素材数量。例如“各种敌人头像：骷髅 哥布林 强盗 龙 蝙蝠等”只是一段完整需求，不代表必须生成或拆出 `6` 个素材。
+- 客户端提交含中文、补充平面字符和内部换行的合法描述时，`iconDescriptions` 只有一个元素且等于去除首尾空白后的原文；`200` 个 Unicode 字符通过，`201` 个字符和全空白描述在付费提交前被拒绝。其它图片入口继续接受大于 `200`、不超过 `32000` 字符的提示词。
 - 默认打开图标素材面板时选中 `nanobanana2 / 1:1 / 1K`；模型切换后，角色和图标素材面板之间沿用上次选择的模型。
 - 图标素材生成请求必须带 `model`、`aspectRatio` 和 `imageSize`；`nanobanana2` 请求体必须包含 `generationConfig.imageConfig.aspectRatio/imageSize`，`gpt-image-2` 请求必须包含文档映射后的 `size`。
 - 图标素材面板可选择 `style: "none" | "pixelArt"`；`none` 完整保持原处理路径，且提交给 provider 的提示词与未带该字段时逐字一致，`pixelArt` 在提示词末尾追加「每个图标素材均为像素风格」并在 Alpha 回贴后、自动拆分前执行内存像素规整，直接持久化整数倍放大后的透明图集；该图集宽高比等于逻辑图、尺寸接近规整输入，最终 OSS PUT、项目资源、图集画布项和切片画布项数量不得因此增加。