godot-cli

Godot CLI

仅使用 CLI 作为连接 Godot 的桥梁。不要读取会话文件、建立原始 TCP 连接、暴露令牌，也不要虚构不受支持的工具。

选择可执行文件

在 Godot 项目根目录中，按以下顺序选择 CLI：

$cliCandidates = @(
  '.\target\x86_64-pc-windows-msvc\release\godot-cli.exe'
  '.\.godot-cli\bin\godot-cli.exe'
)
$cli = $cliCandidates |
  Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } |
  Select-Object -First 1

if ([string]::IsNullOrWhiteSpace($cli)) {
  $command = Get-Command godot-cli -ErrorAction SilentlyContinue
  if ($null -ne $command) {
	$cli = $command.Source
  }
}

优先使用仓库的 release 构建，其次使用便携安装包中的 EXE，最后使用 PATH 中的 godot-cli。如果三者都不存在，停止操作并说明必须先构建或安装 CLI；不要修改系统 PATH。后续命令始终通过 & $cli 调用选中的可执行文件。

开始每个工作流

保持 Godot 编辑器处于打开状态并启用插件。使用结构化输出，并明确选择项目：

& $cli --json --project . doctor

将非零退出码和 "ok": false 视为失败。日志应输出到 stderr；只解析 stdout 中唯一的 JSON 对象。

读取编辑器状态

使用作用域最小的领域命令：

& $cli --json --project . project info
& $cli --json --project . scene current
& $cli --json --project . scene tree --depth 4 --max-nodes 500
& $cli --json --project . scene list-project
& $cli --json --project . scene list-open
& $cli --json --project . resource list --extension png,svg
& $cli --json --project . resource inspect res://game/assets/player.png
& $cli --json --project . class search-nodes camera --base-type Node3D
& $cli --json --project . class api Node2D --section properties --filter position
& $cli --json --project . node list . --group actors --limit 200
& $cli --json --project . node groups get Player
& $cli --json --project . node signals get Player --signal health_changed
& $cli --json --project . node get Player --fields visible,process_mode

契约未知时，在使用通用 tool-call 前先使用 tools list、tools search 和 tools schema。通过 --args-json 或 --args-file 以对象形式传递通用参数。绝不要把 apply 放入该对象。

安全创建本地节点

只有在用户明确批准具体父路径、类型和名称后才能创建节点。

1. 读取当前场景，并用 node list 核验父节点、owner 边界和同级名称。
2. 必要时先用 class search-nodes 确认精确的运行时 ClassDB 节点类型。
3. 调用 node create，单独传入 --apply。
4. 再次用 node list 核验路径、类型、父路径、owner_path="." 和 editable=true，并检查 scene current。
5. 报告节点已进入 UndoRedo、场景仍未保存且磁盘没有被隐式修改。