来源: CONTRIBUTING.md doc/c++/TESTING.md doc/c++/PERFORMANCE.md tests/AGENTS.md commit d32b9cc880a8 docs-explanation

调试与故障定位

高质量调试先固定现象和边界，再选择工具。不要从最后一行日志直接猜修复，也 不要为了“消除报错”改变无关游戏行为。

建立可复现案例

记录以下最小上下文：

• CCB commit、平台、编译器和构建选项；
• 世界、存档或 MOD 组合，以及是否能在新世界复现；
• 精确操作序列、预期行为和实际行为；
• debug.log 的相关时间段、堆栈、断言与首个错误；
• 测试 filter、RNG seed、重复次数和是否只在优化构建出现。

先在干净的受支持配置复现，再逐个加入 MOD 或资源包。不要删除原存档；在副本 上测试迁移或恢复。

按失败阶段定位

阶段	先检查	证据
配置	preset、依赖、feature flag	完整配置命令与首个错误
编译/链接	首个失败 translation unit、符号、库顺序	编译器原始诊断
启动/加载	JSON/MOD 顺序、Schema、资源路径	debug.log 与最小数据集
运行时	调用栈、对象生命周期、不变量	聚焦测试或 debugger backtrace
保存/加载	save version、迁移、失效 ID	存档副本与回归测试
性能	可重复 workload、release build	profile，不凭体感优化

工具选择

• 使用 rg 从日志文本、动作 ID、JSON type 或断言定位注册与调用者。
• 用 Catch2 filter 把问题固定成回归测试，然后再扩大测试范围。
• native 崩溃使用目标平台 debugger 和符号化 backtrace；Android 同时保存 logcat 与 native 崩溃信息。
• 性能问题先按 doc/c++/PERFORMANCE.md 的原则测量热点；不要提交大型 profile、 clangd index、ctags 或 Doxygen HTML。

常见误区

• 后续 error 可能只是第一个 loader 错误的连锁反应。
• Debug 与 Release 的未初始化状态、断言和优化行为可能不同。
• 上游已经修复不等于能直接 cherry-pick；先检查 CCB 分歧和兼容性。
• 文档命令过期时应标记页面 stale 并修正文档，不能改构建脚本迁就旧教程。

完成调试后，把最小重现转成测试，运行测试策略中的受影响层级， 并在 PR 中分别报告已运行和未运行的平台检查。