Schema 兼容层
Schema Compatibility Layer
解决 Zod 跨版本兼容和 JSON Schema 到 Zod 的动态转换，确保结构化输出的类型安全
子问题
1.Zod v3/v4 跨版本兼容
2.JSON Schema 到 Zod 动态转换
3.结构化输出类型推断
4.MCP 工具 schema 适配
5.schema 递归变换时的版本一致性保持
6.v3 lazy shape（函数式）与 v4 静态 shape 的统一访问
7.多目标格式转换（JSON Schema / Gemini Schema / Zod 三向）
各项目的解法1 solutions
Signals
横向对比
| 维度 | Stagehand |
|---|---|
| 版本检测 | _zod 属性存在性检测，单属性区分 v3/v4 |
| 转换策略 | v3 走 zod-to-json-schema 库，v4 走原生 z.toJSONSchema() |
| 重建一致性 | getZFactory 返回同版本工厂，递归重建不混版本 |
| 类型推断 | InferStagehandSchema 条件类型分发，编译期正确推断 |
| 内部访问 | 15+ 双路径访问器覆盖 object/array/union/enum/pipe 等全类型 |
| 多格式输出 | 同时支持 JSON Schema、Gemini Schema、Zod 三种格式互转 |
最佳实践
1.提供统一的 toJsonSchema 抽象屏蔽版本差异
2.用 peerDependencies 宽版本范围声明让用户自选版本
3.getZFactory 模式确保 schema 重建不混用版本
4.TYPE_NAME_MAP 统一两套类型命名体系