Paseo 协议校验的 AOT 化改造：基于 zod-aot 的 WebSocket 消息验证实践-平芜编程栈

Paseo 协议校验的 AOT 化改造：基于 zod-aot 的 WebSocket 消息验证实践

【免费下载链接】paseoOrchestrate multiple coding agents from desktop and mobile项目地址: https://gitcode.com/gh_mirrors/pa/paseo

Paseo 在客户端（App / Desktop）与 daemon 之间通过 WebSocket 传递结构化消息，而移动端（Hermes 运行时）对每条入站消息的解析与校验开销直接决定会话流畅度。本文讲解 Paseo 如何把 WebSocket 入站消息的热路径校验从运行时 Zod 替换为 zod-aot 预编译生成的验证器，覆盖性能动因、运行时边界、代码生成归属、生命周期钩子、回归测试与 Schema 纯净性约定。读完本文，你将掌握一套"以 Zod 为 Schema 唯一事实来源、以 AOT 生成代码承担运行时校验"的可落地工程方案。

为什么要在热路径上放弃运行时 Zod

Paseo 客户端负责校验所有入站 WebSocket 消息。早期实现直接使用 Zod 在运行时解析消息，这在移动端（Hermes）上代价高昂。项目文档 docs/protocol-validation.md 记录了一组实测数据：

一条约 353 KB 的 provider snapshot 消息，JSON.parse加运行时 Zod 校验大约耗时10.9 ms、分配5.9 MB内存；
将 provider-model 归一化逻辑从 Schema 中移出、让 zod-aot 可以编译热路径子树后，生成验证器路径大约耗时2.5 ms、分配1.2 MB。

也就是说，仅把校验从解释执行换成预编译代码，单条大消息的时间与内存开销下降约 4~5 倍。这正是 Paseo 引入 AOT 校验的核心动机：Zod 仍然是 Schema 与 TypeScript 类型的唯一创作来源（authoring source of truth），但运行时不再解释执行 Zod，而是执行由 zod-aot 预先编译出的原生 JavaScript 验证器。

需要说明的是，上述数字来自项目内部文档的实测记录，具体收益会随消息体积、设备与 Schema 复杂度变化，但方向性结论——生成验证器显著优于 Hermes 上的运行时 Zod——是稳定成立的。

运行时边界：ws-outbound.ts 是唯一发货边界

Paseo 把入站消息验证的"发货边界"收敛在一个文件： packages/protocol/src/validation/ws-outbound.ts。

import type { z } from "zod"; import { WSOutboundMessageSchema } from "../generated/validation/ws-outbound.aot.js"; import type { WSOutboundMessage } from "../messages.js"; type WSOutboundValidationResult = | { success: true; data: WSOutboundMessage } | { success: false; error: z.ZodError }; interface WSOutboundGeneratedValidator { safeParse(input: unknown): WSOutboundValidationResult; } // zod-aot 生成的是运行时代码，不携带 TypeScript 类型表面， // 因此在这里做一次接口层面的断言。 const wsOutboundValidator = WSOutboundMessageSchema as WSOutboundGeneratedValidator; export function validateWSOutboundMessage(input: unknown): WSOutboundValidationResult { return wsOutboundValidator.safeParse(input); }

几个关键设计点：

只校验、不修理：validateWSOutboundMessage直接调用生成验证器的safeParse并原样返回结果，不做归一化（normalize）、修复（repair）或二次校验（re-validate）。
未知键透传：生成的验证器会保留 Schema 未声明的未知键，而 Zod 的对象解析默认会剥离它们。由于客户端分发路径只消费已知的type与 payload 字段，这种透传行为对入站消息是被接受的，且线上线格式（wire format）没有改变。
兼容性 shim 外置：provider-model 归一化被实现为"解析器侧的兼容性 shim"，放在确实需要它的客户端消费者中；而较新的 daemon 在 provider registry 源头就完成归一化，客户端无需再做。

从源码结构可以推断，这个边界文件刻意保持极薄：真正的 Schema 定义在 packages/protocol/src/messages.ts（WSOutboundMessage及其 schema），生成代码在 packages/protocol/src/generated/validation/ws-outbound.aot.ts（gitignore，不提交），而验证器只负责"接线"。

代码生成归属：protocol 包独占生成权

AOT 生成不是 CI 或安装期的黑盒，而是由 protocol 包自己完整拥有。相关文件布局如下：

