@66rpg/cgmaker 0.1.23 → 0.1.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +27 -25
  2. package/dist/index.js +40 -51
  3. package/dist/validate.js +1 -1
  4. package/package.json +2 -2
  5. package/share/run-logic.mjs +1 -1
  6. package/skill/cgmaker/SKILL.md +120 -131
  7. package/skill/cgmaker-identity/SKILL.md +44 -45
  8. package/skill/cgmaker-identity/references/branches.md +123 -163
  9. package/skill/cgmaker-identity/references/fields.md +64 -64
  10. package/skill/cgmaker-template-spec/SKILL.md +11 -10
  11. package/skill/cgmaker-template-spec/references/layout.md +27 -19
package/skill/cgmaker-identity/references/branches.md CHANGED
@@ -1,163 +1,123 @@
1
- # 业务场景与参数配置指南
2
-
3
- 本文档面向真实用户，详细介绍不同业务场景下命令行功能参数的选择与搭配规则，以及各参数值如何影响发布和构建流程。
4
-
5
- 发布前请先确认两件事：
6
-
7
- - **模板、开源工程**：上传不含 `node_modules`，`package.json` 里的依赖须能公开安装、版本真实可用。
8
- - **模板、游戏、开源工程**：运行时只用本地资源，不要用 CDN 或其它在线地址。
9
-
10
- ---
11
-
12
- ## 1. 模板发布业务场景
13
-
14
- 发布模板时，工具会根据当前工程是否已在平台登记，以及你所提供的命令行参数自动决定业务流向。
15
-
16
- ### 场景 1.1：首次发布全新模板
17
-
18
- 当你的模板工程从未在平台发布过，准备首次上架时：
19
-
20
- - **方式 A：完整首次发布（代码 + 素材）**
21
- - **适用场景**：模板开发完毕，既有完整代码逻辑，也有配套的基础内容或示范素材。
22
- - **前置准备**：`package.json` 中已配置好 `slug`、`version` 与 `data_ver`（工具强制校验必填）。另需平台模板名：`--name` 或 `package.json.name`，不能含 `/` 或 `@`；都没有时会要求输入，不会用 `slug` 顶上。
23
- - **命令示例**：
24
- ```bash
25
- # 显式传入版本号
26
- npx cgmaker publish-template --version 0.1.0 --with-assets --data-ver 1 --data-summary "示范关卡"
27
-
28
- # 或直接使用 package.json 中配置的默认版本号
29
- npx cgmaker publish-template
30
- ```
31
- - **参数说明**：
32
- - `--version 0.1.0`：定义模板首发版本的代码版本号（未传时默认读取 `package.json` 的 `version`）。须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝发布。
33
- - `--data-ver 1`：定义首发素材包的版本编号（未传则读 `package.json` 的 `data_ver`，不写回；显式指定且上传成功后才写回）。
34
- - 可选 `--data-summary <说明>`：本包说明，写入 `data/create` 的 `summary`。不传或空则不写该字段。
35
- - 可选 `--assets <绝对路径>`：如果素材文件不在工程根目录默认的 `assets/` 下，可通过此参数指定实际的本地绝对路径（出现即视为要上传）。
36
- - 可选 `--with-assets`：即使该 `data_ver` 已有包也再传一包。首发该 `data_ver` 尚无包且本地有 `assets/` 时会自动上传，不必加。
37
- - **业务逻辑**：平台将为模板创建全新的模板信息；若本次带数据包则上传素材包，并生成第一个模板发布版本。
38
-
39
- - **方式 B：仅初始化模板代码框架（暂不带素材）**
40
- - **适用场景**：先在平台上建立模板框架，稍后再补充素材，或该模板本身不需要素材包。
41
- - **命令示例**：
42
- ```bash
43
- npx cgmaker publish-template --version 0.1.0 --init
44
- ```
45
- - **参数说明**：
46
- - `--init`：声明为首次登记初始化模板，不绑数据包。
47
- - **业务逻辑**：平台仅初始化模板身份并发布该代码版本，不生成任何素材包。本地即使有 `assets/` 也不会上传。
48
- - **注意**：**严禁同时传入 `--with-assets` / `--assets`**，否则命令会因逻辑冲突而终止。
49
-
50
- ---
51
-
52
- ### 场景 1.2：已有模板版本更新
53
-
54
- 当工程已经发布过，后续进行功能迭代或缺陷修复时：
55
-
56
- - **方式 A：同时更新代码与素材**
57
- - **命令示例**：
58
- ```bash
59
- npx cgmaker publish-template --version 0.2.0 --with-assets --data-ver 2 --data-summary "新关卡"
60
- ```
61
- - **业务逻辑**：向平台提交新一版代码，并为该模板上传一份新素材包。该 `data_ver` 尚无包时即使不加 `--with-assets` 也会自动传 `assets/`。
62
-
63
- - **方式 B：仅更新模板代码（素材沿用或不更新）**
64
- - **命令示例**：
65
- ```bash
66
- npx cgmaker publish-template --version 0.2.0
67
- ```
68
- - **业务逻辑**：仅打包并发布新代码。该 `data_ver` 已有包时默认不 `data/create`。新版本仍绑定 origin 里已有的 `data_id`（空 `data_id` 会解绑）。不要为此传 `--data-ver`。
69
-
70
- - **注意事项**：
71
- - 已经发布过的模板，后续更新时**不要重复传入 `--init`**，否则系统会提示已存在而报错。
72
-
73
- ---
74
-
75
- ### 场景 1.3：仅更新模板素材（代码未变动）
76
-
77
- - **适用场景**：模板代码未作任何修改，仅优化或增补了关卡、图集、音效、文字等素材内容。
78
- - **推荐命令**：使用专用的素材发布命令 `publish-template-data`，无需也不应重新发布代码版本。
79
- ```bash
80
- # 使用默认 assets/ 目录
81
- npx cgmaker publish-template-data --data-ver 2 --data-summary "关卡修订"
82
-
83
- # 指定自定义素材绝对路径
84
- npx cgmaker publish-template-data --data-ver 2 --assets D:\templates\custom-assets
85
- ```
86
- - **核心业务影响**：
87
- 1. 该命令仅将素材打包并上传，生成一个新的**素材包 ID**（`data_id`）。
88
- 2. **平台不会因此产生新的模板代码版本**，已发布的旧版本模板仍默认维持原有的素材绑定关系。
89
- 3. 已经基于旧素材开好工的游戏工程不受任何影响。若游戏创作者需要使用这份新素材，可以在开工程时显式指定新生成的素材包 ID。
90
-
91
- ---
92
-
93
- ### 场景 1.4：基于他人已上架版本派生制作（Fork）
94
-
95
- - **适用场景**：需要在平台已有的某个成熟模板版本基础上派生出新的模板（克隆底座），进行二次创作。
96
- - **命令示例**：
97
- ```bash
98
- # 方式 A：继承源版本的代码与默认素材绑定
99
- npx cgmaker publish-template --version 0.1.0 --fork <源版本ID>
100
-
101
- # 方式 B：继承源版本的代码，并换绑平台已有的一份素材包
102
- npx cgmaker publish-template --version 0.1.0 --fork <源版本ID> --data-id <目标素材包ID>
103
-
104
- # 方式 C：继承源版本的代码，并上传本地素材（走 fork 的 upload_id，不走 data/create）
105
- npx cgmaker publish-template --version 0.1.0 --fork <源版本ID> --with-assets
106
- ```
107
- - **业务逻辑**：
108
- - 由服务端直接继承源版本的代码底座，本地无需上传源码包。
109
- - `--data-id`（或 `--data-ver-id`）仅在包含 `--fork` 时合法，用于挂接已有素材包。
110
- - 默认不传本地包。本地素材须 `--with-assets` / `--assets` 才走 fork 的 `upload_id`，**不**走 `data/create`，因此不要传 `--data-ver` / `--data-summary`。
111
- - 派生成功后将生成全新的模板 ID。
112
-
113
- ---
114
-
115
- ## 2. 游戏发布业务场景（正式版与试玩版）
116
-
117
- 在游戏工程中发布游戏产物时：
118
-
119
- - **发布正式游戏**：
120
- ```bash
121
- npx cgmaker publish --version 1.0.0
122
- ```
123
- - 将当前工程编译产物（`dist/` 目录）上传到平台的正式游戏通道。
124
- - 若此工程之前未发布过游戏，平台将创建全新的游戏 ID；若已发布过，则自动追加新版本。
125
-
126
- - **发布试玩版本（Demo）**：
127
- ```bash
128
- npx cgmaker publish --demo --version 1.0.0
129
- ```
130
- - 试玩版本通过 `--demo` 旗标区分。在平台机制中，试玩版属于**独立的作品发布通道**，拥有独立的试玩游戏 ID。
131
- - **支持先发试玩**：允许在正式游戏发布前提前发布试玩版本。
132
- - **自动挂接机制**：当同一工程后续执行正式版发布（不带 `--demo`）时，平台会自动检测并关联该工程已有的试玩版，无需创作者手动配置关联关系。
133
-
134
- ---
135
-
136
- ## 3. 参数冲突与规范清单（避坑指南）
137
-
138
- 为避免因参数冲突导致命令执行失败，请注意以下规则：
139
-
140
- 1. **`--assets` 必须是绝对路径**
141
- - 正确：`--assets D:\game\assets` 或 `--assets /Users/name/game/assets`
142
- - 错误：`--assets ./assets` 或 `--assets ..\custom-assets`（相对路径将直接导致校验失败退出）
143
- - 映射规则：无论外部目录名是什么，打包后在平台素材包中均统一置于 `assets/` 根路径。
144
-
145
- 2. **第一版不能绑数据包**
146
- - 无 origin 的 `publish-template`（含 `--init`）不要同时传 `--with-assets` / `--assets` / `--data-ver` / `--data-summary`。
147
- - 续发默认不带包；要再传一包用 `--with-assets`。该 `data_ver` 尚无包且本地有 `assets/` 时会自动带上。
148
- - 无 origin 时不要擅自加 `--init`（与默认首发相同）。
149
-
150
- 3. **`--data-id` 仅用于 Fork 换绑；开工程用 `--with-assets <数据包ID>`**
151
- - 在普通的模板发布（`publish-template` 且未带 `--fork`）中，严禁传入 `--data-id`。
152
- - 开工程只有带了 `--with-assets` 才下载素材包；不带则只下代码。已不再支持 `--data-id`。
153
- - 上传自己本地的素材，用 `--with-assets` 声明（Fork 不要再传 `--data-ver`）。
154
-
155
- 4. **`--data-ver` 仅在实际上传数据包时使用**
156
- - 续发默认不带包时不要传 `--data-ver`，否则退出 2。
157
- - 无 origin 的首发 / `--init` / `--fork` 也不要带。
158
-
159
- 5. **素材版本号不自动递增，未指定则不改 `package.json`**
160
- - 未传 `--data-ver` 时读 `package.json` 的 `data_ver`，不写回。只有命令行显式传入且上传成功才写回。
161
-
162
- 6. **本地测试模板无法直接上架发布**
163
- - 若工程是从本地磁盘目录直接导入安装创建的，其模板处于本地调试模式，无法直接作为官方上架模板执行 `publish-template`。
1
+ # 业务场景与参数配置指南
2
+
3
+ 本文档面向模板作者与游戏创作者。版本号、素材版本写在 `package.json`，素材目录固定为工程 `assets/`。不要在命令里传版本号或素材路径。素材说明可用 `--data-summary`。平台展示名写在 `package.json.name`。更新说明去网页改。
4
+
5
+ 发布前请先确认两件事：
6
+
7
+ - **模板、开源工程**：上传不含 `node_modules`，`package.json` 里的依赖须能公开安装、版本真实可用。
8
+ - **模板、游戏、开源工程**：运行时只用本地资源，不要用 CDN 或其它在线地址。
9
+
10
+ ---
11
+
12
+ ## 1. 模板发布业务场景
13
+
14
+ ### 场景 1.1：首次发布全新模板
15
+
16
+ 当你的模板工程从未在平台发布过：
17
+
18
+ - **方式 A：完整首次发布（代码 + 素材）**
19
+ - **前置准备**：`package.json` 中已配置好 `slug`、`version`、`data_ver`、可选 `data_summary`、`scripts.validate`、`scripts.dev:demo` 与 `scripts.build:demo`。有独立试玩数据时 `validate` 必须同时检查两份，不要 `validate:demo`。无独立 demo 时 `dev:demo` 可与 `dev` 相同、`build:demo` 可与 `build` 相同。另需合法平台展示名：`package.json.name`，不能含 `/` 或 `@`；空缺时会要求输入并写回。若现有 name 已经带 `/` 或 `@`，不要覆盖，发布时会再问展示名。不会用 `slug` 顶上。本地素材放在工程 `assets/`。
20
+ - **命令示例**：
21
+ ```bash
22
+ npx cgmaker publish-template
23
+ ```
24
+ - **说明**：
25
+ - `package.json.version`：首发代码版本号。须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。
26
+ - `package.json.data_ver`：首发素材包版本。平台不会自动 +1。
27
+ - 可选 `--with-assets`：即使该 `data_ver` 已有包也再传一包。**第一版不能带包**，不要加。
28
+ - 可选 `--data-summary`：本包说明。也可写 `package.json.data_summary`。
29
+
30
+ - **方式 B：仅发布代码（暂不带素材）**
31
+ - **命令示例**：
32
+ ```bash
33
+ npx cgmaker publish-template
34
+ ```
35
+ - **注意**：**不要加 `--with-assets`**。本地即使有 `assets/` 也不会上传。
36
+
37
+ ---
38
+
39
+ ### 场景 1.2：已有模板版本更新
40
+
41
+ - **方式 A：同时更新代码与素材**
42
+ - 先改 `package.json` 的 `version` / `data_ver`（及可选 `data_summary`）。
43
+ - **命令示例**：
44
+ ```bash
45
+ npx cgmaker publish-template --with-assets
46
+ ```
47
+ - 该 `data_ver` 尚无包时即使不加 `--with-assets` 也会自动传 `assets/`。
48
+
49
+ - **方式 B：仅更新模板代码**
50
+ - 先改 `package.json.version`。
51
+ - **命令示例**：
52
+ ```bash
53
+ npx cgmaker publish-template
54
+ ```
55
+ - 该 `data_ver` 已有包时默认不再上传素材。新版本仍绑定已有素材包。
56
+
57
+ ---
58
+
59
+ ### 场景 1.3：仅更新模板素材（代码未变动）
60
+
61
+ - 改 `package.json` 的 `data_ver`（及可选 `data_summary`）；素材放在工程 `assets/`。
62
+ ```bash
63
+ npx cgmaker publish-template-data
64
+ ```
65
+ - 只上传素材，**不会**产生新的模板代码版本。已经基于旧素材开好的游戏工程不受影响。要用新素材，开工程时带上新的素材包 ID。
66
+
67
+ ---
68
+
69
+ ### 场景 1.4：基于他人已上架版本派生
70
+
71
+ ```bash
72
+ npx cgmaker publish-template --fork <源版本ID>
73
+ npx cgmaker publish-template --fork <源版本ID> --with-assets
74
+ ```
75
+
76
+ - 继承源版本的代码底座。
77
+ - 默认不传本地包。要上传本地素材加 `--with-assets`。
78
+ - 换绑已有素材包时按提示选择，不要自己编 ID。
79
+ - 派生成功后是一份新模板。代码版本号仍读 `package.json.version`。
80
+
81
+ ---
82
+
83
+ ## 2. 游戏发布业务场景（正式版与试玩版）
84
+
85
+ 先改 `package.json.version`：
86
+
87
+ - **发布正式游戏**：
88
+ ```bash
89
+ npx cgmaker publish
90
+ ```
91
+ - 上传当前工程 `dist/`。还没发布过会新建游戏；已发布过则追加新版本。
92
+ - 上传前会列出名称、版本、正式/试玩等，确认后才发布。不想询问时可加 `--no-interactive`。
93
+
94
+ - **发布试玩**：
95
+ ```bash
96
+ npx cgmaker publish --demo
97
+ ```
98
+ - 试玩是**独立作品**。
99
+ - 允许先发试玩。同一工程后续发正式版时会自动挂接。
100
+
101
+ ---
102
+
103
+ ## 3. 避坑
104
+
105
+ 1. **素材目录固定为工程 `assets/`**，不要在命令里指定别的路径。
106
+
107
+ 2. **第一版不能绑数据包**
108
+ - 还没发布过的 `publish-template` 不要加 `--with-assets`。
109
+ - 续发默认不带包；要再传一包用 `--with-assets`。该 `data_ver` 尚无包且本地有 `assets/` 时会自动带上。
110
+
111
+ 3. **开工程下载素材用 `--with-assets <数据包ID>`**
112
+ - 和发模板时的 `--with-assets`（开关、无值）不是同一个参数。
113
+ - 网页命令没有素材包编号，就不要补。
114
+
115
+ 4. **`data_ver` 写在 `package.json`**
116
+ - 续发默认不带包时，改这个字段也不会上传。
117
+ - 首发、派生默认都不走「只传素材」。
118
+
119
+ 5. **素材版本号不自动递增**
120
+ - 更新素材时请改 `package.json` 的 `data_ver`（及可选 `data_summary`）。
121
+
122
+ 6. **从本地文件夹拷来的工程不能当模板上架**
123
+ - `--from-dir` 落地的工程还没接到平台，不能 `publish-template`。
package/skill/cgmaker-identity/references/fields.md CHANGED
@@ -1,64 +1,64 @@
1
- # 参数与配置字段说明
2
-
3
- 本文档面向真实用户，详细罗列在开发、构建和发布模板或游戏过程中涉及的所有配置字段、命令行功能参数以及平台标识的作用与使用规范。
4
-
5
- ---
6
-
7
- ## 1. 模板工程配置字段（`package.json`）
8
-
9
- 在开发模板工程时，由你在根目录的 `package.json` 中配置：
10
-
11
- | 字段名称 | 类型 | 是否必填 | 功能与使用说明 | 配置规范与注意事项 |
12
- |---|---|---|---|---|
13
- | `slug` | 字符串 | 是 | **模板的英文短名**。写入 `package.json`，首发时随 `versions/create` 提交给平台。 | 仅支持小写字母、数字与中划线，如 `quiz-react`（`^[a-z0-9][a-z0-9-]{0,62}$`）。**发布后禁止修改**，工具会拒绝与 origin 不一致的 slug。它**不是**平台分配的模板 ID，也**不是** `用户名/模板名` 里的模板名。 |
14
- | `name` | 字符串 | 首发必填 | **平台模板名**（`用户名/模板名` 中间那段）。服务端按同一作者未删除模板校验唯一，且不能含 `/` 或 `@`。 | 可改。用 `--name` 或填写本字段。**不要用 `slug` 冒充**。都没有时交互必问；脚本则报错。开工程落地会把游戏工程的 `name` 改成目录名，不要动 `slug`。 |
15
- | `version` | 字符串 | 是 | **工程的默认代码版本号**。作为当前模板或工程的代码版本基准。 | 执行发布命令时若未显式传入 `--version`，工具将默认采用该值。**仅发布模板**（`publish-template`）时该值作为接口 `version_name`，须 1–16 位、仅小写字母/数字/`.`/`-`、以字母或数字开头和结尾、不能有连续符号（如 `0.1.0`、`1.0.0-a`）。游戏与开源工程发版不套此格式。 |
16
- | `data_ver` | 字符串或数字 | 是 | **模板配套素材的版本号**。用于标识当前工程配套素材的版本。模板规范校验（`validate-template`）与发布模板（`publish-template`）时**强制要求该字段存在**。 | 建议从 `"1"` 开始（如 `"1"`、`"2"`）。未传 `--data-ver` 时沿用此字段且不改写；仅命令行显式传入 `--data-ver` 且上传成功后才写回。 |
17
-
18
- ---
19
-
20
- ## 2. 命令行功能参数详解
21
-
22
- 在调用 `cgmaker` 各类发布或创建命令时使用的主要功能参数：
23
-
24
- | 参数名称 | 适用命令 | 是否必填 | 功能与作用说明 | 参数规则与配置示例 |
25
- |---|---|---|---|---|
26
- | `--version <版本号>` | `publish-template` | 推荐显式指定 | **指定本次发布的模板版本号**（接口 `version_name`）。 | 覆盖 `package.json` 的 `version`。须 1–16 位，仅小写字母、数字、`.`、`-`；必须以字母或数字开头和结尾，且不能有连续符号。例如 `--version 1.0.0`。不合法则拒绝发布。<br>注：单独执行 `cgmaker --version`（前面无子命令）输出的是工具客户端自身的软件版本，两者含义不同。 |
27
- | `--version <版本号>` | `publish`<br>`publish-project` | 推荐显式指定 | **指定本次发布的游戏 / 开源工程版本号**。 | 覆盖 `package.json` 的 `version`。例如 `--version 1.0.0`。不套模板 `version_name` 的格式校验。 |
28
- | `--name <名称>` | `publish-template` | 首发必填 | **平台模板名**（`用户名/模板名` 后半段）。 | 覆盖 `package.json` 的 `name`。都不能用或含 `/` `@` 时会要求重填。交互下可用 slug 作输入建议，回车即表示采用建议。 |
29
- | `--data-ver <素材版本号>` | `publish-template`<br>`publish-template-data` | 选填（未传时默认读取 `package.json`） | **指定本次上传素材包的版本编号**。用于在平台区分不同批次或规格的素材内容。 | 字符串或数字（如 `--data-ver 2`）。未指定则读 `package.json` 的 `data_ver`，**不写回**。仅当命令行显式传入且实际上传成功后才写回。<br>**注意：平台不会自动自增此版本号**。未实际上传时不要带此参数（含续发默认不带包、`--init` / `--fork`），否则退出 2。 |
30
- | `--data-summary <说明>` | `publish-template`<br>`publish-template-data` | 选填 | **本次素材包的说明**。对应 `data/create` 的 `summary`。同一 `data_ver` 下有多包时用来区分。 | 例如 `--data-summary "春节活动关卡"`。不传、空串、纯空格或交互回车都不写入接口。仅在走 `data/create` 时有效；不要与 `--init` / `--fork` 同时使用。 |
31
- | `--with-assets` | `publish-template` | 选填 | **显式同时上传数据包**。 | 默认不带包。该 `data_ver` 在平台尚无包且本地有 `assets/` 时也会自动上传。再传一包须加本开关。不要与 `--init` 同时使用。 |
32
- | `--with-assets <数据包ID>` | `cgmaker-create` | 选填 | **下载指定素材包**。 | 值必填，与 `publish-template --with-assets`（开关、无值）不是同一个参数。不带则只下代码。已不再支持 `--data-id`。 |
33
- | `--assets <绝对路径>` | `publish-template`<br>`publish-template-data` | 选填 | **自定义素材目录的完整来源路径**。当素材文件不在默认的工程根目录 `assets/` 下时使用。 | **必须是本机完整绝对路径**（例如 `D:\game-project\custom-assets`），不支持相对路径。zip 内仍为 `assets/`。在 `publish-template` 上出现即视为要上传。不要与 `--init` 同时使用。 |
34
- | `--init` | `publish-template` | 首次发空代码时选填 | **声明首次登记并初始化模板代码，不绑定任何素材包**。 | 仅用于未曾发布过的模板工程首次上线代码框架。不可与 `--with-assets` / `--assets` 混用。本地有 `assets/` 也不再要求加排除开关。 |
35
- | `--fork <源版本ID>` | `publish-template` | 派生制作时必填 | **基于平台上已有的某个模板版本派生新模板**。 | 服务端继承该版本的代码底座，本地无需上传源码包。换绑已有素材用 `--data-id`。默认不传本地包；须 `--with-assets` / `--assets` 才走 fork 的 `upload_id`。不要传 `--data-ver` / `--data-summary`。 |
36
- | `--data-id`<br>（或 `--data-ver-id`） | `publish-template`（搭配 `--fork`） | 选填 | **Fork 时换绑平台上已存在的素材包**。 | 仅 fork。开工程请用 `--with-assets <数据包ID>`，不要用本参数。 |
37
- | `--demo` | `publish` | 选填 | **指定本次发布为试玩版本（Demo）**。 | 发布游戏的试玩内容。试玩与正式版通道独立，支持独立抢先发布，后续在同一工程发布正式版时平台会自动建立两者关联。 |
38
- | `--yes` | `publish` | 脚本选填 | **跳过发布前确认**。 | 仅 npm 层。真正上传前会先列出名称、版本、正式/试玩等，等人确认。TTY 默认询问；Agent 同意后再带本旗标重跑。**禁止**助手自行添加。CI / `--no-interactive` 不询问。 |
39
-
40
- ---
41
-
42
- ## 3. 平台全局标识（ID）与用途
43
-
44
- 你在平台管理后台、命令执行成功的输出结果，或开工程参数中会接触到的核心标识：
45
-
46
- | 标识名称 | 产生方式 | 主要用途与业务意义 |
47
- |---|---|---|
48
- | **模板 ID**（`template_id`） | 首次发布模板成功后由平台统一分配 | 模板在全平台的唯一全局身份编号（通常为 12 位左右的英数混合字符串，如 `4p7fh9mytcsg`）。查询、发布仍用该 ID。开工程网页默认用 `用户名/模板名`，也可传该 ID 或版本 ID。 |
49
- | **版本 ID**（`version_id`） | 每次发布新的模板代码版本时生成 | 标识某一次具体的模板代码迭代版本。游戏工程在与模板建立依赖关系时，实际绑定的是特定的版本 ID。 |
50
- | **素材包 ID**（`data_id`；CLI JSON 成功载荷键名 `data_ver_id`） | 每次成功上传素材包后生成 | 标识一份独立的素材内容包。通过此 ID，模板作者可以在不同代码版本间复用素材包，游戏创作者也可以在开工程时指定拉取特定的素材包。 |
51
- | **游戏 ID**（`game_id` / `demo_game_id`） | 首次发布游戏成功后由平台统一分配 | 游戏在平台上的唯一编号。正式版与试玩版各对应一个独立 ID，试玩版本可先于正式版发布，系统会自动维护两者的绑定关系。 |
52
-
53
- ---
54
-
55
- ## 4. 常见易混淆概念说明
56
-
57
- ### 模板短名（`slug`） vs 模板名（`name`） vs 模板 ID（`template_id`）
58
- - **`slug`**：本地 `package.json` 的英文短名，首发写入接口；发布后禁止修改。
59
- - **`name`**：平台模板名，即 `用户名/模板名` 的后半段。首发必须由用户给出（`--name` 或 `package.json.name`），不能含 `/` 或 `@`；**不会**自动用 `slug` 顶上。
60
- - **`template_id`**：由平台系统自动分配的唯一全球编码。查询与发布必须用它。开工程第一位置交给平台解析：`用户名/模板名`、`用户名/模板名@版本`、模板 id 或版本 id 均可。
61
-
62
- ### 素材版本号（`--data-ver`） vs 素材包 ID（`data_id`）
63
- - **`--data-ver`**：由你规划并填写的版本标号（如第 1 版、第 2 版，用 `1`、`2` 表示），便于人类记忆与辨识。**它不会自动加 1**。未传则读 `package.json`，不写回。
64
- - **`data_id`**：平台为该次上传生成的全局唯一物理标识。开工程用 `--with-assets <数据包ID>` 精确获取该包素材；Fork 换绑仍用 `--data-id`。
1
+ # 参数与配置字段说明
2
+
3
+ 本文档面向模板作者与游戏创作者，说明开发、构建和发布时会用到的配置字段、命令参数和平台标识。
4
+
5
+ ---
6
+
7
+ ## 1. 模板工程配置字段（`package.json`）
8
+
9
+ 在模板工程根目录的 `package.json` 中配置：
10
+
11
+ | 字段名称 | 类型 | 是否必填 | 功能与使用说明 | 配置规范与注意事项 |
12
+ |---|---|---|---|---|
13
+ | `slug` | 字符串 | 是 | **模板的英文短名**。开工程引用 `用户名/slug` 的后半段就是它。 | 仅支持小写字母、数字与中划线，如 `quiz-react`。**发布后禁止修改**。它**不是**平台分配的模板 ID，也**不是**平台展示名 `name`。 |
14
+ | `name` | 字符串 | 首发必填 | **平台展示名**（给人看，可中文）。同一作者下未删除的模板不能重名，且不能含 `/` 或 `@`。 | 可改。**不要用 `slug` 冒充展示名**，也**不要**把本字段写进开工程命令。空缺时会问你并写回本字段。如果现有 name 已经带 `/` 或 `@`（包名），不要覆盖，发布时会再问展示名。开工程落地会把游戏工程的 `name` 改成目录名，不要动 `slug`。 |
15
+ | `version` | 字符串 | 是 | **工程的代码版本号**。发布时读取，不要在命令里传版本号。 | **仅发布模板**时须 1–16 位、仅小写字母/数字/`.`/`-`、以字母或数字开头和结尾、不能有连续符号（如 `0.1.0`、`1.0.0-a`）。游戏与开源工程发版不套此格式。 |
16
+ | `data_ver` | 字符串或数字 | 是 | **模板配套素材的版本号**。发布时读取，不要在命令里传素材版本号。 | 建议从 `"1"` 开始。平台不会自动 +1。更新素材时请改这个字段再跑 `publish-template --with-assets` 或 `publish-template-data`。 |
17
+ | `data_summary` | 字符串 | 否 | **本次素材包说明**。同一 `data_ver` 下多包时用来区分。 | 可写在 `package.json`，也可用 `--data-summary`。 |
18
+ | `scripts.dev` | 字符串 | 是 | **正式内容的开发服务**（`npm run dev`）。 | 命令随技术栈，名字不能改。 |
19
+ | `scripts.dev:demo` | 字符串 | 是 | **试玩的开发服务**（`npm run dev:demo`）。 | 发模板时必须有。无独立 demo 时可与 `dev` 写成同一条命令。 |
20
+ | `scripts.build` | 字符串 | 是 | **打包正式版到 `dist/`**。 | 发布游戏前由作者自行执行。 |
21
+ | `scripts.build:demo` | 字符串 | 是 | **打包试玩到同一份 `dist/`**（会覆盖正式产物）。 | 发模板时必须有。无独立 demo 时可与 `build` 写成同一条命令。发游戏试玩前由作者执行。 |
22
+ | `scripts.validate` | 字符串 | 是 | **模板自己的数据检查**（`npm run validate`）。 | 发模板时必须有。有独立试玩数据时，同一条命令必须把正式和试玩两份都检查过。**不要** `scripts.validate:demo`。必须是模板自己的命令，**不要**写成 `cgmaker validate`。`npx cgmaker validate` 会转调这条脚本。 |
23
+
24
+ ---
25
+
26
+ ## 2. 命令行功能参数详解
27
+
28
+ 帮助里能看到、作者会用到的参数：
29
+
30
+ | 参数名称 | 适用命令 | 是否必填 | 功能与作用说明 | 参数规则与配置示例 |
31
+ |---|---|---|---|---|
32
+ | `--data-summary <说明>` | `publish-template` / `publish-template-data` | 选填 | **本次素材包说明**。 | 也可写在 `package.json.data_summary`。派生时不要传。 |
33
+ | `--with-assets` | `publish-template` | 选填 | **显式同时上传数据包**。 | 默认不带包。该 `data_ver` 在平台尚无包且本地有 `assets/` 时也会自动上传。再传一包须加本开关。第一版不能带包。zip 始终来自工程 `assets/`。 |
34
+ | `--with-assets <数据包ID>` | `cgmaker-create` | 选填 | **下载指定素材包**。 | 值必填，与 `publish-template --with-assets`（开关、无值）不是同一个参数。不带则只下代码。 |
35
+ | `--fork <源版本ID>` | `publish-template` | 派生制作时必填 | **基于平台上已有的某个模板版本派生新模板**。 | 继承该版本的代码底座。要带本地包加 `--with-assets`。换绑已有素材包时按提示选择。 |
36
+ | `--demo` | `publish` | 选填 | **本次发布为试玩**。 | 试玩与正式版是两份独立作品。可先发试玩，后续在同一工程发正式版时会自动挂接。 |
37
+ | `--no-interactive` | 各命令 | 选填 | **关闭终端询问**。 | 脚本或不想逐步确认时使用。 |
38
+ | `--force` | `login` | 选填 | **强制重新登录**。 | 换号时不必先退出。 |
39
+
40
+ ---
41
+
42
+ ## 3. 平台全局标识（ID）与用途
43
+
44
+ 你在网页、命令成功提示或开工程参数中会接触到的标识：
45
+
46
+ | 标识名称 | 产生方式 | 主要用途与业务意义 |
47
+ |---|---|---|
48
+ | **模板 ID** | 首次发布模板成功后由平台分配 | 模板在平台上的身份。开工程网页默认用 `用户名/slug`，也可传该 ID 或版本 ID。 |
49
+ | **版本 ID** | 每次发布新的模板代码版本时生成 | 某一次具体的模板代码版本。派生、绑定游戏时用它。 |
50
+ | **素材包 ID** | 每次成功上传素材包后生成 | 一份独立的素材内容。开工程用 `--with-assets <数据包ID>` 拉取。 |
51
+ | **游戏 ID** | 首次发布游戏成功后由平台分配 | 游戏在平台上的编号。正式版与试玩各有一份，可先发试玩。 |
52
+
53
+ ---
54
+
55
+ ## 4. 常见易混淆概念说明
56
+
57
+ ### 模板短名（`slug`） vs 模板名（`name`） vs 模板 ID
58
+ - **`slug`**：本地 `package.json` 的英文短名。发布后禁止修改。开工程命令 `用户名/slug` 的后半段用它，不要用 `name`。
59
+ - **`name`**：平台展示名（可中文）。首发必须合法，不能含 `/` 或 `@`；**不会**自动用 `slug` 顶上。不用于开工程引用。若现有 `package.json.name` 已经带 `/` `@`，不要覆盖该字段。
60
+ - **模板 ID**：平台分配。开工程第一位置交给平台解析：`用户名/slug`、`用户名/slug@版本`、模板 id 或版本 id 均可。
61
+
62
+ ### 素材版本号（`data_ver`） vs 素材包 ID
63
+ - **`data_ver`**：写在 `package.json`，由你规划（如 `"1"`、`"2"`）。**它不会自动加 1**。
64
+ - **素材包 ID**：平台为该次上传生成。开工程用 `--with-assets <数据包ID>` 精确获取该包。
package/skill/cgmaker-template-spec/SKILL.md CHANGED
@@ -24,10 +24,10 @@ description: 橙光 cgmaker 模板工程规范。在用户改目录或脚本名
24
24
  模板提供（进指纹）：
