@66rpg/cgmaker 0.1.15 → 0.1.16

package/skill/cgmaker-identity/SKILL.md

@@ -1,43 +1,43 @@
----
-name: cgmaker-identity
-description: 模板与游戏的参数与标识配置指南。帮助用户理解 slug、模板ID、素材版本号 data_ver、素材包ID data_id 等参数含义，以及不同发布场景下的功能参数搭配。
----
-
-# 模板与游戏配置参数指南
-
-本文档面向真实用户（模板作者与游戏创作者），详细说明在开发、发布模板与游戏时涉及的各类**配置字段**与**命令行参数**。
-
-具体操作命令的使用方式请参考 `cgmaker` 说明；工程目录结构是否合规请参考 `cgmaker-template-spec`。
-
-## 核心原则
-
-1. **自定义配置项由用户决定**：例如模板英文简称（`slug`）、代码版本号（`version`）、素材版本号（`package.json` 中的 `data_ver` 或命令行的 `--data-ver`），由你在配置文件或发布命令中明确指定。
-2. **平台标识由系统分配**：例如模板 ID（`template_id`）、素材包 ID（`data_id`）、游戏 ID 等，均由平台在创建成功后自动生成，无需也不可人工编造。
-3. **参数按需选用，避免互斥**：不同发布场景对应不同的参数组合，例如不上传素材时无需指定素材版本或素材路径。
-
-各参数与字段的详细定义，见 [references/fields.md](references/fields.md)。
-
-## 常见业务场景与参数选用快速指引
-
-详细的业务分支行为与冲突处理，见 [references/branches.md](references/branches.md)。
-
-- **首次发布新模板**：
-  - 完整发布（含代码与素材）：配置 `package.json` 中的 `slug`，执行发布时传入 `--version` 与 `--data-ver`。
-  - 仅发布代码骨架（暂不上传素材）：传入 `--version`，并追加 `--init --no-data`。
-- **更新已有模板**：
-  - 代码与素材一并更新：传入新 `--version` 与新 `--data-ver`。
-  - 仅更新模板代码：传入新 `--version` 并追加 `--no-data`。
-  - 仅更新素材（关卡/图/文案更新，代码不变）：使用 `publish-template-data`，传入 `--data-ver`；可用 `--data-summary` 写本包说明（空则不写接口）。
-- **基于已有模板派生制作（Fork）**：
-  - 使用 `--fork <版本ID>`。换绑已有素材包用 `--data-id`。本地有素材时走 fork 的 `upload_id`，不要传 `--data-ver` / `--data-summary`（Fork 不走 `data/create`）。
-- **发布游戏正式版与试玩版**：
-  - 正式版：执行 `publish --version <版本号>`。
-  - 试玩版：执行 `publish --demo --version <版本号>`，平台将自动维护正式版与试玩版的关联关系。
-
-## 注意事项
-
-- 请勿在命令中编造或随意伪造任何平台 ID。
-- 请勿使用 `用户名/模板名` 这种格式作为模板标识或用于开工程。
-- 模板工程一旦发布并在实际项目中使用，请勿更改 `package.json` 中的 `slug`。
-- 模板 `--version` / `package.json.version`（接口 `version_name`）须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝发布。游戏 / 开源工程 / `--data-ver` 不套此规则。细则见 [references/fields.md](references/fields.md)。
-- 素材版本号（`--data-ver`）不会由平台自动加 1，每次更新素材时请根据规划显式指定。
+---
+name: cgmaker-identity
+description: 模板与游戏的参数与标识配置指南。帮助用户理解 slug、模板ID、素材版本号 data_ver、素材包ID data_id 等参数含义，以及不同发布场景下的功能参数搭配。
+---
+
+# 模板与游戏配置参数指南
+
+本文档面向真实用户（模板作者与游戏创作者），详细说明在开发、发布模板与游戏时涉及的各类**配置字段**与**命令行参数**。
+
+具体操作命令的使用方式请参考 `cgmaker` 说明（须 `--agent --json`）。工程目录结构是否合规请参考 `cgmaker-template-spec`。见到退出码 10 / 11 / 12 先问用户，不要猜、不要擅自 `--skip-update`。
+
+## 核心原则
+
+1. **自定义配置项由用户决定**：例如模板英文简称（`slug`）、代码版本号（`version`）、素材版本号（`package.json` 中的 `data_ver` 或命令行的 `--data-ver`），由你在配置文件或发布命令中明确指定。
+2. **平台标识由系统分配**：例如模板 ID（`template_id`）、素材包 ID（`data_id`）、游戏 ID 等，均由平台在创建成功后自动生成，无需也不可人工编造。
+3. **参数按需选用，避免互斥**：不同发布场景对应不同的参数组合，例如不上传素材时无需指定素材版本或素材路径。
+
+各参数与字段的详细定义，见 [references/fields.md](references/fields.md)。
+
+## 常见业务场景与参数选用快速指引
+
+详细的业务分支行为与冲突处理，见 [references/branches.md](references/branches.md)。
+
+- **首次发布新模板**：
+  - 完整发布（含代码与素材）：配置 `package.json` 的 `slug` 与 `data_ver`，执行 `publish-template --version …`。该 `data_ver` 尚无包且本地有 `assets/` 时会自动上传；也可显式 `--with-assets`。
+  - 仅发布代码骨架：`publish-template --version … --init`（不要加 `--with-assets` / `--assets`）。
+- **更新已有模板**：
+  - 仅更新模板代码：传入新 `--version`（默认不带数据包；该 `data_ver` 已有包则不再上传；新版本仍绑 origin 的 `data_id`。不要为此传 `--data-ver`）。
+  - 代码与素材一并更新：新 `--version` 加 `--with-assets`（可用 `--data-ver` / `--data-summary` / `--assets`）。
+  - 仅更新素材（关卡/图/文案更新，代码不变）：使用 `publish-template-data`；未传 `--data-ver` 则读 `package.json`（不写回）；显式传入才写回。
+- **基于已有模板派生制作（Fork）**：
+  - 使用 `--fork <版本ID>`。换绑已有素材包用 `--data-id`。要带本地包加 `--with-assets`（走 fork 的 `upload_id`），不要传 `--data-ver` / `--data-summary`（Fork 不走 `data/create`）。
+- **发布游戏正式版与试玩版**：
+  - 正式版：执行 `publish --version <版本号>`。
+  - 试玩版：执行 `publish --demo --version <版本号>`，平台将自动维护正式版与试玩版的关联关系。
+
+## 注意事项
+
+- 请勿在命令中编造或随意伪造任何平台 ID。
+- 请勿使用 `用户名/模板名` 这种格式作为模板标识或用于开工程。
+- 模板工程一旦发布并在实际项目中使用，请勿更改 `package.json` 中的 `slug`。
+- 模板 `--version` / `package.json.version`（接口 `version_name`）须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝发布。游戏 / 开源工程 / `--data-ver` 不套此规则。细则见 [references/fields.md](references/fields.md)。
+- 素材版本号（`--data-ver`）不会由平台自动加 1，每次更新素材时请根据规划显式指定。

