zod

用途

该技能面向 Zod 4 的 schema 实现、审查与调试，仅在请求涉及 Zod 解析、类型转换、结构化错误等运行时契约时启用。它把一个边界问题拆成可验证的步骤，避免把表单生命周期、鉴权、UI 或传输层故障混入校验逻辑。

主要能力

• 确认有效契约：检查实际安装的 Zod 版本、导入路径、TypeScript 配置以及相关适配器声明。技能以 Zod 4 为目标，使用包根或 zod/v4 作为 Classic 入口；仅当代码有意使用 Mini 的函数式 API 时才用 Mini 入口。对 Zod 4 期间新增的 API 需做能力检查，不能仅凭主版本号假定所有小版本都提供。
• 定义边界契约：编码前记录不可信来源与原始表示、解析后输出及其是线格式还是领域值、未知对象键的 strip/reject/preserve/catchall 策略、同步或异步解析、失败是抛出、局部分支还是转为适配器错误、是否需要反向编码或生成 JSON Schema。建议在外部边界使用 unknown，解析一次后向内传递，直到下一个信任边界；与边界有效性无关的独立领域规则应留在 schema 外。
• 按需加载参考：涵盖导入与能力、类型与解析、对象与细化、错误、联合/记录/枚举、元数据与 JSON Schema、Classic 与 Mini 及性能等主题。
• 实现最小完整模式：提供一个使成功值与失败路径都可观察的 schema 和调用方；当转换改变表示时保留 z.input 与 z.output；为适配器提供其支持的契约，不假设校验同时提供转换输出、异步解析或期望的错误形状。涉及 React Hook Form 时只展示 Zod 输入/输出交接，默认值、脏状态与提交生命周期归该组件负责；涉及 TanStack Query 时让 HTTP 与解析失败使查询函数 reject，重试、缓存与渲染策略归 Query/前端负责。
• 验证可观察行为：针对有效与无效输入运行精确入口用例，再执行相关类型检查与测试，覆盖缺失/空值、多余键、歧义原始字符串、转换输出与 issue 路径；只要有嵌套异步效果，就端到端使用异步解析。若回复被要求提供检查，应包含可运行的成败断言，并标注未执行的检查。对生成物需断言方向、方言、必需键、对象策略、元数据与引用；对 Mini 或性能改动需在保持相同输出与失败的前提下比较生产包或代表性吞吐。

使用方式

按工作流顺序执行：建立有效契约、写出边界契约、加载匹配参考、实现最小完整模式、验证可观察行为。完成门槛包括：已安装 Zod 4 的导入与声明支持所有使用的 API；不可信输入在进入可信领域或查询缓存数据前只解析一次；强制转换与回退行为用歧义输入测试；对象组合保留显式键策略与细化；错误在消费端投影前保留 code 与 path 且排除敏感输入；编解码器仅用于真实往返，并把可恢复的转换失败报告为 issue；JSON Schema 需说明描述的是被接受输入还是解析输出；Classic、Mini、compile 或 validate 的选择应基于实测需求而非新奇。

适用场景

适合处理 Zod 4 schema 的边界解析、对象键策略、联合与枚举、结构化错误、类型输入/输出、form 转换、coercion、transforms、defaults、codecs、异步 schema，以及元数据、注册表、JSON Schema、文档与代码生成等任务。

限制

该技能仅面向 Zod 4，资料未提供其他版本的兼容说明；资料未提供收费、价格或平台信息。