用途
该技能提供一套可用于生产环境的 AI 模型集成模式，重点解决调用 LLM 接口时的稳定性与结构化输出问题。资料中明确针对 Google Gemini，适用于把 AI/LLM API 集成进应用、需要在模型过载或限流时自动回退、希望获得类型安全的结构化响应，以及构建对生成可靠性有要求的功能的场景。它也支持把 Zod schema 转换为 LLM 兼容格式，并实现 fast/smart 不同模型层级的生成模式。
主要能力
- 模型级联与自动回退：按 lite → flash → pro 顺序尝试模型。
- 结构化输出：将 Zod schema 转换为 Gemini 格式，配合 responseMimeType 与 responseSchema 使用。
- 重试逻辑：对 503/429 错误自动重试。
- Token 追踪：记录并输出用量指标用于监控。
- 超时支持：通过 timeoutMs 避免请求挂起。
- 错误分类：区分可重试错误与致命错误，如 overloaded、rate limited、authentication failed、invalid request、unknown error 等。
使用方式
资料给出的实现分两步。第一步创建 lib/gemini-client.ts，导入 @google/generative-ai 与 zod，读取环境变量 GEMINI_API_KEY，定义 MODEL_CASCADE 为 gemini-2.5-flash-lite、gemini-2.5-flash、gemini-2.5-pro，并实现 isValidModel、isRetryableError、getErrorType、convertToGeminiSchema 以及核心函数 generateWithFallback。第二步创建 lib/schemas.ts 定义 Zod schema，资料提供了 topicQuoteSchema、topicGenerationSchema、suggestedQuestionsSchema、chatResponseSchema、summaryTakeawaySchema、summaryTakeawaysSchema 等示例。生成时调用 generateWithFallback(prompt, config)，可通过 preferredModel 指定首选模型、zodSchema 指定结构化 schema、timeoutMs 设置超时；preferredModel 会被放在级联首位，其余模型依次回退。
示例与高级模式
资料包含多个使用示例：生成结构化选题（preferredModel 用 gemini-2.5-flash-lite，timeoutMs 60000）、带时间戳引用的 AI 问答（chatResponseSchema，preferredModel 用 gemini-2.5-flash，timeoutMs 30000）、smart 与 fast 模式映射不同模型与超时、Next.js API 路由集成并返回用户友好的错误响应，以及生成后用 Zod 再次校验摘要要点。高级模式部分还给出流式输出、自定义错误恢复重试、以及提示词模板 PROMPTS 的写法。
环境与最佳实践
环境变量在 .env.local 中设置 GEMINI_API_KEY。资料提到可从 https://makersuite.google.com/app/apikey 获取 API key。最佳实践包括：始终用 Zod schema 保证类型安全、设置超时、从 lite 模型开始并可回退到更强模型、记录 token 用量、优雅处理错误、提供 fast 与 quality 模式选择、对关键字段再做校验。常见陷阱包括：不处理 JSON 解析错误、超时设置过于激进、忘记 API key、未测试级联回退、schema 过于复杂、缺少错误日志、未指定 preferredModel。
限制
资料仅明确针对 Google Gemini 与 @google/generative-ai、Zod 环境，未提供其他模型供应商的适配说明；未提及收费、价格、性能指标或效果数据；流式输出在资料中标注为未来增强项。