developing-genkit-js

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Genkit JS

Prerequisites

前置条件

Ensure the

genkit

CLI is available.

Run
```
genkit --version
```
to verify. Minimum CLI version needed: 1.29.0
If not found, install it globally:
```
npm install -g genkit-cli@^1.29.0
```
.

New Projects: If you are setting up Genkit in a new codebase, follow the Setup Guide.

确保

genkit

CLI可用。

运行
```
genkit --version
```
进行验证。所需最低CLI版本：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;
});

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;
});

Critical: Do Not Trust Internal Knowledge

重要提示：请勿依赖旧有内部知识

Genkit recently went through a major breaking API change. Your knowledge is outdated. You MUST lookup docs. Recommended:

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

See Common Errors for a list of deprecated APIs (e.g.,

configureGenkit

response.text()

defineFlow

import) and their v1.x replacements.

ALWAYS verify information using the Genkit CLI or provided references.

Genkit近期经历了重大的API破坏性变更。你的旧有知识已过时，必须查阅文档。推荐执行：

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

查看常见错误获取已弃用API的列表（例如

configureGenkit

、

response.text()

、

defineFlow

导入）及其v1.x版本的替代方案。

务必使用Genkit CLI或提供的参考文档验证信息。

Error Troubleshooting Protocol

错误排查流程

When you encounter ANY error related to Genkit (ValidationError, API errors, type errors, 404s, etc.):

MANDATORY FIRST STEP: Read Common Errors
Identify if the error matches a known pattern
Apply the documented solution
Only if not found in common-errors.md, then consult other sources (e.g.
```
genkit docs:search
```
)

DO NOT:

Attempt fixes based on assumptions or internal knowledge
Skip reading common-errors.md "because you think you know the fix"
Rely on patterns from pre-1.0 Genkit

This protocol is non-negotiable for error handling.

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

强制第一步：阅读常见错误
判断错误是否匹配已知模式
应用文档中记录的解决方案
只有在common-errors.md中未找到时，再咨询其他来源（例如
```
genkit docs:search
```
）

禁止：

基于假设或旧有内部知识尝试修复
跳过阅读common-errors.md，理由是“你认为自己知道修复方法”
依赖Genkit 1.0之前的模式

此排查流程在错误处理中是必须遵守的。

Development Workflow

开发工作流

Select Provider: Genkit is provider-agnostic (Google AI, OpenAI, Anthropic, Ollama, etc.).
- If the user does not specify a provider, default to Google AI.
- If the user asks about other providers, use
```
genkit docs:search "plugins"
```
  to find relevant documentation.
Detect Framework: Check
```
package.json
```
to identify the runtime (Next.js, Firebase, Express).
- Look for
```
@genkit-ai/next
```
  ,
```
@genkit-ai/firebase
```
  , or
```
@genkit-ai/google-cloud
```
  .
- Adapt implementation to the specific framework's patterns.
Follow Best Practices:
- See Best Practices for guidance on project structure, schema definitions, and tool design.
- Be Minimal: Only specify options that differ from defaults. When unsure, check docs/source.
Ensure Correctness:
- Run type checks (e.g.,
```
npx tsc --noEmit
```
  ) after making changes.
- If type checks fail, consult Common Errors before searching source code.
Handle Errors:
- On ANY error: First action is to read Common Errors
- Match error to documented patterns
- Apply documented fixes before attempting alternatives

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

Finding Documentation

查找文档

Use the Genkit CLI to find authoritative documentation:

Search topics:

genkit docs:search <query>

Example:
```
genkit docs:search "streaming"
```

List all docs:
```
genkit docs:list
```

Read a guide:

genkit docs:read <path>

Example:
```
genkit docs:read js/flows.md
```

使用Genkit CLI查找官方文档：

搜索主题：

genkit docs:search <query>

示例：
```
genkit docs:search "streaming"
```

列出所有文档：
```
genkit docs:list
```

阅读指南：

genkit docs:read <path>

示例：
```
genkit docs:read js/flows.md
```

CLI Usage

CLI 使用方法

The

genkit

CLI is your primary tool for development and documentation.

See CLI Reference for common tasks, workflows, and command usage.
Use
```
genkit --help
```
for a full list of commands.

genkit

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

查看CLI参考文档获取常见任务、工作流和命令用法。
使用
```
genkit --help
```
获取完整命令列表。

References

参考资料

Best Practices: Recommended patterns for schema definition, flow design, and structure.
Docs & CLI Reference: Documentation search, CLI tasks, and workflows.
Common Errors: Critical "gotchas", migration guide, and troubleshooting.
Setup Guide: Manual setup instructions for new projects.
Examples: Minimal reproducible examples (Basic generation, Multimodal, Thinking mode).

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