package/skill/cgmaker-identity/references/branches.md

@@ -1,149 +1,157 @@
-# 业务场景与参数配置指南
-
-本文档面向真实用户，详细介绍不同业务场景下命令行功能参数的选择与搭配规则，以及各参数值如何影响发布和构建流程。
-
----
-
-## 1. 模板发布业务场景
-
-发布模板时，工具会根据当前工程是否已在平台登记，以及你所提供的命令行参数自动决定业务流向。
-
-### 场景 1.1：首次发布全新模板
-
-当你的模板工程从未在平台发布过，准备首次上架时：
-
-- **方式 A：完整首次发布（代码 + 素材）**
-  - **适用场景**：模板开发完毕，既有完整代码逻辑，也有配套的基础内容或示范素材。
-  - **前置准备**：`package.json` 中已配置好 `slug`、`version` 与 `data_ver`（工具强制校验必填）。
-  - **命令示例**：
-    ```bash
-    # 显式传入版本号
-    npx cgmaker publish-template --version 0.1.0 --data-ver 1 --data-summary "示范关卡"
-
-    # 或直接使用 package.json 中配置的默认版本号
-    npx cgmaker publish-template
-    ```
-  - **参数说明**：
-    - `--version 0.1.0`：定义模板首发版本的代码版本号（未传时默认读取 `package.json` 的 `version`）。须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝发布。
-    - `--data-ver 1`：定义首发素材包的版本编号（未传时默认读取 `package.json` 的 `data_ver`；若显式指定，发布成功后会自动写回 `package.json`）。
-    - 可选 `--data-summary <说明>`：本包说明，写入 `data/create` 的 `summary`。不传或空则不写该字段。
-    - 可选 `--assets <绝对路径>`：如果素材文件不在工程根目录默认的 `assets/` 下，可通过此参数指定实际的本地绝对路径。
-  - **业务逻辑**：平台将为模板创建全新的模板信息、上传素材包，并生成第一个模板发布版本。成功后在 `package.json` 记录 `data_ver`，本地记录模板 ID 与版本 ID。
-
-- **方式 B：仅初始化模板代码框架（暂不带素材）**
-  - **适用场景**：先在平台上建立模板框架，稍后再补充素材，或该模板本身不需要素材包。
-  - **命令示例**：
-    ```bash
-    npx cgmaker publish-template --version 0.1.0 --init --no-data
-    ```
-  - **参数说明**：
-    - `--init`：声明为首次登记初始化模板。
-    - `--no-data`：明确声明本次发布不包含任何素材内容。
-  - **业务逻辑**：平台仅初始化模板身份并发布该代码版本，不生成任何素材包。
-  - **注意**：使用 `--init` 时必须配合 `--no-data`（或当前工程完全无素材文件），**严禁同时传入 `--data-ver` / `--data-summary` / `--assets`**，否则命令会因逻辑冲突而终止。
-
----
-
-### 场景 1.2：已有模板版本更新
-
-当工程已经发布过，后续进行功能迭代或缺陷修复时：
-
-- **方式 A：同时更新代码与素材**
-  - **命令示例**：
-    ```bash
-    npx cgmaker publish-template --version 0.2.0 --data-ver 2 --data-summary "新关卡"
-    ```
-  - **业务逻辑**：向平台提交新一版代码，并为该模板上传一份新素材包，生成新的模板版本。
-
-- **方式 B：仅更新模板代码（素材沿用或不更新）**
-  - **命令示例**：
-    ```bash
-    npx cgmaker publish-template --version 0.2.0 --no-data
-    ```
-  - **业务逻辑**：仅打包并发布新代码，不上传新素材包，新版本模板不会绑定新的素材数据。
-
-- **注意事项**：
-  - 已经发布过的模板，后续更新时**不要重复传入 `--init`**，否则系统会提示已存在而报错。
-
----
-
-### 场景 1.3：仅更新模板素材（代码未变动）
-
-- **适用场景**：模板代码未作任何修改，仅优化或增补了关卡、图集、音效、文字等素材内容。
-- **推荐命令**：使用专用的素材发布命令 `publish-template-data`，无需也不应重新发布代码版本。
-  ```bash
-  # 使用默认 assets/ 目录
-  npx cgmaker publish-template-data --data-ver 2 --data-summary "关卡修订"
-
-  # 指定自定义素材绝对路径
-  npx cgmaker publish-template-data --data-ver 2 --assets D:\templates\custom-assets
-  ```
-- **核心业务影响**：
-  1. 该命令仅将素材打包并上传，生成一个新的**素材包 ID**（`data_id`）。
-  2. **平台不会因此产生新的模板代码版本**，已发布的旧版本模板仍默认维持原有的素材绑定关系。
-  3. 已经基于旧素材开好工的游戏工程不受任何影响。若游戏创作者需要使用这份新素材，可以在开工程时显式指定新生成的素材包 ID。
-
----
-
-### 场景 1.4：基于他人已上架版本派生制作（Fork）
-
-- **适用场景**：需要在平台已有的某个成熟模板版本基础上派生出新的模板（克隆底座），进行二次创作。
-- **命令示例**：
-  ```bash
-  # 方式 A：继承源版本的代码与默认素材绑定
-  npx cgmaker publish-template --version 0.1.0 --fork <源版本ID>
-
-  # 方式 B：继承源版本的代码，并换绑平台已有的一份素材包
-  npx cgmaker publish-template --version 0.1.0 --fork <源版本ID> --data-id <目标素材包ID>
-  ```
-- **业务逻辑**：
-  - 由服务端直接继承源版本的代码底座，本地无需上传源码包。
-  - `--data-id`（或 `--data-ver-id`）仅在包含 `--fork` 时合法，用于挂接已有素材包。
-  - 本地若有素材，经 fork 的 `upload_id` 上传，**不**走 `data/create`，因此不要传 `--data-ver` / `--data-summary`。
-  - 派生成功后将生成全新的模板 ID。
-
----
-
-## 2. 游戏发布业务场景（正式版与试玩版）
-
-在游戏工程中发布游戏产物时：
-
-- **发布正式游戏**：
-  ```bash
-  npx cgmaker publish --version 1.0.0
-  ```
-  - 将当前工程编译产物（`dist/` 目录）上传到平台的正式游戏通道。
-  - 若此工程之前未发布过游戏，平台将创建全新的游戏 ID；若已发布过，则自动追加新版本。
-
-- **发布试玩版本（Demo）**：
-  ```bash
-  npx cgmaker publish --demo --version 1.0.0
-  ```
-  - 试玩版本通过 `--demo` 旗标区分。在平台机制中，试玩版属于**独立的作品发布通道**，拥有独立的试玩游戏 ID。
-  - **支持先发试玩**：允许在正式游戏发布前提前发布试玩版本。
-  - **自动挂接机制**：当同一工程后续执行正式版发布（不带 `--demo`）时，平台会自动检测并关联该工程已有的试玩版，无需创作者手动配置关联关系。
-
----
-
-## 3. 参数冲突与规范清单（避坑指南）
-
-为避免因参数冲突导致命令执行失败，请注意以下规则：
-
-1. **`--assets` 必须是绝对路径**  
-   - 正确：`--assets D:\game\assets` 或 `--assets /Users/name/game/assets`
-   - 错误：`--assets ./assets` 或 `--assets ..\custom-assets`（相对路径将直接导致校验失败退出）
-   - 映射规则：无论外部目录名是什么，打包后在平台素材包中均统一置于 `assets/` 根路径。
-
-2. **声明不传素材时，禁止携带任何素材参数**  
-   - 当使用 `--no-data` 或首次仅发代码的 `--init` 时，表示本次操作排除素材。
-   - 禁止同时传入 `--data-ver`、`--data-summary` 或 `--assets`，否则命令会因语义互斥报错。
-
-3. **`--data-id` 仅用于 Fork 换绑或创建工程**  
-   - 在普通的模板发布（`publish-template` 且未带 `--fork`）中，严禁传入 `--data-id`。
-   - 上传自己本地的素材，必须使用 `--data-ver` 声明版本号。
-
-4. **素材版本号不自动递增**  
-   - 每次调用 `publish-template`（含素材）或 `publish-template-data` 时，请务必明确规划本次素材包的版本号（如 `--data-ver 2`）。
-
-5. **本地测试模板无法直接上架发布**  
-   - 若工程是从本地磁盘目录直接导入安装创建的，其模板处于本地调试模式，无法直接作为官方上架模板执行 `publish-template`。
+# 业务场景与参数配置指南
+
+本文档面向真实用户，详细介绍不同业务场景下命令行功能参数的选择与搭配规则，以及各参数值如何影响发布和构建流程。
+
+---
+
+## 1. 模板发布业务场景
+
+发布模板时，工具会根据当前工程是否已在平台登记，以及你所提供的命令行参数自动决定业务流向。
+
+### 场景 1.1：首次发布全新模板
+
+当你的模板工程从未在平台发布过，准备首次上架时：
+
+- **方式 A：完整首次发布（代码 + 素材）**
+  - **适用场景**：模板开发完毕，既有完整代码逻辑，也有配套的基础内容或示范素材。
+  - **前置准备**：`package.json` 中已配置好 `slug`、`version` 与 `data_ver`（工具强制校验必填）。
+  - **命令示例**：
+    ```bash
+    # 显式传入版本号
+    npx cgmaker publish-template --version 0.1.0 --with-assets --data-ver 1 --data-summary "示范关卡"
+
+    # 或直接使用 package.json 中配置的默认版本号
+    npx cgmaker publish-template
+    ```
+  - **参数说明**：
+    - `--version 0.1.0`：定义模板首发版本的代码版本号（未传时默认读取 `package.json` 的 `version`）。须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝发布。
+    - `--data-ver 1`：定义首发素材包的版本编号（未传则读 `package.json` 的 `data_ver`，不写回；显式指定且上传成功后才写回）。
+    - 可选 `--data-summary <说明>`：本包说明，写入 `data/create` 的 `summary`。不传或空则不写该字段。
+    - 可选 `--assets <绝对路径>`：如果素材文件不在工程根目录默认的 `assets/` 下，可通过此参数指定实际的本地绝对路径（出现即视为要上传）。
+    - 可选 `--with-assets`：即使该 `data_ver` 已有包也再传一包。首发该 `data_ver` 尚无包且本地有 `assets/` 时会自动上传，不必加。
+  - **业务逻辑**：平台将为模板创建全新的模板信息；若本次带数据包则上传素材包，并生成第一个模板发布版本。
+
+- **方式 B：仅初始化模板代码框架（暂不带素材）**
+  - **适用场景**：先在平台上建立模板框架，稍后再补充素材，或该模板本身不需要素材包。
+  - **命令示例**：
+    ```bash
+    npx cgmaker publish-template --version 0.1.0 --init
+    ```
+  - **参数说明**：
+    - `--init`：声明为首次登记初始化模板，不绑数据包。
+  - **业务逻辑**：平台仅初始化模板身份并发布该代码版本，不生成任何素材包。本地即使有 `assets/` 也不会上传。
+  - **注意**：**严禁同时传入 `--with-assets` / `--assets`**，否则命令会因逻辑冲突而终止。
+
+---
+
+### 场景 1.2：已有模板版本更新
+
+当工程已经发布过，后续进行功能迭代或缺陷修复时：
+
+- **方式 A：同时更新代码与素材**
+  - **命令示例**：
+    ```bash
+    npx cgmaker publish-template --version 0.2.0 --with-assets --data-ver 2 --data-summary "新关卡"
+    ```
+  - **业务逻辑**：向平台提交新一版代码，并为该模板上传一份新素材包。该 `data_ver` 尚无包时即使不加 `--with-assets` 也会自动传 `assets/`。
+
+- **方式 B：仅更新模板代码（素材沿用或不更新）**
+  - **命令示例**：
+    ```bash
+    npx cgmaker publish-template --version 0.2.0
+    ```
+  - **业务逻辑**：仅打包并发布新代码。该 `data_ver` 已有包时默认不 `data/create`。新版本仍绑定 origin 里已有的 `data_id`（空 `data_id` 会解绑）。不要为此传 `--data-ver`。
+
+- **注意事项**：
+  - 已经发布过的模板，后续更新时**不要重复传入 `--init`**，否则系统会提示已存在而报错。
+
+---
+
+### 场景 1.3：仅更新模板素材（代码未变动）
+
+- **适用场景**：模板代码未作任何修改，仅优化或增补了关卡、图集、音效、文字等素材内容。
+- **推荐命令**：使用专用的素材发布命令 `publish-template-data`，无需也不应重新发布代码版本。
+  ```bash
+  # 使用默认 assets/ 目录
+  npx cgmaker publish-template-data --data-ver 2 --data-summary "关卡修订"
+
+  # 指定自定义素材绝对路径
+  npx cgmaker publish-template-data --data-ver 2 --assets D:\templates\custom-assets
+  ```
+- **核心业务影响**：
+  1. 该命令仅将素材打包并上传，生成一个新的**素材包 ID**（`data_id`）。
+  2. **平台不会因此产生新的模板代码版本**，已发布的旧版本模板仍默认维持原有的素材绑定关系。
+  3. 已经基于旧素材开好工的游戏工程不受任何影响。若游戏创作者需要使用这份新素材，可以在开工程时显式指定新生成的素材包 ID。
+
+---
+
+### 场景 1.4：基于他人已上架版本派生制作（Fork）
+
+- **适用场景**：需要在平台已有的某个成熟模板版本基础上派生出新的模板（克隆底座），进行二次创作。
+- **命令示例**：
+  ```bash
+  # 方式 A：继承源版本的代码与默认素材绑定
+  npx cgmaker publish-template --version 0.1.0 --fork <源版本ID>
+
+  # 方式 B：继承源版本的代码，并换绑平台已有的一份素材包
+  npx cgmaker publish-template --version 0.1.0 --fork <源版本ID> --data-id <目标素材包ID>
+
+  # 方式 C：继承源版本的代码，并上传本地素材（走 fork 的 upload_id，不走 data/create）
+  npx cgmaker publish-template --version 0.1.0 --fork <源版本ID> --with-assets
+  ```
+- **业务逻辑**：
+  - 由服务端直接继承源版本的代码底座，本地无需上传源码包。
+  - `--data-id`（或 `--data-ver-id`）仅在包含 `--fork` 时合法，用于挂接已有素材包。
+  - 默认不传本地包。本地素材须 `--with-assets` / `--assets` 才走 fork 的 `upload_id`，**不**走 `data/create`，因此不要传 `--data-ver` / `--data-summary`。
+  - 派生成功后将生成全新的模板 ID。
+
+---
+
+## 2. 游戏发布业务场景（正式版与试玩版）
+
+在游戏工程中发布游戏产物时：
+
+- **发布正式游戏**：
+  ```bash
+  npx cgmaker publish --version 1.0.0
+  ```
+  - 将当前工程编译产物（`dist/` 目录）上传到平台的正式游戏通道。
+  - 若此工程之前未发布过游戏，平台将创建全新的游戏 ID；若已发布过，则自动追加新版本。
+
+- **发布试玩版本（Demo）**：
+  ```bash
+  npx cgmaker publish --demo --version 1.0.0
+  ```
+  - 试玩版本通过 `--demo` 旗标区分。在平台机制中，试玩版属于**独立的作品发布通道**，拥有独立的试玩游戏 ID。
+  - **支持先发试玩**：允许在正式游戏发布前提前发布试玩版本。
+  - **自动挂接机制**：当同一工程后续执行正式版发布（不带 `--demo`）时，平台会自动检测并关联该工程已有的试玩版，无需创作者手动配置关联关系。
+
+---
+
+## 3. 参数冲突与规范清单（避坑指南）
+
+为避免因参数冲突导致命令执行失败，请注意以下规则：
+
+1. **`--assets` 必须是绝对路径**  
+   - 正确：`--assets D:\game\assets` 或 `--assets /Users/name/game/assets`
+   - 错误：`--assets ./assets` 或 `--assets ..\custom-assets`（相对路径将直接导致校验失败退出）
+   - 映射规则：无论外部目录名是什么，打包后在平台素材包中均统一置于 `assets/` 根路径。
+
+2. **`--init` 与显式带包互斥**  
+   - `--init` 表示本次不绑数据包。不要同时传 `--with-assets` / `--assets`。
+   - 普通发模板默认不带包；要再传一包用 `--with-assets`。该 `data_ver` 尚无包且本地有 `assets/` 时会自动带上。
+   - 无 origin 时默认路径 A，不要擅自加 `--init`。
+
+3. **`--data-id` 仅用于 Fork 换绑或创建工程**  
+   - 在普通的模板发布（`publish-template` 且未带 `--fork`）中，严禁传入 `--data-id`。
+   - 上传自己本地的素材，用 `--with-assets` 声明（Fork 不要再传 `--data-ver`）。
+
+4. **`--data-ver` 仅在实际上传数据包时使用**  
+   - 续发默认不带包时不要传 `--data-ver`，否则退出 2。
+   - `--init` / `--fork` 也不要带。
+
+5. **素材版本号不自动递增，未指定则不改 `package.json`**  
+   - 未传 `--data-ver` 时读 `package.json` 的 `data_ver`，不写回。只有命令行显式传入且上传成功才写回。
+
+6. **本地测试模板无法直接上架发布**  
+   - 若工程是从本地磁盘目录直接导入安装创建的，其模板处于本地调试模式，无法直接作为官方上架模板执行 `publish-template`。

