性能:预算与分析缓存
两个常被混淆的独立杠杆:
- 预算管精度。Nudo 分析的是(可能无限的)执行的有限近似。预算用尽时,受影响的结果拓宽(
#widened),并有诊断码说明 —— 绝不静默。 - 磁盘缓存(
.nudo/cache)管一部分冷路径的重复运行延迟。默认关闭,且绝不加速test/export/health背后的完整分析。
分析预算
求值器(transpile → new Function)在你的代码上执行真实的 Abs 代数。预算为这份工作量设界:
| 预算 | 默认 | 旋钮 | 触发时 |
|---|---|---|---|
| 调用总数(函数进入次数) | 20,000 | — | nudo:recursion-truncated |
| 调用深度 | 64 | — | nudo:recursion-truncated |
分支展开($fork 总数) | 5,000 | NUDO_MAX_FORKS / package.json#nudo.analysis.maxForks | nudo:fork-truncated |
| 每函数合并的调用点数 | 3 | package.json#nudo.analysis.callSiteBudget(1–64) | 超限调用点符号折叠 → #widened |
只有 fork 预算可调(env NUDO_MAX_FORKS 优先于 nudo.analysis.maxForks;非法值回落默认)。调用总数与调用深度是硬上限 —— 请重构代码,而不是找旋钮。
何时触发截断 —— 该做什么
nudo:recursion-truncated —— 递归求值被截断;受影响结果拓宽。reason 字段(check --json)与文案区分归因:cycle 表示同抽象实参的调用已在求值栈上——调用环,任何预算都解不开(让实参逐层变化、收窄基例,或声明 @nudo:contract);depth / calls 表示调用预算(深度 64 / 总进入 20,000)真的用尽——函数上的 @nudo:budget depth=… / calls=… 可抬。nudo:loop-truncated —— 循环退出条件越过迭代预算(抽象展开 8 / 具体 1024)仍具体真;循环状态拓宽。这是循环预算——@nudo:budget calls/depth 不适用;让上界依赖数据或用 @nudo:case / @nudo:contract 钉住。nudo:fork-truncated —— 分支展开预算用尽;受影响结果拓宽(info)。这些都出现在 nudo check / nudo test 输出里 —— 截断绝不静默降级结果。
三个杠杆,按值得尝试的顺序:
- 加约束。 契约(
*.nudo.js/@nudo:contract)与调用点证据让集合早收窄 —— 更小的 Abs、更少的重求值、更少的 fork。这也是唯一能同时提升精度的修法。 - 拆函数 / 拍平分支。 深调用链烧调用深度;长
if/else链与分支内循环让$fork计数组合式膨胀。抽取 helper、提前 return、拆分关注点。 - 调旋钮与 env。 调高 fork 预算(
NUDO_MAX_FORKS=20000或package.json#nudo.analysis.maxForks);用@nudo:env/ mock 建模你触碰的 API,让分析留在已建模的精确路径上,而不是对 opaque 值反复 fork。
预算的存在是为了让分析在对抗性代码上可终止。如果你经常调 maxForks,真正的故事通常在代码(或缺的契约)上。
.nudo/cache 项目磁盘缓存
默认关闭。通过 package.json 打开:
{
"nudo": {
"cache": true
}
}
nudo.cache 接受:
| 取值 | 含义 |
|---|---|
true | 缓存在 <projectRoot>/.nudo/cache |
"some/dir" | 自定义目录,相对项目根解析 |
{ "dir": …, "sign": true } | 对象形态 —— 自定义根与条目签名(见下)组合 |
false / 省略 | 关闭(默认) |
env 覆盖(配置未设时):NUDO_CACHE_DIR —— 绝对路径,或 off / 0 关闭。
落到磁盘的内容(缓存根下按命名空间分子目录):
| 命名空间 | 内容 | 服务的面 |
|---|---|---|
contract | 整文件 effectiveContract 表(导出 → 契约 JSON,或 implicit 负缓存) | nudo contract 打印 / 契约读取冷启动 |
check | 整文件 CheckJson 报告 | 未变更文件在 nudo check 冷路径 —— 带 --from 时绝不读写(现场注入的证据不可作为整报告复用) |
键是内容寻址的:对源码 + 侧车 + 依赖内容 + 配置维度(如 contract.autoBind)取 sha256,并带分析 ABI 前缀(nudo-check-cache-v…+<version>,其中含 TypeScript 版本 —— 不是 package.json#version)。升级 @nudojs/* → 前缀变 → 整层干净 miss。改源码、侧车或任一依赖 → 键变 → 自然 miss。
fail-open 语义。 损坏的 JSON、ABI 不符、读不了的条目、被删的目录 —— 每种失败都是一次缓存 miss。分析重算;不抛任何东西;可观察行为完全一致。你随时可以 rm -rf .nudo/cache。被截断或 opaque 证据触及的条目绝不写入。
为什么默认关闭
一份结构合法的伪造 CheckJson 能制造假阴性 —— 被投毒的缓存可能藏掉真实违例。因此:只在可信机器 / CI 上开启;.nudo/cache 必须 gitignore;不可信 runner 上保持 nudo.cache 未设/false,或设 NUDO_CACHE_DIR=off。
条目签名(nudo.cache.sign: true + NUDO_CACHE_KEY)
给仍想用缓存的不可信 runner:打开逐条 HMAC-SHA256 签名。
// package.json —— 打开;秘密经 env 提供(CI secret,绝不入库)
{ "nudo": { "cache": { "sign": true } } }
# CI:打码 secret → env;check / contract / health 都读它
- run: pnpm exec nudo check src/
env:
NUDO_CACHE_KEY: ${{ secrets.NUDO_CACHE_KEY }}
- 每条条目带内容签名;验签失败(值被篡改、签名被剥、密钥不对)= miss —— 重算,绝不采信。伪造的「绿」过不了签名,进不了门禁。
- 签名与未签名条目键空间分离:轮换密钥(或开关签名)= 同路径干净的全量 miss —— 不脏命中、无孤儿要清理。
- 配置 fail-closed:
sign: true却没有NUDO_CACHE_KEY、或sign值不是布尔,check/contract/health拒绝运行(exit 1;--json面走既有信封)。安全旋钮绝不静默退回无签名。 - 密钥卫生:只放 env 或打码 CI secret —— 永不进仓库、绝不放进缓存目录本身。
依赖层(默认开启)
另一个跨项目缓存在 ~/.cache/nudo/deps(覆盖:NUDO_DEPS_CACHE_DIR;off / 0 关闭),存 @types harvest 的签名投影 —— 纯 JSON,绝不是 Abs 本体。默认开启、fail-open、跨项目共享 —— 重复分析的最大收益在这里。
缓存不加速什么
诚实边界:
- 服务的面:
contract打印 / 契约读取冷启动;opt-in 的check冷路径(未变更文件);harvest 依赖层。 - 不服务的面:
test/contract --emit/health的完整求值器分析;export的整条投影链。 - 绝不进盘:Abs 本体、AST、
PolyFn、AnalysisResult,以及截断 / opaque / mock 改道的分析结果。 --from(现场调用点证据)完全跳过CheckJson读写。
缓存让未变更文件的重复 check 在代数面上更便宜。它不是「让 Nudo 变快」的通用开关 —— 先看预算和契约。
CI:缓存目录要不要 restore?
- 默认配置:什么都不用 restore。 项目缓存关闭;
nudo check每次诚实重算。 - 可信 CI runner 上的推荐配置:打开项目缓存并在多次运行之间 restore
.nudo/cache。 键内容寻址(源码 + 侧车 + 依赖内容 + 配置维度的 sha256,带 ABI 前缀),restore 出来的层不可能给出陈旧或错误的结果 —— 最坏情况是干净 miss、诚实重算。始终 gitignore 该目录;绝不入库。契约文件(*.nudo.js)进 git;缓存不进。完整配方见下。 - 不可信 runner: 要么保持关闭 ——
nudo.cache: false(或不设)且NUDO_CACHE_DIR=off—— 要么打开条目签名(见上「条目签名」一节:cache.sign: true+ 打码 CI secret 的NUDO_CACHE_KEY),被篡改的缓存会诚实地 miss,而不是毒害门禁。 - 依赖层(
~/.cache/nudo/deps)才是 CI 值得弄的那层:默认开启、跨项目、纯签名投影。把NUDO_DEPS_CACHE_DIR指到 restore 出来的目录即可跨 job 复用 harvest 成果;陈旧或损坏的副本只会 miss。
可信 runner 配方(GitHub Actions)
在 package.json 里打开项目缓存(配置入库 —— 缓存目录绝不入库),并把目录加进 gitignore:
// package.json
{ "nudo": { "cache": true } } // → <projectRoot>/.nudo/cache
# .gitignore
.nudo/cache/
然后在门禁前 restore、门禁后 save:
# .github/workflows/nudo.yml —— 可信 runner
jobs:
nudo-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- run: pnpm install
# 先 restore。miss(首次运行、冷层)只是诚实重算。
- uses: actions/cache/restore@v4
with:
path: .nudo/cache
# 桶键 = lockfile + 受跟踪源码。它不必精确:nudo 的逐文件键
# (源码 + 侧车 + 依赖 + 配置的 sha256,带 ABI 前缀)负责真正
# 的失效判定;经 restore-keys 恢复的旧桶只会逐文件 miss。
key: nudo-check-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('src/**') }}
restore-keys: |
nudo-check-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
nudo-check-${{ runner.os }}-
- run: pnpm exec nudo check src/
# 保存本次运行产出的层。check exit 1 时自动跳过;想让红的运行也
# 回填就加 `if: always()` —— 条目是内容键寻址的整文件报告,不是裁决。
- uses: actions/cache/save@v4
with:
path: .nudo/cache
key: nudo-check-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('src/**') }}
把 src/**(与 lockfile 文件名)换成你实际 check 的布局。用单个 actions/cache@v4 步骤也可以 —— restore/save 拆开只是把保存变成显式、可加条件的步骤。不可信 runner 上不要照抄这份配方:结构合法的伪造 CheckJson 能制造假阴性 —— 在那里保持缓存关闭(nudo.cache: false / NUDO_CACHE_DIR=off),或加条目签名(见上「条目签名」)。
会话缓存上限(进程内 LRU)
与上面的磁盘缓存是两个不同的杠杆:每个 Nudo 进程内部都维护内存 LRU 缓存,服务热路径重分析 —— 整文件分析结果、逐函数分析、求值器 run。它们的条目数通过 package.json#nudo.sessionCache 封顶。这只是内存与 warm 命中之间的取舍,绝不是精度旋钮 —— 逐出只是诚实重算,结果与诊断完全不变。
键(nudo.sessionCache.*) | 环境变量 | 封什么 | 默认 |
|---|---|---|---|
maxFiles | NUDO_CACHE_MAX_FILES | 整文件分析结果 LRU 条目 | 64 |
maxFns | NUDO_CACHE_MAX_FNS | 逐函数分析 LRU 条目 | 1024 |
maxEvalRuns | NUDO_CACHE_MAX_EVALRUNS | 求值器 run LRU 条目 | 32 |
- 优先级:环境变量 >
package.json#nudo.sessionCache> 默认。0/off关闭该层;数值钳制到65,536。 - 多项目共用一个 IDE/LSP 进程时调低;大单仓可调高换 warm 命中。
- 与持久化磁盘缓存(上面的
nudo.cache/NUDO_CACHE_DIR)正交:会话上限随进程消失,绝不落盘。
配置速查
| 想要 | 设置 |
|---|---|
| 调高分支预算 | NUDO_MAX_FORKS=20000 或 package.json#nudo.analysis.maxForks |
| 每函数合并更多调用点 | package.json#nudo.analysis.callSiteBudget(1–64,默认 3) |
| 打开项目磁盘缓存 | package.json#nudo.cache: true(→ .nudo/cache) |
| 自定义缓存目录 | nudo.cache: ".nudo-cache" 或 NUDO_CACHE_DIR=/abs/path |
| 关闭依赖缓存 | NUDO_DEPS_CACHE_DIR=off |
| 封顶进程内会话缓存 | package.json#nudo.sessionCache.* / NUDO_CACHE_MAX_FILES · NUDO_CACHE_MAX_FNS · NUDO_CACHE_MAX_EVALRUNS |
完整配置表 —— 全部 package.json#nudo 键与 NUDO_* 变量 —— 见配置参考。
下一步
- 诊断 ——
nudo:recursion-truncated/nudo:fork-truncated - 边界与非目标
- nudo check
- CLI 参考