跳到主要内容

Agent API

@nudojs/lsp 面向 agent 的 API 参考。全部 agent 命令都内置于 Nudo 语言服务器,通过标准的 workspace/executeCommand 调用或自定义 LSP 请求访问——不需要安装独立的服务器进程或协议。连接方式(LSP→MCP 桥、原生 LSP 客户端、VS Code)见 Agent 集成指南。

命令​

命令自定义请求别名用途
nudo.checknudo/check约束门禁 —— CheckJson v1(Abs 签名 + actual ⊭ expected)
nudo.testnudo/test全文件推断 —— CaseJson v1(intension 携带无损 Abs)
nudo.hovernudo/hover源码位置上的无损 Abs(可选 inlay / contract 分层)
nudo.whatIfnudo/whatIf对绑定应用类型假设,读取目标的推断类型
nudo.suggestCasenudo/suggestCase检查函数的 @nudo:case 覆盖情况;用例全为合成时返回可直接粘贴的指令
nudo.tracenudo/trace列出函数每个用例的参数类型 → 结果类型
nudo.contractnudo/contract打印有效契约分层(handwritten / generated / implicit)
nudo.contract.draftnudo/contract.draft代码优先草稿:从已有逻辑生成 *.nudo.draft.js / *.nudo.draft.ts(与 CLI --draft 同源)
nudo.contract.emitnudo/contract.emit把调用点域固化为侧车 @generated 段
nudo.selectCasenudo/selectCase切换用于悬停/诊断的活动用例
nudo.getActiveCasesnudo/getActiveCases读取文件中每个函数的活动用例索引

nudo.check / nudo.test / nudo.hover / nudo.whatIf / nudo.suggestCase / nudo.trace / nudo.contract* 返回 MCP 风格的文本内容——{ content: [{ type: "text", text }] }。nudo.selectCase / nudo.selectContract 成功时返回 { success: true },被拒绝时(函数未知、用例下标越界、参数畸形)返回 { success: false, error, isError: true };nudo.getActiveCases 成功时返回 Record<string, number>,失败时返回同样的 { success: false, error, isError: true } 形状。共享数据源由 AGENT_TOOL_SOURCES(E5)钉住——agent 工具与 CLI/LSP 命令走同一 service/core 入口。

约定​

  • file 参数——每个命令都接收字符串 file,接受 file:// URI 或裸路径。未在编辑器中打开的文件从磁盘读取。
  • 编辑器风格请求——nudo/selectCase 与 nudo/getActiveCases 请求额外接受编辑器风格的 { uri, ... } 参数(VS Code 扩展的 CodeLens 使用)。Agent 应始终使用 file。
  • 类型表达式——见下方类型表达式。
  • Abs 优先——check / test / hover 暴露无损代数(Abs)。外延字符串(args / result / ext)是兼容用的有损投影,不是类型模型本身。

nudo.check​

在 Abs(类型即计算)上的约束门禁。契约与 CLI nudo check --json 一致。见 nudo check。

参数:

名称类型描述
filestringfile:// URI 或路径
sourcestring?预读源码(绕过磁盘/编辑器)
format"text" | "json""json" → 只返回 CheckJson;默认人类摘要 + JSON

返回(CheckJson v1): { version: 1, file, ok, summary, signatures[], issues[] },issue 可携带 actual / expected。Issue code(完整表见 check 指南):

Code含义
nudo:constraint-violated调用/返回不满足显式契约 Pred(actual ⊭ expected)
nudo:assign-mismatch赋值 ⊭ 既有绑定形状
nudo:arg-structureHOF:实参不是可调用 fn / arity 不匹配
nudo:case-inconsistency@nudo:case 见证 ⊭ refine
nudo:contract-param-mismatch手写契约的形参名不在形参面上
nudo:contract-conflict手写契约的合取不可满足
nudo:contract-load / nudo:contract-cycle侧车装载失败 / 循环
nudo:contract-domain-exceeds跨文件调用证据 ⊄ 手写契约
nudo:contract-name-clash侧车导出名与源导出重名
nudo:contract-underivable派生契约行无法从源证据推导(info;手写契约永不触发它)
nudo:contract-drift@generated 段 ≠ 重算结果(warning)
nudo:no-signature无符号化 Abs 签名(warning;L2 仍可能经 entry 回退生效)
nudo:opaque-result不透明求值

