docs(workflow): 新增游戏开发工作流文档，定义版本流水线与PM质量门

docs/development-workflow.md

@@ -0,0 +1,395 @@
+# 游戏开发工作流
+
+> 本文档定义 ChildHood 项目的版本开发流水线、角色职责、产出标准和质量检查规则。
+> 所有开发工作必须遵循此工作流，不可跳过或并行阶段。
+
+---
+
+## 角色定义
+
+| 角色 | 职责 | 产出位置 | PM 如何判断其进度 |
+|------|------|----------|-------------------|
+| **策划** (Design) | 玩法设计、数值平衡、叙事、系统机制 | `docs/design/`、`GameConfig/` | 扫描 `docs/design/` 和 `GameConfig/` 目录中的文件 |
+| **程序** (Dev) | 蓝图/C++、系统实现、技术架构、Bug 修复 | `Source/`、`Content/Blueprints/`、`Content/Data/`、`docs/technical/` | 扫描 `Source/`、`Content/`、`docs/technical/` 目录中的文件 |
+| **美术** (Art) | 美术需求分析、资产规格、风格指南、AI 图像 | `docs/art/`、`Content/` | 扫描 `docs/art/` 和 `Content/` 目录中的文件 |
+| **PM** | 进度追踪、优先级决策、风险预警、流水线推进、任务依赖梳理 | `docs/plans/` | 不产出设计文档、代码或美术资产 |
+
+### 协作规则
+
+- **策划先行**：设计文档是其他角色的需求源
+- **程序读设计**：实现前必须先读取对应设计文档和配置表
+- **文档即交接**：Agent 之间不直接通信，通过共享文档目录交接
+- **冲突时策划说了算**：玩法/数值/叙事的最终决定权在策划角色
+- **PM 是信息枢纽**：跨角色的信息同步和阻塞排查由 PM 负责
+
+### 进度汇报规则
+
+- 各 Agent 完成工作后汇报结果，**不自动勾选** `current.md`
+- 开发者确认后，由 PM 统一更新进度文档
+- PM 每次调用时主动扫描各目录，验证「汇报的进度」与「实际文件产出」是否一致
+
+---
+
+## 版本开发流水线
+
+每个版本的开发必须按以下流水线**严格顺序推进**：
+
+```
+① 全局设计案 → ② 版本Roadmap → ③ 当前版本设计文档 → ④ 执行案
+      ↓
+  [PM 审查：执行案质量门]
+      ↓
+  ⑤ 程序设计
+      ↓
+  [PM 审查：程序设计质量门]
+      ↓
+  ⑥ 美术产出
+      ↓
+  [PM 审查：美术资产验收门]
+      ↓
+  ⑦ 程序实现
+```
+
+**每个阶段都是下一阶段的必要前置条件。不可跳过或并行。PM 审查不通过则退回重做，不可进入下一阶段。**
+
+---
+
+### ① 全局设计案（策划）
+
+**目的**：定义整个游戏**最终形态**的全景图——有哪些系统、有哪些元素、它们大体上是什么关系。
+
+**范围**：面向游戏的最终完成形态，不是某个版本。
+
+**必须包含的内容**：
+
+1. **系统清单**：游戏最终包含哪些系统（移动、交互、收集、小游戏、时间、NPC、经济、叙事等）
+2. **元素清单**：游戏世界中的关键元素（角色、场景区域、收集品分类、NPC等）
+3. **系统关系**：各系统之间如何关联和互相影响
+4. **核心玩法循环**：玩家在游戏中做什么、为什么持续玩
+5. **情感目标**：游戏要给玩家带来什么样的体验和情感
+
+**产出形式**：
+- 可以有多个文档，按系统或主题拆分
+- 必须有一个**索引文档**把所有全局设计文档串联起来
+- 产出位置：`docs/design/`
+
+**PM 检查要点**：
+- 是否覆盖了游戏最终形态的所有主要系统？
+- 系统关系是否清晰（谁依赖谁、谁独立）？
+- 索引文档是否存在且能串联所有全局设计文档？
+
+**时间点**：项目初期集中产出，后续版本中可增量补充新系统的全局设计。
+
+---
+
+### ② 版本Roadmap（PM 主导，策划配合）
+
+**目的**：根据全局设计案，明确分几个版本推进，每个版本大致做哪些内容。
+
+**必须包含的内容**：
+
+1. **版本列表**：从 v0.1 到 v1.0 有哪些版本
+2. **每个版本的核心目标**：这个版本验证什么、实现什么
+3. **每个版本的范围概述**：大致包含哪些系统和内容
+4. **版本间的递进关系**：为什么先做这些后做那些
+5. **预估时间**：粗略的时间预估（不需要精确到天）
+
+**产出位置**：`docs/plans/roadmap.md`
+
+**PM 检查要点**：
+- 每个版本的范围是否与全局设计案对齐？
+- 版本间是否有清晰的递进逻辑（先核心后扩展）？
+- 是否有版本范围过大的风险？
+
+**时间点**：全局设计案基本成型后产出，随版本推进可调整。
+
+---
+
+### ③ 当前版本设计文档（策划）
+
+**目的**：针对最近要做的版本，明确这个版本的目标、范围、需要哪些元素和系统、做到什么程度。
+
+**范围**：仅限当前版本，不涉及后续版本。
+
+**必须包含的内容**：
+
+1. **版本目标定位**：这个版本要做到什么程度——是最小能跑的原型、功能完整的可玩版本、还是经过打磨的体验版？
+2. **内容范围**：本版本包含哪些内容，每种内容做到什么完成度（占位/初版/正式）
+3. **版本验收标准**：怎样算"这个版本做完了"？验收标准必须明确、可检验
+4. **本版本涉及的系统清单**：哪些系统需要在本版本实现（引用执行案）
+
+> **示例**：一个"场景漫游原型"版本的内容范围可能包括：主角使用占位胶囊体、场景用白盒几何体搭建其中3个区域、交互物先做5个验证核心流程、UI 用占位灰框。验收标准为"能在场景中自由移动并完成5个交互点的完整流程"。
+
+**产出位置**：`docs/design/vXX-design.md`（如 `docs/design/v01-design.md`）
+
+**与执行案的关系**：本文档是"这个版本要做什么"的总纲，执行案是"怎么实现每个系统"的细节。本文档引用执行案。
+
+**PM 检查要点**：
+- 版本目标定位是否明确？
+- 内容范围是否清晰，每种内容的完成度是否定义？
+- 验收标准是否明确、可检验？
+- 范围是否与 roadmap 中该版本的定义一致？
+
+---
+
+### ④ 执行案（策划）
+
+**目的**：针对当前版本中的每个系统/元素，写出完整的**交互规则细节**，细到程序照着这个逻辑实现功能。
+
+**范围**：仅限当前版本中需要实现的系统。
+
+**核心原则**：
+
+- **只描述行为和规则，不涉及技术实现**
+- **必须覆盖所有玩家可感知的行为**
+- **不能有模糊地带**——程序拿到执行案后不应有"这没写要怎么做"的疑问
+- **具体参数数值**（速度、距离等）不需要策划提前确定，程序先设初始值，后续体验阶段调优。如果策划有初始建议值可以标注"建议值，可调"
+
+**必须包含的内容**：
+
+1. **系统概述**：这个系统做什么、服务于什么体验目标
+2. **完整的行为规则清单**：每个操作的触发条件、触发后表现、结束条件
+3. **状态和状态转换**：系统有哪些状态、什么条件触发状态变化
+4. **边界情况处理**：异常/极端情况下的系统行为（如多个交互物重叠、交互中移动等）
+5. **与其他系统的交互**：本系统与其他系统的关联和影响
+
+**不应包含的内容**：
+- 用什么 UE5 组件实现
+- 代码/蓝图架构怎么组织
+- 数据用什么格式存储（JSON/CSV/DataAsset 等）
+- 具体的参数精确值（如推镜 0.5 秒、文案延迟 0.2 秒等调优参数）
+
+**产出形式**：
+- 每个系统一份执行案，按系统拆分
+- 产出位置：`docs/design/systems/<系统名>-execution.md`（如 `docs/design/systems/player-controller-execution.md`）
+- 如果某系统的全局设计文档中恰好已经写清了当前版本的执行级细节，可以直接引用，但需确保满足执行案的完整性标准
+
+**PM 检查要点**：
+- 是否覆盖了该系统所有"玩家可感知的行为"？
+- 是否有模糊地带（行为描述含"大概"、"可能"、"看情况"等词）？
+- 是否误入了技术细节（说了用什么 UE5 组件、数据格式等）？
+- 边界情况是否都处理了（多物体重叠、交互中断、异常状态等）？
+- 程序拿到这份文档后，能否不问策划任何问题就实现功能？
+
+---
+
+### PM 审查：执行案质量门
+
+**触发时机**：策划完成执行案（④）后，进入程序设计（⑤）之前。
+
+**审查人**：PM
+
+**审查内容**：
+
+1. **完整性**：是否覆盖了该系统所有玩家可感知的行为？每个操作是否明确了触发条件、触发后表现、结束条件？
+2. **清晰性**：是否有模糊地带（"大概"、"可能"、"看情况"等词）？行为描述是否无歧义？程序拿到后能否不问策划任何问题就实现功能？
+3. **边界情况**：异常/极端情况下的系统行为是否都处理了（多物体重叠、交互中断、异常状态等）？
+4. **系统间关联**：与其他系统的关联和影响是否说明？
+5. **技术越界检查**：是否误入了技术细节（UE5 组件、数据格式、代码架构）？精确参数值是否标注为"建议值，可调"而非固定值？
+
+**判定**：
+- **通过** → 进入 ⑤ 程序设计
+- **不通过** → 退回策划修改，列出具体问题清单，策划修正后重新提交审查
+
+**产出**：PM 审查记录（附在执行案文档末尾或记录在 `docs/plans/review-log.md`）
+
+---
+
+### ⑤ 程序设计（程序）
+
+**目的**：程序读完策划的执行案后，设计 UE5 中的具体实现方案。
+
+**前置条件**：执行案（④）已就绪，且 PM 审查通过。
+
+**必须包含的内容**：
+
+1. **实现方案**：针对执行案中的每条行为规则，说明打算如何在 UE5 中实现
+   - UE5 有现成功能的 → 说明用哪个功能、如何配置（如 Enhanced Input System、CharacterMovementComponent）
+   - UE5 没有直接对应的 → 说明自己如何实现，复杂系统需单独出一份技术文档描述
+2. **类与组件架构**：需要哪些 C++ 类/蓝图？继承关系？组件挂载方式？
+3. **数据流**：数据从哪里来（配置表/DataAsset/硬编码）？系统之间如何通信？
+4. **美术资源需求清单**：实现这个功能需要哪些美术资源？
+   - 角色骨骼模型？绑定要求？
+   - 哪几个动画？每个动画的触发时机和参数？
+   - 哪几个交互物模型？尺寸参考？
+   - UI 需要哪些图？图标？背景？尺寸？
+5. **技术风险和注意事项**：实现中可能遇到的技术难点
+
+**产出位置**：`docs/technical/<系统名>-tech.md`
+
+**PM 检查要点**：
+- 程序设计是否完整回应了执行案中的**每条**行为规则？
+- 美术资源需求是否列得具体（不是"需要一些模型"，而是"需要1个冰箱模型，约1.7m高"）？
+- 是否有执行案中的行为规则在技术方案中被遗漏？
+
+---
+
+### PM 审查：程序设计质量门
+
+**触发时机**：程序完成技术设计（⑤）后，进入美术产出（⑥）之前。
+
+**审查人**：PM
+
+**审查内容**：
+
+1. **执行案覆盖度**：程序设计是否完整回应了执行案中的**每条**行为规则？逐条对照，不得有遗漏
+2. **美术资源需求**：需求是否列得具体（不是"需要一些模型"，而是"需要1个冰箱模型，约1.7m高"）？每个资源的数量、尺寸、触发时机是否明确？
+3. **类与组件架构**：C++ 类/蓝图的继承关系和组件挂载方式是否清晰？
+4. **数据流**：数据从哪里来？系统之间如何通信？是否明确？
+5. **技术风险**：是否识别了实现中可能遇到的技术难点？
+
+**判定**：
+- **通过** → 进入 ⑥ 美术产出
+- **不通过** → 退回程序修改，列出具体问题清单（如遗漏的行为规则、不够具体的美术需求等），程序修正后重新提交审查
+
+**产出**：PM 审查记录（附在技术方案文档末尾或记录在 `docs/plans/review-log.md`）
+
+---
+
+### ⑥ 美术产出（美术）
+
+**目的**：根据程序输出的美术资源需求清单，产出对应资产。
+
+**前置条件**：程序设计（⑤）已就绪，且 PM 审查通过。
+
+**产出内容**：
+
+1. **美术资产**（模型、贴图、UI 图等）
+2. **资产清单**：哪个资源在哪个路径，方便程序引用
+
+**产出位置**：
+- 资产放 `Content/` 对应目录
+- 清单记录在 `docs/art/asset-manifest.md` 或直接在技术方案中更新
+
+**PM 检查要点**：
+- 程序资源需求清单中的每一项是否都有对应的美术产出？
+- 资产路径是否记录清晰，程序能找到？
+
+**当前阶段特殊说明**：v0.1 的美术资产可由开发者直接处理（使用占位模型/免费资源）。后续版本应建立 AI 生成流程（提示词 → 出图 → 出 3D 模型）。
+
+---
+
+### PM 审查：美术资产验收门
+
+**触发时机**：美术完成资产产出（⑥）后，进入程序实现（⑦）之前。
+
+**审查人**：PM
+
+**审查内容**：
+
+1. **需求覆盖度**：逐项对照程序设计中的美术资源需求清单，每一项是否都有对应的美术产出？
+2. **资产到位确认**：资产文件是否已放置在 `Content/` 对应目录？路径是否记录在资产清单中？
+3. **资产规格**：模型尺寸、贴图尺寸等是否符合需求清单中的规格要求？
+4. **缺失项处理**：如有未到位的资产，是否有明确的处理方案（开发者自行处理/使用占位/延期）？
+
+**判定**：
+- **通过** → 进入 ⑦ 程序实现
+- **不通过** → 退回美术补齐，列出具体缺失项和规格不符项，美术修正后重新提交审查
+
+**产出**：PM 审查记录（记录在 `docs/plans/review-log.md`）
+
+---
+
+### ⑦ 程序实现（程序）
+
+**目的**：基于程序设计方案和美术资产，实际编写代码和蓝图。
+
+**前置条件**：
+- 执行案（④）已就绪，且 PM 审查通过
+- 程序设计方案（⑤）已就绪，且 PM 审查通过
+- 必需的美术资产（⑥）已就位，且 PM 审查通过（或开发者已确认自行处理占位方案）
+
+**执行要求**：
+- 严格按照程序设计方案执行，如有偏差需记录原因
+- 实现完成后安排体验阶段，收集反馈调整参数
+- 每个系统实现后进行独立验证
+
+**产出位置**：`Source/`（C++）、`Content/Blueprints/`（蓝图）、`Content/Data/`（DataAsset）
+
+---
+
+## PM 诊断检查清单
+
+PM 在每次 `/plan` 调用时，针对**当前版本**逐项检查流水线状态：
+
+| 检查项 | 检查方式 | 通过条件 |
+|--------|----------|----------|
+| ① 全局设计案是否存在且完整？ | 检查 `docs/design/` 中的全局设计文档和索引 | 覆盖所有主要系统，有索引串联 |
+| ② Roadmap 是否存在？ | 检查 `docs/plans/roadmap.md` | 版本列表、每版本目标、递进关系明确 |
+| ③ 当前版本设计文档是否完整？ | 检查 `docs/design/vXX-design.md` | 回答了版本定位、内容范围、验收标准 |
+| ④ 执行案是否齐全？ | 检查 `docs/design/systems/` 对应执行案 | 每个涉及系统的行为规则都已明确，无模糊地带，无技术越界 |
+| **PM 审查**：执行案质量门 | 对照执行案质量标准逐项检查 | 完整性、清晰性、边界情况、技术越界全部通过 |
+| ⑤ 程序设计方案是否齐全？ | 检查 `docs/technical/` 对应文档 | 每个执行案都有对应技术方案，美术资源需求已列出 |
+| **PM 审查**：程序设计质量门 | 执行案与技术方案逐条对照，检查美术需求 | 行为规则全覆盖，美术需求具体 |
+| ⑥ 美术资产是否就位？ | 检查程序设计中的资源需求清单 vs 实际资产 | 所有必需资产已产出或开发者已确认自行处理 |
+| **PM 审查**：美术资产验收门 | 美术需求清单 vs 实际资产逐项对照 | 每项需求都有对应产出，路径和规格符合 |
+| ⑦ 程序实现是否完成？ | 检查 `Source/`、`Content/` 中的实际文件 | 上游产出均已就位，实现工作可启动或已完成 |
+
+**遇到第一个未通过的即为当前应推进的阶段。PM 审查未通过的，退回对应角色修改后重新审查。**
+
+---
+
+## 文档质量检查标准
+
+以下标准对应流水线中的三道 PM 质量门。PM 审查时按对应清单逐项检查。
+
+### 执行案质量标准（对应「执行案质量门」）
+
+**完整性检查**：
+- [ ] 是否覆盖了该系统所有玩家可感知的行为？
+- [ ] 每个操作是否明确了触发条件、触发后表现、结束条件？
+- [ ] 边界情况是否都处理了？
+- [ ] 与其他系统的关联是否说明？
+
+**清晰性检查**：
+- [ ] 是否有模糊地带（"大概"、"可能"、"看情况"等词）？
+- [ ] 行为描述是否无歧义（如"移动"是否明确了参考系）？
+- [ ] 程序拿到后能否不问策划任何问题就实现功能？
+
+**边界检查**：
+- [ ] 是否误入了技术细节（UE5 组件、数据格式、代码架构）？
+- [ ] 精确参数值是否标注为"建议值，可调"而非固定值？
+
+### 程序设计质量标准（对应「程序设计质量门」）
+
+- [ ] 是否完整回应了执行案中的**每条**行为规则？（逐条对照）
+- [ ] 美术资源需求是否列得具体（尺寸、数量、触发时机）？
+- [ ] 类与组件架构是否清晰？
+- [ ] 数据流是否明确？
+- [ ] 技术风险是否识别？
+
+### 美术资产验收标准（对应「美术资产验收门」）
+
+- [ ] 程序资源需求清单中的每一项是否都有对应的美术产出？（逐项对照）
+- [ ] 资产文件是否已放置在 `Content/` 对应目录？
+- [ ] 资产路径是否记录在资产清单中，程序能找到？
+- [ ] 资产规格（模型尺寸、贴图尺寸等）是否符合需求？
+- [ ] 未到位资产是否有明确的处理方案？
+
+---
+
+## 游戏开发阶段知识
+
+PM 必须理解游戏开发各阶段的特征，用于诊断产出是否匹配：
+
+| 阶段 | 特征 | 应有交付物 | 工作重点 |
+|------|------|-----------|----------|
+| **预制作** | 想清楚再动手 | 全局设计案、版本Roadmap、各系统执行案、美术风格指南 | 确保设计充分，避免后期返工 |
+| **核心系统制作** | 先跑通最小可玩循环 | 角色控制器、核心交互系统、基础UI框架、白盒场景、占位模型 | 系统能跑起来比做得漂亮重要 |
+| **内容填充** | 依赖核心系统稳定 | 场景细节、交互数据配置、正式美术资产、音效 | 核心系统锁定后再大规模填充 |
+| **集成联调** | 多系统协同工作 | 系统集成测试记录、Bug列表、性能报告 | 暴露和解决集成问题 |
+| **打磨发布** | 不加新功能 | Bug修复记录、平衡性调整、优化报告、构建版本 | 稳定性和品质 |
+
+**诊断判断**：
+- 处于「预制作」但缺少关键设计文档 → 标记风险，建议补齐
+- 处于「核心系统制作」但执行案未完成 → 建议先收尾执行案再写代码
+- 处于「内容填充」但核心系统不稳定 → 建议先修复核心系统
+- 某角色产出明显落后于其他角色 → 标记为瓶颈
+
+### 单人独立开发的特殊考量
+
+- **无法并行**——同一时间只能做一件事，选择更关键
+- **精力有限**——避免一次性拆分太多并行任务
+- **心流重要**——建议按「完整做完一个小系统」而非「同时推进多个系统」的方式工作
+- **早期验证**——越早能跑起来看到东西，越不容易失去动力
+- **文档交接**——Agent 之间通过文档交接，PM 是信息枢纽