@66rpg/cgmaker 0.1.23 → 0.1.24

package/skill/cgmaker/SKILL.md

@@ -1,131 +1,120 @@
----
-name: cgmaker
-description: 登录橙光托管平台，发布静态游戏、模板或开源工程。用户说发布、上传、上线、login、publish、发模板、发游戏、开源工程时使用。不要运行 npm login 或 npm publish。
----
-
-# cgmaker 平台（给 Agent）
-
-作者长文在仓库 `docs/users.md`。你不要整篇引用，按本文决策。
-
-`validate-template` 走 kit TS。其余命令转发 `cgmaker`。本期只保证 Windows x64。
-
-不要对用户说「已通过审核」或「已上线」，除非命令退出 0 且 JSON `success` 为 true 且 `data.status === 4`。`success: true` 只表示已上传并提交审核，审核是异步的：`data.status` 为 2/3 时机审/人审中，为 5 时已被拒绝；终态用 `games --versions` / `templates --versions` / `projects --versions` 查看审核结果。
-
-`login` 默认已有有效登录则跳过；换号用 `npx cgmaker login --force`。
-
-## 怎么问用户
-
-不要问用户过于专业的技术问题，除非你清楚知道对方具备专业能力（例如他自己先说出了命令、旗标、字段名）。
-
-所有问用户的问题，都用更口语、易懂的方式。信封 `data.questions` 只给你对照，转述时改成白话；你自己把答案翻译成旗标后重跑即可。
-
-## 必须带 `--agent --json`，缺参时先问人
-
-每条 `npx cgmaker` / `npx @66rpg/cgmaker-create` **都加 `--agent --json`**。不要猜用户没给的参数。
-
-见到下面退出码，**先问用户，禁止擅自填默认、禁止擅自 `--skip-update`**：
-
-| 退出码 | `command` | 你要做的 |
-|---|---|---|
-| 10 | `update-available` | 列出 `data.packages`，问「推荐更新，是否现在更新？」同意：执行信封 `data.apply`（kit：`npx cgmaker --apply-update`；create：`npx @66rpg/cgmaker-create@latest --apply-update`）。空目录没有 `package.json` 时不要 `npm install`，直接用 `@latest` 重跑原命令。成功后再原样重跑。拒绝：原命令加 `--skip-update` |
-| 11 | `need-input` | 按 `data.questions` 逐项问人（`recommended` 标推荐）。**用口语问**，不要把旗标名念给用户。把答案变成旗标后重跑 |
-| 12 | `login-required` | 问「是否现在打开浏览器登录？」同意：`npx cgmaker login`，等人完成后再重跑原命令 |
-
-`--agent` 只给 Agent 用。没有该旗标时脚本仍走静默默认，不要改用户的非 Agent 命令。
-
-## 何时启用
-
-登录、发游戏 `dist/`、发模板、发开源工程、改帖子。改目录 / 指纹用 `cgmaker-template-spec`，不要用本 skill 改规范。查阅模板短名、版本号、素材版本号及发布参数搭配，看 `cgmaker-identity`。游戏里调宿主登录 / 查用户 / 跳转 / 全屏，看 `cgmaker-play-sdk`（SDK 由发布时注入，不要把文件打进工程）。
-
-## 不要做
-
-- 不要 `npm login` / `npm publish`。游戏和模板上的是橙光托管。
-- 不要编造 `template_id` / `game_id` / `project_id`。开工程用网页给的 `用户名/模板名`（可 `@版本`）；其它命令仍用平台 id。
-- 不要把私有 npm registry、内网 IP、镜像域名写进回复、`.npmrc` 或命令示例。用户若装不上 `@66rpg/*`，让他联系客服。具体邮箱和 QQ 以 CLI 提示为准，不要编造。
-- 发模板 / 游戏 / 开源工程成功后，把 CLI 给出的页面链接交给用户。`data.post_status === 4` 是已公开页，否则是草稿页（请用户自己去网页确认）。不要和版本审核 `data.status` 混读，不要自己拼链接。
-- `--from-dir` 的 origin 为 `local`，不能 `publish-template`。
-- 不要把试玩当成同一 `game_id` 的第二个通道。首发可以只发试玩；后补正式版会自动挂接。
-- 用户没说工程放哪时，不要自己编文件夹名（不要填 `my-game`，不要用模板 id）。省略目录参数让 create 退出 11，用口语问完再重跑。
-- 首发模板不要用 `slug` 冒充平台名。没有合法 `--name` / `package.json.name` 时退出 11，用口语问「这个模板在平台上叫什么？」（不能含 `/` 或 `@`）。不要擅自填。
-- 发游戏不要擅自加 `--yes`。补齐参数后若信封还有确认项，把名称、版本、正式/试玩等摘要念给用户，**等人点头**再带 `--yes` 重跑。拒绝则停止。
-
-## 发布前请确认
-
-- **发模板或开源工程**：上传的是源码，**不含** `node_modules`。别人从平台拿到工程后，必须能按 `package.json` 把依赖装上。依赖须是公开可装的包、版本号真实存在（不要写只有你电脑上才有的包、未发布的私有包、或装不到的版本）。装不上就先改依赖再发。
-- **发模板、游戏或开源工程**：运行时**不能用在线资源**（CDN 图片、远程字体、外链脚本/样式、热链网上的音视频等）。图、音、字体、文案、数据都用工程里的本地文件：模板和开源工程放在 `assets/` 或源码内；游戏须打进 `dist/`。发现外链，先改成本地再发。
-
-## 按业务选命令
-
-从模板开工程（用户还没有目录）：
-
-用户没说工程放哪时，**不要自己编文件夹名**。省略目录参数，让 create 退出 11，用口语问「工程要建在哪个文件夹？」。用户回答后再把名字写进命令重跑。未指定 `--skill-platform` 时 CLI 会探测当前编辑器并询问（信封会标明「当前」），**不要擅自写成 cursor**。仅 `npx @66rpg/cgmaker-create`、还没装 kit 时，以该包 `skill/cgmaker-create/SKILL.md` 为准。
-
-```bash
-npx @66rpg/cgmaker-create@latest --agent --json <用户名/模板名>
-npx @66rpg/cgmaker-create@latest --agent --json <用户名/模板名> <用户说的目录>
-npx @66rpg/cgmaker-create@latest --agent --json <用户名/模板名@版本> --with-assets <数据包ID>
-```
-
-缺目录或 skill 时 create 退出 11。未登录（12）时脚手架会留在用户说的目录里，**不要换文件夹、不要删目录**。先 `login` 后用同一目录重跑原 create 命令即可续 init。网页命令没有 `--with-assets` 就不要补素材包。补装同样先让 CLI 探测再问，不要擅自加 `--platform cursor`：
-
-```bash
-npx cgmaker --agent --json skill
-npx cgmaker --agent --json skill --all
-```
-
-发正式游戏：
-
-```bash
-npx cgmaker --agent --json login
-npx cgmaker --agent --json whoami
-npx cgmaker --agent --json validate-template
-npm run build
-npx cgmaker --agent --json publish --version 1.0.0
-npx cgmaker --agent --json publish --version 1.0.0 --yes
-```
-
-缺名称/版本等会先退出 11。补齐后再出现确认时，把摘要念给用户，同意后加 `--yes` 重跑。**不要**自己加 `--yes`。
-
-发试玩（独立游戏；可无正式版首发，后补正式版会自动挂接）：
-
-```bash
-npm run build:demo
-npx cgmaker --agent --json publish --demo --version 1.0.0
-```
-
-发模板：
-
-```bash
-npx cgmaker --agent --json validate-template
-npm run build
-npx cgmaker --agent --json publish-template --version 0.1.0
-npx cgmaker --agent --json publish-template --version 0.1.0 --changelog "首发"
-npx cgmaker --agent --json publish-template --version 0.1.1 --with-assets --data-ver 1 --data-summary "示范关卡"
-npx cgmaker --agent --json publish-template --version 0.1.1 --with-assets --assets C:\path\to\assets
-npx cgmaker --agent --json publish-template-data --data-ver 2 --data-summary "关卡修订"
-npx cgmaker --agent --json publish-template-data --data-ver 2 --assets C:\path\to\assets
-```
-
-无 origin 时 `publish-template` **默认首发**：`versions/create` 且 `template_id` 为空，**第一版不能绑数据包**（不要加 `--with-assets` / `--assets` / `--data-ver`）。不要擅自加 `--init`（与默认首发相同）。派生用 `--fork <version_id>`。`package.json` 必须有 `scripts.build:demo` 与 `data_ver`。**平台模板名**必须由用户给出（`--name` 或已有合法 `package.json.name`），不能含 `/` 或 `@`；不要用 `slug` 顶上。`--version`（缺省 `package.json.version`）须为模板 `version_name`：1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝。续发默认不带数据包；该 `data_ver` 尚无包且本地有 `assets/` 则自动上传。再带包用 `--with-assets`。上传数据包时可用 `--assets`（绝对路径，出现即视为要上传）和 `--data-summary`（空则不写接口 `summary`）。未传 `--data-ver` 时读 `package.json`、不写回；显式传入且上传成功才写回。未实际上传时不要传 `--data-ver`。续发不带包时新版本仍绑 origin 的 `data_id`。只改 `assets/`、不发新代码版本：`publish-template-data`（须已有非 local 的 origin；不改已有 `version_id` 的绑定，游戏作者用 `--with-assets` 拉新包）。`--fork` 不要带 `--data-ver` / `--data-summary`；fork 要带本地包加 `--with-assets`。参数说明与业务场景配置，见 `cgmaker-identity`。
-
-发开源工程：
-
-```bash
-npx cgmaker --agent --json publish-project --version 1.0.0
-```
-
-改帖子（不上传产物）：
-
-```bash
-npx cgmaker --agent --json games update --name "..."
-npx cgmaker --agent --json games update --status 2
-npx cgmaker --agent --json games update --changelog "..."
-npx cgmaker --agent --json templates update --name "..."
-npx cgmaker --agent --json templates update --status 2
-npx cgmaker --agent --json templates update --changelog "..."
-npx cgmaker --agent --json projects update --name "..."
-```
-
-`--status 1|2` 是货架上架/下架，**不是**审核状态。不要把 update 回包的 `shelf_status` 当成 `data.status === 4`。`demo_scope` / `play_duration` 只能在新建游戏的 `publish` 上带 `--demo-scope` / `--play-duration`；续发和 `games update` 都不要传。
-
-`.cgmaker/` 要进 git。config 手动放 `~/.cgmaker/config.json`。凭据在密钥环。
+---
+name: cgmaker
+description: 登录橙光托管平台，发布静态游戏、模板或开源工程。用户说发布、上传、上线、login、publish、发模板、发游戏、开源工程时使用。不要运行 npm login 或 npm publish。
+---
+
+# cgmaker 平台（给 Agent）
+
+作者长文在仓库 `docs/users.md`。你不要整篇引用，按本文决策。
+
+`validate-template` 走 kit TS。`validate` 转调工程里的 `npm run validate`。其余命令转发 `cgmaker`。目前只保证 Windows x64。
+
+不要对用户说「已通过审核」或「已上线」，除非命令退出 0 且 JSON `success` 为 true 且 `data.status === 4`。`success: true` 只表示已上传并提交审核，审核是异步的：`data.status` 为 2/3 时机审/人审中，为 5 时已被拒绝；终态请用户到网页查看。
+
+`login` 默认已有有效登录则跳过；换号用 `npx cgmaker login --force`。
+
+## 怎么问用户
+
+不要问用户过于专业的技术问题，除非你清楚知道对方具备专业能力（例如他自己先说出了命令、旗标、字段名）。
+
+所有问用户的问题，都用更口语、易懂的方式。信封 `data.questions` 只给你对照，转述时改成白话；有 `flag` 的把答案变成旗标后重跑，有 `field` 的写入该文件字段后再原样重跑。
+
+## 缺参时先问人（输出模式由程序判断）
+
+不要给命令加输出格式开关。人在终端走交互卡片；你在编辑器里跑命令（非 TTY）会自动走 JSON 信封；脚本管道同样自动信封。不要猜用户没给的参数。
+
+`version`、`data_ver` 和素材目录都写在 `package.json` / 工程 `assets/`，**不要**把 `--version`、`--data-ver`、`--assets` 写进命令。素材包说明可用 `--data-summary`，或写在 `package.json.data_summary`。缺 `version` / `data_ver` 时用口语问人，把答案写入信封里的 `field`（如 `package.json.version`），写完后**原样重跑**。平台模板名优先合法 `package.json.name`：没有时退出 11，口语问完后写入该字段再重跑。若现有 `name` 含 `/` 或 `@`（npm 包名），不要覆盖该字段，信封会给 `flag: --name`，把答案变成旗标后重跑。不要擅自填。发版**不要**加 `--changelog`（更新说明去网页改）。
+
+见到下面退出码，**先问用户，禁止擅自填默认、禁止擅自 `--skip-update`**：
+
+| 退出码 | `command` | 你要做的 |
+|---|---|---|
+| 10 | `update-available` | 列出 `data.packages`，问「推荐更新，是否现在更新？」同意：执行信封 `data.apply`（kit：`npx cgmaker --apply-update`；create：`npx @66rpg/cgmaker-create@latest --apply-update`）。空目录没有 `package.json` 时不要 `npm install`，直接用 `@latest` 重跑原命令。成功后再原样重跑。拒绝：原命令加 `--skip-update` |
+| 11 | `need-input` | 按 `data.questions` 逐项用口语问人（`recommended` 标推荐）。不要把旗标名念给用户。有 `flag` 的把答案变成旗标后重跑；有 `field` 的把答案写入该文件字段，不要加 CLI 旗标，写完后原样重跑 |
+| 12 | `login-required` | 问「是否现在打开浏览器登录？」同意：`npx cgmaker login`，等人完成后再重跑原命令 |
+
+不要改用户的非 Agent 命令。
+
+## 何时启用
+
+登录、发游戏 `dist/`、发模板、发开源工程。改帖子请用户到网页操作，不要跑列表或改帖命令。改目录 / 指纹用 `cgmaker-template-spec`，不要用本 skill 改规范。查阅模板短名、版本号、素材版本号及发布参数搭配，看 `cgmaker-identity`。游戏里调宿主登录 / 查用户 / 跳转 / 全屏，看 `cgmaker-play-sdk`（SDK 由发布时注入，不要把文件打进工程）。
+
+## 不要做
+
+- 不要 `npm login` / `npm publish`。游戏和模板上的是橙光托管。
+- 不要编造 `template_id` / `game_id` / `project_id`。开工程用网页给的 `用户名/slug`（可 `@版本`）；其它命令仍用平台 id。
+- 不要把私有 npm registry、内网 IP、镜像域名写进回复、`.npmrc` 或命令示例。用户若装不上 `@66rpg/*`，让他联系客服。具体邮箱和 QQ 以 CLI 提示为准，不要编造。
+- 发模板 / 游戏 / 开源工程成功后，必须把帖子链接交给用户。信封里从 `data.post_url` 念成「帖子：…」；人手动跑时 CLI 自己会在成功卡片下再打一整行「帖子：」。`data.post_status === 4` 是已公开，否则是草稿（请用户自己去网页确认）。不要和版本审核 `data.status` 混读，不要自己拼链接。
+- 发模板成功后若信封有 `owner` 和 `slug`，把 CLI「他人拉取」那一行原样交给用户（`用户名/slug@version`），**不要**用 `template_name` / `name`，缺 `owner` 时不要自己拼 `<用户名>`。有 `data_ver_id` 再加 `--with-assets`。
+- `--from-dir` 的 origin 为 `local`，不能 `publish-template`。
+- 不要把试玩当成同一 `game_id` 的第二个通道。首发可以只发试玩；后补正式版会自动挂接。
+- 用户没说工程放哪时，不要自己编文件夹名（不要填 `my-game`，不要用模板 id）。省略目录参数让 create 退出 11，用口语问完再重跑。
+- 首发模板不要用 `slug` 冒充平台名。没有合法 `package.json.name` 时退出 11，用口语问「这个模板在平台上叫什么？」（不能含 `/` 或 `@`）。信封给 `field` 就把答案写入 `package.json.name`；给 `flag: --name` 时现有 name 是 npm 包名，不要覆盖，把答案变成旗标后重跑。不要擅自填。
+- 发游戏不要擅自加 `--yes`。补齐参数后若信封还有确认项，把名称、版本、正式/试玩等摘要念给用户，**等人点头**再带 `--yes` 重跑。拒绝则停止。
+
+## 发布前请确认
+
+- **发模板或开源工程**：上传的是源码，**不含** `node_modules`。别人从平台拿到工程后，必须能按 `package.json` 把依赖装上。依赖须是公开可装的包、版本号真实存在（不要写只有你电脑上才有的包、未发布的私有包、或装不到的版本）。装不上就先改依赖再发。
+- **发模板、游戏或开源工程**：运行时**不能用在线资源**（CDN 图片、远程字体、外链脚本/样式、热链网上的音视频等）。图、音、字体、文案、数据都用工程里的本地文件：模板和开源工程放在 `assets/` 或源码内；游戏须打进 `dist/`。发现外链，先改成本地再发。
+
+## 按业务选命令
+
+从模板开工程（用户还没有目录）：
+
+用户没说工程放哪时，**不要自己编文件夹名**。省略目录参数，让 create 退出 11，用口语问「工程要建在哪个文件夹？」。用户回答后再把名字写进命令重跑。未指定 `--skill-platform` 时 CLI 会探测当前编辑器并询问（信封会标明「当前」），**不要擅自写成 cursor**。仅 `npx @66rpg/cgmaker-create`、还没装 kit 时，以该包 `skill/cgmaker-create/SKILL.md` 为准。
+
+```bash
+npx @66rpg/cgmaker-create@latest <用户名/slug>
+npx @66rpg/cgmaker-create@latest <用户名/slug> <用户说的目录>
+npx @66rpg/cgmaker-create@latest <用户名/slug@版本> --with-assets <数据包ID>
+```
+
+缺目录或 skill 时 create 退出 11。未登录（12）时脚手架会留在用户说的目录里，**不要换文件夹、不要删目录**。先 `login` 后用同一目录重跑原 create 命令即可续 init。网页命令没有 `--with-assets` 就不要补素材包。补装同样先让 CLI 探测再问，不要擅自加 `--platform cursor`：
+
+```bash
+npx cgmaker skill
+npx cgmaker skill --all
+```
+
+发正式游戏：
+
+```bash
+npx cgmaker login
+npx cgmaker whoami
+npx cgmaker validate-template
+npm run build
+npx cgmaker publish
+npx cgmaker publish --yes
+```
+
+缺名称/版本等会先退出 11。补齐后再出现确认时，把摘要念给用户，同意后加 `--yes` 重跑。**不要**自己加 `--yes`。
+
+发试玩（独立游戏；可无正式版首发，后补正式版会自动挂接）：
+
+```bash
+npm run build:demo
+npx cgmaker publish --demo
+```
+
+发模板：
+
+```bash
+npx cgmaker validate-template
+npm run build
+npx cgmaker publish-template
+npx cgmaker publish-template --with-assets
+npx cgmaker publish-template --data-summary "关卡包"
+npx cgmaker publish-template-data
+```
+
+无 origin 时 `publish-template` **默认首发**，**第一版不能绑数据包**（不要加 `--with-assets`）。不要擅自加 `--init`。派生用 `--fork <version_id>`。`package.json` 必须有 `scripts.validate`、`scripts.dev:demo`、`scripts.build:demo`、`version`、`data_ver`。素材包说明可用 `--data-summary` 或 `package.json.data_summary`。素材目录固定为工程 `assets/`。有独立试玩数据时 `validate` 必须同时检查正式和试玩两份，不要 `validate:demo`。无独立 demo 时 `dev:demo` 可与 `dev` 相同、`build:demo` 可与 `build` 相同。**平台展示名**优先合法 `package.json.name`，不能含 `/` 或 `@`；不要用 `slug` 顶上。现有 name 含 `/` `@` 时不要覆盖，按信封 `flag: --name` 重跑。`package.json.version` 须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝。续发默认不带数据包；该 `data_ver` 尚无包且本地有 `assets/` 则自动上传。再带包用 `--with-assets`。只改 `assets/`、不发新代码版本：`publish-template-data`。`--fork` 要带本地包加 `--with-assets`。发版不要加 `--changelog`，更新说明请用户去网页改。参数说明见 `cgmaker-identity`。
+
+发开源工程：
+
+```bash
+npx cgmaker publish-project
+```
+
+改帖子（改名、简介、上下架、更新说明）请用户到网页操作，不要用命令行改帖或列列表。试玩范围、预计时长只在第一次发布时按信封补齐；续发不要传。
+
+`.cgmaker/` 要进 git。登录凭据在本机，不要提交。