actions[](只增字段)。 每条 issues[] 可携带结构化下一步。Agent 应优先消费 actions[],不要解析 suggestion 散文:

字段描述
actions[].kinddraft | relax | callsite | assume | mock | emit | ignore-throws | info
actions[].command可选的可执行命令(如 nudo contract --draft);省略则只读 label/hint
actions[].label一行说明(与 suggestion 同源,通常更短)
actions[].hint可选:目标 Pred / 字段名等,供程序化改写
{
"command": "nudo.check",
"arguments": [{ "file": "src/validators.js", "format": "json" }]
}

nudo.test​

全文件用例报告 —— 数据与 CLI nudo test --json 一致。CI 优先 CLI nudo check / nudo test;本工具名为遗留,映射到 test/check 观察面。

参数:

名称类型描述
filestring路径或 URI
sourcestring?预读源码
format"text" | "json""json" → 只返回 CaseJson
functionsstring[]?过滤到这些函数名

返回(CaseJson v1): cases[].intension 携带 abs / term / pred / conf(无损);args / result 是外延字符串(formatShape 投影)。无约束的入口参数是 any;unknown 表示推断失败。

{
"command": "nudo.test",
"arguments": [{ "file": "src/app.js", "functions": ["scale"], "format": "json" }]
}

nudo.hover​

位置上的无损 Abs —— 与编辑器 hover 同源,中间不经过投影。

参数:

名称类型描述
filestring路径或 URI
linenumber1-based 行号
columnnumber0-based 列号
sourcestring?预读源码
includeInlaysboolean?同时返回该文件全部 Abs inlay

返回 JSON: { file, line, column, abs, absMultiline, intension, ext, inlays? } —— abs 无损;ext 仅作对照用的外延投影。

nudo.whatIf​

设置类型假设并观察其他位置的推断类型——AI 驱动类型探索的主要工具。

参数:

名称类型描述
filestringJavaScript 文件的 file:// URI 或路径
bindingsArray<{ name: string, type: string }>要应用的类型假设。name 必须是顶层声明(顶层 const/let/var、函数或类)——函数参数与局部变量没有可匹配的声明,会被回报为未应用。type 是类型表达式,如 number 或 string | null
targetstring要获取类型的顶层变量

返回: { content: [{ type: "text", text }] },其中 text 为 Type of "<target>": <type>——目标在假设绑定之下的推断类型;不是已知绑定时为 unknown。末尾的说明行回报哪些绑定生效了:Bindings applied: …;对没有顶层声明的名字则有 Bindings not applied (no top-level declaration found): …(此时答案使用文件自身的类型)。

示例——src/config.js 中有 const size = raw.length,raw 来自一个未知加载函数;假设 raw 是 string,询问 size 变成什么:

const raw = loadRaw();
const size = raw.length;
{
"command": "nudo.whatIf",
"arguments": [
{
"file": "src/config.js",
"bindings": [{ "name": "raw", "type": "string" }],
"target": "size"
}
]
}
Type of "size": number
Bindings applied: raw: string

nudo.suggestCase​

根据函数的参数类型建议 @nudo:case 指令。

参数:

名称类型描述
filestringJavaScript 文件的 file:// URI 或路径
functionNamestring函数名

