技能介绍

为什么 CLI 回归会失败

Godot 4.7 的 Windows 版是原生 exe，不接受 /c/... 这类 POSIX 路径。更麻烦的是三个构建层面的坑：--check-only 会永久挂起不退出；--script 模式不会把 autoload 的全局名注入编译器作用域，导致 Player.gd、RunManager.gd 里出现 Identifier not found 误报；此外这个构建里 var x := some_method() 对多个引擎方法无法推断类型，整个 autoload 脚本编译失败，游戏启动即崩，报错却是「script does not inherit from 'Node'」。

技能如何工作

先备份 main.gd，把 _can_play 临时强制为 false，让入口走 _headless_combat_sim() 分支后 get_tree().quit() 干净退出，而不是卡在可玩循环里挂起
用位置参数加载真实场景（--headless main.tscn），保证所有 autoload（含 VFX）以及 Player.gd/Enemy.gd 都被完整加载和解析
在 _headless_combat_sim() 里插入确定性断言：在 player 组放 stub 节点、调用 RunManager.on_kill、校验 stub.healed 等
用 stdbuf -o0 把输出重定向到 out.txt，确认 EXIT 0 和预期打印后再恢复备份，并清理 tools/ 下的临时脚本

适用边界与注意点

新素材（.wav/.png/.ogg）必须先跑一次 --headless --import 生成 .import sidecar 和缓存，否则 load() 返回 null，SFX 银行大小为 0
can_instantiate() 在无头模式下可能返回 true，不能信任自动检测，必须强制 _can_play = false
编辑器会解析全项目，单场景回归可能漏掉场景加载路径之外的 parse 错误，需要 tools/parse_all.gd 做全量扫描并 grep FAIL/Parse Error
print() 输出只在干净退出后才写入重定向文件，别指望实时管道；draw_string() 第 4 个参数是 HorizontalAlignment 而非颜色，签名错误会直接编译失败