game-build-log-triage

游戏构建日志分类

使用此技能，将嘈杂的 Unity 和 Unreal 日志整理成简短、按优先级排序的调试概要。

目标不是解释每一行，而是找出第一个非级联故障，确定最可能出问题的子系统，并告知用户接下来该检查什么。

在对不熟悉的引擎特定错误进行分类前，请先阅读 references/engine-patterns.md。

如果用户询问的不是某一条故障日志，而是 Unity/Unreal 项目中反复出现的 CI 不稳定问题、缓存策略、打包工作流设计或发布自动化，请在此次分类之后或同时，将这类更广泛的工作流设计任务交给 game-ci-cd-pipeline。

何时使用此技能

• Unity 构建、导入、编译、打包或运行模式启动故障
• Unreal 构建、UBT/UHT、Cook、打包、着色器、插件或模块故障
• 游戏项目的 CI 日志，其中原始输出冗长且嘈杂
• 资源移动、重定向器、引用丢失、.meta/GUID、模块或插件损坏
• 用户提供 Editor.log、包输出、BuildCookRun 日志、堆栈跟踪或控制台摘录，并希望了解接下来的调试步骤

说明

步骤 1：确认引擎和日志范围

1. 判断材料主要涉及 Unity、Unreal，还是混合/未知。
2. 记录可见的日志来源：
   • Unity：Editor.log、控制台输出、包管理器输出、玩家构建输出、CI 记录
   • Unreal：UBT/UHT 输出、Cook/打包日志、输出日志、消息日志、崩溃日志、CI 记录
3. 如果日志中包含时间范围或失败命令，请找出并记录。
4. 如果日志很长，优先关注：
   • 包含 error、exception、fatal、failed、UHT、UBT、NullReferenceException、MissingReferenceException、Cook failed、AutomationTool exiting、Script compilation error 的行
   • 大量重复后续错误出现之前的第一组错误

步骤 2：找出第一个可采取行动的故障

从上到下检查，并区分根因候选项与级联噪声。

按以下顺序判断：

1. 硬性中止/致命行——首条明确导致运行中止的行
2. 配置或依赖阻塞——缺少模块、SDK、包、插件、目标或程序集定义
3. 编译/反射阻塞——C# 编译器错误、UHT/UBT 错误、宏/反射问题、符号缺失、类重复、循环依赖
4. 资源/引用阻塞——资源缺失、重定向器引发的问题、GUID/meta 不匹配、导入错误、Prefab/Blueprint 引用损坏
5. 环境/平台阻塞——Android/iOS/主机平台 SDK 问题、签名/预配、工具链路径、不支持的目标平台
6. 次要噪声——重复异常、重试或后续出现的“无法完成”消息

不要把 20 个症状总结成 20 个原因。

步骤 3：对故障类型进行分类

将日志归入一个主要类别，可选归入一个次要类别。

主要类别

• compile-code
• compile-reflection
• asset-reference
• package-plugin-config
• platform-sdk
• build-pipeline-state
• runtime-startup
• unknown-needs-more-context

Unity 常见对应关系

• CS0246、CS0103、Assembly has reference to non-existent assembly → compile-code 或 package-plugin-config
• 导入/构建期间出现 MissingReferenceException、NullReferenceException，或 GUID/meta 缺失问题 → asset-reference
• 包管理器解析失败、asmdef 引用无效、脚本定义不匹配 → package-plugin-config
• Android SDK/JDK/Gradle/Xcode 签名故障 → platform-sdk

Unreal 常见对应关系

• Unable to instantiate module、插件/模块缺失、.Build.cs 错误、目标规则故障 → package-plugin-config
• UHT/UObject/反射宏错误、生成代码问题 → compile-reflection
• Cook failed、内容缺失、重定向器/资源移动引发的问题 → asset-reference 或 build-pipeline-state
• Visual Studio/工具链/SDK/平台打包阻塞 → platform-sdk

第 4 步：生成分诊简报

返回一份简明报告，结构必须如下：

# Game Log Triage

## Engine
- Unity | Unreal | Mixed/Unknown

## Log scope
- Source: ...
- Failing command/stage: ...
- Confidence: high | medium | low

## First actionable failure
- Line or excerpt: `...`
- Why it matters: ...
- Why later errors look secondary: ...

## Classification
- Primary bucket: ...
- Secondary bucket: ...

## Most likely root cause
- 1-3 sentence explanation grounded in the log

## Next checks
1. ...
2. ...
3. ...

## Files / settings to inspect
- ...
- ...
- ...

