跳到主要内容

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-G1VS Code 已闭(函数体 + case 行装饰)。Zed / Neovim / Helix 仍开(客户端无装饰 API,或需要插件)
CodeLens 不渲染LSP-G2Helix / 极简 Neovim — 观察面由 inlay 覆盖 ● contract / hw|gen|imp(与 CodeLens 同源)。CodeLens UI 本身仍是客户端限制
Semantic tokens 默认关闭LSP-G3VS 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说明
DiagnosticsvalidateText(push)+ diagnosticProvider(pull)自适应防抖 300/400/800 ms;过期 generation 可取消(A8);pull 仅在 version + casesHash + depsHash 全匹配时命中缓存
HoveronHoverAbs / intension;导出函数名首行 ● contract / hw|gen|imp(A7)
补全(.)onCompletion按推断类型给出 property/method
CodeLensonCodeLens观察选择器:●/○ contract / hw|gen|imp(默认激活)+ persist/update;●/○ case "…" 选项跟随(nudo.selectCase / nudo.selectContract)
Inlay hintslanguages.inlayHintcase 提示 + Abs 参数/返回(implicit 导出标 derived)
跳转定义 / 引用 / 重命名标准 LSP含侧车绑定名(A5)
文档 / 工作区符号标准 LSP
Signature helponSignatureHelp触发 (、,;投影真实 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 commandnudo.*selectCase、contract、contract.draft、contract.emit、agent 工具
Custom requestnudo/…与 command 同一 handler(E5);协议契约用 slash 形式
Pull diagnosticsdiagnosticProviderinterFileDependencies: 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-lspcommand = nudo-lsp启动 nudo-lsp 或 node dist/server.js
DiagnosticsYYYYY
Hover(Abs + contract 档)YYYYY
补全YYYCY
CodeLens contract + caseYC(code_lens: "on")C(插件因实现而异)NC(视客户端)
Inlay hintsYC(inlay_hints.enabled)CCC
定义 / 引用 / 重命名YYYYY
文档符号YYYYY
Signature helpYYYCY
Code actions / QuickfixYYYYC
Code actions — extract / inline var / change signatureYYYYC
Semantic tokensYC(semantic_tokens: "combined")CCC
Active-case 装饰Y(扩展)NNNN
Agent 命令(nudo.check / nudo.hover / …)Y(executeCommand / MCP 桥)Y(agent / custom request)Y(custom LSP request)CY
未保存侧车 buffer(A4)YYYYY
buffer 感知的 contract agent 工具(E5)YYYYY

配置要点(复制即用默认配置)​

安装 @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 — 复制即用默认配置​

  1. 从扩展市场安装 nudojs/nudo-zed(或以 dev extension 安装)。扩展会通过 Zed 托管 npm 自动安装 @nudojs/lsp,无需在 package.json 里固定版本。
  2. ~/.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.hoverLSP-G1 — VS Code 已闭;其余为客户端限制(Zed 无 decoration API;Neovim 需自写插件)
不渲染 CodeLensHelix、部分精简 NeovimInlay ● contract / … 与 CodeLens 同源投影观察面。另有 CLI nudo contract / nudo check;agent nudo.contract / nudo.contract.draftLSP-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 §7LSP-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 testLSP-G7 — 服务端已强化;Helix UI 仍为客户端限制

同源保证​

下列表面共用同一计算(测试钉住):

表面共享数据源
CodeLens ● contractcontractTierOf
Hover 首行 + 契约展示contractTierOf + getHoverAtPosition
Inlay contractSource / derivedcollectAbsInlays + contractTierOf
Semantic token modifiersbuildSemanticTokens + 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

参见​