25
25
 
26
26
  - `src/` 必须
27
- - `package.json` 必须有 `scripts.dev` / `scripts.build` / `scripts.build:demo`，以及 `slug`、`data_ver`
27
+ - `package.json` 必须有 `scripts.dev` / `scripts.dev:demo` / `scripts.build` / `scripts.build:demo` / `scripts.validate`，以及 `slug`、`data_ver`
28
28
  - `README.md`、`AGENTS.md` 必须（README 不进指纹；AGENTS.md 进）
29
29
  - `skill/` 可选
30
- - 校验（惯例 `schema/`）可选，不必是 JSON Schema
30
+ - `scripts.validate` 必有：模板自己检查数据。有独立试玩数据时同一条命令检查两份，不要 `validate:demo`。实现可放 `schema/`，不必是 JSON Schema
31
31
  - 根 `index.html`、打包配置可选
32
32
 
33
33
  不要 `template.yaml`。作者只填 `package.json` 的 `slug`、`data_ver` + 已有的 `version` / `description`。平台模板名用 `name`（可改；首发必须填写，不能含 `/` 或 `@`，不要用 `slug` 顶上）。不要手写 `template_id`。落地会改 `name`，**禁止改 `slug`**。参数与字段详细定义，见 `cgmaker-identity`。
