kurushimee/gdls
GitHub: kurushimee/gdls
用 Rust 忠实移植 Godot 4.6.3 GDScript 前端的独立语言服务器，无需运行 Godot 进程即可提供类型感知的 LSP 诊断与代码导航。
Stars: 1 | Forks: 2
# gdls — 一个独立的 GDScript 语言服务器，适用于 Godot 4.6.3-stable
[](https://github.com/kurushimee/gdls/actions/workflows/ci.yml)
[](LICENSE)
[](rust-toolchain.toml)
[](docs/06-testing-fidelity.md)
一个单一的自包含语言服务器，通过 stdio 为 Claude Code（以及任何 LSP client）提供**具备类型感知能力的 GDScript 诊断和导航** —— **在运行时无需运行任何 Godot 引擎或编辑器进程**。
`gdls` 是对 Godot 4.6.3-stable 的 GDScript 前端（tokenizer → parser → analyzer）的忠实 Rust 移植。它的存在是为了解决在 3,000–10,000+ 个 `.gd` 规模下编辑器 LSP 的笨重、陈旧和引擎耦合问题。仅移植了前端部分 —— compiler/bytecode/VM 的另一半不在范围内（仅提供诊断）。
## 安装
`gdls` 不由 Claude Code 提供；你需要获取发布版本（或自行构建）并将其放在 `PATH` 中。
- **预构建二进制文件** —— 从 [GitHub Releases](https://github.com/kurushimee/gdls/releases) 下载 `gdls`（Linux x86_64）或 `gdls.exe`（Windows x86_64）。
- **从源码构建（cargo）** —— 直接从此仓库构建并将 `gdls` 二进制文件安装到 `~/.cargo/bin`（无需检出代码）：
cargo install --git https://github.com/kurushimee/gdls gd_server
toolchain 由 `rust-toolchain.toml`（stable）固定。
`gdls` 通过 **stdio** 进行 JSON-RPC 通信，因此直接调用 `gdls` 只会在 stdin 上等待 LSP client。要在不连接 client 的情况下对二进制文件进行冒烟测试，可将其索引阶段指向某个项目 —— 它会正常退出并在 stderr 中打印核对摘要：
```
gdls diagnose --reconcile --root /path/to/your/godot/project
```
## 快速开始
1. **向你的 LSP client 注册该服务器**。对于 Claude Code，请从 [`kurushimee/gdls-plugin`](https://github.com/kurushimee/gdls-plugin) 市场安装官方插件 —— 在 Claude Code 会话中执行：
/plugin marketplace add kurushimee/gdls-plugin
/plugin install gdls@gdls-plugin
对于任何其他 LSP client（或手动编写的插件），核心注册仅需五行：
{
"gdscript": {
"command": "gdls",
"extensionToLanguage": { ".gd": "gdscript" }
}
}
2. **原生类型：无需任何操作**（自 v1.0.1 起）。gdls 会查找你的 Godot 二进制文件（`godotBinaryPath` 选项 → `GDLS_GODOT` 环境变量 → `PATH` 上的 `godot4`/`godot`），在项目上下文中运行 `--dump-extension-api-with-docs` —— 这也是捕获项目 GDExtension 类的方式 —— 并将结果管理在 `.gdls/` 目录下，仅当二进制文件或项目的 `.gdextension` 集发生更改时才重新生成。自 v1.0.2 起，dump 操作在后台运行（它绝不会延迟任何请求；会话在 dump 结果落地时会立即重新检查已打开的文件），并且当完全找不到二进制文件时，内置的通用 4.6.3 类表面可确保内建类型（`Node`、`Timer` 等）能被正常解析 —— 不会针对仅存在于你的引擎构建版本中的类编造“unknown type”错误。若要改为固定手动制作的 dump，请设置 `initializationOptions.extensionApiPath`；若要禁止 gdls 启动 Godot，请设置 `autoDumpExtensionApi: false`（或 `GDLS_GODOT=off`）并从项目目录内手动执行 dump：
godot --dump-extension-api-with-docs
更多详情以及多源捕获方案（包括 `doc_classes` XML 后备）请见 [`docs/03-indexing-freshness.md`](docs/03-indexing-freshness.md) §1–§2。
## 配置
该服务器完全通过 LSP 的 `initializationOptions` 进行配置 —— `projectRoot`、自动 dump 对（`godotBinaryPath`、`autoDumpExtensionApi`）、用于固定手动 dump 的 `extensionApiPath`，以及 `strict` 诊断配置（`godot` / `strict` / `off`）和针对每个警告的覆盖设置。完整的 schema 和配置清单示例请见 [`docs/05-lsp-cc-integration.md`](docs/05-lsp-cc-integration.md) §3。
## 架构
- **问题、目标和既定决策** — [`docs/00-overview.md`](docs/00-overview.md)。
- **组件、控制循环和 crate DAG**（`gd_syntax` → `gd_types` → `gd_analyze` / `gd_project` → `gd_server`）— [`docs/01-architecture.md`](docs/01-architecture.md)。
## 状态
**阶段 1 = M0–M6 = v1。已完成。** 两个保真度棘轮均达到 **1.0000**（parser 186/186，analyzer 300/300），基于内置的 Godot 4.6.3-stable 一致性语料库。**M6** 弥补了与 Godot 自带 LSP 相比在暴露能力上的差距（hover 成员签名、对 `class_name`/`preload`/autoloads 的 `definition`/`documentLink`、项目范围的 `references`、分层 `documentSymbol`、`implementation` 覆盖、autoload-singleton 类型推断），并添加了一个持久化、多实例安全的预热启动索引缓存（热重启比冷扫描快 **>5 倍**）。已通过对真实的 Godot 4.6.3 OSS 项目和一个 Windows 原生的 2,338 个脚本的生产项目进行能力验证。
**v1.0.4** 是当前版本 —— 原生表面完整性版本：hover 和 `definition` 现在可用于原生类和成员（声明行的 hover 固定采用 Godot 自带 LSP 的详情格式；`definition` 会跳转到实体化于用户缓存中的可读 API 桩），`workspace/symbol` 锚定 `class_name` 声明而不是第 0 行，analyzer 恢复了上游的 class→native 回落机制，使得 int 类型的原生表面能如实反映类型，而 `UNSAFE_PROPERTY_ACCESS` —— 唯一一个被刻意推迟的警告 —— 现在会触发，并带有来源验证机制，因此在不完整的类表面上绝不会出现误报。在此之前，**v1.0.3** 使得完整的 Godot 警告集得以真正触发（逐个功能移植了 19 个静默代码）并带有精确的 `@warning_ignore` 范围，**v1.0.2** 使首次运行变得稳健（后台自动进行 `extension_api.json` dump，内置通用 4.6.3 后备），而 **v1.0.1** 修复了 v1.0.0 发布后通过全项目诊断扫描暴露出的跨文件误报系列问题。
关于 M6 的范围请参阅 [`docs/08-m6-v1-ship.md`](docs/08-m6-v1-ship.md)，关于里程碑历史请参阅 [`CHANGELOG.md`](CHANGELOG.md)。
阶段 2（v1 之后）是**通用语言服务器阶段** —— 里程碑 **M7–M11**：完整的编辑器级 LSP 表面（completion、signature help、rename、document highlight、type hierarchy、仅使用标准图例的 semantic tokens、inlay hints、code actions、folding/selection 范围、pull diagnostics、cancellation preemption、progress reporting）以及用于 `$`/`%` 的 `.tscn` 节点类型推断，从而使得任何编辑器 —— Helix、VS Code、Neovim、Zed、Emacs、Sublime —— 都能获得完整的功能集，且无需任何 gdls 特定的 client 代码，更不包含 Godot-editor LSP 的自定义协议。（持久化的预热启动索引缓存已提前至 **M6** —— 它是 v1 的门槛。）
完整规范：[`docs/09-phase-2.md`](docs/09-phase-2.md)；路线图表见 [`docs/07-milestones-risks.md`](docs/07-milestones-risks.md)。
## 贡献
欢迎贡献 —— 请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。首先需要了解的一点是*忠实移植原则*：`gdls` 逐个功能地镜像了 Godot 的前端，并与其诊断字节逐字节匹配，因此对上游源码的保真度审查优先于 Rust 惯用法。开发循环即是 CI 把关（`cargo fmt --all --check`、`cargo lint`、`cargo build`、`cargo test`）。
## 许可证
`gdls` 基于 [MIT License](LICENSE) 发布。
它是对 [Godot Engine](https://github.com/godotengine/godot) GDScript 前端的忠实移植，后者同样基于 MIT 许可证；本软件的绝大部分内容派生自 Godot 的源码，且根据该许可证的要求，Godot Engine 的版权声明保留在 [`LICENSE`](LICENSE) 中。
标签：GDScript, Godot, Rust, SOC Prime, 代码分析, 凭证管理, 可视化界面, 开发工具, 网络流量审计, 语言服务器, 通知系统