路径	角色
packages/protocol/codegen/ws-outbound.compile.ts	构建期 zod-aot 发现入口（discovery entry），对源 Schema 执行`compile()`
packages/protocol/scripts/generate-validation-aot.mjs	运行精确锁定（exact-pinned）的编译器，并在生成前应用两处本地编译器补丁
packages/protocol/scripts/watch-validation-aot.mjs	编辑 protocol 源码时自动重跑生成
packages/protocol/src/generated/validation/ws-outbound.aot.ts	生成的运行时代码，gitignored
packages/protocol/src/validation/ws-outbound-schema-metadata.ts	运行时 Schema 元数据，供 zod-aot 回退 / 默认值引用
packages/protocol/tests/validation/ws-outbound.test.ts	针对被补丁编译器行为的回归测试

编译入口：compile 即发现

ws-outbound.compile.ts 的完整内容只有三行：

import { compile } from "zod-aot"; import { WSOutboundMessageSchema as SourceWSOutboundMessageSchema } from "../src/messages.js"; export const WSOutboundMessageSchema = compile(SourceWSOutboundMessageSchema);

zod-aot 的discoverSchemas会扫描该文件的compile()导出，从而找到需要生成验证器的 Schema。

生成脚本：先打补丁，再生成

generate-validation-aot.mjs 的流程是：

通过require.resolve("zod-aot")定位编译器安装根目录；
应用两处本地编译器补丁：
- 运行时 import 扩展名补丁：修改 emitter，使生成的 import 路径在源路径以.js结尾时保留.js扩展名（否则剥离扩展名），保证打包后的 Node ESM 能正确解析；
- discriminated-union 输出补丁：修改 discriminated-union 的代码生成器，当任一分支存在变更（如.default()）时，把分支输出对象回写到输出变量，从而让.default()字段在分支内生效；
动态import()zod-aot 的discoverSchemas/compileSchemas/generateCompiledFileContent；
以mode: "inline"编译，生成文件头部自动加上// @ts-nocheck，再写入src/generated/validation/ws-outbound.aot.ts。

值得注意的是补丁的健壮性设计：每次打补丁前都会先检查目标代码是否已包含补丁后的标记（幂等），同时校验补丁前的原始形状，一旦 zod-aot 内部实现变化导致匹配失败，会直接抛出 "zod-aot emitter shape changed" 之类的错误，提示维护者更新补丁，而不是悄悄生成错误代码。

为什么 zod-aot 要精确锁定

zod-aot 在 packages/protocol/package.json 中以精确版本锁定（"zod-aot": "0.20.4"，无^）。原因是该项目属于较年轻的编译器，且 Paseo 已经依赖其内部实现打了两个补丁。正如 packages/protocol/codegen/README.md 所写：对待补丁要像对待编译器升级一样——重新生成、审查产物、跑协议回归测试后再发布。

运行时 Schema 元数据

ws-outbound-schema-metadata.ts 内容也很简洁：

import { WSOutboundMessageSchema as SourceWSOutboundMessageSchema } from "../messages.js"; export const WSOutboundMessageSchema = { schema: SourceWSOutboundMessageSchema };

它把原始 Zod Schema暴露给生成代码，供 zod-aot 在需要回退到运行时引用（如默认值计算）时使用。也就是说：生成代码并非完全脱离 Zod，而是"大部分编译成纯 JavaScript、少量需要 Schema 元数据的地方引用源 Schema"。

生命周期钩子：生成只在需要时发生

packages/protocol/package.json 中的 scripts 展示了生成时机：

"scripts": { "generate:validators": "node scripts/generate-validation-aot.mjs", "watch": "concurrently --kill-others --names validation,tsc ... \"node scripts/watch-validation-aot.mjs\" ...", "prebuild": "npm run generate:validators", "pretypecheck": "npm run generate:validators", "pretest": "npm run generate:validators" }

prebuild/pretypecheck/pretest：构建、类型检查、测试之前自动生成，保证本地开发链路拿到的永远是新鲜产物；
watch：开发时并行运行验证器 watcher 与 tsc watch。

关键约束是：安装（install）不会触发生成。发布包直接消费 protocol 的预构建dist，而本地 build / typecheck / test 流程在真正需要的那一刻才生成源文件。这避免了安装期依赖编译器补丁，也让发布产物完全可复现。

packages/protocol/src/generated/validation/README.md 还给出了手动生成命令：

npm run generate:validators --workspace=@getpaseo/protocol

watch 模式实现：指纹轮询

watch-validation-aot.mjs 没有依赖文件系统事件库，而是实现了一个 1 秒间隔的指纹轮询器：

递归收集src下所有.ts文件（跳过generated目录，避免生成产物触发自身重建）；
计算每个文件相对路径: mtimeMs: size拼接成的指纹；
指纹变化时 spawnnpm run generate:validators，并用generateInFlight/generateAgain两个标志做防重入：生成进行中再有变更就标记一次"待再生成"，结束后补跑，避免丢失编辑。

