背景：为什么工具调用的 JSON 校验会卡住生产 Agent

Agent 的核心循环是「LLM → 结构化输出 → 校验 → 执行/重试」。当 LLM 返回一个工具调用时，框架拿到的是一段文本形式的 JSON（或 tool_use block），需要：

1.解析成 JS 对象（JSON.parse）

2.校验是否符合该工具的输入 schema（字段类型、枚举值、嵌套结构）

3.通过则执行工具，拒绝则生成错误反馈喂回 LLM 重试（即 validation sandwich 模式）

第 2 步就是本文聚焦的环节。2026 年主流方案有四种：

问题在于：这四者在「正确性」上没有区别——只要 schema 写对，它们都能拦下非法入参。真正的差异藏在运行时吞吐和错误反馈成本里，而这恰恰是大多数团队从未量化过的。

图1：校验器站在 LLM 输出和工具执行之间。通过则进入下一步，拒绝则走 validation sandwich 回环重试。一次性编译成本均 sub-ms。

解剖：四种校验器在 Agent 循环里各在哪一层干活

为了公平对比，我构造了一个真实 Agent 工具调用的 arguments 对象——模拟一个知识库检索工具，包含字符串查询、整数 top_k、filter 数组（含枚举 op）、布尔开关、枚举 mode 和可选分页对象。同时准备了一个故意非法的变体：top_k 变字符串、filters 缺 required 字段 op、多了未知 key、mode 不在枚举内。

四种校验器的实现方式各不相同：

• AJV：先ajv.compile(schema)产出预编译函数，之后每次调用只执行这个函数。编译是一次性的（sub-ms），后续调用接近裸函数速度。
• Zod：用z.object({...}).strict()定义 schema，每次调用safeParse(o).success。schema 定义本身很轻（~0.007ms），但 safeParse 内部做了完整的类型遍历和结果对象构建。
• Valibot：类似 Zod 但设计为 tree-shakeable，用v.object(...)+v.parse(...)或 try/catch。无外部依赖。
• 手写校验：直接写 if/typeof/Array.isArray 判断。最快但不可复用——每个新工具都要重写一遍。

关键区别：AJV 把「理解 schema」的成本前置到编译阶段，而 Zod/Valibot 在每次调用时都重新遍历 schema 树。这在单次调用上微不足道，但在高频热路径中会被放大。

实证：同条件跑出来的真实吞吐

测试环境：Node v22.22.2（managed runtime），Windows 11，warmup 10 万次后取 5 轮中位数。每个 validator 对同一份合法入参跑 80 万次。

# 复现命令 cd csdn_auto/2026-08-04-noon NODE_PATH=<workspace>/node_modules node bench_validate.cjs

核心数据如下表（单位：万 ops/s，越大越好）：

图2：合法入参吞吐（对数刻度）。AJV 以 3558 万 ops/s 领先，Zod 仅 86 万——差距 41 倍。手写校验居中，Valibot 略优于 Zod。

几个值得注意的点：

1.AJV 的预编译优势是实打实的：compile 一次后，validate 就是一个紧凑的 JIT 友好函数。3558 万 ops/s 意味着每次校验约 0.028µs——基本上就是一次属性查表。

2.Zod 的 safeParse 做了很多「隐形工作」：它构建完整的 ParseResult 对象（即便 success=true 也分配了对象），遍历整棵 schema 树做类型检查。这些 DX 上的便利在吞吐上付出了 ~41 倍的代价。

3.Valibot 比 Zod 快约 50%（128 vs 86 万），因为它的内部实现更精简，且不构建完整的结果对象（直接 throw on failure）。

4.手写校验慢于 AJV 约 3.25 倍（1094 < 3558），因为 AJV 编译出的函数经过高度优化，而手写版本用了 Set 和多次 typeof 检查，JIT 优化空间不如 AJV 的编译产物。

正确性自检全部通过：四家对合法入参返回 true，对非法入参返回 false，无一误判。

实证二：拒绝路径与「重试反馈」才是 Zod 的真正代价

合法入参只是故事的一半。在生产 Agent 中，拒绝路径往往更有意义——因为当模型吐出非法 JSON 时，你需要快速判断并生成可读的错误信息喂回 LLM 触发重试（validation sandwich 模式）。

我测量了「校验 + 生成错误反馈」的组合吞吐（对非法入参）：

