MetaCore/docs/designs/metacore-m1-m2-detailed-task-breakdown.md

# MetaCore M1-M2 详细任务分解

生成时间：2026-03-28  
状态：草案  
范围：M1 引擎壳与项目循环，M2 资源与模型导入循环

## 目的

这份文档把当前最应该推进的两个里程碑拆成真正可执行的任务单。

它不是概念清单，而是用于直接指导后续开发排序、拆工和验收的。

当前原则：

- 先把引擎基础工作流做扎实
- 不再让 RuntimeData 继续主导第一阶段节奏
- 所有任务都要服务于“像 Unity / UE 一样完成工业项目开发”的最小生产力闭环

## 当前代码基础判断

结合现有仓库，MetaCore 已经具备一些可以复用的基础：

- 项目描述文件读取基础
- 资源数据库与 package 基础能力
- 场景保存/加载二进制方向
- 基础层级编辑能力
- 基础 Inspector
- 基础 prefab 能力
- 独立 Player

但当前真正缺的是：

- 把项目系统做成稳定入口
- 把导入流程做成真正可用的资源工作流
- 把模型导入从“识别格式”推进到“可用于场景”
- 把 Project 面板、资源引用、重新导入和 package 行为串成闭环

所以 M1-M2 的目标不是“继续补零散能力”，而是把这条主链打通：

```text
打开项目
  -> 浏览资源
    -> 导入模型
      -> 模型变成可引用资产
        -> 放入场景
          -> 保存并重开仍然有效
```

## M1：引擎壳与项目循环

### M1 目标

把 MetaCore 做成一个稳定的“项目入口”，而不只是一个能打开窗口的编辑器。

### M1 完成标准

- 能稳定定位和打开项目
- 项目描述文件能被一致读取和保存
- 启动场景机制稳定
- Editor 和 Player 都能围绕项目根目录工作
- 新老路径兼容行为清晰，不再依赖临时 fallback 才能运行

---

## M1 工作包

### M1-A 项目定位与启动逻辑统一

#### 目标

统一 Editor、Player、工具对项目根目录的解析逻辑。

#### 现状

当前代码里已经存在多处项目路径解析和 fallback 逻辑，但它们分散在不同入口。

#### 任务

- 抽出统一的项目路径解析帮助层
- 统一 `MetaCore.project.json` 定位逻辑
- 统一 startup scene 解析逻辑
- 统一 Runtime 目录定位逻辑
- 明确命令行传项目路径与默认样板项目路径的优先级

#### 交付物

- 一个公共项目路径解析入口
- Editor/Player/工具共用同一套项目根解析规则

#### 验收

- 从不同当前工作目录启动时仍能打开同一个项目
- 样板项目不依赖“碰巧的相对路径”才能运行

### M1-B 项目描述文件能力补齐

#### 目标

把 `MetaCore.project.json` 做成真正的项目描述文件，而不是只存一个 startup scene。

#### 建议字段

当前至少明确以下字段：

- `name`
- `version`
- `startup_scene`
- `scenes`
- `runtime_config` 或转向固定 runtime 目录策略
- 未来可预留 `asset_roots`、`ui_roots`

#### 任务

- 梳理项目描述文件的最小字段集
- 统一读写逻辑
- 明确旧字段兼容策略
- 对非法项目描述给出明确错误

#### 验收

- 坏项目文件能报错
- 缺字段时行为一致
- 保存后再次打开结果一致

### M1-C 启动场景工作流稳定化

#### 目标

确保项目和启动场景关系稳定。

#### 任务

- 明确 startup scene 的设置入口
- 明确 startup scene 保存后项目描述同步规则
- 明确启动场景缺失时的行为
- Player 和 Editor 对 startup scene 的解释保持一致

#### 验收

- 设置 startup scene 后，Editor/Player 行为一致
- 场景改名或移动后，引用更新策略清晰

### M1-D 样板项目 bootstrap 规则

#### 目标

样板项目成为可持续维护的基线项目，而不是演示残留物。

#### 任务

- 固定样板项目目录结构
- 固定 `Scenes / Assets / Runtime / Library` 的职责
- 明确自动生成内容与手工维护内容边界
- 把当前样板工程转成规范项目

#### 验收

- 新人能直接理解样板项目结构
- 工具生成文件不会污染错误目录

### M1-E 项目级测试

#### 目标

给项目循环加回归保护。

#### 必测项

- 项目描述读取
- startup scene 读取
- startup scene 缺失处理
- 项目根目录解析
- Player 项目启动链

---

## M2：资源与模型导入循环

### M2 目标

把 MetaCore 变成一个真正围绕资源工作的工具，而不是只围绕内建对象工作的编辑器。

### M2 完成标准

- 导入的资源进入 Asset Database
- 模型资源成为可追踪资产
- Project 面板能看见并定位这些资源
- 导入资源能被放进场景并在保存后重开
- 重新导入和元数据行为稳定

---

## M2 工作包

### M2-A 导入器策略收敛

#### 目标

明确第一阶段首批导入策略，不再模糊支持。

#### 建议首批格式

