新增模板包组织规范并接入文档索引

- 新增 docs/【模板规范】AGC模板包组织指南-2026-09-21.md：ZIP 根目录契约、html 与 Cocos 工程的建议结构与保留项、禁止放入的内容（.agent/.git/node_modules/dist/密钥/嵌套锁文件）、路径与体积上限、封面要求、元数据字段约束、版本不可变规则与发布前自检清单 - 说明两条发布路径的输入差异（CLI 源目录 vs 后台成品 ZIP 上传）与各自上限，并标注「工具不会自动拦截 .agent/.git」这一已知边界 - 主规范与模板库 README（会发布到 OSS templates/README.md）各加一条指向该指南的入口 - docs/README.md 登记新文档，check:doc-index 通过（194 份）
2026-09-21 16:16:21 +08:00
parent 15e7d6065e
commit b5e1c0f1d6
4 changed files with 116 additions and 0 deletions
@@ -7,4 +7,5 @@
 - 客户端只信任「受信任 OSS 主机 + 对象键」，清单里的地址字段不参与请求；下载后强校验包大小与 SHA-256，安装完成的唯一判据是模板目录里的 `installed.json`。
 - 这份文件就是线上 `templates/README.md` 的源：内容随每次发布覆盖写，所以改契约要改这里，不要只改线上对象。
 - 契约与验收以仓库文档 `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md` 为准；模板源在 `apps/ai-game-creator-shell/template-library/`，发布用 `node scripts/agc-template-library-publish.mjs --source apps/ai-game-creator-shell/template-library [--dry-run] [--only <id,id,...>]`（脚本现场打包 zip、按内容地址上传、逐个回读校验、持锁提交清单）。
+- 准备新模板（ZIP 里放什么、不能放什么、封面与元数据约束、发布前自检）先读 `docs/【模板规范】AGC模板包组织指南-2026-09-21.md`。
 - 同一个 `templateVersion` 的 ZIP 字节发生变化时发布会失败关闭，必须递增该模板的 `templateVersion`；发布不删除历史对象，历史版本仍可按旧键下载。
@@ -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)：当前工作台页面和验收边界。
@@ -78,6 +78,7 @@ 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/` 现场打包（条目排序、固定时间戳，同内容重复打包摘要一致）。
+- 模板包内容怎么组织（根目录结构、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`。失败不回收已上传对象，旧清单及其引用始终可读。
 - 只更新指定模板时使用 `--only <id,id,...>`，在发布锁内读取最新清单，只替换指定 ID，其余条目和未知扩展字段保留。首次清单 404 可由本次选择初始化；读取异常或清单非法时停止。全量发布也遵守相同锁与版本门禁。
 - `templates/README.md` 与上述正文不同：它不是内容寻址对象，而是**覆盖写的说明文档**，源在仓库 `apps/ai-game-creator-shell/template-library/README.md`（上限 64 KiB），由同一次发布在清单之前写入并回读校验。客户端从不读它，改契约只改仓库源即可，不要再手工维护线上副本。
@@ -0,0 +1,113 @@
+# 【模板规范】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`），不要用这种结构。
+
+### 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/`。
+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. 首次上架后，在客户端「模板库」里搜到该模板并实际建一次项目。
+
+## 已知边界
+
+- 当前工具**不会**自动拦截 `.agent/`、`.git/`、`node_modules/` 这类目录：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)。