package/skill/cgmaker-identity/references/fields.md

@@ -1,59 +1,59 @@
-# 参数与配置字段说明
-
-本文档面向真实用户，详细罗列在开发、构建和发布模板或游戏过程中涉及的所有配置字段、命令行功能参数以及平台标识的作用与使用规范。
-
----
-
-## 1. 模板工程配置字段（`package.json`）
-
-在开发模板工程时，由你在根目录的 `package.json` 中配置：
-
-| 字段名称 | 类型 | 是否必填 | 功能与使用说明 | 配置规范与注意事项 |
-|---|---|---|---|---|
-| `slug` | 字符串 | 是 | **模板的唯一英文简称**。用于在开发阶段或没有发布前标识该模板工程，并在工具检查时作为模板合法性的依据。 | 仅支持小写字母、数字与中划线（连字符），如 `quiz-react`。**模板发布后请勿随意修改**，否则后续依赖此模板的衍生工程将无法正常识别。注意：它**不是**平台分配的模板 ID。 |
-| `version` | 字符串 | 是 | **工程的默认代码版本号**。作为当前模板或工程的代码版本基准。 | 执行发布命令时若未显式传入 `--version`，工具将默认采用该值。**仅发布模板**（`publish-template`）时该值作为接口 `version_name`，须 1–16 位、仅小写字母/数字/`.`/`-`、以字母或数字开头和结尾、不能有连续符号（如 `0.1.0`、`1.0.0-a`）。游戏与开源工程发版不套此格式。 |
-| `data_ver` | 字符串或数字 | 是 | **模板配套素材的版本号**。用于标识当前工程配套素材的版本。模板规范校验（`validate-template`）与发布模板（`publish-template`）时**强制要求该字段存在**。 | 建议从 `"1"` 开始（如 `"1"`、`"2"`）。执行发布命令时若显式指定了 `--data-ver`，发布成功后工具会自动将新版本号写回 `package.json` 中保存。 |
-
----
-
-## 2. 命令行功能参数详解
-
-在调用 `cgmaker` 各类发布或创建命令时使用的主要功能参数：
-
-| 参数名称 | 适用命令 | 是否必填 | 功能与作用说明 | 参数规则与配置示例 |
-|---|---|---|---|---|
-| `--version <版本号>` | `publish-template` | 推荐显式指定 | **指定本次发布的模板版本号**（接口 `version_name`）。 | 覆盖 `package.json` 的 `version`。须 1–16 位，仅小写字母、数字、`.`、`-`；必须以字母或数字开头和结尾，且不能有连续符号。例如 `--version 1.0.0`。不合法则拒绝发布。<br>注：单独执行 `cgmaker --version`（前面无子命令）输出的是工具客户端自身的软件版本，两者含义不同。 |
-| `--version <版本号>` | `publish`<br>`publish-project` | 推荐显式指定 | **指定本次发布的游戏 / 开源工程版本号**。 | 覆盖 `package.json` 的 `version`。例如 `--version 1.0.0`。不套模板 `version_name` 的格式校验。 |
-| `--data-ver <素材版本号>` | `publish-template`<br>`publish-template-data` | 选填（未传时默认读取 `package.json`） | **指定本次上传素材包的版本编号**。用于在平台区分不同批次或规格的素材内容。 | 字符串或数字（如 `--data-ver 2`）。若命令行未指定，工具优先从 `package.json` 的 `data_ver` 字段读取；若命令行显式传入，发布成功后会自动同步写回 `package.json`。<br>**注意：平台不会自动自增此版本号**。若本次不走 `data/create`（`--no-data` / `--init` / `--fork`），严禁携带此参数。 |
-| `--data-summary <说明>` | `publish-template`<br>`publish-template-data` | 选填 | **本次素材包的说明**。对应 `data/create` 的 `summary`。同一 `data_ver` 下有多包时用来区分。 | 例如 `--data-summary "春节活动关卡"`。不传、空串、纯空格或交互回车都不写入接口。仅在走 `data/create` 时有效；不要与 `--no-data` / `--init` / `--fork` 同时使用。 |
-| `--assets <绝对路径>` | `publish-template`<br>`publish-template-data` | 选填 | **自定义素材目录的完整来源路径**。当素材文件不在默认的工程根目录 `assets/` 下时使用。 | **必须是本机完整绝对路径**（例如 `D:\game-project\custom-assets`），不支持相对路径。<br>素材上传后在包内均自动映射为 `assets/` 根目录。若声明了不上传素材，严禁使用此参数。 |
-| `--no-data` | `publish-template` | 选填 | **声明本次发布仅上传模板代码，不上传任何素材包**。 | 适用于代码逻辑迭代但素材未变动的更新场景。使用时不可同时传入 `--data-ver`、`--data-summary` 或 `--assets`。 |
-| `--init` | `publish-template` | 首次发空代码时选填 | **声明首次登记并初始化模板代码，不绑定任何素材包**。 | 仅用于未曾发布过的模板工程首次上线代码框架。必须配合 `--no-data` 或确保当前无素材目录。不可与 `--data-ver` / `--data-summary` / `--assets` 混用。 |
-| `--fork <源版本ID>` | `publish-template` | 派生制作时必填 | **基于平台上已有的某个模板版本派生新模板**。 | 服务端继承该版本的代码底座，本地无需上传源码包。换绑已有素材用 `--data-id`；本地素材走 fork 的 `upload_id`。不要传 `--data-ver` / `--data-summary`。 |
-| `--data-id`<br>（或 `--data-ver-id`） | `publish-template`（搭配 `--fork`）<br>`cgmaker-create`（开工程） | 选填 | **指定或换绑平台上已存在的素材包 ID**。 | 在使用 `--fork` 派生模板时，用于直接挂接指定素材包；在创建工程时，用于指定下载历史特定版本的素材包。普通发布模板场景无需使用。 |
-| `--demo` | `publish` | 选填 | **指定本次发布为试玩版本（Demo）**。 | 发布游戏的试玩内容。试玩与正式版通道独立，支持独立抢先发布，后续在同一工程发布正式版时平台会自动建立两者关联。 |
-
----
-
-## 3. 平台全局标识（ID）与用途
-
-你在平台管理后台、命令执行成功的输出结果，或开工程参数中会接触到的核心标识：
-
-| 标识名称 | 产生方式 | 主要用途与业务意义 |
-|---|---|---|
-| **模板 ID**（`template_id`） | 首次发布模板成功后由平台统一分配 | 模板在全平台的唯一全局身份编号（通常为 12 位左右的英数混合字符串，如 `4p7fh9mytcsg`）。创作者使用脚手架开工程时必须指定该 ID（如 `npx @66rpg/cgmaker-create <template_id>`）。 |
-| **版本 ID**（`version_id`） | 每次发布新的模板代码版本时生成 | 标识某一次具体的模板代码迭代版本。游戏工程在与模板建立依赖关系时，实际绑定的是特定的版本 ID。 |
-| **素材包 ID**（`data_id`；CLI JSON 成功载荷键名 `data_ver_id`） | 每次成功上传素材包后生成 | 标识一份独立的素材内容包。通过此 ID，模板作者可以在不同代码版本间复用素材包，游戏创作者也可以在开工程时指定拉取特定的素材包。 |
-| **游戏 ID**（`game_id` / `demo_game_id`） | 首次发布游戏成功后由平台统一分配 | 游戏在平台上的唯一编号。正式版与试玩版各对应一个独立 ID，试玩版本可先于正式版发布，系统会自动维护两者的绑定关系。 |
-
----
-
-## 4. 常见易混淆概念说明
-
-### 模板短名（`slug`） vs 模板 ID（`template_id`）
-- **`slug`**：由你自行命名的英文别名，保存在本地 `package.json` 中，便于开发阶段阅读与标识。
-- **`template_id`**：由平台系统自动分配的唯一全球编码。使用脚手架创建游戏工程时，**必须且只能使用平台的模板 ID**，不可传入 `slug` 或 `用户名/slug`。
-
-### 素材版本号（`--data-ver`） vs 素材包 ID（`data_id`）
-- **`--data-ver`**：由你规划并填写的版本标号（如第 1 版、第 2 版，用 `1`、`2` 表示），便于人类记忆与辨识。**它不会自动加 1**，每次上传素材包时均需由你指定。
-- **`data_id`**：平台为该次上传生成的全局唯一物理标识。开工程或换绑时，系统通过该 ID 精确获取该包素材。
+# 参数与配置字段说明
+
+本文档面向真实用户，详细罗列在开发、构建和发布模板或游戏过程中涉及的所有配置字段、命令行功能参数以及平台标识的作用与使用规范。
+
+---
+
+## 1. 模板工程配置字段（`package.json`）
+
+在开发模板工程时，由你在根目录的 `package.json` 中配置：
+
+| 字段名称 | 类型 | 是否必填 | 功能与使用说明 | 配置规范与注意事项 |
+|---|---|---|---|---|
+| `slug` | 字符串 | 是 | **模板的唯一英文简称**。用于在开发阶段或没有发布前标识该模板工程，并在工具检查时作为模板合法性的依据。 | 仅支持小写字母、数字与中划线（连字符），如 `quiz-react`。**模板发布后请勿随意修改**，否则后续依赖此模板的衍生工程将无法正常识别。注意：它**不是**平台分配的模板 ID。 |
+| `version` | 字符串 | 是 | **工程的默认代码版本号**。作为当前模板或工程的代码版本基准。 | 执行发布命令时若未显式传入 `--version`，工具将默认采用该值。**仅发布模板**（`publish-template`）时该值作为接口 `version_name`，须 1–16 位、仅小写字母/数字/`.`/`-`、以字母或数字开头和结尾、不能有连续符号（如 `0.1.0`、`1.0.0-a`）。游戏与开源工程发版不套此格式。 |
+| `data_ver` | 字符串或数字 | 是 | **模板配套素材的版本号**。用于标识当前工程配套素材的版本。模板规范校验（`validate-template`）与发布模板（`publish-template`）时**强制要求该字段存在**。 | 建议从 `"1"` 开始（如 `"1"`、`"2"`）。未传 `--data-ver` 时沿用此字段且不改写；仅命令行显式传入 `--data-ver` 且上传成功后才写回。 |
+
+---
+
+## 2. 命令行功能参数详解
+
+在调用 `cgmaker` 各类发布或创建命令时使用的主要功能参数：
+
+| 参数名称 | 适用命令 | 是否必填 | 功能与作用说明 | 参数规则与配置示例 |
+|---|---|---|---|---|
+| `--version <版本号>` | `publish-template` | 推荐显式指定 | **指定本次发布的模板版本号**（接口 `version_name`）。 | 覆盖 `package.json` 的 `version`。须 1–16 位，仅小写字母、数字、`.`、`-`；必须以字母或数字开头和结尾，且不能有连续符号。例如 `--version 1.0.0`。不合法则拒绝发布。<br>注：单独执行 `cgmaker --version`（前面无子命令）输出的是工具客户端自身的软件版本，两者含义不同。 |
+| `--version <版本号>` | `publish`<br>`publish-project` | 推荐显式指定 | **指定本次发布的游戏 / 开源工程版本号**。 | 覆盖 `package.json` 的 `version`。例如 `--version 1.0.0`。不套模板 `version_name` 的格式校验。 |
+| `--data-ver <素材版本号>` | `publish-template`<br>`publish-template-data` | 选填（未传时默认读取 `package.json`） | **指定本次上传素材包的版本编号**。用于在平台区分不同批次或规格的素材内容。 | 字符串或数字（如 `--data-ver 2`）。未指定则读 `package.json` 的 `data_ver`，**不写回**。仅当命令行显式传入且实际上传成功后才写回。<br>**注意：平台不会自动自增此版本号**。未实际上传时不要带此参数（含续发默认不带包、`--init` / `--fork`），否则退出 2。 |
+| `--data-summary <说明>` | `publish-template`<br>`publish-template-data` | 选填 | **本次素材包的说明**。对应 `data/create` 的 `summary`。同一 `data_ver` 下有多包时用来区分。 | 例如 `--data-summary "春节活动关卡"`。不传、空串、纯空格或交互回车都不写入接口。仅在走 `data/create` 时有效；不要与 `--init` / `--fork` 同时使用。 |
+| `--with-assets` | `publish-template` | 选填 | **显式同时上传数据包**。 | 默认不带包。该 `data_ver` 在平台尚无包且本地有 `assets/` 时也会自动上传。再传一包须加本开关。不要与 `--init` 同时使用。 |
+| `--assets <绝对路径>` | `publish-template`<br>`publish-template-data` | 选填 | **自定义素材目录的完整来源路径**。当素材文件不在默认的工程根目录 `assets/` 下时使用。 | **必须是本机完整绝对路径**（例如 `D:\game-project\custom-assets`），不支持相对路径。zip 内仍为 `assets/`。在 `publish-template` 上出现即视为要上传。不要与 `--init` 同时使用。 |
+| `--init` | `publish-template` | 首次发空代码时选填 | **声明首次登记并初始化模板代码，不绑定任何素材包**。 | 仅用于未曾发布过的模板工程首次上线代码框架。不可与 `--with-assets` / `--assets` 混用。本地有 `assets/` 也不再要求加排除开关。 |
+| `--fork <源版本ID>` | `publish-template` | 派生制作时必填 | **基于平台上已有的某个模板版本派生新模板**。 | 服务端继承该版本的代码底座，本地无需上传源码包。换绑已有素材用 `--data-id`。默认不传本地包；须 `--with-assets` / `--assets` 才走 fork 的 `upload_id`。不要传 `--data-ver` / `--data-summary`。 |
+| `--data-id`<br>（或 `--data-ver-id`） | `publish-template`（搭配 `--fork`）<br>`cgmaker-create`（开工程） | 选填 | **指定或换绑平台上已存在的素材包 ID**。 | 在使用 `--fork` 派生模板时，用于直接挂接指定素材包；在创建工程时，用于指定下载历史特定版本的素材包。普通发布模板场景无需使用。 |
+| `--demo` | `publish` | 选填 | **指定本次发布为试玩版本（Demo）**。 | 发布游戏的试玩内容。试玩与正式版通道独立，支持独立抢先发布，后续在同一工程发布正式版时平台会自动建立两者关联。 |
+
+---
+
+## 3. 平台全局标识（ID）与用途
+
+你在平台管理后台、命令执行成功的输出结果，或开工程参数中会接触到的核心标识：
+
+| 标识名称 | 产生方式 | 主要用途与业务意义 |
+|---|---|---|
+| **模板 ID**（`template_id`） | 首次发布模板成功后由平台统一分配 | 模板在全平台的唯一全局身份编号（通常为 12 位左右的英数混合字符串，如 `4p7fh9mytcsg`）。创作者使用脚手架开工程时必须指定该 ID（如 `npx @66rpg/cgmaker-create <template_id>`）。 |
+| **版本 ID**（`version_id`） | 每次发布新的模板代码版本时生成 | 标识某一次具体的模板代码迭代版本。游戏工程在与模板建立依赖关系时，实际绑定的是特定的版本 ID。 |
+| **素材包 ID**（`data_id`；CLI JSON 成功载荷键名 `data_ver_id`） | 每次成功上传素材包后生成 | 标识一份独立的素材内容包。通过此 ID，模板作者可以在不同代码版本间复用素材包，游戏创作者也可以在开工程时指定拉取特定的素材包。 |
+| **游戏 ID**（`game_id` / `demo_game_id`） | 首次发布游戏成功后由平台统一分配 | 游戏在平台上的唯一编号。正式版与试玩版各对应一个独立 ID，试玩版本可先于正式版发布，系统会自动维护两者的绑定关系。 |
+
+---
+
+## 4. 常见易混淆概念说明
+
+### 模板短名（`slug`） vs 模板 ID（`template_id`）
+- **`slug`**：由你自行命名的英文别名，保存在本地 `package.json` 中，便于开发阶段阅读与标识。
+- **`template_id`**：由平台系统自动分配的唯一全球编码。使用脚手架创建游戏工程时，**必须且只能使用平台的模板 ID**，不可传入 `slug` 或 `用户名/slug`。
+
+### 素材版本号（`--data-ver`） vs 素材包 ID（`data_id`）
+- **`--data-ver`**：由你规划并填写的版本标号（如第 1 版、第 2 版，用 `1`、`2` 表示），便于人类记忆与辨识。**它不会自动加 1**。未传则读 `package.json`，不写回。
+- **`data_id`**：平台为该次上传生成的全局唯一物理标识。开工程或换绑时，系统通过该 ID 精确获取该包素材。