# MetaCore M1 Backlog 生成时间：2026-04-04 状态：草案 范围：M1 项目与资源主干 读者：架构、引擎、编辑器、工具链、测试 ## 目的 这份文档把 M1 从“里程碑目标”进一步下钻为“可以直接开卡的 backlog”。 每个 backlog 项都尽量包含： - 背景 - 目标 - 交付结果 - 依赖 - 建议 owner - 验收标准 建议后续直接按本文件拆 issue 或任务卡。 ## M1 成功定义 M1 完成时，MetaCore 至少应满足： - 用户可以创建并打开项目 - Editor / Player / Tool 能按统一规则定位项目 - 项目描述文件读写稳定 - Project 面板能显示项目资源 - 资源进入项目后能进入 Asset Database - meta / GUID / package 基础记录稳定生成 --- ## M1-01 统一项目根目录解析 ### 背景 当前项目路径解析逻辑分散在 Editor、Player 和局部工具中，存在 fallback 和相对路径依赖。 ### 目标 抽出统一的项目根解析入口，统一所有入口程序的项目定位行为。 ### 交付结果 - 公共项目解析帮助层 - Editor / Player / Tool 共用同一套解析规则 - 项目路径优先级规则文档化 ### 依赖 - 无 ### 建议 owner - 引擎核心 ### 验收标准 - 从不同工作目录启动，能解析到同一项目 - 命令行传入项目路径时优先级明确且行为一致 - 不再依赖临时相对路径 fallback 才能正常运行 --- ## M1-02 统一项目描述文件模型 ### 背景 `MetaCore.project.json` 已存在，但字段语义和读写责任边界还不够收敛。 ### 目标 定义项目描述文件的正式最小字段集合，并统一读写入口。 ### 交付结果 - 项目描述数据结构 - 统一读写实现 - 最小字段清单 - 字段缺失和错误格式处理规则 ### 依赖 - `M1-01` ### 建议 owner - 引擎核心 ### 验收标准 - 保存后重新打开结果一致 - 缺字段时行为可预测 - 损坏文件时有明确报错 --- ## M1-03 项目创建流程 ### 背景 当前更偏已有样板项目驱动，还没有形成明确的正式项目创建流程。 ### 目标 建立最小项目创建能力，让 MetaCore 的项目不是手工拼目录生成。 ### 交付结果 - 新建项目入口 - 标准目录结构创建 - 默认 `MetaCore.project.json` - 默认场景和必要目录初始化 ### 依赖 - `M1-02` ### 建议 owner - 编辑器与工作流 - 工具链配合 ### 验收标准 - 用户可创建一个新项目并立即打开 - 项目创建后目录结构符合规范 - 默认项目可在 Editor 中正常启动 --- ## M1-04 项目打开流程 ### 背景 打开项目目前更多是隐式解析，而不是明确工作流。 ### 目标 建立正式的项目打开流程，包括错误处理和 UI 反馈。 ### 交付结果 - 打开项目入口 - 项目有效性校验 - 项目切换行为 - 打开失败时的提示 ### 依赖 - `M1-01` - `M1-02` ### 建议 owner - 编辑器与工作流 ### 验收标准 - 用户能选择并打开现有项目 - 非法项目目录会被拒绝并提示原因 - 切换项目后编辑器状态可恢复到一致状态 --- ## M1-05 startup scene 规则统一 ### 背景 startup scene 现在已经存在，但 Editor 和 Player 的解释路径应进一步统一。 ### 目标 统一 startup scene 的定位、读取、设置和异常处理规则。 ### 交付结果 - startup scene 读取规则 - startup scene 设置规则 - 缺失/损坏场景的降级规则 ### 依赖 - `M1-02` ### 建议 owner - 引擎核心 ### 验收标准 - Editor / Player 对同一项目的 startup scene 行为一致 - startup scene 缺失时有明确日志和降级路径 - 修改 startup scene 后项目描述同步正确 --- ## M1-06 Asset Database 初始化主干 ### 背景 资源系统已有基础，但还需要收敛成明确的初始化和扫描主干。 ### 目标 建立项目打开后的 Asset Database 初始化主流程。 ### 交付结果 - 项目扫描入口 - 资源记录加载/生成流程 - 初始化后的统一查询状态 ### 依赖 - `M1-01` - `M1-02` ### 建议 owner - 引擎核心 - 工具链配合 ### 验收标准 - 打开项目后资源数据库处于稳定可查询状态 - 已存在资源能被识别和记录 - 多次打开同一项目结果一致 --- ## M1-07 meta / GUID / package 记录统一 ### 背景 meta、GUID、package 已经出现，但还需要更严格的一致性规则。 ### 目标 统一资源身份与持久化元数据的最小规则。 ### 交付结果 - GUID 生成和持久化规则 - `.mcmeta` 的最小结构 - package 记录与资源记录的对应关系 ### 依赖 - `M1-06` ### 建议 owner - 引擎核心 - 工具链 ### 验收标准 - 同一资源重复打开项目后 GUID 稳定 - meta 缺失或损坏时有明确行为 - package 与资源记录关系可追踪 --- ## M1-08 资源导入基础入口 ### 背景 资源进入项目的路径要统一，不应该由测试或脚本间接驱动。 ### 目标 建立基础资源导入入口，让文件进入项目后被正式纳管。 ### 交付结果 - 导入入口 - 导入后生成 meta / package / 资源记录 - 导入结果反馈到 Project 面板和 Console ### 依赖 - `M1-06` - `M1-07` ### 建议 owner - 工具链与构建发布 - 编辑器与工作流配合 ### 验收标准 - 导入一个资源后，Asset Database 和 Project 面板都能看到它 - 导入失败不会静默 - 导入后必要元数据生成完整 --- ## M1-09 Project 面板第一版 ### 背景 资源系统没有稳定可见入口时，整个内容工作流都会不顺。 ### 目标 做出可用的 Project 面板第一版。 ### 交付结果 - 目录树 - 资源列表 - 资源类型显示 - 与 Inspector 联动 ### 依赖 - `M1-06` - `M1-08` ### 建议 owner - 编辑器与工作流 ### 验收标准 - 用户能在 Project 面板中看到项目资源结构 - 新导入资源能立刻被定位 - 资源选择能联动详情面板或 Inspector --- ## M1-10 资源刷新、重命名、移动基础规则 ### 背景 如果资源移动、重命名、刷新规则不清晰，后续导入链会很脆。 ### 目标 明确资源刷新、重命名、移动的最小规则和失败面。 ### 交付结果 - 刷新策略 - 重命名策略 - 移动策略 - 基础引用保持规则 ### 依赖 - `M1-06` - `M1-07` - `M1-08` ### 建议 owner - 引擎核心 - 工具链 - 编辑器配合 ### 验收标准 - 刷新后资源视图与数据库一致 - 重命名/移动后资源仍能被识别 - 基础引用不会被无故打断 --- ## M1-11 样板项目规范化 ### 背景 样板项目目前兼有演示和验证角色，需要变成规范基线。 ### 目标 把样板项目收敛成正式基线项目结构。 ### 交付结果 - 样板项目目录职责说明 - 自动生成内容与手工内容边界 - 样板项目可作为持续回归输入 ### 依赖 - `M1-03` - `M1-05` - `M1-06` ### 建议 owner - 工具链与构建发布 - 测试与验收配合 ### 验收标准 - 新人可以直接理解样板项目结构 - 样板项目能稳定被 Editor 和 Player 打开 - 生成内容不会污染不该写入的目录 --- ## M1-12 M1 回归测试矩阵 ### 背景 没有测试矩阵，M1 很容易在后续 M2/M3 中被回归破坏。 ### 目标 给 M1 建立最小但稳定的测试与验收矩阵。 ### 交付结果 - 项目创建/打开测试 - 项目描述文件读写测试 - startup scene 测试 - 项目路径解析测试 - Asset Database 初始化/刷新测试 - 样板项目回归流程 ### 依赖 - `M1-01` 到 `M1-11` ### 建议 owner - 测试与验收 - 各模块 owner 联合 ### 验收标准 - M1 核心链路均有自动化或半自动回归 - 样板项目可作为固定验收输入 - 后续改动可以快速判断是否破坏 M1 主干 --- ## 建议优先级 ### P0 - `M1-01` 统一项目根目录解析 - `M1-02` 统一项目描述文件模型 - `M1-05` startup scene 规则统一 - `M1-06` Asset Database 初始化主干 - `M1-07` meta / GUID / package 记录统一 - `M1-09` Project 面板第一版 ### P1 - `M1-03` 项目创建流程 - `M1-04` 项目打开流程 - `M1-08` 资源导入基础入口 - `M1-10` 资源刷新、重命名、移动基础规则 - `M1-11` 样板项目规范化 ### P2 - `M1-12` M1 回归测试矩阵 说明： - `M1-12` 虽然放在 P2，是因为它依赖前置能力收敛，不代表不重要 - 一旦 P0/P1 功能基本落地，应立即补齐 `M1-12` ## 推荐执行顺序 ```text M1-01 -> M1-02 -> M1-05 -> M1-06 -> M1-07 -> M1-09 -> M1-03 / M1-04 -> M1-08 -> M1-10 -> M1-11 -> M1-12 ``` ## 建议任务卡字段 后续如果转到看板，建议每个任务卡都带上： - `Milestone`: `M1` - `Workstream`: 引擎核心 / 编辑器与工作流 / 工具链与构建发布 / 测试与验收 - `Priority`: `P0/P1/P2` - `Owner` - `Depends On` - `Definition of Done` - `Validation` ## 结论 M1 的本质不是“做几个项目系统相关功能”，而是把这条主链做稳： **项目可以被统一识别，资源可以被统一纳管，编辑器可以稳定把这些内容展示给用户。** 只要这条主链没稳，M2 及以后都会建立在不稳定地基之上。