developing-genkit-js

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';

// Initialize Genkit with the Google AI plugin
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: `Tell me a joke about ${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
• 依赖 Genkit 1.0 之前的模式

此错误处理流程不可妥协。

开发工作流

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 <query>
   • 示例：genkit docs:search "streaming"
2. 列出所有文档：genkit docs:list
3. 阅读指南：genkit docs:read <path>
   • 示例：genkit docs:read js/flows.md

CLI 用法

genkit CLI 是开发和查阅文档的主要工具。

• 请参阅 CLI 参考，了解常见任务、工作流和命令用法。
• 使用 genkit --help 查看完整命令列表。

参考资料

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