@@ -41,16 +41,17 @@ description: 橙光 cgmaker 模板工程规范。在用户改目录或脚本名
41
41
 
42
42
  ```bash
43
43
  npx cgmaker validate-template # 验证当前工程目录是否符合模板规范
44
- npm run validate # 仅当模板提供了数据校验
44
+ npm run validate # 必有：模板自己检查数据。有独立试玩数据时同一条命令检查两份，不要 validate:demo
45
+ npx cgmaker validate # 转调 npm run validate
46
+ npm run dev # 正式内容开发服务
47
+ npm run dev:demo # 试玩开发服务（无独立 demo 时可与 dev 相同）
45
48
  npm run build
46
- npm run build:demo # 试玩 dist/（发布模板必须有这条脚本）
47
- npx cgmaker publish-template --version 0.1.0 --data-ver 1
48
- npx cgmaker publish-template --version 0.1.0 --data-ver 1 --data-summary "示范关卡"
49
- npx cgmaker publish-template --version 0.1.0 --data-ver 1 --assets C:\path\to\assets
50
- npx cgmaker publish-template-data --data-ver 2 --data-summary "关卡修订"
51
- npx cgmaker publish-template-data --data-ver 2 --assets C:\path\to\assets
49
+ npm run build:demo # 试玩 dist/（发布模板必须有这条脚本；无独立 demo 时可与 build 相同）
50
+ npx cgmaker publish-template
51
+ npx cgmaker publish-template --with-assets
52
+ npx cgmaker publish-template-data
52
53
  ```
