AI-native DX
读完你会知道: Nudo 如何为 agent 修环 设计(不只服务人类 IDE),以及如何客观度量(token · 轮数 · bug)。
给 agent 的一句话:不要相信声明。跑 nudo check --json。actual 是值,actions[] 是下一步。
Agent 在 TypeScript 上的痛
| TS 上的 agent 痛点 | 后果 |
|---|---|
| 假绿 | ms: number + setDelay(0) 能过检,bug 出货 |
| 散文报错 | “Not assignable to type …” —— 无值、无命令 |
| 双 IR | 注解与运行时漂移;agent「修错边」 |
| 闭环贵 | 全量 tsc / LS 多轮,费时费 token |
Nudo 给 agent 的面
| 需要 | 表面 |
|---|---|
| 真值 | 分析执行 JS(Abs);调用点是证据 |
| 机读门禁 | npx nudojs check <file> --json → CheckJson v1(稳定 code) |
| 下一步 | issues[].actions[] —— draft / relax / callsite / … + 可执行 command |
| 诚实 | any ≠ unknown;结果宽化时 budget.truncated |
| 快环 | 编辑路径远快于 tsc.LS |
| 出口 | migrate retire —— 一门禁,不双跑 |
{
"code": "nudo:constraint-violated",
"actual": "0 #exact",
"expected": "ms > 0",
"actions": [
{ "kind": "callsite", "label": "use a value satisfying the constraint", "hint": "ms > 0" },
{ "kind": "relax", "label": "relax the precondition (edit *.nudo.js / @nudo:contract)" },
{ "kind": "draft", "command": "nudo contract --draft", "label": "emit a sidecar draft you can edit" }
]
}
少样本「错→对」在 Agents(及 packages/lsp/agent-skill/SKILL.md)。粘贴块:
Read https://nudojs.github.io/nudo/agents.md and set up Nudo in this project.
Primary gate: npx nudojs check <path>.
Prefer issues[].actions[] over parsing suggestion prose.
Do not invent body-AST obligations. @nudo:case is debug-only.
Entry params print as any; unknown = inference failed.
Leaving tsc: npx nudojs migrate status|strip|verify|retire (exit is retire).
量什么(别争「感觉更 agent-friendly」)
| 指标 | 定义 | 为何重要 |
|---|---|---|
| detectRate | bug 在门禁上是红的比例 | agent 看得见吗? |
| silentGreen | 门禁绿但 bug 仍在 | TypeScript 失效模式 |
| wrongFixGreen | 常见错误修法后门禁仍绿 | 可作弊的门禁 |
| diagTokens | 首个红载荷近似 token(仅报红时) | 看见之后的读成本 |
| rounds | 文档路径上的门禁次数 | 迭代税 |
成对夹具(同一 bug:JS+Nudo vs TS+tsc)——pnpm run agent-dx:
task | detect n/ts | diagTok n/ts (when fired) | wrongFixGreen n/ts | rounds n/ts
01-constraint | RED/SG | 101/0 | true/true | 1/0
02-shape | RED/RED | 96/58 | true/true | 1/1
03-assign | RED/RED | 98/44 | false/true | 1/1
04-entry-throws | RED/SG | 124/0 | false/true | 1/0
05-return | RED/SG | 96/0 | true/true | 1/0
detectRate nudo=5/5 ts=2/5
silentGreen nudo=0/5 ts=3/5
wrongFixGreen nudo=3/5 ts=5/5
TS 的「便宜 token」往往是沉默(SG)——agent 根本看不见 bug。Nudo 付的是检出的 token。
pnpm run agent-dx # table
node benchmark/agent-dx/run.mjs --json # ingest
更重的成对评测(仓库内)
agent-dx 是静态门禁载荷探针。要在多文件模块图 + 真实历史 bug 上量 LLM 修复环(detect · silentGreen · token/轮次),用 benchmark/lsp-rounds/(夹具由本地 node-semver checkout 生成,脚本为 oss-semver/build.mjs);结论档:benchmark/lsp-rounds/out/OSS-SEMVER.md。
OSS 历史 bug 切片(node-semver,6 个最近 fix,约 2.4k LOC 多文件)——两侧都 6/6:
| Nudo | TypeScript | |
|---|---|---|
| detectRate | 6/6 | 6/6 |
| silentGreen | false | false(跑完时) |
| tokenTotal | 569k | 993k(+75%) |
| rounds / repairLoops | 45 / 16 | 63 / 21 |
| gate 峰值 RSS | 226MB | 289MB |
结论:在大模块真缺陷上,两侧都能摸到满分检出——差距在成本与稳定性,不是天花板。预算偏紧时 TS 侧 2/3 次出现 silentGreen(门禁绿、坑还在);Nudo 跑完那轮没有。约束类小题(agent-dx)上 detect / silentGreen 的类型面分裂仍然更尖锐。
node benchmark/lsp-rounds/oss-semver/build.mjs /path/to/node-semver
node benchmark/lsp-rounds/harness/run.mjs --seed 1 --task oss
推荐 agent 闭环
写/改 JS
→ nudo check --json
→ 选 actions[](或 few-shot 对)
→ 改实参 / 放宽契约 / draft→accept
→ 再 check
→ 绿,或诚实 unknown(禁止假 @returns)
可脚本探针:
npx nudojs check src/app.js --what-if raw=string --target size
npx nudojs contract --draft src/app.js --json # draftSource + unified diff
非目标(让 agent 保持诚实)
- 不要把 JS 改写成 TS「为了类型」。
- 不要发明 body-AST 义务。
- 不要用编造的
@returns消unknown。 - 不要把双跑写成终态 —— 出口是
migrate retire。
下一步
- Agents — 规则 + 少样本修复对
- 错误对照 — 人读的
actual ⊭ expected - 心智模型
- 从 TypeScript 迁移 — 退役 tsc