Mastra AI 项目中 JSON Schema 引用策略的技术解析

在 Mastra AI 项目的 JavaScript 客户端开发中，当使用 Zod 库定义数据结构并转换为 JSON Schema 时，开发者可能会遇到一个关键的技术问题：某些 AI 服务提供商（如 Google Vertex AI）无法正确处理包含 $ref 引用的 JSON Schema。

问题背景

Zod 是一个流行的 TypeScript 模式验证库，它允许开发者定义数据结构并进行验证。zod-to-json-schema 是将 Zod 模式转换为 JSON Schema 的工具。默认情况下，当 Schema 中存在重复使用的结构时，转换工具会生成带有 $ref 引用的 JSON Schema，这是一种常见的优化手段，可以减少 Schema 的体积。

然而，在 AI 服务集成场景中，许多服务提供商的后端实现并不支持这种引用机制。当 Mastra 客户端尝试向 Google Vertex AI 等服务发送包含 $ref 的 Schema 时，会收到"请求包含无效参数"的错误响应。

技术解决方案

解决这个问题的直接方法是在调用 zodToJsonSchema 时显式设置 $refStrategy: 'none' 选项。这个选项会强制转换工具展开所有引用，生成一个完全展开的、不包含任何引用的 JSON Schema。

从技术实现角度看，Mastra 客户端应该在内部自动应用这个选项，而不是依赖每个开发者手动添加。这种做法有几个优势：

1. 兼容性保障：确保生成的 Schema 能在所有支持的 AI 服务提供商上正常工作
2. 开发者体验：减少开发者需要关注的底层细节
3. 一致性：所有生成的 Schema 保持相同的行为模式

实现建议

在 Mastra 客户端的代码实现中，应该对 zodToJsonSchema 的调用进行封装，自动添加 $refStrategy: 'none' 选项。这种封装可以放在客户端的工具函数层，确保所有通过客户端生成的 Schema 都遵循相同的引用策略。

这种设计决策与业界其他类似项目（如 Vercel 的 AI SDK）的做法一致，这些项目也推荐使用无引用的 Schema 来确保最大兼容性。

最佳实践

对于 Mastra 项目的开发者，在使用 Zod 定义输出 Schema 时，可以遵循以下实践：

1. 充分利用 Zod 的类型复用能力定义数据结构
2. 不需要担心重复结构导致的 Schema 体积增大，客户端会自动优化
3. 当遇到 Schema 相关错误时，首先检查是否意外传入了包含引用的 Schema

这种自动处理引用策略的方式，既保留了 Zod 的类型安全优势，又避免了与特定服务提供商的兼容性问题，是 AI 服务集成中的一个实用解决方案。