53
54
 
54
- 过不过关只认 `cgmaker validate-template`。发布游戏用 `npx cgmaker publish`（只认 `dist/`）；试玩用 `npx cgmaker publish --demo`（先 `build:demo`，可无正式版首发）。命令怎么敲见 `cgmaker`；功能参数与场景搭配见 `cgmaker-identity`。上传素材时没写 `--data-ver` 会问你（可沿用 `package.json` 里的号，不会自动 +1）；没法提问时必须自己写上或保证 `package.json` 已有 `data_ver`。`--data-summary` 可选，空则不写接口。`publish-template` 与 `publish-template-data` 都可用 `--assets` 指定素材目录的完整路径（传上去以后包里仍然叫 `assets/`）。
55
+ 过不过关只认 `cgmaker validate-template`。发布游戏用 `npx cgmaker publish`（只认 `dist/`）；试玩用 `npx cgmaker publish --demo`（先 `build:demo`，可无正式版首发）。命令怎么敲见 `cgmaker`；功能参数与场景搭配见 `cgmaker-identity`。`version`、`data_ver` 写在 `package.json`；素材固定为工程 `assets/`。素材说明可用 `--data-summary`。平台展示名写在 `package.json.name`；现有 name 已经带 `@` 时不要覆盖。更新说明去网页改。缺字段就改 `package.json` 再跑。
55
56
 
