godot-verify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Godot Verification Skill

Godot 验证技能

Validate Godot project changes using gdlint, gdformat, gdradon, godot export commands, and LSP diagnostics.

使用gdlint、gdformat、gdradon、godot导出命令及LSP诊断工具验证Godot项目变更。

排除规则

不要检查和处理
addons
目录下的任何文件。

addons

目录通常包含第三方插件或外部资源，这些代码不由项目维护，不应纳入项目代码质量检查范围。

不要检查和处理
addons
目录下的任何文件。

addons

目录通常包含第三方插件或外部资源，这些代码不由项目维护，不应纳入项目代码质量检查范围。

检查项

检查	命令/工具	说明
Lint	`gdlint`	Lint GDScript 代码
Format	`gdformat`	格式化/检查格式
Metrics	`gdradon cc`	代码指标分析
Export	`godot --export-pack`	导出验证
LSP Diagnostics	`godot-lsp__diagnostics`	实时语法检查（通过 MCP）

检查	命令/工具	说明
代码检查（Lint）	`gdlint`	检查GDScript代码
格式检查	`gdformat`	格式化/检查代码格式
代码指标	`gdradon cc`	代码指标分析
导出验证	`godot --export-pack`	执行导出验证
LSP诊断	`godot-lsp__diagnostics`	实时语法检查（通过MCP）

gdradon 输出

gdradon cc <path>

输出格式：

F <line>:<col> <function_name> - <grade> (<cc>)

字段	说明
F	函数 (Function)
`<line>:<col>`	行号和列号
`<function_name>`	函数名
`<grade>`	复杂度等级: A(简单), B(中等), C(复杂), D(非常复杂), F(极复杂)
`<cc>`	圈复杂度数值

示例：

.\character_body_2d.gd
    F 13:0 _physics_process - C (15)

gdradon cc <path>

输出格式：

F <line>:<col> <function_name> - <grade> (<cc>)

字段	说明
F	函数 (Function)
`<line>:<col>`	行号和列号
`<function_name>`	函数名
`<grade>`	复杂度等级: A(简单), B(中等), C(复杂), D(非常复杂), F(极复杂)
`<cc>`	圈复杂度数值

示例：

.\character_body_2d.gd
    F 13:0 _physics_process - C (15)

使用示例

bash

undefined

bash

undefined

Lint 检查

gdlint "D:/project/scripts/Player.gd"

Format 检查

gdformat --check "D:/project/scripts/Player.gd"

代码指标

gdradon cc D:/project/scripts/

LSP 诊断（DiagnosticsServer 为开机自启动服务）

调用 MCP 工具获取诊断（只需 uri 参数）

godot-lsp__diagnostics(uri="file:///D:/project/game/player.gd")

LSP 诊断（修改代码后使用 refresh=true）

godot-lsp__diagnostics(uri="file:///D:/project/game/player.gd", refresh=true)

完整检查

gdlint D:/project/scripts/ && gdformat D:/project/scripts/ && gdradon cc D:/project/scripts/

导出验证

godot --headless --path "D:/project" --export-pack "Web" "D:/export.pck"

undefined

godot --headless --path "D:/project" --export-pack "Web" "D:/export.pck"

undefined

LSP Diagnostics

Godot LSP 诊断提供实时的语法检查和错误检测，与 Godot 编辑器显示的诊断一致。

前置条件

Godot 编辑器运行（Godot LSP 服务器在编辑器启动时自动开启，默认端口 6005）
DiagnosticsServer 运行（开机自启动服务，提供诊断缓存）

Godot 编辑器运行（Godot LSP 服务器在编辑器启动时自动开启，默认端口 6005）
DiagnosticsServer 运行（开机自启动服务，提供诊断缓存）

MCP 工具调用

工具名:

godot-lsp__diagnostics

参数:

uri

(必需):

file://

URI，例如

file:///D:/project/game/player.gd

```
refresh
```
(可选): 是否强制刷新诊断缓存，默认 false

json

{
  "uri": "file:///D:/project/game/player.gd",
  "diagnostics": [
    {
      "range": { "start": { "line": 4, "character": 0 }, "end": { "line": 4, "character": 56 } },
      "severity": 2,
      "code": 9,
      "source": "gdscript",
      "message": "(SHADOWED_GLOBAL_IDENTIFIER): The constant \"AttackType\" has the same name as a global class..."
    }
  ],
  "cached": false  // true 表示从缓存返回，false 表示新打开文件
}

说明:

DiagnosticsServer 会自动读取文件内容，无需传递
```
text
```
参数
首次查询会打开文件并等待诊断（约 500ms）
后续查询直接从缓存返回，速度更快
修改代码后推荐使用
refresh=true
强制刷新缓存，确保获取最新诊断结果

工具名:

godot-lsp__diagnostics

参数:

uri

(必需):

file://

URI，例如

file:///D:/project/game/player.gd

```
refresh
```
(可选): 是否强制刷新诊断缓存，默认 false

json

{
  "uri": "file:///D:/project/game/player.gd",
  "diagnostics": [
    {
      "range": { "start": { "line": 4, "character": 0 }, "end": { "line": 4, "character": 56 } },
      "severity": 2,
      "code": 9,
      "source": "gdscript",
      "message": "(SHADOWED_GLOBAL_IDENTIFIER): The constant \"AttackType\" has the same name as a global class..."
    }
  ],
  "cached": false  // true 表示从缓存返回，false 表示新打开文件
}

说明:

DiagnosticsServer 会自动读取文件内容，无需传递
```
text
```
参数
首次查询会打开文件并等待诊断（约 500ms）
后续查询直接从缓存返回，速度更快
修改代码后推荐使用
refresh=true
强制刷新缓存，确保获取最新诊断结果

诊断级别 (severity)

