From 8123bc6b22c37e23548f73b3078fe5bbc1ea826c Mon Sep 17 00:00:00 2001
From: moyin <2443444649@qq.com>
Date: Tue, 10 Mar 2026 16:18:17 +0800
Subject: [PATCH] =?UTF-8?q?chore=EF=BC=9A=E6=96=B0=E5=A2=9E=E5=B9=B6?=
 =?UTF-8?q?=E5=AE=8C=E5=96=84=20Godot=20CLI=20=E6=B5=8B=E8=AF=95=E6=8A=80?=
 =?UTF-8?q?=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude/skills/godot-cli-test-runner/SKILL.md | 105 ++++++++++++++++++
 .../godot-cli-test-runner/agents/openai.yaml  |   4 +
 .../references/godot-cli-commands.md          |  74 ++++++++++++
 3 files changed, 183 insertions(+)
 create mode 100644 .claude/skills/godot-cli-test-runner/SKILL.md
 create mode 100644 .claude/skills/godot-cli-test-runner/agents/openai.yaml
 create mode 100644 .claude/skills/godot-cli-test-runner/references/godot-cli-commands.md

diff --git a/.claude/skills/godot-cli-test-runner/SKILL.md b/.claude/skills/godot-cli-test-runner/SKILL.md
new file mode 100644
index 0000000..4633ece
--- /dev/null
+++ b/.claude/skills/godot-cli-test-runner/SKILL.md
@@ -0,0 +1,105 @@
+---
+name: godot-cli-test-runner
+description: Run Godot CLI commands for this project with emphasis on headless test execution, script runs, scene runs, and export/debug operations. Use when the user asks to run Godot tests or commands (for example “Godot 跑测试”, “执行 Godot 命令”, “检查 Godot 参数”), troubleshoot CLI failures, or request reusable terminal/CI command templates.
+---
+
+# Godot CLI Test Runner
+
+## Overview
+Use deterministic Godot CLI workflows for Windows terminal and CI-style execution. Prefer `--headless`, explicit `--path`, and `--log-file` for reproducible diagnostics.
+
+## Quick Decision
+1. Parse-only check script syntax: `--headless --path . --script <file> --check-only`.
+2. If test logic depends on autoload singletons (for example `SceneManager`, `LocationManager`, `EventSystem`), do not use direct `--script` as primary validation; use scene/project context first.
+3. For isolated script tests without autoload dependencies, run `--headless --path . --script <file>`.
+4. Export build by using `--export-release` / `--export-debug` with an existing preset.
+5. Diagnose CLI behavior by adding `--verbose` and always writing `--log-file`.
+
+## Workflow
+
+### 1. Resolve executable and project path
+1. Prefer `godot` from PATH.
+2. If not available, use explicit exe path (for this machine typically `D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64_console.exe` or `D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64.exe`).
+3. Run from repository root and always pass `--path .` unless intentionally targeting another project.
+
+### 2. Preflight checks
+1. Confirm engine version: `godot --version`.
+2. Confirm options when needed: `godot --help`.
+3. Confirm project exists: ensure `project.godot` is present under `--path`.
+4. Read `project.godot` `[autoload]` and check whether the target test script references those singleton names.
+5. Prepare a log output path (for example `.godot/test_xxx.log`) and pass `--log-file`.
+
+### 3. Execute task type
+1. Autoload-dependent validation (preferred when script references global singleton names):
+`godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log`
+2. Scene-specific validation:
+`godot --headless --path . --scene res://scenes/Maps/square.tscn --quit-after 90 --log-file .godot/smoke_square.log`
+3. Script test (only for isolated logic or known SceneTree tests):
+`godot --headless --path . --script tests/unit/test_xxx.gd --log-file .godot/test_xxx.log`
+4. Script syntax only:
+`godot --headless --path . --script tests/unit/test_xxx.gd --check-only --log-file .godot/check_xxx.log`
+5. Export:
+`godot --headless --path . --export-release "Web" web_assets/index.html --log-file .godot/export_web_release.log`
+
+### 4. Capture and report results
+1. Report exit code, key stdout/stderr lines, and failed command.
+2. For failures, include one retry variant (for example add `--verbose`, switch explicit exe path, or switch from `--script` to `--scene` context).
+3. Keep output concise and actionable.
+4. If `--script` fails with missing singleton identifiers, mark it as context mismatch first, not business regression.
+
+## Command Templates
+
+### Windows (explicit exe)
+```powershell
+& "D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64_console.exe" --headless --path . --log-file .godot\test_websocket_close_code.log --script tests/unit/test_websocket_close_code.gd
+```
+
+### Generic (PATH)
+```powershell
+godot --headless --path . --log-file .godot/test_websocket_close_code.log --script tests/unit/test_websocket_close_code.gd
+```
+
+### With extra app args
+```powershell
+godot --headless --path . --log-file .godot/test_runner.log --script tests/unit/test_runner.gd -- --case websocket --timeout 30
+```
+
+## Minimal Runnable Examples
+Run from repository root (`--path .`).
+
+1. Run one scene-level smoke test (autoload-safe):
+```powershell
+godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log
+```
+
+2. Run one test script (isolated logic):
+```powershell
+godot --headless --path . --script tests/unit/test_websocket_close_code.gd --log-file .godot/test_websocket_close_code.log
+```
+
+3. Run one scene:
+```powershell
+godot --headless --path . --scene res://scenes/SomeScene.tscn --quit-after 90 --log-file .godot/smoke_scene.log
+```
+
+4. Parse script only (syntax check):
+```powershell
+godot --headless --path . --script tests/unit/test_websocket_close_code.gd --check-only --log-file .godot/check_websocket.log
+```
+
+If `godot` is not in PATH, replace `godot` with explicit exe call:
+```powershell
+& "D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64.exe" <same arguments>
+```
+
+## Option Summary Reference
+Use `references/godot-cli-commands.md` for categorized option summary and quick recipes based on `godot --help` output.
+
+## Guardrails
+1. Prefer non-interactive commands.
+2. Prefer `--headless` for tests and scripts.
+3. For this environment, include `--log-file` for reproducible logs and to avoid console build logging issues.
+4. Avoid assuming GUT addon exists; check `addons/gut/gut_cmdline.gd` before using GUT command.
+5. Use `--check-only` when user requests parse/syntax validation only.
+6. For long-running runs, include `--quit-after` when appropriate.
+7. Do not classify missing autoload singleton errors in `--script` mode as product regressions until scene/project-context validation is also run.
diff --git a/.claude/skills/godot-cli-test-runner/agents/openai.yaml b/.claude/skills/godot-cli-test-runner/agents/openai.yaml
new file mode 100644
index 0000000..2197703
--- /dev/null
+++ b/.claude/skills/godot-cli-test-runner/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Godot CLI Test Runner"
+  short_description: "Run Godot tests and command-line workflows"
+  default_prompt: "Use this skill to run Godot headless tests with autoload-aware strategy, check CLI options, and execute Godot commands with reproducible --log-file diagnostics."
diff --git a/.claude/skills/godot-cli-test-runner/references/godot-cli-commands.md b/.claude/skills/godot-cli-test-runner/references/godot-cli-commands.md
new file mode 100644
index 0000000..258fc8a
--- /dev/null
+++ b/.claude/skills/godot-cli-test-runner/references/godot-cli-commands.md
@@ -0,0 +1,74 @@
+# Godot CLI Commands Summary
+
+This reference summarizes the provided `godot --help` output for fast command selection.
+
+## 1. Core inspection
+- Help: `godot --help`
+- Version: `godot --version`
+- Verbose logs: `godot --verbose`
+- Quiet mode: `godot --quiet`
+
+## 2. Project targeting and run mode
+- Point to project directory: `godot --path .`
+- Run specific scene: `godot --path . --scene res://scenes/MainScene.tscn`
+- Headless mode: `godot --headless --path . ...`
+- Quit quickly: `godot --path . --quit`
+- Quit after N frames: `godot --path . --quit-after 120`
+
+## 3. Script execution and tests
+- Run script: `godot --headless --path . --script tests/unit/test_xxx.gd`
+- Parse-only script check: `godot --headless --path . --script tests/unit/test_xxx.gd --check-only`
+- Pass custom user args to script:
+`godot --headless --path . --script tests/unit/test_runner.gd -- --case websocket`
+- Autoload-safe smoke test (preferred when test uses singleton globals):
+`godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log`
+
+## 4. Debug and diagnostics
+- Local debugger: `godot --debug --path .`
+- Remote debug: `godot --remote-debug tcp://127.0.0.1:6007 --path .`
+- Print FPS: `godot --path . --print-fps`
+- Log to file: `godot --path . --log-file logs/godot.log`
+- Disable VSync for profiling: `godot --path . --disable-vsync`
+
+## 5. Display and runtime controls
+- Fullscreen: `godot --path . --fullscreen`
+- Windowed: `godot --path . --windowed`
+- Resolution: `godot --path . --resolution 1920x1080`
+- Max FPS: `godot --path . --max-fps 60`
+- Fixed FPS: `godot --path . --fixed-fps 60`
+- Time scale: `godot --path . --time-scale 0.5`
+
+## 6. Export operations (editor build only)
+- Release export:
+`godot --path . --export-release "Web" build/web/index.html`
+- Debug export:
+`godot --path . --export-debug "Web" build/web/index.html`
+- Pack export:
+`godot --path . --export-pack "Web" build/web/game.pck`
+- Check preset syntax only:
+`godot --path . --export-debug "Web" --check-only`
+
+## 7. Common quick recipes
+- Run a unit test script (isolated logic):
+`godot --headless --path . --script tests/unit/test_websocket_close_code.gd --log-file .godot/test_websocket_close_code.log`
+- Validate script syntax without running:
+`godot --headless --path . --script tests/unit/test_websocket_close_code.gd --check-only --log-file .godot/check_websocket.log`
+- Run game with verbose logs:
+`godot --verbose --path . --log-file .godot/main_verbose.log`
+- Run scene and auto-exit after startup checks:
+`godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log`
+
+## 8. Windows explicit executable pattern
+When `godot` is not in PATH, call the executable directly:
+
+```powershell
+& "D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64.exe" --headless --path . --script tests/unit/test_websocket_close_code.gd
+```
+
+## 9. Notes for AI execution
+- Prefer `--headless` for tests and scripts in terminal/CI.
+- Always include `--path .` for reproducibility.
+- Use `--check-only` for parse checks when execution is not needed.
+- If a script depends on autoload singleton names from `project.godot` (`SceneManager`, `LocationManager`, `EventSystem`, etc.), validate in scene/project context before concluding regression.
+- Prefer `--log-file` for reliable diagnostics and environment-specific logging issues.
+- Add `--verbose` when failure context is insufficient.