跳到主要内容

VS Code 扩展

nudo-vscode 扩展将 Nudo 的类型推断带入编辑器,提供悬停类型、补全、CodeLens 和内联提示。

定位(诚实): VS Code 是 Nudo 的旗舰 IDE 路径——@nudojs/lsp 上最完整的客户端面。门禁路径仍是 CLI / Agent:CI 里的 nudo check --json,以及给 agent 的 nudo.check / MCP 工具。IDE 是跑在同一服务器上的尽力而为观察面;它不替代门禁。其他编辑器:LSP 客户端矩阵。

安装​

  1. 从最新 GitHub Release下载 nudo-vscode.vsix
  2. VS Code → 扩展视图(Cmd+Shift+X / Ctrl+Shift+X)→ … 菜单 → 从 VSIX 安装…
  3. 选择刚下载的文件

或从命令行安装:

code --install-extension nudo-vscode.vsix

市场列表(VS Code Marketplace 与 Open VSX 上的 wmzy.nudo-vscode)是发布产物——搜得到时可直接从扩展视图安装,也可以从源码构建(pnpm --filter nudo-vscode run build && pnpm --filter nudo-vscode run package)。GitHub Release 上的 .vsix 才是真源。

激活​

打开 JavaScript 文件时扩展会激活。它使用 @nudojs/lsp 包运行 Language Server Protocol(LSP)服务器,提供所有编辑器功能。

文件检测:语言服务器分析 .js、.ts 与 .mjs 文件。出厂默认 nudo.analysis.mode = "exports"(export / 侧车 / 指令);模式语义见与 TypeScript 共存。契约写在 *.nudo.js 侧车与源内 @nudo:contract;@nudo:case 是调试 / 可选 nudo test 子层。完整语法见指令参考。跨编辑器能力对比:LSP 客户端矩阵。

激活 vs 分析门:activationEvents(onLanguage:javascript / onLanguage:typescript)只负责启动客户端。缓冲区是否被分析由服务端 shouldAnalyzeFile 门决定(目标路径 + nudo.analysis.mode)。JSX/tsx 可激活扩展,但不是 Nudo 分析目标。

发布检查清单(维护者)​

扩展打包与 Marketplace 发布步骤:贡献指南 — 发布。

功能​

悬停类型​

将鼠标悬停在表达式上可查看其推断类型。扩展通过 getTypeAtPosition 计算光标处的类型,并在悬停工具提示中显示。

活动 Case 装饰(LSP-G1)​

通过 CodeLens 选中某个 @nudo:case 会高亮整个函数体加上该 case 注释行(不只是注释)。高亮会在每次文档编辑时按当前缓冲区重算,因此你边打字它边跟着走。服务端签名帮助也会投影真实的 paramTypes / 返回 shape。

与 tsserver 共存(LSP-G4)​

命令面板 → Nudo: Apply coexistence settings (vs tsserver) 会在确认后(绝不静默)向工作区写入 javascript.validate.enable=false。完整配方:与 TypeScript 共存。

/**
* @nudo:case "test" (42)
*/
function double(x) {
return x * 2; // hover over x → number
}

补全​

在表达式后输入 . 时会触发补全。LSP 会根据该位置的推断类型建议属性和方法。

/**
* @nudo:case "test" ("hello")
*/
function upper(s) {
return s. // completions: toUpperCase, toLowerCase, slice, etc.
}

CodeLens:观察选择器(contract + 各 case)​

透镜行是一个观察选择器——contract 是与各 case 并排的一项,恰好一项激活(●):

  • ● contract / hw|gen|imp —— 契约选项(handwritten / generated / implicit 档),默认激活。点击切回契约观察(nudo.selectContract);已激活时点击幂等
  • ⚡ persist contract / ↻ update contract —— 把调用点域固化进 *.nudo.js 侧车
  • ● / ○ case "name" —— 点击选择类型重放的激活 case(nudo.selectCase);契约选项随之转 ○

悬停导出函数名时,hover 首行与 CodeLens 同源显示 ● contract / hw\|gen\|imp(A7)。VS Code 中当前激活 case 以不同样式高亮。这样可以在不修改文件的情况下查看不同输入下的类型。

内联提示​

内联提示会在行内显示类型信息。在每个 case 的结果之后或相关位置,Nudo 会将推断的类型以灰色注释形式显示。

状态栏​

右侧状态栏在扩展激活时显示 Nudo,悬停提示为 "Nudo Type Inference Engine"。

跳转到定义​

跳转到函数、变量或类的定义。将光标放在标识符上并按 F12(或右键 -> Go to Definition)。

function process(data) {
return transform(data); // F12 on transform → jumps to its definition
}

查找引用​

查找符号的所有使用——本文件及跨文件(其他已打开/已知文件中的导入方)。按 Shift+F12(或右键 -> Find All References)。

重命名符号​

安全地重命名符号及其所有引用。按 F2(或右键 -> Rename Symbol)。Nudo 会验证新名称不会与现有符号冲突。

签名帮助​

