跳到主要内容

Agents(智能体)

Nudo 面向 agent 可执行:稳定动词、稳定诊断码,并提供机器入口。

  • 机器入口:agents.md
  • 策展索引:llms.txt
  • 源码 Markdown:monorepo packages/website/docs/**(llms.txt 中列出 raw 链接)

可粘贴进 agent 的指令块​

Read https://nudojs.github.io/nudo/agents.md and set up Nudo in this project.
Primary gate: npx nudojs check <path>.
Contracts are *.nudo.js / @nudo:contract.
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).

产品规则(不得违反)​

规则说明
动词仅 check | test | contract | export | health | migrate
无 infer 动词观察 = check 签名 + IDE
契约sidecar / @nudo:contract(历史拼写 @nudo:refine / @nudo:interface 已移除,无别名层)
@nudo:case仅调试 / nudo test / LSP
any vs unknown入口 any;unknown = 推导失败
check vs exportcheck 校验;export 有损投影
L1 / L2L1 显式契约;L2 入口 may-throw;ignoreThrows ≠ L1
不发明 body-AST 槽位义务只来自契约或调用点事实
HOF promote ≠ check errorbody 用法提升只是警告建议
migrate 是单向门status → strip → verify → retire tsc;共存不是终态

观察层 / 契约层命令​

npx nudojs check <path>
npx nudojs check <path> --what-if raw=string --target size # AI3:假设 → 观察
npx nudojs contract <path>
npx nudojs contract --draft <path> [--write] [--json] # AI4:draftSource + unified diff
npx nudojs export <path> --format dts --out dist/types
npx nudojs health <path>
npx nudojs migrate status <pkg>
npx nudojs migrate retire <pkg> --dry-run

nudo test 是可选的调试 case 报告,不是主叙事。

配置(package.json)​

{
"nudo": {
"analysis": { "mode": "exports" },
"check": { "ignoreThrows": ["TypeError"], "entryThrows": "error" },
"contract": { "autoBind": true }
}
}

默认分析模式 "exports"(export / 侧车 / 指令);命名路径的 CLI check 仍会分析该文件。完整配置面:CLI 参考。

机器可读诊断​

npx nudojs check file.js --json

人类可读面使用 Abs 上的 actual ⊭ expected。稳定诊断码见 诊断码词典。

每个 issues[] 条目可携带 actions[](AI1)——优先消费它们,而不是解析 suggestion 文本:

{
"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" }
]
}

少样本修复对(该这么改,别那么改)​

最小 diff。优先消费 issue 上的 actions[],再套用下表。

nudo:constraint-violated — 改调用点​

// 错 — actual: 0 #exact ⊭ expected: ms > 0
setDelay(0);

// 对 — 同一契约,值满足 Pred
setDelay(250);

仅当 0 合法时才放宽契约(编辑 *.nudo.js):

// 错
export const setDelay = fn({ ms: number().gt(0) }, number());
// 对
export const setDelay = fn({ ms: number().ge(0) }, number());

nudo:entry-may-throw — refine / 守卫 / 迁移开关​

// 错 — L2: property 'name' on any
export function getName(user) {
return user.name;
}

// 对 — 声明入口形状
export const getName = fn({ user: shape({ name: string() }) }, string());

迁移期逃生舱(不是类型修复):npx nudojs check --ignore-throws TypeError。

nudo:module-throw — 给装载期 throw 加守卫​

// 错 — 模块永远无法被导入:装载即抛
throw new TypeError("config missing");

// 对 — 只在真正不可用的路径上抛
if (process.env.NODE_ENV === "production" && !config) {
throw new TypeError("config missing");
}

装载即抛是有意行为(react-dom/client.react-server.js 那种模式)? 保留它并显式声明:npx nudojs check --ignore-throws TypeError(或 --entry-throws off)。 每模块一条诊断 —— 该模块未被分析(所有导出都不可用)。

nudo:unknown-inference / nudo:opaque-result — 让返回面可计算,禁止编造​

// 错 — 调进未建模 native,返回面是 true unknown
export function fmt(v) {
return __nudoMissingNative(v);
}

// 对 — 可计算函数体(或补调用点证据)
export function fmt(v) {
return String(v);
}

不要为了消掉 unknown 去写 @returns string。那正是 Nudo 拒绝的 TS 谎言。
@nudo:mock 面向导入模块面(对自由全局仍不稳——优先可计算函数体或真实证据)。

nudo:assign-mismatch — 保住形状​

// 错 — 丢 port
export let config = { host: "localhost", port: 8080 };
config = { host: "y" };
// 对
config = { host: "y", port: 8080 };

draft→accept(新义务)​

npx nudojs contract --draft src/app.js # 仅审阅
# 把选中的 export 抄进 app.nudo.js ← accept 时 L1 才生效
npx nudojs check src/app.js

不发明 body-AST 槽;不把 JS 改写成 TS「为了类型」。

工具面​

表面文档
LSP 包@nudojs/lsp
Agent executeCommandAPI · agent
Agent 集成Agent 集成指南

不要把服务端注入字段(loadModule、生效中的 autoBind)当作 JSON-RPC 参数发送。

Agent 非目标​

  • 不要把 @nudo:case 当成契约生成器
  • 不要把 JS 改写成 TS「为了类型」
  • 不要从 body AST 发明必填 slot
  • 不要把无约束入口参数叙述成 unknown
  • 不要把双跑 tsc + nudo check 写成永久终态 —— 出口是 migrate retire

参见 Limits · 术语表 · Recipes · 从 TypeScript 迁移。