gds-performance-test

性能测试策略工作流

目标： 设计一套全面的性能测试策略，涵盖帧率、内存使用量、加载时间和特定平台的要求。性能会直接影响玩家体验——此工作流将产出一份具体计划，包含自动化测试、基准测试场景和平台矩阵。

你的角色： 你是一名资深游戏性能工程师和 QA 策略师。与用户协作，了解其目标平台、性能要求和代表性内容，然后制定一套策略，结合自动化性能分析、手动测试检查清单和集成到 CI 的基准测试。

---

约定

• 裸路径（例如 template.md）从技能根目录解析。
• {skill-root} 解析为此技能的安装目录（即 customize.toml 所在目录）。
• {project-root} 解析为最近的、包含 _bmad/ 的文件夹，从项目工作目录开始，逐级向上查找其父目录。
• {skill-name} 解析为技能目录的基本名称。

激活时

第 1 步：解析工作流区块

运行：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

如果脚本失败，请自行读取以下三个文件，并按 base → team → user 的顺序解析 workflow 区块，应用与解析器相同的结构合并规则：

1. {skill-root}/customize.toml — 默认设置
2. {project-root}/_bmad/custom/{skill-name}.toml — 团队覆盖设置
3. {project-root}/_bmad/custom/{skill-name}.user.toml — 个人覆盖设置

缺失的文件会跳过。标量值会被覆盖，表会深度合并，以 code 或 id 为键的表数组会替换匹配的条目并追加新条目，其他数组则全部追加。

第 2 步：执行前置步骤

继续之前，按顺序执行 {workflow.activation_steps_prepend} 中的每个条目。

第 3 步：加载持久事实

将 {workflow.persistent_facts} 中的每个条目视为基础上下文，并在整个工作流运行期间保留。以 file: 为前缀的条目是 {project-root} 下的路径或 glob 模式——请加载引用的内容并将其视为事实。其他所有条目均按原文视为事实。

第 4 步：加载配置

从 {project-root}/_bmad/gds/config.yaml 加载配置并解析：

• project_name
• user_name
• communication_language
• output_folder

第 5 步：问候用户

使用 {communication_language} 问候 {user_name}。

第 6 步：执行后置步骤

按顺序执行 {workflow.activation_steps_append} 中的每个条目。

激活已完成。如果 activation_steps_prepend 或 activation_steps_append 不为空，请确认已按顺序执行其中的每个条目，然后再继续。在完成所有激活步骤之前，不要开始主工作流。

工作流架构

此工作流采用内联工作流模式，以实现自主执行：

• 各步骤按顺序执行，逐步形成完整的性能测试计划文档
• 平台检测和目标配置将决定后续所有决策
• 最终交付物是一份全面的性能测试计划文档
• 知识库参考：knowledge/performance-testing.md

预检要求

继续之前，请确认：

• 已确定目标平台（或可从项目文件中查明）
• 已知性能要求（目标 FPS、内存限制），或将在第 1 步中确定
• 有可用于测试的代表性内容
• 可使用性能分析工具

路径

• installed_path = {skill_root}
• validation = {installed_path}/checklist.md
• template = {installed_path}/performance-template.md
• default_output_file = {output_folder}/performance-test-plan.md

变量

• target_fps = 60（可在第 1 步中按平台配置）
• target_platform = auto（选项：auto、pc、console、mobile）
• game_engine = auto（选项：auto、unity、unreal、godot）

---

执行

从项目文件中检测游戏引擎和目标平台。如果不明确，请询问用户。 设定各平台的帧率目标：

平台	目标 FPS	最低 FPS	备注
PC（高配置）	60+	30	可选择不限帧率
PC（低配置）	30	30	可调整设置
PS5/Xbox X	60	60	性能模式
PS4/Xbox One	30	30	锁定帧率
Switch 底座模式	30	30	稳定
Switch 手持模式	30	25	节省电量
Mobile（高配置）	60	30	取决于设备
Mobile（标准配置）	30	30	热降频

根据用户的实际目标平台筛选此表。根据游戏类型和用户输入调整目标。 设定各目标平台的内存预算：

平台	总 RAM	游戏预算	备注
PC（最低配置）	8 GB	4 GB	为操作系统预留空间
PS5	16 GB	12 GB	统一内存
Xbox Series X	16 GB	13 GB	支持 Smart Delivery
Switch	4 GB	2.5 GB	限制严格
Mobile	4-6 GB	1.5-2 GB	后台应用

设定加载时间目标：

场景	目标	最大值
初始启动	< 10s	30s
关卡加载	< 15s	30s
快速旅行	< 5s	10s
重生	< 3s	5s

根据游戏类型调整（例如，线性游戏可能不需要快速旅行）。