级别	值	说明
Error	1	错误，必须修复
Warning	2	警告，建议修复
Information	3	信息
Hint	4	提示

级别	值	说明
错误	1	错误，必须修复
警告	2	警告，建议修复
信息	3	信息提示
提示	4	优化提示

常见诊断代码

代码	消息	说明
1	`PARSER_ERROR`	语法错误
9	`SHADOWED_GLOBAL_IDENTIFIER`	常量名与全局类冲突
12	`STATIC_VARIABLE_TYPE_MISMATCH`	静态变量类型不匹配
21	`RETURN_VALUE_DISCARDED`	返回值未使用
30	`UNSAFE_CALL`	不安全的函数调用
40	`UNASSIGNED_VARIABLE_ACCESS`	访问未赋值的变量

代码	消息	说明
1	`PARSER_ERROR`	语法错误
9	`SHADOWED_GLOBAL_IDENTIFIER`	常量名与全局类冲突
12	`STATIC_VARIABLE_TYPE_MISMATCH`	静态变量类型不匹配
21	`RETURN_VALUE_DISCARDED`	返回值未使用
30	`UNSAFE_CALL`	不安全的函数调用
40	`UNASSIGNED_VARIABLE_ACCESS`	访问未赋值的变量

HTTP API（直接访问 DiagnosticsServer）

bash

undefined

bash

undefined

获取诊断

curl "http://127.0.0.1:3457/diagnostics?path=D:/project/game/player.gd"

刷新诊断

curl -X POST "http://127.0.0.1:3457/refresh" -d "{"path":"D:/project/game/player.gd"}"

查看状态

curl "http://127.0.0.1:3457/stats"

undefined

curl "http://127.0.0.1:3457/stats"

undefined

与 gdlint 对比

特性	LSP Diagnostics	gdlint
实时性	实时（缓存）	需要运行
错误类型	语法 + 语义	Lint 规则
与编辑器一致	完全一致	可能不同
速度	快（有缓存）	慢（需解析）
需要 Godot	是	否

建议: 使用 LSP Diagnostics 作为快速检查，gdlint 作为补充 lint 规则检查。

特性	LSP Diagnostics	gdlint
实时性	实时（缓存）	需要手动运行
错误类型	语法 + 语义错误	Lint规则检查
与编辑器一致性	完全一致	可能存在差异
速度	快（带缓存）	慢（需重新解析）
是否需要Godot	是	否

建议: 使用 LSP Diagnostics 作为快速检查工具，gdlint 作为补充的Lint规则检查工具。

Lint Rules (gdlint)

Rule	Severity	Description
`unused-variable`	Error	Variable declared but never used
`shadowed-variable`	Error	Variable shadows member variable
`function-name`	Error	Function name violates naming convention
`constant-name`	Error	Constant name violates naming convention
`trailing-whitespace`	Warning	Lines have trailing whitespace
`missing-docstring`	Warning	Function missing documentation
`line-too-long`	Warning	Line exceeds 120 characters

规则	级别	描述
`unused-variable`	错误	变量已声明但从未使用
`shadowed-variable`	错误	变量遮蔽了成员变量
`function-name`	错误	函数名违反命名规范
`constant-name`	错误	常量名违反命名规范
`trailing-whitespace`	警告	行尾存在空格
`missing-docstring`	警告	函数缺少文档注释
`line-too-long`	警告	行长度超过120字符

Error Handling

错误处理

Error	Solution
`No project.godot found`	Navigate to project root or provide absolute path
`gdlint not found`	Install: `pip install gdtoolkit`
`gdradon not found`	Install: `pip install gdradon`
`godot not found`	Add godot to PATH
`Path must be absolute`	Convert relative to absolute paths

错误	解决方案
`No project.godot found`	切换到项目根目录或提供绝对路径
`gdlint not found`	安装： `pip install gdtoolkit`
`gdradon not found`	安装： `pip install gdradon`
`godot not found`	将godot添加到系统PATH中
`Path must be absolute`	将相对路径转换为绝对路径

Common Workflows

常见工作流

After Code Changes

代码修改后

bash

gdlint "D:/project/scripts/Player.gd"

bash

gdlint "D:/project/scripts/Player.gd"

Pre-commit Validation

提交前验证

bash

gdlint D:/project/scripts/ && gdformat D:/project/scripts/

bash

gdlint D:/project/scripts/ && gdformat D:/project/scripts/

Code Metrics Analysis

代码指标分析

bash

gdradon cc D:/project/scripts/

输出示例：

.\character_body_2d.gd
    F 13:0 _physics_process - C (15)

bash

gdradon cc D:/project/scripts/

输出示例：

.\character_body_2d.gd
    F 13:0 _physics_process - C (15)

Export Validation

导出验证

bash

godot --headless --path "D:/project" --export-pack "Web" "D:/export.pck"

bash

godot --headless --path "D:/project" --export-pack "Web" "D:/export.pck"

安装要求

```
pip install gdtoolkit
```
(gdlint, gdformat)
```
pip install gdradon
```
(code metrics)
```
godot
```
in PATH (export validation)

```
pip install gdtoolkit
```
(gdlint, gdformat)
```
pip install gdradon
```
(代码指标)
```
godot
```
已添加到PATH（导出验证）

Tips

提示

Use
```
file
```
param to check only changed files (faster)
```
gdformat --check
```
shows what would change without modifying
```
gdradon cc
```
shows complexity and maintainability metrics
Export validation catches dependency issues lint misses

使用
```
file
```
参数仅检查变更的文件（速度更快）
```
gdformat --check
```
会显示将进行的格式修改但不实际更改文件
```
gdradon cc
```
会显示代码复杂度及可维护性指标
导出验证能发现Lint工具无法检测到的依赖问题