56
57
  发布模板或开源工程前：zip 不含 `node_modules`，`package.json` 里的依赖必须能装、版本必须真实可用。发布模板、游戏或开源工程前：运行时只用本地资源，不要热链 CDN 或其它在线地址。
package/skill/cgmaker-template-spec/references/layout.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  给人（和 AI）读的条文。机器实现是 `npx cgmaker validate-template`。
4
4
 
5
- 技术栈自选（React / Vue / Phaser / 原生 Canvas 均可），工程是 **npm 包**：必须有 `package.json` 和 `scripts.dev` / `scripts.build` / `scripts.build:demo`。**平台规定的目录名不允许改**；`assets/` 内部子目录名由各模板写在 `AGENTS.md` 里。
5
+ 技术栈自选（React / Vue / Phaser / 原生 Canvas 均可），工程是 **npm 包**：必须有 `package.json` 和 `scripts.dev` / `scripts.dev:demo` / `scripts.build` / `scripts.build:demo` / `scripts.validate`。**平台规定的目录名不允许改**；`assets/` 内部子目录名由各模板写在 `AGENTS.md` 里。
6
6
 
7
7
  ✅ 必有 · ⭕ 可选（有则校验）。产物 HTML 见 [dist.md](dist.md)。`template_id` / origin / 再发布是平台实现，见仓库 [docs/origin.md](../../../../../docs/origin.md)。