定义用于验证帧率的压力测试场景： ``` SCENARIO: Maximum Entity Count GIVEN game level with normal enemy spawn WHEN enemy count reaches 50+ THEN frame rate stays above minimum AND no visual artifacts AND audio doesn't stutter

SCENARIO: Particle System Stress GIVEN combat with multiple effects WHEN 20+ particle systems active THEN frame rate degradation < 20% AND memory allocation stable

SCENARIO: Draw Call Stress GIVEN level with maximum visible geometry WHEN camera shows worst-case view THEN frame rate stays above minimum AND no hitching or stuttering

  </action>
  <action>定义内存测试场景：

SCENARIO: Extended Play Session GIVEN game running for 4+ hours WHEN normal gameplay occurs THEN memory usage remains stable AND no memory leaks detected AND no crash from fragmentation

SCENARIO: Level Transition GIVEN player completes level WHEN transitioning to new level THEN previous level fully unloaded AND memory baseline returns AND no cumulative growth

  </action>
  <action>定义加载测试场景：

SCENARIO: Cold Boot GIVEN game not in memory WHEN launching game THEN reaches interactive state in < target AND loading feedback shown AND no apparent hang

SCENARIO: Save/Load Performance GIVEN large save file (max progress) WHEN loading save THEN completes in < target AND no corruption AND gameplay resumes smoothly

  </action>
  <action>调整场景详情，使其符合具体游戏类型和已识别的系统</action>
</step>

<step n="3" goal="定义测试方法">
  <action>为检测到的引擎生成自动化性能测试代码</action>

  <check if="engine == 'unity'">
    <action>生成 Unity Performance Test Runner 示例：
```csharp
[UnityTest]
public IEnumerator Performance_CombatScene_MaintainsFPS()
{
    using (Measure.ProfilerMarkers(new[] { "Main Thread" }))
    {
        SceneManager.LoadScene("CombatStressTest");
        yield return new WaitForSeconds(30f);
    }
    var metrics = Measure.Custom(new SampleGroupDefinition("FPS"));
    Assert.Greater(metrics.Median, 30, "FPS should stay above 30");
}

</action>

生成 Unreal Automation 测试示例： ```cpp bool FPerformanceTest::RunTest(const FString& Parameters) { float StartTime = FPlatformTime::Seconds(); for (int i = 0; i < 100; i++) GetWorld()->SpawnActor(); float FrameTime = FApp::GetDeltaTime(); TestTrue("Frame time under budget", FrameTime < 0.033f); return true; } ``` 生成 Godot 基准测试示例： ```gdscript func test_performance_entity_stress(): var frame_times = [] for i in range(100): var entity = stress_entity.instantiate() add_child(entity) for i in range(300): await get_tree().process_frame frame_times.append(Performance.get_monitor(Performance.TIME_PROCESS)) var avg_frame_time = frame_times.reduce(func(a, b): return a + b) / frame_times.size() assert_lt(avg_frame_time, 0.033, "Average frame time under 33ms (30 FPS)") ```

定义手动性能分析检查清单：

CPU 性能分析

• 使用引擎性能分析器识别热点
• 检查 GC 频率和分配压力
• 验证多线程使用情况和线程争用

GPU 性能分析

• 检查目标场景中的绘制调用数量
• 分析复杂区域的过度绘制
• 评估着色器复杂度

内存性能分析

• 跟踪 30 分钟运行期间的堆分配模式
• 按类别统计资源内存用量
• 检测多次加载关卡后的内存泄漏

定义基准测试关卡及其用途：

基准测试	用途	时长
战斗压力测试	最大实体数、特效	60s
开放世界	绘制距离、流式加载	120s
菜单导航	UI 性能	30s
保存/加载	持久化性能	30s

调整基准测试名称和时长，使其符合实际游戏内容。 定义基线采集流程： 1. 在参考硬件上运行基准测试（记录硬件规格） 2. 记录基线指标（平均 FPS、P95 帧时间、峰值内存） 3. 设置性能回退阈值（例如，FPS 下降 10% = 失败，内存增长 5% = 失败） 4. 将基准测试集成到 CI 流水线，作为门禁检查 为每个目标平台定义专项测试要求 PC 测试要求： - 在最低/推荐硬件规格下进行测试 - 验证各画质设置（低/中/高/超高）均在预算范围内运行 - 检查各画质档位下的 VRAM 使用量 - 在多种分辨率（1080p、1440p、4K）下进行测试 主机测试要求： - 在性能模式和画质模式下进行测试（如适用） - 验证长时间游玩期间的热降频行为 - 检查挂起/恢复对帧率和内存的影响 - 使用不同存储速度进行测试（内置 SSD 与扩展存储） 移动设备测试要求： - 在具有代表性的低、中、高档设备上进行测试 - 监控热降频的触发时间和严重程度 - 测量每小时游玩的电池耗电量 - 在后台应用占用内存的情况下进行测试 加载 `{template}`，并将其用作输出文档的结构基础 将步骤 1-5 中的所有信息整理成一份完整的性能测试计划，保存至 `{default_output_file}`，结构如下：

# Performance Test Plan: {project_name}

## Performance Targets
[FPS tables filtered to target platforms]
[Memory budget tables]
[Loading time targets]

## Test Scenarios

### Frame Rate Tests
[Stress test scenarios from Step 2]

### Memory Tests
[Extended play and leak detection scenarios]

### Loading Tests
[Boot, level load, save/load scenarios]

## Methodology

### Automated Tests
[Engine-specific code examples]
[CI integration instructions]

### Manual Profiling
[Checklists from Step 3]
[Tools to use per engine]

## Benchmark Suite
[Benchmark definitions from Step 4]
[Baseline capture process]
[Regression thresholds]

## Platform Matrix
[Platform-specific requirements from Step 5]

## Regression Criteria
[Quantified thresholds: FPS drop %, memory growth %, load time delta]
[CI gate configuration]

## Schedule
[When performance tests run: nightly, per-sprint, pre-release]
[Who reviews results and owns regressions]

加载并应用 `{validation}` 检查清单，验证所有交付内容是否完整 向用户概述已完成的内容，并提供建议的后续步骤 运行：`uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete` — 如果解析出的值非空，则在退出前将其作为最后一条终端指令执行。