LSP 客户端矩阵
Nudo 只交付一个语言服务器(@nudojs/lsp)。编辑器差异仅在如何启动它、以及客户端侧打开了哪些能力。本页是对齐表:服务器提供什么、各客户端如何消费、缺口在哪里。
服务器按设计与 tsserver / vtsls 并存,而不是替代它们。
Known gaps / 哪些限制在客户端侧(先读)
诚实定位。 产品门禁是 nudo check --json 加上 Agent/MCP 工具。IDE 是跑在同一服务器上的尽力而为观察面——不是门禁。服务器能力绝不会为了迁就更弱的客户端而降级;下面几乎每条缺口都是客户端 UI 或客户端配置。
| 客户端 | 角色 | 预期 |
|---|---|---|
VS Code(wmzy.nudo-vscode) | 旗舰 IDE 客户端 | 完整功能面:hover、CodeLens contract 档 + case 切换、inlay hints、装饰、agent 桥 |
| Zed | 尽力而为 | 核心面可用(diagnostics / hover / rename)。CodeLens 需 code_lens: "on";无 active-case 装饰 API |
| Helix | 尽力而为 | Diagnostics / hover / definition / rename。无 CodeLens UI——同一数据请用 CLI nudo contract / nudo check |
| Neovim | 尽力而为 | 核心面可用;CodeLens / semantic tokens / 装饰取决于插件 |
| 通用 stdio / agent 桥 | 协议 | workspace/executeCommand + nudo/… 自定义请求始终可用 |
缺口主题(完整表与 workaround 见下;跟踪 ID 在设计源 docs/design/lsp-client-gaps.md):
| 主题 | ID | 谁会碰到 |
|---|---|---|
| Active-case 装饰 | LSP-G1 | VS Code 已闭(函数体 + case 行装饰)。Zed / Neovim / Helix 仍开(客户端无装饰 API,或需要插件) |
| CodeLens 不渲染 | LSP-G2 | Helix / 极简 Neovim — 观察面由 inlay 覆盖 ● contract / hw|gen|imp(与 CodeLens 同源)。CodeLens UI 本身仍是客户端限制 |
| Semantic tokens 默认关闭 | LSP-G3 | VS Code 可染色(semanticTokenScopes)。Zed / Neovim / Helix:按 Setup 说明打开 |
| 与 tsserver 并存的次要服务器噪音 | LSP-G4 | 所有客户端(配置:nudo.analysis.include / exclude,或 mode: "directives")。VS Code:命令 Nudo: Apply coexistence settings |
| Pull diagnostics 未被使用 | LSP-G6 | 较老客户端 — push 面已钉(validateText 必 publish);pull 是增强 |
| 补全 / signature help UI 太薄 | LSP-G7 | 服务端:真实 paramTypes / 返回 + @nudo: 指令补全(@ 触发)。Helix UI 仍视构建 |
经验法则: 如果协议提供了、编辑器却画不出来,那是客户端限制——退回 nudo check / nudo contract 或 agent 工具。服务器端语义在各编辑器间保持一致。
服务器能力
在 initialize 时声明(详见 @nudojs/lsp API):
| 能力 | 服务器 handler | 说明 |
|---|---|---|
| Diagnostics | validateText(push)+ diagnosticProvider(pull) | 自适应防抖 300/400/800 ms;过期 generation 可取消(A8);pull 仅在 version + casesHash + depsHash 全匹配时命中缓存 |
| Hover | onHover | Abs / intension;导出函数名首行 ● contract / hw|gen|imp(A7) |
补全(.) | onCompletion | 按推断类型给出 property/method |
| CodeLens | onCodeLens | 观察选择器:●/○ contract / hw|gen|imp(默认激活)+ persist/update;●/○ case "…" 选项跟随(nudo.selectCase / nudo.selectContract) |
| Inlay hints | languages.inlayHint | case 提示 + Abs 参数/返回(implicit 导出标 derived) |
| 跳转定义 / 引用 / 重命名 | 标准 LSP | 含侧车绑定名(A5) |
| 文档 / 工作区符号 | 标准 LSP | |
| Signature help | onSignatureHelp | 触发 (、,;投影真实 paramTypes / 返回(G7) |
Code actions(quickfix) | onCodeAction | 不可达代码清理;契约/参数修复(A6);action-map quickfix([fix] / [silence] / [review] / [adjust] / [scaffold]) |
| Semantic tokens(full) | languages.semanticTokens | 图例含 contract / generated / derived contract modifier(A7) |
| Execute command | nudo.* | selectCase、contract、contract.draft、contract.emit、agent 工具 |
| Custom request | nudo/… | 与 command 同一 handler(E5);协议契约用 slash 形式 |
| Pull diagnostics | diagnosticProvider | interFileDependencies: false |
文件检测(A1/A2): 目标为 .js / .mjs / .ts。出厂默认 nudo.analysis.mode = "exports" — 完整门禁语义:共存。CodeLens contract 档使用更宽的目标路径——诊断可对无指令文件保持安静,档位仍可见。
Zed / Nvim 协议冒烟(B4): pnpm --filter @nudojs/lsp run smoke 走一遍 stdio initialize → textDocument/hover → textDocument/publishDiagnostics——正是这些编辑器需要的基本面。VS Code 包有自带的 smoke(捆绑 server + initialize)。
客户端支持矩阵
图例:Y = 原生客户端 + 本服务器即可 · C = 需要设置 / 次要 language server · N = 客户端 UI 不提供(服务器仍响应协议) · — = 不适用
| 能力 | VS Code(nudo-vscode) | Zed(nudo-zed) | Neovim(nvim-lspconfig) | Helix | 通用 stdio LSP |
|---|---|---|---|---|---|
| 启动 | 扩展捆绑 server.js(IPC) | Zed 托管 npm(@nudojs/lsp → node …/server.js --stdio) | cmd = nudo-lsp | command = nudo-lsp | 启动 nudo-lsp 或 node dist/server.js |
| Diagnostics | Y | Y | Y | Y | Y |
| Hover(Abs + contract 档) | Y | Y | Y | Y | Y |
| 补全 | Y | Y | Y | C | Y |
| CodeLens contract + case | Y | C(code_lens: "on") | C(插件因实现而异) | N | C(视客户端) |
| Inlay hints | Y | C(inlay_hints.enabled) | C | C | C |
| 定义 / 引用 / 重命名 | Y | Y | Y | Y | Y |
| 文档符号 | Y | Y | Y | Y | Y |
| Signature help | Y | Y | Y | C | Y |
| Code actions / Quickfix | Y | Y | Y | Y | C |
| Code actions — extract / inline var / change signature | Y | Y | Y | Y | C |
| Semantic tokens | Y | C(semantic_tokens: "combined") | C | C | C |
| Active-case 装饰 | Y(扩展) | N | N | N | N |
Agent 命令(nudo.check / nudo.hover / …) | Y(executeCommand / MCP 桥) | Y(agent / custom request) | Y(custom LSP request) | C | Y |
| 未保存侧车 buffer(A4) | Y | Y | Y | Y | Y |
| buffer 感知的 contract agent 工具(E5) | Y | Y | Y | Y | Y |
配置要点(复制即用默认配置)
安装 @nudojs/lsp,让 nudo-lsp 在 PATH 上(项目内 npm i -D @nudojs/lsp 或全局安装)。冻结清单见 packages/lsp/PUBLIC_API.md / API。下面每个配置块都是推荐的默认配置——可整块复制;每个键都在对应客户端页有文档。
VS Code
安装 wmzy.nudo-vscode。扩展捆绑服务器并注册 nudo.selectCase。见 VS Code 扩展(含发布检查清单)。
Zed — 复制即用默认配置
- 从扩展市场安装 nudojs/nudo-zed(或以 dev extension 安装)。扩展会通过 Zed 托管 npm 自动安装
@nudojs/lsp,无需在package.json里固定版本。 ~/.config/zed/settings.json(或项目.zed/settings.json):
{
"languages": {
"JavaScript": {
"language_servers": ["vtsls", "nudo", "..."]
},
"TypeScript": {
"language_servers": ["vtsls", "nudo", "..."]
}
},
"code_lens": "on",
"inlay_hints": { "enabled": true },
"semantic_tokens": "combined"
}
"..." 会保留其余已注册 language server;code_lens / inlay_hints 打开 CodeLens 选择器与 case 提示;semantic_tokens: "combined" 把服务器的 contract / generated / derived modifier 叠加到语法高亮上。可选 binary 覆盖(跳过托管安装):"lsp": { "nudo": { "binary": { "path": "nudo-lsp", "arguments": [] } } }。详见 Zed 扩展。
Neovim — 复制即用默认配置
lazy.nvim + nvim-lspconfig(下列为 Neovim 0.11+ vim.lsp.config;旧版用下方 require("lspconfig").nudo.setup{…})。整块即为完整默认配置:
-- 已安装 @nudojs/lsp,nudo-lsp 在 PATH 上
vim.lsp.config("nudo", {
cmd = { "nudo-lsp" },
filetypes = { "javascript", "javascriptreact", "typescript", "typescriptreact" },
root_markers = { "package.json", ".git" },
})
vim.lsp.enable("nudo")
-- inlay hints(内置)
vim.lsp.inlay_hint.enable(true, { bufnr = 0 })
-- 可选:CodeLens UI 插件(glance / nvim-code-action-menu 等)
无编辑器也能做的基本面检查:pnpm --filter @nudojs/lsp run smoke(stdio 上的 hover + push diagnostics)。
旧版 lspconfig:
require("lspconfig").nudo.setup({
cmd = { "nudo-lsp" }, -- 或 { "node", "node_modules/@nudojs/lsp/dist/server.js" }
filetypes = { "javascript", "javascriptreact", "typescript", "typescriptreact" },
root_dir = require("lspconfig").util.root_pattern("package.json", ".git"),
})
Agent 命令示例:
vim.lsp.buf.execute_command({
command = "nudo.check",
arguments = { { file = vim.api.nvim_buf_get_name(0) } },
})
Custom request(slash 形式是协议契约):
vim.lsp.buf_request(0, "nudo/check", { file = vim.api.nvim_buf_get_name(0) }, function(err, result) end)
Helix — 复制即用默认配置
~/.config/helix/languages.toml(含 javascript / typescript 两个块——整块复制):
[language-server.nudo]
command = "nudo-lsp"
# args = ["--stdio"] # 可选;无 transport 参数时 server 默认 stdio
[[language]]
name = "javascript"
language-servers = [ "vtsls", "nudo" ]
[[language]]
name = "typescript"
language-servers = [ "vtsls", "nudo" ]
Helix 渲染诊断 / hover / 定义 / 重命名。UI 无 CodeLens——用 CLI nudo contract / nudo check 拿同一数据。Signature help 视 Helix 版本而定;缺失时用 CLI / agent 工具。
通用 / agent 桥
任意 LSP 客户端可 workspace/executeCommand 或发送 nudo/<tool> custom request。slash 形式(nudo/check)是协议契约;dot 形式(nudo.check)对齐 MCP 风格桥的 command 名。两者路由到同一 handler(E5)。见 Agent 集成 与 PUBLIC_API.md。
已知缺口
先读摘要背后的细节。采用非 VS Code 客户端时关注这些。服务器语义共享;缺口几乎都在客户端 UI。每条均给出权宜 + 跟踪 ID(仓内真值:docs/design/lsp-client-gaps.md —— 先在那里关掉缺口,再同步本表)。
| 缺口 | 影响客户端 | 权宜 | 跟踪 |
|---|---|---|---|
| Active-case 装饰(高亮当前 case 函数体) | Zed、Neovim、Helix(VS Code 已闭) | VS Code 扩展高亮整个函数体 + case 行。其它客户端:渲染 CodeLens 时用 ●/○ 切换 case,hover 跟随;无 CodeLens UI 时用 CLI nudo check / agent nudo.hover | LSP-G1 — VS Code 已闭;其余为客户端限制(Zed 无 decoration API;Neovim 需自写插件) |
| 不渲染 CodeLens | Helix、部分精简 Neovim | Inlay ● contract / … 与 CodeLens 同源投影观察面。另有 CLI nudo contract / nudo check;agent nudo.contract / nudo.contract.draft | LSP-G2 — 观察面已由 inlay 覆盖;CodeLens UI 仍为客户端限制 |
| Semantic tokens 默认关闭 | Zed、Neovim、Helix(VS Code 可染色) | VS Code 自带 semanticTokenScopes。其它客户端按 Setup notes 打开(Zed semantic_tokens: "combined";Neovim treesitter/semantic-tokens 插件;Helix editor.semantic-tokens) | LSP-G3 — VS Code 已可;其余仍配置债 |
| 次要 server 诊断可能与 tsserver 噪声叠加 | 全部 | VS Code:命令 Nudo: Apply coexistence settings。或收窄 package.json#nudo.analysis.include / exclude,或 mode: "directives" — 完整步骤见 共存。目标包带 tsconfig.json / jsconfig.json 时 nudo init 会打印此指引(只打印不写盘) | LSP-G4 — 配置面;VS Code 可自助 + 共存配方;init 打印指引 |
文件探测 / analysis.mode 文档 | 文档 | 真值:@nudojs/service API + PUBLIC_API.md §7 | LSP-G5 — 已关闭(文档已对齐 exports 默认) |
| 部分客户端不用 pull diagnostics | 较旧客户端 | push 路径必 publish(validateText / didOpen);客户端可能忽略 diagnosticProvider——pull 是可选增强 | LSP-G6 — push 面已有测试钉住 |
| 部分客户端补全触发 / signature help 偏弱 | Helix(视版本) | 服务端:真实参数/返回 + @nudo: 指令补全(触发符 @)。UI 仍薄时用 hover + nudo.check(agent 命令;CLI 侧为 nudo check)/ nudo test | LSP-G7 — 服务端已强化;Helix UI 仍为客户端限制 |
同源保证
下列表面共用同一计算(测试钉住):
| 表面 | 共享数据源 |
|---|---|
CodeLens ● contract | contractTierOf |
| Hover 首行 + 契约展示 | contractTierOf + getHoverAtPosition |
Inlay contractSource / derived | collectAbsInlays + contractTierOf |
| Semantic token modifiers | buildSemanticTokens + contractTierOf |
Agent nudo.check / nudo.hover / nudo.contract / test/whatIf/trace | 同一 service/core 入口 + buffer-aware loadModule(E5 AGENT_TOOL_SOURCES);工具错误带 isError: true |
CLI nudo check / nudo contract | 同一 service/core 入口 |
executeCommand nudo.* ↔ slash nudo/… | 同一 dispatch 表;清单钉在 packages/lsp/PUBLIC_API.md + public-api-surface.test.ts |