背景为什么工具调用的 JSON 校验会卡住生产 AgentAgent 的核心循环是「LLM → 结构化输出 → 校验 → 执行/重试」。当 LLM 返回一个工具调用时框架拿到的是一段文本形式的 JSON或 tool_use block需要1.解析成 JS 对象JSON.parse2.校验是否符合该工具的输入 schema字段类型、枚举值、嵌套结构3.通过则执行工具拒绝则生成错误反馈喂回 LLM 重试即 validation sandwich 模式第 2 步就是本文聚焦的环节。2026 年主流方案有四种方案特点典型使用场景AJV预编译 schema 为验证函数运行时极快高频中间件、流式校验ZodTypeScript-first类型推断完美DX 极佳全栈 TS 项目、API 入参校验Valibot零依赖、tree-shakeable体积小单文件 CLI 工具、bundle 敏感场景手写校验零依赖零开销但每个工具要重写性能极致敏感的热路径问题在于这四者在「正确性」上没有区别——只要 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.2managed runtimeWindows 11warmup 10 万次后取 5 轮中位数。每个 validator 对同一份合法入参跑 80 万次。# 复现命令 cd csdn_auto/2026-08-04-noon NODE_PATHworkspace/node_modules node bench_validate.cjs核心数据如下表单位万 ops/s越大越好校验器合法入参吞吐相对 Zod 倍数AJV3558×41手写校验1094×13Valibot128×1.5Zod86基准图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 对象即便 successtrue 也分配了对象遍历整棵 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 模式。我测量了「校验 生成错误反馈」的组合吞吐对非法入参校验器拒绝反馈吞吐万 ops/s相对 Zod 倍数手写校验472×54AJV60.5×7Valibot11.5×1.3Zod8.7基准图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µsAJV 花费约0.03µs。而 LLM 推理一次需要数百毫秒到数秒。即使你的 Agent 一分钟调用 100 次工具校验总耗时Zod ~0.12msAJV ~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 复杂度梯度本次用的是中小型 schema6 个顶层字段 1 个嵌套数组。超大型 schema20 字段、深层嵌套、$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. · GitHubGitHub 组织主页wangzifan396-wzf (WangZi) · GitHub
背景为什么工具调用的 JSON 校验会卡住生产 AgentAgent 的核心循环是「LLM → 结构化输出 → 校验 → 执行/重试」。当 LLM 返回一个工具调用时框架拿到的是一段文本形式的 JSON或 tool_use block需要1.解析成 JS 对象JSON.parse2.校验是否符合该工具的输入 schema字段类型、枚举值、嵌套结构3.通过则执行工具拒绝则生成错误反馈喂回 LLM 重试即 validation sandwich 模式第 2 步就是本文聚焦的环节。2026 年主流方案有四种方案特点典型使用场景AJV预编译 schema 为验证函数运行时极快高频中间件、流式校验ZodTypeScript-first类型推断完美DX 极佳全栈 TS 项目、API 入参校验Valibot零依赖、tree-shakeable体积小单文件 CLI 工具、bundle 敏感场景手写校验零依赖零开销但每个工具要重写性能极致敏感的热路径问题在于这四者在「正确性」上没有区别——只要 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.2managed runtimeWindows 11warmup 10 万次后取 5 轮中位数。每个 validator 对同一份合法入参跑 80 万次。# 复现命令 cd csdn_auto/2026-08-04-noon NODE_PATHworkspace/node_modules node bench_validate.cjs核心数据如下表单位万 ops/s越大越好校验器合法入参吞吐相对 Zod 倍数AJV3558×41手写校验1094×13Valibot128×1.5Zod86基准图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 对象即便 successtrue 也分配了对象遍历整棵 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 模式。我测量了「校验 生成错误反馈」的组合吞吐对非法入参校验器拒绝反馈吞吐万 ops/s相对 Zod 倍数手写校验472×54AJV60.5×7Valibot11.5×1.3Zod8.7基准图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µsAJV 花费约0.03µs。而 LLM 推理一次需要数百毫秒到数秒。即使你的 Agent 一分钟调用 100 次工具校验总耗时Zod ~0.12msAJV ~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 复杂度梯度本次用的是中小型 schema6 个顶层字段 1 个嵌套数组。超大型 schema20 字段、深层嵌套、$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. · GitHubGitHub 组织主页wangzifan396-wzf (WangZi) · GitHub