- P0：`glTF/.glb`
- P1：`FBX`
- P2：`OBJ`

#### 理由

- `glTF/.glb` 更适合作为第一生产级导入格式
- `FBX` 很重要，但复杂度高，不应该先把整条链卡死在 FBX 上
- `OBJ` 可作为简化补充，不应该主导设计

#### 任务

- 明确导入器接口的能力边界
- 区分“识别格式”和“完整导入能力”
- 明确哪些格式只是注册，哪些格式是真生产支持

#### 验收

- 文档和代码里对格式支持口径一致

### M2-B 模型资源数据模型

#### 目标

给模型资源一个稳定的数据表示，不要只把原始文件名记进数据库。

#### 最低要求

- 资源 GUID
- 资源类型
- 原始源文件路径
- package 路径
- 导入器 id
- 源文件 hash
- 模型节点层级信息的承载位置

#### 任务

- 明确“模型资产”和“导入源文件”的关系
- 明确 package 里到底存什么
- 明确导入后场景引用的是什么对象

#### 验收

- 一个模型导入后有明确资产身份
- 场景引用模型时不依赖源文件路径硬绑

### M2-C 模型导入最小闭环

#### 目标

把至少一种格式做成真的可用，而不是仅识别扩展名。

#### 推荐第一闭环

优先 `glTF/.glb`

#### 闭环要求

- 选择模型文件导入
- 生成资产记录
- 生成 package
- Project 面板里可见
- 放进场景后可渲染
- 保存场景后重开仍然存在

#### 验收

- 至少一个 `glTF/.glb` 样例能完整跑通上述闭环

### M2-D 层级保留与归一化

#### 目标

导入模型时不要只保一个“单网格结果”，要为数字孪生常见设备结构保留层级。

#### 任务

- 保留模型节点层级
- 明确坐标系转换
- 明确缩放归一化
- 明确材质槽映射
- 明确空节点是否保留

#### 验收

- 导入后层级结构与源模型基本一致
- 不会出现方向、缩放完全错误的基础问题

### M2-E 重新导入策略

#### 目标

资源改动后可刷新，而不是删了重来。

#### 任务

- 基于源 hash 检测变化
- 明确重新导入触发方式
- 明确重新导入后 package 更新规则
- 明确重新导入对场景引用的影响

#### 验收

- 修改源模型后可稳定刷新
- 场景里的引用不被无故打断

### M2-F Project 面板与资源浏览增强

#### 目标

让资源工作流真正可用。

#### 必须支持

- 浏览项目资源
- 区分 source / meta / package
- 定位资源
- 显示资源类型
- 打开场景资产
- 未来可扩展到双击实例化模型

#### 任务

- 补齐资源显示信息
- 强化 scene / prefab / asset 的区分
- 明确从资源到场景的最小放置流程

#### 验收

- 用户能在 Project 面板里明确找到导入的模型资产

### M2-G 导入错误与诊断

#### 目标

导入失败要可定位。

#### 必须可见的错误类型

- 文件不存在
- 格式不支持
- package 写入失败
- 元数据损坏
- 重新导入失败

#### 验收

- 失败不会静默
- Console 有明确错误类别和信息

### M2-H M2 测试矩阵

#### 目标

给资源与导入闭环加回归保护。

#### 必测项

- 项目导入一个模型
- 生成 metadata
- 生成 package
- Asset Database 记录稳定
- Project 面板可见
- 场景引用导入资源
- 保存并重开仍然有效
- 重新导入不打断引用

---

## 推荐开发顺序

M1-M2 的推荐顺序如下：

```text
M1-A 项目定位与启动逻辑统一
  -> M1-B 项目描述文件能力补齐
    -> M1-C 启动场景工作流稳定化
      -> M1-D 样板项目 bootstrap 规则
        -> M1-E 项目级测试
          -> M2-A 导入器策略收敛
            -> M2-B 模型资源数据模型
              -> M2-C 模型导入最小闭环
                -> M2-D 层级保留与归一化
                  -> M2-F Project 面板与资源浏览增强
                    -> M2-E 重新导入策略
                      -> M2-G 导入错误与诊断
                        -> M2-H M2 测试矩阵
```

## 当前代码库下的优先实现建议

基于现有仓库状态，我建议最先动这几条：

### 第一批

- 项目路径与项目描述统一
- startup scene 行为统一
- 导入器支持口径收敛
- `glTF/.glb` 作为第一优先格式定下来

### 第二批

- 模型资产数据结构
- 最小模型导入闭环
- Project 面板识别模型资产

### 第三批

- 重新导入
- 导入错误诊断
- 资源引用稳定性

## Definition of Done

M1-M2 完成时，MetaCore 至少要做到：

- 能稳定打开项目
- 能稳定打开 startup scene
- 能导入第一种正式支持的模型格式
- 能在 Project 面板里看到模型资产
- 能把模型资产放进场景
- 场景保存、重开后模型仍然有效
- 打包链路不会因为导入资产而断掉

这才说明 MetaCore 开始真正具备“像 Unity/UE 一样开发项目”的最小引擎基础能力。