8
8
 
@@ -10,7 +10,7 @@
10
10
 
11
11
  只要求 **Node.js 20+**（LTS，自带 `npm` / `npx`）。不要写 `"packageManager": "pnpm@…"`。
12
12
 
13
- `create` 脚手架会写一份含 `@66rpg/cgmaker` 的 `package.json`。模板 zip 自带的 `package.json` 覆盖脚手架那份（须保留 `slug` 与 `dev` / `build` / `build:demo`）。
13
+ `create` 脚手架会写一份含 `@66rpg/cgmaker` 的 `package.json`。模板 zip 自带的 `package.json` 覆盖脚手架那份（须保留 `slug` 与 `dev` / `dev:demo` / `build` / `build:demo` / `validate`）。
14
14
 
15
15
  ## 工程根
16
16
 
@@ -18,12 +18,12 @@
18
18
 
19
19
  ```
20
20
  .
21
- ├── package.json ✅ slug + version + data_ver + scripts.dev / build / build:demo；指纹不含 name、slug、data_ver
21
+ ├── package.json ✅ slug + version + data_ver + scripts.dev / dev:demo / build / build:demo / validate；指纹不含 name、slug、data_ver
22
22
  ├── README.md ✅ 不进指纹
23
23
  ├── AGENTS.md ✅ 进指纹。写明 assets/ 子目录；可指向 skill/SKILL.md
24
24
  ├── src/ ✅ 进指纹。完整可改源码，不规定语言或框架
25
25
  ├── assets/ ✅ 必须有这个目录（可空）；正式内容；不进指纹
26
- │ ├── data/ ⭕ 样板惯例；kit validate 默认找 data/game.json
26
+ │ ├── data/ ⭕ 样板惯例。正式 game.json；有独立试玩时另有 game.demo.json，由 scripts.validate 同一条命令检查
27
27
  │ ├── theme/ ⭕ 样板惯例；默认找 theme/layout.json
28
28
  │ └── images/ ⭕ 样板惯例。子目录名平台不管，写在 AGENTS.md
29
29
  ├── .gitignore ✅ 必须忽略 dist/、node_modules/
@@ -42,7 +42,7 @@
42
42
 
43
43
  素材引用相对 **`assets/` 根**（JSON 写 `images/cover.svg`，不要写 `assets/images/...`）。根目录不要再放 `data/`、`theme/`。
44
44
 
45
- 试玩（同一工程、同一份 `src/`，两次 build 都进 `dist/`）：必须提供 `scripts.build:demo`，自己从 `assets/` 切片或按模板约定生成试玩内容。不要第二份作者工程，不要 `dist-demo/`。
45
+ 试玩（同一工程、同一份 `src/`，两次 build 都进 `dist/`）：必须提供 `scripts.dev:demo`（试玩开发服务）和 `scripts.build:demo`（试玩产物）。无独立 demo 时，`dev:demo` 可与 `dev` 相同、`build:demo` 可与 `build` 相同。数据校验只有一条 `scripts.validate`：有独立试玩数据时，同一条命令必须把正式和试玩两份都检查过。**不要** `scripts.validate:demo`。不要第二份作者工程，不要 `dist-demo/`。
46
46
 
47
47
  安装之后多出来、**不要打回 zip** 的：`.cgmaker/`（`origin.json` 模板身份、`game.json` 游戏正式版 / demo，见 [docs/origin.md](../../../../../docs/origin.md)）、`node_modules/`、`dist/`、以及 create/init 或 `cgmaker skill` 按所选编辑器拷入的 `.agents/` `.cursor/` 等目录（未选编辑器则没有这些目录；之后可 `npx cgmaker skill --platform cursor` 补装）。凭据在 `~/.cgmaker/`，不在工程里。
48
48
 
@@ -67,41 +67,49 @@
67
67
  "name": "my-game",
68
68
  "slug": "react-admin",
69
69
  "version": "1.2.0",
70
+ "data_ver": "1",
71
+ "data_summary": "示范关卡",
70
72
  "description": "商店简介 / 列表说明",
71
73
  "scripts": {
72
- "dev": "<预览>",
74
+ "dev": "<正式内容开发服务>",
75
+ "dev:demo": "<试玩开发服务；无独立 demo 时可与 dev 相同>",
73
76
  "build": "<打包正式版到 dist/>",
74
- "build:demo": "<打包试玩到同一个 dist/，会覆盖正式产物>"
77
+ "build:demo": "<打包试玩到同一个 dist/，会覆盖正式产物；无独立 demo 时可与 build 相同>",
78
+ "validate": "<模板自己的数据检查；有独立试玩数据时同一条命令检查两份>"
75
79
  }
76
80
  }
77
81
  ```