在函数调用的括号内输入时,Nudo 会显示参数提示。在输入 ( 或 , 时自动激活。

/**
* @nudo:case "test" (string(), number())
*/
function createUser(name, age) { ... }

createUser( // ← signature help shows: (name: string, age: number)

代码操作 / 快速修复​

当 Nudo 报告诊断时,可使用快速修复建议。点击灯泡图标或按 Cmd+. / Ctrl+. 查看可用修复:

  • 移除不可达代码 ——针对 return/throw 之后的代码
  • 给调用点 / 侧车形状补字段 ——在调用点与(若存在)*.nudo.js 形状里插入 field: undefined
  • 放宽侧车契约 ——对 refine / domain 违例,把手写侧车上的数值 pred(number().gt(0) → number())改写掉

语义标记​

Nudo 根据推断类型提供语法高亮。函数、变量和死代码的高亮与标准语法着色不同。

命令:"Nudo: Select Case"​

Nudo: Select Case(nudo.selectCase)就是 case CodeLens 背后的命令:透镜把文件、函数名与 case 下标一并传进来,扩展据此切换该函数的激活 case(并立刻在本地高亮)。

同一条命令也列在命令面板(Cmd+Shift+P / Ctrl+Shift+P)里,但面板执行不传任何参数——裸命令无从得知要选哪个函数、哪个 case。扩展会先用当前编辑器兜住文件,然后如实报告缺失的入参(Nudo: select case needs a function name (use the CodeLens))而不是猜:既不发请求,也不写本地高亮。因此切换 case 是 CodeLens 的动作。

另外两点:

  • 该命令的处理器在语言服务器连上时才挂上(id 由客户端按服务端广告注册),所以面板项要等客户端就绪后才可点。
  • 服务端拒绝一次 case 切换时,扩展会给出错误提示并回滚乐观的本地高亮——被拒的切换不会留下错误的高亮。

命令:Interface / Draft / Persist​

面板标题命令行为
Nudo: Show Contractnudo.contract在 Nudo 输出通道打印分层(同 nudo contract)
Nudo: Select Contract (back to contract observation)nudo.selectContract把函数切回契约观测(取消其激活的 case),并清掉本地 case 高亮
Nudo: Trace Observation (entry@ / call@)nudo.trace在 Nudo 输出通道打印该函数的逐用例观测(entry@ / call@)(同 nudo trace)
Nudo: Draft Contract (code-first)nudo.contract.draftOutput 预览草稿;可选写入 *.nudo.draft.js / *.nudo.draft.ts(无项目根时写盘 fail-closed)
Nudo: Persist Contract (@generated)nudo.contract.emit先 dry-run(dryRun: true,不写盘)→ Output 预览 → 确认 → 真实写入侧车。CodeLens persist/update 共用同一确认流程;从面板走时用 QuickPick 交互选函数,三步门禁不变

非手写导出上的 CodeLens 含 ⚡ draft contract——与 CLI --draft、agent nudo.contract.draft 同源。persist/update CodeLens 在确认对话框接受前绝不会写盘。

从命令面板触发时,这些命令作用于当前活动编辑器(不需要传文件参数):Show Contract 与 Draft Contract 是文件粒度的,而 Persist Contract (@generated) 会用 QuickPick 让你从该文件可固化的导出里选一个函数——与服务端 ⚡ persist contract / ↻ update contract CodeLens 给的是同一批函数。文件里没有可固化函数时,命令会如实报告没有(没有自由文本兜底)。两条路径的门禁完全一致:dry-run 绝不写盘,dry-run 失败时根本不提供写盘动作,侧车只在你确认之后才写。


资源占用​

Nudo 语言服务器的设计目标是在你的其他工具旁保持轻量:

  • 内存有界。 请求之间,服务器只持有轻量簿记 —— 文件路径、函数名和少量每文件记录 —— 你一关闭文件,它的分析结果即被丢弃。服务器绝不在内存中保留解析后的语法树,其定位是与 TypeScript 自身的语言功能并排运行,而非取而代之。
  • 打开即出诊断。 打开文件就会立即分析;无需先编辑一次才能看到 Nudo 的诊断。
  • 陈旧诊断在重开时消除。 你关闭的文件不会因其依赖发生变化而被重新分析 —— 它的诊断保持原样,直到你再次打开该文件时刷新。从磁盘删除的文件会自动清空诊断。

总结​

功能描述
悬停Abs / intension;导出函数名显示 ● contract / hw|gen|imp
补全在 . 后触发;属性和方法建议
CodeLenscontract 档 + persist/update;case 副层
内联提示Abs 参数/返回;implicit 导出标 derived
跳转到定义跳转到符号定义(F12)
查找引用查找符号的所有使用(Shift+F12)
重命名符号重命名符号及其所有引用(F2)
签名帮助函数调用内的参数提示
代码操作诊断的快速修复
语义标记类型感知高亮 + contract 档 modifier
状态栏激活时显示 "Nudo" 指示器
命令nudo.selectCase / nudo.contract / nudo.contract.emit

参见:LSP 客户端矩阵(其他编辑器)。

下一步​