developing-genkit-js

用途

这是一个用于 AI 编程助手（Agent Skill）的 Genkit JS 开发技能定义，来源为 firebase/agent-skills。它用于指导开发者使用 Genkit 在 Node.js/TypeScript 环境中开发 AI 驱动的应用程序。当用户询问 Genkit、JavaScript/TypeScript 中的 AI 智能体（agents）、flows 或工具（tools）相关内容时适用。

前置条件

需要确保 genkit CLI 可用。运行 genkit --version 验证，要求最低 CLI 版本为 1.29.0。若未找到或版本较旧（1.x < 1.29.0），需安装或升级：npm install -g genkit-cli@^1.29.0。若是在新代码库中设置 Genkit，需遵循 Setup Guide。

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

可参见 Common Errors 了解已弃用 API 列表（例如 configureGenkit、response.text()、defineFlow import）及其 v1.x 替代方案。始终使用 Genkit CLI 或提供的参考来验证信息。

错误排查协议

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

强制第一步：阅读 Common Errors。
识别错误是否匹配已知模式。
应用文档给出的解决方案。
仅当在 common-errors.md 中未找到时，才查阅其他来源（如 genkit docs:search）。

禁止：基于假设或内部知识尝试修复；因为自认为知道修复方法而跳过阅读 common-errors.md；依赖 1.0 之前的 Genkit 模式。此协议对错误处理不可协商。

开发工作流

选择 Provider：Genkit 与 provider 无关（Google AI、OpenAI、Anthropic、Ollama 等）。若用户未指定 provider，默认使用 Google AI。若用户询问其他 provider，使用 genkit docs:search "plugins" 查找相关文档。
检测框架：检查 package.json 以识别运行时（Next.js、Firebase、Express）。查找 @genkit-ai/next、@genkit-ai/firebase 或 @genkit-ai/google-cloud。根据具体框架的模式调整实现。
遵循最佳实践：参见 Best Practices 了解项目结构、schema 定义和工具设计的指导。
保持最小化：仅指定与默认值不同的选项。不确定时查阅 docs/source。
确保正确性：修改后运行类型检查（如 npx tsc --noEmit）。若类型检查失败，在搜索源代码前先查阅 Common Errors。
处理错误：遇到任何错误时，第一步阅读 Common Errors，将错误匹配到文档模式，先应用文档给出的修复方案再尝试其他替代。

查找文档

使用 Genkit CLI 查找权威文档：

搜索主题：genkit docs:search <query>，例如 genkit docs:search "streaming"
列出所有文档：genkit docs:list
阅读指南：genkit docs:read <path>，例如 genkit docs:read js/flows.md

CLI 用法

genkit CLI 是开发与文档查阅的主要工具。参见 CLI Reference 了解常见任务、工作流和命令用法。使用 genkit --help 查看完整命令列表。

参考

Best Practices：schema 定义、flow 设计和结构的推荐模式。
Docs & CLI Reference：文档搜索、CLI 任务和工作流。
Common Errors：关键“坑点”、迁移指南和故障排查。
Setup Guide：新项目的手动设置说明。
Examples：最小可复现示例（基础生成、多模态、思考模式）。

适用场景与限制

适用于用户使用 Genkit 在 Node.js/TypeScript 中构建 AI 应用、询问 Genkit 智能体/flows/tools 的场景。限制：本技能资料未提供具体收费、价格、支持平台范围或效果指标；使用前需满足 CLI 版本 1.29.0 的要求，且强调必须依赖 CLI 文档而非内部知识。