78
82
 
79
83
  - `slug` ✅ `^[a-z0-9][a-z0-9-]{0,62}$`。发布后禁止修改。**不是**平台模板名，也不是 `name`
80
- - `version` ✅ 模板发版时作为接口 `version_name`（`--version` 可覆盖）：1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号（如 `0.1.0`、`1.0.0-a`）。不是随意 semver。游戏 / 开源工程发版不套此格式。
84
+ - `version` ✅ 模板发版时作为接口 `version_name`：1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号（如 `0.1.0`、`1.0.0-a`）。不是随意 semver。游戏 / 开源工程发版不套此格式。不要用 `--version` 覆盖。
85
+ - `data_ver` ✅ 素材版本号（发布模板强制）。平台不会自动 +1。不要用 `--data-ver`
86
+ - `data_summary` ⭕ 本次素材包说明（接口 `summary`）。也可用 `--data-summary`
81
87
  - `description` ⭕ 商店简介（接口 `summary`）
82
88
  - `name` ⭕ 平台模板名。可改；服务端按作者校验唯一，不能含 `/` 或 `@`。首发必须由用户给出，**不会**默认用 `slug`。落地会改成工程目录名，不要拿它当 slug
83
- - `scripts.dev` ✅ 源码热更新。命令随栈，**名字不能改**
89
+ - `scripts.dev` ✅ 正式内容开发服务。命令随栈，**名字不能改**
90
+ - `scripts.dev:demo` ✅ 试玩开发服务（`npm run dev:demo`）。发布模板时强制有这条。无独立 demo 时可与 `dev` 写成同一条命令。CLI **不执行**该脚本
84
91
  - `scripts.build` ✅ 产出正式版 `dist/`，命名见 [dist.md](dist.md)
