From b37c7c5424232cf2d8b93ea06ea4a0a045382f7e Mon Sep 17 00:00:00 2001
From: Joywayer <joywayer@163.com>
Date: Sun, 28 Jun 2026 12:22:19 +0800
Subject: [PATCH] =?UTF-8?q?docs(tools):=20=E5=B7=A5=E5=85=B7=E9=93=BE=20RE?=
 =?UTF-8?q?ADME=20+=20=E7=AB=AF=E5=88=B0=E7=AB=AF=E5=86=92=E7=83=9F?=
 =?UTF-8?q?=E9=80=9A=E8=BF=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

全量 22 单测通过；e2e 冒烟 new-game→check-cocos→setup-links 全绿。
README 含命令表、关键约束，并补充 junction 删除安全注意事项
（避免 rm -rf 穿透 junction 误删框架真源）。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 cocoscreator_projects/scripts/README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 cocoscreator_projects/scripts/README.md

diff --git a/cocoscreator_projects/scripts/README.md b/cocoscreator_projects/scripts/README.md
new file mode 100644
index 0000000..fce472f
--- /dev/null
+++ b/cocoscreator_projects/scripts/README.md
@@ -0,0 +1,24 @@
+# Monorepo 工具链
+
+所有命令在 `cocoscreator_projects/` 下用 `npm run <script>` 执行。
+
+| 命令 | 作用 |
+|------|------|
+| `npm run new-game <name>` | 从 `templates/game-seed` 克隆一个子游戏工程到 `games/<name>`，重置身份、铺 `game/` 骨架、挂 framework junction |
+| `npm run setup-links` | 为 `games/*` 重建 `assets/framework` junction（clone 仓库后必跑一次） |
+| `npm run check-cocos` | 校验所有子游戏工程的 `creator.version` 与宿主 `YouleNexus` 一致（不一致退出码 1） |
+| `npm run bump-cocos <version>` | 批量改宿主+所有子游戏的 `creator.version`（之后仍需逐个用编辑器打开迁移） |
+| `npm test` | 运行工具链全部单元测试 |
+
+## 关键约束
+- **framework 真源**唯一存放于 `YouleNexus/assets/framework`；各子游戏的 `assets/framework` 是指向它的 junction（不入库，见根 `.gitignore`）。clone 后跑 `setup-links` 重建。
+- **Cocos 版本必须全 monorepo 统一**（junction 共享同一份资源，跨版本不兼容）。升级走 `bump-cocos` + 逐工程编辑器迁移，详见 spec §8。
+- 子游戏私有内容只放 `games/<name>/assets/game/`；协议一律引用 `docs/protocol/`（spec §0.1）。
+
+## ⚠️ 删除子游戏工程的注意事项
+子游戏的 `assets/framework` 是指向框架真源的 junction。**不要用 `rm -rf` 删除整个子游戏工程**——git-bash 的 `rm -rf` 可能穿透 junction 误删框架真源。请用 Node 安全删除（对 junction 不穿透）：
+
+```bash
+node -e "require('fs').rmSync('games/<name>', { recursive: true, force: true })"
+```
+或先单独移除 junction（`rmdir games/<name>/assets/framework`）再删工程目录。