回归测试：把补丁行为锁进测试

由于 zod-aot 是精确锁定且相对年轻的编译器，本地补丁被视为 protocol 包的一部分，tests/validation/ws-outbound.test.ts 为被打补丁的场景维护了小型回归测试。文档列出的四类核心用例：

discriminated-union 分支输出必须传播.default()字段：测试通过临时目录内联一段带z.boolean().default(true)的 discriminatedUnion Schema，现场走一遍 discover→compile→generate 流程，断言{ type: "with_default" }解析后得到enabled: true。这直接对应上文提到的 discriminated-union 输出补丁。
当前顺序条目路由必须接受tool_call风格的 status 分支：构造type: "tool_call"+status: running/completed/failed/canceled的四种组合，验证嵌套在z.union中的 discriminatedUnion 都能被正确路由解析。
生成运行时 import 必须保留.js扩展名：直接读取生成的.aot.ts文件内容，断言包含from "../../validation/ws-outbound-schema-metadata.js"，保证打包后的 Node ESM 可解析。这对应运行时 import 扩展名补丁。
生成信封接受最小合法消息、拒绝损坏消息：{ type: "pong" }通过，{ type: "not_a_message" }失败。

测试文件还覆盖了更多真实业务信封：project config 响应（带或不带hasUncommittedWorktreeSetupChanges）、紧凑 provider snapshot（get_providers_snapshot_response）、注意力通知（agent_attention_required与agent_stream内的attention_required事件）、forge.search.response以及旧版github_search_response。其中紧凑 provider snapshot 的断言使用了toEqual（全等比较），进一步验证生成验证器不剥离任何字段的透传语义。

此外，测试里的compileInlineSchema辅助函数通过mkdtemp建临时目录、用 jiti 动态加载生成的验证器，实现了"针对任意内联 Schema 片段现场编译并验证行为"的能力——这让补丁回归测试不依赖真实消息 Schema 的变化，稳定且独立。

Schema 纯净性：给 Schema 作者的三条纪律

为了让 AOT 生成稳定可预测，项目对 WebSocket 消息 Schema 的写法有明确约束（见 docs/protocol-validation.md）：

消息 Schema 必须是结构声明：禁止在 WebSocket 消息 Schema 上使用.transform()、.catch()、.preprocess()。如果解析后的数据需要归一化，放进显式的消费者或校验后的 pass 中处理。这正是 provider-model 归一化被移出 Schema 的原因——它曾阻碍 zod-aot 编译热路径子树。
优先z.discriminatedUnion()：只要每个分支都有共享的字面量标签（如type、status），就必须用z.discriminatedUnion()；只有不存在共享字面量判别器，或有生成代码回归测试证明某特定形状被错误编译时，才允许使用普通z.union()。这是为了让生成器能生成高效的逐分支路由代码。
默认值只能放在原始类型叶子节点：不要把.default()放在大数组、条目 Schema 或大容器上。入站消息的.default()只允许出现在原始类型叶子字段，避免生成器在容器级别做昂贵的默认值处理。

从测试用例可以印证第一条与第二条的实际落地：tool_call 测试中ToolCallItemSchema用status做 discriminator 的 discriminatedUnion，外层再包z.union组合不同消息类型——这正是"有共享字面量标签就用 discriminatedUnion，没有共享标签的组合层才用 union"的典型写法。

结语：一条可持续演进的校验架构

Paseo 的协议校验方案可以总结为一条清晰的价值链：

创作层：Zod Schema 是唯一事实来源，保持纯净的结构声明；
编译层：protocol 包在 build/typecheck/test/watch 生命周期中，用精确锁定的 zod-aot 加上两处本地补丁，把热路径 Schema 预编译为内联 JavaScript；
运行时层：客户端只经过 ws-outbound.ts 这一薄边界调用生成验证器，不校验之外的任何额外工作；
质量层：回归测试把补丁行为、.js扩展名、信封合法/非法判定全部固化下来，升级编译器时必须"重新生成 + 审查产物 + 跑回归"。

对于任何需要在移动端或低性能运行时上承载高频结构化消息校验的 TypeScript 项目，这套"Zod 创作 + AOT 生成 + 薄边界 + 回归锁定"的架构都是一份可直接借鉴的工程样板。更多背景可进一步阅读 docs/protocol-validation.md、packages/protocol/codegen/README.md 与 packages/protocol/src/generated/validation/README.md。

【免费下载链接】paseoOrchestrate multiple coding agents from desktop and mobile项目地址: https://gitcode.com/gh_mirrors/pa/paseo

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考