## Safe follow-up commands
```bash
# optional read-only inspection commands only

暂时不要做的事

• 在确认主要阻碍之前，避免进行无差别清理或大规模删除资源

### Step 5: Tailor the next checks to the engine
**For Unity, prefer checks like:**
- `Packages/manifest.json`, `Packages/packages-lock.json`
- `.asmdef` references and scripting define symbols
- `ProjectSettings/`, platform build settings, signing/toolchain paths
- recent asset moves, `.meta` files, GUID stability, prefab/scene references
- the first compiler error before any `NullReferenceException` flood

**For Unreal, prefer checks like:**
- `.uproject`, plugin enablement, `Source/*/*.Build.cs`, target files
- first UBT/UHT error before package/cook fallout
- redirectors, missing assets, moved content, generated code mismatches
- platform SDK/toolchain prerequisites and AutomationTool stage
- whether the failure started after renaming classes/assets or changing modules/plugins

### Step 6: Escalate carefully when evidence is weak
If the log excerpt is too short or starts mid-cascade:
1. Say that confidence is low.
2. Ask for the earliest error cluster or the failing command section.
3. List the minimum extra context required:
   - first 50-150 lines around the first error
   - engine version
   - target platform
   - whether the breakage followed code/package/asset/plugin changes

Do not pretend certainty from a truncated excerpt.

## Output format
Always return a short debugging brief, not a stream-of-consciousness analysis.

Required qualities:
- prioritize the first actionable blocker
- separate root cause from cascade noise
- keep the report under roughly 250-400 words unless the user asks for more
- include file paths/settings to inspect when the engine suggests them
- keep shell suggestions read-only unless the user explicitly asks for fixes

## Examples

### Example 1: Unity compile + package drift
**Input**
> Unity build failed after we updated a package. The log shows `CS0246: The type or namespace name 'InputSystem' could not be found` and then dozens of `NullReferenceException` lines.

**Output sketch**
- Engine: Unity
- First actionable failure: `CS0246` for `InputSystem`
- Classification: `package-plugin-config`
- Root cause: package or asmdef reference drift is blocking compilation; the later null refs are likely fallout from the failed compile/import state
- Next checks:
  1. confirm `Packages/manifest.json` still includes the Input System package
  2. inspect asmdef references for the affected assembly
  3. verify scripting define symbols or package migration notes

### Example 2: Unreal cook failure after asset moves
**Input**
> Unreal cook started failing after we renamed folders. The log shows `Cook failed` and multiple missing asset warnings.

**Output sketch**
- Engine: Unreal
- First actionable failure: earliest missing asset / redirector-related line before `Cook failed`
- Classification: `asset-reference`
- Root cause: moved content likely left broken references or redirectors that were not fixed up before cook
- Next checks:
  1. inspect moved asset paths and redirectors
  2. run a read-only audit of referenced missing assets from the log
  3. verify whether plugin/content paths changed with the rename

### Example 3: Unreal UHT blocker
**Input**
> CI says `UnrealHeaderTool failed` after a refactor.

**Output sketch**
- Engine: Unreal
- First actionable failure: first UHT reflection/macros error, not later AutomationTool exit lines
- Classification: `compile-reflection`
- Root cause: header/reflection metadata mismatch during generated code step
- Next checks:
  1. inspect the referenced header and macro usage
  2. compare recent renamed classes or moved modules
  3. verify generated-code dependencies in the owning module

## Best practices
1. **Lead with the earliest blocker** — game-engine logs cascade badly.
2. **Name the subsystem** — compile, reflection, asset/reference, plugin/config, or platform SDK.
3. **Prefer specific inspection targets** over generic advice like "rebuild everything."
4. **Keep remediation safe-first** — read-only commands and targeted checks before destructive cleanup.
5. **Treat asset moves as high-suspicion events** in both engines.
6. **Explain confidence** when the excerpt is partial or noisy.
7. **Use engine language the team already uses**: asmdef, GUID/meta, UBT/UHT, redirectors, BuildCookRun, etc.

## References
- [Unity Console](https://docs.unity3d.com/Manual/Console.html)
- [Unity Log Files](https://docs.unity3d.com/Manual/log-files.html)
- [Unity Version Control / Smart Merge Support](https://docs.unity3d.com/Manual/ExternalVersionControlSystemSupport.html)
- [Unreal Logging](https://dev.epicgames.com/documentation/en-us/unreal-engine/logging-in-unreal-engine)
- [Unreal Packaging Projects](https://docs.unrealengine.com/5.0/en-US/packaging-unreal-engine-projects/)
- [Unreal Redirectors](https://docs.unrealengine.com/5.0/en-US/redirectors-in-unreal-engine/)