Genkit JS

前提条件

确保 genkit CLI 可用。

• 运行 genkit --version 进行验证。所需的最低 CLI 版本：1.29.0
• 如果未找到或存在较旧版本（1.x < 1.29.0），请安装/升级它：npm install -g genkit-cli@^1.29.0。

新项目：如果您要在新的代码库中设置 Genkit，请遵循 设置指南。

Hello World

import { z, genkit } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';

// 使用 Google AI 插件初始化 Genkit
const ai = genkit({
  plugins: [googleAI()],
});

export const myFlow = ai.defineFlow({
  name: 'myFlow',
  inputSchema: z.string().default('AI'),
  outputSchema: z.string(),
}, async (subject) => {
  const response = await ai.generate({
    model: googleAI.model('gemini-2.5-flash'),
    prompt: `讲一个关于 ${subject} 的笑话`,
  });
  return response.text;
});

关键：不要依赖内部知识

Genkit 最近经历了一次重大的破坏性 API 变更。您的知识已经过时。您必须查阅文档。推荐：

genkit docs:read js/get-started.md
genkit docs:read js/flows.md

有关已弃用 API（例如 configureGenkit、response.text()、defineFlow 导入）及其 v1.x 替代方案的列表，请参阅 常见错误。

始终使用 Genkit CLI 或提供的参考资料验证信息。

错误排查协议

当您遇到任何与 Genkit 相关的错误（ValidationError、API 错误、类型错误、404 等）时：

1. 强制性第一步：阅读 常见错误
2. 识别错误是否与已知模式匹配
3. 应用已记录的解决方案
4. 仅当在 common-errors.md 中未找到时，才查阅其他来源（例如 genkit docs:search）

禁止事项：

• 基于假设或内部知识尝试修复
• “因为您认为自己知道修复方法”而跳过阅读 common-errors.md
• 依赖 1.0 之前 Genkit 的模式

此协议是错误处理的强制要求。

开发工作流

1. 选择提供商：Genkit 是提供商无关的（Google AI、OpenAI、Anthropic、Ollama 等）。
   • 如果用户未指定提供商，默认使用 Google AI。
   • 如果用户询问其他提供商，请使用 genkit docs:search "plugins" 查找相关文档。
2. 检测框架：检查 package.json 以识别运行时（Next.js、Firebase、Express）。
   • 查找 @genkit-ai/next、@genkit-ai/firebase 或 @genkit-ai/google-cloud。
   • 根据特定框架的模式调整实现。
3. 遵循最佳实践：
   • 有关项目结构、模式定义和工具设计的指导，请参阅 最佳实践。
   • 保持最小化：仅指定与默认值不同的选项。不确定时，请查阅文档/源代码。
4. 确保正确性：
   • 修改后运行类型检查（例如 npx tsc --noEmit）。
   • 如果类型检查失败，在查阅源代码之前，请先查阅 常见错误。
5. 处理错误：
   • 遇到任何错误时：首要操作是阅读 常见错误
   • 将错误与已记录的模式匹配
   • 在尝试替代方案之前，应用已记录的修复方法

查找文档

使用 Genkit CLI 查找权威文档：

1. 搜索主题：genkit docs:search <查询>
   • 示例：genkit docs:search "streaming"
2. 列出所有文档：genkit docs:list
3. 阅读指南：genkit docs:read <路径>
   • 示例：genkit docs:read js/flows.md

CLI 用法

genkit CLI 是您开发和文档编写的主要工具。

• 有关常见任务、工作流和命令用法的信息，请参阅 CLI 参考。
• 使用 genkit --help 获取完整命令列表。

参考资料

• 最佳实践：模式定义、流程设计和结构的推荐模式。
• 文档与 CLI 参考：文档搜索、CLI 任务和工作流。
• 常见错误：关键“注意事项”、迁移指南和故障排除。
• 设置指南：新项目的手动设置说明。
• 示例：最小可重现示例（基础生成、多模态、思考模式）。