Paseo 協(xié)議校驗的 AOT 化改造基于 zod-aot 的 WebSocket 消息驗證實踐【免費下載鏈接】paseoOrchestrate multiple coding agents from desktop and mobile項目地址: https://gitcode.com/gh_mirrors/pa/paseoPaseo 在客戶端App / Desktop與 daemon 之間通過 WebSocket 傳遞結構化消息而移動端Hermes 運行時對每條入站消息的解析與校驗開銷直接決定會話流暢度。本文講解 Paseo 如何把 WebSocket 入站消息的熱路徑校驗從運行時 Zod 替換為 zod-aot 預編譯生成的驗證器覆蓋性能動因、運行時邊界、代碼生成歸屬、生命周期鉤子、回歸測試與 Schema 純凈性約定。讀完本文你將掌握一套以 Zod 為 Schema 唯一事實來源、以 AOT 生成代碼承擔運行時校驗的可落地工程方案。為什么要在熱路徑上放棄運行時 ZodPaseo 客戶端負責校驗所有入站 WebSocket 消息。早期實現(xiàn)直接使用 Zod 在運行時解析消息這在移動端Hermes上代價高昂。項目文檔 docs/protocol-validation.md 記錄了一組實測數(shù)據(jù)一條約 353 KB 的 provider snapshot 消息JSON.parse加運行時 Zod 校驗大約耗時10.9 ms、分配5.9 MB內(nèi)存將 provider-model 歸一化邏輯從 Schema 中移出、讓 zod-aot 可以編譯熱路徑子樹后生成驗證器路徑大約耗時2.5 ms、分配1.2 MB。也就是說僅把校驗從解釋執(zhí)行換成預編譯代碼單條大消息的時間與內(nèi)存開銷下降約 4~5 倍。這正是 Paseo 引入 AOT 校驗的核心動機Zod 仍然是 Schema 與 TypeScript 類型的唯一創(chuàng)作來源authoring source of truth但運行時不再解釋執(zhí)行 Zod而是執(zhí)行由 zod-aot 預先編譯出的原生 JavaScript 驗證器。需要說明的是上述數(shù)字來自項目內(nèi)部文檔的實測記錄具體收益會隨消息體積、設備與 Schema 復雜度變化但方向性結論——生成驗證器顯著優(yōu)于 Hermes 上的運行時 Zod——是穩(wěn)定成立的。運行時邊界ws-outbound.ts 是唯一發(fā)貨邊界Paseo 把入站消息驗證的發(fā)貨邊界收斂在一個文件 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直接調(diào)用生成驗證器的safeParse并原樣返回結果不做歸一化normalize、修復repair或二次校驗re-validate。未知鍵透傳生成的驗證器會保留 Schema 未聲明的未知鍵而 Zod 的對象解析默認會剝離它們。由于客戶端分發(fā)路徑只消費已知的type與 payload 字段這種透傳行為對入站消息是被接受的且線上線格式wire format沒有改變。兼容性 shim 外置provider-model 歸一化被實現(xiàn)為解析器側的兼容性 shim放在確實需要它的客戶端消費者中而較新的 daemon 在 provider registry 源頭就完成歸一化客戶端無需再做。從源碼結構可以推斷這個邊界文件刻意保持極薄真正的 Schema 定義在 packages/protocol/src/messages.tsWSOutboundMessage及其 schema生成代碼在 packages/protocol/src/generated/validation/ws-outbound.aot.tsgitignore不提交而驗證器只負責接線。代碼生成歸屬protocol 包獨占生成權AOT 生成不是 CI 或安裝期的黑盒而是由 protocol 包自己完整擁有。相關文件布局如下路徑角色packages/protocol/codegen/ws-outbound.compile.ts構建期 zod-aot 發(fā)現(xiàn)入口discovery entry對源 Schema 執(zhí)行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生成的運行時代碼gitignoredpackages/protocol/src/validation/ws-outbound-schema-metadata.ts運行時 Schema 元數(shù)據(jù)供 zod-aot 回退 / 默認值引用packages/protocol/tests/validation/ws-outbound.test.ts針對被補丁編譯器行為的回歸測試編譯入口compile 即發(fā)現(xiàn)ws-outbound.compile.ts 的完整內(nèi)容只有三行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()字段在分支內(nèi)生效動態(tài)import()zod-aot 的discoverSchemas/compileSchemas/generateCompiledFileContent以mode: inline編譯生成文件頭部自動加上// ts-nocheck再寫入src/generated/validation/ws-outbound.aot.ts。值得注意的是補丁的健壯性設計每次打補丁前都會先檢查目標代碼是否已包含補丁后的標記冪等同時校驗補丁前的原始形狀一旦 zod-aot 內(nèi)部實現(xiàn)變化導致匹配失敗會直接拋出 zod-aot emitter shape changed 之類的錯誤提示維護者更新補丁而不是悄悄生成錯誤代碼。為什么 zod-aot 要精確鎖定zod-aot 在 packages/protocol/package.json 中以精確版本鎖定zod-aot: 0.20.4無^。原因是該項目屬于較年輕的編譯器且 Paseo 已經(jīng)依賴其內(nèi)部實現(xiàn)打了兩個補丁。正如 packages/protocol/codegen/README.md 所寫對待補丁要像對待編譯器升級一樣——重新生成、審查產(chǎn)物、跑協(xié)議回歸測試后再發(fā)布。運行時 Schema 元數(shù)據(jù)ws-outbound-schema-metadata.ts 內(nèi)容也很簡潔import { WSOutboundMessageSchema as SourceWSOutboundMessageSchema } from ../messages.js; export const WSOutboundMessageSchema { schema: SourceWSOutboundMessageSchema };它把原始 Zod Schema暴露給生成代碼供 zod-aot 在需要回退到運行時引用如默認值計算時使用。也就是說生成代碼并非完全脫離 Zod而是大部分編譯成純 JavaScript、少量需要 Schema 元數(shù)據(jù)的地方引用源 Schema。生命周期鉤子生成只在需要時發(fā)生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構建、類型檢查、測試之前自動生成保證本地開發(fā)鏈路拿到的永遠是新鮮產(chǎn)物watch開發(fā)時并行運行驗證器 watcher 與 tsc watch。關鍵約束是安裝install不會觸發(fā)生成。發(fā)布包直接消費 protocol 的預構建dist而本地 build / typecheck / test 流程在真正需要的那一刻才生成源文件。這避免了安裝期依賴編譯器補丁也讓發(fā)布產(chǎn)物完全可復現(xiàn)。packages/protocol/src/generated/validation/README.md 還給出了手動生成命令npm run generate:validators --workspacegetpaseo/protocolwatch 模式實現(xiàn)指紋輪詢watch-validation-aot.mjs 沒有依賴文件系統(tǒng)事件庫而是實現(xiàn)了一個 1 秒間隔的指紋輪詢器遞歸收集src下所有.ts文件跳過generated目錄避免生成產(chǎn)物觸發(fā)自身重建計算每個文件相對路徑: mtimeMs: size拼接成的指紋指紋變化時 spawnnpm run generate:validators并用generateInFlight/generateAgain兩個標志做防重入生成進行中再有變更就標記一次待再生成結束后補跑避免丟失編輯?；貧w測試把補丁行為鎖進測試由于 zod-aot 是精確鎖定且相對年輕的編譯器本地補丁被視為 protocol 包的一部分tests/validation/ws-outbound.test.ts 為被打補丁的場景維護了小型回歸測試。文檔列出的四類核心用例discriminated-union 分支輸出必須傳播.default()字段測試通過臨時目錄內(nèi)聯(lián)一段帶z.boolean().default(true)的 discriminatedUnion Schema現(xiàn)場走一遍 discover→compile→generate 流程斷言{ type: with_default }解析后得到enabled: true。這直接對應上文提到的 discriminated-union 輸出補丁。當前順序條目路由必須接受tool_call風格的 status 分支構造type: tool_callstatus: running/completed/failed/canceled的四種組合驗證嵌套在z.union中的 discriminatedUnion 都能被正確路由解析。生成運行時 import 必須保留.js擴展名直接讀取生成的.aot.ts文件內(nèi)容斷言包含from ../../validation/ws-outbound-schema-metadata.js保證打包后的 Node ESM 可解析。這對應運行時 import 擴展名補丁。生成信封接受最小合法消息、拒絕損壞消息{ type: pong }通過{ type: not_a_message }失敗。測試文件還覆蓋了更多真實業(yè)務信封project config 響應帶或不帶hasUncommittedWorktreeSetupChanges、緊湊 provider snapshotget_providers_snapshot_response、注意力通知agent_attention_required與agent_stream內(nèi)的attention_required事件、forge.search.response以及舊版github_search_response。其中緊湊 provider snapshot 的斷言使用了toEqual全等比較進一步驗證生成驗證器不剝離任何字段的透傳語義。此外測試里的compileInlineSchema輔助函數(shù)通過mkdtemp建臨時目錄、用 jiti 動態(tài)加載生成的驗證器實現(xiàn)了針對任意內(nèi)聯(lián) Schema 片段現(xiàn)場編譯并驗證行為的能力——這讓補丁回歸測試不依賴真實消息 Schema 的變化穩(wěn)定且獨立。Schema 純凈性給 Schema 作者的三條紀律為了讓 AOT 生成穩(wěn)定可預測項目對 WebSocket 消息 Schema 的寫法有明確約束見 docs/protocol-validation.md消息 Schema 必須是結構聲明禁止在 WebSocket 消息 Schema 上使用.transform()、.catch()、.preprocess()。如果解析后的數(shù)據(jù)需要歸一化放進顯式的消費者或校驗后的 pass 中處理。這正是 provider-model 歸一化被移出 Schema 的原因——它曾阻礙 zod-aot 編譯熱路徑子樹。優(yōu)先z.discriminatedUnion()只要每個分支都有共享的字面量標簽如type、status就必須用z.discriminatedUnion()只有不存在共享字面量判別器或有生成代碼回歸測試證明某特定形狀被錯誤編譯時才允許使用普通z.union()。這是為了讓生成器能生成高效的逐分支路由代碼。默認值只能放在原始類型葉子節(jié)點不要把.default()放在大數(shù)組、條目 Schema 或大容器上。入站消息的.default()只允許出現(xiàn)在原始類型葉子字段避免生成器在容器級別做昂貴的默認值處理。從測試用例可以印證第一條與第二條的實際落地tool_call 測試中ToolCallItemSchema用status做 discriminator 的 discriminatedUnion外層再包z.union組合不同消息類型——這正是有共享字面量標簽就用 discriminatedUnion沒有共享標簽的組合層才用 union的典型寫法。結語一條可持續(xù)演進的校驗架構Paseo 的協(xié)議校驗方案可以總結為一條清晰的價值鏈創(chuàng)作層Zod Schema 是唯一事實來源保持純凈的結構聲明編譯層protocol 包在 build/typecheck/test/watch 生命周期中用精確鎖定的 zod-aot 加上兩處本地補丁把熱路徑 Schema 預編譯為內(nèi)聯(lián) JavaScript運行時層客戶端只經(jīng)過 ws-outbound.ts 這一薄邊界調(diào)用生成驗證器不校驗之外的任何額外工作質(zhì)量層回歸測試把補丁行為、.js擴展名、信封合法/非法判定全部固化下來升級編譯器時必須重新生成 審查產(chǎn)物 跑回歸。對于任何需要在移動端或低性能運行時上承載高頻結構化消息校驗的 TypeScript 項目這套Zod 創(chuàng)作 AOT 生成 薄邊界 回歸鎖定的架構都是一份可直接借鑒的工程樣板。更多背景可進一步閱讀 docs/protocol-validation.md、packages/protocol/codegen/README.md 與 packages/protocol/src/generated/validation/README.md?！久赓M下載鏈接】paseoOrchestrate multiple coding agents from desktop and mobile項目地址: https://gitcode.com/gh_mirrors/pa/paseo創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考