MetaCore/docs/designs/metacore-m1-p0-task-cards.md

MetaCore M1 P0 任务卡清单

生成时间：2026-04-04
状态：草案
范围：M1 P0 执行卡片
读者：项目负责人、架构、引擎、编辑器、工具链、测试

目的

这份文档把 metacore-m1-backlog.md 中的 M1 P0 项，整理成可以直接复制到项目管理工具中的任务卡格式。

使用建议：

• 一张卡对应一个执行 owner
• 每张卡进入开发前先补 owner 和计划时间
• 每张卡进入 Ready for QA 前，先自检 Definition of Done

建议看板状态

• Not Started
• In Design
• In Progress
• Blocked
• Ready for QA
• Accepted

建议字段

• Title
• Milestone
• Priority
• Workstream
• Owner
• Depends On
• Description
• Definition of Done
• Validation

---

卡片 1

Title

M1-01 统一项目根目录解析

Milestone

M1

Priority

P0

Workstream

引擎核心

Depends On

• 无

Description

抽出统一的项目根目录解析入口，统一 Editor、Player、Tool 对项目路径的识别规则，消除当前分散 fallback 和相对路径偶然成功的问题。

Definition of Done

• 存在统一的公共项目解析入口
• Editor / Player / Tool 使用同一套项目根解析规则
• 命令行传项目路径的优先级清晰
• 不再依赖临时相对路径 fallback 才能运行样板项目

Validation

• 从不同当前工作目录启动 Editor 和 Player，解析到同一项目
• 传命令行项目路径和不传路径时，行为符合预期
• 样板项目不依赖“碰巧的路径”运行

---

卡片 2

Title

M1-02 统一项目描述文件模型

Milestone

M1

Priority

P0

Workstream

引擎核心

Depends On

• M1-01

Description

统一 MetaCore.project.json 的正式字段模型、读写入口和错误处理规则，避免项目描述语义继续分散。

Definition of Done

• 项目描述文件有正式最小字段集合
• 有统一的读写实现
• 缺字段和损坏文件的行为明确
• 保存后重新读取结果一致

Validation

• 正常项目文件可稳定读写
• 缺字段项目文件行为一致
• 损坏项目文件时有明确错误

---

卡片 3

Title

M1-05 startup scene 规则统一

Milestone

M1

Priority

P0

Workstream

引擎核心

Depends On

• M1-02

Description

统一 startup scene 在 Editor 和 Player 中的定位、设置、读取和异常处理规则。

Definition of Done

• startup scene 读取规则统一
• startup scene 设置规则统一
• 缺失或损坏时有明确降级行为
• 修改 startup scene 后项目描述同步正确

Validation

• 同一项目在 Editor / Player 中加载同一 startup scene
• startup scene 缺失时有明确日志
• 修改 startup scene 后重开项目结果一致

---

卡片 4

Title

M1-06 Asset Database 初始化主干

Milestone

M1

Priority

P0

Workstream

引擎核心

Depends On

• M1-01
• M1-02

Description

建立项目打开后的 Asset Database 初始化、扫描、记录加载与查询主流程。

Definition of Done

• 打开项目后 Asset Database 稳定初始化
• 已存在资源能被识别
• 资源记录处于稳定可查询状态
• 多次打开同一项目结果一致

Validation

• 打开样板项目后资源记录可查询
• 多次重复打开结果一致
• 初始化失败时有明确错误信息

---

卡片 5

Title

M1-07 meta / GUID / package 记录统一

Milestone

M1

Priority

P0

Workstream

引擎核心 + 工具链与构建发布

Depends On

• M1-06

Description

统一资源身份、GUID、.mcmeta 和 package 的基础规则，让资源进入项目后的元数据可追踪、可复现。

Definition of Done

• GUID 生成和持久化规则明确
• .mcmeta 最小结构明确
• package 与资源记录关系一致
• 同一资源在重复打开项目后 GUID 保持稳定

Validation

• 导入同一资源后再次打开项目，GUID 不变化
• meta 缺失或损坏时行为明确
• 资源记录能追溯到 package 和 meta

---

卡片 6

Title

M1-09 Project 面板第一版

Milestone

M1

Priority

P0

Workstream

编辑器与工作流

Depends On

• M1-06
• M1-07

Description

实现可用的 Project 面板第一版，让用户能够看到项目目录、资源列表和资源类型，并与 Inspector 联动。

Definition of Done

• Project 面板能显示项目目录树
• 能显示资源列表和基础类型信息
• 资源选择与 Inspector 或详情区联动
• 新资源进入项目后能在面板中找到

Validation

• 打开样板项目后可浏览资源结构
• 新资源进入项目后可立即定位
• 切换资源时联动信息正确

---

卡片 7

Title

M1-12 建立 M1 回归测试矩阵

Milestone

M1

Priority

P0-收尾

Workstream

测试与验收

Depends On

• M1-01
• M1-02
• M1-05
• M1-06
• M1-07
• M1-09

Description

建立覆盖 M1 主链的最小回归矩阵，保证后续 M2-M4 不会轻易破坏项目与资源主干。

Definition of Done

• 项目创建/打开或打开现有项目测试存在
• 项目描述文件读写测试存在
• startup scene 测试存在
• Asset Database 初始化/刷新测试存在
• 样板项目回归步骤固定

Validation

• M1 主链有自动化或半自动回归覆盖
• 后续修改后可以快速回归判断是否破坏 M1

---

建议第一批开工顺序

卡片 1 -> 卡片 2 -> 卡片 3 -> 卡片 4 -> 卡片 5 -> 卡片 6 -> 卡片 7

建议并行策略

第一组

• 卡片 1
• 卡片 2

说明：

• 这两张卡决定项目语义主干，必须最先完成

第二组

• 卡片 3
• 卡片 4

说明：

• startup scene 和 Asset Database 可以在项目模型基本稳定后并行推进

第三组

• 卡片 5
• 卡片 6

说明：

• meta/GUID/package 与 Project 面板可以并行，但卡片 6 要依赖卡片 4 的稳定数据来源

第四组

• 卡片 7

说明：

• 当前面主链收敛后，立刻补测试矩阵，不要拖到 M2 中后期

建议首周目标

如果现在立刻进入执行，建议首周目标不是“完成整个 M1”，而是完成下面这一小段：

• 卡片 1：统一项目根目录解析
• 卡片 2：统一项目描述文件模型
• 卡片 3：startup scene 规则统一

原因：

• 这三张卡决定整个后续 M1-M4 的项目语义是否稳定
• 如果这层不稳，后面所有资源、导入、打包都容易建立在脆弱假设上

结论

M1 P0 的正确执行方式，不是同时开很多卡，而是先把项目语义、资源语义和编辑器可见性主链做稳。

因此建议现在就以本文件为基础，把卡片 1 到卡片 3 先进入正式开发，把卡片 4 到卡片 7 放入紧随其后的短周期执行队列。