图3：拒绝路径加上错误信息格式化后的吞吐。Zod 因为需要构建完整 issues 树再序列化，跌到仅 8.7 万 ops/s。

这里的故事变了：

• 手写校验反超成为最快（472 万 ops/s）：因为它在第一次失败处立即 return，错误消息是预先写好的简单字符串拼接，几乎零额外开销。
• AJV 从 3558 万骤降到 60.5 万（~59×）：因为allErrors: true模式下它会扫描整个对象收集所有错误，然后JSON.stringify(errors)序列化错误数组。这是有意义的开销，但仍然比 Zod 快 7 倍。
• Zod 跌到 8.7 万：safeParse失败时构建了一棵完整的ZodErrorissue 树（包含 path、code、message、expected/received 等），再JSON.stringify(issues)。这棵树的信息量丰富，但构建成本高昂。
• Valibot 11.5 万：介于两者之间，异常消息相对简洁。

如果你用了 validation sandwich（失败→带错重试），Zod 的 DX 优势在 rejection path 上变成了吞吐劣势。这不是 Zod 的 bug——它是为「开发时类型安全」设计的，而不是为「每秒百万次热路径校验」设计的。

局限：41 倍在哪儿才真的要命，哪儿可以忽略

坦率讲，在绝大多数 Agent 循环中，这 41 倍差距可以忽略。原因很简单：

• 一个典型的 Agent 工具调用校验，Zod 花费约1.2µs，AJV 花费约0.03µs。
• 而 LLM 推理一次需要数百毫秒到数秒。
• 即使你的 Agent 一分钟调用 100 次工具，校验总耗时：Zod ~0.12ms，AJV ~0.003ms。差异对用户不可感知。

41 倍只在以下场景被放大：

1.高频中间件 / API 网关：如果你的校验层每秒处理数十万请求（比如 rate limiter、WAF 规则引擎），41 倍从 µs 级累积到 ms 级，影响 p99 尾延迟。

2.流式工具调用校验：某些 Agent 框架在 LLM 流式输出时就逐 chunk 校验 schema 合法性（提前拦截明显非法的输出），这种场景校验频率远高于最终调用次数。

3.单文件 CLI 工具：bundle 体积敏感。Zod/AJV 引入运行时依赖，Valibot 可 tree-shake 到只保留用到的校验器，手写为零依赖。（本次未单独测 bundle 体积，属已知特性。）

4.子进程 per-step 架构：如果每个 Agent 步骤 fork 一个新进程（某些沙箱架构如此），AJV 的 compile 成本虽然 sub-ms 但仍需每次进程启动时支付；Zod/Valibot 的 schema 构建同理。手写无此成本。

本次未覆盖的维度：

• Bundle 体积（gzip 后大小）：未用 bundler 测量，仅定性引用已知特性。
• Schema 复杂度梯度：本次用的是中小型 schema（6 个顶层字段 + 1 个嵌套数组）。超大型 schema（20+ 字段、深层嵌套、$ref）可能改变相对排名。
• TypeScript 类型推断收益：Zod 的 Infer<> 类型推导在开发时的价值无法用 ops/s 衡量。

结论与下一步

一句话方法论：正常 Agent 循环按 DX 选 Zod 或 Valibot（类型安全 + 错误信息丰富）；如果校验落在高频热路径（中间件、流式校验、单文件工具），换 AJV 或手写——41 倍的差距在那里会从「看不见」变成「看得见」。

选型决策树：

• 需要 TS 类型推断 + 开发体验 →Zod
• 零依赖 + tree-shakeable + 单文件友好 →Valibot
• 吞吐极致 + 已有 JSON Schema →AJV
• 极致性能 + 工具数量少且固定 →手写

开源地址：

• 矩阵门户：GitHub - wangzifan396-wzf/WB: nano-tools: 400+ single-file, zero-dependency, local-first web utilities in one portal. Offline and private, nothing leaves your browser. Binary & protocol parsers, crypto, dev, audio, visualization, productivity. · GitHub
• 单文件工具聚合器：GitHub - wangzifan396-wzf/nano-workbench: Single-file tabbed launcher for the nano-tools matrix - one tab, all 28 tools, instant switch. Zero-dep. Part of nano-tools. · GitHub
• GitHub 组织主页：wangzifan396-wzf (WangZi) · GitHub