starmen1265
0f96b79dba
两阶段流水线：搭建指南Markdown → JSON → UE5 Actor - 解析器：4种表格变体+范围展开+坐标表达式计算 - 配置：37种BSP资产映射+13种材质+7区域定义 - 验证：265个Actor全部通过，0错误 - Builder：UE5 Python API自动放置Actor+材质+Outliner - 报告：自动生成搭建报告Markdown Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
165 lines
7.2 KiB
Markdown
165 lines
7.2 KiB
Markdown
---
|
||
name: "requirements-analysis"
|
||
description: >
|
||
This skill should be used when the user or game-dev agent needs to "design a technical plan",
|
||
"write a tech design document", "analyze requirements", "do requirements analysis",
|
||
"做需求分析", "设计技术方案", "写技术设计文档", or "分析需求".
|
||
Provides an 8-step structured requirements analysis workflow that produces a comprehensive
|
||
technical design document from an execution document for UE5 game systems.
|
||
---
|
||
|
||
# 需求分析 Skill
|
||
|
||
8 步结构化需求分析工作流，从执行文档（执行案）到技术设计文档。为 UE5 游戏系统的程序设计（步骤④）提供系统化的分析方法论。
|
||
|
||
## 触发条件
|
||
|
||
- **步骤④自动触发**：game-dev agent 进入程序设计阶段时自动使用此 skill
|
||
- **用户手动触发**：用户说"做需求分析"、"设计技术方案"、"写技术设计文档"等时触发
|
||
|
||
## 输入
|
||
|
||
按序阅读以下文档，获取完整的上下文信息：
|
||
|
||
1. **执行文档** (`docs/design/<stage>/<系统名>-执行案.md`) — 行为规则细节（主要输入）
|
||
2. **系统设计文档** (`docs/design/<stage>/<系统名>.md`) — 全局上下文
|
||
3. **配置表** (`GameConfig/`) — 可调参数
|
||
4. **概念文档** (`docs/design/概念草案.md`) — 方向参考（需要理解设计意图时查阅）
|
||
|
||
---
|
||
|
||
## 8 步分析工作流
|
||
|
||
### 步骤①：需求功能点罗列
|
||
|
||
从执行文档中提取每个行为规则作为功能点，按实现方式分为两大类：
|
||
|
||
**UE 内置功能**：使用 UE5 引擎原生能力即可覆盖的功能点。典型包括：
|
||
- Enhanced Input 输入映射与回调
|
||
- SpringArm 摄像机跟随、碰撞处理、Camera Lag
|
||
- CMC（CharacterMovementComponent）移动参数配置
|
||
- SetViewTargetWithBlend 摄像机切换
|
||
- 碰撞检测（SphereComponent / BoxComponent Overlap）
|
||
- UMG Widget 生命周期管理
|
||
- DataAsset / DataTable 数据配置
|
||
|
||
**自定义实现**：需要编写 C++ 或蓝图代码的功能点。包括：
|
||
- 自定义状态机与状态转换逻辑
|
||
- 跨系统协调与事件分发
|
||
- 自定义 UI 交互逻辑
|
||
- 特殊的游戏规则判定
|
||
|
||
以表格形式输出，每个功能点标注对应的执行案条目编号。分类原则：UE 内置能力覆盖 80% 以上需求且行为一致 → UE 内置；否则 → 自定义实现。
|
||
|
||
### 步骤②：功能领域图
|
||
|
||
识别当前系统由哪些功能模块组成，以及模块之间的交互关系。
|
||
|
||
**关键约束**：只关注功能领域和领域之间的关系，不细分到类级别。这是自顶向下的模块级设计，在深入类设计之前先建立全局视图。
|
||
|
||
使用 Mermaid `flowchart` 绘制：
|
||
- 使用 `subgraph` 划分层（如输入层、核心层、数据层、表现层）
|
||
- 实线 `-->` 表示主数据流 / 同步调用
|
||
- 虚线 `-.->` 表示事件通知 / 异步通信
|
||
- 配合模块职责说明表格
|
||
|
||
### 步骤③：类设计图
|
||
|
||
将功能领域图细化为具体的类设计。展示每个类的关键数据成员和关键接口，以及类之间的关系。
|
||
|
||
使用 Mermaid `classDiagram` 绘制，必须明确标注关系类型：
|
||
|
||
| 关系 | 箭头 | UE5 典型场景 |
|
||
|------|------|-------------|
|
||
| 继承 | `<\|--` | `ACharacter` 的子类 |
|
||
| 实现 | `..\|>` | `UInterface` 的实现类 |
|
||
| 组合 | `*--` | Character 持有 Component（生命周期绑定） |
|
||
| 聚合 | `o--` | 引用其他 Actor/Component（非拥有） |
|
||
| 依赖 | `..>` | 方法参数、临时引用 |
|
||
|
||
同时提供新增类表格、修改类表格、新增蓝图表格。类命名遵循 UE5 前缀规范（`A`/`U`/`I`/`F`/`E`）。
|
||
|
||
### 步骤④：时序图（条件性）
|
||
|
||
> ⚠️ 仅当特性满足以下任一条件时绘制：涉及 3+ 个系统协调、有条件分支或循环流程、跨层级通信（UI ↔ 逻辑 ↔ 数据）。简单特性跳过。
|
||
|
||
使用 Mermaid `sequenceDiagram` 追踪复杂特性的跨系统调用流程：
|
||
- 从玩家输入或系统入口开始
|
||
- 经过哪些系统的哪些接口
|
||
- 到最终完成或返回
|
||
- 使用 `activate`/`deactivate` 展示调用栈深度
|
||
- 标注关键判断分支
|
||
|
||
### 步骤⑤：核心数据结构
|
||
|
||
定义系统所需的枚举、结构体、配置数据。
|
||
|
||
以 UE5 C++ 头文件风格书写：
|
||
- 使用 `UENUM(BlueprintType)` 标记枚举
|
||
- 使用 `USTRUCT(BlueprintType)` 标记结构体
|
||
- 使用 `UPROPERTY(EditAnywhere, ...)` 标记可配置属性
|
||
- 每个字段提供中文注释说明和合理的默认值
|
||
- 区分"配置参数"和"运行时状态"
|
||
|
||
### 步骤⑥：复杂接口描述（条件性）
|
||
|
||
> ⚠️ 仅当接口有 5+ 个决策分支或协调多个子系统状态时需要。简单接口（纯数据查询、简单赋值）跳过。
|
||
|
||
对复杂接口，选择最适合的方式描述其执行逻辑：
|
||
- **流程图**（Mermaid `flowchart`）：适合有多条件分支和并行路径的逻辑
|
||
- **伪代码**：适合有明确顺序步骤、需要展示具体判断条件的逻辑
|
||
- **鲁棒图**：适合展示边界/控制/数据三种元素的交互
|
||
|
||
描述时必须包含：前置检查（快速失败）→ 核心逻辑 → 异步操作标注 → 边界情况处理。
|
||
|
||
### 步骤⑦：技术难点/风险
|
||
|
||
识别并评估实现过程中可能遇到的技术难点和风险：
|
||
|
||
- 按等级分类：🔴 高（可能导致方案不可行）、🟡 中（需要额外工作但可控）、🟢 低（已知解法）
|
||
- 每个风险包含：风险描述、详细说明、缓解措施
|
||
- 特别关注：UE5 限制、性能瓶颈、跨系统时序问题、数据一致性
|
||
|
||
### 步骤⑧：工期预估
|
||
|
||
给出工作量和实现拆分建议：
|
||
|
||
- **总工期**：以天为单位（X-Y 天范围）
|
||
- **代码量**：新增/修改的 C++ 行数 + 蓝图数量
|
||
- **实现拆分**：推荐按系统/模块/功能点拆分为可独立验证的子任务，每个子任务标注预估时间、依赖关系、验证方式
|
||
|
||
拆分原则：每个子任务可在半天到一天内完成，有明确的验证标准，子任务之间依赖关系清晰。
|
||
|
||
---
|
||
|
||
## 输出
|
||
|
||
最终产出为技术设计文档，保存到 `docs/technical/<系统名>-技术方案.md`。
|
||
|
||
文档必须遵循 `references/output-template.md` 中定义的标准模板结构。8 步分析的结果整合到模板的对应章节中，同时保留现有的必要章节（美术资源需求、数据流、可调参数汇总、文件结构）。
|
||
|
||
**阶段适配**：
|
||
- 原型阶段：步骤②④⑥可适度简化，允许占位描述
|
||
- 批量生产阶段：所有步骤必须完整、详细
|
||
|
||
---
|
||
|
||
## 条件步骤判定速查
|
||
|
||
| 步骤 | 激活条件 | 跳过条件 |
|
||
|------|---------|---------|
|
||
| ④ 时序图 | 3+ 系统协调 / 有分支循环 / 跨层级通信 | 单系统内部 / 纯配置 |
|
||
| ⑥ 复杂接口描述 | 5+ 决策分支 / 协调多子系统 / 有异步等待 | 简单查询 / 2-4 分支简单逻辑 |
|
||
|
||
详细判定启发式参见 `references/diagram-guide.md` 第 3 节。
|
||
|
||
---
|
||
|
||
## 参考文件
|
||
|
||
| 文件 | 内容 | 何时查阅 |
|
||
|------|------|---------|
|
||
| `references/diagram-guide.md` | Mermaid 语法速查、项目约定、复杂度判定 | 绘制任何图表前查阅 |
|
||
| `references/output-template.md` | 完整技术设计文档模板 | 开始写文档前查阅，确保结构完整 |
|
||
| `references/examples.md` | 各步骤的注释示例（来自现有技术文档） | 需要参考输出效果时查阅 |
|