用途:这是一个针对 TypeScript 应用中 Zod schema 代码的正确性与版本时效门禁。它不提供建议式反馈,而是给出可判定的 PASS/FAIL:由单个盲评审子代理按既定规则以对抗立场审查,只有每条规则均为 PASS 或 N/A 时整体才通过。技能只产出裁决,不修复代码。
适用与不适用:适用于即将合并、定义或修改 Zod schema 的 diff 或功能;适用于需要独立核查 AI 代理生成的 schema 代码是否沿用 Zod 3 模式;适用于声称完成 Zod 3 到 4 迁移、需要审计静默语义破坏的场景;也适用于用 Zod 校验服务端函数输入或搜索参数的 TanStack Start 应用。不适用于 Zod 3 代码库(会中止并报告 GATE NOT APPLICABLE),也不适用于想要解释与重构而非裁决的需求。两条 start- 规则在非 TanStack 应用中为 N/A,其余规则可用于任何使用 Zod 4 的 TypeScript 项目。
评审流程:先确定被评审对象并固定 ref 与路径,目标路径须包含 package.json,因为 Zod 4 前置条件和 pkg-、compose-native-json-schema、start- 适配器规则由其依赖版本决定;再加载 references/_sections.md 与 references/ 下全部规则文件(sem-、gone-、err-、dep-、compose-、start-、pkg-*);然后按 references/reviewer-prompt.md 组装完全自包含的评审提示词;派发单个盲评审 Task 子代理,输入仅是该提示词;最后 fail-closed 渲染裁决,任一 FAIL 即整体失败,不做加权、平均或豁免,若返回 GATE NOT APPLICABLE 则停止并报告。
裁决格式与规则类别:评审者逐条返回 PASS、FAIL 或 N/A,附证据(file:line 或引用,PASS 也需证据),并对每个 FAIL 给出可落实的修复项及其位置。最终报告按 assets/templates/verdict.md 输出。规则分七类:sem- 静默语义破坏(如 .prefault()、z.partialRecord()、z.stringbool())、gone- 已移除 API(如 .ip()/.cidr()、单参 z.record()、error 参数三件套、.errors getter、z.interface() 幻觉)、err- 错误定制与格式化(统一 error 参数、z.treeifyError/z.flattenError/z.prettifyError)、dep- 弃用写法(顶层字符串格式、z.strictObject/z.looseObject、用 .extend 替代 .merge、z.enum 替代 z.nativeEnum、z.int()、无 z.promise())、compose- 组合递归与编解码(getter 递归、z.codec()、原生 z.toJSONSchema())、start- TanStack Start 集成(裸 schema 传给 .validator()、无适配器的 validateSearch)、pkg- 打包与导入(根 "zod" 导入路径,zod/mini 仅用于严格体积约束)。
限制:规则固定于 zod 4.4.x 与(start- 类)TanStack Start v1 RC;若同一条规则在未变更目标上多次翻转裁决,或人工推翻裁决,应记录到 gotchas.md 并收紧规则,而非绕过门禁。相关技能:zod(教学式精讲,用于解释或重构)、adversarial-tanstack(框架级门禁,可与本技能在 Start diff 上同时运行)。