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

// 使用 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-flash-latest'),
    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「因為你認為你知道解決方法」
• 依賴 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 <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 任務和工作流程。
• 常見錯誤：重要的「陷阱」、遷移指南和疑難排解。
• 設定指南：新專案的手動設定說明。
• 範例：最小可重現範例（基本生成、多模態、思考模式）。