MetaCore/docs/designs/metacore-m4-backlog.md

MetaCore M4 Backlog

生成时间：2026-04-04
状态：草案
范围：M4 Player、打包、发布闭环
读者：架构、引擎、编辑器、工具链、测试、交付

目的

这份文档把 M4 从“里程碑目标”进一步下钻为“可以直接开卡的 backlog”。

M4 的核心不是“多一个 build 命令”，而是让 MetaCore 走完这条最终闭环：

编辑器里的项目内容 -> 正式构建输入 -> 独立 Player 输出 -> 脱离开发环境运行。

M4 成功定义

M4 完成时，MetaCore 至少应满足：

• 用户可以从正式项目生成独立输出目录
• 输出目录包含运行项目所需的最小内容
• Player 脱离 Editor 与源工程目录可运行
• startup scene、模型、材质、UI 和运行时配置可正确加载
• 打包失败与运行时缺失关键内容时，有明确日志和诊断

---

M4-01 Player 项目加载链统一

背景

Player 已存在，但项目加载逻辑还需要与 Editor 主干完全统一。

目标

统一 Player 对项目根、startup scene、资源和 UI 的解析逻辑。

交付结果

• Player 项目根解析规则
• startup scene 加载规则
• 资源与 UI 路径解析规则
• 与 Editor 行为的一致性约束

依赖

• M1、M2、M3 完成

建议 owner

• 引擎核心

验收标准

• 同一项目在 Editor 和 Player 中加载语义一致
• Player 脱离 Editor 仍能稳定解析项目内容

---

M4-02 构建输出目录规范

背景

如果输出目录不固定，后续交付、诊断和 clean machine 验证都会混乱。

目标

定义正式的输出目录结构和最小运行内容。

交付结果

• 输出目录结构规范
• Player 产物放置规则
• 资源产物放置规则
• 配置产物放置规则

依赖

• M4-01

建议 owner

• 工具链与构建发布

验收标准

• 同类项目打包输出目录结构一致
• 运行所需内容边界清晰

---

M4-03 cook 规则固定化

背景

没有稳定的 cook 规则，打包输出就不能成为可信构建结果。

目标

收敛第一阶段需要的 cook 规则和命名约定。

交付结果

• cook 输入输出规则
• 资源产物命名约定
• 场景、材质、UI、Prefab 的构建处理规则

依赖

• M4-02

建议 owner

• 工具链与构建发布
• 引擎核心配合

验收标准

• 同一输入在相同条件下产生稳定输出
• 关键资源类型都能进入正式构建链

---

M4-04 编辑器打包入口

背景

如果打包只能通过内部脚本或手工命令完成，交付工作流不完整。

目标

提供第一版面向用户的打包入口。

交付结果

• 编辑器内打包入口
• 打包参数入口
• 打包结果反馈
• 打包失败信息反馈

依赖

• M4-02
• M4-03

建议 owner

• 编辑器与工作流
• 工具链与构建发布配合

验收标准

• 用户可以从编辑器发起正式打包
• 成功和失败结果都有明确可见反馈

---

M4-05 独立输出目录生成

背景

M4 的关键不是“构建成功”，而是“得到一个脱离工程目录可运行的独立输出”。

目标

让项目生成独立的 Windows 输出目录。

交付结果

• 输出目录生成逻辑
• Player、资源、配置、UI 的正式摆放
• 最小依赖内容收敛

依赖

• M4-02
• M4-03
• M4-04

建议 owner

• 工具链与构建发布

验收标准

• 输出目录中包含项目运行的最小必需内容
• 脱离源工程目录仍可启动

---

M4-06 发布态资源加载一致性

背景

编辑器里能跑不代表发布态能跑，尤其是路径和资源解析常常不同。

目标

验证并修正 Player 在发布态下对场景、材质、UI 等内容的加载一致性。

交付结果