返回: { content: [{ type: "text", text }] },内容为以下四种之一:

  • Function "<functionName>" not found —— 文件中没有该函数。
  • 一行 Suggested: /** @nudo:case */ 后跟 function <functionName>(...) { ... } —— 函数完全没有用例(只有被推断跳过的函数才会零用例)。
  • Function "<functionName>" already has N case(s) —— 函数已有手写(或 entry-only)的 @nudo:case 用例,保持不动。
  • 全部用例都由调用点合成 —— 返回可直接粘贴到函数声明上方的指令文本,例如:
Function "add" has 2 synthesized case(s); suggested directives:
/**
* @nudo:case "witness@1" (1, 2) => 3
* @nudo:case "witness@2" ("x", "y") => "xy"
*/
Note: witness names are hand-written (not the synthetic call@/entry@ namespace); the expected value is the observed result.

实参无法序列化为指令的用例(函数、Promise、实例等)会被丢弃,并在末尾追加一行 (M case(s) skipped: not serializable as directives);若全部用例都不可序列化,则改回 Function "<functionName>" already has N case(s) (none serializable as directives)。

nudo.trace​

追踪类型在函数中从输入到输出的转换——每个用例一行。

参数:

名称类型描述
filestringJavaScript 文件的 file:// URI 或路径
functionNamestring要追踪的函数

返回: { content: [{ type: "text", text }] },每个用例一行 Input: (<参数类型>) => Output: <结果类型>,或 Function "<functionName>" not found / No cases found for "<functionName>"。

nudo.selectCase​

切换函数的活动用例。活动用例决定悬停类型、诊断和内联提示,直到再次切换。

参数:

名称类型描述
filestringJavaScript 文件的 file:// URI 或路径
functionNamestring函数名
caseIndexnumber要激活的用例索引(从 0 开始)

返回: 成功时 { success: true };函数未知、该函数没有可选择的 @nudo:case、或 caseIndex 越界时 { success: false, error, isError: true }。服务器会以新的活动用例重新验证文档并刷新 CodeLens、内联提示与拉取诊断。

nudo.getActiveCases​

读取文件中每个函数的活动用例索引。

参数:

名称类型描述
filestringJavaScript 文件的 file:// URI 或路径

返回: Record<string, number>,函数名 → 活动用例索引,例如 { "parse": 1, "greet": 0 };失败时 { success: false, error, isError: true }。

nudo.contract / nudo.contract.draft / nudo.contract.emit​

Interface 产品面(与 CLI 同一数据源):

命令参数行为
nudo.contract{ file, functionName?, source? }打印 fn [handwritten|generated|implicit] (params) → returns + JSON
nudo.contract.draft{ file, functionName?, source?, write?, dryRun? }代码优先草稿模块(@nudo:draft);write: true 落盘 *.nudo.draft.js / *.nudo.draft.ts(从不碰 ambient 绑定)。body 读字段仅作建议。write: true 无项目根时 fail-closed(nudo 配置 / package.json 祖先)——与 CLI --draft --write 同口径(覆盖:NUDO_DRAFT_FORCE=1)
nudo.contract.emit{ file, functionName, mode: "add"|"update", dryRun?: boolean, from?: string[] }通过 emitContract 固化调用点域。dryRun: true 只预览不写盘:返回同形结果(路径、would-change、unifiedDiff)与 [dry-run] would update … 文本;不会新建/修改侧车文件。VS Code Persist/CodeLens 确认流程先发 dryRun: true,确认后再真实写盘