package/skill/cgmaker-identity/SKILL.md

@@ -1,45 +1,44 @@
----
-name: cgmaker-identity
-description: 模板与游戏的参数与标识配置指南。帮助用户理解 slug、模板ID、素材版本号 data_ver、素材包ID data_id 等参数含义，以及不同发布场景下的功能参数搭配。
----
-
-# 模板与游戏配置参数指南
-
-本文档面向真实用户（模板作者与游戏创作者），详细说明在开发、发布模板与游戏时涉及的各类**配置字段**与**命令行参数**。
-
-具体操作命令的使用方式请参考 `cgmaker` 说明。工程目录结构是否合规请参考 `cgmaker-template-spec`。游戏内调宿主登录 / 查用户 / 跳转 / 全屏，请参考 `cgmaker-play-sdk`（SDK 由发布时注入，你不用管文件）。
-
-## 核心原则
-
-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` 与平台模板名 `name`（或发版时 `--name`，不能含 `/` `@`），执行 `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 <版本号>`。真正上传前会列出名称、版本、正式/试玩等，确认后才发布；脚本加 `--yes`。
-  - 试玩版：执行 `publish --demo --version <版本号>`，平台将自动维护正式版与试玩版的关联关系。
-
-## 注意事项
-
-- 请勿在命令中编造或随意伪造任何平台 ID。
-- 开工程网页命令默认用 `用户名/模板名`（可 `@版本`）；查询/发布等其它命令仍用平台分配的 id。
-- 模板工程一旦发布，禁止更改 `package.json` 中的 `slug`（工具会拒绝）。平台模板名 `name` 可以改；**首发必须由用户给出**（`--name` 或 `package.json.name`），不能含 `/` 或 `@`，不要用 `slug` 顶上。
-- 模板 `--version` / `package.json.version`（接口 `version_name`）须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝发布。游戏 / 开源工程 / `--data-ver` 不套此规则。细则见 [references/fields.md](references/fields.md)。
-- 素材版本号（`--data-ver`）不会由平台自动加 1，每次更新素材时请根据规划显式指定。
-- **发模板或开源工程前**：上传的是源码、不含 `node_modules`。请确认 `package.json` 里的依赖都能在常规 npm 源装到，版本号真实可用；不要写只有本机才有的包或装不到的版本。
-- **发模板、游戏或开源工程前**：运行时请只用本地资源（图、音、字体、文案、数据放在工程内；游戏打进 `dist/`），不要用 CDN 或其它在线地址。
+---
+name: cgmaker-identity
+description: 模板与游戏的参数与标识配置指南。帮助用户理解 slug、模板ID、素材版本号 data_ver、素材包ID 等参数含义，以及不同发布场景下的功能参数搭配。
+---
+
+# 模板与游戏配置参数指南
+
+本文档面向模板作者与游戏创作者，说明开发、发布时涉及的**配置字段**与**命令行参数**。
+
+具体操作命令请参考 `cgmaker` 说明。工程目录结构是否合规请参考 `cgmaker-template-spec`。游戏内调宿主登录 / 查用户 / 跳转 / 全屏，请参考 `cgmaker-play-sdk`（SDK 由发布时注入，你不用管文件）。
+
+## 核心原则
+
+1. **自定义配置项写在 `package.json`**：模板英文简称（`slug`）、代码版本号（`version`）、素材版本号（`data_ver`），由作者改文件，**不要**在命令里传版本号或素材路径。素材目录固定为工程 `assets/`。素材包说明可用 `--data-summary`，也可写 `package.json.data_summary`。平台展示名写在 `package.json.name`；若现有 name 已经带 `/` `@`，不要覆盖。更新说明去网页改。
+2. **平台标识由系统分配**：模板 ID、素材包 ID、游戏 ID 等，均由平台在创建成功后自动生成，不要人工编造。
+3. **参数按需选用**：不同发布场景对应不同组合，例如不上传素材时不必加 `--with-assets`。
+
+各参数与字段的详细定义，见 [references/fields.md](references/fields.md)。
+
+## 常见业务场景与参数选用快速指引
+
+详细的业务分支，见 [references/branches.md](references/branches.md)。
+
+- **首次发布新模板**：
+  - 配置 `package.json` 的 `slug`、`version`、`data_ver` 与平台展示名 `name`（不能含 `/` `@`），执行 `publish-template`。**第一版只交代码，不要加 `--with-assets`**。素材说明可写在 `package.json.data_summary`。
+- **更新已有模板**：
+  - 仅更新模板代码：先改 `package.json.version` 再 `publish-template`（默认不带数据包；该 `data_ver` 已有包则不再上传）。
+  - 代码与素材一并更新：改 `version` / `data_ver` / `data_summary` 后 `publish-template --with-assets`。
+  - 仅更新素材：改 `data_ver`（及可选 `data_summary`）后 `publish-template-data`。
+- **基于已有模板派生**：
+  - 使用 `--fork <版本ID>`。要带本地包加 `--with-assets`。换绑已有素材包时按提示选择。
+- **发布游戏正式版与试玩版**：
+  - 正式版：改 `package.json.version` 后执行 `publish`。真正上传前会列出名称、版本、正式/试玩等，确认后才发布。
+  - 试玩版：执行 `publish --demo`。
+
+## 注意事项
+
+- 请勿在命令中编造平台 ID。
+- 开工程网页命令默认用 `用户名/slug`（可 `@版本`），不要用平台展示名 `name`。
+- 模板工程一旦发布，禁止更改 `package.json` 中的 `slug`。平台展示名 `name` 可以改；**首发必须给出合法展示名**，不能含 `/` 或 `@`，不要用 `slug` 顶上。若现有 `package.json.name` 已经带 `/` `@`，不要覆盖该字段。
+- 模板 `package.json.version` 须 1–16 位，仅小写字母、数字、`.`、`-`；须以字母或数字开头和结尾，不能有连续符号。不合法则拒绝发布。游戏 / 开源工程 / `data_ver` 不套此规则。细则见 [references/fields.md](references/fields.md)。
+- 素材版本号（`data_ver`）不会由平台自动加 1，更新素材时请改 `package.json`。
+- **发模板或开源工程前**：上传的是源码、不含 `node_modules`。请确认 `package.json` 里的依赖都能装到，版本号真实可用。
+- **发模板、游戏或开源工程前**：运行时请只用本地资源，不要用 CDN 或其它在线地址。