Asteroid.GodotCli 0.3.0

Asteroid Godot CLI

Asteroid Godot CLI 是一个 .NET 工具，用于在调试和场景脚本验证过程中观察并驱动 Godot 项目。它会在目标项目中安装一个小型 Runtime 集成，以 localhost 运行时服务器的方式启动 Godot，并通过 godot-cli 命令暴露一组受控的运行时工具。

该工具面向 agent 辅助工作流和本地调试设计。它不暴露任意反射、任意方法调用、属性写入或脚本求值。运行时操作仅限于已注册的工具方法。本目录属于 Asteroid Framework Develop 开发仓，完整手册见仓内 docs/GodotCli.md。

包

• CLI dotnet 工具：Asteroid.GodotCli
• Godot C# 运行时包：Asteroid.GodotCli.Runtime
• CLI 包版本：0.2.0
• Godot C# 运行时包版本：0.2.0
• NuGet 源：nuget.org（官方源）

安装

从 nuget.org 安装 CLI：

dotnet tool install --global Asteroid.GodotCli --version 0.2.0

更新已有安装：

dotnet tool update --global Asteroid.GodotCli --version 0.2.0

初始化 Godot 项目

C# 是默认的 Runtime 集成方式。目标项目必须是使用 Godot.NET.Sdk 的 Godot C# 项目。

godot-cli init --project <godot-project> --dry-run
godot-cli init --project <godot-project>
godot-cli init status --project <godot-project>

init 会添加 Asteroid.GodotCli.Runtime，写入生成的 GodotCli/GodotCliAutoload.cs 桥接文件，并启用 project.godot 中的 Autoload 条目。

lifecycle 命令：

godot-cli init upgrade --project <godot-project>
godot-cli init disable --project <godot-project>
godot-cli init remove --project <godot-project>

基本用法

设置 GODOT_BIN 或传入 --godot-bin，CLI 才能启动 Godot 4.7 Mono。

godot-cli doctor --project <godot-project>
godot-cli session oneshot tree --project <godot-project> --scene res://Main.tscn
godot-cli session oneshot screenshot --project <godot-project> --scene res://Main.tscn
godot-cli scenario run <scenario.json> --project <godot-project> --scene res://Main.tscn --cache-dir <cache-dir>

probe 仍可作为 session oneshot 命令的兼容 shortcut 使用。

当多条命令需要复用同一个 Godot 进程时，可以使用长时间运行的会话：

godot-cli session start --project <godot-project> --scene res://Main.tscn --cache-dir <cache-dir>
godot-cli session tree <session-id>
godot-cli session stop <session-id>
godot-cli session cleanup --cache-dir <cache-dir>

工件安全

CLI 会在缓存目录下写入运行时日志、request/response JSONL 文件、场景脚本摘要和截图。token 字段和受控文本输入会做脱敏，但普通 UI 文本、日志和截图仍可能包含敏感的项目数据。

在把工件发送给他人或其他系统之前，请使用以下分享流程：

godot-cli session cleanup --cache-dir <cache-dir>
godot-cli artifacts inspect <artifact-or-cache-dir> --deny <sensitive-value>
godot-cli artifacts scrub <artifact-or-cache-dir> --output <safe-dir> --deny <sensitive-value>
godot-cli artifacts inspect <safe-dir> --deny <sensitive-value>

artifacts scrub 会生成脱敏副本，且绝不修改源目录。文本工件会被扫描并脱敏。.token 文件不会复制。PNG/JPG/WebP 截图和其他二进制文件会原样复制，分享前必须人工复查。

自定义运行时工具

生成的桥接文件包含一个 partial 钩子：

partial void RegisterTools(GodotCliToolRegistry tools);

在生成的桥接文件旁用单独的 partial 文件添加项目专属工具。工具必须通过运行时注册表显式注册，之后即可通过 tool.list、tools export 和场景脚本 lint 发现。

当前限制

• 公开的 Runtime 支持目前只面向 Godot C# 项目。
• GDScript Runtime 支持属于内部实验特性，尚不是公开的安装路径。
• UI 自动化聚焦于 root viewport 下的 Control 工作流。
• JSONPath 支持刻意保持精简：仅支持简单对象路径和数组下标。
• artifacts scrub 不会对截图像素做脱敏。
• 默认 CI 路径刻意保持轻量；依赖 Godot 的验证由冒烟测试脚本承担。

开发验证

在本仓库中执行：

dotnet test ../../tests/Managed/Asteroid.GodotCli.Tests/Asteroid.GodotCli.Tests.csproj
powershell -ExecutionPolicy Bypass -File scripts/verify-godot-cli.ps1
powershell -ExecutionPolicy Bypass -File scripts/verify-gdscript-runtime.ps1
powershell -ExecutionPolicy Bypass -File scripts/verify-runtime-package-consumer.ps1

依赖 Godot 的脚本需要 Godot 4.7 Mono，并设置 GODOT_BIN 或传入 -GodotBin。verify-godot-cli.ps1 覆盖公开的 C# Runtime 冒烟测试路径；verify-gdscript-runtime.ps1 覆盖内部实验性的 GDScript addon 冒烟测试路径。