unity/Docs/Production/TreeInitializationPlan.md

# tree1–tree3 资源初始化计划

2026-11-12。资源初始化已按本计划执行完成：建立普通目录及资源快照，暂不创建 Git 分支、不注册 worktree，也不开始玩法优化或同时启动三个编辑器。实际结果见 [初始化验收](../QA/Workspaces/Initialization.md)。

## 位置与基线

三个目标按当前项目根目录下规划：

| 名称 | 目标绝对路径 | 初始用途 |
| --- | --- | --- |
| tree1 | `D:/vibeCoding/unityRouge/tree1` | 完整资源基线，具体任务后续分配。 |
| tree2 | `D:/vibeCoding/unityRouge/tree2` | 完整资源基线，具体任务后续分配。 |
| tree3 | `D:/vibeCoding/unityRouge/tree3` | 完整资源基线，具体任务后续分配。 |

执行前核查确认三个目录均不存在。参考基线为 `main` 的 `92623a1bc8678319819e3300eddf1ccff41a55e9`，Unity 版本为 `6000.6.8f1`。执行开始时冻结并记录一次基线提交，三份快照均从该提交导出，不分别读取可能变化的工作区文件。若执行时 HEAD 已更新，先将实际采用的提交写入初始化记录。

当前基线共 256 个已提交文件，包含源码、资源、制作源文件、工具、文档和验收证据。三份采用独立文件副本，预计合计约 126 MiB，尚不包含以后 Unity 导入生成的缓存。

## 每个目录的内容

```text
tree1/                         # tree2、tree3 同样结构
  Assets/                      # 场景、脚本、配置、模型、字体及全部 .meta
  Packages/                    # manifest 与锁定文件
  ProjectSettings/             # 当前引擎、输入、渲染和构建配置
  SourceAssets/                # Blender 源文件、字体原件与许可
  Tools/                       # Unity、Blender、本地化工具
  Docs/                        # 设计、规范、许可及已提交验收证据
  README.md                    # 基线的工程说明
  .editorconfig
  .gitattributes
  .gitignore
  .vsconfig
  WORKSPACE.md                 # 当前目录用途、阶段及使用边界
  WorkspaceInfo.json           # tree 名称、来源提交、目标路径及状态
  InitializationManifest.json  # 文件大小、SHA-256、路径适配记录
```

Unity 资产及 `.meta` 原样成对复制，不重新生成 GUID。原始字体、Blender 源文件与许可完整保留，沿用 [文件规范](ProjectConventions.md) 与 [素材台账](AssetSources.md)。不使用硬链接、目录联接或符号链接共享可修改的 Assets、ProjectSettings 或 SourceAssets。

不复制主仓库的 `.git`、Library、Temp、Obj、Logs、UserSettings、Builds、IDE 缓存和生成的工程文件。已提交到 Docs 的验收摘要与截图属于基线文档，随快照保留。现有 Windows 成品继续位于主工程的 Builds，不为这三个资源目录重新构建。

在主仓库 `.gitignore` 中增加 `/tree1/`、`/tree2/`、`/tree3/`，避免后续普通提交把三份资源重复加入主仓库。三个目录此时没有独立 Git 历史；在其内部运行 Git 仍可能识别到父仓库，不能将其视为已经建立的 worktree。

## 初始化时处理的路径

已发现以下四份工具文件含主工程的绝对路径。每份副本仅将对应根路径替换为本 tree 的完整路径，记录适配前后哈希；主工程工具保持原样。

| 文件 | 适配内容 |
| --- | --- |
| `Tools/Unity/Commands/Build.json` | Windows 原型输出进入本 tree 的 Builds。 |
| `Tools/Unity/Commands/LocalizationBuild.json` | 多语言构建输出进入本 tree 的 Builds。 |
| `Tools/Unity/Commands/Restart.json` | 重开工程的目标指向本 tree。 |
| `Tools/Blender/CreatePrototypeMech.py` | Blender 保存和模型导出根目录指向本 tree。 |

适配采用 JSON 解析或明确的源码常量替换，随后检查解析结果及预期差异。许可、历史验收记录和来源元数据里的原始路径属于记录内容，保持原样。初始化不执行这些工具。

