编辑器与 LSP

Riddle 通过 riddle-lsp 为编辑器提供实时诊断、自动导入补全、语义高亮、悬停信息、签名帮助、代码跳转、调用与类型层级、查找引用、重命名、符号导航、格式化和代码折叠。当前仓库提供 Helix、VS Code、Zed 和 IntelliJ IDEA 2026.1+ 的适配文件。

准备 riddle-lsp

先按照安装 Riddle 工具链完成安装，并确认编辑器启动时能找到服务器：

riddle-lsp --version

如果命令不可用，请把 Riddle 二进制目录加入 PATH，或在支持路径设置的编辑器中填写 riddle-lsp 的绝对路径。JetBrains 插件当前固定从 IDE 进程的 PATH 启动服务器。四个适配都会识别 .rid 文件；服务器会发现每个工作区文件夹内的 Clue 项目，加载项目模块和本地依赖，并为未打开文件建立内存索引。

打包编辑器扩展

在仓库根目录运行 PowerShell 或 Bash 脚本：

pwsh -File editors\package.ps1

bash editors/package.sh

脚本需要 Node.js、npm、JDK 25 或更高版本和网络连接，Bash 版本还需要 zip 命令。首次构建 JetBrains 插件时，Gradle wrapper 会下载 Gradle 9 和 IntelliJ Platform 2026.1 SDK。脚本会在 editors/dist 中生成：

文件	用途
`riddle-vscode.vsix`	直接导入 VS Code
`riddle-intellij.zip`	从磁盘安装到受支持的 JetBrains IDE
`riddle-helix.zip`	解压后合并到 Helix 配置目录
`riddle-zed.zip`	解压后作为 Zed Dev Extension 导入

JetBrains ZIP 和 VSIX 可以直接安装。Helix 和 Zed 的 ZIP 只负责分发所需文件；导入方式见下文。

Helix

解压 editors/dist/riddle-helix.zip。压缩包内容与仓库中的 editors/helix 相同：

editors/helix/
├── languages.toml
└── runtime/queries/riddle/

把解压目录中 languages.toml 的两个配置块合并到 Helix 配置目录的 languages.toml。已有文件时不要直接覆盖。
把解压目录中的 runtime/queries/riddle 复制到 Helix 配置目录的 runtime/queries/riddle。
重新启动 Helix。

Helix 配置目录通常是：

平台	路径
Linux / macOS	`~/.config/helix`
Windows	`%AppData%\helix`

直接从仓库导入时，查询文件可以这样复制：