• startup scene 发布态加载验证
• 模型、材质、UI 发布态加载验证
• 关键路径差异修正

依赖

• M4-05

建议 owner

• 引擎核心
• 渲染与资源表现配合

验收标准

• 发布态运行结果与编辑态期望一致
• 关键内容不会因路径或构建差异丢失

---

M4-07 运行时日志与错误诊断

背景

没有日志与错误面，交付和现场排障成本会很高。

目标

建立 Player 发布态的最小可用日志与诊断体系。

交付结果

• 启动日志
• startup scene 加载错误日志
• 资源缺失日志
• UI / 配置加载错误日志
• 可定位的失败路径

依赖

• M4-01
• M4-05

建议 owner

• 引擎核心
• 工具链与构建发布配合

验收标准

• 缺失关键内容时不会静默失败
• 交付团队能通过日志快速判断问题位置

---

M4-08 发布目录与移交规范

背景

打包完成后还需要明确“什么是交付物”。

目标

定义交付目录结构、最小移交内容和交付说明边界。

交付结果

• 发布目录说明
• 最小移交清单
• 缺失关键文件时的错误说明
• 面向交付团队的目录语义

依赖

• M4-05
• M4-07

建议 owner

• 工具链与构建发布
• 交付配合

验收标准

• 交付团队可以理解并使用输出目录
• 缺失文件时能快速定位责任边界

---

M4-09 clean machine 验证流程

背景

如果产物只能在开发机跑，M4 就没有真正完成。

目标

建立 clean machine 或近似隔离环境验证流程。

交付结果

• clean machine 验证步骤
• 隔离环境下运行检查项
• 常见失败类型清单

依赖

• M4-05
• M4-06
• M4-07

建议 owner

• 测试与验收
• 工具链与构建发布配合

验收标准

• 样板项目可在隔离环境中成功运行
• 不依赖 Editor、源码目录或开发机临时状态

---

M4-10 M4 回归测试矩阵

背景

发布链如果没有回归矩阵，很容易在后续迭代中失效。

目标

建立 M4 的最小稳定验收矩阵。

交付结果

• 打包输出检查测试
• Player 独立运行测试
• 发布态资源加载测试
• clean machine 验证回归
• 样板项目发布回归

依赖

• M4-01 到 M4-09

建议 owner

• 测试与验收
• 各模块 owner 联合

验收标准

• M4 主链均有回归覆盖
• 样板项目可作为固定发布态验收输入

---

建议优先级

P0

• M4-01 Player 项目加载链统一
• M4-02 构建输出目录规范
• M4-03 cook 规则固定化
• M4-05 独立输出目录生成
• M4-06 发布态资源加载一致性
• M4-07 运行时日志与错误诊断
• M4-09 clean machine 验证流程

P1

• M4-04 编辑器打包入口
• M4-08 发布目录与移交规范

P2

• M4-10 M4 回归测试矩阵

说明：

• M4-10 依赖前面链路稳定，不代表不重要
• 一旦发布主链基本成立，应尽快补齐回归矩阵

推荐执行顺序

M4-01
  -> M4-02
    -> M4-03
      -> M4-04
        -> M4-05
          -> M4-06
            -> M4-07
              -> M4-08
                -> M4-09
                  -> M4-10

建议任务卡字段

后续如果转到看板，建议每个任务卡都带上：

• Milestone: M4
• Workstream: 引擎核心 / 编辑器与工作流 / 工具链与构建发布 / 渲染与资源表现 / 测试与验收
• Priority: P0/P1/P2
• Owner
• Depends On
• Definition of Done
• Validation

结论

M4 的本质不是“把构建功能做出来”，而是让 MetaCore 的第一阶段真正拥有交付意义：

项目内容能够脱离开发环境，以独立 Player 的形式被稳定运行和移交。

只要这条链没有成立，前面 M1-M3 的成果就还没有真正进入“可交付引擎”的阶段。