85
- - `scripts.build:demo` ✅ 产出试玩 `dist/`（同一目录，会覆盖）。发布模板时强制有这条
86
- - `scripts.validate` ⭕ 仅当模板提供数据校验。只许叫 `validate`
92
+ - `scripts.build:demo` ✅ 产出试玩 `dist/`（同一目录，会覆盖）。发布模板时强制有这条。无独立 demo 时可与 `build` 写成同一条命令
93
+ - `scripts.validate` ✅ 模板自己的数据检查（`npm run validate`）。发布模板时强制有这条。有独立试玩数据时，同一条命令必须把正式和试玩两份都检查过。**不要** `scripts.validate:demo`（开发服务和打包才分正式/试玩）。必须是模板自己的检查（如 `node schema/check.mjs`），**不要**写成 `cgmaker validate`（`npx cgmaker validate` 会转调 `npm run validate`，会循环）
87
94
  - 不要 `scripts.login` / `publish`（和 npm 撞车），不要 `bin` / `packageManager`
88
95
 
89
- `qualified_name` = 当前账号用户名 + `/` + 平台模板名 `name`（首发必须有 `name`，不要用 `slug` 顶上）。
96
+ `qualified_name` = 当前账号用户名 + `/` + `slug`（开工程用这个，不要用平台模板名 `name`）。
90
97
 
91
98
  三件容易混的「scripts」：`package.json` 的 `"scripts"` 字段（必有，不是文件夹）；`schema/logic.mjs`（可选校验）；`skill/scripts/`（给 AI，不是 npm）。
92
99
 
93
100
  ```bash
94
101
  npx cgmaker validate-template
95
- npm run validate # 仅当模板提供了数据校验
102
+ npm run validate # 必有：模板自己检查数据。有独立试玩数据时同一条命令检查两份，不要 validate:demo
103
+ npx cgmaker validate # 转调 npm run validate
104
+ npm run dev
105
+ npm run dev:demo # 试玩开发服务（无独立 demo 时可与 dev 相同）
96
106
  npm run build
97
107
  npm run build:demo # 试玩 dist/（发布模板也必须有这条脚本）
98
108
  npx cgmaker publish # 游戏正式版：只认 dist/
99
109
  npx cgmaker publish --demo # 试玩：先 build:demo，只认 dist/
100
- npx cgmaker publish-template --version 0.1.0 --data-ver 1
101
- npx cgmaker publish-template --version 0.1.0 --data-ver 1 --data-summary "示范关卡"
102
- npx cgmaker publish-template --version 0.1.0 --data-ver 1 --assets C:\path\to\assets
103
- npx cgmaker publish-template-data --data-ver 2 --data-summary "关卡修订"
104
- npx cgmaker publish-template-data --data-ver 2 --assets C:\path\to\assets
110
+ npx cgmaker publish-template
111
+ npx cgmaker publish-template --with-assets
112
+ npx cgmaker publish-template-data
105
113
  ```
106
114
 
107
115
  ## 指纹
@@ -118,7 +126,7 @@ npx cgmaker publish-template-data --data-ver 2 --assets C:\path\to\assets
118
126
 
119
127
  `publish-template` 打的是源码树，不传 `.git`。Git 是可选派生，不当主键。
120
128
 
121
- **不要打进代码 zip：** `assets/`、`node_modules/`、`dist/`、`.git/`、`.cgmaker/`（包内一律丢弃，防伪造 origin / game.json）、`.agents/` `.cursor/` `.claude/` 等 `skill-targets`、`preview/`、`tests/`、根目录 `scripts/`、`build/` `out/` `www/`。资源 zip 只含 `assets/`（`publish-template` / `publish-template-data` 的 `--assets` 可指定其它绝对路径，zip 内仍为 `assets/`）。
129
+ **不要打进代码 zip：** `assets/`、`node_modules/`、`dist/`、`.git/`、`.cgmaker/`（包内一律丢弃，防伪造 origin / game.json）、`.agents/` `.cursor/` `.claude/` 等 `skill-targets`、`preview/`、`tests/`、根目录 `scripts/`、`build/` `out/` `www/`。资源 zip 只含工程 `assets/`。
122
130
 
123
131
  平台 skill（`cgmaker`、`cgmaker-template-spec`、`cgmaker-identity`、`cgmaker-play-sdk`）来自 `@66rpg/cgmaker` 包，不来自模板 zip。zip 里的 `skill/` 只可能是玩法 skill。
124
132