mkdir -p ~/.config/helix/runtime/queries/riddle
cp editors/helix/runtime/queries/riddle/*.scm ~/.config/helix/runtime/queries/riddle/

PowerShell：

$queries = Join-Path $env:APPDATA "helix\runtime\queries\riddle"
New-Item -ItemType Directory -Force $queries | Out-Null
Copy-Item editors\helix\runtime\queries\riddle\*.scm $queries

默认配置从 PATH 启动服务器。需要指定路径或参数时，修改合并后的服务器配置：

[language-server.riddle-lsp]
command = "/path/to/riddle-lsp"
args = ["--no-std"]

补全默认立即响应。需要在持续输入时合并请求，可追加 --completion-delay-ms，单位为毫秒：

args = ["--completion-delay-ms", "25"]

检查安装结果：

hx --health riddle

riddle-lsp、Tree-sitter parser、Highlight queries、Textobject queries 和 Indent queries 都应显示可用。

VS Code

VS Code 适配包含 .rid 文件注册、基础 TextMate 高亮和 LSP 客户端。当前尚未发布到 Marketplace，需要安装本地 VSIX。

命令行安装打包脚本生成的扩展：

code --install-extension editors\dist\riddle-vscode.vsix

也可以打开扩展面板，在右上角 ... 菜单中选择 Install from VSIX…，然后选择 riddle-vscode.vsix。

安装完成后重新打开 .rid 文件。右下角的语言模式应显示 Riddle。

扩展默认从 PATH 启动 riddle-lsp。可以在 settings.json 中覆盖路径和参数：

{
    "riddle.server.path": "/path/to/riddle-lsp",
    "riddle.server.arguments": ["--completion-delay-ms", "25"]
}

Windows 路径中的反斜杠需要转义：

{
    "riddle.server.path": "C:\\tools\\riddle\\riddle-lsp.exe"
}

修改服务器路径或参数后，执行 Developer: Reload Window 重新启动扩展。

IntelliJ IDEA

插件使用 IntelliJ Platform 2026.1 的 LSP integration API，源码全部为 Kotlin。IntelliJ IDEA 2026.1 及更高版本可用；Android Studio 不在当前支持范围内。

打开 Settings | Plugins。
点击齿轮菜单，选择 Install Plugin from Disk…。
选择 editors/dist/riddle-intellij.zip，然后重新启动 IDE。
打开 .rid 文件，确认文件类型显示为 Riddle，并检查诊断、补全和语义高亮。

插件不向 riddle-lsp 传递额外参数，并固定从 IDE 进程的 PATH 查找命令。修改系统 PATH 后需要完全退出并重新启动 IDE。JetBrains 适配没有 TextMate 或 Tree-sitter 回退；没有启动 LSP 时不会出现 Riddle 语义高亮。

只构建这个插件时，可以运行：

Set-Location editors\intellij
.\gradlew.bat buildPlugin

生成的版本化 ZIP 位于 editors/intellij/build/distributions。

Zed

Zed 适配当前以 Dev Extension 方式安装。先把 riddle-zed.zip 解压到固定目录，并确认该目录顶层包含 extension.toml，然后：

在命令面板运行 zed: extensions。
选择 Install Dev Extension。
选择刚才解压的目录；直接从仓库导入时选择 editors/zed。
重新打开 .rid 文件，并确认语言模式为 Riddle。

扩展默认从工作树的 PATH 查找 riddle-lsp。也可以在 Zed 的 settings.json 中指定路径、参数，并启用完整语义 Token：

{
    "languages": {
        "Riddle": {
            "semantic_tokens": "full"
        }
    },
    "lsp": {
        "riddle-lsp": {
            "binary": {
                "path": "/path/to/riddle-lsp",
                "arguments": ["--completion-delay-ms", "25"]
            }
        }
    }
}

修改配置后，在命令面板运行 language server: restart。Zed 和 Helix 当前复用 Rust Tree-sitter grammar 作为结构化回退；Riddle 专用的标识符分类由 riddle-lsp 语义 Token 提供。

当前能力

能力	状态
`.rid` 文件识别	Helix、VS Code、Zed、JetBrains 均支持
Clue 项目、未保存文件和未打开模块诊断	支持
多工作区 Clue 项目发现、内存索引和按文件失效	支持
解析、类型、move/borrow 诊断	支持
Clue 项目级函数、方法、struct、enum、trait、参数和可变绑定语义高亮	支持
跨模块返回类型和调用参数名 Inlay Hint	支持
Clue 项目中的关键字、类型、全局项、局部变量、模式绑定和导入别名补全	支持
字段、实例方法、模块项、枚举变体和关联函数补全	支持
诊断驱动的快速修复（加 `mut`、补缺失字段、补 match 分支、删除空 `use`、`drop` 重写、名字纠错与自动导入）及 `source.organizeImports`	支持
跨文件补全（包含已打开文件的未保存内容）	支持
公开符号自动导入、重名路径区分和确定性排序	支持
函数签名、推断类型和 struct/enum 声明 Hover（最多 5 个顶层字段或变体，枚举 payload 完整）；方法调用显示实例化后的签名（替换过的接收者与返回类型）	支持
内联提示：`let` 绑定推断类型、lambda 参数推断类型、多行链式调用每级结果类型、调用参数名	支持
impl 块内补全缺失的 trait 方法（携带签名的 snippet）与关联类型	支持
结构化选择范围（selectionRange）、`mod` 声明的模块文件链接、pull 诊断	支持
`Clue.toml` 清单：未知键/类型/semver/依赖规则诊断（CLUE0002–CLUE0004）、节与键补全、键悬停、节与键符号	支持
跳转定义（包含未打开的 Clue 模块）	支持
跳转声明与跳转类型定义	支持
trait 与 trait 方法的跳转实现	支持
静态调用层级与 trait/实现类型层级	支持
项目级查找引用与重命名（包含未保存文件、未打开模块、字段、trait 方法和导入别名）	支持
签名帮助与当前参数跟踪	支持
文档符号与工作区符号搜索	支持
文档引用高亮与代码折叠	支持
增量文档同步、过期分析取消与 Semantic Token delta	支持
编辑器外部 `.rid` 与 `Clue.toml` 文件变更	支持动态监听
格式化	支持

工作区中的 Clue 项目会建立内存索引。补全可通过独立的 use path; 编辑自动导入可达的公开符号；调用层级只包含编译器能够静态解析的目标，不推测函数指针、闭包或 Trait 的运行时分派。

The Riddle Book

编辑器与 LSP

准备 riddle-lsp

打包编辑器扩展

Helix

VS Code

IntelliJ IDEA

Zed

当前能力

常见问题

编辑器提示找不到 riddle-lsp

Helix 没有高亮或缩进查询

Zed 只有基础语法颜色

VS Code 有基础高亮但没有诊断

JetBrains 中没有诊断或高亮

如果上述的一切都不起作用？

Keyboard shortcuts

The Riddle Book