From b5e1c0f1d6ce256dd681e20851220d770b93add7 Mon Sep 17 00:00:00 2001 From: kdletters <61648117+kdletters@users.noreply.github.com> Date: Mon, 21 Sep 2026 16:16:21 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=A8=A1=E6=9D=BF=E5=8C=85?= =?UTF-8?q?=E7=BB=84=E7=BB=87=E8=A7=84=E8=8C=83=E5=B9=B6=E6=8E=A5=E5=85=A5?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=B4=A2=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 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 份） --- .../template-library/README.md | 1 + docs/README.md | 1 + ...技术方案】AGC模板库与模板建项-2026-09-17.md | 1 + ...模板规范】AGC模板包组织指南-2026-09-21.md | 113 ++++++++++++++++++ 4 files changed, 116 insertions(+) create mode 100644 docs/【模板规范】AGC模板包组织指南-2026-09-21.md diff --git a/apps/ai-game-creator-shell/template-library/README.md b/apps/ai-game-creator-shell/template-library/README.md index 692abfbfc..5c2a69162 100644 --- a/apps/ai-game-creator-shell/template-library/README.md +++ b/apps/ai-game-creator-shell/template-library/README.md @@ -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 ]`（脚本现场打包 zip、按内容地址上传、逐个回读校验、持锁提交清单）。 +- 准备新模板（ZIP 里放什么、不能放什么、封面与元数据约束、发布前自检）先读 `docs/【模板规范】AGC模板包组织指南-2026-09-21.md`。 - 同一个 `templateVersion` 的 ZIP 字节发生变化时发布会失败关闭，必须递增该模板的 `templateVersion`；发布不删除历史对象，历史版本仍可按旧键下载。 diff --git a/docs/README.md b/docs/README.md index 63f7d95a5..baaa5723f 100644 --- a/docs/README.md +++ b/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)：当前工作台页面和验收边界。 diff --git a/docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md b/docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md index 111dfa757..67e327bde 100644 --- a/docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md +++ b/docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md @@ -78,6 +78,7 @@ templates/ - 所有对象键必须落在 `templates/` 前缀内；客户端只用「受信任 OSS 主机 + 对象键」自行拼 URL，**不直接信任清单里的地址**。 - 任何一项校验失败（schema、标识符、sha256、尺寸、键前缀）都让整次清单读取失败，前端拿到的是全有或全无的清单。 - 模板源在仓库 `apps/ai-game-creator-shell/template-library/`：`v1//{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 ]`。ZIP、封面和元数据分别以自身字节的 SHA-256 定位，只创建新对象或复用逐字节校验一致的已有对象；全部对象回读一致后才更新 `index.json`。失败不回收已上传对象，旧清单及其引用始终可读。 - 只更新指定模板时使用 `--only `，在发布锁内读取最新清单，只替换指定 ID，其余条目和未知扩展字段保留。首次清单 404 可由本次选择初始化；读取异常或清单非法时停止。全量发布也遵守相同锁与版本门禁。 - `templates/README.md` 与上述正文不同：它不是内容寻址对象，而是**覆盖写的说明文档**，源在仓库 `apps/ai-game-creator-shell/template-library/README.md`（上限 64 KiB），由同一次发布在清单之前写入并回读校验。客户端从不读它，改契约只改仓库源即可，不要再手工维护线上副本。 diff --git a/docs/【模板规范】AGC模板包组织指南-2026-09-21.md b/docs/【模板规范】AGC模板包组织指南-2026-09-21.md new file mode 100644 index 000000000..18bfa39b7 --- /dev/null +++ b/docs/【模板规范】AGC模板包组织指南-2026-09-21.md @@ -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//{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 --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)。