loadModule 与有效 autoBind 由服务端注入(buffer-aware 侧车装载 + 项目 package.json#nudo.contract.autoBind AND 客户端请求)。它们不是可 JSON 序列化的请求参数——agent 不要发送。

手写契约永不被 draft 或 emit 覆盖。接受草稿时请将审阅过的导出拷入 *.nudo.js / *.nudo.ts。工具错误携带 isError: true。

类型表达式​

nudo.whatIf 绑定的 type 字段接受基本类型或以 | 分隔的基本类型联合:

表达式含义
number | string | boolean对应的基本类型
null | undefined对应的单例类型
bigint | symbol其余基本类型
string | null联合——“string 或 null”

约束构建器形式(number()、lit(...)、shape({...})、union(...)、array(...))与结构化表达式(对象/数组字面量、=> 函数)透传给指令文法(parseCaseArgExpr);其他名字一律变为 unknown。

Nudo 无法表达的名字会降级为 unknown——绝不被悄悄放宽成 any。Bindings applied: … 这行说明实际注入了什么,所以降级后的绑定读作 x: unknown (requested "Date" is not expressible; applied as unknown)。联合里只要有一个成员不可表达,整个联合一起降级(union(unknown, …) 不是合法的约束构建器实参)。

诊断​

类型错误(失败的 @nudo:contract 断言、不可达代码等)通过 LSP 诊断在两个方向可用:

  • 推送:每次分析后的 textDocument/publishDiagnostics
  • 拉取:按需的 textDocument/diagnostic

拉取模式天然适合 agent:打开(或指向)一个文件,发送 textDocument/diagnostic,读取 severity 为 1 的条目即可——无需调用命令。

从 MCP 服务器迁移​

独立的 @nudojs/mcp 包已退役;其工具映射到上述命令:

旧 MCP 工具替代方案
nudo-what-ifnudo.whatIf——bindings 现在会真正生效(此前被忽略)
nudo-checknudo.check(CheckJson v1,CI/agent 门禁首选)。pull 诊断现已含 Abs check + A3 过滤的 evaluator 诊断(打开 buffer),但不等价于全文件 CI 门禁
nudo-type-atnudo.hover(无损 Abs),或 bindings 为空、target 指定目标的 nudo.whatIf
nudo-suggest-casenudo.suggestCase
nudo-tracenudo.trace

连接层面的变化见指南的从 MCP 服务器迁移一节。

Export inventory​

由 node scripts/gen-api-docs.mjs 从包导出面(PUBLIC_API.md / src/index.ts)生成 —— 请勿手改本块(或在 pnpm run docs:gen 里一并再生)。每行名字带稳定锚点 #slug(符号名小写)。

Agent 工具来自 AGENT_TOOL_SOURCES(packages/lsp/src/agent-tools.ts),与 src/public-api.ts 的 nudo.* executeCommand / nudo/* 请求名同源钉住。codeLens 仅服务端;selectCase / getActiveCases 是编辑器命令,不是 agent 工具。

名称种类说明签名
checkfnnudo.check / nudo/check — checkSource + mergeCheckIssues + serializeCheckJsonnudo.check | nudo/check
codeLensfn(server-only, no command) — computeContractLenses + contractTierOf—
contractfnnudo.contract / nudo/contract — contractSurface + formatContractSurfaceLinenudo.contract | nudo/contract
contract.draftfnnudo.contract.draft / nudo/contract.draft — draftContract + formatDraftSummarynudo.contract.draft | nudo/contract.draft
contract.emitfnnudo.contract.emit / nudo/contract.emit — emitContractnudo.contract.emit | nudo/contract.emit
getActiveCasesfnnudo.getActiveCases / nudo/getActiveCases — editor command (not an agent tool)nudo.getActiveCases | nudo/getActiveCases
hoverfnnudo.hover / nudo/hover — getHoverAtPosition + contractTierOfnudo.hover | nudo/hover
selectCasefnnudo.selectCase / nudo/selectCase — editor command (not an agent tool)nudo.selectCase | nudo/selectCase
suggestCasefnnudo.suggestCase / nudo/suggestCase — analyzeFileAsync + buildCaseDirectivenudo.suggestCase | nudo/suggestCase
testfnnudo.test / nudo/test — analyzeFileAsync + buildTestReport + serializeCaseJsonnudo.test | nudo/test
tracefnnudo.trace / nudo/trace — analyzeFileAsync casesnudo.trace | nudo/trace
whatIffnnudo.whatIf / nudo/whatIf — injectBindings + analyzeFileAsyncnudo.whatIf | nudo/whatIf