`WorkspaceInfo.json` 记录预期 Unity 工程路径，MCP 实例 ID 保持空值，状态为 `resources-only / not-connected`。Python 服务安装与已有 Unity MCP 包版本可以复用，此阶段不复制全局 Python 环境，不修改现有 MCP 连接。

## 执行顺序

| 编号 | 工作 | 完成条件 |
| --- | --- | --- |
| T0 | 核对主仓库、基线提交、目标路径和剩余空间。 | 三个目标在预定根目录内，没有覆盖风险；记录采用的提交。 |
| T1 | 配置主仓库的三个忽略目录，建立初始化工具与临时区。 | 工具放在 `Tools/Workspaces/`，临时区放在已忽略的 `Logs/WorkspaceInitialization/`。 |
| T2 | 从冻结提交导出资源，在临时区分别生成三份独立副本。 | 已提交内容完整；没有 `.git`、Unity 缓存、构建包或共享链接。 |
| T3 | 适配四份工具路径，生成工作区说明、元数据与 SHA-256 清单。 | 每个副本的输出和重开目标均属于本 tree，原始资源内容保持。 |
| T4 | 校验文件、资产引用基础条件和目录隔离。 | 下方静态验收全部通过。 |
| T5 | 将通过校验的临时目录移到 tree1、tree2、tree3。 | 再次核对源和目标绝对路径；目标不存在才发布，不覆盖已有文件。 |
| T6 | 写入初始化验收与主仓库状态记录。 | 结果进入 `Docs/QA/Workspaces/Initialization.md`；分支列表、worktree 列表与主工程 Assets 不变。 |

若同名目录已经存在，先检查其初始化清单。同一基线且内容完整时可以跳过；存在未知内容或差异时保留现场，不自动覆盖。重新初始化不使用删除整个工作区的方式。

## 静态验收

1. 三份目录的基线提交和复制清单一致；除说明、元数据及四份路径适配外，所有文件与源提交的 SHA-256 一致。
2. Assets 下每个资产与目录均有对应 `.meta`，GUID 与基线一致；场景、预制体、字体配置及本地化表均存在。
3. 包清单、锁定文件、Unity 版本、自制 Blender 源文件、原始字体和许可齐全。
4. 四份工具的写入目标全部在自己的 tree 根目录内，不残留指向主工程的活动输出路径；历史文档中的路径单独列为来源记录。
5. 目录之间没有共享可写链接；没有复制缓存、构建产物或 `.git`。
6. 主仓库的 `git status` 不列出 tree 内资源；分支和 worktree 注册数量保持不变。
7. 记录实际大小、文件数量、适配项与静态检查结果。此阶段不把文件复制成功记录为 Unity 编译、播放或构建通过。

## 启动并行开发前的后续工作

- 各 tree 首次打开 Unity 时独立解析 UPM 包、导入资源和生成缓存，再通过 Unity MCP检查场景、编译与中文字体。资源初始化不预先复制主工程 Library。
- 每个 Unity 编辑器通过准确的 `Name@hash` 与完整工程路径绑定自己的 MCP 会话，实际发现实例后才填入连接信息。
- 当前游戏读取 `Application.persistentDataPath`，语言偏好使用 PlayerPrefs；复制工程会保留相同的 companyName / productName。在并行运行前，通过各自 Unity MCP 配置独立的测试存档及偏好命名空间，避免互相修改主工程测试数据。
- 需要分支时，先明确各目录的任务与修改归属，再在新的空目标目录建立真实 Git worktree。已有资源目录若产生变更，按初始化清单保存和迁移差异，经验证后再切换用途，不直接覆盖现有目录。

## 本次执行结果

T0–T6 已完成，三份均采用上述 `92623a1` 基线。每份共 259 个文件、约 41.96 MiB，其中 252 个基线文件原样保留、4 个工具文件完成路径适配，另附 3 个初始化说明与清单文件。85 个 Unity GUID 及每种语言 134 个文本键检查通过。三份总计约 125.88 MiB。

初始化工具为 `Tools/Workspaces/InitializeTrees.py`，可核验同基线的已有目录并跳过复制，遇到未知内容时拒绝覆盖。逐文件 SHA-256 位于各 tree 的 `InitializationManifest.json`，总结果见 [Initialization.json](../QA/Workspaces/Initialization.json)。本轮未创建分支或 worktree，未运行导入、编译、播放或构建。